dart:io | Ensure that Directory.list terminates even when symbolic links create loops in the file s…

sdk/lib/io/directory.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * [Directory] objects are used for working with directories.
  */
 abstract class Directory extends FileSystemEntity {
@@ skipping 134 matching lines @@
    * Lists the sub-directories and files of this [Directory].
    * Optionally recurses into sub-directories.
    *
    * If [followLinks] is false, then any symbolic links found
    * are reported as [Link] objects, rather than as directories or files,
    * and are not recursed into.
    *
    * If [followLinks] is true, then working links are reported as
    * directories or files, depending on
    * their type, and links to directories are recursed into.
-   * Broken links are reported as [Link] objects,
+   * Broken links are reported as [Link] objects.
+   * If a symbolic link makes a loop in the file system, then a recursive
+   * listing will not follow a link twice in the
+   * same recursive descent, but will report it as a [Link]
+   * the second time it is seen.
    *
    * The result is a stream of [FileSystemEntity] objects
    * for the directories, files, and links.
    */
   Stream<FileSystemEntity> list({bool recursive: false,
                                  bool followLinks: true});
 
   /**
    * Lists the sub-directories and files of this [Directory].
    * Optionally recurses into sub-directories.
    *
    * If [followLinks] is false, then any symbolic links found
    * are reported as [Link] objects, rather than as directories or files,
    * and are not recursed into.
    *
    * If [followLinks] is true, then working links are reported as
    * directories or files, depending on
    * their type, and links to directories are recursed into.
-   * Broken links are reported as [Link] objects,
+   * Broken links are reported as [Link] objects.
+   * If a link makes a loop in the file system, then a recursive
+   * listing will not follow a link twice in the
+   * same recursive descent, but will report it as a [Link]
+   * the second time it is seen.
    *
    * Returns a [List] containing [FileSystemEntity] objects for the
    * directories, files, and links.
    */
   List<FileSystemEntity> listSync({bool recursive: false,
                                    bool followLinks: true});
 
   /**
    * Returns a human readable string for this Directory instance.
    */
@@ skipping 26 matching lines @@
       if (path != null) {
         sb.write(", path = $path");
       }
     }
     return sb.toString();
   }
   final String message;
   final String path;
   final OSError osError;
 }