sigtimedwait()

Wait for a signal or a timeout

Synopsis:

#include <signal.h>

int sigtimedwait( const sigset_t *set, 
                  siginfo_t *info, 
                  const struct timespec *timeout );

Arguments:

set
A set of signals from which the function selects a pending signal.
info
NULL, or a pointer to a siginfo_t structure where the function can store information about the signal.
timeout
NULL, or a pointer to a timespec structure that specifies the maximum time to wait for a pending signal.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The sigtimedwait() function selects a pending signal from set, atomically clears it from the set of pending signals in the process, and returns that signal number.

The signals defined by set should be blocked before you call sigtimedwait(). If you don't block them, there's a race condition in that a signal can be delivered just before the call is made, causing the call to block, which you might not want it to do. Note that simply blocking a signal is insufficient, as there's still a race condition where the signal is delivered just before the call to block it is handled. You could do the following:

  1. Install a signal handler that sets a flag.
  2. Block the signal.
  3. Check if the flag is set.
  4. Call sigtimedwait().

If the info argument isn't NULL, sigtimedwait() stores the selected signal in the si_signo member of info, and the cause of the signal in the si_code member.

If any value is queued to the selected signal, the first queued value is dequeued and, if the info argument is non-NULL, the value is stored in the si_value member of info. The system resources used to queue the signal are released and made available to queue other signals. If no value is queued, the content of the si_value member is undefined.

If no further signals are queued for the selected signal, the pending indication for that signal is reset.

If none of the signals specified by set are pending, sigtimedwait() waits for the time interval specified by the timespec structure timeout. The CLOCK_MONOTONIC clock is used to measure the time interval.

If timeout is zero and if none of the signals specified by set are pending, then sigtimedwait() returns immediately with an error. If timeout is NULL, sigtimedwait() behaves the same as sigwaitinfo().

Returns:

The selected signal number, or -1 if an error occurred (errno is set).

Errors:

EAGAIN
The timeout expired before a signal specified in set was generated, or all kernel timers are in use.
EFAULT
A fault occurred while accessing the provided buffers.
EINTR
The wait was interrupted by an unblocked, caught signal.
EINVAL
The timeout argument specified a tv_nsec value less than zero or greater than or equal to 1000 million or set contains an invalid or unsupported signal number.

Classification:

POSIX 1003.1 RTS

Safety:
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes

See also:

pause(), pthread_sigmask(), sigaction(), siginfo_t, SignalWaitinfo(), sigpending(), sigsuspend(), sigwaitinfo(), timespec