CP(1) General Commands Manual CP(1)

cp — copy files

cp [-fip] source_file target_file

cp [-fip] source_file ... target

cp -R [-fip] source_file ... target

cp -r [-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 will copy the contents of source_file to the destination 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 is 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 XSH specification, but is not a file of type directory. The cp utility will copy the contents of each 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 will copy each file in the file hierarchy rooted in each source_file to a destination 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 will 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 will be the name of the corresponding destination path for all other files in the file hierarchy will be the concatenation of target, a slash character and the pathname of the file relative to source_file.

It is an error if target does not exist and more than two operands are specified, or if target exists and is a file of a type defined by the XSH specification, but is not a file of type directory.

In the following description, 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. The term dest_file refers to the file named by the destination path.

For each source_file, the following steps will be taken:

  1. If source_file references the same file as dest_file, cp may write a diagnostic message to standard error; it will do nothing more with source_file and will go on to any remaining files.
  2. If source_file is of type directory, the following steps will be taken:
  3. If neither the -R or -r options were specified, cp will write a diagnostic message to standard error, do nothing more with source_file and go on to any remaining files.

    If source_file was not specified as an operand and source_file is dot or dot-dot, cp will do nothing more with source_file and go on to any remaining files.

    If dest_file exists and it is a file type not specified by the XSH specification, the behaviour is implementation-dependent.

    If dest_file exists and it is not of type directory, cp will 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.

    If the directory dest_file does not exist, it will 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 ORed with S_IRWXU. If dest_file cannot be created, cp will 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 will attempt to copy files in the file hierarchy rooted in source_file.

    The files in the directory source_file will be copied to the directory dest_file, taking the four steps [1-4] listed here with the files as source_file s.

    If dest_file was created, its file permission bits will 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.

    The cp utility will do nothing more with source_file and go on to any remaining files.

  4. If source_file is of type regular file, the following steps will be taken:
  5. If dest_file exists, the following steps are taken:
    1. If the -i option is in effect, the cp utility will write a prompt to the standard error and read a line from the standard input. If the response is not affirmative, cp will do nothing more with source_file and go on to any remaining files.
    2. A file descriptor for dest_file will be obtained by performing actions equivalent to the XSH specification open(3) function called using dest_file as the path argument, and the bitwise inclusive OR of O_WRONLY and O_TRUNC as the oflag argument.
    3. If the attempt to obtain a file descriptor fails and the -f option is in effect, cp will attempt to remove the file by performing actions equivalent to the XSH specification unlink(3) function called using dest_file as the path argument. If this attempt succeeds, cp will continue with step 3b.

    If dest_file does not exist, a file descriptor will be obtained by performing actions equivalent to the XSH specification function called using dest_file as the argument, and the bitwise inclusive OR of O_WRONLY and O_CREAT as the argument. The file permission bits of source_file will be the argument.

    If the attempt to obtain a file descriptor fails, cp will write a diagnostic message to standard error, do nothing more with source_file, and go on to any remaining files.

    The contents of source_file will be written to the file descriptor. Any write errors will cause cp to write a diagnostic message to standard error and continue to step 3e.

    The file descriptor will be closed.

    The cp utility will 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 will go on to any remaining files.

  6. Otherwise, the following steps will be taken:
  7. If the -r option was specified, the behaviour is implementation-dependent.

    If the -R option was specified, the following steps will be taken:

    1. The dest_file will be created with the same file type as source_file .
    2. If source_file is a file of type FIFO, the file permission bits will 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-dependent.
    3. If this creation fails for any reason, cp will 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 in the specification, glossary(7) ), their effect on copies of files is implementation-dependent.

The cp utility supports the XBD specification, .

The following options are supported:

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.
Write a prompt to standard error before copying to any existing destination file. If the response from the standard input is affirmative, the copy will be attempted, otherwise not.
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 will 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-dependent, bits may be duplicated as well. If this duplication fails for any reason, cp will 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 will 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 will not be deleted if these characteristics cannot be preserved.
Copy file hierarchies.
Copy file hierarchies. The treatment of special files is implementation-dependent.

The following operands are supported:

source_file
A pathname of a file 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.

Used to read an input line in response to each prompt specified in the STDERR section. Otherwise, the standard input will not be used.

The input files specified as operands may be of any file type.

The following environment variables affect the execution of cp :

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.
If set to a non-empty string value, override the values of all the other internationalisation variables.
Determine the locale for the behaviour 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.
Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files) and the behaviour of character classes used in the extended regular expression defined for the yesexpr locale keyword in the LC_MESSAGES category.
Determine the locale for the processing of affirmative responses that should be used to affect the format and contents of diagnostic messages written to standard error.
Determine the location of message catalogues for the processing of LC_MESSAGES .

Default.

Not used.

A prompt will be written to standard error under the conditions specified in the DESCRIPTION section. The prompt will contain the destination pathname, but its format is otherwise unspecified. Otherwise, the standard error will be used only for diagnostic messages.

The output files may be of any type.

None.

The following exit values are returned:

All files were copied successfully.
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 difference between -R and -r is in the treatment by cp of file types other than regular and directory. The original -r flag, for historic reasons, does not handle special files any differently from regular 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 practice. It is anticipated that a future issue of this specification will deprecate the -r option, and for that reason, there has been no attempt to fix its behaviour with respect to FIFOs or other file types where copying the file is clearly wrong. However, some systems support -r with the same abilities as the -R defined in the ISO/IEC 9945-2:1993 (“POSIX.2”) standard. To accommodate them as well as systems that do not, the differences between -r and -R are implementation-dependent. Implementations may make them identical.

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 -r option may be removed; use -R instead.

mv(1) , find(1) , ln(1) , pax(1) .

February 1997 posix.fail