From a69791e5e3b463e366199d4ab9fc1b9b0edb247c Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Wed, 21 Oct 2026 09:29:27 +0200
Subject: [PATCH] [Sync-En] sem, shmop: document errors on detached segments,
 auto_release warning and shmop fixes

---
 reference/sem/entities.ent                 | 20 ++++++++++++++++++++
 reference/sem/functions/sem-get.xml        | 12 +++++++++++-
 reference/sem/functions/shm-detach.xml     |  7 ++++++-
 reference/sem/functions/shm-get-var.xml    | 15 +++++++++++----
 reference/sem/functions/shm-has-var.xml    |  9 +++++++--
 reference/sem/functions/shm-put-var.xml    |  7 ++++++-
 reference/sem/functions/shm-remove-var.xml |  7 ++++++-
 reference/sem/functions/shm-remove.xml     |  7 ++++++-
 reference/shmop/functions/shmop-delete.xml | 14 ++++++++++++--
 reference/shmop/functions/shmop-open.xml   | 22 ++++++++++++----------
 reference/shmop/functions/shmop-write.xml  |  6 +++---
 11 files changed, 100 insertions(+), 26 deletions(-)
 create mode 100644 reference/sem/entities.ent

diff --git a/reference/sem/entities.ent b/reference/sem/entities.ent
new file mode 100644
index 0000000000..c8a6033c3e
--- /dev/null
+++ b/reference/sem/entities.ent
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: 589b2024573a14b6a4d286e5ec9aad614b36c6fa Maintainer: lacatoire Status: ready -->
+<!-- Reviewed: no -->
+<!--
+    See `manual.xml` for XML namespaces defaults.
+    Keep the lines under 79 columns, to make the process of manual
+    translation easier, and to avoid wrap-around in some other contexts.
+-->
+<entities xmlns       = "http://docbook.org/ns/docbook"
+          xmlns:xlink = "http://www.w3.org/1999/xlink"
+          translate   = "yes">
+
+<entity name="ext.sem.shm-detached-error">
+ <simpara>
+  Lanza un <exceptionname>Error</exceptionname> si <parameter>shm</parameter>
+  ya ha sido liberado con <function>shm_detach</function>.
+ </simpara>
+</entity>
+
+</entities>
diff --git a/reference/sem/functions/sem-get.xml b/reference/sem/functions/sem-get.xml
index 93975ee575..074c9ff0cd 100644
--- a/reference/sem/functions/sem-get.xml
+++ b/reference/sem/functions/sem-get.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: fd2f14b2e44fbda6dd3f94a1d07f2bc9a7567aff Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: e1ed939373254ebf51ed7822d1a700eb4abeb3a1 Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: no -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.sem-get">
  <refnamediv>
@@ -125,6 +125,16 @@
     semáforo.
    </simpara>
   </warning>
+  <warning>
+   <simpara>
+    Si <parameter>auto_release</parameter> está habilitado, las reservas mantenidas por un
+    objeto <classname>SysvSemaphore</classname> también se liberan en cuanto el
+    objeto es liberado, por ejemplo cuando la variable que lo contiene es eliminada
+    con unset, sobrescrita o sale del ámbito, y no solo al finalizar la petición.
+    Conserve una referencia al objeto durante todo el tiempo que el semáforo deba
+    permanecer reservado.
+   </simpara>
+  </warning>
  </refsect1>
 
  <refsect1 role="seealso">
diff --git a/reference/sem/functions/shm-detach.xml b/reference/sem/functions/shm-detach.xml
index bed54c9060..07eb882232 100644
--- a/reference/sem/functions/shm-detach.xml
+++ b/reference/sem/functions/shm-detach.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 5b7646656eb183ea568b8261d6d87a10a1b961c7 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 589b2024573a14b6a4d286e5ec9aad614b36c6fa Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: yes -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.shm-detach">
  <refnamediv>
@@ -45,6 +45,11 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  &ext.sem.shm-detached-error;
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/sem/functions/shm-get-var.xml b/reference/sem/functions/shm-get-var.xml
index 3113000ac8..45b0034177 100644
--- a/reference/sem/functions/shm-get-var.xml
+++ b/reference/sem/functions/shm-get-var.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: fd2f14b2e44fbda6dd3f94a1d07f2bc9a7567aff Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 589b2024573a14b6a4d286e5ec9aad614b36c6fa Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: yes -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.shm-get-var">
  <refnamediv>
