399 lines
12 KiB
HTML
399 lines
12 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>waitpid()--Wait for Specific Child Process</title>
|
|
<!-- Begin Header Records ========================================== -->
|
|
<!-- UNIX11 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2DCIJB at -->
|
|
<!-- RCHVMW2 on 1 Jun 1999 at 16:14:12 -->
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- Edited by Kersten Feb 02 -->
|
|
<!-- This file has undergone error condition cleanup JULY 2002 by JET -->
|
|
<!--End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
|
|
<!-- Java sync-link -->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<a name="Top_Of_Page"></a>
|
|
|
|
<h2>waitpid()--Wait for Specific Child Process</h2>
|
|
|
|
<div class="box" style="width: 60%;">
|
|
<br>
|
|
Syntax<br>
|
|
<pre>
|
|
#include <sys/types.h>
|
|
#include <sys/wait.h>
|
|
|
|
pid_t waitpid(pid_t <em>pid</em>, int <em>*stat_loc</em>, int <em>options</em>);
|
|
</pre>
|
|
|
|
<br>
|
|
Service Program Name: QP0ZSPWN<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The <strong>waitpid()</strong> function allows the calling thread to obtain
|
|
status information for one of its child processes. The calling thread suspends
|
|
processing until status information is available for the specified child
|
|
process, if the <em>options</em> argument is 0. A suspended <strong>
|
|
waitpid()</strong> function call can be interrupted by the delivery of a signal
|
|
whose action is either to run a signal-catching function or to terminate the
|
|
process. When <strong>waitpid()</strong> is successful, status information
|
|
about how the child process ended (for example, whether the process ended
|
|
normally) is stored in the location specified by stat_loc.</p>
|
|
|
|
<p>The <strong>waitpid()</strong> function behaves the same as <strong>
|
|
wait()</strong> if the <em>pid</em> argument is (pid_t)-1 and the <em>
|
|
options</em> argument is 0.</p>
|
|
|
|
<br>
|
|
<h3><strong>Parameters</strong></h3>
|
|
|
|
<dl>
|
|
<dt><strong><em>pid</em></strong></dt>
|
|
|
|
<dd>(Input) A process ID or a process group ID to identify the child process or
|
|
processes on which <strong>waitpid()</strong> should operate.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong><em>stat_loc</em></strong></dt>
|
|
|
|
<dd>(Input) Pointer to an area where status information about how the child
|
|
process ended is to be placed.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong><em>options</em></strong></dt>
|
|
|
|
<dd>(Input) An integer field containing flags that define how <strong>
|
|
waitpid()</strong> should operate.</dd>
|
|
</dl>
|
|
|
|
<p>The <em>pid</em> argument specifies a set of child processes for which
|
|
status is requested. The <strong>waitpid()</strong> function only returns the
|
|
status of a child process from the following set:</p>
|
|
|
|
<ul>
|
|
<li>If <em>pid</em> is equal to (pid_t)-1, status is requested for any child
|
|
process. In this respect, <strong>waitpid()</strong> is then equivalent to
|
|
<strong>wait()</strong>.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If <em>pid</em> is greater than (pid_t)0, it specifies the process ID of a
|
|
single child process for which status is requested.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If <em>pid</em> is (pid_t)0, status is requested for any child process
|
|
whose process group ID is equal to that of the calling thread.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If <em>pid</em> is less than (pid_t)-1, status is requested for any child
|
|
process whose process group ID is equal to the absolute value of <em>
|
|
pid</em>.</li>
|
|
</ul>
|
|
|
|
<p>The status referenced by the <em>stat_loc</em> argument is interpreted using
|
|
macros defined in the <strong><sys/wait.h></strong> header file. The
|
|
macros use an argument <em>stat_val</em>, which is the integer value pointed to
|
|
by <em>stat_loc</em>. When <strong>waitpid()</strong> returns with a valid
|
|
process ID (pid), the macros analyze the status referenced by the <em>
|
|
stat_loc</em> argument. The macros are as follows:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="25 75" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>WIFEXITED(stat_val)</em></td>
|
|
<td align="left" valign="top">Evaluates to a nonzero value if the status was
|
|
returned for a child process that ended normally.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>WEXITSTATUS(stat_val)</em></td>
|
|
<td align="left" valign="top">If the value of the WIFEXITED(<em>stat_val</em>)
|
|
is nonzero, evaluates to the low-order 8 bits of the status argument that the
|
|
child process passed to <strong>exit()</strong>, or to the value the child
|
|
process returned from <strong>main()</strong>.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>WIFSIGNALED(stat_val)</em></td>
|
|
<td align="left" valign="top">Evaluates to a nonzero value if the status was
|
|
returned for a child process that ended because of the receipt of a terminating
|
|
signal that was not caught by the process.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>WTERMSIG(stat_val)</em></td>
|
|
<td align="left" valign="top">If the value of WIFSIGNALED(<em>stat_val</em>) is
|
|
nonzero, evaluates to the number of the signal that caused the child process to
|
|
end.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>WIFStopPED(stat_val)</em></td>
|
|
<td align="left" valign="top">Evaluates to a nonzero value if the status was
|
|
returned for a child process that is currently stopped.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>WStopSIG(stat_val)</em></td>
|
|
<td align="left" valign="top">If the value of the WIFStopPED(<em>stat_val</em>)
|
|
is nonzero, evaluates to the number of the signal that caused the child process
|
|
to stop.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" nowrap><em>WIFEXCEPTION(stat_val)</em></td>
|
|
<td align="left" valign="top">Evaluates to a nonzero value if the status was
|
|
returned for a child process that ended because of an error condition.
|
|
|
|
<p><strong>Note</strong>: The WIFEXCEPTION macro is unique to the i5/OS
|
|
implementation. See the <a href="#USAGE">Usage Notes</a>.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" nowrap><em>WEXCEPTNUMBER(stat_val)</em></td>
|
|
<td align="left" valign="top">If the value of the
|
|
WIFEXCEPTION(<em>stat_val</em>) is nonzero, this macro evaluates to the last
|
|
i5/OS exception number related to the child process.
|
|
|
|
<p><strong>Note</strong>: The WEXCEPTNUMBER macro is unique to the i5/OS
|
|
implementation. See the <a href="#USAGE">Usage Notes</a>.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The <em>options</em> argument can be set to either 0 or WNOHANG. WNOHANG
|
|
indicates that the <strong>waitpid()</strong> function should not suspend
|
|
processing of the calling thread if status is not immediately available for one
|
|
of the child processes specified by <em>pid</em>. If WNOHANG is specified and
|
|
no child process is immediately available, <strong>waitpid()</strong> returns
|
|
0.</p>
|
|
|
|
<br>
|
|
<h3>Authorities</h3>
|
|
|
|
<p>None</p>
|
|
|
|
<br>
|
|
<h3>Return Value</h3>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="10 90" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>value</em></td>
|
|
<td align="left" valign="top"><strong>waitpid()</strong> was successful. The
|
|
value returned indicates the process ID of the child process whose status
|
|
information was recorded in the storage pointed to by <em>stat_loc</em>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">WNOHANG was specified on the <em>options</em>
|
|
parameter, but no child process was immediately available.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>-1</em></td>
|
|
<td align="left" valign="top"><strong>waitpid()</strong> was not successful.
|
|
The <em>errno</em> value is set to indicate the error.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
<h3>Error Conditions</h3>
|
|
|
|
<p>If <strong>waitpid()</strong> is not successful, <em>errno</em> usually
|
|
indicates one of the following errors. Under some conditions, errno could
|
|
indicate an error other than those listed here.</p>
|
|
|
|
<dl>
|
|
|
|
<dt><em>[ECHILD]</em></dt>
|
|
<dd><p>Calling process has no remaining child processes
|
|
on which wait operation can be performed.</p>
|
|
</dd>
|
|
|
|
|
|
|
|
<dt><em>[EINVAL]</em></dt>
|
|
<dd><p>The value specified for the argument is not
|
|
correct.</p>
|
|
|
|
<p>A function was passed incorrect argument values, or an operation was
|
|
attempted on an object and the operation specified is not supported for that
|
|
type of object.</p>
|
|
|
|
<p>An argument value is not valid, out of range, or NULL.</p>
|
|
</dd>
|
|
|
|
|
|
|
|
<dt><em>[EFAULT]</em></dt>
|
|
<dd><p>The address used for an argument is not correct. </p>
|
|
|
|
<p>In attempting to use an argument in a call, the system detected an address
|
|
that is not valid.</p>
|
|
|
|
<p>While attempting to access a parameter passed to this function, the system
|
|
detected an address that is not valid.</p>
|
|
</dd>
|
|
|
|
|
|
|
|
<dt><em>[EINTR]</em></dt>
|
|
<dd><p>Interrupted function call.</p>
|
|
</dd>
|
|
|
|
|
|
|
|
<dt><em>[EOPNOTSUPP]</em></dt>
|
|
<dd><p>Operation not supported. </p>
|
|
|
|
<p>The operation, though supported in general, is not supported for the
|
|
requested object or the requested arguments.</p>
|
|
</dd>
|
|
|
|
|
|
|
|
<dt><em>[EUNKNOWN]</em></dt>
|
|
<dd><p>Unknown system state.</p>
|
|
|
|
<p>The operation failed because of an unknown system state. See any messages in
|
|
the job log and correct any errors that are indicated, then retry the
|
|
operation.</p>
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<br>
|
|
<h3><a name="USAGE"><strong>Usage Notes</strong></a></h3>
|
|
|
|
<ol>
|
|
<li>The WIFEXCEPTION macro is unique to the i5/OS implementation. This macro
|
|
can be used to determine whether the child process has ended because of an
|
|
exception. When WIFEXCEPTION returns a nonzero value, the value returned by the
|
|
WEXCEPTNUMBER macro corresponds to the last i5/OS exception number related to
|
|
the child process.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>When a child process ends because of an exception, the ILE C run-time
|
|
library catches and handles the original exception. The value returned by
|
|
WEXCEPTNUMBER indicates that the exception was <strong>CEE9901</strong>. This
|
|
is a common exception ID. If you want to determine the original exception that
|
|
ended the child process, look at the job log for the child process.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If the child process is ended by any of the following:
|
|
|
|
<ul>
|
|
<li>ENDJOB OPTION(*IMMED),</li>
|
|
|
|
<li>ENDJOB OPTION(*CNTRLD) and delay time was reached, or</li>
|
|
|
|
<li>Debugging a child process (environment variable QIBM_CHILD_JOB_SNDINQMSG is
|
|
used) and the resulting CPAA980 *INQUIRY message is replied to using C,</li>
|
|
</ul>
|
|
|
|
<p>then the parent's <strong>wait()</strong> <em>stat_loc</em> value indicates
|
|
that:</p>
|
|
|
|
<ul>
|
|
<li>WIFEXCEPTION(<em>stat_val</em>) evaluates to a nonzero value, and</li>
|
|
|
|
<li><em>WEXCEPTNUMBER(stat_val)</em> evaluates to zero.</li>
|
|
</ul>
|
|
</li>
|
|
</ol>
|
|
|
|
<br>
|
|
<h3>Related Information</h3>
|
|
|
|
<ul>
|
|
<li>The <<strong>sys/types.h</strong>> file (see <a href="unix13.htm">
|
|
Header Files for UNIX-Type Functions</a>)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The <<strong>sys/wait.h</strong>> file (see <a href="unix13.htm">
|
|
Header Files for UNIX-Type Functions</a>)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="spawn.htm">spawn()</a>--Spawn Process<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="spawnp.htm">spawnp()</a>--Spawn Process with Path<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="wait.htm">wait()</a>--Wait for Child Process to End<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><A href="unix5a2.htm#sigconcepts">Signal concepts</a></li>
|
|
</ul>
|
|
|
|
<br>
|
|
<h3>Example</h3>
|
|
|
|
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
|
|
for information pertaining to code examples.</p>
|
|
|
|
<p>For an example of using this function, see <a href="../apiref/apiexuspro.htm">Using the Spawn Process and Wait
|
|
for Child Process APIs</a> in API examples.</p>
|
|
|
|
<br>
|
|
<hr>
|
|
API introduced: V3R6
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|