theory.html (46c599340f187db577b9212ab18022f3c7380c68) theory.html (a979394afeb5c20fc58c5f5b005d51eb8f92f666)
1<!DOCTYPE html>
2<html lang="en">
3<head>
4 <title>Theory and pragmatics of the tz code and data</title>
5 <meta charset="UTF-8">
6 <style>
7 pre {margin-left: 2em; white-space: pre-wrap;}
8 </style>

--- 75 unchanged lines hidden (view full) ---

84
85<p>
86As described below, reference source code for using the
87<code><abbr>tz</abbr></code> database is also available.
88The <code><abbr>tz</abbr></code> code is upwards compatible with <a
89href="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international
90standard for <a
91href="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems.
1<!DOCTYPE html>
2<html lang="en">
3<head>
4 <title>Theory and pragmatics of the tz code and data</title>
5 <meta charset="UTF-8">
6 <style>
7 pre {margin-left: 2em; white-space: pre-wrap;}
8 </style>

--- 75 unchanged lines hidden (view full) ---

84
85<p>
86As described below, reference source code for using the
87<code><abbr>tz</abbr></code> database is also available.
88The <code><abbr>tz</abbr></code> code is upwards compatible with <a
89href="https://en.wikipedia.org/wiki/POSIX">POSIX</a>, an international
90standard for <a
91href="https://en.wikipedia.org/wiki/Unix">UNIX</a>-like systems.
92As of this writing, the current edition of POSIX is: <a
92As of this writing, the current edition of POSIX is POSIX.1-2024,
93which has been published but not yet in HTML form.
94Unlike its predecessor POSIX.1-2017 (<a
93href="https://pubs.opengroup.org/onlinepubs/9699919799/"> The Open
94Group Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018
95href="https://pubs.opengroup.org/onlinepubs/9699919799/"> The Open
96Group Base Specifications Issue 7</a>, IEEE Std 1003.1-2017, 2018
95Edition.
96Because the database's scope encompasses real-world changes to civil
97timekeeping, its model for describing time is more complex than the
98standard and daylight saving times supported by POSIX.1-2017.
97Edition), POSIX.1-2024 requires support for the
98<code><abbr>tz</abbr></code> database, which has a
99model for describing civil time that is more complex than the
100standard and daylight saving times required by POSIX.1-2017.
99A <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can
100have more than two changes per year, these changes need not merely
101flip back and forth between two alternatives, and the rules themselves
102can change at times.
103Whether and when a timezone changes its clock,
104and even the timezone's notional base offset from <abbr>UTC</abbr>,
105are variable.
106It does not always make sense to talk about a timezone's

--- 47 unchanged lines hidden (view full) ---

154 Be portable to a wide variety of implementations.
155 </li>
156 <li>
157 Use a consistent naming conventions over the entire world.
158 </li>
159</ul>
160
161<p>
101A <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can
102have more than two changes per year, these changes need not merely
103flip back and forth between two alternatives, and the rules themselves
104can change at times.
105Whether and when a timezone changes its clock,
106and even the timezone's notional base offset from <abbr>UTC</abbr>,
107are variable.
108It does not always make sense to talk about a timezone's

--- 47 unchanged lines hidden (view full) ---

156 Be portable to a wide variety of implementations.
157 </li>
158 <li>
159 Use a consistent naming conventions over the entire world.
160 </li>
161</ul>
162
163<p>
162Names normally have the form
164Names normally have the format
163<var>AREA</var><code>/</code><var>LOCATION</var>, where
164<var>AREA</var> is a continent or ocean, and
165<var>LOCATION</var> is a specific location within the area.
166North and South America share the same area, '<code>America</code>'.
167Typical names are '<code>Africa/Cairo</code>',
168'<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'.
169Some names are further qualified to help avoid confusion; for example,
170'<code>America/Indiana/Petersburg</code>' distinguishes Petersburg,

--- 11 unchanged lines hidden (view full) ---

182 Use only valid POSIX file name components (i.e., the parts of
183 names other than '<code>/</code>').
184 Do not use the file name components '<code>.</code>' and
185 '<code>..</code>'.
186 Within a file name component, use only <a
187 href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters,
188 '<code>.</code>', '<code>-</code>' and '<code>_</code>'.
189 Do not use digits, as that might create an ambiguity with <a
165<var>AREA</var><code>/</code><var>LOCATION</var>, where
166<var>AREA</var> is a continent or ocean, and
167<var>LOCATION</var> is a specific location within the area.
168North and South America share the same area, '<code>America</code>'.
169Typical names are '<code>Africa/Cairo</code>',
170'<code>America/New_York</code>', and '<code>Pacific/Honolulu</code>'.
171Some names are further qualified to help avoid confusion; for example,
172'<code>America/Indiana/Petersburg</code>' distinguishes Petersburg,

