Hi Paul, On Wed, Nov 08, 2023 at 10:28:51PM -0800, Paul Eggert wrote: > On 2023-11-08 13:21, Alejandro Colomar wrote: > > > We use all italics for inline code samples. See man-pages(7): > > OK, revised patch attached. > From 0870bd87ecbddffb8e536b1e7d635f3ac148d603 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. Patch applied. Thanks! <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=7f652f51d9526899a243cd875653b39b7ff49654> Cheers, Alex > --- > 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..1077b70e9 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 > +.I "difftime(b,\~a)" > +acts like > +.I "(b\-a)" > +except that the result does not overflow and is rounded to > +.IR 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 > -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
