From 0aeadebf36eab6d537b67b38c5dcacf648f2f69f Mon Sep 17 00:00:00 2001 From: bkoz Date: Fri, 18 Jan 2008 08:16:51 +0000 Subject: 2008-01-18 Benjamin Kosnik * docs/*: To... * doc/*: ...here. * testsuite/Makefile.am: Move doc-performance to... * Makefile.am: Add doc to SUBDIRS, move doxygen-* rules to... * doc/Makefile.am: Consolidate documentation creation here. (doc-doxygen-html): New. (doc-doxygen-man): New. (doc-performance): New. * doc/Makefile.in: New. * acinclude.m4 (glibcxx_SUBDIRS): Add doc directory. * doc/doxygen/guide.html: Edit for unified html configuration. * doc/doxygen/mainpage.html: Same. * doc/doxygen/run_doxygen: Same, more namespace fixups for man generation. * doc/doxygen/user.cfg.in: Update for doxygen 1.5.4. * include/tr1_impl/random: Remove maint from doxygen markup. * include/tr1_impl/functional: Same. * include/std/tuple: Same. * include/std/streambuf: Same. * include/std/bitset: Same. * include/std/limits: Same. * include/std/fstream: Same. * include/std/istream: Same. * include/std/sstream: Same. * include/ext/pool_allocator.h: Same. * include/ext/rc_string_base.h: Same. * include/bits/basic_ios.h: Same. * include/bits/stl_list.h: Same. * include/bits/stl_map.h: Same. * include/bits/locale_classes.h: Same. * include/bits/stl_set.h: Same. * include/bits/stl_iterator_base_types.h: Same. * include/bits/basic_string.h: Same. * include/bits/stl_multimap.h: Same. * include/bits/stl_vector.h: Same. * include/bits/ios_base.h: Same. * include/bits/stl_deque.h: Same. * include/bits/postypes.h: Same. * include/bits/stl_multiset.h: Same. * include/bits/stl_algo.h: Same. * include/bits/stl_iterator.h: Same. * include/bits/stl_tempbuf.h: Same. * include/bits/stl_construct.h: Same. * include/bits/stl_relops.h: Same. * include/tr1/tuple: Same. * include/backward/auto_ptr.h: Same. * testsuite/23_containers/vector/requirements/dr438/assign_neg.cc: Fixups for line number changes. * testsuite/23_containers/vector/requirements/dr438/insert_neg.cc: Same. * testsuite/23_containers/vector/requirements/dr438/ constructor_1_neg.cc: Same. * testsuite/23_containers/vector/requirements/dr438/ constructor_2_neg.cc: Same. * testsuite/23_containers/deque/requirements/dr438/assign_neg.cc: Same. * testsuite/23_containers/deque/requirements/dr438/insert_neg.cc: Same. * testsuite/23_containers/deque/requirements/dr438/ constructor_1_neg.cc: Same. * testsuite/23_containers/deque/requirements/dr438/ constructor_2_neg.cc: Same. * testsuite/23_containers/list/requirements/dr438/assign_neg.cc: Same. * testsuite/23_containers/list/requirements/dr438/insert_neg.cc: Same. * testsuite/23_containers/list/requirements/dr438/ constructor_1_neg.cc: Same. * testsuite/23_containers/list/requirements/dr438/ constructor_2_neg.cc: Same. * testsuite/20_util/auto_ptr/assign_neg.cc: Same. * aclocal.m4: Regenerate. * config.h.in: Regenerate. * configure: Regenerate. * Makefile.in: Regenerate. * src/Makefile.in: Regenerate. * po/Makefile.in: Regenerate. * libmath/Makefile.in: Regenerate. * include/Makefile.in: Regenerate. * libsupc++/Makefile.in: Regenerate. * testsuite/Makefile.in: Regenerate. * scripts/make_graphs.py: Correct paths for new layout. 2008-01-17 Benjamin Kosnik * acinclude.m4 (AC_LC_MESSAGES): Remove serial. * linkage.m4 (AC_REPLACE_MATHFUNCS): Same. * configure: Regenerate. * aclocal.m4: Regenerate. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@131625 138bc75d-0d04-0410-961f-82ee72b054a4 --- libstdc++-v3/doc/html/debug.html | 474 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 474 insertions(+) create mode 100644 libstdc++-v3/doc/html/debug.html (limited to 'libstdc++-v3/doc/html/debug.html') diff --git a/libstdc++-v3/doc/html/debug.html b/libstdc++-v3/doc/html/debug.html new file mode 100644 index 00000000000..61c6a8ba17b --- /dev/null +++ b/libstdc++-v3/doc/html/debug.html @@ -0,0 +1,474 @@ + + + + + + + + + + Debugging schemes and strategies + + + + + +

Debugging schemes and strategies

+ +

+ The latest version of this document is always available at + + http://gcc.gnu.org/onlinedocs/libstdc++/debug.html. +

+ +

+ To the libstdc++ homepage. +

+ + +
+

There are numerous things that can be done to improve the ease with + which C++ binaries are debugged when using the GNU + tool chain. Here are some of them. +

+ +

Compiler flags determine debug info

+

The default optimizations and debug flags for a libstdc++ build are + -g -O2. However, both debug and optimization flags can + be varied to change debugging characteristics. For instance, + turning off all optimization via the -g -O0 flag will + disable inlining, so that stepping through all functions, including + inlined constructors and destructors, is possible. In addition, + -fno-eliminate-unused-debug-types can be used when + additional debug information, such as nested class info, is desired. +

+ +

Or, the debug format that the compiler and debugger use to communicate + information about source constructs can be changed via + -gdwarf-2 or -gstabs flags: some debugging + formats permit more expressive type and scope information to be + shown in gdb. The default debug information for a particular + platform can be identified via the value set by the + PREFERRED_DEBUGGING_TYPE macro in the gcc sources. +

+ +

Many other options are available: please see +"Options for Debugging Your Program" + in Using the GNU Compiler Collection (GCC) for a complete list. +

+ +

Using special flags to make a debug binary

+

If you would like debug symbols in libstdc++, there are two ways to + build libstdc++ with debug flags. The first is to run make from the + toplevel in a freshly-configured tree with +

+
+     --enable-libstdcxx-debug
+
+

and perhaps

+
+     --enable-libstdcxx-debug-flags='...'
+
+

to create a separate debug build. Both the normal build and the + debug build will persist, without having to specify + CXXFLAGS, and the debug library will be installed in a + separate directory tree, in (prefix)/lib/debug. For + more information, look at the configuration + options document. +

+ +

A second approach is to use the configuration flags +

+
+     make CXXFLAGS='-g3 -O0' all
+
+ +

This quick and dirty approach is often sufficient for quick + debugging tasks, when you cannot or don't want to recompile your + application to use the debug mode.

+ +

The libstdc++ debug mode

+

By default, libstdc++ is built with efficiency in mind, and + therefore performs little or no error checking that is not required + by the C++ standard. This means that programs that incorrectly use + the C++ standard library will exhibit behavior that is not portable + and may not even be predictable, because they tread into + implementation-specific or undefined behavior. To detect some of + these errors before they can become problematic, libstdc++ offers a + debug mode that provides additional checking of library facilities, + and will report errors in the use of libstdc++ as soon as they can + be detected by emitting a description of the problem to standard + error and aborting the program. This debug mode is available with + GCC 3.4.0 and later versions.

+ +

The libstdc++ debug mode performs checking for many areas of the C++ + standard, but the focus is on checking interactions among standard + iterators, containers, and algorithms, including:

+ +
    +
  • Safe iterators: Iterators keep track of the + container whose elements they reference, so errors such as + incrementing a past-the-end iterator or dereferencing an iterator + that points to a container that has been destructed are diagnosed + immediately.
    • + +
  • Algorithm preconditions: Algorithms attempt to + validate their input parameters to detect errors as early as + possible. For instance, the set_intersection + algorithm requires that its iterator + parameters first1 and last1 form a valid + iterator range, and that the sequence + [first1, last1) is sorted according to + the same predicate that was passed + to set_intersection; the libstdc++ debug mode will + detect an error if the sequence is not sorted or was sorted by a + different predicate.
    • +
+ +

Using the libstdc++ debug mode

+

To use the libstdc++ debug mode, compile your application with the + compiler flag -D_GLIBCXX_DEBUG. Note that this flag + changes the sizes and behavior of standard class templates such + as std::vector, and therefore you can only link code + compiled with debug mode and code compiled without debug mode if no + instantiation of a container is passed between the two translation + units.

+ +

By default, error messages are formatted to fit on lines of about + 78 characters. The environment variable + GLIBCXX_DEBUG_MESSAGE_LENGTH can be used to request a + different length.

+ +

For information about the design of the libstdc++ debug mode, + please see the libstdc++ debug mode design + document.

+ +

Using the debugging containers without debug + mode

+

When it is not feasible to recompile your entire application, or + only specific containers need checking, debugging containers are + available as GNU extensions. These debugging containers are + functionally equivalent to the standard drop-in containers used in + debug mode, but they are available in a separate namespace as GNU + extensions and may be used in programs compiled with either release + mode or with debug mode. The + following table provides the names and headers of the debugging + containers: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ContainerHeaderDebug containerDebug header
std::bitset<bitset>__gnu_debug::bitset<debug/bitset>
std::deque<deque>__gnu_debug::deque<debug/deque>
std::list<list>__gnu_debug::list<debug/list>
std::map<map>__gnu_debug::map<debug/map>
std::multimap<map>__gnu_debug::multimap<debug/map>
std::multiset<set>__gnu_debug::multiset<debug/set>
std::set<set>__gnu_debug::set<debug/set>
std::string<string>__gnu_debug::string<debug/string>
std::wstring<string>__gnu_debug::wstring<debug/string>
std::basic_string<string>__gnu_debug::basic_string<debug/string>
std::vector<vector>__gnu_debug::vector<debug/vector>
+ +

In addition, when compiling in C++0x mode, these additional +containers have additional debug capability. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
std::unordered_map<unordered_map>__gnu_debug::unordered_map<debug/unordered_map>
std::unordered_multimap<unordered_map>__gnu_debug::unordered_multimap<debug/unordered_map>
std::unordered_set<unordered_set>__gnu_debug::unordered_set<debug/unordered_set>
std::unordered_multiset<unordered_set>__gnu_debug::unordered_multiset<debug/unordered_set>
+ +

Debug mode semantics

+

A program that uses the C++ standard library correctly + will maintain the same semantics under debug mode as it had with + the normal (release) library. All functional and exception-handling + guarantees made by the normal library also hold for the debug mode + library, with one exception: performance guarantees made by the + normal library may not hold in the debug mode library. For + instance, erasing an element in a std::list is a + constant-time operation in normal library, but in debug mode it is + linear in the number of iterators that reference that particular + list. So while your (correct) program won't change its results, it + is likely to execute more slowly.

+ +

libstdc++ includes many extensions to the C++ standard library. In + some cases the extensions are obvious, such as the hashed + associative containers, whereas other extensions give predictable + results to behavior that would otherwise be undefined, such as + throwing an exception when a std::basic_string is + constructed from a NULL character pointer. This latter category also + includes implementation-defined and unspecified semantics, such as + the growth rate of a vector. Use of these extensions is not + considered incorrect, so code that relies on them will not be + rejected by debug mode. However, use of these extensions may affect + the portability of code to other implementations of the C++ standard + library, and is therefore somewhat hazardous. For this reason, the + libstdc++ debug mode offers a "pedantic" mode (similar to + GCC's -pedantic compiler flag) that attempts to emulate + the semantics guaranteed by the C++ standard. For + instance, constructing a std::basic_string with a NULL + character pointer would result in an exception under normal mode or + non-pedantic debug mode (this is a libstdc++ extension), whereas + under pedantic debug mode libstdc++ would signal an error. To enable + the pedantic debug mode, compile your program with + both -D_GLIBCXX_DEBUG + and -D_GLIBCXX_DEBUG_PEDANTIC . + (N.B. In GCC 3.4.x and 4.0.0, due to a bug, + -D_GLIBXX_DEBUG_PEDANTIC was also needed. The problem has + been fixed in GCC 4.0.1 and later versions.)

+ +

The following library components provide extra debugging + capabilities in debug mode:

+
    +
  • std::basic_string (no safe iterators and see note below)
    • +
  • std::bitset
    • +
  • std::deque
    • +
  • std::list
    • +
  • std::map
    • +
  • std::multimap
    • +
  • std::multiset
    • +
  • std::set
    • +
  • std::vector
    • +
  • std::unordered_map
    • +
  • std::unordered_multimap
    • +
  • std::unordered_set
    • +
  • std::unordered_multiset
    • +
+ +

N.B. although there are precondition checks for some string operations, +e.g. operator[], +they will not always be run when using the char and +wchar_t specialisations (std::string and +std::wstring). This is because libstdc++ uses GCC's +extern template extension to provide explicit instantiations +of std::string and std::wstring, and those +explicit instantiations don't include the debug-mode checks. If the +containing functions are inlined then the checks will run, so compiling +with -O1 might be enough to enable them. Alternatively +-D_GLIBCXX_EXTERN_TEMPLATE=0 will suppress the declarations +of the explicit instantiations and cause the functions to be instantiated +with the debug-mode checks included, but this is unsupported and not +guaranteed to work. For full debug-mode support you can use the +__gnu_debug::basic_string debugging container directly, +which always works correctly. +

+ +

Tips for memory leak hunting

+ +

There are various third party memory tracing and debug utilities + that can be used to provide detailed memory allocation information + about C++ code. An exhaustive list of tools is not going to be + attempted, but includes mtrace, valgrind, + mudflap, and the non-free commercial product + purify. In addition, libcwd has a + replacement for the global new and delete operators that can track + memory allocation and deallocation and provide useful memory + statistics. +

+ +

Regardless of the memory debugging tool being used, there is one + thing of great importance to keep in mind when debugging C++ code + that uses new and delete: + there are different kinds of allocation schemes that can be used by + std::allocator . For implementation details, see the + mt allocator documentation and + look specifically for GLIBCXX_FORCE_NEW. +

+ +

In a nutshell, the default allocator used by + std::allocator is a high-performance pool allocator, and can + give the mistaken impression that in a suspect executable, memory + is being leaked, when in reality the memory "leak" is a pool being + used by the library's allocator and is reclaimed after program + termination. +

+ +

For valgrind, there are some specific items to keep in mind. First + of all, use a version of valgrind that will work with current GNU + C++ tools: the first that can do this is valgrind 1.0.4, but later + versions should work at least as well. Second of all, use a + completely unoptimized build to avoid confusing valgrind. Third, + use GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from + cluttering debug information. +

+ +

Fourth, it may be necessary to force deallocation in other + libraries as well, namely the "C" library. On linux, this can be + accomplished with the appropriate use of the + __cxa_atexit or atexit functions. +

+ +
+   #include <cstdlib>
+
+   extern "C" void __libc_freeres(void);
+
+   void do_something() { }
+
+   int main()
+   {
+     atexit(__libc_freeres);
+     do_something();
+     return 0;
+   }
+
+ + +

or, using __cxa_atexit:

+ +
+   extern "C" void __libc_freeres(void);
+   extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
+
+   void do_something() { }
+
+   int main()
+   {
+      extern void* __dso_handle __attribute__ ((__weak__));
+      __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, 
+                   &__dso_handle ? __dso_handle : NULL);
+      do_test();
+      return 0;
+   }
+
+ +

Suggested valgrind flags, given the suggestions above about setting + up the runtime environment, library, and test file, might be: +

+
 
+   valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
+
+ + +

Some gdb strategies

+

Many options are available for gdb itself: please see + "GDB features for C++" in the gdb documentation. Also + recommended: the other parts of this manual. +

+ +

These settings can either be switched on in at the gdb command + line, or put into a .gdbint file to establish default debugging + characteristics, like so: +

+ +
+   set print pretty on
+   set print object on
+   set print static-members on
+   set print vtbl on
+   set print demangle on
+   set demangle-style gnu-v3
+
+ + +

Tracking uncaught exceptions

+

The verbose termination handler + gives information about uncaught exceptions which are killing the + program. It is described in the linked-to page. +

+ + +

Return to the top of the page or + to the libstdc++ homepage. +

+ + + + +
+

+See license.html for copying conditions. +Comments and suggestions are welcome, and may be sent to +the libstdc++ mailing list. +

+ + + + -- cgit v1.2.3