copyfile.3

   1 .\"
   2 .\" Copyright (c) 2002 Apple Computer, Inc.  All rights reserved.
   3 .\"
   4 .Dd November 2, 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 | COPYFILE_NOFOLLOW_SRC).
 186 Note that if cloning is successful, progress callbacks will not be invoked.
 187 Note also that there is no support for cloning directories: if a directory is provided as the source,
 188 an error will be returned. Since this flag implies COPYFILE_NOFOLLOW_SRC, symbolic links themselves will
 189 be cloned instead of their targets.
 190 (This is only applicable for the
 191 .Fn copyfile
 192 function.)
 193 .It Dv COPYFILE_CLONE
 194 Try to clone the file instead.
 195 This is a best try flag i.e. if cloning fails, fallback to copying the file.
 196 This flag is equivalent to (COPYFILE_EXCL | COPYFILE_ACL | COPYFILE_STAT | COPYFILE_XATTR | COPYFILE_DATA
 197 | COPYFILE_NOFOLLOW_SRC).
 198 Note that if cloning is successful, progress callbacks will not be invoked.
 199 Note also that there is no support for cloning directories: if a directory is provided as the source and
 200 COPYFILE_CLONE_FORCE is not passed, this will instead copy the directory. Since this flag implies COPYFILE_NOFOLLOW_SRC,
 201 symbolic links themselves will be cloned instead of their targets. Recursive copying however is
 202 supported, see below for more information.
 203 (This is only applicable for the
 204 .Fn copyfile
 205 function.)
 206 .It Dv COPYFILE_DATA_SPARSE
 207 Copy a file sparsely.
 208 This requires that the source and destination file systems support sparse files with hole sizes
 209 at least as large as their block sizes.
 210 This also requires that the source file is sparse, and for
 211 .Fn fcopyfile
 212 the source file descriptor's offset be a multiple of the minimum hole size.
 213 If COPYFILE_DATA is also specified, this will fall back to a full copy
 214 if sparse copying cannot be performed for any reason; otherwise, an error is returned.
 215 .It Dv COPYFILE_NOFOLLOW
 216 This is a convenience macro, equivalent to
 217 .Dv (COPYFILE_NOFOLLOW_DST | COPYFILE_NOFOLLOW_SRC) .
 218 .It Dv COPYFILE_RUN_IN_PLACE
 219 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.
 220 .El
 221 .Pp
 222 Copying files into a directory is supported. If
 223 .Va to
 224 is a directory,
 225 .Va from
 226 will be copied into
 227 .Va to
 228 (if
 229 .Va from
 230 is a directory,
 231 copying its contents requires use of the COPYFILE_RECURSIVE parameter,
 232 which is documented below).
 233 .Pp
 234 The
 235 .Fn copyfile_state_get
 236 and
 237 .Fn copyfile_state_set
 238 functions can be used to manipulate the
 239 .Ft copyfile_state_t
 240 object returned by
 241 .Fn copyfile_state_alloc .
 242 In both functions, the
 243 .Va dst
 244 parameter's type depends on the
 245 .Va flag
 246 parameter that is passed in.
 247 .Bl -tag -width COPYFILE_STATE_DST_FILENAME
 248 .It Dv COPYFILE_STATE_SRC_FD
 249 .It Dv COPYFILE_STATE_DST_FD
 250 Get or set the file descriptor associated with the source (or destination)
 251 file.
 252 If this has not been initialized yet, the value will be -2.
 253 The
 254 .Va dst
 255 (for
 256 .Fn copyfile_state_get )
 257 and
 258 .Va src
 259 (for
 260 .Fn copyfile_state_set )
 261 parameters are pointers to
 262 .Vt int .
 263 .It Dv COPYFILE_STATE_SRC_FILENAME
 264 .It Dv COPYFILE_STATE_DST_FILENAME
 265 Get or set the filename associated with the source (or destination)
 266 file.  If it has not been initialized yet, the value will be
 267 .Dv NULL .
 268 For
 269 .Fn copyfile_state_set ,
 270 the
 271 .Va src
 272 parameter is a pointer to a C string
 273 (i.e.,
 274 .Vt char* );
 275 .Fn copyfile_state_set
 276 makes a private copy of this string.
 277 For
 278 .Fn copyfile_state_get
 279 function, the
 280 .Va dst
 281 parameter is a pointer to a pointer to a C string
 282 (i.e.,
 283 .Vt char** );
 284 the returned value is a pointer to the
 285 .Va state 's
 286 copy, and must not be modified or released.
 287 .It Dv COPYFILE_STATE_STATUS_CB
 288 Get or set the callback status function (currently
 289 only used for recursive copies; see below for details).
 290 The
 291 .Va src
 292 parameter is a pointer to a function of type
 293 .Vt copyfile_callback_t
 294 (see above).
 295 .It Dv COPYFILE_STATE_STATUS_CTX
 296 Get or set the context parameter for the status
 297 call-back function (see below for details).
 298 The
 299 .Va src
 300 parameter is a
 301 .Vt void\ * .
 302 .It Dv COPYFILE_STATE_QUARANTINE
 303 Get or set the quarantine information with the source file.
 304 The
 305 .Va src
 306 parameter is a pointer to an opaque
 307 object (type
 308 .Vt void\ *
 309 ).
 310 .It Dv COPYFILE_STATE_COPIED
 311 Get the number of data bytes copied so far.
 312 (Only valid for
 313 .Fn copyfile_state_get ;
 314 see below for more details about callbacks.)
 315 If a
 316 .Dv COPYFILE_CLONE
 317 or
 318 .Dv COPYFILE_CLONE_FORCE
 319 operation successfully cloned the requested objects, then this value will be 0.
 320 The
 321 .Va dst
 322 parameter is a pointer to
 323 .Vt off_t
 324 (type
 325 .Vt off_t\ * ).
 326 .It Dv COPYFILE_STATE_XATTRNAME
 327 Get the name of the extended attribute during a callback
 328 for
 329 .Dv COPYFILE_COPY_XATTR
 330 (see below for details).  This field cannot be set,
 331 and may be
 332 .Dv NULL .
 333 .It Dv COPYFILE_STATE_WAS_CLONED
 334 True if a
 335 .Dv COPYFILE_CLONE
 336 or
 337 .Dv COPYFILE_CLONE_FORCE
 338 operation successfully cloned the requested objects.
 339 The
 340 .Va dst
 341 parameter is a pointer to
 342 .Vt bool
 343 (type
 344 .Vt bool\ * ).
 345 .El
 346 .Sh Recursive Copies
 347 When given the
 348 .Dv COPYFILE_RECURSIVE
 349 flag,
 350 .Fn copyfile
 351 (but not
 352 .Fn fcopyfile )
 353 will use the
 354 .Xr fts 3
 355 functions to recursively descend into the source file-system object.
 356 It then calls
 357 .Fn copyfile
 358 on each of the entries it finds that way.
 359 If a call-back function is given (using
 360 .Fn copyfile_state_set
 361 and
 362 .Dv COPYFILE_STATE_STATUS_CB ),
 363 the call-back function will be called four times for each directory
 364 object, and twice for all other objects.  (Each directory will
 365 be examined twice, once on entry -- before copying each of the
 366 objects contained in the directory -- and once on exit -- after
 367 copying each object contained in the directory, in order to perform
 368 some final cleanup.)
 369 .Pp
 370 The call-back function will have one of the following values
 371 as the first argument, indicating what is being copied:
 372 .Bl -tag -width COPYFILE_RECURSE_DIR_CLEANUP
 373 .It Dv COPYFILE_RECURSE_FILE
 374 The object being copied is a file (or, rather,
 375 something other than a directory).
 376 .It Dv COPYFILE_RECURSE_DIR
 377 The object being copied is a directory, and is being
 378 entered.  (That is, none of the filesystem objects contained
 379 within the directory have been copied yet.)
 380 .It Dv COPYFILE_RECURSE_DIR_CLEANUP
 381 The object being copied is a directory, and all of the
 382 objects contained have been copied.  At this stage, the destination directory
 383 being copied will have any extra permissions that were added to
 384 allow the copying will be removed.
 385 .It Dv COPYFILE_RECURSE_ERROR
 386 There was an error in processing an element of the source hierarchy;
 387 this happens when
 388 .Xr fts 3
 389 returns an error or unknown file type.
 390 (Currently, the second argument to the call-back function will always
 391 be
 392 .Dv COPYFILE_ERR
 393 in this case.)
 394 .El
 395 .Pp
 396 The second argument to the call-back function will indicate
 397 the stage of the copy, and will be one of the following values:
 398 .Bl -tag -width COPYFILE_FINISH
 399 .It Dv COPYFILE_START
 400 Before copying has begun.  The third
 401 parameter will be a newly-created
 402 .Vt copyfile_state_t
 403 object with the call-back function and context pre-loaded.
 404 .It Dv COPYFILE_FINISH
 405 After copying has successfully finished.
 406 .It Dv COPYFILE_ERR
 407 Indicates an error has happened at some stage.  If the
 408 first argument to the call-back function is
 409 .Dv COPYFILE_RECURSE_ERROR ,
 410 then an error occurred while processing the source hierarchy;
 411 otherwise, it will indicate what type of object was being copied,
 412 and
 413 .Dv errno
 414 will be set to indicate the error.
 415 .El
 416 .Pp
 417 The fourth and fifth
 418 parameters are the source and destination paths that
 419 are to be copied (or have been copied, or failed to copy, depending on
 420 the second argument).
 421 .Pp
 422 The last argument to the call-back function will be the value
 423 set by
 424 .Dv COPYFILE_STATE_STATUS_CTX ,
 425 if any.
 426 .Pp
 427 The call-back function is required to return one of the following
 428 values:
 429 .Bl -tag -width COPYFILE_CONTINUE
 430 .It Dv COPYFILE_CONTINUE
 431 The copy will continue as expected.
 432 .It Dv COPYFILE_SKIP
 433 This object will be skipped, and the next object will
 434 be processed.  (Note that, when entering a directory.
 435 returning
 436 .Dv COPYFILE_SKIP
 437 from the call-back function will prevent the contents
 438 of the directory from being copied.)
 439 .It Dv COPYFILE_QUIT
 440 The entire copy is aborted at this stage.  Any filesystem
 441 objects created up to this point will remain.
 442 .Fn copyfile
 443 will return -1, but
 444 .Dv errno
 445 will be unmodified.
 446 .El
 447 .Pp
 448 The call-back function must always return one of the values listed
 449 above; if not, the results are undefined.
 450 .Pp
 451 The call-back function will be called twice for each object
 452 (and an additional two times for directory cleanup); the first
 453 call will have a
 454 .Ar stage
 455 parameter of
 456 .Dv COPYFILE_START ;
 457 the second time, that value will be either
 458 .Dv COPYFILE_FINISH
 459 or
 460 .Dv COPYFILE_ERR
 461 to indicate a successful completion, or an error during
 462 processing.
 463 In the event of an error, the
 464 .Dv errno
 465 value will be set appropriately.
 466 .Pp
 467 Note that recursive cloning is also supported with the
 468 .Dv COPYFILE_CLONE
 469 flag (but not the
 470 .Dv COPYFILE_CLONE_FORCE
 471 flag). A recursive clone operation invokes
 472 .Fn copyfile
 473 with
 474 .Dv COPYFILE_CLONE
 475 on every entry found in the source file-system object. Because
 476 .Fn copyfile
 477 does not allow the cloning of directories, a recursive clone will
 478 instead copy any directory it finds (while cloning its contents).
 479 As symbolic links may point to directories, they are not followed
 480 during recursive clones even if the source is a symbolic link.
 481 Additionally, because the
 482 .Dv COPYFILE_CLONE
 483 flag implies the
 484 .Dv COPYFILE_EXCL
 485 flag, recursive clones require a nonexistent destination.
 486 .Pp
 487 The
 488 .Dv COPYFILE_PACK ,
 489 .Dv COPYFILE_UNPACK ,
 490 .Dv COPYFILE_MOVE ,
 491 and
 492 .Dv COPYFILE_UNLINK
 493 flags are not used during a recursive copy, and will result
 494 in an error being returned.
 495 .Pp
 496 Note that if the source path ends in a
 497 .Va /
 498 its contents are copied rather than the directory itself (like cp(1)).
 499 The behavior of a recursive copy on a directory hierarchy also depends
 500 on the contents of the destination. If the destination is a directory,
 501 the source directory (or its contents, if the source path ends in a
 502 .Va /
 503 ) will be copied into it. If the destination exists but is not a
 504 directory, and the source is a non-empty directory, the copy will fail;
 505 the exact error set depends on the flags provided to
 506 .Fn copyfile
 507 initially.
 508 .Sh Progress Callback
 509 In addition to the recursive callbacks described above,
 510 .Fn copyfile
 511 and
 512 .Fn fcopyfile
 513 will also use a callback to report data (e.g.,
 514 .Dv COPYFILE_DATA )
 515 progress.  If given, the callback will be invoked on each
 516 .Xr write 2
 517 call.  The first argument to the callback function will be
 518 .Dv COPYFILE_COPY_DATA .
 519 The second argument will either be
 520 .Dv COPYFILE_PROGRESS
 521 (indicating that the write was successful), or
 522 .Dv COPYFILE_ERR
 523 (indicating that there was an error of some sort).
 524 .Pp
 525 The amount of data bytes copied so far can be retrieved using
 526 .Fn copyfile_state_get ,
 527 with the
 528 .Dv COPYFILE_STATE_COPIED
 529 requestor (the argument type is a pointer to
 530 .Vt off_t ).
 531 .Pp
 532 When copying extended attributes, the first argument to the
 533 callback function will be
 534 .Dv COPYFILE_COPY_XATTR .
 535 The other arguments will be as described for
 536 .Dv COPYFILE_COPY_DATA ;
 537 the name of the extended attribute being copied may be
 538 retrieved using
 539 .Fn copyfile_state_get
 540 and the parameter
 541 .Dv COPYFILE_STATE_XATTRNAME .
 542 When using
 543 .Dv COPYFILE_PACK ,
 544 the callback may be called with
 545 .Dv COPYFILE_START
 546 for each of the extended attributes first, followed by
 547 .Dv COPYFILE_PROGRESS
 548 before getting and packing the data for each
 549 individual attribute, and then
 550 .Dv COPYFILE_FINISH
 551 when finished with each individual attribute.
 552 (That is,
 553 .Dv COPYFILE_START
 554 may be called for all of the extended attributes, before
 555 the first callback with
 556 .Dv COPYFILE_PROGRESS
 557 is invoked.)  Any attribute skipped by returning
 558 .Dv COPYFILE_SKIP
 559 from the
 560 .Dv COPYFILE_START
 561 callback will not be placed into the packed output file.
 562 .Pp
 563 The return value for the data callback must be one of
 564 .Bl -tag -width COPYFILE_CONTINUE
 565 .It Dv COPYFILE_CONTINUE
 566 The copy will continue as expected.
 567 (In the case of error, it will attempt to write the data again.)
 568 .It Dv COPYFILE_SKIP
 569 The data copy will be aborted, but without error.
 570 .It Dv COPYFILE_QUIT
 571 The data copy will be aborted; in the case of
 572 .Dv COPYFILE_PROGRESS ,
 573 .Dv errno
 574 will be set to
 575 .Dv ECANCELED .
 576 .El
 577 .Pp
 578 While the
 579 .Va src
 580 and
 581 .Va dst
 582 parameters will be passed in, they may be
 583 .Dv NULL
 584 in the case of
 585 .Fn fcopyfile .
 586 .Pp
 587 Note that progress callbacks are not invoked when a clone is requested
 588 (e.g.
 589 .Dv COPYFILE_CLONE )
 590 unless the clone cannot be performed and a copy is performed instead.
 591 .Sh RETURN VALUES
 592 Except when given the
 593 .Dv COPYFILE_CHECK
 594 flag,
 595 .Fn copyfile
 596 and
 597 .Fn fcopyfile
 598 return less than 0 on error, and 0 on success.
 599 All of the other functions return 0 on success, and less than 0
 600 on error.
 601 .Sh WARNING
 602 Both
 603 .Fn copyfile
 604 and
 605 .Fn fcopyfile
 606 can copy symbolic links; there is a gap between when the source
 607 link is examined and the actual copy is started, and this can
 608 be a potential security risk, especially if the process has
 609 elevated privileges.
 610 .Pp
 611 When performing a recursive copy, if the source hierarchy
 612 changes while the copy is occurring, the results are undefined.
 613 .Pp
 614 .Fn fcopyfile
 615 does not reset the seek position for either source or destination.
 616 This can result in the destination file being a different size
 617 than the source file.
 618 .Sh ERRORS
 619 .Fn copyfile
 620 and
 621 .Fn fcopyfile
 622 will fail if:
 623 .Bl -tag -width Er
 624 .It Bq Er EINVAL
 625 An invalid flag was passed in with
 626 .Dv COPYFILE_RECURSIVE .
 627 .It Bq Er EINVAL
 628 The
 629 .Va from
 630 or
 631 .Va to
 632 parameter to
 633 .Fn copyfile
 634 was a
 635 .Dv NULL
 636 pointer.
 637 .It Bq Er EINVAL
 638 The
 639 .Va from
 640 or
 641 .Va to
 642 parameter to
 643 .Fn fcopyfile
 644 was a negative number.
 645 .It Bq Er ENOMEM
 646 A memory allocation failed.
 647 .It Bq Er ENOTSUP
 648 The source file was not a directory, symbolic link, or regular file.
 649 .It Bq Er ENOTSUP
 650 COPYFILE_CLONE_FORCE was specified and file cloning is not supported.
 651 .It Bq Er ENOTSUP
 652 COPYFILE_DATA_SPARSE was specified, sparse copying is not supported,
 653 and COPYFILE_DATA was not specified.
 654 .It Bq Er ECANCELED
 655 The copy was cancelled by callback.
 656 .It Bq Er EEXIST
 657 The
 658 .Va to
 659 parameter to
 660 .Fn copyfile
 661 already existed and was passed in with
 662 .Dv COPYFILE_EXCL .
 663 .It Bq Er ENOENT
 664 The
 665 .Va from
 666 parameter to
 667 .Fn copyfile
 668 did not exist.
 669 .It Bq Er EACCES
 670 Search permission is denied for a component of the path prefix for
 671 the
 672 .Va from
 673 or
 674 .Va to
 675 parameters.
 676 .It Bq Er EACCES
 677 Write permission is denied for a component of the path prefix for the
 678 .Va to
 679 parameter.
 680 .El
 681 .Pp
 682 In addition, both functions may set
 683 .Dv errno
 684 via an underlying library or system call.
 685 .Sh EXAMPLES
 686 .Bd -literal -offset indent
 687 /* Initialize a state variable */
 688 copyfile_state_t s;
 689 s = copyfile_state_alloc();
 690 /* Copy the data and extended attributes of one file to another */
 691 copyfile("/tmp/f1", "/tmp/f2", s, COPYFILE_DATA | COPYFILE_XATTR);
 692 /* Convert a file to an AppleDouble file for serialization */
 693 copyfile("/tmp/f2", "/tmp/tmpfile", NULL, COPYFILE_ALL | COPYFILE_PACK);
 694 /* Release the state variable */
 695 copyfile_state_free(s);
 696 /* A more complex way to call copyfile() */
 697 s = copyfile_state_alloc();
 698 copyfile_state_set(s, COPYFILE_STATE_SRC_FILENAME, "/tmp/foo");
 699 /* One of src or dst must be set... rest can come from the state */
 700 copyfile(NULL, "/tmp/bar", s, COPYFILE_ALL);
 701 /* Now copy the same source file to another destination file */
 702 copyfile(NULL, "/tmp/car", s, COPYFILE_ALL);
 703 copyfile_state_free(s);
 704 /* Remove extended attributes from a file */
 705 copyfile("/dev/null", "/tmp/bar", NULL, COPYFILE_XATTR);
 706 .Ed
 707 .Sh SEE ALSO
 708 .Xr listxattr 2 ,
 709 .Xr getxattr 2 ,
 710 .Xr setxattr 2 ,
 711 .Xr acl 3
 712 .Sh BUGS
 713 Both
 714 .Fn copyfile
 715 functions lack a way to set the input or output block size.
 716 .Pp
 717 Recursive copies do not honor hard links.
 718 .Sh HISTORY
 719 The
 720 .Fn copyfile
 721 API was introduced in Mac OS X 10.5.