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)