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