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{num-
bered,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 desti-
nation 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 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 produc-
ing 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.
POSIXOPTIONS
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.)
-p Preserve the original files' owner, group, permissions (includ-
ing 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 encoun-
tered. (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 ver-
sion of cp (see below) is not forbidden.)
-- Terminate option list.
GNUDETAILS
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 iden-
tical, 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.
GNUOPTIONS
-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 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 destination files.
-l,--link
Make hard links instead of copies of non-directories.
-p,--preserve
Preserve the original files' owner, group, permissions, and
timestamps.
-P,--parents
Form the name of each destination file by appending to the tar-
get 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 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 copy-
ing. Opening an unknown device file, say a scanner, has unknown
effects on the hardware.)
-R,--recursive
Copy directories recursively, preserving non-directories (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 corre-
sponding 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.
always Always make the output file sparse. This is useful when
the input file resides on a filesystem that does not sup-
port sparse files, but the output file is on a filesystem
that does.
never Never make the output file sparse. If you find an appli-
cation 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 sup-
port 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 filesystems from the
one that the copy started on.
GNUBACKUPOPTIONS
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.
--backup=CONTROL
(Since fileutils-4.1.)
-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 '~'.
-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 'sim-
ple'). If this option is not specified, the value of the VER-
SION_CONTROL environment variable is used. And if VERSION_CON-
TROL 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.
nil, existing
Make numbered backups of files that already have them,
simple backups of the others.
never, simple
Always make simple backups.
GNUSTANDARDOPTIONS
--help Print a usage message on standard output and exit successfully.
--version
Print version information on standard output, then exit success-
fully.
-- 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 SIM-
PLE_BACKUP_SUFFIX and VERSION_CONTROL control backup file naming, as
described above.
CONFORMINGTO
POSIX 1003.2
NOTES
This page describes cp as found in the fileutils-4.0 package; other
versions may differ slightly. Mail corrections and additions to
aeb
cwi.nl. Report bugs in the program to fileutils-
bugsgnu.edu.
GNU fileutils 4.0 1998-11 CP(1)
Take our 
