LinuxReviws.org --get your your Linux knowledge
> Linux Reviews > Manual Pages (man) >

aio

Asynchronous IO


  1. aio.3.man
  2. aio.7.man


1. aio.3.man

Manpage of aio

aio

Section: Linux (3)
Updated: 2002-09-12
Index Return to Main Contents
 

NAME

aio - Asynchronous IO  

SYNOPSIS

#include <errno.h>


#include <aio.h>
 

DESCRIPTION

The POSIX.1b standard defines a new set of I/O operations which can significantly reduce the time an application spends waiting at I/O. The new functions allow a program to initiate one or more I/O operations and then immediately resume normal work while the I/O operations are executed in parallel. This functionality is available if the unistd.h file defines the symbol _POSIX_ASYNCHRONOUS_IO

These functions are part of the library with realtime functions named librt libc binary. The implementation of these functions can be done using support in the kernel (if available) or using an implementation based on threads at userlevel. In the latter case it might be necessary to link applications with the thread library libpthread in addition to librt and libaio

All AIO operations operate on files which were opened previously. There might be arbitrarily many operations running for one file. The asynchronous I/O operations are controlled using a data structure named struct aiocb It is defined in aio.h
 as follows.

struct aiocb
{
  int aio_fildes;               /* File desriptor.  */
  int aio_lio_opcode;           /* Operation to be performed.  */
  int aio_reqprio;              /* Request priority offset.  */
  volatile void *aio_buf;       /* Location of buffer.  */
  size_t aio_nbytes;            /* Length of transfer.  */
  struct sigevent aio_sigevent; /* Signal number and value.  */

  /* Internal members.  */
  struct aiocb *__next_prio;
  int __abs_prio;
  int __policy;
  int __error_code;
  __ssize_t __return_value;

#ifndef __USE_FILE_OFFSET64
  __off_t aio_offset;           /* File offset.  */
  char __pad[sizeof (__off64_t) - sizeof (__off_t)];
#else
  __off64_t aio_offset;         /* File offset.  */
#endif
  char __unused[32];
};

The POSIX.1b standard mandates that the struct aiocb structure contains at least the members described in the following table. There might be more elements which are used by the implementation, but depending upon these elements is not portable and is highly deprecated.

int aio_fildes
This element specifies the file descriptor to be used for the operation. It must be a legal descriptor, otherwise the operation will fail.

The device on which the file is opened must allow the seek operation. I.e., it is not possible to use any of the AIO operations on devices like terminals where an lseek
 call would lead to an error.

off_t aio_offset
This element specifies the offset in the file at which the operation (input or output) is performed. Since the operations are carried out in arbitrary order and more than one operation for one file descriptor can be started, one cannot expect a current read/write position of the file descriptor.
volatile void *aio_buf
This is a pointer to the buffer with the data to be written or the place where the read data is stored.
size_t aio_nbytes
This element specifies the length of the buffer pointed to by aio_buf
int aio_reqprio
If the platform has defined _POSIX_PRIORITIZED_IO and _POSIX_PRIORITY_SCHEDULING , the AIO requests are processed based on the current scheduling priority. The aio_reqprio element can then be used to lower the priority of the AIO operation.
struct sigevent aio_sigevent
This element specifies how the calling process is notified once the operation terminates. If the sigev_notify element is SIGEV_NONE , no notification is sent. If it is SIGEV_SIGNAL , the signal determined by sigev_signo is sent. Otherwise, sigev_notify must be SIGEV_THREAD is created which starts executing the function pointed to by sigev_notify_function
int aio_lio_opcode
This element is only used by the lio_listio
 and lio_listio64
 functions.  Since these functions allow an arbitrary number of operations to start at once, and each operation can be input or output (or nothing), the information must be stored in the control block. The possible values are:
LIO_READ
Start a read operation. Read from the file at position aio_offset
 and store the next  aio_nbytes
 bytes in the buffer pointed to by aio_buf
LIO_WRITE
Start a write operation. Write aio_nbytes bytes starting at aio_buf into the file starting at position aio_offset
LIO_NOP
Do nothing for this control block. This value is useful sometimes when an array of struct aiocb values contains holes, i.e., some of the values must not be handled although the whole array is presented to the lio_listio function.

When the sources are compiled using _FILE_OFFSET_BITS == 64 on a 32 bit machine, this type is in fact struct aiocb64 , since the LFS interface transparently replaces the struct aiocb definition.

For use with the AIO functions defined in the LFS, there is a similar type defined which replaces the types of the appropriate members with larger types but otherwise is equivalent to struct aiocb rticularly, all member names are the same.

/* The same for the 64bit offsets.  Please note that the members aio_fildes
   to __return_value have to be the same in aiocb and aiocb64.  */
