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

NAME
     ccooppyyffiillee, ffccooppyyffiillee, ccooppyyffiilleessttaatteeaalllloocc, ccooppyyffiilleessttaatteeffrreeee,
     ccooppyyffiilleessttaatteeggeett, ccooppyyffiilleessttaatteesseett - copy a file

LLIIBBRRAARRYY
     Standard C Library (libc, -lc)

SYNOPSIS
     ##iinncclluuddee <>

     int
     ccooppyyffiillee(const char *from, const char *to, copyfilestatet state,
         copyfileflagst flags);

     int
     ffccooppyyffiillee(int from, int to, copyfilestatet state,
         copyfileflagst flags);

     copyfilestatet
     ccooppyyffiilleessttaatteeaalllloocc(void);

     int
     ccooppyyffiilleessttaatteeffrreeee(copyfilestatet state);

     int
     ccooppyyffiilleessttaatteeggeett(copyfilestatet state, uint32t flag, void * dst);

     int
     ccooppyyffiilleessttaatteesseett(copyfilestatet state, uint32t flag,
         const void * src);

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 ccooppyyffiilleessttaatteeaalllloocc() function initializes a copyfilestatet object
     (which is an opaque data type).  This object can be passed to ccooppyyffiillee()
     and ffccooppyyffiillee(); ccooppyyffiilleessttaatteeggeett() and ccooppyyffiilleessttaatteesseett() can be
     used to manipulate the state (see below).  The ccooppyyffiilleessttaatteeffrreeee()
     function is used to deallocate the object and its contents.

     The ccooppyyffiillee() function can copy the named from file to the named to
     file; the ffccooppyyffiillee() function does the same, but using the file descrip-
     tors of already-opened files.  If the state parameter is the return value
     from ccooppyyffiilleessttaatteeaalllloocc(), then ccooppyyffiillee() and ffccooppyyffiillee() 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:

     COPYFILEACL    Copy the source file's access control lists.

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

     COPYFILEXATTR  Copy the source file's extended attributes.

     COPYFILEDATA   Copy the source file's data.

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

     COPYFILESECURITY  Copy the source file's POSIX and ACL information;
                        equivalent to (COPYFILESTAT|COPYFILEACL).

     COPYFILEMETADATA  Copy the metadata; equivalent to
                        (COPYFILESECURITY|COPYFILEXATTR).

     COPYFILEALL       Copy the entire file; equivalent to
                        (COPYFILEMETADATA|COPYFILEDATA).

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

     COPYFILECHECK         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 COPYFILECHECK|COPYFILEMETADATA, and the
                            from file had extended attributes but no ACLs, the
                            return value would be COPYFILEXATTR .)

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

     COPYFILEUNPACK        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.

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

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

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

     COPYFILEMOVE          Unlink (remove) the from file.  (This is only
                            applicable for the ccooppyyffiillee() function.)

     COPYFILEUNLINK        Unlink the to file before starting.  (This is only
                            applicable for the ccooppyyffiillee() function.)

     COPYFILENOFOLLOW      This is a convenience macro, equivalent to
                            (COPYFILENOFOLLOWDST|COPYFILENOFOLLOWSRC).

     The ccooppyyffiilleessttaatteeggeett() and ccooppyyffiilleessttaatteesseett() functions can be used
     to manipulate the copyfilestatet object returned by
     ccooppyyffiilleessttaatteeaalllloocc().  In both functions, the dst parameter's type
     depends on the flag parameter that is passed in.

     COPYFILESTATESRCFD

     COPYFILESTATEDSTFD        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
                                  ccooppyyffiilleessttaatteeggeett()) and src (for
                                  ccooppyyffiilleessttaatteesseett()) parameters are point-
                                  ers to int.

     COPYFILESTATESRCFILENAME

     COPYFILESTATEDSTFILENAME  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 ccooppyyffiilleessttaatteesseett(), the src
                                  parameter is a pointer to a C string (i.e.,
                                  char* ); ccooppyyffiilleessttaatteesseett() makes a pri-
                                  vate copy of this string.  For
                                  ccooppyyffiilleessttaatteeggeett() 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.

     COPYFILESTATEQUARANTINE    Get or set the quarantine information with
                                  the source file.  The src parameter is a
                                  pointer to a qtnfilet object (see
                                   ). In the case of
                                  COPYFILESTATESET, the object is cloned; in
                                  the case of COPYFILESTATEGET, the object
                                  is simply returned, and it is up to the
                                  caller to clone it if desired.

RETURN VALUES
     Except when given the COPYFILECHECK flag, ccooppyyffiillee() and ffccooppyyffiillee()
     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.

EERRRROORRSS
     ccooppyyffiillee() and ffccooppyyffiillee() will fail if:

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

     [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.

EEXXAAMMPPLLEESS
           /* Initialize a state variable */
           copyfilestatet s;
           s = copyfilestatealloc();
           /* Copy the data and extended attributes of one file to another */
           copyfile("/tmp/f1", "/tmp/f2", s, COPYFILEDATA | COPYFILEXATTR);
           /* Convert a file to an AppleDouble file for serialization */
           copyfile("/tmp/f2", "/tmp/tmpfile", NULL, COPYFILEALL | COPYFILEPACK);
           /* Release the state variable */
           copyfilestatefree(s);
           /* A more complex way to call copyfile() */
           s = copyfilestatealloc();
           copyfilestateset(s, COPYFILESTATESRCFILENAME, "/tmp/foo");
           /* One of src or dst must be set... rest can come from the state */
           copyfile(NULL, "/tmp/bar", s, COPYFILEALL);
           /* Now copy the same source file to another destination file */
           copyfile(NULL, "/tmp/car", s, COPYFILEALL);
           copyfilestatefree(s);

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

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

BSD                             April 27, 2006                             BSD