--- 11 unchanged lines hidden (view full) ---

184 Use only valid POSIX file name components (i.e., the parts of
185 names other than '<code>/</code>').
186 Do not use the file name components '<code>.</code>' and
187 '<code>..</code>'.
188 Within a file name component, use only <a
189 href="https://en.wikipedia.org/wiki/ASCII">ASCII</a> letters,
190 '<code>.</code>', '<code>-</code>' and '<code>_</code>'.
191 Do not use digits, as that might create an ambiguity with <a
190 href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX.1-2017
192 href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">POSIX's proleptic
191 <code>TZ</code> strings</a>.
192 A file name component must not exceed 14 characters or start with
193 '<code>-</code>'.
194 E.g., prefer <code>America/Noronha</code> to
195 <code>America/Fernando_de_Noronha</code>.
196 Exceptions: see the discussion of legacy names below.
197 </li>
198 <li>

--- 174 unchanged lines hidden (view full) ---

373The database defines each timezone name to be a zone, or a link to a zone.
374The source file <code>backward</code> defines links for backward
375compatibility; it does not define zones.
376Although <code>backward</code> was originally designed to be optional,
377nowadays distributions typically use it
378and no great weight should be attached to whether a link
379is defined in <code>backward</code> or in some other file.
380The source file <code>etcetera</code> defines names that may be useful
193 <code>TZ</code> strings</a>.
194 A file name component must not exceed 14 characters or start with
195 '<code>-</code>'.
196 E.g., prefer <code>America/Noronha</code> to
197 <code>America/Fernando_de_Noronha</code>.
198 Exceptions: see the discussion of legacy names below.
199 </li>
200 <li>

--- 174 unchanged lines hidden (view full) ---

375The database defines each timezone name to be a zone, or a link to a zone.
376The source file <code>backward</code> defines links for backward
377compatibility; it does not define zones.
378Although <code>backward</code> was originally designed to be optional,
379nowadays distributions typically use it
380and no great weight should be attached to whether a link
381is defined in <code>backward</code> or in some other file.
382The source file <code>etcetera</code> defines names that may be useful
381on platforms that do not support POSIX.1-2017-style <code>TZ</code> strings;
383on platforms that do not support proleptic <code>TZ</code> strings
384like <code>&lt;+08&gt;-8</code>;
382no other source file other than <code>backward</code>
383contains links to its zones.
384One of <code>etcetera</code>'s names is <code>Etc/UTC</code>,
385used by functions like <code>gmtime</code> to obtain leap
386second information on platforms that support leap seconds.
387Another <code>etcetera</code> name, <code>GMT</code>,
388is used by older code releases.
389</p>

--- 30 unchanged lines hidden (view full) ---

420 character set in the current locale.
421 In practice ASCII alphanumerics and '<code>+</code>' and
422 '<code>-</code>' are safe in all locales.
423
424 <p>
425 In other words, in the C locale the POSIX extended regular
426 expression <code>[-+[:alnum:]]{3,6}</code> should match the
427 abbreviation.
385no other source file other than <code>backward</code>
386contains links to its zones.
387One of <code>etcetera</code>'s names is <code>Etc/UTC</code>,
388used by functions like <code>gmtime</code> to obtain leap
389second information on platforms that support leap seconds.
390Another <code>etcetera</code> name, <code>GMT</code>,
391is used by older code releases.
392</p>

--- 30 unchanged lines hidden (view full) ---

423 character set in the current locale.
424 In practice ASCII alphanumerics and '<code>+</code>' and
425 '<code>-</code>' are safe in all locales.
426
427 <p>
428 In other words, in the C locale the POSIX extended regular
429 expression <code>[-+[:alnum:]]{3,6}</code> should match the
430 abbreviation.
428 This guarantees that all abbreviations could have been specified by a
429 POSIX.1-2017 <code>TZ</code> string.
431 This guarantees that all abbreviations could have been specified
432 explicitly by a POSIX proleptic <code>TZ</code> string.
430 </p>
431 </li>
432 <li>
433 Use abbreviations that are in common use among English-speakers,
434 e.g., 'EST' for Eastern Standard Time in North America.
435 We assume that applications translate them to other languages
436 as part of the normal localization process; for example,
437 a French application might translate 'EST' to 'HNE'.

--- 135 unchanged lines hidden (view full) ---

