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 ':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.
53
54   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
62       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
67   POSIX FLAGS
68       The POSIX defined flags for bsd_glob() are:
69
70       "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
75       "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
83       "GLOB_MARK"
84           Each pathname that is a directory that matches the pattern has a
85           slash appended.
86
87       "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
91       "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
96       "GLOB_NOSORT"
97           By default, the pathnames are sorted in ascending ASCII order; this
98           flag prevents that sorting (speeding up bsd_glob()).
99
100       The FreeBSD extensions to the POSIX standard are the following flags:
101
102       "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
108       "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
114       "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
120       "GLOB_TILDE"
121           Expand patterns that start with '~' to user name home directories.
122
123       "GLOB_CSH"
124           For convenience, "GLOB_CSH" is a synonym for "GLOB_BRACE |
125           GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT".
126
127       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
132       The following flag has been added in the Perl implementation for csh
133       compatibility:
134
135       "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

DIAGNOSTICS

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
145       "GLOB_NOSPACE"
146           An attempt to allocate memory failed.
147
148       "GLOB_ABEND"
149           The glob was stopped because an error was encountered.
150
151       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
155       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
160       Be aware that all filenames returned from File::Glob are tainted.
161

NOTES

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
169       ·   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
180       ·   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
184       ·   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
189           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
193           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
199           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
210           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
219           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

SEE ALSO

226       "glob" in perlfunc, glob(3)
227

AUTHOR

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
235           Copyright (c) 1989, 1993 The Regents of the University of California.
236           All rights reserved.
237
238           This code is derived from software contributed to Berkeley by
239           Guido van Rossum.
240
241           Redistribution and use in source and binary forms, with or without
242           modification, are permitted provided that the following conditions
243           are met:
244
245           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
254           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.
265
266
267
268perl v5.10.1                      2009-04-14                   File::Glob(3pm)
Impressum