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