| 1 |
.\" Copyright 2016, Oracle |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: GPL-2.0-or-later |
| 5 |
.\" |
| 6 |
.TH FIDEDUPERANGE 2const 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
FIDEDUPERANGE |
| 9 |
\- |
| 10 |
share some the data of one file with another file |
| 11 |
.SH LIBRARY |
| 12 |
Standard C library |
| 13 |
.RI ( libc ,\~ \-lc ) |
| 14 |
.SH SYNOPSIS |
| 15 |
.nf |
| 16 |
.BR "#include <linux/fs.h>" " /* Definition of " FIDEDUPERANGE " and" |
| 17 |
.BR " FILE_DEDUPE_* " constants */ |
| 18 |
.B #include <sys/ioctl.h> |
| 19 |
.P |
| 20 |
.BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg ); |
| 21 |
.fi |
| 22 |
.SH DESCRIPTION |
| 23 |
If a filesystem supports files sharing physical storage between multiple |
| 24 |
files, this |
| 25 |
.BR ioctl (2) |
| 26 |
operation can be used to make some of the data in the |
| 27 |
.B src_fd |
| 28 |
file appear in the |
| 29 |
.B dest_fd |
| 30 |
file by sharing the underlying storage if the file data is identical |
| 31 |
("deduplication"). |
| 32 |
Both files must reside within the same filesystem. |
| 33 |
This reduces storage consumption by allowing the filesystem |
| 34 |
to store one shared copy of the data. |
| 35 |
If a file write should occur to a shared |
| 36 |
region, the filesystem must ensure that the changes remain private to the file |
| 37 |
being written. |
| 38 |
This behavior is commonly referred to as "copy on write". |
| 39 |
.P |
| 40 |
This ioctl performs the "compare and share if identical" operation on up to |
| 41 |
.I src_length |
| 42 |
bytes from file descriptor |
| 43 |
.I src_fd |
| 44 |
at offset |
| 45 |
.IR src_offset . |
| 46 |
This information is conveyed in a structure of the following form: |
| 47 |
.P |
| 48 |
.in +4n |
| 49 |
.EX |
| 50 |
struct file_dedupe_range { |
| 51 |
__u64 src_offset; |
| 52 |
__u64 src_length; |
| 53 |
__u16 dest_count; |
| 54 |
__u16 reserved1; |
| 55 |
__u32 reserved2; |
| 56 |
struct file_dedupe_range_info info[0]; |
| 57 |
}; |
| 58 |
.EE |
| 59 |
.in |
| 60 |
.P |
| 61 |
Deduplication is atomic with regards to concurrent writes, so no locks need to |
| 62 |
be taken to obtain a consistent deduplicated copy. |
| 63 |
.P |
| 64 |
The fields |
| 65 |
.IR reserved1 " and " reserved2 |
| 66 |
must be zero. |
| 67 |
.P |
| 68 |
Destinations for the deduplication operation are conveyed in the array at the |
| 69 |
end of the structure. |
| 70 |
The number of destinations is given in |
| 71 |
.IR dest_count , |
| 72 |
and the destination information is conveyed in the following form: |
| 73 |
.P |
| 74 |
.in +4n |
| 75 |
.EX |
| 76 |
struct file_dedupe_range_info { |
| 77 |
__s64 dest_fd; |
| 78 |
__u64 dest_offset; |
| 79 |
__u64 bytes_deduped; |
| 80 |
__s32 status; |
| 81 |
__u32 reserved; |
| 82 |
}; |
| 83 |
.EE |
| 84 |
.in |
| 85 |
.P |
| 86 |
Each deduplication operation targets |
| 87 |
.I src_length |
| 88 |
bytes in file descriptor |
| 89 |
.I dest_fd |
| 90 |
at offset |
| 91 |
.IR dest_offset . |
| 92 |
The field |
| 93 |
.I reserved |
| 94 |
must be zero. |
| 95 |
During the call, |
| 96 |
.I src_fd |
| 97 |
must be open for reading and |
| 98 |
.I dest_fd |
| 99 |
must be open for writing. |
| 100 |
The combined size of the struct |
| 101 |
.I file_dedupe_range |
| 102 |
and the struct |
| 103 |
.I file_dedupe_range_info |
| 104 |
array must not exceed the system page size. |
| 105 |
The maximum size of |
| 106 |
.I src_length |
| 107 |
is filesystem dependent and is typically 16\~MiB. |
| 108 |
This limit will be enforced silently by the filesystem. |
| 109 |
By convention, the storage used by |
| 110 |
.I src_fd |
| 111 |
is mapped into |
| 112 |
.I dest_fd |
| 113 |
and the previous contents in |
| 114 |
.I dest_fd |
| 115 |
are freed. |
| 116 |
.P |
| 117 |
Upon successful completion of this ioctl, the number of bytes successfully |
| 118 |
deduplicated is returned in |
| 119 |
.I bytes_deduped |
| 120 |
and a status code for the deduplication operation is returned in |
| 121 |
.IR status . |
| 122 |
If even a single byte in the range does not match, the deduplication |
| 123 |
operation request will be ignored and |
| 124 |
.I status |
| 125 |
set to |
| 126 |
.BR FILE_DEDUPE_RANGE_DIFFERS . |
| 127 |
The |
| 128 |
.I status |
| 129 |
code is set to |
| 130 |
.B FILE_DEDUPE_RANGE_SAME |
| 131 |
for success, a negative error code in case of error, or |
| 132 |
.B FILE_DEDUPE_RANGE_DIFFERS |
| 133 |
if the data did not match. |
| 134 |
.SH RETURN VALUE |
| 135 |
On error, \-1 is returned, and |
| 136 |
.I errno |
| 137 |
is set to indicate the error. |
| 138 |
.SH ERRORS |
| 139 |
Possible errors include (but are not limited to) the following: |
| 140 |
.TP |
| 141 |
.B EBADF |
| 142 |
.I src_fd |
| 143 |
is not open for reading; |
| 144 |
.I dest_fd |
| 145 |
is not open for writing or is open for append-only writes; |
| 146 |
or the filesystem which |
| 147 |
.I src_fd |
| 148 |
resides on |
| 149 |
does not support deduplication. |
| 150 |
.TP |
| 151 |
.B EINVAL |
| 152 |
The filesystem does not support deduplicating the ranges of the given files. |
| 153 |
This error can also appear if either file descriptor represents |
| 154 |
a device, FIFO, or socket. |
| 155 |
Disk filesystems generally require the offset and length arguments |
| 156 |
to be aligned to the fundamental block size. |
| 157 |
Neither Btrfs nor XFS support |
| 158 |
overlapping deduplication ranges in the same file. |
| 159 |
.TP |
| 160 |
.B EISDIR |
| 161 |
One of the files is a directory and the filesystem does not support shared |
| 162 |
regions in directories. |
| 163 |
.TP |
| 164 |
.B ENOMEM |
| 165 |
The kernel was unable to allocate sufficient memory to perform the |
| 166 |
operation or |
| 167 |
.I dest_count |
| 168 |
is so large that the input argument description spans more than a single |
| 169 |
page of memory. |
| 170 |
.TP |
| 171 |
.B EOPNOTSUPP |
| 172 |
This can appear if the filesystem does not support deduplicating either file |
| 173 |
descriptor, or if either file descriptor refers to special inodes. |
| 174 |
.TP |
| 175 |
.B EPERM |
| 176 |
.I dest_fd |
| 177 |
is immutable. |
| 178 |
.TP |
| 179 |
.B ETXTBSY |
| 180 |
One of the files is a swap file. |
| 181 |
Swap files cannot share storage. |
| 182 |
.TP |
| 183 |
.B EXDEV |
| 184 |
.I dest_fd |
| 185 |
and |
| 186 |
.I src_fd |
| 187 |
are not on the same mounted filesystem. |
| 188 |
.SH VERSIONS |
| 189 |
Some filesystems may limit the amount of data that can be deduplicated in a |
| 190 |
single call. |
| 191 |
.SH STANDARDS |
| 192 |
Linux. |
| 193 |
.SH HISTORY |
| 194 |
Linux 4.5. |
| 195 |
.P |
| 196 |
It was previously known as |
| 197 |
.B BTRFS_IOC_FILE_EXTENT_SAME |
| 198 |
and was private to Btrfs. |
| 199 |
.SH NOTES |
| 200 |
Because a copy-on-write operation requires the allocation of new storage, the |
| 201 |
.BR fallocate (2) |
| 202 |
operation may unshare shared blocks to guarantee that subsequent writes will |
| 203 |
not fail because of lack of disk space. |
| 204 |
.SH SEE ALSO |
| 205 |
.BR ioctl (2) |