Debian Codegraph @

upstream/debian-unstable/man3/File::Copy.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "File::Copy 3perl"
58 .TH File::Copy 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 File::Copy \- Copy files or filehandles
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use File::Copy;
69 \&
70 \& copy("sourcefile", "destinationfile") or die "Copy failed: $!";
71 \& copy("Copy.pm", \e*STDOUT);
72 \& move("/dev1/sourcefile", "/dev2/destinationfile");
73 \&
74 \& use File::Copy "cp";
75 \&
76 \& my $n = FileHandle\->new("/a/file", "r");
77 \& cp($n, "x");
78 .Ve
79 .SH DESCRIPTION
80 .IX Header "DESCRIPTION"
81 The File::Copy module provides two basic functions, \f(CW\*(C`copy\*(C'\fR and
82 \&\f(CW\*(C`move\*(C'\fR, which are useful for getting the contents of a file from
83 one place to another.
84 .IP copy 4
85 .IX Xref "copy cp"
86 .IX Item "copy"
87 The \f(CW\*(C`copy\*(C'\fR function takes two
88 parameters: a file to copy from and a file to copy to. Either
89 argument may be a string, a FileHandle reference or a FileHandle
90 glob. Obviously, if the first argument is a filehandle of some
91 sort, it will be read from, and if it is a file \fIname\fR it will
92 be opened for reading. Likewise, the second argument will be
93 written to. If the second argument does not exist but the parent
94 directory does exist, then it will be created. Trying to copy
95 a file into a non-existent directory is an error.
96 Trying to copy a file on top of itself is also an error.
97 \&\f(CW\*(C`copy\*(C'\fR will not overwrite read-only files.
98 .Sp
99 If the destination (second argument) already exists and is a directory,
100 and the source (first argument) is not a filehandle, then the source
101 file will be copied into the directory specified by the destination,
102 using the same base name as the source file. It's a failure to have a
103 filehandle as the source when the destination is a directory.
104 .Sp
105 \&\fBNote that passing in
106 files as handles instead of names may lead to loss of information
107 on some operating systems; it is recommended that you use file
108 names whenever possible.\fR Files are opened in binary mode where
109 applicable. To get a consistent behaviour when copying from a
110 filehandle to a file, use \f(CW\*(C`binmode\*(C'\fR on the filehandle.
111 .Sp
112 An optional third parameter can be used to specify the buffer
113 size used for copying. This is the number of bytes from the
114 first file, that will be held in memory at any given time, before
115 being written to the second file. The default buffer size depends
116 upon the file, but will generally be the whole file (up to 2MB), or
117 1k for filehandles that do not reference files (eg. sockets).
118 .Sp
119 You may use the syntax \f(CW\*(C`use File::Copy "cp"\*(C'\fR to get at the \f(CW\*(C`cp\*(C'\fR
120 alias for this function. The syntax is \fIexactly\fR the same. The
121 behavior is nearly the same as well: as of version 2.15, \f(CW\*(C`cp\*(C'\fR will
122 preserve the source file's permission bits like the shell utility
123 \&\f(CWcp(1)\fR would do with default options, while \f(CW\*(C`copy\*(C'\fR uses the default
124 permissions for the target file (which may depend on the process'
125 \&\f(CW\*(C`umask\*(C'\fR, file ownership, inherited ACLs, etc.). That is, if the
126 destination file already exists, \f(CW\*(C`cp\*(C'\fR will leave its permissions
127 unchanged; otherwise the permissions are taken from the source file
128 and modified by the \f(CW\*(C`umask\*(C'\fR. If an error occurs in setting
129 permissions, \f(CW\*(C`cp\*(C'\fR will return 0, regardless of whether the file was
130 successfully copied.
131 .IP move 4
132 .IX Xref "move mv rename"
133 .IX Item "move"
134 The \f(CW\*(C`move\*(C'\fR function also takes two parameters: the current name
135 and the intended name of the file to be moved. If the destination
136 already exists and is a directory, and the source is not a
137 directory, then the source file will be renamed into the directory
138 specified by the destination.
139 .Sp
140 If possible, \fBmove()\fR will simply rename the file. Otherwise, it copies
141 the file to the new location and deletes the original. If an error occurs
142 during this copy-and-delete process, you may be left with a (possibly partial)
143 copy of the file under the destination name.
144 .Sp
145 You may use the \f(CW\*(C`mv\*(C'\fR alias for this function in the same way that
146 you may use the \f(CW\*(C`cp\*(C'\fR alias for \f(CW\*(C`copy\*(C'\fR.
147 .IP syscopy 4
148 .IX Xref "syscopy"
149 .IX Item "syscopy"
150 File::Copy also provides the \f(CW\*(C`syscopy\*(C'\fR routine, which copies the
151 file specified in the first parameter to the file specified in the
152 second parameter, preserving OS-specific attributes and file
153 structure. For Unix systems, this is equivalent to the simple
154 \&\f(CW\*(C`copy\*(C'\fR routine, which doesn't preserve OS-specific attributes. For
155 VMS systems, this calls the \f(CW\*(C`rmscopy\*(C'\fR routine (see below). For OS/2
156 systems, this calls the \f(CW\*(C`syscopy\*(C'\fR XSUB directly. For Win32 systems,
157 this calls \f(CW\*(C`Win32::CopyFile\*(C'\fR.
158 .Sp
159 \&\fBSpecial behaviour if \fR\f(CB\*(C`syscopy\*(C'\fR\fB is defined (OS/2, VMS and Win32)\fR:
160 .Sp
161 If both arguments to \f(CW\*(C`copy\*(C'\fR are not file handles,
162 then \f(CW\*(C`copy\*(C'\fR will perform a "system copy" of
163 the input file to a new output file, in order to preserve file
164 attributes, indexed file structure, \fIetc.\fR The buffer size
165 parameter is ignored. If either argument to \f(CW\*(C`copy\*(C'\fR is a
166 handle to an opened file, then data is copied using Perl
167 operators, and no effort is made to preserve file attributes
168 or record structure.
169 .Sp
170 The system copy routine may also be called directly under VMS and OS/2
171 as \f(CW\*(C`File::Copy::syscopy\*(C'\fR (or under VMS as \f(CW\*(C`File::Copy::rmscopy\*(C'\fR, which
172 is the routine that does the actual work for syscopy).
173 .IP rmscopy($from,$to[,$date_flag]) 4
174 .IX Xref "rmscopy"
175 .IX Item "rmscopy($from,$to[,$date_flag])"
176 The first and second arguments may be strings, typeglobs, typeglob
177 references, or objects inheriting from IO::Handle;
178 they are used in all cases to obtain the
179 \&\fIfilespec\fR of the input and output files, respectively. The
180 name and type of the input file are used as defaults for the
181 output file, if necessary.
182 .Sp
183 A new version of the output file is always created, which
184 inherits the structure and RMS attributes of the input file,
185 except for owner and protections (and possibly timestamps;
186 see below). All data from the input file is copied to the
187 output file; if either of the first two parameters to \f(CW\*(C`rmscopy\*(C'\fR
188 is a file handle, its position is unchanged. (Note that this
189 means a file handle pointing to the output file will be
190 associated with an old version of that file after \f(CW\*(C`rmscopy\*(C'\fR
191 returns, not the newly created version.)
192 .Sp
193 The third parameter is an integer flag, which tells \f(CW\*(C`rmscopy\*(C'\fR
194 how to handle timestamps. If it is < 0, none of the input file's
195 timestamps are propagated to the output file. If it is > 0, then
196 it is interpreted as a bitmask: if bit 0 (the LSB) is set, then
197 timestamps other than the revision date are propagated; if bit 1
198 is set, the revision date is propagated. If the third parameter
199 to \f(CW\*(C`rmscopy\*(C'\fR is 0, then it behaves much like the DCL COPY command:
200 if the name or type of the output file was explicitly specified,
201 then no timestamps are propagated, but if they were taken implicitly
202 from the input filespec, then all timestamps other than the
203 revision date are propagated. If this parameter is not supplied,
204 it defaults to 0.
205 .Sp
206 \&\f(CW\*(C`rmscopy\*(C'\fR is VMS specific and cannot be exported; it must be
207 referenced by its full name, e.g.:
208 .Sp
209 .Vb 1
210 \& File::Copy::rmscopy($from, $to) or die $!;
211 .Ve
212 .Sp
213 Like \f(CW\*(C`copy\*(C'\fR, \f(CW\*(C`rmscopy\*(C'\fR returns 1 on success. If an error occurs,
214 it sets \f(CW$!\fR, deletes the output file, and returns 0.
215 .SH RETURN
216 .IX Header "RETURN"
217 All functions return 1 on success, 0 on failure.
218 $! will be set if an error was encountered.
219 .SH NOTES
220 .IX Header "NOTES"
221 Before calling \fBcopy()\fR or \fBmove()\fR on a filehandle, the caller should
222 close or \fBflush()\fR the file to avoid writes being lost. Note that this
223 is the case even for \fBmove()\fR, because it may actually copy the file,
224 depending on the OS-specific implementation, and the underlying
225 filesystem(s).
226 .SH AUTHOR
227 .IX Header "AUTHOR"
228 File::Copy was written by Aaron Sherman \fI<[email protected]>\fR in 1995,
229 and updated by Charles Bailey \fI<[email protected]>\fR in 1996.