Debian Codegraph @

upstream/debian-unstable/man2/io_getevents.2

raw
1 .\" Copyright 2003, Free Software Foundation, Inc.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-1.0-or-later
5 .\"
6 .TH io_getevents 2 2026-04-11 "Linux man-pages 6.18"
7 .SH NAME
8 io_getevents \- read asynchronous I/O events from the completion queue
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <linux/aio_abi.h>" " /* Definition of " *io_* " types */"
15 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
16 .B #include <unistd.h>
17 .P
18 .BI "int syscall(SYS_io_getevents, aio_context_t " ctx_id ,
19 .BI " long " min_nr ", long " nr ", struct io_event *" events ,
20 .BI " struct timespec *" timeout );
21 .fi
22 .SH DESCRIPTION
23 .IR Note :
24 you probably want to use the
25 .BR io_getevents (3)
26 wrapper function provided by
27 .IR libaio ;
28 see VERSIONS.
29 .P
30 The
31 .BR io_getevents ()
32 system call
33 attempts to read at least
34 .I min_nr
35 events and
36 up to
37 .I nr
38 events from the completion queue of the AIO context
39 specified by
40 .IR ctx_id .
41 .P
42 The
43 .I timeout
44 argument specifies the amount of time to wait for events,
45 and is specified as a relative timeout in a
46 .BR timespec (3)
47 structure.
48 .P
49 The specified time will be rounded up to the system clock granularity
50 and is guaranteed not to expire early.
51 .P
52 Specifying
53 .I timeout
54 as NULL means block indefinitely until at least
55 .I min_nr
56 events have been obtained.
57 .SH RETURN VALUE
58 On success,
59 .BR io_getevents ()
60 returns the number of events read.
61 This may be 0, or a value less than
62 .IR min_nr ,
63 if the
64 .I timeout
65 expired.
66 It may also be a nonzero value less than
67 .IR min_nr ,
68 if the call was interrupted by a signal handler.
69 .P
70 On error,
71 \-1 is returned,
72 and
73 .I errno
74 is set to indicate the error.
75 .SH ERRORS
76 .TP
77 .B EFAULT
78 Either
79 .I events
80 or
81 .I timeout
82 is an invalid pointer.
83 .TP
84 .B EINTR
85 Interrupted by a signal handler;
86 see
87 .BR signal (7).
88 .TP
89 .B EINVAL
90 .I ctx_id
91 is invalid.
92 .TP
93 .B EINVAL
94 .I min_nr
95 is out of range or
96 .I nr
97 is out of range.
98 .TP
99 .B ENOSYS
100 .BR io_getevents ()
101 is not implemented on this architecture.
102 .SH VERSIONS
103 .UR https://pagure.io/libaio
104 .I libaio
105 .UE
106 provides a wrapper function with the same name,
107 but different prototype and return value.
108 You probably want to use that wrapper.
109 .SH STANDARDS
110 Linux.
111 .SH HISTORY
112 Linux 2.5.
113 .SH SEE ALSO
114 .BR io_cancel (2),
115 .BR io_destroy (2),
116 .BR io_setup (2),
117 .BR io_submit (2),
118 .BR io_getevents (3),
119 .BR timespec (3),
120 .BR aio (7),
121 .BR time (7)
122 .\" .SH AUTHOR
123 .\" Kent Yoder.