[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

Re: [PATCH v4] Y2038: add function __localtime64

[Albert ARIBAUD]

Hi Rafal,

Le Wed, 19 Dec 2018 09:13:38 +0100 (CET), Rafal Luzynski
<digitalfreak@lingonborough.com> a écrit :

> 18.12.2018 07:00 Albert ARIBAUD <albert.aribaud@3adev.fr> wrote:
> > [...]
> > Commit is ready anyway and checked against both make check and
> > make pdf.  
> 
> Thank you for pushing this new commit, Albert.  This works correctly
> now.  However, somebody please fix me if I'm wrong but AFAIK even such
> trivial patches should be posted to libc-alpha as [PATCH COMMITTED].

Apologies for missing this.

> Regards,
> 
> Rafal

Cordialement,
Albert ARIBAUD
3ADEV

Re: [PATCH v4] Y2038: add function __localtime64

[Rafal Luzynski]

18.12.2018 07:00 Albert ARIBAUD <albert.aribaud@3adev.fr> wrote:
> [...]
> Commit is ready anyway and checked against both make check and
> make pdf.

Thank you for pushing this new commit, Albert.  This works correctly
now.  However, somebody please fix me if I'm wrong but AFAIK even such
trivial patches should be posted to libc-alpha as [PATCH COMMITTED].

Regards,

Rafal

Re: [PATCH v4] Y2038: add function __localtime64

[Florian Weimer]

* Albert ARIBAUD:

> Hi Joseph,
>
> On Tue, 18 Dec 2018 01:09:25 +0000, Joseph Myers
> <joseph@codesourcery.com> wrote :
>
>> On Tue, 18 Dec 2018, Rafal Luzynski wrote:
>> 
>> > Perhaps you should use:
>> > 
>> >     the @glibcadj{}
>> > 
>> > instead?  
>> 
>> I don't think the word "the" belongs there at all; just @glibcadj{}.
>
> I'd run 'make manual' instead of 'make pdf'. :(
>
> This was pushed already, and master has't moved yet. For the sake of
> bisectability, should I do a git amend (for this and changelog typo
> altogether)?
>
> Commit is ready anyway and checked against both make check and
> make pdf.

Please push a new commit and do not amend the existing commit.

Thanks,
Florian

Re: [PATCH v4] Y2038: add function __localtime64

[Andreas Schwab]

On Dez 18 2018, Albert ARIBAUD <albert.aribaud@3adev.fr> wrote:

> This was pushed already, and master has't moved yet. For the sake of
> bisectability, should I do a git amend (for this and changelog typo
> altogether)?

You must never modify published commits (and the server will not allow
to push that anyway).

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."

Re: [PATCH v4] Y2038: add function __localtime64

[Albert ARIBAUD]

Hi Joseph,

On Tue, 18 Dec 2018 01:09:25 +0000, Joseph Myers
<joseph@codesourcery.com> wrote :

> On Tue, 18 Dec 2018, Rafal Luzynski wrote:
> 
> > Perhaps you should use:
> > 
> >     the @glibcadj{}
> > 
> > instead?  
> 
> I don't think the word "the" belongs there at all; just @glibcadj{}.

I'd run 'make manual' instead of 'make pdf'. :(

This was pushed already, and master has't moved yet. For the sake of
bisectability, should I do a git amend (for this and changelog typo
altogether)?

Commit is ready anyway and checked against both make check and
make pdf.

Cordialement,
Albert ARIBAUD
3ADEV

Re: [PATCH v4] Y2038: add function __localtime64

[Joseph Myers]

On Tue, 18 Dec 2018, Rafal Luzynski wrote:

> Perhaps you should use:
> 
>     the @glibcadj{}
> 
> instead?

I don't think the word "the" belongs there at all; just @glibcadj{}.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [PATCH v4] Y2038: add function __localtime64

[Rafal Luzynski]

Albert,

Your commit fails during "make install" with the following message:

    ./maint.texi:198: unknown command `theglibcadj'
    ./maint.texi:198: misplaced {
    ./maint.texi:198: misplaced }

Perhaps you should use:

    the @glibcadj{}

instead?

Regards,

Rafal