On Wed, Jun 08, 2016 at 12:35:47PM +0200, Michael Kerrisk (man-pages) wrote:
> On 03/15/2016 05:48 PM, Darrick J. Wong wrote:
> > Document the FIDEDUPERANGE ioctl, formerly known as BTRFS_IOC_EXTENT_SAME.
>
> Again, thanks for the nice page, Darrick. Applied!
NP. I have a couple of one-line fixes for the manpages that Christoph
suggested a while back that I'll send separately.
[Sorry I forgot about the new-sentence->new-line rule.]
--D
>
> Cheers,
>
> Michael
>
>
> > Signed-off-by: Darrick J. Wong <darrick.wong@xxxxxxxxxx>
> > ---
> > man2/ioctl_fideduperange.2 | 168 ++++++++++++++++++++++++++++++++++++++++++++
> > 1 file changed, 168 insertions(+)
> > create mode 100644 man2/ioctl_fideduperange.2
> >
> >
> > diff --git a/man2/ioctl_fideduperange.2 b/man2/ioctl_fideduperange.2
> > new file mode 100644
> > index 0000000..0fbc388
> > --- /dev/null
> > +++ b/man2/ioctl_fideduperange.2
> > @@ -0,0 +1,168 @@
> > +.\" 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-FIDEDUPERANGE 2 2016-02-10 "Linux" "Linux Programmer's Manual"
> > +.SH NAME
> > +ioctl_fideduperange \- 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 " src_fd ", FIDEDUPERANGE, struct file_dedupe_range * " arg );
> > +.SH DESCRIPTION
> > +If a filesystem supports files sharing physical storage between multiple
> > +files, 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 if the file data is identical
> > +("deduplication"). This reduces storage consumption by allowing the filesystem
> > +to store one shared 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 performs the "compare and share if identical" operation on up to
> > +.IR src_length
> > +bytes from file descriptor
> > +.IR src_fd
> > +at offset
> > +.IR src_offset ".
> > +This information is conveyed in a structure of the following form:
> > +.in +4n
> > +.nf
> > +
> > +struct file_dedupe_range {
> > + __u64 src_offset;
> > + __u64 src_length;
> > + __u16 dest_count;
> > + __u16 reserved1;
> > + __u32 reserved2;
> > + struct file_dedupe_range_info info[0];
> > +};
> > +.fi
> > +.in
> > +Deduplication is atomic with regards to concurrent writes, so no locks need to
> > +be taken to obtain a consistent deduplicated copy.
> > +
> > +The fields
> > +.IR reserved1 " and " reserved2
> > +must be zero.
> > +
> > +Destinations for the deduplication operation are conveyed in the array at the
> > +end of the structure. The number of destinations is given in
> > +.IR dest_count ",
> > +and the destination information is conveyed in the following form:
> > +
> > +.in +4n
> > +.nf
> > +struct file_dedupe_range_info {
> > + __s64 dest_fd;
> > + __u64 dest_offset;
> > + __u64 bytes_deduped;
> > + __s32 status;
> > + __u32 reserved;
> > +};
> > +
> > +.fi
> > +.in
> > +
> > +Each deduplication operation targets
> > +.IR length
> > +bytes in file descriptor
> > +.IR dest_fd
> > +at offset
> > +.IR logical_offset ".
> > +The field
> > +.IR reserved
> > +must be zero.
> > +
> > +Upon successful completion of this ioctl, the number of bytes successfully
> > +deduplicated is returned in
> > +.IR bytes_deduped
> > +and a status code for the deduplication operation is returned in
> > +.IR status ".
> > +
> > +The
> > +.IR status
> > +code is set to
> > +.B 0
> > +for success, a negative error code in case of error, or
> > +.B FILE_DEDUPE_RANGE_DIFFERS
> > +if the data did not match.
> > +
> > +.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 deduplicating 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. Neither btrfs nor XFS support
> > +overlapping deduplication 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 deduplication.
> > +.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 deduplicating 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.
> > +
> > +Some filesystems may limit the amount of data that can be deduplicated in a
> > +single call.
> > +
> > +.SH CONFORMING TO
> > +This API is Linux-specific. This ioctl was previously known as
> > +.B BTRFS_IOC_FILE_EXTENT_SAME
> > +and was private to btrfs.
> > +.fi
> > +.in
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> >
> >
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/
> --
> 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
--
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
