[PATCH] Y2038: add function __localtime64

[PATCH] Y2038: add function __localtime64

[Albert ARIBAUD (3ADEV)]

Tested with 'make check' on x86_64-linux-gnu and i686-linux.gnu.

	* include/time.h
	(__localtime64): Add.
        * manual/maint.texi: Document Y2038 symbol handling.
	* time/localtime.c
	(__localtime64): Add.
	[__TIMERSIZE != 64] (__localtime): Turn into a wrapper.
---
 include/time.h    |   9 +++-
 manual/maint.texi | 122 ++++++++++++++++++++++++++++++++++++++++++++++
 time/localtime.c  |  18 +++++--
 3 files changed, 145 insertions(+), 4 deletions(-)

diff --git a/include/time.h b/include/time.h
index 37964f7b76..251a2b0329 100644
--- a/include/time.h
+++ b/include/time.h
@@ -56,9 +56,16 @@ extern time_t __mktime_internal (struct tm *__tp,
 				 struct tm *(*__func) (const time_t *,
 						       struct tm *),
 				 long int *__offset) attribute_hidden;
+
+#if __TIMESIZE == 64
+# define __localtime64 localtime
+#else
+extern struct tm *__localtime64 (const __time64_t *__timer);
+libc_hidden_proto (__localtime64)
+#endif
+
 extern struct tm *__localtime_r (const time_t *__timer,
 				 struct tm *__tp) attribute_hidden;
-
 extern struct tm *__gmtime_r (const time_t *__restrict __timer,
 			      struct tm *__restrict __tp);
 libc_hidden_proto (__gmtime_r)
diff --git a/manual/maint.texi b/manual/maint.texi
index fce06bfa88..c707544095 100644
--- a/manual/maint.texi
+++ b/manual/maint.texi
@@ -5,6 +5,7 @@
 @menu
 * Source Layout::         How to add new functions or header files
                              to the GNU C Library.
+* Symbol handling::       How to handle symbols in the GNU C Library.
 * Porting::               How to port the GNU C Library to
                              a new machine or operating system.
 @end menu
@@ -183,6 +184,127 @@ header file in the machine-specific directory, e.g.,
 @file{sysdeps/powerpc/sys/platform/ppc.h}.
 
 
+@node Symbol handling
+@appendixsec Symbol handling in the GNU C Library
+
+@menu
+* 64-bit time symbol handling :: How to handle 64-bit time related
+                                    symbols in the GNU C Library.
+@end menu
+
+@node 64-bit time symbol handling
+@appendixsubsec 64-bit time symbol handling in the GNU C Library
+
+Some of the architectures supported by @theglibc{} already use 64-bit
+time (@code{__TIMESIZE == 64}), while other architectures use 32-bit time
+(@code{__TIMESIZE != 64}) and therefore cannot handle dates beyond
+2038-01-19 03:14:07 (aka 'Y2038').
+
+In order to make @theglibc{} Y2038-proof, 64-bit time support must be
+added to those 32-bit-time-only architectures. When adding new code
+for Y2038 support, some principles must be followed:
+
+@itemize @bullet
+
+@item
+Y2038 support code added to @theglibc{} must not modify or remove
+existing symbols on 32-bit time architectures. This ensures that
+existing user object code will remain able to link against the newer
+Y2038-proof @glibcadj{}.
+
+@item
+Y2038 support code added to @theglibc{} must not add any new symbol
+when building on 64-bit time architectures when existing symbols are
+aleady Y2038-proof.
+
+@item
+In public headers, @theglibc{} supports either 64- or 32-bit time with
+a single set of names. On 64-bit time architectures, only 64-bit time
+is supporte (@code{time_t} is 64-bit, @code{time()} returns a 64-bit time
+etc); on 32-bit architectures, 32-bit time is supported (@code{time_t}
+is 32-bit, @code{time()} returns a 32-bit time etc) unless
+@code{_TIME_BITS} is defined equal to @code{64} before including
+headers from @theglibc{}, in which case 64-bit time is supported.
+
+@end itemize
+
+In order to simplify Y2038 support, all Y2038 proofing follows the
+same mechanism: for each non-Y2038-proof 32-bit-time function, a
+Y2038-proof 64-bit-time version is created, and the 32-bit-time function
+is rewritten as a wrapper around the 64-bit-time function.
+
+Here is an example with @code{localtime}:
+
+Function @code{localtime} is declared in @file{time/time.h} as
+@smallexample
+extern struct tm *localtime (const time_t *__timer) __THROW;
+libc_hidden_proto (localtime)
+@end smallexample
+
+On 64-bit time architectures, we declare @code{__localtime64} to be a
+macro which evaluates to @code{localtime}, so that
+@smallexample
+extern struct tm *__localtime64 (const __time64_t *__timer) __THROW;
+@end smallexample
+evaluates to
+@smallexample
+extern struct tm *localtime (const time_t *__timer) __THROW;
+@end smallexample
+
+(for 64-bit-time architectures, @code{__time64_t} is declared as a
+macro which evaluates to @code{time_t})
+
+On 32-bit time architectures, we declare @code{__localtime64} similar
+to @code{localtime} except it uses Y2038-proof types:
+@smallexample
+#if __TIMESIZE == 64
+# define __localtime64 localtime
+#else
+extern struct tm *__localtime64 (const __time64_t *__timer) __THROW;
+libc_hidden_proto (__localtime64)
+#endif
+@end smallexample
+
+(type @code{time_t} is replaced with @code{__time64_t} because
+@code{time_t} is not Y2038-proof, whereas @code{struct tm} is not
+replaced because it is already Y2038-proof.)
+
+The implementation of @code{localtime} is replaced as follows:
+
+@smallexample
+struct tm *
+__localtime64 (const __time64_t *t)
+(
+  return __tz_convert (*t, 1, &_tmbuf);
+)
+libc_hidden_def (__localtime64)
+
+/* Provide a 32-bit variant if needed */
+
+#if __TIMESIZE != 64
+
+struct tm *
+localtime (const time_t *t)
+(
+  __time64_t t64 = *t;
+  return __localtime64 (&t64);
+)
+libc_hidden_def (localtime)
+
+#endif
+@end smallexample
+
+For 64-bit-time architectures, @code{__localtime64} is a macro which
+evaluates to @code{localtime} and @code{__time64} is a macro which
+evaluates to @code{time_t}, so the first definition above amounts to
+the original definition of @code{localtime}; and since @code{__TIMESIZE}
+equals 64, the second definition is removed by the preprocessor.
+
+For 32-bit architectures, the first definition creates the new function
+@code{__localtime64} which uses Y2038-proof types, and since
+@code{__TIMESIZE} is different from 64, the second definition provides
+@code{localtime} as a wrapper around @code{__localtime64}.
+
 @node Porting
 @appendixsec Porting @theglibc{}
 
