1AIO(7) Linux Programmer's Manual AIO(7)
2
3
4
6 aio - POSIX asynchronous I/O overview
7
9 The POSIX asynchronous I/O (AIO) interface allows applications to ini‐
10 tiate one or more I/O operations that are performed asynchronously
11 (i.e., in the background). The application can elect to be notified of
12 completion of the I/O operation in a variety of ways: by delivery of a
13 signal, by instantiation of a thread, or no notification at all.
14
15 The POSIX AIO interface consists of the following functions:
16
17 aio_read(3)
18 Enqueue a read request. This is the asynchronous analog of
19 read(2).
20
21 aio_write(3)
22 Enqueue a write request. This is the asynchronous analog of
23 write(2).
24
25 aio_fsync(3)
26 Enqueue a sync request for the I/O operations on a file descrip‐
27 tor. This is the asynchronous analog of fsync(2) and fdata‐
28 sync(2).
29
30 aio_error(3)
31 Obtain the error status of an enqueued I/O request.
32
33 aio_return(3)
34 Obtain the return status of a completed I/O request.
35
36 aio_suspend(3)
37 Suspend the caller until one or more of a specified set of I/O
38 requests completes.
39
40 aio_cancel(3)
41 Attempt to cancel outstanding I/O requests on a specified file
42 descriptor.
43
44 lio_listio(3)
45 Enqueue multiple I/O requests using a single function call.
46
47 The aiocb ("asynchronous I/O control block") structure defines parame‐
48 ters that control an I/O operation. An argument of this type is
49 employed with all of the functions listed above. This structure has
50 the following form:
51
52 #include <aiocb.h>
53
54 struct aiocb {
55 /* The order of these fields is implementation-dependent */
56
57 int aio_fildes; /* File descriptor */
58 off_t aio_offset; /* File offset */
59 volatile void *aio_buf; /* Location of buffer */
60 size_t aio_nbytes; /* Length of transfer */
61 int aio_reqprio; /* Request priority */
62 struct sigevent aio_sigevent; /* Notification method */
63 int aio_lio_opcode; /* Operation to be performed;
64 lio_listio() only */
65
66 /* Various implementation-internal fields not shown */
67 };
68
69 /* Operation codes for 'aio_lio_opcode': */
70
71 enum { LIO_READ, LIO_WRITE, LIO_NOP };
72
73 The fields of this structure are as follows:
74
75 aio_fildes
76 The file descriptor on which the I/O operation is to be per‐
77 formed.
78
79 aio_offset
80 This is the file offset at which the I/O operation is to be per‐
81 formed.
82
83 aio_buf
84 This is the buffer used to transfer data for a read or write
85 operation.
86
87 aio_nbytes
88 This is the size of the buffer pointed to by aio_buf.
89
90 aio_reqprio
91 This field specifies a value that is subtracted from the calling
92 thread's real-time priority in order to determine the priority
93 for execution of this I/O request (see pthread_setsched‐
94 param(3)). The specified value must be between 0 and the value
95 returned by sysconf(_SC_AIO_PRIO_DELTA_MAX). This field is
96 ignored for file synchronization operations.
97
98 aio_sigevent
99 This field is a structure that specifies how the caller is to be
100 notified when the asynchronous I/O operation completes. Possi‐
101 ble values for aio_sigevent.sigev_notify are SIGEV_NONE,
102 SIGEV_SIGNAL, and SIGEV_THREAD. See sigevent(7) for further
103 details.
104
105 aio_lio_opcode
106 The type of operation to be performed; used only for lio_lis‐
107 tio(3).
108
109 In addition to the standard functions listed above, the GNU C library
110 provides the following extension to the POSIX AIO API:
111
112 aio_init(3)
113 Set parameters for tuning the behavior of the glibc POSIX AIO
114 implementation.
115
117 EINVAL The aio_reqprio field of the aiocb structure was less than 0, or
118 was greater than the limit returned by the call
119 sysconf(_SC_AIO_PRIO_DELTA_MAX).
120
122 The POSIX AIO interfaces are provided by glibc since version 2.1.
123
125 POSIX.1-2001, POSIX.1-2008.
126
128 It is a good idea to zero out the control block buffer before use (see
129 memset(3)). The control block buffer and the buffer pointed to by
130 aio_buf must not be changed while the I/O operation is in progress.
131 These buffers must remain valid until the I/O operation completes.
132
133 Simultaneous asynchronous read or write operations using the same aiocb
134 structure yield undefined results.
135
136 The current Linux POSIX AIO implementation is provided in user space by
137 glibc. This has a number of limitations, most notably that maintaining
138 multiple threads to perform I/O operations is expensive and scales
139 poorly. Work has been in progress for some time on a kernel state-
140 machine-based implementation of asynchronous I/O (see io_submit(2),
141 io_setup(2), io_cancel(2), io_destroy(2), io_getevents(2)), but this
142 implementation hasn't yet matured to the point where the POSIX AIO
143 implementation can be completely reimplemented using the kernel system
144 calls.
145
147 The program below opens each of the files named in its command-line
148 arguments and queues a request on the resulting file descriptor using
149 aio_read(3). The program then loops, periodically monitoring each of
150 the I/O operations that is still in progress using aio_error(3). Each
151 of the I/O requests is set up to provide notification by delivery of a
152 signal. After all I/O requests have completed, the program retrieves
153 their status using aio_return(3).
154
155 The SIGQUIT signal (generated by typing control-\) causes the program
156 to request cancellation of each of the outstanding requests using
157 aio_cancel(3).
158
159 Here is an example of what we might see when running this program. In
160 this example, the program queues two requests to standard input, and
161 these are satisfied by two lines of input containing "abc" and "x".
162
163 $ ./a.out /dev/stdin /dev/stdin
164 opened /dev/stdin on descriptor 3
165 opened /dev/stdin on descriptor 4
166 aio_error():
167 for request 0 (descriptor 3): In progress
168 for request 1 (descriptor 4): In progress
169 abc
170 I/O completion signal received
171 aio_error():
172 for request 0 (descriptor 3): I/O succeeded
173 for request 1 (descriptor 4): In progress
174 aio_error():
175 for request 1 (descriptor 4): In progress
176 x
177 I/O completion signal received
178 aio_error():
179 for request 1 (descriptor 4): I/O succeeded
180 All I/O requests completed
181 aio_return():
182 for request 0 (descriptor 3): 4
183 for request 1 (descriptor 4): 2
184
185 Program source
186
187 #include <fcntl.h>
188 #include <stdlib.h>
189 #include <unistd.h>
190 #include <stdio.h>
191 #include <errno.h>
192 #include <aio.h>
193 #include <signal.h>
194
195 #define BUF_SIZE 20 /* Size of buffers for read operations */
196
197 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0)
198
199 #define errMsg(msg) do { perror(msg); } while (0)
200
201 struct ioRequest { /* Application-defined structure for tracking
202 I/O requests */
203 int reqNum;
204 int status;
205 struct aiocb *aiocbp;
206 };
207
208 static volatile sig_atomic_t gotSIGQUIT = 0;
209 /* On delivery of SIGQUIT, we attempt to
210 cancel all outstanding I/O requests */
211
212 static void /* Handler for SIGQUIT */
213 quitHandler(int sig)
214 {
215 gotSIGQUIT = 1;
216 }
217
218 #define IO_SIGNAL SIGUSR1 /* Signal used to notify I/O completion */
219
220 static void /* Handler for I/O completion signal */
221 aioSigHandler(int sig, siginfo_t *si, void *ucontext)
222 {
223 if (si->si_code == SI_ASYNCIO) {
224 write(STDOUT_FILENO, "I/O completion signal received\n", 31);
225
226 /* The corresponding ioRequest structure would be available as
227 struct ioRequest *ioReq = si->si_value.sival_ptr;
228 and the file descriptor would then be available via
229 ioReq->aiocbp->aio_fildes */
230 }
231 }
232
233 int
234 main(int argc, char *argv[])
235 {
236 struct ioRequest *ioList;
237 struct aiocb *aiocbList;
238 struct sigaction sa;
239 int s, j;
240 int numReqs; /* Total number of queued I/O requests */
241 int openReqs; /* Number of I/O requests still in progress */
242
243 if (argc < 2) {
244 fprintf(stderr, "Usage: %s <pathname> <pathname>...\n",
245 argv[0]);
246 exit(EXIT_FAILURE);
247 }
248
249 numReqs = argc - 1;
250
251 /* Allocate our arrays */
252
253 ioList = calloc(numReqs, sizeof(struct ioRequest));
254 if (ioList == NULL)
255 errExit("calloc");
256
257 aiocbList = calloc(numReqs, sizeof(struct aiocb));
258 if (aiocbList == NULL)
259 errExit("calloc");
260
261 /* Establish handlers for SIGQUIT and the I/O completion signal */
262
263 sa.sa_flags = SA_RESTART;
264 sigemptyset(&sa.sa_mask);
265
266 sa.sa_handler = quitHandler;
267 if (sigaction(SIGQUIT, &sa, NULL) == -1)
268 errExit("sigaction");
269
270 sa.sa_flags = SA_RESTART | SA_SIGINFO;
271 sa.sa_sigaction = aioSigHandler;
272 if (sigaction(IO_SIGNAL, &sa, NULL) == -1)
273 errExit("sigaction");
274
275 /* Open each file specified on the command line, and queue
276 a read request on the resulting file descriptor */
277
278 for (j = 0; j < numReqs; j++) {
279 ioList[j].reqNum = j;
280 ioList[j].status = EINPROGRESS;
281 ioList[j].aiocbp = &aiocbList[j];
282
283 ioList[j].aiocbp->aio_fildes = open(argv[j + 1], O_RDONLY);
284 if (ioList[j].aiocbp->aio_fildes == -1)
285 errExit("open");
286 printf("opened %s on descriptor %d\n", argv[j + 1],
287 ioList[j].aiocbp->aio_fildes);
288
289 ioList[j].aiocbp->aio_buf = malloc(BUF_SIZE);
290 if (ioList[j].aiocbp->aio_buf == NULL)
291 errExit("malloc");
292
293 ioList[j].aiocbp->aio_nbytes = BUF_SIZE;
294 ioList[j].aiocbp->aio_reqprio = 0;
295 ioList[j].aiocbp->aio_offset = 0;
296 ioList[j].aiocbp->aio_sigevent.sigev_notify = SIGEV_SIGNAL;
297 ioList[j].aiocbp->aio_sigevent.sigev_signo = IO_SIGNAL;
298 ioList[j].aiocbp->aio_sigevent.sigev_value.sival_ptr =
299 &ioList[j];
300
301 s = aio_read(ioList[j].aiocbp);
302 if (s == -1)
303 errExit("aio_read");
304 }
305
306 openReqs = numReqs;
307
308 /* Loop, monitoring status of I/O requests */
309
310 while (openReqs > 0) {
311 sleep(3); /* Delay between each monitoring step */
312
313 if (gotSIGQUIT) {
314
315 /* On receipt of SIGQUIT, attempt to cancel each of the
316 outstanding I/O requests, and display status returned
317 from the cancellation requests */
318
319 printf("got SIGQUIT; canceling I/O requests: \n");
320
321 for (j = 0; j < numReqs; j++) {
322 if (ioList[j].status == EINPROGRESS) {
323 printf(" Request %d on descriptor %d:", j,
324 ioList[j].aiocbp->aio_fildes);
325 s = aio_cancel(ioList[j].aiocbp->aio_fildes,
326 ioList[j].aiocbp);
327 if (s == AIO_CANCELED)
328 printf("I/O canceled\n");
329 else if (s == AIO_NOTCANCELED)
330 printf("I/O not canceled\n");
331 else if (s == AIO_ALLDONE)
332 printf("I/O all done\n");
333 else
334 errMsg("aio_cancel");
335 }
336 }
337
338 gotSIGQUIT = 0;
339 }
340
341 /* Check the status of each I/O request that is still
342 in progress */
343
344 printf("aio_error():\n");
345 for (j = 0; j < numReqs; j++) {
346 if (ioList[j].status == EINPROGRESS) {
347 printf(" for request %d (descriptor %d): ",
348 j, ioList[j].aiocbp->aio_fildes);
349 ioList[j].status = aio_error(ioList[j].aiocbp);
350
351 switch (ioList[j].status) {
352 case 0:
353 printf("I/O succeeded\n");
354 break;
355 case EINPROGRESS:
356 printf("In progress\n");
357 break;
358 case ECANCELED:
359 printf("Canceled\n");
360 break;
361 default:
362 errMsg("aio_error");
363 break;
364 }
365
366 if (ioList[j].status != EINPROGRESS)
367 openReqs--;
368 }
369 }
370 }
371
372 printf("All I/O requests completed\n");
373
374 /* Check status return of all I/O requests */
375
376 printf("aio_return():\n");
377 for (j = 0; j < numReqs; j++) {
378 ssize_t s;
379
380 s = aio_return(ioList[j].aiocbp);
381 printf(" for request %d (descriptor %d): %zd\n",
382 j, ioList[j].aiocbp->aio_fildes, s);
383 }
384
385 exit(EXIT_SUCCESS);
386 }
387
389 io_cancel(2), io_destroy(2), io_getevents(2), io_setup(2),
390 io_submit(2), aio_cancel(3), aio_error(3), aio_init(3), aio_read(3),
391 aio_return(3), aio_write(3), lio_listio(3)
392
393 "Asynchronous I/O Support in Linux 2.5", Bhattacharya, Pratt,
394 Pulavarty, and Morgan, Proceedings of the Linux Symposium, 2003,
395 ⟨https://www.kernel.org/doc/ols/2003/ols2003-pages-351-366.pdf⟩
396
398 This page is part of release 5.07 of the Linux man-pages project. A
399 description of the project, information about reporting bugs, and the
400 latest version of this page, can be found at
401 https://www.kernel.org/doc/man-pages/.
402
403
404
405Linux 2020-04-11 AIO(7)