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