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