diff --git a/functions/filesystem.xml b/functions/filesystem.xml
index 56023b64c5..42b0fd61f4 100644
--- a/functions/filesystem.xml
+++ b/functions/filesystem.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.117 $ -->
+<!-- $Revision: 1.118 $ -->
  <reference id="ref.filesystem">
   <title>Filesystem functions</title>
   <titleabbrev>Filesystem</titleabbrev>
@@ -2348,7 +2348,7 @@ html
      <function>fputs</function>.
     </para>
     <para>
-     If an error occurs, returns &false;.
+     If an error occurs, returns &false;. 
     </para>
     <para>
      <informalexample>
@@ -2359,6 +2359,29 @@ $fp = popen ("/bin/ls", "r");
       </programlisting>
      </informalexample>
     </para>
+    <note>
+     <para>
+      If the command to be executed could not be found, a valid
+      resource is returned. This may seem odd, but makes sense; it
+      allows you to access any error message returned by the shell:
+      <informalexample>
+       <programlisting role="php">
+<![CDATA[
+<?php
+error_reporting(E_ALL);
+
+/* Add redirection so we can get stderr. */
+$fp = popen('/path/to/spooge 2>&1', 'r');
+echo "'$fp'; " . gettype($fp) . "\n";
+$read = fread($fp, 2096);
+echo $read;
+pclose($fp);
+?>
+]]>
+       </programlisting>
+      </informalexample>
+     </para>
+    </note>
     <para>
      See also <function>pclose</function>.
     </para>