POSIX.1-2024 is now official, and tm_gmtoff and tm_zone are now part of POSIX. Update the man pages accordingly. Don't overpromise the global state that tzset updates. Its contents are unspecified if you use a geographical time zone. For more details, see: https://austingroupbugs.net/view.php?id=1816 https://sourceware.org/bugzilla/show_bug.cgi?id=31876 The hours in a TZ string time can now range from -167 to 167. Update NZ example to use NZ's current practice. Omit leading ":" from TZ examples as this usage is rare. --- man/man3/ctime.3 | 15 +++++---------- man/man3/tzset.3 | 39 ++++++++++++++++++++++++++++----------- man/man3type/tm.3type | 7 ++++--- 3 files changed, 37 insertions(+), 24 deletions(-) diff --git a/man/man3/ctime.3 b/man/man3/ctime.3 index b8543a1cf..94819961d 100644 --- a/man/man3/ctime.3 +++ b/man/man3/ctime.3 @@ -102,9 +102,8 @@ The return value points to a statically allocated string which might be overwritten by subsequent calls to any of the date and time functions. The function also sets the external -variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP (see -.BR tzset (3)) -with information about the current timezone. +variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP as if it called +.BR tzset (3). The reentrant version .BR ctime_r () does the same, but stores the @@ -131,13 +130,9 @@ The function converts the calendar time \fItimep\fP to broken-down time representation, expressed relative to the user's specified timezone. -The function acts as if it called -.BR tzset (3) -and sets the external variables \fItzname\fP with -information about the current timezone, \fItimezone\fP with the difference -between Coordinated Universal Time (UTC) and local standard time in -seconds, and \fIdaylight\fP to a nonzero value if daylight savings -time rules apply during some part of the year. +The function also sets the external variables \fItzname\fP, +\fItimezone\fP, and \fIdaylight\fP as if it called +.BR tzset (3). The return value points to a statically allocated struct which might be overwritten by subsequent calls to any of the date and time functions. The diff --git a/man/man3/tzset.3 b/man/man3/tzset.3 index 8479b17b0..8623abf09 100644 --- a/man/man3/tzset.3 +++ b/man/man3/tzset.3 @@ -63,6 +63,18 @@ In a System-V-like environment, it will also set the variables \fItimezone\fP have any daylight saving time rules, or to nonzero if there is a time, past, present, or future when daylight saving time applies). .P +The +.BR tzset () +function initializes these variables to unspecified values if this +timezone is a geographical timezone like "America/New_York" (see below). +Because these variables' contents are often unspecified, +code should instead obtain time zone offset and abbreviations from the +.I tm_gmtoff +and +.I tm_zone +members of the broken-down time structure +.BR tm (3type). +.P If the .B TZ variable does not appear in the environment, the system timezone is used. @@ -79,7 +91,7 @@ variable does appear in the environment, but its value is empty, or its value cannot be interpreted using any of the formats specified below, then Coordinated Universal Time (UTC) is used. .P -The value of +A nonempty value of .B TZ can be one of two formats. The first format is a string of characters that directly represent the @@ -141,44 +153,49 @@ Day 0 is a Sunday. .P The \fItime\fP fields specify when, in the local time currently in effect, the change to the other time occurs. +They use the same format as \fIoffset\fP except that the hour can range +from \-167 to 167 to represent times before and after the named day. If omitted, the default is 02:00:00. .P Here is an example for New Zealand, where the standard time (NZST) is 12 hours ahead of UTC, and daylight saving time (NZDT), 13 hours ahead of UTC, -runs from the first Sunday in October to the third Sunday in March, -and the changeovers happen at the default time of 02:00:00: +runs from September's last Sunday at 02:00:00 +to April's first Sunday at 03:00:00. .P .in +4n .EX -TZ="NZST\-12:00:00NZDT\-13:00:00,M10.1.0,M3.3.0" +TZ="NZST\-12:00:00NZDT\-13:00:00,M9.5.0,M4.1.0/3" .EE .in .P -The second format specifies that the timezone information should be read +The second, or "geographical", +format specifies that the timezone information should be read from a file: .P .in +4n .EX -:[filespec] +filespec .EE .in .P -If the file specification \fIfilespec\fP is omitted, or its value cannot -be interpreted, then Coordinated Universal Time (UTC) is used. If \fIfilespec\fP is given, it specifies another .BR tzfile (5)-format file to read the timezone information from. If \fIfilespec\fP does not begin with a \[aq]/\[aq], the file specification is relative to the system timezone directory. -If the colon is omitted each -of the above \fBTZ\fP formats will be tried. +If the named file cannot be read or interpreted, +Coordinated Universal Time (UTC) is used; +however, applications should not depend on random \fIfilespec\fP values +standing for UTC, as +.B TZ +formats may be extended in the future. .P Here's an example, once more for New Zealand: .P .in +4n .EX -TZ=":Pacific/Auckland" +TZ="Pacific/Auckland" .EE .in .SH ENVIRONMENT diff --git a/man/man3type/tm.3type b/man/man3type/tm.3type index 5d5b28658..cbf89a54c 100644 --- a/man/man3type/tm.3type +++ b/man/man3type/tm.3type @@ -90,9 +90,9 @@ points to static storage and may be overridden on subsequent calls to .BR localtime (3) and similar functions (however, this never happens under glibc). .SH STANDARDS -C11, POSIX.1-2008. +C23, POSIX.1-2024. .SH HISTORY -C89, POSIX.1-2001. +C89, C99, POSIX.1-2001, POSIX.1-2008. .P .I tm_gmtoff and @@ -100,7 +100,8 @@ and originate from 4.3BSD-Tahoe (where .I tm_zone is a -.IR "char *" ). +.IR "char *" ), +and were first standardized in POSIX.1-2024. .SH NOTES .I tm_sec can represent a leap second with the value -- 2.43.0
