Gcc 3.2.1-prerelease from the FSF anoncvs repo gcc-3_2-branch on 16-Sep-2002 13:23:11 EDT.

11 files changed, 211 insertions, 51 deletions

diff --git a/contrib/gcc/doc/c-tree.texi b/contrib/gcc/doc/c-tree.texi
index 0e821e5..35da90a 100644
--- a/contrib/gcc/doc/c-tree.texi
+++ b/contrib/gcc/doc/c-tree.texi
@@ -1203,11 +1203,11 @@ Then, if @code{THUNK_VCALL_OFFSET} (an @code{INTEGER_CST}) is nonzero
 the adjusted @code{this} pointer must be adjusted again.  The complete
 calculation is given by the following pseudo-code:
 
-@example
+@smallexample
 this += THUNK_DELTA
 if (THUNK_VCALL_OFFSET)
   this += (*((ptrdiff_t **) this))[THUNK_VCALL_OFFSET]
-@end example
+@end smallexample
 
 Finally, the thunk should jump to the location given
 by @code{DECL_INITIAL}; this will always be an expression for the
diff --git a/contrib/gcc/doc/compat.texi b/contrib/gcc/doc/compat.texi
new file mode 100644
index 0000000..3e4ef89
--- /dev/null
+++ b/contrib/gcc/doc/compat.texi
@@ -0,0 +1,115 @@
+@c Copyright (C) 2002 Free Software Foundation, Inc.
+@c This is part of the GCC manual.
+@c For copying conditions, see the file gcc.texi.
+
+@node Compatibility
+@chapter Binary Compatibility
+@cindex binary compatibility
+@cindex ABI
+@cindex application binary interface
+
+Binary compatibility encompasses several related concepts:
+
+@table @dfn
+@item application binary interface (ABI)
+The set of runtime conventions followed by all of the tools that deal
+with binary representations of a program, including compilers, assemblers,
+linkers, and language runtime support.
+Some ABIs are formal with a written specification, possibly designed
+by multiple interested parties.  Others are simply the way things are
+actually done by a particular set of tools.
+
+@item ABI conformance
+A compiler conforms to an ABI if it generates code that follows all of
+the specifications enumerated by that ABI@.
+A library conforms to an ABI if it is implemented according to that ABI@.
+An application conforms to an ABI if it is built using tools that conform
+to that ABI and does not contain source code that specifically changes
+behavior specified by the ABI@.
+
+@item calling conventions
+Calling conventions are a subset of an ABI that specify of how arguments
+are passed and function results are returned.
+
+@item interoperability
+Different sets of tools are interoperable if they generate files that
+can be used in the same program.  The set of tools includes compilers,
+assemblers, linkers, libraries, header files, startup files, and debuggers.
+Binaries produced by different sets of tools are not interoperable unless
+they implement the same ABI@.  This applies to different versions of the
+same tools as well as tools from different vendors.
+
+@item intercallability
+Whether a function in a binary built by one set of tools can call a
+function in a binary built by a different set of tools is a subset
+of interoperability.
+
+@item implementation-defined features
+Language standards include lists of implementation-defined features whose
+behavior can vary from one implementation to another.  Some of these
+features are normally covered by a platform's ABI and others are not.
+The features that are not covered by an ABI generally affect how a
+program behaves, but not intercallability.
+
+@item compatibility
+Conformance to the same ABI and the same behavior of implementation-defined
+features are both relevant for compatibility.
+@end table
+
+The application binary interface implemented by a C or C++ compiler
+affects code generation and runtime support for:
+
+@itemize @bullet
+@item
+size and alignment of data types
+@item
+layout of structured types
+@item
+calling conventions
+@item
+register usage conventions
+@item
+interfaces for runtime arithmetic support
+@item
+object file formats
+@end itemize
+
+In addition, the application binary interface implemented by a C++ compiler
+affects code generation and runtime support for:
+@itemize @bullet
+@item
+name mangling
+@item
+exception handling
+@item
+invoking constructors and destructors
+@item
+layout, alignment, and padding of classes
+@item
+layout and alignment of virtual tables
+@end itemize
+
+Some GCC compilation options cause the compiler to generate code that
+does not conform to the platform's default ABI@.  Other options cause
+different program behavior for implementation-defined features that are
+not covered by an ABI@.  These options are provided for consistency with
+other compilers that do not follow the platform's default ABI or the
+usual behavior of implementation-defined features for the platform.
+Be very careful about using such options.
+
+Most platforms have a well-defined ABI that covers C code, but ABIs
+that cover C++ functionality are not yet common.
+
+Starting with GCC 3.2, GCC binary conventions for C++ are based on a
+written, vendor-neutral C++ ABI that was designed to be specific to
+64-bit Itanium but also includes generic specifications that apply to
+any platform.
+This C++ ABI is also implemented by other compiler vendors on some
+platforms, notably GNU/Linux and BSD systems.
+We have tried hard to provide a stable ABI that will be compatible with
+future GCC releases, but it is possible that we will encounter problems
+that make this difficult.  Such problems could include different
+interpretations of the C++ ABI by different vendors, bugs in the ABI, or
+bugs in the implementation of the ABI in different compilers.
+GCC's @code{-Wabi} switch warns when G++ generates code that is
+probably not compatible with the C++ ABI@.
diff --git a/contrib/gcc/doc/cppopts.texi b/contrib/gcc/doc/cppopts.texi
index 463403e..308e989 100644
--- a/contrib/gcc/doc/cppopts.texi
+++ b/contrib/gcc/doc/cppopts.texi
@@ -541,10 +541,10 @@ standard-conforming modes it converts them.  See the @option{-std} and
 
 The nine trigraphs and their replacements are
 
