TIMERFD(2)

TIMERFD(2) | System Calls Manual | 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.

The `timerfd_gettime`() and `timerfd_settime`() 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 `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.

September 17, 2021 | NetBSD 10.1