ChapterÂ 3.Â Using

In C++11 mode you can call s.shrink_to_fit() to achieve the same effect as s.reserve(s.size()). diff --git a/libstdc++-v3/doc/html/manual/using.html b/libstdc++-v3/doc/html/manual/using.html index dff5192f5f2..cc5c65079b0 100644 --- a/libstdc++-v3/doc/html/manual/using.html +++ b/libstdc++-v3/doc/html/manual/using.html @@ -2,14 +2,19 @@ ChapterÂ 3.Â Using

ChapterÂ 3.Â Using
PrevÂ	PartÂ I.Â Introduction -	Â Next

ChapterÂ 3.Â Using

Command Options

+Â Next

ChapterÂ 3.Â Using

Command Options

The set of features available in the GNU C++ library is shaped by several GCC Command Options. Options that impact libstdc++ are enumerated and detailed in the table below.

- By default, g++ is equivalent to g++ -std=gnu++98. The standard library also defaults to this dialect. -

TableÂ 3.1.Â C++ Command Options

Option Flags Description

-std=c++98 Use the 1998 ISO C++ standard plus amendments.

-std=gnu++98 As directly above, with GNU extensions.

-std=c++11 Use the 2011 ISO C++ standard.

-std=gnu++11 As directly above, with GNU extensions.

-fexceptions See exception-free dialect

-frtti As above, but RTTI-free dialect.

-pthread or -pthreads

For ISO C++11 + The standard library conforms to the dialect of C++ specified by the + -std option passed to the compiler. + By default, g++ is equivalent to + g++ -std=gnu++98. +

TableÂ 3.1.Â C++ Command Options

Option Flags Description

-std=c++98 or -std=c++03 + Use the 1998 ISO C++ standard plus amendments.

-std=gnu++98 or -std=gnu++03 + As directly above, with GNU extensions.

-std=c++11 Use the 2011 ISO C++ standard.

-std=gnu++11 As directly above, with GNU extensions.

-std=c++14 Use the 2014 ISO C++ standard.

-std=gnu++14 As directly above, with GNU extensions.

-fexceptions See exception-free dialect

-frtti As above, but RTTI-free dialect.

-pthread or -pthreads

For ISO C++11 <thread>, <future>, <mutex>, diff --git a/libstdc++-v3/doc/html/manual/using_dual_abi.html b/libstdc++-v3/doc/html/manual/using_dual_abi.html new file mode 100644 index 00000000000..24f4f7a7778 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/using_dual_abi.html @@ -0,0 +1,65 @@ + +Dual ABI

Dual ABI
PrevÂ	ChapterÂ 3.Â Using	Â Next

Dual ABI

In the GCC 5.1 release libstdc++ introduced a new library ABI that + includes new implementations of std::string and + std::list. These changes were necessary to conform + to the 2011 C++ standard which forbids Copy-On-Write strings and requires + lists to keep track of their size. +

In order to maintain backwards compatibility for existing code linked + to libstdc++ the library's soname has not changed and the old + implementations are still supported in parallel with the new ones. + This is achieved by defining the new implementations in an inline namespace + so they have different names for linkage purposes, e.g. the new version of + std::list<int> is actually defined as + std::__cxx11::list<int>. Because the symbols + for the new implementations have different names the definitions for both + versions can be present in the same library. +

The _GLIBCXX_USE_CXX11_ABI macro (see +Macros) controls whether + the declarations in the library headers use the old or new ABI. + So the decision of which ABI to use can be made separately for each + source file being compiled. + Using the default configuration options for GCC the default value + of the macro is 1 which causes the new ABI to be active, + so to use the old ABI you must explicitly define the macro to + 0 before including any library headers. + (Be aware that some GNU/Linux distributions configure GCC 5 differently so + that the default value of the macro is 0 and users must + define it to 1 to enable the new ABI.) +

Although the changes were made for C++11 conformance, the choice of ABI + to use is independent of the -std option used to compile + your code, i.e. for a given GCC build the default value of the + _GLIBCXX_USE_CXX11_ABI macro is the same for all dialects. + This ensures that the -std does not change the ABI, so + that it is straightforward to link C++03 and C++11 code together. +