-@example
+@smallexample
 Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
 Replacement:      [    ]    @{    @}    #    \    ^    |    ~
-@end example
+@end smallexample
 @end ifclear
 
 @item -remap
diff --git a/contrib/gcc/doc/extend.texi b/contrib/gcc/doc/extend.texi
index 4a33eea..79eea70 100644
--- a/contrib/gcc/doc/extend.texi
+++ b/contrib/gcc/doc/extend.texi
@@ -739,7 +739,7 @@ GCC implements taking the address of a nested function using a technique
 called @dfn{trampolines}.  A paper describing them is available as
 
 @noindent
-@uref{http://people.debian.org/~karlheg/Usenix88-lexic.pdf}.
+@uref{http://people.debian.org/~aaronl/Usenix88-lexic.pdf}.
 
 A nested function can jump to a label inherited from a containing
 function, provided the label was explicitly declared in the containing
@@ -1396,9 +1396,9 @@ variable number of arguments much as a function can.  The syntax for
 defining the macro is similar to that of a function.  Here is an
 example:
 
-@example
+@smallexample
 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
-@end example
+@end smallexample
 
 Here @samp{@dots{}} is a @dfn{variable argument}.  In the invocation of
 such a macro, it represents the zero or more tokens until the closing
@@ -1437,9 +1437,9 @@ string.
 To help solve this problem, CPP behaves specially for variable arguments
 used with the token paste operator, @samp{##}.  If instead you write
 
-@example
+@smallexample
 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
-@end example
+@end smallexample
 
 and if the variable arguments are omitted or empty, the @samp{##}
 operator causes the preprocessor to remove the comma before it.  If you
@@ -1749,9 +1749,9 @@ nested subobject to initialize; the list is taken relative to the
 subobject corresponding to the closest surrounding brace pair.  For
 example, with the @samp{struct point} declaration above:
 
-@example
+@smallexample
 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
-@end example
+@end smallexample
 
 @noindent
 If the same field is initialized multiple times, it will have value from
@@ -6749,10 +6749,10 @@ inclusive.  Lower numbers indicate a higher priority.
 In the following example, @code{A} would normally be created before
 @code{B}, but the @code{init_priority} attribute has reversed that order:
 
-@example
+@smallexample
 Some_Class  A  __attribute__ ((init_priority (2000)));
 Some_Class  B  __attribute__ ((init_priority (543)));
-@end example
+@end smallexample
 
 @noindent
 Note that the particular values of @var{priority} do not matter; only their
@@ -6778,7 +6778,7 @@ appropriately.  However, if C++ code only needs to execute destructors
 when Java exceptions are thrown through it, GCC will guess incorrectly.
 Sample problematic code is:
 
-@example
+@smallexample
   struct S @{ ~S(); @};
   extern void bar();    // is written in Java, and may throw exceptions
   void foo()
@@ -6786,7 +6786,7 @@ Sample problematic code is:
     S s;
     bar();
   @}
-@end example
+@end smallexample
 
 @noindent
 The usual effect of an incorrect guess is a link failure, complaining of
diff --git a/contrib/gcc/doc/gcc.texi b/contrib/gcc/doc/gcc.texi
index 4af8694..fe51216 100644
--- a/contrib/gcc/doc/gcc.texi
+++ b/contrib/gcc/doc/gcc.texi
@@ -164,6 +164,7 @@ Introduction, gccint, GNU Compiler Collection (GCC) Internals}.
 * C Extensions::    GNU extensions to the C language family.
 * C++ Extensions::  GNU extensions to the C++ language.
 * Objective-C::     GNU Objective-C runtime features.
+* Compatibility::   Binary Compatibility
 * Gcov::	    gcov: a GCC test coverage program.
 * Trouble::         If you have trouble using GCC.
 * Bugs::            How, why and where to report bugs.
@@ -188,6 +189,7 @@ Introduction, gccint, GNU Compiler Collection (GCC) Internals}.
 @include invoke.texi
 @include extend.texi
 @include objc.texi
+@include compat.texi
 @include gcov.texi
 @include trouble.texi
 @include bugreport.texi
diff --git a/contrib/gcc/doc/invoke.texi b/contrib/gcc/doc/invoke.texi
index a3b53ed..d60d6fc 100644
--- a/contrib/gcc/doc/invoke.texi
+++ b/contrib/gcc/doc/invoke.texi
@@ -169,7 +169,7 @@ in the following sections.
 -fallow-single-precision  -fcond-mismatch @gol
 -fsigned-bitfields  -fsigned-char @gol
 -funsigned-bitfields  -funsigned-char @gol
--fwritable-strings  -fshort-wchar}
+-fwritable-strings}
 
 @item C++ Language Options
 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
