Skip to main content

19.2 Pathnames

19.2.1 Pathname Components​

A pathname has six components: a host, a device, a directory, a name, a type, and a version.

19.2.1.1 The Pathname Host Component​

The name of the file system on which the file resides, or the name of a logical host.

19.2.1.2 The Pathname Device Component​

Corresponds to the “device” or “file structure” concept in many host file systems: the name of a logical or physical device containing files.

19.2.1.3 The Pathname Directory Component​

Corresponds to the “directory” concept in many host file systems: the name of a group of related files.

19.2.1.4 The Pathname Name Component​

The “name” part of a group of files that can be thought of as conceptually related.

19.2.1.5 The Pathname Type Component​

Corresponds to the “filetype” or “extension” concept in many host file systems. This says what kind of file this is. This component is always a string, nil, :wild, or :unspecific.

19.2.1.6 The Pathname Version Component​

Corresponds to the “version number” concept in many host file systems.

The version is either a positive integer or a symbol from the following list: nil, :wild, :unspecific, or :newest (refers to the largest version number that already exists in the file system when reading a file, or to a version number greater than any already existing in the file system when writing a new file). Implementations can define other special version symbols.

19.2.2 Interpreting Pathname Component Values​

19.2.2.1 Strings in Component Values​

19.2.2.1.1 Special Characters in Pathname Components​

Strings in pathname component values never contain special characters that represent separation between pathname fields, such as slash in Unix filenames. Whether separator characters are permitted as part of a string in a pathname component is implementation-defined; however, if the implementation does permit it, it must arrange to properly “quote” the character for the file system when constructing a namestring. For example,

;; In a TOPS-20 implementation, which uses ^V to quote
(NAMESTRING (MAKE-PATHNAME :HOST "OZ" :NAME "<TEST>"))
→ #P"OZ:PS:^V<TEST^V>"
NOT → #P"OZ:PS:<TEST>"
info

Replaced ∧ with ^

19.2.2.1.2 Case in Pathname Components​

Namestrings always use local file system case conventions, but Common Lisp functions that manipulate pathname components allow the caller to select either of two conventions for representing case in component values by supplying a value for the :case keyword argument. Figure 19–2 lists the functions relating to pathnames that permit a :case argument:

|make-pathname pathname-directory pathname-name pathname-device pathname-host pathname-type|

| :- |

Figure 19–2. Pathname functions using a :CASE argument

19.2.2.1.2.1 Local Case in Pathname Components​

For the functions in Figure 19–2, a value of :local for the :case argument (the default for these functions) indicates that the functions should receive and yield strings in component values as if they were already represented according to the host file system’s convention for case.

If the file system supports both cases, strings given or received as pathname component values under this protocol are to be used exactly as written. If the file system only supports one case, the strings will be translated to that case.

19.2.2.1.2.2 Common Case in Pathname Components​

For the functions in Figure 19–2, a value of :common for the :case argument that these functions should receive and yield strings in component values according to the following conventions:

• All uppercase means to use a file system’s customary case.

• All lowercase means to use the opposite of the customary case.

• Mixed case represents itself.

Note that these conventions have been chosen in such a way that translation from :local to :common and back to :local is information-preserving.

19.2.2.2 Special Pathname Component Values​

19.2.2.2.1 NIL as a Component Value​

As a pathname component value, nilrepresents that the component is “unfilled”; see Section 19.2.3 (Merging Pathnames).

The value of any pathname component can be nil.

When constructing a pathname, nil in the host component might mean a default host rather than an actual nil in some implementations.

WILD as a Component Value​

If :wild is the value of a pathname component, that component is considered to be a wildcard, which matches anything.

A conforming program must be prepared to encounter a value of :wild as the value of any pathname component, or as an element of a list that is the value of the directory component.

When constructing a pathname, a conforming program may use :wild as the value of any or all of the directory, name, type, or version component, but must not use :wild as the value of the host, or device component.

If :wild is used as the value of the directory component in the construction of a pathname, the effect is equivalent to specifying the list (:absolute :wild-inferiors), or the same as (:absolute :wild) in a file system that does not support :wild-inferiors.

UNSPECIFIC as a Component Value​

If :unspecific is the value of a pathname component, the component is considered to be “absent” or to “have no meaning” in the filename being represented by the pathname.

