1*404b540aSrobert<?xml version="1.0" encoding="ISO-8859-1"?> 2*404b540aSrobert<!DOCTYPE html 3*404b540aSrobert PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 4*404b540aSrobert "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 5*404b540aSrobert 6*404b540aSrobert<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 7*404b540aSrobert<head> 8*404b540aSrobert <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> 9*404b540aSrobert <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> 10*404b540aSrobert <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> 11*404b540aSrobert <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 18." /> 12*404b540aSrobert <meta name="GENERATOR" content="vi and eight fingers" /> 13*404b540aSrobert <title>libstdc++-v3 HOWTO: Chapter 18: Library Support</title> 14*404b540aSrobert<link rel="StyleSheet" href="../lib3styles.css" type="text/css" /> 15*404b540aSrobert<link rel="Start" href="../documentation.html" type="text/html" 16*404b540aSrobert title="GNU C++ Standard Library" /> 17*404b540aSrobert<link rel="Prev" href="../17_intro/howto.html" type="text/html" 18*404b540aSrobert title="Library Introduction" /> 19*404b540aSrobert<link rel="Next" href="../19_diagnostics/howto.html" type="text/html" 20*404b540aSrobert title="Diagnostics" /> 21*404b540aSrobert<link rel="Copyright" href="../17_intro/license.html" type="text/html" /> 22*404b540aSrobert<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." /> 23*404b540aSrobert</head> 24*404b540aSrobert<body> 25*404b540aSrobert 26*404b540aSrobert<h1 class="centered"><a name="top">Chapter 18: Library Support</a></h1> 27*404b540aSrobert 28*404b540aSrobert<p>Chapter 18 deals with the functions called and objects created 29*404b540aSrobert automatically during the course of a program's existence. 30*404b540aSrobert</p> 31*404b540aSrobert<p>While we can't reproduce the contents of the Standard here (you need to 32*404b540aSrobert get your own copy from your nation's member body; see our homepage for 33*404b540aSrobert help), we can mention a couple of changes in what kind of support a C++ 34*404b540aSrobert program gets from the Standard Library. 35*404b540aSrobert</p> 36*404b540aSrobert 37*404b540aSrobert 38*404b540aSrobert<!-- ####################################################### --> 39*404b540aSrobert<hr /> 40*404b540aSrobert<h1>Contents</h1> 41*404b540aSrobert<ul> 42*404b540aSrobert <li><a href="#1">Types</a></li> 43*404b540aSrobert <li><a href="#2">Implementation properties</a></li> 44*404b540aSrobert <li><a href="#3">Start and Termination</a></li> 45*404b540aSrobert <li><a href="#4">Verbose <code>terminate</code></a></li> 46*404b540aSrobert <li><a href="#5">Dynamic memory management</a></li> 47*404b540aSrobert <li><a href="#6">RTTI, the ABI, and demangling</a></li> 48*404b540aSrobert</ul> 49*404b540aSrobert 50*404b540aSrobert<hr /> 51*404b540aSrobert 52*404b540aSrobert<!-- ####################################################### --> 53*404b540aSrobert 54*404b540aSrobert<h2><a name="1">Types</a></h2> 55*404b540aSrobert <p>All the types that you're used to in C are here in one form or 56*404b540aSrobert another. The only change that might affect people is the type of 57*404b540aSrobert NULL: while it is required to be a macro, the definition of that 58*404b540aSrobert macro is <em>not</em> allowed to be <code>(void*)0</code>, which is 59*404b540aSrobert often used in C. 60*404b540aSrobert </p> 61*404b540aSrobert <p>In g++, NULL is #define'd to be <code>__null</code>, a magic keyword 62*404b540aSrobert extension of g++. 63*404b540aSrobert </p> 64*404b540aSrobert <p>The biggest problem of #defining NULL to be something like 65*404b540aSrobert "0L" is that the compiler will view that as a long integer 66*404b540aSrobert before it views it as a pointer, so overloading won't do what you 67*404b540aSrobert expect. (This is why g++ has a magic extension, so that NULL is 68*404b540aSrobert always a pointer.) 69*404b540aSrobert </p> 70*404b540aSrobert <p>In his book 71*404b540aSrobert <a href="http://www.awprofessional.com/titles/0-201-92488-9/"><em>Effective C++</em></a>, 72*404b540aSrobert Scott Meyers points out that the best way to solve this problem is to 73*404b540aSrobert not overload on pointer-vs-integer types to begin with. He also 74*404b540aSrobert offers a way to make your own magic NULL that will match pointers 75*404b540aSrobert before it matches integers: 76*404b540aSrobert </p> 77*404b540aSrobert <pre> 78*404b540aSrobert const // this is a const object... 79*404b540aSrobert class { 80*404b540aSrobert public: 81*404b540aSrobert template<class T> // convertible to any type 82*404b540aSrobert operator T*() const // of null non-member 83*404b540aSrobert { return 0; } // pointer... 84*404b540aSrobert 85*404b540aSrobert template<class C, class T> // or any type of null 86*404b540aSrobert operator T C::*() const // member pointer... 87*404b540aSrobert { return 0; } 88*404b540aSrobert 89*404b540aSrobert private: 90*404b540aSrobert void operator&() const; // whose address can't be 91*404b540aSrobert // taken (see Item 27)... 92*404b540aSrobert 93*404b540aSrobert } NULL; // and whose name is NULL 94*404b540aSrobert </pre> 95*404b540aSrobert <p>(Cribbed from the published version of 96*404b540aSrobert <a href="http://www.awprofessional.com/titles/0-201-31015-5/">the 97*404b540aSrobert Effective C++ CD</a>, reproduced here with permission.) 98*404b540aSrobert </p> 99*404b540aSrobert <p>If you aren't using g++ (why?), but you do have a compiler which 100*404b540aSrobert supports member function templates, then you can use this definition 101*404b540aSrobert of NULL (be sure to #undef any existing versions). It only helps if 102*404b540aSrobert you actually use NULL in function calls, though; if you make a call of 103*404b540aSrobert <code>foo(0);</code> instead of <code>foo(NULL);</code>, then you're back 104*404b540aSrobert where you started. 105*404b540aSrobert </p> 106*404b540aSrobert <p><strong>Added Note:</strong> When we contacted Dr. Meyers to ask 107*404b540aSrobert permission to 108*404b540aSrobert print this stuff, it prompted him to run this code through current 109*404b540aSrobert compilers to see what the state of the art is with respect to member 110*404b540aSrobert template functions. He posted 111*404b540aSrobert <a href="http://groups.google.com/groups?oi=djq&selm=an_644660779">an 112*404b540aSrobert article to Usenet</a> after discovering that the code above is not 113*404b540aSrobert valid! Even though it has no data members, it still needs a 114*404b540aSrobert user-defined constructor (which means that the class needs a type name 115*404b540aSrobert after all). The ctor can have an empty body; it just needs to be 116*404b540aSrobert there. (Stupid requirement? We think so too, and this will probably 117*404b540aSrobert be changed in the language itself.) 118*404b540aSrobert </p> 119*404b540aSrobert <p>Return <a href="#top">to top of page</a> or 120*404b540aSrobert <a href="../faq/index.html">to the FAQ</a>. 121*404b540aSrobert </p> 122*404b540aSrobert 123*404b540aSrobert<hr /> 124*404b540aSrobert<h2><a name="2">Implementation properties</a></h2> 125*404b540aSrobert <h3><code><limits></code></h3> 126*404b540aSrobert <p>This header mainly defines traits classes to give access to various 127*404b540aSrobert implementation defined-aspects of the fundamental types. The 128*404b540aSrobert traits classes -- fourteen in total -- are all specializations of the 129*404b540aSrobert template class <code>numeric_limits</code>, documented 130*404b540aSrobert <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/structstd_1_1numeric__limits.html">here</a> 131*404b540aSrobert and defined as follows: 132*404b540aSrobert </p> 133*404b540aSrobert <pre> 134*404b540aSrobert template<typename T> struct class { 135*404b540aSrobert static const bool is_specialized; 136*404b540aSrobert static T max() throw(); 137*404b540aSrobert static T min() throw(); 138*404b540aSrobert 139*404b540aSrobert static const int digits; 140*404b540aSrobert static const int digits10; 141*404b540aSrobert static const bool is_signed; 142*404b540aSrobert static const bool is_integer; 143*404b540aSrobert static const bool is_exact; 144*404b540aSrobert static const int radix; 145*404b540aSrobert static T epsilon() throw(); 146*404b540aSrobert static T round_error() throw(); 147*404b540aSrobert 148*404b540aSrobert static const int min_exponent; 149*404b540aSrobert static const int min_exponent10; 150*404b540aSrobert static const int max_exponent; 151*404b540aSrobert static const int max_exponent10; 152*404b540aSrobert 153*404b540aSrobert static const bool has_infinity; 154*404b540aSrobert static const bool has_quiet_NaN; 155*404b540aSrobert static const bool has_signaling_NaN; 156*404b540aSrobert static const float_denorm_style has_denorm; 157*404b540aSrobert static const bool has_denorm_loss; 158*404b540aSrobert static T infinity() throw(); 159*404b540aSrobert static T quiet_NaN() throw(); 160*404b540aSrobert static T denorm_min() throw(); 161*404b540aSrobert 162*404b540aSrobert static const bool is_iec559; 163*404b540aSrobert static const bool is_bounded; 164*404b540aSrobert static const bool is_modulo; 165*404b540aSrobert 166*404b540aSrobert static const bool traps; 167*404b540aSrobert static const bool tinyness_before; 168*404b540aSrobert static const float_round_style round_style; 169*404b540aSrobert };</pre> 170*404b540aSrobert <p>Return <a href="#top">to top of page</a> or 171*404b540aSrobert <a href="../faq/index.html">to the FAQ</a>. 172*404b540aSrobert </p> 173*404b540aSrobert 174*404b540aSrobert<hr /> 175*404b540aSrobert<h2><a name="3">Start and Termination</a></h2> 176*404b540aSrobert <p>Not many changes here to <code><cstdlib></code> (the old stdlib.h). 177*404b540aSrobert You should note that the <code>abort()</code> function does not call 178*404b540aSrobert the destructors of automatic nor static objects, so if you're depending 179*404b540aSrobert on those to do cleanup, it isn't going to happen. (The functions 180*404b540aSrobert registered with <code>atexit()</code> don't get called either, so you 181*404b540aSrobert can forget about that possibility, too.) 182*404b540aSrobert </p> 183*404b540aSrobert <p>The good old <code>exit()</code> function can be a bit funky, too, until 184*404b540aSrobert you look closer. Basically, three points to remember are: 185*404b540aSrobert </p> 186*404b540aSrobert <ol> 187*404b540aSrobert <li>Static objects are destroyed in reverse order of their creation. 188*404b540aSrobert </li> 189*404b540aSrobert <li>Functions registered with <code>atexit()</code> are called in 190*404b540aSrobert reverse order of registration, once per registration call. 191*404b540aSrobert (This isn't actually new.) 192*404b540aSrobert </li> 193*404b540aSrobert <li>The previous two actions are "interleaved," that is, 194*404b540aSrobert given this pseudocode: 195*404b540aSrobert <pre> 196*404b540aSrobert extern "C or C++" void f1 (void); 197*404b540aSrobert extern "C or C++" void f2 (void); 198*404b540aSrobert 199*404b540aSrobert static Thing obj1; 200*404b540aSrobert atexit(f1); 201*404b540aSrobert static Thing obj2; 202*404b540aSrobert atexit(f2); 203*404b540aSrobert </pre> 204*404b540aSrobert then at a call of <code>exit()</code>, f2 will be called, then 205*404b540aSrobert obj2 will be destroyed, then f1 will be called, and finally obj1 206*404b540aSrobert will be destroyed. If f1 or f2 allow an exception to propagate 207*404b540aSrobert out of them, Bad Things happen. 208*404b540aSrobert </li> 209*404b540aSrobert </ol> 210*404b540aSrobert <p>Note also that <code>atexit()</code> is only required to store 32 211*404b540aSrobert functions, and the compiler/library might already be using some of 212*404b540aSrobert those slots. If you think you may run out, we recommend using 213*404b540aSrobert the xatexit/xexit combination from libiberty, which has no such limit. 214*404b540aSrobert </p> 215*404b540aSrobert <p>Return <a href="#top">to top of page</a> or 216*404b540aSrobert <a href="../faq/index.html">to the FAQ</a>. 217*404b540aSrobert </p> 218*404b540aSrobert 219*404b540aSrobert<hr /> 220*404b540aSrobert<h2><a name="4">Verbose <code>terminate</code></a></h2> 221*404b540aSrobert <p>If you are having difficulty with uncaught exceptions and want a 222*404b540aSrobert little bit of help debugging the causes of the core dumps, you can 223*404b540aSrobert make use of a GNU extension in GCC 3.1 and later: 224*404b540aSrobert </p> 225*404b540aSrobert <pre> 226*404b540aSrobert #include <exception> 227*404b540aSrobert 228*404b540aSrobert int main() 229*404b540aSrobert { 230*404b540aSrobert std::set_terminate(__gnu_cxx::__verbose_terminate_handler); 231*404b540aSrobert ... 232*404b540aSrobert throw <em>anything</em>; 233*404b540aSrobert }</pre> 234*404b540aSrobert <p>The <code> __verbose_terminate_handler </code> function obtains the name 235*404b540aSrobert of the current exception, attempts to demangle it, and prints it to 236*404b540aSrobert stderr. If the exception is derived from <code> std::exception </code> 237*404b540aSrobert then the output from <code>what()</code> will be included. 238*404b540aSrobert </p> 239*404b540aSrobert <p>Any replacement termination function is required to kill the program 240*404b540aSrobert without returning; this one calls abort. 241*404b540aSrobert </p> 242*404b540aSrobert <p>For example: 243*404b540aSrobert </p> 244*404b540aSrobert <pre> 245*404b540aSrobert #include <exception> 246*404b540aSrobert #include <stdexcept> 247*404b540aSrobert 248*404b540aSrobert struct argument_error : public std::runtime_error 249*404b540aSrobert { 250*404b540aSrobert argument_error(const std::string& s): std::runtime_error(s) { } 251*404b540aSrobert }; 252*404b540aSrobert 253*404b540aSrobert int main(int argc) 254*404b540aSrobert { 255*404b540aSrobert std::set_terminate(__gnu_cxx::__verbose_terminate_handler); 256*404b540aSrobert if (argc > 5) 257*404b540aSrobert throw argument_error("argc is greater than 5!"); 258*404b540aSrobert else 259*404b540aSrobert throw argc; 260*404b540aSrobert } 261*404b540aSrobert </pre> 262*404b540aSrobert <p>In GCC 3.1 and later, this gives 263*404b540aSrobert </p> 264*404b540aSrobert <pre> 265*404b540aSrobert % ./a.out 266*404b540aSrobert terminate called after throwing a `int' 267*404b540aSrobert Aborted 268*404b540aSrobert % ./a.out f f f f f f f f f f f 269*404b540aSrobert terminate called after throwing an instance of `argument_error' 270*404b540aSrobert what(): argc is greater than 5! 271*404b540aSrobert Aborted 272*404b540aSrobert %</pre> 273*404b540aSrobert <p>The 'Aborted' line comes from the call to abort(), of course. 274*404b540aSrobert </p> 275*404b540aSrobert <p><strong>UPDATE:</strong> Starting with GCC 3.4, this is the default 276*404b540aSrobert termination handler; nothing need be done to use it. To go back to 277*404b540aSrobert the previous "silent death" method, simply include 278*404b540aSrobert <code><exception></code> and <code><cstdlib></code>, 279*404b540aSrobert and call 280*404b540aSrobert </p> 281*404b540aSrobert <pre> 282*404b540aSrobert std::set_terminate(std::abort);</pre> 283*404b540aSrobert <p>Return <a href="#top">to top of page</a> or 284*404b540aSrobert <a href="../faq/index.html">to the FAQ</a>. 285*404b540aSrobert </p> 286*404b540aSrobert 287*404b540aSrobert<p> 288*404b540aSrobert This function will attempt to write to stderr. If your application 289*404b540aSrobert closes stderr or redirects it to an inappropriate location, 290*404b540aSrobert <code>__verbose_terminate_handler</code> will behave in an 291*404b540aSrobert unspecified manner. 292*404b540aSrobert</p> 293*404b540aSrobert 294*404b540aSrobert<hr /> 295*404b540aSrobert<h2><a name="5">Dynamic memory management</a></h2> 296*404b540aSrobert <p>There are six flavors each of <code>new</code> and 297*404b540aSrobert <code>delete</code>, so make certain that you're using the right 298*404b540aSrobert ones! Here are quickie descriptions of <code>new</code>: 299*404b540aSrobert </p> 300*404b540aSrobert <ul> 301*404b540aSrobert <li>single object form, throwing a <code>bad_alloc</code> on errors; 302*404b540aSrobert this is what most people are used to using</li> 303*404b540aSrobert <li>single object "nothrow" form, returning NULL on errors</li> 304*404b540aSrobert <li>array new, throwing <code>bad_alloc</code> on errors</li> 305*404b540aSrobert <li>array nothrow new, returning NULL on errors</li> 306*404b540aSrobert <li>placement new, which does nothing (like it's supposed to)</li> 307*404b540aSrobert <li>placement array new, which also does nothing</li> 308*404b540aSrobert </ul> 309*404b540aSrobert <p>They are distinguished by the parameters that you pass to them, like 310*404b540aSrobert any other overloaded function. The six flavors of <code>delete</code> 311*404b540aSrobert are distinguished the same way, but none of them are allowed to throw 312*404b540aSrobert an exception under any circumstances anyhow. (They match up for 313*404b540aSrobert completeness' sake.) 314*404b540aSrobert </p> 315*404b540aSrobert <p>Remember that it is perfectly okay to call <code>delete</code> on a 316*404b540aSrobert NULL pointer! Nothing happens, by definition. That is not the 317*404b540aSrobert same thing as deleting a pointer twice. 318*404b540aSrobert </p> 319*404b540aSrobert <p>By default, if one of the "throwing <code>new</code>s" can't 320*404b540aSrobert allocate the memory requested, it tosses an instance of a 321*404b540aSrobert <code>bad_alloc</code> exception (or, technically, some class derived 322*404b540aSrobert from it). You can change this by writing your own function (called a 323*404b540aSrobert new-handler) and then registering it with <code>set_new_handler()</code>: 324*404b540aSrobert </p> 325*404b540aSrobert <pre> 326*404b540aSrobert typedef void (*PFV)(void); 327*404b540aSrobert 328*404b540aSrobert static char* safety; 329*404b540aSrobert static PFV old_handler; 330*404b540aSrobert 331*404b540aSrobert void my_new_handler () 332*404b540aSrobert { 333*404b540aSrobert delete[] safety; 334*404b540aSrobert popup_window ("Dude, you are running low on heap memory. You 335*404b540aSrobert should, like, close some windows, or something. 336*404b540aSrobert The next time you run out, we're gonna burn!"); 337*404b540aSrobert set_new_handler (old_handler); 338*404b540aSrobert return; 339*404b540aSrobert } 340*404b540aSrobert 341*404b540aSrobert int main () 342*404b540aSrobert { 343*404b540aSrobert safety = new char[500000]; 344*404b540aSrobert old_handler = set_new_handler (&my_new_handler); 345*404b540aSrobert ... 346*404b540aSrobert } 347*404b540aSrobert </pre> 348*404b540aSrobert <p><code>bad_alloc</code> is derived from the base <code>exception</code> 349*404b540aSrobert class defined in Chapter 19. 350*404b540aSrobert </p> 351*404b540aSrobert <p>Return <a href="#top">to top of page</a> or 352*404b540aSrobert <a href="../faq/index.html">to the FAQ</a>. 353*404b540aSrobert </p> 354*404b540aSrobert 355*404b540aSrobert<hr /> 356*404b540aSrobert<h2><a name="6">RTTI, the ABI, and demangling</a></h2> 357*404b540aSrobert <p>If you have read the <a href="../documentation.html#4">source 358*404b540aSrobert documentation</a> for <code> namespace abi </code> then you are aware 359*404b540aSrobert of the cross-vendor C++ ABI which we use. One of the exposed 360*404b540aSrobert functions is the one which we use for demangling in programs like 361*404b540aSrobert <code>c++filt</code>, and you can use it yourself as well. 362*404b540aSrobert </p> 363*404b540aSrobert <p>(The function itself might use different demanglers, but that's the 364*404b540aSrobert whole point of abstract interfaces. If we change the implementation, 365*404b540aSrobert you won't notice.) 366*404b540aSrobert </p> 367*404b540aSrobert <p>Probably the only times you'll be interested in demangling at runtime 368*404b540aSrobert are when you're seeing <code>typeid</code> strings in RTTI, or when 369*404b540aSrobert you're handling the runtime-support exception classes. For example: 370*404b540aSrobert </p> 371*404b540aSrobert <pre> 372*404b540aSrobert#include <exception> 373*404b540aSrobert#include <iostream> 374*404b540aSrobert#include <cxxabi.h> 375*404b540aSrobert 376*404b540aSrobertstruct empty { }; 377*404b540aSrobert 378*404b540aSroberttemplate <typename T, int N> 379*404b540aSrobert struct bar { }; 380*404b540aSrobert 381*404b540aSrobert 382*404b540aSrobertint main() 383*404b540aSrobert{ 384*404b540aSrobert int status; 385*404b540aSrobert char *realname; 386*404b540aSrobert 387*404b540aSrobert // exception classes not in <stdexcept>, thrown by the implementation 388*404b540aSrobert // instead of the user 389*404b540aSrobert std::bad_exception e; 390*404b540aSrobert realname = abi::__cxa_demangle(e.what(), 0, 0, &status); 391*404b540aSrobert std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n'; 392*404b540aSrobert free(realname); 393*404b540aSrobert 394*404b540aSrobert 395*404b540aSrobert // typeid 396*404b540aSrobert bar<empty,17> u; 397*404b540aSrobert const std::type_info &ti = typeid(u); 398*404b540aSrobert 399*404b540aSrobert realname = abi::__cxa_demangle(ti.name(), 0, 0, &status); 400*404b540aSrobert std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n'; 401*404b540aSrobert free(realname); 402*404b540aSrobert 403*404b540aSrobert return 0; 404*404b540aSrobert}</pre> 405*404b540aSrobert <p>With GCC 3.1 and later, this prints 406*404b540aSrobert </p> 407*404b540aSrobert <pre> 408*404b540aSrobert St13bad_exception => std::bad_exception : 0 409*404b540aSrobert 3barI5emptyLi17EE => bar<empty, 17> : 0 </pre> 410*404b540aSrobert <p>The demangler interface is described in the source documentation 411*404b540aSrobert linked to above. It is actually written in C, so you don't need to 412*404b540aSrobert be writing C++ in order to demangle C++. (That also means we have to 413*404b540aSrobert use crummy memory management facilities, so don't forget to free() 414*404b540aSrobert the returned char array.) 415*404b540aSrobert </p> 416*404b540aSrobert <p>Return <a href="#top">to top of page</a> or 417*404b540aSrobert <a href="../faq/index.html">to the FAQ</a>. 418*404b540aSrobert </p> 419*404b540aSrobert 420*404b540aSrobert 421*404b540aSrobert<!-- ####################################################### --> 422*404b540aSrobert 423*404b540aSrobert<hr /> 424*404b540aSrobert<p class="fineprint"><em> 425*404b540aSrobertSee <a href="../17_intro/license.html">license.html</a> for copying conditions. 426*404b540aSrobertComments and suggestions are welcome, and may be sent to 427*404b540aSrobert<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>. 428*404b540aSrobert</em></p> 429*404b540aSrobert 430*404b540aSrobert 431*404b540aSrobert</body> 432*404b540aSrobert</html> 433