Debian Codegraph @

upstream/opensuse-tumbleweed/man2/ioctl_xfs_exchange_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-EXCHANGE-RANGE 2 2024-02-10 "XFS"
24 .SH NAME
25 ioctl_xfs_exchange_range \- exchange the contents of parts of two files
26 .SH SYNOPSIS
27 .br
28 .B #include <sys/ioctl.h>
29 .br
30 .B #include <xfs/xfs_fs.h>
31 .PP
32 .BI "int ioctl(int " file2_fd ", XFS_IOC_EXCHANGE_RANGE, struct xfs_exchange_range *" arg );
33 .SH DESCRIPTION
34 Given a range of bytes in a first file
35 .B file1_fd
36 and a second range of bytes in a second file
37 .BR file2_fd ,
38 this
39 .BR ioctl (2)
40 exchanges the contents of the two ranges.
41 .PP
42 Exchanges are atomic with regards to concurrent file operations.
43 Implementations must guarantee that readers see either the old contents or the
44 new contents in their entirety, even if the system fails.
45 .PP
46 The system call parameters are conveyed in structures of the following form:
47 .PP
48 .in +4n
49 .EX
50 struct xfs_exchange_range {
51 __s32 file1_fd;
52 __u32 pad;
53 __u64 file1_offset;
54 __u64 file2_offset;
55 __u64 length;
56 __u64 flags;
57 };
58 .EE
59 .in
60 .PP
61 The field
62 .I pad
63 must be zero.
64 .PP
65 The fields
66 .IR file1_fd ", " file1_offset ", and " length
67 define the first range of bytes to be exchanged.
68 .PP
69 The fields
70 .IR file2_fd ", " file2_offset ", and " length
71 define the second range of bytes to be exchanged.
72 .PP
73 Both files must be from the same filesystem mount.
74 If the two file descriptors represent the same file, the byte ranges must not
75 overlap.
76 Most disk-based filesystems require that the starts of both ranges must be
77 aligned to the file block size.
78 If this is the case, the ends of the ranges must also be so aligned unless the
79 .B XFS_EXCHANGE_RANGE_TO_EOF
80 flag is set.
81
82 .PP
83 The field
84 .I flags
85 control the behavior of the exchange operation.
86 .RS 0.4i
87 .TP
88 .B XFS_EXCHANGE_RANGE_TO_EOF
89 Ignore the
90 .I length
91 parameter.
92 All bytes in
93 .I file1_fd
94 from
95 .I file1_offset
96 to EOF are moved to
97 .IR file2_fd ,
98 and file2's size is set to
99 .RI ( file2_offset "+(" file1_length - file1_offset )).
100 Meanwhile, all bytes in file2 from
101 .I file2_offset
102 to EOF are moved to file1 and file1's size is set to
103 .RI ( file1_offset "+(" file2_length - file2_offset )).
104 .TP
105 .B XFS_EXCHANGE_RANGE_DSYNC
106 Ensure that all modified in-core data in both file ranges and all metadata
107 updates pertaining to the exchange operation are flushed to persistent storage
108 before the call returns.
109 Opening either file descriptor with
110 .BR O_SYNC " or " O_DSYNC
111 will have the same effect.
112 .TP
113 .B XFS_EXCHANGE_RANGE_FILE1_WRITTEN
114 Only exchange sub-ranges of
115 .I file1_fd
116 that are known to contain data written by application software.
117 Each sub-range may be expanded (both upwards and downwards) to align with the
118 file allocation unit.
119 For files on the data device, this is one filesystem block.
120 For files on the realtime device, this is the realtime extent size.
121 This facility can be used to implement fast atomic scatter-gather writes of any
122 complexity for software-defined storage targets if all writes are aligned to
123 the file allocation unit.
124 .TP
125 .B XFS_EXCHANGE_RANGE_DRY_RUN
126 Check the parameters and the feasibility of the operation, but do not change
127 anything.
128 .RE
129 .PP
130 .SH RETURN VALUE
131 On error, \-1 is returned, and
132 .I errno
133 is set to indicate the error.
134 .PP
135 .SH ERRORS
136 Error codes can be one of, but are not limited to, the following:
137 .TP
138 .B EBADF
139 .IR file1_fd
140 is not open for reading and writing or is open for append-only writes; or
141 .IR file2_fd
142 is not open for reading and writing or is open for append-only writes.
143 .TP
144 .B EINVAL
145 The parameters are not correct for these files.
146 This error can also appear if either file descriptor represents
147 a device, FIFO, or socket.
148 Disk filesystems generally require the offset and length arguments
149 to be aligned to the fundamental block sizes of both files.
150 .TP
151 .B EIO
152 An I/O error occurred.
153 .TP
154 .B EISDIR
155 One of the files is a directory.
156 .TP
157 .B ENOMEM
158 The kernel was unable to allocate sufficient memory to perform the
159 operation.
160 .TP
161 .B ENOSPC
162 There is not enough free space in the filesystem exchange the contents safely.
163 .TP
164 .B EOPNOTSUPP
165 The filesystem does not support exchanging bytes between the two
166 files.
167 .TP
168 .B EPERM
169 .IR file1_fd " or " file2_fd
170 are immutable.
171 .TP
172 .B ETXTBSY
173 One of the files is a swap file.
174 .TP
175 .B EUCLEAN
176 The filesystem is corrupt.
177 .TP
178 .B EXDEV
179 .IR file1_fd " and " file2_fd
180 are not on the same mounted filesystem.
181 .SH CONFORMING TO
182 This API is XFS-specific.
183 .SH USE CASES
184 .PP
185 Several use cases are imagined for this system call.
186 In all cases, application software must coordinate updates to the file
187 because the exchange is performed unconditionally.
188 .PP
189 The first is a data storage program that wants to commit non-contiguous updates
190 to a file atomically and coordinates write access to that file.
191 This can be done by creating a temporary file, calling
192 .BR FICLONE (2)
193 to share the contents, and staging the updates into the temporary file.
194 The
195 .B FULL_FILES
196 flag is recommended for this purpose.
197 The temporary file can be deleted or punched out afterwards.
198 .PP
199 An example program might look like this:
200 .PP
201 .in +4n
202 .EX
203 int fd = open("/some/file", O_RDWR);
204 int temp_fd = open("/some", O_TMPFILE | O_RDWR);
205
206 ioctl(temp_fd, FICLONE, fd);
207
208 /* append 1MB of records */
209 lseek(temp_fd, 0, SEEK_END);
210 write(temp_fd, data1, 1000000);
211
212 /* update record index */
213 pwrite(temp_fd, data1, 600, 98765);
214 pwrite(temp_fd, data2, 320, 54321);
215 pwrite(temp_fd, data2, 15, 0);
216
217 /* commit the entire update */
218 struct xfs_exchange_range args = {
219 .file1_fd = temp_fd,
220 .flags = XFS_EXCHANGE_RANGE_TO_EOF,
221 };
222
223 ioctl(fd, XFS_IOC_EXCHANGE_RANGE, &args);
224 .EE
225 .in
226 .PP
227 The second is a software-defined storage host (e.g. a disk jukebox) which
228 implements an atomic scatter-gather write command.
229 Provided the exported disk's logical block size matches the file's allocation
230 unit size, this can be done by creating a temporary file and writing the data
231 at the appropriate offsets.
232 It is recommended that the temporary file be truncated to the size of the
233 regular file before any writes are staged to the temporary file to avoid issues
234 with zeroing during EOF extension.
235 Use this call with the
236 .B FILE1_WRITTEN
237 flag to exchange only the file allocation units involved in the emulated
238 device's write command.
239 The temporary file should be truncated or punched out completely before being
240 reused to stage another write.
241 .PP
242 An example program might look like this:
243 .PP
244 .in +4n
245 .EX
246 int fd = open("/some/file", O_RDWR);
247 int temp_fd = open("/some", O_TMPFILE | O_RDWR);
248 struct stat sb;
249 int blksz;
250
251 fstat(fd, &sb);
252 blksz = sb.st_blksize;
253
254 /* land scatter gather writes between 100fsb and 500fsb */
255 pwrite(temp_fd, data1, blksz * 2, blksz * 100);
256 pwrite(temp_fd, data2, blksz * 20, blksz * 480);
257 pwrite(temp_fd, data3, blksz * 7, blksz * 257);
258
259 /* commit the entire update */
260 struct xfs_exchange_range args = {
261 .file1_fd = temp_fd,
262 .file1_offset = blksz * 100,
263 .file2_offset = blksz * 100,
264 .length = blksz * 400,
265 .flags = XFS_EXCHANGE_RANGE_FILE1_WRITTEN |
266 XFS_EXCHANGE_RANGE_FILE1_DSYNC,
267 };
268
269 ioctl(fd, XFS_IOC_EXCHANGE_RANGE, &args);
270 .EE
271 .in
272 .B
273 .SH NOTES
274 .PP
275 Some filesystems may limit the amount of data or the number of extents that can
276 be exchanged in a single call.
277 .SH SEE ALSO
278 .BR ioctl (2)