From 603044843a924d9889fdc3d967125d6b710672f9 Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Sat, 11 Oct 2025 19:35:59 +0100
Subject: [PATCH 1/5] pcntl_wait / pcntl_waitpid: Document the rusage parameter
 (fixes #861)

---
 reference/pcntl/functions/pcntl-wait.xml    | 70 +++++++++++++++++++++
 reference/pcntl/functions/pcntl-waitpid.xml | 70 +++++++++++++++++++++
 2 files changed, 140 insertions(+)

diff --git a/reference/pcntl/functions/pcntl-wait.xml b/reference/pcntl/functions/pcntl-wait.xml
index ba4c81de9f0c..1fb4c0c1850d 100644
--- a/reference/pcntl/functions/pcntl-wait.xml
+++ b/reference/pcntl/functions/pcntl-wait.xml
@@ -86,6 +86,16 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term><parameter>resource_usage</parameter></term>
+     <listitem>
+      <para>
+       Stores the resource usage information for the child that exited as an
+       associative <type>array</type>. For information on the contents see
+       <function>getrusage</function>.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -99,12 +109,72 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>pcntl_wait</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+function checkChildren(bool $wait): void
+{
+    $flags = ($wait ? 0 : WNOHANG);
+    $deadPid = pcntl_wait($status, $flags, $rusage);
+    if ($deadPid === -1) {
+        $errNo = pcntl_get_last_error();
+        $errMsg = pcntl_strerror($errNo);
+        print "PARENT pcntl_wait FAILED ({$deadPid}): {$errMsg}\n";
+    } elseif ($deadPid === 0) {
+        print "PARENT pcntl_wait: No exited children.\n";
+    } else {
+        print "PARENT pcntl_wait: Child PID {$deadPid} exited with status: "
+            . pcntl_wexitstatus($status) ."\n";
+        var_dump($rusage);
+    }
+}
+
+$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";
+    checkChildren(false);
+
+    // Processes which exit without waiting for children will remain in the
+    // system process list marked as a "Zombie process"
+    print "PARENT is waiting for a child to exit\n";
+    checkChildren(true);
+
+    print "PARENT is checking for exited children\n";
+    checkChildren(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>
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
     <member><function>pcntl_fork</function></member>
     <member><function>pcntl_signal</function></member>
+    <member><function>pcntl_waitpid</function></member>
     <member><function>pcntl_wifexited</function></member>
     <member><function>pcntl_wifstopped</function></member>
     <member><function>pcntl_wifsignaled</function></member>
diff --git a/reference/pcntl/functions/pcntl-waitpid.xml b/reference/pcntl/functions/pcntl-waitpid.xml
index d385fe06be38..7af3da128fd0 100644
--- a/reference/pcntl/functions/pcntl-waitpid.xml
+++ b/reference/pcntl/functions/pcntl-waitpid.xml
@@ -130,6 +130,16 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term><parameter>resource_usage</parameter></term>
+     <listitem>
+      <para>
+       Stores the resource usage information for the child that exited as an
+       associative <type>array</type>. For information on the contents see
+       <function>getrusage</function>.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -143,12 +153,72 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <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 ({$deadPid}): {$errMsg}\n";
+    } elseif ($deadPid === 0) {
+        print "PARENT pcntl_waitpid: No exited children.\n";
+    } else {
+        print "PARENT pcntl_waitpid: Child PID {$deadPid} exited with status: "
+            . pcntl_wexitstatus($status) ."\n";
+        var_dump($rusage);
+    }
+}
+
+$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);
+
+    // Processes which exit without waiting for children will remain in the
+    // system process list marked 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>
+  </para>
+ </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>

