2 .\" Copyright (c) 2010 by Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH AIO 7 2016-03-15 "Linux" "Linux Programmer's Manual"
28 aio \- POSIX asynchronous I/O overview
30 The POSIX asynchronous I/O (AIO) interface allows applications
31 to initiate one or more I/O operations that are performed
32 asynchronously (i.e., in the background).
33 The application can elect to be notified of completion of
34 the I/O operation in a variety of ways:
35 by delivery of a signal, by instantiation of a thread,
36 or no notification at all.
38 The POSIX AIO interface consists of the following functions:
41 Enqueue a read request.
42 This is the asynchronous analog of
46 Enqueue a write request.
47 This is the asynchronous analog of
51 Enqueue a sync request for the I/O operations on a file descriptor.
52 This is the asynchronous analog of
58 Obtain the error status of an enqueued I/O request.
61 Obtain the return status of a completed I/O request.
64 Suspend the caller until one or more of a specified set of
65 I/O requests completes.
68 Attempt to cancel outstanding I/O requests on a specified
72 Enqueue multiple I/O requests using a single function call.
76 ("asynchronous I/O control block") structure defines
77 parameters that control an I/O operation.
78 An argument of this type is employed with all of the functions listed above.
79 This structure has the following form:
86 /* The order of these fields is implementation-dependent */
88 int aio_fildes; /* File descriptor */
89 off_t aio_offset; /* File offset */
90 volatile void *aio_buf; /* Location of buffer */
91 size_t aio_nbytes; /* Length of transfer */
92 int aio_reqprio; /* Request priority */
93 struct sigevent aio_sigevent; /* Notification method */
94 int aio_lio_opcode; /* Operation to be performed;
97 /* Various implementation-internal fields not shown */
100 /* Operation codes for \(aqaio_lio_opcode\(aq: */
102 enum { LIO_READ, LIO_WRITE, LIO_NOP };
106 The fields of this structure are as follows:
109 The file descriptor on which the I/O operation is to be performed.
112 This is the file offset at which the I/O operation is to be performed.
115 This is the buffer used to transfer data for a read or write operation.
118 This is the size of the buffer pointed to by
122 This field specifies a value that is subtracted
123 from the calling thread's real-time priority in order to
124 determine the priority for execution of this I/O request (see
125 .BR pthread_setschedparam (3)).
126 The specified value must be between 0 and the value returned by
127 .IR sysconf(_SC_AIO_PRIO_DELTA_MAX) .
128 This field is ignored for file synchronization operations.
131 This field is a structure that specifies how the caller is
132 to be notified when the asynchronous I/O operation completes.
134 .IR aio_sigevent.sigev_notify
145 The type of operation to be performed; used only for
148 In addition to the standard functions listed above,
149 the GNU C library provides the following extension to the POSIX AIO API:
152 Set parameters for tuning the behavior of the glibc POSIX AIO implementation.
160 structure was less than 0,
161 or was greater than the limit returned by the call
162 .IR sysconf(_SC_AIO_PRIO_DELTA_MAX) .
164 The POSIX AIO interfaces are provided by glibc since version 2.1.
166 POSIX.1-2001, POSIX.1-2008.
168 It is a good idea to zero out the control block buffer before use (see
170 The control block buffer and the buffer pointed to by
172 must not be changed while the I/O operation is in progress.
173 These buffers must remain valid until the I/O operation completes.
175 Simultaneous asynchronous read or write operations using the same
177 structure yield undefined results.
179 The current Linux POSIX AIO implementation is provided in user space by glibc.
180 This has a number of limitations, most notably that maintaining multiple
181 threads to perform I/O operations is expensive and scales poorly.
182 Work has been in progress for some time on a kernel
183 state-machine-based implementation of asynchronous I/O
189 .BR io_getevents (2)),
190 but this implementation hasn't yet matured to the point where
191 the POSIX AIO implementation can be completely
192 reimplemented using the kernel system calls.
193 .\" http://lse.sourceforge.net/io/aio.html
194 .\" http://lse.sourceforge.net/io/aionotes.txt
195 .\" http://lwn.net/Articles/148755/
197 The program below opens each of the files named in its command-line
198 arguments and queues a request on the resulting file descriptor using
200 The program then loops,
201 periodically monitoring each of the I/O operations
202 that is still in progress using
204 Each of the I/O requests is set up to provide notification by delivery
206 After all I/O requests have completed,
207 the program retrieves their status using
212 signal (generated by typing control-\\) causes the program to request
213 cancellation of each of the outstanding requests using
216 Here is an example of what we might see when running this program.
217 In this example, the program queues two requests to standard input,
218 and these are satisfied by two lines of input containing
223 $ \fB./a.out /dev/stdin /dev/stdin\fP
224 opened /dev/stdin on descriptor 3
225 opened /dev/stdin on descriptor 4
227 for request 0 (descriptor 3): In progress
228 for request 1 (descriptor 4): In progress
230 I/O completion signal received
232 for request 0 (descriptor 3): I/O succeeded
233 for request 1 (descriptor 4): In progress
235 for request 1 (descriptor 4): In progress
237 I/O completion signal received
239 for request 1 (descriptor 4): I/O succeeded
240 All I/O requests completed
242 for request 0 (descriptor 3): 4
243 for request 1 (descriptor 4): 2
257 #define BUF_SIZE 20 /* Size of buffers for read operations */
259 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0)
261 #define errMsg(msg) do { perror(msg); } while (0)
263 struct ioRequest { /* Application\-defined structure for tracking
267 struct aiocb *aiocbp;
270 static volatile sig_atomic_t gotSIGQUIT = 0;
271 /* On delivery of SIGQUIT, we attempt to
272 cancel all outstanding I/O requests */
274 static void /* Handler for SIGQUIT */
280 #define IO_SIGNAL SIGUSR1 /* Signal used to notify I/O completion */
282 static void /* Handler for I/O completion signal */
283 aioSigHandler(int sig, siginfo_t *si, void *ucontext)
285 if (si->si_code == SI_ASYNCIO) {
286 write(STDOUT_FILENO, "I/O completion signal received\\n", 31);
288 /* The corresponding ioRequest structure would be available as
289 struct ioRequest *ioReq = si\->si_value.sival_ptr;
290 and the file descriptor would then be available via
291 ioReq\->aiocbp\->aio_fildes */
296 main(int argc, char *argv[])
298 struct ioRequest *ioList;
299 struct aiocb *aiocbList;
302 int numReqs; /* Total number of queued I/O requests */
303 int openReqs; /* Number of I/O requests still in progress */
306 fprintf(stderr, "Usage: %s <pathname> <pathname>...\\n",
313 /* Allocate our arrays */
315 ioList = calloc(numReqs, sizeof(struct ioRequest));
319 aiocbList = calloc(numReqs, sizeof(struct aiocb));
320 if (aiocbList == NULL)
323 /* Establish handlers for SIGQUIT and the I/O completion signal */
325 sa.sa_flags = SA_RESTART;
326 sigemptyset(&sa.sa_mask);
328 sa.sa_handler = quitHandler;
329 if (sigaction(SIGQUIT, &sa, NULL) == \-1)
330 errExit("sigaction");
332 sa.sa_flags = SA_RESTART | SA_SIGINFO;
333 sa.sa_sigaction = aioSigHandler;
334 if (sigaction(IO_SIGNAL, &sa, NULL) == \-1)
335 errExit("sigaction");
337 /* Open each file specified on the command line, and queue
338 a read request on the resulting file descriptor */
340 for (j = 0; j < numReqs; j++) {
341 ioList[j].reqNum = j;
342 ioList[j].status = EINPROGRESS;
343 ioList[j].aiocbp = &aiocbList[j];
345 ioList[j].aiocbp\->aio_fildes = open(argv[j + 1], O_RDONLY);
346 if (ioList[j].aiocbp\->aio_fildes == \-1)
348 printf("opened %s on descriptor %d\\n", argv[j + 1],
349 ioList[j].aiocbp\->aio_fildes);
351 ioList[j].aiocbp\->aio_buf = malloc(BUF_SIZE);
352 if (ioList[j].aiocbp\->aio_buf == NULL)
355 ioList[j].aiocbp\->aio_nbytes = BUF_SIZE;
356 ioList[j].aiocbp\->aio_reqprio = 0;
357 ioList[j].aiocbp\->aio_offset = 0;
358 ioList[j].aiocbp\->aio_sigevent.sigev_notify = SIGEV_SIGNAL;
359 ioList[j].aiocbp\->aio_sigevent.sigev_signo = IO_SIGNAL;
360 ioList[j].aiocbp\->aio_sigevent.sigev_value.sival_ptr =
363 s = aio_read(ioList[j].aiocbp);
370 /* Loop, monitoring status of I/O requests */
372 while (openReqs > 0) {
373 sleep(3); /* Delay between each monitoring step */
377 /* On receipt of SIGQUIT, attempt to cancel each of the
378 outstanding I/O requests, and display status returned
379 from the cancellation requests */
381 printf("got SIGQUIT; canceling I/O requests: \\n");
383 for (j = 0; j < numReqs; j++) {
384 if (ioList[j].status == EINPROGRESS) {
385 printf(" Request %d on descriptor %d:", j,
386 ioList[j].aiocbp\->aio_fildes);
387 s = aio_cancel(ioList[j].aiocbp\->aio_fildes,
389 if (s == AIO_CANCELED)
390 printf("I/O canceled\\n");
391 else if (s == AIO_NOTCANCELED)
392 printf("I/O not canceled\\n");
393 else if (s == AIO_ALLDONE)
394 printf("I/O all done\\n");
396 errMsg("aio_cancel");
403 /* Check the status of each I/O request that is still
406 printf("aio_error():\\n");
407 for (j = 0; j < numReqs; j++) {
408 if (ioList[j].status == EINPROGRESS) {
409 printf(" for request %d (descriptor %d): ",
410 j, ioList[j].aiocbp\->aio_fildes);
411 ioList[j].status = aio_error(ioList[j].aiocbp);
413 switch (ioList[j].status) {
415 printf("I/O succeeded\\n");
418 printf("In progress\\n");
421 printf("Canceled\\n");
428 if (ioList[j].status != EINPROGRESS)
434 printf("All I/O requests completed\\n");
436 /* Check status return of all I/O requests */
438 printf("aio_return():\\n");
439 for (j = 0; j < numReqs; j++) {
442 s = aio_return(ioList[j].aiocbp);
443 printf(" for request %d (descriptor %d): %zd\\n",
444 j, ioList[j].aiocbp\->aio_fildes, s);
455 .BR io_getevents (2),
466 "Asynchronous I/O Support in Linux 2.5",
467 Bhattacharya, Pratt, Pulavarty, and Morgan,
468 Proceedings of the Linux Symposium, 2003,
469 .UR https://www.kernel.org/doc/ols/2003/ols2003-pages-351-366.pdf