Debian Codegraph @

upstream/debian-unstable/man7/aio.7

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