mirror of https://github.com/mkerrisk/man-pages
man2: New page documenting the FIDEDUPERANGE ioctl
Document the FIDEDUPERANGE ioctl, formerly known as BTRFS_IOC_EXTENT_SAME. Reviewed-by: Christoph Hellwig <hch@lst.de> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
This commit is contained in:
parent
c4f9c619fe
commit
2998d8b804
|
@ -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)
|
Loading…
Reference in New Issue