From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 1211) id E1351386FC1B; Wed, 23 Jun 2021 16:05:04 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org E1351386FC1B Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: Paul Eggert To: glibc-cvs@sourceware.org Subject: [glibc] doc: _TIME_BITS defaults may change X-Act-Checkin: glibc X-Git-Author: Paul Eggert X-Git-Refname: refs/heads/master X-Git-Oldrev: 451659ccf13c513611841a69327193facbfdd977 X-Git-Newrev: 03caacbc7f3004ad21fc00bf883f00421a211130 Message-Id: <20210623160504.E1351386FC1B@sourceware.org> Date: Wed, 23 Jun 2021 16:05:04 +0000 (GMT) X-BeenThere: glibc-cvs@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Glibc-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 23 Jun 2021 16:05:05 -0000 https://sourceware.org/git/gitweb.cgi?p=glibc.git;h=03caacbc7f3004ad21fc00bf883f00421a211130 commit 03caacbc7f3004ad21fc00bf883f00421a211130 Author: Paul Eggert 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