diff --git a/time/localtime.c b/time/localtime.c
index 92dbfe0f8c..50e0be2272 100644
--- a/time/localtime.c
+++ b/time/localtime.c
@@ -21,7 +21,6 @@
 /* The C Standard says that localtime and gmtime return the same pointer.  */
 struct tm _tmbuf;
 
-
 /* Return the `struct tm' representation of *T in local time,
    using *TP to store the result.  */
 struct tm *
@@ -31,11 +30,24 @@ __localtime_r (const time_t *t, struct tm *tp)
 }
 weak_alias (__localtime_r, localtime_r)
 
-
 /* Return the `struct tm' representation of *T in local time.  */
 struct tm *
-localtime (const time_t *t)
+__localtime64 (const __time64_t *t)
 {
   return __tz_convert (*t, 1, &_tmbuf);
 }
+libc_hidden_def (__localtime64)
+
+/* Provide a 32-bit variant if needed */
+
+#if __TIMESIZE != 64
+
+struct tm *
+localtime (const time_t *t)
+{
+  __time64_t t64 = *t;
+  return __localtime64 (&t64);
+}
 libc_hidden_def (localtime)
+
+#endif
-- 
2.17.1

Re: [PATCH] Y2038: add function __localtime64

[Andreas Schwab]

On Dez 12 2018, "Albert ARIBAUD (3ADEV)" <albert.aribaud@3adev.fr> wrote:

> +Some of the architectures supported by @theglibc{} already use 64-bit
> +time (@code{__TIMESIZE == 64}), while other architectures use 32-bit time
> +(@code{__TIMESIZE != 64}) and therefore cannot handle dates beyond
> +2038-01-19 03:14:07 (aka 'Y2038').

