wait.html

IEEE 1003.1-2003, Single Unix Specification v3

<dd>The function was interrupted by a signal. The value of the location pointed to by <i>stat_loc</i> is undefined.</dd>
</dl>

<p>The <i>waitpid</i>() function shall fail if:</p>

<dl compact>
<dt>[ECHILD]</dt>

<dd>The process specified by <i>pid</i> does not exist or is not a child of the calling process, or the process group specified by
<i>pid</i> does not exist or does not have any member process that is a child of the calling process.</dd>

<dt>[EINTR]</dt>

<dd>The function was interrupted by a signal. The value of the location pointed to by <i>stat_loc</i> is undefined.</dd>

<dt>[EINVAL]</dt>

<dd>The <i>options</i> argument is not valid.</dd>
</dl>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_03_822_06"></a>EXAMPLES</h4>

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

<h4><a name="tag_03_822_07"></a>APPLICATION USAGE</h4>

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

<h4><a name="tag_03_822_08"></a>RATIONALE</h4>

<blockquote>
<p>A call to the <i>wait</i>() or <i>waitpid</i>() function only returns <i>status</i> on an immediate child process of the calling
process; that is, a child that was produced by a single <a href="../functions/fork.html"><i>fork</i>()</a> call (perhaps followed
by an <i><a href="../functions/exec.html">exec</a></i> or other function calls) from the parent. If a child produces grandchildren
by further use of <a href="../functions/fork.html"><i>fork</i>()</a>, none of those grandchildren nor any of their descendants
affect the behavior of a <i>wait</i>() from the original parent process. Nothing in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001
prevents an implementation from providing extensions that permit a process to get <i>status</i> from a grandchild or any other
process, but a process that does not use such extensions must be guaranteed to see <i>status</i> from only its direct children.</p>

<p>The <i>waitpid</i>() function is provided for three reasons:</p>

<ol>
<li>
<p>To support job control</p>
</li>

<li>
<p>To permit a non-blocking version of the <i>wait</i>() function</p>
</li>

<li>
<p>To permit a library routine, such as <a href="../functions/system.html"><i>system</i>()</a> or <a href=
"../functions/pclose.html"><i>pclose</i>()</a>, to wait for its children without interfering with other terminated children for
which the process has not waited</p>
</li>
</ol>

<p>The first two of these facilities are based on the <i>wait3</i>() function provided by 4.3 BSD. The function uses the
<i>options</i> argument, which is equivalent to an argument to <i>wait3</i>(). The WUNTRACED flag is used only in conjunction with
job control on systems supporting job control. Its name comes from 4.3 BSD and refers to the fact that there are two types of
stopped processes in that implementation: processes being traced via the <i>ptrace</i>() debugging facility and (untraced)
processes stopped by job control signals. Since <i>ptrace</i>() is not part of this volume of IEEE&nbsp;Std&nbsp;1003.1-2001, only
the second type is relevant. The name WUNTRACED was retained because its usage is the same, even though the name is not intuitively
meaningful in this context.</p>

<p>The third reason for the <i>waitpid</i>() function is to permit independent sections of a process to spawn and wait for children
without interfering with each other. For example, the following problem occurs in developing a portable shell, or command
interpreter:</p>

<pre>
<tt>stream = popen("/bin/true");
(void) system("sleep 100");
(void) pclose(stream);
</tt>
</pre>

<p>On all historical implementations, the final <a href="../functions/pclose.html"><i>pclose</i>()</a> fails to reap the
<i>wait</i>() <i>status</i> of the <a href="../functions/popen.html"><i>popen</i>()</a>.</p>

<p>The status values are retrieved by macros, rather than given as specific bit encodings as they are in most historical
implementations (and thus expected by existing programs). This was necessary to eliminate a limitation on the number of signals an
implementation can support that was inherent in the traditional encodings. This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 does
require that a <i>status</i> value of zero corresponds to a process calling <i>_exit</i>(0), as this is the most common encoding
expected by existing programs. Some of the macro names were adopted from 4.3 BSD.</p>

<p>These macros syntactically operate on an arbitrary integer value. The behavior is undefined unless that value is one stored by a
successful call to <i>wait</i>() or <i>waitpid</i>() in the location pointed to by the <i>stat_loc</i> argument. An early proposal
attempted to make this clearer by specifying each argument as *<i>stat_loc</i> rather than <i>stat_val</i>. However, that did not
follow the conventions of other specifications in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 or traditional usage. It also could
have implied that the argument to the macro must literally be *<i>stat_loc</i>; in fact, that value can be stored or passed as an
argument to other functions before being interpreted by these macros.</p>

<p>The extension that affects <i>wait</i>() and <i>waitpid</i>() and is common in historical implementations is the <i>ptrace</i>()
function. It is called by a child process and causes that child to stop and return a <i>status</i> that appears identical to the
<i>status</i> indicated by WIFSTOPPED. The <i>status</i> of <i>ptrace</i>() children is traditionally returned regardless of the
WUNTRACED flag (or by the <i>wait</i>() function). Most applications do not need to concern themselves with such extensions because
they have control over what extensions they or their children use. However, applications, such as command interpreters, that invoke
arbitrary processes may see this behavior when those arbitrary processes misuse such extensions.</p>

<p>Implementations that support <b>core</b> file creation or other implementation-defined actions on termination of some processes
traditionally provide a bit in the <i>status</i> returned by <i>wait</i>() to indicate that such actions have occurred.</p>

<p>Allowing the <i>wait</i>() family of functions to discard a pending SIGCHLD signal that is associated with a successfully
waited-for child process puts them into the <a href="../functions/sigwait.html"><i>sigwait</i>()</a> and <a href=
"../functions/sigwaitinfo.html"><i>sigwaitinfo</i>()</a> category with respect to SIGCHLD.</p>

