src/lib/libc/time/Theory - annotate

Return to Theory CVS log

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>