]> Savannah Git Hosting - gnulib.git/commitdiff
doc: improve warnings about ctime etc.
authorPaul Eggert <eggert@cs.ucla.edu>
Sun, 11 Feb 2024 01:53:34 +0000 (17:53 -0800)
committerPaul Eggert <eggert@cs.ucla.edu>
Sun, 11 Feb 2024 01:54:42 +0000 (17:54 -0800)
* 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
doc/posix-functions/asctime.texi
doc/posix-functions/asctime_r.texi
doc/posix-functions/ctime.texi
doc/posix-functions/ctime_r.texi

index 143100114af4868307b0657f07b3ea9ee36747d1..8b6c726087c1141021a5b444f1d68be6f8a5c29e 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2024-02-10  Paul Eggert  <eggert@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  <bruno@clisp.org>
 
        havelib: Add support for NetBSD/sparc64.
index 13aae8385a811049af8b718d48517d97b1f7d2bb..be2f3a6889bfab61c346485c64ac2a31173c0646 100644 (file)
@@ -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
index e948d3c47bedd8290495db2d85a3045575068fbd..cf3ac4ce27d5ae09bc2c89fd609ae8d6e2e3be3f 100644 (file)
@@ -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
index 3a1aa489f492dffa39f6c335f2565cca0ffe6f56..3ed8e29840667f66896bcc65c5fc17ac85e2ab71 100644 (file)
@@ -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.
index 8b3fcb4ea78b11062d9732c5fc29c78e883900c2..99ae828a548b65dad77523efd29930b6a6891983 100644 (file)
@@ -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