Debian Codegraph @

upstream/debian-trixie/man2/FIDEDUPERANGE.2const

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