Debian Codegraph @

upstream/opensuse-tumbleweed/man3/File::Find.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::Find 3pm"
61 .TH File::Find 3pm 2026-03-09 "perl v5.42.1" "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::Find \- Traverse a directory tree.
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 3
71 \& use File::Find;
72 \& find(\e&wanted, @directories_to_search);
73 \& sub wanted { ... }
74 \&
75 \& use File::Find;
76 \& finddepth(\e&wanted, @directories_to_search);
77 \& sub wanted { ... }
78 \&
79 \& use File::Find;
80 \& find({ wanted => \e&process, follow => 1 }, \*(Aq.\*(Aq);
81 .Ve
82 .SH DESCRIPTION
83 .IX Header "DESCRIPTION"
84 These are functions for searching through directory trees doing work
85 on each file found similar to the Unix \fBfind\fR\|(1) command. \f(CW\*(C`File::Find\*(C'\fR
86 exports two functions, \f(CW\*(C`find\*(C'\fR and \f(CW\*(C`finddepth\*(C'\fR. They work similarly
87 but have subtle differences.
88 .IP \fBfind\fR 4
89 .IX Item "find"
90 .Vb 2
91 \& find(\e&wanted, @directories);
92 \& find(\e%options, @directories);
93 .Ve
94 .Sp
95 \&\f(CWfind()\fR does a depth\-first search over the given \f(CW@directories\fR in
96 the order they are given. For each file or directory found, it calls
97 the \f(CW&wanted\fR subroutine. (See below for details on how to use the
98 \&\f(CW&wanted\fR function). Additionally, for each directory found, it will
99 \&\f(CWchdir()\fR into that directory and continue the search, invoking the
100 \&\f(CW&wanted\fR function on each file or subdirectory in the directory.
101 .IP \fBfinddepth\fR 4
102 .IX Item "finddepth"
103 .Vb 2
104 \& finddepth(\e&wanted, @directories);
105 \& finddepth(\e%options, @directories);
106 .Ve
107 .Sp
108 \&\f(CWfinddepth()\fR works just like \f(CWfind()\fR except that it invokes the
109 \&\f(CW&wanted\fR function for a directory \fIafter\fR invoking it for the
110 directory\*(Aqs contents. It does a postorder traversal instead of a
111 preorder traversal, working from the bottom of the directory tree up
112 where \f(CWfind()\fR works from the top of the tree down.
113 .PP
114 Despite the name of the \f(CWfinddepth()\fR function, both \f(CWfind()\fR and
115 \&\f(CWfinddepth()\fR perform a depth\-first search of the directory hierarchy.
116 .ie n .SS %options
117 .el .SS \f(CW%options\fP
118 .IX Subsection "%options"
119 The first argument to \f(CWfind()\fR is either a code reference to your
120 \&\f(CW&wanted\fR function, or a hash reference describing the operations
121 to be performed for each file. The
122 code reference is described in "The wanted function" below.
123 .PP
124 Here are the possible \fBkeys\fR for the hash:
125 .ie n .IP """wanted""" 4
126 .el .IP \f(CWwanted\fR 4
127 .IX Item "wanted"
128 The value should be a code reference. This code reference is
129 described in "The wanted function" below. The \f(CW&wanted\fR subroutine is
130 mandatory.
131 .ie n .IP """bydepth""" 4
132 .el .IP \f(CWbydepth\fR 4
133 .IX Item "bydepth"
134 Reports the name of a directory only AFTER all its entries
135 have been reported. Entry point \f(CWfinddepth()\fR is a shortcut for
136 specifying \f(CW\*(C`{ bydepth => 1 }\*(C'\fR in the first argument of \f(CWfind()\fR.
137 .ie n .IP """preprocess""" 4
138 .el .IP \f(CWpreprocess\fR 4
139 .IX Item "preprocess"
140 The value should be a code reference. This code reference is used to
141 preprocess the current directory. The name of the currently processed
142 directory is in \f(CW$File::Find::dir\fR. Your preprocessing function is
143 called after \f(CWreaddir()\fR, but before the loop that calls the \f(CWwanted()\fR
144 function. It is called with a list of strings (actually file/directory
145 names) and is expected to return a list of strings. The code can be
146 used to sort the file/directory names alphabetically, numerically,
147 or to filter out directory entries based on their name alone. When
148 \&\f(CW\*(C`follow\*(C'\fR or \f(CW\*(C`follow_fast\*(C'\fR are in effect, \f(CW\*(C`preprocess\*(C'\fR is a no\-op.
149 .ie n .IP """postprocess""" 4
150 .el .IP \f(CWpostprocess\fR 4
151 .IX Item "postprocess"
152 The value should be a code reference. It is invoked just before leaving
153 the currently processed directory. It is called in void context with no
154 arguments. The name of the current directory is in \f(CW$File::Find::dir\fR. This
155 hook is handy for summarizing a directory, such as calculating its disk
156 usage. When \f(CW\*(C`follow\*(C'\fR or \f(CW\*(C`follow_fast\*(C'\fR are in effect, \f(CW\*(C`postprocess\*(C'\fR is a
157 no\-op.
158 .ie n .IP """follow""" 4
159 .el .IP \f(CWfollow\fR 4
160 .IX Item "follow"
161 Causes symbolic links to be followed. Since directory trees with symbolic
162 links (followed) may contain files more than once and may even have
163 cycles, a hash has to be built up with an entry for each file.
164 This might be expensive both in space and time for a large
165 directory tree. See "follow_fast" and "follow_skip" below.
166 If either \f(CW\*(C`follow\*(C'\fR or \f(CW\*(C`follow_fast\*(C'\fR is in effect:
167 .RS 4
168 .IP \(bu 4
169 It is guaranteed that an \f(CW\*(C`lstat\*(C'\fR has been called before the user\*(Aqs
170 \&\f(CWwanted()\fR function is called. This enables fast file checks involving \f(CW\*(C`_\*(C'\fR.
171 Note that this guarantee no longer holds if \f(CW\*(C`follow\*(C'\fR or \f(CW\*(C`follow_fast\*(C'\fR
172 are not set.
173 .IP \(bu 4
174 There is a variable \f(CW$File::Find::fullname\fR which holds the absolute
175 pathname of the file with all symbolic links resolved. If the link is
176 a dangling symbolic link, then fullname will be set to \f(CW\*(C`undef\*(C'\fR.
177 .RE
178 .RS 4
179 .RE
180 .ie n .IP """follow_fast""" 4
181 .el .IP \f(CWfollow_fast\fR 4
182 .IX Item "follow_fast"
183 This is similar to \f(CW\*(C`follow\*(C'\fR except that it may report some files more
184 than once. It does detect cycles, however. Since only symbolic links
185 have to be hashed, this is much cheaper both in space and time. If
186 processing a file more than once (by the user\*(Aqs \f(CWwanted()\fR function)
187 is worse than just taking time, the option \f(CW\*(C`follow\*(C'\fR should be used.
188 .ie n .IP """follow_skip""" 4
189 .el .IP \f(CWfollow_skip\fR 4
190 .IX Item "follow_skip"
191 \&\f(CW\*(C`follow_skip==1\*(C'\fR, which is the default, causes all files which are
192 neither directories nor symbolic links to be ignored if they are about
193 to be processed a second time. If a directory or a symbolic link
194 are about to be processed a second time, \f(CW\*(C`File::Find\*(C'\fR dies.
195 .Sp
196 \&\f(CW\*(C`follow_skip==0\*(C'\fR causes \f(CW\*(C`File::Find\*(C'\fR to die if any file is about to be
197 processed a second time.
198 .Sp
199 \&\f(CW\*(C`follow_skip==2\*(C'\fR causes \f(CW\*(C`File::Find\*(C'\fR to ignore any duplicate files and
200 directories but to proceed normally otherwise.
201 .ie n .IP """dangling_symlinks""" 4
202 .el .IP \f(CWdangling_symlinks\fR 4
203 .IX Item "dangling_symlinks"
204 Specifies what to do with symbolic links whose target doesn\*(Aqt exist.
205 If true and a code reference, will be called with the symbolic link
206 name and the directory it lives in as arguments. Otherwise, if true
207 and warnings are on, a warning of the form \f(CW"symbolic_link_name is a dangling
208 symbolic link\en"\fR will be issued. If false, the dangling symbolic link
209 will be silently ignored.
210 .ie n .IP """no_chdir""" 4
211 .el .IP \f(CWno_chdir\fR 4
212 .IX Item "no_chdir"
213 Does not \f(CWchdir()\fR to each directory as it recurses. The \f(CWwanted()\fR
214 function will need to be aware of this, of course. In this case,
215 \&\f(CW$_\fR will be the same as \f(CW$File::Find::name\fR.
216 .ie n .IP """untaint""" 4
217 .el .IP \f(CWuntaint\fR 4
218 .IX Item "untaint"
219 If find is used in taint\-mode (\f(CW\*(C`\-T\*(C'\fR command line
220 switch or \f(CW\*(C`if EUID != UID\*(C'\fR or \f(CW\*(C`if EGID != GID\*(C'\fR), then internally
221 directory names have to be untainted before they can be \f(CW\*(C`chdir\*(C'\fR\*(Aqd to.
222 Therefore they are checked against a regular expression \f(CW\*(C`untaint_pattern\*(C'\fR.
223 Note that all names passed to the user\*(Aqs \f(CWwanted()\fR function are still
224 tainted. If this option is used while not in taint\-mode, \f(CW\*(C`untaint\*(C'\fR
225 is a no\-op.
226 .ie n .IP """untaint_pattern""" 4
227 .el .IP \f(CWuntaint_pattern\fR 4
228 .IX Item "untaint_pattern"
229 See above. This should be set using the \f(CW\*(C`qr\*(C'\fR quoting operator.
230 The default is set to \f(CW\*(C`qr|^([\-+@\ew./]+)$|\*(C'\fR.
231 Note that the parentheses are vital.
232 .ie n .IP """untaint_skip""" 4
233 .el .IP \f(CWuntaint_skip\fR 4
234 .IX Item "untaint_skip"
235 If set, a directory which fails the \f(CW\*(C`untaint_pattern\*(C'\fR is skipped,
236 including all its sub\-directories. The default is to \f(CW\*(C`die\*(C'\fR in such a case.
237 .SS "The wanted function"
238 .IX Subsection "The wanted function"
239 The \f(CWwanted()\fR function does whatever verifications you want on
240 each file and directory. Note that despite its name, the \f(CWwanted()\fR
241 function is a generic callback function, and does \fBnot\fR tell
242 \&\f(CW\*(C`File::Find\*(C'\fR if a file is "wanted" or not. In fact, its return value
243 is ignored.
244 .PP
245 The \f(CW\*(C`wanted\*(C'\fR function takes no arguments but rather does its work
246 through a collection of variables.
247 .ie n .IP "$File::Find::dir is the current directory name," 4
248 .el .IP "\f(CW$File::Find::dir\fR is the current directory name," 4
249 .IX Item "$File::Find::dir is the current directory name,"
250 .PD 0
251 .ie n .IP "$_ is the current filename within that directory" 4
252 .el .IP "\f(CW$_\fR is the current filename within that directory" 4
253 .IX Item "$_ is the current filename within that directory"
254 .ie n .IP "$File::Find::name is the complete pathname to the file." 4
255 .el .IP "\f(CW$File::Find::name\fR is the complete pathname to the file." 4
256 .IX Item "$File::Find::name is the complete pathname to the file."
257 .PD
258 .PP
259 The above variables have all been localized and may be changed without
260 affecting data outside of the wanted function.
261 .PP
262 For example, when examining the file \fI/some/path/foo.ext\fR you will have:
263 .PP
264 .Vb 3
265 \& $File::Find::dir = /some/path/
266 \& $_ = foo.ext
267 \& $File::Find::name = /some/path/foo.ext
268 .Ve
269 .PP
270 You are \f(CWchdir()\fR\*(Aqd to \f(CW$File::Find::dir\fR when the function is called,
271 unless \f(CW\*(C`no_chdir\*(C'\fR was specified. Note that when changing to
272 directories is in effect, the root directory (\fI/\fR) is a somewhat
273 special case inasmuch as the concatenation of \f(CW$File::Find::dir\fR,
274 \&\f(CW\*(Aq/\*(Aq\fR and \f(CW$_\fR is not literally equal to \f(CW$File::Find::name\fR. The
275 table below summarizes all variants:
276 .PP
277 .Vb 4
278 \& $File::Find::name $File::Find::dir $_
279 \& default / / .
280 \& no_chdir=>0 /etc / etc
281 \& /etc/x /etc x
282 \&
283 \& no_chdir=>1 / / /
284 \& /etc / /etc
285 \& /etc/x /etc /etc/x
286 .Ve
287 .PP
288 When \f(CW\*(C`follow\*(C'\fR or \f(CW\*(C`follow_fast\*(C'\fR are in effect, there is
289 also a \f(CW$File::Find::fullname\fR. The function may set
290 \&\f(CW$File::Find::prune\fR to prune the tree unless \f(CW\*(C`bydepth\*(C'\fR was
291 specified. Unless \f(CW\*(C`follow\*(C'\fR or \f(CW\*(C`follow_fast\*(C'\fR is specified, for
292 compatibility reasons (\f(CW\*(C`find.pl\*(C'\fR, find2perl) there are
293 in addition the following globals available: \f(CW$File::Find::topdir\fR,
294 \&\f(CW$File::Find::topdev\fR, \f(CW$File::Find::topino\fR,
295 \&\f(CW$File::Find::topmode\fR and \f(CW$File::Find::topnlink\fR.
296 .PP
297 This library is useful for the \f(CW\*(C`find2perl\*(C'\fR tool (distributed with the
298 App::find2perl CPAN module), which when fed:
299 .PP
300 .Vb 2
301 \& find2perl / \-name .nfs\e* \-mtime +7 \e
302 \& \-exec rm \-f {} \e; \-o \-fstype nfs \-prune
303 .Ve
304 .PP
305 produces something like:
306 .PP
307 .Vb 10
308 \& sub wanted {
309 \& /^\e.nfs.*\ez/s &&
310 \& (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_)) &&
311 \& int(\-M _) > 7 &&
312 \& unlink($_)
313 \& ||
314 \& ($nlink || (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_))) &&
315 \& $dev < 0 &&
316 \& ($File::Find::prune = 1);
317 \& }
318 .Ve
319 .PP
320 Notice the \f(CW\*(C`_\*(C'\fR in the above \f(CW\*(C`int(\-M _)\*(C'\fR: the \f(CW\*(C`_\*(C'\fR is a magical
321 filehandle that caches the information from the preceding
322 \&\f(CWstat()\fR, \f(CWlstat()\fR, or filetest.
323 .PP
324 Here\*(Aqs another interesting wanted function. It will find all symbolic
325 links that don\*(Aqt resolve:
326 .PP
327 .Vb 3
328 \& sub wanted {
329 \& \-l && !\-e && print "bogus link: $File::Find::name\en";
330 \& }
331 .Ve
332 .PP
333 Note that you may mix directories and (non\-directory) files in the list of
334 directories to be searched by the \f(CWwanted()\fR function.
335 .PP
336 .Vb 1
337 \& find(\e&wanted, "./foo", "./bar", "./baz/epsilon");
338 .Ve
339 .PP
340 In the example above, no file in \fI./baz/\fR other than \fI./baz/epsilon\fR will be
341 evaluated by \f(CWwanted()\fR.
342 .PP
343 See also the script \f(CW\*(C`pfind\*(C'\fR on CPAN for a nice application of this
344 module.
345 .SH WARNINGS
346 .IX Header "WARNINGS"
347 If you run your program with the \f(CW\*(C`\-w\*(C'\fR switch, or if you use the
348 \&\f(CW\*(C`warnings\*(C'\fR pragma, File::Find will report warnings for several weird
349 situations. You can disable these warnings by putting the statement
350 .PP
351 .Vb 1
352 \& no warnings \*(AqFile::Find\*(Aq;
353 .Ve
354 .PP
355 in the appropriate scope. See warnings for more info about lexical
356 warnings.
357 .SH "BUGS AND CAVEATS"
358 .IX Header "BUGS AND CAVEATS"
359 .ie n .IP $dont_use_nlink 4
360 .el .IP \f(CW$dont_use_nlink\fR 4
361 .IX Item "$dont_use_nlink"
362 You can set the variable \f(CW$File::Find::dont_use_nlink\fR to \f(CW0\fR if you
363 are sure the filesystem you are scanning reflects the number of
364 subdirectories in the parent directory\*(Aqs \f(CW\*(C`nlink\*(C'\fR count.
365 .Sp
366 If you do set \f(CW$File::Find::dont_use_nlink\fR to 0, you may notice an
367 improvement in speed at the risk of not recursing into subdirectories
368 if a filesystem doesn\*(Aqt populate \f(CW\*(C`nlink\*(C'\fR as expected.
369 .Sp
370 \&\f(CW$File::Find::dont_use_nlink\fR now defaults to 1 on all platforms.
371 .IP Symlinks 4
372 .IX Item "Symlinks"
373 Be aware that the option to follow symbolic links can be dangerous.
374 Depending on the structure of the directory tree (including symbolic
375 links to directories) you might traverse a given (physical) directory
376 more than once (only if \f(CW\*(C`follow_fast\*(C'\fR is in effect).
377 Furthermore, deleting or changing files in a symbolically linked directory
378 might cause very unpleasant surprises, since you delete or change files
379 in an unknown directory.
380 .SH HISTORY
381 .IX Header "HISTORY"
382 \&\f(CW\*(C`File::Find\*(C'\fR used to produce incorrect results if called recursively.
383 During the development of perl 5.8 this bug was fixed.
384 The first fixed version of \f(CW\*(C`File::Find\*(C'\fR was 1.01.
385 .SH "SEE ALSO"
386 .IX Header "SEE ALSO"
387 \&\fBfind\fR\|(1), find2perl