.TH SEARCHPATH 1 "pdc Wed. 22 May 1991" "mff 2.8" "CONTRIBUTED PROGRAMS"
.SH NAME
searchpath \- search for a file along a colon-separated list of
directories
.SH SYNOPSIS
.\" searchpath.1 - man page for searchpath
.\" Copyright (C) 1990 Damian Cugley
.\" - pdc Wed. 19 Sept. 1990
.B searchpath
.I name
.I path
[
.I suffix
]
.SH DESCRIPTION
.I searchpath 
searches for 
.I name
along a `searchpath', i.e., a string of directory names separated by
colons, in the manner of
.IR sh (1)
(with 
.SM PATH\*S)
and 
.IR tex (1)
(with 
.SM TEXINPUTS\*S).
This can be used in shellscripts that manipulate files usually kept in
particular directories.
.LP
If 
.I name
contains a
.RB ` / ',
or 
.I path
is empty,
.I name
is not searched for and 
.I searchpath
succeeds iff a file called
.I name
exists.
Otherwise
.I searchpath
looks in each directory in the list for  a file called 
.I name
(or 
.I name.suffix
if the
.I suffix
argument is supplied).
.LP
A null directory \(em represented by two consecutive colons 
.RB ( :: ) 
or by a
colon at the start or end of the path \(em stands for the current
directory; this is for compatability with 
.IR sh .
An optional trailing slash is allowed after a directory name, so 
.B ./:/bin/:/usr/bin/
is equivalent to
.B .:/bin:/usr/bin 
or 
.BR :/bin:/usr/bin .
.LP
If the search succeeds, the name of the found file is printed on the
standard outut stream.  Otherwise
.I name
is echoed verbatim and an error message is printed on the standard error
stream, and 
.I searchpath
exits with a nonzero status value.
.SH EXAMPLE
To mimic the 
.if t T\v|0.25m|\h|-0.1m|E\v|-0.25m|X
.if n TeX
file-searching algorithm in a shellscript you might use:
.if t .sp 0.5v
.if n .sp
.RS
.nf
.ft B
fullname=\(gasearchpath $1 ${TEXINPUTS\-.:/usr/local/tex/macros} .tex\(ga
[ $? \-ne 0 ] && exit 1
\&.\|.\|.
.ft P
.fi
.RE
.if t .sp 0.5v
.if n .sp
This succeeds whether $1 has a 
.B .tex
at the end or not (however, if $1 is
.BR foo ,
say, and there is a file 
.I foo
then this will be found instead of
.IR foo.tex ).
.SH AUTHOR
Damian Cugley <pdc@prg.ox.ac.uk>.  See the 
.IR mff (1)
for information about reporting bugs.
.SH "SEE ALSO"
basename(1), dirname(1), sh(1), findfile(3)