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 itimterspec *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)

OmniOS March 26, 2017 OmniOS