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