This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
File::Path 2.02
[perl5.git] / lib / File / Path.pm
CommitLineData
1fc4cb55 1package File::Path;
fed7345c 2
cac619e8
DL
3use 5.005_04;
4use strict;
5
6use Cwd 'getcwd';
7use File::Basename ();
8use File::Spec ();
9
10BEGIN {
11 if ($] < 5.006) {
12 # can't say 'opendir my $dh, $dirname'
13 # need to initialise $dh
14 eval "use Symbol";
15 }
16}
17
18use Exporter ();
19use vars qw($VERSION @ISA @EXPORT);
20$VERSION = '2.02';
21@ISA = qw(Exporter);
22@EXPORT = qw(mkpath rmtree);
23
24my $Is_VMS = $^O eq 'VMS';
25my $Is_MacOS = $^O eq 'MacOS';
26
27# These OSes complain if you want to remove a file that you have no
28# write permission to:
29my $Force_Writeable = ($^O eq 'os2' || $^O eq 'dos' || $^O eq 'MSWin32' ||
30 $^O eq 'amigaos' || $^O eq 'MacOS' || $^O eq 'epoc');
31
32sub _carp {
33 require Carp;
34 goto &Carp::carp;
35}
36
37sub _croak {
38 require Carp;
39 goto &Carp::croak;
40}
41
42sub _error {
43 my $arg = shift;
44 my $message = shift;
45 my $object = shift;
46
47 if ($arg->{error}) {
48 $object = '' unless defined $object;
49 push @{${$arg->{error}}}, {$object => "$message: $!"};
50 }
51 else {
52 _carp(defined($object) ? "$message for $object: $!" : "$message: $!");
53 }
54}
55
56sub mkpath {
57 my $old_style = (
58 UNIVERSAL::isa($_[0],'ARRAY')
59 or (@_ == 2 and (defined $_[1] ? $_[1] =~ /\A\d+\z/ : 1))
60 or (@_ == 3
61 and (defined $_[1] ? $_[1] =~ /\A\d+\z/ : 1)
62 and (defined $_[2] ? $_[2] =~ /\A\d+\z/ : 1)
63 )
64 ) ? 1 : 0;
65
66 my $arg;
67 my $paths;
68
69 if ($old_style) {
70 my ($verbose, $mode);
71 ($paths, $verbose, $mode) = @_;
72 $paths = [$paths] unless UNIVERSAL::isa($paths,'ARRAY');
73 $arg->{verbose} = defined $verbose ? $verbose : 0;
74 $arg->{mode} = defined $mode ? $mode : 0777;
75 }
76 else {
77 if (@_ > 0 and UNIVERSAL::isa($_[-1], 'HASH')) {
78 $arg = pop @_;
79 exists $arg->{mask} and $arg->{mode} = delete $arg->{mask};
80 $arg->{mode} = 0777 unless exists $arg->{mode};
81 ${$arg->{error}} = [] if exists $arg->{error};
82 }
83 else {
84 @{$arg}{qw(verbose mode)} = (0, 0777);
85 }
86 $paths = [@_];
87 }
88 return _mkpath($arg, $paths);
89}
90
91sub _mkpath {
92 my $arg = shift;
93 my $paths = shift;
94
95 local($")=$Is_MacOS ? ":" : "/";
96 my(@created,$path);
97 foreach $path (@$paths) {
98 next unless length($path);
99 $path .= '/' if $^O eq 'os2' and $path =~ /^\w:\z/s; # feature of CRT
100 # Logic wants Unix paths, so go with the flow.
101 if ($Is_VMS) {
102 next if $path eq '/';
103 $path = VMS::Filespec::unixify($path);
104 }
105 next if -d $path;
106 my $parent = File::Basename::dirname($path);
107 unless (-d $parent or $path eq $parent) {
108 push(@created,_mkpath($arg, [$parent]));
109 }
110 print "mkdir $path\n" if $arg->{verbose};
111 if (mkdir($path,$arg->{mode})) {
112 push(@created, $path);
113 }
114 else {
115 my $save_bang = $!;
116 my ($e, $e1) = ($save_bang, $^E);
117 $e .= "; $e1" if $e ne $e1;
118 # allow for another process to have created it meanwhile
119 if (!-d $path) {
120 $! = $save_bang;
121 if ($arg->{error}) {
122 push @{${$arg->{error}}}, {$path => $e};
123 }
124 else {
125 _croak("mkdir $path: $e");
126 }
127 }
128 }
129 }
130 return @created;
131}
132
133sub rmtree {
134 my $old_style = (
135 UNIVERSAL::isa($_[0],'ARRAY')
136 or (@_ == 2 and (defined $_[1] ? $_[1] =~ /\A\d+\z/ : 1))
137 or (@_ == 3
138 and (defined $_[1] ? $_[1] =~ /\A\d+\z/ : 1)
139 and (defined $_[2] ? $_[2] =~ /\A\d+\z/ : 1)
140 )
141 ) ? 1 : 0;
142
143 my $arg;
144 my $paths;
145
146 if ($old_style) {
147 my ($verbose, $safe);
148 ($paths, $verbose, $safe) = @_;
149 $arg->{verbose} = defined $verbose ? $verbose : 0;
150 $arg->{safe} = defined $safe ? $safe : 0;
151
152 if (defined($paths) and length($paths)) {
153 $paths = [$paths] unless UNIVERSAL::isa($paths,'ARRAY');
154 }
155 else {
156 _carp ("No root path(s) specified\n");
157 return 0;
158 }
159 }
160 else {
161 if (@_ > 0 and UNIVERSAL::isa($_[-1],'HASH')) {
162 $arg = pop @_;
163 ${$arg->{error}} = [] if exists $arg->{error};
164 ${$arg->{result}} = [] if exists $arg->{result};
165 }
166 else {
167 @{$arg}{qw(verbose safe)} = (0, 0);
168 }
169 $paths = [@_];
170 }
171
172 $arg->{prefix} = '';
173 $arg->{depth} = 0;
174
175 $arg->{cwd} = getcwd() or do {
176 _error($arg, "cannot fetch initial working directory");
177 return 0;
178 };
179 for ($arg->{cwd}) { /\A(.*)\Z/; $_ = $1 } # untaint
180
181 @{$arg}{qw(device inode)} = (stat $arg->{cwd})[0,1] or do {
182 _error($arg, "cannot stat initial working directory", $arg->{cwd});
183 return 0;
184 };
185
186 return _rmtree($arg, $paths);
187}
188
189sub _rmtree {
190 my $arg = shift;
191 my $paths = shift;
192
193 my $count = 0;
194 my $curdir = File::Spec->curdir();
195 my $updir = File::Spec->updir();
196
197 my (@files, $root);
198 ROOT_DIR:
199 foreach $root (@$paths) {
200 if ($Is_MacOS) {
201 $root = ":$root" unless $root =~ /:/;
202 $root .= ":" unless $root =~ /:\z/;
203 }
204 else {
205 $root =~ s{/\z}{};
206 }
207
208 # since we chdir into each directory, it may not be obvious
209 # to figure out where we are if we generate a message about
210 # a file name. We therefore construct a semi-canonical
211 # filename, anchored from the directory being unlinked (as
212 # opposed to being truly canonical, anchored from the root (/).
213
214 my $canon = $arg->{prefix}
215 ? File::Spec->catfile($arg->{prefix}, $root)
216 : $root
217 ;
218
219 my ($ldev, $lino, $perm) = (lstat $root)[0,1,2] or next ROOT_DIR;
220
221 if ( -d _ ) {
222 $root = VMS::Filespec::pathify($root) if $Is_VMS;
223 if (!chdir($root)) {
224 # see if we can escalate privileges to get in
225 # (e.g. funny protection mask such as -w- instead of rwx)
226 $perm &= 07777;
227 my $nperm = $perm | 0700;
228 if (!($arg->{safe} or $nperm == $perm or chmod($nperm, $root))) {
229 _error($arg, "cannot make child directory read-write-exec", $canon);
230 next ROOT_DIR;
231 }
232 elsif (!chdir($root)) {
233 _error($arg, "cannot chdir to child", $canon);
234 next ROOT_DIR;
235 }
236 }
237
238 my ($device, $inode, $perm) = (stat $curdir)[0,1,2] or do {
239 _error($arg, "cannot stat current working directory", $canon);
240 next ROOT_DIR;
241 };
242
243 ($ldev eq $device and $lino eq $inode)
244 or _croak("directory $canon changed before chdir, expected dev=$ldev inode=$lino, actual dev=$device ino=$inode, aborting.");
245
246 $perm &= 07777; # don't forget setuid, setgid, sticky bits
247 my $nperm = $perm | 0700;
248
249 # notabene: 0700 is for making readable in the first place,
250 # it's also intended to change it to writable in case we have
251 # to recurse in which case we are better than rm -rf for
252 # subtrees with strange permissions
253
254 if (!($arg->{safe} or $nperm == $perm or chmod($nperm, $curdir))) {
255 _error($arg, "cannot make directory read+writeable", $canon);
256 $nperm = $perm;
257 }
258
259 my $d;
260 $d = gensym() if $] < 5.006;
261 if (!opendir $d, $curdir) {
262 _error($arg, "cannot opendir", $canon);
263 @files = ();
264 }
265 else {
266 no strict 'refs';
267 if (!defined ${"\cTAINT"} or ${"\cTAINT"}) {
268 # Blindly untaint dir names if taint mode is
269 # active, or any perl < 5.006
270 @files = map { /\A(.*)\z/s; $1 } readdir $d;
271 }
272 else {
273 @files = readdir $d;
274 }
275 closedir $d;
276 }
277
278 if ($Is_VMS) {
279 # Deleting large numbers of files from VMS Files-11
280 # filesystems is faster if done in reverse ASCIIbetical order.
281 # include '.' to '.;' from blead patch #31775
282 @files = map {$_ eq '.' ? '.;' : $_} reverse @files;
283 ($root = VMS::Filespec::unixify($root)) =~ s/\.dir\z//;
284 }
285 @files = grep {$_ ne $updir and $_ ne $curdir} @files;
286
287 if (@files) {
288 # remove the contained files before the directory itself
289 my $narg = {%$arg};
290 @{$narg}{qw(device inode cwd prefix depth)}
291 = ($device, $inode, $updir, $canon, $arg->{depth}+1);
292 $count += _rmtree($narg, \@files);
293 }
294
295 # restore directory permissions of required now (in case the rmdir
296 # below fails), while we are still in the directory and may do so
297 # without a race via '.'
298 if ($nperm != $perm and not chmod($perm, $curdir)) {
299 _error($arg, "cannot reset chmod", $canon);
300 }
301
302 # don't leave the client code in an unexpected directory
303 chdir($arg->{cwd})
304 or _croak("cannot chdir to $arg->{cwd} from $canon: $!, aborting.");
305
306 # ensure that a chdir upwards didn't take us somewhere other
307 # than we expected (see CVE-2002-0435)
308 ($device, $inode) = (stat $curdir)[0,1]
309 or _croak("cannot stat prior working directory $arg->{cwd}: $!, aborting.");
310
311 ($arg->{device} eq $device and $arg->{inode} eq $inode)
312 or _croak("previous directory $arg->{cwd} changed before entering $canon, expected dev=$ldev inode=$lino, actual dev=$device ino=$inode, aborting.");
313
314 if ($arg->{depth} or !$arg->{keep_root}) {
315 if ($arg->{safe} &&
316 ($Is_VMS ? !&VMS::Filespec::candelete($root) : !-w $root)) {
317 print "skipped $root\n" if $arg->{verbose};
318 next ROOT_DIR;
319 }
320 if (!chmod $perm | 0700, $root) {
321 if ($Force_Writeable) {
322 _error($arg, "cannot make directory writeable", $canon);
323 }
324 }
325 print "rmdir $root\n" if $arg->{verbose};
326 if (rmdir $root) {
327 push @{${$arg->{result}}}, $root if $arg->{result};
328 ++$count;
329 }
330 else {
331 _error($arg, "cannot remove directory", $canon);
332 if (!chmod($perm, ($Is_VMS ? VMS::Filespec::fileify($root) : $root))
333 ) {
334 _error($arg, sprintf("cannot restore permissions to 0%o",$perm), $canon);
335 }
336 }
337 }
338 }
339 else {
340 # not a directory
341
342 $root = VMS::Filespec::vmsify("./$root")
343 if $Is_VMS && !File::Spec->file_name_is_absolute($root);
344
345 if ($arg->{safe} &&
346 ($Is_VMS ? !&VMS::Filespec::candelete($root)
347 : !(-l $root || -w $root)))
348 {
349 print "skipped $root\n" if $arg->{verbose};
350 next ROOT_DIR;
351 }
352
353 my $nperm = $perm & 07777 | 0600;
354 if ($nperm != $perm and not chmod $nperm, $root) {
355 if ($Force_Writeable) {
356 _error($arg, "cannot make file writeable", $canon);
357 }
358 }
359 print "unlink $canon\n" if $arg->{verbose};
360 # delete all versions under VMS
361 for (;;) {
362 if (unlink $root) {
363 push @{${$arg->{result}}}, $root if $arg->{result};
364 }
365 else {
366 _error($arg, "cannot unlink file", $canon);
367 $Force_Writeable and chmod($perm, $root) or
368 _error($arg, sprintf("cannot restore permissions to 0%o",$perm), $canon);
369 last;
370 }
371 ++$count;
372 last unless $Is_VMS && lstat $root;
373 }
374 }
375 }
376
377 return $count;
378}
379
3801;
381__END__
382
fed7345c
AD
383=head1 NAME
384
12c2e016
DL
385File::Path - Create or remove directory trees
386
387=head1 VERSION
388
cac619e8
DL
389This document describes version 2.02 of File::Path, released
3902007-10-24.
fed7345c
AD
391
392=head1 SYNOPSIS
393
8b87c192 394 use File::Path;
fed7345c 395
12c2e016
DL
396 # modern
397 mkpath( 'foo/bar/baz', '/zug/zwang', {verbose => 1} );
398
399 rmtree(
400 'foo/bar/baz', '/zug/zwang',
91c4f65e 401 { verbose => 1, error => \my $err_list }
12c2e016
DL
402 );
403
404 # traditional
8b87c192
GS
405 mkpath(['/foo/bar/baz', 'blurfl/quux'], 1, 0711);
406 rmtree(['foo/bar/baz', 'blurfl/quux'], 1, 1);
fed7345c
AD
407
408=head1 DESCRIPTION
409
0b3d36bd
DL
410The C<mkpath> function provides a convenient way to create directories
411of arbitrary depth. Similarly, the C<rmtree> function provides a
412convenient way to delete an entire directory subtree from the
413filesystem, much like the Unix command C<rm -r>.
12c2e016
DL
414
415Both functions may be called in one of two ways, the traditional,
416compatible with code written since the dawn of time, and modern,
417that offers a more flexible and readable idiom. New code should use
418the modern interface.
419
420=head2 FUNCTIONS
421
0b3d36bd
DL
422The modern way of calling C<mkpath> and C<rmtree> is with a list
423of directories to create, or remove, respectively, followed by an
424optional hash reference containing keys to control the
425function's behaviour.
12c2e016
DL
426
427=head3 C<mkpath>
428
0b3d36bd
DL
429The following keys are recognised as parameters to C<mkpath>.
430The function returns the list of files actually created during the
431call.
12c2e016
DL
432
433 my @created = mkpath(
434 qw(/tmp /flub /home/nobody),
435 {verbose => 1, mode => 0750},
436 );
437 print "created $_\n" for @created;
438
439=over 4
440
441=item mode
442
0b3d36bd
DL
443The numeric permissions mode to apply to each created directory
444(defaults to 0777), to be modified by the current C<umask>. If the
445directory already exists (and thus does not need to be created),
446the permissions will not be modified.
447
448C<mask> is recognised as an alias for this parameter.
12c2e016
DL
449
450=item verbose
451
452If present, will cause C<mkpath> to print the name of each directory
453as it is created. By default nothing is printed.
454
455=item error
456
457If present, will be interpreted as a reference to a list, and will
458be used to store any errors that are encountered. See the ERROR
0b3d36bd 459HANDLING section for more information.
12c2e016 460
0b3d36bd
DL
461If this parameter is not used, certain error conditions may raise
462a fatal error that will cause the program will halt, unless trapped
463in an C<eval> block.
12c2e016
DL
464
465=back
466
467=head3 C<rmtree>
468
469=over 4
470
471=item verbose
472
473If present, will cause C<rmtree> to print the name of each file as
474it is unlinked. By default nothing is printed.
475
5808899a 476=item safe
12c2e016 477
0b3d36bd
DL
478When set to a true value, will cause C<rmtree> to skip the files
479for which the process lacks the required privileges needed to delete
5808899a
DL
480files, such as delete privileges on VMS. In other words, the code
481will make no attempt to alter file permissions. Thus, if the process
482is interrupted, no filesystem object will be left in a more
483permissive mode.
12c2e016
DL
484
485=item keep_root
486
0b3d36bd
DL
487When set to a true value, will cause all files and subdirectories
488to be removed, except the initially specified directories. This comes
489in handy when cleaning out an application's scratch directory.
12c2e016
DL
490
491 rmtree( '/tmp', {keep_root => 1} );
492
493=item result
494
495If present, will be interpreted as a reference to a list, and will
496be used to store the list of all files and directories unlinked
497during the call. If nothing is unlinked, a reference to an empty
498list is returned (rather than C<undef>).
499
500 rmtree( '/tmp', {result => \my $list} );
501 print "unlinked $_\n" for @$list;
502
0b3d36bd
DL
503This is a useful alternative to the C<verbose> key.
504
12c2e016
DL
505=item error
506
507If present, will be interpreted as a reference to a list,
508and will be used to store any errors that are encountered.
0b3d36bd 509See the ERROR HANDLING section for more information.
12c2e016 510
0b3d36bd
DL
511Removing things is a much more dangerous proposition than
512creating things. As such, there are certain conditions that
513C<rmtree> may encounter that are so dangerous that the only
514sane action left is to kill the program.
515
516Use C<error> to trap all that is reasonable (problems with
517permissions and the like), and let it die if things get out
518of hand. This is the safest course of action.
12c2e016
DL
519
520=back
521
522=head2 TRADITIONAL INTERFACE
523
0b3d36bd
DL
524The old interfaces of C<mkpath> and C<rmtree> take a reference to
525a list of directories (to create or remove), followed by a series
526of positional, numeric, modal parameters that control their behaviour.
527
528This design made it difficult to add additional functionality, as
529well as posed the problem of what to do when the calling code only
530needs to set the last parameter. Even though the code doesn't care
531how the initial positional parameters are set, the programmer is
532forced to learn what the defaults are, and specify them.
12c2e016 533
0b3d36bd
DL
534Worse, if it turns out in the future that it would make more sense
535to change the default behaviour of the first parameter (for example,
536to avoid a security vulnerability), all existing code will remain
537hard-wired to the wrong defaults.
12c2e016 538
0b3d36bd
DL
539Finally, a series of numeric parameters are much less self-documenting
540in terms of communicating to the reader what the code is doing. Named
541parameters do not have this problem.
542
543In the traditional API, C<mkpath> takes three arguments:
fed7345c
AD
544
545=over 4
546
547=item *
548
0b3d36bd
DL
549The name of the path to create, or a reference to a list of paths
550to create,
fed7345c
AD
551
552=item *
553
0b3d36bd
DL
554a boolean value, which if TRUE will cause C<mkpath> to print the
555name of each directory as it is created (defaults to FALSE), and
fed7345c
AD
556
557=item *
558
0b3d36bd
DL
559the numeric mode to use when creating the directories (defaults to
5600777), to be modified by the current umask.
fed7345c
AD
561
562=back
563
037c8c09 564It returns a list of all directories (including intermediates, determined
cc61921f
GA
565using the Unix '/' separator) created. In scalar context it returns
566the number of directories created.
fed7345c 567
070ed461 568If a system error prevents a directory from being created, then the
99c4c5e8
AMS
569C<mkpath> function throws a fatal error with C<Carp::croak>. This error
570can be trapped with an C<eval> block:
070ed461
CM
571
572 eval { mkpath($dir) };
573 if ($@) {
574 print "Couldn't create $dir: $@";
575 }
576
0b3d36bd 577In the traditional API, C<rmtree> takes three arguments:
fed7345c
AD
578
579=over 4
580
581=item *
582
0b3d36bd
DL
583the root of the subtree to delete, or a reference to a list of
584roots. All of the files and directories below each root, as well
585as the roots themselves, will be deleted. If you want to keep
586the roots themselves, you must use the modern API.
fed7345c
AD
587
588=item *
589
0b3d36bd
DL
590a boolean value, which if TRUE will cause C<rmtree> to print a
591message each time it examines a file, giving the name of the file,
592and indicating whether it's using C<rmdir> or C<unlink> to remove
593it, or that it's skipping it. (defaults to FALSE)
fed7345c
AD
594
595=item *
596
0b3d36bd
DL
597a boolean value, which if TRUE will cause C<rmtree> to skip any
598files to which you do not have delete access (if running under VMS)
599or write access (if running under another OS). This will change
600in the future when a criterion for 'delete permission' under OSs
601other than VMS is settled. (defaults to FALSE)
fed7345c
AD
602
603=back
604
cc61921f
GA
605It returns the number of files, directories and symlinks successfully
606deleted. Symlinks are simply deleted and not followed.
fed7345c 607
12c2e016
DL
608Note also that the occurrence of errors in C<rmtree> using the
609traditional interface can be determined I<only> by trapping diagnostic
610messages using C<$SIG{__WARN__}>; it is not apparent from the return
611value. (The modern interface may use the C<error> parameter to
0b3d36bd 612record any problems encountered).
12c2e016
DL
613
614=head2 ERROR HANDLING
615
616If C<mkpath> or C<rmtree> encounter an error, a diagnostic message
617will be printed to C<STDERR> via C<carp> (for non-fatal errors),
618or via C<croak> (for fatal errors).
619
620If this behaviour is not desirable, the C<error> attribute may be
621used to hold a reference to a variable, which will be used to store
622the diagnostics. The result is a reference to a list of hash
623references. For each hash reference, the key is the name of the
624file, and the value is the error message (usually the contents of
625C<$!>). An example usage looks like:
626
627 rmpath( 'foo/bar', 'bar/rat', {error => \my $err} );
628 for my $diag (@$err) {
629 my ($file, $message) = each %$diag;
630 print "problem unlinking $file: $message\n";
631 }
632
633If no errors are encountered, C<$err> will point to an empty list
634(thus there is no need to test for C<undef>). If a general error
635is encountered (for instance, C<rmtree> attempts to remove a directory
636tree that does not exist), the diagnostic key will be empty, only
637the value will be set:
638
639 rmpath( '/no/such/path', {error => \my $err} );
640 for my $diag (@$err) {
641 my ($file, $message) = each %$diag;
642 if ($file eq '') {
643 print "general error: $message\n";
644 }
645 }
646
647=head2 NOTES
648
0b3d36bd
DL
649C<File::Path> blindly exports C<mkpath> and C<rmtree> into the
650current namespace. These days, this is considered bad style, but
651to change it now would break too much code. Nonetheless, you are
652invited to specify what it is you are expecting to use:
653
654 use File::Path 'rmtree';
655
12c2e016
DL
656=head3 HEURISTICS
657
658The functions detect (as far as possible) which way they are being
659called and will act appropriately. It is important to remember that
660the heuristic for detecting the old style is either the presence
661of an array reference, or two or three parameters total and second
662and third parameters are numeric. Hence...
663
0b3d36bd 664 mkpath 486, 487, 488;
12c2e016
DL
665
666... will not assume the modern style and create three directories, rather
667it will create one directory verbosely, setting the permission to
6680750 (488 being the decimal equivalent of octal 750). Here, old
669style trumps new. It must, for backwards compatibility reasons.
e2ba98a1 670
12c2e016
DL
671If you want to ensure there is absolutely no ambiguity about which
672way the function will behave, make sure the first parameter is a
673reference to a one-element list, to force the old style interpretation:
e2ba98a1 674
0b3d36bd 675 mkpath [486], 487, 488;
12c2e016
DL
676
677and get only one directory created. Or add a reference to an empty
678parameter hash, to force the new style:
679
0b3d36bd 680 mkpath 486, 487, 488, {};
12c2e016
DL
681
682... and hence create the three directories. If the empty hash
683reference seems a little strange to your eyes, or you suspect a
684subsequent programmer might I<helpfully> optimise it away, you
685can add a parameter set to a default value:
686
0b3d36bd 687 mkpath 486, 487, 488, {verbose => 0};
12c2e016 688
0b3d36bd 689=head3 SECURITY CONSIDERATIONS
12c2e016 690
0b3d36bd
DL
691There were race conditions 1.x implementations of File::Path's
692C<rmtree> function (although sometimes patched depending on the OS
693distribution or platform). The 2.0 version contains code to avoid the
694problem mentioned in CVE-2002-0435.
12c2e016 695
0b3d36bd 696See the following pages for more information:
12c2e016 697
0b3d36bd
DL
698 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=286905
699 http://www.nntp.perl.org/group/perl.perl5.porters/2005/01/msg97623.html
700 http://www.debian.org/security/2005/dsa-696
12c2e016 701
5808899a 702Additionally, unless the C<safe> parameter is set (or the
37b1cd44 703third parameter in the traditional interface is TRUE), should a
0b3d36bd
DL
704C<rmtree> be interrupted, files that were originally in read-only
705mode may now have their permissions set to a read-write (or "delete
706OK") mode.
96e4d5b1 707
b8d5f521
CW
708=head1 DIAGNOSTICS
709
0b3d36bd
DL
710FATAL errors will cause the program to halt (C<croak>), since the
711problem is so severe that it would be dangerous to continue. (This
712can always be trapped with C<eval>, but it's not a good idea. Under
713the circumstances, dying is the best thing to do).
714
715SEVERE errors may be trapped using the modern interface. If the
716they are not trapped, or the old interface is used, such an error
717will cause the program will halt.
718
719All other errors may be trapped using the modern interface, otherwise
720they will be C<carp>ed about. Program execution will not be halted.
721
b8d5f521
CW
722=over 4
723
37b1cd44 724=item mkdir [path]: [errmsg] (SEVERE)
0b3d36bd
DL
725
726C<mkpath> was unable to create the path. Probably some sort of
727permissions error at the point of departure, or insufficient resources
728(such as free inodes on Unix).
729
730=item No root path(s) specified
731
732C<mkpath> was not given any paths to create. This message is only
733emitted if the routine is called with the traditional interface.
734The modern interface will remain silent if given nothing to do.
735
736=item No such file or directory
737
738On Windows, if C<mkpath> gives you this warning, it may mean that
739you have exceeded your filesystem's maximum path length.
740
741=item cannot fetch initial working directory: [errmsg]
742
743C<rmtree> attempted to determine the initial directory by calling
744C<Cwd::getcwd>, but the call failed for some reason. No attempt
745will be made to delete anything.
746
747=item cannot stat initial working directory: [errmsg]
748
749C<rmtree> attempted to stat the initial directory (after having
750successfully obtained its name via C<getcwd>), however, the call
751failed for some reason. No attempt will be made to delete anything.
752
753=item cannot chdir to [dir]: [errmsg]
754
755C<rmtree> attempted to set the working directory in order to
756begin deleting the objects therein, but was unsuccessful. This is
757usually a permissions issue. The routine will continue to delete
758other things, but this directory will be left intact.
759
760=item directory [dir] changed before chdir, expected dev=[n] inode=[n], actual dev=[n] ino=[n], aborting. (FATAL)
761
762C<rmtree> recorded the device and inode of a directory, and then
763moved into it. It then performed a C<stat> on the current directory
764and detected that the device and inode were no longer the same. As
765this is at the heart of the race condition problem, the program
766will die at this point.
767
768=item cannot make directory [dir] read+writeable: [errmsg]
769
770C<rmtree> attempted to change the permissions on the current directory
771to ensure that subsequent unlinkings would not run into problems,
772but was unable to do so. The permissions remain as they were, and
773the program will carry on, doing the best it can.
774
775=item cannot read [dir]: [errmsg]
776
777C<rmtree> tried to read the contents of the directory in order
778to acquire the names of the directory entries to be unlinked, but
779was unsuccessful. This is usually a permissions issue. The
780program will continue, but the files in this directory will remain
781after the call.
782
783=item cannot reset chmod [dir]: [errmsg]
784
cac619e8
DL
785C<rmtree>, after having deleted everything in a directory, attempted
786to restore its permissions to the original state but failed. The
787directory may wind up being left behind.
12c2e016 788
cac619e8 789=item cannot chdir to [parent-dir] from [child-dir]: [errmsg], aborting. (FATAL)
12c2e016 790
cac619e8
DL
791C<rmtree>, after having deleted everything and restored the permissions
792of a directory, was unable to chdir back to the parent. This is usually
793a sign that something evil this way comes.
fed7345c 794
cac619e8 795=item cannot stat prior working directory [dir]: [errmsg], aborting. (FATAL)
0b3d36bd 796
cac619e8
DL
797C<rmtree> was unable to stat the parent directory after have returned
798from the child. Since there is no way of knowing if we returned to
799where we think we should be (by comparing device and inode) the only
800way out is to C<croak>.
0b3d36bd 801
cac619e8 802=item previous directory [parent-dir] changed before entering [child-dir], expected dev=[n] inode=[n], actual dev=[n] ino=[n], aborting. (FATAL)
0b3d36bd 803
cac619e8
DL
804When C<rmtree> returned from deleting files in a child directory, a
805check revealed that the parent directory it returned to wasn't the one
806it started out from. This is considered a sign of malicious activity.
0b3d36bd 807
cac619e8 808=item cannot make directory [dir] writeable: [errmsg]
ee79a11f 809
cac619e8
DL
810Just before removing a directory (after having successfully removed
811everything it contained), C<rmtree> attempted to set the permissions
812on the directory to ensure it could be removed and failed. Program
813execution continues, but the directory may possibly not be deleted.
0b3d36bd 814
cac619e8 815=item cannot remove directory [dir]: [errmsg]
0b3d36bd 816
cac619e8
DL
817C<rmtree> attempted to remove a directory, but failed. This may because
818some objects that were unable to be removed remain in the directory, or
819a permissions issue. The directory will be left behind.
0b3d36bd 820
cac619e8 821=item cannot restore permissions of [dir] to [0nnn]: [errmsg]
0b3d36bd 822
cac619e8
DL
823After having failed to remove a directory, C<rmtree> was unable to
824restore its permissions from a permissive state back to a possibly
825more restrictive setting. (Permissions given in octal).
0b3d36bd 826
cac619e8 827=item cannot make file [file] writeable: [errmsg]
b5400373 828
cac619e8
DL
829C<rmtree> attempted to force the permissions of a file to ensure it
830could be deleted, but failed to do so. It will, however, still attempt
831to unlink the file.
0b3d36bd 832
cac619e8 833=item cannot unlink file [file]: [errmsg]
0b3d36bd 834
cac619e8 835C<rmtree> failed to remove a file. Probably a permissions issue.
0b3d36bd 836
cac619e8 837=item cannot restore permissions of [file] to [0nnn]: [errmsg]
0b3d36bd 838
cac619e8
DL
839After having failed to remove a file, C<rmtree> was also unable
840to restore the permissions on the file to a possibly less permissive
841setting. (Permissions given in octal).
0b3d36bd 842
cac619e8 843=back
12c2e016 844
cac619e8 845=head1 SEE ALSO
037c8c09 846
cac619e8 847=over 4
0b3d36bd 848
cac619e8 849=item *
0b3d36bd 850
cac619e8 851L<File::Find::Rule>
0b3d36bd 852
cac619e8
DL
853When removing directory trees, if you want to examine each file to
854decide whether to delete it (and possibly leaving large swathes
855alone), F<File::Find::Rule> offers a convenient and flexible approach
856to examining directory trees.
0b3d36bd 857
cac619e8 858=back
0b3d36bd 859
cac619e8 860=head1 BUGS
0b3d36bd 861
cac619e8 862Please report all bugs on the RT queue:
b5400373 863
cac619e8 864L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-Path>
b5400373 865
cac619e8 866=head1 ACKNOWLEDGEMENTS
0b3d36bd 867
cac619e8
DL
868Paul Szabo identified the race condition originally, and Brendan
869O'Dea wrote an implementation for Debian that addressed the problem.
870That code was used as a basis for the current code. Their efforts
871are greatly appreciated.
fed7345c 872
cac619e8 873=head1 AUTHORS
fed7345c 874
cac619e8
DL
875Tim Bunce <F<Tim.Bunce@ig.co.uk>> and Charles Bailey
876<F<bailey@newman.upenn.edu>>. Currently maintained by David Landgren
877<F<david@landgren.net>>.
878
879=head1 COPYRIGHT
880
881This module is copyright (C) Charles Bailey, Tim Bunce and
882David Landgren 1995-2007. All rights reserved.
883
884=head1 LICENSE
885
886This library is free software; you can redistribute it and/or modify
887it under the same terms as Perl itself.
888
889=cut