[doc-en] master: pcntl_signal(): document the SIGALRM default for restart_syscalls (#5821)
| From: | Louis-Arnaud via GitHub | 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>