path.3 revision da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.ie \\$3 .ft \\$1
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.nr ;G \\n(.f
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.ft \\n(;G \}
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.de EX \" start example
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.ta 1i 2i 3i 4i 5i 6i
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.de EE \" end example
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinpath \- file path routines
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH SYNOPSIS
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathaccess(char* \fIpath\fP, const char* \fIdirs\fP, const char* \fIa\fP, const char* \fIb\fP, int \fImode\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathbin(void);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathcanon(char* \fIpath\fP, int \fIflags\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathcat(char* \fIpath\fP, const char* \fIdirs\fP, int \fIsep\fP, const char* \fIa\fP, const char* \fIb\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathcd(char* \fIpath\fP, const char* \fIhome\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint pathcheck(const char* \fIpackage\fP, const char* \fItool\fP, Pathcheck_t* \fIpc\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint pathgetlink(const char* \fIname\fP, char* \fIbuf\fP, int \fIsiz\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathkey(char* \fIkey\fP, char* \fIattr\fP, const char* \fIlang\fP, const char* \fIpath\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathnext(char* \fIpath\fP, char* \fIextra\fP, long* \fIvisits\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathpath(char* \fIpath\fP, const char* \fIp\fP, const char* \fIa\fP, int \fImode\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathprobe(char* \fIpath\fP, char* \fIattr\fP, const char* \fIlang\fP, const char* \fItool\fP, const char* \fIproc\fP, int \fIop\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathrepl(char* \fIpath\fP, const char* \fImatch\fP, const char* \fIreplace\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint pathsetlink(const char* \fItext\fP, char* \fIname\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathshell(void);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint pathstat(const char* \fIpath\fP, struct stat* \fIst\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar* pathtemp(char* \fIpath\fP, const char* \fIdir\fP, const char* \fIpfx\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH DESCRIPTION
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThese routines operate on file path names.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinPath buffers are assumed to be of size
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.LR PATH_MAX .
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinalways defines
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.LR PATH_MAX ,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chineven if it indeterminant on the local system.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinYes, this was probably a bad choice, but it was made about 10 years ago.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinWe will probably move to a <stk.h> based implementation.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathaccess
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinconstructs a path in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto the file
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwith access
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinseparated directories in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis the inclusive-or of:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFile exists.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinRead permission on file.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinWrite permission on file.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinExecute permission on file.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L PATH_REGULAR
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA regular file.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L PATH_ABSOLUTE
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinGenerated path name is rooted at
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis returned, 0 on error.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreturns a pointer to the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinseparated list of directories to search for executable commands.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinenvironment variable is first consulted.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf not defined then
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L confstr(_CS_PATH,...)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA valid string is always returned.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathcanon
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincanonicalizes the path
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA pointer to the trailing 0 in the canonicalized path is returned.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA canonical path has:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinmoved to the front;
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinpreserved for super root hacks;
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinresolved if
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR fs3d (3)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis enabled.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I flags is the inclusive-or of:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L PATH_DOTDOT
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis checked for access.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L PATH_EXISTS
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinPath must exist at each component.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L PATH_PHYSICAL
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinSymbolic links are resolved at each component.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin0 is returned on error.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf an error occurs and either of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L PATH_DOTDOT
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L PATH_EXISTS
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis set then
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwill contain the components following the failure point.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinconcatenates the first
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinseparated path component in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwith the path components
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe path is constructed in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinby separating each path component with
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA pointer to the next
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinseparated component in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis returned,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwhen there are no more components.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.LR pathaccess .
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinsets the current working directory to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR chdir (2).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis longer than
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L PATH_MAX
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthen it is split up into a sequence of relative paths and
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis called on each of these.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinFor any given system, if you got to a directory, then
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincan get you back, modulo permission and link changes.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathcheck
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis a stub for license libraries.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR license (3).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathgetlink
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreturns the 0-terminated symbolic link text for
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinin the buffer
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe link text length is returned on success, \-1 on error.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I universe (1)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininteractions with dynamic symbolic links are handled
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinby converting non-standard dynamic link text to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.LI .../$( UNIVERSE )/...
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathsetsymlink
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinconverts in the other direction.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chingenerates in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china 14 character lookup key (plus terminating 0) for the language
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinprocessor in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA poihter to the key is returned, 0 on error.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I "key == 0"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthen space is allocated via
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR malloc (3).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinKey specific attribute
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I name=value
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinpairs are copied into
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR "attr != 0" .
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathpath
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinconstructs in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR access (2)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinusing the directories from
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.LR pathbin() .
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIa != 0\fP then
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR argv [0]
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin(if available via
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR optget (3)),
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinenvironment variable (set by
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR ksh (1) )
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinare used for related root searching.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinalso contains a
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis searched for.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathprobe
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chingenerates in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe full path name of the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR probe (1)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininformation file for the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinlangauge processor
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I "path == 0"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthen space is allocated via
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR malloc (3).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinProbe attribute
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I name=value
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinpairs are copied into
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR "attr != 0" .
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinmay be one of:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreturn the path name with no access checks or generation
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinmessage emitted information must be generated via
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR probe (1)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinno message emitted information must be probed via
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR probe (1)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin0 is returned if the information does not exist and cannot be generated.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathrepl
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chindoes an in-place replacement of the first occurrence of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I /replace/
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathsetlink
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincreates a symbolic link
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinin the path
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathgetlink
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinabove for weird
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR universe (1)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininteractions hidden by this routine.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathshell
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreturns a pointer to the pathname for the shell for the current process.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinenvironment variable is first consulted, but is rejected under suspicious
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinownership/setuid conditions of if it seems to point to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR csh (1) ;
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L confstr(_CS_SHELL,...)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA valid string is always returned.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathstat
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfirst tries
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.LI stat( path,st )
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinand if that fails it tries
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.LI lstat( path,st ).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreturn value is returned.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.L pathtemp
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chingenerates in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china temporary file path name of the form
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.I dir/pfx<pid>.<suf>
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwhere the length of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinif !=0, is limited to 5, the length of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin(the base 64 representation of the current process id)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis limited to 3, and
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin(an internally generated suffix that avoid file confilicts)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis limited to 3.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe generated path name conforms to the classic UNIX 14 char and the DOS
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinlimitations.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.IR access (2)
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis used to avoid file conflicts but the generated path name is not created,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinso you could lose in a race.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH "SEE ALSO"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin3d(1), access(2), confstr(3), fs3d(3), lstat(2), stat(2)