19. Filenames

• 19.1 Overview of Filenames
• 19.2 Pathnames
• 19.3 Logical Pathnames
• Dictionary

19.1 Overview of Filenames#

There are many kinds of file systems, varying widely both in their superficial syntactic details, and in their underlying power and structure. The facilities provided by Common Lisp for referring to and manipulating files has been chosen to be compatible with many kinds of file systems, while at the same time minimizing the program-visible differences between kinds of file systems.

23.1.0 1Since file systems vary in their conventions for naming files, there are two distinct ways to represent filenames: as namestrings and as pathnames.

19.1.1 Namestrings as Filenames#

In general, the syntax of namestrings involves the use of implementation-defined conventions, usually those customary for the file system in which the named file resides. The only exception is the syntax of a logical pathname namestring, which is defined in this specification; see Section 19.3.1 (Syntax of Logical Pathname Namestrings).

A conforming program must never unconditionally use a literal namestring other than a logical pathname namestring because Common Lisp does not define any namestring syntax other than that for logical pathnames that would be guaranteed to be portable. However, a conforming program can, if it is careful, successfully manipulate user-supplied data which contains or refers to non-portable namestrings.

23.1.1 11A namestring can be coerced to a pathname by the functions pathname or parse-namestring. Not true for logical pathnames. Anyway, better said (if at all) in the function entries. The effect of these \term{functions} is necessarily \term{implementation-dependent} because the format of \term{namestrings} is \term{implementation-dependent}.

19.1.2 Pathnames as Filenames#

From Chapter 21.1 ... \term{Pathnames} provide a means for expressing many operations that manipulate files or file names in a manner that does not depend on the specific format of file names on a particular file system.

Pathnames are structured objects that can represent, in an implementation-independent way, the filenames that are used natively by an underlying file system.

In addition, pathnames can also represent certain partially composed filenames for which an underlying file system might not have a specific namestring representation.

23.1.1 10 A \term{pathname} is not necessarily the name of a specific file. Rather, it is a specification (possibly only a partial specification) of how to access a file.

A pathname need not correspond to any file that actually exists, and more than one pathname can refer to the same file. For example, the pathname with a version of :newest might refer to the same file as a pathname with the same components except a certain number as the version. Indeed, a pathname with version :newest might refer to different files as time passes, because the meaning of such a pathname depends on the state of the file system.

Some file systems naturally use a structural model for their filenames, while others do not. Within the Common Lisp pathname model, all filenames are seen as having a particular structure, even if that structure is not reflected in the underlying file system. The nature of the mapping between structure imposed by pathnames and the structure, if any, that is used by the underlying file system is implementation-defined.

23.1.0 2 In order to allow code to operate in a network environment that may have more than one kind of file system, the pathname facility allows a file name to specify which file system (called the host) is to be used. Left out.

23.1.1 3Every pathname has six components: a host, a device, a directory, a name, a type, and a version. By naming files with pathnames, Common Lisp programs can work in essentially the same way even in file systems that seem superficially quite different. For a detailed description of these components, see Section 19.2.1 (Pathname Components).

Per X3J13. -kmp 5-Oct-93 The mapping of the \term{pathname} components into the concepts peculiar to each \term{file system} is \term{implementation-defined}. There exist conceivable \term{pathnames} for which there is no valid mapping in a particular \term{implementation}. The time at which this error detection occurs is \term{implementation-dependent}.The mapping of the pathname components into the concepts peculiar to each file system is implementation-defined. There exist conceivable pathnames for which there is no mapping to a syntactically valid filename in a particular implementation. An implementation may use various strategies in an attempt to find a mapping; for example, an implementation may quietly truncate filenames that exceed length limitations imposed by the underlying file system, or ignore certain pathname components for which the file system provides no support. If such a mapping cannot be found, an error of type file-error is signaled.

The time at which this mapping and associated error signaling occurs is implementation-dependent. Specifically, it may occur at the time the pathname is constructed, when coercing a pathname to a namestring, or when an attempt is made to open or otherwise access the file designated by the pathname.

The next figure lists some defined names that are applicable to pathnames.

19.1.3 Parsing Namestrings Into Pathnames#

23.1.1 20A conforming implementation is free to accommodate other file system features in its pathname representation and provides a parser that can process such specifications in namestrings. Conforming programs must not depend on any such features, since those features will not be portable.

19.2 Pathnames#

19.2.1 Pathname Components#

\long\def\possiblecomponentvalues#1{\goodbreak Possible values for this component:\par \beginlist\par#1\par \itemitem{\nil, \kwd{wild}, or \kwd{unspecific}}\par See details and restrictions in \secref\SpecialComponentValues.\par \endlist\par} \possiblecomponentvalues{\itemitem{...}\par...}

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

23.1.1 4 23.1.1 5 23.1.1 17

19.2.1.1 The Pathname Host Component#

\possiblecomponentvalues{\itemitem{...}\par...}

19.2.1.2 The Pathname Device Component#

\possiblecomponentvalues{\itemitem{...}\par...}

23.1.1 6

19.2.1.3 The Pathname Directory Component#

\possiblecomponentvalues{\itemitem{...}\par...}

23.1.1 7

19.2.1.4 The Pathname Name Component#

\possiblecomponentvalues{\itemitem{...}\par...}

23.1.1 8 23.1.1 15

19.2.1.5 The Pathname Type Component#

\possiblecomponentvalues{\itemitem{...}\par...}

23.1.1 9 23.1.1 16

19.2.1.6 The Pathname Version Component#

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.

\possiblecomponentvalues{\itemitem{...}\par...}

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#

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

