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