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