HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
PROLOG |NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |EXAMPLES |APPLICATION USAGE |RATIONALE |FUTURE DIRECTIONS |SEE ALSO |COPYRIGHT | |
SIGTIMEDWAIT(3P) POSIX Programmer's ManualSIGTIMEDWAIT(3P)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.
sigtimedwait, sigwaitinfo — wait for queued signals
#include <signal.h> int sigtimedwait(const sigset_t *restrictset, siginfo_t *restrictinfo, const struct timespec *restricttimeout); int sigwaitinfo(const sigset_t *restrictset, siginfo_t *restrictinfo);
Thesigtimedwait() function shall be equivalent tosigwaitinfo() except that if none of the signals specified byset are pending,sigtimedwait() shall wait for the time interval specified in thetimespecstructure referenced bytimeout. If thetimespec structure pointed to bytimeout is zero-valued and if none of the signals specified byset are pending, thensigtimedwait() shall return immediately with an error. Iftimeout 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 thetimeout argument. Thesigwaitinfo() function selects the pending signal from the set specified byset. 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 inset is pending at the time of the call, the calling thread shall be suspended until one or more signals inset become pending or until it is interrupted by an unblocked, caught signal. Thesigwaitinfo() function shall be equivalent to thesigwait() function, except that the return value and the error reporting method are different (see RETURN VALUE), and that if theinfo argument is non-NULL, the selected signal number shall be stored in thesi_signo member, and the cause of the signal shall be stored in thesi_code member. If any value is queued to the selected signal, the first such queued value shall be dequeued and, if theinfo argument is non-NULL, the value shall be stored in thesi_value member ofinfo. 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 thesi_value member is undefined. If no further signals are queued for the selected signal, the pending indication for that signal shall be reset.
Upon successful completion (that is, one of the signals specified byset is pending or is generated)sigwaitinfo() andsigtimedwait() shall return the selected signal number. Otherwise, the function shall return a value of -1 and seterrno to indicate the error.
Thesigtimedwait() function shall fail if:EAGAINNo signal specified byset was generated within the specified timeout period. Thesigtimedwait() andsigwaitinfo() functions may fail if:EINTRThe wait was interrupted by an unblocked, caught signal. It shall be documented in system documentation whether this error causes these functions to fail. Thesigtimedwait() function may also fail if:EINVALThetimeout argument specified atv_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 inset and it is necessary to wait.The following sections are informative.
None.
Thesigtimedwait() function times out and returns an[EAGAIN] error. Application developers should note that this is inconsistent with other functions such aspthread_cond_timedwait() that return[ETIMEDOUT]. Note that in order to ensure that generated signals are queued and signal values passed tosigqueue() are available insi_value, applications which usesigwaitinfo() orsigtimedwait() need to set the SA_SIGINFO flag for each signal in the set (seeSection 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 thesa_handler member ofstruct sigaction instead of thesa_sigaction member would result in undefined behavior, and SIG_DFL need not be assignment-compatible withsa_sigaction. Even if an assignment of SIG_DFL tosa_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.
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 thesigwaitinfo() function are nearly identical to that of thesigwait() function defined by this volume of POSIX.1‐2017. The only difference is thatsigwaitinfo() returns the queued signal value in thevalue 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, thatsigwaitinfo() does not return the queued value if thevalue argument is NULL, so the POSIX Threads Extensionsigwait() function can be implemented as a macro onsigwaitinfo(). Thesigtimedwait() function was separated from thesigwaitinfo() function to address concerns regarding the overloading of thetimeout 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 ofsigtimedwait() are specified such thatsigwaitinfo() could be implemented as a macro with a null pointer fortimeout. Thesigwait 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 asigwait() 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 tosigwait functions for the same signal. 2. One or more threads return. 3. All waiting threads return. 4. Exactly one thread returns. Prohibiting multiple calls tosigwait() 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 tosigwait() 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 asigwait 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 simplesigwait_multiple() routine can be constructed to achieve this goal. A possible implementation would be to have eachsigwait_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 asigwait() function on the union of all registered signals. When thesigwait() function returns, the appropriate state is set and condition variables are broadcast. Newsigwait_multiple() callers may cause the pendingsigwait() call to be canceled and reissued in order to update the set of signals being waited for.
None.
Section 2.4,Signal Concepts,Section 2.8.1,Realtime Signals,pause(3p),pthread_sigmask(3p),sigaction(3p),sigpending(3p),sigsuspend(3p),sigwait(3p) The Base Definitions volume of POSIX.1‐2017,signal.h(0p),time.h(0p)
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 athttp://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, seehttps://www.kernel.org/doc/man-pages/reporting_bugs.html .IEEE/The Open Group 2017SIGTIMEDWAIT(3P)Pages that refer to this page:signal.h(0p), sigwait(3p), sigwaitinfo(3p)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |