From 62c66edd0cab5db89bc33120e1ebf37e485dc0fc Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Tue, 25 Aug 2026 10:34:09 +0200
Subject: [PATCH] docs(filesystem): document potential Windows deadlock in
 flock()

---
 reference/filesystem/functions/flock.xml | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/reference/filesystem/functions/flock.xml b/reference/filesystem/functions/flock.xml
index d9ed8bcb1..20f6a9608 100644
--- a/reference/filesystem/functions/flock.xml
+++ b/reference/filesystem/functions/flock.xml
@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 75a76afb61d91f04feebc83931c5412b13682d2b Maintainer: PhilDaiguille Status: ready -->
-<!-- Reviewed: no -->
+<!-- EN-Revision: f3112c43e303fcd63c0df89798b45bfef9d49e15 Maintainer: PhilDaiguille Status: ready -->
 <refentry xml:id="function.flock" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>flock</refname>
@@ -191,12 +190,33 @@ fclose($fp);
     anticuados como <literal>FAT</literal> y sus derivados, y por lo tanto
     siempre devolverá &false; en estos entornos.
    </para>
+   <para>
+    En Windows, si PHP intenta ejecutar un fichero de código fuente PHP bloqueado con
+    <constant>LOCK_EX</constant>, el proceso quedará suspendido hasta que el fichero
+    sea desbloqueado. El siguiente ejemplo provocará un bloqueo mutuo (deadlock):
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+if ($argv[1] ?? null === 'child') { die(); }
+$fp = fopen(__FILE__, "rb");
+flock($fp, LOCK_EX);
+shell_exec("php " . escapeshellarg(__FILE__) . " child");
+?>
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
   </warning>
   <note>
    <para>
     En Windows, si el proceso de bloqueo abre el fichero una segunda vez, no podrá
     acceder al fichero a través de este segundo manejador hasta que desbloquee el fichero.
    </para>
+   <simpara>
+    En Windows, si se intenta incluir con require un fichero bloqueado con LOCK_EX,
+    fallará con ErrorException: require(): Read of X bytes failed with errno=13 Permission denied
+   </simpara>
   </note>
  </refsect1>