123 lines · plain
1=================2Time Zone Support3=================4 5Introduction6============7 8Starting with C++20 the ``<chrono>`` library has support for time zones.9These are available in the10`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 this12feature. This page contains several links with more information regarding the13contents of the IANA database, this page assumes the reader is familiar with14this information.15 16Which version of the Time Zone Database to use17==============================================18 19The data of the database is available on several platforms in different forms:20 21- Typically Unix systems ship the database as22 `TZif files <https://www.rfc-editor.org/rfc/rfc8536.html>`_. This format has23 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 information26 is needed for the functions ``std::chrono:: remote_version()`` and27 ``std::chrono::reload_tzdb()``.28 29- On several Unix systems the time zone source files are available. These files30 are stored in several regions, mainly the continents. This file contains a31 large amount of comment with historical information regarding time zones.32 The format is documented in the33 `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 have36 the database version information. This information is needed for the functions37 ``std::chrono:: remote_version()`` and ``std::chrono::reload_tzdb()``.38 39- On Linux systems ``tzdata.zi`` is available. This contains the same40 information as the source files but in one file without the comments. This41 file uses the same format as the sources, but shortens the names. For example42 ``Rule`` is abbreviated to ``R``. This file contains the database version43 information.44 45The disadvantage of the ``TZif`` format (which is a binary format) is that it's46not 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 decided52to use the ``tzdata.zi``. The other benefit is that the ``tzdata.zi`` file53contains the database version information needed for a conforming54implementation.55 56The ``tzdata.zi`` file is not available on all platforms as of August 2023, so57some vendors will need to make changes to their platform. Most vendors already58ship the database, so they only need to adjust the packaging of their time zone59package 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 for61Windows packagers to add these files to their libc++ packages. The IANA62databases can be63`downloaded <https://data.iana.org/time-zones/releases/>`_.64 65An alternative would be to ship the database with libc++, either as a file or66compiled in the dylib. The text file is about 112 KB. For now libc++ will not67ship this file. If it's hard to get vendors to ship these files we can68reconsider based on that information.69 70Leap seconds71------------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 are75present on Linux, but not always on other platforms. Since these platforms need76to change their packaging for ``tzdata.zi``, adding two instead of one files77seems a small change.78 79 80Updating the Time Zone Database81===============================82 83Per `[time.zone.db.remote]/1 <http://eel.is/c++draft/time.zone#db.remote-1>`_84 85.. code-block:: text86 87 The local time zone database is that supplied by the implementation when the88 program first accesses the database, for example via current_zone(). While the89 program is running, the implementation may choose to update the time zone90 database. This update shall not impact the program in any way unless the91 program calls the functions in this subclause. This potentially updated time92 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 version96information of the ``tzdata.zi`` file and return that information. Similarly,97``std::chrono::reload_tzdb()`` will parse the ``tzdata.zi`` and98``leap-seconds.list`` again. This makes it possible to update the database if99needed 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 poll105 changes to the filesystem. When using a background process, it may become106 active when the application is busy with its core task, taking away resources107 from that task.108- If there is no threading available this polling109 becomes more involved. For example, query the file every *x* calls to110 ``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 background117 process.118 119Another issue with the automatic update is that it may not be considered120Standard compliant, since the Standard uses the wording "This update shall not121impact the program in any way". Using resources could be considered as122impacting the program.123