Debian Codegraph @

upstream/debian-unstable/man2/epoll_wait.2

raw
1 .\" Copyright 2003, Davide Libenzi <[email protected]>
2 .\" Copyright 2007-2018, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH epoll_wait 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 epoll_wait, epoll_pwait, epoll_pwait2 \-
10 wait for an I/O event on an epoll file descriptor
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <sys/epoll.h>
17 .P
18 .BR "int epoll_wait(" "int n;"
19 .BI " int " epfd ", struct epoll_event " events [ n "], int " n ,
20 .BI " int " timeout );
21 .BR "int epoll_pwait(" "int n;"
22 .BI " int " epfd ", struct epoll_event " events [ n "], int " n ,
23 .BI " int " timeout ,
24 .BI " const sigset_t *_Nullable " sigmask );
25 .BR "int epoll_pwait2(" "int n;"
26 .BI " int " epfd ", struct epoll_event " events [ n "], int " n ,
27 .BI " const struct timespec *_Nullable " timeout ,
28 .BI " const sigset_t *_Nullable " sigmask );
29 .fi
30 .SH DESCRIPTION
31 The
32 .BR epoll_wait ()
33 system call waits for events on the
34 .BR epoll (7)
35 instance referred to by the file descriptor
36 .IR epfd .
37 The buffer pointed to by
38 .I events
39 is used to return information from the ready list
40 about file descriptors in the interest list that
41 have some events available.
42 Up to
43 .I n
44 are returned by
45 .BR epoll_wait ().
46 The
47 .I n
48 argument must be greater than zero.
49 .P
50 The
51 .I timeout
52 argument specifies the number of milliseconds that
53 .BR epoll_wait ()
54 will block.
55 Time is measured against the
56 .B CLOCK_MONOTONIC
57 clock.
58 .P
59 A call to
60 .BR epoll_wait ()
61 will block until either:
62 .IP \[bu] 3
63 a file descriptor delivers an event;
64 .IP \[bu]
65 the call is interrupted by a signal handler;
66 or
67 .IP \[bu]
68 the timeout expires.
69 .P
70 Note that the
71 .I timeout
72 interval will be rounded up to the system clock granularity,
73 and kernel scheduling delays mean that the blocking interval
74 may overrun by a small amount.
75 Specifying a
76 .I timeout
77 of \-1 causes
78 .BR epoll_wait ()
79 to block indefinitely, while specifying a
80 .I timeout
81 equal to zero causes
82 .BR epoll_wait ()
83 to return immediately, even if no events are available.
84 .P
85 The
86 .I struct epoll_event
87 is described in
88 .BR epoll_event (3type).
89 .P
90 The
91 .I data
92 field of each returned
93 .I epoll_event
94 structure contains the same data as was specified
95 in the most recent call to
96 .BR epoll_ctl (2)
97 .RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD )
98 for the corresponding open file descriptor.
99 .P
100 The
101 .I events
102 field is a bit mask that indicates the events that have occurred for the
103 corresponding open file description.
104 See
105 .BR epoll_ctl (2)
106 for a list of the bits that may appear in this mask.
107 .\"
108 .SS epoll_pwait()
109 The relationship between
110 .BR epoll_wait ()
111 and
112 .BR epoll_pwait ()
113 is analogous to the relationship between
114 .BR select (2)
115 and
116 .BR pselect (2):
117 like
118 .BR pselect (2),
119 .BR epoll_pwait ()
120 allows an application to safely wait until either a file descriptor
121 becomes ready or until a signal is caught.
122 .P
123 The following
124 .BR epoll_pwait ()
125 call:
126 .P
127 .in +4n
128 .EX
129 ready = epoll_pwait(epfd, &events, n, timeout, &sigmask);
130 .EE
131 .in
132 .P
133 is equivalent to
134 .I atomically
135 executing the following calls:
136 .P
137 .in +4n
138 .EX
139 sigset_t origmask;
140 \&
141 pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
142 ready = epoll_wait(epfd, &events, n, timeout);
143 pthread_sigmask(SIG_SETMASK, &origmask, NULL);
144 .EE
145 .in
146 .P
147 The
148 .I sigmask
149 argument may be specified as NULL, in which case
150 .BR epoll_pwait ()
151 is equivalent to
152 .BR epoll_wait ().
153 .\"
154 .SS epoll_pwait2()
155 The
156 .BR epoll_pwait2 ()
157 system call is equivalent to
158 .BR epoll_pwait ()
159 except for the
160 .I timeout
161 argument.
162 It takes an argument of type
163 .I timespec
164 to be able to specify nanosecond resolution timeout.
165 This argument functions the same as in
166 .BR pselect (2)
167 and
168 .BR ppoll (2).
169 If
170 .I timeout
171 is NULL, then
172 .BR epoll_pwait2 ()
173 can block indefinitely.
174 .SH RETURN VALUE
175 On success,
176 .BR epoll_wait ()
177 returns the number of file descriptors ready for the requested I/O operation,
178 or zero if no file descriptor became ready during the requested
179 .I timeout
180 milliseconds.
181 On failure,
182 .BR epoll_wait ()
183 returns \-1 and
184 .I errno
185 is set to indicate the error.
186 .SH ERRORS
187 .TP
188 .B EBADF
189 .I epfd
190 is not a valid file descriptor.
191 .TP
192 .B EFAULT
193 The memory area pointed to by
194 .I events
195 is not accessible with write permissions.
196 .TP
197 .B EINTR
198 The call was interrupted by a signal handler before either (1) any of the
199 requested events occurred or (2) the
200 .I timeout
201 expired;
202 see
203 .BR signal (7).
204 .TP
205 .B EINVAL
206 .I epfd
207 is not an
208 .B epoll
209 file descriptor, or
210 .I n
211 is less than or equal to zero.
212 .SH STANDARDS
213 Linux.
214 .SH HISTORY
215 .TP
216 .BR epoll_wait ()
217 Linux 2.6,
218 .\" To be precise: Linux 2.5.44.
219 .\" The interface should be finalized by Linux 2.5.66.
220 glibc 2.3.2.
221 .TP
222 .BR epoll_pwait ()
223 Linux 2.6.19,
224 glibc 2.6.
225 .TP
226 .BR epoll_pwait2 ()
227 Linux 5.11.
228 .SH NOTES
229 While one thread is blocked in a call to
230 .BR epoll_wait (),
231 it is possible for another thread to add a file descriptor to the waited-upon
232 .B epoll
233 instance.
234 If the new file descriptor becomes ready,
235 it will cause the
236 .BR epoll_wait ()
237 call to unblock.
238 .P
239 If more than
240 .I n
241 file descriptors are ready when
242 .BR epoll_wait ()
243 is called, then successive
244 .BR epoll_wait ()
245 calls will round robin through the set of ready file descriptors.
246 This behavior helps avoid starvation scenarios,
247 where a process fails to notice that additional file descriptors
248 are ready because it focuses on a set of file descriptors that
249 are already known to be ready.
250 .P
251 Note that it is possible to call
252 .BR epoll_wait ()
253 on an
254 .B epoll
255 instance whose interest list is currently empty
256 (or whose interest list becomes empty because file descriptors are closed
257 or removed from the interest in another thread).
258 The call will block until some file descriptor is later added to the
259 interest list (in another thread) and that file descriptor becomes ready.
260 .SS C library/kernel differences
261 The raw
262 .BR epoll_pwait ()
263 and
264 .BR epoll_pwait2 ()
265 system calls have a sixth argument,
266 .IR "size_t sigsetsize" ,
267 which specifies the size in bytes of the
268 .I sigmask
269 argument.
270 The glibc
271 .BR epoll_pwait ()
272 wrapper function specifies this argument as a fixed value
273 (equal to
274 .IR sizeof(sigset_t) ).
275 .SH BUGS
276 Before Linux 2.6.37, a
277 .I timeout
278 value larger than approximately
279 .I LONG_MAX / HZ
280 milliseconds is treated as \-1 (i.e., infinity).
281 Thus, for example, on a system where
282 .I sizeof(long)
283 is 4 and the kernel
284 .I HZ
285 value is 1000,
286 this means that timeouts greater than 35.79 minutes are treated as infinity.
287 .SH SEE ALSO
288 .BR epoll_create (2),
289 .BR epoll_ctl (2),
290 .BR epoll (7)