Whether a value of :unspecific is permitted for any component on any given file system accessible to the implementation is implementation-defined. A conforming program must never unconditionally use a :unspecific as the value of a pathname component because such a value is not guaranteed to be permissible in all implementations. However, a conforming program can, if it is careful, successfully manipulate user-supplied data which contains or refers to non-portable pathname components. And certainly a conforming program should be prepared for the possibility that any components of a pathname could be :unspecific.

When reading1 the value of any pathname component, conforming programs should be prepared for the value to be :unspecific.

When writing1 the value of any pathname component, the consequences are undefined if :unspecific is given for a pathname in a file system for which it does not make sense.

19.2.2.2.3.1 Relation between component values NIL and​

If a pathname is converted to a namestring, the symbols nil and :unspecific cause the field to be treated as if it were empty. That is, both nil and :unspecific cause the component not to appear in the namestring.

However, when merging a pathname with a set of defaults, only a nil value for a component will be replaced with the default for that component, while a value of :unspecific will be left alone as if the field were “filled”; see the function merge-pathnames and Section 19.2.3 (Merging Pathnames).

19.2.2.3 Restrictions on Wildcard Pathnames​

Wildcard pathnames can be used with directory but not with open, and return true from wild-pathname-p. When examining wildcard components of a wildcard pathname, conforming programs must be prepared to encounter any of the following additional values in any component or any element of a list that is the directory component:

• The symbol :wild, which matches anything.

• A string containing implementation-dependent special wildcard characters.

• Any object, representing an implementation-dependent wildcard pattern.

19.2.2.4 Restrictions on Examining Pathname Components​

The space of possible objects that a conforming program must be prepared to read 1 as the value of a pathname component is substantially larger than the space of possible objects that a conforming program is permitted to write1 into such a component.

While the values discussed in the subsections of this section, in Section 19.2.2.2 (Special Pathname Component Values), and in Section 19.2.2.3 (Restrictions on Wildcard Pathnames) apply to values that might be seen when reading the component values, substantially more restrictive rules apply to constructing pathnames; see Section 19.2.2.5 (Restrictions on Constructing Pathnames).

When examining pathname components, conforming programs should be aware of the following restrictions.

19.2.2.4.1 Restrictions on Examining a Pathname Host Component​

It is implementation-dependent what object is used to represent the host.

19.2.2.4.2 Restrictions on Examining a Pathname Device Component​

The device might be a string, :wild, :unspecific, or nil.

Note that :wild might result from an attempt to read 1 the pathname component, even though portable programs are restricted from writing1 such a component value; see Section 19.2.2.3 (Restrictions on Wildcard Pathnames) and Section 19.2.2.5 (Restrictions on Constructing Pathnames).

19.2.2.4.3 Restrictions on Examining a Pathname Directory Component​

The directory might be a string, :wild, :unspecific, or nil.

The directory can be a list of strings and symbols. The car of the list is one of the symbols :absolute or :relative, meaning:

:absolute

A list whose car is the symbol :absolute represents a directory path starting from the root direc tory. The list (:absolute) represents the root directory. The list (:absolute "foo" "bar" "baz") represents the directory called "/foo/bar/baz" in Unix (except possibly for case).

:relative

A list whose car is the symbol :relative represents a directory path starting from a default directory. The list (:relative) has the same meaning as nil and hence is not used. The list (:relative "foo" "bar") represents the directory named "bar" in the directory named "foo" in the default directory.

Each remaining element of the list is a string or a symbol.

Each string names a single level of directory structure. The strings should contain only the directory names themselves—no punctuation characters.

In place of a string, at any point in the list, symbols can occur to indicate special file notations. Figure 19–3 lists the symbols that have standard meanings. Implementations are permitted to add additional objects of any type that is disjoint from string if necessary to represent features of their file systems that cannot be represented with the standard strings and symbols.

Supplying any non-string, including any of the symbols listed below, to a file system for which it does not make sense signals an error of type file-error. For example, Unix does not support :wild-inferiors in most implementations.

|Symbol Meaning|

| :- |

|

:wild Wildcard match of one level of directory structure :wild-inferiors Wildcard match of any number of directory levels :up Go upward in directory structure (semantic)

:back Go upward in directory structure (syntactic)

|

Figure 19–3. Special Markers In Directory Component

The following notes apply to the previous figure:

