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 userspace applications, and by the kernel to
16 notify userspace 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 Starting with Linux 2.6.27, the following values may be bitwise ORed in
22 flags to change the behaviour of eventfd():
23 EFD_NONBLOCK Set the O_NONBLOCK file status flag on the new open file
25 description. Using this flag saves extra calls to
26 fcntl(2) to achieve the same result.
27 EFD_CLOEXEC Set the close-on-exec (FD_CLOEXEC) flag on the new file
29 descriptor. See the description of the O_CLOEXEC flag in
30 open(2) for reasons why this may be useful.
31 In Linux up to version 2.6.26, the flags argument is unused, and must
33 be specified as zero.
34 As its return value, eventfd() returns a new file descriptor that can
36 be used to refer to the eventfd object. The following operations can
37 be performed on the file descriptor:
38 read(2)
40 If the eventfd counter has a non-zero value, then a read(2)
41 returns 8 bytes containing that value, and the counter's value
42 is reset to zero. (The returned value is in host byte order,
43 i.e., the native byte order for integers on the host machine.)
44 If the counter is zero at the time of the read(2), then the call
46 either blocks until the counter becomes non-zero, or fails with
47 the error EAGAIN if the file descriptor has been made non-block‐
48 ing.
49 A read(2) will fail with the error EINVAL if the size of the
51 supplied buffer is less than 8 bytes.
52 write(2)
54 A write(2) call adds the 8-byte integer value supplied in its
55 buffer to the counter. The maximum value that may be stored in
56 the counter is the largest unsigned 64-bit value minus 1 (i.e.,
57 0xfffffffffffffffe). If the addition would cause the counter's
58 value to exceed the maximum, then the write(2) either blocks
59 until a read(2) is performed on the file descriptor, or fails
60 with the error EAGAIN if the file descriptor has been made non-
61 blocking.
62 A write(2) will fail with the error EINVAL if the size of the
64 supplied buffer is less than 8 bytes, or if an attempt is made
65 to write the value 0xffffffffffffffff.
66 poll(2), select(2) (and similar)
68 The returned file descriptor supports poll(2) (and analogously
69 epoll(7)) and select(2), as follows:
70 * The file descriptor is readable (the select(2) readfds argu‐
72 ment; the poll(2) POLLIN flag) if the counter has a value
73 greater than 0.
74 * The file descriptor is writable (the select(2) writefds argu‐
76 ment; the poll(2) POLLOUT flag) if it is possible to write a
77 value of at least "1" without blocking.
78 * If an overflow of the counter value was detected, then
80 select(2) indicates the file descriptor as being both read‐
81 able and writable, and poll(2) returns a POLLERR event. As
82 noted above, write(2) can never overflow the counter. How‐
83 ever an overflow can occur if 2^64 eventfd "signal posts"
84 were performed by the KAIO subsystem (theoretically possible,
85 but practically unlikely). If an overflow has occurred, then
86 read(2) will return that maximum uint64_t value (i.e.,
87 0xffffffffffffffff).
88 The eventfd file descriptor also supports the other file-
90 descriptor multiplexing APIs: pselect(2), ppoll(2), and
91 epoll(7).
92 close(2)
94 When the file descriptor is no longer required it should be
95 closed. When all file descriptors associated with the same
96 eventfd object have been closed, the resources for object are
97 freed by the kernel.
98 A copy of the file descriptor created by eventfd() is inherited by the
100 child produced by fork(2). The duplicate file descriptor is associated
101 with the same eventfd object. File descriptors created by eventfd()
102 are preserved across execve(2).
103
105 On success, eventfd() returns a new eventfd file descriptor. On error,
106 -1 is returned and errno is set to indicate the error.
107
109 EINVAL flags is invalid; or, in Linux 2.6.26 or earlier, flags is non-
110 zero.
111 EMFILE The per-process limit on open file descriptors has been reached.
113 ENFILE The system-wide limit on the total number of open files has been
115 reached.
116 ENODEV Could not mount (internal) anonymous inode device.
118 ENOMEM There was insufficient memory to create a new eventfd file
120 descriptor.
121
123 eventfd() is available on Linux since kernel 2.6.22. Working support
124 is provided in glibc since version 2.8. The eventfd2() system call
125 (see NOTES) is available on Linux since kernel 2.6.27. Since version
126 2.9, the glibc eventfd() wrapper will employ the eventfd2() system
127 call, if it is supported by the kernel.
128
130 eventfd() and eventfd2() are Linux-specific.
131
133 Applications can use an eventfd file descriptor instead of a pipe (see
134 pipe(2)) in all cases where a pipe is used simply to signal events.
135 The kernel overhead of an eventfd file descriptor is much lower than
136 that of a pipe, and only one file descriptor is required (versus the
137 two required for a pipe).
138 When used in the kernel, an eventfd file descriptor can provide a ker‐
140 nel-userspace bridge allowing, for example, functionalities like KAIO
141 (kernel AIO) to signal to a file descriptor that some operation is com‐
142 plete.
143 A key point about an eventfd file descriptor is that it can be moni‐
145 tored just like any other file descriptor using select(2), poll(2), or
146 epoll(7). This means that an application can simultaneously monitor
147 the readiness of "traditional" files and the readiness of other kernel
148 mechanisms that support the eventfd interface. (Without the eventfd()
149 interface, these mechanisms could not be multiplexed via select(2),
150 poll(2), or epoll(7).)
151 Underlying Linux system calls
153 There are two underlying Linux system calls: eventfd() and the more
154 recent eventfd2(). The former system call does not implement a flags
155 argument. The latter system call implements the flags values described
156 above. The glibc wrapper function will use eventfd2() where it is
157 available.
158 Additional glibc features
160 The GNU C library defines an additional type, and two functions that
161 attempt to abstract some of the details of reading and writing on an
162 eventfd file descriptor:
163 typedef uint64_t eventfd_t;
165 int eventfd_read(int fd, eventfd_t *value);
167 int eventfd_write(int fd, eventfd_t value);
168 The functions perform the read and write operations on an eventfd file
170 descriptor, returning 0 if the correct number of bytes was transferred,
171 or -1 otherwise.
172
174 The following program creates an eventfd file descriptor and then forks
175 to create a child process. While the parent briefly sleeps, the child
176 writes each of the integers supplied in the program's command-line
177 arguments to the eventfd file descriptor. When the parent has finished
178 sleeping, it reads from the eventfd file descriptor.
179 The following shell session shows a sample run of the program:
181 $ ./a.out 1 2 4 7 14
183 Child writing 1 to efd
184 Child writing 2 to efd
185 Child writing 4 to efd
186 Child writing 7 to efd
187 Child writing 14 to efd
188 Child completed write loop
189 Parent about to read
190 Parent read 28 (0x1c) from efd
191 Program source
193 #include <sys/eventfd.h>
195 #include <unistd.h>
196 #include <stdlib.h>
197 #include <stdio.h>
198 #include <stdint.h> /* Definition of uint64_t */
199 #define handle_error(msg) \
201 do { perror(msg); exit(EXIT_FAILURE); } while (0)
202 int
204 main(int argc, char *argv[])
205 {
206 int efd, j;
207 uint64_t u;
208 ssize_t s;
209 if (argc < 2) {
211 fprintf(stderr, "Usage: %s <num>...\n", argv[0]);
212 exit(EXIT_FAILURE);
213 }
214 efd = eventfd(0, 0);
216 if (efd == -1)
217 handle_error("eventfd");
218 switch (fork()) {
220 case 0:
221 for (j = 1; j < argc; j++) {
222 printf("Child writing %s to efd\n", argv[j]);
223 u = strtoull(argv[j], NULL, 0);
224 /* strtoull() allows various bases */
225 s = write(efd, &u, sizeof(uint64_t));
226 if (s != sizeof(uint64_t))
227 handle_error("write");
228 }
229 printf("Child completed write loop\n");
230 exit(EXIT_SUCCESS);
232 default:
234 sleep(2);
235 printf("Parent about to read\n");
237 s = read(efd, &u, sizeof(uint64_t));
238 if (s != sizeof(uint64_t))
239 handle_error("read");
240 printf("Parent read %llu (0x%llx) from efd\n",
241 (unsigned long long) u, (unsigned long long) u);
242 exit(EXIT_SUCCESS);
243 case -1:
245 handle_error("fork");
246 }
247 }
248
250 futex(2), pipe(2), poll(2), read(2), select(2), signalfd(2),
251 timerfd_create(2), write(2), epoll(7), sem_overview(7)
252
254 This page is part of release 3.22 of the Linux man-pages project. A
255 description of the project, and information about reporting bugs, can
256 be found at http://www.kernel.org/doc/man-pages/.
257Linux 2009-01-26 EVENTFD(2)