1 ========== 2 Debug Mode 3 ========== 4 5 .. contents:: 6 :local: 7 8 .. _using-debug-mode: 9 10 Using Debug Mode 11 ================ 12 13 Libc++ provides a debug mode that enables assertions meant to detect incorrect 14 usage of the standard library. By default these assertions are disabled but 15 they 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 31 Note that this option has no effect on libc++'s ABI 32 33 **_LIBCPP_DEBUG_USE_EXCEPTIONS**: 34 When this macro is defined ``_LIBCPP_ASSERT`` failures throw 35 ``__libcpp_debug_exception`` instead of aborting. Additionally this macro 36 disables exception specifications on functions containing ``_LIBCPP_ASSERT`` 37 checks. This allows assertion failures to correctly throw through these 38 functions. 39 40 Handling Assertion Failures 41 --------------------------- 42 43 When a debug assertion fails the assertion handler is called via the 44 ``std::__libcpp_debug_function`` function pointer. It is possible to override 45 this function pointer using a different handler function. Libc++ provides two 46 different assertion handlers, the default handler 47 ``std::__libcpp_abort_debug_handler`` which aborts the program, and 48 ``std::__libcpp_throw_debug_handler`` which throws an instance of 49 ``std::__libcpp_debug_exception``. Libc++ can be changed to use the throwing 50 assertion handler as follows: 51 52 .. code-block:: cpp 53 54 #define _LIBCPP_DEBUG 1 55 #include <string> 56 int main() { 57 std::__libcpp_debug_function = std::__libcpp_throw_debug_function; 58 try { 59 std::string::iterator bad_it; 60 std::string str("hello world"); 61 str.insert(bad_it, '!'); // causes debug assertion 62 } catch (std::__libcpp_debug_exception const&) { 63 return EXIT_SUCCESS; 64 } 65 return EXIT_FAILURE; 66 } 67 68 Debug Mode Checks 69 ================= 70 71 Libc++'s debug mode offers two levels of checking. The first enables various 72 precondition checks throughout libc++. The second additionally enables 73 "iterator debugging" which checks the validity of iterators used by the program. 74 75 Basic Checks 76 ============ 77 78 These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1. 79 80 The following checks are enabled by ``_LIBCPP_DEBUG``: 81 82 * FIXME: Update this list 83 84 Iterator Debugging Checks 85 ========================= 86 87 These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1. 88 89 The following containers and STL classes support iterator debugging: 90 91 * ``std::string`` 92 * ``std::vector<T>`` (``T != bool``) 93 * ``std::list`` 94 * ``std::unordered_map`` 95 * ``std::unordered_multimap`` 96 * ``std::unordered_set`` 97 * ``std::unordered_multiset`` 98 99 The remaining containers do not currently support iterator debugging. 100 Patches welcome. 101
