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