Re: [PATCH 12/12] Revise the documentation of ‘simple calendar time’.

[Paul Eggert <eggert at cs dot ucla dot edu>]

Zack Weinberg wrote:
> +@code{clock_t} is used to measure processor and CPU time.  Its values
> +are counts of @dfn{clock ticks} since some arbitrary event.  The
> +number of clock ticks per second is system-specific.

Also mention here that ISO C and POSIX both say that clock_t may be an an 
integer or a floating-point type.


> +POSIX says that @code{time_t} values do not include leap seconds, but
> +some systems interpret them as including leap seconds when the
> +@code{TZ} environment variable is set a certain way
> +(@pxref{TZ Variable}).

This gives the misleading impression that one can set 
TZ='right/America/Los_Angeles' (or whatever) on a system where the kernel 
follows POSIX rules, and your process will then be consistent within itself and 
will be leap-second aware. This doesn't work, as some conversions will be messed 
up due to libc's references to files like /usr/share/zoneinfo/posixrules and 
/usr/share/zoneinfo/UTC0 that still disregard leap seconds (the latter file 
typically isn't even installed on typical glibc systems, which means no leap 
seconds will be used). For example, on Fedora, this shell script:

  for cmd in 'date' 'date -u'; do
    for prefix in '' right/; do
      TZ=${prefix}America/Los_Angeles $cmd
    done
  done

outputs this:

  Tue Aug 20 11:35:41 PDT 2019
  Tue Aug 20 11:35:14 PDT 2019
  Tue Aug 20 18:35:41 UTC 2019
  Tue Aug 20 18:35:41 UTC 2019

where plain "date" respects the TZ leap second setting, but "date -u" ignores it 
and always uses POSIX time_t.

If you want leap seconds with glibc, you must arrange for the kernel clock to 
count leap seconds and you must discard the normal /usr/share/zoneinfo directory 
and replace it with leap-second-aware TZif files.  So I suggest replacing the 
above with this:

POSIX says that @code{time_t} values do not include leap seconds, but
some systems interpret them as including leap seconds if configured appropriately.


> +@deftypefun double difftime (time_t @var{end}, time_t @var{begin})
> +@standards{ISO, time.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +The @code{difftime} function returns the number of seconds of elapsed
> +time from calendar time @var{begin} to calendar time @var{end}, as
> +a value of type @code{double}.  The calculation is unaware of whether
> +or not @var{begin} and @var{end} are meant to include leap seconds.

Remove "or not".

> +On POSIX-conformant systems, @samp{difftime (end, begin)} produces the
> +same result as the expression @samp{(double)(end - begin)}.  But on
> +other systems, @code{time_t} values might be encoded in a way that
> +prevents subtraction from working directly.

Not so: for example, on a 64-bit time_t POSIX host with the extreme values begin 
== -2**63 and end == (2**63 - 1), (end - begin) typically overflows and yields 
-1 whereas difftime (end, begin) typically rounds the mathematically-correct 
value (2**64 - 1) to double as 2**64. I suggest something like this instead:

On POSIX-conformant systems, @samp{difftime (end, begin)} is the
mathematical difference between @var{end} and @var{begin}, converted to
@samp{double}; although this computation does not suffer from integer overflow
the result is not exact if the difference is large enough.  On
other systems, @code{time_t} values might be encoded in a way that
prevents subtraction from working directly.


> +@deftypefun time_t time (time_t *@var{result})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +This is the simplest function for getting the current calendar time.
> +It returns the calendar time as a value of type @code{time_t}; on
> +POSIX systems, that means it has a resolution of one second.  It
> +uses the same clock as @w{@samp{clock_gettime (CLOCK_REALTIME)}}
> +and @code{gettimeofday} (see below).

Remove "and @code{gettimeofday}", as we shouldn't be cluttering the manual with 
unnecessary references to an obsolescent function.

> +System-wide clock measuring calendar time.  This clock reports the
> +same time as @code{time} (above) and @code{gettimeofday} (below)

Similarly, remove "and @code{gettimeofday} (below)" here.


> +For instance, if the clock hardware for @code{CLOCK_REALTIME}
> +uses a quartz crystal that oscillates at 32.768 kHz,
> +then its resolution would be 30.518 microseconds,

Change "30.518 microseconds" to "30517.578125 nanoseconds", the exact value and 
a sharper way to explain the rounding that occurs with the "30518" that follows.


> +Because simple calendar times are independent of time zone, this
> +function should not be used when the time zone changes (e.g.@: if the
> +computer is physically moved from one zone to another).  Instead, use
> +the facilities described in @ref{Time Zone Functions} (but see below
> +for an exception).

I suggest removing "(but see below for an exception)", as it's confusing here. 
The later section can say that it's an exception.