summaryrefslogtreecommitdiffstats
path: root/upstream/mageia-cauldron/man3pm/File::Glob.3pm
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:43:11 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:43:11 +0000
commitfc22b3d6507c6745911b9dfcc68f1e665ae13dbc (patch)
treece1e3bce06471410239a6f41282e328770aa404a /upstream/mageia-cauldron/man3pm/File::Glob.3pm
parentInitial commit. (diff)
downloadmanpages-l10n-fc22b3d6507c6745911b9dfcc68f1e665ae13dbc.tar.xz
manpages-l10n-fc22b3d6507c6745911b9dfcc68f1e665ae13dbc.zip
Adding upstream version 4.22.0.upstream/4.22.0
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/File::Glob.3pm')
-rw-r--r--upstream/mageia-cauldron/man3pm/File::Glob.3pm357
1 files changed, 357 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/File::Glob.3pm b/upstream/mageia-cauldron/man3pm/File::Glob.3pm
new file mode 100644
index 00000000..fabb21f6
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/File::Glob.3pm
@@ -0,0 +1,357 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds C`
+. ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+. if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. if !\nF==2 \{\
+. nr % 0
+. nr F 2
+. \}
+. \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "File::Glob 3pm"
+.TH File::Glob 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+File::Glob \- Perl extension for BSD glob routine
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use File::Glob \*(Aq:bsd_glob\*(Aq;
+\&
+\& @list = bsd_glob(\*(Aq*.[ch]\*(Aq);
+\& $homedir = bsd_glob(\*(Aq~gnat\*(Aq, 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 \*(Aq:globally\*(Aq;
+\& 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 \*(Aq:globally\*(Aq;
+\& my @sources = <~gnat/*>;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+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.
+.PP
+\&\fBFile::Glob::bsd_glob()\fR implements the FreeBSD \fBglob\fR\|(3) routine, which is
+a superset of the POSIX \fBglob()\fR (described in IEEE Std 1003.2 "POSIX.2").
+\&\fBbsd_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
+variable.
+.PP
+Since v5.6.0, Perl's \fBCORE::glob()\fR is implemented in terms of \fBbsd_glob()\fR.
+Note that they don't share the same prototype\-\-\fBCORE::glob()\fR only accepts
+a single argument. Due to historical reasons, \fBCORE::glob()\fR will also
+split its argument on whitespace, treating it as multiple patterns,
+whereas \fBbsd_glob()\fR considers them as one pattern. But see \f(CW\*(C`:bsd_glob\*(C'\fR
+under "EXPORTS", below.
+.SS "META CHARACTERS"
+.IX Subsection "META CHARACTERS"
+.Vb 6
+\& \e Quote the next metacharacter
+\& [] Character class
+\& {} Multiple pattern
+\& * Match any string of characters
+\& ? Match any single character
+\& ~ User name home directory
+.Ve
+.PP
+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.
+.SS EXPORTS
+.IX Subsection "EXPORTS"
+See also the "POSIX FLAGS" below, which can be exported individually.
+.PP
+\fR\f(CI\*(C`:bsd_glob\*(C'\fR\fI\fR
+.IX Subsection ":bsd_glob"
+.PP
+The \f(CW\*(C`:bsd_glob\*(C'\fR export tag exports \fBbsd_glob()\fR and the constants listed
+below. It also overrides \fBglob()\fR in the calling package with one that
+behaves like \fBbsd_glob()\fR 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.
+.PP
+\fR\f(CI\*(C`:glob\*(C'\fR\fI\fR
+.IX Subsection ":glob"
+.PP
+The \f(CW\*(C`:glob\*(C'\fR tag, now discouraged, is the old version of \f(CW\*(C`:bsd_glob\*(C'\fR. It
+exports the same constants and functions, but its \fBglob()\fR override does not
+support iteration; it returns the last file name in scalar context. That
+means this will loop forever:
+.PP
+.Vb 4
+\& use File::Glob \*(Aq:glob\*(Aq;
+\& while (my $file = <* copy.txt>) {
+\& ...
+\& }
+.Ve
+.PP
+\fR\f(CI\*(C`bsd_glob\*(C'\fR\fI\fR
+.IX Subsection "bsd_glob"
+.PP
+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".
+.PP
+Remember that to use the named constants for flags you must import
+them, for example with \f(CW\*(C`:bsd_glob\*(C'\fR described above. If not imported,
+and \f(CW\*(C`use strict\*(C'\fR is not in effect, then the constants will be
+treated as bareword strings, which won't do what you what.
+.PP
+\fR\f(CI\*(C`:nocase\*(C'\fR\fI and \fR\f(CI\*(C`:case\*(C'\fR\fI\fR
+.IX Subsection ":nocase and :case"
+.PP
+These two export tags globally modify the default flags that \fBbsd_glob()\fR
+and, except on VMS, Perl's built-in \f(CW\*(C`glob\*(C'\fR operator use. \f(CW\*(C`GLOB_NOCASE\*(C'\fR
+is turned on or off, respectively.
+.PP
+\fR\f(CI\*(C`csh_glob\*(C'\fR\fI\fR
+.IX Subsection "csh_glob"
+.PP
+The \fBcsh_glob()\fR 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 \fBbsd_glob()\fR. Perl's own \fBglob()\fR function
+uses this internally.
+.SS "POSIX FLAGS"
+.IX Subsection "POSIX FLAGS"
+If no flags argument is give then \f(CW\*(C`GLOB_CSH\*(C'\fR is set, and on VMS and
+Windows systems, \f(CW\*(C`GLOB_NOCASE\*(C'\fR too. Otherwise the flags to use are
+determined solely by the flags argument. The POSIX defined flags are:
+.ie n .IP """GLOB_ERR""" 4
+.el .IP \f(CWGLOB_ERR\fR 4
+.IX Item "GLOB_ERR"
+Force \fBbsd_glob()\fR to return an error when it encounters a directory it
+cannot open or read. Ordinarily \fBbsd_glob()\fR continues to find matches.
+.ie n .IP """GLOB_LIMIT""" 4
+.el .IP \f(CWGLOB_LIMIT\fR 4
+.IX Item "GLOB_LIMIT"
+Make \fBbsd_glob()\fR return an error (GLOB_NOSPACE) 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, \fBbsd_glob()\fR uses
+\&\f(CWsysconf(_SC_ARG_MAX)\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
+extension.
+.ie n .IP """GLOB_MARK""" 4
+.el .IP \f(CWGLOB_MARK\fR 4
+.IX Item "GLOB_MARK"
+Each pathname that is a directory that matches the pattern has a slash
+appended.
+.ie n .IP """GLOB_NOCASE""" 4
+.el .IP \f(CWGLOB_NOCASE\fR 4
+.IX Item "GLOB_NOCASE"
+By default, file names are assumed to be case sensitive; this flag
+makes \fBbsd_glob()\fR treat case differences as not significant.
+.ie n .IP """GLOB_NOCHECK""" 4
+.el .IP \f(CWGLOB_NOCHECK\fR 4
+.IX Item "GLOB_NOCHECK"
+If the pattern does not match any pathname, then \fBbsd_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
+.IX Item "GLOB_NOSORT"
+By default, the pathnames are sorted in ascending ASCII order; this
+flag prevents that sorting (speeding up \fBbsd_glob()\fR).
+.PP
+The FreeBSD extensions to the POSIX standard are the following flags:
+.ie n .IP """GLOB_BRACE""" 4
+.el .IP \f(CWGLOB_BRACE\fR 4
+.IX Item "GLOB_BRACE"
+Pre-process the string to expand \f(CW\*(C`{pat,pat,...}\*(C'\fR strings like \fBcsh\fR\|(1).
+The pattern '{}' is left unexpanded for historical reasons (and \fBcsh\fR\|(1)
+does the same thing to ease typing of \fBfind\fR\|(1) patterns).
+.ie n .IP """GLOB_NOMAGIC""" 4
+.el .IP \f(CWGLOB_NOMAGIC\fR 4
+.IX Item "GLOB_NOMAGIC"
+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 "*", "?" or "[". \f(CW\*(C`NOMAGIC\*(C'\fR is
+provided to simplify implementing the historic \fBcsh\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
+.IX Item "GLOB_QUOTE"
+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 DOSISH systems).
+.ie n .IP """GLOB_TILDE""" 4
+.el .IP \f(CWGLOB_TILDE\fR 4
+.IX Item "GLOB_TILDE"
+Expand patterns that start with '~' to user name home directories.
+.ie n .IP """GLOB_CSH""" 4
+.el .IP \f(CWGLOB_CSH\fR 4
+.IX Item "GLOB_CSH"
+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.
+.PP
+The POSIX 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.
+.PP
+The following flag has been added in the Perl implementation for
+csh compatibility:
+.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 ASCII order.
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+\&\fBbsd_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
+.IX Item "GLOB_NOSPACE"
+An attempt to allocate memory failed.
+.ie n .IP """GLOB_ABEND""" 4
+.el .IP \f(CWGLOB_ABEND\fR 4
+.IX Item "GLOB_ABEND"
+The glob was stopped because an error was encountered.
+.PP
+In the case where \fBbsd_glob()\fR has found some matching paths, but is
+interrupted by an error, it will return a list of filenames \fBand\fR
+set &File::Glob::ERROR.
+.PP
+Note that \fBbsd_glob()\fR deviates from POSIX and FreeBSD \fBglob\fR\|(3) behaviour
+by not considering \f(CW\*(C`ENOENT\*(C'\fR and \f(CW\*(C`ENOTDIR\*(C'\fR as errors \- \fBbsd_glob()\fR will
+continue processing despite those errors, unless the \f(CW\*(C`GLOB_ERR\*(C'\fR flag is
+set.
+.PP
+Be aware that all filenames returned from File::Glob are tainted.
+.SH NOTES
+.IX Header "NOTES"
+.IP \(bu 4
+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 \fBbsd_glob()\fR isn't subjected to parsing by the C shell.
+Remember that you can use a backslash to escape things.
+.IP \(bu 4
+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.
+.IP \(bu 4
+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.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+"glob" in perlfunc, \fBglob\fR\|(3)
+.SH AUTHOR
+.IX Header "AUTHOR"
+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
+following copyright:
+.PP
+Copyright (c) 1989, 1993 The Regents of the University of California.
+All rights reserved.
+.PP
+This code is derived from software contributed to Berkeley by
+Guido van Rossum.
+.PP
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+.IP 1. 4
+Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+.IP 2. 4
+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.
+.IP 3. 4
+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.
+.PP
+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.