On Thu, 7 Jun 2001, Jonathan Lennox wrote:

I've drawn a lot of inspiration for this work from Ulrich Drepper's work on thread-aware POSIX locales (http://www.cygnus.com/~drepper/tllocale.ps.bz2).

* Are people interested in this? * Do people think that my proposal is a sensible API? * Would people be interested in seeing the resulting code? * Would people be interested in helping write the code? * Would the resulting code (assuming it's written sensibly) be acceptable/appropriate for incorporation into tzcode?

Comments very welcome!

Have you looked at Markus Kuhn's proposal at http://www.cl.cam.ac.uk/~mgk25/c-time/ and the other ones linked to from there? My recommendations: * Design the proposal as an amendment for ISO C rather than POSIX. * Don't touch how timestamps are represented (any interface can be adapted to use any time_t replacement that gets agreed). * Provide a struct tm replacement with (a) subsecond resolution and (b) a proper field indicating which repetition of a repeated timestamp is referred to (A/B in German time notation), rather than the inadequate indication of whether the time is in daylight savings. * Provide four conversion functions: between time_t and broken down times, in either direction, and equivalents of strftime and wcsftime. Don't duplicate other functions such as asctime that can easily be replicated. * Use an C99 snprintf-style return value (return the length of buffer required if the buffer isn't long enough) rather than what strftime currently does (return 0 if the buffer isn't long enough). * Provide specified timezone names for both the user's local timezone and the system's local timezone. -- Joseph S. Myers jsm28@cam.ac.uk

Jonathan Lennox wrote:

* Are people interested in this?

I think it's a good idea.

* Do people think that my proposal is a sensible API?

My main problem with it is that I see no point in the struct tz objects. Programs don't typically do zillions of time conversions. I would rather pass the time zone name to each externally vizible *_z function and let them look up the name in the currently maintained cache, if any. We certainly want to discourage callers from trying to save the tz structure in a persistent database, since its content may change over time. This would require adding a new function to retrieve the tz_name array for a given time zone name. I also question the utility of a per-thread current time zone being maintained by the library, which then has to know what kind of thread library you have so it can discover the current thread ID. Making something thread-safe at the cost of adding one argument to each tzlib call is not so bad. -- There is / one art || John Cowan <jcowan@reutershealth.com> no more / no less || http://www.reutershealth.com to do / all things || http://www.ccil.org/~cowan with art- / lessness \\ -- Piet Hein

<<On Thu, 7 Jun 2001 12:09:33 -0400 (EDT), Jonathan Lennox <lennox@cs.columbia.edu> said:

Three functions manipulate a struct tz:

newtz -- create a time zone object

Poor choice of name. I believe that POSIX now requires any new interfaces to use namespace prefixes to avoid taking away more application namespace.

#include <time.h>

...probably a different header file should be used as well.

tzname is a pointer to a string representing the name of the allocated time zone.

Should allow a null pointer to represent whatever the default (as used in tzset()) would be.

It has one externally-visible element: tz_name,

A structure of this sort should be opaque. Define accessor functions, not the members of the structure. Unfortunately, POSIX is rather too fond of defining foo_t typedefs for things (like pointers to opaque structures) which should not be typedef'ed, so `struct tz' would probably get transmogrified by standards committees into `timezone_t' or some similar nonsense.

If tzname is NULL, the returned struct tz describes the local wall-clock time, as best as it is known by the local system.

Oops... Should reorder this description.

If tzname is the empty string "", the returned struct tz describes Coordinated Universal Time (UTC). (The POSIX rules also allow UTC to be represented with the string "GMT0".)

As I think about it, I think a better alternative would be parallel to how setlocale() works: If tzname is a null pointer, the return value shall represent Coordinated Universal Time (UTC). If tzname is a string of length zero, the return value shall represent the same timezone as is chosen by tzset().

This interface is designed so that newtz(getenv("TZ")) will return an object describing the default time zone object that non-thread-aware versions of the time functions will use by default, provided TZ (if set) is set to a valid time zone name.

I would suggest that requiring applications to check the ennvironment -- or even assuming that there is a meaningful environment, which there may not be in some profiles -- is probably a bad idea and potentially prone to error. (Consider: getenv("ZT") would be a common typo which would not be recognized by a compiler.)

#include <time.h> void freetz(struct tz* tzobj);

The same namespace comments apply here as well.

If the system defines the tm_zone field of struct tm, this function invalidates the strings pointed to by the tm_zone field of all struct tm values created by localtime_z called with this tzobj.

The result of accessing any freed memory is undefined, so such language is not necessary and would probably reduce standardizability.

#include <time.h> struct tz* duptz(const struct tz* tzobj);

I'm not sure how really useful this interface is. In many other places in C and POSIX we define opaque structures without any sort of ``duplicate'' mechanism, and leave the application to do reference counting if it so wishes. (Viz., the `FILE *' interfaces.)

struct tm * localtime_z(const time_t *clock, struct tm *result, const struct tz *tz);

Equivalent to localtime_r() or gmtime_r(), in the time zone represented by tz, except that tz->tz_name is not modified.

There doesn't seem to me to be any benefit in this restriction, and a program which is adopting this interface may well need to interact or be linked with libraries developed to the old interface. If you eliminate this restriction, then you no longer need to duplicate the strftime() interfacem, since the returned `struct tm' contains all the necessary information.

char * ctime_z(const time_t *clock, char *buf, const struct tz *tz);

char * asctime_z(const struct tm *tm, char *buf, const struct tz *tz);

As Joseph Myers pointed out, these interfaces are redundant with strftime() and an appropriate format specifier. Don't forget that for C99 you'll want to add an appropriate `restrict' qualifier or two.

Name tzuse -- use time zone object in current thread.

Synopsis #include <time.h> void tzuse(const struct tz *tz);

Rather than having a specific function, one might instead define a specific pre-instantiated key such that one can call `pthread_setspecific(PTHREAD_DEFAULT_TIMEZONE, tz)' with the consequences you describe. This makes it possible for the application to find out what the current timezone is, simply by calling `pthread_getspecific(PTHREAD_DEFAULT_TIMEZONE)'. You would need to specify what the thread-termination consequences are. -GAWollman

From: Jonathan Lennox <lennox@cs.columbia.edu> Date: Thu, 7 Jun 2001 12:09:33 -0400 (EDT)

* Are people interested in this? * Would people be interested in seeing the resulting code? * Would people be interested in helping write the code? * Would the resulting code (assuming it's written sensibly) be acceptable/appropriate for incorporation into tzcode?

Yes, several people have proposed something along those lines. (I'm one of them -- see <http://www.twinsun.com/tz/timeapi.html>.) However, nobody has gotten anything running yet. Part of the problem with many of the proposals (mine included) is that they're perhaps too ambitious. There are a lot of problems with the existing interfaces, and it's a pain to solve them all at once.

* Do people think that my proposal is a sensible API?

Here are some thoughts: * Is this spec compatible with Drepper's proposal? This is a relevant issue, since time zone names ought to be part of the locale. For example, where you say "EDT", a French Canadian would say "HAE". Thus, for example, for full generality it seems to me that localtime_z would need to have a locale parameter or have access to the locale somehow. Admittedly the current time zone database does not support any locale other than English, but we've seen proposals for fixing this and it will probably happen some day. * Conversely, if you merge Drepper's work with your proposal, then 'struct tz' should be part of his locale object, so that there is no need for a separate 'struct tz', or a separate 'localtime_z', etc. Perhaps this is too drastic (as you may not want to assume Drepper's approach), but treating TZ like we treat LC_CTYPE etc. would have real advantages if we were starting from green fields. * I see no reason for struct tz to make tz_name visible. If a user wants the time zone name, he can use strftime_z with the "%Z" format. Many time zones have more than two names, so it's incorrect for tz_name to have just two elements anyway. * I would drop 'tzuse', or at least make it optional and dependent on support for POSIX threads. If you drop it, you don't have to worry about threads at all; you'll simply have thread-safe functions. It's not worth the hassle of interacting with all the different thread implementations out there. * Frankly, I don't know how POSIX functions like localtime_r are supposed to interact with setting the TZ variable. It seems to me that the POSIX spec is unclear here. This murk is not your fault, but it seems to me that if you want to address the thread problem that this issue should be made crystal clear in any thread-safe spec. * 'strptime_z' should be marked as being POSIX-only; it needn't be available on ISO-C-only systems. * What is the use of 'duptz'? Can you give an example that cannot easily be expressed without 'duptz'? * A nit: you mention "GMT0", but the latest POSIX draft says that "date -u" acts as if TZ is either "UTC0" or "GMT0", with "UTC0" preferred.

Date: Thu, 7 Jun 2001 17:30:58 +0100 (BST) From: "Joseph S. Myers" <jsm28@cam.ac.uk>

* Don't touch how timestamps are represented (any interface can be adapted to use any time_t replacement that gets agreed).

Presumably if we have an xtime_t, then the xtime_t functions will address all the issues Lennox raises, because they'll have merged or subsumed his ideas.

* Provide a struct tm replacement with (a) subsecond resolution and (b) a proper field indicating which repetition of a repeated timestamp is referred to (A/B in German time notation), rather than the inadequate indication of whether the time is in daylight savings. * Provide four conversion functions: between time_t and broken down times, in either direction, and equivalents of strftime and wcsftime. Don't duplicate other functions such as asctime that can easily be replicated. * Use an C99 snprintf-style return value (return the length of buffer required if the buffer isn't long enough) rather than what strftime currently does (return 0 if the buffer isn't long enough).

These changes all sound reasonable to me -- though they make the proposal more ambitious. If we go down this route, though, we should definitely look at Kuhn's and my proposals (both of which are too ambitious, in my opinion). I could try to merge the three, or perhaps you'd like to take a crack at it.

* Provide specified timezone names for both the user's local timezone and the system's local timezone.

Doesn't his proposed API already do this, with newtz(getenv("TZ")) and newtz(NULL)?

Jonathan Lennox said:

One of the major shortcomings of the current time zone API defined by ISO C [...] Therefore, I've written up a proposal (attached) for a thread-safe API for time zone functions.

Please don't. There are a number of known deficiencies with the C time stuff, and it really needs redesigning from scratch with a solid set of concepts behind it. For various reasons I'm supposed to be organising a group to do that, but it's way way down my list of priorities. Any new design will, of course, need to address these issues, but I don't think there's any point in doing this sort of ad hoc work to solve just one item. -- Clive D.W. Feather | Work: <clive@demon.net> | Tel: +44 20 8371 1138 Internet Expert | Home: <clive@davros.org> | Fax: +44 20 8371 1037 Demon Internet | WWW: http://www.davros.org | DFax: +44 20 8371 4037 Thus plc | | Mobile: +44 7973 377646

After the comments on this list (and several sent by private e-mail) I've revised yesterday's thread-safe time zone API document. I thank everyone who commented; I think this document is a lot stronger and clearer. A list of changes from yesterday's version are given at the end of the document. Once again, comments are very welcome. A proposal for thread-safe time zone information. A set of extensions to ISO C (99) and IEEE POSIX (200x). by Jonathan Lennox, Columbia University. Version 2. Summary: A new data type is defined, 'struct timezone', that represents the time zone information for a particular region. Versions of the ISO C time conversion functions are defined that take this data type as an argument. Definitions: Time zone: The set of information necessary to correctly convert bidirectionally between a time_t and a struct tm, for a particular geographic region. Wall clock time: The system's best approximation of the local time in its physical location, independent of the physical location of any user. Functions defined in this proposal: Functions manipulating struct timezone values: Name tz_prep -- prepare a time zone object, based on a descriptive string. Synopsis #include <time.h> int tz_prep tz_prep(struct timezone** tz, const char *tzstring); Description The tz_prep() function creates a new time zone object, corresponding to the given time zone name. tzstring is a pointer to a string, or NULL. The two defined values of tzstring are NULL, representing the system's best approximation of its wall clock time, and the zero-length string "", representing the system's best approximation of Coordinated Universal Time (UTC). On successful completion, *tz will contain a pointer to a struct timezone, contains all necessary information to represent times in the specified time zone. It has no externally-visible elements. POSIX extension: In a POSIX-based environment, the syntax of tzstring is the same as that of the "TZ" environment variable, including the implementation-defined values beginning with ':'. Return Value On successful completion, tz_prep() returns a value of 0 and fills in *tz. On failure, an error number is returned and no resources are allocated. Errors The tz_prep() function shall fail if: ENOMEM Not enough memory is available to create the time zone object. ENOENT No known time zone corresponds to tzname. The tz_prep() function may fail if: * There is a problem with the system's configuration (such as an on-disk time zone database) which caused retrieval of the time zone information to fail unexpectedly. In this case any appropriate error number may be returned. Rationale and commentary Systems which define extensions beyond POSIX (such as the Olson time zone names) for the "TZ" environment variable should support the same extensions for tzstring. Under the POSIX rules, strings such as "UTC0" can also represent UTC, but the empty string "" is the portable representation. This representation is also correctly locale-independent -- "UTC0" in fr_FR generates times with the incorrect time zone abbreviation "UTC", whereas "" in that locale should use the correct time zone abbreviation "TUC" if the time zone code correctly supports locales. This interface is designed so that tz_prep(getenv("TZ")) will return an object describing the default time zone object that non-thread-aware versions of the time functions will use by default, provided TZ (if set) is set to a valid time zone name. Question for discussion: should there be an ISO C way of saying "the timezone which localtime() and mktime() would use by default"? Currently this is only possible for POSIX, using thee tz_prep(getenv("TZ")) idiom mentioned above. Name tz_free -- Free resources allocated for a time zone object Synopsis #include <time.h> void tz_free(struct timezone* tzobj); Description The tz_free() function frees the resources allocated for a time zone object returned by a call to tz_prep(). Return Value None. Errors None. Rationale and commentary None needed. Functions using struct timezone to manipulate time values: Name time_make - derive a time_t from a struct tm, in a specified time zone. Synopsis #include <time.h> int time_make(time_t *clock, struct tm *tm, const timezone_t *tz); Description This function interprets the broken-down time in *tm as a local time in the timezone specified in *tz, and writes the corresponding value into *clock, using the same encoding as that of the values returned by the 'time' function. The original values of the tm_wday and tm_yday components of *tm are ignored, and the original values of the other components are not restricted to their normal ranges. (A positive or zero value for tm_isdst causes mktime() to presume initially that summer time (for example, Daylight Saving Time) is or is not in effect for the specified time, respectively. A negative value for tm_isdst causes the mktime() function to attempt to divine whether summer time is in effect for the specified time.) On successful completion, the values of the tm_wday and tm_yday components of *tm are set appropriately, and the other components are set to represent the specified calendar time, but with their values forced to their normal ranges; the final value of tm_mday is not set until tm_mon and tm_year are determined. Returns time_make returns 0 on sucessful completion, sets *clock, and normalizes *tm. On failure, it returns an error number and leaves *clock and *tm unmodified. Errors time_make() shall fail if: ERANGE *tm does not represent a time representable by a time_t value. time_make() may fail if: EINVAL *tm does not represent a possible time in the timezone *tz. (For instance, a leap-forward interval.) Rationale and commentary This function is the generalization of the ISO C function mktime() and the BSD/tzcode function timegm(). The name and calling conventions of this function are inspired by Markus Kuhn's proposed xtime_prep(). struct xtime is a much more sophisticated and better-defined representation of time than time_t; this proposal is designed to be less ambitious while still leaving room for these future improvements. Following Kuhn, this function corrects a flaw of mktime()/timegm(). Those functions use the value (time_t)-1 to represent an error return status. However, this value can also be a correct translation of a struct tm representing the time December 31, 1969, 23:59:59 GMT (assuming POSIX time_t's). This function, instead, uses an out-of-band method to indicate error conditions, leaving the entire time_t space free to represent valid values. Given an impossible time value for the time zone (e.g. one that occurs during a leap-forward interval), implemenetations have a choice of failing and returning ERANGE, or normalizing *tm to a nearby valid time. Name time_breakup - derive a struct tm from a time_t, in a specified time zone. Summary #include <time.h> int time_breakup(struct tm *result, const time_t *clock, const struct timezone *tz); Description Fill in *result with the values corresponding to *clock in the time zone *tz. Return value time_breakup() returns 0, and fills in *result, always. Errors None. Rationale and commentary This function is the generalization of the ISO C functions localtime() and gmtime(), and the POSIX functions localtime_r() and gmtime_r(). It is inspired by Markus Kuhn's xtime_breakup(). The function assumes that a 'struct timezone' will be able to do something reasonable over the whole range of a time_t. This isn't necessarily true; it might be sensible to define an ERANGE error return value? This function omits the localtime side effect that it sets the value of the global variable char *tzname[2]. It's not clear how best to handle the BSD/tzcode tm_zone field of struct tm. This is defined as a char*, but since there is no tm_free() function, the data it points to cannot be dynamically allocated by time_breakup(). One possibility would be to have tm_zone point into data stored within 'struct tz', but then it would be invalidated when tz_free() was called. A second possibility would be to define tm_zone as char tm_zone[TZNAME_MAX], but this would break binary compatibility. A third possibility would be to deprecate tm_zone, and have time_breakup leave it NULL. Zone names can be obtained by calling strftime with a "%Z" format string (assuming POSIX strftime). Name strftime_z - generate a text representation of a time value, in a given time zone. Summary #include <time.h> size_t strftime_z(char * restrict buf, size_t maxsize, const char * restrict format, const struct tm * restrict timeptr, const struct timezone * restrict tz); Description strftime_z() formats the information from 'timeptr' into the buffer 'buf' according to the format specified by 'format' and the system locale. The format specified by 'format' is the same as that of strftime(). POSIX note: All POSIX extensions to strftime() apply to strftime_z() as well. Return value On successful completion, strftime_z fills in 'buf' and returns the number of bytes converted. On failure, strftime returns the number of bytes of buffer that would be required to fully perform the conversion (including the terminating NUL), and leaves 'buf' in an indeterminate state. Errors None. Rationale and commentary This function is a generalization of strftime(). The return value of this function has changed from strftime(), however. strftime() returns 0 if the buffer is not large enough. This function, instead, follows the example of ISO C 99's snprintf(), which allows an appropriately-sized buffer to be allocated in one step after a failure, rather than requiring a binary search. The error status can be easily checked by checking (ret <= maxbuf). The formatting strings of ISO C strftime() are not affected by the time zone, so this function is strictly speaking not necessary in a pure-C environment. POSIX strftime(), however, has the '%z' and '%Z' conversions, which require knowledge of the relevant time zone. It has been argued that this function is redundant, because time_breakup() could embed time zone information into struct tm (either in extension fields or private fields), and thus the standard POSIX strftime could suffice to convert struct tm's in a thread-safe way. However, this is only true for struct tm's created from time_breakup() or the mktime() family. Creation of struct tm values "by hand" is still fairly common, and a time zone specification is needed to print these. Name strftime_zl - generate a text representation of a time value, in a given time zone and locale. Summary #include <time.h> size_t strftime_zl(char * restrict buf, size_t maxsize, const char * restrict format, const struct tm * restrict timeptr, const struct timezone * restrict tz, const locale_t * restrict l); Description (This is an extension based on Ulrich Drepper's thread-aware locale proposal; see rationale.) strftime_z() formats the information from 'timeptr' into the buffer 'buf' according to the format specified by 'format' and the locale specified by 'l'. Other than the source of locale information, this is in all ways identical to strftime_z. Rationale and commentary This function follows Ulrich Drepper's thread-safe locale proposal; it is the combination of his strftime_l and strftime_z defined above. See <http://www.cygnus.com/~drepper/tllocale.ps.bz2> for details. This function should only be implemented if the rest of Drepper's proposal is as well. The _zl suffix is ugly. More natural would be to define a single function which takes all the necessary thread-safe data as arguments, but I don't want to force implementation of this proposal to be blocked on Drepper's. Thread-support functions Name pthread_settz -- set time zone object for the current POSIX thread. Synopsis #include <time.h> #include <pthread.h> int pthread_settz(const struct timezone *tz); Description (This function is only relevant in a POSIX system with the Threads option.) pthread_settz() sets the time zone object to be used for time functions called from the current POSIX thread. The time zone setting for all other threads remains the same. Once pthread_settz() has been called, all calls to the functions localtime(), localtime_r(), ctime(), ctime_r(), asctime(), asctime_r(), mktime(), strftime(), and strptime() in the thread from which it was called will use the specified time zone rather than the process-wide time zone. If tzuse() is called with a NULL pointer as its argument, the current thread will again use the global time zone object. Return value Upon successful completion, pthread_settz() returns a value of zero. Otherwise, an error code is returned to indicate an error. Errors pthread_settz() may fail if: ENOMEM Insufficient memory exists to store the time zone information for the thread. EAGAIN The system lacked the necessary resources to associate the time zone information with the thread. Rationale and commentary This function allows existing code which uses the ISO C and POSIX APIs to work correctly, unmodified, in a threaded environment. It would typically be implemented as a wrapper around pthread_setspecific(). It's not clear if a parallel pthread_gettz() is also needed. General rationale and commentary Thanks to many comments from the people of the tz@elsie.nci.nih.gov mailing list. Much inspiration for this work was drawn from Markus Kuhn's proposed extended time APIs for ISO C 200x, and from Ulrich Drepper's proposed thread-aware locale functions. Markus Kuhn's proposed time zone API defined an additional time zone manipulation function tz_jump(), which gets the next or previous discontinuity in a given time zone. This is a potentially useful function, but it was omitted here so as to keep the API definitions modest. (Additionally, it should probably wait on the proper definition of an extended time type, to avoid unnecessary redundancy.) Time zone specific versions of asctime[_r] and ctime[_r] were omitted, as they can be constructed trivially out of the functions defined here. A time zone specific version of strptime is not necessary. The only zone-aware function of strptime that I know of is the BSD extension to scan "%Z"; POSIX 200x does not define this, and it generally doesn't seem to work very well as zone abbreviations are ambiguous. (BSD strptime only recognizes the current local timezone, in standard and summer forms, and "GMT". Even this is not necessarily unambiguous: consider for example the Australian "EST" meaning both "Eastern Standard Time" and "Eastern Summer Time".) wcsftime_z and wcsftime_zl functions are needed, analogous to strftime_z and strftime_zl for wide strings. Their definitions are obvious analogies to the existing functions. Changes from Version 1: The time-zone creation and destruction functions were renamed from newtz() and freetz() to tz_prep() and tz_free(). This puts them in a name space, and aligns them with Markus Kuhn's functions. (These functions are slightly different from Kuhn's, though, in that they are defined to return errno values on errors.) tzdup() was dropped as not useful. mktime_z() and localtime_z() were renamed to time_make() and time_breakup(), by analogy with Kuhn's xtime_* functions. Zone-specific versions of asctime(), ctime(), and strptime() were dropped as unnecessary. The text was greatly clarified to make clear the distinctions between ISO C extensions, POSIX extensions, and rationale and commentary. The externally-visible tz_name elements of struct tz were dropped. The strftime_zl function was defined. -- Jonathan Lennox lennox@cs.columbia.edu