support.xml revision 1.8
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 class template 101 <classname>numeric_limits</classname> 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" 173 xlink:href="http://www.aristeia.com/books.html"><emphasis>Effective 174 C++</emphasis></link>, Scott Meyers points out that the best way 175 to solve this problem is to not overload on pointer-vs-integer 176 types to begin with. He also offers a way to make your own magic 177 <constant>NULL</constant> that will match pointers before it 178 matches integers. 179 </para> 180 <para>See the 181 <link xmlns:xlink="http://www.w3.org/1999/xlink" 182 xlink:href="http://www.aristeia.com/books.html"><emphasis>Effective 183 C++ CD</emphasis></link> example. 184 </para> 185 </section> 186 187</section> 188 189<section xml:id="std.support.memory" xreflabel="Dynamic Memory"><info><title>Dynamic Memory</title></info> 190 <?dbhtml filename="dynamic_memory.html"?> 191 192 <para> 193 There are six flavors each of <function>new</function> and 194 <function>delete</function>, so make certain that you're using the right 195 ones. Here are quickie descriptions of <function>new</function>: 196 </para> 197 <itemizedlist> 198 <listitem><para> 199 single object form, throwing a 200 <classname>bad_alloc</classname> on errors; this is what most 201 people are used to using 202 </para></listitem> 203 <listitem><para> 204 Single object "nothrow" form, returning NULL on errors 205 </para></listitem> 206 <listitem><para> 207 Array <function>new</function>, throwing 208 <classname>bad_alloc</classname> on errors 209 </para></listitem> 210 <listitem><para> 211 Array nothrow <function>new</function>, returning 212 <constant>NULL</constant> on errors 213 </para></listitem> 214 <listitem><para> 215 Placement <function>new</function>, which does nothing (like 216 it's supposed to) 217 </para></listitem> 218 <listitem><para> 219 Placement array <function>new</function>, which also does 220 nothing 221 </para></listitem> 222 </itemizedlist> 223 <para> 224 They are distinguished by the parameters that you pass to them, like 225 any other overloaded function. The six flavors of <function>delete</function> 226 are distinguished the same way, but none of them are allowed to throw 227 an exception under any circumstances anyhow. (They match up for 228 completeness' sake.) 229 </para> 230 <para> 231 Remember that it is perfectly okay to call <function>delete</function> on a 232 NULL pointer! Nothing happens, by definition. That is not the 233 same thing as deleting a pointer twice. 234 </para> 235 <para> 236 By default, if one of the <quote>throwing <function>new</function>s</quote> can't 237 allocate the memory requested, it tosses an instance of a 238 <classname>bad_alloc</classname> exception (or, technically, some class derived 239 from it). You can change this by writing your own function (called a 240 new-handler) and then registering it with <function>set_new_handler()</function>: 241 </para> 242 <programlisting> 243 typedef void (*PFV)(void); 244 245 static char* safety; 246 static PFV old_handler; 247 248 void my_new_handler () 249 { 250 delete[] safety; 251 popup_window ("Dude, you are running low on heap memory. You" 252 " should, like, close some windows, or something." 253 " The next time you run out, we're gonna burn!"); 254 set_new_handler (old_handler); 255 return; 256 } 257 258 int main () 259 { 260 safety = new char[500000]; 261 old_handler = set_new_handler (&my_new_handler); 262 ... 263 } 264 </programlisting> 265 <para> 266 <classname>bad_alloc</classname> is derived from the base <classname>exception</classname> 267 class defined in Sect1 19. 268 </para> 269</section> 270 271<section xml:id="std.support.termination" xreflabel="Termination"><info><title>Termination</title></info> 272 <?dbhtml filename="termination.html"?> 273 274 <section xml:id="support.termination.handlers" xreflabel="Termination Handlers"><info><title>Termination Handlers</title></info> 275 276 <para> 277 Not many changes here to <filename class="headerfile">cstdlib</filename>. You should note that the 278 <function>abort()</function> function does not call the 279 destructors of automatic nor static objects, so if you're 280 depending on those to do cleanup, it isn't going to happen. 281 (The functions registered with <function>atexit()</function> 282 don't get called either, so you can forget about that 283 possibility, too.) 284 </para> 285 <para> 286 The good old <function>exit()</function> function can be a bit 287 funky, too, until you look closer. Basically, three points to 288 remember are: 289 </para> 290 <orderedlist inheritnum="ignore" continuation="restarts"> 291 <listitem> 292 <para> 293 Static objects are destroyed in reverse order of their creation. 294 </para> 295 </listitem> 296 <listitem> 297 <para> 298 Functions registered with <function>atexit()</function> are called in 299 reverse order of registration, once per registration call. 300 (This isn't actually new.) 301 </para> 302 </listitem> 303 <listitem> 304 <para> 305 The previous two actions are <quote>interleaved,</quote> that is, 306 given this pseudocode: 307 </para> 308<programlisting> 309 extern "C or C++" void f1 (void); 310 extern "C or C++" void f2 (void); 311 312 static Thing obj1; 313 atexit(f1); 314 static Thing obj2; 315 atexit(f2); 316</programlisting> 317 <para> 318 then at a call of <function>exit()</function>, 319 <varname>f2</varname> will be called, then 320 <varname>obj2</varname> will be destroyed, then 321 <varname>f1</varname> will be called, and finally 322 <varname>obj1</varname> will be destroyed. If 323 <varname>f1</varname> or <varname>f2</varname> allow an 324 exception to propagate out of them, Bad Things happen. 325 </para> 326 </listitem> 327 </orderedlist> 328 <para> 329 Note also that <function>atexit()</function> is only required to store 32 330 functions, and the compiler/library might already be using some of 331 those slots. If you think you may run out, we recommend using 332 the <function>xatexit</function>/<function>xexit</function> combination from <literal>libiberty</literal>, which has no such limit. 333 </para> 334 </section> 335 336 <section xml:id="support.termination.verbose" xreflabel="Verbose Terminate Handler"><info><title>Verbose Terminate Handler</title></info> 337 <?dbhtml filename="verbose_termination.html"?> 338 339 <para> 340 If you are having difficulty with uncaught exceptions and want a 341 little bit of help debugging the causes of the core dumps, you can 342 make use of a GNU extension, the verbose terminate handler. 343 </para> 344 345<programlisting> 346#include <exception> 347 348int main() 349{ 350 std::set_terminate(__gnu_cxx::__verbose_terminate_handler); 351 ... 352 353 throw <replaceable>anything</replaceable>; 354} 355</programlisting> 356 357 <para> 358 The <function>__verbose_terminate_handler</function> function 359 obtains the name of the current exception, attempts to demangle 360 it, and prints it to stderr. If the exception is derived from 361 <classname>exception</classname> then the output from 362 <function>what()</function> will be included. 363 </para> 364 365 <para> 366 Any replacement termination function is required to kill the 367 program without returning; this one calls abort. 368 </para> 369 370 <para> 371 For example: 372 </para> 373 374<programlisting> 375#include <exception> 376#include <stdexcept> 377 378struct argument_error : public std::runtime_error 379{ 380 argument_error(const std::string& s): std::runtime_error(s) { } 381}; 382 383int main(int argc) 384{ 385 std::set_terminate(__gnu_cxx::__verbose_terminate_handler); 386 if (argc > 5) 387 throw argument_error("argc is greater than 5!"); 388 else 389 throw argc; 390} 391</programlisting> 392 393 <para> 394 With the verbose terminate handler active, this gives: 395 </para> 396 397 <screen> 398 <computeroutput> 399 % ./a.out 400 terminate called after throwing a `int' 401 Aborted 402 % ./a.out f f f f f f f f f f f 403 terminate called after throwing an instance of `argument_error' 404 what(): argc is greater than 5! 405 Aborted 406 </computeroutput> 407 </screen> 408 409 <para> 410 The 'Aborted' line comes from the call to 411 <function>abort()</function>, of course. 412 </para> 413 414 <para> 415 This is the default termination handler; nothing need be done to 416 use it. To go back to the previous <quote>silent death</quote> 417 method, simply include <filename>exception</filename> and 418 <filename>cstdlib</filename>, and call 419 </para> 420 421 <programlisting> 422 std::set_terminate(std::abort); 423 </programlisting> 424 425 <para> 426 After this, all calls to <function>terminate</function> will use 427 <function>abort</function> as the terminate handler. 428 </para> 429 430 <para> 431 Note: the verbose terminate handler will attempt to write to 432 stderr. If your application closes stderr or redirects it to an 433 inappropriate location, 434 <function>__verbose_terminate_handler</function> will behave in 435 an unspecified manner. 436 </para> 437 438 </section> 439</section> 440 441</chapter> 442