https://gcc.gnu.org/g:01b8c6ffbd32ab222f14b3932e58425d7bd0970e
commit r16-5495-g01b8c6ffbd32ab222f14b3932e58425d7bd0970e Author: Jonathan Wakely <[email protected]> Date: Fri Nov 21 14:33:29 2025 +0000 libstdc++: Update some old docs about predefined feature macros libstdc++-v3/ChangeLog: * doc/xml/faq.xml: Refresh information on _GNU_SOURCE and _XOPEN_SOURCE being predefined. * doc/xml/manual/internals.xml: Remove outdated paragraph about _POSIX_SOURCE in libstdc++ source files. * doc/html/*: Regenerate. Diff: --- libstdc++-v3/doc/html/faq.html | 32 +++++++++++++++------------- libstdc++-v3/doc/html/manual/internals.html | 14 ------------ libstdc++-v3/doc/xml/faq.xml | 33 ++++++++++++++++------------- libstdc++-v3/doc/xml/manual/internals.xml | 16 -------------- 4 files changed, 35 insertions(+), 60 deletions(-) diff --git a/libstdc++-v3/doc/html/faq.html b/libstdc++-v3/doc/html/faq.html index ba887ae2061a..a0c4216f9943 100644 --- a/libstdc++-v3/doc/html/faq.html +++ b/libstdc++-v3/doc/html/faq.html @@ -432,26 +432,28 @@ This has been fixed for libstdc++ releases greater than 3.0.3. </p></td></tr><tr class="question"><td align="left" valign="top"><a id="faq.predefined"></a><a id="q-predefined"></a><p><strong>4.3.</strong></p></td><td align="left" valign="top"><p> <code class="constant">_XOPEN_SOURCE</code> and <code class="constant">_GNU_SOURCE</code> are always defined? - </p></td></tr><tr class="answer"><td align="left" valign="top"><a id="a-predefined"></a></td><td align="left" valign="top"><p>On Solaris, <span class="command"><strong>g++</strong></span> (but not <span class="command"><strong>gcc</strong></span>) + </p></td></tr><tr class="answer"><td align="left" valign="top"><a id="a-predefined"></a></td><td align="left" valign="top"><p>On GNU/Linux, <span class="command"><strong>g++</strong></span> (but not <span class="command"><strong>gcc</strong></span>) always defines the preprocessor macro - <code class="constant">_XOPEN_SOURCE</code>. On GNU/Linux, the same happens - with <code class="constant">_GNU_SOURCE</code>. (This is not an exhaustive list; + <code class="constant">_GNU_SOURCE</code>. On Solaris, the same happens + with <code class="constant">_XOPEN_SOURCE</code>. (This is not an exhaustive list; other macros and other platforms are also affected.) </p><p>These macros are typically used in C library headers, guarding new - versions of functions from their older versions. The C++98 standard - library includes the C standard library, but it requires the C90 - version, which for backwards-compatibility reasons is often not the - default for many vendors. - </p><p>More to the point, the C++ standard requires behavior which is only - available on certain platforms after certain symbols are defined. + versions of functions from their older versions. Historically, + libstdc++ needed these macros to ensure that the headers provided by + the C library declared all the functions that libstdc++ relies on. + For example, functions for working with <code class="code">long long</code>, + such as <code class="function">strtoll</code>, are needed by libstdc++ but + were not part of the C90 standard. + </p><p>Additionally the C++ standard requires behavior which is only + available on certain platforms after certain macros are defined. Usually the issue involves I/O-related typedefs. In order to - ensure correctness, the compiler simply predefines those symbols. - </p><p>Note that it's not enough to <code class="literal">#define</code> them only when the library is - being built (during installation). Since we don't have an 'export' - keyword, much of the library exists as headers, which means that - the symbols must also be defined as your programs are parsed and + ensure correctness, the compiler simply predefines those macros. + </p><p>Note that it's not enough to <code class="literal">#define</code> them + only when the library is being built (during installation). + Much of the library exists as headers, which means that + the macros must also be defined as your programs are parsed and compiled. - </p><p>To see which symbols are defined, look for + </p><p>To see which macros are defined, look for <code class="varname">CPLUSPLUS_CPP_SPEC</code> in the gcc config headers for your target (and try changing them to see what happens when building complicated code). You can also run diff --git a/libstdc++-v3/doc/html/manual/internals.html b/libstdc++-v3/doc/html/manual/internals.html index f61b0b12b803..08c1a1829f2b 100644 --- a/libstdc++-v3/doc/html/manual/internals.html +++ b/libstdc++-v3/doc/html/manual/internals.html @@ -41,20 +41,6 @@ OS portion of the triplet (the default), then nothing needs to be changed. </p><p>The first file to create in this directory, should be called <code class="code">os_defines.h</code>. This file contains basic macro definitions that are required to allow the C++ library to work with your C library. - </p><p>Several libstdc++ source files unconditionally define the macro -<code class="code">_POSIX_SOURCE</code>. On many systems, defining this macro causes -large portions of the C library header files to be eliminated -at preprocessing time. Therefore, you may have to <code class="code">#undef</code> this -macro, or define other macros (like <code class="code">_LARGEFILE_SOURCE</code> or -<code class="code">__EXTENSIONS__</code>). You won't know what macros to define or -undefine at this point; you'll have to try compiling the library and -seeing what goes wrong. If you see errors about calling functions -that have not been declared, look in your C library headers to see if -the functions are declared there, and then figure out what macros you -need to define. You will need to add them to the -<code class="code">CPLUSPLUS_CPP_SPEC</code> macro in the GCC configuration file for your -target. It will not work to simply define these macros in -<code class="code">os_defines.h</code>. </p><p>At this time, there are a few libstdc++-specific macros which may be defined: </p><p><code class="code">_GLIBCXX_USE_C99_CHECK</code> may be defined to 1 to check C99 diff --git a/libstdc++-v3/doc/xml/faq.xml b/libstdc++-v3/doc/xml/faq.xml index 92b81f2068c4..1af41c2fbaf0 100644 --- a/libstdc++-v3/doc/xml/faq.xml +++ b/libstdc++-v3/doc/xml/faq.xml @@ -551,31 +551,34 @@ <constant>_XOPEN_SOURCE</constant> and <constant>_GNU_SOURCE</constant> are always defined? </para> </question> + <answer xml:id="a-predefined"> - <para>On Solaris, <command>g++</command> (but not <command>gcc</command>) + <para>On GNU/Linux, <command>g++</command> (but not <command>gcc</command>) always defines the preprocessor macro - <constant>_XOPEN_SOURCE</constant>. On GNU/Linux, the same happens - with <constant>_GNU_SOURCE</constant>. (This is not an exhaustive list; + <constant>_GNU_SOURCE</constant>. On Solaris, the same happens + with <constant>_XOPEN_SOURCE</constant>. (This is not an exhaustive list; other macros and other platforms are also affected.) </para> <para>These macros are typically used in C library headers, guarding new - versions of functions from their older versions. The C++98 standard - library includes the C standard library, but it requires the C90 - version, which for backwards-compatibility reasons is often not the - default for many vendors. + versions of functions from their older versions. Historically, + libstdc++ needed these macros to ensure that the headers provided by + the C library declared all the functions that libstdc++ relies on. + For example, functions for working with <code>long long</code>, + such as <function>strtoll</function>, are needed by libstdc++ but + were not part of the C90 standard. </para> - <para>More to the point, the C++ standard requires behavior which is only - available on certain platforms after certain symbols are defined. + <para>Additionally the C++ standard requires behavior which is only + available on certain platforms after certain macros are defined. Usually the issue involves I/O-related typedefs. In order to - ensure correctness, the compiler simply predefines those symbols. + ensure correctness, the compiler simply predefines those macros. </para> - <para>Note that it's not enough to <literal>#define</literal> them only when the library is - being built (during installation). Since we don't have an 'export' - keyword, much of the library exists as headers, which means that - the symbols must also be defined as your programs are parsed and + <para>Note that it's not enough to <literal>#define</literal> them + only when the library is being built (during installation). + Much of the library exists as headers, which means that + the macros must also be defined as your programs are parsed and compiled. </para> - <para>To see which symbols are defined, look for + <para>To see which macros are defined, look for <varname>CPLUSPLUS_CPP_SPEC</varname> in the gcc config headers for your target (and try changing them to see what happens when building complicated code). You can also run diff --git a/libstdc++-v3/doc/xml/manual/internals.xml b/libstdc++-v3/doc/xml/manual/internals.xml index 5b3be2d1a846..699c21af6a5a 100644 --- a/libstdc++-v3/doc/xml/manual/internals.xml +++ b/libstdc++-v3/doc/xml/manual/internals.xml @@ -73,22 +73,6 @@ OS portion of the triplet (the default), then nothing needs to be changed. that are required to allow the C++ library to work with your C library. </para> - <para>Several libstdc++ source files unconditionally define the macro -<code>_POSIX_SOURCE</code>. On many systems, defining this macro causes -large portions of the C library header files to be eliminated -at preprocessing time. Therefore, you may have to <code>#undef</code> this -macro, or define other macros (like <code>_LARGEFILE_SOURCE</code> or -<code>__EXTENSIONS__</code>). You won't know what macros to define or -undefine at this point; you'll have to try compiling the library and -seeing what goes wrong. If you see errors about calling functions -that have not been declared, look in your C library headers to see if -the functions are declared there, and then figure out what macros you -need to define. You will need to add them to the -<code>CPLUSPLUS_CPP_SPEC</code> macro in the GCC configuration file for your -target. It will not work to simply define these macros in -<code>os_defines.h</code>. - </para> - <para>At this time, there are a few libstdc++-specific macros which may be defined: </para>
