1 .\" Copyright (c) 2016, Oracle. All rights reserved.
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
4 .TH IOCTL_FIDEDUPERANGE 2 2021-03-22 "Linux" "Linux Programmer's Manual"
6 ioctl_fideduperange \- share some the data of one file with another file
12 .BR "#include <linux/fs.h>" " /* Definition of " FIDEDUPERANGE " and
13 .BR " FILE_DEDUPE_* " constants */
14 .B #include <sys/ioctl.h>
16 .BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg );
19 If a filesystem supports files sharing physical storage between multiple
22 operation can be used to make some of the data in the
26 file by sharing the underlying storage if the file data is identical
28 Both files must reside within the same filesystem.
29 This reduces storage consumption by allowing the filesystem
30 to store one shared copy of the data.
31 If a file write should occur to a shared
32 region, the filesystem must ensure that the changes remain private to the file
34 This behavior is commonly referred to as "copy on write".
36 This ioctl performs the "compare and share if identical" operation on up to
38 bytes from file descriptor
42 This information is conveyed in a structure of the following form:
46 struct file_dedupe_range {
52 struct file_dedupe_range_info info[0];
57 Deduplication is atomic with regards to concurrent writes, so no locks need to
58 be taken to obtain a consistent deduplicated copy.
61 .IR reserved1 " and " reserved2
64 Destinations for the deduplication operation are conveyed in the array at the
66 The number of destinations is given in
68 and the destination information is conveyed in the following form:
72 struct file_dedupe_range_info {
82 Each deduplication operation targets
84 bytes in file descriptor
93 must be open for reading and
95 must be open for writing.
96 The combined size of the struct
99 .I file_dedupe_range_info
100 array must not exceed the system page size.
103 is filesystem dependent and is typically 16\~MiB.
104 This limit will be enforced silently by the filesystem.
105 By convention, the storage used by
109 and the previous contents in
113 Upon successful completion of this ioctl, the number of bytes successfully
114 deduplicated is returned in
116 and a status code for the deduplication operation is returned in
118 If even a single byte in the range does not match, the deduplication
119 request will be ignored and
122 .BR FILE_DEDUPE_RANGE_DIFFERS .
126 .B FILE_DEDUPE_RANGE_SAME
127 for success, a negative error code in case of error, or
128 .B FILE_DEDUPE_RANGE_DIFFERS
129 if the data did not match.
131 On error, \-1 is returned, and
133 is set to indicate the error.
135 Possible errors include (but are not limited to) the following:
139 is not open for reading;
141 is not open for writing or is open for append-only writes; or the filesystem
144 resides on does not support deduplication.
147 The filesystem does not support deduplicating the ranges of the given files.
148 This error can also appear if either file descriptor represents
149 a device, FIFO, or socket.
150 Disk filesystems generally require the offset and length arguments
151 to be aligned to the fundamental block size.
152 Neither Btrfs nor XFS support
153 overlapping deduplication ranges in the same file.
156 One of the files is a directory and the filesystem does not support shared
157 regions in directories.
160 The kernel was unable to allocate sufficient memory to perform the
163 is so large that the input argument description spans more than a single
167 This can appear if the filesystem does not support deduplicating either file
168 descriptor, or if either file descriptor refers to special inodes.
175 One of the files is a swap file.
176 Swap files cannot share storage.
182 are not on the same mounted filesystem.
184 This ioctl operation first appeared in Linux 4.5.
185 It was previously known as
186 .B BTRFS_IOC_FILE_EXTENT_SAME
187 and was private to Btrfs.
189 This API is Linux-specific.
191 Because a copy-on-write operation requires the allocation of new storage, the
193 operation may unshare shared blocks to guarantee that subsequent writes will
194 not fail because of lack of disk space.
196 Some filesystems may limit the amount of data that can be deduplicated in a