573 Use
574 <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a>
575 (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for
576 locations while uninhabited.
577 The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in
578 some sense undefined; this notation is derived
579 from <a href="https://datatracker.ietf.org/doc/html/rfc3339">Internet
580 <abbr title="Request For Comments">RFC</abbr> 3339</a>.
433 </p>
434 </li>
435 <li>
436 Use abbreviations that are in common use among English-speakers,
437 e.g., 'EST' for Eastern Standard Time in North America.
438 We assume that applications translate them to other languages
439 as part of the normal localization process; for example,
440 a French application might translate 'EST' to 'HNE'.

--- 135 unchanged lines hidden (view full) ---

576 Use
577 <a href="https://en.wikipedia.org/wiki/Universal_Time">Universal Time</a>
578 (<abbr>UT</abbr>) (with time zone abbreviation '<code>-</code>00') for
579 locations while uninhabited.
580 The leading '<code>-</code>' is a flag that the <abbr>UT</abbr> offset is in
581 some sense undefined; this notation is derived
582 from <a href="https://datatracker.ietf.org/doc/html/rfc3339">Internet
583 <abbr title="Request For Comments">RFC</abbr> 3339</a>.
584 (The abbreviation 'Z' that
585 <a href="https://datatracker.ietf.org/doc/html/rfc9557">Internet
586 <abbr>RFC</abbr> 9557</a> uses for this concept
587 would violate the POSIX requirement
588 of at least three characters in an abbreviation.)
581 </li>
582</ul>
583
584<p>
585Application writers should note that these abbreviations are ambiguous
586in practice: e.g., 'CST' means one thing in China and something else
587in North America, and 'IST' can refer to time in India, Ireland or
588Israel.

--- 181 unchanged lines hidden (view full) ---

770 calendar with 24-hour days. These divergences range from
771 relatively minor, such as Japanese bars giving times like "24:30" for the
772 wee hours of the morning, to more-significant differences such as <a
773 href="https://theworld.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the
774 east African practice of starting the day at dawn</a>, renumbering
775 the Western 06:00 to be 12:00. These practices are largely outside
776 the scope of the <code><abbr>tz</abbr></code> code and data, which
777 provide only limited support for date and time localization
589 </li>
590</ul>
591
592<p>
593Application writers should note that these abbreviations are ambiguous
594in practice: e.g., 'CST' means one thing in China and something else
595in North America, and 'IST' can refer to time in India, Ireland or
596Israel.

--- 181 unchanged lines hidden (view full) ---

778 calendar with 24-hour days. These divergences range from
779 relatively minor, such as Japanese bars giving times like "24:30" for the
780 wee hours of the morning, to more-significant differences such as <a
781 href="https://theworld.org/stories/2015-01-30/if-you-have-meeting-ethiopia-you-better-double-check-time">the
782 east African practice of starting the day at dawn</a>, renumbering
783 the Western 06:00 to be 12:00. These practices are largely outside
784 the scope of the <code><abbr>tz</abbr></code> code and data, which
785 provide only limited support for date and time localization
778 such as that required by POSIX.1-2017.
786 such as that required by POSIX.
779 If <abbr>DST</abbr> is not used a different time zone
780 can often do the trick; for example, in Kenya a <code>TZ</code> setting
781 like <code>&lt;-03&gt;3</code> or <code>America/Cayenne</code> starts
782 the day six hours later than <code>Africa/Nairobi</code> does.
783 </li>
784 <li>
785 Early clocks were less reliable, and data entries do not represent
786 clock error.

--- 74 unchanged lines hidden (view full) ---

861 <h2 id="functions">Time and date functions</h2>
862<p>
863The <code><abbr>tz</abbr></code> code contains time and date functions
864that are upwards compatible with those of POSIX.
865Code compatible with this package is already
866<a href="tz-link.html#tzdb">part of many platforms</a>, where the
867primary use of this package is to update obsolete time-related files.
868To do this, you may need to compile the time zone compiler
787 If <abbr>DST</abbr> is not used a different time zone
788 can often do the trick; for example, in Kenya a <code>TZ</code> setting
789 like <code>&lt;-03&gt;3</code> or <code>America/Cayenne</code> starts
790 the day six hours later than <code>Africa/Nairobi</code> does.
791 </li>
792 <li>
793 Early clocks were less reliable, and data entries do not represent
794 clock error.

--- 74 unchanged lines hidden (view full) ---

869 <h2 id="functions">Time and date functions</h2>
870<p>
871The <code><abbr>tz</abbr></code> code contains time and date functions
872that are upwards compatible with those of POSIX.
873Code compatible with this package is already
874<a href="tz-link.html#tzdb">part of many platforms</a>, where the
875primary use of this package is to update obsolete time-related files.
876To do this, you may need to compile the time zone compiler
869'<code>zic</code>' supplied with this package instead of using the
870system '<code>zic</code>', since the format of <code>zic</code>'s
877<code>zic</code> supplied with this package instead of using the
878system <code>zic</code>, since the format of <code>zic</code>'s
871input is occasionally extended, and a platform may still be shipping
872an older <code>zic</code>.
873</p>
874
879input is occasionally extended, and a platform may still be shipping
880an older <code>zic</code>.
881</p>
882
875<h3 id="POSIX">POSIX.1-2017 properties and limitations</h3>
883<p>
884In POSIX, time display in a process is controlled by the
885environment variable <code>TZ</code>, which can have two forms:
886</p>
876<ul>
877 <li>
887<ul>
888 <li>
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
891 notation that specifies a single standard time along with daylight
892 saving rules that apply to all years past, present, and future.
893 </li>
894 <li>
895 A <dfn>geographical <code>TZ</code></dfn> value
896 like <code>Europe/Berlin</code> names a location that stands for
897 civil time near that location, which can have more than
898 one standard time and more than one set of daylight saving rules,
899 to record timekeeping practice more accurately.
900 These names are defined by the <code><abbr>tz</abbr></code> database.
901 </li>
902</ul>
903
904<h3 id="POSIX.1-2017">POSIX.1-2017 properties and limitations</h3>
905<p>
906Some platforms support only the features required by POSIX.1-2017,
907and have not yet upgraded to POSIX.1-2024.
908Code intended to be portable to these platforms must deal
909with problems that were fixed in later POSIX editions.
910</p>
911
912<ul>
913 <li>
914 POSIX.1-2017 does not require support for geographical <code>TZ</code>,
915 and there is no convenient and efficient way to determine
916 the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary
917 timestamps, particularly for timezones
918 that do not fit into the POSIX model.
919 </li>
920 <li>
878 <p>
921 <p>
879 In POSIX.1-2017, time display in a process is controlled by the
880 environment variable <code>TZ</code>.
881 Unfortunately, the POSIX.1-2017
882 <code>TZ</code> string takes a form that is hard to describe and
883 is error-prone in practice.
884 Also, POSIX.1-2017 <code>TZ</code> strings cannot deal with daylight
922 The proleptic <code>TZ</code> string,
923 which is all that POSIX.1-2017 requires,
924 has a format that is hard to describe and is error-prone in practice.
925 Also, proleptic <code>TZ</code> strings cannot deal with daylight
885 saving time rules not based on the Gregorian calendar (as in
886 Morocco), or with situations where more than two time zone
887 abbreviations or <abbr>UT</abbr> offsets are used in an area.
888 </p>
889
890 <p>
926 saving time rules not based on the Gregorian calendar (as in
927 Morocco), or with situations where more than two time zone
928 abbreviations or <abbr>UT</abbr> offsets are used in an area.
929 </p>
930
931 <p>
891 The POSIX.1-2017 <code>TZ</code> string takes the following form:
932 A proleptic <code>TZ</code> string has the following format:
892 </p>
893
894 <p>
895 <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>]]]
896 </p>
897
898 <p>
899 where:

