diff --git a/functions/filesystem.xml b/functions/filesystem.xml
index da03069e9e..98b6557620 100644
--- a/functions/filesystem.xml
+++ b/functions/filesystem.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.94 $ -->
+<!-- $Revision: 1.95 $ -->
  <reference id="ref.filesystem">
   <title>Filesystem functions</title>
   <titleabbrev>Filesystem</titleabbrev>
@@ -1152,7 +1152,7 @@ $fcontents = join ('', file ('http://www.php.net'));
     <simpara>
      <function>flock</function> allows you to perform a simple
      reader/writer model which can be used on virtually every platform
-     (including most Unices and even Windows).  The optional 3rd
+     (including most Unix derivatives and even Windows).  The optional third
      argument is set to &true; if the lock would block (EWOULDBLOCK
      errno condition)
     </simpara>
@@ -1160,13 +1160,26 @@ $fcontents = join ('', file ('http://www.php.net'));
      <function>flock</function> returns &true; on success and &false; on
      error (e.g. when a lock could not be acquired).
     </simpara>
+    <note>
+     <para>
+      Because <function>flock</function> requires a file pointer, you may have
+      to use a special lock file to protect access to a file that you intend
+      to truncate by opening it in write mode (with a "w" or "w+" argument to
+      <function>fopen</function>).
+     </para>
+    </note>
     <warning>
      <para>
-      On most operation systems <function>flock</function> is implemented
-      at the process level. When using a multithreaded server API like
-      ISAPI you cannot rely on <function>flock</function> to protect
-      files against other PHP scripts running in parallel threads of the
-      same server instance!
+      <function>flock</function> will not work on NFS and many other networked
+      file systems. Check your operating system documentation for more
+      details.
+     </para>
+     <para>
+      On some operating systems <function>flock</function> is implemented at
+      the process level. When using a multithreaded server API like ISAPI you
+      may not be able to rely on <function>flock</function> to protect files
+      against other PHP scripts running in parallel threads of the same server
+      instance!
      </para>
     </warning>
    </refsect1>