Because std::string is used extensively + throughout the library a number of other types are also defined twice, + including the stringstream classes and several facets used by + std::locale. The standard facets which are always + installed in a locale may be present twice, with both ABIs, to ensure that + code like + std::use_facet<std::time_get<char>>(locale); + will work correctly for both std::time_get and + std::__cxx11::time_get (even if a user-defined + facet that derives from one or other version of + time_get is installed in the locale). +

Although the standard exception types defined in + <stdexcept> use strings, they + are not defined twice, so that a std::out_of_range + exception thrown in one file can always be caught by a suitable handler in + another file, even if the two files are compiled with different ABIs. +

Troubleshooting

If you get linker errors about undefined references to symbols + that involve types in the std::__cxx11 namespace or the tag + [abi:cxx11] then it probably indicates that you are trying to + link together object files that were compiled with different values for the + _GLIBCXX_USE_CXX11_ABI macro. This commonly happens when + linking to a third-party library that was compiled with an older version + of GCC. If the third-party library cannot be rebuilt with the new ABI then + you will need to recompile your code with the old ABI. +

Not all uses of the new ABI will cause changes in symbol names, for + example a class with a std::string member variable + will have the same mangled name whether compiled with the old or new ABI. + In order to detect such problems the new types and functions are + annotated with the abi_tag attribute, allowing the + compiler to warn about potential ABI incompatibilities in code using them. + Those warnings can be enabled with the -Wabi-tag option. +

PrevÂ	Up	Â Next
MacrosÂ	Home	Â Namespaces

\ No newline at end of file diff --git a/libstdc++-v3/doc/html/manual/using_exceptions.html b/libstdc++-v3/doc/html/manual/using_exceptions.html index 00e9d38f315..cb7c9991304 100644 --- a/libstdc++-v3/doc/html/manual/using_exceptions.html +++ b/libstdc++-v3/doc/html/manual/using_exceptions.html @@ -265,7 +265,7 @@ is called. } catch(...) { this->_M_setstate(ios_base::badbit); } -

Bibliography

+ .

Error and Exception Handling . David Abrahams . Boost - .

+ .

Exception-Safety in Generic Components . David Abrahams. Boost - .

+ .

Standard Library Exception Policy . Matt Austern. WG21 N1077 - .

+ .

ia64 c++ abi exception handling . Richard Henderson. GNU - .

+ .

Appendix E: Standard-Library Exception Safety - . Bjarne Stroustrup.

+ . Bjarne Stroustrup.

Exceptional C++ . Exception-Safety Issues and Techniques - . Herb Sutter.

+ . Herb Sutter.

GCC Bug 25191: exception_defines.h #defines try/catch diff --git a/libstdc++-v3/doc/html/manual/using_macros.html b/libstdc++-v3/doc/html/manual/using_macros.html index bac3f363080..4bb99b1f5d2 100644 --- a/libstdc++-v3/doc/html/manual/using_macros.html +++ b/libstdc++-v3/doc/html/manual/using_macros.html @@ -1,5 +1,5 @@ -Macros
Macros
PrevÂ ChapterÂ 3.Â Using Â Next
Macros
+Macros
Macros
PrevÂ ChapterÂ 3.Â Using Â Next
Macros
All library macros begin with _GLIBCXX_.
Furthermore, all pre-processor macros, switches, and @@ -50,6 +50,17 @@ be useful in updating old C++ code which no longer meet the requirements of the language, or for checking current code against new language standards. +
_GLIBCXX_USE_CXX11_ABI
+ Defined to the value 1 by default. + Configurable via --disable-libstdcxx-dual-abi + and/or --with-default-libstdcxx-abi. + ABI-changing. + When defined to a non-zero value the library headers will use the + new C++11-conforming ABI introduced in GCC 5, rather than the older + ABI introduced in GCC 3.4. This changes the definition of several + class templates, including std:string, + std::list and some locale facets. + For more details see Dual ABI.
_GLIBCXX_CONCEPT_CHECKS
Undefined by default. Configurable via --enable-concept-checks. When defined, performs @@ -71,4 +82,4 @@
_GLIBCXX_PROFILE
Undefined by default. When defined, compiles user code using the profile mode. -
PrevÂ Up Â Next
HeadersÂ Home Â Namespaces
\ No newline at end of file +

