<!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>