This should be `Y2038' or @dfn{Y2038}.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

[PATCH v2] Y2038: add function __localtime64

[Albert ARIBAUD (3ADEV)]

Tested with 'make check' on x86_64-linux-gnu and i686-linux.gnu.

	* include/time.h
	(__localtime64): Add.
        * manual/maint.texi: Document Y2038 symbol handling.
	* time/localtime.c
	(__localtime64): Add.
	[__TIMERSIZE != 64] (__localtime): Turn into a wrapper.
---
v2: fix 'Y2038' => @dfn{Y2038} in manual/maint.texi

 include/time.h    |   9 +++-
 manual/maint.texi | 122 ++++++++++++++++++++++++++++++++++++++++++++++
 time/localtime.c  |  18 +++++--
 3 files changed, 145 insertions(+), 4 deletions(-)

diff --git a/include/time.h b/include/time.h
index 37964f7b76..251a2b0329 100644
--- a/include/time.h
+++ b/include/time.h
@@ -56,9 +56,16 @@ extern time_t __mktime_internal (struct tm *__tp,
 				 struct tm *(*__func) (const time_t *,
 						       struct tm *),
 				 long int *__offset) attribute_hidden;
+
+#if __TIMESIZE == 64
+# define __localtime64 localtime
+#else
+extern struct tm *__localtime64 (const __time64_t *__timer);
+libc_hidden_proto (__localtime64)
+#endif
+
 extern struct tm *__localtime_r (const time_t *__timer,
 				 struct tm *__tp) attribute_hidden;
-
 extern struct tm *__gmtime_r (const time_t *__restrict __timer,
 			      struct tm *__restrict __tp);
 libc_hidden_proto (__gmtime_r)
diff --git a/manual/maint.texi b/manual/maint.texi
index fce06bfa88..49be3621a0 100644
--- a/manual/maint.texi
+++ b/manual/maint.texi
@@ -5,6 +5,7 @@
 @menu
 * Source Layout::         How to add new functions or header files
                              to the GNU C Library.
+* Symbol handling::       How to handle symbols in the GNU C Library.
 * Porting::               How to port the GNU C Library to
                              a new machine or operating system.
 @end menu
@@ -183,6 +184,127 @@ header file in the machine-specific directory, e.g.,
 @file{sysdeps/powerpc/sys/platform/ppc.h}.
 
 
+@node Symbol handling
+@appendixsec Symbol handling in the GNU C Library
+
+@menu
+* 64-bit time symbol handling :: How to handle 64-bit time related
+                                    symbols in the GNU C Library.
+@end menu
+
+@node 64-bit time symbol handling
+@appendixsubsec 64-bit time symbol handling in the GNU C Library
+
+Some of the architectures supported by @theglibc{} already use 64-bit
+time (@code{__TIMESIZE == 64}), while other architectures use 32-bit time
+(@code{__TIMESIZE != 64}) and therefore cannot handle dates beyond
+2038-01-19 03:14:07 (aka @dfn{Y2038}).
+
+In order to make @theglibc{} Y2038-proof, 64-bit time support must be
+added to those 32-bit-time-only architectures. When adding new code
+for Y2038 support, some principles must be followed:
+
+@itemize @bullet
+
+@item
+Y2038 support code added to @theglibc{} must not modify or remove
+existing symbols on 32-bit time architectures. This ensures that
+existing user object code will remain able to link against the newer
+Y2038-proof @glibcadj{}.
+
+@item
+Y2038 support code added to @theglibc{} must not add any new symbol
+when building on 64-bit time architectures when existing symbols are
+aleady Y2038-proof.
+
+@item
+In public headers, @theglibc{} supports either 64- or 32-bit time with
+a single set of names. On 64-bit time architectures, only 64-bit time
+is supporte (@code{time_t} is 64-bit, @code{time()} returns a 64-bit time
+etc); on 32-bit architectures, 32-bit time is supported (@code{time_t}
+is 32-bit, @code{time()} returns a 32-bit time etc) unless
+@code{_TIME_BITS} is defined equal to @code{64} before including
+headers from @theglibc{}, in which case 64-bit time is supported.
+
+@end itemize
+
+In order to simplify Y2038 support, all Y2038 proofing follows the
+same mechanism: for each non-Y2038-proof 32-bit-time function, a
+Y2038-proof 64-bit-time version is created, and the 32-bit-time function
+is rewritten as a wrapper around the 64-bit-time function.
+
+Here is an example with @code{localtime}:
+
+Function @code{localtime} is declared in @file{time/time.h} as
+@smallexample
+extern struct tm *localtime (const time_t *__timer) __THROW;
+libc_hidden_proto (localtime)
+@end smallexample
+
+On 64-bit time architectures, we declare @code{__localtime64} to be a
+macro which evaluates to @code{localtime}, so that
+@smallexample
+extern struct tm *__localtime64 (const __time64_t *__timer) __THROW;
+@end smallexample
+evaluates to
+@smallexample
+extern struct tm *localtime (const time_t *__timer) __THROW;
+@end smallexample
+
+(for 64-bit-time architectures, @code{__time64_t} is declared as a
+macro which evaluates to @code{time_t})
+
+On 32-bit time architectures, we declare @code{__localtime64} similar
+to @code{localtime} except it uses Y2038-proof types:
+@smallexample
+#if __TIMESIZE == 64
+# define __localtime64 localtime
+#else
+extern struct tm *__localtime64 (const __time64_t *__timer) __THROW;
+libc_hidden_proto (__localtime64)
+#endif
+@end smallexample
+
+(type @code{time_t} is replaced with @code{__time64_t} because
+@code{time_t} is not Y2038-proof, whereas @code{struct tm} is not
+replaced because it is already Y2038-proof.)
+
+The implementation of @code{localtime} is replaced as follows:
+
+@smallexample
+struct tm *
+__localtime64 (const __time64_t *t)
+(
+  return __tz_convert (*t, 1, &_tmbuf);
+)
+libc_hidden_def (__localtime64)
+
+/* Provide a 32-bit variant if needed */
+
+#if __TIMESIZE != 64
+
+struct tm *
+localtime (const time_t *t)
+(
+  __time64_t t64 = *t;
+  return __localtime64 (&t64);
+)
+libc_hidden_def (localtime)
+
+#endif
+@end smallexample
+
+For 64-bit-time architectures, @code{__localtime64} is a macro which
+evaluates to @code{localtime} and @code{__time64} is a macro which
+evaluates to @code{time_t}, so the first definition above amounts to
+the original definition of @code{localtime}; and since @code{__TIMESIZE}
+equals 64, the second definition is removed by the preprocessor.
+
+For 32-bit architectures, the first definition creates the new function
+@code{__localtime64} which uses Y2038-proof types, and since
+@code{__TIMESIZE} is different from 64, the second definition provides
+@code{localtime} as a wrapper around @code{__localtime64}.
+
 @node Porting
 @appendixsec Porting @theglibc{}
 
diff --git a/time/localtime.c b/time/localtime.c
index 92dbfe0f8c..50e0be2272 100644
--- a/time/localtime.c
+++ b/time/localtime.c
@@ -21,7 +21,6 @@
 /* The C Standard says that localtime and gmtime return the same pointer.  */
 struct tm _tmbuf;
 
-
 /* Return the `struct tm' representation of *T in local time,
    using *TP to store the result.  */
 struct tm *
@@ -31,11 +30,24 @@ __localtime_r (const time_t *t, struct tm *tp)
 }
 weak_alias (__localtime_r, localtime_r)
 
-
 /* Return the `struct tm' representation of *T in local time.  */
 struct tm *
-localtime (const time_t *t)
+__localtime64 (const __time64_t *t)
 {
   return __tz_convert (*t, 1, &_tmbuf);
 }
+libc_hidden_def (__localtime64)
+
+/* Provide a 32-bit variant if needed */
+
+#if __TIMESIZE != 64
+
+struct tm *
+localtime (const time_t *t)
+{
+  __time64_t t64 = *t;
+  return __localtime64 (&t64);
+}
 libc_hidden_def (localtime)
+
+#endif
-- 
2.17.1

Re: [PATCH v2] Y2038: add function __localtime64

