1TZFILE(5)                  Linux Programmer's Manual                 TZFILE(5)
2
3
4

NAME

6       tzfile - timezone information
7

DESCRIPTION

9       The timezone information files used by tzset(3) are typically found un‐
10       der a directory with a name like /usr/share/zoneinfo.  These files  use
11       the  format described in Internet RFC 8536.  Each file is a sequence of
12       8-bit bytes.  In a file, a binary integer is represented by a  sequence
13       of  one  or  more bytes in network order (bigendian, or high-order byte
14       first), with all bits significant, a signed binary  integer  is  repre‐
15       sented  using  two's complement, and a boolean is represented by a one-
16       byte binary integer that is either 0 (false) or 1 (true).   The  format
17       begins with a 44-byte header containing the following fields:
18
19       * The  magic  four-byte  ASCII sequence “TZif” identifies the file as a
20         timezone information file.
21
22       * A byte identifying the version of the file's format (as of 2017,  ei‐
23         ther an ASCII NUL, or “2”, or “3”).
24
25       * Fifteen bytes containing zeros reserved for future use.
26
27       * Six four-byte integer values, in the following order:
28
29         tzh_ttisutcnt
30                The  number of UT/local indicators stored in the file.  (UT is
31                Universal Time.)
32
33         tzh_ttisstdcnt
34                The number of standard/wall indicators stored in the file.
35
36         tzh_leapcnt
37                The number of leap seconds for which data entries  are  stored
38                in the file.
39
40         tzh_timecnt
41                The  number  of  transition  times  for which data entries are
42                stored in the file.
43
44         tzh_typecnt
45                The number of local time types  for  which  data  entries  are
46                stored in the file (must not be zero).
47
48         tzh_charcnt
49                The  number  of bytes of time zone abbreviation strings stored
50                in the file.
51
52       The above header is followed by the following fields, whose lengths de‐
53       pend on the contents of the header:
54
55       * tzh_timecnt  four-byte  signed integer values sorted in ascending or‐
56         der.  These values are written in network byte order.  Each  is  used
57         as  a transition time (as returned by time(2)) at which the rules for
58         computing local time change.
59
60       * tzh_timecnt one-byte unsigned integer values; each one but  the  last
61         tells  which  of the different types of local time types described in
62         the file is associated with the time period starting with  the  same-
63         indexed  transition  time  and continuing up to but not including the
64         next transition time.  (The last time type is present only  for  con‐
65         sistency  checking  with  the POSIX-style TZ string described below.)
66         These values serve as indices into the next field.
67
68       * tzh_typecnt ttinfo entries, each defined as follows:
69
70              struct ttinfo {
71                   int32_t        tt_utoff;
72                   unsigned char  tt_isdst;
73                   unsigned char  tt_desigidx;
74              };
75
76         Each structure is written as a four-byte  signed  integer  value  for
77         tt_utoff,  in  network byte order, followed by a one-byte boolean for
78         tt_isdst and a one-byte value for tt_desigidx.   In  each  structure,
79         tt_utoff  gives  the  number  of  seconds to be added to UT, tt_isdst
80         tells whether tm_isdst should be set by localtime(3) and  tt_desigidx
81         serves  as  an  index  into the array of time zone abbreviation bytes
82         that follow the ttinfo structure(s) in the file.  The tt_utoff  value
83         is  never  equal  to  -2**31, to let 32-bit clients negate it without
84         overflow.  Also, in realistic applications tt_utoff is in  the  range
85         [-89999,  93599]  (i.e., more than -25 hours and less than 26 hours);
86         this allows easy support by implementations that already support  the
87         POSIX-required range [-24:59:59, 25:59:59].
88
89       * tzh_leapcnt pairs of four-byte values, written in network byte order;
90         the first value of each pair gives the nonnegative time (as  returned
91         by time(2)) at which a leap second occurs; the second is a signed in‐
92         teger specifying the total number of leap seconds to be applied  dur‐
93         ing  the time period starting at the given time.  The pairs of values
94         are sorted in ascending order by time.  Each transition  is  for  one
95         leap  second,  either  positive or negative; transitions always sepa‐
96         rated by at least 28 days minus 1 second.
97
98       * tzh_ttisstdcnt standard/wall indicators, each stored  as  a  one-byte
99         boolean; they tell whether the transition times associated with local
100         time types were specified as standard  time  or  local  (wall  clock)
101         time.
102
103       * tzh_ttisutcnt UT/local indicators, each stored as a one-byte boolean;
104         they tell whether the transition times  associated  with  local  time
105         types were specified as UT or local time.  If a UT/local indicator is
106         set, the corresponding standard/wall indicator must also be set.
107
108       The standard/wall and UT/local indicators were designed for  transform‐
109       ing a TZif file's transition times into transitions appropriate for an‐
110       other time zone specified via a POSIX-style TZ string that lacks rules.
111       For example, when TZ="EET-2EEST" and there is no TZif file "EET-2EEST",
112       the idea was to adapt the transition times from a TZif  file  with  the
113       well-known  name "posixrules" that is present only for this purpose and
114       is a copy of the file "Europe/Brussels", a file  with  a  different  UT
115       offset.   POSIX  does not specify this obsolete transformational behav‐
116       ior, the default rules are installation-dependent, and  no  implementa‐
117       tion  is  known  to  support  this feature for timestamps past 2037, so
118       users  desiring  (say)  Greek  time  should  instead  specify   TZ="Eu‐
119       rope/Athens"   for   better   historical   coverage,  falling  back  on
120       TZ="EET-2EEST,M3.5.0/3,M10.5.0/4" if POSIX conformance is required  and
121       older timestamps need not be handled accurately.
122
123       The  localtime(3)  function normally uses the first ttinfo structure in
124       the file if either tzh_timecnt is zero or the  time  argument  is  less
125       than the first transition time recorded in the file.
126
127   Version 2 format
128       For version-2-format timezone files, the above header and data are fol‐
129       lowed by a second header and data,  identical  in  format  except  that
130       eight  bytes  are  used  for  each transition time or leap second time.
131       (Leap second counts remain four bytes.)  After the  second  header  and
132       data   comes  a  newline-enclosed,  POSIX-TZ-environment-variable-style
133       string for use in handling instants  after  the  last  transition  time
134       stored  in the file or for all instants if the file has no transitions.
135       The POSIX-style TZ string is empty (i.e., nothing between the newlines)
136       if  there  is  no POSIX representation for such instants.  If nonempty,
137       the POSIX-style TZ string must agree with the local time type after the
138       last  transition  time  if present in the eight-byte data; for example,
139       given the string “WET0WEST,M3.5.0,M10.5.0/3” then if a last  transition
140       time  is  in July, the transition's local time type must specify a day‐
141       light-saving time abbreviated “WEST” that  is  one  hour  east  of  UT.
142       Also,  if  there  is at least one transition, time type 0 is associated
143       with the time period from the indefinite past up to but  not  including
144       the earliest transition time.
145
146   Version 3 format
147       For  version-3-format timezone files, the POSIX-TZ-style string may use
148       two  minor  extensions  to  the  POSIX  TZ  format,  as  described   in
149       newtzset(3).   First,  the  hours  part  of its transition times may be
150       signed and range from -167 through 167 instead  of  the  POSIX-required
151       unsigned  values  from 0 through 24.  Second, DST is in effect all year
152       if it starts January 1 at 00:00 and ends December 31 at 24:00 plus  the
153       difference between daylight saving and standard time.
154
155   Interoperability considerations
156       Future changes to the format may append more data.
157
158       Version  1  files are considered a legacy format and should be avoided,
159       as they do not support transition times after the year  2038.   Readers
160       that only understand Version 1 must ignore any data that extends beyond
161       the calculated end of the version 1 data block.
162
163       Writers should generate a version 3 file if TZ  string  extensions  are
164       necessary  to  accurately model transition times.  Otherwise, version 2
165       files should be generated.
166
167       The sequence of time changes defined by the version 1 header  and  data
168       block should be a contiguous subsequence of the time changes defined by
169       the version 2+ header and data block, and by the footer.   This  guide‐
170       line  helps  obsolescent  version  1 readers agree with current readers
171       about timestamps within the contiguous subsequence.  It also lets writ‐
172       ers not supporting obsolescent readers use a tzh_timecnt of zero in the
173       version 1 data block to save space.
174
175       Time zone designations should consist of at least three (3) and no more
176       than  six  (6) ASCII characters from the set of alphanumerics, “-”, and
177       “+”.  This is for compatibility with POSIX requirements for  time  zone
178       abbreviations.
179
180       When reading a version 2 or 3 file, readers should ignore the version 1
181       header and data block except for the purpose of skipping over them.
182
183       Readers should calculate the total lengths  of  the  headers  and  data
184       blocks and check that they all fit within the actual file size, as part
185       of a validity check for the file.
186
187   Common interoperability issues
188       This section documents common  problems  in  reading  or  writing  TZif
189       files.   Most of these are problems in generating TZif files for use by
190       older readers.  The goals of this section are:
191
192       * to help TZif writers output files that avoid common pitfalls in older
193         or buggy TZif readers,
194
195       * to  help TZif readers avoid common pitfalls when reading files gener‐
196         ated by future TZif writers, and
197
198       * to help any future specification authors see what  sort  of  problems
199         arise when the TZif format is changed.
200
201       When  new  versions of the TZif format have been defined, a design goal
202       has been that a reader can successfully use a TZif  file  even  if  the
203       file  is of a later TZif version than what the reader was designed for.
204       When complete compatibility was not achieved, an attempt  was  made  to
205       limit  glitches  to rarely used timestamps, and to allow simple partial
206       workarounds in writers designed to  generate  new-version  data  useful
207       even  for  older-version  readers.   This  section attempts to document
208       these compatibility issues and workarounds,  as  well  as  to  document
209       other common bugs in readers.
210
211       Interoperability problems with TZif include the following:
212
213       * Some readers examine only version 1 data.  As a partial workaround, a
214         writer can output as much version 1 data  as  possible.   However,  a
215         reader  should  ignore version 1 data, and should use version 2+ data
216         even if the reader's native timestamps have only 32 bits.
217
218       * Some readers designed for version 2 might mishandle timestamps  after
219         a  version 3 file's last transition, because they cannot parse exten‐
220         sions to POSIX in the TZ-like string.  As  a  partial  workaround,  a
221         writer  can output more transitions than necessary, so that only far-
222         future timestamps are mishandled by version 2 readers.
223
224       * Some readers designed for version 2 do not support permanent daylight
225         saving  time, e.g., a TZ string “EST5EDT,0/0,J365/25” denoting perma‐
226         nent Eastern Daylight Time (-04).  As a partial workaround, a  writer
227         can  substitute  standard  time  for  the  next time zone east, e.g.,
228         “AST4” for permanent Atlantic Standard Time (-04).
229
230       * Some readers ignore the footer, and instead predict future timestamps
231         from  the time type of the last transition.  As a partial workaround,
232         a writer can output more transitions than necessary.
233
234       * Some readers do not use time type 0 for timestamps before  the  first
235         transition,  in  that  they  infer a time type using a heuristic that
236         does not always select time type  0.   As  a  partial  workaround,  a
237         writer can output a dummy (no-op) first transition at an early time.
238
239       * Some  readers  mishandle  timestamps before the first transition that
240         has a timestamp not less than  -2**31.   Readers  that  support  only
241         32-bit  timestamps  are  likely to be more prone to this problem, for
242         example, when they process 64-bit transitions only some of which  are
243         representable in 32 bits.  As a partial workaround, a writer can out‐
244         put a dummy transition at timestamp -2**31.
245
246       * Some readers mishandle a transition if its timestamp has the  minimum
247         possible  signed  64-bit  value.  Timestamps less than -2**59 are not
248         recommended.
249
250       * Some readers mishandle POSIX-style TZ strings  that  contain  “<”  or
251         “>”.   As  a  partial workaround, a writer can avoid using “<” or “>”
252         for time zone abbreviations containing only alphabetic characters.
253
254       * Many readers mishandle time zone abbreviations that contain non-ASCII
255         characters.  These characters are not recommended.
256
257       * Some readers may mishandle time zone abbreviations that contain fewer
258         than 3 or more than 6 characters, or that  contain  ASCII  characters
259         other  than alphanumerics, “-”, and “+”.  These abbreviations are not
260         recommended.
261
262       * Some readers mishandle TZif files that specify  daylight-saving  time
263         UT  offsets  that  are less than the UT offsets for the corresponding
264         standard time.  These readers do not support locations like  Ireland,
265         which    uses    the    equivalent    of    the   POSIX   TZ   string
266         “IST-1GMT0,M10.5.0,M3.5.0/1”, observing standard time (IST,  +01)  in
267         summer  and  daylight saving time (GMT, +00) in winter.  As a partial
268         workaround, a writer can output data for the equivalent of the  POSIX
269         TZ string “GMT0IST,M3.5.0/1,M10.5.0”, thus swapping standard and day‐
270         light saving time.  Although this workaround misidentifies which part
271         of the year uses daylight saving time, it records UT offsets and time
272         zone abbreviations correctly.
273
274       Some interoperability problems are reader bugs  that  are  listed  here
275       mostly as warnings to developers of readers.
276
277       * Some  readers do not support negative timestamps.  Developers of dis‐
278         tributed applications should keep this in mind if they need  to  deal
279         with pre-1970 data.
280
281       * Some  readers  mishandle  timestamps before the first transition that
282         has a nonnegative timestamp.  Readers that do  not  support  negative
283         timestamps are likely to be more prone to this problem.
284
285       * Some  readers  mishandle time zone abbreviations like “-08” that con‐
286         tain “+”, “-”, or digits.
287
288       * Some readers mishandle UT offsets that are  out  of  the  traditional
289         range  of -12 through +12 hours, and so do not support locations like
290         Kiritimati that are outside this range.
291
292       * Some readers mishandle UT offsets in the range  [-3599,  -1]  seconds
293         from  UT, because they integer-divide the offset by 3600 to get 0 and
294         then display the hour part as “+00”.
295
296       * Some readers mishandle UT offsets that are  not  a  multiple  of  one
297         hour, or of 15 minutes, or of 1 minute.
298

SEE ALSO

300       time(2), localtime(3), tzset(3), tzselect(8), zdump(8), zic(8).
301
302       Olson  A,  Eggert  P,  Murchison  K.  The  Time Zone Information Format
303       (TZif).  2019 Feb.  Internet RFC 8536 ⟨https://www.rfc-editor.org/info/
304       rfc8536⟩ doi:10.17487/RFC8536 ⟨https://doi.org/10.17487/RFC8536⟩.
305

COLOPHON

307       This  page  is  part of release 5.12 of the Linux man-pages project.  A
308       description of the project, information about reporting bugs,  and  the
309       latest     version     of     this    page,    can    be    found    at
310       https://www.kernel.org/doc/man-pages/.
311
312
313
314                                  2020-04-27                         TZFILE(5)
Impressum