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