Debian Codegraph @

upstream/fedora-44/man2/io_submit.2

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