1 # File/Copy.pm. Written in 1994 by Aaron Sherman <ajs@ajs.com>. This
2 # source code has been placed in the public domain by the author.
3 # Please be kind and preserve the documentation.
5 # Additions copyright 1996 by Charles Bailey. Permission is granted
6 # to distribute the revised code under the same terms as Perl itself.
12 use vars qw(@ISA @EXPORT @EXPORT_OK $VERSION $Too_Big
13 © &syscopy &cp &mv);
15 # Note that this module implements only *part* of the API defined by
16 # the File/Copy.pm module of the File-Tools-2.0 package. However, that
17 # package has not yet been updated to work with Perl 5.004, and so it
18 # would be a Bad Thing for the CPAN module to grab it and replace this
19 # module. Therefore, we set this module's version higher than 2.0.
24 @EXPORT = qw(copy move);
25 @EXPORT_OK = qw(cp mv);
27 $Too_Big = 1024 * 1024 * 2;
29 sub _catname { # Will be replaced by File::Spec when it arrives
31 if (not defined &basename) {
32 require File::Basename;
33 import File::Basename 'basename';
35 if ($^O eq 'VMS') { $to = VMS::Filespec::vmspath($to) . basename($from); }
36 elsif ($^O eq 'MacOS') { $to .= ':' . basename($from); }
37 elsif ($to =~ m|\\|) { $to .= '\\' . basename($from); }
38 else { $to .= '/' . basename($from); }
42 croak("Usage: copy(FROM, TO [, BUFFERSIZE]) ")
43 unless(@_ == 2 || @_ == 3);
48 my $from_a_handle = (ref($from)
49 ? (ref($from) eq 'GLOB'
50 || UNIVERSAL::isa($from, 'GLOB')
51 || UNIVERSAL::isa($from, 'IO::Handle'))
52 : (ref(\$from) eq 'GLOB'));
53 my $to_a_handle = (ref($to)
55 || UNIVERSAL::isa($to, 'GLOB')
56 || UNIVERSAL::isa($to, 'IO::Handle'))
57 : (ref(\$to) eq 'GLOB'));
59 if (!$from_a_handle && !$to_a_handle && -d $to && ! -d $from) {
60 $to = _catname($from, $to);
63 if (defined &syscopy && \&syscopy != \©
65 && !($from_a_handle && $^O eq 'os2')) # OS/2 cannot handle handles
67 return syscopy($from, $to);
72 my ($size, $status, $r, $buf);
77 *FROM = *$from{FILEHANDLE};
79 $from = "./$from" if $from =~ /^\s/;
80 open(FROM, "< $from\0") or goto fail_open1;
81 binmode FROM or die "($!,$^E)";
86 *TO = *$to{FILEHANDLE};
88 $to = "./$to" if $to =~ /^\s/;
89 open(TO,"> $to\0") or goto fail_open2;
90 binmode TO or die "($!,$^E)";
95 $size = shift(@_) + 0;
96 croak("Bad buffer size for copy: $size\n") unless ($size > 0);
99 $size = 1024 if ($size < 512);
100 $size = $Too_Big if ($size > $Too_Big);
106 defined($r = sysread(FROM, $buf, $size))
109 for ($w = 0; $w < $r; $w += $t) {
110 $t = syswrite(TO, $buf, $r - $w, $w)
115 close(TO) || goto fail_open2 if $closeto;
116 close(FROM) || goto fail_open1 if $closefrom;
118 # Use this idiom to avoid uninitialized value warning.
121 # All of these contortions try to preserve error messages...
127 $! = $status unless $!;
134 $! = $status unless $!;
142 my($copied,$fromsz,$tosz1,$tomt1,$tosz2,$tomt2,$sts,$ossts);
144 if (-d $to && ! -d $from) {
145 $to = _catname($from, $to);
148 ($tosz1,$tomt1) = (stat($to))[7,9];
150 if ($^O eq 'os2' and defined $tosz1 and defined $fromsz) {
151 # will not rename with overwrite
154 return 1 if rename $from, $to;
156 ($sts,$ossts) = ($! + 0, $^E + 0);
157 # Did rename return an error even though it succeeded, because $to
158 # is on a remote NFS file system, and NFS lost the server's ack?
159 return 1 if defined($fromsz) && !-e $from && # $from disappeared
160 (($tosz2,$tomt2) = (stat($to))[7,9]) && # $to's there
161 ($tosz1 != $tosz2 or $tomt1 != $tomt2) && # and changed
162 $tosz2 == $fromsz; # it's all there
164 ($tosz1,$tomt1) = (stat($to))[7,9]; # just in case rename did something
165 return 1 if ($copied = copy($from,$to)) && unlink($from);
167 ($tosz2,$tomt2) = ((stat($to))[7,9],0,0) if defined $tomt1;
168 unlink($to) if !defined($tomt1) or $tomt1 != $tomt2 or $tosz1 != $tosz2;
169 ($!,$^E) = ($sts,$ossts);
176 # &syscopy is an XSUB under OS/2
177 *syscopy = ($^O eq 'VMS' ? \&rmscopy : \©) unless defined &syscopy;
185 File::Copy - Copy files or filehandles
191 copy("file1","file2");
192 copy("Copy.pm",\*STDOUT);'
193 move("/dev1/fileA","/dev2/fileB");
198 $n=FileHandle->new("/dev/null","r");
203 The File::Copy module provides two basic functions, C<copy> and
204 C<move>, which are useful for getting the contents of a file from
205 one place to another.
211 The C<copy> function takes two
212 parameters: a file to copy from and a file to copy to. Either
213 argument may be a string, a FileHandle reference or a FileHandle
214 glob. Obviously, if the first argument is a filehandle of some
215 sort, it will be read from, and if it is a file I<name> it will
216 be opened for reading. Likewise, the second argument will be
217 written to (and created if need be).
219 B<Note that passing in
220 files as handles instead of names may lead to loss of information
221 on some operating systems; it is recommended that you use file
222 names whenever possible.> Files are opened in binary mode where
223 applicable. To get a consistent behavour when copying from a
224 filehandle to a file, use C<binmode> on the filehandle.
226 An optional third parameter can be used to specify the buffer
227 size used for copying. This is the number of bytes from the
228 first file, that wil be held in memory at any given time, before
229 being written to the second file. The default buffer size depends
230 upon the file, but will generally be the whole file (up to 2Mb), or
231 1k for filehandles that do not reference files (eg. sockets).
233 You may use the syntax C<use File::Copy "cp"> to get at the
234 "cp" alias for this function. The syntax is I<exactly> the same.
238 The C<move> function also takes two parameters: the current name
239 and the intended name of the file to be moved. If the destination
240 already exists and is a directory, and the source is not a
241 directory, then the source file will be renamed into the directory
242 specified by the destination.
244 If possible, move() will simply rename the file. Otherwise, it copies
245 the file to the new location and deletes the original. If an error occurs
246 during this copy-and-delete process, you may be left with a (possibly partial)
247 copy of the file under the destination name.
249 You may use the "mv" alias for this function in the same way that
250 you may use the "cp" alias for C<copy>.
254 File::Copy also provides the C<syscopy> routine, which copies the
255 file specified in the first parameter to the file specified in the
256 second parameter, preserving OS-specific attributes and file
257 structure. For Unix systems, this is equivalent to the simple
258 C<copy> routine. For VMS systems, this calls the C<rmscopy>
259 routine (see below). For OS/2 systems, this calls the C<syscopy>
262 =head2 Special behavior if C<syscopy> is defined (VMS and OS/2)
264 If both arguments to C<copy> are not file handles,
265 then C<copy> will perform a "system copy" of
266 the input file to a new output file, in order to preserve file
267 attributes, indexed file structure, I<etc.> The buffer size
268 parameter is ignored. If either argument to C<copy> is a
269 handle to an opened file, then data is copied using Perl
270 operators, and no effort is made to preserve file attributes
273 The system copy routine may also be called directly under VMS and OS/2
274 as C<File::Copy::syscopy> (or under VMS as C<File::Copy::rmscopy>, which
275 is the routine that does the actual work for syscopy).
279 =item rmscopy($from,$to[,$date_flag])
281 The first and second arguments may be strings, typeglobs, typeglob
282 references, or objects inheriting from IO::Handle;
283 they are used in all cases to obtain the
284 I<filespec> of the input and output files, respectively. The
285 name and type of the input file are used as defaults for the
286 output file, if necessary.
288 A new version of the output file is always created, which
289 inherits the structure and RMS attributes of the input file,
290 except for owner and protections (and possibly timestamps;
291 see below). All data from the input file is copied to the
292 output file; if either of the first two parameters to C<rmscopy>
293 is a file handle, its position is unchanged. (Note that this
294 means a file handle pointing to the output file will be
295 associated with an old version of that file after C<rmscopy>
296 returns, not the newly created version.)
298 The third parameter is an integer flag, which tells C<rmscopy>
299 how to handle timestamps. If it is E<lt> 0, none of the input file's
300 timestamps are propagated to the output file. If it is E<gt> 0, then
301 it is interpreted as a bitmask: if bit 0 (the LSB) is set, then
302 timestamps other than the revision date are propagated; if bit 1
303 is set, the revision date is propagated. If the third parameter
304 to C<rmscopy> is 0, then it behaves much like the DCL COPY command:
305 if the name or type of the output file was explicitly specified,
306 then no timestamps are propagated, but if they were taken implicitly
307 from the input filespec, then all timestamps other than the
308 revision date are propagated. If this parameter is not supplied,
311 Like C<copy>, C<rmscopy> returns 1 on success. If an error occurs,
312 it sets C<$!>, deletes the output file, and returns 0.
318 All functions return 1 on success, 0 on failure.
319 $! will be set if an error was encountered.
323 File::Copy was written by Aaron Sherman I<E<lt>ajs@ajs.comE<gt>> in 1995,
324 and updated by Charles Bailey I<E<lt>bailey@genetics.upenn.eduE<gt>> in 1996.