blob: e4d4e5b2d909ae1908e4e565acd348a58a3687e6 [file] [log] [blame]
Eric Fiselierfb825432016-12-28 04:58:52 +00001==========
2Debug Mode
3==========
4
5.. contents::
Eric Fiselier53923992017-02-05 01:16:25 +00006 :local:
Eric Fiselierfb825432016-12-28 04:58:52 +00007
8.. _using-debug-mode:
9
10Using Debug Mode
11================
12
13Libc++ provides a debug mode that enables assertions meant to detect incorrect
14usage of the standard library. By default these assertions are disabled but
15they can be enabled using the ``_LIBCPP_DEBUG`` macro.
16
17**_LIBCPP_DEBUG** Macro
18-----------------------
19
20**_LIBCPP_DEBUG**:
21 This macro is used to enable assertions and iterator debugging checks within
22 libc++. By default it is undefined.
23
24 **Values**: ``0``, ``1``
25
26 Defining ``_LIBCPP_DEBUG`` to ``0`` or greater enables most of libc++'s
27 assertions. Defining ``_LIBCPP_DEBUG`` to ``1`` enables "iterator debugging"
28 which provides additional assertions about the validity of iterators used by
29 the program.
30
Eric Fiselierba56b322019-06-08 04:59:41 +000031 Note that this option has no effect on libc++'s ABI; but it does have broad
32 ODR implications. Users should compile their whole program at the same
33 debugging level.
Eric Fiselierfb825432016-12-28 04:58:52 +000034
35Handling Assertion Failures
36---------------------------
37
38When a debug assertion fails the assertion handler is called via the
39``std::__libcpp_debug_function`` function pointer. It is possible to override
Eric Fiselierba56b322019-06-08 04:59:41 +000040this function pointer using a different handler function. Libc++ provides a
41the default handler, ``std::__libcpp_abort_debug_handler``, which aborts the
42program. The handler may not return. Libc++ can be changed to use a custom
43assertion handler as follows.
Eric Fiselierfb825432016-12-28 04:58:52 +000044
45.. code-block:: cpp
46
47 #define _LIBCPP_DEBUG 1
48 #include <string>
Eric Fiselierba56b322019-06-08 04:59:41 +000049 void my_handler(std::__libcpp_debug_info const&);
JF Bastienb7b53ca2019-02-04 20:31:13 +000050 int main(int, char**) {
Eric Fiselierba56b322019-06-08 04:59:41 +000051 std::__libcpp_debug_function = &my_handler;
52
53 std::string::iterator bad_it;
54 std::string str("hello world");
55 str.insert(bad_it, '!'); // causes debug assertion
56 // control flow doesn't return
Eric Fiselierfb825432016-12-28 04:58:52 +000057 }
58
59Debug Mode Checks
60=================
61
62Libc++'s debug mode offers two levels of checking. The first enables various
63precondition checks throughout libc++. The second additionally enables
64"iterator debugging" which checks the validity of iterators used by the program.
65
66Basic Checks
67============
68
69These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1.
70
71The following checks are enabled by ``_LIBCPP_DEBUG``:
72
73 * FIXME: Update this list
74
75Iterator Debugging Checks
76=========================
77
78These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1.
79
80The following containers and STL classes support iterator debugging:
81
82 * ``std::string``
83 * ``std::vector<T>`` (``T != bool``)
84 * ``std::list``
85 * ``std::unordered_map``
86 * ``std::unordered_multimap``
87 * ``std::unordered_set``
88 * ``std::unordered_multiset``
89
90The remaining containers do not currently support iterator debugging.
91Patches welcome.