77 lines
2.4 KiB
Diff
77 lines
2.4 KiB
Diff
From 9fdca71e4aba3605caa88b0c9eff3dc2c3f6fcfe Mon Sep 17 00:00:00 2001
|
|
From: DJ Delorie <dj@redhat.com>
|
|
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: <https://www.redhat.com/en/blog/brief-history-mktime>
|
|
Cc: Paul Eggert <eggert@cs.ucla.edu>
|
|
Cc: Carlos O'Donell <carlos@redhat.com>
|
|
Signed-off-by: DJ Delorie <dj@redhat.com>
|
|
Message-ID: <xncylqiznb.fsf@greed.delorie.com>
|
|
Signed-off-by: Alejandro Colomar <alx@kernel.org>
|
|
---
|
|
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
|
|
|