Opening and Examining Directories

This subsection contains procedures for dealing with existing directories: obtaining a directory handle to be used to qualify path name lookups, converting a (directory handle, relative path name) pair to an absolute path name, and listing the contents of a directory.

  

PROCEDURE OpenDir(
    dir: Dir;
    path: PathName;
    euser: User := NIL)
    : Dir
  RAISES {Error};
  (* NotSuperUserEC, PathES, NotADirectoryEC, FailureES? *)

  OpenDir returns a directory handle for an open directory. This directory handle can then be supplied to Open, OpenDir, and other operations for use as the base for looking up relative path names.

OpenDir performs access checking on the path name up to, but not including, the final component, which must be a directory (or else NotADirectoryEC is raised). Access checking on the actual directory is done each time the directory handle is used by another operation.

OpenDir interprets the euser parameter the same way Open does.

 

PROCEDURE GetPath(
    dir: Dir;
    path: PathName := NIL;
    euser: User := NIL)
    : PathName
  RAISES {Error}; (* NotSuperUserEC, PathES, FailureES? *)

    GetPath accepts a specification of a file by the usual combination of a path name (possibly relative) and a directory handle; it returns an absolute path name for the file that contains no . or .. or symbolic link components.

The path name returned by GetPath consists of an <abspath>, possibly preceded by a <machine> (i.e., a # followed by a machine name). (See section 2.6, page , for the syntax of <abspath> and <machine>.) The <machine> is present if and only if the file or directory to which the path name refers resides on a remote machine. The <abspath> specifies a sequence of directories from the root of the local or specified remote file system (never a symbolic link, or a . or .. entry). Recall that a directory has a unique absolute path name, but a file may have several; it is not predictable which one GetPath returns.

GetPath interprets the euser parameter the same way Open does.

Ultrix note: The current implementation may return a path name containing .. entries. This should be fixed eventually.

   

PROCEDURE ListDir(
    dir: Dir;
    VAR (* IN OUT *) rd: Rd.T;
    euser: User := NIL)
  RAISES {Error}; (* ProtectionViolationEC, FailureES *)

PROCEDURE NextEntry(rd: Rd.T): BOOLEAN RAISES {Error};
  (* ProtectionViolationEC, FailureES *)

      ListDir and NextEntry enumerate the names of the entries in a directory, including the . and .. entries.

ListDir prepares a directory enumeration reader so that it is ready to read the first entry of the specified directory. (The . entry is always returned first.) If ListDir is passed NIL, it allocates a new reader; if it is passed an old reader (that it had returned on an earlier call), ListDir avoids additional allocations.

NextEntry returns TRUE and modifies rd so it is ready to read the next entry if one exists; otherwise it returns FALSE and does not modify the reader.

ListDir and NextEntry raise ProtectionViolationEC if the calling process lacks read access to the directory being enumerated.

Ultrix note: On Ultrix 2.0 systems using NFS, ListDir and NextEntry do not work on remote directories.

Here is a program to list a directory: