[BACK]Return to Theory CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / time

Annotation of src/lib/libc/time/Theory, Revision 1.23

1.18      christos    1: Theory and pragmatics of the tz code and data
                      2:
1.2       perry       3:
                      4: ----- Outline -----
                      5:
1.10      christos    6:        Scope of the tz database
1.18      christos    7:        Names of time zone rules
1.2       perry       8:        Time zone abbreviations
1.18      christos    9:        Accuracy of the tz database
                     10:        Time and date functions
1.23    ! christos   11:        Interface stability
1.4       kleink     12:        Calendrical issues
1.8       kleink     13:        Time and time zones on Mars
1.2       perry      14:
                     15:
1.18      christos   16: ----- Scope of the tz database -----
                     17:
                     18: The tz database attempts to record the history and predicted future of
                     19: all computer-based clocks that track civil time.  To represent this
                     20: data, the world is partitioned into regions whose clocks all agree
                     21: about time stamps that occur after the somewhat-arbitrary cutoff point
                     22: of the POSIX Epoch (1970-01-01 00:00:00 UTC).  For each such region,
                     23: the database records all known clock transitions, and labels the region
                     24: with a notable location.  Although 1970 is a somewhat-arbitrary
                     25: cutoff, there are significant challenges to moving the cutoff earlier
                     26: even by a decade or two, due to the wide variety of local practices
                     27: before computer timekeeping became prevalent.
                     28:
                     29: Clock transitions before 1970 are recorded for each such location,
                     30: because most systems support time stamps before 1970 and could
                     31: misbehave if data entries were omitted for pre-1970 transitions.
                     32: However, the database is not designed for and does not suffice for
                     33: applications requiring accurate handling of all past times everywhere,
                     34: as it would take far too much effort and guesswork to record all
                     35: details of pre-1970 civil timekeeping.
                     36:
                     37: As described below, reference source code for using the tz database is
                     38: also available.  The tz code is upwards compatible with POSIX, an
                     39: international standard for UNIX-like systems.  As of this writing, the
                     40: current edition of POSIX is:
1.2       perry      41:
1.14      christos   42:   The Open Group Base Specifications Issue 7
1.23    ! christos   43:   IEEE Std 1003.1-2008, 2016 Edition
1.14      christos   44:   <http://pubs.opengroup.org/onlinepubs/9699919799/>
1.2       perry      45:
                     46:
1.1       jtc        47:
1.18      christos   48: ----- Names of time zone rules -----
1.2       perry      49:
1.18      christos   50: Each of the database's time zone rules has a unique name.
                     51: Inexperienced users are not expected to select these names unaided.
                     52: Distributors should provide documentation and/or a simple selection
                     53: interface that explains the names; for one example, see the 'tzselect'
                     54: program in the tz code.  The Unicode Common Locale Data Repository
                     55: <http://cldr.unicode.org/> contains data that may be useful for other
                     56: selection interfaces.
1.2       perry      57:
1.18      christos   58: The time zone rule naming conventions attempt to strike a balance
                     59: among the following goals:
1.6       kleink     60:
1.18      christos   61:  * Uniquely identify every region where clocks have agreed since 1970.
                     62:    This is essential for the intended use: static clocks keeping local
                     63:    civil time.
                     64:
                     65:  * Indicate to experts where that region is.
                     66:
                     67:  * Be robust in the presence of political changes.  For example, names
                     68:    of countries are ordinarily not used, to avoid incompatibilities
                     69:    when countries change their name (e.g. Zaire->Congo) or when
                     70:    locations change countries (e.g. Hong Kong from UK colony to
                     71:    China).
1.2       perry      72:
1.18      christos   73:  * Be portable to a wide variety of implementations.
1.9       mlelstv    74:
1.18      christos   75:  * Use a consistent naming conventions over the entire world.
1.9       mlelstv    76:
1.18      christos   77: Names normally have the form AREA/LOCATION, where AREA is the name
                     78: of a continent or ocean, and LOCATION is the name of a specific
                     79: location within that region.  North and South America share the same
                     80: area, 'America'.  Typical names are 'Africa/Cairo', 'America/New_York',
                     81: and 'Pacific/Honolulu'.
1.9       mlelstv    82:
1.18      christos   83: Here are the general rules used for choosing location names,
                     84: in decreasing order of importance:
1.9       mlelstv    85:
1.18      christos   86:        Use only valid POSIX file name components (i.e., the parts of
                     87:                names other than '/').  Do not use the file name
                     88:                components '.' and '..'.  Within a file name component,
                     89:                use only ASCII letters, '.', '-' and '_'.  Do not use
                     90:                digits, as that might create an ambiguity with POSIX
                     91:                TZ strings.  A file name component must not exceed 14
                     92:                characters or start with '-'.  E.g., prefer 'Brunei'
                     93:                to 'Bandar_Seri_Begawan'.  Exceptions: see the discussion
                     94:                of legacy names below.
                     95:        A name must not be empty, or contain '//', or start or end with '/'.
                     96:        Do not use names that differ only in case.  Although the reference
                     97:                implementation is case-sensitive, some other implementations
                     98:                are not, and they would mishandle names differing only in case.
                     99:        If one name A is an initial prefix of another name AB (ignoring case),
                    100:                then B must not start with '/', as a regular file cannot have
                    101:                the same name as a directory in POSIX.  For example,
                    102:                'America/New_York' precludes 'America/New_York/Bronx'.
                    103:        Uninhabited regions like the North Pole and Bouvet Island
                    104:                do not need locations, since local time is not defined there.
                    105:        There should typically be at least one name for each ISO 3166-1
                    106:                officially assigned two-letter code for an inhabited country
                    107:                or territory.
                    108:        If all the clocks in a region have agreed since 1970,
                    109:                don't bother to include more than one location
                    110:                even if subregions' clocks disagreed before 1970.
                    111:                Otherwise these tables would become annoyingly large.
                    112:        If a name is ambiguous, use a less ambiguous alternative;
                    113:                e.g. many cities are named San José and Georgetown, so
                    114:                prefer 'Costa_Rica' to 'San_Jose' and 'Guyana' to 'Georgetown'.
                    115:        Keep locations compact.  Use cities or small islands, not countries
                    116:                or regions, so that any future time zone changes do not split
                    117:                locations into different time zones.  E.g. prefer 'Paris'
                    118:                to 'France', since France has had multiple time zones.
                    119:        Use mainstream English spelling, e.g. prefer 'Rome' to 'Roma', and
                    120:                prefer 'Athens' to the Greek 'Αθήνα' or the Romanized 'Athína'.
                    121:                The POSIX file name restrictions encourage this rule.
                    122:        Use the most populous among locations in a zone,
                    123:                e.g. prefer 'Shanghai' to 'Beijing'.  Among locations with
                    124:                similar populations, pick the best-known location,
                    125:                e.g. prefer 'Rome' to 'Milan'.
                    126:        Use the singular form, e.g. prefer 'Canary' to 'Canaries'.
                    127:        Omit common suffixes like '_Islands' and '_City', unless that
                    128:                would lead to ambiguity.  E.g. prefer 'Cayman' to
                    129:                'Cayman_Islands' and 'Guatemala' to 'Guatemala_City',
                    130:                but prefer 'Mexico_City' to 'Mexico' because the country
                    131:                of Mexico has several time zones.
                    132:        Use '_' to represent a space.
                    133:        Omit '.' from abbreviations in names, e.g. prefer 'St_Helena'
                    134:                to 'St._Helena'.
                    135:        Do not change established names if they only marginally
                    136:                violate the above rules.  For example, don't change
                    137:                the existing name 'Rome' to 'Milan' merely because
                    138:                Milan's population has grown to be somewhat greater
                    139:                than Rome's.
                    140:        If a name is changed, put its old spelling in the 'backward' file.
                    141:                This means old spellings will continue to work.
1.1       jtc       142:
1.18      christos  143: The file 'zone1970.tab' lists geographical locations used to name time
                    144: zone rules.  It is intended to be an exhaustive list of names for
                    145: geographic regions as described above; this is a subset of the names
                    146: in the data.  Although a 'zone1970.tab' location's longitude
                    147: corresponds to its LMT offset with one hour for every 15 degrees east
                    148: longitude, this relationship is not exact.
1.1       jtc       149:
1.18      christos  150: Older versions of this package used a different naming scheme,
                    151: and these older names are still supported.
                    152: See the file 'backward' for most of these older names
                    153: (e.g., 'US/Eastern' instead of 'America/New_York').
                    154: The other old-fashioned names still supported are
                    155: 'WET', 'CET', 'MET', and 'EET' (see the file 'europe').
1.1       jtc       156:
1.18      christos  157: Older versions of this package defined legacy names that are
                    158: incompatible with the first rule of location names, but which are
                    159: still supported.  These legacy names are mostly defined in the file
                    160: 'etcetera'.  Also, the file 'backward' defines the legacy names
                    161: 'GMT0', 'GMT-0', 'GMT+0' and 'Canada/East-Saskatchewan', and the file
                    162: 'northamerica' defines the legacy names 'EST5EDT', 'CST6CDT',
                    163: 'MST7MDT', and 'PST8PDT'.
1.14      christos  164:
1.18      christos  165: Excluding 'backward' should not affect the other data.  If
                    166: 'backward' is excluded, excluding 'etcetera' should not affect the
                    167: remaining data.
1.1       jtc       168:
                    169:
1.18      christos  170: ----- Time zone abbreviations -----
1.1       jtc       171:
1.18      christos  172: When this package is installed, it generates time zone abbreviations
                    173: like 'EST' to be compatible with human tradition and POSIX.
                    174: Here are the general rules used for choosing time zone abbreviations,
                    175: in decreasing order of importance:
1.1       jtc       176:
1.19      christos  177:        Use three or more characters that are ASCII alphanumerics or '+' or '-'.
1.18      christos  178:                Previous editions of this database also used characters like
                    179:                ' ' and '?', but these characters have a special meaning to
                    180:                the shell and cause commands like
                    181:                        set `date`
                    182:                to have unexpected effects.
                    183:                Previous editions of this rule required upper-case letters,
                    184:                but the Congressman who introduced Chamorro Standard Time
1.19      christos  185:                preferred "ChST", so lower-case letters are now allowed.
                    186:                Also, POSIX from 2001 on relaxed the rule to allow '-', '+',
                    187:                and alphanumeric characters from the portable character set
                    188:                in the current locale.  In practice ASCII alphanumerics and
                    189:                '+' and '-' are safe in all locales.
1.1       jtc       190:
1.19      christos  191:                In other words, in the C locale the POSIX extended regular
                    192:                expression [-+[:alnum:]]{3,} should match the abbreviation.
                    193:                This guarantees that all abbreviations could have been
                    194:                specified by a POSIX TZ string.
1.1       jtc       195:
1.18      christos  196:        Use abbreviations that are in common use among English-speakers,
                    197:                e.g. 'EST' for Eastern Standard Time in North America.
                    198:                We assume that applications translate them to other languages
                    199:                as part of the normal localization process; for example,
                    200:                a French application might translate 'EST' to 'HNE'.
1.1       jtc       201:
1.18      christos  202:        For zones whose times are taken from a city's longitude, use the
                    203:                traditional xMT notation, e.g. 'PMT' for Paris Mean Time.
                    204:                The only name like this in current use is 'GMT'.
1.14      christos  205:
1.18      christos  206:        Use 'LMT' for local mean time of locations before the introduction
                    207:                of standard time; see "Scope of the tz database".
1.1       jtc       208:
1.18      christos  209:        If there is no common English abbreviation, use numeric offsets like
                    210:                -05 and +0830 that are generated by zic's %z notation.
1.2       perry     211:
1.23    ! christos  212:        Use current abbreviations for older timestamps to avoid confusion.
        !           213:                For example, in 1910 a common English abbreviation for UT +01
        !           214:                in central Europe was 'MEZ' (short for both "Middle European
        !           215:                Zone" and for "Mitteleuropäische Zeit" in German).  Nowadays
        !           216:                'CET' ("Central European Time") is more common in English, and
        !           217:                the database uses 'CET' even for circa-1910 timestamps as this
        !           218:                is less confusing for modern users and avoids the need for
        !           219:                determining when 'CET' supplanted 'MEZ' in common usage.
        !           220:
        !           221:        Use a consistent style in a zone's history.  For example, if a zone's
        !           222:                history tends to use numeric abbreviations and a particular
        !           223:                entry could go either way, use a numeric abbreviation.
        !           224:
1.18      christos  225:     [The remaining guidelines predate the introduction of %z.
                    226:     They are problematic as they mean tz data entries invent
                    227:     notation rather than record it.  These guidelines are now
                    228:     deprecated and the plan is to gradually move to %z for
                    229:     inhabited locations and to "-00" for uninhabited locations.]
1.2       perry     230:
1.18      christos  231:        If there is no common English abbreviation, abbreviate the English
                    232:                translation of the usual phrase used by native speakers.
                    233:                If this is not available or is a phrase mentioning the country
                    234:                (e.g. "Cape Verde Time"), then:
1.2       perry     235:
1.18      christos  236:                When a country is identified with a single or principal zone,
                    237:                        append 'T' to the country's ISO code, e.g. 'CVT' for
                    238:                        Cape Verde Time.  For summer time append 'ST';
                    239:                        for double summer time append 'DST'; etc.
                    240:                Otherwise, take the first three letters of an English place
                    241:                        name identifying each zone and append 'T', 'ST', etc.
1.23    ! christos  242:                        as before; e.g. 'CHAST' for CHAtham Summer Time.
1.1       jtc       243:
1.20      christos  244:        Use UT (with time zone abbreviation '-00') for locations while
                    245:                uninhabited.  The leading '-' is a flag that the time
                    246:                zone is in some sense undefined; this notation is
                    247:                derived from Internet RFC 3339.
1.2       perry     248:
1.18      christos  249: Application writers should note that these abbreviations are ambiguous
                    250: in practice: e.g. 'CST' has a different meaning in China than
                    251: it does in the United States.  In new applications, it's often better
                    252: to use numeric UT offsets like '-0600' instead of time zone
                    253: abbreviations like 'CST'; this avoids the ambiguity.
1.10      christos  254:
1.14      christos  255:
                    256: ----- Accuracy of the tz database -----
                    257:
                    258: The tz database is not authoritative, and it surely has errors.
1.16      christos  259: Corrections are welcome and encouraged; see the file CONTRIBUTING.
                    260: Users requiring authoritative data should consult national standards
                    261: bodies and the references cited in the database's comments.
1.10      christos  262:
1.14      christos  263: Errors in the tz database arise from many sources:
                    264:
                    265:  * The tz database predicts future time stamps, and current predictions
                    266:    will be incorrect after future governments change the rules.
                    267:    For example, if today someone schedules a meeting for 13:00 next
                    268:    October 1, Casablanca time, and tomorrow Morocco changes its
                    269:    daylight saving rules, software can mess up after the rule change
                    270:    if it blithely relies on conversions made before the change.
                    271:
1.16      christos  272:  * The pre-1970 entries in this database cover only a tiny sliver of how
1.14      christos  273:    clocks actually behaved; the vast majority of the necessary
                    274:    information was lost or never recorded.  Thousands more zones would
                    275:    be needed if the tz database's scope were extended to cover even
                    276:    just the known or guessed history of standard time; for example,
                    277:    the current single entry for France would need to split into dozens
1.19      christos  278:    of entries, perhaps hundreds.  And in most of the world even this
                    279:    approach would be misleading due to widespread disagreement or
                    280:    indifference about what times should be observed.  In her 2015 book
                    281:    "The Global Transformation of Time, 1870-1950", Vanessa Ogle writes
                    282:    "Outside of Europe and North America there was no system of time
                    283:    zones at all, often not even a stable landscape of mean times,
                    284:    prior to the middle decades of the twentieth century".  See:
                    285:    Timothy Shenk, Booked: A Global History of Time. Dissent 2015-12-17
                    286:    https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle
1.14      christos  287:
1.16      christos  288:  * Most of the pre-1970 data entries come from unreliable sources, often
1.14      christos  289:    astrology books that lack citations and whose compilers evidently
                    290:    invented entries when the true facts were unknown, without
                    291:    reporting which entries were known and which were invented.
                    292:    These books often contradict each other or give implausible entries,
1.16      christos  293:    and on the rare occasions when they are checked they are
1.14      christos  294:    typically found to be incorrect.
                    295:
                    296:  * For the UK the tz database relies on years of first-class work done by
                    297:    Joseph Myers and others; see <http://www.polyomino.org.uk/british-time/>.
                    298:    Other countries are not done nearly as well.
                    299:
                    300:  * Sometimes, different people in the same city would maintain clocks
                    301:    that differed significantly.  Railway time was used by railroad
                    302:    companies (which did not always agree with each other),
                    303:    church-clock time was used for birth certificates, etc.
                    304:    Often this was merely common practice, but sometimes it was set by law.
                    305:    For example, from 1891 to 1911 the UT offset in France was legally
                    306:    0:09:21 outside train stations and 0:04:21 inside.
                    307:
                    308:  * Although a named location in the tz database stands for the
                    309:    containing region, its pre-1970 data entries are often accurate for
                    310:    only a small subset of that region.  For example, Europe/London
                    311:    stands for the United Kingdom, but its pre-1847 times are valid
                    312:    only for locations that have London's exact meridian, and its 1847
                    313:    transition to GMT is known to be valid only for the L&NW and the
                    314:    Caledonian railways.
                    315:
1.16      christos  316:  * The tz database does not record the earliest time for which a zone's
                    317:    data entries are thereafter valid for every location in the region.
1.14      christos  318:    For example, Europe/London is valid for all locations in its
                    319:    region after GMT was made the standard time, but the date of
                    320:    standardization (1880-08-02) is not in the tz database, other than
                    321:    in commentary.  For many zones the earliest time of validity is
                    322:    unknown.
                    323:
                    324:  * The tz database does not record a region's boundaries, and in many
                    325:    cases the boundaries are not known.  For example, the zone
                    326:    America/Kentucky/Louisville represents a region around the city of
                    327:    Louisville, the boundaries of which are unclear.
                    328:
                    329:  * Changes that are modeled as instantaneous transitions in the tz
                    330:    database were often spread out over hours, days, or even decades.
                    331:
                    332:  * Even if the time is specified by law, locations sometimes
                    333:    deliberately flout the law.
                    334:
                    335:  * Early timekeeping practices, even assuming perfect clocks, were
                    336:    often not specified to the accuracy that the tz database requires.
                    337:
                    338:  * Sometimes historical timekeeping was specified more precisely
                    339:    than what the tz database can handle.  For example, from 1909 to
1.21      christos  340:    1937 Netherlands clocks were legally UT +00:19:32.13, but the tz
1.14      christos  341:    database cannot represent the fractional second.
                    342:
                    343:  * Even when all the timestamp transitions recorded by the tz database
                    344:    are correct, the tz rules that generate them may not faithfully
                    345:    reflect the historical rules.  For example, from 1922 until World
                    346:    War II the UK moved clocks forward the day following the third
                    347:    Saturday in April unless that was Easter, in which case it moved
                    348:    clocks forward the previous Sunday.  Because the tz database has no
                    349:    way to specify Easter, these exceptional years are entered as
                    350:    separate tz Rule lines, even though the legal rules did not change.
                    351:
1.16      christos  352:  * The tz database models pre-standard time using the proleptic Gregorian
1.14      christos  353:    calendar and local mean time (LMT), but many people used other
                    354:    calendars and other timescales.  For example, the Roman Empire used
                    355:    the Julian calendar, and had 12 varying-length daytime hours with a
                    356:    non-hour-based system at night.
                    357:
1.16      christos  358:  * Early clocks were less reliable, and data entries do not represent
1.23    ! christos  359:    clock error.
1.14      christos  360:
1.23    ! christos  361:  * The tz database assumes Universal Time (UT) as an origin, even
        !           362:    though UT is not standardized for older time stamps.  In the tz
        !           363:    database commentary, UT denotes a family of time standards that
        !           364:    includes Coordinated Universal Time (UTC) along with other variants
        !           365:    such as UT1 and GMT, with days starting at midnight.  Although UT
        !           366:    equals UTC for modern time stamps, UTC was not defined until 1960,
        !           367:    so commentary uses the more-general abbreviation UT for time stamps
        !           368:    that might predate 1960.  Since UT, UT1, etc. disagree slightly,
        !           369:    and since pre-1972 UTC seconds varied in length, interpretation of
        !           370:    older time stamps can be problematic when subsecond accuracy is
        !           371:    needed.
        !           372:
        !           373:  * Civil time was not based on atomic time before 1972, and we don't
        !           374:    know the history of earth's rotation accurately enough to map SI
        !           375:    seconds to historical solar time to more than about one-hour
        !           376:    accuracy.  See: Stephenson FR, Morrison LV, Hohenkerk CY.
        !           377:    Measurement of the Earth's rotation: 720 BC to AD 2015.
        !           378:    Proc Royal Soc A. 2016 Dec 7;472:20160404.
        !           379:    http://dx.doi.org/10.1098/rspa.2016.0404
        !           380:    Also see: Espenak F. Uncertainty in Delta T (ΔT).
        !           381:    http://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html
1.14      christos  382:
                    383:  * The relationship between POSIX time (that is, UTC but ignoring leap
                    384:    seconds) and UTC is not agreed upon after 1972.  Although the POSIX
                    385:    clock officially stops during an inserted leap second, at least one
                    386:    proposed standard has it jumping back a second instead; and in
                    387:    practice POSIX clocks more typically either progress glacially during
                    388:    a leap second, or are slightly slowed while near a leap second.
                    389:
                    390:  * The tz database does not represent how uncertain its information is.
1.16      christos  391:    Ideally it would contain information about when data entries are
1.14      christos  392:    incomplete or dicey.  Partial temporal knowledge is a field of
                    393:    active research, though, and it's not clear how to apply it here.
                    394:
                    395: In short, many, perhaps most, of the tz database's pre-1970 and future
                    396: time stamps are either wrong or misleading.  Any attempt to pass the
                    397: tz database off as the definition of time should be unacceptable to
                    398: anybody who cares about the facts.  In particular, the tz database's
                    399: LMT offsets should not be considered meaningful, and should not prompt
                    400: creation of zones merely because two locations differ in LMT or
                    401: transitioned to standard time at different dates.
                    402:
1.10      christos  403:
1.18      christos  404: ----- Time and date functions -----
                    405:
                    406: The tz code contains time and date functions that are upwards
                    407: compatible with those of POSIX.
                    408:
                    409: POSIX has the following properties and limitations.
                    410:
                    411: *      In POSIX, time display in a process is controlled by the
                    412:        environment variable TZ.  Unfortunately, the POSIX TZ string takes
                    413:        a form that is hard to describe and is error-prone in practice.
                    414:        Also, POSIX TZ strings can't deal with other (for example, Israeli)
                    415:        daylight saving time rules, or situations where more than two
                    416:        time zone abbreviations are used in an area.
                    417:
                    418:        The POSIX TZ string takes the following form:
                    419:
                    420:                stdoffset[dst[offset][,date[/time],date[/time]]]
                    421:
                    422:        where:
                    423:
                    424:        std and dst
                    425:                are 3 or more characters specifying the standard
                    426:                and daylight saving time (DST) zone names.
                    427:                Starting with POSIX.1-2001, std and dst may also be
                    428:                in a quoted form like "<UTC+10>"; this allows
                    429:                "+" and "-" in the names.
                    430:        offset
                    431:                is of the form '[+-]hh:[mm[:ss]]' and specifies the
                    432:                offset west of UT.  'hh' may be a single digit; 0<=hh<=24.
                    433:                The default DST offset is one hour ahead of standard time.
                    434:        date[/time],date[/time]
                    435:                specifies the beginning and end of DST.  If this is absent,
                    436:                the system supplies its own rules for DST, and these can
                    437:                differ from year to year; typically US DST rules are used.
                    438:        time
                    439:                takes the form 'hh:[mm[:ss]]' and defaults to 02:00.
                    440:                This is the same format as the offset, except that a
                    441:                leading '+' or '-' is not allowed.
                    442:        date
                    443:                takes one of the following forms:
                    444:                Jn (1<=n<=365)
                    445:                        origin-1 day number not counting February 29
                    446:                n (0<=n<=365)
                    447:                        origin-0 day number counting February 29 if present
                    448:                Mm.n.d (0[Sunday]<=d<=6[Saturday], 1<=n<=5, 1<=m<=12)
                    449:                        for the dth day of week n of month m of the year,
                    450:                        where week 1 is the first week in which day d appears,
                    451:                        and '5' stands for the last week in which day d appears
                    452:                        (which may be either the 4th or 5th week).
                    453:                        Typically, this is the only useful form;
                    454:                        the n and Jn forms are rarely used.
                    455:
                    456:        Here is an example POSIX TZ string, for US Pacific time using rules
                    457:        appropriate from 1987 through 2006:
1.2       perry     458:
1.18      christos  459:                TZ='PST8PDT,M4.1.0/02:00,M10.5.0/02:00'
1.6       kleink    460:
1.18      christos  461:        This POSIX TZ string is hard to remember, and mishandles time stamps
                    462:        before 1987 and after 2006.  With this package you can use this
                    463:        instead:
1.6       kleink    464:
1.18      christos  465:                TZ='America/Los_Angeles'
1.6       kleink    466:
1.18      christos  467: *      POSIX does not define the exact meaning of TZ values like "EST5EDT".
                    468:        Typically the current US DST rules are used to interpret such values,
                    469:        but this means that the US DST rules are compiled into each program
                    470:        that does time conversion.  This means that when US time conversion
                    471:        rules change (as in the United States in 1987), all programs that
                    472:        do time conversion must be recompiled to ensure proper results.
1.6       kleink    473:
1.22      christos  474: *      The TZ environment variable is process-global, which makes it hard
                    475:        to write efficient, thread-safe applications that need access
                    476:        to multiple time zones.
                    477:
1.18      christos  478: *      In POSIX, there's no tamper-proof way for a process to learn the
                    479:        system's best idea of local wall clock.  (This is important for
                    480:        applications that an administrator wants used only at certain times -
                    481:        without regard to whether the user has fiddled the "TZ" environment
                    482:        variable.  While an administrator can "do everything in UTC" to get
                    483:        around the problem, doing so is inconvenient and precludes handling
                    484:        daylight saving time shifts - as might be required to limit phone
                    485:        calls to off-peak hours.)
1.2       perry     486:
1.22      christos  487: *      POSIX provides no convenient and efficient way to determine the UT
                    488:        offset and time zone abbreviation of arbitrary time stamps,
                    489:        particularly for time zone settings that do not fit into the
                    490:        POSIX model.
                    491:
1.18      christos  492: *      POSIX requires that systems ignore leap seconds.
1.2       perry     493:
1.18      christos  494: *      The tz code attempts to support all the time_t implementations
                    495:        allowed by POSIX.  The time_t type represents a nonnegative count of
                    496:        seconds since 1970-01-01 00:00:00 UTC, ignoring leap seconds.
                    497:        In practice, time_t is usually a signed 64- or 32-bit integer; 32-bit
                    498:        signed time_t values stop working after 2038-01-19 03:14:07 UTC, so
                    499:        new implementations these days typically use a signed 64-bit integer.
                    500:        Unsigned 32-bit integers are used on one or two platforms,
                    501:        and 36-bit and 40-bit integers are also used occasionally.
                    502:        Although earlier POSIX versions allowed time_t to be a
                    503:        floating-point type, this was not supported by any practical
                    504:        systems, and POSIX.1-2013 and the tz code both require time_t
                    505:        to be an integer type.
1.2       perry     506:
1.18      christos  507: These are the extensions that have been made to the POSIX functions:
1.2       perry     508:
1.18      christos  509: *      The "TZ" environment variable is used in generating the name of a file
                    510:        from which time zone information is read (or is interpreted a la
                    511:        POSIX); "TZ" is no longer constrained to be a three-letter time zone
                    512:        name followed by a number of hours and an optional three-letter
                    513:        daylight time zone name.  The daylight saving time rules to be used
                    514:        for a particular time zone are encoded in the time zone file;
                    515:        the format of the file allows U.S., Australian, and other rules to be
                    516:        encoded, and allows for situations where more than two time zone
                    517:        abbreviations are used.
1.2       perry     518:
1.18      christos  519:        It was recognized that allowing the "TZ" environment variable to
                    520:        take on values such as "America/New_York" might cause "old" programs
                    521:        (that expect "TZ" to have a certain form) to operate incorrectly;
                    522:        consideration was given to using some other environment variable
                    523:        (for example, "TIMEZONE") to hold the string used to generate the
                    524:        time zone information file name.  In the end, however, it was decided
                    525:        to continue using "TZ": it is widely used for time zone purposes;
                    526:        separately maintaining both "TZ" and "TIMEZONE" seemed a nuisance;
                    527:        and systems where "new" forms of "TZ" might cause problems can simply
                    528:        use TZ values such as "EST5EDT" which can be used both by
                    529:        "new" programs (a la POSIX) and "old" programs (as zone names and
                    530:        offsets).
1.2       perry     531:
1.22      christos  532: *      The code supports platforms with a UT offset member in struct tm,
                    533:        e.g., tm_gmtoff.
                    534:
                    535: *      The code supports platforms with a time zone abbreviation member in
                    536:        struct tm, e.g., tm_zone.
1.15      christos  537:
1.18      christos  538: *      Since the "TZ" environment variable can now be used to control time
                    539:        conversion, the "daylight" and "timezone" variables are no longer
                    540:        needed.  (These variables are defined and set by "tzset"; however, their
                    541:        values will not be used by "localtime.")
