1 .\" Copyright (C) 2003 Free Software Foundation, Inc.
2 .\" and Copyright (C) 2017 Goldwyn Rodrigues <rgoldwyn@suse.de>
4 .\" SPDX-License-Identifier: GPL-1.0-or-later
6 .TH IO_SUBMIT 2 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
8 io_submit \- submit asynchronous I/O blocks for processing
11 .RI ( libc ", " \-lc )
13 Alternatively, Asynchronous I/O library
14 .RI ( libaio ", " \-laio );
18 .BR "#include <linux/aio_abi.h>" " /* Defines needed types */"
20 .BI "int io_submit(aio_context_t " ctx_id ", long " nr \
21 ", struct iocb **" iocbpp );
25 There is no glibc wrapper for this system call; see NOTES.
28 this page describes the raw Linux system call interface.
29 The wrapper function provided by
31 uses a different type for the
39 queues \fInr\fP I/O request blocks for processing in
40 the AIO context \fIctx_id\fP.
43 argument should be an array of \fInr\fP AIO control blocks,
44 which will be submitted to context \fIctx_id\fP.
48 (I/O control block) structure defined in
50 defines the parameters that control the I/O operation.
54 #include <linux/aio_abi.h>
58 __u32 PADDED(aio_key, aio_rw_flags);
72 The fields of this structure are as follows:
75 This data is copied into the
79 structure upon I/O completion (see
80 .BR io_getevents (2)).
83 This is an internal field used by the kernel.
84 Do not modify this field after an
89 This defines the R/W flags passed with structure.
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
98 as well as the description of
105 The file offset is not changed.
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
112 as well the description of
117 .BR RWF_HIPRI " (since Linux 4.13)"
118 High priority request, poll if possible
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
132 .BR io_getevents (2)).
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
139 as well the description of
146 This defines the type of I/O to be performed by the
150 valid values are defined by the enum defined in
151 .IR linux/aio_abi.h :
163 IOCB_CMD_PWRITEV = 8,
169 This defines the requests priority.
172 The file descriptor on which the I/O operation is to be performed.
175 This is the buffer used to transfer data for a read or write operation.
178 This is the size of the buffer pointed to by
182 This is the file offset at which the I/O operation is to be performed.
185 This is the set of flags associated with the
188 The valid values are:
192 Asynchronous I/O control must signal the file
193 descriptor mentioned in
197 .BR IOCB_FLAG_IOPRIO " (since Linux 4.18)"
198 .\" commit d9a08a9e616beeccdbd0e7262b7225ffdfa49e92
208 The file descriptor to signal in the event of asynchronous I/O completion.
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.
218 Insufficient resources are available to queue any \fIiocb\fPs.
221 The file descriptor specified in the first \fIiocb\fP is invalid.
224 One of the data structures points to invalid data.
227 The AIO context specified by \fIctx_id\fP is invalid.
228 \fInr\fP is less than 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
238 is not implemented on this architecture.
243 field is set with the class
244 .BR IOPRIO_CLASS_RT ,
245 but the submitting context does not have the
249 The asynchronous I/O system calls first appeared in Linux 2.5.
252 is Linux-specific and should not be used in
253 programs that are intended to be portable.
255 Glibc does not provide a wrapper for this system call.
256 You could invoke it using
258 But instead, you probably want to use the
260 wrapper function provided by
261 .\" http://git.fedorahosted.org/git/?p=libaio.git
266 wrapper function uses a different type
268 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
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
280 then the return value follows the usual conventions for
281 indicating an error: \-1, with
283 set to a (positive) value that indicates the error.
287 .BR io_getevents (2),