.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\" ========================================================================
.de Sh \" Subsection heading
.de Sp \" Vertical space (when we can't use .PP)
.de Vb \" Begin verbatim text
.de Ve \" End verbatim text
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
. tm Index:\\$1\t\\n%\t"\\$2"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. \" simple accents for nroff and troff
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
.\" ========================================================================
.TH File::Glob 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide"
File::Glob \- Perl extension for BSD glob routine
\& use File::Glob ':glob';
\& @list = bsd_glob('*.[ch]');
\& $homedir = bsd_glob('~gnat', GLOB_TILDE | GLOB_ERR);
\& # an error occurred reading $homedir
\& ## override the core glob (CORE::glob() does this automatically
\& ## by default anyway, since v5.6.0)
\& use File::Glob ':globally';
\& my @sources = <*.{c,h,y}>;
\& ## override the core glob, forcing case sensitivity
\& use File::Glob qw(:globally :case);
\& my @sources = <*.{c,h,y}>;
\& ## override the core glob forcing case insensitivity
\& use File::Glob qw(:globally :nocase);
\& my @sources = <*.{c,h,y}>;
\& ## glob on all files in home directory
\& use File::Glob ':globally';
\& my @sources = <~gnat/*>;
The glob angle-bracket operator \f(CW\*(C`<>\*(C'\fR is a pathname generator that
implements the rules for file name pattern matching used by Unix-like shells
such as the Bourne shell or C shell.
\&\fIFile::Glob::bsd_glob()\fR implements the FreeBSD \fIglob\fR\|(3) routine, which is
a superset of the \s-1POSIX\s0 \fIglob()\fR (described in \s-1IEEE\s0 Std 1003.2 \*(L"\s-1POSIX\s0.2\*(R").
\&\fIbsd_glob()\fR takes a mandatory \f(CW\*(C`pattern\*(C'\fR argument, and an optional
\&\f(CW\*(C`flags\*(C'\fR argument, and returns a list of filenames matching the
pattern, with interpretation of the pattern modified by the \f(CW\*(C`flags\*(C'\fR
Since v5.6.0, Perl's \fICORE::glob()\fR is implemented in terms of \fIbsd_glob()\fR.
Note that they don't share the same prototype\*(--\fICORE::glob()\fR only accepts
a single argument. Due to historical reasons, \fICORE::glob()\fR will also
split its argument on whitespace, treating it as multiple patterns,
whereas \fIbsd_glob()\fR considers them as one pattern.
.Sh "\s-1META\s0 \s-1CHARACTERS\s0"
.IX Subsection "META CHARACTERS"
\& \e Quote the next metacharacter
\& * Match any string of characters
\& ? Match any single character
\& ~ User name home directory
The metanotation \f(CW\*(C`a{b,c,d}e\*(C'\fR is a shorthand for \f(CW\*(C`abe ace ade\*(C'\fR. Left to
right order is preserved, with results of matches being sorted separately
at a low level to preserve this order. As a special case \f(CW\*(C`{\*(C'\fR, \f(CW\*(C`}\*(C'\fR, and
\&\f(CW\*(C`{}\*(C'\fR are passed undisturbed.
.Sh "\s-1POSIX\s0 \s-1FLAGS\s0"
.IX Subsection "POSIX FLAGS"
The \s-1POSIX\s0 defined flags for \fIbsd_glob()\fR are:
.ie n .IP """GLOB_ERR""" 4
.el .IP "\f(CWGLOB_ERR\fR" 4
Force \fIbsd_glob()\fR to return an error when it encounters a directory it
cannot open or read. Ordinarily \fIbsd_glob()\fR continues to find matches.
.ie n .IP """GLOB_LIMIT""" 4
.el .IP "\f(CWGLOB_LIMIT\fR" 4
Make \fIbsd_glob()\fR return an error (\s-1GLOB_NOSPACE\s0) when the pattern expands
to a size bigger than the system constant \f(CW\*(C`ARG_MAX\*(C'\fR (usually found in
limits.h). If your system does not define this constant, \fIbsd_glob()\fR uses
\&\f(CW\*(C`sysconf(_SC_ARG_MAX)\*(C'\fR or \f(CW\*(C`_POSIX_ARG_MAX\*(C'\fR where available (in that
order). You can inspect these values using the standard \f(CW\*(C`POSIX\*(C'\fR
.ie n .IP """GLOB_MARK""" 4
.el .IP "\f(CWGLOB_MARK\fR" 4
Each pathname that is a directory that matches the pattern has a slash
.ie n .IP """GLOB_NOCASE""" 4
.el .IP "\f(CWGLOB_NOCASE\fR" 4
By default, file names are assumed to be case sensitive; this flag
makes \fIbsd_glob()\fR treat case differences as not significant.
.ie n .IP """GLOB_NOCHECK""" 4
.el .IP "\f(CWGLOB_NOCHECK\fR" 4
If the pattern does not match any pathname, then \fIbsd_glob()\fR returns a list
consisting of only the pattern. If \f(CW\*(C`GLOB_QUOTE\*(C'\fR is set, its effect
is present in the pattern returned.
.ie n .IP """GLOB_NOSORT""" 4
.el .IP "\f(CWGLOB_NOSORT\fR" 4
By default, the pathnames are sorted in ascending \s-1ASCII\s0 order; this
flag prevents that sorting (speeding up \fIbsd_glob()\fR).
The FreeBSD extensions to the \s-1POSIX\s0 standard are the following flags:
.ie n .IP """GLOB_BRACE""" 4
.el .IP "\f(CWGLOB_BRACE\fR" 4
Pre-process the string to expand \f(CW\*(C`{pat,pat,...}\*(C'\fR strings like \fIcsh\fR\|(1).
The pattern '{}' is left unexpanded for historical reasons (and \fIcsh\fR\|(1)
does the same thing to ease typing of \fIfind\fR\|(1) patterns).
.ie n .IP """GLOB_NOMAGIC""" 4
.el .IP "\f(CWGLOB_NOMAGIC\fR" 4
Same as \f(CW\*(C`GLOB_NOCHECK\*(C'\fR but it only returns the pattern if it does not
contain any of the special characters \*(L"*\*(R", \*(L"?\*(R" or \*(L"[\*(R". \f(CW\*(C`NOMAGIC\*(C'\fR is
provided to simplify implementing the historic \fIcsh\fR\|(1) globbing
behaviour and should probably not be used anywhere else.
.ie n .IP """GLOB_QUOTE""" 4
.el .IP "\f(CWGLOB_QUOTE\fR" 4
Use the backslash ('\e') character for quoting: every occurrence of a
backslash followed by a character in the pattern is replaced by that
character, avoiding any special interpretation of the character.
(But see below for exceptions on \s-1DOSISH\s0 systems).
.ie n .IP """GLOB_TILDE""" 4
.el .IP "\f(CWGLOB_TILDE\fR" 4
Expand patterns that start with '~' to user name home directories.
.ie n .IP """GLOB_CSH""" 4
.el .IP "\f(CWGLOB_CSH\fR" 4
For convenience, \f(CW\*(C`GLOB_CSH\*(C'\fR is a synonym for
\&\f(CW\*(C`GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT\*(C'\fR.
The \s-1POSIX\s0 provided \f(CW\*(C`GLOB_APPEND\*(C'\fR, \f(CW\*(C`GLOB_DOOFFS\*(C'\fR, and the FreeBSD
extensions \f(CW\*(C`GLOB_ALTDIRFUNC\*(C'\fR, and \f(CW\*(C`GLOB_MAGCHAR\*(C'\fR flags have not been
implemented in the Perl version because they involve more complex
interaction with the underlying C structures.
The following flag has been added in the Perl implementation for
.ie n .IP """GLOB_ALPHASORT""" 4
.el .IP "\f(CWGLOB_ALPHASORT\fR" 4
.IX Item "GLOB_ALPHASORT"
If \f(CW\*(C`GLOB_NOSORT\*(C'\fR is not in effect, sort filenames is alphabetical
order (case does not matter) rather than in \s-1ASCII\s0 order.
\&\fIbsd_glob()\fR returns a list of matching paths, possibly zero length. If an
error occurred, &File::Glob::GLOB_ERROR will be non-zero and \f(CW$!\fR will be
set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred,
or one of the following values otherwise:
.ie n .IP """GLOB_NOSPACE""" 4
.el .IP "\f(CWGLOB_NOSPACE\fR" 4
An attempt to allocate memory failed.
.ie n .IP """GLOB_ABEND""" 4
.el .IP "\f(CWGLOB_ABEND\fR" 4
The glob was stopped because an error was encountered.
In the case where \fIbsd_glob()\fR has found some matching paths, but is
interrupted by an error, it will return a list of filenames \fBand\fR
Note that \fIbsd_glob()\fR deviates from \s-1POSIX\s0 and FreeBSD \fIglob\fR\|(3) behaviour
by not considering \f(CW\*(C`ENOENT\*(C'\fR and \f(CW\*(C`ENOTDIR\*(C'\fR as errors \- \fIbsd_glob()\fR will
continue processing despite those errors, unless the \f(CW\*(C`GLOB_ERR\*(C'\fR flag is
Be aware that all filenames returned from File::Glob are tainted.
If you want to use multiple patterns, e.g. \f(CW\*(C`bsd_glob("a* b*")\*(C'\fR, you should
probably throw them in a set as in \f(CW\*(C`bsd_glob("{a*,b*}")\*(C'\fR. This is because
the argument to \fIbsd_glob()\fR isn't subjected to parsing by the C shell.
Remember that you can use a backslash to escape things.
On \s-1DOSISH\s0 systems, backslash is a valid directory separator character.
In this case, use of backslash as a quoting character (via \s-1GLOB_QUOTE\s0)
interferes with the use of backslash as a directory separator. The
best (simplest, most portable) solution is to use forward slashes for
directory separators, and backslashes for quoting. However, this does
not match \*(L"normal practice\*(R" on these systems. As a concession to user
expectation, therefore, backslashes (under \s-1GLOB_QUOTE\s0) only quote the
glob metacharacters '[', ']', '{', '}', '\-', '~', and backslash itself.
All other backslashes are passed through unchanged.
Win32 users should use the real slash. If you really want to use
backslashes, consider using Sarathy's File::DosGlob, which comes with
the standard Perl distribution.
Mac \s-1OS\s0 (Classic) users should note a few differences. Since
Mac \s-1OS\s0 is not Unix, when the glob code encounters a tilde glob (e.g.
~user) and the \f(CW\*(C`GLOB_TILDE\*(C'\fR flag is used, it simply returns that
pattern without doing any expansion.
Glob on Mac \s-1OS\s0 is case-insensitive by default (if you don't use any
flags). If you specify any flags at all and still want glob
to be case\-insensitive, you must include \f(CW\*(C`GLOB_NOCASE\*(C'\fR in the flags.
The path separator is ':' (aka colon), not '/' (aka slash). Mac \s-1OS\s0 users
should be careful about specifying relative pathnames. While a full path
always begins with a volume name, a relative pathname should always
begin with a ':'. If specifying a volume name only, a trailing ':' is
The specification of pathnames in glob patterns adheres to the usual Mac
\&\s-1OS\s0 conventions: The path separator is a colon ':', not a slash '/'. A
full path always begins with a volume name. A relative pathname on Mac
\&\s-1OS\s0 must always begin with a ':', except when specifying a file or
directory name in the current working directory, where the leading colon
is optional. If specifying a volume name only, a trailing ':' is
required. Due to these rules, a glob like <*:> will find all
mounted volumes, while a glob like <*> or <:*> will find
all files and directories in the current directory.
Note that updirs in the glob pattern are resolved before the matching begins,
i.e. a pattern like \*(L"*HD:t?p::a*\*(R" will be matched as \*(L"*HD:a*\*(R". Note also,
that a single trailing ':' in the pattern is ignored (unless it's a volume
name pattern like \*(L"*HD:\*(R"), i.e. a glob like <:*:> will find both
directories \fIand\fR files (and not, as one might expect, only directories).
You can, however, use the \f(CW\*(C`GLOB_MARK\*(C'\fR flag to distinguish (without a file
test) directory names from file names.
If the \f(CW\*(C`GLOB_MARK\*(C'\fR flag is set, all directory paths will have a ':' appended.
Since a directory like 'lib:' is \fInot\fR a valid \fIrelative\fR path on Mac \s-1OS\s0,
both a leading and a trailing colon will be added, when the directory name in
question doesn't contain any colons (e.g. 'lib' becomes ':lib:').
\&\*(L"glob\*(R" in perlfunc, \fIglob\fR\|(3)
The Perl interface was written by Nathan Torkington <gnat@frii.com>,
and is released under the artistic license. Further modifications were
made by Greg Bacon <gbacon@cs.uah.edu>, Gurusamy Sarathy
<gsar@activestate.com>, and Thomas Wegner
<wegner_thomas@yahoo.com>. The C glob code has the
\& Copyright (c) 1989, 1993 The Regents of the University of California.
\& This code is derived from software contributed to Berkeley by
\& Redistribution and use in source and binary forms, with or without
\& modification, are permitted provided that the following conditions
\& 1. Redistributions of source code must retain the above copyright
\& notice, this list of conditions and the following disclaimer.
\& 2. Redistributions in binary form must reproduce the above copyright
\& notice, this list of conditions and the following disclaimer in the
\& documentation and/or other materials provided with the distribution.
\& 3. Neither the name of the University nor the names of its contributors
\& may be used to endorse or promote products derived from this software
\& without specific prior written permission.
\& THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
\& ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
\& IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
\& ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
\& FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
\& DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
\& OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
\& HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
\& LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
\& OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
projects / OpenSPARC-T2-SAM / blob