1EVENTFD(2)                 Linux Programmer's Manual                EVENTFD(2)
2
3
4

NAME

6       eventfd - create a file descriptor for event notification
7

SYNOPSIS

9       #include <sys/eventfd.h>
10
11       int eventfd(unsigned int initval, int flags);
12

DESCRIPTION

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 un‐
17       signed 64-bit integer (uint64_t) counter that is maintained by the ker‐
18       nel.  This counter is initialized with the value specified in the argu‐
19       ment initval.
20
21       As its return value, eventfd() returns a new file descriptor  that  can
22       be used to refer to the eventfd object.
23
24       The  following values may be bitwise ORed in flags to change the behav‐
25       ior of eventfd():
26
27       EFD_CLOEXEC (since Linux 2.6.27)
28              Set the close-on-exec (FD_CLOEXEC) flag on the new file descrip‐
29              tor.   See  the description of the O_CLOEXEC flag in open(2) for
30              reasons why this may be useful.
31
32       EFD_NONBLOCK (since Linux 2.6.27)
33              Set the O_NONBLOCK file status flag on the open file description
34              (see  open(2))  referred  to  by the new file descriptor.  Using
35              this flag saves extra calls to fcntl(2) to achieve the same  re‐
36              sult.
37
38       EFD_SEMAPHORE (since Linux 2.6.30)
39              Provide semaphore-like semantics for reads from the new file de‐
40              scriptor.  See below.
41
42       In Linux up to version 2.6.26, the flags argument is unused,  and  must
43       be specified as zero.
44
45       The  following  operations  can be performed on the file descriptor re‐
46       turned by eventfd():
47
48       read(2)
49              Each successful read(2) returns an 8-byte  integer.   A  read(2)
50              fails  with  the error EINVAL if the size of the supplied buffer
51              is less than 8 bytes.
52
53              The value returned by read(2) is in host byte order—that is, the
54              native byte order for integers on the host machine.
55
56              The  semantics  of read(2) depend on whether the eventfd counter
57              currently has a nonzero value and whether the EFD_SEMAPHORE flag
58              was specified when creating the eventfd file descriptor:
59
60              *  If  EFD_SEMAPHORE  was  not specified and the eventfd counter
61                 has a nonzero value, then a read(2) returns 8 bytes  contain‐
62                 ing that value, and the counter's value is reset to zero.
63
64              *  If  EFD_SEMAPHORE was specified and the eventfd counter has a
65                 nonzero value, then a read(2) returns 8 bytes containing  the
66                 value 1, and the counter's value is decremented by 1.
67
68              *  If  the  eventfd  counter  is zero at the time of the call to
69                 read(2), then the call either blocks until  the  counter  be‐
70                 comes  nonzero  (at  which  time, the read(2) proceeds as de‐
71                 scribed above) or fails with the error EAGAIN if the file de‐
72                 scriptor has been made nonblocking.
73
74       write(2)
75              A  write(2)  call  adds the 8-byte integer value supplied in its
76              buffer to the counter.  The maximum value that may be stored  in
77              the  counter is the largest unsigned 64-bit value minus 1 (i.e.,
78              0xfffffffffffffffe).  If the addition would cause the  counter's
79              value to exceed the maximum, then the write(2) either blocks un‐
80              til a read(2) is performed on the file descriptor, or fails with
81              the  error EAGAIN if the file descriptor has been made nonblock‐
82              ing.
83
84              A write(2) fails with the error EINVAL if the size of  the  sup‐
85              plied  buffer  is less than 8 bytes, or if an attempt is made to
86              write the value 0xffffffffffffffff.
87
88       poll(2), select(2) (and similar)
89              The returned file descriptor supports poll(2)  (and  analogously
90              epoll(7)) and select(2), as follows:
91
92              *  The  file descriptor is readable (the select(2) readfds argu‐
93                 ment; the poll(2) POLLIN flag) if the  counter  has  a  value
94                 greater than 0.
95
96              *  The file descriptor is writable (the select(2) writefds argu‐
97                 ment; the poll(2) POLLOUT flag) if it is possible to write  a
98                 value of at least "1" without blocking.
99
100              *  If  an  overflow  of the counter value was detected, then se‐
101                 lect(2) indicates the file descriptor as being both  readable
102                 and  writable, and poll(2) returns a POLLERR event.  As noted
103                 above, write(2) can never overflow the counter.   However  an
104                 overflow  can  occur if 2^64 eventfd "signal posts" were per‐
105                 formed by the KAIO  subsystem  (theoretically  possible,  but
106                 practically  unlikely).   If  an  overflow has occurred, then
107                 read(2)  will  return  that  maximum  uint64_t  value  (i.e.,
108                 0xffffffffffffffff).
109
110              The  eventfd  file  descriptor  also supports the other file-de‐
111              scriptor multiplexing APIs: pselect(2) and ppoll(2).
112
113       close(2)
114              When the file descriptor is no  longer  required  it  should  be
115              closed.   When  all  file  descriptors  associated with the same
116              eventfd object have been closed, the resources  for  object  are
117              freed by the kernel.
118
119       A  copy of the file descriptor created by eventfd() is inherited by the
120       child produced by fork(2).  The duplicate file descriptor is associated
121       with  the  same  eventfd object.  File descriptors created by eventfd()
122       are preserved across execve(2), unless the close-on-exec flag has  been
123       set.
124

