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