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.
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.