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)

illumos August 10, 2021 illumos