From nobody Thu Aug 24 20:29:49 2023 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4RWvp60XDdz4rY05; Thu, 24 Aug 2023 20:29:50 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4RWvp56lfGz3M5w; Thu, 24 Aug 2023 20:29:49 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1692908990; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=bluWO9DD4FBsr8xKOISvH8nmEz30Q9SXe4Ifa2oTyko=; b=CQEXhfHxlgMiNEbQUprpE1WP6lzhWvzEf5g4Rp/kfkzPIaO1MrwOAADVLe3zmGCxthFHjt yUnLp/s15ZejuN+OFX7FSfZ8TK63AXTHltDsbDZf2J4CwoIEVMbx0xFGA1ZEfEzlXleWP4 HTIXp7nRLa/adOdD6FCI0TwgHl/tfMNfVsB1u4k1t6nhj3Y0sQoyUzKyyXB+N5Q87jYl1G KLYskmkm0Z2X+mXVt0xF6krYVYo4whvFB+Ls0fMiVE25x6UAuGu53E4Bh6K5hIliAJuWc+ vNUgywNOHFKuAp5mHhF778p2Ys1oXj2JkQ95oDtjahYX5/DMcqyHL+KHuO74ig== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1692908990; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=bluWO9DD4FBsr8xKOISvH8nmEz30Q9SXe4Ifa2oTyko=; b=nZS6bSFhISWyIcTjSvF8dxBdkP9dq5keionJsoSvqldaUfJs5hIrJaRX8J7zEQFJTUNPoA jXaO7F2/82Njr0X3w0ox2dvLGYkjbnL/e4XIRa7TpVtWn45ztBU8lKJvOXio4eyMkG8ZT2 OPramdnJFqytkaw5p8t4vxMedcisiKS1j9eSsGa5UNf9p99gRIXWeE2q9QtPWH5BZs9YW4 cjiUPpW2LMDXPxu2TJ6DF0sFPqD0uy6h5+Urvqt76y86Ajcw92cfv2KBNkxQvSu4XRu9CK JKGkD1ZxpsH+8T4U8xQBhziKFOwDmeRbvTjrkK8nCclN5pKmjMpWn3gElfeHcQ== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1692908990; a=rsa-sha256; cv=none; b=yAD5oG5m8xMPyDj62ngAA4sSCrlpUzYuRiHxbJQZveCUQqOO4TDrTV3WVZWGUZkpVHCu9O +n6gTTUFF1xEwwBg0qpf9ikkaHlC32EmG9igyt9kKtlyH6wX+C/Kx6PPM8LEIBMop1LbNJ Tj48kjC8PrFjZuGY0TWIFhqWS+4tbOIRyJMPFAKwUuw/uXO9usYUq7TUOoNfayC8ZnOsW2 w3AD5YZbAWnCBM705W3CaB6j8A8y4WjjT4JaTpB6OseBdMliWdYB5JBCH2wzDFietgaaDg sUfjKTJMJ51g4Mu5EGthpJEYPo0RxplcsBn/FDQ2aZ3QNtX4LsHA1odwNnp3OA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4RWvp54l7tzh1y; Thu, 24 Aug 2023 20:29:49 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 37OKTn9j091797; Thu, 24 Aug 2023 20:29:49 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 37OKTnBU091794; Thu, 24 Aug 2023 20:29:49 GMT (envelope-from git) Date: Thu, 24 Aug 2023 20:29:49 GMT Message-Id: <202308242029.37OKTnBU091794@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Warner Losh Subject: git: 8544651dc509 - main - timerfd: Add manual page. List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: imp X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 8544651dc509dadb8b20d1aeb41b3be4efbdf6dd Auto-Submitted: auto-generated The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=8544651dc509dadb8b20d1aeb41b3be4efbdf6dd commit 8544651dc509dadb8b20d1aeb41b3be4efbdf6dd Author: Jake Freeland AuthorDate: 2023-08-24 19:59:20 +0000 Commit: Warner Losh 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 +.\" +.\" 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 .