1EVENTFD(2) Linux Programmer's Manual EVENTFD(2)
2
6 eventfd - create a file descriptor for event notification
7
9 #include <sys/eventfd.h>
10 int eventfd(unsigned int initval, int flags);
12
14 eventfd() creates an "eventfd object" that can be used as an event
15 wait/notify mechanism by user-space applications, and by the kernel to
16 notify user-space applications of events. The object contains an
17 unsigned 64-bit integer (uint64_t) counter that is maintained by the
18 kernel. This counter is initialized with the value specified in the
19 argument initval.
20 The following values may be bitwise ORed in flags to change the behav‐
22 ior of eventfd():
23 EFD_CLOEXEC (since Linux 2.6.27)
25 Set the close-on-exec (FD_CLOEXEC) flag on the new file descrip‐
26 tor. See the description of the O_CLOEXEC flag in open(2) for
27 reasons why this may be useful.
28 EFD_NONBLOCK (since Linux 2.6.27)
30 Set the O_NONBLOCK file status flag on the new open file
31 description. Using this flag saves extra calls to fcntl(2) to
32 achieve the same result.
33 EFD_SEMAPHORE (since Linux 2.6.30)
35 Provide semaphore-like semantics for reads from the new file
36 descriptor. See below.
37 In Linux up to version 2.6.26, the flags argument is unused, and must
39 be specified as zero.
40 As its return value, eventfd() returns a new file descriptor that can
42 be used to refer to the eventfd object. The following operations can
43 be performed on the file descriptor:
44 read(2)
46 Each successful read(2) returns an 8-byte integer. A read(2)
47 fails with the error EINVAL if the size of the supplied buffer
48 is less than 8 bytes.
49 The value returned by read(2) is in host byte order—that is, the
51 native byte order for integers on the host machine.
52 The semantics of read(2) depend on whether the eventfd counter
54 currently has a nonzero value and whether the EFD_SEMAPHORE flag
55 was specified when creating the eventfd file descriptor:
56 * If EFD_SEMAPHORE was not specified and the eventfd counter
58 has a nonzero value, then a read(2) returns 8 bytes contain‐
59 ing that value, and the counter's value is reset to zero.
60 * If EFD_SEMAPHORE was specified and the eventfd counter has a
62 nonzero value, then a read(2) returns 8 bytes containing the
63 value 1, and the counter's value is decremented by 1.
64 * If the eventfd counter is zero at the time of the call to
66 read(2), then the call either blocks until the counter
67 becomes nonzero (at which time, the read(2) proceeds as
68 described above) or fails with the error EAGAIN if the file
69 descriptor has been made nonblocking.
70 write(2)
72 A write(2) call adds the 8-byte integer value supplied in its
73 buffer to the counter. The maximum value that may be stored in
74 the counter is the largest unsigned 64-bit value minus 1 (i.e.,
75 0xfffffffffffffffe). If the addition would cause the counter's
76 value to exceed the maximum, then the write(2) either blocks
77 until a read(2) is performed on the file descriptor, or fails
78 with the error EAGAIN if the file descriptor has been made non‐
79 blocking.
80 A write(2) fails with the error EINVAL if the size of the sup‐
82 plied buffer is less than 8 bytes, or if an attempt is made to
83 write the value 0xffffffffffffffff.
84 poll(2), select(2) (and similar)
86 The returned file descriptor supports poll(2) (and analogously
87 epoll(7)) and select(2), as follows:
88 * The file descriptor is readable (the select(2) readfds argu‐
90 ment; the poll(2) POLLIN flag) if the counter has a value
91 greater than 0.
92 * The file descriptor is writable (the select(2) writefds argu‐
94 ment; the poll(2) POLLOUT flag) if it is possible to write a
95 value of at least "1" without blocking.
96 * If an overflow of the counter value was detected, then
98 select(2) indicates the file descriptor as being both read‐
99 able and writable, and poll(2) returns a POLLERR event. As
100 noted above, write(2) can never overflow the counter. How‐
101 ever an overflow can occur if 2^64 eventfd "signal posts"
102 were performed by the KAIO subsystem (theoretically possible,
103 but practically unlikely). If an overflow has occurred, then
104 read(2) will return that maximum uint64_t value (i.e.,
105 0xffffffffffffffff).
106 The eventfd file descriptor also supports the other file-
108 descriptor multiplexing APIs: pselect(2) and ppoll(2).
109 close(2)
111 When the file descriptor is no longer required it should be
112 closed. When all file descriptors associated with the same
113 eventfd object have been closed, the resources for object are
114 freed by the kernel.
115 A copy of the file descriptor created by eventfd() is inherited by the
117 child produced by fork(2). The duplicate file descriptor is associated
118 with the same eventfd object. File descriptors created by eventfd()
119 are preserved across execve(2), unless the close-on-exec flag has been
120 set.
121
123 On success, eventfd() returns a new eventfd file descriptor. On error,
124 -1 is returned and errno is set to indicate the error.
125
127 EINVAL An unsupported value was specified in flags.
128 EMFILE The per-process limit on the number of open file descriptors has
130 been reached.
131 ENFILE The system-wide limit on the total number of open files has been
133 reached.
134 ENODEV Could not mount (internal) anonymous inode device.
136 ENOMEM There was insufficient memory to create a new eventfd file
138 descriptor.
139
141 eventfd() is available on Linux since kernel 2.6.22. Working support
142 is provided in glibc since version 2.8. The eventfd2() system call
143 (see NOTES) is available on Linux since kernel 2.6.27. Since version
144 2.9, the glibc eventfd() wrapper will employ the eventfd2() system
145 call, if it is supported by the kernel.
146
148 For an explanation of the terms used in this section, see
149 attributes(7).
150 ┌──────────┬───────────────┬─────────┐
152 │Interface │ Attribute │ Value │
153 ├──────────┼───────────────┼─────────┤
154 │eventfd() │ Thread safety │ MT-Safe │
155 └──────────┴───────────────┴─────────┘
156
158 eventfd() and eventfd2() are Linux-specific.
159
161 Applications can use an eventfd file descriptor instead of a pipe (see
162 pipe(2)) in all cases where a pipe is used simply to signal events.
163 The kernel overhead of an eventfd file descriptor is much lower than
164 that of a pipe, and only one file descriptor is required (versus the
165 two required for a pipe).
166 When used in the kernel, an eventfd file descriptor can provide a
168 bridge from kernel to user space, allowing, for example, functionali‐
169 ties like KAIO (kernel AIO) to signal to a file descriptor that some
170 operation is complete.
171 A key point about an eventfd file descriptor is that it can be moni‐
173 tored just like any other file descriptor using select(2), poll(2), or
174 epoll(7). This means that an application can simultaneously monitor
175 the readiness of "traditional" files and the readiness of other kernel
176 mechanisms that support the eventfd interface. (Without the eventfd()
177 interface, these mechanisms could not be multiplexed via select(2),
178 poll(2), or epoll(7).)
179 The current value of an eventfd counter can be viewed via the entry for
181 the corresponding file descriptor in the process's /proc/[pid]/fdinfo
182 directory. See proc(5) for further details.
183 C library/kernel differences
185 There are two underlying Linux system calls: eventfd() and the more
186 recent eventfd2(). The former system call does not implement a flags
187 argument. The latter system call implements the flags values described
188 above. The glibc wrapper function will use eventfd2() where it is
189 available.
190 Additional glibc features
192 The GNU C library defines an additional type, and two functions that
193 attempt to abstract some of the details of reading and writing on an
194 eventfd file descriptor:
195 typedef uint64_t eventfd_t;
197 int eventfd_read(int fd, eventfd_t *value);
199 int eventfd_write(int fd, eventfd_t value);
200 The functions perform the read and write operations on an eventfd file
202 descriptor, returning 0 if the correct number of bytes was transferred,
203 or -1 otherwise.
204
206 The following program creates an eventfd file descriptor and then forks
207 to create a child process. While the parent briefly sleeps, the child
208 writes each of the integers supplied in the program's command-line
209 arguments to the eventfd file descriptor. When the parent has finished
210 sleeping, it reads from the eventfd file descriptor.
211 The following shell session shows a sample run of the program:
213 $ ./a.out 1 2 4 7 14
215 Child writing 1 to efd
216 Child writing 2 to efd
217 Child writing 4 to efd
218 Child writing 7 to efd
219 Child writing 14 to efd
220 Child completed write loop
221 Parent about to read
222 Parent read 28 (0x1c) from efd
223 Program source
225 #include <sys/eventfd.h>
227 #include <unistd.h>
228 #include <stdlib.h>
229 #include <stdio.h>
230 #include <stdint.h> /* Definition of uint64_t */
231 #define handle_error(msg) \
233 do { perror(msg); exit(EXIT_FAILURE); } while (0)
234 int
236 main(int argc, char *argv[])
237 {
238 int efd, j;
239 uint64_t u;
240 ssize_t s;
241 if (argc < 2) {
243 fprintf(stderr, "Usage: %s <num>...\n", argv[0]);
244 exit(EXIT_FAILURE);
245 }
246 efd = eventfd(0, 0);
248 if (efd == -1)
249 handle_error("eventfd");
250 switch (fork()) {
252 case 0:
253 for (j = 1; j < argc; j++) {
254 printf("Child writing %s to efd\n", argv[j]);
255 u = strtoull(argv[j], NULL, 0);
256 /* strtoull() allows various bases */
257 s = write(efd, &u, sizeof(uint64_t));
258 if (s != sizeof(uint64_t))
259 handle_error("write");
260 }
261 printf("Child completed write loop\n");
262 exit(EXIT_SUCCESS);
264 default:
266 sleep(2);
267 printf("Parent about to read\n");
269 s = read(efd, &u, sizeof(uint64_t));
270 if (s != sizeof(uint64_t))
271 handle_error("read");
272 printf("Parent read %llu (0x%llx) from efd\n",
273 (unsigned long long) u, (unsigned long long) u);
274 exit(EXIT_SUCCESS);
275 case -1:
277 handle_error("fork");
278 }
279 }
280
282 futex(2), pipe(2), poll(2), read(2), select(2), signalfd(2),
283 timerfd_create(2), write(2), epoll(7), sem_overview(7)
284
286 This page is part of release 4.16 of the Linux man-pages project. A
287 description of the project, information about reporting bugs, and the
288 latest version of this page, can be found at
289 https://www.kernel.org/doc/man-pages/.
290Linux 2017-09-15 EVENTFD(2)