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.

3 files changed, 58 insertions, 23 deletions

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