cp — Copy a file

cp [–fimp] file1 file2
cp [–fimp] file ... directory
cp –R [–fimp] source...  directory
cp –r [–fimp] source...  directory

Purpose

cp copies files to a target named by the last argument on its command line. If the target is an existing file, cp overwrites it; if it does not exist, cp creates it. If the target file already exists and does not have write permission, cp denies access and continues with the next copy.

If you specify more than two path names, the last path name (that is, the target) must be a directory. If the target is a directory, cp copies the sources into that directory with names given by the final component of the source path name.

Options

cp accepts the following options:
–f
Attempts to replace files that do not have write permission.
–i
Asks you if you want to overwrite an existing file, whether or not the file is read-only.
–m
Sets the modification and access time of each destination file to that of the corresponding source file. Normally, cp sets the modification time of the destination file to the present.
–p
Preserves the modification and access times (as the –m option does); in addition, it preserves file mode, owner, and group owner, if possible.
–R
Clones the source trees. cp copies all the files and subdirectories specified by source... into directory, making careful arrangements to duplicate special files (FIFO, character special).
–r
Clones the source trees, but makes no allowances for special files (FIFO, character special). Consequently, cp attempts to read from a device rather than duplicate the special file. This is similar to, but less useful than, the preferred –R.

Localization

cp uses the following localization environment variables:
  • LANG
  • LC_ALL
  • LC_COLLATE
  • LC_CTYPE
  • LC_MESSAGES
See Localization for more information.

Exit Values

Possible exit status values are:
0
Successful completion.
1
Failure due to any of the following:
  • An argument had a trailing slash (/) but was not a directory.
  • Inability to find a file.
  • Inability to open an input file for reading.
  • Inability to create or open an output file.
  • A read error occurred on an input file.
  • A write error occurred on an output file.
  • The input and output files were the same file.
  • An irrecoverable error when using –r or –R.
  • Possible irrecoverable –r or –R errors include:
    • Inability to access a file.
    • Inability to change permissions on a target file.
    • Inability to read a directory.
    • Inability to create a directory.
    • A target that is not a directory.
    • Source and destination directories are the same.
2
Failure due to any of the following:
  • An incorrect command-line option.
  • Too few arguments on the command line.
  • A target that should be a directory but isn't.
  • No space left on target device.
  • Insufficient memory to hold the data to be copied.
  • Inability to create a directory to hold a target file.

Messages and Return Codes

Possible error messages include:
cannot allocate target string
cp has no space to hold the name of the target file. Try to release some memory to give cp more space.
name is a directory (not copied)
You did not specify –r or –R, but one of the names you asked to copy was the name of a directory.
target name?
You are attempting to copy a file with the –i option, but there is already a file with the target name. If you have specified –f, you can write over the existing file by typing y and pressing <Enter>. If you do not want to write over the existing file, type n and press <Enter>. If you did not specify –f and the file is read-only, you are not given the opportunity to overwrite it.
source name and target name are identical
The source and the target are actually the same file (for example, because of links). In this case, cp does nothing.
unreadable directory name
cp cannot read the specified directory—for example, because you do not have appropriate permission.

Portability

POSIX.2, X/Open Portability Guide, UNIX systems.

The –f and –m options are extensions of the POSIX standard.

Related Commands

cat, cpio, mv, rm, ln