GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


man:aio

AIO(7) Linux Programmer's Manual AIO(7)

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:
     aio_read(3)     Enqueue  a read request.  This is the asynchronous ana-
                     log of read(2).
     aio_write(3)    Enqueue a write request.  This is the asynchronous ana-
                     log 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  speci-
                     fied file descriptor.
     lio_listio(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 <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_fildes      The file descriptor on which the I/O operation is to be
                     performed.
     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
                     lio_listio(3).
     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.

ERRORS

     EINVAL The aio_reqprio field of the aiocb structure was less than 0, or
            was    greater   than   the   limit   returned   by   the   call
            sysconf(_SC_AIO_PRIO_DELTA_MAX).

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
     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
     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
     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
     aio_cancel(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 aio_error():
             for request 0 (descriptor 3): In progress
             for  request  1  (descriptor 4): In progress abc I/O completion
         signal received aio_error():
             for request 0 (descriptor 3): I/O succeeded
             for request 1 (descriptor 4): In progress aio_error():
             for request 1 (descriptor 4): In progress x I/O completion sig-
         nal received aio_error():
             for  request  1  (descriptor 4): I/O succeeded All I/O requests
         completed aio_return():
             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 */
         } }
     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 <pathname> <pathname>...\n",
                     argv[0]);
             exit(EXIT_FAILURE);
         }
         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.sa_flags = SA_RESTART;
         sigemptyset(&sa.sa_mask);
         sa.sa_handler = quitHandler;
         if (sigaction(SIGQUIT, &sa, NULL) == -1)
             errExit("sigaction");
         sa.sa_flags = SA_RESTART | SA_SIGINFO;
         sa.sa_sigaction = aioSigHandler;
         if (sigaction(IO_SIGNAL, &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->aio_fildes = open(argv[j + 1], O_RDONLY);
             if (ioList[j].aiocbp->aio_fildes == -1)
                 errExit("open");
             printf("opened %s on descriptor %d\n", argv[j + 1],
                     ioList[j].aiocbp->aio_fildes);
             ioList[j].aiocbp->aio_buf = malloc(BUF_SIZE);
             if (ioList[j].aiocbp->aio_buf == NULL)
                 errExit("malloc");
             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 =
                                     &ioList[j];
             s = aio_read(ioList[j].aiocbp);
             if (s == -1)
                 errExit("aio_read");
         }
         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->aio_fildes);
                         s = aio_cancel(ioList[j].aiocbp->aio_fildes,
                                 ioList[j].aiocbp);
                         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");
                         else
                             errMsg("aio_cancel");
                     }
                 }
                 gotSIGQUIT = 0;
             }
             /* Check the status of each I/O request that is still
                in progress */
             printf("aio_error():\n");
             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");
                         break;
                     case EINPROGRESS:
                         printf("In progress\n");
                         break;
                     case ECANCELED:
                         printf("Canceled\n");
                         break;
                     default:
                         errMsg("aio_error");
                         break;
                     }
                     if (ioList[j].status != EINPROGRESS)
                         openReqs--;
                 }
             }
         }
         printf("All I/O requests completed\n");
         /* Check status return of all I/O requests */
         printf("aio_return():\n");
         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);
         }
         exit(EXIT_SUCCESS); }

SEE ALSO

     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,

COLOPHON

     This page is part of release 4.16 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
     https://www.kernel.org/doc/man-pages/.

Linux 2017-09-15 AIO(7)

/data/webs/external/dokuwiki/data/pages/man/aio.txt · Last modified: 2019/05/17 09:47 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki