| TIMERFD(2) | System Calls Manual | TIMERFD(2) | 
timerfd, timerfd_create,
  timerfd_gettime,
  timerfd_settime —
#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);
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_CLOEXECO_CLOEXEC flag; see
      open(2) for more
    information.TFD_NONBLOCKO_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_ABSTIMETIMER_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_SETtimerfd 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.
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.
timerfd() system call fails if:
EINVAL]TFD_CLOEXEC and
      TFD_NONBLOCK are set in the
      flags argument.EINVAL]CLOCK_REALTIME or
      CLOCK_MONOTONIC.EMFILE]ENFILE]The timerfd_gettime() system call fails
    if:
EBADF]EFAULT]EINVAL]timerfd object.The timerfd_settime() system call fails
    if:
EBADF]EFAULT]EINVAL]timerfd object.EINVAL]TFD_TIMER_ABSTIME and
      TFD_TIMER_CANCEL_ON_SET bits are set in the
      flags argument.EINVAL]A read from a timerfd object fails if:
EAGAIN]timerfd object's expiration
      counter is 0 and the
      timerfd object is set for non-blocking I/O.ECANCELED]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]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.0 |