| blob | a27ef5183729e3b99cf4664988cba41bda9ae6df |
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 "Oct 25, 2017"
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
57 .LP
58 .nf
59 \fB/usr/bin/cp\fR [\fB-afip@/\fR] \fIsource_file\fR... \fItarget\fR
60 .fi
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
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
72 .SH DESCRIPTION
73 .sp
74 .LP
75 In the first synopsis form, neither \fIsource_file\fR nor \fItarget_file\fR are
76 directory files, nor can they have the same name. The \fBcp\fR utility copies
77 the contents of \fIsource_file\fR to the destination path named by
78 \fItarget_file\fR. If \fItarget_file\fR exists, \fBcp\fR overwrites its
79 contents, but the mode (and \fBACL\fR if applicable), owner, and group
80 associated with it are not changed. The last modification time of
81 \fItarget_file\fR and the last access time of \fIsource_file\fR are set to the
82 time the copy was made. If \fItarget_file\fR does not exist, \fBcp\fR creates a
83 new file named \fItarget_file\fR that has the same mode as \fIsource_file\fR
84 except that the sticky bit is not set unless the user is super-user. In this
85 case, the owner and group of \fItarget_file\fR are those of the user, unless
86 the setgid bit is set on the directory containing the newly created file. If
87 the directory's setgid bit is set, the newly created file has the group of the
88 containing directory rather than of the creating user. If \fItarget_file\fR is
89 a link to another file, \fBcp\fR overwrites the link destination with the
90 contents of \fIsource_file\fR; the link(s) from \fItarget_file\fR remains.
91 .sp
92 .LP
93 In the second synopsis form, one or more \fIsource_file\fRs are copied to the
94 directory specified by \fItarget\fR. It is an error if any \fIsource_file\fR is
95 a file of type directory, if \fItarget\fR either does not exist or is not a
96 directory.
97 .sp
98 .LP
99 In the third or fourth synopsis forms, one or more directories specified by
100 \fIsource_dir\fR are copied to the directory specified by \fItarget\fR. Either
101 the \fB-r\fR or \fB-R\fR must be specified. For each \fIsource_dir\fR, \fBcp\fR
102 copies all files and subdirectories.
103 .SH OPTIONS
104 .sp
105 .LP
106 The following options are supported:
107 .sp
108 .ne 2
109 .na
110 \fB\fB-a\fR\fR
111 .ad
112 .RS 6n
113 Archive mode. Same as -RpP.
114 .RE
116 .sp
117 .ne 2
118 .na
119 \fB\fB-f\fR\fR
120 .ad
121 .RS 6n
122 Unlink. If a file descriptor for a destination file cannot be obtained, this
123 option attempts to unlink the destination file and proceed.
124 .RE
126 .sp
127 .ne 2
128 .na
129 \fB\fB-H\fR\fR
130 .ad
131 .RS 6n
132 Takes actions based on the type and contents of the file referenced by any
133 symbolic link specified as a \fIsource_file\fR operand.
134 .sp
135 If the \fIsource_file\fR operand is a symbolic link, then \fBcp\fR copies the
136 file referenced by the symbolic link for the \fIsource_file\fR operand. All
137 other symbolic links encountered during traversal of a file hierarchy are
138 preserved.
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fB\fB-i\fR\fR
145 .ad
146 .RS 6n
147 Interactive. \fBcp\fR prompts for confirmation whenever the copy would
148 overwrite an existing \fItarget\fR. An affirmative response means that the copy
149 should proceed. Any other answer prevents \fBcp\fR from overwriting
150 \fItarget\fR.
151 .RE
153 .sp
154 .ne 2
155 .na
156 \fB\fB-L\fR\fR
157 .ad
158 .RS 6n
159 Takes actions based on the type and contents of the file referenced by any
160 symbolic link specified as a \fIsource_file\fR operand or any symbolic links
161 encountered during traversal of a file hierarchy.
162 .sp
163 Copies files referenced by symbolic links. Symbolic links encountered during
164 traversal of a file hierarchy are not preserved.
165 .RE
167 .sp
168 .ne 2
169 .na
170 \fB\fB-p\fR\fR
171 .ad
172 .RS 6n
173 Preserve. The \fBcp\fR utility duplicates not only the contents of
174 \fIsource_file\fR, but also attempts to preserve its ACL, access and
175 modification times, extended attributes, extended system attributes, file mode,
176 and owner and group ids.
177 .sp
178 If \fBcp\fR is unable to preserve the access and modification times, extended
179 attributes, or the file mode, \fBcp\fR does not consider it a failure. If
180 \fBcp\fR is unable to preserve the owner and group id, the copy does not fail,
181 but \fBcp\fR silently clears the \fBS_ISUID\fR and \fBS_ISGID\fR bits from the
182 file mode of the target. The copy fails if \fBcp\fR is unable to clear these
183 bits. If \fBcp\fR is unable to preserve the ACL or extended system attributes,
184 the copy fails. If the copy fails, then a diagnostic message is written to
185 \fBstderr\fR and (after processing any remaining operands) \fBcp\fR exits with
186 a \fBnon-zero\fR exit status.
187 .RE
189 .sp
190 .ne 2
191 .na
192 \fB\fB-P\fR\fR
193 .ad
194 .RS 6n
195 Takes actions on any symbolic link specified as a \fIsource_file\fR operand or
196 any symbolic link encountered during traversal of a file hierarchy.
197 .sp
198 Copies symbolic links. Symbolic links encountered during traversal of a file
199 hierarchy are preserved.
200 .RE
202 .sp
203 .ne 2
204 .na
205 \fB\fB-r\fR\fR
206 .ad
207 .RS 6n
208 Recursive. \fBcp\fR copies the directory and all its files, including any
209 subdirectories and their files to \fItarget\fR. Unless the \fB-H\fR, \fB-L\fR,
210 or \fB-P\fR option is specified, the \fB-L\fR option is used as the default
211 mode.
212 .RE
214 .sp
215 .ne 2
216 .na
217 \fB\fB-R\fR\fR
218 .ad
219 .RS 6n
220 Same as \fB-r\fR, except pipes are replicated, not read from.
221 .RE
223 .sp
224 .ne 2
225 .na
226 \fB\fB-@\fR\fR
227 .ad
228 .RS 6n
229 Preserves extended attributes. \fBcp\fR attempts to copy all of the source
230 file's extended attributes along with the file data to the destination file.
231 .RE
233 .sp
234 .ne 2
235 .na
236 \fB\fB-/\fR\fR
237 .ad
238 .RS 6n
239 Preserves extended attributes and extended system attributes. Along with the
240 file's data, the \fBcp\fR utility attempts to copy extended attributes and
241 extended system attributes from each source file, and extended system
242 attributes associated with extended attributes to the destination file. If
243 \fBcp\fR is unable to copy extended attributes or extended system attributes,
244 then a diagnostic message is written to \fBstderr\fR and (after processing any
245 remaining operands) exits with a \fBnon-zero\fR exit status.
246 .RE
248 .sp
249 .LP
250 Specifying more than one of the mutually-exclusive options \fB-H\fR, \fB-L\fR,
251 and \fB-P\fR is not considered an error. The last option specified determines
252 the behavior of the utility.
253 .sp
254 .LP
255 If the \fB-p\fR option is specified with either the \fB-@\fR option or the
256 \fB-/\fR option, /\fBusr/bin/cp\fR behaves as follows:
257 .RS +4
258 .TP
259 .ie t \(bu
260 .el o
261 When both \fB-p\fR and \fB-@\fR are specified, the last option specified
262 determines whether the copy fails if extended attributes cannot be preserved.
263 .RE
264 .RS +4
265 .TP
266 .ie t \(bu
267 .el o
268 When both \fB-p\fR and \fB-/\fR are specified, the last option specified
269 determines whether the copy fails if extended system attributes cannot be
270 preserved.
271 .RE
272 .SH OPERANDS
273 .sp
274 .LP
275 The following operands are supported:
276 .sp
277 .ne 2
278 .na
279 \fB\fIsource_file\fR\fR
280 .ad
281 .RS 15n
282 A pathname of a regular file to be copied.
283 .RE
285 .sp
286 .ne 2
287 .na
288 \fB\fIsource_dir\fR\fR
289 .ad
290 .RS 15n
291 A pathname of a directory to be copied.
292 .RE
294 .sp
295 .ne 2
296 .na
297 \fB\fItarget_file\fR\fR
298 .ad
299 .RS 15n
300 A pathname of an existing or non-existing file, used for the output when a
301 single file is copied.
302 .RE
304 .sp
305 .ne 2
306 .na
307 \fB\fItarget\fR\fR
308 .ad
309 .RS 15n
310 A pathname of a directory to contain the copied files.
311 .RE
313 .SH USAGE
314 .sp
315 .LP
316 See \fBlargefile\fR(5) for the description of the behavior of \fBcp\fR when
317 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
318 .SH EXAMPLES
319 .LP
320 \fBExample 1 \fRCopying a File
321 .sp
322 .LP
323 The following example copies a file:
325 .sp
326 .in +2
327 .nf
328 example% cp goodies goodies.old
330 example% ls goodies*
331 goodies goodies.old
332 .fi
333 .in -2
334 .sp
336 .LP
337 \fBExample 2 \fRCopying a List of Files
338 .sp
339 .LP
340 The following example copies a list of files to a destination directory:
342 .sp
343 .in +2
344 .nf
345 example% cp ~/src/* /tmp
346 .fi
347 .in -2
348 .sp
350 .LP
351 \fBExample 3 \fRCopying a Directory
352 .sp
353 .LP
354 The following example copies a directory, first to a new, and then to an
355 existing destination directory
357 .sp
358 .in +2
359 .nf
360 example% ls ~/bkup
361 /usr/example/fred/bkup not found
363 example% cp \fB-r\fR ~/src ~/bkup
365 example% ls \fB-R\fR ~/bkup
366 x.c y.c z.sh
368 example% cp \fB-r\fR ~/src ~/bkup
370 example% ls \fB-R\fR ~/bkup
371 src x.c y.c z.sh
372 src:
373 x.c y.c z.s
374 .fi
375 .in -2
376 .sp
378 .LP
379 \fBExample 4 \fRCopying Extended File System Attributes
380 .sp
381 .LP
382 The following example copies extended file system attributes:
384 .sp
385 .in +2
386 .nf
387 $ ls -/ c file1
388 -rw-r--r-- 1 foo staff 0 Oct 29 20:04 file1
389 {AH-----m--}
391 $ cp -/ file1 file2
392 $ ls -/c file2
393 -rw-r--r-- 1 foo staff 0 Oct 29 20:17 file2
394 {AH-----m--}
395 .fi
396 .in -2
397 .sp
399 .LP
400 \fBExample 5 \fRFailing to Copy Extended System Attributes
401 .sp
402 .LP
403 The following example fails to copy extended system attributes:
405 .sp
406 .in +2
407 .nf
408 $ ls -/c file1
409 -rw-r--r-- 1 foo staff 0 Oct 29 20:04 file1
410 {AH-----m--}
412 $ cp -/ file1 /tmp
413 cp: Failed to copy extended system attributes from file1 to /tmp/file1
416 $ ls -/c /tmp/file1
417 -rw-r--r-- 1 foo staff 0 Oct 29 20:09 /tmp/file1
418 {}
419 .fi
420 .in -2
421 .sp
423 .SH ENVIRONMENT VARIABLES
424 .sp
425 .LP
426 See \fBenviron\fR(5) for descriptions of the following environment variables
427 that affect the execution of \fBcp\fR: \fBLANG\fR, \fBLC_ALL\fR,
428 \fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
429 .sp
430 .LP
431 Affirmative responses are processed using the extended regular expression
432 defined for the \fByesexpr\fR keyword in the \fBLC_MESSAGES\fR category of the
433 user's locale. The locale specified in the \fBLC_COLLATE\fR category defines
434 the behavior of ranges, equivalence classes, and multi-character collating
435 elements used in the expression defined for \fByesexpr\fR. The locale specified
436 in \fBLC_CTYPE\fR determines the locale for interpretation of sequences of
437 bytes of text data a characters, the behavior of character classes used in the
438 expression defined for the \fByesexpr\fR. See \fBlocale\fR(5).
439 .SH EXIT STATUS
440 .sp
441 .LP
442 The following exit values are returned:
443 .sp
444 .ne 2
445 .na
446 \fB\fB0\fR\fR
447 .ad
448 .RS 6n
449 All files were copied successfully.
450 .RE
452 .sp
453 .ne 2
454 .na
455 \fB\fB>0\fR\fR
456 .ad
457 .RS 6n
458 An error occurred.
459 .RE
461 .SH ATTRIBUTES
462 .sp
463 .LP
464 See \fBattributes\fR(5) for descriptions of the following attributes:
465 .SS "/usr/bin/cp"
466 .sp
468 .sp
469 .TS
470 box;
471 c | c
472 l | l .
473 ATTRIBUTE TYPE ATTRIBUTE VALUE
474 _
475 CSI Enabled
476 _
477 Interface Stability Committed
478 .TE
480 .SH SEE ALSO
481 .sp
482 .LP
483 \fBchmod\fR(1), \fBchown\fR(1), \fBsetfacl\fR(1), \fButime\fR(2),
484 \fBfgetattr\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBfsattr\fR(5),
485 \fBlargefile\fR(5), \fBlocale\fR(5), \fBstandards\fR(5)
486 .SH NOTES
487 .sp
488 .LP
489 The permission modes of the source file are preserved in the copy.
490 .sp
491 .LP
492 A \fB--\fR permits the user to mark the end of any command line options
493 explicitly, thus allowing \fBcp\fR to recognize filename arguments that begin
494 with a \fB-\fR.