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