A proposal for thread-safe time zone information. Three functions manipulate a struct tz: Name newtz -- create a time zone object Synopsis #include struct tz* newtz(const char *tzname); Description The newtz() function creates a new time zone object, corresponding to the given time zone name. tzname is a pointer to a string representing the name of the allocated time zone. It has the same syntax as the "TZ" environment variable, both the POSIX forms and locally-defined symbolic names. The allocated struct tz contains all necessary information to represent times in the specified time zone. It has one externally-visible element: tz_name, an array of two ASCII strings containing the time zone abbreviations for standard and daylight time in the current time zone. struct tz { const char *tz_name[2]; (private data) }; If tzname is NULL, the returned struct tz describes the local wall-clock time, as best as it is known by the local system. 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".) 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. Return Value If the function call succeeds, the return value is a pointer to a time zone object, which should be released by a call to freetz(). If it fails, it returns NULL and sets errno. Errors The newtz() function shall fail if: ENOMEM Not enough memory is available to create the time zone object. ENOENT No known time zone corresponds to tzname. newtz() may also fail with other errno values if there is a problem with the system time zone database. Name freetz -- Free resources allocated for a time zone object Synopsis #include void freetz(struct tz* tzobj); Description The freetz() function frees the resources allocated for a time zone object returned by a call to newtz() or duptz(). 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. Return Value None. Errors None. Name duptz -- Duplicate a time zone object Synopsis #include struct tz* duptz(const struct tz* tzobj); Description The duptz() function can be used to duplicate an existing time zone object. A time zone object can be used at any time in multiple places but if the lifetime can possibly end before all uses are finished one has to create a duplicate. Return Value If the function succeeds it returns a pointer to a time zone object identical to the one represented by the pointer passed in tzobj. If it fails it returns NULL. Errors The duptz() function shall fail if: ENOMEM Not enough memory is available to create the duplicated time zone object. The duptz() function may fail if: EINVAL tzobj does not point to a valid time zone object. Modified time-zone-aware time manipulation functions: 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. (The return value's tm_zone value is set correctly, if the system has tm_zone.) char * ctime_z(const time_t *clock, char *buf, const struct tz *tz); Equivalent to ctime_r(), in the time zone represented by tz. char * asctime_z(const struct tm *tm, char *buf, const struct tz *tz); Equivalent to asctime_r(), in the time zone represented by tz. time_t mktime_z(struct tm* tm, const struct tz *tz); Equivalent to mktime() or timegm(), in the time zone represented by tz. size_t strftime_z(char *buf, size_t maxsize, const char *format, const struct tm* timeptr, const struct tz *tz); Equivalent to strftime(), in the time zone represented by tz. char * strptime_z(const char *buf, const char *format, struct tm *timeptr, const struct tz *tz); Equivalent to strptime(), in the time zone represented by tz. (This affects only the interpretation of the %Z format specifier.) Thread-support functions Name tzuse -- use time zone object in current thread. Synopsis #include void tzuse(const struct tz *tz); Description The tzuze() function is similar to the tzset() function, but it does not affect the global time zone. Instead it selects the new time zone only for the current thread. The time zone setting for all other threads remains the same. Once tzuse() has been called, all calls to the functions localtime(), localtime_r(), ctime(), ctime_r(), asctime(), asctime_r(), mktime(), strftime(), and strptime() in the current thread will use the current thread's define time zone. If tzuse() is called with a NULL pointer as its argument, the current thread will again use the global time zone object.