man2/eventfd.2

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