This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH v2 10/10] Revise the documentation of simple calendar time.
- From: Paul Eggert <eggert at cs dot ucla dot edu>
- To: Zack Weinberg <zackw at panix dot com>, libc-alpha at sourceware dot org
- Cc: Joseph Myers <joseph at codesourcery dot com>, Florian Weimer <fweimer at redhat dot com>, Lukasz Majewski <lukma at denx dot de>, Alistair Francis <alistair23 at gmail dot com>, Stepan Golosunov <stepan at golosunov dot pp dot ru>, Arnd Bergmann <arnd at arndb dot de>, Adhemerval Zanella <adhemerval dot zanella at linaro dot org>, Samuel Thibault <samuel dot thibault at ens-lyon dot org>
- Date: Wed, 28 Aug 2019 18:09:38 -0700
- Subject: Re: [PATCH v2 10/10] Revise the documentation of simple calendar time.
- References: <20190828153236.18229-1-zackw@panix.com> <20190828153236.18229-11-zackw@panix.com>
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).