mirror of https://github.com/mkerrisk/man-pages
107 lines
4.2 KiB
Plaintext
107 lines
4.2 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "SIGWAIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" sigwait
|
|
.SH NAME
|
|
sigwait \- wait for queued signals
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <signal.h>
|
|
.br
|
|
.sp
|
|
int sigwait(const sigset_t *restrict\fP \fIset\fP\fB, int *restrict\fP
|
|
\fIsig\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIsigwait\fP() function shall select a pending signal from \fIset\fP,
|
|
atomically clear it from the system's set of
|
|
pending signals, and return that signal number in the location referenced
|
|
by \fIsig\fP. If prior to the call to \fIsigwait\fP()
|
|
there are multiple pending instances of a single signal number, it
|
|
is implementation-defined whether upon successful return there
|
|
are any remaining pending signals for that signal number. \ If the
|
|
implementation supports queued signals and there are
|
|
multiple signals queued for the signal number selected, the first
|
|
such queued signal shall cause a return from \fIsigwait\fP() and
|
|
the remainder shall remain queued. If no signal in \fIset\fP is
|
|
pending at the time of the call, the thread shall be suspended until
|
|
one or more becomes pending. The signals defined by \fIset\fP
|
|
shall have been blocked at the time of the call to \fIsigwait\fP();
|
|
otherwise, the behavior is undefined. The effect of
|
|
\fIsigwait\fP() on the signal actions for the signals in \fIset\fP
|
|
is unspecified.
|
|
.LP
|
|
If more than one thread is using \fIsigwait\fP() to wait for the same
|
|
signal, no more than one of these threads shall return
|
|
from \fIsigwait\fP() with the signal number. Which thread returns
|
|
from \fIsigwait\fP() if more than a single thread is waiting is
|
|
unspecified.
|
|
.LP
|
|
Should any of the multiple pending signals in the range SIGRTMIN to
|
|
SIGRTMAX be selected, it shall be the lowest numbered one. The
|
|
selection order between realtime and non-realtime signals, or between
|
|
multiple pending non-realtime signals, is unspecified.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fIsigwait\fP() shall store the signal
|
|
number of the received signal at the location referenced by
|
|
\fIsig\fP and return zero. Otherwise, an error number shall be returned
|
|
to indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIsigwait\fP() function may fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
The \fIset\fP argument contains an invalid or unsupported signal number.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
To provide a convenient way for a thread to wait for a signal, this
|
|
volume of IEEE\ Std\ 1003.1-2001 provides the
|
|
\fIsigwait\fP() function. For most cases where a thread has to wait
|
|
for a signal, the \fIsigwait\fP() function should be quite
|
|
convenient, efficient, and adequate.
|
|
.LP
|
|
However, requests were made for a lower-level primitive than \fIsigwait\fP()
|
|
and for semaphores that could be used by threads.
|
|
After some consideration, threads were allowed to use semaphores and
|
|
\fIsem_post\fP() was
|
|
defined to be async-signal and async-cancel-safe.
|
|
.LP
|
|
In summary, when it is necessary for code run in response to an asynchronous
|
|
signal to notify a thread, \fIsigwait\fP() should
|
|
be used to handle the signal. Alternatively, if the implementation
|
|
provides semaphores, they also can be used, either following
|
|
\fIsigwait\fP() or from within a signal handling routine previously
|
|
registered with \fIsigaction\fP().
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fISignal Concepts\fP , \fIRealtime
|
|
Signals\fP , \fIpause\fP() , \fIpthread_sigmask\fP() , \fIsigaction\fP()
|
|
, \fIsigpending\fP() , \fIsigsuspend\fP() , \fIsigwaitinfo\fP() ,
|
|
the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, \fI<signal.h>\fP, \fI<time.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|