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 2017-09-15 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 The following values may be bitwise ORed in
  41 .IR flags
  42 to change the behavior of
  43 .BR eventfd ():
  44 .TP
  45 .BR EFD_CLOEXEC " (since Linux 2.6.27)"
  46 Set the close-on-exec
  47 .RB ( FD_CLOEXEC )
  48 flag on the new file descriptor.
  49 See the description of the
  50 .B O_CLOEXEC
  51 flag in
  52 .BR open (2)
  53 for reasons why this may be useful.
  54 .TP
  55 .BR EFD_NONBLOCK " (since Linux 2.6.27)"
  56 Set the
  57 .BR O_NONBLOCK
  58 file status flag on the new open file description.
  59 Using this flag saves extra calls to
  60 .BR fcntl (2)
  61 to achieve the same result.
  62 .TP
  63 .BR EFD_SEMAPHORE " (since Linux 2.6.30)"
  64 Provide semaphore-like semantics for reads from the new file descriptor.
  65 See below.
  66 .PP
  67 In Linux up to version 2.6.26, the
  68 .I flags
  69 argument is unused, and must be specified as zero.
  70 .PP
  71 As its return value,
  72 .BR eventfd ()
  73 returns a new file descriptor that can be used to refer to the
  74 eventfd object.
  75 The following operations can be performed on the file descriptor:
  76 .TP
  77 .BR read (2)
  78 Each successful
  79 .BR read (2)
  80 returns an 8-byte integer.
  81 A
  82 .BR read (2)
  83 fails with the error
  84 .B EINVAL
  85 if the size of the supplied buffer is less than 8 bytes.
  86 .IP
  87 The value returned by
  88 .BR read (2)
  89 is in host byte order\(emthat is,
  90 the native byte order for integers on the host machine.
  91 .IP
  92 The semantics of
  93 .BR read (2)
  94 depend on whether the eventfd counter currently has a nonzero value
  95 and whether the
  96 .BR EFD_SEMAPHORE
  97 flag was specified when creating the eventfd file descriptor:
  98 .RS
  99 .IP * 3
 100 If
 101 .BR EFD_SEMAPHORE
 102 was not specified and the eventfd counter has a nonzero value, then a
 103 .BR read (2)
 104 returns 8 bytes containing that value,
 105 and the counter's value is reset to zero.
 106 .IP *
 107 If
 108 .BR EFD_SEMAPHORE
 109 was specified and the eventfd counter has a nonzero value, then a
 110 .BR read (2)
 111 returns 8 bytes containing the value 1,
 112 and the counter's value is decremented by 1.
 113 .IP *
 114 If the eventfd counter is zero at the time of the call to
 115 .BR read (2),
 116 then the call either blocks until the counter becomes nonzero
 117 (at which time, the
 118 .BR read (2)
 119 proceeds as described above)
 120 or fails with the error
 121 .B EAGAIN
 122 if the file descriptor has been made nonblocking.
 123 .RE
 124 .TP
 125 .BR write (2)
 126 A
 127 .BR write (2)
 128 call adds the 8-byte integer value supplied in its
 129 buffer to the counter.
 130 The maximum value that may be stored in the counter is the largest
 131 unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe).
 132 If the addition would cause the counter's value to exceed
 133 the maximum, then the
 134 .BR write (2)
 135 either blocks until a
 136 .BR read (2)
 137 is performed on the file descriptor,
 138 or fails with the error
 139 .B EAGAIN
 140 if the file descriptor has been made nonblocking.
 141 .IP
 142 A
 143 .BR write (2)
 144 fails with the error
 145 .B EINVAL
 146 if the size of the supplied buffer is less than 8 bytes,
 147 or if an attempt is made to write the value 0xffffffffffffffff.
 148 .TP
 149 .BR poll "(2), " select "(2) (and similar)"
 150 The returned file descriptor supports
 151 .BR poll (2)
 152 (and analogously
 153 .BR epoll (7))
 154 and
 155 .BR select (2),
 156 as follows:
 157 .RS
 158 .IP * 3
 159 The file descriptor is readable
 160 (the
 161 .BR select (2)
 162 .I readfds
 163 argument; the
 164 .BR poll (2)
 165 .B POLLIN
 166 flag)
 167 if the counter has a value greater than 0.
 168 .IP *
 169 The file descriptor is writable
 170 (the
 171 .BR select (2)
 172 .I writefds
 173 argument; 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 *
 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^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 .PP
 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 VERSIONS
 254 .BR eventfd ()
 255 is available on Linux since kernel 2.6.22.
 256 Working support is provided in glibc since version 2.8.
 257 .\" eventfd() is in glibc 2.7, but reportedly does not build
 258 The
 259 .BR eventfd2 ()
 260 system call (see NOTES) is available on Linux since kernel 2.6.27.
 261 Since version 2.9, the glibc
 262 .BR eventfd ()
 263 wrapper will employ the
 264 .BR eventfd2 ()
 265 system call, if it is supported by the kernel.
 266 .SH ATTRIBUTES
 267 For an explanation of the terms used in this section, see
 268 .BR attributes (7).
 269 .TS
 270 allbox;
 271 lb lb lb
 272 l l l.
 273 Interface       Attribute       Value
 274 T{
 275 .BR eventfd ()
 276 T}      Thread safety   MT-Safe
 277 .TE
 278 .sp 1
 279 .SH CONFORMING TO
 280 .BR eventfd ()
 281 and
 282 .BR eventfd2 ()
 283 are Linux-specific.
 284 .SH NOTES
 285 Applications can use an eventfd file descriptor instead of a pipe (see
 286 .BR pipe (2))
 287 in all cases where a pipe is used simply to signal events.
 288 The kernel overhead of an eventfd file descriptor
 289 is much lower than that of a pipe,
 290 and only one file descriptor is
 291 required (versus the two required for a pipe).
 292 .PP
 293 When used in the kernel, an eventfd
 294 file descriptor can provide a bridge from kernel to user space, allowing,
 295 for example, functionalities like KAIO (kernel AIO)
 296 .\" or eventually syslets/threadlets
 297 to signal to a file descriptor that some operation is complete.
 298 .PP
 299 A key point about an eventfd file descriptor is that it can be
 300 monitored just like any other file descriptor using
 301 .BR select (2),
 302 .BR poll (2),
 303 or
 304 .BR epoll (7).
 305 This means that an application can simultaneously monitor the
 306 readiness of "traditional" files and the readiness of other
 307 kernel mechanisms that support the eventfd interface.
 308 (Without the
 309 .BR eventfd ()
 310 interface, these mechanisms could not be multiplexed via
 311 .BR select (2),
 312 .BR poll (2),
 313 or
 314 .BR epoll (7).)
 315 .PP
 316 The current value of an eventfd counter can be viewed
 317 via the entry for the corresponding file descriptor in the process's
 318 .IR /proc/[pid]/fdinfo
 319 directory.
 320 See
 321 .BR proc (5)
 322 for further details.
 323 .\"
 324 .SS C library/kernel differences
 325 There are two underlying Linux system calls:
 326 .BR eventfd ()
 327 and the more recent
 328 .BR eventfd2 ().
 329 The former system call does not implement a
 330 .I flags
 331 argument.
 332 The latter system call implements the
 333 .I flags
 334 values described above.
 335 The glibc wrapper function will use
 336 .BR eventfd2 ()
 337 where it is available.
 338 .SS Additional glibc features
 339 The GNU C library defines an additional type,
 340 and two functions that attempt to abstract some of the details of
 341 reading and writing on an eventfd file descriptor:
 342 .PP
 343 .in +4n
 344 .EX
 345 typedef uint64_t eventfd_t;
 346
 347 int eventfd_read(int fd, eventfd_t *value);
 348 int eventfd_write(int fd, eventfd_t value);
 349 .EE
 350 .in
 351 .PP
 352 The functions perform the read and write operations on an
 353 eventfd file descriptor,
 354 returning 0 if the correct number of bytes was transferred,
 355 or \-1 otherwise.
 356 .SH EXAMPLE
 357 .PP
 358 The following program creates an eventfd file descriptor
 359 and then forks to create a child process.
 360 While the parent briefly sleeps,
 361 the child writes each of the integers supplied in the program's
 362 command-line arguments to the eventfd file descriptor.
 363 When the parent has finished sleeping,
 364 it reads from the eventfd file descriptor.
 365 .PP
 366 The following shell session shows a sample run of the program:
 367 .PP
 368 .in +4n
 369 .EX
 370 .RB "$" " ./a.out 1 2 4 7 14"
 371 Child writing 1 to efd
 372 Child writing 2 to efd
 373 Child writing 4 to efd
 374 Child writing 7 to efd
 375 Child writing 14 to efd
 376 Child completed write loop
 377 Parent about to read
 378 Parent read 28 (0x1c) from efd
 379 .EE
 380 .in
 381 .SS Program source
 382 \&
 383 .EX
 384 #include <sys/eventfd.h>
 385 #include <unistd.h>
 386 #include <stdlib.h>
 387 #include <stdio.h>
 388 #include <stdint.h>             /* Definition of uint64_t */
 389
 390 #define handle_error(msg) \\
 391     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 392
 393 int
 394 main(int argc, char *argv[])
 395 {
 396     int efd, j;
 397     uint64_t u;
 398     ssize_t s;
 399
 400     if (argc < 2) {
 401         fprintf(stderr, "Usage: %s <num>...\\n", argv[0]);
 402         exit(EXIT_FAILURE);
 403     }
 404
 405     efd = eventfd(0, 0);
 406     if (efd == \-1)
 407         handle_error("eventfd");
 408
 409     switch (fork()) {
 410     case 0:
 411         for (j = 1; j < argc; j++) {
 412             printf("Child writing %s to efd\\n", argv[j]);
 413             u = strtoull(argv[j], NULL, 0);
 414                     /* strtoull() allows various bases */
 415             s = write(efd, &u, sizeof(uint64_t));
 416             if (s != sizeof(uint64_t))
 417                 handle_error("write");
 418         }
 419         printf("Child completed write loop\\n");
 420
 421         exit(EXIT_SUCCESS);
 422
 423     default:
 424         sleep(2);
 425
 426         printf("Parent about to read\\n");
 427         s = read(efd, &u, sizeof(uint64_t));
 428         if (s != sizeof(uint64_t))
 429             handle_error("read");
 430         printf("Parent read %llu (0x%llx) from efd\\n",
 431                 (unsigned long long) u, (unsigned long long) u);
 432         exit(EXIT_SUCCESS);
 433
 434     case \-1:
 435         handle_error("fork");
 436     }
 437 }
 438 .EE
 439 .SH SEE ALSO
 440 .BR futex (2),
 441 .BR pipe (2),
 442 .BR poll (2),
 443 .BR read (2),
 444 .BR select (2),
 445 .BR signalfd (2),
 446 .BR timerfd_create (2),
 447 .BR write (2),
 448 .BR epoll (7),
 449 .BR sem_overview (7)