sigtimedwait.html

IEEE 1003.1-2003, Single Unix Specification v3

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.</p>

<p>Note that the semantics of the <i>sigwaitinfo</i>() function are nearly identical to that of the <a href=
"../functions/sigwait.html"><i>sigwait</i>()</a> function defined by this volume of IEEE&nbsp;Std&nbsp;1003.1-2001. The only
difference is that <i>sigwaitinfo</i>() returns the queued signal value in the <i>value</i> argument. The return of the queued
value is required so that applications can differentiate between multiple events queued to the same signal number.</p>

<p>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, that <i>sigwaitinfo</i>() does not return the queued value
if the <i>value</i> argument is NULL, so the POSIX Threads Extension <a href="../functions/sigwait.html"><i>sigwait</i>()</a>
function can be implemented as a macro on <i>sigwaitinfo</i>().</p>

<p>The <i>sigtimedwait</i>() function was separated from the <i>sigwaitinfo</i>() function to address concerns regarding the
overloading of the <i>timeout</i> 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 of <i>sigtimedwait</i>() are specified such that <i>sigwaitinfo</i>() could be implemented as a macro with
a NULL pointer for <i>timeout</i>.</p>

<p>The <i>sigwait</i> 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 a <a href="../functions/sigwait.html"><i>sigwait</i>()</a>
function for a signal should return from the call when the signal is sent. Four choices were considered:</p>

<ol>
<li>
<p>Return an error for multiple simultaneous calls to <i>sigwait</i> functions for the same signal.</p>
</li>

<li>
<p>One or more threads return.</p>
</li>

<li>
<p>All waiting threads return.</p>
</li>

<li>
<p>Exactly one thread returns.</p>
</li>
</ol>

<p>Prohibiting multiple calls to <a href="../functions/sigwait.html"><i>sigwait</i>()</a> for the same signal was felt to be overly
restrictive. The &quot;one or more&quot; behavior made implementation of conforming packages easy at the expense of forcing POSIX threads
clients to protect against multiple simultaneous calls to <a href="../functions/sigwait.html"><i>sigwait</i>()</a> in application
code in order to achieve predictable behavior. There was concern that the &quot;all waiting threads&quot; behavior would result in &quot;signal
broadcast storms&quot;, 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.</p>

<p>Thus, the consensus was that exactly one thread that was suspended in a call to a <i>sigwait</i> function for a signal should
return when that signal occurs. This is not an onerous restriction as:</p>

<ul>
<li>
<p>A multi-way signal wait can be built from the single-way wait.</p>
</li>

<li>
<p>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.</p>
</li>

<li>
<p>Applications can thus arrange for a single thread to wait for any given signal and call any needed routines upon its
arrival.</p>
</li>
</ul>

<p>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.</p>

<p>Certainly, there exist programming styles where it is logical to consider waiting for a single signal in multiple threads. A
simple <i>sigwait_multiple</i>() routine can be constructed to achieve this goal. A possible implementation would be to have each
<i>sigwait_multiple</i>() 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 a <a href="../functions/sigwait.html"><i>sigwait</i>()</a>
function on the union of all registered signals. When the <a href="../functions/sigwait.html"><i>sigwait</i>()</a> function
returns, the appropriate state is set and condition variables are broadcast. New <i>sigwait_multiple</i>() callers may cause the
pending <a href="../functions/sigwait.html"><i>sigwait</i>()</a> call to be canceled and reissued in order to update the set of
signals being waited for.</p>
</blockquote>

<h4><a name="tag_03_699_09"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_699_10"></a>SEE ALSO</h4>

<blockquote>
<p><a href="xsh_chap02_08.html#tag_02_08_01"><i>Realtime Signals</i></a> , <a href="pause.html"><i>pause</i>()</a> , <a href=
"pthread_sigmask.html"><i>pthread_sigmask</i>()</a> , <a href="sigaction.html"><i>sigaction</i>()</a> , <a href=
"sigpending.html"><i>sigpending</i>()</a> , <a href="sigsuspend.html"><i>sigsuspend</i>()</a> , <a href=
"sigwait.html"><i>sigwait</i>()</a> , the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../basedefs/signal.h.html"><i>&lt;signal.h&gt;</i></a>, <a href="../basedefs/time.h.html"><i>&lt;time.h&gt;</i></a></p>
</blockquote>

<h4><a name="tag_03_699_11"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 5. Included for alignment with the POSIX Realtime Extension and the POSIX Threads Extension.</p>
</blockquote>

<h4><a name="tag_03_699_12"></a>Issue 6</h4>

<blockquote>
<p>These functions are marked as part of the Realtime Signals Extension option.</p>

<p>The Open Group Corrigendum U035/3 is applied. The SYNOPSIS of the <i>sigwaitinfo</i>() function has been corrected so that the
second argument is of type <b>siginfo_t *</b>.</p>

<p>The [ENOSYS] error condition has been removed as stubs need not be provided if an implementation does not support the Realtime
Signals Extension option.</p>

<p>The DESCRIPTION is updated for alignment with IEEE&nbsp;Std&nbsp;1003.1j-2000 by specifying that the CLOCK_MONOTONIC clock, if
supported, is used to measure timeout intervals.</p>

<p>The <b>restrict</b> keyword is added to the <i>sigtimedwait</i>() and <i>sigwaitinfo</i>() prototypes for alignment with the
ISO/IEC&nbsp;9899:1999 standard.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>