logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

sigtimedwait.3p (12707B)


  1. '\" et
  2. .TH SIGTIMEDWAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. sigtimedwait,
  12. sigwaitinfo
  13. \(em wait for queued signals
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <signal.h>
  18. .P
  19. int sigtimedwait(const sigset_t *restrict \fIset\fP,
  20. siginfo_t *restrict \fIinfo\fP,
  21. const struct timespec *restrict \fItimeout\fP);
  22. int sigwaitinfo(const sigset_t *restrict \fIset\fP,
  23. siginfo_t *restrict \fIinfo\fP);
  24. .fi
  25. .SH DESCRIPTION
  26. The
  27. \fIsigtimedwait\fR()
  28. function shall be equivalent to
  29. \fIsigwaitinfo\fR()
  30. except that if none of the signals specified by
  31. .IR set
  32. are pending,
  33. \fIsigtimedwait\fR()
  34. shall wait for the time interval specified in the
  35. .BR timespec
  36. structure referenced by
  37. .IR timeout .
  38. If the
  39. .BR timespec
  40. structure pointed to by
  41. .IR timeout
  42. is zero-valued and if none of the signals specified by
  43. .IR set
  44. are pending, then
  45. \fIsigtimedwait\fR()
  46. shall return immediately with an error. If
  47. .IR timeout
  48. is the null pointer, the behavior is unspecified.
  49. If the Monotonic Clock option is supported, the CLOCK_MONOTONIC clock
  50. shall be used to measure the time interval specified by the
  51. .IR timeout
  52. argument.
  53. .P
  54. The
  55. \fIsigwaitinfo\fR()
  56. function selects the pending signal from the set specified by
  57. .IR set .
  58. Should any of multiple pending signals in the range SIGRTMIN to
  59. SIGRTMAX be selected,
  60. it shall be the lowest numbered one. The selection order between
  61. realtime and non-realtime signals, or between multiple pending
  62. non-realtime signals, is unspecified. If no signal in
  63. .IR set
  64. is pending at the time of the call, the calling thread shall be
  65. suspended until one or more signals in
  66. .IR set
  67. become pending or until it is interrupted by an unblocked, caught
  68. signal.
  69. .P
  70. The
  71. \fIsigwaitinfo\fR()
  72. function shall be equivalent to the
  73. \fIsigwait\fR()
  74. function, except that the return value and the error reporting method
  75. are different (see RETURN VALUE), and that if the
  76. .IR info
  77. argument is non-NULL, the selected signal number shall be stored in the
  78. .IR si_signo
  79. member, and the cause of the signal shall be stored in the
  80. .IR si_code
  81. member. If any value is queued to the selected signal, the first such
  82. queued value shall be dequeued and, if the
  83. .IR info
  84. argument is non-NULL, the value shall be stored in the
  85. .IR si_value
  86. member of
  87. .IR info .
  88. The system resource used to queue the signal shall be released and
  89. returned to the system for other use. If no value is queued, the
  90. content of the
  91. .IR si_value
  92. member is undefined. If no further signals are queued for the selected
  93. signal, the pending indication for that signal shall be reset.
  94. .SH "RETURN VALUE"
  95. Upon successful completion (that is, one of the signals specified by
  96. .IR set
  97. is pending or is generated)
  98. \fIsigwaitinfo\fR()
  99. and
  100. \fIsigtimedwait\fR()
  101. shall return the selected signal number. Otherwise, the function shall
  102. return a value of \-1 and set
  103. .IR errno
  104. to indicate the error.
  105. .SH ERRORS
  106. The
  107. \fIsigtimedwait\fR()
  108. function shall fail if:
  109. .TP
  110. .BR EAGAIN
  111. No signal specified by
  112. .IR set
  113. was generated within the specified timeout period.
  114. .P
  115. The
  116. \fIsigtimedwait\fR()
  117. and
  118. \fIsigwaitinfo\fR()
  119. functions may fail if:
  120. .TP
  121. .BR EINTR
  122. The wait was interrupted by an unblocked, caught signal. It shall be
  123. documented in system documentation whether this error causes these
  124. functions to fail.
  125. .br
  126. .P
  127. The
  128. \fIsigtimedwait\fR()
  129. function may also fail if:
  130. .TP
  131. .BR EINVAL
  132. The
  133. .IR timeout
  134. argument specified a
  135. .IR tv_nsec
  136. value less than zero or greater than or equal to 1\|000 million.
  137. .P
  138. An implementation should only check for this error if no signal is
  139. pending in
  140. .IR set
  141. and it is necessary to wait.
  142. .LP
  143. .IR "The following sections are informative."
  144. .SH EXAMPLES
  145. None.
  146. .SH "APPLICATION USAGE"
  147. The
  148. \fIsigtimedwait\fR()
  149. function times out and returns an
  150. .BR [EAGAIN]
  151. error. Application developers should note that this is inconsistent
  152. with other functions such as
  153. \fIpthread_cond_timedwait\fR()
  154. that return
  155. .BR [ETIMEDOUT] .
  156. .P
  157. Note that in order to ensure that generated signals are queued and signal
  158. values passed to
  159. \fIsigqueue\fR()
  160. are available in
  161. .IR si_value ,
  162. applications which use
  163. \fIsigwaitinfo\fR()
  164. or
  165. \fIsigtimedwait\fR()
  166. need to set the SA_SIGINFO flag for each signal in the set (see
  167. .IR "Section 2.4" ", " "Signal Concepts").
  168. This means setting each signal to be handled by a three-argument
  169. signal-catching function, even if the handler will never be called.
  170. It is not possible (portably) to set a signal handler to SIG_DFL while
  171. setting the SA_SIGINFO flag, because assigning to the
  172. .IR sa_handler
  173. member of
  174. .BR "struct sigaction"
  175. instead of the
  176. .IR sa_sigaction
  177. member would result in undefined behavior, and SIG_DFL need not be
  178. assignment-compatible with
  179. .IR sa_sigaction .
  180. Even if an assignment of SIG_DFL to
  181. .IR sa_sigaction
  182. is accepted by the compiler, the implementation need not treat this value
  183. as special\(emit could just be taken as the address of a signal-catching
  184. function.
  185. .SH RATIONALE
  186. Existing programming practice on realtime systems uses the ability to
  187. pause waiting for a selected set of events and handle the first event
  188. that occurs in-line instead of in a signal-handling function. This
  189. allows applications to be written in an event-directed style similar to
  190. a state machine. This style of programming is useful for largescale
  191. transaction processing in which the overall throughput of an
  192. application and the ability to clearly track states are more important
  193. than the ability to minimize the response time of individual event
  194. handling.
  195. .P
  196. It is possible to construct a signal-waiting macro function out of the
  197. realtime signal function mechanism defined in this volume of POSIX.1\(hy2017. However, such a
  198. macro has to include the definition of a generalized handler for all
  199. signals to be waited on. A significant portion of the overhead of
  200. handler processing can be avoided if the signal-waiting function is
  201. provided by the kernel. This volume of POSIX.1\(hy2017 therefore provides two signal-waiting
  202. functions\(emone that waits indefinitely and one with a timeout\(emas
  203. part of the overall realtime signal function specification.
  204. .P
  205. The specification of a function with a timeout allows an application
  206. to be written that can be broken out of a wait after a set period of
  207. time if no event has occurred. It was argued that setting a timer
  208. event before the wait and recognizing the timer event in the wait would
  209. also implement the same functionality, but at a lower performance
  210. level. Because of the performance degradation associated with the
  211. user-level specification of a timer event and the subsequent
  212. cancellation of that timer event after the wait completes for a valid
  213. event, and the complexity associated with handling potential race
  214. conditions associated with the user-level method, the separate
  215. function has been included.
  216. .P
  217. Note that the semantics of the
  218. \fIsigwaitinfo\fR()
  219. function are nearly identical to that of the
  220. \fIsigwait\fR()
  221. function defined by this volume of POSIX.1\(hy2017. The only difference is that
  222. \fIsigwaitinfo\fR()
  223. returns the queued signal value in the
  224. .IR value
  225. argument. The return of the queued value is required so that
  226. applications can differentiate between multiple events queued to the
  227. same signal number.
  228. .P
  229. The two distinct functions are being maintained because some
  230. implementations may choose to implement the POSIX Threads Extension functions and not
  231. implement the queued signals extensions. Note, though, that
  232. \fIsigwaitinfo\fR()
  233. does not return the queued value if the
  234. .IR value
  235. argument is NULL, so the POSIX Threads Extension
  236. \fIsigwait\fR()
  237. function can be implemented as a macro on
  238. \fIsigwaitinfo\fR().
  239. .P
  240. The
  241. \fIsigtimedwait\fR()
  242. function was separated from the
  243. \fIsigwaitinfo\fR()
  244. function to address concerns regarding the overloading of the
  245. .IR timeout
  246. pointer to indicate indefinite wait (no timeout), timed wait, and
  247. immediate return, and concerns regarding consistency with other
  248. functions where the conditional and timed waits were separate
  249. functions from the pure blocking function. The semantics of
  250. \fIsigtimedwait\fR()
  251. are specified such that
  252. \fIsigwaitinfo\fR()
  253. could be implemented as a macro with a null pointer for
  254. .IR timeout .
  255. .P
  256. The
  257. .IR sigwait
  258. functions provide a synchronous mechanism for threads to wait for
  259. asynchronously-generated signals. One important question was how many
  260. threads that are suspended in a call to a
  261. \fIsigwait\fR()
  262. function for a signal should return from the call when the signal is
  263. sent. Four choices were considered:
  264. .IP " 1." 4
  265. Return an error for multiple simultaneous calls to
  266. .IR sigwait
  267. functions for the same signal.
  268. .IP " 2." 4
  269. One or more threads return.
  270. .IP " 3." 4
  271. All waiting threads return.
  272. .IP " 4." 4
  273. Exactly one thread returns.
  274. .P
  275. Prohibiting multiple calls to
  276. \fIsigwait\fR()
  277. for the same signal was felt to be overly restrictive. The ``one or
  278. more'' behavior made implementation of conforming packages easy at the
  279. expense of forcing POSIX threads clients to protect against multiple
  280. simultaneous calls to
  281. \fIsigwait\fR()
  282. in application code in order to achieve predictable behavior. There
  283. was concern that the ``all waiting threads'' behavior would result in
  284. ``signal broadcast storms'', consuming excessive CPU resources by
  285. replicating the signals in the general case. Furthermore, no
  286. convincing examples could be presented that delivery to all was either
  287. simpler or more powerful than delivery to one.
  288. .P
  289. Thus, the consensus was that exactly one thread that was suspended in a
  290. call to a
  291. .IR sigwait
  292. function for a signal should return when that signal occurs. This is
  293. not an onerous restriction as:
  294. .IP " *" 4
  295. A multi-way signal wait can be built from the single-way wait.
  296. .IP " *" 4
  297. Signals should only be handled by application-level code, as library
  298. routines cannot guess what the application wants to do with signals
  299. generated for the entire process.
  300. .IP " *" 4
  301. Applications can thus arrange for a single thread to wait for any given
  302. signal and call any needed routines upon its arrival.
  303. .P
  304. In an application that is using signals for interprocess communication,
  305. signal processing is typically done in one place. Alternatively, if
  306. the signal is being caught so that process cleanup can be done, the
  307. signal handler thread can call separate process cleanup routines for
  308. each portion of the application. Since the application main line
  309. started each portion of the application, it is at the right abstraction
  310. level to tell each portion of the application to clean up.
  311. .P
  312. Certainly, there exist programming styles where it is logical to
  313. consider waiting for a single signal in multiple threads. A simple
  314. \fIsigwait_multiple\fR()
  315. routine can be constructed to achieve this goal. A possible
  316. implementation would be to have each
  317. \fIsigwait_multiple\fR()
  318. caller registered as having expressed interest in a set of signals.
  319. The caller then waits on a thread-specific condition variable. A
  320. single server thread calls a
  321. \fIsigwait\fR()
  322. function on the union of all registered signals. When the
  323. \fIsigwait\fR()
  324. function returns, the appropriate state is set and condition variables
  325. are broadcast. New
  326. \fIsigwait_multiple\fR()
  327. callers may cause the pending
  328. \fIsigwait\fR()
  329. call to be canceled and reissued in order to update the set of signals
  330. being waited for.
  331. .SH "FUTURE DIRECTIONS"
  332. None.
  333. .SH "SEE ALSO"
  334. .IR "Section 2.4" ", " "Signal Concepts",
  335. .IR "Section 2.8.1" ", " "Realtime Signals",
  336. .IR "\fIpause\fR\^(\|)",
  337. .IR "\fIpthread_sigmask\fR\^(\|)",
  338. .IR "\fIsigaction\fR\^(\|)",
  339. .IR "\fIsigpending\fR\^(\|)",
  340. .IR "\fIsigsuspend\fR\^(\|)",
  341. .IR "\fIsigwait\fR\^(\|)"
  342. .P
  343. The Base Definitions volume of POSIX.1\(hy2017,
  344. .IR "\fB<signal.h>\fP",
  345. .IR "\fB<time.h>\fP"
  346. .\"
  347. .SH COPYRIGHT
  348. Portions of this text are reprinted and reproduced in electronic form
  349. from IEEE Std 1003.1-2017, Standard for Information Technology
  350. -- Portable Operating System Interface (POSIX), The Open Group Base
  351. Specifications Issue 7, 2018 Edition,
  352. Copyright (C) 2018 by the Institute of
  353. Electrical and Electronics Engineers, Inc and The Open Group.
  354. In the event of any discrepancy between this version and the original IEEE and
  355. The Open Group Standard, the original IEEE and The Open Group Standard
  356. is the referee document. The original Standard can be obtained online at
  357. http://www.opengroup.org/unix/online.html .
  358. .PP
  359. Any typographical or formatting errors that appear
  360. in this page are most likely
  361. to have been introduced during the conversion of the source files to
  362. man page format. To report such errors, see
  363. https://www.kernel.org/doc/man-pages/reporting_bugs.html .