pike.git / lib / modules / Calendar.pmod / tzdata / Theory

version» Context lines:

pike.git/lib/modules/Calendar.pmod/tzdata/Theory:316:    database were often spread out over hours, days, or even decades.       * Even if the time is specified by law, locations sometimes    deliberately flout the law.       * Early timekeeping practices, even assuming perfect clocks, were    often not specified to the accuracy that the tz database requires.       * Sometimes historical timekeeping was specified more precisely    than what the tz database can handle. For example, from 1909 to -  1937 Netherlands clocks were legally UT+00:19:32.13, but the tz +  1937 Netherlands clocks were legally UT +00:19:32.13, but the tz    database cannot represent the fractional second.       * Even when all the timestamp transitions recorded by the tz database    are correct, the tz rules that generate them may not faithfully    reflect the historical rules. For example, from 1922 until World    War II the UK moved clocks forward the day following the third    Saturday in April unless that was Easter, in which case it moved    clocks forward the previous Sunday. Because the tz database has no    way to specify Easter, these exceptional years are entered as    separate tz Rule lines, even though the legal rules did not change.
pike.git/lib/modules/Calendar.pmod/tzdata/Theory:438:       TZ='America/Los_Angeles'      * POSIX does not define the exact meaning of TZ values like "EST5EDT".    Typically the current US DST rules are used to interpret such values,    but this means that the US DST rules are compiled into each program    that does time conversion. This means that when US time conversion    rules change (as in the United States in 1987), all programs that    do time conversion must be recompiled to ensure proper results.    + * The TZ environment variable is process-global, which makes it hard +  to write efficient, thread-safe applications that need access +  to multiple time zones. +    * In POSIX, there's no tamper-proof way for a process to learn the    system's best idea of local wall clock. (This is important for    applications that an administrator wants used only at certain times -    without regard to whether the user has fiddled the "TZ" environment    variable. While an administrator can "do everything in UTC" to get    around the problem, doing so is inconvenient and precludes handling    daylight saving time shifts - as might be required to limit phone    calls to off-peak hours.)    -  + * POSIX provides no convenient and efficient way to determine the UT +  offset and time zone abbreviation of arbitrary time stamps, +  particularly for time zone settings that do not fit into the +  POSIX model. +    * POSIX requires that systems ignore leap seconds.      * The tz code attempts to support all the time_t implementations    allowed by POSIX. The time_t type represents a nonnegative count of    seconds since 1970-01-01 00:00:00 UTC, ignoring leap seconds.    In practice, time_t is usually a signed 64- or 32-bit integer; 32-bit    signed time_t values stop working after 2038-01-19 03:14:07 UTC, so    new implementations these days typically use a signed 64-bit integer.    Unsigned 32-bit integers are used on one or two platforms,    and 36-bit and 40-bit integers are also used occasionally.
pike.git/lib/modules/Calendar.pmod/tzdata/Theory:487:    consideration was given to using some other environment variable    (for example, "TIMEZONE") to hold the string used to generate the    time zone information file name. In the end, however, it was decided    to continue using "TZ": it is widely used for time zone purposes;    separately maintaining both "TZ" and "TIMEZONE" seemed a nuisance;    and systems where "new" forms of "TZ" might cause problems can simply    use TZ values such as "EST5EDT" which can be used both by    "new" programs (a la POSIX) and "old" programs (as zone names and    offsets).    - * To handle places where more than two time zone abbreviations are used, -  the functions "localtime" and "gmtime" set tzname[tmp->tm_isdst] -  (where "tmp" is the value the function returns) to the time zone -  abbreviation to be used. This differs from POSIX, where the elements -  of tzname are only changed as a result of calls to tzset. + * The code supports platforms with a UT offset member in struct tm, +  e.g., tm_gmtoff.    -  + * The code supports platforms with a time zone abbreviation member in +  struct tm, e.g., tm_zone. +    * Since the "TZ" environment variable can now be used to control time    conversion, the "daylight" and "timezone" variables are no longer    needed. (These variables are defined and set by "tzset"; however, their    values will not be used by "localtime.")    - * The "localtime" function has been set up to deliver correct results -  for near-minimum or near-maximum time_t values. (A comment in the -  source code tells how to get compatibly wrong results). + * Functions tzalloc, tzfree, localtime_rz, and mktime_z for +  more-efficient thread-safe applications that need to use +  multiple time zones. The tzalloc and tzfree functions +  allocate and free objects of type timezone_t, and localtime_rz +  and mktime_z are like localtime_r and mktime with an extra +  timezone_t argument. The functions were inspired by NetBSD.      * A function "tzsetwall" has been added to arrange for the system's    best approximation to local wall clock time to be delivered by    subsequent calls to "localtime." Source code for portable    applications that "must" run on local wall clock time should call    "tzsetwall();" if such code is moved to "old" systems that don't    provide tzsetwall, you won't be able to generate an executable program.    (These time zone functions also arrange for local wall clock time to be    used if tzset is called - directly or indirectly - and there's no "TZ"    environment variable; portable applications should not, however, rely    on this behavior since it's not the way SVR2 systems behave.)      * Negative time_t values are supported, on systems where time_t is signed.      * These functions can account for leap seconds, thanks to Bradley White.      Points of interest to folks with other systems:    - * This package is already part of many POSIX-compliant hosts, -  including BSD, HP, Linux, Network Appliance, SCO, SGI, and Sun. + * Code compatible with this package is already part of many platforms, +  including GNU/Linux, Android, the BSDs, Chromium OS, Cygwin, AIX, iOS, +  BlackBery 10, macOS, Microsoft Windows, OpenVMS, and Solaris.    On such hosts, the primary use of this package    is to update obsolete time zone rule tables.    To do this, you may need to compile the time zone compiler    'zic' supplied with this package instead of using the system 'zic', -  since the format of zic's input changed slightly in late 1994, -  and many vendors still do not support the new input format. +  since the format of zic's input is occasionally extended, +  and a platform may still be shipping an older zic.      * The UNIX Version 7 "timezone" function is not present in this package;    it's impossible to reliably map timezone's arguments (a "minutes west    of GMT" value and a "daylight saving time in effect" flag) to a    time zone abbreviation, and we refuse to guess.    Programs that in the past used the timezone function may now examine    tzname[localtime(&clock)->tm_isdst] to learn the correct time    zone abbreviation to use. Alternatively, use    localtime(&clock)->tm_zone if this has been enabled.      * The 4.2BSD gettimeofday function is not used in this package.    This formerly let users obtain the current UTC offset and DST flag,    but this functionality was removed in later versions of BSD.      * In SVR2, time conversion fails for near-minimum or near-maximum    time_t values when doing conversions for places that don't use UT.    This package takes care to do these conversions correctly. -  +  A comment in the source code tells how to get compatibly wrong +  results.      The functions that are conditionally compiled if STD_INSPIRED is defined   should, at this point, be looked on primarily as food for thought. They are   not in any sense "standard compatible" - some are not, in fact, specified in   *any* standard. They do, however, represent responses of various authors to   standardization proposals.      Other time conversion proposals, in particular the one developed by folks at   Hewlett Packard, offer a wider selection of functions that provide capabilities   beyond those provided here. The absence of such functions from this package   is not meant to discourage the development, standardization, or use of such   functions. Rather, their absence reflects the decision to make this package   contain valid extensions to POSIX, to ensure its broad acceptability. If   more powerful time conversion functions can be standardized, so much the   better.       -  + ----- Interface stability ----- +  + The tz code and data supply the following interfaces: +  +  * A set of zone names as per "Names of time zone rules" above. +  +  * Library functions described in "Time and date functions" above. +  +  * The programs tzselect, zdump, and zic, documented in their man pages. +  +  * The format of zic input files, documented in the zic man page. +  +  * The format of zic output files, documented in the tzfile man page. +  +  * The format of zone table files, documented in zone1970.tab. +  +  * The format of the country code file, documented in iso3166.tab. +  + When these interfaces are changed, an effort is made to preserve + backward compatibility. For example, tz data files typically do not + rely on recently-added zic features, so that users can run older zic + versions to process newer data files. +  + Interfaces not listed above are less stable. For example, users + should not rely on particular UT offsets or abbreviations for time + stamps, as data entries are often based on guesswork and these guesses + may be corrected or improved. +  +    ----- Calendrical issues -----      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 Nachum Dershowitz and Edward M. Reingold,   Calendrical Calculations: Third Edition, Cambridge University Press (2008)   <http://emr.cs.iit.edu/home/reingold/calendar-book/third-edition/>.   Other information and sources are given below. They sometimes disagree.