PATH(3)

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);
    int       pathcheck(const char* package, const char* tool, Pathcheck_t* pc);
    int       pathgetlink(const char* name, char* buf, int siz);
    int       pathicase(const char* path);
    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 always defines even if it's indeterminate 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.

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

File exists.

Read permission on file.

Write permission on file.

Execute permission on file.

A regular file.

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

returns a pointer to the separated list of directories to search for executable commands. The environment variable is first consulted. If not defined then is used. A valid string is always returned.

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:

Each
    is checked for access.

Path must exist at each component.

Symbolic links are resolved at each component.

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

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

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

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

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 converts in the other direction.

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, 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 returns -1 with set to

generates in key a 14 character lookup key (plus terminating 0) for the language lang processor in path. A pointer 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.

constructs in path a path to p with access(2) mode mode using the directories from 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.

generates in path the full path name of the tool specific probe(1) information file for the lang language 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.

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

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

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

first tries and if that fails it tries The or return value is returned.

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 limitations. Both dir and pfx may be 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)