'\"macro stdmacro
.if n .pH g3g.pathfind @(#)pathfind	40.7 of 10/27/89
.\" Copyright 1989 AT&T
'''	ident	"@(#)libgen:doc/pathfind.3G	1.1"
.nr X
.if \nX=0 .ds x} pathfind 3G "" "\&"
.if \nX=1 .ds x} pathfind 3G ""
.if \nX=2 .ds x} pathfind 3G "" "\&"
.if \nX=3 .ds x} pathfind "" "" "\&"
.TH \*(x}
.SH "NAME"
\f4pathfind\f1 \- search for named file in named directories
.SH "SYNOPSIS"
\f4cc\f1
[\f2flag\fP \|.\|.\|.] \f2file\fP \|.\|.\|.
\f4\-lgen\f1
[\f2library\fP \|.\|.\|.]
.PP
\f4#include <libgen.h>\fP
.PP
.nf
\f4char \(**pathfind (const char \(**path, const char \(**name, const char 
    \(**mode);\f1
.fi
.SH DESCRIPTION
\f4pathfind\fP searches the directories named in
\f2path\f1 for the file \f2name\f1.
The directories named in
.I path
are separated by semicolons.
.I mode
is a string of option letters chosen from the set
\f4rwxfbcdpugks\f1:
.TS
center;
c l
cf4 l .
Letter	Meaning
_
r	readable
w	writable
x	executable
f	normal file
b	block special
c	character special
d	directory
p	\s-1FIFO\s0 (pipe)
u	set user \s-1ID\s+1 bit
g	set group \s-1ID\s+1 bit
k	sticky bit
s	size nonzero
.TE
Options read, write, and execute are checked relative to the
real (not the effective) user
.SM ID
and group
.SM ID
of the
current process.
.P
If the file \f2name\f1,
with all the characteristics specified by
.IR mode ,
is found in any of the directories specified by
.IR path ,
then
\f4pathfind\fP
returns a pointer to a string containing the member of
.IR path ,
followed by a slash character (\f4/\fP),
followed by
.IR name .
.PP
If
.I name
begins with a slash,
it is treated as an absolute path name, and
.I path
is ignored.
.P
An empty
.I path
member is treated as the current directory.
\f4./\fP is not prepended at the occurrence of the first match;
rather, the unadorned
.I name
is returned.
.SH EXAMPLES
To find the \f4ls\fP command using the \f4PATH\fP environment variable:
.PP
.RS
.ft 4
pathfind (getenv ("PATH"), "ls", "rx")
.ft 1
.RE
.SH "SEE ALSO"
\f4access\fP(2), \f4mknod\fP(2), \f4stat\fP(2), \f4getenv\fP(3C).
.br
\f4sh\fP(1), \f4test\fP(1) in the \f2User's Reference Manual\fP.
.SH DIAGNOSTICS
If no match is found,
\f4pathname\f1
returns a null pointer, \f4((char \(**) 0)\fP.
.SH NOTES
The string pointed to by the returned pointer is stored in a static
area that is reused on subsequent calls to
\f4pathfind\fP.
