Skip to content

escapeshellarg / escapeshellcmd: Document multibyte string behavior #4924

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AllenJB wants to merge 5 commits into
base: master
Choose a base branch
from
+32 −20
Open

escapeshellarg / escapeshellcmd: Document multibyte string behavior #4924

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
12eb5ae
escapeshellarg / escapeshellcmd: Document multibyte string behavior
AllenJB Oct 13, 2025
c77784d
Merge remote-tracking branch 'origin/master' into escshellarg
AllenJB Jul 1, 2026
3bc41d6
Fix missing .
AllenJB Jul 1, 2026
e55b817
simpara and whitespace fixes
AllenJB Jul 1, 2026
5edf0aa
same for escapeshellarg (fullstop, simpara)
AllenJB Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions reference/exec/functions/escapeshellarg.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,22 +13,27 @@
<type>string</type><methodname>escapeshellarg</methodname>
<methodparam><type>string</type><parameter>arg</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>escapeshellarg</function> adds single quotes around a string
and quotes/escapes any existing single quotes allowing you to pass a
string directly to a shell function and having it be treated as a single
safe argument. This function should be used to escape individual
arguments to shell functions coming from user input. The shell functions
include <function>exec</function>, <function>system</function> and the
<link linkend="language.operators.execution">backtick operator</link>.
</para>
<para>
</simpara>
<simpara>
On Windows, <function>escapeshellarg</function> instead replaces percent
signs, exclamation marks (delayed variable substitution) and double quotes
with spaces and adds double quotes around the string.
Furthermore, each streak of consecutive backslashes (<literal>\</literal>)
is escaped by one additional backslash.
</para>
</simpara>
<simpara>
The behavior of this function with multibyte strings depends on the current
<constant>LC_CTYPE</constant> locale setting. Unrecognized characters will be
discarded. See <function>setlocale</function>.
</simpara>
</refsect1>

<refsect1 role="parameters">
Expand All @@ -38,9 +43,9 @@
<varlistentry>
<term><parameter>arg</parameter></term>
<listitem>
<para>
<simpara>
The argument that will be escaped.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
Expand All @@ -49,9 +54,9 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
The escaped string.
</para>
</simpara>
</refsect1>

<refsect1 role="examples">
Expand All @@ -74,6 +79,7 @@ system('ls '.escapeshellarg($dir));
&reftitle.seealso;
<para>
<simplelist>
<member><function>setlocale</function></member>
<member><function>escapeshellcmd</function></member>
<member><function>exec</function></member>
<member><function>popen</function></member>
Expand Down
30 changes: 18 additions & 12 deletions reference/exec/functions/escapeshellcmd.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
<type>string</type><methodname>escapeshellcmd</methodname>
<methodparam><type>string</type><parameter>command</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
<function>escapeshellcmd</function> escapes any characters in a
string that might be used to trick a shell command into executing
arbitrary commands. This function should be used to make sure
Expand All @@ -22,15 +22,20 @@
<function>system</function> functions, or to the <link
linkend="language.operators.execution">backtick
operator</link>.
</para>
<para>
</simpara>
<simpara>
Following characters are preceded by a backslash:
<literal>&amp;#;`|*?~&lt;&gt;^()[]{}$\</literal>, <literal>\x0A</literal>
and <literal>\xFF</literal>. <literal>'</literal> and <literal>"</literal>
are escaped only if they are not paired. On Windows, all these characters
plus <literal>%</literal> and <literal>!</literal> are preceded by a caret
(<literal>^</literal>).
</para>
</simpara>
<simpara>
The behavior of this function with multibyte strings depends on the current
<constant>LC_CTYPE</constant> locale setting. Unrecognized characters will be
discarded. See <function>setlocale</function>.
</simpara>
</refsect1>

<refsect1 role="parameters">
Expand All @@ -40,9 +45,9 @@
<varlistentry>
<term><parameter>command</parameter></term>
<listitem>
<para>
<simpara>
The command that will be escaped.
</para>
</simpara>
</listitem>
</varlistentry>
</variablelist>
Expand All @@ -51,9 +56,9 @@

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
The escaped string.
</para>
</simpara>
</refsect1>

<refsect1 role="examples">
Expand All @@ -68,7 +73,7 @@
$command = './configure '.$_POST['configure_options'];

$escaped_command = escapeshellcmd($command);

system($escaped_command);
?>
]]>
Expand All @@ -80,12 +85,12 @@ system($escaped_command);
<refsect1 role="notes">
&reftitle.notes;
<warning xmlns="http://docbook.org/ns/docbook">
<para>
<simpara>
<function>escapeshellcmd</function> should be used on the whole
command string, and it still allows the attacker to pass
arbitrary number of arguments. For escaping a single argument
arbitrary number of arguments. For escaping a single argument
<function>escapeshellarg</function> should be used instead.
</para>
</simpara>
</warning>
<warning xmlns="http://docbook.org/ns/docbook">
<para>
Expand All @@ -107,6 +112,7 @@ $cmd = preg_replace('`(?<!^) `', '^ ', escapeshellcmd($cmd));
&reftitle.seealso;
<para>
<simplelist>
<member><function>setlocale</function></member>
<member><function>escapeshellarg</function></member>
<member><function>exec</function></member>
<member><function>popen</function></member>
Expand Down