copyfile.3

   1 .\"
   2 .\" Copyright (c) 2002 Apple Computer, Inc.  All rights reserved.
   3 .\"
   4 .Dd April 27, 2006
   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 hierachy.
 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 (remove) the
 164 .Fa from
 165 file.  (This is only applicable for the
 166 .Fn copyfile
 167 function.)
 168 .It Dv COPYFILE_UNLINK
 169 Unlink the
 170 .Va to
 171 file before starting.  (This is only applicable for the
 172 .Fn copyfile
 173 function.)
 174 .It Dv COPYFILE_NOFOLLOW
 175 This is a convenience macro, equivalent to
 176 .Dv (COPYFILE_NOFOLLOW_DST|COPYFILE_NOFOLLOW_SRC) .
 177 .El
 178 .Pp
 179 The
 180 .Fn copyfile_state_get
 181 and
 182 .Fn copyfile_state_set
 183 functions can be used to manipulate the
 184 .Ft copyfile_state_t
 185 object returned by
 186 .Fn copyfile_state_alloc .
 187 In both functions, the
 188 .Va dst
 189 parameter's type depends on the
 190 .Va flag
 191 parameter that is passed in.
 192 .Bl -tag -width COPYFILE_STATE_DST_FILENAME
 193 .It Dv COPYFILE_STATE_SRC_FD
 194 .It Dv COPYFILE_STATE_DST_FD
 195 Get or set the file descriptor associated with the source (or destination)
 196 file.
 197 If this has not been initialized yet, the value will be -2.
 198 The
 199 .Va dst
 200 (for
 201 .Fn copyfile_state_get )
 202 and
 203 .Va src
 204 (for
 205 .Fn copyfile_state_set )
 206 parameters are pointers to
 207 .Vt int .
 208 .It Dv COPYFILE_STATE_SRC_FILENAME
 209 .It Dv COPYFILE_STATE_DST_FILENAME
 210 Get or set the filename associated with the source (or destination)
 211 file.  If it has not been initialized yet, the value will be
 212 .Dv NULL .
 213 For
 214 .Fn copyfile_state_set ,
 215 the
 216 .Va src
 217 parameter is a pointer to a C string
 218 (i.e.,
 219 .Vt char* );
 220 .Fn copyfile_state_set
 221 makes a private copy of this string.
 222 For
 223 .Fn copyfile_state_get
 224 function, the
 225 .Va dst
 226 parameter is a pointer to a pointer to a C string
 227 (i.e.,
 228 .Vt char** );
 229 the returned value is a pointer to the
 230 .Va state 's
 231 copy, and must not be modified or released.
 232 .It Dv COPYFILE_STATE_STATUS_CB
 233 Get or set the callback status function (currently
 234 only used for recursive copies; see below for details).
 235 The
 236 .Va src
 237 parameter is a pointer to a function of type
 238 .Vt copyfile_callback_t
 239 (see above).
 240 .It Dv COPYFILE_STATE_STATUS_CTX
 241 Get or set the context parameter for the status
 242 call-back function (see below for details).
 243 The
 244 .Va src
 245 parameter is a
 246 .Vt void\ * .
 247 .It Dv COPYFILE_STATE_QUARANTINE
 248 Get or set the quarantine information with the source file.
 249 The
 250 .Va src
 251 parameter is a pointer to an opaque
 252 object (type
 253 .Vt void\ *
 254 ).
 255 .It Dv COPYFILE_STATE_COPIED
 256 Get the number of data bytes copied so far.
 257 (Only valid for
 258 .Fn copyfile_state_get ;
 259 see below for more details about callbacks.)
 260 The
 261 .Va dst
 262 parameter is a pointer to
 263 .Vt off_t
 264 (type
 265 .Vt off_t\ * ).
 266 .El
 267 .Sh Recursive Copies
 268 When given the
 269 .Dv COPYFILE_RECURSIVE
 270 flag,
 271 .Fn copyfile
 272 (but not
 273 .Fn fcopyfile )
 274 will use the
 275 .Xr fts 3
 276 functions to recursively descend into the source file-system object.
 277 It then calls
 278 .Fn copyfile
 279 on each of the entries it finds that way.
 280 If a call-back function is given (using
 281 .Fn copyfile_state_set
 282 and
 283 .Dv COPYFILE_STATE_STATUS_CB ),
 284 the call-back function will be called four times for each directory
 285 object, and twice for all other objects.  (Each directory will
 286 be examined twice, once on entry -- before copying each of the
 287 objects contained in the directory -- and once on exit -- after
 288 copying each object contained in the directory, in order to perform
 289 some final cleanup.)
 290 .Pp
 291 The call-back function will have one of the following values
 292 as the first argument, indicating what is being copied:
 293 .Bl -tag -width COPYFILE_RECURSE_DIR_CLEANUP
 294 .It Dv COPYFILE_RECURSE_FILE
 295 The object being copied is a file (or, rather,
 296 something other than a directory).
 297 .It Dv COPYFILE_RECURSE_DIR
 298 The object being copied is a directory, and is being
 299 entered.  (That is, none of the filesystem objects contained
 300 within the directory have been copied yet.)
 301 .It Dv COPYFILE_RECURSE_DIR_CLEANUP
 302 The object being copied is a directory, and all of the
 303 objects contained have been copied.  At this stage, the destination directory
 304 being copied will have any extra permissions that were added to
 305 allow the copying will be removed.
 306 .It Dv COPYFILE_RECURSE_ERROR
 307 There was an error in processing an element of the source hierarchy;
 308 this happens when
 309 .Xr fts 3
 310 returns an error or unknown file type.
 311 (Currently, the second argument to the call-back function will always
 312 be
 313 .Dv COPYFILE_ERR
 314 in this case.)
 315 .El
 316 .Pp
 317 The second argument to the call-back function will indicate
 318 the stage of the copy, and will be one of the following values:
 319 .Bl -tag -width COPYFILE_FINISH
 320 .It Dv COPYFILE_START
 321 Before copying has begun.  The third
 322 parameter will be a newly-created
 323 .Vt copyfile_state_t
 324 object with the call-back function and context pre-loaded.
 325 .It Dv COPYFILE_FINISH
 326 After copying has successfully finished.
 327 .It Dv COPYFILE_ERR
 328 Indicates an error has happened at some stage.  If the
 329 first argument to the call-back function is
 330 .Dv COPYFILE_RECURSE_ERROR ,
 331 then an error occurred while processing the source hierarchy;
 332 otherwise, it will indicate what type of object was being copied,
 333 and
 334 .Dv errno
 335 will be set to indicate the error.
 336 .El
 337 .Pp
 338 The fourth and fifth
 339 parameters are the source and destination paths that
 340 are to be copied (or have been copied, or failed to copy, depending on
 341 the second argument).
 342 .Pp
 343 The last argument to the call-back function will be the value
 344 set by
 345 .Dv COPYFILE_STATE_STATUS_CTX ,
 346 if any.
 347 .Pp
 348 The call-back function is required to return one of the following
 349 values:
 350 .Bl -tag -width COPYFILE_CONTINUE
 351 .It Dv COPYFILE_CONTINUE
 352 The copy will continue as expected.
 353 .It Dv COPYFILE_SKIP
 354 This object will be skipped, and the next object will
 355 be processed.  (Note that, when entering a directory.
 356 returning
 357 .Dv COPYFILE_SKIP
 358 from the call-back function will prevent the contents
 359 of the directory from being copied.)
 360 .It Dv COPYFILE_QUIT
 361 The entire copy is aborted at this stage.  Any filesystem
 362 objects created up to this point will remain.
 363 .Fn copyfile
 364 will return -1, but
 365 .Dv errno
 366 will be unmodified.
 367 .El
 368 .Pp
 369 The call-back function must always return one of the values listed
 370 above; if not, the results are undefined.
 371 .Pp
 372 The call-back function will be called twice for each object
 373 (and an additional two times for directory cleanup); the first
 374 call will have a
 375 .Ar stage
 376 parameter of
 377 .Dv COPYFILE_START ;
 378 the second time, that value will be either
 379 .Dv COPYFILE_FINISH
 380 or
 381 .Dv COPYFILE_ERR
 382 to indicate a successful completion, or an error during
 383 processing.
 384 In the event of an error, the
 385 .Dv errno
 386 value will be set appropriately.
 387 .Pp
 388 The
 389 .Dv COPYFILE_PACK ,
 390 .Dv COPYFILE_UNPACK ,
 391 .Dv COPYFILE_MOVE ,
 392 and
 393 .Dv COPYFILE_UNLINK
 394 flags are not used during a recursive copy, and will result
 395 in an error being returned.
 396 .Sh Progress Callback
 397 In addition to the recursive callbacks described above,
 398 .Fn copyfile
 399 and
 400 .Fn fcopyfile
 401 will also use a callback to report data (i.e.,
 402 .Dv COPYFILE_DATA )
 403 progress.  If given, the callback will be invoked on each
 404 .Xr write 2
 405 call.  The first argument to the callback function will be
 406 .Dv COPYFILE_COPY_DATA .
 407 The second argument will either be
 408 .Dv COPYFILE_COPY_PROGRESS
 409 (indicating that the write was successful), or
 410 .Dv COPYFILE_ERR
 411 (indicating that there was an error of some sort).
 412 .Pp
 413 The amount of data bytes copied so far can be retrieved using
 414 .Fn copyfile_state_get ,
 415 with the
 416 .Dv COPYFILE_STATE_COPIED
 417 requestor (the argument type is a pointer to
 418 .Vt off_t ).
 419 .Pp
 420 The return value for the data callback must be one of
 421 .Bl -tag -width COPYFILE_CONTINUE
 422 .It Dv COPYFILE_CONTINUE
 423 The copy will continue as expected.
 424 (In the case of error, it will attempt to write the data again.)
 425 .It Dv COPYFILE_SKIP
 426 The data copy will be aborted, but without error.
 427 .It Dv COPYFILE_QUIT
 428 The data copy will be aborted; in the case of
 429 .Dv COPYFILE_COPY_PROGRESS ,
 430 .Dv errno
 431 will be set to
 432 .Dv ECANCELED .
 433 .El
 434 .Pp
 435 While the
 436 .Va src
 437 and
 438 .Va dst
 439 parameters will be passed in, they may be
 440 .Dv NULL
 441 in the case of
 442 .Fn fcopyfile .
 443 .Sh RETURN VALUES
 444 Except when given the
 445 .Dv COPYFILE_CHECK
 446 flag,
 447 .Fn copyfile
 448 and
 449 .Fn fcopyfile
 450 return less than 0 on error, and 0 on success.
 451 All of the other functions return 0 on success, and less than 0
 452 on error.
 453 .Sh WARNING
 454 Both
 455 .Fn copyfile
 456 and
 457 .Fn fcopyfile
 458 can copy symbolic links; there is a gap between when the source
 459 link is examnined and the actual copy is started, and this can
 460 be a potential security risk, especially if the process has
 461 elevated privileges.
 462 .Pp
 463 When performing a recursive copy, if the source hierarchy
 464 changes while the copy is occurring, the results are undefined.
 465 .Sh ERRORS
 466 .Fn copyfile
 467 and
 468 .Fn fcopyfile
 469 will fail if:
 470 .Bl -tag -width Er
 471 .It Bq Er EINVAL
 472 An invalid flag was passed in with
 473 .Dv COPYFILE_RECURSIVE .
 474 .It Bq Er EINVAL
 475 The
 476 .Va from
 477 or
 478 .Va to
 479 parameter to
 480 .Fn copyfile
 481 was a
 482 .Dv NULL
 483 pointer.
 484 .It Bq Er EINVAL
 485 The
 486 .Va from
 487 or
 488 .Va to
 489 parameter to
 490 .Fn copyfile
 491 was a negative number.
 492 .It Bq Er ENOMEM
 493 A memory allocation failed.
 494 .It Bq Er ENOTSUP
 495 The source file was not a directory, symbolic link, or regular file.
 496 .It Bq Er ECANCELED
 497 The copy was cancelled by callback.
 498 .El
 499 In addition, both functions may set
 500 .Dv errno
 501 via an underlying library or system call.
 502 .Sh EXAMPLES
 503 .Bd -literal -offset indent
 504 /* Initialize a state variable */
 505 copyfile_state_t s;
 506 s = copyfile_state_alloc();
 507 /* Copy the data and extended attributes of one file to another */
 508 copyfile("/tmp/f1", "/tmp/f2", s, COPYFILE_DATA | COPYFILE_XATTR);
 509 /* Convert a file to an AppleDouble file for serialization */
 510 copyfile("/tmp/f2", "/tmp/tmpfile", NULL, COPYFILE_ALL | COPYFILE_PACK);
 511 /* Release the state variable */
 512 copyfile_state_free(s);
 513 /* A more complex way to call copyfile() */
 514 s = copyfile_state_alloc();
 515 copyfile_state_set(s, COPYFILE_STATE_SRC_FILENAME, "/tmp/foo");
 516 /* One of src or dst must be set... rest can come from the state */
 517 copyfile(NULL, "/tmp/bar", s, COPYFILE_ALL);
 518 /* Now copy the same source file to another destination file */
 519 copyfile(NULL, "/tmp/car", s, COPYFILE_ALL);
 520 copyfile_state_free(s);
 521 /* Remove extended attributes from a file */
 522 copyfile("/dev/null", "/tmp/bar", NULL, COPYFILE_XATTR);
 523 .Ed
 524 .Sh SEE ALSO
 525 .Xr listxattr 2 ,
 526 .Xr getxattr 2 ,
 527 .Xr setxattr 2 ,
 528 .Xr acl 3
 529 .Sh BUGS
 530 Both
 531 .Fn copyfile
 532 functions lack a way to set the input or output block size.
 533 .Pp
 534 Recursive copies do not honor hard links.
 535 .Sh HISTORY
 536 The
 537 .Fn copyfile
 538 API was introduced in Mac OS X 10.5.