33d9f9e08d
Changes affecting API
The 'zic' command now outputs a dummy transition when far-future
data can't be summarized using a TZ string, and uses a 402-year
window rather than a 400-year window. For the current data, this
affects only the Asia/Tehran file. It does not affect any of the
time stamps that this file represents, so zdump outputs the same
information as before. (Thanks to Andrew Main (Zefram).)
The 'date' command has a new '-r' option, which lets you specify
the integer time to display, a la FreeBSD.
The 'tzselect' command has two new options '-c' and '-n', which lets you
select a zone based on latitude and longitude.
The 'zic' command's '-v' option now warns about constructs that
require the new version-3 binary file format. (Thanks to Arthur
David Olson for the suggestion.)
Support for floating-point time_t has been removed.
It was always dicey, and POSIX no longer requires it.
(Thanks to Eric Blake for suggesting to the POSIX committee to
remove it, and thanks to Alan Barrett, Clive D.W. Feather, Andy
Heninger, Arthur David Olson, and Alois Treindl, for reporting
bugs and elucidating some of the corners of the old floating-point
implementation.)
The signatures of 'offtime', 'timeoff', and 'gtime' have been
changed back to the old practice of using 'long' to represent UT
offsets. This had been inadvertently and mistakenly changed to
'int_fast32_t'. (Thanks to Christos Zoulos.)
The code avoids undefined behavior on integer overflow in some
more places, including gmtime, localtime, mktime and zdump.
Changes affecting the zdump utility
zdump now outputs "UT" when referring to Universal Time, not "UTC".
"UTC" does not make sense for time stamps that predate the introduction
of UTC, whereas "UT", a more-generic term, does. (Thanks to Steve Allen
for clarifying UT vs UTC.)
Data changes affecting behavior of tzselect and similar programs
Country code BQ is now called the more-common name "Caribbean Netherlands"
rather than the more-official "Bonaire, St Eustatius & Saba".
Remove from zone.tab the names America/Montreal, America/Shiprock,
and Antarctica/South_Pole, as they are equivalent to existing
same-country-code zones for post-1970 time stamps. The data for
these names are unchanged, so the names continue to work as before.
Changes affecting code internals
zic -c now runs way faster on 64-bit hosts when given large numbers.
zic now uses vfprintf to avoid allocating and freeing some memory.
tzselect now computes the list of continents from the data,
rather than have it hard-coded.
Minor changes pacify GCC 4.7.3 and GCC 4.8.1.
Changes affecting the build procedure
The 'leapseconds' file is now generated automatically from a
new file 'leap-seconds.list', which is a copy of
<ftp://time.nist.gov/pub/leap-seconds.list>.
A new source file 'leapseconds.awk' implements this.
The goal is simplification of the future maintenance of 'leapseconds'.
When building the 'posix' or 'right' subdirectories, if the
subdirectory would be a copy of the default subdirectory, it is
now made a symbolic link if that is supported. This saves about
2 MB of file system space.
The links America/Shiprock and Antarctica/South_Pole have been
moved to the 'backward' file. This affects only nondefault builds
that omit 'backward'.
Changes affecting documentation and commentary
Changes to the 'tzfile' man page
It now mentions that the binary file format may be extended in
future versions by appending data.
It now refers to the 'zdump' and 'zic' man pages.
Changes to the 'zic' man page
It lists conditions that elicit a warning with '-v'.
It says that the behavior is unspecified when duplicate names
are given, or if the source of one link is the target of another.
Its examples are updated to match the latest data.
The definition of white space has been clarified slightly.
(Thanks to Michael Deckers.)
Changes to the 'Theory' file
There is a new section about the accuracy of the tz database,
describing the many ways that errors can creep in, and
explaining why so many of the pre-1970 time stamps are wrong or
misleading (thanks to Steve Allen, Lester Caine, and Garrett
Wollman for discussions that contributed to this).
The 'Theory' file describes LMT better (this follows a
suggestion by Guy Harris).
It refers to the 2013 edition of POSIX rather than the 2004 edition.
It's mentioned that excluding 'backward' should not affect the
other data, and it suggests at least one zone.tab name per
inhabited country (thanks to Stephen Colebourne).
Some longstanding restrictions on names are documented, e.g.,
'America/New_York' precludes 'America/New_York/Bronx'.
It gives more reasons for the 1970 cutoff.
It now mentions which time_t variants are supported, such as
signed integer time_t. (Thanks to Paul Goyette for reporting
typos in an experimental version of this change.)
(Thanks to Philip Newton for correcting typos in these changes.)
Documentation and commentary is more careful to distinguish UT in
general from UTC in particular. (Thanks to Steve Allen.)
Add a better source for the Zurich 1894 transition.
(Thanks to Pierre-Yves Berger.)
Update shapefile citations in tz-link.htm. (Thanks to Guy Harris.)
170 lines
5.1 KiB
Groff
170 lines
5.1 KiB
Groff
.\" $NetBSD: tzfile.5,v 1.20 2013/09/20 19:06:54 christos Exp $
|
|
.\"
|
|
.\" This file is in the public domain, so clarified as of
|
|
.\" 1996-06-05 by Arthur David Olson (arthur_david_olson@nih.gov).
|
|
.Dd September 20, 2013
|
|
.Dt TZFILE 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm tzfile
|
|
.Nd time zone information
|
|
.Sh SYNOPSIS
|
|
.In tzfile.h
|
|
.Sh DESCRIPTION
|
|
The time zone information files used by
|
|
.Xr tzset 3
|
|
begin with the magic characters
|
|
.Dq TZif
|
|
to identify them as time zone information files,
|
|
followed by a character identifying the version of the file's format
|
|
(as of 2013, either an ASCII NUL or a '2', or '3')
|
|
followed by fifteen bytes containing zeroes reserved for future use,
|
|
followed by six four-byte values of type
|
|
.Fa long ,
|
|
followed by six four-byte integer values written in a
|
|
.Dq standard
|
|
byte order (the high-order byte of the value is written first).
|
|
These values are, in order:
|
|
.Bl -tag -width XXXXXX -compact
|
|
.It Va tzh_ttisgmtcnt
|
|
The number of UT/local indicators stored in the file.
|
|
.It Va tzh_ttisstdcnt
|
|
The number of standard/wall indicators stored in the file.
|
|
.It Va tzh_leapcnt
|
|
The number of leap seconds for which data is stored in the file.
|
|
.It Va tzh_timecnt
|
|
The number of
|
|
.Dq transition times
|
|
for which data is stored in the file.
|
|
.It Va tzh_typecnt
|
|
The number of
|
|
.Dq local time types
|
|
for which data is stored in the file (must not be zero).
|
|
.It Va tzh_charcnt
|
|
The number of characters of "time zone abbreviation strings"
|
|
stored in the file.
|
|
.El
|
|
.Pp
|
|
The above header is followed by
|
|
.Va tzh_timecnt
|
|
four-byte signed integer values sorted in ascending order.
|
|
These values are written in
|
|
These values are written in
|
|
.Dq standard
|
|
byte order.
|
|
Each is used as a transition time (as returned by
|
|
.Xr time 3 )
|
|
at which the rules for computing local time change.
|
|
Next come
|
|
.Va tzh_timecnt
|
|
one-byte unsigned integer values;
|
|
each one tells which of the different types of
|
|
.Dq local time
|
|
types described in the file is associated with the same-indexed
|
|
transition time.
|
|
These values serve as indices into an array of
|
|
.Fa ttinfo
|
|
structures (with
|
|
.Va tzh_typecnt
|
|
entries) that appears next in the file;
|
|
these structures are defined as follows:
|
|
.Bd -literal
|
|
struct ttinfo {
|
|
int32_t tt_gmtoff;
|
|
unsigned char tt_isdst;
|
|
unsigned char tt_abbrind;
|
|
};
|
|
.Ed
|
|
Each structure is written as a four-byte signed integer value for
|
|
.Va tt_gmtoff
|
|
in a standard byte order, followed by a one-byte value for
|
|
.Va tt_isdst
|
|
and a one-byte value for
|
|
.Va tt_abbrind .
|
|
In each structure,
|
|
.Va tt_gmtoff
|
|
gives the number of seconds to be added to UT,
|
|
.Va tt_isdst
|
|
tells whether
|
|
.Va tm_isdst
|
|
should be set by
|
|
.Xr localtime 3
|
|
and
|
|
.Va tt_abbrind
|
|
serves as an index into the array of time zone abbreviation characters
|
|
that follow the
|
|
.Va ttinfo
|
|
structure(s) in the file.
|
|
.Pp
|
|
Then there are
|
|
.Va tzh_leapcnt
|
|
pairs of four-byte values, written in standard byte order;
|
|
the first value of each pair gives the time
|
|
(as returned by
|
|
.Xr time 3 )
|
|
at which a leap second occurs;
|
|
the second gives the
|
|
.Em total
|
|
number of leap seconds to be applied after the given time.
|
|
The pairs of values are sorted in ascending order by time.
|
|
.Pp
|
|
Then there are
|
|
.Va tzh_ttisstdcnt
|
|
standard/wall indicators, each stored as a one-byte value;
|
|
they tell whether the transition times associated with local time types
|
|
were specified as standard time or wall clock time,
|
|
and are used when a time zone file is used in handling POSIX-style
|
|
time zone environment variables.
|
|
.Pp
|
|
Finally there are
|
|
.Va tzh_ttisgmtcnt
|
|
UT/local indicators, each stored as a one-byte value;
|
|
they tell whether the transition times associated with local time types
|
|
were specified as UT or local time,
|
|
and are used when a time zone file is used in handling POSIX-style
|
|
time zone environment variables.
|
|
.Pp
|
|
.Xr localtime 3
|
|
uses the first standard-time
|
|
.Fa ttinfo
|
|
structure in the file
|
|
(or simply the first
|
|
.Fa ttinfo
|
|
structure in the absence of a standard-time structure)
|
|
if either
|
|
.Va tzh_timecnt
|
|
is zero or the time argument is less than the first transition time recorded
|
|
in the file.
|
|
.Pp
|
|
For version-2-format time zone files,
|
|
the above header and data are followed by a second header and data,
|
|
identical in format except that
|
|
eight bytes are used for each transition time or leap second time.
|
|
After the second header and data comes a newline-enclosed,
|
|
POSIX-TZ-environment-variable-style string for use in handling instants
|
|
after the last transition time stored in the file
|
|
(with nothing between the newlines if there is no POSIX representation for
|
|
such instants).
|
|
.Pp
|
|
For version-3-format time zone files, the POSIX-TZ-style string may
|
|
use two minor extensions to the POSIX TZ format, as described in
|
|
.Xr tzset 3 .
|
|
First, the hours part of its transition times may be signed and range from
|
|
\(mi167 through 167 instead of the POSIX-required unsigned values
|
|
from 0 through 24.
|
|
Second, DST is in effect all year if it starts
|
|
January 1 at 00:00 and ends December 31 at 24:00 plus the difference
|
|
between daylight saving and standard time.
|
|
.Pp
|
|
Future changes to the format may append more data.
|
|
.Sh SEE ALSO
|
|
.Xr ctime 3 ,
|
|
.Xr localtime 3 ,
|
|
.Xr time 3 ,
|
|
.Xr tzset 3 ,
|
|
.Xr zdump 8
|
|
.Xr zic 8
|
|
.\" @(#)tzfile.5 8.3
|
|
.\" This file is in the public domain, so clarified as of
|
|
.\" 1996-06-05 by Arthur David Olson.
|