[p5sagit/p5-mst-13.2.git] / ext / File / Glob / Glob.pm

package File::Glob;

use strict;
use Carp;
our($VERSION, @ISA, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS,
    $AUTOLOAD, $DEFAULT_FLAGS);

require Exporter;
use XSLoader ();
require AutoLoader;

@ISA = qw(Exporter AutoLoader);

# NOTE: The glob() export is only here for compatibility with 5.6.0.
# csh_glob() should not be used directly, unless you know what you're doing.

@EXPORT_OK   = qw(
    csh_glob
    bsd_glob
    glob
    GLOB_ABEND
    GLOB_ALTDIRFUNC
    GLOB_BRACE
    GLOB_CSH
    GLOB_ERR
    GLOB_ERROR
    GLOB_MARK
    GLOB_NOCASE
    GLOB_NOCHECK
    GLOB_NOMAGIC
    GLOB_NOSORT
    GLOB_NOSPACE
    GLOB_QUOTE
    GLOB_TILDE
);

%EXPORT_TAGS = (
    'glob' => [ qw(
        GLOB_ABEND
        GLOB_ALTDIRFUNC
        GLOB_BRACE
        GLOB_CSH
        GLOB_ERR
        GLOB_ERROR
        GLOB_MARK
        GLOB_NOCASE
        GLOB_NOCHECK
        GLOB_NOMAGIC
        GLOB_NOSORT
        GLOB_NOSPACE
        GLOB_QUOTE
        GLOB_TILDE
        glob
        bsd_glob
    ) ],
);

$VERSION = '0.991';

sub import {
    my $i = 1;
    while ($i < @_) {
	if ($_[$i] =~ /^:(case|nocase|globally)$/) {
	    splice(@_, $i, 1);
	    $DEFAULT_FLAGS &= ~GLOB_NOCASE() if $1 eq 'case';
	    $DEFAULT_FLAGS |= GLOB_NOCASE() if $1 eq 'nocase';
	    if ($1 eq 'globally') {
		no warnings;
		*CORE::GLOBAL::glob = \&File::Glob::csh_glob;
	    }
	    next;
	}
	++$i;
    }
    goto &Exporter::import;
}

sub AUTOLOAD {
    # This AUTOLOAD is used to 'autoload' constants from the constant()
    # XS function.  If a constant is not found then control is passed
    # to the AUTOLOAD in AutoLoader.

    my $constname;
    ($constname = $AUTOLOAD) =~ s/.*:://;
    my $val = constant($constname, @_ ? $_[0] : 0);
    if ($! != 0) {
	if ($! =~ /Invalid/) {
	    $AutoLoader::AUTOLOAD = $AUTOLOAD;
	    goto &AutoLoader::AUTOLOAD;
	}
	else {
		croak "Your vendor has not defined File::Glob macro $constname";
	}
    }
    eval "sub $AUTOLOAD { $val }";
    goto &$AUTOLOAD;
}

XSLoader::load 'File::Glob', $VERSION;

# Preloaded methods go here.

sub GLOB_ERROR {
    return constant('GLOB_ERROR', 0);
}

sub GLOB_CSH () { GLOB_BRACE() | GLOB_NOMAGIC() | GLOB_QUOTE() | GLOB_TILDE() }

$DEFAULT_FLAGS = GLOB_CSH();
if ($^O =~ /^(?:MSWin32|VMS|os2|dos|riscos|MacOS)$/) {
    $DEFAULT_FLAGS |= GLOB_NOCASE();
}

# Autoload methods go after =cut, and are processed by the autosplit program.

sub bsd_glob {
    my ($pat,$flags) = @_;
    $flags = $DEFAULT_FLAGS if @_ < 2;
    return doglob($pat,$flags);
}

# File::Glob::glob() is deprecated because its prototype is different from
# CORE::glob() (use bsd_glob() instead)
sub glob {
    goto &bsd_glob;
}

## borrowed heavily from gsar's File::DosGlob
my %iter;
my %entries;

