1EVENTFD(2)                 Linux Programmer's Manual                EVENTFD(2)
2
3
4

NAME

6       eventfd - create a file descriptor for event notification
7

SYNOPSIS

9       #include <sys/eventfd.h>
10
11       int eventfd(unsigned int initval, int flags);
12

DESCRIPTION

14       eventfd()  creates  an  "eventfd  object"  that can be used as an event
15       wait/notify mechanism by user-space applications, and by the kernel  to
16       notify  user-space  applications  of  events.   The  object contains an
17       unsigned 64-bit integer (uint64_t) counter that is  maintained  by  the
18       kernel.   This  counter  is initialized with the value specified in the
19       argument initval.
20
21       As its return value, eventfd() returns a new file descriptor  that  can
22       be used to refer to the eventfd object.
23
24       The  following values may be bitwise ORed in flags to change the behav‐
25       ior of eventfd():
26
27       EFD_CLOEXEC (since Linux 2.6.27)
28              Set the close-on-exec (FD_CLOEXEC) flag on the new file descrip‐
29              tor.   See  the description of the O_CLOEXEC flag in open(2) for
30              reasons why this may be useful.
31
32       EFD_NONBLOCK (since Linux 2.6.27)
33              Set the O_NONBLOCK file status flag on the open file description
34              (see  open(2))  referred  to  by the new file descriptor.  Using
35              this flag saves extra calls to  fcntl(2)  to  achieve  the  same
36              result.
37
38       EFD_SEMAPHORE (since Linux 2.6.30)
39              Provide  semaphore-like  semantics  for  reads from the new file
40              descriptor.  See below.
41
42       In Linux up to version 2.6.26, the flags argument is unused,  and  must
43       be specified as zero.
44
45       The  following  operations  can  be  performed  on  the file descriptor
46       returned by eventfd():
47
48       read(2)
49              Each successful read(2) returns an 8-byte  integer.   A  read(2)
50              fails  with  the error EINVAL if the size of the supplied buffer
51              is less than 8 bytes.
52
53              The value returned by read(2) is in host byte order—that is, the
54              native byte order for integers on the host machine.
55
56              The  semantics  of read(2) depend on whether the eventfd counter
57              currently has a nonzero value and whether the EFD_SEMAPHORE flag
58              was specified when creating the eventfd file descriptor:
59
60              *  If  EFD_SEMAPHORE  was  not specified and the eventfd counter
61                 has a nonzero value, then a read(2) returns 8 bytes  contain‐
62                 ing that value, and the counter's value is reset to zero.
63
64              *  If  EFD_SEMAPHORE was specified and the eventfd counter has a
65                 nonzero value, then a read(2) returns 8 bytes containing  the
66                 value 1, and the counter's value is decremented by 1.
67
68              *  If  the  eventfd  counter  is zero at the time of the call to
69                 read(2), then  the  call  either  blocks  until  the  counter
70                 becomes  nonzero  (at  which  time,  the  read(2) proceeds as
71                 described above) or fails with the error EAGAIN if  the  file
72                 descriptor has been made nonblocking.
73
74       write(2)
75              A  write(2)  call  adds the 8-byte integer value supplied in its
76              buffer to the counter.  The maximum value that may be stored  in
77              the  counter is the largest unsigned 64-bit value minus 1 (i.e.,
78              0xfffffffffffffffe).  If the addition would cause the  counter's
79              value  to  exceed  the  maximum, then the write(2) either blocks
80              until a read(2) is performed on the file  descriptor,  or  fails
81              with  the error EAGAIN if the file descriptor has been made non‐
82              blocking.
83
84              A write(2) fails with the error EINVAL if the size of  the  sup‐
85              plied  buffer  is less than 8 bytes, or if an attempt is made to
86              write the value 0xffffffffffffffff.
87
88       poll(2), select(2) (and similar)
89              The returned file descriptor supports poll(2)  (and  analogously
90              epoll(7)) and select(2), as follows:
91
92              *  The  file descriptor is readable (the select(2) readfds argu‐
93                 ment; the poll(2) POLLIN flag) if the  counter  has  a  value
94                 greater than 0.
95
96              *  The file descriptor is writable (the select(2) writefds argu‐
97                 ment; the poll(2) POLLOUT flag) if it is possible to write  a
98                 value of at least "1" without blocking.
99
100              *  If  an  overflow  of  the  counter  value  was detected, then
101                 select(2) indicates the file descriptor as being  both  read‐
102                 able  and  writable, and poll(2) returns a POLLERR event.  As
103                 noted above, write(2) can never overflow the  counter.   How‐
104                 ever  an  overflow  can  occur if 2^64 eventfd "signal posts"
105                 were performed by the KAIO subsystem (theoretically possible,
106                 but practically unlikely).  If an overflow has occurred, then
107                 read(2)  will  return  that  maximum  uint64_t  value  (i.e.,
108                 0xffffffffffffffff).
109
110              The  eventfd  file  descriptor  also  supports  the  other file-
111              descriptor multiplexing APIs: pselect(2) and ppoll(2).
112
113       close(2)
114              When the file descriptor is no  longer  required  it  should  be
115              closed.   When  all  file  descriptors  associated with the same
116              eventfd object have been closed, the resources  for  object  are
117              freed by the kernel.
118
119       A  copy of the file descriptor created by eventfd() is inherited by the
120       child produced by fork(2).  The duplicate file descriptor is associated
121       with  the  same  eventfd object.  File descriptors created by eventfd()
122       are preserved across execve(2), unless the close-on-exec flag has  been
123       set.
124

