fcopyfile man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin logo
[printable version]

COPYFILE(3)		 BSD Library Functions Manual		   COPYFILE(3)

NAME
     copyfile, fcopyfile, copyfile_state_alloc, copyfile_state_free,
     copyfile_state_get, copyfile_state_set — copy a file

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <copyfile.h>

     int
     copyfile(const char *from, const char *to, copyfile_state_t state,
	 copyfile_flags_t flags);

     int
     fcopyfile(int from, int to, copyfile_state_t state,
	 copyfile_flags_t flags);

     copyfile_state_t
     copyfile_state_alloc(void);

     int
     copyfile_state_free(copyfile_state_t state);

     int
     copyfile_state_get(copyfile_state_t state, uint32_t flag, void * dst);

     int
     copyfile_state_set(copyfile_state_t state, uint32_t flag,
	 const void * src);

     typedef int
     (*copyfile_callback_t)(int what, int stage, copyfile_state_t state,
	 const char * src, const char * dst, void * ctx);

DESCRIPTION
     These functions are used to copy a file's data and/or metadata.  (Meta‐
     data consists of permissions, extended attributes, access control lists,
     and so forth.)

     The copyfile_state_alloc() function initializes a copyfile_state_t object
     (which is an opaque data type).  This object can be passed to copyfile()
     and fcopyfile(); copyfile_state_get() and copyfile_state_set() can be
     used to manipulate the state (see below).	The copyfile_state_free()
     function is used to deallocate the object and its contents.

     The copyfile() function can copy the named from file to the named to
     file; the fcopyfile() function does the same, but using the file descrip‐
     tors of already-opened files.  If the state parameter is the return value
     from copyfile_state_alloc(), then copyfile() and fcopyfile() will use the
     information from the state object; if it is NULL, then both functions
     will work normally, but less control will be available to the caller.
     The flags parameter controls which contents are copied:

     COPYFILE_ACL    Copy the source file's access control lists.

     COPYFILE_STAT   Copy the source file's POSIX information (mode, modifica‐
		     tion time, etc.).

     COPYFILE_XATTR  Copy the source file's extended attributes.

     COPYFILE_DATA   Copy the source file's data.

     These values may be or'd together; several convenience macros are pro‐
     vided:

     COPYFILE_SECURITY	Copy the source file's POSIX and ACL information;
			equivalent to (COPYFILE_STAT|COPYFILE_ACL).

     COPYFILE_METADATA	Copy the metadata; equivalent to
			(COPYFILE_SECURITY|COPYFILE_XATTR).

     COPYFILE_ALL	Copy the entire file; equivalent to
			(COPYFILE_METADATA|COPYFILE_DATA).

     The copyfile() and fcopyfile() functions can also have their behavior
     modified by the following flags:

     COPYFILE_RECURSIVE	    Causes copyfile() to recursively copy a hierarchy.
			    This flag is not used by fcopyfile(); see below
			    for more information.

     COPYFILE_CHECK	    Return a bitmask (corresponding to the flags argu‐
			    ment) indicating which contents would be copied;
			    no data are actually copied.  (E.g., if flags was
			    set to COPYFILE_CHECK|COPYFILE_METADATA, and the
			    from file had extended attributes but no ACLs, the
			    return value would be COPYFILE_XATTR .)

     COPYFILE_PACK	    Serialize the from file.  The to file is an Apple‐
			    Double-format file.

     COPYFILE_UNPACK	    Unserialize the from file.	The from file is an
			    AppleDouble-format file; the to file will have the
			    extended attributes, ACLs, resource fork, and
			    FinderInfo data from the to file, regardless of
			    the flags argument passed in.

     COPYFILE_EXCL	    Fail if the to file already exists.	 (This is only
			    applicable for the copyfile() function.)

     COPYFILE_NOFOLLOW_SRC  Do not follow the from file, if it is a symbolic
			    link.  (This is only applicable for the copyfile()
			    function.)

     COPYFILE_NOFOLLOW_DST  Do not follow the to file, if it is a symbolic
			    link.  (This is only applicable for the copyfile()
			    function.)

     COPYFILE_MOVE	    Unlink (using remove(3)) the from file.  (This is
			    only applicable for the copyfile() function.)  No
			    error is returned if remove(3) fails.  Note that
			    remove(3) removes a symbolic link itself, not the
			    target of the link.

     COPYFILE_UNLINK	    Unlink the to file before starting.	 (This is only
			    applicable for the copyfile() function.)

     COPYFILE_NOFOLLOW	    This is a convenience macro, equivalent to
			    (COPYFILE_NOFOLLOW_DST|COPYFILE_NOFOLLOW_SRC).

     The copyfile_state_get() and copyfile_state_set() functions can be used
     to manipulate the copyfile_state_t object returned by
     copyfile_state_alloc().  In both functions, the dst parameter's type
     depends on the flag parameter that is passed in.

     COPYFILE_STATE_SRC_FD

     COPYFILE_STATE_DST_FD	  Get or set the file descriptor associated
				  with the source (or destination) file.  If
				  this has not been initialized yet, the value
				  will be -2.  The dst (for
				  copyfile_state_get()) and src (for
				  copyfile_state_set()) parameters are point‐
				  ers to int.

     COPYFILE_STATE_SRC_FILENAME

     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
				  NULL.	 For copyfile_state_set(), the src
				  parameter is a pointer to a C string (i.e.,
				  char* ); copyfile_state_set() makes a pri‐
				  vate copy of this string.  For
				  copyfile_state_get() function, the dst
				  parameter is a pointer to a pointer to a C
				  string (i.e., char** ); the returned value
				  is a pointer to the state 's copy, and must
				  not be modified or released.

     COPYFILE_STATE_STATUS_CB	  Get or set the callback status function
				  (currently only used for recursive copies;
				  see below for details).  The src parameter
				  is a pointer to a function of type
				  copyfile_callback_t (see above).

     COPYFILE_STATE_STATUS_CTX	  Get or set the context parameter for the
				  status call-back function (see below for
				  details).  The src parameter is a void *.

     COPYFILE_STATE_QUARANTINE	  Get or set the quarantine information with
				  the source file.  The src parameter is a
				  pointer to an opaque object (type void * ).

     COPYFILE_STATE_COPIED	  Get the number of data bytes copied so far.
				  (Only valid for copyfile_state_get(); see
				  below for more details about callbacks.)
				  The dst parameter is a pointer to off_t
				  (type off_t * ).

     COPYFILE_STATE_XATTRNAME	  Get the name of the extended attribute dur‐
				  ing a callback for COPYFILE_COPY_XATTR (see
				  below for details).  This field cannot be
				  set, and may be NULL.

