The branch main has been updated by khng: URL: https://cgit.FreeBSD.org/src/commit/?id=c3f6c655dd155f4c84ce743c86e07d9f0b6b348a
commit c3f6c655dd155f4c84ce743c86e07d9f0b6b348a Author: Ka Ho Ng <[email protected]> AuthorDate: 2026-07-13 00:21:01 +0000 Commit: Ka Ho Ng <[email protected]> CommitDate: 2026-07-13 00:21:01 +0000 Add sbintime.9 manual page sbintime.9 is a manual page that documents the usage of sbintime_t and its helper functions. MFC after: 1 week Reviewed by: ziaee, markj Differential Revision: https://reviews.freebsd.org/D57931 --- share/man/man9/Makefile | 14 ++++ share/man/man9/callout.9 | 5 +- share/man/man9/microtime.9 | 3 +- share/man/man9/sbintime.9 | 171 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 190 insertions(+), 3 deletions(-) diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index e00a74a49a94..6df531d5300c 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -320,6 +320,7 @@ MAN= accept_filter.9 \ rtentry.9 \ runqueue.9 \ rwlock.9 \ + sbintime.9 \ sbuf.9 \ scheduler.9 \ SDT.9 \ @@ -1988,6 +1989,19 @@ MLINKS+=rwlock.9 rw_assert.9 \ rwlock.9 rw_wlock.9 \ rwlock.9 rw_wowned.9 \ rwlock.9 rw_wunlock.9 +MLINKS+=sbintime.9 bttosbt.9 \ + sbintime.9 mstosbt.9 \ + sbintime.9 nstosbt.9 \ + sbintime.9 sbintime_getsec.9 \ + sbintime.9 sbttobt.9 \ + sbintime.9 sbttoms.9 \ + sbintime.9 sbttons.9 \ + sbintime.9 sbttots.9 \ + sbintime.9 sbttotv.9 \ + sbintime.9 sbttous.9 \ + sbintime.9 tstosbt.9 \ + sbintime.9 tvtosbt.9 \ + sbintime.9 ustosbt.9 MLINKS+=sbuf.9 sbuf_bcat.9 \ sbuf.9 sbuf_bcopyin.9 \ sbuf.9 sbuf_bcpy.9 \ diff --git a/share/man/man9/callout.9 b/share/man/man9/callout.9 index 637049ec1ef5..aef4567764c2 100644 --- a/share/man/man9/callout.9 +++ b/share/man/man9/callout.9 @@ -27,7 +27,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd November 4, 2025 +.Dd July 4, 2026 .Dt CALLOUT 9 .Os .Sh NAME @@ -790,7 +790,8 @@ functions return a value of one if the callout was still pending when it was called, a zero if the callout could not be stopped and a negative one is it was either not running or has already completed. .Sh SEE ALSO -.Xr dtrace_callout_execute 4 +.Xr dtrace_callout_execute 4 , +.Xr sbintime 9 .Sh HISTORY .Fx initially used the long standing diff --git a/share/man/man9/microtime.9 b/share/man/man9/microtime.9 index d703d7b572d7..42c7000f0110 100644 --- a/share/man/man9/microtime.9 +++ b/share/man/man9/microtime.9 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd September 16, 2004 +.Dd July 4, 2026 .Dt MICROTIME 9 .Os .Sh NAME @@ -100,6 +100,7 @@ execution time. .Xr getnanouptime 9 , .Xr microuptime 9 , .Xr nanouptime 9 , +.Xr sbintime 9 , .Xr tvtohz 9 .Sh HISTORY The diff --git a/share/man/man9/sbintime.9 b/share/man/man9/sbintime.9 new file mode 100644 index 000000000000..2b101c04ef01 --- /dev/null +++ b/share/man/man9/sbintime.9 @@ -0,0 +1,171 @@ +.\" +.\" Copyright (c) 2026 Ka Ho Ng +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd July 12, 2026 +.Dt SBINTIME 9 +.Os +.Sh NAME +.Nm sbintime_t , +.Nm sbintime_getsec , +.Nm bttosbt , +.Nm sbttobt , +.Nm sbttons , +.Nm nstosbt , +.Nm sbttous , +.Nm ustosbt , +.Nm sbttoms , +.Nm mstosbt , +.Nm sbttots , +.Nm tstosbt , +.Nm sbttotv , +.Nm tvtosbt +.Nd Q32.32 fixed point representation of time +.Sh SYNOPSIS +.In sys/types.h +.In sys/time.h +.Vt typedef __int64_t __sbintime_t ; +.Vt typedef __sbintime_t sbintime_t ; +.Fd #define SBT_1S ((sbintime_t)1 << 32) +.Fd #define SBT_1M (SBT_1S * 60) +.Fd #define SBT_1MS (SBT_1S / 1000) +.Fd #define SBT_1US (SBT_1S / 1000000) +.Fd #define SBT_1NS (SBT_1S / 1000000000) +.Ft int +.Fn sbintime_getsec "sbintime_t sbt" +.Ft sbintime_t +.Fn bttosbt "const struct bintime bt" +.Ft struct bintime +.Fn sbttobt "sbintime_t sbt" +.Ft int64_t +.Fn sbttons "sbintime_t sbt" +.Ft sbintime_t +.Fn nstosbt "int64_t ns" +.Ft int64_t +.Fn sbttous "sbintime_t sbt" +.Ft sbintime_t +.Fn ustosbt "int64_t us" +.Ft int64_t +.Fn sbttoms "sbintime_t sbt" +.Ft sbintime_t +.Fn mstosbt "int64_t ms" +.Ft struct timespec +.Fn sbttots "sbintime_t sbt" +.Ft sbintime_t +.Fn tstosbt "struct timespec ts" +.Ft struct timeval +.Fn sbttotv "sbintime_t sbt" +.Ft sbintime_t +.Fn tvtosbt "struct timeval tv" +.Sh DESCRIPTION +The +.Vt sbintime_t +type is a Q32.32 fixed point representation of time. +The high 32-bit integral bits specify the number of seconds, +and the low 32-bit fractional bits specify the sub-second portion. +Since the lower 32 bits are counting with a base unit of 1/2^32 seconds, +.Ql (sbintime_t)0x1 +is just under 250 picoseconds. +.Pp +All of the conversion functions are designed to do the conversion without large +truncation errors that are possible with naive math. +.\" Begin of helper functions subsection +.Bl -tag -width indent +.It Fn sbintime_getsec sbt +Return the whole number of seconds from a +.Vt sbintime_t +specified by the +.Fa sbt +argument. +.It Fn bttosbt bt +Convert a +.Vt struct bintime +specified by the +.Fa bt +argument to a +.Vt sbintime_t . +.It Fn sbttobt sbt +Convert a +.Vt sbintime_t +specified by the +.Fa sbt +argument to a +.Vt "struct bintime" . +.It Fn sbttons sbt +Convert a +.Vt sbintime_t +specified by the +.Fa sbt +argument to the number of nanoseconds. +.It Fn nstosbt ns +Convert the number of nanoseconds specified by the +.Fa ns +argument to a +.Vt sbintime_t . +.It Fn sbttous sbt +Convert a +.Vt sbintime_t +specified by the +.Fa sbt +argument to the number of microseconds. +.It Fn ustosbt us +Convert the number of microseconds specified by the +.Fa us +argument to a +.Vt sbintime_t . +.It Fn sbttoms sbt +Convert a +.Vt sbintime_t +specified by the +.Fa sbt +argument to the number of milliseconds. +.It Fn mstosbt ms +Convert the number of milliseconds specified by the +.Fa ms +argument to a +.Vt sbintime_t . +.It Fn sbttots sbt +Convert a +.Vt sbintime_t +specified by the +.Fa sbt +argument to a +.Vt "struct timespec" . +.It Fn tstosbt ts +Convert a +.Vt "struct timespec" +specified by the +.Fa ts +argument to a +.Vt sbintime_t . +.It Fn sbttotv sbt +Convert a +.Vt sbintime_t +specified by the +.Fa sbt +argument to a +.Vt "struct timeval" . +.It Fn tvtosbt tv +Convert a +.Vt "struct timeval" +specified by the +.Fa tv +argument to a +.Vt sbintime_t . +.El +.\" End of helper functions subsection +.Sh SEE ALSO +.Xr bintime 9 , +.Xr callout 9 , +.Xr tvtohz 9 +.Sh HISTORY +The +.Nm sbintime_t +type and most of the helper functions first appeared in +.Fx 10.0 . +The Xstosbt functions first appeared in +.Fx 12.0 . +.Sh AUTHORS +This manual page was written by +.An Ka Ho Ng Aq Mt [email protected] .
