Common Lisp the Language, 2nd Edition

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

# 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]
`directory pathname &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.

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.

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