Updated: 2022/Sep/29
Please read Privacy Policy. It's for your privacy.
TIMERFD(2) System Calls Manual TIMERFD(2) NAME timerfd, timerfd_create, timerfd_gettime, timerfd_settime - create and interact with a timer descriptor SYNOPSIS #include <sys/timerfd.h> int timerfd_create(clockid_t clockid, int flags); int timerfd_gettime(int fd, struct itimerspec *tim); int timerfd_settime(int fd, int flags, const struct itimerspec *tim, struct itimerspec *otim); DESCRIPTION timerfd presents an interface to interval timers associated with a file descriptor. These timers are functionally equivalent to per-process timers but are associated with a file descriptor, rather than a process. Because they are associated with a file descriptor, they may be passed to other processes, inherited across a fork, and multiplexed using kevent(2), poll(2), or select(2). When a timerfd object is no longer needed, it may be disposed of using close(2). The timerfd_create() system call creates a timerfd object using the clock specified in the clockid argument. Valid values for clockid are CLOCK_REALTIME and CLOCK_MONOTONIC. The following flags define the behavior of the resulting object: TFD_CLOEXEC This is an alias for the O_CLOEXEC flag; see open(2) for more information. TFD_NONBLOCK This is an alias for the O_NONBLOCK flag; see open(2) for more information. Each time a timerfd timer expires, an internal counter is incremented. Reads from an timerfd object return the value of this counter in the caller's buffer as an unsigned 64-bit integer and reset the counter to 0. If the value of the timerfd object's counter is 0, then reads will block, unless the timerfd object is set for non-blocking I/O. Writes to a timerfd object are not supported. The timerfd_settime() system call sets the next expiration time of the timerfd object to the it_value (see itimerspec(3)) specified in the tim argument. If the value is 0, the timer is disarmed. If the argument otim is not NULL the old timer settings are returned. The following flags may be specified to alter the behavior of the timer: TFD_TIMER_ABSTIME The specified timer value is an absolute time. This is equivalent to specifying TIMER_ABSTIME to timer_settime(2). Otherwise, the time value is a relative time, equivalent to specifying TIMER_RELTIME to timer_settime(2). TFD_TIMER_CANCEL_ON_SET If the timerfd object's clock ID is CLOCK_REALTIME, then the timer will be cancelled and its file descriptor will become immediately readable if the system realtime clock is set using clock_settime(2) or settimeofday(2). If the timerfd object's clock ID is not CLOCK_REALTIME this flag is ignored. If the it_interval of the tim argument is non-zero, then the timer reloads upon expiration. The timerfd_gettime() system call returns the current settings of the timerfd object in the tim argument. RETURN VALUES The timerfd_create() system call returns -1 if an error occurs, otherwise the return value is a descriptor representing the timerfd object. The timerfd_gettime() and timerfd_settime() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. ERRORS The timerfd() system call fails if: [EINVAL] Flags other than TFD_CLOEXEC and TFD_NONBLOCK are set in the flags argument. [EINVAL] The clockid argument was something other than CLOCK_REALTIME or CLOCK_MONOTONIC. [EMFILE] The per-process descriptor table is full. [ENFILE] The system file table is full. The timerfd_gettime() system call fails if: [EBADF] The argument fd is not a valid file descriptor. [EFAULT] The tim argument points outside the allocated address space. [EINVAL] The argument fd does not refer to a timerfd object. The timerfd_settime() system call fails if: [EBADF] The argument fd is not a valid file descriptor. [EFAULT] The tim or otim arguments point outside the allocated address space. [EINVAL] The argument fd does not refer to a timerfd object. [EINVAL] Bits other than the defined TFD_TIMER_ABSTIME and TFD_TIMER_CANCEL_ON_SET bits are set in the flags argument. [EINVAL] A nanosecond field in the tim argument specified a value less than zero or greater than or equal to 10^9. A read from a timerfd object fails if: [EAGAIN] The value of the timerfd object's expiration counter is 0 and the timerfd object is set for non-blocking I/O. [ECANCELED] The timerfd object was created with the clock ID CLOCK_REALTIME, was configured with the TFD_TIMER_CANCEL_ON_SET flag, and the system realtime clock was changed with clock_settime(2) or settimeofday(2). [EINVAL] The size of the read buffer is less than 8 bytes (the size required to hold an unsigned 64-bit integer). SEE ALSO clock_settime(2), close(2), kevent(2), open(2), poll(2), read(2), select(2), settimeofday(2), timer_create(2), timer_gettime(2), timer_settime(2) HISTORY The timerfd interface first appeared in NetBSD 10. It is compatible with the timerfd interface that appeared in Linux 2.6.25. NetBSD 10.99 September 17, 2021 NetBSD 10.99