gcc.texi: Move several chapters out to ...

	* 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.

From-SVN: r46929

10 files changed, 2514 insertions, 2458 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index eb1a3fb..f4825e7 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,5 +1,13 @@
 2001-11-11  Joseph S. Myers  <jsm28@cam.ac.uk>
 
+	* 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.
+
+2001-11-11  Joseph S. Myers  <jsm28@cam.ac.uk>
+
 	* ChangeLog.2, ChangeLog.3, ChangeLog.4, ChangeLog.5, ChangeLog,
 	cfg.c, cfganal.c, cfgcleanup.c, cfglayout.c, cfgloop.c, cfgrtl.c,
 	collect2.c, combine.c, config.in, configure, configure.in,
diff --git a/gcc/Makefile.in b/gcc/Makefile.in
index 2e9d3fe..2112a07 100644
--- a/gcc/Makefile.in
+++ b/gcc/Makefile.in
@@ -2315,7 +2315,10 @@ $(docdir)/gcc.info: $(docdir)/gcc.texi $(docdir)/extend.texi \
 	 $(docdir)/c-tree.texi $(docdir)/rtl.texi $(docdir)/tm.texi \
 	 $(docdir)/gcov.texi $(docdir)/contrib.texi $(docdir)/objc.texi \
 	 $(docdir)/include/fdl.texi $(docdir)/include/gpl.texi \
-	 $(docdir)/include/funding.texi
+	 $(docdir)/include/funding.texi $(docdir)/bugreport.texi \
+	 $(docdir)/contribute.texi $(docdir)/frontends.texi \
+	 $(docdir)/service.texi $(docdir)/standards.texi \
+	 $(docdir)/trouble.texi $(docdir)/vms.texi
 	cd $(srcdir) && $(MAKEINFO) $(MAKEINFOFLAGS) -I doc -I doc/include -o doc/gcc.info doc/gcc.texi
 
 $(docdir)/cppinternals.info: $(docdir)/cppinternals.texi
@@ -2333,7 +2336,10 @@ gcc.dvi: $(docdir)/gcc.texi $(docdir)/extend.texi $(docdir)/install-old.texi \
 	 $(docdir)/rtl.texi $(docdir)/tm.texi $(docdir)/gcov.texi \
 	 $(docdir)/contrib.texi $(docdir)/objc.texi \
 	 $(docdir)/include/fdl.texi $(docdir)/include/gpl.texi \
-	 $(docdir)/include/funding.texi
+	 $(docdir)/include/funding.texi $(docdir)/bugreport.texi \
+	 $(docdir)/contribute.texi $(docdir)/frontends.texi \
+	 $(docdir)/service.texi $(docdir)/standards.texi \
+	 $(docdir)/trouble.texi $(docdir)/vms.texi
 	$(TEXI2DVI) -I $(docdir) -I $(docdir)/include $(docdir)/gcc.texi
 
 cppinternals.dvi: $(docdir)/cppinternals.texi
