coreutils: cp invocation
1
1 11.1 ‘cp’: Copy files and directories
1 =====================================
1
1 ‘cp’ copies files (or, optionally, directories). The copy is completely
1 independent of the original. You can either copy one file to another,
1 or copy arbitrarily many files to a destination directory. Synopses:
1
1 cp [OPTION]... [-T] SOURCE DEST
1 cp [OPTION]... SOURCE... DIRECTORY
1 cp [OPTION]... -t DIRECTORY SOURCE...
1
1 • If two file names are given, ‘cp’ copies the first file to the
1 second.
1
1 • If the ‘--target-directory’ (‘-t’) option is given, or failing that
1 if the last file is a directory and the ‘--no-target-directory’
1 (‘-T’) option is not given, ‘cp’ copies each SOURCE file to the
1 specified directory, using the SOURCEs’ names.
1
1 Generally, files are written just as they are read. For exceptions,
1 see the ‘--sparse’ option below.
1
1 By default, ‘cp’ does not copy directories. However, the ‘-R’, ‘-a’,
1 and ‘-r’ options cause ‘cp’ to copy recursively by descending into
1 source directories and copying files to corresponding destination
1 directories.
1
1 When copying from a symbolic link, ‘cp’ normally follows the link
1 only when not copying recursively or when ‘--link’ (‘-l’) is used. This
1 default can be overridden with the ‘--archive’ (‘-a’), ‘-d’,
1 ‘--dereference’ (‘-L’), ‘--no-dereference’ (‘-P’), and ‘-H’ options. If
1 more than one of these options is specified, the last one silently
1 overrides the others.
1
1 When copying to a symbolic link, ‘cp’ follows the link only when it
1 refers to an existing regular file. However, when copying to a dangling
1 symbolic link, ‘cp’ refuses by default, and fails with a diagnostic,
1 since the operation is inherently dangerous. This behavior is contrary
1 to historical practice and to POSIX. Set ‘POSIXLY_CORRECT’ to make ‘cp’
1 attempt to create the target of a dangling destination symlink, in spite
1 of the possible risk. Also, when an option like ‘--backup’ or ‘--link’
1 acts to rename or remove the destination before copying, ‘cp’ renames or
1 removes the symbolic link rather than the file it points to.
1
1 By default, ‘cp’ copies the contents of special files only when not
1 copying recursively. This default can be overridden with the
1 ‘--copy-contents’ option.
1
1 ‘cp’ generally refuses to copy a file onto itself, with the following
1 exception: if ‘--force --backup’ is specified with SOURCE and DEST
1 identical, and referring to a regular file, ‘cp’ will make a backup
11 file, either regular or numbered, as specified in the usual ways (⇒
Backup options). This is useful when you simply want to make a backup
1 of an existing file before changing it.
1
11 The program accepts the following options. Also see ⇒Common
options.
1
1 ‘-a’
1 ‘--archive’
1 Preserve as much as possible of the structure and attributes of the
1 original files in the copy (but do not attempt to preserve internal
1 directory structure; i.e., ‘ls -U’ may list the entries in a copied
1 directory in a different order). Try to preserve SELinux security
1 context and extended attributes (xattr), but ignore any failure to
1 do that and print no corresponding diagnostic. Equivalent to ‘-dR
1 --preserve=all’ with the reduced diagnostics.
1
1 ‘--attributes-only’
1 Copy only the specified attributes of the source file to the
1 destination. If the destination already exists, do not alter its
1 contents. See the ‘--preserve’ option for controlling which
1 attributes to copy.
1
1 ‘-b’
1 ‘--backup[=METHOD]’
1 ⇒Backup options. Make a backup of each file that would
1 otherwise be overwritten or removed. As a special case, ‘cp’ makes
1 a backup of SOURCE when the force and backup options are given and
1 SOURCE and DEST are the same name for an existing, regular file.
1 One useful application of this combination of options is this tiny
1 Bourne shell script:
1
1 #!/bin/sh
1 # Usage: backup FILE...
1 # Create a GNU-style backup of each listed FILE.
1 fail=0
1 for i; do
1 cp --backup --force --preserve=all -- "$i" "$i" || fail=1
1 done
1 exit $fail
1
1 ‘-c’
1 Preserve SELinux security context of the original files if
1 possible. Some file systems don’t support storing of SELinux
1 security context.
1
1 ‘--copy-contents’
1 If copying recursively, copy the contents of any special files
1 (e.g., FIFOs and device files) as if they were regular files. This
1 means trying to read the data in each source file and writing it to
1 the destination. It is usually a mistake to use this option, as it
1 normally has undesirable effects on special files like FIFOs and
1 the ones typically found in the ‘/dev’ directory. In most cases,
1 ‘cp -R --copy-contents’ will hang indefinitely trying to read from
1 FIFOs and special files like ‘/dev/console’, and it will fill up
1 your destination disk if you use it to copy ‘/dev/zero’. This
1 option has no effect unless copying recursively, and it does not
1 affect the copying of symbolic links.
1
1 ‘-d’
1 Copy symbolic links as symbolic links rather than copying the files
1 that they point to, and preserve hard links between source files in
1 the copies. Equivalent to ‘--no-dereference --preserve=links’.
1
1 ‘-f’
1 ‘--force’
1 When copying without this option and an existing destination file
1 cannot be opened for writing, the copy fails. However, with
1 ‘--force’, when a destination file cannot be opened, ‘cp’ then
1 tries to recreate the file by first removing it. Note ‘--force’
1 alone will not remove dangling symlinks. When this option is
1 combined with ‘--link’ (‘-l’) or ‘--symbolic-link’ (‘-s’), the
1 destination link is replaced, and unless ‘--backup’ (‘-b’) is also
1 given there is no brief moment when the destination does not exist.
1 Also see the description of ‘--remove-destination’.
1
1 This option is independent of the ‘--interactive’ or ‘-i’ option:
1 neither cancels the effect of the other.
1
1 This option is ignored when the ‘--no-clobber’ or ‘-n’ option is
1 also used.
1
1 ‘-H’
1 If a command line argument specifies a symbolic link, then copy the
1 file it points to rather than the symbolic link itself. However,
1 copy (preserving its nature) any symbolic link that is encountered
1 via recursive traversal.
1
1 ‘-i’
1 ‘--interactive’
1 When copying a file other than a directory, prompt whether to
1 overwrite an existing destination file. The ‘-i’ option overrides
1 a previous ‘-n’ option.
1
1 ‘-l’
1 ‘--link’
1 Make hard links instead of copies of non-directories.
1
1 ‘-L’
1 ‘--dereference’
1 Follow symbolic links when copying from them. With this option,
1 ‘cp’ cannot create a symbolic link. For example, a symlink (to
1 regular file) in the source tree will be copied to a regular file
1 in the destination tree.
1
1 ‘-n’
1 ‘--no-clobber’
1 Do not overwrite an existing file; silently do nothing instead.
1 This option overrides a previous ‘-i’ option. This option is
1 mutually exclusive with ‘-b’ or ‘--backup’ option.
1
1 ‘-P’
1 ‘--no-dereference’
1 Copy symbolic links as symbolic links rather than copying the files
1 that they point to. This option affects only symbolic links in the
1 source; symbolic links in the destination are always followed if
1 possible.
1
1 ‘-p’
1 ‘--preserve[=ATTRIBUTE_LIST]’
1 Preserve the specified attributes of the original files. If
1 specified, the ATTRIBUTE_LIST must be a comma-separated list of one
1 or more of the following strings:
1
1 ‘mode’
1 Preserve the file mode bits and access control lists.
1 ‘ownership’
1 Preserve the owner and group. On most modern systems, only
1 users with appropriate privileges may change the owner of a
1 file, and ordinary users may preserve the group ownership of a
1 file only if they happen to be a member of the desired group.
1 ‘timestamps’
1 Preserve the times of last access and last modification, when
1 possible. On older systems, it is not possible to preserve
1 these attributes when the affected file is a symbolic link.
1 However, many systems now provide the ‘utimensat’ function,
1 which makes it possible even for symbolic links.
1 ‘links’
1 Preserve in the destination files any links between
1 corresponding source files. Note that with ‘-L’ or ‘-H’, this
1 option can convert symbolic links to hard links. For example,
1 $ mkdir c; : > a; ln -s a b; cp -aH a b c; ls -i1 c
1 74161745 a
1 74161745 b
1 Note the inputs: ‘b’ is a symlink to regular file ‘a’, yet the
1 files in destination directory, ‘c/’, are hard-linked. Since
1 ‘-a’ implies ‘--no-dereference’ it would copy the symlink, but
1 the later ‘-H’ tells ‘cp’ to dereference the command line
1 arguments where it then sees two files with the same inode
1 number. Then the ‘--preserve=links’ option also implied by
1 ‘-a’ will preserve the perceived hard link.
1
1 Here is a similar example that exercises ‘cp’’s ‘-L’ option:
1 $ mkdir b c; (cd b; : > a; ln -s a b); cp -aL b c; ls -i1 c/b
1 74163295 a
1 74163295 b
1
1 ‘context’
1 Preserve SELinux security context of the file, or fail with
1 full diagnostics.
1 ‘xattr’
1 Preserve extended attributes of the file, or fail with full
1 diagnostics. If ‘cp’ is built without xattr support, ignore
1 this option. If SELinux context, ACLs or Capabilities are
1 implemented using xattrs, they are preserved implicitly by
1 this option as well, i.e., even without specifying
1 ‘--preserve=mode’ or ‘--preserve=context’.
1 ‘all’
1 Preserve all file attributes. Equivalent to specifying all of
1 the above, but with the difference that failure to preserve
1 SELinux security context or extended attributes does not
1 change ‘cp’’s exit status. In contrast to ‘-a’, all but
1 ‘Operation not supported’ warnings are output.
1
1 Using ‘--preserve’ with no ATTRIBUTE_LIST is equivalent to
1 ‘--preserve=mode,ownership,timestamps’.
1
1 In the absence of this option, the permissions of existing
1 destination files are unchanged. Each new file is created with the
1 mode of the corresponding source file minus the set-user-ID,
1 set-group-ID, and sticky bits as the create mode; the operating
1 system then applies either the umask or a default ACL, possibly
11 resulting in a more restrictive file mode. ⇒File
permissions.
1
1 ‘--no-preserve=ATTRIBUTE_LIST’
1 Do not preserve the specified attributes. The ATTRIBUTE_LIST has
1 the same form as for ‘--preserve’.
1
1 ‘--parents’
1 Form the name of each destination file by appending to the target
1 directory a slash and the specified name of the source file. The
1 last argument given to ‘cp’ must be the name of an existing
1 directory. For example, the command:
1
1 cp --parents a/b/c existing_dir
1
1 copies the file ‘a/b/c’ to ‘existing_dir/a/b/c’, creating any
1 missing intermediate directories.
1
1 ‘-R’
1 ‘-r’
1 ‘--recursive’
1 Copy directories recursively. By default, do not follow symbolic
1 links in the source unless used together with the ‘--link’ (‘-l’)
1 option; see the ‘--archive’ (‘-a’), ‘-d’, ‘--dereference’ (‘-L’),
1 ‘--no-dereference’ (‘-P’), and ‘-H’ options. Special files are
1 copied by creating a destination file of the same type as the
1 source; see the ‘--copy-contents’ option. It is not portable to
1 use ‘-r’ to copy symbolic links or special files. On some non-GNU
1 systems, ‘-r’ implies the equivalent of ‘-L’ and ‘--copy-contents’
1 for historical reasons. Also, it is not portable to use ‘-R’ to
1 copy symbolic links unless you also specify ‘-P’, as POSIX allows
1 implementations that dereference symbolic links by default.
1
1 ‘--reflink[=WHEN]’
1 Perform a lightweight, copy-on-write (COW) copy, if supported by
1 the file system. Once it has succeeded, beware that the source and
1 destination files share the same disk data blocks as long as they
1 remain unmodified. Thus, if a disk I/O error affects data blocks
1 of one of the files, the other suffers the same fate.
1
1 The WHEN value can be one of the following:
1
1 ‘always’
1 The default behavior: if the copy-on-write operation is not
1 supported then report the failure for each file and exit with
1 a failure status.
1
1 ‘auto’
1 If the copy-on-write operation is not supported then fall back
1 to the standard copy behavior.
1
1 ‘never’
1 Disable copy-on-write operation and use the standard copy
1 behavior.
1
1 This option is overridden by the ‘--link’, ‘--symbolic-link’ and
1 ‘--attributes-only’ options, thus allowing it to be used to
1 configure the default data copying behavior for ‘cp’. For example,
1 with the following alias, ‘cp’ will use the minimum amount of space
1 supported by the file system.
1
1 alias cp='cp --reflink=auto --sparse=always'
1
1 ‘--remove-destination’
1 Remove each existing destination file before attempting to open it
1 (contrast with ‘-f’ above).
1
1 ‘--sparse=WHEN’
1 A “sparse file” contains “holes”—a sequence of zero bytes that does
1 not occupy any physical disk blocks; the ‘read’ system call reads
1 these as zeros. This can both save considerable disk space and
1 increase speed, since many binary files contain lots of consecutive
1 zero bytes. By default, ‘cp’ detects holes in input source files
1 via a crude heuristic and makes the corresponding output file
1 sparse as well. Only regular files may be sparse.
1
1 The WHEN value can be one of the following:
1
1 ‘auto’
1 The default behavior: if the input file is sparse, attempt to
1 make the output file sparse, too. However, if an output file
1 exists but refers to a non-regular file, then do not attempt
1 to make it sparse.
1
1 ‘always’
1 For each sufficiently long sequence of zero bytes in the input
1 file, attempt to create a corresponding hole in the output
1 file, even if the input file does not appear to be sparse.
1 This is useful when the input file resides on a file system
1 that does not support sparse files (for example, ‘efs’ file
1 systems in SGI IRIX 5.3 and earlier), but the output file is
1 on a type of file system that does support them. Holes may be
1 created only in regular files, so if the destination file is
1 of some other type, ‘cp’ does not even try to make it sparse.
1
1 ‘never’
1 Never make the output file sparse. This is useful in creating
1 a file for use with the ‘mkswap’ command, since such a file
1 must not have any holes.
1
1 ‘--strip-trailing-slashes’
11 Remove any trailing slashes from each SOURCE argument. ⇒
Trailing slashes.
1
1 ‘-s’
1 ‘--symbolic-link’
1 Make symbolic links instead of copies of non-directories. All
1 source file names must be absolute (starting with ‘/’) unless the
1 destination files are in the current directory. This option merely
1 results in an error message on systems that do not support symbolic
1 links.
1
1 ‘-S SUFFIX’
1 ‘--suffix=SUFFIX’
11 Append SUFFIX to each backup file made with ‘-b’. ⇒Backup
options.
1
1 ‘-t DIRECTORY’
1 ‘--target-directory=DIRECTORY’
1 Specify the destination DIRECTORY. ⇒Target directory.
1
1 ‘-T’
1 ‘--no-target-directory’
1 Do not treat the last operand specially when it is a directory or a
1 symbolic link to a directory. ⇒Target directory.
1
1 ‘-u’
1 ‘--update’
1 Do not copy a non-directory that has an existing destination with
1 the same or newer modification timestamp. If timestamps are being
1 preserved, the comparison is to the source timestamp truncated to
1 the resolutions of the destination file system and of the system
1 calls used to update timestamps; this avoids duplicate work if
1 several ‘cp -pu’ commands are executed with the same source and
1 destination. This option is ignored if the ‘-n’ or ‘--no-clobber’
1 option is also specified. Also, if ‘--preserve=links’ is also
1 specified (like with ‘cp -au’ for example), that will take
1 precedence; consequently, depending on the order that files are
1 processed from the source, newer files in the destination may be
1 replaced, to mirror hard links in the source.
1
1 ‘-v’
1 ‘--verbose’
1 Print the name of each file before copying it.
1
1 ‘-x’
1 ‘--one-file-system’
1 Skip subdirectories that are on different file systems from the one
1 that the copy started on. However, mount point directories _are_
1 copied.
1
1 ‘-Z’
1 ‘--context[=CONTEXT]’
1 Without a specified CONTEXT, adjust the SELinux security context
1 according to the system default type for destination files,
1 similarly to the ‘restorecon’ command. The long form of this
1 option with a specific context specified, will set the context for
1 newly created files only. With a specified context, if both
1 SELinux and SMACK are disabled, a warning is issued. This option
1 is mutually exclusive with the ‘--preserve=context’ option, and
1 overrides the ‘--preserve=all’ and ‘-a’ options.
1
1 An exit status of zero indicates success, and a nonzero value
1 indicates failure.
1