--- 50 unchanged lines hidden (view full) ---

950 Typically, this is the only useful form; the <var>n</var>
951 and <code>J</code><var>n</var> forms are rarely used.
952 </dd>
953 </dl>
954 </dd>
955 </dl>
956
957 <p>
933 </p>
934
935 <p>
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>]]]
937 </p>
938
939 <p>
940 where:

--- 50 unchanged lines hidden (view full) ---

991 Typically, this is the only useful form; the <var>n</var>
992 and <code>J</code><var>n</var> forms are rarely used.
993 </dd>
994 </dl>
995 </dd>
996 </dl>
997
998 <p>
958 Here is an example POSIX.1-2017 <code>TZ</code> string for New
999 Here is an example proleptic <code>TZ</code> string for New
959 Zealand after 2007.
960 It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead
961 of <abbr>UT</abbr>, and that daylight saving time
962 (<abbr>NZDT</abbr>) is observed from September's last Sunday at
963 02:00 until April's first Sunday at 03:00:
964 </p>
965
966 <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
967
968 <p>
1000 Zealand after 2007.
1001 It says that standard time (<abbr>NZST</abbr>) is 12 hours ahead
1002 of <abbr>UT</abbr>, and that daylight saving time
1003 (<abbr>NZDT</abbr>) is observed from September's last Sunday at
1004 02:00 until April's first Sunday at 03:00:
1005 </p>
1006
1007 <pre><code>TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'</code></pre>
1008
1009 <p>
969 This POSIX.1-2017 <code>TZ</code> string is hard to remember, and
1010 This proleptic <code>TZ</code> string is hard to remember, and
970 mishandles some timestamps before 2008.
1011 mishandles some timestamps before 2008.
971 With this package you can use this instead:
1012 With this package you can use a geographical <code>TZ</code> instead:
972 </p>
973
974 <pre><code>TZ='Pacific/Auckland'</code></pre>
975 </li>
1013 </p>
1014
1015 <pre><code>TZ='Pacific/Auckland'</code></pre>
1016 </li>
1017</ul>
1018
1019<p>
1020POSIX.1-2017 also has the limitations of POSIX.1-2024,
1021discussed in the next section.
1022</p>
1023
1024<h3 id="POSIX.1-2024">POSIX.1-2024 properties and limitations</h3>
1025<p>
1026POSIX.1-2024 extends POSIX.1-2017 in the following significant ways:
1027</p>
1028<ul>
976 <li>
1029 <li>
977 POSIX does not define the <abbr>DST</abbr> transitions
978 for <code>TZ</code> values like
979 "<code>EST5EDT</code>".
980 Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules
981 were used to interpret such values, but this meant that the
982 <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each
983 time conversion package, and when
984 <abbr>US</abbr> time conversion rules changed (as in the United
985 States in 1987 and again in 2007), all packages that
986 interpreted <code>TZ</code> values had to be updated
987 to ensure proper results.
1030 POSIX.1-2024 requires support for geographical <code>TZ</code>.
1031 Earlier POSIX editions require support only for proleptic <code>TZ</code>.
988 </li>
989 <li>
1032 </li>
1033 <li>
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>.
1037 Earlier POSIX editions lack this requirement.
1038 </li>
1039 <li>
1040 DST transition times can range from &minus;167:59:59
1041 to 167:59:59 instead of merely from 00:00:00 to 24:59:59.
1042 This allows for proleptic TZ strings
1043 like <code>"&lt;-02&gt;2&lt;-01&gt;,M3.5.0/-1,M10.5.0/0"</code>
1044 where the transition time &minus;1:00 means 23:00 the previous day.
1045 </li>
1046</ul>
1047<p>
1048However POSIX.1-2024, like earlier POSIX editions, has some limitations:
1049<ul>
1050 <li>
990 The <code>TZ</code> environment variable is process-global, which
991 makes it hard to write efficient, thread-safe applications that
992 need access to multiple timezones.
993 </li>
994 <li>
995 In POSIX, there is no tamper-proof way for a process to learn the
996 system's best idea of local (wall clock) time.
997 This is important for applications that an administrator wants
998 used only at certain times &ndash; without regard to whether the
999 user has fiddled the
1000 <code>TZ</code> environment variable.
1001 While an administrator can "do everything in <abbr>UT</abbr>" to
1002 get around the problem, doing so is inconvenient and precludes
1003 handling daylight saving time shifts &ndash; as might be required to
1004 limit phone calls to off-peak hours.
1005 </li>
1006 <li>
1051 The <code>TZ</code> environment variable is process-global, which
1052 makes it hard to write efficient, thread-safe applications that
1053 need access to multiple timezones.
1054 </li>
1055 <li>
1056 In POSIX, there is no tamper-proof way for a process to learn the
1057 system's best idea of local (wall clock) time.
1058 This is important for applications that an administrator wants
1059 used only at certain times &ndash; without regard to whether the
1060 user has fiddled the
1061 <code>TZ</code> environment variable.
1062 While an administrator can "do everything in <abbr>UT</abbr>" to
1063 get around the problem, doing so is inconvenient and precludes
1064 handling daylight saving time shifts &ndash; as might be required to
1065 limit phone calls to off-peak hours.
1066 </li>
1067 <li>
1007 POSIX.1-2017 provides no convenient and efficient way to determine
1008 the <abbr>UT</abbr> offset and time zone abbreviation of arbitrary
1009 timestamps, particularly for timezones
1010 that do not fit into the POSIX model.
1011 </li>
1012 <li>
1013 POSIX requires that <code>time_t</code> clock counts exclude leap
1014 seconds.
1015 </li>
1016 <li>
1068 POSIX requires that <code>time_t</code> clock counts exclude leap
1069 seconds.
1070 </li>
1071 <li>
1072 POSIX does not define the <abbr>DST</abbr> transitions
1073 for <code>TZ</code> values like
1074 "<code>EST5EDT</code>".
1075 Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules
1076 were used to interpret such values, but this meant that the
1077 <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each
1078 time conversion package, and when
1079 <abbr>US</abbr> time conversion rules changed (as in the United
1080 States in 1987 and again in 2007), all packages that
1081 interpreted <code>TZ</code> values had to be updated
1082 to ensure proper results.
1083 </li>
1084</ul>
1085
1086<h3 id="POSIX-extensions">Extensions to POSIX in the
1087<code><abbr>tz</abbr></code> code</h3>
1088<p>
1089 The <code><abbr>tz</abbr></code> code defines some properties
1090 left unspecified by POSIX, and attempts to support some
1091 extensions to POSIX.
1092</p>
1093
1094<ul>
1095 <li>
1017 The <code><abbr>tz</abbr></code> code attempts to support all the
1018 <code>time_t</code> implementations allowed by POSIX.
1019 The <code>time_t</code> type represents a nonnegative count of seconds
1020 since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap seconds.
1021 In practice, <code>time_t</code> is usually a signed 64- or 32-bit
1022 integer; 32-bit signed <code>time_t</code> values stop working after
1023 2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these
1024 days typically use a signed 64-bit integer.
1025 Unsigned 32-bit integers are used on one or two platforms, and 36-bit
1026 and 40-bit integers are also used occasionally.
1027 Although earlier POSIX versions allowed <code>time_t</code> to be a
1028 floating-point type, this was not supported by any practical system,
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
1099 since 1970-01-01 00:00:00 <abbr>UTC</abbr>, ignoring leap 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
1102 2038-01-19 03:14:07 <abbr>UTC</abbr>, so new implementations these
1103 days typically use a signed 64-bit integer.
1104 Unsigned 32-bit integers are used on one or two platforms, and 36-bit
1105 and 40-bit integers are also used occasionally.
1106 Although earlier POSIX versions allowed <code>time_t</code> to be a
1107 floating-point type, this was not supported by any practical system,
1029 and POSIX.1-2013 and the <code><abbr>tz</abbr></code> code both
1108 and POSIX.1-2013+ and the <code><abbr>tz</abbr></code> code both
1030 require <code>time_t</code> to be an integer type.
1031 </li>
1109 require <code>time_t</code> to be an integer type.
1110 </li>
1032</ul>
1033
1034<h3 id="POSIX-extensions">Extensions to POSIX.1-2017 in the
1035<code><abbr>tz</abbr></code> code</h3>
1036<ul>
1037 <li>
1038 <p>
1111 <li>
1112 <p>
1039 The <code>TZ</code> environment variable is used in generating
1040 the name of a file from which time-related information is read
1041 (or is interpreted à la POSIX.1-2017); <code>TZ</code> is no longer
1042 constrained to be a string containing abbreviations
1043 and numeric data as described <a href="#POSIX">above</a>.
1113 If the <code>TZ</code> environment variable uses the geographical format,
1114 it is used in generating
1115 the name of a file from which time-related information is read.
1044 The file's format is <dfn><abbr>TZif</abbr></dfn>,
1045 a timezone information format that contains binary data; see
1046 <a href="https://datatracker.ietf.org/doc/html/8536">Internet
1047 <abbr>RFC</abbr> 8536</a>.
1048 The daylight saving time rules to be used for a
1049 particular timezone are encoded in the
1050 <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>,
1051 Australian, and other rules to be encoded, and
1052 allows for situations where more than two time zone
1053 abbreviations are used.
1054 </p>
1055 <p>
1116 The file's format is <dfn><abbr>TZif</abbr></dfn>,
1117 a timezone information format that contains binary data; see
1118 <a href="https://datatracker.ietf.org/doc/html/8536">Internet
1119 <abbr>RFC</abbr> 8536</a>.
1120 The daylight saving time rules to be used for a
1121 particular timezone are encoded in the
1122 <abbr>TZif</abbr> file; the format of the file allows <abbr>US</abbr>,
1123 Australian, and other rules to be encoded, and
1124 allows for situations where more than two time zone
1125 abbreviations are used.
1126 </p>
1127 <p>
1056 It was recognized that allowing the <code>TZ</code> environment
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
1057 variable to take on values such as '<code>America/New_York</code>'
1058 might cause "old" programs (that expect <code>TZ</code> to have a
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
1059 certain form) to operate incorrectly; consideration was given to using
1132 certain format) to operate incorrectly; consideration was given to using
1060 some other environment variable (for example, <code>TIMEZONE</code>)
1061 to hold the string used to generate the <abbr>TZif</abbr> file's name.
1062 In the end, however, it was decided to continue using
1063 <code>TZ</code>: it is widely used for time zone purposes;
1064 separately maintaining both <code>TZ</code>
1065 and <code>TIMEZONE</code> seemed a nuisance; and systems where
1066 "new" forms of <code>TZ</code> might cause problems can simply
1067 use legacy <code>TZ</code> values such as "<code>EST5EDT</code>" which
1068 can be used by "new" programs as well as by "old" programs that
1069 assume pre-POSIX <code>TZ</code> values.
1070 </p>
1071 </li>
1072 <li>
1133 some other environment variable (for example, <code>TIMEZONE</code>)
1134 to hold the string used to generate the <abbr>TZif</abbr> file's name.
1135 In the end, however, it was decided to continue using
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
1141 can be used by "new" programs as well as by "old" programs that
1142 assume pre-POSIX <code>TZ</code> values.
1143 </p>
1144 </li>
1145 <li>
1073 The code supports platforms with a <abbr>UT</abbr> offset member
1074 in <code>struct tm</code>, e.g., <code>tm_gmtoff</code>,
1075 or with a time zone abbreviation member in
1076 <code>struct tm</code>, e.g., <code>tm_zone</code>. As noted
1077 in <a href="https://austingroupbugs.net/view.php?id=1533">Austin
1078 Group defect 1533</a>, a future version of POSIX is planned to
1079 require <code>tm_gmtoff</code> and <code>tm_zone</code>.
1080 </li>
1081 <li>
1082 Functions <code>tzalloc</code>, <code>tzfree</code>,
1083 <code>localtime_rz</code>, and <code>mktime_z</code> for
1084 more-efficient thread-safe applications that need to use multiple
1085 timezones.
1086 The <code>tzalloc</code> and <code>tzfree</code> functions
1087 allocate and free objects of type <code>timezone_t</code>,
1088 and <code>localtime_rz</code> and <code>mktime_z</code> are
1089 like <code>localtime_r</code> and <code>mktime</code> with an
1090 extra <code>timezone_t</code> argument.
1146 Functions <code>tzalloc</code>, <code>tzfree</code>,
1147 <code>localtime_rz</code>, and <code>mktime_z</code> for
1148 more-efficient thread-safe applications that need to use multiple
1149 timezones.
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.
1091 The functions were inspired by <a href="https://netbsd.org/">NetBSD</a>.
1155 The functions were inspired by <a href="https://netbsd.org">NetBSD</a>.
1092 </li>
1093 <li>
1094 Negative <code>time_t</code> values are supported, on systems
1095 where <code>time_t</code> is signed.
1096 </li>
1097 <li>
1098 These functions can account for leap seconds;
1099 see <a href="#leapsec">Leap seconds</a> below.

--- 11 unchanged lines hidden (view full) ---

1111vestigial <abbr>API</abbr>s for backwards compatibility, they should
1112be avoided in portable applications.
1113The vestigial <abbr>API</abbr>s are:
1114</p>
1115<ul>
1116 <li>
1117 The POSIX <code>tzname</code> variable does not suffice and is no
1118 longer needed.
1156 </li>
1157 <li>
1158 Negative <code>time_t</code> values are supported, on systems
1159 where <code>time_t</code> is signed.
1160 </li>
1161 <li>
1162 These functions can account for leap seconds;
1163 see <a href="#leapsec">Leap seconds</a> below.

--- 11 unchanged lines hidden (view full) ---

1175vestigial <abbr>API</abbr>s for backwards compatibility, they should
1176be avoided in portable applications.
1177The vestigial <abbr>API</abbr>s are:
1178</p>
1179<ul>
1180 <li>
1181 The POSIX <code>tzname</code> variable does not suffice and is no
1182 longer needed.
1183 It is planned to be removed in a future edition of POSIX.
1119 To get a timestamp's time zone abbreviation, consult
1120 the <code>tm_zone</code> member if available; otherwise,
1121 use <code>strftime</code>'s <code>"%Z"</code> conversion
1122 specification.
1123 </li>
1124 <li>
1125 The POSIX <code>daylight</code> and <code>timezone</code>
1126 variables do not suffice and are no longer needed.
1184 To get a timestamp's time zone abbreviation, consult
1185 the <code>tm_zone</code> member if available; otherwise,
1186 use <code>strftime</code>'s <code>"%Z"</code> conversion
1187 specification.
1188 </li>
1189 <li>
1190 The POSIX <code>daylight</code> and <code>timezone</code>
1191 variables do not suffice and are no longer needed.
1192 They are planned to be removed in a future edition of POSIX.
1127 To get a timestamp's <abbr>UT</abbr> offset, consult
1128 the <code>tm_gmtoff</code> member if available; otherwise,
1129 subtract values returned by <code>localtime</code>
1130 and <code>gmtime</code> using the rules of the Gregorian calendar,
1131 or use <code>strftime</code>'s <code>"%z"</code> conversion
1132 specification if a string like <code>"+0900"</code> suffices.
1133 </li>
1134 <li>

