aio - POSIX asynchronous I/O overview


   The  POSIX  asynchronous  I/O  (AIO)  interface  allows applications to
   initiate 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:

   aio_read(3)     Enqueue  a  read  request.   This  is  the asynchronous
                   analog of read(2).

   aio_write(3)    Enqueue a write  request.   This  is  the  asynchronous
                   analog of write(2).

   aio_fsync(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).

   aio_error(3)    Obtain the error status of an enqueued I/O request.

   aio_return(3)   Obtain the return status of a completed I/O request.

   aio_suspend(3)  Suspend the caller until one or more of a specified set
                   of I/O requests completes.

   aio_cancel(3)   Attempt  to  cancel  outstanding  I/O  requests  on   a
                   specified file descriptor.

   lio_listio(3)   Enqueue  multiple  I/O requests using a single function

   The  aiocb  ("asynchronous  I/O  control  block")   structure   defines
   parameters  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 <aiocb.h>

       struct aiocb {
           /* The order of these fields is implementation-dependent */

           int             aio_fildes;     /* File descriptor */
           off_t           aio_offset;     /* File offset */
           volatile void  *aio_buf;        /* Location of buffer */
           size_t          aio_nbytes;     /* Length of transfer */
           int             aio_reqprio;    /* Request priority */
           struct sigevent aio_sigevent;   /* Notification method */
           int             aio_lio_opcode; /* Operation to be performed;
                                              lio_listio() only */

           /* Various implementation-internal fields not shown */

       /* Operation codes for 'aio_lio_opcode': */

       enum { LIO_READ, LIO_WRITE, LIO_NOP };

   The fields of this structure are as follows:

   aio_filedes     The file descriptor on which the I/O operation is to be

   aio_offset      This is the file offset at which the I/O  operation  is
                   to be performed.

   aio_buf         This  is the buffer used to transfer data for a read or
                   write operation.

   aio_nbytes      This is the size of the buffer pointed to by aio_buf.

   aio_reqprio     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 pthread_setschedparam(3)).  The specified
                   value must be between  0  and  the  value  returned  by
                   sysconf(_SC_AIO_PRIO_DELTA_MAX).  This field is ignored
                   for file synchronization operations.

   aio_sigevent    This field is a structure that specifies how the caller
                   is  to  be notified when the asynchronous I/O operation
                   completes.          Possible         values         for
                   aio_sigevent.sigev_notify are SIGEV_NONE, SIGEV_SIGNAL,
                   and SIGEV_THREAD.  See sigevent(7) for further details.

   aio_lio_opcode  The type of operation to be performed;  used  only  for

   In  addition  to the standard functions listed above, the GNU C library
   provides the following extension to the POSIX AIO API:

   aio_init(3)     Set parameters for tuning the  behavior  of  the  glibc
                   POSIX AIO implementation.


   EINVAL The aio_reqprio field of the aiocb structure was less than 0, or
          was   greater   than   the   limit   returned   by   the    call


   The POSIX AIO interfaces are provided by glibc since version 2.1.


   POSIX.1-2001, POSIX.1-2008.


   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
   aio_buf  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 io_submit(2),
   io_setup(2), io_cancel(2), io_destroy(2),  io_getevents(2)),  but  this
   implementation  hasn't  yet  matured  to  the point where the POSIX AIO
   implementation can be completely reimplemented using the kernel  system


   The  program  below  opens  each of the files named in its command-line
   arguments and queues a request on the resulting file  descriptor  using
   aio_read(3).   The  program then loops, periodically monitoring each of
   the I/O operations that is still in progress using aio_error(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 aio_return(3).

   The  SIGQUIT  signal (generated by typing control-\) causes the program
   to request cancellation of  each  of  the  outstanding  requests  using

   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
           for request 0 (descriptor 3): In progress
           for request 1 (descriptor 4): In progress
       I/O completion signal received
           for request 0 (descriptor 3): I/O succeeded
           for request 1 (descriptor 4): In progress
           for request 1 (descriptor 4): In progress
       I/O completion signal received
           for request 1 (descriptor 4): I/O succeeded
       All I/O requests completed
           for request 0 (descriptor 3): 4
           for request 1 (descriptor 4): 2

   Program source

   #include <fcntl.h>
   #include <stdlib.h>
   #include <unistd.h>
   #include <stdio.h>
   #include <errno.h>
   #include <aio.h>
   #include <signal.h>

   #define BUF_SIZE 20     /* Size of buffers for read operations */

   #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); } 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 sig_atomic_t 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 IO_SIGNAL SIGUSR1   /* Signal used to notify I/O completion */

   static void                 /* Handler for I/O completion signal */
   aioSigHandler(int sig, siginfo_t *si, void *ucontext)
       if (si->si_code == SI_ASYNCIO) {
           write(STDOUT_FILENO, "I/O completion signal received\n", 31);

           /* The corresponding ioRequest structure would be available as
                  struct ioRequest *ioReq = si->si_value.sival_ptr;
              and the file descriptor would then be available via
                  ioReq->aiocbp->aio_fildes */

   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 <pathname> <pathname>...\n",

       numReqs = argc - 1;

       /* Allocate our arrays */

       ioList = calloc(numReqs, sizeof(struct ioRequest));
       if (ioList == NULL)

       aiocbList = calloc(numReqs, sizeof(struct aiocb));
       if (aiocbList == NULL)

       /* Establish handlers for SIGQUIT and the I/O completion signal */

       sa.sa_flags = SA_RESTART;

       sa.sa_handler = quitHandler;
       if (sigaction(SIGQUIT, &sa, NULL) == -1)

       sa.sa_flags = SA_RESTART | SA_SIGINFO;
       sa.sa_sigaction = aioSigHandler;
       if (sigaction(IO_SIGNAL, &sa, NULL) == -1)

       /* 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->aio_fildes = open(argv[j + 1], O_RDONLY);
           if (ioList[j].aiocbp->aio_fildes == -1)
           printf("opened %s on descriptor %d\n", argv[j + 1],

           ioList[j].aiocbp->aio_buf = malloc(BUF_SIZE);
           if (ioList[j].aiocbp->aio_buf == NULL)

           ioList[j].aiocbp->aio_nbytes = BUF_SIZE;
           ioList[j].aiocbp->aio_reqprio = 0;
           ioList[j].aiocbp->aio_offset = 0;
           ioList[j].aiocbp->aio_sigevent.sigev_notify = SIGEV_SIGNAL;
           ioList[j].aiocbp->aio_sigevent.sigev_signo = IO_SIGNAL;
           ioList[j].aiocbp->aio_sigevent.sigev_value.sival_ptr =

           s = aio_read(ioList[j].aiocbp);
           if (s == -1)

       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,
                       s = aio_cancel(ioList[j].aiocbp->aio_fildes,
                       if (s == AIO_CANCELED)
                           printf("I/O canceled\n");
                       else if (s == AIO_NOTCANCELED)
                               printf("I/O not canceled\n");
                       else if (s == AIO_ALLDONE)
                           printf("I/O all done\n");

               gotSIGQUIT = 0;

           /* Check the status of each I/O request that is still
              in progress */

           for (j = 0; j < numReqs; j++) {
               if (ioList[j].status == EINPROGRESS) {
                   printf("    for request %d (descriptor %d): ",
                           j, ioList[j].aiocbp->aio_fildes);
                   ioList[j].status = aio_error(ioList[j].aiocbp);

                   switch (ioList[j].status) {
                   case 0:
                       printf("I/O succeeded\n");
                   case EINPROGRESS:
                       printf("In progress\n");
                   case ECANCELED:

                   if (ioList[j].status != EINPROGRESS)

       printf("All I/O requests completed\n");

       /* Check status return of all I/O requests */

       for (j = 0; j < numReqs; j++) {
           ssize_t s;

           s = aio_return(ioList[j].aiocbp);
           printf("    for request %d (descriptor %d): %zd\n",
                   j, ioList[j].aiocbp->aio_fildes, s);



   io_cancel(2), io_destroy(2), io_getevents(2), io_setup(2),
   io_submit(2), aio_cancel(3), aio_error(3), aio_init(3), aio_read(3),
   aio_return(3), aio_write(3), lio_listio(3)

   "Asynchronous I/O Support in Linux 2.5", Bhattacharya, Pratt,
   Pulavarty, and Morgan, Proceedings of the Linux Symposium, 2003,


   This page is part of release 4.09 of the Linux man-pages project.  A
   description of the project, information about reporting bugs, and the
   latest version of this page, can be found at

More Linux Commands

iswdigit(3) - test for decimal digit wide character.........
The iswdigit() function is the wide-character equivalent of the isdigit(3) function. It tests whether wc is a wide character belonging to the wide-character cla

bootparam(7) - Introduction to boot time parameters of the L
The Linux kernel accepts certain command-line options or boot time parameters at the moment it is started. In general this is used to supply the kernel with inf

pause(2) - wait for signal (System calls - Linux man page)
pause() causes the calling process (or thread) to sleep until a signal is delivered that either terminates the process or causes the invocation of a signal-catc

XtCallAcceptFocus(3) - calla widget's accept_focus procedure
The XtCallAcceptFocus function calls the specified widgets accept_focus procedure, passing it the specified widget and time, and returns what the accept_focus p

mvinch(3ncurses) - get a character and attributes from a cur
These routines return the character, of type chtype, at the current position in the named window. If any attributes are set for that position, their values are

keyctl_update(3) - Update a key (Library - Linux man page)
keyctl_update() updates the payload of a key if the key type permits it. The caller must have write permission on a key to be able update it. payload and plen s

groff_diff(7) - differences between GNU troff and classical
This manual page describes the language differences between groff, the GNU roff text processing system, and the classical roff formatter of the freely available

service(8) - run a System V init script - Linux manual page
The SERVICE parameter specifies a systemd service name to operate on. The supported values of ACTION depend on the specified service. The actions start, stop, r

XSubtractRegion(3) - region arithmetic - Linux manual page
The XIntersectRegion function computes the intersection of two regions. The XUnionRegion function computes the union of two regions. The XUnionRectWithRegion fu

sinh(3) - hyperbolic sine function - Linux manual page......
The sinh() function returns the hyperbolic sine of x, which is defined mathematically as: sinh(x) = (exp(x) - exp(-x)) / 2 RETURN VALUE On success, these functi

canonicalize_file_name(3) - return the canonicalized filenam
The canonicalize_file_name() function returns a null-terminated string containing the canonicalized absolute pathname corresponding to path. In the returned str

auvirt(8) a program that shows data related to virtual machi
auvirt shows a list of guest sessions found in the audit logs. If a guest is specified, only the events related to that guest is considered. To specify a guest,

We can't live, work or learn in freedom unless the software we use is free.