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 <para> 95 The header <filename class="headerfile"><limits></filename> defines 96 traits classes to give access to various implementation 97 defined-aspects of the fundamental types. The traits classes -- 98 fourteen in total -- are all specializations of the class template 99 <classname>numeric_limits</classname> 100 and defined as follows: 101 </para> 102 103 <programlisting> 104 template<typename T> 105 struct class 106 { 107 static const bool is_specialized; 108 static T max() throw(); 109 static T min() throw(); 110 111 static const int digits; 112 static const int digits10; 113 static const bool is_signed; 114 static const bool is_integer; 115 static const bool is_exact; 116 static const int radix; 117 static T epsilon() throw(); 118 static T round_error() throw(); 119 120 static const int min_exponent; 121 static const int min_exponent10; 122 static const int max_exponent; 123 static const int max_exponent10; 124 125 static const bool has_infinity; 126 static const bool has_quiet_NaN; 127 static const bool has_signaling_NaN; 128 static const float_denorm_style has_denorm; 129 static const bool has_denorm_loss; 130 static T infinity() throw(); 131 static T quiet_NaN() throw(); 132 static T denorm_min() throw(); 133 134 static const bool is_iec559; 135 static const bool is_bounded; 136 static const bool is_modulo; 137 138 static const bool traps; 139 static const bool tinyness_before; 140 static const float_round_style round_style; 141 }; 142 </programlisting> 143 </section> 144 145 <section xml:id="std.support.types.null" xreflabel="NULL"><info><title>NULL</title></info> 146 147 <para> 148 The only change that might affect people is the type of 149 <constant>NULL</constant>: while it is required to be a macro, 150 the definition of that macro is <emphasis>not</emphasis> allowed 151 to be an expression with pointer type such as 152 <constant>(void*)0</constant>, which is often used in C. 153 </para> 154 155 <para> 156 For <command>g++</command>, <constant>NULL</constant> is 157 <code>#define</code>'d to be 158 <constant>__null</constant>, a magic keyword extension of 159 <command>g++</command> that is slightly safer than a plain integer. 160 </para> 161 162 <para> 163 The biggest problem of #defining <constant>NULL</constant> to be 164 something like <quote>0L</quote> is that the compiler will view 165 that as a long integer before it views it as a pointer, so 166 overloading won't do what you expect. It might not even have the 167 same size as a pointer, so passing <constant>NULL</constant> to a 168 varargs function where a pointer is expected might not even work 169 correctly if <code>sizeof(NULL) < sizeof(void*)</code>. 170 The G++ <constant>__null</constant> extension is defined so that 171 <code>sizeof(__null) == sizeof(void*)</code> to avoid this problem. 172 </para> 173 174 <para> 175 Scott Meyers explains this in more detail in his book 176 <link xmlns:xlink="http://www.w3.org/1999/xlink" 177 xlink:href="https://www.aristeia.com/books.html"><emphasis>Effective 178 Modern C++</emphasis></link> and as a guideline to solve this problem 179 recommends to not overload on pointer-vs-integer types to begin with. 180 </para> 181 182 <para> 183 The C++ 2011 standard added the <constant>nullptr</constant> keyword, 184 which is a null pointer constant of a special type, 185 <classname>std::nullptr_t</classname>. Values of this type can be 186 implicitly converted to <emphasis>any</emphasis> pointer type, 187 and cannot convert to integer types or be deduced as an integer type. 188 Unless you need to be compatible with C++98/C++03 or C you should prefer 189 to use <constant>nullptr</constant> instead of <constant>NULL</constant>. 190 </para> 191 </section> 192 193</section> 194 195<section xml:id="std.support.memory" xreflabel="Dynamic Memory"><info><title>Dynamic Memory</title></info> 196 <?dbhtml filename="dynamic_memory.html"?> 197 198 <para> 199 In C++98 there are six flavors each of <function>operator new</function> 200 and <function>operator delete</function>, so make certain that you're 201 using the right ones. 202 Here are quickie descriptions of <function>operator new</function>: 203 </para> 204 <variablelist> 205 <varlistentry> 206 <term><code>void* operator new(std::size_t);</code></term> 207 <listitem> 208 Single object form. 209 Throws <classname>std::bad_alloc</classname> on error. 210 This is what most people are used to using. 211 </listitem> 212 </varlistentry> 213 <varlistentry> 214 <term><code>void* operator new(std::size_t, std::nothrow_t) noexcept;</code></term> 215 <listitem> 216 Single object <quote>nothrow</quote> form. 217 Calls <code>operator new(std::size_t)</code> but if that throws, 218 returns a null pointer instead. 219 </listitem> 220 </varlistentry> 221 <varlistentry> 222 <term><code>void* operator new[](std::size_t);</code></term> 223 <listitem> 224 Array <function>new</function>. 225 Calls <code>operator new(std::size_t)</code> and so 226 throws <classname>std::bad_alloc</classname> on error. 227 </listitem> 228 </varlistentry> 229 <varlistentry> 230 <term><code>void* operator new[](std::size_t, std::nothrow_t) noexcept;</code></term> 231 <listitem> 232 Array <quote>nothrow</quote> <function>new</function>. 233 Calls <code>operator new[](std::size_t)</code> but if that throws, 234 returns a null pointer instead. 235 </listitem> 236 </varlistentry> 237 <varlistentry> 238 <term><code>void* operator new(std::size_t, void*) noexcept;</code></term> 239 <listitem> 240 Non-allocating, <quote>placement</quote> single-object <function>new</function>, 241 which does nothing except return its argument. 242 This function cannot be replaced. 243 </listitem> 244 </varlistentry> 245 <varlistentry> 246 <term><code>void* operator new[](std::size_t, void*) noexcept;</code></term> 247 <listitem> 248 Non-allocating, <quote>placement</quote> array <function>new</function>, 249 which also does nothing except return its argument. 250 This function cannot be replaced. 251 </listitem> 252 </varlistentry> 253 </variablelist> 254 <para> 255 They are distinguished by the arguments that you pass to them, like 256 any other overloaded function. The six flavors of 257 <function>operator delete</function> 258 are distinguished the same way, but none of them are allowed to throw 259 an exception under any circumstances anyhow. (The overloads match up 260 with the ones above, for completeness' sake.) 261 </para> 262 <para> 263 The C++ 2014 revision of the standard added two additional overloads of 264 <function>operator delete</function> for <quote>sized deallocation</quote>, 265 allowing the compiler to provide the size of the storage being freed. 266 </para> 267 <para> 268 The C++ 2017 standard added even more overloads of both 269 <function>operator new</function> and <function>operator delete</function> 270 for allocating and deallocating storage for overaligned types. 271 These overloads correspond to each of the allocating forms of 272 <function>operator new</function> and <function>operator delete</function> 273 but with an additional parameter of type <type>std::align_val_t</type>. 274 These new overloads are not interchangeable with the versions without 275 an aligment parameter, so if memory was allocated by an overload of 276 <function>operator new</function> taking an alignment parameter, 277 then it must be decallocated by the corresponding overload of 278 <function>operator delete</function> that takes an alignment parameter. 279 </para> 280 <para> 281 Apart from the non-allocating forms, the default versions of the array 282 and nothrow <function>operator new</function> functions will all result 283 in a call to either <function>operator new(std::size_t)</function> or 284 <function>operator new(std::size_t, std::align_val_t)</function>, 285 and similarly the default versions of the array and nothrow 286 <function>operator delete</function> functions will result in a call to 287 either <function>operator delete(void*)</function> or 288 <function>operator delete(void*, std::align_val_t)</function> 289 (or the sized versions of those). 290 </para> 291 <para> 292 Apart from the non-allocating forms, any of these functions can be 293 replaced by defining a function with the same signature in your program. 294 Replacement versions must preserve certain guarantees, such as memory 295 obtained from a nothrow <function>operator new</function> being free-able 296 by the normal (non-nothrow) <function>operator delete</function>, 297 and the sized and unsized forms of <function>operator delete</function> 298 being interchangeable (because it's unspecified whether 299 the compiler calls the sized delete instead of the normal one). 300 The simplest way to meet the guarantees is to only replace the ordinary 301 <function>operator new(size_t)</function> and 302 <function>operator delete(void*)</function> and 303 <function>operator delete(void*, std::size_t)</function> 304 functions, and the replaced versions will be used by all of 305 <function>operator new(size_t, nothrow_t)</function>, 306 <function>operator new[](size_t)</function> and 307 <function>operator new[](size_t, nothrow_t)</function> 308 and the corresponding <function>operator delete</function> functions. 309 To support types with extended alignment you may also need to replace 310 <function>operator new(size_t, align_val_t)</function> and 311 <function>operator delete(void*, align_val_t)</function> 312 <function>operator delete(void*, size_t, align_val_t)</function> 313 (which will then be used by the nothrow and array forms for 314 extended alignments). 315 If you do need to replace other forms (e.g. to define the nothrow 316 <function>operator new</function> to allocate memory directly, so it 317 works with exceptions disabled) then make sure the memory it allocates 318 can still be freed by the non-nothrow forms of 319 <function>operator delete</function>. 320 </para> 321 <para> 322 If the default versions of <function>operator new(std::size_t)</function> 323 and <function>operator new(size_t, std::align_val_t)</function> 324 can't allocate the memory requested, they usually throw an exception 325 object of type <classname>std::bad_alloc</classname> (or some class 326 derived from that). However, the program can influence that behavior 327 by registering a <quote>new-handler</quote>, because what 328 <function>operator new</function> actually does is something like: 329 </para> 330 <programlisting> 331 while (true) 332 { 333 if (void* p = /* try to allocate memory */) 334 return p; 335 else if (std::new_handler h = std::get_new_handler ()) 336 h (); 337 else 338 throw bad_alloc{}; 339 } 340 </programlisting> 341 <para> 342 This means you can influence what happens on allocation failure by 343 writing your own new-handler and then registering it with 344 <function>std::set_new_handler</function>: 345 </para> 346 <programlisting> 347 typedef void (*PFV)(); 348 349 static char* safety; 350 static PFV old_handler; 351 352 void my_new_handler () 353 { 354 delete[] safety; 355 safety = nullptr; 356 popup_window ("Dude, you are running low on heap memory. You" 357 " should, like, close some windows, or something." 358 " The next time you run out, we're gonna burn!"); 359 set_new_handler (old_handler); 360 return; 361 } 362 363 int main () 364 { 365 safety = new char[500000]; 366 old_handler = set_new_handler (&my_new_handler); 367 ... 368 } 369 </programlisting> 370 371 <section xml:id="std.support.memory.notes" xreflabel="Dynamic Memory Notes"><info><title>Additional Notes</title></info> 372 373 <para> 374 Remember that it is perfectly okay to <function>delete</function> a 375 null pointer! Nothing happens, by definition. That is not the 376 same thing as deleting a pointer twice. 377 </para> 378 <para> 379 <classname>std::bad_alloc</classname> is derived from the base 380 <classname>std::exception</classname> class, 381 see <xref linkend="std.diagnostics.exceptions"/>. 382 </para> 383 </section> 384 385</section> 386 387<section xml:id="std.support.termination" xreflabel="Termination"><info><title>Termination</title></info> 388 <?dbhtml filename="termination.html"?> 389 390 <section xml:id="support.termination.handlers" xreflabel="Termination Handlers"><info><title>Termination Handlers</title></info> 391 392 <para> 393 Not many changes here to 394 <filename class="headerfile"><cstdlib></filename>. 395 You should note that the 396 <function>abort()</function> function does not call the 397 destructors of automatic nor static objects, so if you're 398 depending on those to do cleanup, it isn't going to happen. 399 (The functions registered with <function>atexit()</function> 400 don't get called either, so you can forget about that 401 possibility, too.) 402 </para> 403 <para> 404 The good old <function>exit()</function> function can be a bit 405 funky, too, until you look closer. Basically, three points to 406 remember are: 407 </para> 408 <orderedlist inheritnum="ignore" continuation="restarts"> 409 <listitem> 410 <para> 411 Static objects are destroyed in reverse order of their creation. 412 </para> 413 </listitem> 414 <listitem> 415 <para> 416 Functions registered with <function>atexit()</function> are called in 417 reverse order of registration, once per registration call. 418 (This isn't actually new.) 419 </para> 420 </listitem> 421 <listitem> 422 <para> 423 The previous two actions are <quote>interleaved,</quote> that is, 424 given this pseudocode: 425 </para> 426<programlisting> 427 extern "C or C++" void f1 (); 428 extern "C or C++" void f2 (); 429 430 static Thing obj1; 431 atexit(f1); 432 static Thing obj2; 433 atexit(f2); 434</programlisting> 435 <para> 436 then at a call of <function>exit()</function>, 437 <varname>f2</varname> will be called, then 438 <varname>obj2</varname> will be destroyed, then 439 <varname>f1</varname> will be called, and finally 440 <varname>obj1</varname> will be destroyed. If 441 <varname>f1</varname> or <varname>f2</varname> allow an 442 exception to propagate out of them, Bad Things happen. 443 </para> 444 </listitem> 445 </orderedlist> 446 <para> 447 Note also that <function>atexit()</function> is only required to store 32 448 functions, and the compiler/library might already be using some of 449 those slots. If you think you may run out, we recommend using 450 the <function>xatexit</function>/<function>xexit</function> combination 451 from <literal>libiberty</literal>, which has no such limit. 452 </para> 453 </section> 454 455 <section xml:id="support.termination.verbose" xreflabel="Verbose Terminate Handler"><info><title>Verbose Terminate Handler</title></info> 456 <?dbhtml filename="verbose_termination.html"?> 457 458 <para> 459 If you are having difficulty with uncaught exceptions and want a 460 little bit of help debugging the causes of the core dumps, you can 461 make use of a GNU extension, the verbose terminate handler. 462 </para> 463 464 <para> 465 The verbose terminate handler is only available for hosted environments 466 (see <xref linkend="manual.intro.setup.configure"/>) and will be used 467 by default unless the library is built with 468 <option>--disable-libstdcxx-verbose</option> 469 or with exceptions disabled. 470 If you need to enable it explicitly you can do so by calling the 471 <function>std::set_terminate</function> function. 472 </para> 473 474<programlisting> 475#include <exception> 476 477int main() 478{ 479 std::set_terminate(__gnu_cxx::__verbose_terminate_handler); 480 ... 481 482 throw <replaceable>anything</replaceable>; 483} 484</programlisting> 485 486 <para> 487 The <function>__verbose_terminate_handler</function> function 488 obtains the name of the current exception, attempts to demangle 489 it, and prints it to <literal>stderr</literal>. 490 If the exception is derived from 491 <classname>std::exception</classname> then the output from 492 <function>what()</function> will be included. 493 </para> 494 495 <para> 496 Any replacement termination function is required to kill the 497 program without returning; this one calls <function>std::abort</function>. 498 </para> 499 500 <para> 501 For example: 502 </para> 503 504<programlisting> 505#include <exception> 506#include <stdexcept> 507 508struct argument_error : public std::runtime_error 509{ 510 argument_error(const std::string& s): std::runtime_error(s) { } 511}; 512 513int main(int argc) 514{ 515 std::set_terminate(__gnu_cxx::__verbose_terminate_handler); 516 if (argc > 5) 517 throw argument_error("argc is greater than 5!"); 518 else 519 throw argc; 520} 521</programlisting> 522 523 <para> 524 With the verbose terminate handler active, this gives: 525 </para> 526 527 <screen> 528 <computeroutput> 529 % ./a.out 530 terminate called after throwing a `int' 531 Aborted 532 % ./a.out f f f f f f f f f f f 533 terminate called after throwing an instance of `argument_error' 534 what(): argc is greater than 5! 535 Aborted 536 </computeroutput> 537 </screen> 538 539 <para> 540 The 'Aborted' line is printed by the shell after the process exits 541 by calling <function>abort()</function>. 542 </para> 543 544 <para> 545 As this is the default termination handler, nothing need be done to 546 use it. To go back to the previous <quote>silent death</quote> 547 method, simply include 548 <filename class="headerfile"><exception></filename> and 549 <filename class="headerfile"><cstdlib></filename>, and call 550 </para> 551 552 <programlisting> 553 std::set_terminate(std::abort); 554 </programlisting> 555 556 <para> 557 After this, all calls to <function>terminate</function> will use 558 <function>abort</function> as the terminate handler. 559 </para> 560 561 <para> 562 Note: the verbose terminate handler will attempt to write to 563 <literal>stderr</literal>. If your application closes 564 <literal>stderr</literal> or redirects it to an inappropriate location, 565 <function>__verbose_terminate_handler</function> will behave in 566 an unspecified manner. 567 </para> 568 569 </section> 570</section> 571 572</chapter> 573