]>
Commit | Line | Data |
---|---|---|
8c93a5df | 1 | .\" Copyright (c) 2016, Oracle. All rights reserved. |
2998d8b8 | 2 | .\" |
8c93a5df DW |
3 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
4 | .\" This is free documentation; you can redistribute it and/or | |
2998d8b8 | 5 | .\" modify it under the terms of the GNU General Public License as |
8c93a5df DW |
6 | .\" published by the Free Software Foundation; either version 2 of |
7 | .\" the License, or (at your option) any later version. | |
2998d8b8 | 8 | .\" |
8c93a5df DW |
9 | .\" The GNU General Public License's references to "object code" |
10 | .\" and "executables" are to be interpreted as the output of any | |
11 | .\" document formatting or typesetting system, including | |
12 | .\" intermediate and printed output. | |
13 | .\" | |
14 | .\" This manual is distributed in the hope that it will be useful, | |
2998d8b8 DW |
15 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 | .\" GNU General Public License for more details. | |
18 | .\" | |
8c93a5df DW |
19 | .\" You should have received a copy of the GNU General Public |
20 | .\" License along with this manual; if not, see | |
21 | .\" <http://www.gnu.org/licenses/>. | |
2998d8b8 | 22 | .\" %%%LICENSE_END |
35deeb87 | 23 | .TH IOCTL-FIDEDUPERANGE 2 2016-12-12 "Linux" "Linux Programmer's Manual" |
2998d8b8 DW |
24 | .SH NAME |
25 | ioctl_fideduperange \- share some the data of one file with another file | |
26 | .SH SYNOPSIS | |
27 | .br | |
28 | .B #include <sys/ioctl.h> | |
29 | .br | |
30 | .B #include <linux/fs.h> | |
68e4db0a | 31 | .PP |
70bdb9b5 | 32 | .BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg ); |
2998d8b8 DW |
33 | .SH DESCRIPTION |
34 | If a filesystem supports files sharing physical storage between multiple | |
35 | files, this | |
36 | .BR ioctl (2) | |
2db75216 | 37 | operation can be used to make some of the data in the |
2998d8b8 DW |
38 | .B src_fd |
39 | file appear in the | |
40 | .B dest_fd | |
41 | file by sharing the underlying storage if the file data is identical | |
990a64f7 | 42 | ("deduplication"). |
8592ec74 | 43 | Both files must reside within the same filesystem. |
990a64f7 MK |
44 | This reduces storage consumption by allowing the filesystem |
45 | to store one shared copy of the data. | |
46 | If a file write should occur to a shared | |
2998d8b8 | 47 | region, the filesystem must ensure that the changes remain private to the file |
990a64f7 MK |
48 | being written. |
49 | This behavior is commonly referred to as "copy on write". | |
efeece04 | 50 | .PP |
2998d8b8 DW |
51 | This ioctl performs the "compare and share if identical" operation on up to |
52 | .IR src_length | |
53 | bytes from file descriptor | |
54 | .IR src_fd | |
55 | at offset | |
56 | .IR src_offset ". | |
57 | This information is conveyed in a structure of the following form: | |
b76974c1 | 58 | .PP |
2998d8b8 | 59 | .in +4n |
b76974c1 | 60 | .EX |
2998d8b8 | 61 | struct file_dedupe_range { |
2db75216 MK |
62 | __u64 src_offset; |
63 | __u64 src_length; | |
64 | __u16 dest_count; | |
65 | __u16 reserved1; | |
66 | __u32 reserved2; | |
67 | struct file_dedupe_range_info info[0]; | |
2998d8b8 | 68 | }; |
b76974c1 | 69 | .EX |
2998d8b8 | 70 | .in |
efeece04 | 71 | .PP |
2998d8b8 DW |
72 | Deduplication is atomic with regards to concurrent writes, so no locks need to |
73 | be taken to obtain a consistent deduplicated copy. | |
efeece04 | 74 | .PP |
2ae96e8a | 75 | The fields |
2998d8b8 DW |
76 | .IR reserved1 " and " reserved2 |
77 | must be zero. | |
efeece04 | 78 | .PP |
2998d8b8 | 79 | Destinations for the deduplication operation are conveyed in the array at the |
990a64f7 MK |
80 | end of the structure. |
81 | The number of destinations is given in | |
2998d8b8 DW |
82 | .IR dest_count ", |
83 | and the destination information is conveyed in the following form: | |
efeece04 | 84 | .PP |
2998d8b8 | 85 | .in +4n |
b76974c1 | 86 | .EX |
2998d8b8 | 87 | struct file_dedupe_range_info { |
b76974c1 MK |
88 | __s64 dest_fd; |
89 | __u64 dest_offset; | |
90 | __u64 bytes_deduped; | |
91 | __s32 status; | |
92 | __u32 reserved; | |
2998d8b8 | 93 | }; |
b76974c1 | 94 | .EE |
2998d8b8 | 95 | .in |
efeece04 | 96 | .PP |
2998d8b8 | 97 | Each deduplication operation targets |
c835f0e0 | 98 | .IR src_length |
2998d8b8 DW |
99 | bytes in file descriptor |
100 | .IR dest_fd | |
101 | at offset | |
2046b8ac | 102 | .IR dest_offset ". |
2998d8b8 DW |
103 | The field |
104 | .IR reserved | |
105 | must be zero. | |
2046b8ac DW |
106 | During the call, |
107 | .IR src_fd | |
108 | must be open for reading and | |
109 | .IR dest_fd | |
110 | must be open for writing. | |
c835f0e0 DW |
111 | The combined size of the struct |
112 | .IR file_dedupe_range | |
113 | and the struct | |
114 | .IR file_dedupe_range_info | |
115 | array must not exceed the system page size. | |
116 | The maximum size of | |
117 | .IR src_length | |
ee8655b5 | 118 | is filesystem dependent and is typically 16\ MiB. |
c835f0e0 | 119 | This limit will be enforced silently by the filesystem. |
2046b8ac DW |
120 | By convention, the storage used by |
121 | .IR src_fd | |
122 | is mapped into | |
123 | .IR dest_fd | |
124 | and the previous contents in | |
125 | .IR dest_fd | |
126 | are freed. | |
efeece04 | 127 | .PP |
2998d8b8 DW |
128 | Upon successful completion of this ioctl, the number of bytes successfully |
129 | deduplicated is returned in | |
130 | .IR bytes_deduped | |
131 | and a status code for the deduplication operation is returned in | |
132 | .IR status ". | |
2046b8ac DW |
133 | If even a single byte in the range does not match, the deduplication |
134 | request will be ignored and | |
135 | .IR status | |
136 | set to | |
137 | .BR FILE_DEDUPE_RANGE_DIFFERS . | |
2998d8b8 DW |
138 | The |
139 | .IR status | |
140 | code is set to | |
2046b8ac | 141 | .B FILE_DEDUPE_RANGE_SAME |
2998d8b8 DW |
142 | for success, a negative error code in case of error, or |
143 | .B FILE_DEDUPE_RANGE_DIFFERS | |
144 | if the data did not match. | |
efeece04 | 145 | .PP |
2998d8b8 DW |
146 | .SH RETURN VALUE |
147 | On error, \-1 is returned, and | |
148 | .I errno | |
149 | is set to indicate the error. | |
150 | .PP | |
151 | .SH ERRORS | |
152 | Error codes can be one of, but are not limited to, the following: | |
153 | .TP | |
c835f0e0 DW |
154 | .B ENOMEM |
155 | The kernel was unable to allocate sufficient memory to perform the | |
156 | operation or | |
157 | .IR dest_count | |
158 | is so large that the input argument description spans more than a single | |
159 | page of memory. | |
160 | .TP | |
a9985427 MK |
161 | .B EBADF |
162 | .IR src_fd | |
163 | is not open for reading; | |
164 | .IR dest_fd | |
165 | is not open for writing or is open for append-only writes; or the filesystem | |
166 | which | |
167 | .IR src_fd | |
168 | resides on does not support deduplication. | |
2998d8b8 DW |
169 | .TP |
170 | .B EINVAL | |
171 | The filesystem does not support deduplicating the ranges of the given files. | |
2db75216 MK |
172 | This error can also appear if either file descriptor represents |
173 | a device, FIFO, or socket. | |
990a64f7 MK |
174 | Disk filesystems generally require the offset and length arguments |
175 | to be aligned to the fundamental block size. | |
2db75216 | 176 | Neither Btrfs nor XFS support |
2998d8b8 DW |
177 | overlapping deduplication ranges in the same file. |
178 | .TP | |
a9985427 MK |
179 | .B EISDIR |
180 | One of the files is a directory and the filesystem does not support shared | |
181 | regions in directories. | |
182 | .TP | |
183 | .B EOPNOTSUPP | |
184 | This can appear if the filesystem does not support deduplicating either file | |
2046b8ac | 185 | descriptor, or if either file descriptor refers to special inodes. |
2998d8b8 DW |
186 | .TP |
187 | .B EPERM | |
188 | .IR dest_fd | |
189 | is immutable. | |
190 | .TP | |
191 | .B ETXTBSY | |
990a64f7 MK |
192 | One of the files is a swap file. |
193 | Swap files cannot share storage. | |
2998d8b8 | 194 | .TP |
a9985427 MK |
195 | .B EXDEV |
196 | .IR dest_fd " and " src_fd | |
197 | are not on the same mounted filesystem. | |
5711c5f7 MK |
198 | .SH VERSIONS |
199 | This ioctl operation first appeared in Linux 4.5. | |
200 | It was previously known as | |
2db75216 MK |
201 | .B BTRFS_IOC_FILE_EXTENT_SAME |
202 | and was private to Btrfs. | |
5711c5f7 MK |
203 | .SH CONFORMING TO |
204 | This API is Linux-specific. | |
2998d8b8 | 205 | .SH NOTES |
2db75216 MK |
206 | Because a copy-on-write operation requires the allocation of new storage, the |
207 | .BR fallocate (2) | |
208 | operation may unshare shared blocks to guarantee that subsequent writes will | |
2998d8b8 | 209 | not fail because of lack of disk space. |
efeece04 | 210 | .PP |
2998d8b8 DW |
211 | Some filesystems may limit the amount of data that can be deduplicated in a |
212 | single call. | |
2998d8b8 DW |
213 | .SH SEE ALSO |
214 | .BR ioctl (2) |