Debian Codegraph @

upstream/opensuse-tumbleweed/man2/ioctl_xfs_commit_range.2

raw
1 .\" Copyright (c) 2020-2024 Oracle. All rights reserved.
2 .\"
3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
4 .\" This is free documentation; 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; either version 2 of
7 .\" the License, or (at your option) any later version.
8 .\"
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,
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 .\"
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/>.
22 .\" %%%LICENSE_END
23 .TH IOCTL-XFS-COMMIT-RANGE 2 2024-02-18 "XFS"
24 .SH NAME
25 ioctl_xfs_commit_range \- conditionally exchange the contents of parts of two files
26 ioctl_xfs_start_commit \- prepare to exchange the contents of two files
27 .SH SYNOPSIS
28 .br
29 .B #include <sys/ioctl.h>
30 .br
31 .B #include <xfs/xfs_fs.h>
32 .PP
33 .BI "int ioctl(int " file2_fd ", XFS_IOC_START_COMMIT, struct xfs_commit_range *" arg );
34 .PP
35 .BI "int ioctl(int " file2_fd ", XFS_IOC_COMMIT_RANGE, struct xfs_commit_range *" arg );
36 .SH DESCRIPTION
37 Given a range of bytes in a first file
38 .B file1_fd
39 and a second range of bytes in a second file
40 .BR file2_fd ,
41 this
42 .BR ioctl (2)
43 exchanges the contents of the two ranges if
44 .B file2_fd
45 passes certain freshness criteria.
46
47 Before exchanging the contents, the program must call the
48 .B XFS_IOC_START_COMMIT
49 ioctl to sample freshness data for
50 .BR file2_fd .
51 If the sampled metadata does not match the file metadata at commit time,
52 .B XFS_IOC_COMMIT_RANGE
53 will return
54 .BR EBUSY .
55 .PP
56 Exchanges are atomic with regards to concurrent file operations.
57 Implementations must guarantee that readers see either the old contents or the
58 new contents in their entirety, even if the system fails.
59 .PP
60 The system call parameters are conveyed in structures of the following form:
61 .PP
62 .in +4n
63 .EX
64 struct xfs_commit_range {
65 __s32 file1_fd;
66 __u32 pad;
67 __u64 file1_offset;
68 __u64 file2_offset;
69 __u64 length;
70 __u64 flags;
71 __u64 file2_freshness[5];
72 };
73 .EE
74 .in
75 .PP
76 The field
77 .I pad
78 must be zero.
79 .PP
80 The fields
81 .IR file1_fd ", " file1_offset ", and " length
82 define the first range of bytes to be exchanged.
83 .PP
84 The fields
85 .IR file2_fd ", " file2_offset ", and " length
86 define the second range of bytes to be exchanged.
87 .PP
88 The field
89 .I file2_freshness
90 is an opaque field whose contents are determined by the kernel.
91 These file attributes are used to confirm that
92 .B file2_fd
93 has not changed by another thread since the current thread began staging its
94 own update.
95 .PP
96 Both files must be from the same filesystem mount.
97 If the two file descriptors represent the same file, the byte ranges must not
98 overlap.
99 Most disk-based filesystems require that the starts of both ranges must be
100 aligned to the file block size.
101 If this is the case, the ends of the ranges must also be so aligned unless the
102 .B XFS_EXCHANGE_RANGE_TO_EOF
103 flag is set.
104
105 .PP
106 The field
107 .I flags
108 control the behavior of the exchange operation.
109 .RS 0.4i
110 .TP
111 .B XFS_EXCHANGE_RANGE_TO_EOF
112 Ignore the
113 .I length
114 parameter.
115 All bytes in
116 .I file1_fd
117 from
118 .I file1_offset
119 to EOF are moved to
120 .IR file2_fd ,
121 and file2's size is set to
122 .RI ( file2_offset "+(" file1_length - file1_offset )).
123 Meanwhile, all bytes in file2 from
124 .I file2_offset
125 to EOF are moved to file1 and file1's size is set to
126 .RI ( file1_offset "+(" file2_length - file2_offset )).
127 .TP
128 .B XFS_EXCHANGE_RANGE_DSYNC
129 Ensure that all modified in-core data in both file ranges and all metadata
130 updates pertaining to the exchange operation are flushed to persistent storage
131 before the call returns.
132 Opening either file descriptor with
133 .BR O_SYNC " or " O_DSYNC
134 will have the same effect.
135 .TP
136 .B XFS_EXCHANGE_RANGE_FILE1_WRITTEN
137 Only exchange sub-ranges of
138 .I file1_fd
139 that are known to contain data written by application software.
140 Each sub-range may be expanded (both upwards and downwards) to align with the
141 file allocation unit.
142 For files on the data device, this is one filesystem block.
143 For files on the realtime device, this is the realtime extent size.
144 This facility can be used to implement fast atomic scatter-gather writes of any
145 complexity for software-defined storage targets if all writes are aligned to
146 the file allocation unit.
147 .TP
148 .B XFS_EXCHANGE_RANGE_DRY_RUN
149 Check the parameters and the feasibility of the operation, but do not change
150 anything.
151 .RE
152 .PP
153 .SH RETURN VALUE
154 On error, \-1 is returned, and
155 .I errno
156 is set to indicate the error.
157 .PP
158 .SH ERRORS
159 Error codes can be one of, but are not limited to, the following:
160 .TP
161 .B EBADF
162 .IR file1_fd
163 is not open for reading and writing or is open for append-only writes; or
164 .IR file2_fd
165 is not open for reading and writing or is open for append-only writes.
166 .TP
167 .B EBUSY
168 The file2 inode number and timestamps supplied do not match
169 .IR file2_fd .
170 .TP
171 .B EINVAL
172 The parameters are not correct for these files.
173 This error can also appear if either file descriptor represents
174 a device, FIFO, or socket.
175 Disk filesystems generally require the offset and length arguments
176 to be aligned to the fundamental block sizes of both files.
177 .TP
178 .B EIO
179 An I/O error occurred.
180 .TP
181 .B EISDIR
182 One of the files is a directory.
183 .TP
184 .B ENOMEM
185 The kernel was unable to allocate sufficient memory to perform the
186 operation.
187 .TP
188 .B ENOSPC
189 There is not enough free space in the filesystem exchange the contents safely.
190 .TP
191 .B EOPNOTSUPP
192 The filesystem does not support exchanging bytes between the two
193 files.
194 .TP
195 .B EPERM
196 .IR file1_fd " or " file2_fd
197 are immutable.
198 .TP
199 .B ETXTBSY
200 One of the files is a swap file.
201 .TP
202 .B EUCLEAN
203 The filesystem is corrupt.
204 .TP
205 .B EXDEV
206 .IR file1_fd " and " file2_fd
207 are not on the same mounted filesystem.
208 .SH CONFORMING TO
209 This API is XFS-specific.
210 .SH USE CASES
211 .PP
212 Several use cases are imagined for this system call.
213 Coordination between multiple threads is performed by the kernel.
214 .PP
215 The first is a filesystem defragmenter, which copies the contents of a file
216 into another file and wishes to exchange the space mappings of the two files,
217 provided that the original file has not changed.
218 .PP
219 An example program might look like this:
220 .PP
221 .in +4n
222 .EX
223 int fd = open("/some/file", O_RDWR);
224 int temp_fd = open("/some", O_TMPFILE | O_RDWR);
225 struct stat sb;
226 struct xfs_commit_range args = {
227 .flags = XFS_EXCHANGE_RANGE_TO_EOF,
228 };
229
230 /* gather file2's freshness information */
231 ioctl(fd, XFS_IOC_START_COMMIT, &args);
232 fstat(fd, &sb);
233
234 /* make a fresh copy of the file with terrible alignment to avoid reflink */
235 clone_file_range(fd, NULL, temp_fd, NULL, 1, 0);
236 clone_file_range(fd, NULL, temp_fd, NULL, sb.st_size - 1, 0);
237
238 /* commit the entire update */
239 args.file1_fd = temp_fd;
240 ret = ioctl(fd, XFS_IOC_COMMIT_RANGE, &args);
241 if (ret && errno == EBUSY)
242 printf("file changed while defrag was underway\\n");
243 .EE
244 .in
245 .PP
246 The second is a data storage program that wants to commit non-contiguous updates
247 to a file atomically.
248 This program cannot coordinate updates to the file and therefore relies on the
249 kernel to reject the COMMIT_RANGE command if the file has been updated by
250 someone else.
251 This can be done by creating a temporary file, calling
252 .BR FICLONE (2)
253 to share the contents, and staging the updates into the temporary file.
254 The
255 .B FULL_FILES
256 flag is recommended for this purpose.
257 The temporary file can be deleted or punched out afterwards.
258 .PP
259 An example program might look like this:
260 .PP
261 .in +4n
262 .EX
263 int fd = open("/some/file", O_RDWR);
264 int temp_fd = open("/some", O_TMPFILE | O_RDWR);
265 struct xfs_commit_range args = {
266 .flags = XFS_EXCHANGE_RANGE_TO_EOF,
267 };
268
269 /* gather file2's freshness information */
270 ioctl(fd, XFS_IOC_START_COMMIT, &args);
271
272 ioctl(temp_fd, FICLONE, fd);
273
274 /* append 1MB of records */
275 lseek(temp_fd, 0, SEEK_END);
276 write(temp_fd, data1, 1000000);
277
278 /* update record index */
279 pwrite(temp_fd, data1, 600, 98765);
280 pwrite(temp_fd, data2, 320, 54321);
281 pwrite(temp_fd, data2, 15, 0);
282
283 /* commit the entire update */
284 args.file1_fd = temp_fd;
285 ret = ioctl(fd, XFS_IOC_COMMIT_RANGE, &args);
286 if (ret && errno == EBUSY)
287 printf("file changed before commit; will roll back\\n");
288 .EE
289 .in
290 .B
291 .SH NOTES
292 .PP
293 Some filesystems may limit the amount of data or the number of extents that can
294 be exchanged in a single call.
295 .SH SEE ALSO
296 .BR ioctl (2)