-
Notifications
You must be signed in to change notification settings - Fork 0
/
io_submit.html
381 lines (279 loc) · 10.4 KB
/
io_submit.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jan 29 11:26:57 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>IO_SUBMIT</title>
</head>
<body>
<h1 align="center">IO_SUBMIT</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#VERSIONS">VERSIONS</a><br>
<a href="#CONFORMING TO">CONFORMING TO</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#COLOPHON">COLOPHON</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">io_submit -
submit asynchronous I/O blocks for processing</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>#include
<linux/aio_abi.h></b> /* Defines needed types */</p>
<p style="margin-left:11%; margin-top: 1em"><b>int
io_submit(aio_context_t</b> <i>ctx_id</i><b>, long</b>
<i>nr</i><b>, struct iocb **</b><i>iocbpp</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><i>Note</i>:
There is no glibc wrapper for this system call; see
NOTES.</p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The
<b>io_submit</b>() system call queues <i>nr</i> I/O request
blocks for processing in the AIO context <i>ctx_id</i>. The
<i>iocbpp</i> argument should be an array of <i>nr</i> AIO
control blocks, which will be submitted to context
<i>ctx_id</i>.</p>
<p style="margin-left:11%; margin-top: 1em">The <i>iocb</i>
(I/O control block) structure defined in
<i>linux/aio_abi.h</i> defines the parameters that control
the I/O operation.</p>
<p style="margin-left:17%; margin-top: 1em">#include
<linux/aio_abi.h></p>
<p style="margin-left:17%; margin-top: 1em">struct iocb {
<br>
__u64 aio_data; <br>
__u32 PADDED(aio_key, aio_rw_flags); <br>
__u16 aio_lio_opcode; <br>
__s16 aio_reqprio; <br>
__u32 aio_fildes; <br>
__u64 aio_buf; <br>
__u64 aio_nbytes; <br>
__s64 aio_offset; <br>
__u64 aio_reserved2; <br>
__u32 aio_flags; <br>
__u32 aio_resfd; <br>
};</p>
<p style="margin-left:11%; margin-top: 1em">The fields of
this structure are as follows: <i><br>
aio_data</i></p>
<p style="margin-left:22%;">This data is copied into the
<i>data</i> field of the <i>io_event</i> structure upon I/O
completion (see <b>io_getevents</b>(2)).</p>
<p style="margin-left:11%;"><i>aio_key</i></p>
<p style="margin-left:22%;">This is an internal field used
by the kernel. Do not modify this field after an
<b>io_submit</b>(2) call.</p>
<p style="margin-left:11%;"><i>aio_rw_flags</i></p>
<p style="margin-left:22%;">This defines the R/W flags
passed with structure. The valid values are: <b><br>
RWF_APPEND</b> (since Linux 4.16)</p>
<p style="margin-left:32%;">Append data to the end of the
file. See the description of the flag of the same name in
<b>pwritev2</b>(2) as well as the description of
<b>O_APPEND</b> in <b>open</b>(2). The <i>aio_offset</i>
field is ignored. The file offset is not changed.</p>
<p style="margin-left:22%;"><b>RWF_DSYNC</b> (since Linux
4.7)</p>
<p style="margin-left:32%;">Write operation complete
according to requirement of synchronized I/O data integrity.
See the description of the flag of the same name in
<b>pwritev2</b>(2) as well the description of <b>O_DSYNC</b>
in <b>open</b>(2).</p>
<p style="margin-left:22%;"><b>RWF_HIPRI</b> (since Linux
4.6)</p>
<p style="margin-left:32%;">High priority request, poll if
possible</p>
<p style="margin-left:22%;"><b>RWF_NOWAIT</b> (since Linux
4.14)</p>
<p style="margin-left:32%;">Don’t wait if the I/O
will block for operations such as file block allocations,
dirty page flush, mutex locks, or a congested block device
inside the kernel. If any of these conditions are met, the
control block is returned immediately with a return value of
<b>-EAGAIN</b> in the <i>res</i> field of the
<i>io_event</i> structure (see <b>io_getevents</b>(2)).</p>
<p style="margin-left:22%;"><b>RWF_SYNC</b> (since Linux
4.7)</p>
<p style="margin-left:32%;">Write operation complete
according to requirement of synchronized I/O file integrity.
See the description of the flag of the same name in
<b>pwritev2</b>(2) as well the description of <b>O_SYNC</b>
in <b>open</b>(2).</p>
<p style="margin-left:11%;"><i>aio_lio_opcode</i></p>
<p style="margin-left:22%;">This defines the type of I/O to
be performed by the <i>iocb</i> structure. The valid values
are defined by the enum defined in
<i>linux/aio_abi.h</i>:</p>
<p style="margin-left:28%; margin-top: 1em">enum { <br>
IOCB_CMD_PREAD = 0, <br>
IOCB_CMD_PWRITE = 1, <br>
IOCB_CMD_FSYNC = 2, <br>
IOCB_CMD_FDSYNC = 3, <br>
IOCB_CMD_NOOP = 6, <br>
IOCB_CMD_PREADV = 7, <br>
IOCB_CMD_PWRITEV = 8, <br>
};</p>
<p style="margin-left:11%;"><i>aio_reqprio</i></p>
<p style="margin-left:22%;">This defines the requests
priority.</p>
<p style="margin-left:11%;"><i>aio_fildes</i></p>
<p style="margin-left:22%;">The file descriptor on which
the I/O operation is to be performed.</p>
<p style="margin-left:11%;"><i>aio_buf</i></p>
<p style="margin-left:22%;">This is the buffer used to
transfer data for a read or write operation.</p>
<p style="margin-left:11%;"><i>aio_nbytes</i></p>
<p style="margin-left:22%;">This is the size of the buffer
pointed to by <i>aio_buf</i>.</p>
<p style="margin-left:11%;"><i>aio_offset</i></p>
<p style="margin-left:22%;">This is the file offset at
which the I/O operation is to be performed.</p>
<p style="margin-left:11%;"><i>aio_flags</i></p>
<p style="margin-left:22%;">This is the set of flags
associated with the <i>iocb</i> structure. The valid values
are: <b><br>
IOCB_FLAG_RESFD</b></p>
<p style="margin-left:32%;">Asynchronous I/O control must
signal the file descriptor mentioned in <i>aio_resfd</i>
upon completion.</p>
<p style="margin-left:22%;"><b>IOCB_FLAG_IOPRIO</b> (since
Linux 4.18)</p>
<p style="margin-left:32%;">Interpret the
<i>aio_reqprio</i> field as an <b>IOPRIO_VALUE</b> as
defined by <i>linux/ioprio.h</i>.</p>
<p style="margin-left:11%;"><i>aio_resfd</i></p>
<p style="margin-left:22%;">The file descriptor to signal
in the event of asynchronous I/O completion.</p>
<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">On success,
<b>io_submit</b>() returns the number of <i>iocb</i>s
submitted (which may be less than <i>nr</i>, or 0 if
<i>nr</i> is zero). For the failure return, see NOTES.</p>
<h2>ERRORS
<a name="ERRORS"></a>
</h2>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p style="margin-top: 1em"><b>EAGAIN</b></p></td>
<td width="2%"></td>
<td width="78%">
<p style="margin-top: 1em">Insufficient resources are
available to queue any <i>iocb</i>s.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EBADF</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The file descriptor specified in the first <i>iocb</i>
is invalid.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EFAULT</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>One of the data structures points to invalid data.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The AIO context specified by <i>ctx_id</i> is invalid.
<i>nr</i> is less than 0. The <i>iocb</i> at
<i>*iocbpp[0]</i> is not properly initialized, the operation
specified is invalid for the file descriptor in the
<i>iocb</i>, or the value in the <i>aio_reqprio</i> field is
invalid.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>ENOSYS</b></p></td>
<td width="2%"></td>
<td width="78%">
<p><b>io_submit</b>() is not implemented on this
architecture.</p> </td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EPERM</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The <i>aio_reqprio</i> field is set with the class
<b>IOPRIO_CLASS_RT</b>, but the submitting context does not
have the <b>CAP_SYS_ADMIN</b> capability.</p></td></tr>
</table>
<h2>VERSIONS
<a name="VERSIONS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The
asynchronous I/O system calls first appeared in Linux
2.5.</p>
<h2>CONFORMING TO
<a name="CONFORMING TO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>io_submit</b>()
is Linux-specific and should not be used in programs that
are intended to be portable.</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">Glibc does not
provide a wrapper function for this system call. You could
invoke it using <b>syscall</b>(2). But instead, you probably
want to use the <b>io_submit</b>() wrapper function provided
by <i>libaio</i>.</p>
<p style="margin-left:11%; margin-top: 1em">Note that the
<i>libaio</i> wrapper function uses a different type
(<i>io_context_t</i>) for the <i>ctx_id</i> argument. Note
also that the <i>libaio</i> wrapper does not follow the
usual C library conventions for indicating errors: on error
it returns a negated error number (the negative of one of
the values listed in ERRORS). If the system call is invoked
via <b>syscall</b>(2), then the return value follows the
usual conventions for indicating an error: -1, with
<i>errno</i> set to a (positive) value that indicates the
error.</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>io_cancel</b>(2),
<b>io_destroy</b>(2), <b>io_getevents</b>(2),
<b>io_setup</b>(2), <b>aio</b>(7)</p>
<h2>COLOPHON
<a name="COLOPHON"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">This page is
part of release 5.02 of the Linux <i>man-pages</i> project.
A description of the project, information about reporting
bugs, and the latest version of this page, can be found at
https://www.kernel.org/doc/man-pages/.</p>
<hr>
</body>
</html>