Debian Codegraph @

upstream/mageia-cauldron/man3pm/File::Glob.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "File::Glob 3pm"
61 .TH File::Glob 3pm 2024-05-07 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 File::Glob \- Perl extension for BSD glob routine
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use File::Glob \*(Aq:bsd_glob\*(Aq;
72 \&
73 \& @list = bsd_glob(\*(Aq*.[ch]\*(Aq);
74 \& $homedir = bsd_glob(\*(Aq~gnat\*(Aq, GLOB_TILDE | GLOB_ERR);
75 \&
76 \& if (GLOB_ERROR) {
77 \& # an error occurred reading $homedir
78 \& }
79 \&
80 \& ## override the core glob (CORE::glob() does this automatically
81 \& ## by default anyway, since v5.6.0)
82 \& use File::Glob \*(Aq:globally\*(Aq;
83 \& my @sources = <*.{c,h,y}>;
84 \&
85 \& ## override the core glob, forcing case sensitivity
86 \& use File::Glob qw(:globally :case);
87 \& my @sources = <*.{c,h,y}>;
88 \&
89 \& ## override the core glob forcing case insensitivity
90 \& use File::Glob qw(:globally :nocase);
91 \& my @sources = <*.{c,h,y}>;
92 \&
93 \& ## glob on all files in home directory
94 \& use File::Glob \*(Aq:globally\*(Aq;
95 \& my @sources = <~gnat/*>;
96 .Ve
97 .SH DESCRIPTION
98 .IX Header "DESCRIPTION"
99 The glob angle\-bracket operator \f(CW\*(C`<>\*(C'\fR is a pathname generator that
100 implements the rules for file name pattern matching used by Unix\-like shells
101 such as the Bourne shell or C shell.
102 .PP
103 \&\fBFile::Glob::bsd_glob()\fR implements the FreeBSD \fBglob\fR\|(3) routine, which is
104 a superset of the POSIX \fBglob()\fR (described in IEEE Std 1003.2 "POSIX.2").
105 \&\fBbsd_glob()\fR takes a mandatory \f(CW\*(C`pattern\*(C'\fR argument, and an optional
106 \&\f(CW\*(C`flags\*(C'\fR argument, and returns a list of filenames matching the
107 pattern, with interpretation of the pattern modified by the \f(CW\*(C`flags\*(C'\fR
108 variable.
109 .PP
110 Since v5.6.0, Perl\*(Aqs \fBCORE::glob()\fR is implemented in terms of \fBbsd_glob()\fR.
111 Note that they don\*(Aqt share the same prototype\-\-\fBCORE::glob()\fR only accepts
112 a single argument. Due to historical reasons, \fBCORE::glob()\fR will also
113 split its argument on whitespace, treating it as multiple patterns,
114 whereas \fBbsd_glob()\fR considers them as one pattern. But see \f(CW\*(C`:bsd_glob\*(C'\fR
115 under "EXPORTS", below.
116 .SS "META CHARACTERS"
117 .IX Subsection "META CHARACTERS"
118 .Vb 6
119 \& \e Quote the next metacharacter
120 \& [] Character class
121 \& {} Multiple pattern
122 \& * Match any string of characters
123 \& ? Match any single character
124 \& ~ User name home directory
125 .Ve
126 .PP
127 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
128 right order is preserved, with results of matches being sorted separately
129 at a low level to preserve this order. As a special case \f(CW\*(C`{\*(C'\fR, \f(CW\*(C`}\*(C'\fR, and
130 \&\f(CW\*(C`{}\*(C'\fR are passed undisturbed.
131 .SS EXPORTS
132 .IX Subsection "EXPORTS"
133 See also the "POSIX FLAGS" below, which can be exported individually.
134 .PP
135 \fR\f(CI\*(C`:bsd_glob\*(C'\fR\fI\fR
136 .IX Subsection ":bsd_glob"
137 .PP
138 The \f(CW\*(C`:bsd_glob\*(C'\fR export tag exports \fBbsd_glob()\fR and the constants listed
139 below. It also overrides \fBglob()\fR in the calling package with one that
140 behaves like \fBbsd_glob()\fR with regard to spaces (the space is treated as part
141 of a file name), but supports iteration in scalar context; i.e., it
142 preserves the core function\*(Aqs feature of returning the next item each time
143 it is called.
144 .PP
145 \fR\f(CI\*(C`:glob\*(C'\fR\fI\fR
146 .IX Subsection ":glob"
147 .PP
148 The \f(CW\*(C`:glob\*(C'\fR tag, now discouraged, is the old version of \f(CW\*(C`:bsd_glob\*(C'\fR. It
149 exports the same constants and functions, but its \fBglob()\fR override does not
150 support iteration; it returns the last file name in scalar context. That
151 means this will loop forever:
152 .PP
153 .Vb 4
154 \& use File::Glob \*(Aq:glob\*(Aq;
155 \& while (my $file = <* copy.txt>) {
156 \& ...
157 \& }
158 .Ve
159 .PP
160 \fR\f(CI\*(C`bsd_glob\*(C'\fR\fI\fR
161 .IX Subsection "bsd_glob"
162 .PP
163 This function, which is included in the two export tags listed above,
164 takes one or two arguments. The first is the glob pattern. The
165 second, if given, is a set of flags ORed together. The available
166 flags and the default set of flags are listed below under "POSIX FLAGS".
167 .PP
168 Remember that to use the named constants for flags you must import
169 them, for example with \f(CW\*(C`:bsd_glob\*(C'\fR described above. If not imported,
170 and \f(CW\*(C`use strict\*(C'\fR is not in effect, then the constants will be
171 treated as bareword strings, which won\*(Aqt do what you what.
172 .PP
173 \fR\f(CI\*(C`:nocase\*(C'\fR\fI and \fR\f(CI\*(C`:case\*(C'\fR\fI\fR
174 .IX Subsection ":nocase and :case"
175 .PP
176 These two export tags globally modify the default flags that \fBbsd_glob()\fR
177 and, except on VMS, Perl\*(Aqs built\-in \f(CW\*(C`glob\*(C'\fR operator use. \f(CW\*(C`GLOB_NOCASE\*(C'\fR
178 is turned on or off, respectively.
179 .PP
180 \fR\f(CI\*(C`csh_glob\*(C'\fR\fI\fR
181 .IX Subsection "csh_glob"
182 .PP
183 The \fBcsh_glob()\fR function can also be exported, but you should not use it
184 directly unless you really know what you are doing. It splits the pattern
185 into words and feeds each one to \fBbsd_glob()\fR. Perl\*(Aqs own \fBglob()\fR function
186 uses this internally.
187 .SS "POSIX FLAGS"
188 .IX Subsection "POSIX FLAGS"
189 If no flags argument is given then \f(CW\*(C`GLOB_CSH\*(C'\fR is set, and on VMS and
190 Windows systems, \f(CW\*(C`GLOB_NOCASE\*(C'\fR too. Otherwise the flags to use are
191 determined solely by the flags argument. The POSIX defined flags are:
192 .ie n .IP """GLOB_ERR""" 4
193 .el .IP \f(CWGLOB_ERR\fR 4
194 .IX Item "GLOB_ERR"
195 Force \fBbsd_glob()\fR to return an error when it encounters a directory it
196 cannot open or read. Ordinarily \fBbsd_glob()\fR continues to find matches.
197 .ie n .IP """GLOB_LIMIT""" 4
198 .el .IP \f(CWGLOB_LIMIT\fR 4
199 .IX Item "GLOB_LIMIT"
200 Make \fBbsd_glob()\fR return an error (GLOB_NOSPACE) when the pattern expands
201 to a size bigger than the system constant \f(CW\*(C`ARG_MAX\*(C'\fR (usually found in
202 limits.h). If your system does not define this constant, \fBbsd_glob()\fR uses
203 \&\f(CWsysconf(_SC_ARG_MAX)\fR or \f(CW\*(C`_POSIX_ARG_MAX\*(C'\fR where available (in that
204 order). You can inspect these values using the standard \f(CW\*(C`POSIX\*(C'\fR
205 extension.
206 .ie n .IP """GLOB_MARK""" 4
207 .el .IP \f(CWGLOB_MARK\fR 4
208 .IX Item "GLOB_MARK"
209 Each pathname that is a directory that matches the pattern has a slash
210 appended.
211 .ie n .IP """GLOB_NOCASE""" 4
212 .el .IP \f(CWGLOB_NOCASE\fR 4
213 .IX Item "GLOB_NOCASE"
214 By default, file names are assumed to be case sensitive; this flag
215 makes \fBbsd_glob()\fR treat case differences as not significant.
216 .ie n .IP """GLOB_NOCHECK""" 4
217 .el .IP \f(CWGLOB_NOCHECK\fR 4
218 .IX Item "GLOB_NOCHECK"
219 If the pattern does not match any pathname, then \fBbsd_glob()\fR returns a list
220 consisting of only the pattern. If \f(CW\*(C`GLOB_QUOTE\*(C'\fR is set, its effect
221 is present in the pattern returned.
222 .ie n .IP """GLOB_NOSORT""" 4
223 .el .IP \f(CWGLOB_NOSORT\fR 4
224 .IX Item "GLOB_NOSORT"
225 By default, the pathnames are sorted in ascending ASCII order; this
226 flag prevents that sorting (speeding up \fBbsd_glob()\fR).
227 .PP
228 The FreeBSD extensions to the POSIX standard are the following flags:
229 .ie n .IP """GLOB_BRACE""" 4
230 .el .IP \f(CWGLOB_BRACE\fR 4
231 .IX Item "GLOB_BRACE"
232 Pre\-process the string to expand \f(CW\*(C`{pat,pat,...}\*(C'\fR strings like \fBcsh\fR\|(1).
233 The pattern \*(Aq{}\*(Aq is left unexpanded for historical reasons (and \fBcsh\fR\|(1)
234 does the same thing to ease typing of \fBfind\fR\|(1) patterns).
235 .ie n .IP """GLOB_NOMAGIC""" 4
236 .el .IP \f(CWGLOB_NOMAGIC\fR 4
237 .IX Item "GLOB_NOMAGIC"
238 Same as \f(CW\*(C`GLOB_NOCHECK\*(C'\fR but it only returns the pattern if it does not
239 contain any of the special characters "*", "?" or "[". \f(CW\*(C`NOMAGIC\*(C'\fR is
240 provided to simplify implementing the historic \fBcsh\fR\|(1) globbing
241 behaviour and should probably not be used anywhere else.
242 .ie n .IP """GLOB_QUOTE""" 4
243 .el .IP \f(CWGLOB_QUOTE\fR 4
244 .IX Item "GLOB_QUOTE"
245 Use the backslash (\*(Aq\e\*(Aq) character for quoting: every occurrence of a
246 backslash followed by a character in the pattern is replaced by that
247 character, avoiding any special interpretation of the character.
248 (But see below for exceptions on DOSISH systems).
249 .ie n .IP """GLOB_TILDE""" 4
250 .el .IP \f(CWGLOB_TILDE\fR 4
251 .IX Item "GLOB_TILDE"
252 Expand patterns that start with \*(Aq~\*(Aq to user name home directories.
253 .ie n .IP """GLOB_CSH""" 4
254 .el .IP \f(CWGLOB_CSH\fR 4
255 .IX Item "GLOB_CSH"
256 For convenience, \f(CW\*(C`GLOB_CSH\*(C'\fR is a synonym for
257 \&\f(CW\*(C`GLOB_BRACE | GLOB_NOMAGIC | GLOB_QUOTE | GLOB_TILDE | GLOB_ALPHASORT\*(C'\fR.
258 .PP
259 The POSIX provided \f(CW\*(C`GLOB_APPEND\*(C'\fR, \f(CW\*(C`GLOB_DOOFFS\*(C'\fR, and the FreeBSD
260 extensions \f(CW\*(C`GLOB_ALTDIRFUNC\*(C'\fR, and \f(CW\*(C`GLOB_MAGCHAR\*(C'\fR flags have not been
261 implemented in the Perl version because they involve more complex
262 interaction with the underlying C structures.
263 .PP
264 The following flag has been added in the Perl implementation for
265 csh compatibility:
266 .ie n .IP """GLOB_ALPHASORT""" 4
267 .el .IP \f(CWGLOB_ALPHASORT\fR 4
268 .IX Item "GLOB_ALPHASORT"
269 If \f(CW\*(C`GLOB_NOSORT\*(C'\fR is not in effect, sort filenames is alphabetical
270 order (case does not matter) rather than in ASCII order.
271 .SH DIAGNOSTICS
272 .IX Header "DIAGNOSTICS"
273 \&\fBbsd_glob()\fR returns a list of matching paths, possibly zero length. If an
274 error occurred, &File::Glob::GLOB_ERROR will be non\-zero and \f(CW$!\fR will be
275 set. &File::Glob::GLOB_ERROR is guaranteed to be zero if no error occurred,
276 or one of the following values otherwise:
277 .ie n .IP """GLOB_NOSPACE""" 4
278 .el .IP \f(CWGLOB_NOSPACE\fR 4
279 .IX Item "GLOB_NOSPACE"
280 An attempt to allocate memory failed.
281 .ie n .IP """GLOB_ABEND""" 4
282 .el .IP \f(CWGLOB_ABEND\fR 4
283 .IX Item "GLOB_ABEND"
284 The glob was stopped because an error was encountered.
285 .PP
286 In the case where \fBbsd_glob()\fR has found some matching paths, but is
287 interrupted by an error, it will return a list of filenames \fBand\fR
288 set &File::Glob::ERROR.
289 .PP
290 Note that \fBbsd_glob()\fR deviates from POSIX and FreeBSD \fBglob\fR\|(3) behaviour
291 by not considering \f(CW\*(C`ENOENT\*(C'\fR and \f(CW\*(C`ENOTDIR\*(C'\fR as errors \- \fBbsd_glob()\fR will
292 continue processing despite those errors, unless the \f(CW\*(C`GLOB_ERR\*(C'\fR flag is
293 set.
294 .PP
295 Be aware that all filenames returned from File::Glob are tainted.
296 .SH NOTES
297 .IX Header "NOTES"
298 .IP \(bu 4
299 If you want to use multiple patterns, e.g. \f(CW\*(C`bsd_glob("a* b*")\*(C'\fR, you should
300 probably throw them in a set as in \f(CW\*(C`bsd_glob("{a*,b*}")\*(C'\fR. This is because
301 the argument to \fBbsd_glob()\fR isn\*(Aqt subjected to parsing by the C shell.
302 Remember that you can use a backslash to escape things.
303 .IP \(bu 4
304 On DOSISH systems, backslash is a valid directory separator character.
305 In this case, use of backslash as a quoting character (via GLOB_QUOTE)
306 interferes with the use of backslash as a directory separator. The
307 best (simplest, most portable) solution is to use forward slashes for
308 directory separators, and backslashes for quoting. However, this does
309 not match "normal practice" on these systems. As a concession to user
310 expectation, therefore, backslashes (under GLOB_QUOTE) only quote the
311 glob metacharacters \*(Aq[\*(Aq, \*(Aq]\*(Aq, \*(Aq{\*(Aq, \*(Aq}\*(Aq, \*(Aq\-\*(Aq, \*(Aq~\*(Aq, and backslash itself.
312 All other backslashes are passed through unchanged.
313 .IP \(bu 4
314 Win32 users should use the real slash. If you really want to use
315 backslashes, consider using Sarathy\*(Aqs File::DosGlob, which comes with
316 the standard Perl distribution.
317 .SH "SEE ALSO"
318 .IX Header "SEE ALSO"
319 "glob" in perlfunc, \fBglob\fR\|(3)
320 .SH AUTHOR
321 .IX Header "AUTHOR"
322 The Perl interface was written by Nathan Torkington <[email protected]>,
323 and is released under the artistic license. Further modifications were
324 made by Greg Bacon <[email protected]>, Gurusamy Sarathy
325 <[email protected]>, and Thomas Wegner
326 <[email protected]>. The C glob code has the
327 following copyright:
328 .PP
329 Copyright (c) 1989, 1993 The Regents of the University of California.
330 All rights reserved.
331 .PP
332 This code is derived from software contributed to Berkeley by
333 Guido van Rossum.
334 .PP
335 Redistribution and use in source and binary forms, with or without
336 modification, are permitted provided that the following conditions
337 are met:
338 .IP 1. 4
339 Redistributions of source code must retain the above copyright
340 notice, this list of conditions and the following disclaimer.
341 .IP 2. 4
342 Redistributions in binary form must reproduce the above copyright
343 notice, this list of conditions and the following disclaimer in the
344 documentation and/or other materials provided with the distribution.
345 .IP 3. 4
346 Neither the name of the University nor the names of its contributors
347 may be used to endorse or promote products derived from this software
348 without specific prior written permission.
349 .PP
350 THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND
351 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
352 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
353 ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
354 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
355 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
356 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
357 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
358 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
359 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
360 SUCH DAMAGE.