From a138d52a9b33aa09ed0a535c38f54e56dfb37bd1 Mon Sep 17 00:00:00 2001
From: Jonathan Wakely <jwakely@redhat.com>
Date: Tue, 28 Mar 2017 13:43:06 +0100
Subject: [PATCH] Add _GLIBCXX_RELEASE macro to "Using" section of manual
* doc/xml/manual/abi.xml: Add xml:id anchor.
* doc/xml/manual/using.xml (manual.intro.using.macros): Document
_GLIBCXX_RELEASE. Link to new anchor for __GLIBCXX__ notes.
(concurrency.io.structure): Add markup.
* doc/html/*: Regenerate.
From-SVN: r246532
---
libstdc++-v3/ChangeLog | 6 +++
libstdc++-v3/doc/html/manual/abi.html | 2 +-
.../doc/html/manual/using_concurrency.html | 9 ++--
.../doc/html/manual/using_macros.html | 25 +++++++----
libstdc++-v3/doc/xml/manual/abi.xml | 2 +-
libstdc++-v3/doc/xml/manual/using.xml | 42 +++++++++++++------
6 files changed, 61 insertions(+), 25 deletions(-)
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 4a7869a1f6f3..cc7c3fb93de5 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,5 +1,11 @@
2017-03-28 Jonathan Wakely <jwakely@redhat.com>
+ * doc/xml/manual/abi.xml: Add xml:id anchor.
+ * doc/xml/manual/using.xml (manual.intro.using.macros): Document
+ _GLIBCXX_RELEASE. Link to new anchor for __GLIBCXX__ notes.
+ (concurrency.io.structure): Add markup.
+ * doc/html/*: Regenerate.
+
PR libstdc++/80229
* include/bits/shared_ptr_base.h
(__shared_ptr::_M_enable_shared_from_this_with): Change parameters to
diff --git a/libstdc++-v3/doc/html/manual/abi.html b/libstdc++-v3/doc/html/manual/abi.html
index 3e619e8ec798..47425aabc229 100644
--- a/libstdc++-v3/doc/html/manual/abi.html
+++ b/libstdc++-v3/doc/html/manual/abi.html
@@ -145,7 +145,7 @@ compatible.
<code class="code">-fabi-version</code>.
</p><p>
It is versioned as follows:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0: (Error, not versioned) </p></li><li class="listitem"><p>GCC 3.1: (Error, not versioned) </p></li><li class="listitem"><p>GCC 3.2: <code class="code">-fabi-version=1</code></p></li><li class="listitem"><p>GCC 3.3: <code class="code">-fabi-version=1</code></p></li><li class="listitem"><p>GCC 3.4, GCC 4.x: <code class="code">-fabi-version=2</code> <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li class="listitem"><p>GCC 5 and higher: <code class="code">-fabi-version=0</code> <span class="emphasis"><em>(See GCC manual for meaning)</em></span></p></li></ul></div><p></p></li><li class="listitem"><p>Incremental bumping of a library pre-defined macro. For releases
+ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0: (Error, not versioned) </p></li><li class="listitem"><p>GCC 3.1: (Error, not versioned) </p></li><li class="listitem"><p>GCC 3.2: <code class="code">-fabi-version=1</code></p></li><li class="listitem"><p>GCC 3.3: <code class="code">-fabi-version=1</code></p></li><li class="listitem"><p>GCC 3.4, GCC 4.x: <code class="code">-fabi-version=2</code> <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li class="listitem"><p>GCC 5 and higher: <code class="code">-fabi-version=0</code> <span class="emphasis"><em>(See GCC manual for meaning)</em></span></p></li></ul></div><p></p></li><li class="listitem"><p><a id="abi.versioning.__GLIBCXX__"></a>Incremental bumping of a library pre-defined macro. For releases
before 3.4.0, the macro is <span class="symbol">__GLIBCPP__</span>. For later
releases, it's <span class="symbol">__GLIBCXX__</span>. (The libstdc++ project
generously changed from CPP to CXX throughout its source to allow the
diff --git a/libstdc++-v3/doc/html/manual/using_concurrency.html b/libstdc++-v3/doc/html/manual/using_concurrency.html
index b404027e7e25..2b8d951ce4de 100644
--- a/libstdc++-v3/doc/html/manual/using_concurrency.html
+++ b/libstdc++-v3/doc/html/manual/using_concurrency.html
@@ -180,10 +180,11 @@ gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
implementations of the C library with varying tradeoffs of threadsafety
and efficiency. You, the programmer, are always required to take care
with multiple threads.
- </p><p>(As an example, the POSIX standard requires that C stdio FILE*
- operations are atomic. POSIX-conforming C libraries (e.g, on Solaris
- and GNU/Linux) have an internal mutex to serialize operations on
- FILE*s. However, you still need to not do stupid things like calling
+ </p><p>(As an example, the POSIX standard requires that C stdio
+ <code class="code">FILE*</code> operations are atomic. POSIX-conforming C libraries
+ (e.g, on Solaris and GNU/Linux) have an internal mutex to serialize
+ operations on <code class="code">FILE*</code>s.
+ However, you still need to not do stupid things like calling
<code class="code">fclose(fs)</code> in one thread followed by an access of
<code class="code">fs</code> in another.)
</p><p>So, if your platform's C library is threadsafe, then your
diff --git a/libstdc++-v3/doc/html/manual/using_macros.html b/libstdc++-v3/doc/html/manual/using_macros.html
index ea146f1d582f..f5a8a223a8b4 100644
--- a/libstdc++-v3/doc/html/manual/using_macros.html
+++ b/libstdc++-v3/doc/html/manual/using_macros.html
@@ -17,13 +17,24 @@
features, or provide versioning information for the API. Only
those macros listed below are offered for consideration by the
general public.
- </p><p>Below is the macro which users may check for library version
- information. </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="code">__GLIBCXX__</code></span></dt><dd><p>The current version of
- libstdc++ in compressed ISO date format, as an unsigned
- long. For details on the value of this particular macro for a
- particular release, please consult the <a class="link" href="abi.html" title="ABI Policy and Guidelines">
- ABI Policy and Guidelines</a> appendix.
- </p></dd></dl></div><p>Below are the macros which users may change with #define/#undef or
+ </p><p>Below are the macros which users may check for library version
+ information. </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="code">_GLIBCXX_RELEASE</code></span></dt><dd><p>The major release number for libstdc++. This macro is defined
+ to the GCC major version that the libstdc++ headers belong to,
+ as an integer constant.
+ When compiling with GCC it has the same value as GCC's pre-defined
+ macro <span class="symbol">__GNUC__</span>.
+ This macro can be used when libstdc++ is used with a non-GNU
+ compiler where <span class="symbol">__GNUC__</span> is not defined, or has a
+ different value that doesn't correspond to the libstdc++ version.
+ This macro first appeared in the GCC 7.1 release and is not defined
+ for GCC 6.x or older releases.
+ </p></dd><dt><span class="term"><code class="code">__GLIBCXX__</code></span></dt><dd><p>The revision date of the libstdc++ source code,
+ in compressed ISO date format, as an unsigned
+ long. For notes about using this macro and details on the value of
+ this macro for a particular release, please consult the
+ <a class="link" href="abi.html#abi.versioning.__GLIBCXX__">ABI History</a>
+ appendix.
+ </p></dd></dl></div><p>Below are the macros which users may change with #define/#undef or
with -D/-U compiler flags. The default state of the symbol is
listed.</p><p><span class="quote">“<span class="quote">Configurable</span>â€</span> (or <span class="quote">“<span class="quote">Not configurable</span>â€</span>) means
that the symbol is initially chosen (or not) based on
diff --git a/libstdc++-v3/doc/xml/manual/abi.xml b/libstdc++-v3/doc/xml/manual/abi.xml
index 3ef57d57288f..e79bf8cf8b17 100644
--- a/libstdc++-v3/doc/xml/manual/abi.xml
+++ b/libstdc++-v3/doc/xml/manual/abi.xml
@@ -383,7 +383,7 @@ compatible.
<para/>
</listitem>
- <listitem>
+ <listitem xml:id="abi.versioning.__GLIBCXX__">
<para>Incremental bumping of a library pre-defined macro. For releases
before 3.4.0, the macro is <symbol>__GLIBCPP__</symbol>. For later
releases, it's <symbol>__GLIBCXX__</symbol>. (The libstdc++ project
diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml
index 3057a937a340..5c0e1b9f8c10 100644
--- a/libstdc++-v3/doc/xml/manual/using.xml
+++ b/libstdc++-v3/doc/xml/manual/using.xml
@@ -829,20 +829,37 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
general public.
</para>
- <para>Below is the macro which users may check for library version
+ <para>Below are the macros which users may check for library version
information. </para>
<variablelist>
+ <varlistentry>
+ <term><code>_GLIBCXX_RELEASE</code></term>
+ <listitem>
+ <para>The major release number for libstdc++. This macro is defined
+ to the GCC major version that the libstdc++ headers belong to,
+ as an integer constant.
+ When compiling with GCC it has the same value as GCC's pre-defined
+ macro <symbol>__GNUC__</symbol>.
+ This macro can be used when libstdc++ is used with a non-GNU
+ compiler where <symbol>__GNUC__</symbol> is not defined, or has a
+ different value that doesn't correspond to the libstdc++ version.
+ This macro first appeared in the GCC 7.1 release and is not defined
+ for GCC 6.x or older releases.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term><code>__GLIBCXX__</code></term>
<listitem>
- <para>The current version of
- libstdc++ in compressed ISO date format, as an unsigned
- long. For details on the value of this particular macro for a
- particular release, please consult the <link linkend="appendix.porting.abi">
- ABI Policy and Guidelines</link> appendix.
- </para>
- </listitem>
+ <para>The revision date of the libstdc++ source code,
+ in compressed ISO date format, as an unsigned
+ long. For notes about using this macro and details on the value of
+ this macro for a particular release, please consult the
+ <link linkend="abi.versioning.__GLIBCXX__">ABI History</link>
+ appendix.
+ </para>
+ </listitem>
</varlistentry>
</variablelist>
@@ -1669,10 +1686,11 @@ gcc version 4.1.2 20070925 (Red Hat 4.1.2-33)
and efficiency. You, the programmer, are always required to take care
with multiple threads.
</para>
- <para>(As an example, the POSIX standard requires that C stdio FILE*
- operations are atomic. POSIX-conforming C libraries (e.g, on Solaris
- and GNU/Linux) have an internal mutex to serialize operations on
- FILE*s. However, you still need to not do stupid things like calling
+ <para>(As an example, the POSIX standard requires that C stdio
+ <code>FILE*</code> operations are atomic. POSIX-conforming C libraries
+ (e.g, on Solaris and GNU/Linux) have an internal mutex to serialize
+ operations on <code>FILE*</code>s.
+ However, you still need to not do stupid things like calling
<code>fclose(fs)</code> in one thread followed by an access of
<code>fs</code> in another.)
</para>
--
GitLab