SIGTIMEDWAIT(P) SIGTIMEDWAIT(P)
NAME
sigtimedwait, sigwaitinfo - wait for queued signals (REALTIME)
SYNOPSIS
#include <signal.h>
int sigtimedwait(const sigset_t *restrict set,
siginfo_t *restrict info,
const struct timespec *restrict timeout);
int sigwaitinfo(const sigset_t *restrict set,
siginfo_t *restrict info);
DESCRIPTION
The sigtimedwait() function shall be equivalent to sigwaitinfo() except that if none of
the signals specified by set are pending, sigtimedwait() shall wait for the time interval
specified in the timespec structure referenced by timeout. If the timespec structure
pointed to by timeout is zero-valued and if none of the signals specified by set are pend-
ing, then sigtimedwait() shall return immediately with an error. If 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 timeout
argument.
The sigwaitinfo() function selects the pending signal from the set specified by 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
set is pending at the time of the call, the calling thread shall be suspended until one or
more signals in set become pending or until it is interrupted by an unblocked, caught sig-
nal.
The sigwaitinfo() function shall be equivalent to the sigwait() function if the info argu-
ment is NULL. If the info argument is non-NULL, the sigwaitinfo() function shall be equiv-
alent to sigwait(), except that the selected signal number shall be stored in the si_signo
member, and the cause of the signal shall be stored in the si_code member. If any value is
queued to the selected signal, the first such queued value shall be dequeued and, if the
info argument is non-NULL, the value shall be stored in the si_value member of 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 si_value member is undefined. If no
further signals are queued for the selected signal, the pending indication for that signal
shall be reset.
RETURN VALUE
Upon successful completion (that is, one of the signals specified by set is pending or is
generated) sigwaitinfo() and sigtimedwait() shall return the selected signal number. Oth-
erwise, the function shall return a value of -1 and set errno to indicate the error.
ERRORS
The sigtimedwait() function shall fail if:
EAGAIN No signal specified by set was generated within the specified timeout period.
The sigtimedwait() and sigwaitinfo() functions may fail if:
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.
The sigtimedwait() function may also fail if:
EINVAL The timeout argument specified a tv_nsec value less than zero or greater than or
equal to 1000 million.
An implementation only checks for this error if no signal is pending in set and it is nec-
essary to wait.
The following sections are informative.
EXAMPLES
None.
APPLICATION USAGE
The sigtimedwait() function times out and returns an [EAGAIN] error. Application writers
should note that this is inconsistent with other functions such as pthread_cond_timed-
wait() that return [ETIMEDOUT].
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 sig-
nal-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 individ-
ual event handling.
It is possible to construct a signal-waiting macro function out of the realtime signal
function mechanism defined in this volume of IEEE Std 1003.1-2001. 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 IEEE Std 1003.1-2001 therefore
provides two signal-waiting functions-one that waits indefinitely and one with a timeout-
as part of the overall realtime signal function specification.
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.
Note that the semantics of the sigwaitinfo() function are nearly identical to that of the
sigwait() function defined by this volume of IEEE Std 1003.1-2001. The only difference is
that sigwaitinfo() returns the queued signal value in the value argument. The return of
the queued value is required so that applications can differentiate between multiple
events queued to the same signal number.
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 sigwaitinfo() does not return the queued value if the value
argument is NULL, so the POSIX Threads Extension sigwait() function can be implemented as
a macro on sigwaitinfo().
The sigtimedwait() function was separated from the sigwaitinfo() function to address con-
cerns regarding the overloading of the 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 sigtimedwait() are specified such that sigwaitinfo()
could be implemented as a macro with a NULL pointer for timeout.
The sigwait functions provide a synchronous mechanism for threads to wait for asyn-
chronously-generated signals. One important question was how many threads that are sus-
pended in a call to a sigwait() function for a signal should return from the call when the
signal is sent. Four choices were considered:
1. Return an error for multiple simultaneous calls to sigwait functions for the same sig-
nal.
2. One or more threads return.
3. All waiting threads return.
4. Exactly one thread returns.
Prohibiting multiple calls to sigwait() for the same signal was felt to be overly restric-
tive. 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
sigwait() in application code in order to achieve predictable behavior. There was concern
that the "all waiting threads" behavior would result in "signal broadcast storms", consum-
ing 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.
Thus, the consensus was that exactly one thread that was suspended in a call to a sigwait
function for a signal should return when that signal occurs. This is not an onerous
restriction as:
* A multi-way signal wait can be built from the single-way wait.
* 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.
* Applications can thus arrange for a single thread to wait for any given signal and call
any needed routines upon its arrival.
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 pro-
cess cleanup can be done, the signal handler thread can call separate process cleanup rou-
tines 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.
Certainly, there exist programming styles where it is logical to consider waiting for a
single signal in multiple threads. A simple sigwait_multiple() routine can be constructed
to achieve this goal. A possible implementation would be to have each sigwait_multiple()
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 sigwait() function
on the union of all registered signals. When the sigwait() function returns, the appropri-
ate state is set and condition variables are broadcast. New sigwait_multiple() callers may
cause the pending sigwait() call to be canceled and reissued in order to update the set of
signals being waited for.
FUTURE DIRECTIONS
None.
SEE ALSO
Realtime Signals , pause() , pthread_sigmask() , sigaction() , sigpending() , sigsuspend()
, sigwait() , the Base Definitions volume of IEEE Std 1003.1-2001, <signal.h>, <time.h>
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 orig-
inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .
POSIX 2003 SIGTIMEDWAIT(P)
|