EVENTFD(2) System Calls Manual EVENTFD(2)

eventfd, eventfd_read, eventfd_write — create and interact with a counting event descriptor

#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);

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 () 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:

This is an alias for the O_CLOEXEC flag; see open(2) for more information.
This is an alias for the O_NONBLOCK flag; see open(2) for more information.
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 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 () and () 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.

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.

The eventfd() system call fails if:

[]
Flags other than EFD_CLOEXEC, EFD_NONBLOCK, and EFD_SEMAPHORE are set in the flags argument.
[]
The per-process descriptor table is full.
[]
The system file table is full.

The eventfd_read() function fails if:

[]
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:

[]
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.
[]
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:

[]
The size of the buffer is less than 8 bytes (the size required to hold an unsigned 64-bit integer).

close(2), kevent(2), open(2), poll(2), read(2), select(2), write(2)

The 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 11.0