- Generated by
1.9.8
|
BDE 4.14.0 Production release
|
Provide utilities for reading the Zoneinfo binary data format.
This component provides a struct, baltzo::ZoneinfoBinaryReader, containing utilities to read the binary data format of the Zoneinfo database from a bsl::istream and populate a baltzo::Zoneinfo object. The Zoneinfo database (also known as the Olson database or TZ database) records information about the world's time zones. It includes information such as the historic changes to the rules of local times, the time of transitions to daylight saving time, and corrections for leap seconds.
The Zoneinfo binary data is generated from a set of text-based rule file. A rule file may be compiled into multiple binary files, each describing one time zone. Information about the Zoneinfo database can be found online at http://www.iana.org/time-zones, including the time zone rules for the supported time zones, and source code for the zic compiler (for compiling those rules into the binary representation read by utility functions provided by this component).
A binary byte stream conforming to the Zoneinfo binary data format begins with a 44-byte header that describes the file. The structure of the header is shown below:
NOTE: All the numbers are 4-byte signed integers stored in big-endian format (higher order byte first).
The binary file has the following layout:
numTransitions number of 4-byte big-endian signed integers representing the transition times in POSIX time format (number of seconds elapsed since midnight UTC, January 1, 1970) sorted in ascending order. Each transition time represents a time at which the rule for computing the local time in that time zone changes. (NOTE: See "Version `2`" section for additional information.)numTransitions number of unsigned bytes. The byte at a given offset N stores the index of the local-time type entry (in the array of local-time types appearing next in the file) that corresponds to the transition at index N in the preceding sequence of transitions.numLocalTimeTypes local-time types, where each entry consist of:numAbbrevChar number of bytes containing the abbreviation strings of the local-time types of this time zone. Each abbreviation string ends with the '\0' character.numLeaps number of pairs of 4-byte signed big-endian integers (totaling 8 bytes). The first value of the pair is the POSIX time at which the leap seconds occur. The second value of the pair gives the number of leap seconds to be applied to times after the time defined by the first element of the pair. The pairs are stored in ascending order by time. (NOTE: See "Version `2`" section for additional information.)numIsGmt number of 1-byte booleans indicating whether the transition time for the local-time type with the corresponding index in the preceding array of local-time types was specified in UTC time or local time in the original rule file (from which the binary file was presumably compiled) (see next section for details).numIsStd number of 1-byte booleans indicating whether the transition time for the local-time type with the corresponding index in the preceding array of local-time types was specified in standard time or local time in the original rule file (from which the binary file was presumably compiled). Standard time refers to the time without adjustment for daylight-saving time whether daylight saving is in effect or not. (see next section for details).The isGmt and isStd boolean flags are not used by this component.
They indicate properties of the original rule file that were compiled into this binary representation. Each isGmt boolean flag indicates whether a transition time was originally specified as a UTC time or as a local time in the rule file. isStd indicates whether a transition time was originally specified as a standard time or local time. Note that all the transitions in the binary Zoneinfo representation are UTC times regardless of whether the original representation in the rule file was in local time. Also note that the value of numIsGmt and numIsStd should equal to numLocalTimeTypes, but for backward compatibility reasons, they may be set to zero.
Leap corrections are currently not supported by this component. Attempts to read a stream containing leap corrections will result in an error.
There is a slight difference between the mean length of a day and 86400 (24 * 60 * 60) seconds. Leap corrections are adjustments to the UTC time to account for this difference. In general, the time in a computer is updated through the network to account for leap seconds. Thus, it is not necessary to for this component to consider leap corrections for accurate time calculations.
Version 2 format of the Zoneinfo binary data can be divided into two parts. The first part contains the header and data described above. The second part contains header and data in the same format with the exception that eight bytes are used for transition time and leap correction time. The second header and data is followed by a formatted string used for handling time after the last transition time.
The version 2 format uses 8 bytes to store date-time values because the 4-byte values used in the version '\0' format provide a limited date range. The standard IANA data contains many transitions that are outside the range of representable values of a 4-byte offset (these transitions are ignored by the version '\0' format, which leads to inaccurate information for dates far in the past or future).
The version 2 format adds an additional optional POSIX TZ environment string, holding a text description of the local time transitions of the timezone, which can be used to compute transitions beyond the range represented in the binary compiled time zone data (see ftp://ftp.iana.org/tz/code/tzfile.h). It is similar (but not necessarily identical to) POSIX time zone description used for the TZ environment variable. String is found between two newline '
' characters immediately following the data. If two consecutive newline characters are found, no string has been specified.
This component will always load version 2 data if it is present in the supplied binary data.
Version 3 format of the Zoneinfo binary data is identical to the version 2 data described above. The version number of some files was incremented because the rules for the allowable range of values for the POSIX TZ environment string (found at the end of the data) were changed (see ftp://ftp.iana.org/tz/code/tzfile.h for more information).
Additional documentation for the Zoneinfo file format can be found at various places on the internet:
tzfile.5.txt. This file contains the most recent man-page text.In this section, we illustrate how this component can be used.
The following demonstrates how to read a byte stream in the Zoneinfo binary data format into a baltzo::Zoneinfo object. We start by creating Zoneinfo data in memory for "Asia/Bangkok", which was chosen due to its small size. Note that this data was generated by the zic compiler, which is publicly obtainable as part of the standard Zoneinfo distribution (see http://www.iana.org/time-zones):
Then, we load this data into a stream buffer.
Now, we read the inputStream using baltzo::ZoneinfoBinaryReader::read.
Finally, we write a description of the loaded Zoneinfo to the console.
The output of the preceding statement should look like:
1.9.8