sub csh_glob {
    my $pat = shift;
    my $cxix = shift;
    my @pat;

    # glob without args defaults to $_
    $pat = $_ unless defined $pat;

    # extract patterns
    $pat =~ s/^\s+//;	# Protect against empty elements in
    $pat =~ s/\s+$//;	# things like < *.c> and <*.c >.
			# These alone shouldn't trigger ParseWords.
    if ($pat =~ /\s/) {
        # XXX this is needed for compatibility with the csh
	# implementation in Perl.  Need to support a flag
	# to disable this behavior.
	require Text::ParseWords;
	@pat = Text::ParseWords::parse_line('\s+',0,$pat);
    }

    # assume global context if not provided one
    $cxix = '_G_' unless defined $cxix;
    $iter{$cxix} = 0 unless exists $iter{$cxix};

    # if we're just beginning, do it all first
    if ($iter{$cxix} == 0) {
	if (@pat) {
	    $entries{$cxix} = [ map { doglob($_, $DEFAULT_FLAGS) } @pat ];
	}
	else {
	    $entries{$cxix} = [ doglob($pat, $DEFAULT_FLAGS) ];
	}
    }

    # chuck it all out, quick or slow
    if (wantarray) {
        delete $iter{$cxix};
        return @{delete $entries{$cxix}};
    }
    else {
        if ($iter{$cxix} = scalar @{$entries{$cxix}}) {
            return shift @{$entries{$cxix}};
        }
        else {
            # return undef for EOL
            delete $iter{$cxix};
            delete $entries{$cxix};
            return undef;
        }
    }
}

1;
__END__

=head1 NAME

File::Glob - Perl extension for BSD glob routine

=head1 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}>

=head1 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 C<pattern> argument, and an optional
C<flags> argument, and returns a list of filenames matching the
pattern, with interpretation of the pattern modified by the C<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:

=over 4

=item C<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.

=item C<GLOB_MARK>

Each pathname that is a directory that matches the pattern has a slash
appended.

=item C<GLOB_NOCASE>

By default, file names are assumed to be case sensitive; this flag
makes bsd_glob() treat case differences as not significant.

=item C<GLOB_NOCHECK>

If the pattern does not match any pathname, then bsd_glob() returns a list
consisting of only the pattern.  If C<GLOB_QUOTE> is set, its effect
is present in the pattern returned.

=item C<GLOB_NOSORT>

By default, the pathnames are sorted in ascending ASCII order; this
flag prevents that sorting (speeding up bsd_glob()).

=back

The FreeBSD extensions to the POSIX standard are the following flags:

=over 4

=item C<GLOB_BRACE>

Pre-process the string to expand C<{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).

=item C<GLOB_NOMAGIC>

Same as C<GLOB_NOCHECK> but it only returns the pattern if it does not
contain any of the special characters "*", "?" or "[".  C<NOMAGIC> is
provided to simplify implementing the historic csh(1) globbing
behaviour and should probably not be used anywhere else.

=item C<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).

=item C<GLOB_TILDE>

Expand patterns that start with '~' to user name home directories.

=item C<GLOB_CSH>

For convenience, C<GLOB_CSH> is a synonym for
C<GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE>.

=back

The POSIX provided C<GLOB_APPEND>, C<GLOB_DOOFFS>, and the FreeBSD
extensions C<GLOB_ALTDIRFUNC>, and C<GLOB_MAGCHAR> flags have not been
implemented in the Perl version because they involve more complex
interaction with the underlying C structures.

=head1 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 C<$!> will be
set.  &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred,
or one of the following values otherwise:

=over 4

=item C<GLOB_NOSPACE>

An attempt to allocate memory failed.

=item C<GLOB_ABEND>

The glob was stopped because an error was encountered.

=back

In the case where bsd_glob() has found some matching paths, but is
interrupted by an error, it will return a list of filenames B<and>
set &File::Glob::ERROR.

Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour
by not considering C<ENOENT> and C<ENOTDIR> as errors - bsd_glob() will
continue processing despite those errors, unless the C<GLOB_ERR> flag is
set.

Be aware that all filenames returned from File::Glob are tainted.

=head1 NOTES

=over 4

=item *

If you want to use multiple patterns, e.g. C<bsd_glob "a* b*">, you should
probably throw them in a set as in C<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.

=item *

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.

=item *

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.

=back

=head1 AUTHOR

The Perl interface was written by Nathan Torkington E<lt>gnat@frii.comE<gt>,
and is released under the artistic license.  Further modifications were
made by Greg Bacon E<lt>gbacon@cs.uah.eduE<gt> and Gurusamy Sarathy
E<lt>gsar@activestate.comE<gt>.  The C glob code has the
following copyright:

    Copyright (c) 1989, 1993 The Regents of the University of California.
    All rights reserved.

    This code is derived from software contributed to Berkeley by
    Guido van Rossum.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    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
    SUCH DAMAGE.

=cut
Commit	Line	Data
72b16652	1	package File::Glob;
	2
	3	use strict;
	4	use Carp;
17f410f9	5	our($VERSION, @ISA, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS,
17f410f9	6	$AUTOLOAD, $DEFAULT_FLAGS);
72b16652	7
72b16652	8	require Exporter;
9426adcd	9	use XSLoader ();
72b16652	10	require AutoLoader;
72b16652	11
9426adcd	12	@ISA = qw(Exporter AutoLoader);
72b16652	13
00c80938	14	# NOTE: The glob() export is only here for compatibility with 5.6.0.
	15	# csh_glob() should not be used directly, unless you know what you're doing.
	16
72b16652	17	@EXPORT_OK = qw(
72b16652	18	csh_glob
00c80938	19	bsd_glob
72b16652	20	glob
	21	GLOB_ABEND
	22	GLOB_ALTDIRFUNC
	23	GLOB_BRACE
220398a0	24	GLOB_CSH
72b16652	25	GLOB_ERR
	26	GLOB_ERROR
	27	GLOB_MARK
220398a0	28	GLOB_NOCASE
72b16652	29	GLOB_NOCHECK
	30	GLOB_NOMAGIC
	31	GLOB_NOSORT
	32	GLOB_NOSPACE
	33	GLOB_QUOTE
	34	GLOB_TILDE
	35	);
	36
72b16652	37	%EXPORT_TAGS = (
	38	'glob' => [ qw(
	39	GLOB_ABEND
	40	GLOB_ALTDIRFUNC
	41	GLOB_BRACE
220398a0	42	GLOB_CSH
72b16652	43	GLOB_ERR
	44	GLOB_ERROR
	45	GLOB_MARK
220398a0	46	GLOB_NOCASE
72b16652	47	GLOB_NOCHECK
	48	GLOB_NOMAGIC
	49	GLOB_NOSORT
	50	GLOB_NOSPACE
	51	GLOB_QUOTE
	52	GLOB_TILDE
	53	glob
00c80938	54	bsd_glob
72b16652	55	) ],
	56	);
	57
220398a0	58	$VERSION = '0.991';
	59
	60	sub import {
	61	my $i = 1;
	62	while ($i < @_) {
	63	if ($_[$i] =~ /^:(case\|nocase\|globally)$/) {
	64	splice(@_, $i, 1);
	65	$DEFAULT_FLAGS &= ~GLOB_NOCASE() if $1 eq 'case';
	66	$DEFAULT_FLAGS \|= GLOB_NOCASE() if $1 eq 'nocase';
	67	if ($1 eq 'globally') {
9f1b1f2d	68	no warnings;
220398a0	69	*CORE::GLOBAL::glob = \&File::Glob::csh_glob;
	70	}
	71	next;
	72	}
	73	++$i;
72b16652	74	}
220398a0	75	goto &Exporter::import;
72b16652	76	}
	77
	78	sub AUTOLOAD {
	79	# This AUTOLOAD is used to 'autoload' constants from the constant()
	80	# XS function. If a constant is not found then control is passed
	81	# to the AUTOLOAD in AutoLoader.
	82
	83	my $constname;
	84	($constname = $AUTOLOAD) =~ s/.*:://;
	85	my $val = constant($constname, @_ ? $_[0] : 0);
	86	if ($! != 0) {
	87	if ($! =~ /Invalid/) {
	88	$AutoLoader::AUTOLOAD = $AUTOLOAD;
	89	goto &AutoLoader::AUTOLOAD;
	90	}
	91	else {
	92	croak "Your vendor has not defined File::Glob macro $constname";
	93	}
	94	}
	95	eval "sub $AUTOLOAD { $val }";
	96	goto &$AUTOLOAD;
	97	}
	98
