[glibc] doc: _TIME_BITS defaults may change

[Paul Eggert <eggert@sourceware.org>]

https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=03caacbc7f3004ad21fc00bf883f00421a211130

commit 03caacbc7f3004ad21fc00bf883f00421a211130
Author: Paul Eggert <eggert@cs.ucla.edu>
Date:   Wed Jun 23 08:57:35 2021 -0700

    doc: _TIME_BITS defaults may change
    
    * NEWS: Don't imply the default will always be 32-bit.
    * manual/creature.texi (Feature Test Macros):
    Say that _TIME_BITS and _FILE_OFFSET_BITS defaults
    may change in future releases.

Diff:
---
 NEWS                 |  2 +-
 manual/creature.texi | 57 ++++++++++++++++++++++++++--------------------------
 2 files changed, 29 insertions(+), 30 deletions(-)

diff --git a/NEWS b/NEWS
index cadc40262f..d64be288da 100644
--- a/NEWS
+++ b/NEWS
@@ -34,7 +34,7 @@ Major new features:
 * On powerpc64*, glibc can now be compiled without scv support using the
   --disable-scv configure option.
 
-* Add support for 64-bit time_t for ABIs with defaults to 32-bit time_t.
+* Add support for 64-bit time_t for ABIs with defaults currently unchanged.
   This is enabled with the _TIME_BITS preprocessor set to 64 and only
   supported when LFS (_FILE_OFFSET_BITS=64) is also enabled.  It is only
   enabled for Linux and the full support requires a minimum version of 5.1.
diff --git a/manual/creature.texi b/manual/creature.texi
index 9fa658e9a7..d3c4fa4702 100644
--- a/manual/creature.texi
+++ b/manual/creature.texi
@@ -146,8 +146,8 @@ bit} interface available as an additional interface,
 @code{_FILE_OFFSET_BITS} allows the @w{64 bit} interface to
 replace the old interface.
 
-If @code{_FILE_OFFSET_BITS} is undefined, or if it is defined to the
-value @code{32}, nothing changes.  The @w{32 bit} interface is used and
+If @code{_FILE_OFFSET_BITS} is defined to the
+value @code{32}, the @w{32 bit} interface is used and
 types like @code{off_t} have a size of @w{32 bits} on @w{32 bit}
 systems.
 
@@ -157,6 +157,11 @@ under different names (as they are with @code{_LARGEFILE64_SOURCE}).
 Instead the old function names now reference the new functions, e.g., a
 call to @code{fseeko} now indeed calls @code{fseeko64}.
 
+If the macro is not defined it currently defaults to @code{32}, but
+this default is planned to change due to a need to update
+@code{time_t} for Y2038 safety, and applications should not rely on
+the default.
+
 This macro should only be selected if the system provides mechanisms for
 handling large files.  On @w{64 bit} systems this macro has no effect
 since the @code{*64} functions are identical to the normal functions.
@@ -166,47 +171,41 @@ This macro was introduced as part of the Large File Support extension
 @end defvr
 
 @defvr Macro _TIME_BITS
-This macro determines the bit size of @code{time_t} (and therefore the
-bit size of all @code{time_t} derived types and the prototypes of all
-related functions).  If @code{_TIME_BITS} is undefined, the bit size of
-@code{time_t} is architecture dependent.
+This macro determines the bit size of @code{time_t}, and therefore the
+bit size of all @code{time_t}-derived types and the prototypes of all
+related functions.
 
-Possible values of @code{_TIME_BITS}:
 @enumerate
-@item
-@code{_TIME_BITS=64} and port from the outset uses 64-bit
-@code{time_t} and word size equals to @w{64 bits} (e.g. x86_64) - no
-action
 
 @item
-@code{_TIME_BITS=32} and port from the outset uses 32-bit
-@code{time_t} and word size equals to @w{64 bits} (e.g. ARM) - no
-action
+If @code{_TIME_BITS} is undefined, the bit size of @code{time_t} is
+architecture dependent.  Currently it defaults to 64 bits on most
+architectures.  Although it defaults to 32 bits on some traditional
+architectures (i686, ARM), this is planned to change and applications
+should not rely on this.
 
 @item
-@code{_TIME_BITS=64} and port from the outset uses 64-bit
-@code{time_t} and word size equals to @w{32 bits} (e.g. ARC, RV32)
-- no action
+If @code{_TIME_BITS} is defined to be 64, @code{time_t} is defined
+to be a 64-bit integer.  On platforms where @code{time_t} was
+traditionally 32 bits, calls to proper syscalls depend on the
+Linux kernel version on which the system is running. For Linux kernel
+version above @b{5.1} syscalls supporting 64-bit time are used. Otherwise,
+a fallback code is used with legacy (i.e. 32-bit) syscalls.
 
 @item
-@code{_TIME_BITS=64} and port from the outset uses 32-bit
-@code{time_t} and word size equals to @w{32 bits} (e.g. ARM)
-- the @code{time_t} is modified to be able to hold 64-bit time.
+If @code{_TIME_BITS} is defined to be 32, @code{time_t} is defined to
+be a 32-bit integer where that is supported.  This is not recommended,
+as 32-bit @code{time_t} stops working in the year 2038.
 
 @item
-For any other use case the compile-time error is emitted.
+For any other use case a compile-time error is emitted.
 @end enumerate
 
-The @code{_TIME_BITS} can be only used when @code{_FILE_OFFSET_BITS=64}
-is also defined.
-
-For the point @b{4} above, calls to proper syscalls depend on the
-Linux kernel version on which the system is running. For Linux kernel
-version above @b{5.1} syscalls supporting 64-bit time are used. Otherwise,
-a fallback code is used with legacy (i.e. 32-bit) syscalls.
+@code{_TIME_BITS=64} can be defined only when
+@code{_FILE_OFFSET_BITS=64} is also defined.
 
 By using this macro certain ports gain support for 64-bit time and as
-a result become immune to Y2038 problem.
+a result become immune to the Y2038 problem.
 @end defvr
 
 @defvr Macro _ISOC99_SOURCE