@@ -17,8 +17,8 @@
   </methodsynopsis>
   <simpara>
    <function>shm_get_var</function> devuelve la variable
-   identificada por <parameter>variable_key</parameter>, en
-   el segmento de memoria compartida identificado por <parameter>shm_identifier</parameter>.
+   identificada por <parameter>key</parameter>, en
+   el segmento de memoria compartida identificado por <parameter>shm</parameter>.
    La variable siempre está presente en la memoria
    compartida.
   </simpara>
@@ -50,9 +50,16 @@
   &reftitle.returnvalues;
   <simpara>
    Devuelve la variable correspondiente a la clave dada.
+   Si la clave no existe, se emite un <constant>E_WARNING</constant>
+   y se devuelve &false;.
   </simpara>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  &ext.sem.shm-detached-error;
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
@@ -82,7 +89,7 @@
    <member><function>shm_has_var</function></member>
    <member><function>shm_put_var</function></member>
   </simplelist>
-  </refsect1>
+ </refsect1>
 
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/sem/functions/shm-has-var.xml b/reference/sem/functions/shm-has-var.xml
index 83733f3e0d..9a65a1ea52 100644
--- a/reference/sem/functions/shm-has-var.xml
+++ b/reference/sem/functions/shm-has-var.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: fd2f14b2e44fbda6dd3f94a1d07f2bc9a7567aff Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 589b2024573a14b6a4d286e5ec9aad614b36c6fa Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: yes -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.shm-has-var">
  <refnamediv>
@@ -35,7 +35,7 @@
     <term><parameter>key</parameter></term>
     <listitem>
      <simpara>
-      El nombre de la variable.
+      La clave de la variable.
      </simpara>
     </listitem>
    </varlistentry>
@@ -49,6 +49,11 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  &ext.sem.shm-detached-error;
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/sem/functions/shm-put-var.xml b/reference/sem/functions/shm-put-var.xml
index 285874ec57..3bb787c0f7 100644
--- a/reference/sem/functions/shm-put-var.xml
+++ b/reference/sem/functions/shm-put-var.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: fd2f14b2e44fbda6dd3f94a1d07f2bc9a7567aff Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 589b2024573a14b6a4d286e5ec9aad614b36c6fa Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: yes -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.shm-put-var">
  <refnamediv>
@@ -70,6 +70,11 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  &ext.sem.shm-detached-error;
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/sem/functions/shm-remove-var.xml b/reference/sem/functions/shm-remove-var.xml
index cb64cce52b..328ae10ee0 100644
--- a/reference/sem/functions/shm-remove-var.xml
+++ b/reference/sem/functions/shm-remove-var.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: fd2f14b2e44fbda6dd3f94a1d07f2bc9a7567aff Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 589b2024573a14b6a4d286e5ec9aad614b36c6fa Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: yes -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.shm-remove-var">
  <refnamediv>
@@ -51,6 +51,11 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  &ext.sem.shm-detached-error;
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/sem/functions/shm-remove.xml b/reference/sem/functions/shm-remove.xml
index 2a05a1fef4..373bc5c161 100644
--- a/reference/sem/functions/shm-remove.xml
+++ b/reference/sem/functions/shm-remove.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: fd2f14b2e44fbda6dd3f94a1d07f2bc9a7567aff Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 589b2024573a14b6a4d286e5ec9aad614b36c6fa Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: yes -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.shm-remove">
  <refnamediv>
@@ -42,6 +42,11 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  &ext.sem.shm-detached-error;
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/shmop/functions/shmop-delete.xml b/reference/shmop/functions/shmop-delete.xml
index 28ed1c88ab..0d6fc177a9 100644
--- a/reference/shmop/functions/shmop-delete.xml
+++ b/reference/shmop/functions/shmop-delete.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 41d34439ea8cae2bb1204264c1bce15d88284503 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: b189a6891d709765f37c6843cbf4f58d44ed847b Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: yes -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.shmop-delete">
  <refnamediv>
@@ -14,7 +14,9 @@
    <methodparam><type>Shmop</type><parameter>shmop</parameter></methodparam>
   </methodsynopsis>
   <simpara>
-   <function>shmop_delete</function> se utiliza para destruir un bloque de memoria compartida.
+   <function>shmop_delete</function> marca un bloque de memoria compartida para su
+   eliminación. El bloque solo se destruye cuando todos los procesos se han
+   desvinculado de él.
   </simpara>
  </refsect1>
  <refsect1 role="parameters">
