# sigtimedwait

## 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.
    


## NAME



           sigtimedwait, sigwaitinfo — wait for queued signals
    


## 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 pending, 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 signal.
    
           The _sigwaitinfo_() function shall be equivalent to the _sigwait_()
           function, except that the return value and the error reporting
           method are different (see RETURN VALUE), and that if the _info_
           argument is non-NULL, 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. Otherwise,
           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 should only check for this error if no signal is
           pending in _set_ and it is necessary to wait.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           The _sigtimedwait_() function times out and returns an **[EAGAIN]**
           error. Application developers should note that this is
           inconsistent with other functions such as _pthread_cond_timedwait_()
           that return **[ETIMEDOUT]**.
    
           Note that in order to ensure that generated signals are queued and
           signal values passed to _sigqueue_() are available in _si_value_ ,
           applications which use _sigwaitinfo_() or _sigtimedwait_() need to set
           the SA_SIGINFO flag for each signal in the set (see _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 _sa_handler_ member of **struct sigaction**
           instead of the _sa_sigaction_ member would result in undefined
           behavior, and SIG_DFL need not be assignment-compatible with
           _sa_sigaction_.  Even if an assignment of SIG_DFL to _sa_sigaction_ is
           accepted by the compiler, the implementation need not treat this
           value as special—it could just be taken as the address of a
           signal-catching function.
    


## 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.
    
           It is possible to construct a signal-waiting macro function out of
           the realtime signal function mechanism defined in this volume of
           POSIX.1‐2017. 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‐2017 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 POSIX.1‐2017. 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 concerns 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 asynchronously-generated signals. One important
           question was how many threads that are suspended 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 signal.
    
            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 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 _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'', 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.
    
           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 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.
    
           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 appropriate 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.
    


* * *