| EVENTFD(2) | System Calls Manual | EVENTFD(2) |
eventfd, eventfd_read,
eventfd_write —
#include <sys/eventfd.h>
int
eventfd(unsigned
int val, int
flags);
int
eventfd_read(int
efd, eventfd_t
*valp);
int
eventfd_write(int
efd, eventfd_t
val);
eventfd interface presents a simple counting object
associated with a file descriptor. Writes and reads to this file descriptor
increment and decrement the count, respectively. When the object's value is
non-zero, the file descriptor is considered “readable”, and when
the count is less than the maximum value UINT64_MAX-1
it is considered “writable”. When an
eventfd object is no longer needed, it may be disposed
of using close(2).
All I/O to an eventfd object is
8 bytes in length, which is the space required to store an unsigned
64-bit integer. Any read or write with a buffer smaller than 8 bytes
will fail with EINVAL. Only the first 8 bytes
of the buffer will be used.
The eventfd() function creates a new
counting event object and returns a file descriptor representing that
object. The initial value of the object is specified by the
val argument. The following flags define the behavior
of the resulting object:
EFD_CLOEXECO_CLOEXEC flag; see
open(2) for more
information.EFD_NONBLOCKO_NONBLOCK flag; see
open(2) for more
information.EFD_SEMAPHOREReads from an eventfd object return an
unsigned 64-bit integer in the caller's buffer. The semantics of this value
are dependent on whether the eventfd object was
created in “semaphore mode”:
eventfd object was created in
“semaphore mode”, reads return the value 1 and
object's counter is decremented by 1.eventfd object was not created in
“semaphore mode”, reads return the current value of the
object's counter and reset the counter to 0.If the value of the eventfd object's
counter is 0, then reads will block, unless the
eventfd object is set for non-blocking I/O.
Writing to an eventfd object adds the
unsigned 64-bit value provided in the caller's buffer to the
eventfd object's counter. If adding the specified
value would exceed the maximum value, then the write will block, unless the
eventfd object is set for non-blocking I/O.
The convenience functions eventfd_read()
and eventfd_write() are provided to simplify
interacting with eventfd objects, and are simply
wrappers around the read(2) and
write(2) system calls:
eventfd_read(efd,
valp)eventfd object and returns it in
valp.eventfd_write(efd,
val)eventfd object.eventfd() system call returns -1 if an error
occurs, otherwise the return value is a descriptor representing the
eventfd object.
The eventfd_read() and
eventfd_write() functions return the value 0
if successful; otherwise the value -1 is returned and the global
variable errno is set to indicate the error.
eventfd() system call fails if:
EINVAL]EFD_CLOEXEC,
EFD_NONBLOCK, and
EFD_SEMAPHORE are set in the
flags argument.EMFILE]ENFILE]The eventfd_read() function fails if:
EAGAIN]eventfd object is 0 and
the eventfd object is set for non-blocking
I/O.The eventfd_write() function fails if:
EAGAIN]eventfd object after
adding the value val would exceed the maximum value
UINT64_MAX-1 and the
eventfd object is set for non-blocking I/O.EINVAL]In addition to the errors returned by
eventfd_read() and
eventfd_write(), a read from or write to an
eventfd object fails if:
EINVAL]eventfd interface first appeared in
NetBSD 10. It is compatible with the
eventfd interface that appeared in Linux 2.6.30.
| September 17, 2021 | NetBSD 10.0 |