.\"     $NetBSD: timerfd.2,v 1.4 2021/09/23 13:59:27 uwe Exp $
.\"
.\" Copyright (c) 2021 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jason R. Thorpe.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd September 17, 2021
.Dt TIMERFD 2
.Os
.\"
.\"
.Sh NAME
.Nm timerfd ,
.Nm timerfd_create ,
.Nm timerfd_gettime ,
.Nm timerfd_settime
.Nd create and interact with a timer descriptor
.\"
.\"
.Sh SYNOPSIS
.In sys/timerfd.h
.Ft int
.Fn timerfd_create "clockid_t clockid" "int flags"
.Ft int
.Fn timerfd_gettime "int fd" "struct itimerspec *tim"
.Ft int
.Fn timerfd_settime "int fd" "int flags" \
"const struct itimerspec *tim" "struct itimerspec *otim"
.\"
.\"
.Sh DESCRIPTION
.Nm
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
.Xr kevent 2 ,
.Xr poll 2 ,
or
.Xr select 2 .
When a
.Nm
object is no longer needed, it may be disposed of using
.Xr close 2 .
.Pp
The
.Fn timerfd_create
system call creates a
.Nm
object using the clock specified in the
.Fa clockid
argument.
Valid values for
.Fa clockid
are
.Dv CLOCK_REALTIME
and
.Dv CLOCK_MONOTONIC .
The following flags define the behavior of the resulting object:
.Bl -tag -width Dv
.It Dv TFD_CLOEXEC
This is an alias for the
.Dv O_CLOEXEC
flag; see
.Xr open 2
for more information.
.It Dv TFD_NONBLOCK
This is an alias for the
.Dv O_NONBLOCK
flag; see
.Xr open 2
for more information.
.El
.Pp
Each time a
.Nm
timer expires, an internal counter is incremented.
Reads from an
.Nm
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
.Nm
object's counter is\~0,
then reads will block, unless the
.Nm
object is set for non-blocking I/O.
.Pp
Writes to a
.Nm
object are not supported.
.Pp
The
.Fn timerfd_settime
system call sets the next expiration time of the
.Nm
object to the
.Va it_value
.Po
see
.Xr itimerspec 3
.Pc
specified in the
.Fa tim
argument.
If the value is\~0,
the timer is disarmed.
If the argument
.Fa otim
is not
.Dv NULL
the old timer settings are returned.
The following flags may be specified to alter the behavior of the timer:
.Bl -tag -width "TFD_TIMER_CANCEL_ON_SET"
.It Dv TFD_TIMER_ABSTIME
The specified timer value is an absolute time.
This is equivalent to specifying
.Dv TIMER_ABSTIME
to
.Xr timer_settime 2 .
Otherwise, the time value is a relative time, equivalent to specifying
.Dv TIMER_RELTIME
to
.Xr timer_settime 2 .
.It Dv TFD_TIMER_CANCEL_ON_SET
If the
.Nm
object's clock ID is
.Dv CLOCK_REALTIME ,
then the timer will be cancelled and its file descriptor will become
immediately readable if the system realtime clock is set using
.Xr clock_settime 2
or
.Xr settimeofday 2 .
If the
.Nm
object's clock ID is not
.Dv CLOCK_REALTIME
this flag is ignored.
.El
.Pp
If the
.Va it_interval
of the
.Fa tim
argument is non-zero, then the timer reloads upon expiration.
.Pp
The
.Fn timerfd_gettime
system call returns the current settings of the
.Nm
object in the
.Fa tim
argument.
.\"
.\"
.Sh RETURN VALUES
The
.Fn timerfd_create
system call returns\~\-1 if an error occurs,
otherwise the return value is a descriptor representing the
.Nm
object.
.Pp
.Rv -std timerfd_gettime timerfd_settime
.\"
.\"
.Sh ERRORS
The
.Fn timerfd
system call fails if:
.Bl -tag -width Er
.It Bq Er EINVAL
Flags other than
.Dv TFD_CLOEXEC
and
.Dv TFD_NONBLOCK
are set in the
.Fa flags
argument.
.It Bq Er EINVAL
The
.Fa clockid
argument was something other than
.Dv CLOCK_REALTIME
or
.Dv CLOCK_MONOTONIC .
.It Bq Er EMFILE
The per-process descriptor table is full.
.It Bq Er ENFILE
The system file table is full.
.El
.Pp
The
.Fn timerfd_gettime
system call fails if:
.Bl -tag -width Er
.It Bq Er EBADF
The argument
.Fa fd
is not a valid file descriptor.
.It Bq Er EFAULT
The
.Fa tim
argument points outside the allocated address space.
.It Bq Er EINVAL
The argument
.Fa fd
does not refer to a
.Nm timerfd
object.
.El
.Pp
The
.Fn timerfd_settime
system call fails if:
.Bl -tag -width Er
.It Bq Er EBADF
The argument
.Fa fd
is not a valid file descriptor.
.It Bq Er EFAULT
The
.Fa tim
or
.Fa otim
arguments point outside the allocated address space.
.It Bq Er EINVAL
The argument
.Fa fd
does not refer to a
.Nm timerfd
object.
.It Bq Er EINVAL
Bits other than the defined
.Dv TFD_TIMER_ABSTIME
and
.Dv TFD_TIMER_CANCEL_ON_SET
bits are set in the
.Fa flags
argument.
.It Bq Er EINVAL
A nanosecond field in the
.Fa tim
argument specified a value less than zero or greater than or equal
to\~10^9.
.El
.Pp
A read from a
.Nm
object fails if:
.Bl -tag -width Er
.It Bq Er EAGAIN
The value of the
.Nm
object's expiration counter is
.Dv 0
and the
.Nm
object is set for non-blocking I/O.
.It Bq Er ECANCELED
The
.Nm
object was created with the clock ID
.Dv CLOCK_REALTIME ,
was configured with the
.Dv TFD_TIMER_CANCEL_ON_SET
flag, and the system realtime clock was changed with
.Xr clock_settime 2
or
.Xr settimeofday 2 .
.It Bq Er EINVAL
The size of the read buffer is less than 8 bytes
.Pq the size required to hold an unsigned 64-bit integer .
.El
.\"
.\"
.Sh SEE ALSO
.Xr clock_settime 2 ,
.Xr close 2 ,
.Xr kevent 2 ,
.Xr open 2 ,
.Xr poll 2 ,
.Xr read 2 ,
.Xr select 2 ,
.Xr settimeofday 2 ,
.Xr timer_create 2 ,
.Xr timer_gettime 2 ,
.Xr timer_settime 2
.\"
.\"
.Sh HISTORY
The
.Nm
interface first appeared in
.Nx 10 .
It is compatible with the
.Nm
interface that appeared in Linux 2.6.25.