Invalid Combinations

Using :absolute or :wild-inferiors immediately followed by :up or :back signals an error of type file-error.

Syntactic vs Semantic

“Syntactic” means that the action of :back depends only on the pathname and not on the contents of the file system.

“Semantic” means that the action of :up depends on the contents of the file system; to resolve a pathname containing :up to a pathname whose directory component contains only :absolute and strings requires probing the file system.

:up differs from :back only in file systems that support multiple names for directories, perhaps via symbolic links. For example, suppose that there is a directory (:absolute "X" "Y" "Z") linked to (:absolute "A" "B" "C") and there also exist directories (:absolute "A" "B" "Q") and (:absolute "X" "Y" "Q"). Then (:absolute "X" "Y" "Z" :up "Q") desig

nates (:absolute "A" "B" "Q") while (:absolute "X" "Y" "Z" :back "Q") designates (:absolute "X" "Y" "Q")

19.2.2.4.3.1 Directory Components in Non​

In non-hierarchical file systems, the only valid list values for the directory component of a pathname are (:absolute string) and (:absolute :wild). :relative directories and the keywords :wild-inferiors, :up, and :back are not used in non-hierarchical file systems.

19.2.2.4.4 Restrictions on Examining a Pathname Name Component​

The name might be a string, :wild, :unspecific, or nil.

19.2.2.4.5 Restrictions on Examining a Pathname Type Component​

The type might be a string, :wild, :unspecific, or nil.

19.2.2.4.6 Restrictions on Examining a Pathname Version Component​

The version can be any symbol or any integer .

The symbol :newest refers to the largest version number that already exists in the file system when reading, overwriting, appending, superseding, or directory listing an existing file. The symbol :newest refers to the smallest version number greater than any existing version number when creating a new file.

The symbols nil, :unspecific, and :wild have special meanings and restrictions; see Section 19.2.2.2 (Special Pathname Component Values) and Section 19.2.2.5 (Restrictions on Constructing Pathnames).

Other symbols and integers have implementation-defined meaning.

19.2.2.4.7 Notes about the Pathname Version Component​

It is suggested, but not required, that implementations do the following:

• Use positive integers starting at 1 as version numbers.

• Recognize the symbol :oldest to designate the smallest existing version number. • Use keywords for other special versions.

19.2.2.5 Restrictions on Constructing Pathnames​

When constructing a pathname from components, conforming programs must follow these rules:

• Any component can be nil. nil in the host might mean a default host rather than an actual nil in some implementations.

• The host, device, directory, name, and type can be strings. There are implementation dependent limits on the number and type of characters in these strings.

• The directory can be a list of strings and symbols. There are implementation-dependent limits on the list’s length and contents.

• The version can be :newest.

• Any component can be taken from the corresponding component of another pathname. When the two pathnames are for different file systems (in implementations that support multiple file systems), an appropriate translation occurs. If no meaningful translation is possible, an error is signaled. The definitions of “appropriate” and “meaningful” are implementation-dependent.

• An implementation might support other values for some components, but a portable program cannot use those values. A conforming program can use implementation-dependent values but this can make it non-portable; for example, it might work only with Unix file systems.

19.2.3 Merging Pathnames​

Merging takes a pathname with unfilled components and supplies values for those components from a source of defaults.

If a component’s value is nil, that component is considered to be unfilled. If a component’s value is any non-nil object, including :unspecific, that component is considered to be filled.

Except as explicitly specified otherwise, for functions that manipulate or inquire about files in the file system, the pathname argument to such a function is merged with *default-pathname-defaults* before accessing the file system (as if by merge-pathnames).

19.2.3.1 Examples of Merging Pathnames​

Although the following examples are possible to execute only in *implementations* which permit :unspecific in the indicated position andwhich permit four-letter type components, they serve to illustrate the basic concept of *pathname* merging. 
(pathname-type 
 (merge-pathnames (make-pathname :type "LISP") 
		  (make-pathname :type "TEXT"))) 
→ "LISP" 
(pathname-type 
 (merge-pathnames (make-pathname :type nil) 
		  (make-pathname :type "LISP"))) 
→ "LISP" 
(pathname-type 
 (merge-pathnames (make-pathname :type :unspecific) 
		  (make-pathname :type "LISP"))) 
→ :UNSPECIFIC