[DOC-CVS] [doc-en] master: escapeshellarg / escapeshellcmd: Document multibyte string behavior (#4924)

Author: AllenJB (AllenJB)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-21T11:52:10+02:00

Commit: https://github.com/php/doc-en/commit/0600ff7ba94e3f491aeb246d8ddfedd98f0d7276
Raw diff: https://github.com/php/doc-en/commit/0600ff7ba94e3f491aeb246d8ddfedd98f0d7276.diff

escapeshellarg / escapeshellcmd: Document multibyte string behavior (#4924)

* escapeshellarg / escapeshellcmd: Document multibyte string behavior

* Fix missing .

* simpara and whitespace fixes

* same for escapeshellarg (fullstop, simpara)

Changed paths:
  M  reference/exec/functions/escapeshellarg.xml
  M  reference/exec/functions/escapeshellcmd.xml


Diff:

diff --git a/reference/exec/functions/escapeshellarg.xml b/reference/exec/functions/escapeshellarg.xml
index 2ccefbdee687..4243ff09e638 100644
--- a/reference/exec/functions/escapeshellarg.xml
+++ b/reference/exec/functions/escapeshellarg.xml
@@ -13,7 +13,7 @@
    <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
@@ -21,14 +21,19 @@
    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">
@@ -38,9 +43,9 @@
     <varlistentry>
      <term><parameter>arg</parameter></term>
      <listitem>
-      <para>
+      <simpara>
        The argument that will be escaped.
-      </para>
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -49,9 +54,9 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
+  <simpara>
    The escaped string.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">
@@ -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>
diff --git a/reference/exec/functions/escapeshellcmd.xml b/reference/exec/functions/escapeshellcmd.xml
index aa90a90f6e8a..0e7787a78aa4 100644
--- a/reference/exec/functions/escapeshellcmd.xml
+++ b/reference/exec/functions/escapeshellcmd.xml
@@ -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
@@ -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">
@@ -40,9 +45,9 @@
     <varlistentry>
      <term><parameter>command</parameter></term>
      <listitem>
-      <para>
+      <simpara>
        The command that will be escaped.
-      </para>
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -51,9 +56,9 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
+  <simpara>
    The escaped string.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">
@@ -68,7 +73,7 @@
 $command = './configure '.$_POST['configure_options'];
 
 $escaped_command = escapeshellcmd($command);
- 
+
 system($escaped_command);
 ?>
 ]]>
@@ -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>
@@ -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>