Updated: 2022/Sep/29
Please read Privacy Policy. It's for your privacy.
EVENTFD(2) System Calls Manual EVENTFD(2)
NAME
eventfd, eventfd_read, eventfd_write - create and interact with a
counting event descriptor
SYNOPSIS
#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);
DESCRIPTION
The 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 This is an alias for the O_CLOEXEC flag; see open(2) for
more information.
EFD_NONBLOCK This is an alias for the O_NONBLOCK flag; see open(2) for
more information.
EFD_SEMAPHORE
Creates a "semaphore mode" object; see below for details.
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":
⊕ If the eventfd object was created in "semaphore mode", reads return
the value 1 and object's counter is decremented by 1.
⊕ If the 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)
Reads the unsigned 64-bit integer value of the eventfd
object and returns it in valp.
eventfd_write(efd, val)
Writes the unsigned 64-bit integer value val to the
eventfd object.
RETURN VALUES
The 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.
ERRORS
The eventfd() system call fails if:
[EINVAL] Flags other than EFD_CLOEXEC, EFD_NONBLOCK, and
EFD_SEMAPHORE are set in the flags argument.
[EMFILE] The per-process descriptor table is full.
[ENFILE] The system file table is full.
The eventfd_read() function fails if:
[EAGAIN] The value of the eventfd object is 0 and the eventfd
object is set for non-blocking I/O.
The eventfd_write() function fails if:
[EAGAIN] The resulting value of the 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] An attempt was made to write a value greater than the
maximum value.
In addition to the errors returned by eventfd_read() and eventfd_write(),
a read from or write to an eventfd object fails if:
[EINVAL] The size of the buffer is less than 8 bytes (the size
required to hold an unsigned 64-bit integer).
SEE ALSO
close(2), kevent(2), open(2), poll(2), read(2), select(2), write(2)
HISTORY
The eventfd interface first appeared in NetBSD 10. It is compatible with
the eventfd interface that appeared in Linux 2.6.30.
NetBSD 10.99 September 17, 2021 NetBSD 10.99