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_CLOEXEC
O_CLOEXEC
flag; see
open(2) for more
information.EFD_NONBLOCK
O_NONBLOCK
flag; see
open(2) for more
information.EFD_SEMAPHORE
Reads 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.1 |