--- name: "timerfd_settime" section: "2" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/timerfd" --- # timerfd\_settime(2) timers with file descriptor semantics Part of [timerfd(2)](/timerfd/2.md). ## NAME **timerfd**, **timerfd\_create**, **timerfd\_gettime**, **timerfd\_settime** – timers with file descriptor semantics ## LIBRARY Standard C Library (libc, -lc) ## SYNOPSIS **#include \** *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. These calls are 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)](/fork/2.md), and monitored via [kevent(2)](/kevent/2.md), [poll(2)](/poll/2.md), or [select(2)](/select/2.md). When a **timerfd** descriptor is no longer needed, it may be disposed of using [close(2)](/close/2.md). - **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 - 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)](/clock_gettime/2.md) 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)](/read/2.md) will fail with ECANCELED. File operations have the following semantics: - [read(2)](/read/2.md) Transfer the number of timer expirations that have occurred since the last successful [read(2)](/read/2.md) or **timerfd\_settime**() into the output buffer of size *uint64\_t*. If the expiration counter is zero, [read(2)](/read/2.md) blocks until a timer expiration occurs unless TFD\_NONBLOCK is set, where EAGAIN is returned. - [poll(2)](/poll/2.md) The file descriptor is readable when its timer expiration counter is greater than zero. - [ioctl(2)](/ioctl/2.md) - 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)](/eventfd/2.md), [kqueue(2)](/kqueue/2.md), [poll(2)](/poll/2.md), [read(2)](/read/2.md), [timer\_create(2)](/timer_create/2.md), [timer\_gettime(2)](/timer_gettime/2.md), [timer\_settime(2)](/timer_settime/2.md) ## STANDARDS The **timerfd** system calls originated from Linux and are non-standard. ## 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.