1File::Glob(3pm) Perl Programmers Reference Guide File::Glob(3pm)
2
6 File::Glob - Perl extension for BSD glob routine
7
9 use File::Glob ':bsd_glob';
10 @list = bsd_glob('*.[ch]');
12 $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR);
13 if (GLOB_ERROR) {
15 # an error occurred reading $homedir
16 }
17 ## override the core glob (CORE::glob() does this automatically
19 ## by default anyway, since v5.6.0)
20 use File::Glob ':globally';
21 my @sources = <*.{c,h,y}>;
22 ## override the core glob, forcing case sensitivity
24 use File::Glob qw(:globally :case);
25 my @sources = <*.{c,h,y}>;
26 ## override the core glob forcing case insensitivity
28 use File::Glob qw(:globally :nocase);
29 my @sources = <*.{c,h,y}>;
30 ## glob on all files in home directory
32 use File::Glob ':globally';
33 my @sources = <~gnat/*>;
34
36 The glob angle-bracket operator "<>" is a pathname generator that
37 implements the rules for file name pattern matching used by Unix-like
38 shells such as the Bourne shell or C shell.
39 File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is
41 a superset of the POSIX glob() (described in IEEE Std 1003.2
42 "POSIX.2"). bsd_glob() takes a mandatory "pattern" argument, and an
43 optional "flags" argument, and returns a list of filenames matching the
44 pattern, with interpretation of the pattern modified by the "flags"
45 variable.
46 Since v5.6.0, Perl's CORE::glob() is implemented in terms of
48 bsd_glob(). Note that they don't share the same
49 prototype--CORE::glob() only accepts a single argument. Due to
50 historical reasons, CORE::glob() will also split its argument on
51 whitespace, treating it as multiple patterns, whereas bsd_glob()
52 considers them as one pattern. But see ":bsd_glob" under "EXPORTS",
53 below.
54 META CHARACTERS
56 \ Quote the next metacharacter
57 [] Character class
58 {} Multiple pattern
59 * Match any string of characters
60 ? Match any single character
61 ~ User name home directory
62 The metanotation "a{b,c,d}e" is a shorthand for "abe ace ade". Left to
64 right order is preserved, with results of matches being sorted
65 separately at a low level to preserve this order. As a special case
66 "{", "}", and "{}" are passed undisturbed.
67 EXPORTS
69 See also the "POSIX FLAGS" below, which can be exported individually.
70 ":bsd_glob"
72 The ":bsd_glob" export tag exports bsd_glob() and the constants listed
74 below. It also overrides glob() in the calling package with one that
75 behaves like bsd_glob() with regard to spaces (the space is treated as
76 part of a file name), but supports iteration in scalar context; i.e.,
77 it preserves the core function's feature of returning the next item
78 each time it is called.
79 ":glob"
81 The ":glob" tag, now discouraged, is the old version of ":bsd_glob".
83 It exports the same constants and functions, but its glob() override
84 does not support iteration; it returns the last file name in scalar
85 context. That means this will loop forever:
86 use File::Glob ':glob';
88 while (my $file = <* copy.txt>) {
89 ...
90 }
91 "bsd_glob"
93 This function, which is included in the two export tags listed above,
95 takes one or two arguments. The first is the glob pattern. The
96 second, if given, is a set of flags ORed together. The available flags
97 and the default set of flags are listed below under "POSIX FLAGS".
98 Remember that to use the named constants for flags you must import
100 them, for example with ":bsd_glob" described above. If not imported,
101 and "use strict" is not in effect, then the constants will be treated
102 as bareword strings, which won't do what you what.
103 ":nocase" and ":case"
105 These two export tags globally modify the default flags that bsd_glob()
107 and, except on VMS, Perl's built-in "glob" operator use. "GLOB_NOCASE"
108 is turned on or off, respectively.
109 "csh_glob"
111 The csh_glob() function can also be exported, but you should not use it
113 directly unless you really know what you are doing. It splits the
114 pattern into words and feeds each one to bsd_glob(). Perl's own glob()
115 function uses this internally.
116 POSIX FLAGS
118 If no flags argument is give then "GLOB_CSH" is set, and on VMS and
119 Windows systems, "GLOB_NOCASE" too. Otherwise the flags to use are
120 determined solely by the flags argument. The POSIX defined flags are:
121 "GLOB_ERR"
123 Force bsd_glob() to return an error when it encounters a directory
124 it cannot open or read. Ordinarily bsd_glob() continues to find
125 matches.
126 "GLOB_LIMIT"
128 Make bsd_glob() return an error (GLOB_NOSPACE) when the pattern
129 expands to a size bigger than the system constant "ARG_MAX"
130 (usually found in limits.h). If your system does not define this
131 constant, bsd_glob() uses "sysconf(_SC_ARG_MAX)" or
132 "_POSIX_ARG_MAX" where available (in that order). You can inspect
133 these values using the standard "POSIX" extension.
134 "GLOB_MARK"
136 Each pathname that is a directory that matches the pattern has a
137 slash appended.
138 "GLOB_NOCASE"
140 By default, file names are assumed to be case sensitive; this flag
141 makes bsd_glob() treat case differences as not significant.
142 "GLOB_NOCHECK"
144 If the pattern does not match any pathname, then bsd_glob() returns
145 a list consisting of only the pattern. If "GLOB_QUOTE" is set, its
146 effect is present in the pattern returned.
147 "GLOB_NOSORT"
149 By default, the pathnames are sorted in ascending ASCII order; this
150 flag prevents that sorting (speeding up bsd_glob()).
151 The FreeBSD extensions to the POSIX standard are the following flags:
153 "GLOB_BRACE"
155 Pre-process the string to expand "{pat,pat,...}" strings like
156 csh(1). The pattern '{}' is left unexpanded for historical reasons
157 (and csh(1) does the same thing to ease typing of find(1)
158 patterns).
159 "GLOB_NOMAGIC"
161 Same as "GLOB_NOCHECK" but it only returns the pattern if it does
162 not contain any of the special characters "*", "?" or "[".
163 "NOMAGIC" is provided to simplify implementing the historic csh(1)
164 globbing behaviour and should probably not be used anywhere else.
165 "GLOB_QUOTE"
167 Use the backslash ('\') character for quoting: every occurrence of
168 a backslash followed by a character in the pattern is replaced by
169 that character, avoiding any special interpretation of the
170 character. (But see below for exceptions on DOSISH systems).
171 "GLOB_TILDE"
173 Expand patterns that start with '~' to user name home directories.
174 "GLOB_CSH"
176 For convenience, "GLOB_CSH" is a synonym for "GLOB_BRACE |
177 GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT".
178 The POSIX provided "GLOB_APPEND", "GLOB_DOOFFS", and the FreeBSD
180 extensions "GLOB_ALTDIRFUNC", and "GLOB_MAGCHAR" flags have not been
181 implemented in the Perl version because they involve more complex
182 interaction with the underlying C structures.
183 The following flag has been added in the Perl implementation for csh
185 compatibility:
186 "GLOB_ALPHASORT"
188 If "GLOB_NOSORT" is not in effect, sort filenames is alphabetical
189 order (case does not matter) rather than in ASCII order.
190
192 bsd_glob() returns a list of matching paths, possibly zero length. If
193 an error occurred, &File::Glob::GLOB_ERROR will be non-zero and $! will
194 be set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error
195 occurred, or one of the following values otherwise:
196 "GLOB_NOSPACE"
198 An attempt to allocate memory failed.
199 "GLOB_ABEND"
201 The glob was stopped because an error was encountered.
202 In the case where bsd_glob() has found some matching paths, but is
204 interrupted by an error, it will return a list of filenames and set
205 &File::Glob::ERROR.
206 Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour
208 by not considering "ENOENT" and "ENOTDIR" as errors - bsd_glob() will
209 continue processing despite those errors, unless the "GLOB_ERR" flag is
210 set.
211 Be aware that all filenames returned from File::Glob are tainted.
213
215 • If you want to use multiple patterns, e.g. "bsd_glob("a* b*")", you
216 should probably throw them in a set as in "bsd_glob("{a*,b*}")".
217 This is because the argument to bsd_glob() isn't subjected to
218 parsing by the C shell. Remember that you can use a backslash to
219 escape things.
220 • On DOSISH systems, backslash is a valid directory separator
222 character. In this case, use of backslash as a quoting character
223 (via GLOB_QUOTE) interferes with the use of backslash as a
224 directory separator. The best (simplest, most portable) solution
225 is to use forward slashes for directory separators, and backslashes
226 for quoting. However, this does not match "normal practice" on
227 these systems. As a concession to user expectation, therefore,
228 backslashes (under GLOB_QUOTE) only quote the glob metacharacters
229 '[', ']', '{', '}', '-', '~', and backslash itself. All other
230 backslashes are passed through unchanged.
231 • Win32 users should use the real slash. If you really want to use
233 backslashes, consider using Sarathy's File::DosGlob, which comes
234 with the standard Perl distribution.
235
237 "glob" in perlfunc, glob(3)
238
240 The Perl interface was written by Nathan Torkington <gnat@frii.com>,
241 and is released under the artistic license. Further modifications were
242 made by Greg Bacon <gbacon@cs.uah.edu>, Gurusamy Sarathy
243 <gsar@activestate.com>, and Thomas Wegner <wegner_thomas@yahoo.com>.
244 The C glob code has the following copyright:
245 Copyright (c) 1989, 1993 The Regents of the University of California.
247 All rights reserved.
248 This code is derived from software contributed to Berkeley by Guido van
250 Rossum.
251 Redistribution and use in source and binary forms, with or without
253 modification, are permitted provided that the following conditions are
254 met:
255 1. Redistributions of source code must retain the above copyright
257 notice, this list of conditions and the following disclaimer.
258 2. Redistributions in binary form must reproduce the above copyright
260 notice, this list of conditions and the following disclaimer in the
261 documentation and/or other materials provided with the
262 distribution.
263 3. Neither the name of the University nor the names of its
265 contributors may be used to endorse or promote products derived
266 from this software without specific prior written permission.
267 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND
269 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
270 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
271 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS
272 BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
273 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
274 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
275 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
276 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
277 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
278 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
279perl v5.34.1 2022-03-15 File::Glob(3pm)