% -*- Mode: TeX -*-

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

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

\beginSubsection{Namestrings as Filenames}

\issue{PATHNAME-HOST-PARSING:RECOGNIZE-LOGICAL-HOST-NAMES}
A \newterm{namestring} is a \term{string} that represents a \term{filename}.

In general, the syntax of \term{namestrings} involves the use of 
\term{implementation-defined} conventions, 
usually those customary for the \term{file system} in which the named \term{file} resides.
The only exception is the syntax of a \term{logical pathname} \term{namestring},
which is defined in this specification; \seesection\LogPathNamestrings.
\endissue{PATHNAME-HOST-PARSING:RECOGNIZE-LOGICAL-HOST-NAMES}

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

%%% 23.1.1 11
A \term{namestring} can be \term{coerced} to a \term{pathname} by \thefunctions{pathname}
or \funref{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}.

\endSubsection%{Namestrings as Filenames}

\beginSubsection{Pathnames as Filenames}
\DefineSection{PathnamesAsFilenames}

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

\newtermidx{Pathnames}{pathname} are structured \term{objects} that can represent,
in an \term{implementation-independent} way,
the \term{filenames} that are used natively by an underlying \term{file system}.

In addition, \term{pathnames} can also represent certain partially composed 
\term{filenames} for which an underlying \term{file system} 
might not have a specific \term{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 \term{pathname} need not correspond to any file that actually exists, 
and more than one \term{pathname} can refer to the same file.
For example, the \term{pathname} with a version of \kwd{newest} 
might refer to the same file as a \term{pathname} 
with the same components except a certain number as the version.
Indeed, a \term{pathname} with version \kwd{newest} might refer to
different files as time passes, because the meaning of such a \term{pathname}
depends on the state of the file system.  

Some \term{file systems} naturally use a structural model for their
\term{filenames}, while others do not.  Within the \clisp\ \term{pathname} model, 
all \term{filenames} are seen as having a particular structure,
even if that structure is not reflected in the underlying \term{file system}.
The nature of the mapping between structure imposed by \term{pathnames}
and the structure, if any, that is used by the underlying \term{file system}
is \term{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 3
Every \term{pathname} has six components:
     a host,
     a device,
     a directory,
     a name,
     a type,
 and a version.
By naming \term{files} with \term{pathnames}, 
\clisp\ programs can work in essentially the same way even in \term{file systems}
that seem superficially quite different.
For a detailed description of these components, \seesection\PathnameComponents.

\issue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR}
\issue{PATHNAME-SYNTAX-ERROR-TIME:EXPLICITLY-VAGUE}%
% %% 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 \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 mapping to a syntactically valid \term{filename}
in a particular \term{implementation}.
An \term{implementation} may use various strategies in an attempt to find a mapping;
for example, 
an \term{implementation} may quietly truncate \term{filenames}
that exceed length limitations imposed by the underlying \term{file system},
or ignore certain \term{pathname} components
for which the \term{file system} provides no support.
If such a mapping cannot be found,
an error \oftype{file-error} is signaled.

The time at which this mapping and associated error signaling 
occurs is \term{implementation-dependent}.
Specifically, it may occur 
    at the time the \term{pathname} is constructed,
    when coercing a \term{pathname} to a \term{namestring},
 or when an attempt is made to \term{open} or otherwise access the \term{file} 
     designated by the \term{pathname}.
\endissue{PATHNAME-SYNTAX-ERROR-TIME:EXPLICITLY-VAGUE}
\endissue{FILE-OPEN-ERROR:SIGNAL-FILE-ERROR}

\Thenextfigure\ lists some \term{defined names} that are applicable to \term{pathnames}.

\displaythree{Pathname Operations}{
*default-pathname-defaults*&namestring&pathname-name\cr
directory-namestring&open&pathname-type\cr
enough-namestring&parse-namestring&pathname-version\cr
file-namestring&pathname&pathnamep\cr
file-string-length&pathname-device&translate-pathname\cr
host-namestring&pathname-directory&truename\cr
make-pathname&pathname-host&user-homedir-pathname\cr
merge-pathnames&pathname-match-p&wild-pathname-p\cr
}
\endSubsection%{Pathnames as Filenames}

\beginSubsection{Parsing Namestrings Into Pathnames}

%% 23.1.1 11
Parsing is the operation used to convert a \term{namestring} into a \term{pathname}.
\issue{PATHNAME-HOST-PARSING:RECOGNIZE-LOGICAL-HOST-NAMES}
Except in the case of parsing \term{logical pathname} \term{namestrings},
\endissue{PATHNAME-HOST-PARSING:RECOGNIZE-LOGICAL-HOST-NAMES}
this operation is \term{implementation-dependent},
because the format of \term{namestrings} is \term{implementation-dependent}.

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

\endSubsection%{Parsing Namestrings Into Pathnames}