TIMERFD(3C) Standard C Library Functions TIMERFD(3C)

timerfd_create, timerfd_settime, timerfd_gettime — create and manipulate timers via a file descriptor interface

#include <sys/timerfd.h>

int
timerfd_create(int clockid, int flags);

int
timerfd_settime(int fd, int flags, const struct itimerspec *restrict value, struct itimerspec *restrict ovalue);

int
timerfd_gettime(int fd, struct itimerspec *value);

These routines create and manipulate timers in which events are associated with a file descriptor, allowing for timer-based events to be used in file-descriptor based facilities like poll(2), port_get(3C) or epoll_wait(3C). The () function creates a timer with the clock type specified by clockid. The and CLOCK_HIGHRES clock types, as defined in timer_create(3C), are supported by timerfd_create(). (Note that may be used as an alias for CLOCK_HIGHRES.)

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

Instance will be closed upon an exec(2); see open(2)'s description of .
Instance will be set to be non-blocking. A read(2) on a timerfd instance that has been initialized with TFD_NONBLOCK will return EAGAIN in lieu of blocking if the timer has not expired since the last () or successful ().

The following operations can be performed upon a timerfd instance:

Atomically reads and clears the number of timer expirations since the last successful read(2) or (). Upon success, the number of expirations will be copied into the eight byte buffer passed to the system call. If there have been no expirations of the timer since the last successful read(2) or (), read(2) will block until at least the next expiration, or return EAGAIN if the instance was created with TFD_NONBLOCK. Note that if multiple threads are blocked in read(2) for the same timer, only one of them will return upon a single timer expiration.

If the buffer specified to read(2) is less than eight bytes in length, will be returned.

Provide notification when the timer expires or has expired in the past without a more recent read(2). Note that threads being simultaneously blocked in read(2) and poll(2) (or equivalents) for the same timer constitute an application-level race; on a timer expiration, the thread blocked in poll(2) may or may not return depending on how it is scheduled with respect to the thread blocked in read(2).
Returns the amount of time until the next timer expiration, with the same functional signature and semantics as timer_gettime(3C).
Sets or disarms the timer, with the same functional signature and semantics as timer_settime(3C).

Upon successful completion, a file descriptor associated with the instance is returned. Otherwise, is returned and errno is set to indicate the error.

The timerfd_create() function will fail if:

The flags are invalid.
There are currently {} file descriptors open in the calling process.
The clock_id, is CLOCK_HIGHRES and the {} is not asserted in the effective set of the calling process.

poll(2), epoll_wait(3C), port_get(3C), timer_create(3C), timer_gettime(3C), timer_settime(3C), privileges(7), timerfd(7)

February 17, 2023 OmniOS