candidate strftime docs patch

[David Holland <dholland-tech%netbsd.org@localhost>]

The following patch is based on the assumption that the current points
of contention (e.g. about undefined behavior calling mktime) are
irrelevant for the time being as taking advantage of them requires
code changes.


Index: strftime.3
===================================================================
RCS file: /cvsroot/src/lib/libc/time/strftime.3,v
retrieving revision 1.37
diff -u -r1.37 strftime.3
--- strftime.3	25 Oct 2022 08:07:07 -0000	1.37
+++ strftime.3	6 Nov 2022 17:55:28 -0000
@@ -32,7 +32,7 @@
 .\"     from: @(#)strftime.3	5.12 (Berkeley) 6/29/91
 .\"	$NetBSD: strftime.3,v 1.37 2022/10/25 08:07:07 kre Exp $
 .\"
-.Dd October 9, 2020
+.Dd November 6, 2022
 .Dt STRFTIME 3
 .Os
 .Sh NAME
@@ -147,7 +147,9 @@
 of leap seconds.
 .It Cm \&%s
 is replaced by the number of seconds since the Epoch (see
-.Xr ctime 3 ) .
+.Xr ctime 3 ) under the assumption that the time in
+.Fa timeptr
+is expressed in the current local time zone.
 .It Cm \&%T
 is replaced by the time in the format
 .Dq Li %H:%M:%S .
@@ -185,13 +187,13 @@
 .It Cm \&%y
 is replaced by the year without century as a decimal number [00,99].
 .It Cm \&%Z
-is replaced by the time zone abbreviation,
-or the empty string if this is not determinable.
+is replaced by the time zone abbreviation of the current local time
+zone, or the empty string if this is not determinable.
 .It Cm \&%z
 is replaced by the offset from the Prime Meridian in the format
 +HHMM or -HHMM (ISO 8601) as appropriate, with positive values representing
-locations east of Greenwich, or by the empty string if this is
-not determinable.
+locations east of Greenwich, reflecting the current local time zone,
+or by the empty string if this is not determinable.
 The numeric time zone abbreviation \&-0000 is used when the time is
 Universal Time
 but local time is indeterminate; by convention this is used for
@@ -227,6 +229,13 @@
 .Ft "const timezone_t"
 .Fa tz
 argument.
+This time zone is used instead of the local time zone when handling
+the
+.Cm \&%s ,
+.Cm \&%Z ,
+and
+.Cm \&%z
+conversions.
 .Sh RETURN VALUES
 If the conversion is successful,
 .Nm
@@ -289,6 +298,28 @@
 .Ql \&%v
 conversion specifications are extensions.
 .Pp
+Note that while in
+.Nx
+the
+.Vt tm
+structure contains fields that describe the time zone, this is an
+extension, and standards compliance prevents
+.Fn strftime
+from using these fields when printing.
+In particular, attempting to print a
+.Vm tm
+structure produced by
+.Xr gmtime 3
+will not necessarily produce the intended results.
+Portable code that wishes to print in multiple timezones must use
+.Xr tzset 3
+to change time zone explicitly, then call
+.Xr localtime 3
+and then
+.Fn strftime
+in each zone.
+This is not thread-safe.
+.Pp
 Use of the ISO 8601 conversions may produce non-intuitive results.
 Week 01 of a year is per definition the first week which has the Thursday
 in this year, which is equivalent to the week which contains the fourth
Index: tm.3
===================================================================
RCS file: /cvsroot/src/share/man/man3/tm.3,v
retrieving revision 1.5
diff -u -r1.5 tm.3
--- tm.3	23 Oct 2022 15:43:40 -0000	1.5
+++ tm.3	6 Nov 2022 17:55:34 -0000
@@ -24,7 +24,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd April 14, 2011
+.Dd November 6, 2022
 .Dt TM 3
 .Os
 .Sh NAME
@@ -83,6 +83,13 @@
 in this form in future releases of
 . Nx .
 .Pp
+In any event these fields are ``informational'' in the sense that they
+are filled in by library routines that produce
+.Vt tm
+structures, but are not used by library routines that consume
+.Vt tm
+structures; portable code is free to not provide values for them.
+.Pp
 The
 .Fa tm_gmtoff
 field denotes the offset (in seconds) of the time represented



-- 
David A. Holland
dholland%netbsd.org@localhost