Debian Codegraph @

upstream/mageia-cauldron/man2/io_submit.2

raw
1 .\" Copyright 2003, Free Software Foundation, Inc.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-1.0-or-later
5 .\"
6 .TH io_submit 2 2025-09-21 "Linux man-pages 6.17"
7 .SH NAME
8 io_submit \- submit asynchronous I/O blocks for processing
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .P
13 Alternatively, Asynchronous I/O library
14 .RI ( libaio ,\~ \-laio );
15 see VERSIONS.
16 .SH SYNOPSIS
17 .nf
18 .BR "#include <linux/aio_abi.h>" " /* Defines needed types */"
19 .P
20 .BI "int io_submit(aio_context_t " ctx_id ", long " nr \
21 ", struct iocb **" iocbpp );
22 .fi
23 .P
24 .IR Note :
25 There is no glibc wrapper for this system call;
26 see VERSIONS.
27 .SH DESCRIPTION
28 .IR Note :
29 this page describes the raw Linux system call interface.
30 The wrapper function provided by
31 .I libaio
32 uses a different type for the
33 .I ctx_id
34 argument.
35 See VERSIONS.
36 .P
37 The
38 .BR io_submit ()
39 system call
40 queues
41 .I nr
42 I/O request blocks for processing in
43 the AIO context
44 .IR ctx_id .
45 The
46 .I iocbpp
47 argument should be an array of
48 .I nr
49 AIO control blocks,
50 which will be submitted to context
51 .IR ctx_id .
52 .P
53 The
54 .I iocb
55 (I/O control block) structure defined in
56 .I linux/aio_abi.h
57 defines the parameters that control the I/O operation.
58 .P
59 .in +4n
60 .EX
61 #include <linux/aio_abi.h>
62 \&
63 struct iocb {
64 __u64 aio_data;
65 __u32 PADDED(aio_key, aio_rw_flags);
66 __u16 aio_lio_opcode;
67 __s16 aio_reqprio;
68 __u32 aio_fildes;
69 __u64 aio_buf;
70 __u64 aio_nbytes;
71 __s64 aio_offset;
72 __u64 aio_reserved2;
73 __u32 aio_flags;
74 __u32 aio_resfd;
75 };
76 .EE
77 .in
78 .P
79 The fields of this structure are as follows:
80 .TP
81 .I aio_data
82 This data is copied into the
83 .I data
84 field of the
85 .I io_event
86 structure upon I/O completion (see
87 .BR io_getevents (2)).
88 .TP
89 .I aio_key
90 This is an internal field used by the kernel.
91 Do not modify this field after an
92 .BR io_submit ()
93 call.
94 .TP
95 .I aio_rw_flags
96 This defines the R/W flags passed with structure.
97 The valid values are:
98 .RS
99 .TP
100 .BR RWF_APPEND " (since Linux 4.16)"
101 .\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb
102 Append data to the end of the file.
103 See the description of the flag of the same name in
104 .BR pwritev2 (2)
105 as well as the description of
106 .B O_APPEND
107 in
108 .BR open (2).
109 The
110 .I aio_offset
111 field is ignored.
112 The file offset is not changed.
113 .TP
114 .BR RWF_DSYNC " (since Linux 4.13)"
115 Write operation complete according to requirement of
116 synchronized I/O data integrity.
117 See the description of the flag of the same name in
118 .BR pwritev2 (2)
119 as well the description of
120 .B O_DSYNC
121 in
122 .BR open (2).
123 .TP
124 .BR RWF_HIPRI " (since Linux 4.13)"
125 High priority request, poll if possible
126 .TP
127 .BR RWF_NOWAIT " (since Linux 4.14)"
128 Don't wait if the I/O will block for operations such as
129 file block allocations, dirty page flush, mutex locks,
130 or a congested block device inside the kernel.
131 If any of these conditions are met, the control block is returned
132 immediately with a return value of
133 .B \-EAGAIN
134 in the
135 .I res
136 field of the
137 .I io_event
138 structure (see
139 .BR io_getevents (2)).
140 .TP
141 .BR RWF_SYNC " (since Linux 4.13)"
142 Write operation complete according to requirement of
143 synchronized I/O file integrity.
144 See the description of the flag of the same name in
145 .BR pwritev2 (2)
146 as well the description of
147 .B O_SYNC
148 in
149 .BR open (2).
150 .TP
151 .BR RWF_NOAPPEND " (since Linux 6.9)"
152 Do not honor
153 .B O_APPEND
154 .BR open (2)
155 flag.
156 See the description of
157 .B RWF_NOAPPEND
158 in
159 .BR pwritev2 (2).
160 .TP
161 .BR RWF_ATOMIC " (since Linux 6.11)"
162 Write a block of data such that
163 a write will never be torn from power fail or similar.
164 See the description of
165 .B RWF_ATOMIC
166 in
167 .BR pwritev2 (2).
168 For usage with
169 .BR IOCB_CMD_PWRITEV ,
170 the upper vector limit is
171 .I stx_atomic_write_segments_max.
172 See
173 .B STATX_WRITE_ATOMIC
174 and
175 .I stx_atomic_write_segments_max
176 description
177 in
178 .BR statx (2).
179 .RE
180 .TP
181 .I aio_lio_opcode
182 This defines the type of I/O to be performed by the
183 .I iocb
184 structure.
185 The
186 valid values are defined by the enum defined in
187 .IR linux/aio_abi.h :
188 .IP
189 .in +4n
190 .EX
191 enum {
192 IOCB_CMD_PREAD = 0,
193 IOCB_CMD_PWRITE = 1,
194 IOCB_CMD_FSYNC = 2,
195 IOCB_CMD_FDSYNC = 3,
196 IOCB_CMD_POLL = 5,
197 IOCB_CMD_NOOP = 6,
198 IOCB_CMD_PREADV = 7,
199 IOCB_CMD_PWRITEV = 8,
200 };
201 .EE
202 .in
203 .TP
204 .I aio_reqprio
205 This defines the requests priority.
206 .TP
207 .I aio_fildes
208 The file descriptor on which the I/O operation is to be performed.
209 .TP
210 .I aio_buf
211 This is the buffer used to transfer data for a read or write operation.
212 .TP
213 .I aio_nbytes
214 This is the size of the buffer pointed to by
215 .IR aio_buf .
216 .TP
217 .I aio_offset
218 This is the file offset at which the I/O operation is to be performed.
219 .TP
220 .I aio_flags
221 This is the set of flags associated with the
222 .I iocb
223 structure.
224 The valid values are:
225 .RS
226 .TP
227 .B IOCB_FLAG_RESFD
228 Asynchronous I/O control must signal the file
229 descriptor mentioned in
230 .I aio_resfd
231 upon completion.
232 .TP
233 .BR IOCB_FLAG_IOPRIO " (since Linux 4.18)"
234 .\" commit d9a08a9e616beeccdbd0e7262b7225ffdfa49e92
235 Interpret the
236 .I aio_reqprio
237 field as an
238 .B IOPRIO_VALUE
239 as defined by
240 .IR linux/ioprio.h .
241 .RE
242 .TP
243 .I aio_resfd
244 The file descriptor to signal in the event of asynchronous I/O completion.
245 .SH RETURN VALUE
246 On success,
247 .BR io_submit ()
248 returns the number of
249 .IR iocb s
250 submitted
251 (which may be
252 less than
253 .IR nr ,
254 or 0 if
255 .I nr
256 is zero).
257 For the failure return, see VERSIONS.
258 .SH ERRORS
259 .TP
260 .B EAGAIN
261 Insufficient resources are available to queue any
262 .IR iocb s.
263 .TP
264 .B EBADF
265 The file descriptor specified in the first
266 .I iocb
267 is invalid.
268 .TP
269 .B EFAULT
270 One of the data structures points to invalid data.
271 .TP
272 .B EINVAL
273 The AIO context specified by
274 .I ctx_id
275 is invalid.
276 .I nr
277 is less than 0.
278 The
279 .I iocb
280 at
281 .I *iocbpp[0]
282 is not properly initialized, the operation specified is invalid for the file
283 descriptor in the
284 .IR iocb ,
285 or the value in the
286 .I aio_reqprio
287 field is invalid.
288 .TP
289 .B ENOSYS
290 .BR io_submit ()
291 is not implemented on this architecture.
292 .TP
293 .B EPERM
294 The
295 .I aio_reqprio
296 field is set with the class
297 .BR IOPRIO_CLASS_RT ,
298 but the submitting context does not have the
299 .B CAP_SYS_ADMIN
300 capability.
301 .SH VERSIONS
302 glibc does not provide a wrapper for this system call.
303 You could invoke it using
304 .BR syscall (2).
305 But instead, you probably want to use the
306 .BR io_submit ()
307 wrapper function provided by
308 .\" http://git.fedorahosted.org/git/?p=libaio.git
309 .IR libaio .
310 .P
311 Note that the
312 .I libaio
313 wrapper function uses a different type
314 .RI ( io_context_t )
315 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
316 .\" the system call.
317 for the
318 .I ctx_id
319 argument.
320 Note also that the
321 .I libaio
322 wrapper does not follow the usual C library conventions for indicating errors:
323 on error it returns a negated error number
324 (the negative of one of the values listed in ERRORS).
325 If the system call is invoked via
326 .BR syscall (2),
327 then the return value follows the usual conventions for
328 indicating an error: \-1, with
329 .I errno
330 set to a (positive) value that indicates the error.
331 .SH STANDARDS
332 Linux.
333 .SH HISTORY
334 Linux 2.5.
335 .SH SEE ALSO
336 .BR io_cancel (2),
337 .BR io_destroy (2),
338 .BR io_getevents (2),
339 .BR io_setup (2),
340 .BR aio (7)
341 .\" .SH AUTHOR
342 .\" Kent Yoder.