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