From patchwork Sun Jan 5 05:56:42 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paul Eggert X-Patchwork-Id: 104045 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 5A57D3858C54 for ; Sun, 5 Jan 2025 06:07:45 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 5A57D3858C54 Authentication-Results: sourceware.org; dkim=pass (2048-bit key, unprotected) header.d=cs.ucla.edu header.i=@cs.ucla.edu header.a=rsa-sha256 header.s=9D0B346E-2AEB-11ED-9476-E14B719DCE6C header.b=EMX0fECW X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail.cs.ucla.edu (mail.cs.ucla.edu [131.179.128.66]) by sourceware.org (Postfix) with ESMTPS id 755FB3858D39 for ; Sun, 5 Jan 2025 05:58:32 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 755FB3858D39 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 ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 755FB3858D39 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=131.179.128.66 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1736056712; cv=none; b=IzWMhzZpNha1P3R0G0OcCAM4gqbIMbERtpfrSkXE2enhtplQLrEBATMODgKHpc0z07CFC9QeYWDEnITsNRBzMPmo3dvdyxnEsMJS33ELRQOMdYAmx1N2VIyS3lagq8gwFlBJeJyGuymTkqmX01XZatFMOoRXa/rUdxGm0qLUPcg= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1736056712; c=relaxed/simple; bh=wvZRt6TsI622ZyJO7WmVw7NXXL4mMdV+K+lHY9OWkyE=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=grQOCRbUDH3FJJj9dj1XReZI5peJyZqkxGkD1fBXoN9ZKfyLOv9sy8IVSiPzFbwRTz6u/xBWVxF4rU/Va0hlp/4UB8q9NDplaEXZTwTlFByiHA2IDDzFkbbfeYRKatS5YTaRdvxsN9B9tGPAj6Q5vHUxCujdjw+GTzuXv+tqhgU= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 755FB3858D39 Received: from localhost (localhost [127.0.0.1]) by mail.cs.ucla.edu (Postfix) with ESMTP id E9A413C123847 for ; Sat, 4 Jan 2025 21:58:31 -0800 (PST) Received: from mail.cs.ucla.edu ([127.0.0.1]) by localhost (mail.cs.ucla.edu [127.0.0.1]) (amavis, port 10032) with ESMTP id vLxTzl8Pu5AI; Sat, 4 Jan 2025 21:58:31 -0800 (PST) Received: from localhost (localhost [127.0.0.1]) by mail.cs.ucla.edu (Postfix) with ESMTP id 888E03C123845; Sat, 4 Jan 2025 21:58:31 -0800 (PST) DKIM-Filter: OpenDKIM Filter v2.10.3 mail.cs.ucla.edu 888E03C123845 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cs.ucla.edu; s=9D0B346E-2AEB-11ED-9476-E14B719DCE6C; t=1736056711; bh=NC6Mt4CO/lxZ+UBmHn9eu/zbrYYzBVSTrk+eMP8GHSs=; h=From:To:Date:Message-ID:MIME-Version; b=EMX0fECWx3P5xqBqaI0dc36AE/4XoXiV2tt0a1svY3PiPwti8HPxKdGprJjAHE8TZ Upj1PFL1msE78opyJ4MVBkvyUMo9i39HJAM0XS4HFgD0MSbsNMtWkrjdiu6Nr6V0hQ wNetOqu0d0Wzc7NMCRYx3Wn5/ToAnWJA4SM0lD6/T0XzJE4lWs9fWJ2Sf6HVocdiwz z00gnYE2jys0715KI5AVz6CsG6cGz48s8hy/D+b8kIhqpJchIQh8pfz5vLzPTjZ5fn 6pQcLDhQSQkiJ8Mu7bT19icxbObP5dOR1nosVFKlnTwzJr2NtE65A8M+eQgKRyjFVq rV+wnabtpT/7g== X-Virus-Scanned: amavis at mail.cs.ucla.edu Received: from mail.cs.ucla.edu ([127.0.0.1]) by localhost (mail.cs.ucla.edu [127.0.0.1]) (amavis, port 10026) with ESMTP id tcaQxtQfBcyI; Sat, 4 Jan 2025 21:58:31 -0800 (PST) Received: from wing.home (unknown [47.154.28.214]) by mail.cs.ucla.edu (Postfix) with ESMTPSA id 720AF3C082EB9; Sat, 4 Jan 2025 21:58:31 -0800 (PST) From: Paul Eggert To: libc-alpha@sourceware.org Cc: Paul Eggert Subject: [PATCH 07/59] Document mktime out-of-range + tm_isdst Date: Sat, 4 Jan 2025 21:56:42 -0800 Message-ID: <20250105055750.1668721-8-eggert@cs.ucla.edu> X-Mailer: git-send-email 2.45.2 In-Reply-To: <01207110-bd60-46ae-9c08-fb39c2011067@cs.ucla.edu> References: <01207110-bd60-46ae-9c08-fb39c2011067@cs.ucla.edu> MIME-Version: 1.0 X-Spam-Status: No, score=-9.7 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, GIT_PATCH_0, SPF_HELO_NONE, SPF_PASS, 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.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces~patchwork=sourceware.org@sourceware.org * manual/time.texi (Broken-down Time): Document mktime better when dealing with out-of-range inputs and nonnegative tm_isdst. Documentation problem reported by Florian Weimer in: https://sourceware.org/pipermail/libc-alpha/2024-October/160310.html --- manual/time.texi | 51 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 43 insertions(+), 8 deletions(-) diff --git a/manual/time.texi b/manual/time.texi index 899128ca7f..28d8912446 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -1075,9 +1075,11 @@ 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. -Although this flag is useful when passing a broken-down time to the -@code{mktime} function, for other uses this flag should be ignored and -the @code{tm_gmtoff} and @code{tm_zone} fields should be inspected instead. +This flag should not be inspected; the @code{tm_gmtoff} and +@code{tm_zone} fields should be inspected instead. +However, before calling @code{mktime} this flag should be set, +and set to a negative value unless the application already has a +correct value for the specified time. @item long int tm_gmtoff This field describes the time zone that was used to compute this @@ -1297,13 +1299,46 @@ The @code{mktime} function ignores the specified contents of the members of the broken-down time 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} +unnormalized values outside their normal ranges. +Out-of-range members are brought into range in reverse order of +significance: for example, an hour equal to @minus{}1 is first +increased to 23 and the day decreased by 1, before an out-of-range day +is brought into range. + +If local time ever observes daylight saving time, the @code{tm_isdst} +member is inspected after other members are brought into range. If +negative, @code{mktime} uses time zone data to determine whether +daylight saving time is in effect at the requested time. Then members +are adjusted if they would otherwise be inconsistent, e.g., by adding +or subtracting an hour if the broken-down time would otherwise have +the wrong @code{tm_isdst} member or would occur during a +spring-forward gap. +The heuristic used for these adjustments is unspecified. +@c The heuristic conforms to POSIX.1-2024 for non-geographic timezones. +@c POSIX-1.2024 is incorrect (and unclear to boot) for geographic timezones, +@c which is the normal use cases for non-UTC timezones these days. + +Ordinarily callers should specify a negative @code{tm_isdst} member. +The main practical use for nonnegative @code{tm_isdst} is when a the +broken-down time was produced by @code{localtime} or similar functions +so its @code{tm_isdst} is already known to be correct. This might +happen if the original simple time has been lost, in which case the +nonnegative @code{tm_isdst} usually (but not always) lets +@code{mktime} disambiguate broken-down times within an overlapping +window after the clock jumps back during a daylight saving or other +transition. A nonnegative @code{tm_isdst} might also happen when +doing broken-down time arithmetic by calling @code{localtime}, adding +or subtracting to (say) @code{tm_mday}, and then calling +@code{mktime}; in this case, though, if the time arithmetic crosses a +time transition boundary the results are unspecified. + +If successful, @code{mktime} uses the equivalent of @code{localtime} +to set all the components of the @code{*@var{brokentime}} structure, including the members that were initially ignored. 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 -the contents of @var{brokentime}. +@code{*@var{brokentime}}. Calling @code{mktime} also sets the time zone state as if @code{tzset} were called; @code{mktime} uses this information instead @@ -1342,8 +1377,8 @@ available. @code{timelocal} is rather rare. @c tzfile_compute(!use_localtime) ok @code{timegm} is functionally identical to @code{mktime} except it -always takes the input values to be UTC -regardless of any local time zone setting. +operates in UTC, so it ignores @code{tm_isdst} other than setting it +to zero when successful. Note that @code{timegm} is the inverse of @code{gmtime}.