Documentation Archive Developer
Search
ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages

 

This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).



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);

DESCRIPTION
     These functions are used to copy a file's data and/or metadata.  (Meta-data (Metadata
     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 descriptors
     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 modification
                     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: provided:
     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_CHECK         Return a bitmask (corresponding to the flags argu-ment) argument)
                            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 AppleDouble-format
                            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 (remove) the from file.  (This is only
                            applicable for the copyfile() function.)

     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 pointers
                                  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 private
                                  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_QUARANTINE    Get or set the quarantine information with
                                  the source file.  The src parameter is a
                                  pointer to a qtn_file_t object (see
                                  <quarantine.h> ). In the case of
                                  COPYFILE_STATE_SET, the object is cloned; in
                                  the case of COPYFILE_STATE_GET, the object
                                  is simply returned, and it is up to the
                                  caller to clone it if desired.

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 functions
     tions return 0 on success, and less than 0 on error.

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

     [EINVAL]           Either the from or to parameter was a NULL pointer (
                        copyfile(),) or a negative number ( fcopyfile().)

     [ENOMEM]           A memory allocation failed.

     [ENOTSUP]          The source file was not a directory, symbolic link, or
                        regular file.
     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);

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

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

BSD                             April 27, 2006                             BSD