NAME
aio - POSIX asynchronous I/O overview DESCRIPTION The POSIX asynchronous I/O (AIO) interface allows applications to ini‐ tiate one or more I/O operations that are performed asynchronously (i.e., in the background). The application can elect to be notified of completion of the I/O operation in a variety of ways: by delivery of a signal, by instantiation of a thread, or no notification at all. The POSIX AIO interface consists of the following functions: aioread(3) Enqueue a read request. This is the asynchronous ana‐ log of read(2). aiowrite(3) Enqueue a write request. This is the asynchronous ana‐ log of write(2). aiofsync(3) Enqueue a sync request for the I/O operations on a file descriptor. This is the asynchronous analog of fsync(2) and fdatasync(2). aioerror(3) Obtain the error status of an enqueued I/O request. aioreturn(3) Obtain the return status of a completed I/O request. aiosuspend(3) Suspend the caller until one or more of a specified set of I/O requests completes. aiocancel(3) Attempt to cancel outstanding I/O requests on a speci‐ fied file descriptor. liolistio(3) Enqueue multiple I/O requests using a single function call. The aiocb ("asynchronous I/O control block") structure defines parame‐ ters that control an I/O operation. An argument of this type is employed with all of the functions listed above. This structure has the following form:
#include
struct aiocb { /* The order of these fields is implementation-dependent */ int aiofildes; /* File descriptor */ offt aiooffset; /* File offset */ volatile void *aiobuf; /* Location of buffer */ sizet aionbytes; /* Length of transfer */ int aioreqprio; /* Request priority */ struct sigevent aiosigevent; /* Notification method */ int aiolioopcode; /* Operation to be performed; liolistio() only */
/* Various implementation-internal fields not shown */ }; /* Operation codes for 'aiolioopcode': */ enum { LIOREAD, LIOWRITE, LIONOP }; The fields of this structure are as follows: aiofiledes The file descriptor on which the I/O operation is to be performed. aiooffset This is the file offset at which the I/O operation is to be performed. aiobuf This is the buffer used to transfer data for a read or write operation. aionbytes This is the size of the buffer pointed to by aiobuf. aioreqprio This field specifies a value that is subtracted from
the calling thread's real-time priority in order to determine the priority for execution of this I/O request (see pthreadsetschedparam(3)). The specified value must be between 0 and the value returned by sysconf(SCAIOPRIODELTAMAX). This field is ignored for file synchronization operations. aiosigevent This field is a structure that specifies how the caller is to be notified when the asynchronous I/O operation completes. Possible values for aiosigevent.sigevnotify are SIGEVNONE, SIGEVSIGNAL, and SIGEVTHREAD. See sigevent(7) for further details. aiolioopcode The type of operation to be performed; used only for liolistio(3). In addition to the standard functions listed above, the GNU C library provides the following extension to the POSIX AIO API: aioinit(3) Set parameters for tuning the behavior of the glibc POSIX AIO implementation. ERRORS EINVAL The aioreqprio field of the aiocb structure was less than 0, or was greater than the limit returned by the call sysconf(SCAIOPRIODELTAMAX). VERSIONS The POSIX AIO interfaces are provided by glibc since version 2.1. CONFORMING TO
POSIX.1-2001, POSIX.1-2008. NOTES It is a good idea to zero out the control block buffer before use (see memset(3)). The control block buffer and the buffer pointed to by aiobuf must not be changed while the I/O operation is in progress. These buffers must remain valid until the I/O operation completes. Simultaneous asynchronous read or write operations using the same aiocb structure yield undefined results. The current Linux POSIX AIO implementation is provided in user space by glibc. This has a number of limitations, most notably that maintaining multiple threads to perform I/O operations is expensive and scales
poorly. Work has been in progress for some time on a kernel state-
machine-based implementation of asynchronous I/O (see iosubmit(2), iosetup(2), iocancel(2), iodestroy(2), iogetevents(2)), but this implementation hasn't yet matured to the point where the POSIX AIO implementation can be completely reimplemented using the kernel system calls. EXAMPLE
The program below opens each of the files named in its command-line arguments and queues a request on the resulting file descriptor using aioread(3). The program then loops, periodically monitoring each of the I/O operations that is still in progress using aioerror(3). Each of the I/O requests is set up to provide notification by delivery of a signal. After all I/O requests have completed, the program retrieves their status using aioreturn(3).
The SIGQUIT signal (generated by typing control-\) causes the program to request cancellation of each of the outstanding requests using aiocancel(3). Here is an example of what we might see when running this program. In this example, the program queues two requests to standard input, and these are satisfied by two lines of input containing "abc" and "x".
$ ./a.out /dev/stdin /dev/stdin opened /dev/stdin on descriptor 3 opened /dev/stdin on descriptor 4 aioerror(): for request 0 (descriptor 3): In progress for request 1 (descriptor 4): In progress abc I/O completion signal received aioerror(): for request 0 (descriptor 3): I/O succeeded for request 1 (descriptor 4): In progress aioerror(): for request 1 (descriptor 4): In progress x I/O completion signal received aioerror(): for request 1 (descriptor 4): I/O succeeded All I/O requests completed aioreturn(): for request 0 (descriptor 3): 4 for request 1 (descriptor 4): 2 Program source
#include
#include
#include
#include
#include
#include
#define BUFSIZE 20 /* Size of buffers for read operations */
#define errExit(msg) do { perror(msg); exit(EXITFAILURE); } while (0)
#define errMsg(msg) do { perror(msg); } while (0)
struct ioRequest { /* Application-defined structure for tracking I/O requests */ int reqNum; int status; struct aiocb *aiocbp; }; static volatile sigatomict gotSIGQUIT = 0; /* On delivery of SIGQUIT, we attempt to cancel all outstanding I/O requests */ static void /* Handler for SIGQUIT */ quitHandler(int sig) { gotSIGQUIT = 1; }
#define IOSIGNAL SIGUSR1 /* Signal used to notify I/O completion */ static void /* Handler for I/O completion signal */ aioSigHandler(int sig, siginfot *si, void *ucontext) { write(STDOUTFILENO, "I/O completion signal received\n", 31); /* The corresponding ioRequest structure would be available as
struct ioRequest *ioReq = si->sivalue.sivalptr; and the file descriptor would then be available via
ioReq->aiocbp->aiofildes */ } int main(int argc, char *argv[]) { struct ioRequest *ioList; struct aiocb *aiocbList; struct sigaction sa; int s, j; int numReqs; /* Total number of queued I/O requests */ int openReqs; /* Number of I/O requests still in progress */ if (argc < 2) {
fprintf(stderr, "Usage: %s
...\n", argv[0]); exit(EXITFAILURE); } numReqs = argc - 1; /* Allocate our arrays */ ioList = calloc(numReqs, sizeof(struct ioRequest)); if (ioList == NULL) errExit("calloc"); aiocbList = calloc(numReqs, sizeof(struct aiocb)); if (aiocbList == NULL) errExit("calloc"); /* Establish handlers for SIGQUIT and the I/O completion signal */ sa.saflags = SARESTART; sigemptyset(&sa.samask); sa.sahandler = quitHandler;
if (sigaction(SIGQUIT, &sa, NULL) == -1) errExit("sigaction"); sa.saflags = SARESTART | SASIGINFO; sa.sasigaction = aioSigHandler;
if (sigaction(IOSIGNAL, &sa, NULL) == -1) errExit("sigaction"); /* Open each file specified on the command line, and queue a read request on the resulting file descriptor */ for (j = 0; j < numReqs; j++) { ioList[j].reqNum = j; ioList[j].status = EINPROGRESS; ioList[j].aiocbp = &aiocbList[j];
ioList[j].aiocbp->aiofildes = open(argv[j + 1], ORDONLY);
if (ioList[j].aiocbp->aiofildes == -1) errExit("open");
printf("opened %s on descriptor %d\n", argv[j + 1],
ioList[j].aiocbp->aiofildes);
ioList[j].aiocbp->aiobuf = malloc(BUFSIZE);
if (ioList[j].aiocbp->aiobuf == NULL) errExit("malloc");
ioList[j].aiocbp->aionbytes = BUFSIZE;
ioList[j].aiocbp->aioreqprio = 0;
ioList[j].aiocbp->aiooffset = 0;
ioList[j].aiocbp->aiosigevent.sigevnotify = SIGEVSIGNAL;
ioList[j].aiocbp->aiosigevent.sigevsigno = IOSIGNAL;
ioList[j].aiocbp->aiosigevent.sigevvalue.sivalptr = &ioList[j]; s = aioread(ioList[j].aiocbp);
if (s == -1) errExit("aioread"); } openReqs = numReqs; /* Loop, monitoring status of I/O requests */ while (openReqs > 0) { sleep(3); /* Delay between each monitoring step */ if (gotSIGQUIT) { /* On receipt of SIGQUIT, attempt to cancel each of the outstanding I/O requests, and display status returned from the cancellation requests */ printf("got SIGQUIT; canceling I/O requests: \n"); for (j = 0; j < numReqs; j++) { if (ioList[j].status == EINPROGRESS) {
printf(" Request %d on descriptor %d:", j,
ioList[j].aiocbp->aiofildes);
s = aiocancel(ioList[j].aiocbp->aiofildes, ioList[j].aiocbp); if (s == AIOCANCELED) printf("I/O canceled\n"); else if (s == AIONOTCANCELED) printf("I/O not canceled\n"); else if (s == AIOALLDONE) printf("I/O all done\n"); else errMsg("aiocancel"); } } gotSIGQUIT = 0; } /* Check the status of each I/O request that is still in progress */ printf("aioerror():\n"); for (j = 0; j < numReqs; j++) { if (ioList[j].status == EINPROGRESS) {
printf(" for request %d (descriptor %d): ",
j, ioList[j].aiocbp->aiofildes); ioList[j].status = aioerror(ioList[j].aiocbp); switch (ioList[j].status) { case 0: printf("I/O succeeded\n"); break; case EINPROGRESS: printf("In progress\n"); break; case ECANCELED: printf("Canceled\n"); break; default: errMsg("aioerror"); break; } if (ioList[j].status != EINPROGRESS) openReqs; } } } printf("All I/O requests completed\n"); /* Check status return of all I/O requests */ printf("aioreturn():\n"); for (j = 0; j < numReqs; j++) { ssizet s; s = aioreturn(ioList[j].aiocbp);
printf(" for request %d (descriptor %d): %ld\n",
j, ioList[j].aiocbp->aiofildes, (long) s); } exit(EXITSUCCESS); } SEE ALSO iocancel(2), iodestroy(2), iogetevents(2), iosetup(2), iosubmit(2), aiocancel(3), aioerror(3), aioinit(3), aioread(3), aioreturn(3), aiowrite(3), liolistio(3)
⟨http://www.squid-cache.org/~adrian/Reprint-Pulavarty-OLS2003.pdf⟩ COLOPHON
This page is part of release 3.53 of the Linux man-pages project. A description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
Linux 2012-08-05 AIO(7)