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_CLOEXEC
O_CLOEXEC
flag; see
open(2) for more
information.TFD_NONBLOCK
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
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
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.
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.1 |