<html lang="en">
<head>
<title>Theory and pragmatics of the tz code and data</title>
<meta charset="UTF-8">
</head>
<body>
<h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1>
<h3>Outline</h3>
<nav>
<ul>
<li><a href="#scope">Scope of the <code><abbr>tz</abbr></code>
database</a></li>
<li><a href="#naming">Names of time zone rulesets</a></li>
<li><a href="#abbreviations">Time zone abbreviations</a></li>
<li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code>
database</a></li>
<li><a href="#functions">Time and date functions</a></li>
<li><a href="#stability">Interface stability</a></li>
<li><a href="#calendar">Calendrical issues</a></li>
<li><a href="#planets">Time and time zones on other planets</a></li>
</ul>
</nav>
<section>
<h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2>
<p>
The <a
href="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code>
database</a> attempts to record the history and predicted future of
all computer-based clocks that track civil time.
It organizes <a href="tz-link.html">time zone and daylight saving time
data</a> by partitioning the world into <a
href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">regions</a>
whose clocks all agree about timestamps that occur after the <a
href="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a>
(1970-01-01 00:00:00 <a
href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr
title="Coordinated Universal Time">UTC</abbr></a>).
The database labels each such region with a notable location and
records all known clock transitions for that location.
Although 1970 is a somewhat-arbitrary cutoff, there are significant
challenges to moving the cutoff earlier even by a decade or two, due
to the wide variety of local practices before computer timekeeping
became prevalent.
</p>
<p>
Clock transitions before 1970 are recorded for each such location,
because most systems support timestamps before 1970 and could
misbehave if data entries were omitted for pre-1970 transitions.
However, the database is not designed for and does not suffice for
applications requiring accurate handling of all past times everywhere,
as it would take far too much effort and guesswork to record all
details of pre-1970 civil timekeeping.
Although some information outside the scope of the database is
collected in a file <code>backzone</code> that is distributed along
with the database proper, this file is less reliable and does not
necessarily follow database guidelines.
</p>
<p>
As described below, reference source code for using the
<code><abbr>tz</abbr></code> database is also available.
The <code><abbr>tz</abbr></code> code is upwards compatible with <a
href="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international
standard for <a
href="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems.
As of this writing, the current edition of POSIX is: <a
href="http://pubs.opengroup.org/onlinepubs/9699919799/"> The Open
Group Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018
Edition.
Because the database's scope encompasses real-world changes to civil
timekeeping, its model for describing time is more complex than the
standard and daylight saving times supported by POSIX.
A <code><abbr>tz</abbr></code> region corresponds to a ruleset that can
have more than two changes per year, these changes need not merely
flip back and forth between two alternatives, and the rules themselves
can change at times.
Whether and when a <code><abbr>tz</abbr></code> region changes its
clock, and even the region's notional base offset from UTC, are variable.
It does not always make sense to talk about a region's
"base offset", since it is not necessarily a single number.
</p>
</section>
<section>
<h2 id="naming">Names of time zone rulesets</h2>
<p>
Each <code><abbr>tz</abbr></code> region has a unique name that
corresponds to a set of time zone rules.
Inexperienced users are not expected to select these names unaided.
Distributors should provide documentation and/or a simple selection
interface that explains the names; for one example, see the
<code>tzselect</code> program in the <code><abbr>tz</abbr></code> code.
The <a href="http://cldr.unicode.org/">Unicode Common Locale Data
Repository</a> contains data that may be useful for other selection
interfaces.
</p>
<p>
The naming conventions attempt to strike a balance
among the following goals:
</p>
<ul>
<li>
Uniquely identify every region where clocks have agreed since 1970.
This is essential for the intended use: static clocks keeping local
civil time.
</li>
<li>
Indicate to experts where that region is.
</li>
<li>
Be robust in the presence of political changes.
For example, names of countries are ordinarily not used, to avoid
incompatibilities when countries change their name (e.g.,
Zaire→Congo) or when locations change countries (e.g., Hong
Kong from UK colony to China).
</li>
<li>
Be portable to a wide variety of implementations.
</li>
<li>
Use a consistent naming conventions over the entire world.
</li>
</ul>
<p>
Names normally have the form
<var>AREA</var><code>/</code><var>LOCATION</var>, where
<var>AREA</var> is the name of a continent or ocean, and
<var>LOCATION</var> is the name of a specific location within that
region.
North and South America share the same area, '<code>America</code>'.
Typical names are '<code>Africa/Cairo</code>',
'<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'.
Some names are further qualified to help avoid confusion; for example,
'<code>America/Indiana/Petersburg</code>' distinguishes Petersburg,
Indiana from other Petersburgs in America.
</p>
<p>
Here are the general guidelines used for
choosing <code><abbr>tz</abbr></code> region names,
in decreasing order of importance:
</p>
<ul>
<li>
Use only valid POSIX file name components (i.e., the parts of
names other than '<code>/</code>').
Do not use the file name components '<code>.</code>' and
'<code>..</code>'.
Within a file name component, use only <a
href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters,
'<code>.</code>', '<code>-</code>' and '<code>_</code>'.
Do not use digits, as that might create an ambiguity with <a
href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX
<code>TZ</code> strings</a>.
A file name component must not exceed 14 characters or start with
'<code>-</code>'.
E.g., prefer <code>Asia/Brunei</code> to
<code>Asia/Bandar_Seri_Begawan</code>.
Exceptions: see the discussion of legacy names below.
</li>
<li>
A name must not be empty, or contain '<code>//</code>', or
start or end with '<code>/</code>'.
</li>
<li>
Do not use names that differ only in case.
Although the reference implementation is case-sensitive, some
other implementations are not, and they would mishandle names
differing only in case.
</li>
<li>
If one name <var>A</var> is an initial prefix of another
name <var>AB</var> (ignoring case), then <var>B</var> must not
start with '<code>/</code>', as a regular file cannot have the
same name as a directory in POSIX.
For example, <code>America/New_York</code> precludes
<code>America/New_York/Bronx</code>.
</li>
<li>
Uninhabited regions like the North Pole and Bouvet Island
do not need locations, since local time is not defined there.
</li>
<li>
There should typically be at least one name for each <a
href="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr
title="International Organization for Standardization">ISO</abbr>
3166-1</a> officially assigned two-letter code for an inhabited
country or territory.
</li>
<li>
If all the clocks in a region have agreed since 1970,
do not bother to include more