1File::Find(3pm) Perl Programmers Reference Guide File::Find(3pm)
2
6 File::Find - Traverse a directory tree.
7
9 use File::Find;
10 find(\&wanted, @directories_to_search);
11 sub wanted { ... }
12 use File::Find;
14 finddepth(\&wanted, @directories_to_search);
15 sub wanted { ... }
16 use File::Find;
18 find({ wanted => \&process, follow => 1 }, '.');
19
21 These are functions for searching through directory trees doing work on
22 each file found similar to the Unix find command. File::Find exports
23 two functions, "find" and "finddepth". They work similarly but have
24 subtle differences.
25 find
27 find(\&wanted, @directories);
28 find(\%options, @directories);
29 "find()" does a depth-first search over the given @directories in
31 the order they are given. For each file or directory found, it
32 calls the &wanted subroutine. (See below for details on how to use
33 the &wanted function). Additionally, for each directory found, it
34 will "chdir()" into that directory and continue the search,
35 invoking the &wanted function on each file or subdirectory in the
36 directory.
37 finddepth
39 finddepth(\&wanted, @directories);
40 finddepth(\%options, @directories);
41 "finddepth()" works just like "find()" except that it invokes the
43 &wanted function for a directory after invoking it for the
44 directory's contents. It does a postorder traversal instead of a
45 preorder traversal, working from the bottom of the directory tree
46 up where "find()" works from the top of the tree down.
47 %options
49 The first argument to "find()" is either a code reference to your
50 &wanted function, or a hash reference describing the operations to be
51 performed for each file. The code reference is described in "The
52 wanted function" below.
53 Here are the possible keys for the hash:
55 "wanted"
57 The value should be a code reference. This code reference is
58 described in "The wanted function" below. The &wanted subroutine is
59 mandatory.
60 "bydepth"
62 Reports the name of a directory only AFTER all its entries have been
63 reported. Entry point "finddepth()" is a shortcut for specifying "{
64 bydepth => 1 }" in the first argument of "find()".
65 "preprocess"
67 The value should be a code reference. This code reference is used to
68 preprocess the current directory. The name of the currently
69 processed directory is in $File::Find::dir. Your preprocessing
70 function is called after "readdir()", but before the loop that calls
71 the "wanted()" function. It is called with a list of strings
72 (actually file/directory names) and is expected to return a list of
73 strings. The code can be used to sort the file/directory names
74 alphabetically, numerically, or to filter out directory entries
75 based on their name alone. When follow or follow_fast are in effect,
76 "preprocess" is a no-op.
77 "postprocess"
79 The value should be a code reference. It is invoked just before
80 leaving the currently processed directory. It is called in void
81 context with no arguments. The name of the current directory is in
82 $File::Find::dir. This hook is handy for summarizing a directory,
83 such as calculating its disk usage. When follow or follow_fast are
84 in effect, "postprocess" is a no-op.
85 "follow"
87 Causes symbolic links to be followed. Since directory trees with
88 symbolic links (followed) may contain files more than once and may
89 even have cycles, a hash has to be built up with an entry for each
90 file. This might be expensive both in space and time for a large
91 directory tree. See "follow_fast" and "follow_skip" below. If
92 either follow or follow_fast is in effect:
93 • It is guaranteed that an lstat has been called before the
95 user's "wanted()" function is called. This enables fast file
96 checks involving "_". Note that this guarantee no longer
97 holds if follow or follow_fast are not set.
98 • There is a variable $File::Find::fullname which holds the
100 absolute pathname of the file with all symbolic links
101 resolved. If the link is a dangling symbolic link, then
102 fullname will be set to "undef".
103 This is a no-op on Win32.
105 "follow_fast"
107 This is similar to follow except that it may report some files more
108 than once. It does detect cycles, however. Since only symbolic
109 links have to be hashed, this is much cheaper both in space and
110 time. If processing a file more than once (by the user's "wanted()"
111 function) is worse than just taking time, the option follow should
112 be used.
113 This is also a no-op on Win32.
115 "follow_skip"
117 "follow_skip==1", which is the default, causes all files which are
118 neither directories nor symbolic links to be ignored if they are
119 about to be processed a second time. If a directory or a symbolic
120 link are about to be processed a second time, File::Find dies.
121 "follow_skip==0" causes File::Find to die if any file is about to be
123 processed a second time.
124 "follow_skip==2" causes File::Find to ignore any duplicate files and
126 directories but to proceed normally otherwise.
127 "dangling_symlinks"
129 Specifies what to do with symbolic links whose target doesn't exist.
130 If true and a code reference, will be called with the symbolic link
131 name and the directory it lives in as arguments. Otherwise, if true
132 and warnings are on, a warning of the form "symbolic_link_name is a
133 dangling symbolic link\n" will be issued. If false, the dangling
134 symbolic link will be silently ignored.
135 "no_chdir"
137 Does not "chdir()" to each directory as it recurses. The "wanted()"
138 function will need to be aware of this, of course. In this case, $_
139 will be the same as $File::Find::name.
140 "untaint"
142 If find is used in taint-mode (-T command line switch or if EUID !=
143 UID or if EGID != GID), then internally directory names have to be
144 untainted before they can be "chdir"'d to. Therefore they are
145 checked against a regular expression untaint_pattern. Note that all
146 names passed to the user's "wanted()" function are still tainted. If
147 this option is used while not in taint-mode, "untaint" is a no-op.
148 "untaint_pattern"
150 See above. This should be set using the "qr" quoting operator. The
151 default is set to "qr|^([-+@\w./]+)$|". Note that the parentheses
152 are vital.
153 "untaint_skip"
155 If set, a directory which fails the untaint_pattern is skipped,
156 including all its sub-directories. The default is to "die" in such a
157 case.
158 The wanted function
160 The "wanted()" function does whatever verifications you want on each
161 file and directory. Note that despite its name, the "wanted()"
162 function is a generic callback function, and does not tell File::Find
163 if a file is "wanted" or not. In fact, its return value is ignored.
164 The wanted function takes no arguments but rather does its work through
166 a collection of variables.
167 $File::Find::dir is the current directory name,
169 $_ is the current filename within that directory
170 $File::Find::name is the complete pathname to the file.
171 The above variables have all been localized and may be changed without
173 affecting data outside of the wanted function.
174 For example, when examining the file /some/path/foo.ext you will have:
176 $File::Find::dir = /some/path/
178 $_ = foo.ext
179 $File::Find::name = /some/path/foo.ext
180 You are chdir()'d to $File::Find::dir when the function is called,
182 unless "no_chdir" was specified. Note that when changing to directories
183 is in effect, the root directory (/) is a somewhat special case
184 inasmuch as the concatenation of $File::Find::dir, '/' and $_ is not
185 literally equal to $File::Find::name. The table below summarizes all
186 variants:
187 $File::Find::name $File::Find::dir $_
189 default / / .
190 no_chdir=>0 /etc / etc
191 /etc/x /etc x
192 no_chdir=>1 / / /
194 /etc / /etc
195 /etc/x /etc /etc/x
196 When "follow" or "follow_fast" are in effect, there is also a
198 $File::Find::fullname. The function may set $File::Find::prune to
199 prune the tree unless "bydepth" was specified. Unless "follow" or
200 "follow_fast" is specified, for compatibility reasons (find.pl,
201 find2perl) there are in addition the following globals available:
202 $File::Find::topdir, $File::Find::topdev, $File::Find::topino,
203 $File::Find::topmode and $File::Find::topnlink.
204 This library is useful for the "find2perl" tool (distributed as part of
206 the App-find2perl CPAN distribution), which when fed,
207 find2perl / -name .nfs\* -mtime +7 \
209 -exec rm -f {} \; -o -fstype nfs -prune
210 produces something like:
212 sub wanted {
214 /^\.nfs.*\z/s &&
215 (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_)) &&
216 int(-M _) > 7 &&
217 unlink($_)
218 ||
219 ($nlink || (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_))) &&
220 $dev < 0 &&
221 ($File::Find::prune = 1);
222 }
223 Notice the "_" in the above "int(-M _)": the "_" is a magical
225 filehandle that caches the information from the preceding "stat()",
226 "lstat()", or filetest.
227 Here's another interesting wanted function. It will find all symbolic
229 links that don't resolve:
230 sub wanted {
232 -l && !-e && print "bogus link: $File::Find::name\n";
233 }
234 Note that you may mix directories and (non-directory) files in the list
236 of directories to be searched by the "wanted()" function.
237 find(\&wanted, "./foo", "./bar", "./baz/epsilon");
239 In the example above, no file in ./baz/ other than ./baz/epsilon will
241 be evaluated by "wanted()".
242 See also the script "pfind" on CPAN for a nice application of this
244 module.
245
247 If you run your program with the "-w" switch, or if you use the
248 "warnings" pragma, File::Find will report warnings for several weird
249 situations. You can disable these warnings by putting the statement
250 no warnings 'File::Find';
252 in the appropriate scope. See warnings for more info about lexical
254 warnings.
255
257 $dont_use_nlink
258 You can set the variable $File::Find::dont_use_nlink to 0 if you are
259 sure the filesystem you are scanning reflects the number of
260 subdirectories in the parent directory's "nlink" count.
261 If you do set $File::Find::dont_use_nlink to 0, you may notice an
263 improvement in speed at the risk of not recursing into subdirectories
264 if a filesystem doesn't populate "nlink" as expected.
265 $File::Find::dont_use_nlink now defaults to 1 on all platforms.
267 symlinks
269 Be aware that the option to follow symbolic links can be dangerous.
270 Depending on the structure of the directory tree (including symbolic
271 links to directories) you might traverse a given (physical) directory
272 more than once (only if "follow_fast" is in effect). Furthermore,
273 deleting or changing files in a symbolically linked directory might
274 cause very unpleasant surprises, since you delete or change files in
275 an unknown directory.
276
278 Despite the name of the "finddepth()" function, both "find()" and
279 "finddepth()" perform a depth-first search of the directory hierarchy.
280
282 File::Find used to produce incorrect results if called recursively.
283 During the development of perl 5.8 this bug was fixed. The first fixed
284 version of File::Find was 1.01.
285
287 find(1), find2perl.
288perl v5.32.1 2021-05-31 File::Find(3pm)