[Joseph Myers]

On Wed, 12 Dec 2018, Albert ARIBAUD (3ADEV) wrote:

>  extern struct tm *__localtime_r (const time_t *__timer,
>  				 struct tm *__tp) attribute_hidden;
> -

I don't think this blank line removal should be included in this patch.

> +In order to make @theglibc{} Y2038-proof, 64-bit time support must be
> +added to those 32-bit-time-only architectures. When adding new code

Two spaces after '.' in Texinfo source, throughout.

> +@item
> +Y2038 support code added to @theglibc{} must not modify or remove
> +existing symbols on 32-bit time architectures. This ensures that
> +existing user object code will remain able to link against the newer
> +Y2038-proof @glibcadj{}.

@glibcadj{} is incorrect here, this is not an adjective use.

> +aleady Y2038-proof.

"already"

> +is supporte (@code{time_t} is 64-bit, @code{time()} returns a 64-bit time

"supported"

Do not use () after a function name to indicate it's a function (see the 
GNU Coding Standards).

> +/* Provide a 32-bit variant if needed */

Comments, both in code and in the manual, should follow GNU standards, so 
end with ".  " (full stop, two spaces).

>  /* The C Standard says that localtime and gmtime return the same pointer.  */
>  struct tm _tmbuf;
>  
> -
>  /* Return the `struct tm' representation of *T in local time,
>     using *TP to store the result.  */
>  struct tm *
> @@ -31,11 +30,24 @@ __localtime_r (const time_t *t, struct tm *tp)
>  }
>  weak_alias (__localtime_r, localtime_r)
>  
> -
>  /* Return the `struct tm' representation of *T in local time.  */

Again, I think the patch should avoid stray removals of blank lines.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [PATCH v2] Y2038: add function __localtime64

[Albert ARIBAUD]

Hi Joseph,

On Wed, 12 Dec 2018 17:09:22 +0000, Joseph Myers
<joseph@codesourcery.com> wrote :

> > +@item
> > +Y2038 support code added to @theglibc{} must not modify or remove
> > +existing symbols on 32-bit time architectures. This ensures that
> > +existing user object code will remain able to link against the newer
> > +Y2038-proof @glibcadj{}.  
> 
> @glibcadj{} is incorrect here, this is not an adjective use.

I would need a noun form here, and manual/macros.texi does not provide
one. Should I add a @macro definition for glibcnoun there and use it in
the paragraph above?

Cordialement,
Albert ARIBAUD
3ADEV

Re: [PATCH v2] Y2038: add function __localtime64

[Joseph Myers]

On Wed, 12 Dec 2018, Albert ARIBAUD wrote:

> Hi Joseph,
> 
> On Wed, 12 Dec 2018 17:09:22 +0000, Joseph Myers
> <joseph@codesourcery.com> wrote :
> 
> > > +@item
> > > +Y2038 support code added to @theglibc{} must not modify or remove
> > > +existing symbols on 32-bit time architectures. This ensures that
> > > +existing user object code will remain able to link against the newer
> > > +Y2038-proof @glibcadj{}.  
> > 
> > @glibcadj{} is incorrect here, this is not an adjective use.
> 
> I would need a noun form here, and manual/macros.texi does not provide
> one. Should I add a @macro definition for glibcnoun there and use it in
> the paragraph above?

I think this paragraph would better be rewritten anyway, so avoiding the 
need for a new macro.

Rather than writing the text as being about a change to glibc, and so 
talking about "existing" symbols or object code and "newer" glibc, it 
might better be written in terms of there being two kinds of glibc 
configurations: those that only support 64-bit time_t, and those that 
support both 32-bit and 64-bit time_t.  (With a note, to be removed later, 
that the latter are a work in progress, so that external interfaces for 
64-bit time_t are not yet enabled on such configurations.)

