aio(7) - f38

1AIO(7)                 Miscellaneous Information Manual                 AIO(7)
2
3
4

NAME

6       aio - POSIX asynchronous I/O overview
7

DESCRIPTION

9       The  POSIX asynchronous I/O (AIO) interface allows applications to ini‐
10       tiate one or more I/O  operations  that  are  performed  asynchronously
11       (i.e., in the background).  The application can elect to be notified of
12       completion of the I/O operation in a variety of ways: by delivery of  a
13       signal, by instantiation of a thread, or no notification at all.
14
15       The POSIX AIO interface consists of the following functions:
16
17       aio_read(3)
18              Enqueue  a  read  request.   This  is the asynchronous analog of
19              read(2).
20
21       aio_write(3)
22              Enqueue a write request.  This is  the  asynchronous  analog  of
23              write(2).
24
25       aio_fsync(3)
26              Enqueue a sync request for the I/O operations on a file descrip‐
27              tor.  This is the asynchronous analog  of  fsync(2)  and  fdata‐
28              sync(2).
29
30       aio_error(3)
31              Obtain the error status of an enqueued I/O request.
32
33       aio_return(3)
34              Obtain the return status of a completed I/O request.
35
36       aio_suspend(3)
37              Suspend  the  caller until one or more of a specified set of I/O
38              requests completes.
39
40       aio_cancel(3)
41              Attempt to cancel outstanding I/O requests on a  specified  file
42              descriptor.
43
44       lio_listio(3)
45              Enqueue multiple I/O requests using a single function call.
46
47       The  aiocb ("asynchronous I/O control block") structure defines parame‐
48       ters that control an I/O operation.  An argument of this  type  is  em‐
49       ployed  with all of the functions listed above.  This structure has the
50       following form:
51
52           #include <aiocb.h>
53
54           struct aiocb {
55               /* The order of these fields is implementation-dependent */
56
57               int             aio_fildes;     /* File descriptor */
58               off_t           aio_offset;     /* File offset */
59               volatile void  *aio_buf;        /* Location of buffer */
60               size_t          aio_nbytes;     /* Length of transfer */
61               int             aio_reqprio;    /* Request priority */
62               struct sigevent aio_sigevent;   /* Notification method */
63               int             aio_lio_opcode; /* Operation to be performed;
64                                                  lio_listio() only */
65
66               /* Various implementation-internal fields not shown */
67           };
68
69           /* Operation codes for 'aio_lio_opcode': */
70
71           enum { LIO_READ, LIO_WRITE, LIO_NOP };
72
73       The fields of this structure are as follows:
74
75       aio_fildes
76              The file descriptor on which the I/O operation  is  to  be  per‐
77              formed.
78
79       aio_offset
80              This is the file offset at which the I/O operation is to be per‐
81              formed.
82
83       aio_buf
84              This is the buffer used to transfer data for a read or write op‐
85              eration.
86
87       aio_nbytes
88              This is the size of the buffer pointed to by aio_buf.
89
90       aio_reqprio
91              This field specifies a value that is subtracted from the calling
92              thread's real-time priority in order to determine  the  priority
93              for   execution  of  this  I/O  request  (see  pthread_setsched‐
94              param(3)).  The specified value must be between 0 and the  value
95              returned  by sysconf(_SC_AIO_PRIO_DELTA_MAX).  This field is ig‐
96              nored for file synchronization operations.
97
98       aio_sigevent
99              This field is a structure that specifies how the caller is to be
100              notified  when the asynchronous I/O operation completes.  Possi‐
101              ble  values  for   aio_sigevent.sigev_notify   are   SIGEV_NONE,
102              SIGEV_SIGNAL, and SIGEV_THREAD.  See sigevent(7) for further de‐
103              tails.
104
105       aio_lio_opcode
106              The type of operation to be performed; used  only  for  lio_lis‐
107              tio(3).
108
109       In  addition  to the standard functions listed above, the GNU C library
110       provides the following extension to the POSIX AIO API:
111
112       aio_init(3)
113              Set parameters for tuning the behavior of the  glibc  POSIX  AIO
114              implementation.
115

ERRORS

117       EINVAL The aio_reqprio field of the aiocb structure was less than 0, or
118              was   greater   than   the   limit   returned   by   the    call
119              sysconf(_SC_AIO_PRIO_DELTA_MAX).
120

STANDARDS

122       POSIX.1-2008.
123

HISTORY

125       POSIX.1-2001.  glibc 2.1.
126

NOTES

