aboutsummaryrefslogtreecommitdiff
path: root/theory.html
diff options
context:
space:
mode:
Diffstat (limited to 'theory.html')
-rw-r--r--theory.html77
1 files changed, 72 insertions, 5 deletions
diff --git a/theory.html b/theory.html
index e0b32335867d..7af7cb23c657 100644
--- a/theory.html
+++ b/theory.html
@@ -21,6 +21,7 @@
database</a></li>
<li><a href="#functions">Time and date functions</a></li>
<li><a href="#stability">Interface stability</a></li>
+ <li><a href="#leapsec">Leap seconds</a></li>
<li><a href="#calendar">Calendrical issues</a></li>
<li><a href="#planets">Time and time zones on other planets</a></li>
</ul>
@@ -98,8 +99,9 @@ A <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can
have more than two changes per year, these changes need not merely
flip back and forth between two alternatives, and the rules themselves
can change at times.
-Whether and when a timezone changes its
-clock, and even the timezone's notional base offset from UTC, are variable.
+Whether and when a timezone changes its clock,
+and even the timezone's notional base offset from <abbr>UTC</abbr>,
+are variable.
It does not always make sense to talk about a timezone's
"base offset", which is not necessarily a single number.
</p>
@@ -428,7 +430,7 @@ in decreasing order of importance:
EET/EEST Eastern European,
GST/GDT Guam,
HST/HDT/HWT/HPT Hawaii,
- HKT/HKST Hong Kong,
+ HKT/HKST/HKWT Hong Kong,
IST India,
IST/GMT Irish,
IST/IDT/IDDT Israel,
@@ -972,7 +974,8 @@ an older <code>zic</code>.
that do not fit into the POSIX model.
</li>
<li>
- POSIX requires that systems ignore leap seconds.
+ POSIX requires that <code>time_t</code> clock counts exclude leap
+ seconds.
</li>
<li>
The <code><abbr>tz</abbr></code> code attempts to support all the
@@ -1072,7 +1075,8 @@ an older <code>zic</code>.
where <code>time_t</code> is signed.
</li>
<li>
- These functions can account for leap seconds, thanks to Bradley White.
+ These functions can account for leap seconds;
+ see <a href="#leapsec">Leap seconds</a> below.
</li>
</ul>
@@ -1249,6 +1253,69 @@ between now and the future time.
</section>
<section>
+ <h2 id="leapsec">Leap seconds</h2>
+<p>
+The <code><abbr>tz</abbr></code> code and data can account for leap seconds,
+thanks to code contributed by Bradley White.
+However, the leap second support of this package is rarely used directly
+because POSIX requires leap seconds to be excluded and many
+software packages would mishandle leap seconds if they were present.
+Instead, leap seconds are more commonly handled by occasionally adjusting
+the operating system kernel clock as described in
+<a href="tz-link.html#precision">Precision timekeeping</a>,
+and this package by default installs a <samp>leapseconds</samp> file
+commonly used by
+<a href="http://www.ntp.org"><abbr title="Network Time Protocol">NTP</abbr></a>
+software that adjusts the kernel clock.
+However, kernel-clock twiddling approximates UTC only roughly,
+and systems needing more-precise UTC can use this package's leap
+second support directly.
+</p>
+
+<p>
+The directly-supported mechanism assumes that <code>time_t</code>
+counts of seconds since the POSIX epoch normally include leap seconds,
+as opposed to POSIX <code>time_t</code> counts which exclude leap seconds.
+This modified timescale is converted to <abbr>UTC</abbr>
+at the same point that time zone and DST adjustments are applied &ndash;
+namely, at calls to <code>localtime</code> and analogous functions &ndash;
+and the process is driven by leap second information
+stored in alternate versions of the <abbr>TZif</abbr> files.
+Because a leap second adjustment may be needed even
+if no time zone correction is desired,
+calls to <code>gmtime</code>-like functions
+also need to consult a <abbr>TZif</abbr> file,
+conventionally named <samp><abbr>GMT</abbr></samp>,
+to see whether leap second corrections are needed.
+To convert an application's <code>time_t</code> timestamps to or from
+POSIX <code>time_t</code> timestamps (for use when, say,
+embedding or interpreting timestamps in portable
+<a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a>
+files),
+the application can call the utility functions
+<code>time2posix</code> and <code>posix2time</code>
+included with this package.
+</p>
+
+<p>
+If the POSIX-compatible <abbr>TZif</abbr> file set is installed
+in a directory whose basename is <samp>zoneinfo</samp>, the
+leap-second-aware file set is by default installed in a separate
+directory <samp>zoneinfo-leaps</samp>.
+Although each process can have its own time zone by setting
+its <code>TZ</code> environment variable, there is no support for some
+processes being leap-second aware while other processes are
+POSIX-compatible; the leap-second choice is system-wide.
+So if you configure your kernel to count leap seconds, you should also
+discard <samp>zoneinfo</samp> and rename <samp>zoneinfo-leaps</samp>
+to <samp>zoneinfo</samp>.
+Alternatively, you can install just one set of <abbr>TZif</abbr> files
+in the first place; see the <code>REDO</code> variable in this package's
+<a href="https://en.wikipedia.org/wiki/Makefile">makefile</a>.
+</p>
+</section>
+
+<section>
<h2 id="calendar">Calendrical issues</h2>
<p>
Calendrical issues are a bit out of scope for a time zone database,