On Sat, Mar 19, 2016 at 06:04:54PM +0100, walter harms wrote: > hi, > i tried to understand the man page and had some problems > (maybe because i am not an FS expert) > > So far i understand the use case is to make a virtual copy > of a file (or range). but it works only on the same fs. Correct, these ioctls allow files within a filesystem to share some of the blocks being managed by that filesystem. I will make that clearer in the manpage. > reading this: > https://lwn.net/Articles/331576/ > > I got the impression there is already a syscall ? > Since when is this function available ? It isn't; the reflink syscall became an ocfs2 ioctl and never progressed beyond that. > Perhaps you can add a simple use case so readers get a better > idea how/why to use this ? cp --reflink is the best known client of this interface, though I've not mentioned this in the manpage in case they should decide some day to use something else. --D > > just my 2 cents, > re, > wh > > > Am 15.03.2016 17:48, schrieb Darrick J. Wong: > > Document the FICLONE and FICLONERANGE ioctls, formerly known as the > > BTRFS_IOC_CLONE and BTRFS_IOC_CLONE_RANGE ioctls. > > > > Signed-off-by: Darrick J. Wong <darrick.wong@xxxxxxxxxx> > > --- > > 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 0000000..19bb348 > > --- /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 0000000..c5c72aa > > --- /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 <sys/ioctl.h> > > +.br > > +.B #include <linux/fs.h> > > +.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) > > > > -- > > To unsubscribe from this list: send the line "unsubscribe linux-man" in > > the body of a message to majordomo@xxxxxxxxxxxxxxx > > More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe linux-api" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
