]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 2003 Free Software Foundation, Inc. |
2be12b9e | 2 | .\" and Copyright (C) 2017 Goldwyn Rodrigues <rgoldwyn@suse.de> |
2297bf0e | 3 | .\" |
95fb8859 | 4 | .\" SPDX-License-Identifier: GPL-1.0-or-later |
fea681da | 5 | .\" |
45186a5d | 6 | .TH IO_SUBMIT 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da | 7 | .SH NAME |
d12c1424 | 8 | io_submit \- submit asynchronous I/O blocks for processing |
6b68f13c AC |
9 | .SH LIBRARY |
10 | Standard C library | |
8fc3b2cf | 11 | .RI ( libc ", " \-lc ) |
6b68f13c AC |
12 | .PP |
13 | Alternatively, Asynchronous I/O library | |
8fc3b2cf | 14 | .RI ( libaio ", " \-laio ); |
6b68f13c | 15 | see NOTES. |
47297adb | 16 | .SH SYNOPSIS |
d12c1424 | 17 | .nf |
e1c5ebfa | 18 | .BR "#include <linux/aio_abi.h>" " /* Defines needed types */" |
dbfe9c70 | 19 | .PP |
1d597481 | 20 | .BI "int io_submit(aio_context_t " ctx_id ", long " nr \ |
d12c1424 | 21 | ", struct iocb **" iocbpp ); |
d12c1424 | 22 | .fi |
dbfe9c70 | 23 | .PP |
45c99e3e MK |
24 | .IR Note : |
25 | There is no glibc wrapper for this system call; see NOTES. | |
47297adb | 26 | .SH DESCRIPTION |
1d597481 AC |
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 | |
e1c5ebfa | 36 | The |
60a90ecd | 37 | .BR io_submit () |
e1c5ebfa | 38 | system call |
a8d55537 MK |
39 | queues \fInr\fP I/O request blocks for processing in |
40 | the AIO context \fIctx_id\fP. | |
e1c5ebfa MK |
41 | The |
42 | .I iocbpp | |
43 | argument should be an array of \fInr\fP AIO control blocks, | |
a8d55537 | 44 | which will be submitted to context \fIctx_id\fP. |
2be12b9e | 45 | .PP |
7a62a055 GR |
46 | The |
47 | .I iocb | |
2be12b9e | 48 | (I/O control block) structure defined in |
1ae6b2c7 | 49 | .I linux/aio_abi.h |
7a62a055 GR |
50 | defines the parameters that control the I/O operation. |
51 | .PP | |
52 | .in +4n | |
2be12b9e | 53 | .EX |
7a62a055 GR |
54 | #include <linux/aio_abi.h> |
55 | ||
56 | struct iocb { | |
2be12b9e MK |
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; | |
7a62a055 | 68 | }; |
2be12b9e | 69 | .EE |
7a62a055 | 70 | .in |
2be12b9e | 71 | .PP |
7a62a055 GR |
72 | The fields of this structure are as follows: |
73 | .TP | |
74 | .I aio_data | |
19dc28eb JM |
75 | This data is copied into the |
76 | .I data | |
77 | field of the | |
78 | .I io_event | |
dcd7215c MK |
79 | structure upon I/O completion (see |
80 | .BR io_getevents (2)). | |
7a62a055 GR |
81 | .TP |
82 | .I aio_key | |
a8d5f567 | 83 | This is an internal field used by the kernel. |
bfddbad0 | 84 | Do not modify this field after an |
549597a8 | 85 | .BR io_submit () |
7a62a055 GR |
86 | call. |
87 | .TP | |
88 | .I aio_rw_flags | |
bfddbad0 MK |
89 | This defines the R/W flags passed with structure. |
90 | The valid values are: | |
7a62a055 GR |
91 | .RS |
92 | .TP | |
9d2d82ff MK |
93 | .BR RWF_APPEND " (since Linux 4.16)" |
94 | .\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb | |
95 | Append data to the end of the file. | |
e9b96f13 MK |
96 | See the description of the flag of the same name in |
97 | .BR pwritev2 (2) | |
9d2d82ff MK |
98 | as well as the description of |
99 | .B O_APPEND | |
e9b96f13 | 100 | in |
2be12b9e | 101 | .BR open (2). |
9d2d82ff MK |
102 | The |
103 | .I aio_offset | |
104 | field is ignored. | |
105 | The file offset is not changed. | |
7a62a055 | 106 | .TP |
17ea6db2 | 107 | .BR RWF_DSYNC " (since Linux 4.13)" |
bfddbad0 | 108 | Write operation complete according to requirement of |
9d2d82ff | 109 | synchronized I/O data integrity. |
e9b96f13 MK |
110 | See the description of the flag of the same name in |
111 | .BR pwritev2 (2) | |
112 | as well the description of | |
9d2d82ff | 113 | .B O_DSYNC |
e9b96f13 | 114 | in |
2be12b9e | 115 | .BR open (2). |
7a62a055 | 116 | .TP |
17ea6db2 | 117 | .BR RWF_HIPRI " (since Linux 4.13)" |
9d2d82ff MK |
118 | High priority request, poll if possible |
119 | .TP | |
2f72816f | 120 | .BR RWF_NOWAIT " (since Linux 4.14)" |
bfddbad0 MK |
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 | |
2be12b9e MK |
126 | .B \-EAGAIN |
127 | in the | |
128 | .I res | |
129 | field of the | |
130 | .I io_event | |
55d59b9b MK |
131 | structure (see |
132 | .BR io_getevents (2)). | |
7ac27e31 | 133 | .TP |
17ea6db2 | 134 | .BR RWF_SYNC " (since Linux 4.13)" |
9d2d82ff MK |
135 | Write operation complete according to requirement of |
136 | synchronized I/O file integrity. | |
7ac27e31 JB |
137 | See the description of the flag of the same name in |
138 | .BR pwritev2 (2) | |
9d2d82ff MK |
139 | as well the description of |
140 | .B O_SYNC | |
7ac27e31 JB |
141 | in |
142 | .BR open (2). | |
7a62a055 GR |
143 | .RE |
144 | .TP | |
145 | .I aio_lio_opcode | |
8092a5c8 MK |
146 | This defines the type of I/O to be performed by the |
147 | .I iocb | |
148 | structure. | |
bfddbad0 | 149 | The |
2be12b9e MK |
150 | valid values are defined by the enum defined in |
151 | .IR linux/aio_abi.h : | |
152 | .IP | |
161b8eda | 153 | .in +4n |
2be12b9e | 154 | .EX |
7a62a055 | 155 | enum { |
2be12b9e MK |
156 | IOCB_CMD_PREAD = 0, |
157 | IOCB_CMD_PWRITE = 1, | |
158 | IOCB_CMD_FSYNC = 2, | |
159 | IOCB_CMD_FDSYNC = 3, | |
af238773 | 160 | IOCB_CMD_POLL = 5, |
2be12b9e MK |
161 | IOCB_CMD_NOOP = 6, |
162 | IOCB_CMD_PREADV = 7, | |
163 | IOCB_CMD_PWRITEV = 8, | |
7a62a055 | 164 | }; |
2be12b9e | 165 | .EE |
7a62a055 GR |
166 | .in |
167 | .TP | |
168 | .I aio_reqprio | |
169 | This defines the requests priority. | |
170 | .TP | |
b085fc1f | 171 | .I aio_fildes |
7a62a055 GR |
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 | |
a1268155 MK |
185 | This is the set of flags associated with the |
186 | .I iocb | |
187 | structure. | |
54028200 AM |
188 | The valid values are: |
189 | .RS | |
190 | .TP | |
1ae6b2c7 | 191 | .B IOCB_FLAG_RESFD |
54028200 | 192 | Asynchronous I/O control must signal the file |
7a62a055 GR |
193 | descriptor mentioned in |
194 | .I aio_resfd | |
195 | upon completion. | |
196 | .TP | |
54028200 AM |
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 | |
a1268155 | 204 | .IR linux/ioprio.h . |
54028200 AM |
205 | .RE |
206 | .TP | |
7a62a055 GR |
207 | .I aio_resfd |
208 | The file descriptor to signal in the event of asynchronous I/O completion. | |
47297adb | 209 | .SH RETURN VALUE |
c13182ef | 210 | On success, |
60a90ecd | 211 | .BR io_submit () |
a8d55537 | 212 | returns the number of \fIiocb\fPs submitted (which may be |
ccf7d8ec | 213 | less than \fInr\fP, or 0 if \fInr\fP is zero). |
24d2f49a | 214 | For the failure return, see NOTES. |
47297adb | 215 | .SH ERRORS |
fea681da | 216 | .TP |
c4e45390 MK |
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 | |
d12c1424 | 226 | .B EINVAL |
e1c5ebfa | 227 | The AIO context specified by \fIctx_id\fP is invalid. |
a8d55537 | 228 | \fInr\fP is less than 0. |
e1c5ebfa MK |
229 | The \fIiocb\fP at |
230 | .I *iocbpp[0] | |
54028200 AM |
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. | |
fea681da | 235 | .TP |
d12c1424 | 236 | .B ENOSYS |
60a90ecd MK |
237 | .BR io_submit () |
238 | is not implemented on this architecture. | |
54028200 AM |
239 | .TP |
240 | .B EPERM | |
a1268155 MK |
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 | |
54028200 | 246 | .B CAP_SYS_ADMIN |
a1268155 | 247 | capability. |
47297adb | 248 | .SH VERSIONS |
e1c5ebfa | 249 | The asynchronous I/O system calls first appeared in Linux 2.5. |
3113c7f3 | 250 | .SH STANDARDS |
60a90ecd | 251 | .BR io_submit () |
8382f16d | 252 | is Linux-specific and should not be used in |
75b48e9d | 253 | programs that are intended to be portable. |
24d2f49a | 254 | .SH NOTES |
16cc03ca | 255 | Glibc does not provide a wrapper for this system call. |
e1c5ebfa MK |
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 . | |
efeece04 | 263 | .PP |
e1c5ebfa | 264 | Note that the |
24d2f49a | 265 | .I libaio |
e1c5ebfa MK |
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: | |
24d2f49a MK |
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. | |
47297adb | 284 | .SH SEE ALSO |
c4e45390 | 285 | .BR io_cancel (2), |
60a90ecd | 286 | .BR io_destroy (2), |
364008ba | 287 | .BR io_getevents (2), |
ff0c3278 MK |
288 | .BR io_setup (2), |
289 | .BR aio (7) | |
d12c1424 MK |
290 | .\" .SH AUTHOR |
291 | .\" Kent Yoder. |