Re: [PATCH] difftime.3: be more explict about "difference".

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 9039 bytes --]

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@cs.ucla.edu>
> 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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]