@@ -38,6 +40,14 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <simpara>
+   Si el bloque no puede marcarse para su eliminación, por ejemplo porque el
+   usuario actual no es su propietario, se emite un <constant>E_WARNING</constant>.
+  </simpara>
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/shmop/functions/shmop-open.xml b/reference/shmop/functions/shmop-open.xml
index 652d9c86d5..8348a96643 100644
--- a/reference/shmop/functions/shmop-open.xml
+++ b/reference/shmop/functions/shmop-open.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 41d34439ea8cae2bb1204264c1bce15d88284503 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: b189a6891d709765f37c6843cbf4f58d44ed847b Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: yes -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.shmop-open">
  <refnamediv>
@@ -49,7 +49,7 @@
         </listitem>
         <listitem>
          <simpara>
-          <literal>"c"</literal> para creación (utiliza <literal>IPC_CREATE</literal>)
+          <literal>"c"</literal> para creación (utiliza <literal>IPC_CREAT</literal>)
           utilice esta opción para crear un nuevo bloque, o, si un
           segmento con el mismo identificador existe, intentar acceder a él en
           modo lectura y escritura.
@@ -66,9 +66,9 @@
         <listitem>
          <simpara>
           <literal>"n"</literal> crea un nuevo segmento de memoria compartida
-          (utiliza <literal>IPC_CREATE|IPC_EXCL</literal>). Utilice esta opción
+          (utiliza <literal>IPC_CREAT|IPC_EXCL</literal>). Utilice esta opción
           cuando se quiera crear un nuevo segmento de memoria
-          compartida a menos que ya exista uno corrupto con la
+          compartida, pero que falle si ya existe uno con la
           misma opción. Esto es muy útil por razones de seguridad, para evitar
           agujeros de seguridad que exploten la carrera por los recursos.
          </simpara>
@@ -115,8 +115,9 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <simpara>
-   Si <parameter>mode</parameter> es inválido, o si <parameter>size</parameter> es inferior o igual a cero,
-   se lanza una <classname>ValueError</classname>.
+   Si <parameter>mode</parameter> es inválido, o si <parameter>size</parameter> es inferior o igual a cero
+   para los modos <literal>"c"</literal> y <literal>"n"</literal>,
+   se lanza una <exceptionname>ValueError</exceptionname>.
    En otros casos de fallo, se emite un <constant>E_WARNING</constant>.
   </simpara>
  </refsect1>
@@ -135,15 +136,16 @@
      <row>
       <entry>8.0.0</entry>
       <entry>
-       <parameter>shmop</parameter> ahora espera una instancia de <classname>Shmop</classname>
-       anteriormente se esperaba un <type>resource</type>.
+       En caso de éxito, esta función devuelve ahora una instancia de <classname>Shmop</classname>;
+       anteriormente se devolvía un <type>resource</type>.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
-       Si <parameter>mode</parameter> es inválido, o si <parameter>size</parameter> es inferior o igual a cero,
-       se lanza una <classname>ValueError</classname>; anteriormente, se emitía un <constant>E_WARNING</constant> en su lugar,
+       Si <parameter>mode</parameter> es inválido, o si <parameter>size</parameter> es inferior o igual a cero
+       para los modos <literal>"c"</literal> y <literal>"n"</literal>,
+       se lanza una <exceptionname>ValueError</exceptionname>; anteriormente, se emitía un <constant>E_WARNING</constant> en su lugar,
        y la función devolvía &false;.
       </entry>
      </row>
diff --git a/reference/shmop/functions/shmop-write.xml b/reference/shmop/functions/shmop-write.xml
index 81f185699f..61a659f109 100644
--- a/reference/shmop/functions/shmop-write.xml
+++ b/reference/shmop/functions/shmop-write.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 41d34439ea8cae2bb1204264c1bce15d88284503 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: b189a6891d709765f37c6843cbf4f58d44ed847b Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: yes -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.shmop-write">
  <refnamediv>
@@ -62,8 +62,8 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <simpara>
-   Si <parameter>offset</parameter> está fuera de límite, o si un segmento de memoria compartida
-   de solo lectura debe ser escrito, se levanta una <classname>ValueError</classname>.
+   Si <parameter>offset</parameter> está fuera de rango, se lanza una <exceptionname>ValueError</exceptionname>.
+   Si el segmento de memoria compartida se abrió en modo solo lectura, se lanza un <exceptionname>Error</exceptionname>.
   </simpara>
  </refsect1>