Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/sys/timerfd.2
- This file was added.
.\" SPDX-License-Identifier: BSD-2-Clause | |||||||||
.\" | |||||||||
.\" Copyright (c) 2023 Jake Freeland <jfree@FreeBSD.org> | |||||||||
.\" | |||||||||
.\" 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 AUTHOR 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 AUTHOR 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 May 21, 2023 | |||||||||
.Dt TIMERFD 2 | |||||||||
.Os | |||||||||
.Sh NAME | |||||||||
.Nm timerfd , | |||||||||
.Nm timerfd_create , | |||||||||
.Nm timerfd_gettime , | |||||||||
.Nm timerfd_settime | |||||||||
.Nd timers with file descriptor semantics | |||||||||
.Sh LIBRARY | |||||||||
.Lb libc | |||||||||
.Sh SYNOPSIS | |||||||||
.In sys/timerfd.h | |||||||||
.Ft int | |||||||||
.Fo timerfd_create | |||||||||
.Fa "int clockid" | |||||||||
.Fa "int flags" | |||||||||
.Fc | |||||||||
.Ft int | |||||||||
.Fo timerfd_gettime | |||||||||
.Fa "int fd" | |||||||||
.Fa "struct itimerspec *curr_value" | |||||||||
.Fc | |||||||||
.Ft int | |||||||||
.Fo timerfd_settime | |||||||||
.Fa "int fd" | |||||||||
.Fa "int flags" | |||||||||
.Fa "const struct itimerspec *new_value" | |||||||||
.Fa "struct itimerspec *old_value" | |||||||||
.Fc | |||||||||
.Sh DESCRIPTION | |||||||||
The | |||||||||
.Nm | |||||||||
system calls operate on timers, identified by special | |||||||||
.Nm | |||||||||
file descriptors. | |||||||||
These calls are analogous to | |||||||||
.Fn timer_create , | |||||||||
.Fn timer_gettime , | |||||||||
and | |||||||||
.Fn timer_settime | |||||||||
per-process timer functions, but use a | |||||||||
.Nm | |||||||||
descriptor in place of | |||||||||
.Fa timerid . | |||||||||
.Pp | |||||||||
All | |||||||||
.Nm | |||||||||
descriptors possess traditional file descriptor semantics; they may be passed | |||||||||
to other processes, preserved across | |||||||||
.Xr fork 2 , | |||||||||
and monitored via | |||||||||
.Xr kevent 2 , | |||||||||
.Xr poll 2 , | |||||||||
or | |||||||||
.Xr select 2 . | |||||||||
When a | |||||||||
.Nm | |||||||||
descriptor is no longer needed, it may be disposed of using | |||||||||
.Xr close 2 . | |||||||||
.Bl -tag -width "Fn timerfd_settime" | |||||||||
.It Fn timerfd_create | |||||||||
Initialize a | |||||||||
.Nm | |||||||||
object and return its file descriptor. | |||||||||
The | |||||||||
.Fa clockid | |||||||||
argument specifies the clock used as a timing base and may be: | |||||||||
.Pp | |||||||||
.Bl -tag -width "Dv CLOCK_MONOTONIC" -compact | |||||||||
.It Dv CLOCK_REALTIME | |||||||||
Increments as a wall clock should. | |||||||||
.It Dv CLOCK_MONOTONIC | |||||||||
Increments monotonically in SI seconds. | |||||||||
.El | |||||||||
.Pp | |||||||||
The | |||||||||
.Fa flags | |||||||||
argument may contain the result of | |||||||||
.Em or Ns 'ing | |||||||||
the following values: | |||||||||
.Pp | |||||||||
.Bl -tag -width "Dv TFD_NONBLOCK" -compact | |||||||||
.It Dv TFD_CLOEXEC | |||||||||
The newly generated file descriptor will close-on-exec. | |||||||||
.It Dv TFD_NONBLOCK | |||||||||
Do not block on read/write operations. | |||||||||
.El | |||||||||
.It Fn timerfd_gettime | |||||||||
Retrieve the current state of the timer denoted by | |||||||||
.Fa fd . | |||||||||
The result is stored in | |||||||||
.Fa curr_value | |||||||||
as a | |||||||||
.Dv struct itimerspec . | |||||||||
The | |||||||||
.Fa it_value | |||||||||
and | |||||||||
.Fa it_interval | |||||||||
members of | |||||||||
.Fa curr_value | |||||||||
represent the relative time until the next expiration and the interval | |||||||||
reload value last set by | |||||||||
.Fn timerfd_settime , | |||||||||
respectively. | |||||||||
.It Fn timerfd_settime | |||||||||
Update the timer denoted by | |||||||||
.Fa fd | |||||||||
with the | |||||||||
.Dv struct itimerspec | |||||||||
in | |||||||||
.Fa new_value . | |||||||||
The | |||||||||
.Fa it_value | |||||||||
member of | |||||||||
.Fa new_value | |||||||||
should contain the amount of time before the timer expires, or zero if the | |||||||||
timer should be disarmed. | |||||||||
The | |||||||||
.Fa it_interval | |||||||||
member should contain the reload time if an interval timer is desired. | |||||||||
.Pp | |||||||||
The previous timer state will be stored in | |||||||||
.Fa old_value | |||||||||
given | |||||||||
.Fa old_value | |||||||||
is not | |||||||||
.Dv NULL . | |||||||||
.Pp | |||||||||
The | |||||||||
.Fa flags | |||||||||
argument may contain the result of | |||||||||
.Em or Ns 'ing | |||||||||
the following values: | |||||||||
.Pp | |||||||||
.Bl -tag -width TFD_TIMER_CANCEL_ON_SET -compact | |||||||||
.It Dv TFD_TIMER_ABSTIME | |||||||||
Expiration will occur at the absolute time provided in | |||||||||
.Fa new_value . | |||||||||
Regularly, | |||||||||
.Fa new_value | |||||||||
grahamperrin: Might //Normally// or //Typically// be better?
(Because [[ https://www.thesaurus. | |||||||||
represents a relative time compared to the timer's | |||||||||
.Fa clockid | |||||||||
clock. | |||||||||
.It Dv TFD_TIMER_CANCEL_ON_SET | |||||||||
If | |||||||||
.Fa clockid | |||||||||
has been set to | |||||||||
.Dv CLOCK_REALTIME | |||||||||
and the realtime clock has experienced a discontinuous jump, | |||||||||
then the timer will be canceled and the next | |||||||||
.Xr read 2 | |||||||||
will fail with | |||||||||
.Dv ECANCELED . | |||||||||
.El | |||||||||
.El | |||||||||
.Pp | |||||||||
File operations have the following semantics: | |||||||||
.Bl -tag -width ioctl | |||||||||
.It Xr read 2 | |||||||||
Transfer the number of timer expirations that have occurred since the last | |||||||||
successful | |||||||||
.Xr read 2 | |||||||||
or | |||||||||
.Fn timerfd_settime | |||||||||
into the output buffer of size | |||||||||
.Vt uint64_t . | |||||||||
If the expiration counter is zero, | |||||||||
.Xr read 2 | |||||||||
blocks until a timer expiration occurs unless | |||||||||
.Dv TFD_NONBLOCK | |||||||||
is set, where | |||||||||
.Dv EAGAIN | |||||||||
is returned. | |||||||||
.It Xr poll 2 | |||||||||
The file descriptor is readable when its timer expiration counter is greater | |||||||||
than zero. | |||||||||
.It Xr ioctl 2 | |||||||||
.Bl -tag -width FIONREAD | |||||||||
.It Dv FIOASYNC int | |||||||||
A non-zero input will set the FASYNC flag. | |||||||||
A zero input will clear the FASYNC flag. | |||||||||
.It Dv FIONBIO int | |||||||||
A non-zero input will set the FNONBLOCK flag. | |||||||||
A zero input will clear the FNONBLOCK flag. | |||||||||
.El | |||||||||
.El | |||||||||
.Sh RETURN VALUES | |||||||||
The | |||||||||
.Fn timerfd_create | |||||||||
system call creates a | |||||||||
.Nm | |||||||||
object and returns its file descriptor. | |||||||||
If an error occurs, -1 is returned and the global variable | |||||||||
.Fa errno | |||||||||
is set to indicate the error. | |||||||||
.Pp | |||||||||
The | |||||||||
.Fn timerfd_gettime | |||||||||
and | |||||||||
.Fn timerfd_settime | |||||||||
system calls return 0 on success. | |||||||||
If an error occurs, -1 is returned and the global variable | |||||||||
.Fa errno | |||||||||
is set to indicate the error. | |||||||||
.Sh ERRORS | |||||||||
The | |||||||||
.Fn timerfd_create | |||||||||
system calls fails if: | |||||||||
.Bl -tag -width Er | |||||||||
Done Inline Actions
grahamperrin: | |||||||||
.It Bq Er EINVAL | |||||||||
The specified | |||||||||
.Fa clockid | |||||||||
is not supported. | |||||||||
.It Bq Er EINVAL | |||||||||
The provided | |||||||||
.Fa flags | |||||||||
are invalid. | |||||||||
.It Bq Er EMFILE | |||||||||
The per-process descriptor table is full. | |||||||||
.It Bq Er ENFILE | |||||||||
The system file table is full. | |||||||||
.It Bq Er ENOMEM | |||||||||
The kernel failed to allocate enough memory for the timer. | |||||||||
.El | |||||||||
.Pp | |||||||||
Both | |||||||||
.Fn timerfd_gettime | |||||||||
and | |||||||||
.Fn timerfd_settime | |||||||||
system calls fail if: | |||||||||
.Bl -tag -width Er | |||||||||
.It Bq Er EBADF | |||||||||
The provided | |||||||||
.Fa fd | |||||||||
is invalid. | |||||||||
.It Bq Er EFAULT | |||||||||
The addresses provided by | |||||||||
.Fa curr_value , | |||||||||
.Fa new_value , | |||||||||
or | |||||||||
.Fa old_value | |||||||||
are invalid. | |||||||||
.It Bq Er EINVAL | |||||||||
The provided | |||||||||
.Fa fd | |||||||||
is valid, but it was not generated by | |||||||||
.Fn timerfd_create . | |||||||||
Done Inline Actions
grahamperrin: | |||||||||
.El | |||||||||
.Pp | |||||||||
The following errors only apply to | |||||||||
.Fn timerfd_settime : | |||||||||
.Bl -tag -width Er | |||||||||
.It Bq Er EINVAL | |||||||||
The provided | |||||||||
.Fa flags | |||||||||
are invalid. | |||||||||
.It Bq Er EINVAL | |||||||||
A nanosecond field in the | |||||||||
.Fa new_value | |||||||||
argument specified a value less than zero or greater than or equal to 10^9. | |||||||||
.It Bq Er ECANCELED | |||||||||
Done Inline Actions
grahamperrin: | |||||||||
The timer 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 experienced a discontinuous change without | |||||||||
being read. | |||||||||
.El | |||||||||
.Pp | |||||||||
A read from a | |||||||||
.Nm | |||||||||
object fails if: | |||||||||
.Bl -tag -width Er | |||||||||
.It Bq Er EAGAIN | |||||||||
The timer's expiration counter is zero and the | |||||||||
.Nm | |||||||||
object is is set for non-blocking I/O. | |||||||||
.It Bq Er ECANCELED | |||||||||
The timer 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 experienced a discontinuous change. | |||||||||
.It Bq Er EINVAL | |||||||||
The size of the read buffer is not large enough to hold the | |||||||||
.Vt uint64_t | |||||||||
sized timer expiration counter. | |||||||||
.El | |||||||||
.Sh SEE ALSO | |||||||||
.Xr eventfd 2 , | |||||||||
.Xr kqueue 2 , | |||||||||
.Xr poll 2 , | |||||||||
.Xr read 2 , | |||||||||
.Xr timer_create 2 , | |||||||||
.Xr timer_gettime 2 , | |||||||||
.Xr timer_settime 2 | |||||||||
.Sh STANDARDS | |||||||||
The | |||||||||
.Nm | |||||||||
system calls originated from Linux and are non-standard. | |||||||||
.Sh HISTORY | |||||||||
The | |||||||||
gbeUnsubmitted Not Done Inline ActionsI would add an '.An -nosplit' after .Sh HISTORY. gbe: I would add an '.An -nosplit' after .Sh HISTORY. | |||||||||
.Nm | |||||||||
facility was originally ported to | |||||||||
.Fx Ns 's | |||||||||
Linux compatibility layer by Dmitry Chagin <dchagin@FreeBSD.org> in | |||||||||
gbeUnsubmitted Not Done Inline ActionsOn a separate line .An Dmitry Chagin Aq Mt dchagin@FreeBSD.org gbe: On a separate line
.An Dmitry Chagin Aq Mt dchagin@FreeBSD.org
| |||||||||
.Fx 12.0 . | |||||||||
It was revised and adapted to be native by Jake Freeland <jfree@FreeBSD.org> in | |||||||||
gbeUnsubmitted Not Done Inline ActionsOn a separaate line .An Jake Freeland Aq Mt jfree@FreeBSD.org gbe: On a separaate line
.An Jake Freeland Aq Mt jfree@FreeBSD.org | |||||||||
.Fx 14.0 . |
Might Normally or Typically be better?
(Because regularity can be time-related, i.e. "like clockwork".)