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

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. The next figure lists the functions relating to pathnames that permit 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, nil represents 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.

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

19.2.2.2.3 :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 reading₁ the value of any pathname component, conforming programs should be prepared for the value to be :unspecific.

When writing₁ 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 :UNSPECIFIC

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₁

as the value of a pathname component is substantially larger than the space of possible objects that a conforming program is permitted to write₁

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₁

the pathname component, even though portable programs are restricted from writing₁ 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 directory. 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. The next figure 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.

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") designates (: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-Hierarchical File Systems

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.