]>
Commit | Line | Data |
---|---|---|
8b428090 MK |
1 | .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" starting from a version by Davide Libenzi <davidel@xmailserver.org> | |
3 | .\" | |
f0008367 | 4 | .\" %%%LICENSE_START(GPLv2+_SW_3_PARA) |
8b428090 MK |
5 | .\" This program is free software; you can redistribute it and/or modify |
6 | .\" it under the terms of the GNU General Public License as published by | |
7 | .\" the Free Software Foundation; either version 2 of the License, or | |
8 | .\" (at your option) any later version. | |
9 | .\" | |
10 | .\" This program is distributed in the hope that it will be useful, | |
11 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
13 | .\" GNU General Public License for more details. | |
14 | .\" | |
68fa4398 MK |
15 | .\" You should have received a copy of the GNU General Public |
16 | .\" License along with this manual; if not, see | |
17 | .\" <http://www.gnu.org/licenses/>. | |
8ff7380d | 18 | .\" %%%LICENSE_END |
8b428090 | 19 | .\" |
c22cb204 MK |
20 | .\" 2008-10-10, mtk: describe eventfd2(), and EFD_NONBLOCK and EFD_CLOEXEC |
21 | .\" | |
4b8c67d9 | 22 | .TH EVENTFD 2 2017-09-15 Linux "Linux Programmer's Manual" |
8b428090 MK |
23 | .SH NAME |
24 | eventfd \- create a file descriptor for event notification | |
25 | .SH SYNOPSIS | |
26 | .B #include <sys/eventfd.h> | |
68e4db0a | 27 | .PP |
8b428090 MK |
28 | .BI "int eventfd(unsigned int " initval ", int " flags ); |
29 | .SH DESCRIPTION | |
30 | .BR eventfd () | |
31 | creates an "eventfd object" that can be used as | |
7fac88a9 MK |
32 | an event wait/notify mechanism by user-space applications, |
33 | and by the kernel to notify user-space applications of events. | |
8b428090 MK |
34 | The object contains an unsigned 64-bit integer |
35 | .RI ( uint64_t ) | |
36 | counter that is maintained by the kernel. | |
37 | This counter is initialized with the value specified in the argument | |
38 | .IR initval . | |
efeece04 | 39 | .PP |
0986cb57 | 40 | The following values may be bitwise ORed in |
e64b5482 | 41 | .IR flags |
a1fa36af | 42 | to change the behavior of |
e64b5482 | 43 | .BR eventfd (): |
e64b5482 | 44 | .TP |
0986cb57 | 45 | .BR EFD_CLOEXEC " (since Linux 2.6.27)" |
e64b5482 MK |
46 | Set the close-on-exec |
47 | .RB ( FD_CLOEXEC ) | |
48 | flag on the new file descriptor. | |
c5571b61 | 49 | See the description of the |
e64b5482 MK |
50 | .B O_CLOEXEC |
51 | flag in | |
52 | .BR open (2) | |
53 | for reasons why this may be useful. | |
4eb6d333 | 54 | .TP |
0986cb57 | 55 | .BR EFD_NONBLOCK " (since Linux 2.6.27)" |
4eb6d333 MK |
56 | Set the |
57 | .BR O_NONBLOCK | |
58 | file status flag on the new open file description. | |
59 | Using this flag saves extra calls to | |
60 | .BR fcntl (2) | |
61 | to achieve the same result. | |
0986cb57 MK |
62 | .TP |
63 | .BR EFD_SEMAPHORE " (since Linux 2.6.30)" | |
64 | Provide semaphore-like semantics for reads from the new file descriptor. | |
65 | See below. | |
e64b5482 MK |
66 | .PP |
67 | In Linux up to version 2.6.26, the | |
8b428090 | 68 | .I flags |
e64b5482 | 69 | argument is unused, and must be specified as zero. |
efeece04 | 70 | .PP |
8b428090 MK |
71 | As its return value, |
72 | .BR eventfd () | |
73 | returns a new file descriptor that can be used to refer to the | |
74 | eventfd object. | |
75 | The following operations can be performed on the file descriptor: | |
76 | .TP | |
77 | .BR read (2) | |
0986cb57 MK |
78 | Each successful |
79 | .BR read (2) | |
80 | returns an 8-byte integer. | |
81 | A | |
82 | .BR read (2) | |
26cd31fd | 83 | fails with the error |
0986cb57 MK |
84 | .B EINVAL |
85 | if the size of the supplied buffer is less than 8 bytes. | |
86 | .IP | |
87 | The value returned by | |
88 | .BR read (2) | |
88879aeb MK |
89 | is in host byte order\(emthat is, |
90 | the native byte order for integers on the host machine. | |
0986cb57 MK |
91 | .IP |
92 | The semantics of | |
93 | .BR read (2) | |
94 | depend on whether the eventfd counter currently has a nonzero value | |
95 | and whether the | |
96 | .BR EFD_SEMAPHORE | |
97 | flag was specified when creating the eventfd file descriptor: | |
98 | .RS | |
99 | .IP * 3 | |
100 | If | |
101 | .BR EFD_SEMAPHORE | |
102 | was not specified and the eventfd counter has a nonzero value, then a | |
8b428090 MK |
103 | .BR read (2) |
104 | returns 8 bytes containing that value, | |
105 | and the counter's value is reset to zero. | |
0986cb57 MK |
106 | .IP * |
107 | If | |
108 | .BR EFD_SEMAPHORE | |
109 | was specified and the eventfd counter has a nonzero value, then a | |
110 | .BR read (2) | |
111 | returns 8 bytes containing the value 1, | |
112 | and the counter's value is decremented by 1. | |
113 | .IP * | |
114 | If the eventfd counter is zero at the time of the call to | |
8b428090 | 115 | .BR read (2), |
0986cb57 MK |
116 | then the call either blocks until the counter becomes nonzero |
117 | (at which time, the | |
118 | .BR read (2) | |
119 | proceeds as described above) | |
8b428090 MK |
120 | or fails with the error |
121 | .B EAGAIN | |
ff40dbb3 | 122 | if the file descriptor has been made nonblocking. |
0986cb57 | 123 | .RE |
8b428090 MK |
124 | .TP |
125 | .BR write (2) | |
126 | A | |
127 | .BR write (2) | |
128 | call adds the 8-byte integer value supplied in its | |
129 | buffer to the counter. | |
130 | The maximum value that may be stored in the counter is the largest | |
131 | unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe). | |
132 | If the addition would cause the counter's value to exceed | |
133 | the maximum, then the | |
134 | .BR write (2) | |
135 | either blocks until a | |
136 | .BR read (2) | |
137 | is performed on the file descriptor, | |
138 | or fails with the error | |
139 | .B EAGAIN | |
ff40dbb3 | 140 | if the file descriptor has been made nonblocking. |
8b428090 MK |
141 | .IP |
142 | A | |
143 | .BR write (2) | |
26cd31fd | 144 | fails with the error |
8b428090 MK |
145 | .B EINVAL |
146 | if the size of the supplied buffer is less than 8 bytes, | |
147 | or if an attempt is made to write the value 0xffffffffffffffff. | |
148 | .TP | |
149 | .BR poll "(2), " select "(2) (and similar)" | |
150 | The returned file descriptor supports | |
151 | .BR poll (2) | |
152 | (and analogously | |
153 | .BR epoll (7)) | |
154 | and | |
155 | .BR select (2), | |
156 | as follows: | |
157 | .RS | |
158 | .IP * 3 | |
159 | The file descriptor is readable | |
160 | (the | |
161 | .BR select (2) | |
162 | .I readfds | |
163 | argument; the | |
164 | .BR poll (2) | |
165 | .B POLLIN | |
166 | flag) | |
167 | if the counter has a value greater than 0. | |
168 | .IP * | |
169 | The file descriptor is writable | |
170 | (the | |
171 | .BR select (2) | |
172 | .I writefds | |
173 | argument; the | |
174 | .BR poll (2) | |
175 | .B POLLOUT | |
176 | flag) | |
177 | if it is possible to write a value of at least "1" without blocking. | |
178 | .IP * | |
20e5fb78 MK |
179 | If an overflow of the counter value was detected, |
180 | then | |
8b428090 | 181 | .BR select (2) |
20e5fb78 | 182 | indicates the file descriptor as being both readable and writable, and |
8b428090 | 183 | .BR poll (2) |
20e5fb78 | 184 | returns a |
8b428090 | 185 | .B POLLERR |
20e5fb78 | 186 | event. |
8b428090 MK |
187 | As noted above, |
188 | .BR write (2) | |
189 | can never overflow the counter. | |
190 | However an overflow can occur if 2^64 | |
191 | eventfd "signal posts" were performed by the KAIO | |
192 | subsystem (theoretically possible, but practically unlikely). | |
193 | If an overflow has occurred, then | |
194 | .BR read (2) | |
195 | will return that maximum | |
196 | .I uint64_t | |
197 | value (i.e., 0xffffffffffffffff). | |
198 | .RE | |
199 | .IP | |
200 | The eventfd file descriptor also supports the other file-descriptor | |
201 | multiplexing APIs: | |
531b15bc | 202 | .BR pselect (2) |
8b428090 | 203 | and |
531b15bc | 204 | .BR ppoll (2). |
8b428090 MK |
205 | .TP |
206 | .BR close (2) | |
207 | When the file descriptor is no longer required it should be closed. | |
208 | When all file descriptors associated with the same eventfd object | |
209 | have been closed, the resources for object are freed by the kernel. | |
210 | .PP | |
211 | A copy of the file descriptor created by | |
212 | .BR eventfd () | |
213 | is inherited by the child produced by | |
214 | .BR fork (2). | |
215 | The duplicate file descriptor is associated with the same | |
216 | eventfd object. | |
217 | File descriptors created by | |
218 | .BR eventfd () | |
219 | are preserved across | |
d45105d9 AS |
220 | .BR execve (2), |
221 | unless the close-on-exec flag has been set. | |
47297adb | 222 | .SH RETURN VALUE |
8b428090 MK |
223 | On success, |
224 | .BR eventfd () | |
225 | returns a new eventfd file descriptor. | |
226 | On error, \-1 is returned and | |
227 | .I errno | |
228 | is set to indicate the error. | |
229 | .SH ERRORS | |
40725279 MK |
230 | .TP |
231 | .B EINVAL | |
0986cb57 MK |
232 | An unsupported value was specified in |
233 | .IR flags . | |
8b428090 MK |
234 | .TP |
235 | .B EMFILE | |
26c32fab | 236 | The per-process limit on the number of open file descriptors has been reached. |
8b428090 MK |
237 | .TP |
238 | .B ENFILE | |
239 | The system-wide limit on the total number of open files has been | |
240 | reached. | |
241 | .TP | |
242 | .B ENODEV | |
243 | .\" Note from Davide: | |
244 | .\" The ENODEV error is basically never going to happen if | |
245 | .\" the kernel boots correctly. That error happen only if during | |
246 | .\" the kernel initialization, some error occur in the anonymous | |
247 | .\" inode source initialization. | |
248 | Could not mount (internal) anonymous inode device. | |
249 | .TP | |
250 | .B ENOMEM | |
251 | There was insufficient memory to create a new | |
252 | eventfd file descriptor. | |
253 | .SH VERSIONS | |
254 | .BR eventfd () | |
255 | is available on Linux since kernel 2.6.22. | |
256 | Working support is provided in glibc since version 2.8. | |
257 | .\" eventfd() is in glibc 2.7, but reportedly does not build | |
e64b5482 MK |
258 | The |
259 | .BR eventfd2 () | |
260 | system call (see NOTES) is available on Linux since kernel 2.6.27. | |
66bbce00 MK |
261 | Since version 2.9, the glibc |
262 | .BR eventfd () | |
263 | wrapper will employ the | |
264 | .BR eventfd2 () | |
265 | system call, if it is supported by the kernel. | |
288c1a09 ZL |
266 | .SH ATTRIBUTES |
267 | For an explanation of the terms used in this section, see | |
268 | .BR attributes (7). | |
269 | .TS | |
270 | allbox; | |
271 | lb lb lb | |
272 | l l l. | |
273 | Interface Attribute Value | |
274 | T{ | |
275 | .BR eventfd () | |
276 | T} Thread safety MT-Safe | |
277 | .TE | |
efeece04 | 278 | .sp 1 |
8b428090 MK |
279 | .SH CONFORMING TO |
280 | .BR eventfd () | |
e64b5482 | 281 | and |
2aa3fb2d | 282 | .BR eventfd2 () |
e64b5482 | 283 | are Linux-specific. |
8b428090 MK |
284 | .SH NOTES |
285 | Applications can use an eventfd file descriptor instead of a pipe (see | |
286 | .BR pipe (2)) | |
287 | in all cases where a pipe is used simply to signal events. | |
288 | The kernel overhead of an eventfd file descriptor | |
289 | is much lower than that of a pipe, | |
290 | and only one file descriptor is | |
291 | required (versus the two required for a pipe). | |
efeece04 | 292 | .PP |
8b428090 | 293 | When used in the kernel, an eventfd |
7fac88a9 | 294 | file descriptor can provide a bridge from kernel to user space, allowing, |
8b428090 MK |
295 | for example, functionalities like KAIO (kernel AIO) |
296 | .\" or eventually syslets/threadlets | |
297 | to signal to a file descriptor that some operation is complete. | |
efeece04 | 298 | .PP |
8b428090 MK |
299 | A key point about an eventfd file descriptor is that it can be |
300 | monitored just like any other file descriptor using | |
301 | .BR select (2), | |
302 | .BR poll (2), | |
303 | or | |
304 | .BR epoll (7). | |
305 | This means that an application can simultaneously monitor the | |
306 | readiness of "traditional" files and the readiness of other | |
307 | kernel mechanisms that support the eventfd interface. | |
308 | (Without the | |
309 | .BR eventfd () | |
310 | interface, these mechanisms could not be multiplexed via | |
311 | .BR select (2), | |
312 | .BR poll (2), | |
313 | or | |
314 | .BR epoll (7).) | |
efeece04 | 315 | .PP |
9764a9ff MK |
316 | The current value of an eventfd counter can be viewed |
317 | via the entry for the corresponding file descriptor in the process's | |
318 | .IR /proc/[pid]/fdinfo | |
319 | directory. | |
320 | See | |
321 | .BR proc (5) | |
322 | for further details. | |
323 | .\" | |
0722a578 | 324 | .SS C library/kernel differences |
e64b5482 MK |
325 | There are two underlying Linux system calls: |
326 | .BR eventfd () | |
327 | and the more recent | |
328 | .BR eventfd2 (). | |
329 | The former system call does not implement a | |
330 | .I flags | |
331 | argument. | |
332 | The latter system call implements the | |
333 | .I flags | |
334 | values described above. | |
e64b5482 MK |
335 | The glibc wrapper function will use |
336 | .BR eventfd2 () | |
337 | where it is available. | |
8b428090 MK |
338 | .SS Additional glibc features |
339 | The GNU C library defines an additional type, | |
340 | and two functions that attempt to abstract some of the details of | |
341 | reading and writing on an eventfd file descriptor: | |
0ffeaeae | 342 | .PP |
8b428090 | 343 | .in +4n |
0ffeaeae | 344 | .EX |
8b428090 MK |
345 | typedef uint64_t eventfd_t; |
346 | ||
ffaecbc1 MK |
347 | int eventfd_read(int fd, eventfd_t *value); |
348 | int eventfd_write(int fd, eventfd_t value); | |
0ffeaeae | 349 | .EE |
8b428090 | 350 | .in |
efeece04 | 351 | .PP |
8b428090 MK |
352 | The functions perform the read and write operations on an |
353 | eventfd file descriptor, | |
354 | returning 0 if the correct number of bytes was transferred, | |
355 | or \-1 otherwise. | |
356 | .SH EXAMPLE | |
357 | .PP | |
358 | The following program creates an eventfd file descriptor | |
359 | and then forks to create a child process. | |
360 | While the parent briefly sleeps, | |
361 | the child writes each of the integers supplied in the program's | |
362 | command-line arguments to the eventfd file descriptor. | |
363 | When the parent has finished sleeping, | |
364 | it reads from the eventfd file descriptor. | |
efeece04 | 365 | .PP |
8b428090 | 366 | The following shell session shows a sample run of the program: |
0ffeaeae | 367 | .PP |
8b428090 | 368 | .in +4n |
0ffeaeae | 369 | .EX |
b43a3b30 | 370 | .RB "$" " ./a.out 1 2 4 7 14" |
8b428090 MK |
371 | Child writing 1 to efd |
372 | Child writing 2 to efd | |
373 | Child writing 4 to efd | |
374 | Child writing 7 to efd | |
375 | Child writing 14 to efd | |
376 | Child completed write loop | |
377 | Parent about to read | |
378 | Parent read 28 (0x1c) from efd | |
0ffeaeae | 379 | .EE |
1c32ee47 | 380 | .in |
9c330504 | 381 | .SS Program source |
d84d0300 | 382 | \& |
e7d0bb47 | 383 | .EX |
8b428090 MK |
384 | #include <sys/eventfd.h> |
385 | #include <unistd.h> | |
386 | #include <stdlib.h> | |
387 | #include <stdio.h> | |
388 | #include <stdint.h> /* Definition of uint64_t */ | |
389 | ||
390 | #define handle_error(msg) \\ | |
391 | do { perror(msg); exit(EXIT_FAILURE); } while (0) | |
392 | ||
393 | int | |
394 | main(int argc, char *argv[]) | |
395 | { | |
396 | int efd, j; | |
397 | uint64_t u; | |
398 | ssize_t s; | |
399 | ||
400 | if (argc < 2) { | |
401 | fprintf(stderr, "Usage: %s <num>...\\n", argv[0]); | |
402 | exit(EXIT_FAILURE); | |
403 | } | |
404 | ||
405 | efd = eventfd(0, 0); | |
406 | if (efd == \-1) | |
407 | handle_error("eventfd"); | |
408 | ||
409 | switch (fork()) { | |
410 | case 0: | |
411 | for (j = 1; j < argc; j++) { | |
412 | printf("Child writing %s to efd\\n", argv[j]); | |
413 | u = strtoull(argv[j], NULL, 0); | |
414 | /* strtoull() allows various bases */ | |
415 | s = write(efd, &u, sizeof(uint64_t)); | |
416 | if (s != sizeof(uint64_t)) | |
417 | handle_error("write"); | |
418 | } | |
419 | printf("Child completed write loop\\n"); | |
420 | ||
421 | exit(EXIT_SUCCESS); | |
422 | ||
423 | default: | |
424 | sleep(2); | |
425 | ||
426 | printf("Parent about to read\\n"); | |
427 | s = read(efd, &u, sizeof(uint64_t)); | |
428 | if (s != sizeof(uint64_t)) | |
429 | handle_error("read"); | |
430 | printf("Parent read %llu (0x%llx) from efd\\n", | |
431 | (unsigned long long) u, (unsigned long long) u); | |
432 | exit(EXIT_SUCCESS); | |
433 | ||
434 | case \-1: | |
435 | handle_error("fork"); | |
436 | } | |
437 | } | |
e7d0bb47 | 438 | .EE |
47297adb | 439 | .SH SEE ALSO |
8b428090 MK |
440 | .BR futex (2), |
441 | .BR pipe (2), | |
442 | .BR poll (2), | |
443 | .BR read (2), | |
444 | .BR select (2), | |
445 | .BR signalfd (2), | |
446 | .BR timerfd_create (2), | |
447 | .BR write (2), | |
448 | .BR epoll (7), | |
449 | .BR sem_overview (7) |