.\" This man page was written to conform with the lenviron v1.1.3
.\" release for Gno v2.0.3 and later by Devin Reade.
.\"
.\" $Id: buildPath.3,v 1.1 1997/02/27 07:32:21 gdr Exp $
.\"
.TH BUILDPATH 3 "30 January 1997" GNO "Library Routines"
.SH NAME
buildPath - search PATH and return the full path name of an executable file
.SH SYNOPSIS
#include <gno/gno.h>
.sp 1
char *\fBbuildPath\fR (const char *\fIfile\fR);
.SH DESCRIPTION
.BR buildPath
searches the directories listed in the
.BR PATH
environment variable for
.IR file .
.LP
If
.IR file
resides within
.BR PATH ,
then
.BR buildPath
constructs a string with
.BR malloc (3)
which contains the full pathname of the file.  If 
.IR file
itself specifies a fully qualified pathname, then the constructed
string will be a copy of
.IR file ,
and no test for existence will be done.
.LP
If PATH is not set or is the empty string, then
.BR buildPath
will default to searching
.BR bin
then
.BR /usr/bin .
.SH RETURN VALUES
On success, the constructed string is returned.  On error, NULL is
returned and 
.BR errno
is set.
.SH CAVEATS
The current version of
.BR gsh
parse the PATH variable backwards, so for compatibility
.BR buildPath
will currently also search PATH backwards.
.SH HISTORY
This routine was originally called
.BR build_path
and was part of the 
.BR lenviron
library written by Devin Reade for GNO v2.0.3 in April 1994.
It was incorporated into the GNO
.BR libc
as of v2.0.6.
.SH SEE ALSO
.BR buildCmd (3),
.BR buildEnv (3),
.BR isRootPath (3),
.BR environ (7).