Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
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 "2002-06-01" "perl v5.8.0" "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_seach); | |
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 | \&\fIfind()\fR does a breadth-first search over the given \f(CW@directories\fR in the | |
167 | order they are given. In essense, it works from the top down. | |
168 | .Sp | |
169 | For each file or directory found the &wanted subroutine is called (see | |
170 | below for details). Additionally, for each directory found it will go | |
171 | into that directory and continue the search. | |
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 | \&\fIfinddepth()\fR works just like \fIfind()\fR except it does a depth-first search. | |
180 | It works from the bottom of the directory tree up. | |
181 | .Sh "%options" | |
182 | .IX Subsection "%options" | |
183 | The first argument to \fIfind()\fR is either a hash reference describing the | |
184 | operations to be performed for each file, or a code reference. The | |
185 | code reference is described in \*(L"The wanted function\*(R" below. | |
186 | .PP | |
187 | Here are the possible keys for the hash: | |
188 | .ie n .IP """wanted""" 3 | |
189 | .el .IP "\f(CWwanted\fR" 3 | |
190 | .IX Item "wanted" | |
191 | The value should be a code reference. This code reference is | |
192 | described in \*(L"The wanted function\*(R" below. | |
193 | .ie n .IP """bydepth""" 3 | |
194 | .el .IP "\f(CWbydepth\fR" 3 | |
195 | .IX Item "bydepth" | |
196 | Reports the name of a directory only \s-1AFTER\s0 all its entries | |
197 | have been reported. Entry point \fIfinddepth()\fR is a shortcut for | |
198 | specifying \f(CW\*(C`{ bydepth => 1 }\*(C'\fR in the first argument of \fIfind()\fR. | |
199 | .ie n .IP """preprocess""" 3 | |
200 | .el .IP "\f(CWpreprocess\fR" 3 | |
201 | .IX Item "preprocess" | |
202 | The value should be a code reference. This code reference is used to | |
203 | preprocess the current directory. The name of currently processed | |
204 | directory is in \f(CW$File::Find::dir\fR. Your preprocessing function is | |
205 | called after \fIreaddir()\fR but before the loop that calls the \fIwanted()\fR | |
206 | function. It is called with a list of strings (actually file/directory | |
207 | names) and is expected to return a list of strings. The code can be | |
208 | used to sort the file/directory names alphabetically, numerically, | |
209 | or to filter out directory entries based on their name alone. When | |
210 | \&\fIfollow\fR or \fIfollow_fast\fR are in effect, \f(CW\*(C`preprocess\*(C'\fR is a no\-op. | |
211 | .ie n .IP """postprocess""" 3 | |
212 | .el .IP "\f(CWpostprocess\fR" 3 | |
213 | .IX Item "postprocess" | |
214 | The value should be a code reference. It is invoked just before leaving | |
215 | the currently processed directory. It is called in void context with no | |
216 | arguments. The name of the current directory is in \f(CW$File::Find::dir\fR. This | |
217 | hook is handy for summarizing a directory, such as calculating its disk | |
218 | usage. When \fIfollow\fR or \fIfollow_fast\fR are in effect, \f(CW\*(C`postprocess\*(C'\fR is a | |
219 | no\-op. | |
220 | .ie n .IP """follow""" 3 | |
221 | .el .IP "\f(CWfollow\fR" 3 | |
222 | .IX Item "follow" | |
223 | Causes symbolic links to be followed. Since directory trees with symbolic | |
224 | links (followed) may contain files more than once and may even have | |
225 | cycles, a hash has to be built up with an entry for each file. | |
226 | This might be expensive both in space and time for a large | |
227 | directory tree. See \fIfollow_fast\fR and \fIfollow_skip\fR below. | |
228 | If either \fIfollow\fR or \fIfollow_fast\fR is in effect: | |
229 | .RS 3 | |
230 | .IP "\(bu" 6 | |
231 | It is guaranteed that an \fIlstat\fR has been called before the user's | |
232 | \&\fI\fIwanted()\fI\fR function is called. This enables fast file checks involving \ _. | |
233 | .IP "\(bu" 6 | |
234 | There is a variable \f(CW$File::Find::fullname\fR which holds the absolute | |
235 | pathname of the file with all symbolic links resolved | |
236 | .RE | |
237 | .RS 3 | |
238 | .RE | |
239 | .ie n .IP """follow_fast""" 3 | |
240 | .el .IP "\f(CWfollow_fast\fR" 3 | |
241 | .IX Item "follow_fast" | |
242 | This is similar to \fIfollow\fR except that it may report some files more | |
243 | than once. It does detect cycles, however. Since only symbolic links | |
244 | have to be hashed, this is much cheaper both in space and time. If | |
245 | processing a file more than once (by the user's \fI\fIwanted()\fI\fR function) | |
246 | is worse than just taking time, the option \fIfollow\fR should be used. | |
247 | .ie n .IP """follow_skip""" 3 | |
248 | .el .IP "\f(CWfollow_skip\fR" 3 | |
249 | .IX Item "follow_skip" | |
250 | \&\f(CW\*(C`follow_skip==1\*(C'\fR, which is the default, causes all files which are | |
251 | neither directories nor symbolic links to be ignored if they are about | |
252 | to be processed a second time. If a directory or a symbolic link | |
253 | are about to be processed a second time, File::Find dies. | |
254 | \&\f(CW\*(C`follow_skip==0\*(C'\fR causes File::Find to die if any file is about to be | |
255 | processed a second time. | |
256 | \&\f(CW\*(C`follow_skip==2\*(C'\fR causes File::Find to ignore any duplicate files and | |
257 | directories but to proceed normally otherwise. | |
258 | .ie n .IP """dangling_symlinks""" 3 | |
259 | .el .IP "\f(CWdangling_symlinks\fR" 3 | |
260 | .IX Item "dangling_symlinks" | |
261 | If true and a code reference, will be called with the symbolic link | |
262 | name and the directory it lives in as arguments. Otherwise, if true | |
263 | and warnings are on, warning \*(L"symbolic_link_name is a dangling | |
264 | symbolic link\en\*(R" will be issued. If false, the dangling symbolic link | |
265 | will be silently ignored. | |
266 | .ie n .IP """no_chdir""" 3 | |
267 | .el .IP "\f(CWno_chdir\fR" 3 | |
268 | .IX Item "no_chdir" | |
269 | Does not \f(CW\*(C`chdir()\*(C'\fR to each directory as it recurses. The \fIwanted()\fR | |
270 | function will need to be aware of this, of course. In this case, | |
271 | \&\f(CW$_\fR will be the same as \f(CW$File::Find::name\fR. | |
272 | .ie n .IP """untaint""" 3 | |
273 | .el .IP "\f(CWuntaint\fR" 3 | |
274 | .IX Item "untaint" | |
275 | If find is used in taint-mode (\-T command line switch or if \s-1EUID\s0 != \s-1UID\s0 | |
276 | or if \s-1EGID\s0 != \s-1GID\s0) then internally directory names have to be untainted | |
277 | before they can be chdir'ed to. Therefore they are checked against a regular | |
278 | expression \fIuntaint_pattern\fR. Note that all names passed to the user's | |
279 | \&\fI\fIwanted()\fI\fR function are still tainted. If this option is used while | |
280 | not in taint\-mode, \f(CW\*(C`untaint\*(C'\fR is a no\-op. | |
281 | .ie n .IP """untaint_pattern""" 3 | |
282 | .el .IP "\f(CWuntaint_pattern\fR" 3 | |
283 | .IX Item "untaint_pattern" | |
284 | See above. This should be set using the \f(CW\*(C`qr\*(C'\fR quoting operator. | |
285 | The default is set to \f(CW\*(C`qr|^([\-+@\ew./]+)$|\*(C'\fR. | |
286 | Note that the parentheses are vital. | |
287 | .ie n .IP """untaint_skip""" 3 | |
288 | .el .IP "\f(CWuntaint_skip\fR" 3 | |
289 | .IX Item "untaint_skip" | |
290 | If set, a directory which fails the \fIuntaint_pattern\fR is skipped, | |
291 | including all its sub\-directories. The default is to 'die' in such a case. | |
292 | .Sh "The wanted function" | |
293 | .IX Subsection "The wanted function" | |
294 | The \fIwanted()\fR function does whatever verifications you want on each | |
295 | file and directory. It takes no arguments but rather does its work | |
296 | through a collection of variables. | |
297 | .ie n .IP "$File::Find::dir is the current directory name," 4 | |
298 | .el .IP "\f(CW$File::Find::dir\fR is the current directory name," 4 | |
299 | .IX Item "$File::Find::dir is the current directory name," | |
300 | .PD 0 | |
301 | .ie n .IP "$_ is the current filename within that directory" 4 | |
302 | .el .IP "\f(CW$_\fR is the current filename within that directory" 4 | |
303 | .IX Item "$_ is the current filename within that directory" | |
304 | .ie n .IP "$File::Find::name is the complete pathname to the file." 4 | |
305 | .el .IP "\f(CW$File::Find::name\fR is the complete pathname to the file." 4 | |
306 | .IX Item "$File::Find::name is the complete pathname to the file." | |
307 | .PD | |
308 | .PP | |
309 | Don't modify these variables. | |
310 | .PP | |
311 | For example, when examining the file /some/path/foo.ext you will have: | |
312 | .PP | |
313 | .Vb 3 | |
314 | \& $File::Find::dir = /some/path/ | |
315 | \& $_ = foo.ext | |
316 | \& $File::Find::name = /some/path/foo.ext | |
317 | .Ve | |
318 | .PP | |
319 | You are \fIchdir()\fR'd to\f(CW$File::Find::dir\fR when the function is called, | |
320 | unless \f(CW\*(C`no_chdir\*(C'\fR was specified. Note that when changing to | |
321 | directories is in effect the root directory (\fI/\fR) is a somewhat | |
322 | special case inasmuch as the concatenation of \f(CW$File::Find::dir\fR, | |
323 | \&\f(CW'/'\fR and \f(CW$_\fR is not literally equal to \f(CW$File::Find::name\fR. The | |
324 | table below summarizes all variants: | |
325 | .PP | |
326 | .Vb 4 | |
327 | \& $File::Find::name $File::Find::dir $_ | |
328 | \& default / / . | |
329 | \& no_chdir=>0 /etc / etc | |
330 | \& /etc/x /etc x | |
331 | .Ve | |
332 | .PP | |
333 | .Vb 3 | |
334 | \& no_chdir=>1 / / / | |
335 | \& /etc / /etc | |
336 | \& /etc/x /etc /etc/x | |
337 | .Ve | |
338 | .PP | |
339 | When <follow> or <follow_fast> are in effect, there is | |
340 | also a \f(CW$File::Find::fullname\fR. The function may set | |
341 | \&\f(CW$File::Find::prune\fR to prune the tree unless \f(CW\*(C`bydepth\*(C'\fR was | |
342 | specified. Unless \f(CW\*(C`follow\*(C'\fR or \f(CW\*(C`follow_fast\*(C'\fR is specified, for | |
343 | compatibility reasons (find.pl, find2perl) there are in addition the | |
344 | following globals available: \f(CW$File::Find::topdir\fR, | |
345 | \&\f(CW$File::Find::topdev\fR, \f(CW$File::Find::topino\fR, | |
346 | \&\f(CW$File::Find::topmode\fR and \f(CW$File::Find::topnlink\fR. | |
347 | .PP | |
348 | This library is useful for the \f(CW\*(C`find2perl\*(C'\fR tool, which when fed, | |
349 | .PP | |
350 | .Vb 2 | |
351 | \& find2perl / -name .nfs\e* -mtime +7 \e | |
352 | \& -exec rm -f {} \e; -o -fstype nfs -prune | |
353 | .Ve | |
354 | .PP | |
355 | produces something like: | |
356 | .PP | |
357 | .Vb 10 | |
358 | \& sub wanted { | |
359 | \& /^\e.nfs.*\ez/s && | |
360 | \& (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_)) && | |
361 | \& int(-M _) > 7 && | |
362 | \& unlink($_) | |
363 | \& || | |
364 | \& ($nlink || (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_))) && | |
365 | \& $dev < 0 && | |
366 | \& ($File::Find::prune = 1); | |
367 | \& } | |
368 | .Ve | |
369 | .PP | |
370 | 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 | |
371 | filehandle that caches the information from the preceding | |
372 | \&\fIstat()\fR, \fIlstat()\fR, or filetest. | |
373 | .PP | |
374 | Here's another interesting wanted function. It will find all symbolic | |
375 | links that don't resolve: | |
376 | .PP | |
377 | .Vb 3 | |
378 | \& sub wanted { | |
379 | \& -l && !-e && print "bogus link: $File::Find::name\en"; | |
380 | \& } | |
381 | .Ve | |
382 | .PP | |
383 | See also the script \f(CW\*(C`pfind\*(C'\fR on \s-1CPAN\s0 for a nice application of this | |
384 | module. | |
385 | .SH "WARNINGS" | |
386 | .IX Header "WARNINGS" | |
387 | If you run your program with the \f(CW\*(C`\-w\*(C'\fR switch, or if you use the | |
388 | \&\f(CW\*(C`warnings\*(C'\fR pragma, File::Find will report warnings for several weird | |
389 | situations. You can disable these warnings by putting the statement | |
390 | .PP | |
391 | .Vb 1 | |
392 | \& no warnings 'File::Find'; | |
393 | .Ve | |
394 | .PP | |
395 | in the appropriate scope. See perllexwarn for more info about lexical | |
396 | warnings. | |
397 | .SH "CAVEAT" | |
398 | .IX Header "CAVEAT" | |
399 | .IP "$dont_use_nlink" 2 | |
400 | .IX Item "$dont_use_nlink" | |
401 | You can set the variable \f(CW$File::Find::dont_use_nlink\fR to 1, if you want to | |
402 | force File::Find to always stat directories. This was used for file systems | |
403 | that do not have an \f(CW\*(C`nlink\*(C'\fR count matching the number of sub\-directories. | |
404 | 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 | |
405 | system) and a couple of others. | |
406 | .Sp | |
407 | You shouldn't need to set this variable, since File::Find should now detect | |
408 | such file systems on-the-fly and switch itself to using stat. This works even | |
409 | for parts of your file system, like a mounted \s-1CD\-ROM\s0. | |
410 | .Sp | |
411 | If you do set \f(CW$File::Find::dont_use_nlink\fR to 1, you will notice slow\-downs. | |
412 | .IP "symlinks" 2 | |
413 | .IX Item "symlinks" | |
414 | Be aware that the option to follow symbolic links can be dangerous. | |
415 | Depending on the structure of the directory tree (including symbolic | |
416 | links to directories) you might traverse a given (physical) directory | |
417 | more than once (only if \f(CW\*(C`follow_fast\*(C'\fR is in effect). | |
418 | Furthermore, deleting or changing files in a symbolically linked directory | |
419 | might cause very unpleasant surprises, since you delete or change files | |
420 | in an unknown directory. | |
421 | .SH "NOTES" | |
422 | .IX Header "NOTES" | |
423 | .IP "\(bu" 4 | |
424 | Mac \s-1OS\s0 (Classic) users should note a few differences: | |
425 | .RS 4 | |
426 | .IP "\(bu" 4 | |
427 | The path separator is ':', not '/', and the current directory is denoted | |
428 | as ':', not '.'. You should be careful about specifying relative pathnames. | |
429 | While a full path always begins with a volume name, a relative pathname | |
430 | should always begin with a ':'. If specifying a volume name only, a | |
431 | trailing ':' is required. | |
432 | .IP "\(bu" 4 | |
433 | \&\f(CW$File::Find::dir\fR is guaranteed to end with a ':'. If \f(CW$_\fR | |
434 | contains the name of a directory, that name may or may not end with a | |
435 | \&':'. Likewise, \f(CW$File::Find::name\fR, which contains the complete | |
436 | pathname to that directory, and \f(CW$File::Find::fullname\fR, which holds | |
437 | the absolute pathname of that directory with all symbolic links resolved, | |
438 | may or may not end with a ':'. | |
439 | .IP "\(bu" 4 | |
440 | The default \f(CW\*(C`untaint_pattern\*(C'\fR (see above) on Mac \s-1OS\s0 is set to | |
441 | \&\f(CW\*(C`qr|^(.+)$|\*(C'\fR. Note that the parentheses are vital. | |
442 | .IP "\(bu" 4 | |
443 | The invisible system file \*(L"Icon\e015\*(R" is ignored. While this file may | |
444 | appear in every directory, there are some more invisible system files | |
445 | on every volume, which are all located at the volume root level (i.e. | |
446 | \&\*(L"MacintoshHD:\*(R"). These system files are \fBnot\fR excluded automatically. | |
447 | Your filter may use the following code to recognize invisible files or | |
448 | directories (requires Mac::Files): | |
449 | .Sp | |
450 | .Vb 1 | |
451 | \& use Mac::Files; | |
452 | .Ve | |
453 | .Sp | |
454 | .Vb 2 | |
455 | \& # invisible() -- returns 1 if file/directory is invisible, | |
456 | \& # 0 if it's visible or undef if an error occurred | |
457 | .Ve | |
458 | .Sp | |
459 | .Vb 4 | |
460 | \& sub invisible($) { | |
461 | \& my $file = shift; | |
462 | \& my ($fileCat, $fileInfo); | |
463 | \& my $invisible_flag = 1 << 14; | |
464 | .Ve | |
465 | .Sp | |
466 | .Vb 7 | |
467 | \& if ( $fileCat = FSpGetCatInfo($file) ) { | |
468 | \& if ($fileInfo = $fileCat->ioFlFndrInfo() ) { | |
469 | \& return (($fileInfo->fdFlags & $invisible_flag) && 1); | |
470 | \& } | |
471 | \& } | |
472 | \& return undef; | |
473 | \& } | |
474 | .Ve | |
475 | .Sp | |
476 | Generally, invisible files are system files, unless an odd application | |
477 | decides to use invisible files for its own purposes. To distinguish | |
478 | such files from system files, you have to look at the \fBtype\fR and \fBcreator\fR | |
479 | file attributes. The MacPerl built-in functions \f(CW\*(C`GetFileInfo(FILE)\*(C'\fR and | |
480 | \&\f(CW\*(C`SetFileInfo(CREATOR, TYPE, FILES)\*(C'\fR offer access to these attributes | |
481 | (see MacPerl.pm for details). | |
482 | .Sp | |
483 | Files that appear on the desktop actually reside in an (hidden) directory | |
484 | named \*(L"Desktop Folder\*(R" on the particular disk volume. Note that, although | |
485 | all desktop files appear to be on the same \*(L"virtual\*(R" desktop, each disk | |
486 | volume actually maintains its own \*(L"Desktop Folder\*(R" directory. | |
487 | .RE | |
488 | .RS 4 | |
489 | .RE | |
490 | .SH "HISTORY" | |
491 | .IX Header "HISTORY" | |
492 | File::Find used to produce incorrect results if called recursively. | |
493 | During the development of perl 5.8 this bug was fixed. | |
494 | The first fixed version of File::Find was 1.01. |