RETURN VALUE

126       On success, eventfd() returns a new eventfd file descriptor.  On error,
127       -1 is returned and errno is set to indicate the error.
128

ERRORS

130       EINVAL An unsupported value was specified in flags.
131
132       EMFILE The per-process limit on the number of open file descriptors has
133              been reached.
134
135       ENFILE The system-wide limit on the total number of open files has been
136              reached.
137
138       ENODEV Could not mount (internal) anonymous inode device.
139
140       ENOMEM There was insufficient memory  to  create  a  new  eventfd  file
141              descriptor.
142

VERSIONS

144       eventfd()  is  available on Linux since kernel 2.6.22.  Working support
145       is provided in glibc since version 2.8.   The  eventfd2()  system  call
146       (see  NOTES)  is available on Linux since kernel 2.6.27.  Since version
147       2.9, the glibc eventfd() wrapper  will  employ  the  eventfd2()  system
148       call, if it is supported by the kernel.
149

ATTRIBUTES

151       For   an   explanation   of   the  terms  used  in  this  section,  see
152       attributes(7).
153
154       ┌──────────┬───────────────┬─────────┐
155Interface Attribute     Value   
156       ├──────────┼───────────────┼─────────┤
157eventfd() │ Thread safety │ MT-Safe │
158       └──────────┴───────────────┴─────────┘
159

CONFORMING TO

161       eventfd() and eventfd2() are Linux-specific.
162

NOTES