Recursive Copies
     When given the COPYFILE_RECURSIVE flag, copyfile() (but not fcopyfile())
     will use the fts(3) functions to recursively descend into the source
     file-system object.  It then calls copyfile() on each of the entries it
     finds that way.  If a call-back function is given (using
     copyfile_state_set() and COPYFILE_STATE_STATUS_CB ), the call-back func‐
     tion will be called four times for each directory object, and twice for
     all other objects.	 (Each directory will be examined twice, once on entry
     -- before copying each of the objects contained in the directory -- and
     once on exit -- after copying each object contained in the directory, in
     order to perform some final cleanup.)

     The call-back function will have one of the following values as the first
     argument, indicating what is being copied:

     COPYFILE_RECURSE_FILE	   The object being copied is a file (or,
				   rather, something other than a directory).

     COPYFILE_RECURSE_DIR	   The object being copied is a directory, and
				   is being entered.  (That is, none of the
				   filesystem objects contained within the
				   directory have been copied yet.)

     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 being copied will have any extra
				   permissions that were added to allow the
				   copying will be removed.

     COPYFILE_RECURSE_ERROR	   There was an error in processing an element
				   of the source hierarchy; this happens when
				   fts(3) returns an error or unknown file
				   type.  (Currently, the second argument to
				   the call-back function will always be
				   COPYFILE_ERR in this case.)

     The second argument to the call-back function will indicate the stage of
     the copy, and will be one of the following values:

     COPYFILE_START   Before copying has begun.	 The third parameter will be a
		      newly-created copyfile_state_t object with the call-back
		      function and context pre-loaded.

     COPYFILE_FINISH  After copying has successfully finished.

     COPYFILE_ERR     Indicates an error has happened at some stage.  If the
		      first argument to the call-back function is
		      COPYFILE_RECURSE_ERROR, then an error occurred while
		      processing the source hierarchy; otherwise, it will
		      indicate what type of object was being copied, and errno
		      will be set to indicate the error.

     The fourth and fifth parameters are the source and destination paths that
     are to be copied (or have been copied, or failed to copy, depending on
     the second argument).

     The last argument to the call-back function will be the value set by
     COPYFILE_STATE_STATUS_CTX, if any.

     The call-back function is required to return one of the following values:

     COPYFILE_CONTINUE	The copy will continue as expected.

     COPYFILE_SKIP	This object will be skipped, and the next object will
			be processed.  (Note that, when entering a directory.
			returning COPYFILE_SKIP from the call-back function
			will prevent the contents of the directory from being
			copied.)

     COPYFILE_QUIT	The entire copy is aborted at this stage.  Any
			filesystem objects created up to this point will
			remain.	 copyfile() will return -1, but errno will be
			unmodified.

     The call-back function must always return one of the values listed above;
     if not, the results are undefined.

     The call-back function will be called twice for each object (and an addi‐
     tional two times for directory cleanup); the first call will have a stage
     parameter of COPYFILE_START; the second time, that value will be either
     COPYFILE_FINISH or COPYFILE_ERR to indicate a successful completion, or
     an error during processing.  In the event of an error, the errno value
     will be set appropriately.

     The COPYFILE_PACK, COPYFILE_UNPACK, COPYFILE_MOVE, and COPYFILE_UNLINK
     flags are not used during a recursive copy, and will result in an error
     being returned.

