<html><head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title></title><style type="text/css">
<!--
.style1 {font-size: 18px;font-weight: bold;font-family: Georgia, "Times New Roman", Times, serif;}
.style2 {font-size: 14px}
a{color:#0000cc;text-decoration:none}
a:visited{color:#0000cc;text-decoration:none}
.style3 {color: #660000}
-->
</style></head>
<body style="margin:0px 0px 0px 0px;">
<table width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td bgcolor="#cccccc"><span class="style1" style="margin-left:5px">sys_waitid <span class="style2">[kernel/exit.c] </span></span></td>
</tr>
<tr>
<td><p style="margin-left:22px;margin-top:0px"><br />
Suspends execution of the current process until the specified child has changed state.<br />
<br />
This system call is similar to <a href="007.html">sys_waitpid</a>, but provides more precise control over which child state changes to wait for.<br />
<br />
A state change is considered to be: the child terminated; the child was stopped by a signal; or the child was resumed by a signal. In the case of a terminated child, performing a wait allows the system to release the resources associated with the child; if a wait is not performed, then terminated the child remains in a "zombie" state (see Remarks below).<br />
<br />
If a child has already changed state, then this call return immediately. Otherwise they block until either a child changes state or a signal handler interrupts the call (assuming that system calls are not automatically restarted using the SA_RESTART flag of <a href="067.html">sys_sigaction</a>). In the remainder of this page, a child whose state has changed and which has not yet been waited upon by one of these system calls is termed <em>waitable</em>. </p>
<p style="margin-left:10px"><strong>Arguments</strong></p>
<table width="100%" border="0" style="margin-left:20px; margin-right:20px">
<tr>
<td width="6%" valign="top"><em>eax</em></td>
<td width="94%">284</td>
</tr>
<tr>
<td valign="top"><em>ebx</em></td>
<td>Child(ren) to wait for. It may be one of the following values:
<table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333">
<tr>
<td><table width="100%" border="0">
<tr>
<td width="7%" valign="top"><code>P_PID</code></td>
<td width="93%"><code>Wait for the child whose process ID matches <em>ecx</em>. </code></td>
</tr>
<tr>
<td valign="top"><code>P_PGID</code></td>
<td><code>Wait for any child whose process group ID matches <em>ecx</em>. </code></td>
</tr>
<tr>
<td valign="top"><code>P_ALL</code></td>
<td><code>Wait for any child; <em>ecx</em> is ignored. </code></td>
</tr>
</table></td>
</tr>
</table></td>
</tr>
<tr>
<td valign="top"><em>ecx</em></td>
<td>PID of the child.</td>
</tr>
<tr>
<td valign="top"><em>edx</em></td>
<td>Pointer to a <em>siginfo</em> structure. <em>siginfo</em> defined as follows:
<table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333">
<tr>
<td><code>struc siginfo <br>
{<br>
.si_signo rd 1<br>
.si_errno rd 1<br>
.si_code rd 1<br>
._kill: ;kill<br>
._timer: ;timer<br>
.__rt: ;_rt<br>
._sigchld: ;sigchld<br>
._sigfault: ;sigfault<br>
._sigpoll: ;sigpoll<br>
._pad rd 29<br>
}</code></td>
</tr>
</table> Where <em>kill</em>, <em>timer</em>, <em>_rt</em>, <em>sigchld</em>, <em>sigfault</em>, and <em>sigpoll</em> defined as follows:
<table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333">
<tr>
<td><p><code>struc kill<br>
{<br>
._pid rd 1<br>
._uid rd 1<br>
}<br>
<br>
</code><code>struc timer<br>
{<br>
._tid rd 1<br>
._overrun rd 1<br>
.sival_int: ;rd 1<br>
.sival_ptr rd 1<br>
._sys_private rd 1<br>
}<br>
<br>
</code><code>struc _rt<br>
{<br>
._pid rd 1<br>
._uid rd 1<br>
.sival_int: ;rd 1<br>
.sival_ptr rd 1<br>
}<br>
<br>
</code><code>struc sigchld<br>
{<br>
._pid rd 1<br>
._uid rd 1<br>
._status rd 1<br>
._utime rd 1<br>
._stime rd 1<br>
}<br>
<br>
</code><code>struc sigfault<br>
{<br>
._addr rd 1<br>
}<br>
<br>
</code><code>struc sigpoll<br>
{<br>
._band rd 1<br>
._fd rd 1<br>
}</code></p></td>
</tr>
</table></td>
</tr>
<tr>
<td valign="top"><em>esi</em></td>
<td>The child state changes to wait for. Specified by bitwsie-or'ing one or more of the following flags:
<br />
<table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333">
<tr>
<td><table width="100%" border="0">
<tr>
<td width="12%" valign="top"><code>WEXITED </code></td>
<td width="88%"><code>Wait for children that have terminated.</code></td>
</tr>
<tr>
<td valign="top"><code>WSTOPPED </code></td>
<td><code>Wait for children that have been stopped by delivery of a signal. </code></td>
</tr>
<tr>
<td valign="top"><code>WCONTINUED </code></td>
<td><code>Wait for (previously stopped) children that have been resumed by delivery of SIGCONT. </code></td>
</tr>
</table></td>
</tr>
</table>
Following flags may additionally be bitwise-or'ed in <em>esi</em>:
<table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333">
<tr>
<td><table width="100%" border="0">
<tr>
<td width="12%" valign="top"><code>WNOHANG </code></td>
<td width="88%"><code>Return immediately if no child has exited. </code></td>
</tr>
<tr>
<td valign="top"><code>WNOWAIT </code></td>
<td><code>Leave the child in a waitable state; a later wait call can be used to again retrieve the child status information. </code></td>
</tr>
</table></td>
</tr>
</table></td>
</tr>
<tr>
<td valign="top"><em>edi</em></td>
<td><span class="style3">*to be documented* </span></td>
</tr>
</table>
<p style="margin-left:10px" ><strong>Return values</strong></p>
<p style="margin-left:22px;margin-right:10px" >If the system call succeeds the return value is the process ID of the child whose state has changed. If WNOHANG was specified and no child(ren) specified by <em>ebx</em> has yet changed state, then 0 is returned. <br />
If the system call fails the return value is one of the following <em>errno</em> values:</p>
<table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333;margin-left:22px;margin-right:22px">
<tr>
<td><table width="100%" border="0">
<tr>
<td width="10%" valign="top"><code>-ECHILD</code></td>
<td width="90%"><code>The process specified by <em>ebx </em>does not exist or is not a child of the calling process. (This can happen for one's own child if the action for SIGCHLD is set to SIG_IGN.)</code></td>
</tr>
<tr>
<td valign="top"><code>-EINTR </code></td>
<td><code>WNOHANG was not set and an unblocked signal or a SIGCHLD was caught. </code></td>
</tr>
<tr>
<td valign="top"><code>-EINVAL </code></td>
<td><code><em>edx</em> argument was invalid.</code></td>
</tr>
</table></td>
</tr>
</table>
<p style="margin-left:10px"><strong>Remarks</strong></p>
<p style="margin-left:22px">A child that terminates, but has not been waited for becomes a "zombie". The kernel maintains a minimal set of information about the zombie process (PID, termination status, resource usage information) in order to allow the parent to later perform a wait to obtain information about the child. As long as a zombie is not removed from the system via a wait, it will consume a slot in the kernel process table, and if this table fills, it will not be possible to create further processes. If a parent process terminates, then its "zombie" children (if any) are adopted by <em>init</em> (<em>man 8 init</em>), which automatically performs a wait to remove the zombies.<br />
<br />
POSIX.1-2001 specifies that if the disposition of SIGCHLD is set to SIG_IGN or the SA_NOCLDWAIT flag is set for SIGCHLD (see<code><a href="067.html"> sys_sigaction</a></code>), then children that terminate do not become zombies and a call to <a href="114.html">sys_wait4</a> or sys_waitpid will block until all children have terminated, and then fail with<em> - </em>ECHILD. (The original POSIX standard left the behaviour of setting SIGCHLD to SIG_IGN unspecified.) Linux 2.6 conforms to this specification. However, Linux 2.4 (and earlier) does not: if a <a href="114.html">sys_wait4</a> or sys_waitpid call is made while SIGCHLD is being ignored, the call behaves just as though SIGCHLD were not being ignored, that is, the call blocks until the next child terminates and then returns the process ID and status of that child. <br />
<br />
In the Linux kernel, a kernel-scheduled thread is not a distinct construct from a process. Instead, a thread is simply a process that is created using the Linux-unique <a href="120.html">sys_clone</a> system call; other routines such as the portable <em>pthread_create</em> (<em>man 3 pthread_create</em>) call are implemented using <a href="120.html">sys_clone</a>. Before Linux 2.4, a thread was just a special case of a process, and as a consequence one thread could not wait on the children of another thread, even when the latter belongs to the same thread group. However, POSIX prescribes such functionality, and since Linux 2.4 a thread can, and by default will, wait on children of other threads in the same thread group.<br />
<br />
The following Linux-specific options are for use with children created using <a href="120.html">sys_clone</a>:</p>
<table width="100%" border="0" style="border:dashed;border-bottom-width:1px;border-left-width:1px;border-right-width:1px;border-top-width:1px;border-color:#333333;margin-left:22px;margin-right:22px">
<tr>
<td><table width="100%" border="0">
<tr>
<td width="10%" valign="top"><code>__WCLONE</code></td>
<td width="90%"><code>Wait for "clone" children only. If omitted then wait for "non-clone" children only. (A "clone" child is one which delivers no signal, or a signal other than SIGCHLD to its parent upon termination.) This option is ignored if __WALL is also specified.</code></td>
</tr>
<tr>
<td valign="top"><code>__WALL</code></td>
<td><code>Wait for all children, regardless of type ("clone" or "non-clone"). </code></td>
</tr>
<tr>
<td valign="top"><code>__WNOTHREAD</code></td>
<td><code>Do not wait for children of other threads in the same thread group. </code></td>
</tr>
</table></td>
</tr>
</table>
<p style="margin-left:10px"><strong>Compatibility</strong></p>
<p style="margin-left:22px">Available since 2.6.9.</p></td>
</tr>
</table>
</body></html>