pike.git / lib / modules / Calendar.pmod / tzdata / theory.html

version» Context lines:

pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:14:    <nav>    <ul>    <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code>    database</a></li>    <li><a href="#naming">Timezone identifiers</a></li>    <li><a href="#abbreviations">Time zone abbreviations</a></li>    <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code>    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>    </nav>      <section>    <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2>   <p>   The <a   href="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code>
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:91:   href="https://pubs.opengroup.org/onlinepubs/9699919799/"> The Open   Group Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018   Edition.   Because the database's scope encompasses real-world changes to civil   timekeeping, its model for describing time is more complex than the   standard and daylight saving times supported by POSIX.   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>      </section>      <section>    <h2 id="naming">Timezone identifiers</h2>   <p>   Each timezone has a name that uniquely identifies the timezone.
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:421:    CET/CEST/CEMT Central European,    ChST Chamorro,    CST/CDT/CWT/CPT/CDDT Central [North America],    CST/CDT China,    GMT/BST/IST/BDST Greenwich,    EAT East Africa,    EST/EDT/EWT/EPT/EDDT Eastern [North America],    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,    JST/JDT Japan,    KST/KDT Korea,    MET/MEST Middle European (a backward-compatibility alias for    Central European),    MSK/MSD Moscow,    MST/MDT/MWT/MPT/MDDT Mountain,    NST/NDT/NWT/NPT/NDDT Newfoundland,
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:965:    handling daylight saving time shifts &ndash; as might be required to    limit phone calls to off-peak hours.    </li>    <li>    POSIX provides no convenient and efficient way to determine    the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary    timestamps, particularly for timezones    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    <code>time_t</code> implementations allowed by POSIX.    The <code>time_t</code> type represents a nonnegative count of seconds    since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds.    In practice, <code>time_t</code> is usually a signed 64- or 32-bit    integer; 32-bit signed <code>time_t</code> values stop working after    2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these    days typically use a signed 64-bit integer.
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:1065:    variable; portable applications should not, however, rely on this    behavior since it is not the way <a    href="https://en.wikipedia.org/wiki/UNIX_System_V#SVR2"><abbr>SVR2</abbr></a>    systems behave.)    </li>    <li>    Negative <code>time_t</code> values are supported, on systems    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>      <h3 id="vestigial">POSIX features no longer needed</h3>   <p>   POSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a>   define some <a href="https://en.wikipedia.org/wiki/API"><abbr   title="application programming interface">API</abbr>s</a> that are vestigial:   they are not needed, and are relics of a too-simple model that does   not suffice to handle many real-world timestamps.
pike.git/lib/modules/Calendar.pmod/tzdata/theory.html:1242:   currently includes Chang Mai, Hanoi, and Phnom Penh, this is not part   of the stable interface and the timezone can split at any time.   If a calendar application records a future event in some location other   than Bangkok by putting "<samp>Asia/Bangkok</samp>" in the event's record,   the application should be robust in the presence of timezone splits   between now and the future time.   </p>   </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,   but they indicate the sort of problems that we would run into if we   extended the time zone database further into the past.   An excellent resource in this area is Edward M. Reingold   and Nachum Dershowitz, <cite><a   href="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical   Calculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018).   Other information and sources are given in the file '<code>calendars</code>'