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

NAME

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

SYNOPSIS

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

DESCRIPTION

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

EFD_CLOEXEC
Instance will be closed upon an exec(2); see open(2)'s description
of O_CLOEXEC.

EFD_NONBLOCK
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.

EFD_SEMAPHORE
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.

eventfd_read() and eventfd_write() are provided for compatibility with
glibc 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.

RETURN VALUES

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.

ERRORS

The eventfd() function will fail if:

EINVAL The flags are invalid.

EMFILE There are currently {OPEN_MAX} file descriptors open in
the calling process.

SEE ALSO

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

OmniOS August 10, 2021 OmniOS