support.xml revision 1.3
1<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" 2 xml:id="std.support" xreflabel="Support"> 3<?dbhtml filename="support.html"?> 4 5<info><title> 6 Support 7 <indexterm><primary>Support</primary></indexterm> 8</title> 9 <keywordset> 10 <keyword>ISO C++</keyword> 11 <keyword>library</keyword> 12 </keywordset> 13</info> 14 15 <para> 16 This part deals with the functions called and objects created 17 automatically during the course of a program's existence. 18 </para> 19 20 <para> 21 While we can't reproduce the contents of the Standard here (you 22 need to get your own copy from your nation's member body; see our 23 homepage for help), we can mention a couple of changes in what 24 kind of support a C++ program gets from the Standard Library. 25 </para> 26 27<section xml:id="std.support.types" xreflabel="Types"><info><title>Types</title></info> 28 <?dbhtml filename="fundamental_types.html"?> 29 30 <section xml:id="std.support.types.fundamental" xreflabel="Fundamental Types"><info><title>Fundamental Types</title></info> 31 32 <para> 33 C++ has the following builtin types: 34 </para> 35 <itemizedlist> 36 <listitem><para> 37 char 38 </para></listitem> 39 <listitem><para> 40 signed char 41 </para></listitem> 42 <listitem><para> 43 unsigned char 44 </para></listitem> 45 <listitem><para> 46 signed short 47 </para></listitem> 48 <listitem><para> 49 signed int 50 </para></listitem> 51 <listitem><para> 52 signed long 53 </para></listitem> 54 <listitem><para> 55 unsigned short 56 </para></listitem> 57 <listitem><para> 58 unsigned int 59 </para></listitem> 60 <listitem><para> 61 unsigned long 62 </para></listitem> 63 <listitem><para> 64 bool 65 </para></listitem> 66 <listitem><para> 67 wchar_t 68 </para></listitem> 69 <listitem><para> 70 float 71 </para></listitem> 72 <listitem><para> 73 double 74 </para></listitem> 75 <listitem><para> 76 long double 77 </para></listitem> 78 </itemizedlist> 79 80 <para> 81 These fundamental types are always available, without having to 82 include a header file. These types are exactly the same in 83 either C++ or in C. 84 </para> 85 86 <para> 87 Specializing parts of the library on these types is prohibited: 88 instead, use a POD. 89 </para> 90 91 </section> 92 <section xml:id="std.support.types.numeric_limits" xreflabel="Numeric Properties"><info><title>Numeric Properties</title></info> 93 94 95 96 <para> 97 The header <filename class="headerfile">limits</filename> defines 98 traits classes to give access to various implementation 99 defined-aspects of the fundamental types. The traits classes -- 100 fourteen in total -- are all specializations of the template class 101 <classname>numeric_limits</classname>, documented <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00593.html">here</link> 102 and defined as follows: 103 </para> 104 105 <programlisting> 106 template<typename T> 107 struct class 108 { 109 static const bool is_specialized; 110 static T max() throw(); 111 static T min() throw(); 112 113 static const int digits; 114 static const int digits10; 115 static const bool is_signed; 116 static const bool is_integer; 117 static const bool is_exact; 118 static const int radix; 119 static T epsilon() throw(); 120 static T round_error() throw(); 121 122 static const int min_exponent; 123 static const int min_exponent10; 124 static const int max_exponent; 125 static const int max_exponent10; 126 127 static const bool has_infinity; 128 static const bool has_quiet_NaN; 129 static const bool has_signaling_NaN; 130 static const float_denorm_style has_denorm; 131 static const bool has_denorm_loss; 132 static T infinity() throw(); 133 static T quiet_NaN() throw(); 134 static T denorm_min() throw(); 135 136 static const bool is_iec559; 137 static const bool is_bounded; 138 static const bool is_modulo; 139 140 static const bool traps; 141 static const bool tinyness_before; 142 static const float_round_style round_style; 143 }; 144 </programlisting> 145 </section> 146 147 <section xml:id="std.support.types.null" xreflabel="NULL"><info><title>NULL</title></info> 148 149 <para> 150 The only change that might affect people is the type of 151 <constant>NULL</constant>: while it is required to be a macro, 152 the definition of that macro is <emphasis>not</emphasis> allowed 153 to be <constant>(void*)0</constant>, which is often used in C. 154 </para> 155 156 <para> 157 For <command>g++</command>, <constant>NULL</constant> is 158 <code>#define</code>'d to be 159 <constant>__null</constant>, a magic keyword extension of 160 <command>g++</command>. 161 </para> 162 163 <para> 164 The biggest problem of #defining <constant>NULL</constant> to be 165 something like <quote>0L</quote> is that the compiler will view 166 that as a long integer before it views it as a pointer, so 167 overloading won't do what you expect. (This is why 168 <command>g++</command> has a magic extension, so that 169 <constant>NULL</constant> is always a pointer.) 170 </para> 171 172 <para>In his book <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.awprofessional.com/titles/0-201-92488-9/"><emphasis>Effective 173 C++</emphasis></link>, Scott Meyers points out that the best way 174 to solve this problem is to not overload on pointer-vs-integer 175 types to begin with. He also offers a way to make your own magic 176 <constant>NULL</constant> that will match pointers before it 177 matches integers. 178 </para> 179 <para>See 180 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.awprofessional.com/titles/0-201-31015-5/">the 181 Effective C++ CD example</link> 182 </para> 183 </section> 184 185</section> 186 187<section xml:id="std.support.memory" xreflabel="Dynamic Memory"><info><title>Dynamic Memory</title></info> 188 <?dbhtml filename="dynamic_memory.html"?> 189 190 <para> 191 There are six flavors each of <function>new</function> and 192 <function>delete</function>, so make certain that you're using the right 193 ones. Here are quickie descriptions of <function>new</function>: 194 </para> 195 <itemizedlist> 196 <listitem><para> 197 single object form, throwing a 198 <classname>bad_alloc</classname> on errors; this is what most 199 people are used to using 200 </para></listitem> 201 <listitem><para> 202 Single object "nothrow" form, returning NULL on errors 203 </para></listitem> 204 <listitem><para> 205 Array <function>new</function>, throwing 206 <classname>bad_alloc</classname> on errors 207 </para></listitem> 208 <listitem><para> 209 Array nothrow <function>new</function>, returning 210 <constant>NULL</constant> on errors 211 </para></listitem> 212 <listitem><para> 213 Placement <function>new</function>, which does nothing (like 214 it's supposed to) 215 </para></listitem> 216 <listitem><para> 217 Placement array <function>new</function>, which also does 218 nothing 219 </para></listitem> 220 </itemizedlist> 221 <para> 222 They are distinguished by the parameters that you pass to them, like 223 any other overloaded function. The six flavors of <function>delete</function> 224 are distinguished the same way, but none of them are allowed to throw 225 an exception under any circumstances anyhow. (They match up for 226 completeness' sake.) 227 </para> 228 <para> 229 Remember that it is perfectly okay to call <function>delete</function> on a 230 NULL pointer! Nothing happens, by definition. That is not the 231 same thing as deleting a pointer twice. 232 </para> 233 <para> 234 By default, if one of the <quote>throwing <function>new</function>s</quote> can't 235 allocate the memory requested, it tosses an instance of a 236 <classname>bad_alloc</classname> exception (or, technically, some class derived 237 from it). You can change this by writing your own function (called a 238 new-handler) and then registering it with <function>set_new_handler()</function>: 239 </para> 240 <programlisting> 241 typedef void (*PFV)(void); 242 243 static char* safety; 244 static PFV old_handler; 245 246 void my_new_handler () 247 { 248 delete[] safety; 249 popup_window ("Dude, you are running low on heap memory. You 250 should, like, close some windows, or something. 251 The next time you run out, we're gonna burn!"); 252 set_new_handler (old_handler); 253 return; 254 } 255 256 int main () 257 { 258 safety = new char[500000]; 259 old_handler = set_new_handler (&my_new_handler); 260 ... 261 } 262 </programlisting> 263 <para> 264 <classname>bad_alloc</classname> is derived from the base <classname>exception</classname> 265 class defined in Sect1 19. 266 </para> 267</section> 268 269<section xml:id="std.support.termination" xreflabel="Termination"><info><title>Termination</title></info> 270 <?dbhtml filename="termination.html"?> 271 272 <section xml:id="support.termination.handlers" xreflabel="Termination Handlers"><info><title>Termination Handlers</title></info> 273 274 <para> 275 Not many changes here to <filename class="headerfile">cstdlib</filename>. You should note that the 276 <function>abort()</function> function does not call the 277 destructors of automatic nor static objects, so if you're 278 depending on those to do cleanup, it isn't going to happen. 279 (The functions registered with <function>atexit()</function> 280 don't get called either, so you can forget about that 281 possibility, too.) 282 </para> 283 <para> 284 The good old <function>exit()</function> function can be a bit 285 funky, too, until you look closer. Basically, three points to 286 remember are: 287 </para> 288 <orderedlist inheritnum="ignore" continuation="restarts"> 289 <listitem> 290 <para> 291 Static objects are destroyed in reverse order of their creation. 292 </para> 293 </listitem> 294 <listitem> 295 <para> 296 Functions registered with <function>atexit()</function> are called in 297 reverse order of registration, once per registration call. 298 (This isn't actually new.) 299 </para> 300 </listitem> 301 <listitem> 302 <para> 303 The previous two actions are <quote>interleaved,</quote> that is, 304 given this pseudocode: 305 </para> 306<programlisting> 307 extern "C or C++" void f1 (void); 308 extern "C or C++" void f2 (void); 309 310 static Thing obj1; 311 atexit(f1); 312 static Thing obj2; 313 atexit(f2); 314</programlisting> 315 <para> 316 then at a call of <function>exit()</function>, 317 <varname>f2</varname> will be called, then 318 <varname>obj2</varname> will be destroyed, then 319 <varname>f1</varname> will be called, and finally 320 <varname>obj1</varname> will be destroyed. If 321 <varname>f1</varname> or <varname>f2</varname> allow an 322 exception to propagate out of them, Bad Things happen. 323 </para> 324 </listitem> 325 </orderedlist> 326 <para> 327 Note also that <function>atexit()</function> is only required to store 32 328 functions, and the compiler/library might already be using some of 329 those slots. If you think you may run out, we recommend using 330 the <function>xatexit</function>/<function>xexit</function> combination from <literal>libiberty</literal>, which has no such limit. 331 </para> 332 </section> 333 334 <section xml:id="support.termination.verbose" xreflabel="Verbose Terminate Handler"><info><title>Verbose Terminate Handler</title></info> 335 <?dbhtml filename="verbose_termination.html"?> 336 337 <para> 338 If you are having difficulty with uncaught exceptions and want a 339 little bit of help debugging the causes of the core dumps, you can 340 make use of a GNU extension, the verbose terminate handler. 341 </para> 342 343<programlisting> 344#include <exception> 345 346int main() 347{ 348 std::set_terminate(__gnu_cxx::__verbose_terminate_handler); 349 ... 350 351 throw <replaceable>anything</replaceable>; 352} 353</programlisting> 354 355 <para> 356 The <function>__verbose_terminate_handler</function> function 357 obtains the name of the current exception, attempts to demangle 358 it, and prints it to stderr. If the exception is derived from 359 <classname>exception</classname> then the output from 360 <function>what()</function> will be included. 361 </para> 362 363 <para> 364 Any replacement termination function is required to kill the 365 program without returning; this one calls abort. 366 </para> 367 368 <para> 369 For example: 370 </para> 371 372<programlisting> 373#include <exception> 374#include <stdexcept> 375 376struct argument_error : public std::runtime_error 377{ 378 argument_error(const std::string& s): std::runtime_error(s) { } 379}; 380 381int main(int argc) 382{ 383 std::set_terminate(__gnu_cxx::__verbose_terminate_handler); 384 if (argc > 5) 385 throw argument_error(<quote>argc is greater than 5!</quote>); 386 else 387 throw argc; 388} 389</programlisting> 390 391 <para> 392 With the verbose terminate handler active, this gives: 393 </para> 394 395 <screen> 396 <computeroutput> 397 % ./a.out 398 terminate called after throwing a `int' 399 Aborted 400 % ./a.out f f f f f f f f f f f 401 terminate called after throwing an instance of `argument_error' 402 what(): argc is greater than 5! 403 Aborted 404 </computeroutput> 405 </screen> 406 407 <para> 408 The 'Aborted' line comes from the call to 409 <function>abort()</function>, of course. 410 </para> 411 412 <para> 413 This is the default termination handler; nothing need be done to 414 use it. To go back to the previous <quote>silent death</quote> 415 method, simply include <filename>exception</filename> and 416 <filename>cstdlib</filename>, and call 417 </para> 418 419 <programlisting> 420 std::set_terminate(std::abort); 421 </programlisting> 422 423 <para> 424 After this, all calls to <function>terminate</function> will use 425 <function>abort</function> as the terminate handler. 426 </para> 427 428 <para> 429 Note: the verbose terminate handler will attempt to write to 430 stderr. If your application closes stderr or redirects it to an 431 inappropriate location, 432 <function>__verbose_terminate_handler</function> will behave in 433 an unspecified manner. 434 </para> 435 436 </section> 437</section> 438 439</chapter> 440