Skip to content

Commit

Permalink
Improve year-2038 documentation
Browse files Browse the repository at this point in the history 
* 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.
  • Loading branch information
@eggert
eggert committed Feb 2, 2023
1 parent 9d26374 commit a7e05c0
Show file tree
Hide file tree
Showing 2 changed files with 113 additions and 109 deletions.
57 changes: 27 additions & 30 deletions NEWS
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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__.
Expand Down
165 changes: 86 additions & 79 deletions doc/autoconf.texi
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down

0 comments on commit a7e05c0

Please sign in to comment.