.It Dv COPYFILE_PACK
Serialize the
.Va from
-file. The
+file.
+The
.Va to
file is an AppleDouble-format file.
.It Dv COPYFILE_UNPACK
Unserialize the
.Va from
-file. The
+file.
+The
.Va from
file is an AppleDouble-format file; the
.Va to
.Fn copyfile
function.) No error is returned if
.Xr remove 3
-fails. Note that
+fails.
+Note that
.Xr remove 3
removes a symbolic link itself, not the
target of the link.
| COPYFILE_NOFOLLOW_SRC).
Note that if cloning is successful, progress callbacks will not be invoked.
Note also that there is no support for cloning directories: if a directory is provided as the source,
-an error will be returned. Since this flag implies COPYFILE_NOFOLLOW_SRC, symbolic links themselves will
-be cloned instead of their targets.
+an error will be returned.
+Since this flag implies COPYFILE_NOFOLLOW_SRC, symbolic links themselves will be cloned instead of their targets.
(This is only applicable for the
.Fn copyfile
function.)
| COPYFILE_NOFOLLOW_SRC).
Note that if cloning is successful, progress callbacks will not be invoked.
Note also that there is no support for cloning directories: if a directory is provided as the source and
-COPYFILE_CLONE_FORCE is not passed, this will instead copy the directory. Since this flag implies COPYFILE_NOFOLLOW_SRC,
-symbolic links themselves will be cloned instead of their targets. Recursive copying however is
-supported, see below for more information.
+COPYFILE_CLONE_FORCE is not passed, this will instead copy the directory.
+Since this flag implies COPYFILE_NOFOLLOW_SRC, symbolic links themselves will be cloned instead of their targets.
+Recursive copying however is supported, see below for more information.
(This is only applicable for the
.Fn copyfile
function.)
This is a convenience macro, equivalent to
.Dv (COPYFILE_NOFOLLOW_DST | COPYFILE_NOFOLLOW_SRC) .
.It Dv COPYFILE_RUN_IN_PLACE
-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.
+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.
.It Dv COPYFILE_PRESERVE_DST_TRACKED
Preserve the UF_TRACKED flag at
.Va to
when copying metadata, regardless of whether
.Va from
-has it set. This flag is used in conjunction with COPYFILE_STAT, or COPYFILE_CLONE (for its fallback case).
+has it set.
+This flag is used in conjunction with COPYFILE_STAT, or COPYFILE_CLONE (for its fallback case).
.El
.Pp
-Copying files into a directory is supported. If
+Copying files into a directory is supported.
+If
.Va to
is a directory,
.Va from
.It Dv COPYFILE_STATE_SRC_FILENAME
.It Dv COPYFILE_STATE_DST_FILENAME
Get or set the filename associated with the source (or destination)
-file. If it has not been initialized yet, the value will be
+file.
+If it has not been initialized yet, the value will be
.Dv NULL .
For
.Fn copyfile_state_set ,
within the directory have been copied yet.)
.It Dv COPYFILE_RECURSE_DIR_CLEANUP
The object being copied is a directory, and all of the
-objects contained have been copied. At this stage, the destination directory
+objects contained have been copied.
+At this stage, the destination directory
being copied will have any extra permissions that were added to
allow the copying will be removed.
.It Dv COPYFILE_RECURSE_ERROR
the stage of the copy, and will be one of the following values:
.Bl -tag -width COPYFILE_FINISH
.It Dv COPYFILE_START
-Before copying has begun. The third
-parameter will be a newly-created
+Before copying has begun.
+The third parameter will be a newly-created
.Vt copyfile_state_t
object with the call-back function and context pre-loaded.
.It Dv COPYFILE_FINISH
After copying has successfully finished.
.It Dv COPYFILE_ERR
-Indicates an error has happened at some stage. If the
-first argument to the call-back function is
+Indicates an error has happened at some stage.
+If the first argument to the call-back function is
.Dv COPYFILE_RECURSE_ERROR ,
then an error occurred while processing the source hierarchy;
otherwise, it will indicate what type of object was being copied,
The copy will continue as expected.
.It Dv COPYFILE_SKIP
This object will be skipped, and the next object will
-be processed. (Note that, when entering a directory.
-returning
+be processed.
+(Note that, when entering a directory, returning
.Dv COPYFILE_SKIP
from the call-back function will prevent the contents
of the directory from being copied.)
.It Dv COPYFILE_QUIT
-The entire copy is aborted at this stage. Any filesystem
+The entire copy is aborted at this stage.
+Any filesystem
objects created up to this point will remain.
.Fn copyfile
will return -1, but
.Dv COPYFILE_CLONE
flag (but not the
.Dv COPYFILE_CLONE_FORCE
-flag). A recursive clone operation invokes
+flag).
+A recursive clone operation invokes
.Fn copyfile
with
.Dv COPYFILE_CLONE
-on every entry found in the source file-system object. Because
+on every entry found in the source file-system object.
+Because
.Fn copyfile
does not allow the cloning of directories, a recursive clone will
instead copy any directory it finds (while cloning its contents).
.Va /
its contents are copied rather than the directory itself (like cp(1)).
The behavior of a recursive copy on a directory hierarchy also depends
-on the contents of the destination. If the destination is a directory,
-the source directory (or its contents, if the source path ends in a
+on the contents of the destination.
+If the destination is a directory, the source directory (or its contents,
+if the source path ends in a
.Va /
-) will be copied into it. If the destination exists but is not a
+) will be copied into it.
+If the destination exists but is not a
directory, and the source is a non-empty directory, the copy will fail;
the exact error set depends on the flags provided to
.Fn copyfile
.Fn fcopyfile
will also use a callback to report data (e.g.,
.Dv COPYFILE_DATA )
-progress. If given, the callback will be invoked on each
+progress.
+If given, the callback will be invoked on each
.Xr write 2
-call. The first argument to the callback function will be
+call.
+The first argument to the callback function will be
.Dv COPYFILE_COPY_DATA .
The second argument will either be
.Dv COPYFILE_PROGRESS
may be called for all of the extended attributes, before
the first callback with
.Dv COPYFILE_PROGRESS
-is invoked.) Any attribute skipped by returning
+is invoked.)
+Any attribute skipped by returning
.Dv COPYFILE_SKIP
from the
.Dv COPYFILE_START
does not reset the seek position for either source or destination.
This can result in the destination file being a different size
than the source file.
+.Sh EXAMPLES
+.Bd -literal -offset indent
+/* Initialize a state variable */
+copyfile_state_t s;
+s = copyfile_state_alloc();
+/* Copy the data and extended attributes of one file to another */
+copyfile("/tmp/f1", "/tmp/f2", s, COPYFILE_DATA | COPYFILE_XATTR);
+/* Convert a file to an AppleDouble file for serialization */
+copyfile("/tmp/f2", "/tmp/tmpfile", NULL, COPYFILE_ALL | COPYFILE_PACK);
+/* Release the state variable */
+copyfile_state_free(s);
+/* A more complex way to call copyfile() */
+s = copyfile_state_alloc();
+copyfile_state_set(s, COPYFILE_STATE_SRC_FILENAME, "/tmp/foo");
+/* One of src or dst must be set... rest can come from the state */
+copyfile(NULL, "/tmp/bar", s, COPYFILE_ALL);
+/* Now copy the same source file to another destination file */
+copyfile(NULL, "/tmp/car", s, COPYFILE_ALL);
+copyfile_state_free(s);
+/* Remove extended attributes from a file */
+copyfile("/dev/null", "/tmp/bar", NULL, COPYFILE_XATTR);
+.Ed
.Sh ERRORS
.Fn copyfile
and
In addition, both functions may set
.Dv errno
via an underlying library or system call.
-.Sh EXAMPLES
-.Bd -literal -offset indent
-/* Initialize a state variable */
-copyfile_state_t s;
-s = copyfile_state_alloc();
-/* Copy the data and extended attributes of one file to another */
-copyfile("/tmp/f1", "/tmp/f2", s, COPYFILE_DATA | COPYFILE_XATTR);
-/* Convert a file to an AppleDouble file for serialization */
-copyfile("/tmp/f2", "/tmp/tmpfile", NULL, COPYFILE_ALL | COPYFILE_PACK);
-/* Release the state variable */
-copyfile_state_free(s);
-/* A more complex way to call copyfile() */
-s = copyfile_state_alloc();
-copyfile_state_set(s, COPYFILE_STATE_SRC_FILENAME, "/tmp/foo");
-/* One of src or dst must be set... rest can come from the state */
-copyfile(NULL, "/tmp/bar", s, COPYFILE_ALL);
-/* Now copy the same source file to another destination file */
-copyfile(NULL, "/tmp/car", s, COPYFILE_ALL);
-copyfile_state_free(s);
-/* Remove extended attributes from a file */
-copyfile("/dev/null", "/tmp/bar", NULL, COPYFILE_XATTR);
-.Ed
.Sh SEE ALSO
-.Xr listxattr 2 ,
.Xr getxattr 2 ,
+.Xr listxattr 2 ,
.Xr setxattr 2 ,
.Xr acl 3
+.Sh HISTORY
+The
+.Fn copyfile
+API was introduced in Mac OS X 10.5.
.Sh BUGS
Both
.Fn copyfile
functions lack a way to set the input or output block size.
.Pp
Recursive copies do not honor hard links.
-.Sh HISTORY
-The
-.Fn copyfile
-API was introduced in Mac OS X 10.5.
projects / apple / copyfile.git / blobdiff