mdoc warning: Empty input line #67

CLONEFILE(2)                BSD 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);

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, extended attributes and ACL's
     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 owner-
          ship

     2.   setuid and setgid bits are turned off in the mode bits for regular
          files.

     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 sub-
     sequent 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 copyfile(3) is more appropriate
     for copying large directory hierarchies instead of clonefile(2)

     The clonefileat() function is equivalent to clonefile() except in the
     case where either src or dst specifies a relative path. If src is a rela-
     tive 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 rela-
     tive 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.

     The 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 con-
     forming 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 capabili-
     ties 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 privi-
                        leges.

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

     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 nei-
                        ther 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                         December 04, 2015                        Darwin