man*/: Improve timestamp documentation

Improve discussion of leap seconds, year-2038 etc.

Cc: Elliott Hughes <enh@google.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>

4 files changed, 45 insertions, 33 deletions

diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
index 3ec6338cb..8457f6148 100644
--- a/man2/clock_getres.2
+++ b/man2/clock_getres.2
@@ -101,9 +101,17 @@ A settable system-wide clock that measures real (i.e., wall-clock) time.
 Setting this clock requires appropriate privileges.
 This clock is affected by discontinuous jumps in the system time
 (e.g., if the system administrator manually changes the clock),
-and by the incremental adjustments performed by
-.BR adjtime (3)
-and NTP.
+and by frequency adjustments performed by NTP and similar applications via
+.BR adjtime (3),
+.BR adjtimex (2),
+.BR clock_adjtime (2),
+and
+.BR ntp_adjtime (3).
+This clock normally counts the number of seconds since
+1970-01-01 00:00:00 Coordinated Universal Time (UTC)
+except that it ignores leap seconds;
+near a leap second it is typically adjusted by NTP
+to stay roughly in sync with UTC.
 .TP
 .BR CLOCK_REALTIME_ALARM " (since Linux 3.0; Linux-specific)"
 Like
@@ -126,9 +134,9 @@ and probably also architecture support for this flag in the
 .BR CLOCK_TAI " (since Linux 3.10; Linux-specific)"
 .\" commit 1ff3c9677bff7e468e0c487d0ffefe4e901d33f4
 A nonsettable system-wide clock derived from wall-clock time
-but ignoring leap seconds.
+but counting leap seconds.
 This clock does
-not experience discontinuities and backwards jumps caused by NTP
+not experience discontinuities or frequency adjustments caused by
 inserting leap seconds as
 .B CLOCK_REALTIME
 does.
@@ -146,9 +154,7 @@ The
 .B CLOCK_MONOTONIC
 clock is not affected by discontinuous jumps in the system time
 (e.g., if the system administrator manually changes the clock),
-but is affected by the incremental adjustments performed by
-.BR adjtime (3)
-and NTP.
+but is affected by frequency adjustments.
 This clock does not count time that the system is suspended.
 All
 .B CLOCK_MONOTONIC
@@ -170,9 +176,7 @@ and probably also architecture support for this flag in the
 Similar to
 .BR CLOCK_MONOTONIC ,
 but provides access to a raw hardware-based time
-that is not subject to NTP adjustments or
-the incremental adjustments performed by
-.BR adjtime (3).
+that is not subject to frequency adjustments.
 This clock does not count time that the system is suspended.
 .TP
 .BR CLOCK_BOOTTIME " (since Linux 2.6.39; Linux-specific)"
@@ -304,6 +308,17 @@ has disappeared after its character device was opened.
 The operation is not supported by the dynamic POSIX clock device
 specified.
 .TP
+.B EOVERFLOW
+The timestamp would not fit in
+.I time_t
+range.
+This can happen if an executable with 32-bit
+.I time_t
+is run on a 64-bit kernel when the time is 2038-01-19 03:14:08 UTC or later.
+However, when the system time is out of
+.I time_t
+range in other situations, the behavior is undefined.
+.TP
 .B EPERM
 .BR clock_settime ()
 does not have permission to set the clock indicated.
diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2
index 8c4ecc010..5bda50e18 100644
--- a/man2/clock_nanosleep.2
+++ b/man2/clock_nanosleep.2
@@ -59,7 +59,7 @@ This argument can have one of the following values:
 A settable system-wide real-time clock.
 .TP
 .BR CLOCK_TAI " (since Linux 3.10)"
-A system-wide clock derived from wall-clock time but ignoring leap seconds.
+A system-wide clock derived from wall-clock time but counting leap seconds.
 .TP
 .B CLOCK_MONOTONIC
 A nonsettable, monotonically increasing clock that measures time
diff --git a/man2/time.2 b/man2/time.2
index 9c67e656c..e85029db0 100644
--- a/man2/time.2
+++ b/man2/time.2
@@ -35,6 +35,17 @@ On error, \fI((time_t)\ \-1)\fP is returned, and
 is set to indicate the error.
 .SH ERRORS
 .TP
+.B EOVERFLOW
+The time cannot be represented as a
+.I time_t
+value.
+This can happen if an executable with 32-bit
+.I time_t
+is run on a 64-bit kernel when the time is 2038-01-19 03:14:08 UTC or later.
+However, when the system time is out of
+.I time_t
+range in other situations, the behavior is undefined.
+.TP
 .B EFAULT
 .I tloc
 points outside your accessible address space (but see BUGS).
@@ -60,29 +71,15 @@ in which case they are leap years.
 This value is not the same as the actual number of seconds between the time
 and the Epoch, because of leap seconds and because system clocks are not
 required to be synchronized to a standard reference.
-The intention is that the interpretation of seconds since the Epoch values be
-consistent; see POSIX.1-2008 Rationale A.4.15 for further rationale.
+Linux systems normally follow the POSIX requirement
+that this value ignore leap seconds,
+so that conforming systems interpret it consistently;
+see POSIX.1-2018 Rationale A.4.16.
 .P
-On Linux, a call to
-.BR time ()
-with
-.I tloc
-specified as NULL cannot fail with the error
-.BR EOVERFLOW ,
-even on ABIs where
-.I time_t
-is a signed 32-bit integer and the clock reaches or exceeds 2**31 seconds
-(2038-01-19 03:14:08 UTC, ignoring leap seconds).
-(POSIX.1 permits, but does not require, the
-.B EOVERFLOW
-error in the case where the seconds since the Epoch will not fit in
-.IR time_t .)
-Instead, the behavior on Linux is undefined when the system time is out of the
-.I time_t
-range.
 Applications intended to run after 2038 should use ABIs with
 .I time_t
-wider than 32 bits.
+wider than 32 bits; see
+.BR time_t (3type).
 .SS C library/kernel differences
 On some architectures, an implementation of
 .BR time ()
diff --git a/man2/timer_create.2 b/man2/timer_create.2
index 345cfd70c..1109858b8 100644
--- a/man2/timer_create.2
+++ b/man2/timer_create.2
@@ -96,7 +96,7 @@ The caller must have the
 capability in order to set a timer against this clock.
 .TP
 .BR CLOCK_TAI " (since Linux 3.10)"
-A system-wide clock derived from wall-clock time but ignoring leap seconds.
+A system-wide clock derived from wall-clock time but counting leap seconds.
 .P
 See
 .BR clock_getres (2)