| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "File::Path 3perl" |
| 58 |
.TH File::Path 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
File::Path \- Create or remove directory trees |
| 65 |
.SH VERSION |
| 66 |
.IX Header "VERSION" |
| 67 |
2.18 \- released November 4 2020. |
| 68 |
.SH SYNOPSIS |
| 69 |
.IX Header "SYNOPSIS" |
| 70 |
.Vb 1 |
| 71 |
\& use File::Path qw(make_path remove_tree); |
| 72 |
\& |
| 73 |
\& @created = make_path(\*(Aqfoo/bar/baz\*(Aq, \*(Aq/zug/zwang\*(Aq); |
| 74 |
\& @created = make_path(\*(Aqfoo/bar/baz\*(Aq, \*(Aq/zug/zwang\*(Aq, { |
| 75 |
\& verbose => 1, |
| 76 |
\& mode => 0711, |
| 77 |
\& }); |
| 78 |
\& make_path(\*(Aqfoo/bar/baz\*(Aq, \*(Aq/zug/zwang\*(Aq, { |
| 79 |
\& chmod => 0777, |
| 80 |
\& }); |
| 81 |
\& |
| 82 |
\& $removed_count = remove_tree(\*(Aqfoo/bar/baz\*(Aq, \*(Aq/zug/zwang\*(Aq, { |
| 83 |
\& verbose => 1, |
| 84 |
\& error => \emy $err_list, |
| 85 |
\& safe => 1, |
| 86 |
\& }); |
| 87 |
\& |
| 88 |
\& # legacy (interface promoted before v2.00) |
| 89 |
\& @created = mkpath(\*(Aq/foo/bar/baz\*(Aq); |
| 90 |
\& @created = mkpath(\*(Aq/foo/bar/baz\*(Aq, 1, 0711); |
| 91 |
\& @created = mkpath([\*(Aq/foo/bar/baz\*(Aq, \*(Aqblurfl/quux\*(Aq], 1, 0711); |
| 92 |
\& $removed_count = rmtree(\*(Aqfoo/bar/baz\*(Aq, 1, 1); |
| 93 |
\& $removed_count = rmtree([\*(Aqfoo/bar/baz\*(Aq, \*(Aqblurfl/quux\*(Aq], 1, 1); |
| 94 |
\& |
| 95 |
\& # legacy (interface promoted before v2.06) |
| 96 |
\& @created = mkpath(\*(Aqfoo/bar/baz\*(Aq, \*(Aq/zug/zwang\*(Aq, { verbose => 1, mode => 0711 }); |
| 97 |
\& $removed_count = rmtree(\*(Aqfoo/bar/baz\*(Aq, \*(Aq/zug/zwang\*(Aq, { verbose => 1, mode => 0711 }); |
| 98 |
.Ve |
| 99 |
.SH DESCRIPTION |
| 100 |
.IX Header "DESCRIPTION" |
| 101 |
This module provides a convenient way to create directories of |
| 102 |
arbitrary depth and to delete an entire directory subtree from the |
| 103 |
filesystem. |
| 104 |
.PP |
| 105 |
The following functions are provided: |
| 106 |
.ie n .IP "make_path( $dir1, $dir2, .... )" 4 |
| 107 |
.el .IP "make_path( \f(CW$dir1\fR, \f(CW$dir2\fR, .... )" 4 |
| 108 |
.IX Item "make_path( $dir1, $dir2, .... )" |
| 109 |
.PD 0 |
| 110 |
.ie n .IP "make_path( $dir1, $dir2, ...., \e%opts )" 4 |
| 111 |
.el .IP "make_path( \f(CW$dir1\fR, \f(CW$dir2\fR, ...., \e%opts )" 4 |
| 112 |
.IX Item "make_path( $dir1, $dir2, ...., %opts )" |
| 113 |
.PD |
| 114 |
The \f(CW\*(C`make_path\*(C'\fR function creates the given directories if they don't |
| 115 |
exist before, much like the Unix command \f(CW\*(C`mkdir \-p\*(C'\fR. |
| 116 |
.Sp |
| 117 |
The function accepts a list of directories to be created. Its |
| 118 |
behaviour may be tuned by an optional hashref appearing as the last |
| 119 |
parameter on the call. |
| 120 |
.Sp |
| 121 |
The function returns the list of directories actually created during |
| 122 |
the call; in scalar context the number of directories created. |
| 123 |
.Sp |
| 124 |
The following keys are recognised in the option hash: |
| 125 |
.RS 4 |
| 126 |
.ie n .IP "mode => $num" 4 |
| 127 |
.el .IP "mode => \f(CW$num\fR" 4 |
| 128 |
.IX Item "mode => $num" |
| 129 |
The numeric permissions mode to apply to each created directory |
| 130 |
(defaults to \f(CW0777\fR), to be modified by the current \f(CW\*(C`umask\*(C'\fR. If the |
| 131 |
directory already exists (and thus does not need to be created), |
| 132 |
the permissions will not be modified. |
| 133 |
.Sp |
| 134 |
\&\f(CW\*(C`mask\*(C'\fR is recognised as an alias for this parameter. |
| 135 |
.ie n .IP "chmod => $num" 4 |
| 136 |
.el .IP "chmod => \f(CW$num\fR" 4 |
| 137 |
.IX Item "chmod => $num" |
| 138 |
Takes a numeric mode to apply to each created directory (not |
| 139 |
modified by the current \f(CW\*(C`umask\*(C'\fR). If the directory already exists |
| 140 |
(and thus does not need to be created), the permissions will |
| 141 |
not be modified. |
| 142 |
.ie n .IP "verbose => $bool" 4 |
| 143 |
.el .IP "verbose => \f(CW$bool\fR" 4 |
| 144 |
.IX Item "verbose => $bool" |
| 145 |
If present, will cause \f(CW\*(C`make_path\*(C'\fR to print the name of each directory |
| 146 |
as it is created. By default nothing is printed. |
| 147 |
.IP "error => \e$err" 4 |
| 148 |
.IX Item "error => $err" |
| 149 |
If present, it should be a reference to a scalar. |
| 150 |
This scalar will be made to reference an array, which will |
| 151 |
be used to store any errors that are encountered. See the "ERROR |
| 152 |
HANDLING" section for more information. |
| 153 |
.Sp |
| 154 |
If this parameter is not used, certain error conditions may raise |
| 155 |
a fatal error that will cause the program to halt, unless trapped |
| 156 |
in an \f(CW\*(C`eval\*(C'\fR block. |
| 157 |
.ie n .IP "owner => $owner" 4 |
| 158 |
.el .IP "owner => \f(CW$owner\fR" 4 |
| 159 |
.IX Item "owner => $owner" |
| 160 |
.PD 0 |
| 161 |
.ie n .IP "user => $owner" 4 |
| 162 |
.el .IP "user => \f(CW$owner\fR" 4 |
| 163 |
.IX Item "user => $owner" |
| 164 |
.ie n .IP "uid => $owner" 4 |
| 165 |
.el .IP "uid => \f(CW$owner\fR" 4 |
| 166 |
.IX Item "uid => $owner" |
| 167 |
.PD |
| 168 |
If present, will cause any created directory to be owned by \f(CW$owner\fR. |
| 169 |
If the value is numeric, it will be interpreted as a uid; otherwise a |
| 170 |
username is assumed. An error will be issued if the username cannot be |
| 171 |
mapped to a uid, the uid does not exist or the process lacks the |
| 172 |
privileges to change ownership. |
| 173 |
.Sp |
| 174 |
Ownership of directories that already exist will not be changed. |
| 175 |
.Sp |
| 176 |
\&\f(CW\*(C`user\*(C'\fR and \f(CW\*(C`uid\*(C'\fR are aliases of \f(CW\*(C`owner\*(C'\fR. |
| 177 |
.ie n .IP "group => $group" 4 |
| 178 |
.el .IP "group => \f(CW$group\fR" 4 |
| 179 |
.IX Item "group => $group" |
| 180 |
If present, will cause any created directory to be owned by the group |
| 181 |
\&\f(CW$group\fR. If the value is numeric, it will be interpreted as a gid; |
| 182 |
otherwise a group name is assumed. An error will be issued if the |
| 183 |
group name cannot be mapped to a gid, the gid does not exist or the |
| 184 |
process lacks the privileges to change group ownership. |
| 185 |
.Sp |
| 186 |
Group ownership of directories that already exist will not be changed. |
| 187 |
.Sp |
| 188 |
.Vb 1 |
| 189 |
\& make_path \*(Aq/var/tmp/webcache\*(Aq, {owner=>\*(Aqnobody\*(Aq, group=>\*(Aqnogroup\*(Aq}; |
| 190 |
.Ve |
| 191 |
.RE |
| 192 |
.RS 4 |
| 193 |
.RE |
| 194 |
.ie n .IP "mkpath( $dir )" 4 |
| 195 |
.el .IP "mkpath( \f(CW$dir\fR )" 4 |
| 196 |
.IX Item "mkpath( $dir )" |
| 197 |
.PD 0 |
| 198 |
.ie n .IP "mkpath( $dir, $verbose, $mode )" 4 |
| 199 |
.el .IP "mkpath( \f(CW$dir\fR, \f(CW$verbose\fR, \f(CW$mode\fR )" 4 |
| 200 |
.IX Item "mkpath( $dir, $verbose, $mode )" |
| 201 |
.ie n .IP "mkpath( [$dir1, $dir2,...], $verbose, $mode )" 4 |
| 202 |
.el .IP "mkpath( [$dir1, \f(CW$dir2\fR,...], \f(CW$verbose\fR, \f(CW$mode\fR )" 4 |
| 203 |
.IX Item "mkpath( [$dir1, $dir2,...], $verbose, $mode )" |
| 204 |
.ie n .IP "mkpath( $dir1, $dir2,..., \e%opt )" 4 |
| 205 |
.el .IP "mkpath( \f(CW$dir1\fR, \f(CW$dir2\fR,..., \e%opt )" 4 |
| 206 |
.IX Item "mkpath( $dir1, $dir2,..., %opt )" |
| 207 |
.PD |
| 208 |
The \f(CWmkpath()\fR function provide the legacy interface of |
| 209 |
\&\f(CWmake_path()\fR with a different interpretation of the arguments |
| 210 |
passed. The behaviour and return value of the function is otherwise |
| 211 |
identical to \f(CWmake_path()\fR. |
| 212 |
.ie n .IP "remove_tree( $dir1, $dir2, .... )" 4 |
| 213 |
.el .IP "remove_tree( \f(CW$dir1\fR, \f(CW$dir2\fR, .... )" 4 |
| 214 |
.IX Item "remove_tree( $dir1, $dir2, .... )" |
| 215 |
.PD 0 |
| 216 |
.ie n .IP "remove_tree( $dir1, $dir2, ...., \e%opts )" 4 |
| 217 |
.el .IP "remove_tree( \f(CW$dir1\fR, \f(CW$dir2\fR, ...., \e%opts )" 4 |
| 218 |
.IX Item "remove_tree( $dir1, $dir2, ...., %opts )" |
| 219 |
.PD |
| 220 |
The \f(CW\*(C`remove_tree\*(C'\fR function deletes the given directories and any |
| 221 |
files and subdirectories they might contain, much like the Unix |
| 222 |
command \f(CW\*(C`rm \-rf\*(C'\fR or the Windows commands \f(CW\*(C`rmdir /s\*(C'\fR and \f(CW\*(C`rd /s\*(C'\fR. |
| 223 |
.Sp |
| 224 |
The function accepts a list of directories to be removed. (In point of fact, |
| 225 |
it will also accept filesystem entries which are not directories, such as |
| 226 |
regular files and symlinks. But, as its name suggests, its intent is to |
| 227 |
remove trees rather than individual files.) |
| 228 |
.Sp |
| 229 |
\&\f(CWremove_tree()\fR's behaviour may be tuned by an optional hashref |
| 230 |
appearing as the last parameter on the call. If an empty string is |
| 231 |
passed to \f(CW\*(C`remove_tree\*(C'\fR, an error will occur. |
| 232 |
.Sp |
| 233 |
\&\fBNOTE:\fR For security reasons, we strongly advise use of the |
| 234 |
hashref-as-final-argument syntax \-\- specifically, with a setting of the \f(CW\*(C`safe\*(C'\fR |
| 235 |
element to a true value. |
| 236 |
.Sp |
| 237 |
.Vb 6 |
| 238 |
\& remove_tree( $dir1, $dir2, ...., |
| 239 |
\& { |
| 240 |
\& safe => 1, |
| 241 |
\& ... # other key\-value pairs |
| 242 |
\& }, |
| 243 |
\& ); |
| 244 |
.Ve |
| 245 |
.Sp |
| 246 |
The function returns the number of files successfully deleted. |
| 247 |
.Sp |
| 248 |
The following keys are recognised in the option hash: |
| 249 |
.RS 4 |
| 250 |
.ie n .IP "verbose => $bool" 4 |
| 251 |
.el .IP "verbose => \f(CW$bool\fR" 4 |
| 252 |
.IX Item "verbose => $bool" |
| 253 |
If present, will cause \f(CW\*(C`remove_tree\*(C'\fR to print the name of each file as |
| 254 |
it is unlinked. By default nothing is printed. |
| 255 |
.ie n .IP "safe => $bool" 4 |
| 256 |
.el .IP "safe => \f(CW$bool\fR" 4 |
| 257 |
.IX Item "safe => $bool" |
| 258 |
When set to a true value, will cause \f(CW\*(C`remove_tree\*(C'\fR to skip the files |
| 259 |
for which the process lacks the required privileges needed to delete |
| 260 |
files, such as delete privileges on VMS. In other words, the code |
| 261 |
will make no attempt to alter file permissions. Thus, if the process |
| 262 |
is interrupted, no filesystem object will be left in a more |
| 263 |
permissive mode. |
| 264 |
.ie n .IP "keep_root => $bool" 4 |
| 265 |
.el .IP "keep_root => \f(CW$bool\fR" 4 |
| 266 |
.IX Item "keep_root => $bool" |
| 267 |
When set to a true value, will cause all files and subdirectories |
| 268 |
to be removed, except the initially specified directories. This comes |
| 269 |
in handy when cleaning out an application's scratch directory. |
| 270 |
.Sp |
| 271 |
.Vb 1 |
| 272 |
\& remove_tree( \*(Aq/tmp\*(Aq, {keep_root => 1} ); |
| 273 |
.Ve |
| 274 |
.IP "result => \e$res" 4 |
| 275 |
.IX Item "result => $res" |
| 276 |
If present, it should be a reference to a scalar. |
| 277 |
This scalar will be made to reference an array, which will |
| 278 |
be used to store all files and directories unlinked |
| 279 |
during the call. If nothing is unlinked, the array will be empty. |
| 280 |
.Sp |
| 281 |
.Vb 2 |
| 282 |
\& remove_tree( \*(Aq/tmp\*(Aq, {result => \emy $list} ); |
| 283 |
\& print "unlinked $_\en" for @$list; |
| 284 |
.Ve |
| 285 |
.Sp |
| 286 |
This is a useful alternative to the \f(CW\*(C`verbose\*(C'\fR key. |
| 287 |
.IP "error => \e$err" 4 |
| 288 |
.IX Item "error => $err" |
| 289 |
If present, it should be a reference to a scalar. |
| 290 |
This scalar will be made to reference an array, which will |
| 291 |
be used to store any errors that are encountered. See the "ERROR |
| 292 |
HANDLING" section for more information. |
| 293 |
.Sp |
| 294 |
Removing things is a much more dangerous proposition than |
| 295 |
creating things. As such, there are certain conditions that |
| 296 |
\&\f(CW\*(C`remove_tree\*(C'\fR may encounter that are so dangerous that the only |
| 297 |
sane action left is to kill the program. |
| 298 |
.Sp |
| 299 |
Use \f(CW\*(C`error\*(C'\fR to trap all that is reasonable (problems with |
| 300 |
permissions and the like), and let it die if things get out |
| 301 |
of hand. This is the safest course of action. |
| 302 |
.RE |
| 303 |
.RS 4 |
| 304 |
.RE |
| 305 |
.ie n .IP "rmtree( $dir )" 4 |
| 306 |
.el .IP "rmtree( \f(CW$dir\fR )" 4 |
| 307 |
.IX Item "rmtree( $dir )" |
| 308 |
.PD 0 |
| 309 |
.ie n .IP "rmtree( $dir, $verbose, $safe )" 4 |
| 310 |
.el .IP "rmtree( \f(CW$dir\fR, \f(CW$verbose\fR, \f(CW$safe\fR )" 4 |
| 311 |
.IX Item "rmtree( $dir, $verbose, $safe )" |
| 312 |
.ie n .IP "rmtree( [$dir1, $dir2,...], $verbose, $safe )" 4 |
| 313 |
.el .IP "rmtree( [$dir1, \f(CW$dir2\fR,...], \f(CW$verbose\fR, \f(CW$safe\fR )" 4 |
| 314 |
.IX Item "rmtree( [$dir1, $dir2,...], $verbose, $safe )" |
| 315 |
.ie n .IP "rmtree( $dir1, $dir2,..., \e%opt )" 4 |
| 316 |
.el .IP "rmtree( \f(CW$dir1\fR, \f(CW$dir2\fR,..., \e%opt )" 4 |
| 317 |
.IX Item "rmtree( $dir1, $dir2,..., %opt )" |
| 318 |
.PD |
| 319 |
The \f(CWrmtree()\fR function provide the legacy interface of |
| 320 |
\&\f(CWremove_tree()\fR with a different interpretation of the arguments |
| 321 |
passed. The behaviour and return value of the function is otherwise |
| 322 |
identical to \f(CWremove_tree()\fR. |
| 323 |
.Sp |
| 324 |
\&\fBNOTE:\fR For security reasons, we strongly advise use of the |
| 325 |
hashref-as-final-argument syntax, specifically with a setting of the \f(CW\*(C`safe\*(C'\fR |
| 326 |
element to a true value. |
| 327 |
.Sp |
| 328 |
.Vb 6 |
| 329 |
\& rmtree( $dir1, $dir2, ...., |
| 330 |
\& { |
| 331 |
\& safe => 1, |
| 332 |
\& ... # other key\-value pairs |
| 333 |
\& }, |
| 334 |
\& ); |
| 335 |
.Ve |
| 336 |
.SS "ERROR HANDLING" |
| 337 |
.IX Subsection "ERROR HANDLING" |
| 338 |
.IP \fBNOTE:\fR 4 |
| 339 |
.IX Item "NOTE:" |
| 340 |
The following error handling mechanism is consistent throughout all |
| 341 |
code paths EXCEPT in cases where the ROOT node is nonexistent. In |
| 342 |
version 2.11 the maintainers attempted to rectify this inconsistency |
| 343 |
but too many downstream modules encountered problems. In such case, |
| 344 |
if you require root node evaluation or error checking prior to calling |
| 345 |
\&\f(CW\*(C`make_path\*(C'\fR or \f(CW\*(C`remove_tree\*(C'\fR, you should take additional precautions. |
| 346 |
.PP |
| 347 |
If \f(CW\*(C`make_path\*(C'\fR or \f(CW\*(C`remove_tree\*(C'\fR encounters an error, a diagnostic |
| 348 |
message will be printed to \f(CW\*(C`STDERR\*(C'\fR via \f(CW\*(C`carp\*(C'\fR (for non-fatal |
| 349 |
errors) or via \f(CW\*(C`croak\*(C'\fR (for fatal errors). |
| 350 |
.PP |
| 351 |
If this behaviour is not desirable, the \f(CW\*(C`error\*(C'\fR attribute may be |
| 352 |
used to hold a reference to a variable, which will be used to store |
| 353 |
the diagnostics. The variable is made a reference to an array of hash |
| 354 |
references. Each hash contain a single key/value pair where the key |
| 355 |
is the name of the file, and the value is the error message (including |
| 356 |
the contents of \f(CW$!\fR when appropriate). If a general error is |
| 357 |
encountered the diagnostic key will be empty. |
| 358 |
.PP |
| 359 |
An example usage looks like: |
| 360 |
.PP |
| 361 |
.Vb 10 |
| 362 |
\& remove_tree( \*(Aqfoo/bar\*(Aq, \*(Aqbar/rat\*(Aq, {error => \emy $err} ); |
| 363 |
\& if ($err && @$err) { |
| 364 |
\& for my $diag (@$err) { |
| 365 |
\& my ($file, $message) = %$diag; |
| 366 |
\& if ($file eq \*(Aq\*(Aq) { |
| 367 |
\& print "general error: $message\en"; |
| 368 |
\& } |
| 369 |
\& else { |
| 370 |
\& print "problem unlinking $file: $message\en"; |
| 371 |
\& } |
| 372 |
\& } |
| 373 |
\& } |
| 374 |
\& else { |
| 375 |
\& print "No error encountered\en"; |
| 376 |
\& } |
| 377 |
.Ve |
| 378 |
.PP |
| 379 |
Note that if no errors are encountered, \f(CW$err\fR will reference an |
| 380 |
empty array. This means that \f(CW$err\fR will always end up TRUE; so you |
| 381 |
need to test \f(CW@$err\fR to determine if errors occurred. |
| 382 |
.SS NOTES |
| 383 |
.IX Subsection "NOTES" |
| 384 |
\&\f(CW\*(C`File::Path\*(C'\fR blindly exports \f(CW\*(C`mkpath\*(C'\fR and \f(CW\*(C`rmtree\*(C'\fR into the |
| 385 |
current namespace. These days, this is considered bad style, but |
| 386 |
to change it now would break too much code. Nonetheless, you are |
| 387 |
invited to specify what it is you are expecting to use: |
| 388 |
.PP |
| 389 |
.Vb 1 |
| 390 |
\& use File::Path \*(Aqrmtree\*(Aq; |
| 391 |
.Ve |
| 392 |
.PP |
| 393 |
The routines \f(CW\*(C`make_path\*(C'\fR and \f(CW\*(C`remove_tree\*(C'\fR are \fBnot\fR exported |
| 394 |
by default. You must specify which ones you want to use. |
| 395 |
.PP |
| 396 |
.Vb 1 |
| 397 |
\& use File::Path \*(Aqremove_tree\*(Aq; |
| 398 |
.Ve |
| 399 |
.PP |
| 400 |
Note that a side-effect of the above is that \f(CW\*(C`mkpath\*(C'\fR and \f(CW\*(C`rmtree\*(C'\fR |
| 401 |
are no longer exported at all. This is due to the way the \f(CW\*(C`Exporter\*(C'\fR |
| 402 |
module works. If you are migrating a codebase to use the new |
| 403 |
interface, you will have to list everything explicitly. But that's |
| 404 |
just good practice anyway. |
| 405 |
.PP |
| 406 |
.Vb 1 |
| 407 |
\& use File::Path qw(remove_tree rmtree); |
| 408 |
.Ve |
| 409 |
.PP |
| 410 |
\fIAPI CHANGES\fR |
| 411 |
.IX Subsection "API CHANGES" |
| 412 |
.PP |
| 413 |
The API was changed in the 2.0 branch. For a time, \f(CW\*(C`mkpath\*(C'\fR and |
| 414 |
\&\f(CW\*(C`rmtree\*(C'\fR tried, unsuccessfully, to deal with the two different |
| 415 |
calling mechanisms. This approach was considered a failure. |
| 416 |
.PP |
| 417 |
The new semantics are now only available with \f(CW\*(C`make_path\*(C'\fR and |
| 418 |
\&\f(CW\*(C`remove_tree\*(C'\fR. The old semantics are only available through |
| 419 |
\&\f(CW\*(C`mkpath\*(C'\fR and \f(CW\*(C`rmtree\*(C'\fR. Users are strongly encouraged to upgrade |
| 420 |
to at least 2.08 in order to avoid surprises. |
| 421 |
.PP |
| 422 |
\fISECURITY CONSIDERATIONS\fR |
| 423 |
.IX Subsection "SECURITY CONSIDERATIONS" |
| 424 |
.PP |
| 425 |
There were race conditions in the 1.x implementations of File::Path's |
| 426 |
\&\f(CW\*(C`rmtree\*(C'\fR function (although sometimes patched depending on the OS |
| 427 |
distribution or platform). The 2.0 version contains code to avoid the |
| 428 |
problem mentioned in CVE\-2002\-0435. |
| 429 |
.PP |
| 430 |
See the following pages for more information: |
| 431 |
.PP |
| 432 |
.Vb 3 |
| 433 |
\& http://bugs.debian.org/cgi\-bin/bugreport.cgi?bug=286905 |
| 434 |
\& http://www.nntp.perl.org/group/perl.perl5.porters/2005/01/msg97623.html |
| 435 |
\& http://www.debian.org/security/2005/dsa\-696 |
| 436 |
.Ve |
| 437 |
.PP |
| 438 |
Additionally, unless the \f(CW\*(C`safe\*(C'\fR parameter is set (or the |
| 439 |
third parameter in the traditional interface is TRUE), should a |
| 440 |
\&\f(CW\*(C`remove_tree\*(C'\fR be interrupted, files that were originally in read-only |
| 441 |
mode may now have their permissions set to a read-write (or "delete |
| 442 |
OK") mode. |
| 443 |
.PP |
| 444 |
The following CVE reports were previously filed against File-Path and are |
| 445 |
believed to have been addressed: |
| 446 |
.IP \(bu 4 |
| 447 |
<http://cve.circl.lu/cve/CVE\-2004\-0452> |
| 448 |
.IP \(bu 4 |
| 449 |
<http://cve.circl.lu/cve/CVE\-2005\-0448> |
| 450 |
.PP |
| 451 |
In February 2017 the cPanel Security Team reported an additional vulnerability |
| 452 |
in File-Path. The \f(CWchmod()\fR logic to make directories traversable can be |
| 453 |
abused to set the mode on an attacker-chosen file to an attacker-chosen value. |
| 454 |
This is due to the time-of-check-to-time-of-use (TOCTTOU) race condition |
| 455 |
(<https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use>) between the |
| 456 |
\&\f(CWstat()\fR that decides the inode is a directory and the \f(CWchmod()\fR that tries |
| 457 |
to make it user-rwx. CPAN versions 2.13 and later incorporate a patch |
| 458 |
provided by John Lightsey to address this problem. This vulnerability has |
| 459 |
been reported as CVE\-2017\-6512. |
| 460 |
.SH DIAGNOSTICS |
| 461 |
.IX Header "DIAGNOSTICS" |
| 462 |
FATAL errors will cause the program to halt (\f(CW\*(C`croak\*(C'\fR), since the |
| 463 |
problem is so severe that it would be dangerous to continue. (This |
| 464 |
can always be trapped with \f(CW\*(C`eval\*(C'\fR, but it's not a good idea. Under |
| 465 |
the circumstances, dying is the best thing to do). |
| 466 |
.PP |
| 467 |
SEVERE errors may be trapped using the modern interface. If the |
| 468 |
they are not trapped, or if the old interface is used, such an error |
| 469 |
will cause the program will halt. |
| 470 |
.PP |
| 471 |
All other errors may be trapped using the modern interface, otherwise |
| 472 |
they will be \f(CW\*(C`carp\*(C'\fRed about. Program execution will not be halted. |
| 473 |
.IP "mkdir [path]: [errmsg] (SEVERE)" 4 |
| 474 |
.IX Item "mkdir [path]: [errmsg] (SEVERE)" |
| 475 |
\&\f(CW\*(C`make_path\*(C'\fR was unable to create the path. Probably some sort of |
| 476 |
permissions error at the point of departure or insufficient resources |
| 477 |
(such as free inodes on Unix). |
| 478 |
.IP "No root path(s) specified" 4 |
| 479 |
.IX Item "No root path(s) specified" |
| 480 |
\&\f(CW\*(C`make_path\*(C'\fR was not given any paths to create. This message is only |
| 481 |
emitted if the routine is called with the traditional interface. |
| 482 |
The modern interface will remain silent if given nothing to do. |
| 483 |
.IP "No such file or directory" 4 |
| 484 |
.IX Item "No such file or directory" |
| 485 |
On Windows, if \f(CW\*(C`make_path\*(C'\fR gives you this warning, it may mean that |
| 486 |
you have exceeded your filesystem's maximum path length. |
| 487 |
.IP "cannot fetch initial working directory: [errmsg]" 4 |
| 488 |
.IX Item "cannot fetch initial working directory: [errmsg]" |
| 489 |
\&\f(CW\*(C`remove_tree\*(C'\fR attempted to determine the initial directory by calling |
| 490 |
\&\f(CW\*(C`Cwd::getcwd\*(C'\fR, but the call failed for some reason. No attempt |
| 491 |
will be made to delete anything. |
| 492 |
.IP "cannot stat initial working directory: [errmsg]" 4 |
| 493 |
.IX Item "cannot stat initial working directory: [errmsg]" |
| 494 |
\&\f(CW\*(C`remove_tree\*(C'\fR attempted to stat the initial directory (after having |
| 495 |
successfully obtained its name via \f(CW\*(C`getcwd\*(C'\fR), however, the call |
| 496 |
failed for some reason. No attempt will be made to delete anything. |
| 497 |
.IP "cannot chdir to [dir]: [errmsg]" 4 |
| 498 |
.IX Item "cannot chdir to [dir]: [errmsg]" |
| 499 |
\&\f(CW\*(C`remove_tree\*(C'\fR attempted to set the working directory in order to |
| 500 |
begin deleting the objects therein, but was unsuccessful. This is |
| 501 |
usually a permissions issue. The routine will continue to delete |
| 502 |
other things, but this directory will be left intact. |
| 503 |
.IP "directory [dir] changed before chdir, expected dev=[n] ino=[n], actual dev=[n] ino=[n], aborting. (FATAL)" 4 |
| 504 |
.IX Item "directory [dir] changed before chdir, expected dev=[n] ino=[n], actual dev=[n] ino=[n], aborting. (FATAL)" |
| 505 |
\&\f(CW\*(C`remove_tree\*(C'\fR recorded the device and inode of a directory, and then |
| 506 |
moved into it. It then performed a \f(CW\*(C`stat\*(C'\fR on the current directory |
| 507 |
and detected that the device and inode were no longer the same. As |
| 508 |
this is at the heart of the race condition problem, the program |
| 509 |
will die at this point. |
| 510 |
.IP "cannot make directory [dir] read+writeable: [errmsg]" 4 |
| 511 |
.IX Item "cannot make directory [dir] read+writeable: [errmsg]" |
| 512 |
\&\f(CW\*(C`remove_tree\*(C'\fR attempted to change the permissions on the current directory |
| 513 |
to ensure that subsequent unlinkings would not run into problems, |
| 514 |
but was unable to do so. The permissions remain as they were, and |
| 515 |
the program will carry on, doing the best it can. |
| 516 |
.IP "cannot read [dir]: [errmsg]" 4 |
| 517 |
.IX Item "cannot read [dir]: [errmsg]" |
| 518 |
\&\f(CW\*(C`remove_tree\*(C'\fR tried to read the contents of the directory in order |
| 519 |
to acquire the names of the directory entries to be unlinked, but |
| 520 |
was unsuccessful. This is usually a permissions issue. The |
| 521 |
program will continue, but the files in this directory will remain |
| 522 |
after the call. |
| 523 |
.IP "cannot reset chmod [dir]: [errmsg]" 4 |
| 524 |
.IX Item "cannot reset chmod [dir]: [errmsg]" |
| 525 |
\&\f(CW\*(C`remove_tree\*(C'\fR, after having deleted everything in a directory, attempted |
| 526 |
to restore its permissions to the original state but failed. The |
| 527 |
directory may wind up being left behind. |
| 528 |
.IP "cannot remove [dir] when cwd is [dir]" 4 |
| 529 |
.IX Item "cannot remove [dir] when cwd is [dir]" |
| 530 |
The current working directory of the program is \fI/some/path/to/here\fR |
| 531 |
and you are attempting to remove an ancestor, such as \fI/some/path\fR. |
| 532 |
The directory tree is left untouched. |
| 533 |
.Sp |
| 534 |
The solution is to \f(CW\*(C`chdir\*(C'\fR out of the child directory to a place |
| 535 |
outside the directory tree to be removed. |
| 536 |
.IP "cannot chdir to [parent\-dir] from [child\-dir]: [errmsg], aborting. (FATAL)" 4 |
| 537 |
.IX Item "cannot chdir to [parent-dir] from [child-dir]: [errmsg], aborting. (FATAL)" |
| 538 |
\&\f(CW\*(C`remove_tree\*(C'\fR, after having deleted everything and restored the permissions |
| 539 |
of a directory, was unable to chdir back to the parent. The program |
| 540 |
halts to avoid a race condition from occurring. |
| 541 |
.IP "cannot stat prior working directory [dir]: [errmsg], aborting. (FATAL)" 4 |
| 542 |
.IX Item "cannot stat prior working directory [dir]: [errmsg], aborting. (FATAL)" |
| 543 |
\&\f(CW\*(C`remove_tree\*(C'\fR was unable to stat the parent directory after having returned |
| 544 |
from the child. Since there is no way of knowing if we returned to |
| 545 |
where we think we should be (by comparing device and inode) the only |
| 546 |
way out is to \f(CW\*(C`croak\*(C'\fR. |
| 547 |
.IP "previous directory [parent\-dir] changed before entering [child\-dir], expected dev=[n] ino=[n], actual dev=[n] ino=[n], aborting. (FATAL)" 4 |
| 548 |
.IX Item "previous directory [parent-dir] changed before entering [child-dir], expected dev=[n] ino=[n], actual dev=[n] ino=[n], aborting. (FATAL)" |
| 549 |
When \f(CW\*(C`remove_tree\*(C'\fR returned from deleting files in a child directory, a |
| 550 |
check revealed that the parent directory it returned to wasn't the one |
| 551 |
it started out from. This is considered a sign of malicious activity. |
| 552 |
.IP "cannot make directory [dir] writeable: [errmsg]" 4 |
| 553 |
.IX Item "cannot make directory [dir] writeable: [errmsg]" |
| 554 |
Just before removing a directory (after having successfully removed |
| 555 |
everything it contained), \f(CW\*(C`remove_tree\*(C'\fR attempted to set the permissions |
| 556 |
on the directory to ensure it could be removed and failed. Program |
| 557 |
execution continues, but the directory may possibly not be deleted. |
| 558 |
.IP "cannot remove directory [dir]: [errmsg]" 4 |
| 559 |
.IX Item "cannot remove directory [dir]: [errmsg]" |
| 560 |
\&\f(CW\*(C`remove_tree\*(C'\fR attempted to remove a directory, but failed. This may be because |
| 561 |
some objects that were unable to be removed remain in the directory, or |
| 562 |
it could be a permissions issue. The directory will be left behind. |
| 563 |
.IP "cannot restore permissions of [dir] to [0nnn]: [errmsg]" 4 |
| 564 |
.IX Item "cannot restore permissions of [dir] to [0nnn]: [errmsg]" |
| 565 |
After having failed to remove a directory, \f(CW\*(C`remove_tree\*(C'\fR was unable to |
| 566 |
restore its permissions from a permissive state back to a possibly |
| 567 |
more restrictive setting. (Permissions given in octal). |
| 568 |
.IP "cannot make file [file] writeable: [errmsg]" 4 |
| 569 |
.IX Item "cannot make file [file] writeable: [errmsg]" |
| 570 |
\&\f(CW\*(C`remove_tree\*(C'\fR attempted to force the permissions of a file to ensure it |
| 571 |
could be deleted, but failed to do so. It will, however, still attempt |
| 572 |
to unlink the file. |
| 573 |
.IP "cannot unlink file [file]: [errmsg]" 4 |
| 574 |
.IX Item "cannot unlink file [file]: [errmsg]" |
| 575 |
\&\f(CW\*(C`remove_tree\*(C'\fR failed to remove a file. Probably a permissions issue. |
| 576 |
.IP "cannot restore permissions of [file] to [0nnn]: [errmsg]" 4 |
| 577 |
.IX Item "cannot restore permissions of [file] to [0nnn]: [errmsg]" |
| 578 |
After having failed to remove a file, \f(CW\*(C`remove_tree\*(C'\fR was also unable |
| 579 |
to restore the permissions on the file to a possibly less permissive |
| 580 |
setting. (Permissions given in octal). |
| 581 |
.IP "unable to map [owner] to a uid, ownership not changed"");" 4 |
| 582 |
.IX Item "unable to map [owner] to a uid, ownership not changed"");" |
| 583 |
\&\f(CW\*(C`make_path\*(C'\fR was instructed to give the ownership of created |
| 584 |
directories to the symbolic name [owner], but \f(CW\*(C`getpwnam\*(C'\fR did |
| 585 |
not return the corresponding numeric uid. The directory will |
| 586 |
be created, but ownership will not be changed. |
| 587 |
.IP "unable to map [group] to a gid, group ownership not changed" 4 |
| 588 |
.IX Item "unable to map [group] to a gid, group ownership not changed" |
| 589 |
\&\f(CW\*(C`make_path\*(C'\fR was instructed to give the group ownership of created |
| 590 |
directories to the symbolic name [group], but \f(CW\*(C`getgrnam\*(C'\fR did |
| 591 |
not return the corresponding numeric gid. The directory will |
| 592 |
be created, but group ownership will not be changed. |
| 593 |
.SH "SEE ALSO" |
| 594 |
.IX Header "SEE ALSO" |
| 595 |
.IP \(bu 4 |
| 596 |
File::Remove |
| 597 |
.Sp |
| 598 |
Allows files and directories to be moved to the Trashcan/Recycle |
| 599 |
Bin (where they may later be restored if necessary) if the operating |
| 600 |
system supports such functionality. This feature may one day be |
| 601 |
made available directly in \f(CW\*(C`File::Path\*(C'\fR. |
| 602 |
.IP \(bu 4 |
| 603 |
File::Find::Rule |
| 604 |
.Sp |
| 605 |
When removing directory trees, if you want to examine each file to |
| 606 |
decide whether to delete it (and possibly leaving large swathes |
| 607 |
alone), \fIFile::Find::Rule\fR offers a convenient and flexible approach |
| 608 |
to examining directory trees. |
| 609 |
.SH "BUGS AND LIMITATIONS" |
| 610 |
.IX Header "BUGS AND LIMITATIONS" |
| 611 |
The following describes \fIFile::Path\fR limitations and how to report bugs. |
| 612 |
.SS "MULTITHREADED APPLICATIONS" |
| 613 |
.IX Subsection "MULTITHREADED APPLICATIONS" |
| 614 |
\&\fIFile::Path\fR \f(CW\*(C`rmtree\*(C'\fR and \f(CW\*(C`remove_tree\*(C'\fR will not work with |
| 615 |
multithreaded applications due to its use of \f(CW\*(C`chdir\*(C'\fR. At this time, |
| 616 |
no warning or error is generated in this situation. You will |
| 617 |
certainly encounter unexpected results. |
| 618 |
.PP |
| 619 |
The implementation that surfaces this limitation will not be changed. See the |
| 620 |
\&\fIFile::Path::Tiny\fR module for functionality similar to \fIFile::Path\fR but which does |
| 621 |
not \f(CW\*(C`chdir\*(C'\fR. |
| 622 |
.SS "NFS Mount Points" |
| 623 |
.IX Subsection "NFS Mount Points" |
| 624 |
\&\fIFile::Path\fR is not responsible for triggering the automounts, mirror mounts, |
| 625 |
and the contents of network mounted filesystems. If your NFS implementation |
| 626 |
requires an action to be performed on the filesystem in order for |
| 627 |
\&\fIFile::Path\fR to perform operations, it is strongly suggested you assure |
| 628 |
filesystem availability by reading the root of the mounted filesystem. |
| 629 |
.SS "REPORTING BUGS" |
| 630 |
.IX Subsection "REPORTING BUGS" |
| 631 |
Please report all bugs on the RT queue, either via the web interface: |
| 632 |
.PP |
| 633 |
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=File\-Path> |
| 634 |
.PP |
| 635 |
or by email: |
| 636 |
.PP |
| 637 |
.Vb 1 |
| 638 |
\& bug\-File\[email protected] |
| 639 |
.Ve |
| 640 |
.PP |
| 641 |
In either case, please \fBattach\fR patches to the bug report rather than |
| 642 |
including them inline in the web post or the body of the email. |
| 643 |
.PP |
| 644 |
You can also send pull requests to the Github repository: |
| 645 |
.PP |
| 646 |
<https://github.com/rpcme/File\-Path> |
| 647 |
.SH ACKNOWLEDGEMENTS |
| 648 |
.IX Header "ACKNOWLEDGEMENTS" |
| 649 |
Paul Szabo identified the race condition originally, and Brendan |
| 650 |
O'Dea wrote an implementation for Debian that addressed the problem. |
| 651 |
That code was used as a basis for the current code. Their efforts |
| 652 |
are greatly appreciated. |
| 653 |
.PP |
| 654 |
Gisle Aas made a number of improvements to the documentation for |
| 655 |
2.07 and his advice and assistance is also greatly appreciated. |
| 656 |
.SH AUTHORS |
| 657 |
.IX Header "AUTHORS" |
| 658 |
Prior authors and maintainers: Tim Bunce, Charles Bailey, and |
| 659 |
David Landgren <\[email protected]\fR>. |
| 660 |
.PP |
| 661 |
Current maintainers are Richard Elberger <\[email protected]\fR> and |
| 662 |
James (Jim) Keenan <\[email protected]\fR>. |
| 663 |
.SH CONTRIBUTORS |
| 664 |
.IX Header "CONTRIBUTORS" |
| 665 |
Contributors to File::Path, in alphabetical order by first name. |
| 666 |
.IP <\[email protected]\fR> 1 |
| 667 |
.IX Item "<[email protected]>" |
| 668 |
.PD 0 |
| 669 |
.IP "Charlie Gonzalez <\[email protected]\fR>" 1 |
| 670 |
.IX Item "Charlie Gonzalez <[email protected]>" |
| 671 |
.IP "Craig A. Berry <\[email protected]\fR>" 1 |
| 672 |
.IX Item "Craig A. Berry <[email protected]>" |
| 673 |
.IP "James E Keenan <\[email protected]\fR>" 1 |
| 674 |
.IX Item "James E Keenan <[email protected]>" |
| 675 |
.IP "John Lightsey <\[email protected]\fR>" 1 |
| 676 |
.IX Item "John Lightsey <[email protected]>" |
| 677 |
.IP "Nigel Horne <\[email protected]\fR>" 1 |
| 678 |
.IX Item "Nigel Horne <[email protected]>" |
| 679 |
.IP "Richard Elberger <\[email protected]\fR>" 1 |
| 680 |
.IX Item "Richard Elberger <[email protected]>" |
| 681 |
.IP "Ryan Yee <\[email protected]\fR>" 1 |
| 682 |
.IX Item "Ryan Yee <[email protected]>" |
| 683 |
.IP "Skye Shaw <\[email protected]\fR>" 1 |
| 684 |
.IX Item "Skye Shaw <[email protected]>" |
| 685 |
.IP "Tom Lutz <\[email protected]\fR>" 1 |
| 686 |
.IX Item "Tom Lutz <[email protected]>" |
| 687 |
.IP "Will Sheppard <\fIwillsheppard@github\fR>" 1 |
| 688 |
.IX Item "Will Sheppard <willsheppard@github>" |
| 689 |
.PD |
| 690 |
.SH COPYRIGHT |
| 691 |
.IX Header "COPYRIGHT" |
| 692 |
This module is copyright (C) Charles Bailey, Tim Bunce, David Landgren, |
| 693 |
James Keenan and Richard Elberger 1995\-2020. All rights reserved. |
| 694 |
.SH LICENSE |
| 695 |
.IX Header "LICENSE" |
| 696 |
This library is free software; you can redistribute it and/or modify |
| 697 |
it under the same terms as Perl itself. |