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

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

[enh]

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

Personally I think the NOTES section should be moved to the main body
for clarity, but it seems worth being explicit that there's no leap
seconds magic here --- it's just "fancy subtraction".

Signed-off-by: Elliott Hughes <enh@google.com>
---
 man3/difftime.3 | 1 +
 1 file changed, 1 insertion(+)

[-- Attachment #2: 0001-difftime.3-be-more-explict-about-difference.patch --]
[-- Type: application/octet-stream, Size: 1065 bytes --]

From 433737b7f818c49ed4354eb178e85b46f69aa849 Mon Sep 17 00:00:00 2001
From: Elliott Hughes <enh@google.com>
Date: Tue, 19 Sep 2023 20:55:36 +0000
Subject: [PATCH] difftime.3: be more explict about "difference".

Personally I think the NOTES section should be moved to the main body
for clarity, but it seems worth being explicit that there's no leap
seconds magic here --- it's just "fancy subtraction".

Signed-off-by: Elliott Hughes <enh@google.com>
---
 man3/difftime.3 | 1 +
 1 file changed, 1 insertion(+)

diff --git a/man3/difftime.3 b/man3/difftime.3
index b85254cd0..dfb75251b 100644
--- a/man3/difftime.3
+++ b/man3/difftime.3
@@ -29,6 +29,7 @@ between time \fItime1\fP and time \fItime0\fP, represented as a
 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).
+This function does not take leap seconds into account.
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
 .BR attributes (7).
-- 
2.42.0.459.ge4e396fd5e-goog

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

[Paul Eggert]

On 2023-09-19 13:59, enh wrote:
> it seems worth being explicit that there's no leap
> seconds magic here --- it's just "fancy subtraction"

OK, but saying "This function does not take leap seconds into account" 
is not the same thing as saying it's just fancy subtraction. On my 
Fedora 38 box, if TZ='right/America/Los_Angeles' then time_t counts leap 
seconds so difftime does take leap seconds into account. So we'd need a 
different wording from what's proposed.

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

[Paul Eggert]

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

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.

[-- Attachment #2: 0001-Improve-timestamp-documentation.patch --]
[-- Type: text/x-patch, Size: 7911 bytes --]

From cac3dc30ceaafe0e0eb9f5157a2448534ae87563 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
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

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

[enh]

that looks really good. i'm glad i poked you with my terrible patch. thanks!

On Wed, Sep 20, 2023 at 1:11 PM Paul Eggert <eggert@cs.ucla.edu> wrote:
>
> 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.

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

[Alejandro Colomar]

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

Hi Paul,

On Wed, Sep 20, 2023 at 01:10:59PM -0700, Paul Eggert wrote:
> 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.

Please use semantic newlines.  See man-pages(7):

$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
   Use semantic newlines
       In the source of a manual page, new sentences should be started
       on  new  lines,  long  sentences  should be split into lines at
       clause breaks (commas, semicolons, colons, and so on), and long
       clauses should be split at phrase boundaries.  This convention,
       sometimes known as "semantic newlines", makes it easier to  see
       the  effect of patches, which often operate at the level of in‐
       dividual sentences, clauses, or phrases.

E.g., in here:

+and by frequency adjustments performed by NTP and similar
+applications via

or

+near a leap second it is typically adjusted by NTP to stay roughly in
+sync with UTC.

and definitely here:

+range.  This can happen if an executable with 32-bit


Thanks,
Alex

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Paul Eggert]

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

On 9/25/23 17:18, Alejandro Colomar wrote:
> Please use semantic newlines.
Sure, revised patch attached. (A bit delayed since this fell off the end 
of my queue....)

[-- Attachment #2: 0001-Improve-timestamp-documentation.patch --]
[-- Type: text/x-patch, Size: 7904 bytes --]

From 07866b20cbacb39146d513f85d43c4c7f97d56e1 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.
---
 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

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

[Alejandro Colomar]

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

Hi Paul!

On Wed, Nov 08, 2023 at 01:10:12PM -0800, Paul Eggert wrote:
> On 9/25/23 17:18, Alejandro Colomar wrote:
> > Please use semantic newlines.
> Sure, revised patch attached. (A bit delayed since this fell off the end of
> my queue....)

Heh, no problem!

Some small formatting comments below.

> From 07866b20cbacb39146d513f85d43c4c7f97d56e1 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.
> ---
>  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/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 )

We use all italics for inline code samples.  See man-pages(7):

     If the command is short, then it can be included  inline  in  the
     text,  in  italic  format, for example, man 7 man‐pages.  In this
     case, it may be worth using nonbreaking spaces (\[ti])  at  suit‐
     able places in the command.  Command options should be written in
     italics (e.g., -l).

     Expressions,  if  not written on a separate indented line, should
     be specified in italics.  Again, the use  of  nonbreaking  spaces
     may be appropriate if the expression is inlined with normal text.

The rest of the patch looks good to me.  Thanks!

Cheers,
Alex

> +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
> 


-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Paul Eggert]

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

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.

[-- Attachment #2: 0001-Improve-timestamp-documentation.patch --]
[-- Type: text/x-patch, Size: 7880 bytes --]

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.
---
 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

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

[Alejandro Colomar]

[-- 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 --]