PrevÂ	Up	Â Next
HeadersÂ	Home	Â Dual ABI

\ No newline at end of file diff --git a/libstdc++-v3/doc/html/manual/using_namespaces.html b/libstdc++-v3/doc/html/manual/using_namespaces.html index 224c7d6bf57..0fe9ce33399 100644 --- a/libstdc++-v3/doc/html/manual/using_namespaces.html +++ b/libstdc++-v3/doc/html/manual/using_namespaces.html @@ -1,16 +1,19 @@ -Namespaces
Namespaces
PrevÂ ChapterÂ 3.Â Using Â Next
Namespaces
Available Namespaces
There are three main namespaces. +Namespaces
Namespaces
PrevÂ ChapterÂ 3.Â Using Â Next
Namespaces
Available Namespaces
There are three main namespaces.
std
The ISO C++ standards specify that "all library entities are defined within namespace std." This includes namespaces nested -within namespace std, such as namespace -std::tr1. +within namespace std, such as namespace +std::chrono.
abi
Specified by the C++ ABI. This ABI specifies a number of type and function APIs supplemental to those required by the ISO C++ Standard, but necessary for interoperability.
__gnu_
Indicating one of several GNU extensions. Choices include __gnu_cxx, __gnu_debug, __gnu_parallel, and __gnu_pbds. -
A complete list of implementation namespaces (including namespace contents) is available in the generated source documentation. +
The library uses a number of inline namespaces as implementation +details that are not intended for users to refer to directly, these include +std::__detail, std::__cxx11 and std::_V2. +
A complete list of implementation namespaces (including namespace contents) is available in the generated source documentation.
namespace std
One standard requirement is that the library components are defined in namespace std::. Thus, in order to use these types or @@ -57,4 +60,4 @@ namespace gtk std::string; (depending on whether the system has libstdc++ in std:: or not). (ideas from Llewelly and Karl Nelson) -
PrevÂ Up Â Next
MacrosÂ Home Â Linking
\ No newline at end of file +
PrevÂ Up Â Next
Dual ABIÂ Home Â Linking
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/configure.xml b/libstdc++-v3/doc/xml/manual/configure.xml index a6e0c212cff..56d071ec469 100644 --- a/libstdc++-v3/doc/xml/manual/configure.xml +++ b/libstdc++-v3/doc/xml/manual/configure.xml @@ -385,18 +385,22 @@ --disable-libstdcxx-dual-abi - Disable support for the new, C++11-conforming std::string - implementation. This option changes the library ABI. + Disable support for the new, C++11-conforming implementations of + std::string, std::list etc. so that the + library only provides definitions of types using the old ABI + (see ). + This option changes the library ABI. ---with-default-libstdcxx-abi +--with-default-libstdcxx-abi=OPTION - By default, the new std::string implementation will be - declared and a macro must be defined to declare the old implementation - instead. That default can be reversed by configuring the library with - --with-default-libstdcxx-abi=c++98. + Set the default value for the _GLIBCXX_USE_CXX11_ABI + macro (see ). + The default is which sets the macro to + 1, + use to set it to 0. This option does not change the library ABI. diff --git a/libstdc++-v3/doc/xml/manual/strings.xml b/libstdc++-v3/doc/xml/manual/strings.xml index 6a94fa22cb4..101f8cd3331 100644 --- a/libstdc++-v3/doc/xml/manual/strings.xml +++ b/libstdc++-v3/doc/xml/manual/strings.xml @@ -353,7 +353,7 @@ stringtok(Container &container, string const &in, a vector's memory usage (see this FAQ entry) but the regular copy constructor cannot be used - because libstdc++'s string is Copy-On-Write. + because libstdc++'s string is Copy-On-Write in GCC 3. In C++11 mode you can call s.shrink_to_fit() to achieve the same effect as diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml index 0ce440703dd..8b4af1a5ed2 100644 --- a/libstdc++-v3/doc/xml/manual/using.xml +++ b/libstdc++-v3/doc/xml/manual/using.xml @@ -875,6 +875,22 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe + _GLIBCXX_USE_CXX11_ABI + + + Defined to the value 1 by default. + Configurable via --disable-libstdcxx-dual-abi + and/or --with-default-libstdcxx-abi. + ABI-changing. + When defined to a non-zero value the library headers will use the + new C++11-conforming ABI introduced in GCC 5, rather than the older + ABI introduced in GCC 3.4. This changes the definition of several + class templates, including std:string, + std::list and some locale facets. + For more details see . + + + _GLIBCXX_CONCEPT_CHECKS @@ -922,6 +938,94 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe +
+ Dual ABI + + + In the GCC 5.1 release libstdc++ introduced a new library ABI that + includes new implementations of std::string and + std::list. These changes were necessary to conform + to the 2011 C++ standard which forbids Copy-On-Write strings and requires + lists to keep track of their size. + + + In order to maintain backwards compatibility for existing code linked + to libstdc++ the library's soname has not changed and the old + implementations are still supported in parallel with the new ones. + This is achieved by defining the new implementations in an inline namespace + so they have different names for linkage purposes, e.g. the new version of + std::list<int> is actually defined as + std::__cxx11::list<int>. Because the symbols + for the new implementations have different names the definitions for both + versions can be present in the same library. + + + The _GLIBCXX_USE_CXX11_ABI macro (see +) controls whether + the declarations in the library headers use the old or new ABI. + So the decision of which ABI to use can be made separately for each + source file being compiled. + Using the default configuration options for GCC the default value + of the macro is 1 which causes the new ABI to be active, + so to use the old ABI you must explicitly define the macro to + 0 before including any library headers. + (Be aware that some GNU/Linux distributions configure GCC 5 differently so + that the default value of the macro is 0 and users must + define it to 1 to enable the new ABI.) + + + Although the changes were made for C++11 conformance, the choice of ABI + to use is independent of the option used to compile + your code, i.e. for a given GCC build the default value of the + _GLIBCXX_USE_CXX11_ABI macro is the same for all dialects. + This ensures that the does not change the ABI, so + that it is straightforward to link C++03 and C++11 code together. + + + Because std::string is used extensively + throughout the library a number of other types are also defined twice, + including the stringstream classes and several facets used by + std::locale. The standard facets which are always + installed in a locale may be present twice, with both ABIs, to ensure that + code like + std::use_facet<std::time_get<char>>(locale); + will work correctly for both std::time_get and + std::__cxx11::time_get (even if a user-defined + facet that derives from one or other version of + time_get is installed in the locale). + + + Although the standard exception types defined in + <stdexcept> use strings, they + are not defined twice, so that a std::out_of_range + exception thrown in one file can always be caught by a suitable handler in + another file, even if the two files are compiled with different ABIs. + + +
Troubleshooting + + If you get linker errors about undefined references to symbols + that involve types in the std::__cxx11 namespace or the tag + [abi:cxx11] then it probably indicates that you are trying to + link together object files that were compiled with different values for the + _GLIBCXX_USE_CXX11_ABI macro. This commonly happens when + linking to a third-party library that was compiled with an older version + of GCC. If the third-party library cannot be rebuilt with the new ABI then + you will need to recompile your code with the old ABI. + + + Not all uses of the new ABI will cause changes in symbol names, for + example a class with a std::string member variable + will have the same mangled name whether compiled with the old or new ABI. + In order to detect such problems the new types and functions are + annotated with the abi_tag attribute, allowing the + compiler to warn about potential ABI incompatibilities in code using them. + Those warnings can be enabled with the option. + + +
+
+
Namespaces @@ -956,6 +1060,11 @@ and __gnu_pbds. + The library uses a number of inline namespaces as implementation +details that are not intended for users to refer to directly, these include +std::__detail, std::__cxx11 and std::_V2. + + A complete list of implementation namespaces (including namespace contents) is available in the generated source documentation.

PrevÂ	Up	Â Next
The GNU C++ Library ManualÂ	Home	Â ChapterÂ 1.Â Status

PartÂ I.Â Introduction -

ChapterÂ 3.Â Using

Command Options

ChapterÂ 3.Â Using

Command Options

Dual ABI

Troubleshooting

Bibliography

Bibliography

Macros

Macros

Namespaces

Available Namespaces

Namespaces

Available Namespaces

namespace std