Such punctuation \term{characters} appear only in \term{namestrings}. Characters used as punctuation can appear in \term{pathname} component values with a non-punctuation meaning if the file system allows it (\eg a \Unix\ file name that begins with a dot).

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. Added per Loosemore #32, first public review -kmp 26-Jun-93The next figure lists the functions relating to pathnames that permit a :case argument:

19.2.2.1.2.1 Local Case in Pathname Components#

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#

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

19.2.2.2 Special Pathname Component Values#

19.2.2.2.1 NIL as a Component Value#

The value of any pathname component can be nil.

This came from bullet 1 of ``Restrictions on Constructing Pathnames''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, "version" commented out per Barmar-- PATHNAME-COMPONENT-VALUE:SPECIFY says that wild versions are permitted. device, or versionor 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” Part of bullet 2 of ``Restrictions on Examining Pathname Components''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.

Part of bullet 2 of ``Restrictions on Examining Pathname Components''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#

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, !!! Laddaga: LOAD? 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#

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.

\beginlist Consolidated with ``NIL as a Component Value'' above. \itemitem{\bull} Any component can be \nil, ... Consolidated with ``:UNSPECIFIC as a Component Value'' above. \issue{PATHNAME-UNSPECIFIC-COMPONENT:NEW-TOKEN} \itemitem{\bull} Any component can be \kwd{unspecific}, ... \endissue{PATHNAME-UNSPECIFIC-COMPONENT:NEW-TOKEN} Moved to various sections below. \itemitem{\bull} The device, directory, name, and type can be \term{strings}. Moved to new section farther down. \itemitem{\bull} It is \term{implementation-dependent} what \term{object} is used to represent the host. Moved to new section below. \itemitem{\bull} The directory can be a \term{list} of \term{strings} and \term{symbols}. [...] Moved to new section below. \itemitem{\bull} The version can be any \term{symbol} or any \term{integer}. \endlist

19.2.2.4.1 Restrictions on Examining a Pathname Host Component#

19.2.2.4.2 Restrictions on Examining a Pathname Device Component#

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

19.2.2.4.4 Restrictions on Examining a Pathname Name Component#

19.2.2.4.5 Restrictions on Examining a Pathname Type Component#

19.2.2.4.6 Restrictions on Examining a Pathname Version Component#

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#

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

• !!! Laddaga questions the "directory" part here. 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.

23.1.1 14 omitted. 23.1.1 18 omitted.

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.

Replaced per X3J13 Moved from ``Restrictions on Examining Pathname Components'' Laddaga had complained that this was in the wrong place before. This place may not be 100% better, but it's at least an improvement. -kmp 30-Aug-93 A relative directory in the \term{pathname} argument to a function such as \funref{open} is merged with \varref{*default-pathname-defaults*} before accessing the file system.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#

 (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

19.3 Logical Pathnames#

19.3.1 Syntax of Logical Pathname Namestrings#

The syntax of a logical pathname namestring is as follows. Added for clarity. -kmp 26-Jun-93(Note that unlike many notational descriptions in this document, this is a syntactic description of character sequences, not a structural description of objects.)

host-marker—a colon.

relative-directory-marker—a semicolon.

directory-marker—a semicolon.

type-marker—a dot.

version-marker—a dot.

wild-inferiors-word—The two character sequence “**” (two asterisks).

newest-word—The six character sequence “newest” or the six character sequence “NEWEST”.

wildcard-version—an asterisk.

wildcard-word—one or more asterisks, uppercase letters, digits, and hyphens, including at least one asterisk, with no two asterisks adjacent.

word—one or more uppercase letters, digits, and hyphens.

pos-int—a positive integer.

19.3.1.1 Additional Information about Parsing Logical Pathname Namestrings#

19.3.1.1.1 The Host part of a Logical Pathname Namestring#

The logical pathname host name "SYS" is reserved for the implementation. The existence and meaning of SYS: logical pathnames is implementation-defined.

19.3.1.1.2 The Device part of a Logical Pathname Namestring#

19.3.1.1.3 The Directory part of a Logical Pathname Namestring#

If a wild-inferiors-marker is specified, it parses into :wild-inferiors.

19.3.1.1.4 The Type part of a Logical Pathname Namestring#

19.3.1.1.5 The Version part of a Logical Pathname Namestring#

If a wildcard-version is specified, it parses into :wild.

19.3.1.1.6 Wildcard Words in a Logical Pathname Namestring#

19.3.1.1.7 Lowercase Letters in a Logical Pathname Namestring#

19.3.1.1.8 Other Syntax in a Logical Pathname Namestring#

!!! What does this mean?? This section is supposed to be about syntax, not component values. Sigh. -kmp 26-Jun-93The consequences of using any value not specified here as a logical pathname component are unspecified.

This wasn't a valid reference. See ``Input/Output'' for parsing and file manipulation details.

19.3.2 Logical Pathname Components#

19.3.2.1 Unspecific Components of a Logical Pathname#

The device component of a logical pathname is always :unspecific; no other component of a logical pathname can be :unspecific.

19.3.2.2 Null Strings as Components of a Logical Pathname#

Dictionary

• pathname System Class
• logical-pathname System Class
• pathname Function
• make-pathname Function
• pathnamep Function
• pathname-host, pathname-device, pathname-directory, pathname-name, pathname-type, pathname-version Function
• load-logical-pathname-translations Function
• logical-pathname-translations Accessor
• logical-pathname Function
• *default-pathname-defaults* Variable
• namestring, file-namestring, directory-namestring, host-namestring, enough-namestring Function
• parse-namestring Function
• wild-pathname-p Function
• pathname-match-p Function
• translate-logical-pathname Function
• translate-pathname Function
• merge-pathnames Function