File: coreutils.info, Node: cp invocation, Next: dd invocation, Up: Basic operations
11.1 `cp': Copy files and directories
=====================================
`cp' copies files (or, optionally, directories). The copy is
completely independent of the original. You can either copy one file to
another, or copy arbitrarily many files to a destination directory.
Synopsis:
cp [OPTION]... SOURCE DEST
cp [OPTION]... SOURCE... 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.
Generally, files are written just as they are read. For exceptions,
see the `--sparse' option below.
By default, `cp' does not copy directories. However, the `-R',
`-a', and `-r' options cause `cp' to copy recursively by descending
into source directories and copying files to corresponding destination
directories.
By default, `cp' follows symbolic links only when not copying
recursively. This default can be overridden with the `--archive'
(`-a'), `-d', `--dereference' (`-L'), `--no-dereference' (`-P'), and
`-H' options. If more than one of these options is specified, the last
one silently overrides the others.
By default, `cp' copies the contents of special files only when not
copying recursively. This default can be overridden with the
`--copy-contents' option.
`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
(*note Backup options::). This is useful when you simply want to make
a backup of an existing file before changing it.
The program accepts the following options. Also see *Note Common
options::.
`-a'
`--archive'
Preserve as much as possible of the structure and attributes of the
original files in the copy (but do not attempt to preserve internal
directory structure; i.e., `ls -U' may list the entries in a copied
directory in a different order). Equivalent to `-dpPR'.
`-b'
`--backup[=METHOD]'
*Note Backup options::. Make a backup of each file that would
otherwise be overwritten or removed. As a special case, `cp'
makes a backup of SOURCE when the force and backup options are
given and SOURCE and DEST are the same name for an existing,
regular file. One useful application of this combination of
options is this tiny Bourne shell script:
#!/bin/sh
# Usage: backup FILE...
# Create a GNU-style backup of each listed FILE.
for i; do
cp --backup --force "$i" "$i"
done
`--copy-contents'
If copying recursively, copy the contents of any special files
(e.g., FIFOs and device files) as if they were regular files.
This means trying to read the data in each source file and writing
it to the destination. It is usually a mistake to use this
option, as it normally has undesirable effects on special files
like FIFOs and the ones typically found in the `/dev' directory.
In most cases, `cp -R --copy-contents' will hang indefinitely
trying to read from FIFOs and special files like `/dev/console',
and it will fill up your destination disk if you use it to copy
`/dev/zero'. This option has no effect unless copying
recursively, and it does not affect the copying of symbolic links.
`-d'
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. Equivalent to `--no-dereference
--preserve=links'.
`-f'
`--force'
When copying without this option and an existing destination file
cannot be opened for writing, the copy fails. However, with
`--force'), when a destination file cannot be opened, `cp' then
unlinks it and tries to open it again. Contrast this behavior
with that enabled by `--link' and `--symbolic-link', whereby the
destination file is never opened but rather is unlinked
unconditionally. Also see the description of
`--remove-destination'.
`-H'
If a command line argument specifies a symbolic link, then copy the
file it points to rather than the symbolic link itself. However,
copy (preserving its nature) any symbolic link that is encountered
via recursive traversal.
`-i'
`--interactive'
Prompt whether to overwrite existing regular destination files.
`-l'
`--link'
Make hard links instead of copies of non-directories.
`-L'
`--dereference'
Always follow symbolic links.
`-P'
`--no-dereference'
Copy symbolic links as symbolic links rather than copying the
files that they point to.
`-p'
`--preserve[=ATTRIBUTE_LIST]'
Preserve the specified attributes of the original files. If
specified, the ATTRIBUTE_LIST must be a comma-separated list of
one or more of the following strings:
`mode'
Preserve the permission attributes.
`ownership'
Preserve the owner and group. On most modern systems, only
the super-user may change the owner of a file, and regular
users may preserve the group ownership of a file only if they
happen to be a member of the desired group.
`timestamps'
Preserve the times of last access and last modification.
`links'
Preserve in the destination files any links between
corresponding source files.
`all'
Preserve all file attributes. Equivalent to specifying all
of the above.
Using `--preserve' with no ATTRIBUTE_LIST is equivalent to
`--preserve=mode,ownership,timestamps'.
In the absence of this option, each destination file is created
with the permissions of the corresponding source file, minus the
bits set in the umask and minus the set-user-id and set-group-id
bits. *Note File permissions::.
`--no-preserve=ATTRIBUTE_LIST'
Do not preserve the specified attributes. The ATTRIBUTE_LIST has
the same form as for `--preserve'.
`--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.
`--reply[=HOW]'
Using `--reply=yes' makes `cp' act as if `yes' were given as a
response to every prompt about a destination file. That
effectively cancels any preceding `--interactive' or `-i' option.
Specify `--reply=no' to make `cp' act as if `no' were given as a
response to every prompt about a destination file. Specify
`--reply=query' to make `cp' prompt the user about each existing
destination file.
`-R'
`-r'
`--recursive'
Copy directories recursively. Symbolic links are not followed by
default; see the `--archive' (`-a'), `-d', `--dereference' (`-L'),
`--no-dereference' (`-P'), and `-H' options. Special files are
copied by creating a destination file of the same type as the
source; see the `--copy-contents' option. It is not portable to
use `-r' to copy symbolic links or special files. On some non-GNU
systems, `-r' implies the equivalent of `-L' and `--copy-contents'
for historical reasons. Also, it is not portable to use `-R' to
copy symbolic links unless you also specify `-P', as POSIX allows
implementations that dereference symbolic links by default.
`--remove-destination'
Remove each existing destination file before attempting to open it
(contrast with `-f' above).
`--sparse=WHEN'
A "sparse file" contains "holes"--a sequence of zero bytes that
does 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. Only regular files may be sparse.
The WHEN value can be one of the following:
`auto'
The default behavior: if the input file is sparse, attempt to
make the output file sparse, too. However, if an output file
exists but refers to a non-regular file, then do not attempt
to make it sparse.
`always'
For each sufficiently long sequence of zero bytes in the
input file, attempt to create a corresponding hole in the
output file, even if the input file does not appear to be
sparse. This is useful when the input file resides on a
filesystem that does not support sparse files (for example,
`efs' filesystems in SGI IRIX 5.3 and earlier), but the
output file is on a type of filesystem that does support them.
Holes may be created only in regular files, so if the
destination file is of some other type, `cp' does not even
try to make it sparse.
`never'
Never make the output file sparse. This is useful in
creating a file for use with the `mkswap' command, since such
a file must not have any holes.
`--strip-trailing-slashes'
Remove any trailing slashes from each SOURCE argument. *Note
Trailing slashes::.
`-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.
`-S SUFFIX'
`--suffix=SUFFIX'
Append SUFFIX to each backup file made with `-b'. *Note Backup
options::.
`--target-directory=DIRECTORY'
Specify the destination DIRECTORY. *Note Target directory::.
`-v'
`--verbose'
Print the name of each file before copying it.
`-V METHOD'
`--version-control=METHOD'
Change the type of backups made with `-b'. The METHOD argument
can be `none' (or `off'), `numbered' (or `t'), `existing' (or
`nil'), or `never' (or `simple'). *Note Backup options::.
`-x'
`--one-file-system'
Skip subdirectories that are on different filesystems from the one
that the copy started on. However, mount point directories _are_
copied.
An exit status of zero indicates success, and a nonzero value
indicates failure.
|