From fd20c6aeb42d1a5daf39da7e06739922b83c1639 Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Sat, 11 Oct 2025 21:40:27 +0100
Subject: [PATCH 2/5] pcntl_wait / pcntl_waitpid: Document the rusage parameter
 (fixes #861) (fix example comments)

---
 reference/pcntl/functions/pcntl-wait.xml    | 3 +--
 reference/pcntl/functions/pcntl-waitpid.xml | 3 +--
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/reference/pcntl/functions/pcntl-wait.xml b/reference/pcntl/functions/pcntl-wait.xml
index 1fb4c0c1850d..c735289148f1 100644
--- a/reference/pcntl/functions/pcntl-wait.xml
+++ b/reference/pcntl/functions/pcntl-wait.xml
@@ -145,8 +145,7 @@ if ($forkedPid == -1) {
     print "PARENT is checking for exited children\n";
     checkChildren(false);
 
-    // Processes which exit without waiting for children will remain in the
-    // system process list marked as a "Zombie process"
+    // Prevents children remaining as a "zombie process"
     print "PARENT is waiting for a child to exit\n";
     checkChildren(true);
 
diff --git a/reference/pcntl/functions/pcntl-waitpid.xml b/reference/pcntl/functions/pcntl-waitpid.xml
index 7af3da128fd0..863c11b6b231 100644
--- a/reference/pcntl/functions/pcntl-waitpid.xml
+++ b/reference/pcntl/functions/pcntl-waitpid.xml
@@ -189,8 +189,7 @@ if ($forkedPid == -1) {
     print "PARENT is checking for exited children\n";
     checkChild($forkedPid, false);
 
-    // Processes which exit without waiting for children will remain in the
-    // system process list marked as a "Zombie process"
+    // Prevents children remaining as a "zombie process"
     print "PARENT is waiting for a child to exit\n";
     checkChild($forkedPid, true);
 

From 55c86d49416fc4a93e1fc0b890e5bab7e318f859 Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Tue, 28 Oct 2025 16:00:11 +0000
Subject: [PATCH 3/5] pcntl_wait / pcntl_waitpid: Document the rusage parameter
 (fixes #861) (remove duplicate example; align parameter descriptions)

---
 reference/pcntl/functions/pcntl-wait.xml    | 70 +++------------------
 reference/pcntl/functions/pcntl-waitid.xml  |  8 ++-
 reference/pcntl/functions/pcntl-waitpid.xml | 10 ++-
 3 files changed, 20 insertions(+), 68 deletions(-)

diff --git a/reference/pcntl/functions/pcntl-wait.xml b/reference/pcntl/functions/pcntl-wait.xml
index c735289148f1..cca361ae1f86 100644
--- a/reference/pcntl/functions/pcntl-wait.xml
+++ b/reference/pcntl/functions/pcntl-wait.xml
@@ -90,9 +90,13 @@
      <term><parameter>resource_usage</parameter></term>
      <listitem>
       <para>
-       Stores the resource usage information for the child that exited as an
-       associative <type>array</type>. For information on the contents see
-       <function>getrusage</function>.
+       The <parameter>resource_usage</parameter> parameter is set to an
+       associative <type>array</type> 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. For
+       information on the contents see <function>getrusage</function>.
       </para>
      </listitem>
     </varlistentry>
@@ -108,65 +112,7 @@
    option (on wait3-available systems) and no child was available.
   </para>
  </refsect1>
-
- <refsect1 role="examples">
-  &reftitle.examples;
-  <para>
-   <example>
-    <title><function>pcntl_wait</function> example</title>
-    <programlisting role="php">
-<![CDATA[
-<?php
-function checkChildren(bool $wait): void
-{
-    $flags = ($wait ? 0 : WNOHANG);
-    $deadPid = pcntl_wait($status, $flags, $rusage);
-    if ($deadPid === -1) {
-        $errNo = pcntl_get_last_error();
-        $errMsg = pcntl_strerror($errNo);
-        print "PARENT pcntl_wait FAILED ({$deadPid}): {$errMsg}\n";
-    } elseif ($deadPid === 0) {
-        print "PARENT pcntl_wait: No exited children.\n";
-    } else {
-        print "PARENT pcntl_wait: Child PID {$deadPid} exited with status: "
-            . pcntl_wexitstatus($status) ."\n";
-        var_dump($rusage);
-    }
-}
-
-$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";
-    checkChildren(false);
-
-    // Prevents children remaining as a "zombie process"
-    print "PARENT is waiting for a child to exit\n";
-    checkChildren(true);
-
-    print "PARENT is checking for exited children\n";
-    checkChildren(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>
-  </para>
- </refsect1>
-
+ 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/pcntl/functions/pcntl-waitid.xml b/reference/pcntl/functions/pcntl-waitid.xml
index d108a9012830..0573ff4c1087 100644
--- a/reference/pcntl/functions/pcntl-waitid.xml
+++ b/reference/pcntl/functions/pcntl-waitid.xml
@@ -250,11 +250,13 @@
     <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.
+      The <parameter>resource_usage</parameter> parameter is set to an 
+      associative <type>array</type> 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.
+      (e.g. on FreeBSD), or on Linux through the raw waitid system call. For 
+      information on the contents see <function>getrusage</function>.
      </para>
     </listitem>
    </varlistentry>
diff --git a/reference/pcntl/functions/pcntl-waitpid.xml b/reference/pcntl/functions/pcntl-waitpid.xml
index 863c11b6b231..fc807421243d 100644
--- a/reference/pcntl/functions/pcntl-waitpid.xml
+++ b/reference/pcntl/functions/pcntl-waitpid.xml
@@ -134,9 +134,13 @@
      <term><parameter>resource_usage</parameter></term>
      <listitem>
       <para>
-       Stores the resource usage information for the child that exited as an
-       associative <type>array</type>. For information on the contents see
-       <function>getrusage</function>.
+       The <parameter>resource_usage</parameter> parameter is set to an
+       associative <type>array</type> 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. For
+       information on the contents see <function>getrusage</function>.
       </para>
      </listitem>
     </varlistentry>

From cb6baa450bc9c99da3335e76123bab54e97fc7cc Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Tue, 28 Oct 2025 16:02:25 +0000
Subject: [PATCH 4/5] pcntl_wait / pcntl_waitpid: Document the rusage parameter
 (fixes #861) (remove duplicate example; align parameter descriptions)

---
 reference/pcntl/functions/pcntl-waitid.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/pcntl/functions/pcntl-waitid.xml b/reference/pcntl/functions/pcntl-waitid.xml
index 0573ff4c1087..3b71b51b2be0 100644
--- a/reference/pcntl/functions/pcntl-waitid.xml
+++ b/reference/pcntl/functions/pcntl-waitid.xml
@@ -250,7 +250,7 @@
     <term><parameter>resource_usage</parameter></term>
     <listitem>
      <para>
-      The <parameter>resource_usage</parameter> parameter is set to an 
+      The <parameter>resource_usage</parameter> parameter is set to an
       associative <type>array</type> containing resource usage statistics 
       from the child process.
 

From b9cb0c258306d75b673769bab2eeb6a23a7541af Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Tue, 28 Oct 2025 16:04:46 +0000
Subject: [PATCH 5/5] pcntl_wait / pcntl_waitpid: Document the rusage parameter
 (fixes #861) (remove duplicate example; align parameter descriptions)

---
 reference/pcntl/functions/pcntl-wait.xml   | 2 +-
 reference/pcntl/functions/pcntl-waitid.xml | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/reference/pcntl/functions/pcntl-wait.xml b/reference/pcntl/functions/pcntl-wait.xml
index cca361ae1f86..f33fba78855c 100644
--- a/reference/pcntl/functions/pcntl-wait.xml
+++ b/reference/pcntl/functions/pcntl-wait.xml
@@ -112,7 +112,7 @@
    option (on wait3-available systems) and no child was available.
   </para>
  </refsect1>
- 
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/pcntl/functions/pcntl-waitid.xml b/reference/pcntl/functions/pcntl-waitid.xml
index 3b71b51b2be0..48c9f94f793f 100644
--- a/reference/pcntl/functions/pcntl-waitid.xml
+++ b/reference/pcntl/functions/pcntl-waitid.xml
@@ -251,11 +251,11 @@
     <listitem>
      <para>
       The <parameter>resource_usage</parameter> parameter is set to an
-      associative <type>array</type> containing resource usage statistics 
+      associative <type>array</type> 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. For 
+      (e.g. on FreeBSD), or on Linux through the raw waitid system call. For
       information on the contents see <function>getrusage</function>.
      </para>
     </listitem>