diff options
Diffstat (limited to 'man/man7/aio.7')
| -rw-r--r-- | man/man7/aio.7 | 446 |
1 files changed, 446 insertions, 0 deletions
diff --git a/man/man7/aio.7 b/man/man7/aio.7 new file mode 100644 index 000000000..513fbbb73 --- /dev/null +++ b/man/man7/aio.7 @@ -0,0 +1,446 @@ +.\" Copyright (c) 2010 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH AIO 7 (date) "Linux man-pages (unreleased)" +.SH NAME +aio \- POSIX asynchronous I/O overview +.SH 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. +.P +The POSIX AIO interface consists of the following functions: +.TP +.BR aio_read (3) +Enqueue a read request. +This is the asynchronous analog of +.BR read (2). +.TP +.BR aio_write (3) +Enqueue a write request. +This is the asynchronous analog of +.BR write (2). +.TP +.BR aio_fsync (3) +Enqueue a sync request for the I/O operations on a file descriptor. +This is the asynchronous analog of +.BR fsync (2) +and +.BR fdatasync (2). +.TP +.BR aio_error (3) +Obtain the error status of an enqueued I/O request. +.TP +.BR aio_return (3) +Obtain the return status of a completed I/O request. +.TP +.BR aio_suspend (3) +Suspend the caller until one or more of a specified set of +I/O requests completes. +.TP +.BR aio_cancel (3) +Attempt to cancel outstanding I/O requests on a specified +file descriptor. +.TP +.BR lio_listio (3) +Enqueue multiple I/O requests using a single function call. +.P +The +.I 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: +.P +.in +4n +.EX +#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 \[aq]aio_lio_opcode\[aq]: */ +\& +enum { LIO_READ, LIO_WRITE, LIO_NOP }; +.EE +.in +.P +The fields of this structure are as follows: +.TP +.I aio_fildes +The file descriptor on which the I/O operation is to be performed. +.TP +.I aio_offset +This is the file offset at which the I/O operation is to be performed. +.TP +.I aio_buf +This is the buffer used to transfer data for a read or write operation. +.TP +.I aio_nbytes +This is the size of the buffer pointed to by +.IR aio_buf . +.TP +.I 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 +.BR pthread_setschedparam (3)). +The specified value must be between 0 and the value returned by +.IR sysconf(_SC_AIO_PRIO_DELTA_MAX) . +This field is ignored for file synchronization operations. +.TP +.I 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 +.I aio_sigevent.sigev_notify +are +.BR SIGEV_NONE , +.BR SIGEV_SIGNAL , +and +.BR SIGEV_THREAD . +See +.BR sigevent (3type) +for further details. +.TP +.I aio_lio_opcode +The type of operation to be performed; used only for +.BR lio_listio (3). +.P +In addition to the standard functions listed above, +the GNU C library provides the following extension to the POSIX AIO API: +.TP +.BR aio_init (3) +Set parameters for tuning the behavior of the glibc POSIX AIO implementation. +.SH ERRORS +.TP +.B EINVAL +The +.I aio_reqprio +field of the +.I aiocb +structure was less than 0, +or was greater than the limit returned by the call +.IR sysconf(_SC_AIO_PRIO_DELTA_MAX) . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +glibc 2.1. +.SH NOTES +It is a good idea to zero out the control block buffer before use (see +.BR memset (3)). +The control block buffer and the buffer pointed to by +.I 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. +.P +Simultaneous asynchronous read or write operations using the same +.I aiocb +structure yield undefined results. +.P +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 +.BR io_submit (2), +.BR io_setup (2), +.BR io_cancel (2), +.BR io_destroy (2), +.BR 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. +.\" http://lse.sourceforge.net/io/aio.html +.\" http://lse.sourceforge.net/io/aionotes.txt +.\" http://lwn.net/Articles/148755/ +.SH EXAMPLES +The program below opens each of the files named in its command-line +arguments and queues a request on the resulting file descriptor using +.BR aio_read (3). +The program then loops, +periodically monitoring each of the I/O operations +that is still in progress using +.BR 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 +.BR aio_return (3). +.P +The +.B SIGQUIT +signal (generated by typing control-\e) causes the program to request +cancelation of each of the outstanding requests using +.BR aio_cancel (3). +.P +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". +.P +.in +4n +.EX +$ \fB./a.out /dev/stdin /dev/stdin\fP +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 +\fBabc\fP +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 +\fBx\fP +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 +.EE +.in +.SS Program source +\& +.EX +#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) +\& +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\en", 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 sigaction sa; + int s; + 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>...\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + numReqs = argc \- 1; +\& + /* Allocate our arrays. */ +\& + struct ioRequest *ioList = calloc(numReqs, sizeof(*ioList)); + if (ioList == NULL) + errExit("calloc"); +\& + struct aiocb *aiocbList = calloc(numReqs, sizeof(*aiocbList)); + 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 (size_t 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\en", 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 cancelation requests. */ +\& + printf("got SIGQUIT; canceling I/O requests: \en"); +\& + for (size_t j = 0; j < numReqs; j++) { + if (ioList[j].status == EINPROGRESS) { + printf(" Request %zu 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\en"); + else if (s == AIO_NOTCANCELED) + printf("I/O not canceled\en"); + else if (s == AIO_ALLDONE) + printf("I/O all done\en"); + else + perror("aio_cancel"); + } + } +\& + gotSIGQUIT = 0; + } +\& + /* Check the status of each I/O request that is still + in progress. */ +\& + printf("aio_error():\en"); + for (size_t j = 0; j < numReqs; j++) { + if (ioList[j].status == EINPROGRESS) { + printf(" for request %zu (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\en"); + break; + case EINPROGRESS: + printf("In progress\en"); + break; + case ECANCELED: + printf("Canceled\en"); + break; + default: + perror("aio_error"); + break; + } +\& + if (ioList[j].status != EINPROGRESS) + openReqs\-\-; + } + } + } +\& + printf("All I/O requests completed\en"); +\& + /* Check status return of all I/O requests. */ +\& + printf("aio_return():\en"); + for (size_t j = 0; j < numReqs; j++) { + ssize_t s; +\& + s = aio_return(ioList[j].aiocbp); + printf(" for request %zu (descriptor %d): %zd\en", + j, ioList[j].aiocbp\->aio_fildes, s); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR io_cancel (2), +.BR io_destroy (2), +.BR io_getevents (2), +.BR io_setup (2), +.BR io_submit (2), +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_init (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_write (3), +.BR lio_listio (3) +.P +"Asynchronous I/O Support in Linux 2.5", +Bhattacharya, Pratt, Pulavarty, and Morgan, +Proceedings of the Linux Symposium, 2003, +.UR https://www.kernel.org/doc/ols/2003/ols2003\-pages\-351\-366.pdf +.UE |