Updated: 2021/Dec/3


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.

NetBSD 9.99                   September 17, 2021                   NetBSD 9.99