HP-UX Reference (11i v1 05/09) - 2 System Calls (vol 5)

s
sigwait(2) sigwait(2)
NAME
sigwait(), sigwaitinfo(), sigtimedwait() - synchronously accept a signal
SYNOPSIS
#include <signal.h>
int sigwait(const sigset_t *set, int *sig);
int sigwaitinfo(const sigset_t *set, siginfo_t *info);
int sigtimedwait(const sigset_t *set, siginfo_t *info,
const struct timespec *timeout);
DESCRIPTION
The sigwait() 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 pending or the thread is interrupted by
an unblocked, caught signal. The signals in set should be blocked at the time of the call to
sigwait().
Otherwise, the behavior is undefined.
If there are multiple signals queued for the selected signal number,
sigwait() will return with the first
queued signal and the remainder will remain queued. If any of multiple pending signals in the range
SIGRTMIN to SIGRTMAX 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 sigwait() for the same signal, only one thread will return
from sigwait() with the signal number; which thread returns is undefined.
sigwaitinfo() has the same behavior as
sigwait() if the info parameter is NULL. If the info
parameter is not
NULL, sigwaitinfo()
has the same behavior as sigwait(), 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 indica-
tion for that signal will be reset.
sigtimedwait() has the same behavior as
sigwaitinfo() except that sigtimedwait() will
only wait for the time interval specified by the timeout parameter if none of the signals specified by set are
pending at the time of the call. If the timeout parameter specifies a zero-valued time interval, then
sigtimedwait() will return immediately with an error if no signals in set are pending at the time of
the call. If the timeout parameter is
NULL, the behavior is undefined.
APPLICATION USAGE
For a given signal number, the sigwait family of routines should not be used in conjunction with
sigac-
tion()
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 signals in a multithreaded process. The suggested method for signal handling in
a multithreaded process is to have all threads block the signals 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 han-
dle the signal can be placed immediately after the return from the sigwait routine. After the signal is han-
dled, 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 car-
ried 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, sigwait() stores the signal number selected in the location pointed to by
sig and returns with a value of 0 (zero). Otherwise, it returns an error number to indicate the error. The
errno variable is NOT set if an error occurs.
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 2−−395