diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index ec0c5887b199..179b742289ad 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,13 @@ +2002-04-01 Phil Edwards + + * 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 * config/linker-map.gnu: Export __verbose_terminate_handler. diff --git a/libstdc++-v3/docs/doxygen/doxygroups.cc b/libstdc++-v3/docs/doxygen/doxygroups.cc index c6139f375478..da71879e8e5b 100644 --- a/libstdc++-v3/docs/doxygen/doxygroups.cc +++ b/libstdc++-v3/docs/doxygen/doxygroups.cc @@ -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 , which notes, + * "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." +*/ + +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 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: diff --git a/libstdc++-v3/docs/doxygen/mainpage.html b/libstdc++-v3/docs/doxygen/mainpage.html index 431344b972e3..ecfa6490782e 100644 --- a/libstdc++-v3/docs/doxygen/mainpage.html +++ b/libstdc++-v3/docs/doxygen/mainpage.html @@ -25,7 +25,7 @@

Documentation Overview

-

Generated 2002-03-27.

+

@LEVEL@-level docs, generated @DATE@.

There are two types of documentation for libstdc++-v3. One is the distribution documentation, which can be read online at @@ -35,7 +35,14 @@

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. +

+ +

Here are quick links to the pages which we seem to use the most; a full index is at the bottom:

@@ -255,6 +256,68 @@ to the FAQ.

+
+

RTTI, the ABI, and demangling

+

If you have read the source + documentation for namespace abi 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 + c++filt, and you can use it yourself as well. +

+

(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.) +

+

Probably the only times you'll be interested in demangling at runtime + are when you're seeing typeid strings in RTTI, or when + you're handling the runtime-support exception classes. For example: + 

+#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;
+}

+

With GCC 3.1 and later, this prints

+      St13bad_exception       => std::bad_exception   : 0
+      3barI5emptyLi17EE       => bar<empty, 17>       : 0
+

+

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.) +

+

Return to top of page or + to the FAQ. +

diff --git a/libstdc++-v3/libsupc++/exception b/libstdc++-v3/libsupc++/exception index 45b98f26eb3f..b26cb6d887f1 100644 --- a/libstdc++-v3/libsupc++/exception +++ b/libstdc++-v3/libsupc++/exception @@ -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