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