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 iour 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 will fail with the error EINVAL if the size of the supplied buf‐
48 fer is less than 8 bytes.
49 The value returned by read(2) is in host byte order, i.e., 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) will fail with the error EINVAL if the size of the
82 supplied buffer is less than 8 bytes, or if an attempt is made
83 to 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 open file descriptors has been reached.
130 ENFILE The system-wide limit on the total number of open files has been
132 reached.
133 ENODEV Could not mount (internal) anonymous inode device.
135 ENOMEM There was insufficient memory to create a new eventfd file
137 descriptor.
138
140 eventfd() is available on Linux since kernel 2.6.22. Working support
141 is provided in glibc since version 2.8. The eventfd2() system call
142 (see NOTES) is available on Linux since kernel 2.6.27. Since version
143 2.9, the glibc eventfd() wrapper will employ the eventfd2() system
144 call, if it is supported by the kernel.
145
147 eventfd() and eventfd2() are Linux-specific.
148
150 Applications can use an eventfd file descriptor instead of a pipe (see
151 pipe(2)) in all cases where a pipe is used simply to signal events.
152 The kernel overhead of an eventfd file descriptor is much lower than
153 that of a pipe, and only one file descriptor is required (versus the
154 two required for a pipe).
155 When used in the kernel, an eventfd file descriptor can provide a
157 bridge from kernel to user space, allowing, for example, functionali‐
158 ties like KAIO (kernel AIO) to signal to a file descriptor that some
159 operation is complete.
160 A key point about an eventfd file descriptor is that it can be moni‐
162 tored just like any other file descriptor using select(2), poll(2), or
163 epoll(7). This means that an application can simultaneously monitor
164 the readiness of "traditional" files and the readiness of other kernel
165 mechanisms that support the eventfd interface. (Without the eventfd()
166 interface, these mechanisms could not be multiplexed via select(2),
167 poll(2), or epoll(7).)
168 Underlying Linux system calls
170 There are two underlying Linux system calls: eventfd() and the more
171 recent eventfd2(). The former system call does not implement a flags
172 argument. The latter system call implements the flags values described
173 above. The glibc wrapper function will use eventfd2() where it is
174 available.
175 Additional glibc features
177 The GNU C library defines an additional type, and two functions that
178 attempt to abstract some of the details of reading and writing on an
179 eventfd file descriptor:
180 typedef uint64_t eventfd_t;
182 int eventfd_read(int fd, eventfd_t *value);
184 int eventfd_write(int fd, eventfd_t value);
185 The functions perform the read and write operations on an eventfd file
187 descriptor, returning 0 if the correct number of bytes was transferred,
188 or -1 otherwise.
189
191 The following program creates an eventfd file descriptor and then forks
192 to create a child process. While the parent briefly sleeps, the child
193 writes each of the integers supplied in the program's command-line
194 arguments to the eventfd file descriptor. When the parent has finished
195 sleeping, it reads from the eventfd file descriptor.
196 The following shell session shows a sample run of the program:
198 $ ./a.out 1 2 4 7 14
200 Child writing 1 to efd
201 Child writing 2 to efd
202 Child writing 4 to efd
203 Child writing 7 to efd
204 Child writing 14 to efd
205 Child completed write loop
206 Parent about to read
207 Parent read 28 (0x1c) from efd
208 Program source
210 #include <sys/eventfd.h>
212 #include <unistd.h>
213 #include <stdlib.h>
214 #include <stdio.h>
215 #include <stdint.h> /* Definition of uint64_t */
216 #define handle_error(msg) \
218 do { perror(msg); exit(EXIT_FAILURE); } while (0)
219 int
221 main(int argc, char *argv[])
222 {
223 int efd, j;
224 uint64_t u;
225 ssize_t s;
226 if (argc < 2) {
228 fprintf(stderr, "Usage: %s <num>...\n", argv[0]);
229 exit(EXIT_FAILURE);
230 }
231 efd = eventfd(0, 0);
233 if (efd == -1)
234 handle_error("eventfd");
235 switch (fork()) {
237 case 0:
238 for (j = 1; j < argc; j++) {
239 printf("Child writing %s to efd\n", argv[j]);
240 u = strtoull(argv[j], NULL, 0);
241 /* strtoull() allows various bases */
242 s = write(efd, &u, sizeof(uint64_t));
243 if (s != sizeof(uint64_t))
244 handle_error("write");
245 }
246 printf("Child completed write loop\n");
247 exit(EXIT_SUCCESS);
249 default:
251 sleep(2);
252 printf("Parent about to read\n");
254 s = read(efd, &u, sizeof(uint64_t));
255 if (s != sizeof(uint64_t))
256 handle_error("read");
257 printf("Parent read %llu (0x%llx) from efd\n",
258 (unsigned long long) u, (unsigned long long) u);
259 exit(EXIT_SUCCESS);
260 case -1:
262 handle_error("fork");
263 }
264 }
265
267 futex(2), pipe(2), poll(2), read(2), select(2), signalfd(2),
268 timerfd_create(2), write(2), epoll(7), sem_overview(7)
269
271 This page is part of release 3.53 of the Linux man-pages project. A
272 description of the project, and information about reporting bugs, can
273 be found at http://www.kernel.org/doc/man-pages/.
274Linux 2010-08-30 EVENTFD(2)