time_rz: Put reference documentation into the .h file.

* lib/time.in.h (timezone_t, tzalloc, tzfree, localtime_rz, mktime_z):
Add comments, based on modules/time_rz.
* modules/time_rz (Comment): Remove section.

diff --git a/ChangeLog b/ChangeLog
index 63aaa7b487aba84fb1f6b464cc8922fd1451935c..b71c327f9bd725b2a9f6803f98ac06a74765fb8c 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2021-03-14  Bruno Haible  <bruno@clisp.org>
+
+       time_rz: Put reference documentation into the .h file.
+       * lib/time.in.h (timezone_t, tzalloc, tzfree, localtime_rz, mktime_z):
+       Add comments, based on modules/time_rz.
+       * modules/time_rz (Comment): Remove section.
+
 2021-03-14  Bruno Haible  <bruno@clisp.org>
 
        parse-datetime tests: Avoid a test failure on NetBSD.

diff --git a/lib/time.in.h b/lib/time.in.h
index 4da1172bded1b0bb74f32aaf2f7320f62c365b03..44483d0da621bc1d9fa0dd35825c9a87934699a6 100644 (file)
--- a/lib/time.in.h
+++ b/lib/time.in.h
@@ -340,22 +340,60 @@ _GL_CXXALIASWARN (strftime);
 # endif
 
 # if defined _GNU_SOURCE && @GNULIB_TIME_RZ@ && ! @HAVE_TIMEZONE_T@
+/* Functions that use a first-class time zone data type, instead of
+   relying on an implicit global time zone.
+   Inspired by NetBSD.  */
+
+/* Represents a time zone.
+   (timezone_t) NULL stands for UTC.  */
 typedef struct tm_zone *timezone_t;
+
+/* tzalloc (name)
+   Returns a time zone object for the given time zone NAME.  This object
+   represents the time zone that other functions would use it the TZ
+   environment variable was set to NAME.
+   If NAME is NULL, the result represents the time zone that other functions
+   would use it the TZ environment variable was unset.
+   May return NULL if NAME is invalid (this is platform dependent) or
+   upon memory allocation failure.  */
 _GL_FUNCDECL_SYS (tzalloc, timezone_t, (char const *__name));
 _GL_CXXALIAS_SYS (tzalloc, timezone_t, (char const *__name));
+
+/* tzfree (tz)
+   Frees a time zone object.
+   The argument must have been returned by tzalloc().  */
 _GL_FUNCDECL_SYS (tzfree, void, (timezone_t __tz));
 _GL_CXXALIAS_SYS (tzfree, void, (timezone_t __tz));
+
+/* localtime_rz (tz, &t, &result)
+   Converts an absolute time T to a broken-down time RESULT, assuming the
+   time zone TZ.
+   This function is like 'localtime_r', but relies on the argument TZ instead
+   of an implicit global time zone.  */
 _GL_FUNCDECL_SYS (localtime_rz, struct tm *,
                   (timezone_t __tz, time_t const *restrict __timer,
                    struct tm *restrict __result) _GL_ARG_NONNULL ((2, 3)));
 _GL_CXXALIAS_SYS (localtime_rz, struct tm *,
                   (timezone_t __tz, time_t const *restrict __timer,
                    struct tm *restrict __result));
+
+/* mktime_z (tz, &tm)
+   Normalizes the broken-down time TM and converts it to an absolute time,
+   assuming the time zone TZ.  Returns the absolute time.
+   This function is like 'mktime', but relies on the argument TZ instead
+   of an implicit global time zone.  */
 _GL_FUNCDECL_SYS (mktime_z, time_t,
-                  (timezone_t __tz, struct tm *restrict __result)
+                  (timezone_t __tz, struct tm *restrict __tm)
                   _GL_ARG_NONNULL ((2)));
 _GL_CXXALIAS_SYS (mktime_z, time_t,
-                  (timezone_t __tz, struct tm *restrict __result));
+                  (timezone_t __tz, struct tm *restrict __tm));
+
+/* Time zone abbreviation strings (returned by 'localtime_rz' or 'mktime_z'
+   in the 'tm_zone' member of 'struct tm') are valid as long as
+     - the 'struct tm' argument is not destroyed or overwritten,
+   and
+     - the 'timezone_t' argument is not freed through tzfree().  */
+
 # endif
 
 /* Convert TM to a time_t value, assuming UTC.  */

diff --git a/modules/time_rz b/modules/time_rz
index 6a2b23c8cc605e58bf8b9e9175f0e1202b1fd6b4..ebcef84fff21d4bac11e137407a8367096119e1e 100644 (file)
--- a/modules/time_rz
+++ b/modules/time_rz
@@ -1,17 +1,6 @@
 Description:
 Reentrant time zone functions: localtime_rz, mktime_z, etc.
 
-Comment:
-This implements the NetBSD-inspired extensions to <time.h>, which
-defines a type timezone_t and associated allocation functions tzalloc
-and tzfree, along with two functions localtime_rz and mktime_z that
-are like localtime_r and mktime except they have a new leading
-timezone_t argument.  Time zone abbreviation strings have lifetimes
-equal to the corresponding struct tm or timezone_t object (whichever
-is less).  tzalloc (X) yields a time zone object equivalent to setting
-the TZ environment variable to X.  tzalloc (NULL) is the same as an
-unset TZ environment variable.  (timezone_t) 0 stands for UTC.
-
 Files:
 lib/time-internal.h
 lib/time_rz.c