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 2010-08-30 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
40 The following values may be bitwise ORed in
42 to change the behaviour of
45 .BR EFD_CLOEXEC " (since Linux 2.6.27)"
48 flag on the new file descriptor.
49 See the description of the
53 for reasons why this may be useful.
55 .BR EFD_NONBLOCK " (since Linux 2.6.27)"
58 file status flag on the new open file description.
59 Using this flag saves extra calls to
61 to achieve the same result.
63 .BR EFD_SEMAPHORE " (since Linux 2.6.30)"
64 Provide semaphore-like semantics for reads from the new file descriptor.
67 In Linux up to version 2.6.26, the
69 argument is unused, and must be specified as zero.
73 returns a new file descriptor that can be used to refer to the
75 The following operations can be performed on the file descriptor:
80 returns an 8-byte integer.
83 will fail with the error
85 if the size of the supplied buffer is less than 8 bytes.
89 is in host byte order,
90 i.e., the native byte order for integers on the host machine.
94 depend on whether the eventfd counter currently has a nonzero value
97 flag was specified when creating the eventfd file descriptor:
102 was not specified and the eventfd counter has a nonzero value, then a
104 returns 8 bytes containing that value,
105 and the counter's value is reset to zero.
109 was specified and the eventfd counter has a nonzero value, then a
111 returns 8 bytes containing the value 1,
112 and the counter's value is decremented by 1.
114 If the eventfd counter is zero at the time of the call to
116 then the call either blocks until the counter becomes nonzero
119 proceeds as described above)
120 or fails with the error
122 if the file descriptor has been made nonblocking.
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
135 either blocks until a
137 is performed on the file descriptor,
138 or fails with the error
140 if the file descriptor has been made nonblocking.
144 will fail with the error
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.
149 .BR poll "(2), " select "(2) (and similar)"
150 The returned file descriptor supports
159 The file descriptor is readable
167 if the counter has a value greater than 0.
169 The file descriptor is writable
177 if it is possible to write a value of at least "1" without blocking.
179 If an overflow of the counter value was detected,
182 indicates the file descriptor as being both readable and writable, and
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
195 will return that maximum
197 value (i.e., 0xffffffffffffffff).
200 The eventfd file descriptor also supports the other file-descriptor
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.
211 A copy of the file descriptor created by
213 is inherited by the child produced by
215 The duplicate file descriptor is associated with the same
217 File descriptors created by
221 unless the close-on-exec flag has been set.
225 returns a new eventfd file descriptor.
226 On error, \-1 is returned and
228 is set to indicate the error.
232 An unsupported value was specified in
236 The per-process limit on open file descriptors has been reached.
239 The system-wide limit on the total number of open files has been
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.
251 There was insufficient memory to create a new
252 eventfd file descriptor.
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
260 system call (see NOTES) is available on Linux since kernel 2.6.27.
261 Since version 2.9, the glibc
263 wrapper will employ the
265 system call, if it is supported by the kernel.
272 Applications can use an eventfd file descriptor instead of a pipe (see
274 in all cases where a pipe is used simply to signal events.
275 The kernel overhead of an eventfd file descriptor
276 is much lower than that of a pipe,
277 and only one file descriptor is
278 required (versus the two required for a pipe).
280 When used in the kernel, an eventfd
281 file descriptor can provide a bridge from kernel to user space, allowing,
282 for example, functionalities like KAIO (kernel AIO)
283 .\" or eventually syslets/threadlets
284 to signal to a file descriptor that some operation is complete.
286 A key point about an eventfd file descriptor is that it can be
287 monitored just like any other file descriptor using
292 This means that an application can simultaneously monitor the
293 readiness of "traditional" files and the readiness of other
294 kernel mechanisms that support the eventfd interface.
297 interface, these mechanisms could not be multiplexed via
302 .SS Underlying Linux system calls
303 There are two underlying Linux system calls:
307 The former system call does not implement a
310 The latter system call implements the
312 values described above.
313 The glibc wrapper function will use
315 where it is available.
316 .SS Additional glibc features
317 The GNU C library defines an additional type,
318 and two functions that attempt to abstract some of the details of
319 reading and writing on an eventfd file descriptor:
323 typedef uint64_t eventfd_t;
325 int eventfd_read(int fd, eventfd_t *value);
326 int eventfd_write(int fd, eventfd_t value);
330 The functions perform the read and write operations on an
331 eventfd file descriptor,
332 returning 0 if the correct number of bytes was transferred,
336 The following program creates an eventfd file descriptor
337 and then forks to create a child process.
338 While the parent briefly sleeps,
339 the child writes each of the integers supplied in the program's
340 command-line arguments to the eventfd file descriptor.
341 When the parent has finished sleeping,
342 it reads from the eventfd file descriptor.
344 The following shell session shows a sample run of the program:
348 .RB "$" " ./a.out 1 2 4 7 14"
349 Child writing 1 to efd
350 Child writing 2 to efd
351 Child writing 4 to efd
352 Child writing 7 to efd
353 Child writing 14 to efd
354 Child completed write loop
356 Parent read 28 (0x1c) from efd
362 #include <sys/eventfd.h>
366 #include <stdint.h> /* Definition of uint64_t */
368 #define handle_error(msg) \\
369 do { perror(msg); exit(EXIT_FAILURE); } while (0)
372 main(int argc, char *argv[])
379 fprintf(stderr, "Usage: %s <num>...\\n", argv[0]);
385 handle_error("eventfd");
389 for (j = 1; j < argc; j++) {
390 printf("Child writing %s to efd\\n", argv[j]);
391 u = strtoull(argv[j], NULL, 0);
392 /* strtoull() allows various bases */
393 s = write(efd, &u, sizeof(uint64_t));
394 if (s != sizeof(uint64_t))
395 handle_error("write");
397 printf("Child completed write loop\\n");
404 printf("Parent about to read\\n");
405 s = read(efd, &u, sizeof(uint64_t));
406 if (s != sizeof(uint64_t))
407 handle_error("read");
408 printf("Parent read %llu (0x%llx) from efd\\n",
409 (unsigned long long) u, (unsigned long long) u);
413 handle_error("fork");
424 .BR timerfd_create (2),