23.5. Accessing Directories

The following function is a very simple portable primitive for examining a directory. Most file systems can support much more powerful directory-searching primitives, but no two are alike. It is expected that most implementations of Common Lisp will extend the directory function or provide more powerful primitives.

[Function]
directorypathname&key

A list of pathnames is returned, one for each file in the file system that matches the given pathname. (The pathname argument may be a pathname, a string, or a stream associated with a file.) For a file that matches, the truename appears in the result list. If no file matches the pathname, it is not an error; directory simply returns nil, the list of no results. Keywords such as :wild and :newest may be used in pathname to indicate the search space.

change_begin
X3J13 voted in March 1988 (PATHNAME-STREAM) to specify exactly which streams may be used as pathnames. See section 23.1.6.

X3J13 voted in January 1989 (CLOSED-STREAM-OPERATIONS) to specify that directory is unaffected by whether the first argument, if a stream, is open or closed. If the first argument is a stream, directory behaves as if the function pathname were applied to the stream and the resulting pathname used instead. However, X3J13 commented that the treatment of open streams may differ considerably from one implementation to another; for example, in some operating systems open files are written under a temporary or invisible name and later renamed when closed. In general, programmers writing code intended to be portable should be careful when using directory.

X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require directory to accept logical pathnames (see section 23.1.5). However, the result returned by directory never contains a logical pathname.
change_end

Implementation note: It is anticipated that an implementation may need to provide additional parameters to control the directory search. Therefore directory is specified to take additional keyword arguments so that implementations may experiment with extensions, even though no particular keywords are specified here.

As a simple example of such an extension, for a file system that supports the notion of cross-directory file links, a keyword argument :links might, if non-nil, specify that such links be included in the result list.

Next: Errors Up: File System Interface Previous: Loading Files

AI.Repository@cs.cmu.edu