diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:43:11 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:43:11 +0000 |
commit | fc22b3d6507c6745911b9dfcc68f1e665ae13dbc (patch) | |
tree | ce1e3bce06471410239a6f41282e328770aa404a /upstream/mageia-cauldron/man3pm/File::Glob.3pm | |
parent | Initial commit. (diff) | |
download | manpages-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.3pm | 357 |
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. |