original/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 .\" This program is free software; you can redistribute it and/or modify
   5 .\" it under the terms of the GNU General Public License as published by
   6 .\" the Free Software Foundation; either version 2 of the License, or
   7 .\" (at your option) any later version.
   8 .\"
   9 .\" This program is distributed in the hope that it will be useful,
  10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 .\" GNU General Public License for more details.
  13 .\"
  14 .\" You should have received a copy of the GNU General Public License
  15 .\" along with this program; if not, write to the Free Software
  16 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  17 .\" MA  02111-1307  USA
  18 .\"
  19 .\" 2008-10-10, mtk: describe eventfd2(), and EFD_NONBLOCK and EFD_CLOEXEC
  20 .\"
  21 .TH EVENTFD 2 2010-08-30 Linux "Linux Programmer's Manual"
  22 .SH NAME
  23 eventfd \- create a file descriptor for event notification
  24 .SH SYNOPSIS
  25 .B #include <sys/eventfd.h>
  26 .sp
  27 .BI "int eventfd(unsigned int " initval ", int " flags );
  28 .SH DESCRIPTION
  29 .BR eventfd ()
  30 creates an "eventfd object" that can be used as
  31 an event wait/notify mechanism by userspace applications,
  32 and by the kernel to notify userspace applications of events.
  33 The object contains an unsigned 64-bit integer
  34 .RI ( uint64_t )
  35 counter that is maintained by the kernel.
  36 This counter is initialized with the value specified in the argument
  37 .IR initval .
  38
  39 The following values may be bitwise ORed in
  40 .IR flags
  41 to change the behaviour of
  42 .BR eventfd ():
  43 .TP
  44 .BR EFD_CLOEXEC " (since Linux 2.6.27)"
  45 Set the close-on-exec
  46 .RB ( FD_CLOEXEC )
  47 flag on the new file descriptor.
  48 See the description of the
  49 .B O_CLOEXEC
  50 flag in
  51 .BR open (2)
  52 for reasons why this may be useful.
  53 .TP
  54 .BR EFD_NONBLOCK " (since Linux 2.6.27)"
  55 Set the
  56 .BR O_NONBLOCK
  57 file status flag on the new open file description.
  58 Using this flag saves extra calls to
  59 .BR fcntl (2)
  60 to achieve the same result.
  61 .TP
  62 .BR EFD_SEMAPHORE " (since Linux 2.6.30)"
  63 Provide semaphore-like semantics for reads from the new file descriptor.
  64 See below.
  65 .PP
  66 In Linux up to version 2.6.26, the
  67 .I flags
  68 argument is unused, and must be specified as zero.
  69
  70 As its return value,
  71 .BR eventfd ()
  72 returns a new file descriptor that can be used to refer to the
  73 eventfd object.
  74 The following operations can be performed on the file descriptor:
  75 .TP
  76 .BR read (2)
  77 Each successful
  78 .BR read (2)
  79 returns an 8-byte integer.
  80 A
  81 .BR read (2)
  82 will fail with the error
  83 .B EINVAL
  84 if the size of the supplied buffer is less than 8 bytes.
  85 .IP
  86 The value returned by
  87 .BR read (2)
  88 is in host byte order,
  89 i.e., the native byte order for integers on the host machine.
  90 .IP
  91 The semantics of
  92 .BR read (2)
  93 depend on whether the eventfd counter currently has a nonzero value
  94 and whether the
  95 .BR EFD_SEMAPHORE
  96 flag was specified when creating the eventfd file descriptor:
  97 .RS
  98 .IP * 3
  99 If
 100 .BR EFD_SEMAPHORE
 101 was not specified and the eventfd counter has a nonzero value, then a
 102 .BR read (2)
 103 returns 8 bytes containing that value,
 104 and the counter's value is reset to zero.
 105 .IP *
 106 If
 107 .BR EFD_SEMAPHORE
 108 was specified and the eventfd counter has a nonzero value, then a
 109 .BR read (2)
 110 returns 8 bytes containing the value 1,
 111 and the counter's value is decremented by 1.
 112 .IP *
 113 If the eventfd counter is zero at the time of the call to
 114 .BR read (2),
 115 then the call either blocks until the counter becomes nonzero
 116 (at which time, the
 117 .BR read (2)
 118 proceeds as described above)
 119 or fails with the error
 120 .B EAGAIN
 121 if the file descriptor has been made nonblocking.
 122 .RE
 123 .TP
 124 .BR write (2)
 125 A
 126 .BR write (2)
 127 call adds the 8-byte integer value supplied in its
 128 buffer to the counter.
 129 The maximum value that may be stored in the counter is the largest
 130 unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe).
 131 If the addition would cause the counter's value to exceed
 132 the maximum, then the
 133 .BR write (2)
 134 either blocks until a
 135 .BR read (2)
 136 is performed on the file descriptor,
 137 or fails with the error
 138 .B EAGAIN
 139 if the file descriptor has been made nonblocking.
 140 .IP
 141 A
 142 .BR write (2)
 143 will fail with the error
 144 .B EINVAL
 145 if the size of the supplied buffer is less than 8 bytes,
 146 or if an attempt is made to write the value 0xffffffffffffffff.
 147 .TP
 148 .BR poll "(2), " select "(2) (and similar)"
 149 The returned file descriptor supports
 150 .BR poll (2)
 151 (and analogously
 152 .BR epoll (7))
 153 and
 154 .BR select (2),
 155 as follows:
 156 .RS
 157 .IP * 3
 158 The file descriptor is readable
 159 (the
 160 .BR select (2)
 161 .I readfds
 162 argument; the
 163 .BR poll (2)
 164 .B POLLIN
 165 flag)
 166 if the counter has a value greater than 0.
 167 .IP *
 168 The file descriptor is writable
 169 (the
 170 .BR select (2)
 171 .I writefds
 172 argument; the
 173 .BR poll (2)
 174 .B POLLOUT
 175 flag)
 176 if it is possible to write a value of at least "1" without blocking.
 177 .IP *
 178 If an overflow of the counter value was detected,
 179 then
 180 .BR select (2)
 181 indicates the file descriptor as being both readable and writable, and
 182 .BR poll (2)
 183 returns a
 184 .B POLLERR
 185 event.
 186 As noted above,
 187 .BR write (2)
 188 can never overflow the counter.
 189 However an overflow can occur if 2^64
 190 eventfd "signal posts" were performed by the KAIO
 191 subsystem (theoretically possible, but practically unlikely).
 192 If an overflow has occurred, then
 193 .BR read (2)
 194 will return that maximum
 195 .I uint64_t
 196 value (i.e., 0xffffffffffffffff).
 197 .RE
 198 .IP
 199 The eventfd file descriptor also supports the other file-descriptor
 200 multiplexing APIs:
 201 .BR pselect (2),
 202 .BR ppoll (2),
 203 and
 204 .BR epoll (7).
 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 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 CONFORMING TO
 267 .BR eventfd ()
 268 and
 269 .BR eventfd2 ()
 270 are Linux-specific.
 271 .SH NOTES
 272 Applications can use an eventfd file descriptor instead of a pipe (see
 273 .BR pipe (2))
 274 in all cases where a pipe is used simply to signal events.
 275 The kernel overhead of an eventfd file descriptor
 276 is much lower than that of a pipe,
 277 and only one file descriptor is
 278 required (versus the two required for a pipe).
 279
 280 When used in the kernel, an eventfd
 281 file descriptor can provide a kernel-userspace bridge allowing,
 282 for example, functionalities like KAIO (kernel AIO)
 283 .\" or eventually syslets/threadlets
 284 to signal to a file descriptor that some operation is complete.
 285
 286 A key point about an eventfd file descriptor is that it can be
 287 monitored just like any other file descriptor using
 288 .BR select (2),
 289 .BR poll (2),
 290 or
 291 .BR epoll (7).
 292 This means that an application can simultaneously monitor the
 293 readiness of "traditional" files and the readiness of other
 294 kernel mechanisms that support the eventfd interface.
 295 (Without the
 296 .BR eventfd ()
 297 interface, these mechanisms could not be multiplexed via
 298 .BR select (2),
 299 .BR poll (2),
 300 or
 301 .BR epoll (7).)
 302 .SS Underlying Linux system calls
 303 There are two underlying Linux system calls:
 304 .BR eventfd ()
 305 and the more recent
 306 .BR eventfd2 ().
 307 The former system call does not implement a
 308 .I flags
 309 argument.
 310 The latter system call implements the
 311 .I flags
 312 values described above.
 313 The glibc wrapper function will use
 314 .BR eventfd2 ()
 315 where it is available.
 316 .SS Additional glibc features
 317 The GNU C library defines an additional type,
 318 and two functions that attempt to abstract some of the details of
 319 reading and writing on an eventfd file descriptor:
 320 .in +4n
 321 .nf
 322
 323 typedef uint64_t eventfd_t;
 324
 325 int eventfd_read(int fd, eventfd_t *value);
 326 int eventfd_write(int fd, eventfd_t value);
 327 .fi
 328 .in
 329
 330 The functions perform the read and write operations on an
 331 eventfd file descriptor,
 332 returning 0 if the correct number of bytes was transferred,
 333 or \-1 otherwise.
 334 .SH EXAMPLE
 335 .PP
 336 The following program creates an eventfd file descriptor
 337 and then forks to create a child process.
 338 While the parent briefly sleeps,
 339 the child writes each of the integers supplied in the program's
 340 command-line arguments to the eventfd file descriptor.
 341 When the parent has finished sleeping,
 342 it reads from the eventfd file descriptor.
 343
 344 The following shell session shows a sample run of the program:
 345 .in +4n
 346 .nf
 347
 348 .RB "$" " ./a.out 1 2 4 7 14"
 349 Child writing 1 to efd
 350 Child writing 2 to efd
 351 Child writing 4 to efd
 352 Child writing 7 to efd
 353 Child writing 14 to efd
 354 Child completed write loop
 355 Parent about to read
 356 Parent read 28 (0x1c) from efd
 357 .fi
 358 .in
 359 .SS Program source
 360 \&
 361 .nf
 362 #include <sys/eventfd.h>
 363 #include <unistd.h>
 364 #include <stdlib.h>
 365 #include <stdio.h>
 366 #include <stdint.h>             /* Definition of uint64_t */
 367
 368 #define handle_error(msg) \\
 369     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 370
 371 int
 372 main(int argc, char *argv[])
 373 {
 374     int efd, j;
 375     uint64_t u;
 376     ssize_t s;
 377
 378     if (argc < 2) {
 379         fprintf(stderr, "Usage: %s <num>...\\n", argv[0]);
 380         exit(EXIT_FAILURE);
 381     }
 382
 383     efd = eventfd(0, 0);
 384     if (efd == \-1)
 385         handle_error("eventfd");
 386
 387     switch (fork()) {
 388     case 0:
 389         for (j = 1; j < argc; j++) {
 390             printf("Child writing %s to efd\\n", argv[j]);
 391             u = strtoull(argv[j], NULL, 0);
 392                     /* strtoull() allows various bases */
 393             s = write(efd, &u, sizeof(uint64_t));
 394             if (s != sizeof(uint64_t))
 395                 handle_error("write");
 396         }
 397         printf("Child completed write loop\\n");
 398
 399         exit(EXIT_SUCCESS);
 400
 401     default:
 402         sleep(2);
 403
 404         printf("Parent about to read\\n");
 405         s = read(efd, &u, sizeof(uint64_t));
 406         if (s != sizeof(uint64_t))
 407             handle_error("read");
 408         printf("Parent read %llu (0x%llx) from efd\\n",
 409                 (unsigned long long) u, (unsigned long long) u);
 410         exit(EXIT_SUCCESS);
 411
 412     case \-1:
 413         handle_error("fork");
 414     }
 415 }
 416 .fi
 417 .SH "SEE ALSO"
 418 .BR futex (2),
 419 .BR pipe (2),
 420 .BR poll (2),
 421 .BR read (2),
 422 .BR select (2),
 423 .BR signalfd (2),
 424 .BR timerfd_create (2),
 425 .BR write (2),
 426 .BR epoll (7),
 427 .BR sem_overview (7)