From 9eb18e174c65475d6530809e2b262ff26e703c7b Mon Sep 17 00:00:00 2001 From: "Darrick J. Wong" Date: Tue, 15 Mar 2016 09:48:10 -0700 Subject: [PATCH] man2: New page documenting FICLONE and FICLONERANGE ioctls Document the FICLONE and FICLONERANGE ioctls, formerly known as the BTRFS_IOC_CLONE and BTRFS_IOC_CLONE_RANGE ioctls. Reviewed-by: Christoph Hellwig Signed-off-by: Darrick J. Wong --- man2/ioctl_ficlone.2 | 1 + man2/ioctl_ficlonerange.2 | 124 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 125 insertions(+) create mode 100644 man2/ioctl_ficlone.2 create mode 100644 man2/ioctl_ficlonerange.2 diff --git a/man2/ioctl_ficlone.2 b/man2/ioctl_ficlone.2 new file mode 100644 index 000000000..19bb3482d --- /dev/null +++ b/man2/ioctl_ficlone.2 @@ -0,0 +1 @@ +.so man2/ioctl_ficlonerange.2 diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2 new file mode 100644 index 000000000..c5c72aadb --- /dev/null +++ b/man2/ioctl_ficlonerange.2 @@ -0,0 +1,124 @@ +.\" Copyright (C) 2016 Oracle. All rights reserved. +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation. +.\" +.\" This program is distributed in the hope that it would 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 program; if not, write the Free Software Foundation, +.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +.\" %%%LICENSE_END +.TH IOCTL-FICLONERANGE 2 2016-02-10 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file +.SH SYNOPSIS +.br +.B #include +.br +.B #include +.sp +.BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range * " arg ); +.br +.BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd ); +.SH DESCRIPTION +If a filesystem supports files sharing physical storage between multiple +files ("reflink"), this +.BR ioctl (2) +system call can be used to make some of the data in the +.B src_fd +file appear in the +.B dest_fd +file by sharing the underlying storage, which is faster than making a separate +physical copy of the data. 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". + +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. This information is conveyed in a structure of +the following form: +.in +4n +.nf + +struct file_clone_range { + __s64 src_fd; + __u64 src_offset; + __u64 src_length; + __u64 dest_offset; +}; + +.fi +.in +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. +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.PP +.SH ERRORS +Error codes can be one of, but are not limited to, the following: +.TP +.B EXDEV +.IR dest_fd " and " src_fd +are not on the same mounted filesystem. +.TP +.B EISDIR +One of the files is a directory and the filesystem does not support shared +regions in directories. +.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 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 EPERM +.IR dest_fd +is immutable. +.TP +.B ETXTBSY +One of the files is a swap file. Swap files cannot share storage. +.TP +.B EOPNOTSUPP +This can appear if the filesystem does not support reflinking either file +descriptor. +.SH NOTES +Because a copy on write operation requires the allocation of new storage, the +.B fallocate (2) +operation may un-share shared blocks to guarantee that subsequent writes will +not fail because of lack of disk space. +.SH CONFORMING TO +This API is Linux-specific. This ioctl was previously known as +.B BTRFS_IOC_CLONE_RANGE +and was private to btrfs. +.fi +.in +.SH SEE ALSO +.BR ioctl (2)