TIMERFD(2)

💖 NAME 💖

okay so hi bestie, welcome to timerfd(2) from the System Calls Manual — the page for timerfd, timerfd_create, timerfd_gettime, and timerfd_settime — literally timers with file descriptor semantics. 💅

📚 LIBRARY 📚

Standard C Library: libc, link with -lc. easy.

✨ SYNOPSIS ✨

#include <sys/timerfd.h>

int
timerfd_create(int clockid, int flags);

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

int
timerfd_settime(int fd, int flags, const struct itimerspec *new_value,
    struct itimerspec *old_value);

🧠 DESCRIPTION 🧠

The timerfd system calls operate on timers, identified by special timerfd file descriptors. They’re analogous to timer_create(), timer_gettime(), and timer_settime() per-process timer functions, but use a timerfd descriptor in place of timerid. 🫶

All timerfd descriptors possess traditional file descriptor semantics; they may be passed to other processes, preserved across fork(2), and monitored via kevent(2), poll(2), or select(2). When a timerfd descriptor is no longer needed, it may be disposed of using close(2). iconic.

🎀 timerfd_create() 🎀

Initialize a timerfd object and return its file descriptor. The clockid argument specifies the clock used as a timing base and may be:

• CLOCK_REALTIME — increments as a wall clock should.
• CLOCK_BOOTTIME — also in the clock list here.
• CLOCK_MONOTONIC — increments monotonically in SI seconds.
• CLOCK_UPTIME — increments monotonically in SI seconds, but is paused while the system is suspended.

See clock_gettime(2) for more precise definitions.

The flags argument may contain the result of OR-ing the following values:

• TFD_CLOEXEC — the newly generated file descriptor will close-on-exec.
• TFD_NONBLOCK — do not block on read/write operations.

🌸 timerfd_gettime() 🌸

Retrieve the current state of the timer denoted by fd. The result is stored in curr_value as a struct itimerspec. The it_value and it_interval members of curr_value represent the relative time until the next expiration and the interval reload value last set by timerfd_settime(), respectively.

🦋 timerfd_settime() 🦋

Update the timer denoted by fd with the struct itimerspec in new_value. The it_value member of new_value should contain the amount of time before the timer expires, or zero if the timer should be disarmed. The it_interval member should contain the reload time if an interval timer is desired.

The previous timer state will be stored in old_value given old_value is not NULL.

The flags argument may contain the result of OR-ing the following values:

• TFD_TIMER_ABSTIME — expiration will occur at the absolute time provided in new_value. Normally, new_value represents a relative time compared to the timer’s clockid clock.
• TFD_TIMER_CANCEL_ON_SET — if clockid has been set to CLOCK_REALTIME and the realtime clock has experienced a discontinuous jump, then the timer will be canceled and the next read(2) will fail with ECANCELED.

🚨 heads up, bestie: that TFD_TIMER_CANCEL_ON_SET behavior is a real caveat — timer canceled, next read(2) fails with ECANCELED, no cap.

🗂️ File operations have the following semantics: 🗂️

📥 read(2) 📥

Transfer the number of timer expirations that have occurred since the last successful read(2) or timerfd_settime() into the output buffer of size uint64_t. If the expiration counter is zero, read(2) blocks until a timer expiration occurs unless TFD_NONBLOCK is set, where EAGAIN is returned.

👀 poll(2) 👀

The file descriptor is readable when its timer expiration counter is greater than zero.

🎛️ ioctl(2) 🎛️

• FIOASYNC int — a non-zero input will set the FASYNC flag. A zero input will clear the FASYNC flag.
• FIONBIO int — a non-zero input will set the FNONBLOCK flag. A zero input will clear the FNONBLOCK flag.

🧾 RETURN VALUES 🧾

The timerfd_create() system call creates a timerfd object and returns its file descriptor. If an error occurs, -1 is returned and the global variable errno is set to indicate the error.

The timerfd_gettime() and timerfd_settime() system calls return 0 on success. If an error occurs, -1 is returned and the global variable errno is set to indicate the error.

💀 ERRORS 💀

The timerfd_create() system call fails if:

• [EINVAL] — the specified clockid is not supported.
• [EINVAL] — the provided flags are invalid.
• [EMFILE] — the per-process descriptor table is full.
• [ENFILE] — the system file table is full.
• [ENOMEM] — the kernel failed to allocate enough memory for the timer.

Both timerfd_gettime() and timerfd_settime() system calls fail if:

• [EBADF] — the provided fd is invalid.
• [EFAULT] — the addresses provided by curr_value, new_value, or old_value are invalid.
• [EINVAL] — the provided fd is valid, but was not generated by timerfd_create().

The following errors only apply to timerfd_settime():

• [EINVAL] — the provided flags are invalid.
• [EINVAL] — a nanosecond field in the new_value argument specified a value less than zero, or greater than or equal to 10^9.
• [ECANCELED] — the timer was created with the clock ID CLOCK_REALTIME, was configured with the TFD_TIMER_CANCEL_ON_SET flag, and the system realtime clock experienced a discontinuous change without being read.

A read from a timerfd object fails if:

• [EAGAIN] — the timer’s expiration counter is zero and the timerfd object is set for non-blocking I/O.
• [ECANCELED] — the timer was created with the clock ID CLOCK_REALTIME, was configured with the TFD_TIMER_CANCEL_ON_SET flag, and the system realtime clock experienced a discontinuous change.
• [EINVAL] — the size of the read buffer is not large enough to hold the uint64_t sized timer expiration counter.

👯 SEE ALSO 👯

eventfd(2), kqueue(2), poll(2), read(2), timer_create(2), timer_gettime(2), timer_settime(2) — that’s the whole squad, bestie.

📜 STANDARDS 📜

The timerfd system calls originated from Linux and are non-standard. so yeah, not a portable-everywhere situation, periodt.

🕰️ HISTORY 🕰️

The timerfd facility was originally ported to FreeBSD’s Linux compatibility layer by Dmitry Chagin <dchagin@FreeBSD.org> in FreeBSD 12.0. It was revised and adapted to be native by Jake Freeland <jfree@FreeBSD.org> in FreeBSD 14.0.

---

xoxo 💖 your Unix bestie — this page is from Debian, dated June 28, 2024, and it’s TIMERFD(2), periodt. 🎀