original/man7/aio.7

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