1.0.10.27: Change unportable find option "-path"
[sbcl.git] / 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
111 @include fun-sb-ext-parse-native-namestring.texinfo
112 @include fun-sb-ext-native-pathname.texinfo
113 @include fun-sb-ext-native-namestring.texinfo