On 6/10/24 15:31, Alejandro Colomar wrote:
Nah, I only keep here the first one, for simplifying. If it was added
in C89, and is present in C23, we can assume that it was present in C99
and C11 too.
OK, though I still don't quite follow what those sections are supposed
to mean. Most of this stuff was first standardized in POSIX.1-1988 or
POSIX.1-1996, for example, but those editions don't seem to be mentioned.
Anyway, I attempted to address that issue and the other issues you
mentioned. Revised proposal attached as a series of patches.From b81cade3cfe4a0e7dd533713b97485902e1a0e06 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Mon, 10 Jun 2024 18:16:40 -0700
Subject: [PATCH 01/10] ctime: simplify coverage of tzname etc.
* man/man3/ctime.3: Simplify by referring to tzset(3) for details
about how it sets tzname etc. This simplifies a later patch,
which changes tzset(3)'s description.
---
man/man3/ctime.3 | 24 +++++++++---------------
1 file changed, 9 insertions(+), 15 deletions(-)
diff --git a/man/man3/ctime.3 b/man/man3/ctime.3
index b8543a1cf..e863f0572 100644
--- a/man/man3/ctime.3
+++ b/man/man3/ctime.3
@@ -101,10 +101,9 @@ The abbreviations for the months are "Jan",
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.
+The function also sets the external 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
@@ -198,10 +193,9 @@ normalized (so that, for example, 40 October is changed into 9 November);
is set (regardless of its initial value)
to a positive value or to 0, respectively,
to indicate whether DST is or is not in effect at the specified time.
-Calling
-.BR mktime ()
-also sets the external variable \fItzname\fP with
-information about the current timezone.
+The function also sets the external variables \fItzname\fP,
+\fItimezone\fP, and \fIdaylight\fP as if it called
+.BR tzset (3).
.P
If the specified broken-down
time cannot be represented as calendar time (seconds since the Epoch),
--
2.45.2
From 144c22f6fae1b8208d29d29977a6ecc7e74bc5c1 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Mon, 10 Jun 2024 18:20:13 -0700
Subject: [PATCH 02/10] tzset: state vars unspecified if geographical TZ
---
man/man3/tzset.3 | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/man/man3/tzset.3 b/man/man3/tzset.3
index 8479b17b0..6e89dd530 100644
--- a/man/man3/tzset.3
+++ b/man/man3/tzset.3
@@ -63,6 +63,11 @@ 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).
+.P
If the
.B TZ
variable does not appear in the environment, the system timezone is used.
@@ -155,7 +160,8 @@ TZ="NZST\-12:00:00NZDT\-13:00:00,M10.1.0,M3.3.0"
.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
--
2.45.2
From d7015ade22c1bf05237c76dae61a7050f2c76f96 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Mon, 10 Jun 2024 18:21:31 -0700
Subject: [PATCH 03/10] tzset: recommend tm_gmtoff, tm_zone instead
New section CAVEATS for why time zone state is dicey.
---
man/man3/tzset.3 | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/man/man3/tzset.3 b/man/man3/tzset.3
index 6e89dd530..552401c58 100644
--- a/man/man3/tzset.3
+++ b/man/man3/tzset.3
@@ -241,6 +241,16 @@ name of the timezone corresponding to its first argument (minutes
West of UTC).
If the second argument was 0, the standard name was used,
otherwise the daylight saving time version.
+.SH CAVEATS
+Because the values of \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP
+are often unspecified, and accessing them can lead to undefined
+behavior in multithreaded applications,
+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).
.SH SEE ALSO
.BR date (1),
.BR gettimeofday (2),
--
2.45.2
From 564a47e79baba83902738e6e98b557ba7dd94510 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Mon, 10 Jun 2024 18:22:36 -0700
Subject: [PATCH 04/10] tzset: TZ can also be empty
---
man/man3/tzset.3 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man/man3/tzset.3 b/man/man3/tzset.3
index 552401c58..7ddea52b7 100644
--- a/man/man3/tzset.3
+++ b/man/man3/tzset.3
@@ -84,7 +84,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
--
2.45.2
From 419dcc95085bcaa844f097d0dc92719ade7d9937 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Mon, 10 Jun 2024 18:23:33 -0700
Subject: [PATCH 05/10] tzset: time hh range is now -167..167
---
man/man3/tzset.3 | 2 ++
1 file changed, 2 insertions(+)
diff --git a/man/man3/tzset.3 b/man/man3/tzset.3
index 7ddea52b7..717b1fec9 100644
--- a/man/man3/tzset.3
+++ b/man/man3/tzset.3
@@ -146,6 +146,8 @@ 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,
--
2.45.2
From 075fb7071afbba5aabbfdf5f6da702b843835bd1 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Mon, 10 Jun 2024 18:26:03 -0700
Subject: [PATCH 06/10] tzset: use NZ's current rules in example
---
man/man3/tzset.3 | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/man/man3/tzset.3 b/man/man3/tzset.3
index 717b1fec9..0b813c568 100644
--- a/man/man3/tzset.3
+++ b/man/man3/tzset.3
@@ -153,12 +153,12 @@ If omitted, the default is 02:00:00.
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 the default time 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
--
2.45.2
From e3bbcdcf1e2219812f94644e742fa12b6064230a Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Mon, 10 Jun 2024 18:34:35 -0700
Subject: [PATCH 07/10] tzset: TZ=":EST5" works
---
man/man3/tzset.3 | 17 ++++++++++-------
1 file changed, 10 insertions(+), 7 deletions(-)
diff --git a/man/man3/tzset.3 b/man/man3/tzset.3
index 0b813c568..f3e6c8748 100644
--- a/man/man3/tzset.3
+++ b/man/man3/tzset.3
@@ -86,7 +86,8 @@ below, then Coordinated Universal Time (UTC) is used.
.P
A nonempty value of
.B TZ
-can be one of two formats.
+can be one of two formats,
+either of which can be preceded by a colon which is ignored.
The first format is a string of characters that directly represent the
timezone to be used:
.P
@@ -168,19 +169,21 @@ 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
+The \fIfilespec\fP specifies a
.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 specified 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
--
2.45.2
From 6d55de651ee757ce3d35531716463aa1004e4404 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Mon, 10 Jun 2024 18:35:14 -0700
Subject: [PATCH 08/10] tzset: omit colon in example
---
man/man3/tzset.3 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man/man3/tzset.3 b/man/man3/tzset.3
index f3e6c8748..4c7e286fe 100644
--- a/man/man3/tzset.3
+++ b/man/man3/tzset.3
@@ -189,7 +189,7 @@ Here's an example, once more for New Zealand:
.P
.in +4n
.EX
-TZ=":Pacific/Auckland"
+TZ="Pacific/Auckland"
.EE
.in
.SH ENVIRONMENT
--
2.45.2
From a08517719a8573276d6f1d16e5730eedabae773e Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Mon, 10 Jun 2024 18:37:47 -0700
Subject: [PATCH 09/10] tzset: update STANDARDS, HISTORY
The current standards are C23 and POSIX.1-2024.
This stuff was first standardized in C89 and POSIX.1-1988.
---
man/man3type/tm.3type | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/man/man3type/tm.3type b/man/man3type/tm.3type
index 5d5b28658..1628e0c1f 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, POSIX.1-1988.
.P
.I tm_gmtoff
and
--
2.45.2
From e44bfedeab7af087111c33aa63c97bcff6dd2bf5 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Mon, 10 Jun 2024 19:11:59 -0700
Subject: [PATCH 10/10] tzset: update more POSIX citations and quotes
---
man/man3/ctime.3 | 29 +++++++++++++----------------
man/man3/tzset.3 | 4 ++--
2 files changed, 15 insertions(+), 18 deletions(-)
diff --git a/man/man3/ctime.3 b/man/man3/ctime.3
index e863f0572..a0dacfeda 100644
--- a/man/man3/ctime.3
+++ b/man/man3/ctime.3
@@ -320,7 +320,7 @@ In many implementations, including glibc, a 0 in
.I tm_mday
is interpreted as meaning the last day of the preceding month.
.P
-According to POSIX.1-2001,
+According to POSIX.1-2024,
.BR localtime ()
is required to behave as though
.BR tzset (3)
@@ -343,16 +343,12 @@ should be called before
.BR localtime ()
.TQ
.BR mktime ()
-C11, POSIX.1-2008.
+C23, POSIX.1-2024.
.TP
-.BR asctime_r ()
-.TQ
-.BR ctime_r ()
-.TQ
.BR gmtime_r ()
.TQ
.BR localtime_r ()
-POSIX.1-2008.
+POSIX.1-2024.
.SH HISTORY
.TP
.BR gmtime ()
@@ -360,25 +356,25 @@ POSIX.1-2008.
.BR localtime ()
.TQ
.BR mktime ()
-C89, POSIX.1-2001.
+C89, POSIX.1-1988.
.TP
.BR asctime ()
.TQ
.BR ctime ()
-C89, POSIX.1-2001.
-Marked obsolete in POSIX.1-2008 (recommending
+C89, POSIX.1-1988.
+Marked obsolescent in C23 and in POSIX.1-2008 (recommending
.BR strftime (3)).
.TP
.BR gmtime_r ()
.TQ
.BR localtime_r ()
-POSIX.1-2001.
+POSIX.1-1996.
.TP
.BR asctime_r ()
.TQ
.BR ctime_r ()
-POSIX.1-2001.
-Marked obsolete in POSIX.1-2008 (recommending
+POSIX.1-1996.
+Removed in POSIX.1-2024 (recommending
.BR strftime (3)).
.SH NOTES
The four functions
@@ -396,7 +392,7 @@ and
.BR localtime_r (),
are specified by SUSv2.
.P
-POSIX.1-2001 says:
+POSIX.1-2024 says:
"The
.BR asctime (),
.BR ctime (),
@@ -406,8 +402,9 @@ and
functions shall return values in one of two static objects:
a broken-down time structure and an array of type
.IR char .
-Execution of any of the functions may overwrite the information returned
-in either of these objects by any of the other functions."
+Execution of any of the functions that return a pointer to one of these
+object types may overwrite the information in any object of the same type
+pointed to by the value returned from any previous call to any of them."
This can occur in the glibc implementation.
.SH SEE ALSO
.BR date (1),
diff --git a/man/man3/tzset.3 b/man/man3/tzset.3
index 4c7e286fe..7d57dc9a1 100644
--- a/man/man3/tzset.3
+++ b/man/man3/tzset.3
@@ -235,9 +235,9 @@ T{
T} Thread safety MT-Safe env locale
.TE
.SH STANDARDS
-POSIX.1-2008.
+POSIX.1-2024.
.SH HISTORY
-POSIX.1-2001, SVr4, 4.3BSD.
+POSIX.1-1988, SVr4, 4.3BSD.
.P
4.3BSD had a function
.BI "char *timezone(" zone ", " dst )
--
2.45.2
