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