From 9fdca71e4aba3605caa88b0c9eff3dc2c3f6fcfe Mon Sep 17 00:00:00 2001 From: DJ Delorie Date: Thu, 29 Aug 2024 21:10:32 -0400 Subject: [PATCH] ctime.3: CAVEATS: Add note about tm_isdst handling in mktime(3) Handling of "invalid" values for tm_isdst is not clearly specified in any standard, and implementations vary as to how they react when you (for example) pass tm_isdst=1 at a time when DST is not in effect. Add a note about this, and a suggestion for a workaround. I go into further detail about this in the link below. Link: Cc: Paul Eggert Cc: Carlos O'Donell Signed-off-by: DJ Delorie Message-ID: Signed-off-by: Alejandro Colomar --- man/man3/ctime.3 | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/man/man3/ctime.3 b/man/man3/ctime.3 index 0ad2b530f..53abab6d9 100644 --- a/man/man3/ctime.3 +++ b/man/man3/ctime.3 @@ -427,6 +427,45 @@ one must use the .I tm->tm_wday field. See the example program in EXAMPLES. +.P +The handling of a non-negative +.I tm_isdst +in +.BR mktime () +is poorly specified, +and passing a value that is incorrect for the time specified +yields unspecified results. +Since +.BR mktime () +is one of the few functions that knows when DST is in effect, +providing a correct value may be difficult. +One workaround for this is to call +.BR mktime () +twice, +once with +.I tm_isdst +set to zero, +and once with +.I tm_isdst +set to a positive value, +and discarding the results from the call that changes it. +If neither call changes +.I tm_isdst +then the time specified probably happens during a fall-back period +where DST begins or ends, +and both results are valid +but represent two different times. +If both calls change it, that could indicate a fall-forward transition, +or some other reason why the time specified does not exist. +.P +The specification of time zones and daylight saving time +are up to regional governments, change often, +and may include discontinuities beyond +.IR mktime 's +ability to document a result. +For example, a change in the timezone definition +may cause a clock time to be repeated or skipped +without a corresponding DST change. .SH EXAMPLES The following shell session shows sample runs of the program: .P -- 2.46.1