[PATCH 4/5] tm.3type: describe tm_zone, tm_gmtoff

[наб <nabijaczleweli@nabijaczleweli.xyz>]

[-- Attachment #1: Type: text/plain, Size: 3047 bytes --]

FreeBSD timezone(3) is V7 char *timezone(int zone, int dst),
our documentation would imply it's impossible to service this type of
system portably

Indeed, glibc defines them both, and they make more sense for most
use-cases than trying to use the globals

glibc cited for __USE_MISC, tm_zone invalidation is Debian 2.33-7
POSIX cited for XSI marking is Issue 7 TC2
CSRG CD #2 contains 4.3BSD-Tahoe with both members

This also fixes the multiple lies in man-pages 5.10 localtime(3),
which says only:
    The glibc version of struct tm has additional fields
        const char *tm_zone;      /* Timezone abbreviation */
    defined when _BSD_SOURCE was set before including <time.h>.
    This is a BSD extension, present in 4.3BSD-Reno.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/tm.3type | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/man3/tm.3type b/man3/tm.3type
index 1931d890d..8b6f8d9bf 100644
--- a/man3/tm.3type
+++ b/man3/tm.3type
@@ -25,8 +25,26 @@ Standard C library
 .BR "    int  tm_yday;" \
 "   /* Day of the year  [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
 .BR "    int  tm_isdst;" "  /* Daylight savings flag */"
+
+.BR "    long tm_gmtoff;" " /* Seconds East of UTC */"
+.BR "    char*tm_zone;" "   /* Timezone abbreviation */"
 .B };
 .fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.IR tm_gmtoff ,
+.IR tm_zone :
+.nf
+.\" Guarded with __USE_MISC:
+    Since glibc 2.19:
+        _DEFAULT_SOURCE
+    Glibc 2.19 and earlier:
+        _BSD_SOURCE || _SVID_SOURCE
+.fi
 .SH DESCRIPTION
 Describes time, broken down into distinct components.
 .PP
@@ -35,6 +53,16 @@ describes wether daylight saving time is in effect at the time described.
 The value is positive if daylight saving time is in effect,
 zero if it is not,
 and negative if the information is not available.
+.PP
+.I tm_gmtoff
+is the difference, in seconds, of the timezone represented by this broken-down time and UTC
+(this is the reverse of
+.BR timezone (3)).
+.PP
+.I tm_zone
+is the equivalent of
+.BR tzname (3)
+for the timezone represented by this broken-down time.
 .SH VERSIONS
 In C90,
 .I tm_sec
@@ -48,10 +76,27 @@ in C99.
 .SH CONFORMING TO
 C90 and later;
 POSIX.1-2001 and later.
+.PP
+.IR tm_gmtoff " and " tm_zone
+originate from 4.3BSD-Tahoe.
 .SH NOTES
 .I tm_sec
 can represent a leap second with the value
 .BR 60 .
+.PP
+.BR timezone (3),
+as a variable, is an XSI extension \(em some systems provide the V7-compatible
+.\" FreeBSD
+.BR timezone ()
+function.
+The
+.I tm_gmtoff
+fields provides an alternative (with the opposite sign) for those systems.
+.PP
+.I tm_zone
+points to potentially-constant static storage and may be overriden on subsequent calls to
+.BR localtime (3)
+&a. (this, however, never happens under glibc).
 .SH SEE ALSO
 .BR ctime (3),
 .BR strftime (3),
-- 
2.30.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]