[src/trunk]: src/lib/libc/time rephrase / clarify explanation of struct tm me...

[jschauma <jschauma%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/43422602df03
branches:  trunk
changeset: 372061:43422602df03
user:      jschauma <jschauma%NetBSD.org@localhost>
date:      Wed Oct 26 23:22:54 2022 +0000

description:
rephrase / clarify explanation of struct tm member normalization

diffstat:

 lib/libc/time/ctime.3 |  55 ++++++++++++++++++++++++++++++++++++++++++++------
 1 files changed, 48 insertions(+), 7 deletions(-)

diffs (72 lines):

diff -r 3eaa498fc3ff -r 43422602df03 lib/libc/time/ctime.3
--- a/lib/libc/time/ctime.3     Wed Oct 26 23:22:38 2022 +0000
+++ b/lib/libc/time/ctime.3     Wed Oct 26 23:22:54 2022 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: ctime.3,v 1.67 2022/10/21 12:28:43 uwe Exp $
+.\" $NetBSD: ctime.3,v 1.68 2022/10/26 23:22:54 jschauma Exp $
 .\"
 .\" XXX: License missing?
 .\"
@@ -255,15 +255,56 @@
 and the original values of the other components are not restricted
 to their normal ranges and will be normalized,
 if need be.
+.Pp
 For example,
-October 40 is changed into November 9, a
-.Fa tm_hour
-of \-1 means 1 hour before midnight,
+consider a
+.Fa struct tm
+initialized with
+.Fa tm_year
+= 122,
+.Fa tm_mon
+= 10,
 .Fa tm_mday
-of 0 means the day preceding the current month, and
+= 30,
+.Fa tm_hour
+= 22,
+.Fa tm_min
+= 57,
+and
+.Fa tm_sec
+= 0.
+Incrementing
+.Fa tm_min
+by 13 and calling
+.Fn mktime
+would lead to
+.Fa tm_hour
+= 23 and
+.Fa tm_min
+= 10.
+.Pp
+This normalizing can lead to cascading changes:
+Again using a
+.Fa struct tm
+initialized as in the above example but with
+.Fa tm_hour
+= 23,
+the same change would lead to
 .Fa tm_mon
-of \-2 means 2 months before January of
-.Fa tm_year .
+= 11,
+.Fa tm_mday
+= 1,
+.Fa tm_hour
+= 0, and
+.Fa tm_min
+= 10.
+.Pp
+Negative values may also be normalized with similar
+cascading effect such that e.g.,
+a
+.Fa tm_hour
+of \-1 means 1 hour before midnight on the previous
+day and so on.
 .It
 A positive or zero value for
 .Fa tm_isdst