2 .\" Copyright (c) 2002 Apple Computer, Inc. All rights reserved.
8 .Nm copyfile , fcopyfile ,
9 .Nm copyfile_state_alloc , copyfile_state_free ,
10 .Nm copyfile_state_get , copyfile_state_set
17 .Fn copyfile "const char *from" "const char *to" "copyfile_state_t state" "copyfile_flags_t flags"
19 .Fn fcopyfile "int from" "int to" "copyfile_state_t state" "copyfile_flags_t flags"
21 .Fn copyfile_state_alloc "void"
23 .Fn copyfile_state_free "copyfile_state_t state"
25 .Fn copyfile_state_get "copyfile_state_t state" "uint32_t flag" "void * dst"
27 .Fn copyfile_state_set "copyfile_state_t state" "uint32_t flag" "const void * src"
29 .Fn (*copyfile_callback_t) "int what" "int stage" "copyfile_state_t state" "const char * src" "const char * dst" "void * ctx"
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
36 .Fn copyfile_state_alloc
37 function initializes a
39 object (which is an opaque data type).
40 This object can be passed to
44 .Fn copyfile_state_get
46 .Fn copyfile_state_set
47 can be used to manipulate the state (see below).
49 .Fn copyfile_state_free
50 function is used to deallocate the object and its contents.
54 function can copy the named
60 function does the same, but using the file descriptors of already-opened
64 parameter is the return value from
65 .Fn copyfile_state_alloc ,
70 will use the information from the state object; if it is
72 then both functions will work normally, but less control will be available to the caller.
75 parameter controls which contents are copied:
76 .Bl -tag -width COPYFILE_XATTR
78 Copy the source file's access control lists.
80 Copy the source file's POSIX information (mode, modification time, etc.).
82 Copy the source file's extended attributes.
84 Copy the source file's data.
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) .
96 Copy the entire file; equivalent to
97 .Dv (COPYFILE_METADATA|COPYFILE_DATA) .
104 functions can also have their behavior modified by the following flags:
105 .Bl -tag -width COPYFILE_NOFOLLOW_SRC
106 .It Dv COPYFILE_RECURSIVE
109 to recursively copy a hierarchy.
110 This flag is not used by
112 see below for more information.
113 .It Dv COPYFILE_CHECK
114 Return a bitmask (corresponding to the
116 argument) indicating which contents would be copied; no data are actually
120 .Dv COPYFILE_CHECK|COPYFILE_METADATA ,
123 file had extended attributes but no ACLs, the return value would be
124 .Dv COPYFILE_XATTR .)
130 file is an AppleDouble-format file.
131 .It Dv COPYFILE_UNPACK
136 file is an AppleDouble-format file; the
138 file will have the extended attributes, ACLs, resource fork, and
139 FinderInfo data from the
141 file, regardless of the
147 file already exists. (This is only applicable for the
150 .It Dv COPYFILE_NOFOLLOW_SRC
153 file, if it is a symbolic link. (This is only applicable for the
156 .It Dv COPYFILE_NOFOLLOW_DST
159 file, if it is a symbolic link. (This is only applicable for the
167 file. (This is only applicable for the
169 function.) No error is returned if
173 removes a symbolic link itself, not the
175 .It Dv COPYFILE_UNLINK
178 file before starting. (This is only applicable for the
181 .It Dv COPYFILE_NOFOLLOW
182 This is a convenience macro, equivalent to
183 .Dv (COPYFILE_NOFOLLOW_DST|COPYFILE_NOFOLLOW_SRC) .
187 .Fn copyfile_state_get
189 .Fn copyfile_state_set
190 functions can be used to manipulate the
193 .Fn copyfile_state_alloc .
194 In both functions, the
196 parameter's type depends on the
198 parameter that is passed in.
199 .Bl -tag -width COPYFILE_STATE_DST_FILENAME
200 .It Dv COPYFILE_STATE_SRC_FD
201 .It Dv COPYFILE_STATE_DST_FD
202 Get or set the file descriptor associated with the source (or destination)
204 If this has not been initialized yet, the value will be -2.
208 .Fn copyfile_state_get )
212 .Fn copyfile_state_set )
213 parameters are pointers to
215 .It Dv COPYFILE_STATE_SRC_FILENAME
216 .It Dv COPYFILE_STATE_DST_FILENAME
217 Get or set the filename associated with the source (or destination)
218 file. If it has not been initialized yet, the value will be
221 .Fn copyfile_state_set ,
224 parameter is a pointer to a C string
227 .Fn copyfile_state_set
228 makes a private copy of this string.
230 .Fn copyfile_state_get
233 parameter is a pointer to a pointer to a C string
236 the returned value is a pointer to the
238 copy, and must not be modified or released.
239 .It Dv COPYFILE_STATE_STATUS_CB
240 Get or set the callback status function (currently
241 only used for recursive copies; see below for details).
244 parameter is a pointer to a function of type
245 .Vt copyfile_callback_t
247 .It Dv COPYFILE_STATE_STATUS_CTX
248 Get or set the context parameter for the status
249 call-back function (see below for details).
254 .It Dv COPYFILE_STATE_QUARANTINE
255 Get or set the quarantine information with the source file.
258 parameter is a pointer to an opaque
262 .It Dv COPYFILE_STATE_COPIED
263 Get the number of data bytes copied so far.
265 .Fn copyfile_state_get ;
266 see below for more details about callbacks.)
269 parameter is a pointer to
273 .It Dv COPYFILE_STATE_XATTRNAME
274 Get the name of the extended attribute during a callback
276 .Dv COPYFILE_COPY_XATTR
277 (see below for details). This field cannot be set,
283 .Dv COPYFILE_RECURSIVE
290 functions to recursively descend into the source file-system object.
293 on each of the entries it finds that way.
294 If a call-back function is given (using
295 .Fn copyfile_state_set
297 .Dv COPYFILE_STATE_STATUS_CB ),
298 the call-back function will be called four times for each directory
299 object, and twice for all other objects. (Each directory will
300 be examined twice, once on entry -- before copying each of the
301 objects contained in the directory -- and once on exit -- after
302 copying each object contained in the directory, in order to perform
305 The call-back function will have one of the following values
306 as the first argument, indicating what is being copied:
307 .Bl -tag -width COPYFILE_RECURSE_DIR_CLEANUP
308 .It Dv COPYFILE_RECURSE_FILE
309 The object being copied is a file (or, rather,
310 something other than a directory).
311 .It Dv COPYFILE_RECURSE_DIR
312 The object being copied is a directory, and is being
313 entered. (That is, none of the filesystem objects contained
314 within the directory have been copied yet.)
315 .It Dv COPYFILE_RECURSE_DIR_CLEANUP
316 The object being copied is a directory, and all of the
317 objects contained have been copied. At this stage, the destination directory
318 being copied will have any extra permissions that were added to
319 allow the copying will be removed.
320 .It Dv COPYFILE_RECURSE_ERROR
321 There was an error in processing an element of the source hierarchy;
324 returns an error or unknown file type.
325 (Currently, the second argument to the call-back function will always
331 The second argument to the call-back function will indicate
332 the stage of the copy, and will be one of the following values:
333 .Bl -tag -width COPYFILE_FINISH
334 .It Dv COPYFILE_START
335 Before copying has begun. The third
336 parameter will be a newly-created
338 object with the call-back function and context pre-loaded.
339 .It Dv COPYFILE_FINISH
340 After copying has successfully finished.
342 Indicates an error has happened at some stage. If the
343 first argument to the call-back function is
344 .Dv COPYFILE_RECURSE_ERROR ,
345 then an error occurred while processing the source hierarchy;
346 otherwise, it will indicate what type of object was being copied,
349 will be set to indicate the error.
353 parameters are the source and destination paths that
354 are to be copied (or have been copied, or failed to copy, depending on
355 the second argument).
357 The last argument to the call-back function will be the value
359 .Dv COPYFILE_STATE_STATUS_CTX ,
362 The call-back function is required to return one of the following
364 .Bl -tag -width COPYFILE_CONTINUE
365 .It Dv COPYFILE_CONTINUE
366 The copy will continue as expected.
368 This object will be skipped, and the next object will
369 be processed. (Note that, when entering a directory.
372 from the call-back function will prevent the contents
373 of the directory from being copied.)
375 The entire copy is aborted at this stage. Any filesystem
376 objects created up to this point will remain.
383 The call-back function must always return one of the values listed
384 above; if not, the results are undefined.
386 The call-back function will be called twice for each object
387 (and an additional two times for directory cleanup); the first
392 the second time, that value will be either
396 to indicate a successful completion, or an error during
398 In the event of an error, the
400 value will be set appropriately.
404 .Dv COPYFILE_UNPACK ,
408 flags are not used during a recursive copy, and will result
409 in an error being returned.
410 .Sh Progress Callback
411 In addition to the recursive callbacks described above,
415 will also use a callback to report data (e.g.,
417 progress. If given, the callback will be invoked on each
419 call. The first argument to the callback function will be
420 .Dv COPYFILE_COPY_DATA .
421 The second argument will either be
422 .Dv COPYFILE_PROGRESS
423 (indicating that the write was successful), or
425 (indicating that there was an error of some sort).
427 The amount of data bytes copied so far can be retrieved using
428 .Fn copyfile_state_get ,
430 .Dv COPYFILE_STATE_COPIED
431 requestor (the argument type is a pointer to
434 When copying extended attributes, the first argument to the
435 callback function will be
436 .Dv COPYFILE_COPY_XATTR .
437 The other arguments will be as described for
438 .Dv COPYFILE_COPY_DATA ;
439 the name of the extended attribute being copied may be
441 .Fn copyfile_state_get
443 .Dv COPYFILE_STATE_XATTRNAME .
446 the callback may be called with
448 for each of the extended attributes first, followed by
449 .Dv COPYFILE_PROGRESS
450 before getting and packing the data for each
451 individual attribute, and then
453 when finished with each individual attribute.
456 may be called for all of the extended attributes, before
457 the first callback with
458 .Dv COPYFILE_PROGRESS
459 is invoked.) Any attribute skipped by returning
463 callback will not be placed into the packed output file.
465 The return value for the data callback must be one of
466 .Bl -tag -width COPYFILE_CONTINUE
467 .It Dv COPYFILE_CONTINUE
468 The copy will continue as expected.
469 (In the case of error, it will attempt to write the data again.)
471 The data copy will be aborted, but without error.
473 The data copy will be aborted; in the case of
474 .Dv COPYFILE_PROGRESS ,
484 parameters will be passed in, they may be
489 Except when given the
495 return less than 0 on error, and 0 on success.
496 All of the other functions return 0 on success, and less than 0
503 can copy symbolic links; there is a gap between when the source
504 link is examined and the actual copy is started, and this can
505 be a potential security risk, especially if the process has
508 When performing a recursive copy, if the source hierarchy
509 changes while the copy is occurring, the results are undefined.
512 does not reset the seek position for either source or destination.
513 This can result in the destination file being a different size
514 than the source file.
522 An invalid flag was passed in with
523 .Dv COPYFILE_RECURSIVE .
541 was a negative number.
543 A memory allocation failed.
545 The source file was not a directory, symbolic link, or regular file.
547 The copy was cancelled by callback.
549 In addition, both functions may set
551 via an underlying library or system call.
553 .Bd -literal -offset indent
554 /* Initialize a state variable */
556 s = copyfile_state_alloc();
557 /* Copy the data and extended attributes of one file to another */
558 copyfile("/tmp/f1", "/tmp/f2", s, COPYFILE_DATA | COPYFILE_XATTR);
559 /* Convert a file to an AppleDouble file for serialization */
560 copyfile("/tmp/f2", "/tmp/tmpfile", NULL, COPYFILE_ALL | COPYFILE_PACK);
561 /* Release the state variable */
562 copyfile_state_free(s);
563 /* A more complex way to call copyfile() */
564 s = copyfile_state_alloc();
565 copyfile_state_set(s, COPYFILE_STATE_SRC_FILENAME, "/tmp/foo");
566 /* One of src or dst must be set... rest can come from the state */
567 copyfile(NULL, "/tmp/bar", s, COPYFILE_ALL);
568 /* Now copy the same source file to another destination file */
569 copyfile(NULL, "/tmp/car", s, COPYFILE_ALL);
570 copyfile_state_free(s);
571 /* Remove extended attributes from a file */
572 copyfile("/dev/null", "/tmp/bar", NULL, COPYFILE_XATTR);
582 functions lack a way to set the input or output block size.
584 Recursive copies do not honor hard links.
588 API was introduced in Mac OS X 10.5.