[DOC-CVS] [doc-en] master: document potential Windows deadlock (#4000)

Author: divinity76 (divinity76)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-24T15:38:08+02:00

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

document potential Windows deadlock (#4000)

* document potential Windows deadlock

on Windows php's require() and "php file.php" reacts very differently to the LOCK_EX situation, require() will fail immediately (like a LOCK_NB) while cli "php file.php" will wait/hang until ready. Make that clear in the documentation.

* Docbook nits

* filesystem: fix flock.xml deadlock example structure

---------

Co-authored-by: Louis-Arnaud <[email protected]>

Changed paths:
  M  reference/filesystem/functions/flock.xml


Diff:

diff --git a/reference/filesystem/functions/flock.xml b/reference/filesystem/functions/flock.xml
index c157e6890ed2..2579c73bdcc5 100644
--- a/reference/filesystem/functions/flock.xml
+++ b/reference/filesystem/functions/flock.xml
@@ -189,12 +189,32 @@ fclose($fp);
     <literal>FAT</literal> and its derivates and will therefore always
     return &false; under these environments.
    </para>
+   <para>
+    On Windows, if PHP tries to execute a <constant>LOCK_EX</constant>'ed PHP source
+    code file, it will hang until the file is unlocked. The following example will
+    cause a 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>
     On Windows, if the locking process opens the file a second time, it cannot
     access the file through this second handle until it unlocks the file.
    </para>
+   <simpara>
+    On Windows, if you try to require a LOCK_EX'ed file, it will fail with ErrorException: require(): Read of X bytes failed with errno=13 Permission denied
+   </simpara>
   </note>
  </refsect1>