Common Lisp the Language
2nd Edition
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.
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.