git: 8544651dc509 - main - timerfd: Add manual page.

Go to: [ bottom of page ] [ top of archives ] [ this month ]
From: Warner Losh <imp_at_FreeBSD.org>
Date: Thu, 24 Aug 2023 20:29:49 UTC
The branch main has been updated by imp:

URL: https://cgit.FreeBSD.org/src/commit/?id=8544651dc509dadb8b20d1aeb41b3be4efbdf6dd

commit 8544651dc509dadb8b20d1aeb41b3be4efbdf6dd
Author:     Jake Freeland <jfree@freebsd.org>
AuthorDate: 2023-08-24 19:59:20 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
CommitDate: 2023-08-24 20:29:06 +0000

    timerfd: Add manual page.
    
    This manual page accompanies the timerfd system calls.
    
    Reviewed by: imp
    Differential Revision: https://reviews.freebsd.org/D40218
---
 lib/libc/sys/Makefile.inc |   4 +
 lib/libc/sys/timerfd.2    | 340 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 344 insertions(+)

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index 0fdcbbf04b07..480002f9875e 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -345,6 +345,7 @@ MAN+=	abort2.2 \
 	timer_create.2 \
 	timer_delete.2 \
 	timer_settime.2 \
+	timerfd.2 \
 	truncate.2 \
 	umask.2 \
 	undelete.2 \
@@ -496,6 +497,9 @@ MLINKS+=symlink.2 symlinkat.2
 MLINKS+=syscall.2 __syscall.2
 MLINKS+=timer_settime.2 timer_getoverrun.2 \
 	timer_settime.2 timer_gettime.2
+MLINKS+=timerfd.2 timerfd_create.2 \
+	timerfd.2 timerfd_gettime.2 \
+	timerfd.2 timerfd_settime.2
 MLINKS+=thr_kill.2 thr_kill2.2
 MLINKS+=truncate.2 ftruncate.2
 MLINKS+=unlink.2 unlinkat.2
diff --git a/lib/libc/sys/timerfd.2 b/lib/libc/sys/timerfd.2
new file mode 100644
index 000000000000..e5dab05821bd
--- /dev/null
+++ b/lib/libc/sys/timerfd.2
@@ -0,0 +1,340 @@
+.\" 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 .
+Normally,
+.Fa new_value
+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 call fails if:
+.Bl -tag -width Er
+.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 was not generated by
+.Fn timerfd_create .
+.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
+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
+.An -nosplit
+The
+.Nm
+facility was originally ported to
+.Fx Ns 's
+Linux compatibility layer by
+.An Dmitry Chagin Aq Mt dchagin@FreeBSD.org
+in
+.Fx 12.0 .
+It was revised and adapted to be native by
+.An Jake Freeland Aq Mt jfree@FreeBSD.org
+in
+.Fx 14.0 .