exception (__verbose_terminate_handler): Point to docs.
2002-04-01 Phil Edwards <pme@gcc.gnu.org> * libsupc++/exception (__verbose_terminate_handler): Point to docs. * docs/doxygen/doxygroups.cc: Doxygen hooks for abi::__cxa_demangle. * docs/html/18_support/howto.html: Document the demangler. * docs/html/17_intro/howto.html: And link to it. * docs/doxygen/mainpage.html: Describe user-vs-maintainer docs. * docs/doxygen/run_doxygen: Print user-vs-maintainer. From-SVN: r51730
This commit is contained in:
Phil Edwards
parent
b88a94c603
commit
efe44c60eb
7 changed files with 167 additions and 10 deletions
|
|
@ -1,3 +1,13 @@
|
|||
2002-04-01 Phil Edwards <pme@gcc.gnu.org>
|
||||
|
||||
* libsupc++/exception (__verbose_terminate_handler): Point to docs.
|
||||
* docs/doxygen/doxygroups.cc: Doxygen hooks for abi::__cxa_demangle.
|
||||
* docs/html/18_support/howto.html: Document the demangler.
|
||||
* docs/html/17_intro/howto.html: And link to it.
|
||||
|
||||
* docs/doxygen/mainpage.html: Describe user-vs-maintainer docs.
|
||||
* docs/doxygen/run_doxygen: Print user-vs-maintainer.
|
||||
|
||||
2002-04-01 Phil Edwards <pme@gcc.gnu.org>
|
||||
|
||||
* config/linker-map.gnu: Export __verbose_terminate_handler.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,3 @@
|
|||
|
||||
/*
|
||||
Copyright (C) 2001, 2002 Free Software Foundation, Inc.
|
||||
See license.html for license.
|
||||
|
|
@ -7,6 +6,11 @@
|
|||
source headers themselves. It is a ".cc" file for the sole cheesy reason
|
||||
that it triggers many different text editors into doing Nice Things when
|
||||
typing comments. However, it is mentioned nowhere except the *cfg.in files.
|
||||
|
||||
Some actual code (declarations) is exposed here, but no compiler ever
|
||||
sees it. The decls must be visible to doxygen, and sometimes their real
|
||||
declarations are not visible, or not visible in a way we want.
|
||||
|
||||
Pieces separated by '// //' lines will usually not be presented to the
|
||||
user on the same page.
|
||||
*/
|
||||
|
|
@ -112,4 +116,69 @@ All associative containers must meet certain requirements, summarized in
|
|||
*/
|
||||
|
||||
// // // // // // // // // // // // // // // // // // // // // // // //
|
||||
/** @namespace abi
|
||||
* @brief The cross-vendor C++ Application Binary Interface.
|
||||
*
|
||||
* A brief overview of an ABI is given in the libstdc++-v3 FAQ, question
|
||||
* 5.8 (you may have a copy of the FAQ locally, or you can view the online
|
||||
* version at http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#5_8).
|
||||
*
|
||||
* GCC subscribes to a relatively-new cross-vendor ABI for C++, sometimes
|
||||
* called the IA64 ABI because it happens to be the native ABI for that
|
||||
* platform. It is summarized at http://www.codesourcery.com/cxx-abi/
|
||||
* along with the current specification.
|
||||
*
|
||||
* For users of GCC 3.x, entry points are available in <cxxabi.h>, which notes,
|
||||
* <em>"It is not normally necessary for user programs to include this header,
|
||||
* or use the entry points directly. However, this header is available
|
||||
* should that be needed."</em>
|
||||
*/
|
||||
|
||||
namespace abi {
|
||||
/**
|
||||
@brief New ABI-mandated entry point in the C++ runtime library for demangling.
|
||||
|
||||
@param mangled_name A NUL-terminated character string containing the name
|
||||
to be demangled.
|
||||
|
||||
@param output_buffer A region of memory, allocated with malloc, of
|
||||
@a *length bytes, into which the demangled name
|
||||
is stored. If @a output_buffer is not long enough,
|
||||
it is expanded using realloc. @a output_buffer may
|
||||
instead be NULL; in that case, the demangled name is
|
||||
placed in a region of memory allocated with malloc.
|
||||
|
||||
@param length If @a length is non-NULL, the length of the buffer containing
|
||||
the demangled name is placed in @a *length.
|
||||
|
||||
@param status @a *status is set to one of the following values:
|
||||
- 0: The demangling operation succeeded.
|
||||
- -1: A memory allocation failiure occurred.
|
||||
- -2: @a mangled_name is not a valid name under the C++ ABI
|
||||
mangling rules.
|
||||
- -3: One of the arguments is invalid.
|
||||
|
||||
@return A pointer to the start of the NUL-terminated demangled name, or NULL
|
||||
if the demangling fails. The caller is responsible for deallocating
|
||||
this memory using @c free.
|
||||
|
||||
|
||||
The demagling is performed using the C++ ABI mangling rules, with
|
||||
GNU extensions. For example, this function is used
|
||||
in __gnu_cxx::__verbose_terminate_handler. See
|
||||
http://gcc.gnu.org/onlinedocs/libstdc++/18_support/howto.html#5 for other
|
||||
examples of use.
|
||||
|
||||
@note The same demangling functionality is available via libiberty
|
||||
(@c <libiberty/demangle.h> and @c libiberty.a) in GCC 3.1 and later, but that
|
||||
requires explicit installation (@c --enable-install-libiberty) and uses a
|
||||
different API, although the ABI is unchanged.
|
||||
*/
|
||||
char* __cxa_demangle (const char* mangled_name, char* output_buffer,
|
||||
size_t* length, int* status);
|
||||
} // namespace abi
|
||||
|
||||
// // // // // // // // // // // // // // // // // // // // // // // //
|
||||
|
||||
// vim:et:noai:
|
||||
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@
|
|||
|
||||
<h2> Documentation Overview </h2>
|
||||
|
||||
<p class="smallertext">Generated 2002-03-27.</p>
|
||||
<p class="smallertext">@LEVEL@-level docs, generated @DATE@.</p>
|
||||
|
||||
<p>There are two types of documentation for libstdc++-v3. One is the
|
||||
distribution documentation, which can be read online at
|
||||
|
|
@ -35,7 +35,14 @@
|
|||
</p>
|
||||
|
||||
<p>The other type is the source documentation, of which this is the first page.
|
||||
Here are quick links to the pages which we seem to use the most; a full
|
||||
Both "user-level" and "maintainer-level" source
|
||||
documentation is produced: user-level docs are for the users of this
|
||||
library. The maint-level docs are for those interested in the underlying
|
||||
workings of the library; they include all the user-level docs plus
|
||||
additional notes and additional classes/functions/etc.
|
||||
</p>
|
||||
|
||||
<p>Here are quick links to the pages which we seem to use the most; a full
|
||||
index is at the bottom:
|
||||
<!-- Keep this in sync with below. -->
|
||||
<ul>
|
||||
|
|
@ -48,10 +55,10 @@
|
|||
|
||||
<h2> Generating this file </h2>
|
||||
<p>These HTML pages are automatically generated, along with the man pages.
|
||||
The Makefile rule <code> 'make
|
||||
doxygen' </code> in the libstdc++-v3 build directory generates these pages
|
||||
using a tool called, appropriately enough, Doxygen. To learn more about
|
||||
Doxygen, take a look at
|
||||
The Makefile rules <code> 'make doxygen' </code> and
|
||||
<code> 'make doxygen-maint' </code> in the libstdc++-v3 build directory
|
||||
generates these pages using a tool called, appropriately enough, Doxygen.
|
||||
To learn more about Doxygen, take a look at
|
||||
<a href="http://www.doxygen.org/">
|
||||
<!-- snagged from the generated page -->
|
||||
<img src="doxygen.gif" alt="the Doxygen homepage"
|
||||
|
|
|
|||
|
|
@ -95,6 +95,7 @@ outdir=unset
|
|||
do_html=no
|
||||
do_man=no
|
||||
enabled_sections=
|
||||
DATEtext=`date '+%Y-%m-%d'`
|
||||
|
||||
parse_options $*
|
||||
find_doxygen
|
||||
|
|
@ -107,9 +108,11 @@ fi
|
|||
|
||||
case x"$mode" in
|
||||
xuser) do_html=yes
|
||||
LEVELtext='User'
|
||||
;;
|
||||
xmaint) do_html=yes
|
||||
enabled_sections=maint
|
||||
LEVELtext='Maintainer'
|
||||
;;
|
||||
xman) do_man=yes
|
||||
;;
|
||||
|
|
@ -147,7 +150,9 @@ set -e
|
|||
set +e
|
||||
|
||||
test $do_html = yes && {
|
||||
cp ${srcdir}/docs/doxygen/mainpage.html ${outdir}/html_${mode}/index.html
|
||||
sed -e "s=@LEVEL@=${LEVELtext}=" \
|
||||
-e "s=@DATE@=${DATEtext}=" \
|
||||
${srcdir}/docs/doxygen/mainpage.html > ${outdir}/html_${mode}/index.html
|
||||
cp ${srcdir}/docs/doxygen/tables.html ${outdir}/html_${mode}/tables.html
|
||||
echo ::
|
||||
echo :: HTML pages begin with
|
||||
|
|
|
|||
|
|
@ -205,7 +205,8 @@
|
|||
classes publicly derived from it, simply returns the name of the
|
||||
class. But they are the <em>mangled</em> names; you will need to call
|
||||
<code>c++filt</code> and pass the names as command-line parameters to
|
||||
demangle them.
|
||||
demangle them, or call a
|
||||
<a href="../18_support/howto.html#5">runtime demangler function</a>.
|
||||
(The classes in <code><stdexcept></code> have constructors which
|
||||
require an argument to use later for <code>what()</code> calls, so the
|
||||
question does not arise in most user-defined exceptions.)
|
||||
|
|
|
|||
|
|
@ -31,6 +31,7 @@
|
|||
<li><a href="#2">Implementation properties</a>
|
||||
<li><a href="#3">Start and Termination</a>
|
||||
<li><a href="#4">Dynamic memory management</a>
|
||||
<li><a href="#5">RTTI, the ABI, and demangling</a>
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
|
|
@ -255,6 +256,68 @@
|
|||
<a href="../faq/index.html">to the FAQ</a>.
|
||||
</p>
|
||||
|
||||
<hr>
|
||||
<h2><a name="5">RTTI, the ABI, and demangling</a></h2>
|
||||
<p>If you have read the <a href="../documentation.html#4">source
|
||||
documentation</a> for <code> namespace abi </code> then you are aware
|
||||
of the cross-vendor C++ ABI which we use. One of the exposed
|
||||
functions is the one which we use for demangling in programs like
|
||||
<code>c++filt</code>, and you can use it yourself as well.
|
||||
</p>
|
||||
<p>(The function itself might use different demanglers, but that's the
|
||||
whole point of abstract interfaces. If we change the implementation,
|
||||
you won't notice.)
|
||||
</p>
|
||||
<p>Probably the only times you'll be interested in demangling at runtime
|
||||
are when you're seeing <code>typeid</code> strings in RTTI, or when
|
||||
you're handling the runtime-support exception classes. For example:
|
||||
<pre>
|
||||
#include <exception>
|
||||
#include <iostream>
|
||||
#include <cxxabi.h>
|
||||
|
||||
struct empty { };
|
||||
|
||||
template <typename T, int N>
|
||||
struct bar { };
|
||||
|
||||
|
||||
int main()
|
||||
{
|
||||
int status;
|
||||
char *realname;
|
||||
|
||||
// exception classes not in <stdexcept>, thrown by the implementation
|
||||
// instead of the user
|
||||
std::bad_exception e;
|
||||
realname = abi::__cxa_demangle(e.what(), 0, 0, &status);
|
||||
std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n';
|
||||
free(realname);
|
||||
|
||||
|
||||
// typeid
|
||||
bar<empty,17> u;
|
||||
const std::type_info &ti = typeid(u);
|
||||
|
||||
realname = abi::__cxa_demangle(ti.name(), 0, 0, &status);
|
||||
std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n';
|
||||
free(realname);
|
||||
|
||||
return 0;
|
||||
}</pre></p>
|
||||
<p>With GCC 3.1 and later, this prints<pre>
|
||||
St13bad_exception => std::bad_exception : 0
|
||||
3barI5emptyLi17EE => bar<empty, 17> : 0</pre>
|
||||
</p>
|
||||
<p>The demangler interface is described in the source documentation
|
||||
linked to above. It is actually written in C, so you don't need to
|
||||
be writing C++ in order to demangle C++. (That also means we have to
|
||||
use crummy memory management facilities, so don't forget to free()
|
||||
the returned char array.)
|
||||
</p>
|
||||
<p>Return <a href="#top">to top of page</a> or
|
||||
<a href="../faq/index.html">to the FAQ</a>.
|
||||
</p>
|
||||
|
||||
|
||||
<!-- ####################################################### -->
|
||||
|
|
|
|||
|
|
@ -105,7 +105,9 @@ namespace __gnu_cxx
|
|||
@code
|
||||
std::set_terminate (__gnu_cxx::__verbose_terminate_handler)
|
||||
@endcode
|
||||
to use. */
|
||||
to use. For more info, see
|
||||
http://gcc.gnu.org/onlinedocs/libstdc++/19_diagnostics/howto.html#4
|
||||
*/
|
||||
void __verbose_terminate_handler ();
|
||||
} // namespace __gnu_cxx
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue