From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from zimbra.cs.ucla.edu (zimbra.cs.ucla.edu [131.179.128.68]) by sourceware.org (Postfix) with ESMTPS id 4B6C33858403 for ; Mon, 24 Oct 2022 19:45:01 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 4B6C33858403 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=cs.ucla.edu Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=cs.ucla.edu Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 6E844160092; Mon, 24 Oct 2022 12:45:00 -0700 (PDT) Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id vrQ8dFMJYkjd; Mon, 24 Oct 2022 12:44:59 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 594F6160095; Mon, 24 Oct 2022 12:44:59 -0700 (PDT) DKIM-Filter: OpenDKIM Filter v2.9.2 zimbra.cs.ucla.edu 594F6160095 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cs.ucla.edu; s=78364E5A-2AF3-11ED-87FA-8298ECA2D365; t=1666640699; bh=ZWvzeRVXL4mEXEAwjCa+ImeuvfthlbwKa83D+yK+7aE=; h=Message-ID:Date:MIME-Version:To:From:Subject:Content-Type: Content-Transfer-Encoding; b=aMRi14Vq0lx2T4TW/tZpYSgbCPcmxoNfVXd1WyMtTPEJ6xjHDNApeXSeHDo2LG9H3 sRpa/JPH7GG63YpFTgcb6lmGLqbqppAVQZ8Ad8zzXw7DdrF7n9zOj9pL7MEyrxWQ6Z yGFXATWJnWSrwgrkFlNhKj+oM0P+lwYLXdLRSA1A= X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id bYsMnDs-XzKK; Mon, 24 Oct 2022 12:44:59 -0700 (PDT) Received: from [192.168.1.9] (cpe-172-91-119-151.socal.res.rr.com [172.91.119.151]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 32C36160092; Mon, 24 Oct 2022 12:44:59 -0700 (PDT) Message-ID: <806730c1-81d4-6601-8ecf-d1b8b322c324@cs.ucla.edu> Date: Mon, 24 Oct 2022 12:44:58 -0700 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.3.3 Content-Language: en-US To: Florian Weimer , libc-alpha@sourceware.org References: <87zgdl4c75.fsf@oldenburg.str.redhat.com> From: Paul Eggert Organization: UCLA Computer Science Department Subject: Re: [PATCH] manual: Add more documentation for the tm_isdst member of struct tm In-Reply-To: <87zgdl4c75.fsf@oldenburg.str.redhat.com> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-3.1 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,JMQ_SPF_NEUTRAL,NICE_REPLY_A,SPF_HELO_NONE,SPF_PASS,TXREP autolearn=no autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: Thanks for looking into the documentation problem here. I hope you don't mind some detailed comments. On 2022-10-24 05:51, Florian Weimer via Libc-alpha wrote: > +This field serves multiple purposes. Historically, it is related to > +daylight saving time. The field is still related to daylight saving time, as described below, so I suggest rewording this to something like: ----- This field indicates whether the daylight saving time is in effect. ----- > +When clocks move backwards (due to time zone changes, or due to the > +transition from daylight saving time to standard time), functions > +converting to a broken-down time value such as @code{localtime} may > +produce the same @code{tm_hour}, @code{tm_min}, @code{tm_sec} values for > +different input times. The @code{tm_isdst} field is used to > +disambiguate these different points in time. Unfortunately tm_dst cannot always disambiguate these points. Although disambiguation works when the ambiguity is due to a DST fall-back transition, it cannot disambiguate in other cases. For example, with TZ='Europe/Volgograd', the timestamp 2020-12-27 01:30 is ambiguous but both times have tm_isdst == 0; this is because Volgograd permanently switched from +04 to +03 that day so standard time was in use both before and after the clocks were changed. Historically, a positive > +value indicates Daylight Saving Time is in effect, and a zero value that > +it is not. That's still the case. POSIX sometimes calls it the "Daylight Savings" flag, and sometimes "alternative time"; but either way it's the same thing. > However, this interpretation depends on the data present in > +the system's time zone database. It's not simply TZDB; it can happen even if there is no TZDB installed, with a POSIX TZ string like TZ='IST-1GMT0,M10.5.0,M3.5.0/1' (valid for timestamps in Ireland after the year 1996). > For example, for some time zones, the > +role of positive and zero @code{tm_isdst} values are swapped in some > +years. The role is not swapped. Some TZ settings have a negative DST offset; that is, their UT offset is smaller when tm_isdst is positive, than when tm_isdst is zero. Perhaps rephrase the above to something like the following? ----- A positive value indicates that daylight saving time (sometimes called "alternative time") is in effect. Although this is typically an hour further east of Greenwich than standard time, other DST offsets from standard time are possible, and the DST offset need not be positive in locations that observe DST in winter or during holidays. In practice, the @code{tm_isdst} value is mostly obsolescent. It should not be used to calculate time zone names or UT offsets, as the @code{tm_zone} and @code{tm_gmtoff} values do this more easily and more reliably. Its only remaining role is as input to @code{mktime}, where it can disambiguate timestamps, though unfortunately this does not work in all cases. ---- > +If the @code{tm_isdst} member is not negative, its value should match a > +previous result from @code{localtime}, @code{localtime_r}, > +@code{gmtime}, or @code{gmtime_r}. This requirement is not in POSIX or the C Standard. Shouldn't we reword this to merely talk about positive versus zero versus negative values for tm_isdst? > +... Given that the > +system time zone database does not necessarily map @code{tm_isdst} > +values to popular notions of daylight saving time and standard time, > +using a negative @code{tm_isdst} value as input to @code{mktime} is > +generally preferable to letting the user input whether daylight saving > +time is in effect or not. Not sure I'd use the word "popular" here. Also, this should mention issues like the Volgograd one. How about replacing the above with the following: ----- When your application does not know whether an ambiguous timestamp occurred before or after the clock moved back due to a DST fallback transition, it can use a negative @code{tm_isdst} to let @code{mktime} deduce which of the two values to return. Unfortunately, this approach does not work in the rarer case where the clock moves back due to a permanent change in the time zone; to avoid ambiguity in this situation you can instead record the timestamp in UTC and convert to local time for display only. ----- > -structure, including the members that were initially ignored. > +structure, including the members that were initially ignored. The > +@code{tm_isdst} member is updated to reflect the time zone status of the > +system time zone database at the specified time. Since there may be no TZDB installed, I suggest rewording the last phrase to "to reflect whether daylight saving time is in effect".