man7/aio.7

   1 .\" Copyright (c) 2010 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH AIO 7 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 aio \- POSIX asynchronous I/O overview
   8 .SH DESCRIPTION
   9 The POSIX asynchronous I/O (AIO) interface allows applications
  10 to initiate one or more I/O operations that are performed
  11 asynchronously (i.e., in the background).
  12 The application can elect to be notified of completion of
  13 the I/O operation in a variety of ways:
  14 by delivery of a signal, by instantiation of a thread,
  15 or no notification at all.
  16 .PP
  17 The POSIX AIO interface consists of the following functions:
  18 .TP
  19 .BR aio_read (3)
  20 Enqueue a read request.
  21 This is the asynchronous analog of
  22 .BR read (2).
  23 .TP
  24 .BR aio_write (3)
  25 Enqueue a write request.
  26 This is the asynchronous analog of
  27 .BR write (2).
  28 .TP
  29 .BR aio_fsync (3)
  30 Enqueue a sync request for the I/O operations on a file descriptor.
  31 This is the asynchronous analog of
  32 .BR fsync (2)
  33 and
  34 .BR fdatasync (2).
  35 .TP
  36 .BR aio_error (3)
  37 Obtain the error status of an enqueued I/O request.
  38 .TP
  39 .BR aio_return (3)
  40 Obtain the return status of a completed I/O request.
  41 .TP
  42 .BR aio_suspend (3)
  43 Suspend the caller until one or more of a specified set of
  44 I/O requests completes.
  45 .TP
  46 .BR aio_cancel (3)
  47 Attempt to cancel outstanding I/O requests on a specified
  48 file descriptor.
  49 .TP
  50 .BR lio_listio (3)
  51 Enqueue multiple I/O requests using a single function call.
  52 .PP
  53 The
  54 .I aiocb
  55 ("asynchronous I/O control block") structure defines
  56 parameters that control an I/O operation.
  57 An argument of this type is employed with all of the functions listed above.
  58 This structure has the following form:
  59 .PP
  60 .in +4n
  61 .EX
  62 #include <aiocb.h>
  63
  64 struct aiocb {
  65     /* The order of these fields is implementation\-dependent */
  66
  67     int             aio_fildes;     /* File descriptor */
  68     off_t           aio_offset;     /* File offset */
  69     volatile void  *aio_buf;        /* Location of buffer */
  70     size_t          aio_nbytes;     /* Length of transfer */
  71     int             aio_reqprio;    /* Request priority */
  72     struct sigevent aio_sigevent;   /* Notification method */
  73     int             aio_lio_opcode; /* Operation to be performed;
  74                                        lio_listio() only */
  75
  76     /* Various implementation\-internal fields not shown */
  77 };
  78
  79 /* Operation codes for \[aq]aio_lio_opcode\[aq]: */
  80
  81 enum { LIO_READ, LIO_WRITE, LIO_NOP };
  82 .EE
  83 .in
  84 .PP
  85 The fields of this structure are as follows:
  86 .TP
  87 .I aio_fildes
  88 The file descriptor on which the I/O operation is to be performed.
  89 .TP
  90 .I aio_offset
  91 This is the file offset at which the I/O operation is to be performed.
  92 .TP
  93 .I aio_buf
  94 This is the buffer used to transfer data for a read or write operation.
  95 .TP
  96 .I aio_nbytes
  97 This is the size of the buffer pointed to by
  98 .IR aio_buf .
  99 .TP
 100 .I aio_reqprio
 101 This field specifies a value that is subtracted
 102 from the calling thread's real-time priority in order to
 103 determine the priority for execution of this I/O request (see
 104 .BR pthread_setschedparam (3)).
 105 The specified value must be between 0 and the value returned by
 106 .IR sysconf(_SC_AIO_PRIO_DELTA_MAX) .
 107 This field is ignored for file synchronization operations.
 108 .TP
 109 .I aio_sigevent
 110 This field is a structure that specifies how the caller is
 111 to be notified when the asynchronous I/O operation completes.
 112 Possible values for
 113 .I aio_sigevent.sigev_notify
 114 are
 115 .BR SIGEV_NONE ,
 116 .BR SIGEV_SIGNAL ,
 117 and
 118 .BR SIGEV_THREAD .
 119 See
 120 .BR sigevent (7)
 121 for further details.
 122 .TP
 123 .I aio_lio_opcode
 124 The type of operation to be performed; used only for
 125 .BR lio_listio (3).
 126 .PP
 127 In addition to the standard functions listed above,
 128 the GNU C library provides the following extension to the POSIX AIO API:
 129 .TP
 130 .BR aio_init (3)
 131 Set parameters for tuning the behavior of the glibc POSIX AIO implementation.
 132 .SH ERRORS
 133 .TP
 134 .B EINVAL
 135 The
 136 .I aio_reqprio
 137 field of the
 138 .I aiocb
 139 structure was less than 0,
 140 or was greater than the limit returned by the call
 141 .IR sysconf(_SC_AIO_PRIO_DELTA_MAX) .
 142 .SH VERSIONS
 143 The POSIX AIO interfaces are provided by glibc since glibc 2.1.
 144 .SH STANDARDS
 145 POSIX.1-2001, POSIX.1-2008.
 146 .SH NOTES
 147 It is a good idea to zero out the control block buffer before use (see
 148 .BR memset (3)).
 149 The control block buffer and the buffer pointed to by
 150 .I aio_buf
 151 must not be changed while the I/O operation is in progress.
 152 These buffers must remain valid until the I/O operation completes.
 153 .PP
 154 Simultaneous asynchronous read or write operations using the same
 155 .I aiocb
 156 structure yield undefined results.
 157 .PP
 158 The current Linux POSIX AIO implementation is provided in user space by glibc.
 159 This has a number of limitations, most notably that maintaining multiple
 160 threads to perform I/O operations is expensive and scales poorly.
 161 Work has been in progress for some time on a kernel
 162 state-machine-based implementation of asynchronous I/O
 163 (see
 164 .BR io_submit (2),
 165 .BR io_setup (2),
 166 .BR io_cancel (2),
 167 .BR io_destroy (2),
 168 .BR io_getevents (2)),
 169 but this implementation hasn't yet matured to the point where
 170 the POSIX AIO implementation can be completely
 171 reimplemented using the kernel system calls.
 172 .\" http://lse.sourceforge.net/io/aio.html
 173 .\" http://lse.sourceforge.net/io/aionotes.txt
 174 .\" http://lwn.net/Articles/148755/
 175 .SH EXAMPLES
 176 The program below opens each of the files named in its command-line
 177 arguments and queues a request on the resulting file descriptor using
 178 .BR aio_read (3).
 179 The program then loops,
 180 periodically monitoring each of the I/O operations
 181 that is still in progress using
 182 .BR aio_error (3).
 183 Each of the I/O requests is set up to provide notification by delivery
 184 of a signal.
 185 After all I/O requests have completed,
 186 the program retrieves their status using
 187 .BR aio_return (3).
 188 .PP
 189 The
 190 .B SIGQUIT
 191 signal (generated by typing control-\e) causes the program to request
 192 cancelation of each of the outstanding requests using
 193 .BR aio_cancel (3).
 194 .PP
 195 Here is an example of what we might see when running this program.
 196 In this example, the program queues two requests to standard input,
 197 and these are satisfied by two lines of input containing
 198 "abc" and "x".
 199 .PP
 200 .in +4n
 201 .EX
 202 $ \fB./a.out /dev/stdin /dev/stdin\fP
 203 opened /dev/stdin on descriptor 3
 204 opened /dev/stdin on descriptor 4
 205 aio_error():
 206     for request 0 (descriptor 3): In progress
 207     for request 1 (descriptor 4): In progress
 208 \fBabc\fP
 209 I/O completion signal received
 210 aio_error():
 211     for request 0 (descriptor 3): I/O succeeded
 212     for request 1 (descriptor 4): In progress
 213 aio_error():
 214     for request 1 (descriptor 4): In progress
 215 \fBx\fP
 216 I/O completion signal received
 217 aio_error():
 218     for request 1 (descriptor 4): I/O succeeded
 219 All I/O requests completed
 220 aio_return():
 221     for request 0 (descriptor 3): 4
 222     for request 1 (descriptor 4): 2
 223 .EE
 224 .in
 225 .SS Program source
 226 \&
 227 .EX
 228 #include <fcntl.h>
 229 #include <stdlib.h>
 230 #include <unistd.h>
 231 #include <stdio.h>
 232 #include <errno.h>
 233 #include <aio.h>
 234 #include <signal.h>
 235
 236 #define BUF_SIZE 20     /* Size of buffers for read operations */
 237
 238 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0)
 239
 240 struct ioRequest {      /* Application\-defined structure for tracking
 241                            I/O requests */
 242     int           reqNum;
 243     int           status;
 244     struct aiocb *aiocbp;
 245 };
 246
 247 static volatile sig_atomic_t gotSIGQUIT = 0;
 248                         /* On delivery of SIGQUIT, we attempt to
 249                            cancel all outstanding I/O requests */
 250
 251 static void             /* Handler for SIGQUIT */
 252 quitHandler(int sig)
 253 {
 254     gotSIGQUIT = 1;
 255 }
 256
 257 #define IO_SIGNAL SIGUSR1   /* Signal used to notify I/O completion */
 258
 259 static void                 /* Handler for I/O completion signal */
 260 aioSigHandler(int sig, siginfo_t *si, void *ucontext)
 261 {
 262     if (si\->si_code == SI_ASYNCIO) {
 263         write(STDOUT_FILENO, "I/O completion signal received\en", 31);
 264
 265         /* The corresponding ioRequest structure would be available as
 266                struct ioRequest *ioReq = si\->si_value.sival_ptr;
 267            and the file descriptor would then be available via
 268                ioReq\->aiocbp\->aio_fildes */
 269     }
 270 }
 271
 272 int
 273 main(int argc, char *argv[])
 274 {
 275     struct sigaction sa;
 276     int s;
 277     int numReqs;        /* Total number of queued I/O requests */
 278     int openReqs;       /* Number of I/O requests still in progress */
 279
 280     if (argc < 2) {
 281         fprintf(stderr, "Usage: %s <pathname> <pathname>...\en",
 282                 argv[0]);
 283         exit(EXIT_FAILURE);
 284     }
 285
 286     numReqs = argc \- 1;
 287
 288     /* Allocate our arrays. */
 289
 290     struct ioRequest *ioList = calloc(numReqs, sizeof(*ioList));
 291     if (ioList == NULL)
 292         errExit("calloc");
 293
 294     struct aiocb *aiocbList = calloc(numReqs, sizeof(*aiocbList));
 295     if (aiocbList == NULL)
 296         errExit("calloc");
 297
 298     /* Establish handlers for SIGQUIT and the I/O completion signal. */
 299
 300     sa.sa_flags = SA_RESTART;
 301     sigemptyset(&sa.sa_mask);
 302
 303     sa.sa_handler = quitHandler;
 304     if (sigaction(SIGQUIT, &sa, NULL) == \-1)
 305         errExit("sigaction");
 306
 307     sa.sa_flags = SA_RESTART | SA_SIGINFO;
 308     sa.sa_sigaction = aioSigHandler;
 309     if (sigaction(IO_SIGNAL, &sa, NULL) == \-1)
 310         errExit("sigaction");
 311
 312     /* Open each file specified on the command line, and queue
 313        a read request on the resulting file descriptor. */
 314
 315     for (size_t j = 0; j < numReqs; j++) {
 316         ioList[j].reqNum = j;
 317         ioList[j].status = EINPROGRESS;
 318         ioList[j].aiocbp = &aiocbList[j];
 319
 320         ioList[j].aiocbp\->aio_fildes = open(argv[j + 1], O_RDONLY);
 321         if (ioList[j].aiocbp\->aio_fildes == \-1)
 322             errExit("open");
 323         printf("opened %s on descriptor %d\en", argv[j + 1],
 324                 ioList[j].aiocbp\->aio_fildes);
 325
 326         ioList[j].aiocbp\->aio_buf = malloc(BUF_SIZE);
 327         if (ioList[j].aiocbp\->aio_buf == NULL)
 328             errExit("malloc");
 329
 330         ioList[j].aiocbp\->aio_nbytes = BUF_SIZE;
 331         ioList[j].aiocbp\->aio_reqprio = 0;
 332         ioList[j].aiocbp\->aio_offset = 0;
 333         ioList[j].aiocbp\->aio_sigevent.sigev_notify = SIGEV_SIGNAL;
 334         ioList[j].aiocbp\->aio_sigevent.sigev_signo = IO_SIGNAL;
 335         ioList[j].aiocbp\->aio_sigevent.sigev_value.sival_ptr =
 336                                 &ioList[j];
 337
 338         s = aio_read(ioList[j].aiocbp);
 339         if (s == \-1)
 340             errExit("aio_read");
 341     }
 342
 343     openReqs = numReqs;
 344
 345     /* Loop, monitoring status of I/O requests. */
 346
 347     while (openReqs > 0) {
 348         sleep(3);       /* Delay between each monitoring step */
 349
 350         if (gotSIGQUIT) {
 351
 352             /* On receipt of SIGQUIT, attempt to cancel each of the
 353                outstanding I/O requests, and display status returned
 354                from the cancelation requests. */
 355
 356             printf("got SIGQUIT; canceling I/O requests: \en");
 357
 358             for (size_t j = 0; j < numReqs; j++) {
 359                 if (ioList[j].status == EINPROGRESS) {
 360                     printf("    Request %zu on descriptor %d:", j,
 361                             ioList[j].aiocbp\->aio_fildes);
 362                     s = aio_cancel(ioList[j].aiocbp\->aio_fildes,
 363                             ioList[j].aiocbp);
 364                     if (s == AIO_CANCELED)
 365                         printf("I/O canceled\en");
 366                     else if (s == AIO_NOTCANCELED)
 367                         printf("I/O not canceled\en");
 368                     else if (s == AIO_ALLDONE)
 369                         printf("I/O all done\en");
 370                     else
 371                         perror("aio_cancel");
 372                 }
 373             }
 374
 375             gotSIGQUIT = 0;
 376         }
 377
 378         /* Check the status of each I/O request that is still
 379            in progress. */
 380
 381         printf("aio_error():\en");
 382         for (size_t j = 0; j < numReqs; j++) {
 383             if (ioList[j].status == EINPROGRESS) {
 384                 printf("    for request %zu (descriptor %d): ",
 385                         j, ioList[j].aiocbp\->aio_fildes);
 386                 ioList[j].status = aio_error(ioList[j].aiocbp);
 387
 388                 switch (ioList[j].status) {
 389                 case 0:
 390                     printf("I/O succeeded\en");
 391                     break;
 392                 case EINPROGRESS:
 393                     printf("In progress\en");
 394                     break;
 395                 case ECANCELED:
 396                     printf("Canceled\en");
 397                     break;
 398                 default:
 399                     perror("aio_error");
 400                     break;
 401                 }
 402
 403                 if (ioList[j].status != EINPROGRESS)
 404                     openReqs\-\-;
 405             }
 406         }
 407     }
 408
 409     printf("All I/O requests completed\en");
 410
 411     /* Check status return of all I/O requests. */
 412
 413     printf("aio_return():\en");
 414     for (size_t j = 0; j < numReqs; j++) {
 415         ssize_t s;
 416
 417         s = aio_return(ioList[j].aiocbp);
 418         printf("    for request %zu (descriptor %d): %zd\en",
 419                 j, ioList[j].aiocbp\->aio_fildes, s);
 420     }
 421
 422     exit(EXIT_SUCCESS);
 423 }
 424 .EE
 425 .SH SEE ALSO
 426 .ad l
 427 .nh
 428 .BR io_cancel (2),
 429 .BR io_destroy (2),
 430 .BR io_getevents (2),
 431 .BR io_setup (2),
 432 .BR io_submit (2),
 433 .BR aio_cancel (3),
 434 .BR aio_error (3),
 435 .BR aio_init (3),
 436 .BR aio_read (3),
 437 .BR aio_return (3),
 438 .BR aio_write (3),
 439 .BR lio_listio (3)
 440 .PP
 441 "Asynchronous I/O Support in Linux 2.5",
 442 Bhattacharya, Pratt, Pulavarty, and Morgan,
 443 Proceedings of the Linux Symposium, 2003,
 444 .UR https://www.kernel.org/doc/ols/2003/ols2003\-pages\-351\-366.pdf
 445 .UE