RETURN VALUE

126       On success, eventfd() returns a new eventfd file descriptor.  On error,
127       -1 is returned and errno is set to indicate the error.
128

ERRORS

130       EINVAL An unsupported value was specified in flags.
131
132       EMFILE The per-process limit on the number of open file descriptors has
133              been reached.
134
135       ENFILE The system-wide limit on the total number of open files has been
136              reached.
137
138       ENODEV Could not mount (internal) anonymous inode device.
139
140       ENOMEM There was insufficient memory to create a new eventfd  file  de‐
141              scriptor.
142

VERSIONS

144       eventfd()  is  available on Linux since kernel 2.6.22.  Working support
145       is provided in glibc since version 2.8.   The  eventfd2()  system  call
146       (see  NOTES)  is available on Linux since kernel 2.6.27.  Since version
147       2.9, the glibc eventfd() wrapper  will  employ  the  eventfd2()  system
148       call, if it is supported by the kernel.
149

ATTRIBUTES

151       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
152       tributes(7).
153
154       ┌────────────────────────────────────────────┬───────────────┬─────────┐
155Interface                                   Attribute     Value   
156       ├────────────────────────────────────────────┼───────────────┼─────────┤
157eventfd()                                   │ Thread safety │ MT-Safe │
158       └────────────────────────────────────────────┴───────────────┴─────────┘
159

CONFORMING TO

161       eventfd() and eventfd2() are Linux-specific.
162

NOTES

164       Applications can use an eventfd file descriptor instead of a pipe  (see
165       pipe(2))  in  all  cases  where a pipe is used simply to signal events.
166       The kernel overhead of an eventfd file descriptor is  much  lower  than
167       that  of  a  pipe, and only one file descriptor is required (versus the
168       two required for a pipe).
169
170       When used in the kernel, an  eventfd  file  descriptor  can  provide  a
171       bridge  from  kernel to user space, allowing, for example, functionali‐
172       ties like KAIO (kernel AIO) to signal to a file  descriptor  that  some
173       operation is complete.
174
175       A  key  point  about an eventfd file descriptor is that it can be moni‐
176       tored just like any other file descriptor using select(2), poll(2),  or
177       epoll(7).   This  means  that an application can simultaneously monitor
178       the readiness of "traditional" files and the readiness of other  kernel
179       mechanisms  that support the eventfd interface.  (Without the eventfd()
180       interface, these mechanisms could not  be  multiplexed  via  select(2),
181       poll(2), or epoll(7).)
182
183       The current value of an eventfd counter can be viewed via the entry for
184       the corresponding file descriptor in the  process's  /proc/[pid]/fdinfo
185       directory.  See proc(5) for further details.
186
187   C library/kernel differences
188       There are two underlying Linux system calls: eventfd() and the more re‐
189       cent eventfd2().  The former system call does not implement a flags ar‐
190       gument.   The  latter system call implements the flags values described
191       above.  The glibc wrapper function will  use  eventfd2()  where  it  is
192       available.
193
194   Additional glibc features
195       The  GNU  C  library defines an additional type, and two functions that
196       attempt to abstract some of the details of reading and  writing  on  an
197       eventfd file descriptor:
198
199           typedef uint64_t eventfd_t;
200
201           int eventfd_read(int fd, eventfd_t *value);
202           int eventfd_write(int fd, eventfd_t value);
203
204       The  functions perform the read and write operations on an eventfd file
205       descriptor, returning 0 if the correct number of bytes was transferred,
206       or -1 otherwise.
207

