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