.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "File::SearchPath 3pm"
.TH File::SearchPath 3pm "2015-07-24" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::SearchPath \- Search for a file in an environment variable path
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use File::SearchPath qw/ searchpath /;
\&
\&  $file = searchpath( \*(Aqlibperl.a\*(Aq, env => \*(AqLD_LIBRARY_PATH\*(Aq );
\&  $file = searchpath( \*(Aqmy.cfg\*(Aq, env => \*(AqCFG_DIR\*(Aq, subdir => \*(AqME\*(Aq );
\&
\&  $path = searchpath( $file, env => \*(AqPATH\*(Aq, exe => 1 );
\&  $path = searchpath( $file, env => \*(AqPATH\*(Aq, dir => 1 );
\&
\&  $file = searchpath( \*(Aqls\*(Aq, $ENV{PATH} );
\&
\&  $exe = searchpath( \*(Aqls\*(Aq );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides the ability to search a path-like environment
variable for a file (that does not necessarily have to be an
executable).
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
The following functions can be exported by this module.
.IP "\fBsearchpath\fR" 4
.IX Item "searchpath"
This is the core function. The only mandatory argument is the name of
a file to be located. The filename should not be absolute although it
can include directory specifications.
.Sp
.Vb 2
\&  $path = searchpath( $file );
\&  @matches = searchpath( $file );
.Ve
.Sp
If a second argument is provided, it is assumed to be
a path like variable. This interface is provided for
backwards compatibility with \f(CW\*(C`File::SearchPath\*(C'\fR version 0.01. It is not
as portable as specifying the name of the environment variable. Note also
that no specific attempt will be made to check whether the file is
executable when the subroutine is called in this way.
.Sp
.Vb 1
\&  $path = searchpath( $file, $ENV{PATH} );
.Ve
.Sp
By default, this will search in \f(CW$PATH\fR for executable files and is
equivalent to:
.Sp
.Vb 1
\&  $path = searchpath( $file, env => \*(AqPATH\*(Aq, exe => 1 );
.Ve
.Sp
Hash-like options can be used to alter the behaviour of the
search:
.RS 4
.IP "env" 8
.IX Item "env"
Name of the environment variable to use as a starting point for the
search. Should be a path-like environment variable such as \f(CW$PATH\fR,
\&\f(CW$LD_LIBRARY_PATH\fR etc. Defaults to \f(CW$PATH\fR. An error occurs if the
environment variable is not set or not defined. If it is defined but
contains a blank string, the current directory will be assumed.
.IP "exe" 8
.IX Item "exe"
If true, only executable files will be located in the search path.
If \f(CW$PATH\fR is being searched, the default is for this to be true. For all
other environment variables the default is false. If \*(L"dir\*(R" option
is specified \*(L"exe\*(R" will always default to false.
.IP "dir" 8
.IX Item "dir"
If true, only directories will be located in the search path. Default
is false. \*(L"dir\*(R" and \*(L"exe\*(R" are not allowed to be true in the same
call. (triggering a \fIcroak()\fR on error).
.IP "subdir" 8
.IX Item "subdir"
If you know that your file is in a subdirectory of the path described
by the environment variable, this direcotry can be specified here.
Alternatively, the path can be included in the file name itself.
.RE
.RS 4
.Sp
In scalar context the first match is returned. In list context all
matches are returned in the order corresponding to the directories
listed in the environment variable.
.Sp
Returns undef (or empty list) if no match could be found.
.Sp
If an absolute file name is provided, that filename is returned if it
exists and is readable, else undef is returned.
.RE
.SH "HISTORY"
.IX Header "HISTORY"
\&\f(CW\*(C`File::SearchPath\*(C'\fR used to exist on \s-1CPAN \s0(now on backpan) and was
written by Robert Spier.  This version is completely new but retains
an interface that is compatible with Robert's version. Thanks to
Robert for allowing me to reuse this module name.
.SH "NOTES"
.IX Header "NOTES"
If \f(CW\*(C`Env::Path\*(C'\fR module is installed it will be used. This allows for
more flexibility than simply assuming colon-separated paths.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Env::Path, File::Which, File::Find, File::Find::Run,
File::Where.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tim Jenness <t.jenness@jach.hawaii.edu>
.PP
Copyright (C) 2005,2006, 2008 Particle Physics and Astronomy Research Council.
Copyright (C) 2009\-2010 Science and Technology Facilities Council.
All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it under
the terms of the \s-1GNU\s0 General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
.PP
This program is distributed in the hope that it will be useful,but \s-1WITHOUT ANY
WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A
PARTICULAR PURPOSE.\s0 See the \s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place,Suite 330, Boston, \s-1MA  02111\-1307, USA\s0