1================= 2Time Zone Support 3================= 4 5Introduction 6============ 7 8Starting with C++20 the ``<chrono>`` library has support for time zones. 9These are available in the 10`IANA Time Zone Database <https://data.iana.org/time-zones/tz-link.html>`_. 11This page describes the design decisions and trade-offs made to implement this 12feature. This page contains several links with more information regarding the 13contents of the IANA database, this page assumes the reader is familiar with 14this information. 15 16Which version of the Time Zone Database to use 17============================================== 18 19The data of the database is available on several platforms in different forms: 20 21- Typically Unix systems ship the database as 22 `TZif files <https://www.rfc-editor.org/rfc/rfc8536.html>`_. This format has 23 3 versions and the ``time_zone_link`` information is not always available. 24 If available, they are symlinks in the file system. 25 These files don't provide the database version information. This information 26 is needed for the functions ``std::chrono:: remote_version()`` and 27 ``std::chrono::reload_tzdb()``. 28 29- On several Unix systems the time zone source files are available. These files 30 are stored in several regions, mainly the continents. This file contains a 31 large amount of comment with historical information regarding time zones. 32 The format is documented in the 33 `IANA documentation <https://data.iana.org/time-zones/tz-how-to.html>`_ 34 and in the `man page <https://man7.org/linux/man-pages/man8/zic.8.html>`_ of zic. 35 The disadvantage of this version is that at least Linux versions don't have 36 the database version information. This information is needed for the functions 37 ``std::chrono:: remote_version()`` and ``std::chrono::reload_tzdb()``. 38 39- On Linux systems ``tzdata.zi`` is available. This contains the same 40 information as the source files but in one file without the comments. This 41 file uses the same format as the sources, but shortens the names. For example 42 ``Rule`` is abbreviated to ``R``. This file contains the database version 43 information. 44 45The disadvantage of the ``TZif`` format (which is a binary format) is that it's 46not possible to get the proper ``time_zone_link`` information on all platforms. 47The time zone database version number is also missing from ``TZif`` files. 48Since the time zone database is supposed to contain both these informations, 49``TZif`` files can't be used to create a conforming implementation. 50 51Since it's easier to parse one file than a set of files we decided 52to use the ``tzdata.zi``. The other benefit is that the ``tzdata.zi`` file 53contains the database version information needed for a conforming 54implementation. 55 56The ``tzdata.zi`` file is not available on all platforms as of August 2023, so 57some vendors will need to make changes to their platform. Most vendors already 58ship the database, so they only need to adjust the packaging of their time zone 59package to include the files we require. One notable exception is Windows, 60where no IANA time zone database is provided at all. However it's possible for 61Windows packagers to add these files to their libc++ packages. The IANA 62databases can be 63`downloaded <https://data.iana.org/time-zones/releases/>`_. 64 65An alternative would be to ship the database with libc++, either as a file or 66compiled in the dylib. The text file is about 112 KB. For now libc++ will not 67ship this file. If it's hard to get vendors to ship these files we can 68reconsider based on that information. 69 70Leap seconds 71------------ 72 73For the leap seconds libc++ will use the source file ``leap-seconds.list``. 74This file is easier to parse than the ``leapseconds`` file. Both files are 75present on Linux, but not always on other platforms. Since these platforms need 76to change their packaging for ``tzdata.zi``, adding two instead of one files 77seems a small change. 78 79 80Updating the Time Zone Database 81=============================== 82 83Per `[time.zone.db.remote]/1 <http://eel.is/c++draft/time.zone#db.remote-1>`_ 84 85.. code-block:: text 86 87 The local time zone database is that supplied by the implementation when the 88 program first accesses the database, for example via current_zone(). While the 89 program is running, the implementation may choose to update the time zone 90 database. This update shall not impact the program in any way unless the 91 program calls the functions in this subclause. This potentially updated time 92 zone database is referred to as the remote time zone database. 93 94There is an update mechanism in libc++, however this is not done automatically. 95Invoking the function ``std::chrono::remote_version()`` will parse the version 96information of the ``tzdata.zi`` file and return that information. Similarly, 97``std::chrono::reload_tzdb()`` will parse the ``tzdata.zi`` and 98``leap-seconds.list`` again. This makes it possible to update the database if 99needed by the application and gives the user full power over the update policy. 100 101This approach has several advantages: 102 103- It is simple to implement. 104- The library does not need to start a periodic background process to poll 105 changes to the filesystem. When using a background process, it may become 106 active when the application is busy with its core task, taking away resources 107 from that task. 108- If there is no threading available this polling 109 becomes more involved. For example, query the file every *x* calls to 110 ``std::chrono::get_tzdb()``. This mean calls to ``std::chrono::get_tzdb()`` 111 would have different performance characteristics. 112 113The small drawback is: 114 115- On platforms with threading enabled updating the database may take longer. 116 On these platforms the remote database could have been loaded in a background 117 process. 118 119Another issue with the automatic update is that it may not be considered 120Standard compliant, since the Standard uses the wording "This update shall not 121impact the program in any way". Using resources could be considered as 122impacting the program. 123