libstdc++-v3/doc/html/manual/using_macros.html

   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>Macros</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><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="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_headers.html" title="Headers" /><link rel="next" href="using_dual_abi.html" title="Dual ABI" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Macros</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_headers.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_dual_abi.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.intro.using.macros"></a>Macros</h2></div></div></div><p>
   3      All library macros begin with <code class="code">_GLIBCXX_</code>.
   4    </p><p>
   5      Furthermore, all pre-processor macros, switches, and
   6       configuration options are gathered in the
   7       file <code class="filename">c++config.h</code>, which
   8       is generated during the libstdc++ configuration and build
   9       process. This file is then included when needed by files part of
  10       the public libstdc++ API, like
  11       <code class="filename">&lt;ios&gt;</code>. Most of these
  12       macros should not be used by consumers of libstdc++, and are reserved
  13       for internal implementation use. <span class="emphasis"><em>These macros cannot
  14       be redefined</em></span>.
  15    </p><p>
  16      A select handful of macros control libstdc++ extensions and extra
  17       features, or provide versioning information for the API.  Only
  18       those macros listed below are offered for consideration by the
  19       general public.
  20    </p><p>Below are the macros which users may check for library version
  21       information. </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="code">_GLIBCXX_RELEASE</code></span></dt><dd><p>The major release number for libstdc++.  This macro is defined
  22         to the GCC major version that the libstdc++ headers belong to,
  23         as an integer constant.
  24         When compiling with GCC it has the same value as GCC's pre-defined
  25         macro <span class="symbol">__GNUC__</span>.
  26         This macro can be used when libstdc++ is used with a non-GNU
  27         compiler where <span class="symbol">__GNUC__</span> is not defined, or has a
  28         different value that doesn't correspond to the libstdc++ version.
  29         This macro first appeared in the GCC 7.1 release and is not defined
  30         for GCC 6.x or older releases.
  31       </p></dd><dt><span class="term"><code class="code">__GLIBCXX__</code></span></dt><dd><p>The revision date of the libstdc++ source code,
  32         in compressed ISO date format, as an unsigned
  33         long. For notes about using this macro and details on the value of
  34         this macro for a particular release, please consult the
  35         <a class="link" href="abi.html#abi.versioning.__GLIBCXX__">ABI History</a>
  36         appendix.
  37         </p></dd></dl></div><p>Below are the macros which users may change with #define/#undef or
  38       with -D/-U compiler flags.  The default state of the symbol is
  39       listed.</p><p><span class="quote">“<span class="quote">Configurable</span>”</span> (or <span class="quote">“<span class="quote">Not configurable</span>”</span>) means
  40       that the symbol is initially chosen (or not) based on
  41       --enable/--disable options at library build and configure time
  42       (documented in
  43       <a class="link" href="configure.html" title="Configure">Configure</a>),
  44       with the various --enable/--disable choices being translated to
  45       #define/#undef).
  46    </p><p> <acronym class="acronym">ABI</acronym>-changing means that changing from the default value may
  47   mean changing the <acronym class="acronym">ABI</acronym> of compiled code. In other words,
  48   these choices control code which has already been compiled (i.e., in a
  49   binary such as libstdc++.a/.so).  If you explicitly #define or
  50   #undef these macros, the <span class="emphasis"><em>headers</em></span> may see different code
  51   paths, but the <span class="emphasis"><em>libraries</em></span> which you link against will not.
  52   Experimenting with different values with the expectation of
  53   consistent linkage requires changing the config headers before
  54   building/installing the library.
  55    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="code">_GLIBCXX_USE_DEPRECATED</code></span></dt><dd><p>
  56         Defined to the value <code class="literal">1</code> by default.
  57         Not configurable. ABI-changing. Turning this off
  58         removes older ARM-style iostreams code, and other anachronisms
  59         from the API.  This macro is dependent on the version of the
  60         standard being tracked, and as a result may give different results for
  61         different <code class="code">-std</code> options.  This may
  62         be useful in updating old C++ code which no longer meet the
  63         requirements of the language, or for checking current code
  64         against new language standards.
  65     </p></dd><dt><span class="term"><code class="code">_GLIBCXX_USE_CXX11_ABI</code></span></dt><dd><p>
  66         Defined to the value <code class="literal">1</code> by default.
  67         Configurable via  <code class="code">--disable-libstdcxx-dual-abi</code>
  68         and/or <code class="code">--with-default-libstdcxx-abi</code>.
  69         ABI-changing.
  70         When defined to a non-zero value the library headers will use the
  71         new C++11-conforming ABI introduced in GCC 5, rather than the older
  72         ABI introduced in GCC 3.4. This changes the definition of several
  73         class templates, including <code class="classname">std:string</code>,
  74         <code class="classname">std::list</code> and some locale facets.
  75         For more details see <a class="xref" href="using_dual_abi.html" title="Dual ABI">Dual ABI</a>.
  76     </p></dd><dt><span class="term"><code class="code">_GLIBCXX_CONCEPT_CHECKS</code></span></dt><dd><p>
  77         Undefined by default.  Configurable via
  78         <code class="code">--enable-concept-checks</code>.  When defined, performs
  79         compile-time checking on certain template instantiations to
  80         detect violations of the requirements of the standard.  This
  81         macro has no effect for freestanding implementations.
  82         This is described in more detail in
  83         <a class="link" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks">Compile Time Checks</a>.
  84       </p></dd><dt><span class="term"><code class="code">_GLIBCXX_ASSERTIONS</code></span></dt><dd><p>
  85         Undefined by default. When defined, enables extra error checking in
  86         the form of precondition assertions, such as bounds checking in
  87         strings and null pointer checks when dereferencing smart pointers.
  88       </p></dd><dt><span class="term"><code class="code">_GLIBCXX_DEBUG</code></span></dt><dd><p>
  89         Undefined by default. When defined, compiles user code using
  90         the <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">debug mode</a>.
  91         When defined, <code class="code">_GLIBCXX_ASSERTIONS</code> is defined
  92         automatically, so all the assertions enabled by that macro are also
  93         enabled in debug mode.
  94       </p></dd><dt><span class="term"><code class="code">_GLIBCXX_DEBUG_PEDANTIC</code></span></dt><dd><p>
  95         Undefined by default. When defined while compiling with
  96         the <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">debug mode</a>, makes
  97         the debug mode extremely picky by making the use of libstdc++
  98         extensions and libstdc++-specific behavior into errors.
  99       </p></dd><dt><span class="term"><code class="code">_GLIBCXX_PARALLEL</code></span></dt><dd><p>Undefined by default. When defined, compiles user code
 100         using the <a class="link" href="parallel_mode.html" title="Chapter 18. Parallel Mode">parallel
 101         mode</a>.
 102       </p></dd><dt><span class="term"><code class="code">_GLIBCXX_PARALLEL_ASSERTIONS</code></span></dt><dd><p>Undefined by default, but when any parallel mode header is included
 103       this macro will be defined to a non-zero value if
 104       <code class="code">_GLIBCXX_ASSERTIONS</code> has a non-zero value, otherwise to zero.
 105       When defined to a non-zero value, it enables extra error checking and
 106       assertions in the parallel mode.
 107       </p></dd><dt><span class="term"><code class="code">__STDCPP_WANT_MATH_SPEC_FUNCS__</code></span></dt><dd><p>Undefined by default. When defined to a non-zero integer constant,
 108         enables support for ISO/IEC 29124 Special Math Functions.
 109       </p></dd><dt><span class="term"><code class="code">_GLIBCXX_SANITIZE_VECTOR</code></span></dt><dd><p>
 110         Undefined by default. When defined, <code class="classname">std::vector</code>
 111         operations will be annotated so that AddressSanitizer can detect
 112         invalid accesses to the unused capacity of a
 113         <code class="classname">std::vector</code>. These annotations are only
 114         enabled for
 115         <code class="classname">std::vector&lt;T, std::allocator&lt;T&gt;&gt;</code>
 116         and only when <code class="classname">std::allocator</code> is derived from
 117         <a class="link" href="memory.html#allocator.ext" title="Extension Allocators"><code class="classname">new_allocator</code>
 118         or <code class="classname">malloc_allocator</code></a>. The annotations
 119         must be present on all vector operations or none, so this macro must
 120         be defined to the same value for all translation units that create,
 121         destroy or modify vectors.
 122       </p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_headers.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_dual_abi.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Headers </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Dual ABI</td></tr></table></div></body></html>