Progress Callback
     In addition to the recursive callbacks described above, copyfile() and
     fcopyfile() will also use a callback to report data (e.g., COPYFILE_DATA)
     progress.	If given, the callback will be invoked on each write(2) call.
     The first argument to the callback function will be COPYFILE_COPY_DATA.
     The second argument will either be COPYFILE_PROGRESS (indicating that the
     write was successful), or COPYFILE_ERR (indicating that there was an
     error of some sort).

     The amount of data bytes copied so far can be retrieved using
     copyfile_state_get(), with the COPYFILE_STATE_COPIED requestor (the argu‐
     ment type is a pointer to off_t ).

     When copying extended attributes, the first argument to the callback
     function will be COPYFILE_COPY_XATTR.  The other arguments will be as
     described for COPYFILE_COPY_DATA; the name of the extended attribute
     being copied may be retrieved using copyfile_state_get() and the parame‐
     ter COPYFILE_STATE_XATTRNAME.  When using COPYFILE_PACK, the callback may
     be called with COPYFILE_START for each of the extended attributes first,
     followed by COPYFILE_PROGRESS before getting and packing the data for
     each individual attribute, and then COPYFILE_FINISH when finished with
     each individual attribute.	 (That is, COPYFILE_START may be called for
     all of the extended attributes, before the first callback with
     COPYFILE_PROGRESS is invoked.)  Any attribute skipped by returning
     COPYFILE_SKIP from the COPYFILE_START callback will not be placed into
     the packed output file.

     The return value for the data callback must be one of

     COPYFILE_CONTINUE	The copy will continue as expected.  (In the case of
			error, it will attempt to write the data again.)

     COPYFILE_SKIP	The data copy will be aborted, but without error.

     COPYFILE_QUIT	The data copy will be aborted; in the case of
			COPYFILE_PROGRESS, errno will be set to ECANCELED.

     While the src and dst parameters will be passed in, they may be NULL in
     the case of fcopyfile().

RETURN VALUES
     Except when given the COPYFILE_CHECK flag, copyfile() and fcopyfile()
     return less than 0 on error, and 0 on success.  All of the other func‐
     tions return 0 on success, and less than 0 on error.

WARNING
     Both copyfile() and fcopyfile() can copy symbolic links; there is a gap
     between when the source link is examined and the actual copy is started,
     and this can be a potential security risk, especially if the process has
     elevated privileges.

     When performing a recursive copy, if the source hierarchy changes while
     the copy is occurring, the results are undefined.

     fcopyfile() does not reset the seek position for either source or desti‐
     nation.  This can result in the destination file being a different size
     than the source file.

ERRORS
     copyfile() and fcopyfile() will fail if:

     [EINVAL]		An invalid flag was passed in with COPYFILE_RECURSIVE.

     [EINVAL]		The from or to parameter to copyfile() was a NULL
			pointer.

     [EINVAL]		The from or to parameter to copyfile() was a negative
			number.

     [ENOMEM]		A memory allocation failed.

     [ENOTSUP]		The source file was not a directory, symbolic link, or
			regular file.

     [ECANCELED]	The copy was cancelled by callback.
     In addition, both functions may set errno via an underlying library or
     system call.

EXAMPLES
	   /* 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);

SEE ALSO
     listxattr(2), getxattr(2), setxattr(2), acl(3)

BUGS
     Both copyfile() functions lack a way to set the input or output block
     size.

     Recursive copies do not honor hard links.

HISTORY
     The copyfile() API was introduced in Mac OS X 10.5.

BSD				April 27, 2006				   BSD
[top]

List of man pages available for Darwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net