]>
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> | |
31 | .sp | |
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". | |
2998d8b8 DW |
50 | |
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: | |
58 | .in +4n | |
59 | .nf | |
60 | ||
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 DW |
68 | }; |
69 | .fi | |
70 | .in | |
48dd0abc | 71 | |
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. | |
74 | ||
2ae96e8a | 75 | The fields |
2998d8b8 DW |
76 | .IR reserved1 " and " reserved2 |
77 | must be zero. | |
78 | ||
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: | |
84 | ||
85 | .in +4n | |
86 | .nf | |
87 | struct file_dedupe_range_info { | |
88 | __s64 dest_fd; | |
89 | __u64 dest_offset; | |
90 | __u64 bytes_deduped; | |
91 | __s32 status; | |
92 | __u32 reserved; | |
93 | }; | |
94 | ||
95 | .fi | |
96 | .in | |
97 | ||
98 | Each deduplication operation targets | |
c835f0e0 | 99 | .IR src_length |
2998d8b8 DW |
100 | bytes in file descriptor |
101 | .IR dest_fd | |
102 | at offset | |
2046b8ac | 103 | .IR dest_offset ". |
2998d8b8 DW |
104 | The field |
105 | .IR reserved | |
106 | must be zero. | |
2046b8ac DW |
107 | During the call, |
108 | .IR src_fd | |
109 | must be open for reading and | |
110 | .IR dest_fd | |
111 | must be open for writing. | |
c835f0e0 DW |
112 | The combined size of the struct |
113 | .IR file_dedupe_range | |
114 | and the struct | |
115 | .IR file_dedupe_range_info | |
116 | array must not exceed the system page size. | |
117 | The maximum size of | |
118 | .IR src_length | |
119 | is filesystem dependent and is typically 16MiB. | |
120 | This limit will be enforced silently by the filesystem. | |
2046b8ac DW |
121 | By convention, the storage used by |
122 | .IR src_fd | |
123 | is mapped into | |
124 | .IR dest_fd | |
125 | and the previous contents in | |
126 | .IR dest_fd | |
127 | are freed. | |
2998d8b8 DW |
128 | |
129 | Upon successful completion of this ioctl, the number of bytes successfully | |
130 | deduplicated is returned in | |
131 | .IR bytes_deduped | |
132 | and a status code for the deduplication operation is returned in | |
133 | .IR status ". | |
2046b8ac DW |
134 | If even a single byte in the range does not match, the deduplication |
135 | request will be ignored and | |
136 | .IR status | |
137 | set to | |
138 | .BR FILE_DEDUPE_RANGE_DIFFERS . | |
2998d8b8 DW |
139 | The |
140 | .IR status | |
141 | code is set to | |
2046b8ac | 142 | .B FILE_DEDUPE_RANGE_SAME |
2998d8b8 DW |
143 | for success, a negative error code in case of error, or |
144 | .B FILE_DEDUPE_RANGE_DIFFERS | |
145 | if the data did not match. | |
146 | ||
147 | .SH RETURN VALUE | |
148 | On error, \-1 is returned, and | |
149 | .I errno | |
150 | is set to indicate the error. | |
151 | .PP | |
152 | .SH ERRORS | |
153 | Error codes can be one of, but are not limited to, the following: | |
154 | .TP | |
c835f0e0 DW |
155 | .B ENOMEM |
156 | The kernel was unable to allocate sufficient memory to perform the | |
157 | operation or | |
158 | .IR dest_count | |
159 | is so large that the input argument description spans more than a single | |
160 | page of memory. | |
161 | .TP | |
a9985427 MK |
162 | .B EBADF |
163 | .IR src_fd | |
164 | is not open for reading; | |
165 | .IR dest_fd | |
166 | is not open for writing or is open for append-only writes; or the filesystem | |
167 | which | |
168 | .IR src_fd | |
169 | resides on does not support deduplication. | |
2998d8b8 DW |
170 | .TP |
171 | .B EINVAL | |
172 | The filesystem does not support deduplicating the ranges of the given files. | |
2db75216 MK |
173 | This error can also appear if either file descriptor represents |
174 | a device, FIFO, or socket. | |
990a64f7 MK |
175 | Disk filesystems generally require the offset and length arguments |
176 | to be aligned to the fundamental block size. | |
2db75216 | 177 | Neither Btrfs nor XFS support |
2998d8b8 DW |
178 | overlapping deduplication ranges in the same file. |
179 | .TP | |
a9985427 MK |
180 | .B EISDIR |
181 | One of the files is a directory and the filesystem does not support shared | |
182 | regions in directories. | |
183 | .TP | |
184 | .B EOPNOTSUPP | |
185 | This can appear if the filesystem does not support deduplicating either file | |
2046b8ac | 186 | descriptor, or if either file descriptor refers to special inodes. |
2998d8b8 DW |
187 | .TP |
188 | .B EPERM | |
189 | .IR dest_fd | |
190 | is immutable. | |
191 | .TP | |
192 | .B ETXTBSY | |
990a64f7 MK |
193 | One of the files is a swap file. |
194 | Swap files cannot share storage. | |
2998d8b8 | 195 | .TP |
a9985427 MK |
196 | .B EXDEV |
197 | .IR dest_fd " and " src_fd | |
198 | are not on the same mounted filesystem. | |
5711c5f7 MK |
199 | .SH VERSIONS |
200 | This ioctl operation first appeared in Linux 4.5. | |
201 | It was previously known as | |
2db75216 MK |
202 | .B BTRFS_IOC_FILE_EXTENT_SAME |
203 | and was private to Btrfs. | |
5711c5f7 MK |
204 | .SH CONFORMING TO |
205 | This API is Linux-specific. | |
2998d8b8 | 206 | .SH NOTES |
2db75216 MK |
207 | Because a copy-on-write operation requires the allocation of new storage, the |
208 | .BR fallocate (2) | |
209 | operation may unshare shared blocks to guarantee that subsequent writes will | |
2998d8b8 DW |
210 | not fail because of lack of disk space. |
211 | ||
212 | Some filesystems may limit the amount of data that can be deduplicated in a | |
213 | single call. | |
2998d8b8 DW |
214 | .SH SEE ALSO |
215 | .BR ioctl (2) |