9426adcd	99	XSLoader::load 'File::Glob', $VERSION;
72b16652	100
	101	# Preloaded methods go here.
	102
	103	sub GLOB_ERROR {
	104	return constant('GLOB_ERROR', 0);
	105	}
	106
	107	sub GLOB_CSH () { GLOB_BRACE() \| GLOB_NOMAGIC() \| GLOB_QUOTE() \| GLOB_TILDE() }
	108
220398a0	109	$DEFAULT_FLAGS = GLOB_CSH();
	110	if ($^O =~ /^(?:MSWin32\|VMS\|os2\|dos\|riscos\|MacOS)$/) {
	111	$DEFAULT_FLAGS \|= GLOB_NOCASE();
	112	}
	113
72b16652	114	# Autoload methods go after =cut, and are processed by the autosplit program.
72b16652	115
00c80938	116	sub bsd_glob {
f0963acb	117	my ($pat,$flags) = @_;
	118	$flags = $DEFAULT_FLAGS if @_ < 2;
	119	return doglob($pat,$flags);
72b16652	120	}
72b16652	121
00c80938	122	# File::Glob::glob() is deprecated because its prototype is different from
	123	# CORE::glob() (use bsd_glob() instead)
	124	sub glob {
	125	goto &bsd_glob;
	126	}
	127
72b16652	128	## borrowed heavily from gsar's File::DosGlob
	129	my %iter;
	130	my %entries;
	131
	132	sub csh_glob {
	133	my $pat = shift;
	134	my $cxix = shift;
	135	my @pat;
	136
	137	# glob without args defaults to $_
	138	$pat = $_ unless defined $pat;
	139
	140	# extract patterns
be3174d2	141	$pat =~ s/^\s+//; # Protect against empty elements in
	142	$pat =~ s/\s+$//; # things like < .c> and <.c >.
	143	# These alone shouldn't trigger ParseWords.
72b16652	144	if ($pat =~ /\s/) {
	145	# XXX this is needed for compatibility with the csh
	146	# implementation in Perl. Need to support a flag
	147	# to disable this behavior.
	148	require Text::ParseWords;
	149	@pat = Text::ParseWords::parse_line('\s+',0,$pat);
	150	}
	151
	152	# assume global context if not provided one
	153	$cxix = '_G_' unless defined $cxix;
	154	$iter{$cxix} = 0 unless exists $iter{$cxix};
	155
	156	# if we're just beginning, do it all first
	157	if ($iter{$cxix} == 0) {
	158	if (@pat) {
220398a0	159	$entries{$cxix} = [ map { doglob($_, $DEFAULT_FLAGS) } @pat ];
72b16652	160	}
72b16652	161	else {
220398a0	162	$entries{$cxix} = [ doglob($pat, $DEFAULT_FLAGS) ];
72b16652	163	}
	164	}
	165
	166	# chuck it all out, quick or slow
	167	if (wantarray) {
	168	delete $iter{$cxix};
	169	return @{delete $entries{$cxix}};
	170	}
	171	else {
	172	if ($iter{$cxix} = scalar @{$entries{$cxix}}) {
	173	return shift @{$entries{$cxix}};
	174	}
	175	else {
	176	# return undef for EOL
	177	delete $iter{$cxix};
	178	delete $entries{$cxix};
	179	return undef;
	180	}
	181	}
	182	}
	183
	184	1;
	185	__END__
	186
	187	=head1 NAME
	188
	189	File::Glob - Perl extension for BSD glob routine
	190
	191	=head1 SYNOPSIS
	192
	193	use File::Glob ':glob';
00c80938	194	@list = bsd_glob('*.[ch]');
00c80938	195	$homedir = bsd_glob('~gnat', GLOB_TILDE \| GLOB_ERR);
72b16652	196	if (GLOB_ERROR) {
	197	# an error occurred reading $homedir
	198	}
	199
