doc: Extend doc of *ctime functions.
authorPaul Eggert <eggert@cs.ucla.edu>
Mon, 5 Feb 2024 14:18:48 +0000 (15:18 +0100)
committerBruno Haible <bruno@clisp.org>
Mon, 5 Feb 2024 14:18:48 +0000 (15:18 +0100)
* doc/posix-functions/ctime.texi (ctime): Document why we got into
this mess.
* doc/posix-functions/asctime.texi (asctime):
* doc/posix-functions/asctime_r.texi (asctime_r):
* doc/posix-functions/ctime_r.texi (ctime_r):
Refer to ctime’s buffer overflow doc.

ChangeLog
doc/posix-functions/asctime.texi
doc/posix-functions/asctime_r.texi
doc/posix-functions/ctime.texi
doc/posix-functions/ctime_r.texi

index 88f92c9609d48c18e43939068de9dee57e4a3c40..5096e5b8e26f1b71aa610ec30fc9c296d4ca9604 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2024-02-05  Paul Eggert  <eggert@cs.ucla.edu>
+
+       doc: Extend doc of *ctime functions.
+       * doc/posix-functions/ctime.texi (ctime): Document why we got into
+       this mess.
+       * doc/posix-functions/asctime.texi (asctime):
+       * doc/posix-functions/asctime_r.texi (asctime_r):
+       * doc/posix-functions/ctime_r.texi (ctime_r):
+       Refer to ctime’s buffer overflow doc.
+
 2024-02-05  Bruno Haible  <bruno@clisp.org>
 
        snippet/warn-on-use: Add comment.
index c212a761182891b5203a60c2fd88c721919c472e..7b19deaa227c44c3c311ac5209fcdf2c3e88e625 100644 (file)
@@ -18,5 +18,7 @@ Likewise, POSIX says this function is obsolescent and it is planned to be
 removed in a future version.
 Portable applications can use @code{strftime} (or even @code{sprintf}) instead.
 @item
-This function may overflow its internal buffer if an invalid year is passed.
+This function may overflow its internal buffer if its argument
+specifies a time before the year 1000 or after the year 9999.
+@xref{ctime}.
 @end itemize
index 3b19860363fc7a8f0271d7e1d01c6a0399fed3be..ae527bd197bd7cb4807b7a6de021234fdc529be5 100644 (file)
@@ -25,6 +25,7 @@ POSIX says this function is obsolescent and it is planned to be
 removed in a future version.
 Use the function @code{strftime} (or even @code{sprintf}) instead.
 @item
-This function may put more than 26 bytes into the argument buffer if an
-invalid year is passed.
+This function may overflow its output buffer if its argument
+specifies a time before the year 1000 or after the year 9999.
+@xref{ctime}.
 @end itemize
index bab929c08c7b8abda0b5a4ccaaafcc41001e6d61..76c6e0ffe0b082dc740ffc4039f70d319f37292d 100644 (file)
@@ -22,7 +22,27 @@ removed in a future version.
 Portable applications can use @code{localtime_r} and @code{strftime}
 (or even @code{sprintf}) instead.
 @item
-This function may overflow its internal buffer if an invalid year is passed.
+This function may overflow its internal buffer if its argument
+specifies a time before the year 1000 or after the year 9999.
+
+Here is some history about this.
+This function was safe to use decades ago when @code{time_t} was narrow
+and there was no @code{strftime} or internationalization.
+Code could call @code{ctime} and then select the parts needed.
+For example, in Unix 7th Edition @file{/usr/src/cmd/ls.c} (1979):
+
+@example
+cp = ctime(&p->lmtime);
+if(p->lmtime < year)
+        printf(" %-7.7s %-4.4s ", cp+4, cp+20); else
+        printf(" %-12.12s ", cp+4);
+@end example
+
+This has well-defined behavior if @code{time_t} is only 32 bits
+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],
+and ISO C says that in this case the behavior of @code{ctime} is undefined.
 @item
 The @code{ctime} function need not be reentrant, and consequently is
 not required to be thread safe.  Implementations of @code{ctime}
index 8b5dd136cc481acdbc3150bb38aca65bbdfa1305..be157cb643c9214f50e27c480e93cfdf9ce6e252 100644 (file)
@@ -26,8 +26,9 @@ removed in a future version.
 Use the functions @code{localtime_r} and @code{strftime}
 (or even @code{sprintf}) instead.
 @item
-This function may put more than 26 bytes into the argument buffer if an
-invalid year is passed.
+This function may overflow its output buffer if its argument
+specifies a time before the year 1000 or after the year 9999.
+@xref{ctime}.
 @end itemize
 
 @code{ctime_r} takes a pre-allocated buffer and length of the buffer,