File::Copy::Recursive(3pm)

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

TO DO

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

AUTHOR

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

COPYRIGHT AND LICENSE

356       Copyright 2004 by Daniel Muey
357
358       This library is free software; you can redistribute it and/or modify it
359       under the same terms as Perl itself.
360
361
362
363perl v5.34.0                      2021-07-22          File::Copy::Recursive(3)