]>
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 | .\" |
f0008367 | 5 | .\" %%%LICENSE_START(GPLv2+_SW_3_PARA) |
fea681da MK |
6 | .\" This program is free software; you can redistribute it and/or modify |
7 | .\" it under the terms of the GNU General Public License as published by | |
8 | .\" the Free Software Foundation; either version 2 of the License, or | |
9 | .\" (at your option) any later version. | |
10 | .\" | |
11 | .\" This program is distributed in the hope that it will be useful, | |
12 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
13 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
14 | .\" GNU General Public License for more details. | |
15 | .\" | |
68fa4398 MK |
16 | .\" You should have received a copy of the GNU General Public |
17 | .\" License along with this manual; if not, see | |
18 | .\" <http://www.gnu.org/licenses/>. | |
8ff7380d | 19 | .\" %%%LICENSE_END |
fea681da | 20 | .\" |
3996edf6 | 21 | .\" 2007-04-30: mtk, Added description of epoll_pwait() |
e0614973 | 22 | .\" |
e8426ca2 | 23 | .TH EPOLL_WAIT 2 2020-04-11 "Linux" "Linux Programmer's Manual" |
fea681da | 24 | .SH NAME |
3996edf6 | 25 | epoll_wait, epoll_pwait \- wait for an I/O event on an epoll file descriptor |
fea681da | 26 | .SH SYNOPSIS |
616c0fd3 | 27 | .nf |
fea681da | 28 | .B #include <sys/epoll.h> |
68e4db0a | 29 | .PP |
c13182ef | 30 | .BI "int epoll_wait(int " epfd ", struct epoll_event *" events , |
3996edf6 | 31 | .BI " int " maxevents ", int " timeout ); |
35f0f2f9 | 32 | .BI "int epoll_pwait(int " epfd ", struct epoll_event *" events , |
988db661 | 33 | .BI " int " maxevents ", int " timeout , |
3996edf6 | 34 | .BI " const sigset_t *" sigmask ); |
616c0fd3 | 35 | .fi |
fea681da | 36 | .SH DESCRIPTION |
35f0f2f9 MK |
37 | The |
38 | .BR epoll_wait () | |
39 | system call waits for events on the | |
284976f8 | 40 | .BR epoll (7) |
8483a88c MK |
41 | instance referred to by the file descriptor |
42 | .IR epfd . | |
23a169f7 | 43 | The buffer pointed to by |
fea681da | 44 | .I events |
23a169f7 MK |
45 | is used to return information from the ready list |
46 | about file descriptors in the interest list that | |
47 | have some events available. | |
fea681da MK |
48 | Up to |
49 | .I maxevents | |
50 | are returned by | |
2777b1ca | 51 | .BR epoll_wait (). |
fea681da MK |
52 | The |
53 | .I maxevents | |
c4bb193f | 54 | argument must be greater than zero. |
94be92bf | 55 | .PP |
f07cd91a | 56 | The |
ae3faf4b | 57 | .I timeout |
3c9b77d5 | 58 | argument specifies the number of milliseconds that |
f07cd91a MK |
59 | .BR epoll_wait () |
60 | will block. | |
c1a2cf47 MC |
61 | Time is measured against the |
62 | .B CLOCK_MONOTONIC | |
63 | clock. | |
23a169f7 MK |
64 | .PP |
65 | A call to | |
66 | .BR epoll_wait () | |
67 | will block until either: | |
68 | .IP \(bu 2 | |
40df3d00 | 69 | a file descriptor delivers an event; |
23a169f7 | 70 | .IP \(bu |
40df3d00 | 71 | the call is interrupted by a signal handler; or |
23a169f7 | 72 | .IP \(bu |
af8ad761 | 73 | the timeout expires. |
40df3d00 MK |
74 | .PP |
75 | Note that the | |
76 | .I timeout | |
77 | interval will be rounded up to the system clock granularity, | |
f07cd91a | 78 | and kernel scheduling delays mean that the blocking interval |
40df3d00 | 79 | may overrun by a small amount. |
c13182ef | 80 | Specifying a |
fea681da | 81 | .I timeout |
70a6338b | 82 | of \-1 causes |
2777b1ca | 83 | .BR epoll_wait () |
70a6338b | 84 | to block indefinitely, while specifying a |
fea681da | 85 | .I timeout |
70a6338b | 86 | equal to zero cause |
2777b1ca | 87 | .BR epoll_wait () |
70a6338b | 88 | to return immediately, even if no events are available. |
94be92bf | 89 | .PP |
fea681da | 90 | The |
8478ee02 | 91 | .I struct epoll_event |
e4dd2d93 | 92 | is defined as: |
0ffeaeae | 93 | .PP |
a08ea57c | 94 | .in +4n |
0ffeaeae | 95 | .EX |
cf0a9ace | 96 | typedef union epoll_data { |
a08ea57c MK |
97 | void *ptr; |
98 | int fd; | |
99 | uint32_t u32; | |
100 | uint64_t u64; | |
cf0a9ace | 101 | } epoll_data_t; |
fea681da | 102 | |
cf0a9ace | 103 | struct epoll_event { |
a08ea57c | 104 | uint32_t events; /* Epoll events */ |
cf0a9ace MK |
105 | epoll_data_t data; /* User data variable */ |
106 | }; | |
0ffeaeae | 107 | .EE |
a08ea57c | 108 | .in |
efeece04 | 109 | .PP |
fea681da MK |
110 | The |
111 | .I data | |
23a169f7 MK |
112 | field of each returned |
113 | .I epoll_event | |
114 | structure contains the same data as was specified | |
991c24c8 | 115 | in the most recent call to |
fea681da | 116 | .BR epoll_ctl (2) |
991c24c8 | 117 | .RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD ) |
23a169f7 MK |
118 | for the corresponding open file descriptor. |
119 | .PP | |
1b564a4b | 120 | The |
fea681da | 121 | .I events |
23a169f7 MK |
122 | field is a bit mask that indicates the events that have occurred for the |
123 | corresponding open file description. | |
124 | See | |
125 | .BR epoll_ctl (2) | |
126 | for a list of the bits that may appear in this mask. | |
127 | .\" | |
3996edf6 MK |
128 | .SS epoll_pwait() |
129 | The relationship between | |
130 | .BR epoll_wait () | |
131 | and | |
132 | .BR epoll_pwait () | |
133 | is analogous to the relationship between | |
0bfa087b | 134 | .BR select (2) |
3996edf6 | 135 | and |
0bfa087b | 136 | .BR pselect (2): |
3996edf6 | 137 | like |
0bfa087b | 138 | .BR pselect (2), |
3996edf6 MK |
139 | .BR epoll_pwait () |
140 | allows an application to safely wait until either a file descriptor | |
141 | becomes ready or until a signal is caught. | |
94be92bf | 142 | .PP |
3996edf6 MK |
143 | The following |
144 | .BR epoll_pwait () | |
145 | call: | |
47f743f1 MK |
146 | .PP |
147 | .in +4n | |
148 | .EX | |
149 | ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask); | |
150 | .EE | |
151 | .in | |
152 | .PP | |
3996edf6 MK |
153 | is equivalent to |
154 | .I atomically | |
155 | executing the following calls: | |
47f743f1 MK |
156 | .PP |
157 | .in +4n | |
158 | .EX | |
159 | sigset_t origmask; | |
3996edf6 | 160 | |
47f743f1 MK |
161 | pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); |
162 | ready = epoll_wait(epfd, &events, maxevents, timeout); | |
163 | pthread_sigmask(SIG_SETMASK, &origmask, NULL); | |
164 | .EE | |
165 | .in | |
c98759f3 MK |
166 | .PP |
167 | The | |
168 | .I sigmask | |
169 | argument may be specified as NULL, in which case | |
170 | .BR epoll_pwait () | |
171 | is equivalent to | |
172 | .BR epoll_wait (). | |
47297adb | 173 | .SH RETURN VALUE |
c13182ef | 174 | When successful, |
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 MK |
179 | milliseconds. |
180 | When an error occurs, | |
2777b1ca | 181 | .BR epoll_wait () |
fea681da MK |
182 | returns \-1 and |
183 | .I errno | |
184 | is set appropriately. | |
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. |
a1d5f77c | 210 | .SH VERSIONS |
cb22cfb4 MK |
211 | .BR epoll_wait () |
212 | was added to the kernel in version 2.6. | |
213 | .\" To be precise: kernel 2.5.44. | |
214 | .\" The interface should be finalized by Linux kernel 2.5.66. | |
215 | Library support is provided in glibc starting with version 2.3.2. | |
94be92bf | 216 | .PP |
a1d5f77c | 217 | .BR epoll_pwait () |
cb22cfb4 MK |
218 | was added to Linux in kernel 2.6.19. |
219 | Library support is provided in glibc starting with version 2.6. | |
fea681da | 220 | .SH CONFORMING TO |
2777b1ca | 221 | .BR epoll_wait () |
cb22cfb4 | 222 | is Linux-specific. |
7396b79c MK |
223 | .SH NOTES |
224 | While one thread is blocked in a call to | |
49853640 | 225 | .BR epoll_wait (), |
7396b79c MK |
226 | it is possible for another thread to add a file descriptor to the waited-upon |
227 | .B epoll | |
228 | instance. | |
229 | If the new file descriptor becomes ready, | |
230 | it will cause the | |
231 | .BR epoll_wait () | |
232 | call to unblock. | |
94be92bf | 233 | .PP |
fc9294cb MK |
234 | If more than |
235 | .I maxevents | |
236 | file descriptors are ready when | |
237 | .BR epoll_wait () | |
238 | is called, then successive | |
239 | .BR epoll_wait () | |
240 | calls will round robin through the set of ready file descriptors. | |
241 | This behavior helps avoid starvation scenarios, | |
242 | where a process fails to notice that additional file descriptors | |
243 | are ready because it focuses on a set of file descriptors that | |
244 | are already known to be ready. | |
245 | .PP | |
e3a60d1c | 246 | Note that it is possible to call |
67378c48 | 247 | .BR epoll_wait () |
e3a60d1c MK |
248 | on an |
249 | .B epoll | |
250 | instance whose interest list is currently empty | |
251 | (or whose interest list becomes empty because file descriptors are closed | |
252 | or removed from the interest in another thread). | |
253 | The call will block until some file descriptor is later added to the | |
254 | interest list (in another thread) and that file descriptor becomes ready. | |
355f61b5 MK |
255 | .SH BUGS |
256 | In kernels before 2.6.37, a | |
257 | .I timeout | |
258 | value larger than approximately | |
259 | .I LONG_MAX / HZ | |
260 | milliseconds is treated as \-1 (i.e., infinity). | |
11f57f44 | 261 | Thus, for example, on a system where |
355f61b5 MK |
262 | .I sizeof(long) |
263 | is 4 and the kernel | |
264 | .I HZ | |
265 | value is 1000, | |
266 | this means that timeouts greater than 35.79 minutes are treated as infinity. | |
0722a578 | 267 | .SS C library/kernel differences |
81428c3a MK |
268 | The raw |
269 | .BR epoll_pwait () | |
270 | system call has a sixth argument, | |
271 | .IR "size_t sigsetsize" , | |
272 | which specifies the size in bytes of the | |
273 | .IR sigmask | |
274 | argument. | |
275 | The glibc | |
276 | .BR epoll_pwait () | |
277 | wrapper function specifies this argument as a fixed value | |
278 | (equal to | |
279 | .IR sizeof(sigset_t) ). | |
47297adb | 280 | .SH SEE ALSO |
fea681da MK |
281 | .BR epoll_create (2), |
282 | .BR epoll_ctl (2), | |
2315114c | 283 | .BR epoll (7) |