| 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:
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:
For each source_file, the following steps shall be taken:
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.
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:
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.
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:
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:
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:
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). 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, find, ln, pax
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(), unlink()
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 .
| 2017 | IEEE/The Open Group |