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"
19 \fB/usr/bin/cp\fR [\fB-afip@/\fR] \fIsource_file\fR \fItarget_file\fR
24 \fB/usr/bin/cp\fR [\fB-afip@/\fR] \fIsource_file\fR... \fItarget\fR
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
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
39 \fB/usr/xpg4/bin/cp\fR [\fB-afip@/\fR] \fIsource_file\fR \fItarget_file\fR
44 \fB/usr/xpg4/bin/cp\fR [\fB-afip@/\fR] \fIsource_file\fR... \fItarget\fR
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
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
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.
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
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.
91 The following options are supported for both \fB/usr/bin/cp\fR and
92 \fB/usr/xpg4/bin/cp\fR:
99 Archive mode. Same as -RpP.
108 Unlink. If a file descriptor for a destination file cannot be obtained, this
109 option attempts to unlink the destination file and proceed.
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.
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
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
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.
149 Copies files referenced by symbolic links. Symbolic links encountered during
150 traversal of a file hierarchy are not preserved.
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.
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.
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.
184 Copies symbolic links. Symbolic links encountered during traversal of a file
185 hierarchy are preserved.
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
206 Same as \fB-r\fR, except pipes are replicated, not read from.
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.
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.
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.
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
248 When both \fB-p\fR and \fB-@\fR are specified in any order, the copy fails if
249 extended attributes cannot be copied.
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.
258 .SS "/usr/xpg4/bin/cp"
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:
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.
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
281 The following operands are supported:
285 \fB\fIsource_file\fR\fR
288 A pathname of a regular file to be copied.
294 \fB\fIsource_dir\fR\fR
297 A pathname of a directory to be copied.
303 \fB\fItarget_file\fR\fR
306 A pathname of an existing or non-existing file, used for the output when a
307 single file is copied.
316 A pathname of a directory to contain the copied files.
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).
326 \fBExample 1 \fRCopying a File
329 The following example copies a file:
334 example% cp goodies goodies.old
343 \fBExample 2 \fRCopying a List of Files
346 The following example copies a list of files to a destination directory:
351 example% cp ~/src/* /tmp
357 \fBExample 3 \fRCopying a Directory
360 The following example copies a directory, first to a new, and then to an
361 existing destination directory
367 /usr/example/fred/bkup not found
369 example% cp \fB-r\fR ~/src ~/bkup
371 example% ls \fB-R\fR ~/bkup
374 example% cp \fB-r\fR ~/src ~/bkup
376 example% ls \fB-R\fR ~/bkup
385 \fBExample 4 \fRCopying Extended File System Attributes
388 The following example copies extended file system attributes:
394 -rw-r--r-- 1 foo staff 0 Oct 29 20:04 file1
399 -rw-r--r-- 1 foo staff 0 Oct 29 20:17 file2
406 \fBExample 5 \fRFailing to Copy Extended System Attributes
409 The following example fails to copy extended system attributes:
415 -rw-r--r-- 1 foo staff 0 Oct 29 20:04 file1
419 cp: Failed to copy extended system attributes from file1 to /tmp/file1
423 -rw-r--r-- 1 foo staff 0 Oct 29 20:09 /tmp/file1
429 .SH ENVIRONMENT VARIABLES
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.
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).
448 The following exit values are returned:
455 All files were copied successfully.
470 See \fBattributes\fR(5) for descriptions of the following attributes:
479 ATTRIBUTE TYPE ATTRIBUTE VALUE
483 Interface Stability Committed
486 .SS "/usr/xpg4/bin/cp"
494 ATTRIBUTE TYPE ATTRIBUTE VALUE
498 Interface Stability Committed
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)
510 The permission modes of the source file are preserved in the copy.
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