pcntl-waitid.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.pcntl-waitid" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>pcntl_waitid</refname>
  <refpurpose>Waits for a child process to change state</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>pcntl_waitid</methodname>
   <methodparam choice="opt"><type>int</type><parameter>idtype</parameter><initializer><constant>P_ALL</constant></initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>id</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter role="reference">info</parameter><initializer>[]</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>WEXITED</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   Obtains status information pertaining to termination, stop, and/or continue
   events in one of the caller's child processes.
  </para>

  <para>
   Unless <constant>WNOHANG</constant> flag is passed, the calling process will
   become blocked until an error occurs, or status information becomes
   available that satisfies all of the following:
   <itemizedlist>
    <listitem>
     <simpara>
      The status information is from one of the child processes in the set of
      child processes specified by the <parameter>idtype</parameter> and
      <parameter>id</parameter> arguments.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      The state change in the status information matches one of the state change
      flags set in the <parameter>flags</parameter> argument.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   If matching status information is available prior to the call to
   <function>pcntl_waitid</function>, return shall be immediate. If matching
   status information is available for two or more child processes, the order
   in which their status is reported is unspecified.
  </para>

  <note>
   <para>
    This documentation covers the POSIX specification of the
    <literal>waitid</literal> function, along with some additional parameters
    specific to implementations on Linux, NetBSD and FreeBSD. Please see your
    system's <literal>waitid(2)</literal> man page for specific details as to
    how <literal>waitid</literal> works on your system.
   </para>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>idtype</parameter></term>
    <term><parameter>id</parameter></term>
    <listitem>
     <simpara>
      The <parameter>idtype</parameter> and <parameter>id</parameter> arguments
      are used to specify which children to wait for.
     </simpara>
     <table>
      <title>POSIX standard <parameter>idtype</parameter> and <parameter>id</parameter> arguments</title>
      <tgroup cols="2">
       <tbody>
        <row>
         <entry>If <parameter>idtype</parameter> is <literal>P_ALL</literal></entry>
         <entry>
          wait for any child process, <parameter>id</parameter> is ignored.
         </entry>
        </row>
        <row>
         <entry>If <parameter>idtype</parameter> is <literal>P_PID</literal></entry>
         <entry>
          wait for the child with process ID equal to <parameter>id</parameter>.
         </entry>
        </row>
        <row>
         <entry>If <parameter>idtype</parameter> is <literal>P_PGID</literal></entry>
         <entry>
          wait for any child with process group ID equal to <parameter>id</parameter>.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
     <table>
      <title>Linux specific <parameter>idtype</parameter> and <parameter>id</parameter> arguments</title>
      <tgroup cols="2">
       <tbody>
        <row>
         <entry>If <parameter>idtype</parameter> is <literal>P_PIDFD</literal> (since Linux 5.4)</entry>
         <entry>
          wait for the child referred to by the PID file descriptor specified in
          <parameter>id</parameter>.
          (See the Linux <literal>pidfd_open(2)</literal> man page for further
          information on PID file descriptors.)
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
     <table>
      <title>NetBSD and FreeBSD specific <parameter>idtype</parameter> and <parameter>id</parameter> arguments</title>
      <tgroup cols="2">
       <tbody>
        <row>
         <entry>
          If <parameter>idtype</parameter> is <literal>P_UID</literal>
         </entry>
         <entry>
          wait for processes whose effective user ID is equal to
          <parameter>id</parameter>.
         </entry>
        </row>
        <row>
         <entry>
          If <parameter>idtype</parameter> is <literal>P_GID</literal>
         </entry>
         <entry>
          wait for processes whose effective group ID is equal to
          <parameter>id</parameter>.
         </entry>
        </row>
        <row>
         <entry>
          If <parameter>idtype</parameter> is <literal>P_SID</literal>
         </entry>
         <entry>
          wait for processes whose session ID is equal to
          <parameter>id</parameter>.
          If the child process started its own session, its session ID will be
          the same as its process ID. Otherwise the session ID of a child
          process will match the caller's session ID.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
     <table>
      <title>FreeBSD specific <parameter>idtype</parameter> and <parameter>id</parameter> arguments</title>
      <tgroup cols="2">
       <tbody>
        <row>
         <entry>
          If <parameter>idtype</parameter> is <literal>P_JAILID</literal>
         </entry>
         <entry>
          wait for processes within a jail whose jail identifier is equal to
          <parameter>id</parameter>.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>info</parameter></term>
    <listitem>
     <para>
      The <parameter>info</parameter> parameter is set to an array
      containing information about the signal.
     </para>
     <para>
      <parameter>info</parameter> array may contain the following keys:
      <simplelist>
       <member><literal>signo</literal>: Signal number</member>
       <member><literal>errno</literal>: System error number</member>
       <member><literal>code</literal>: Signal code</member>
       <member><literal>status</literal>: Exit value or signal</member>
       <member><literal>pid</literal>: Sending process ID</member>
       <member><literal>uid</literal>: Real user ID of sending process</member>
       <member><literal>utime</literal>: User time consumed</member>
       <member><literal>stime</literal>: System time consumed</member>
      </simplelist>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>flags</parameter></term>
    <listitem>
     <para>
      The value of <parameter>flags</parameter> is the value of zero or more of
      the following constants OR'ed together:
      <table>
       <title>possible values for <parameter>flags</parameter></title>
       <tgroup cols="2">
        <tbody>
         <row>
          <entry><constant>WCONTINUED</constant></entry>
          <entry>
           Status shall be returned for any continued child process whose
           status either has not been reported since it continued from a job
           control stop or has been reported only by calls to
           <function>pcntl_waitid</function> with the
           <constant>WNOWAIT</constant> flag set.
          </entry>
         </row>
         <row>
          <entry><constant>WEXITED</constant></entry>
          <entry>
           Wait for processes that have exited.
          </entry>
         </row>
         <row>
          <entry><constant>WNOHANG</constant></entry>
          <entry>
           Do not hang if no status is available; return immediately.
          </entry>
         </row>
         <row>
          <entry><constant>WNOWAIT</constant></entry>
          <entry>
           Keep the process whose status is returned in
           <parameter>info</parameter> in a waitable state. This shall not
           affect the state of the process; the process may be waited for again
           after this call completes.
          </entry>
         </row>
         <row>
          <entry><constant>WSTOPPED</constant></entry>
          <entry>
           Status shall be returned for any child that has stopped upon receipt
           of a signal, and whose status either has not been reported since it
           stopped or has been reported only by calls to
           <function>pcntl_waitid</function> with the
           <constant>WNOWAIT</constant> flag set.
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <function>pcntl_waitid</function> returns &true; if
   <constant>WNOHANG</constant> was specified and status is not available for
   any process specified by <parameter>idtype</parameter> and
   <parameter>id</parameter>.
  </para>

  <para>
   <function>pcntl_waitid</function> returns &true; due to the change of state
   of one of its children.
  </para>

  <para>
   Otherwise, &false; is returned and <function>pcntl_get_last_error</function>
   can be used to get the <literal>errno</literal> error number.
  </para>

  <note>
   <para>
    Once an <literal>errno</literal> error number has been obtained,
    <function>pcntl_strerror</function> can be used to get the text message
    associated with it.
   </para>
  </note>
 </refsect1>

  <refsect1 role="errors">
  &reftitle.errors;
  <table>
   <title>Error number (<literal>errno</literal>) values</title>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry><constant>ECHILD</constant></entry>
      <entry>
       The calling process has no existing unwaited-for child processes.
      </entry>
     </row>
     <row>
      <entry><constant>EINTR</constant></entry>
      <entry>
       <function>pcntl_waitid</function> was interrupted by a signal.
      </entry>
     </row>
     <row>
      <entry><constant>EINVAL</constant></entry>
      <entry>
       An invalid value was specified for <parameter>flags</parameter>, or
       <parameter>idtype</parameter> and <parameter>id</parameter> specify an
       invalid set of processes.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>pcntl_waitpid</function></member>
    <member><function>pcntl_wait</function></member>
    <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>
   </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
-->