Understanding Linux timerfd: From Procfs to Epoll Integration

Timerfd is a special file descriptor type that represents a timer; its name literally means "timer fd". By inspecting /proc/${pid}/fd/ you can see an entry like anon_inode:[timerfd], indicating that the fd is bound to an anonymous inode.

Reading /proc/${pid}/fdinfo/ reveals detailed fields such as clockid (clock type), ticks (number of expirations), settime flags (parameters for timerfd_settime), it_value (remaining time until expiration), and it_interval (periodic interval).

Timerfd supports the usual file operations read, poll, and close. After creating a timerfd with timerfd_create, you set its expiration using timerfd_settime. When the timer expires, the fd becomes readable; a read returns the number of expirations that have occurred.

The core implementation resides in fs/timerfd.c. The file operations table timerfd_fops defines .read, .poll, .show_fdinfo, etc. The kernel structure struct timerfd_ctx holds the actual timer (either an hrtimer or an alarm), a wait‑queue head ctx->wqh, the expiration count, and other metadata. When a timerfd is created, an anonymous inode is allocated via anon_inode_getfd, and the timerfd_ctx is stored in file->private_data.

Key system calls:

int timerfd_create(int clockid, int flags);
int timerfd_settime(int fd, int flags, const struct itimerspec *new_value, struct itimerspec *old_value);
int timerfd_gettime(int fd, struct itimerspec *curr_value);

The itimerspec structure contains it_interval (periodic interval) and it_value (initial expiration). A typical C example creates a timerfd, configures new_value, and then loops reading the fd to count expirations, printing each read.

Timerfd can be combined with epoll. When an fd is registered with epoll_ctl, the kernel sets up a poll function ( timerfd_poll) that adds a wait entry to ctx->wqh via poll_wait. The wait entry’s callback is ep_poll_callback, which places the associated epitem on epoll’s ready list and wakes any process blocked in epoll_wait.

When the timer expires, the kernel’s timer callback ( timerfd_tmrproc) invokes timerfd_trigger, which calls wake_up_locked_poll on the wait queue, ultimately invoking ep_poll_callback and delivering the event to epoll.

Summary of important points:

Procfs provides visibility into timerfd handles and their detailed info.

The central structure is timerfd_ctx, linked from file->private_data.

Timerfd wraps kernel timers (hrtimer or alarm) with a file‑like interface.

Anonymous inode filesystem ( anon_inodefs) supplies a shared inode for these special fds, avoiding duplicate inode code.

Integration with epoll is straightforward: epoll registers the fd, poll adds a wait entry to ctx->wqh, and timer expiration wakes epoll via the wait‑queue callback.

Overall, timerfd exemplifies the Linux principle "everything is a file" by exposing timer functionality through standard file I/O and event‑driven mechanisms.