|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
|
|
|
CP(1P) POSIX Programmer's Manual CP(1P)
This manual page is part of the POSIX Programmer's Manual. The
Linux implementation of this interface may differ (consult the
corresponding Linux manual page for details of Linux behavior), or
the interface may not be implemented on Linux.
cp — copy files
cp [-Pfip] source_file target_file
cp [-Pfip] source_file... target
cp -R [-H|-L|-P] [-fip] source_file... target
The first synopsis form is denoted by two operands, neither of
which are existing files of type directory. The cp utility shall
copy the contents of source_file (or, if source_file is a file of
type symbolic link, the contents of the file referenced by
source_file) to the destination path named by target_file.
The second synopsis form is denoted by two or more operands where
the -R option is not specified and the first synopsis form is not
applicable. It shall be an error if any source_file is a file of
type directory, if target does not exist, or if target does not
name a directory. The cp utility shall copy the contents of each
source_file (or, if source_file is a file of type symbolic link,
the contents of the file referenced by source_file) to the
destination path named by the concatenation of target, a single
<slash> character if target did not end in a <slash>, and the last
component of source_file.
The third synopsis form is denoted by two or more operands where
the -R option is specified. The cp utility shall copy each file in
the file hierarchy rooted in each source_file to a destination
path named as follows:
* If target exists and names an existing directory, the name of
the corresponding destination path for each file in the file
hierarchy shall be the concatenation of target, a single
<slash> character if target did not end in a <slash>, and the
pathname of the file relative to the directory containing
source_file.
* If target does not exist and two operands are specified, the
name of the corresponding destination path for source_file
shall be target; the name of the corresponding destination
path for all other files in the file hierarchy shall be the
concatenation of target, a <slash> character, and the pathname
of the file relative to source_file.
It shall be an error if target does not exist and more than two
operands are specified, or if target exists and does not name a
directory.
In the following description, the term dest_file refers to the
file named by the destination path. The term source_file refers to
the file that is being copied, whether specified as an operand or
a file in a file hierarchy rooted in a source_file operand. If
source_file is a file of type symbolic link:
* If the -R option was not specified, cp shall take actions
based on the type and contents of the file referenced by the
symbolic link, and not by the symbolic link itself, unless the
-P option was specified.
* If the -R option was specified:
-- If none of the options -H, -L, nor -P were specified, it
is unspecified which of -H, -L, or -P will be used as a
default.
-- If the -H option was specified, cp shall take actions
based on the type and contents of the file referenced by
any symbolic link specified as a source_file operand.
-- If the -L option was specified, cp shall take 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.
-- If the -P option was specified, cp shall copy any symbolic
link specified as a source_file operand and any symbolic
links encountered during traversal of a file hierarchy,
and shall not follow any symbolic links.
For each source_file, the following steps shall be taken:
1. If source_file references the same file as dest_file, cp may
write a diagnostic message to standard error; it shall do
nothing more with source_file and shall go on to any remaining
files.
2. If source_file is of type directory, the following steps shall
be taken:
a. If the -R option was not specified, cp shall write a
diagnostic message to standard error, do nothing more with
source_file, and go on to any remaining files.
b. If source_file was not specified as an operand and
source_file is dot or dot-dot, cp shall do nothing more
with source_file and go on to any remaining files.
c. If dest_file exists and it is a file type not specified by
the System Interfaces volume of POSIX.1‐2017, the behavior
is implementation-defined.
d. If dest_file exists and it is not of type directory, cp
shall write a diagnostic message to standard error, do
nothing more with source_file or any files below
source_file in the file hierarchy, and go on to any
remaining files.
e. If the directory dest_file does not exist, it shall be
created with file permission bits set to the same value as
those of source_file, modified by the file creation mask
of the user if the -p option was not specified, and then
bitwise-inclusively OR'ed with S_IRWXU. If dest_file
cannot be created, cp shall write a diagnostic message to
standard error, do nothing more with source_file, and go
on to any remaining files. It is unspecified if cp
attempts to copy files in the file hierarchy rooted in
source_file.
f. The files in the directory source_file shall be copied to
the directory dest_file, taking the four steps (1 to 4)
listed here with the files as source_files.
g. If dest_file was created, its file permission bits shall
be changed (if necessary) to be the same as those of
source_file, modified by the file creation mask of the
user if the -p option was not specified.
h. The cp utility shall do nothing more with source_file and
go on to any remaining files.
3. If source_file is of type regular file, the following steps
shall be taken:
a. The behavior is unspecified if dest_file exists and was
written by a previous step. Otherwise, if dest_file
exists, the following steps shall be taken:
i. If the -i option is in effect, the cp utility shall
write a prompt to the standard error and read a line
from the standard input. If the response is not
affirmative, cp shall do nothing more with
source_file and go on to any remaining files.
ii. A file descriptor for dest_file shall be obtained by
performing actions equivalent to the open() function
defined in the System Interfaces volume of
POSIX.1‐2017 called using dest_file as the path
argument, and the bitwise-inclusive OR of O_WRONLY
and O_TRUNC as the oflag argument.
iii. If the attempt to obtain a file descriptor fails and
the -f option is in effect, cp shall attempt to
remove the file by performing actions equivalent to
the unlink() function defined in the System
Interfaces volume of POSIX.1‐2017 called using
dest_file as the path argument. If this attempt
succeeds, cp shall continue with step 3b.
b. If dest_file does not exist, a file descriptor shall be
obtained by performing actions equivalent to the open()
function defined in the System Interfaces volume of
POSIX.1‐2017 called using dest_file as the path argument,
and the bitwise-inclusive OR of O_WRONLY and O_CREAT as
the oflag argument. The file permission bits of
source_file shall be the mode argument.
c. If the attempt to obtain a file descriptor fails, cp shall
write a diagnostic message to standard error, do nothing
more with source_file, and go on to any remaining files.
d. The contents of source_file shall be written to the file
descriptor. Any write errors shall cause cp to write a
diagnostic message to standard error and continue to step
3e.
e. The file descriptor shall be closed.
f. The cp utility shall do nothing more with source_file. If
a write error occurred in step 3d, it is unspecified if cp
continues with any remaining files. If no write error
occurred in step 3d, cp shall go on to any remaining
files.
4. Otherwise, the -R option was specified, and the following
steps shall be taken:
a. The dest_file shall be created with the same file type as
source_file.
b. If source_file is a file of type FIFO, the file permission
bits shall be the same as those of source_file, modified
by the file creation mask of the user if the -p option was
not specified. Otherwise, the permissions, owner ID, and
group ID of dest_file are implementation-defined.
If this creation fails for any reason, cp shall write a
diagnostic message to standard error, do nothing more with
source_file, and go on to any remaining files.
c. If source_file is a file of type symbolic link, and the
options require the symbolic link itself to be acted upon,
the pathname contained in dest_file shall be the same as
the pathname contained in source_file.
If this fails for any reason, cp shall write a diagnostic
message to standard error, do nothing more with
source_file, and go on to any remaining files.
If the implementation provides additional or alternate access
control mechanisms (see the Base Definitions volume of
POSIX.1‐2017, Section 4.5, File Access Permissions), their effect
on copies of files is implementation-defined.
The cp utility shall conform to the Base Definitions volume of
POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
The following options shall be supported:
-f If a file descriptor for a destination file cannot be
obtained, as described in step 3.a.ii., attempt to
unlink the destination file and proceed.
-H Take actions based on the type and contents of the file
referenced by any symbolic link specified as a
source_file operand.
-i Write a prompt to standard error before copying to any
existing non-directory destination file. If the response
from the standard input is affirmative, the copy shall
be attempted; otherwise, it shall not.
-L Take 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.
-P Take actions on any symbolic link specified as a
source_file operand or any symbolic link encountered
during traversal of a file hierarchy.
-p Duplicate the following characteristics of each source
file in the corresponding destination file:
1. The time of last data modification and time of last
access. If this duplication fails for any reason, cp
shall write a diagnostic message to standard error.
2. The user ID and group ID. If this duplication fails
for any reason, it is unspecified whether cp writes
a diagnostic message to standard error.
3. The file permission bits and the S_ISUID and S_ISGID
bits. Other, implementation-defined, bits may be
duplicated as well. If this duplication fails for
any reason, cp shall write a diagnostic message to
standard error.
If the user ID or the group ID cannot be duplicated, the
file permission bits S_ISUID and S_ISGID shall be
cleared. If these bits are present in the source file
but are not duplicated in the destination file, it is
unspecified whether cp writes a diagnostic message to
standard error.
The order in which the preceding characteristics are
duplicated is unspecified. The dest_file shall not be
deleted if these characteristics cannot be preserved.
-R Copy file hierarchies.
Specifying more than one of the mutually-exclusive options -H, -L,
and -P shall not be considered an error. The last option specified
shall determine the behavior of the utility.
The following operands shall be supported:
source_file
A pathname of a file to be copied. If a source_file
operand is '-', it shall refer to a file named -;
implementations shall not treat it as meaning standard
input.
target_file
A pathname of an existing or nonexistent file, used for
the output when a single file is copied. If a
target_file operand is '-', it shall refer to a file
named -; implementations shall not treat it as meaning
standard output.
target A pathname of a directory to contain the copied files.
The standard input shall be used to read an input line in response
to each prompt specified in the STDERR section. Otherwise, the
standard input shall not be used.
The input files specified as operands may be of any file type.
The following environment variables shall affect the execution of
cp:
LANG Provide a default value for the internationalization
variables that are unset or null. (See the Base
Definitions volume of POSIX.1‐2017, Section 8.2,
Internationalization Variables for the precedence of
internationalization variables used to determine the
values of locale categories.)
LC_ALL If set to a non-empty string value, override the values
of all the other internationalization variables.
LC_COLLATE
Determine the locale for the behavior of ranges,
equivalence classes, and multi-character collating
elements used in the extended regular expression defined
for the yesexpr locale keyword in the LC_MESSAGES
category.
LC_CTYPE Determine the locale for the interpretation of sequences
of bytes of text data as characters (for example,
single-byte as opposed to multi-byte characters in
arguments and input files) and the behavior of character
classes used in the extended regular expression defined
for the yesexpr locale keyword in the LC_MESSAGES
category.
LC_MESSAGES
Determine the locale used to process affirmative
responses, and the locale used to affect the format and
contents of diagnostic messages and prompts written to
standard error.
NLSPATH Determine the location of message catalogs for the
processing of LC_MESSAGES.
Default.
Not used.
A prompt shall be written to standard error under the conditions
specified in the DESCRIPTION section. The prompt shall contain the
destination pathname, but its format is otherwise unspecified.
Otherwise, the standard error shall be used only for diagnostic
messages.
The output files may be of any type.
None.
The following exit values shall be returned:
0 All files were copied successfully.
>0 An error occurred.
If cp is prematurely terminated by a signal or error, files or
file hierarchies may be only partially copied and files and
directories may have incorrect permissions or access and
modification times.
The following sections are informative.
The set-user-ID and set-group-ID bits are explicitly cleared when
files are created. This is to prevent users from creating programs
that are set-user-ID or set-group-ID to them when copying files or
to make set-user-ID or set-group-ID files accessible to new groups
of users. For example, if a file is set-user-ID and the copy has
a different group ID than the source, a new group of users has
execute permission to a set-user-ID program than did previously.
In particular, this is a problem for superusers copying users'
trees.
None.
The -i option exists on BSD systems, giving applications and users
a way to avoid accidentally removing files when copying. Although
the 4.3 BSD version does not prompt if the standard input is not a
terminal, the standard developers decided that use of -i is a
request for interaction, so when the destination path exists, the
utility takes instructions from whatever responds on standard
input.
The exact format of the interactive prompts is unspecified. Only
the general nature of the contents of prompts are specified
because implementations may desire more descriptive prompts than
those used on historical implementations. Therefore, an
application using the -i option relies on the system to provide
the most suitable dialog directly with the user, based on the
behavior specified.
The -p option is historical practice on BSD systems, duplicating
the time of last data modification and time of last access. This
volume of POSIX.1‐2017 extends it to preserve the user and group
IDs, as well as the file permissions. This requirement has obvious
problems in that the directories are almost certainly modified
after being copied. This volume of POSIX.1‐2017 requires that the
modification times be preserved. The statement that the order in
which the characteristics are duplicated is unspecified is to
permit implementations to provide the maximum amount of security
for the user. Implementations should take into account the
obvious security issues involved in setting the owner, group, and
mode in the wrong order or creating files with an owner, group, or
mode different from the final value.
It is unspecified whether cp writes diagnostic messages when the
user and group IDs cannot be set due to the widespread practice of
users using -p to duplicate some portion of the file
characteristics, indifferent to the duplication of others.
Historic implementations only write diagnostic messages on errors
other than [EPERM].
Earlier versions of this standard included support for the -r
option to copy file hierarchies. The -r option is historical
practice on BSD and BSD-derived systems. This option is no longer
specified by POSIX.1‐2008 but may be present in some
implementations. The -R option was added as a close synonym to the
-r option, selected for consistency with all other options in this
volume of POSIX.1‐2017 that do recursive directory descent.
The difference between -R and the removed -r option is in the
treatment by cp of file types other than regular and directory. It
was implementation-defined how the - option treated special files
to allow both historical implementations and those that chose to
support -r with the same abilities as -R defined by this volume of
POSIX.1‐2017. The original -r flag, for historic reasons, did not
handle special files any differently from regular files, but
always read the file and copied its contents. This had obvious
problems in the presence of special file types; for example,
character devices, FIFOs, and sockets.
When a failure occurs during the copying of a file hierarchy, cp
is required to attempt to copy files that are on the same level in
the hierarchy or above the file where the failure occurred. It is
unspecified if cp shall attempt to copy files below the file where
the failure occurred (which cannot succeed in any case).
Permissions, owners, and groups of created special file types have
been deliberately left as implementation-defined. This is to allow
systems to satisfy special requirements (for example, allowing
users to create character special devices, but requiring them to
be owned by a certain group). In general, it is strongly suggested
that the permissions, owner, and group be the same as if the user
had run the historical mknod, ln, or other utility to create the
file. It is also probable that additional privileges are required
to create block, character, or other implementation-defined
special file types.
Additionally, the -p option explicitly requires that all set-user-
ID and set-group-ID permissions be discarded if any of the owner
or group IDs cannot be set. This is to keep users from
unintentionally giving away special privilege when copying
programs.
When creating regular files, historical versions of cp use the
mode of the source file as modified by the file mode creation
mask. Other choices would have been to use the mode of the source
file unmodified by the creation mask or to use the same mode as
would be given to a new file created by the user (plus the
execution bits of the source file) and then modify it by the file
mode creation mask. In the absence of any strong reason to change
historic practice, it was in large part retained.
When creating directories, historical versions of cp use the mode
of the source directory, plus read, write, and search bits for the
owner, as modified by the file mode creation mask. This is done so
that cp can copy trees where the user has read permission, but the
owner does not. A side-effect is that if the file creation mask
denies the owner permissions, cp fails. Also, once the copy is
done, historical versions of cp set the permissions on the created
directory to be the same as the source directory, unmodified by
the file creation mask.
This behavior has been modified so that cp is always able to
create the contents of the directory, regardless of the file
creation mask. After the copy is done, the permissions are set to
be the same as the source directory, as modified by the file
creation mask. This latter change from historical behavior is to
prevent users from accidentally creating directories with
permissions beyond those they would normally set and for
consistency with the behavior of cp in creating files.
It is not a requirement that cp detect attempts to copy a file to
itself; however, implementations are strongly encouraged to do so.
Historical implementations have detected the attempt in most
cases.
There are two methods of copying subtrees in this volume of
POSIX.1‐2017. The other method is described as part of the pax
utility (see pax(1p)). Both methods are historical practice. The
cp utility provides a simpler, more intuitive interface, while pax
offers a finer granularity of control. Each provides additional
functionality to the other; in particular, pax maintains the hard-
link structure of the hierarchy, while cp does not. It is the
intention of the standard developers that the results be similar
(using appropriate option combinations in both utilities). The
results are not required to be identical; there seemed
insufficient gain to applications to balance the difficulty of
implementations having to guarantee that the results would be
exactly identical.
The wording allowing cp to copy a directory to implementation-
defined file types not specified by the System Interfaces volume
of POSIX.1‐2017 is provided so that implementations supporting
symbolic links are not required to prohibit copying directories to
symbolic links. Other extensions to the System Interfaces volume
of POSIX.1‐2017 file types may need to use this loophole as well.
None.
mv(1p), find(1p), ln(1p), pax(1p)
The Base Definitions volume of POSIX.1‐2017, Section 4.5, File
Access Permissions, Chapter 8, Environment Variables, Section
12.2, Utility Syntax Guidelines
The System Interfaces volume of POSIX.1‐2017, open(3p), unlink(3p)
Portions of this text are reprinted and reproduced in electronic
form from IEEE Std 1003.1-2017, Standard for Information
Technology -- Portable Operating System Interface (POSIX), The
Open Group Base Specifications Issue 7, 2018 Edition, Copyright
(C) 2018 by the Institute of Electrical and Electronics Engineers,
Inc and The Open Group. In the event of any discrepancy between
this version 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 .
Any typographical or formatting errors that appear in this page
are most likely to have been introduced during the conversion of
the source files to man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2017 CP(1P)
Pages that refer to this page: mv(1p), pax(1p)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|