doc/manual/pathnames.texinfo

   1 @node Pathnames
   2 @comment  node-name,  next,  previous,  up
   3 @chapter Pathnames
   4
   5 @cindex Pathnames
   6
   7 @menu
   8 * Lisp Pathnames::
   9 * Native Filenames::
  10 @end menu
  11
  12 @node Lisp Pathnames
  13 @comment  node-name,  next,  previous,  up
  14 @section Lisp Pathnames
  15
  16 There are many aspects of ANSI Common Lisp's pathname support which are
  17 implementation-defined and so need documentation.
  18
  19 @c FIXME: as a matter of ANSI conformance, we are required to document
  20 @c implementation-defined stuff, which for pathnames (chapter 19 of CLtS)
  21 @c includes:
  22 @c
  23 @c * Otherwise, the parsing of thing is implementation-defined.
  24 @c   (PARSE-NAMESTRING)
  25 @c
  26 @c * If thing contains an explicit host name and no explicit device name,
  27 @c   then it is implementation-defined whether parse-namestring will supply
  28 @c   the standard default device for that host as the device component of
  29 @c   the resulting pathname.  (PARSE-NAMESTRING)
  30 @c
  31 @c * The specific nature of the search is implementation-defined.
  32 @c   (LOAD-LOGICAL-PATHNAME-TRANSLATIONS)
  33 @c
  34 @c * Any additional elements are implementation-defined.
  35 @c   (LOGICAL-PATHNAME-TRANSLATIONS)
  36 @c
  37 @c * The matching rules are implementation-defined but should be consistent
  38 @c   with directory.  (PATHNAME-MATCH-P)
  39 @c
  40 @c * Any such additional translations are implementation-defined.
  41 @c   (TRANSLATE-LOGICAL-PATHNAMES)
  42 @c
  43 @c * ...or an implementation-defined portion of a component...
  44 @c   (TRANSLATE-PATHNAME)
  45 @c
  46 @c * The portion of source that is copied into the resulting pathname is
  47 @c   implementation-defined.  (TRANSLATE-PATHNAME)
  48 @c
  49 @c * During the copying of a portion of source into the resulting
  50 @c   pathname, additional implementation-defined translations of case or
  51 @c   file naming conventions might occur.  (TRANSLATE-PATHNAME)
  52 @c
  53 @c * In general, the syntax of namestrings involves the use of
  54 @c   implementation-defined conventions.  (19.1.1)
  55 @c
  56 @c * The nature of the mapping between structure imposed by pathnames and
  57 @c   the structure, if any, that is used by the underlying file system is
  58 @c   implementation-defined.  (19.1.2)
  59 @c
  60 @c * The mapping of the pathname components into the concepts peculiar to
  61 @c   each file system is implementation-defined.  (19.1.2)
  62 @c
  63 @c * Whether separator characters are permitted as part of a string in a
  64 @c   pathname component is implementation-defined;  (19.2.2.1.1)
  65 @c
  66 @c * Whether a value of :unspecific is permitted for any component on any
  67 @c   given file system accessible to the implementation is
  68 @c   implementation-defined.  (19.2.2.2.3)
  69 @c
  70 @c * Other symbols and integers have implementation-defined meaning.
  71 @c   (19.2.2.4.6)
  72
  73 @subsection The SYS Logical Pathname Host
  74
  75 @cindex Logical pathnames
  76 @cindex Pathnames, logical
  77 @findex logical-pathname-translations
  78 @findex (setf logical-pathname-translations)
  79
  80 @c * The existence and meaning of SYS: logical pathnames is
  81 @c   implementation-defined.  (19.3.1.1.1)
  82
  83 The logical pathname host named by @code{"SYS"} exists in SBCL.  Its
  84 @code{logical-pathname-translations} may be set by the site or the user
  85 applicable to point to the locations of the system's sources; in
  86 particular, the core system's source files match the logical pathname
  87 @code{"SYS:SRC;**;*.*.*"}, and the contributed modules' source files
  88 match @code{"SYS:CONTRIB;**;*.*.*"}.
  89
  90 @node Native Filenames
  91 @comment  node-name,  next,  previous,  up
  92 @section Native Filenames
  93
  94 In some circumstances, what is wanted is a Lisp pathname object which
  95 corresponds to a string produced by the Operating System.  In this case,
  96 some of the default parsing rules are inappropriate: most filesystems do
  97 not have a native understanding of wild pathnames; such functionality is
  98 often provided by shells above the OS, often in mutually-incompatible
  99 ways.
 100
 101 To allow the user to deal with this, the following functions are
 102 provided: @code{parse-native-namestring} and @code{native-pathname}
 103 return the closest equivalent Lisp pathname to a given string
 104 (appropriate for the Operating System), while @code{native-namestring}
 105 converts a non-wild pathname designator to the equivalent native
 106 namestring, if possible.  Some Lisp pathname concepts (such as the
 107 @code{:back} directory component) have no direct equivalents in most
 108 Operating Systems; the behaviour of @code{native-namestring} is
 109 unspecified if an inappropriate pathname designator is passed to it.
 110 Additionally, note that conversion from pathname to native filename
 111 and back to pathname should not be expected to preserve equivalence
 112 under @code{equal}.
 113
 114 @include fun-sb-ext-parse-native-namestring.texinfo
 115 @include fun-sb-ext-native-pathname.texinfo
 116 @include fun-sb-ext-native-namestring.texinfo
 117
 118 Because some file systems permit the names of directories to be
 119 expressed in multiple ways, it is occasionally necessary to parse a
 120 native file name ``as a directory name'' or to produce a native file
 121 name that names a directory ``as a file''.  For these cases,
 122 @code{parse-native-namestring} accepts the keyword argument
 123 @code{as-directory} to force a filename to parse as a directory, and
 124 @code{native-namestring} accepts the keyword argument @code{as-file}
 125 to force a pathname to unparse as a file.  For example,
 126
 127 @lisp
 128 ; On Unix, the directory "/tmp/" can be denoted by "/tmp/" or "/tmp".
 129 ; Under the default rules for native filenames, these parse and
 130 ; unparse differently.
 131 (defvar *p*)
 132 (setf *p* (parse-native-namestring "/tmp/")) @result{} #P"/tmp/"
 133 (pathname-name *p*) @result{} NIL
 134 (pathname-directory *p*) @result{} (:ABSOLUTE "tmp")
 135 (native-namestring *p*) @result{} "/tmp/"
 136
 137 (setf *p* (parse-native-namestring "/tmp")) @result{} #P"/tmp"
 138 (pathname-name *p*) @result{} "tmp"
 139 (pathname-directory *p*) @result{} (:ABSOLUTE)
 140 (native-namestring *p*) @result{} "/tmp"
 141
 142 ; A non-NIL AS-DIRECTORY argument to PARSE-NATIVE-NAMESTRING forces
 143 ; both the second string to parse the way the first does.
 144 (setf *p* (parse-native-namestring "/tmp"
 145                                    nil *default-pathname-defaults*
 146                                    :as-directory t)) @result{} #P"/tmp/"
 147 (pathname-name *p*) @result{} NIL
 148 (pathname-directory *p*) @result{} (:ABSOLUTE "tmp")
 149
 150 ; A non-NIL AS-FILE argument to NATIVE-NAMESTRING forces the pathname
 151 ; parsed from the first string to unparse as the second string.
 152 (setf *p* (parse-native-namestring "/tmp/")) @result{} #P"/tmp/"
 153 (native-namestring *p* :as-file t) @result{} "/tmp"
 154 @end lisp