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

[Zack Weinberg <zackw at panix dot com>]

On Tue, Aug 20, 2019 at 2:50 PM Paul Eggert <eggert@cs.ucla.edu> wrote:

BTW, thank you for reviewing documentation changes.

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

OK.

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

Thanks, I didn't know any of this detail.  I will make this change.

> > +@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".

*shrug* OK.

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

Blech, you're right.  This means this chunk of the manual has always
been wrong; it used to say "on GNU systems you can simply subtract
time_t values."

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

I might try to wordsmith this a little more but I'll make a change
along these lines.

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

I think it is actually quite important to make it clear in the
documentation of all three functions that time, gettimeofday, and
clock_gettime(CLOCK_REALTIME) all use the same "clock".  They can't be
set independently, "simple calendar times" retrieved from one of them
are directly comparable to times retrieved from another, and so on.

And gettimeofday may be formally obsolescent per POSIX, but
practically speaking it's going to be with us for many years to come.

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

Rounding where I did was intentional.  A 32.768kHz crystal oscillator
typically has a tolerance of ±20 parts per million, which _sounds_
tiny but works out to be more than half of the final digit of the
nominal frequency (32.768 ± 0.0006 kHz).  30.518µs is therefore
correctly rounded, giving any more digits would be false precision.
Using microseconds for the intermediate figure was also intentional;
it emphasizes that the resolution of the clock is a real number
independent of the units in which clock_getres reports it.

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

OK.

zw