libstdc++-v3/docs/html/17_intro/porting.html

   1 <html lang="en">
   2 <head>
   3 <title>Porting libstdc++-v3</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="Porting libstdc++-v3">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 <!--
   9 Copyright &copy; 2000, 2001, 2002 Free Software Foundation, Inc.
  10
  11    <p>Permission is granted to copy, distribute and/or modify this document
  12 under the terms of the GNU Free Documentation License, Version 1.2 or
  13 any later version published by the Free Software Foundation; with the
  14 Invariant Sections being "GNU General Public License", the Front-Cover
  15 texts being (a) (see below), and with the Back-Cover Texts being (b)
  16 (see below).  A copy of the license is included in the section entitled
  17 "GNU Free Documentation License".
  18
  19    <p>(a) The FSF's Front-Cover Text is:
  20
  21    <p>A GNU Manual
  22
  23    <p>(b) The FSF's Back-Cover Text is:
  24
  25    <p>You have freedom to copy and modify this GNU Manual, like GNU
  26      software.  Copies published by the Free Software Foundation raise
  27      funds for GNU development.-->
  28 </head>
  29 <body>
  30 <h1 class="settitle">Porting libstdc++-v3</h1>
  31 <div class="node">
  32 <p><hr>
  33 Node:<a name="Top">Top</a>,
  34 Next:<a rel="next" accesskey="n" href="#Operating%20system">Operating system</a>,
  35 Up:<a rel="up" accesskey="u" href="#dir">(dir)</a>
  36 <br>
  37 </div>
  38
  39 <h2 class="unnumbered">Porting libstdc++-v3</h2>
  40
  41    <p>This document explains how to port libstdc++-v3 (the GNU C++ library) to
  42 a new target.
  43
  44    <p>In order to make the GNU C++ library (libstdc++-v3) work with a new
  45 target, you must edit some configuration files and provide some new
  46 header files.  Unless this is done, libstdc++-v3 will use generic
  47 settings which may not be correct for your target; even if they are
  48 correct, they will likely be inefficient.
  49
  50    <p>Before you get started, make sure that you have a working C library on
  51 your target.  The C library need not precisely comply with any
  52 particular standard, but should generally conform to the requirements
  53 imposed by the ANSI/ISO standard.
  54
  55    <p>In addition, you should try to verify that the C++ compiler generally
  56 works.  It is difficult to test the C++ compiler without a working
  57 library, but you should at least try some minimal test cases.
  58
  59    <p>Here are the primary steps required to port the library:
  60
  61 <ul class="menu">
  62 <li><a accesskey="1" href="#Operating%20system">Operating system</a>:     Configuring for your operating system.
  63 <li><a accesskey="2" href="#CPU">CPU</a>:                  Configuring for your processor chip.
  64 <li><a accesskey="3" href="#Character%20types">Character types</a>:      Implementing character classification.
  65 <li><a accesskey="4" href="#Thread%20safety">Thread safety</a>:        Implementing atomic operations.
  66 <li><a accesskey="5" href="#Numeric%20limits">Numeric limits</a>:       Implementing numeric limits.
  67 <li><a accesskey="6" href="#Libtool">Libtool</a>:              Using libtool.
  68 <li><a accesskey="7" href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>:  How you can copy and share this manual.
  69 </ul>
  70
  71 <div class="node">
  72 <p><hr>
  73 Node:<a name="Operating%20system">Operating system</a>,
  74 Next:<a rel="next" accesskey="n" href="#CPU">CPU</a>,
  75 Previous:<a rel="previous" accesskey="p" href="#Top">Top</a>,
  76 Up:<a rel="up" accesskey="u" href="#Top">Top</a>
  77 <br>
  78 </div>
  79
  80 <h2 class="chapter">Operating system</h2>
  81
  82    <p>If you are porting to a new operating system (as opposed to a new chip
  83 using an existing operating system), you will need to create a new
  84 directory in the <code>config/os</code> hierarchy.  For example, the IRIX
  85 configuration files are all in <code>config/os/irix</code>.  There is no set
  86 way to organize the OS configuration directory.  For example,
  87 <code>config/os/solaris/solaris-2.6</code> and
  88 <code>config/os/solaris/solaris-2.7</code> are used as configuration
  89 directories for these two versions of Solaris.  On the other hand, both
  90 Solaris 2.7 and Solaris 2.8 use the <code>config/os/solaris/solaris-2.7</code>
  91 directory.  The important information is that there needs to be a
  92 directory under <code>config/os</code> to store the files for your operating
  93 system.
  94
  95    <p>You might have to change the <code>configure.target</code> file to ensure that
  96 your new directory is activated.  Look for the switch statement that sets
  97 <code>os_include_dir</code>, and add a pattern to handle your operating system
  98 if the default will not suffice.  The switch statement switches on only
  99 the OS portion of the standard target triplet; e.g., the <code>solaris2.8</code>
 100 in <code>sparc-sun-solaris2.8</code>.  If the new directory is named after the
 101 OS portion of the triplet (the default), then nothing needs to be changed.
 102
 103    <p>The first file to create in this directory, should be called
 104 <code>os_defines.h</code>.  This file contains basic macro definitions
 105 that are required to allow the C++ library to work with your C library.
 106 This file should provide macro definitions for <code>__off_t</code>,
 107 <code>__off64_t</code>, and <code>__ssize_t</code>.  Typically, this just looks
 108 like:
 109
 110 <pre class="example">     #define __off_t off_t
 111      #define __off64_t off64_t
 112      #define __ssize_t ssize_t
 113      </pre>
 114
 115 <p>You don't have to provide these definitions if your system library
 116 already defines these types - but the only library known to provide
 117 these types is the GNU C Library, so you will almost certainly have to
 118 provide these macros.  Note that this file does not have to include a
 119 header file that defines <code>off_t</code>, or the other types; you simply
 120 have to provide the macros.
 121
 122    <p>In addition, several libstdc++-v3 source files unconditionally define
 123 the macro <code>_POSIX_SOURCE</code>.  On many systems, defining this macro
 124 causes large portions of the C library header files to be eliminated
 125 at preprocessing time.  Therefore, you may have to <code>#undef</code> this
 126 macro, or define other macros (like <code>_LARGEFILE_SOURCE</code> or
 127 <code>__EXTENSIONS__</code>).  You won't know what macros to define or
 128 undefine at this point; you'll have to try compiling the library and
 129 seeing what goes wrong.  If you see errors about calling functions
 130 that have not been declared, look in your C library headers to see if
 131 the functions are declared there, and then figure out what macros you
 132 need to define.  You will need to add them to the
 133 <code>CPLUSPLUS_CPP_SPEC</code> macro in the GCC configuration file for your
 134 target.  It will not work to simply define these macros in
 135 <code>os_defines.h</code>.
 136
 137    <p>At this time, there is one libstdc++-v3-specific macro which may be
 138 defined.  <code>_G_USING_THUNKS</code> may be defined to 0 to express that the
 139 port doesn't use thunks (although it is unclear that this is still
 140 useful since libio support isn't currently working and the g++ v3 ABI
 141 invalidates the assumption that some ports don't use thunks).
 142
 143    <p>Finally, you should bracket the entire file in an include-guard, like
 144 this:
 145
 146 <pre class="example">     #ifndef _GLIBCPP_OS_DEFINES
 147      #define _GLIBCPP_OS_DEFINES
 148      ...
 149      #endif
 150      </pre>
 151
 152    <p>We recommend copying an existing <code>os_defines.h</code> to use as a
 153 starting point.
 154
 155 <div class="node">
 156 <p><hr>
 157 Node:<a name="CPU">CPU</a>,
 158 Next:<a rel="next" accesskey="n" href="#Character%20types">Character types</a>,
 159 Previous:<a rel="previous" accesskey="p" href="#Operating%20system">Operating system</a>,
 160 Up:<a rel="up" accesskey="u" href="#Top">Top</a>
 161 <br>
 162 </div>
 163
 164 <h2 class="chapter">CPU</h2>
 165
 166    <p>If you are porting to a new chip (as opposed to a new operating system
 167 running on an existing chip), you will need to create a new directory in the
 168 <code>config/cpu</code> hierarchy.  Much like the <a href="#Operating%20system">Operating system</a> setup,
 169 there are no strict rules on how to organize the CPU configuration
 170 directory, but careful naming choices will allow the configury to find your
 171 setup files without explicit help.
 172
 173    <p>We recommend that for a target triplet <code>&lt;CPU&gt;-&lt;vendor&gt;-&lt;OS&gt;</code>, you
 174 name your configuration directory <code>config/cpu/&lt;CPU&gt;</code>.  If you do this,
 175 the configury will find the directory itself.  Otherwise you will need to
 176 edit the <code>configure.target</code> file and, in the switch statement that sets
 177 <code>cpu_include_dir</code>, add a pattern to handle your chip.
 178
 179    <p>Note that some chip families share a single configuration directory, for
 180 example, <code>alpha</code>, <code>alphaev5</code>, and <code>alphaev6</code> all use the
 181 <code>config/cpu/alpha</code> directory, and there is an entry in the
 182 <code>configure.target</code> switch statement to handle this.
 183
 184    <p>The <code>cpu_include_dir</code> sets default locations for the files controlling
 185 <a href="#Thread%20safety">Thread safety</a> and <a href="#Numeric%20limits">Numeric limits</a>, if the defaults are not
 186 appropriate for your chip.
 187
 188 <div class="node">
 189 <p><hr>
 190 Node:<a name="Character%20types">Character types</a>,
 191 Next:<a rel="next" accesskey="n" href="#Thread%20safety">Thread safety</a>,
 192 Previous:<a rel="previous" accesskey="p" href="#CPU">CPU</a>,
 193 Up:<a rel="up" accesskey="u" href="#Top">Top</a>
 194 <br>
 195 </div>
 196
 197 <h2 class="chapter">Character types</h2>
 198
 199    <p>The library requires that you provide three header files to implement
 200 character classification, analogous to that provided by the C libraries
 201 <code>&lt;ctype.h&gt;</code> header.  You can model these on the files provided in
 202 <code>config/os/generic</code>.  However, these files will almost
 203 certainly need some modification.
 204
 205    <p>The first file to write is <code>ctype_base.h</code>.  This file provides
 206 some very basic information about character classification.  The libstdc++-v3
 207 library assumes that your C library implements <code>&lt;ctype.h&gt;</code> by using
 208 a table (indexed by character code) containing integers, where each of
 209 these integers is a bit-mask indicating whether the character is
 210 upper-case, lower-case, alphabetic, etc.  The <code>ctype_base.h</code>
 211 file gives the type of the integer, and the values of the various bit
 212 masks.  You will have to peer at your own <code>&lt;ctype.h&gt;</code> to figure out
 213 how to define the values required by this file.
 214
 215    <p>The <code>ctype_base.h</code> header file does not need include guards.
 216 It should contain a single <code>struct</code> definition called
 217 <code>ctype_base</code>.  This <code>struct</code> should contain two type
 218 declarations, and one enumeration declaration, like this example, taken
 219 from the IRIX configuration:
 220
 221 <pre class="example">     struct ctype_base
 222      {
 223        typedef unsigned int     mask;
 224        typedef int*             __to_type;
 225
 226        enum
 227        {
 228          space = _ISspace,
 229          print = _ISprint,
 230          cntrl = _IScntrl,
 231          upper = _ISupper,
 232          lower = _ISlower,
 233          alpha = _ISalpha,
 234          digit = _ISdigit,
 235          punct = _ISpunct,
 236          xdigit = _ISxdigit,
 237          alnum = _ISalnum,
 238          graph = _ISgraph
 239        };
 240      };
 241      </pre>
 242
 243 <p>The <code>mask</code> type is the type of the elements in the table.  If your
 244 C library uses a table to map lower-case numbers to upper-case numbers,
 245 and vice versa, you should define <code>__to_type</code> to be the type of the
 246 elements in that table.  If you don't mind taking a minor performance
 247 penalty, or if your library doesn't implement <code>toupper</code> and
 248 <code>tolower</code> in this way, you can pick any pointer-to-integer type,
 249 but you must still define the type.
 250
 251    <p>The enumeration should give definitions for all the values in the above
 252 example, using the values from your native <code>&lt;ctype.h&gt;</code>.  They can
 253 be given symbolically (as above), or numerically, if you prefer.  You do
 254 not have to include <code>&lt;ctype.h&gt;</code> in this header; it will always be
 255 included before <code>ctype_base.h</code> is included.
 256
 257    <p>The next file to write is <code>ctype_noninline.h</code>, which also does
 258 not require include guards.  This file defines a few member functions
 259 that will be included in <code>include/bits/locale_facets.h</code>.  The first
 260 function that must be written is the <code>ctype&lt;char&gt;::ctype</code>
 261 constructor.  Here is the IRIX example:
 262
 263 <pre class="example">     ctype&lt;char&gt;::ctype(const mask* __table = 0, bool __del = false,
 264            size_t __refs = 0)
 265        : _Ctype_nois&lt;char&gt;(__refs), _M_del(__table != 0 &amp;&amp; __del),
 266          _M_toupper(NULL),
 267          _M_tolower(NULL),
 268          _M_ctable(NULL),
 269          _M_table(!__table
 270                   ? (const mask*) (__libc_attr._ctype_tbl-&gt;_class + 1)
 271                   : __table)
 272        { }
 273      </pre>
 274
 275 <p>There are two parts of this that you might choose to alter. The first,
 276 and most important, is the line involving <code>__libc_attr</code>.  That is
 277 IRIX system-dependent code that gets the base of the table mapping
 278 character codes to attributes.  You need to substitute code that obtains
 279 the address of this table on your system.  If you want to use your
 280 operating system's tables to map upper-case letters to lower-case, and
 281 vice versa, you should initialize <code>_M_toupper</code> and
 282 <code>_M_tolower</code> with those tables, in similar fashion.
 283
 284    <p>Now, you have to write two functions to convert from upper-case to
 285 lower-case, and vice versa.  Here are the IRIX versions:
 286
 287 <pre class="example">     char
 288      ctype&lt;char&gt;::do_toupper(char __c) const
 289      { return _toupper(__c); }
 290
 291      char
 292      ctype&lt;char&gt;::do_tolower(char __c) const
 293      { return _tolower(__c); }
 294      </pre>
 295
 296 <p>Your C library provides equivalents to IRIX's <code>_toupper</code> and
 297 <code>_tolower</code>.  If you initialized <code>_M_toupper</code> and
 298 <code>_M_tolower</code> above, then you could use those tables instead.
 299
 300    <p>Finally, you have to provide two utility functions that convert strings
 301 of characters.  The versions provided here will always work - but you
 302 could use specialized routines for greater performance if you have
 303 machinery to do that on your system:
 304
 305 <pre class="example">     const char*
 306      ctype&lt;char&gt;::do_toupper(char* __low, const char* __high) const
 307      {
 308        while (__low &lt; __high)
 309          {
 310            *__low = do_toupper(*__low);
 311            ++__low;
 312          }
 313        return __high;
 314      }
 315
 316      const char*
 317      ctype&lt;char&gt;::do_tolower(char* __low, const char* __high) const
 318      {
 319        while (__low &lt; __high)
 320          {
 321            *__low = do_tolower(*__low);
 322            ++__low;
 323          }
 324        return __high;
 325      }
 326      </pre>
 327
 328    <p>You must also provide the <code>ctype_inline.h</code> file, which
 329 contains a few more functions.  On most systems, you can just copy
 330 <code>config/os/generic/ctype_inline.h</code> and use it on your system.
 331
 332    <p>In detail, the functions provided test characters for particular
 333 properties; they are analogous to the functions like <code>isalpha</code> and
 334 <code>islower</code> provided by the C library.
 335
 336    <p>The first function is implemented like this on IRIX:
 337
 338 <pre class="example">     bool
 339      ctype&lt;char&gt;::
 340      is(mask __m, char __c) const throw()
 341      { return (_M_table)[(unsigned char)(__c)] &amp; __m; }
 342      </pre>
 343
 344 <p>The <code>_M_table</code> is the table passed in above, in the constructor.
 345 This is the table that contains the bitmasks for each character.  The
 346 implementation here should work on all systems.
 347
 348    <p>The next function is:
 349
 350 <pre class="example">     const char*
 351      ctype&lt;char&gt;::
 352      is(const char* __low, const char* __high, mask* __vec) const throw()
 353      {
 354        while (__low &lt; __high)
 355          *__vec++ = (_M_table)[(unsigned char)(*__low++)];
 356        return __high;
 357      }
 358      </pre>
 359
 360 <p>This function is similar; it copies the masks for all the characters
 361 from <code>__low</code> up until <code>__high</code> into the vector given by
 362 <code>__vec</code>.
 363
 364    <p>The last two functions again are entirely generic:
 365
 366 <pre class="example">     const char*
 367      ctype&lt;char&gt;::
 368      scan_is(mask __m, const char* __low, const char* __high) const throw()
 369      {
 370        while (__low &lt; __high &amp;&amp; !this-&gt;is(__m, *__low))
 371          ++__low;
 372        return __low;
 373      }
 374
 375      const char*
 376      ctype&lt;char&gt;::
 377      scan_not(mask __m, const char* __low, const char* __high) const throw()
 378      {
 379        while (__low &lt; __high &amp;&amp; this-&gt;is(__m, *__low))
 380          ++__low;
 381        return __low;
 382      }
 383      </pre>
 384
 385 <div class="node">
 386 <p><hr>
 387 Node:<a name="Thread%20safety">Thread safety</a>,
 388 Next:<a rel="next" accesskey="n" href="#Numeric%20limits">Numeric limits</a>,
 389 Previous:<a rel="previous" accesskey="p" href="#Character%20types">Character types</a>,
 390 Up:<a rel="up" accesskey="u" href="#Top">Top</a>
 391 <br>
 392 </div>
 393
 394 <h2 class="chapter">Thread safety</h2>
 395
 396    <p>The C++ library string functionality requires a couple of atomic
 397 operations to provide thread-safety.  If you don't take any special
 398 action, the library will use stub versions of these functions that are
 399 not thread-safe.  They will work fine, unless your applications are
 400 multi-threaded.
 401
 402    <p>If you want to provide custom, safe, versions of these functions, there
 403 are two distinct approaches.  One is to provide a version for your CPU,
 404 using assembly language constructs.  The other is to use the
 405 thread-safety primitives in your operating system.  In either case, you
 406 make a file called <code>atomicity.h</code>, and the variable
 407 <code>ATOMICITYH</code> must point to this file.
 408
 409    <p>If you are using the assembly-language approach, put this code in
 410 <code>config/cpu/&lt;chip&gt;/atomicity.h</code>, where chip is the name of
 411 your processor (see <a href="#CPU">CPU</a>).  No additional changes are necessary to
 412 locate the file in this case; <code>ATOMICITYH</code> will be set by default.
 413
 414    <p>If you are using the operating system thread-safety primitives approach,
 415 you can also put this code in the same CPU directory, in which case no more
 416 work is needed to locate the file.  For examples of this approach,
 417 see the <code>atomicity.h</code> file for IRIX or IA64.
 418
 419    <p>Alternatively, if the primitives are more closely related to the OS
 420 than they are to the CPU, you can put the <code>atomicity.h</code> file in
 421 the <a href="#Operating%20system">Operating system</a> directory instead.  In this case, you must
 422 edit <code>configure.target</code>, and in the switch statement that handles
 423 operating systems, override the <code>ATOMICITYH</code> variable to point to
 424 the appropriate <code>os_include_dir</code>.  For examples of this approach,
 425 see the <code>atomicity.h</code> file for AIX.
 426
 427    <p>With those bits out of the way, you have to actually write
 428 <code>atomicity.h</code> itself.  This file should be wrapped in an
 429 include guard named <code>_BITS_ATOMICITY_H</code>.  It should define one
 430 type, and two functions.
 431
 432    <p>The type is <code>_Atomic_word</code>.  Here is the version used on IRIX:
 433
 434 <pre class="example">     typedef long _Atomic_word;
 435      </pre>
 436
 437 <p>This type must be a signed integral type supporting atomic operations.
 438 If you're using the OS approach, use the same type used by your system's
 439 primitives.  Otherwise, use the type for which your CPU provides atomic
 440 primitives.
 441
 442    <p>Then, you must provide two functions.  The bodies of these functions
 443 must be equivalent to those provided here, but using atomic operations:
 444
 445 <pre class="example">     static inline _Atomic_word
 446      __attribute__ ((__unused__))
 447      __exchange_and_add (_Atomic_word* __mem, int __val)
 448      {
 449        _Atomic_word __result = *__mem;
 450        *__mem += __val;
 451        return __result;
 452      }
 453
 454      static inline void
 455      __attribute__ ((__unused__))
 456      __atomic_add (_Atomic_word* __mem, int __val)
 457      {
 458        *__mem += __val;
 459      }
 460      </pre>
 461
 462 <div class="node">
 463 <p><hr>
 464 Node:<a name="Numeric%20limits">Numeric limits</a>,
 465 Next:<a rel="next" accesskey="n" href="#Libtool">Libtool</a>,
 466 Previous:<a rel="previous" accesskey="p" href="#Thread%20safety">Thread safety</a>,
 467 Up:<a rel="up" accesskey="u" href="#Top">Top</a>
 468 <br>
 469 </div>
 470
 471 <h2 class="chapter">Numeric limits</h2>
 472
 473    <p>The C++ library requires information about the fundamental data types,
 474 such as the minimum and maximum representable values of each type.
 475 You can define each of these values individually, but it is usually
 476 easiest just to indicate how many bits are used in each of the data
 477 types and let the library do the rest.  For information about the
 478 macros to define, see the top of <code>include/bits/std_limits.h</code>.
 479
 480    <p>If you need to define any macros, you can do so in <code>os_defines.h</code>.
 481 However, if all operating systems for your CPU are likely to use the
 482 same values, you can provide a CPU-specific file instead so that you
 483 do not have to provide the same definitions for each operating system.
 484 To take that approach, create a new file called <code>cpu_limits.h</code> in
 485 your CPU configuration directory (see <a href="#CPU">CPU</a>).
 486
 487 <div class="node">
 488 <p><hr>
 489 Node:<a name="Libtool">Libtool</a>,
 490 Next:<a rel="next" accesskey="n" href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>,
 491 Previous:<a rel="previous" accesskey="p" href="#Numeric%20limits">Numeric limits</a>,
 492 Up:<a rel="up" accesskey="u" href="#Top">Top</a>
 493 <br>
 494 </div>
 495
 496 <h2 class="chapter">Libtool</h2>
 497
 498    <p>The C++ library is compiled, archived and linked with libtool.
 499 Explaining the full workings of libtool is beyond the scope of this
 500 document, but there are a few, particular bits that are necessary for
 501 porting.
 502
 503    <p>Some parts of the libstdc++-v3 library are compiled with the libtool
 504 <code>--tags CXX</code> option (the C++ definitions for libtool).  Therefore,
 505 <code>ltcf-cxx.sh</code> in the top-level directory needs to have the correct
 506 logic to compile and archive objects equivalent to the C version of libtool,
 507 <code>ltcf-c.sh</code>.  Some libtool targets have definitions for C but not
 508 for C++, or C++ definitions which have not been kept up to date.
 509
 510    <p>The C++ run-time library contains initialization code that needs to be
 511 run as the library is loaded.  Often, that requires linking in special
 512 object files when the C++ library is built as a shared library, or
 513 taking other system-specific actions.
 514
 515    <p>The libstdc++-v3 library is linked with the C version of libtool, even
 516 though it is a C++ library.  Therefore, the C version of libtool needs to
 517 ensure that the run-time library initializers are run.  The usual way to
 518 do this is to build the library using <code>gcc -shared</code>.
 519
 520    <p>If you need to change how the library is linked, look at
 521 <code>ltcf-c.sh</code> in the top-level directory.  Find the switch statement
 522 that sets <code>archive_cmds</code>.  Here, adjust the setting for your
 523 operating system.
 524
 525 <div class="node">
 526 <p><hr>
 527 Node:<a name="GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>,
 528 Previous:<a rel="previous" accesskey="p" href="#Libtool">Libtool</a>,
 529 Up:<a rel="up" accesskey="u" href="#Top">Top</a>
 530 <br>
 531 </div>
 532
 533 <h2 class="unnumbered">GNU Free Documentation License</h2>
 534
 535 <div align="center">Version 1.2, November 2002</div>
 536 <pre class="display">     Copyright &copy; 2000,2001,2002 Free Software Foundation, Inc.
 537      59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
 538
 539      Everyone is permitted to copy and distribute verbatim copies
 540      of this license document, but changing it is not allowed.
 541      </pre>
 542
 543      <ol type=1 start=0>
 544 <li>PREAMBLE
 545
 546      <p>The purpose of this License is to make a manual, textbook, or other
 547 functional and useful document <dfn>free</dfn> in the sense of freedom: to
 548 assure everyone the effective freedom to copy and redistribute it,
 549 with or without modifying it, either commercially or noncommercially.
 550 Secondarily, this License preserves for the author and publisher a way
 551 to get credit for their work, while not being considered responsible
 552 for modifications made by others.
 553
 554      <p>This License is a kind of "copyleft", which means that derivative
 555 works of the document must themselves be free in the same sense.  It
 556 complements the GNU General Public License, which is a copyleft
 557 license designed for free software.
 558
 559      <p>We have designed this License in order to use it for manuals for free
 560 software, because free software needs free documentation: a free
 561 program should come with manuals providing the same freedoms that the
 562 software does.  But this License is not limited to software manuals;
 563 it can be used for any textual work, regardless of subject matter or
 564 whether it is published as a printed book.  We recommend this License
 565 principally for works whose purpose is instruction or reference.
 566
 567      </p><li>APPLICABILITY AND DEFINITIONS
 568
 569      <p>This License applies to any manual or other work, in any medium, that
 570 contains a notice placed by the copyright holder saying it can be
 571 distributed under the terms of this License.  Such a notice grants a
 572 world-wide, royalty-free license, unlimited in duration, to use that
 573 work under the conditions stated herein.  The "Document", below,
 574 refers to any such manual or work.  Any member of the public is a
 575 licensee, and is addressed as "you".  You accept the license if you
 576 copy, modify or distribute the work in a way requiring permission
 577 under copyright law.
 578
 579      <p>A "Modified Version" of the Document means any work containing the
 580 Document or a portion of it, either copied verbatim, or with
 581 modifications and/or translated into another language.
 582
 583      <p>A "Secondary Section" is a named appendix or a front-matter section
 584 of the Document that deals exclusively with the relationship of the
 585 publishers or authors of the Document to the Document's overall
 586 subject (or to related matters) and contains nothing that could fall
 587 directly within that overall subject.  (Thus, if the Document is in
 588 part a textbook of mathematics, a Secondary Section may not explain
 589 any mathematics.)  The relationship could be a matter of historical
 590 connection with the subject or with related matters, or of legal,
 591 commercial, philosophical, ethical or political position regarding
 592 them.
 593
 594      <p>The "Invariant Sections" are certain Secondary Sections whose titles
 595 are designated, as being those of Invariant Sections, in the notice
 596 that says that the Document is released under this License.  If a
 597 section does not fit the above definition of Secondary then it is not
 598 allowed to be designated as Invariant.  The Document may contain zero
 599 Invariant Sections.  If the Document does not identify any Invariant
 600 Sections then there are none.
 601
 602      <p>The "Cover Texts" are certain short passages of text that are listed,
 603 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
 604 the Document is released under this License.  A Front-Cover Text may
 605 be at most 5 words, and a Back-Cover Text may be at most 25 words.
 606
 607      <p>A "Transparent" copy of the Document means a machine-readable copy,
 608 represented in a format whose specification is available to the
 609 general public, that is suitable for revising the document
 610 straightforwardly with generic text editors or (for images composed of
 611 pixels) generic paint programs or (for drawings) some widely available
 612 drawing editor, and that is suitable for input to text formatters or
 613 for automatic translation to a variety of formats suitable for input
 614 to text formatters.  A copy made in an otherwise Transparent file
 615 format whose markup, or absence of markup, has been arranged to thwart
 616 or discourage subsequent modification by readers is not Transparent.
 617 An image format is not Transparent if used for any substantial amount
 618 of text.  A copy that is not "Transparent" is called "Opaque".
 619
 620      <p>Examples of suitable formats for Transparent copies include plain
 621 <small>ASCII</small> without markup, Texinfo input format, LaTeX input
 622 format, <small>SGML</small> or <small>XML</small> using a publicly available
 623 <small>DTD</small>, and standard-conforming simple <small>HTML</small>,
 624 PostScript or <small>PDF</small> designed for human modification.  Examples
 625 of transparent image formats include <small>PNG</small>, <small>XCF</small> and
 626 <small>JPG</small>.  Opaque formats include proprietary formats that can be
 627 read and edited only by proprietary word processors, <small>SGML</small> or
 628 <small>XML</small> for which the <small>DTD</small> and/or processing tools are
 629 not generally available, and the machine-generated <small>HTML</small>,
 630 PostScript or <small>PDF</small> produced by some word processors for
 631 output purposes only.
 632
 633      <p>The "Title Page" means, for a printed book, the title page itself,
 634 plus such following pages as are needed to hold, legibly, the material
 635 this License requires to appear in the title page.  For works in
 636 formats which do not have any title page as such, "Title Page" means
 637 the text near the most prominent appearance of the work's title,
 638 preceding the beginning of the body of the text.
 639
 640      <p>A section "Entitled XYZ" means a named subunit of the Document whose
 641 title either is precisely XYZ or contains XYZ in parentheses following
 642 text that translates XYZ in another language.  (Here XYZ stands for a
 643 specific section name mentioned below, such as "Acknowledgements",
 644 "Dedications", "Endorsements", or "History".)  To "Preserve the Title"
 645 of such a section when you modify the Document means that it remains a
 646 section "Entitled XYZ" according to this definition.
 647
 648      <p>The Document may include Warranty Disclaimers next to the notice which
 649 states that this License applies to the Document.  These Warranty
 650 Disclaimers are considered to be included by reference in this
 651 License, but only as regards disclaiming warranties: any other
 652 implication that these Warranty Disclaimers may have is void and has
 653 no effect on the meaning of this License.
 654
 655      </p><li>VERBATIM COPYING
 656
 657      <p>You may copy and distribute the Document in any medium, either
 658 commercially or noncommercially, provided that this License, the
 659 copyright notices, and the license notice saying this License applies
 660 to the Document are reproduced in all copies, and that you add no other
 661 conditions whatsoever to those of this License.  You may not use
 662 technical measures to obstruct or control the reading or further
 663 copying of the copies you make or distribute.  However, you may accept
 664 compensation in exchange for copies.  If you distribute a large enough
 665 number of copies you must also follow the conditions in section 3.
 666
 667      <p>You may also lend copies, under the same conditions stated above, and
 668 you may publicly display copies.
 669
 670      </p><li>COPYING IN QUANTITY
 671
 672      <p>If you publish printed copies (or copies in media that commonly have
 673 printed covers) of the Document, numbering more than 100, and the
 674 Document's license notice requires Cover Texts, you must enclose the
 675 copies in covers that carry, clearly and legibly, all these Cover
 676 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
 677 the back cover.  Both covers must also clearly and legibly identify
 678 you as the publisher of these copies.  The front cover must present
 679 the full title with all words of the title equally prominent and
 680 visible.  You may add other material on the covers in addition.
 681 Copying with changes limited to the covers, as long as they preserve
 682 the title of the Document and satisfy these conditions, can be treated
 683 as verbatim copying in other respects.
 684
 685      <p>If the required texts for either cover are too voluminous to fit
 686 legibly, you should put the first ones listed (as many as fit
 687 reasonably) on the actual cover, and continue the rest onto adjacent
 688 pages.
 689
 690      <p>If you publish or distribute Opaque copies of the Document numbering
 691 more than 100, you must either include a machine-readable Transparent
 692 copy along with each Opaque copy, or state in or with each Opaque copy
 693 a computer-network location from which the general network-using
 694 public has access to download using public-standard network protocols
 695 a complete Transparent copy of the Document, free of added material.
 696 If you use the latter option, you must take reasonably prudent steps,
 697 when you begin distribution of Opaque copies in quantity, to ensure
 698 that this Transparent copy will remain thus accessible at the stated
 699 location until at least one year after the last time you distribute an
 700 Opaque copy (directly or through your agents or retailers) of that
 701 edition to the public.
 702
 703      <p>It is requested, but not required, that you contact the authors of the
 704 Document well before redistributing any large number of copies, to give
 705 them a chance to provide you with an updated version of the Document.
 706
 707      </p><li>MODIFICATIONS
 708
 709      <p>You may copy and distribute a Modified Version of the Document under
 710 the conditions of sections 2 and 3 above, provided that you release
 711 the Modified Version under precisely this License, with the Modified
 712 Version filling the role of the Document, thus licensing distribution
 713 and modification of the Modified Version to whoever possesses a copy
 714 of it.  In addition, you must do these things in the Modified Version:
 715
 716           <ol type=A start=1>
 717 <li>Use in the Title Page (and on the covers, if any) a title distinct
 718 from that of the Document, and from those of previous versions
 719 (which should, if there were any, be listed in the History section
 720 of the Document).  You may use the same title as a previous version
 721 if the original publisher of that version gives permission.
 722
 723           <li>List on the Title Page, as authors, one or more persons or entities
 724 responsible for authorship of the modifications in the Modified
 725 Version, together with at least five of the principal authors of the
 726 Document (all of its principal authors, if it has fewer than five),
 727 unless they release you from this requirement.
 728
 729           <li>State on the Title page the name of the publisher of the
 730 Modified Version, as the publisher.
 731
 732           <li>Preserve all the copyright notices of the Document.
 733
 734           <li>Add an appropriate copyright notice for your modifications
 735 adjacent to the other copyright notices.
 736
 737           <li>Include, immediately after the copyright notices, a license notice
 738 giving the public permission to use the Modified Version under the
 739 terms of this License, in the form shown in the Addendum below.
 740
 741           <li>Preserve in that license notice the full lists of Invariant Sections
 742 and required Cover Texts given in the Document's license notice.
 743
 744           <li>Include an unaltered copy of this License.
 745
 746           <li>Preserve the section Entitled "History", Preserve its Title, and add
 747 to it an item stating at least the title, year, new authors, and
 748 publisher of the Modified Version as given on the Title Page.  If
 749 there is no section Entitled "History" in the Document, create one
 750 stating the title, year, authors, and publisher of the Document as
 751 given on its Title Page, then add an item describing the Modified
 752 Version as stated in the previous sentence.
 753
 754           <li>Preserve the network location, if any, given in the Document for
 755 public access to a Transparent copy of the Document, and likewise
 756 the network locations given in the Document for previous versions
 757 it was based on.  These may be placed in the "History" section.
 758 You may omit a network location for a work that was published at
 759 least four years before the Document itself, or if the original
 760 publisher of the version it refers to gives permission.
 761
 762           <li>For any section Entitled "Acknowledgements" or "Dedications", Preserve
 763 the Title of the section, and preserve in the section all the
 764 substance and tone of each of the contributor acknowledgements and/or
 765 dedications given therein.
 766
 767           <li>Preserve all the Invariant Sections of the Document,
 768 unaltered in their text and in their titles.  Section numbers
 769 or the equivalent are not considered part of the section titles.
 770
 771           <li>Delete any section Entitled "Endorsements".  Such a section
 772 may not be included in the Modified Version.
 773
 774           <li>Do not retitle any existing section to be Entitled "Endorsements" or
 775 to conflict in title with any Invariant Section.
 776
 777           <li>Preserve any Warranty Disclaimers.
 778           </ol>
 779
 780      <p>If the Modified Version includes new front-matter sections or
 781 appendices that qualify as Secondary Sections and contain no material
 782 copied from the Document, you may at your option designate some or all
 783 of these sections as invariant.  To do this, add their titles to the
 784 list of Invariant Sections in the Modified Version's license notice.
 785 These titles must be distinct from any other section titles.
 786
 787      <p>You may add a section Entitled "Endorsements", provided it contains
 788 nothing but endorsements of your Modified Version by various
 789 parties--for example, statements of peer review or that the text has
 790 been approved by an organization as the authoritative definition of a
 791 standard.
 792
 793      <p>You may add a passage of up to five words as a Front-Cover Text, and a
 794 passage of up to 25 words as a Back-Cover Text, to the end of the list
 795 of Cover Texts in the Modified Version.  Only one passage of
 796 Front-Cover Text and one of Back-Cover Text may be added by (or
 797 through arrangements made by) any one entity.  If the Document already
 798 includes a cover text for the same cover, previously added by you or
 799 by arrangement made by the same entity you are acting on behalf of,
 800 you may not add another; but you may replace the old one, on explicit
 801 permission from the previous publisher that added the old one.
 802
 803      <p>The author(s) and publisher(s) of the Document do not by this License
 804 give permission to use their names for publicity for or to assert or
 805 imply endorsement of any Modified Version.
 806
 807      </p><li>COMBINING DOCUMENTS
 808
 809      <p>You may combine the Document with other documents released under this
 810 License, under the terms defined in section 4 above for modified
 811 versions, provided that you include in the combination all of the
 812 Invariant Sections of all of the original documents, unmodified, and
 813 list them all as Invariant Sections of your combined work in its
 814 license notice, and that you preserve all their Warranty Disclaimers.
 815
 816      <p>The combined work need only contain one copy of this License, and
 817 multiple identical Invariant Sections may be replaced with a single
 818 copy.  If there are multiple Invariant Sections with the same name but
 819 different contents, make the title of each such section unique by
 820 adding at the end of it, in parentheses, the name of the original
 821 author or publisher of that section if known, or else a unique number.
 822 Make the same adjustment to the section titles in the list of
 823 Invariant Sections in the license notice of the combined work.
 824
 825      <p>In the combination, you must combine any sections Entitled "History"
 826 in the various original documents, forming one section Entitled
 827 "History"; likewise combine any sections Entitled "Acknowledgements",
 828 and any sections Entitled "Dedications".  You must delete all
 829 sections Entitled "Endorsements."
 830
 831      </p><li>COLLECTIONS OF DOCUMENTS
 832
 833      <p>You may make a collection consisting of the Document and other documents
 834 released under this License, and replace the individual copies of this
 835 License in the various documents with a single copy that is included in
 836 the collection, provided that you follow the rules of this License for
 837 verbatim copying of each of the documents in all other respects.
 838
 839      <p>You may extract a single document from such a collection, and distribute
 840 it individually under this License, provided you insert a copy of this
 841 License into the extracted document, and follow this License in all
 842 other respects regarding verbatim copying of that document.
 843
 844      </p><li>AGGREGATION WITH INDEPENDENT WORKS
 845
 846      <p>A compilation of the Document or its derivatives with other separate
 847 and independent documents or works, in or on a volume of a storage or
 848 distribution medium, is called an "aggregate" if the copyright
 849 resulting from the compilation is not used to limit the legal rights
 850 of the compilation's users beyond what the individual works permit.
 851 When the Document is included an aggregate, this License does not
 852 apply to the other works in the aggregate which are not themselves
 853 derivative works of the Document.
 854
 855      <p>If the Cover Text requirement of section 3 is applicable to these
 856 copies of the Document, then if the Document is less than one half of
 857 the entire aggregate, the Document's Cover Texts may be placed on
 858 covers that bracket the Document within the aggregate, or the
 859 electronic equivalent of covers if the Document is in electronic form.
 860 Otherwise they must appear on printed covers that bracket the whole
 861 aggregate.
 862
 863      </p><li>TRANSLATION
 864
 865      <p>Translation is considered a kind of modification, so you may
 866 distribute translations of the Document under the terms of section 4.
 867 Replacing Invariant Sections with translations requires special
 868 permission from their copyright holders, but you may include
 869 translations of some or all Invariant Sections in addition to the
 870 original versions of these Invariant Sections.  You may include a
 871 translation of this License, and all the license notices in the
 872 Document, and any Warrany Disclaimers, provided that you also include
 873 the original English version of this License and the original versions
 874 of those notices and disclaimers.  In case of a disagreement between
 875 the translation and the original version of this License or a notice
 876 or disclaimer, the original version will prevail.
 877
 878      <p>If a section in the Document is Entitled "Acknowledgements",
 879 "Dedications", or "History", the requirement (section 4) to Preserve
 880 its Title (section 1) will typically require changing the actual
 881 title.
 882
 883      </p><li>TERMINATION
 884
 885      <p>You may not copy, modify, sublicense, or distribute the Document except
 886 as expressly provided for under this License.  Any other attempt to
 887 copy, modify, sublicense or distribute the Document is void, and will
 888 automatically terminate your rights under this License.  However,
 889 parties who have received copies, or rights, from you under this
 890 License will not have their licenses terminated so long as such
 891 parties remain in full compliance.
 892
 893      </p><li>FUTURE REVISIONS OF THIS LICENSE
 894
 895      <p>The Free Software Foundation may publish new, revised versions
 896 of the GNU Free Documentation License from time to time.  Such new
 897 versions will be similar in spirit to the present version, but may
 898 differ in detail to address new problems or concerns.  See
 899 <a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>.
 900
 901      <p>Each version of the License is given a distinguishing version number.
 902 If the Document specifies that a particular numbered version of this
 903 License "or any later version" applies to it, you have the option of
 904 following the terms and conditions either of that specified version or
 905 of any later version that has been published (not as a draft) by the
 906 Free Software Foundation.  If the Document does not specify a version
 907 number of this License, you may choose any version ever published (not
 908 as a draft) by the Free Software Foundation.
 909         </ol>
 910
 911 <h3 class="unnumberedsec">ADDENDUM: How to use this License for your documents</h3>
 912
 913    <p>To use this License in a document you have written, include a copy of
 914 the License in the document and put the following copyright and
 915 license notices just after the title page:
 916
 917 <pre class="smallexample">       Copyright (C)  <var>year</var>  <var>your name</var>.
 918        Permission is granted to copy, distribute and/or modify this document
 919        under the terms of the GNU Free Documentation License, Version 1.2
 920        or any later version published by the Free Software Foundation;
 921        with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
 922        A copy of the license is included in the section entitled ``GNU
 923        Free Documentation License''.
 924      </pre>
 925
 926    <p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
 927 replace the "with...Texts." line with this:
 928
 929 <pre class="smallexample">         with the Invariant Sections being <var>list their titles</var>, with
 930          the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts
 931          being <var>list</var>.
 932      </pre>
 933
 934    <p>If you have Invariant Sections without Cover Texts, or some other
 935 combination of the three, merge those two alternatives to suit the
 936 situation.
 937
 938    <p>If your document contains nontrivial examples of program code, we
 939 recommend releasing these examples in parallel under your choice of
 940 free software license, such as the GNU General Public License,
 941 to permit their use in free software.
 942
 943
 944 <div class="contents">
 945 <h2>Table of Contents</h2>
 946 <ul>
 947 <li><a name="toc_Top" href="#Top">Porting libstdc++-v3</a>
 948 <li><a name="toc_Operating%20system" href="#Operating%20system">Operating system</a>
 949 <li><a name="toc_CPU" href="#CPU">CPU</a>
 950 <li><a name="toc_Character%20types" href="#Character%20types">Character types</a>
 951 <li><a name="toc_Thread%20safety" href="#Thread%20safety">Thread safety</a>
 952 <li><a name="toc_Numeric%20limits" href="#Numeric%20limits">Numeric limits</a>
 953 <li><a name="toc_Libtool" href="#Libtool">Libtool</a>
 954 <li><a name="toc_GNU%20Free%20Documentation%20License" href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>
 955 <ul>
 956 <li><a href="#GNU%20Free%20Documentation%20License">ADDENDUM: How to use this License for your documents</a>
 957 </li></ul>
 958 </li></ul>
 959 </div>
 960
 961    </body></html>
 962