From: Tomasz Kamiński <[email protected]>
libstdc++-v3/ChangeLog:
* doc/Makefile.am: Add time.xml.
* doc/Makefile.in: Regenerate.
* doc/html/*: Regenerate.
* doc/xml/manual/spine.xml: Add time.xml.
* doc/xml/manual/time.xml: New file.
---
Same patch again but without the huge changes to the generated HTML
files, because that made the patch too big for gcc-patches.
libstdc++-v3/doc/Makefile.am | 1 +
libstdc++-v3/doc/Makefile.in | 1 +
libstdc++-v3/doc/html/index.html | 15 +-
libstdc++-v3/doc/html/manual/api.html | 2 +-
libstdc++-v3/doc/html/manual/atomics.html | 8 +-
.../doc/html/manual/bitmap_allocator.html | 4 +-
.../html/manual/bitmap_allocator_impl.html | 6 +-
libstdc++-v3/doc/html/manual/concurrency.html | 8 +-
libstdc++-v3/doc/html/manual/debug.html | 6 +-
libstdc++-v3/doc/html/manual/debug_mode.html | 6 +-
.../doc/html/manual/debug_mode_design.html | 4 +-
.../doc/html/manual/debug_mode_semantics.html | 4 +-
.../doc/html/manual/debug_mode_using.html | 6 +-
.../doc/html/manual/ext_algorithms.html | 6 +-
.../doc/html/manual/ext_compile_checks.html | 6 +-
.../doc/html/manual/ext_concurrency.html | 6 +-
.../doc/html/manual/ext_concurrency_impl.html | 4 +-
.../doc/html/manual/ext_concurrency_use.html | 2 +-
.../doc/html/manual/ext_containers.html | 4 +-
.../doc/html/manual/ext_demangling.html | 6 +-
libstdc++-v3/doc/html/manual/ext_io.html | 6 +-
.../doc/html/manual/ext_iterators.html | 6 +-
.../doc/html/manual/ext_numerics.html | 6 +-
libstdc++-v3/doc/html/manual/ext_preface.html | 4 +-
libstdc++-v3/doc/html/manual/ext_sgi.html | 4 +-
.../doc/html/manual/ext_utilities.html | 6 +-
libstdc++-v3/doc/html/manual/extensions.html | 8 +-
libstdc++-v3/doc/html/manual/fstreams.html | 2 +-
libstdc++-v3/doc/html/manual/index.html | 31 ++-
libstdc++-v3/doc/html/manual/io.html | 13 +-
libstdc++-v3/doc/html/manual/io_and_c.html | 6 +-
libstdc++-v3/doc/html/manual/memory.html | 6 +-
.../doc/html/manual/mt_allocator.html | 4 +-
.../doc/html/manual/mt_allocator_design.html | 4 +-
.../html/manual/mt_allocator_ex_multi.html | 4 +-
.../html/manual/mt_allocator_ex_single.html | 2 +-
.../doc/html/manual/mt_allocator_impl.html | 2 +-
.../doc/html/manual/numerics_and_c.html | 8 +-
.../doc/html/manual/parallel_mode.html | 4 +-
.../doc/html/manual/parallel_mode_design.html | 2 +-
.../html/manual/parallel_mode_semantics.html | 4 +-
.../doc/html/manual/parallel_mode_test.html | 4 +-
.../doc/html/manual/parallel_mode_using.html | 4 +-
.../policy_based_data_structures_test.html | 2 +-
.../html/manual/policy_data_structures.html | 16 +-
.../manual/policy_data_structures_ack.html | 4 +-
.../manual/policy_data_structures_design.html | 70 ++---
.../manual/policy_data_structures_using.html | 6 +-
libstdc++-v3/doc/html/manual/status.html | 4 +-
.../doc/html/manual/std_contents.html | 9 +-
libstdc++-v3/doc/html/manual/streambufs.html | 4 +-
.../doc/html/manual/stringstreams.html | 2 +-
libstdc++-v3/doc/html/manual/test.html | 8 +-
libstdc++-v3/doc/html/manual/time.html | 176 +++++++++++++
libstdc++-v3/doc/html/manual/using.html | 2 +-
.../doc/html/manual/using_macros.html | 10 +-
libstdc++-v3/doc/xml/manual/spine.xml | 10 +-
libstdc++-v3/doc/xml/manual/time.xml | 242 ++++++++++++++++++
58 files changed, 623 insertions(+), 187 deletions(-)
create mode 100644 libstdc++-v3/doc/html/manual/time.html
create mode 100644 libstdc++-v3/doc/xml/manual/time.xml
diff --git a/libstdc++-v3/doc/Makefile.am b/libstdc++-v3/doc/Makefile.am
index 330b07ccf8ce..69f5faafc266 100644
--- a/libstdc++-v3/doc/Makefile.am
+++ b/libstdc++-v3/doc/Makefile.am
@@ -357,6 +357,7 @@ xml_sources_manual = \
${xml_dir}/manual/support.xml \
${xml_dir}/manual/test.xml \
${xml_dir}/manual/test_policy_data_structures.xml \
+ ${xml_dir}/manual/time.xml \
${xml_dir}/manual/using.xml \
${xml_dir}/manual/using_exceptions.xml \
${xml_dir}/manual/utilities.xml \
diff --git a/libstdc++-v3/doc/Makefile.in b/libstdc++-v3/doc/Makefile.in
index 6e7a5a0f9084..39a6988d4853 100644
--- a/libstdc++-v3/doc/Makefile.in
+++ b/libstdc++-v3/doc/Makefile.in
@@ -509,6 +509,7 @@ xml_sources_manual = \
${xml_dir}/manual/support.xml \
${xml_dir}/manual/test.xml \
${xml_dir}/manual/test_policy_data_structures.xml \
+ ${xml_dir}/manual/time.xml \
${xml_dir}/manual/using.xml \
${xml_dir}/manual/using_exceptions.xml \
${xml_dir}/manual/utilities.xml \
diff --git a/libstdc++-v3/doc/xml/manual/spine.xml
b/libstdc++-v3/doc/xml/manual/spine.xml
index eff72bc13d72..47536f000778 100644
--- a/libstdc++-v3/doc/xml/manual/spine.xml
+++ b/libstdc++-v3/doc/xml/manual/spine.xml
@@ -197,15 +197,19 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"
href="numerics.xml">
</xi:include>
-<!-- Chapter 10 : Input Output -->
+<!-- Chapter 10 : Time -->
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"
href="time.xml">
+</xi:include>
+
+<!-- Chapter 11 : Input Output -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"
href="io.xml">
</xi:include>
-<!-- Chapter 11 : Atomics -->
+<!-- Chapter 12 : Atomics -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"
href="atomics.xml">
</xi:include>
-<!-- Chapter 12 : Concurrency -->
+<!-- Chapter 13 : Concurrency -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="xml"
href="concurrency.xml">
</xi:include>
diff --git a/libstdc++-v3/doc/xml/manual/time.xml
b/libstdc++-v3/doc/xml/manual/time.xml
new file mode 100644
index 000000000000..b61be5852ef2
--- /dev/null
+++ b/libstdc++-v3/doc/xml/manual/time.xml
@@ -0,0 +1,242 @@
+<chapter xmlns="http://docbook.org/ns/docbook"; version="5.0"
+ xml:id="std.time" xreflabel="Time">
+<?dbhtml filename="time.html"?>
+
+<info><title>
+ Time
+ <indexterm><primary>Time</primary></indexterm>
+</title>
+ <keywordset>
+ <keyword>ISO C++</keyword>
+ <keyword>library</keyword>
+ </keywordset>
+</info>
+
+<!-- Sect1 01 : Time zone database -->
+<section xml:id="std.time.zone.db" xreflabel=""><info><title>Time zone
database</title></info>
+<?dbhtml filename="tzdb.html"?>
+
+ <para>
+ Since C++20 the <code><chrono></code> header provides time zone
+ support via <code>std::chrono::tzdb</code>, a complete interface to the
+ <link xmlns:xlink="http://www.w3.org/1999/xlink";
+ xlink:href="https://www.iana.org/time-zones";>IANA Time Zone
Database</link>.
+ The library supports converting times between UTC and the local time
+ in a specific time zone, querying UTC offsets and DST information for a
+ given time zone on a given date, and finding the system's current time
zone.
+ Key entry points are <code>std::chrono::get_tzdb()</code> to access
+ the database, <code>std::chrono::locate_zone()</code> to look up
+ a zone by name, and <code>std::chrono::current_zone()</code> to obtain
+ the system's local time zone. The <code>std::chrono::zoned_time</code>
+ class template represents a time point in a given time zone.
+ The database can be reloaded at runtime
+ via <code>std::chrono::reload_tzdb()</code> to pick up updated zone
+ data without restarting the program.
+ </para>
+
+ <para>
+ The <link xmlns:xlink="http://www.w3.org/1999/xlink";
+ xlink:href="https://howardhinnant.github.io/date/tz.html";>Time Zone
Database
+ Parser</link> by Howard E. Hinnant is a valuable source of information and
+ examples of usage for the <code>date</code> library, on which the standard
+ API is based.
+ </para>
+
+ <section xml:id="zone.db.zic" xreflabel="tzdb uses zic
format"><info><title>tzdb uses zic format</title></info>
+
+ <para>
+ When support is enabled (which is default) the time zone database class,
+ <code>tzdb</code>, uses the <link
xmlns:xlink="http://www.w3.org/1999/xlink";
+ xlink:href="https://man7.org/linux/man-pages/man8/zic.8.html#FILES";>
+ <code>zic</code> file format</link>, both as the format of the input
+ files, and for in-memory representation. This results in a reduced
+ memory footprint for many programs, as time zone data is stored in
+ a compact form until needed by the application.
+ </para>
+ <para>
+ The transitions to/from DST (Daylight Savings Time) are generated and
+ cached on the fly, when information
+ for a given zone is requested. Consequently, the initial request for
+ UTC conversion for a given <code>time_zone</code> object is slower.
+ To mitigate this, a <code>time_zone</code> can be expanded for a
+ particular time range at the start
+ of the program (and after each reload), by iterating over the
+ <code>sys_info</code> dequence, as in the example below.
+ </para>
+ <programlisting>
+ void
+ expand_zone(const std::chrono::time_zone* tz,
+ const std::chrono::sys_seconds start,
+ const std::chrono::sys_seconds end)
+ {
+ std::chrono::sys_seconds time = start;
+ while (time < end) {
+ const std::chrono::sys_info& info = tz->get_info(time);
+ time = info.end + std::chrono::seconds(1);
+ }
+ }
+ </programlisting>
+ </section>
+
+ <section xml:id="zone.current" xreflabel="current zone"><info><title>current
zone</title></info>
+
+ <para>
+ The <code>time_zone</code> pointer returned from
+ <code>std::chrono::current_zone</code>, is determined by looking up
+ (by <code>std::chrono::locate_zone</code>) IANA zone name
+ determined as follows (for platforms other than AIX and Windows):
+ </para>
+ <itemizedlist>
+ <listitem>
+ On system supporting <code>readlink</code>, suffix components of the
+ path of the file linked by <code>/etc/localtime</code>. The suffixes
+ are matched in the other of increasing length, starting from the final
+ component, until the match is found in the time zone database.
+ Any repeated slashes (<code>//</code>) are eliminated.
+ </listitem>
+ <listitem>
+ Names stored in the files <code>/etc/timezone</code> (Debian
+ derivatives) or <code>/var/db/zoneinfo</code> (FreeBSD) in that order.
+ </listitem>
+ <listitem>
+ Values for <code>TIMEZONE</code> and <code>ZONE</code> keys in
+ <code>/etc/sysconfig/clock</code>.
+ </listitem>
+ <listitem>
+ <code>UTC</code>.
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ For AIX, the value of <code>TZ</code> environment value is used, with
+ fallback to <code>UTC</code>.
+ </para>
+
+ <para>
+ On Windows <code>TimeZoneKeyName</code> is mapped to the IANA zone, using
+ internal mapping hard-coded in library, with fallback to <code>UTC</code>:
+ </para>
+ <itemizedlist>
+ <listitem>
+ If the returned <code>TimeZoneKeyName</code> is empty or DST is
disabled,
+ then a value based on <code>Bias</code> is returned:
<code>Etc/UTC</code>
+ for zero, <code>Etc/GMT+/-N</code> for value that is multiply of 60,
+ and empty string otherwise.
+ </listitem>
+ <listitem>
+ If the mapping contains a single entry for <code>TimeZoneKeyName</code>,
+ that name is used.
+ </listitem>
+ <listitem>
+ If <code>TimeZoneKeyName</code> corresponds to multiple IANA zones,
+ a 2-letter country code is used, retrieved by applying
<code>GetGeoInfoW</code>
+ on the result of <code>GetUserGeoID(GEOCLASS_NATION)</code>.
+ If determining the country code fails, or no entry exits for a given
code,
+ the first mapping entry (<code>001</code>) is returned.
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="zone.db.sources" xreflabel="data sources"><info><title>data
sources</title></info>
+ <para>
+ Depending on the build configuration (see
+ <code>--with-libstdcxx-zoneinfo=</code> documentation in
+ <xref linkend="manual.intro.setup.configure">Configure section</xref>).
+ the content of the time zone database is sourced from
+ <filename>tzdata.zi</filename> and <filename>leapseconds</filename> files
+ located in <emphasis>zoneinfo_dir</emphasis>, or from static information
+ embedded in the library.
+ </para>
+
+ <para>
+ By default, <emphasis>zoneinfo_dir</emphasis> is set to the
+ system-specific default directory (if a suitable dir is known for
target),
+ usually <code>/usr/share/zoneinfo</code>. If no such directory
+ exits, or it does not contain the required files in the correct format,
+ embedded static data is used as fallback.
+ </para>
+
+ <para>
+ In addition to <code>--with-libstdcxx-zoneinfo=</code> configure option
+ (used during GCC build), the path of <emphasis>zoneinfo_dir</emphasis>
+ can be overridden by the application by providing a definition of the
+ <code>__gnu_cxx::zoneinfo_dir_overrride()</code> function. The
+ returned path should be directory that contains <code>tzdata.zi</code>
+ and <code>leapseconds</code> files in the
+ <link xmlns:xlink="http://www.w3.org/1999/xlink";
+ xlink:href="https://man7.org/linux/man-pages/man8/zic.8.html#FILES";>
+ <code>zic</code> format</link>.
+ </para>
+
+ <para>
+ The embedded timezone information corresponds to the copy of the
+ IANA database at the time of the release, and its version can be queried
+ using <code>std::chrono::get_tzdb().version</code>.
+ </para>
+
+ <para>
+ The full time zone database can be disabled when GCC is configured,
+ in which case a minimal time zone database is provided. This minimal
+ database can be identified by <code>chrono::get_tzdb().version</code>
+ being set to <code>"ersatz"</code>. This database contains leapseconds
+ data, <code>Etc/UTC</code>, <code>Etc/GMT</code> zones, and their aliases
+ (<code>Etc/Zulu</code>, <code>Etc/UCT</code>, <code>Etc/Universal</code>,
+ <code>Etc/Greenwich</code>, <code>Etc/GMT0</code>,
<code>Etc/GMT+0</code>,
+ <code>Etc/GMT-0</code>). This information is sufficient to support
+ conversion between <code>utc_clock</code> and <code>sys_clock</code>,
+ as well as a <code>UTC</code> fallback for <code>current_zone</code>
+ (<xref linkend="zone.current">link</xref>).
+ </para>
+ </section>
+
+ <section xml:id="zone.db.iterator" xreflabel="tzdb_list::const_iterator
extends lifetime">
+ <info><title>tzdb_list::const_iterator extends lifetime</title></info>
+
+ <para>
+ The <code>std::chrono::reload_tzdb()</code> function may be used to load
+ updated content of the <code>tzdata.zi</code> and
<code>leapseconds</code>
+ files from <emphasis>zoneinfo_dir</emphasis> (if
+ <xref linkend="zone.db.sources">enabled</xref>). If the version is
different
+ (<code>std::chrono::remote_version() !=
std::chrono::get_tzdb().version</code>),
+ a new element is added at the front of the <code>tzdb_list</code>.
+ This new database is used for subsequent calls to
<code>current_zone</code>
+ and <code>locate_zone</code>.
+ </para>
+
+ <para>
+ The above process is thread-safe, and does not invalidate nor change any
+ pre-existing pointers to <code>time_zone</code> objects. However, for a
+ long-running application it may lead to accumulation of time zone data,
+ and thus increased memory usage. In most cases, this is acceptable even
+ for long-running applications, due to infrequent updates to the IANA
database,
+ and the reduced footprint of the libstdc++ implementation (see
+ <xref linkend="zone.db.zic">link</xref>).
+ </para>
+
+ <para>
+ If accumulating old <code>tzdb</code> databases is not acceptable
+ (e.g. due to memory constraints), entries
+ may be removed from <code>tzdb_list</code> using
<code>tzdb_list::erase_after</code>.
+ When using this function, you are responsible for ensuring that the
application
+ no longer is no longer using any <code>time_zone*</code> to a removed
database.
+ If you erase a <code>tzdb</code> while some part of the application is
still
+ using it (or one of its <code>time_zone</code> objects) you will create
+ a dangling pointer, leading to undefined behaviour.
+ To make <code>tzdb_list::erase_after</code> safer, libstdc++ provides an
+ <emphasis>extension</emphasis> that avoids creating dangling pointers.
+ The <code>tzdb_list</code> uses <code>shared_ptr<tzdb></code> to
+ refer to each entry in the list, and
<code>tzdb_list::const_iterator</code>
+ also uses a <code>shared_ptr<tzdb></code> to refer to its target.
+ This means that iterators into the list share ownership of the list
elements,
+ so that erasing an element from the list does not destroy it if there are
+ any iterators which share ownership of the element. The application can
+ use this to ensure that <code>tzdb</code> and <code>time_zone</code>
+ objects are not destroyed while they're still being used. The lifetime
+ of a <code>tzdb</code> that is still in use can be extended by holding
+ onto a <code>tzdb_list::const_iterator</code> that refers to it.
+ </para>
+ </section>
+
+</section>
+
+</chapter>
--
2.55.0
