libstdc++-v3/docs/html/abi.html

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html
   3           PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8    <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" />
   9    <meta name="KEYWORDS" content="C++, libstdc++, dynamic, shared, library, ABI, version" />
  10    <meta name="DESCRIPTION" content="C++ Standard Library ABI" />
  11    <meta name="GENERATOR" content="emacs and ten fingers" />
  12    <title>Standard C++ Library ABI</title>
  13 <link rel="StyleSheet" href="lib3styles.css" type="text/css" />
  14 <link rel="Start" href="documentation.html" type="text/html"
  15   title="GNU C++ Standard Library" />
  16 <link rel="Copyright" href="17_intro/license.html" type="text/html" />
  17 </head>
  18 <body>
  19
  20 <h1 class="centered"><a name="top">C++ Standard Library ABI</a></h1>
  21
  22 <p class="fineprint"><em>
  23    The latest version of this document is always available at
  24    <a href="http://gcc.gnu.org/onlinedocs/libstdc++/abi.html">
  25    http://gcc.gnu.org/onlinedocs/libstdc++/abi.html</a>.
  26 </em></p>
  27
  28 <p><em>
  29    To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
  30 </em></p>
  31
  32 <!-- ####################################################### -->
  33 <hr />
  34 <h3 class="left">
  35   <a name="CXXinterface">The C++ interface</a>
  36 </h3>
  37
  38 <p> C++ applications often dependent on specific language support
  39 routines, say for throwing exceptions, or catching exceptions, and
  40 perhaps also dependent on features in the C++ Standard Library.
  41 </p>
  42
  43 <p> The C++ Standard Library has many include files, types defined in
  44 those include files, specific named functions, and other behavior. The
  45 text of these behaviors, as written in source include files, is called
  46 the Application Programing Interface, or API.
  47 </p>
  48
  49 <p> Furthermore, C++ source that is compiled into object files is
  50  transformed by the compiler: it arranges objects with specific
  51  alignment and in a particular layout, mangling names according to a
  52  well-defined algorithm, has specific arrangements for the support of
  53  virtual functions, etc. These details are defined as the compiler
  54  Application Binary Interface, or ABI. The GNU C++ compiler uses an
  55  industry-standard C++ ABI starting with version 3. Details can be
  56  found in the <a href="http://www.codesourcery.com/cxx-abi/abi.html">
  57  ABI specification</a>.
  58 </p>
  59
  60 <p>
  61  The GNU C++ compiler, g++, has a compiler command line option to
  62   switch between various different C++ ABIs. This explicit version
  63   switch is the flag <code> -fabi-version</code>. In addition, some
  64   g++ command line options may change the ABI as a side-effect of
  65   use. Such flags include <code>-fpack-struct</code> and
  66   <code>-fno-exceptions</code>, but include others: see the complete
  67   list in the GCC manual under the heading <a
  68   href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options">Options
  69   for Code Generation Conventions</a>.
  70 </p>
  71
  72 <p> The configure options used when building a specific libstdc++
  73 version may also impact the resulting library ABI. The available
  74 configure options, and their impact on the library ABI, are documented
  75 <a href="http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html">
  76 here</a>.
  77 </p>
  78
  79 <p> Putting all of these ideas together results in the C++ Standard
  80 library ABI, which is the compilation of a given library API by a
  81 given compiler ABI. In a nutshell:
  82 </p>
  83
  84 <code> library API + compiler ABI = library ABI</code>
  85
  86 <p>
  87  The library ABI is mostly of interest for end-users who have
  88  unresolved symbols and are linking dynamically to the C++ Standard
  89  library, and who thus must be careful to compile their application
  90  with a compiler that is compatible with the available C++ Standard
  91  library binary. In this case, compatible is defined with the equation
  92  above: given an application compiled with a given compiler ABI and
  93  library API, it will work correctly with a Standard C++ Library
  94  created with the same constraints.
  95 </p>
  96
  97 <p>
  98   To use a specific version of the C++ ABI, one must use a
  99   corresponding GNU C++ toolchain (Ie, g++ and libstdc++) that
 100   implements the C++ ABI in question.
 101 </p>
 102
 103 <h3 class="left">
 104   <a name="ABI_versioning">Versioning</a>
 105 </h3>
 106
 107 <p> The C++ interface has evolved throughout the history of the GNU
 108 C++ toolchain. With each release, various details have been changed so
 109 as to give distinct versions to the C++ interface.
 110 </p>
 111
 112 <h5 class="left">
 113   <a name="goals">Goals of versioning</a>
 114 </h5>
 115
 116 <p>Extending existing, stable ABIs. Versioning gives subsequent stable
 117 releases series libraries the ability to add new symbols and add
 118 functionality, all the while retaining backwards compatibility with
 119 the previous releases in the series. Note: the reverse is not true. It
 120 is not possible to take binaries linked with the latest version of a
 121 release series (if symbols have been added) and expect the initial
 122 release of the series to remain link compatible.
 123 </p>
 124
 125 <p>Allows multiple, incompatible ABIs to coexist at the same time.
 126 </p>
 127
 128 <p>
 129 </p>
 130
 131 <h5 class="left">
 132   <a name="details"> Version History </a>
 133 </h5>
 134 <p>
 135  How can this complexity be managed? What does C++ versioning mean?
 136   Because library and compiler changes often make binaries compiled
 137   with one version of the GNU tools incompatible with binaries
 138   compiled with other (either newer or older) versions of the same GNU
 139   tools, specific techniques are used to make managing this complexity
 140   easier.
 141 </p>
 142
 143 <p>
 144   The following techniques are used:
 145 </p>
 146
 147   <ul>
 148
 149     <li> <p>Release versioning on the libgcc_s.so binary. This is
 150 implemented via file names and the ELF DT_SONAME mechanism (at least
 151 on ELF systems).</p>
 152
 153     <p>It is versioned as follows:
 154     </p>
 155     <ul>
 156     <li>gcc-3.0.0: libgcc_s.so.1</li>
 157     <li>gcc-3.0.1: libgcc_s.so.1</li>
 158     <li>gcc-3.0.2: libgcc_s.so.1</li>
 159     <li>gcc-3.0.3: libgcc_s.so.1</li>
 160     <li>gcc-3.0.4: libgcc_s.so.1</li>
 161     <li>gcc-3.1.0: libgcc_s.so.1</li>
 162     <li>gcc-3.1.1: libgcc_s.so.1</li>
 163     <li>gcc-3.2.0: libgcc_s.so.1</li>
 164     <li>gcc-3.2.1: libgcc_s.so.1</li>
 165     <li>gcc-3.2.2: libgcc_s.so.1</li>
 166     <li>gcc-3.2.3: libgcc_s.so.1</li>
 167     <li>gcc-3.3.0: libgcc_s.so.1</li>
 168     <li>gcc-3.3.1: libgcc_s.so.1</li>
 169     <li>gcc-3.3.2: libgcc_s.so.1</li>
 170     <li>gcc-3.3.3: libgcc_s.so.1</li>
 171     <li>gcc-3.4.0: on m68k-linux and hppa-linux this is either libgcc_s.so.1
 172     (when configuring <code>--with-sjlj-exceptions</code>) or
 173     libgcc_s.so.2. For all others, this is libgcc_s.so.1.
 174     </li>
 175     </ul>
 176     <p></p>
 177     </li>
 178
 179     <li>Release versioning on the libstdc++.so binary, implemented in the same was as the libgcc_s.so binary, above.
 180
 181     <p>It is versioned as follows:
 182     </p>
 183     <ul>
 184     <li>gcc-3.0.0: libstdc++.so.3.0.0</li>
 185     <li>gcc-3.0.1: libstdc++.so.3.0.1</li>
 186     <li>gcc-3.0.2: libstdc++.so.3.0.2</li>
 187     <li>gcc-3.0.3: libstdc++.so.3.0.2 (Error should be libstdc++.so.3.0.3)</li>
 188     <li>gcc-3.0.4: libstdc++.so.3.0.4</li>
 189     <li>gcc-3.1.0: libstdc++.so.4.0.0</li>
 190     <li>gcc-3.1.1: libstdc++.so.4.0.1</li>
 191     <li>gcc-3.2.0: libstdc++.so.5.0.0</li>
 192     <li>gcc-3.2.1: libstdc++.so.5.0.1</li>
 193     <li>gcc-3.2.2: libstdc++.so.5.0.2</li>
 194     <li>gcc-3.2.3: libstdc++.so.5.0.3 (Not strictly required)</li>
 195     <li>gcc-3.3.0: libstdc++.so.5.0.4</li>
 196     <li>gcc-3.3.1: libstdc++.so.5.0.5</li>
 197     <li>gcc-3.3.2: libstdc++.so.5.0.5</li>
 198     <li>gcc-3.3.3: libstdc++.so.5.0.5</li>
 199     <li>gcc-3.4.0: libstdc++.so.6.0.0</li>
 200     <li>gcc-3.4.1: libstdc++.so.6.0.1</li>
 201     </ul>
 202     <p></p>
 203     </li>
 204
 205     <li>Symbol versioning on the libgcc_s.so binary.
 206     <p>mapfile: gcc/libgcc-std.ver</p>
 207
 208     <p>It is versioned with the following labels and version definitions:</p>
 209     <ul>
 210     <li>gcc-3.0.0: GCC_3.0</li>
 211     <li>gcc-3.0.1: GCC_3.0</li>
 212     <li>gcc-3.0.2: GCC_3.0</li>
 213     <li>gcc-3.0.3: GCC_3.0</li>
 214     <li>gcc-3.0.4: GCC_3.0</li>
 215     <li>gcc-3.1.0: GCC_3.0</li>
 216     <li>gcc-3.1.1: GCC_3.0</li>
 217     <li>gcc-3.2.0: GCC_3.0</li>
 218     <li>gcc-3.2.1: GCC_3.0</li>
 219     <li>gcc-3.2.2: GCC_3.0</li>
 220     <li>gcc-3.2.3: GCC_3.0</li>
 221     <li>gcc-3.3.0: GCC_3.0</li>
 222     <li>gcc-3.3.1: GCC_3.0</li>
 223     <li>gcc-3.3.2: GCC_3.0</li>
 224     <li>gcc-3.3.3: GCC_3.0</li>
 225     <li>gcc-3.4.0: GCC_3.0</li>
 226     </ul>
 227     <p></p>
 228     </li>
 229
 230     <li>Symbol versioning on the libstdc++.so binary.
 231
 232     <p>mapfile: libstdc++-v3/config/linker-map.gnu</p>
 233     <p>It is versioned with the following labels and version
 234    definitions, where the version definition is the maximum for a
 235    particular release. Note, only symbol which are newly introduced
 236    will use the maximum version definition. Thus, for release series
 237    with the same label, but incremented version definitions, the later
 238    release has both versions. (An example of this would be the
 239    gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and
 240    GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0
 241    release.)
 242    </p>
 243     <ul>
 244     <li>gcc-3.0.0: (Error, not versioned)</li>
 245     <li>gcc-3.0.1: (Error, not versioned)</li>
 246     <li>gcc-3.0.2: (Error, not versioned)</li>
 247     <li>gcc-3.0.3: (Error, not versioned)</li>
 248     <li>gcc-3.0.4: (Error, not versioned)</li>
 249     <li>gcc-3.1.0: GLIBCPP_3.1, CXXABI_1</li>
 250     <li>gcc-3.1.1: GLIBCPP_3.1, CXXABI_1</li>
 251     <li>gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2</li>
 252     <li>gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</li>
 253     <li>gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</li>
 254     <li>gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</li>
 255     <li>gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</li>
 256     <li>gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</li>
 257     <li>gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</li>
 258     <li>gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</li>
 259     <li>gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3</li>
 260     <li>gcc-3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</li>
 261     </ul>
 262     <p></p>
 263     </li>
 264
 265     <li>
 266     <p>Incremental bumping of a compiler pre-defined macro,
 267     __GXX_ABI_VERSION. This macro is defined as the version of the
 268     compiler v3 ABI, with g++ 3.0.x being version 100. This macro will
 269     be automatically defined whenever g++ is used (the curious can
 270     test this by invoking g++ with the '-v' flag.)
 271     </p>
 272
 273     <p>
 274     This macro was defined in the file "lang-specs.h" in the gcc/cp directory.
 275     Later versions defined it in "c-common.c" in the gcc directory, and from
 276     G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the
 277     '-fabi-version' command line option.
 278     </p>
 279
 280     <p>
 281     It is versioned as follows, where 'n' is given by '-fabi-version=n':
 282     </p>
 283     <ul>
 284     <li>gcc-3.0.x: 100</li>
 285     <li>gcc-3.1.x: 100 (Error, should be 101)</li>
 286     <li>gcc-3.2.x: 102</li>
 287     <li>gcc-3.3.x: 102</li>
 288     <li>gcc-3.4.x: 102 (when n=1)</li>
 289     <li>gcc-3.4.x: 1000 + n (when n&gt;1)</li>
 290     <li>gcc-3.4.x: 999999 (when n=0)</li>
 291     </ul>
 292     <p></p>
 293     </li>
 294
 295     <li>
 296     <p>Changes to the default compiler option for
 297     <code>-fabi-version</code>.
 298     </p>
 299    <p>
 300     It is versioned as follows:
 301     </p>
 302     <ul>
 303     <li>gcc-3.0.x: (Error, not versioned) </li>
 304     <li>gcc-3.1.x: (Error, not versioned) </li>
 305     <li>gcc-3.2.x: <code>-fabi-version=1</code></li>
 306     <li>gcc-3.3.x: <code>-fabi-version=1</code></li>
 307     <li>gcc-3.4.x: <code>-fabi-version=2</code></li>
 308     </ul>
 309     <p></p>
 310     </li>
 311
 312    <li>
 313     <p>Incremental bumping of a library pre-defined macro. For releases
 314     before 3.4.0, the macro is __GLIBCPP__. For later releases, it's
 315     __GLIBCXX__. (The libstdc++ project generously changed from CPP to
 316     CXX throughout its source to allow the "C" pre-processor the CPP
 317     macro namespace.) These macros are defined as the date the library
 318     was released, in compressed ISO date format, as an unsigned long.
 319     </p>
 320
 321     <p>
 322     In addition, the pre-defined macro is defined in the file
 323     "c++config" in the "libstdc++-v3/include/bits" directory and is
 324     changed every night by an automated script.
 325     </p>
 326     <p>
 327     It is versioned as follows:
 328     </p>
 329     <ul>
 330     <li>gcc-3.0.0: 20010615</li>
 331     <li>gcc-3.0.1: 20010819</li>
 332     <li>gcc-3.0.2: 20011023</li>
 333     <li>gcc-3.0.3: 20011220</li>
 334     <li>gcc-3.0.4: 20020220</li>
 335     <li>gcc-3.1.0: 20020514</li>
 336     <li>gcc-3.1.1: 20020725</li>
 337     <li>gcc-3.2.0: 20020814</li>
 338     <li>gcc-3.2.1: 20021119</li>
 339     <li>gcc-3.2.2: 20030205</li>
 340     <li>gcc-3.2.3: 20030422</li>
 341     <li>gcc-3.3.0: 20030513</li>
 342     <li>gcc-3.3.1: 20030804</li>
 343     <li>gcc-3.3.2: 20031016</li>
 344     <li>gcc-3.3.3: 20040214</li>
 345     <li>gcc-3.4.0: 20040419</li>
 346     <li>gcc-3.4.1: 20040701</li>
 347     </ul>
 348     <p></p>
 349     </li>
 350
 351
 352     <li>
 353     <p>
 354     Incremental bumping of a library pre-defined macro,
 355     _GLIBCPP_VERSION. This macro is defined as the released version of
 356     the library, as a string literal. This is only implemented in
 357     gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it
 358     is called _GLIBCXX_VERSION).
 359     </p>
 360
 361     <p>
 362     This macro is defined in the file "c++config" in the
 363     "libstdc++-v3/include/bits" directory and is generated
 364     automatically by autoconf as part of the configure-time generation
 365     of config.h.
 366     </p>
 367
 368     <p>
 369     It is versioned as follows:
 370     </p>
 371     <ul>
 372     <li>gcc-3.0.0: "3.0.0"</li>
 373     <li>gcc-3.0.1: "3.0.0" (Error, should be "3.0.1")</li>
 374     <li>gcc-3.0.2: "3.0.0" (Error, should be "3.0.2")</li>
 375     <li>gcc-3.0.3: "3.0.0" (Error, should be "3.0.3")</li>
 376     <li>gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")</li>
 377     <li>gcc-3.1.0: "3.1.0"</li>
 378     <li>gcc-3.1.1: "3.1.1"</li>
 379     <li>gcc-3.2.0: "3.2"</li>
 380     <li>gcc-3.2.1: "3.2.1"</li>
 381     <li>gcc-3.2.2: "3.2.2"</li>
 382     <li>gcc-3.2.3: "3.2.3"</li>
 383     <li>gcc-3.3.0: "3.3"</li>
 384     <li>gcc-3.3.1: "3.3.1"</li>
 385     <li>gcc-3.3.2: "3.3.2"</li>
 386     <li>gcc-3.3.3: "3.3.3"</li>
 387     <li>gcc-3.4.0: "version-unused"</li>
 388     <li>gcc-3.4.1: "version-unused"</li>
 389     </ul>
 390     <p></p>
 391     </li>
 392
 393     <li>
 394     <p>
 395     Matching each specific C++ compiler release to a specific set of
 396     C++ include files. This is only implemented in gcc-3.1.1 releases
 397     and higher.
 398     </p>
 399     <p>
 400     All C++ includes are installed in include/c++, then nest in a
 401     directory hierarchy corresponding to the C++ compiler's released
 402     version. This version corresponds to the variable "gcc_version" in
 403     "libstdc++-v3/acinclude.m4," and more details can be found in that
 404     file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0).
 405     </p>
 406     <p>
 407     C++ includes are versioned as follows:
 408     </p>
 409     <ul>
 410     <li>gcc-3.0.0: include/g++-v3</li>
 411     <li>gcc-3.0.1: include/g++-v3</li>
 412     <li>gcc-3.0.2: include/g++-v3</li>
 413     <li>gcc-3.0.3: include/g++-v3</li>
 414     <li>gcc-3.0.4: include/g++-v3</li>
 415     <li>gcc-3.1.0: include/g++-v3</li>
 416     <li>gcc-3.1.1: include/c++/3.1.1</li>
 417     <li>gcc-3.2.0: include/c++/3.2</li>
 418     <li>gcc-3.2.1: include/c++/3.2.1</li>
 419     <li>gcc-3.2.2: include/c++/3.2.2</li>
 420     <li>gcc-3.2.3: include/c++/3.2.3</li>
 421     <li>gcc-3.3.0: include/c++/3.3</li>
 422     <li>gcc-3.3.1: include/c++/3.3.1</li>
 423     <li>gcc-3.3.2: include/c++/3.3.2</li>
 424     <li>gcc-3.3.3: include/c++/3.3.3</li>
 425     <li>gcc-3.4.0: include/c++/3.4.0</li>
 426     <li>gcc-3.4.1: include/c++/3.4.1</li>
 427     </ul>
 428     <p></p>
 429     </li>
 430   </ul>
 431 <p>
 432   Taken together, these techniques can accurately specify interface
 433   and implementation changes in the GNU C++ tools themselves. Used
 434   properly, they allow both the GNU C++ tools implementation, and
 435   programs using them, an evolving yet controlled development that
 436   maintains backward compatibility.
 437 </p>
 438
 439
 440
 441 <h5 class="left">
 442   <a name="requirements"> Minimum requirements for a versioned ABI </a>
 443 </h5>
 444 <p>
 445   Minimum environment that supports a versioned ABI: A supported
 446   dynamic linker, a GNU linker of sufficient vintage to understand
 447   demangled C++ name globbing (ld), a shared executable compiled with
 448   g++, and shared libraries (libgcc_s, libstdc++-v3) compiled by a
 449   compiler (g++) with a compatible ABI. Phew.
 450 </p>
 451
 452 <p>
 453   On top of all that, an additional constraint: libstdc++ did not
 454   attempt to version symbols (or age gracefully, really) until version
 455   3.1.0.
 456 </p>
 457
 458 <p>
 459   Most modern Linux and BSD versions, particularly ones using
 460   gcc-3.1.x tools and more recent vintages, will meet the requirements above.
 461 </p>
 462
 463
 464 <h5 class="left">
 465   <a name="config"> What configure options impact symbol versioning? </a>
 466 </h5>
 467 <p>
 468   It turns out that most of the configure options that change default
 469   behavior will impact the mangled names of exported symbols, and thus
 470   impact versioning and compatibility.
 471 </p>
 472
 473 <p>
 474   For more information on configure options, including ABI impacts, see:
 475   http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html
 476 </p>
 477
 478 <p>
 479   There is one flag that explicitly deals with symbol versioning:
 480   --enable-symvers.
 481 </p>
 482
 483 <p>
 484   In particular, libstdc++-v3/acinclude.m4 has a macro called
 485   GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument passed
 486   in via --enable-symvers=foo). At that point, the macro attempts to
 487   make sure that all the requirement for symbol versioning are in
 488   place. For more information, please consult acinclude.m4.
 489 </p>
 490
 491
 492 <h5 class="left">
 493   <a name="active"> How to tell if symbol versioning is, indeed, active? </a>
 494 </h5>
 495 <p>
 496   When the GNU C++ library is being built with symbol versioning on,
 497   you should see the following at configure time for libstdc++-v3:
 498 </p>
 499
 500
 501 <code>  checking versioning on shared library symbols... gnu</code>
 502
 503 <p>
 504   If you don't see this line in the configure output, or if this line
 505   appears but the last word is 'no', then you are out of luck.
 506 </p>
 507
 508 <p>
 509   If the compiler is pre-installed, a quick way to test is to compile
 510   the following (or any) simple C++ file and link it to the shared
 511   libstdc++ library:
 512 </p>
 513
 514 <pre>
 515 #include &lt;iostream&gt;
 516
 517 int main()
 518 { std::cout &lt;&lt; "hello" &lt;&lt; std::endl; return 0; }
 519
 520 %g++ hello.cc -o hello.out
 521
 522 %ldd hello.out
 523         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
 524         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
 525         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
 526         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
 527         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 528
 529 %nm hello.out
 530 </pre>
 531
 532 <p>
 533 If you see symbols in the resulting output with "GLIBCXX_3" as part
 534 of the name, then the executable is versioned. Here's an example:
 535 </p>
 536
 537    <code>      U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4 </code>
 538
 539 <h3 class="left">
 540   <a name="ABI_allowed">Library allowed ABI changes</a>
 541 </h3>
 542 <p>
 543 The following will cause the library minor version number to
 544 increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5".
 545 </p>
 546 <ul>
 547  <li>adding an exported global or static data member</li>
 548  <li>adding an exported function, static or non-virtual member function</li>
 549  <li>adding an exported symbol or symbols by additional instantiations</li>
 550 </ul>
 551 <p>
 552 </p>
 553 <p>
 554 Other allowed changes are possible.
 555 </p>
 556
 557
 558 <h3 class="left">
 559   <a name="ABI_disallowed">Library disallowed ABI changes</a>
 560 </h3>
 561
 562 <p>
 563 The following non-exhaustive list will cause the library major version
 564 number to increase, say from "libstdc++.so.3.0.4" to
 565 "libstdc++.so.4.0.0".
 566 </p>
 567 <ul>
 568  <li>changes in the gcc/g++ compiler ABI</li>
 569 <li>changing size of an exported symbol</li>
 570 <li>changing alignment of an exported symbol</li>
 571 <li>changing the layout of an exported symbol</li>
 572 <li>changing mangling on an exported symbol</li>
 573 <li>deleting an exported symbol</li>
 574 <li>changing the inheritance properties of a type by adding or removing
 575     base classes</li>
 576 <li>
 577   changing the size, alignment, or layout of types
 578   specified in the C++ standard. These may not necessarily be
 579   instantiated or otherwise exported in the library binary, and
 580   include all the required locale facets, as well as things like
 581   std::basic_streambuf, et al.
 582 </li>
 583
 584 <li> adding an explicit copy constructor or destructor to a
 585 class that would otherwise have implicit versions. This will change
 586 the way the compiler deals with this class in by-value return
 587 statements or parameters: instead of being passing instances of this
 588 class in registers, the compiler will be forced to use memory. See <a
 589 href="http://www.codesourcery.com/cxx-abi/abi.html#calls"> this part</a>
 590  of the C++ ABI documentation for further details.
 591  </li>
 592
 593 </ul>
 594
 595 <h3 class="left">
 596   <a name="implementation">Library implementation strategy</a> </h3>
 597
 598 <ul>
 599  <li>Separation of interface and implementation
 600 <p>This is accomplished by two techniques that separate the API from
 601 the ABI: forcing undefined references to link against a library binary
 602 for definitions.
 603 </p>
 604
 605  <dl>
 606   <dt>Include files have declarations, source files have defines</dt>
 607
 608    <dd> For non-templatized types, such as much of <code>class
 609    locale</code>, the appropriate standard C++ include, say
 610    <code>locale</code>, can contain full declarations, while various
 611    source files (say <code> locale.cc, locale_init.cc,
 612    localename.cc</code>) contain definitions.</dd>
 613
 614   <dt>Extern template on required types</dt>
 615
 616    <dd>For parts of the standard that have an explicit list of required
 617    instantiations, the GNU extension syntax <code> extern template
 618    </code> can be used to control where template definitions
 619    reside. By marking required instantiations as <code> extern
 620    template </code> in include files, and providing explicit
 621    instantiations in the appropriate instantiation files, non-inlined
 622    template functions can be versioned. This technique is mostly used
 623    on parts of the standard that require <code> char</code> and <code>
 624    wchar_t</code> instantiations, and includes <code>
 625    basic_string</code>, the locale facets, and the types in <code>
 626    iostreams</code>.</dd>
 627
 628  </dl>
 629  <p> In addition, these techniques have the additional benefit that
 630  they reduce binary size, which can increase runtime performance.
 631  </p>
 632  </li>
 633
 634  <li>Namespaces linking symbol definitions to export mapfiles
 635
 636 <p>All symbols in the shared library binary are processed by a linker
 637 script at build time that either allows or disallows external
 638 linkage. Because of this, some symbols, regardless of normal C/C++
 639 linkage, are not visible. Symbols that are internal have several
 640 appealing characteristics: by not exporting the symbols, there are no
 641 relocations when the shared library is started and thus this makes for
 642 faster runtime loading performance by the underlying dynamic loading
 643 mechanism. In addition, they have the possibility of changing without
 644 impacting ABI compatibility.
 645 </p>
 646
 647 <p>The following namespaces are transformed by the mapfile:</p>
 648
 649 <dl>
 650 <dt><code>namespace std</code></dt>
 651 <dd> Defaults to exporting all symbols in label
 652 <code>GLIBCXX</code> that do not begin with an underscore, ie
 653 <code>__test_func</code> would not be exported by default. Select
 654 exceptional symbols are allowed to be visible.</dd>
 655
 656 <dt><code>namespace __gnu_cxx</code></dt>
 657 <dd> Defaults to not exporting any symbols in label
 658 <code>GLIBCXX</code>, select items are allowed to be visible.</dd>
 659
 660 <dt><code>namespace __gnu_internal</code></dt>
 661 <dd> Defaults to not exported, no items are allowed to be visible.</dd>
 662
 663 <dt><code>namespace __cxxabiv1</code>, aliased to <code> namespace abi</code></dt>
 664 <dd> Defaults to not exporting any symbols in label
 665 <code>CXXABI</code>, select items are allowed to be visible.</dd>
 666 </dl>
 667 <p>
 668 </p>
 669 </li>
 670
 671  <li>Freezing the API
 672  <p>Disallowed changes, as above, are not made on a stable release
 673 branch. Enforcement tends to be less strict with GNU extensions that
 674 standard includes.</p>
 675 </li>
 676 </ul>
 677
 678 <h3 class="left">
 679   <a name="ABI_testing">Testing ABI changes</a>
 680 </h3>
 681
 682 <p>
 683 Testing for GNU C++ ABI changes is composed of two distinct areas:
 684 testing the C++ compiler (g++) for compiler changes, and testing the
 685 C++ library (libstdc++) for library changes.
 686 </p>
 687
 688 <p>
 689 Testing the C++ compiler ABI can be done various ways.
 690 </p>
 691
 692 <p>
 693 One.
 694 Intel ABI checker. More information can be obtained
 695 <a href="http://developer.intel.com/software/products/opensource/">here.</a>
 696 </p>
 697
 698 <p>
 699 Two.
 700 The second is yet unreleased, but has been announced on the gcc
 701 mailing list. It is yet unspecified if these tools will be freely
 702 available, and able to be included in a GNU project. Please contact
 703 Mark Mitchell (mark@codesourcery.com) for more details, and current
 704 status.
 705 </p>
 706
 707 <p>
 708 Three.
 709 Involves using the vlad.consistency test framework. This has also been
 710 discussed on the gcc mailing lists.
 711 </p>
 712
 713 <p>
 714 Testing the C++ library ABI can also be done various ways.
 715 </p>
 716
 717 <p>
 718 One.
 719 (Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways,
 720 one with a new compiler and an old library, and the other with an old
 721 compiler and a new library, and look for testsuite regressions)
 722 </p>
 723
 724 <p>
 725 Details on how to set this kind of test up can be found here:
 726 http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html
 727 </p>
 728
 729 <p>
 730 Two.
 731 Use the 'make check-abi' rule in the libstdc++-v3 Makefile.
 732 </p>
 733
 734 <p>
 735 This is a proactive check the library ABI. Currently, exported symbol
 736 names that are either weak or defined are checked against a last known
 737 good baseline. Currently, this baseline is keyed off of 3.4.0
 738 binaries, as this was the last time the .so number was incremented. In
 739 addition, all exported names are demangled, and the exported objects
 740 are checked to make sure they are the same size as the same object in
 741 the baseline.
 742
 743 Notice that each baseline is relative to a <strong>default</strong>
 744 configured library and compiler: in particular, if options such as
 745 --enable-clocale, or --with-cpu, in case of multilibs, are used at
 746 configure time, the check may fail, either because of substantive
 747 differences or because of limitations of the current checking
 748 machinery.
 749 </p>
 750
 751 <p>
 752 This dataset is insufficient, yet a start. Also needed is a
 753 comprehensive check for all user-visible types part of the standard
 754 library for sizeof() and alignof() changes.
 755 </p>
 756
 757 <p>
 758 Verifying compatible layouts of objects is not even attempted.  It
 759 should be possible to use sizeof, alignof, and offsetof to compute
 760 offsets for each structure and type in the standard library, saving to
 761 another datafile. Then, compute this in a similar way for new
 762 binaries, and look for differences.
 763 </p>
 764
 765 <p>
 766 Another approach might be to use the -fdump-class-hierarchy flag to
 767 get information. However, currently this approach gives insufficient
 768 data for use in library testing, as class data members, their offsets,
 769 and other detailed data is not displayed with this flag.
 770 (See g++/7470 on how this was used to find bugs.)
 771 </p>
 772
 773 <p>
 774 Perhaps there are other C++ ABI checkers. If so, please notify
 775 us. We'd like to know about them!
 776 </p>
 777
 778 <h3 class="left">
 779   <a name="ABI_multi_testing">Testing Multi-ABI binaries</a>
 780 </h3>
 781
 782 <p>
 783 A "C" application, dynamically linked to two shared libraries, liba,
 784 libb. The dependent library liba is C++ shared library compiled with
 785 gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library
 786 libb is a C++ shared library compiled with gcc-3.4.x, and also uses io,
 787 exceptions, locale, etc.
 788 </p>
 789
 790 <p> As above, libone is constructed as follows: </p>
 791 <pre>
 792 %$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc
 793
 794 %$bld/H-x86-gcc-3.4.0/bin/g++ -shared -Wl,-soname -Wl,libone.so.1 -Wl,-O1 -Wl,-z,defs a.o -o libone.so.1.0.0
 795
 796 %ln -s libone.so.1.0.0 libone.so
 797
 798 %$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc
 799
 800 %ar cru libone.a a.o
 801 </pre>
 802
 803 <p> And, libtwo is constructed as follows: </p>
 804
 805 <pre>
 806 %$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc
 807
 808 %$bld/H-x86-gcc-3.3.3/bin/g++ -shared -Wl,-soname -Wl,libtwo.so.1 -Wl,-O1 -Wl,-z,defs b.o -o libtwo.so.1.0.0
 809
 810 %ln -s libtwo.so.1.0.0 libtwo.so
 811
 812 %$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc
 813
 814 %ar cru libtwo.a b.o
 815 </pre>
 816
 817 <p> ...with the resulting libraries looking like </p>
 818 <pre>
 819 %ldd libone.so.1.0.0
 820         libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40016000)
 821         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400fa000)
 822         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
 823         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x40125000)
 824         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 825
 826 %ldd libtwo.so.1.0.0
 827         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x40027000)
 828         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400e1000)
 829         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
 830         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x4010c000)
 831         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 832
 833 </pre>
 834
 835 <p> Then, the "C" compiler is used to compile a source file that uses
 836 functions from each library.</p>
 837 <pre>
 838 gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6
 839 </pre>
 840
 841 <p>
 842 Which gives the expected:
 843 </p>
 844 <pre>
 845 %ldd a.out
 846         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
 847         libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40015000)
 848         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
 849         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
 850         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
 851         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 852 </pre>
 853
 854 <p>
 855 This resulting binary, when executed, will be able to safely use code
 856 from both liba, and the dependent libstdc++.so.6, and libb, with the
 857 dependent libstdc++.so.5.
 858 </p>
 859
 860 <h3 class="left">
 861   <a name="references">Bibliography / Further Reading</a>
 862 </h3>
 863
 864 <p>
 865 ABIcheck, a vague idea of checking ABI compatibility
 866 <br />
 867 <a href="http://abicheck.sourceforge.net/">http://abicheck.sourceforge.net/</a>
 868 </p>
 869
 870 <p>
 871 C++ ABI reference
 872 <br />
 873 <a href="http://www.codesourcery.com/cxx-abi/">http://www.codesourcery.com/cxx-abi/</a>
 874 </p>
 875
 876 <p>
 877 Intel ABI documentation, "Intel® Compilers for Linux* -Compatibility with the GNU Compilers"
 878 <br />
 879 <a href="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm">http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm</a>
 880 </p>
 881
 882 <p>
 883 Sun Solaris 2.9 docs
 884 <br />
 885 Linker and Libraries Guide (document 816-1386)
 886 <br />
 887 C++ Migration Guide (document 816-2459)
 888 <br />
 889 <a href="http://docs.sun.com/db/prod/solaris.9">http://docs.sun.com/db/prod/solaris.9</a>
 890 <br />
 891 <a href="http://docs.sun.com/?p=/doc/816-1386&amp;a=load">http://docs.sun.com/?p=/doc/816-1386&amp;a=load</a>
 892 </p>
 893
 894 <p>
 895 Ulrich Drepper, "ELF Symbol Versioning"
 896 <br />
 897 <a href="http://people.redhat.com/drepper/symbol-versioning">http://people.redhat.com/drepper/symbol-versioning</a>
 898 </p>
 899
 900 </body>
 901 </html>
 902