+2024-02-03 Paul Eggert <eggert@cs.ucla.edu>
+
+ ctime: improve doc
+ * doc/posix-functions/asctime.texi (asctime):
+ * doc/posix-functions/asctime_r.texi (asctime_r):
+ * doc/posix-functions/ctime_r.texi (ctime_r):
+ * doc/posix-functions/ctime.texi (ctime):
+ Mention locale problem of strftime more consistently. Improve
+ wording. For ctime and ctime_r, mention that localtime_r can
+ fail.
+ * doc/posix-functions/ctime.texi (ctime): Move history section
+ to end and spiff up a bit.
+ * doc/posix-functions/ctime_r.texi (ctime_r): Omit commentary that
+ assumes traditional SunOS ctime_r API; it was confusing and not
+ useful for Gnulib apps, which assume the POSIX API.
+
2024-02-05 Bruno Haible <bruno@clisp.org>
Further improve cross-compilation for midipix.
removed in a future version.
Portable applications can use @code{localtime_r} and @code{strftime}
(or even @code{sprintf}) instead.
+However, @code{localtime_r} can fail and @code{strftime} is locale dependent.
@item
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}
zones supported by GNU or specified by POSIX@. @xref{tzset}.
@end itemize
-A more flexible function is @code{strftime}. However, note that it is
-locale dependent.
+Although @code{ctime} and related functions @code{asctime}, @code{asctime_r}
+and @code{ctime_r} formerly were plausible to use,
+they are now unsafe in general, and should be avoided.
+
+Decades ago when @code{time_t} was narrow
+and there was no @code{strftime} or internationalization,
+code could call these functions 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
+
+@noindent
+This had well-defined behavior when @code{time_t} was 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].
+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,
+because it incorrectly assumes that every year is represented by
+exactly four digits.
removed in a future version.
Use the functions @code{localtime_r} and @code{strftime}
(or even @code{sprintf}) instead.
+However, @code{localtime_r} can fail and @code{strftime} is locale dependent.
@item
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,
-and returns @code{NULL} on errors.
-The input buffer should be at least 26 bytes in size. The output
-string is locale-independent. However, years can have more than 4
-digits if @code{time_t} is sufficiently wide, so the length of the
-required output buffer is not easy to determine. Increasing the
-buffer size when @code{ctime_r} returns @code{NULL} is not necessarily
-sufficient. The @code{NULL} return value could mean some other error
-condition, which will not go away by increasing the buffer size.
-
-A more flexible function is @code{strftime}. However, note that it is
-locale dependent.