search..
No manual entry for -- in section 2const
FICLONE(2const)							FICLONE(2const)

NAME
       FICLONE,	 FICLONERANGE  -  share	 some the data of one file with another
       file

LIBRARY
       Standard C library (libc, -lc)

SYNOPSIS
       #include <linux/fs.h>  /* Definition of FICLONE* constants */
       #include <sys/ioctl.h>

       int ioctl(int dest_fd, FICLONERANGE, struct file_clone_range *arg);
       int ioctl(int dest_fd, FICLONE, int src_fd);

DESCRIPTION
       If a filesystem supports files sharing physical storage between multiple
       files ("reflink"), this ioctl(2) operation can be used to make  some  of
       the  data  in  the src_fd file appear in the dest_fd file by sharing the
       underlying storage, which is faster than making a separate physical copy
       of the data.  Both files must reside within the same filesystem.	  If  a
       file  write  should occur to a shared region, the filesystem must ensure
       that the changes remain private to the file being written.  This	 behav-
       ior is commonly referred to as "copy on write".

       This  ioctl  reflinks up to src_length bytes from file descriptor src_fd
       at offset src_offset into the file dest_fd at offset  dest_offset,  pro-
       vided that both are files.  If src_length is zero, the ioctl reflinks to
       the end of the source file.  This information is conveyed in a structure
       of the following form:

	   struct file_clone_range {
	       __s64 src_fd;
	       __u64 src_offset;
	       __u64 src_length;
	       __u64 dest_offset;
	   };

       Clones are atomic with regards to concurrent writes, so no locks need to
       be taken to obtain a consistent cloned copy.

       The FICLONE ioctl clones entire files.

RETURN VALUE
       On error, -1 is returned, and errno is set to indicate the error.

ERRORS
       Error codes can be one of, but are not limited to, the following:

       EBADF  src_fd  is  not open for reading; dest_fd is not open for writing
	      or is open for append-only writes; or the filesystem which src_fd
	      resides on does not support reflink.

       EINVAL The filesystem does not support  reflinking  the	ranges	of  the
	      given  files.  This error can also appear if either file descrip-
	      tor represents a device, FIFO, or socket.	 Disk filesystems  gen-
	      erally  require  the offset and length arguments to be aligned to
	      the fundamental block size.  XFS and Btrfs do not	 support  over-
	      lapping reflink ranges in the same file.

       EISDIR One  of the files is a directory and the filesystem does not sup-
	      port shared regions in directories.

       EOPNOTSUPP
	      This can appear if the filesystem does not support reflinking ei-
	      ther file descriptor, or if either file descriptor refers to spe-
	      cial inodes.

       EPERM  dest_fd is immutable.

       ETXTBSY
	      One of the files is a swap file.	Swap files cannot  share  stor-
	      age.

       EXDEV  dest_fd and src_fd are not on the same mounted filesystem.

STANDARDS
       Linux.

HISTORY
       Linux 4.5.

       They were previously known as BTRFS_IOC_CLONE and BTRFS_IOC_CLONE_RANGE,
       and were private to Btrfs.

CAVEATS
       Because	a  copy-on-write operation requires the allocation of new stor-
       age, the fallocate(2) operation may unshare shared blocks  to  guarantee
       that subsequent writes will not fail because of lack of disk space.

SEE ALSO
       ioctl(2)

Linux man-pages 6.9.1		   2024-06-13			FICLONE(2const)