Accuracy of the `tz` database

The tz database is not authoritative, and it surely has errors. Corrections are welcome and encouraged; see the file CONTRIBUTING. Users requiring authoritative data should consult national standards bodies and the references cited in the database's comments.

Errors in the tz database arise from many sources:

The tz database predicts future timestamps, and current predictions will be incorrect after future governments change the rules. For example, if today someone schedules a meeting for 13:00 next October 1, Casablanca time, and tomorrow Morocco changes its daylight saving rules, software can mess up after the rule change if it blithely relies on conversions made before the change.
The pre-1970 entries in this database cover only a tiny sliver of how clocks actually behaved; the vast majority of the necessary information was lost or never recorded. Thousands more tz regions would be needed if the tz database's scope were extended to cover even just the known or guessed history of standard time; for example, the current single entry for France would need to split into dozens of entries, perhaps hundreds. And in most of the world even this approach would be misleading due to widespread disagreement or indifference about what times should be observed. In her 2015 book The Global Transformation of Time, 1870–1950, Vanessa Ogle writes "Outside of Europe and North America there was no system of time zones at all, often not even a stable landscape of mean times, prior to the middle decades of the twentieth century". See: Timothy Shenk, Booked: A Global History of Time. Dissent 2015-12-17.
Most of the pre-1970 data entries come from unreliable sources, often astrology books that lack citations and whose compilers evidently invented entries when the true facts were unknown, without reporting which entries were known and which were invented. These books often contradict each other or give implausible entries, and on the rare occasions when they are checked they are typically found to be incorrect.
For the UK the tz database relies on years of first-class work done by Joseph Myers and others; see "History of legal time in Britain". Other countries are not done nearly as well.
Sometimes, different people in the same city maintain clocks that differ significantly. Historically, railway time was used by railroad companies (which did not always agree with each other), church-clock time was used for birth certificates, etc. More recently, competing political groups might disagree about clock settings. Often this is merely common practice, but sometimes it is set by law. For example, from 1891 to 1911 the UT offset in France was legally UT +00:09:21 outside train stations and UT +00:04:21 inside. Other examples include Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and Ürümqi to this day.
Although a named location in the tz database stands for the containing region, its pre-1970 data entries are often accurate for only a small subset of that region. For example, Europe/London stands for the United Kingdom, but its pre-1847 times are valid only for locations that have London's exact meridian, and its 1847 transition to GMT is known to be valid only for the L&NW and the Caledonian railways.
The tz database does not record the earliest time for which a tz region's data entries are thereafter valid for every location in the region. For example, Europe/London is valid for all locations in its region after GMT was made the standard time, but the date of standardization (1880-08-02) is not in the tz database, other than in commentary. For many tz regions the earliest time of validity is unknown.
The tz database does not record a region's boundaries, and in many cases the boundaries are not known. For example, the tz region America/Kentucky/Louisville represents a region around the city of Louisville, the boundaries of which are unclear.
Changes that are modeled as instantaneous transitions in the tz database were often spread out over hours, days, or even decades.
Even if the time is specified by law, locations sometimes deliberately flout the law.
Early timekeeping practices, even assuming perfect clocks, were often not specified to the accuracy that the tz database requires.
Sometimes historical timekeeping was specified more precisely than what the tz code can handle. For example, from 1909 to 1937 Netherlands clocks were legally Amsterdam Mean Time (estimated to be UT +00:19:32.13), but the tz code cannot represent the fractional second. In practice these old specifications were rarely if ever implemented to subsecond precision.
Even when all the timestamp transitions recorded by the tz database are correct, the tz rules that generate them may not faithfully reflect the historical rules. For example, from 1922 until World War II the UK moved clocks forward the day following the third Saturday in April unless that was Easter, in which case it moved clocks forward the previous Sunday. Because the tz database has no way to specify Easter, these exceptional years are entered as separate tz Rule lines, even though the legal rules did not change.
The tz database models pre-standard time using the proleptic Gregorian calendar and local mean time, but many people used other calendars and other timescales. For example, the Roman Empire used the Julian calendar, and Roman timekeeping had twelve varying-length daytime hours with a non-hour-based system at night.
Early clocks were less reliable, and data entries do not represent clock error.
The tz database assumes Universal Time (UT) as an origin, even though UT is not standardized for older timestamps. In the tz database commentary, UT denotes a family of time standards that includes Coordinated Universal Time (UTC) along with other variants such as UT1 and GMT, with days starting at midnight. Although UT equals UTC for modern timestamps, UTC was not defined until 1960, so commentary uses the more-general abbreviation UT for timestamps that might predate 1960. Since UT, UT1, etc. disagree slightly, and since pre-1972 UTC seconds varied in length, interpretation of older timestamps can be problematic when subsecond accuracy is needed.
Civil time was not based on atomic time before 1972, and we do not know the history of earth's rotation accurately enough to map SI seconds to historical solar time to more than about one-hour accuracy. See: Stephenson FR, Morrison LV, Hohenkerk CY. Measurement of the Earth's rotation: 720 BC to AD 2015. Proc Royal Soc A. 2016 Dec 7;472:20160404. Also see: Espenak F. Uncertainty in Delta T (ΔT).
The relationship between POSIX time (that is, UTC but ignoring leap seconds) and UTC is not agreed upon after 1972. Although the POSIX clock officially stops during an inserted leap second, at least one proposed standard has it jumping back a second instead; and in practice POSIX clocks more typically either progress glacially during a leap second, or are slightly slowed while near a leap second.
The tz database does not represent how uncertain its information is. Ideally it would contain information about when data entries are incomplete or dicey. Partial temporal knowledge is a field of active research, though, and it is not clear how to apply it here.

