[doc-en] master: exec: document the ValueError thrown by four more functions (#6068)

From: 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>

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