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 ':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.
53 META CHARACTERS
55 \ Quote the next metacharacter
56 [] Character class
57 {} Multiple pattern
58 * Match any string of characters
59 ? Match any single character
60 ~ User name home directory
61 The metanotation "a{b,c,d}e" is a shorthand for "abe ace ade". Left to
63 right order is preserved, with results of matches being sorted
64 separately at a low level to preserve this order. As a special case
65 "{", "}", and "{}" are passed undisturbed.
66 POSIX FLAGS
68 The POSIX defined flags for bsd_glob() are:
69 "GLOB_ERR"
71 Force bsd_glob() to return an error when it encounters a directory
72 it cannot open or read. Ordinarily bsd_glob() continues to find
73 matches.
74 "GLOB_LIMIT"
76 Make bsd_glob() return an error (GLOB_NOSPACE) when the pattern
77 expands to a size bigger than the system constant "ARG_MAX"
78 (usually found in limits.h). If your system does not define this
79 constant, bsd_glob() uses "sysconf(_SC_ARG_MAX)" or
80 "_POSIX_ARG_MAX" where available (in that order). You can inspect
81 these values using the standard "POSIX" extension.
82 "GLOB_MARK"
84 Each pathname that is a directory that matches the pattern has a
85 slash appended.
86 "GLOB_NOCASE"
88 By default, file names are assumed to be case sensitive; this flag
89 makes bsd_glob() treat case differences as not significant.
90 "GLOB_NOCHECK"
92 If the pattern does not match any pathname, then bsd_glob() returns
93 a list consisting of only the pattern. If "GLOB_QUOTE" is set, its
94 effect is present in the pattern returned.
95 "GLOB_NOSORT"
97 By default, the pathnames are sorted in ascending ASCII order; this
98 flag prevents that sorting (speeding up bsd_glob()).
99 The FreeBSD extensions to the POSIX standard are the following flags:
101 "GLOB_BRACE"
103 Pre-process the string to expand "{pat,pat,...}" strings like
104 csh(1). The pattern '{}' is left unexpanded for historical reasons
105 (and csh(1) does the same thing to ease typing of find(1)
106 patterns).
107 "GLOB_NOMAGIC"
109 Same as "GLOB_NOCHECK" but it only returns the pattern if it does
110 not contain any of the special characters "*", "?" or "[".
111 "NOMAGIC" is provided to simplify implementing the historic csh(1)
112 globbing behaviour and should probably not be used anywhere else.
113 "GLOB_QUOTE"
115 Use the backslash ('\') character for quoting: every occurrence of
116 a backslash followed by a character in the pattern is replaced by
117 that character, avoiding any special interpretation of the
118 character. (But see below for exceptions on DOSISH systems).
119 "GLOB_TILDE"
121 Expand patterns that start with '~' to user name home directories.
122 "GLOB_CSH"
124 For convenience, "GLOB_CSH" is a synonym for "GLOB_BRACE |
125 GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT".
126 The POSIX provided "GLOB_APPEND", "GLOB_DOOFFS", and the FreeBSD
128 extensions "GLOB_ALTDIRFUNC", and "GLOB_MAGCHAR" flags have not been
129 implemented in the Perl version because they involve more complex
130 interaction with the underlying C structures.
131 The following flag has been added in the Perl implementation for csh
133 compatibility:
134 "GLOB_ALPHASORT"
136 If "GLOB_NOSORT" is not in effect, sort filenames is alphabetical
137 order (case does not matter) rather than in ASCII order.
138
140 bsd_glob() returns a list of matching paths, possibly zero length. If
141 an error occurred, &File::Glob::GLOB_ERROR will be non-zero and $! will
142 be set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error
143 occurred, or one of the following values otherwise:
144 "GLOB_NOSPACE"
146 An attempt to allocate memory failed.
147 "GLOB_ABEND"
149 The glob was stopped because an error was encountered.
150 In the case where bsd_glob() has found some matching paths, but is
152 interrupted by an error, it will return a list of filenames and set
153 &File::Glob::ERROR.
154 Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour
156 by not considering "ENOENT" and "ENOTDIR" as errors - bsd_glob() will
157 continue processing despite those errors, unless the "GLOB_ERR" flag is
158 set.
159 Be aware that all filenames returned from File::Glob are tainted.
161
163 · If you want to use multiple patterns, e.g. "bsd_glob("a* b*")", you
164 should probably throw them in a set as in "bsd_glob("{a*,b*}")".
165 This is because the argument to bsd_glob() isn't subjected to
166 parsing by the C shell. Remember that you can use a backslash to
167 escape things.
168 · On DOSISH systems, backslash is a valid directory separator
170 character. In this case, use of backslash as a quoting character
171 (via GLOB_QUOTE) interferes with the use of backslash as a
172 directory separator. The best (simplest, most portable) solution is
173 to use forward slashes for directory separators, and backslashes
174 for quoting. However, this does not match "normal practice" on
175 these systems. As a concession to user expectation, therefore,
176 backslashes (under GLOB_QUOTE) only quote the glob metacharacters
177 '[', ']', '{', '}', '-', '~', and backslash itself. All other
178 backslashes are passed through unchanged.
179 · Win32 users should use the real slash. If you really want to use
181 backslashes, consider using Sarathy's File::DosGlob, which comes
182 with the standard Perl distribution.
183 · Mac OS (Classic) users should note a few differences. Since Mac OS
185 is not Unix, when the glob code encounters a tilde glob (e.g.
186 ~user) and the "GLOB_TILDE" flag is used, it simply returns that
187 pattern without doing any expansion.
188 Glob on Mac OS is case-insensitive by default (if you don't use any
190 flags). If you specify any flags at all and still want glob to be
191 case-insensitive, you must include "GLOB_NOCASE" in the flags.
192 The path separator is ':' (aka colon), not '/' (aka slash). Mac OS
194 users should be careful about specifying relative pathnames. While
195 a full path always begins with a volume name, a relative pathname
196 should always begin with a ':'. If specifying a volume name only,
197 a trailing ':' is required.
198 The specification of pathnames in glob patterns adheres to the
200 usual Mac OS conventions: The path separator is a colon ':', not a
201 slash '/'. A full path always begins with a volume name. A relative
202 pathname on Mac OS must always begin with a ':', except when
203 specifying a file or directory name in the current working
204 directory, where the leading colon is optional. If specifying a
205 volume name only, a trailing ':' is required. Due to these rules, a
206 glob like <*:> will find all mounted volumes, while a glob like <*>
207 or <:*> will find all files and directories in the current
208 directory.
209 Note that updirs in the glob pattern are resolved before the
211 matching begins, i.e. a pattern like "*HD:t?p::a*" will be matched
212 as "*HD:a*". Note also, that a single trailing ':' in the pattern
213 is ignored (unless it's a volume name pattern like "*HD:"), i.e. a
214 glob like <:*:> will find both directories and files (and not, as
215 one might expect, only directories). You can, however, use the
216 "GLOB_MARK" flag to distinguish (without a file test) directory
217 names from file names.
218 If the "GLOB_MARK" flag is set, all directory paths will have a ':'
220 appended. Since a directory like 'lib:' is not a valid relative
221 path on Mac OS, both a leading and a trailing colon will be added,
222 when the directory name in question doesn't contain any colons
223 (e.g. 'lib' becomes ':lib:').
224
226 "glob" in perlfunc, glob(3)
227
229 The Perl interface was written by Nathan Torkington <gnat@frii.com>,
230 and is released under the artistic license. Further modifications were
231 made by Greg Bacon <gbacon@cs.uah.edu>, Gurusamy Sarathy
232 <gsar@activestate.com>, and Thomas Wegner <wegner_thomas@yahoo.com>.
233 The C glob code has the following copyright:
234 Copyright (c) 1989, 1993 The Regents of the University of California.
236 All rights reserved.
237 This code is derived from software contributed to Berkeley by
239 Guido van Rossum.
240 Redistribution and use in source and binary forms, with or without
242 modification, are permitted provided that the following conditions
243 are met:
244 1. Redistributions of source code must retain the above copyright
246 notice, this list of conditions and the following disclaimer.
247 2. Redistributions in binary form must reproduce the above copyright
248 notice, this list of conditions and the following disclaimer in the
249 documentation and/or other materials provided with the distribution.
250 3. Neither the name of the University nor the names of its contributors
251 may be used to endorse or promote products derived from this software
252 without specific prior written permission.
253 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
255 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
256 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
257 ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
258 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
259 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
260 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
261 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
262 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
263 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
264 SUCH DAMAGE.
265perl v5.12.4 2011-06-07 File::Glob(3pm)