In short, many, perhaps most, of the tz database's pre-1970 and future timestamps are either wrong or misleading. Any attempt to pass the tz database off as the definition of time should be unacceptable to anybody who cares about the facts. In particular, the tz database's LMT offsets should not be considered meaningful, and should not prompt creation of tz regions merely because two locations differ in LMT or transitioned to standard time at different dates.

Time and date functions

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-related files. To do this, you may need to compile the time zone compiler '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

In POSIX, time display in a process is controlled by the environment variable TZ. Unfortunately, the POSIX TZ string takes a form that is hard to describe and is error-prone in practice. Also, POSIX TZ strings cannot deal with daylight saving time rules not based on the Gregorian calendar (as in Iran), or with situations where more than two time zone abbreviations or UT offsets are used in an area.

The POSIX TZ string takes the following form:

stdoffset[dst[offset][,date[/time],date[/time]]]

where:

std and dst
are 3 or more characters specifying the standard and daylight saving time (DST) zone names. Starting with POSIX.1-2001, std and dst may also be in a quoted form like '<+09>'; this allows "+" and "-" in the names.

offset
is of the form '[±]hh:[mm[:ss]]' and specifies the offset west of UT. 'hh' may be a single digit; 0≤hh≤24. The default DST offset is one hour ahead of standard time.

date[/time],date[/time]
specifies the beginning and end of DST. If this is absent, the system supplies its own ruleset for DST, and its rules can differ from year to year; typically US DST rules are used.

time
takes the form 'hh:[mm[:ss]]' and defaults to 02:00. This is the same format as the offset, except that a leading '+' or '-' is not allowed.

date
takes one of the following forms:

Jn (1≤n≤365)
origin-1 day number not counting February 29

n (0≤n≤365)
origin-0 day number counting February 29 if present

Mm.n.d (0[Sunday]≤d≤6[Saturday], 1≤n≤5, 1≤m≤12)
for the dth day of week n of month m of the year, where week 1 is the first week in which day d appears, and '5' stands for the last week in which day d appears (which may be either the 4th or 5th week). Typically, this is the only useful form; the n and Jn forms are rarely used.

