| blob | 8721888bb5bfbe6740af0d9abc650af277ebbc8f |
1 .fp 5 CW
2 .de Af
3 .ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
5 ..
6 .de aF
8 .el \{\
9 .ds ;G \&
10 .nr ;G \\n(.f
11 .Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
12 \\*(;G
13 .ft \\n(;G \}
14 ..
15 .de L
16 .aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
17 ..
18 .de LR
19 .aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
20 ..
21 .de RL
22 .aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
23 ..
24 .de EX \" start example
25 .ta 1i 2i 3i 4i 5i 6i
26 .PP
27 .RS
28 .PD 0
29 .ft 5
30 .nf
31 ..
32 .de EE \" end example
33 .fi
34 .ft
35 .PD
36 .RE
37 .PP
38 ..
39 .TH PATH 3
40 .SH NAME
41 path \- file path routines
42 .SH SYNOPSIS
43 .EX
44 #include <ast.h>
46 char* pathaccess(char* \fIpath\fP, const char* \fIdirs\fP, const char* \fIa\fP, const char* \fIb\fP, int \fImode\fP);
47 char* pathbin(void);
48 char* pathcanon(char* \fIpath\fP, int \fIflags\fP);
49 char* pathcat(char* \fIpath\fP, const char* \fIdirs\fP, int \fIsep\fP, const char* \fIa\fP, const char* \fIb\fP);
50 char* pathcd(char* \fIpath\fP, const char* \fIhome\fP);
51 int pathcheck(const char* \fIpackage\fP, const char* \fItool\fP, Pathcheck_t* \fIpc\fP);
52 int pathgetlink(const char* \fIname\fP, char* \fIbuf\fP, int \fIsiz\fP);
53 char* pathkey(char* \fIkey\fP, char* \fIattr\fP, const char* \fIlang\fP, const char* \fIpath\fP);
54 char* pathnext(char* \fIpath\fP, char* \fIextra\fP, long* \fIvisits\fP);
55 char* pathpath(char* \fIpath\fP, const char* \fIp\fP, const char* \fIa\fP, int \fImode\fP);
56 char* pathprobe(char* \fIpath\fP, char* \fIattr\fP, const char* \fIlang\fP, const char* \fItool\fP, const char* \fIproc\fP, int \fIop\fP);
57 char* pathrepl(char* \fIpath\fP, const char* \fImatch\fP, const char* \fIreplace\fP);
58 int pathsetlink(const char* \fItext\fP, char* \fIname\fP);
59 char* pathshell(void);
60 int pathstat(const char* \fIpath\fP, struct stat* \fIst\fP);
61 char* pathtemp(char* \fIpath\fP, const char* \fIdir\fP, const char* \fIpfx\fP);
62 .EE
63 .SH DESCRIPTION
64 These routines operate on file path names.
65 Path buffers are assumed to be of size
66 .LR PATH_MAX .
67 .L <ast.h>
68 always defines
69 .LR PATH_MAX ,
70 even if it indeterminant on the local system.
71 Yes, this was probably a bad choice, but it was made about 10 years ago.
72 We will probably move to a <stk.h> based implementation.
73 .PP
74 .L pathaccess
75 constructs a path in
76 .L path
77 to the file
78 .L a/b
79 with access
80 .L mode
81 using the
82 .L :
83 separated directories in
84 .IR dirs .
85 Both
86 .I a
87 and
88 .I b
89 may be
90 .LR 0 .
91 .L mode
92 is the inclusive-or of:
93 .TP
94 .L F_OK
95 File exists.
96 .TP
97 .L R_OK
98 Read permission on file.
99 .TP
100 .L W_OK
101 Write permission on file.
102 .TP
103 .L X_OK
104 Execute permission on file.
105 .TP
106 .L PATH_REGULAR
107 A regular file.
108 .TP
109 .L PATH_ABSOLUTE
110 Generated path name is rooted at
111 .LR / .
112 .I path
113 is returned, 0 on error.
114 .PP
115 .L pathbin
116 returns a pointer to the
117 .L :
118 separated list of directories to search for executable commands.
119 The
120 .L PATH
121 environment variable is first consulted.
122 If not defined then
123 .L confstr(_CS_PATH,...)
124 is used.
125 A valid string is always returned.
126 .PP
127 .L pathcanon
128 canonicalizes the path
129 .I path
130 in place.
131 A pointer to the trailing 0 in the canonicalized path is returned.
132 A canonical path has:
133 redundant
134 .L .
135 and
136 .L /
137 removed;
138 .L ..
139 moved to the front;
140 .L /..
141 preserved for super root hacks;
142 .L ...
143 resolved if
144 .IR fs3d (3)
145 is enabled.
146 .I flags is the inclusive-or of:
147 .TP
148 .L PATH_DOTDOT
149 Each
150 .L ..
151 is checked for access.
152 .TP
153 .L PATH_EXISTS
154 Path must exist at each component.
155 .TP
156 .L PATH_PHYSICAL
157 Symbolic links are resolved at each component.
158 .PP
159 0 is returned on error.
160 If an error occurs and either of
161 .L PATH_DOTDOT
162 or
163 .L PATH_EXISTS
164 is set then
165 .I path
166 will contain the components following the failure point.
167 .PP
168 .L pathcat
169 concatenates the first
170 .I sep
171 separated path component in
172 .I dirs
173 with the path components
174 .I a
175 and
176 .I b
177 into
178 .LR path .
179 The path is constructed in
180 .I path
181 by separating each path component with
182 .IR / .
183 Both
184 .I a
185 and
186 .I b
187 may be
188 .LR 0 .
189 A pointer to the next
190 .I sep
191 separated component in
192 .I dirs
193 is returned,
194 .L 0
195 when there are no more components.
196 .L pathcat
197 is used by
198 .LR pathaccess .
199 .PP
200 .L pathcd
201 sets the current working directory to
202 .I path
203 via
204 .IR chdir (2).
205 If
206 .I path
207 is longer than
208 .L PATH_MAX
209 then it is split up into a sequence of relative paths and
210 .I chdir
211 is called on each of these.
212 For any given system, if you got to a directory, then
213 .L pathcd
214 can get you back, modulo permission and link changes.
215 .PP
216 .L pathcheck
217 is a stub for license libraries.
218 See
219 .IR license (3).
220 .PP
221 .L pathgetlink
222 returns the 0-terminated symbolic link text for
223 .I path
224 in the buffer
225 .I bu
226 of size
227 .IR siz .
228 The link text length is returned on success, \-1 on error.
229 Weird
230 .I universe (1)
231 interactions with dynamic symbolic links are handled
232 by converting non-standard dynamic link text to
233 .LI .../$( UNIVERSE )/...
234 .L pathsetsymlink
235 converts in the other direction.
236 .PP
237 .L pathkey
238 generates in
239 .I key
240 a 14 character lookup key (plus terminating 0) for the language
241 .I lang
242 processor in
243 .IR path .
244 A poihter to the key is returned, 0 on error.
245 If
246 .I "key == 0"
247 then space is allocated via
248 .IR malloc (3).
249 Key specific attribute
250 .I name=value
251 pairs are copied into
252 .I attr
253 if
254 .IR "attr != 0" .
255 .PP
256 .L pathpath
257 constructs in
258 .I path
259 a path to
260 .I p
261 with
262 .IR access (2)
263 mode
264 .I mode
265 using the directories from
266 .LR pathbin() .
267 If \fIa != 0\fP then
268 .IR a ,
269 .IR argv [0]
270 (if available via
271 .IR optget (3)),
272 and the
273 .L _
274 environment variable (set by
275 .IR ksh (1) )
276 are used for related root searching.
277 If
278 .I p
279 also contains a
280 .L /
281 then
282 .I ../p
283 is searched for.
284 .PP
285 .L pathprobe
286 generates in
287 .I path
288 the full path name of the
289 .I tool
290 specific
291 .IR probe (1)
292 information file for the
293 .I lang
294 langauge processor
295 .IR proc .
296 If
297 .I "path == 0"
298 then space is allocated via
299 .IR malloc (3).
300 Probe attribute
301 .I name=value
302 pairs are copied into
303 .I attr
304 if
305 .IR "attr != 0" .
306 .I op
307 may be one of:
308 .TP
309 .B \-1
310 return the path name with no access checks or generation
311 .TP
312 .B 0
313 message emitted information must be generated via
314 .IR probe (1)
315 .TP
316 .B 1
317 no message emitted information must be probed via
318 .IR probe (1)
319 .PP
320 0 is returned if the information does not exist and cannot be generated.
321 .PP
322 .L pathrepl
323 does an in-place replacement of the first occurrence of
324 .I /match/
325 with
326 .I /replace/
327 in
328 .IR path .
329 .PP
330 .L pathsetlink
331 creates a symbolic link
332 .I text
333 in the path
334 .IR name .
335 See
336 .L pathgetlink
337 above for weird
338 .IR universe (1)
339 interactions hidden by this routine.
340 .PP
341 .L pathshell
342 returns a pointer to the pathname for the shell for the current process.
343 The
344 .L SHELL
345 environment variable is first consulted, but is rejected under suspicious
346 ownership/setuid conditions of if it seems to point to
347 .IR csh (1) ;
348 otherwise
349 .L confstr(_CS_SHELL,...)
350 is used.
351 A valid string is always returned.
352 .PP
353 .L pathstat
354 first tries
355 .LI stat( path,st )
356 and if that fails it tries
357 .LI lstat( path,st ).
358 The
359 .L stat
360 or
361 .L lstat
362 return value is returned.
363 .PP
364 .L pathtemp
365 generates in
366 .I path
367 a temporary file path name of the form
368 .I dir/pfx<pid>.<suf>
369 where the length of
370 .IR pfx ,
371 if !=0, is limited to 5, the length of
372 .I <pid>
373 (the base 64 representation of the current process id)
374 is limited to 3, and
375 .I <suf>
376 (an internally generated suffix that avoid file confilicts)
377 is limited to 3.
378 The generated path name conforms to the classic UNIX 14 char and the DOS
379 .LR 8.3
380 limitations.
381 Both
382 .I dir
383 and
384 .I pfx
385 may be
386 .LR 0 .
387 .IR access (2)
388 is used to avoid file conflicts but the generated path name is not created,
389 so you could lose in a race.
390 .SH "SEE ALSO"
391 3d(1), access(2), confstr(3), fs3d(3), lstat(2), stat(2)