CP(P) POSIX Programmer's Manual CP(P)NAMEcp - copy files
SYNOPSIScp [-fip] source_file target_file
cp [-fip] source_file ... target
cp-R [-H | -L | -P][-fip] source_file ... target
cp-r [-H | -L | -P][-fip] source_file ... target
DESCRIPTION
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 desti‐
nation path named by target_file.
The second synopsis form is denoted by two or more operands where the
-R or -r options are 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 is a file of a type
defined by the System Interfaces volume of IEEE Std 1003.1-2001, but is
not a file of type 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 slash character, and the
last component of source_file.
The third and fourth synopsis forms are denoted by two or more operands
where the -R or -r options are specified. The cp utility shall copy
each file in the file hierarchy rooted in each source_file to a desti‐
nation path named as follows:
* If target exists and is a file of type directory, the name of the
corresponding destination path for each file in the file hierarchy
shall be the concatenation of target, a slash character, 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 oper‐
ands are specified, or if target exists and is a file of a type defined
by the System Interfaces volume of IEEE Std 1003.1-2001, but is not a
file of type 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 neither the -R nor -r options were 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.
* 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 encoun‐
tered 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 encoun‐
tered during traversal of a file hierarchy, and shall not follow
any symbolic links.
* If the -r option was specified, the behavior is implementation-
defined.
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 neither the -R or -r options were 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 IEEE Std 1003.1-2001, 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. 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 per‐
forming actions equivalent to the open() function defined
in the System Interfaces volume of IEEE Std 1003.1-2001
called using dest_file as the path argument, and the bit‐
wise-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
IEEE Std 1003.1-2001 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() func‐
tion defined in the System Interfaces volume of
IEEE Std 1003.1-2001 called using dest_file as the path argu‐
ment, 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 diag‐
nostic 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 con‐
tinues with any remaining files. If no write error occurred in
step 3d, cp shall go on to any remaining files.
4. Otherwise, the following steps shall be taken:
a. If the -r option was specified, the behavior is implementation-
defined.
b. If the -R option was specified, the following steps shall be
taken:
i. The dest_file shall be created with the same file type as
source_file.
ii. 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 diag‐
nostic message to standard error, do nothing more with
source_file, and go on to any remaining files.
iii. If source_file is a file of type symbolic link, the path‐
name contained in dest_file shall be the same as the path‐
name contained in source_file.
If this fails for any reason, cp shall write a diagnostic mes‐
sage 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 IEEE Std 1003.1-2001,
Section 4.4, File Access Permissions), their effect on copies of files
is implementation-defined.
OPTIONS
The cp utility shall conform to the Base Definitions volume of
IEEE Std 1003.1-2001, 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 refer‐
enced by any symbolic link specified as a source_file operand.
-i Write a prompt to standard error before copying to any existing
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 refer‐
enced by any symbolic link specified as a source_file operand or
any symbolic links encountered during traversal of a file hier‐
archy.
-P Take actions on any symbolic link specified as a source_file op‐
erand 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 permis‐
sion 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 stan‐
dard error.
The order in which the preceding characteristics are duplicated is
unspecified. The dest_file shall not be deleted if these characteris‐
tics cannot be preserved.
-R Copy file hierarchies.
-r Copy file hierarchies. The treatment of special files is imple‐
mentation-defined.
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.
OPERANDS
The following operands shall be supported:
source_file
A pathname of a file to be copied.
target_file
A pathname of an existing or nonexistent file, used for the out‐
put when a single file is copied.
target A pathname of a directory to contain the copied files.
STDIN
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.
INPUT FILES
The input files specified as operands may be of any file type.
ENVIRONMENT VARIABLES
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
IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
ables 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 key‐
word 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 regu‐
lar expression defined for the yesexpr locale keyword in the
LC_MESSAGES category.
LC_MESSAGES
Determine the locale for the processing of affirmative responses
that should be used to affect the format and contents of diag‐
nostic messages written to standard error.
NLSPATH
Determine the location of message catalogs for the processing of
LC_MESSAGES .
ASYNCHRONOUS EVENTS
Default.
STDOUT
Not used.
STDERR
A prompt shall be written to standard error under the conditions speci‐
fied in the DESCRIPTION section. The prompt shall contain the destina‐
tion pathname, but its format is otherwise unspecified. Otherwise, the
standard error shall be used only for diagnostic messages.
OUTPUT FILES
The output files may be of any type.
EXTENDED DESCRIPTION
None.
EXIT STATUS
The following exit values shall be returned:
0 All files were copied successfully.
>0 An error occurred.
CONSEQUENCES OF ERRORS
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.
APPLICATION USAGE
The difference between -R and -r is in the treatment by cp of file
types other than regular and directory. The original -r flag, for his‐
toric reasons, does not handle special files any differently from regu‐
lar files, but always reads the file and copies its contents. This has
obvious problems in the presence of special file types; for example,
character devices, FIFOs, and sockets. The -R option is intended to
recreate the file hierarchy and the -r option supports historical prac‐
tice. It was anticipated that a future version of this volume of
IEEE Std 1003.1-2001 would deprecate the -r option, and for that rea‐
son, there has been no attempt to fix its behavior with respect to
FIFOs or other file types where copying the file is clearly wrong. How‐
ever, some implementations support -r with the same abilities as the -R
defined in this volume of IEEE Std 1003.1-2001. To accommodate them as
well as systems that do not, the differences between -r and -R are
implementation-defined. Implementations may make them identical. The -r
option is marked obsolescent.
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.
EXAMPLES
None.
RATIONALE
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 inter‐
action, so when the destination path exists, the utility takes instruc‐
tions 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 imple‐
mentations may desire more descriptive prompts than those used on his‐
torical 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
IEEE Std 1003.1-2001 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 IEEE Std 1003.1-2001 requires that the modification
times be preserved. The statement that the order in which the charac‐
teristics 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 set‐
ting 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, indif‐
ferent to the duplication of others. Historic implementations only
write diagnostic messages on errors other than [EPERM].
The -r option is historical practice on BSD and BSD-derived systems,
copying file hierarchies as opposed to single files. This functional‐
ity is used heavily in historical applications, and its loss would sig‐
nificantly decrease consensus. The -R option was added as a close syn‐
onym to the -r option, selected for consistency with all other options
in this volume of IEEE Std 1003.1-2001 that do recursive directory
descent.
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 unspeci‐
fied 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 per‐
missions, 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. His‐
torical implementations have detected the attempt in most cases.
There are two methods of copying subtrees in this volume of
IEEE Std 1003.1-2001. The other method is described as part of the pax
utility (see pax ). Both methods are historical practice. The cp util‐
ity 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 combi‐
nations in both utilities). The results are not required to be identi‐
cal; there seemed insufficient gain to applications to balance the dif‐
ficulty 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
IEEE Std 1003.1-2001 is provided so that implementations supporting
symbolic links are not required to prohibit copying directories to sym‐
bolic links. Other extensions to the System Interfaces volume of
IEEE Std 1003.1-2001 file types may need to use this loophole as well.
FUTURE DIRECTIONS
The -r option may be removed; use -R instead.
SEE ALSO
mv , find , ln , pax , the System Interfaces volume of
IEEE Std 1003.1-2001, open(), unlink()COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .
IEEE/The Open Group 2003 CP(P)
