lib/libc/stdtime/tzfile.5

   1 .\" $FreeBSD: src/lib/libc/stdtime/tzfile.5,v 1.8.2.2 2001/08/17 15:42:43 ru Exp $
   2 .Dd October 19, 2008
   3 .Dt TZFILE 5
   4 .Os
   5 .Sh NAME
   6 .Nm tzfile
   7 .Nd timezone information
   8 .Sh SYNOPSIS
   9 .Fd #include \&"/usr/src/lib/libc/stdtime/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 2005, either an ASCII
  19 .Dv NUL
  20 or a
  21 .Sq Li 2 )
  22 followed by fifteen bytes containing zeroes reserved for future use,
  23 followed by six four-byte values of type
  24 .Vt long ,
  25 written in a
  26 .Dq standard
  27 byte order
  28 (the high-order byte of the value is written first).
  29 These values are,
  30 in order:
  31 .Pp
  32 .Bl -tag -compact -width tzh_ttisstdcnt
  33 .It Va tzh_ttisgmtcnt
  34 The number of UTC/local indicators stored in the file.
  35 .It Va tzh_ttisstdcnt
  36 The number of standard/wall indicators stored in the file.
  37 .It Va tzh_leapcnt
  38 The number of leap seconds for which data is stored in the file.
  39 .It Va tzh_timecnt
  40 The number of
  41 .Dq transition times
  42 for which data is stored
  43 in the file.
  44 .It Va tzh_typecnt
  45 The number of
  46 .Dq local time types
  47 for which data is stored
  48 in the file (must not be zero).
  49 .It Va tzh_charcnt
  50 The number of characters of
  51 .Dq time zone abbreviation strings
  52 stored in the file.
  53 .El
  54 .Pp
  55 The above header is followed by
  56 .Va tzh_timecnt
  57 four-byte values of type
  58 .Fa long ,
  59 sorted in ascending order.
  60 These values are written in
  61 .Dq standard
  62 byte order.
  63 Each is used as a transition time (as returned by
  64 .Xr time 3 )
  65 at which the rules for computing local time change.
  66 Next come
  67 .Va tzh_timecnt
  68 one-byte values of type
  69 .Fa "unsigned char" ;
  70 each one tells which of the different types of
  71 .Dq local time
  72 types
  73 described in the file is associated with the same-indexed transition time.
  74 These values serve as indices into an array of
  75 .Fa ttinfo
  76 structures (with
  77 .Va tzh_typecnt
  78 entries) that appears next in the file;
  79 these structures are defined as follows:
  80 .Bd -literal -offset indent
  81 struct ttinfo {
  82         long    tt_gmtoff;
  83         int     tt_isdst;
  84         unsigned int    tt_abbrind;
  85 };
  86 .Ed
  87 .Pp
  88 Each structure is written as a four-byte value for
  89 .Va tt_gmtoff
  90 of type
  91 .Fa long ,
  92 in a standard byte order, followed by a one-byte value for
  93 .Va tt_isdst
  94 and a one-byte value for
  95 .Va tt_abbrind .
  96 In each structure,
  97 .Va tt_gmtoff
  98 gives the number of seconds to be added to UTC,
  99 .Li tt_isdst
 100 tells whether
 101 .Li tm_isdst
 102 should be set by
 103 .Xr localtime 3
 104 and
 105 .Va tt_abbrind
 106 serves as an index into the array of time zone abbreviation characters
 107 that follow the
 108 .Li ttinfo
 109 structure(s) in the file.
 110 .Pp
 111 Then there are
 112 .Va tzh_leapcnt
 113 pairs of four-byte values, written in standard byte order;
 114 the first value of each pair gives the time
 115 (as returned by
 116 .Xr time 3 )
 117 at which a leap second occurs;
 118 the second gives the
 119 .Em total
 120 number of leap seconds to be applied after the given time.
 121 The pairs of values are sorted in ascending order by time.
 122 .Pp
 123 Then there are
 124 .Va tzh_ttisstdcnt
 125 standard/wall indicators, each stored as a one-byte value;
 126 they tell whether the transition times associated with local time types
 127 were specified as standard time or wall clock time,
 128 and are used when a time zone file is used in handling POSIX-style
 129 time zone environment variables.
 130 .Pp
 131 Finally there are
 132 .Va tzh_ttisgmtcnt
 133 UTC/local indicators, each stored as a one-byte value;
 134 they tell whether the transition times associated with local time types
 135 were specified as UTC or local time,
 136 and are used when a time zone file is used in handling POSIX-style
 137 time zone environment variables.
 138 .Pp
 139 .Nm localtime
 140 uses the first standard-time
 141 .Li ttinfo
 142 structure in the file
 143 (or simply the first
 144 .Li ttinfo
 145 structure in the absence of a standard-time structure)
 146 if either
 147 .Li tzh_timecnt
 148 is zero or the time argument is less than the first transition time recorded
 149 in the file.
 150 .Pp
 151 For version-2-format time zone files,
 152 the above header and data is followed by a second header and data,
 153 identical in format except that
 154 eight bytes are used for each transition time or leap second time.
 155 After the second header and data comes a newline-enclosed,
 156 POSIX-TZ-environment-variable-style string for use in handling instants
 157 after the last transition time stored in the file
 158 (with nothing between the newlines if there is no POSIX representation for
 159 such instants).
 160 .Sh SEE ALSO
 161 .Xr ctime 3 ,
 162 .Xr time2posix 3 ,
 163 .Xr zic 8
 164 .\" This file is in the public domain, so clarified as of
 165 .\" 1996-06-05 by Arthur David Olson.