1========== 2Debug Mode 3========== 4 5.. contents:: 6 :local: 7 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 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 40Handling Assertion Failures 41--------------------------- 42 43When a debug assertion fails the assertion handler is called via the 44``std::__libcpp_debug_function`` function pointer. It is possible to override 45this function pointer using a different handler function. Libc++ provides two 46different 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 50assertion 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 68Debug Mode Checks 69================= 70 71Libc++'s debug mode offers two levels of checking. The first enables various 72precondition checks throughout libc++. The second additionally enables 73"iterator debugging" which checks the validity of iterators used by the program. 74 75Basic Checks 76============ 77 78These checks are enabled when ``_LIBCPP_DEBUG`` is defined to either 0 or 1. 79 80The following checks are enabled by ``_LIBCPP_DEBUG``: 81 82 * FIXME: Update this list 83 84Iterator Debugging Checks 85========================= 86 87These checks are enabled when ``_LIBCPP_DEBUG`` is defined to 1. 88 89The 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 99The remaining containers do not currently support iterator debugging. 100Patches welcome. 101