@@ -279,8 +279,8 @@ in the following sections.
 -frerun-cse-after-loop  -frerun-loop-opt @gol
 -fschedule-insns  -fschedule-insns2 @gol
 -fsingle-precision-constant  -fssa -fssa-ccp -fssa-dce @gol
--fstrength-reduce  -fstrict-aliasing  -fthread-jumps  -ftrapv @gol
--funroll-all-loops  -funroll-loops  @gol
+-fstrength-reduce  -fstrict-aliasing  -fthread-jumps @gol
+-ftrapv -funroll-all-loops  -funroll-loops  @gol
 --param @var{name}=@var{value}
 -O  -O0  -O1  -O2  -O3  -Os}
 
@@ -444,7 +444,7 @@ in the following sections.
 -mno-relocatable  -mrelocatable-lib  -mno-relocatable-lib @gol
 -mtoc  -mno-toc -mlittle  -mlittle-endian  -mbig  -mbig-endian @gol
 -mcall-aix -mcall-sysv -mcall-netbsd @gol
--maix-struct-return -msvr4-struct-return
+-maix-struct-return -msvr4-struct-return @gol
 -mabi=altivec -mabi=no-altivec @gol
 -mprototype  -mno-prototype @gol
 -msim  -mmvme  -mads  -myellowknife  -memb -msdata @gol
