From 37d2d048ac172a5179cc9c637303dfddee15e32c Mon Sep 17 00:00:00 2001
From: Torben Wilson <torben@php.net>
Date: Sun, 10 Feb 2002 18:47:27 +0000
Subject: [PATCH] Clarified readdir() a bit.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@69971 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/dir.xml | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/functions/dir.xml b/functions/dir.xml
index 818b11a097..31999e00bd 100644
--- a/functions/dir.xml
+++ b/functions/dir.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.30 $ -->
+<!-- $Revision: 1.31 $ -->
  <reference id="ref.dir">
   <title>Directory functions</title>
   <titleabbrev>Directories</titleabbrev>
@@ -209,7 +209,17 @@ if ($dir = @opendir("/tmp")) {
      </methodsynopsis>
     <para>
      Returns the filename of the next file from the directory. The
-     filenames are not returned in any particular order.
+     filenames are returned in the order in which they are stored by
+     the filesystem.
+    </para>
+    <para>
+     Please note the fashion in which <function>readdir</function>'s
+     return value is checked in the examples below. We are explicitly
+     testing whether the return value is equal and identical to
+     &false; since otherwise, any directory entry whose name evaluates
+     to &false; will stop the loop.
+    </para>
+    <para>
      <example>
       <title>List all files in the current directory</title>
       <programlisting role="php">
@@ -219,9 +229,17 @@ if ($dir = @opendir("/tmp")) {
 $handle=opendir('.');
 echo "Directory handle: $handle\n";
 echo "Files:\n";
+
+/* This is the correct way to loop over the directory. */
 while (false !== ($file = readdir($handle))) { 
     echo "$file\n";
 }
+
+/* This is the WRONG way to loop over the directory. */
+while ($file = readdir($handle)) { 
+    echo "$file\n";
+}
+
 closedir($handle); 
 ?>
 ]]>