From cbb65906071be99ccf8af9cada6def283cff76d4 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Mon, 5 Feb 2024 15:18:48 +0100 Subject: [PATCH] doc: Extend doc of *ctime functions. MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit * 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 | 10 ++++++++++ doc/posix-functions/asctime.texi | 4 +++- doc/posix-functions/asctime_r.texi | 5 +++-- doc/posix-functions/ctime.texi | 22 +++++++++++++++++++++- doc/posix-functions/ctime_r.texi | 5 +++-- 5 files changed, 40 insertions(+), 6 deletions(-) diff --git a/ChangeLog b/ChangeLog index 88f92c9609..5096e5b8e2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2024-02-05 Paul Eggert + + 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 snippet/warn-on-use: Add comment. diff --git a/doc/posix-functions/asctime.texi b/doc/posix-functions/asctime.texi index c212a76118..7b19deaa22 100644 --- a/doc/posix-functions/asctime.texi +++ b/doc/posix-functions/asctime.texi @@ -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 diff --git a/doc/posix-functions/asctime_r.texi b/doc/posix-functions/asctime_r.texi index 3b19860363..ae527bd197 100644 --- a/doc/posix-functions/asctime_r.texi +++ b/doc/posix-functions/asctime_r.texi @@ -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 diff --git a/doc/posix-functions/ctime.texi b/doc/posix-functions/ctime.texi index bab929c08c..76c6e0ffe0 100644 --- a/doc/posix-functions/ctime.texi +++ b/doc/posix-functions/ctime.texi @@ -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} diff --git a/doc/posix-functions/ctime_r.texi b/doc/posix-functions/ctime_r.texi index 8b5dd136cc..be157cb643 100644 --- a/doc/posix-functions/ctime_r.texi +++ b/doc/posix-functions/ctime_r.texi @@ -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, -- 2.39.5