Then you can explain that for the configurations with only 64-bit time_t, 
there are no variant symbol names or function definitions for different 
time_t choices (with the consequent internal #defines, etc.) - whereas on 
configurations with both 32-bit and 64-bit time_t, time-related functions 
generally have two definitions, one being a wrapper round the other (and 
the symbol names not containing a "64" are the ones for 32-bit time_t).

This avoids needing to apply descriptions like "newer" or "Y2038-proof" to 
"GNU C Library" (although such descriptions might still be relevant to 
apply to functions).

With this structure, the fact that configurations with both 32-bit and 
64-bit time_t are ones that used to have only 32-bit time_t is essentially 
a historical note that explains why a particular design is used.  At the 
level of individual symbols, it may not even be true that one is the old 
symbol and one is the new one; it's entirely plausible that new 
time-related functions may be added after the 64-bit time_t support for 
such platforms is complete (but before 32-bit time_t support is completely 
obsoleted and the relevant symbols made into compat symbols), and so would 
get both versions of the symbol added to glibc at the same time.

-- 
Joseph S. Myers
joseph@codesourcery.com

[PATCH v3] Y2038: add function __localtime64

[Albert ARIBAUD (3ADEV)]

Tested with 'make check' on x86_64-linux-gnu and i686-linux.gnu.

	* include/time.h
	(__localtime64): Add.
        * manual/maint.texi: Document Y2038 symbol handling.
	* time/localtime.c
	(__localtime64): Add.
	[__TIMERSIZE != 64] (__localtime): Turn into a wrapper.
---
v3: Rewrite manual section as suggested by Joseph Myers
    Revert blank line removals
    Ensure periods are followed with two spaces
    Fix typos
    Remove () after function names
v2: Fix 'Y2038' => @dfn{Y2038} in manual/maint.texi

 include/time.h    |   8 ++++
 manual/maint.texi | 120 ++++++++++++++++++++++++++++++++++++++++++++++
 time/localtime.c  |  16 ++++++-
 3 files changed, 143 insertions(+), 1 deletion(-)

diff --git a/include/time.h b/include/time.h
index 37964f7b76..3bc303a36e 100644
--- a/include/time.h
+++ b/include/time.h
@@ -56,6 +56,14 @@ extern time_t __mktime_internal (struct tm *__tp,
 				 struct tm *(*__func) (const time_t *,
 						       struct tm *),
 				 long int *__offset) attribute_hidden;
+
+#if __TIMESIZE == 64
+# define __localtime64 localtime
+#else
+extern struct tm *__localtime64 (const __time64_t *__timer);
+libc_hidden_proto (__localtime64)
+#endif
+
 extern struct tm *__localtime_r (const time_t *__timer,
 				 struct tm *__tp) attribute_hidden;
 
diff --git a/manual/maint.texi b/manual/maint.texi
index fce06bfa88..e6a396c078 100644
--- a/manual/maint.texi
+++ b/manual/maint.texi
@@ -5,6 +5,7 @@
 @menu
 * Source Layout::         How to add new functions or header files
                              to the GNU C Library.
+* Symbol handling::       How to handle symbols in the GNU C Library.
 * Porting::               How to port the GNU C Library to
                              a new machine or operating system.
 @end menu
@@ -183,6 +184,125 @@ header file in the machine-specific directory, e.g.,
 @file{sysdeps/powerpc/sys/platform/ppc.h}.
 
 
+@node Symbol handling
+@appendixsec Symbol handling in the GNU C Library
+
+@menu
+* 64-bit time symbol handling :: How to handle 64-bit time related
+                                    symbols in the GNU C Library.
+@end menu
+
+@node 64-bit time symbol handling
+@appendixsubsec 64-bit time symbol handling in the GNU C Library
+
+With respect to time handling, @theglibc{} configurations fall in two
+classes depending on the value of @code{__TIMESIZE}:
+
+@table @code
+
+@item @code{__TIMESIZE == 32}
+
+These @dfn{dual-time} configurations have both 32-bit and 64-bit time 
+support.  32-bit time support provides type @code{time_t} and cannot 
+handle dates beyond @dfn{Y2038}.  64-bit time support provides type 
+@code{__time64_t} and can handle dates beyond @dfn{Y2038}.
+
+In these configurations, time-related types have two declarations,
+a 64-bit one, and a 32-bit one; and time-related functions generally
+have two definitions: a 64-bit one, and a 32-bit one which is a wrapper
+around the former.  Therefore, for every @code{time_t}-related symbol,
+there is a corresponding @code{__time64_t}-related symbol, the name of
+which is usually the 32-bit symbol's name with @code{__} (a double
+underscore) prepended and @code{64} appended.  For instance, the
+64-bit-time counterpart of @code{clock_gettime} is
+@code{__clock_gettime64}.
+
+@item @code{__TIMESIZE == 64}
+
+These @dfn{single-time} configurations only have a 64-bit @code{time_t} 
+and related functions, which can handle dates beyond 2038-01-19 
+03:14:07 (aka @dfn{Y2038}).
+
+In these configurations, time-related types only have a 64-bit
+declaration; and time-related functions only have one 64-bit definition.
+However, for every @code{time_t}-related symbol, there is a
+corresponding @code{__time64_t}-related macro, the name of which is
+derived as in the dual-time configuration case, and which expands to
+the symbol's name.  For instance, the macro @code{__clock_gettime64}
+expands to @code{clock_gettime}.
+
+@end table
+
+@c The following paragraph should be removed once external interfaces
+@c get support for both time sizes.
+
+Note: at this point, 64-bit time support in dual-time configurations is
+work-in-progress, so for these configurations, the public API only makes
+the 32-bit time support available.  In a later change, the public API
+will allow user code to choose the time size for a given compilation
+unit.
+
+64-bit variants of time-related types or functions are defined for all
+configurations and use 64-bit-time symbol names (for dual-time
+configurations) or macros (for single-time configurations).
+
+32-bit variants of time-related types or functions are defined only for
+dual-time configurations.
+
+Here is an example with @code{localtime}:
+
+Function @code{localtime} is declared in @file{time/time.h} as
+@smallexample
+extern struct tm *localtime (const time_t *__timer) __THROW;
+libc_hidden_proto (localtime)
+@end smallexample
+
+For single-time configurations, @code{__localtime64} is a macro which
+evaluates to @code{localtime}; for dual-time configurations,
+@code{__localtime64} is a function similar to @code{localtime} except
+it uses Y2038-proof types:
+@smallexample
+#if __TIMESIZE == 64
+# define __localtime64 localtime
+#else
+extern struct tm *__localtime64 (const __time64_t *__timer) __THROW;
+libc_hidden_proto (__localtime64)
+#endif
+@end smallexample
+
+(note: type @code{time_t} is replaced with @code{__time64_t} because
+@code{time_t} is not Y2038-proof, but @code{struct tm} is not
+replaced because it is already Y2038-proof.)
+
+The 64-bit-time implementation of @code{localtime} is written as follows
+and is compiled for both dual-time and single-time configuration classes.
+
+@smallexample
+struct tm *
+__localtime64 (const __time64_t *t)
+@lbracechar{}
+  return __tz_convert (*t, 1, &_tmbuf);
+@rbracechar{}
+libc_hidden_def (__localtime64)
+@end smallexample
+
+The 32-bit-time implementation is a wrapper and is only compiled for
+dual-time configurations:
+
+@smallexample
+#if __TIMESIZE != 64
+
+struct tm *
+localtime (const time_t *t)
+@lbracechar{}
+  __time64_t t64 = *t;
+  return __localtime64 (&t64);
+@rbracechar{}
+libc_hidden_def (localtime)
+
+#endif
+@end smallexample
+
 @node Porting
 @appendixsec Porting @theglibc{}
 
