From 240c8d6e29e3069d72bec323910ee6800a6155d1 Mon Sep 17 00:00:00 2001
From: Paul Eggert
The tz code contains time and date functions that are upwards
compatible with those of POSIX.
+Code compatible with this package is already
+part of many platforms,
+where the primary use of this package
+is to update obsolete time zone rule tables.
+To do this, you may need to compile the time zone compiler
+'
-POSIX has the following properties and limitations.
-
@@ -772,9 +779,8 @@ POSIX has the following properties and limitations.
to be an integer type.
-These are the extensions that have been made to the POSIX functions:
-
@@ -814,14 +820,6 @@ These are the extensions that have been made to the POSIX functions:
-Points of interest to folks with other systems:
+POSIX and ISO C define some APIs that are vestigial: they are not
+needed, and are relics of a too-simple model that does not suffice to
+handle many real-world timestamps. Although the tz code supports these
+vestigial APIs for backwards compatibility, they should be avoided in
+portable applications. The vestigial APIs are:
+zic
' supplied with this package instead of using
+the system 'zic
', since the format
+of zic
's input is occasionally extended, and a
+platform may still be shipping an older zic
.
POSIX properties and limitations
-Extensions to POSIX in the tz code
+
+struct tm
, e.g., tm_zone
.
daylight
- and timezone
variables are no longer needed.
- (These variables are defined and set by tzset
;
- however, their values will not be used
- by localtime
.)
-tzalloc
, tzfree
,
localtime_rz
, and mktime_z
for
more-efficient thread-safe applications that need to use
@@ -855,23 +853,47 @@ These are the extensions that have been made to the POSIX functions:
These functions can account for leap seconds, thanks to Bradley White.
POSIX features no longer needed
+
+zic
' supplied with this package instead of using
- the system 'zic
', since the format
- of zic
's input is occasionally extended, and a
- platform may still be shipping an older zic
.
+ The POSIX tzname
variable does not suffice and is no
+ longer needed. To get a timestamp's time zone abbreviation,
+ consult the tm_zone
member if available; otherwise,
+ use strftime
's "%Z"
conversion
+ specification.
+ daylight
and timezone
+ variables do not suffice and are no longer needed. To get a
+ timestamp's UT offset, consult the tm_gmtoff
member
+ if available; otherwise, subtract values returned
+ by localtime
and gmtime
using the rules
+ of the Gregorian calendar, or
+ use strftime
's "%z"
conversion
+ specification if a string like "+0900" suffices.
tm_isdst
member is almost never needed and most of
+ its uses should be discouraged in favor of the abovementioned
+ APIs. Although it can still be used in arguments to
+ mktime
to disambiguate timestamps near a DST
+ transition when the clock jumps back, this disambguation does not
+ work when standard time itself jumps back, which can occur when a
+ location changes to a time zone with a lesser UT offset.
+ Other portability notes
+
+
-timezone
function is not
present in this package;
it's impossible to reliably map timezone's arguments (a "minutes west
@@ -898,8 +920,7 @@ Points of interest to folks with other systems:
A comment in the source code tells how to get compatibly wrong
results.
STD_INSPIRED
is defined
should, at this point, be looked on primarily as food for thought. They are
@@ -907,9 +928,8 @@ not in any sense "standard compatible" – some are not, in fact,
specified in any standard. They do, however, represent responses of
various authors to
standardization proposals.
-
+ +