Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "File::Find 3" | |
132 | .TH File::Find 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | File::Find \- Traverse a directory tree. | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 3 | |
138 | \& use File::Find; | |
139 | \& find(\e&wanted, @directories_to_search); | |
140 | \& sub wanted { ... } | |
141 | .Ve | |
142 | .PP | |
143 | .Vb 3 | |
144 | \& use File::Find; | |
145 | \& finddepth(\e&wanted, @directories_to_search); | |
146 | \& sub wanted { ... } | |
147 | .Ve | |
148 | .PP | |
149 | .Vb 2 | |
150 | \& use File::Find; | |
151 | \& find({ wanted => \e&process, follow => 1 }, '.'); | |
152 | .Ve | |
153 | .SH "DESCRIPTION" | |
154 | .IX Header "DESCRIPTION" | |
155 | These are functions for searching through directory trees doing work | |
156 | on each file found similar to the Unix \fIfind\fR command. File::Find | |
157 | exports two functions, \f(CW\*(C`find\*(C'\fR and \f(CW\*(C`finddepth\*(C'\fR. They work similarly | |
158 | but have subtle differences. | |
159 | .IP "\fBfind\fR" 4 | |
160 | .IX Item "find" | |
161 | .Vb 2 | |
162 | \& find(\e&wanted, @directories); | |
163 | \& find(\e%options, @directories); | |
164 | .Ve | |
165 | .Sp | |
166 | \&\f(CW\*(C`find()\*(C'\fR does a depth-first search over the given \f(CW@directories\fR in | |
167 | the order they are given. For each file or directory found, it calls | |
168 | the \f(CW&wanted\fR subroutine. (See below for details on how to use the | |
169 | \&\f(CW&wanted\fR function). Additionally, for each directory found, it will | |
170 | \&\f(CW\*(C`chdir()\*(C'\fR into that directory and continue the search, invoking the | |
171 | \&\f(CW&wanted\fR function on each file or subdirectory in the directory. | |
172 | .IP "\fBfinddepth\fR" 4 | |
173 | .IX Item "finddepth" | |
174 | .Vb 2 | |
175 | \& finddepth(\e&wanted, @directories); | |
176 | \& finddepth(\e%options, @directories); | |
177 | .Ve | |
178 | .Sp | |
179 | \&\f(CW\*(C`finddepth()\*(C'\fR works just like \f(CW\*(C`find()\*(C'\fR except that is invokes the | |
180 | \&\f(CW&wanted\fR function for a directory \fIafter\fR invoking it for the | |
181 | directory's contents. It does a postorder traversal instead of a | |
182 | preorder traversal, working from the bottom of the directory tree up | |
183 | where \f(CW\*(C`find()\*(C'\fR works from the top of the tree down. | |
184 | .Sh "%options" | |
185 | .IX Subsection "%options" | |
186 | The first argument to \f(CW\*(C`find()\*(C'\fR is either a code reference to your | |
187 | \&\f(CW&wanted\fR function, or a hash reference describing the operations | |
188 | to be performed for each file. The | |
189 | code reference is described in \*(L"The wanted function\*(R" below. | |
190 | .PP | |
191 | Here are the possible keys for the hash: | |
192 | .ie n .IP """wanted""" 3 | |
193 | .el .IP "\f(CWwanted\fR" 3 | |
194 | .IX Item "wanted" | |
195 | The value should be a code reference. This code reference is | |
196 | described in \*(L"The wanted function\*(R" below. | |
197 | .ie n .IP """bydepth""" 3 | |
198 | .el .IP "\f(CWbydepth\fR" 3 | |
199 | .IX Item "bydepth" | |
200 | Reports the name of a directory only \s-1AFTER\s0 all its entries | |
201 | have been reported. Entry point \f(CW\*(C`finddepth()\*(C'\fR is a shortcut for | |
202 | specifying \f(CW\*(C`<{ bydepth =\*(C'\fR 1 }>> in the first argument of \f(CW\*(C`find()\*(C'\fR. | |
203 | .ie n .IP """preprocess""" 3 | |
204 | .el .IP "\f(CWpreprocess\fR" 3 | |
205 | .IX Item "preprocess" | |
206 | The value should be a code reference. This code reference is used to | |
207 | preprocess the current directory. The name of the currently processed | |
208 | directory is in \f(CW$File::Find::dir\fR. Your preprocessing function is | |
209 | called after \f(CW\*(C`readdir()\*(C'\fR, but before the loop that calls the \f(CW\*(C`wanted()\*(C'\fR | |
210 | function. It is called with a list of strings (actually file/directory | |
211 | names) and is expected to return a list of strings. The code can be | |
212 | used to sort the file/directory names alphabetically, numerically, | |
213 | or to filter out directory entries based on their name alone. When | |
214 | \&\fIfollow\fR or \fIfollow_fast\fR are in effect, \f(CW\*(C`preprocess\*(C'\fR is a no\-op. | |
215 | .ie n .IP """postprocess""" 3 | |
216 | .el .IP "\f(CWpostprocess\fR" 3 | |
217 | .IX Item "postprocess" | |
218 | The value should be a code reference. It is invoked just before leaving | |
219 | the currently processed directory. It is called in void context with no | |
220 | arguments. The name of the current directory is in \f(CW$File::Find::dir\fR. This | |
221 | hook is handy for summarizing a directory, such as calculating its disk | |
222 | usage. When \fIfollow\fR or \fIfollow_fast\fR are in effect, \f(CW\*(C`postprocess\*(C'\fR is a | |
223 | no\-op. | |
224 | .ie n .IP """follow""" 3 | |
225 | .el .IP "\f(CWfollow\fR" 3 | |
226 | .IX Item "follow" | |
227 | Causes symbolic links to be followed. Since directory trees with symbolic | |
228 | links (followed) may contain files more than once and may even have | |
229 | cycles, a hash has to be built up with an entry for each file. | |
230 | This might be expensive both in space and time for a large | |
231 | directory tree. See \fIfollow_fast\fR and \fIfollow_skip\fR below. | |
232 | If either \fIfollow\fR or \fIfollow_fast\fR is in effect: | |
233 | .RS 3 | |
234 | .IP "*" 6 | |
235 | It is guaranteed that an \fIlstat\fR has been called before the user's | |
236 | \&\f(CW\*(C`wanted()\*(C'\fR function is called. This enables fast file checks involving _. | |
237 | Note that this guarantee no longer holds if \fIfollow\fR or \fIfollow_fast\fR | |
238 | are not set. | |
239 | .IP "*" 6 | |
240 | There is a variable \f(CW$File::Find::fullname\fR which holds the absolute | |
241 | pathname of the file with all symbolic links resolved. If the link is | |
242 | a dangling symbolic link, then fullname will be set to \f(CW\*(C`undef\*(C'\fR. | |
243 | .RE | |
244 | .RS 3 | |
245 | .Sp | |
246 | This is a no-op on Win32. | |
247 | .RE | |
248 | .ie n .IP """follow_fast""" 3 | |
249 | .el .IP "\f(CWfollow_fast\fR" 3 | |
250 | .IX Item "follow_fast" | |
251 | This is similar to \fIfollow\fR except that it may report some files more | |
252 | than once. It does detect cycles, however. Since only symbolic links | |
253 | have to be hashed, this is much cheaper both in space and time. If | |
254 | processing a file more than once (by the user's \f(CW\*(C`wanted()\*(C'\fR function) | |
255 | is worse than just taking time, the option \fIfollow\fR should be used. | |
256 | .Sp | |
257 | This is also a no-op on Win32. | |
258 | .ie n .IP """follow_skip""" 3 | |
259 | .el .IP "\f(CWfollow_skip\fR" 3 | |
260 | .IX Item "follow_skip" | |
261 | \&\f(CW\*(C`follow_skip==1\*(C'\fR, which is the default, causes all files which are | |
262 | neither directories nor symbolic links to be ignored if they are about | |
263 | to be processed a second time. If a directory or a symbolic link | |
264 | are about to be processed a second time, File::Find dies. | |
265 | .Sp | |
266 | \&\f(CW\*(C`follow_skip==0\*(C'\fR causes File::Find to die if any file is about to be | |
267 | processed a second time. | |
268 | .Sp | |
269 | \&\f(CW\*(C`follow_skip==2\*(C'\fR causes File::Find to ignore any duplicate files and | |
270 | directories but to proceed normally otherwise. | |
271 | .ie n .IP """dangling_symlinks""" 3 | |
272 | .el .IP "\f(CWdangling_symlinks\fR" 3 | |
273 | .IX Item "dangling_symlinks" | |
274 | If true and a code reference, will be called with the symbolic link | |
275 | name and the directory it lives in as arguments. Otherwise, if true | |
276 | and warnings are on, warning \*(L"symbolic_link_name is a dangling | |
277 | symbolic link\en\*(R" will be issued. If false, the dangling symbolic link | |
278 | will be silently ignored. | |
279 | .ie n .IP """no_chdir""" 3 | |
280 | .el .IP "\f(CWno_chdir\fR" 3 | |
281 | .IX Item "no_chdir" | |
282 | Does not \f(CW\*(C`chdir()\*(C'\fR to each directory as it recurses. The \f(CW\*(C`wanted()\*(C'\fR | |
283 | function will need to be aware of this, of course. In this case, | |
284 | \&\f(CW$_\fR will be the same as \f(CW$File::Find::name\fR. | |
285 | .ie n .IP """untaint""" 3 | |
286 | .el .IP "\f(CWuntaint\fR" 3 | |
287 | .IX Item "untaint" | |
288 | If find is used in taint-mode (\-T command line switch or if \s-1EUID\s0 != \s-1UID\s0 | |
289 | or if \s-1EGID\s0 != \s-1GID\s0) then internally directory names have to be untainted | |
290 | before they can be chdir'ed to. Therefore they are checked against a regular | |
291 | expression \fIuntaint_pattern\fR. Note that all names passed to the user's | |
292 | \&\fI\fIwanted()\fI\fR function are still tainted. If this option is used while | |
293 | not in taint\-mode, \f(CW\*(C`untaint\*(C'\fR is a no\-op. | |
294 | .ie n .IP """untaint_pattern""" 3 | |
295 | .el .IP "\f(CWuntaint_pattern\fR" 3 | |
296 | .IX Item "untaint_pattern" | |
297 | See above. This should be set using the \f(CW\*(C`qr\*(C'\fR quoting operator. | |
298 | The default is set to \f(CW\*(C`qr|^([\-+@\ew./]+)$|\*(C'\fR. | |
299 | Note that the parentheses are vital. | |
300 | .ie n .IP """untaint_skip""" 3 | |
301 | .el .IP "\f(CWuntaint_skip\fR" 3 | |
302 | .IX Item "untaint_skip" | |
303 | If set, a directory which fails the \fIuntaint_pattern\fR is skipped, | |
304 | including all its sub\-directories. The default is to 'die' in such a case. | |
305 | .Sh "The wanted function" | |
306 | .IX Subsection "The wanted function" | |
307 | The \f(CW\*(C`wanted()\*(C'\fR function does whatever verifications you want on | |
308 | each file and directory. Note that despite its name, the \f(CW\*(C`wanted()\*(C'\fR | |
309 | function is a generic callback function, and does \fBnot\fR tell | |
310 | File::Find if a file is \*(L"wanted\*(R" or not. In fact, its return value | |
311 | is ignored. | |
312 | .PP | |
313 | The wanted function takes no arguments but rather does its work | |
314 | through a collection of variables. | |
315 | .ie n .IP "$File::Find::dir is the current directory name," 4 | |
316 | .el .IP "\f(CW$File::Find::dir\fR is the current directory name," 4 | |
317 | .IX Item "$File::Find::dir is the current directory name," | |
318 | .PD 0 | |
319 | .ie n .IP "$_ is the current filename within that directory" 4 | |
320 | .el .IP "\f(CW$_\fR is the current filename within that directory" 4 | |
321 | .IX Item "$_ is the current filename within that directory" | |
322 | .ie n .IP "$File::Find::name is the complete pathname to the file." 4 | |
323 | .el .IP "\f(CW$File::Find::name\fR is the complete pathname to the file." 4 | |
324 | .IX Item "$File::Find::name is the complete pathname to the file." | |
325 | .PD | |
326 | .PP | |
327 | Don't modify these variables. | |
328 | .PP | |
329 | For example, when examining the file \fI/some/path/foo.ext\fR you will have: | |
330 | .PP | |
331 | .Vb 3 | |
332 | \& $File::Find::dir = /some/path/ | |
333 | \& $_ = foo.ext | |
334 | \& $File::Find::name = /some/path/foo.ext | |
335 | .Ve | |
336 | .PP | |
337 | You are \fIchdir()\fR'd to \f(CW$File::Find::dir\fR when the function is called, | |
338 | unless \f(CW\*(C`no_chdir\*(C'\fR was specified. Note that when changing to | |
339 | directories is in effect the root directory (\fI/\fR) is a somewhat | |
340 | special case inasmuch as the concatenation of \f(CW$File::Find::dir\fR, | |
341 | \&\f(CW'/'\fR and \f(CW$_\fR is not literally equal to \f(CW$File::Find::name\fR. The | |
342 | table below summarizes all variants: | |
343 | .PP | |
344 | .Vb 4 | |
345 | \& $File::Find::name $File::Find::dir $_ | |
346 | \& default / / . | |
347 | \& no_chdir=>0 /etc / etc | |
348 | \& /etc/x /etc x | |
349 | .Ve | |
350 | .PP | |
351 | .Vb 3 | |
352 | \& no_chdir=>1 / / / | |
353 | \& /etc / /etc | |
354 | \& /etc/x /etc /etc/x | |
355 | .Ve | |
356 | .PP | |
357 | When <follow> or <follow_fast> are in effect, there is | |
358 | also a \f(CW$File::Find::fullname\fR. The function may set | |
359 | \&\f(CW$File::Find::prune\fR to prune the tree unless \f(CW\*(C`bydepth\*(C'\fR was | |
360 | specified. Unless \f(CW\*(C`follow\*(C'\fR or \f(CW\*(C`follow_fast\*(C'\fR is specified, for | |
361 | compatibility reasons (find.pl, find2perl) there are in addition the | |
362 | following globals available: \f(CW$File::Find::topdir\fR, | |
363 | \&\f(CW$File::Find::topdev\fR, \f(CW$File::Find::topino\fR, | |
364 | \&\f(CW$File::Find::topmode\fR and \f(CW$File::Find::topnlink\fR. | |
365 | .PP | |
366 | This library is useful for the \f(CW\*(C`find2perl\*(C'\fR tool, which when fed, | |
367 | .PP | |
368 | .Vb 2 | |
369 | \& find2perl / -name .nfs\e* -mtime +7 \e | |
370 | \& -exec rm -f {} \e; -o -fstype nfs -prune | |
371 | .Ve | |
372 | .PP | |
373 | produces something like: | |
374 | .PP | |
375 | .Vb 10 | |
376 | \& sub wanted { | |
377 | \& /^\e.nfs.*\ez/s && | |
378 | \& (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_)) && | |
379 | \& int(-M _) > 7 && | |
380 | \& unlink($_) | |
381 | \& || | |
382 | \& ($nlink || (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_))) && | |
383 | \& $dev < 0 && | |
384 | \& ($File::Find::prune = 1); | |
385 | \& } | |
386 | .Ve | |
387 | .PP | |
388 | 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 | |
389 | filehandle that caches the information from the preceding | |
390 | \&\f(CW\*(C`stat()\*(C'\fR, \f(CW\*(C`lstat()\*(C'\fR, or filetest. | |
391 | .PP | |
392 | Here's another interesting wanted function. It will find all symbolic | |
393 | links that don't resolve: | |
394 | .PP | |
395 | .Vb 3 | |
396 | \& sub wanted { | |
397 | \& -l && !-e && print "bogus link: $File::Find::name\en"; | |
398 | \& } | |
399 | .Ve | |
400 | .PP | |
401 | See also the script \f(CW\*(C`pfind\*(C'\fR on \s-1CPAN\s0 for a nice application of this | |
402 | module. | |
403 | .SH "WARNINGS" | |
404 | .IX Header "WARNINGS" | |
405 | If you run your program with the \f(CW\*(C`\-w\*(C'\fR switch, or if you use the | |
406 | \&\f(CW\*(C`warnings\*(C'\fR pragma, File::Find will report warnings for several weird | |
407 | situations. You can disable these warnings by putting the statement | |
408 | .PP | |
409 | .Vb 1 | |
410 | \& no warnings 'File::Find'; | |
411 | .Ve | |
412 | .PP | |
413 | in the appropriate scope. See perllexwarn for more info about lexical | |
414 | warnings. | |
415 | .SH "CAVEAT" | |
416 | .IX Header "CAVEAT" | |
417 | .IP "$dont_use_nlink" 2 | |
418 | .IX Item "$dont_use_nlink" | |
419 | You can set the variable \f(CW$File::Find::dont_use_nlink\fR to 1, if you want to | |
420 | force File::Find to always stat directories. This was used for file systems | |
421 | that do not have an \f(CW\*(C`nlink\*(C'\fR count matching the number of sub\-directories. | |
422 | Examples are \s-1ISO\-9660\s0 (\s-1CD\-ROM\s0), \s-1AFS\s0, \s-1HPFS\s0 (\s-1OS/2\s0 file system), \s-1FAT\s0 (\s-1DOS\s0 file | |
423 | system) and a couple of others. | |
424 | .Sp | |
425 | You shouldn't need to set this variable, since File::Find should now detect | |
426 | such file systems on-the-fly and switch itself to using stat. This works even | |
427 | for parts of your file system, like a mounted \s-1CD\-ROM\s0. | |
428 | .Sp | |
429 | If you do set \f(CW$File::Find::dont_use_nlink\fR to 1, you will notice slow\-downs. | |
430 | .IP "symlinks" 2 | |
431 | .IX Item "symlinks" | |
432 | Be aware that the option to follow symbolic links can be dangerous. | |
433 | Depending on the structure of the directory tree (including symbolic | |
434 | links to directories) you might traverse a given (physical) directory | |
435 | more than once (only if \f(CW\*(C`follow_fast\*(C'\fR is in effect). | |
436 | Furthermore, deleting or changing files in a symbolically linked directory | |
437 | might cause very unpleasant surprises, since you delete or change files | |
438 | in an unknown directory. | |
439 | .SH "NOTES" | |
440 | .IX Header "NOTES" | |
441 | .IP "\(bu" 4 | |
442 | Mac \s-1OS\s0 (Classic) users should note a few differences: | |
443 | .RS 4 | |
444 | .IP "\(bu" 4 | |
445 | The path separator is ':', not '/', and the current directory is denoted | |
446 | as ':', not '.'. You should be careful about specifying relative pathnames. | |
447 | While a full path always begins with a volume name, a relative pathname | |
448 | should always begin with a ':'. If specifying a volume name only, a | |
449 | trailing ':' is required. | |
450 | .IP "\(bu" 4 | |
451 | \&\f(CW$File::Find::dir\fR is guaranteed to end with a ':'. If \f(CW$_\fR | |
452 | contains the name of a directory, that name may or may not end with a | |
453 | \&':'. Likewise, \f(CW$File::Find::name\fR, which contains the complete | |
454 | pathname to that directory, and \f(CW$File::Find::fullname\fR, which holds | |
455 | the absolute pathname of that directory with all symbolic links resolved, | |
456 | may or may not end with a ':'. | |
457 | .IP "\(bu" 4 | |
458 | The default \f(CW\*(C`untaint_pattern\*(C'\fR (see above) on Mac \s-1OS\s0 is set to | |
459 | \&\f(CW\*(C`qr|^(.+)$|\*(C'\fR. Note that the parentheses are vital. | |
460 | .IP "\(bu" 4 | |
461 | The invisible system file \*(L"Icon\e015\*(R" is ignored. While this file may | |
462 | appear in every directory, there are some more invisible system files | |
463 | on every volume, which are all located at the volume root level (i.e. | |
464 | \&\*(L"MacintoshHD:\*(R"). These system files are \fBnot\fR excluded automatically. | |
465 | Your filter may use the following code to recognize invisible files or | |
466 | directories (requires Mac::Files): | |
467 | .Sp | |
468 | .Vb 1 | |
469 | \& use Mac::Files; | |
470 | .Ve | |
471 | .Sp | |
472 | .Vb 2 | |
473 | \& # invisible() -- returns 1 if file/directory is invisible, | |
474 | \& # 0 if it's visible or undef if an error occurred | |
475 | .Ve | |
476 | .Sp | |
477 | .Vb 4 | |
478 | \& sub invisible($) { | |
479 | \& my $file = shift; | |
480 | \& my ($fileCat, $fileInfo); | |
481 | \& my $invisible_flag = 1 << 14; | |
482 | .Ve | |
483 | .Sp | |
484 | .Vb 7 | |
485 | \& if ( $fileCat = FSpGetCatInfo($file) ) { | |
486 | \& if ($fileInfo = $fileCat->ioFlFndrInfo() ) { | |
487 | \& return (($fileInfo->fdFlags & $invisible_flag) && 1); | |
488 | \& } | |
489 | \& } | |
490 | \& return undef; | |
491 | \& } | |
492 | .Ve | |
493 | .Sp | |
494 | Generally, invisible files are system files, unless an odd application | |
495 | decides to use invisible files for its own purposes. To distinguish | |
496 | such files from system files, you have to look at the \fBtype\fR and \fBcreator\fR | |
497 | file attributes. The MacPerl built-in functions \f(CW\*(C`GetFileInfo(FILE)\*(C'\fR and | |
498 | \&\f(CW\*(C`SetFileInfo(CREATOR, TYPE, FILES)\*(C'\fR offer access to these attributes | |
499 | (see MacPerl.pm for details). | |
500 | .Sp | |
501 | Files that appear on the desktop actually reside in an (hidden) directory | |
502 | named \*(L"Desktop Folder\*(R" on the particular disk volume. Note that, although | |
503 | all desktop files appear to be on the same \*(L"virtual\*(R" desktop, each disk | |
504 | volume actually maintains its own \*(L"Desktop Folder\*(R" directory. | |
505 | .RE | |
506 | .RS 4 | |
507 | .RE | |
508 | .SH "BUGS AND CAVEATS" | |
509 | .IX Header "BUGS AND CAVEATS" | |
510 | Despite the name of the \f(CW\*(C`finddepth()\*(C'\fR function, both \f(CW\*(C`find()\*(C'\fR and | |
511 | \&\f(CW\*(C`finddepth()\*(C'\fR perform a depth-first search of the directory | |
512 | hierarchy. | |
513 | .SH "HISTORY" | |
514 | .IX Header "HISTORY" | |
515 | File::Find used to produce incorrect results if called recursively. | |
516 | During the development of perl 5.8 this bug was fixed. | |
517 | The first fixed version of File::Find was 1.01. |