@@ -610,8 +610,8 @@ in the following sections.
 
 @emph{D30V Options}
 @gccoptlist{
--mextmem  -mextmemory  -monchip  -mno-asm-optimize  -masm-optimize @gol
--mbranch-cost=@var{n} -mcond-exec=@var{n}}
+-mextmem  -mextmemory  -monchip  -mno-asm-optimize @gol
+-masm-optimize -mbranch-cost=@var{n} -mcond-exec=@var{n}}
 
 @emph{S/390 and zSeries Options}
 @gccoptlist{
@@ -670,7 +670,7 @@ in the following sections.
 -fno-common  -fno-ident  -fno-gnu-linker @gol
 -fpcc-struct-return  -fpic  -fPIC @gol
 -freg-struct-return  -fshared-data  -fshort-enums @gol
--fshort-double  -fvolatile @gol
+-fshort-double  -fshort-wchar -fvolatile @gol
 -fvolatile-global  -fvolatile-static @gol
 -fverbose-asm  -fpack-struct  -fstack-check @gol
 -fstack-limit-register=@var{reg}  -fstack-limit-symbol=@var{sym} @gol
@@ -1297,12 +1297,6 @@ than double precision.   If you must use @option{-traditional}, but want
 to use single precision operations when the operands are single
 precision, use this option.   This option has no effect when compiling
 with ISO or GNU C conventions (the default).
-
-@item -fshort-wchar
-@opindex fshort-wchar
-Override the underlying type for @samp{wchar_t} to be @samp{short
-unsigned int} instead of the default for the target.  This option is
-useful for building programs to run under WINE@.
 @end table
 
 @node C++ Dialect Options
@@ -9716,7 +9710,8 @@ unwinding from asynchronous events (such as debugger or garbage collector).
 Return ``short'' @code{struct} and @code{union} values in memory like
 longer ones, rather than in registers.  This convention is less
 efficient, but it has the advantage of allowing intercallability between
-GCC-compiled files and files compiled with other compilers.
+GCC-compiled files and files compiled with other compilers, particularly
+the Portable C Compiler (pcc).
 
 The precise convention for returning structures in memory depends
 on the target configuration macros.
@@ -9724,6 +9719,11 @@ on the target configuration macros.
 Short structures and unions are those whose size and alignment match
 that of some integer type.
 
+@strong{Warning:} code compiled with the @option{-fpcc-struct-return}
+switch is not binary compatible with code compiled with the
+@option{-freg-struct-return} switch.
+Use it to conform to a non-default application binary interface.
+
 @item -freg-struct-return
 @opindex freg-struct-return
 Return @code{struct} and @code{union} values in registers when possible.
@@ -9737,16 +9737,39 @@ defaults to @option{-fpcc-struct-return}, except on targets where GCC is
 the principal compiler.  In those cases, we can choose the standard, and
 we chose the more efficient register return alternative.
 
+@strong{Warning:} code compiled with the @option{-freg-struct-return}
+switch is not binary compatible with code compiled with the
+@option{-fpcc-struct-return} switch.
+Use it to conform to a non-default application binary interface.
+
 @item -fshort-enums
 @opindex fshort-enums
 Allocate to an @code{enum} type only as many bytes as it needs for the
 declared range of possible values.  Specifically, the @code{enum} type
 will be equivalent to the smallest integer type which has enough room.
 
+@strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Use it to conform to a non-default application binary interface.
+
 @item -fshort-double
 @opindex fshort-double
 Use the same size for @code{double} as for @code{float}.
 
+@strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Use it to conform to a non-default application binary interface.
+
+@item -fshort-wchar
+@opindex fshort-wchar
+Override the underlying type for @samp{wchar_t} to be @samp{short
+unsigned int} instead of the default for the target.  This option is
+useful for building programs to run under WINE@.
+
+@strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Use it to conform to a non-default application binary interface.
+
 @item -fshared-data
 @opindex fshared-data
 Requests that the data and non-@code{const} variables of this
@@ -9888,9 +9911,12 @@ three-way choice.
 
 @item -fpack-struct
 @opindex fpack-struct
-Pack all structure members together without holes.  Usually you would
-not want to use this option, since it makes the code suboptimal, and
-the offsets of structure members won't agree with system libraries.
+Pack all structure members together without holes.
+
+@strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
+code that is not binary compatible with code generated without that switch.
+Additionally, it makes the code suboptimial.
+Use it to conform to a non-default application binary interface.
 
 @item -finstrument-functions
 @opindex finstrument-functions
@@ -9987,8 +10013,10 @@ This option and its counterpart, @option{-fno-leading-underscore}, forcibly
 change the way C symbols are represented in the object file.  One use
 is to help link with legacy assembly code.
 
-Be warned that you should know what you are doing when invoking this
-option, and that not all targets provide complete support for it.
+@strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
+generate code that is not binary compatible with code generated without that
+switch.  Use it to conform to a non-default application binary interface.
+Not all targets provide complete support for this switch.
 @end table
 
 @c man end
diff --git a/contrib/gcc/doc/makefile.texi b/contrib/gcc/doc/makefile.texi
index 69d621b..6d6b025 100644
--- a/contrib/gcc/doc/makefile.texi
+++ b/contrib/gcc/doc/makefile.texi
@@ -48,9 +48,9 @@ You can specify specific tests by setting RUNTESTFLAGS to be the name
 of the @file{.exp} file, optionally followed by (for some tests) an equals
 and a file wildcard, like:
 
-@example
+@smallexample
 make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
-@end example
+@end smallexample
 
 Note that running the testsuite may require additional tools be
 installed, such as TCL or dejagnu.
diff --git a/contrib/gcc/doc/rtl.texi b/contrib/gcc/doc/rtl.texi
index 2151047..56a02d3 100644
--- a/contrib/gcc/doc/rtl.texi
+++ b/contrib/gcc/doc/rtl.texi
@@ -2316,11 +2316,11 @@ An hypothetical example might be a pattern for an addition that can
 either wrap around or use saturating addition depending on the value
 of a special control register:
 
-@example
+@smallexample
 (parallel [(set (reg:SI 2) (unspec:SI [(reg:SI 3)
                                        (reg:SI 4)] 0))
            (use (reg:SI 1))])
-@end example
+@end smallexample
 
 @noindent
 
@@ -2552,10 +2552,10 @@ where @var{z} is an index register and @var{i} is a constant.
 
 Here is an example of its use:
 
-@example
+@smallexample
 (mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
                                           (reg:SI 48))))
