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
http://www.opengroup.org/bookstore/.
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 SunOS 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.
This notice shall appear on any product containing this material.
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.
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.
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]
Copyright 1989 AT&T
Copyright (c) 1992, X/Open Company Limited All Rights Reserved
Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
Copyright 2013 Nexenta Systems, Inc. All rights reserved.
Copyright 2024 Oxide Computer Company
/usr/bin/cp [-afinp@/] source_file target_file
/usr/bin/cp [-afinp@/] source_file... target
/usr/bin/cp [-r | -R [-H | -L | -P]] [-afinp@/] source_dir... target
/usr/bin/cp [-R | -R [-H | -L | -P]] [-afinp@/] source_dir... target
/usr/xpg4/bin/cp [-afinp@/] source_file target_file
/usr/xpg4/bin/cp [-afinp@/] source_file... target
/usr/xpg4/bin/cp [-r | -R [-H | -L | -P]] [-afinp@/] source_dir... target
/usr/xpg4/bin/cp [-R | -R [-H | -L | -P]] [-afinp@/] source_dir... target
In the second synopsis form, one or more source_files are copied to the directory specified by target. It is an error if any source_file is a file of type directory, if target either does not exist or is not a directory.
In the third or fourth synopsis forms, one or more directories specified by source_dir are copied to the directory specified by target. Either the -r or -R must be specified. For each source_dir, cp copies all files and subdirectories.
Archive mode. Same as -RpP.
Unlink. If a file descriptor for a destination file cannot be obtained, this option attempts to unlink the destination file and proceed. If the -n option is specified then this option is ignored.
Takes actions based on the type and contents of the file referenced by any symbolic link specified as a source_file operand. If the source_file operand is a symbolic link, then cp copies the file referenced by the symbolic link for the source_file operand. All other symbolic links encountered during traversal of a file hierarchy are preserved.
Interactive. cp prompts for confirmation whenever the copy would overwrite an existing target. An affirmative response means that the copy should proceed. Any other answer prevents cp from overwriting target. If both the -i and -n options are specified, only the last one on the command line is honored.
Takes actions based on the type and contents of the file referenced by any symbolic link specified as a source_file operand or any symbolic links encountered during traversal of a file hierarchy. Copies files referenced by symbolic links. Symbolic links encountered during traversal of a file hierarchy are not preserved.
No clobber. When cp encounters a target file that already exists, whether specified explicitly, the file is found in a directory, or as part of a recursive copy, do not overwrite the file. Files skipped this way are not considered errors. If both the -i and -n options are specified, only the last one on the command line is honored.
Preserve. The cp utility duplicates not only the contents of source_file, but also attempts to preserve its ACL, access and modification times, extended attributes, extended system attributes, file mode, and owner and group ids. If cp is unable to preserve the access and modification times, extended attributes, or the file mode, cp does not consider it a failure. If cp is unable to preserve the owner and group id, the copy does not fail, but cp silently clears the S_ISUID and S_ISGID bits from the file mode of the target. The copy fails if cp is unable to clear these bits. If cp is unable to preserve the ACL or extended system attributes, the copy fails. If the copy fails, then a diagnostic message is written to stderr and (after processing any remaining operands) cp exits with a non-zero exit status.
Takes actions on any symbolic link specified as a source_file operand or any symbolic link encountered during traversal of a file hierarchy. Copies symbolic links. Symbolic links encountered during traversal of a file hierarchy are preserved.
Recursive. cp copies the directory and all its files, including any subdirectories and their files to target. Unless the -H, -L, or -P option is specified, the -L option is used as the default mode.
Same as -r, except pipes are replicated, not read from.
Preserves extended attributes. cp attempts to copy all of the source file's extended attributes along with the file data to the destination file.
Preserves extended attributes and extended system attributes. Along with the file's data, the cp utility attempts to copy extended attributes and extended system attributes from each source file, and extended system attributes associated with extended attributes to the destination file. If cp is unable to copy extended attributes or extended system attributes, then a diagnostic message is written to stderr and (after processing any remaining operands) exits with a non-zero exit status.
Specifying more than one of the mutually-exclusive options -H, -L, and -P is not considered an error. The last option specified determines the behavior of the utility.
If the -p option is specified with either the -@ option or the -/ option, /usr/bin/cp behaves as follows
When both -p and -@ are specified in any order, the copy fails if extended attributes cannot be copied.
When both -p and -/ are specified in any order, the copy fails if extended system attributes cannot be copied.
When both -p and -@ are specified, the last option specified determines whether the copy fails if extended attributes cannot be preserved.
When both -p and -/ are specified, the last option specified determines whether the copy fails if extended system attributes cannot be preserved.
A pathname of a regular file to be copied.
A pathname of a directory to be copied.
A pathname of an existing or non-existing file, used for the output when a single file is copied.
A pathname of a directory to contain the copied files.
The following example copies a file:
example% cp goodies goodies.old example% ls goodies* goodies goodies.old
Example 2 Copying a List of Files
The following example copies a list of files to a destination directory:
example% cp ~/src/* /tmp
Example 3 Copying a Directory
The following example copies a directory, first to a new, and then to an existing destination directory
example% ls ~/bkup /usr/example/fred/bkup not found example% cp -r ~/src ~/bkup example% ls -R ~/bkup x.c y.c z.sh example% cp -r ~/src ~/bkup example% ls -R ~/bkup src x.c y.c z.sh src: x.c y.c z.s
Example 4 Copying Extended File System Attributes
The following example copies extended file system attributes:
$ ls -/ c file1
-rw-r--r-- 1 foo staff 0 Oct 29 20:04 file1
{AH-----m--}
$ cp -/ file1 file2
$ ls -/c file2
-rw-r--r-- 1 foo staff 0 Oct 29 20:17 file2
{AH-----m--}
Example 5 Failing to Copy Extended System Attributes
The following example fails to copy extended system attributes:
$ ls -/c file1
-rw-r--r-- 1 foo staff 0 Oct 29 20:04 file1
{AH-----m--}
$ cp -/ file1 /tmp
cp: Failed to copy extended system attributes from file1 to /tmp/file1
$ ls -/c /tmp/file1
-rw-r--r-- 1 foo staff 0 Oct 29 20:09 /tmp/file1
{}
Affirmative responses are processed using the extended regular expression defined for the yesexpr keyword in the LC_MESSAGES category of the user's locale. The locale specified in the LC_COLLATE category defines the behavior of ranges, equivalence classes, and multi-character collating elements used in the expression defined for yesexpr. The locale specified in LC_CTYPE determines the locale for interpretation of sequences of bytes of text data a characters, the behavior of character classes used in the expression defined for the yesexpr. See locale(7).
All files were copied successfully.
An error occurred.
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| CSI Enabled |
| Interface Stability Committed |
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| CSI Enabled |
| Interface Stability Committed |
A -- permits the user to mark the end of any command line options explicitly, thus allowing cp to recognize filename arguments that begin with a -.