Lines Matching full:code
4 <title>Theory and pragmatics of the tz code and data</title>
12 <h1>Theory and pragmatics of the <code><abbr>tz</abbr></code> code and data</h1>
16 <li><a href="#scope">Scope of the <code><abbr>tz</abbr></code>
20 <li><a href="#accuracy">Accuracy of the <code><abbr>tz</abbr></code>
31 <h2 id="scope">Scope of the <code><abbr>tz</abbr></code> database</h2>
34 href="https://www.iana.org/time-zones"><code><abbr>tz</abbr></code>
61 <code>America/Denver</code> which observes US-style daylight saving
63 and <code>America/Phoenix</code> which does not observe <abbr>DST</abbr>.
66 <code>America/Boise</code>, <code>America/Edmonton</code>, and
67 <code>America/Hermosillo</code>, each of which currently uses mountain
80 collected in a file <code>backzone</code> that is distributed along
86 As described below, reference source code for using the
87 <code><abbr>tz</abbr></code> database is also available.
88 The <code><abbr>tz</abbr></code> code is upwards compatible with <a
98 <code><abbr>tz</abbr></code> database, which has a
101 A <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can
121 "Czech Republic" instead of the timezone name "<code>Europe/Prague</code>".
125 <code>tzselect</code> program in the <code><abbr>tz</abbr></code> code.
129 interfaces; it maps timezone names like <code>Europe/Prague</code> to
166 <var>AREA</var><code>/</code><var>LOCATION</var>, where
169 North and South America share the same area, '<code>America</code>'.
170 Typical names are '<code>Africa/Cairo</code>',
171 '<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'.
173 '<code>America/Indiana/Petersburg</code>' distinguishes Petersburg,
186 names other than '<code>/</code>').
187 Do not use the file name components '<code>.</code>' and
188 '<code>..</code>'.
191 '<code>.</code>', '<code>-</code>' and '<code>_</code>'.
194 <code>TZ</code> strings</a>.
196 '<code>-</code>'.
197 E.g., prefer <code>America/Noronha</code> to
198 <code>America/Fernando_de_Noronha</code>.
202 A name must not be empty, or contain '<code>//</code>', or
203 start or end with '<code>/</code>'.
204 Also, a name must not be '<code>Etc/Unknown</code>', as
216 start with '<code>/</code>', as a regular file cannot have the
218 For example, <code>America/New_York</code> precludes
219 <code>America/New_York/Bronx</code>.
230 For example, do not create a name <code>Indian/Crozet</code>
231 as a near-duplicate or alias of <code>Asia/Dubai</code>
237 that use <code>Asia/Dubai</code>.
248 prefer <code>America/Costa_Rica</code> to
249 <code>America/San_Jose</code> and <code>America/Guyana</code>
250 to <code>America/Georgetown</code>.
257 E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>,
264 <code>Europe/Rome</code> to <code>Europa/Roma</code>, and
265 prefer <code>Europe/Athens</code> to the Greek
266 <code>Ευρώπη/Αθήνα</code> or the Romanized
267 <code>Evrópi/Athína</code>.
272 e.g., prefer <code>Asia/Shanghai</code> to
273 <code>Asia/Beijing</code>.
275 location, e.g., prefer <code>Europe/Rome</code> to
276 <code>Europe/Milan</code>.
279 Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to
280 <code>Atlantic/Canaries</code>.
283 Omit common suffixes like '<code>_Islands</code>' and
284 '<code>_City</code>', unless that would lead to ambiguity.
285 E.g., prefer <code>America/Cayman</code> to
286 <code>America/Cayman_Islands</code> and
287 <code>America/Guatemala</code> to
288 <code>America/Guatemala_City</code>, but prefer
289 <code>America/Mexico_City</code> to
290 <code>America/Mexico</code>
295 Use '<code>_</code>' to represent a space.
298 Omit '<code>.</code>' from abbreviations in names.
299 E.g., prefer <code>Atlantic/St_Helena</code> to
300 <code>Atlantic/St._Helena</code>.
305 For example, do not change the existing name <code>Europe/Rome</code> to
306 <code>Europe/Milan</code> merely because Milan's population has grown
311 '<code>backward</code>' file as a link to the new spelling.
315 in 2008 <code>Asia/Calcutta</code> was renamed to <code>Asia/Kolkata</code>
330 See the file '<code>backward</code>' for most of these older names
331 (e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>').
333 '<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and
334 '<code>EET</code>' (see the file '<code>europe</code>').
342 '<code>etcetera</code>'.
343 Also, the file '<code>backward</code>' defines the legacy names
344 '<code>Etc/GMT0</code>', '<code>Etc/GMT-0</code>', '<code>Etc/GMT+0</code>',
345 '<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>',
346 and the file '<code>northamerica</code>' defines the legacy names
347 '<code>EST5EDT</code>', '<code>CST6CDT</code>',
348 '<code>MST7MDT</code>', and '<code>PST8PDT</code>'.
356 3166-1</a> officially assigned two-letter code for an inhabited
364 The file <code>zone1970.tab</code> lists geographical locations used
368 Although a <code>zone1970.tab</code> location's
374 The backward-compatibility file <code>zone.tab</code> is similar
376 it lists only one country code per entry and unlike <code>zone1970.tab</code>
377 it can list names defined in <code>backward</code>.
379 <code>zonenow.tab</code>, which partitions the world more coarsely,
381 this file is smaller and simpler than <code>zone1970.tab</code>
382 and <code>zone.tab</code>.
387 The source file <code>backward</code> defines links for backward
389 Although <code>backward</code> was originally designed to be optional,
392 is defined in <code>backward</code> or in some other file.
393 The source file <code>etcetera</code> defines names that may be useful
394 on platforms that do not support proleptic <code>TZ</code> strings
395 like <code><+08>-8</code>;
396 no other source file other than <code>backward</code>
398 One of <code>etcetera</code>'s names is <code>Etc/UTC</code>,
399 used by functions like <code>gmtime</code> to obtain leap
401 Another <code>etcetera</code> name, <code>GMT</code>,
402 is used by older code releases.
410 like '<code>EST</code>' to be compatible with human tradition and POSIX.
418 '<code>+</code>' or '<code>-</code>'.
420 space and '<code>?</code>', but these characters have a
424 '<code><a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a>
425 `<a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>'
432 Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>',
433 '<code>+</code>', and alphanumeric characters from the portable
435 In practice ASCII alphanumerics and '<code>+</code>' and
436 '<code>-</code>' are safe in all locales.
440 expression <code>[-+[:alnum:]]{3,6}</code> should match the
443 explicitly by a POSIX proleptic <code>TZ</code> string.
508 Typically, numeric abbreviations (e.g., '<code>-</code>004430' for
562 <code><abbr>tz</abbr></code> database</a>".
566 <code>-</code>05 and <code>+</code>0530 that are generated
567 by <code>zic</code>'s <code>%z</code> notation.
589 (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for
591 The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in
609 '<code>-</code>0600' instead of time zone abbreviations like 'CST'.
614 <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2>
616 The <code><abbr>tz</abbr></code> database is not authoritative, and it
618 Corrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>.
624 Errors in the <code><abbr>tz</abbr></code> database arise from many sources:
629 The <code><abbr>tz</abbr></code> database predicts future
642 the <code><abbr>tz</abbr></code> database's scope were extended to
671 For the UK the <code><abbr>tz</abbr></code> database relies on
695 Although a named location in the <code><abbr>tz</abbr></code>
698 For example, <code>Europe/London</code> stands for the United
705 The <code><abbr>tz</abbr></code> database does not record the
708 For example, <code>Europe/London</code> is valid for all locations
711 <code><abbr>tz</abbr></code> database, other than in commentary.
716 The <code><abbr>tz</abbr></code> database does not record a
719 <code>America/Kentucky/Louisville</code> represents a region
725 <code><abbr>tz</abbr></code>
735 <code><abbr>tz</abbr></code> database requires.
738 The <code><abbr>tz</abbr></code> database cannot represent stopped clocks.
741 The <code><abbr>tz</abbr></code> database models this via a
747 than what the <code><abbr>tz</abbr></code> code can handle.
750 −00:25:21.1); although the <code><abbr>tz</abbr></code>
751 source data can represent the .1 second, TZif files and the code cannot.
757 <code><abbr>tz</abbr></code> database are correct, the
758 <code><abbr>tz</abbr></code> rules that generate them may not
764 Because the <code><abbr>tz</abbr></code> database has no
766 separate <code><abbr>tz</abbr> Rule</code> lines, even though the
769 the database contains <code>Zone</code> and <code>Rule</code>
775 The <code><abbr>tz</abbr></code> database models time
795 the scope of the <code><abbr>tz</abbr></code> code and data, which
799 can often do the trick; for example, in Kenya a <code>TZ</code> setting
800 like <code><-03>3</code> or <code>America/Cayenne</code> starts
801 the day six hours later than <code>Africa/Nairobi</code> does.
808 The <code><abbr>tz</abbr></code> database assumes Universal Time
811 In the <code><abbr>tz</abbr></code> database commentary,
854 The <code><abbr>tz</abbr></code> database does not represent how
864 In short, many, perhaps most, of the <code><abbr>tz</abbr></code>
868 <code><abbr>tz</abbr></code> database off as the definition of time
870 In particular, the <code><abbr>tz</abbr></code> database's
882 The <code><abbr>tz</abbr></code> code contains time and date functions
884 Code compatible with this package is already
888 <code>zic</code> supplied with this package instead of using the
889 system <code>zic</code>, since the format of <code>zic</code>'s
891 an older <code>zic</code>.
896 environment variable <code>TZ</code>, which can have two forms:
900 A <dfn>proleptic <code>TZ</code></dfn> value
901 like <code>CET-1CEST,M3.5.0,M10.5.0/3</code> uses a complex
906 A <dfn>geographical <code>TZ</code></dfn> value
907 like <code>Europe/Berlin</code> names a location that stands for
911 These names are defined by the <code><abbr>tz</abbr></code> database.
919 Code intended to be portable to these platforms must deal
925 POSIX.1-2017 does not require support for geographical <code>TZ</code>,
933 The proleptic <code>TZ</code> string,
936 Also, proleptic <code>TZ</code> strings cannot deal with daylight
943 A proleptic <code>TZ</code> string has the following format:
947 <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>]]]
959 may also be in a quoted form like '<code><+09></code>';
960 this allows "<code>+</code>" and "<code>-</code>" in the names.
964 '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>'
971 <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd>
979 '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]'
982 leading '<code>+</code>' or '<code>-</code>' is not allowed.
993 <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var>
999 '<code>5</code>' stands for the last week in which
1003 and <code>J</code><var>n</var> forms are rarely used.
1010 Here is an example proleptic <code>TZ</code> string for New
1018 <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
1021 This proleptic <code>TZ</code> string is hard to remember, and
1023 With this package you can use a geographical <code>TZ</code> instead:
1026 <pre><code>TZ='Pacific/Auckland'</code></pre>
1041 POSIX.1-2024 requires support for geographical <code>TZ</code>.
1042 Earlier POSIX editions require support only for proleptic <code>TZ</code>.
1045 POSIX.1-2024 requires <code>struct tm</code>
1046 to have a <abbr>UT</abbr> offset member <code>tm_gmtoff</code>
1047 and a time zone abbreviation member <code>tm_zone</code>.
1054 like <code>"<-02>2<-01>,M3.5.0/-1,M10.5.0/0"</code>
1062 The <code>TZ</code> environment variable is process-global, which
1072 <code>TZ</code> environment variable.
1079 POSIX requires that <code>time_t</code> clock counts exclude leap
1084 for <code>TZ</code> values like
1085 "<code>EST5EDT</code>".
1092 interpreted <code>TZ</code> values had to be updated
1098 <code><abbr>tz</abbr></code> code</h3>
1100 The <code><abbr>tz</abbr></code> code defines some properties
1107 The <code><abbr>tz</abbr></code> code attempts to support all the
1108 <code>time_t</code> implementations allowed by POSIX.
1109 The <code>time_t</code> type represents a nonnegative count of seconds
1111 In practice, <code>time_t</code> is usually a signed 64- or 32-bit
1112 integer; 32-bit signed <code>time_t</code> values stop working after
1117 Although earlier POSIX versions allowed <code>time_t</code> to be a
1119 and POSIX.1-2013+ and the <code><abbr>tz</abbr></code> code both
1120 require <code>time_t</code> to be an integer type.
1124 If the <code>TZ</code> environment variable uses the geographical format,
1139 When the <code><abbr>tz</abbr></code> code was developed in the 1980s,
1140 it was recognized that allowing the <code>TZ</code> environment
1141 variable to take on values such as '<code>America/New_York</code>'
1142 might cause "old" programs (that expect <code>TZ</code> to have a
1144 some other environment variable (for example, <code>TIMEZONE</code>)
1147 <code>TZ</code>: it is widely used for time zone purposes;
1148 separately maintaining both <code>TZ</code>
1149 and <code>TIMEZONE</code> seemed a nuisance; and systems where
1150 "new" forms of <code>TZ</code> might cause problems can simply
1151 use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which
1153 assume pre-POSIX <code>TZ</code> values.
1157 Functions <code>tzalloc</code>, <code>tzfree</code>,
1158 <code>localtime_rz</code>, and <code>mktime_z</code> for
1161 The <code>tzalloc</code> and <code>tzfree</code> functions
1162 allocate and free objects of type <code>timezone_t</code>,
1163 and <code>localtime_rz</code> and <code>mktime_z</code> are
1164 like <code>localtime_r</code> and <code>mktime</code> with an
1165 extra <code>timezone_t</code> argument.
1169 Negative <code>time_t</code> values are supported, on systems
1170 where <code>time_t</code> is signed.
1185 Although the <code><abbr>tz</abbr></code> code supports these
1192 The POSIX <code>tzname</code> variable does not suffice and is no
1196 the <code>tm_zone</code> member if available; otherwise,
1197 use <code>strftime</code>'s <code>"%Z"</code> conversion
1201 The POSIX <code>daylight</code> and <code>timezone</code>
1205 the <code>tm_gmtoff</code> member if available; otherwise,
1206 subtract values returned by <code>localtime</code>
1207 and <code>gmtime</code> using the rules of the Gregorian calendar,
1208 or use <code>strftime</code>'s <code>"%z"</code> conversion
1209 specification if a string like <code>"+0900"</code> suffices.
1212 The <code>tm_isdst</code> member is almost never needed and most of
1215 It was intended as an index into the <code>tzname</code> variable,
1218 <code>mktime</code> to disambiguate timestamps near
1220 platforms lacking <code>tm_gmtoff</code>, this
1221 disambiguation works only for proleptic <code>TZ</code> strings;
1232 UNIX</a> <code>timezone</code> function is not present in this
1233 package; it is impossible to reliably map <code>timezone</code>'s
1237 Programs that in the past used the <code>timezone</code> function
1238 may now examine <code>localtime(&clock)->tm_zone</code>
1239 (if <code>TM_ZONE</code> is defined) or
1240 use <code>strftime</code> with a <code>%Z</code> conversion specification
1247 <code>gettimeofday</code> function is not
1255 near-maximum <code>time_t</code> values when doing conversions
1258 A comment in the source code tells how to get compatibly wrong
1263 if <code>STD_INSPIRED</code> is nonzero should, at this point, be
1290 The <code><abbr>tz</abbr></code> code and data supply the following interfaces:
1303 The programs <code>tzselect</code>, <code>zdump</code>,
1304 and <code>zic</code>, documented in their man pages.
1307 The format of <code>zic</code> input files, documented in
1308 the <code>zic</code> man page.
1311 The format of <code>zic</code> output files, documented in
1312 the <code>tzfile</code> man page.
1315 The format of zone table files, documented in <code>zone1970.tab</code>.
1318 The format of the country code file, documented in <code>iso3166.tab</code>.
1321 The version number of the code and data, as the first line of
1322 the text file '<code>version</code>' in each release.
1329 For example, <code><abbr>tz</abbr></code> data files typically do not
1330 rely on recently added <code>zic</code> features, so that users can
1331 run older <code>zic</code> versions to process newer data files.
1333 the <code><abbr>tz</abbr></code> database</a> describes how releases
1371 The <code><abbr>tz</abbr></code> code and data can account for leap seconds,
1372 thanks to code contributed by Bradley White.
1389 The directly supported mechanism assumes that <code>time_t</code>
1391 as opposed to POSIX <code>time_t</code> counts which exclude leap seconds.
1395 namely, at calls to <code>localtime</code> and analogous functions –
1400 calls to <code>gmtime</code>-like functions
1405 To convert an application's <code>time_t</code> timestamps to or from
1406 POSIX <code>time_t</code> timestamps (for use when, say,
1408 <a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a>
1411 <code>time2posix</code> and <code>posix2time</code>
1421 its <code>TZ</code> environment variable, there is no support for some
1428 in the first place; see the <code>REDO</code> variable in this package's
1443 Other information and sources are given in the file '<code>calendars</code>'
1444 in the <code><abbr>tz</abbr></code> distribution.
1545 Although the <code><abbr>tz</abbr></code> database does not support