From f91f633858cf132e50924224c50d6264a92caabb Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Sun, 9 Apr 2023 18:16:57 -0700 Subject: largefile: sync from Autoconf master * modules/largefile-required, modules/year2038-required: New modules. * MODULES.html.sh, doc/largefile.texi, doc/posix-headers/time.texi: * doc/year2038.texi: Document this. * m4/largefile.m4: Sync from Autoconf master. Conditionalize the workaround on AC_SYS_LARGEFILE_REQUIRED rather than on AC_SYS_YEAR2038 so that we replace older but still unreleased Autoconf. (AC_SYS_LARGEFILE_REQUIRED, AC_SYS_YEAR2038_REQUIRED): New macros. --- doc/largefile.texi | 19 +++++++++++++--- doc/posix-headers/time.texi | 8 +++++-- doc/year2038.texi | 54 ++++++++++++++++++++++++++++++--------------- 3 files changed, 58 insertions(+), 23 deletions(-) (limited to 'doc') diff --git a/doc/largefile.texi b/doc/largefile.texi index 13572b47e5..b5bfa5116a 100644 --- a/doc/largefile.texi +++ b/doc/largefile.texi @@ -1,9 +1,22 @@ @node Large File Support @section Large File Support -The module provides support for files larger than 2 GB, or with device -or inode numbers or timestamps exceeding 32 bits. To this effect, it -ensures that types like @code{off_t} and @code{time_t} are 64-bit when possible, +The Gnulib @samp{largefile-required} module provides support for files +2 GiB and larger, or with device or inode numbers exceeding 32 bits. +To this effect, it ensures that types like @code{off_t} and +@code{ino_t} are 64-bit, at least on the following platforms: glibc, Mac OS X, FreeBSD, NetBSD, OpenBSD, AIX, HP-UX, IRIX, Solaris, Cygwin, mingw, MSVC. + +The Gnulib @samp{largefile} module is similar, except that it gives +@command{configure} an option @samp{--disable-largefile} that +suppresses support for large files. This may be useful if the package +links to other libraries whose user-facing ABIs still require +@code{off_t} or most other file-related types to be 32-bit on your +platform. + +Both modules also add to @command{configure} an option +@code{--enable-year2038}, needed on some platforms to access files +with timestamps past the year 2038. @xref{Avoiding the year 2038 +problem}. diff --git a/doc/posix-headers/time.texi b/doc/posix-headers/time.texi index 5ecebbfdda..a506ec640c 100644 --- a/doc/posix-headers/time.texi +++ b/doc/posix-headers/time.texi @@ -18,14 +18,16 @@ expressions: NetBSD 5.0. @end itemize -Portability problems fixed by the Gnulib module @code{year2038}: +Portability problems fixed by the Gnulib modules +@code{year2038-required} and @code{year-2038}: @itemize @item On some platforms where @code{time_t} defaults to 32-bit but can be changed to 64-bit, functions like @code{stat} can fail with @code{errno == EOVERFLOW} when a 32-bit timestamp is out of range, such as with a file timestamp in the far future or past: -glibc 2.34. +glibc 2.34+ atop 32-bit x86 or ARM Linux. +@xref{Avoiding the year 2038 problem}. @end itemize Portability problems not fixed by Gnulib: @@ -39,6 +41,8 @@ the functions silently return the low-order 32 bits of the correct timestamp. These platforms will be obsolete when 32-bit @code{time_t} rolls around, which will occur in 2038 for the typical case when @code{time_t} is signed. +@xref{Avoiding the year 2038 problem}. + @item On some platforms the @code{tv_nsec} member of @code{struct timespec} is not of type @code{long}, but is of type @code{long long} instead: diff --git a/doc/year2038.texi b/doc/year2038.texi index 213fda235f..d98753101e 100644 --- a/doc/year2038.texi +++ b/doc/year2038.texi @@ -1,25 +1,43 @@ @node Avoiding the year 2038 problem @section Avoiding the year 2038 problem -The ``year 2038 problem'' denotes unpredictable behaviour of programs -that will likely occur in the year 2038, for programs that use a 32-bit -@samp{time_t} type. See @url{https://en.wikipedia.org/wiki/Year_2038_problem} -for details. +The ``year 2038 problem'' denotes unpredictable behaviour that will +likely occur in the year 2038, for programs that use a 32-bit signed +integer @samp{time_t} type that cannot represent timestamps on or +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} attempts to avoid this problem, by -ensuring that @code{time_t} is a 64-bit type and by causing -@code{configure} to fail otherwise. +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 +timestamps. On older platforms that do not support timestamps after +the year 2038, @samp{year2038-required} causes @command{configure} to +fail. -The Gnulib module @samp{largefile} also attempts to avoid this problem -when possible, because @samp{largefile} enables the widest -file-related types supported by the system and @code{time_t} is one of -those types. However, @code{largefile} does not cause -@code{configure} to fail when the year 2038 problem is not avoidable. +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 @samp{largefile} and @samp{year2038} modules are +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 you build such a package you can -disable its use of 64-bit @code{time_t} by giving the -@code{--disable-year2038} option to @code{configure}. 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. +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}. +@xref{Large File Support}. -- cgit v1.2.1