1SIGTIMEDWAIT(P) POSIX Programmer's Manual SIGTIMEDWAIT(P)
2
6 sigtimedwait, sigwaitinfo - wait for queued signals (REALTIME)
7
9 #include <signal.h>
10 int sigtimedwait(const sigset_t *restrict set,
12 siginfo_t *restrict info,
13 const struct timespec *restrict timeout);
14 int sigwaitinfo(const sigset_t *restrict set,
15 siginfo_t *restrict info);
16
19 The sigtimedwait() function shall be equivalent to sigwaitinfo() except
20 that if none of the signals specified by set are pending, sigtimed‐
21 wait() shall wait for the time interval specified in the timespec
22 structure referenced by timeout. If the timespec structure pointed to
23 by timeout is zero-valued and if none of the signals specified by set
24 are pending, then sigtimedwait() shall return immediately with an
25 error. If timeout is the NULL pointer, the behavior is unspecified.
26 If the Monotonic Clock option is supported, the CLOCK_MONOTONIC clock
27 shall be used to measure the time interval specified by the timeout
28 argument.
29 The sigwaitinfo() function selects the pending signal from the set
31 specified by set. Should any of multiple pending signals in the range
32 SIGRTMIN to SIGRTMAX be selected, it shall be the lowest numbered one.
33 The selection order between realtime and non-realtime signals, or
34 between multiple pending non-realtime signals, is unspecified. If no
35 signal in set is pending at the time of the call, the calling thread
36 shall be suspended until one or more signals in set become pending or
37 until it is interrupted by an unblocked, caught signal.
38 The sigwaitinfo() function shall be equivalent to the sigwait() func‐
40 tion if the info argument is NULL. If the info argument is non-NULL,
41 the sigwaitinfo() function shall be equivalent to sigwait(), except
42 that the selected signal number shall be stored in the si_signo member,
43 and the cause of the signal shall be stored in the si_code member. If
44 any value is queued to the selected signal, the first such queued value
45 shall be dequeued and, if the info argument is non-NULL, the value
46 shall be stored in the si_value member of info. The system resource
47 used to queue the signal shall be released and returned to the system
48 for other use. If no value is queued, the content of the si_value mem‐
49 ber is undefined. If no further signals are queued for the selected
50 signal, the pending indication for that signal shall be reset.
51
53 Upon successful completion (that is, one of the signals specified by
54 set is pending or is generated) sigwaitinfo() and sigtimedwait() shall
55 return the selected signal number. Otherwise, the function shall
56 return a value of -1 and set errno to indicate the error.
57
59 The sigtimedwait() function shall fail if:
60 EAGAIN No signal specified by set was generated within the specified
62 timeout period.
63 The sigtimedwait() and sigwaitinfo() functions may fail if:
66 EINTR The wait was interrupted by an unblocked, caught signal. It
68 shall be documented in system documentation whether this error
69 causes these functions to fail.
70 The sigtimedwait() function may also fail if:
73 EINVAL The timeout argument specified a tv_nsec value less than zero or
75 greater than or equal to 1000 million.
76 An implementation only checks for this error if no signal is pending in
79 set and it is necessary to wait.
80 The following sections are informative.
82
84 None.
85
87 The sigtimedwait() function times out and returns an [EAGAIN] error.
88 Application writers should note that this is inconsistent with other
89 functions such as pthread_cond_timedwait() that return [ETIMEDOUT].
90
92 Existing programming practice on realtime systems uses the ability to
93 pause waiting for a selected set of events and handle the first event
94 that occurs in-line instead of in a signal-handling function. This
95 allows applications to be written in an event-directed style similar to
96 a state machine. This style of programming is useful for largescale
97 transaction processing in which the overall throughput of an applica‐
98 tion and the ability to clearly track states are more important than
99 the ability to minimize the response time of individual event handling.
100 It is possible to construct a signal-waiting macro function out of the
102 realtime signal function mechanism defined in this volume of
103 IEEE Std 1003.1-2001. However, such a macro has to include the defini‐
104 tion of a generalized handler for all signals to be waited on. A sig‐
105 nificant portion of the overhead of handler processing can be avoided
106 if the signal-waiting function is provided by the kernel. This volume
107 of IEEE Std 1003.1-2001 therefore provides two signal-waiting func‐
108 tions-one that waits indefinitely and one with a timeout-as part of the
109 overall realtime signal function specification.
110 The specification of a function with a timeout allows an application to
112 be written that can be broken out of a wait after a set period of time
113 if no event has occurred. It was argued that setting a timer event
114 before the wait and recognizing the timer event in the wait would also
115 implement the same functionality, but at a lower performance level.
116 Because of the performance degradation associated with the user-level
117 specification of a timer event and the subsequent cancellation of that
118 timer event after the wait completes for a valid event, and the com‐
119 plexity associated with handling potential race conditions associated
120 with the user-level method, the separate function has been included.
121 Note that the semantics of the sigwaitinfo() function are nearly iden‐
123 tical to that of the sigwait() function defined by this volume of
124 IEEE Std 1003.1-2001. The only difference is that sigwaitinfo() returns
125 the queued signal value in the value argument. The return of the queued
126 value is required so that applications can differentiate between multi‐
127 ple events queued to the same signal number.
128 The two distinct functions are being maintained because some implemen‐
130 tations may choose to implement the POSIX Threads Extension functions
131 and not implement the queued signals extensions. Note, though, that
132 sigwaitinfo() does not return the queued value if the value argument is
133 NULL, so the POSIX Threads Extension sigwait() function can be imple‐
134 mented as a macro on sigwaitinfo().
135 The sigtimedwait() function was separated from the sigwaitinfo() func‐
137 tion to address concerns regarding the overloading of the timeout
138 pointer to indicate indefinite wait (no timeout), timed wait, and imme‐
139 diate return, and concerns regarding consistency with other functions
140 where the conditional and timed waits were separate functions from the
141 pure blocking function. The semantics of sigtimedwait() are specified
142 such that sigwaitinfo() could be implemented as a macro with a NULL
143 pointer for timeout.
144 The sigwait functions provide a synchronous mechanism for threads to
146 wait for asynchronously-generated signals. One important question was
147 how many threads that are suspended in a call to a sigwait() function
148 for a signal should return from the call when the signal is sent. Four
149 choices were considered:
150 1. Return an error for multiple simultaneous calls to sigwait func‐
152 tions for the same signal.
153 2. One or more threads return.
155 3. All waiting threads return.
157 4. Exactly one thread returns.
159 Prohibiting multiple calls to sigwait() for the same signal was felt to
161 be overly restrictive. The "one or more" behavior made implementation
162 of conforming packages easy at the expense of forcing POSIX threads
163 clients to protect against multiple simultaneous calls to sigwait() in
164 application code in order to achieve predictable behavior. There was
165 concern that the "all waiting threads" behavior would result in "signal
166 broadcast storms", consuming excessive CPU resources by replicating the
167 signals in the general case. Furthermore, no convincing examples could
168 be presented that delivery to all was either simpler or more powerful
169 than delivery to one.
170 Thus, the consensus was that exactly one thread that was suspended in a
172 call to a sigwait function for a signal should return when that signal
173 occurs. This is not an onerous restriction as:
174 * A multi-way signal wait can be built from the single-way wait.
176 * Signals should only be handled by application-level code, as library
178 routines cannot guess what the application wants to do with signals
179 generated for the entire process.
180 * Applications can thus arrange for a single thread to wait for any
182 given signal and call any needed routines upon its arrival.
183 In an application that is using signals for interprocess communication,
185 signal processing is typically done in one place. Alternatively, if
186 the signal is being caught so that process cleanup can be done, the
187 signal handler thread can call separate process cleanup routines for
188 each portion of the application. Since the application main line
189 started each portion of the application, it is at the right abstraction
190 level to tell each portion of the application to clean up.
191 Certainly, there exist programming styles where it is logical to con‐
193 sider waiting for a single signal in multiple threads. A simple sig‐
194 wait_multiple() routine can be constructed to achieve this goal. A pos‐
195 sible implementation would be to have each sigwait_multiple() caller
196 registered as having expressed interest in a set of signals. The caller
197 then waits on a thread-specific condition variable. A single server
198 thread calls a sigwait() function on the union of all registered sig‐
199 nals. When the sigwait() function returns, the appropriate state is set
200 and condition variables are broadcast. New sigwait_multiple() callers
201 may cause the pending sigwait() call to be canceled and reissued in
202 order to update the set of signals being waited for.
203
205 None.
206
208 Realtime Signals , pause() , pthread_sigmask() , sigaction() , sigpend‐
209 ing() , sigsuspend() , sigwait() , the Base Definitions volume of
210 IEEE Std 1003.1-2001, <signal.h>, <time.h>
211
213 Portions of this text are reprinted and reproduced in electronic form
214 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
215 -- Portable Operating System Interface (POSIX), The Open Group Base
216 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
217 Electrical and Electronics Engineers, Inc and The Open Group. In the
218 event of any discrepancy between this version and the original IEEE and
219 The Open Group Standard, the original IEEE and The Open Group Standard
220 is the referee document. The original Standard can be obtained online
221 at http://www.opengroup.org/unix/online.html .
222IEEE/The Open Group 2003 SIGTIMEDWAIT(P)