diff --git a/gcc/doc/bugreport.texi b/gcc/doc/bugreport.texi
new file mode 100644
index 0000000..1ac26c5
--- /dev/null
+++ b/gcc/doc/bugreport.texi
@@ -0,0 +1,394 @@
+@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 Bugs
+@chapter Reporting Bugs
+@cindex bugs
+@cindex reporting bugs
+
+Your bug reports play an essential role in making GCC reliable.
+
+When you encounter a problem, the first thing to do is to see if it is
+already known.  @xref{Trouble}.  If it isn't known, then you should
+report the problem.
+
+Reporting a bug may help you by bringing a solution to your problem, or
+it may not.  (If it does not, look in the service directory; see
+@ref{Service}.)  In any case, the principal function of a bug report is
+to help the entire community by making the next version of GCC work
+better.  Bug reports are your contribution to the maintenance of GCC@.
+
+Since the maintainers are very overloaded, we cannot respond to every
+bug report.  However, if the bug has not been fixed, we are likely to
+send you a patch and ask you to tell us whether it works.
+
+In order for a bug report to serve its purpose, you must include the
+information that makes for fixing the bug.
+
+@menu
+* Criteria:  Bug Criteria.   Have you really found a bug?
+* Where: Bug Lists.	     Where to send your bug report.
+* Reporting: Bug Reporting.  How to report a bug effectively.
+* GNATS: gccbug.             You can use a bug reporting tool.
+* Known: Trouble.            Known problems.
+* Help: Service.             Where to ask for help.
+@end menu
+
+@node Bug Criteria,Bug Lists,,Bugs
+@section Have You Found a Bug?
+@cindex bug criteria
+
+If you are not sure whether you have found a bug, here are some guidelines:
+
+@itemize @bullet
+@cindex fatal signal
+@cindex core dump
+@item
+If the compiler gets a fatal signal, for any input whatever, that is a
+compiler bug.  Reliable compilers never crash.
+
+@cindex invalid assembly code
+@cindex assembly code, invalid
+@item
+If the compiler produces invalid assembly code, for any input whatever
+(except an @code{asm} statement), that is a compiler bug, unless the
+compiler reports errors (not just warnings) which would ordinarily
+prevent the assembler from being run.
+
+@cindex undefined behavior
+@cindex undefined function value
+@cindex increment operators
+@item
+If the compiler produces valid assembly code that does not correctly
+execute the input source code, that is a compiler bug.
+
+However, you must double-check to make sure, because you may have run
+into an incompatibility between GNU C and traditional C
+(@pxref{Incompatibilities}).  These incompatibilities might be considered
+bugs, but they are inescapable consequences of valuable features.
+
+Or you may have a program whose behavior is undefined, which happened
+by chance to give the desired results with another C or C++ compiler.
+
+For example, in many nonoptimizing compilers, you can write @samp{x;}
+at the end of a function instead of @samp{return x;}, with the same
+results.  But the value of the function is undefined if @code{return}
+is omitted; it is not a bug when GCC produces different results.
+
+Problems often result from expressions with two increment operators,
+as in @code{f (*p++, *p++)}.  Your previous compiler might have
+interpreted that expression the way you intended; GCC might
+interpret it another way.  Neither compiler is wrong.  The bug is
+in your code.
+
+After you have localized the error to a single source line, it should
+be easy to check for these things.  If your program is correct and
+well defined, you have found a compiler bug.
+
+@item
+If the compiler produces an error message for valid input, that is a
+compiler bug.
+
+@cindex invalid input
+@item
+If the compiler does not produce an error message for invalid input,
+that is a compiler bug.  However, you should note that your idea of
+``invalid input'' might be my idea of ``an extension'' or ``support
+for traditional practice''.
+
+@item
+If you are an experienced user of one of the languages GCC supports, your
+suggestions for improvement of GCC are welcome in any case.
+@end itemize
+
+@node Bug Lists,Bug Reporting,Bug Criteria,Bugs
+@section Where to Report Bugs
+@cindex bug report mailing lists
+@kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
+Send bug reports for the GNU Compiler Collection to
+@email{gcc-bugs@@gcc.gnu.org}.  In accordance with the GNU-wide
+convention, in which bug reports for tool ``foo'' are sent
+to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
+may also be used; it will forward to the address given above.
+
+Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or
+more up-to-date bug reporting instructions before you post a bug report.
+
+@node Bug Reporting,gccbug,Bug Lists,Bugs
+@section How to Report Bugs
+@cindex compiler bugs, reporting
+
+The fundamental principle of reporting bugs usefully is this:
+@strong{report all the facts}.  If you are not sure whether to state a
+fact or leave it out, state it!
+
+Often people omit facts because they think they know what causes the
+problem and they conclude that some details don't matter.  Thus, you might
+assume that the name of the variable you use in an example does not matter.
+Well, probably it doesn't, but one cannot be sure.  Perhaps the bug is a
+stray memory reference which happens to fetch from the location where that
+name is stored in memory; perhaps, if the name were different, the contents
+of that location would fool the compiler into doing the right thing despite
+the bug.  Play it safe and give a specific, complete example.  That is the
+easiest thing for you to do, and the most helpful.
+
+Keep in mind that the purpose of a bug report is to enable someone to
+fix the bug if it is not known.  It isn't very important what happens if
+the bug is already known.  Therefore, always write your bug reports on
+the assumption that the bug is not known.
+
+Sometimes people give a few sketchy facts and ask, ``Does this ring a
+bell?''  This cannot help us fix a bug, so it is basically useless.  We
+respond by asking for enough details to enable us to investigate.
+You might as well expedite matters by sending them to begin with.
+
+Try to make your bug report self-contained.  If we have to ask you for
+more information, it is best if you include all the previous information
+in your response, as well as the information that was missing.
+
+Please report each bug in a separate message.  This makes it easier for
+us to track which bugs have been fixed and to forward your bugs reports
+to the appropriate maintainer.
+
+To enable someone to investigate the bug, you should include all these
+things:
+
+@itemize @bullet
+@item
+The version of GCC@.  You can get this by running it with the
+@option{-v} option.
+
+Without this, we won't know whether there is any point in looking for
+the bug in the current version of GCC@.
+
+@item
+A complete input file that will reproduce the bug.  If the bug is in the
+C preprocessor, send a source file and any header files that it
+requires.  If the bug is in the compiler proper (@file{cc1}), send the
+preprocessor output generated by adding @option{-save-temps} to the
+compilation command (@pxref{Debugging Options}).  When you do this, use
+the same @option{-I}, @option{-D} or @option{-U} options that you used in
+actual compilation.  Then send the @var{input}.i or @var{input}.ii files
+generated.
+
+A single statement is not enough of an example.  In order to compile it,
+it must be embedded in a complete file of compiler input; and the bug
+might depend on the details of how this is done.
+
+Without a real example one can compile, all anyone can do about your bug
+report is wish you luck.  It would be futile to try to guess how to
+provoke the bug.  For example, bugs in register allocation and reloading
+frequently depend on every little detail of the function they happen in.
+
+Even if the input file that fails comes from a GNU program, you should
+still send the complete test case.  Don't ask the GCC maintainers to
+do the extra work of obtaining the program in question---they are all
+overworked as it is.  Also, the problem may depend on what is in the
+header files on your system; it is unreliable for the GCC maintainers
+to try the problem with the header files available to them.  By sending
+CPP output, you can eliminate this source of uncertainty and save us
+a certain percentage of wild goose chases.
+
+@item
+The command arguments you gave GCC to compile that example
+and observe the bug.  For example, did you use @option{-O}?  To guarantee
+you won't omit something important, list all the options.
+
+If we were to try to guess the arguments, we would probably guess wrong
+and then we would not encounter the bug.
+
+@item
+The type of machine you are using, and the operating system name and
+version number.
+
+@item
+The operands you gave to the @code{configure} command when you installed
+the compiler.
+
+@item
+A complete list of any modifications you have made to the compiler
+source.  (We don't promise to investigate the bug unless it happens in
+an unmodified compiler.  But if you've made modifications and don't tell
+us, then you are sending us on a wild goose chase.)
+
+Be precise about these changes.  A description in English is not
+enough---send a context diff for them.
+
+Adding files of your own (such as a machine description for a machine we
+don't support) is a modification of the compiler source.
+
+@item
+Details of any other deviations from the standard procedure for installing
+GCC@.
+
+@item
+A description of what behavior you observe that you believe is
+incorrect.  For example, ``The compiler gets a fatal signal,'' or,
+``The assembler instruction at line 208 in the output is incorrect.''
+
+Of course, if the bug is that the compiler gets a fatal signal, then one
+can't miss it.  But if the bug is incorrect output, the maintainer might
+not notice unless it is glaringly wrong.  None of us has time to study
+all the assembler code from a 50-line C program just on the chance that
+one instruction might be wrong.  We need @emph{you} to do this part!
+
+Even if the problem you experience is a fatal signal, you should still
+say so explicitly.  Suppose something strange is going on, such as, your
+copy of the compiler is out of synch, or you have encountered a bug in
+the C library on your system.  (This has happened!)  Your copy might
+crash and the copy here would not.  If you @i{said} to expect a crash,
+then when the compiler here fails to crash, we would know that the bug
+was not happening.  If you don't say to expect a crash, then we would
+not know whether the bug was happening.  We would not be able to draw
+any conclusion from our observations.
+
+If the problem is a diagnostic when compiling GCC with some other
+compiler, say whether it is a warning or an error.
+
+Often the observed symptom is incorrect output when your program is run.
+Sad to say, this is not enough information unless the program is short
+and simple.  None of us has time to study a large program to figure out
+how it would work if compiled correctly, much less which line of it was
+compiled wrong.  So you will have to do that.  Tell us which source line
+it is, and what incorrect result happens when that line is executed.  A
+person who understands the program can find this as easily as finding a
+bug in the program itself.
+
+@item
+If you send examples of assembler code output from GCC,
+please use @option{-g} when you make them.  The debugging information
+includes source line numbers which are essential for correlating the
+output with the input.
+
+@item
+If you wish to mention something in the GCC source, refer to it by
+context, not by line number.
+
+The line numbers in the development sources don't match those in your
+sources.  Your line numbers would convey no useful information to the
+maintainers.
+
+@item
+Additional information from a debugger might enable someone to find a
+problem on a machine which he does not have available.  However, you
+need to think when you collect this information if you want it to have
+any chance of being useful.
+
+@cindex backtrace for bug reports
+For example, many people send just a backtrace, but that is never
+useful by itself.  A simple backtrace with arguments conveys little
+about GCC because the compiler is largely data-driven; the same
+functions are called over and over for different RTL insns, doing
+different things depending on the details of the insn.
+
+Most of the arguments listed in the backtrace are useless because they
+are pointers to RTL list structure.  The numeric values of the
+pointers, which the debugger prints in the backtrace, have no
+significance whatever; all that matters is the contents of the objects
+they point to (and most of the contents are other such pointers).
+
+In addition, most compiler passes consist of one or more loops that
+scan the RTL insn sequence.  The most vital piece of information about
+such a loop---which insn it has reached---is usually in a local variable,
+not in an argument.
+
+@findex debug_rtx
+What you need to provide in addition to a backtrace are the values of
+the local variables for several stack frames up.  When a local
+variable or an argument is an RTX, first print its value and then use
+the GDB command @code{pr} to print the RTL expression that it points
+to.  (If GDB doesn't run on your machine, use your debugger to call
+the function @code{debug_rtx} with the RTX as an argument.)  In
+general, whenever a variable is a pointer, its value is no use
+without the data it points to.
+@end itemize
+
+Here are some things that are not necessary:
+
+@itemize @bullet
+@item
+A description of the envelope of the bug.
+
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
+
+This is often time consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger with
+breakpoints, not by pure deduction from a series of examples.  You might
+as well save your time for something else.
+
+Of course, if you can find a simpler example to report @emph{instead} of
+the original one, that is a convenience.  Errors in the output will be
+easier to spot, running under the debugger will take less time, etc.
+Most GCC bugs involve just one function, so the most straightforward
+way to simplify an example is to delete all the function definitions
+except the one where the bug occurs.  Those earlier in the file may be
+replaced by external declarations if the crucial function depends on
+them.  (Exception: inline functions may affect compilation of functions
+defined later in the file.)
+
+However, simplification is not vital; if you don't want to do this,
+report the bug anyway and send the entire test case you used.
+
+@item
+In particular, some people insert conditionals @samp{#ifdef BUG} around
+a statement which, if removed, makes the bug not happen.  These are just
+clutter; we won't pay any attention to them anyway.  Besides, you should
+send us cpp output, and that can't have conditionals.
+
+@item
+A patch for the bug.
+
+A patch for the bug is useful if it is a good one.  But don't omit the
+necessary information, such as the test case, on the assumption that a
+patch is all we need.  We might see problems with your patch and decide
+to fix the problem another way, or we might not understand it at all.
+
+Sometimes with a program as complicated as GCC it is very hard to
+construct an example that will make the program follow a certain path
+through the code.  If you don't send the example, we won't be able to
+construct one, so we won't be able to verify that the bug is fixed.
+
+And if we can't understand what bug you are trying to fix, or why your
+patch should be an improvement, we won't install it.  A test case will
+help us to understand.
+
+See @uref{http://gcc.gnu.org/contribute.html}
+for guidelines on how to make it easy for us to
+understand and install your patches.
+
+@item
+A guess about what the bug is or what it depends on.
+
+Such guesses are usually wrong.  Even I can't guess right about such
+things without first using the debugger to find the facts.
+
+@item
+A core dump file.
+
+We have no way of examining a core dump for your type of machine
+unless we have an identical system---and if we do have one,
+we should be able to reproduce the crash ourselves.
+@end itemize
+
+@node gccbug,, Bug Reporting, Bugs
+@section The gccbug script
+@cindex gccbug script
+
+To simplify creation of bug reports, and to allow better tracking of
+reports, we use the GNATS bug tracking system.  Part of that system is
+the @code{gccbug} script.  This is a Unix shell script, so you need a
+shell to run it.  It is normally installed in the same directory where
+@code{gcc} is installed.
+
+The gccbug script is derived from send-pr, @pxref{using
+send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}.  When
+invoked, it starts a text editor so you can fill out the various fields
+of the report.  When the you quit the editor, the report is automatically
+send to the bug reporting address.
+
+A number of fields in this bug report form are specific to GCC, and are
+explained at @uref{http://gcc.gnu.org/gnats.html}.
diff --git a/gcc/doc/contribute.texi b/gcc/doc/contribute.texi
new file mode 100644
index 0000000..f9a5f97
--- /dev/null
+++ b/gcc/doc/contribute.texi
@@ -0,0 +1,25 @@
+@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 Contributing
+@chapter Contributing to GCC Development
+
+If you would like to help pretest GCC releases to assure they work well,
+our current development sources are available by CVS (see
+@uref{http://gcc.gnu.org/cvs.html}).  Source and binary snapshots are
+also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
+
+If you would like to work on improvements to GCC, please read the
+advice at these URLs:
+
+@smallexample
+@uref{http://gcc.gnu.org/contribute.html} 
+@uref{http://gcc.gnu.org/contributewhy.html}
+@end smallexample
+
+@noindent
+for information on how to make useful contributions and avoid
+duplication of effort.  Suggested projects are listed at
+@uref{http://gcc.gnu.org/projects/}.
diff --git a/gcc/doc/frontends.texi b/gcc/doc/frontends.texi
new file mode 100644
index 0000000..ffaa9aa
--- /dev/null
+++ b/gcc/doc/frontends.texi
@@ -0,0 +1,70 @@
+@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 G++ and GCC
+@chapter Compile C, C++, Objective-C, Ada, CHILL, Fortran, or Java
+
+@cindex Objective-C
+@cindex Fortran
+@cindex Java
+@cindex CHILL
+@cindex Ada
+Several versions of the compiler (C, C++, Objective-C, Ada, CHILL,
+Fortran, and Java) are integrated; this is why we use the name
+``GNU Compiler Collection''.  GCC can compile programs written in any of these
+languages.  The Ada, CHILL, Fortran, and Java compilers are described in
+separate manuals.
+
+@cindex GCC
+``GCC'' is a common shorthand term for the GNU Compiler Collection.  This is both
+the most general name for the compiler, and the name used when the
+emphasis is on compiling C programs (as the abbreviation formerly
+stood for ``GNU C Compiler'').
+
+@cindex C++
+@cindex G++
+When referring to C++ compilation, it is usual to call the compiler
+``G++''.  Since there is only one compiler, it is also accurate to call
+it ``GCC'' no matter what the language context; however, the term
+``G++'' is more useful when the emphasis is on compiling C++ programs.
+
+@cindex Ada
+@cindex GNAT
+Similarly, when we talk about Ada compilation, we usually call the
+compiler ``GNAT'', for the same reasons.
+
+We use the name ``GCC'' to refer to the compilation system as a
+whole, and more specifically to the language-independent part of the
+compiler.  For example, we refer to the optimization options as
+affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
+
+Front ends for other languages, such as Mercury and Pascal exist but
+have not yet been integrated into GCC@.  These front ends, like that for C++,
+are built in subdirectories of GCC and link to it.  The result is an
+integrated compiler that can compile programs written in C, C++,
+Objective-C, or any of the languages for which you have installed front
+ends.
+
+In this manual, we only discuss the options for the C, Objective-C, and
+C++ compilers and those of the GCC core.  Consult the documentation
+of the other front ends for the options to use when compiling programs
+written in other languages.
+
+@cindex compiler compared to C++ preprocessor
+@cindex intermediate C version, nonexistent
+@cindex C intermediate output, nonexistent
+G++ is a @emph{compiler}, not merely a preprocessor.  G++ builds object
+code directly from your C++ program source.  There is no intermediate C
+version of the program.  (By contrast, for example, some other
+implementations use a program that generates a C program from your C++
+source.)  Avoiding an intermediate C representation of the program means
+that you get better object code, and better debugging information.  The
+GNU debugger, GDB, works with this information in the object code to
+give you comprehensive C++ source-level editing capabilities
+(@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
+
+@c FIXME!  Someone who knows something about Objective-C ought to put in
+@c a paragraph or two about it here, and move the index entry down when
+@c there is more to point to than the general mention in the 1st par.
diff --git a/gcc/doc/gcc.texi b/gcc/doc/gcc.texi
index f476d8d..43301ab 100644
--- a/gcc/doc/gcc.texi
+++ b/gcc/doc/gcc.texi
@@ -277,242 +277,10 @@ bugs.  It corresponds to GCC version 3.1.
 @end menu
 
 @ifset USING
-@node G++ and GCC
-@chapter Compile C, C++, Objective-C, Ada, CHILL, Fortran, or Java
-
-@cindex Objective-C
-@cindex Fortran
-@cindex Java
-@cindex CHILL
-@cindex Ada
-Several versions of the compiler (C, C++, Objective-C, Ada, CHILL,
-Fortran, and Java) are integrated; this is why we use the name
-``GNU Compiler Collection''.  GCC can compile programs written in any of these
-languages.  The Ada, CHILL, Fortran, and Java compilers are described in
-separate manuals.
-
-@cindex GCC
-``GCC'' is a common shorthand term for the GNU Compiler Collection.  This is both
-the most general name for the compiler, and the name used when the
-emphasis is on compiling C programs (as the abbreviation formerly
-stood for ``GNU C Compiler'').
-
-@cindex C++
-@cindex G++
-When referring to C++ compilation, it is usual to call the compiler
-``G++''.  Since there is only one compiler, it is also accurate to call
-it ``GCC'' no matter what the language context; however, the term
-``G++'' is more useful when the emphasis is on compiling C++ programs.
-
-@cindex Ada
-@cindex GNAT
-Similarly, when we talk about Ada compilation, we usually call the
-compiler ``GNAT'', for the same reasons.
-
-We use the name ``GCC'' to refer to the compilation system as a
-whole, and more specifically to the language-independent part of the
-compiler.  For example, we refer to the optimization options as
-affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
-
-Front ends for other languages, such as Mercury and Pascal exist but
-have not yet been integrated into GCC@.  These front ends, like that for C++,
-are built in subdirectories of GCC and link to it.  The result is an
-integrated compiler that can compile programs written in C, C++,
-Objective-C, or any of the languages for which you have installed front
-ends.
-
-In this manual, we only discuss the options for the C, Objective-C, and
-C++ compilers and those of the GCC core.  Consult the documentation
-of the other front ends for the options to use when compiling programs
-written in other languages.
-
-@cindex compiler compared to C++ preprocessor
-@cindex intermediate C version, nonexistent
-@cindex C intermediate output, nonexistent
-G++ is a @emph{compiler}, not merely a preprocessor.  G++ builds object
-code directly from your C++ program source.  There is no intermediate C
-version of the program.  (By contrast, for example, some other
-implementations use a program that generates a C program from your C++
-source.)  Avoiding an intermediate C representation of the program means
-that you get better object code, and better debugging information.  The
-GNU debugger, GDB, works with this information in the object code to
-give you comprehensive C++ source-level editing capabilities
-(@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
-
-@c FIXME!  Someone who knows something about Objective-C ought to put in
-@c a paragraph or two about it here, and move the index entry down when
-@c there is more to point to than the general mention in the 1st par.
-
-@node Standards
-@chapter Language Standards Supported by GCC
-@cindex C standard
-@cindex C standards
-@cindex ANSI C standard
-@cindex ANSI C
-@cindex ANSI C89
-@cindex C89
-@cindex ANSI X3.159-1989
-@cindex X3.159-1989
-@cindex ISO C standard
-@cindex ISO C
-@cindex ISO C89
-@cindex ISO C90
-@cindex ISO/IEC 9899
-@cindex ISO 9899
-@cindex C90
-@cindex ISO C94
-@cindex C94
-@cindex ISO C95
-@cindex C95
-@cindex ISO C99
-@cindex C99
-@cindex ISO C9X
-@cindex C9X
-@cindex Technical Corrigenda
-@cindex TC1
-@cindex Technical Corrigendum 1
-@cindex TC2
-@cindex Technical Corrigendum 2
-@cindex AMD1
-@cindex freestanding implementation
-@cindex freestanding environment
-@cindex hosted implementation
-@cindex hosted environment
-@findex __STDC_HOSTED__
-
-For each language compiled by GCC for which there is a standard, GCC
-attempts to follow one or more versions of that standard, possibly
-with some exceptions, and possibly with some extensions.
-
-GCC supports three versions of the C standard, although support for
-the most recent version is not yet complete.
-
-@opindex std
-@opindex ansi
-@opindex pedantic
-@opindex pedantic-errors
-The original ANSI C standard (X3.159-1989) was ratified in 1989 and
-published in 1990.  This standard was ratified as an ISO standard
-(ISO/IEC 9899:1990) later in 1990.  There were no technical
-differences between these publications, although the sections of the
-ANSI standard were renumbered and became clauses in the ISO standard.
-This standard, in both its forms, is commonly known as @dfn{C89}, or
-occasionally as @dfn{C90}, from the dates of ratification.  The ANSI
-standard, but not the ISO standard, also came with a Rationale
-document.  To select this standard in GCC, use one of the options
-@option{-ansi}, @option{-std=c89} or @option{-std=iso9899:1990}; to obtain
-all the diagnostics required by the standard, you should also specify
-@option{-pedantic} (or @option{-pedantic-errors} if you want them to be
-errors rather than warnings).  @xref{C Dialect Options,,Options
-Controlling C Dialect}.
-
-Errors in the 1990 ISO C standard were corrected in two Technical
-Corrigenda published in 1994 and 1996.  GCC does not support the
-uncorrected version.
-
-An amendment to the 1990 standard was published in 1995.  This
-amendment added digraphs and @code{__STDC_VERSION__} to the language,
-but otherwise concerned the library.  This amendment is commonly known
-as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
-@dfn{C95}.  To select this standard in GCC, use the option
-@option{-std=iso9899:199409} (with, as for other standard versions,
-@option{-pedantic} to receive all required diagnostics).
-
-A new edition of the ISO C standard was published in 1999 as ISO/IEC
-9899:1999, and is commonly known as @dfn{C99}.  GCC has incomplete
-support for this standard version; see
-@uref{http://gcc.gnu.org/c99status.html} for details.  To select this
-standard, use @option{-std=c99} or @option{-std=iso9899:1999}.  (While in
-development, drafts of this standard version were referred to as
-@dfn{C9X}.)
-
-@opindex traditional
-GCC also has some limited support for traditional (pre-ISO) C with the
-@option{-traditional} option.  This support may be of use for compiling
-some very old programs that have not been updated to ISO C, but should
-not be used for new programs.  It will not work with some modern C
-libraries such as the GNU C library.
-
-By default, GCC provides some extensions to the C language that on
-rare occasions conflict with the C standard.  @xref{C
-Extensions,,Extensions to the C Language Family}.  Use of the
-@option{-std} options listed above will disable these extensions where
-they conflict with the C standard version selected.  You may also
-select an extended version of the C language explicitly with
-@option{-std=gnu89} (for C89 with GNU extensions) or @option{-std=gnu99}
-(for C99 with GNU extensions).  The default, if no C language dialect
-options are given, is @option{-std=gnu89}; this will change to
-@option{-std=gnu99} in some future release when the C99 support is
-complete.  Some features that are part of the C99 standard are
-accepted as extensions in C89 mode.
-
-The ISO C standard defines (in clause 4) two classes of conforming
-implementation.  A @dfn{conforming hosted implementation} supports the
-whole standard including all the library facilities; a @dfn{conforming
-freestanding implementation} is only required to provide certain
-library facilities: those in @code{<float.h>}, @code{<limits.h>},
-@code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
-@code{<iso646.h>}; and in C99, also those in @code{<stdbool.h>} and
-@code{<stdint.h>}.  In addition, complex types, added in C99, are not
-required for freestanding implementations.  The standard also defines
-two environments for programs, a @dfn{freestanding environment},
-required of all implementations and which may not have library
-facilities beyond those required of freestanding implementations,
-where the handling of program startup and termination are
-implementation-defined, and a @dfn{hosted environment}, which is not
-required, in which all the library facilities are provided and startup
-is through a function @code{int main (void)} or @code{int main (int,
-char *[])}.  An OS kernel would be a freestanding environment; a
-program using the facilities of an operating system would normally be
-in a hosted implementation.
-
-@opindex ffreestanding
-GCC aims towards being usable as a conforming freestanding
-implementation, or as the compiler for a conforming hosted
-implementation.  By default, it will act as the compiler for a hosted
-implementation, defining @code{__STDC_HOSTED__} as @code{1} and
-presuming that when the names of ISO C functions are used, they have
-the semantics defined in the standard.  To make it act as a conforming
-freestanding implementation for a freestanding environment, use the
-option @option{-ffreestanding}; it will then define
-@code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
-meanings of function names from the standard library.  To build an OS
-kernel, you may well still need to make your own arrangements for
-linking and startup.  @xref{C Dialect Options,,Options Controlling C
-Dialect}.
-
-GCC does not provide the library facilities required only of hosted
-implementations, nor yet all the facilities required by C99 of
-freestanding implementations; to use the facilities of a hosted
-environment, you will need to find them elsewhere (for example, in the
-GNU C library).  @xref{Standard Libraries,,Standard Libraries}.
-
-For references to Technical Corrigenda, Rationale documents and
-information concerning the history of C that is available online, see
-@uref{http://gcc.gnu.org/readings.html}
-
-@c FIXME: details of C++ standard.
-
-There is no formal written standard for Objective-C@.  The most
-authoritative manual is ``Object-Oriented Programming and the
-Objective-C Language'', available at a number of web sites;
-@uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/} has a
-recent version, while @uref{http://www.toodarkpark.org/computers/objc/}
-is an older example.  @uref{http://www.gnustep.org} includes useful
-information as well.
-
-@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, 
-GNAT Reference Manual}, for information on standard
-conformance and compatibility of the Ada compiler.
-
-@xref{References,,Language Definition References, chill, GNU Chill},
-for details of the CHILL standard.
-
-@xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
-Fortran}, for details of the Fortran language supported by GCC@.
-
-@xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj},
-for details of compatibility between @code{gcj} and the Java Platform.
+
+@include frontends.texi
+
+@include standards.texi
 
 @include invoke.texi
 
@@ -524,2230 +292,15 @@ for details of compatibility between @code{gcj} and the Java Platform.
 
 @include gcov.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.
+@include trouble.texi
 
-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.
-
-@node Bugs
-@chapter Reporting Bugs
-@cindex bugs
-@cindex reporting bugs
-
-Your bug reports play an essential role in making GCC reliable.
-
-When you encounter a problem, the first thing to do is to see if it is
-already known.  @xref{Trouble}.  If it isn't known, then you should
-report the problem.
-
-Reporting a bug may help you by bringing a solution to your problem, or
-it may not.  (If it does not, look in the service directory; see
-@ref{Service}.)  In any case, the principal function of a bug report is
-to help the entire community by making the next version of GCC work
-better.  Bug reports are your contribution to the maintenance of GCC@.
-
-Since the maintainers are very overloaded, we cannot respond to every
-bug report.  However, if the bug has not been fixed, we are likely to
-send you a patch and ask you to tell us whether it works.
-
-In order for a bug report to serve its purpose, you must include the
-information that makes for fixing the bug.
-
-@menu
-* Criteria:  Bug Criteria.   Have you really found a bug?
-* Where: Bug Lists.	     Where to send your bug report.
-* Reporting: Bug Reporting.  How to report a bug effectively.
-* GNATS: gccbug.             You can use a bug reporting tool.
-* Known: Trouble.            Known problems.
-* Help: Service.             Where to ask for help.
-@end menu
-
-@node Bug Criteria,Bug Lists,,Bugs
-@section Have You Found a Bug?
-@cindex bug criteria
-
-If you are not sure whether you have found a bug, here are some guidelines:
-
-@itemize @bullet
-@cindex fatal signal
-@cindex core dump
-@item
-If the compiler gets a fatal signal, for any input whatever, that is a
-compiler bug.  Reliable compilers never crash.
-
-@cindex invalid assembly code
-@cindex assembly code, invalid
-@item
-If the compiler produces invalid assembly code, for any input whatever
-(except an @code{asm} statement), that is a compiler bug, unless the
-compiler reports errors (not just warnings) which would ordinarily
-prevent the assembler from being run.
-
-@cindex undefined behavior
-@cindex undefined function value
-@cindex increment operators
-@item
-If the compiler produces valid assembly code that does not correctly
-execute the input source code, that is a compiler bug.
-
-However, you must double-check to make sure, because you may have run
-into an incompatibility between GNU C and traditional C
-(@pxref{Incompatibilities}).  These incompatibilities might be considered
-bugs, but they are inescapable consequences of valuable features.
-
-Or you may have a program whose behavior is undefined, which happened
-by chance to give the desired results with another C or C++ compiler.
-
-For example, in many nonoptimizing compilers, you can write @samp{x;}
-at the end of a function instead of @samp{return x;}, with the same
-results.  But the value of the function is undefined if @code{return}
-is omitted; it is not a bug when GCC produces different results.
-
-Problems often result from expressions with two increment operators,
-as in @code{f (*p++, *p++)}.  Your previous compiler might have
-interpreted that expression the way you intended; GCC might
-interpret it another way.  Neither compiler is wrong.  The bug is
-in your code.
-
-After you have localized the error to a single source line, it should
-be easy to check for these things.  If your program is correct and
-well defined, you have found a compiler bug.
-
-@item
-If the compiler produces an error message for valid input, that is a
-compiler bug.
-
-@cindex invalid input
-@item
-If the compiler does not produce an error message for invalid input,
-that is a compiler bug.  However, you should note that your idea of
-``invalid input'' might be my idea of ``an extension'' or ``support
-for traditional practice''.
-
-@item
-If you are an experienced user of one of the languages GCC supports, your
-suggestions for improvement of GCC are welcome in any case.
-@end itemize
+@include bugreport.texi
 
-@node Bug Lists,Bug Reporting,Bug Criteria,Bugs
-@section Where to Report Bugs
-@cindex bug report mailing lists
-@kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
-Send bug reports for the GNU Compiler Collection to
-@email{gcc-bugs@@gcc.gnu.org}.  In accordance with the GNU-wide
-convention, in which bug reports for tool ``foo'' are sent
-to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
-may also be used; it will forward to the address given above.
-
-Please read @uref{http://gcc.gnu.org/bugs.html} for additional and/or
-more up-to-date bug reporting instructions before you post a bug report.
-
-@node Bug Reporting,gccbug,Bug Lists,Bugs
-@section How to Report Bugs
-@cindex compiler bugs, reporting
-
-The fundamental principle of reporting bugs usefully is this:
-@strong{report all the facts}.  If you are not sure whether to state a
-fact or leave it out, state it!
-
-Often people omit facts because they think they know what causes the
-problem and they conclude that some details don't matter.  Thus, you might
-assume that the name of the variable you use in an example does not matter.
-Well, probably it doesn't, but one cannot be sure.  Perhaps the bug is a
-stray memory reference which happens to fetch from the location where that
-name is stored in memory; perhaps, if the name were different, the contents
-of that location would fool the compiler into doing the right thing despite
-the bug.  Play it safe and give a specific, complete example.  That is the
-easiest thing for you to do, and the most helpful.
-
-Keep in mind that the purpose of a bug report is to enable someone to
-fix the bug if it is not known.  It isn't very important what happens if
-the bug is already known.  Therefore, always write your bug reports on
-the assumption that the bug is not known.
-
-Sometimes people give a few sketchy facts and ask, ``Does this ring a
-bell?''  This cannot help us fix a bug, so it is basically useless.  We
-respond by asking for enough details to enable us to investigate.
-You might as well expedite matters by sending them to begin with.
-
-Try to make your bug report self-contained.  If we have to ask you for
-more information, it is best if you include all the previous information
-in your response, as well as the information that was missing.
-
-Please report each bug in a separate message.  This makes it easier for
-us to track which bugs have been fixed and to forward your bugs reports
-to the appropriate maintainer.
-
-To enable someone to investigate the bug, you should include all these
-things:
+@include service.texi
 
-@itemize @bullet
-@item
-The version of GCC@.  You can get this by running it with the
-@option{-v} option.
-
-Without this, we won't know whether there is any point in looking for
-the bug in the current version of GCC@.
-
-@item
-A complete input file that will reproduce the bug.  If the bug is in the
-C preprocessor, send a source file and any header files that it
-requires.  If the bug is in the compiler proper (@file{cc1}), send the
-preprocessor output generated by adding @option{-save-temps} to the
-compilation command (@pxref{Debugging Options}).  When you do this, use
-the same @option{-I}, @option{-D} or @option{-U} options that you used in
-actual compilation.  Then send the @var{input}.i or @var{input}.ii files
-generated.
-
-A single statement is not enough of an example.  In order to compile it,
-it must be embedded in a complete file of compiler input; and the bug
-might depend on the details of how this is done.
-
-Without a real example one can compile, all anyone can do about your bug
-report is wish you luck.  It would be futile to try to guess how to
-provoke the bug.  For example, bugs in register allocation and reloading
-frequently depend on every little detail of the function they happen in.
-
-Even if the input file that fails comes from a GNU program, you should
-still send the complete test case.  Don't ask the GCC maintainers to
-do the extra work of obtaining the program in question---they are all
-overworked as it is.  Also, the problem may depend on what is in the
-header files on your system; it is unreliable for the GCC maintainers
-to try the problem with the header files available to them.  By sending
-CPP output, you can eliminate this source of uncertainty and save us
-a certain percentage of wild goose chases.
-
-@item
-The command arguments you gave GCC to compile that example
-and observe the bug.  For example, did you use @option{-O}?  To guarantee
-you won't omit something important, list all the options.
-
-If we were to try to guess the arguments, we would probably guess wrong
-and then we would not encounter the bug.
-
-@item
-The type of machine you are using, and the operating system name and
-version number.
-
-@item
-The operands you gave to the @code{configure} command when you installed
-the compiler.
-
-@item
-A complete list of any modifications you have made to the compiler
-source.  (We don't promise to investigate the bug unless it happens in
-an unmodified compiler.  But if you've made modifications and don't tell
-us, then you are sending us on a wild goose chase.)
-
-Be precise about these changes.  A description in English is not
-enough---send a context diff for them.
-
-Adding files of your own (such as a machine description for a machine we
-don't support) is a modification of the compiler source.
-
-@item
-Details of any other deviations from the standard procedure for installing
-GCC@.
-
-@item
-A description of what behavior you observe that you believe is
-incorrect.  For example, ``The compiler gets a fatal signal,'' or,
-``The assembler instruction at line 208 in the output is incorrect.''
-
-Of course, if the bug is that the compiler gets a fatal signal, then one
-can't miss it.  But if the bug is incorrect output, the maintainer might
-not notice unless it is glaringly wrong.  None of us has time to study
-all the assembler code from a 50-line C program just on the chance that
-one instruction might be wrong.  We need @emph{you} to do this part!
-
-Even if the problem you experience is a fatal signal, you should still
-say so explicitly.  Suppose something strange is going on, such as, your
-copy of the compiler is out of synch, or you have encountered a bug in
-the C library on your system.  (This has happened!)  Your copy might
-crash and the copy here would not.  If you @i{said} to expect a crash,
-then when the compiler here fails to crash, we would know that the bug
-was not happening.  If you don't say to expect a crash, then we would
-not know whether the bug was happening.  We would not be able to draw
-any conclusion from our observations.
-
-If the problem is a diagnostic when compiling GCC with some other
-compiler, say whether it is a warning or an error.
-
-Often the observed symptom is incorrect output when your program is run.
-Sad to say, this is not enough information unless the program is short
-and simple.  None of us has time to study a large program to figure out
-how it would work if compiled correctly, much less which line of it was
-compiled wrong.  So you will have to do that.  Tell us which source line
-it is, and what incorrect result happens when that line is executed.  A
-person who understands the program can find this as easily as finding a
-bug in the program itself.
-
-@item
-If you send examples of assembler code output from GCC,
-please use @option{-g} when you make them.  The debugging information
-includes source line numbers which are essential for correlating the
-output with the input.
-
-@item
-If you wish to mention something in the GCC source, refer to it by
-context, not by line number.
-
-The line numbers in the development sources don't match those in your
-sources.  Your line numbers would convey no useful information to the
-maintainers.
-
-@item
-Additional information from a debugger might enable someone to find a
-problem on a machine which he does not have available.  However, you
-need to think when you collect this information if you want it to have
-any chance of being useful.
-
-@cindex backtrace for bug reports
-For example, many people send just a backtrace, but that is never
-useful by itself.  A simple backtrace with arguments conveys little
-about GCC because the compiler is largely data-driven; the same
-functions are called over and over for different RTL insns, doing
-different things depending on the details of the insn.
-
-Most of the arguments listed in the backtrace are useless because they
-are pointers to RTL list structure.  The numeric values of the
-pointers, which the debugger prints in the backtrace, have no
-significance whatever; all that matters is the contents of the objects
-they point to (and most of the contents are other such pointers).
-
-In addition, most compiler passes consist of one or more loops that
-scan the RTL insn sequence.  The most vital piece of information about
-such a loop---which insn it has reached---is usually in a local variable,
-not in an argument.
-
-@findex debug_rtx
-What you need to provide in addition to a backtrace are the values of
-the local variables for several stack frames up.  When a local
-variable or an argument is an RTX, first print its value and then use
-the GDB command @code{pr} to print the RTL expression that it points
-to.  (If GDB doesn't run on your machine, use your debugger to call
-the function @code{debug_rtx} with the RTX as an argument.)  In
-general, whenever a variable is a pointer, its value is no use
-without the data it points to.
-@end itemize
-
-Here are some things that are not necessary:
-
-@itemize @bullet
-@item
-A description of the envelope of the bug.
-
-Often people who encounter a bug spend a lot of time investigating
-which changes to the input file will make the bug go away and which
-changes will not affect it.
-
-This is often time consuming and not very useful, because the way we
-will find the bug is by running a single example under the debugger with
-breakpoints, not by pure deduction from a series of examples.  You might
-as well save your time for something else.
-
-Of course, if you can find a simpler example to report @emph{instead} of
-the original one, that is a convenience.  Errors in the output will be
-easier to spot, running under the debugger will take less time, etc.
-Most GCC bugs involve just one function, so the most straightforward
-way to simplify an example is to delete all the function definitions
-except the one where the bug occurs.  Those earlier in the file may be
-replaced by external declarations if the crucial function depends on
-them.  (Exception: inline functions may affect compilation of functions
-defined later in the file.)
-
-However, simplification is not vital; if you don't want to do this,
-report the bug anyway and send the entire test case you used.
-
-@item
-In particular, some people insert conditionals @samp{#ifdef BUG} around
-a statement which, if removed, makes the bug not happen.  These are just
-clutter; we won't pay any attention to them anyway.  Besides, you should
-send us cpp output, and that can't have conditionals.
-
-@item
-A patch for the bug.
-
-A patch for the bug is useful if it is a good one.  But don't omit the
-necessary information, such as the test case, on the assumption that a
-patch is all we need.  We might see problems with your patch and decide
-to fix the problem another way, or we might not understand it at all.
-
-Sometimes with a program as complicated as GCC it is very hard to
-construct an example that will make the program follow a certain path
-through the code.  If you don't send the example, we won't be able to
-construct one, so we won't be able to verify that the bug is fixed.
-
-And if we can't understand what bug you are trying to fix, or why your
-patch should be an improvement, we won't install it.  A test case will
-help us to understand.
-
-See @uref{http://gcc.gnu.org/contribute.html}
-for guidelines on how to make it easy for us to
-understand and install your patches.
-
-@item
-A guess about what the bug is or what it depends on.
-
-Such guesses are usually wrong.  Even I can't guess right about such
-things without first using the debugger to find the facts.
-
-@item
-A core dump file.
-
-We have no way of examining a core dump for your type of machine
-unless we have an identical system---and if we do have one,
-we should be able to reproduce the crash ourselves.
-@end itemize
-
-@node gccbug,, Bug Reporting, Bugs
-@section The gccbug script
-@cindex gccbug script
-
-To simplify creation of bug reports, and to allow better tracking of
-reports, we use the GNATS bug tracking system.  Part of that system is
-the @code{gccbug} script.  This is a Unix shell script, so you need a
-shell to run it.  It is normally installed in the same directory where
-@code{gcc} is installed.
-
-The gccbug script is derived from send-pr, @pxref{using
-send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}.  When
-invoked, it starts a text editor so you can fill out the various fields
-of the report.  When the you quit the editor, the report is automatically
-send to the bug reporting address.
-
-A number of fields in this bug report form are specific to GCC, and are
-explained at @uref{http://gcc.gnu.org/gnats.html}.
-
-@node Service
-@chapter How To Get Help with GCC
-
-If you need help installing, using or changing GCC, there are two
-ways to find it:
-
-@itemize @bullet
-@item
-Send a message to a suitable network mailing list.  First try
-@email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
-that brings no response, try @email{gcc@@gcc.gnu.org}.  For help
-changing GCC, ask @email{gcc@@gcc.gnu.org}.  If you think you have found
-a bug in GCC, please report it following the instructions at
-@pxref{Bug Reporting}.
-
-@item
-Look in the service directory for someone who might help you for a fee.
-The service directory is found at
-@uref{http://www.gnu.org/prep/service.html}.
-@end itemize
-
-@c For further information, see
-@c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}.
-@c FIXME: this URL may be too volatile, this FAQ entry needs to move to
-@c the regular web pages before we can uncomment the reference.
-
-@node Contributing
-@chapter Contributing to GCC Development
-
-If you would like to help pretest GCC releases to assure they work well,
-our current development sources are available by CVS (see
-@uref{http://gcc.gnu.org/cvs.html}).  Source and binary snapshots are
-also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
-
-If you would like to work on improvements to GCC, please read the
-advice at these URLs:
-
-@smallexample
-@uref{http://gcc.gnu.org/contribute.html} 
-@uref{http://gcc.gnu.org/contributewhy.html}
-@end smallexample
-
-@noindent
-for information on how to make useful contributions and avoid
-duplication of effort.  Suggested projects are listed at
-@uref{http://gcc.gnu.org/projects/}.
-
-@node VMS
-@chapter Using GCC on VMS
-
-@c prevent bad page break with this line
-Here is how to use GCC on VMS@.
-
-@menu
-* Include Files and VMS::  Where the preprocessor looks for the include files.
-* Global Declarations::    How to do globaldef, globalref and globalvalue with
-                           GCC.
-* VMS Misc::		   Misc information.
-@end menu
-
-@node Include Files and VMS
-@section Include Files and VMS
-
-@cindex include files and VMS
-@cindex VMS and include files
-@cindex header files and VMS
-Due to the differences between the filesystems of Unix and VMS, GCC
-attempts to translate file names in @samp{#include} into names that VMS
-will understand.  The basic strategy is to prepend a prefix to the
-specification of the include file, convert the whole filename to a VMS
-filename, and then try to open the file.  GCC tries various prefixes
-one by one until one of them succeeds:
-
-@enumerate
-@item
-The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
-where GNU C header files are traditionally stored.  If you wish to store
-header files in non-standard locations, then you can assign the logical
-@samp{GNU_CC_INCLUDE} to be a search list, where each element of the
-list is suitable for use with a rooted logical.
-
-@item
-The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}.  This is where
-VAX-C header files are traditionally stored.
-
-@item
-If the include file specification by itself is a valid VMS filename, the
-preprocessor then uses this name with no prefix in an attempt to open
-the include file.
-
-@item
-If the file specification is not a valid VMS filename (i.e.@: does not
-contain a device or a directory specifier, and contains a @samp{/}
-character), the preprocessor tries to convert it from Unix syntax to
-VMS syntax.
-
-Conversion works like this: the first directory name becomes a device,
-and the rest of the directories are converted into VMS-format directory
-names.  For example, the name @file{X11/foobar.h} is
-translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
-whichever one can be opened.  This strategy allows you to assign a
-logical name to point to the actual location of the header files.
-
-@item
-If none of these strategies succeeds, the @samp{#include} fails.
-@end enumerate
-
-Include directives of the form:
-
-@example
-#include foobar
-@end example
-
-@noindent
-are a common source of incompatibility between VAX-C and GCC@.  VAX-C
-treats this much like a standard @code{#include <foobar.h>} directive.
-That is incompatible with the ISO C behavior implemented by GCC: to
-expand the name @code{foobar} as a macro.  Macro expansion should
-eventually yield one of the two standard formats for @code{#include}:
-
-@example
-#include "@var{file}"
-#include <@var{file}>
-@end example
-
-If you have this problem, the best solution is to modify the source to
-convert the @code{#include} directives to one of the two standard forms.
-That will work with either compiler.  If you want a quick and dirty fix,
-define the file names as macros with the proper expansion, like this:
-
-@example
-#define stdio <stdio.h>
-@end example
-
-@noindent
-This will work, as long as the name doesn't conflict with anything else
-in the program.
-
-Another source of incompatibility is that VAX-C assumes that:
-
-@example
-#include "foobar"
-@end example
-
-@noindent
-is actually asking for the file @file{foobar.h}.  GCC does not
-make this assumption, and instead takes what you ask for literally;
-it tries to read the file @file{foobar}.  The best way to avoid this
-problem is to always specify the desired file extension in your include
-directives.
-
-GCC for VMS is distributed with a set of include files that is
-sufficient to compile most general purpose programs.  Even though the
-GCC distribution does not contain header files to define constants
-and structures for some VMS system-specific functions, there is no
-reason why you cannot use GCC with any of these functions.  You first
-may have to generate or create header files, either by using the public
-domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
-extracting the relevant modules from one of the system macro libraries,
-and using an editor to construct a C header file.
-
-A @code{#include} file name cannot contain a DECNET node name.  The
-preprocessor reports an I/O error if you attempt to use a node name,
-whether explicitly, or implicitly via a logical name.
-
-@node Global Declarations
-@section Global Declarations and VMS
-
-@findex GLOBALREF
-@findex GLOBALDEF
-@findex GLOBALVALUEDEF
-@findex GLOBALVALUEREF
-GCC does not provide the @code{globalref}, @code{globaldef} and
-@code{globalvalue} keywords of VAX-C@.  You can get the same effect with
-an obscure feature of GAS, the GNU assembler.  (This requires GAS
-version 1.39 or later.)  The following macros allow you to use this
-feature in a fairly natural way:
-
-@smallexample
-#ifdef __GNUC__
-#define GLOBALREF(TYPE,NAME)                      \
-  TYPE NAME                                       \
-  asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
-#define GLOBALDEF(TYPE,NAME,VALUE)                \
-  TYPE NAME                                       \
-  asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
-    = VALUE
-#define GLOBALVALUEREF(TYPE,NAME)                 \
-  const TYPE NAME[1]                              \
-  asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
-#define GLOBALVALUEDEF(TYPE,NAME,VALUE)           \
-  const TYPE NAME[1]                              \
-  asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)  \
-    = @{VALUE@}
-#else
-#define GLOBALREF(TYPE,NAME) \
-  globalref TYPE NAME
-#define GLOBALDEF(TYPE,NAME,VALUE) \
-  globaldef TYPE NAME = VALUE
-#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
-  globalvalue TYPE NAME = VALUE
-#define GLOBALVALUEREF(TYPE,NAME) \
-  globalvalue TYPE NAME
-#endif
-@end smallexample
-
-@noindent
-(The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
-name is removed by the assembler, after it has modified the attributes
-of the symbol).  These macros are provided in the VMS binaries
-distribution in a header file @file{GNU_HACKS.H}.  An example of the
-usage is:
-
-@example
-GLOBALREF (int, ijk);
-GLOBALDEF (int, jkl, 0);
-@end example
-
-The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
-straightforwardly for arrays, since there is no way to insert the array
-dimension into the declaration at the right place.  However, you can
-declare an array with these macros if you first define a typedef for the
-array type, like this:
-
-@example
-typedef int intvector[10];
-GLOBALREF (intvector, foo);
-@end example
-
-Array and structure initializers will also break the macros; you can
-define the initializer to be a macro of its own, or you can expand the
-@code{GLOBALDEF} macro by hand.  You may find a case where you wish to
-use the @code{GLOBALDEF} macro with a large array, but you are not
-interested in explicitly initializing each element of the array.  In
-such cases you can use an initializer like: @code{@{0,@}}, which will
-initialize the entire array to @code{0}.
-
-A shortcoming of this implementation is that a variable declared with
-@code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array.  For
-example, the declaration:
-
-@example
-GLOBALVALUEREF(int, ijk);
-@end example
-
-@noindent
-declares the variable @code{ijk} as an array of type @code{int [1]}.
-This is done because a globalvalue is actually a constant; its ``value''
-is what the linker would normally consider an address.  That is not how
-an integer value works in C, but it is how an array works.  So treating
-the symbol as an array name gives consistent results---with the
-exception that the value seems to have the wrong type.  @strong{Don't
-try to access an element of the array.}  It doesn't have any elements.
-The array ``address'' may not be the address of actual storage.
-
-The fact that the symbol is an array may lead to warnings where the
-variable is used.  Insert type casts to avoid the warnings.  Here is an
-example; it takes advantage of the ISO C feature allowing macros that
-expand to use the same name as the macro itself.
-
-@example
-GLOBALVALUEREF (int, ss$_normal);
-GLOBALVALUEDEF (int, xyzzy,123);
-#ifdef __GNUC__
-#define ss$_normal ((int) ss$_normal)
-#define xyzzy ((int) xyzzy)
-#endif
-@end example
-
-Don't use @code{globaldef} or @code{globalref} with a variable whose
-type is an enumeration type; this is not implemented.  Instead, make the
-variable an integer, and use a @code{globalvaluedef} for each of the
-enumeration values.  An example of this would be:
-
-@example
-#ifdef __GNUC__
-GLOBALDEF (int, color, 0);
-GLOBALVALUEDEF (int, RED, 0);
-GLOBALVALUEDEF (int, BLUE, 1);
-GLOBALVALUEDEF (int, GREEN, 3);
-#else
-enum globaldef color @{RED, BLUE, GREEN = 3@};
-#endif
-@end example
-
-@node VMS Misc
-@section Other VMS Issues
-
-@cindex exit status and VMS
-@cindex return value of @code{main}
-@cindex @code{main} and the exit status
-GCC automatically arranges for @code{main} to return 1 by default if
-you fail to specify an explicit return value.  This will be interpreted
-by VMS as a status code indicating a normal successful completion.
-Version 1 of GCC did not provide this default.
-
-GCC on VMS works only with the GNU assembler, GAS@.  You need version
-1.37 or later of GAS in order to produce value debugging information for
-the VMS debugger.  Use the ordinary VMS linker with the object files
-produced by GAS@.
-
-@cindex shared VMS run time system
-@cindex @file{VAXCRTL}
-Under previous versions of GCC, the generated code would occasionally
-give strange results when linked to the sharable @file{VAXCRTL} library.
-Now this should work.
-
-A caveat for use of @code{const} global variables: the @code{const}
-modifier must be specified in every external declaration of the variable
-in all of the source files that use that variable.  Otherwise the linker
-will issue warnings about conflicting attributes for the variable.  Your
-program will still work despite the warnings, but the variable will be
-placed in writable storage.
-
-@cindex name augmentation
-@cindex case sensitivity and VMS
-@cindex VMS and case sensitivity
-Although the VMS linker does distinguish between upper and lower case
-letters in global symbols, most VMS compilers convert all such symbols
-into upper case and most run-time library routines also have upper case
-names.  To be able to reliably call such routines, GCC (by means of
-the assembler GAS) converts global symbols into upper case like other
-VMS compilers.  However, since the usual practice in C is to distinguish
-case, GCC (via GAS) tries to preserve usual C behavior by augmenting
-each name that is not all lower case.  This means truncating the name
-to at most 23 characters and then adding more characters at the end
-which encode the case pattern of those 23.   Names which contain at
-least one dollar sign are an exception; they are converted directly into
-upper case without augmentation.
-
-Name augmentation yields bad results for programs that use precompiled
-libraries (such as Xlib) which were generated by another compiler.  You
-can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
-it makes external C functions and variables case-independent as is usual
-on VMS@.  Alternatively, you could write all references to the functions
-and variables in such libraries using lower case; this will work on VMS,
-but is not portable to other systems.  The compiler option @samp{/NAMES}
-also provides control over global name handling.
-
-Function and variable names are handled somewhat differently with G++.
-The GNU C++ compiler performs @dfn{name mangling} on function
-names, which means that it adds information to the function name to
-describe the data types of the arguments that the function takes.  One
-result of this is that the name of a function can become very long.
-Since the VMS linker only recognizes the first 31 characters in a name,
-special action is taken to ensure that each function and variable has a
-unique name that can be represented in 31 characters.
-
-If the name (plus a name augmentation, if required) is less than 32
-characters in length, then no special action is performed.  If the name
-is longer than 31 characters, the assembler (GAS) will generate a
-hash string based upon the function name, truncate the function name to
-23 characters, and append the hash string to the truncated name.  If the
-@samp{/VERBOSE} compiler option is used, the assembler will print both
-the full and truncated names of each symbol that is truncated.
-
-The @samp{/NOCASE_HACK} compiler option should not be used when you are
-compiling programs that use libg++.  libg++ has several instances of
-objects (i.e.  @code{Filebuf} and @code{filebuf}) which become
-indistinguishable in a case-insensitive environment.  This leads to
-cases where you need to inhibit augmentation selectively (if you were
-using libg++ and Xlib in the same program, for example).  There is no
-special feature for doing this, but you can get the result by defining a
-macro for each mixed case symbol for which you wish to inhibit
-augmentation.  The macro should expand into the lower case equivalent of
-itself.  For example:
-
-@example
-#define StuDlyCapS studlycaps
-@end example
+@include contribute.texi
 
-These macro definitions can be placed in a header file to minimize the
-number of changes to your source code.
+@include vms.texi
 
 @node Makefile
 @chapter Additional Makefile and configure information.
diff --git a/gcc/doc/service.texi b/gcc/doc/service.texi
new file mode 100644
index 0000000..8637744
--- /dev/null
+++ b/gcc/doc/service.texi
@@ -0,0 +1,30 @@
+@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 Service
+@chapter How To Get Help with GCC
+
+If you need help installing, using or changing GCC, there are two
+ways to find it:
+
+@itemize @bullet
+@item
+Send a message to a suitable network mailing list.  First try
+@email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
+that brings no response, try @email{gcc@@gcc.gnu.org}.  For help
+changing GCC, ask @email{gcc@@gcc.gnu.org}.  If you think you have found
+a bug in GCC, please report it following the instructions at
+@pxref{Bug Reporting}.
+
+@item
+Look in the service directory for someone who might help you for a fee.
+The service directory is found at
+@uref{http://www.gnu.org/prep/service.html}.
+@end itemize
+
+@c For further information, see
+@c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}.
+@c FIXME: this URL may be too volatile, this FAQ entry needs to move to
+@c the regular web pages before we can uncomment the reference.
diff --git a/gcc/doc/standards.texi b/gcc/doc/standards.texi
new file mode 100644
index 0000000..8dae44f
--- /dev/null
+++ b/gcc/doc/standards.texi
@@ -0,0 +1,174 @@
+@c Copyright (C) 2000, 2001 Free Software Foundation, Inc.
+@c This is part of the GCC manual.
+@c For copying conditions, see the file gcc.texi.
+
+@node Standards
+@chapter Language Standards Supported by GCC
+@cindex C standard
+@cindex C standards
+@cindex ANSI C standard
+@cindex ANSI C
+@cindex ANSI C89
+@cindex C89
+@cindex ANSI X3.159-1989
+@cindex X3.159-1989
+@cindex ISO C standard
+@cindex ISO C
+@cindex ISO C89
+@cindex ISO C90
+@cindex ISO/IEC 9899
+@cindex ISO 9899
+@cindex C90
+@cindex ISO C94
+@cindex C94
+@cindex ISO C95
+@cindex C95
+@cindex ISO C99
+@cindex C99
+@cindex ISO C9X
+@cindex C9X
+@cindex Technical Corrigenda
+@cindex TC1
+@cindex Technical Corrigendum 1
+@cindex TC2
+@cindex Technical Corrigendum 2
+@cindex AMD1
+@cindex freestanding implementation
+@cindex freestanding environment
+@cindex hosted implementation
+@cindex hosted environment
+@findex __STDC_HOSTED__
+
+For each language compiled by GCC for which there is a standard, GCC
+attempts to follow one or more versions of that standard, possibly
+with some exceptions, and possibly with some extensions.
+
+GCC supports three versions of the C standard, although support for
+the most recent version is not yet complete.
+
+@opindex std
+@opindex ansi
+@opindex pedantic
+@opindex pedantic-errors
+The original ANSI C standard (X3.159-1989) was ratified in 1989 and
+published in 1990.  This standard was ratified as an ISO standard
+(ISO/IEC 9899:1990) later in 1990.  There were no technical
+differences between these publications, although the sections of the
+ANSI standard were renumbered and became clauses in the ISO standard.
+This standard, in both its forms, is commonly known as @dfn{C89}, or
+occasionally as @dfn{C90}, from the dates of ratification.  The ANSI
+standard, but not the ISO standard, also came with a Rationale
+document.  To select this standard in GCC, use one of the options
+@option{-ansi}, @option{-std=c89} or @option{-std=iso9899:1990}; to obtain
+all the diagnostics required by the standard, you should also specify
+@option{-pedantic} (or @option{-pedantic-errors} if you want them to be
+errors rather than warnings).  @xref{C Dialect Options,,Options
+Controlling C Dialect}.
+
+Errors in the 1990 ISO C standard were corrected in two Technical
+Corrigenda published in 1994 and 1996.  GCC does not support the
+uncorrected version.
+
+An amendment to the 1990 standard was published in 1995.  This
+amendment added digraphs and @code{__STDC_VERSION__} to the language,
+but otherwise concerned the library.  This amendment is commonly known
+as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
+@dfn{C95}.  To select this standard in GCC, use the option
+@option{-std=iso9899:199409} (with, as for other standard versions,
+@option{-pedantic} to receive all required diagnostics).
+
+A new edition of the ISO C standard was published in 1999 as ISO/IEC
+9899:1999, and is commonly known as @dfn{C99}.  GCC has incomplete
+support for this standard version; see
+@uref{http://gcc.gnu.org/c99status.html} for details.  To select this
+standard, use @option{-std=c99} or @option{-std=iso9899:1999}.  (While in
+development, drafts of this standard version were referred to as
+@dfn{C9X}.)
+
+@opindex traditional
+GCC also has some limited support for traditional (pre-ISO) C with the
+@option{-traditional} option.  This support may be of use for compiling
+some very old programs that have not been updated to ISO C, but should
+not be used for new programs.  It will not work with some modern C
+libraries such as the GNU C library.
+
+By default, GCC provides some extensions to the C language that on
+rare occasions conflict with the C standard.  @xref{C
+Extensions,,Extensions to the C Language Family}.  Use of the
+@option{-std} options listed above will disable these extensions where
+they conflict with the C standard version selected.  You may also
+select an extended version of the C language explicitly with
+@option{-std=gnu89} (for C89 with GNU extensions) or @option{-std=gnu99}
+(for C99 with GNU extensions).  The default, if no C language dialect
+options are given, is @option{-std=gnu89}; this will change to
+@option{-std=gnu99} in some future release when the C99 support is
+complete.  Some features that are part of the C99 standard are
+accepted as extensions in C89 mode.
+
+The ISO C standard defines (in clause 4) two classes of conforming
+implementation.  A @dfn{conforming hosted implementation} supports the
+whole standard including all the library facilities; a @dfn{conforming
+freestanding implementation} is only required to provide certain
+library facilities: those in @code{<float.h>}, @code{<limits.h>},
+@code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
+@code{<iso646.h>}; and in C99, also those in @code{<stdbool.h>} and
+@code{<stdint.h>}.  In addition, complex types, added in C99, are not
+required for freestanding implementations.  The standard also defines
+two environments for programs, a @dfn{freestanding environment},
+required of all implementations and which may not have library
+facilities beyond those required of freestanding implementations,
+where the handling of program startup and termination are
+implementation-defined, and a @dfn{hosted environment}, which is not
+required, in which all the library facilities are provided and startup
+is through a function @code{int main (void)} or @code{int main (int,
+char *[])}.  An OS kernel would be a freestanding environment; a
+program using the facilities of an operating system would normally be
+in a hosted implementation.
+
+@opindex ffreestanding
+GCC aims towards being usable as a conforming freestanding
+implementation, or as the compiler for a conforming hosted
+implementation.  By default, it will act as the compiler for a hosted
+implementation, defining @code{__STDC_HOSTED__} as @code{1} and
+presuming that when the names of ISO C functions are used, they have
+the semantics defined in the standard.  To make it act as a conforming
+freestanding implementation for a freestanding environment, use the
+option @option{-ffreestanding}; it will then define
+@code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
+meanings of function names from the standard library.  To build an OS
+kernel, you may well still need to make your own arrangements for
+linking and startup.  @xref{C Dialect Options,,Options Controlling C
+Dialect}.
+
+GCC does not provide the library facilities required only of hosted
+implementations, nor yet all the facilities required by C99 of
+freestanding implementations; to use the facilities of a hosted
+environment, you will need to find them elsewhere (for example, in the
+GNU C library).  @xref{Standard Libraries,,Standard Libraries}.
+
+For references to Technical Corrigenda, Rationale documents and
+information concerning the history of C that is available online, see
+@uref{http://gcc.gnu.org/readings.html}
+
+@c FIXME: details of C++ standard.
+
+There is no formal written standard for Objective-C@.  The most
+authoritative manual is ``Object-Oriented Programming and the
+Objective-C Language'', available at a number of web sites;
+@uref{http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/} has a
+recent version, while @uref{http://www.toodarkpark.org/computers/objc/}
+is an older example.  @uref{http://www.gnustep.org} includes useful
+information as well.
+
+@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, 
+GNAT Reference Manual}, for information on standard
+conformance and compatibility of the Ada compiler.
+
+@xref{References,,Language Definition References, chill, GNU Chill},
+for details of the CHILL standard.
+
+@xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
+Fortran}, for details of the Fortran language supported by GCC@.
+
+@xref{Compatibility,,Compatibility with the Java Platform, gcj, GNU gcj},
+for details of compatibility between @code{gcj} and the Java Platform.
diff --git a/gcc/doc/trouble.texi b/gcc/doc/trouble.texi
new file mode 100644
index 0000000..ff67f8f
--- /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.
diff --git a/gcc/doc/vms.texi b/gcc/doc/vms.texi
new file mode 100644
index 0000000..5ab2666
--- /dev/null
+++ b/gcc/doc/vms.texi
@@ -0,0 +1,331 @@
+@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 VMS
+@chapter Using GCC on VMS
+
+@c prevent bad page break with this line
+Here is how to use GCC on VMS@.
+
+@menu
+* Include Files and VMS::  Where the preprocessor looks for the include files.
+* Global Declarations::    How to do globaldef, globalref and globalvalue with
+                           GCC.
+* VMS Misc::		   Misc information.
+@end menu
+
+@node Include Files and VMS
+@section Include Files and VMS
+
+@cindex include files and VMS
+@cindex VMS and include files
+@cindex header files and VMS
+Due to the differences between the filesystems of Unix and VMS, GCC
+attempts to translate file names in @samp{#include} into names that VMS
+will understand.  The basic strategy is to prepend a prefix to the
+specification of the include file, convert the whole filename to a VMS
+filename, and then try to open the file.  GCC tries various prefixes
+one by one until one of them succeeds:
+
+@enumerate
+@item
+The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
+where GNU C header files are traditionally stored.  If you wish to store
+header files in non-standard locations, then you can assign the logical
+@samp{GNU_CC_INCLUDE} to be a search list, where each element of the
+list is suitable for use with a rooted logical.
+
+@item
+The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}.  This is where
+VAX-C header files are traditionally stored.
+
+@item
+If the include file specification by itself is a valid VMS filename, the
+preprocessor then uses this name with no prefix in an attempt to open
+the include file.
+
+@item
+If the file specification is not a valid VMS filename (i.e.@: does not
+contain a device or a directory specifier, and contains a @samp{/}
+character), the preprocessor tries to convert it from Unix syntax to
+VMS syntax.
+
+Conversion works like this: the first directory name becomes a device,
+and the rest of the directories are converted into VMS-format directory
+names.  For example, the name @file{X11/foobar.h} is
+translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
+whichever one can be opened.  This strategy allows you to assign a
+logical name to point to the actual location of the header files.
+
+@item
+If none of these strategies succeeds, the @samp{#include} fails.
+@end enumerate
+
+Include directives of the form:
+
+@example
+#include foobar
+@end example
+
+@noindent
+are a common source of incompatibility between VAX-C and GCC@.  VAX-C
+treats this much like a standard @code{#include <foobar.h>} directive.
+That is incompatible with the ISO C behavior implemented by GCC: to
+expand the name @code{foobar} as a macro.  Macro expansion should
+eventually yield one of the two standard formats for @code{#include}:
+
+@example
+#include "@var{file}"
+#include <@var{file}>
+@end example
+
+If you have this problem, the best solution is to modify the source to
+convert the @code{#include} directives to one of the two standard forms.
+That will work with either compiler.  If you want a quick and dirty fix,
+define the file names as macros with the proper expansion, like this:
+
+@example
+#define stdio <stdio.h>
+@end example
+
+@noindent
+This will work, as long as the name doesn't conflict with anything else
+in the program.
+
+Another source of incompatibility is that VAX-C assumes that:
+
+@example
+#include "foobar"
+@end example
+
+@noindent
+is actually asking for the file @file{foobar.h}.  GCC does not
+make this assumption, and instead takes what you ask for literally;
+it tries to read the file @file{foobar}.  The best way to avoid this
+problem is to always specify the desired file extension in your include
+directives.
+
+GCC for VMS is distributed with a set of include files that is
+sufficient to compile most general purpose programs.  Even though the
+GCC distribution does not contain header files to define constants
+and structures for some VMS system-specific functions, there is no
+reason why you cannot use GCC with any of these functions.  You first
+may have to generate or create header files, either by using the public
+domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
+extracting the relevant modules from one of the system macro libraries,
+and using an editor to construct a C header file.
+
+A @code{#include} file name cannot contain a DECNET node name.  The
+preprocessor reports an I/O error if you attempt to use a node name,
+whether explicitly, or implicitly via a logical name.
+
+@node Global Declarations
+@section Global Declarations and VMS
+
+@findex GLOBALREF
+@findex GLOBALDEF
+@findex GLOBALVALUEDEF
+@findex GLOBALVALUEREF
+GCC does not provide the @code{globalref}, @code{globaldef} and
+@code{globalvalue} keywords of VAX-C@.  You can get the same effect with
+an obscure feature of GAS, the GNU assembler.  (This requires GAS
+version 1.39 or later.)  The following macros allow you to use this
+feature in a fairly natural way:
+
+@smallexample
+#ifdef __GNUC__
+#define GLOBALREF(TYPE,NAME)                      \
+  TYPE NAME                                       \
+  asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
+#define GLOBALDEF(TYPE,NAME,VALUE)                \
+  TYPE NAME                                       \
+  asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
+    = VALUE
+#define GLOBALVALUEREF(TYPE,NAME)                 \
+  const TYPE NAME[1]                              \
+  asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
+#define GLOBALVALUEDEF(TYPE,NAME,VALUE)           \
+  const TYPE NAME[1]                              \
+  asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)  \
+    = @{VALUE@}
+#else
+#define GLOBALREF(TYPE,NAME) \
+  globalref TYPE NAME
+#define GLOBALDEF(TYPE,NAME,VALUE) \
+  globaldef TYPE NAME = VALUE
+#define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
+  globalvalue TYPE NAME = VALUE
+#define GLOBALVALUEREF(TYPE,NAME) \
+  globalvalue TYPE NAME
+#endif
+@end smallexample
+
+@noindent
+(The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
+name is removed by the assembler, after it has modified the attributes
+of the symbol).  These macros are provided in the VMS binaries
+distribution in a header file @file{GNU_HACKS.H}.  An example of the
+usage is:
+
+@example
+GLOBALREF (int, ijk);
+GLOBALDEF (int, jkl, 0);
+@end example
+
+The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
+straightforwardly for arrays, since there is no way to insert the array
+dimension into the declaration at the right place.  However, you can
+declare an array with these macros if you first define a typedef for the
+array type, like this:
+
+@example
+typedef int intvector[10];
+GLOBALREF (intvector, foo);
+@end example
+
+Array and structure initializers will also break the macros; you can
+define the initializer to be a macro of its own, or you can expand the
+@code{GLOBALDEF} macro by hand.  You may find a case where you wish to
+use the @code{GLOBALDEF} macro with a large array, but you are not
+interested in explicitly initializing each element of the array.  In
+such cases you can use an initializer like: @code{@{0,@}}, which will
+initialize the entire array to @code{0}.
+
+A shortcoming of this implementation is that a variable declared with
+@code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array.  For
+example, the declaration:
+
+@example
+GLOBALVALUEREF(int, ijk);
+@end example
+
+@noindent
+declares the variable @code{ijk} as an array of type @code{int [1]}.
+This is done because a globalvalue is actually a constant; its ``value''
+is what the linker would normally consider an address.  That is not how
+an integer value works in C, but it is how an array works.  So treating
+the symbol as an array name gives consistent results---with the
+exception that the value seems to have the wrong type.  @strong{Don't
+try to access an element of the array.}  It doesn't have any elements.
+The array ``address'' may not be the address of actual storage.
+
+The fact that the symbol is an array may lead to warnings where the
+variable is used.  Insert type casts to avoid the warnings.  Here is an
+example; it takes advantage of the ISO C feature allowing macros that
+expand to use the same name as the macro itself.
+
+@example
+GLOBALVALUEREF (int, ss$_normal);
+GLOBALVALUEDEF (int, xyzzy,123);
+#ifdef __GNUC__
+#define ss$_normal ((int) ss$_normal)
+#define xyzzy ((int) xyzzy)
+#endif
+@end example
+
+Don't use @code{globaldef} or @code{globalref} with a variable whose
+type is an enumeration type; this is not implemented.  Instead, make the
+variable an integer, and use a @code{globalvaluedef} for each of the
+enumeration values.  An example of this would be:
+
+@example
+#ifdef __GNUC__
+GLOBALDEF (int, color, 0);
+GLOBALVALUEDEF (int, RED, 0);
+GLOBALVALUEDEF (int, BLUE, 1);
+GLOBALVALUEDEF (int, GREEN, 3);
+#else
+enum globaldef color @{RED, BLUE, GREEN = 3@};
+#endif
+@end example
+
+@node VMS Misc
+@section Other VMS Issues
+
+@cindex exit status and VMS
+@cindex return value of @code{main}
+@cindex @code{main} and the exit status
+GCC automatically arranges for @code{main} to return 1 by default if
+you fail to specify an explicit return value.  This will be interpreted
+by VMS as a status code indicating a normal successful completion.
+Version 1 of GCC did not provide this default.
+
+GCC on VMS works only with the GNU assembler, GAS@.  You need version
+1.37 or later of GAS in order to produce value debugging information for
+the VMS debugger.  Use the ordinary VMS linker with the object files
+produced by GAS@.
+
+@cindex shared VMS run time system
+@cindex @file{VAXCRTL}
+Under previous versions of GCC, the generated code would occasionally
+give strange results when linked to the sharable @file{VAXCRTL} library.
+Now this should work.
+
+A caveat for use of @code{const} global variables: the @code{const}
+modifier must be specified in every external declaration of the variable
+in all of the source files that use that variable.  Otherwise the linker
+will issue warnings about conflicting attributes for the variable.  Your
+program will still work despite the warnings, but the variable will be
+placed in writable storage.
+
+@cindex name augmentation
+@cindex case sensitivity and VMS
+@cindex VMS and case sensitivity
+Although the VMS linker does distinguish between upper and lower case
+letters in global symbols, most VMS compilers convert all such symbols
+into upper case and most run-time library routines also have upper case
+names.  To be able to reliably call such routines, GCC (by means of
+the assembler GAS) converts global symbols into upper case like other
+VMS compilers.  However, since the usual practice in C is to distinguish
+case, GCC (via GAS) tries to preserve usual C behavior by augmenting
+each name that is not all lower case.  This means truncating the name
+to at most 23 characters and then adding more characters at the end
+which encode the case pattern of those 23.   Names which contain at
+least one dollar sign are an exception; they are converted directly into
+upper case without augmentation.
+
+Name augmentation yields bad results for programs that use precompiled
+libraries (such as Xlib) which were generated by another compiler.  You
+can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
+it makes external C functions and variables case-independent as is usual
+on VMS@.  Alternatively, you could write all references to the functions
+and variables in such libraries using lower case; this will work on VMS,
+but is not portable to other systems.  The compiler option @samp{/NAMES}
+also provides control over global name handling.
+
+Function and variable names are handled somewhat differently with G++.
+The GNU C++ compiler performs @dfn{name mangling} on function
+names, which means that it adds information to the function name to
+describe the data types of the arguments that the function takes.  One
+result of this is that the name of a function can become very long.
+Since the VMS linker only recognizes the first 31 characters in a name,
+special action is taken to ensure that each function and variable has a
+unique name that can be represented in 31 characters.
+
+If the name (plus a name augmentation, if required) is less than 32
+characters in length, then no special action is performed.  If the name
+is longer than 31 characters, the assembler (GAS) will generate a
+hash string based upon the function name, truncate the function name to
+23 characters, and append the hash string to the truncated name.  If the
+@samp{/VERBOSE} compiler option is used, the assembler will print both
+the full and truncated names of each symbol that is truncated.
+
+The @samp{/NOCASE_HACK} compiler option should not be used when you are
+compiling programs that use libg++.  libg++ has several instances of
+objects (i.e.  @code{Filebuf} and @code{filebuf}) which become
+indistinguishable in a case-insensitive environment.  This leads to
+cases where you need to inhibit augmentation selectively (if you were
+using libg++ and Xlib in the same program, for example).  There is no
+special feature for doing this, but you can get the result by defining a
+macro for each mixed case symbol for which you wish to inhibit
+augmentation.  The macro should expand into the lower case equivalent of
+itself.  For example:
+
+@example
+#define StuDlyCapS studlycaps
+@end example
+
+These macro definitions can be placed in a header file to minimize the
+number of changes to your source code.