EXAMPLES

209       The following program creates an eventfd file descriptor and then forks
210       to create a child process.  While the parent briefly sleeps, the  child
211       writes  each of the integers supplied in the program's command-line ar‐
212       guments to the eventfd file descriptor.  When the parent  has  finished
213       sleeping, it reads from the eventfd file descriptor.
214
215       The following shell session shows a sample run of the program:
216
217           $ ./a.out 1 2 4 7 14
218           Child writing 1 to efd
219           Child writing 2 to efd
220           Child writing 4 to efd
221           Child writing 7 to efd
222           Child writing 14 to efd
223           Child completed write loop
224           Parent about to read
225           Parent read 28 (0x1c) from efd
226
227   Program source
228
229       #include <sys/eventfd.h>
230       #include <unistd.h>
231       #include <inttypes.h>           /* Definition of PRIu64 & PRIx64 */
232       #include <stdlib.h>
233       #include <stdio.h>
234       #include <stdint.h>             /* Definition of uint64_t */
235
236       #define handle_error(msg) \
237           do { perror(msg); exit(EXIT_FAILURE); } while (0)
238
239       int
240       main(int argc, char *argv[])
241       {
242           int efd;
243           uint64_t u;
244           ssize_t s;
245
246           if (argc < 2) {
247               fprintf(stderr, "Usage: %s <num>...\n", argv[0]);
248               exit(EXIT_FAILURE);
249           }
250
251           efd = eventfd(0, 0);
252           if (efd == -1)
253               handle_error("eventfd");
254
255           switch (fork()) {
256           case 0:
257               for (int j = 1; j < argc; j++) {
258                   printf("Child writing %s to efd\n", argv[j]);
259                   u = strtoull(argv[j], NULL, 0);
260                           /* strtoull() allows various bases */
261                   s = write(efd, &u, sizeof(uint64_t));
262                   if (s != sizeof(uint64_t))
263                       handle_error("write");
264               }
265               printf("Child completed write loop\n");
266
267               exit(EXIT_SUCCESS);
268
269           default:
270               sleep(2);
271
272               printf("Parent about to read\n");
273               s = read(efd, &u, sizeof(uint64_t));
274               if (s != sizeof(uint64_t))
275                   handle_error("read");
276               printf("Parent read %"PRIu64" (%#"PRIx64") from efd\n", u, u);
277               exit(EXIT_SUCCESS);
278
279           case -1:
280               handle_error("fork");
281           }
282       }
283

SEE ALSO

285       futex(2),    pipe(2),   poll(2),   read(2),   select(2),   signalfd(2),
286       timerfd_create(2), write(2), epoll(7), sem_overview(7)
287

COLOPHON

289       This page is part of release 5.12 of the Linux  man-pages  project.   A
290       description  of  the project, information about reporting bugs, and the
291       latest    version    of    this    page,    can     be     found     at
292       https://www.kernel.org/doc/man-pages/.
293
294
295
296Linux                             2021-03-22                        EVENTFD(2)
Impressum