From de1e91339b17171e020029e1d49f361aa66c5146 Mon Sep 17 00:00:00 2001
From: Warner Losh <imp@FreeBSD.org>
Date: Fri, 28 Jun 2024 10:55:23 -0600
Subject: [PATCH] clock_gettime: Catch up with the CLOCK_BOOTTIME changes

When CLOCK_BOOTTIME was made an alias for CLOCK_MONOTONIC, the man page
wasn't updated. Update to include the changed semantics (it was to be
better compatible with Linux). Clarify the details of these clocks.
Provide a reference to the UTC standard, and a clarifying remark
about leap second encoding (fun fact: POSIX provides no unique
value for these, nor definitive values to use).

Sponsored by:		Netflix
---
 lib/libsys/clock_gettime.2 | 42 +++++++++++++++++++++++++++-----------
 1 file changed, 30 insertions(+), 12 deletions(-)

diff --git a/lib/libsys/clock_gettime.2 b/lib/libsys/clock_gettime.2
index 82f6615e8b93..fcdc5be498f2 100644
--- a/lib/libsys/clock_gettime.2
+++ b/lib/libsys/clock_gettime.2
@@ -27,7 +27,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd October 27, 2023
+.Dd June 28, 2024
 .Dt CLOCK_GETTIME 2
 .Os
 .Sh NAME
@@ -67,18 +67,26 @@ as well as the following values:
 .It Dv CLOCK_REALTIME_PRECISE
 .It Dv CLOCK_REALTIME_FAST
 .It Dv CLOCK_REALTIME_COARSE
-Increments as a wall clock should.
+Increments in SI seconds like a wall clock.
+It uses a 1970 epoch and implements the UTC timescale.
+The count of physical SI seconds since 1970, adjusted by subtracting the number
+of positive leap seconds and adding the number of negative leap seconds.
+Behavior during a leap second is not defined by and POSIX standard.
 .It Dv CLOCK_MONOTONIC
 .It Dv CLOCK_MONOTONIC_PRECISE
 .It Dv CLOCK_MONOTONIC_FAST
 .It Dv CLOCK_MONOTONIC_COARSE
-Increments in SI seconds.
+.It Dv CLOCK_BOOTTIME
+Increments in SI seconds, even while the system is suspended.
+Its epoch is unspecified.
+The count is not adjusted by leap seconds.
+.Fx implements
 .It Dv CLOCK_UPTIME
 .It Dv CLOCK_UPTIME_PRECISE
 .It Dv CLOCK_UPTIME_FAST
-.It Dv CLOCK_BOOTTIME
-Starts at zero when the kernel boots and increments
-monotonically in SI seconds while the machine is running.
+Increments monotonically in SI seconds while the machine is running.
+The count is not adjusted by leap seconds.
+The epoch is unspecified.
 .It Dv CLOCK_VIRTUAL
 Increments only when
 the CPU is running in user mode on behalf of the calling process.
@@ -94,6 +102,7 @@ Returns the execution time of the calling thread.
 .El
 .Pp
 The clock IDs
+.Dv CLOCK_BOOTTIME ,
 .Dv CLOCK_REALTIME ,
 .Dv CLOCK_MONOTONIC ,
 and
@@ -122,7 +131,7 @@ systems.
 Finally,
 .Dv CLOCK_BOOTTIME
 is an alias for
-.Dv CLOCK_UPTIME
+.Dv CLOCK_MONOTONIC
 for compatibility with other systems and is unrelated to the
 .Fa kern.boottime
 .Xr sysctl 8 .
@@ -186,19 +195,28 @@ The
 and
 .Fn clock_getres
 system calls conform to
-.St -p1003.1b-93 .
+.St -p1003.1-2008 .
 The clock IDs
-.Dv CLOCK_REALTIME_FAST ,
-.Dv CLOCK_REALTIME_PRECISE ,
+.Dv CLOCK_BOOTTIME ,
 .Dv CLOCK_MONOTONIC_FAST ,
 .Dv CLOCK_MONOTONIC_PRECISE ,
+.Dv CLOCK_REALTIME_FAST ,
+.Dv CLOCK_REALTIME_PRECISE ,
+.Dv CLOCK_SECOND
 .Dv CLOCK_UPTIME ,
 .Dv CLOCK_UPTIME_FAST ,
-.Dv CLOCK_UPTIME_PRECISE ,
-.Dv CLOCK_SECOND
+and
+.Dv CLOCK_UPTIME_PRECISE
 are
 .Fx
 extensions to the POSIX interface.
+.Pp
+UTC is defined by ITU-R TF.460-6, Standard-frequency and time-signal emissions.
+However, the
+.Vt time_t
+type is a simple count that does not provide a unique encoding for leap seconds,
+nor a specification for what values should be used to encode a leap second.
+.Pp
 .Sh HISTORY
 The
 .Fn clock_gettime ,