Debian Codegraph @

upstream/debian-trixie/man2/eventfd.2

raw
1 '\" t
2 .\" Copyright (C) 2008 Michael Kerrisk <[email protected]>
3 .\" starting from a version by Davide Libenzi <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .\" 2008-10-10, mtk: describe eventfd2(), and EFD_NONBLOCK and EFD_CLOEXEC
8 .\"
9 .TH eventfd 2 2024-06-15 "Linux man-pages 6.9.1"
10 .SH NAME
11 eventfd \- create a file descriptor for event notification
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ", " \-lc )
15 .SH SYNOPSIS
16 .nf
17 .B #include <sys/eventfd.h>
18 .P
19 .BI "int eventfd(unsigned int " initval ", int " flags );
20 .fi
21 .SH DESCRIPTION
22 .BR eventfd ()
23 creates an "eventfd object" that can be used as
24 an event wait/notify mechanism by user-space applications,
25 and by the kernel to notify user-space applications of events.
26 The object contains an unsigned 64-bit integer
27 .RI ( uint64_t )
28 counter that is maintained by the kernel.
29 This counter is initialized with the value specified in the argument
30 .IR initval .
31 .P
32 As its return value,
33 .BR eventfd ()
34 returns a new file descriptor that can be used to refer to the
35 eventfd object.
36 .P
37 The following values may be bitwise ORed in
38 .I flags
39 to change the behavior of
40 .BR eventfd ():
41 .TP
42 .BR EFD_CLOEXEC " (since Linux 2.6.27)"
43 Set the close-on-exec
44 .RB ( FD_CLOEXEC )
45 flag on the new file descriptor.
46 See the description of the
47 .B O_CLOEXEC
48 flag in
49 .BR open (2)
50 for reasons why this may be useful.
51 .TP
52 .BR EFD_NONBLOCK " (since Linux 2.6.27)"
53 Set the
54 .B O_NONBLOCK
55 file status flag on the open file description (see
56 .BR open (2))
57 referred to by the new file descriptor.
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 .P
66 Up to Linux 2.6.26, the
67 .I flags
68 argument is unused, and must be specified as zero.
69 .P
70 The following operations can be performed on the file descriptor returned by
71 .BR eventfd ():
72 .TP
73 .BR read (2)
74 Each successful
75 .BR read (2)
76 returns an 8-byte integer.
77 A
78 .BR read (2)
79 fails with the error
80 .B EINVAL
81 if the size of the supplied buffer is less than 8 bytes.
82 .IP
83 The value returned by
84 .BR read (2)
85 is in host byte order\[em]that is,
86 the native byte order for integers on the host machine.
87 .IP
88 The semantics of
89 .BR read (2)
90 depend on whether the eventfd counter currently has a nonzero value
91 and whether the
92 .B EFD_SEMAPHORE
93 flag was specified when creating the eventfd file descriptor:
94 .RS
95 .IP \[bu] 3
96 If
97 .B EFD_SEMAPHORE
98 was not specified and the eventfd counter has a nonzero value, then a
99 .BR read (2)
100 returns 8 bytes containing that value,
101 and the counter's value is reset to zero.
102 .IP \[bu]
103 If
104 .B EFD_SEMAPHORE
105 was specified and the eventfd counter has a nonzero value, then a
106 .BR read (2)
107 returns 8 bytes containing the value 1,
108 and the counter's value is decremented by 1.
109 .IP \[bu]
110 If the eventfd counter is zero at the time of the call to
111 .BR read (2),
112 then the call either blocks until the counter becomes nonzero
113 (at which time, the
114 .BR read (2)
115 proceeds as described above)
116 or fails with the error
117 .B EAGAIN
118 if the file descriptor has been made nonblocking.
119 .RE
120 .TP
121 .BR write (2)
122 A
123 .BR write (2)
124 call adds the 8-byte integer value supplied in its
125 buffer to the counter.
126 The maximum value that may be stored in the counter is the largest
127 unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe).
128 If the addition would cause the counter's value to exceed
129 the maximum, then the
130 .BR write (2)
131 either blocks until a
132 .BR read (2)
133 is performed on the file descriptor,
134 or fails with the error
135 .B EAGAIN
136 if the file descriptor has been made nonblocking.
137 .IP
138 A
139 .BR write (2)
140 fails with the error
141 .B EINVAL
142 if the size of the supplied buffer is less than 8 bytes,
143 or if an attempt is made to write the value 0xffffffffffffffff.
144 .TP
145 .BR poll (2)
146 .TQ
147 .BR select (2)
148 .TQ
149 (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 \[bu] 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 \[bu]
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 \[bu]
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\[ha]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 .P
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 ATTRIBUTES
254 For an explanation of the terms used in this section, see
255 .BR attributes (7).
256 .TS
257 allbox;
258 lbx lb lb
259 l l l.
260 Interface Attribute Value
261 T{
262 .na
263 .nh
264 .BR eventfd ()
265 T} Thread safety MT-Safe
266 .TE
267 .SH VERSIONS
268 .SS C library/kernel differences
269 There are two underlying Linux system calls:
270 .BR eventfd ()
271 and the more recent
272 .BR eventfd2 ().
273 The former system call does not implement a
274 .I flags
275 argument.
276 The latter system call implements the
277 .I flags
278 values described above.
279 The glibc wrapper function will use
280 .BR eventfd2 ()
281 where it is available.
282 .SS Additional glibc features
283 The GNU C library defines an additional type,
284 and two functions that attempt to abstract some of the details of
285 reading and writing on an eventfd file descriptor:
286 .P
287 .in +4n
288 .EX
289 typedef uint64_t eventfd_t;
290 \&
291 int eventfd_read(int fd, eventfd_t *value);
292 int eventfd_write(int fd, eventfd_t value);
293 .EE
294 .in
295 .P
296 The functions perform the read and write operations on an
297 eventfd file descriptor,
298 returning 0 if the correct number of bytes was transferred,
299 or \-1 otherwise.
300 .SH STANDARDS
301 Linux, GNU.
302 .SH HISTORY
303 .TP
304 .BR eventfd ()
305 Linux 2.6.22,
306 glibc 2.8.
307 .\" eventfd() is in glibc 2.7, but reportedly does not build
308 .TP
309 .BR eventfd2 ()
310 Linux 2.6.27 (see VERSIONS).
311 Since glibc 2.9, the
312 .BR eventfd ()
313 wrapper will employ the
314 .BR eventfd2 ()
315 system call, if it is supported by the kernel.
316 .SH NOTES
317 Applications can use an eventfd file descriptor instead of a pipe (see
318 .BR pipe (2))
319 in all cases where a pipe is used simply to signal events.
320 The kernel overhead of an eventfd file descriptor
321 is much lower than that of a pipe,
322 and only one file descriptor is
323 required (versus the two required for a pipe).
324 .P
325 When used in the kernel, an eventfd
326 file descriptor can provide a bridge from kernel to user space, allowing,
327 for example, functionalities like KAIO (kernel AIO)
328 .\" or eventually syslets/threadlets
329 to signal to a file descriptor that some operation is complete.
330 .P
331 A key point about an eventfd file descriptor is that it can be
332 monitored just like any other file descriptor using
333 .BR select (2),
334 .BR poll (2),
335 or
336 .BR epoll (7).
337 This means that an application can simultaneously monitor the
338 readiness of "traditional" files and the readiness of other
339 kernel mechanisms that support the eventfd interface.
340 (Without the
341 .BR eventfd ()
342 interface, these mechanisms could not be multiplexed via
343 .BR select (2),
344 .BR poll (2),
345 or
346 .BR epoll (7).)
347 .P
348 The current value of an eventfd counter can be viewed
349 via the entry for the corresponding file descriptor in the process's
350 .IR /proc/ pid /fdinfo
351 directory.
352 See
353 .BR proc (5)
354 for further details.
355 .SH EXAMPLES
356 The following program creates an eventfd file descriptor
357 and then forks to create a child process.
358 While the parent briefly sleeps,
359 the child writes each of the integers supplied in the program's
360 command-line arguments to the eventfd file descriptor.
361 When the parent has finished sleeping,
362 it reads from the eventfd file descriptor.
363 .P
364 The following shell session shows a sample run of the program:
365 .P
366 .in +4n
367 .EX
368 .RB "$" " ./a.out 1 2 4 7 14"
369 Child writing 1 to efd
370 Child writing 2 to efd
371 Child writing 4 to efd
372 Child writing 7 to efd
373 Child writing 14 to efd
374 Child completed write loop
375 Parent about to read
376 Parent read 28 (0x1c) from efd
377 .EE
378 .in
379 .SS Program source
380 \&
381 .\" SRC BEGIN (eventfd.c)
382 .EX
383 #include <err.h>
384 #include <inttypes.h>
385 #include <stdio.h>
386 #include <stdlib.h>
387 #include <sys/eventfd.h>
388 #include <sys/types.h>
389 #include <unistd.h>
390 \&
391 int
392 main(int argc, char *argv[])
393 {
394 int efd;
395 uint64_t u;
396 ssize_t s;
397 \&
398 if (argc < 2) {
399 fprintf(stderr, "Usage: %s <num>...\[rs]n", argv[0]);
400 exit(EXIT_FAILURE);
401 }
402 \&
403 efd = eventfd(0, 0);
404 if (efd == \-1)
405 err(EXIT_FAILURE, "eventfd");
406 \&
407 switch (fork()) {
408 case 0:
409 for (size_t j = 1; j < argc; j++) {
410 printf("Child writing %s to efd\[rs]n", argv[j]);
411 u = strtoull(argv[j], NULL, 0);
412 /* strtoull() allows various bases */
413 s = write(efd, &u, sizeof(uint64_t));
414 if (s != sizeof(uint64_t))
415 err(EXIT_FAILURE, "write");
416 }
417 printf("Child completed write loop\[rs]n");
418 \&
419 exit(EXIT_SUCCESS);
420 \&
421 default:
422 sleep(2);
423 \&
424 printf("Parent about to read\[rs]n");
425 s = read(efd, &u, sizeof(uint64_t));
426 if (s != sizeof(uint64_t))
427 err(EXIT_FAILURE, "read");
428 printf("Parent read %"PRIu64" (%#"PRIx64") from efd\[rs]n", u, u);
429 exit(EXIT_SUCCESS);
430 \&
431 case \-1:
432 err(EXIT_FAILURE, "fork");
433 }
434 }
435 .EE
436 .\" SRC END
437 .SH SEE ALSO
438 .BR futex (2),
439 .BR pipe (2),
440 .BR poll (2),
441 .BR read (2),
442 .BR select (2),
443 .BR signalfd (2),
444 .BR timerfd_create (2),
445 .BR write (2),
446 .BR epoll (7),
447 .BR sem_overview (7)