theory.html revision 1.2.2.1
1 1.1 christos <html lang="en"> 2 1.1 christos <head> 3 1.1 christos <title>Theory and pragmatics of the tz code and data</title> 4 1.1 christos <meta charset="UTF-8"> 5 1.1 christos </head> 6 1.1 christos 7 1.1 christos <body> 8 1.2.2.1 pgoyette <h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1> 9 1.1 christos <h3>Outline</h3> 10 1.1 christos <nav> 11 1.1 christos <ul> 12 1.2.2.1 pgoyette <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code> 13 1.2.2.1 pgoyette database</a></li> 14 1.2.2.1 pgoyette <li><a href="#naming">Names of time zone rulesets</a></li> 15 1.1 christos <li><a href="#abbreviations">Time zone abbreviations</a></li> 16 1.2.2.1 pgoyette <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code> 17 1.2.2.1 pgoyette database</a></li> 18 1.1 christos <li><a href="#functions">Time and date functions</a></li> 19 1.1 christos <li><a href="#stability">Interface stability</a></li> 20 1.1 christos <li><a href="#calendar">Calendrical issues</a></li> 21 1.1 christos <li><a href="#planets">Time and time zones on other planets</a></li> 22 1.1 christos </ul> 23 1.1 christos </nav> 24 1.1 christos 25 1.2.2.1 pgoyette <section> 26 1.2.2.1 pgoyette <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2> 27 1.1 christos <p> 28 1.2.2.1 pgoyette The <a 29 1.2.2.1 pgoyette href="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code> 30 1.2.2.1 pgoyette database</a> attempts to record the history and predicted future of 31 1.2.2.1 pgoyette all computer-based clocks that track civil time. 32 1.2.2.1 pgoyette It organizes <a href="tz-link.html">time zone and daylight saving time 33 1.2.2.1 pgoyette data</a> by partitioning the world into <a 34 1.2.2.1 pgoyette href="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">regions</a> 35 1.2.2.1 pgoyette whose clocks all agree about timestamps that occur after the <a 36 1.2.2.1 pgoyette href="https://en.wikipedia.org/wiki/Unix_time">POSIX Epoch</a> 37 1.2.2.1 pgoyette (1970-01-01 00:00:00 <a 38 1.2.2.1 pgoyette href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time"><abbr 39 1.2.2.1 pgoyette title="Coordinated Universal Time">UTC</abbr></a>). 40 1.2.2.1 pgoyette The database labels each such region with a notable location and 41 1.2.2.1 pgoyette records all known clock transitions for that location. 42 1.2.2.1 pgoyette Although 1970 is a somewhat-arbitrary cutoff, there are significant 43 1.2.2.1 pgoyette challenges to moving the cutoff earlier even by a decade or two, due 44 1.2.2.1 pgoyette to the wide variety of local practices before computer timekeeping 45 1.2.2.1 pgoyette became prevalent. 46 1.1 christos </p> 47 1.1 christos 48 1.1 christos <p> 49 1.1 christos Clock transitions before 1970 are recorded for each such location, 50 1.1 christos because most systems support timestamps before 1970 and could 51 1.1 christos misbehave if data entries were omitted for pre-1970 transitions. 52 1.1 christos However, the database is not designed for and does not suffice for 53 1.1 christos applications requiring accurate handling of all past times everywhere, 54 1.1 christos as it would take far too much effort and guesswork to record all 55 1.1 christos details of pre-1970 civil timekeeping. 56 1.2.2.1 pgoyette Although some information outside the scope of the database is 57 1.2 christos collected in a file <code>backzone</code> that is distributed along 58 1.2 christos with the database proper, this file is less reliable and does not 59 1.2 christos necessarily follow database guidelines. 60 1.1 christos </p> 61 1.1 christos 62 1.1 christos <p> 63 1.2.2.1 pgoyette As described below, reference source code for using the 64 1.2.2.1 pgoyette <code><abbr>tz</abbr></code> database is also available. 65 1.2.2.1 pgoyette The <code><abbr>tz</abbr></code> code is upwards compatible with <a 66 1.2.2.1 pgoyette href="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international 67 1.2.2.1 pgoyette standard for <a 68 1.2.2.1 pgoyette href="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems. 69 1.2.2.1 pgoyette As of this writing, the current edition of POSIX is: <a 70 1.2.2.1 pgoyette href="http://pubs.opengroup.org/onlinepubs/9699919799/"> The Open 71 1.2.2.1 pgoyette Group Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018 72 1.2.2.1 pgoyette Edition. 73 1.2.2.1 pgoyette Because the database's scope encompasses real-world changes to civil 74 1.2.2.1 pgoyette timekeeping, its model for describing time is more complex than the 75 1.2.2.1 pgoyette standard and daylight saving times supported by POSIX. 76 1.2.2.1 pgoyette A <code><abbr>tz</abbr></code> region corresponds to a ruleset that can 77 1.2.2.1 pgoyette have more than two changes per year, these changes need not merely 78 1.2.2.1 pgoyette flip back and forth between two alternatives, and the rules themselves 79 1.2.2.1 pgoyette can change at times. 80 1.2.2.1 pgoyette Whether and when a <code><abbr>tz</abbr></code> region changes its 81 1.2.2.1 pgoyette clock, and even the region's notional base offset from UTC, are variable. 82 1.2.2.1 pgoyette It does not always make sense to talk about a region's 83 1.2.2.1 pgoyette "base offset", since it is not necessarily a single number. 84 1.1 christos </p> 85 1.1 christos 86 1.2.2.1 pgoyette </section> 87 1.1 christos 88 1.2.2.1 pgoyette <section> 89 1.2.2.1 pgoyette <h2 id="naming">Names of time zone rulesets</h2> 90 1.1 christos <p> 91 1.2.2.1 pgoyette Each <code><abbr>tz</abbr></code> region has a unique name that 92 1.2.2.1 pgoyette corresponds to a set of time zone rules. 93 1.1 christos Inexperienced users are not expected to select these names unaided. 94 1.1 christos Distributors should provide documentation and/or a simple selection 95 1.2.2.1 pgoyette interface that explains the names; for one example, see the 96 1.2.2.1 pgoyette <code>tzselect</code> program in the <code><abbr>tz</abbr></code> code. 97 1.2.2.1 pgoyette The <a href="http://cldr.unicode.org/">Unicode Common Locale Data 98 1.2.2.1 pgoyette Repository</a> contains data that may be useful for other selection 99 1.2.2.1 pgoyette interfaces. 100 1.1 christos </p> 101 1.1 christos 102 1.1 christos <p> 103 1.2.2.1 pgoyette The naming conventions attempt to strike a balance 104 1.1 christos among the following goals: 105 1.1 christos </p> 106 1.2.2.1 pgoyette 107 1.1 christos <ul> 108 1.1 christos <li> 109 1.2.2.1 pgoyette Uniquely identify every region where clocks have agreed since 1970. 110 1.2.2.1 pgoyette This is essential for the intended use: static clocks keeping local 111 1.2.2.1 pgoyette civil time. 112 1.1 christos </li> 113 1.1 christos <li> 114 1.2.2.1 pgoyette Indicate to experts where that region is. 115 1.1 christos </li> 116 1.1 christos <li> 117 1.2.2.1 pgoyette Be robust in the presence of political changes. 118 1.2.2.1 pgoyette For example, names of countries are ordinarily not used, to avoid 119 1.2.2.1 pgoyette incompatibilities when countries change their name (e.g., 120 1.2.2.1 pgoyette Zaire→Congo) or when locations change countries (e.g., Hong 121 1.2.2.1 pgoyette Kong from UK colony to China). 122 1.1 christos </li> 123 1.1 christos <li> 124 1.2.2.1 pgoyette Be portable to a wide variety of implementations. 125 1.1 christos </li> 126 1.1 christos <li> 127 1.2.2.1 pgoyette Use a consistent naming conventions over the entire world. 128 1.1 christos </li> 129 1.1 christos </ul> 130 1.2.2.1 pgoyette 131 1.1 christos <p> 132 1.2.2.1 pgoyette Names normally have the form 133 1.2.2.1 pgoyette <var>AREA</var><code>/</code><var>LOCATION</var>, where 134 1.2.2.1 pgoyette <var>AREA</var> is the name of a continent or ocean, and 135 1.2.2.1 pgoyette <var>LOCATION</var> is the name of a specific location within that 136 1.2.2.1 pgoyette region. 137 1.2.2.1 pgoyette North and South America share the same area, '<code>America</code>'. 138 1.2.2.1 pgoyette Typical names are '<code>Africa/Cairo</code>', 139 1.2.2.1 pgoyette '<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'. 140 1.2.2.1 pgoyette Some names are further qualified to help avoid confusion; for example, 141 1.2.2.1 pgoyette '<code>America/Indiana/Petersburg</code>' distinguishes Petersburg, 142 1.2.2.1 pgoyette Indiana from other Petersburgs in America. 143 1.1 christos </p> 144 1.1 christos 145 1.1 christos <p> 146 1.2.2.1 pgoyette Here are the general guidelines used for 147 1.2.2.1 pgoyette choosing <code><abbr>tz</abbr></code> region names, 148 1.1 christos in decreasing order of importance: 149 1.1 christos </p> 150 1.2.2.1 pgoyette 151 1.1 christos <ul> 152 1.1 christos <li> 153 1.2.2.1 pgoyette Use only valid POSIX file name components (i.e., the parts of 154 1.2.2.1 pgoyette names other than '<code>/</code>'). 155 1.2.2.1 pgoyette Do not use the file name components '<code>.</code>' and 156 1.2.2.1 pgoyette '<code>..</code>'. 157 1.2.2.1 pgoyette Within a file name component, use only <a 158 1.2.2.1 pgoyette href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters, 159 1.2.2.1 pgoyette '<code>.</code>', '<code>-</code>' and '<code>_</code>'. 160 1.2.2.1 pgoyette Do not use digits, as that might create an ambiguity with <a 161 1.2.2.1 pgoyette href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX 162 1.2.2.1 pgoyette <code>TZ</code> strings</a>. 163 1.2.2.1 pgoyette A file name component must not exceed 14 characters or start with 164 1.2.2.1 pgoyette '<code>-</code>'. 165 1.2.2.1 pgoyette E.g., prefer <code>Asia/Brunei</code> to 166 1.2.2.1 pgoyette <code>Asia/Bandar_Seri_Begawan</code>. 167 1.2.2.1 pgoyette Exceptions: see the discussion of legacy names below. 168 1.1 christos </li> 169 1.1 christos <li> 170 1.2.2.1 pgoyette A name must not be empty, or contain '<code>//</code>', or 171 1.2.2.1 pgoyette start or end with '<code>/</code>'. 172 1.1 christos </li> 173 1.1 christos <li> 174 1.2.2.1 pgoyette Do not use names that differ only in case. 175 1.2.2.1 pgoyette Although the reference implementation is case-sensitive, some 176 1.2.2.1 pgoyette other implementations are not, and they would mishandle names 177 1.2.2.1 pgoyette differing only in case. 178 1.1 christos </li> 179 1.1 christos <li> 180 1.2.2.1 pgoyette If one name <var>A</var> is an initial prefix of another 181 1.2.2.1 pgoyette name <var>AB</var> (ignoring case), then <var>B</var> must not 182 1.2.2.1 pgoyette start with '<code>/</code>', as a regular file cannot have the 183 1.2.2.1 pgoyette same name as a directory in POSIX. 184 1.2.2.1 pgoyette For example, <code>America/New_York</code> precludes 185 1.2.2.1 pgoyette <code>America/New_York/Bronx</code>. 186 1.1 christos </li> 187 1.1 christos <li> 188 1.2.2.1 pgoyette Uninhabited regions like the North Pole and Bouvet Island 189 1.2.2.1 pgoyette do not need locations, since local time is not defined there. 190 1.1 christos </li> 191 1.1 christos <li> 192 1.2.2.1 pgoyette There should typically be at least one name for each <a 193 1.2.2.1 pgoyette href="https://en.wikipedia.org/wiki/ISO_3166-1"><abbr 194 1.2.2.1 pgoyette title="International Organization for Standardization">ISO</abbr> 195 1.2.2.1 pgoyette 3166-1</a> officially assigned two-letter code for an inhabited 196 1.2.2.1 pgoyette country or territory. 197 1.1 christos </li> 198 1.1 christos <li> 199 1.2.2.1 pgoyette If all the clocks in a region have agreed since 1970, 200 1.2.2.1 pgoyette do not bother to include more than one location 201 1.2.2.1 pgoyette even if subregions' clocks disagreed before 1970. 202 1.2.2.1 pgoyette Otherwise these tables would become annoyingly large. 203 1.1 christos </li> 204 1.1 christos <li> 205 1.2.2.1 pgoyette If a name is ambiguous, use a less ambiguous alternative; 206 1.2.2.1 pgoyette e.g., many cities are named San Jos and Georgetown, so 207 1.2.2.1 pgoyette prefer <code>America/Costa_Rica</code> to 208 1.2.2.1 pgoyette <code>America/San_Jose</code> and <code>America/Guyana</code> 209 1.2.2.1 pgoyette to <code>America/Georgetown</code>. 210 1.1 christos </li> 211 1.1 christos <li> 212 1.2.2.1 pgoyette Keep locations compact. 213 1.2.2.1 pgoyette Use cities or small islands, not countries or regions, so that any 214 1.2.2.1 pgoyette future changes do not split individual locations into different 215 1.2.2.1 pgoyette <code><abbr>tz</abbr></code> regions. 216 1.2.2.1 pgoyette E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>, 217 1.2.2.1 pgoyette since 218 1.2.2.1 pgoyette <a href="https://en.wikipedia.org/wiki/Time_in_France#History">France 219 1.2.2.1 pgoyette has had multiple time zones</a>. 220 1.1 christos </li> 221 1.1 christos <li> 222 1.2.2.1 pgoyette Use mainstream English spelling, e.g., prefer 223 1.2.2.1 pgoyette <code>Europe/Rome</code> to <code>Europe/Roma</code>, and 224 1.2.2.1 pgoyette prefer <code>Europe/Athens</code> to the Greek 225 1.2.2.1 pgoyette <code>Europe/</code> or the Romanized 226 1.2.2.1 pgoyette <code>Europe/Athna</code>. 227 1.2.2.1 pgoyette The POSIX file name restrictions encourage this guideline. 228 1.1 christos </li> 229 1.1 christos <li> 230 1.2.2.1 pgoyette Use the most populous among locations in a region, 231 1.2.2.1 pgoyette e.g., prefer <code>Asia/Shanghai</code> to 232 1.2.2.1 pgoyette <code>Asia/Beijing</code>. 233 1.2.2.1 pgoyette Among locations with similar populations, pick the best-known 234 1.2.2.1 pgoyette location, e.g., prefer <code>Europe/Rome</code> to 235 1.2.2.1 pgoyette <code>Europe/Milan</code>. 236 1.1 christos </li> 237 1.1 christos <li> 238 1.2.2.1 pgoyette Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to 239 1.2.2.1 pgoyette <code>Atlantic/Canaries</code>. 240 1.1 christos </li> 241 1.1 christos <li> 242 1.2.2.1 pgoyette Omit common suffixes like '<code>_Islands</code>' and 243 1.2.2.1 pgoyette '<code>_City</code>', unless that would lead to ambiguity. 244 1.2.2.1 pgoyette E.g., prefer <code>America/Cayman</code> to 245 1.2.2.1 pgoyette <code>America/Cayman_Islands</code> and 246 1.2.2.1 pgoyette <code>America/Guatemala</code> to 247 1.2.2.1 pgoyette <code>America/Guatemala_City</code>, but prefer 248 1.2.2.1 pgoyette <code>America/Mexico_City</code> to 249 1.2.2.1 pgoyette <code>America/Mexico</code> 250 1.2.2.1 pgoyette because <a href="https://en.wikipedia.org/wiki/Time_in_Mexico">the 251 1.2.2.1 pgoyette country of Mexico has several time zones</a>. 252 1.1 christos </li> 253 1.1 christos <li> 254 1.2.2.1 pgoyette Use '<code>_</code>' to represent a space. 255 1.1 christos </li> 256 1.1 christos <li> 257 1.2.2.1 pgoyette Omit '<code>.</code>' from abbreviations in names. 258 1.2.2.1 pgoyette E.g., prefer <code>Atlantic/St_Helena</code> to 259 1.2.2.1 pgoyette <code>Atlantic/St._Helena</code>. 260 1.1 christos </li> 261 1.1 christos <li> 262 1.2.2.1 pgoyette Do not change established names if they only marginally violate 263 1.2.2.1 pgoyette the above guidelines. 264 1.2.2.1 pgoyette For example, do not change the existing name <code>Europe/Rome</code> to 265 1.2.2.1 pgoyette <code>Europe/Milan</code> merely because Milan's population has grown 266 1.2.2.1 pgoyette to be somewhat greater than Rome's. 267 1.1 christos </li> 268 1.1 christos <li> 269 1.2.2.1 pgoyette If a name is changed, put its old spelling in the 270 1.2.2.1 pgoyette '<code>backward</code>' file. 271 1.2.2.1 pgoyette This means old spellings will continue to work. 272 1.1 christos </li> 273 1.1 christos </ul> 274 1.1 christos 275 1.1 christos <p> 276 1.1 christos The file '<code>zone1970.tab</code>' lists geographical locations used 277 1.2.2.1 pgoyette to name <code><abbr>tz</abbr></code> regions. 278 1.2.2.1 pgoyette It is intended to be an exhaustive list of names for geographic 279 1.2.2.1 pgoyette regions as described above; this is a subset of the names in the data. 280 1.2.2.1 pgoyette Although a '<code>zone1970.tab</code>' location's 281 1.2.2.1 pgoyette <a href="https://en.wikipedia.org/wiki/Longitude">longitude</a> 282 1.2.2.1 pgoyette corresponds to 283 1.2.2.1 pgoyette its <a href="https://en.wikipedia.org/wiki/Local_mean_time">local mean 284 1.2.2.1 pgoyette time (<abbr>LMT</abbr>)</a> offset with one hour for every 15° 285 1.2.2.1 pgoyette east longitude, this relationship is not exact. 286 1.1 christos </p> 287 1.1 christos 288 1.1 christos <p> 289 1.1 christos Older versions of this package used a different naming scheme, 290 1.1 christos and these older names are still supported. 291 1.1 christos See the file '<code>backward</code>' for most of these older names 292 1.1 christos (e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>'). 293 1.1 christos The other old-fashioned names still supported are 294 1.2.2.1 pgoyette '<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and 295 1.2.2.1 pgoyette '<code>EET</code>' (see the file '<code>europe</code>'). 296 1.1 christos </p> 297 1.1 christos 298 1.1 christos <p> 299 1.1 christos Older versions of this package defined legacy names that are 300 1.2.2.1 pgoyette incompatible with the first guideline of location names, but which are 301 1.2.2.1 pgoyette still supported. 302 1.2.2.1 pgoyette These legacy names are mostly defined in the file 303 1.2.2.1 pgoyette '<code>etcetera</code>'. 304 1.2.2.1 pgoyette Also, the file '<code>backward</code>' defines the legacy names 305 1.2.2.1 pgoyette '<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>', 306 1.2.2.1 pgoyette and the file '<code>northamerica</code>' defines the legacy names 307 1.2.2.1 pgoyette '<code>EST5EDT</code>', '<code>CST6CDT</code>', 308 1.2.2.1 pgoyette '<code>MST7MDT</code>', and '<code>PST8PDT</code>'. 309 1.1 christos </p> 310 1.1 christos 311 1.1 christos <p> 312 1.2.2.1 pgoyette Excluding '<code>backward</code>' should not affect the other data. 313 1.2.2.1 pgoyette If '<code>backward</code>' is excluded, excluding 314 1.2.2.1 pgoyette '<code>etcetera</code>' should not affect the remaining data. 315 1.1 christos </p> 316 1.2.2.1 pgoyette </section> 317 1.1 christos 318 1.2.2.1 pgoyette <section> 319 1.2.2.1 pgoyette <h2 id="abbreviations">Time zone abbreviations</h2> 320 1.1 christos <p> 321 1.1 christos When this package is installed, it generates time zone abbreviations 322 1.1 christos like '<code>EST</code>' to be compatible with human tradition and POSIX. 323 1.2.2.1 pgoyette Here are the general guidelines used for choosing time zone abbreviations, 324 1.1 christos in decreasing order of importance: 325 1.2.2.1 pgoyette </p> 326 1.2.2.1 pgoyette 327 1.1 christos <ul> 328 1.1 christos <li> 329 1.2.2.1 pgoyette Use three to six characters that are ASCII alphanumerics or 330 1.2.2.1 pgoyette '<code>+</code>' or '<code>-</code>'. 331 1.2.2.1 pgoyette Previous editions of this database also used characters like 332 1.2.2.1 pgoyette space and '<code>?</code>', but these characters have a 333 1.2.2.1 pgoyette special meaning to the 334 1.2.2.1 pgoyette <a href="https://en.wikipedia.org/wiki/Unix_shell">UNIX shell</a> 335 1.2.2.1 pgoyette and cause commands like 336 1.2.2.1 pgoyette '<code><a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a> 337 1.2.2.1 pgoyette `<a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>' 338 1.2.2.1 pgoyette to have unexpected effects. 339 1.2.2.1 pgoyette Previous editions of this guideline required upper-case letters, but the 340 1.2.2.1 pgoyette Congressman who introduced 341 1.2.2.1 pgoyette <a href="https://en.wikipedia.org/wiki/Chamorro_Time_Zone">Chamorro 342 1.2.2.1 pgoyette Standard Time</a> preferred "ChST", so lower-case letters are now 343 1.2.2.1 pgoyette allowed. 344 1.2.2.1 pgoyette Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>', 345 1.2.2.1 pgoyette '<code>+</code>', and alphanumeric characters from the portable 346 1.2.2.1 pgoyette character set in the current locale. 347 1.2.2.1 pgoyette In practice ASCII alphanumerics and '<code>+</code>' and 348 1.2.2.1 pgoyette '<code>-</code>' are safe in all locales. 349 1.2.2.1 pgoyette 350 1.2.2.1 pgoyette <p> 351 1.2.2.1 pgoyette In other words, in the C locale the POSIX extended regular 352 1.2.2.1 pgoyette expression <code>[-+[:alnum:]]{3,6}</code> should match the 353 1.2.2.1 pgoyette abbreviation. 354 1.2.2.1 pgoyette This guarantees that all abbreviations could have been specified by a 355 1.2.2.1 pgoyette POSIX <code>TZ</code> string. 356 1.2.2.1 pgoyette </p> 357 1.2.2.1 pgoyette </li> 358 1.2.2.1 pgoyette <li> 359 1.2.2.1 pgoyette Use abbreviations that are in common use among English-speakers, 360 1.2.2.1 pgoyette e.g., 'EST' for Eastern Standard Time in North America. 361 1.2.2.1 pgoyette We assume that applications translate them to other languages 362 1.2.2.1 pgoyette as part of the normal localization process; for example, 363 1.2.2.1 pgoyette a French application might translate 'EST' to 'HNE'. 364 1.2.2.1 pgoyette 365 1.2.2.1 pgoyette <p> 366 1.2.2.1 pgoyette <small>These abbreviations (for standard/daylight/etc. time) are: 367 1.2.2.1 pgoyette ACST/ACDT Australian Central, 368 1.2.2.1 pgoyette AST/ADT/APT/AWT/ADDT Atlantic, 369 1.2.2.1 pgoyette AEST/AEDT Australian Eastern, 370 1.2.2.1 pgoyette AHST/AHDT Alaska-Hawaii, 371 1.2.2.1 pgoyette AKST/AKDT Alaska, 372 1.2.2.1 pgoyette AWST/AWDT Australian Western, 373 1.2.2.1 pgoyette BST/BDT Bering, 374 1.2.2.1 pgoyette CAT/CAST Central Africa, 375 1.2.2.1 pgoyette CET/CEST/CEMT Central European, 376 1.2.2.1 pgoyette ChST Chamorro, 377 1.2.2.1 pgoyette CST/CDT/CWT/CPT/CDDT Central [North America], 378 1.2.2.1 pgoyette CST/CDT China, 379 1.2.2.1 pgoyette GMT/BST/IST/BDST Greenwich, 380 1.2.2.1 pgoyette EAT East Africa, 381 1.2.2.1 pgoyette EST/EDT/EWT/EPT/EDDT Eastern [North America], 382 1.2.2.1 pgoyette EET/EEST Eastern European, 383 1.2.2.1 pgoyette GST Guam, 384 1.2.2.1 pgoyette HST/HDT Hawaii, 385 1.2.2.1 pgoyette HKT/HKST Hong Kong, 386 1.2.2.1 pgoyette IST India, 387 1.2.2.1 pgoyette IST/GMT Irish, 388 1.2.2.1 pgoyette IST/IDT/IDDT Israel, 389 1.2.2.1 pgoyette JST/JDT Japan, 390 1.2.2.1 pgoyette KST/KDT Korea, 391 1.2.2.1 pgoyette MET/MEST Middle European (a backward-compatibility alias for 392 1.2.2.1 pgoyette Central European), 393 1.2.2.1 pgoyette MSK/MSD Moscow, 394 1.2.2.1 pgoyette MST/MDT/MWT/MPT/MDDT Mountain, 395 1.2.2.1 pgoyette NST/NDT/NWT/NPT/NDDT Newfoundland, 396 1.2.2.1 pgoyette NST/NDT/NWT/NPT Nome, 397 1.2.2.1 pgoyette NZMT/NZST New Zealand through 1945, 398 1.2.2.1 pgoyette NZST/NZDT New Zealand 1946–present, 399 1.2.2.1 pgoyette PKT/PKST Pakistan, 400 1.2.2.1 pgoyette PST/PDT/PWT/PPT/PDDT Pacific, 401 1.2.2.1 pgoyette SAST South Africa, 402 1.2.2.1 pgoyette SST Samoa, 403 1.2.2.1 pgoyette WAT/WAST West Africa, 404 1.2.2.1 pgoyette WET/WEST/WEMT Western European, 405 1.2.2.1 pgoyette WIB Waktu Indonesia Barat, 406 1.2.2.1 pgoyette WIT Waktu Indonesia Timur, 407 1.2.2.1 pgoyette WITA Waktu Indonesia Tengah, 408 1.2.2.1 pgoyette YST/YDT/YWT/YPT/YDDT Yukon</small>. 409 1.2.2.1 pgoyette </p> 410 1.2.2.1 pgoyette </li> 411 1.2.2.1 pgoyette <li> 412 1.2.2.1 pgoyette <p> 413 1.2.2.1 pgoyette For times taken from a city's longitude, use the 414 1.2.2.1 pgoyette traditional <var>x</var>MT notation. 415 1.2.2.1 pgoyette The only abbreviation like this in current use is '<abbr>GMT</abbr>'. 416 1.2.2.1 pgoyette The others are for timestamps before 1960, 417 1.2.2.1 pgoyette except that Monrovia Mean Time persisted until 1972. 418 1.2.2.1 pgoyette Typically, numeric abbreviations (e.g., '<code>-</code>004430' for 419 1.2.2.1 pgoyette MMT) would cause trouble here, as the numeric strings would exceed 420 1.2.2.1 pgoyette the POSIX length limit. 421 1.2.2.1 pgoyette </p> 422 1.2.2.1 pgoyette 423 1.2.2.1 pgoyette <p> 424 1.2.2.1 pgoyette <small>These abbreviations are: 425 1.2.2.1 pgoyette AMT Amsterdam, Asuncin, Athens; 426 1.2.2.1 pgoyette BMT Baghdad, Bangkok, Batavia, Bern, Bogot, Bridgetown, Brussels, 427 1.2.2.1 pgoyette Bucharest; 428 1.2.2.1 pgoyette CMT Calamarca, Caracas, Chisinau, Coln, Copenhagen, Crdoba; 429 1.2.2.1 pgoyette DMT Dublin/Dunsink; 430 1.2.2.1 pgoyette EMT Easter; 431 1.2.2.1 pgoyette FFMT Fort-de-France; 432 1.2.2.1 pgoyette FMT Funchal; 433 1.2.2.1 pgoyette GMT Greenwich; 434 1.2.2.1 pgoyette HMT Havana, Helsinki, Horta, Howrah; 435 1.2.2.1 pgoyette IMT Irkutsk, Istanbul; 436 1.2.2.1 pgoyette JMT Jerusalem; 437 1.2.2.1 pgoyette KMT Kaunas, Kiev, Kingston; 438 1.2.2.1 pgoyette LMT Lima, Lisbon, local, Luanda; 439 1.2.2.1 pgoyette MMT Macassar, Madras, Mal, Managua, Minsk, Monrovia, Montevideo, 440 1.2.2.1 pgoyette Moratuwa, Moscow; 441 1.2.2.1 pgoyette PLMT Ph Lin; 442 1.2.2.1 pgoyette PMT Paramaribo, Paris, Perm, Pontianak, Prague; 443 1.2.2.1 pgoyette PMMT Port Moresby; 444 1.2.2.1 pgoyette QMT Quito; 445 1.2.2.1 pgoyette RMT Rangoon, Riga, Rome; 446 1.2.2.1 pgoyette SDMT Santo Domingo; 447 1.2.2.1 pgoyette SJMT San Jos; 448 1.2.2.1 pgoyette SMT Santiago, Simferopol, Singapore, Stanley; 449 1.2.2.1 pgoyette TBMT Tbilisi; 450 1.2.2.1 pgoyette TMT Tallinn, Tehran; 451 1.2.2.1 pgoyette WMT Warsaw</small>. 452 1.2.2.1 pgoyette </p> 453 1.2.2.1 pgoyette 454 1.2.2.1 pgoyette <p> 455 1.2.2.1 pgoyette <small>A few abbreviations also follow the pattern that 456 1.2.2.1 pgoyette <abbr>GMT<abbr>/<abbr>BST</abbr> established for time in the UK. 457 1.2.2.1 pgoyette They are: 458 1.2.2.1 pgoyette CMT/BST for Calamarca Mean Time and Bolivian Summer Time 459 1.2.2.1 pgoyette 1890–1932, 460 1.2.2.1 pgoyette DMT/IST for Dublin/Dunsink Mean Time and Irish Summer Time 461 1.2.2.1 pgoyette 1880–1916, 462 1.2.2.1 pgoyette MMT/MST/MDST for Moscow 1880–1919, and 463 1.2.2.1 pgoyette RMT/LST for Riga Mean Time and Latvian Summer time 1880–1926. 464 1.2.2.1 pgoyette An extra-special case is SET for Swedish Time (<em>svensk 465 1.2.2.1 pgoyette normaltid</em>) 1879–1899, 3° west of the Stockholm 466 1.2.2.1 pgoyette Observatory.</small> 467 1.2.2.1 pgoyette </p> 468 1.2.2.1 pgoyette </li> 469 1.2.2.1 pgoyette <li> 470 1.2.2.1 pgoyette Use '<abbr>LMT</abbr>' for local mean time of locations before the 471 1.2.2.1 pgoyette introduction of standard time; see "<a href="#scope">Scope of the 472 1.2.2.1 pgoyette <code><abbr>tz</abbr></code> database</a>". 473 1.2.2.1 pgoyette </li> 474 1.2.2.1 pgoyette <li> 475 1.2.2.1 pgoyette If there is no common English abbreviation, use numeric offsets like 476 1.2.2.1 pgoyette <code>-</code>05 and <code>+</code>0830 that are generated 477 1.2.2.1 pgoyette by <code>zic</code>'s <code>%z</code> notation. 478 1.2.2.1 pgoyette </li> 479 1.2.2.1 pgoyette <li> 480 1.2.2.1 pgoyette Use current abbreviations for older timestamps to avoid confusion. 481 1.2.2.1 pgoyette For example, in 1910 a common English abbreviation for time 482 1.2.2.1 pgoyette in central Europe was 'MEZ' (short for both "Middle European 483 1.2.2.1 pgoyette Zone" and for "Mitteleuropische Zeit" in German). 484 1.2.2.1 pgoyette Nowadays 'CET' ("Central European Time") is more common in 485 1.2.2.1 pgoyette English, and the database uses 'CET' even for circa-1910 486 1.2.2.1 pgoyette timestamps as this is less confusing for modern users and avoids 487 1.2.2.1 pgoyette the need for determining when 'CET' supplanted 'MEZ' in common 488 1.2.2.1 pgoyette usage. 489 1.2.2.1 pgoyette </li> 490 1.2.2.1 pgoyette <li> 491 1.2.2.1 pgoyette Use a consistent style in a <code><abbr>tz</abbr></code> region's history. 492 1.2.2.1 pgoyette For example, if history tends to use numeric 493 1.2.2.1 pgoyette abbreviations and a particular entry could go either way, use a 494 1.2.2.1 pgoyette numeric abbreviation. 495 1.2.2.1 pgoyette </li> 496 1.2.2.1 pgoyette <li> 497 1.2.2.1 pgoyette Use 498 1.2.2.1 pgoyette <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a> 499 1.2.2.1 pgoyette (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for 500 1.2.2.1 pgoyette locations while uninhabited. 501 1.2.2.1 pgoyette The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in 502 1.2.2.1 pgoyette some sense undefined; this notation is derived 503 1.2.2.1 pgoyette from <a href="https://tools.ietf.org/html/rfc3339">Internet 504 1.2.2.1 pgoyette <abbr title="Request For Comments">RFC 3339</a>. 505 1.1 christos </li> 506 1.1 christos </ul> 507 1.2.2.1 pgoyette 508 1.1 christos <p> 509 1.1 christos Application writers should note that these abbreviations are ambiguous 510 1.2 christos in practice: e.g., 'CST' means one thing in China and something else 511 1.2 christos in North America, and 'IST' can refer to time in India, Ireland or 512 1.2.2.1 pgoyette Israel. 513 1.2.2.1 pgoyette To avoid ambiguity, use numeric <abbr>UT</abbr> offsets like 514 1.2 christos '<code>-</code>0600' instead of time zone abbreviations like 'CST'. 515 1.1 christos </p> 516 1.2.2.1 pgoyette </section> 517 1.1 christos 518 1.2.2.1 pgoyette <section> 519 1.2.2.1 pgoyette <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2> 520 1.1 christos <p> 521 1.2.2.1 pgoyette The <code><abbr>tz</abbr></code> database is not authoritative, and it 522 1.2.2.1 pgoyette surely has errors. 523 1.2 christos Corrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>. 524 1.1 christos Users requiring authoritative data should consult national standards 525 1.1 christos bodies and the references cited in the database's comments. 526 1.1 christos </p> 527 1.1 christos 528 1.1 christos <p> 529 1.2.2.1 pgoyette Errors in the <code><abbr>tz</abbr></code> database arise from many sources: 530 1.1 christos </p> 531 1.2.2.1 pgoyette 532 1.1 christos <ul> 533 1.1 christos <li> 534 1.2.2.1 pgoyette The <code><abbr>tz</abbr></code> database predicts future 535 1.2.2.1 pgoyette timestamps, and current predictions 536 1.2.2.1 pgoyette will be incorrect after future governments change the rules. 537 1.2.2.1 pgoyette For example, if today someone schedules a meeting for 13:00 next 538 1.2.2.1 pgoyette October 1, Casablanca time, and tomorrow Morocco changes its 539 1.2.2.1 pgoyette daylight saving rules, software can mess up after the rule change 540 1.2.2.1 pgoyette if it blithely relies on conversions made before the change. 541 1.2.2.1 pgoyette </li> 542 1.2.2.1 pgoyette <li> 543 1.2.2.1 pgoyette The pre-1970 entries in this database cover only a tiny sliver of how 544 1.2.2.1 pgoyette clocks actually behaved; the vast majority of the necessary 545 1.2.2.1 pgoyette information was lost or never recorded. 546 1.2.2.1 pgoyette Thousands more <code><abbr>tz</abbr></code> regions would be needed if 547 1.2.2.1 pgoyette the <code><abbr>tz</abbr></code> database's scope were extended to 548 1.2.2.1 pgoyette cover even just the known or guessed history of standard time; for 549 1.2.2.1 pgoyette example, the current single entry for France would need to split 550 1.2.2.1 pgoyette into dozens of entries, perhaps hundreds. 551 1.2.2.1 pgoyette And in most of the world even this approach would be misleading 552 1.2.2.1 pgoyette due to widespread disagreement or indifference about what times 553 1.2.2.1 pgoyette should be observed. 554 1.2.2.1 pgoyette In her 2015 book 555 1.2.2.1 pgoyette <cite><a 556 1.2.2.1 pgoyette href="http://www.hup.harvard.edu/catalog.php?isbn=9780674286146">The 557 1.2.2.1 pgoyette Global Transformation of Time, 1870–1950</a></cite>, 558 1.2.2.1 pgoyette Vanessa Ogle writes 559 1.2.2.1 pgoyette "Outside of Europe and North America there was no system of time 560 1.2.2.1 pgoyette zones at all, often not even a stable landscape of mean times, 561 1.2.2.1 pgoyette prior to the middle decades of the twentieth century". 562 1.2.2.1 pgoyette See: Timothy Shenk, <a 563 1.2.2.1 pgoyette href="https://www.dissentmagazine.org/blog/booked-a-global-history-of-time-vanessa-ogle">Booked: 564 1.2.2.1 pgoyette A Global History of Time</a>. <cite>Dissent</cite> 2015-12-17. 565 1.2.2.1 pgoyette </li> 566 1.2.2.1 pgoyette <li> 567 1.2.2.1 pgoyette Most of the pre-1970 data entries come from unreliable sources, often 568 1.2.2.1 pgoyette astrology books that lack citations and whose compilers evidently 569 1.2.2.1 pgoyette invented entries when the true facts were unknown, without 570 1.2.2.1 pgoyette reporting which entries were known and which were invented. 571 1.2.2.1 pgoyette These books often contradict each other or give implausible entries, 572 1.2.2.1 pgoyette and on the rare occasions when they are checked they are 573 1.2.2.1 pgoyette typically found to be incorrect. 574 1.2.2.1 pgoyette </li> 575 1.2.2.1 pgoyette <li> 576 1.2.2.1 pgoyette For the UK the <code><abbr>tz</abbr></code> database relies on 577 1.2.2.1 pgoyette years of first-class work done by 578 1.2.2.1 pgoyette Joseph Myers and others; see 579 1.2.2.1 pgoyette "<a href="https://www.polyomino.org.uk/british-time/">History of 580 1.2.2.1 pgoyette legal time in Britain</a>". 581 1.2.2.1 pgoyette Other countries are not done nearly as well. 582 1.2.2.1 pgoyette </li> 583 1.2.2.1 pgoyette <li> 584 1.2.2.1 pgoyette Sometimes, different people in the same city maintain clocks 585 1.2.2.1 pgoyette that differ significantly. 586 1.2.2.1 pgoyette Historically, railway time was used by railroad companies (which 587 1.2.2.1 pgoyette did not always 588 1.2.2.1 pgoyette agree with each other), church-clock time was used for birth 589 1.2.2.1 pgoyette certificates, etc. 590 1.2.2.1 pgoyette More recently, competing political groups might disagree about 591 1.2.2.1 pgoyette clock settings. Often this is merely common practice, but 592 1.2.2.1 pgoyette sometimes it is set by law. 593 1.2.2.1 pgoyette For example, from 1891 to 1911 the <abbr>UT</abbr> offset in France 594 1.2.2.1 pgoyette was legally <abbr>UT</abbr> +00:09:21 outside train stations and 595 1.2.2.1 pgoyette <abbr>UT</abbr> +00:04:21 inside. Other examples include 596 1.2.2.1 pgoyette Chillicothe in 1920, Palm Springs in 1946/7, and Jerusalem and 597 1.2.2.1 pgoyette rmqi to this day. 598 1.2.2.1 pgoyette </li> 599 1.2.2.1 pgoyette <li> 600 1.2.2.1 pgoyette Although a named location in the <code><abbr>tz</abbr></code> 601 1.2.2.1 pgoyette database stands for the containing region, its pre-1970 data 602 1.2.2.1 pgoyette entries are often accurate for only a small subset of that region. 603 1.2.2.1 pgoyette For example, <code>Europe/London</code> stands for the United 604 1.2.2.1 pgoyette Kingdom, but its pre-1847 times are valid only for locations that 605 1.2.2.1 pgoyette have London's exact meridian, and its 1847 transition 606 1.2.2.1 pgoyette to <abbr>GMT</abbr> is known to be valid only for the L&NW and 607 1.2.2.1 pgoyette the Caledonian railways. 608 1.2.2.1 pgoyette </li> 609 1.2.2.1 pgoyette <li> 610 1.2.2.1 pgoyette The <code><abbr>tz</abbr></code> database does not record the 611 1.2.2.1 pgoyette earliest time for which a <code><abbr>tz</abbr></code> region's 612 1.2.2.1 pgoyette data entries are thereafter valid for every location in the region. 613 1.2.2.1 pgoyette For example, <code>Europe/London</code> is valid for all locations 614 1.2.2.1 pgoyette in its region after <abbr>GMT</abbr> was made the standard time, 615 1.2.2.1 pgoyette but the date of standardization (1880-08-02) is not in the 616 1.2.2.1 pgoyette <code><abbr>tz</abbr></code> database, other than in commentary. 617 1.2.2.1 pgoyette For many <code><abbr>tz</abbr></code> regions the earliest time of 618 1.2.2.1 pgoyette validity is unknown. 619 1.2.2.1 pgoyette </li> 620 1.2.2.1 pgoyette <li> 621 1.2.2.1 pgoyette The <code><abbr>tz</abbr></code> database does not record a 622 1.2.2.1 pgoyette region's boundaries, and in many cases the boundaries are not known. 623 1.2.2.1 pgoyette For example, the <code><abbr>tz</abbr></code> region 624 1.2.2.1 pgoyette <code>America/Kentucky/Louisville</code> represents a region 625 1.2.2.1 pgoyette around the city of Louisville, the boundaries of which are 626 1.2.2.1 pgoyette unclear. 627 1.2.2.1 pgoyette </li> 628 1.2.2.1 pgoyette <li> 629 1.2.2.1 pgoyette Changes that are modeled as instantaneous transitions in the 630 1.2.2.1 pgoyette <code><abbr>tz</abbr></code> 631 1.2.2.1 pgoyette database were often spread out over hours, days, or even decades. 632 1.2.2.1 pgoyette </li> 633 1.2.2.1 pgoyette <li> 634 1.2.2.1 pgoyette Even if the time is specified by law, locations sometimes 635 1.2.2.1 pgoyette deliberately flout the law. 636 1.2.2.1 pgoyette </li> 637 1.2.2.1 pgoyette <li> 638 1.2.2.1 pgoyette Early timekeeping practices, even assuming perfect clocks, were 639 1.2.2.1 pgoyette often not specified to the accuracy that the 640 1.2.2.1 pgoyette <code><abbr>tz</abbr></code> database requires. 641 1.2.2.1 pgoyette </li> 642 1.2.2.1 pgoyette <li> 643 1.2.2.1 pgoyette Sometimes historical timekeeping was specified more precisely 644 1.2.2.1 pgoyette than what the <code><abbr>tz</abbr></code> code can handle. 645 1.2.2.1 pgoyette For example, from 1909 to 1937 <a 646 1.2.2.1 pgoyette href="https://www.staff.science.uu.nl/~gent0113/wettijd/wettijd.htm" 647 1.2.2.1 pgoyette hreflang="nl">Netherlands clocks</a> were legally Amsterdam Mean 648 1.2.2.1 pgoyette Time (estimated to be <abbr>UT</abbr> 649 1.2.2.1 pgoyette +00:19:32.13), but the <code><abbr>tz</abbr></code> 650 1.2.2.1 pgoyette code cannot represent the fractional second. 651 1.2.2.1 pgoyette In practice these old specifications were rarely if ever 652 1.2.2.1 pgoyette implemented to subsecond precision. 653 1.2.2.1 pgoyette </li> 654 1.2.2.1 pgoyette <li> 655 1.2.2.1 pgoyette Even when all the timestamp transitions recorded by the 656 1.2.2.1 pgoyette <code><abbr>tz</abbr></code> database are correct, the 657 1.2.2.1 pgoyette <code><abbr>tz</abbr></code> rules that generate them may not 658 1.2.2.1 pgoyette faithfully reflect the historical rules. 659 1.2.2.1 pgoyette For example, from 1922 until World War II the UK moved clocks 660 1.2.2.1 pgoyette forward the day following the third Saturday in April unless that 661 1.2.2.1 pgoyette was Easter, in which case it moved clocks forward the previous 662 1.2.2.1 pgoyette Sunday. 663 1.2.2.1 pgoyette Because the <code><abbr>tz</abbr></code> database has no 664 1.2.2.1 pgoyette way to specify Easter, these exceptional years are entered as 665 1.2.2.1 pgoyette separate <code><abbr>tz</abbr> Rule</code> lines, even though the 666 1.2.2.1 pgoyette legal rules did not change. 667 1.2.2.1 pgoyette </li> 668 1.2.2.1 pgoyette <li> 669 1.2.2.1 pgoyette The <code><abbr>tz</abbr></code> database models pre-standard time 670 1.2.2.1 pgoyette using the <a 671 1.2.2.1 pgoyette href="https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar">proleptic 672 1.2.2.1 pgoyette Gregorian calendar</a> and local mean time, but many people used 673 1.2.2.1 pgoyette other calendars and other timescales. 674 1.2.2.1 pgoyette For example, the Roman Empire used 675 1.2.2.1 pgoyette the <a href="https://en.wikipedia.org/wiki/Julian_calendar">Julian 676 1.2.2.1 pgoyette calendar</a>, 677 1.2.2.1 pgoyette and <a href="https://en.wikipedia.org/wiki/Roman_timekeeping">Roman 678 1.2.2.1 pgoyette timekeeping</a> had twelve varying-length daytime hours with a 679 1.2.2.1 pgoyette non-hour-based system at night. 680 1.2.2.1 pgoyette </li> 681 1.2.2.1 pgoyette <li> 682 1.2.2.1 pgoyette Early clocks were less reliable, and data entries do not represent 683 1.2.2.1 pgoyette clock error. 684 1.2.2.1 pgoyette </li> 685 1.2.2.1 pgoyette <li> 686 1.2.2.1 pgoyette The <code><abbr>tz</abbr></code> database assumes Universal Time 687 1.2.2.1 pgoyette (<abbr>UT</abbr>) as an origin, even though <abbr>UT</abbr> is not 688 1.2.2.1 pgoyette standardized for older timestamps. 689 1.2.2.1 pgoyette In the <code><abbr>tz</abbr></code> database commentary, 690 1.2.2.1 pgoyette <abbr>UT</abbr> denotes a family of time standards that includes 691 1.2.2.1 pgoyette Coordinated Universal Time (<abbr>UTC</abbr>) along with other 692 1.2.2.1 pgoyette variants such as <abbr>UT1</abbr> and <abbr>GMT</abbr>, 693 1.2.2.1 pgoyette with days starting at midnight. 694 1.2.2.1 pgoyette Although <abbr>UT</abbr> equals <abbr>UTC</abbr> for modern 695 1.2.2.1 pgoyette timestamps, <abbr>UTC</abbr> was not defined until 1960, so 696 1.2.2.1 pgoyette commentary uses the more-general abbreviation <abbr>UT</abbr> for 697 1.2.2.1 pgoyette timestamps that might predate 1960. 698 1.2.2.1 pgoyette Since <abbr>UT</abbr>, <abbr>UT1</abbr>, etc. disagree slightly, 699 1.2.2.1 pgoyette and since pre-1972 <abbr>UTC</abbr> seconds varied in length, 700 1.2.2.1 pgoyette interpretation of older timestamps can be problematic when 701 1.2.2.1 pgoyette subsecond accuracy is needed. 702 1.2.2.1 pgoyette </li> 703 1.2.2.1 pgoyette <li> 704 1.2.2.1 pgoyette Civil time was not based on atomic time before 1972, and we do not 705 1.2.2.1 pgoyette know the history of 706 1.2.2.1 pgoyette <a href="https://en.wikipedia.org/wiki/Earth's_rotation">earth's 707 1.2.2.1 pgoyette rotation</a> accurately enough to map <a 708 1.2.2.1 pgoyette href="https://en.wikipedia.org/wiki/International_System_of_Units"><abbr 709 1.2.2.1 pgoyette title="International System of Units">SI</abbr></a> seconds to 710 1.2.2.1 pgoyette historical <a href="https://en.wikipedia.org/wiki/Solar_time">solar time</a> 711 1.2.2.1 pgoyette to more than about one-hour accuracy. 712 1.2.2.1 pgoyette See: Stephenson FR, Morrison LV, Hohenkerk CY. 713 1.2.2.1 pgoyette <a href="http://dx.doi.org/10.1098/rspa.2016.0404">Measurement of 714 1.2.2.1 pgoyette the Earth's rotation: 720 BC to AD 2015</a>. 715 1.2.2.1 pgoyette <cite>Proc Royal Soc A</cite>. 2016 Dec 7;472:20160404. 716 1.2.2.1 pgoyette Also see: Espenak F. <a 717 1.2.2.1 pgoyette href="https://eclipse.gsfc.nasa.gov/SEhelp/uncertainty2004.html">Uncertainty 718 1.2.2.1 pgoyette in Delta T (T)</a>. 719 1.2.2.1 pgoyette </li> 720 1.2.2.1 pgoyette <li> 721 1.2.2.1 pgoyette The relationship between POSIX time (that is, <abbr>UTC</abbr> but 722 1.2.2.1 pgoyette ignoring <a href="https://en.wikipedia.org/wiki/Leap_second">leap 723 1.2.2.1 pgoyette seconds</a>) and <abbr>UTC</abbr> is not agreed upon after 1972. 724 1.2.2.1 pgoyette Although the POSIX 725 1.2.2.1 pgoyette clock officially stops during an inserted leap second, at least one 726 1.2.2.1 pgoyette proposed standard has it jumping back a second instead; and in 727 1.2.2.1 pgoyette practice POSIX clocks more typically either progress glacially during 728 1.2.2.1 pgoyette a leap second, or are slightly slowed while near a leap second. 729 1.2.2.1 pgoyette </li> 730 1.2.2.1 pgoyette <li> 731 1.2.2.1 pgoyette The <code><abbr>tz</abbr></code> database does not represent how 732 1.2.2.1 pgoyette uncertain its information is. 733 1.2.2.1 pgoyette Ideally it would contain information about when data entries are 734 1.2.2.1 pgoyette incomplete or dicey. 735 1.2.2.1 pgoyette Partial temporal knowledge is a field of active research, though, 736 1.2.2.1 pgoyette and it is not clear how to apply it here. 737 1.1 christos </li> 738 1.1 christos </ul> 739 1.1 christos 740 1.1 christos <p> 741 1.2.2.1 pgoyette In short, many, perhaps most, of the <code><abbr>tz</abbr></code> 742 1.2.2.1 pgoyette database's pre-1970 and future timestamps are either wrong or 743 1.2.2.1 pgoyette misleading. 744 1.2.2.1 pgoyette Any attempt to pass the 745 1.2.2.1 pgoyette <code><abbr>tz</abbr></code> database off as the definition of time 746 1.2.2.1 pgoyette should be unacceptable to anybody who cares about the facts. 747 1.2.2.1 pgoyette In particular, the <code><abbr>tz</abbr></code> database's 748 1.2.2.1 pgoyette <abbr>LMT</abbr> offsets should not be considered meaningful, and 749 1.2.2.1 pgoyette should not prompt creation of <code><abbr>tz</abbr></code> regions 750 1.2.2.1 pgoyette merely because two locations 751 1.2.2.1 pgoyette differ in <abbr>LMT</abbr> or transitioned to standard time at 752 1.2.2.1 pgoyette different dates. 753 1.2.2.1 pgoyette </p> 754 1.2.2.1 pgoyette </section> 755 1.2.2.1 pgoyette 756 1.2.2.1 pgoyette <section> 757 1.2.2.1 pgoyette <h2 id="functions">Time and date functions</h2> 758 1.2.2.1 pgoyette <p> 759 1.2.2.1 pgoyette The <code><abbr>tz</abbr></code> code contains time and date functions 760 1.2.2.1 pgoyette that are upwards compatible with those of POSIX. 761 1.2.2.1 pgoyette Code compatible with this package is already 762 1.2.2.1 pgoyette <a href="tz-link.html#tzdb">part of many platforms</a>, where the 763 1.2.2.1 pgoyette primary use of this package is to update obsolete time-related files. 764 1.2.2.1 pgoyette To do this, you may need to compile the time zone compiler 765 1.2.2.1 pgoyette '<code>zic</code>' supplied with this package instead of using the 766 1.2.2.1 pgoyette system '<code>zic</code>', since the format of <code>zic</code>'s 767 1.2.2.1 pgoyette input is occasionally extended, and a platform may still be shipping 768 1.2.2.1 pgoyette an older <code>zic</code>. 769 1.1 christos </p> 770 1.1 christos 771 1.2.2.1 pgoyette <h3 id="POSIX">POSIX properties and limitations</h3> 772 1.1 christos <ul> 773 1.1 christos <li> 774 1.1 christos <p> 775 1.2.2.1 pgoyette In POSIX, time display in a process is controlled by the 776 1.2.2.1 pgoyette environment variable <code>TZ</code>. 777 1.2.2.1 pgoyette Unfortunately, the POSIX 778 1.2.2.1 pgoyette <code>TZ</code> string takes a form that is hard to describe and 779 1.2.2.1 pgoyette is error-prone in practice. 780 1.2.2.1 pgoyette Also, POSIX <code>TZ</code> strings cannot deal with daylight 781 1.2.2.1 pgoyette saving time rules not based on the Gregorian calendar (as in 782 1.2.2.1 pgoyette Iran), or with situations where more than two time zone 783 1.2.2.1 pgoyette abbreviations or <abbr>UT</abbr> offsets are used in an area. 784 1.1 christos </p> 785 1.2.2.1 pgoyette 786 1.1 christos <p> 787 1.2.2.1 pgoyette The POSIX <code>TZ</code> string takes the following form: 788 1.1 christos </p> 789 1.2.2.1 pgoyette 790 1.1 christos <p> 791 1.2.2.1 pgoyette <var>stdoffset</var>[<var>dst</var>[<var>offset</var>][<code>,</code><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]]] 792 1.1 christos </p> 793 1.2.2.1 pgoyette 794 1.1 christos <p> 795 1.2.2.1 pgoyette where: 796 1.2.2.1 pgoyette </p> 797 1.2.2.1 pgoyette 798 1.1 christos <dl> 799 1.1 christos <dt><var>std</var> and <var>dst</var></dt><dd> 800 1.2.2.1 pgoyette are 3 or more characters specifying the standard 801 1.2.2.1 pgoyette and daylight saving time (<abbr>DST</abbr>) zone names. 802 1.2.2.1 pgoyette Starting with POSIX.1-2001, <var>std</var> and <var>dst</var> 803 1.2.2.1 pgoyette may also be in a quoted form like '<code><+09></code>'; 804 1.2.2.1 pgoyette this allows "<code>+</code>" and "<code>-</code>" in the names. 805 1.1 christos </dd> 806 1.1 christos <dt><var>offset</var></dt><dd> 807 1.2.2.1 pgoyette is of the form 808 1.2.2.1 pgoyette '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>' 809 1.2.2.1 pgoyette and specifies the offset west of <abbr>UT</abbr>. 810 1.2.2.1 pgoyette '<var>hh</var>' may be a single digit; 811 1.2.2.1 pgoyette 0≤<var>hh</var>≤24. 812 1.2.2.1 pgoyette The default <abbr>DST</abbr> offset is one hour ahead of 813 1.2.2.1 pgoyette standard time. 814 1.1 christos </dd> 815 1.1 christos <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd> 816 1.2.2.1 pgoyette specifies the beginning and end of <abbr>DST</abbr>. 817 1.2.2.1 pgoyette If this is absent, the system supplies its own ruleset 818 1.2.2.1 pgoyette for <abbr>DST</abbr>, and its rules can differ from year to year; 819 1.2.2.1 pgoyette typically <abbr>US</abbr> <abbr>DST</abbr> rules are used. 820 1.1 christos </dd> 821 1.1 christos <dt><var>time</var></dt><dd> 822 1.2.2.1 pgoyette takes the form 823 1.2.2.1 pgoyette '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]' 824 1.2.2.1 pgoyette and defaults to 02:00. 825 1.2.2.1 pgoyette This is the same format as the offset, except that a 826 1.2.2.1 pgoyette leading '<code>+</code>' or '<code>-</code>' is not allowed. 827 1.1 christos </dd> 828 1.1 christos <dt><var>date</var></dt><dd> 829 1.2.2.1 pgoyette takes one of the following forms: 830 1.1 christos <dl> 831 1.1 christos <dt>J<var>n</var> (1≤<var>n</var>≤365)</dt><dd> 832 1.2.2.1 pgoyette origin-1 day number not counting February 29 833 1.2.2.1 pgoyette </dd> 834 1.1 christos <dt><var>n</var> (0≤<var>n</var>≤365)</dt><dd> 835 1.2.2.1 pgoyette origin-0 day number counting February 29 if present 836 1.2.2.1 pgoyette </dd> 837 1.2.2.1 pgoyette <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var> 838 1.2.2.1 pgoyette (0[Sunday]≤<var>d</var>≤6[Saturday], 1≤<var>n</var>≤5, 839 1.2.2.1 pgoyette 1≤<var>m</var>≤12)</dt><dd> 840 1.2.2.1 pgoyette for the <var>d</var>th day of week <var>n</var> of 841 1.2.2.1 pgoyette month <var>m</var> of the year, where week 1 is the first 842 1.2.2.1 pgoyette week in which day <var>d</var> appears, and 843 1.2.2.1 pgoyette '<code>5</code>' stands for the last week in which 844 1.2.2.1 pgoyette day <var>d</var> appears (which may be either the 4th or 845 1.2.2.1 pgoyette 5th week). 846 1.2.2.1 pgoyette Typically, this is the only useful form; the <var>n</var> 847 1.2.2.1 pgoyette and <code>J</code><var>n</var> forms are rarely used. 848 1.1 christos </dd> 849 1.2.2.1 pgoyette </dl> 850 1.2.2.1 pgoyette </dd> 851 1.2.2.1 pgoyette </dl> 852 1.2.2.1 pgoyette 853 1.2.2.1 pgoyette <p> 854 1.2.2.1 pgoyette Here is an example POSIX <code>TZ</code> string for New 855 1.2.2.1 pgoyette Zealand after 2007. 856 1.2.2.1 pgoyette It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead 857 1.2.2.1 pgoyette of <abbr>UT</abbr>, and that daylight saving time 858 1.2.2.1 pgoyette (<abbr>NZDT</abbr>) is observed from September's last Sunday at 859 1.2.2.1 pgoyette 02:00 until April's first Sunday at 03:00: 860 1.2.2.1 pgoyette </p> 861 1.2.2.1 pgoyette 862 1.2.2.1 pgoyette <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre> 863 1.2.2.1 pgoyette 864 1.2.2.1 pgoyette <p> 865 1.2.2.1 pgoyette This POSIX <code>TZ</code> string is hard to remember, and 866 1.2.2.1 pgoyette mishandles some timestamps before 2008. 867 1.2.2.1 pgoyette With this package you can use this instead: 868 1.2.2.1 pgoyette </p> 869 1.2.2.1 pgoyette 870 1.2.2.1 pgoyette <pre><code>TZ='Pacific/Auckland'</code></pre> 871 1.2.2.1 pgoyette </li> 872 1.2.2.1 pgoyette <li> 873 1.2.2.1 pgoyette POSIX does not define the exact meaning of <code>TZ</code> values like 874 1.2.2.1 pgoyette "<code>EST5EDT</code>". 875 1.2.2.1 pgoyette Typically the current <abbr>US</abbr> <abbr>DST</abbr> rules 876 1.2.2.1 pgoyette are used to interpret such values, but this means that the 877 1.2.2.1 pgoyette <abbr>US</abbr> <abbr>DST</abbr> rules are compiled into each 878 1.2.2.1 pgoyette program that does time conversion. 879 1.2.2.1 pgoyette This means that when 880 1.2.2.1 pgoyette <abbr>US</abbr> time conversion rules change (as in the United 881 1.2.2.1 pgoyette States in 1987), all programs that do time conversion must be 882 1.2.2.1 pgoyette recompiled to ensure proper results. 883 1.2.2.1 pgoyette </li> 884 1.2.2.1 pgoyette <li> 885 1.2.2.1 pgoyette The <code>TZ</code> environment variable is process-global, which 886 1.2.2.1 pgoyette makes it hard to write efficient, thread-safe applications that 887 1.2.2.1 pgoyette need access to multiple time zone rulesets. 888 1.2.2.1 pgoyette </li> 889 1.2.2.1 pgoyette <li> 890 1.2.2.1 pgoyette In POSIX, there is no tamper-proof way for a process to learn the 891 1.2.2.1 pgoyette system's best idea of local wall clock. 892 1.2.2.1 pgoyette (This is important for applications that an administrator wants 893 1.2.2.1 pgoyette used only at certain times – without regard to whether the 894 1.2.2.1 pgoyette user has fiddled the 895 1.2.2.1 pgoyette <code>TZ</code> environment variable. 896 1.2.2.1 pgoyette While an administrator can "do everything in <abbr>UT</abbr>" to 897 1.2.2.1 pgoyette get around the problem, doing so is inconvenient and precludes 898 1.2.2.1 pgoyette handling daylight saving time shifts - as might be required to 899 1.2.2.1 pgoyette limit phone calls to off-peak hours.) 900 1.2.2.1 pgoyette </li> 901 1.2.2.1 pgoyette <li> 902 1.2.2.1 pgoyette POSIX provides no convenient and efficient way to determine 903 1.2.2.1 pgoyette the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary 904 1.2.2.1 pgoyette timestamps, particularly for <code><abbr>tz</abbr></code> regions 905 1.2.2.1 pgoyette that do not fit into the POSIX model. 906 1.2.2.1 pgoyette </li> 907 1.2.2.1 pgoyette <li> 908 1.2.2.1 pgoyette POSIX requires that systems ignore leap seconds. 909 1.2.2.1 pgoyette </li> 910 1.2.2.1 pgoyette <li> 911 1.2.2.1 pgoyette The <code><abbr>tz</abbr></code> code attempts to support all the 912 1.2.2.1 pgoyette <code>time_t</code> implementations allowed by POSIX. 913 1.2.2.1 pgoyette The <code>time_t</code> type represents a nonnegative count of seconds 914 1.2.2.1 pgoyette since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds. 915 1.2.2.1 pgoyette In practice, <code>time_t</code> is usually a signed 64- or 32-bit 916 1.2.2.1 pgoyette integer; 32-bit signed <code>time_t</code> values stop working after 917 1.2.2.1 pgoyette 2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these 918 1.2.2.1 pgoyette days typically use a signed 64-bit integer. 919 1.2.2.1 pgoyette Unsigned 32-bit integers are used on one or two platforms, and 36-bit 920 1.2.2.1 pgoyette and 40-bit integers are also used occasionally. 921 1.2.2.1 pgoyette Although earlier POSIX versions allowed <code>time_t</code> to be a 922 1.2.2.1 pgoyette floating-point type, this was not supported by any practical systems, 923 1.2.2.1 pgoyette and POSIX.1-2013 and the <code><abbr>tz</abbr></code> code both 924 1.2.2.1 pgoyette require <code>time_t</code> to be an integer type. 925 1.1 christos </li> 926 1.1 christos </ul> 927 1.2.2.1 pgoyette 928 1.2.2.1 pgoyette <h3 id="POSIX-extensions">Extensions to POSIX in the 929 1.2.2.1 pgoyette <code><abbr>tz</abbr></code> code</h3> 930 1.1 christos <ul> 931 1.1 christos <li> 932 1.1 christos <p> 933 1.2.2.1 pgoyette The <code>TZ</code> environment variable is used in generating 934 1.2.2.1 pgoyette the name of a binary file from which time-related information is read 935 1.2.2.1 pgoyette (or is interpreted la POSIX); <code>TZ</code> is no longer 936 1.2.2.1 pgoyette constrained to be a three-letter time zone 937 1.2.2.1 pgoyette abbreviation followed by a number of hours and an optional three-letter 938 1.2.2.1 pgoyette daylight time zone abbreviation. 939 1.2.2.1 pgoyette The daylight saving time rules to be used for a 940 1.2.2.1 pgoyette particular <code><abbr>tz</abbr></code> region are encoded in the 941 1.2.2.1 pgoyette binary file; the format of the file 942 1.2.2.1 pgoyette allows U.S., Australian, and other rules to be encoded, and 943 1.2.2.1 pgoyette allows for situations where more than two time zone 944 1.2.2.1 pgoyette abbreviations are used. 945 1.1 christos </p> 946 1.1 christos <p> 947 1.2.2.1 pgoyette It was recognized that allowing the <code>TZ</code> environment 948 1.2.2.1 pgoyette variable to take on values such as '<code>America/New_York</code>' 949 1.2.2.1 pgoyette might cause "old" programs (that expect <code>TZ</code> to have a 950 1.2.2.1 pgoyette certain form) to operate incorrectly; consideration was given to using 951 1.2.2.1 pgoyette some other environment variable (for example, <code>TIMEZONE</code>) 952 1.2.2.1 pgoyette to hold the string used to generate the binary file's name. 953 1.2.2.1 pgoyette In the end, however, it was decided to continue using 954 1.2.2.1 pgoyette <code>TZ</code>: it is widely used for time zone purposes; 955 1.2.2.1 pgoyette separately maintaining both <code>TZ</code> 956 1.2.2.1 pgoyette and <code>TIMEZONE</code> seemed a nuisance; and systems where 957 1.2.2.1 pgoyette "new" forms of <code>TZ</code> might cause problems can simply 958 1.2.2.1 pgoyette use <code>TZ</code> values such as "<code>EST5EDT</code>" which 959 1.2.2.1 pgoyette can be used both by "new" programs ( la POSIX) and "old" 960 1.2.2.1 pgoyette programs (as zone names and offsets). 961 1.1 christos </p> 962 1.2.2.1 pgoyette </li> 963 1.2.2.1 pgoyette <li> 964 1.2.2.1 pgoyette The code supports platforms with a <abbr>UT</abbr> offset member 965 1.2.2.1 pgoyette in <code>struct tm</code>, e.g., <code>tm_gmtoff</code>. 966 1.2.2.1 pgoyette </li> 967 1.2.2.1 pgoyette <li> 968 1.2.2.1 pgoyette The code supports platforms with a time zone abbreviation member in 969 1.2.2.1 pgoyette <code>struct tm</code>, e.g., <code>tm_zone</code>. 970 1.2.2.1 pgoyette </li> 971 1.2.2.1 pgoyette <li> 972 1.2.2.1 pgoyette Functions <code>tzalloc</code>, <code>tzfree</code>, 973 1.2.2.1 pgoyette <code>localtime_rz</code>, and <code>mktime_z</code> for 974 1.2.2.1 pgoyette more-efficient thread-safe applications that need to use multiple 975 1.2.2.1 pgoyette time zone rulesets. 976 1.2.2.1 pgoyette The <code>tzalloc</code> and <code>tzfree</code> functions 977 1.2.2.1 pgoyette allocate and free objects of type <code>timezone_t</code>, 978 1.2.2.1 pgoyette and <code>localtime_rz</code> and <code>mktime_z</code> are 979 1.2.2.1 pgoyette like <code>localtime_r</code> and <code>mktime</code> with an 980 1.2.2.1 pgoyette extra <code>timezone_t</code> argument. 981 1.2.2.1 pgoyette The functions were inspired by <a href="https://netbsd.org/">NetBSD</a>. 982 1.2.2.1 pgoyette </li> 983 1.2.2.1 pgoyette <li> 984 1.2.2.1 pgoyette A function <code>tzsetwall</code> has been added to arrange for the 985 1.2.2.1 pgoyette system's best approximation to local wall clock time to be delivered 986 1.2.2.1 pgoyette by subsequent calls to <code>localtime</code>. 987 1.2.2.1 pgoyette Source code for portable applications that "must" run on local wall 988 1.2.2.1 pgoyette clock time should call <code>tzsetwall</code>; 989 1.2.2.1 pgoyette if such code is moved to "old" systems that do not 990 1.2.2.1 pgoyette provide <code>tzsetwall</code>, you will not be able to generate an 991 1.2.2.1 pgoyette executable program. 992 1.2.2.1 pgoyette (These functions also arrange for local wall clock time to 993 1.2.2.1 pgoyette be used if <code>tzset</code> is called – directly or 994 1.2.2.1 pgoyette indirectly – and there is no <code>TZ</code> environment 995 1.2.2.1 pgoyette variable; portable applications should not, however, rely on this 996 1.2.2.1 pgoyette behavior since it is not the way <a 997 1.2.2.1 pgoyette href="https://en.wikipedia.org/wiki/UNIX_System_V#SVR2"><abbr>SVR2</abbr></a> 998 1.2.2.1 pgoyette systems behave.) 999 1.2.2.1 pgoyette </li> 1000 1.2.2.1 pgoyette <li> 1001 1.2.2.1 pgoyette Negative <code>time_t</code> values are supported, on systems 1002 1.2.2.1 pgoyette where <code>time_t</code> is signed. 1003 1.2.2.1 pgoyette </li> 1004 1.2.2.1 pgoyette <li> 1005 1.2.2.1 pgoyette These functions can account for leap seconds, thanks to Bradley White. 1006 1.2.2.1 pgoyette </li> 1007 1.1 christos </ul> 1008 1.2.2.1 pgoyette 1009 1.2.2.1 pgoyette <h3 id="vestigial">POSIX features no longer needed</h3> 1010 1.1 christos <p> 1011 1.2.2.1 pgoyette POSIX and <a href="https://en.wikipedia.org/wiki/ISO_C"><abbr>ISO</abbr> C</a> 1012 1.2.2.1 pgoyette define some <a href="https://en.wikipedia.org/wiki/API"><abbr 1013 1.2.2.1 pgoyette title="application programming interface">API</abbr>s</a> that are vestigial: 1014 1.2.2.1 pgoyette they are not needed, and are relics of a too-simple model that does 1015 1.2.2.1 pgoyette not suffice to handle many real-world timestamps. 1016 1.2.2.1 pgoyette Although the <code><abbr>tz</abbr></code> code supports these 1017 1.2.2.1 pgoyette vestigial <abbr>API</abbr>s for backwards compatibility, they should 1018 1.2.2.1 pgoyette be avoided in portable applications. 1019 1.2.2.1 pgoyette The vestigial <abbr>API</abbr>s are: 1020 1.1 christos </p> 1021 1.1 christos <ul> 1022 1.1 christos <li> 1023 1.2.2.1 pgoyette The POSIX <code>tzname</code> variable does not suffice and is no 1024 1.2.2.1 pgoyette longer needed. 1025 1.2.2.1 pgoyette To get a timestamp's time zone abbreviation, consult 1026 1.2.2.1 pgoyette the <code>tm_zone</code> member if available; otherwise, 1027 1.2.2.1 pgoyette use <code>strftime</code>'s <code>"%Z"</code> conversion 1028 1.2.2.1 pgoyette specification. 1029 1.2.2.1 pgoyette </li> 1030 1.2.2.1 pgoyette <li> 1031 1.2.2.1 pgoyette The POSIX <code>daylight</code> and <code>timezone</code> 1032 1.2.2.1 pgoyette variables do not suffice and are no longer needed. 1033 1.2.2.1 pgoyette To get a timestamp's <abbr>UT</abbr> offset, consult 1034 1.2.2.1 pgoyette the <code>tm_gmtoff</code> member if available; otherwise, 1035 1.2.2.1 pgoyette subtract values returned by <code>localtime</code> 1036 1.2.2.1 pgoyette and <code>gmtime</code> using the rules of the Gregorian calendar, 1037 1.2.2.1 pgoyette or use <code>strftime</code>'s <code>"%z"</code> conversion 1038 1.2.2.1 pgoyette specification if a string like <code>"+0900"</code> suffices. 1039 1.2.2.1 pgoyette </li> 1040 1.2.2.1 pgoyette <li> 1041 1.2.2.1 pgoyette The <code>tm_isdst</code> member is almost never needed and most of 1042 1.2.2.1 pgoyette its uses should be discouraged in favor of the abovementioned 1043 1.2.2.1 pgoyette <abbr>API</abbr>s. 1044 1.2.2.1 pgoyette Although it can still be used in arguments to 1045 1.2.2.1 pgoyette <code>mktime</code> to disambiguate timestamps near 1046 1.2.2.1 pgoyette a <abbr>DST</abbr> transition when the clock jumps back, this 1047 1.2.2.1 pgoyette disambiguation does not work when standard time itself jumps back, 1048 1.2.2.1 pgoyette which can occur when a location changes to a time zone with a 1049 1.2.2.1 pgoyette lesser <abbr>UT</abbr> offset. 1050 1.1 christos </li> 1051 1.1 christos </ul> 1052 1.1 christos 1053 1.2.2.1 pgoyette <h3 id="other-portability">Other portability notes</h3> 1054 1.2.2.1 pgoyette <ul> 1055 1.2.2.1 pgoyette <li> 1056 1.2.2.1 pgoyette The <a href="https://en.wikipedia.org/wiki/Version_7_Unix">7th Edition 1057 1.2.2.1 pgoyette UNIX</a> <code>timezone</code> function is not present in this 1058 1.2.2.1 pgoyette package; it is impossible to reliably map <code>timezone</code>'s 1059 1.2.2.1 pgoyette arguments (a "minutes west of <abbr>GMT</abbr>" value and a 1060 1.2.2.1 pgoyette "daylight saving time in effect" flag) to a time zone 1061 1.2.2.1 pgoyette abbreviation, and we refuse to guess. 1062 1.2.2.1 pgoyette Programs that in the past used the <code>timezone</code> function 1063 1.2.2.1 pgoyette may now examine <code>localtime(&clock)->tm_zone</code> 1064 1.2.2.1 pgoyette (if <code>TM_ZONE</code> is defined) or 1065 1.2.2.1 pgoyette <code>tzname[localtime(&clock)->tm_isdst]</code> 1066 1.2.2.1 pgoyette (if <code>HAVE_TZNAME</code> is defined) to learn the correct time 1067 1.2.2.1 pgoyette zone abbreviation to use. 1068 1.2.2.1 pgoyette </li> 1069 1.2.2.1 pgoyette <li> 1070 1.2.2.1 pgoyette The <a 1071 1.2.2.1 pgoyette href="https://en.wikipedia.org/wiki/History_of_the_Berkeley_Software_Distribution#4.2BSD"><abbr>4.2BSD</abbr></a> 1072 1.2.2.1 pgoyette <code>gettimeofday</code> function is not 1073 1.2.2.1 pgoyette used in this package. 1074 1.2.2.1 pgoyette This formerly let users obtain the current <abbr>UTC</abbr> offset 1075 1.2.2.1 pgoyette and <abbr>DST</abbr> flag, but this functionality was removed in 1076 1.2.2.1 pgoyette later versions of <abbr>BSD</abbr>. 1077 1.2.2.1 pgoyette </li> 1078 1.2.2.1 pgoyette <li> 1079 1.2.2.1 pgoyette In <abbr>SVR2</abbr>, time conversion fails for near-minimum or 1080 1.2.2.1 pgoyette near-maximum <code>time_t</code> values when doing conversions 1081 1.2.2.1 pgoyette for places that do not use <abbr>UT</abbr>. 1082 1.2.2.1 pgoyette This package takes care to do these conversions correctly. 1083 1.2.2.1 pgoyette A comment in the source code tells how to get compatibly wrong 1084 1.2.2.1 pgoyette results. 1085 1.2.2.1 pgoyette </li> 1086 1.2.2.1 pgoyette <li> 1087 1.2.2.1 pgoyette The functions that are conditionally compiled 1088 1.2.2.1 pgoyette if <code>STD_INSPIRED</code> is defined should, at this point, be 1089 1.2.2.1 pgoyette looked on primarily as food for thought. 1090 1.2.2.1 pgoyette They are not in any sense "standard compatible" – some are 1091 1.2.2.1 pgoyette not, in fact, specified in <em>any</em> standard. 1092 1.2.2.1 pgoyette They do, however, represent responses of various authors to 1093 1.2.2.1 pgoyette standardization proposals. 1094 1.2.2.1 pgoyette </li> 1095 1.2.2.1 pgoyette <li> 1096 1.2.2.1 pgoyette Other time conversion proposals, in particular the one developed 1097 1.2.2.1 pgoyette by folks at Hewlett Packard, offer a wider selection of functions 1098 1.2.2.1 pgoyette that provide capabilities beyond those provided here. 1099 1.2.2.1 pgoyette The absence of such functions from this package is not meant to 1100 1.2.2.1 pgoyette discourage the development, standardization, or use of such 1101 1.2.2.1 pgoyette functions. 1102 1.2.2.1 pgoyette Rather, their absence reflects the decision to make this package 1103 1.2.2.1 pgoyette contain valid extensions to POSIX, to ensure its broad 1104 1.2.2.1 pgoyette acceptability. 1105 1.2.2.1 pgoyette If more powerful time conversion functions can be standardized, so 1106 1.2.2.1 pgoyette much the better. 1107 1.2.2.1 pgoyette </li> 1108 1.2.2.1 pgoyette </ul> 1109 1.2.2.1 pgoyette </section> 1110 1.1 christos 1111 1.2.2.1 pgoyette <section> 1112 1.2.2.1 pgoyette <h2 id="stability">Interface stability</h2> 1113 1.1 christos <p> 1114 1.2.2.1 pgoyette The <code><abbr>tz</abbr></code> code and data supply the following interfaces: 1115 1.1 christos </p> 1116 1.2.2.1 pgoyette 1117 1.1 christos <ul> 1118 1.1 christos <li> 1119 1.2.2.1 pgoyette A set of <code><abbr>tz</abbr></code> region names as per 1120 1.2.2.1 pgoyette "<a href="#naming">Names of time zone rulesets</a>" above. 1121 1.1 christos </li> 1122 1.1 christos <li> 1123 1.2.2.1 pgoyette Library functions described in "<a href="#functions">Time and date 1124 1.2.2.1 pgoyette functions</a>" above. 1125 1.1 christos </li> 1126 1.1 christos <li> 1127 1.2.2.1 pgoyette The programs <code>tzselect</code>, <code>zdump</code>, 1128 1.2.2.1 pgoyette and <code>zic</code>, documented in their man pages. 1129 1.1 christos </li> 1130 1.1 christos <li> 1131 1.2.2.1 pgoyette The format of <code>zic</code> input files, documented in 1132 1.2.2.1 pgoyette the <code>zic</code> man page. 1133 1.1 christos </li> 1134 1.1 christos <li> 1135 1.2.2.1 pgoyette The format of <code>zic</code> output files, documented in 1136 1.2.2.1 pgoyette the <code>tzfile</code> man page. 1137 1.1 christos </li> 1138 1.1 christos <li> 1139 1.2.2.1 pgoyette The format of zone table files, documented in <code>zone1970.tab</code>. 1140 1.1 christos </li> 1141 1.1 christos <li> 1142 1.2.2.1 pgoyette The format of the country code file, documented in <code>iso3166.tab</code>. 1143 1.1 christos </li> 1144 1.1 christos <li> 1145 1.2.2.1 pgoyette The version number of the code and data, as the first line of 1146 1.2.2.1 pgoyette the text file '<code>version</code>' in each release. 1147 1.1 christos </li> 1148 1.1 christos </ul> 1149 1.2.2.1 pgoyette 1150 1.1 christos <p> 1151 1.1 christos Interface changes in a release attempt to preserve compatibility with 1152 1.2.2.1 pgoyette recent releases. 1153 1.2.2.1 pgoyette For example, <code><abbr>tz</abbr></code> data files typically do not 1154 1.2.2.1 pgoyette rely on recently-added <code>zic</code> features, so that users can 1155 1.2.2.1 pgoyette run older <code>zic</code> versions to process newer data files. 1156 1.2.2.1 pgoyette <a href="tz-link.html#download">Downloading 1157 1.2.2.1 pgoyette the <code><abbr>tz</abbr></code> database</a> describes how releases 1158 1.2.2.1 pgoyette are tagged and distributed. 1159 1.1 christos </p> 1160 1.1 christos 1161 1.1 christos <p> 1162 1.2.2.1 pgoyette Interfaces not listed above are less stable. 1163 1.2.2.1 pgoyette For example, users should not rely on particular <abbr>UT</abbr> 1164 1.2.2.1 pgoyette offsets or abbreviations for timestamps, as data entries are often 1165 1.2.2.1 pgoyette based on guesswork and these guesses may be corrected or improved. 1166 1.1 christos </p> 1167 1.2.2.1 pgoyette </section> 1168 1.1 christos 1169 1.2.2.1 pgoyette <section> 1170 1.2.2.1 pgoyette <h2 id="calendar">Calendrical issues</h2> 1171 1.1 christos <p> 1172 1.1 christos Calendrical issues are a bit out of scope for a time zone database, 1173 1.1 christos but they indicate the sort of problems that we would run into if we 1174 1.2.2.1 pgoyette extended the time zone database further into the past. 1175 1.2.2.1 pgoyette An excellent resource in this area is Edward M. Reingold 1176 1.2.2.1 pgoyette and Nachum Dershowitz, <cite><a 1177 1.2.2.1 pgoyette href="https://www.cambridge.org/fr/academic/subjects/computer-science/computing-general-interest/calendrical-calculations-ultimate-edition-4th-edition">Calendrical 1178 1.2.2.1 pgoyette Calculations: The Ultimate Edition</a></cite>, Cambridge University Press (2018). 1179 1.2.2.1 pgoyette Other information and sources are given in the file '<code>calendars</code>' 1180 1.2.2.1 pgoyette in the <code><abbr>tz</abbr></code> distribution. 1181 1.2.2.1 pgoyette They sometimes disagree. 1182 1.2.2.1 pgoyette </p> 1183 1.2.2.1 pgoyette </section> 1184 1.2.2.1 pgoyette 1185 1.2.2.1 pgoyette <section> 1186 1.2.2.1 pgoyette <h2 id="planets">Time and time zones on other planets</h2> 1187 1.2.2.1 pgoyette <p> 1188 1.2.2.1 pgoyette Some people's work schedules 1189 1.2.2.1 pgoyette use <a href="https://en.wikipedia.org/wiki/Timekeeping on Mars">Mars time</a>. 1190 1.2.2.1 pgoyette Jet Propulsion Laboratory (JPL) coordinators kept Mars time on 1191 1.2.2.1 pgoyette and off during the 1192 1.2.2.1 pgoyette <a href="https://en.wikipedia.org/wiki/Mars_Pathfinder#End_of_mission">Mars 1193 1.2.2.1 pgoyette Pathfinder</a> mission. 1194 1.2.2.1 pgoyette Some of their family members also adapted to Mars time. 1195 1.2.2.1 pgoyette Dozens of special Mars watches were built for JPL workers who kept 1196 1.2.2.1 pgoyette Mars time during the Mars Exploration Rovers mission (2004). 1197 1.2.2.1 pgoyette These timepieces look like normal Seikos and Citizens but use Mars 1198 1.2.2.1 pgoyette seconds rather than terrestrial seconds. 1199 1.1 christos </p> 1200 1.1 christos 1201 1.1 christos <p> 1202 1.1 christos A Mars solar day is called a "sol" and has a mean period equal to 1203 1.2.2.1 pgoyette about 24 hours 39 minutes 35.244 seconds in terrestrial time. 1204 1.2.2.1 pgoyette It is divided into a conventional 24-hour clock, so each Mars second 1205 1.2.2.1 pgoyette equals about 1.02749125 terrestrial seconds. 1206 1.1 christos </p> 1207 1.1 christos 1208 1.1 christos <p> 1209 1.2.2.1 pgoyette The <a href="https://en.wikipedia.org/wiki/Prime_meridian">prime 1210 1.2.2.1 pgoyette meridian</a> of Mars goes through the center of the crater 1211 1.2.2.1 pgoyette <a href="https://en.wikipedia.org/wiki/Airy-0">Airy-0</a>, named in 1212 1.2.2.1 pgoyette honor of the British astronomer who built the Greenwich telescope that 1213 1.2.2.1 pgoyette defines Earth's prime meridian. 1214 1.2.2.1 pgoyette Mean solar time on the Mars prime meridian is 1215 1.2.2.1 pgoyette called <a href="https://en.wikipedia.org/wiki/Mars_Coordinated_Time">Mars 1216 1.2.2.1 pgoyette Coordinated Time (<abbr>MTC</abbr>)</a>. 1217 1.1 christos </p> 1218 1.1 christos 1219 1.1 christos <p> 1220 1.1 christos Each landed mission on Mars has adopted a different reference for 1221 1.1 christos solar time keeping, so there is no real standard for Mars time zones. 1222 1.2.2.1 pgoyette For example, the 1223 1.2.2.1 pgoyette <a href="https://en.wikipedia.org/wiki/Mars_Exploration_Rover">Mars 1224 1.2.2.1 pgoyette Exploration Rover</a> project (2004) defined two time zones "Local 1225 1.2.2.1 pgoyette Solar Time A" and "Local Solar Time B" for its two missions, each zone 1226 1.2.2.1 pgoyette designed so that its time equals local true solar time at 1227 1.2.2.1 pgoyette approximately the middle of the nominal mission. 1228 1.2.2.1 pgoyette Such a "time zone" is not particularly suited for any application 1229 1.2.2.1 pgoyette other than the mission itself. 1230 1.1 christos </p> 1231 1.1 christos 1232 1.1 christos <p> 1233 1.1 christos Many calendars have been proposed for Mars, but none have achieved 1234 1.2.2.1 pgoyette wide acceptance. 1235 1.2.2.1 pgoyette Astronomers often use Mars Sol Date (<abbr>MSD</abbr>) which is a 1236 1.1 christos sequential count of Mars solar days elapsed since about 1873-12-29 1237 1.2.2.1 pgoyette 12:00 <abbr>GMT</abbr>. 1238 1.1 christos </p> 1239 1.1 christos 1240 1.1 christos <p> 1241 1.1 christos In our solar system, Mars is the planet with time and calendar most 1242 1.2.2.1 pgoyette like Earth's. 1243 1.2.2.1 pgoyette On other planets, Sun-based time and calendars would work quite 1244 1.2.2.1 pgoyette differently. 1245 1.2.2.1 pgoyette For example, although Mercury's 1246 1.2.2.1 pgoyette <a href="https://en.wikipedia.org/wiki/Rotation_period">sidereal 1247 1.2.2.1 pgoyette rotation period</a> is 58.646 Earth days, Mercury revolves around the 1248 1.2.2.1 pgoyette Sun so rapidly that an observer on Mercury's equator would see a 1249 1.2.2.1 pgoyette sunrise only every 175.97 Earth days, i.e., a Mercury year is 0.5 of a 1250 1.2.2.1 pgoyette Mercury day. 1251 1.2.2.1 pgoyette Venus is more complicated, partly because its rotation is slightly 1252 1.2.2.1 pgoyette <a href="https://en.wikipedia.org/wiki/Retrograde_motion">retrograde</a>: 1253 1.2.2.1 pgoyette its year is 1.92 of its days. 1254 1.2.2.1 pgoyette Gas giants like Jupiter are trickier still, as their polar and 1255 1.2.2.1 pgoyette equatorial regions rotate at different rates, so that the length of a 1256 1.2.2.1 pgoyette day depends on latitude. 1257 1.2.2.1 pgoyette This effect is most pronounced on Neptune, where the day is about 12 1258 1.2.2.1 pgoyette hours at the poles and 18 hours at the equator. 1259 1.1 christos </p> 1260 1.1 christos 1261 1.1 christos <p> 1262 1.2.2.1 pgoyette Although the <code><abbr>tz</abbr></code> database does not support 1263 1.2.2.1 pgoyette time on other planets, it is documented here in the hopes that support 1264 1.2.2.1 pgoyette will be added eventually. 1265 1.1 christos </p> 1266 1.1 christos 1267 1.1 christos <p> 1268 1.2.2.1 pgoyette Sources for time on other planets: 1269 1.1 christos </p> 1270 1.2.2.1 pgoyette 1271 1.1 christos <ul> 1272 1.1 christos <li> 1273 1.2.2.1 pgoyette Michael Allison and Robert Schmunk, 1274 1.2.2.1 pgoyette "<a href="https://www.giss.nasa.gov/tools/mars24/help/notes.html">Technical 1275 1.2.2.1 pgoyette Notes on Mars Solar Time as Adopted by the Mars24 Sunclock</a>" 1276 1.2.2.1 pgoyette (2015-06-30). 1277 1.1 christos </li> 1278 1.1 christos <li> 1279 1.2.2.1 pgoyette Jia-Rui Chong, 1280 1.2.2.1 pgoyette "<a href="http://articles.latimes.com/2004/jan/14/science/sci-marstime14">Workdays 1281 1.2.2.1 pgoyette Fit for a Martian</a>", <cite>Los Angeles Times</cite> 1282 1.2.2.1 pgoyette (2004-01-14), pp A1, A20–A21. 1283 1.1 christos </li> 1284 1.1 christos <li> 1285 1.2.2.1 pgoyette Tom Chmielewski, 1286 1.2.2.1 pgoyette "<a href="https://www.theatlantic.com/technology/archive/2015/02/jet-lag-is-worse-on-mars/386033/">Jet 1287 1.2.2.1 pgoyette Lag Is Worse on Mars</a>", <cite>The Atlantic</cite> (2015-02-26) 1288 1.1 christos </li> 1289 1.1 christos <li> 1290 1.2.2.1 pgoyette Matt Williams, 1291 1.2.2.1 pgoyette "<a href="https://www.universetoday.com/37481/days-of-the-planets/">How 1292 1.2.2.1 pgoyette long is a day on the other planets of the solar system?</a>" 1293 1.2.2.1 pgoyette (2017-04-27). 1294 1.1 christos </li> 1295 1.1 christos </ul> 1296 1.2.2.1 pgoyette </section> 1297 1.1 christos 1298 1.2.2.1 pgoyette <footer> 1299 1.2.2.1 pgoyette <hr> 1300 1.2.2.1 pgoyette This file is in the public domain, so clarified as of 2009-05-17 by 1301 1.2.2.1 pgoyette Arthur David Olson. 1302 1.2.2.1 pgoyette </footer> 1303 1.1 christos </body> 1304 1.1 christos </html> 1305
Indexes created Tue Mar 31 00:22:50 UTC 2026