From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- libstdc++-v3/doc/xml/manual/support.xml | 443 ++++++++++++++++++++++++++++++++ 1 file changed, 443 insertions(+) create mode 100644 libstdc++-v3/doc/xml/manual/support.xml (limited to 'libstdc++-v3/doc/xml/manual/support.xml') diff --git a/libstdc++-v3/doc/xml/manual/support.xml b/libstdc++-v3/doc/xml/manual/support.xml new file mode 100644 index 000000000..2cb7205bd --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/support.xml @@ -0,0 +1,443 @@ + + + + + Support + <indexterm><primary>Support</primary></indexterm> + + + + ISO C++ + + + library + + + + + + This part deals with the functions called and objects created + automatically during the course of a program's existence. + + + + While we can't reproduce the contents of the Standard here (you + need to get your own copy from your nation's member body; see our + homepage for help), we can mention a couple of changes in what + kind of support a C++ program gets from the Standard Library. + + +
Types + + +
Fundamental Types + + + C++ has the following builtin types: + + + + char + + + signed char + + + unsigned char + + + signed short + + + signed int + + + signed long + + + unsigned short + + + unsigned int + + + unsigned long + + + bool + + + wchar_t + + + float + + + double + + + long double + + + + + These fundamental types are always available, without having to + include a header file. These types are exactly the same in + either C++ or in C. + + + + Specializing parts of the library on these types is prohibited: + instead, use a POD. + + +
+
Numeric Properties + + + + + The header limits defines + traits classes to give access to various implementation + defined-aspects of the fundamental types. The traits classes -- + fourteen in total -- are all specializations of the template class + numeric_limits, documented here + and defined as follows: + + + + template<typename T> + struct class + { + static const bool is_specialized; + static T max() throw(); + static T min() throw(); + + static const int digits; + static const int digits10; + static const bool is_signed; + static const bool is_integer; + static const bool is_exact; + static const int radix; + static T epsilon() throw(); + static T round_error() throw(); + + static const int min_exponent; + static const int min_exponent10; + static const int max_exponent; + static const int max_exponent10; + + static const bool has_infinity; + static const bool has_quiet_NaN; + static const bool has_signaling_NaN; + static const float_denorm_style has_denorm; + static const bool has_denorm_loss; + static T infinity() throw(); + static T quiet_NaN() throw(); + static T denorm_min() throw(); + + static const bool is_iec559; + static const bool is_bounded; + static const bool is_modulo; + + static const bool traps; + static const bool tinyness_before; + static const float_round_style round_style; + }; + +
+ +
NULL + + + The only change that might affect people is the type of + NULL: while it is required to be a macro, + the definition of that macro is not allowed + to be (void*)0, which is often used in C. + + + + For g++, NULL is + #define'd to be + __null, a magic keyword extension of + g++. + + + + The biggest problem of #defining NULL to be + something like 0L is that the compiler will view + that as a long integer before it views it as a pointer, so + overloading won't do what you expect. (This is why + g++ has a magic extension, so that + NULL is always a pointer.) + + + In his book Effective + C++, Scott Meyers points out that the best way + to solve this problem is to not overload on pointer-vs-integer + types to begin with. He also offers a way to make your own magic + NULL that will match pointers before it + matches integers. + + See + the + Effective C++ CD example + +
+ +
+ +
Dynamic Memory + + + + There are six flavors each of new and + delete, so make certain that you're using the right + ones. Here are quickie descriptions of new: + + + + single object form, throwing a + bad_alloc on errors; this is what most + people are used to using + + + Single object "nothrow" form, returning NULL on errors + + + Array new, throwing + bad_alloc on errors + + + Array nothrow new, returning + NULL on errors + + + Placement new, which does nothing (like + it's supposed to) + + + Placement array new, which also does + nothing + + + + They are distinguished by the parameters that you pass to them, like + any other overloaded function. The six flavors of delete + are distinguished the same way, but none of them are allowed to throw + an exception under any circumstances anyhow. (They match up for + completeness' sake.) + + + Remember that it is perfectly okay to call delete on a + NULL pointer! Nothing happens, by definition. That is not the + same thing as deleting a pointer twice. + + + By default, if one of the throwing news can't + allocate the memory requested, it tosses an instance of a + bad_alloc exception (or, technically, some class derived + from it). You can change this by writing your own function (called a + new-handler) and then registering it with set_new_handler(): + + + typedef void (*PFV)(void); + + static char* safety; + static PFV old_handler; + + void my_new_handler () + { + delete[] safety; + popup_window ("Dude, you are running low on heap memory. You + should, like, close some windows, or something. + The next time you run out, we're gonna burn!"); + set_new_handler (old_handler); + return; + } + + int main () + { + safety = new char[500000]; + old_handler = set_new_handler (&my_new_handler); + ... + } + + + bad_alloc is derived from the base exception + class defined in Sect1 19. + +
+ +
Termination + + +
Termination Handlers + + + Not many changes here to cstdlib. You should note that the + abort() function does not call the + destructors of automatic nor static objects, so if you're + depending on those to do cleanup, it isn't going to happen. + (The functions registered with atexit() + don't get called either, so you can forget about that + possibility, too.) + + + The good old exit() function can be a bit + funky, too, until you look closer. Basically, three points to + remember are: + + + + + Static objects are destroyed in reverse order of their creation. + + + + + Functions registered with atexit() are called in + reverse order of registration, once per registration call. + (This isn't actually new.) + + + + + The previous two actions are interleaved, that is, + given this pseudocode: + + + extern "C or C++" void f1 (void); + extern "C or C++" void f2 (void); + + static Thing obj1; + atexit(f1); + static Thing obj2; + atexit(f2); + + + then at a call of exit(), + f2 will be called, then + obj2 will be destroyed, then + f1 will be called, and finally + obj1 will be destroyed. If + f1 or f2 allow an + exception to propagate out of them, Bad Things happen. + + + + + Note also that atexit() is only required to store 32 + functions, and the compiler/library might already be using some of + those slots. If you think you may run out, we recommend using + the xatexit/xexit combination from libiberty, which has no such limit. + +
+ +
Verbose Terminate Handler + + + + If you are having difficulty with uncaught exceptions and want a + little bit of help debugging the causes of the core dumps, you can + make use of a GNU extension, the verbose terminate handler. + + + +#include <exception> + +int main() +{ + std::set_terminate(__gnu_cxx::__verbose_terminate_handler); + ... + + throw anything; +} + + + + The __verbose_terminate_handler function + obtains the name of the current exception, attempts to demangle + it, and prints it to stderr. If the exception is derived from + exception then the output from + what() will be included. + + + + Any replacement termination function is required to kill the + program without returning; this one calls abort. + + + + For example: + + + +#include <exception> +#include <stdexcept> + +struct argument_error : public std::runtime_error +{ + argument_error(const std::string& s): std::runtime_error(s) { } +}; + +int main(int argc) +{ + std::set_terminate(__gnu_cxx::__verbose_terminate_handler); + if (argc > 5) + throw argument_error(argc is greater than 5!); + else + throw argc; +} + + + + With the verbose terminate handler active, this gives: + + + + + % ./a.out + terminate called after throwing a `int' + Aborted + % ./a.out f f f f f f f f f f f + terminate called after throwing an instance of `argument_error' + what(): argc is greater than 5! + Aborted + + + + + The 'Aborted' line comes from the call to + abort(), of course. + + + + This is the default termination handler; nothing need be done to + use it. To go back to the previous silent death + method, simply include exception and + cstdlib, and call + + + + std::set_terminate(std::abort); + + + + After this, all calls to terminate will use + abort as the terminate handler. + + + + Note: the verbose terminate handler will attempt to write to + stderr. If your application closes stderr or redirects it to an + inappropriate location, + __verbose_terminate_handler will behave in + an unspecified manner. + + +
+
+ + -- cgit v1.2.3