debug_mode_semantics.html revision 1.1
1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Semantics</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="C++, library, debug" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="debug_mode.html" title="Chapter��17.��Debug Mode" /><link rel="prev" href="debug_mode.html" title="Chapter��17.��Debug Mode" /><link rel="next" href="debug_mode_using.html" title="Using" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Semantics</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="debug_mode.html">Prev</a>��</td><th width="60%" align="center">Chapter��17.��Debug Mode</th><td width="20%" align="right">��<a accesskey="n" href="debug_mode_using.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.debug_mode.semantics"></a>Semantics</h2></div></div></div><p> 3 </p><p>A program that uses the C++ standard library correctly 4 will maintain the same semantics under debug mode as it had with 5 the normal (release) library. All functional and exception-handling 6 guarantees made by the normal library also hold for the debug mode 7 library, with one exception: performance guarantees made by the 8 normal library may not hold in the debug mode library. For 9 instance, erasing an element in a <code class="code">std::list</code> is a 10 constant-time operation in normal library, but in debug mode it is 11 linear in the number of iterators that reference that particular 12 list. So while your (correct) program won't change its results, it 13 is likely to execute more slowly.</p><p>libstdc++ includes many extensions to the C++ standard library. In 14 some cases the extensions are obvious, such as the hashed 15 associative containers, whereas other extensions give predictable 16 results to behavior that would otherwise be undefined, such as 17 throwing an exception when a <code class="code">std::basic_string</code> is 18 constructed from a NULL character pointer. This latter category also 19 includes implementation-defined and unspecified semantics, such as 20 the growth rate of a vector. Use of these extensions is not 21 considered incorrect, so code that relies on them will not be 22 rejected by debug mode. However, use of these extensions may affect 23 the portability of code to other implementations of the C++ standard 24 library, and is therefore somewhat hazardous. For this reason, the 25 libstdc++ debug mode offers a "pedantic" mode (similar to 26 GCC's <code class="code">-pedantic</code> compiler flag) that attempts to emulate 27 the semantics guaranteed by the C++ standard. For 28 instance, constructing a <code class="code">std::basic_string</code> with a NULL 29 character pointer would result in an exception under normal mode or 30 non-pedantic debug mode (this is a libstdc++ extension), whereas 31 under pedantic debug mode libstdc++ would signal an error. To enable 32 the pedantic debug mode, compile your program with 33 both <code class="code">-D_GLIBCXX_DEBUG</code> 34 and <code class="code">-D_GLIBCXX_DEBUG_PEDANTIC</code> . 35 (N.B. In GCC 3.4.x and 4.0.0, due to a bug, 36 <code class="code">-D_GLIBXX_DEBUG_PEDANTIC</code> was also needed. The problem has 37 been fixed in GCC 4.0.1 and later versions.) </p><p>The following library components provide extra debugging 38 capabilities in debug mode:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="code">std::basic_string</code> (no safe iterators and see note below)</p></li><li class="listitem"><p><code class="code">std::bitset</code></p></li><li class="listitem"><p><code class="code">std::deque</code></p></li><li class="listitem"><p><code class="code">std::list</code></p></li><li class="listitem"><p><code class="code">std::map</code></p></li><li class="listitem"><p><code class="code">std::multimap</code></p></li><li class="listitem"><p><code class="code">std::multiset</code></p></li><li class="listitem"><p><code class="code">std::set</code></p></li><li class="listitem"><p><code class="code">std::vector</code></p></li><li class="listitem"><p><code class="code">std::unordered_map</code></p></li><li class="listitem"><p><code class="code">std::unordered_multimap</code></p></li><li class="listitem"><p><code class="code">std::unordered_set</code></p></li><li class="listitem"><p><code class="code">std::unordered_multiset</code></p></li></ul></div><p>N.B. although there are precondition checks for some string operations, 39e.g. <code class="code">operator[]</code>, 40they will not always be run when using the <code class="code">char</code> and 41<code class="code">wchar_t</code> specialisations (<code class="code">std::string</code> and 42<code class="code">std::wstring</code>). This is because libstdc++ uses GCC's 43<code class="code">extern template</code> extension to provide explicit instantiations 44of <code class="code">std::string</code> and <code class="code">std::wstring</code>, and those 45explicit instantiations don't include the debug-mode checks. If the 46containing functions are inlined then the checks will run, so compiling 47with <code class="code">-O1</code> might be enough to enable them. Alternatively 48<code class="code">-D_GLIBCXX_EXTERN_TEMPLATE=0</code> will suppress the declarations 49of the explicit instantiations and cause the functions to be instantiated 50with the debug-mode checks included, but this is unsupported and not 51guaranteed to work. For full debug-mode support you can use the 52<code class="code">__gnu_debug::basic_string</code> debugging container directly, 53which always works correctly. 54</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="debug_mode.html">Prev</a>��</td><td width="20%" align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td width="40%" align="right">��<a accesskey="n" href="debug_mode_using.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter��17.��Debug Mode��</td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top">��Using</td></tr></table></div></body></html>