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.

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.