eventfd(2) - NetBSD Manual Pages

EVENTFD(2)                NetBSD System Calls Manual                EVENTFD(2)


NAME

     eventfd, eventfd_read, eventfd_write -- create and interact with a count-
     ing 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 spec-
     ified 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.

NetBSD 10.99                  September 17, 2021                  NetBSD 10.99