diff --git a/time/localtime.c b/time/localtime.c
index 92dbfe0f8c..96879d4ec0 100644
--- a/time/localtime.c
+++ b/time/localtime.c
@@ -34,8 +34,22 @@ weak_alias (__localtime_r, localtime_r)
 
 /* Return the `struct tm' representation of *T in local time.  */
 struct tm *
-localtime (const time_t *t)
+__localtime64 (const __time64_t *t)
 {
   return __tz_convert (*t, 1, &_tmbuf);
 }
+libc_hidden_def (__localtime64)
+
+/* Provide a 32-bit variant if needed.  */
+
+#if __TIMESIZE != 64
+
+struct tm *
+localtime (const time_t *t)
+{
+  __time64_t t64 = *t;
+  return __localtime64 (&t64);
+}
 libc_hidden_def (localtime)
+
+#endif
-- 
2.17.1

Re: [PATCH v3] Y2038: add function __localtime64

[Joseph Myers]

On Wed, 12 Dec 2018, Albert ARIBAUD (3ADEV) wrote:

> +In these configurations, time-related types only have a 64-bit
> +declaration; and time-related functions only have one 64-bit definition.
> +However, for every @code{time_t}-related symbol, there is a
> +corresponding @code{__time64_t}-related macro, the name of which is
> +derived as in the dual-time configuration case, and which expands to
> +the symbol's name.  For instance, the macro @code{__clock_gettime64}
> +expands to @code{clock_gettime}.

I think this should say explicitly that these macros are purely internal 
(visible when glibc is built, but not to users of glibc), and that they 
exist so that a single definition of the 64-bit time functions can be used 
on both kinds of configurations, and so that glibc code can freely call 
the 64-bit functions internally.

-- 
Joseph S. Myers
joseph@codesourcery.com

[PATCH v4] Y2038: add function __localtime64

[Albert ARIBAUD (3ADEV)]

Tested with 'make check' on x86_64-linux-gnu and i686-linux.gnu.

	* include/time.h
	(__localtime64): Add.
        * manual/maint.texi: Document Y2038 symbol handling.
	* time/localtime.c
	(__localtime64): Add.
	[__TIMERSIZE != 64] (__localtime): Turn into a wrapper.
---
v4: Add paragraph about macros to manual section as suggested by
    Joseph Myers
v3: Rewrite manual section as suggested by Joseph Myers
    Revert blank line removals
    Ensure periods are followed with two spaces
    Fix typos
    Remove () after function names
v2: Fix 'Y2038' => @dfn{Y2038} in manual/maint.texi

 include/time.h    |   8 +++
 manual/maint.texi | 125 ++++++++++++++++++++++++++++++++++++++++++++++
 time/localtime.c  |  16 +++++-
 3 files changed, 148 insertions(+), 1 deletion(-)

diff --git a/include/time.h b/include/time.h
index 37964f7b76..3bc303a36e 100644
--- a/include/time.h
+++ b/include/time.h
@@ -56,6 +56,14 @@ extern time_t __mktime_internal (struct tm *__tp,
 				 struct tm *(*__func) (const time_t *,
 						       struct tm *),
 				 long int *__offset) attribute_hidden;
+
+#if __TIMESIZE == 64
+# define __localtime64 localtime
+#else
+extern struct tm *__localtime64 (const __time64_t *__timer);
+libc_hidden_proto (__localtime64)
+#endif
+
 extern struct tm *__localtime_r (const time_t *__timer,
 				 struct tm *__tp) attribute_hidden;
 
diff --git a/manual/maint.texi b/manual/maint.texi
index fce06bfa88..b5f69a1f9d 100644
--- a/manual/maint.texi
+++ b/manual/maint.texi
@@ -5,6 +5,7 @@
 @menu
 * Source Layout::         How to add new functions or header files
                              to the GNU C Library.
+* Symbol handling::       How to handle symbols in the GNU C Library.
 * Porting::               How to port the GNU C Library to
                              a new machine or operating system.
 @end menu
@@ -183,6 +184,130 @@ header file in the machine-specific directory, e.g.,
 @file{sysdeps/powerpc/sys/platform/ppc.h}.
 
 
