lib/timeutil: avoid implementation-defined behavior

The algorithm for converting broken-down civil time to seconds in the
POSIX epoch time scale would produce undefined behavior on a toolchain
that uses a 32-bit time_t in cases where the referenced time could not
be represented exactly.

However, there are use cases in Zephyr for civil time conversions
outside the 32-bit representable range of 1901-12-13T20:45:52Z through
2038-01-19T03:14:07Z inclusive.

Add new API that specifically returns a 64-bit signed seconds count, and
revise the existing API to detect out-of-range values and convert them
to a diagnosible error.

Closes #18465

Signed-off-by: Peter A. Bigot <pab@pabigot.com>

include/sys/timeutil.h

@@ -11,7 +11,11 @@
  * POSIX defines gmtime() to convert from time_t to struct tm, but all
  * inverse transformations are non-standard or require access to time
  * zone information.  timeutil_timegm() implements the functionality
- * of the GNU extension timegm() function.
+ * of the GNU extension timegm() function, but changes the error value
+ * as @c EOVERFLOW is not a standard C error identifier.
+ *
+ * timeutil_timegm64() is provided to support full precision
+ * conversion on platforms where @c time_t is limited to 32 bits.
  */
 
 #ifndef ZEPHYR_INCLUDE_SYS_TIMEUTIL_H_
@@ -32,6 +36,19 @@ extern "C" {
  *
  * @see http://man7.org/linux/man-pages/man3/timegm.3.html
  */
+s64_t timeutil_timegm64(const struct tm *tm);
+
+/**
+ * @brief Convert broken-down time to a POSIX epoch offset in seconds.
+ *
+ * @param tm pointer to broken down time.
+ *
+ * @return the corresponding time in the POSIX epoch time scale.  If
+ * the time cannot be represented then @c (time_t)-1 is returned and
+ * @c errno is set to @c ERANGE`.
+ *
+ * @see http://man7.org/linux/man-pages/man3/timegm.3.html
+ */
 time_t timeutil_timegm(const struct tm *tm);
 
 #ifdef __cplusplus