path.3

.fp 5 CW
.de Af
.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
..
.de aF
.ie \\$3 .ft \\$1
.el \{\
.ds ;G \&
.nr ;G \\n(.f
.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
\\*(;G
.ft \\n(;G \}
..
.de L
.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de LR
.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de RL
.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de LI
.aF 5 2 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de EX		\" start example
.ta 1i 2i 3i 4i 5i 6i
.PP
.RS
.PD 0
.ft 5
.nf
..
.de EE		\" end example
.fi
.ft
.PD
.RE
.PP
..
.TH PATH 3
.SH NAME
path \- file path routines
.SH SYNOPSIS
.EX
#include <ast.h>

char*     pathaccess(char* \fIpath\fP, const char* \fIdirs\fP, const char* \fIa\fP, const char* \fIb\fP, int \fImode\fP);
char*     pathbin(void);
char*     pathcanon(char* \fIpath\fP, int \fIflags\fP);
char*     pathcat(char* \fIpath\fP, const char* \fIdirs\fP, int \fIsep\fP, const char* \fIa\fP, const char* \fIb\fP);
char*     pathcd(char* \fIpath\fP, const char* \fIhome\fP);
int       pathcheck(const char* \fIpackage\fP, const char* \fItool\fP, Pathcheck_t* \fIpc\fP);
int       pathgetlink(const char* \fIname\fP, char* \fIbuf\fP, int \fIsiz\fP);
int       pathicase(const char* \fIpath\fP);
char*     pathnext(char* \fIpath\fP, char* \fIextra\fP, long* \fIvisits\fP);
char*     pathpath(char* \fIpath\fP, const char* \fIp\fP, const char* \fIa\fP, int \fImode\fP);
char*     pathrepl(char* \fIpath\fP, const char* \fImatch\fP, const char* \fIreplace\fP);
int       pathsetlink(const char* \fItext\fP, char* \fIname\fP);
char*     pathshell(void);
int       pathstat(const char* \fIpath\fP, struct stat* \fIst\fP);
char*     pathtemp(char* \fIpath\fP, const char* \fIdir\fP, const char* \fIpfx\fP);
.EE
.SH 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's indeterminate on the local system.
Yes, this was probably a bad choice, but it was made in the 1980s.
We will probably move to a <stk.h> based implementation.
.PP
.L pathaccess
constructs a path in
.L path
to the file
.L a/b
with access
.L mode
using the
.L :
separated directories in
.IR dirs .
Both
.I a
and
.I b
may be
.LR 0 .
.L mode
is the inclusive-or of:
.TP
.L F_OK
File exists.
.TP
.L R_OK
Read permission on file.
.TP
.L W_OK
Write permission on file.
.TP
.L X_OK
Execute permission on file.
.TP
.L PATH_REGULAR
A regular file.
.TP
.L PATH_ABSOLUTE
Generated path name is rooted at
.LR / .
.I path
is returned, 0 on error.
.PP
.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.
.PP
.L pathcanon
canonicalizes the path
.I 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.
.I flags is the inclusive-or of:
.TP
.L PATH_DOTDOT
Each
.L ..
is checked for access.
.TP
.L PATH_EXISTS
Path must exist at each component.
.TP
.L PATH_PHYSICAL
Symbolic links are resolved at each component.
.PP
0 is returned on error.
If an error occurs and either of
.L PATH_DOTDOT
or
.L PATH_EXISTS
is set then
.I path
will contain the components following the failure point.
.PP
.L pathcat
concatenates the first
.I sep
separated path component in
.I dirs
with the path components
.I a
and
.I b
into
.LR path .
The path is constructed in
.I path
by separating each path component with
.IR / .
Both
.I a
and
.I b
may be
.LR 0 .
A pointer to the next
.I sep
separated component in
.I dirs
is returned,
.L 0
when there are no more components.
.L pathcat
is used by
.LR pathaccess .
.PP
.L pathcd
sets the current working directory to
.I path
via
.IR chdir (2).
If
.I path
is longer than
.L PATH_MAX
then it is split up into a sequence of relative paths and
.I 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.
.PP
.L pathcheck
is a stub for license libraries.
See
.IR license (3).
.PP
.L pathgetlink
returns the 0-terminated symbolic link text for
.I path
in the buffer
.I bu
of size
.IR siz .
The link text length is returned on success, \-1 on error.
Weird
.IR universe (1)
interactions with dynamic symbolic links are handled
by converting non-standard dynamic link text to
.LI .../$( UNIVERSE )/...
The
.L pathsetsymlink
function
converts in the other direction.
.PP
.L pathicase
uses an operating system-specific method, if available,
to determine if a file system uses case-insensitive file names.
The return value is
.B 1
if the file system associated with the
.I path
is case-insensitive (regardless of case preservation),
.B 0
if it is not, or
.B \-1
if an error occurred. On error,
.L errno
is set by the system-specific function that was used.
If the operating system does not have a known method
to determine file system case insensitivity for the
.IR path ,
then
.L pathicase
returns
.B \-1
with
.L errno
set to
.LR ENOSYS .
.PP
.L pathpath
constructs in
.I path
a path to
.I p
with
.IR access (2)
mode
.I mode
using the directories from
.LR pathbin() .
If \fIa != 0\fP then
.IR a ,
.IR argv [0]
(if available via
.IR optget (3)),
and the
.L _
environment variable (set by
.IR ksh (1) )
are used for related root searching.
If
.I p
also contains a
.L /
then
.I ../p
is searched for.
.PP
.L pathrepl
does an in-place replacement of the first occurrence of
.I /match/
with
.I /replace/
in
.IR path .
.PP
.L pathsetlink
creates a symbolic link
.I text
in the path
.IR name .
See
.L pathgetlink
above for weird
.IR universe (1)
interactions hidden by this routine.
.PP
.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
.IR csh (1) ;
otherwise
.L confstr(_CS_SHELL,...)
is used.
A valid string is always returned.
.PP
.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.
.PP
.L pathtemp
generates in
.I path
a temporary file path name of the form
.I dir/pfx<pid>.<suf>
where the length of
.IR pfx ,
if !=0, is limited to 5, the length of
.I <pid>
(the base 64 representation of the current process ID)
is limited to 3, and
.I <suf>
(an internally generated suffix that avoid file conflicts)
is limited to 3.
The generated path name conforms to the classic UNIX 14 char and the DOS
.LR 8.3
limitations.
Both
.I dir
and
.I pfx
may be
.LR 0 .
.IR access (2)
is used to avoid file conflicts but the generated path name is not created,
so you could lose in a race.
.SH "SEE ALSO"
access(2), confstr(3), lstat(2), stat(2)