--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/gcc/doc/trouble.texi	Fri Jul 17 14:47:48 2009 +0900
@@ -0,0 +1,1312 @@
+@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+@c 1999, 2000, 2001, 2003, 2004, 2005, 2006, 2007, 2008
+@c Free Software Foundation, Inc.
+@c This is part of the GCC manual.
+@c For copying conditions, see the file gcc.texi.
+
+@node Trouble
+@chapter Known Causes of Trouble with GCC
+@cindex bugs, known
+@cindex installation trouble
+@cindex known causes of trouble
+
+This section describes known problems that affect users of GCC@.  Most
+of these are not GCC bugs per se---if they were, we would fix them.
+But the result for a user may be like the result of a bug.
+
+Some of these problems are due to bugs in other software, some are
+missing features that are too much work to add, and some are places
+where people's opinions differ as to what is best.
+
+@menu
+* Actual Bugs::         Bugs we will fix later.
+* Cross-Compiler Problems:: Common problems of cross compiling with GCC.
+* Interoperation::      Problems using GCC with other compilers,
+                        and with certain linkers, assemblers and debuggers.
+* Incompatibilities::   GCC is incompatible with traditional C.
+* Fixed Headers::       GCC uses corrected versions of system header files.
+                        This is necessary, but doesn't always work smoothly.
+* Standard Libraries::  GCC uses the system C library, which might not be
+                        compliant with the ISO C standard.
+* Disappointments::     Regrettable things we can't change, but not quite bugs.
+* C++ Misunderstandings:: Common misunderstandings with GNU C++.
+* Protoize Caveats::    Things to watch out for when using @code{protoize}.
+* Non-bugs::            Things we think are right, but some others disagree.
+* Warnings and Errors:: Which problems in your code get warnings,
+                        and which get errors.
+@end menu
+
+@node Actual Bugs
+@section Actual Bugs We Haven't Fixed Yet
+
+@itemize @bullet
+@item
+The @code{fixincludes} script interacts badly with automounters; if the
+directory of system header files is automounted, it tends to be
+unmounted while @code{fixincludes} is running.  This would seem to be a
+bug in the automounter.  We don't know any good way to work around it.
+
+@item
+The @code{fixproto} script will sometimes add prototypes for the
+@code{sigsetjmp} and @code{siglongjmp} functions that reference the
+@code{jmp_buf} type before that type is defined.  To work around this,
+edit the offending file and place the typedef in front of the
+prototypes.
+@end itemize
+
+@node Cross-Compiler Problems
+@section Cross-Compiler Problems
+
+You may run into problems with cross compilation on certain machines,
+for several reasons.
+
+@itemize @bullet
+@item
+At present, the program @file{mips-tfile} which adds debug
+support to object files on MIPS systems does not work in a cross
+compile environment.
+@end itemize
+
+@node Interoperation
+@section Interoperation
+
+This section lists various difficulties encountered in using GCC
+together with other compilers or with the assemblers, linkers,
+libraries and debuggers on certain systems.
+
+@itemize @bullet
+@item
+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.
+
+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
+encoding were made the same, your programs would link against libraries
+provided from other compilers---but the programs would then crash when
+run.  Incompatible libraries are then detected at link time, rather than
+at run time.
+
+@item
+On some BSD systems, including some versions of Ultrix, use of profiling
+causes static variable destructors (currently used only in C++) not to
+be run.
+
+@item
+On some SGI systems, when you use @option{-lgl_s} as an option,
+it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
+Naturally, this does not happen when you use GCC@.
+You must specify all three options explicitly.
+
+@item
+On a SPARC, GCC aligns all values of type @code{double} on an 8-byte
+boundary, and it expects every @code{double} to be so aligned.  The Sun
+compiler usually gives @code{double} values 8-byte alignment, with one
+exception: function arguments of type @code{double} may not be aligned.
+
+As a result, if a function compiled with Sun CC takes the address of an
+argument of type @code{double} and passes this pointer of type
+@code{double *} to a function compiled with GCC, dereferencing the
+pointer may cause a fatal signal.
+
+One way to solve this problem is to compile your entire program with GCC@.
+Another solution is to modify the function that is compiled with
+Sun CC to copy the argument into a local variable; local variables
+are always properly aligned.  A third solution is to modify the function
+that uses the pointer to dereference it via the following function
+@code{access_double} instead of directly with @samp{*}:
+
+@smallexample
+inline double
+access_double (double *unaligned_ptr)
+@{
+  union d2i @{ double d; int i[2]; @};
+
+  union d2i *p = (union d2i *) unaligned_ptr;
+  union d2i u;
+
+  u.i[0] = p->i[0];
+  u.i[1] = p->i[1];
+
+  return u.d;
+@}
+@end smallexample
+
+@noindent
+Storing into the pointer can be done likewise with the same union.
+
+@item
+On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
+may allocate memory that is only 4 byte aligned.  Since GCC on the
+SPARC assumes that doubles are 8 byte aligned, this may result in a
+fatal signal if doubles are stored in memory allocated by the
+@file{libmalloc.a} library.
+
+The solution is to not use the @file{libmalloc.a} library.  Use instead
+@code{malloc} and related functions from @file{libc.a}; they do not have
+this problem.
+
+@item
+On the HP PA machine, ADB sometimes fails to work on functions compiled
+with GCC@.  Specifically, it fails to work on functions that use
+@code{alloca} or variable-size arrays.  This is because GCC doesn't
+generate HP-UX unwind descriptors for such functions.  It may even be
+impossible to generate them.
+
+@item
+Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
+the preliminary GNU tools.
+
+@item
+Taking the address of a label may generate errors from the HP-UX
+PA assembler.  GAS for the PA does not have this problem.
+
+@item
+Using floating point parameters for indirect calls to static functions
+will not work when using the HP assembler.  There simply is no way for GCC
+to specify what registers hold arguments for static functions when using
+the HP assembler.  GAS for the PA does not have this problem.
+
+@item
+In extremely rare cases involving some very large functions you may
+receive errors from the HP linker complaining about an out of bounds
+unconditional branch offset.  This used to occur more often in previous
+versions of GCC, but is now exceptionally rare.  If you should run
+into it, you can work around by making your function smaller.
+
+@item
+GCC compiled code sometimes emits warnings from the HP-UX assembler of
+the form:
+
+@smallexample
+(warning) Use of GR3 when
+  frame >= 8192 may cause conflict.
+@end smallexample
+
+These warnings are harmless and can be safely ignored.
+
+@item
+In extremely rare cases involving some very large functions you may
+receive errors from the AIX Assembler complaining about a displacement
+that is too large.  If you should run into it, you can work around by
+making your function smaller.
+
+@item
+The @file{libstdc++.a} library in GCC relies on the SVR4 dynamic
+linker semantics which merges global symbols between libraries and
+applications, especially necessary for C++ streams functionality.
+This is not the default behavior of AIX shared libraries and dynamic
+linking.  @file{libstdc++.a} is built on AIX with ``runtime-linking''
+enabled so that symbol merging can occur.  To utilize this feature,
+the application linked with @file{libstdc++.a} must include the
+@option{-Wl,-brtl} flag on the link line.  G++ cannot impose this
+because this option may interfere with the semantics of the user
+program and users may not always use @samp{g++} to link his or her
+application.  Applications are not required to use the
+@option{-Wl,-brtl} flag on the link line---the rest of the
+@file{libstdc++.a} library which is not dependent on the symbol
+merging semantics will continue to function correctly.
+
+@item
+An application can interpose its own definition of functions for
+functions invoked by @file{libstdc++.a} with ``runtime-linking''
+enabled on AIX@.  To accomplish this the application must be linked
+with ``runtime-linking'' option and the functions explicitly must be
+exported by the application (@option{-Wl,-brtl,-bE:exportfile}).
+
+@item
+AIX on the RS/6000 provides support (NLS) for environments outside of
+the United States.  Compilers and assemblers use NLS to support
+locale-specific representations of various objects including
+floating-point numbers (@samp{.} vs @samp{,} for separating decimal
+fractions).  There have been problems reported where the library linked
+with GCC does not produce the same floating-point formats that the
+assembler accepts.  If you have this problem, set the @env{LANG}
+environment variable to @samp{C} or @samp{En_US}.
+
+@item
+@opindex fdollars-in-identifiers
+Even if you specify @option{-fdollars-in-identifiers},
+you cannot successfully use @samp{$} in identifiers on the RS/6000 due
+to a restriction in the IBM assembler.  GAS supports these
+identifiers.
+
+@end itemize
+
+@node Incompatibilities
+@section Incompatibilities of GCC
+@cindex incompatibilities of GCC
+@opindex traditional
+
+There are several noteworthy incompatibilities between GNU C and K&R
+(non-ISO) versions of C@.
+
+@itemize @bullet
+@cindex string constants
+@cindex read-only strings
+@cindex shared strings
+@item
+GCC normally makes string constants read-only.  If several
+identical-looking string constants are used, GCC stores only one
+copy of the string.
+
+@cindex @code{mktemp}, and constant strings
+One consequence is that you cannot call @code{mktemp} with a string
+constant argument.  The function @code{mktemp} always alters the
+string its argument points to.
+
+@cindex @code{sscanf}, and constant strings
+@cindex @code{fscanf}, and constant strings
+@cindex @code{scanf}, and constant strings
+Another consequence is that @code{sscanf} does not work on some very
+old systems when passed a string constant as its format control string
+or input.  This is because @code{sscanf} incorrectly tries to write
+into the string constant.  Likewise @code{fscanf} and @code{scanf}.
+
+The solution to these problems is to change the program to use
+@code{char}-array variables with initialization strings for these
+purposes instead of string constants.
+
+@item
+@code{-2147483648} is positive.
+
+This is because 2147483648 cannot fit in the type @code{int}, so
+(following the ISO C rules) its data type is @code{unsigned long int}.
+Negating this value yields 2147483648 again.
+
+@item
+GCC does not substitute macro arguments when they appear inside of
+string constants.  For example, the following macro in GCC
+
+@smallexample
+#define foo(a) "a"
+@end smallexample
+
+@noindent
+will produce output @code{"a"} regardless of what the argument @var{a} is.
+
+@cindex @code{setjmp} incompatibilities
+@cindex @code{longjmp} incompatibilities
+@item
+When you use @code{setjmp} and @code{longjmp}, the only automatic
+variables guaranteed to remain valid are those declared
+@code{volatile}.  This is a consequence of automatic register
+allocation.  Consider this function:
+
+@smallexample
+jmp_buf j;
+
+foo ()
+@{
+  int a, b;
+
+  a = fun1 ();
+  if (setjmp (j))
+    return a;
+
+  a = fun2 ();
+  /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
+  return a + fun3 ();
+@}
+@end smallexample
+
+Here @code{a} may or may not be restored to its first value when the
+@code{longjmp} occurs.  If @code{a} is allocated in a register, then
+its first value is restored; otherwise, it keeps the last value stored
+in it.
+
+@opindex W
+If you use the @option{-W} option with the @option{-O} option, you will
+get a warning when GCC thinks such a problem might be possible.
+
+@item
+Programs that use preprocessing directives in the middle of macro
+arguments do not work with GCC@.  For example, a program like this
+will not work:
+
+@smallexample
+@group
+foobar (
+#define luser
+        hack)
+@end group
+@end smallexample
+
+ISO C does not permit such a construct.
+
+@item
+K&R compilers allow comments to cross over an inclusion boundary
+(i.e.@: started in an include file and ended in the including file).
+
+@cindex external declaration scope
+@cindex scope of external declarations
+@cindex declaration scope
+@item
+Declarations of external variables and functions within a block apply
+only to the block containing the declaration.  In other words, they
+have the same scope as any other declaration in the same place.
+
+In some other C compilers, a @code{extern} declaration affects all the
+rest of the file even if it happens within a block.
+
+@item
+In traditional C, you can combine @code{long}, etc., with a typedef name,
+as shown here:
+
+@smallexample
+typedef int foo;
+typedef long foo bar;
+@end smallexample
+
+In ISO C, this is not allowed: @code{long} and other type modifiers
+require an explicit @code{int}.
+
+@cindex typedef names as function parameters
+@item
+PCC allows typedef names to be used as function parameters.
+
+@item
+Traditional C allows the following erroneous pair of declarations to
+appear together in a given scope:
+
+@smallexample
+typedef int foo;
+typedef foo foo;
+@end smallexample
+
+@item
+GCC treats all characters of identifiers as significant.  According to
+K&R-1 (2.2), ``No more than the first eight characters are significant,
+although more may be used.''.  Also according to K&R-1 (2.2), ``An
+identifier is a sequence of letters and digits; the first character must
+be a letter.  The underscore _ counts as a letter.'', but GCC also
+allows dollar signs in identifiers.
+
+@cindex whitespace
+@item
+PCC allows whitespace in the middle of compound assignment operators
+such as @samp{+=}.  GCC, following the ISO standard, does not
+allow this.
+
+@cindex apostrophes
+@cindex '
+@item
+GCC complains about unterminated character constants inside of
+preprocessing conditionals that fail.  Some programs have English
+comments enclosed in conditionals that are guaranteed to fail; if these
+comments contain apostrophes, GCC will probably report an error.  For
+example, this code would produce an error:
+
+@smallexample
+#if 0
+You can't expect this to work.
+#endif
+@end smallexample
+
+The best solution to such a problem is to put the text into an actual
+C comment delimited by @samp{/*@dots{}*/}.
+
+@item
+Many user programs contain the declaration @samp{long time ();}.  In the
+past, the system header files on many systems did not actually declare
+@code{time}, so it did not matter what type your program declared it to
+return.  But in systems with ISO C headers, @code{time} is declared to
+return @code{time_t}, and if that is not the same as @code{long}, then
+@samp{long time ();} is erroneous.
+
+The solution is to change your program to use appropriate system headers
+(@code{<time.h>} on systems with ISO C headers) and not to declare
+@code{time} if the system header files declare it, or failing that to
+use @code{time_t} as the return type of @code{time}.
+
+@cindex @code{float} as function value type
+@item
+When compiling functions that return @code{float}, PCC converts it to
+a double.  GCC actually returns a @code{float}.  If you are concerned
+with PCC compatibility, you should declare your functions to return
+@code{double}; you might as well say what you mean.
+
+@cindex structures
+@cindex unions
+@item
+When compiling functions that return structures or unions, GCC
+output code normally uses a method different from that used on most
+versions of Unix.  As a result, code compiled with GCC cannot call
+a structure-returning function compiled with PCC, and vice versa.
+
+The method used by GCC is as follows: a structure or union which is
+1, 2, 4 or 8 bytes long is returned like a scalar.  A structure or union
+with any other size is stored into an address supplied by the caller
+(usually in a special, fixed register, but on some machines it is passed
+on the stack).  The target hook @code{TARGET_STRUCT_VALUE_RTX}
+tells GCC where to pass this address.
+
+By contrast, PCC on most target machines returns structures and unions
+of any size by copying the data into an area of static storage, and then
+returning the address of that storage as if it were a pointer value.
+The caller must copy the data from that memory area to the place where
+the value is wanted.  GCC does not use this method because it is
+slower and nonreentrant.
+
+On some newer machines, PCC uses a reentrant convention for all
+structure and union returning.  GCC on most of these machines uses a
+compatible convention when returning structures and unions in memory,
+but still returns small structures and unions in registers.
+
+@opindex fpcc-struct-return
+You can tell GCC to use a compatible convention for all structure and
+union returning with the option @option{-fpcc-struct-return}.
+
+@cindex preprocessing tokens
+@cindex preprocessing numbers
+@item
+GCC complains about program fragments such as @samp{0x74ae-0x4000}
+which appear to be two hexadecimal constants separated by the minus
+operator.  Actually, this string is a single @dfn{preprocessing token}.
+Each such token must correspond to one token in C@.  Since this does not,
+GCC prints an error message.  Although it may appear obvious that what
+is meant is an operator and two values, the ISO C standard specifically
+requires that this be treated as erroneous.
+
+A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
+begins with a digit and is followed by letters, underscores, digits,
+periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
+@samp{p-}, @samp{P+}, or @samp{P-} character sequences.  (In strict C89
+mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
+appear in preprocessing numbers.)
+
+To make the above program fragment valid, place whitespace in front of
+the minus sign.  This whitespace will end the preprocessing number.
+@end itemize
+
+@node Fixed Headers
+@section Fixed Header Files
+
+GCC needs to install corrected versions of some system header files.
+This is because most target systems have some header files that won't
+work with GCC unless they are changed.  Some have bugs, some are
+incompatible with ISO C, and some depend on special features of other
+compilers.
+
+Installing GCC automatically creates and installs the fixed header
+files, by running a program called @code{fixincludes}.  Normally, you
+don't need to pay attention to this.  But there are cases where it
+doesn't do the right thing automatically.
+
+@itemize @bullet
+@item
+If you update the system's header files, such as by installing a new
+system version, the fixed header files of GCC are not automatically
+updated.  They can be updated using the @command{mkheaders} script
+installed in
+@file{@var{libexecdir}/gcc/@var{target}/@var{version}/install-tools/}.
+
+@item
+On some systems, header file directories contain
+machine-specific symbolic links in certain places.  This makes it
+possible to share most of the header files among hosts running the
+same version of the system on different machine models.
+
+The programs that fix the header files do not understand this special
+way of using symbolic links; therefore, the directory of fixed header
+files is good only for the machine model used to build it.
+
+It is possible to make separate sets of fixed header files for the
+different machine models, and arrange a structure of symbolic links so
+as to use the proper set, but you'll have to do this by hand.
+@end itemize
+
+@node Standard Libraries
+@section Standard Libraries
+
+@opindex Wall
+GCC by itself attempts to be a conforming freestanding implementation.
+@xref{Standards,,Language Standards Supported by GCC}, for details of
+what this means.  Beyond the library facilities required of such an
+implementation, the rest of the C library is supplied by the vendor of
+the operating system.  If that C library doesn't conform to the C
+standards, then your programs might get warnings (especially when using
+@option{-Wall}) that you don't expect.
+
+For example, the @code{sprintf} function on SunOS 4.1.3 returns
+@code{char *} while the C standard says that @code{sprintf} returns an
+@code{int}.  The @code{fixincludes} program could make the prototype for
+this function match the Standard, but that would be wrong, since the
+function will still return @code{char *}.
+
+If you need a Standard compliant library, then you need to find one, as
+GCC does not provide one.  The GNU C library (called @code{glibc})
+provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
+GNU/Linux and HURD-based GNU systems; no recent version of it supports
+other systems, though some very old versions did.  Version 2.2 of the
+GNU C library includes nearly complete C99 support.  You could also ask
+your operating system vendor if newer libraries are available.
+
+@node Disappointments
+@section Disappointments and Misunderstandings
+
+These problems are perhaps regrettable, but we don't know any practical
+way around them.
+
+@itemize @bullet
+@item
+Certain local variables aren't recognized by debuggers when you compile
+with optimization.
+
+This occurs because sometimes GCC optimizes the variable out of
+existence.  There is no way to tell the debugger how to compute the
+value such a variable ``would have had'', and it is not clear that would
+be desirable anyway.  So GCC simply does not mention the eliminated
+variable when it writes debugging information.
+
+You have to expect a certain amount of disagreement between the
+executable and your source code, when you use optimization.
+
+@cindex conflicting types
+@cindex scope of declaration
+@item
+Users often think it is a bug when GCC reports an error for code
+like this:
+
+@smallexample
+int foo (struct mumble *);
+
+struct mumble @{ @dots{} @};
+
+int foo (struct mumble *x)
+@{ @dots{} @}
+@end smallexample
+
+This code really is erroneous, because the scope of @code{struct
+mumble} in the prototype is limited to the argument list containing it.
+It does not refer to the @code{struct mumble} defined with file scope
+immediately below---they are two unrelated types with similar names in
+different scopes.
+
+But in the definition of @code{foo}, the file-scope type is used
+because that is available to be inherited.  Thus, the definition and
+the prototype do not match, and you get an error.
+
+This behavior may seem silly, but it's what the ISO standard specifies.
+It is easy enough for you to make your code work by moving the
+definition of @code{struct mumble} above the prototype.  It's not worth
+being incompatible with ISO C just to avoid an error for the example
+shown above.
+
+@item
+Accesses to bit-fields even in volatile objects works by accessing larger
+objects, such as a byte or a word.  You cannot rely on what size of
+object is accessed in order to read or write the bit-field; it may even
+vary for a given bit-field according to the precise usage.
+
+If you care about controlling the amount of memory that is accessed, use
+volatile but do not use bit-fields.
+
+@item
+GCC comes with shell scripts to fix certain known problems in system
+header files.  They install corrected copies of various header files in
+a special directory where only GCC will normally look for them.  The
+scripts adapt to various systems by searching all the system header
+files for the problem cases that we know about.
+
+If new system header files are installed, nothing automatically arranges
+to update the corrected header files.  They can be updated using the
+@command{mkheaders} script installed in
+@file{@var{libexecdir}/gcc/@var{target}/@var{version}/install-tools/}.
+
+@item
+@cindex floating point precision
+On 68000 and x86 systems, for instance, you can get paradoxical results
+if you test the precise values of floating point numbers.  For example,
+you can find that a floating point value which is not a NaN is not equal
+to itself.  This results from the fact that the floating point registers
+hold a few more bits of precision than fit in a @code{double} in memory.
+Compiled code moves values between memory and floating point registers
+at its convenience, and moving them into memory truncates them.
+
+@opindex ffloat-store
+You can partially avoid this problem by using the @option{-ffloat-store}
+option (@pxref{Optimize Options}).
+
+@item
+On AIX and other platforms without weak symbol support, templates
+need to be instantiated explicitly and symbols for static members
+of templates will not be generated.
+
+@item
+On AIX, GCC scans object files and library archives for static
+constructors and destructors when linking an application before the
+linker prunes unreferenced symbols.  This is necessary to prevent the
+AIX linker from mistakenly assuming that static constructor or
+destructor are unused and removing them before the scanning can occur.
+All static constructors and destructors found will be referenced even
+though the modules in which they occur may not be used by the program.
+This may lead to both increased executable size and unexpected symbol
+references.
+@end itemize
+
+@node C++ Misunderstandings
+@section Common Misunderstandings with GNU C++
+
+@cindex misunderstandings in C++
+@cindex surprises in C++
+@cindex C++ misunderstandings
+C++ is a complex language and an evolving one, and its standard
+definition (the ISO C++ standard) was only recently completed.  As a
+result, your C++ compiler may occasionally surprise you, even when its
+behavior is correct.  This section discusses some areas that frequently
+give rise to questions of this sort.
+
+@menu
+* Static Definitions::  Static member declarations are not definitions
+* Name lookup::         Name lookup, templates, and accessing members of base classes
+* Temporaries::         Temporaries may vanish before you expect
+* Copy Assignment::     Copy Assignment operators copy virtual bases twice
+@end menu
+
+@node Static Definitions
+@subsection Declare @emph{and} Define Static Members
+
+@cindex C++ static data, declaring and defining
+@cindex static data in C++, declaring and defining
+@cindex declaring static data in C++
+@cindex defining static data in C++
+When a class has static data members, it is not enough to @emph{declare}
+the static member; you must also @emph{define} it.  For example:
+
+@smallexample
+class Foo
+@{
+  @dots{}
+  void method();
+  static int bar;
+@};
+@end smallexample
+
+This declaration only establishes that the class @code{Foo} has an
+@code{int} named @code{Foo::bar}, and a member function named
+@code{Foo::method}.  But you still need to define @emph{both}
+@code{method} and @code{bar} elsewhere.  According to the ISO
+standard, you must supply an initializer in one (and only one) source
+file, such as:
+
+@smallexample
+int Foo::bar = 0;
+@end smallexample
+
+Other C++ compilers may not correctly implement the standard behavior.
+As a result, when you switch to @command{g++} from one of these compilers,
+you may discover that a program that appeared to work correctly in fact
+does not conform to the standard: @command{g++} reports as undefined
+symbols any static data members that lack definitions.
+
+
+@node Name lookup
+@subsection Name lookup, templates, and accessing members of base classes
+
+@cindex base class members
+@cindex two-stage name lookup
+@cindex dependent name lookup
+
+The C++ standard prescribes that all names that are not dependent on
+template parameters are bound to their present definitions when parsing
+a template function or class.@footnote{The C++ standard just uses the
+term ``dependent'' for names that depend on the type or value of
+template parameters.  This shorter term will also be used in the rest of
+this section.}  Only names that are dependent are looked up at the point
+of instantiation.  For example, consider
+
+@smallexample
+  void foo(double);
+
+  struct A @{
+    template <typename T>
+    void f () @{
+      foo (1);        // @r{1}
+      int i = N;      // @r{2}
+      T t;
+      t.bar();        // @r{3}
+      foo (t);        // @r{4}
+    @}
+
+    static const int N;
+  @};
+@end smallexample
+
+Here, the names @code{foo} and @code{N} appear in a context that does
+not depend on the type of @code{T}.  The compiler will thus require that
+they are defined in the context of use in the template, not only before
+the point of instantiation, and will here use @code{::foo(double)} and
+@code{A::N}, respectively.  In particular, it will convert the integer
+value to a @code{double} when passing it to @code{::foo(double)}.
+
+Conversely, @code{bar} and the call to @code{foo} in the fourth marked
+line are used in contexts that do depend on the type of @code{T}, so
+they are only looked up at the point of instantiation, and you can
+provide declarations for them after declaring the template, but before
+instantiating it.  In particular, if you instantiate @code{A::f<int>},
+the last line will call an overloaded @code{::foo(int)} if one was
+provided, even if after the declaration of @code{struct A}.
+
+This distinction between lookup of dependent and non-dependent names is
+called two-stage (or dependent) name lookup.  G++ implements it
+since version 3.4.
+
+Two-stage name lookup sometimes leads to situations with behavior
+different from non-template codes.  The most common is probably this:
+
+@smallexample
+  template <typename T> struct Base @{
+    int i;
+  @};
+
+  template <typename T> struct Derived : public Base<T> @{
+    int get_i() @{ return i; @}
+  @};
+@end smallexample
+
+In @code{get_i()}, @code{i} is not used in a dependent context, so the
+compiler will look for a name declared at the enclosing namespace scope
+(which is the global scope here).  It will not look into the base class,
+since that is dependent and you may declare specializations of
+@code{Base} even after declaring @code{Derived}, so the compiler can't
+really know what @code{i} would refer to.  If there is no global
+variable @code{i}, then you will get an error message.
+
+In order to make it clear that you want the member of the base class,
+you need to defer lookup until instantiation time, at which the base
+class is known.  For this, you need to access @code{i} in a dependent
+context, by either using @code{this->i} (remember that @code{this} is of
+type @code{Derived<T>*}, so is obviously dependent), or using
+@code{Base<T>::i}.  Alternatively, @code{Base<T>::i} might be brought
+into scope by a @code{using}-declaration.
+
+Another, similar example involves calling member functions of a base
+class:
+
+@smallexample
+  template <typename T> struct Base @{
+      int f();
+  @};
+
+  template <typename T> struct Derived : Base<T> @{
+      int g() @{ return f(); @};
+  @};
+@end smallexample
+
+Again, the call to @code{f()} is not dependent on template arguments
+(there are no arguments that depend on the type @code{T}, and it is also
+not otherwise specified that the call should be in a dependent context).
+Thus a global declaration of such a function must be available, since
+the one in the base class is not visible until instantiation time.  The
+compiler will consequently produce the following error message:
+
+@smallexample
+  x.cc: In member function `int Derived<T>::g()':
+  x.cc:6: error: there are no arguments to `f' that depend on a template
+     parameter, so a declaration of `f' must be available
+  x.cc:6: error: (if you use `-fpermissive', G++ will accept your code, but
+     allowing the use of an undeclared name is deprecated)
+@end smallexample
+
+To make the code valid either use @code{this->f()}, or
+@code{Base<T>::f()}.  Using the @option{-fpermissive} flag will also let
+the compiler accept the code, by marking all function calls for which no
+declaration is visible at the time of definition of the template for
+later lookup at instantiation time, as if it were a dependent call.
+We do not recommend using @option{-fpermissive} to work around invalid
+code, and it will also only catch cases where functions in base classes
+are called, not where variables in base classes are used (as in the
+example above).
+
+Note that some compilers (including G++ versions prior to 3.4) get these
+examples wrong and accept above code without an error.  Those compilers
+do not implement two-stage name lookup correctly.
+
+
+@node Temporaries
+@subsection Temporaries May Vanish Before You Expect
+
+@cindex temporaries, lifetime of
+@cindex portions of temporary objects, pointers to
+It is dangerous to use pointers or references to @emph{portions} of a
+temporary object.  The compiler may very well delete the object before
+you expect it to, leaving a pointer to garbage.  The most common place
+where this problem crops up is in classes like string classes,
+especially ones that define a conversion function to type @code{char *}
+or @code{const char *}---which is one reason why the standard
+@code{string} class requires you to call the @code{c_str} member
+function.  However, any class that returns a pointer to some internal
+structure is potentially subject to this problem.
+
+For example, a program may use a function @code{strfunc} that returns
+@code{string} objects, and another function @code{charfunc} that
+operates on pointers to @code{char}:
+
+@smallexample
+string strfunc ();
+void charfunc (const char *);
+
+void
+f ()
+@{
+  const char *p = strfunc().c_str();
+  @dots{}
+  charfunc (p);
+  @dots{}
+  charfunc (p);
+@}
+@end smallexample
+
+@noindent
+In this situation, it may seem reasonable to save a pointer to the C
+string returned by the @code{c_str} member function and use that rather
+than call @code{c_str} repeatedly.  However, the temporary string
+created by the call to @code{strfunc} is destroyed after @code{p} is
+initialized, at which point @code{p} is left pointing to freed memory.
+
+Code like this may run successfully under some other compilers,
+particularly obsolete cfront-based compilers that delete temporaries
+along with normal local variables.  However, the GNU C++ behavior is
+standard-conforming, so if your program depends on late destruction of
+temporaries it is not portable.
+
+The safe way to write such code is to give the temporary a name, which
+forces it to remain until the end of the scope of the name.  For
+example:
+
+@smallexample
+const string& tmp = strfunc ();
+charfunc (tmp.c_str ());
+@end smallexample
+
+@node Copy Assignment
+@subsection Implicit Copy-Assignment for Virtual Bases
+
+When a base class is virtual, only one subobject of the base class
+belongs to each full object.  Also, the constructors and destructors are
+invoked only once, and called from the most-derived class.  However, such
+objects behave unspecified when being assigned.  For example:
+
+@smallexample
+struct Base@{
+  char *name;
+  Base(char *n) : name(strdup(n))@{@}
+  Base& operator= (const Base& other)@{
+   free (name);
+   name = strdup (other.name);
+  @}
+@};
+
+struct A:virtual Base@{
+  int val;
+  A():Base("A")@{@}
+@};
+
+struct B:virtual Base@{
+  int bval;
+  B():Base("B")@{@}
+@};
+
+struct Derived:public A, public B@{
+  Derived():Base("Derived")@{@}
+@};
+
+void func(Derived &d1, Derived &d2)
+@{
+  d1 = d2;
+@}
+@end smallexample
+
+The C++ standard specifies that @samp{Base::Base} is only called once
+when constructing or copy-constructing a Derived object.  It is
+unspecified whether @samp{Base::operator=} is called more than once when
+the implicit copy-assignment for Derived objects is invoked (as it is
+inside @samp{func} in the example).
+
+G++ implements the ``intuitive'' algorithm for copy-assignment: assign all
+direct bases, then assign all members.  In that algorithm, the virtual
+base subobject can be encountered more than once.  In the example, copying
+proceeds in the following order: @samp{val}, @samp{name} (via
+@code{strdup}), @samp{bval}, and @samp{name} again.
+
+If application code relies on copy-assignment, a user-defined
+copy-assignment operator removes any uncertainties.  With such an
+operator, the application can define whether and how the virtual base
+subobject is assigned.
+
+@node Protoize Caveats
+@section Caveats of using @command{protoize}
+
+The conversion programs @command{protoize} and @command{unprotoize} can
+sometimes change a source file in a way that won't work unless you
+rearrange it.
+
+@itemize @bullet
+@item
+@command{protoize} can insert references to a type name or type tag before
+the definition, or in a file where they are not defined.
+
+If this happens, compiler error messages should show you where the new
+references are, so fixing the file by hand is straightforward.
+
+@item
+There are some C constructs which @command{protoize} cannot figure out.
+For example, it can't determine argument types for declaring a
+pointer-to-function variable; this you must do by hand.  @command{protoize}
+inserts a comment containing @samp{???} each time it finds such a
+variable; so you can find all such variables by searching for this
+string.  ISO C does not require declaring the argument types of
+pointer-to-function types.
+
+@item
+Using @command{unprotoize} can easily introduce bugs.  If the program
+relied on prototypes to bring about conversion of arguments, these
+conversions will not take place in the program without prototypes.
+One case in which you can be sure @command{unprotoize} is safe is when
+you are removing prototypes that were made with @command{protoize}; if
+the program worked before without any prototypes, it will work again
+without them.
+
+@opindex Wtraditional-conversion
+You can find all the places where this problem might occur by compiling
+the program with the @option{-Wtraditional-conversion} option.  It
+prints a warning whenever an argument is converted.
+
+@item
+Both conversion programs can be confused if there are macro calls in and
+around the text to be converted.  In other words, the standard syntax
+for a declaration or definition must not result from expanding a macro.
+This problem is inherent in the design of C and cannot be fixed.  If
+only a few functions have confusing macro calls, you can easily convert
+them manually.
+
+@item
+@command{protoize} cannot get the argument types for a function whose
+definition was not actually compiled due to preprocessing conditionals.
+When this happens, @command{protoize} changes nothing in regard to such
+a function.  @command{protoize} tries to detect such instances and warn
+about them.
+
+You can generally work around this problem by using @command{protoize} step
+by step, each time specifying a different set of @option{-D} options for
+compilation, until all of the functions have been converted.  There is
+no automatic way to verify that you have got them all, however.
+
+@item
+Confusion may result if there is an occasion to convert a function
+declaration or definition in a region of source code where there is more
+than one formal parameter list present.  Thus, attempts to convert code
+containing multiple (conditionally compiled) versions of a single
+function header (in the same vicinity) may not produce the desired (or
+expected) results.
+
+If you plan on converting source files which contain such code, it is
+recommended that you first make sure that each conditionally compiled
+region of source code which contains an alternative function header also
+contains at least one additional follower token (past the final right
+parenthesis of the function header).  This should circumvent the
+problem.
+
+@item
+@command{unprotoize} can become confused when trying to convert a function
+definition or declaration which contains a declaration for a
+pointer-to-function formal argument which has the same name as the
+function being defined or declared.  We recommend you avoid such choices
+of formal parameter names.
+
+@item
+You might also want to correct some of the indentation by hand and break
+long lines.  (The conversion programs don't write lines longer than
+eighty characters in any case.)
+@end itemize
+
+@node Non-bugs
+@section Certain Changes We Don't Want to Make
+
+This section lists changes that people frequently request, but which
+we do not make because we think GCC is better without them.
+
+@itemize @bullet
+@item
+Checking the number and type of arguments to a function which has an
+old-fashioned definition and no prototype.
+
+Such a feature would work only occasionally---only for calls that appear
+in the same file as the called function, following the definition.  The
+only way to check all calls reliably is to add a prototype for the
+function.  But adding a prototype eliminates the motivation for this
+feature.  So the feature is not worthwhile.
+
+@item
+Warning about using an expression whose type is signed as a shift count.
+
+Shift count operands are probably signed more often than unsigned.
+Warning about this would cause far more annoyance than good.
+
+@item
+Warning about assigning a signed value to an unsigned variable.
+
+Such assignments must be very common; warning about them would cause
+more annoyance than good.
+
+@item
+Warning when a non-void function value is ignored.
+
+C contains many standard functions that return a value that most
+programs choose to ignore.  One obvious example is @code{printf}.
+Warning about this practice only leads the defensive programmer to
+clutter programs with dozens of casts to @code{void}.  Such casts are
+required so frequently that they become visual noise.  Writing those
+casts becomes so automatic that they no longer convey useful
+information about the intentions of the programmer.  For functions
+where the return value should never be ignored, use the
+@code{warn_unused_result} function attribute (@pxref{Function
+Attributes}).
+
+@item
+@opindex fshort-enums
+Making @option{-fshort-enums} the default.
+
+This would cause storage layout to be incompatible with most other C
+compilers.  And it doesn't seem very important, given that you can get
+the same result in other ways.  The case where it matters most is when
+the enumeration-valued object is inside a structure, and in that case
+you can specify a field width explicitly.
+
+@item
+Making bit-fields unsigned by default on particular machines where ``the
+ABI standard'' says to do so.
+
+The ISO C standard leaves it up to the implementation whether a bit-field
+declared plain @code{int} is signed or not.  This in effect creates two
+alternative dialects of C@.
+
+@opindex fsigned-bitfields
+@opindex funsigned-bitfields
+The GNU C compiler supports both dialects; you can specify the signed
+dialect with @option{-fsigned-bitfields} and the unsigned dialect with
+@option{-funsigned-bitfields}.  However, this leaves open the question of
+which dialect to use by default.
+
+Currently, the preferred dialect makes plain bit-fields signed, because
+this is simplest.  Since @code{int} is the same as @code{signed int} in
+every other context, it is cleanest for them to be the same in bit-fields
+as well.
+
+Some computer manufacturers have published Application Binary Interface
+standards which specify that plain bit-fields should be unsigned.  It is
+a mistake, however, to say anything about this issue in an ABI@.  This is
+because the handling of plain bit-fields distinguishes two dialects of C@.
+Both dialects are meaningful on every type of machine.  Whether a
+particular object file was compiled using signed bit-fields or unsigned
+is of no concern to other object files, even if they access the same
+bit-fields in the same data structures.
+
+A given program is written in one or the other of these two dialects.
+The program stands a chance to work on most any machine if it is
+compiled with the proper dialect.  It is unlikely to work at all if
+compiled with the wrong dialect.
+
+Many users appreciate the GNU C compiler because it provides an
+environment that is uniform across machines.  These users would be
+inconvenienced if the compiler treated plain bit-fields differently on
+certain machines.
+
+Occasionally users write programs intended only for a particular machine
+type.  On these occasions, the users would benefit if the GNU C compiler
+were to support by default the same dialect as the other compilers on
+that machine.  But such applications are rare.  And users writing a
+program to run on more than one type of machine cannot possibly benefit
+from this kind of compatibility.
+
+This is why GCC does and will treat plain bit-fields in the same
+fashion on all types of machines (by default).
+
+There are some arguments for making bit-fields unsigned by default on all
+machines.  If, for example, this becomes a universal de facto standard,
+it would make sense for GCC to go along with it.  This is something
+to be considered in the future.
+
+(Of course, users strongly concerned about portability should indicate
+explicitly in each bit-field whether it is signed or not.  In this way,
+they write programs which have the same meaning in both C dialects.)
+
+@item
+@opindex ansi
+@opindex std
+Undefining @code{__STDC__} when @option{-ansi} is not used.
+
+Currently, GCC defines @code{__STDC__} unconditionally.  This provides
+good results in practice.
+
+Programmers normally use conditionals on @code{__STDC__} to ask whether
+it is safe to use certain features of ISO C, such as function
+prototypes or ISO token concatenation.  Since plain @command{gcc} supports
+all the features of ISO C, the correct answer to these questions is
+``yes''.
+
+Some users try to use @code{__STDC__} to check for the availability of
+certain library facilities.  This is actually incorrect usage in an ISO
+C program, because the ISO C standard says that a conforming
+freestanding implementation should define @code{__STDC__} even though it
+does not have the library facilities.  @samp{gcc -ansi -pedantic} is a
+conforming freestanding implementation, and it is therefore required to
+define @code{__STDC__}, even though it does not come with an ISO C
+library.
+
+Sometimes people say that defining @code{__STDC__} in a compiler that
+does not completely conform to the ISO C standard somehow violates the
+standard.  This is illogical.  The standard is a standard for compilers
+that claim to support ISO C, such as @samp{gcc -ansi}---not for other
+compilers such as plain @command{gcc}.  Whatever the ISO C standard says
+is relevant to the design of plain @command{gcc} without @option{-ansi} only
+for pragmatic reasons, not as a requirement.
+
+GCC normally defines @code{__STDC__} to be 1, and in addition
+defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
+or a @option{-std} option for strict conformance to some version of ISO C@.
+On some hosts, system include files use a different convention, where
+@code{__STDC__} is normally 0, but is 1 if the user specifies strict
+conformance to the C Standard.  GCC follows the host convention when
+processing system include files, but when processing user files it follows
+the usual GNU C convention.
+
+@item
+Undefining @code{__STDC__} in C++.
+
+Programs written to compile with C++-to-C translators get the
+value of @code{__STDC__} that goes with the C compiler that is
+subsequently used.  These programs must test @code{__STDC__}
+to determine what kind of C preprocessor that compiler uses:
+whether they should concatenate tokens in the ISO C fashion
+or in the traditional fashion.
+
+These programs work properly with GNU C++ if @code{__STDC__} is defined.
+They would not work otherwise.
+
+In addition, many header files are written to provide prototypes in ISO
+C but not in traditional C@.  Many of these header files can work without
+change in C++ provided @code{__STDC__} is defined.  If @code{__STDC__}
+is not defined, they will all fail, and will all need to be changed to
+test explicitly for C++ as well.
+
+@item
+Deleting ``empty'' loops.
+
+Historically, GCC has not deleted ``empty'' loops under the
+assumption that the most likely reason you would put one in a program is
+to have a delay, so deleting them will not make real programs run any
+faster.
+
+However, the rationale here is that optimization of a nonempty loop
+cannot produce an empty one. This held for carefully written C compiled
+with less powerful optimizers but is not always the case for carefully
+written C++ or with more powerful optimizers.
+Thus GCC will remove operations from loops whenever it can determine
+those operations are not externally visible (apart from the time taken
+to execute them, of course).  In case the loop can be proved to be finite,
+GCC will also remove the loop itself.
+
+Be aware of this when performing timing tests, for instance the
+following loop can be completely removed, provided
+@code{some_expression} can provably not change any global state.
+
+@smallexample
+@{
+   int sum = 0;
+   int ix;
+
+   for (ix = 0; ix != 10000; ix++)
+      sum += some_expression;
+@}
+@end smallexample
+
+Even though @code{sum} is accumulated in the loop, no use is made of
+that summation, so the accumulation can be removed.
+
+@item
+Making side effects happen in the same order as in some other compiler.
+
+@cindex side effects, order of evaluation
+@cindex order of evaluation, side effects
+It is never safe to depend on the order of evaluation of side effects.
+For example, a function call like this may very well behave differently
+from one compiler to another:
+
+@smallexample
+void func (int, int);
+
+int i = 2;
+func (i++, i++);
+@end smallexample
+
+There is no guarantee (in either the C or the C++ standard language
+definitions) that the increments will be evaluated in any particular
+order.  Either increment might happen first.  @code{func} might get the
+arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
+
+@item
+Making certain warnings into errors by default.
+
+Some ISO C testsuites report failure when the compiler does not produce
+an error message for a certain program.
+
+@opindex pedantic-errors
+ISO C requires a ``diagnostic'' message for certain kinds of invalid
+programs, but a warning is defined by GCC to count as a diagnostic.  If
+GCC produces a warning but not an error, that is correct ISO C support.
+If testsuites call this ``failure'', they should be run with the GCC
+option @option{-pedantic-errors}, which will turn these warnings into
+errors.
+
+@end itemize
+
+@node Warnings and Errors
+@section Warning Messages and Error Messages
+
+@cindex error messages
+@cindex warnings vs errors
+@cindex messages, warning and error
+The GNU compiler can produce two kinds of diagnostics: errors and
+warnings.  Each kind has a different purpose:
+
+@itemize @w{}
+@item
+@dfn{Errors} report problems that make it impossible to compile your
+program.  GCC reports errors with the source file name and line
+number where the problem is apparent.
+
+@item
+@dfn{Warnings} report other unusual conditions in your code that
+@emph{may} indicate a problem, although compilation can (and does)
+proceed.  Warning messages also report the source file name and line
+number, but include the text @samp{warning:} to distinguish them
+from error messages.
+@end itemize
+
+Warnings may indicate danger points where you should check to make sure
+that your program really does what you intend; or the use of obsolete
+features; or the use of nonstandard features of GNU C or C++.  Many
+warnings are issued only if you ask for them, with one of the @option{-W}
+options (for instance, @option{-Wall} requests a variety of useful
+warnings).
+
+@opindex pedantic
+@opindex pedantic-errors
+GCC always tries to compile your program if possible; it never
+gratuitously rejects a program whose meaning is clear merely because
+(for instance) it fails to conform to a standard.  In some cases,
+however, the C and C++ standards specify that certain extensions are
+forbidden, and a diagnostic @emph{must} be issued by a conforming
+compiler.  The @option{-pedantic} option tells GCC to issue warnings in
+such cases; @option{-pedantic-errors} says to make them errors instead.
+This does not mean that @emph{all} non-ISO constructs get warnings
+or errors.
+
+@xref{Warning Options,,Options to Request or Suppress Warnings}, for
+more detail on these and related command-line options.