copyfile.3

   1 .\"
   2 .\" Copyright (c) 2002 Apple Computer, Inc.  All rights reserved.
   3 .\"
   4 .Dd February 27, 2017
   5 .Dt COPYFILE 3
   6 .Os
   7 .Sh NAME
   8 .Nm copyfile , fcopyfile ,
   9 .Nm copyfile_state_alloc , copyfile_state_free ,
  10 .Nm copyfile_state_get , copyfile_state_set
  11 .Nd copy a file
  12 .Sh LIBRARY
  13 .Lb libc
  14 .Sh SYNOPSIS
  15 .In copyfile.h
  16 .Ft int
  17 .Fn copyfile "const char *from" "const char *to" "copyfile_state_t state" "copyfile_flags_t flags"
  18 .Ft int
  19 .Fn fcopyfile "int from" "int to" "copyfile_state_t state" "copyfile_flags_t flags"
  20 .Ft copyfile_state_t
  21 .Fn copyfile_state_alloc "void"
  22 .Ft int
  23 .Fn copyfile_state_free "copyfile_state_t state"
  24 .Ft int
  25 .Fn copyfile_state_get "copyfile_state_t state" "uint32_t flag" "void * dst"
  26 .Ft int
  27 .Fn copyfile_state_set "copyfile_state_t state" "uint32_t flag" "const void * src"
  28 .Ft typedef int
  29 .Fn (*copyfile_callback_t) "int what" "int stage" "copyfile_state_t state" "const char * src" "const char * dst" "void * ctx"
  30 .Sh DESCRIPTION
  31 These functions are used to copy a file's data and/or metadata.  (Metadata
  32 consists of permissions, extended attributes, access control lists, and so
  33 forth.)
  34 .Pp
  35 The
  36 .Fn copyfile_state_alloc
  37 function initializes a
  38 .Vt copyfile_state_t
  39 object (which is an opaque data type).
  40 This object can be passed to
  41 .Fn copyfile
  42 and
  43 .Fn fcopyfile ;
  44 .Fn copyfile_state_get
  45 and
  46 .Fn copyfile_state_set
  47 can be used to manipulate the state (see below).
  48 The
  49 .Fn copyfile_state_free
  50 function is used to deallocate the object and its contents.
  51 .Pp
  52 The
  53 .Fn copyfile
  54 function can copy the named
  55 .Va from
  56 file to the named
  57 .Va to
  58 file; the
  59 .Fn fcopyfile
  60 function does the same, but using the file descriptors of already-opened
  61 files.
  62 If the
  63 .Va state
  64 parameter is the return value from
  65 .Fn copyfile_state_alloc ,
  66 then
  67 .Fn copyfile
  68 and
  69 .Fn fcopyfile
  70 will use the information from the state object; if it is
  71 .Dv NULL ,
  72 then both functions will work normally, but less control will be available to the caller.
  73 The
  74 .Va flags
  75 parameter controls which contents are copied:
  76 .Bl -tag -width COPYFILE_XATTR
  77 .It Dv COPYFILE_ACL
  78 Copy the source file's access control lists.
  79 .It Dv COPYFILE_STAT
  80 Copy the source file's POSIX information (mode, modification time, etc.).
  81 .It Dv COPYFILE_XATTR
  82 Copy the source file's extended attributes.
  83 .It Dv COPYFILE_DATA
  84 Copy the source file's data.
  85 .El
  86 .Pp
  87 These values may be or'd together; several convenience macros are provided:
  88 .Bl -tag -width COPYFILE_SECURITY
  89 .It Dv COPYFILE_SECURITY
  90 Copy the source file's POSIX and ACL information; equivalent to
  91 .Dv (COPYFILE_STAT|COPYFILE_ACL) .
  92 .It Dv COPYFILE_METADATA
  93 Copy the metadata; equivalent to
  94 .Dv (COPYFILE_SECURITY|COPYFILE_XATTR) .
  95 .It Dv COPYFILE_ALL
  96 Copy the entire file; equivalent to
  97 .Dv (COPYFILE_METADATA|COPYFILE_DATA) .
  98 .El
  99 .Pp
 100 The
 101 .Fn copyfile
 102 and
 103 .Fn fcopyfile
 104 functions can also have their behavior modified by the following flags:
 105 .Bl -tag -width COPYFILE_NOFOLLOW_SRC
 106 .It Dv COPYFILE_RECURSIVE
 107 Causes
 108 .Fn copyfile
 109 to recursively copy a hierarchy.
 110 This flag is not used by
 111 .Fn fcopyfile ;
 112 see below for more information.
 113 .It Dv COPYFILE_CHECK
 114 Return a bitmask (corresponding to the
 115 .Va flags
 116 argument) indicating which contents would be copied; no data are actually
 117 copied.  (E.g., if
 118 .Va flags
 119 was set to
 120 .Dv COPYFILE_CHECK|COPYFILE_METADATA ,
 121 and the
 122 .Va from
 123 file had extended attributes but no ACLs, the return value would be
 124 .Dv COPYFILE_XATTR .)
 125 .It Dv COPYFILE_PACK
 126 Serialize the
 127 .Va from
 128 file.  The
 129 .Va to
 130 file is an AppleDouble-format file.
 131 .It Dv COPYFILE_UNPACK
 132 Unserialize the
 133 .Va from
 134 file.  The
 135 .Va from
 136 file is an AppleDouble-format file; the
 137 .Va to
 138 file will have the extended attributes, ACLs, resource fork, and
 139 FinderInfo data from the
 140 .Va to
 141 file, regardless of the
 142 .Va flags
 143 argument passed in.
 144 .It Dv COPYFILE_EXCL
 145 Fail if the
 146 .Va to
 147 file already exists.  (This is only applicable for the
 148 .Fn copyfile
 149 function.)
 150 .It Dv COPYFILE_NOFOLLOW_SRC
 151 Do not follow the
 152 .Va from
 153 file, if it is a symbolic link.  (This is only applicable for the
 154 .Fn copyfile
 155 function.)
 156 .It Dv COPYFILE_NOFOLLOW_DST
 157 Do not follow the
 158 .Va to
 159 file, if it is a symbolic link.  (This is only applicable for the
 160 .Fn copyfile
 161 function.)
 162 .It Dv COPYFILE_MOVE
 163 Unlink (using
 164 .Xr remove 3 )
 165 the
 166 .Fa from
 167 file.  (This is only applicable for the
 168 .Fn copyfile
 169 function.)  No error is returned if
 170 .Xr remove 3
 171 fails.  Note that
 172 .Xr remove 3
 173 removes a symbolic link itself, not the
 174 target of the link.
 175 .It Dv COPYFILE_UNLINK
 176 Unlink the
 177 .Va to
 178 file before starting.  (This is only applicable for the
 179 .Fn copyfile
 180 function.)
 181 .It Dv COPYFILE_CLONE_FORCE
 182 Clone the file instead.
 183 This is a force flag i.e. if cloning fails, an error is returned.
 184 This flag is equivalent to (COPYFILE_EXCL | COPYFILE_ACL | COPYFILE_STAT | COPYFILE_XATTR | COPYFILE_DATA).
 185 Note that if cloning is successful, callbacks will not be invoked.
 186 Note also that there is no support for cloning directories: if a directory is provided as the source,
 187 an error will be returned.
 188 (This is only applicable for the
 189 .Fn copyfile
 190 function.)
 191 .It Dv COPYFILE_CLONE
 192 Try to clone the file instead.
 193 This is a best try flag i.e. if cloning fails, fallback to copying the file.
 194 This flag is equivalent to (COPYFILE_EXCL | COPYFILE_ACL | COPYFILE_STAT | COPYFILE_XATTR | COPYFILE_DATA).
 195 Note that if cloning is successful, callbacks will not be invoked.
 196 Note also that there is no support for cloning directories: if a directory is provided as the source,
 197 this will instead copy the directory (recursively if COPYFILE_RECURSIVE is also passed).
 198 (This is only applicable for the
 199 .Fn copyfile
 200 function.)
 201 .It Dv COPYFILE_NOFOLLOW
 202 This is a convenience macro, equivalent to
 203 .Dv (COPYFILE_NOFOLLOW_DST | COPYFILE_NOFOLLOW_SRC) .
 204 .It Dv COPYFILE_RUN_IN_PLACE
 205 If the src file has quarantine information, add the QTN_FLAG_DO_NOT_TRANSLOCATE flag to the quarantine information of the dst file. This allows a bundle to run in place instead of being translocated.
 206 .El
 207 .Pp
 208 The
 209 .Fn copyfile_state_get
 210 and
 211 .Fn copyfile_state_set
 212 functions can be used to manipulate the
 213 .Ft copyfile_state_t
 214 object returned by
 215 .Fn copyfile_state_alloc .
 216 In both functions, the
 217 .Va dst
 218 parameter's type depends on the
 219 .Va flag
 220 parameter that is passed in.
 221 .Bl -tag -width COPYFILE_STATE_DST_FILENAME
 222 .It Dv COPYFILE_STATE_SRC_FD
 223 .It Dv COPYFILE_STATE_DST_FD
 224 Get or set the file descriptor associated with the source (or destination)
 225 file.
 226 If this has not been initialized yet, the value will be -2.
 227 The
 228 .Va dst
 229 (for
 230 .Fn copyfile_state_get )
 231 and
 232 .Va src
 233 (for
 234 .Fn copyfile_state_set )
 235 parameters are pointers to
 236 .Vt int .
 237 .It Dv COPYFILE_STATE_SRC_FILENAME
 238 .It Dv COPYFILE_STATE_DST_FILENAME
 239 Get or set the filename associated with the source (or destination)
 240 file.  If it has not been initialized yet, the value will be
 241 .Dv NULL .
 242 For
 243 .Fn copyfile_state_set ,
 244 the
 245 .Va src
 246 parameter is a pointer to a C string
 247 (i.e.,
 248 .Vt char* );
 249 .Fn copyfile_state_set
 250 makes a private copy of this string.
 251 For
 252 .Fn copyfile_state_get
 253 function, the
 254 .Va dst
 255 parameter is a pointer to a pointer to a C string
 256 (i.e.,
 257 .Vt char** );
 258 the returned value is a pointer to the
 259 .Va state 's
 260 copy, and must not be modified or released.
 261 .It Dv COPYFILE_STATE_STATUS_CB
 262 Get or set the callback status function (currently
 263 only used for recursive copies; see below for details).
 264 The
 265 .Va src
 266 parameter is a pointer to a function of type
 267 .Vt copyfile_callback_t
 268 (see above).
 269 .It Dv COPYFILE_STATE_STATUS_CTX
 270 Get or set the context parameter for the status
 271 call-back function (see below for details).
 272 The
 273 .Va src
 274 parameter is a
 275 .Vt void\ * .
 276 .It Dv COPYFILE_STATE_QUARANTINE
 277 Get or set the quarantine information with the source file.
 278 The
 279 .Va src
 280 parameter is a pointer to an opaque
 281 object (type
 282 .Vt void\ *
 283 ).
 284 .It Dv COPYFILE_STATE_COPIED
 285 Get the number of data bytes copied so far.
 286 (Only valid for
 287 .Fn copyfile_state_get ;
 288 see below for more details about callbacks.)
 289 If a
 290 .Dv COPYFILE_CLONE
 291 or
 292 .Dv COPYFILE_CLONE_FORCE
 293 operation successfully cloned the requested objects, then this value will be 0.
 294 The
 295 .Va dst
 296 parameter is a pointer to
 297 .Vt off_t
 298 (type
 299 .Vt off_t\ * ).
 300 .It Dv COPYFILE_STATE_XATTRNAME
 301 Get the name of the extended attribute during a callback
 302 for
 303 .Dv COPYFILE_COPY_XATTR
 304 (see below for details).  This field cannot be set,
 305 and may be
 306 .Dv NULL .
 307 .It Dv COPYFILE_STATE_WAS_CLONED
 308 True if a
 309 .Dv COPYFILE_CLONE
 310 or
 311 .Dv COPYFILE_CLONE_FORCE
 312 operation successfully cloned the requested objects.
 313 The
 314 .Va dst
 315 parameter is a pointer to
 316 .Vt bool
 317 (type
 318 .Vt bool\ * ).
 319 .El
 320 .Sh Recursive Copies
 321 When given the
 322 .Dv COPYFILE_RECURSIVE
 323 flag,
 324 .Fn copyfile
 325 (but not
 326 .Fn fcopyfile )
 327 will use the
 328 .Xr fts 3
 329 functions to recursively descend into the source file-system object.
 330 It then calls
 331 .Fn copyfile
 332 on each of the entries it finds that way.
 333 If a call-back function is given (using
 334 .Fn copyfile_state_set
 335 and
 336 .Dv COPYFILE_STATE_STATUS_CB ),
 337 the call-back function will be called four times for each directory
 338 object, and twice for all other objects.  (Each directory will
 339 be examined twice, once on entry -- before copying each of the
 340 objects contained in the directory -- and once on exit -- after
 341 copying each object contained in the directory, in order to perform
 342 some final cleanup.)
 343 .Pp
 344 The call-back function will have one of the following values
 345 as the first argument, indicating what is being copied:
 346 .Bl -tag -width COPYFILE_RECURSE_DIR_CLEANUP
 347 .It Dv COPYFILE_RECURSE_FILE
 348 The object being copied is a file (or, rather,
 349 something other than a directory).
 350 .It Dv COPYFILE_RECURSE_DIR
 351 The object being copied is a directory, and is being
 352 entered.  (That is, none of the filesystem objects contained
 353 within the directory have been copied yet.)
 354 .It Dv COPYFILE_RECURSE_DIR_CLEANUP
 355 The object being copied is a directory, and all of the
 356 objects contained have been copied.  At this stage, the destination directory
 357 being copied will have any extra permissions that were added to
 358 allow the copying will be removed.
 359 .It Dv COPYFILE_RECURSE_ERROR
 360 There was an error in processing an element of the source hierarchy;
 361 this happens when
 362 .Xr fts 3
 363 returns an error or unknown file type.
 364 (Currently, the second argument to the call-back function will always
 365 be
 366 .Dv COPYFILE_ERR
 367 in this case.)
 368 .El
 369 .Pp
 370 The second argument to the call-back function will indicate
 371 the stage of the copy, and will be one of the following values:
 372 .Bl -tag -width COPYFILE_FINISH
 373 .It Dv COPYFILE_START
 374 Before copying has begun.  The third
 375 parameter will be a newly-created
 376 .Vt copyfile_state_t
 377 object with the call-back function and context pre-loaded.
 378 .It Dv COPYFILE_FINISH
 379 After copying has successfully finished.
 380 .It Dv COPYFILE_ERR
 381 Indicates an error has happened at some stage.  If the
 382 first argument to the call-back function is
 383 .Dv COPYFILE_RECURSE_ERROR ,
 384 then an error occurred while processing the source hierarchy;
 385 otherwise, it will indicate what type of object was being copied,
 386 and
 387 .Dv errno
 388 will be set to indicate the error.
 389 .El
 390 .Pp
 391 The fourth and fifth
 392 parameters are the source and destination paths that
 393 are to be copied (or have been copied, or failed to copy, depending on
 394 the second argument).
 395 .Pp
 396 The last argument to the call-back function will be the value
 397 set by
 398 .Dv COPYFILE_STATE_STATUS_CTX ,
 399 if any.
 400 .Pp
 401 The call-back function is required to return one of the following
 402 values:
 403 .Bl -tag -width COPYFILE_CONTINUE
 404 .It Dv COPYFILE_CONTINUE
 405 The copy will continue as expected.
 406 .It Dv COPYFILE_SKIP
 407 This object will be skipped, and the next object will
 408 be processed.  (Note that, when entering a directory.
 409 returning
 410 .Dv COPYFILE_SKIP
 411 from the call-back function will prevent the contents
 412 of the directory from being copied.)
 413 .It Dv COPYFILE_QUIT
 414 The entire copy is aborted at this stage.  Any filesystem
 415 objects created up to this point will remain.
 416 .Fn copyfile
 417 will return -1, but
 418 .Dv errno
 419 will be unmodified.
 420 .El
 421 .Pp
 422 The call-back function must always return one of the values listed
 423 above; if not, the results are undefined.
 424 .Pp
 425 The call-back function will be called twice for each object
 426 (and an additional two times for directory cleanup); the first
 427 call will have a
 428 .Ar stage
 429 parameter of
 430 .Dv COPYFILE_START ;
 431 the second time, that value will be either
 432 .Dv COPYFILE_FINISH
 433 or
 434 .Dv COPYFILE_ERR
 435 to indicate a successful completion, or an error during
 436 processing.
 437 In the event of an error, the
 438 .Dv errno
 439 value will be set appropriately.
 440 .Pp
 441 The
 442 .Dv COPYFILE_PACK ,
 443 .Dv COPYFILE_UNPACK ,
 444 .Dv COPYFILE_MOVE ,
 445 and
 446 .Dv COPYFILE_UNLINK
 447 flags are not used during a recursive copy, and will result
 448 in an error being returned.
 449 .Sh Progress Callback
 450 In addition to the recursive callbacks described above,
 451 .Fn copyfile
 452 and
 453 .Fn fcopyfile
 454 will also use a callback to report data (e.g.,
 455 .Dv COPYFILE_DATA )
 456 progress.  If given, the callback will be invoked on each
 457 .Xr write 2
 458 call.  The first argument to the callback function will be
 459 .Dv COPYFILE_COPY_DATA .
 460 The second argument will either be
 461 .Dv COPYFILE_PROGRESS
 462 (indicating that the write was successful), or
 463 .Dv COPYFILE_ERR
 464 (indicating that there was an error of some sort).
 465 .Pp
 466 The amount of data bytes copied so far can be retrieved using
 467 .Fn copyfile_state_get ,
 468 with the
 469 .Dv COPYFILE_STATE_COPIED
 470 requestor (the argument type is a pointer to
 471 .Vt off_t ).
 472 .Pp
 473 When copying extended attributes, the first argument to the
 474 callback function will be
 475 .Dv COPYFILE_COPY_XATTR .
 476 The other arguments will be as described for
 477 .Dv COPYFILE_COPY_DATA ;
 478 the name of the extended attribute being copied may be
 479 retrieved using
 480 .Fn copyfile_state_get
 481 and the parameter
 482 .Dv COPYFILE_STATE_XATTRNAME .
 483 When using
 484 .Dv COPYFILE_PACK ,
 485 the callback may be called with
 486 .Dv COPYFILE_START
 487 for each of the extended attributes first, followed by
 488 .Dv COPYFILE_PROGRESS
 489 before getting and packing the data for each
 490 individual attribute, and then
 491 .Dv COPYFILE_FINISH
 492 when finished with each individual attribute.
 493 (That is,
 494 .Dv COPYFILE_START
 495 may be called for all of the extended attributes, before
 496 the first callback with
 497 .Dv COPYFILE_PROGRESS
 498 is invoked.)  Any attribute skipped by returning
 499 .Dv COPYFILE_SKIP
 500 from the
 501 .Dv COPYFILE_START
 502 callback will not be placed into the packed output file.
 503 .Pp
 504 The return value for the data callback must be one of
 505 .Bl -tag -width COPYFILE_CONTINUE
 506 .It Dv COPYFILE_CONTINUE
 507 The copy will continue as expected.
 508 (In the case of error, it will attempt to write the data again.)
 509 .It Dv COPYFILE_SKIP
 510 The data copy will be aborted, but without error.
 511 .It Dv COPYFILE_QUIT
 512 The data copy will be aborted; in the case of
 513 .Dv COPYFILE_PROGRESS ,
 514 .Dv errno
 515 will be set to
 516 .Dv ECANCELED .
 517 .El
 518 .Pp
 519 While the
 520 .Va src
 521 and
 522 .Va dst
 523 parameters will be passed in, they may be
 524 .Dv NULL
 525 in the case of
 526 .Fn fcopyfile .
 527 .Sh RETURN VALUES
 528 Except when given the
 529 .Dv COPYFILE_CHECK
 530 flag,
 531 .Fn copyfile
 532 and
 533 .Fn fcopyfile
 534 return less than 0 on error, and 0 on success.
 535 All of the other functions return 0 on success, and less than 0
 536 on error.
 537 .Sh WARNING
 538 Both
 539 .Fn copyfile
 540 and
 541 .Fn fcopyfile
 542 can copy symbolic links; there is a gap between when the source
 543 link is examined and the actual copy is started, and this can
 544 be a potential security risk, especially if the process has
 545 elevated privileges.
 546 .Pp
 547 When performing a recursive copy, if the source hierarchy
 548 changes while the copy is occurring, the results are undefined.
 549 .Pp
 550 .Fn fcopyfile
 551 does not reset the seek position for either source or destination.
 552 This can result in the destination file being a different size
 553 than the source file.
 554 .Sh ERRORS
 555 .Fn copyfile
 556 and
 557 .Fn fcopyfile
 558 will fail if:
 559 .Bl -tag -width Er
 560 .It Bq Er EINVAL
 561 An invalid flag was passed in with
 562 .Dv COPYFILE_RECURSIVE .
 563 .It Bq Er EINVAL
 564 The
 565 .Va from
 566 or
 567 .Va to
 568 parameter to
 569 .Fn copyfile
 570 was a
 571 .Dv NULL
 572 pointer.
 573 .It Bq Er EINVAL
 574 The
 575 .Va from
 576 or
 577 .Va to
 578 parameter to
 579 .Fn fcopyfile
 580 was a negative number.
 581 .It Bq Er ENOMEM
 582 A memory allocation failed.
 583 .It Bq Er ENOTSUP
 584 The source file was not a directory, symbolic link, or regular file.
 585 .It Bq Er ECANCELED
 586 The copy was cancelled by callback.
 587 .It Bq Er EEXIST
 588 The
 589 .Va to
 590 parameter to
 591 .Fn copyfile
 592 already existed and was passed in with
 593 .Dv COPYFILE_EXCL .
 594 .It Bq Er ENOENT
 595 The
 596 .Va from
 597 parameter to
 598 .Fn copyfile
 599 did not exist.
 600 .It Bq Er EACCES
 601 Search permission is denied for a component of the path prefix for
 602 the
 603 .Va from
 604 or
 605 .Va to
 606 parameters.
 607 .It Bq Er EACCES
 608 Write permission is denied for a component of the path prefix for the
 609 .Va to
 610 parameter.
 611 .El
 612 .Pp
 613 In addition, both functions may set
 614 .Dv errno
 615 via an underlying library or system call.
 616 .Sh EXAMPLES
 617 .Bd -literal -offset indent
 618 /* Initialize a state variable */
 619 copyfile_state_t s;
 620 s = copyfile_state_alloc();
 621 /* Copy the data and extended attributes of one file to another */
 622 copyfile("/tmp/f1", "/tmp/f2", s, COPYFILE_DATA | COPYFILE_XATTR);
 623 /* Convert a file to an AppleDouble file for serialization */
 624 copyfile("/tmp/f2", "/tmp/tmpfile", NULL, COPYFILE_ALL | COPYFILE_PACK);
 625 /* Release the state variable */
 626 copyfile_state_free(s);
 627 /* A more complex way to call copyfile() */
 628 s = copyfile_state_alloc();
 629 copyfile_state_set(s, COPYFILE_STATE_SRC_FILENAME, "/tmp/foo");
 630 /* One of src or dst must be set... rest can come from the state */
 631 copyfile(NULL, "/tmp/bar", s, COPYFILE_ALL);
 632 /* Now copy the same source file to another destination file */
 633 copyfile(NULL, "/tmp/car", s, COPYFILE_ALL);
 634 copyfile_state_free(s);
 635 /* Remove extended attributes from a file */
 636 copyfile("/dev/null", "/tmp/bar", NULL, COPYFILE_XATTR);
 637 .Ed
 638 .Sh SEE ALSO
 639 .Xr listxattr 2 ,
 640 .Xr getxattr 2 ,
 641 .Xr setxattr 2 ,
 642 .Xr acl 3
 643 .Sh BUGS
 644 Both
 645 .Fn copyfile
 646 functions lack a way to set the input or output block size.
 647 .Pp
 648 Recursive copies do not honor hard links.
 649 .Sh HISTORY
 650 The
 651 .Fn copyfile
 652 API was introduced in Mac OS X 10.5.