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