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. (Metadata 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() func-tion function
tion 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 descriptors 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, modification 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 provided:
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 argument) 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 AppleDouble-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()) parame-ters parameters
ters are pointers 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 private 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 functions 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 num-ber number
ber ( 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
|