164       Applications can use an eventfd file descriptor instead of a pipe  (see
165       pipe(2))  in  all  cases  where a pipe is used simply to signal events.
166       The kernel overhead of an eventfd file descriptor is  much  lower  than
167       that  of  a  pipe, and only one file descriptor is required (versus the
168       two required for a pipe).
169
170       When used in the kernel, an  eventfd  file  descriptor  can  provide  a
171       bridge  from  kernel to user space, allowing, for example, functionali‐
172       ties like KAIO (kernel AIO) to signal to a file  descriptor  that  some
173       operation is complete.
174
175       A  key  point  about an eventfd file descriptor is that it can be moni‐
176       tored just like any other file descriptor using select(2), poll(2),  or
177       epoll(7).   This  means  that an application can simultaneously monitor
178       the readiness of "traditional" files and the readiness of other  kernel
179       mechanisms  that support the eventfd interface.  (Without the eventfd()
180       interface, these mechanisms could not  be  multiplexed  via  select(2),
181       poll(2), or epoll(7).)
182
183       The current value of an eventfd counter can be viewed via the entry for
184       the corresponding file descriptor in the  process's  /proc/[pid]/fdinfo
185       directory.  See proc(5) for further details.
186
187   C library/kernel differences
188       There  are  two  underlying  Linux system calls: eventfd() and the more
189       recent eventfd2().  The former system call does not implement  a  flags
190       argument.  The latter system call implements the flags values described
191       above.  The glibc wrapper function will  use  eventfd2()  where  it  is
192       available.
193
194   Additional glibc features
195       The  GNU  C  library defines an additional type, and two functions that
196       attempt to abstract some of the details of reading and  writing  on  an
197       eventfd file descriptor:
198
199           typedef uint64_t eventfd_t;
200
201           int eventfd_read(int fd, eventfd_t *value);
202           int eventfd_write(int fd, eventfd_t value);
203
204       The  functions perform the read and write operations on an eventfd file
205       descriptor, returning 0 if the correct number of bytes was transferred,
206       or -1 otherwise.
207

EXAMPLE

209       The following program creates an eventfd file descriptor and then forks
210       to create a child process.  While the parent briefly sleeps, the  child
211       writes  each  of  the  integers  supplied in the program's command-line
212       arguments to the eventfd file descriptor.  When the parent has finished
213       sleeping, it reads from the eventfd file descriptor.
214
215       The following shell session shows a sample run of the program:
216
217           $ ./a.out 1 2 4 7 14
218           Child writing 1 to efd
219           Child writing 2 to efd
220           Child writing 4 to efd
221           Child writing 7 to efd
222           Child writing 14 to efd
223           Child completed write loop
224           Parent about to read
225           Parent read 28 (0x1c) from efd
226
227   Program source
228
229       #include <sys/eventfd.h>
230       #include <unistd.h>
231       #include <stdlib.h>
232       #include <stdio.h>
233       #include <stdint.h>             /* Definition of uint64_t */
234
235       #define handle_error(msg) \
236           do { perror(msg); exit(EXIT_FAILURE); } while (0)
237
238       int
239       main(int argc, char *argv[])
240       {
241           int efd, j;
242           uint64_t u;
243           ssize_t s;
244
245           if (argc < 2) {
246               fprintf(stderr, "Usage: %s <num>...\n", argv[0]);
247               exit(EXIT_FAILURE);
248           }
249
250           efd = eventfd(0, 0);
251           if (efd == -1)
252               handle_error("eventfd");
253
254           switch (fork()) {
255           case 0:
256               for (j = 1; j < argc; j++) {
257                   printf("Child writing %s to efd\n", argv[j]);
258                   u = strtoull(argv[j], NULL, 0);
259                           /* strtoull() allows various bases */
260                   s = write(efd, &u, sizeof(uint64_t));
261                   if (s != sizeof(uint64_t))
262                       handle_error("write");
263               }
264               printf("Child completed write loop\n");
265
266               exit(EXIT_SUCCESS);
267
268           default:
269               sleep(2);
270
271               printf("Parent about to read\n");
272               s = read(efd, &u, sizeof(uint64_t));
273               if (s != sizeof(uint64_t))
274                   handle_error("read");
275               printf("Parent read %llu (0x%llx) from efd\n",
276                       (unsigned long long) u, (unsigned long long) u);
277               exit(EXIT_SUCCESS);
278
279           case -1:
280               handle_error("fork");
281           }
282       }
283

SEE ALSO

285       futex(2),    pipe(2),   poll(2),   read(2),   select(2),   signalfd(2),
286       timerfd_create(2), write(2), epoll(7), sem_overview(7)
287

COLOPHON

289       This page is part of release 5.02 of the Linux  man-pages  project.   A
290       description  of  the project, information about reporting bugs, and the
291       latest    version    of    this    page,    can     be     found     at
292       https://www.kernel.org/doc/man-pages/.
293
294
295
296Linux                             2019-03-06                        EVENTFD(2)
Impressum