1 .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
2 .\" starting from a version by Davide Libenzi <davidel@xmailserver.org>
4 .\" This program is free software; you can redistribute it and/or modify
5 .\" it under the terms of the GNU General Public License as published by
6 .\" the Free Software Foundation; either version 2 of the License, or
7 .\" (at your option) any later version.
9 .\" This program is distributed in the hope that it will be useful,
10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 .\" GNU General Public License for more details.
14 .\" You should have received a copy of the GNU General Public
15 .\" License along with this manual; if not, see
16 .\" <http://www.gnu.org/licenses/>.
18 .\" 2008-10-10, mtk: describe eventfd2(), and EFD_NONBLOCK and EFD_CLOEXEC
20 .TH EVENTFD 2 2010-08-30 Linux "Linux Programmer's Manual"
22 eventfd \- create a file descriptor for event notification
24 .B #include <sys/eventfd.h>
26 .BI "int eventfd(unsigned int " initval ", int " flags );
29 creates an "eventfd object" that can be used as
30 an event wait/notify mechanism by user-space applications,
31 and by the kernel to notify user-space applications of events.
32 The object contains an unsigned 64-bit integer
34 counter that is maintained by the kernel.
35 This counter is initialized with the value specified in the argument
38 The following values may be bitwise ORed in
40 to change the behaviour of
43 .BR EFD_CLOEXEC " (since Linux 2.6.27)"
46 flag on the new file descriptor.
47 See the description of the
51 for reasons why this may be useful.
53 .BR EFD_NONBLOCK " (since Linux 2.6.27)"
56 file status flag on the new open file description.
57 Using this flag saves extra calls to
59 to achieve the same result.
61 .BR EFD_SEMAPHORE " (since Linux 2.6.30)"
62 Provide semaphore-like semantics for reads from the new file descriptor.
65 In Linux up to version 2.6.26, the
67 argument is unused, and must be specified as zero.
71 returns a new file descriptor that can be used to refer to the
73 The following operations can be performed on the file descriptor:
78 returns an 8-byte integer.
81 will fail with the error
83 if the size of the supplied buffer is less than 8 bytes.
87 is in host byte order,
88 i.e., the native byte order for integers on the host machine.
92 depend on whether the eventfd counter currently has a nonzero value
95 flag was specified when creating the eventfd file descriptor:
100 was not specified and the eventfd counter has a nonzero value, then a
102 returns 8 bytes containing that value,
103 and the counter's value is reset to zero.
107 was specified and the eventfd counter has a nonzero value, then a
109 returns 8 bytes containing the value 1,
110 and the counter's value is decremented by 1.
112 If the eventfd counter is zero at the time of the call to
114 then the call either blocks until the counter becomes nonzero
117 proceeds as described above)
118 or fails with the error
120 if the file descriptor has been made nonblocking.
126 call adds the 8-byte integer value supplied in its
127 buffer to the counter.
128 The maximum value that may be stored in the counter is the largest
129 unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe).
130 If the addition would cause the counter's value to exceed
131 the maximum, then the
133 either blocks until a
135 is performed on the file descriptor,
136 or fails with the error
138 if the file descriptor has been made nonblocking.
142 will fail with the error
144 if the size of the supplied buffer is less than 8 bytes,
145 or if an attempt is made to write the value 0xffffffffffffffff.
147 .BR poll "(2), " select "(2) (and similar)"
148 The returned file descriptor supports
157 The file descriptor is readable
165 if the counter has a value greater than 0.
167 The file descriptor is writable
175 if it is possible to write a value of at least "1" without blocking.
177 If an overflow of the counter value was detected,
180 indicates the file descriptor as being both readable and writable, and
187 can never overflow the counter.
188 However an overflow can occur if 2^64
189 eventfd "signal posts" were performed by the KAIO
190 subsystem (theoretically possible, but practically unlikely).
191 If an overflow has occurred, then
193 will return that maximum
195 value (i.e., 0xffffffffffffffff).
198 The eventfd file descriptor also supports the other file-descriptor
205 When the file descriptor is no longer required it should be closed.
206 When all file descriptors associated with the same eventfd object
207 have been closed, the resources for object are freed by the kernel.
209 A copy of the file descriptor created by
211 is inherited by the child produced by
213 The duplicate file descriptor is associated with the same
215 File descriptors created by
219 unless the close-on-exec flag has been set.
223 returns a new eventfd file descriptor.
224 On error, \-1 is returned and
226 is set to indicate the error.
230 An unsupported value was specified in
234 The per-process limit on open file descriptors has been reached.
237 The system-wide limit on the total number of open files has been
241 .\" Note from Davide:
242 .\" The ENODEV error is basically never going to happen if
243 .\" the kernel boots correctly. That error happen only if during
244 .\" the kernel initialization, some error occur in the anonymous
245 .\" inode source initialization.
246 Could not mount (internal) anonymous inode device.
249 There was insufficient memory to create a new
250 eventfd file descriptor.
253 is available on Linux since kernel 2.6.22.
254 Working support is provided in glibc since version 2.8.
255 .\" eventfd() is in glibc 2.7, but reportedly does not build
258 system call (see NOTES) is available on Linux since kernel 2.6.27.
259 Since version 2.9, the glibc
261 wrapper will employ the
263 system call, if it is supported by the kernel.
270 Applications can use an eventfd file descriptor instead of a pipe (see
272 in all cases where a pipe is used simply to signal events.
273 The kernel overhead of an eventfd file descriptor
274 is much lower than that of a pipe,
275 and only one file descriptor is
276 required (versus the two required for a pipe).
278 When used in the kernel, an eventfd
279 file descriptor can provide a bridge from kernel to user space, allowing,
280 for example, functionalities like KAIO (kernel AIO)
281 .\" or eventually syslets/threadlets
282 to signal to a file descriptor that some operation is complete.
284 A key point about an eventfd file descriptor is that it can be
285 monitored just like any other file descriptor using
290 This means that an application can simultaneously monitor the
291 readiness of "traditional" files and the readiness of other
292 kernel mechanisms that support the eventfd interface.
295 interface, these mechanisms could not be multiplexed via
300 .SS Underlying Linux system calls
301 There are two underlying Linux system calls:
305 The former system call does not implement a
308 The latter system call implements the
310 values described above.
311 The glibc wrapper function will use
313 where it is available.
314 .SS Additional glibc features
315 The GNU C library defines an additional type,
316 and two functions that attempt to abstract some of the details of
317 reading and writing on an eventfd file descriptor:
321 typedef uint64_t eventfd_t;
323 int eventfd_read(int fd, eventfd_t *value);
324 int eventfd_write(int fd, eventfd_t value);
328 The functions perform the read and write operations on an
329 eventfd file descriptor,
330 returning 0 if the correct number of bytes was transferred,
334 The following program creates an eventfd file descriptor
335 and then forks to create a child process.
336 While the parent briefly sleeps,
337 the child writes each of the integers supplied in the program's
338 command-line arguments to the eventfd file descriptor.
339 When the parent has finished sleeping,
340 it reads from the eventfd file descriptor.
342 The following shell session shows a sample run of the program:
346 .RB "$" " ./a.out 1 2 4 7 14"
347 Child writing 1 to efd
348 Child writing 2 to efd
349 Child writing 4 to efd
350 Child writing 7 to efd
351 Child writing 14 to efd
352 Child completed write loop
354 Parent read 28 (0x1c) from efd
360 #include <sys/eventfd.h>
364 #include <stdint.h> /* Definition of uint64_t */
366 #define handle_error(msg) \\
367 do { perror(msg); exit(EXIT_FAILURE); } while (0)
370 main(int argc, char *argv[])
377 fprintf(stderr, "Usage: %s <num>...\\n", argv[0]);
383 handle_error("eventfd");
387 for (j = 1; j < argc; j++) {
388 printf("Child writing %s to efd\\n", argv[j]);
389 u = strtoull(argv[j], NULL, 0);
390 /* strtoull() allows various bases */
391 s = write(efd, &u, sizeof(uint64_t));
392 if (s != sizeof(uint64_t))
393 handle_error("write");
395 printf("Child completed write loop\\n");
402 printf("Parent about to read\\n");
403 s = read(efd, &u, sizeof(uint64_t));
404 if (s != sizeof(uint64_t))
405 handle_error("read");
406 printf("Parent read %llu (0x%llx) from efd\\n",
407 (unsigned long long) u, (unsigned long long) u);
411 handle_error("fork");
422 .BR timerfd_create (2),