Debian Codegraph @

upstream/debian-unstable/man3/File::Glob.3perl

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