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.
128 interfaces; it maps timezone names like <code>Europe/Prague</code> to
165 <var>AREA</var><code>/</code><var>LOCATION</var>, where
168 North and South America share the same area, '<code>America</code>'.
169 Typical names are '<code>Africa/Cairo</code>',
170 '<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'.
172 '<code>America/Indiana/Petersburg</code>' distinguishes Petersburg,
185 names other than '<code>/</code>').
186 Do not use the file name components '<code>.</code>' and
187 '<code>..</code>'.
190 '<code>.</code>', '<code>-</code>' and '<code>_</code>'.
193 <code>TZ</code> strings</a>.
195 '<code>-</code>'.
196 E.g., prefer <code>America/Noronha</code> to
197 <code>America/Fernando_de_Noronha</code>.
201 A name must not be empty, or contain '<code>//</code>', or
202 start or end with '<code>/</code>'.
213 start with '<code>/</code>', as a regular file cannot have the
215 For example, <code>America/New_York</code> precludes
216 <code>America/New_York/Bronx</code>.
237 prefer <code>America/Costa_Rica</code> to
238 <code>America/San_Jose</code> and <code>America/Guyana</code>
239 to <code>America/Georgetown</code>.
246 E.g., prefer <code>Europe/Paris</code> to <code>Europe/France</code>,
253 <code>Europe/Rome</code> to <code>Europa/Roma</code>, and
254 prefer <code>Europe/Athens</code> to the Greek
255 <code>Ευρώπη/Αθήνα</code> or the Romanized
256 <code>Evrópi/Athína</code>.
261 e.g., prefer <code>Asia/Shanghai</code> to
262 <code>Asia/Beijing</code>.
264 location, e.g., prefer <code>Europe/Rome</code> to
265 <code>Europe/Milan</code>.
268 Use the singular form, e.g., prefer <code>Atlantic/Canary</code> to
269 <code>Atlantic/Canaries</code>.
272 Omit common suffixes like '<code>_Islands</code>' and
273 '<code>_City</code>', unless that would lead to ambiguity.
274 E.g., prefer <code>America/Cayman</code> to
275 <code>America/Cayman_Islands</code> and
276 <code>America/Guatemala</code> to
277 <code>America/Guatemala_City</code>, but prefer
278 <code>America/Mexico_City</code> to
279 <code>America/Mexico</code>
284 Use '<code>_</code>' to represent a space.
287 Omit '<code>.</code>' from abbreviations in names.
288 E.g., prefer <code>Atlantic/St_Helena</code> to
289 <code>Atlantic/St._Helena</code>.
294 For example, do not change the existing name <code>Europe/Rome</code> to
295 <code>Europe/Milan</code> merely because Milan's population has grown
300 '<code>backward</code>' file as a link to the new spelling.
304 in 2008 <code>Asia/Calcutta</code> was renamed to <code>Asia/Kolkata</code>
319 See the file '<code>backward</code>' for most of these older names
320 (e.g., '<code>US/Eastern</code>' instead of '<code>America/New_York</code>').
322 '<code>WET</code>', '<code>CET</code>', '<code>MET</code>', and
323 '<code>EET</code>' (see the file '<code>europe</code>').
331 '<code>etcetera</code>'.
332 Also, the file '<code>backward</code>' defines the legacy names
333 '<code>Etc/GMT0</code>', '<code>Etc/GMT-0</code>', '<code>Etc/GMT+0</code>',
334 '<code>GMT0</code>', '<code>GMT-0</code>' and '<code>GMT+0</code>',
335 and the file '<code>northamerica</code>' defines the legacy names
336 '<code>EST5EDT</code>', '<code>CST6CDT</code>',
337 '<code>MST7MDT</code>', and '<code>PST8PDT</code>'.
345 3166-1</a> officially assigned two-letter code for an inhabited
353 The file <code>zone1970.tab</code> lists geographical locations used
357 Although a <code>zone1970.tab</code> location's
363 The backward-compatibility file <code>zone.tab</code> is similar
365 it lists only one country code per entry and unlike <code>zone1970.tab</code>
366 it can list names defined in <code>backward</code>.
368 <code>zonenow.tab</code>, which partitions the world more coarsely,
370 this file is smaller and simpler than <code>zone1970.tab</code>
371 and <code>zone.tab</code>.
376 The source file <code>backward</code> defines links for backward
378 Although <code>backward</code> was originally designed to be optional,
381 is defined in <code>backward</code> or in some other file.
382 The source file <code>etcetera</code> defines names that may be useful
383 on platforms that do not support proleptic <code>TZ</code> strings
384 like <code><+08>-8</code>;
385 no other source file other than <code>backward</code>
387 One of <code>etcetera</code>'s names is <code>Etc/UTC</code>,
388 used by functions like <code>gmtime</code> to obtain leap
390 Another <code>etcetera</code> name, <code>GMT</code>,
391 is used by older code releases.
399 like '<code>EST</code>' to be compatible with human tradition and POSIX.
407 '<code>+</code>' or '<code>-</code>'.
409 space and '<code>?</code>', but these characters have a
413 '<code><a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set">set</a>
414 `<a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/date.html">date</a>`</code>'
421 Also, POSIX from 2001 on relaxed the rule to allow '<code>-</code>',
422 '<code>+</code>', and alphanumeric characters from the portable
424 In practice ASCII alphanumerics and '<code>+</code>' and
425 '<code>-</code>' are safe in all locales.
429 expression <code>[-+[:alnum:]]{3,6}</code> should match the
432 explicitly by a POSIX proleptic <code>TZ</code> string.
497 Typically, numeric abbreviations (e.g., '<code>-</code>004430' for
551 <code><abbr>tz</abbr></code> database</a>".
555 <code>-</code>05 and <code>+</code>0530 that are generated
556 by <code>zic</code>'s <code>%z</code> notation.
578 (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for
580 The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in
598 '<code>-</code>0600' instead of time zone abbreviations like 'CST'.
603 <h2 id="accuracy">Accuracy of the <code><abbr>tz</abbr></code> database</h2>
605 The <code><abbr>tz</abbr></code> database is not authoritative, and it
607 Corrections are welcome and encouraged; see the file <code>CONTRIBUTING</code>.
613 Errors in the <code><abbr>tz</abbr></code> database arise from many sources:
618 The <code><abbr>tz</abbr></code> database predicts future
631 the <code><abbr>tz</abbr></code> database's scope were extended to
660 For the UK the <code><abbr>tz</abbr></code> database relies on
684 Although a named location in the <code><abbr>tz</abbr></code>
687 For example, <code>Europe/London</code> stands for the United
694 The <code><abbr>tz</abbr></code> database does not record the
697 For example, <code>Europe/London</code> is valid for all locations
700 <code><abbr>tz</abbr></code> database, other than in commentary.
705 The <code><abbr>tz</abbr></code> database does not record a
708 <code>America/Kentucky/Louisville</code> represents a region
714 <code><abbr>tz</abbr></code>
724 <code><abbr>tz</abbr></code> database requires.
727 The <code><abbr>tz</abbr></code> database cannot represent stopped clocks.
730 The <code><abbr>tz</abbr></code> database models this via a
736 than what the <code><abbr>tz</abbr></code> code can handle.
739 −00:25:21.1); although the <code><abbr>tz</abbr></code>
740 source data can represent the .1 second, TZif files and the code cannot.
746 <code><abbr>tz</abbr></code> database are correct, the
747 <code><abbr>tz</abbr></code> rules that generate them may not
753 Because the <code><abbr>tz</abbr></code> database has no
755 separate <code><abbr>tz</abbr> Rule</code> lines, even though the
758 the database contains <code>Zone</code> and <code>Rule</code>
764 The <code><abbr>tz</abbr></code> database models time
784 the scope of the <code><abbr>tz</abbr></code> code and data, which
788 can often do the trick; for example, in Kenya a <code>TZ</code> setting
789 like <code><-03>3</code> or <code>America/Cayenne</code> starts
790 the day six hours later than <code>Africa/Nairobi</code> does.
797 The <code><abbr>tz</abbr></code> database assumes Universal Time
800 In the <code><abbr>tz</abbr></code> database commentary,
843 The <code><abbr>tz</abbr></code> database does not represent how
853 In short, many, perhaps most, of the <code><abbr>tz</abbr></code>
857 <code><abbr>tz</abbr></code> database off as the definition of time
859 In particular, the <code><abbr>tz</abbr></code> database's
871 The <code><abbr>tz</abbr></code> code contains time and date functions
873 Code compatible with this package is already
877 <code>zic</code> supplied with this package instead of using the
878 system <code>zic</code>, since the format of <code>zic</code>'s
880 an older <code>zic</code>.
885 environment variable <code>TZ</code>, which can have two forms:
889 A <dfn>proleptic <code>TZ</code></dfn> value
890 like <code>CET-1CEST,M3.5.0,M10.5.0/3</code> uses a complex
895 A <dfn>geographical <code>TZ</code></dfn> value
896 like <code>Europe/Berlin</code> names a location that stands for
900 These names are defined by the <code><abbr>tz</abbr></code> database.
908 Code intended to be portable to these platforms must deal
914 POSIX.1-2017 does not require support for geographical <code>TZ</code>,
922 The proleptic <code>TZ</code> string,
925 Also, proleptic <code>TZ</code> strings cannot deal with daylight
932 A proleptic <code>TZ</code> string has the following format:
936 <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>]]]
948 may also be in a quoted form like '<code><+09></code>';
949 this allows "<code>+</code>" and "<code>-</code>" in the names.
953 '<code>[±]<var>hh</var>:[<var>mm</var>[:<var>ss</var>]]</code>'
960 <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd>
968 '<var>hh</var><code>:</code>[<var>mm</var>[<code>:</code><var>ss</var>]]'
971 leading '<code>+</code>' or '<code>-</code>' is not allowed.
982 <dt><code>M</code><var>m</var><code>.</code><var>n</var><code>.</code><var>d</var>
988 '<code>5</code>' stands for the last week in which
992 and <code>J</code><var>n</var> forms are rarely used.
999 Here is an example proleptic <code>TZ</code> string for New
1007 <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
1010 This proleptic <code>TZ</code> string is hard to remember, and
1012 With this package you can use a geographical <code>TZ</code> instead:
1015 <pre><code>TZ='Pacific/Auckland'</code></pre>
1030 POSIX.1-2024 requires support for geographical <code>TZ</code>.
1031 Earlier POSIX editions require support only for proleptic <code>TZ</code>.
1034 POSIX.1-2024 requires <code>struct tm</code>
1035 to have a <abbr>UT</abbr> offset member <code>tm_gmtoff</code>
1036 and a time zone abbreviation member <code>tm_zone</code>.
1043 like <code>"<-02>2<-01>,M3.5.0/-1,M10.5.0/0"</code>
1051 The <code>TZ</code> environment variable is process-global, which
1061 <code>TZ</code> environment variable.
1068 POSIX requires that <code>time_t</code> clock counts exclude leap
1073 for <code>TZ</code> values like
1074 "<code>EST5EDT</code>".
1081 interpreted <code>TZ</code> values had to be updated
1087 <code><abbr>tz</abbr></code> code</h3>
1089 The <code><abbr>tz</abbr></code> code defines some properties
1096 The <code><abbr>tz</abbr></code> code attempts to support all the
1097 <code>time_t</code> implementations allowed by POSIX.
1098 The <code>time_t</code> type represents a nonnegative count of seconds
1100 In practice, <code>time_t</code> is usually a signed 64- or 32-bit
1101 integer; 32-bit signed <code>time_t</code> values stop working after
1106 Although earlier POSIX versions allowed <code>time_t</code> to be a
1108 and POSIX.1-2013+ and the <code><abbr>tz</abbr></code> code both
1109 require <code>time_t</code> to be an integer type.
1113 If the <code>TZ</code> environment variable uses the geographical format,
1128 When the <code><abbr>tz</abbr></code> code was developed in the 1980s,
1129 it was recognized that allowing the <code>TZ</code> environment
1130 variable to take on values such as '<code>America/New_York</code>'
1131 might cause "old" programs (that expect <code>TZ</code> to have a
1133 some other environment variable (for example, <code>TIMEZONE</code>)
1136 <code>TZ</code>: it is widely used for time zone purposes;
1137 separately maintaining both <code>TZ</code>
1138 and <code>TIMEZONE</code> seemed a nuisance; and systems where
1139 "new" forms of <code>TZ</code> might cause problems can simply
1140 use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which
1142 assume pre-POSIX <code>TZ</code> values.
1146 Functions <code>tzalloc</code>, <code>tzfree</code>,
1147 <code>localtime_rz</code>, and <code>mktime_z</code> for
1150 The <code>tzalloc</code> and <code>tzfree</code> functions
1151 allocate and free objects of type <code>timezone_t</code>,
1152 and <code>localtime_rz</code> and <code>mktime_z</code> are
1153 like <code>localtime_r</code> and <code>mktime</code> with an
1154 extra <code>timezone_t</code> argument.
1158 Negative <code>time_t</code> values are supported, on systems
1159 where <code>time_t</code> is signed.
1174 Although the <code><abbr>tz</abbr></code> code supports these
1181 The POSIX <code>tzname</code> variable does not suffice and is no
1185 the <code>tm_zone</code> member if available; otherwise,
1186 use <code>strftime</code>'s <code>"%Z"</code> conversion
1190 The POSIX <code>daylight</code> and <code>timezone</code>
1194 the <code>tm_gmtoff</code> member if available; otherwise,
1195 subtract values returned by <code>localtime</code>
1196 and <code>gmtime</code> using the rules of the Gregorian calendar,
1197 or use <code>strftime</code>'s <code>"%z"</code> conversion
1198 specification if a string like <code>"+0900"</code> suffices.
1201 The <code>tm_isdst</code> member is almost never needed and most of
1205 <code>mktime</code> to disambiguate timestamps near
1207 platforms lacking <code>tm_gmtoff</code>, this
1218 UNIX</a> <code>timezone</code> function is not present in this
1219 package; it is impossible to reliably map <code>timezone</code>'s
1223 Programs that in the past used the <code>timezone</code> function
1224 may now examine <code>localtime(&clock)->tm_zone</code>
1225 (if <code>TM_ZONE</code> is defined) or
1226 <code>tzname[localtime(&clock)->tm_isdst]</code>
1227 (if <code>HAVE_TZNAME</code> is nonzero) to learn the correct time
1233 <code>gettimeofday</code> function is not
1241 near-maximum <code>time_t</code> values when doing conversions
1244 A comment in the source code tells how to get compatibly wrong
1249 if <code>STD_INSPIRED</code> is nonzero should, at this point, be
1276 The <code><abbr>tz</abbr></code> code and data supply the following interfaces:
1289 The programs <code>tzselect</code>, <code>zdump</code>,
1290 and <code>zic</code>, documented in their man pages.
1293 The format of <code>zic</code> input files, documented in
1294 the <code>zic</code> man page.
1297 The format of <code>zic</code> output files, documented in
1298 the <code>tzfile</code> man page.
1301 The format of zone table files, documented in <code>zone1970.tab</code>.
1304 The format of the country code file, documented in <code>iso3166.tab</code>.
1307 The version number of the code and data, as the first line of
1308 the text file '<code>version</code>' in each release.
1315 For example, <code><abbr>tz</abbr></code> data files typically do not
1316 rely on recently added <code>zic</code> features, so that users can
1317 run older <code>zic</code> versions to process newer data files.
1319 the <code><abbr>tz</abbr></code> database</a> describes how releases
1357 The <code><abbr>tz</abbr></code> code and data can account for leap seconds,
1358 thanks to code contributed by Bradley White.
1375 The directly supported mechanism assumes that <code>time_t</code>
1377 as opposed to POSIX <code>time_t</code> counts which exclude leap seconds.
1381 namely, at calls to <code>localtime</code> and analogous functions –
1386 calls to <code>gmtime</code>-like functions
1391 To convert an application's <code>time_t</code> timestamps to or from
1392 POSIX <code>time_t</code> timestamps (for use when, say,
1394 <a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a>
1397 <code>time2posix</code> and <code>posix2time</code>
1407 its <code>TZ</code> environment variable, there is no support for some
1414 in the first place; see the <code>REDO</code> variable in this package's
1429 Other information and sources are given in the file '<code>calendars</code>'
1430 in the <code><abbr>tz</abbr></code> distribution.
1531 Although the <code><abbr>tz</abbr></code> database does not support