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