CLONEFILE(2) System Calls Manual CLONEFILE(2)
NAME
clonefile – create copy on write clones of files
SYNOPSIS
#include <sys/attr.h>
#include <sys/clonefile.h>
int
clonefile(const char * src, const char * dst, int flags);
clonefileat(int src_dirfd, const char * src, int dst_dirfd,
const char * dst, int flags);
fclonefileat(int srcfd, int dst_dirfd, const char * dst, int flags);
LIMITATIONS
Cloning directories with these functions is strongly discouraged. Use
copyfile(3) to clone directories instead.
DESCRIPTION
The clonefile() function causes the named file src to be cloned to the
named file dst. The cloned file dst shares its data blocks with the src
file but has its own copy of attributes and extended attributes which are
identical to those of the named file src with the exceptions listed
below:
1. ownership information is set as it would be if dst was created by
openat(2) or mkdirat(2) or symlinkat(2) if the current user does not
have privileges to change ownership. If the optional flag
CLONE_NOOWNERCOPY is passed, the ownership information is the same
as if the the current user does not have privileges to change
ownership.
2. setuid and setgid bits are turned off in the mode bits for regular
files.
3. inherit target directory's access control lists. If the optional
flag CLONE_ACL is passed, it will additionally copy the ACLs from
the source file and also apply the inherited ACLs from the target
directory.
Subsequent writes to either the original or cloned file are private to
the file being modified (copy-on-write). The named file dst must not
exist for the call to be successful. Since the clonefile() system call
might not allocate new storage for data blocks, it is possible for a
subsequent overwrite of an existing data block to return ENOSPC. If src
names a directory, the directory hierarchy is cloned as if each item was
cloned individually. However, the use of clonefile(2) to clone directory
hierarchies is strongly discouraged. Use copyfile(3) instead for copying
directories.
The clonefileat() function is equivalent to clonefile() except in the
case where either src or dst specifies a relative path. If src is a
relative path, the file to be cloned is located relative to the directory
associated with the file descriptor src_dirfd instead of the current
working directory. If dst is a relative path, the same happens only
relative to the directory associated with dst_dirfd. If clonefileat() is
passed the special value AT_FDCWD in either the src_dirfd or dst_dirfd
parameters, the current working directory is used in the determination of
the file for the respective path parameter.
The fclonefileat() function is similar to clonefileat() except that the
source is identified by file descriptor srcfd rather than a path (as in
clonefile() or clonefileat() ).
The flags parameter specifies the options that can be passed. Options are
specified in the flags argument by or'ing the following values:
CLONE_NOFOLLOW Don't follow the src file if it is a symbolic link
(applicable only if the source is not a directory). The
symbolic link is itself cloned if src names a symbolic
link.
CLONE_NOOWNERCOPY Don't copy ownership information from the source when
run called with superuser privileges. The symbolic
link is itself cloned if src names a symbolic link.
CLONE_ACL Copy ACLs from the source file.
The clonefile(), clonefileat() and fclonefileat() functions are expected
to be atomic i.e. the system call will result all new objects being
created successfully or no new objects will be created. POSIX conforming
applications cannot use clonefile().
RETURN VALUES
Upon successful completion, clonefile() returns 0. Otherwise, a value of
-1 is returned and errno is set to indicate the error.
COMPATIBILITY
Not all volumes support clonefile(). A volume can be tested for
clonefile() support by using getattrlist(2) to get the volume
capabilities attribute ATTR_VOL_CAPABILITIES, and then testing the
VOL_CAP_INT_CLONE flag.
ERRORS
The clonefile() function will fail if:
[EACCES] Read permissions are denied on the source or write
permissions are on the destination parent.
[ENOTSUP] The underlying filesystem does not support this call.
[EEXIST] The named file dst exists.
[EXDEV] src and dst are not on the same filesystem.
[EINVAL] The value of the flags parameter is invalid.
[ENOSPC] There is no free space remaining on the file system
containing the file.
[EIO] An I/O error occurred while reading from or writing to
the file system.
[EPERM] The calling process does not have appropriate
privileges.
[EPERM] src is the root of the Filesystem.
[ELOOP] A loop exists in symbolic links encountered during in
resolution of the src or dst path arguments.
[EROFS] The requested operation requires writing in a
directory on a read-only file system.
[ENAMETOOLONG] The length of a component of a pathname is longer than
{NAME_MAX}.
[ENOENT] A component of path src or the path dst does not name
an existing file or path is an empty string.
[ENOTDIR] A component of path prefix of either src or dst names
an existing file that is neither a directory nor a
symbolic link to a directory, or the path argument
contains at least one non <slash> character and ends
with one or more trailing <slash> characters and the
last pathname component names an existing file that is
neither a directory nor a symbolic link to a
directory.
[EDEADLK] A component of either pathname refers to a “dataless”
directory that requires materialization and the I/O
policy of the current thread or process disallows
dataless directory materialization (see
getiopolicy_np(3)).
[EDEADLK] The src pathname refers to a “dataless” file that must
be materialized before being cloned and the I/O policy
of the current thread or process disallows file
materialization (see getiopolicy_np(3)).
In addition, the clonefileat() or fclonefileat() functions may fail with
the following errors:
[EBADF] The src or dst argument does not specify an absolute
path and the src_dirfd or dst_dirfd argument is
neither AT_FDCWD nor a valid file descriptor open for
searching.
[ENOTDIR] The src or dst argument is not an absolute path and
src_dirfd or dst_dirfd is neither AT_FDCWD nor a file
descriptor associated with a directory.
SEE ALSO
copyfile(3) chown(2)
HISTORY
The clonefile(), clonefileat() and fclonefileat() function calls appeared
in OS X version 10.12
Darwin June 3, 2021 Darwin