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
20         rcopy_glob("orig/stuff-*", $trg [, $buf]) or die $!;
21         rmove_glob("orig/stuff-*", $trg [,$buf]) or die $!;
22

DESCRIPTION

24       This module copies and moves directories recursively (or single files,
25       well... singley) to an optional depth and attempts to preserve each
26       file or directory's mode.
27

EXPORT

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

TO DO

337       I am currently working on and reviewing some other modules to use in
338       the new interface so we can lose the horrid globals as well as some
339       other undesirable traits and also more easily make available some long
340       standing requests.
341
342       Tests will be easier to do with the new interface and hence the testing
343       focus will shift to the new interface and aim to be comprehensive.
344
345       The old interface will work, it just won't be brought in until it is
346       used, so it will add no overhead for users of the new interface.
347
348       I'll add this after the latest verision has been out for a while with
349       no new features or issues found :)
350

AUTHOR

352       Daniel Muey, <http://drmuey.com/cpan_contact.pl>
353

COPYRIGHT AND LICENSE

355       Copyright 2004 by Daniel Muey
356
357       This library is free software; you can redistribute it and/or modify it
358       under the same terms as Perl itself.
359
360
361
362perl v5.16.3                      2008-11-20                      Recursive(3)