CP(1) User Commands CP(1)
cp - copy files
/usr/bin/cp [-afinp@/] source_file target_file
/usr/bin/cp [-afinp@/] source_file... target
/usr/bin/cp [-afinp@/] -T source_file 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 [-afinp@/] -T source_file target
/usr/xpg4/bin/cp [-r | -R [-H | -L | -P]] [-afinp@/] source_dir...
target
In the first synopsis form, neither source_file nor target_file are
directory files, nor can they have the same name. The cp utility
copies the contents of source_file to the destination path named by
target_file. If target_file exists, cp overwrites its contents, but
the mode (and ACL if applicable), owner, and group associated with it
are not changed. The last modification time of target_file and the
last access time of source_file are set to the time the copy was made.
If target_file does not exist, cp creates a new file named target_file
that has the same mode as source_file except that the sticky bit is not
set unless the user is super-user. In this case, the owner and group
of target_file are those of the user, unless the setgid bit is set on
the directory containing the newly created file. If the directory's
setgid bit is set, the newly created file has the group of the
containing directory rather than of the creating user. If target_file
is a link to another file, cp overwrites the link destination with the
contents of source_file; the link(s) from target_file remains.
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 synopsis form, target is always treated logically as a
file regardless if it is one or not. Unlike the second synopsis form
which creates source_file inside of the directory target, the path of
target itself would be used.
In the fourth synopsis form, 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.
The following options are supported for both /usr/bin/cp and
/usr/xpg4/bin/cp:
-a Archive mode. Same as -RpP.
-f 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.
-H 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.
-i 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.
-L 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.
-n 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.
-p 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.
-P 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.
-r 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.
-R Same as -r, except pipes are replicated, not read from.
-T Treat target as a file and do not attempt to place source_file
inside of target if it is a directory. This is only usable
with exactly one source_file and target.
-@ 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.
/usr/bin/cp
If the -p option is specified with either the -@ option or the -/
option, /usr/bin/cp behaves as follows:
+o When both -p and -@ are specified in any order, the copy
fails if extended attributes cannot be copied.
+o When both -p and -/ are specified in any order, the copy
fails if extended system attributes cannot be copied.
/usr/xpg4/bin/cp
If the -p option is specified with either the -@ option or the -/
option, /usr/xpg4/bin/cp behaves as follows:
+o When both -p and -@ are specified, the last option specified
determines whether the copy fails if extended attributes
cannot be preserved.
+o When both -p and -/ are specified, the last option specified
determines whether the copy fails if extended system
attributes cannot be preserved.
The following operands are supported:
source_file A pathname of a regular file to be copied.
source_dir A pathname of a directory to be copied.
target_file A pathname of an existing or non-existing file, used for
the output when a single file is copied.
target A pathname of a directory to contain the copied files.
See largefile(7) for the description of the behavior of cp when
encountering files greater than or equal to 2 Gbyte (2^31 bytes).
See environ(7) for descriptions of the following environment variables
that affect the execution of cp: LANG, LC_ALL, LC_COLLATE, LC_CTYPE,
LC_MESSAGES, and NLSPATH.
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).
The following exit values are returned:
0 All files were copied successfully.
> 0 An error occurred.
Example 1 Copying a File
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
{}
Committed
Enabled
chmod(1), chown(1), setfacl(1), utime(2), fgetattr(3C), attributes(7),
environ(7), fsattr(7), largefile(7), locale(7), standards(7)
The permission modes of the source file are preserved in the copy.
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 -.
illumos March 22, 2026 illumos
NAME
cp - copy files
SYNOPSIS
/usr/bin/cp [-afinp@/] source_file target_file
/usr/bin/cp [-afinp@/] source_file... target
/usr/bin/cp [-afinp@/] -T source_file 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 [-afinp@/] -T source_file target
/usr/xpg4/bin/cp [-r | -R [-H | -L | -P]] [-afinp@/] source_dir...
target
DESCRIPTION
In the first synopsis form, neither source_file nor target_file are
directory files, nor can they have the same name. The cp utility
copies the contents of source_file to the destination path named by
target_file. If target_file exists, cp overwrites its contents, but
the mode (and ACL if applicable), owner, and group associated with it
are not changed. The last modification time of target_file and the
last access time of source_file are set to the time the copy was made.
If target_file does not exist, cp creates a new file named target_file
that has the same mode as source_file except that the sticky bit is not
set unless the user is super-user. In this case, the owner and group
of target_file are those of the user, unless the setgid bit is set on
the directory containing the newly created file. If the directory's
setgid bit is set, the newly created file has the group of the
containing directory rather than of the creating user. If target_file
is a link to another file, cp overwrites the link destination with the
contents of source_file; the link(s) from target_file remains.
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 synopsis form, target is always treated logically as a
file regardless if it is one or not. Unlike the second synopsis form
which creates source_file inside of the directory target, the path of
target itself would be used.
In the fourth synopsis form, 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.
OPTIONS
The following options are supported for both /usr/bin/cp and
/usr/xpg4/bin/cp:
-a Archive mode. Same as -RpP.
-f 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.
-H 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.
-i 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.
-L 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.
-n 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.
-p 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.
-P 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.
-r 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.
-R Same as -r, except pipes are replicated, not read from.
-T Treat target as a file and do not attempt to place source_file
inside of target if it is a directory. This is only usable
with exactly one source_file and target.
-@ 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.
/usr/bin/cp
If the -p option is specified with either the -@ option or the -/
option, /usr/bin/cp behaves as follows:
+o When both -p and -@ are specified in any order, the copy
fails if extended attributes cannot be copied.
+o When both -p and -/ are specified in any order, the copy
fails if extended system attributes cannot be copied.
/usr/xpg4/bin/cp
If the -p option is specified with either the -@ option or the -/
option, /usr/xpg4/bin/cp behaves as follows:
+o When both -p and -@ are specified, the last option specified
determines whether the copy fails if extended attributes
cannot be preserved.
+o When both -p and -/ are specified, the last option specified
determines whether the copy fails if extended system
attributes cannot be preserved.
OPERANDS
The following operands are supported:
source_file A pathname of a regular file to be copied.
source_dir A pathname of a directory to be copied.
target_file A pathname of an existing or non-existing file, used for
the output when a single file is copied.
target A pathname of a directory to contain the copied files.
USAGE
See largefile(7) for the description of the behavior of cp when
encountering files greater than or equal to 2 Gbyte (2^31 bytes).
ENVIRONMENT VARIABLES
See environ(7) for descriptions of the following environment variables
that affect the execution of cp: LANG, LC_ALL, LC_COLLATE, LC_CTYPE,
LC_MESSAGES, and NLSPATH.
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).
EXIT STATUS
The following exit values are returned:
0 All files were copied successfully.
> 0 An error occurred.
EXAMPLES
Example 1 Copying a File
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
{}
INTERFACE STABILITY
Committed
CODE SET INDEPENDENCE
Enabled
SEE ALSO
chmod(1), chown(1), setfacl(1), utime(2), fgetattr(3C), attributes(7),
environ(7), fsattr(7), largefile(7), locale(7), standards(7)
NOTES
The permission modes of the source file are preserved in the copy.
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 -.
illumos March 22, 2026 illumos