1SIGTIMEDWAIT(3P) POSIX Programmer's Manual SIGTIMEDWAIT(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 sigtimedwait, sigwaitinfo — wait for queued signals
13
15 #include <signal.h>
16 int sigtimedwait(const sigset_t *restrict set,
18 siginfo_t *restrict info,
19 const struct timespec *restrict timeout);
20 int sigwaitinfo(const sigset_t *restrict set,
21 siginfo_t *restrict info);
22
24 The sigtimedwait() function shall be equivalent to sigwaitinfo() except
25 that if none of the signals specified by set are pending, sigtimed‐
26 wait() shall wait for the time interval specified in the timespec
27 structure referenced by timeout. If the timespec structure pointed to
28 by timeout is zero-valued and if none of the signals specified by set
29 are pending, then sigtimedwait() shall return immediately with an
30 error. If timeout is the null pointer, the behavior is unspecified. If
31 the Monotonic Clock option is supported, the CLOCK_MONOTONIC clock
32 shall be used to measure the time interval specified by the timeout
33 argument.
34 The sigwaitinfo() function selects the pending signal from the set
36 specified by set. Should any of multiple pending signals in the range
37 SIGRTMIN to SIGRTMAX be selected, it shall be the lowest numbered one.
38 The selection order between realtime and non-realtime signals, or
39 between multiple pending non-realtime signals, is unspecified. If no
40 signal in set is pending at the time of the call, the calling thread
41 shall be suspended until one or more signals in set become pending or
42 until it is interrupted by an unblocked, caught signal.
43 The sigwaitinfo() function shall be equivalent to the sigwait() func‐
45 tion, except that the return value and the error reporting method are
46 different (see RETURN VALUE), and that if the info argument is non-
47 NULL, the selected signal number shall be stored in the si_signo mem‐
48 ber, and the cause of the signal shall be stored in the si_code member.
49 If any value is queued to the selected signal, the first such queued
50 value shall be dequeued and, if the info argument is non-NULL, the
51 value shall be stored in the si_value member of info. The system
52 resource used to queue the signal shall be released and returned to the
53 system for other use. If no value is queued, the content of the
54 si_value member is undefined. If no further signals are queued for the
55 selected signal, the pending indication for that signal shall be reset.
56
58 Upon successful completion (that is, one of the signals specified by
59 set is pending or is generated) sigwaitinfo() and sigtimedwait() shall
60 return the selected signal number. Otherwise, the function shall return
61 a value of -1 and set errno to indicate the error.
62
64 The sigtimedwait() function shall fail if:
65 EAGAIN No signal specified by set was generated within the specified
67 timeout period.
68 The sigtimedwait() and sigwaitinfo() functions may fail if:
70 EINTR The wait was interrupted by an unblocked, caught signal. It
72 shall be documented in system documentation whether this error
73 causes these functions to fail.
74 The sigtimedwait() function may also fail if:
76 EINVAL The timeout argument specified a tv_nsec value less than zero or
78 greater than or equal to 1000 million.
79 An implementation should only check for this error if no signal is
81 pending in set and it is necessary to wait.
82 The following sections are informative.
84
86 None.
87
89 The sigtimedwait() function times out and returns an [EAGAIN] error.
90 Application developers should note that this is inconsistent with other
91 functions such as pthread_cond_timedwait() that return [ETIMEDOUT].
92 Note that in order to ensure that generated signals are queued and sig‐
94 nal values passed to sigqueue() are available in si_value, applications
95 which use sigwaitinfo() or sigtimedwait() need to set the SA_SIGINFO
96 flag for each signal in the set (see Section 2.4, Signal Concepts).
97 This means setting each signal to be handled by a three-argument sig‐
98 nal-catching function, even if the handler will never be called. It is
99 not possible (portably) to set a signal handler to SIG_DFL while set‐
100 ting the SA_SIGINFO flag, because assigning to the sa_handler member of
101 struct sigaction instead of the sa_sigaction member would result in
102 undefined behavior, and SIG_DFL need not be assignment-compatible with
103 sa_sigaction. Even if an assignment of SIG_DFL to sa_sigaction is
104 accepted by the compiler, the implementation need not treat this value
105 as special—it could just be taken as the address of a signal-catching
106 function.
107
109 Existing programming practice on realtime systems uses the ability to
110 pause waiting for a selected set of events and handle the first event
111 that occurs in-line instead of in a signal-handling function. This
112 allows applications to be written in an event-directed style similar to
113 a state machine. This style of programming is useful for largescale
114 transaction processing in which the overall throughput of an applica‐
115 tion and the ability to clearly track states are more important than
116 the ability to minimize the response time of individual event handling.
117 It is possible to construct a signal-waiting macro function out of the
119 realtime signal function mechanism defined in this volume of
120 POSIX.1‐2017. However, such a macro has to include the definition of a
121 generalized handler for all signals to be waited on. A significant por‐
122 tion of the overhead of handler processing can be avoided if the sig‐
123 nal-waiting function is provided by the kernel. This volume of
124 POSIX.1‐2017 therefore provides two signal-waiting functions—one that
125 waits indefinitely and one with a timeout—as part of the overall real‐
126 time signal function specification.
127 The specification of a function with a timeout allows an application to
129 be written that can be broken out of a wait after a set period of time
130 if no event has occurred. It was argued that setting a timer event
131 before the wait and recognizing the timer event in the wait would also
132 implement the same functionality, but at a lower performance level.
133 Because of the performance degradation associated with the user-level
134 specification of a timer event and the subsequent cancellation of that
135 timer event after the wait completes for a valid event, and the com‐
136 plexity associated with handling potential race conditions associated
137 with the user-level method, the separate function has been included.
138 Note that the semantics of the sigwaitinfo() function are nearly iden‐
140 tical to that of the sigwait() function defined by this volume of
141 POSIX.1‐2017. The only difference is that sigwaitinfo() returns the
142 queued signal value in the value argument. The return of the queued
143 value is required so that applications can differentiate between multi‐
144 ple events queued to the same signal number.
145 The two distinct functions are being maintained because some implemen‐
147 tations may choose to implement the POSIX Threads Extension functions
148 and not implement the queued signals extensions. Note, though, that
149 sigwaitinfo() does not return the queued value if the value argument is
150 NULL, so the POSIX Threads Extension sigwait() function can be imple‐
151 mented as a macro on sigwaitinfo().
152 The sigtimedwait() function was separated from the sigwaitinfo() func‐
154 tion to address concerns regarding the overloading of the timeout
155 pointer to indicate indefinite wait (no timeout), timed wait, and imme‐
156 diate return, and concerns regarding consistency with other functions
157 where the conditional and timed waits were separate functions from the
158 pure blocking function. The semantics of sigtimedwait() are specified
159 such that sigwaitinfo() could be implemented as a macro with a null
160 pointer for timeout.
161 The sigwait functions provide a synchronous mechanism for threads to
163 wait for asynchronously-generated signals. One important question was
164 how many threads that are suspended in a call to a sigwait() function
165 for a signal should return from the call when the signal is sent. Four
166 choices were considered:
167 1. Return an error for multiple simultaneous calls to sigwait func‐
169 tions for the same signal.
170 2. One or more threads return.
172 3. All waiting threads return.
174 4. Exactly one thread returns.
176 Prohibiting multiple calls to sigwait() for the same signal was felt to
178 be overly restrictive. The ``one or more'' behavior made implementation
179 of conforming packages easy at the expense of forcing POSIX threads
180 clients to protect against multiple simultaneous calls to sigwait() in
181 application code in order to achieve predictable behavior. There was
182 concern that the ``all waiting threads'' behavior would result in
183 ``signal broadcast storms'', consuming excessive CPU resources by
184 replicating the signals in the general case. Furthermore, no convincing
185 examples could be presented that delivery to all was either simpler or
186 more powerful than delivery to one.
187 Thus, the consensus was that exactly one thread that was suspended in a
189 call to a sigwait function for a signal should return when that signal
190 occurs. This is not an onerous restriction as:
191 * A multi-way signal wait can be built from the single-way wait.
193 * Signals should only be handled by application-level code, as
195 library routines cannot guess what the application wants to do with
196 signals generated for the entire process.
197 * Applications can thus arrange for a single thread to wait for any
199 given signal and call any needed routines upon its arrival.
200 In an application that is using signals for interprocess communication,
202 signal processing is typically done in one place. Alternatively, if the
203 signal is being caught so that process cleanup can be done, the signal
204 handler thread can call separate process cleanup routines for each por‐
205 tion of the application. Since the application main line started each
206 portion of the application, it is at the right abstraction level to
207 tell each portion of the application to clean up.
208 Certainly, there exist programming styles where it is logical to con‐
210 sider waiting for a single signal in multiple threads. A simple sig‐
211 wait_multiple() routine can be constructed to achieve this goal. A pos‐
212 sible implementation would be to have each sigwait_multiple() caller
213 registered as having expressed interest in a set of signals. The call‐
214 er then waits on a thread-specific condition variable. A single server
215 thread calls a sigwait() function on the union of all registered sig‐
216 nals. When the sigwait() function returns, the appropriate state is set
217 and condition variables are broadcast. New sigwait_multiple() callers
218 may cause the pending sigwait() call to be canceled and reissued in
219 order to update the set of signals being waited for.
220
222 None.
223
225 Section 2.4, Signal Concepts, Section 2.8.1, Realtime Signals, pause(),
226 pthread_sigmask(), sigaction(), sigpending(), sigsuspend(), sigwait()
227 The Base Definitions volume of POSIX.1‐2017, <signal.h>, <time.h>
229
231 Portions of this text are reprinted and reproduced in electronic form
232 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
233 table Operating System Interface (POSIX), The Open Group Base Specifi‐
234 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
235 Electrical and Electronics Engineers, Inc and The Open Group. In the
236 event of any discrepancy between this version and the original IEEE and
237 The Open Group Standard, the original IEEE and The Open Group Standard
238 is the referee document. The original Standard can be obtained online
239 at http://www.opengroup.org/unix/online.html .
240 Any typographical or formatting errors that appear in this page are
242 most likely to have been introduced during the conversion of the source
243 files to man page format. To report such errors, see https://www.ker‐
244 nel.org/doc/man-pages/reporting_bugs.html .
245IEEE/The Open Group 2017 SIGTIMEDWAIT(3P)