Imported Upstream version 93u+upstream

1 files changed, 391 insertions, 0 deletions

diff --git a/src/lib/libast/man/path.3 b/src/lib/libast/man/path.3
new file mode 100644
index 0000000..8721888
--- /dev/null
+++ b/src/lib/libast/man/path.3
@@ -0,0 +1,391 @@
+.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 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);
+char*     pathkey(char* \fIkey\fP, char* \fIattr\fP, const char* \fIlang\fP, 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*     pathprobe(char* \fIpath\fP, char* \fIattr\fP, const char* \fIlang\fP, const char* \fItool\fP, const char* \fIproc\fP, int \fIop\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 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.
+.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;
+.L ...
+resolved if
+.IR fs3d (3)
+is enabled.
+.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
+.I 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.
+.PP
+.L pathkey
+generates in 
+.I key
+a 14 character lookup key (plus terminating 0) for the language
+.I lang
+processor in
+.IR path .
+A poihter to the key is returned, 0 on error.
+If
+.I "key == 0"
+then space is allocated via
+.IR malloc (3).
+Key specific attribute
+.I name=value
+pairs are copied into
+.I attr
+if
+.IR "attr != 0" .
+.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 pathprobe
+generates in
+.I path
+the full path name of the
+.I tool
+specific
+.IR probe (1)
+information file for the
+.I lang
+langauge processor
+.IR proc .
+If
+.I "path == 0"
+then space is allocated via
+.IR malloc (3).
+Probe attribute
+.I name=value
+pairs are copied into
+.I attr
+if
+.IR "attr != 0" .
+.I op
+may be one of:
+.TP
+.B \-1
+return the path name with no access checks or generation
+.TP
+.B 0
+message emitted information must be generated via
+.IR probe (1)
+.TP
+.B 1
+no message emitted information must be probed via
+.IR probe (1)
+.PP
+0 is returned if the information does not exist and cannot be generated.
+.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 confilicts)
+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"
+3d(1), access(2), confstr(3), fs3d(3), lstat(2), stat(2)