path: root/upstream/archlinux/man3p/sigtimedwait.3p

'\" et
.TH SIGTIMEDWAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
sigtimedwait,
sigwaitinfo
\(em wait for queued signals
.SH SYNOPSIS
.LP
.nf
#include <signal.h>
.P
int sigtimedwait(const sigset_t *restrict \fIset\fP,
    siginfo_t *restrict \fIinfo\fP,
    const struct timespec *restrict \fItimeout\fP);
int sigwaitinfo(const sigset_t *restrict \fIset\fP,
    siginfo_t *restrict \fIinfo\fP);
.fi
.SH DESCRIPTION
The
\fIsigtimedwait\fR()
function shall be equivalent to
\fIsigwaitinfo\fR()
except that if none of the signals specified by
.IR set
are pending,
\fIsigtimedwait\fR()
shall wait for the time interval specified in the
.BR timespec
structure referenced by
.IR timeout .
If the
.BR timespec
structure pointed to by
.IR timeout
is zero-valued and if none of the signals specified by
.IR set
are pending, then
\fIsigtimedwait\fR()
shall return immediately with an error. If
.IR timeout
is the null pointer, the behavior is unspecified.
If the Monotonic Clock option is supported, the CLOCK_MONOTONIC clock
shall be used to measure the time interval specified by the
.IR timeout
argument.
.P
The
\fIsigwaitinfo\fR()
function selects the pending signal from the set specified by
.IR set .
Should any of 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. If no signal in
.IR set
is pending at the time of the call, the calling thread shall be
suspended until one or more signals in
.IR set
become pending or until it is interrupted by an unblocked, caught
signal.
.P
The
\fIsigwaitinfo\fR()
function shall be equivalent to the
\fIsigwait\fR()
function, except that the return value and the error reporting method
are different (see RETURN VALUE), and that if the
.IR info
argument is non-NULL, the selected signal number shall be stored in the
.IR si_signo
member, and the cause of the signal shall be stored in the
.IR si_code
member. If any value is queued to the selected signal, the first such
queued value shall be dequeued and, if the
.IR info
argument is non-NULL, the value shall be stored in the
.IR si_value
member of
.IR info .
The system resource used to queue the signal shall be released and
returned to the system for other use. If no value is queued, the
content of the
.IR si_value
member is undefined. If no further signals are queued for the selected
signal, the pending indication for that signal shall be reset.
.SH "RETURN VALUE"
Upon successful completion (that is, one of the signals specified by
.IR set
is pending or is generated)
\fIsigwaitinfo\fR()
and
\fIsigtimedwait\fR()
shall return the selected signal number. Otherwise, the function shall
return a value of \-1 and set
.IR errno
to indicate the error.
.SH ERRORS
The
\fIsigtimedwait\fR()
function shall fail if:
.TP
.BR EAGAIN
No signal specified by
.IR set
was generated within the specified timeout period.
.P
The
\fIsigtimedwait\fR()
and
\fIsigwaitinfo\fR()
functions may fail if:
.TP
.BR EINTR
The wait was interrupted by an unblocked, caught signal. It shall be
documented in system documentation whether this error causes these
functions to fail.
.br
.P
The
\fIsigtimedwait\fR()
function may also fail if:
.TP
.BR EINVAL
The
.IR timeout
argument specified a
.IR tv_nsec
value less than zero or greater than or equal to 1\|000 million.
.P
An implementation should only check for this error if no signal is
pending in
.IR set
and it is necessary to wait.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
The
\fIsigtimedwait\fR()
function times out and returns an
.BR [EAGAIN] 
error. Application developers should note that this is inconsistent
with other functions such as
\fIpthread_cond_timedwait\fR()
that return
.BR [ETIMEDOUT] .
.P
Note that in order to ensure that generated signals are queued and signal
values passed to
\fIsigqueue\fR()
are available in
.IR si_value ,
applications which use
\fIsigwaitinfo\fR()
or
\fIsigtimedwait\fR()
need to set the SA_SIGINFO flag for each signal in the set (see
.IR "Section 2.4" ", " "Signal Concepts").
This means setting each signal to be handled by a three-argument
signal-catching function, even if the handler will never be called.
It is not possible (portably) to set a signal handler to SIG_DFL while
setting the SA_SIGINFO flag, because assigning to the
.IR sa_handler
member of
.BR "struct sigaction"
instead of the
.IR sa_sigaction
member would result in undefined behavior, and SIG_DFL need not be
assignment-compatible with
.IR sa_sigaction .
Even if an assignment of SIG_DFL to
.IR sa_sigaction
is accepted by the compiler, the implementation need not treat this value
as special\(emit could just be taken as the address of a signal-catching
function.
.SH RATIONALE
Existing programming practice on realtime systems uses the ability to
pause waiting for a selected set of events and handle the first event
that occurs in-line instead of in a signal-handling function. This
allows applications to be written in an event-directed style similar to
a state machine. This style of programming is useful for largescale
transaction processing in which the overall throughput of an
application and the ability to clearly track states are more important
than the ability to minimize the response time of individual event
handling.
.P
It is possible to construct a signal-waiting macro function out of the
realtime signal function mechanism defined in this volume of POSIX.1\(hy2017. However, such a
macro has to include the definition of a generalized handler for all
signals to be waited on. A significant portion of the overhead of
handler processing can be avoided if the signal-waiting function is
provided by the kernel. This volume of POSIX.1\(hy2017 therefore provides two signal-waiting
functions\(emone that waits indefinitely and one with a timeout\(emas
part of the overall realtime signal function specification.
.P
The specification of a function with a timeout allows an application
to be written that can be broken out of a wait after a set period of
time if no event has occurred. It was argued that setting a timer
event before the wait and recognizing the timer event in the wait would
also implement the same functionality, but at a lower performance
level. Because of the performance degradation associated with the
user-level specification of a timer event and the subsequent
cancellation of that timer event after the wait completes for a valid
event, and the complexity associated with handling potential race
conditions associated with the user-level method, the separate
function has been included.
.P
Note that the semantics of the
\fIsigwaitinfo\fR()
function are nearly identical to that of the
\fIsigwait\fR()
function defined by this volume of POSIX.1\(hy2017. The only difference is that
\fIsigwaitinfo\fR()
returns the queued signal value in the
.IR value
argument. The return of the queued value is required so that
applications can differentiate between multiple events queued to the
same signal number.
.P
The two distinct functions are being maintained because some
implementations may choose to implement the POSIX Threads Extension functions and not
implement the queued signals extensions. Note, though, that
\fIsigwaitinfo\fR()
does not return the queued value if the
.IR value
argument is NULL, so the POSIX Threads Extension
\fIsigwait\fR()
function can be implemented as a macro on
\fIsigwaitinfo\fR().
.P
The
\fIsigtimedwait\fR()
function was separated from the
\fIsigwaitinfo\fR()
function to address concerns regarding the overloading of the
.IR timeout
pointer to indicate indefinite wait (no timeout), timed wait, and
immediate return, and concerns regarding consistency with other
functions where the conditional and timed waits were separate
functions from the pure blocking function. The semantics of
\fIsigtimedwait\fR()
are specified such that
\fIsigwaitinfo\fR()
could be implemented as a macro with a null pointer for
.IR timeout .
.P
The
.IR sigwait
functions provide a synchronous mechanism for threads to wait for
asynchronously-generated signals. One important question was how many
threads that are suspended in a call to a
\fIsigwait\fR()
function for a signal should return from the call when the signal is
sent. Four choices were considered:
.IP " 1." 4
Return an error for multiple simultaneous calls to
.IR sigwait
functions for the same signal.
.IP " 2." 4
One or more threads return.
.IP " 3." 4
All waiting threads return.
.IP " 4." 4
Exactly one thread returns.
.P
Prohibiting multiple calls to
\fIsigwait\fR()
for the same signal was felt to be overly restrictive. The ``one or
more'' behavior made implementation of conforming packages easy at the
expense of forcing POSIX threads clients to protect against multiple
simultaneous calls to
\fIsigwait\fR()
in application code in order to achieve predictable behavior. There
was concern that the ``all waiting threads'' behavior would result in
``signal broadcast storms'', consuming excessive CPU resources by
replicating the signals in the general case. Furthermore, no
convincing examples could be presented that delivery to all was either
simpler or more powerful than delivery to one.
.P
Thus, the consensus was that exactly one thread that was suspended in a
call to a
.IR sigwait
function for a signal should return when that signal occurs. This is
not an onerous restriction as:
.IP " *" 4
A multi-way signal wait can be built from the single-way wait.
.IP " *" 4
Signals should only be handled by application-level code, as library
routines cannot guess what the application wants to do with signals
generated for the entire process.
.IP " *" 4
Applications can thus arrange for a single thread to wait for any given
signal and call any needed routines upon its arrival.
.P
In an application that is using signals for interprocess communication,
signal processing is typically done in one place. Alternatively, if
the signal is being caught so that process cleanup can be done, the
signal handler thread can call separate process cleanup routines for
each portion of the application. Since the application main line
started each portion of the application, it is at the right abstraction
level to tell each portion of the application to clean up.
.P
Certainly, there exist programming styles where it is logical to
consider waiting for a single signal in multiple threads. A simple
\fIsigwait_multiple\fR()
routine can be constructed to achieve this goal. A possible
implementation would be to have each
\fIsigwait_multiple\fR()
caller registered as having expressed interest in a set of signals.
The caller then waits on a thread-specific condition variable. A
single server thread calls a
\fIsigwait\fR()
function on the union of all registered signals. When the
\fIsigwait\fR()
function returns, the appropriate state is set and condition variables
are broadcast. New
\fIsigwait_multiple\fR()
callers may cause the pending
\fIsigwait\fR()
call to be canceled and reissued in order to update the set of signals
being waited for.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "Section 2.4" ", " "Signal Concepts",
.IR "Section 2.8.1" ", " "Realtime Signals",
.IR "\fIpause\fR\^(\|)",
.IR "\fIpthread_sigmask\fR\^(\|)",
.IR "\fIsigaction\fR\^(\|)",
.IR "\fIsigpending\fR\^(\|)",
.IR "\fIsigsuspend\fR\^(\|)",
.IR "\fIsigwait\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<signal.h>\fP",
.IR "\fB<time.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 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 .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .