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