This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
avoid initializing GvCV slot for autovivified filehandles
[perl5.git] / lib / File / Find.pm
CommitLineData
a0d0e21e
LW
1package File::Find;
2require 5.000;
3require Exporter;
6280b799 4require Cwd;
a0d0e21e 5
f06db76b
AD
6=head1 NAME
7
8find - traverse a file tree
9
10finddepth - traverse a directory structure depth-first
11
12=head1 SYNOPSIS
13
14 use File::Find;
15 find(\&wanted, '/foo','/bar');
16 sub wanted { ... }
237437d0 17
f06db76b
AD
18 use File::Find;
19 finddepth(\&wanted, '/foo','/bar');
20 sub wanted { ... }
21
22=head1 DESCRIPTION
23
20408e3c 24The first argument to find() is either a hash reference describing the
98793e5e
GS
25operations to be performed for each file, a code reference, or a string
26that contains a subroutine name. If it is a hash reference, then the
27value for the key C<wanted> should be a code reference. This code
28reference is called I<the wanted() function> below.
20408e3c
GS
29
30Currently the only other supported key for the above hash is
31C<bydepth>, in presense of which the walk over directories is
32performed depth-first. Entry point finddepth() is a shortcut for
33specifying C<{ bydepth => 1}> in the first argument of find().
34
6280b799
PP
35The wanted() function does whatever verifications you want.
36$File::Find::dir contains the current directory name, and $_ the
37current filename within that directory. $File::Find::name contains
38C<"$File::Find::dir/$_">. You are chdir()'d to $File::Find::dir when
39the function is called. The function may set $File::Find::prune to
40prune the tree.
f06db76b 41
47a735e8
MDLR
42File::Find assumes that you don't alter the $_ variable. If you do then
43make sure you return it to its original value before exiting your function.
44
20408e3c 45This library is useful for the C<find2perl> tool, which when fed,
f06db76b
AD
46
47 find2perl / -name .nfs\* -mtime +7 \
48 -exec rm -f {} \; -o -fstype nfs -prune
49
50produces something like:
51
52 sub wanted {
53 /^\.nfs.*$/ &&
54 (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_)) &&
55 int(-M _) > 7 &&
56 unlink($_)
57 ||
58 ($nlink || (($dev,$ino,$mode,$nlink,$uid,$gid) = lstat($_))) &&
59 $dev < 0 &&
6280b799 60 ($File::Find::prune = 1);
f06db76b
AD
61 }
62
6280b799
PP
63Set the variable $File::Find::dont_use_nlink if you're using AFS,
64since AFS cheats.
f06db76b
AD
65
66C<finddepth> is just like C<find>, except that it does a depth-first
67search.
68
69Here's another interesting wanted function. It will find all symlinks
70that don't resolve:
71
72 sub wanted {
6280b799 73 -l && !-e && print "bogus link: $File::Find::name\n";
237437d0 74 }
f06db76b 75
0530a6c4
GW
76=head1 BUGS
77
78There is no way to make find or finddepth follow symlinks.
79
f06db76b
AD
80=cut
81
a0d0e21e 82@ISA = qw(Exporter);
6280b799
PP
83@EXPORT = qw(find finddepth);
84
a0d0e21e 85
20408e3c 86sub find_opt {
a0d0e21e 87 my $wanted = shift;
20408e3c
GS
88 my $bydepth = $wanted->{bydepth};
89 my $cwd = $bydepth ? Cwd::fastcwd() : Cwd::cwd();
28312d68
RS
90 # Localize these rather than lexicalizing them for backwards
91 # compatibility.
92 local($topdir,$topdev,$topino,$topmode,$topnlink);
a0d0e21e 93 foreach $topdir (@_) {
d0e28714
CK
94 (($topdev,$topino,$topmode,$topnlink) =
95 ($Is_VMS ? stat($topdir) : lstat($topdir)))
a0d0e21e
LW
96 || (warn("Can't stat $topdir: $!\n"), next);
97 if (-d _) {
98 if (chdir($topdir)) {
d0e28714 99 $prune = 0;
20408e3c
GS
100 unless ($bydepth) {
101 ($dir,$_) = ($topdir,'.');
102 $name = $topdir;
103 $wanted->{wanted}->();
104 }
237437d0
CK
105 next if $prune;
106 my $fixtopdir = $topdir;
107 $fixtopdir =~ s,/$,, ;
108 $fixtopdir =~ s/\.dir$// if $Is_VMS;
20408e3c
GS
109 &finddir($wanted,$fixtopdir,$topnlink, $bydepth);
110 if ($bydepth) {
111 ($dir,$_) = ($fixtopdir,'.');
112 $name = $fixtopdir;
113 $wanted->{wanted}->();
114 }
a0d0e21e
LW
115 }
116 else {
117 warn "Can't cd to $topdir: $!\n";
118 }
119 }
120 else {
20408e3c 121 require File::Basename;
9f637d3d 122 unless (($_,$dir) = File::Basename::fileparse($topdir)) {
a0d0e21e
LW
123 ($dir,$_) = ('.', $topdir);
124 }
237437d0
CK
125 if (chdir($dir)) {
126 $name = $topdir;
20408e3c 127 $wanted->{wanted}->();
237437d0
CK
128 }
129 else {
130 warn "Can't cd to $dir: $!\n";
131 }
a0d0e21e 132 }
17b275ff
RA
133 }
134 continue {
a0d0e21e
LW
135 chdir $cwd;
136 }
137}
138
139sub finddir {
20408e3c 140 my($wanted, $nlink, $bydepth);
6280b799 141 local($dir, $name);
20408e3c 142 ($wanted, $dir, $nlink, $bydepth) = @_;
a0d0e21e 143
6280b799 144 my($dev, $ino, $mode, $subcount);
a0d0e21e 145
6280b799 146 # Get the list of files in the current directory.
20408e3c 147 opendir(DIR,'.') || (warn("Can't open $dir: $!\n"), $bydepth || return);
6280b799 148 my(@filenames) = readdir(DIR);
a0d0e21e
LW
149 closedir(DIR);
150
151 if ($nlink == 2 && !$dont_use_nlink) { # This dir has no subdirectories.
152 for (@filenames) {
153 next if $_ eq '.';
154 next if $_ eq '..';
155 $name = "$dir/$_";
156 $nlink = 0;
20408e3c 157 $wanted->{wanted}->();
a0d0e21e
LW
158 }
159 }
237437d0 160 else { # This dir has subdirectories.
a0d0e21e
LW
161 $subcount = $nlink - 2;
162 for (@filenames) {
163 next if $_ eq '.';
164 next if $_ eq '..';
20408e3c
GS
165 $nlink = 0;
166 $prune = 0 unless $bydepth;
a0d0e21e 167 $name = "$dir/$_";
20408e3c 168 $wanted->{wanted}->() unless $bydepth;
a0d0e21e
LW
169 if ($subcount > 0 || $dont_use_nlink) { # Seen all the subdirs?
170
171 # Get link count and check for directoriness.
172
2f0242eb 173 $_ = "" if (!defined($_));
10eba763
PP
174 ($dev,$ino,$mode,$nlink) = ($Is_VMS ? stat($_) : lstat($_));
175 # unless ($nlink || $dont_use_nlink);
237437d0 176
a0d0e21e
LW
177 if (-d _) {
178
179 # It really is a directory, so do it recursively.
180
237437d0
CK
181 --$subcount;
182 next if $prune;
183 if (chdir $_) {
748a9306 184 $name =~ s/\.dir$// if $Is_VMS;
20408e3c 185 &finddir($wanted,$name,$nlink, $bydepth);
a0d0e21e
LW
186 chdir '..';
187 }
237437d0
CK
188 else {
189 warn "Can't cd to $_: $!\n";
190 }
a0d0e21e
LW
191 }
192 }
20408e3c 193 $wanted->{wanted}->() if $bydepth;
a0d0e21e
LW
194 }
195 }
196}
197
20408e3c
GS
198sub wrap_wanted {
199 my $wanted = shift;
98793e5e 200 ref($wanted) eq 'HASH' ? $wanted : { wanted => $wanted };
a0d0e21e
LW
201}
202
20408e3c
GS
203sub find {
204 my $wanted = shift;
205 find_opt(wrap_wanted($wanted), @_);
a0d0e21e
LW
206}
207
55d729e4 208sub finddepth {
20408e3c
GS
209 my $wanted = wrap_wanted(shift);
210 $wanted->{bydepth} = 1;
211 find_opt($wanted, @_);
212}
6280b799
PP
213
214# These are hard-coded for now, but may move to hint files.
10eba763 215if ($^O eq 'VMS') {
748a9306
LW
216 $Is_VMS = 1;
217 $dont_use_nlink = 1;
218}
219
55497cff 220$dont_use_nlink = 1
3e8584ad 221 if $^O eq 'os2' || $^O eq 'dos' || $^O eq 'amigaos' || $^O eq 'MSWin32';
6280b799 222
20408e3c
GS
223# Set dont_use_nlink in your hint file if your system's stat doesn't
224# report the number of links in a directory as an indication
225# of the number of files.
226# See, e.g. hints/machten.sh for MachTen 2.2.
227unless ($dont_use_nlink) {
228 require Config;
229 $dont_use_nlink = 1 if ($Config::Config{'dont_use_nlink'});
230}
231
a0d0e21e
LW
2321;
233