path - file path routines

#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);

These routines operate on file path names. Path buffers are assumed to be of size PATH_MAX. <ast.h> always defines 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.

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

F_OK

File exists.

R_OK

Read permission on file.

W_OK

Write permission on file.

X_OK

Execute permission on file.

PATH_REGULAR

A regular file.

PATH_ABSOLUTE

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

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

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

PATH_DOTDOT

Each .. is checked for access.

PATH_EXISTS

Path must exist at each component.

PATH_PHYSICAL

Symbolic links are resolved at each component.

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

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

pathcd sets the current working directory to path via chdir(2). If path is longer than 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 pathcd can get you back, modulo permission and link changes.

pathcheck is a stub for license libraries. See license(3).

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 .../$(UNIVERSE)/... pathsetsymlink converts in the other direction.

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.

pathpath constructs in path a path to p with access(2) mode mode using the directories from pathbin(). If a != 0 then a, argv[0] (if available via optget(3)), and the _ environment variable (set by ksh(1)) are used for related root searching. If p also contains a / then ../p is searched for.

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.

pathrepl does an in-place replacement of the first occurrence of /match/ with /replace/ in path.

pathsetlink creates a symbolic link text in the path name. See pathgetlink above for weird universe(1) interactions hidden by this routine.

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

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

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 8.3 limitations. Both dir and pfx may be 0. access(2) is used to avoid file conflicts but the generated path name is not created, so you could lose in a race.

3d(1), access(2), confstr(3), fs3d(3), lstat(2), stat(2)