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 argu-
ment is not a directory and more than two non-option argu-
ments are given.
(Thus, `cp -r /a /b' will copy /a to /b/a and /a/x to /b/a/x
in case /b exists already, but it will copy /a to /b and
/a/x to /b/x if there was no /b beforehand.)
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 possi-
bly 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
above.)
-i Prompt whether to overwrite existing regular destina-
tion 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
(including the setuid and setgid bits), time of last
modification and time of last access. In case duplica-
tion 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 unspeci-
fied with objects other than ordinary files or direc-
tories. (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.)
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.
-d, --no-dereference
Copy symbolic links as symbolic links rather than copy-
ing the files that they point to, and preserve hard
links between source files in the copies.
-f, --force
Remove existing destination files.
-i, --interactive
Prompt whether to overwrite existing regular destina-
tion 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 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', creat-
ing 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 copying. 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
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.
always
Always make the output file sparse. This is use-
ful when the input file resides on a filesystem
that does not support sparse files, but the output
file is on a filesystem 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-
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 sym-
bolic links.
-u, --update
Do not copy a nondirectory that has an existing desti-
nation 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.
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.
-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 `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.
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 suc-
cessfully.
--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-3.16 pack-
age; other versions may differ slightly. Mail corrections
and additions to aeb@cwi.nl and aw@mail1.bet1.puv.fi and
ragnar@lightside.ddns.org . Report bugs in the program to
fileutils-bugs@gnu.ai.mit.edu.