Debian Codegraph @

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