eventfd(2) manual page

eventfd() creates a special file descriptor with event counter or semaphore semantics, designed for interprocess communication. The returned file descriptor refers to a kernel object containing an unsigned 64-bit integer counter, which is initialized with the value of the initval argument.

The flags argument may contain the result of or'ing the following values:

EFD_CLOEXEC set FD_CLOEXEC on the file descriptor

EFD_NONBLOCK do not block on read/write operations

EFD_SEMAPHORE

use semaphore semantics

File operations have the following semantics:

read(2)

If the counter is zero, the call blocks until the counter becomes non-zero, unless EFD_NONBLOCK was set, in which case it would fail with EAGAIN instead.
If the counter is non-zero:

If EFD_SEMAPHORE is not set, the current value of the counter is returned, and the value is reset to zero.
If EFD_SEMAPHORE is set, the constant 1 is returned, and the value is decremented by 1.

The numeric value is encoded as 64-bit (8 bytes) in host byte order. The read(2) call fails with EINVAL if there is less than 8 bytes available in the supplied buffer.

write(2)

Adds the given value to the counter. The maximum value that can be stored in the counter is the maximum unsigned 64-bit integer value minus one (0xfffffffffffffffe).
If the resulting value exceeds the maximum, the call would block until the value is reduced by read(2), unless EFD_NONBLOCK was set, in which case it would fail with EAGAIN instead.
The numeric value is encoded as 64-bit (8 bytes) in host byte order. The write(2) call fails with EINVAL if there is less than 8 bytes available in the supplied buffer, or if the value 0xffffffffffffffff is given.

poll(2)

When receiving notifications via poll(2) / ppoll(2) / select(2) / pselect(2) / kqueue(2), the following semantics apply:

The file descriptor is readable when the counter is greater than zero.
The file descriptor is writable when the counter is less than the maximum value.

File descriptors created by eventfd() are passable to other processes via sendmsg(2) and are preserved across fork(2); in both cases the descriptors refer to the same counter from both processes. Unless O_CLOEXEC flag was specified, the created file descriptor will remain open across execve(2) system calls; see close(2), fcntl(2) and O_CLOEXEC description.

eventfd_read() and eventfd_write() are thin wrappers around read(2) and write(2) system calls, provided for compatibility with glibc.

“

Ken Thompson has an automobile which he helped design. Unlike most automobiles, it has neither speedometer, nor gas gauge, nor any of the other numerous idiot lights which plague the modern driver. Rather, if the driver makes a mistake, a giant “?” lights up in the center of the dashboard. “The experienced driver,” says Thompson, “will usually know what's wrong.”

”

[`EINVAL`]
	The flags argument given to `eventfd()` has unknown bits set.
[`EMFILE`]
	The process has already reached its limit for open file descriptors.
[`ENFILE`]
	The system file table is full.
[`ENOMEM`]
	No memory was available to create the kernel object.

Manual Pages — EVENTFD

NAME

CONTENTS

LIBRARY

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

SEE ALSO

STANDARDS

HISTORY

`EFD_CLOEXEC`	set FD_CLOEXEC on the file descriptor
`EFD_NONBLOCK`	do not block on read/write operations
`EFD_SEMAPHORE`
	use semaphore semantics

read(2)
	If the counter is zero, the call blocks until the counter becomes non-zero, unless `EFD_NONBLOCK` was set, in which case it would fail with `EAGAIN` instead. If the counter is non-zero: If `EFD_SEMAPHORE` is not set, the current value of the counter is returned, and the value is reset to zero. If `EFD_SEMAPHORE` is set, the constant 1 is returned, and the value is decremented by 1. The numeric value is encoded as 64-bit (8 bytes) in host byte order. The read(2) call fails with `EINVAL` if there is less than 8 bytes available in the supplied buffer.
write(2)
	Adds the given value to the counter. The maximum value that can be stored in the counter is the maximum unsigned 64-bit integer value minus one (0xfffffffffffffffe). If the resulting value exceeds the maximum, the call would block until the value is reduced by read(2), unless `EFD_NONBLOCK` was set, in which case it would fail with `EAGAIN` instead. The numeric value is encoded as 64-bit (8 bytes) in host byte order. The write(2) call fails with `EINVAL` if there is less than 8 bytes available in the supplied buffer, or if the value 0xffffffffffffffff is given.
poll(2)
	When receiving notifications via poll(2) / ppoll(2) / select(2) / pselect(2) / kqueue(2), the following semantics apply: The file descriptor is readable when the counter is greater than zero. The file descriptor is writable when the counter is less than the maximum value.