[man page] cp – copy

CP

Section: User Commands (1)
Updated: 1998-11
Index
Return to Home Page

CP – copy files and directories

SYNOPSIS

cp [options] file path

cp [options] file… directory

POSIX options:
[-fipRr] [–]

GNU options (shortest form):
[-abdfilprsuvxPR]

[-S SUFFIX]

[-V {numbered,existing,simple}]

[–backup=CONTROL]

[–sparse=WHEN]

[–help] [–version] [–]

DESCRIPTION

cp copies files (or, optionally, directories).

You can either copy one file to a given destination, or copy arbitrarily many files to a destination directory.

If the last argument names an existing directory, cp copies each source file into that directory (retaining the same name).
Otherwise, if only two files are given, it copies the first onto the second.
It is an error if the last argument is not a directory and more than two non-option arguments are given.

(Thus, if /a is a directory, then `cp -r /a /b’ will copy /a to /b/a and /a/x to /b/a/x in case a directory /b existed already, but it will copy /a to /b and /a/x to /b/x if there was no /b beforehand, while it will fail in case there was an ordinary file /b.)

The modes of the files and directories created will be the same as those of the original files, ANDed by 0777, and modified by
the user’s umask (unless the -p option was specified).

However, during the recursive copy of directories, newly created directories will temporarily get their final mode ORed with
S_IRWXU (0700), so as to allow the process to read, write and search the newly created directory.

Nothing is done when copying a file to itself (except possibly producing an error message).

When copying to a different existing file, it is opened using `open(path, O_WRONLY | O_TRUNC)’.

When copying to a new file it is created using `open(path, O_WRONLY | O_CREAT, mode)’.
If this fails, the file existed, and the -f option was given, cp tries to delete (unlink) the existing file, and if this succeeds proceeds as for a new file.

POSIX OPTIONS

POSIX recognizes four options and a half:


-f
Remove existing destination files if required. (See above.)
-i
Prompt whether to overwrite existing regular destination files.
(Write a question on stderr, and read the answer from stdin. Only copy upon an affirmative answer.)
l
-p
Preserve the original files' owner, group, permissions (including the setuid and setgid bits), time of last modification and time of last access.
In case duplication of owner or group fails, the setuid and setgid bits are cleared. 
(Note that afterwards source and copy may well have different times of last access, since the copy operation is an access to the source file.)
l
-R
Copy directories recursively, and do the right thing when
objects other than ordinary files or directories are encountered.
(Thus, the copy of a FIFO or special file is a FIFO or special file.)
l
-r
Copy directories recursively, and do something unspecified with objects other than ordinary files or directories. 
(Thus, it is allowed, in fact encouraged, to have the -r option a synonym for -R. However, silly behaviour, like that of the present GNU version of cp

(see below) is not forbidden.)
l
--
Terminate option list.

GNU DETAILS

Generally, files are written just as they are read. For exceptions,
see the
–sparse

option below.

By default, `cp’ does not copy directories (see -r below).

cp generally refuses to copy a file onto itself, with the following exception: if –force –backup is specified with source and dest identical, and

referring to a regular file, cp will make a backup file, either regular or numbered, as specified in the usual ways. This is useful when you simply want to make a

backup of an existing file before changing it.

GNU OPTIONS

-a, –archive

Preserve as much as possible of the structure and attributes of the original files in the copy (but do not preserve directory structure).
Equivalent to -dpR.
l

-d, –no-dereference

Copy symbolic links as symbolic links rather than copying the files that they point to, and preserve hard links between source files in the copies.
l

-f, –force

Remove existing destination files, and never prompt before doing so.

l

-i, –interactive

Prompt whether to overwrite existing regular destination files.
l

-l, –link

Make hard links instead of copies of non-directories.
l

-p, –preserve

Preserve the original files’ owner, group, permissions, and timestamps.
l

-P, –parents

Form the name of each destination file by appending to the target
directory a slash and the specified name of the source file. The
last argument given to
cp

must be the name of an existing directory. For example, the command:



    cp --parents a/b/c existing_dir

copies the file `a/b/c’ to `existing_dir/a/b/c’, creating any
missing intermediate directories.
l

-r

Copy directories recursively, copying any non-directories and non-symbolic links (that is, FIFOs and special files) as if they were regular files.
This means trying to read the data in each source file and writing it to the destination. Thus, with this option, `cp’ may well hang indefinitely reading a FIFO or /dev/tty.

(This is a bug. It means that you have to avoid -r and use -R if you don’t know what is in the tree you are copying.
Opening an unknown device file, say a scanner, has unknown effects on the hardware.)
l

-R, –recursive

Copy directories recursively, preserving non-directories (see -r just above).
l

–sparse=WHEN

A `sparse file’ contains `holes’ – sequences of zero bytes that do not occupy any physical disk blocks; the `read’ system call reads these as zeroes. This can both save

considerable disk space
and increase speed, since many binary files contain lots of consecutive zero bytes.
By default, cp detects holes in input source files via a crude heuristic and makes the corresponding output file sparse as well.

: The WHEN value can be one of the following:

auto: The default behavior: the output file is sparse if the input
file is sparse.
l
always: Always make the output file sparse. This is useful when the
input file resides on a filesystem that does not support
sparse files, but the output file is on a filesystem that does.
l
never: Never make the output file sparse. If you find an application for
this option, let us know.

-s, –symbolic-link: Make symbolic links instead of copies of non-directories. All
source file names must be absolute (starting with `/’) unless the
destination files are in the current directory. This option merely
results in an error message on systems that do not support
symbolic links.
l
-u, –update: Do not copy a nondirectory that has an existing destination with
the same or newer modification time.
l
-v, –verbose: Print the name of each file before copying it.
l
-x, –one-file-system: Skip subdirectories that are on different filesystems from the one
that the copy started on.

GNU BACKUP OPTIONS

The GNU versions of programs like
cp,

mv,

ln,

install

and
patch

will make a backup of files about to be overwritten, changed or destroyed
if that is desired. That backup files are desired is indicated by
the -b option. How they should be named is specified by the -V option.
In case the name of the backup file is given by the name of the file
extended by a suffix, this suffix is specified by the -S option.

-b, –backup: Make backups of files that are about to be overwritten or removed.
l
–backup=CONTROL: (Since fileutils-4.1.)
l
-S SUFFIX, –suffix=SUFFIX: Append
SUFFIX to each backup file made.
If this option is not specified, the value of the SIMPLE_BACKUP_SUFFIX environment variable is used. And if
SIMPLE_BACKUP_SUFFIX is not set, the default is `~’.l
-V METHOD, –version-control=METHOD

l

Specify how backup files are named.
The METHOD argument can be `numbered’ (or `t’), `existing’ (or `nil’), or `never’ (or `simple’).
If this option is not specified, the value of the VERSION_CONTROL environment variable is used. And if
VERSION_CONTROL is not set, the default backup type is `existing’.

This option corresponds to the Emacs variable `version-control’.
The valid METHODs are (unique abbreviations are accepted):

t, numbered: Always make numbered backups.
l
nil, existing: Make numbered backups of files that already have them, simple
backups of the others.
l
never, simple: Always make simple backups.

GNU STANDARD OPTIONS

–help: Print a usage message on standard output and exit successfully.
l
–version: Print version information on standard output, then exit successfully.
l
—: Terminate option list.

ENVIRONMENT

The variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE and LC_MESSAGES have the usual meaning. For the GNU version, the variables SIMPLE_BACKUP_SUFFIX and VERSION_CONTROL control backup file naming, as described above.

CONFORMING TO

POSIX 1003.2

NOTES

This page describes cp as found in the fileutils-4.0 package; other versions may differ slightly.

Report bugs in the program to fileutils-bugs@gnu.ai.mit.edu.