[DOC-CVS] [doc-en] master: pcntl: fix the reference pages and document the 8.4 failure return (#5767)

[email protected] (Louis-Arnaud via GitHub)
Newsgroups php.doc.cvs
Message-ID <[email protected]> 
Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-24T14:01:44+02:00

Commit: https://github.com/php/doc-en/commit/253f4bdd29fc3938030dce22882611ceefa9f74a
Raw diff: https://github.com/php/doc-en/commit/253f4bdd29fc3938030dce22882611ceefa9f74a.diff

pcntl: fix the reference pages and document the 8.4 failure return (#5767)

- pcntl_exec(): it only returns false on failure; on success the process image is replaced and the function does not return.
- pcntl_unshare(): it returns a bool, not 0 or -1.
- pcntl_sigprocmask(), pcntl_sigtimedwait(), pcntl_sigwaitinfo(): the parameter is named signals, and the thrown classes are marked up as exceptionname.
- pcntl_sigtimedwait(), pcntl_sigwaitinfo(): document that failure now returns false, where -1 could be returned before PHP 8.4.0.
- pcntl_sigprocmask(): an empty signals array is accepted when mode is SIG_SETMASK.
- pcntl_sigtimedwait(): nanoseconds must be between 0 and 1e9, not merely non-negative.
- versions.xml: add pcntl_forkx, pcntl_getcpu, pcntl_setns and pcntl_wifcontinued.
- constants.xml: drop SI_MSGGQ, which does not exist; the constant is SI_MESGQ and is already documented.
- move the seealso simplelists out of their para.

Changed paths:
  M  reference/pcntl/constants.xml
  M  reference/pcntl/functions/pcntl-exec.xml
  M  reference/pcntl/functions/pcntl-sigprocmask.xml
  M  reference/pcntl/functions/pcntl-sigtimedwait.xml
  M  reference/pcntl/functions/pcntl-sigwaitinfo.xml
  M  reference/pcntl/functions/pcntl-unshare.xml
  M  reference/pcntl/versions.xml


Diff:

diff --git a/reference/pcntl/constants.xml b/reference/pcntl/constants.xml
index b3e1da7c4b35..bd5236419381 100644
--- a/reference/pcntl/constants.xml
+++ b/reference/pcntl/constants.xml
@@ -641,17 +641,6 @@
     </simpara>
    </listitem>
   </varlistentry>
-  <varlistentry xml:id="constant.si-msggq">
-   <term>
-    <constant>SI_MSGGQ</constant>
-    (<type>int</type>)
-   </term>
-   <listitem>
-    <simpara>
-
-    </simpara>
-   </listitem>
-  </varlistentry>
   <varlistentry xml:id="constant.si-asyncio">
    <term>
     <constant>SI_ASYNCIO</constant>
diff --git a/reference/pcntl/functions/pcntl-exec.xml b/reference/pcntl/functions/pcntl-exec.xml
index 51086829f4e0..ddab4cb3331c 100644
--- a/reference/pcntl/functions/pcntl-exec.xml
+++ b/reference/pcntl/functions/pcntl-exec.xml
@@ -60,9 +60,10 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns &false;.
-  </para>
+  <simpara>
+   Returns &false; on failure. On success the function does not return, because
+   the current process image is replaced by the executed program.
+  </simpara>
  </refsect1>
 
 </refentry>
diff --git a/reference/pcntl/functions/pcntl-sigprocmask.xml b/reference/pcntl/functions/pcntl-sigprocmask.xml
index e1a0c00afacd..32d9a40039f2 100644
--- a/reference/pcntl/functions/pcntl-sigprocmask.xml
+++ b/reference/pcntl/functions/pcntl-sigprocmask.xml
@@ -83,28 +83,29 @@
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>ValueError</classname> is thrown if <parameter>signal</parameter>
-       is empty.
+       A <exceptionname>ValueError</exceptionname> is thrown if <parameter>signals</parameter>
+       is empty, unless <parameter>mode</parameter> is
+       <constant>SIG_SETMASK</constant>.
       </entry>
      </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>TypeError</classname> is thrown if <parameter>signal</parameter>
+       A <exceptionname>TypeError</exceptionname> is thrown if <parameter>signals</parameter>
        value is not an <type>int</type>.
       </entry>
      </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>ValueError</classname> is thrown if <parameter>signal</parameter>
+       A <exceptionname>ValueError</exceptionname> is thrown if <parameter>signals</parameter>
        value is invalid.
       </entry>
      </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>ValueError</classname> is thrown if <parameter>mode</parameter>
+       A <exceptionname>ValueError</exceptionname> is thrown if <parameter>mode</parameter>
        value is not <constant>SIG_BLOCK</constant>, <constant>SIG_UNBLOCK</constant> or
        <constant>SIG_SETMASK</constant>.
       </entry>
@@ -134,12 +135,10 @@ pcntl_sigprocmask(SIG_UNBLOCK, array(SIGHUP), $oldset);
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>pcntl_sigwaitinfo</function></member>
-    <member><function>pcntl_sigtimedwait</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>pcntl_sigwaitinfo</function></member>
+   <member><function>pcntl_sigtimedwait</function></member>
+  </simplelist>
  </refsect1>
 
 </refentry>
diff --git a/reference/pcntl/functions/pcntl-sigtimedwait.xml b/reference/pcntl/functions/pcntl-sigtimedwait.xml
index 99aeb5631a62..c220b9c8d3d4 100644
--- a/reference/pcntl/functions/pcntl-sigtimedwait.xml
+++ b/reference/pcntl/functions/pcntl-sigtimedwait.xml
@@ -87,42 +87,49 @@
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>ValueError</classname> is thrown if <parameter>signal</parameter>
+       On failure, &false; is now returned; previously
+       <literal>-1</literal> was returned in some cases.
+      </entry>
+     </row>
+     <row>
+      <entry>8.4.0</entry>
+      <entry>
+       A <exceptionname>ValueError</exceptionname> is thrown if <parameter>signals</parameter>
        is empty.
       </entry>
      </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>TypeError</classname> is thrown if <parameter>signal</parameter>
+       A <exceptionname>TypeError</exceptionname> is thrown if <parameter>signals</parameter>
        value is not an <type>int</type>.
       </entry>
      </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>ValueError</classname> is thrown if <parameter>signal</parameter>
+       A <exceptionname>ValueError</exceptionname> is thrown if <parameter>signals</parameter>
        value is invalid.
       </entry>
      </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>ValueError</classname> is thrown if <parameter>seconds</parameter>
+       A <exceptionname>ValueError</exceptionname> is thrown if <parameter>seconds</parameter>
        value is less than <literal>0</literal>.
       </entry>
      </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>ValueError</classname> is thrown if <parameter>nanoseconds</parameter>
-       value is less than <literal>0</literal>.
+       A <exceptionname>ValueError</exceptionname> is thrown if <parameter>nanoseconds</parameter>
+       value is not between <literal>0</literal> and <literal>1e9</literal>.
       </entry>
      </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>ValueError</classname> is thrown if both <parameter>seconds</parameter> and
+       A <exceptionname>ValueError</exceptionname> is thrown if both <parameter>seconds</parameter> and
        <parameter>nanoseconds</parameter> values are <literal>0</literal>.
       </entry>
      </row>
@@ -133,12 +140,10 @@
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>pcntl_sigprocmask</function></member>
-    <member><function>pcntl_sigwaitinfo</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>pcntl_sigprocmask</function></member>
+   <member><function>pcntl_sigwaitinfo</function></member>
+  </simplelist>
  </refsect1>
 
 </refentry>
diff --git a/reference/pcntl/functions/pcntl-sigwaitinfo.xml b/reference/pcntl/functions/pcntl-sigwaitinfo.xml
index 8c03bef9c159..7d04ca1916f6 100644
--- a/reference/pcntl/functions/pcntl-sigwaitinfo.xml
+++ b/reference/pcntl/functions/pcntl-sigwaitinfo.xml
@@ -102,21 +102,28 @@
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>ValueError</classname> is thrown if <parameter>signal</parameter>
+       On failure, &false; is now returned; previously
+       <literal>-1</literal> was returned in some cases.
+      </entry>
+     </row>
+     <row>
+      <entry>8.4.0</entry>
+      <entry>
+       A <exceptionname>ValueError</exceptionname> is thrown if <parameter>signals</parameter>
        is empty.
       </entry>
      </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>TypeError</classname> is thrown if <parameter>signal</parameter>
+       A <exceptionname>TypeError</exceptionname> is thrown if <parameter>signals</parameter>
        value is not an <type>int</type>.
       </entry>
      </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
-       A <classname>ValueError</classname> is thrown if <parameter>signal</parameter>
+       A <exceptionname>ValueError</exceptionname> is thrown if <parameter>signals</parameter>
        value is invalid.
       </entry>
      </row>
@@ -151,12 +158,10 @@ pcntl_sigwaitinfo(array(SIGHUP), $info);
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>pcntl_sigprocmask</function></member>
-    <member><function>pcntl_sigtimedwait</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>pcntl_sigprocmask</function></member>
+   <member><function>pcntl_sigtimedwait</function></member>
+  </simplelist>
  </refsect1>
 
 </refentry>
diff --git a/reference/pcntl/functions/pcntl-unshare.xml b/reference/pcntl/functions/pcntl-unshare.xml
index 35112d37b157..9778fd6bbb21 100644
--- a/reference/pcntl/functions/pcntl-unshare.xml
+++ b/reference/pcntl/functions/pcntl-unshare.xml
@@ -47,20 +47,18 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns <literal>0</literal> on success, <literal>-1</literal> otherwise.
+  <simpara>
+   Returns &true; on success or &false; on failure.
    On failure it sets an error code, that can be retrieved with <function>pcntl_get_last_error</function>.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><link linkend="pcntl.constants.clone">PCNTL Constants</link></member>
-    <member><function>pcntl_get_last_error</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><link linkend="pcntl.constants.clone">PCNTL Constants</link></member>
+   <member><function>pcntl_get_last_error</function></member>
+  </simplelist>
  </refsect1>
 
 </refentry>
diff --git a/reference/pcntl/versions.xml b/reference/pcntl/versions.xml
index 8a39783e4210..72178cf8caa3 100644
--- a/reference/pcntl/versions.xml
+++ b/reference/pcntl/versions.xml
@@ -7,12 +7,15 @@
  <function name="pcntl_errno" from="PHP 5 &gt;= 5.3.4, PHP 7, PHP 8"/>
  <function name="pcntl_exec" from="PHP 4 &gt;= 4.2.0, PHP 5, PHP 7, PHP 8"/>
  <function name="pcntl_fork" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
+ <function name="pcntl_forkx" from="PHP 8 &gt;= 8.2.0"/>
+ <function name="pcntl_getcpu" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pcntl_getcpuaffinity" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pcntl_getqos_class" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pcntl_getpriority" from="PHP 5, PHP 7, PHP 8"/>
  <function name="pcntl_get_last_error" from="PHP 5 &gt;= 5.3.4, PHP 7, PHP 8"/>
  <function name="pcntl_rfork" from="PHP 8 &gt;= 8.1.0"/>
  <function name="pcntl_setcpuaffinity" from="PHP 8 &gt;= 8.4.0"/>
+ <function name="pcntl_setns" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pcntl_setpriority" from="PHP 5, PHP 7, PHP 8"/>
  <function name="pcntl_setqos_class" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pcntl_signal" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
@@ -27,6 +30,7 @@
  <function name="pcntl_waitpid" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
  <function name="pcntl_waitid" from="PHP 8 &gt;= 8.4.0"/>
  <function name="pcntl_wexitstatus" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
+ <function name="pcntl_wifcontinued" from="PHP 7, PHP 8"/>
  <function name="pcntl_wifexited" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
  <function name="pcntl_wifsignaled" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
  <function name="pcntl_wifstopped" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
lmpx.com only provides a reader for public news (NNTP) servers. It is not affiliated with the servers or forums shown here and is not responsible for the content of articles, which is written by their respective authors.