This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
[libstdc++] Doc new demangler functionality
- From: Phil Edwards <phil at jaj dot com>
- To: libstdc++ at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Date: Mon, 1 Apr 2002 21:10:01 -0500
- Subject: [libstdc++] Doc new demangler functionality
This adds example documentation for how to use __cxa_demangle; trunk
and branch. It also makes clear, when reading the doxygen'd pages,
which collection one is viewing, which is something I've been meaning to
do forever.
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.
Index: libsupc++/exception
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/libsupc++/exception,v
retrieving revision 1.12
diff -u -3 -p -r1.12 exception
--- exception 2002/01/28 22:13:11 1.12
+++ exception 2002/04/02 02:04:17
@@ -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
Index: docs/doxygen/doxygroups.cc
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/doxygroups.cc,v
retrieving revision 1.8
diff -u -3 -p -r1.8 doxygroups.cc
--- doxygroups.cc 2002/03/27 21:41:30 1.8
+++ doxygroups.cc 2002/04/02 02:04:17
@@ -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 cer
*/
// // // // // // // // // // // // // // // // // // // // // // // //
+/** @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:
Index: docs/doxygen/mainpage.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/mainpage.html,v
retrieving revision 1.3
diff -u -3 -p -r1.3 mainpage.html
--- mainpage.html 2002/03/27 21:41:30 1.3
+++ mainpage.html 2002/04/02 02:04:17
@@ -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"
Index: docs/doxygen/run_doxygen
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/run_doxygen,v
retrieving revision 1.14
diff -u -3 -p -r1.14 run_doxygen
--- run_doxygen 2002/03/27 21:41:30 1.14
+++ run_doxygen 2002/04/02 02:04:17
@@ -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
Index: docs/html/17_intro/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/howto.html,v
retrieving revision 1.21
diff -u -3 -p -r1.21 howto.html
--- howto.html 2002/03/06 21:22:46 1.21
+++ howto.html 2002/04/02 02:04:17
@@ -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.)
Index: docs/html/18_support/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/18_support/howto.html,v
retrieving revision 1.11
diff -u -3 -p -r1.11 howto.html
--- howto.html 2001/11/23 16:29:00 1.11
+++ howto.html 2002/04/02 02:04:17
@@ -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>
<!-- ####################################################### -->