abi.txt: New file.

2002-07-20  Phil Edwards  <pme@gcc.gnu.org>

	* docs/html/abi.txt:  New file.
	* docs/html/23_containers/howto.html:  Tweak vector-overhead text.
	* docs/html/ext/lwg-active.html, docs/html/ext/lwg-defects.html:
	Import from upstream, R22.

	* include/bits/char_traits.h, include/bits/stl_iterator.h,
	include/bits/stl_iterator_base_types.h, libsupc++/exception,
	libsupc++/new, libsupc++/typeinfo:  Use @brief markup.

	* include/bits/deque.tcc, include/bits/stl_alloc.h,
	include/bits/stl_deque.h, include/bits/stl_list.h:  Postpone removal
	of deprecated functions until 3.4.  (Same timeframe, different text.)
	* include/bits/stl_vector.h:  Ditto.  Also do the same cleanups that
	the other sequence classes received.

From-SVN: r55602

libstdc++-v3/ChangeLog

+2002-07-20  Phil Edwards  <pme@gcc.gnu.org>
+
+	* docs/html/abi.txt:  New file.
+	* docs/html/23_containers/howto.html:  Tweak vector-overhead text.
+	* docs/html/ext/lwg-active.html, docs/html/ext/lwg-defects.html:
+	Import from upstream, R22.
+
+	* include/bits/char_traits.h, include/bits/stl_iterator.h,
+	include/bits/stl_iterator_base_types.h, libsupc++/exception,
+	libsupc++/new, libsupc++/typeinfo:  Use @brief markup.
+
+	* include/bits/deque.tcc, include/bits/stl_alloc.h,
+	include/bits/stl_deque.h, include/bits/stl_list.h:  Postpone removal
+	of deprecated functions until 3.4.  (Same timeframe, different text.)
+	* include/bits/stl_vector.h:  Ditto.  Also do the same cleanups that
+	the other sequence classes received.
+
 2002-07-18  Brendan Kehoe  <brendan@zen.org>
 
 	* bits/slice_array.h (_DEFINE_VALARRAY_OPERATOR): Fix typo of

libstdc++-v3/docs/html/23_containers/howto.html

@@ -27,7 +27,7 @@
    <li><a href="#4">&quot;Hinting&quot; during insertion</a>
    <li><a href="#5">Bitmasks and string arguments</a>
    <li><a href="#6"><code>std::list::size()</code> is O(n)!</a>
-   <li><a href="#7">Memory management for vectors</a>
+   <li><a href="#7">Space overhead management for vectors</a>
 </ul>
 
 <hr>
@@ -434,17 +434,19 @@
    </p>
 
 <hr>
-<h2><a name="7">Memory management for vectors</h2>
+<h2><a name="7">Space overhead management for vectors</h2>
    <p>In
       <a href="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html">this
       message to the list</a>, Daniel Kostecky announced work on an
       alternate form of <code>std::vector</code> that would support hints
-      about free store management.  The design was also described, along
-      with possible implementation choices.
-   </p>
-   <p>The first alpha release was announced
-      <a href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00048.html">recently</a>
-      and the releases themselves are available at
+      on the number of elements to be over-allocated.  The design was also
+      described, along with possible implementation choices.
+   </p>
+   <p>The first two alpha releases were announced
+      <a href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00048.html">here</a>
+      and
+      <a href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00111.html">here</a>.
+      The releases themselves are available at
       <a href="http://www.kotelna.sk/dk/sw/caphint/">
       http://www.kotelna.sk/dk/sw/caphint/</a>.
    </p>

libstdc++-v3/docs/html/abi.txt