+@node Symbol handling
+@appendixsec Symbol handling in the GNU C Library
+
+@menu
+* 64-bit time symbol handling :: How to handle 64-bit time related
+                                    symbols in the GNU C Library.
+@end menu
+
+@node 64-bit time symbol handling
+@appendixsubsec 64-bit time symbol handling in the GNU C Library
+
+With respect to time handling, @theglibc{} configurations fall in two
+classes depending on the value of @code{__TIMESIZE}:
+
+@table @code
+
+@item @code{__TIMESIZE == 32}
+
+These @dfn{dual-time} configurations have both 32-bit and 64-bit time 
+support.  32-bit time support provides type @code{time_t} and cannot 
+handle dates beyond @dfn{Y2038}.  64-bit time support provides type 
+@code{__time64_t} and can handle dates beyond @dfn{Y2038}.
+
+In these configurations, time-related types have two declarations,
+a 64-bit one, and a 32-bit one; and time-related functions generally
+have two definitions: a 64-bit one, and a 32-bit one which is a wrapper
+around the former.  Therefore, for every @code{time_t}-related symbol,
+there is a corresponding @code{__time64_t}-related symbol, the name of
+which is usually the 32-bit symbol's name with @code{__} (a double
+underscore) prepended and @code{64} appended.  For instance, the
+64-bit-time counterpart of @code{clock_gettime} is
+@code{__clock_gettime64}.
+
+@item @code{__TIMESIZE == 64}
+
+These @dfn{single-time} configurations only have a 64-bit @code{time_t} 
+and related functions, which can handle dates beyond 2038-01-19 
+03:14:07 (aka @dfn{Y2038}).
+
+In these configurations, time-related types only have a 64-bit
+declaration; and time-related functions only have one 64-bit definition.
+However, for every @code{time_t}-related symbol, there is a
+corresponding @code{__time64_t}-related macro, the name of which is
+derived as in the dual-time configuration case, and which expands to
+the symbol's name.  For instance, the macro @code{__clock_gettime64}
+expands to @code{clock_gettime}.
+
+These macros are purely internal to @theglibc{} and exist only so that
+a single definition of the 64-bit time functions can be used  on both
+single-time and dual-time configurations, and so that glibc code can
+freely call  the 64-bit functions internally in all configurations.
+
+@end table
+
+@c The following paragraph should be removed once external interfaces
+@c get support for both time sizes.
+
+Note: at this point, 64-bit time support in dual-time configurations is
+work-in-progress, so for these configurations, the public API only makes
+the 32-bit time support available.  In a later change, the public API
+will allow user code to choose the time size for a given compilation
+unit.
+
+64-bit variants of time-related types or functions are defined for all
+configurations and use 64-bit-time symbol names (for dual-time
+configurations) or macros (for single-time configurations).
+
+32-bit variants of time-related types or functions are defined only for
+dual-time configurations.
+
+Here is an example with @code{localtime}:
+
+Function @code{localtime} is declared in @file{time/time.h} as
+@smallexample
+extern struct tm *localtime (const time_t *__timer) __THROW;
+libc_hidden_proto (localtime)
+@end smallexample
+
+For single-time configurations, @code{__localtime64} is a macro which
+evaluates to @code{localtime}; for dual-time configurations,
+@code{__localtime64} is a function similar to @code{localtime} except
+it uses Y2038-proof types:
+@smallexample
+#if __TIMESIZE == 64
+# define __localtime64 localtime
+#else
+extern struct tm *__localtime64 (const __time64_t *__timer) __THROW;
+libc_hidden_proto (__localtime64)
+#endif
+@end smallexample
+
+(note: type @code{time_t} is replaced with @code{__time64_t} because
+@code{time_t} is not Y2038-proof, but @code{struct tm} is not
+replaced because it is already Y2038-proof.)
+
+The 64-bit-time implementation of @code{localtime} is written as follows
+and is compiled for both dual-time and single-time configuration classes.
+
+@smallexample
+struct tm *
+__localtime64 (const __time64_t *t)
+@lbracechar{}
+  return __tz_convert (*t, 1, &_tmbuf);
+@rbracechar{}
+libc_hidden_def (__localtime64)
+@end smallexample
+
+The 32-bit-time implementation is a wrapper and is only compiled for
+dual-time configurations:
+
+@smallexample
+#if __TIMESIZE != 64
+
+struct tm *
+localtime (const time_t *t)
+@lbracechar{}
+  __time64_t t64 = *t;
+  return __localtime64 (&t64);
+@rbracechar{}
+libc_hidden_def (localtime)
+
+#endif
+@end smallexample
+
 @node Porting
 @appendixsec Porting @theglibc{}
 
diff --git a/time/localtime.c b/time/localtime.c
index 92dbfe0f8c..96879d4ec0 100644
--- a/time/localtime.c
+++ b/time/localtime.c
@@ -34,8 +34,22 @@ weak_alias (__localtime_r, localtime_r)
 
 /* Return the `struct tm' representation of *T in local time.  */
 struct tm *
-localtime (const time_t *t)
+__localtime64 (const __time64_t *t)
 {
   return __tz_convert (*t, 1, &_tmbuf);
 }
+libc_hidden_def (__localtime64)
+
+/* Provide a 32-bit variant if needed.  */
+
+#if __TIMESIZE != 64
+
+struct tm *
+localtime (const time_t *t)
+{
+  __time64_t t64 = *t;
+  return __localtime64 (&t64);
+}
 libc_hidden_def (localtime)
+
+#endif
-- 
2.17.1

Re: [PATCH v4] Y2038: add function __localtime64

[Albert ARIBAUD]

On Thu, 13 Dec 2018 08:44:41 +0100, "Albert ARIBAUD (3ADEV)"
<albert.aribaud@3adev.fr> wrote :

> Tested with 'make check' on x86_64-linux-gnu and i686-linux.gnu.
> 
> 	* include/time.h
> 	(__localtime64): Add.
>         * manual/maint.texi: Document Y2038 symbol handling.
> 	* time/localtime.c
> 	(__localtime64): Add.
> 	[__TIMERSIZE != 64] (__localtime): Turn into a wrapper.
> ---
> v4: Add paragraph about macros to manual section as suggested by
>     Joseph Myers
> v3: Rewrite manual section as suggested by Joseph Myers
>     Revert blank line removals
>     Ensure periods are followed with two spaces
>     Fix typos
>     Remove () after function names
> v2: Fix 'Y2038' => @dfn{Y2038} in manual/maint.texi

Is this patch ok now?

Cordialement,
Albert ARIBAUD
3ADEV

Re: [PATCH v4] Y2038: add function __localtime64

