12745 man page typos

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved
  45 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
  46 .\" Copyright 2013 Nexenta Systems, Inc. All rights reserved.
  47 .\"
  48 .TH CP 1 "Apr 15, 2013"
  49 .SH NAME
  50 cp \- copy files
  51 .SH SYNOPSIS
  52 .LP
  53 .nf
  54 \fB/usr/bin/cp\fR [\fB-afip@/\fR] \fIsource_file\fR \fItarget_file\fR
  55 .fi
  56 
  57 .LP
  58 .nf
  59 \fB/usr/bin/cp\fR [\fB-afip@/\fR] \fIsource_file\fR... \fItarget\fR
  60 .fi
  61 
  62 .LP
  63 .nf
  64 \fB/usr/bin/cp\fR [\fB-r\fR | \fB-R\fR [\fB-H\fR | \fB-L\fR | \fB-P\fR]] [\fB-afip@/\fR] \fIsource_dir\fR... \fItarget\fR
  65 .fi
  66 
  67 .LP
  68 .nf
  69 \fB/usr/bin/cp\fR [\fB-R\fR | \fB-R\fR [\fB-H\fR | \fB-L\fR | \fB-P\fR]] [\fB-afip@/\fR] \fIsource_dir\fR... \fItarget\fR
  70 .fi
  71 
  72 .LP
  73 .nf
  74 \fB/usr/xpg4/bin/cp\fR [\fB-afip@/\fR] \fIsource_file\fR \fItarget_file\fR
  75 .fi
  76 
  77 .LP
  78 .nf
  79 \fB/usr/xpg4/bin/cp\fR [\fB-afip@/\fR] \fIsource_file\fR... \fItarget\fR
  80 .fi
  81 
  82 .LP
  83 .nf
  84 \fB/usr/xpg4/bin/cp\fR [\fB-r\fR | \fB-R\fR [\fB-H\fR | \fB-L\fR | \fB-P\fR]] [\fB-afip@/\fR] \fIsource_dir\fR... \fItarget\fR
  85 .fi
  86 
  87 .LP
  88 .nf
  89 \fB/usr/xpg4/bin/cp\fR [\fB-R\fR | \fB-R\fR [\fB-H\fR | \fB-L\fR | \fB-P\fR]] [\fB-afip@/\fR] \fIsource_dir\fR... \fItarget\fR
  90 .fi
  91 
  92 .SH DESCRIPTION
  93 .sp
  94 .LP
  95 In the first synopsis form, neither \fIsource_file\fR nor \fItarget_file\fR are
  96 directory files, nor can they have the same name. The \fBcp\fR utility copies
  97 the contents of \fIsource_file\fR to the destination path named by
  98 \fItarget_file\fR. If \fItarget_file\fR exists, \fBcp\fR overwrites its
  99 contents, but the mode (and \fBACL\fR if applicable), owner, and group
 100 associated with it are not changed. The last modification time of
 101 \fItarget_file\fR and the last access time of \fIsource_file\fR are set to the
 102 time the copy was made. If \fItarget_file\fR does not exist, \fBcp\fR creates a
 103 new file named \fItarget_file\fR that has the same mode as \fIsource_file\fR
 104 except that the sticky bit is not set unless the user is super-user. In this
 105 case, the owner and group of \fItarget_file\fR are those of the user, unless
 106 the setgid bit is set on the directory containing the newly created file. If
 107 the directory's setgid bit is set, the newly created file has the group of the
 108 containing directory rather than of the creating user. If \fItarget_file\fR is
 109 a link to another file, \fBcp\fR overwrites the link destination with the
 110 contents of \fIsource_file\fR; the link(s) from \fItarget_file\fR remains.
 111 .sp
 112 .LP
 113 In the second synopsis form, one or more \fIsource_file\fRs are copied to the
 114 directory specified by \fItarget\fR. It is an error if any \fIsource_file\fR is
 115 a file of type directory, if \fItarget\fR either does not exist or is not a
 116 directory.
 117 .sp
 118 .LP
 119 In the third or fourth synopsis forms, one or more directories specified by
 120 \fIsource_dir\fR are copied to the directory specified by \fItarget\fR. Either
 121 the \fB-r\fR or \fB-R\fR must be specified. For each \fIsource_dir\fR, \fBcp\fR
 122 copies all files and subdirectories.
 123 .SH OPTIONS
 124 .sp
 125 .LP
 126 The following options are supported for both \fB/usr/bin/cp\fR and
 127 \fB/usr/xpg4/bin/cp\fR:
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fB-a\fR\fR
 132 .ad
 133 .RS 6n
 134 Archive mode. Same as -RpP.
 135 .RE
 136 
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fB-f\fR\fR
 141 .ad
 142 .RS 6n
 143 Unlink. If a file descriptor for a destination file cannot be obtained, this
 144 option attempts to unlink the destination file and proceed.
 145 .RE
 146 
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fB-H\fR\fR
 151 .ad
 152 .RS 6n
 153 Takes actions based on the type and contents of the file referenced by any
 154 symbolic link specified as a \fIsource_file\fR operand.
 155 .sp
 156 If the \fIsource_file\fR operand is a symbolic link, then \fBcp\fR copies the
 157 file referenced by the symbolic link for the \fIsource_file\fR operand. All
 158 other symbolic links encountered during traversal of a file hierarchy are
 159 preserved.
 160 .RE
 161 
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fB-i\fR\fR
 166 .ad
 167 .RS 6n
 168 Interactive. \fBcp\fR prompts for confirmation whenever the copy would
 169 overwrite an existing \fItarget\fR. An affirmative response means that the copy
 170 should proceed. Any other answer prevents \fBcp\fR from overwriting
 171 \fItarget\fR.
 172 .RE
 173 
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fB-L\fR\fR
 178 .ad
 179 .RS 6n
 180 Takes actions based on the type and contents of the file referenced by any
 181 symbolic link specified as a \fIsource_file\fR operand or any symbolic links
 182 encountered during traversal of a file hierarchy.
 183 .sp
 184 Copies files referenced by symbolic links. Symbolic links encountered during
 185 traversal of a file hierarchy are not preserved.
 186 .RE
 187 
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fB-p\fR\fR
 192 .ad
 193 .RS 6n
 194 Preserve. The \fBcp\fR utility duplicates not only the contents of
 195 \fIsource_file\fR, but also attempts to preserve its ACL, access and
 196 modification times, extended attributes, extended system attributes, file mode,
 197 and owner and group ids.
 198 .sp
 199 If \fBcp\fR is unable to preserve the access and modification times, extended
 200 attributes, or the file mode, \fBcp\fR does not consider it a failure. If
 201 \fBcp\fR is unable to preserve the owner and group id, the copy does not fail,
 202 but \fBcp\fR silently clears the \fBS_ISUID\fR and \fBS_ISGID\fR bits from the
 203 file mode of the target. The copy fails if \fBcp\fR is unable to clear these
 204 bits. If \fBcp\fR is unable to preserve the ACL or extended system attributes,
 205 the copy fails. If the copy fails, then a diagnostic message is written to
 206 \fBstderr\fR and (after processing any remaining operands) \fBcp\fR exits with
 207 a \fBnon-zero\fR exit status.
 208 .RE
 209 
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fB-P\fR\fR
 214 .ad
 215 .RS 6n
 216 Takes actions on any symbolic link specified as a \fIsource_file\fR operand or
 217 any symbolic link encountered during traversal of a file hierarchy.
 218 .sp
 219 Copies symbolic links. Symbolic links encountered during traversal of a file
 220 hierarchy are preserved.
 221 .RE
 222 
 223 .sp
 224 .ne 2
 225 .na
 226 \fB\fB-r\fR\fR
 227 .ad
 228 .RS 6n
 229 Recursive. \fBcp\fR copies the directory and all its files, including any
 230 subdirectories and their files to \fItarget\fR. Unless the \fB-H\fR, \fB-L\fR,
 231 or \fB-P\fR option is specified, the \fB-L\fR option is used as the default
 232 mode.
 233 .RE
 234 
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fB-R\fR\fR
 239 .ad
 240 .RS 6n
 241 Same as \fB-r\fR, except pipes are replicated, not read from.
 242 .RE
 243 
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fB-@\fR\fR
 248 .ad
 249 .RS 6n
 250 Preserves extended attributes. \fBcp\fR attempts to copy all of the source
 251 file's extended attributes along with the file data to the destination file.
 252 .RE
 253 
 254 .sp
 255 .ne 2
 256 .na
 257 \fB\fB-/\fR\fR
 258 .ad
 259 .RS 6n
 260 Preserves extended attributes and extended system attributes. Along with the
 261 file's data, the \fBcp\fR utility attempts to copy extended attributes and
 262 extended system attributes from each source file, and extended system
 263 attributes associated with extended attributes to the destination file. If
 264 \fBcp\fR is unable to copy extended attributes or extended system attributes,
 265 then a diagnostic message is written to \fBstderr\fR and (after processing any
 266 remaining operands) exits with a \fBnon-zero\fR exit status.
 267 .RE
 268 
 269 .sp
 270 .LP
 271 Specifying more than one of the mutually-exclusive options \fB-H\fR, \fB-L\fR,
 272 and \fB-P\fR is not considered an error. The last option specified determines
 273 the behavior of the utility.
 274 .SS "/usr/bin/cp"
 275 .sp
 276 .LP
 277 If the \fB-p\fR option is specified with either the \fB-@\fR option or the
 278 \fB-/\fR option, \fB/usr/bin/cp\fR behaves as follows
 279 .RS +4
 280 .TP
 281 .ie t \(bu
 282 .el o
 283 When both \fB-p\fR and \fB-@\fR are specified in any order, the copy fails if
 284 extended attributes cannot be copied.
 285 .RE
 286 .RS +4
 287 .TP
 288 .ie t \(bu
 289 .el o
 290 When both \fB-p\fR and \fB-/\fR are specified in any order, the copy fails if
 291 extended system attributes cannot be copied.
 292 .RE
 293 .SS "/usr/xpg4/bin/cp"
 294 .sp
 295 .LP
 296 If the \fB-p\fR option is specified with either the \fB-@\fR option or the
 297 \fB-/\fR option, /\fBusr/xpg4/bin/cp\fR behaves as follows:
 298 .RS +4
 299 .TP
 300 .ie t \(bu
 301 .el o
 302 When both \fB-p\fR and \fB-@\fR are specified, the last option specified
 303 determines whether the copy fails if extended attributes cannot be preserved.
 304 .RE
 305 .RS +4
 306 .TP
 307 .ie t \(bu
 308 .el o
 309 When both \fB-p\fR and \fB-/\fR are specified, the last option specified
 310 determines whether the copy fails if extended system attributes cannot be
 311 preserved.
 312 .RE
 313 .SH OPERANDS
 314 .sp
 315 .LP
 316 The following operands are supported:
 317 .sp
 318 .ne 2
 319 .na
 320 \fB\fIsource_file\fR\fR
 321 .ad
 322 .RS 15n
 323 A pathname of a regular file to be copied.
 324 .RE
 325 
 326 .sp
 327 .ne 2
 328 .na
 329 \fB\fIsource_dir\fR\fR
 330 .ad
 331 .RS 15n
 332 A pathname of a directory to be copied.
 333 .RE
 334 
 335 .sp
 336 .ne 2
 337 .na
 338 \fB\fItarget_file\fR\fR
 339 .ad
 340 .RS 15n
 341 A pathname of an existing or non-existing file, used for the output when a
 342 single file is copied.
 343 .RE
 344 
 345 .sp
 346 .ne 2
 347 .na
 348 \fB\fItarget\fR\fR
 349 .ad
 350 .RS 15n
 351 A pathname of a directory to contain the copied files.
 352 .RE
 353 
 354 .SH USAGE
 355 .sp
 356 .LP
 357 See \fBlargefile\fR(5) for the description of the behavior of \fBcp\fR when
 358 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
 359 .SH EXAMPLES
 360 .LP
 361 \fBExample 1 \fRCopying a File
 362 .sp
 363 .LP
 364 The following example copies a file:
 365 
 366 .sp
 367 .in +2
 368 .nf
 369 example% cp goodies goodies.old
 370 
 371 example% ls goodies*
 372 goodies goodies.old
 373 .fi
 374 .in -2
 375 .sp
 376 
 377 .LP
 378 \fBExample 2 \fRCopying a List of Files
 379 .sp
 380 .LP
 381 The following example copies a list of files to a destination directory:
 382 
 383 .sp
 384 .in +2
 385 .nf
 386 example% cp ~/src/* /tmp
 387 .fi
 388 .in -2
 389 .sp
 390 
 391 .LP
 392 \fBExample 3 \fRCopying a Directory
 393 .sp
 394 .LP
 395 The following example copies a directory, first to a new, and then to an
 396 existing destination directory
 397 
 398 .sp
 399 .in +2
 400 .nf
 401 example% ls ~/bkup
 402 /usr/example/fred/bkup not found
 403 
 404 example% cp \fB-r\fR ~/src ~/bkup
 405 
 406 example% ls \fB-R\fR ~/bkup
 407 x.c y.c z.sh
 408 
 409 example% cp \fB-r\fR ~/src ~/bkup
 410 
 411 example% ls \fB-R\fR ~/bkup
 412 src x.c y.c z.sh
 413 src:
 414 x.c y.c z.s
 415 .fi
 416 .in -2
 417 .sp
 418 
 419 .LP
 420 \fBExample 4 \fRCopying Extended File System Attributes
 421 .sp
 422 .LP
 423 The following example copies extended file system attributes:
 424 
 425 .sp
 426 .in +2
 427 .nf
 428 $ ls -/ c file1
 429 -rw-r--r--   1 foo   staff          0 Oct 29 20:04 file1
 430                 {AH-----m--}
 431 
 432 $ cp -/ file1 file2
 433 $ ls -/c file2
 434 -rw-r--r--   1 foo  staff          0 Oct 29 20:17 file2
 435                 {AH-----m--}
 436 .fi
 437 .in -2
 438 .sp
 439 
 440 .LP
 441 \fBExample 5 \fRFailing to Copy Extended System Attributes
 442 .sp
 443 .LP
 444 The following example fails to copy extended system attributes:
 445 
 446 .sp
 447 .in +2
 448 .nf
 449 $ ls -/c file1
 450 -rw-r--r--   1 foo    staff          0 Oct 29 20:04 file1
 451                 {AH-----m--}
 452 
 453 $ cp -/ file1 /tmp
 454 cp: Failed to copy extended system attributes from file1 to /tmp/file1
 455 
 456 
 457 $ ls -/c /tmp/file1
 458 -rw-r--r--   1 foo    staff          0 Oct 29 20:09 /tmp/file1
 459                 {}
 460 .fi
 461 .in -2
 462 .sp
 463 
 464 .SH ENVIRONMENT VARIABLES
 465 .sp
 466 .LP
 467 See \fBenviron\fR(5) for descriptions of the following environment variables
 468 that affect the execution of \fBcp\fR: \fBLANG\fR, \fBLC_ALL\fR,
 469 \fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 470 .sp
 471 .LP
 472 Affirmative responses are processed using the extended regular expression
 473 defined for the \fByesexpr\fR keyword in the \fBLC_MESSAGES\fR category of the
 474 user's locale. The locale specified in the \fBLC_COLLATE\fR category defines
 475 the behavior of ranges, equivalence classes, and multi-character collating
 476 elements used in the expression defined for \fByesexpr\fR. The locale specified
 477 in \fBLC_CTYPE\fR determines the locale for interpretation of sequences of
 478 bytes of text data a characters, the behavior of character classes used in the
 479 expression defined for the \fByesexpr\fR. See \fBlocale\fR(5).
 480 .SH EXIT STATUS
 481 .sp
 482 .LP
 483 The following exit values are returned:
 484 .sp
 485 .ne 2
 486 .na
 487 \fB\fB0\fR\fR
 488 .ad
 489 .RS 6n
 490 All files were copied successfully.
 491 .RE
 492 
 493 .sp
 494 .ne 2
 495 .na
 496 \fB\fB>0\fR\fR
 497 .ad
 498 .RS 6n
 499 An error occurred.
 500 .RE
 501 
 502 .SH ATTRIBUTES
 503 .sp
 504 .LP
 505 See \fBattributes\fR(5) for descriptions of the following attributes:
 506 .SS "/usr/bin/cp"
 507 .sp
 508 
 509 .sp
 510 .TS
 511 box;
 512 c | c
 513 l | l .
 514 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 515 _
 516 CSI     Enabled
 517 _
 518 Interface Stability     Committed
 519 .TE
 520 
 521 .SS "/usr/xpg4/bin/cp"
 522 .sp
 523 
 524 .sp
 525 .TS
 526 box;
 527 c | c
 528 l | l .
 529 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 530 _
 531 CSI     Enabled
 532 _
 533 Interface Stability     Committed
 534 .TE
 535 
 536 .SH SEE ALSO
 537 .sp
 538 .LP
 539 \fBchmod\fR(1), \fBchown\fR(1), \fBsetfacl\fR(1), \fButime\fR(2),
 540 \fBfgetattr\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBfsattr\fR(5),
 541 \fBlargefile\fR(5), \fBlocale\fR(5), \fBstandards\fR(5)
 542 .SH NOTES
 543 .sp
 544 .LP
 545 The permission modes of the source file are preserved in the copy.
 546 .sp
 547 .LP
 548 A \fB--\fR permits the user to mark the end of any command line options
 549 explicitly, thus allowing \fBcp\fR to recognize filename arguments that begin
 550 with a \fB-\fR.
--- EOF ---