| blob | eca1ae3fad5f0893f485cff6c6151ad8cf9f0d7c |
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-\[rs]) 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\[rs]n", 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>...\[rs]n",
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\[rs]n", 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: \[rs]n");
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\[rs]n");
367 else if (s == AIO_NOTCANCELED)
368 printf("I/O not canceled\[rs]n");
369 else if (s == AIO_ALLDONE)
370 printf("I/O all done\[rs]n");
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():\[rs]n");
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\[rs]n");
392 break;
393 case EINPROGRESS:
394 printf("In progress\[rs]n");
395 break;
396 case ECANCELED:
397 printf("Canceled\[rs]n");
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\[rs]n");
411 \&
412 /* Check status return of all I/O requests. */
413 \&
414 printf("aio_return():\[rs]n");
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\[rs]n",
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