On 2024-02-10 02:03, Bruno Haible wrote:
That's something we should mention in doc/posix-functions/asctime{,_r}.texi.
I gave that a shot by installing the attached.
From 3aafd55066902b942ebb0263a5c235e684e2eeca Mon Sep 17 00:00:00 2001
From: Paul Eggert <egg...@cs.ucla.edu>
Date: Sat, 10 Feb 2024 17:53:34 -0800
Subject: [PATCH] doc: improve warnings about ctime etc.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* doc/posix-functions/asctime.texi (asctime):
* doc/posix-functions/asctime_r.texi (asctime_r):
Say why these functions are typically used mistakenly.
* doc/posix-functions/ctime.texi (ctime):
* doc/posix-functions/ctime_r.texi (ctimef):
Say that they can dump core due to an internal null pointer, too.
* doc/posix-functions/ctime.texi (ctime):
Don’t recommend ctime_r.
---
ChangeLog | 12 ++++++++++++
doc/posix-functions/asctime.texi | 6 ++++++
doc/posix-functions/asctime_r.texi | 6 ++++++
doc/posix-functions/ctime.texi | 14 +++++++++-----
doc/posix-functions/ctime_r.texi | 4 ++++
5 files changed, 37 insertions(+), 5 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 143100114a..8b6c726087 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2024-02-10 Paul Eggert <egg...@cs.ucla.edu>
+
+ doc: improve warnings about ctime etc.
+ * doc/posix-functions/asctime.texi (asctime):
+ * doc/posix-functions/asctime_r.texi (asctime_r):
+ Say why these functions are typically used mistakenly.
+ * doc/posix-functions/ctime.texi (ctime):
+ * doc/posix-functions/ctime_r.texi (ctimef):
+ Say that they can dump core due to an internal null pointer, too.
+ * doc/posix-functions/ctime.texi (ctime):
+ Don’t recommend ctime_r.
+
2024-02-10 Bruno Haible <br...@clisp.org>
havelib: Add support for NetBSD/sparc64.
diff --git a/doc/posix-functions/asctime.texi b/doc/posix-functions/asctime.texi
index 13aae8385a..be2f3a6889 100644
--- a/doc/posix-functions/asctime.texi
+++ b/doc/posix-functions/asctime.texi
@@ -22,4 +22,10 @@ However, @code{strftime} is locale dependent.
This function may overflow its internal buffer if its argument
specifies a year before 1000 or after 9999.
@xref{ctime}.
+@item
+Although it is tempting to call this function on the value that
+functions like @code{localtime} return, this is typically a mistake.
+On most current platforms, these functions return a null pointer for
+timestamps out of range, and this function has undefined behavior in
+that case.
@end itemize
diff --git a/doc/posix-functions/asctime_r.texi b/doc/posix-functions/asctime_r.texi
index e948d3c47b..cf3ac4ce27 100644
--- a/doc/posix-functions/asctime_r.texi
+++ b/doc/posix-functions/asctime_r.texi
@@ -29,4 +29,10 @@ However, @code{strftime} is locale dependent.
This function may overflow its output buffer if its argument
specifies a year before 1000 or after 9999.
@xref{ctime}.
+@item
+Although it is tempting to call this function on the value that
+functions like @code{localtime} return, this is typically a mistake.
+On most current platforms, these functions return a null pointer for
+timestamps out of range, and this function has undefined behavior in
+that case.
@end itemize
diff --git a/doc/posix-functions/ctime.texi b/doc/posix-functions/ctime.texi
index 3a1aa489f4..3ed8e29840 100644
--- a/doc/posix-functions/ctime.texi
+++ b/doc/posix-functions/ctime.texi
@@ -26,12 +26,15 @@ However, @code{localtime_r} can fail and @code{strftime} is locale dependent.
This function may overflow its internal buffer if its argument
specifies a time before the year 1000 or after the year 9999.
@item
+This function may dereference an internal null pointer if its argument
+specifies a time before the year @code{INT_MIN}+1900 or after the
+year @code{INT_MAX}+1900.
+@item
The @code{ctime} function need not be reentrant, and consequently is
not required to be thread safe. Implementations of @code{ctime}
typically write the timestamp into static buffer. If two threads
call @code{ctime} at roughly the same time, you might end up with the
-wrong date in one of the threads, or some undefined string. There is
-a reentrant interface @code{ctime_r}.
+wrong date in one of the threads, or some undefined string.
@item
Native Windows platforms (mingw, MSVC) support only a subset of time
zones supported by GNU or specified by POSIX@. @xref{tzset}.
@@ -60,8 +63,9 @@ and so was OK for circa 1979 platforms.
However, today's platforms have a @code{time_t} so wide
that the year might not be in the range [1000, 9999].
In this case the behavior of @code{ctime} is undefined
-and some platforms behave badly, overrunning a buffer;
-and even on platforms where no buffer overrun occurs,
-the 7th Edition code can generate wrong output for out-of-range years,
+and some platforms behave badly, overrunning a buffer
+or dereferencing an internal null pointer;
+and even on platforms where no undefined behavior occurs,
+the 7th Edition code generates wrong output for out-of-range years,
because it incorrectly assumes that every year is represented by
exactly four digits.
diff --git a/doc/posix-functions/ctime_r.texi b/doc/posix-functions/ctime_r.texi
index 8b3fcb4ea7..99ae828a54 100644
--- a/doc/posix-functions/ctime_r.texi
+++ b/doc/posix-functions/ctime_r.texi
@@ -30,4 +30,8 @@ However, @code{localtime_r} can fail and @code{strftime} is locale dependent.
This function may overflow its output buffer if its argument
specifies a time before the year 1000 or after the year 9999.
@xref{ctime}.
+@item
+This function may dereference an internal null pointer if its argument
+specifies a time before the year @code{INT_MIN}+1900 or after the
+year @code{INT_MAX}+1900.
@end itemize
--
2.40.1
