manpagez: man pages & more
info coreutils
Home | html | info | man
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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. Synopses:

 
cp [option]… [-T] source dest
cp [option]… sourcedirectory
cp [option]… -t directory source

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.

When copying from a symbolic link, cp normally follows the link 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.

When copying to a symbolic link, cp follows the link only when it refers to an existing regular file. However, when copying to a dangling symbolic link, cp refuses by default, and fails with a diagnostic, since the operation is inherently dangerous. This behavior is contrary to historical practice and to POSIX. Set POSIXLY_CORRECT to make cp attempt to create the target of a dangling destination symlink, in spite of the possible risk. Also, when an option like ‘--backup’ or ‘--link’ acts to rename or remove the destination before copying, cp renames or removes the symbolic link rather than the file it points to.

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 (see section 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 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 ‘-dpR’.

-b
--backup[=method]

See section 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 removes 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 removed unconditionally. Also see the description of ‘--remove-destination’.

This option is independent of the ‘--interactive’ or ‘-i’ option: neither cancels the effect of the other.

-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

When copying a file other than a directory, prompt whether to overwrite an existing destination file.

-l
--link

Make hard links instead of copies of non-directories.

-L
--dereference

Follow symbolic links when copying from them.

-P
--no-dereference

Copy symbolic links as symbolic links rather than copying the files that they point to. This option affects only symbolic links in the source; symbolic links in the destination are always followed if possible.

-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 file mode bits and access control lists.

ownership

Preserve the owner and group. On most modern systems, only users with appropriate privileges may change the owner of a file, and ordinary 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, when possible. In general, it is not possible to preserve these attributes when the affected file is a symbolic link. However, FreeBSD now provides the lutimes function, which makes it possible even for symbolic links. However, this implementation does not yet take advantage of that.

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 mode bits of the corresponding source file, minus the bits set in the umask and minus the set-user-ID and set-group-ID bits. See section 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

Deprecated: to be removed in 2008.
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. By default, do not follow symbolic links in the source; 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 zeros. 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 file system that does not support sparse files (for example, ‘efs’ file systems in SGI IRIX 5.3 and earlier), but the output file is on a type of file system 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. See section 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’. See section Backup options.

-t directory
--target-directory=directory

Specify the destination directory. See section Target directory.

-T
--no-target-directory

Do not treat the last operand specially when it is a directory or a symbolic link to a directory. See section Target directory.

-u
--update

Do not copy a non-directory that has an existing destination with the same or newer modification time. If time stamps are being preserved, the comparison is to the source time stamp truncated to the resolutions of the destination file system and of the system calls used to update time stamps; this avoids duplicate work if several ‘cp -pu’ commands are executed with the same source and destination.

-v
--verbose

Print the name of each file before copying it.

-x
--one-file-system

Skip subdirectories that are on different file systems 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.