META CHARACTERS

  \       Quote the next metacharacter
  []      Character class
  {}      Multiple pattern
  *       Match any string of characters
  ?       Match any single character
  ~       User name home directory

The metanotation "a{b,c,d}e" is a shorthand for "abe ace ade". 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 "{", "}", and "{}" are passed undisturbed.

EXPORTS

":bsd_glob"

The ":bsd_glob" export tag exports bsd_glob() and the constants listed below. It also overrides glob() in the calling package with one that behaves like bsd_glob() with regard to spaces (the space is treated as part of a file name), but supports iteration in scalar context; i.e., it preserves the core function's feature of returning the next item each time it is called.

":glob"

The ":glob" tag, now discouraged, is the old version of ":bsd_glob". It exports the same constants and functions, but its glob() override does not support iteration; it returns the last file name in scalar context. That means this will loop forever:

    use File::Glob ':glob';
    while (my $file = <* copy.txt>) {
        ...
    }

"bsd_glob"

This function, which is included in the two export tags listed above, takes one or two arguments. The first is the glob pattern. The second, if given, is a set of flags ORed together. The available flags and the default set of flags are listed below under "POSIX FLAGS".

Remember that to use the named constants for flags you must import them, for example with ":bsd_glob" described above. If not imported, and "use strict" is not in effect, then the constants will be treated as bareword strings, which won't do what you what.

":nocase" and ":case"

These two export tags globally modify the default flags that bsd_glob() and, except on VMS, Perl's built-in "glob" operator use. "GLOB_NOCASE" is turned on or off, respectively.

"csh_glob"

The csh_glob() function can also be exported, but you should not use it directly unless you really know what you are doing. It splits the pattern into words and feeds each one to bsd_glob(). Perl's own glob() function uses this internally.

POSIX FLAGS

"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_LIMIT"

Make bsd_glob() return an error (GLOB_NOSPACE) when the pattern expands to a size bigger than the system constant "ARG_MAX" (usually found in limits.h). If your system does not define this constant, bsd_glob() uses "sysconf(_SC_ARG_MAX)" or "_POSIX_ARG_MAX" where available (in that order). You can inspect these values using the standard "POSIX" extension.

"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 | GLOB_ALPHASORT".

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.

The following flag has been added in the Perl implementation for csh compatibility:

"GLOB_ALPHASORT"

If "GLOB_NOSORT" is not in effect, sort filenames is alphabetical order (case does not matter) rather than in ASCII order.