1File::SearchPath(3)   User Contributed Perl Documentation  File::SearchPath(3)
2
3
4

NAME

6       File::SearchPath - Search for a file in an environment variable path
7

SYNOPSIS

9         use File::SearchPath qw/ searchpath /;
10
11         $file = searchpath( 'libperl.a', env => 'LD_LIBRARY_PATH' );
12         $file = searchpath( 'my.cfg', env => 'CFG_DIR', subdir => 'ME' );
13
14         $path = searchpath( $file, env => 'PATH', exe => 1 );
15         $path = searchpath( $file, env => 'PATH', dir => 1 );
16
17         $file = searchpath( 'ls', $ENV{PATH} );
18
19         $exe = searchpath( 'ls' );
20

DESCRIPTION

22       This module provides the ability to search a path-like environment
23       variable for a file (that does not necessarily have to be an
24       executable).
25

FUNCTIONS

27       The following functions can be exported by this module.
28
29       searchpath
30           This is the core function. The only mandatory argument is the name
31           of a file to be located. The filename should not be absolute
32           although it can include directory specifications.
33
34             $path = searchpath( $file );
35             @matches = searchpath( $file );
36
37           If only two arguments are provided, it is assumed that the second
38           argument is a path-like string. This interface is provided for
39           backwards compatibility with "File::SearchPath" version 0.01. It is
40           not as portable as specifying the name of the environment variable.
41           Note also that no specific attempt will be made to check whether
42           the file is executable when the subroutine is called in this way.
43
44             $path = searchpath( $file, $ENV{PATH} );
45
46           By default, this will search in $PATH for executable files and is
47           equivalent to:
48
49             $path = searchpath( $file, env => 'PATH', exe => 0 );
50
51           Hash-like options can be used to alter the behaviour of the search:
52
53           env     Name of the environment variable to use as a starting point
54                   for the search. Should be a path-like environment variable
55                   such as $PATH, $LD_LIBRARY_PATH etc. Defaults to $PATH. An
56                   error occurs if the environment variable is not set or not
57                   defined. If it is defined but contains a blank string, the
58                   current directory will be assumed.
59
60           exe     If true, only executable files will be located in the
61                   search path.  If $PATH is being searched, the default is
62                   for this to be true. For all other environment variables
63                   the default is false. If "dir" option is specified "exe"
64                   will always default to false.
65
66           dir     If true, only directories will be located in the search
67                   path. Default is false. "dir" and "exe" are not allowed to
68                   be true in the same call. (triggering a croak() on error).
69
70           subdir  If you know that your file is in a subdirectory of the path
71                   described by the environment variable, this direcotry can
72                   be specified here.  Alternatively, the path can be included
73                   in the file name itself.
74
75           In scalar context the first match is returned. In list context all
76           matches are returned in the order corresponding to the directories
77           listed in the environment variable.
78
79           Returns undef (or empty list) if no match could be found.
80
81           If an absolute file name is provided, that filename is returned if
82           it exists and is readable, else undef is returned.
83

HISTORY

85       "File::SearchPath" used to exist on CPAN (now on backpan) and was
86       written by Robert Spier.  This version is completely new but retains an
87       interface that is compatible with Robert's version. Thanks to Robert
88       for allowing me to reuse this module name.
89

NOTES

91       If "Env::Path" module is installed it will be used. This allows for
92       more flexibility than simply assuming colon-separated paths.
93

SEE ALSO

95       Env::Path, File::Which, File::Find, File::Find::Run, File::Where.
96

AUTHOR

98       Tim Jenness <tjenness@cpan.org>
99
100       Copyright (C) 2005,2006, 2008 Particle Physics and Astronomy Research
101       Council.  Copyright (C) 2009-2010 Science and Technology Facilities
102       Council.  Copyright (C) 2015 Tim Jenness All Rights Reserved.
103
104       This program is free software; you can redistribute it and/or modify it
105       under the terms of the GNU General Public License as published by the
106       Free Software Foundation; either version 2 of the License, or (at your
107       option) any later version.
108
109       This program is distributed in the hope that it will be useful,but
110       WITHOUT ANY WARRANTY; without even the implied warranty of
111       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
112       General Public License for more details.
113
114       You should have received a copy of the GNU General Public License along
115       with this program; if not, write to the Free Software Foundation, Inc.,
116       59 Temple Place,Suite 330, Boston, MA  02111-1307, USA
117
118
119
120perl v5.36.0                      2023-01-20               File::SearchPath(3)
Impressum