This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
s/USE_TEXTMODE_SCRIPTS/PERL_TEXTMODE_SCRIPTS/g
[perl5.git] / lib / File / Copy.pm
CommitLineData
f716a1dd 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.
4#
71be2cbc 5# Additions copyright 1996 by Charles Bailey. Permission is granted
6# to distribute the revised code under the same terms as Perl itself.
f716a1dd 7
8package File::Copy;
9
71be2cbc 10use strict;
f716a1dd 11use Carp;
71be2cbc 12use vars qw(@ISA @EXPORT @EXPORT_OK $VERSION $Too_Big
13 &copy &syscopy &cp &mv);
14
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.
e6434134 20$VERSION = '2.02';
f716a1dd 21
71be2cbc 22require Exporter;
23@ISA = qw(Exporter);
24@EXPORT = qw(copy move);
25@EXPORT_OK = qw(cp mv);
f716a1dd 26
441496b2 27$Too_Big = 1024 * 1024 * 2;
f716a1dd 28
71be2cbc 29sub _catname { # Will be replaced by File::Spec when it arrives
30 my($from, $to) = @_;
31 if (not defined &basename) {
32 require File::Basename;
33 import File::Basename 'basename';
34 }
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); }
f716a1dd 39}
40
41sub copy {
71be2cbc 42 croak("Usage: copy(FROM, TO [, BUFFERSIZE]) ")
f716a1dd 43 unless(@_ == 2 || @_ == 3);
44
45 my $from = shift;
46 my $to = shift;
71be2cbc 47
48 my $from_a_handle = (ref($from)
49 ? (ref($from) eq 'GLOB'
d704f39a
MG
50 || UNIVERSAL::isa($from, 'GLOB')
51 || UNIVERSAL::isa($from, 'IO::Handle'))
71be2cbc 52 : (ref(\$from) eq 'GLOB'));
53 my $to_a_handle = (ref($to)
54 ? (ref($to) eq 'GLOB'
d704f39a
MG
55 || UNIVERSAL::isa($to, 'GLOB')
56 || UNIVERSAL::isa($to, 'IO::Handle'))
71be2cbc 57 : (ref(\$to) eq 'GLOB'));
58
59 if (!$from_a_handle && !$to_a_handle && -d $to && ! -d $from) {
60 $to = _catname($from, $to);
61 }
62
63 if (defined &syscopy && \&syscopy != \&copy
e6434134 64 && !$to_a_handle
1d84e8df
JH
65 && !($from_a_handle && $^O eq 'os2' ) # OS/2 cannot handle handles
66 && !($from_a_handle && $^O eq 'mpeix') # and neither can MPE/iX.
7509b657 67 && !($from_a_handle && $^O eq 'MSWin32')
1d84e8df 68 )
71be2cbc 69 {
70 return syscopy($from, $to);
71 }
72
73 my $closefrom = 0;
74 my $closeto = 0;
f716a1dd 75 my ($size, $status, $r, $buf);
76 local(*FROM, *TO);
48a5c399 77 local($\) = '';
f716a1dd 78
71be2cbc 79 if ($from_a_handle) {
80 *FROM = *$from{FILEHANDLE};
f716a1dd 81 } else {
71be2cbc 82 $from = "./$from" if $from =~ /^\s/;
83 open(FROM, "< $from\0") or goto fail_open1;
84 binmode FROM or die "($!,$^E)";
f716a1dd 85 $closefrom = 1;
71be2cbc 86 }
87
88 if ($to_a_handle) {
89 *TO = *$to{FILEHANDLE};
90 } else {
91 $to = "./$to" if $to =~ /^\s/;
92 open(TO,"> $to\0") or goto fail_open2;
93 binmode TO or die "($!,$^E)";
94 $closeto = 1;
95 }
f716a1dd 96
97 if (@_) {
98 $size = shift(@_) + 0;
99 croak("Bad buffer size for copy: $size\n") unless ($size > 0);
100 } else {
101 $size = -s FROM;
102 $size = 1024 if ($size < 512);
441496b2 103 $size = $Too_Big if ($size > $Too_Big);
f716a1dd 104 }
105
71be2cbc 106 $! = 0;
107 for (;;) {
108 my ($r, $w, $t);
109 defined($r = sysread(FROM, $buf, $size))
110 or goto fail_inner;
111 last unless $r;
112 for ($w = 0; $w < $r; $w += $t) {
113 $t = syswrite(TO, $buf, $r - $w, $w)
114 or goto fail_inner;
f716a1dd 115 }
116 }
71be2cbc 117
f716a1dd 118 close(TO) || goto fail_open2 if $closeto;
119 close(FROM) || goto fail_open1 if $closefrom;
71be2cbc 120
48a5c399 121 # Use this idiom to avoid uninitialized value warning.
f716a1dd 122 return 1;
123
124 # All of these contortions try to preserve error messages...
125 fail_inner:
126 if ($closeto) {
127 $status = $!;
128 $! = 0;
129 close TO;
130 $! = $status unless $!;
131 }
132 fail_open2:
133 if ($closefrom) {
134 $status = $!;
135 $! = 0;
136 close FROM;
137 $! = $status unless $!;
138 }
139 fail_open1:
f716a1dd 140 return 0;
141}
9b957b78 142
441496b2 143sub move {
71be2cbc 144 my($from,$to) = @_;
145 my($copied,$fromsz,$tosz1,$tomt1,$tosz2,$tomt2,$sts,$ossts);
441496b2 146
71be2cbc 147 if (-d $to && ! -d $from) {
148 $to = _catname($from, $to);
149 }
150
151 ($tosz1,$tomt1) = (stat($to))[7,9];
152 $fromsz = -s $from;
e6434134
IZ
153 if ($^O eq 'os2' and defined $tosz1 and defined $fromsz) {
154 # will not rename with overwrite
155 unlink $to;
156 }
71be2cbc 157 return 1 if rename $from, $to;
158
159 ($sts,$ossts) = ($! + 0, $^E + 0);
160 # Did rename return an error even though it succeeded, because $to
161 # is on a remote NFS file system, and NFS lost the server's ack?
162 return 1 if defined($fromsz) && !-e $from && # $from disappeared
163 (($tosz2,$tomt2) = (stat($to))[7,9]) && # $to's there
164 ($tosz1 != $tosz2 or $tomt1 != $tomt2) && # and changed
165 $tosz2 == $fromsz; # it's all there
441496b2 166
71be2cbc 167 ($tosz1,$tomt1) = (stat($to))[7,9]; # just in case rename did something
168 return 1 if ($copied = copy($from,$to)) && unlink($from);
441496b2 169
71be2cbc 170 ($tosz2,$tomt2) = ((stat($to))[7,9],0,0) if defined $tomt1;
171 unlink($to) if !defined($tomt1) or $tomt1 != $tomt2 or $tosz1 != $tosz2;
172 ($!,$^E) = ($sts,$ossts);
173 return 0;
441496b2 174}
9b957b78 175
71be2cbc 176*cp = \&copy;
177*mv = \&move;
178
9b957b78 179# &syscopy is an XSUB under OS/2
1d84e8df
JH
180unless (defined &syscopy) {
181 if ($^O eq 'VMS') {
182 *syscopy = \&rmscopy;
183 } elsif ($^O eq 'mpeix') {
184 *syscopy = sub {
3f5ee302 185 return 0 unless @_ == 2;
1d84e8df
JH
186 # Use the MPE cp program in order to
187 # preserve MPE file attributes.
188 return system('/bin/cp', '-f', $_[0], $_[1]) == 0;
189 };
7509b657
GS
190 } elsif ($^O eq 'MSWin32') {
191 *syscopy = sub {
192 return 0 unless @_ == 2;
193 return Win32::CopyFile(@_, 1);
194 };
1d84e8df
JH
195 } else {
196 *syscopy = \&copy;
197 }
198}
f716a1dd 199
2001;
201
202__END__
a5f75d66 203
f716a1dd 204=head1 NAME
205
206File::Copy - Copy files or filehandles
207
a5f75d66 208=head1 SYNOPSIS
f716a1dd 209
210 use File::Copy;
211
212 copy("file1","file2");
213 copy("Copy.pm",\*STDOUT);'
441496b2 214 move("/dev1/fileA","/dev2/fileB");
f716a1dd 215
216 use POSIX;
217 use File::Copy cp;
218
219 $n=FileHandle->new("/dev/null","r");
220 cp($n,"x");'
221
222=head1 DESCRIPTION
223
441496b2
CB
224The File::Copy module provides two basic functions, C<copy> and
225C<move>, which are useful for getting the contents of a file from
226one place to another.
227
228=over 4
229
230=item *
231
232The C<copy> function takes two
f716a1dd 233parameters: a file to copy from and a file to copy to. Either
234argument may be a string, a FileHandle reference or a FileHandle
235glob. Obviously, if the first argument is a filehandle of some
236sort, it will be read from, and if it is a file I<name> it will
237be opened for reading. Likewise, the second argument will be
e6434134 238written to (and created if need be).
71be2cbc 239
240B<Note that passing in
9b957b78 241files as handles instead of names may lead to loss of information
242on some operating systems; it is recommended that you use file
e6434134 243names whenever possible.> Files are opened in binary mode where
8dcee03e 244applicable. To get a consistent behaviour when copying from a
e6434134 245filehandle to a file, use C<binmode> on the filehandle.
f716a1dd 246
247An optional third parameter can be used to specify the buffer
248size used for copying. This is the number of bytes from the
249first file, that wil be held in memory at any given time, before
250being written to the second file. The default buffer size depends
251upon the file, but will generally be the whole file (up to 2Mb), or
2521k for filehandles that do not reference files (eg. sockets).
253
254You may use the syntax C<use File::Copy "cp"> to get at the
255"cp" alias for this function. The syntax is I<exactly> the same.
256
441496b2
CB
257=item *
258
259The C<move> function also takes two parameters: the current name
71be2cbc 260and the intended name of the file to be moved. If the destination
261already exists and is a directory, and the source is not a
262directory, then the source file will be renamed into the directory
263specified by the destination.
264
265If possible, move() will simply rename the file. Otherwise, it copies
266the file to the new location and deletes the original. If an error occurs
267during this copy-and-delete process, you may be left with a (possibly partial)
441496b2
CB
268copy of the file under the destination name.
269
270You may use the "mv" alias for this function in the same way that
271you may use the "cp" alias for C<copy>.
272
273=back
274
9b957b78 275File::Copy also provides the C<syscopy> routine, which copies the
276file specified in the first parameter to the file specified in the
277second parameter, preserving OS-specific attributes and file
278structure. For Unix systems, this is equivalent to the simple
279C<copy> routine. For VMS systems, this calls the C<rmscopy>
280routine (see below). For OS/2 systems, this calls the C<syscopy>
7509b657 281XSUB directly. For Win32 systems, this calls C<Win32::CopyFile>.
9b957b78 282
7509b657 283=head2 Special behaviour if C<syscopy> is defined (OS/2, VMS and Win32)
9b957b78 284
71be2cbc 285If both arguments to C<copy> are not file handles,
286then C<copy> will perform a "system copy" of
9b957b78 287the input file to a new output file, in order to preserve file
288attributes, indexed file structure, I<etc.> The buffer size
71be2cbc 289parameter is ignored. If either argument to C<copy> is a
290handle to an opened file, then data is copied using Perl
9b957b78 291operators, and no effort is made to preserve file attributes
292or record structure.
293
55497cff 294The system copy routine may also be called directly under VMS and OS/2
295as C<File::Copy::syscopy> (or under VMS as C<File::Copy::rmscopy>, which
71be2cbc 296is the routine that does the actual work for syscopy).
9b957b78 297
441496b2 298=over 4
55497cff 299
9b957b78 300=item rmscopy($from,$to[,$date_flag])
301
71be2cbc 302The first and second arguments may be strings, typeglobs, typeglob
303references, or objects inheriting from IO::Handle;
304they are used in all cases to obtain the
9b957b78 305I<filespec> of the input and output files, respectively. The
306name and type of the input file are used as defaults for the
307output file, if necessary.
308
309A new version of the output file is always created, which
310inherits the structure and RMS attributes of the input file,
311except for owner and protections (and possibly timestamps;
312see below). All data from the input file is copied to the
313output file; if either of the first two parameters to C<rmscopy>
314is a file handle, its position is unchanged. (Note that this
315means a file handle pointing to the output file will be
316associated with an old version of that file after C<rmscopy>
317returns, not the newly created version.)
318
319The third parameter is an integer flag, which tells C<rmscopy>
1fef88e7
JM
320how to handle timestamps. If it is E<lt> 0, none of the input file's
321timestamps are propagated to the output file. If it is E<gt> 0, then
9b957b78 322it is interpreted as a bitmask: if bit 0 (the LSB) is set, then
323timestamps other than the revision date are propagated; if bit 1
324is set, the revision date is propagated. If the third parameter
325to C<rmscopy> is 0, then it behaves much like the DCL COPY command:
326if the name or type of the output file was explicitly specified,
327then no timestamps are propagated, but if they were taken implicitly
328from the input filespec, then all timestamps other than the
329revision date are propagated. If this parameter is not supplied,
330it defaults to 0.
331
332Like C<copy>, C<rmscopy> returns 1 on success. If an error occurs,
333it sets C<$!>, deletes the output file, and returns 0.
334
55497cff 335=back
336
f716a1dd 337=head1 RETURN
338
441496b2
CB
339All functions return 1 on success, 0 on failure.
340$! will be set if an error was encountered.
f716a1dd 341
342=head1 AUTHOR
343
441496b2 344File::Copy was written by Aaron Sherman I<E<lt>ajs@ajs.comE<gt>> in 1995,
bd3fa61c 345and updated by Charles Bailey I<E<lt>bailey@newman.upenn.eduE<gt>> in 1996.
f716a1dd 346
347=cut
441496b2 348