sigwait(2) System Calls Manual sigwait(2)
NAME
sigwait(), sigwaitinfo(), sigtimedwait() - synchronously accept a signal
SYNOPSIS
DESCRIPTION
The function atomically selects and clears a pending signal from set and returns the signal number in the location pointed to by sig. If
none of the signals in set is pending at the time of the call, the calling thread will be suspended until one or more signals become pend-
ing or the thread is interrupted by an unblocked, caught signal. The signals in set should be blocked at the time of the call to Other-
wise, the behavior is undefined.
If there are multiple signals queued for the selected signal number, will return with the first queued signal and the remainder will remain
queued. If any of multiple pending signals in the range to is selected, the lowest numbered signal will be returned. The selection order
between realtime and nonrealtime signals, or between multiple pending nonrealtime signals, is unspecified.
If more than one thread in a process is in for the same signal, only one thread will return from with the signal number; which thread
returns is undefined.
has the same behavior as if the info parameter is If the info parameter is not has the same behavior as except that the selected signal
number is returned in the si_signo field of the info parameter and the cause of the signal is returned in the si_code field. If any value
is queued to the selected signal, the first such queued value will be dequeued and stored in the si_value member of info and the system
resource used to queue the signal will be released and made available to queue other signals. If no value is queued, the contents of the
si_value member is undefined. If no further signals are queued for the selected signal, the pending indication for that signal will be
reset.
has the same behavior as except that will only wait for the time interval specified by the timeout parameter if none of the signals speci-
fied by set are pending at the time of the call. If the timeout parameter specifies a zero-valued time interval, then will return immedi-
ately with an error if no signals in set are pending at the time of the call. If the timeout parameter is the behavior is undefined.
APPLICATION USAGE
For a given signal number, the sigwait family of routines should not be used in conjunction with or any other functions which change signal
action. If they are used together, the results are undefined.
Threads Considerations
The sigwait family of routines enable a thread to synchronously wait for signals. This makes the sigwait routines ideal for handling sig-
nals in a multithreaded process. The suggested method for signal handling in a multithreaded process is to have all threads block the sig-
nals of interest and dedicate one thread to call a sigwait function to wait for the signals. When a signal causes a sigwait function to
return, the code to handle the signal can be placed immediately after the return from the sigwait routine. After the signal is handled, a
sigwait function can again be called to wait for another signal.
In order to ensure that the dedicated thread handles the signal, it is essential that all threads, including the thread issuing the sigwait
call, block the signals of interest. Otherwise, the signal could be delivered to a thread other than the dedicated signal handling thread.
This could result in the default action being carried out for the signal. It is important that the thread issuing the sigwait call also
block the signal. This will prevent signals from carrying out the default signal action while the dedicated signal handling thread is
between calls to a sigwait function.
RETURN VALUE
Upon successful completion, stores the signal number selected in the location pointed to by sig and returns with a value of (zero). Other-
wise, it returns an error number to indicate the error. The variable is NOT set if an error occurs.
Upon successful completion, and will return the selected signal number. Otherwise a value of -1 is returned and is set to indicate the
error.
ERRORS
If any of the following conditions occur, the sigwait family of routines will return the following error number:
[EAGAIN] was called and no signal in the set parameter was delivered within the time interval specified by the timeout parame-
ter.
If any of the following conditions occur and the condition is detected, the sigwait family of routines will fail and return the following
error number:
[EINVAL] set contains an invalid or unsupported signal number.
[EINVAL] was called and the timeout parameter specified a tv_nsec value less than zero or greater than or equal to 1000 mil-
lion, or a tv_sec value less than zero or greater than or equal to 2147483648 (that is, a value too large to be rep-
resented as a signed 32-bit integer).
[EINTR] The wait was interrupted by an unblocked, caught signal.
[EFAULT] At least one of the set, sig, info, or timeout parameters references an illegal address.
AUTHOR
sigwaitinfo() and sigtimedwait() were derived from the IEEE POSIX P1003.1b standard.
sigwait() was derived from the IEEE POSIX P1003.1c standard.
SEE ALSO
pause(2), sigaction(2), sigpending(2), sigsuspend(2), pthread_sigmask(3T), signal(5).
STANDARDS CONFORMANCE
sigwait(2)