diff options
Diffstat (limited to 'man2/ioctl_fideduperange.2')
| -rw-r--r-- | man2/ioctl_fideduperange.2 | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/man2/ioctl_fideduperange.2 b/man2/ioctl_fideduperange.2 new file mode 100644 index 0000000..5388c5d --- /dev/null +++ b/man2/ioctl_fideduperange.2 @@ -0,0 +1,200 @@ +.\" Copyright (c) 2016, Oracle. All rights reserved. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH ioctl_fideduperange 2 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +ioctl_fideduperange \- share some the data of one file with another file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <linux/fs.h>" " /* Definition of " FIDEDUPERANGE " and" +.BR " FILE_DEDUPE_* " constants */ +.B #include <sys/ioctl.h> +.PP +.BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg ); +.fi +.SH DESCRIPTION +If a filesystem supports files sharing physical storage between multiple +files, this +.BR ioctl (2) +operation 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"). +Both files must reside within the same filesystem. +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". +.PP +This ioctl performs the "compare and share if identical" operation on up to +.I src_length +bytes from file descriptor +.I src_fd +at offset +.IR src_offset . +This information is conveyed in a structure of the following form: +.PP +.in +4n +.EX +struct file_dedupe_range { + __u64 src_offset; + __u64 src_length; + __u16 dest_count; + __u16 reserved1; + __u32 reserved2; + struct file_dedupe_range_info info[0]; +}; +.EE +.in +.PP +Deduplication is atomic with regards to concurrent writes, so no locks need to +be taken to obtain a consistent deduplicated copy. +.PP +The fields +.IR reserved1 " and " reserved2 +must be zero. +.PP +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: +.PP +.in +4n +.EX +struct file_dedupe_range_info { + __s64 dest_fd; + __u64 dest_offset; + __u64 bytes_deduped; + __s32 status; + __u32 reserved; +}; +.EE +.in +.PP +Each deduplication operation targets +.I src_length +bytes in file descriptor +.I dest_fd +at offset +.IR dest_offset . +The field +.I reserved +must be zero. +During the call, +.I src_fd +must be open for reading and +.I dest_fd +must be open for writing. +The combined size of the struct +.I file_dedupe_range +and the struct +.I file_dedupe_range_info +array must not exceed the system page size. +The maximum size of +.I src_length +is filesystem dependent and is typically 16\~MiB. +This limit will be enforced silently by the filesystem. +By convention, the storage used by +.I src_fd +is mapped into +.I dest_fd +and the previous contents in +.I dest_fd +are freed. +.PP +Upon successful completion of this ioctl, the number of bytes successfully +deduplicated is returned in +.I bytes_deduped +and a status code for the deduplication operation is returned in +.IR status . +If even a single byte in the range does not match, the deduplication +request will be ignored and +.I status +set to +.BR FILE_DEDUPE_RANGE_DIFFERS . +The +.I status +code is set to +.B FILE_DEDUPE_RANGE_SAME +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. +.SH ERRORS +Possible errors include (but are not limited to) the following: +.TP +.B EBADF +.I src_fd +is not open for reading; +.I dest_fd +is not open for writing or is open for append-only writes; or the filesystem +which +.I src_fd +resides on does not support deduplication. +.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 EISDIR +One of the files is a directory and the filesystem does not support shared +regions in directories. +.TP +.B ENOMEM +The kernel was unable to allocate sufficient memory to perform the +operation or +.I dest_count +is so large that the input argument description spans more than a single +page of memory. +.TP +.B EOPNOTSUPP +This can appear if the filesystem does not support deduplicating either file +descriptor, or if either file descriptor refers to special inodes. +.TP +.B EPERM +.I dest_fd +is immutable. +.TP +.B ETXTBSY +One of the files is a swap file. +Swap files cannot share storage. +.TP +.B EXDEV +.I dest_fd +and +.I src_fd +are not on the same mounted filesystem. +.SH VERSIONS +Some filesystems may limit the amount of data that can be deduplicated in a +single call. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.5. +.PP +It was previously known as +.B BTRFS_IOC_FILE_EXTENT_SAME +and was private to Btrfs. +.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) |