common/man/path.3

        .fp 5 CW
..
.nr ;G \\n(.f
.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
\\*(;G
..
.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..


 0
..


..
 PATH 3
 NAME
path - file path routines
 SYNOPSIS
.EX
#include <ast.h>

char* pathaccess(char* path, const char* dirs, const char* a, const char* b, int mode);
char* pathbin(void);
char* pathcanon(char* path, int flags);
char* pathcat(char* path, const char* dirs, int sep, const char* a, const char* b);
char* pathcd(char* path, const char* home);
int pathcheck(const char* package, const char* tool, Pathcheck_t* pc);
int pathgetlink(const char* name, char* buf, int siz);
char* pathkey(char* key, char* attr, const char* lang, const char* path);
char* pathnext(char* path, char* extra, long* visits);
char* pathpath(char* path, const char* p, const char* a, int mode);
char* pathprobe(char* path, char* attr, const char* lang, const char* tool, const char* proc, int op);
char* pathrepl(char* path, const char* match, const char* replace);
int pathsetlink(const char* text, char* name);
char* pathshell(void);
int pathstat(const char* path, struct stat* st);
char* pathtemp(char* path, const char* dir, const char* pfx);

 DESCRIPTION
These routines operate on file path names.
Path buffers are assumed to be of size
.LR PATH_MAX .
.L <ast.h>
always defines
.LR PATH_MAX ,
even if it indeterminant on the local system.
Yes, this was probably a bad choice, but it was made about 10 years ago.
We will probably move to a <stk.h> based implementation.

.L pathaccess
constructs a path in
.L path
to the file
.L a/b
with access
.L mode
using the
.L :
separated directories in
 dirs . Both
 a and
 b may be
.LR 0 .
.L mode
is the inclusive-or of:

.L F_OK
File exists.

.L R_OK
Read permission on file.

.L W_OK
Write permission on file.

.L X_OK
Execute permission on file.

.L PATH_REGULAR
A regular file.

.L PATH_ABSOLUTE
Generated path name is rooted at
.LR / .
 path  is returned, 0 on error.

.L pathbin
returns a pointer to the
.L :
separated list of directories to search for executable commands.
The
.L PATH
environment variable is first consulted.
If not defined then
.L confstr(_CS_PATH,...)
is used.
A valid string is always returned.

.L pathcanon
canonicalizes the path
 path in place.
A pointer to the trailing 0 in the canonicalized path is returned.
A canonical path has:
redundant
.L .
and
.L /
removed;
.L ..
moved to the front;
.L /..
preserved for super root hacks;
.L ...
resolved if
 fs3d (3) is enabled.
 flags is the inclusive-or of:
.L PATH_DOTDOT
Each
.L ..
is checked for access.

.L PATH_EXISTS
Path must exist at each component.

.L PATH_PHYSICAL
Symbolic links are resolved at each component.

0 is returned on error.
If an error occurs and either of
.L PATH_DOTDOT
or
.L PATH_EXISTS
is set then
 path will contain the components following the failure point.

.L pathcat
concatenates the first
 sep separated path component in
 dirs with the path components
 a and
 b into
.LR path .
The path is constructed in
 path by separating each path component with
 / . Both
 a and
 b may be
.LR 0 .
A pointer to the next
 sep separated component in
 dirs is returned,
.L 0
when there are no more components.
.L pathcat
is used by
.LR pathaccess .

.L pathcd
sets the current working directory to
 path via
 chdir (2). If
 path is longer than
.L PATH_MAX
then it is split up into a sequence of relative paths and
 chdir is called on each of these.
For any given system, if you got to a directory, then
.L pathcd
can get you back, modulo permission and link changes.

.L pathcheck
is a stub for license libraries.
See
 license (3).
.L pathgetlink
returns the 0-terminated symbolic link text for
 path in the buffer
 bu of size
 siz . The link text length is returned on success, -1 on error.
Weird
 universe (1) interactions with dynamic symbolic links are handled
by converting non-standard dynamic link text to
.LI .../$( UNIVERSE )/...
.L pathsetsymlink
converts in the other direction.

.L pathkey
generates in
 key a 14 character lookup key (plus terminating 0) for the language
 lang processor in
 path . A poihter to the key is returned, 0 on error.
If
 "key == 0" then space is allocated via
 malloc (3). Key specific attribute
 name=value pairs are copied into
 attr if
 "attr != 0" .
.L pathpath
constructs in
 path a path to
 p with
 access (2) mode
 mode using the directories from
.LR pathbin() .
If a != 0 then
 a ,  argv [0] (if available via
 optget (3)), and the
.L _
environment variable (set by
 ksh (1) ) are used for related root searching.
If
 p also contains a
.L /
then
 ../p is searched for.

.L pathprobe
generates in
 path the full path name of the
 tool specific
 probe (1) information file for the
 lang langauge processor
 proc . If
 "path == 0" then space is allocated via
 malloc (3). Probe attribute
 name=value pairs are copied into
 attr if
 "attr != 0" .  op may be one of:

 -1 return the path name with no access checks or generation

 0 message emitted information must be generated via
 probe (1)
 1 no message emitted information must be probed via
 probe (1)
0 is returned if the information does not exist and cannot be generated.

.L pathrepl
does an in-place replacement of the first occurrence of
 /match/ with
 /replace/ in
 path .
.L pathsetlink
creates a symbolic link
 text in the path
 name . See
.L pathgetlink
above for weird
 universe (1) interactions hidden by this routine.

.L pathshell
returns a pointer to the pathname for the shell for the current process.
The
.L SHELL
environment variable is first consulted, but is rejected under suspicious
ownership/setuid conditions of if it seems to point to
 csh (1) ; otherwise
.L confstr(_CS_SHELL,...)
is used.
A valid string is always returned.

.L pathstat
first tries
.LI stat( path,st )
and if that fails it tries
.LI lstat( path,st ).
The
.L stat
or
.L lstat
return value is returned.

.L pathtemp
generates in
 path a temporary file path name of the form
 dir/pfx<pid>.<suf> where the length of
 pfx , if !=0, is limited to 5, the length of
 <pid> (the base 64 representation of the current process id)
is limited to 3, and
 <suf> (an internally generated suffix that avoid file confilicts)
is limited to 3.
The generated path name conforms to the classic UNIX 14 char and the DOS
.LR 8.3
limitations.
Both
 dir and
 pfx may be
.LR 0 .
 access (2) is used to avoid file conflicts but the generated path name is not created,
so you could lose in a race.
 "SEE ALSO"
3d(1), access(2), confstr(3), fs3d(3), lstat(2), stat(2)