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