sigwait()

Updated: April 19, 2023

Wait for a pending signal

Synopsis:

#include <signal.h>

int sigwait( const sigset_t *set, 
             int *sig );

Arguments:

set
A pointer to a sigset_t object that specifies the signals you want to wait for.
sig
A pointer to a location where the function can store the signal that it cleared.

Library:

libc

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

Description:

The sigwait() function selects a pending signal from set, atomically clears it from the set of pending signals in the system, and returns that signal number in sig. If there are multiple signals queued for the signal number selected, the first signal causes a return from sigwait() and the rest remain queued. If no signal in set is pending at the time of the call, the thread is suspended until one or more becomes pending.

The signals defined by set should be blocked before you call sigwait(). 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 sigwait().

or, if portability isn't important, you could call SignalWaitinfoMask(), which blocks a specified set of signals and then waits.

The effect of sigwait() on the signal actions for the signals in set is undefined.

If more than one thread is using sigwait() to wait for the same signal, only one of the threads (chosen arbitrarily) returns from sigwait() with the signal number.

Returns:

0
Success (that is, one of the signals specified by set is pending or has been generated).
EFAULT
A fault occurred while accessing the provided buffers.
EINTR
The sigwait() function was interrupted by a signal.
EINVAL
The set argument contains an invalid or unsupported signal number.

Classification:

POSIX 1003.1

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