1 '\" te
2 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved
3 .\" Copyright 1989 AT&T
4 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
6 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
8 .\" This notice shall appear on any product containing this material.
9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
12 .TH CP 1 "Oct 30, 2007"
13 .SH NAME
14 cp \- copy files
15 .SH SYNOPSIS
16 .LP
17 .nf
18 \fB/usr/bin/cp\fR [\fB-fip@/\fR] \fIsource_file\fR \fItarget_file\fR
19 .fi
20
21 .LP
22 .nf
23 \fB/usr/bin/cp\fR [\fB-fip@/\fR] \fIsource_file\fR... \fItarget\fR
24 .fi
25
26 .LP
27 .nf
28 \fB/usr/bin/cp\fR \fB-r\fR | \fB-R\fR [\fB-H\fR | \fB-L\fR | \fB-P\fR] [\fB-fip@/\fR] \fIsource_dir\fR... \fItarget\fR
29 .fi
30
31 .LP
32 .nf
33 \fB/usr/bin/cp\fR \fB-R\fR | \fB-R\fR [\fB-H\fR | \fB-L\fR | \fB-P\fR] [\fB-fip@/\fR] \fIsource_dir\fR... \fItarget\fR
34 .fi
35
36 .LP
37 .nf
38 \fB/usr/xpg4/bin/cp\fR [\fB-fip@/\fR] \fIsource_file\fR \fItarget_file\fR
39 .fi
40
41 .LP
42 .nf
43 \fB/usr/xpg4/bin/cp\fR [\fB-fip@/\fR] \fIsource_file\fR... \fItarget\fR
44 .fi
45
46 .LP
47 .nf
48 \fB/usr/xpg4/bin/cp\fR \fB-r\fR | \fB-R\fR [\fB-H\fR | \fB-L\fR | \fB-P\fR] [\fB-fip@/\fR] \fIsource_dir\fR... \fItarget\fR
49 .fi
50
51 .LP
52 .nf
53 \fB/usr/xpg4/bin/cp\fR \fB-R\fR | \fB-R\fR [\fB-H\fR | \fB-L\fR | \fB-P\fR] [\fB-fip@/\fR] \fIsource_dir\fR... \fItarget\fR
54 .fi
55
56 .SH DESCRIPTION
57 .sp
58 .LP
59 In the first synopsis form, neither \fIsource_file\fR nor \fItarget_file\fR are
60 directory files, nor can they have the same name. The \fBcp\fR utility copies
61 the contents of \fIsource_file\fR to the destination path named by
62 \fItarget_file\fR. If \fItarget_file\fR exists, \fBcp\fR overwrites its
63 contents, but the mode (and \fBACL\fR if applicable), owner, and group
64 associated with it are not changed. The last modification time of
65 \fItarget_file\fR and the last access time of \fIsource_file\fR are set to the
66 time the copy was made. If \fItarget_file\fR does not exist, \fBcp\fR creates a
67 new file named \fItarget_file\fR that has the same mode as \fIsource_file\fR
68 except that the sticky bit is not set unless the user is super-user. In this
69 case, the owner and group of \fItarget_file\fR are those of the user, unless
70 the setgid bit is set on the directory containing the newly created file. If
71 the directory's setgid bit is set, the newly created file has the group of the
72 containing directory rather than of the creating user. If \fItarget_file\fR is
73 a link to another file, \fBcp\fR overwrites the link destination with the
74 contents of \fIsource_file\fR; the link(s) from \fItarget_file\fR remains.
75 .sp
76 .LP
77 In the second synopsis form, one or more \fIsource_file\fRs are copied to the
78 directory specified by \fItarget\fR. It is an error if any \fIsource_file\fR is
79 a file of type directory, if \fItarget\fR either does not exist or is not a
80 directory.
81 .sp
82 .LP
83 In the third or fourth synopsis forms, one or more directories specified by
84 \fIsource_dir\fR are copied to the directory specified by \fItarget\fR. Either
85 the \fB-r\fR or \fB-R\fR must be specified. For each \fIsource_dir\fR, \fBcp\fR
86 copies all files and subdirectories.
87 .SH OPTIONS
88 .sp
89 .LP
90 The following options are supported for both \fB/usr/bin/cp\fR and
91 \fB/usr/xpg4/bin/cp\fR:
92 .sp
93 .ne 2
94 .na
95 \fB\fB-f\fR\fR
96 .ad
97 .RS 6n
98 Unlink. If a file descriptor for a destination file cannot be obtained, this
99 option attempts to unlink the destination file and proceed.
100 .RE
101
102 .sp
103 .ne 2
104 .na
105 \fB\fB-H\fR\fR
106 .ad
107 .RS 6n
108 Takes actions based on the type and contents of the file referenced by any
109 symbolic link specified as a \fIsource_file\fR operand.
110 .sp
111 If the \fIsource_file\fR operand is a symbolic link, then \fBcp\fR copies the
112 file referenced by the symbolic link for the \fIsource_file\fR operand. All
113 other symbolic links encountered during traversal of a file hierarchy are
114 preserved.
115 .RE
116
117 .sp
118 .ne 2
119 .na
120 \fB\fB-i\fR\fR
121 .ad
122 .RS 6n
123 Interactive. \fBcp\fR prompts for confirmation whenever the copy would
124 overwrite an existing \fItarget\fR. An affirmative response means that the copy
125 should proceed. Any other answer prevents \fBcp\fR from overwriting
126 \fItarget\fR.
127 .RE
128
129 .sp
130 .ne 2
131 .na
132 \fB\fB-L\fR\fR
133 .ad
134 .RS 6n
135 Takes actions based on the type and contents of the file referenced by any
136 symbolic link specified as a \fIsource_file\fR operand or any symbolic links
137 encountered during traversal of a file hierarchy.
138 .sp
139 Copies files referenced by symbolic links. Symbolic links encountered during
140 traversal of a file hierarchy are not preserved.
141 .RE
142
143 .sp
144 .ne 2
145 .na
146 \fB\fB-p\fR\fR
147 .ad
148 .RS 6n
149 Preserve. The \fBcp\fR utility duplicates not only the contents of
150 \fIsource_file\fR, but also attempts to preserve its ACL, access and
151 modification times, extended attributes, extended system attributes, file mode,
152 and owner and group ids.
153 .sp
154 If \fBcp\fR is unable to preserve the access and modification times, extended
155 attributes, or the file mode, \fBcp\fR does not consider it a failure. If
156 \fBcp\fR is unable to preserve the owner and group id, the copy does not fail,
157 but \fBcp\fR silently clears the \fBS_ISUID\fR and \fBS_ISGID\fR bits from the
158 file mode of the target. The copy fails if \fBcp\fR is unable to clear these
159 bits. If \fBcp\fR is unable to preserve the ACL or extended system attributes,
160 the copy fails. If the copy fails, then a diagnostic message is written to
161 \fBstderr\fR and (after processing any remaining operands) \fBcp\fR exits with
162 a \fBnon-zero\fR exit status.
163 .RE
164
165 .sp
166 .ne 2
167 .na
168 \fB\fB-P\fR\fR
169 .ad
170 .RS 6n
171 Takes actions on any symbolic link specified as a \fIsource_file\fR operand or
172 any symbolic link encountered during traversal of a file hierarchy.
173 .sp
174 Copies symbolic links. Symbolic links encountered during traversal of a file
175 hierarchy are preserved.
176 .RE
177
178 .sp
179 .ne 2
180 .na
181 \fB\fB-r\fR\fR
182 .ad
183 .RS 6n
184 Recursive. \fBcp\fR copies the directory and all its files, including any
185 subdirectories and their files to \fItarget\fR. Unless the \fB-H\fR, \fB-L\fR,
186 or \fB-P\fR option is specified, the \fB-L\fR option is used as the default
187 mode.
188 .RE
189
190 .sp
191 .ne 2
192 .na
193 \fB\fB-R\fR\fR
194 .ad
195 .RS 6n
196 Same as \fB-r\fR, except pipes are replicated, not read from.
197 .RE
198
199 .sp
200 .ne 2
201 .na
202 \fB\fB-@\fR\fR
203 .ad
204 .RS 6n
205 Preserves extended attributes. \fBcp\fR attempts to copy all of the source
206 file's extended attributes along with the file data to the destination file.
207 .RE
208
209 .sp
210 .ne 2
211 .na
212 \fB\fB-/\fR\fR
213 .ad
214 .RS 6n
215 Preserves extended attributes and extended system attributes. Along with the
216 file's data, the \fBcp\fR utility attempts to copy extended attributes and
217 extended system attributes from each source file, and extended system
218 attributes associated with extended attributes to the destination file. If
219 \fBcp\fR is unable to copy extended attributes or extended system attributes,
220 then a diagnostic message is written to \fBstderr\fR and (after processing any
221 remaining operands) exits with a \fBnon-zero\fR exit status.
222 .RE
223
224 .sp
225 .LP
226 Specifying more than one of the mutually-exclusive options \fB-H\fR, \fB-L\fR,
227 and \fB-P\fR is not considered an error. The last option specified determines
228 the behavior of the utility.
229 .SS "/usr/bin/cp"
230 .sp
231 .LP
232 If the \fB-p\fR option is specified with either the \fB-@\fR option or the
233 \fB-/\fR option, \fB/usr/bin/cp\fR behaves as follows
234 .RS +4
235 .TP
236 .ie t \(bu
237 .el o
238 When both \fB-p\fR and \fB-@\fR are specified in any order, the copy fails if
239 extended attributes cannot be copied.
240 .RE
241 .RS +4
242 .TP
243 .ie t \(bu
244 .el o
245 When both \fB-p\fR and \fB-/\fR are specified in any order, the copy fails if
246 extended system attributes cannot be copied.
247 .RE
248 .SS "/usr/xpg4/bin/cp"
249 .sp
250 .LP
251 If the \fB-p\fR option is specified with either the \fB-@\fR option or the
252 \fB-/\fR option, /\fBusr/xpg4/bin/cp\fR behaves as follows:
253 .RS +4
254 .TP
255 .ie t \(bu
256 .el o
257 When both \fB-p\fR and \fB-@\fR are specified, the last option specified
258 determines whether the copy fails if extended attributes cannot be preserved.
259 .RE
260 .RS +4
261 .TP
262 .ie t \(bu
263 .el o
264 When both \fB-p\fR and \fB-/\fR are specified, the last option specified
265 determines whether the copy fails if extended system attributes cannot be
266 preserved.
267 .RE
268 .SH OPERANDS
269 .sp
270 .LP
271 The following operands are supported:
272 .sp
273 .ne 2
274 .na
275 \fB\fIsource_file\fR\fR
276 .ad
277 .RS 15n
278 A pathname of a regular file to be copied.
279 .RE
280
281 .sp
282 .ne 2
283 .na
284 \fB\fIsource_dir\fR\fR
285 .ad
286 .RS 15n
287 A pathname of a directory to be copied.
288 .RE
289
290 .sp
291 .ne 2
292 .na
293 \fB\fItarget_file\fR\fR
294 .ad
295 .RS 15n
296 A pathname of an existing or non-existing file, used for the output when a
297 single file is copied.
298 .RE
299
300 .sp
301 .ne 2
302 .na
303 \fB\fItarget\fR\fR
304 .ad
305 .RS 15n
306 A pathname of a directory to contain the copied files.
307 .RE
308
309 .SH USAGE
310 .sp
311 .LP
312 See \fBlargefile\fR(5) for the description of the behavior of \fBcp\fR when
313 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
314 .SH EXAMPLES
315 .LP
316 \fBExample 1 \fRCopying a File
317 .sp
318 .LP
319 The following example copies a file:
320
321 .sp
322 .in +2
323 .nf
324 example% cp goodies goodies.old
325
326 example% ls goodies*
327 goodies goodies.old
328 .fi
329 .in -2
330 .sp
331
332 .LP
333 \fBExample 2 \fRCopying a List of Files
334 .sp
335 .LP
336 The following example copies a list of files to a destination directory:
337
338 .sp
339 .in +2
340 .nf
341 example% cp ~/src/* /tmp
342 .fi
343 .in -2
344 .sp
345
346 .LP
347 \fBExample 3 \fRCopying a Directory
348 .sp
349 .LP
350 The following example copies a directory, first to a new, and then to an
351 existing destination directory
352
353 .sp
354 .in +2
355 .nf
356 example% ls ~/bkup
357 /usr/example/fred/bkup not found
358
359 example% cp \fB-r\fR ~/src ~/bkup
360
361 example% ls \fB-R\fR ~/bkup
362 x.c y.c z.sh
363
364 example% cp \fB-r\fR ~/src ~/bkup
365
366 example% ls \fB-R\fR ~/bkup
367 src x.c y.c z.sh
368 src:
369 x.c y.c z.s
370 .fi
371 .in -2
372 .sp
373
374 .LP
375 \fBExample 4 \fRCopying Extended File System Attributes
376 .sp
377 .LP
378 The following example copies extended file system attributes:
379
380 .sp
381 .in +2
382 .nf
383 $ ls -/ c file1
384 -rw-r--r-- 1 foo staff 0 Oct 29 20:04 file1
385 {AH-----m--}
386
387 $ cp -/ file1 file2
388 $ ls -/c file2
389 -rw-r--r-- 1 foo staff 0 Oct 29 20:17 file2
390 {AH-----m--}
391 .fi
392 .in -2
393 .sp
394
395 .LP
396 \fBExample 5 \fRFailing to Copy Extended System Attributes
397 .sp
398 .LP
399 The following example fails to copy extended system attributes:
400
401 .sp
402 .in +2
403 .nf
404 $ ls -/c file1
405 -rw-r--r-- 1 foo staff 0 Oct 29 20:04 file1
406 {AH-----m--}
407
408 $ cp -/ file1 /tmp
409 cp: Failed to copy extended system attributes from file1 to /tmp/file1
410
411
412 $ ls -/c /tmp/file1
413 -rw-r--r-- 1 foo staff 0 Oct 29 20:09 /tmp/file1
414 {}
415 .fi
416 .in -2
417 .sp
418
419 .SH ENVIRONMENT VARIABLES
420 .sp
421 .LP
422 See \fBenviron\fR(5) for descriptions of the following environment variables
423 that affect the execution of \fBcp\fR: \fBLANG\fR, \fBLC_ALL\fR,
424 \fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
425 .sp
426 .LP
427 Affirmative responses are processed using the extended regular expression
428 defined for the \fByesexpr\fR keyword in the \fBLC_MESSAGES\fR category of the
429 user's locale. The locale specified in the \fBLC_COLLATE\fR category defines
430 the behavior of ranges, equivalence classes, and multi-character collating
431 elements used in the expression defined for \fByesexpr\fR. The locale specified
432 in \fBLC_CTYPE\fR determines the locale for interpretation of sequences of
433 bytes of text data a characters, the behavior of character classes used in the
434 expression defined for the \fByesexpr\fR. See \fBlocale\fR(5).
435 .SH EXIT STATUS
436 .sp
437 .LP
438 The following exit values are returned:
439 .sp
440 .ne 2
441 .na
442 \fB\fB0\fR\fR
443 .ad
444 .RS 6n
445 All files were copied successfully.
446 .RE
447
448 .sp
449 .ne 2
450 .na
451 \fB\fB>0\fR\fR
452 .ad
453 .RS 6n
454 An error occurred.
455 .RE
456
457 .SH ATTRIBUTES
458 .sp
459 .LP
460 See \fBattributes\fR(5) for descriptions of the following attributes:
461 .SS "/usr/bin/cp"
462 .sp
463
464 .sp
465 .TS
466 box;
467 c | c
468 l | l .
469 ATTRIBUTE TYPE ATTRIBUTE VALUE
470 _
471 CSI Enabled
472 _
473 Interface Stability Committed
474 .TE
475
476 .SS "/usr/xpg4/bin/cp"
477 .sp
478
479 .sp
480 .TS
481 box;
482 c | c
483 l | l .
484 ATTRIBUTE TYPE ATTRIBUTE VALUE
485 _
486 CSI Enabled
487 _
488 Interface Stability Committed
489 .TE
490
491 .SH SEE ALSO
492 .sp
493 .LP
494 \fBchmod\fR(1), \fBchown\fR(1), \fBsetfacl\fR(1), \fButime\fR(2),
495 \fBfgetattr\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBfsattr\fR(5),
496 \fBlargefile\fR(5), \fBlocale\fR(5), \fBstandards\fR(5)
497 .SH NOTES
498 .sp
499 .LP
500 The permission modes of the source file are preserved in the copy.
501 .sp
502 .LP
503 A \fB--\fR permits the user to mark the end of any command line options
504 explicitly, thus allowing \fBcp\fR to recognize filename arguments that begin
505 with a \fB-\fR.