[doc-en] master: pcntl_wait / pcntl_waitpid: Document the rusage parameter (fixes #861) (#4917)

Author: AllenJB (AllenJB) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-03T11:13:32+02:00 Commit: https://github.com/php/doc-en/commit/ec891f50fa7c999195c1c792261bfd15e41daf73 Raw diff: https://github.com/php/doc-en/commit/ec891f50fa7c999195c1c792261bfd15e41daf73.diff pcntl_wait / pcntl_waitpid: Document the rusage parameter (fixes #861) (#4917) * pcntl_wait / pcntl_waitpid: Document the rusage parameter (fixes #861) * pcntl_wait / pcntl_waitpid: Document the rusage parameter (fixes #861) (fix example comments) * pcntl_wait / pcntl_waitpid: Document the rusage parameter (fixes #861) (remove duplicate example; align parameter descriptions) * pcntl_wait / pcntl_waitpid: Document the rusage parameter (fixes #861) (remove duplicate example; align parameter descriptions) * pcntl_wait / pcntl_waitpid: Document the rusage parameter (fixes #861) (remove duplicate example; align parameter descriptions) * pcntl: fix the resource_usage description and the pcntl_waitpid example The wait6 / raw waitid wording only applies to pcntl_waitid. pcntl_wait uses wait3() under HAVE_WAIT3 and pcntl_waitpid uses wait4() under HAVE_WAIT4, so both fill resource_usage on Linux and macOS as well. Also document that the array is emptied when no child is reaped, drop the pcntl_waitpid entry duplicated in the pcntl_wait seealso list, guard pcntl_wexitstatus() with pcntl_wifexited() in the example, print the errno instead of the constant -1 return, unwrap the example from its para and split the inline-only paras into simparas for the style check. --------- Co-authored-by: Louis-Arnaud <la.catoire@gmail.com> Changed paths: M reference/pcntl/functions/pcntl-wait.xml M reference/pcntl/functions/pcntl-waitid.xml M reference/pcntl/functions/pcntl-waitpid.xml Diff: diff --git a/reference/pcntl/functions/pcntl-wait.xml b/reference/pcntl/functions/pcntl-wait.xml index ba4c81de9f0c..76dc36d2f0ae 100644 --- a/reference/pcntl/functions/pcntl-wait.xml +++ b/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> diff --git a/reference/pcntl/functions/pcntl-waitid.xml b/reference/pcntl/functions/pcntl-waitid.xml index 6a623bbc11f9..2cda7551161b 100644 --- a/reference/pcntl/functions/pcntl-waitid.xml +++ b/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> diff --git a/reference/pcntl/functions/pcntl-waitpid.xml b/reference/pcntl/functions/pcntl-waitpid.xml index d385fe06be38..c679c5f2a220 100644 --- a/reference/pcntl/functions/pcntl-waitpid.xml +++ b/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>