1SIGTIMEDWAIT(3P)           POSIX Programmer's Manual          SIGTIMEDWAIT(3P)
2
3
4

PROLOG

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

NAME

12       sigtimedwait, sigwaitinfo — wait for queued signals
13

SYNOPSIS

15       #include <signal.h>
16
17       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

DESCRIPTION

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
35       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
44       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

RETURN VALUE

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

ERRORS

64       The sigtimedwait() function shall fail if:
65
66       EAGAIN No signal specified by set was generated  within  the  specified
67              timeout period.
68
69       The sigtimedwait() and sigwaitinfo() functions may fail if:
70
71       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
75       The sigtimedwait() function may also fail if:
76
77       EINVAL The timeout argument specified a tv_nsec value less than zero or
78              greater than or equal to 1000 million.
79
80       An implementation should only check for this  error  if  no  signal  is
81       pending in set and it is necessary to wait.
82
83       The following sections are informative.
84

EXAMPLES

86       None.
87

APPLICATION USAGE

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
93       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

RATIONALE

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
118       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
128       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
139       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
146       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
153       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
162       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
168        1. Return  an  error  for multiple simultaneous calls to sigwait func‐
169           tions for the same signal.
170
171        2. One or more threads return.
172
173        3. All waiting threads return.
174
175        4. Exactly one thread returns.
176
177       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
188       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
192        *  A multi-way signal wait can be built from the single-way wait.
193
194        *  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
198        *  Applications  can  thus arrange for a single thread to wait for any
199           given signal and call any needed routines upon its arrival.
200
201       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
209       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

FUTURE DIRECTIONS

222       None.
223

SEE ALSO

225       Section 2.4, Signal Concepts, Section 2.8.1, Realtime Signals, pause(),
226       pthread_sigmask(), sigaction(), sigpending(), sigsuspend(), sigwait()
227
228       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
241       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 .
245
246
247
248IEEE/The Open Group                  2017                     SIGTIMEDWAIT(3P)
Impressum