CP(1)                                                       CP(1)



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  argument  is  not a directory and more than two non-
       option arguments are given.

       (Thus, if /a is a directory, then `cp -r /a /b' will  copy
       /a  to  /b/a  and  /a/x  to  /b/a/x in case a directory /b
       existed already, but it will copy /a to  /b  and  /a/x  to
       /b/x  if there was no /b beforehand, while it will fail in
       case there was an ordinary file /b.)

       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 directo-
       ries, 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 direc-
       tory.)

       Nothing is done when copying a file to itself (except pos-
       sibly 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



GNU fileutils 4.0         November 1998                         1





CP(1)                                                       CP(1)


              above.)

       -i     Prompt whether to overwrite existing regular desti-
              nation 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,  permis-
              sions  (including the setuid and setgid bits), time
              of last modification and time of last  access.   In
              case  duplication  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
              unspecified  with objects other than ordinary files
              or directories.  (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.)

       --     Terminate option list.


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  num-
       bered,  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
              copying  the files that they point to, and preserve



GNU fileutils 4.0         November 1998                         2





CP(1)                                                       CP(1)


              hard links between source files in the copies.

       -f, --force
              Remove existing destination files, and never prompt
              before doing so.

       -i, --interactive
              Prompt whether to overwrite existing regular desti-
              nation files.

       -l, --link
              Make hard links instead of copies  of  non-directo-
              ries.

       -p, --preserve
              Preserve  the original files' owner, group, permis-
              sions, 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',
              creating 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  read-
              ing  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-direc-
              tories (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.



GNU fileutils 4.0         November 1998                         3





CP(1)                                                       CP(1)


              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
                     useful when the  input  file  resides  on  a
                     filesystem  that  does  not  support  sparse
                     files, but the output file is on a  filesys-
                     tem 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-direc-
              tories.  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.

       -u, --update
              Do not copy a nondirectory  that  has  an  existing
              destination  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  filesys-
              tems 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  over-
              written or removed.

       -S SUFFIX, --suffix=SUFFIX
              Append  SUFFIX  to  each backup file made.  If this
              option is not specified,  the  value  of  the  SIM-
              PLE_BACKUP_SUFFIX  environment  variable  is  used.
              And if SIMPLE_BACKUP_SUFFIX is not set, the default



GNU fileutils 4.0         November 1998                         4





CP(1)                                                       CP(1)


              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_CON-
              TROL is not set, the default backup type is `exist-
              ing'.

              This option corresponds to the Emacs variable `ver-
              sion-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
              successfully.

       --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-4.0 pack-
       age; other versions may differ slightly.  Mail corrections
       and  additions  to aeb@cwi.nl.  Report bugs in the program
       to fileutils-bugs@gnu.ai.mit.edu.








GNU fileutils 4.0         November 1998                         5