]>
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 |
3df541c0 | 23 | .TH IOCTL-FIDEDUPERANGE 2 2016-07-17 "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 | |
32 | .BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range * " arg ); | |
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 | |
71 | Deduplication is atomic with regards to concurrent writes, so no locks need to | |
72 | be taken to obtain a consistent deduplicated copy. | |
73 | ||
2ae96e8a | 74 | The fields |
2998d8b8 DW |
75 | .IR reserved1 " and " reserved2 |
76 | must be zero. | |
77 | ||
78 | Destinations for the deduplication operation are conveyed in the array at the | |
990a64f7 MK |
79 | end of the structure. |
80 | The number of destinations is given in | |
2998d8b8 DW |
81 | .IR dest_count ", |
82 | and the destination information is conveyed in the following form: | |
83 | ||
84 | .in +4n | |
85 | .nf | |
86 | struct file_dedupe_range_info { | |
87 | __s64 dest_fd; | |
88 | __u64 dest_offset; | |
89 | __u64 bytes_deduped; | |
90 | __s32 status; | |
91 | __u32 reserved; | |
92 | }; | |
93 | ||
94 | .fi | |
95 | .in | |
96 | ||
97 | Each deduplication operation targets | |
98 | .IR length | |
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. | |
111 | For any call to this ioctl, there may not be more than 65,536 | |
112 | requests attached; each request may not exceed 16MiB. | |
113 | By convention, the storage used by | |
114 | .IR src_fd | |
115 | is mapped into | |
116 | .IR dest_fd | |
117 | and the previous contents in | |
118 | .IR dest_fd | |
119 | are freed. | |
2998d8b8 DW |
120 | |
121 | Upon successful completion of this ioctl, the number of bytes successfully | |
122 | deduplicated is returned in | |
123 | .IR bytes_deduped | |
124 | and a status code for the deduplication operation is returned in | |
125 | .IR status ". | |
2046b8ac DW |
126 | If even a single byte in the range does not match, the deduplication |
127 | request will be ignored and | |
128 | .IR status | |
129 | set to | |
130 | .BR FILE_DEDUPE_RANGE_DIFFERS . | |
2998d8b8 DW |
131 | The |
132 | .IR status | |
133 | code is set to | |
2046b8ac | 134 | .B FILE_DEDUPE_RANGE_SAME |
2998d8b8 DW |
135 | for success, a negative error code in case of error, or |
136 | .B FILE_DEDUPE_RANGE_DIFFERS | |
137 | if the data did not match. | |
138 | ||
139 | .SH RETURN VALUE | |
140 | On error, \-1 is returned, and | |
141 | .I errno | |
142 | is set to indicate the error. | |
143 | .PP | |
144 | .SH ERRORS | |
145 | Error codes can be one of, but are not limited to, the following: | |
146 | .TP | |
a9985427 MK |
147 | .B EBADF |
148 | .IR src_fd | |
149 | is not open for reading; | |
150 | .IR dest_fd | |
151 | is not open for writing or is open for append-only writes; or the filesystem | |
152 | which | |
153 | .IR src_fd | |
154 | resides on does not support deduplication. | |
2998d8b8 DW |
155 | .TP |
156 | .B EINVAL | |
157 | The filesystem does not support deduplicating the ranges of the given files. | |
2db75216 MK |
158 | This error can also appear if either file descriptor represents |
159 | a device, FIFO, or socket. | |
990a64f7 MK |
160 | Disk filesystems generally require the offset and length arguments |
161 | to be aligned to the fundamental block size. | |
2db75216 | 162 | Neither Btrfs nor XFS support |
2998d8b8 DW |
163 | overlapping deduplication ranges in the same file. |
164 | .TP | |
a9985427 MK |
165 | .B EISDIR |
166 | One of the files is a directory and the filesystem does not support shared | |
167 | regions in directories. | |
168 | .TP | |
169 | .B EOPNOTSUPP | |
170 | This can appear if the filesystem does not support deduplicating either file | |
2046b8ac | 171 | descriptor, or if either file descriptor refers to special inodes. |
2998d8b8 DW |
172 | .TP |
173 | .B EPERM | |
174 | .IR dest_fd | |
175 | is immutable. | |
176 | .TP | |
177 | .B ETXTBSY | |
990a64f7 MK |
178 | One of the files is a swap file. |
179 | Swap files cannot share storage. | |
2998d8b8 | 180 | .TP |
a9985427 MK |
181 | .B EXDEV |
182 | .IR dest_fd " and " src_fd | |
183 | are not on the same mounted filesystem. | |
5711c5f7 MK |
184 | .SH VERSIONS |
185 | This ioctl operation first appeared in Linux 4.5. | |
186 | It was previously known as | |
2db75216 MK |
187 | .B BTRFS_IOC_FILE_EXTENT_SAME |
188 | and was private to Btrfs. | |
5711c5f7 MK |
189 | .SH CONFORMING TO |
190 | This API is Linux-specific. | |
2998d8b8 | 191 | .SH NOTES |
2db75216 MK |
192 | Because a copy-on-write operation requires the allocation of new storage, the |
193 | .BR fallocate (2) | |
194 | operation may unshare shared blocks to guarantee that subsequent writes will | |
2998d8b8 DW |
195 | not fail because of lack of disk space. |
196 | ||
197 | Some filesystems may limit the amount of data that can be deduplicated in a | |
198 | single call. | |
2998d8b8 DW |
199 | .SH SEE ALSO |
200 | .BR ioctl (2) |