Changes.old: Document some renamed pages from man-pages-6.9

[thirdparty/man-pages.git] / man2 / ioctl_ficlonerange.2

diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2
deleted file mode 100644 (file)
index 75ab14b..0000000
--- a/man2/ioctl_ficlonerange.2
+++ /dev/null
@@ -1,143 +0,0 @@
-.\" Copyright (c) 2016, Oracle.  All rights reserved.
-.\"
-.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
-.\" This is free documentation; you can redistribute it and/or
-.\" modify it under the terms of the GNU General Public License as
-.\" published by the Free Software Foundation; either version 2 of
-.\" the License, or (at your option) any later version.
-.\"
-.\" The GNU General Public License's references to "object code"
-.\" and "executables" are to be interpreted as the output of any
-.\" document formatting or typesetting system, including
-.\" intermediate and printed output.
-.\"
-.\" This manual is distributed in the hope that it will be useful,
-.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-.\" GNU General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public
-.\" License along with this manual; if not, see
-.\" <http://www.gnu.org/licenses/>.
-.\" %%%LICENSE_END
-.TH IOCTL_FICLONERANGE 2 2021-03-22 "Linux" "Linux Programmer's Manual"
-.SH NAME
-ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file
-.SH SYNOPSIS
-.nf
-.BR "#include <linux/fs.h>" "        /* Definition of " FICLONE* " constants */"
-.B #include <sys/ioctl.h>
-.PP
-.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".
-.PP
-This ioctl reflinks up to
-.IR src_length
-bytes from file descriptor
-.IR src_fd
-at offset
-.IR src_offset
-into the file
-.IR dest_fd
-at offset
-.IR dest_offset ,
-provided that both are files.
-If
-.IR 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:
-.PP
-.in +4n
-.EX
-struct file_clone_range {
-    __s64 src_fd;
-    __u64 src_offset;
-    __u64 src_length;
-    __u64 dest_offset;
-};
-.EE
-.in
-.PP
-Clones are atomic with regards to concurrent writes, so no locks need to be
-taken to obtain a consistent cloned copy.
-.PP
-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
-.IR src_fd
-is not open for reading;
-.IR dest_fd
-is not open for writing or is open for append-only writes;
-or the filesystem which
-.IR 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
-.IR 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 VERSIONS
-These ioctl operations first appeared in Linux 4.5.
-They were previously known as
-.B BTRFS_IOC_CLONE
-and
-.BR BTRFS_IOC_CLONE_RANGE ,
-and were private to Btrfs.
-.SH CONFORMING TO
-This API is Linux-specific.
-.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)