00c80938	200	## override the core glob (CORE::glob() does this automatically
11fe14b1	201	## by default anyway, since v5.6.0)
220398a0	202	use File::Glob ':globally';
	203	my @sources = <*.{c,h,y}>
	204
	205	## override the core glob, forcing case sensitivity
	206	use File::Glob qw(:globally :case);
	207	my @sources = <*.{c,h,y}>
	208
	209	## override the core glob forcing case insensitivity
	210	use File::Glob qw(:globally :nocase);
72b16652	211	my @sources = <*.{c,h,y}>
	212
	213	=head1 DESCRIPTION
	214
00c80938	215	File::Glob::bsd_glob() implements the FreeBSD glob(3) routine, which is
	216	a superset of the POSIX glob() (described in IEEE Std 1003.2 "POSIX.2").
	217	bsd_glob() takes a mandatory C<pattern> argument, and an optional
72b16652	218	C<flags> argument, and returns a list of filenames matching the
72b16652	219	pattern, with interpretation of the pattern modified by the C<flags>
00c80938	220	variable.
	221
	222	Since v5.6.0, Perl's CORE::glob() is implemented in terms of bsd_glob().
	223	Note that they don't share the same prototype--CORE::glob() only accepts
	224	a single argument. Due to historical reasons, CORE::glob() will also
	225	split its argument on whitespace, treating it as multiple patterns,
	226	whereas bsd_glob() considers them as one pattern.
	227
	228	The POSIX defined flags for bsd_glob() are:
72b16652	229
	230	=over 4
	231
	232	=item C<GLOB_ERR>
	233
00c80938	234	Force bsd_glob() to return an error when it encounters a directory it
00c80938	235	cannot open or read. Ordinarily bsd_glob() continues to find matches.
72b16652	236
	237	=item C<GLOB_MARK>
	238
	239	Each pathname that is a directory that matches the pattern has a slash
	240	appended.
	241
220398a0	242	=item C<GLOB_NOCASE>
	243
	244	By default, file names are assumed to be case sensitive; this flag
00c80938	245	makes bsd_glob() treat case differences as not significant.
220398a0	246
72b16652	247	=item C<GLOB_NOCHECK>
72b16652	248
00c80938	249	If the pattern does not match any pathname, then bsd_glob() returns a list
72b16652	250	consisting of only the pattern. If C<GLOB_QUOTE> is set, its effect
	251	is present in the pattern returned.
	252
	253	=item C<GLOB_NOSORT>
	254
	255	By default, the pathnames are sorted in ascending ASCII order; this
00c80938	256	flag prevents that sorting (speeding up bsd_glob()).
72b16652	257
	258	=back
	259
	260	The FreeBSD extensions to the POSIX standard are the following flags:
	261
	262	=over 4
	263
	264	=item C<GLOB_BRACE>
	265
