Time zone and daylight saving rules are controlled by individual governments. They are sometimes changed with little notice, and their histories and planned futures are often recorded only fitfully. Here is a summary of attempts to organize and record relevant data in this area.
tz
database
The public-domain
time zone database contains code and data
that represent the history of local time
for many representative locations around the globe.
It is updated periodically to reflect changes made by political bodies
to time zone
boundaries and
daylight-saving
rules.
This database (often called zoneinfo
or
tz
)
is used by several implementations,
including
the
GNU
C Library (used in
GNU/Linux),
Android,
B2G
OS,
FreeBSD,
NetBSD,
OpenBSD,
Chromium OS,
Cygwin,
DJGPP,
MINIX,
MySQL,
webOS,
AIX,
BlackBerry 10,
iOS,
macOS,
Microsoft Windows,
OpenVMS,
Oracle Database, and
Oracle Solaris.
Each location in the database represents a region where all
clocks keeping local time have agreed since 1970.
Locations are identified by continent or ocean and then by the name of
the location, which is typically the largest city within the region.
For example, America/New_York
represents most of the US eastern time zone;
America/Phoenix
represents most of Arizona, which
uses mountain time without daylight saving time (DST);
America/Detroit
represents most of Michigan, which uses
eastern time but with different DST rules in 1975;
and other entries represent smaller regions like Starke County,
Indiana, which switched from central to eastern time in 1991
and switched back in 2006.
To use the database on an extended POSIX
implementation set the TZ
environment variable to the location's full name,
e.g., TZ="America/New_York"
.
Associated with each region is a history of offsets from Universal Time (UT), which is Greenwich Mean Time (GMT) with days beginning at midnight; for time stamps after 1960 this is more precisely Coordinated Universal Time (UTC). The database also records when daylight saving time was in use, along with some time zone abbreviations such as EST for Eastern Standard Time in the US.
tz
databaseThe following shell commands download the latest release's two tarballs to a GNU/Linux or similar host.
mkdir tzdb
cd tzdb
wget https://www.iana.org/time-zones/repository/tzcode-latest.tar.gz
wget https://www.iana.org/time-zones/repository/tzdata-latest.tar.gz
gzip -dc tzcode-latest.tar.gz | tar -xf -
gzip -dc tzdata-latest.tar.gz | tar -xf -
Alternatively, the following shell commands download the same release in a single-tarball format containing extra data useful for regression testing:
wget https://www.iana.org/time-zones/repository/tzdb-latest.tar.lz
lzip -dc tzdb-latest.tar.lz | tar -xf -
These commands use convenience links to the latest release
of the tz
database hosted by the
Time Zone Database website
of the Internet Assigned Numbers
Authority (IANA).
Older releases are in files named
tzcodeV.tar.gz
,
tzdataV.tar.gz
, and
tzdb-V.tar.lz
,
where V
is the version.
Since 1996, each version has been a four-digit year followed by
lower-case letter (a through z,
then za through zz, then zza
through zzz, and so on).
Since version 2016h, each release has contained a text file named
"version" whose first (and currently only) line is the version.
The releases are also available in an
FTP directory via a
less-secure protocol .
Alternatively, a development repository of code and data can be retrieved from GitHub via the shell command:
git clone https://github.com/eggert/tz
Since version 2012e, each release has been tagged in development repositories. Untagged commits are less well tested and probably contain more errors.
After obtaining the code and data files, see the
README
file for what to do next.
The code lets you compile the tz
source files into
machine-readable binary files, one for each location. It also lets
you read a tz
binary file and interpret time stamps for that
location.
tz
database
The tz
code and data
are by no means authoritative. If you find errors, please
send changes to tz@iana.org
,
the time zone mailing list. You can also subscribe to it
and browse the archive of old
messages.
If your government plans to change its time zone boundaries or
daylight saving rules, inform tz@iana.org
well in
advance, as this will coordinate updates to many cell phones,
computers, and other devices around the world. With
less than a year's notice there is a good chance that some
computer-based clocks will operate incorrectly after the change, due
to delays in propagating updates to software and data. The shorter
the notice, the more likely clock problems will arise; see "On
the Timing of Time Zone Changes" for examples.
Changes to the tz
code and data are often
propagated to clients via operating system updates, so
client tz
data can often be corrected by
applying these updates. With GNU/Linux and similar systems, if your
maintenance provider has not yet adopted the
latest tz
data, you can often short-circuit
the process by tailoring the generic instructions in
the tz README
file and installing the latest
data yourself. System-specific instructions for installing the
latest tz
data have also been published
for AIX,
ICU,
IBM
and Oracle
Java, Joda-Time, MySQL,
and Noda Time (see below).
Sources for the tz
database are
UTF-8
text files
with lines terminated by LF,
which can be modified by common text editors such
as GNU Emacs,
gedit, and
vim.
Specialized source-file editing can be done via the
Sublime
zoneinfo package for Sublime Text and the VSCode
zoneinfo extension for Visual
Studio Code.
For further information about updates, please see Procedures for Maintaining the Time Zone Database (Internet RFC 6557). More detail can be found in Theory and pragmatics of the tz code and data.
tz
databasetz
database format.tz
databaseThese are listed roughly in ascending order of complexity and fanciness.
TZ
values directly.tz
datatz
compilerstz
source into iCalendar-compatible VTIMEZONE files.
Vzic is freely
available under the GNU
General Public License (GPL).parse_olson
that compiles
tz
source into Perl
modules. It is part of the Perl DateTime Project, which is freely
available under both the GPL and the Perl Artistic
License. DateTime::TimeZone also contains a script
tests_from_zdump
that generates test cases for each clock
transition in the tz
database.tz
source
and from CLDR data
(mentioned below)
into an ICU-specific format.
ICU is freely available under a
BSD-style license.tz
source into the format used by
Oracle Java.java.time
API can be supplemented by ThreeTen-Extra,
which is freely available under a BSD-style license.org.joda.time.tz.ZoneInfoCompiler
that compiles
tz
source into a binary format. It inspired
Java 8 java.time
, which its users should migrate to once
they can assume Java 8 or later. It is available under the Apache License.net.time4j.tool.TimezoneRepositoryCompiler
that compiles
tz
source into a binary format. Time4J is
available under the GNU Lesser
General Public License (LGPL).tz
source into
Julia. It is freely available
under the MIT license.tz
source into
Python.
It is freely available under a BSD-style license.tz
source into
Ruby.
It is freely available under the MIT license.tz
source into a time
zone repository whose format
is either proprietary or an XML-encoded
representation.tz
source into text files, along with a runtime that can read those
files. Tcl is freely available under a BSD-style
license.tz
binary file readerstz
binary file reader.
This library is freely available under the LGPL
and is widely used in GNU/Linux systems.tz
binary file reader written in C that
creates a GTimeZone
object representing sets
of UT offsets.
It is freely available under the LGPL.baltzo::TimeZoneUtil
component contains a C++
implementation of a binary file reader. It is freely available under
the Apache License.tz
binary file reader written in Java.
It is freely available under the LGPL.tz
binary file reader.tz
binary file reader written in Perl.
It is freely available under the same terms as Perl
(dual GPL and Artistic license).tz
binary data into
JSON-format data suitable for use
in its JavaScript library for time zone conversion. Dates before 1970
are not supported.tz
binary data. It is freely
available under a BSD-style license.tz
-based time zone softwaretz
database in a
Go-specific format.tz
data and CLDR
data (mentioned below) used by
Windows Runtime
classes such as DateTimeFormatter
.
Exploring
Windows Time Zones with System.TimeZoneInfo
describes
the older, proprietary method of Microsoft Windows 2000 and later,
which stores time zone data in the
Windows Registry. The
Zone →
Tzid table or XML
file of the CLDR data maps proprietary zone IDs
to tz
names.
tz
database in a
Java-specific format.tz
releases. The Basic version
is free.tz
contributors.tztab
(4) format.Geographical boundaries between time zone regions are available from several geolocation services and other sources.
tz
regions.
Its code is freely available under the MIT license, and
its data entries are freely available under the
Open Data Commons
Open Database License. The maps' borders appear to be quite accurate.tz
regions. This includes
tz_world, a shapefile
for all the world's regions. These maps are no longer maintained and
are superseded by the Timezone Boundary Builder.tz
regions include:
tz
code and data support leap seconds
via an optional "right
" configuration, as opposed to the
default "posix
" configuration.tz
"posix
" configuration, is supported by
the NTP reference implementation, and is used by major
cloud service providers.tz
database contains English abbreviations for many time stamps;
unfortunately some of these abbreviations were merely the database maintainers'
inventions, and these have been removed when possible.TZ
environment variable uses the opposite convention.
For example, one might use TZ="JST-9"
and
TZ="HST10"
for Japan and Hawaii, respectively. If the
tz
database is available, it is usually better to use
settings like TZ="Asia/Tokyo"
and
TZ="Pacific/Honolulu"
instead, as this should avoid
confusion, handle old time stamps better, and insulate you better from
any future changes to the rules. One should never set
POSIX TZ
to a value like
"GMT-9"
, though, since this would incorrectly imply that
local time is nine hours ahead of UT and the time zone
is called "GMT".