<p>This definition allows implementations to treat a pending SIGCHLD signal as accepted by the process in <i>wait</i>(), with the
same meaning of &quot;accepted&quot; as when that word is applied to the <a href="../functions/sigwait.html"><i>sigwait</i>()</a> family of
functions.</p>

<p>Allowing the <i>wait</i>() family of functions to behave this way permits an implementation to be able to deal precisely with
SIGCHLD signals.</p>

<p>In particular, an implementation that does accept (discard) the SIGCHLD signal can make the following guarantees regardless of
the queuing depth of signals in general (the list of waitable children can hold the SIGCHLD queue):</p>

<ol>
<li>
<p>If a SIGCHLD signal handler is established via <a href="../functions/sigaction.html"><i>sigaction</i>()</a> without the
SA_RESETHAND flag, SIGCHLD signals can be accurately counted; that is, exactly one SIGCHLD signal will be delivered to or accepted
by the process for every child process that terminates.</p>
</li>

<li>
<p>A single <i>wait</i>() issued from a SIGCHLD signal handler can be guaranteed to return immediately with status information for
a child process.</p>
</li>

<li>
<p>When SA_SIGINFO is requested, the SIGCHLD signal handler can be guaranteed to receive a non-NULL pointer to a <b>siginfo_t</b>
structure that describes a child process for which a wait via <i>waitpid</i>() or <a href=
"../functions/waitid.html"><i>waitid</i>()</a> will not block or fail.</p>
</li>

<li>
<p>The <a href="../functions/system.html"><i>system</i>()</a> function will not cause a process' SIGCHLD handler to be called as a
result of the <a href="../functions/fork.html"><i>fork</i>()</a>/ <i><a href="../functions/exec.html">exec</a></i> executed within
<a href="../functions/system.html"><i>system</i>()</a> because <a href="../functions/system.html"><i>system</i>()</a> will accept
the SIGCHLD signal when it performs a <i>waitpid</i>() for its child process. This is a desirable behavior of <a href=
"../functions/system.html"><i>system</i>()</a> so that it can be used in a library without causing side effects to the application
linked with the library.</p>
</li>
</ol>

<p>An implementation that does not permit the <i>wait</i>() family of functions to accept (discard) a pending SIGCHLD signal
associated with a successfully waited-for child, cannot make the guarantees described above for the following reasons:</p>

<dl compact>
<dt>Guarantee #1</dt>

<dd><br>
Although it might be assumed that reliable queuing of all SIGCHLD signals generated by the system can make this guarantee, the
counter-example is the case of a process that blocks SIGCHLD and performs an indefinite loop of <a href=
"../functions/fork.html"><i>fork</i>()</a>/ <i>wait</i>() operations. If the implementation supports queued signals, then
eventually the system will run out of memory for the queue. The guarantee cannot be made because there must be some limit to the
depth of queuing.</dd>

<dt>Guarantees #2 and #3</dt>

<dd><br>
These cannot be guaranteed unless the <i>wait</i>() family of functions accepts the SIGCHLD signal. Otherwise, a <a href=
"../functions/fork.html"><i>fork</i>()</a>/ <i>wait</i>() executed while SIGCHLD is blocked (as in the <a href=
"../functions/system.html"><i>system</i>()</a> function) will result in an invocation of the handler when SIGCHLD is unblocked,
after the process has disappeared.</dd>

<dt>Guarantee #4</dt>

<dd><br>
Although possible to make this guarantee, <a href="../functions/system.html"><i>system</i>()</a> would have to set the SIGCHLD
handler to SIG_DFL so that the SIGCHLD signal generated by its <a href="../functions/fork.html"><i>fork</i>()</a> would be
discarded (the SIGCHLD default action is to be ignored), then restore it to its previous setting. This would have the undesirable
side effect of discarding all SIGCHLD signals pending to the process.</dd>
</dl>
</blockquote>

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

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

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

<blockquote>
<p><a href="exec.html"><i><a href="../functions/exec.html">exec</a></i>()</a> , <a href="exit.html"><i>exit</i>()</a> , <a href=
"fork.html"><i>fork</i>()</a> , <a href="waitid.html"><i>waitid</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/sys/wait.h.html"><i>&lt;sys/wait.h&gt;</i></a></p>
</blockquote>

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

<blockquote>
<p>First released in Issue 1. Derived from Issue 1 of the SVID.</p>
</blockquote>

<h4><a name="tag_03_822_12"></a>Issue 5</h4>

<blockquote>
<p>The DESCRIPTION is updated for alignment with the POSIX Threads Extension.</p>
</blockquote>

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

<blockquote>
<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>

<ul>
<li>
<p>The requirement to include <a href="../basedefs/sys/types.h.html"><i>&lt;sys/types.h&gt;</i></a> has been removed. Although <a
href="../basedefs/sys/types.h.html"><i>&lt;sys/types.h&gt;</i></a> was required for conforming implementations of previous POSIX
specifications, it was not required for UNIX applications.</p>
</li>
</ul>

<p>The following changes were made to align with the IEEE&nbsp;P1003.1a draft standard:</p>

<ul>
<li>
<p>The processing of the SIGCHLD signal and the [ECHILD] error is clarified.</p>
</li>
</ul>

<p>The semantics of WIFSTOPPED(<i>stat_val</i>), WIFEXITED(<i>stat_val</i>), and WIFSIGNALED(<i>stat_val</i>) are defined with
respect to <a href="../functions/posix_spawn.html"><i>posix_spawn</i>()</a> or <a href=
"../functions/posix_spawnp.html"><i>posix_spawnp</i>()</a> for alignment with IEEE&nbsp;Std&nbsp;1003.1d-1999.</p>

<p>The DESCRIPTION is updated 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>