1 .\" Copyright (c) 2010 by Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .TH AIO 7 2021-03-22 "Linux" "Linux Programmer's Manual"
7 aio \- POSIX asynchronous I/O overview
9 The POSIX asynchronous I/O (AIO) interface allows applications
10 to initiate one or more I/O operations that are performed
11 asynchronously (i.e., in the background).
12 The application can elect to be notified of completion of
13 the I/O operation in a variety of ways:
14 by delivery of a signal, by instantiation of a thread,
15 or no notification at all.
17 The POSIX AIO interface consists of the following functions:
20 Enqueue a read request.
21 This is the asynchronous analog of
25 Enqueue a write request.
26 This is the asynchronous analog of
30 Enqueue a sync request for the I/O operations on a file descriptor.
31 This is the asynchronous analog of
37 Obtain the error status of an enqueued I/O request.
40 Obtain the return status of a completed I/O request.
43 Suspend the caller until one or more of a specified set of
44 I/O requests completes.
47 Attempt to cancel outstanding I/O requests on a specified
51 Enqueue multiple I/O requests using a single function call.
55 ("asynchronous I/O control block") structure defines
56 parameters that control an I/O operation.
57 An argument of this type is employed with all of the functions listed above.
58 This structure has the following form:
65 /* The order of these fields is implementation\-dependent */
67 int aio_fildes; /* File descriptor */
68 off_t aio_offset; /* File offset */
69 volatile void *aio_buf; /* Location of buffer */
70 size_t aio_nbytes; /* Length of transfer */
71 int aio_reqprio; /* Request priority */
72 struct sigevent aio_sigevent; /* Notification method */
73 int aio_lio_opcode; /* Operation to be performed;
76 /* Various implementation\-internal fields not shown */
79 /* Operation codes for \(aqaio_lio_opcode\(aq: */
81 enum { LIO_READ, LIO_WRITE, LIO_NOP };
85 The fields of this structure are as follows:
88 The file descriptor on which the I/O operation is to be performed.
91 This is the file offset at which the I/O operation is to be performed.
94 This is the buffer used to transfer data for a read or write operation.
97 This is the size of the buffer pointed to by
101 This field specifies a value that is subtracted
102 from the calling thread's real-time priority in order to
103 determine the priority for execution of this I/O request (see
104 .BR pthread_setschedparam (3)).
105 The specified value must be between 0 and the value returned by
106 .IR sysconf(_SC_AIO_PRIO_DELTA_MAX) .
107 This field is ignored for file synchronization operations.
110 This field is a structure that specifies how the caller is
111 to be notified when the asynchronous I/O operation completes.
113 .I aio_sigevent.sigev_notify
124 The type of operation to be performed; used only for
127 In addition to the standard functions listed above,
128 the GNU C library provides the following extension to the POSIX AIO API:
131 Set parameters for tuning the behavior of the glibc POSIX AIO implementation.
139 structure was less than 0,
140 or was greater than the limit returned by the call
141 .IR sysconf(_SC_AIO_PRIO_DELTA_MAX) .
143 The POSIX AIO interfaces are provided by glibc since version 2.1.
145 POSIX.1-2001, POSIX.1-2008.
147 It is a good idea to zero out the control block buffer before use (see
149 The control block buffer and the buffer pointed to by
151 must not be changed while the I/O operation is in progress.
152 These buffers must remain valid until the I/O operation completes.
154 Simultaneous asynchronous read or write operations using the same
156 structure yield undefined results.
158 The current Linux POSIX AIO implementation is provided in user space by glibc.
159 This has a number of limitations, most notably that maintaining multiple
160 threads to perform I/O operations is expensive and scales poorly.
161 Work has been in progress for some time on a kernel
162 state-machine-based implementation of asynchronous I/O
168 .BR io_getevents (2)),
169 but this implementation hasn't yet matured to the point where
170 the POSIX AIO implementation can be completely
171 reimplemented using the kernel system calls.
172 .\" http://lse.sourceforge.net/io/aio.html
173 .\" http://lse.sourceforge.net/io/aionotes.txt
174 .\" http://lwn.net/Articles/148755/
176 The program below opens each of the files named in its command-line
177 arguments and queues a request on the resulting file descriptor using
179 The program then loops,
180 periodically monitoring each of the I/O operations
181 that is still in progress using
183 Each of the I/O requests is set up to provide notification by delivery
185 After all I/O requests have completed,
186 the program retrieves their status using
191 signal (generated by typing control-\e) causes the program to request
192 cancelation of each of the outstanding requests using
195 Here is an example of what we might see when running this program.
196 In this example, the program queues two requests to standard input,
197 and these are satisfied by two lines of input containing
202 $ \fB./a.out /dev/stdin /dev/stdin\fP
203 opened /dev/stdin on descriptor 3
204 opened /dev/stdin on descriptor 4
206 for request 0 (descriptor 3): In progress
207 for request 1 (descriptor 4): In progress
209 I/O completion signal received
211 for request 0 (descriptor 3): I/O succeeded
212 for request 1 (descriptor 4): In progress
214 for request 1 (descriptor 4): In progress
216 I/O completion signal received
218 for request 1 (descriptor 4): I/O succeeded
219 All I/O requests completed
221 for request 0 (descriptor 3): 4
222 for request 1 (descriptor 4): 2
236 #define BUF_SIZE 20 /* Size of buffers for read operations */
238 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0)
240 struct ioRequest { /* Application\-defined structure for tracking
244 struct aiocb *aiocbp;
247 static volatile sig_atomic_t gotSIGQUIT = 0;
248 /* On delivery of SIGQUIT, we attempt to
249 cancel all outstanding I/O requests */
251 static void /* Handler for SIGQUIT */
257 #define IO_SIGNAL SIGUSR1 /* Signal used to notify I/O completion */
259 static void /* Handler for I/O completion signal */
260 aioSigHandler(int sig, siginfo_t *si, void *ucontext)
262 if (si\->si_code == SI_ASYNCIO) {
263 write(STDOUT_FILENO, "I/O completion signal received\en", 31);
265 /* The corresponding ioRequest structure would be available as
266 struct ioRequest *ioReq = si\->si_value.sival_ptr;
267 and the file descriptor would then be available via
268 ioReq\->aiocbp\->aio_fildes */
273 main(int argc, char *argv[])
277 int numReqs; /* Total number of queued I/O requests */
278 int openReqs; /* Number of I/O requests still in progress */
281 fprintf(stderr, "Usage: %s <pathname> <pathname>...\en",
288 /* Allocate our arrays. */
290 struct ioRequest *ioList = calloc(numReqs, sizeof(*ioList));
294 struct aiocb *aiocbList = calloc(numReqs, sizeof(*aiocbList));
295 if (aiocbList == NULL)
298 /* Establish handlers for SIGQUIT and the I/O completion signal. */
300 sa.sa_flags = SA_RESTART;
301 sigemptyset(&sa.sa_mask);
303 sa.sa_handler = quitHandler;
304 if (sigaction(SIGQUIT, &sa, NULL) == \-1)
305 errExit("sigaction");
307 sa.sa_flags = SA_RESTART | SA_SIGINFO;
308 sa.sa_sigaction = aioSigHandler;
309 if (sigaction(IO_SIGNAL, &sa, NULL) == \-1)
310 errExit("sigaction");
312 /* Open each file specified on the command line, and queue
313 a read request on the resulting file descriptor. */
315 for (int j = 0; j < numReqs; j++) {
316 ioList[j].reqNum = j;
317 ioList[j].status = EINPROGRESS;
318 ioList[j].aiocbp = &aiocbList[j];
320 ioList[j].aiocbp\->aio_fildes = open(argv[j + 1], O_RDONLY);
321 if (ioList[j].aiocbp\->aio_fildes == \-1)
323 printf("opened %s on descriptor %d\en", argv[j + 1],
324 ioList[j].aiocbp\->aio_fildes);
326 ioList[j].aiocbp\->aio_buf = malloc(BUF_SIZE);
327 if (ioList[j].aiocbp\->aio_buf == NULL)
330 ioList[j].aiocbp\->aio_nbytes = BUF_SIZE;
331 ioList[j].aiocbp\->aio_reqprio = 0;
332 ioList[j].aiocbp\->aio_offset = 0;
333 ioList[j].aiocbp\->aio_sigevent.sigev_notify = SIGEV_SIGNAL;
334 ioList[j].aiocbp\->aio_sigevent.sigev_signo = IO_SIGNAL;
335 ioList[j].aiocbp\->aio_sigevent.sigev_value.sival_ptr =
338 s = aio_read(ioList[j].aiocbp);
345 /* Loop, monitoring status of I/O requests. */
347 while (openReqs > 0) {
348 sleep(3); /* Delay between each monitoring step */
352 /* On receipt of SIGQUIT, attempt to cancel each of the
353 outstanding I/O requests, and display status returned
354 from the cancelation requests. */
356 printf("got SIGQUIT; canceling I/O requests: \en");
358 for (int j = 0; j < numReqs; j++) {
359 if (ioList[j].status == EINPROGRESS) {
360 printf(" Request %d on descriptor %d:", j,
361 ioList[j].aiocbp\->aio_fildes);
362 s = aio_cancel(ioList[j].aiocbp\->aio_fildes,
364 if (s == AIO_CANCELED)
365 printf("I/O canceled\en");
366 else if (s == AIO_NOTCANCELED)
367 printf("I/O not canceled\en");
368 else if (s == AIO_ALLDONE)
369 printf("I/O all done\en");
371 perror("aio_cancel");
378 /* Check the status of each I/O request that is still
381 printf("aio_error():\en");
382 for (int j = 0; j < numReqs; j++) {
383 if (ioList[j].status == EINPROGRESS) {
384 printf(" for request %d (descriptor %d): ",
385 j, ioList[j].aiocbp\->aio_fildes);
386 ioList[j].status = aio_error(ioList[j].aiocbp);
388 switch (ioList[j].status) {
390 printf("I/O succeeded\en");
393 printf("In progress\en");
396 printf("Canceled\en");
403 if (ioList[j].status != EINPROGRESS)
409 printf("All I/O requests completed\en");
411 /* Check status return of all I/O requests. */
413 printf("aio_return():\en");
414 for (int j = 0; j < numReqs; j++) {
417 s = aio_return(ioList[j].aiocbp);
418 printf(" for request %d (descriptor %d): %zd\en",
419 j, ioList[j].aiocbp\->aio_fildes, s);
430 .BR io_getevents (2),
441 "Asynchronous I/O Support in Linux 2.5",
442 Bhattacharya, Pratt, Pulavarty, and Morgan,
443 Proceedings of the Linux Symposium, 2003,
444 .UR https://www.kernel.org/doc/ols/2003/ols2003\-pages\-351\-366.pdf