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