clarified return value of opendir and added example

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@41791 c90b9560-bf6c-de11-be94-00142212c4b1

functions/dir.xml

@@ -148,6 +148,31 @@ $d->close();
      <function>closedir</function>, <function>readdir</function>, and
      <function>rewinddir</function> calls.
     </para>
+    <para>
+     If <parameter>path</parameter> is not a valid directory or the
+     directory can not be opened due to permission restrictions or
+     filesystem errors, <function>opendir</function> returns false and
+     generates a PHP error.  You can suppress the error output of
+     <function>opendir</function> by prepending `@' to the front of
+     the function name.
+    </para>
+    <para>
+     <example>
+      <title><function>opendir</function> Example</title>
+      <programlisting role="php">
+&lt;?php
+
+if ($dir = @opendir("/tmp")) {
+  while($file = readdir($dir)) {
+    echo "$file\n";
+  }  
+  closedir($dir);
+}
+
+?&gt;
+      </programlisting>
+     </example>
+    </para>
    </refsect1>
   </refentry>