pcntl_wait / pcntl_waitpid: Document the rusage parameter (fixes #861)

reference/pcntl/functions/pcntl-wait.xml

@@ -86,6 +86,24 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term><parameter>resource_usage</parameter></term>
+     <listitem>
+      <simpara>
+       The <parameter>resource_usage</parameter> parameter is set to an
+       associative <type>array</type> containing resource usage statistics
+       from the child process. For information on the contents see
+       <function>getrusage</function>.
+      </simpara>
+      <simpara>
+       This is only supported if the <literal>wait3(2)</literal> system call is
+       available on the system; otherwise the parameter is left untouched.
+       If no child process was reaped, that is if the function returns
+       <literal>0</literal> or <literal>-1</literal>, the parameter is set to
+       an empty <type>array</type>.
+      </simpara>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>

reference/pcntl/functions/pcntl-waitid.xml

@@ -249,13 +249,18 @@
    <varlistentry>
     <term><parameter>resource_usage</parameter></term>
     <listitem>
-     <para>
-      The <parameter>resource_usage</parameter> parameter is set to an array
-      containing resource usage statistics from the child process.
-
-      This is supported either if the wait6 system call is available
-      (e.g. on FreeBSD), or on Linux through the raw waitid system call.
-     </para>
+     <simpara>
+      The <parameter>resource_usage</parameter> parameter is set to an
+      associative <type>array</type> containing resource usage statistics
+      from the child process. For information on the contents see
+      <function>getrusage</function>.
+     </simpara>
+     <simpara>
+      This is only supported if the <literal>wait6(2)</literal> system call is
+      available, for example on FreeBSD, or on Linux through the raw
+      <literal>waitid(2)</literal> system call; otherwise the parameter is
+      left untouched.
+     </simpara>
     </listitem>
    </varlistentry>
   </variablelist>

reference/pcntl/functions/pcntl-waitpid.xml

@@ -130,6 +130,24 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term><parameter>resource_usage</parameter></term>
+     <listitem>
+      <simpara>
+       The <parameter>resource_usage</parameter> parameter is set to an
+       associative <type>array</type> containing resource usage statistics
+       from the child process. For information on the contents see
+       <function>getrusage</function>.
+      </simpara>
+      <simpara>
+       This is only supported if the <literal>wait4(2)</literal> system call is
+       available on the system; otherwise the parameter is left untouched.
+       If no child process was reaped, that is if the function returns
+       <literal>0</literal> or <literal>-1</literal>, the parameter is set to
+       an empty <type>array</type>.
+      </simpara>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -143,12 +161,72 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>pcntl_waitpid</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+function checkChild(int $pid, bool $wait): void
+{
+    $flags = ($wait ? 0 : WNOHANG);
+    $deadPid = pcntl_waitpid($pid, $status, $flags, $rusage);
+    if ($deadPid === -1) {
+        $errNo = pcntl_get_last_error();
+        $errMsg = pcntl_strerror($errNo);
+        print "PARENT pcntl_waitpid FAILED ({$errNo}): {$errMsg}\n";
+    } elseif ($deadPid === 0) {
+        print "PARENT pcntl_waitpid: No exited children.\n";
+    } elseif (pcntl_wifexited($status)) {
+        print "PARENT pcntl_waitpid: Child PID {$deadPid} exited with status: "
+            . pcntl_wexitstatus($status) . "\n";
+        var_dump($rusage);
+    } else {
+        print "PARENT pcntl_waitpid: Child PID {$deadPid} was terminated by signal: "
+            . pcntl_wtermsig($status) . "\n";
+    }
+}
+
+$parentPid = getmypid();
+$forkedPid = pcntl_fork();
+if ($forkedPid == -1) {
+    die('Could not fork');
+} else if ($forkedPid) {
+    // Parent process
+    print "PARENT {$parentPid} has forked {$forkedPid}\n";
+
+    print "PARENT is checking for exited children\n";
+    checkChild($forkedPid, false);
+
+    // Prevents children remaining as a "zombie process"
+    print "PARENT is waiting for a child to exit\n";
+    checkChild($forkedPid, true);
+
+    print "PARENT is checking for exited children\n";
+    checkChild($forkedPid, false);
+
+    print "PARENT is exiting\n";
+} else {
+    // Child process
+    $pid = getmypid();
+    print "CHILD {$pid} is sleeping\n";
+    sleep(10);
+    print "CHILD is exiting\n";
+    exit(7);
+}
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
     <member><function>pcntl_fork</function></member>
     <member><function>pcntl_signal</function></member>
+    <member><function>pcntl_wait</function></member>
     <member><function>pcntl_wifexited</function></member>
     <member><function>pcntl_wifstopped</function></member>
     <member><function>pcntl_wifsignaled</function></member>