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