eventfd_read(3)

1eventfd(2)                    System Calls Manual                   eventfd(2)
2
3
4

NAME

6       eventfd - create a file descriptor for event notification
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/eventfd.h>
13
14       int eventfd(unsigned int initval, int flags);
15

DESCRIPTION

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

RETURN VALUE

129       On success, eventfd() returns a new eventfd file descriptor.  On error,
130       -1 is returned and errno is set to indicate the error.
131

ERRORS

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

ATTRIBUTES

147       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
148       tributes(7).
149
150       ┌────────────────────────────────────────────┬───────────────┬─────────┐
151       │Interface                                   │ Attribute     │ Value   │
152       ├────────────────────────────────────────────┼───────────────┼─────────┤
153       │eventfd()                                   │ Thread safety │ MT-Safe │
154       └────────────────────────────────────────────┴───────────────┴─────────┘
155

VERSIONS

157   C library/kernel differences
158       There are two underlying Linux system calls: eventfd() and the more re‐
159       cent eventfd2().  The former system call does not implement a flags ar‐
160       gument.  The latter system call implements the flags  values  described
161       above.   The  glibc  wrapper  function  will use eventfd2() where it is
162       available.
163
164   Additional glibc features
165       The GNU C library defines an additional type, and  two  functions  that
166       attempt  to  abstract  some of the details of reading and writing on an
167       eventfd file descriptor:
168
169           typedef uint64_t eventfd_t;
170
171           int eventfd_read(int fd, eventfd_t *value);
172           int eventfd_write(int fd, eventfd_t value);
173
174       The functions perform the read and write operations on an eventfd  file
175       descriptor, returning 0 if the correct number of bytes was transferred,
176       or -1 otherwise.
177

STANDARDS

179       Linux, GNU.
180

HISTORY

182       eventfd()
183              Linux 2.6.22, glibc 2.8.
184
185       eventfd2()
186              Linux 2.6.27 (see VERSIONS).  Since  glibc  2.9,  the  eventfd()
187              wrapper  will  employ  the eventfd2() system call, if it is sup‐
188              ported by the kernel.
189

NOTES

191       Applications can use an eventfd file descriptor instead of a pipe  (see
192       pipe(2))  in  all  cases  where a pipe is used simply to signal events.
193       The kernel overhead of an eventfd file descriptor is  much  lower  than
194       that  of  a  pipe, and only one file descriptor is required (versus the
195       two required for a pipe).
196
197       When used in the kernel, an  eventfd  file  descriptor  can  provide  a
198       bridge  from  kernel to user space, allowing, for example, functionali‐
199       ties like KAIO (kernel AIO) to signal to a file  descriptor  that  some
200       operation is complete.
201
202       A  key  point  about an eventfd file descriptor is that it can be moni‐
203       tored just like any other file descriptor using select(2), poll(2),  or
204       epoll(7).   This  means  that an application can simultaneously monitor
205       the readiness of "traditional" files and the readiness of other  kernel
206       mechanisms  that support the eventfd interface.  (Without the eventfd()
207       interface, these mechanisms could not  be  multiplexed  via  select(2),
208       poll(2), or epoll(7).)
209
210       The current value of an eventfd counter can be viewed via the entry for
211       the corresponding file descriptor in the process's /proc/pid/fdinfo di‐
212       rectory.  See proc(5) for further details.
213

EXAMPLES

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