Debian Codegraph @

upstream/debian-unstable/man2/FIDEDUPERANGE.2const

raw
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)