--- name: "clonefileat" section: "2" platform: "macos" package: "xnu" version: "12377.121.6" release: "macOS 26.5" platforms: ["macos"] url: "https://new.carta.tech/clonefile" --- # clonefileat(2) create copy on write clones of files Part of [clonefile(2)](/clonefile/2.md). ## NAME **clonefile** – create copy on write clones of files ## SYNOPSIS **#include \** **#include \** *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)](/copyfile/3.md) 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)](/openat/2.md) or [mkdirat(2)](/mkdirat/2.md) or [symlinkat(2)](/symlinkat/2.md) 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)](/clonefile/2.md) to clone directory hierarchies is strongly discouraged. Use [copyfile(3)](/copyfile/3.md) 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. - CLONE\_NOFOLLOW\_ANY do not follow any symbolic links encountered during pathname resolution. An error is returned if a symlink is encountered before the last component of either *src* or *dst.* - CLONE\_RESOLVE\_BENEATH If *src* and *dst* does not reside in the hierarchy beneath the starting directory, an error is returned. 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)](/getattrlist/2.md) 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. - \[ELOOP\] If CLONE\_NOFOLLOW\_ANY option was passed and a symbolic link was encountered in translating the pathname of either *src* or *dst* arguments. - \[ENOTCAPABLE\] If CLONE\_RESOLVE\_BENEATH was passed and either *src* or *dst* does not reside in the directory hierarchy beneath the starting directory. - \[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 \ character and ends with one or more trailing \ 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)](/getiopolicy_np/3.md)). - \[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)](/getiopolicy_np/3.md)). 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)](/copyfile/3.md) [chown(2)](/chown/2.md) ## HISTORY The **clonefile**(), **clonefileat**() and **fclonefileat**() function calls appeared in OS X version 10.12