File::Glob - Perl extension for BSD glob routine

NAME
SUPPORTED PLATFORMS
SYNOPSIS
DESCRIPTION
DIAGNOSTICS
NOTES
AUTHOR
NAME
File::Glob - Perl extension for BSD glob routine
SUPPORTED PLATFORMS
Linux
Solaris
Windows
SYNOPSIS use File::Glob ':glob';
@list = bsd_glob('*.[ch]');
$homedir = bsd_glob('~gnat', GLOB_TILDE GLOB_ERR);
if (GLOB_ERROR) {
# 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}>
DESCRIPTION
File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is a superset of the POSIX glob() (described in IEEE Std 1003.2 ``POSIX.2''). bsd_glob() takes a mandatory pattern argument, and an optional flags argument, and returns a list of filenames matching the pattern, with interpretation of the pattern modified by the flags variable.
Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob(). Note that they don't share the same prototype--CORE::glob() only accepts a single argument. Due to historical reasons, CORE::glob() will also split its argument on whitespace, treating it as multiple patterns, whereas bsd_glob() considers them as one pattern.
The POSIX defined flags for bsd_glob() are:
GLOB_ERR
Force bsd_glob() to return an error when it encounters a directory it cannot open or read. Ordinarily bsd_glob() continues to find matches.
GLOB_MARK
Each pathname that is a directory that matches the pattern has a slash appended.
GLOB_NOCASE
By default, file names are assumed to be case sensitive; this flag makes bsd_glob() treat case differences as not significant.
GLOB_NOCHECK
If the pattern does not match any pathname, then bsd_glob() returns a list consisting of only the pattern. If GLOB_QUOTE is set, its effect is present in the pattern returned.
GLOB_NOSORT
By default, the pathnames are sorted in ascending ASCII order; this flag prevents that sorting (speeding up bsd_glob()).
The FreeBSD extensions to the POSIX standard are the following flags:
GLOB_BRACE
Pre-process the string to expand {pat,pat,...} strings like csh(1). The pattern '{}' is left unexpanded for historical reasons (and csh(1) does the same thing to ease typing of find(1) patterns).
GLOB_NOMAGIC
Same as GLOB_NOCHECK but it only returns the pattern if it does not contain any of the special characters ``*'', ``?'' or ``[''. NOMAGIC is provided to simplify implementing the historic csh(1) globbing behaviour and should probably not be used anywhere else.
GLOB_QUOTE
Use the backslash ('\') 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 DOSISH systems).
GLOB_TILDE
Expand patterns that start with '~' to user name home directories.
GLOB_CSH
For convenience, GLOB_CSH is a synonym for GLOB_BRACE GLOB_NOMAGIC GLOB_QUOTE GLOB_TILDE.
The POSIX provided GLOB_APPEND, GLOB_DOOFFS, and the FreeBSD extensions GLOB_ALTDIRFUNC, and GLOB_MAGCHAR flags have not been implemented in the Perl version because they involve more complex interaction with the underlying C structures.
DIAGNOSTICS
bsd_glob() returns a list of matching paths, possibly zero length. If an error occurred, &File::Glob::GLOB_ERROR will be non-zero and $! will be set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred, or one of the following values otherwise:
GLOB_NOSPACE
An attempt to allocate memory failed.
GLOB_ABEND
The glob was stopped because an error was encountered.
In the case where bsd_glob() has found some matching paths, but is interrupted by an error, it will return a list of filenames and set &File::Glob::ERROR.
Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour by not considering ENOENT and ENOTDIR as errors - bsd_glob() will continue processing despite those errors, unless the GLOB_ERR flag is set.
Be aware that all filenames returned from File::Glob are tainted.
NOTES
If you want to use multiple patterns, e.g. bsd_glob "a* b*", you should probably throw them in a set as in bsd_glob "{a*,b*}". This is because the argument to bsd_glob() isn't subjected to parsing by the C shell. Remember that you can use a backslash to escape things.
On DOSISH systems, backslash is a valid directory separator character. In this case, use of backslash as a quoting character (via GLOB_QUOTE) 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 ``normal practice'' on these systems. As a concession to user expectation, therefore, backslashes (under GLOB_QUOTE) 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.