From 2423b5b4a37da406d405649a4f0019c7343f76ca Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Tue, 26 Aug 2014 14:10:08 -0700 Subject: [PROPOSED PATCH 4/4] 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 | 6 ++++-- newctime.3 | 42 +++++++++++++++++++++++++++++++++-------- newtzset.3 | 64 ++++++++++++++++++++++++++++++++++++++++++++------------------ 3 files changed, 84 insertions(+), 28 deletions(-) diff --git a/NEWS b/NEWS index 3ebef9e..68d0ae3 100644 --- a/NEWS +++ b/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, diff --git a/newctime.3 b/newctime.3 index accefa5..6667e0d 100644 --- a/newctime.3 +++ b/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, diff --git a/newtzset.3 b/newtzset.3 index 51c4197..68905a5 100644 --- a/newtzset.3 +++ b/newtzset.3 @@ -7,6 +7,10 @@ tzset \- initialize time conversion information .el ds - \- .B #include .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 +.I Tzalloc +allocates and returns a time zone object described by +.BR TZ . +If .B TZ -to set time conversion information used by -.IR localtime . +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 -does not appear in the environment, -the best available approximation to local wall clock time, as specified -by the +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 -- 1.9.1