From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- libstdc++-v3/doc/xml/manual/intro.xml | 878 ++++++++++++++++++++++++++++++++++ 1 file changed, 878 insertions(+) create mode 100644 libstdc++-v3/doc/xml/manual/intro.xml (limited to 'libstdc++-v3/doc/xml/manual/intro.xml') diff --git a/libstdc++-v3/doc/xml/manual/intro.xml b/libstdc++-v3/doc/xml/manual/intro.xml new file mode 100644 index 000000000..36e07b437 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/intro.xml @@ -0,0 +1,878 @@ + + + + + Introduction + <indexterm><primary>Introduction</primary></indexterm> + + + + ISO C++ + + + library + + + + + + +Status + + + + +
Implementation Status + + + + + + + + + + + + + + + + + +
+ + +
License + + + + There are two licenses affecting GNU libstdc++: one for the code, + and one for the documentation. + + + + There is a license section in the FAQ regarding common questions. If you have more + questions, ask the FSF or the gcc mailing list. + + +
The Code: GPL + + + + The source code is distributed under the GNU General Public License version 3, + with the addition under section 7 of an exception described in + the GCC Runtime Library Exception, version 3.1 + as follows (or see the file COPYING.RUNTIME): + + + +GCC RUNTIME LIBRARY EXCEPTION + +Version 3.1, 31 March 2009 + +Copyright (C) 2009 Free Software Foundation, Inc. + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + +This GCC Runtime Library Exception ("Exception") is an additional +permission under section 7 of the GNU General Public License, version +3 ("GPLv3"). It applies to a given file (the "Runtime Library") that +bears a notice placed by the copyright holder of the file stating that +the file is governed by GPLv3 along with this Exception. + +When you use GCC to compile a program, GCC may combine portions of +certain GCC header files and runtime libraries with the compiled +program. The purpose of this Exception is to allow compilation of +non-GPL (including proprietary) programs to use, in this way, the +header files and runtime libraries covered by this Exception. + +0. Definitions. + +A file is an "Independent Module" if it either requires the Runtime +Library for execution after a Compilation Process, or makes use of an +interface provided by the Runtime Library, but is not otherwise based +on the Runtime Library. + +"GCC" means a version of the GNU Compiler Collection, with or without +modifications, governed by version 3 (or a specified later version) of +the GNU General Public License (GPL) with the option of using any +subsequent versions published by the FSF. + +"GPL-compatible Software" is software whose conditions of propagation, +modification and use would permit combination with GCC in accord with +the license of GCC. + +"Target Code" refers to output from any compiler for a real or virtual +target processor architecture, in executable form or suitable for +input to an assembler, loader, linker and/or execution +phase. Notwithstanding that, Target Code does not include data in any +format that is used as a compiler intermediate representation, or used +for producing a compiler intermediate representation. + +The "Compilation Process" transforms code entirely represented in +non-intermediate languages designed for human-written code, and/or in +Java Virtual Machine byte code, into Target Code. Thus, for example, +use of source code generators and preprocessors need not be considered +part of the Compilation Process, since the Compilation Process can be +understood as starting with the output of the generators or +preprocessors. + +A Compilation Process is "Eligible" if it is done using GCC, alone or +with other GPL-compatible software, or if it is done without using any +work based on GCC. For example, using non-GPL-compatible Software to +optimize any GCC intermediate representations would not qualify as an +Eligible Compilation Process. + +1. Grant of Additional Permission. + +You have permission to propagate a work of Target Code formed by +combining the Runtime Library with Independent Modules, even if such +propagation would otherwise violate the terms of GPLv3, provided that +all Target Code was generated by Eligible Compilation Processes. You +may then convey such a combination under terms of your choice, +consistent with the licensing of the Independent Modules. + +2. No Weakening of GCC Copyleft. + +The availability of this Exception does not imply any general +presumption that third-party software is unaffected by the copyleft +requirements of the license of GCC. + + + + Hopefully that text is self-explanatory. If it isn't, you need to speak + to your lawyer, or the Free Software Foundation. + +
+ +
The Documentation: GPL, FDL + + + + The documentation shipped with the library and made available over + the web, excluding the pages generated from source comments, are + copyrighted by the Free Software Foundation, and placed under the + GNU Free Documentation + License version 1.3. There are no Front-Cover Texts, no + Back-Cover Texts, and no Invariant Sections. + + + + For documentation generated by doxygen or other automated tools + via processing source code comments and markup, the original source + code license applies to the generated files. Thus, the doxygen + documents are licensed GPL. + + + + If you plan on making copies of the documentation, please let us know. + We can probably offer suggestions. + +
+ +
+ + +
Bugs + + + +
Implementation Bugs + + + Information on known bugs, details on efforts to fix them, and + fixed bugs are all available as part of the GCC bug tracking system, + with the category set to libstdc++. + +
+ +
Standard Bugs + + + Everybody's got issues. Even the C++ Standard Library. + + + The Library Working Group, or LWG, is the ISO subcommittee responsible + for making changes to the library. They periodically publish an + Issues List containing problems and possible solutions. As they reach + a consensus on proposed solutions, we often incorporate the solution. + + + Here are the issues which have resulted in code changes to the library. + The links are to the specific defect reports from a partial + copy of the Issues List. You can read the full version online + at the ISO C++ + Committee homepage, linked to on the + GCC "Readings" + page. If + you spend a lot of time reading the issues, we recommend downloading + the ZIP file and reading them locally. + + + (NB: partial copy means that not all + links within the lwg-*.html pages will work. Specifically, + links to defect reports that have not been accorded full DR + status will probably break. Rather than trying to mirror the + entire issues list on our overworked web server, we recommend + you go to the LWG homepage instead.) + + + If a DR is not listed here, we may simply not have gotten to + it yet; feel free to submit a patch. Search the include/bits + and src directories for appearances of + _GLIBCXX_RESOLVE_LIB_DEFECTS for examples + of style. Note that we usually do not make changes to the + code until an issue has reached DR status. + + + + 5: + string::compare specification questionable + + This should be two overloaded functions rather than a single function. + + + 17: + Bad bool parsing + + Apparently extracting Boolean values was messed up... + + + 19: + "Noconv" definition too vague + + If codecvt::do_in returns noconv there are + no changes to the values in [to, to_limit). + + + 22: + Member open vs flags + + Re-opening a file stream does not clear the state flags. + + + 23: + Num_get overflow result + + Implement the proposed resolution. + + + 25: + String operator<< uses width() value wrong + + Padding issues. + + + 48: + Use of non-existent exception constructor + + An instance of ios_base::failure is constructed instead. + + + 49: + Underspecification of ios_base::sync_with_stdio + + The return type is the previous state of synchronization. + + + 50: + Copy constructor and assignment operator of ios_base + + These members functions are declared private and are + thus inaccessible. Specifying the correct semantics of + "copying stream state" was deemed too complicated. + + + 60: + What is a formatted input function? + + This DR made many widespread changes to basic_istream + and basic_ostream all of which have been implemented. + + + 63: + Exception-handling policy for unformatted output + + Make the policy consistent with that of formatted input, unformatted + input, and formatted output. + + + 68: + Extractors for char* should store null at end + + And they do now. An editing glitch in the last item in the list of + [27.6.1.2.3]/7. + + + 74: + Garbled text for codecvt::do_max_length + + The text of the standard was gibberish. Typos gone rampant. + + + 75: + Contradiction in codecvt::length's argument types + + Change the first parameter to stateT& and implement + the new effects paragraph. + + + 83: + string::npos vs. string::max_size() + + Safety checks on the size of the string should test against + max_size() rather than npos. + + + 90: + Incorrect description of operator>> for strings + + The effect contain isspace(c,getloc()) which must be + replaced by isspace(c,is.getloc()). + + + 91: + Description of operator>> and getline() for string<> + might cause endless loop + + They behave as a formatted input function and as an unformatted + input function, respectively (except that getline is + not required to set gcount). + + + 103: + set::iterator is required to be modifiable, but this allows + modification of keys. + + For associative containers where the value type is the same as + the key type, both iterator and const_iterator + are constant iterators. + + + 109: + Missing binders for non-const sequence elements + + The binder1st and binder2nd didn't have an + operator() taking a non-const parameter. + + + 110: + istreambuf_iterator::equal not const + + This was not a const member function. Note that the DR says to + replace the function with a const one; we have instead provided an + overloaded version with identical contents. + + + 117: + basic_ostream uses nonexistent num_put member functions + + num_put::put() was overloaded on the wrong types. + + + 118: + basic_istream uses nonexistent num_get member functions + + Same as 117, but for num_get::get(). + + + 129: + Need error indication from seekp() and seekg() + + These functions set failbit on error now. + + + 130: + Return type of container::erase(iterator) differs for associative containers + + Make member erase return iterator for set, multiset, map, multimap. + + + 136: + seekp, seekg setting wrong streams? + + seekp should only set the output stream, and + seekg should only set the input stream. + + + + + 167: + Improper use of traits_type::length() + + op<< with a const char* was + calculating an incorrect number of characters to write. + + + 169: + Bad efficiency of overflow() mandated + + Grow efficiently the internal array object. + + + 171: + Strange seekpos() semantics due to joint position + + Quite complex to summarize... + + + 181: + make_pair() unintended behavior + + This function used to take its arguments as reference-to-const, now + it copies them (pass by value). + + + 195: + Should basic_istream::sentry's constructor ever set eofbit? + + Yes, it can, specifically if EOF is reached while skipping whitespace. + + + 211: + operator>>(istream&, string&) doesn't set failbit + + If nothing is extracted into the string, op>> now + sets failbit (which can cause an exception, etc., etc.). + + + 214: + set::find() missing const overload + + Both set and multiset were missing + overloaded find, lower_bound, upper_bound, and equal_range functions + for const instances. + + + 231: + Precision in iostream? + + For conversion from a floating-point type, str.precision() + is specified in the conversion specification. + + + 233: + Insertion hints in associative containers + + Implement N1780, first check before then check after, insert as close + to hint as possible. + + + 235: + No specification of default ctor for reverse_iterator + + The declaration of reverse_iterator lists a default constructor. + However, no specification is given what this constructor should do. + + + 241: + Does unique_copy() require CopyConstructible and Assignable? + + Add a helper for forward_iterator/output_iterator, fix the existing + one for input_iterator/output_iterator to not rely on Assignability. + + + 243: + get and getline when sentry reports failure + + Store a null character only if the character array has a non-zero size. + + + 251: + basic_stringbuf missing allocator_type + + This nested typedef was originally not specified. + + + 253: + valarray helper functions are almost entirely useless + + Make the copy constructor and copy-assignment operator declarations + public in gslice_array, indirect_array, mask_array, slice_array; provide + definitions. + + + 265: + std::pair::pair() effects overly restrictive + + The default ctor would build its members from copies of temporaries; + now it simply uses their respective default ctors. + + + 266: + bad_exception::~bad_exception() missing Effects clause + + The bad_* classes no longer have destructors (they + are trivial), since no description of them was ever given. + + + 271: + basic_iostream missing typedefs + + The typedefs it inherits from its base classes can't be used, since + (for example) basic_iostream<T>::traits_type is ambiguous. + + + 275: + Wrong type in num_get::get() overloads + + Similar to 118. + + + 280: + Comparison of reverse_iterator to const reverse_iterator + + Add global functions with two template parameters. + (NB: not added for now a templated assignment operator) + + + 292: + Effects of a.copyfmt (a) + + If (this == &rhs) do nothing. + + + 300: + List::merge() specification incomplete + + If (this == &x) do nothing. + + + 303: + Bitset input operator underspecified + + Basically, compare the input character to + is.widen(0) and is.widen(1). + + + 305: + Default behavior of codecvt<wchar_t, char, + mbstate_t>::length() + + Do not specify what codecvt<wchar_t, char, + mbstate_t>::do_length must return. + + + 328: + Bad sprintf format modifier in + money_put<>::do_put() + + Change the format string to "%.0Lf". + + + 365: + Lack of const-qualification in clause 27 + + Add const overloads of is_open. + + + 387: + std::complex over-encapsulated + + Add the real(T) and imag(T) + members; in C++0x mode, also adjust the existing + real() and imag() members and + free functions. + + + 389: + Const overload of valarray::operator[] returns + by value + + Change it to return a const T&. + + + 396: + what are characters zero and one + + Implement the proposed resolution. + + + 402: + Wrong new expression in [some_]allocator::construct + + Replace "new" with "::new". + + + 408: + + Is vector<reverse_iterator<char*> > forbidden? + + + Tweak the debug-mode checks in _Safe_iterator. + + + 409: + Closing an fstream should clear the error state + + Have open clear the error flags. + + + 431: + Swapping containers with unequal allocators + + Implement Option 3, as per N1599. + + + 432: + stringbuf::overflow() makes only one write position + available + + Implement the resolution, beyond DR 169. + + + 434: + bitset::to_string() hard to use + + Add three overloads, taking fewer template arguments. + + + 438: + Ambiguity in the "do the right thing" clause + + Implement the resolution, basically cast less. + + + 453: + basic_stringbuf::seekoff need not always fail for an empty stream + + Don't fail if the next pointer is null and newoff is zero. + + + 455: + cerr::tie() and wcerr::tie() are overspecified + + Initialize cerr tied to cout and wcerr tied to wcout. + + + 464: + Suggestion for new member functions in standard containers + + Add data() to std::vector and + at(const key_type&) to std::map. + + + 508: + Bad parameters for ranlux64_base_01 + + Fix the parameters. + + + 512: + Seeding subtract_with_carry_01 from a single unsigned long + + Construct a linear_congruential engine and seed with it. + + + 526: + Is it undefined if a function in the standard changes in + parameters? + + Use &value. + + + 538: + 241 again: Does unique_copy() require CopyConstructible + and Assignable? + + In case of input_iterator/output_iterator rely on Assignability of + input_iterator' value_type. + + + 539: + partial_sum and adjacent_difference should mention + requirements + + We were almost doing the right thing, just use std::move + in adjacent_difference. + + + 541: + shared_ptr template assignment and void + + Add an auto_ptr<void> specialization. + + + 543: + valarray slice default constructor + + Follow the straightforward proposed resolution. + + + 550: + What should the return type of pow(float,int) be? + + In C++0x mode, remove the pow(float,int), etc., signatures. + + + 586: + string inserter not a formatted function + + Change it to be a formatted output function (i.e. catch exceptions). + + + 596: + 27.8.1.3 Table 112 omits "a+" and "a+b" modes + + Add the missing modes to fopen_mode. + + + 630: + arrays of valarray + + Implement the simple resolution. + + + 660: + Missing bitwise operations + + Add the missing operations. + + + 691: + const_local_iterator cbegin, cend missing from TR1 + + In C++0x mode add cbegin(size_type) and cend(size_type) + to the unordered containers. + + + 693: + std::bitset::all() missing + + Add it, consistently with the discussion. + + + 695: + ctype<char>::classic_table() not accessible + + Make the member functions table and classic_table public. + + + 696: + istream::operator>>(int&) broken + + Implement the straightforward resolution. + + + 761: + unordered_map needs an at() member function + + In C++0x mode, add at() and at() const. + + + 775: + Tuple indexing should be unsigned? + + Implement the int -> size_t replacements. + + + 776: + Undescribed assign function of std::array + + In C++0x mode, remove assign, add fill. + + + 781: + std::complex should add missing C99 functions + + In C++0x mode, add std::proj. + + + 809: + std::swap should be overloaded for array types + + Add the overload. + + + 844: + complex pow return type is ambiguous + + In C++0x mode, remove the pow(complex<T>, int) signature. + + + 853: + to_string needs updating with zero and one + + Update / add the signatures. + + + 865: + More algorithms that throw away information + + The traditional HP / SGI return type and value is blessed + by the resolution of the DR. + + + +
+
+ + + + +Setup + + + + To transform libstdc++ sources into installed include files + and properly built binaries useful for linking to other software is + a multi-step process. Steps include getting the sources, + configuring and building the sources, testing, and installation. + + + The general outline of commands is something like: + + + + get gcc sources + extract into gccsrcdir + mkdir gccbuilddir + cd gccbuilddir + gccsrcdir/configure --prefix=destdir --other-opts... + make + make check + make install + + + + Each step is described in more detail in the following sections. + + + + + + + + + + + +
Make + + + If you have never done this before, you should read the basic + GCC Installation + Instructions first. Read all of them. + Twice. + + +Then type: make, and congratulations, you've +started to build. + + +
+ + + + + + + + -- cgit v1.2.3