[PATCH v2 10/10] Revise the documentation of simple calendar time.

[Paul Eggert]

Zack Weinberg wrote:

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

As we've discussed recently (e.g., 
<https://sourceware.org/ml/libc-alpha/2019-08/msg00755.html>), the 'time' 
function does not necessarily use the same clock as clock_gettime 
(CLOCK_REALTIME). On GNU/Linux it appears to use the CLOCK_REALTIME_COARSE 
clock, though I doubt whether that's guaranteed everywhere. So I suggest 
changing that last sentence to:

This function uses a clock close to the clocks of @w{@samp{clock_gettime 
(CLOCK_REALTIME)}} and of @code{gettimeofday} (see below), but the three clocks 
are not necessarily in lock-step, and precise timestamp comparison is reliable 
only when timestamps come from the same clock.

> +@deftypevr Macro clockid_t CLOCK_REALTIME
> +@standards{POSIX.1, time.h}
> +System-wide clock measuring calendar time.  This clock reports the
> +same time as @code{time} (above) and @code{gettimeofday} (below) and
> +uses the POSIX epoch, 00:00:00 on January 1, 1970, Coordinated
> +Universal Time.

Similarly, change the last sentence to:

This clock uses the POSIX epoch, 00:00:00 on January 1, 1970, Coordinated 
Universal Time. It is close to, but not necessarily in lock-step with, the 
clocks of @code{time} (above) and of @code{gettimeofday} (below).

> +@code{struct timeval}.  @code{gettimeofday} uses the same clock as
> +@code{time} and @w{@samp{clock_gettime (CLOCK_REALTIME)}}.

Similarly, change this sentence to:

The clock of @code{gettimeofday} is close to, but not necessarily in lock-step 
with, the clocks of @code{time} and of @w{@samp{clock_gettime (CLOCK_REALTIME)}} 
(see above).