--- 138 unchanged lines hidden (view full) ---

1273</p>
1274</section>
1275
1276<section>
1277 <h2 id="leapsec">Leap seconds</h2>
1278<p>
1279Leap seconds were introduced in 1972 to accommodate the
1280difference between atomic time and the less regular rotation of the earth.
1193 To get a timestamp's <abbr>UT</abbr> offset, consult
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.
1199 </li>
1200 <li>

--- 138 unchanged lines hidden (view full) ---

1339</p>
1340</section>
1341
1342<section>
1343 <h2 id="leapsec">Leap seconds</h2>
1344<p>
1345Leap seconds were introduced in 1972 to accommodate the
1346difference between atomic time and the less regular rotation of the earth.
1281Unfortunately they caused so many problems with civil
1282timekeeping that they
1283are <a href="https://www.bipm.org/en/cgpm-2022/resolution-4">planned
1284to be discontinued by 2035</a>, with some as-yet-undetermined
1285mechanism replacing them, perhaps after the year 2135.
1286Despite their impending obsolescence, a record of leap seconds is still
1287needed to resolve timestamps from 1972 through 2035.
1347Unfortunately they have caused so many problems with civil
1348timekeeping that there are
1349<a href="https://www.bipm.org/en/cgpm-2022/resolution-4">plans
1350to discontinue them by 2035</a>.
1351Even if these plans come to fruition, a record of leap seconds will still be
1352needed to resolve timestamps from 1972 through 2035,
1353and there may also be a need to record whatever mechanism replaces them.
1288</p>
1289
1290<p>
1291The <code><abbr>tz</abbr></code> code and data can account for leap seconds,
1292thanks to code contributed by Bradley White.
1293However, the leap second support of this package is rarely used directly
1294because POSIX requires leap seconds to be excluded and many
1295software packages would mishandle leap seconds if they were present.