+
+===========================
+
+See http://gcc.gnu.org/ml/libstdc++/2002-07/msg00054.html for why this
+document exists, why it's incomplete, and what needs to be done still.
+
+===========================
+
+2002-07-01 Benjamin Kosnik
+
+Description of the libstdc++ ABI.
+
+I. What is an ABI? What's covered? What's not?
+
+- What's the deal with C++? Why can't different compiler's object
+  files link with each other? Bug? Feature?
+
+- scope of document, of use to system integrators.
+
+- compilation includes and linked library binary must match up..
+
+- library ABI, compiler ABI different (but effects)
+
+- GNU C++ does not have a compiler command line option to switch
+  between various different C++ ABIs. For instance, there is no way to
+  switch between the gcc-3.0.x ABI, gcc-3.1.x ABI, and the gcc-3.2.x
+  ABI during compilation. Other C++ compilers do allow this, and some
+  g++ command line options may change the ABI (-fno-exceptions, see
+  the complete list), but there is no version switch. Sorry. The GNU
+  Project recommends that
+
+- shared library only, static is immutable.
+
+- Minimum environment that supports a versioned ABI: what's needed?  A
+  supported dynamic linker, a GNU linker of sufficient vintage to
+  understand demangled C++ name globbing (ld), a shared executable
+  compiled with g++, and shared libraries (libgcc_s, libstdc++-v3)
+  compiled by a compiler (g++) with a compatible ABI. Phew.
+
+  On top of all that, an additional constraint: libstdc++ did not
+  attempt to version symbols (or age gracefully, really) until version
+  3.1.0. 
+
+  Most modern Linux and BSD versions, particularly ones using
+  gcc-3.1.x tools, will meet the requirements above.
+
+- What configure options impact symbol versioning?
+  There is only one: --enable-symvers. For more information see:
+  http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html
+
+  In particular, libstdc++-v3/acinclude.m4 has a macro called
+  GLIBCPP_ENABLE_SYMVERS that defaults to yes (or the argument passed
+  in via --enable-symvers=foo). At that point, the macro attempts to
+  make sure that all the requirement for symbol versioning are in
+  place. For more information, please consult acinclude.m4. 
+
+- How can I tell if symbol versioning is, indeed, active? 
+
+  When the GNU C++ library is being built with symbol versioning on,
+  you should see the following at configure time for libstdc++-v3:
+
+checking versioning on shared library symbols... gnu
+
+  If you don't see this line in the configure output, or if this line
+  appears but the last word is 'no', then you are out of luck.
+
+  If the compiler is pre-installed, a quick way to test is to compile
+  the following (or any) simple C++ file:
+
+#include <iostream>
+
+int main()
+{ std::cout << "hello" << std::endl; return 0; }
+
+%g++ hello.cc -o hello.out
+%nm hello.out
+
+If you see symbols in the resulting output with "GLIBCPP_3.x" as part
+of the name, then the executable is versioned. Here's an example:
+
+         U _ZNSt8ios_base4InitC1Ev@@GLIBCPP_3.1
+
+
+
+
+
+
+II. ABI changes
+
+- (anything) changing size of an exported symbol
+
+- (anything) changing alignment of an exported symbol
+
+- (anything) changing the layout of an exported symbol
+
+- (anything) changing mangling on an exported symbol
+
+- (anything) adding or deleting an exported symbol
+
+
+III. Versioning
+
+- include files
+
+  - versioning headers with version, why necessary
+    (need to control member/non-member functions, add delete files)
+
+- shared library binaries
+
+  - release versions
+
+  - libtool versions
+
+  - when does so version get a bump? what are the options?
+
+  - how is the link map used?  
+
+  - in an non-abi breaking minor release, how are symbols added?
+    removed?
+
+  - in an abi-breaking major release, what happens? symbol fall back
+
+
+IV. Testing ABI changes
+
+- 'make check-abi'??
+
+- other ABI checkers
+
+
+V. Issues not directly addressed, and possible suggestions
+
+- what to do about multi-ABI systems (nathan scenario)?
+
+  - compatibility libs
+
+  --enable-version-specific-runtime-libs
+
+  - Alexandre Oliva proposal to have extended name attributes, modify ld
+ 
+  - directory-level versioning
+
+- wrapping C++ API's n "C" to use the C ABI.
+
+
+V. References
+
+ABIcheck, a vauge idea of checking ABI compatibility
+http://abicheck.sourceforge.net/
+
+C++ ABI reference
+http://www.codesourcery.com/cxx-abi/
+
+Intel ABI documentation
+"Intel® Compilers for Linux* -Compatibility with the GNU Compilers"
+(included in icc 6.0)
+
+Sun Solaris 2.9 docs
+Linker and Libraries Guide (document 816-1386)
+C++ Migration Guide (document 816-2459)
+http://docs.sun.com/db/prod/solaris.9
+http://docs.sun.com/?p=/doc/816-1386&a=load
+
+Ulrich Drepper, "ELF Symbol Versioning"
+http://people.redhat.com/drepper/symbol-versioning
+

