1 files changed, 129 insertions, 0 deletions
diff --git a/man/man2/ioctl_ficlonerange.2 b/man/man2/ioctl_ficlonerange.2
new file mode 100644
index 000000000..63a430dd4
--- /dev/null
+++ b/man/man2/ioctl_ficlonerange.2
@@ -0,0 +1,129 @@
+.\" Copyright (c) 2016, Oracle.  All rights reserved.
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.TH ioctl_ficlonerange 2 (date) "Linux man-pages (unreleased)"
+.SH NAME
+ioctl_ficlonerange, ioctl_ficlone \-
+share some the data of one file with another file
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/fs.h>" "        /* Definition of " FICLONE* " constants */"
+.B #include <sys/ioctl.h>
+.P
+.BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg );
+.BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd );
+.fi
+.SH DESCRIPTION
+If a filesystem supports files sharing physical storage between multiple
+files ("reflink"), this
+.BR ioctl (2)
+operation can be used to make some of the data in the
+.I src_fd
+file appear in the
+.I 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 behavior is commonly referred to as "copy on write".
+.P
+This ioctl reflinks up to
+.I src_length
+bytes from file descriptor
+.I src_fd
+at offset
+.I src_offset
+into the file
+.I dest_fd
+at offset
+.IR dest_offset ,
+provided that both are files.
+If
+.I 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:
+.P
+.in +4n
+.EX
+struct file_clone_range {
+    __s64 src_fd;
+    __u64 src_offset;
+    __u64 src_length;
+    __u64 dest_offset;
+};
+.EE
+.in
+.P
+Clones are atomic with regards to concurrent writes, so no locks need to be
+taken to obtain a consistent cloned copy.
+.P
+The
+.B FICLONE
+ioctl clones entire files.
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EBADF
+.I src_fd
+is not open for reading;
+.I dest_fd
+is not open for writing or is open for append-only writes;
+or the filesystem which
+.I src_fd
+resides on does not support reflink.
+.TP
+.B EINVAL
+The filesystem does not support reflinking the ranges of the given files.
+This error can also appear if either file descriptor represents
+a device, FIFO, or socket.
+Disk filesystems generally require the offset and length arguments
+to be aligned to the fundamental block size.
+XFS and Btrfs do not support
+overlapping reflink ranges in the same file.
+.TP
+.B EISDIR
+One of the files is a directory and the filesystem does not support shared
+regions in directories.
+.TP
+.B EOPNOTSUPP
+This can appear if the filesystem does not support reflinking either file
+descriptor, or if either file descriptor refers to special inodes.
+.TP
+.B EPERM
+.I dest_fd
+is immutable.
+.TP
+.B ETXTBSY
+One of the files is a swap file.
+Swap files cannot share storage.
+.TP
+.B EXDEV
+.IR dest_fd " and " src_fd
+are not on the same mounted filesystem.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 4.5.
+.P
+They were previously known as
+.B BTRFS_IOC_CLONE
+and
+.BR BTRFS_IOC_CLONE_RANGE ,
+and were private to Btrfs.
+.SH NOTES
+Because a copy-on-write operation requires the allocation of new storage, the
+.BR fallocate (2)
+operation may unshare shared blocks to guarantee that subsequent writes will
+not fail because of lack of disk space.
+.SH SEE ALSO
+.BR ioctl (2)