1.15      christos  542:
1.22      christos  543: *      Functions tzalloc, tzfree, localtime_rz, and mktime_z for
                    544:        more-efficient thread-safe applications that need to use
                    545:        multiple time zones.  The tzalloc and tzfree functions
                    546:        allocate and free objects of type timezone_t, and localtime_rz
                    547:        and mktime_z are like localtime_r and mktime with an extra
                    548:        timezone_t argument.  The functions were inspired by NetBSD.
1.2       perry     549:
1.18      christos  550: *      A function "tzsetwall" has been added to arrange for the system's
                    551:        best approximation to local wall clock time to be delivered by
                    552:        subsequent calls to "localtime."  Source code for portable
                    553:        applications that "must" run on local wall clock time should call
                    554:        "tzsetwall();" if such code is moved to "old" systems that don't
                    555:        provide tzsetwall, you won't be able to generate an executable program.
                    556:        (These time zone functions also arrange for local wall clock time to be
                    557:        used if tzset is called - directly or indirectly - and there's no "TZ"
                    558:        environment variable; portable applications should not, however, rely
                    559:        on this behavior since it's not the way SVR2 systems behave.)
1.2       perry     560:
1.18      christos  561: *      Negative time_t values are supported, on systems where time_t is signed.
1.2       perry     562:
1.18      christos  563: *      These functions can account for leap seconds, thanks to Bradley White.
1.6       kleink    564:
1.18      christos  565: Points of interest to folks with other systems:
1.6       kleink    566:
1.22      christos  567: *      Code compatible with this package is already part of many platforms,
                    568:        including GNU/Linux, Android, the BSDs, Chromium OS, Cygwin, AIX, iOS,
                    569:        BlackBery 10, macOS, Microsoft Windows, OpenVMS, and Solaris.
1.18      christos  570:        On such hosts, the primary use of this package
                    571:        is to update obsolete time zone rule tables.
                    572:        To do this, you may need to compile the time zone compiler
                    573:        'zic' supplied with this package instead of using the system 'zic',
1.22      christos  574:        since the format of zic's input is occasionally extended,
                    575:        and a platform may still be shipping an older zic.
1.6       kleink    576:
1.18      christos  577: *      The UNIX Version 7 "timezone" function is not present in this package;
                    578:        it's impossible to reliably map timezone's arguments (a "minutes west
                    579:        of GMT" value and a "daylight saving time in effect" flag) to a
                    580:        time zone abbreviation, and we refuse to guess.
                    581:        Programs that in the past used the timezone function may now examine
                    582:        tzname[localtime(&clock)->tm_isdst] to learn the correct time
                    583:        zone abbreviation to use.  Alternatively, use
                    584:        localtime(&clock)->tm_zone if this has been enabled.
1.6       kleink    585:
1.18      christos  586: *      The 4.2BSD gettimeofday function is not used in this package.
                    587:        This formerly let users obtain the current UTC offset and DST flag,
                    588:        but this functionality was removed in later versions of BSD.
1.2       perry     589:
1.18      christos  590: *      In SVR2, time conversion fails for near-minimum or near-maximum
                    591:        time_t values when doing conversions for places that don't use UT.
                    592:        This package takes care to do these conversions correctly.
1.22      christos  593:        A comment in the source code tells how to get compatibly wrong
                    594:        results.
1.2       perry     595:
1.18      christos  596: The functions that are conditionally compiled if STD_INSPIRED is defined
                    597: should, at this point, be looked on primarily as food for thought.  They are
                    598: not in any sense "standard compatible" - some are not, in fact, specified in
                    599: *any* standard.  They do, however, represent responses of various authors to
                    600: standardization proposals.
1.14      christos  601:
1.18      christos  602: Other time conversion proposals, in particular the one developed by folks at
                    603: Hewlett Packard, offer a wider selection of functions that provide capabilities
                    604: beyond those provided here.  The absence of such functions from this package
                    605: is not meant to discourage the development, standardization, or use of such
                    606: functions.  Rather, their absence reflects the decision to make this package
                    607: contain valid extensions to POSIX, to ensure its broad acceptability.  If
                    608: more powerful time conversion functions can be standardized, so much the
                    609: better.
1.4       kleink    610:
                    611:
1.22      christos  612: ----- Interface stability -----
                    613:
                    614: The tz code and data supply the following interfaces:
                    615:
                    616:  * A set of zone names as per "Names of time zone rules" above.
                    617:
                    618:  * Library functions described in "Time and date functions" above.
                    619:
                    620:  * The programs tzselect, zdump, and zic, documented in their man pages.
                    621:
                    622:  * The format of zic input files, documented in the zic man page.
                    623:
                    624:  * The format of zic output files, documented in the tzfile man page.
                    625:
                    626:  * The format of zone table files, documented in zone1970.tab.
                    627:
                    628:  * The format of the country code file, documented in iso3166.tab.
                    629:
1.23    ! christos  630:  * The version number of the code and data, as the first line of
        !           631:    the text file 'version' in each release.
        !           632:
        !           633: Interface changes in a release attempt to preserve compatibility with
        !           634: recent releases.  For example, tz data files typically do not rely on
        !           635: recently-added zic features, so that users can run older zic versions
        !           636: to process newer data files.  The tz-link.htm file describes how
        !           637: releases are tagged and distributed.
1.22      christos  638:
                    639: Interfaces not listed above are less stable.  For example, users
                    640: should not rely on particular UT offsets or abbreviations for time
                    641: stamps, as data entries are often based on guesswork and these guesses
                    642: may be corrected or improved.
                    643:
                    644:
1.4       kleink    645: ----- Calendrical issues -----
                    646:
                    647: Calendrical issues are a bit out of scope for a time zone database,
                    648: but they indicate the sort of problems that we would run into if we
                    649: extended the time zone database further into the past.  An excellent
1.10      christos  650: resource in this area is Nachum Dershowitz and Edward M. Reingold,
1.15      christos  651: Calendrical Calculations: Third Edition, Cambridge University Press (2008)
                    652: <http://emr.cs.iit.edu/home/reingold/calendar-book/third-edition/>.
                    653: Other information and sources are given below.  They sometimes disagree.
1.4       kleink    654:
                    655:
                    656: France
                    657:
                    658: Gregorian calendar adopted 1582-12-20.
                    659: French Revolutionary calendar used 1793-11-24 through 1805-12-31,
                    660: and (in Paris only) 1871-05-06 through 1871-05-23.
                    661:
                    662:
                    663: Russia
                    664:
1.9       mlelstv   665: From Chris Carrier (1996-12-02):
1.14      christos  666: On 1929-10-01 the Soviet Union instituted an "Eternal Calendar"
1.4       kleink    667: with 30-day months plus 5 holidays, with a 5-day week.
                    668: On 1931-12-01 it changed to a 6-day week; in 1934 it reverted to the
                    669: Gregorian calendar while retaining the 6-day week; on 1940-06-27 it
                    670: reverted to the 7-day week.  With the 6-day week the usual days
                    671: off were the 6th, 12th, 18th, 24th and 30th of the month.
                    672: (Source: Evitiar Zerubavel, _The Seven Day Circle_)
                    673:
                    674:
                    675: Mark Brader reported a similar story in "The Book of Calendars", edited
                    676: by Frank Parise (1982, Facts on File, ISBN 0-8719-6467-8), page 377.  But:
                    677:
                    678: From: Petteri Sulonen (via Usenet)
                    679: Date: 14 Jan 1999 00:00:00 GMT
1.9       mlelstv   680: ...
1.4       kleink    681:
1.15      christos  682: If your source is correct, how come documents between 1929 and 1940 were
1.4       kleink    683: still dated using the conventional, Gregorian calendar?
                    684:
                    685: I can post a scan of a document dated December 1, 1934, signed by
                    686: Yenukidze, the secretary, on behalf of Kalinin, the President of the
                    687: Executive Committee of the Supreme Soviet, if you like.
                    688:
                    689:
                    690:
                    691: Sweden (and Finland)
                    692:
1.9       mlelstv   693: From: Mark Brader
1.15      christos  694: Subject: Re: Gregorian reform - a part of locale?
                    695: <news:1996Jul6.012937.29190@sq.com>
1.4       kleink    696: Date: 1996-07-06
                    697:
                    698: In 1700, Denmark made the transition from Julian to Gregorian.  Sweden
                    699: decided to *start* a transition in 1700 as well, but rather than have one of
                    700: those unsightly calendar gaps :-), they simply decreed that the next leap
1.15      christos  701: year after 1696 would be in 1744 - putting the whole country on a calendar
1.4       kleink    702: different from both Julian and Gregorian for a period of 40 years.
                    703:
                    704: However, in 1704 something went wrong and the plan was not carried through;
                    705: they did, after all, have a leap year that year.  And one in 1708.  In 1712
                    706: they gave it up and went back to Julian, putting 30 days in February that
                    707: year!...
                    708:
                    709: Then in 1753, Sweden made the transition to Gregorian in the usual manner,
                    710: getting there only 13 years behind the original schedule.
                    711:
                    712: (A previous posting of this story was challenged, and Swedish readers
1.15      christos  713: produced the following references to support it: "Tideräkning och historia"
                    714: by Natanael Beckman (1924) and "Tid, en bok om tideräkning och
                    715: kalenderväsen" by Lars-Olof Lodén (1968).
1.4       kleink    716:
                    717:
                    718: Grotefend's data
                    719:
1.9       mlelstv   720: From: "Michael Palmer" [with one obvious typo fixed]
1.4       kleink    721: Subject: Re: Gregorian Calendar (was Re: Another FHC related question
                    722: Newsgroups: soc.genealogy.german
                    723: Date: Tue, 9 Feb 1999 02:32:48 -800
1.9       mlelstv   724: ...
1.4       kleink    725:
1.6       kleink    726: The following is a(n incomplete) listing, arranged chronologically, of
                    727: European states, with the date they converted from the Julian to the
1.4       kleink    728: Gregorian calendar:
                    729:
                    730: 04/15 Oct 1582 - Italy (with exceptions), Spain, Portugal, Poland (Roman
                    731:                  Catholics and Danzig only)
                    732: 09/20 Dec 1582 - France, Lorraine
                    733:
                    734: 21 Dec 1582/
                    735:    01 Jan 1583 - Holland, Brabant, Flanders, Hennegau
1.15      christos  736: 10/21 Feb 1583 - bishopric of Liege (Lüttich)
1.4       kleink    737: 13/24 Feb 1583 - bishopric of Augsburg
                    738: 04/15 Oct 1583 - electorate of Trier
                    739: 05/16 Oct 1583 - Bavaria, bishoprics of Freising, Eichstedt, Regensburg,
                    740:                  Salzburg, Brixen
1.15      christos  741: 13/24 Oct 1583 - Austrian Oberelsaß and Breisgau
1.4       kleink    742: 20/31 Oct 1583 - bishopric of Basel
1.15      christos  743: 02/13 Nov 1583 - duchy of Jülich-Berg
                    744: 02/13 Nov 1583 - electorate and city of Köln
                    745: 04/15 Nov 1583 - bishopric of Würzburg
1.4       kleink    746: 11/22 Nov 1583 - electorate of Mainz
                    747: 16/27 Nov 1583 - bishopric of Strassburg and the margraviate of Baden
1.15      christos  748: 17/28 Nov 1583 - bishopric of Münster and duchy of Cleve
1.4       kleink    749: 14/25 Dec 1583 - Steiermark
                    750:
                    751: 06/17 Jan 1584 - Austria and Bohemia
1.15      christos  752: 11/22 Jan 1584 - Lucerne, Uri, Schwyz, Zug, Freiburg, Solothurn
1.4       kleink    753: 12/23 Jan 1584 - Silesia and the Lausitz
                    754: 22 Jan/
                    755:    02 Feb 1584 - Hungary (legally on 21 Oct 1587)
                    756:       Jun 1584 - Unterwalden
                    757: 01/12 Jul 1584 - duchy of Westfalen
                    758:
                    759: 16/27 Jun 1585 - bishopric of Paderborn
                    760:
                    761: 14/25 Dec 1590 - Transylvania
                    762:
                    763: 22 Aug/
                    764:    02 Sep 1612 - duchy of Prussia
                    765:
                    766: 13/24 Dec 1614 - Pfalz-Neuburg
                    767:
                    768:           1617 - duchy of Kurland (reverted to the Julian calendar in
                    769:                  1796)
                    770:
1.15      christos  771:           1624 - bishopric of Osnabrück
1.4       kleink    772:
                    773:           1630 - bishopric of Minden
                    774:
                    775: 15/26 Mar 1631 - bishopric of Hildesheim
                    776:
                    777:           1655 - Kanton Wallis
                    778:
                    779: 05/16 Feb 1682 - city of Strassburg
                    780:
                    781: 18 Feb/
                    782:    01 Mar 1700 - Protestant Germany (including Swedish possessions in
                    783:                  Germany), Denmark, Norway
                    784: 30 Jun/
                    785:    12 Jul 1700 - Gelderland, Zutphen
                    786: 10 Nov/
                    787:    12 Dec 1700 - Utrecht, Overijssel
                    788:
                    789: 31 Dec 1700/
1.15      christos  790:    12 Jan 1701 - Friesland, Groningen, Zürich, Bern, Basel, Geneva,
1.4       kleink    791:                  Turgau, and Schaffhausen
                    792:
                    793:           1724 - Glarus, Appenzell, and the city of St. Gallen
                    794:
                    795: 01 Jan 1750    - Pisa and Florence
                    796:
                    797: 02/14 Sep 1752 - Great Britain
                    798:
                    799: 17 Feb/
                    800:    01 Mar 1753 - Sweden
                    801:
1.15      christos  802: 1760-1812      - Graubünden
1.4       kleink    803:
1.6       kleink    804: The Russian empire (including Finland and the Baltic states) did not
1.4       kleink    805: convert to the Gregorian calendar until the Soviet revolution of 1917.
                    806:
1.16      christos  807: Source: H. Grotefend, _Taschenbuch der Zeitrechnung des deutschen
1.6       kleink    808: Mittelalters und der Neuzeit_, herausgegeben von Dr. O. Grotefend
1.16      christos  809: (Hannover: Hahnsche Buchhandlung, 1941), pp. 26-28.
1.8       kleink    810:
                    811:
                    812: ----- Time and time zones on Mars -----
                    813:
1.17      christos  814: Some people's work schedules use Mars time.  Jet Propulsion Laboratory
                    815: (JPL) coordinators have kept Mars time on and off at least since 1997
                    816: for the Mars Pathfinder mission.  Some of their family members have
                    817: also adapted to Mars time.  Dozens of special Mars watches were built
                    818: for JPL workers who kept Mars time during the Mars Exploration
1.8       kleink    819: Rovers mission (2004).  These timepieces look like normal Seikos and
                    820: Citizens but use Mars seconds rather than terrestrial seconds.
                    821:
                    822: A Mars solar day is called a "sol" and has a mean period equal to
                    823: about 24 hours 39 minutes 35.244 seconds in terrestrial time.  It is
                    824: divided into a conventional 24-hour clock, so each Mars second equals
                    825: about 1.02749125 terrestrial seconds.
                    826:
                    827: The prime meridian of Mars goes through the center of the crater
                    828: Airy-0, named in honor of the British astronomer who built the
                    829: Greenwich telescope that defines Earth's prime meridian.  Mean solar
                    830: time on the Mars prime meridian is called Mars Coordinated Time (MTC).
                    831:
                    832: Each landed mission on Mars has adopted a different reference for
                    833: solar time keeping, so there is no real standard for Mars time zones.
                    834: For example, the Mars Exploration Rover project (2004) defined two
                    835: time zones "Local Solar Time A" and "Local Solar Time B" for its two
                    836: missions, each zone designed so that its time equals local true solar
                    837: time at approximately the middle of the nominal mission.  Such a "time
                    838: zone" is not particularly suited for any application other than the
                    839: mission itself.
                    840:
                    841: Many calendars have been proposed for Mars, but none have achieved
                    842: wide acceptance.  Astronomers often use Mars Sol Date (MSD) which is a
                    843: sequential count of Mars solar days elapsed since about 1873-12-29
                    844: 12:00 GMT.
                    845:
                    846: The tz database does not currently support Mars time, but it is
                    847: documented here in the hopes that support will be added eventually.
                    848:
                    849: Sources:
                    850:
                    851: Michael Allison and Robert Schmunk,
                    852: "Technical Notes on Mars Solar Time as Adopted by the Mars24 Sunclock"
1.13      christos  853: <http://www.giss.nasa.gov/tools/mars24/help/notes.html> (2012-08-08).
1.8       kleink    854:
                    855: Jia-Rui Chong, "Workdays Fit for a Martian", Los Angeles Times
1.13      christos  856: <http://articles.latimes.com/2004/jan/14/science/sci-marstime14>
1.8       kleink    857: (2004-01-14), pp A1, A20-A21.
1.15      christos  858:
1.17      christos  859: Tom Chmielewski, "Jet Lag Is Worse on Mars", The Atlantic (2015-02-26)
                    860: <http://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/>
1.15      christos  861:
                    862: -----
1.18      christos  863:
                    864: This file is in the public domain, so clarified as of 2009-05-17 by
                    865: Arthur David Olson.
                    866:
                    867: -----
1.15      christos  868: Local Variables:
                    869: coding: utf-8
                    870: End:

CVSweb <webmaster@jp.NetBSD.org>