libstdc++-v3/include/bits/char_traits.h

@@ -46,9 +46,13 @@
 
 namespace std 
 {
-  /// 21.1.2 Basis for explicit _Traits specialization 
-  /// NB: That for any given actual character type this definition is
-  /// probably wrong.
+  // 21.1.2
+  /**
+   *  @brief  Basis for explicit traits specializations.
+   *
+   *  @note  For any given actual character type, this definition is
+   *  probably wrong.
+  */
   template<class _CharT>
     struct char_traits
     {

libstdc++-v3/include/bits/deque.tcc

@@ -516,7 +516,7 @@ template <typename _Tp, typename _Alloc>
 // Nothing seems to actually use this.  According to the pattern followed by
 // the rest of the SGI code, it would be called by the deprecated insert(pos)
 // function, but that has been replaced.  We'll take our time removing this
-// anyhow; mark for 3.3.  -pme
+// anyhow; mark for 3.4.  -pme
 template <typename _Tp, typename _Alloc>
   typename deque<_Tp,_Alloc>::iterator 
   deque<_Tp,_Alloc>::

libstdc++-v3/include/bits/stl_alloc.h

@@ -75,7 +75,7 @@
  *  @endif
  *
  *  @note The @c reallocate member functions have been deprecated for 3.2
- *        and will be removed in 3.3.  You must define @c _GLIBCPP_DEPRECATED
+ *        and will be removed in 3.4.  You must define @c _GLIBCPP_DEPRECATED
  *        to make this visible in 3.2; see c++config.h.
  *
  *  The canonical description of these classes is in docs/html/ext/howto.html
@@ -221,7 +221,8 @@ namespace std
   /**
    *  @if maint
    *  This is used primarily (only?) in _Alloc_traits and other places to
-   *  help provide the _Alloc_type typedef.
+   *  help provide the _Alloc_type typedef.  All it does is forward the
+   *  requests after some minimal checking.
    *
    *  This is neither "standard"-conforming nor "SGI".  The _Alloc parameter
    *  must be "SGI" style.
@@ -620,8 +621,10 @@ namespace std
 
 
   /**
-   *  This is a "standard" allocator, as per [20.4].  The private _Alloc is
-   *  "SGI" style.  (See comments at the top of stl_alloc.h.)
+   *  @brief  The "standard" allocator, as per [20.4].
+   *
+   *  The private _Alloc is "SGI" style.  (See comments at the top
+   *  of stl_alloc.h.)
    *
    *  The underlying allocator behaves as follows.
    *  - if __USE_MALLOC then

libstdc++-v3/include/bits/stl_deque.h

@@ -1034,7 +1034,7 @@ public:
    *  of a %deque this operation can be done in constant time.  You should
    *  consider using push_front(value_type()) instead.
    *
-   *  @note This was deprecated in 3.2 and will be removed in 3.3.  You must
+   *  @note This was deprecated in 3.2 and will be removed in 3.4.  You must
    *        define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
    *        c++config.h.
   */
@@ -1078,7 +1078,7 @@ public:
    *  of a %deque this operation can be done in constant time.  You should
    *  consider using push_back(value_type()) instead.
    *
-   *  @note This was deprecated in 3.2 and will be removed in 3.3.  You must
+   *  @note This was deprecated in 3.2 and will be removed in 3.4.  You must
    *        define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
    *        c++config.h.
   */
@@ -1154,7 +1154,7 @@ public:
    *  specified location.  You should consider using
    *  insert(position,value_type()) instead.
    *
-   *  @note This was deprecated in 3.2 and will be removed in 3.3.  You must
+   *  @note This was deprecated in 3.2 and will be removed in 3.4.  You must
    *        define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
    *        c++config.h.
   */

libstdc++-v3/include/bits/stl_iterator.h

@@ -317,6 +317,8 @@ namespace std
 
   // 24.4.2.2.1 back_insert_iterator
   /**
+   *  @brief  Turns assignment into insertion.
+   *
    *  These are output iterators, constructed from a container-of-T.
    *  Assigning a T to the iterator appends it to the container using
    *  push_back.
@@ -387,6 +389,8 @@ namespace std
     { return back_insert_iterator<_Container>(__x); }
 
   /**
+   *  @brief  Turns assignment into insertion.
+   *
    *  These are output iterators, constructed from a container-of-T.
    *  Assigning a T to the iterator prepends it to the container using
    *  push_front.
@@ -456,6 +460,8 @@ namespace std
     { return front_insert_iterator<_Container>(__x); }
 
   /**
+   *  @brief  Turns assignment into insertion.
+   *
    *  These are output iterators, constructed from a container-of-T.
    *  Assigning a T to the iterator inserts it in the container at the
    *  %iterator's position, rather than overwriting the value at that

libstdc++-v3/include/bits/stl_iterator_base_types.h

@@ -68,13 +68,12 @@
 
 namespace std
 {
-  /**
+  /** @{
    *  @defgroup iterator_tags Iterator Tags
    *  These are empty types, used to distinguish different iterators.  The
    *  distinction is not made by what they contain, but simply by what they
    *  are.  Different underlying algorithms can then be used based on the
    *  different operations supporetd by different iterator types.
-   *  @{
   */
   ///  Marking input iterators.
   struct input_iterator_tag {};
@@ -90,6 +89,8 @@ namespace std
 
 
   /**
+   *  @brief  Common %iterator class.
+   *
    *  This class does nothing but define nested typedefs.  %Iterator classes
    *  can inherit from this class to save some work.  The typedefs are then
    *  used in specializations and overloading.
@@ -98,8 +99,9 @@ namespace std
    *  such as @c operator++ and the like.  (How could there be?)
   */
   template<typename _Category, typename _Tp, typename _Distance = ptrdiff_t,
-	   typename _Pointer = _Tp*, typename _Reference = _Tp&>
-    struct iterator {
+           typename _Pointer = _Tp*, typename _Reference = _Tp&>
+    struct iterator
+    {
       /// One of the @link iterator_tags tag types@endlink.
       typedef _Category  iterator_category;
       /// The type "pointed to" by the iterator.

libstdc++-v3/include/bits/stl_list.h

@@ -715,7 +715,7 @@ public:
    *  of a %list this operation can be done in constant time.  You should
    *  consider using push_front(value_type()) instead.
    *
-   *  @note This was deprecated in 3.2 and will be removed in 3.3.  You must
+   *  @note This was deprecated in 3.2 and will be removed in 3.4.  You must
    *        define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
    *        c++config.h.
   */
@@ -758,7 +758,7 @@ public:
    *  of a %list this operation can be done in constant time.  You should
    *  consider using push_back(value_type()) instead.
    *
-   *  @note This was deprecated in 3.2 and will be removed in 3.3.  You must
+   *  @note This was deprecated in 3.2 and will be removed in 3.4.  You must
    *        define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
    *        c++config.h.
   */
@@ -810,7 +810,7 @@ public:
    *  Due to the nature of a %list this operation can be done in constant
    *  time, and does not invalidate iterators and references.
    *
-   *  @note This was deprecated in 3.2 and will be removed in 3.3.  You must
+   *  @note This was deprecated in 3.2 and will be removed in 3.4.  You must
    *        define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
    *        c++config.h.
   */

libstdc++-v3/include/bits/stl_vector.h

@@ -253,7 +253,7 @@ public:
   explicit
   vector(size_type __n)
     : _Base(__n, allocator_type())
-    { _M_finish = uninitialized_fill_n(_M_start, __n, _Tp()); }
+    { _M_finish = uninitialized_fill_n(_M_start, __n, value_type()); }
 
   /**
    *  @brief  %Vector copy constructor.
@@ -489,7 +489,6 @@ public:
   */
   reference
   operator[](size_type __n) { return *(begin() + __n); }
-  // XXX do we need to convert to normal_iterator first?
 
   /**
    *  @brief  Subscript access to the data contained in the %vector.
@@ -545,7 +544,6 @@ public:
   */
   reference
   front() { return *begin(); }
-  // XXX do we need to convert to normal_iterator first?
 
   /**
    *  Returns a read-only (constant) reference to the data at the first
@@ -631,7 +629,7 @@ public:
    *  Note that this kind of operation could be expensive for a vector and if
    *  it is frequently used the user should consider using std::list.
    *
-   *  @note This was deprecated in 3.2 and will be removed in 3.3.  You must
+   *  @note This was deprecated in 3.2 and will be removed in 3.4.  You must
    *        define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
    *        c++config.h.
   */
@@ -914,7 +912,7 @@ protected:
 */
 template <typename _Tp, typename _Alloc>
   inline bool
-  operator==(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
+  operator==(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
   {
     return __x.size() == __y.size() &&
            equal(__x.begin(), __x.end(), __y.begin());
@@ -933,7 +931,7 @@ template <typename _Tp, typename _Alloc>
 */
 template <typename _Tp, typename _Alloc>
   inline bool
-  operator<(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
+  operator<(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
   {
     return lexicographical_compare(__x.begin(), __x.end(),
                                    __y.begin(), __y.end());
@@ -941,40 +939,34 @@ template <typename _Tp, typename _Alloc>
 
 /// Based on operator==
 template <typename _Tp, typename _Alloc>
-inline bool
-operator!=(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y) {
-  return !(__x == __y);
-}
+  inline bool
+  operator!=(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
+  { return !(__x == __y); }
 
 /// Based on operator<
 template <typename _Tp, typename _Alloc>
-inline bool
-operator>(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y) {
-  return __y < __x;
-}
+  inline bool
+  operator>(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
+  { return __y < __x; }
 
 /// Based on operator<
 template <typename _Tp, typename _Alloc>
-inline bool
-operator<=(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y) {
-  return !(__y < __x);
-}
+  inline bool
+  operator<=(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
+  { return !(__y < __x); }
 
 /// Based on operator<
 template <typename _Tp, typename _Alloc>
-inline bool
-operator>=(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y) {
-  return !(__x < __y);
-}
+  inline bool
+  operator>=(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
+  { return !(__x < __y); }
 
 /// See std::vector::swap().
 template <typename _Tp, typename _Alloc>
-inline void swap(vector<_Tp, _Alloc>& __x, vector<_Tp, _Alloc>& __y)
-{
-  __x.swap(__y);
-}
+  inline void
+  swap(vector<_Tp,_Alloc>& __x, vector<_Tp,_Alloc>& __y)
+  { __x.swap(__y); }
 
 } // namespace std
 
 #endif /* __GLIBCPP_INTERNAL_VECTOR_H */
-

libstdc++-v3/libsupc++/exception

@@ -41,11 +41,13 @@ extern "C++" {
 
 namespace std 
 {
-  /** This is the base class for all exceptions thrown by the standard
+  /**
+   *  @brief Base class for all library exceptions.
+   *
+   *  This is the base class for all exceptions thrown by the standard
    *  library, and by certain language expressions.  You are free to derive
    *  your own %exception classes, or use a different hierarchy, or to
    *  throw non-class data (e.g., fundamental types).
-   *  @brief Base class for all library exceptions.
    */
   class exception 
   {

libstdc++-v3/libsupc++/new

@@ -45,7 +45,10 @@ extern "C++" {
 
 namespace std 
 {
-  /** @c bad_alloc (or classes derived from it) is used to report allocation
+  /**
+   *  @brief  Exception possibly thrown by @c new.
+   *
+   *  @c bad_alloc (or classes derived from it) is used to report allocation
    *  errors from the throwing forms of @c new.  */
   class bad_alloc : public exception 
   {

libstdc++-v3/libsupc++/typeinfo

@@ -54,9 +54,12 @@ namespace __cxxabiv1
 
 namespace std 
 {
-  /** The @c type_info class describes type information generated by
+  /**
+   *  @brief  Part of RTTI.
+   *
+   *  The @c type_info class describes type information generated by
    *  an implementation.
-   *  @brief Used in RTTI.  */
+  */
   class type_info 
   {
   public:
@@ -124,7 +127,10 @@ namespace std
 			     void **__obj_ptr) const;
   };
 
-  /** If you attempt an invalid @c dynamic_cast expression, an instance of
+  /**
+   *  @brief  Thrown during incorrect typecasting.
+   *
+   *  If you attempt an invalid @c dynamic_cast expression, an instance of
    *  this class (or something derived from this class) is thrown.  */
   class bad_cast : public exception 
   {