2
.\" Copyright (c) 2010 by Michael Kerrisk <mtk.manpages@gmail.com>
4
.\" Permission is granted to make and distribute verbatim copies of this
5
.\" manual provided the copyright notice and this permission notice are
6
.\" preserved on all copies.
8
.\" Permission is granted to copy and distribute modified versions of this
9
.\" manual under the conditions for verbatim copying, provided that the
10
.\" entire resulting derived work is distributed under the terms of a
11
.\" permission notice identical to this one.
13
.\" Since the Linux kernel and libraries are constantly changing, this
14
.\" manual page may be incorrect or out-of-date. The author(s) assume no
15
.\" responsibility for errors or omissions, or for damages resulting from
16
.\" the use of the information contained herein. The author(s) may not
17
.\" have taken the same level of care in the production of this manual,
18
.\" which is licensed free of charge, as they might when working
21
.\" Formatted or processed versions of this manual, if unaccompanied by
22
.\" the source, must acknowledge the copyright and authors of this work.
24
.TH AIO 7 2010-10-02 "Linux" "Linux Programmer's Manual"
26
aio \- POSIX asynchronous I/O overview
28
The POSIX asynchronous I/O (AIO) interface allows applications
29
to initiate one or more I/O operations that are performed
30
asynchronously (i.e., in the background).
31
The application can elect to be notified of completion of
32
the I/O operation in a variety of ways:
33
by delivery of a signal, by instantiation of a thread,
34
or no notification at all.
36
The POSIX AIO interface consists of the following functions:
39
Enqueue a read request.
40
This is the asynchronous analog of
44
Enqueue a write request.
45
This is the asynchronous analog of
49
Enqueue a sync request for the I/O operations on a file descriptor.
50
This is the asynchronous analog of
56
Obtain the error status of an enqueued I/O request.
59
Obtain the return status of a completed I/O request.
62
Suspend the caller until one or more of a specified set of
63
I/O requests completes.
66
Attempt to cancel outstanding I/O requests on a specified
70
Enqueue multiple I/O requests using a single function call.
74
("asynchronous I/O control block") structure defines
75
parameters that control an I/O operation.
76
An argument of this type is employed with all of the functions listed above.
77
This structure has the following form:
84
/* The order of these fields is implementation-dependent */
86
int aio_fildes; /* File descriptor */
87
off_t aio_offset; /* File offset */
88
volatile void *aio_buf; /* Location of buffer */
89
size_t aio_nbytes; /* Length of transfer */
90
int aio_reqprio; /* Request priority */
91
struct sigevent aio_sigevent; /* Notification method */
92
int aio_lio_opcode; /* Operation to be performed;
95
/* Various implementation-internal fields not shown */
98
/* Operation codes for 'aio_lio_opcode': */
100
enum { LIO_READ, LIO_WRITE, LIO_NOP };
104
The fields of this structure are as follows:
107
The file descriptor on which the I/O operation is to be performed.
110
This is the file offset at which the I/O operation is to be performed.
113
This is the buffer used to transfer data for a read or write operation.
116
This is the size of the buffer pointed to by
120
This field specifies a value that is subtracted
121
from the calling thread's real-time priority in order to
122
determine the priority for execution of this I/O request (see
123
.BR pthread_setschedparam (3)).
124
The specified value must be between 0 and the value returned by
125
.IR sysconf(_SC_AIO_PRIO_DELTA_MAX) .
126
This field is ignored for file synchronization operations.
129
This field is a structure that specifies how the caller is
130
to be notified when the asynchronous I/O operation completes.
132
.IR aio_sigevent.sigev_notify
143
The type of operation to be performed; used only for
146
In addition to the standard functions listed above,
147
the GNU C library provides the following extension to the POSIX AIO API:
150
Set parameters for tuning the behavior of the glibc POSIX AIO implementation.
152
It is a good idea to zero out the control block buffer before use (see
154
The control block buffer and the buffer pointed to by
156
must not be changed while the I/O operation is in progress.
157
These buffers must remain valid until the I/O operation completes.
159
Simultaneous asynchronous read or write operations using the same
161
structure yield undefined results.
163
The current Linux POSIX AIO implementation is provided in userspace by glibc.
164
This has a number of limitations, most notably that maintaining multiple
165
threads to perform I/O operations is expensive and scales poorly.
166
Work has been in progress for some time on a kernel
167
state-machine-based implementation of asynchronous I/O
173
.BR io_getevents (2)),
174
but this implementation hasn't yet matured to the point where
175
the POSIX AIO implementation can be completely
176
reimplemented using the kernel system calls.
177
.\" http://lse.sourceforge.net/io/aio.html
178
.\" http://lse.sourceforge.net/io/aionotes.txt
179
.\" http://lwn.net/Articles/148755/
187
structure was less than 0,
188
or was greater than the limit returned by the call
189
.IR sysconf(_SC_AIO_PRIO_DELTA_MAX) .
191
The POSIX AIO interfaces are provided by glibc since version 2.1.
193
POSIX.1-2001, POSIX.1-2008.
195
The program below opens each of the files named in its command-line
196
arguments and queues a request on the resulting file descriptor using
198
The program then loops,
199
periodically monitoring each of the I/O operations
200
that is still in progress using
202
Each of the I/O requests is set up to provide notification by delivery
204
After all I/O requests have completed,
205
the program retrieves their status using
210
signal (generated by typing control-\\) causes the program to request
211
cancellation of each of the outstanding requests using
214
Here is an example of what we might see when running this program.
215
In this example, the program queues two requests to standard input,
216
and these are satisfied by two lines of input containing
221
$ \fB./a.out /dev/stdin /dev/stdin\fP
222
opened /dev/stdin on descriptor 3
223
opened /dev/stdin on descriptor 4
225
for request 0 (descriptor 3): In progress
226
for request 1 (descriptor 4): In progress
228
I/O completion signal received
230
for request 0 (descriptor 3): I/O succeeded
231
for request 1 (descriptor 4): In progress
233
for request 1 (descriptor 4): In progress
235
I/O completion signal received
237
for request 1 (descriptor 4): I/O succeeded
238
All I/O requests completed
240
for request 0 (descriptor 3): 4
241
for request 1 (descriptor 4): 2
254
#define BUF_SIZE 20 /* Size of buffers for read operations */
256
#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0)
258
#define errMsg(msg) do { perror(msg); } while (0)
260
struct ioRequest { /* Application\-defined structure for tracking
264
struct aiocb *aiocbp;
267
static volatile sig_atomic_t gotSIGQUIT = 0;
268
/* On delivery of SIGQUIT, we attempt to
269
cancel all outstanding I/O requests */
271
static void /* Handler for SIGQUIT */
277
#define IO_SIGNAL SIGUSR1 /* Signal used to notify I/O completion */
279
static void /* Handler for I/O completion signal */
280
aioSigHandler(int sig, siginfo_t *si, void *ucontext)
282
write(STDOUT_FILENO, "I/O completion signal received\\n", 31);
284
/* The corresponding ioRequest structure would be available as
285
struct ioRequest *ioReq = si\->si_value.sival_ptr;
286
and the file descriptor would then be available via
287
ioReq\->aiocbp\->aio_fildes */
291
main(int argc, char *argv[])
293
struct ioRequest *ioList;
294
struct aiocb *aiocbList;
297
int numReqs; /* Total number of queued I/O requests */
298
int openReqs; /* Number of I/O requests still in progress */
301
fprintf(stderr, "Usage: %s <pathname> <pathname>...\\n",
308
/* Allocate our arrays */
310
ioList = calloc(numReqs, sizeof(struct ioRequest));
314
aiocbList = calloc(numReqs, sizeof(struct aiocb));
315
if (aiocbList == NULL)
318
/* Establish handlers for SIGQUIT and the I/O completion signal */
320
sa.sa_flags = SA_RESTART;
321
sigemptyset(&sa.sa_mask);
323
sa.sa_handler = quitHandler;
324
if (sigaction(SIGQUIT, &sa, NULL) == \-1)
325
errExit("sigaction");
327
sa.sa_flags = SA_RESTART | SA_SIGINFO;
328
sa.sa_sigaction = aioSigHandler;
329
if (sigaction(IO_SIGNAL, &sa, NULL) == \-1)
330
errExit("sigaction");
332
/* Open each file specified on the command line, and queue
333
a read request on the resulting file descriptor */
335
for (j = 0; j < numReqs; j++) {
336
ioList[j].reqNum = j;
337
ioList[j].status = EINPROGRESS;
338
ioList[j].aiocbp = &aiocbList[j];
340
ioList[j].aiocbp\->aio_fildes = open(argv[j + 1], O_RDONLY);
341
if (ioList[j].aiocbp\->aio_fildes == \-1)
343
printf("opened %s on descriptor %d\\n", argv[j + 1],
344
ioList[j].aiocbp\->aio_fildes);
346
ioList[j].aiocbp\->aio_buf = malloc(BUF_SIZE);
347
if (ioList[j].aiocbp\->aio_buf == NULL)
350
ioList[j].aiocbp\->aio_nbytes = BUF_SIZE;
351
ioList[j].aiocbp\->aio_reqprio = 0;
352
ioList[j].aiocbp\->aio_offset = 0;
353
ioList[j].aiocbp\->aio_sigevent.sigev_notify = SIGEV_SIGNAL;
354
ioList[j].aiocbp\->aio_sigevent.sigev_signo = IO_SIGNAL;
355
ioList[j].aiocbp\->aio_sigevent.sigev_value.sival_ptr =
358
s = aio_read(ioList[j].aiocbp);
365
/* Loop, monitoring status of I/O requests */
367
while (openReqs > 0) {
368
sleep(3); /* Delay between each monitoring step */
372
/* On receipt of SIGQUIT, attempt to cancel each of the
373
outstanding I/O requests, and display status returned
374
from the cancellation requests */
376
printf("got SIGQUIT; canceling I/O requests: \\n");
378
for (j = 0; j < numReqs; j++) {
379
if (ioList[j].status == EINPROGRESS) {
380
printf(" Request %d on descriptor %d:", j,
381
ioList[j].aiocbp\->aio_fildes);
382
s = aio_cancel(ioList[j].aiocbp\->aio_fildes,
384
if (s == AIO_CANCELED)
385
printf("I/O canceled\\n");
386
else if (s == AIO_NOTCANCELED)
387
printf("I/O not canceled\\n");
388
else if (s == AIO_ALLDONE)
389
printf("I/O all done\\n");
391
errMsg("aio_cancel");
398
/* Check the status of each I/O request that is still
401
printf("aio_error():\\n");
402
for (j = 0; j < numReqs; j++) {
403
if (ioList[j].status == EINPROGRESS) {
404
printf(" for request %d (descriptor %d): ",
405
j, ioList[j].aiocbp\->aio_fildes);
406
ioList[j].status = aio_error(ioList[j].aiocbp);
408
switch (ioList[j].status) {
410
printf("I/O succeeded\\n");
413
printf("In progress\\n");
416
printf("Canceled\\n");
423
if (ioList[j].status != EINPROGRESS)
429
printf("All I/O requests completed\\n");
431
/* Check status return of all I/O requests */
433
printf("aio_return():\\n");
434
for (j = 0; j < numReqs; j++) {
437
s = aio_return(ioList[j].aiocbp);
438
printf(" for request %d (descriptor %d): %ld\\n",
439
j, ioList[j].aiocbp\->aio_fildes, (long) s);
449
.BR io_getevents (2),
459
http://www.squid-cache.org/~adrian/Reprint-Pulavarty-OLS2003.pdf
461
This page is part of release 3.32 of the Linux
464
A description of the project,
465
and information about reporting bugs,
467
http://www.kernel.org/doc/man-pages/.
added
removed
man7/aio.7