#ifdef __USE_LARGEFILE64
struct aiocb64
{
  int aio_fildes;               /* File desriptor.  */
  int aio_lio_opcode;           /* Operation to be performed.  */
  int aio_reqprio;              /* Request priority offset.  */
  volatile void *aio_buf;       /* Location of buffer.  */
  size_t aio_nbytes;            /* Length of transfer.  */
  struct sigevent aio_sigevent; /* Signal number and value.  */

  /* Internal members.  */
  struct aiocb *__next_prio;
  int __abs_prio;
  int __policy;
  int __error_code;
  __ssize_t __return_value;

  __off64_t aio_offset;         /* File offset.  */
  char __unused[32];
};

int aio_fildes
This element specifies the file descriptor which is used for the operation. It must be a legal descriptor since otherwise the operation fails for obvious reasons. The device on which the file is opened must allow the seek operation. I.e., it is not possible to use any of the AIO operations on devices like terminals where an lseek
 call would lead to an error.
off64_t aio_offset
This element specifies at which offset in the file the operation (input or output) is performed. Since the operation are carried in arbitrary order and more than one operation for one file descriptor can be started, one cannot expect a current read/write position of the file descriptor.
volatile void *aio_buf
This is a pointer to the buffer with the data to be written or the place where the read data is stored.
size_t aio_nbytes
This element specifies the length of the buffer pointed to by aio_buf
int aio_reqprio
If for the platform _POSIX_PRIORITIZED_IO and _POSIX_PRIORITY_SCHEDULING are defined the AIO requests are processed based on the current scheduling priority. The aio_reqprio element can then be used to lower the priority of the AIO operation.
struct sigevent aio_sigevent
This element specifies how the calling process is notified once the operation terminates. If the sigev_notify , element is SIGEV_NONE no notification is sent. If it is SIGEV_SIGNAL , the signal determined by sigev_signo is sent. Otherwise, sigev_notify
 must be  SIGEV_THREAD in which case a thread which starts executing the function pointed to by sigev_notify_function
int aio_lio_opcode
This element is only used by the lio_listio and lio_listio64 functions. Since these functions allow an arbitrary number of operations to start at once, and since each operation can be input or output (or nothing), the information must be stored in the control block. See the description of struct aiocb for a description of the possible values.

When the sources are compiled using _FILE_OFFSET_BITS == 64 on a 32 bit machine, this type is available under the name struct aiocb64 , since the LFS transparently replaces the old interface.  

RETURN VALUES

 

ERRORS

 

SEE ALSO

aio_cancel(3), aio_cancel64(3), aio_error(3), aio_error64(3), aio_fsync(3), aio_fsync64(3), aio_init(3), aio_read(3), aio_read64(3), aio_return(3), aio_return64(3), aio_suspend(3), aio_suspend64(3), aio_write(3), aio_write64(3), errno(3),


 

Index

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUES
ERRORS
SEE ALSO

This document was created by man2html using the manual pages.
Time: 17:30:14 GMT, October 23, 2013

2. aio.7.man

Manpage of AIO

AIO

Section: Linux Programmer's Manual (7)
Updated: 2010-10-02
Index Return to Main Contents
 

NAME

aio - POSIX asynchronous I/O overview  

DESCRIPTION

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 call.

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 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.
 

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 userspace 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.  

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.  

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 signal 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 <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)
{
    write(STDOUT_FILENO, "I/O completion signal received
", 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>...
", 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
", 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:
"); 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
"); else if (s == AIO_NOTCANCELED) printf("I/O not canceled
"); else if (s == AIO_ALLDONE) printf("I/O all done
"); else errMsg("aio_cancel"); } } gotSIGQUIT = 0; } /* Check the status of each I/O request that is still in progress */ printf("aio_error():
"); 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
"); break; case EINPROGRESS: printf("In progress
"); break; case ECANCELED: printf("Canceled
"); break; default: errMsg("aio_error"); break; } if (ioList[j].status != EINPROGRESS) openReqs--; } } } printf("All I/O requests completed
"); /* Check status return of all I/O requests */ printf("aio_return():
"); for (j = 0; j < numReqs; j++) { ssize_t s; s = aio_return(ioList[j].aiocbp); printf(" for request %d (descriptor %d): %ld
", j, ioList[j].aiocbp->aio_fildes, (long) 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), http://www.squid-cache.org/~adrian/Reprint-Pulavarty-OLS2003.pdf  

COLOPHON

This page is part of release 3.32 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/.


 

Index

NAME
DESCRIPTION
NOTES
ERRORS
VERSIONS
CONFORMING TO
EXAMPLE
Program source
SEE ALSO
COLOPHON

This document was created by man2html using the manual pages.
Time: 17:30:14 GMT, October 23, 2013

Meet new people