[libc] Introduces gmtime_r to LLVM libc, based on C99/C2X/Single Unix Sp.

[rtenneti]

Summary

gmtime and gmtime_r share the same common code. They call gmtime_internal
a static inline function. Thus added only validation tests for gmtime_r.

[MaskRay]

https://llvm.org/docs/DeveloperPolicy.html#commit-messages The subject line is usually an imperative sentence. Words like "This introduces" can be deleted.

[sivachandra]

In D99046#2642356, @MaskRay wrote:

https://llvm.org/docs/DeveloperPolicy.html#commit-messages The subject line is usually an imperative sentence. Words like "This introduces" can be deleted.

Also, please add "[libc] " prefix.

libc/config/linux/api.td

 def TimeAPI : PublicAPI<"time.h"> {
   let TypeDeclarations = [
     StructTm,
     TimeT,
   ];
 
   let Functions = [
     "gmtime",
+    "gmtime_r",
     "mktime",
   ];
 }
 
 def ErrnoAPI : PublicAPI<"errno.h"> {
   let Macros = [
     ErrnoMacro,
     // We largely depend on linux/errno.h to give us the

libc/config/linux/x86_64/entrypoints.txt

list(APPEND TARGET_LIBC_ENTRYPOINTS
     libc.src.threads.mtx_init
     libc.src.threads.mtx_lock
     libc.src.threads.mtx_unlock
     libc.src.threads.thrd_create
     libc.src.threads.thrd_join
 
     # time.h entrypoints
     libc.src.time.gmtime
+    libc.src.time.gmtime_r
     libc.src.time.mktime
 
     # unistd.h entrypoints
     libc.src.unistd.write
   )
 endif()
 
 set(TARGET_LLVMLIBC_ENTRYPOINTS
   ${TARGET_LIBC_ENTRYPOINTS}
   ${TARGET_LIBM_ENTRYPOINTS}
 )

libc/spec/stdc.td

HeaderSpec Time = HeaderSpec<
       [], // Enumerations
       [
           FunctionSpec<
               "gmtime",
               RetValSpec<StructTmPtr>,
               [ArgSpec<TimeTTypePtr>]
           >,
           FunctionSpec<
+              "gmtime_r",
+              RetValSpec<StructTmPtr>,
+              [
+                  ArgSpec<TimeTTypePtr>,
+                  ArgSpec<StructTmPtr>,
+              ]
+          >,
+          FunctionSpec<
               "mktime",
               RetValSpec<TimeTType>,
               [ArgSpec<StructTmPtr>]
           >,
       ]
   >;
 
   let Headers = [

libc/src/time/CMakeLists.txt

 add_object_library(
   time_utils
   SRCS
     time_utils.cpp
   HDRS
     time_utils.h
+  DEPENDS
+    libc.include.errno
+    libc.include.time
+    libc.src.errno.__errno_location
 )
 
 add_entrypoint_object(
   gmtime
   SRCS
     gmtime.cpp
   HDRS
     gmtime.h
   DEPENDS
     .time_utils
-    libc.include.errno
     libc.include.time
-    libc.src.errno.__errno_location
+)
+
+add_entrypoint_object(
+  gmtime_r
+  SRCS
+    gmtime_r.cpp
+  HDRS
+    gmtime_r.h
+  DEPENDS
+    .time_utils
+    libc.include.time
 )
 
 add_entrypoint_object(
   mktime
   SRCS
     mktime.cpp
   HDRS
     mktime.h
   DEPENDS
     .time_utils
     libc.include.errno
     libc.include.time
     libc.src.errno.__errno_location
 )

libc/src/time/gmtime.cpp

 //===-- Implementation of gmtime function ---------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "src/time/gmtime.h"
 #include "src/__support/common.h"
 #include "src/time/time_utils.h"
 
-#include <limits.h>
-
 namespace __llvm_libc {
 
 LLVM_LIBC_FUNCTION(struct tm *, gmtime, (const time_t *timer)) {
   static struct tm tm_out;
-  time_t seconds = *timer;
-  // Update the tm structure's year, month, day, etc. from seconds.
-  if (time_utils::UpdateFromSeconds(seconds, &tm_out) < 0) {
-    time_utils::OutOfRange();
-    return nullptr;
-  }
-
-  return &tm_out;
+  return time_utils::gmtime_internal(timer, &tm_out);
 }
 
 } // namespace __llvm_libc

libc/src/time/gmtime_r.h

+//===-- Implementation header of gmtime_r -----------------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_TIME_GMTIME_R_H
+#define LLVM_LIBC_SRC_TIME_GMTIME_R_H
+
+#include <time.h>
+
+namespace __llvm_libc {
+
+struct tm *gmtime_r(const time_t *timer, struct tm *result);
+
+} // namespace __llvm_libc
+
+#endif // LLVM_LIBC_SRC_TIME_GMTIME_R_H
+
+#include "include/time.h"

libc/src/time/gmtime_r.cpp

+//===-- Implementation of gmtime_r function -------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/time/gmtime_r.h"
+#include "src/__support/common.h"
+#include "src/time/time_utils.h"
+
+namespace __llvm_libc {
+
+LLVM_LIBC_FUNCTION(struct tm *, gmtime_r,
+                   (const time_t *timer, struct tm *result)) {
+  return time_utils::gmtime_internal(timer, result);
+}
+
+} // namespace __llvm_libc

libc/src/time/time_utils.h

struct TimeConstants {
   // Tuesday, 19 January 2038 (corresponding to 2,147,483,647 seconds since the
   // start of the epoch). This means that systems using a 32-bit time_t type are
   // susceptible to the Year 2038 problem.
   static constexpr int EndOf32BitEpochYear = 2038;
 
   static constexpr time_t OutOfRangeReturnValue = -1;
 };
 
+// Update the "tm" structure's year, month, etc. members from seconds.
+// "total_seconds" is the number of seconds since January 1st, 1970.
+extern int64_t UpdateFromSeconds(int64_t total_seconds, struct tm *tm);
+
 // POSIX.1-2017 requires this.
 static inline time_t OutOfRange() {
   llvmlibc_errno = EOVERFLOW;
   return static_cast<time_t>(-1);
 }
 
-// Update the "tm" structure's year, month, etc. members from seconds.
-// "total_seconds" is the number of seconds since January 1st, 1970.
-extern int64_t UpdateFromSeconds(int64_t total_seconds, struct tm *tm);
+static inline struct tm *gmtime_internal(const time_t *timer,
+                                         struct tm *result) {
+  int64_t seconds = *timer;
+  // Update the tm structure's year, month, day, etc. from seconds.
+  if (UpdateFromSeconds(seconds, result) < 0) {
+    OutOfRange();
+    return nullptr;
+  }
+
+  return result;
+}
 
 } // namespace time_utils
 } // namespace __llvm_libc
 
 #endif // LLVM_LIBC_SRC_TIME_TIME_UTILS_H

libc/test/src/time/CMakeLists.txt

 add_libc_testsuite(libc_time_unittests)
 
 add_libc_unittest(
-  mktime
+  gmtime
   SUITE
     libc_time_unittests
   SRCS
     gmtime_test.cpp
-    mktime_test.cpp
   HDRS
     TmMatcher.h
   DEPENDS
     libc.src.time.gmtime
+)
+
+add_libc_unittest(
+  gmtime_r
+  SUITE
+    libc_time_unittests
+  SRCS
+    gmtime_r_test.cpp
+  HDRS
+    TmMatcher.h
+  DEPENDS
+    libc.src.time.gmtime_r
+)
+
+add_libc_unittest(
+  mktime
+  SUITE
+    libc_time_unittests
+  SRCS
+    mktime_test.cpp
+  HDRS
+    TmMatcher.h
+  DEPENDS
     libc.src.time.mktime
 )

libc/test/src/time/gmtime_r_test.cpp

+//===-- Unittests for gmtime_r --------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/time/gmtime_r.h"
+#include "src/time/time_utils.h"
+#include "test/src/time/TmMatcher.h"
+#include "utils/UnitTest/Test.h"
+
+using __llvm_libc::time_utils::TimeConstants;
+
+// gmtime and gmtime_r share the same code and thus didn't repeat all the tests
+// from gmtime. Added couple of validation tests.
+TEST(LlvmLibcGmTimeR, EndOf32BitEpochYear) {
+  // Test for maximum value of a signed 32-bit integer.
+  // Test implementation can encode time for Tue 19 January 2038 03:14:07 UTC.
+  time_t seconds = 0x7FFFFFFF;
+  struct tm tm_data;
+  struct tm *tm_data_ptr;
+  tm_data_ptr = __llvm_libc::gmtime_r(&seconds, &tm_data);
+  EXPECT_TM_EQ((tm{7,  // sec
+                   14, // min
+                   3,  // hr
+                   19, // day
+                   0,  // tm_mon starts with 0 for Jan
+                   2038 - TimeConstants::TimeYearBase, // year
+                   2,                                  // wday
+                   7,                                  // yday
+                   0}),
+               *tm_data_ptr);
+  EXPECT_TM_EQ(*tm_data_ptr, tm_data);
+}
+
+TEST(LlvmLibcGmTimeR, Max64BitYear) {
+  if (sizeof(time_t) == 4)
+    return;
+  // Test for Tue Jan 1 12:50:50 in 2,147,483,647th year.
+  time_t seconds = 67767976202043050;
+  struct tm tm_data;
+  struct tm *tm_data_ptr;
+  tm_data_ptr = __llvm_libc::gmtime_r(&seconds, &tm_data);
+  EXPECT_TM_EQ((tm{50, // sec
+                   50, // min
+                   12, // hr
+                   1,  // day
+                   0,  // tm_mon starts with 0 for Jan
+                   2147483647 - TimeConstants::TimeYearBase, // year
+                   2,                                        // wday
+                   50,                                       // yday
+                   0}),
+               *tm_data_ptr);
+  EXPECT_TM_EQ(*tm_data_ptr, tm_data);
+}