[tz] [PROPOSED] Use “TZif” for binary files.

Paul Eggert eggert at cs.ucla.edu
Mon May 21 02:16:46 UTC 2018


Also, mention tzdist-bis and draft-murchison-tzdist-tzif-00.
---
 Makefile     |  8 +++++---
 NEWS         |  2 ++
 theory.html  | 15 ++++++++-------
 tz-link.html | 37 ++++++++++++++++++++++---------------
 zic.c        |  2 +-
 5 files changed, 38 insertions(+), 26 deletions(-)

diff --git a/Makefile b/Makefile
index 91c30f7..06f7fd6 100644
--- a/Makefile
+++ b/Makefile
@@ -109,6 +109,8 @@ LIBDIR = $(TOPDIR)/$(USRDIR)/lib
 # Types to try, as an alternative to time_t.  int64_t should be first.
 TIME_T_ALTERNATIVES = int64_t int32_t uint32_t uint64_t
 
+# What kind of TZif data files to generate.
+# (TZif is the binary time zone data format that zic generates.)
 # If you want only POSIX time, with time values interpreted as
 # seconds since the epoch (not counting leap seconds), use
 #	REDO=		posix_only
@@ -129,7 +131,7 @@ TIME_T_ALTERNATIVES = int64_t int32_t uint32_t uint64_t
 
 REDO=		posix_right
 
-# To install data in text form that has all the information of the binary data,
+# To install data in text form that has all the information of the TZif data,
 # (optionally incorporating leap second information), use
 #	TZDATA_TEXT=	tzdata.zi leapseconds
 # To install text data without leap second information (e.g., because
@@ -357,7 +359,7 @@ ZIC=		$(zic) $(ZFLAGS)
 
 ZFLAGS=
 
-# How to use zic to install tz binary files.
+# How to use zic to install TZif files.
 
 ZIC_INSTALL=	$(ZIC) -d '$(DESTDIR)$(TZDIR)' $(LEAPSECONDS)
 
@@ -605,7 +607,7 @@ INSTALLARGS = \
  YEARISTYPE='$(YEARISTYPE)' \
  ZIC='$(ZIC)'
 
-# 'make install_data' installs one set of tz binary files.
+# 'make install_data' installs one set of TZif files.
 install_data:	zic leapseconds yearistype tzdata.zi
 		$(ZIC_INSTALL) tzdata.zi
 
diff --git a/NEWS b/NEWS
index a91f00a..6bd89c2 100644
--- a/NEWS
+++ b/NEWS
@@ -25,6 +25,8 @@ Unreleased, experimental changes
     The latter restriction makes room for future extensions (a
     possibility noted by Tom Lane).
 
+    The name "TZif" is now used for the tz binary data format.
+
   Changes to build procedure
 
     New 'make' target 'rearguard_tarballs' to build the rearguard
diff --git a/theory.html b/theory.html
index d5055b2..f2409f4 100644
--- a/theory.html
+++ b/theory.html
@@ -932,15 +932,16 @@ an older <code>zic</code>.
   <li>
     <p>
     The <code>TZ</code> environment variable is used in generating
-    the name of a binary file from which time-related information is read
+    the name of a file from which time-related information is read
     (or is interpreted à la POSIX); <code>TZ</code> is no longer
-    constrained to be a three-letter time zone
-    abbreviation followed by a number of hours and an optional three-letter
-    daylight time zone abbreviation.
+    constrained to be a string containing abbreviations
+    and numeric data as described <a href="#POSIX">above</a>.
+    The file's format is <dfn><abbr>TZif</abbr></dfn>,
+    a time zone information format that contains binary data.
     The daylight saving time rules to be used for a
     particular <code><abbr>tz</abbr></code> region are encoded in the
-    binary file; the format of the file
-    allows U.S., Australian, and other rules to be encoded, and
+    <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>,
+    Australian, and other rules to be encoded, and
     allows for situations where more than two time zone
     abbreviations are used.
     </p>
@@ -950,7 +951,7 @@ an older <code>zic</code>.
     might cause "old" programs (that expect <code>TZ</code> to have a
     certain form) to operate incorrectly; consideration was given to using
     some other environment variable (for example, <code>TIMEZONE</code>)
-    to hold the string used to generate the binary file's name.
+    to hold the string used to generate the <abbr>TZif</abbr> file's name.
     In the end, however, it was decided to continue using
     <code>TZ</code>: it is widely used for time zone purposes;
     separately maintaining both <code>TZ</code>
diff --git a/tz-link.html b/tz-link.html
index b8b7944..77e06d2 100644
--- a/tz-link.html
+++ b/tz-link.html
@@ -143,8 +143,10 @@ more errors.</p>
 After obtaining the code and data files, see the
 <code>README</code> file for what to do next.
 The code lets you compile the <code><abbr>tz</abbr></code> source files into
-machine-readable binary files, one for each location. It also lets
-you read a <code><abbr>tz</abbr></code> binary file and interpret time stamps for that
+machine-readable binary files, one for each location. The binary files
+are in a special time zone information format (<dfn><abbr>TZif</abbr></dfn>).
+The code also lets
+you read a <abbr>TZif</abbr> file and interpret time stamps for that
 location.</p>
 <h2 id="changes">Changes to the <code><abbr>tz</abbr></code> database</h2>
 <p>
@@ -272,12 +274,17 @@ href="https://tools.ietf.org/html/rfc7808">TZDIST</a>
 (Internet <abbr>RFC</abbr> 7808), a time zone data distribution service,
 along with <a href="https://tools.ietf.org/html/rfc7809">CalDAV</a>
 (Internet <abbr>RFC</abbr> 7809), a calendar access protocol for
-transferring time zone data by reference. The draft <a
+transferring time zone data by reference.
+The <a href="https://www.ietf.org/mailman/listinfo/tzdist-bis">tzdist-bis
+mailing list</a> discusses two Internet drafts: <a
 id="TZDIST-Geolocate"
 href="https://tools.ietf.org/html/draft-murchison-tzdist-geolocate-01">TZDIST
 Geolocate Extension</a> lets a client determine its time zone region
 from its geographic location using a <a
-href="https://tools.ietf.org/html/rfc5870">'geo' URI</a>.</li>
+href="https://tools.ietf.org/html/rfc5870">'geo' URI</a>, and
+<a href="https://tools.ietf.org/html/draft-murchison-tzdist-tzif-00">The
+Time Zone Information Format (<abbr>TZif</abbr>)</a> specifies the format of
+<abbr>TZif</abbr> data.</li>
 <li>The <a href="https://tools.ietf.org/html/rfc5545">
 Internet Calendaring and Scheduling Core Object Specification
 (iCalendar)</a> (Internet <abbr>RFC</abbr> 5445)
@@ -426,35 +433,35 @@ source into text files, along with a runtime that can read those
 files. Tcl is freely available under a <abbr>BSD</abbr>-style
 license.</li>
 </ul>
-<h2 id="binary">Other <code><abbr>tz</abbr></code> binary file readers</h2>
+<h2 id="TZif">Other <abbr>TZif</abbr> readers</h2>
 <ul>
 <li>The <a
 href="https://www.gnu.org/software/libc/"><abbr>GNU</abbr> C
 Library</a>
 has an independent, thread-safe implementation of
-a <code><abbr>tz</abbr></code> binary file reader.
+a <abbr>TZif</abbr> file reader.
 This library is freely available under the LGPL
 and is widely used in <abbr>GNU</abbr>/Linux systems.</li>
 <li><a href="https://www.gnome.org">GNOME</a>'s
 <a href="https://developer.gnome.org/glib/">GLib</a> has
