| blob | 50c2c707ea2fda0a302a8c13ed20790cb2d5e7e5 |
1 .\" $NetBSD: tzfile.5,v 1.20 2013/09/20 19:06:54 christos Exp $
2 .\"
3 .\" This file is in the public domain, so clarified as of
4 .\" 1996-06-05 by Arthur David Olson (arthur_david_olson@nih.gov).
5 .Dd September 20, 2013
6 .Dt TZFILE 5
7 .Os
8 .Sh NAME
9 .Nm tzfile
10 .Nd time zone information
11 .Sh SYNOPSIS
12 .In tzfile.h
13 .Sh DESCRIPTION
14 The time zone information files used by
15 .Xr tzset 3
16 begin with the magic characters
17 .Dq TZif
18 to identify them as time zone information files,
19 followed by a character identifying the version of the file's format
20 (as of 2013, either an ASCII NUL or a '2', or '3')
21 followed by fifteen bytes containing zeroes reserved for future use,
22 followed by six four-byte values of type
23 .Fa long ,
24 followed by six four-byte integer values written in a
25 .Dq standard
26 byte order (the high-order byte of the value is written first).
27 These values are, in order:
28 .Bl -tag -width XXXXXX -compact
29 .It Va tzh_ttisgmtcnt
30 The number of UT/local indicators stored in the file.
31 .It Va tzh_ttisstdcnt
32 The number of standard/wall indicators stored in the file.
33 .It Va tzh_leapcnt
34 The number of leap seconds for which data is stored in the file.
35 .It Va tzh_timecnt
36 The number of
37 .Dq transition times
38 for which data is stored in the file.
39 .It Va tzh_typecnt
40 The number of
41 .Dq local time types
42 for which data is stored in the file (must not be zero).
43 .It Va tzh_charcnt
44 The number of characters of "time zone abbreviation strings"
45 stored in the file.
46 .El
47 .Pp
48 The above header is followed by
49 .Va tzh_timecnt
50 four-byte signed integer values sorted in ascending order.
51 These values are written in
52 These values are written in
53 .Dq standard
54 byte order.
55 Each is used as a transition time (as returned by
56 .Xr time 3 )
57 at which the rules for computing local time change.
58 Next come
59 .Va tzh_timecnt
60 one-byte unsigned integer values;
61 each one tells which of the different types of
62 .Dq local time
63 types described in the file is associated with the same-indexed
64 transition time.
65 These values serve as indices into an array of
66 .Fa ttinfo
67 structures (with
68 .Va tzh_typecnt
69 entries) that appears next in the file;
70 these structures are defined as follows:
71 .Bd -literal
72 struct ttinfo {
73 int32_t tt_gmtoff;
74 unsigned char tt_isdst;
75 unsigned char tt_abbrind;
76 };
77 .Ed
78 Each structure is written as a four-byte signed integer value for
79 .Va tt_gmtoff
80 in a standard byte order, followed by a one-byte value for
81 .Va tt_isdst
82 and a one-byte value for
83 .Va tt_abbrind .
84 In each structure,
85 .Va tt_gmtoff
86 gives the number of seconds to be added to UT,
87 .Va tt_isdst
88 tells whether
89 .Va tm_isdst
90 should be set by
91 .Xr localtime 3
92 and
93 .Va tt_abbrind
94 serves as an index into the array of time zone abbreviation characters
95 that follow the
96 .Va ttinfo
97 structure(s) in the file.
98 .Pp
99 Then there are
100 .Va tzh_leapcnt
101 pairs of four-byte values, written in standard byte order;
102 the first value of each pair gives the time
103 (as returned by
104 .Xr time 3 )
105 at which a leap second occurs;
106 the second gives the
107 .Em total
108 number of leap seconds to be applied after the given time.
109 The pairs of values are sorted in ascending order by time.
110 .Pp
111 Then there are
112 .Va tzh_ttisstdcnt
113 standard/wall indicators, each stored as a one-byte value;
114 they tell whether the transition times associated with local time types
115 were specified as standard time or wall clock time,
116 and are used when a time zone file is used in handling POSIX-style
117 time zone environment variables.
118 .Pp
119 Finally there are
120 .Va tzh_ttisgmtcnt
121 UT/local indicators, each stored as a one-byte value;
122 they tell whether the transition times associated with local time types
123 were specified as UT or local time,
124 and are used when a time zone file is used in handling POSIX-style
125 time zone environment variables.
126 .Pp
127 .Xr localtime 3
128 uses the first standard-time
129 .Fa ttinfo
130 structure in the file
131 (or simply the first
132 .Fa ttinfo
133 structure in the absence of a standard-time structure)
134 if either
135 .Va tzh_timecnt
136 is zero or the time argument is less than the first transition time recorded
137 in the file.
138 .Pp
139 For version-2-format time zone files,
140 the above header and data are followed by a second header and data,
141 identical in format except that
142 eight bytes are used for each transition time or leap second time.
143 After the second header and data comes a newline-enclosed,
144 POSIX-TZ-environment-variable-style string for use in handling instants
145 after the last transition time stored in the file
146 (with nothing between the newlines if there is no POSIX representation for
147 such instants).
148 .Pp
149 For version-3-format time zone files, the POSIX-TZ-style string may
150 use two minor extensions to the POSIX TZ format, as described in
151 .Xr tzset 3 .
152 First, the hours part of its transition times may be signed and range from
153 \(mi167 through 167 instead of the POSIX-required unsigned values
154 from 0 through 24.
155 Second, DST is in effect all year if it starts
156 January 1 at 00:00 and ends December 31 at 24:00 plus the difference
157 between daylight saving and standard time.
158 .Pp
159 Future changes to the format may append more data.
160 .Sh SEE ALSO
161 .Xr ctime 3 ,
162 .Xr localtime 3 ,
163 .Xr time 3 ,
164 .Xr tzset 3 ,
165 .Xr zdump 8
166 .Xr zic 8
167 .\" @(#)tzfile.5 8.3
168 .\" This file is in the public domain, so clarified as of
169 .\" 1996-06-05 by Arthur David Olson.