TIMERFD(2)

NAME
timerfd, timerfd_create, timerfd_gettime, timerfd_settime - create and interact with a timer descriptor

SYNOPSIS
#include <sys/timerfd.h>
int
timerfd_create(clockid_t clockid, int flags);
int
timerfd_gettime(int fd, struct itimerspec *tim);
int
timerfd_settime(int fd, int flags, const struct itimerspec *tim, struct itimerspec *otim);

DESCRIPTION
timerfd presents an interface to interval timers associated with a file descriptor. These timers are functionally equivalent to per-process timers but are associated with a file descriptor, rather than a process. Because they are associated with a file descriptor, they may be passed to other processes, inherited across a fork, and multiplexed using kevent(2), poll(2), or select(2). When a timerfd object is no longer needed, it may be disposed of using close(2).

The timerfd_create() system call creates a timerfd object using the clock specified in the clockid argument. Valid values for clockid are CLOCK_REALTIME and CLOCK_MONOTONIC. The following flags define the behavior of the resulting object:

TFD_CLOEXEC
    This is an alias for the O_CLOEXEC flag; see open(2) for more information.

TFD_NONBLOCK
    This is an alias for the O_NONBLOCK flag; see open(2) for more information.

Each time a timerfd timer expires, an internal counter is incremented. Reads from an timerfd object return the value of this counter in the caller's buffer as an unsigned 64-bit integer and reset the counter to 0. If the value of the timerfd object's counter is 0, then reads will block, unless the timerfd object is set for non-blocking I/O.

Writes to a timerfd object are not supported.

The timerfd_settime() system call sets the next expiration time of the timerfd object to the it_value ( see itimerspec(3)) specified in the tim argument. If the value is 0, the timer is disarmed. If the argument otim is not NULL the old timer settings are returned. The following flags may be specified to alter the behavior of the timer:

TFD_TIMER_ABSTIME
    The specified timer value is an absolute time. This is equivalent to specifying TIMER_ABSTIME to timer_settime(2). Otherwise, the time value is a relative time, equivalent to specifying TIMER_RELTIME to timer_settime(2).

TFD_TIMER_CANCEL_ON_SET
    If the timerfd object's clock ID is CLOCK_REALTIME, then the timer will be cancelled and its file descriptor will become immediately readable if the system realtime clock is set using clock_settime(2) or settimeofday(2). If the timerfd object's clock ID is not CLOCK_REALTIME this flag is ignored.

If the it_interval of the tim argument is non-zero, then the timer reloads upon expiration.

The timerfd_gettime() system call returns the current settings of the timerfd object in the tim argument.

RETURN VALUES
The timerfd_create() system call returns -1 if an error occurs, otherwise the return value is a descriptor representing the timerfd object.

ERRORS
The timerfd() system call fails if:

[EINVAL]
    Flags other than TFD_CLOEXEC and TFD_NONBLOCK are set in the flags argument.

[EINVAL]
    The clockid argument was something other than CLOCK_REALTIME or CLOCK_MONOTONIC.

[EMFILE]
    The per-process descriptor table is full.

[ENFILE]
    The system file table is full.

The timerfd_gettime() system call fails if:

[EBADF]
    The argument fd is not a valid file descriptor.

[EFAULT]
    The tim argument points outside the allocated address space.

[EINVAL]
    The argument fd does not refer to a timerfd object.

The timerfd_settime() system call fails if:

[EBADF]
    The argument fd is not a valid file descriptor.

[EFAULT]
    The tim or otim arguments point outside the allocated address space.

[EINVAL]
    The argument fd does not refer to a timerfd object.

[EINVAL]
    Bits other than the defined TFD_TIMER_ABSTIME and TFD_TIMER_CANCEL_ON_SET bits are set in the flags argument.

[EINVAL]
    A nanosecond field in the tim argument specified a value less than zero or greater than or equal to 10^9.

A read from a timerfd object fails if:

[EAGAIN]
    The value of the timerfd object's expiration counter is 0 and the timerfd object is set for non-blocking I/O.

[ECANCELED]
    The timerfd object was created with the clock ID CLOCK_REALTIME, was configured with the TFD_TIMER_CANCEL_ON_SET flag, and the system realtime clock was changed with clock_settime(2) or settimeofday(2).

[EINVAL]
    The size of the read buffer is less than 8 bytes (the size required to hold an unsigned 64-bit integer).

SEE ALSO
clock_settime(2), close(2), kevent(2), open(2), poll(2), read(2), select(2), settimeofday(2), timer_create(2), timer_gettime(2), timer_settime(2)

HISTORY
The timerfd interface first appeared in NetBSD 10. It is compatible with the timerfd interface that appeared in Linux 2.6.25.