Lines Matching full:code
4 <title>Theory and pragmatics of the tz code and data</title>
15 <h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1>
18 <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code>
22 <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code>
33 <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2>
36 href="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code>
63 <code>America/Denver</code> which observes US-style daylight saving
65 and <code>America/Phoenix</code> which does not observe <abbr>DST</abbr>.
68 <code>America/Boise</code>, <code>America/Edmonton</code>, and
69 <code>America/Hermosillo</code>, each of which currently uses mountain
82 collected in a file <code>backzone</code> that is distributed along
88 As described below, reference source code for using the
89 <code><abbr>tz</abbr></code> database is also available.
90 The <code><abbr>tz</abbr></code> code is upwards compatible with <a
101 <code><abbr>tz</abbr></code> database, which has a
104 A <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can
124 “Czech Republic” instead of the timezone name “<code>Europe/Prague</code>”.
128 <code>tzselect</code> program in the <code><abbr>tz</abbr></code> code.
132 interfaces; it maps timezone names like <code>Europe/Prague</code> to
169 <var>AREA</var><code>/</code><var>LOCATION</var>, where
172 North and South America share the same area, <code>America</code>.
173 Typical names are <code>Africa/Cairo</code>,
174 <code>America/New_York</code>, and <code>Pacific/Honolulu</code>.
176 <code>America/Indiana/Petersburg</code> distinguishes Petersburg,
189 names other than "<code>/</code>").
190 Do not use the file name components "<code>.</code>" and
191 "<code>..</code>".
194 "<code>.</code>", "<code>-</code>" and "<code>_</code>".
197 proleptic <code>TZ</code> strings</a>.
199 "<code>-</code>".
200 E.g., prefer <code>America/Noronha</code> to
201 <code>America/Fernando_de_Noronha</code>.
205 A name must not be empty, or contain "<code>//</code>", or
206 start or end with "<code>/</code>".
207 Also, a name must not be "<code>Etc/Unknown</code>", as
219 start with "<code>/</code>", as a regular file cannot have the
221 For example, <code>America/New_York</code> precludes
222 <code>America/New_York/Bronx</code>.
233 For example, do not create a name <code>Indian/Crozet</code>
234 as a near-duplicate or alias of <code>Asia/Dubai</code>
240 that use <code>Asia/Dubai</code>.
251 prefer <code>America/Costa_Rica</code> to
252 <code>America/San_Jose</code> and <code>America/Guyana</code>
253 to <code>America/Georgetown</code>.
260 E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>,
267 <code>Europe/Rome</code> to <code>Europa/Roma</code>, and
268 prefer <code>Europe/Athens</code> to the Greek
269 <code>Ευρώπη/Αθήνα</code> or the Romanized
270 <code>Evrópi/Athína</code>.
275 e.g., prefer <code>Asia/Shanghai</code> to
276 <code>Asia/Beijing</code>.
278 location, e.g., prefer <code>Europe/Rome</code> to
279 <code>Europe/Milan</code>.
282 Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to
283 <code>Atlantic/Canaries</code>.
286 Omit common suffixes like "<code>_Islands</code>" and
287 "<code>_City</code>", unless that would lead to ambiguity.
288 E.g., prefer <code>America/Cayman</code> to
289 <code>America/Cayman_Islands</code> and
290 <code>America/Guatemala</code> to
291 <code>America/Guatemala_City</code>, but prefer
292 <code>America/Mexico_City</code> to
293 <code>America/Mexico</code>
298 Use "<code>_</code>" to represent a space.
301 Omit "<code>.</code>" from abbreviations in names.
302 E.g., prefer <code>Atlantic/St_Helena</code> to
303 <code>Atlantic/St._Helena</code>.
308 For example, do not change the existing name <code>Europe/Rome</code> to
309 <code>Europe/Milan</code> merely because Milan’s population has grown
314 "<code>backward</code>" file as a link to the new spelling.
318 in 2008 <code>Asia/Calcutta</code> was renamed to <code>Asia/Kolkata</code>
333 See the file "<code>backward</code>" for most of these older names
334 (e.g., <code>US/Eastern</code> instead of <code>America/New_York</code>).
336 <code>WET</code>, <code>CET</code>, <code>MET</code>, and
337 <code>EET</code> (see the file "<code>europe</code>").
345 "<code>etcetera</code>".
346 Also, the file "<code>backward</code>" defines the legacy names
347 <code>Etc/GMT0</code>, <code>Etc/GMT-0</code>, <code>Etc/GMT+0</code>,
348 <code>GMT0</code>, <code>GMT-0</code> and <code>GMT+0</code>,
349 and the file "<code>northamerica</code>" defines the legacy names
350 <code>EST5EDT</code>, <code>CST6CDT</code>,
351 <code>MST7MDT</code>, and <code>PST8PDT</code>.
359 3166-1</a> officially assigned two-letter code for an inhabited
367 The file <code>zone1970.tab</code> lists geographical locations used
371 Although a <code>zone1970.tab</code> location’s
377 The backward-compatibility file <code>zone.tab</code> is similar
379 it lists only one country code per entry and unlike <code>zone1970.tab</code>
380 it can list names defined in <code>backward</code>.
382 <code>zonenow.tab</code>, which partitions the world more coarsely,
384 this file is smaller and simpler than <code>zone1970.tab</code>
385 and <code>zone.tab</code>.
390 The source file <code>backward</code> defines links for backward
392 Although <code>backward</code> was originally designed to be optional,
395 is defined in <code>backward</code> or in some other file.
396 The source file <code>etcetera</code> defines names that may be useful
397 on platforms that do not support proleptic <code>TZ</code> strings
398 like <code><+08>-8</code>;
399 no other source file other than <code>backward</code>
401 One of <code>etcetera</code>’s names is <code>Etc/UTC</code>,
402 used by functions like <code>gmtime</code> to obtain leap
404 Another <code>etcetera</code> name, <code>GMT</code>,
405 is used by older code releases.
413 like <code>EST</code> to be compatible with human tradition and POSIX.
421 "<code>+</code>" or "<code>-</code>".
423 space and "<code>?</code>", but these characters have a
427 …"<code><a href="https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#set">set…
428 … `<a href="https://pubs.opengroup.org/onlinepubs/9799919799/utilities/date.html">date</a>`</code>"
434 Also, POSIX from 2001 on relaxed the rule to allow "<code>-</code>",
435 "<code>+</code>", and alphanumeric characters from the portable
437 In practice ASCII alphanumerics and "<code>+</code>" and
438 "<code>-</code>" are safe in all locales.
442 expression <code>[-+[:alnum:]]{3,6}</code> should match the
445 explicitly by a POSIX proleptic <code>TZ</code> string.
510 Typically, numeric abbreviations (e.g., <code>-</code>004430 for
564 <code><abbr>tz</abbr></code> database</a>”.
568 <code>-</code>05 and <code>+</code>0530 that are generated
569 by <code>zic</code>’s <code>%z</code> notation.
591 (<abbr>UT</abbr>) (with time zone abbreviation <code>-</code>00) for
593 The leading "<code>-</code>" is a flag that the <abbr>UT</abbr> offset is in
611 <code>-</code>0600 instead of time zone abbreviations like CST.
616 <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2>
618 The <code><abbr>tz</abbr></code> database is not authoritative, and it
620 Corrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>.
626 Errors in the <code><abbr>tz</abbr></code> database arise from many sources:
631 The <code><abbr>tz</abbr></code> database predicts future
644 the <code><abbr>tz</abbr></code> database’s scope were extended to
673 For the UK the <code><abbr>tz</abbr></code> database relies on
697 Although a named location in the <code><abbr>tz</abbr></code>
700 For example, <code>Europe/London</code> stands for the United
707 The <code><abbr>tz</abbr></code> database does not record the
710 For example, <code>Europe/London</code> is valid for all locations
713 <code><abbr>tz</abbr></code> database, other than in commentary.
718 The <code><abbr>tz</abbr></code> database does not record a
721 <code>America/Kentucky/Louisville</code> represents a region
727 <code><abbr>tz</abbr></code>
737 <code><abbr>tz</abbr></code> database requires.
740 The <code><abbr>tz</abbr></code> database cannot represent stopped clocks.
743 The <code><abbr>tz</abbr></code> database models this via a
749 than what the <code><abbr>tz</abbr></code> code can handle.
752 −00:25:21.1); although the <code><abbr>tz</abbr></code>
753 source data can represent the .1 second, TZif files and the code cannot.
759 <code><abbr>tz</abbr></code> database are correct, the
760 <code><abbr>tz</abbr></code> rules that generate them may not
766 Because the <code><abbr>tz</abbr></code> database has no
768 separate <code><abbr>tz</abbr> Rule</code> lines, even though the
771 the database contains <code>Zone</code> and <code>Rule</code>
777 The <code><abbr>tz</abbr></code> database models time
797 the scope of the <code><abbr>tz</abbr></code> code and data, which
801 can often do the trick; for example, in Kenya a <code>TZ</code> setting
802 like <code><-03>3</code> or <code>America/Cayenne</code> starts
803 the day six hours later than <code>Africa/Nairobi</code> does.
810 The <code><abbr>tz</abbr></code> database assumes Universal Time
813 In the <code><abbr>tz</abbr></code> database commentary,
856 The <code><abbr>tz</abbr></code> database does not represent how
866 In short, many, perhaps most, of the <code><abbr>tz</abbr></code>
870 <code><abbr>tz</abbr></code> database off as the definition of time
872 In particular, the <code><abbr>tz</abbr></code> database’s
884 The <code><abbr>tz</abbr></code> code contains time and date functions
886 Code compatible with this package is already
890 <code>zic</code> supplied with this package instead of using the
891 system <code>zic</code>, since the format of <code>zic</code>’s
893 an older <code>zic</code>.
898 environment variable <code>TZ</code>, which can have two forms:
902 A <dfn>proleptic <code>TZ</code></dfn> value
903 like <code>CET-1CEST,M3.5.0,M10.5.0/3</code> uses a complex
908 A <dfn>geographical <code>TZ</code></dfn> value
909 like <code>Europe/Berlin</code> names a location that stands for
913 These names are defined by the <code><abbr>tz</abbr></code> database.
922 Code intended to be portable to these platforms must deal
928 POSIX.1-2017 does not require support for geographical <code>TZ</code>,
936 The proleptic <code>TZ</code> string,
939 Also, proleptic <code>TZ</code> strings cannot deal with daylight
946 A proleptic <code>TZ</code> string has the following format:
950 …var>[<var>offset</var>][<code>,</code><var>date</var>[<code>/</code><var>time</var>]<code>,</code>…
962 may also be quoted in angle brackets, like <code><+09></code>;
963 this allows "<code>+</code>" and "<code>-</code>" in the names.
967 <code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>
974 …<dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var…
982 <var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]
985 leading "<code>+</code>" or "<code>-</code>" is not allowed.
996 <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var>
1002 "<code>5</code>" stands for the last week in which
1006 and <code>J</code><var>n</var> forms are rarely used.
1013 Here is an example proleptic <code>TZ</code> string for New
1021 <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
1024 This proleptic <code>TZ</code> string is hard to remember, and
1026 With this package you can use a geographical <code>TZ</code> instead:
1029 <pre><code>TZ='Pacific/Auckland'</code></pre>
1044 POSIX.1-2024 requires support for geographical <code>TZ</code>.
1045 Earlier POSIX editions require support only for proleptic <code>TZ</code>.
1048 POSIX.1-2024 requires <code>struct tm</code>
1049 to have a <abbr>UT</abbr> offset member <code>tm_gmtoff</code>
1050 and a time zone abbreviation member <code>tm_zone</code>.
1057 like <code>"<-02>2<-01>,M3.5.0/-1,M10.5.0/0"</code>
1065 The <code>TZ</code> environment variable is process-global, which
1075 <code>TZ</code> environment variable.
1082 POSIX requires that <code>time_t</code> clock counts exclude leap
1087 for settings like <code>TZ='EST5EDT'</code>.
1094 interpreted <code>TZ</code> values had to be updated
1100 <code><abbr>tz</abbr></code> code</h3>
1102 The <code><abbr>tz</abbr></code> code defines some properties
1109 The <code><abbr>tz</abbr></code> code attempts to support all the
1110 <code>time_t</code> implementations allowed by POSIX.
1111 The <code>time_t</code> type represents a nonnegative count of seconds
1113 In practice, <code>time_t</code> is usually a signed 64- or 32-bit
1114 integer; 32-bit signed <code>time_t</code> values stop working after
1119 Although earlier POSIX versions allowed <code>time_t</code> to be a
1121 and POSIX.1-2013+ and the <code><abbr>tz</abbr></code> code both
1122 require <code>time_t</code> to be an integer type.
1126 If the <code>TZ</code> environment variable uses the geographical format,
1141 When the <code><abbr>tz</abbr></code> code was developed in the 1980s,
1142 it was recognized that allowing the <code>TZ</code> environment
1143 variable to take on values such as <code>America/New_York</code>
1144 might cause old programs (that expect <code>TZ</code> to have a
1146 some other environment variable (for example, <code>TIMEZONE</code>)
1149 <code>TZ</code>: it is widely used for time zone purposes;
1150 separately maintaining both <code>TZ</code>
1151 and <code>TIMEZONE</code> seemed a nuisance; and systems where
1152 new forms of <code>TZ</code> might cause problems can simply
1153 use legacy settings such as <code>TZ='EST5EDT'</code> which
1155 assume pre-POSIX <code>TZ</code> values.
1159 Functions <code>tzalloc</code>, <code>tzfree</code>,
1160 <code>localtime_rz</code>, and <code>mktime_z</code> for
1163 The <code>tzalloc</code> and <code>tzfree</code> functions
1164 allocate and free objects of type <code>timezone_t</code>,
1165 and <code>localtime_rz</code> and <code>mktime_z</code> are
1166 like <code>localtime_r</code> and <code>mktime</code> with an
1167 extra <code>timezone_t</code> argument.
1171 Negative <code>time_t</code> values are supported, on systems
1172 where <code>time_t</code> is signed.
1187 Although the <code><abbr>tz</abbr></code> code supports these
1194 The POSIX <code>tzname</code> variable does not suffice and is no
1198 the <code>tm_zone</code> member if available; otherwise,
1199 use <code>strftime</code>’s <code>"%Z"</code> conversion
1203 The POSIX <code>daylight</code> and <code>timezone</code>
1207 the <code>tm_gmtoff</code> member if available; otherwise,
1208 subtract values returned by <code>localtime</code>
1209 and <code>gmtime</code> using the rules of the Gregorian calendar,
1210 or use <code>strftime</code>’s <code>"%z"</code> conversion
1211 specification if a string like <code>"+0900"</code> suffices.
1214 The <code>tm_isdst</code> member is almost never needed and most of
1217 It was intended as an index into the <code>tzname</code> variable,
1220 <code>mktime</code> to disambiguate timestamps near
1222 platforms lacking <code>tm_gmtoff</code>, this
1223 disambiguation works only for proleptic <code>TZ</code> strings;
1234 UNIX</a> <code>timezone</code> function is not present in this
1235 package; it is impossible to reliably map <code>timezone</code>’s
1239 Programs that in the past used the <code>timezone</code> function
1240 may now examine <code>localtime(&clock)->tm_zone</code>
1241 (if <code>TM_ZONE</code> is defined) or
1242 use <code>strftime</code> with a <code>%Z</code> conversion specification
1249 <code>gettimeofday</code> function is not
1257 near-maximum <code>time_t</code> values when doing conversions
1260 A comment in the source code tells how to get compatibly wrong
1265 if <code>STD_INSPIRED</code> is nonzero should, at this point, be
1292 The <code><abbr>tz</abbr></code> code and data supply the following interfaces:
1305 The programs <code>tzselect</code>, <code>zdump</code>,
1306 and <code>zic</code>, documented in their man pages.
1309 The format of <code>zic</code> input files, documented in
1310 the <code>zic</code> man page.
1313 The format of <code>zic</code> output files, documented in
1314 the <code>tzfile</code> man page.
1317 The format of zone table files, documented in <code>zone1970.tab</code>.
1320 The format of the country code file, documented in <code>iso3166.tab</code>.
1323 The version number of the code and data, as the first line of
1324 the text file "<code>version</code>" in each release.
1331 For example, <code><abbr>tz</abbr></code> data files typically do not
1332 rely on recently added <code>zic</code> features, so that users can
1333 run older <code>zic</code> versions to process newer data files.
1335 the <code><abbr>tz</abbr></code> database</a> describes how releases
1373 The <code><abbr>tz</abbr></code> code and data can account for leap seconds,
1374 thanks to code contributed by Bradley White.
1391 The directly supported mechanism assumes that <code>time_t</code>
1393 as opposed to POSIX <code>time_t</code> counts which exclude leap seconds.
1397 namely, at calls to <code>localtime</code> and analogous functions –
1402 calls to <code>gmtime</code>-like functions
1407 To convert an application’s <code>time_t</code> timestamps to or from
1408 POSIX <code>time_t</code> timestamps (for use when, say,
1410 <a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a>
1413 <code>time2posix</code> and <code>posix2time</code>
1423 its <code>TZ</code> environment variable, there is no support for some
1430 in the first place; see the <code>REDO</code> variable in this package’s
1445 Other information and sources are given in the file "<code>calendars</code>"
1446 in the <code><abbr>tz</abbr></code> distribution.
1547 Although the <code><abbr>tz</abbr></code> database does not support