1Recursive(3) User Contributed Perl Documentation Recursive(3)
2
3
4
6 File::Copy::Recursive - Perl extension for recursively copying files
7 and directories
8
10 use File::Copy::Recursive qw(fcopy rcopy dircopy fmove rmove dirmove);
11
12 fcopy($orig,$new[,$buf]) or die $!;
13 rcopy($orig,$new[,$buf]) or die $!;
14 dircopy($orig,$new[,$buf]) or die $!;
15
16 fmove($orig,$new[,$buf]) or die $!;
17 rmove($orig,$new[,$buf]) or die $!;
18 dirmove($orig,$new[,$buf]) or die $!;
19
21 This module copies and moves directories recursively (or single files,
22 well... singley) to an optional depth and attempts to preserve each
23 file or directory's mode.
24
26 None by default. But you can export all the functions as in the example
27 above and the path* functions if you wish.
28
29 fcopy()
30
31 This function uses File::Copy's copy() function to copy a file but not
32 a directory. Any directories are recursively created if need be. One
33 difference to File::Copy::copy() is that fcopy attempts to preserve the
34 mode (see Preserving Mode below) The optional $buf in the synopsis if
35 the same as File::Copy::copy()'s 3rd argument returns the same as
36 File::Copy::copy() in scalar context and 1,0,0 in list context to acco‐
37 midate rcopy()'s list context on regular files. (See below for more
38 info)
39
40 dircopy()
41
42 This function recursively traverses the $orig directory's structure and
43 recursively copies it to the $new directory. $new is created if neces‐
44 sary (multiple non existant directories is ok (IE foo/bar/baz). The
45 script logically and portably creates all of them if necessary). It
46 attempts to preserve the mode (see Preserving Mode below) and by
47 default it copies all the way down into the directory, (see Managing
48 Depth) below. If a directory is not specified it croaks just like
49 fcopy croaks if its not a file that is specified.
50
51 returns true or false, for true in scalar context it returns the number
52 of files and directories copied, In list context it returns the number
53 of files and directories, number of directories only, depth level tra‐
54 versed.
55
56 my $num_of_files_and_dirs = dircopy($orig,$new);
57 my($num_of_files_and_dirs,$num_of_dirs,$depth_traversed) = dircopy($orig,$new);
58
59 Normally it stops and return's if a copy fails, to continue on regard‐
60 less set $File::Copy::Recursive::SkipFlop to true.
61
62 local $File::Copy::Recursive::SkipFlop = 1;
63
64 That way it will copy everythgingit can ina directory and won't stop
65 because of permissions, etc...
66
67 rcopy()
68
69 This function will allow you to specify a file *or* directory. It calls
70 fcopy() if its a file and dircopy() if its a directory. If you call
71 rcopy() (or fcopy() for that matter) on a file in list context, the
72 values will be 1,0,0 since no directories and no depth are used. This
73 is important becasue if its a directory in list context and there is
74 only the initial directory the return value is 1,1,1.
75
76 fmove()
77
78 Copies the file then removes the original. You can manage the path the
79 original file is in according to $RemvBase.
80
81 dirmove()
82
83 Uses dircopy() to copy the directory then removes the original. You can
84 manage the path the original directory is in according to $RemvBase.
85
86 rmove()
87
88 Like rcopy() but calls fmove() or dirmove() instead.
89
90 $RemvBase
91
92 Default is false. When set to true the *move() functions will not only
93 attempt to remove the original file or directory but will remove the
94 given path it is in.
95
96 So if you:
97
98 rmove('foo/bar/baz', '/etc/');
99 # "baz" is removed from foo/bar after it is successfully copied to /etc/
100
101 local $File::Copy::Recursive::Remvbase = 1;
102 rmove('foo/bar/baz','/etc/');
103 # if baz is successfully copied to /etc/ :
104 # first "baz" is removed from foo/bar
105 # then "foo/bar is removed via pathrm()
106
107 $ForcePth
108
109 Default is false. When set to true it calls pathempty() before any
110 directories are removed to empty the directory so it can be rmdir()'ed
111 when $RemvBase is in effect.
112
113 Creating and Removing Paths
114
115 $NoFtlPth
116
117 Default is false. If set to true rmdir(), mkdir(), and pathempty()
118 calls in pathrm() and pathmk() do not return() on failure.
119
120 If its set to true they just silently go about their business regard‐
121 less. This isn't a good idea but its there if you want it.
122
123 Path functions
124
125 These functions exist soley because they were necessary for the move
126 and copy functions to have the features they do and not because they
127 are of themselves the purpose of this module. That being said, here is
128 how they work so you can understand how the copy and move funtions work
129 and use them by themselves if you wish.
130
131 pathrm()
132
133 Removes a given path recursively. It removes the *entire* path so be
134 carefull!!!
135
136 Returns 2 if the given path is not a directory.
137
138 File::Copy::Recursive::pathrm('foo/bar/baz') or die $!;
139 # foo no longer exists
140
141 Same as:
142
143 rmdir 'foo/bar/baz' or die $!;
144 rmdir 'foo/bar' or die $!;
145 rmdir 'foo' or die $!;
146
147 An optional second argument makes it call pathempty() before any
148 rmdir()'s when set to true.
149
150 File::Copy::Recursive::pathrm('foo/bar/baz', 1) or die $!;
151 # foo no longer exists
152
153 Same as:
154
155 File::Copy::Recursive::pathempty('foo/bar/baz') or die $!;
156 rmdir 'foo/bar/baz' or die $!;
157 File::Copy::Recursive::pathempty('foo/bar/') or die $!;
158 rmdir 'foo/bar' or die $!;
159 File::Copy::Recursive::pathempty('foo/') or die $!;
160 rmdir 'foo' or die $!;
161
162 An optional third argument acts like $File::Copy::Recursive::NoFtlPth,
163 again probably not a good idea.
164
165 pathempty()
166
167 Recursively removes the given directory's contents so it is empty.
168 returns 2 if argument is not a directory, 1 on successfully emptying
169 the directory.
170
171 File::Copy::Recursive::pathempty($pth) or die $!;
172 # $pth is now an empty directory
173
174 pathmk()
175
176 Creates a given path recursively. Creates foo/bar/baz even if foo does
177 not exist.
178
179 File::Copy::Recursive::pathmk('foo/bar/baz') or die $!;
180
181 An optional second argument if true acts just like $File::Copy::Recur‐
182 sive::NoFtlPth, which means you'd never get your die() if something
183 went wrong. Again, probably a *bad* idea.
184
185 pathrmdir()
186
187 Same as rmdir() but it calls pathempty() first to recursively empty it
188 first since rmdir can not remove a directory with contents. Just
189 removes the top directory the path given insetad of the entire path
190 like pathrm(). Return 2 if the given argument is not a directory.
191
192 Preserving Mode
193
194 By default a quiet attempt is made to change the new file or directory
195 to the mode of the old one. To turn this behavior off set
196 $File::Copy::Recursive::KeepMode to false;
197
198 Managing Depth
199
200 You can set the maximum depth a directory structure is recursed by set‐
201 ting:
202 $File::Copy::Recursive::MaxDepth to a whole number greater than 0.
203
204 SymLinks
205
206 If your system supports symlinks then symlinks will be copied as sym‐
207 links instead of as the target file. Perl's symlink() is used instead
208 of File::Copy's copy() You can customize this behavior by setting
209 $File::Copy::Recursive::CopyLink to a true or false value. It is
210 already set to true or false dending on your system's support of sym‐
211 links so you can check it with an if statement to see how it will
212 behave:
213
214 if($File::Copy::Recursive::CopyLink) {
215 print "Symlinks will be preserved\n";
216 } else {
217 print "Symlinks will not be preserved because your system does not support it\n";
218 }
219
220 If symlinks are being copied you can set $File::Copy::Recursive::BdTrg‐
221 Wrn to true to make it carp when it copies a link whose target does not
222 exist. Its false by default.
223
224 local $File::Copy::Recursive::BdTrgWrn = 1;
225
226 Removing existing target file or directory before copying.
227
228 This can be done by setting $File::Copy::Recursive::RMTrgFil or
229 $File::Copy::Recursive::RMTrgDir for file or directory behavior respec‐
230 tively.
231
232 0 = off (This is the default)
233
234 1 = carp() $! if removal fails
235
236 2 = return if removal fails
237
238 local $File::Copy::Recursive::RMTrgFil = 1;
239 fcopy($orig, $target) or die $!;
240 # if it fails it does warn() and keeps going
241
242 local $File::Copy::Recursive::RMTrgDir = 2;
243 dircopy($orig, $target) or die $!;
244 # if it fails it does your "or die"
245
246 This should be unnecessary most of the time but its there if you need
247 it :)
248
249 Turning off stat() check
250
251 By default the files or directories are checked to see if they are the
252 same (IE linked, or two paths (absolute/relative or different relative
253 paths) to the same file) by comparing the file's stat() info. It's a
254 very efficient check that croaks if they are and shouldn't be turned
255 off but if you must for some weird reason just set $File::Copy::Recur‐
256 sive::PFSCheck to a false value. ("PFS" stands for "Physical File Sys‐
257 tem")
258
259 Emulating cp -rf dir1/ dir2/
260
261 By default dircopy($dir1,$dir2) will put $dir1's contents right into
262 $dir2 whether $dir2 exists or not.
263
264 You can make dircopy() emulate cp -rf by setting $File::Copy::Recur‐
265 sive::CPRFComp to true.
266
267 NOTE: This only emulates -f in the sense that it does not prompt. It
268 does not remove the target file or directory if it exists. If you need
269 to do that then use the variables $RMTrgFil and $RMTrgDir described in
270 "Removing existing target file or directory before copying" above.
271
272 That means that if $dir2 exists it puts the contents into $dir2/$dir1
273 instead of $dir2 just like cp -rf. If $dir2 does not exist then the
274 contents go into $dir2 like normal (also like cp -rf)
275
276 So assuming 'foo/file':
277
278 dircopy('foo', 'bar') or die $!;
279 # if bar does not exist the result is bar/file
280 # if bar does exist the result is bar/file
281
282 $File::Copy::Recursive::CPRFComp = 1;
283 dircopy('foo', 'bar') or die $!;
284 # if bar does not exist the result is bar/file
285 # if bar does exist the result is bar/foo/file
286
287 You can also specify a star for cp -rf glob type behavior:
288
289 dircopy('foo/*', 'bar') or die $!;
290 # if bar does not exist the result is bar/file
291 # if bar does exist the result is bar/file
292
293 $File::Copy::Recursive::CPRFComp = 1;
294 dircopy('foo/*', 'bar') or die $!;
295 # if bar does not exist the result is bar/file
296 # if bar does exist the result is bar/file
297
298 NOTE: The '*' is only like cp -rf foo/* and *DOES NOT EXPAND PARTIAL
299 DIRECTORY NAMES LIKE YOUR SHELL DOES* (IE not like cp -rf fo* to copy
300 foo/*)
301
302 Allowing Copy Loops
303
304 If you want to allow:
305
306 cp -rf . foo/
307
308 type behavior set $File::Copy::Recursive::CopyLoop to true.
309
310 This is false by default so that a check is done to see if the source
311 directory will contain the target directory and croaks to avoid this
312 problem.
313
314 If you ever find a situation where $CopyLoop = 1 is desirable let me
315 know (IE its a bad bad idea but is there if you want it)
316
317 (Note: On Windows this was necessary since it uses stat() to detemine
318 samedness and stat() is essencially useless for this on Windows. The
319 test is now simply skipped on Windows but I'd rather have an actual
320 reliable check if anyone in Microsoft land would care to share)
321
323 File::Copy File::Spec
324
326 Add OO interface so you can have different behavior with different
327 objects instead of relying on global variables. This will give better
328 control in environments where behavior based on global variables is not
329 very desireable.
330
331 I'll add this after the latest verision has been out for a while with
332 no new features or issues found :)
333
335 Daniel Muey, <http://drmuey.com/cpan_contact.pl>
336
338 Copyright 2004 by Daniel Muey
339
340 This library is free software; you can redistribute it and/or modify it
341 under the same terms as Perl itself.
342
343
344
345perl v5.8.8 2008-04-16 Recursive(3)