| .\" Copyright (c) 2016, Oracle. All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will 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 manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .TH IOCTL_FIDEDUPERANGE 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| ioctl_fideduperange \- share some the data of one file with another file |
| .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 |
| .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: |
| .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 |
| .IR src_length |
| bytes in file descriptor |
| .IR dest_fd |
| at offset |
| .IR dest_offset . |
| The field |
| .IR reserved |
| must be zero. |
| During the call, |
| .IR src_fd |
| must be open for reading and |
| .IR dest_fd |
| must be open for writing. |
| The combined size of the struct |
| .IR file_dedupe_range |
| and the struct |
| .IR file_dedupe_range_info |
| array must not exceed the system page size. |
| The maximum size of |
| .IR 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 |
| .IR src_fd |
| is mapped into |
| .IR dest_fd |
| and the previous contents in |
| .IR dest_fd |
| are freed. |
| .PP |
| 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 . |
| If even a single byte in the range does not match, the deduplication |
| request will be ignored and |
| .IR status |
| set to |
| .BR FILE_DEDUPE_RANGE_DIFFERS . |
| The |
| .IR 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 |
| .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 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 |
| .IR 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 |
| .IR dest_fd |
| is immutable. |
| .TP |
| .B ETXTBSY |
| One of the files is a swap file. |
| Swap files cannot share storage. |
| .TP |
| .B EXDEV |
| .IR dest_fd " and " src_fd |
| are not on the same mounted filesystem. |
| .SH VERSIONS |
| This ioctl operation first appeared in Linux 4.5. |
| It was previously known as |
| .B BTRFS_IOC_FILE_EXTENT_SAME |
| and was private to Btrfs. |
| .SH CONFORMING TO |
| This API is Linux-specific. |
| .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. |
| .PP |
| Some filesystems may limit the amount of data that can be deduplicated in a |
| single call. |
| .SH SEE ALSO |
| .BR ioctl (2) |