]> git.saurik.com Git - apple/copyfile.git/blob - copyfile.3
copyfile-103.tar.gz
[apple/copyfile.git] / 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 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_NOFOLLOW
182 This is a convenience macro, equivalent to
183 .Dv (COPYFILE_NOFOLLOW_DST|COPYFILE_NOFOLLOW_SRC) .
184 .El
185 .Pp
186 The
187 .Fn copyfile_state_get
188 and
189 .Fn copyfile_state_set
190 functions can be used to manipulate the
191 .Ft copyfile_state_t
192 object returned by
193 .Fn copyfile_state_alloc .
194 In both functions, the
195 .Va dst
196 parameter's type depends on the
197 .Va flag
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)
203 file.
204 If this has not been initialized yet, the value will be -2.
205 The
206 .Va dst
207 (for
208 .Fn copyfile_state_get )
209 and
210 .Va src
211 (for
212 .Fn copyfile_state_set )
213 parameters are pointers to
214 .Vt int .
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
219 .Dv NULL .
220 For
221 .Fn copyfile_state_set ,
222 the
223 .Va src
224 parameter is a pointer to a C string
225 (i.e.,
226 .Vt char* );
227 .Fn copyfile_state_set
228 makes a private copy of this string.
229 For
230 .Fn copyfile_state_get
231 function, the
232 .Va dst
233 parameter is a pointer to a pointer to a C string
234 (i.e.,
235 .Vt char** );
236 the returned value is a pointer to the
237 .Va state 's
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).
242 The
243 .Va src
244 parameter is a pointer to a function of type
245 .Vt copyfile_callback_t
246 (see above).
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).
250 The
251 .Va src
252 parameter is a
253 .Vt void\ * .
254 .It Dv COPYFILE_STATE_QUARANTINE
255 Get or set the quarantine information with the source file.
256 The
257 .Va src
258 parameter is a pointer to an opaque
259 object (type
260 .Vt void\ *
261 ).
262 .It Dv COPYFILE_STATE_COPIED
263 Get the number of data bytes copied so far.
264 (Only valid for
265 .Fn copyfile_state_get ;
266 see below for more details about callbacks.)
267 The
268 .Va dst
269 parameter is a pointer to
270 .Vt off_t
271 (type
272 .Vt off_t\ * ).
273 .It Dv COPYFILE_STATE_XATTRNAME
274 Get the name of the extended attribute during a callback
275 for
276 .Dv COPYFILE_COPY_XATTR
277 (see below for details). This field cannot be set,
278 and may be
279 .Dv NULL .
280 .El
281 .Sh Recursive Copies
282 When given the
283 .Dv COPYFILE_RECURSIVE
284 flag,
285 .Fn copyfile
286 (but not
287 .Fn fcopyfile )
288 will use the
289 .Xr fts 3
290 functions to recursively descend into the source file-system object.
291 It then calls
292 .Fn copyfile
293 on each of the entries it finds that way.
294 If a call-back function is given (using
295 .Fn copyfile_state_set
296 and
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
303 some final cleanup.)
304 .Pp
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;
322 this happens when
323 .Xr fts 3
324 returns an error or unknown file type.
325 (Currently, the second argument to the call-back function will always
326 be
327 .Dv COPYFILE_ERR
328 in this case.)
329 .El
330 .Pp
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
337 .Vt copyfile_state_t
338 object with the call-back function and context pre-loaded.
339 .It Dv COPYFILE_FINISH
340 After copying has successfully finished.
341 .It Dv COPYFILE_ERR
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,
347 and
348 .Dv errno
349 will be set to indicate the error.
350 .El
351 .Pp
352 The fourth and fifth
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).
356 .Pp
357 The last argument to the call-back function will be the value
358 set by
359 .Dv COPYFILE_STATE_STATUS_CTX ,
360 if any.
361 .Pp
362 The call-back function is required to return one of the following
363 values:
364 .Bl -tag -width COPYFILE_CONTINUE
365 .It Dv COPYFILE_CONTINUE
366 The copy will continue as expected.
367 .It Dv COPYFILE_SKIP
368 This object will be skipped, and the next object will
369 be processed. (Note that, when entering a directory.
370 returning
371 .Dv COPYFILE_SKIP
372 from the call-back function will prevent the contents
373 of the directory from being copied.)
374 .It Dv COPYFILE_QUIT
375 The entire copy is aborted at this stage. Any filesystem
376 objects created up to this point will remain.
377 .Fn copyfile
378 will return -1, but
379 .Dv errno
380 will be unmodified.
381 .El
382 .Pp
383 The call-back function must always return one of the values listed
384 above; if not, the results are undefined.
385 .Pp
386 The call-back function will be called twice for each object
387 (and an additional two times for directory cleanup); the first
388 call will have a
389 .Ar stage
390 parameter of
391 .Dv COPYFILE_START ;
392 the second time, that value will be either
393 .Dv COPYFILE_FINISH
394 or
395 .Dv COPYFILE_ERR
396 to indicate a successful completion, or an error during
397 processing.
398 In the event of an error, the
399 .Dv errno
400 value will be set appropriately.
401 .Pp
402 The
403 .Dv COPYFILE_PACK ,
404 .Dv COPYFILE_UNPACK ,
405 .Dv COPYFILE_MOVE ,
406 and
407 .Dv COPYFILE_UNLINK
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,
412 .Fn copyfile
413 and
414 .Fn fcopyfile
415 will also use a callback to report data (e.g.,
416 .Dv COPYFILE_DATA )
417 progress. If given, the callback will be invoked on each
418 .Xr write 2
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
424 .Dv COPYFILE_ERR
425 (indicating that there was an error of some sort).
426 .Pp
427 The amount of data bytes copied so far can be retrieved using
428 .Fn copyfile_state_get ,
429 with the
430 .Dv COPYFILE_STATE_COPIED
431 requestor (the argument type is a pointer to
432 .Vt off_t ).
433 .Pp
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
440 retrieved using
441 .Fn copyfile_state_get
442 and the parameter
443 .Dv COPYFILE_STATE_XATTRNAME .
444 When using
445 .Dv COPYFILE_PACK ,
446 the callback may be called with
447 .Dv COPYFILE_START
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
452 .Dv COPYFILE_FINISH
453 when finished with each individual attribute.
454 (That is,
455 .Dv COPYFILE_START
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
460 .Dv COPYFILE_SKIP
461 from the
462 .Dv COPYFILE_START
463 callback will not be placed into the packed output file.
464 .Pp
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.)
470 .It Dv COPYFILE_SKIP
471 The data copy will be aborted, but without error.
472 .It Dv COPYFILE_QUIT
473 The data copy will be aborted; in the case of
474 .Dv COPYFILE_PROGRESS ,
475 .Dv errno
476 will be set to
477 .Dv ECANCELED .
478 .El
479 .Pp
480 While the
481 .Va src
482 and
483 .Va dst
484 parameters will be passed in, they may be
485 .Dv NULL
486 in the case of
487 .Fn fcopyfile .
488 .Sh RETURN VALUES
489 Except when given the
490 .Dv COPYFILE_CHECK
491 flag,
492 .Fn copyfile
493 and
494 .Fn fcopyfile
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
497 on error.
498 .Sh WARNING
499 Both
500 .Fn copyfile
501 and
502 .Fn fcopyfile
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
506 elevated privileges.
507 .Pp
508 When performing a recursive copy, if the source hierarchy
509 changes while the copy is occurring, the results are undefined.
510 .Pp
511 .Fn fcopyfile
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.
515 .Sh ERRORS
516 .Fn copyfile
517 and
518 .Fn fcopyfile
519 will fail if:
520 .Bl -tag -width Er
521 .It Bq Er EINVAL
522 An invalid flag was passed in with
523 .Dv COPYFILE_RECURSIVE .
524 .It Bq Er EINVAL
525 The
526 .Va from
527 or
528 .Va to
529 parameter to
530 .Fn copyfile
531 was a
532 .Dv NULL
533 pointer.
534 .It Bq Er EINVAL
535 The
536 .Va from
537 or
538 .Va to
539 parameter to
540 .Fn copyfile
541 was a negative number.
542 .It Bq Er ENOMEM
543 A memory allocation failed.
544 .It Bq Er ENOTSUP
545 The source file was not a directory, symbolic link, or regular file.
546 .It Bq Er ECANCELED
547 The copy was cancelled by callback.
548 .El
549 In addition, both functions may set
550 .Dv errno
551 via an underlying library or system call.
552 .Sh EXAMPLES
553 .Bd -literal -offset indent
554 /* Initialize a state variable */
555 copyfile_state_t s;
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);
573 .Ed
574 .Sh SEE ALSO
575 .Xr listxattr 2 ,
576 .Xr getxattr 2 ,
577 .Xr setxattr 2 ,
578 .Xr acl 3
579 .Sh BUGS
580 Both
581 .Fn copyfile
582 functions lack a way to set the input or output block size.
583 .Pp
584 Recursive copies do not honor hard links.
585 .Sh HISTORY
586 The
587 .Fn copyfile
588 API was introduced in Mac OS X 10.5.