EVENTFD(3C) Standard C Library Functions EVENTFD(3C)

eventfd, eventfd_read, eventfd_write — create a file descriptor for event notification

#include <sys/eventfd.h>

int
eventfd(unsigned int initval, int flags);

int
eventfd_read(int fd, eventfd_t *valp);

int
eventfd_write(int fd, eventfd_t val);

The () function creates an eventfd(7) instance that has an associated 64-bit unsigned counter. It returns a file descriptor that can be operated upon via read(2), write(2) and the facilities that notify of file descriptor activity (e.g., poll(2), port_get(3C), epoll_wait(3C)). To dispose of the instance, close(2) should be called on the file descriptor.

The initval argument specifies the initial value of the 64-bit counter associated with the instance. (Note that this limits the initial value to be a 32-bit quantity despite the fact that the underlying counter is 64-bit).

The flags argument specifies additional parameters for the instance, and can have any of the following values:

Instance will be closed upon an exec(2); see open(2)'s description of O_CLOEXEC.
Instance will be set to be non-blocking. A read(2) on an eventfd instance that has been initialized with EFD_NONBLOCK will return EAGAIN in lieu of blocking if the count associated with the instance is zero.
Provide counting semaphore semantics whereby a read(2) will atomically decrement rather than atomically clear the count when it becomes non-zero. See below for details on read(2) semantics.

The following operations can be performed upon an eventfd instance:

read(2)
Atomically reads and modifies the value of the 64-bit counter associated with the instance. The precise semantics of read(2) depend on the disposition of EFD_SEMAPHORE with respect to the instance: if EFD_SEMAPHORE was set when the instance was created, read(2) will atomically decrement the counter if (and when) it is non-zero, copying the value 1 to the eight byte buffer passed to the system call; if EFD_SEMAPHORE was not set, read(2) will atomically clear the counter if (and when) it is non-zero, copying the former value of the counter to the eight byte buffer passed to the system call. In either case, read(2) will block if the counter is zero (or return EAGAIN if the instance was created with EFD_NONBLOCK). If the buffer specified to read(2) is less than eight bytes in length, EINVAL will be returned.
write(2)
Atomically adds the 64-bit value pointed to by the buffer to the 64-bit counter associated with the instance. If the resulting value would overflow, the write(2) will block until the value would not overflow (or return EAGAIN if the instance was created with EFD_NONBLOCK). If the buffer specified to write(2) is less than eight bytes in length, EINVAL will be returned.
poll(2), port_get(3C), epoll_wait(3C)
Provide notification when the 64-bit counter associated with the instance is ready for reading or writing, as specified. If the 64-bit value associated with the instance is non-zero, POLLIN and POLLRDNORM will be set; if the value 1 can be added the value without blocking, POLLOUT and POLLWRNORM will be set.

() and () are provided for compatibility with and are wrappers around read(2) and write(2), respectively. They return 0 if the correct number of bytes was transferred and -1 otherwise. These functions may return -1 without setting errno.

Upon successful completion, eventfd() returns a file descriptor associated with the instance. Otherwise, -1 is returned and errno is set to indicate the error.

Upon successful completion, eventfd_read() and eventfd_write() return 0. Otherwise, -1 is returned.

The eventfd() function will fail if:

The flags are invalid.
There are currently {} file descriptors open in the calling process.

poll(2), read(2), write(2), epoll_wait(3C), port_get(3C), eventfd(7)

August 10, 2021 OmniOS