CP(1) CP(1)
NAME
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}] [--sparse=WHEN] [--help]
[--version] [--]
DESCRIPTION
cp copies files (or, optionally, directories). You can
either copy one file to a given destination, or copy arbi-
trarily 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). (But during the recursive copy of directo-
ries, 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 direc-
tory.)
Nothing is done when copying a file to itself (except pos-
sibly producing an error message). When copying to a dif-
ferent 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
GNU fileutils 4.0 November 1998 1
CP(1) CP(1)
above.)
-i Prompt whether to overwrite existing regular desti-
nation files. (Write a question on stderr, and
read the answer from stdin. Only copy upon an
affirmative answer.)
-p Preserve the original files' owner, group, permis-
sions (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.)
-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.)
-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.)
-- 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 num-
bered, 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.
-d, --no-dereference
Copy symbolic links as symbolic links rather than
copying the files that they point to, and preserve
GNU fileutils 4.0 November 1998 2
CP(1) CP(1)
hard links between source files in the copies.
-f, --force
Remove existing destination files, and never prompt
before doing so.
-i, --interactive
Prompt whether to overwrite existing regular desti-
nation files.
-l, --link
Make hard links instead of copies of non-directo-
ries.
-p, --preserve
Preserve the original files' owner, group, permis-
sions, and timestamps.
-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.
-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 read-
ing 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.)
-R, --recursive
Copy directories recursively, preserving non-direc-
tories (see -r just above).
--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.
GNU fileutils 4.0 November 1998 3
CP(1) CP(1)
The WHEN value can be one of the following:
auto The default behavior: the output file is
sparse if the input file is sparse.
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 filesys-
tem that does.
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-direc-
tories. 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.
-u, --update
Do not copy a nondirectory that has an existing
destination with the same or newer modification
time.
-v, --verbose
Print the name of each file before copying it.
-x, --one-file-system
Skip subdirectories that are on different filesys-
tems 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 over-
written or removed.
-S SUFFIX, --suffix=SUFFIX
Append SUFFIX to each backup file made. If this
option is not specified, the value of the SIM-
PLE_BACKUP_SUFFIX environment variable is used.
And if SIMPLE_BACKUP_SUFFIX is not set, the default
GNU fileutils 4.0 November 1998 4
CP(1) CP(1)
is `~'.
-V METHOD, --version-control=METHOD
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_CON-
TROL is not set, the default backup type is `exist-
ing'.
This option corresponds to the Emacs variable `ver-
sion-control'. The valid METHODs are (unique
abbreviations are accepted):
t, numbered
Always make numbered backups.
nil, existing
Make numbered backups of files that already
have them, simple backups of the others.
never, simple
Always make simple backups.
GNU STANDARD OPTIONS
--help Print a usage message on standard output and exit
successfully.
--version
Print version information on standard output, then
exit successfully.
-- 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 pack-
age; other versions may differ slightly. Mail corrections
and additions to aeb@cwi.nl. Report bugs in the program
to fileutils-bugs@gnu.ai.mit.edu.
GNU fileutils 4.0 November 1998 5