| blob | 7eccba170bdc924db058a40c8a452478edccb262 |
1 .\" Copyright (C) 2003 Free Software Foundation, Inc.
2 .\" and Copyright (C) 2017 Goldwyn Rodrigues <rgoldwyn@suse.de>
3 .\"
4 .\" SPDX-License-Identifier: GPL-1.0-or-later
5 .\"
6 .TH IO_SUBMIT 2 2021-03-22 "Linux man-pages (unreleased)"
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 .PP
13 Alternatively, Asynchronous I/O library
14 .RI ( libaio ", " \-laio );
15 see NOTES.
16 .SH SYNOPSIS
17 .nf
18 .BR "#include <linux/aio_abi.h>" " /* Defines needed types */"
19 .PP
20 .BI "int io_submit(aio_context_t " ctx_id ", long " nr \
21 ", struct iocb **" iocbpp );
22 .fi
23 .PP
24 .IR Note :
25 There is no glibc wrapper for this system call; see NOTES.
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 NOTES.
35 .PP
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 .PP
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 .PP
52 .in +4n
53 .EX
54 #include <linux/aio_abi.h>
56 struct iocb {
57 uint64_t aio_data;
58 uint32_t PADDED(aio_key, aio_rw_flags);
59 uint16_t aio_lio_opcode;
60 int16_t aio_reqprio;
61 uint32_t aio_fildes;
62 uint64_t aio_buf;
63 uint64_t aio_nbytes;
64 int64_t aio_offset;
65 uint64_t aio_reserved2;
66 uint32_t aio_flags;
67 uint32_t aio_resfd;
68 };
69 .EE
70 .in
71 .PP
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 .RE
144 .TP
145 .I aio_lio_opcode
146 This defines the type of I/O to be performed by the
147 .I iocb
148 structure.
149 The
150 valid values are defined by the enum defined in
151 .IR linux/aio_abi.h :
152 .IP
153 .in +4n
154 .EX
155 enum {
156 IOCB_CMD_PREAD = 0,
157 IOCB_CMD_PWRITE = 1,
158 IOCB_CMD_FSYNC = 2,
159 IOCB_CMD_FDSYNC = 3,
160 IOCB_CMD_POLL = 5,
161 IOCB_CMD_NOOP = 6,
162 IOCB_CMD_PREADV = 7,
163 IOCB_CMD_PWRITEV = 8,
164 };
165 .EE
166 .in
167 .TP
168 .I aio_reqprio
169 This defines the requests priority.
170 .TP
171 .I aio_fildes
172 The file descriptor on which the I/O operation is to be performed.
173 .TP
174 .I aio_buf
175 This is the buffer used to transfer data for a read or write operation.
176 .TP
177 .I aio_nbytes
178 This is the size of the buffer pointed to by
179 .IR aio_buf .
180 .TP
181 .I aio_offset
182 This is the file offset at which the I/O operation is to be performed.
183 .TP
184 .I aio_flags
185 This is the set of flags associated with the
186 .I iocb
187 structure.
188 The valid values are:
189 .RS
190 .TP
191 .B IOCB_FLAG_RESFD
192 Asynchronous I/O control must signal the file
193 descriptor mentioned in
194 .I aio_resfd
195 upon completion.
196 .TP
197 .BR IOCB_FLAG_IOPRIO " (since Linux 4.18)"
198 .\" commit d9a08a9e616beeccdbd0e7262b7225ffdfa49e92
199 Interpret the
200 .I aio_reqprio
201 field as an
202 .B IOPRIO_VALUE
203 as defined by
204 .IR linux/ioprio.h .
205 .RE
206 .TP
207 .I aio_resfd
208 The file descriptor to signal in the event of asynchronous I/O completion.
209 .SH RETURN VALUE
210 On success,
211 .BR io_submit ()
212 returns the number of \fIiocb\fPs submitted (which may be
213 less than \fInr\fP, or 0 if \fInr\fP is zero).
214 For the failure return, see NOTES.
215 .SH ERRORS
216 .TP
217 .B EAGAIN
218 Insufficient resources are available to queue any \fIiocb\fPs.
219 .TP
220 .B EBADF
221 The file descriptor specified in the first \fIiocb\fP is invalid.
222 .TP
223 .B EFAULT
224 One of the data structures points to invalid data.
225 .TP
226 .B EINVAL
227 The AIO context specified by \fIctx_id\fP is invalid.
228 \fInr\fP is less than 0.
229 The \fIiocb\fP at
230 .I *iocbpp[0]
231 is not properly initialized, the operation specified is invalid for the file
232 descriptor in the \fIiocb\fP, or the value in the
233 .I aio_reqprio
234 field is invalid.
235 .TP
236 .B ENOSYS
237 .BR io_submit ()
238 is not implemented on this architecture.
239 .TP
240 .B EPERM
241 The
242 .I aio_reqprio
243 field is set with the class
244 .BR IOPRIO_CLASS_RT ,
245 but the submitting context does not have the
246 .B CAP_SYS_ADMIN
247 capability.
248 .SH VERSIONS
249 The asynchronous I/O system calls first appeared in Linux 2.5.
250 .SH STANDARDS
251 .BR io_submit ()
252 is Linux-specific and should not be used in
253 programs that are intended to be portable.
254 .SH NOTES
255 Glibc does not provide a wrapper for this system call.
256 You could invoke it using
257 .BR syscall (2).
258 But instead, you probably want to use the
259 .BR io_submit ()
260 wrapper function provided by
261 .\" http://git.fedorahosted.org/git/?p=libaio.git
262 .IR libaio .
263 .PP
264 Note that the
265 .I libaio
266 wrapper function uses a different type
267 .RI ( io_context_t )
268 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
269 .\" the system call.
270 for the
271 .I ctx_id
272 argument.
273 Note also that the
274 .I libaio
275 wrapper does not follow the usual C library conventions for indicating errors:
276 on error it returns a negated error number
277 (the negative of one of the values listed in ERRORS).
278 If the system call is invoked via
279 .BR syscall (2),
280 then the return value follows the usual conventions for
281 indicating an error: \-1, with
282 .I errno
283 set to a (positive) value that indicates the error.
284 .SH SEE ALSO
285 .BR io_cancel (2),
286 .BR io_destroy (2),
287 .BR io_getevents (2),
288 .BR io_setup (2),
289 .BR aio (7)
290 .\" .SH AUTHOR
291 .\" Kent Yoder.