]>
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> |
68e4db0a | 19 | .PP |
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 , |
3996edf6 | 24 | .BI " const sigset_t *" sigmask ); |
ba47eb5e | 25 | .BI "int epoll_pwait2(int " epfd ", struct epoll_event *" events , |
5efa68d5 MK |
26 | .BI " int " maxevents ", const struct timespec *" timeout , |
27 | .BI " const sigset_t *" sigmask ); | |
616c0fd3 | 28 | .fi |
fea681da | 29 | .SH DESCRIPTION |
35f0f2f9 MK |
30 | The |
31 | .BR epoll_wait () | |
32 | system call waits for events on the | |
284976f8 | 33 | .BR epoll (7) |
8483a88c MK |
34 | instance referred to by the file descriptor |
35 | .IR epfd . | |
23a169f7 | 36 | The buffer pointed to by |
fea681da | 37 | .I events |
23a169f7 MK |
38 | is used to return information from the ready list |
39 | about file descriptors in the interest list that | |
40 | have some events available. | |
fea681da MK |
41 | Up to |
42 | .I maxevents | |
43 | are returned by | |
2777b1ca | 44 | .BR epoll_wait (). |
fea681da MK |
45 | The |
46 | .I maxevents | |
c4bb193f | 47 | argument must be greater than zero. |
94be92bf | 48 | .PP |
f07cd91a | 49 | The |
ae3faf4b | 50 | .I timeout |
3c9b77d5 | 51 | argument specifies the number of milliseconds that |
f07cd91a MK |
52 | .BR epoll_wait () |
53 | will block. | |
c1a2cf47 MC |
54 | Time is measured against the |
55 | .B CLOCK_MONOTONIC | |
56 | clock. | |
23a169f7 MK |
57 | .PP |
58 | A call to | |
59 | .BR epoll_wait () | |
60 | will block until either: | |
22356d97 | 61 | .IP \(bu 3 |
40df3d00 | 62 | a file descriptor delivers an event; |
23a169f7 | 63 | .IP \(bu |
40df3d00 | 64 | the call is interrupted by a signal handler; or |
23a169f7 | 65 | .IP \(bu |
af8ad761 | 66 | the timeout expires. |
40df3d00 MK |
67 | .PP |
68 | Note that the | |
69 | .I timeout | |
70 | interval will be rounded up to the system clock granularity, | |
f07cd91a | 71 | and kernel scheduling delays mean that the blocking interval |
40df3d00 | 72 | may overrun by a small amount. |
c13182ef | 73 | Specifying a |
fea681da | 74 | .I timeout |
70a6338b | 75 | of \-1 causes |
2777b1ca | 76 | .BR epoll_wait () |
70a6338b | 77 | to block indefinitely, while specifying a |
fea681da | 78 | .I timeout |
70a6338b | 79 | equal to zero cause |
2777b1ca | 80 | .BR epoll_wait () |
70a6338b | 81 | to return immediately, even if no events are available. |
94be92bf | 82 | .PP |
fea681da | 83 | The |
8478ee02 | 84 | .I struct epoll_event |
4ecb3859 AC |
85 | is described in |
86 | .BR epoll_event (3type). | |
efeece04 | 87 | .PP |
fea681da MK |
88 | The |
89 | .I data | |
23a169f7 MK |
90 | field of each returned |
91 | .I epoll_event | |
92 | structure contains the same data as was specified | |
991c24c8 | 93 | in the most recent call to |
fea681da | 94 | .BR epoll_ctl (2) |
991c24c8 | 95 | .RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD ) |
23a169f7 MK |
96 | for the corresponding open file descriptor. |
97 | .PP | |
1b564a4b | 98 | The |
fea681da | 99 | .I events |
23a169f7 MK |
100 | field is a bit mask that indicates the events that have occurred for the |
101 | corresponding open file description. | |
102 | See | |
103 | .BR epoll_ctl (2) | |
104 | for a list of the bits that may appear in this mask. | |
105 | .\" | |
3996edf6 MK |
106 | .SS epoll_pwait() |
107 | The relationship between | |
108 | .BR epoll_wait () | |
109 | and | |
110 | .BR epoll_pwait () | |
111 | is analogous to the relationship between | |
0bfa087b | 112 | .BR select (2) |
3996edf6 | 113 | and |
0bfa087b | 114 | .BR pselect (2): |
3996edf6 | 115 | like |
0bfa087b | 116 | .BR pselect (2), |
3996edf6 MK |
117 | .BR epoll_pwait () |
118 | allows an application to safely wait until either a file descriptor | |
119 | becomes ready or until a signal is caught. | |
94be92bf | 120 | .PP |
3996edf6 MK |
121 | The following |
122 | .BR epoll_pwait () | |
123 | call: | |
47f743f1 MK |
124 | .PP |
125 | .in +4n | |
126 | .EX | |
127 | ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask); | |
128 | .EE | |
129 | .in | |
130 | .PP | |
3996edf6 MK |
131 | is equivalent to |
132 | .I atomically | |
133 | executing the following calls: | |
47f743f1 MK |
134 | .PP |
135 | .in +4n | |
136 | .EX | |
137 | sigset_t origmask; | |
3996edf6 | 138 | |
47f743f1 MK |
139 | pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); |
140 | ready = epoll_wait(epfd, &events, maxevents, timeout); | |
141 | pthread_sigmask(SIG_SETMASK, &origmask, NULL); | |
142 | .EE | |
143 | .in | |
c98759f3 MK |
144 | .PP |
145 | The | |
146 | .I sigmask | |
147 | argument may be specified as NULL, in which case | |
148 | .BR epoll_pwait () | |
149 | is equivalent to | |
150 | .BR epoll_wait (). | |
5efa68d5 MK |
151 | .\" |
152 | .SS epoll_pwait2() | |
ba47eb5e WB |
153 | The |
154 | .BR epoll_pwait2 () | |
155 | system call is equivalent to | |
156 | .BR epoll_pwait () | |
157 | except for the | |
158 | .I timeout | |
5efa68d5 MK |
159 | argument. |
160 | It takes an argument of type | |
ba47eb5e | 161 | .I timespec |
5efa68d5 MK |
162 | to be able to specify nanosecond resolution timeout. |
163 | This argument functions the same as in | |
ba47eb5e WB |
164 | .BR pselect (2) |
165 | and | |
166 | .BR ppoll (2). | |
167 | If | |
168 | .I timeout | |
169 | is NULL, then | |
170 | .BR epoll_pwait2 () | |
171 | can block indefinitely. | |
47297adb | 172 | .SH RETURN VALUE |
2ae5c63a | 173 | On success, |
2777b1ca | 174 | .BR epoll_wait () |
fea681da MK |
175 | returns the number of file descriptors ready for the requested I/O, or zero |
176 | if no file descriptor became ready during the requested | |
177 | .I timeout | |
c13182ef | 178 | milliseconds. |
2ae5c63a | 179 | On failure, |
2777b1ca | 180 | .BR epoll_wait () |
fea681da MK |
181 | returns \-1 and |
182 | .I errno | |
f6a4078b | 183 | is set to indicate the error. |
fea681da MK |
184 | .SH ERRORS |
185 | .TP | |
186 | .B EBADF | |
187 | .I epfd | |
188 | is not a valid file descriptor. | |
189 | .TP | |
190 | .B EFAULT | |
191 | The memory area pointed to by | |
192 | .I events | |
193 | is not accessible with write permissions. | |
194 | .TP | |
c5a2d222 | 195 | .B EINTR |
db6f9ec8 MK |
196 | The call was interrupted by a signal handler before either (1) any of the |
197 | requested events occurred or (2) the | |
c5a2d222 | 198 | .I timeout |
01538d0d MK |
199 | expired; see |
200 | .BR signal (7). | |
c5a2d222 | 201 | .TP |
fea681da | 202 | .B EINVAL |
0daa9e92 | 203 | .I epfd |
fea681da MK |
204 | is not an |
205 | .B epoll | |
3d9a2200 | 206 | file descriptor, or |
fea681da | 207 | .I maxevents |
3d9a2200 | 208 | is less than or equal to zero. |
a1d5f77c | 209 | .SH VERSIONS |
cb22cfb4 MK |
210 | .BR epoll_wait () |
211 | was added to the kernel in version 2.6. | |
212 | .\" To be precise: kernel 2.5.44. | |
213 | .\" The interface should be finalized by Linux kernel 2.5.66. | |
214 | Library support is provided in glibc starting with version 2.3.2. | |
94be92bf | 215 | .PP |
a1d5f77c | 216 | .BR epoll_pwait () |
cb22cfb4 MK |
217 | was added to Linux in kernel 2.6.19. |
218 | Library support is provided in glibc starting with version 2.6. | |
ba47eb5e WB |
219 | .PP |
220 | .BR epoll_pwait2 () | |
221 | was added to Linux in kernel 5.11. | |
3113c7f3 | 222 | .SH STANDARDS |
1e6910c9 DL |
223 | .BR epoll_wait (), |
224 | .BR epoll_pwait (), | |
f7f02d0f | 225 | and |
1e6910c9 | 226 | .BR epoll_pwait2 () |
f7f02d0f | 227 | are Linux-specific. |
7396b79c MK |
228 | .SH NOTES |
229 | While one thread is blocked in a call to | |
49853640 | 230 | .BR epoll_wait (), |
7396b79c MK |
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. | |
94be92bf | 238 | .PP |
fc9294cb MK |
239 | If more than |
240 | .I maxevents | |
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 | .PP | |
e3a60d1c | 251 | Note that it is possible to call |
67378c48 | 252 | .BR epoll_wait () |
e3a60d1c MK |
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. | |
0722a578 | 260 | .SS C library/kernel differences |
81428c3a MK |
261 | The raw |
262 | .BR epoll_pwait () | |
ba47eb5e WB |
263 | and |
264 | .BR epoll_pwait2 () | |
265 | system calls have a sixth argument, | |
81428c3a MK |
266 | .IR "size_t sigsetsize" , |
267 | which specifies the size in bytes of the | |
1ae6b2c7 | 268 | .I sigmask |
81428c3a MK |
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) ). | |
099b33fb AC |
275 | .SH BUGS |
276 | In kernels before 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. | |
47297adb | 287 | .SH SEE ALSO |
fea681da MK |
288 | .BR epoll_create (2), |
289 | .BR epoll_ctl (2), | |
2315114c | 290 | .BR epoll (7) |