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