Add note about tm_isdst handling in mktime(3)

Resolves: RHEL-58342

0002-ctime.3-CAVEATS-Add-note-about-tm_isdst-handling-in-.patch

@@ -0,0 +1,76 @@
+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
+

man-pages.spec

@@ -8,7 +8,7 @@
 Summary: Linux kernel and C library user-space interface documentation
 Name: man-pages
 Version: 6.04
-Release: 2%{?dist}
+Release: 3%{?dist}
 # List of licenses with examples of man-pages using them
 # BSD-2-Clause: man-pages/man5/elf.5
 # BSD-3-Clause: man-pages/man3/list.3
@@ -62,6 +62,9 @@ Patch21: man-pages-3.42-close.patch
 # Resolves: RHEL-53953
 Patch22: 0001-dlinfo.3-Document-the-RTLD_DI_PHDR-request.patch
 
+# Upstream commit: https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man/man3/ctime.3?id=9fdca71e4aba3605caa88b0c9eff3dc2c3f6fcfe
+# Resolves: RHEL-58342
+Patch23: 0002-ctime.3-CAVEATS-Add-note-about-tm_isdst-handling-in-.patch
 %description
 A large collection of manual pages from the Linux Documentation Project (LDP).
 
@@ -135,6 +138,10 @@ fi
 %{_mandir}/man*/*
 
 %changelog
+* Tue Oct 01 2024 Lukas Javorsky <ljavorsk@redhat.com> - 6.04-3
+- Add note about tm_isdst handling in mktime(3)
+- Resolves: RHEL-58342
+
 * Fri Sep 13 2024 Lukas Javorsky <ljavorsk@redhat.com> - 6.04-2
 - Add RTLD_DI_PHDR to dlinfo(3)
 - Resolves: RHEL-53953