sigwait(2)

sigwait -- wait for a signal to be posted

Synopsis

   #include <signal.h>

   int sigwait(sigset_t *set);

Description

This function atomically chooses and clears a pending signal from set and returns the number of the signal chosen. If no signal in set is pending at the time of the call, the calling function shall be suspended until one or more signals become pending. This suspension is indefinite in extent.

The set of signals remains blocked after return.

An application should not mix use of sigwait and sigaction for a given signal number because the results may be unpredictable.

Return values

Upon successful completion, sigwait returns the signal number of the received signal. Otherwise, a negative value is returned and errno is set to indicate the error.

Errors

If any of the following conditions occurs, sigwait returns a negative value and sets errno to the corresponding value:

EINVAL: set contains an invalid or unsupported signal number
EFAULT: set points to an illegal address.

References

_lwp_kill(2), kill(2), sigaction(2), signal(5), sigpending(2), sigsend(2), sigsuspend(2), thread(3thread)

Notices

Considerations for threads programming

The sigwait system call allows a multithreaded application to use a synchronous organization for signal handling.

Usage

The semantics of sigwait make it ideal for a thread that will be dedicated to handling certain signal types for a process. The functionality that might have been placed in a separate handler function could be placed after the return from sigwait to be executed once a signal arrives. Once handling is complete, the thread could call sigwait again to block itself until arrival of the next signal.

To be sure that signals are delivered to the intended thread:

All threads in the process (including the thread that will be using sigwait) should mask the relevant signal types.
Only the intended thread should use sigwait.
No thread should define a handler function.

See signal(5) for further details.

Code to handle a signal type on return from sigwait is not considered a handler in the containing process' disposition for that signal type. It is important that signal types handled by a thread using sigwait(2) be included in the signal mask of every thread, otherwise, the default response for the process will be triggered. Even the thread calling sigwait should mask that signal type because a signal of that type may arrive while the thread is between calls to sigwait(2).

While one thread is blocked, siblings might still be executing.