a45bd81d	266	Pre-process the string to expand C<{pat,pat,...}> strings like csh(1).
72b16652	267	The pattern '{}' is left unexpanded for historical reasons (and csh(1)
	268	does the same thing to ease typing of find(1) patterns).
	269
	270	=item C<GLOB_NOMAGIC>
	271
	272	Same as C<GLOB_NOCHECK> but it only returns the pattern if it does not
	273	contain any of the special characters "*", "?" or "[". C<NOMAGIC> is
	274	provided to simplify implementing the historic csh(1) globbing
	275	behaviour and should probably not be used anywhere else.
	276
	277	=item C<GLOB_QUOTE>
	278
	279	Use the backslash ('\') character for quoting: every occurrence of a
	280	backslash followed by a character in the pattern is replaced by that
	281	character, avoiding any special interpretation of the character.
220398a0	282	(But see below for exceptions on DOSISH systems).
72b16652	283
	284	=item C<GLOB_TILDE>
	285
	286	Expand patterns that start with '~' to user name home directories.
	287
	288	=item C<GLOB_CSH>
	289
	290	For convenience, C<GLOB_CSH> is a synonym for
	291	C<GLOB_BRACE \| GLOB_NOMAGIC \| GLOB_QUOTE \| GLOB_TILDE>.
	292
	293	=back
	294
	295	The POSIX provided C<GLOB_APPEND>, C<GLOB_DOOFFS>, and the FreeBSD
	296	extensions C<GLOB_ALTDIRFUNC>, and C<GLOB_MAGCHAR> flags have not been
	297	implemented in the Perl version because they involve more complex
	298	interaction with the underlying C structures.
	299
	300	=head1 DIAGNOSTICS
	301
00c80938	302	bsd_glob() returns a list of matching paths, possibly zero length. If an
72b16652	303	error occurred, &File::Glob::GLOB_ERROR will be non-zero and C<$!> will be
	304	set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred,
	305	or one of the following values otherwise:
	306
	307	=over 4
	308
	309	=item C<GLOB_NOSPACE>
	310
	311	An attempt to allocate memory failed.
	312
	313	=item C<GLOB_ABEND>
	314
	315	The glob was stopped because an error was encountered.
	316
	317	=back
	318
00c80938	319	In the case where bsd_glob() has found some matching paths, but is
00c80938	320	interrupted by an error, it will return a list of filenames B<and>
72b16652	321	set &File::Glob::ERROR.
72b16652	322
00c80938	323	Note that bsd_glob() deviates from POSIX and FreeBSD glob(3) behaviour
00c80938	324	by not considering C<ENOENT> and C<ENOTDIR> as errors - bsd_glob() will
72b16652	325	continue processing despite those errors, unless the C<GLOB_ERR> flag is
	326	set.
	327
	328	Be aware that all filenames returned from File::Glob are tainted.
	329
	330	=head1 NOTES
	331
	332	=over 4
	333
	334	=item *
	335
00c80938	336	If you want to use multiple patterns, e.g. C<bsd_glob "a* b*">, you should
150b260b	337	probably throw them in a set as in C<bsd_glob "{a,b}">. This is because
	338	the argument to bsd_glob() isn't subjected to parsing by the C shell.
	339	Remember that you can use a backslash to escape things.
72b16652	340
	341	=item *
	342
220398a0	343	On DOSISH systems, backslash is a valid directory separator character.
	344	In this case, use of backslash as a quoting character (via GLOB_QUOTE)
	345	interferes with the use of backslash as a directory separator. The
	346	best (simplest, most portable) solution is to use forward slashes for
	347	directory separators, and backslashes for quoting. However, this does
	348	not match "normal practice" on these systems. As a concession to user
	349	expectation, therefore, backslashes (under GLOB_QUOTE) only quote the
	350	glob metacharacters '[', ']', '{', '}', '-', '~', and backslash itself.
	351	All other backslashes are passed through unchanged.
	352
	353	=item *
	354
72b16652	355	Win32 users should use the real slash. If you really want to use
	356	backslashes, consider using Sarathy's File::DosGlob, which comes with
	357	the standard Perl distribution.
	358
a45bd81d	359	=back
a45bd81d	360
72b16652	361	=head1 AUTHOR
72b16652	362
0e950d83	363	The Perl interface was written by Nathan Torkington E<lt>gnat@frii.comE<gt>,
72b16652	364	and is released under the artistic license. Further modifications were
	365	made by Greg Bacon E<lt>gbacon@cs.uah.eduE<gt> and Gurusamy Sarathy
	366	E<lt>gsar@activestate.comE<gt>. The C glob code has the
	367	following copyright:
	368
0e950d83	369	Copyright (c) 1989, 1993 The Regents of the University of California.
0e950d83	370	All rights reserved.
3cb6de81	371
0e950d83	372	This code is derived from software contributed to Berkeley by
	373	Guido van Rossum.
	374
	375	Redistribution and use in source and binary forms, with or without
	376	modification, are permitted provided that the following conditions
	377	are met:
	378
	379	1. Redistributions of source code must retain the above copyright
	380	notice, this list of conditions and the following disclaimer.
	381	2. Redistributions in binary form must reproduce the above copyright
	382	notice, this list of conditions and the following disclaimer in the
	383	documentation and/or other materials provided with the distribution.
	384	3. Neither the name of the University nor the names of its contributors
	385	may be used to endorse or promote products derived from this software
	386	without specific prior written permission.
	387
	388	THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	389	ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	390	IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	391	ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	392	FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	393	DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	394	OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	395	HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	396	LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	397	OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	398	SUCH DAMAGE.
72b16652	399
72b16652	400	=cut