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