TIMERFD(3C) Standard C Library Functions TIMERFD(3C)

NAME

timerfd_create, timerfd_settime, timerfd_gettime - create and
manipulate timers via a file descriptor interface

SYNOPSIS

#include <sys/timerfd.h>

int
timerfd_create(int clockid, int flags);

int
timerfd_settime(int fd, int flags,
const struct itimerspec *restrict value,
struct itimerspec *restrict ovalue);

int
timerfd_gettime(int fd, struct itimerspec *value);

DESCRIPTION

These routines create and manipulate timers in which events are
associated with a file descriptor, allowing for timer-based events to
be used in file-descriptor based facilities like poll(2), port_get(3C)
or epoll_wait(3C). The timerfd_create() function creates a timer with
the clock type specified by clockid. The CLOCK_REALTIME and
CLOCK_HIGHRES clock types, as defined in timer_create(3C), are
supported by timerfd_create(). (Note that CLOCK_MONOTONIC may be used
as an alias for CLOCK_HIGHRES.)

The flags argument specifies additional parameters for the timer
instance, and can have any of the following values:

TFD_CLOEXEC
Instance will be closed upon an exec(2); see open(2)'s
description of O_CLOEXEC.

TFD_NONBLOCK
Instance will be set to be non-blocking. A read(2) on a
timerfd instance that has been initialized with TFD_NONBLOCK
will return EAGAIN in lieu of blocking if the timer has not
expired since the last timerfd_settime() or successful read().

The following operations can be performed upon a timerfd instance:

read(2)
Atomically reads and clears the number of timer expirations
since the last successful read(2) or timerfd_settime(). Upon
success, the number of expirations will be copied into the
eight byte buffer passed to the system call. If there have
been no expirations of the timer since the last successful
read(2) or timerfd_sttime(), read(2) will block until at least
the next expiration, or return EAGAIN if the instance was
created with TFD_NONBLOCK. Note that if multiple threads are
blocked in read(2) for the same timer, only one of them will
return upon a single timer expiration.

If the buffer specified to read(2) is less than eight bytes in
length, EINVAL will be returned.

poll(2), port_get(3C), epoll_wait(3C)
Provide notification when the timer expires or has expired in
the past without a more recent read(2). Note that threads
being simultaneously blocked in read(2) and poll(2) (or
equivalents) for the same timer constitute an application-level
race; on a timer expiration, the thread blocked in poll(2) may
or may not return depending on how it is scheduled with respect
to the thread blocked in read(2).

timerfd_gettime()
Returns the amount of time until the next timer expiration,
with the same functional signature and semantics as
timer_gettime(3C).

timerfd_settime()
Sets or disarms the timer, with the same functional signature
and semantics as timer_settime(3C).

RETURN VALUES

Upon successful completion, a file descriptor associated with the
instance is returned. Otherwise, -1 is returned and errno is set to
indicate the error.

ERRORS

The timerfd_create() function will fail if:

EINAL The flags are invalid.

EMFILE There are currently {OPEN_MAX} file descriptors open
in the calling process.

EPERM The clock_id, is CLOCK_HIGHRES and the
{PRIV_PROC_CLOCK_HIGHRES} is not asserted in the
effective set of the calling process.

SEE ALSO

poll(2), epoll_wait(3C), port_get(3C), timer_create(3C),
timer_gettime(3C), timer_settime(3C), privileges(7), timerfd(7)

illumos February 17, 2023 illumos