SIGTIMEDWAIT(3)            POSIX Programmer's Manual           SIGTIMEDWAIT(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       sigtimedwait, sigwaitinfo -- wait for queued signals

SSYYNNOOPPSSIISS
       #include <signal.h>

       int sigtimedwait(const sigset_t *restrict _s_e_t,
           siginfo_t *restrict _i_n_f_o,
           const struct timespec *restrict _t_i_m_e_o_u_t);
       int sigwaitinfo(const sigset_t *restrict _s_e_t,
           siginfo_t *restrict _i_n_f_o);

DDEESSCCRRIIPPTTIIOONN
       The _s_i_g_t_i_m_e_d_w_a_i_t() function shall be equivalent to _s_i_g_w_a_i_t_i_n_f_o() except
       that if none of the signals specified by _s_e_t are pending,
       _s_i_g_t_i_m_e_d_w_a_i_t() shall wait for the time interval specified in the
       ttiimmeessppeecc structure referenced by _t_i_m_e_o_u_t.  If the ttiimmeessppeecc structure
       pointed to by _t_i_m_e_o_u_t is zero-valued and if none of the signals
       specified by _s_e_t are pending, then _s_i_g_t_i_m_e_d_w_a_i_t() shall return
       immediately with an error. If _t_i_m_e_o_u_t 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 _t_i_m_e_o_u_t argument.

       The _s_i_g_w_a_i_t_i_n_f_o() function selects the pending signal from the set
       specified by _s_e_t.  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 _s_e_t is pending at the time of the call, the calling thread
       shall be suspended until one or more signals in _s_e_t become pending or
       until it is interrupted by an unblocked, caught signal.

       The _s_i_g_w_a_i_t_i_n_f_o() function shall be equivalent to the _s_i_g_w_a_i_t()
       function, except that the return value and the error reporting method
       are different (see RETURN VALUE), and that if the _i_n_f_o argument is non-
       NULL, the selected signal number shall be stored in the _s_i___s_i_g_n_o
       member, and the cause of the signal shall be stored in the _s_i___c_o_d_e
       member. If any value is queued to the selected signal, the first such
       queued value shall be dequeued and, if the _i_n_f_o argument is non-NULL,
       the value shall be stored in the _s_i___v_a_l_u_e member of _i_n_f_o.  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
       _s_i___v_a_l_u_e member is undefined. If no further signals are queued for the
       selected signal, the pending indication for that signal shall be reset.

RREETTUURRNN VVAALLUUEE
       Upon successful completion (that is, one of the signals specified by
       _s_e_t is pending or is generated) _s_i_g_w_a_i_t_i_n_f_o() and _s_i_g_t_i_m_e_d_w_a_i_t() shall
       return the selected signal number. Otherwise, the function shall return
       a value of -1 and set _e_r_r_n_o to indicate the error.

EERRRROORRSS
       The _s_i_g_t_i_m_e_d_w_a_i_t() function shall fail if:

       EEAAGGAAIINN No signal specified by _s_e_t was generated within the specified
              timeout period.

       The _s_i_g_t_i_m_e_d_w_a_i_t() and _s_i_g_w_a_i_t_i_n_f_o() functions may fail if:

       EEIINNTTRR  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 _s_i_g_t_i_m_e_d_w_a_i_t() function may also fail if:

       EEIINNVVAALL The _t_i_m_e_o_u_t argument specified a _t_v___n_s_e_c 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 _s_e_t and it is necessary to wait.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The _s_i_g_t_i_m_e_d_w_a_i_t() function times out and returns an [[EEAAGGAAIINN]] error.
       Application developers should note that this is inconsistent with other
       functions such as _p_t_h_r_e_a_d___c_o_n_d___t_i_m_e_d_w_a_i_t() that return [[EETTIIMMEEDDOOUUTT]].

       Note that in order to ensure that generated signals are queued and
       signal values passed to _s_i_g_q_u_e_u_e() are available in _s_i___v_a_l_u_e,
       applications which use _s_i_g_w_a_i_t_i_n_f_o() or _s_i_g_t_i_m_e_d_w_a_i_t() need to set the
       SA_SIGINFO flag for each signal in the set (see _S_e_c_t_i_o_n _2_._4, _S_i_g_n_a_l
       _C_o_n_c_e_p_t_s).  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
       _s_a___h_a_n_d_l_e_r member of ssttrruucctt ssiiggaaccttiioonn instead of the _s_a___s_i_g_a_c_t_i_o_n
       member would result in undefined behavior, and SIG_DFL need not be
       assignment-compatible with _s_a___s_i_g_a_c_t_i_o_n.  Even if an assignment of
       SIG_DFL to _s_a___s_i_g_a_c_t_i_o_n 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.

RRAATTIIOONNAALLEE
       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 _s_i_g_w_a_i_t_i_n_f_o() function are nearly
       identical to that of the _s_i_g_w_a_i_t() function defined by this volume of
       POSIX.1-2017. The only difference is that _s_i_g_w_a_i_t_i_n_f_o() returns the
       queued signal value in the _v_a_l_u_e 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 _s_i_g_w_a_i_t_i_n_f_o() does not return the queued value if the
       _v_a_l_u_e argument is NULL, so the POSIX Threads Extension _s_i_g_w_a_i_t()
       function can be implemented as a macro on _s_i_g_w_a_i_t_i_n_f_o().

       The _s_i_g_t_i_m_e_d_w_a_i_t() function was separated from the _s_i_g_w_a_i_t_i_n_f_o()
       function to address concerns regarding the overloading of the _t_i_m_e_o_u_t
       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 _s_i_g_t_i_m_e_d_w_a_i_t() are
       specified such that _s_i_g_w_a_i_t_i_n_f_o() could be implemented as a macro with
       a null pointer for _t_i_m_e_o_u_t.

       The _s_i_g_w_a_i_t 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 _s_i_g_w_a_i_t() 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 _s_i_g_w_a_i_t
           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 _s_i_g_w_a_i_t() 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 _s_i_g_w_a_i_t() 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 _s_i_g_w_a_i_t 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
       _s_i_g_w_a_i_t___m_u_l_t_i_p_l_e() routine can be constructed to achieve this goal. A
       possible implementation would be to have each _s_i_g_w_a_i_t___m_u_l_t_i_p_l_e() 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 _s_i_g_w_a_i_t() function on the union of all registered
       signals. When the _s_i_g_w_a_i_t() function returns, the appropriate state is
       set and condition variables are broadcast. New _s_i_g_w_a_i_t___m_u_l_t_i_p_l_e()
       callers may cause the pending _s_i_g_w_a_i_t() call to be canceled and
       reissued in order to update the set of signals being waited for.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _S_e_c_t_i_o_n _2_._4, _S_i_g_n_a_l _C_o_n_c_e_p_t_s, _S_e_c_t_i_o_n _2_._8_._1, _R_e_a_l_t_i_m_e _S_i_g_n_a_l_s, _p_a_u_s_e(),
       _p_t_h_r_e_a_d___s_i_g_m_a_s_k(), _s_i_g_a_c_t_i_o_n(), _s_i_g_p_e_n_d_i_n_g(), _s_i_g_s_u_s_p_e_n_d(), _s_i_g_w_a_i_t()

       The Base Definitions volume of POSIX.1-2017, <<ssiiggnnaall..hh>>, <<ttiimmee..hh>>

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

       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 .



IEEE/The Open Group                  2017                      SIGTIMEDWAIT(3)