--- 73 unchanged lines hidden (view full) ---

1369<section>
1370 <h2 id="planets">Time and time zones off Earth</h2>
1371<p>
1372The European Space Agency is <a
1373href='https://www.esa.int/Applications/Navigation/Telling_time_on_the_Moon'>considering</a>
1374the establishment of a reference timescale for the Moon, which has
1375days roughly equivalent to 29.5 Earth days, and where relativistic
1376effects cause clocks to tick slightly faster than on Earth.
1354</p>
1355
1356<p>
1357The <code><abbr>tz</abbr></code> code and data can account for leap seconds,
1358thanks to code contributed by Bradley White.
1359However, the leap second support of this package is rarely used directly
1360because POSIX requires leap seconds to be excluded and many
1361software packages would mishandle leap seconds if they were present.

--- 73 unchanged lines hidden (view full) ---

1435<section>
1436 <h2 id="planets">Time and time zones off Earth</h2>
1437<p>
1438The European Space Agency is <a
1439href='https://www.esa.int/Applications/Navigation/Telling_time_on_the_Moon'>considering</a>
1440the establishment of a reference timescale for the Moon, which has
1441days roughly equivalent to 29.5 Earth days, and where relativistic
1442effects cause clocks to tick slightly faster than on Earth.
1443Also, <abbr title="National Aeronautics and Space Administration">NASA</abbr>
1444has been <a
1445href='https://www.whitehouse.gov/wp-content/uploads/2024/04/Celestial-Time-Standardization-Policy.pdf'>ordered</a>
1446to consider the establishment of Coordinated Lunar Time (<abbr>LTC</abbr>).
1447It is not yet known whether the US and European efforts will result in
1448multiple timescales on the Moon.
1377</p>
1378
1379<p>
1380Some people's work schedules have used
1381<a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>.
1382Jet Propulsion Laboratory (JPL) coordinators kept Mars time on
1383and off during the
1384<a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars

--- 122 unchanged lines hidden --- 		1449</p>
1450
1451<p>
1452Some people's work schedules have used
1453<a href="https://en.wikipedia.org/wiki/Timekeeping_on_Mars">Mars time</a>.
1454Jet Propulsion Laboratory (JPL) coordinators kept Mars time on
1455and off during the
1456<a href="https://en.wikipedia.org/wiki/Mars_Pathfinder">Mars

--- 122 unchanged lines hidden ---