sigwait()
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 by all threads, including the one that will handle them, before this designated handler thread calls sigwait(). This design ensures simplicity by separating application threads into those that ignore signals and those that handle them. If you don't block signals, there's a race condition because a signal can be delivered just before the call is made, causing the call to block, which you might not want it to do.
However, 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. To avoid this situation, you could do the following:
- Install a signal handler that sets a flag.
- Block the signal.
- Check if the flag is set.
- Call sigwait().
Or, if portability isn't important, you could call SignalWaitinfoMask(), which blocks a specified set of signals and then waits.
It is recommended to have just one thread call sigwait() for a given signal. This means if multiple threads use this function, they must specify non-overlapping signals in set. Handling signals with just one thread is simpler and race-free, and you don't have to worry about whether you're using something that is unsafe in a signal handler. If your design requires that you have more than one thread use sigwait() for the same signal, be aware that only one of these threads (chosen arbitrarily) will return from this function with the signal's 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:
| Safety: | |
|---|---|
| Cancellation point | Yes |
| Signal handler | Yes |
| Thread | Yes |