Re: On time64 and Large File Support
Paul Eggert <[email protected]> Fri, 30 Dec 2022 14:12:32 -0800
| Newsgroups | gmane.comp.sysutils.autoconf.patches |
|---|---|
| Message-ID | <[email protected]> |
On 12/28/22 20:02, Zack Weinberg wrote:
> Please revert that part of your follow-up patch.
OK, I reverted all that patch, except for the further changes you
requested, plus some minor quoting and version-number fixes in comments.
> Is there any
> chance you could send a wdiff to the list, after restoring the text
> you took out because you took out the _REQUIRED variants?
Sure, I'm attaching a proposed patch to Autoconf master documentation in
two forms. The first is a simple "git format-patch" file; the second is
the output of "git diff --color=always --word-diff=color".
> I want it to be
> crystal clear from the text of configure.ac that it bombed out because
> package X considers 64-bit time_t and/or off_t a requirement.
Although I don't think this feature is useful, I don't have to use it so
we can leave it in.
Here's why I'm not planning to use it. I help maintain (for example) GNU
Tar, where file sizes and timestamps are crucial. But if I change GNU
Tar to use AC_SYS_LARGEFILE_REQUIRED, people won't be able to build GNU
Tar on ancient platforms that support file sizes only up to 2 GiB.
Nobody will benefit from this: the very few users who'd care (computer
museum curators, say) already know their systems are limited, and will
simply build older versions of GNU Tar that don't use
AC_SYS_LARGEFILE_REQUIRED, or will edit away the "_REQUIRED" before
building. So adding the _REQUIRED will harm a very small set of users,
will increase my maintenance burden a bit, and will benefit essentially
nobody.
To put it another way: we've all gotten by without needing
AC_SYS_LARGEFILE_REQUIRED for 25 years, and there's no reason for us to
start needing it now even though it's imperative for any serious
application that deals with files.
The situation for AC_SYS_YEAR2038_REQUIRED will likely be similar.
As things currently stand, I plan to use AC_SYS_YEAR2038 instead of
AC_SYS_LARGEFILE in GNU Tar and similar applications. (They'll use
Gnulib so they'll get Autoconf 2.72-compatible AC_SYS_YEAR2038 even with
older Autoconf.) Perhaps other maintainers will want to use the
*_REQUIRED macros, but as far as I can see my advice will be to avoid
them as being more trouble than they're worth.
> I *intended* to make it clear that they are not orthogonal in
> practice, but it is not logically necessary for them to be coupled,
> and it is, I think, easier to understand what
> AC_SYS_{LARGEFILE,YEAR2038} do if we document them as abstractly
Unfortunately the documenation currently on Autoconf master makes for a
lot of confusion and misimpression. It's more important for
documentation to agree with what the code actually does, than for it to
present an abstract picture of what we'd like the code to do eventually.
The abovementioned patches fix this.
> In the new year, I can look into the possibility of decoupling the
> macros’ implementations.
I don't see how that would be possible. On the only platforms where
--enable-year2038 matters, you cannot have year-2038 support without
also having large-file support.
The platforms in question are glibc 2.34+ on 32-bit ARM and x86. The
glibc community considered making the two things orthogonal but rejected
that alternative as being considerably more trouble than it was worth. I
think it unlikely for other 32-bit OS suppliers to decide differently.
> I think you’re still writing documentation with application-colored
> glasses on, making it sound like --enable-year2038 has no negative
> implications whatsoever.
That's a bit unfair. The proposed documentation does mention the
compatibility implications; it merely uses the same level of caution for
both --enable-largefile and --enable-year2038, and it doesn't overhype
the time_t issue with an undeserved big "Caution:" inbold.
Although I plead guilty in being close to users (many who need year 2038
support now for obvious reasons) I'm well aware of the implication for
libraries. When I implemented AC_SYS_LARGEFILE back in the 1990s, there
were similar compatibility concerns with off_t that I also took
seriously. In the end, the need for large-file support outweighed the
backward-compatibility hassles and AC_SYS_LARGEFILE has been a success
in that people have used AC_SYS_LARGEFILE for years and sure there are
occasionally glitches but the benefits far outweigh the costs.
AC_SYS_YEAR2038 will be similar. Not identical of course, but similar.
We've done this sort of thing before and have experience.
> I do not believe we have consensus
> for AC_SYS_LARGEFILE to become a synonym for AC_SYS_YEAR2038, not even
> “in a future Autoconf version.”
The proposed documentation patches contain a simple plan for how
Autoconf can plausibly survive through the year 2038. Is there a better
plan? If so, I'd like to hear it. If not, then let's use this plan.
Given the long delay between Autoconf versions and end uses of
downstream software, we need a plan now, not years from now. The plan
doesn't have to be perfect, nor does it need to be cast in stone. But
there needs to be a plan.
0001-Improve-year-2038-documentation.patch
(text/x-patch, 16.4 KB)
From 3e9f1159ae9145c50d048a74422dd8464a6a8f6f Mon Sep 17 00:00:00 2001 From: Paul Eggert <[email protected]> Date: Fri, 30 Dec 2022 12:48:39 -0800 Subject: [PATCH] Improve year-2038 documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * NEWS, doc/autoconf.texi (System Services): Improve documentation for behavior of largefile and year-2038 support. Say that in the current implementation, year-2038 support requires largefile support. Say that year-2038 support matters only for GNU/Linux glibc 2.34+ on 32-bit x86 and ARM. Prefer brevity when this does not hurt understandability; for example, prefer active to passive voice. Prefer “wider” to “larger” when talking about the number of bits in an integer, as this terminology is more standard. Tone down the wording in warnings about enabling year-2038 support, use similar wording in warnings about enabling largefile support, and warn also about disabling largefile and year-2038 support. No need for @emph. Also mention rlim_t. Be a bit more careful about saying “2 GiB” rather than “2 GB”. Mention that a future version of Autoconf might change AC_SYS_LARGEFILE to default to --enable-year2038, since something has gotta happen before 2038. Coalesce descriptions of --enable-largefile and --enable-year2038 to simplify documentation. Mention that the only system where AC_SYS_LARGEFILE changes CC is IRIX and that these systems are obsolete. Say that ‘stat’ can fail due to time_t overflow. Say that you can’t portably print time_t with %ld. Say that binary compatibilty problems also can occur when one library is linking to amother; it’s not just apps vs libraries. Mention the possibility of modifying libraries to support both 32- and 64-bit interfaces. Warn more consistently about ABI compatibility issues, but put the bulk of this text in one location that the other locations refer to. --- NEWS | 57 ++++++++-------- doc/autoconf.texi | 165 ++++++++++++++++++++++++---------------------- 2 files changed, 113 insertions(+), 109 deletions(-) diff --git a/NEWS b/NEWS index eafd7d69..0f71628d 100644 --- a/NEWS +++ b/NEWS @@ -27,36 +27,33 @@ GNU Autoconf NEWS - User visible changes. ** New features -*** New macros AC_SYS_YEAR2038 and AC_SYS_YEAR2038_REQUIRED. - These macros attempt to enlarge time_t to 64 bits, on systems where - it has historically been only 32 bits wide, and therefore (assuming - the usual Unix epoch) cannot represent dates after mid-January of - 2038 (hence the names). The difference between the two is that - AC_SYS_YEAR2038_REQUIRED unconditionally causes 'configure' to error - out if 64-bit time_t is not available. - - Enlarging time_t to 64 bits is likely to have the side effect of - enlarging off_t and related types to 64 bits as well, as if you - had used AC_SYS_LARGEFILE. See the manual for details. - - Library authors should be cautious about adding these macros to - their configure scripts; they can break binary backward compatibility. - -*** New macro AC_SYS_LARGEFILE_REQUIRED. - This macro is the same as the existing AC_SYS_LARGEFILE except that - it will cause 'configure' to error out if 64-bit off_t is not available, - and it does not provide a --disable-largefile option. - -*** AC_SYS_LARGEFILE now optionally arranges to enlarge time_t. - As an experimental measure to make it easier to rebuild old programs - with support for dates after Jan 2038, if you regenerate any configure - script that uses AC_SYS_LARGEFILE (but not AC_SYS_YEAR2038) using - Autoconf 2.72, it will gain an --enable-year2038 option. When the - program is configured with this option, time_t will be enlarged if - possible, as if AC_SYS_YEAR2038 had been used. - - Using this option in a library build also potentially breaks binary - backward compatibility. +*** New macro AC_SYS_YEAR2038. + This causes 'configure' to widen time_t if possible on systems where + time_t by default cannot represent file and other timestamps after + January 2038. Widening is possible only on 32-bit GNU/Linux x86 and + ARM systems with glibc 2.34 or later. To prevent widening, + configure with --disable-year2038. + + This macro also has the effects as AC_SYS_LARGEFILE, because in + practice time_t cannot be widened without large-file sypport. + + Application and library builders should take care that packages + configured with --enable-year2038 and --disable-year2038 options + are configured consistently, to avoid breaking binary compatibility. + This is similar to longstanding consistency requirements with + --enable-largefile and --disable-largefile. + +*** AC_SYS_LARGEFILE now optionally arranges to widen time_t. + It now acts like AC_SYS_YEAR2038, except 'configure' defaults to + --disable-year2038 unless AC_SYS_YEAR2038 is also present. + As with AC_SYS_YEAR2038, application and library builders should + configure consistently. + +*** New macros AC_SYS_LARGEFILE_REQUIRED and AC_SYS_YEAR2038_REQUIRED. + These act like AC_SYS_LARGEFILE and AC_SYS_YEAR2038 respectively, + except that they require large-file and year-2038 support respectively. + As with AC_SYS_YEAR2038, application and library builders should + configure consistently. *** AC_USE_SYSTEM_EXTENSIONS now enables C23 Annex F extensions by defining __STDC_WANT_IEC_60559_EXT__. diff --git a/doc/autoconf.texi b/doc/autoconf.texi index df96280b..ce214284 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -8798,71 +8798,109 @@ if the system supports @samp{#!}, @samp{no} if not. @defmac AC_SYS_LARGEFILE @acindex{SYS_LARGEFILE} @cvindex _FILE_OFFSET_BITS +@cvindex _TIME_BITS @ovindex CC @cindex Large file support @cindex LFS -If the default @code{off_t} type is a 32-bit integer, and therefore -cannot be used to work with files larger than 4 gigabytes, arrange to -make a larger @code{off_t} available, if the system supports this. -Several other types related to the sizes of files and file systems will -also be enlarged: @code{ino_t}, @code{blkcnt_t}, @code{fsblkcnt_t}, -@code{fsfilcnt_t}, and possibly @code{dev_t}. - -If a large @code{off_t} is available (whether or not any arrangements -were necessary), the shell variable @code{ac_have_largefile} will be set -to @samp{yes}; if not, it will be set to @samp{no}. - -Preprocessor macros will be defined if necessary to make a larger -@code{off_t} available. (For example, on many systems the macro -@code{_FILE_OFFSET_BITS} will be defined.) Some of these macros only -work if they are defined before the first system header is included; +If the default @code{off_t} type is a 32-bit integer, +and therefore cannot be used with files 2 GiB or larger, +make a wider @code{off_t} available if the system supports it. +Similarly, widen other types related to sizes of files and file systems +if possible. These types may include @code{blkcnt_t}, @code{dev_t}, +@code{ino_t}, @code{fsblkcnt_t}, @code{fsfilcnt_t}, and @code{rlim_t}. + +Also, arrange for a @command{configure} option @code{--enable-year2038} +to request widening the type @code{time_t} as needed to represent file +wand other timestamps after January 2038. This widening is possible +only on 32-bit GNU/Linux x86 and ARM systems with glibc 2.34 or later. +If year-2038 support is requested but @command{configure} fails to find a way +to widen @code{time_t} and inspection of the system suggests that +this feature is available somehow, @command{configure} will error out. +If you want the default to be @code{--enable-year2038}, you can use +@code{AC_SYS_YEAR2038} instead of @code{AC_SYS_LARGEFILE}. +In other words, older packages that have long used @code{AC_SYS_LARGEFILE} +can have year-2038 support on 32-bit GNU/Linux x86 and ARM systems either by +regenerating @file{configure} with current Autoconf and configuring with +@option{--enable-year2038}, or by using @code{AC_SYS_YEAR2038} and +configuring without @option{--disable-year2038}. +A future version of Autoconf might change the @code{AC_SYS_LARGEFILE} +default to @code{--enable-year2038}; if and when that happens, +@code{AC_SYS_LARGEFILE} and @code{AC_SYS_YEAR2038} will become equivalent. +@xref{AC_SYS_YEAR2038}. + +Set the shell variable @code{ac_have_largefile} to to @samp{yes} or +@code{no} depending on whether a wide @code{off_t} is available, +regardless of whether arrangements were necessary. +Similarly, set the shell variable @code{ac_have_year2038} to @code{yes} +or @code{no} depending on whether a wide-enough @code{time_t} is available. + +Define preprocessor macros if necessary to make types wider; +for example, on GNU/Linux systems the macros @code{_FILE_OFFSET_BITS} +and @code{_TIME_BITS} can be defined. Some of these macros work only if +defined before the first system header is included; therefore, when using this macro in concert with @code{AC_CONFIG_HEADERS}, make sure that @file{config.h} is included before any system headers. -On a few older systems, the output variable @code{CC} will also be -changed to add special compiler options that are needed to enable large -@code{off_t}. +On obsolete IRIX systems, also change the output variable @code{CC} to +add compiler options needed for wide @code{off_t}. Large-file support can be disabled by configuring with the -@option{--disable-largefile} option. Note that this has no effect on -systems where @code{off_t} is 64 bits or larger by default. Disabling -large-file support can have surprising effects, such as causing -functions like @code{readdir} and @code{stat} to fail on small files -(because their @emph{inode numbers} are unrepresentable). +@option{--disable-largefile} option, and year-2038 support can +be enabled and disabled via the @option{--enable-year2038} and +@option{--disable-year2038} options. These options have no effect on +systems where types are wide enough by default. +Large-file support is required for year-2038 support: if you configure +with @option{--disable-largefile} on a platform with 32-bit +@code{time_t}, then year-2038 support is not available. + +Disabling large-file or year-2038 support can have surprising effects, +such as causing functions like @code{readdir} and @code{stat} to fail +even on a small file because its inode number or timestamp is out of range. Regardless of whether you use this macro, portable programs should not assume that any of the types listed above fit into a @code{long int}. -For example, it is not correct to print an arbitrary @code{off_t} value -@code{X} with @code{printf ("%ld", (long int) X)}. +For example, it is not portable to print an arbitrary @code{off_t} or +@code{time_t} value @code{X} with @code{printf ("%ld", (long int) X)}. -Note that the standard C library functions @code{fseek} and @code{ftell} +The standard C library functions @code{fseek} and @code{ftell} do not use @code{off_t}. If you need to use either of these functions, you should use @code{AC_FUNC_FSEEKO} as well as @code{AC_SYS_LARGEFILE}, -and then use their Posix replacements @code{fseeko} and @code{ftello}, -which @emph{do} use @code{off_t}, when available. @xref{AC_FUNC_FSEEKO}. - -As of Autoconf 2.72, @code{AC_SYS_LARGEFILE} also @emph{optionally} -arranges to enlarge @code{time_t}. This is to make it easier to build -programs that support timestamps after 2038; many configure scripts will -not need to be modified, only regenerated with newer Autoconf. When -@code{AC_SYS_LARGEFILE} is used, and @code{AC_SYS_YEAR2038} is -@emph{not} used, @code{time_t} will normally be left at the system's -default size, but you can request it be enlarged by configuring with the -@option{--enable-year2038} option. (When @code{AC_SYS_YEAR2038} is also -used, @code{time_t} is enlarged if possible. @xref{AC_SYS_YEAR2038}.) +and then use their Posix replacements @code{fseeko} and @code{ftello}. +@xref{AC_FUNC_FSEEKO}. + +When using @code{AC_SYS_LARGEFILE} in different packages that are linked +together and that have interfaces that depend on the width of @code{off_t}, +@code{time_t} or related types, the simplest thing is to configure all +components the same way. For example, if an application uses +@code{AC_SYS_LARGEFILE} and is configured with +@option{--enable-year2038}, libraries it links to with an @code{off_t}- +or @code{time_t}-dependent interface should be configured equivalently. +Alternatively, you can modify libraries to support both 32- and 64-bit +interfaces though this is more work and few libraries other than the C +library itself are modified in this way. + +Applications and libraries should be configured compatibly. +If @code{off_t}, @code{time_t} or related types appear in a library's +public interface, enabling or disabling the library's large-file or +year-2038 support may break binary compatibility with applications or +with other libraries. Similarly, if an application links to a such a +library, enabling or disabling the application's large-file support may +break binary compatibility with that library. @end defmac @defmac AC_SYS_LARGEFILE_REQUIRED @acindex{SYS_LARGEFILE_REQUIRED} This macro has the same effect as @code{AC_SYS_LARGEFILE}, but also declares that the program being configured -@emph{requires} support for large files. +requires support for large files. If a large @code{off_t} is unavailable, @command{configure} will error out. The @option{--disable-largefile} option will not be available. -@end defmac +Large-file and year-2038 support for applications and libraries should +be configured compatibly. @xref{AC_SYS_LARGEFILE}. +@end defmac @anchor{AC_SYS_LONG_FILE_NAMES} @defmac AC_SYS_LONG_FILE_NAMES @@ -8885,55 +8923,24 @@ system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to @anchor{AC_SYS_YEAR2038} @defmac AC_SYS_YEAR2038 @acindex{SYS_YEAR2038} -@cvindex _TIME_BITS @cindex Year 2038 -If the default @code{time_t} type is a signed 32-bit integer, -and therefore (assuming the usual Unix epoch) cannot represent -timestamps after mid-January of 2038, arrange to make a larger -@code{time_t} available, if the system supports this. - -If a large @code{time_t} is available (whether or not any arrangements -were necessary), the shell variable @code{ac_have_year2038} will be set -to @samp{yes}; if not, it will be set to @samp{no}. - -Preprocessor macros will be defined if necessary to make a larger -@code{time_t} available. (For example, on some systems the macro -@code{_TIME_BITS} will be defined.) Some of these macros only work if -they are defined before the first system header is included; therefore, -when using this macro in concert with @code{AC_CONFIG_HEADERS}, make -sure that @file{config.h} is included before any system headers. - -Support for timestamps after 2038 can be disabled by configuring with -the @option{--disable-year2038} option. Note that this has no effect on -systems where @code{time_t} is 64 bits or larger by default. -If this option is @emph{not} given, and @command{configure} fails to -find a way to enable a large @code{time_t}, but inspection of the -system suggests that this feature is available @emph{somehow}, it will -error out. - -Regardless of whether you use this macro, portable programs should not -assume that @code{time_t} fits into @code{long int}. For example, it is -not correct to print an arbitrary @code{time_t} value @code{X} with -@code{printf ("%ld", (long int) X)}. - -@strong{Caution:} If you are developing a shared library, and -@code{time_t} appears anywhere in your library's public interface, use -of this macro may break binary compatibility with older executables. +This is like @code{AC_SYS_LARGEFILE} except it defaults to enabling +instead of disabling year-2038 support. Year-2038 support for +applications and libraries should be configured compatibly. +@xref{AC_SYS_LARGEFILE}. @end defmac @defmac AC_SYS_YEAR2038_REQUIRED @acindex{SYS_YEAR2038_REQUIRED} This macro has the same effect as @code{AC_SYS_YEAR2038}, but also declares that the program being configured -@emph{requires} support for timestamps after mid-January of 2038. +requires support for timestamps after mid-January of 2038. If a large @code{time_t} is unavailable, -@command{configure} will @emph{unconditionally} error out -(unlike the behavior of @code{AC_SYS_YEAR2038}). +@command{configure} will unconditionally error out. The @option{--disable-year2038} option will not be available. -@strong{Caution:} If you are developing a shared library, and -@code{time_t} appears anywhere in your library's public interface, use -of this macro may break binary compatibility with older executables. +Year-2038 support for applications and libraries should be configured +compatibly. @xref{AC_SYS_YEAR2038}. @end defmac @node C and Posix Variants -- 2.38.1
Improve-year-2038-doc-wdiff-color.txt
(text/plain, 15 KB)
[1mdiff --git a/NEWS b/NEWS[m
[1mindex eafd7d69..0f71628d 100644[m
[1m--- a/NEWS[m
[1m+++ b/NEWS[m
[36m@@ -27,36 +27,33 @@[m [mGNU Autoconf NEWS - User visible changes.[m
** New features[m
*** New [31mmacros AC_SYS_YEAR2038 and AC_SYS_YEAR2038_REQUIRED.[m
[31m These macros attempt[m[32mmacro AC_SYS_YEAR2038.[m
[32m This causes 'configure'[m to [31menlarge[m[32mwiden[m time_t [31mto 64 bits,[m[32mif possible[m on systems where
[31mit has historically been only 32 bits wide, and therefore (assuming[m
[31m the usual Unix epoch)[m[32mtime_t by default[m cannot represent [31mdates[m[32mfile and other timestamps[m after
[31mmid-January of[m
[31m 2038 (hence the names). The difference between the two[m[32mJanuary 2038. Widening[m is [31mthat[m
[31m AC_SYS_YEAR2038_REQUIRED unconditionally causes 'configure' to error[m
[31m out if 64-bit time_t is not available.[m
[31m Enlarging time_t to 64 bits is likely to have the side effect of[m
[31m enlarging off_t[m[32mpossible only on 32-bit GNU/Linux x86[m and
[31mrelated types to 64 bits as well, as if you[m
[31m had used AC_SYS_LARGEFILE. See the manual for details.[m
[31m Library authors should be cautious about adding these macros to[m
[31m their[m[32mARM systems with glibc 2.34 or later. To prevent widening,[m
configure [31mscripts; they can break binary backward compatibility.[m
[31m*** New macro AC_SYS_LARGEFILE_REQUIRED.[m[32mwith --disable-year2038.[m
This macro [31mis[m[32malso has[m the [31msame[m[32meffects[m as [31mthe existing AC_SYS_LARGEFILE except[m[32mAC_SYS_LARGEFILE, because in[m
[32m practice time_t cannot be widened without large-file sypport.[m
[32m Application and library builders should take care[m that [31mit will cause 'configure'[m[32mpackages[m
[32m configured with --enable-year2038 and --disable-year2038 options[m
[32m are configured consistently,[m to [31merror out if 64-bit off_t[m[32mavoid breaking binary compatibility.[m
[32m This[m is [31mnot available,[m[32msimilar to longstanding consistency requirements with[m
[32m --enable-largefile[m and [31mit does not provide a --disable-largefile option.[m[32m--disable-largefile.[m
*** AC_SYS_LARGEFILE now optionally arranges to [31menlarge[m[32mwiden[m time_t.
[31mAs an experimental measure to make it easier[m[32mIt now acts like AC_SYS_YEAR2038, except 'configure' defaults[m to
[31mrebuild old programs[m[32m--disable-year2038 unless AC_SYS_YEAR2038 is also present.[m
[32m As[m with [31msupport for dates after Jan 2038, if you regenerate any[m[32mAC_SYS_YEAR2038, application and library builders should[m
configure [31mscript that uses[m[32mconsistently.[m
[32m*** New macros AC_SYS_LARGEFILE_REQUIRED and AC_SYS_YEAR2038_REQUIRED.[m
[32m These act like[m AC_SYS_LARGEFILE [31m(but not AC_SYS_YEAR2038) using[m
[31m Autoconf 2.72, it will gain an --enable-year2038 option. When the[m
[31m program is configured with this option, time_t will be enlarged if[m
[31m possible, as if[m[32mand[m AC_SYS_YEAR2038 [31mhad been used.[m
[31m Using this option in a[m[32mrespectively,[m
[32m except that they require large-file and year-2038 support respectively.[m
[32m As with AC_SYS_YEAR2038, application and[m library [31mbuild also potentially breaks binary[m
[31m backward compatibility.[m[32mbuilders should[m
[32m configure consistently.[m
*** AC_USE_SYSTEM_EXTENSIONS now enables C23 Annex F extensions[m
by defining __STDC_WANT_IEC_60559_EXT__.[m
[1mdiff --git a/doc/autoconf.texi b/doc/autoconf.texi[m
[1mindex df96280b..ce214284 100644[m
[1m--- a/doc/autoconf.texi[m
[1m+++ b/doc/autoconf.texi[m
[36m@@ -8798,71 +8798,109 @@[m [mif the system supports @samp{#!}, @samp{no} if not.[m
@defmac AC_SYS_LARGEFILE[m
@acindex{SYS_LARGEFILE}[m
@cvindex _FILE_OFFSET_BITS[m
[32m@cvindex _TIME_BITS[m
@ovindex CC[m
@cindex Large file support[m
@cindex LFS[m
If the default @code{off_t} type is a 32-bit integer,
and therefore cannot be used[31mto work[m with files [31mlarger than 4 gigabytes, arrange to[m[32m2 GiB or larger,[m
make a [31mlarger[m[32mwider[m @code{off_t} [31mavailable,[m[32mavailable[m if the system supports [31mthis.[m
[31mSeveral[m[32mit.[m
[32mSimilarly, widen[m other types related to[31mthe[m sizes of files and file systems
[31mwill[m
[31malso be enlarged: @code{ino_t},[m[32mif possible. These types may include[m @code{blkcnt_t}, [32m@code{dev_t},[m
[32m@code{ino_t},[m @code{fsblkcnt_t}, @code{fsfilcnt_t}, and [31mpossibly @code{dev_t}.[m[32m@code{rlim_t}.[m
[32mAlso, arrange for a @command{configure} option @code{--enable-year2038}[m
[32mto request widening the type @code{time_t} as needed to represent file[m
[32mwand other timestamps after January 2038. This widening is possible[m
[32monly on 32-bit GNU/Linux x86 and ARM systems with glibc 2.34 or later.[m
If [32myear-2038 support is requested but @command{configure} fails to find[m a [31mlarge @code{off_t}[m[32mway[m
[32mto widen @code{time_t} and inspection of the system suggests that[m
[32mthis feature[m is available [31m(whether[m[32msomehow, @command{configure} will error out.[m
[32mIf you want the default to be @code{--enable-year2038}, you can use[m
[32m@code{AC_SYS_YEAR2038} instead of @code{AC_SYS_LARGEFILE}.[m
[32mIn other words, older packages that have long used @code{AC_SYS_LARGEFILE}[m
[32mcan have year-2038 support on 32-bit GNU/Linux x86 and ARM systems either by[m
[32mregenerating @file{configure} with current Autoconf and configuring with[m
[32m@option{--enable-year2038},[m or [31mnot any arrangements[m
[31mwere necessary),[m[32mby using @code{AC_SYS_YEAR2038} and[m
[32mconfiguring without @option{--disable-year2038}.[m
[32mA future version of Autoconf might change the @code{AC_SYS_LARGEFILE}[m
[32mdefault to @code{--enable-year2038}; if and when that happens,[m
[32m@code{AC_SYS_LARGEFILE} and @code{AC_SYS_YEAR2038} will become equivalent.[m
[32m@xref{AC_SYS_YEAR2038}.[m
[32mSet[m the shell variable @code{ac_have_largefile}[31mwill be set[m to [31m@samp{yes}; if not, it will be[m[32mto @samp{yes} or[m
[32m@code{no} depending on whether a wide @code{off_t} is available,[m
[32mregardless of whether arrangements were necessary.[m
[32mSimilarly,[m set [32mthe shell variable @code{ac_have_year2038}[m to [31m@samp{no}.[m
[31mPreprocessor[m[32m@code{yes}[m
[32mor @code{no} depending on whether a wide-enough @code{time_t} is available.[m
[32mDefine preprocessor[m macros[31mwill be defined[m if necessary to make [31ma larger[m
[31m@code{off_t} available. (For[m[32mtypes wider;[m
[32mfor[m example, on [31mmany[m[32mGNU/Linux[m systems the [31mmacro[m[32mmacros[m @code{_FILE_OFFSET_BITS}
[31mwill[m[32mand @code{_TIME_BITS} can[m be [31mdefined.)[m[32mdefined.[m Some of these macros[31monly[m work [32monly[m if[31mthey are[m
defined before the first system header is included;
therefore, when using this macro in concert with[m
@code{AC_CONFIG_HEADERS}, make sure that @file{config.h} is included[m
before any system headers.[m
On [31ma few older[m[32mobsolete IRIX[m systems, [32malso change[m the output variable @code{CC}[31mwill also be[m
[31mchanged[m to
add[31mspecial[m compiler options[31mthat are[m needed [31mto enable large[m[32mfor wide[m @code{off_t}.
Large-file support can be disabled by configuring with the[m
@option{--disable-largefile} [31moption. Note that this has[m[32moption, and year-2038 support can[m
[32mbe enabled and disabled via the @option{--enable-year2038} and[m
[32m@option{--disable-year2038} options. These options have[m no effect on
systems where [31m@code{off_t} is 64 bits or larger[m[32mtypes are wide enough[m by default.
[32mLarge-file support is required for year-2038 support: if you configure[m
[32mwith @option{--disable-largefile} on a platform with 32-bit[m
[32m@code{time_t}, then year-2038 support is not available.[m
Disabling large-file [32mor year-2038[m support can have surprising effects,
such as causing functions like @code{readdir} and @code{stat} to fail
[32meven[m on [32ma[m small [31mfiles[m
[31m(because their @emph{inode numbers} are unrepresentable).[m[32mfile because its inode number or timestamp is out of range.[m
Regardless of whether you use this macro, portable programs should not[m
assume that any of the types listed above fit into a @code{long int}.[m
For example, it is not [31mcorrect[m[32mportable[m to print an arbitrary @code{off_t} [32mor[m
[32m@code{time_t}[m value @code{X} with @code{printf ("%ld", (long int) X)}.
[31mNote that the[m[32mThe[m standard C library functions @code{fseek} and @code{ftell}
do not use @code{off_t}. If you need to use either of these functions,[m
you should use @code{AC_FUNC_FSEEKO} as well as @code{AC_SYS_LARGEFILE},[m
and then use their Posix replacements @code{fseeko} and [31m@code{ftello},[m
[31mwhich @emph{do} use @code{off_t}, when available.[m[32m@code{ftello}.[m
@xref{AC_FUNC_FSEEKO}.
[31mAs of Autoconf 2.72,[m[32mWhen using[m @code{AC_SYS_LARGEFILE} [31malso @emph{optionally}[m
[31marranges to enlarge @code{time_t}. This[m[32min different packages that are linked[m
[32mtogether and that have interfaces that depend on the width of @code{off_t},[m
[32m@code{time_t} or related types, the simplest thing[m is to[31mmake it easier to build[m
[31mprograms that support timestamps after 2038; many[m configure [31mscripts will[m
[31mnot need to be modified, only regenerated with newer Autoconf. When[m[32mall[m
[32mcomponents the same way. For example, if an application uses[m
@code{AC_SYS_LARGEFILE}[31mis used,[m and[31m@code{AC_SYS_YEAR2038}[m is [31m@emph{not} used, @code{time_t} will normally[m[32mconfigured with[m
[32m@option{--enable-year2038}, libraries it links to with an @code{off_t}-[m
[32mor @code{time_t}-dependent interface should[m be [31mleft at the system's[m
[31mdefault size, but[m[32mconfigured equivalently.[m
[32mAlternatively,[m you can [31mrequest it be enlarged by configuring with the[m
[31m@option{--enable-year2038} option. (When @code{AC_SYS_YEAR2038}[m[32mmodify libraries to support both 32- and 64-bit[m
[32minterfaces though this[m is [31malso[m
[31mused,[m[32mmore work and few libraries other than the C[m
[32mlibrary itself are modified in this way.[m
[32mApplications and libraries should be configured compatibly.[m
[32mIf @code{off_t},[m @code{time_t} [31mis enlarged[m[32mor related types appear in a library's[m
[32mpublic interface, enabling or disabling the library's large-file or[m
[32myear-2038 support may break binary compatibility with applications or[m
[32mwith other libraries. Similarly,[m if [31mpossible. @xref{AC_SYS_YEAR2038}.)[m[32man application links to a such a[m
[32mlibrary, enabling or disabling the application's large-file support may[m
[32mbreak binary compatibility with that library.[m
@end defmac[m
@defmac AC_SYS_LARGEFILE_REQUIRED[m
@acindex{SYS_LARGEFILE_REQUIRED}[m
This macro has the same effect as @code{AC_SYS_LARGEFILE},[m
but also declares that the program being configured[m
[31m@emph{requires}[m[32mrequires[m support for large files.
If a large @code{off_t} is unavailable,[m
@command{configure} will error out.[m
The @option{--disable-largefile} option will not be available.[m
[31m@end defmac[m
[32mLarge-file and year-2038 support for applications and libraries should[m
[32mbe configured compatibly. @xref{AC_SYS_LARGEFILE}.[m
[32m@end defmac[m
@anchor{AC_SYS_LONG_FILE_NAMES}[m
@defmac AC_SYS_LONG_FILE_NAMES[m
[36m@@ -8885,55 +8923,24 @@[m [msystem. If so, set the shell variable @code{ac_cv_sys_posix_termios} to[m
@anchor{AC_SYS_YEAR2038}[m
@defmac AC_SYS_YEAR2038[m
@acindex{SYS_YEAR2038}[m
[31m@cvindex _TIME_BITS[m
@cindex Year 2038[m
[31mIf the default @code{time_t} type[m[32mThis[m is [31ma signed 32-bit integer,[m
[31mand therefore (assuming the usual Unix epoch) cannot represent[m
[31mtimestamps after mid-January of 2038, arrange to make a larger[m
[31m@code{time_t} available, if the system supports this.[m
[31mIf a large @code{time_t} is available (whether or not any arrangements[m
[31mwere necessary), the shell variable @code{ac_have_year2038} will be set[m
[31mto @samp{yes}; if not,[m[32mlike @code{AC_SYS_LARGEFILE} except[m it [31mwill be set[m[32mdefaults[m to [31m@samp{no}.[m
[31mPreprocessor macros will be defined if necessary to make a larger[m
[31m@code{time_t} available. (For example, on some systems the macro[m
[31m@code{_TIME_BITS} will be defined.) Some[m[32menabling[m
[32minstead[m of [31mthese macros only work if[m
[31mthey are defined before the first system header is included; therefore,[m
[31mwhen using this macro in concert with @code{AC_CONFIG_HEADERS}, make[m
[31msure that @file{config.h} is included before any system headers.[m
[31mSupport[m[32mdisabling year-2038 support. Year-2038 support[m for
[31mtimestamps after 2038 can be disabled by configuring with[m
[31mthe @option{--disable-year2038} option. Note that this has no effect on[m
[31msystems where @code{time_t} is 64 bits or larger by default.[m
[31mIf this option is @emph{not} given,[m[32mapplications[m and [31m@command{configure} fails to[m
[31mfind a way to enable a large @code{time_t}, but inspection of the[m
[31msystem suggests that this feature is available @emph{somehow}, it will[m
[31merror out.[m
[31mRegardless of whether you use this macro, portable programs[m[32mlibraries[m should [31mnot[m
[31massume that @code{time_t} fits into @code{long int}. For example, it is[m
[31mnot correct to print an arbitrary @code{time_t} value @code{X} with[m
[31m@code{printf ("%ld", (long int) X)}.[m
[31m@strong{Caution:} If you are developing a shared library, and[m
[31m@code{time_t} appears anywhere in your library's public interface, use[m
[31mof this macro may break binary compatibility with older executables.[m[32mbe configured compatibly.[m
[32m@xref{AC_SYS_LARGEFILE}.[m
@end defmac[m
@defmac AC_SYS_YEAR2038_REQUIRED[m
@acindex{SYS_YEAR2038_REQUIRED}[m
This macro has the same effect as @code{AC_SYS_YEAR2038},[m
but also declares that the program being configured[m
[31m@emph{requires}[m[32mrequires[m support for timestamps after mid-January of 2038.
If a large @code{time_t} is unavailable,[m
@command{configure} will [31m@emph{unconditionally}[m[32munconditionally[m error [31mout[m
[31m(unlike the behavior of @code{AC_SYS_YEAR2038}).[m[32mout.[m
The @option{--disable-year2038} option will not be available.[m
[31m@strong{Caution:} If you are developing a shared library,[m[32mYear-2038 support for applications[m and [31m@code{time_t} appears anywhere in your library's public interface, use[m
[31mof this macro may break binary compatibility with older executables.[m[32mlibraries should be configured[m
[32mcompatibly. @xref{AC_SYS_YEAR2038}.[m
@end defmac[m
@node C and Posix Variants[m