| 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 |