Add documentation for the core NetBSD-inspired functions.

Lack of documentation reported by Jonathan Lennox in:
http://mm.icann.org/pipermail/tz/2014-August/021529.html
* newtzset.3: Document tzalloc and tzfree.
* newctime.3: Document localtime_rz and mktime_z.
* NEWS: Mention this.

NEWS

@@ -136,8 +136,10 @@ Unreleased, experimental changes
     suggesting a CONTRIBUTING file, and to Tony Finch and Walter Harms
     for debugging it.)
 
-    The man pages have been updated to use function prototypes, and
-    to document thread-safe variants like localtime_r.
+    The man pages have been updated to use function prototypes,
+    to document thread-safe variants like localtime_r, and to document
+    the NetBSD-inspired functions tzalloc, tzfree, localtime_rz, and
+    mktime_z.
 
     The fields in Link lines have been renamed to be more descriptive
     and more like the parameters of 'ln'.  LINK-FROM has become TARGET,

newctime.3

@@ -25,6 +25,10 @@ asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time
 .B "struct tm *localtime_r(time_t const *restrict clock,"
 .B "    struct tm *restrict result);"
 .PP
+.B "struct tm *localtime_rz(timezone_t restrict zone,"
+.B "    time_t const *restrict clock,"
+.B "    struct tm *restrict result);"
+.PP
 .B struct tm *gmtime(time_t const *clock);
 .PP
 .B "struct tm *gmtime_r(time_t const *restrict clock,"
@@ -32,6 +36,9 @@ asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time
 .PP
 .B time_t mktime(struct tm *tm);
 .PP
+.B "time_t mktime_z(timezone_t restrict zone,"
+.B "    struct tm *restrict tm);"
+.PP
 .B cc ... \*-ltz
 .fi
 .SH DESCRIPTION
@@ -110,14 +117,6 @@ structure to a string,
 as shown in the above example,
 and returns a pointer to the string.
 .PP
-.IR Ctime_r ,
-.IR localtime_r ,
-.IR gmtime_r ,
-and
-.I asctime_r
-are like their unsuffixed counterparts, except that they accept an
-additional argument specifying where to store the result if successful.
-.PP
 .I Mktime
 converts the broken-down time,
 expressed as local time,
@@ -175,6 +174,33 @@ returns the difference between two calendar times,
 .IR time0 ),
 expressed in seconds.
 .PP
+.IR Ctime_r ,
+.IR localtime_r ,
+.IR gmtime_r ,
+and
+.I asctime_r
+are like their unsuffixed counterparts, except that they accept an
+additional argument specifying where to store the result if successful.
+.PP
+.IR Localtime_rz
+and
+.I mktime_z
+are like their unsuffixed counterparts, except that they accept an
+extra initial
+.B zone
+argument specifying the time zone to be used for conversion.
+If
+.B zone
+is null, UTC is used; otherwise,
+.B zone
+should be have been allocated by
+.I tzalloc
+and should not be freed until after all uses (e.g., by calls to
+.IR strftime )
+of the filled-in
+.B tm_zone
+fields.
+.PP
 Declarations of all the functions and externals, and the
 .q "tm"
 structure,

newtzset.3

@@ -7,6 +7,10 @@ tzset \- initialize time conversion information
 .el ds - \-
 .B #include <time.h>
 .PP
+.B timezone_t tzalloc(char const *TZ);
+.PP
+.B void tzfree(timezone_t tz);
+.PP
 .B void tzset(void);
 .PP
 .B cc ... \*-ltz
@@ -21,30 +25,61 @@ tzset \- initialize time conversion information
 .de q
 \\$3\*(lq\\$1\*(rq\\$2
 ..
-.I Tzset
-uses the value of the environment variable
-.B TZ
-to set time conversion information used by
-.IR localtime .
+.I Tzalloc
+allocates and returns a time zone object described by
+.BR TZ .
 If
 .B TZ
-does not appear in the environment,
-the best available approximation to local wall clock time, as specified
-by the
+is not a valid time zone description, or if the object cannot be allocated,
+.I tzalloc
+returns a null pointer and sets
+.BR errno .
+.PP
+.I Tzfree
+frees a time zone object
+.BR tz ,
+which should have been successfully allocated by
+.IR tzalloc .
+This invalidates any
+.B tm_zone
+pointers that
+.B tz
+was used to set.
+.PP
+.I Tzset
+acts like
+.BR tzalloc(getenv("TZ")) ,
+except it saves any resulting time zone object into internal
+storage that is accessed by
+.IR localtime ,
+.IR localtime_r ,
+and
+.IR mktime .
+The anonymous shared time zone object is freed by the next call to
+.IR tzset .
+If the implied call to
+.B tzalloc
+fails,
+.I tzset
+falls back on UTC.
+.PP
+If
+.B TZ
+is null, the best available approximation to local wall
+clock time, as specified by the
 .IR tzfile (5)-format
 file
 .B localtime
-in the system time conversion information directory, is used by
-.IR localtime .
+in the system time conversion information directory, is used.
 If
 .B TZ
-appears in the environment but its value is a null string,
+is the empty string,
 Universal Time (UT) is used, with the abbreviation "UTC"
 and without leap second correction; please see
 .IR newctime (3)
 for more about UT, UTC, and leap seconds.  If
 .B TZ
-appears in the environment and its value is not a null string:
+is nonnull and nonempty:
 .IP
 if the value begins with a colon, it is used as a pathname of a file
 from which to read the time conversion information;
@@ -267,13 +302,6 @@ For compatibility with System V Release 3.1, a semicolon
 may be used to separate the
 .I rule
 from the rest of the specification.
-.PP
-If the
-.B TZ
-environment variable does not specify a
-.IR tzfile (5)-format
-and cannot be interpreted as a direct specification,
-UTC is used.
 .SH FILES
 .ta \w'/usr/local/etc/zoneinfo/posixrules\0\0'u
 /usr/local/etc/zoneinfo	time zone information directory