On 2023-09-20 07:13, enh wrote:
that's why i added you --- to suggest better wording 🤣
I noodled around a bit. There are several mistakes about timestamps in the man pages. difftime, for example, copies the C standard's "calendar time" wording but in Linux it's just a seconds count and need not have anything to do with 1970 or any other calendar. And there are lots of other howlers about leap seconds and 2038, improperly parenthesized macros, unclear wording like "incremental adjustments", out-of-date references, etc.
Attached is a proposed patch to fix the problems I found before I ran out of time. I haven't checked formatting. I'm sure it could be improved further.
From cac3dc30ceaafe0e0eb9f5157a2448534ae87563 Mon Sep 17 00:00:00 2001 From: Paul Eggert <eggert@xxxxxxxxxxx> Date: Wed, 20 Sep 2023 12:57:36 -0700 Subject: [PATCH] Improve timestamp documentation Improve discussion of leap seconds, year-2038 etc. --- man2/clock_getres.2 | 37 ++++++++++++++++++++++++++----------- man2/clock_nanosleep.2 | 2 +- man2/time.2 | 36 ++++++++++++++++-------------------- man2/timer_create.2 | 2 +- man3/difftime.3 | 23 +++++++---------------- man3type/time_t.3type | 2 ++ 6 files changed, 53 insertions(+), 49 deletions(-) diff --git a/man2/clock_getres.2 b/man2/clock_getres.2 index 1ce618c00..939acfa11 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 38abca6de..e809333b6 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 65db67a34..4a0918d33 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,14 @@ 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. .PP -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 a3987bb1e..ea4947299 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. .PP See .BR clock_getres (2) diff --git a/man3/difftime.3 b/man3/difftime.3 index f1eec673b..7da24a34c 100644 --- a/man3/difftime.3 +++ b/man3/difftime.3 @@ -26,9 +26,13 @@ The function returns the number of seconds elapsed between time \fItime1\fP and time \fItime0\fP, represented as a .IR double . -Each of the times is specified in calendar time, which means its -value is a measurement (in seconds) relative to the -Epoch, 1970-01-01 00:00:00 +0000 (UTC). +Each time is a count of seconds. +.PP +.BI "difftime( time1 ", " time0 ) +acts like +.BI ( time1 \- time2 ) +except that the result does not overflow and is rounded to +.BR double . .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7). @@ -47,19 +51,6 @@ T} Thread safety MT-Safe C11, POSIX.1-2008. .SH HISTORY POSIX.1-2001, C89, SVr4, 4.3BSD. -.SH NOTES -On a POSIX system, -.I time_t -is an arithmetic type, and one could just -define -.PP -.in +4n -.EX -#define my_difftime(t1,t0) (double)(t1 \- t0) -.EE -.in -.PP -when the possible overflow in the subtraction is not a concern. .SH SEE ALSO .BR date (1), .BR gettimeofday (2), diff --git a/man3type/time_t.3type b/man3type/time_t.3type index 2ba4f6833..88c6444b3 100644 --- a/man3type/time_t.3type +++ b/man3type/time_t.3type @@ -81,6 +81,8 @@ the width of .I time_t can be controlled with the feature test macro .BR _TIME_BITS . +See +.BR feature_test_macros (7). .PP The following headers also provide .IR time_t : -- 2.41.0
