lib/libc/stdtime/tzfile.5

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