* doc/gcc.texi: Move several chapters out to ...

	* doc/bugreport.texi, doc/contribute.texi, doc/frontends.texi,
	doc/service.texi, doc/standards.texi, doc/trouble.texi,
	doc/vms.texi: ... here.  New files.
	* Makefile.in ($(docdir)/gcc.info, gcc.dvi): Update dependencies.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@46929 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 1465 insertions, 0 deletions

diff --git a/gcc/doc/trouble.texi b/gcc/doc/trouble.texi
new file mode 100644
index 00000000000..ff67f8f19fa
--- /dev/null
+++ b/gcc/doc/trouble.texi
@@ -0,0 +1,1465 @@
+@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
+@c 1999, 2000, 2001 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.
+* External Bugs::	Problems compiling certain programs.
+* 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.
+
+@item
+@opindex pedantic-errors
+When @option{-pedantic-errors} is specified, GCC will incorrectly give
+an error message when a function name is specified in an expression
+involving the comma operator.
+@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
+Cross compilation can run into trouble for certain machines because
+some target machines' assemblers require floating point numbers to be
+written as @emph{integer} constants in certain contexts.
+
+The compiler writes these integer constants by examining the floating
+point value as an integer and printing that integer, because this is
+simple to write and independent of the details of the floating point
+representation.  But this does not work if the compiler is running on
+a different machine with an incompatible floating point format, or
+even a different byte-ordering.
+
+In addition, correct constant folding of floating point values
+requires representing them in the target machine's format.
+(The C standard does not quite require this, but in practice
+it is the only way to win.)
+
+It is now possible to overcome these problems by defining macros such
+as @code{REAL_VALUE_TYPE}.  But doing so is a substantial amount of
+work for each target machine.
+@ifset INTERNALS
+@xref{Cross-compilation}.
+@end ifset
+@ifclear INTERNALS
+@xref{Cross-compilation,,Cross Compilation and Floating Point Format,
+gcc.info, Using and Porting GCC}.
+@end ifclear
+
+@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
+Objective-C does not work on the RS/6000.
+
+@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.
+
+This effect 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
+Older GDB versions sometimes fail to read the output of GCC version
+2.  If you have trouble, get GDB version 4.4 or later.
+
+@item
+@cindex DBX
+DBX rejects some files produced by GCC, though it accepts similar
+constructs in output from PCC@.  Until someone can supply a coherent
+description of what is valid DBX input and what is not, there is
+nothing I can do about these problems.  You are on your own.
+
+@item
+The GNU assembler (GAS) does not support PIC@.  To generate PIC code, you
+must use some other assembler, such as @file{/bin/as}.
+
+@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.
+
+@ignore
+@cindex @code{vfork}, for the Sun-4
+@item
+There is a bug in @code{vfork} on the Sun-4 which causes the registers
+of the child process to clobber those of the parent.  Because of this,
+programs that call @code{vfork} are likely to lose when compiled
+optimized with GCC when the child code alters registers which contain
+C variables in the parent.  This affects variables which are live in the
+parent across the call to @code{vfork}.
+
+If you encounter this, you can work around the problem by declaring
+variables @code{volatile} in the function that calls @code{vfork}, until
+the problem goes away, or by not declaring them @code{register} and not
+using @option{-O} for those source files.
+@end ignore
+
+@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
+Sun forgot to include a static version of @file{libdl.a} with some
+versions of SunOS (mainly 4.1).  This results in undefined symbols when
+linking static binaries (that is, if you use @option{-static}).  If you
+see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
+when linking, compile and link against the file
+@file{mit/util/misc/dlsym.c} from the MIT version of X windows.
+
+@item
+The 128-bit long double format that the Sparc port supports currently
+works by using the architecturally defined quad-word floating point
+instructions.  Since there is no hardware that supports these
+instructions they must be emulated by the operating system.  Long
+doubles do not work in Sun OS versions 4.0.3 and earlier, because the
+kernel emulator uses an obsolete and incompatible format.  Long doubles
+do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
+Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
+does not enable them by default.  Long doubles appear to work in Sun OS
+5.x (Solaris 2.x).
+
+@item
+On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
+compile GCC correctly.  We do not yet know why.  However, GCC
+compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
+compile itself properly on 9.01.
+
+@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 (@pxref{Installation}).
+
+@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
+The current version of the assembler (@file{/bin/as}) for the RS/6000
+has certain problems that prevent the @option{-g} option in GCC from
+working.  Note that @file{Makefile.in} uses @option{-g} by default when
+compiling @file{libgcc2.c}.
+
+IBM has produced a fixed version of the assembler.  The upgraded
+assembler unfortunately was not included in any of the AIX 3.2 update
+PTF releases (3.2.2, 3.2.3, or 3.2.3e).  Users of AIX 3.1 should request
+PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
+See the file @file{README.RS6000} for more details on these updates.
+
+You can test for the presence of a fixed assembler by using the
+command
+
+@smallexample
+as -u < /dev/null
+@end smallexample
+
+@noindent
+If the command exits normally, the assembler fix already is installed.
+If the assembler complains that @option{-u} is an unknown flag, you need to
+order the fix.
+
+@item
+On the IBM RS/6000, compiling code of the form
+
+@smallexample
+extern int foo;
+
+@dots{} foo @dots{}
+
+static int foo;
+@end smallexample
+
+@noindent
+will cause the linker to report an undefined symbol @code{foo}.
+Although this behavior differs from most other systems, it is not a
+bug because redefining an @code{extern} variable as @code{static}
+is undefined in ISO C@.
+
+@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.
+
+@item
+On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}.  XLC
+version 1.3.0.1 or later fixes this problem.  You can obtain XLC-1.3.0.2
+by requesting PTF 421749 from IBM@.
+
+@item
+@opindex mno-serialize-volatile
+There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
+occurs when the @samp{fldcr} instruction is used.  GCC uses
+@samp{fldcr} on the 88100 to serialize volatile memory references.  Use
+the option @option{-mno-serialize-volatile} if your version of the
+assembler has this bug.
+
+@item
+On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
+messages from the linker.  These warning messages complain of mismatched
+psect attributes.  You can ignore them.  @xref{VMS Install}.
+
+@item
+On NewsOS version 3, if you include both of the files @file{stddef.h}
+and @file{sys/types.h}, you get an error because there are two typedefs
+of @code{size_t}.  You should change @file{sys/types.h} by adding these
+lines around the definition of @code{size_t}:
+
+@smallexample
+#ifndef _SIZE_T
+#define _SIZE_T
+@var{actual-typedef-here}
+#endif
+@end smallexample
+
+@cindex Alliant
+@item
+On the Alliant, the system's own convention for returning structures
+and unions is unusual, and is not compatible with GCC no matter
+what options are used.
+
+@cindex RT PC
+@cindex IBM RT PC
+@item
+@opindex mhc-struct-return
+On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
+convention for structure and union returning.  Use the option
+@option{-mhc-struct-return} to tell GCC to use a convention compatible
+with it.
+
+@cindex VAX calling convention
+@cindex Ultrix calling convention
+@item
+@opindex fcall-saved
+On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
+by function calls.  However, the C compiler uses conventions compatible
+with BSD Unix: registers 2 through 5 may be clobbered by function calls.
+
+GCC uses the same convention as the Ultrix C compiler.  You can use
+these options to produce code compatible with the Fortran compiler:
+
+@smallexample
+-fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
+@end smallexample
+
+@item
+On the WE32k, you may find that programs compiled with GCC do not
+work with the standard shared C library.  You may need to link with
+the ordinary C compiler.  If you do so, you must specify the following
+options:
+
+@smallexample
+-L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
+@end smallexample
+
+The first specifies where to find the library @file{libgcc.a}
+specified with the @option{-lgcc} option.
+
+GCC does linking by invoking @command{ld}, just as @command{cc} does, and
+there is no reason why it @emph{should} matter which compilation program
+you use to invoke @command{ld}.  If someone tracks this problem down,
+it can probably be fixed easily.
+
+@item
+On the Alpha, you may get assembler errors about invalid syntax as a
+result of floating point constants.  This is due to a bug in the C
+library functions @code{ecvt}, @code{fcvt} and @code{gcvt}.  Given valid
+floating point numbers, they sometimes print @samp{NaN}.
+
+@item
+On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
+sometimes reorders instructions incorrectly when optimization is turned
+on.  If you think this may be happening to you, try using the GNU
+assembler; GAS version 2.1 supports ECOFF on Irix.
+
+@opindex noasmopt
+Or use the @option{-noasmopt} option when you compile GCC with itself,
+and then again when you compile your program.  (This is a temporary
+kludge to turn off assembler optimization on Irix.)  If this proves to
+be what you need, edit the assembler spec in the file @file{specs} so
+that it unconditionally passes @option{-O0} to the assembler, and never
+passes @option{-O2} or @option{-O3}.
+@end itemize
+
+@node External Bugs
+@section Problems Compiling Certain Programs
+
+@c prevent bad page break with this line
+Certain programs have problems compiling.
+
+@itemize @bullet
+@item
+Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
+because of problems in DEC's versions of the X11 header files
+@file{X11/Xlib.h} and @file{X11/Xutil.h}.  People recommend adding
+@option{-I/usr/include/mit} to use the MIT versions of the header files,
+using the @option{-traditional} switch to turn off ISO C, or fixing the
+header files by adding this:
+
+@example
+#ifdef __STDC__
+#define NeedFunctionPrototypes 0
+#endif
+@end example
+
+@item
+On various 386 Unix systems derived from System V, including SCO, ISC,
+and ESIX, you may get error messages about running out of virtual memory
+while compiling certain programs.
+
+You can prevent this problem by linking GCC with the GNU malloc
+(which thus replaces the malloc that comes with the system).  GNU malloc
+is available as a separate package, and also in the file
+@file{src/gmalloc.c} in the GNU Emacs 19 distribution.
+
+If you have installed GNU malloc as a separate library package, use this
+option when you relink GCC:
+
+@example
+MALLOC=/usr/local/lib/libgmalloc.a
+@end example
+
+Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
+the object file to @file{gmalloc.o} and use this option when you relink
+GCC:
+
+@example
+MALLOC=gmalloc.o
+@end example
+@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@.  The @option{-traditional} option
+eliminates many of these incompatibilities, @emph{but not all}, by
+telling GCC to behave like a K&R C compiler.
+
+@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 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}.
+
+@opindex fwritable-strings
+The best 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.  But if this is not possible,
+you can use the @option{-fwritable-strings} flag, which directs GCC
+to handle string constants the same way most C compilers do.
+@option{-traditional} also has this effect, among others.
+
+@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
+
+@example
+#define foo(a) "a"
+@end example
+
+@noindent
+will produce output @code{"a"} regardless of what the argument @var{a} is.
+
+The @option{-traditional} option directs GCC to handle such cases
+(among others) in the old-fashioned (non-ISO) fashion.
+
+@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:
+
+@example
+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 example
+
+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.
+
+The @option{-traditional} option directs GCC to put variables in
+the stack by default, rather than in registers, in functions that
+call @code{setjmp}.  This results in the behavior found in
+traditional C compilers.
+
+@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:
+
+@example
+@group
+foobar (
+#define luser
+        hack)
+@end group
+@end example
+
+ISO C does not permit such a construct.  It would make sense to support
+it when @option{-traditional} is used, but it is too much work to
+implement.
+
+@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).  I think
+this would be quite ugly and can't imagine it could be needed.
+
+@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.
+
+The @option{-traditional} option directs GCC to treat all @code{extern}
+declarations as global, like traditional compilers.
+
+@item
+In traditional C, you can combine @code{long}, etc., with a typedef name,
+as shown here:
+
+@example
+typedef int foo;
+typedef long foo bar;
+@end example
+
+In ISO C, this is not allowed: @code{long} and other type modifiers
+require an explicit @code{int}.  Because this criterion is expressed
+by Bison grammar rules rather than C code, the @option{-traditional}
+flag cannot alter it.
+
+@cindex typedef names as function parameters
+@item
+PCC allows typedef names to be used as function parameters.  The
+difficulty described immediately above applies here too.
+
+@item
+When in @option{-traditional} mode, GCC allows the following erroneous
+pair of declarations to appear together in a given scope:
+
+@example
+typedef int foo;
+typedef foo foo;
+@end example
+
+@item
+GCC treats all characters of identifiers as significant, even when in
+@option{-traditional} mode.  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.  The difficulty described immediately above applies here
+too.
+
+@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:
+
+@example
+#if 0
+You can't expect this to work.
+#endif
+@end example
+
+The best solution to such a problem is to put the text into an actual
+C comment delimited by @samp{/*@dots{}*/}.  However,
+@option{-traditional} suppresses these error messages.
+
+@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 machine-description macros @code{STRUCT_VALUE} and
+@code{STRUCT_INCOMING_VALUE} tell 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} (or for certain
+targets an alternative such as @code{fixinc.svr4}).  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.  The easiest way to update them is to reinstall GCC@.  (If
+you want to be clever, look in the makefile and you can find a
+shortcut.)
+
+@item
+On some systems, in particular SunOS 4, 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 SunOS 4 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.
+
+In SunOS 4, only programs that look inside the kernel will notice the
+difference between machine models.  Therefore, for most purposes, you
+need not be concerned about this.
+
+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.
+
+@item
+On Lynxos, GCC by default does not fix the header files.  This is
+because bugs in the shell cause the @code{fixincludes} script to fail.
+
+This means you will encounter problems due to bugs in the system header
+files.  It may be no comfort that they aren't GCC's fault, but it
+does mean that there's nothing for us to do about them.
+@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:
+
+@example
+int foo (struct mumble *);
+
+struct mumble @{ @dots{} @};
+
+int foo (struct mumble *x)
+@{ @dots{} @}
+@end example
+
+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.  You will have to reinstall GCC
+to fix the new header files.  More specifically, go to the build
+directory and delete the files @file{stmp-fixinc} and
+@file{stmp-headers}, and the subdirectory @code{include}; then do
+@samp{make install} again.
+
+@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 the MIPS, variable argument functions using @file{varargs.h}
+cannot have a floating point value for the first argument.  The
+reason for this is that in the absence of a prototype in scope,
+if the first argument is a floating point, it is passed in a
+floating point register, rather than an integer register.
+
+If the code is rewritten to use the ISO standard @file{stdarg.h}
+method of variable arguments, and the prototype is in scope at
+the time of the call, everything will work fine.
+
+@item
+On the H8/300 and H8/300H, variable argument functions must be
+implemented using the ISO standard @file{stdarg.h} method of
+variable arguments.  Furthermore, calls to functions using @file{stdarg.h}
+variable arguments must have a prototype for the called function
+in scope at the time of the call.
+@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
+* 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:
+
+@example
+class Foo
+@{
+  @dots{}
+  void method();
+  static int bar;
+@};
+@end example
+
+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:
+
+@example
+int Foo::bar = 0;
+@end example
+
+Other C++ compilers may not correctly implement the standard behavior.
+As a result, when you switch to @code{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: @code{g++} reports as undefined
+symbols any static data members that lack definitions.
+
+@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}:
+
+@example
+string strfunc ();
+void charfunc (const char *);
+
+void
+f ()
+@{
+  const char *p = strfunc().c_str();
+  @dots{}
+  charfunc (p);
+  @dots{}
+  charfunc (p);
+@}
+@end example
+
+@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:
+
+@example
+string& tmp = strfunc ();
+charfunc (tmp.c_str ());
+@end example
+
+@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:
+
+@example
+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 example
+
+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 many times.  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 Wconversion
+You can find all the places where this problem might occur by compiling
+the program with the @option{-Wconversion} 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.
+
+Coming as I do from a Lisp background, I balk at the idea that there is
+something dangerous about discarding a value.  There are functions that
+return values which some callers may find useful; it makes no sense to
+clutter the program with a cast to @code{void} whenever the value isn't
+useful.
+
+@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 traditional
+@opindex std
+Undefining @code{__STDC__} when @option{-ansi} is not used.
+
+Currently, GCC defines @code{__STDC__} as long as you don't use
+@option{-traditional}.  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, which holds for C but is not always the
+case for C++.
+
+@opindex funroll-loops
+Moreover, with @option{-funroll-loops} small ``empty'' loops are already
+removed, so the current behavior is both sub-optimal and inconsistent
+and will change in the future.
+
+@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:
+
+@example
+void func (int, int);
+
+int i = 2;
+func (i++, i++);
+@end example
+
+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
+Not allowing structures with volatile fields in registers.
+
+Strictly speaking, there is no prohibition in the ISO C standard
+against allowing structures with volatile fields in registers, but
+it does not seem to make any sense and is probably not what you wanted
+to do.  So the compiler will give an error message in this case.
+
+@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 test suites 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.