sigwait(3pthread)

sigwait -- wait for a signal to be posted

Synopsis

   #include <signal.h>
   
   int sigwait(sigset_t *set);
   

   cc [options] -Kthread file
   

   #include <signal.h>
   #define _XOPEN_SOURCE 500
   #define _POSIX_C_SOURCE 199506
   

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

Description

There are two versions of the sigwait function in this release.

Non-POSIX-compliant version

This version of the 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.

POSIX compliant version

To access the POSIX version of sigwait you must define the value of _XOPEN_SOURCE to be greater than or equal to 500, and the value of _POSIX_C_SOURCE to be greater than or equal to 199506. You must also specify the Kthread library as an option to the cc command.

The POSIX compliant version of sigwait, shown in the second synopsis shown above, selects a pending signal from set, atomically clears it from the system's set of pending signals, and returns that signal number in the location referenced by sig. 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 shall have been blocked at the time of the call to sigwait; otherwise the behavior is undefined.

If more than one thread is using sigwait to wait for the same signal, only one of these threads will return from sigwait with the signal number.

Return values

Upon successful completion, the non-POSIX-compliant version of sigwait returns the signal number of the received signal. Otherwise, it returns a negative value and errno is set to indicate the error.

Upon successful completion, the POSIX compliant version of sigwait stores the signal number of the received signal at the location referenced by sig and returns zero. Otherwise, an error number is returned to indicate the error.

Diagnostics

The non-POSIX-compliant version of sigwait returns a negative value and sets errno to the following values if the corresponding conditions are detected.:

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

The POSIX compliant version of sigwait returns the following value if the corresponding condition is detected:

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

Standards compliance

The Single UNIX Specification, Version 2; The Open Group.

References

Intro(3thread), Intro(3pthread), _lwp_kill(2), kill(2), pause(2), pthread_sigmask(3pthread), sigaction(2), signal(5), sigpending(2), sigsend(2), sigsuspend(2), thr_sigsetmask(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.