128       It  is a good idea to zero out the control block buffer before use (see
129       memset(3)).  The control block buffer and  the  buffer  pointed  to  by
130       aio_buf  must  not  be  changed while the I/O operation is in progress.
131       These buffers must remain valid until the I/O operation completes.
132
133       Simultaneous asynchronous read or write operations using the same aiocb
134       structure yield undefined results.
135
136       The current Linux POSIX AIO implementation is provided in user space by
137       glibc.  This has a number of limitations, most notably that maintaining
138       multiple  threads  to  perform  I/O  operations is expensive and scales
139       poorly.  Work has been in progress for some time on a kernel  state-ma‐
140       chine-based  implementation  of  asynchronous  I/O  (see  io_submit(2),
141       io_setup(2), io_cancel(2), io_destroy(2),  io_getevents(2)),  but  this
142       implementation  hasn't yet matured to the point where the POSIX AIO im‐
143       plementation can be completely reimplemented using  the  kernel  system
144       calls.
145

EXAMPLES

147       The program below opens each of the files named in its command-line ar‐
148       guments and queues a request on the  resulting  file  descriptor  using
149       aio_read(3).   The  program then loops, periodically monitoring each of
150       the I/O operations that is still in progress using aio_error(3).   Each
151       of  the I/O requests is set up to provide notification by delivery of a
152       signal.  After all I/O requests have completed, the  program  retrieves
153       their status using aio_return(3).
154
155       The  SIGQUIT  signal (generated by typing control-\) causes the program
156       to request cancelation  of  each  of  the  outstanding  requests  using
157       aio_cancel(3).
158
159       Here  is an example of what we might see when running this program.  In
160       this example, the program queues two requests to  standard  input,  and
161       these are satisfied by two lines of input containing "abc" and "x".
162
163           $ ./a.out /dev/stdin /dev/stdin
164           opened /dev/stdin on descriptor 3
165           opened /dev/stdin on descriptor 4
166           aio_error():
167               for request 0 (descriptor 3): In progress
168               for request 1 (descriptor 4): In progress
169           abc
170           I/O completion signal received
171           aio_error():
172               for request 0 (descriptor 3): I/O succeeded
173               for request 1 (descriptor 4): In progress
174           aio_error():
175               for request 1 (descriptor 4): In progress
176           x
177           I/O completion signal received
178           aio_error():
179               for request 1 (descriptor 4): I/O succeeded
180           All I/O requests completed
181           aio_return():
182               for request 0 (descriptor 3): 4
183               for request 1 (descriptor 4): 2
184
185   Program source
186
187       #include <fcntl.h>
188       #include <stdlib.h>
189       #include <unistd.h>
190       #include <stdio.h>
191       #include <errno.h>
192       #include <aio.h>
193       #include <signal.h>
194
195       #define BUF_SIZE 20     /* Size of buffers for read operations */
196
197       #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0)
198
199       struct ioRequest {      /* Application-defined structure for tracking
200                                  I/O requests */
201           int           reqNum;
202           int           status;
203           struct aiocb *aiocbp;
204       };
205
206       static volatile sig_atomic_t gotSIGQUIT = 0;
207                               /* On delivery of SIGQUIT, we attempt to
208                                  cancel all outstanding I/O requests */
209
210       static void             /* Handler for SIGQUIT */
211       quitHandler(int sig)
212       {
213           gotSIGQUIT = 1;
214       }
215
216       #define IO_SIGNAL SIGUSR1   /* Signal used to notify I/O completion */
217
218       static void                 /* Handler for I/O completion signal */
219       aioSigHandler(int sig, siginfo_t *si, void *ucontext)
220       {
221           if (si->si_code == SI_ASYNCIO) {
222               write(STDOUT_FILENO, "I/O completion signal received\n", 31);
223
224               /* The corresponding ioRequest structure would be available as
225                      struct ioRequest *ioReq = si->si_value.sival_ptr;
226                  and the file descriptor would then be available via
227                      ioReq->aiocbp->aio_fildes */
228           }
229       }
230
231       int
232       main(int argc, char *argv[])
233       {
234           struct sigaction sa;
235           int s;
236           int numReqs;        /* Total number of queued I/O requests */
237           int openReqs;       /* Number of I/O requests still in progress */
238
239           if (argc < 2) {
240               fprintf(stderr, "Usage: %s <pathname> <pathname>...\n",
241                       argv[0]);
242               exit(EXIT_FAILURE);
243           }
244
245           numReqs = argc - 1;
246
247           /* Allocate our arrays. */
248
249           struct ioRequest *ioList = calloc(numReqs, sizeof(*ioList));
250           if (ioList == NULL)
251               errExit("calloc");
252
253           struct aiocb *aiocbList = calloc(numReqs, sizeof(*aiocbList));
254           if (aiocbList == NULL)
255               errExit("calloc");
256
257           /* Establish handlers for SIGQUIT and the I/O completion signal. */
258
259           sa.sa_flags = SA_RESTART;
260           sigemptyset(&sa.sa_mask);
261
262           sa.sa_handler = quitHandler;
263           if (sigaction(SIGQUIT, &sa, NULL) == -1)
264               errExit("sigaction");
265
266           sa.sa_flags = SA_RESTART | SA_SIGINFO;
267           sa.sa_sigaction = aioSigHandler;
268           if (sigaction(IO_SIGNAL, &sa, NULL) == -1)
269               errExit("sigaction");
270
271           /* Open each file specified on the command line, and queue
272              a read request on the resulting file descriptor. */
273
274           for (size_t j = 0; j < numReqs; j++) {
275               ioList[j].reqNum = j;
276               ioList[j].status = EINPROGRESS;
277               ioList[j].aiocbp = &aiocbList[j];
278
279               ioList[j].aiocbp->aio_fildes = open(argv[j + 1], O_RDONLY);
280               if (ioList[j].aiocbp->aio_fildes == -1)
281                   errExit("open");
282               printf("opened %s on descriptor %d\n", argv[j + 1],
283                       ioList[j].aiocbp->aio_fildes);
284
285               ioList[j].aiocbp->aio_buf = malloc(BUF_SIZE);
286               if (ioList[j].aiocbp->aio_buf == NULL)
287                   errExit("malloc");
288
289               ioList[j].aiocbp->aio_nbytes = BUF_SIZE;
290               ioList[j].aiocbp->aio_reqprio = 0;
291               ioList[j].aiocbp->aio_offset = 0;
292               ioList[j].aiocbp->aio_sigevent.sigev_notify = SIGEV_SIGNAL;
293               ioList[j].aiocbp->aio_sigevent.sigev_signo = IO_SIGNAL;
294               ioList[j].aiocbp->aio_sigevent.sigev_value.sival_ptr =
295                                       &ioList[j];
296
297               s = aio_read(ioList[j].aiocbp);
298               if (s == -1)
299                   errExit("aio_read");
300           }
301
302           openReqs = numReqs;
303
304           /* Loop, monitoring status of I/O requests. */
305
306           while (openReqs > 0) {
307               sleep(3);       /* Delay between each monitoring step */
308
309               if (gotSIGQUIT) {
310
311                   /* On receipt of SIGQUIT, attempt to cancel each of the
312                      outstanding I/O requests, and display status returned
313                      from the cancelation requests. */
314
315                   printf("got SIGQUIT; canceling I/O requests: \n");
316
317                   for (size_t j = 0; j < numReqs; j++) {
318                       if (ioList[j].status == EINPROGRESS) {
319                           printf("    Request %zu on descriptor %d:", j,
320                                   ioList[j].aiocbp->aio_fildes);
321                           s = aio_cancel(ioList[j].aiocbp->aio_fildes,
322                                   ioList[j].aiocbp);
323                           if (s == AIO_CANCELED)
324                               printf("I/O canceled\n");
325                           else if (s == AIO_NOTCANCELED)
326                               printf("I/O not canceled\n");
327                           else if (s == AIO_ALLDONE)
328                               printf("I/O all done\n");
329                           else
330                               perror("aio_cancel");
331                       }
332                   }
333
334                   gotSIGQUIT = 0;
335               }
336
337               /* Check the status of each I/O request that is still
338                  in progress. */
339
340               printf("aio_error():\n");
341               for (size_t j = 0; j < numReqs; j++) {
342                   if (ioList[j].status == EINPROGRESS) {
343                       printf("    for request %zu (descriptor %d): ",
344                               j, ioList[j].aiocbp->aio_fildes);
345                       ioList[j].status = aio_error(ioList[j].aiocbp);
346
347                       switch (ioList[j].status) {
348                       case 0:
349                           printf("I/O succeeded\n");
350                           break;
351                       case EINPROGRESS:
352                           printf("In progress\n");
353                           break;
354                       case ECANCELED:
355                           printf("Canceled\n");
356                           break;
357                       default:
358                           perror("aio_error");
359                           break;
360                       }
361
362                       if (ioList[j].status != EINPROGRESS)
363                           openReqs--;
364                   }
365               }
366           }
367
368           printf("All I/O requests completed\n");
369
370           /* Check status return of all I/O requests. */
371
372           printf("aio_return():\n");
373           for (size_t j = 0; j < numReqs; j++) {
374               ssize_t s;
375
376               s = aio_return(ioList[j].aiocbp);
377               printf("    for request %zu (descriptor %d): %zd\n",
378                       j, ioList[j].aiocbp->aio_fildes, s);
379           }
380
381           exit(EXIT_SUCCESS);
382       }
383