-@end example
+@end smallexample
 
 This says to modify pseudo register 42 by adding the contents of pseudo
 register 48 to it, after the use of what ever 42 points to.
diff --git a/contrib/gcc/doc/standards.texi b/contrib/gcc/doc/standards.texi
index 25fbb45..b3e8b18 100644
--- a/contrib/gcc/doc/standards.texi
+++ b/contrib/gcc/doc/standards.texi
@@ -168,11 +168,19 @@ information concerning the history of C that is available online, see
 
 There is no formal written standard for Objective-C@.  The most
 authoritative manual is ``Object-Oriented Programming and the
-Objective-C Language'', available at a number of web sites;
-@uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/} has a
-recent version, while @uref{http://www.toodarkpark.org/computers/objc/}
-is an older example.  @uref{http://www.gnustep.org} includes useful
-information as well.
+Objective-C Language'', available at a number of web sites
+
+@itemize
+@item
+@uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/}
+is a recent version
+@item
+@uref{http://www.toodarkpark.org/computers/objc/}
+is an older example
+@item
+@uref{http://www.gnustep.org}
+has additional useful information
+@end itemize
 
 @xref{Top, GNAT Reference Manual, About This Guide, gnat_rm,
 GNAT Reference Manual}, for information on standard
diff --git a/contrib/gcc/doc/tm.texi b/contrib/gcc/doc/tm.texi
index 2e3ad05..d8821c5 100644
--- a/contrib/gcc/doc/tm.texi
+++ b/contrib/gcc/doc/tm.texi
@@ -156,11 +156,11 @@ such as one option that enables many options, some of which select
 multilibs.  Example nonsensical definition, where @code{-malt-abi},
 @code{-EB}, and @code{-mspoo} cause different multilibs to be chosen:
 
-@example
+@smallexample
 #define TARGET_OPTION_TRANSLATE_TABLE \
 @{ "-fast",   "-march=fast-foo -malt-abi -I/usr/fast-foo" @}, \
 @{ "-compat", "-EB -malign=4 -mspoo" @}
-@end example
+@end smallexample
 
 @findex CPP_SPEC
 @item CPP_SPEC
@@ -7423,6 +7423,11 @@ argument @var{name} is the name of an assembler symbol (for use with
 @item DBX_OUTPUT_RBRAC (@var{stream}, @var{name})
 Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level.
 
+@findex DBX_OUTPUT_NFUN
+@item DBX_OUTPUT_NFUN (@var{stream}, @var{lscope_label}, @var{decl})
+Define this macro if the target machine requires special handling to
+output an @code{N_FUN} entry for the function @var{decl}.
+
 @findex DBX_OUTPUT_ENUM
 @item DBX_OUTPUT_ENUM (@var{stream}, @var{type})
 Define this macro if the target machine requires special handling to
diff --git a/contrib/gcc/doc/trouble.texi b/contrib/gcc/doc/trouble.texi
index 09026fe..4cfef9f 100644
--- a/contrib/gcc/doc/trouble.texi
+++ b/contrib/gcc/doc/trouble.texi
@@ -105,11 +105,13 @@ libraries and debuggers on certain systems.
 
 @itemize @bullet
 @item
-G++ does not do name mangling in the same way as other C++
-compilers.  This means that object files compiled with one compiler
-cannot be used with another.
+On many platforms, GCC supports a different ABI for C++ than do other
+compilers, so the object files compiled by GCC cannot be used with object
+files generated by another C++ compiler.
 
-This effect is intentional, to protect you from more subtle problems.
+An area where the difference is most apparent is name mangling.  The use
+of different name mangling is intentional, to protect you from more subtle
+problems.
 Compilers differ as to many internal details of C++ implementation,
 including: how class instances are laid out, how multiple inheritance is
 implemented, and how virtual function calls are handled.  If the name