[doc-en] master: exec: document the ValueError thrown by four more functions (#6068)
| From: | Asish Kumar via GitHub | Date: | Thu, 12 Nov 2026 14:25:30 +0000 |
| Subject: | [doc-en] master: exec: document the ValueError thrown by four more functions (#6068) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23941@lists.php.net to get a copy of this message | ||
Author: Asish Kumar (officialasishkumar)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-11-12T15:25:27+01:00
Commit: https://github.com/php/doc-en/commit/d71237a6d72fe22ef4b47b6d65ef169b90aecd9b
Raw diff: https://github.com/php/doc-en/commit/d71237a6d72fe22ef4b47b6d65ef169b90aecd9b.diff
exec: document the ValueError thrown by four more functions (#6068)
system(), shell_exec(), escapeshellcmd() and escapeshellarg() throw a
ValueError, but unlike exec() and passthru() their pages did not say so.
- system() and shell_exec() throw if command is empty or contains null
bytes. Both used to emit an E_WARNING and return false; they throw as
of 8.0.0. system() also gets the E_WARNING for a command that cannot
be executed, as on exec().
- escapeshellcmd() and escapeshellarg() throw if the input contains null
bytes (as of 8.0.0), and if the input or the escaped string is longer
than the maximum command line length of the system (as of 8.4.0).
Both used to raise a fatal E_ERROR.
Checked against ext/standard/exec.c in php-src (php-7.4.0 to php-8.5.0)
and by running each case on PHP 7.4, 8.3 and 8.4.
Fixes #6064
Changed paths:
M reference/exec/functions/escapeshellarg.xml
M reference/exec/functions/escapeshellcmd.xml
M reference/exec/functions/shell-exec.xml
M reference/exec/functions/system.xml
Diff:
diff --git a/reference/exec/functions/escapeshellarg.xml
b/reference/exec/functions/escapeshellarg.xml
index 4243ff09e638..60ccd329f6a1 100644
--- a/reference/exec/functions/escapeshellarg.xml
+++ b/reference/exec/functions/escapeshellarg.xml
@@ -59,6 +59,48 @@
</simpara>
</refsect1>
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws a <exceptionname>ValueError</exceptionname> if
<parameter>arg</parameter>
+ contains null bytes, or if <parameter>arg</parameter> or the escaped
+ argument is longer than the maximum command line length allowed by the
+ system.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.4.0</entry>
+ <entry>
+ If <parameter>arg</parameter> or the escaped argument is too long,
+ <function>escapeshellarg</function> now throws a
<exceptionname>ValueError</exceptionname>.
+ Previously a fatal <constant>E_ERROR</constant> was raised.
+ </entry>
+ </row>
+ <row>
+ <entry>8.0.0</entry>
+ <entry>
+ If <parameter>arg</parameter> contains null bytes,
+ <function>escapeshellarg</function> now throws a
<exceptionname>ValueError</exceptionname>.
+ Previously a fatal <constant>E_ERROR</constant> was raised.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<para>
diff --git a/reference/exec/functions/escapeshellcmd.xml
b/reference/exec/functions/escapeshellcmd.xml
index 0e7787a78aa4..a51c52616f7c 100644
--- a/reference/exec/functions/escapeshellcmd.xml
+++ b/reference/exec/functions/escapeshellcmd.xml
@@ -61,6 +61,48 @@
</simpara>
</refsect1>
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws a <exceptionname>ValueError</exceptionname> if
<parameter>command</parameter>
+ contains null bytes, or if <parameter>command</parameter> or the escaped
+ command is longer than the maximum command line length allowed by the
+ system.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.4.0</entry>
+ <entry>
+ If <parameter>command</parameter> or the escaped command is too long,
+ <function>escapeshellcmd</function> now throws a
<exceptionname>ValueError</exceptionname>.
+ Previously a fatal <constant>E_ERROR</constant> was raised.
+ </entry>
+ </row>
+ <row>
+ <entry>8.0.0</entry>
+ <entry>
+ If <parameter>command</parameter> contains null bytes,
+ <function>escapeshellcmd</function> now throws a
<exceptionname>ValueError</exceptionname>.
+ Previously a fatal <constant>E_ERROR</constant> was raised.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<para>
diff --git a/reference/exec/functions/shell-exec.xml b/reference/exec/functions/shell-exec.xml
index 1af9bfaf7951..2a0ced2763dc 100644
--- a/reference/exec/functions/shell-exec.xml
+++ b/reference/exec/functions/shell-exec.xml
@@ -63,6 +63,34 @@
An <constant>E_WARNING</constant> level error is generated
when the pipe cannot be established.
</para>
+ <simpara>
+ Throws a <exceptionname>ValueError</exceptionname> if
<parameter>command</parameter>
+ is empty or contains null bytes.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.0.0</entry>
+ <entry>
+ If <parameter>command</parameter> is empty or contains null bytes,
+ <function>shell_exec</function> now throws a
<exceptionname>ValueError</exceptionname>.
+ Previously it emitted an <constant>E_WARNING</constant> and returned
&false;.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
</refsect1>
<refsect1 role="examples">
diff --git a/reference/exec/functions/system.xml b/reference/exec/functions/system.xml
index 25adbb15ac35..32f59f2c321d 100644
--- a/reference/exec/functions/system.xml
+++ b/reference/exec/functions/system.xml
@@ -65,6 +65,42 @@
</para>
</refsect1>
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Emits an <constant>E_WARNING</constant> if <function>system</function>
+ is unable to execute the <parameter>command</parameter>.
+ </simpara>
+ <simpara>
+ Throws a <exceptionname>ValueError</exceptionname> if
<parameter>command</parameter>
+ is empty or contains null bytes.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.0.0</entry>
+ <entry>
+ If <parameter>command</parameter> is empty or contains null bytes,
+ <function>system</function> now throws a
<exceptionname>ValueError</exceptionname>.
+ Previously it emitted an <constant>E_WARNING</constant> and returned
&false;.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<para>