[doc-en] master: pcntl_signal(): document the SIGALRM default for restart_syscalls (#5821)

From: Date: Tue, 01 Sep 2026 16:09:57 +0000
Subject: [doc-en] master: pcntl_signal(): document the SIGALRM default for restart_syscalls (#5821)
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-23691@lists.php.net to get a copy of this message
Author: Louis-Arnaud (lacatoire) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-01T18:09:54+02:00 Commit: https://github.com/php/doc-en/commit/3866fba43ed70c07afa89df7daf21529b09b4f3b Raw diff: https://github.com/php/doc-en/commit/3866fba43ed70c07afa89df7daf21529b09b4f3b.diff pcntl_signal(): document the SIGALRM default for restart_syscalls (#5821) Changed paths: M reference/pcntl/functions/pcntl-signal.xml Diff: diff --git a/reference/pcntl/functions/pcntl-signal.xml b/reference/pcntl/functions/pcntl-signal.xml index 07f4736e893c..01f5f03e2899 100644 --- a/reference/pcntl/functions/pcntl-signal.xml +++ b/reference/pcntl/functions/pcntl-signal.xml @@ -5,7 +5,7 @@ <refname>pcntl_signal</refname> <refpurpose>Installs a signal handler</refpurpose> </refnamediv> - + <refsect1 role="description"> &reftitle.description; <methodsynopsis> @@ -35,13 +35,13 @@ <varlistentry> <term><parameter>handler</parameter></term> <listitem> - <para> + <simpara> The signal handler. This may be either a <type>callable</type>, which will be invoked to handle the signal, or either of the two global constants <constant>SIG_IGN</constant> or <constant>SIG_DFL</constant>, which will ignore the signal or restore the default signal handler - respectively. - </para> + respectively. + </simpara> <para> If a <type>callable</type> is given, it must implement the following signature: @@ -54,7 +54,7 @@ </methodsynopsis> <variablelist> <varlistentry> - <term><parameter>signal</parameter></term> + <term><parameter>signo</parameter></term> <listitem> <simpara> The signal being handled. @@ -72,11 +72,11 @@ </variablelist> </para> <note> - <para> - Note that when you set a handler to an object method, that object's - reference count is increased which makes it persist until you either - change the handler to something else, or your script ends. - </para> + <simpara> + When a handler is set to an object method, the reference count of that + object is increased, which makes it persist until the handler is + changed to something else, or the script ends. + </simpara> </note> </listitem> </varlistentry> @@ -87,6 +87,16 @@ Specifies whether system call restarting should be used when this signal arrives. </para> + <note> + <simpara> + Although this parameter defaults to &true;, that default does not + apply to <constant>SIGALRM</constant>: when + <parameter>restart_syscalls</parameter> is not passed and + <parameter>signal</parameter> is <constant>SIGALRM</constant>, + system call restarting is disabled. Pass &true; explicitly to + enable system call restarting for <constant>SIGALRM</constant>. + </simpara> + </note> </listitem> </varlistentry> </variablelist> @@ -100,6 +110,22 @@ </para> </refsect1> + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + A <exceptionname>ValueError</exceptionname> is thrown if + <parameter>signal</parameter> is less than <literal>1</literal> or greater + than or equal to <constant>NSIG</constant>, or if + <parameter>handler</parameter> is an <type>int</type> other than + <constant>SIG_DFL</constant> or <constant>SIG_IGN</constant>. + </simpara> + <simpara> + A <exceptionname>TypeError</exceptionname> is thrown if + <parameter>handler</parameter> is neither a <type>callable</type> nor an + <type>int</type>. + </simpara> + </refsect1> + <refsect1 role="changelog"> &reftitle.changelog; <para> @@ -112,6 +138,16 @@ </row> </thead> <tbody> + <row> + <entry>7.4.0</entry> + <entry> + <parameter>restart_syscalls</parameter> is now honoured for + <constant>SIGALRM</constant>; previously system call restarting was + always disabled for that signal. When the argument is not passed, + system call restarting remains disabled for + <constant>SIGALRM</constant>. + </entry> + </row> <row> <entry>7.1.0</entry> <entry> @@ -185,9 +221,10 @@ echo "Done\n"; <refsect1 role="notes"><!-- {{{ --> &reftitle.notes; - <para> - <function>pcntl_signal</function> doesn't stack the signal handlers, but replaces them. - </para> + <simpara> + <function>pcntl_signal</function> does not stack the signal handlers, but + replaces them. + </simpara> <refsect2> <title>Dispatch Methods</title> <para> @@ -207,15 +244,13 @@ echo "Done\n"; <refsect1 role="seealso"> &reftitle.seealso; - <para> - <simplelist> - <member><link xlink:href="https://en.wikipedia.org/wiki/Signal_(IPC)">Signal (IPC)</link> on Wikipedia</member> - <member><function>pcntl_async_signals</function></member> - <member><function>pcntl_fork</function></member> - <member><function>pcntl_signal_dispatch</function></member> - <member><function>pcntl_waitpid</function></member> - </simplelist> - </para> + <simplelist> + <member><link xlink:href="https://en.wikipedia.org/wiki/Signal_(IPC)">Signal (IPC)</link> on Wikipedia</member> + <member><function>pcntl_async_signals</function></member> + <member><function>pcntl_fork</function></member> + <member><function>pcntl_signal_dispatch</function></member> + <member><function>pcntl_waitpid</function></member> + </simplelist> </refsect1> </refentry>

« previous php.doc.cvs (#23691) next »