2 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
6 <part id="manual.support" xreflabel="Support">
7 <?dbhtml filename="support.html"?>
20 <title>Support</title>
25 This part deals with the functions called and objects created
26 automatically during the course of a program's existence.
30 While we can't reproduce the contents of the Standard here (you
31 need to get your own copy from your nation's member body; see our
32 homepage for help), we can mention a couple of changes in what
33 kind of support a C++ program gets from the Standard Library.
37 <chapter id="manual.support.types" xreflabel="Types">
39 <sect1 id="manual.support.types.fundamental" xreflabel="Fundamental Types">
40 <title>Fundamental Types</title>
42 C++ has the following builtin types:
90 These fundamental types are always available, without having to
91 include a header file. These types are exactly the same in
96 Specializing parts of the library on these types is prohibited:
101 <sect1 id="manual.support.types.numeric_limits" xreflabel="Numeric Properties">
102 <title>Numeric Properties</title>
106 The header <filename class="headerfile">limits</filename> defines
107 traits classes to give access to various implementation
108 defined-aspects of the fundamental types. The traits classes --
109 fourteen in total -- are all specializations of the template class
110 <classname>numeric_limits</classname>, documented <ulink
111 url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/structstd_1_1numeric__limits.html">here</ulink>
112 and defined as follows:
116 template<typename T>
119 static const bool is_specialized;
120 static T max() throw();
121 static T min() throw();
123 static const int digits;
124 static const int digits10;
125 static const bool is_signed;
126 static const bool is_integer;
127 static const bool is_exact;
128 static const int radix;
129 static T epsilon() throw();
130 static T round_error() throw();
132 static const int min_exponent;
133 static const int min_exponent10;
134 static const int max_exponent;
135 static const int max_exponent10;
137 static const bool has_infinity;
138 static const bool has_quiet_NaN;
139 static const bool has_signaling_NaN;
140 static const float_denorm_style has_denorm;
141 static const bool has_denorm_loss;
142 static T infinity() throw();
143 static T quiet_NaN() throw();
144 static T denorm_min() throw();
146 static const bool is_iec559;
147 static const bool is_bounded;
148 static const bool is_modulo;
150 static const bool traps;
151 static const bool tinyness_before;
152 static const float_round_style round_style;
157 <sect1 id="manual.support.types.null" xreflabel="NULL">
160 The only change that might affect people is the type of
161 <constant>NULL</constant>: while it is required to be a macro,
162 the definition of that macro is <emphasis>not</emphasis> allowed
163 to be <constant>(void*)0</constant>, which is often used in C.
167 For <command>g++</command>, <constant>NULL</constant> is
168 <programlisting>#define</programlisting>'d to be
169 <constant>__null</constant>, a magic keyword extension of
170 <command>g++</command>.
174 The biggest problem of #defining <constant>NULL</constant> to be
175 something like <quote>0L</quote> is that the compiler will view
176 that as a long integer before it views it as a pointer, so
177 overloading won't do what you expect. (This is why
178 <command>g++</command> has a magic extension, so that
179 <constant>NULL</constant> is always a pointer.)
182 <para>In his book <ulink
183 url="http://www.awprofessional.com/titles/0-201-92488-9/"><emphasis>Effective
184 C++</emphasis></ulink>, Scott Meyers points out that the best way
185 to solve this problem is to not overload on pointer-vs-integer
186 types to begin with. He also offers a way to make your own magic
187 <constant>NULL</constant> that will match pointers before it
191 <ulink url="http://www.awprofessional.com/titles/0-201-31015-5/">the
192 Effective C++ CD example</ulink>
198 <chapter id="manual.support.memory" xreflabel="Dynamic Memory">
199 <title>Dynamic Memory</title>
201 There are six flavors each of <function>new</function> and
202 <function>delete</function>, so make certain that you're using the right
203 ones. Here are quickie descriptions of <function>new</function>:
207 single object form, throwing a
208 <classname>bad_alloc</classname> on errors; this is what most
209 people are used to using
212 Single object "nothrow" form, returning NULL on errors
215 Array <function>new</function>, throwing
216 <classname>bad_alloc</classname> on errors
219 Array nothrow <function>new</function>, returning
220 <constant>NULL</constant> on errors
223 Placement <function>new</function>, which does nothing (like
227 Placement array <function>new</function>, which also does
232 They are distinguished by the parameters that you pass to them, like
233 any other overloaded function. The six flavors of <function>delete</function>
234 are distinguished the same way, but none of them are allowed to throw
235 an exception under any circumstances anyhow. (They match up for
239 Remember that it is perfectly okay to call <function>delete</function> on a
240 NULL pointer! Nothing happens, by definition. That is not the
241 same thing as deleting a pointer twice.
244 By default, if one of the <quote>throwing <function>new</function>s</quote> can't
245 allocate the memory requested, it tosses an instance of a
246 <classname>bad_alloc</classname> exception (or, technically, some class derived
247 from it). You can change this by writing your own function (called a
248 new-handler) and then registering it with <function>set_new_handler()</function>:
251 typedef void (*PFV)(void);
254 static PFV old_handler;
256 void my_new_handler ()
259 popup_window ("Dude, you are running low on heap memory. You
260 should, like, close some windows, or something.
261 The next time you run out, we're gonna burn!");
262 set_new_handler (old_handler);
268 safety = new char[500000];
269 old_handler = set_new_handler (&my_new_handler);
274 <classname>bad_alloc</classname> is derived from the base <classname>exception</classname>
275 class defined in Chapter 19.
279 <chapter id="manual.support.termination" xreflabel="Termination">
280 <title>Termination</title>
281 <sect1 id="support.termination.handlers" xreflabel="Termination Handlers">
282 <title>Termination Handlers</title>
284 Not many changes here to <filename
285 class="headerfile">cstdlib</filename>. You should note that the
286 <function>abort()</function> function does not call the
287 destructors of automatic nor static objects, so if you're
288 depending on those to do cleanup, it isn't going to happen.
289 (The functions registered with <function>atexit()</function>
290 don't get called either, so you can forget about that
294 The good old <function>exit()</function> function can be a bit
295 funky, too, until you look closer. Basically, three points to
301 Static objects are destroyed in reverse order of their creation.
306 Functions registered with <function>atexit()</function> are called in
307 reverse order of registration, once per registration call.
308 (This isn't actually new.)
313 The previous two actions are <quote>interleaved,</quote> that is,
314 given this pseudocode:
317 extern "C or C++" void f1 (void);
318 extern "C or C++" void f2 (void);
326 then at a call of <function>exit()</function>,
327 <varname>f2</varname> will be called, then
328 <varname>obj2</varname> will be destroyed, then
329 <varname>f1</varname> will be called, and finally
330 <varname>obj1</varname> will be destroyed. If
331 <varname>f1</varname> or <varname>f2</varname> allow an
332 exception to propagate out of them, Bad Things happen.
337 Note also that <function>atexit()</function> is only required to store 32
338 functions, and the compiler/library might already be using some of
339 those slots. If you think you may run out, we recommend using
340 the <function>xatexit</function>/<function>xexit</function> combination from <literal>libiberty</literal>, which has no such limit.
344 <sect1 id="support.termination.verbose" xreflabel="Verbose Terminate Handler">
345 <title>Verbose Terminate Handler</title>
347 If you are having difficulty with uncaught exceptions and want a
348 little bit of help debugging the causes of the core dumps, you can
349 make use of a GNU extension, the verbose terminate handler.
353 #include <exception>
357 std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
360 throw <replaceable>anything</replaceable>;
365 The <function>__verbose_terminate_handler</function> function
366 obtains the name of the current exception, attempts to demangle
367 it, and prints it to stderr. If the exception is derived from
368 <classname>exception</classname> then the output from
369 <function>what()</function> will be included.
373 Any replacement termination function is required to kill the
374 program without returning; this one calls abort.
382 #include <exception>
383 #include <stdexcept>
385 struct argument_error : public std::runtime_error
387 argument_error(const std::string& s): std::runtime_error(s) { }
392 std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
394 throw argument_error(<quote>argc is greater than 5!</quote>);
401 With the verbose terminate handler active, this gives:
407 terminate called after throwing a `int'
409 % ./a.out f f f f f f f f f f f
410 terminate called after throwing an instance of `argument_error'
411 what(): argc is greater than 5!
417 The 'Aborted' line comes from the call to
418 <function>abort()</function>, of course.
422 This is the default termination handler; nothing need be done to
423 use it. To go back to the previous <quote>silent death</quote>
424 method, simply include <filename>exception</filename> and
425 <filename>cstdlib</filename>, and call
429 std::set_terminate(std::abort);
433 After this, all calls to <function>terminate</function> will use
434 <function>abort</function> as the terminate handler.
438 Note: the verbose terminate handler will attempt to write to
439 stderr. If your application closes stderr or redirects it to an
440 inappropriate location,
441 <function>__verbose_terminate_handler</function> will behave in
442 an unspecified manner.