From 3440548819e087e97dc950aab0bc0adba0c467e5 Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Tue, 25 Aug 2026 11:05:34 +0200
Subject: [PATCH] [Sync EN] exec: document escapeshellarg()/escapeshellcmd()
 multibyte behavior

---
 reference/exec/functions/escapeshellarg.xml | 24 +++++++++++-------
 reference/exec/functions/escapeshellcmd.xml | 28 +++++++++++++--------
 2 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/reference/exec/functions/escapeshellarg.xml b/reference/exec/functions/escapeshellarg.xml
index 6922579752..74c2eb30e1 100644
--- a/reference/exec/functions/escapeshellarg.xml
+++ b/reference/exec/functions/escapeshellarg.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 60c391265d2a51003e1ed0952e5a2413f81c7fc2 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 0600ff7ba94e3f491aeb246d8ddfedd98f0d7276 Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.escapeshellarg" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -14,7 +14,7 @@
    <type>string</type><methodname>escapeshellarg</methodname>
    <methodparam><type>string</type><parameter>arg</parameter></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    <function>escapeshellarg</function> añade comillas simples
    alrededor de las cadenas de caracteres, y añade
    comillas y escapa las comillas simples de la
@@ -25,14 +25,19 @@
    a pasar al Shell. Las funciones Shell son <function>exec</function>,
    <function>system</function> y los operadores
    <link linkend="language.operators.execution">comillas invertidas</link>.
-  </para>
-  <para>
+  </simpara>
+  <simpara>
    En Windows, <function>escapeshellarg</function> reemplaza en su lugar los
    signos de porcentaje, los signos de exclamación (sustitución de variables
    diferidas) y las comillas dobles con espacios y añade comillas dobles alrededor de la cadena.
    Además, cada serie de barras invertidas consecutivas (<literal>\</literal>)
    es escapada por una barra invertida adicional.
-  </para>
+  </simpara>
+  <simpara>
+   El comportamiento de esta función con cadenas multibyte depende de la
+   configuración regional <constant>LC_CTYPE</constant> actual. Los caracteres
+   no reconocidos serán descartados. Véase <function>setlocale</function>.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -42,9 +47,9 @@
     <varlistentry>
      <term><parameter>arg</parameter></term>
      <listitem>
-      <para>
+      <simpara>
        El argumento a escapar.
-      </para>
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -53,9 +58,9 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
+  <simpara>
    La cadena escapada.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">
@@ -78,6 +83,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 0f4357d43d..82256cc1fc 100644
--- a/reference/exec/functions/escapeshellcmd.xml
+++ b/reference/exec/functions/escapeshellcmd.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 62126c55f1c6ed444043e7272c4f9e233818a44b Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 0600ff7ba94e3f491aeb246d8ddfedd98f0d7276 Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: no -->
 
 <refentry xml:id="function.escapeshellcmd" xmlns="http://docbook.org/ns/docbook">
@@ -15,7 +15,7 @@
    <type>string</type><methodname>escapeshellcmd</methodname>
    <methodparam><type>string</type><parameter>command</parameter></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    <function>escapeshellcmd</function> escapa todos los
    caracteres de la cadena <parameter>command</parameter>
    que podrían tener un significado especial en una
@@ -23,15 +23,20 @@
    correctamente pasada al ejecutor de órdenes Shell
    <function>exec</function> y <function>system</function>, o incluso
    a <link linkend="language.operators.execution">comillas invertidas</link>.
-  </para>
-  <para>
+  </simpara>
+  <simpara>
    Los siguientes caracteres serán escapados:
    <literal>&amp;#;`|*?~&lt;&gt;^()[]{}$\</literal>, <literal>\x0A</literal>
    y <literal>\xFF</literal>. <literal>'</literal> y <literal>"</literal>
    son escapados solo si no están en pares. En Windows, todos estos caracteres
    así como <literal>%</literal> y <literal>!</literal> son precedidos por
    un circunflejo (<literal>^</literal>).
-  </para>
+  </simpara>
+  <simpara>
+   El comportamiento de esta función con cadenas multibyte depende de la
+   configuración regional <constant>LC_CTYPE</constant> actual. Los caracteres
+   no reconocidos serán descartados. Véase <function>setlocale</function>.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -41,9 +46,9 @@
     <varlistentry>
      <term><parameter>command</parameter></term>
      <listitem>
-      <para>
+      <simpara>
        La orden a escapar.
-      </para>
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -52,9 +57,9 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
+  <simpara>
    La cadena escapada.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">
@@ -81,14 +86,14 @@ system($escaped_command);
  <refsect1 role="notes">
   &reftitle.notes;
    <warning xmlns="http://docbook.org/ns/docbook">
-    <para>
+    <simpara>
      La función <function>escapeshellcmd</function> debe ser utilizada
      sobre toda la cadena de orden, y permite
      a personas malintencionadas pasar un número arbitrario
      de argumentos. Para escapar un solo argumento,
      la función <function>escapeshellarg</function> debería ser
      utilizada en su lugar.
-    </para>
+    </simpara>
    </warning>
   <warning xmlns="http://docbook.org/ns/docbook">
    <para>
@@ -110,6 +115,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>