From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS31976 209.132.180.0/23 X-Spam-Status: No, score=-4.0 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_EF,HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED,SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id CBD3C1F461 for ; Thu, 29 Aug 2019 01:09:50 +0000 (UTC) DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:subject:to:cc:references:from:message-id:date :mime-version:in-reply-to:content-type :content-transfer-encoding; q=dns; s=default; b=i0wBv6d4Ub8u91ft BUH7Se3Nli32kcZAL/ReJUG6O8s5YWn29PCRrSLMR3dd3coFT74kkRMr4SX2TK3Q ICJDzedG33anIyU833+MhcTcvhnnvtxV/T3MTWcJw953v/7YvzuvenXe/9+gTmbu HoKAIsianyQNWOQH+VxmY5ULRjc= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:subject:to:cc:references:from:message-id:date :mime-version:in-reply-to:content-type :content-transfer-encoding; s=default; bh=sGJj+JcEIkV3iLNr/AlbI9 KsOPE=; b=MvZ5yki9vogygt53geWczFylC+/fJwyLyMLzMzSdYMzSsOz9qphMTQ 3ExXF5FOl6OQAJjVp8OFsqR5btQaJZPWa6EAfxu4Q+1HPGHhafGchmYCIDu6wmPB 7R9fhht/Pto+rhtkE/5d7EEMlBM4nKOjxUI5NyPcj4LfY+ovRjovc= Received: (qmail 95934 invoked by alias); 29 Aug 2019 01:09:48 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Received: (qmail 95920 invoked by uid 89); 29 Aug 2019 01:09:48 -0000 Authentication-Results: sourceware.org; auth=none X-HELO: zimbra.cs.ucla.edu Subject: Re: [PATCH v2 10/10] Revise the documentation of simple calendar time. To: Zack Weinberg , libc-alpha@sourceware.org Cc: Joseph Myers , Florian Weimer , Lukasz Majewski , Alistair Francis , Stepan Golosunov , Arnd Bergmann , Adhemerval Zanella , Samuel Thibault References: <20190828153236.18229-1-zackw@panix.com> <20190828153236.18229-11-zackw@panix.com> From: Paul Eggert Message-ID: Date: Wed, 28 Aug 2019 18:09:38 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.8.0 MIME-Version: 1.0 In-Reply-To: <20190828153236.18229-11-zackw@panix.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit 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., ), 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).