Debian Codegraph @

upstream/mageia-cauldron/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 2025-09-21 "Linux man-pages 6.17"
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 .P
13 Alternatively, Asynchronous I/O library
14 .RI ( libaio ,\~ \-laio );
15 see VERSIONS.
16 .SH SYNOPSIS
17 .nf
18 .BR "#include <linux/aio_abi.h>" " /* Definition of " *io_* " types */"
19 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
20 .B #include <unistd.h>
21 .P
22 .BI "int syscall(SYS_io_getevents, aio_context_t " ctx_id ,
23 .BI " long " min_nr ", long " nr ", struct io_event *" events ,
24 .BI " struct timespec *" timeout );
25 .fi
26 .P
27 .IR Note :
28 glibc provides no wrapper for
29 .BR io_getevents (),
30 necessitating the use of
31 .BR syscall (2).
32 .SH DESCRIPTION
33 .IR Note :
34 this page describes the raw Linux system call interface.
35 The wrapper function provided by
36 .I libaio
37 uses a different type for the
38 .I ctx_id
39 argument.
40 See VERSIONS.
41 .P
42 The
43 .BR io_getevents ()
44 system call
45 attempts to read at least
46 .I min_nr
47 events and
48 up to
49 .I nr
50 events from the completion queue of the AIO context
51 specified by
52 .IR ctx_id .
53 .P
54 The
55 .I timeout
56 argument specifies the amount of time to wait for events,
57 and is specified as a relative timeout in a
58 .BR timespec (3)
59 structure.
60 .P
61 The specified time will be rounded up to the system clock granularity
62 and is guaranteed not to expire early.
63 .P
64 Specifying
65 .I timeout
66 as NULL means block indefinitely until at least
67 .I min_nr
68 events have been obtained.
69 .SH RETURN VALUE
70 On success,
71 .BR io_getevents ()
72 returns the number of events read.
73 This may be 0, or a value less than
74 .IR min_nr ,
75 if the
76 .I timeout
77 expired.
78 It may also be a nonzero value less than
79 .IR min_nr ,
80 if the call was interrupted by a signal handler.
81 .P
82 For the failure return, see VERSIONS.
83 .SH ERRORS
84 .TP
85 .B EFAULT
86 Either
87 .I events
88 or
89 .I timeout
90 is an invalid pointer.
91 .TP
92 .B EINTR
93 Interrupted by a signal handler;
94 see
95 .BR signal (7).
96 .TP
97 .B EINVAL
98 .I ctx_id
99 is invalid.
100 .I min_nr
101 is out of range or
102 .I nr
103 is out of range.
104 .TP
105 .B ENOSYS
106 .BR io_getevents ()
107 is not implemented on this architecture.
108 .SH VERSIONS
109 You probably want to use the
110 .BR io_getevents ()
111 wrapper function provided by
112 .\" http://git.fedorahosted.org/git/?p=libaio.git
113 .IR libaio .
114 .P
115 Note that the
116 .I libaio
117 wrapper function uses a different type
118 .RI ( io_context_t )
119 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
120 .\" the system call.
121 for the
122 .I ctx_id
123 argument.
124 Note also that the
125 .I libaio
126 wrapper does not follow the usual C library conventions for indicating errors:
127 on error it returns a negated error number
128 (the negative of one of the values listed in ERRORS).
129 If the system call is invoked via
130 .BR syscall (2),
131 then the return value follows the usual conventions for
132 indicating an error: \-1, with
133 .I errno
134 set to a (positive) value that indicates the error.
135 .SH STANDARDS
136 Linux.
137 .SH HISTORY
138 Linux 2.5.
139 .SH BUGS
140 An invalid
141 .I ctx_id
142 may cause a segmentation fault instead of generating the error
143 .BR EINVAL .
144 .SH SEE ALSO
145 .BR io_cancel (2),
146 .BR io_destroy (2),
147 .BR io_setup (2),
148 .BR io_submit (2),
149 .BR timespec (3),
150 .BR aio (7),
151 .BR time (7)
152 .\" .SH AUTHOR
153 .\" Kent Yoder.