From: Jonathan Wakely Date: Fri, 21 Nov 2025 14:33:29 +0000 (+0000) Subject: libstdc++: Update some old docs about predefined feature macros X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=01b8c6ffbd32ab222f14b3932e58425d7bd0970e;p=thirdparty%2Fgcc.git 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 --git a/libstdc++-v3/doc/html/faq.html b/libstdc++-v3/doc/html/faq.html index ba887ae2061..a0c4216f994 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.

4.3.

_XOPEN_SOURCE and _GNU_SOURCE are always defined? -

On Solaris, g++ (but not gcc) +

On GNU/Linux, g++ (but not gcc) always defines the preprocessor macro - _XOPEN_SOURCE. On GNU/Linux, the same happens - with _GNU_SOURCE. (This is not an exhaustive list; + _GNU_SOURCE. On Solaris, the same happens + with _XOPEN_SOURCE. (This is not an exhaustive list; other macros and other platforms are also affected.)

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. -

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 long long, + such as strtoll, are needed by libstdc++ but + were not part of the C90 standard. +

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. -

Note that it's not enough to #define 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. +

Note that it's not enough to #define 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. -

To see which symbols are defined, look for +

To see which macros are defined, look for CPLUSPLUS_CPP_SPEC 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 f61b0b12b80..08c1a1829f2 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.

The first file to create in this directory, should be called os_defines.h. This file contains basic macro definitions that are required to allow the C++ library to work with your C library. -

Several libstdc++ source files unconditionally define the macro -_POSIX_SOURCE. 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 #undef this -macro, or define other macros (like _LARGEFILE_SOURCE or -__EXTENSIONS__). 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 -CPLUSPLUS_CPP_SPEC macro in the GCC configuration file for your -target. It will not work to simply define these macros in -os_defines.h.

At this time, there are a few libstdc++-specific macros which may be defined:

_GLIBCXX_USE_C99_CHECK 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 92b81f2068c..1af41c2fbaf 100644 --- a/libstdc++-v3/doc/xml/faq.xml +++ b/libstdc++-v3/doc/xml/faq.xml @@ -551,31 +551,34 @@ _XOPEN_SOURCE and _GNU_SOURCE are always defined? + - On Solaris, g++ (but not gcc) + On GNU/Linux, g++ (but not gcc) always defines the preprocessor macro - _XOPEN_SOURCE. On GNU/Linux, the same happens - with _GNU_SOURCE. (This is not an exhaustive list; + _GNU_SOURCE. On Solaris, the same happens + with _XOPEN_SOURCE. (This is not an exhaustive list; other macros and other platforms are also affected.) 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 long long, + such as strtoll, are needed by libstdc++ but + were not part of the C90 standard. - More to the point, the C++ standard requires behavior which is only - available on certain platforms after certain symbols are defined. + 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. - Note that it's not enough to #define 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 + Note that it's not enough to #define 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. - To see which symbols are defined, look for + To see which macros are defined, look for CPLUSPLUS_CPP_SPEC 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 5b3be2d1a84..699c21af6a5 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. - Several libstdc++ source files unconditionally define the macro -_POSIX_SOURCE. 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 #undef this -macro, or define other macros (like _LARGEFILE_SOURCE or -__EXTENSIONS__). 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 -CPLUSPLUS_CPP_SPEC macro in the GCC configuration file for your -target. It will not work to simply define these macros in -os_defines.h. - - At this time, there are a few libstdc++-specific macros which may be defined: