File::Copy::Recursive(3pm)

1Recursive(3)          User Contributed Perl Documentation         Recursive(3)
2
3
4

NAME

6       File::Copy::Recursive - Perl extension for recursively copying files
7       and directories
8

SYNOPSIS

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

DESCRIPTION

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

EXPORT

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

TO DO

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

AUTHOR

335       Daniel Muey, <http://drmuey.com/cpan_contact.pl>
336

COPYRIGHT AND LICENSE

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)