Re: time64 functions for glibc

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 433 bytes --]

On 5/31/21 12:03 PM, Adhemerval Zanella wrote:

>> Proposed patch attached, relative to the azanella/y2038 branch.
> 
> Thanks, the patch looks reasonable and I will add merge on the
> patch that enable the y2038 symbols.

That documentation patch didn't make it into the master branch when the 
corresponding y2038 symbols did. OK to install that doc patch now? I've 
attached it to this email (this is relative to current master).

[-- Attachment #2: 0001-doc-_TIME_BITS-defaults-may-change.patch --]
[-- Type: text/x-patch, Size: 5397 bytes --]

From 9784d7dce26553f40ec49648c337d6c95e95a8af Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Tue, 22 Jun 2021 14:36:25 -0700
Subject: [PATCH] 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.
---
 NEWS                 |  2 +-
 manual/creature.texi | 57 ++++++++++++++++++++++----------------------
 2 files changed, 29 insertions(+), 30 deletions(-)

diff --git a/NEWS b/NEWS
index 72115073fb..cedc998a22 100644
--- a/NEWS
+++ b/NEWS
@@ -31,7 +31,7 @@ Major new features:
   __STDC_WANT_IEC_60559_BFP_EXT__, as specified in TS 18661-1, is
   defined, and when _GNU_SOURCE is defined.
 
-* 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
-- 
2.30.2