From: Alejandro Colomar <alx@kernel.org>
To: Paul Eggert <eggert@cs.ucla.edu>
Cc: enh <enh@google.com>, linux-man <linux-man@vger.kernel.org>
Subject: Re: [PATCH] difftime.3: be more explict about "difference".
Date: Sat, 11 Nov 2023 21:08:43 +0100 [thread overview]
Message-ID: <ZU_fTMkp9Rzh2XcZ@debian> (raw)
In-Reply-To: <8360a79c-1ff0-4675-ba10-c57394bb2ac2@cs.ucla.edu>
[-- 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 --]
prev parent reply other threads:[~2023-11-11 20:08 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-09-19 20:59 [PATCH] difftime.3: be more explict about "difference" enh
2023-09-20 0:16 ` Paul Eggert
[not found] ` <CAJgzZorrrPLSJ-EWrsGcXg9y-ipVsX9FjHtdeh1x15yY7c-eHw@mail.gmail.com>
2023-09-20 20:10 ` Paul Eggert
2023-09-20 21:30 ` enh
2023-09-26 0:18 ` Alejandro Colomar
2023-11-08 21:10 ` Paul Eggert
2023-11-08 21:21 ` Alejandro Colomar
2023-11-09 6:28 ` Paul Eggert
2023-11-11 20:08 ` Alejandro Colomar [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ZU_fTMkp9Rzh2XcZ@debian \
--to=alx@kernel.org \
--cc=eggert@cs.ucla.edu \
--cc=enh@google.com \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).