On 9/25/23 17:18, Alejandro Colomar wrote:
Sure, revised patch attached. (A bit delayed since this fell off the end of my queue....)Please use semantic newlines.
From 07866b20cbacb39146d513f85d43c4c7f97d56e1 Mon Sep 17 00:00:00 2001 From: Paul Eggert <eggert@xxxxxxxxxxx> Date: Wed, 8 Nov 2023 13:05:57 -0800 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 | 37 +++++++++++++++++-------------------- man2/timer_create.2 | 2 +- man3/difftime.3 | 23 +++++++---------------- man3type/time_t.3type | 2 ++ 6 files changed, 54 insertions(+), 49 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) diff --git a/man3/difftime.3 b/man3/difftime.3 index 5504ea8ff..7f129d30d 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. +.P +.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 -.P -.in +4n -.EX -#define my_difftime(t1,t0) (double)(t1 \- t0) -.EE -.in -.P -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 fb788b823..0dba4afb0 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). .P The following headers also provide .IR time_t : -- 2.41.0
