Debian Codegraph @

upstream/mageia-cauldron/man3pm/File::Copy.3pm

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