From fb1e5ecf9ee990ee1373d45f73b75cf4f956dcdd Mon Sep 17 00:00:00 2001 From: Louis-Arnaud Date: Sun, 16 Aug 2026 18:50:05 +0200 Subject: [PATCH] pcntl: fix the reference pages and document the 8.4 failure return - 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. --- reference/pcntl/constants.xml | 11 ------- reference/pcntl/functions/pcntl-exec.xml | 7 +++-- .../pcntl/functions/pcntl-sigprocmask.xml | 21 ++++++------- .../pcntl/functions/pcntl-sigtimedwait.xml | 31 +++++++++++-------- .../pcntl/functions/pcntl-sigwaitinfo.xml | 23 ++++++++------ reference/pcntl/functions/pcntl-unshare.xml | 16 +++++----- reference/pcntl/versions.xml | 4 +++ 7 files changed, 57 insertions(+), 56 deletions(-) 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 @@ - - - SI_MSGGQ - (int) - - - - - - - SI_ASYNCIO 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 @@ &reftitle.returnvalues; - - Returns &false;. - + + Returns &false; on failure. On success the function does not return, because + the current process image is replaced by the executed program. + 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 @@ 8.4.0 - A ValueError is thrown if signal - is empty. + A ValueError is thrown if signals + is empty, unless mode is + SIG_SETMASK. 8.4.0 - A TypeError is thrown if signal + A TypeError is thrown if signals value is not an int. 8.4.0 - A ValueError is thrown if signal + A ValueError is thrown if signals value is invalid. 8.4.0 - A ValueError is thrown if mode + A ValueError is thrown if mode value is not SIG_BLOCK, SIG_UNBLOCK or SIG_SETMASK. @@ -134,12 +135,10 @@ pcntl_sigprocmask(SIG_UNBLOCK, array(SIGHUP), $oldset); &reftitle.seealso; - - - pcntl_sigwaitinfo - pcntl_sigtimedwait - - + + pcntl_sigwaitinfo + pcntl_sigtimedwait + 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 @@ 8.4.0 - A ValueError is thrown if signal + On failure, &false; is now returned; previously + -1 was returned in some cases. + + + + 8.4.0 + + A ValueError is thrown if signals is empty. 8.4.0 - A TypeError is thrown if signal + A TypeError is thrown if signals value is not an int. 8.4.0 - A ValueError is thrown if signal + A ValueError is thrown if signals value is invalid. 8.4.0 - A ValueError is thrown if seconds + A ValueError is thrown if seconds value is less than 0. 8.4.0 - A ValueError is thrown if nanoseconds - value is less than 0. + A ValueError is thrown if nanoseconds + value is not between 0 and 1e9. 8.4.0 - A ValueError is thrown if both seconds and + A ValueError is thrown if both seconds and nanoseconds values are 0. @@ -133,12 +140,10 @@ &reftitle.seealso; - - - pcntl_sigprocmask - pcntl_sigwaitinfo - - + + pcntl_sigprocmask + pcntl_sigwaitinfo + 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 @@ 8.4.0 - A ValueError is thrown if signal + On failure, &false; is now returned; previously + -1 was returned in some cases. + + + + 8.4.0 + + A ValueError is thrown if signals is empty. 8.4.0 - A TypeError is thrown if signal + A TypeError is thrown if signals value is not an int. 8.4.0 - A ValueError is thrown if signal + A ValueError is thrown if signals value is invalid. @@ -151,12 +158,10 @@ pcntl_sigwaitinfo(array(SIGHUP), $info); &reftitle.seealso; - - - pcntl_sigprocmask - pcntl_sigtimedwait - - + + pcntl_sigprocmask + pcntl_sigtimedwait + 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 @@ &reftitle.returnvalues; - - Returns 0 on success, -1 otherwise. + + Returns &true; on success or &false; on failure. On failure it sets an error code, that can be retrieved with pcntl_get_last_error. - + &reftitle.seealso; - - - PCNTL Constants - pcntl_get_last_error - - + + PCNTL Constants + pcntl_get_last_error + 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 @@ + + + @@ -27,6 +30,7 @@ +