]>
Commit | Line | Data |
---|---|---|
2998d8b8 DW |
1 | .\" Copyright (C) 2016 Oracle. All rights reserved. |
2 | .\" | |
3 | .\" %%%LICENSE_START(VERBATIM) | |
4 | .\" This program is free software; you can redistribute it and/or | |
5 | .\" modify it under the terms of the GNU General Public License as | |
6 | .\" published by the Free Software Foundation. | |
7 | .\" | |
8 | .\" This program is distributed in the hope that it would be useful, | |
9 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
10 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
11 | .\" GNU General Public License for more details. | |
12 | .\" | |
13 | .\" You should have received a copy of the GNU General Public License | |
14 | .\" along with this program; if not, write the Free Software Foundation, | |
15 | .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA | |
16 | .\" %%%LICENSE_END | |
17 | .TH IOCTL-FIDEDUPERANGE 2 2016-02-10 "Linux" "Linux Programmer's Manual" | |
18 | .SH NAME | |
19 | ioctl_fideduperange \- share some the data of one file with another file | |
20 | .SH SYNOPSIS | |
21 | .br | |
22 | .B #include <sys/ioctl.h> | |
23 | .br | |
24 | .B #include <linux/fs.h> | |
25 | .sp | |
26 | .BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range * " arg ); | |
27 | .SH DESCRIPTION | |
28 | If a filesystem supports files sharing physical storage between multiple | |
29 | files, this | |
30 | .BR ioctl (2) | |
2db75216 | 31 | operation can be used to make some of the data in the |
2998d8b8 DW |
32 | .B src_fd |
33 | file appear in the | |
34 | .B dest_fd | |
35 | file by sharing the underlying storage if the file data is identical | |
990a64f7 MK |
36 | ("deduplication"). |
37 | This reduces storage consumption by allowing the filesystem | |
38 | to store one shared copy of the data. | |
39 | If a file write should occur to a shared | |
2998d8b8 | 40 | region, the filesystem must ensure that the changes remain private to the file |
990a64f7 MK |
41 | being written. |
42 | This behavior is commonly referred to as "copy on write". | |
2998d8b8 DW |
43 | |
44 | This ioctl performs the "compare and share if identical" operation on up to | |
45 | .IR src_length | |
46 | bytes from file descriptor | |
47 | .IR src_fd | |
48 | at offset | |
49 | .IR src_offset ". | |
50 | This information is conveyed in a structure of the following form: | |
51 | .in +4n | |
52 | .nf | |
53 | ||
54 | struct file_dedupe_range { | |
2db75216 MK |
55 | __u64 src_offset; |
56 | __u64 src_length; | |
57 | __u16 dest_count; | |
58 | __u16 reserved1; | |
59 | __u32 reserved2; | |
60 | struct file_dedupe_range_info info[0]; | |
2998d8b8 DW |
61 | }; |
62 | .fi | |
63 | .in | |
64 | Deduplication is atomic with regards to concurrent writes, so no locks need to | |
65 | be taken to obtain a consistent deduplicated copy. | |
66 | ||
67 | The fields | |
68 | .IR reserved1 " and " reserved2 | |
69 | must be zero. | |
70 | ||
71 | Destinations for the deduplication operation are conveyed in the array at the | |
990a64f7 MK |
72 | end of the structure. |
73 | The number of destinations is given in | |
2998d8b8 DW |
74 | .IR dest_count ", |
75 | and the destination information is conveyed in the following form: | |
76 | ||
77 | .in +4n | |
78 | .nf | |
79 | struct file_dedupe_range_info { | |
80 | __s64 dest_fd; | |
81 | __u64 dest_offset; | |
82 | __u64 bytes_deduped; | |
83 | __s32 status; | |
84 | __u32 reserved; | |
85 | }; | |
86 | ||
87 | .fi | |
88 | .in | |
89 | ||
90 | Each deduplication operation targets | |
91 | .IR length | |
92 | bytes in file descriptor | |
93 | .IR dest_fd | |
94 | at offset | |
95 | .IR logical_offset ". | |
96 | The field | |
97 | .IR reserved | |
98 | must be zero. | |
99 | ||
100 | Upon successful completion of this ioctl, the number of bytes successfully | |
101 | deduplicated is returned in | |
102 | .IR bytes_deduped | |
103 | and a status code for the deduplication operation is returned in | |
104 | .IR status ". | |
105 | ||
106 | The | |
107 | .IR status | |
108 | code is set to | |
109 | .B 0 | |
110 | for success, a negative error code in case of error, or | |
111 | .B FILE_DEDUPE_RANGE_DIFFERS | |
112 | if the data did not match. | |
113 | ||
114 | .SH RETURN VALUE | |
115 | On error, \-1 is returned, and | |
116 | .I errno | |
117 | is set to indicate the error. | |
118 | .PP | |
119 | .SH ERRORS | |
120 | Error codes can be one of, but are not limited to, the following: | |
121 | .TP | |
122 | .B EXDEV | |
123 | .IR dest_fd " and " src_fd | |
124 | are not on the same mounted filesystem. | |
125 | .TP | |
126 | .B EISDIR | |
127 | One of the files is a directory and the filesystem does not support shared | |
128 | regions in directories. | |
129 | .TP | |
130 | .B EINVAL | |
131 | The filesystem does not support deduplicating the ranges of the given files. | |
2db75216 MK |
132 | This error can also appear if either file descriptor represents |
133 | a device, FIFO, or socket. | |
990a64f7 MK |
134 | Disk filesystems generally require the offset and length arguments |
135 | to be aligned to the fundamental block size. | |
2db75216 | 136 | Neither Btrfs nor XFS support |
2998d8b8 DW |
137 | overlapping deduplication ranges in the same file. |
138 | .TP | |
139 | .B EBADF | |
140 | .IR src_fd | |
141 | is not open for reading; | |
142 | .IR dest_fd | |
143 | is not open for writing or is open for append-only writes; or the filesystem | |
144 | which | |
145 | .IR src_fd | |
146 | resides on does not support deduplication. | |
147 | .TP | |
148 | .B EPERM | |
149 | .IR dest_fd | |
150 | is immutable. | |
151 | .TP | |
152 | .B ETXTBSY | |
990a64f7 MK |
153 | One of the files is a swap file. |
154 | Swap files cannot share storage. | |
2998d8b8 DW |
155 | .TP |
156 | .B EOPNOTSUPP | |
157 | This can appear if the filesystem does not support deduplicating either file | |
158 | descriptor. | |
5711c5f7 MK |
159 | .SH VERSIONS |
160 | This ioctl operation first appeared in Linux 4.5. | |
161 | It was previously known as | |
2db75216 MK |
162 | .B BTRFS_IOC_FILE_EXTENT_SAME |
163 | and was private to Btrfs. | |
5711c5f7 MK |
164 | .SH CONFORMING TO |
165 | This API is Linux-specific. | |
2998d8b8 | 166 | .SH NOTES |
2db75216 MK |
167 | Because a copy-on-write operation requires the allocation of new storage, the |
168 | .BR fallocate (2) | |
169 | operation may unshare shared blocks to guarantee that subsequent writes will | |
2998d8b8 DW |
170 | not fail because of lack of disk space. |
171 | ||
172 | Some filesystems may limit the amount of data that can be deduplicated in a | |
173 | single call. | |
2998d8b8 DW |
174 | .SH SEE ALSO |
175 | .BR ioctl (2) |