lib/libc/time/tzfile.5

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