EVENTFD(2)

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.

September 17, 2021 | NetBSD 11.0