NAME

path - file path routines

SYNOPSIS

#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);
ssize_t   pathgetlink(const char* name, char* buf, size_t siz);
int       pathicase(const char* path);
char*     pathnext(char* path, char* extra, long* visits);
char*     pathpath(char* path, const char* p, const char* a, int mode);
char*     pathrepl(char* path, const char* match, const char* replace);
int       pathsetlink(const char* text, char* name);
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 PATH_MAX. <ast.h> always defines 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.

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. 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.

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)/... The pathsetsymlink function converts in the other direction.

pathicase uses an operating system-specific method, if available, to determine if a file system uses case-insensitive file names. The return value is 1 if the file system associated with the path is case-insensitive (regardless of case preservation), 0 if it is not, or -1 if an error occurred. On error, 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 path, then pathicase returns -1 with errno set to ENOSYS.

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.

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.

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 conflicts) 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.

SEE ALSO

access(2), confstr(3), lstat(2), stat(2)