X-Git-Url: https://git.saurik.com/apple/copyfile.git/blobdiff_plain/62b275d9547c3d23186feb0825fa54e9bb3be954..85b8a2cb94f73769e5f566efbb1f194a70d37e6d:/copyfile.3

diff --git a/copyfile.3 b/copyfile.3
index 55d4454..08d07a2 100644
--- a/copyfile.3
+++ b/copyfile.3
@@ -125,13 +125,15 @@ file had extended attributes but no ACLs, the return value would be
 .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
@@ -168,7 +170,8 @@ file.  (This is only applicable for the
 .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.
@@ -185,8 +188,8 @@ This flag is equivalent to (COPYFILE_EXCL | COPYFILE_ACL | COPYFILE_STAT | COPYF
 | 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.)
@@ -197,9 +200,9 @@ This flag is equivalent to (COPYFILE_EXCL | COPYFILE_ACL | COPYFILE_STAT | COPYF
 | 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.)
@@ -216,16 +219,19 @@ if sparse copying cannot be performed for any reason; otherwise, an error is ret
 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
@@ -269,7 +275,8 @@ parameters are pointers to
 .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 ,
@@ -385,7 +392,8 @@ entered.  (That is, none of the filesystem objects contained
 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
@@ -403,15 +411,15 @@ The second argument to the call-back function will indicate
 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,
@@ -437,13 +445,14 @@ values:
 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
@@ -474,11 +483,13 @@ Note that recursive cloning is also supported with the
 .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).
@@ -503,10 +514,12 @@ Note that if the source path ends in a
 .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
@@ -518,9 +531,11 @@ and
 .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
@@ -560,7 +575,8 @@ when finished with each individual attribute.
 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
@@ -621,6 +637,28 @@ changes while the copy is occurring, the results are undefined.
 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
@@ -688,40 +726,18 @@ parameter.
 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.