+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.
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
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
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}
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,