1File::Glob(3pm)        Perl Programmers Reference Guide        File::Glob(3pm)
2
3
4

NAME

6       File::Glob - Perl extension for BSD glob routine
7

SYNOPSIS

9         use File::Glob ':bsd_glob';
10
11         @list = bsd_glob('*.[ch]');
12         $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR);
13
14         if (GLOB_ERROR) {
15           # an error occurred reading $homedir
16         }
17
18         ## 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
23         ## override the core glob, forcing case sensitivity
24         use File::Glob qw(:globally :case);
25         my @sources = <*.{c,h,y}>;
26
27         ## override the core glob forcing case insensitivity
28         use File::Glob qw(:globally :nocase);
29         my @sources = <*.{c,h,y}>;
30
31         ## glob on all files in home directory
32         use File::Glob ':globally';
33         my @sources = <~gnat/*>;
34

DESCRIPTION

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
40       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
47       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
55   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
63       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
68   EXPORTS
69       See also the "POSIX FLAGS" below, which can be exported individually.
70
71       ":bsd_glob"
72
73       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
80       ":glob"
81
82       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
87           use File::Glob ':glob';
88           while (my $file = <* copy.txt>) {
89               ...
90           }
91
92       "bsd_glob"
93
94       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
99       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
104       ":nocase" and ":case"
105
106       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
110       "csh_glob"
111
112       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
117   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
122       "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
127       "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
135       "GLOB_MARK"
136           Each pathname that is a directory that matches the pattern has a
137           slash appended.
138
139       "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
143       "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
148       "GLOB_NOSORT"
149           By default, the pathnames are sorted in ascending ASCII order; this
150           flag prevents that sorting (speeding up bsd_glob()).
151
152       The FreeBSD extensions to the POSIX standard are the following flags:
153
154       "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
160       "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
166       "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
172       "GLOB_TILDE"
173           Expand patterns that start with '~' to user name home directories.
174
175       "GLOB_CSH"
176           For convenience, "GLOB_CSH" is a synonym for "GLOB_BRACE |
177           GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT".
178
179       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
184       The following flag has been added in the Perl implementation for csh
185       compatibility:
186
187       "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

DIAGNOSTICS

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
197       "GLOB_NOSPACE"
198           An attempt to allocate memory failed.
199
200       "GLOB_ABEND"
201           The glob was stopped because an error was encountered.
202
203       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
207       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
212       Be aware that all filenames returned from File::Glob are tainted.
213

NOTES

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
221       •   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
232       •   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

SEE ALSO

237       "glob" in perlfunc, glob(3)
238

AUTHOR

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
246       Copyright (c) 1989, 1993 The Regents of the University of California.
247       All rights reserved.
248
249       This code is derived from software contributed to Berkeley by Guido van
250       Rossum.
251
252       Redistribution and use in source and binary forms, with or without
253       modification, are permitted provided that the following conditions are
254       met:
255
256       1.  Redistributions of source code must retain the above copyright
257           notice, this list of conditions and the following disclaimer.
258
259       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
264       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
268       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.
279
280
281
282perl v5.32.1                      2021-05-31                   File::Glob(3pm)
Impressum