copyfile.3

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