| 1 |
'\" t |
| 2 |
.\" Copyright 2008, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: GPL-2.0-or-later |
| 6 |
.\" |
| 7 |
.TH eventfd 2 2026-02-16 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
eventfd \- create a file descriptor for event notification |
| 10 |
.SH LIBRARY |
| 11 |
Standard C library |
| 12 |
.RI ( libc ,\~ \-lc ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.B #include <sys/eventfd.h> |
| 16 |
.P |
| 17 |
.BI "int eventfd(unsigned int " initval ", int " flags ); |
| 18 |
.fi |
| 19 |
.SH DESCRIPTION |
| 20 |
.BR eventfd () |
| 21 |
creates an "eventfd object" that can be used as |
| 22 |
an event wait/notify mechanism by user-space applications, |
| 23 |
and by the kernel to notify user-space applications of events. |
| 24 |
The object contains an unsigned 64-bit integer |
| 25 |
.RI ( uint64_t ) |
| 26 |
counter that is maintained by the kernel. |
| 27 |
This counter is initialized with the value specified in the argument |
| 28 |
.IR initval . |
| 29 |
.P |
| 30 |
As its return value, |
| 31 |
.BR eventfd () |
| 32 |
returns a new file descriptor that can be used to refer to the |
| 33 |
eventfd object. |
| 34 |
.P |
| 35 |
The following values may be bitwise ORed in |
| 36 |
.I flags |
| 37 |
to change the behavior of |
| 38 |
.BR eventfd (): |
| 39 |
.TP |
| 40 |
.BR EFD_CLOEXEC " (since Linux 2.6.27)" |
| 41 |
Set the close-on-exec |
| 42 |
.RB ( FD_CLOEXEC ) |
| 43 |
flag on the new file descriptor. |
| 44 |
See the description of the |
| 45 |
.B O_CLOEXEC |
| 46 |
flag in |
| 47 |
.BR open (2) |
| 48 |
for reasons why this may be useful. |
| 49 |
.TP |
| 50 |
.BR EFD_NONBLOCK " (since Linux 2.6.27)" |
| 51 |
Set the |
| 52 |
.B O_NONBLOCK |
| 53 |
file status flag on the open file description (see |
| 54 |
.BR open (2)) |
| 55 |
referred to by the new file descriptor. |
| 56 |
Using this flag saves extra calls to |
| 57 |
.BR fcntl (2) |
| 58 |
to achieve the same result. |
| 59 |
.TP |
| 60 |
.BR EFD_SEMAPHORE " (since Linux 2.6.30)" |
| 61 |
Provide semaphore-like semantics for reads from the new file descriptor. |
| 62 |
See below. |
| 63 |
.P |
| 64 |
Up to Linux 2.6.26, the |
| 65 |
.I flags |
| 66 |
argument is unused, and must be specified as zero. |
| 67 |
.P |
| 68 |
The following operations can be performed on the file descriptor returned by |
| 69 |
.BR eventfd (): |
| 70 |
.TP |
| 71 |
.BR read (2) |
| 72 |
Each successful |
| 73 |
.BR read (2) |
| 74 |
returns an 8-byte integer. |
| 75 |
A |
| 76 |
.BR read (2) |
| 77 |
fails with the error |
| 78 |
.B EINVAL |
| 79 |
if the size of the supplied buffer is less than 8 bytes. |
| 80 |
.IP |
| 81 |
The value returned by |
| 82 |
.BR read (2) |
| 83 |
is in host byte order\[em]that is, |
| 84 |
the native byte order for integers on the host machine. |
| 85 |
.IP |
| 86 |
The semantics of |
| 87 |
.BR read (2) |
| 88 |
depend on whether the eventfd counter currently has a nonzero value |
| 89 |
and whether the |
| 90 |
.B EFD_SEMAPHORE |
| 91 |
flag was specified when creating the eventfd file descriptor: |
| 92 |
.RS |
| 93 |
.IP \[bu] 3 |
| 94 |
If |
| 95 |
.B EFD_SEMAPHORE |
| 96 |
was not specified and the eventfd counter has a nonzero value, then a |
| 97 |
.BR read (2) |
| 98 |
returns 8 bytes containing that value, |
| 99 |
and the counter's value is reset to zero. |
| 100 |
.IP \[bu] |
| 101 |
If |
| 102 |
.B EFD_SEMAPHORE |
| 103 |
was specified and the eventfd counter has a nonzero value, then a |
| 104 |
.BR read (2) |
| 105 |
returns 8 bytes containing the value 1, |
| 106 |
and the counter's value is decremented by 1. |
| 107 |
.IP \[bu] |
| 108 |
If the eventfd counter is zero at the time of the call to |
| 109 |
.BR read (2), |
| 110 |
then the call either blocks until the counter becomes nonzero |
| 111 |
(at which time, the |
| 112 |
.BR read (2) |
| 113 |
proceeds as described above) |
| 114 |
or fails with the error |
| 115 |
.B EAGAIN |
| 116 |
if the file descriptor has been made nonblocking. |
| 117 |
.RE |
| 118 |
.TP |
| 119 |
.BR write (2) |
| 120 |
A |
| 121 |
.BR write (2) |
| 122 |
call adds the 8-byte integer value supplied in its |
| 123 |
buffer to the counter. |
| 124 |
The maximum value that may be stored in the counter is the largest |
| 125 |
unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe). |
| 126 |
If the addition would cause the counter's value to exceed |
| 127 |
the maximum, then the |
| 128 |
.BR write (2) |
| 129 |
either blocks until a |
| 130 |
.BR read (2) |
| 131 |
is performed on the file descriptor, |
| 132 |
or fails with the error |
| 133 |
.B EAGAIN |
| 134 |
if the file descriptor has been made nonblocking. |
| 135 |
.IP |
| 136 |
A |
| 137 |
.BR write (2) |
| 138 |
fails with the error |
| 139 |
.B EINVAL |
| 140 |
if the size of the supplied buffer is less than 8 bytes, |
| 141 |
or if an attempt is made to write the value 0xffffffffffffffff. |
| 142 |
.TP |
| 143 |
.BR poll (2) |
| 144 |
.TQ |
| 145 |
.BR select (2) |
| 146 |
.TQ |
| 147 |
(and similar) |
| 148 |
The returned file descriptor supports |
| 149 |
.BR poll (2) |
| 150 |
(and analogously |
| 151 |
.BR epoll (7)) |
| 152 |
and |
| 153 |
.BR select (2), |
| 154 |
as follows: |
| 155 |
.RS |
| 156 |
.IP \[bu] 3 |
| 157 |
The file descriptor is readable |
| 158 |
(the |
| 159 |
.BR select (2) |
| 160 |
.I readfds |
| 161 |
argument; |
| 162 |
the |
| 163 |
.BR poll (2) |
| 164 |
.B POLLIN |
| 165 |
flag) |
| 166 |
if the counter has a value greater than 0. |
| 167 |
.IP \[bu] |
| 168 |
The file descriptor is writable |
| 169 |
(the |
| 170 |
.BR select (2) |
| 171 |
.I writefds |
| 172 |
argument; |
| 173 |
the |
| 174 |
.BR poll (2) |
| 175 |
.B POLLOUT |
| 176 |
flag) |
| 177 |
if it is possible to write a value of at least "1" without blocking. |
| 178 |
.IP \[bu] |
| 179 |
If an overflow of the counter value was detected, |
| 180 |
then |
| 181 |
.BR select (2) |
| 182 |
indicates the file descriptor as being both readable and writable, and |
| 183 |
.BR poll (2) |
| 184 |
returns a |
| 185 |
.B POLLERR |
| 186 |
event. |
| 187 |
As noted above, |
| 188 |
.BR write (2) |
| 189 |
can never overflow the counter. |
| 190 |
However an overflow can occur if 2\[ha]64 |
| 191 |
eventfd "signal posts" were performed by the KAIO |
| 192 |
subsystem (theoretically possible, but practically unlikely). |
| 193 |
If an overflow has occurred, then |
| 194 |
.BR read (2) |
| 195 |
will return that maximum |
| 196 |
.I uint64_t |
| 197 |
value (i.e., 0xffffffffffffffff). |
| 198 |
.RE |
| 199 |
.IP |
| 200 |
The eventfd file descriptor also supports the other file-descriptor |
| 201 |
multiplexing APIs: |
| 202 |
.BR pselect (2) |
| 203 |
and |
| 204 |
.BR ppoll (2). |
| 205 |
.TP |
| 206 |
.BR close (2) |
| 207 |
When the file descriptor is no longer required it should be closed. |
| 208 |
When all file descriptors associated with the same eventfd object |
| 209 |
have been closed, the resources for object are freed by the kernel. |
| 210 |
.P |
| 211 |
A copy of the file descriptor created by |
| 212 |
.BR eventfd () |
| 213 |
is inherited by the child produced by |
| 214 |
.BR fork (2). |
| 215 |
The duplicate file descriptor is associated with the same |
| 216 |
eventfd object. |
| 217 |
File descriptors created by |
| 218 |
.BR eventfd () |
| 219 |
are preserved across |
| 220 |
.BR execve (2), |
| 221 |
unless the close-on-exec flag has been set. |
| 222 |
.SH RETURN VALUE |
| 223 |
On success, |
| 224 |
.BR eventfd () |
| 225 |
returns a new eventfd file descriptor. |
| 226 |
On error, \-1 is returned and |
| 227 |
.I errno |
| 228 |
is set to indicate the error. |
| 229 |
.SH ERRORS |
| 230 |
.TP |
| 231 |
.B EINVAL |
| 232 |
An unsupported value was specified in |
| 233 |
.IR flags . |
| 234 |
.TP |
| 235 |
.B EMFILE |
| 236 |
The per-process limit on the number of open file descriptors has been reached. |
| 237 |
.TP |
| 238 |
.B ENFILE |
| 239 |
The system-wide limit on the total number of open files has been |
| 240 |
reached. |
| 241 |
.TP |
| 242 |
.B ENODEV |
| 243 |
.\" Note from Davide: |
| 244 |
.\" The ENODEV error is basically never going to happen if |
| 245 |
.\" the kernel boots correctly. That error happen only if during |
| 246 |
.\" the kernel initialization, some error occur in the anonymous |
| 247 |
.\" inode source initialization. |
| 248 |
Could not mount (internal) anonymous inode device. |
| 249 |
.TP |
| 250 |
.B ENOMEM |
| 251 |
There was insufficient memory to create a new |
| 252 |
eventfd file descriptor. |
| 253 |
.SH ATTRIBUTES |
| 254 |
For an explanation of the terms used in this section, see |
| 255 |
.BR attributes (7). |
| 256 |
.TS |
| 257 |
allbox; |
| 258 |
lbx lb lb |
| 259 |
l l l. |
| 260 |
Interface Attribute Value |
| 261 |
T{ |
| 262 |
.na |
| 263 |
.nh |
| 264 |
.BR eventfd () |
| 265 |
T} Thread safety MT-Safe |
| 266 |
.TE |
| 267 |
.SH VERSIONS |
| 268 |
.SS C library/kernel differences |
| 269 |
There are two underlying Linux system calls: |
| 270 |
.BR eventfd () |
| 271 |
and the more recent |
| 272 |
.BR eventfd2 (). |
| 273 |
The former system call does not implement a |
| 274 |
.I flags |
| 275 |
argument. |
| 276 |
The latter system call implements the |
| 277 |
.I flags |
| 278 |
values described above. |
| 279 |
The glibc wrapper function will use |
| 280 |
.BR eventfd2 () |
| 281 |
where it is available. |
| 282 |
.SS Additional glibc features |
| 283 |
The GNU C library defines an additional type, |
| 284 |
and two functions that attempt to abstract some of the details of |
| 285 |
reading and writing on an eventfd file descriptor: |
| 286 |
.P |
| 287 |
.in +4n |
| 288 |
.EX |
| 289 |
typedef uint64_t eventfd_t; |
| 290 |
\& |
| 291 |
int eventfd_read(int fd, eventfd_t *value); |
| 292 |
int eventfd_write(int fd, eventfd_t value); |
| 293 |
.EE |
| 294 |
.in |
| 295 |
.P |
| 296 |
The functions perform the read and write operations on an |
| 297 |
eventfd file descriptor, |
| 298 |
returning 0 if the correct number of bytes was transferred, |
| 299 |
or \-1 otherwise. |
| 300 |
.SH STANDARDS |
| 301 |
Linux, GNU. |
| 302 |
.SH HISTORY |
| 303 |
.TP |
| 304 |
.BR eventfd () |
| 305 |
Linux 2.6.22, |
| 306 |
glibc 2.8. |
| 307 |
.\" eventfd() is in glibc 2.7, but reportedly does not build |
| 308 |
.TP |
| 309 |
.BR eventfd2 () |
| 310 |
Linux 2.6.27 (see VERSIONS). |
| 311 |
Since glibc 2.9, the |
| 312 |
.BR eventfd () |
| 313 |
wrapper will employ the |
| 314 |
.BR eventfd2 () |
| 315 |
system call, if it is supported by the kernel. |
| 316 |
.SH NOTES |
| 317 |
Applications can use an eventfd file descriptor instead of a pipe (see |
| 318 |
.BR pipe (2)) |
| 319 |
in all cases where a pipe is used simply to signal events. |
| 320 |
The kernel overhead of an eventfd file descriptor |
| 321 |
is much lower than that of a pipe, |
| 322 |
and only one file descriptor is |
| 323 |
required (versus the two required for a pipe). |
| 324 |
.P |
| 325 |
When used in the kernel, an eventfd |
| 326 |
file descriptor can provide a bridge from kernel to user space, allowing, |
| 327 |
for example, functionalities like KAIO (kernel AIO) |
| 328 |
.\" or eventually syslets/threadlets |
| 329 |
to signal to a file descriptor that some operation is complete. |
| 330 |
.P |
| 331 |
A key point about an eventfd file descriptor is that it can be |
| 332 |
monitored just like any other file descriptor using |
| 333 |
.BR select (2), |
| 334 |
.BR poll (2), |
| 335 |
or |
| 336 |
.BR epoll (7). |
| 337 |
This means that an application can simultaneously monitor the |
| 338 |
readiness of "traditional" files and the readiness of other |
| 339 |
kernel mechanisms that support the eventfd interface. |
| 340 |
(Without the |
| 341 |
.BR eventfd () |
| 342 |
interface, these mechanisms could not be multiplexed via |
| 343 |
.BR select (2), |
| 344 |
.BR poll (2), |
| 345 |
or |
| 346 |
.BR epoll (7).) |
| 347 |
.P |
| 348 |
The current value of an eventfd counter can be viewed |
| 349 |
via the entry for the corresponding file descriptor in the process's |
| 350 |
.IR /proc/ pid /fdinfo |
| 351 |
directory. |
| 352 |
See |
| 353 |
.BR proc (5) |
| 354 |
for further details. |
| 355 |
.SH EXAMPLES |
| 356 |
The following program creates an eventfd file descriptor |
| 357 |
and then forks to create a child process. |
| 358 |
While the parent briefly sleeps, |
| 359 |
the child writes each of the integers supplied in the program's |
| 360 |
command-line arguments to the eventfd file descriptor. |
| 361 |
When the parent has finished sleeping, |
| 362 |
it reads from the eventfd file descriptor. |
| 363 |
.P |
| 364 |
The following shell session shows a sample run of the program: |
| 365 |
.P |
| 366 |
.in +4n |
| 367 |
.EX |
| 368 |
.RB "$" " ./a.out 1 2 4 7 14" |
| 369 |
Child writing 1 to efd |
| 370 |
Child writing 2 to efd |
| 371 |
Child writing 4 to efd |
| 372 |
Child writing 7 to efd |
| 373 |
Child writing 14 to efd |
| 374 |
Child completed write loop |
| 375 |
Parent about to read |
| 376 |
Parent read 28 (0x1c) from efd |
| 377 |
.EE |
| 378 |
.in |
| 379 |
.SS Program source |
| 380 |
\& |
| 381 |
.\" SRC BEGIN (eventfd.c) |
| 382 |
.EX |
| 383 |
#include <err.h> |
| 384 |
#include <inttypes.h> |
| 385 |
#include <stdio.h> |
| 386 |
#include <stdlib.h> |
| 387 |
#include <sys/eventfd.h> |
| 388 |
#include <sys/types.h> |
| 389 |
#include <unistd.h> |
| 390 |
\& |
| 391 |
int |
| 392 |
main(int argc, char *argv[]) |
| 393 |
{ |
| 394 |
int efd; |
| 395 |
uint64_t u; |
| 396 |
ssize_t s; |
| 397 |
\& |
| 398 |
if (argc < 2) { |
| 399 |
fprintf(stderr, "Usage: %s <num>...\[rs]n", argv[0]); |
| 400 |
exit(EXIT_FAILURE); |
| 401 |
} |
| 402 |
\& |
| 403 |
efd = eventfd(0, 0); |
| 404 |
if (efd == \-1) |
| 405 |
err(EXIT_FAILURE, "eventfd"); |
| 406 |
\& |
| 407 |
switch (fork()) { |
| 408 |
case 0: |
| 409 |
for (size_t j = 1; j < argc; j++) { |
| 410 |
printf("Child writing %s to efd\[rs]n", argv[j]); |
| 411 |
u = strtoull(argv[j], NULL, 0); |
| 412 |
/* strtoull() allows various bases */ |
| 413 |
s = write(efd, &u, sizeof(uint64_t)); |
| 414 |
if (s != sizeof(uint64_t)) |
| 415 |
err(EXIT_FAILURE, "write"); |
| 416 |
} |
| 417 |
printf("Child completed write loop\[rs]n"); |
| 418 |
\& |
| 419 |
exit(EXIT_SUCCESS); |
| 420 |
\& |
| 421 |
default: |
| 422 |
sleep(2); |
| 423 |
\& |
| 424 |
printf("Parent about to read\[rs]n"); |
| 425 |
s = read(efd, &u, sizeof(uint64_t)); |
| 426 |
if (s != sizeof(uint64_t)) |
| 427 |
err(EXIT_FAILURE, "read"); |
| 428 |
printf("Parent read %w64u (%#w64x) from efd\[rs]n", u, u); |
| 429 |
exit(EXIT_SUCCESS); |
| 430 |
\& |
| 431 |
case \-1: |
| 432 |
err(EXIT_FAILURE, "fork"); |
| 433 |
} |
| 434 |
} |
| 435 |
.EE |
| 436 |
.\" SRC END |
| 437 |
.SH SEE ALSO |
| 438 |
.BR futex (2), |
| 439 |
.BR pipe (2), |
| 440 |
.BR poll (2), |
| 441 |
.BR read (2), |
| 442 |
.BR select (2), |
| 443 |
.BR signalfd (2), |
| 444 |
.BR timerfd_create (2), |
| 445 |
.BR write (2), |
| 446 |
.BR epoll (7), |
| 447 |
.BR sem_overview (7) |