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