This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
xsubpp patch to add #line
[perl5.git] / lib / File / Copy.pm
CommitLineData
f716a1dd
PP
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#
5
6package File::Copy;
7
8require Exporter;
9use Carp;
55497cff 10use UNIVERSAL qw(isa);
f716a1dd
PP
11
12@ISA=qw(Exporter);
13@EXPORT=qw(copy);
14@EXPORT_OK=qw(copy cp);
15
16$File::Copy::VERSION = '1.5';
17$File::Copy::Too_Big = 1024 * 1024 * 2;
18
19sub VERSION {
20 # Version of File::Copy
21 return $File::Copy::VERSION;
22}
23
24sub copy {
25 croak("Usage: copy( file1, file2 [, buffersize]) ")
26 unless(@_ == 2 || @_ == 3);
27
55497cff
PP
28 if (defined &File::Copy::syscopy &&
29 \&File::Copy::syscopy != \&File::Copy::copy &&
30 ref(\$_[1]) ne 'GLOB' &&
31 !(defined ref $_[1] and isa($_[1], 'GLOB')))
32 { return File::Copy::syscopy($_[0],$_[1]) }
a5f75d66 33
f716a1dd
PP
34 my $from = shift;
35 my $to = shift;
f716a1dd
PP
36 my $closefrom=0;
37 my $closeto=0;
38 my ($size, $status, $r, $buf);
39 local(*FROM, *TO);
48a5c399 40 local($\) = '';
f716a1dd
PP
41
42 if (ref(\$from) eq 'GLOB') {
43 *FROM = $from;
44 } elsif (defined ref $from and
9b957b78
PP
45 (ref($from) eq 'GLOB' || ref($from) eq 'FileHandle' ||
46 ref($from) eq 'VMS::Stdio')) {
f716a1dd
PP
47 *FROM = *$from;
48 } else {
49 open(FROM,"<$from")||goto(fail_open1);
9b957b78 50 binmode FROM;
f716a1dd
PP
51 $closefrom = 1;
52 }
53
54 if (ref(\$to) eq 'GLOB') {
55 *TO = $to;
56 } elsif (defined ref $to and
9b957b78
PP
57 (ref($to) eq 'GLOB' || ref($to) eq 'FileHandle' ||
58 ref($to) eq 'VMS::Stdio')) {
f716a1dd
PP
59 *TO = *$to;
60 } else {
61 open(TO,">$to")||goto(fail_open2);
9b957b78 62 binmode TO;
f716a1dd
PP
63 $closeto=1;
64 }
65
66 if (@_) {
67 $size = shift(@_) + 0;
68 croak("Bad buffer size for copy: $size\n") unless ($size > 0);
69 } else {
70 $size = -s FROM;
71 $size = 1024 if ($size < 512);
72 $size = $File::Copy::Too_Big if ($size > $File::Copy::Too_Big);
73 }
74
75 $buf = '';
76 while(defined($r = read(FROM,$buf,$size)) && $r > 0) {
77 if (syswrite (TO,$buf,$r) != $r) {
78 goto fail_inner;
79 }
80 }
81 goto fail_inner unless(defined($r));
82 close(TO) || goto fail_open2 if $closeto;
83 close(FROM) || goto fail_open1 if $closefrom;
48a5c399 84 # Use this idiom to avoid uninitialized value warning.
f716a1dd
PP
85 return 1;
86
87 # All of these contortions try to preserve error messages...
88 fail_inner:
89 if ($closeto) {
90 $status = $!;
91 $! = 0;
92 close TO;
93 $! = $status unless $!;
94 }
95 fail_open2:
96 if ($closefrom) {
97 $status = $!;
98 $! = 0;
99 close FROM;
100 $! = $status unless $!;
101 }
102 fail_open1:
f716a1dd
PP
103 return 0;
104}
9b957b78
PP
105
106
f716a1dd 107*cp = \&copy;
9b957b78
PP
108# &syscopy is an XSUB under OS/2
109*syscopy = ($^O eq 'VMS' ? \&rmscopy : \&copy) unless $^O eq 'os2';
f716a1dd
PP
110
1111;
112
113__END__
a5f75d66 114
f716a1dd
PP
115=head1 NAME
116
117File::Copy - Copy files or filehandles
118
a5f75d66 119=head1 SYNOPSIS
f716a1dd
PP
120
121 use File::Copy;
122
123 copy("file1","file2");
124 copy("Copy.pm",\*STDOUT);'
125
126 use POSIX;
127 use File::Copy cp;
128
129 $n=FileHandle->new("/dev/null","r");
130 cp($n,"x");'
131
132=head1 DESCRIPTION
133
9b957b78 134The File::Copy module provides a basic function C<copy> which takes two
f716a1dd
PP
135parameters: a file to copy from and a file to copy to. Either
136argument may be a string, a FileHandle reference or a FileHandle
137glob. Obviously, if the first argument is a filehandle of some
138sort, it will be read from, and if it is a file I<name> it will
139be opened for reading. Likewise, the second argument will be
9b957b78
PP
140written to (and created if need be). Note that passing in
141files as handles instead of names may lead to loss of information
142on some operating systems; it is recommended that you use file
143names whenever possible.
f716a1dd
PP
144
145An optional third parameter can be used to specify the buffer
146size used for copying. This is the number of bytes from the
147first file, that wil be held in memory at any given time, before
148being written to the second file. The default buffer size depends
149upon the file, but will generally be the whole file (up to 2Mb), or
1501k for filehandles that do not reference files (eg. sockets).
151
152You may use the syntax C<use File::Copy "cp"> to get at the
153"cp" alias for this function. The syntax is I<exactly> the same.
154
9b957b78
PP
155File::Copy also provides the C<syscopy> routine, which copies the
156file specified in the first parameter to the file specified in the
157second parameter, preserving OS-specific attributes and file
158structure. For Unix systems, this is equivalent to the simple
159C<copy> routine. For VMS systems, this calls the C<rmscopy>
160routine (see below). For OS/2 systems, this calls the C<syscopy>
161XSUB directly.
162
55497cff 163=head2 Special behavior if C<syscopy> is defined (VMS and OS/2)
9b957b78
PP
164
165If the second argument to C<copy> is not a file handle for an
55497cff 166already opened file, then C<copy> will perform an "system copy" of
9b957b78
PP
167the input file to a new output file, in order to preserve file
168attributes, indexed file structure, I<etc.> The buffer size
169parameter is ignored. If the second argument to C<copy> is a
170Perl handle to an opened file, then data is copied using Perl
171operators, and no effort is made to preserve file attributes
172or record structure.
173
55497cff
PP
174The system copy routine may also be called directly under VMS and OS/2
175as C<File::Copy::syscopy> (or under VMS as C<File::Copy::rmscopy>, which
9b957b78
PP
176is just an alias for this routine).
177
55497cff
PP
178=over
179
9b957b78
PP
180=item rmscopy($from,$to[,$date_flag])
181
182The first and second arguments may be strings, typeglobs, or
183typeglob references; they are used in all cases to obtain the
184I<filespec> of the input and output files, respectively. The
185name and type of the input file are used as defaults for the
186output file, if necessary.
187
188A new version of the output file is always created, which
189inherits the structure and RMS attributes of the input file,
190except for owner and protections (and possibly timestamps;
191see below). All data from the input file is copied to the
192output file; if either of the first two parameters to C<rmscopy>
193is a file handle, its position is unchanged. (Note that this
194means a file handle pointing to the output file will be
195associated with an old version of that file after C<rmscopy>
196returns, not the newly created version.)
197
198The third parameter is an integer flag, which tells C<rmscopy>
1fef88e7
JM
199how to handle timestamps. If it is E<lt> 0, none of the input file's
200timestamps are propagated to the output file. If it is E<gt> 0, then
9b957b78
PP
201it is interpreted as a bitmask: if bit 0 (the LSB) is set, then
202timestamps other than the revision date are propagated; if bit 1
203is set, the revision date is propagated. If the third parameter
204to C<rmscopy> is 0, then it behaves much like the DCL COPY command:
205if the name or type of the output file was explicitly specified,
206then no timestamps are propagated, but if they were taken implicitly
207from the input filespec, then all timestamps other than the
208revision date are propagated. If this parameter is not supplied,
209it defaults to 0.
210
211Like C<copy>, C<rmscopy> returns 1 on success. If an error occurs,
212it sets C<$!>, deletes the output file, and returns 0.
213
55497cff
PP
214=back
215
f716a1dd
PP
216=head1 RETURN
217
218Returns 1 on success, 0 on failure. $! will be set if an error was
219encountered.
220
221=head1 AUTHOR
222
9b957b78
PP
223File::Copy was written by Aaron Sherman I<E<lt>ajs@ajs.comE<gt>> in 1995.
224The VMS-specific code was added by Charles Bailey
225I<E<lt>bailey@genetics.upenn.eduE<gt>> in March 1996.
f716a1dd
PP
226
227=cut