From 3aafd55066902b942ebb0263a5c235e684e2eeca Mon Sep 17 00:00:00 2001 From: Paul Eggert 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 + + 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 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