From 3e6b572b5f6dcd204f3636e3c7a265063a315f2c Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Mon, 10 Apr 2023 15:15:37 -0700 Subject: [PATCH 1/3] doc: document year2038 first * doc/year2038.texi: Document year2038 first, then year2038-required. --- doc/posix-headers/time.texi | 2 +- doc/year2038.texi | 59 +++++++++++++++++++++---------------- 2 files changed, 35 insertions(+), 26 deletions(-) diff --git a/doc/posix-headers/time.texi b/doc/posix-headers/time.texi index f9d1def2aa..70814d6cda 100644 --- a/doc/posix-headers/time.texi +++ b/doc/posix-headers/time.texi @@ -19,7 +19,7 @@ NetBSD 5.0. @end itemize Portability problems fixed by the Gnulib module -@code{year2038-required} or @code{year2038}: +@code{year2038} or @code{year2038-required}: @itemize @item On some platforms where @code{time_t} defaults to 32-bit but can be diff --git a/doc/year2038.texi b/doc/year2038.texi index cae738c5da..81b212e455 100644 --- a/doc/year2038.texi +++ b/doc/year2038.texi @@ -8,15 +8,39 @@ after 2038-01-19 03:14:08 UTC@. See @url{https://en.wikipedia.org/wiki/Year_2038_problem, Year 2038 problem} for details. -The Gnulib module @samp{year2038-required} fixes this problem, by -making @code{time_t} wide enough to represent timestamps after 2038. -This has no effect on most current systems, which have timestamps that -are already wide enough. However, @samp{year2038-required} arranges -for builds on legacy 32-bit x86 and ARM Linux kernels running glibc -2.34 and later to compile with @samp{_TIME_BITS=64} to get wider +The Gnulib module @samp{year2038} fixes this problem on some +platforms, by making @code{time_t} wide enough to represent timestamps +after 2038. This has no effect on most current platforms, which have +timestamps that are already wide enough. However, @samp{year2038} by +default arranges for builds on legacy 32-bit Linux kernels running +glibc 2.34 and later to compile with @samp{_TIME_BITS=64} to get wider timestamps. On older platforms that do not support timestamps after -the year 2038, @samp{year2038-required} causes @command{configure} to -fail. +the year 2038, @samp{year2038} causes @command{configure} to issue a +warning but still proceed. On platforms that appear to support +post-2038 timestamps but where something prevents this from working, +@command{configure} fails. + +The default behavior of @samp{year2038} can be overridden by using the +@command{configure} option @option{--disable-year2038}, which +suppresses support for post-2038 timestamps. This may be useful if +the package links to other libraries whose user-facing ABIs still +require @code{time_t} to be 32-bit on your platform. + +The Gnulib module @samp{year2038-required} is like @samp{year2038}, +except it rejects platforms where @code{time_t} cannot represent +timestamps after 2038, and it lacks a @option{--disable-year2038} +option. If this module is used and a 32-platform cannot support +64-bit @code{time_t}, one can still fix the year-2038 problem by using +a 64-bit instead of a 32-bit build, as noted in the architecture list +below. If all else fails one can configure with +@samp{ac_year2038_required=no}; however, the resulting programs will +mishandle timestamps after 2038. + +The Gnulib module @samp{year2038-required} is +recommended for packages intended for use on 32-bit platforms +after the year 2038. However, if your package needs to support +32-bit platforms that will not be used after the year 2038, +you can use the @samp{year2038} module instead. With the @samp{year2038-required} module, @command{configure} fails on the following 32-bit platforms (or ABIs in bi-arch systems): @@ -65,26 +89,11 @@ FreeBSD/arm, Minix 3.3. @end itemize -The Gnulib module @samp{year2038} is like @samp{year2038-required}, -except that it causes @command{configure} to fail only when it appears -that the current system should support post-2038 timestamps but -something prevents that from working. Also, @samp{year2038} gives -@command{configure} a @option{--disable-year2038} option, which -suppresses support for post-2038 timestamps. This may be useful if -the package links to other libraries whose user-facing ABIs still -require @code{time_t} to be 32-bit on your platform. - -The Gnulib module @samp{year2038-required} is -recommended for any package that might be used after the year 2038 on -32-bit platforms. However, if your package needs to support -platforms that will not be used after the year 2038, -you can use the @samp{year2038} module instead. - If the Gnulib module @samp{largefile} is used but neither @samp{year2038} nor @samp{year2038-required} is used, @command{configure} will have an option @option{--enable-year2038} that causes @code{configure} to behave as if @samp{year2038} was used. This is for packages that have long used @samp{largefile} but have not -gotten around to upgrade their Gnulib module list to include -@samp{year2038-required} or @samp{year2038}. +gotten around to upgrading their Gnulib module list to include +@samp{year2038} or @samp{year2038-required}. @xref{Large File Support}. -- 2.37.2