]>
Commit | Line | Data |
---|---|---|
2d6c6dd1 | 1 | .\" %%%LICENSE_START(PUBLIC_DOMAIN) |
fea681da MK |
2 | .\" This file is in the public domain, so clarified as of |
3 | .\" 1996-06-05 by Arthur David Olson <arthur_david_olson@nih.gov>. | |
2d6c6dd1 | 4 | .\" %%%LICENSE_END |
2297bf0e MK |
5 | .\" |
6 | .\" @(#)tzfile.5 7.11 | |
7 | .\" | |
67d2c687 | 8 | .TH TZFILE 5 2015-05-07 "" "Linux Programmer's Manual" |
fea681da | 9 | .SH NAME |
5b0dc1ba | 10 | tzfile \- timezone information |
fea681da | 11 | .SH DESCRIPTION |
56c4cc36 MK |
12 | This page describes the structure of the timezone files used by |
13 | .BR tzset (3). | |
14 | These files are typically found under one of the directories | |
15 | .IR /usr/lib/zoneinfo | |
16 | or | |
17 | .IR /usr/share/zoneinfo . | |
18 | ||
7291261f MK |
19 | Timezone information files begin with a 44-byte header structured as follows: |
20 | .IP * 3 | |
21 | The magic four-byte sequence | |
22 | "TZif" identifying this as a | |
23 | timezone information file. | |
24 | .IP * | |
25 | A single character identifying the version of the file's format: | |
26 | either an ASCII NUL (\(aq\\0\(aq) or a \(aq2\(aq (\fB0x32\fP). | |
27 | .IP * | |
28 | Fifteen bytes containing zeros reserved for future use. | |
29 | .IP * | |
30 | Six four-byte values of type | |
8478ee02 | 31 | .IR long , |
324633ae | 32 | written in a "standard" byte order |
fea681da MK |
33 | (the high-order byte of the value is written first). |
34 | These values are, | |
35 | in order: | |
7291261f | 36 | .RS |
fea681da MK |
37 | .TP |
38 | .I tzh_ttisgmtcnt | |
39 | The number of UTC/local indicators stored in the file. | |
40 | .TP | |
41 | .I tzh_ttisstdcnt | |
42 | The number of standard/wall indicators stored in the file. | |
43 | .TP | |
44 | .I tzh_leapcnt | |
45 | The number of leap seconds for which data is stored in the file. | |
46 | .TP | |
47 | .I tzh_timecnt | |
48 | The number of "transition times" for which data is stored | |
49 | in the file. | |
50 | .TP | |
51 | .I tzh_typecnt | |
52 | The number of "local time types" for which data is stored | |
53 | in the file (must not be zero). | |
54 | .TP | |
55 | .I tzh_charcnt | |
5b0dc1ba | 56 | The number of characters of "timezone abbreviation strings" |
fea681da | 57 | stored in the file. |
7291261f | 58 | .RE |
fea681da MK |
59 | .PP |
60 | The above header is followed by | |
61 | .I tzh_timecnt | |
62 | four-byte values of type | |
9ff08aad | 63 | .IR long , |
fea681da | 64 | sorted in ascending order. |
324633ae | 65 | These values are written in "standard" byte order. |
fea681da MK |
66 | Each is used as a transition time (as returned by |
67 | .BR time (2)) | |
68 | at which the rules for computing local time change. | |
69 | Next come | |
70 | .I tzh_timecnt | |
71 | one-byte values of type | |
9ff08aad | 72 | .IR "unsigned char" ; |
324633ae | 73 | each one tells which of the different types of "local time" types |
fea681da MK |
74 | described in the file is associated with the same-indexed transition time. |
75 | These values serve as indices into an array of | |
76 | .I ttinfo | |
64fb5aed MK |
77 | structures (with |
78 | .I tzh_typecnt | |
79 | entries) that appear next in the file; | |
fea681da | 80 | these structures are defined as follows: |
a08ea57c | 81 | .in +4n |
fea681da MK |
82 | .sp |
83 | .nf | |
fea681da | 84 | struct ttinfo { |
7295b7ed MK |
85 | long tt_gmtoff; |
86 | int tt_isdst; | |
87 | unsigned int tt_abbrind; | |
fea681da | 88 | }; |
a08ea57c | 89 | .in |
fea681da MK |
90 | .fi |
91 | .sp | |
92 | Each structure is written as a four-byte value for | |
93 | .I tt_gmtoff | |
94 | of type | |
9ff08aad | 95 | .IR long , |
fea681da MK |
96 | in a standard byte order, followed by a one-byte value for |
97 | .I tt_isdst | |
98 | and a one-byte value for | |
99 | .IR tt_abbrind . | |
100 | In each structure, | |
101 | .I tt_gmtoff | |
102 | gives the number of seconds to be added to UTC, | |
103 | .I tt_isdst | |
104 | tells whether | |
105 | .I tm_isdst | |
106 | should be set by | |
107 | .BR localtime (3), | |
108 | and | |
109 | .I tt_abbrind | |
5b0dc1ba | 110 | serves as an index into the array of timezone abbreviation characters |
fea681da MK |
111 | that follow the |
112 | .I ttinfo | |
113 | structure(s) in the file. | |
114 | .PP | |
115 | Then there are | |
116 | .I tzh_leapcnt | |
117 | pairs of four-byte values, written in standard byte order; | |
118 | the first value of each pair gives the time | |
119 | (as returned by | |
120 | .BR time (2)) | |
121 | at which a leap second occurs; | |
122 | the second gives the | |
123 | .I total | |
124 | number of leap seconds to be applied after the given time. | |
125 | The pairs of values are sorted in ascending order by time. | |
126 | .PP | |
127 | Then there are | |
128 | .I tzh_ttisstdcnt | |
129 | standard/wall indicators, each stored as a one-byte value; | |
130 | they tell whether the transition times associated with local time types | |
131 | were specified as standard time or wall clock time, | |
5b0dc1ba MK |
132 | and are used when a timezone file is used in handling POSIX-style |
133 | timezone environment variables. | |
fea681da MK |
134 | .PP |
135 | Finally, there are | |
136 | .I tzh_ttisgmtcnt | |
137 | UTC/local indicators, each stored as a one-byte value; | |
138 | they tell whether the transition times associated with local time types | |
139 | were specified as UTC or local time, | |
5b0dc1ba MK |
140 | and are used when a timezone file is used in handling POSIX-style |
141 | timezone environment variables. | |
fea681da | 142 | .PP |
64fb5aed | 143 | .BR localtime (3) |
fea681da MK |
144 | uses the first standard-time |
145 | .I ttinfo | |
146 | structure in the file | |
147 | (or simply the first | |
148 | .I ttinfo | |
149 | structure in the absence of a standard-time structure) | |
150 | if either | |
151 | .I tzh_timecnt | |
152 | is zero or the time argument is less than the first transition time recorded | |
153 | in the file. | |
f09abf6d | 154 | .SS Version 2 format |
64fb5aed MK |
155 | For version-2-format timezone files, |
156 | the above header and data is followed by a second header and data, | |
157 | identical in format except that | |
f09abf6d SV |
158 | eight bytes are used for each transition time or leap-second time |
159 | (and that the version byte in the header record is | |
160 | \fB0x32\fP rather than \fB0x00\fP). | |
64fb5aed MK |
161 | After the second header and data comes a newline-enclosed, |
162 | POSIX-TZ-environment-variable-style string for use in handling instants | |
163 | after the last transition time stored in the file | |
164 | (with nothing between the newlines if there is no POSIX representation for | |
165 | such instants). | |
f09abf6d SV |
166 | .PP |
167 | The second section of the timezone file consists of another 44-byte header | |
168 | record, identical in structure to the one at the beginning of the file, | |
169 | except that it applies to the data that follows, | |
170 | which is also identical in structure | |
171 | to the first section of the timezone file, with the following differences: | |
172 | .IP * 3 | |
173 | The transition time values, after the header, are eight-byte values. | |
174 | .IP * | |
175 | In each leap second record, the leap second value is an eight-byte value. | |
176 | The accumulated leap second count is still a four-byte value. | |
177 | .PP | |
178 | In all cases, the eight-byte time values are given in | |
179 | the "standard" byte order, | |
180 | the high-order byte first. | |
181 | .SS POSIX timezone string | |
182 | The second eight-byte time value section is followed by an optional | |
183 | third section: | |
184 | a single ASCII newline character (\(aq\\n\(aq), | |
185 | then a text string followed by a second | |
186 | newline character. | |
187 | The text string is a POSIX timezone string, whose format is described in the | |
188 | .BR tzset (3) | |
189 | manual page. | |
190 | .PP | |
191 | The POSIX timezone string defines a rule for computing transition times | |
192 | that follow the last transition time explicitly specified in the timezone | |
193 | information file. | |
194 | .SS Summary of the timezone information file format | |
195 | \& | |
f09abf6d SV |
196 | .RS |
197 | .nf | |
198 | Four-byte value section | |
199 | (header version \fB0x00\fP or \fB0x32\fP) | |
200 | Header record | |
201 | Four-byte transition times | |
202 | Transition time index | |
203 | \fBttinfo\fP structures | |
204 | Timezone abbreviation array | |
205 | Leap second records | |
206 | Standard/Wall array | |
207 | UTC/Local array | |
208 | ||
209 | Eight-byte value section | |
210 | (only if first header version is \fB0x32\fP, | |
211 | the second header's version is also \fB0x32\fP) | |
212 | Header record | |
213 | Eight-byte transition times | |
214 | Transition time index | |
215 | \fBttinfo\fP structures | |
216 | Timezone abbreviation array | |
217 | Leap second records | |
218 | Standard/Wall array | |
219 | UTC/Local array | |
220 | ||
221 | Third section | |
222 | (optional, only in \fB0x32\fP version files) | |
223 | Newline character | |
224 | Timezone string | |
225 | Newline character | |
226 | .fi | |
227 | .RE | |
787dd4ad | 228 | .\" |
64fb5aed | 229 | .SH SEE ALSO |
b58ee47a MK |
230 | .BR ctime (3), |
231 | .BR tzset (3), | |
c80ce5bc | 232 | .BR tzselect (8), |
173fe7e7 | 233 | |
c80ce5bc | 234 | .I timezone/tzfile.h |
173fe7e7 | 235 | in the glibc source tree |