From patchwork Mon Oct 24 12:51:10 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 59352 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 8E7423857342 for ; Mon, 24 Oct 2022 12:51:37 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 8E7423857342 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1666615897; bh=iRljfMu2/DrInRZkK6B4GIE/5yDfHTco8MJE8r5zDls=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:From; b=urcasAE0f3RAJP/vvyD6cEkSnVWN8JBURVP0Ovny/U6Xad/FX69BYzaGyRupqB8aE e9QzMv47nemMfNa14UJ3FkUCGixQYJGgWlYAZaQYEVM6RTdlERn3PyMo1G6HwSTVPa a/U4qWkUbO4pogoK89xFGGOYGZoPC55RrvHagTM0= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id E7FC13857B89 for ; Mon, 24 Oct 2022 12:51:14 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org E7FC13857B89 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-302-aLIYEcPCO0O1EQc6u5XbhA-1; Mon, 24 Oct 2022 08:51:13 -0400 X-MC-Unique: aLIYEcPCO0O1EQc6u5XbhA-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com [10.11.54.3]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id EAB04299E767 for ; Mon, 24 Oct 2022 12:51:12 +0000 (UTC) Received: from oldenburg.str.redhat.com (unknown [10.2.16.74]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 4FE091121315 for ; Mon, 24 Oct 2022 12:51:12 +0000 (UTC) To: libc-alpha@sourceware.org Subject: [PATCH] manual: Add more documentation for the tm_isdst member of struct tm Date: Mon, 24 Oct 2022 14:51:10 +0200 Message-ID: <87zgdl4c75.fsf@oldenburg.str.redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.1 on 10.11.54.3 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-11.2 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Florian Weimer via Libc-alpha From: Florian Weimer Reply-To: Florian Weimer Errors-To: libc-alpha-bounces+patchwork=sourceware.org@sourceware.org Sender: "Libc-alpha" The meaning of the member has changed implicitly since the IANA tz database started releasing zone data with negative DST. --- manual/time.texi | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) base-commit: 8775479804cfea2bbe4dcdf19d6589264c96d5fb diff --git a/manual/time.texi b/manual/time.texi index 0c7a942b4c..8632bd9b77 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -1010,10 +1010,24 @@ range @code{0} through @code{365}). @item int tm_isdst @cindex Daylight Saving Time @cindex summer time -This is a flag that indicates whether Daylight Saving Time is (or was, or -will be) in effect at the time described. The value is positive if -Daylight Saving Time is in effect, zero if it is not, and negative if the -information is not available. +This field serves multiple purposes. Historically, it is related to +daylight saving time. + +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. Historically, a positive +value indicates Daylight Saving Time is in effect, and a zero value that +it is not. However, this interpretation depends on the data present in +the system's time zone database. For example, for some time zones, the +role of positive and zero @code{tm_isdst} values are swapped in some +years. + +If the broken-down time is used as an input for a conversion function in +the other direction, such as @code{mktime}, a negative value can be +used to indicate that the information is not available. @item long int tm_gmtoff This field describes the time zone that was used to compute this @@ -1219,6 +1233,21 @@ simple time representation. It also normalizes the contents of the broken-down time structure, and fills in some components based on the values of the others. +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}. If @code{tm_isdst} is negative and +the calendar time is not ambiguous, @code{mktime} will use this time. +For ambiguous inputs with a negative @code{tm_isdst} value, an arbitrary +choice is made. If a non-negative value was specified for +@code{tm_isdst} and the system time zone database contains data +conflicting with the request in @code{tm_isdst}, @code{mktime} attempts +to adjust the computed result in an unspecified way. 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. + The @code{mktime} function ignores the specified contents of the @code{tm_wday}, @code{tm_yday}, @code{tm_gmtoff}, and @code{tm_zone} members of the broken-down time @@ -1226,7 +1255,9 @@ structure. It uses the values of the other components to determine the calendar time; it's permissible for these components to have unnormalized values outside their normal ranges. The last thing that @code{mktime} does is adjust the components of the @var{brokentime} -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. If the specified broken-down time cannot be represented as a simple time, @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify