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