-a <code><abbr>tz</abbr></code> binary file reader written in C that
+a <abbr>TZif</abbr> file reader written in C that
 creates a <code>GTimeZone</code> object representing sets
 of <abbr>UT</abbr> offsets.
 It is freely available under the <abbr>LGPL</abbr>.</li>
 <li>The
 <a href="https://github.com/bloomberg/bde/wiki">BDE Standard Library</a>'s
 <code>baltzo::TimeZoneUtil</code> component contains a C++
-implementation of a binary file reader. It is freely available under
+implementation of a <abbr>TZif</abbr> file reader. It is freely available under
 the Apache License.</li>
 <li><a href="https://github.com/google/cctz">CCTZ</a> is a simple C++
 library that translates between <abbr>UT</abbr> and civil time and
-can read binary files. It is freely available under the Apache
+can read <abbr>TZif</abbr> files. It is freely available under the Apache
 License.</li>
 <li><a href="http://bmsi.com/java/#TZ">ZoneInfo.java</a>
-is a <code><abbr>tz</abbr></code> binary file reader written in Java.
+is a <abbr>TZif</abbr> file reader written in Java.
 It is freely available under the <abbr>LGPL</abbr>.</li>
 <li><a href="https://github.com/derickr/timelib">Timelib</a> is a C
-library that reads tz binary files and converts
+library that reads <abbr>TZif</abbr> files and converts
 time stamps from one time zone or format to another.
 It is used by <a href="https://secure.php.net"><abbr
 title="PHP: Hypertext Preprocessor">PHP</abbr></a>,
@@ -465,23 +472,23 @@ It is freely available under the <abbr>MIT</abbr> license.</li>
 JavaScript library that supports date arithmetic that is time zone
 aware. It is freely available under the <abbr>MIT</abbr> license.</li>
 <li>Tcl, mentioned <a href="#Tcl">above</a>, also contains a
-<code><abbr>tz</abbr></code> binary file reader.</li>
+<abbr>TZif</abbr> file reader.</li>
 <li><a href="http://search.cpan.org/perldoc?DateTime::TimeZone::Tzfile">
 DateTime::TimeZone::Tzfile</a>
-is a <code><abbr>tz</abbr></code> binary file reader written in Perl.
+is a <abbr>TZif</abbr> file reader written in Perl.
 It is freely available under the same terms as Perl
 (dual <abbr>GPL</abbr> and Artistic license).</li>
 <li>The
 public-domain <a href="https://github.com/dbaron/tz.js">tz.js</a>
 library contains a Python tool that
-converts <code><abbr>tz</abbr></code> binary data into
+converts <abbr>TZif</abbr> data into
 <abbr>JSON</abbr>-format data suitable for use
 in its JavaScript library for time zone conversion. Dates before 1970
 are not supported.</li>
 <li>The <a
 href="https://hackage.haskell.org/package/timezone-olson">timezone-olson</a>
 package contains <a href="https://www.haskell.org">Haskell</a> code that
-parses and uses <code><abbr>tz</abbr></code> binary data. It is freely
+parses and uses <abbr>TZif</abbr> data. It is freely
 available under a <abbr>BSD</abbr>-style license.</li>
 </ul>
 <h2 id="software">Other <code><abbr>tz</abbr></code>-based time zone software</h2>
diff --git a/zic.c b/zic.c
index 0c4c384..f1d0bf3 100644
--- a/zic.c
+++ b/zic.c
@@ -184,7 +184,7 @@ static bool	yearistype(zic_t year, const char * type);
 enum { PERCENT_Z_LEN_BOUND = sizeof "+995959" - 1 };
 
 /* If true, work around a bug in Qt 5.6.1 and earlier, which mishandles
-   tz binary files whose POSIX-TZ-style strings contain '<'; see
+   TZif files whose POSIX-TZ-style strings contain '<'; see
    QTBUG-53071 <https://bugreports.qt.io/browse/QTBUG-53071>.  This
    workaround will no longer be needed when Qt 5.6.1 and earlier are
    obsolete, say in the year 2021.  */
-- 
2.7.4



More information about the tz mailing list