man1/cp.1

   1 .\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998.
   2 .\"
   3 .\" Distributed under GPL.
   4 .\"
   5 .TH CP 1 2003-11 "GNU fileutils 4.1"
   6 .SH NAME
   7 cp \- copy files and directories
   8 .SH SYNOPSIS
   9 .BI "cp [" "options" "] " "file path"
  10 .br
  11 .BI "cp [" "options" "] " "file... directory"
  12 .sp
  13 POSIX options:
  14 .B "[\-fiprR] [\-\-]"
  15 .sp
  16 Additional POSIX 1003.1-2003 options:
  17 .B "[\-HLP]
  18 .sp
  19 GNU file-utils 4.0 options (shortest form):
  20 .br
  21 .B [\-abdfilprsuvxPR]
  22 .BI "[\-S " SUFFIX ]
  23 .B "[\-V {numbered,existing,simple}]"
  24 .BI [\-\-backup= CONTROL ]
  25 .BI [\-\-sparse= WHEN ]
  26 .B "[\-\-help] [\-\-version] [\-\-]"
  27 .sp
  28 Additional GNU file-utils 4.1 options (shortest form):
  29 .br
  30 .B [\-HLP]
  31 .B [\-\-copy\-contents]
  32 .B [\-\-no\-preserve]
  33 .BI [\-\-reply= HOW ]
  34 .B [\-\-remove\-destination]
  35 .B [\-\-strip\-trailing\-slashes]
  36 .BI [\-\-target\-directory= DIR ]
  37 .SH DESCRIPTION
  38 .B cp
  39 copies files (or, optionally, directories).
  40 You can either copy one file to a given destination,
  41 or copy arbitrarily many files to a destination directory.
  42 .PP
  43 If the last argument names an existing directory,
  44 .B cp
  45 copies each source
  46 .I file
  47 into that directory (retaining the same name).  Otherwise,
  48 if only two files are given, it copies the first onto the second.  It
  49 is an error if the last argument is not a directory and more than two
  50 non-option arguments are given.
  51 .PP
  52 (Thus, if /a is a directory, then `cp \-r /a /b' will copy /a to /b/a
  53 and /a/x to /b/a/x in case a directory /b existed already, but it will
  54 copy /a to /b and /a/x to /b/x if there was no /b beforehand,
  55 while it will fail in case there was an ordinary file /b.)
  56 .PP
  57 The modes of the files and directories created will be the same
  58 as those of the original files, ANDed by 0777, and modified by
  59 the user's umask (unless the \-p option was specified).
  60 (But during the recursive copy of directories, newly created
  61 directories will temporarily get their final mode ORed with
  62 S_IRWXU (0700), so as to allow the process to read, write
  63 and search the newly created directory.)
  64 .PP
  65 Nothing is done when copying a file to itself (except possibly
  66 producing an error message).
  67 When copying to a different existing file, it is opened
  68 using `open(path, O_WRONLY | O_TRUNC)'.
  69 When copying to a new file it is created
  70 using `open(path, O_WRONLY | O_CREAT, mode)'.
  71 If this fails, the file existed, and the \-f option was given,
  72 .B cp
  73 tries to delete (unlink) the existing file, and if this succeeds
  74 proceeds as for a new file.
  75
  76 .SH "POSIX OPTIONS"
  77 POSIX recognizes four options and a half:
  78 .TP
  79 .B \-f
  80 Remove existing destination files if required. (See above.)
  81 .TP
  82 .B \-i
  83 Prompt whether to overwrite existing regular destination files.
  84 (Write a question on stderr, and read the answer from stdin.
  85 Only copy upon an affirmative answer.)
  86 .TP
  87 .B \-p
  88 Preserve the original files' owner, group, permissions
  89 (including the setuid and setgid bits), time of last modification
  90 and time of last access.
  91 In case duplication of owner or group fails, the setuid and setgid
  92 bits are cleared.
  93 (Note that afterwards source and copy may well have different
  94 times of last access, since the copy operation is an access
  95 to the source file.)
  96 .TP
  97 .B \-R
  98 Copy directories recursively, and do the right thing when
  99 objects other than ordinary files or directories are encountered.
 100 (Thus, the copy of a FIFO or special file is a FIFO or special file.)
 101 .TP
 102 .B \-r
 103 Copy directories recursively, and do something unspecified
 104 with objects other than ordinary files or directories.
 105 (Thus, it is allowed, in fact encouraged, to have the \-r option
 106 a synonym for \-R. However, silly behaviour, like that of the
 107 GNU 4.0 version of
 108 .BR cp
 109 is not forbidden.)
 110 .TP
 111 .B "\-\-"
 112 Terminate option list.
 113 .SH "ADDITIONAL POSIX 2003 OPTIONS"
 114 POSIX 1003.1-2003 adds three options that specify how to handle
 115 symbolic links. When doing a non-recursive copy, symbolic links
 116 are followed. When doing a recursive copy using the \-r option,
 117 the results are implementation-defined. When doing a recursive
 118 copy using the \-R option:
 119 .TP
 120 .B \-H
 121 Follow the symbolic links given in the parameter list.
 122 Do not follow symbolic links encountered during the recursive copy,
 123 but just copy them as symbolic link.
 124 .TP
 125 .B \-L
 126 Follow all symbolic links, both those that occur in the parameter list
 127 and those encountered during the recursive copy.
 128 .TP
 129 .B \-P
 130 Do not follow any symbolic links, neither those that occur
 131 in the parameter list nor those encountered during the recursive copy.
 132 Just copy them as symbolic link.
 133 .LP
 134 There is no default - one should specify the desired behaviour.
 135 .SH "GNU DETAILS"
 136 .PP
 137 Generally, files are written just as they are read.  For exceptions,
 138 see the
 139 .B "\-\-sparse"
 140 option below.
 141 .PP
 142 By default, `cp' does not copy directories (see
 143 .B "\-r"
 144 below).
 145 .PP
 146 .B cp
 147 generally refuses to copy a file onto itself, with the following
 148 exception: if
 149 .B "\-\-force \-\-backup"
 150 is specified with
 151 .I source
 152 and
 153 .I dest
 154 identical, and referring to a regular file,
 155 .B cp
 156 will make a backup file, either regular or numbered, as specified in
 157 the usual ways.  This is useful when you simply want to make a backup
 158 of an existing file before changing it.
 159 .PP
 160 By default, symbolic links are not followed.
 161 .SH "GNU OPTIONS"
 162 .TP
 163 .B "\-a, \-\-archive"
 164 Preserve as much as possible of the structure and attributes of the
 165 original files in the copy (but do not preserve directory structure).
 166 Equivalent to
 167 .BR "\-dpPR" .
 168 .TP
 169 .B "\-b"
 170 See the discussion of backups below.
 171 .TP
 172 .BR "\-\-copy\-contents" " (since file-utils 4.1)"
 173 Do the silly things file-utils 4.0 did,
 174 trying to copy the contents of device files and FIFOs during
 175 a recursive copy. Never use this option. With it, `cp' may well hang
 176 indefinitely reading a FIFO or /dev/tty, or fill the destination disk
 177 copying /dev/zero.
 178 .TP
 179 .B "\-d"
 180 Copy symbolic links as symbolic links rather than copying the
 181 files that they point to, and preserve hard links between source
 182 files in the copies.
 183
 184 With file-utils 4.0 the long option \-\-no\-dereference was a
 185 synonym for \-d, with file-utils 4.1 it is a synonym for \-P,
 186 while \-d is equivalent to \-\-no\-dereference \-\-preserve=links.
 187 .TP
 188 .B "\-f, \-\-force"
 189 Remove existing destination files in case an open for writing fails,
 190 and never prompt before doing so.
 191 (Thus since file-utils 4.1. With file-utils 4.0 this option was
 192 equivalent to the new \-\-remove\-destination.)
 193 .TP
 194 .BR "\-H" " (since file-utils 4.1)"
 195 See POSIX description above.
 196 .TP
 197 .B "\-i, \-\-interactive"
 198 Prompt whether to overwrite existing regular destination files.
 199 .TP
 200 .B "\-l, \-\-link"
 201 Make hard links instead of copies of non-directories.
 202 .TP
 203 .BR "\-L, \-\-dereference" " (since file-utils 4.1)"
 204 See POSIX description above.
 205 .TP
 206 .BR "\-\-no\-preserve=\fIATTRIBUTES\fP" " (since file-utils 4.1)"
 207 Do not preserve the specified attributes.
 208 See the \-\-preserve option below.
 209 .TP
 210 .B "\-p, \-\-preserve"
 211 Preserve the original files' owner, group, permissions, and timestamps.
 212 .TP
 213 .BR "\-\-preserve=\fIATTRIBUTES\fP" " (since file-utils 4.1)"
 214 Here ATTRIBUTES can be one of "mode" (permissions), "ownership" (owner
 215 and group), "timestamps", "links", "all" (all of the foregoing).
 216 .TP
 217 .BR "\-P, \-\-no\-dereference" " (since file-utils 4.1)"
 218 See POSIX description above.
 219 This replaces the file-utils 4.0 meaning of the \-P option, that
 220 was a synonym for \-\-parents. See also \-d above.
 221 .TP
 222 .BR "\-\-parents" " (in file-utils 4.0 also \-P)"
 223 Form the name of each destination file by appending to the target
 224 directory a slash and the specified name of the source file.  The
 225 last argument given to
 226 .B cp
 227 must be the name of an existing directory.  For example, the command:
 228 .br
 229 .nf
 230     cp \-\-parents a/b/c existing_dir
 231 .br
 232 .fi
 233 copies the file `a/b/c' to `existing_dir/a/b/c', creating any
 234 missing intermediate directories.
 235 .TP
 236 .B "\-r"
 237 In file-utils 4.1: synonym of \-R.
 238 In file-utils 4.0:
 239 Copy directories recursively, copying any non-directories and
 240 non-symbolic links (that is, FIFOs and special files) as if they
 241 were regular files. This silly behaviour is obtained in file-utils 4.1
 242 if the \-\-copy\-contents option is given.
 243 .TP
 244 .B "\-R, \-\-recursive"
 245 Copy directories recursively, preserving non-directories.
 246 .TP
 247 .BR "\-\-reply=\fIHOW\fP" " (since file-utils 4.1)"
 248 Here HOW can be one of "yes", "no", "query", specifying that
 249 to all questions the answer is yes, or is no, or must be obtained
 250 by querying the user, respectively.
 251 .TP
 252 .BR "\-\-remove\-destination" " (since file-utils 4.1)"
 253 Remove each existing destination file before copying.
 254 With file-utils 4.0 this option was implied by \-f.
 255 .TP
 256 .BI "\-\-sparse=" "WHEN"
 257 A `sparse file' contains `holes' - sequences of zero bytes that
 258 do not occupy any physical disk blocks; the `read' system call
 259 reads these as zeroes.  This can both save considerable disk space
 260 and increase speed, since many binary files contain lots of
 261 consecutive zero bytes.  By default,
 262 .B cp
 263 detects holes in input source files via a crude heuristic
 264 and makes the corresponding output file sparse as well.
 265 .RS
 266 .PP
 267 The
 268 .I WHEN
 269 value can be one of the following:
 270 .TP
 271 .B auto
 272 The default behavior: the output file is sparse if the input
 273 file is sparse.
 274 .TP
 275 .B always
 276 Always make the output file sparse.  This is useful when the
 277 input file resides on a filesystem that does not support
 278 sparse files, but the output file is on a filesystem that does.
 279 .TP
 280 .B never
 281 Never make the output file sparse.  If you find an application for
 282 this option, let us know.
 283 .RE
 284 .TP
 285 .BR "\-\-strip\-trailing\-slashes" " (since file-utils 4.1)"
 286 Remove any trailing slashes from each source argument.
 287 (This can change the interpretation in case of a symbolic link
 288 to a directory.)
 289 .TP
 290 .B "\-s, \-\-symbolic\-link"
 291 Make symbolic links instead of copies of non-directories.  All
 292 source file names must be absolute (starting with `/') unless the
 293 destination files are in the current directory.  This option merely
 294 results in an error message on systems that do not support
 295 symbolic links.
 296 .TP
 297 .B "\-S"
 298 Backup suffix, see below.
 299 .TP
 300 .BR "\-\-target\-directory=\fIDIR\fP" " (since file-utils 4.1)"
 301 Specify the destination directory. Meant for use with
 302 .BR xargs (1),
 303 as in "ls | xargs cp --target-directory=../d".
 304 .TP
 305 .B "\-u, \-\-update"
 306 Do not copy a nondirectory that has an existing destination with
 307 the same or newer modification time.
 308 .TP
 309 .B "\-v, \-\-verbose"
 310 Print the name of each file before copying it.
 311 .TP
 312 .B "\-x, \-\-one\-file\-system"
 313 Skip subdirectories that are on different filesystems from the one
 314 that the copy started on.
 315 .SH "GNU BACKUP OPTIONS"
 316 The GNU versions of programs like
 317 .BR cp ,
 318 .BR mv ,
 319 .BR ln ,
 320 .B install
 321 and
 322 .B patch
 323 will make a backup of files about to be overwritten, changed or destroyed
 324 if that is desired. That backup files are desired is indicated by
 325 the \-b option. How they should be named is specified by the \-V option.
 326 In case the name of the backup file is given by the name of the file
 327 extended by a suffix, this suffix is specified by the \-S option.
 328 .TP
 329 .B "\-b, \-\-backup"
 330 Make backups of files that are about to be overwritten or removed.
 331 .TP
 332 .BI \-\-backup= CONTROL
 333 (Since fileutils-4.1.)
 334 .TP
 335 .BI "\-S " SUFFIX ", \-\-suffix=" SUFFIX
 336 Append
 337 .I SUFFIX
 338 to each backup file made.
 339 If this option is not specified, the value of the
 340 .B SIMPLE_BACKUP_SUFFIX
 341 environment variable is used.  And if
 342 .B SIMPLE_BACKUP_SUFFIX
 343 is not set, the default is `~'.
 344 .TP
 345 .BI "\-V " METHOD ", \-\-version\-control=" METHOD
 346 .RS
 347 Specify how backup files are named. The
 348 .I METHOD
 349 argument can be `numbered' (or `t'), `existing' (or `nil'), or `never' (or
 350 `simple').
 351 If this option is not specified, the value of the
 352 .B VERSION_CONTROL
 353 environment variable is used.  And if
 354 .B VERSION_CONTROL
 355 is not set, the default backup type is `existing'.
 356 .PP
 357 This option corresponds to the Emacs variable `version-control'.
 358 The valid
 359 .IR METHOD s
 360 are (unique abbreviations are accepted):
 361 .TP
 362 .BR t ", " numbered
 363 Always make numbered backups.
 364 .TP
 365 .BR nil ", " existing
 366 Make numbered backups of files that already have them, simple
 367 backups of the others.
 368 .TP
 369 .BR never ", " simple
 370 Always make simple backups.
 371 .RE
 372 .SH "GNU STANDARD OPTIONS"
 373 .TP
 374 .B "\-\-help"
 375 Print a usage message on standard output and exit successfully.
 376 .TP
 377 .B "\-\-version"
 378 Print version information on standard output, then exit successfully.
 379 .TP
 380 .B "\-\-"
 381 Terminate option list.
 382 .SH ENVIRONMENT
 383 The variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE and LC_MESSAGES have the
 384 usual meaning. For the GNU version, the variables SIMPLE_BACKUP_SUFFIX
 385 and VERSION_CONTROL control backup file naming, as described above.
 386 .SH "CONFORMING TO"
 387 POSIX 1003.2
 388 .SH NOTES
 389 This page describes
 390 .B cp
 391 as found in the fileutils-4.1 package;
 392 other versions may differ slightly.