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 .P
  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 .P
  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 .P
  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 .P
  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 (3type)
 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 .P
 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 STANDARDS
 143 POSIX.1-2008.
 144 .SH HISTORY
 145 POSIX.1-2001.
 146 glibc 2.1.
 147 .SH NOTES
 148 It is a good idea to zero out the control block buffer before use (see
 149 .BR memset (3)).
 150 The control block buffer and the buffer pointed to by
 151 .I aio_buf
 152 must not be changed while the I/O operation is in progress.
 153 These buffers must remain valid until the I/O operation completes.
 154 .P
 155 Simultaneous asynchronous read or write operations using the same
 156 .I aiocb
 157 structure yield undefined results.
 158 .P
 159 The current Linux POSIX AIO implementation is provided in user space by glibc.
 160 This has a number of limitations, most notably that maintaining multiple
 161 threads to perform I/O operations is expensive and scales poorly.
 162 Work has been in progress for some time on a kernel
 163 state-machine-based implementation of asynchronous I/O
 164 (see
 165 .BR io_submit (2),
 166 .BR io_setup (2),
 167 .BR io_cancel (2),
 168 .BR io_destroy (2),
 169 .BR io_getevents (2)),
 170 but this implementation hasn't yet matured to the point where
 171 the POSIX AIO implementation can be completely
 172 reimplemented using the kernel system calls.
 173 .\" http://lse.sourceforge.net/io/aio.html
 174 .\" http://lse.sourceforge.net/io/aionotes.txt
 175 .\" http://lwn.net/Articles/148755/
 176 .SH EXAMPLES
 177 The program below opens each of the files named in its command-line
 178 arguments and queues a request on the resulting file descriptor using
 179 .BR aio_read (3).
 180 The program then loops,
 181 periodically monitoring each of the I/O operations
 182 that is still in progress using
 183 .BR aio_error (3).
 184 Each of the I/O requests is set up to provide notification by delivery
 185 of a signal.
 186 After all I/O requests have completed,
 187 the program retrieves their status using
 188 .BR aio_return (3).
 189 .P
 190 The
 191 .B SIGQUIT
 192 signal (generated by typing control-\e) causes the program to request
 193 cancelation of each of the outstanding requests using
 194 .BR aio_cancel (3).
 195 .P
 196 Here is an example of what we might see when running this program.
 197 In this example, the program queues two requests to standard input,
 198 and these are satisfied by two lines of input containing
 199 "abc" and "x".
 200 .P
 201 .in +4n
 202 .EX
 203 $ \fB./a.out /dev/stdin /dev/stdin\fP
 204 opened /dev/stdin on descriptor 3
 205 opened /dev/stdin on descriptor 4
 206 aio_error():
 207     for request 0 (descriptor 3): In progress
 208     for request 1 (descriptor 4): In progress
 209 \fBabc\fP
 210 I/O completion signal received
 211 aio_error():
 212     for request 0 (descriptor 3): I/O succeeded
 213     for request 1 (descriptor 4): In progress
 214 aio_error():
 215     for request 1 (descriptor 4): In progress
 216 \fBx\fP
 217 I/O completion signal received
 218 aio_error():
 219     for request 1 (descriptor 4): I/O succeeded
 220 All I/O requests completed
 221 aio_return():
 222     for request 0 (descriptor 3): 4
 223     for request 1 (descriptor 4): 2
 224 .EE
 225 .in
 226 .SS Program source
 227 \&
 228 .EX
 229 #include <fcntl.h>
 230 #include <stdlib.h>
 231 #include <unistd.h>
 232 #include <stdio.h>
 233 #include <errno.h>
 234 #include <aio.h>
 235 #include <signal.h>
 236 \&
 237 #define BUF_SIZE 20     /* Size of buffers for read operations */
 238 \&
 239 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0)
 240 \&
 241 struct ioRequest {      /* Application\-defined structure for tracking
 242                            I/O requests */
 243     int           reqNum;
 244     int           status;
 245     struct aiocb *aiocbp;
 246 };
 247 \&
 248 static volatile sig_atomic_t gotSIGQUIT = 0;
 249                         /* On delivery of SIGQUIT, we attempt to
 250                            cancel all outstanding I/O requests */
 251 \&
 252 static void             /* Handler for SIGQUIT */
 253 quitHandler(int sig)
 254 {
 255     gotSIGQUIT = 1;
 256 }
 257 \&
 258 #define IO_SIGNAL SIGUSR1   /* Signal used to notify I/O completion */
 259 \&
 260 static void                 /* Handler for I/O completion signal */
 261 aioSigHandler(int sig, siginfo_t *si, void *ucontext)
 262 {
 263     if (si\->si_code == SI_ASYNCIO) {
 264         write(STDOUT_FILENO, "I/O completion signal received\en", 31);
 265 \&
 266         /* The corresponding ioRequest structure would be available as
 267                struct ioRequest *ioReq = si\->si_value.sival_ptr;
 268            and the file descriptor would then be available via
 269                ioReq\->aiocbp\->aio_fildes */
 270     }
 271 }
 272 \&
 273 int
 274 main(int argc, char *argv[])
 275 {
 276     struct sigaction sa;
 277     int s;
 278     int numReqs;        /* Total number of queued I/O requests */
 279     int openReqs;       /* Number of I/O requests still in progress */
 280 \&
 281     if (argc < 2) {
 282         fprintf(stderr, "Usage: %s <pathname> <pathname>...\en",
 283                 argv[0]);
 284         exit(EXIT_FAILURE);
 285     }
 286 \&
 287     numReqs = argc \- 1;
 288 \&
 289     /* Allocate our arrays. */
 290 \&
 291     struct ioRequest *ioList = calloc(numReqs, sizeof(*ioList));
 292     if (ioList == NULL)
 293         errExit("calloc");
 294 \&
 295     struct aiocb *aiocbList = calloc(numReqs, sizeof(*aiocbList));
 296     if (aiocbList == NULL)
 297         errExit("calloc");
 298 \&
 299     /* Establish handlers for SIGQUIT and the I/O completion signal. */
 300 \&
 301     sa.sa_flags = SA_RESTART;
 302     sigemptyset(&sa.sa_mask);
 303 \&
 304     sa.sa_handler = quitHandler;
 305     if (sigaction(SIGQUIT, &sa, NULL) == \-1)
 306         errExit("sigaction");
 307 \&
 308     sa.sa_flags = SA_RESTART | SA_SIGINFO;
 309     sa.sa_sigaction = aioSigHandler;
 310     if (sigaction(IO_SIGNAL, &sa, NULL) == \-1)
 311         errExit("sigaction");
 312 \&
 313     /* Open each file specified on the command line, and queue
 314        a read request on the resulting file descriptor. */
 315 \&
 316     for (size_t j = 0; j < numReqs; j++) {
 317         ioList[j].reqNum = j;
 318         ioList[j].status = EINPROGRESS;
 319         ioList[j].aiocbp = &aiocbList[j];
 320 \&
 321         ioList[j].aiocbp\->aio_fildes = open(argv[j + 1], O_RDONLY);
 322         if (ioList[j].aiocbp\->aio_fildes == \-1)
 323             errExit("open");
 324         printf("opened %s on descriptor %d\en", argv[j + 1],
 325                 ioList[j].aiocbp\->aio_fildes);
 326 \&
 327         ioList[j].aiocbp\->aio_buf = malloc(BUF_SIZE);
 328         if (ioList[j].aiocbp\->aio_buf == NULL)
 329             errExit("malloc");
 330 \&
 331         ioList[j].aiocbp\->aio_nbytes = BUF_SIZE;
 332         ioList[j].aiocbp\->aio_reqprio = 0;
 333         ioList[j].aiocbp\->aio_offset = 0;
 334         ioList[j].aiocbp\->aio_sigevent.sigev_notify = SIGEV_SIGNAL;
 335         ioList[j].aiocbp\->aio_sigevent.sigev_signo = IO_SIGNAL;
 336         ioList[j].aiocbp\->aio_sigevent.sigev_value.sival_ptr =
 337                                 &ioList[j];
 338 \&
 339         s = aio_read(ioList[j].aiocbp);
 340         if (s == \-1)
 341             errExit("aio_read");
 342     }
 343 \&
 344     openReqs = numReqs;
 345 \&
 346     /* Loop, monitoring status of I/O requests. */
 347 \&
 348     while (openReqs > 0) {
 349         sleep(3);       /* Delay between each monitoring step */
 350 \&
 351         if (gotSIGQUIT) {
 352 \&
 353             /* On receipt of SIGQUIT, attempt to cancel each of the
 354                outstanding I/O requests, and display status returned
 355                from the cancelation requests. */
 356 \&
 357             printf("got SIGQUIT; canceling I/O requests: \en");
 358 \&
 359             for (size_t j = 0; j < numReqs; j++) {
 360                 if (ioList[j].status == EINPROGRESS) {
 361                     printf("    Request %zu on descriptor %d:", j,
 362                             ioList[j].aiocbp\->aio_fildes);
 363                     s = aio_cancel(ioList[j].aiocbp\->aio_fildes,
 364                             ioList[j].aiocbp);
 365                     if (s == AIO_CANCELED)
 366                         printf("I/O canceled\en");
 367                     else if (s == AIO_NOTCANCELED)
 368                         printf("I/O not canceled\en");
 369                     else if (s == AIO_ALLDONE)
 370                         printf("I/O all done\en");
 371                     else
 372                         perror("aio_cancel");
 373                 }
 374             }
 375 \&
 376             gotSIGQUIT = 0;
 377         }
 378 \&
 379         /* Check the status of each I/O request that is still
 380            in progress. */
 381 \&
 382         printf("aio_error():\en");
 383         for (size_t j = 0; j < numReqs; j++) {
 384             if (ioList[j].status == EINPROGRESS) {
 385                 printf("    for request %zu (descriptor %d): ",
 386                         j, ioList[j].aiocbp\->aio_fildes);
 387                 ioList[j].status = aio_error(ioList[j].aiocbp);
 388 \&
 389                 switch (ioList[j].status) {
 390                 case 0:
 391                     printf("I/O succeeded\en");
 392                     break;
 393                 case EINPROGRESS:
 394                     printf("In progress\en");
 395                     break;
 396                 case ECANCELED:
 397                     printf("Canceled\en");
 398                     break;
 399                 default:
 400                     perror("aio_error");
 401                     break;
 402                 }
 403 \&
 404                 if (ioList[j].status != EINPROGRESS)
 405                     openReqs\-\-;
 406             }
 407         }
 408     }
 409 \&
 410     printf("All I/O requests completed\en");
 411 \&
 412     /* Check status return of all I/O requests. */
 413 \&
 414     printf("aio_return():\en");
 415     for (size_t j = 0; j < numReqs; j++) {
 416         ssize_t s;
 417 \&
 418         s = aio_return(ioList[j].aiocbp);
 419         printf("    for request %zu (descriptor %d): %zd\en",
 420                 j, ioList[j].aiocbp\->aio_fildes, s);
 421     }
 422 \&
 423     exit(EXIT_SUCCESS);
 424 }
 425 .EE
 426 .SH SEE ALSO
 427 .ad l
 428 .nh
 429 .BR io_cancel (2),
 430 .BR io_destroy (2),
 431 .BR io_getevents (2),
 432 .BR io_setup (2),
 433 .BR io_submit (2),
 434 .BR aio_cancel (3),
 435 .BR aio_error (3),
 436 .BR aio_init (3),
 437 .BR aio_read (3),
 438 .BR aio_return (3),
 439 .BR aio_write (3),
 440 .BR lio_listio (3)
 441 .P
 442 "Asynchronous I/O Support in Linux 2.5",
 443 Bhattacharya, Pratt, Pulavarty, and Morgan,
 444 Proceedings of the Linux Symposium, 2003,
 445 .UR https://www.kernel.org/doc/ols/2003/ols2003\-pages\-351\-366.pdf
 446 .UE