326 lines
9.2 KiB
HTML
326 lines
9.2 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>wait()--Wait for Child Process to End</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 html 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>wait()--Wait for Child Process to End</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
Syntax<br>
|
||
|
|
<pre>
|
||
|
|
#include <sys/types.h>
|
||
|
|
#include <sys/wait.h>
|
||
|
|
|
||
|
|
pid_t wait(int <em>*stat_loc</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>wait()</strong> function suspends processing until a child
|
||
|
|
process has ended. The calling thread will suspend processing until status
|
||
|
|
information is available for a child process that ended. A suspended <strong>
|
||
|
|
wait()</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>wait()</strong> is successful, status information about
|
||
|
|
how the child process ended (for example, whether the process ended <em>
|
||
|
|
*stat_loc</em>.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<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.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<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 <em>*stat_loc</em>. When <strong>
|
||
|
|
wait()</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:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<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" nowrap><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"><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>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<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>wait()</strong> was successful. The value
|
||
|
|
returned indicates the process ID of the child process whose status information
|
||
|
|
*stat_loc.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>-1</em></td>
|
||
|
|
<td align="left" valign="top"><strong>wait()</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>wait()</strong> is not successful, <em>errno</em> usually
|
||
|
|
indicates one of the following errors. Under some conditions, <em>errno</em>
|
||
|
|
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>[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>[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:<br>
|
||
|
|
<br>
|
||
|
|
<ul>
|
||
|
|
<li>ENDJOB OPTION(*IMMED)</li>
|
||
|
|
|
||
|
|
<li>ENDJOB OPTION(*CNTRLD) and delay time was reached</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</li>
|
||
|
|
|
||
|
|
<li>WEXCEPTNUMBER(<em>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="waitpid.htm">waitpid()</a>--Wait for Specific Child Process<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>
|
||
|
|
|