Debian Codegraph @

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