Here is an example POSIX TZ string for New Zealand after 2007. It says that standard time (NZST) is 12 hours ahead of UT, and that daylight saving time (NZDT) is observed from September's last Sunday at 02:00 until April's first Sunday at 03:00:
```
TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'
```
This POSIX TZ string is hard to remember, and mishandles some timestamps before 2008. With this package you can use this instead:
```
TZ='Pacific/Auckland'
```
POSIX does not define the exact meaning of TZ values like "EST5EDT". Typically the current US DST rules are used to interpret such values, but this means that the US DST rules are compiled into each program that does time conversion. This means that when US time conversion rules change (as in the United States in 1987), all programs that do time conversion must be recompiled to ensure proper results.
The TZ environment variable is process-global, which makes it hard to write efficient, thread-safe applications that need access to multiple time zone rulesets.
In POSIX, there is no tamper-proof way for a process to learn the system's best idea of local wall clock. (This is important for applications that an administrator wants used only at certain times – without regard to whether the user has fiddled the TZ environment variable. While an administrator can "do everything in UT" to get around the problem, doing so is inconvenient and precludes handling daylight saving time shifts - as might be required to limit phone calls to off-peak hours.)
POSIX provides no convenient and efficient way to determine the UT offset and time zone abbreviation of arbitrary timestamps, particularly for tz regions that do not fit into the POSIX model.
POSIX requires that systems ignore leap seconds.
The tz code attempts to support all the time_t implementations allowed by POSIX. The time_t type represents a nonnegative count of seconds since 1970-01-01 00:00:00 UTC, ignoring leap seconds. In practice, time_t is usually a signed 64- or 32-bit integer; 32-bit signed time_t values stop working after 2038-01-19 03:14:07 UTC, so new implementations these days typically use a signed 64-bit integer. Unsigned 32-bit integers are used on one or two platforms, and 36-bit and 40-bit integers are also used occasionally. Although earlier POSIX versions allowed time_t to be a floating-point type, this was not supported by any practical systems, and POSIX.1-2013 and the tz code both require time_t to be an integer type.

Extensions to POSIX in the `tz` code

The TZ environment variable is used in generating the name of a binary file from which time-related information is read (or is interpreted à la POSIX); TZ is no longer constrained to be a three-letter time zone abbreviation followed by a number of hours and an optional three-letter daylight time zone abbreviation. The daylight saving time rules to be used for a particular tz region are encoded in the binary file; the format of the file allows U.S., Australian, and other rules to be encoded, and allows for situations where more than two time zone abbreviations are used.

It was recognized that allowing the TZ environment variable to take on values such as 'America/New_York' might cause "old" programs (that expect TZ to have a certain form) to operate incorrectly; consideration was given to using some other environment variable (for example, TIMEZONE) to hold the string used to generate the binary file's name. In the end, however, it was decided to continue using TZ: it is widely used for time zone purposes; separately maintaining both TZ and TIMEZONE seemed a nuisance; and systems where "new" forms of TZ might cause problems can simply use TZ values such as "EST5EDT" which can be used both by "new" programs (à la POSIX) and "old" programs (as zone names and offsets).
The code supports platforms with a UT offset member in struct tm, e.g., tm_gmtoff.
The code supports platforms with a time zone abbreviation member in struct tm, e.g., tm_zone.
Functions tzalloc, tzfree, localtime_rz, and mktime_z for more-efficient thread-safe applications that need to use multiple time zone rulesets. The tzalloc and tzfree functions allocate and free objects of type timezone_t, and localtime_rz and mktime_z are like localtime_r and mktime with an extra timezone_t argument. The functions were inspired by NetBSD.
A function tzsetwall has been added to arrange for the system's best approximation to local wall clock time to be delivered by subsequent calls to localtime. Source code for portable applications that "must" run on local wall clock time should call tzsetwall; if such code is moved to "old" systems that do not provide tzsetwall, you will not be able to generate an executable program. (These functions also arrange for local wall clock time to be used if tzset is called – directly or indirectly – and there is no TZ environment variable; portable applications should not, however, rely on this behavior since it is not the way SVR2 systems behave.)
Negative time_t values are supported, on systems where time_t is signed.
These functions can account for leap seconds, thanks to Bradley White.

POSIX features no longer needed

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:

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.
The POSIX 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.
The 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 disambiguation 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

The 7th Edition UNIX timezone function is not present in this package; it is impossible to reliably map timezone's arguments (a "minutes west of GMT" value and a "daylight saving time in effect" flag) to a time zone abbreviation, and we refuse to guess. Programs that in the past used the timezone function may now examine localtime(&clock)->tm_zone (if TM_ZONE is defined) or tzname[localtime(&clock)->tm_isdst] (if HAVE_TZNAME is defined) to learn the correct time zone abbreviation to use.
The 4.2BSD gettimeofday function is not used in this package. This formerly let users obtain the current UTC offset and DST flag, but this functionality was removed in later versions of BSD.
In SVR2, time conversion fails for near-minimum or near-maximum time_t values when doing conversions for places that do not use UT. This package takes care to do these conversions correctly. A comment in the source code tells how to get compatibly wro