<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.pcntl-wait" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>pcntl_wait</refname>
  <refpurpose>Waits on or returns the status of a forked child</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>pcntl_wait</methodname>
   <methodparam><type>int</type><parameter role="reference">status</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter role="reference">resource_usage</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>
  <para>
   The wait function suspends execution of the current process until a
   child has exited, or until a signal is delivered whose action is to
   terminate the current process or to call a signal handling function.  If a
   child has already exited by the time of the call (a so-called "zombie"
   process), the function returns immediately.  Any system resources used by
   the child are freed.  Please see your system's wait(2) man page for
   specific details as to how wait works on your system.
  </para>
  <note>
   <para>
    This function is equivalent to calling <function>pcntl_waitpid</function>
    with a <literal>-1</literal> <parameter>process_id</parameter> and no
    <parameter>flags</parameter>.
   </para>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>status</parameter></term>
     <listitem>
      <para>
       <function>pcntl_wait</function> will store status information
       in the <parameter>status</parameter> parameter which can be
       evaluated using the following functions:
       <function>pcntl_wifexited</function>,
       <function>pcntl_wifstopped</function>,
       <function>pcntl_wifsignaled</function>,
       <function>pcntl_wexitstatus</function>,
       <function>pcntl_wtermsig</function> and
       <function>pcntl_wstopsig</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       If wait3 is available on your system (mostly BSD-style systems), you can
       provide the optional <parameter>flags</parameter> parameter.  If this
       parameter is not provided, wait will be used for the system call.  If
       wait3 is not available, providing a value for <parameter>flags</parameter>
       will have no effect. The value of <parameter>flags</parameter>
       is the value of zero or more of the following two constants
       <literal>OR</literal>'ed together:
       <table>
        <title>Possible values for <parameter>flags</parameter></title>
        <tgroup cols="2">
         <tbody>
          <row>
           <entry><literal>WNOHANG</literal></entry>
           <entry>
            Return immediately if no child has exited.
           </entry>
          </row>
          <row>
           <entry><literal>WUNTRACED</literal></entry>
           <entry>
            Return for children which are stopped, and whose status has
            not been reported.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <function>pcntl_wait</function> returns the process ID of the
   child which exited, -1 on error or zero if WNOHANG was provided as an
   option (on wait3-available systems) and no child was available.
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>pcntl_fork</function></member>
    <member><function>pcntl_signal</function></member>
    <member><function>pcntl_wifexited</function></member>
    <member><function>pcntl_wifstopped</function></member>
    <member><function>pcntl_wifsignaled</function></member>
    <member><function>pcntl_wexitstatus</function></member>
    <member><function>pcntl_wtermsig</function></member>
    <member><function>pcntl_wstopsig</function></member>
    <member><function>pcntl_waitpid</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
