1 .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
2 .\" starting from a version by Davide Libenzi <davidel@xmailserver.org>
4 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
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.
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.
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/>.
20 .\" 2008-10-10, mtk: describe eventfd2(), and EFD_NONBLOCK and EFD_CLOEXEC
22 .TH EVENTFD 2 2019-03-06 Linux "Linux Programmer's Manual"
24 eventfd \- create a file descriptor for event notification
26 .B #include <sys/eventfd.h>
28 .BI "int eventfd(unsigned int " initval ", int " flags );
31 creates an "eventfd object" that can be used as
32 an event wait/notify mechanism by user-space applications,
33 and by the kernel to notify user-space applications of events.
34 The object contains an unsigned 64-bit integer
36 counter that is maintained by the kernel.
37 This counter is initialized with the value specified in the argument
42 returns a new file descriptor that can be used to refer to the
45 The following values may be bitwise ORed in
47 to change the behavior of
50 .BR EFD_CLOEXEC " (since Linux 2.6.27)"
53 flag on the new file descriptor.
54 See the description of the
58 for reasons why this may be useful.
60 .BR EFD_NONBLOCK " (since Linux 2.6.27)"
63 file status flag on the open file description (see
65 referred to by the new file descriptor.
66 Using this flag saves extra calls to
68 to achieve the same result.
70 .BR EFD_SEMAPHORE " (since Linux 2.6.30)"
71 Provide semaphore-like semantics for reads from the new file descriptor.
74 In Linux up to version 2.6.26, the
76 argument is unused, and must be specified as zero.
78 The following operations can be performed on the file descriptor returned by
84 returns an 8-byte integer.
89 if the size of the supplied buffer is less than 8 bytes.
93 is in host byte order\(emthat is,
94 the native byte order for integers on the host machine.
98 depend on whether the eventfd counter currently has a nonzero value
101 flag was specified when creating the eventfd file descriptor:
106 was not specified and the eventfd counter has a nonzero value, then a
108 returns 8 bytes containing that value,
109 and the counter's value is reset to zero.
113 was specified and the eventfd counter has a nonzero value, then a
115 returns 8 bytes containing the value 1,
116 and the counter's value is decremented by 1.
118 If the eventfd counter is zero at the time of the call to
120 then the call either blocks until the counter becomes nonzero
123 proceeds as described above)
124 or fails with the error
126 if the file descriptor has been made nonblocking.
132 call adds the 8-byte integer value supplied in its
133 buffer to the counter.
134 The maximum value that may be stored in the counter is the largest
135 unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe).
136 If the addition would cause the counter's value to exceed
137 the maximum, then the
139 either blocks until a
141 is performed on the file descriptor,
142 or fails with the error
144 if the file descriptor has been made nonblocking.
150 if the size of the supplied buffer is less than 8 bytes,
151 or if an attempt is made to write the value 0xffffffffffffffff.
153 .BR poll "(2), " select "(2) (and similar)"
154 The returned file descriptor supports
163 The file descriptor is readable
171 if the counter has a value greater than 0.
173 The file descriptor is writable
181 if it is possible to write a value of at least "1" without blocking.
183 If an overflow of the counter value was detected,
186 indicates the file descriptor as being both readable and writable, and
193 can never overflow the counter.
194 However an overflow can occur if 2^64
195 eventfd "signal posts" were performed by the KAIO
196 subsystem (theoretically possible, but practically unlikely).
197 If an overflow has occurred, then
199 will return that maximum
201 value (i.e., 0xffffffffffffffff).
204 The eventfd file descriptor also supports the other file-descriptor
211 When the file descriptor is no longer required it should be closed.
212 When all file descriptors associated with the same eventfd object
213 have been closed, the resources for object are freed by the kernel.
215 A copy of the file descriptor created by
217 is inherited by the child produced by
219 The duplicate file descriptor is associated with the same
221 File descriptors created by
225 unless the close-on-exec flag has been set.
229 returns a new eventfd file descriptor.
230 On error, \-1 is returned and
232 is set to indicate the error.
236 An unsupported value was specified in
240 The per-process limit on the number of open file descriptors has been reached.
243 The system-wide limit on the total number of open files has been
247 .\" Note from Davide:
248 .\" The ENODEV error is basically never going to happen if
249 .\" the kernel boots correctly. That error happen only if during
250 .\" the kernel initialization, some error occur in the anonymous
251 .\" inode source initialization.
252 Could not mount (internal) anonymous inode device.
255 There was insufficient memory to create a new
256 eventfd file descriptor.
259 is available on Linux since kernel 2.6.22.
260 Working support is provided in glibc since version 2.8.
261 .\" eventfd() is in glibc 2.7, but reportedly does not build
264 system call (see NOTES) is available on Linux since kernel 2.6.27.
265 Since version 2.9, the glibc
267 wrapper will employ the
269 system call, if it is supported by the kernel.
271 For an explanation of the terms used in this section, see
277 Interface Attribute Value
280 T} Thread safety MT-Safe
289 Applications can use an eventfd file descriptor instead of a pipe (see
291 in all cases where a pipe is used simply to signal events.
292 The kernel overhead of an eventfd file descriptor
293 is much lower than that of a pipe,
294 and only one file descriptor is
295 required (versus the two required for a pipe).
297 When used in the kernel, an eventfd
298 file descriptor can provide a bridge from kernel to user space, allowing,
299 for example, functionalities like KAIO (kernel AIO)
300 .\" or eventually syslets/threadlets
301 to signal to a file descriptor that some operation is complete.
303 A key point about an eventfd file descriptor is that it can be
304 monitored just like any other file descriptor using
309 This means that an application can simultaneously monitor the
310 readiness of "traditional" files and the readiness of other
311 kernel mechanisms that support the eventfd interface.
314 interface, these mechanisms could not be multiplexed via
320 The current value of an eventfd counter can be viewed
321 via the entry for the corresponding file descriptor in the process's
322 .IR /proc/[pid]/fdinfo
328 .SS C library/kernel differences
329 There are two underlying Linux system calls:
333 The former system call does not implement a
336 The latter system call implements the
338 values described above.
339 The glibc wrapper function will use
341 where it is available.
342 .SS Additional glibc features
343 The GNU C library defines an additional type,
344 and two functions that attempt to abstract some of the details of
345 reading and writing on an eventfd file descriptor:
349 typedef uint64_t eventfd_t;
351 int eventfd_read(int fd, eventfd_t *value);
352 int eventfd_write(int fd, eventfd_t value);
356 The functions perform the read and write operations on an
357 eventfd file descriptor,
358 returning 0 if the correct number of bytes was transferred,
362 The following program creates an eventfd file descriptor
363 and then forks to create a child process.
364 While the parent briefly sleeps,
365 the child writes each of the integers supplied in the program's
366 command-line arguments to the eventfd file descriptor.
367 When the parent has finished sleeping,
368 it reads from the eventfd file descriptor.
370 The following shell session shows a sample run of the program:
374 .RB "$" " ./a.out 1 2 4 7 14"
375 Child writing 1 to efd
376 Child writing 2 to efd
377 Child writing 4 to efd
378 Child writing 7 to efd
379 Child writing 14 to efd
380 Child completed write loop
382 Parent read 28 (0x1c) from efd
388 #include <sys/eventfd.h>
392 #include <stdint.h> /* Definition of uint64_t */
394 #define handle_error(msg) \e
395 do { perror(msg); exit(EXIT_FAILURE); } while (0)
398 main(int argc, char *argv[])
405 fprintf(stderr, "Usage: %s <num>...\en", argv[0]);
411 handle_error("eventfd");
415 for (j = 1; j < argc; j++) {
416 printf("Child writing %s to efd\en", argv[j]);
417 u = strtoull(argv[j], NULL, 0);
418 /* strtoull() allows various bases */
419 s = write(efd, &u, sizeof(uint64_t));
420 if (s != sizeof(uint64_t))
421 handle_error("write");
423 printf("Child completed write loop\en");
430 printf("Parent about to read\en");
431 s = read(efd, &u, sizeof(uint64_t));
432 if (s != sizeof(uint64_t))
433 handle_error("read");
434 printf("Parent read %llu (0x%llx) from efd\en",
435 (unsigned long long) u, (unsigned long long) u);
439 handle_error("fork");
450 .BR timerfd_create (2),