main/libstdc++-v3/doc/xml/manual/intro.xml

   1 <part xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="manual.intro" xreflabel="Introduction">
   2 <?dbhtml filename="intro.html"?>
   3
   4 <info><title>
   5   Introduction
   6   <indexterm><primary>Introduction</primary></indexterm>
   7 </title>
   8   <keywordset>
   9     <keyword>ISO C++</keyword>
  10     <keyword>library</keyword>
  11   </keywordset>
  12 </info>
  13
  14
  15 <!-- Chapter 01 : Status -->
  16 <chapter xml:id="manual.intro.status" xreflabel="Status"><info><title>Status</title></info>
  17   <?dbhtml filename="status.html"?>
  18
  19
  20   <!-- Section 01 : Implementation Status -->
  21   <section xml:id="manual.intro.status.iso" xreflabel="Status"><info><title>Implementation Status</title></info>
  22
  23
  24     <!-- Section 01.1 : Status C++ 1998 -->
  25     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="status_cxx1998.xml">
  26     </xi:include>
  27
  28     <!-- Section 01.2 : Status C++ 2011 -->
  29     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="status_cxx2011.xml">
  30     </xi:include>
  31
  32     <!-- Section 01.3 : Status C++ 2014 -->
  33     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="status_cxx2014.xml">
  34     </xi:include>
  35
  36     <!-- Section 01.4 : Status C++ TR1 -->
  37     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="status_cxxtr1.xml">
  38     </xi:include>
  39
  40     <!-- Section 01.5 : Status C++ TR24733 -->
  41     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="status_cxxtr24733.xml">
  42     </xi:include>
  43   </section>
  44
  45   <!-- Section 02 : License -->
  46   <section xml:id="manual.intro.status.license" xreflabel="License"><info><title>License</title></info>
  47     <?dbhtml filename="license.html"?>
  48
  49     <para>
  50     There are two licenses affecting GNU libstdc++: one for the code,
  51     and one for the documentation.
  52     </para>
  53
  54     <para>
  55       There is a license section in the FAQ regarding common <link linkend="faq.license">questions</link>. If you have more
  56       questions, ask the FSF or the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/lists.html">gcc mailing list</link>.
  57     </para>
  58
  59     <section xml:id="manual.intro.status.license.gpl" xreflabel="License GPL"><info><title>The Code: GPL</title></info>
  60
  61
  62     <para>
  63       The source code is distributed under the <link linkend="appendix.gpl-3.0">GNU General Public License version 3</link>,
  64       with the addition under section 7 of an exception described in
  65       the <quote>GCC Runtime Library Exception, version 3.1</quote>
  66       as follows (or see the file COPYING.RUNTIME):
  67     </para>
  68
  69     <literallayout class="normal">
  70 GCC RUNTIME LIBRARY EXCEPTION
  71
  72 Version 3.1, 31 March 2009
  73
  74 Copyright (C) 2009 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.fsf.org">Free Software Foundation, Inc.</link>
  75
  76 Everyone is permitted to copy and distribute verbatim copies of this
  77 license document, but changing it is not allowed.
  78
  79 This GCC Runtime Library Exception ("Exception") is an additional
  80 permission under section 7 of the GNU General Public License, version
  81 3 ("GPLv3"). It applies to a given file (the "Runtime Library") that
  82 bears a notice placed by the copyright holder of the file stating that
  83 the file is governed by GPLv3 along with this Exception.
  84
  85 When you use GCC to compile a program, GCC may combine portions of
  86 certain GCC header files and runtime libraries with the compiled
  87 program. The purpose of this Exception is to allow compilation of
  88 non-GPL (including proprietary) programs to use, in this way, the
  89 header files and runtime libraries covered by this Exception.
  90
  91 0. Definitions.
  92
  93 A file is an "Independent Module" if it either requires the Runtime
  94 Library for execution after a Compilation Process, or makes use of an
  95 interface provided by the Runtime Library, but is not otherwise based
  96 on the Runtime Library.
  97
  98 "GCC" means a version of the GNU Compiler Collection, with or without
  99 modifications, governed by version 3 (or a specified later version) of
 100 the GNU General Public License (GPL) with the option of using any
 101 subsequent versions published by the FSF.
 102
 103 "GPL-compatible Software" is software whose conditions of propagation,
 104 modification and use would permit combination with GCC in accord with
 105 the license of GCC.
 106
 107 "Target Code" refers to output from any compiler for a real or virtual
 108 target processor architecture, in executable form or suitable for
 109 input to an assembler, loader, linker and/or execution
 110 phase. Notwithstanding that, Target Code does not include data in any
 111 format that is used as a compiler intermediate representation, or used
 112 for producing a compiler intermediate representation.
 113
 114 The "Compilation Process" transforms code entirely represented in
 115 non-intermediate languages designed for human-written code, and/or in
 116 Java Virtual Machine byte code, into Target Code. Thus, for example,
 117 use of source code generators and preprocessors need not be considered
 118 part of the Compilation Process, since the Compilation Process can be
 119 understood as starting with the output of the generators or
 120 preprocessors.
 121
 122 A Compilation Process is "Eligible" if it is done using GCC, alone or
 123 with other GPL-compatible software, or if it is done without using any
 124 work based on GCC. For example, using non-GPL-compatible Software to
 125 optimize any GCC intermediate representations would not qualify as an
 126 Eligible Compilation Process.
 127
 128 1. Grant of Additional Permission.
 129
 130 You have permission to propagate a work of Target Code formed by
 131 combining the Runtime Library with Independent Modules, even if such
 132 propagation would otherwise violate the terms of GPLv3, provided that
 133 all Target Code was generated by Eligible Compilation Processes. You
 134 may then convey such a combination under terms of your choice,
 135 consistent with the licensing of the Independent Modules.
 136
 137 2. No Weakening of GCC Copyleft.
 138
 139 The availability of this Exception does not imply any general
 140 presumption that third-party software is unaffected by the copyleft
 141 requirements of the license of GCC.
 142     </literallayout>
 143
 144     <para>
 145       Hopefully that text is self-explanatory.  If it isn't, you need to speak
 146       to your lawyer, or the Free Software Foundation.
 147     </para>
 148     </section>
 149
 150     <section xml:id="manual.intro.status.license.fdl" xreflabel="License FDL"><info><title>The Documentation: GPL, FDL</title></info>
 151
 152
 153     <para>
 154       The documentation shipped with the library and made available over
 155       the web, excluding the pages generated from source comments, are
 156       copyrighted by the Free Software Foundation, and placed under the
 157       <link linkend="appendix.gfdl-1.3"> GNU Free Documentation
 158       License version 1.3</link>.  There are no Front-Cover Texts, no
 159       Back-Cover Texts, and no Invariant Sections.
 160     </para>
 161
 162     <para>
 163       For documentation generated by doxygen or other automated tools
 164       via processing source code comments and markup, the original source
 165       code license applies to the generated files. Thus, the doxygen
 166       documents are licensed <link linkend="appendix.gpl-3.0">GPL</link>.
 167     </para>
 168
 169     <para>
 170       If you plan on making copies of the documentation, please let us know.
 171       We can probably offer suggestions.
 172     </para>
 173     </section>
 174
 175   </section>
 176
 177   <!-- Section 03 : Known Bugs -->
 178   <section xml:id="manual.intro.status.bugs" xreflabel="Bugs"><info><title>Bugs</title></info>
 179     <?dbhtml filename="bugs.html"?>
 180
 181
 182     <section xml:id="manual.intro.status.bugs.impl" xreflabel="Bugs impl"><info><title>Implementation Bugs</title></info>
 183
 184     <para>
 185       Information on known bugs, details on efforts to fix them, and
 186       fixed bugs are all available as part of the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/bugs/">GCC bug tracking system</link>,
 187       with the category set to <literal>libstdc++</literal>.
 188     </para>
 189     </section>
 190
 191     <section xml:id="manual.intro.status.bugs.iso" xreflabel="Bugs iso"><info><title>Standard Bugs</title></info>
 192
 193       <para>
 194         Everybody's got issues.  Even the C++ Standard Library.
 195       </para>
 196       <para>
 197         The Library Working Group, or LWG, is the ISO subcommittee responsible
 198         for making changes to the library.  They periodically publish an
 199         Issues List containing problems and possible solutions.  As they reach
 200         a consensus on proposed solutions, we often incorporate the solution.
 201       </para>
 202       <para>
 203         Here are the issues which have resulted in code changes to the library.
 204         The links are to the specific defect reports from a <emphasis>partial
 205         copy</emphasis> of the Issues List.  You can read the full version online
 206         at the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/">ISO C++
 207         Committee homepage</link>, linked to on the
 208         <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/readings.html">GCC "Readings"
 209         page</link>.  If
 210         you spend a lot of time reading the issues, we recommend downloading
 211         the ZIP file and reading them locally.
 212       </para>
 213       <para>
 214         (NB: <emphasis>partial copy</emphasis> means that not all
 215         links within the lwg-*.html pages will work.  Specifically,
 216         links to defect reports that have not been accorded full DR
 217         status will probably break.  Rather than trying to mirror the
 218         entire issues list on our overworked web server, we recommend
 219         you go to the LWG homepage instead.)
 220       </para>
 221       <para>
 222         If a DR is not listed here, we may simply not have gotten to
 223         it yet; feel free to submit a patch.  Search the include/bits
 224         and src directories for appearances of
 225         <constant>_GLIBCXX_RESOLVE_LIB_DEFECTS</constant> for examples
 226         of style.  Note that we usually do not make changes to the
 227         code until an issue has reached <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-active.html#DR">DR</link> status.
 228       </para>
 229
 230       <variablelist>
 231     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#5">5</link>:
 232         <emphasis>string::compare specification questionable</emphasis>
 233     </term>
 234     <listitem><para>This should be two overloaded functions rather than a single function.
 235     </para></listitem></varlistentry>
 236
 237     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#17">17</link>:
 238         <emphasis>Bad bool parsing</emphasis>
 239     </term>
 240     <listitem><para>Apparently extracting Boolean values was messed up...
 241     </para></listitem></varlistentry>
 242
 243     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#19">19</link>:
 244         <emphasis>"Noconv" definition too vague</emphasis>
 245     </term>
 246     <listitem><para>If <code>codecvt::do_in</code> returns <code>noconv</code> there are
 247         no changes to the values in <code>[to, to_limit)</code>.
 248     </para></listitem></varlistentry>
 249
 250     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#22">22</link>:
 251         <emphasis>Member open vs flags</emphasis>
 252     </term>
 253     <listitem><para>Re-opening a file stream does <emphasis>not</emphasis> clear the state flags.
 254     </para></listitem></varlistentry>
 255
 256     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#23">23</link>:
 257         <emphasis>Num_get overflow result</emphasis>
 258     </term>
 259     <listitem><para>Implement the proposed resolution.
 260     </para></listitem></varlistentry>
 261
 262     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#25">25</link>:
 263         <emphasis>String operator&lt;&lt; uses width() value wrong</emphasis>
 264     </term>
 265     <listitem><para>Padding issues.
 266     </para></listitem></varlistentry>
 267
 268     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#48">48</link>:
 269         <emphasis>Use of non-existent exception constructor</emphasis>
 270     </term>
 271     <listitem><para>An instance of <code>ios_base::failure</code> is constructed instead.
 272     </para></listitem></varlistentry>
 273
 274     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#49">49</link>:
 275         <emphasis>Underspecification of ios_base::sync_with_stdio</emphasis>
 276     </term>
 277     <listitem><para>The return type is the <emphasis>previous</emphasis> state of synchronization.
 278     </para></listitem></varlistentry>
 279
 280     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#50">50</link>:
 281         <emphasis>Copy constructor and assignment operator of ios_base</emphasis>
 282     </term>
 283     <listitem><para>These members functions are declared <code>private</code> and are
 284         thus inaccessible.  Specifying the correct semantics of
 285         "copying stream state" was deemed too complicated.
 286     </para></listitem></varlistentry>
 287
 288     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#60">60</link>:
 289         <emphasis>What is a formatted input function?</emphasis>
 290     </term>
 291     <listitem><para>This DR made many widespread changes to <code>basic_istream</code>
 292         and <code>basic_ostream</code> all of which have been implemented.
 293     </para></listitem></varlistentry>
 294
 295     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#63">63</link>:
 296         <emphasis>Exception-handling policy for unformatted output</emphasis>
 297     </term>
 298     <listitem><para>Make the policy consistent with that of formatted input, unformatted
 299         input, and formatted output.
 300     </para></listitem></varlistentry>
 301
 302     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#68">68</link>:
 303         <emphasis>Extractors for char* should store null at end</emphasis>
 304     </term>
 305     <listitem><para>And they do now.  An editing glitch in the last item in the list of
 306         [27.6.1.2.3]/7.
 307     </para></listitem></varlistentry>
 308
 309     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#74">74</link>:
 310         <emphasis>Garbled text for codecvt::do_max_length</emphasis>
 311     </term>
 312     <listitem><para>The text of the standard was gibberish.  Typos gone rampant.
 313     </para></listitem></varlistentry>
 314
 315     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#75">75</link>:
 316         <emphasis>Contradiction in codecvt::length's argument types</emphasis>
 317     </term>
 318     <listitem><para>Change the first parameter to <code>stateT&amp;</code> and implement
 319         the new effects paragraph.
 320     </para></listitem></varlistentry>
 321
 322     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#83">83</link>:
 323         <emphasis>string::npos vs. string::max_size()</emphasis>
 324     </term>
 325     <listitem><para>Safety checks on the size of the string should test against
 326         <code>max_size()</code> rather than <code>npos</code>.
 327     </para></listitem></varlistentry>
 328
 329     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#90">90</link>:
 330         <emphasis>Incorrect description of operator&gt;&gt; for strings</emphasis>
 331     </term>
 332     <listitem><para>The effect contain <code>isspace(c,getloc())</code> which must be
 333         replaced by <code>isspace(c,is.getloc())</code>.
 334     </para></listitem></varlistentry>
 335
 336     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#91">91</link>:
 337         <emphasis>Description of operator&gt;&gt; and getline() for string&lt;&gt;
 338             might cause endless loop</emphasis>
 339     </term>
 340     <listitem><para>They behave as a formatted input function and as an unformatted
 341         input function, respectively (except that <code>getline</code> is
 342         not required to set <code>gcount</code>).
 343     </para></listitem></varlistentry>
 344
 345     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#103">103</link>:
 346         <emphasis>set::iterator is required to be modifiable, but this allows
 347             modification of keys.</emphasis>
 348     </term>
 349     <listitem><para>For associative containers where the value type is the same as
 350         the key type, both <code>iterator</code> and <code>const_iterator
 351         </code> are constant iterators.
 352     </para></listitem></varlistentry>
 353
 354     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#109">109</link>:
 355         <emphasis>Missing binders for non-const sequence elements</emphasis>
 356     </term>
 357     <listitem><para>The <code>binder1st</code> and <code>binder2nd</code> didn't have an
 358         <code>operator()</code> taking a non-const parameter.
 359     </para></listitem></varlistentry>
 360
 361     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#110">110</link>:
 362         <emphasis>istreambuf_iterator::equal not const</emphasis>
 363     </term>
 364     <listitem><para>This was not a const member function.  Note that the DR says to
 365         replace the function with a const one; we have instead provided an
 366         overloaded version with identical contents.
 367     </para></listitem></varlistentry>
 368
 369     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#117">117</link>:
 370         <emphasis>basic_ostream uses nonexistent num_put member functions</emphasis>
 371     </term>
 372     <listitem><para><code>num_put::put()</code> was overloaded on the wrong types.
 373     </para></listitem></varlistentry>
 374
 375     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#118">118</link>:
 376         <emphasis>basic_istream uses nonexistent num_get member functions</emphasis>
 377     </term>
 378     <listitem><para>Same as 117, but for <code>num_get::get()</code>.
 379     </para></listitem></varlistentry>
 380
 381     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#129">129</link>:
 382         <emphasis>Need error indication from seekp() and seekg()</emphasis>
 383     </term>
 384     <listitem><para>These functions set <code>failbit</code> on error now.
 385     </para></listitem></varlistentry>
 386
 387     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#130">130</link>:
 388         <emphasis>Return type of container::erase(iterator) differs for associative containers</emphasis>
 389     </term>
 390     <listitem><para>Make member <code>erase</code> return iterator for <code>set</code>, <code>multiset</code>, <code>map</code>, <code>multimap</code>.
 391     </para></listitem></varlistentry>
 392
 393     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#136">136</link>:
 394         <emphasis>seekp, seekg setting wrong streams?</emphasis>
 395     </term>
 396     <listitem><para><code>seekp</code> should only set the output stream, and
 397         <code>seekg</code> should only set the input stream.
 398     </para></listitem></varlistentry>
 399
 400 <!--<varlistentry><term><ulink url="../ext/lwg-defects.html#159">159</ulink>:
 401         <emphasis>Strange use of underflow()</emphasis>
 402     </term>
 403     <listitem><para>In fstream.tcc, the basic_filebuf&lt;&gt;::showmanyc() function
 404         should probably not be calling <code>underflow()</code>.
 405     </para></listitem></varlistentry> -->
 406
 407     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#167">167</link>:
 408         <emphasis>Improper use of traits_type::length()</emphasis>
 409     </term>
 410     <listitem><para><code>op&lt;&lt;</code> with a <code>const char*</code> was
 411         calculating an incorrect number of characters to write.
 412     </para></listitem></varlistentry>
 413
 414     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#169">169</link>:
 415         <emphasis>Bad efficiency of overflow() mandated</emphasis>
 416     </term>
 417     <listitem><para>Grow efficiently the internal array object.
 418     </para></listitem></varlistentry>
 419
 420     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#171">171</link>:
 421         <emphasis>Strange seekpos() semantics due to joint position</emphasis>
 422     </term>
 423     <listitem><para>Quite complex to summarize...
 424     </para></listitem></varlistentry>
 425
 426     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#181">181</link>:
 427         <emphasis>make_pair() unintended behavior</emphasis>
 428     </term>
 429     <listitem><para>This function used to take its arguments as reference-to-const, now
 430         it copies them (pass by value).
 431     </para></listitem></varlistentry>
 432
 433     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#195">195</link>:
 434         <emphasis>Should basic_istream::sentry's constructor ever set eofbit?</emphasis>
 435     </term>
 436     <listitem><para>Yes, it can, specifically if EOF is reached while skipping whitespace.
 437     </para></listitem></varlistentry>
 438
 439     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#211">211</link>:
 440         <emphasis>operator&gt;&gt;(istream&amp;, string&amp;) doesn't set failbit</emphasis>
 441     </term>
 442     <listitem><para>If nothing is extracted into the string, <code>op&gt;&gt;</code> now
 443         sets <code>failbit</code> (which can cause an exception, etc., etc.).
 444     </para></listitem></varlistentry>
 445
 446     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#214">214</link>:
 447         <emphasis>set::find() missing const overload</emphasis>
 448     </term>
 449     <listitem><para>Both <code>set</code> and <code>multiset</code> were missing
 450         overloaded find, lower_bound, upper_bound, and equal_range functions
 451         for const instances.
 452     </para></listitem></varlistentry>
 453
 454     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#231">231</link>:
 455         <emphasis>Precision in iostream?</emphasis>
 456     </term>
 457     <listitem><para>For conversion from a floating-point type, <code>str.precision()</code>
 458         is specified in the conversion specification.
 459     </para></listitem></varlistentry>
 460
 461     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#233">233</link>:
 462         <emphasis>Insertion hints in associative containers</emphasis>
 463     </term>
 464     <listitem><para>Implement N1780, first check before then check after, insert as close
 465         to hint as possible.
 466     </para></listitem></varlistentry>
 467
 468     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#235">235</link>:
 469         <emphasis>No specification of default ctor for reverse_iterator</emphasis>
 470     </term>
 471     <listitem><para>The declaration of <code>reverse_iterator</code> lists a default constructor.
 472         However, no specification is given what this constructor should do.
 473     </para></listitem></varlistentry>
 474
 475     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#241">241</link>:
 476         <emphasis>Does unique_copy() require CopyConstructible and Assignable?</emphasis>
 477     </term>
 478     <listitem><para>Add a helper for forward_iterator/output_iterator, fix the existing
 479         one for input_iterator/output_iterator to not rely on Assignability.
 480     </para></listitem></varlistentry>
 481
 482     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#243">243</link>:
 483         <emphasis>get and getline when sentry reports failure</emphasis>
 484     </term>
 485     <listitem><para>Store a null character only if the character array has a non-zero size.
 486     </para></listitem></varlistentry>
 487
 488     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#251">251</link>:
 489         <emphasis>basic_stringbuf missing allocator_type</emphasis>
 490     </term>
 491     <listitem><para>This nested typedef was originally not specified.
 492     </para></listitem></varlistentry>
 493
 494     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#253">253</link>:
 495         <emphasis>valarray helper functions are almost entirely useless</emphasis>
 496     </term>
 497     <listitem><para>Make the copy constructor and copy-assignment operator declarations
 498         public in gslice_array, indirect_array, mask_array, slice_array; provide
 499         definitions.
 500     </para></listitem></varlistentry>
 501
 502     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#265">265</link>:
 503         <emphasis>std::pair::pair() effects overly restrictive</emphasis>
 504     </term>
 505     <listitem><para>The default ctor would build its members from copies of temporaries;
 506         now it simply uses their respective default ctors.
 507     </para></listitem></varlistentry>
 508
 509     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#266">266</link>:
 510         <emphasis>bad_exception::~bad_exception() missing Effects clause</emphasis>
 511     </term>
 512     <listitem><para>The <code>bad_</code>* classes no longer have destructors (they
 513         are trivial), since no description of them was ever given.
 514     </para></listitem></varlistentry>
 515
 516     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#271">271</link>:
 517         <emphasis>basic_iostream missing typedefs</emphasis>
 518     </term>
 519     <listitem><para>The typedefs it inherits from its base classes can't be used, since
 520         (for example) <code>basic_iostream&lt;T&gt;::traits_type</code> is ambiguous.
 521     </para></listitem></varlistentry>
 522
 523     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#275">275</link>:
 524         <emphasis>Wrong type in num_get::get() overloads</emphasis>
 525     </term>
 526     <listitem><para>Similar to 118.
 527     </para></listitem></varlistentry>
 528
 529     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#280">280</link>:
 530         <emphasis>Comparison of reverse_iterator to const reverse_iterator</emphasis>
 531     </term>
 532     <listitem><para>Add global functions with two template parameters.
 533         (NB: not added for now a templated assignment operator)
 534     </para></listitem></varlistentry>
 535
 536     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#292">292</link>:
 537         <emphasis>Effects of a.copyfmt (a)</emphasis>
 538     </term>
 539     <listitem><para>If <code>(this == &amp;rhs)</code> do nothing.
 540     </para></listitem></varlistentry>
 541
 542     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#300">300</link>:
 543         <emphasis>List::merge() specification incomplete</emphasis>
 544     </term>
 545     <listitem><para>If <code>(this == &amp;x)</code> do nothing.
 546     </para></listitem></varlistentry>
 547
 548     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#303">303</link>:
 549         <emphasis>Bitset input operator underspecified</emphasis>
 550     </term>
 551     <listitem><para>Basically, compare the input character to
 552                     <code>is.widen(0)</code> and <code>is.widen(1)</code>.
 553     </para></listitem></varlistentry>
 554
 555     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#305">305</link>:
 556         <emphasis>Default behavior of codecvt&lt;wchar_t, char,
 557                   mbstate_t&gt;::length()</emphasis>
 558     </term>
 559     <listitem><para>Do not specify what <code>codecvt&lt;wchar_t, char,
 560                     mbstate_t&gt;::do_length</code> must return.
 561     </para></listitem></varlistentry>
 562
 563     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#328">328</link>:
 564         <emphasis>Bad sprintf format modifier in
 565                   money_put&lt;&gt;::do_put()</emphasis>
 566     </term>
 567     <listitem><para>Change the format string to "%.0Lf".
 568     </para></listitem></varlistentry>
 569
 570     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#365">365</link>:
 571         <emphasis>Lack of const-qualification in clause 27</emphasis>
 572     </term>
 573     <listitem><para>Add const overloads of <code>is_open</code>.
 574     </para></listitem></varlistentry>
 575
 576     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#387">387</link>:
 577         <emphasis>std::complex over-encapsulated</emphasis>
 578     </term>
 579     <listitem><para>Add the <code>real(T)</code> and <code>imag(T)</code>
 580                     members;  in C++11 mode, also adjust the existing
 581                     <code>real()</code> and <code>imag()</code> members and
 582                     free functions.
 583     </para></listitem></varlistentry>
 584
 585     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#389">389</link>:
 586         <emphasis>Const overload of valarray::operator[] returns
 587                   by value</emphasis>
 588     </term>
 589     <listitem><para>Change it to return a <code>const T&amp;</code>.
 590     </para></listitem></varlistentry>
 591
 592     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#396">396</link>:
 593         <emphasis>what are characters zero and one</emphasis>
 594     </term>
 595     <listitem><para>Implement the proposed resolution.
 596     </para></listitem></varlistentry>
 597
 598     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#402">402</link>:
 599         <emphasis>Wrong new expression in [some_]allocator::construct</emphasis>
 600     </term>
 601     <listitem><para>Replace "new" with "::new".
 602     </para></listitem></varlistentry>
 603
 604     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#408">408</link>:
 605         <emphasis>
 606         Is vector&lt;reverse_iterator&lt;char*&gt; &gt; forbidden?
 607         </emphasis>
 608     </term>
 609     <listitem><para>Tweak the debug-mode checks in _Safe_iterator.
 610     </para></listitem></varlistentry>
 611
 612     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#409">409</link>:
 613         <emphasis>Closing an fstream should clear the error state</emphasis>
 614     </term>
 615     <listitem><para>Have <code>open</code> clear the error flags.
 616     </para></listitem></varlistentry>
 617
 618     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#431">431</link>:
 619         <emphasis>Swapping containers with unequal allocators</emphasis>
 620     </term>
 621     <listitem><para>Implement Option 3, as per N1599.
 622     </para></listitem></varlistentry>
 623
 624     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#432">432</link>:
 625         <emphasis>stringbuf::overflow() makes only one write position
 626             available</emphasis>
 627     </term>
 628     <listitem><para>Implement the resolution, beyond DR 169.
 629     </para></listitem></varlistentry>
 630
 631     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#434">434</link>:
 632         <emphasis>bitset::to_string() hard to use</emphasis>
 633     </term>
 634     <listitem><para>Add three overloads, taking fewer template arguments.
 635     </para></listitem></varlistentry>
 636
 637     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#438">438</link>:
 638         <emphasis>Ambiguity in the "do the right thing" clause</emphasis>
 639     </term>
 640     <listitem><para>Implement the resolution, basically cast less.
 641     </para></listitem></varlistentry>
 642
 643     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#453">453</link>:
 644         <emphasis>basic_stringbuf::seekoff need not always fail for an empty stream</emphasis>
 645     </term>
 646     <listitem><para>Don't fail if the next pointer is null and newoff is zero.
 647     </para></listitem></varlistentry>
 648
 649     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#455">455</link>:
 650         <emphasis>cerr::tie() and wcerr::tie() are overspecified</emphasis>
 651     </term>
 652     <listitem><para>Initialize cerr tied to cout and wcerr tied to wcout.
 653     </para></listitem></varlistentry>
 654
 655     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#464">464</link>:
 656         <emphasis>Suggestion for new member functions in standard containers</emphasis>
 657     </term>
 658     <listitem><para>Add <code>data()</code> to <code>std::vector</code> and
 659         <code>at(const key_type&amp;)</code> to <code>std::map</code>.
 660     </para></listitem></varlistentry>
 661
 662     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#508">508</link>:
 663         <emphasis>Bad parameters for ranlux64_base_01</emphasis>
 664     </term>
 665     <listitem><para>Fix the parameters.
 666     </para></listitem></varlistentry>
 667
 668     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#512">512</link>:
 669         <emphasis>Seeding subtract_with_carry_01 from a single unsigned long</emphasis>
 670     </term>
 671     <listitem><para>Construct a <code>linear_congruential</code> engine and seed with it.
 672     </para></listitem></varlistentry>
 673
 674     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-closed.html#526">526</link>:
 675         <emphasis>Is it undefined if a function in the standard changes in
 676             parameters?</emphasis>
 677     </term>
 678     <listitem><para>Use &amp;value.
 679     </para></listitem></varlistentry>
 680
 681     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#538">538</link>:
 682         <emphasis>241 again: Does unique_copy() require CopyConstructible
 683             and Assignable?</emphasis>
 684     </term>
 685     <listitem><para>In case of input_iterator/output_iterator rely on Assignability of
 686         input_iterator' value_type.
 687     </para></listitem></varlistentry>
 688
 689     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#539">539</link>:
 690         <emphasis>partial_sum and adjacent_difference should mention
 691             requirements</emphasis>
 692     </term>
 693     <listitem><para>We were almost doing the right thing, just use std::move
 694         in adjacent_difference.
 695     </para></listitem></varlistentry>
 696
 697     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#541">541</link>:
 698         <emphasis>shared_ptr template assignment and void</emphasis>
 699     </term>
 700     <listitem><para>Add an auto_ptr&lt;void&gt; specialization.
 701     </para></listitem></varlistentry>
 702
 703     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#543">543</link>:
 704         <emphasis>valarray slice default constructor</emphasis>
 705     </term>
 706     <listitem><para>Follow the straightforward proposed resolution.
 707     </para></listitem></varlistentry>
 708
 709     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#550">550</link>:
 710         <emphasis>What should the return type of pow(float,int) be?</emphasis>
 711     </term>
 712     <listitem><para>In C++11 mode, remove the pow(float,int), etc., signatures.
 713     </para></listitem></varlistentry>
 714
 715     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#586">586</link>:
 716         <emphasis>string inserter not a formatted function</emphasis>
 717     </term>
 718     <listitem><para>Change it to be a formatted output function (i.e. catch exceptions).
 719     </para></listitem></varlistentry>
 720
 721     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#596">596</link>:
 722         <emphasis>27.8.1.3 Table 112 omits "a+" and "a+b" modes</emphasis>
 723     </term>
 724     <listitem><para>Add the missing modes to fopen_mode.
 725     </para></listitem></varlistentry>
 726
 727     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#630">630</link>:
 728         <emphasis>arrays of valarray</emphasis>
 729     </term>
 730     <listitem><para>Implement the simple resolution.
 731     </para></listitem></varlistentry>
 732
 733     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#660">660</link>:
 734         <emphasis>Missing bitwise operations</emphasis>
 735     </term>
 736     <listitem><para>Add the missing operations.
 737     </para></listitem></varlistentry>
 738
 739     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#691">691</link>:
 740         <emphasis>const_local_iterator cbegin, cend missing from TR1</emphasis>
 741     </term>
 742     <listitem><para>In C++11 mode add cbegin(size_type) and cend(size_type)
 743                     to the unordered containers.
 744     </para></listitem></varlistentry>
 745
 746     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#693">693</link>:
 747         <emphasis>std::bitset::all() missing</emphasis>
 748     </term>
 749     <listitem><para>Add it, consistently with the discussion.
 750     </para></listitem></varlistentry>
 751
 752     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#695">695</link>:
 753         <emphasis>ctype&lt;char&gt;::classic_table() not accessible</emphasis>
 754     </term>
 755     <listitem><para>Make the member functions table and classic_table public.
 756     </para></listitem></varlistentry>
 757
 758     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#696">696</link>:
 759         <emphasis>istream::operator&gt;&gt;(int&amp;) broken</emphasis>
 760     </term>
 761     <listitem><para>Implement the straightforward resolution.
 762     </para></listitem></varlistentry>
 763
 764     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#761">761</link>:
 765         <emphasis>unordered_map needs an at() member function</emphasis>
 766     </term>
 767     <listitem><para>In C++11 mode, add at() and at() const.
 768     </para></listitem></varlistentry>
 769
 770     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#775">775</link>:
 771         <emphasis>Tuple indexing should be unsigned?</emphasis>
 772     </term>
 773     <listitem><para>Implement the int -&gt; size_t replacements.
 774     </para></listitem></varlistentry>
 775
 776     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#776">776</link>:
 777         <emphasis>Undescribed assign function of std::array</emphasis>
 778     </term>
 779     <listitem><para>In C++11 mode, remove assign, add fill.
 780     </para></listitem></varlistentry>
 781
 782     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#781">781</link>:
 783         <emphasis>std::complex should add missing C99 functions</emphasis>
 784     </term>
 785     <listitem><para>In C++11 mode, add std::proj.
 786     </para></listitem></varlistentry>
 787
 788     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#809">809</link>:
 789         <emphasis>std::swap should be overloaded for array types</emphasis>
 790     </term>
 791     <listitem><para>Add the overload.
 792     </para></listitem></varlistentry>
 793
 794     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#853">853</link>:
 795         <emphasis>to_string needs updating with zero and one</emphasis>
 796     </term>
 797     <listitem><para>Update / add the signatures.
 798     </para></listitem></varlistentry>
 799
 800     <varlistentry><term><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="../ext/lwg-defects.html#865">865</link>:
 801         <emphasis>More algorithms that throw away information</emphasis>
 802     </term>
 803     <listitem><para>The traditional HP / SGI return type and value is blessed
 804                     by the resolution of the DR.
 805     </para></listitem></varlistentry>
 806   </variablelist>
 807
 808  </section>
 809   </section>
 810 </chapter>
 811
 812
 813 <!-- Chapter 02 : Setup -->
 814 <chapter xml:id="manual.intro.setup" xreflabel="Setup"><info><title>Setup</title></info>
 815   <?dbhtml filename="setup.html"?>
 816
 817
 818    <para>To transform libstdc++ sources into installed include files
 819    and properly built binaries useful for linking to other software is
 820    a multi-step process. Steps include getting the sources,
 821    configuring and building the sources, testing, and installation.
 822    </para>
 823
 824    <para>The general outline of commands is something like:
 825    </para>
 826
 827    <programlisting>
 828    <emphasis>get gcc sources</emphasis>
 829    <emphasis>extract into gccsrcdir</emphasis>
 830    mkdir <emphasis>gccbuilddir</emphasis>
 831    cd <emphasis>gccbuilddir</emphasis>
 832    <emphasis>gccsrcdir</emphasis>/configure --prefix=<emphasis>destdir</emphasis> --other-opts...
 833    make
 834    make check
 835    make install
 836    </programlisting>
 837
 838    <para>
 839      Each step is described in more detail in the following sections.
 840    </para>
 841
 842   <!-- Section 01 : Prerequisites -->
 843   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="prerequisites.xml">
 844   </xi:include>
 845
 846   <!-- Section 02 : Configure -->
 847   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="configure.xml">
 848   </xi:include>
 849
 850   <!-- Section 03 : Make -->
 851 <section xml:id="manual.intro.setup.make" xreflabel="Make"><info><title>Make</title></info>
 852   <?dbhtml filename="make.html"?>
 853
 854    <para>If you have never done this before, you should read the basic
 855       <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/">GCC Installation
 856       Instructions</link> first.  Read <emphasis>all of them</emphasis>.
 857       <emphasis>Twice.</emphasis>
 858    </para>
 859
 860 <para>Then type: <command>make</command>, and congratulations, you've
 861 started to build.
 862 </para>
 863
 864 </section>
 865
 866 </chapter>
 867
 868 <!-- Chapter 03 : Using -->
 869 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="using.xml">
 870 </xi:include>
 871
 872 </part>