[Joseph Myers]

On Thu, 13 Dec 2018, Albert ARIBAUD (3ADEV) wrote:

> +With respect to time handling, @theglibc{} configurations fall in two

This is an adjective use, so @glibcadj{}.

> +These macros are purely internal to @theglibc{} and exist only so that
> +a single definition of the 64-bit time functions can be used  on both

Only one space between words, not two.

> +single-time and dual-time configurations, and so that glibc code can
> +freely call  the 64-bit functions internally in all configurations.

Likewise.

This patch is OK with those changes.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [PATCH v4] Y2038: add function __localtime64

[Albert ARIBAUD]

Hi Joseph,

On Mon, 17 Dec 2018 16:53:47 +0000, Joseph Myers
<joseph@codesourcery.com> wrote :

> On Thu, 13 Dec 2018, Albert ARIBAUD (3ADEV) wrote:
> 
> > +With respect to time handling, @theglibc{} configurations fall in two  
> 
> This is an adjective use, so @glibcadj{}.
> 
> > +These macros are purely internal to @theglibc{} and exist only so that
> > +a single definition of the 64-bit time functions can be used  on both  
> 
> Only one space between words, not two.
> 
> > +single-time and dual-time configurations, and so that glibc code can
> > +freely call  the 64-bit functions internally in all configurations.  
> 
> Likewise.
> 
> This patch is OK with those changes.

Thanks. Changes above done, rebasing above current master, re-running
'make check' as described in the commit message, then will apply.

Cordialement,
Albert ARIBAUD
3ADEV

Re: [PATCH v4] Y2038: add function __localtime64

[H.J. Lu]

On Fri, Dec 14, 2018 at 2:57 PM Albert ARIBAUD <albert.aribaud@3adev.fr> wrote:
>
> On Thu, 13 Dec 2018 08:44:41 +0100, "Albert ARIBAUD (3ADEV)"
> <albert.aribaud@3adev.fr> wrote :
>
> > Tested with 'make check' on x86_64-linux-gnu and i686-linux.gnu.
> >
> >       * include/time.h
> >       (__localtime64): Add.
> >         * manual/maint.texi: Document Y2038 symbol handling.
> >       * time/localtime.c
> >       (__localtime64): Add.
> >       [__TIMERSIZE != 64] (__localtime): Turn into a wrapper.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Is __TIMERSIZE a typo?
> > ---
> > v4: Add paragraph about macros to manual section as suggested by
> >     Joseph Myers
> > v3: Rewrite manual section as suggested by Joseph Myers
> >     Revert blank line removals
> >     Ensure periods are followed with two spaces
> >     Fix typos
> >     Remove () after function names
> > v2: Fix 'Y2038' => @dfn{Y2038} in manual/maint.texi
>
> Is this patch ok now?
>
> Cordialement,
> Albert ARIBAUD
> 3ADEV



-- 
H.J.

Re: [PATCH v4] Y2038: add function __localtime64

[Szabolcs Nagy]

On 13/12/2018 07:44, Albert ARIBAUD (3ADEV) wrote:
> Tested with 'make check' on x86_64-linux-gnu and i686-linux.gnu.
> 
> 	* include/time.h
> 	(__localtime64): Add.
>         * manual/maint.texi: Document Y2038 symbol handling.
> 	* time/localtime.c
> 	(__localtime64): Add.
> 	[__TIMERSIZE != 64] (__localtime): Turn into a wrapper.
> ---
> v4: Add paragraph about macros to manual section as suggested by
>     Joseph Myers
> v3: Rewrite manual section as suggested by Joseph Myers
>     Revert blank line removals
>     Ensure periods are followed with two spaces
>     Fix typos
>     Remove () after function names
> v2: Fix 'Y2038' => @dfn{Y2038} in manual/maint.texi
> 
>  include/time.h    |   8 +++
>  manual/maint.texi | 125 ++++++++++++++++++++++++++++++++++++++++++++++
>  time/localtime.c  |  16 +++++-
>  3 files changed, 148 insertions(+), 1 deletion(-)
...
> +The 64-bit-time implementation of @code{localtime} is written as follows
> +and is compiled for both dual-time and single-time configuration classes.
> +
> +@smallexample
> +struct tm *
> +__localtime64 (const __time64_t *t)
> +@lbracechar{}
> +  return __tz_convert (*t, 1, &_tmbuf);
> +@rbracechar{}
> +libc_hidden_def (__localtime64)
> +@end smallexample

install.texi requires GNU @code{texinfo} 4.7 or later
but this fails with texinfo 4.13:

/S/glibc/manual//maint.texi:288: Unknown command `lbracechar'.
/S/glibc/manual//maint.texi:288: Misplaced {.
/S/glibc/manual//maint.texi:288: Misplaced }.
/S/glibc/manual//maint.texi:290: Unknown command `rbracechar'.
/S/glibc/manual//maint.texi:290: Misplaced {.
/S/glibc/manual//maint.texi:290: Misplaced }.
/S/glibc/manual//maint.texi:302: Unknown command `lbracechar'.
/S/glibc/manual//maint.texi:302: Misplaced {.
/S/glibc/manual//maint.texi:302: Misplaced }.
/S/glibc/manual//maint.texi:305: Unknown command `rbracechar'.
/S/glibc/manual//maint.texi:305: Misplaced {.
/S/glibc/manual//maint.texi:305: Misplaced }.
makeinfo: Removing output file `/B/glibc/manual/libc.info' due to errors; use --force to preserve.
make[2]: *** [Makefile:142: /B/glibc/manual/libc.info] Error 1