summaryrefslogtreecommitdiffstats
path: root/contrib/gcc/gcc.texi
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/gcc/gcc.texi')
-rw-r--r--contrib/gcc/gcc.texi4722
1 files changed, 4722 insertions, 0 deletions
diff --git a/contrib/gcc/gcc.texi b/contrib/gcc/gcc.texi
new file mode 100644
index 0000000..7c6b056
--- /dev/null
+++ b/contrib/gcc/gcc.texi
@@ -0,0 +1,4722 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename gcc.info
+@c @setfilename usegcc.info
+@c @setfilename portgcc.info
+@c To produce the full manual, use the "gcc.info" setfilename, and
+@c make sure the following do NOT begin with '@c' (and the @clear lines DO)
+@set INTERNALS
+@set USING
+@c To produce a user-only manual, use the "usegcc.info" setfilename, and
+@c make sure the following does NOT begin with '@c':
+@c @clear INTERNALS
+@c To produce a porter-only manual, use the "portgcc.info" setfilename,
+@c and make sure the following does NOT begin with '@c':
+@c @clear USING
+
+@c i have commented out the smallbook command below, and reformatted
+@c this manual in the regular book size for distribution. in addition,
+@c i commented out the commands that shift the text to one or the other
+@c side of the page for smallbook printing (which makes it easier for
+@c the photocopying people to handle...). -mew, 15june93
+
+@c (For FSF printing, turn on smallbook, comment out finalout below;
+@c that is all that is needed.)
+
+@c smallbook
+
+@c i also commented out the finalout command, so if there *are* any
+@c overfulls, you'll (hopefully) see the rectangle in the right hand
+@c margin. -mew 15june93
+@c finalout
+
+@c NOTE: checks/things to do:
+@c
+@c -have bob do a search in all seven files for "mew" (ideally --mew,
+@c but i may have forgotten the occasional "--"..).
+@c -item/itemx, text after all (sub/sub)section titles, etc..
+@c -consider putting the lists of options on pp 17--> etc in columns or
+@c some such.
+@c -spellcheck
+@c -continuity of phrasing; ie, bit-field vs bitfield in rtl.texi
+@c -overfulls. do a search for "mew" in the files, and you will see
+@c overfulls that i noted but could not deal with.
+@c -have to add text: beginning of chapter 8
+
+@c
+@c anything else? --mew 10feb93
+
+
+
+@ifset INTERNALS
+@ifset USING
+@settitle Using and Porting GNU CC
+@end ifset
+@end ifset
+@c seems reasonable to assume at least one of INTERNALS or USING is set...
+@ifclear INTERNALS
+@settitle Using GNU CC
+@end ifclear
+@ifclear USING
+@settitle Porting GNU CC
+@end ifclear
+
+@syncodeindex fn cp
+@syncodeindex vr cp
+@c %**end of header
+
+@c Use with @@smallbook.
+
+@c Cause even numbered pages to be printed on the left hand side of
+@c the page and odd numbered pages to be printed on the right hand
+@c side of the page. Using this, you can print on both sides of a
+@c sheet of paper and have the text on the same part of the sheet.
+
+@c The text on right hand pages is pushed towards the right hand
+@c margin and the text on left hand pages is pushed toward the left
+@c hand margin.
+@c (To provide the reverse effect, set bindingoffset to -0.75in.)
+
+@c @tex
+@c \global\bindingoffset=0.75in
+@c \global\normaloffset =0.75in
+@c @end tex
+
+@ifinfo
+@ifset INTERNALS
+@ifset USING
+This file documents the use and the internals of the GNU compiler.
+@end ifset
+@end ifset
+@ifclear USING
+This file documents the internals of the GNU compiler.
+@end ifclear
+@ifclear INTERNALS
+This file documents the use of the GNU compiler.
+@end ifclear
+
+Published by the Free Software Foundation
+59 Temple Place - Suite 330
+Boston, MA 02111-1307 USA
+
+Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+sections entitled ``GNU General Public License,'' ``Funding for Free
+Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are
+included exactly as in the original, and provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the sections entitled ``GNU General Public License,''
+``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look
+And Feel'@w{}'', and this permission notice, may be included in
+translations approved by the Free Software Foundation instead of in the
+original English.
+@end ifinfo
+
+@setchapternewpage odd
+
+@titlepage
+@ifset INTERNALS
+@ifset USING
+@center @titlefont{Using and Porting GNU CC}
+
+@end ifset
+@end ifset
+@ifclear INTERNALS
+@title Using GNU CC
+@end ifclear
+@ifclear USING
+@title Porting GNU CC
+@end ifclear
+@sp 2
+@center Richard M. Stallman
+@sp 3
+@center Last updated 26 November 1995
+@sp 1
+@c The version number appears twice more in this file.
+
+@center for version 2.7.2
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1988, 89, 92, 93, 94, 1995 Free Software Foundation, Inc.
+@sp 2
+For GCC Version 2.7.2@*
+@sp 1
+Published by the Free Software Foundation @*
+59 Temple Place - Suite 330@*
+Boston, MA 02111-1307, USA@*
+Last printed November, 1995.@*
+Printed copies are available for $50 each.@*
+ISBN 1-882114-66-3
+@sp 1
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+sections entitled ``GNU General Public License,'' ``Funding for Free
+Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are
+included exactly as in the original, and provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the sections entitled ``GNU General Public License,''
+``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look
+And Feel'@w{}'', and this permission notice, may be included in
+translations approved by the Free Software Foundation instead of in the
+original English.
+@end titlepage
+@page
+
+@ifinfo
+
+@node Top, Copying,, (DIR)
+@top Introduction
+@cindex introduction
+
+@ifset INTERNALS
+@ifset USING
+This manual documents how to run, install and port the GNU
+compiler, as well as its new features and incompatibilities, and how to
+report bugs. It corresponds to GNU CC version 2.7.2.
+@end ifset
+@end ifset
+
+@ifclear INTERNALS
+This manual documents how to run and install the GNU compiler,
+as well as its new features and incompatibilities, and how to report
+bugs. It corresponds to GNU CC version 2.7.2.
+@end ifclear
+@ifclear USING
+This manual documents how to port the GNU compiler,
+as well as its new features and incompatibilities, and how to report
+bugs. It corresponds to GNU CC version 2.7.1.
+@end ifclear
+
+@end ifinfo
+@menu
+* Copying:: GNU General Public License says
+ how you can copy and share GNU CC.
+* Contributors:: People who have contributed to GNU CC.
+* Funding:: How to help assure funding for free software.
+* Look and Feel:: Protect your freedom---fight ``look and feel''.
+@ifset USING
+* G++ and GCC:: You can compile C or C++ programs.
+* Invoking GCC:: Command options supported by @samp{gcc}.
+* Installation:: How to configure, compile and install GNU CC.
+* C Extensions:: GNU extensions to the C language family.
+* C++ Extensions:: GNU extensions to the C++ language.
+* Trouble:: If you have trouble installing GNU CC.
+* Bugs:: How, why and where to report bugs.
+* Service:: How to find suppliers of support for GNU CC.
+* VMS:: Using GNU CC on VMS.
+@end ifset
+@ifset INTERNALS
+* Portability:: Goals of GNU CC's portability features.
+* Interface:: Function-call interface of GNU CC output.
+* Passes:: Order of passes, what they do, and what each file is for.
+* RTL:: The intermediate representation that most passes work on.
+* Machine Desc:: How to write machine description instruction patterns.
+* Target Macros:: How to write the machine description C macros.
+* Config:: Writing the @file{xm-@var{machine}.h} file.
+* Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
+@end ifset
+
+* Index:: Index of concepts and symbol names.
+@end menu
+
+@node Copying
+@unnumbered GNU GENERAL PUBLIC LICENSE
+@center Version 2, June 1991
+
+@display
+Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
+59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@unnumberedsec Preamble
+
+ The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software---to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.) You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.
+
+ We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+ Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+@iftex
+@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end ifinfo
+
+@enumerate 0
+@item
+This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License. The ``Program'', below,
+refers to any such program or work, and a ``work based on the Program''
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language. (Hereinafter, translation is included without limitation in
+the term ``modification''.) Each licensee is addressed as ``you''.
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+@item
+You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+@item
+You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+@enumerate a
+@item
+You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.
+
+@item
+You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.
+
+@item
+If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License. (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)
+@end enumerate
+
+These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+@item
+You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+@enumerate a
+@item
+Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,
+
+@item
+Accompany it with a written offer, valid for at least three
+years, to give any third party, for a charge no more than your
+cost of physically performing source distribution, a complete
+machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+@item
+Accompany it with the information you received as to the offer
+to distribute corresponding source code. (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)
+@end enumerate
+
+The source code for a work means the preferred form of the work for
+making modifications to it. For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable. However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+@item
+You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Program or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+@item
+Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+@item
+If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all. For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+@item
+If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+@item
+The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies a version number of this License which applies to it and ``any
+later version'', you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation. If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+@item
+If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission. For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+@iftex
+@heading NO WARRANTY
+@end iftex
+@ifinfo
+@center NO WARRANTY
+@end ifinfo
+
+@item
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+@item
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+@end enumerate
+
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+
+@page
+@unnumberedsec How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the ``copyright'' line and a pointer to where the full notice is found.
+
+@smallexample
+@var{one line to give the program's name and a brief idea of what it does.}
+Copyright (C) 19@var{yy} @var{name of author}
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+@end smallexample
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+@smallexample
+Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
+Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+type `show w'.
+This is free software, and you are welcome to redistribute it
+under certain conditions; type `show c' for details.
+@end smallexample
+
+The hypothetical commands @samp{show w} and @samp{show c} should show
+the appropriate parts of the General Public License. Of course, the
+commands you use may be called something other than @samp{show w} and
+@samp{show c}; they could even be mouse-clicks or menu items---whatever
+suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a ``copyright disclaimer'' for the program, if
+necessary. Here is a sample; alter the names:
+
+@smallexample
+Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+`Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+@end smallexample
+
+This General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library. If this is what you want to do, use the GNU Library General
+Public License instead of this License.
+
+@node Contributors
+@unnumbered Contributors to GNU CC
+@cindex contributors
+
+In addition to Richard Stallman, several people have written parts
+of GNU CC.
+
+@itemize @bullet
+@item
+The idea of using RTL and some of the optimization ideas came from the
+program PO written at the University of Arizona by Jack Davidson and
+Christopher Fraser. See ``Register Allocation and Exhaustive Peephole
+Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
+857-866.
+
+@item
+Paul Rubin wrote most of the preprocessor.
+
+@item
+Leonard Tower wrote parts of the parser, RTL generator, and RTL
+definitions, and of the Vax machine description.
+
+@item
+Ted Lemon wrote parts of the RTL reader and printer.
+
+@item
+Jim Wilson implemented loop strength reduction and some other
+loop optimizations.
+
+@item
+Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
+the support for the Sony NEWS machine.
+
+@item
+Charles LaBrec contributed the support for the Integrated Solutions
+68020 system.
+
+@item
+Michael Tiemann of Cygnus Support wrote the front end for C++, as well
+as the support for inline functions and instruction scheduling. Also
+the descriptions of the National Semiconductor 32000 series cpu, the
+SPARC cpu and part of the Motorola 88000 cpu.
+
+@item
+Gerald Baumgartner added the signature extension to the C++ front-end.
+
+@item
+Jan Stein of the Chalmers Computer Society provided support for
+Genix, as well as part of the 32000 machine description.
+
+@item
+Randy Smith finished the Sun FPA support.
+
+@item
+Robert Brown implemented the support for Encore 32000 systems.
+
+@item
+David Kashtan of SRI adapted GNU CC to VMS.
+
+@item
+Alex Crain provided changes for the 3b1.
+
+@item
+Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for
+the 9000 series 300.
+
+@item
+William Schelter did most of the work on the Intel 80386 support.
+
+@item
+Christopher Smith did the port for Convex machines.
+
+@item
+Paul Petersen wrote the machine description for the Alliant FX/8.
+
+@item
+Dario Dariol contributed the four varieties of sample programs
+that print a copy of their source.
+
+@item
+Alain Lichnewsky ported GNU CC to the Mips cpu.
+
+@item
+Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the Tahoe.
+
+@item
+Jonathan Stone wrote the machine description for the Pyramid computer.
+
+@item
+Gary Miller ported GNU CC to Charles River Data Systems machines.
+
+@item
+Richard Kenner of the New York University Ultracomputer Research
+Laboratory wrote the machine descriptions for the AMD 29000, the DEC
+Alpha, the IBM RT PC, and the IBM RS/6000 as well as the support for
+instruction attributes. He also made changes to better support RISC
+processors including changes to common subexpression elimination,
+strength reduction, function calling sequence handling, and condition
+code support, in addition to generalizing the code for frame pointer
+elimination.
+
+@item
+Richard Kenner and Michael Tiemann jointly developed reorg.c, the delay
+slot scheduler.
+
+@item
+Mike Meissner and Tom Wood of Data General finished the port to the
+Motorola 88000.
+
+@item
+Masanobu Yuhara of Fujitsu Laboratories implemented the machine
+description for the Tron architecture (specifically, the Gmicro).
+
+@item
+NeXT, Inc.@: donated the front end that supports the Objective C
+language.
+@c We need to be careful to make it clear that "Objective C"
+@c is the name of a language, not that of a program or product.
+
+@item
+James van Artsdalen wrote the code that makes efficient use of
+the Intel 80387 register stack.
+
+@item
+Mike Meissner at the Open Software Foundation finished the port to the
+MIPS cpu, including adding ECOFF debug support, and worked on the
+Intel port for the Intel 80386 cpu.
+
+@item
+Ron Guilmette implemented the @code{protoize} and @code{unprotoize}
+tools, the support for Dwarf symbolic debugging information, and much of
+the support for System V Release 4. He has also worked heavily on the
+Intel 386 and 860 support.
+
+@item
+Torbjorn Granlund implemented multiply- and divide-by-constant
+optimization, improved long long support, and improved leaf function
+register allocation.
+
+@item
+Mike Stump implemented the support for Elxsi 64 bit CPU.
+
+@item
+John Wehle added the machine description for the Western Electric 32000
+processor used in several 3b series machines (no relation to the
+National Semiconductor 32000 processor).
+
+@ignore @c These features aren't advertised yet, since they don't fully work.
+@item
+Analog Devices helped implement the support for complex data types
+and iterators.
+@end ignore
+
+@item
+Holger Teutsch provided the support for the Clipper cpu.
+
+@item
+Kresten Krab Thorup wrote the run time support for the Objective C
+language.
+
+@item
+Stephen Moshier contributed the floating point emulator that assists in
+cross-compilation and permits support for floating point numbers wider
+than 64 bits.
+
+@item
+David Edelsohn contributed the changes to RS/6000 port to make it
+support the PowerPC and POWER2 architectures.
+
+@item
+Steve Chamberlain wrote the support for the Hitachi SH processor.
+
+@item
+Peter Schauer wrote the code to allow debugging to work on the Alpha.
+
+@item
+Oliver M. Kellogg of Deutsche Aerospace contributed the port to the
+MIL-STD-1750A.
+
+@item
+Michael K. Gschwind contributed the port to the PDP-11.
+@end itemize
+
+@node Funding
+@chapter Funding Free Software
+
+If you want to have more free software a few years from now, it makes
+sense for you to help encourage people to contribute funds for its
+development. The most effective approach known is to encourage
+commercial redistributors to donate.
+
+Users of free software systems can boost the pace of development by
+encouraging for-a-fee distributors to donate part of their selling price
+to free software developers---the Free Software Foundation, and others.
+
+The way to convince distributors to do this is to demand it and expect
+it from them. So when you compare distributors, judge them partly by
+how much they give to free software development. Show distributors
+they must compete to be the one who gives the most.
+
+To make this approach work, you must insist on numbers that you can
+compare, such as, ``We will donate ten dollars to the Frobnitz project
+for each disk sold.'' Don't be satisfied with a vague promise, such as
+``A portion of the profits are donated,'' since it doesn't give a basis
+for comparison.
+
+Even a precise fraction ``of the profits from this disk'' is not very
+meaningful, since creative accounting and unrelated business decisions
+can greatly alter what fraction of the sales price counts as profit.
+If the price you pay is $50, ten percent of the profit is probably
+less than a dollar; it might be a few cents, or nothing at all.
+
+Some redistributors do development work themselves. This is useful too;
+but to keep everyone honest, you need to inquire how much they do, and
+what kind. Some kinds of development make much more long-term
+difference than others. For example, maintaining a separate version of
+a program contributes very little; maintaining the standard version of a
+program for the whole community contributes much. Easy new ports
+contribute little, since someone else would surely do them; difficult
+ports such as adding a new CPU to the GNU C compiler contribute more;
+major new features or packages contribute the most.
+
+By establishing the idea that supporting further development is ``the
+proper thing to do'' when distributing free software for a fee, we can
+assure a steady flow of resources into making more free software.
+
+@display
+Copyright (C) 1994 Free Software Foundation, Inc.
+Verbatim copying and redistribution of this section is permitted
+without royalty; alteration is not permitted.
+@end display
+
+@node Look and Feel
+@chapter Protect Your Freedom---Fight ``Look And Feel''
+@c the above chapter heading overflows onto the next line. --mew 1/26/93
+
+@quotation
+@i{This section is a political message from the League for Programming
+Freedom to the users of GNU CC. We have included it here because the
+issue of interface copyright is important to the GNU project.}
+@end quotation
+
+Apple, Lotus, and now CDC have tried to create a new form of legal
+monopoly: a copyright on a user interface.
+
+An interface is a kind of language---a set of conventions for
+communication between two entities, human or machine. Until a few years
+ago, the law seemed clear: interfaces were outside the domain of
+copyright, so programmers could program freely and implement whatever
+interface the users demanded. Imitating de-facto standard interfaces,
+sometimes with improvements, was standard practice in the computer
+field. These improvements, if accepted by the users, caught on and
+became the norm; in this way, much progress took place.
+
+Computer users, and most software developers, were happy with this state
+of affairs. However, large companies such as Apple and Lotus would
+prefer a different system---one in which they can own interfaces and
+thereby rid themselves of all serious competitors. They hope that
+interface copyright will give them, in effect, monopolies on major
+classes of software.
+
+Other large companies such as IBM and Digital also favor interface
+monopolies, for the same reason: if languages become property, they
+expect to own many de-facto standard languages. But Apple and Lotus are
+the ones who have actually sued. Apple's lawsuit was defeated, for
+reasons only partly related to the general issue of interface copyright.
+
+Lotus won lawsuits against two small companies, which were thus put out
+of business. Then they sued Borland; they won in the trial court (no
+surprise, since it was the same court that had ruled for Lotus twice
+before), but the decision was reversed by the court of appeals, with
+help from the League for Programming Freedom in the form of a
+friend-of-the-court brief. We are now waiting to see if the Supreme
+Court will hear the case. If it does, the League for Programming
+Freedom will again submit a brief.
+
+The battle is not over. Just this summer a company that produced a
+simulator for a CDC computer was shut down by a copyright lawsuit by
+CDC, which charged that the simulator infringed the copyright on the
+manuals for the computer.
+
+If the monopolists get their way, they will hobble the software field:
+
+@itemize @bullet
+@item
+Gratuitous incompatibilities will burden users. Imagine if each car
+manufacturer had to design a different way to start, stop, and steer a
+car.
+
+@item
+Users will be ``locked in'' to whichever interface they learn; then they
+will be prisoners of one supplier, who will charge a monopolistic price.
+
+@item
+Large companies have an unfair advantage wherever lawsuits become
+commonplace. Since they can afford to sue, they can intimidate smaller
+developers with threats even when they don't really have a case.
+
+@item
+Interface improvements will come slower, since incremental evolution
+through creative partial imitation will no longer occur.
+@end itemize
+
+If interface monopolies are accepted, other large companies are waiting
+to grab theirs:
+
+@itemize @bullet
+@item
+Adobe is expected to claim a monopoly on the interfaces of various
+popular application programs, if Lotus ultimately wins the case against
+Borland.
+
+@item
+Open Computing magazine reported a Microsoft vice president as threatening
+to sue people who imitate the interface of Windows.
+@end itemize
+
+Users invest a great deal of time and money in learning to use computer
+interfaces. Far more, in fact, than software developers invest in
+developing @emph{and even implementing} the interfaces. Whoever can own
+an interface, has made its users into captives, and misappropriated
+their investment.
+
+To protect our freedom from monopolies like these, a group of
+programmers and users have formed a grass-roots political organization,
+the League for Programming Freedom.
+
+The purpose of the League is to oppose monopolistic practices such as
+interface copyright and software patents. The League calls for a return
+to the legal policies of the recent past, in which programmers could
+program freely. The League is not concerned with free software as an
+issue, and is not affiliated with the Free Software Foundation.
+
+The League's activities include publicizing the issues, as is being done
+here, and filing friend-of-the-court briefs on behalf of defendants sued
+by monopolists.
+
+The League's membership rolls include Donald Knuth, the foremost
+authority on algorithms, John McCarthy, inventor of Lisp, Marvin Minsky,
+founder of the MIT Artificial Intelligence lab, Guy L. Steele, Jr.,
+author of well-known books on Lisp and C, as well as Richard Stallman,
+the developer of GNU CC. Please join and add your name to the list.
+Membership dues in the League are $42 per year for programmers, managers
+and professionals; $10.50 for students; $21 for others.
+
+Activist members are especially important, but members who have no time
+to give are also important. Surveys at major ACM conferences have
+indicated a vast majority of attendees agree with the League on both
+issues (interface copyrights and software patents). If just ten percent
+of the programmers who agree with the League join the League, we will
+probably triumph.
+
+To join, or for more information, phone (617) 243-4091 or write to:
+
+@display
+League for Programming Freedom
+1 Kendall Square #143
+P.O. Box 9171
+Cambridge, MA 02139
+@end display
+
+You can also send electronic mail to @code{lpf@@uunet.uu.net}.
+
+In addition to joining the League, here are some suggestions from the
+League for other things you can do to protect your freedom to write
+programs:
+
+@itemize @bullet
+@item
+Tell your friends and colleagues about this issue and how it threatens
+to ruin the computer industry.
+
+@item
+Mention that you are a League member in your @file{.signature}, and
+mention the League's email address for inquiries.
+
+@item
+Ask the companies you consider working for or working with to make
+statements against software monopolies, and give preference to those
+that do.
+
+@item
+When employers ask you to sign contracts giving them copyright on your
+work, insist on a clause saying they will not claim the copyright covers
+imitating the interface.
+
+@item
+When employers ask you to sign contracts giving them patent rights,
+insist on clauses saying they can use these rights only defensively.
+Don't rely on ``company policy,'' since that can change at any time;
+don't rely on an individual executive's private word, since that person
+may be replaced. Get a commitment just as binding as the commitment
+they get from you.
+
+@item
+Write to Congress to explain the importance of these issues.
+
+@display
+House Subcommittee on Intellectual Property
+2137 Rayburn Bldg
+Washington, DC 20515
+
+Senate Subcommittee on Patents, Trademarks and Copyrights
+United States Senate
+Washington, DC 20510
+@end display
+
+(These committees have received lots of mail already; let's give them
+even more.)
+@end itemize
+
+Democracy means nothing if you don't use it. Stand up and be counted!
+@ifset USING
+@node G++ and GCC
+@chapter Compile C, C++, or Objective C
+
+@cindex Objective C
+The C, C++, and Objective C versions of the compiler are integrated; the
+GNU C compiler can compile programs written in C, C++, or Objective C.
+
+@cindex GCC
+``GCC'' is a common shorthand term for the GNU C compiler. This is both
+the most general name for the compiler, and the name used when the
+emphasis is on compiling C programs.
+
+@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.
+
+We use the name ``GNU CC'' 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 ``GNU CC'' or sometimes just ``the compiler''.
+
+Front ends for other languages, such as Ada 9X, Fortran, Modula-3, and
+Pascal, are under development. These front-ends, like that for C++, are
+built in subdirectories of GNU CC 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 GNU CC 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.
+
+@include invoke.texi
+
+@include install.texi
+
+@include extend.texi
+
+@node Trouble
+@chapter Known Causes of Trouble with GNU CC
+@cindex bugs, known
+@cindex installation trouble
+@cindex known causes of trouble
+
+This section describes known problems that affect users of GNU CC. Most
+of these are not GNU CC 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.
+* Installation Problems:: Problems that manifest when you install GNU CC.
+* Cross-Compiler Problems:: Common problems of cross compiling with GNU CC.
+* Interoperation:: Problems using GNU CC with other compilers,
+ and with certain linkers, assemblers and debuggers.
+* External Bugs:: Problems compiling certain programs.
+* Incompatibilities:: GNU CC is incompatible with traditional C.
+* Fixed Headers:: GNU C uses corrected versions of system header files.
+ This is necessary, but doesn't always work smoothly.
+* Standard Libraries:: GNU C uses the system C library, which might not be
+ compliant with the ISO/ANSI 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
+There are several obscure case of mis-using struct, union, and
+enum tags that are not detected as errors by the compiler.
+
+@item
+When @samp{-pedantic-errors} is specified, GNU C will incorrectly give
+an error message when a function name is specified in an expression
+involving the comma operator.
+
+@item
+Loop unrolling doesn't work properly for certain C++ programs. This is
+a bug in the C++ front end. It sometimes emits incorrect debug info, and
+the loop unrolling code is unable to recover from this error.
+@end itemize
+
+@node Installation Problems
+@section Installation Problems
+
+This is a list of problems (and some apparent problems which don't
+really mean anything is wrong) that show up during installation of GNU
+CC.
+
+@itemize @bullet
+@item
+On certain systems, defining certain environment variables such as
+@code{CC} can interfere with the functioning of @code{make}.
+
+@item
+If you encounter seemingly strange errors when trying to build the
+compiler in a directory other than the source directory, it could be
+because you have previously configured the compiler in the source
+directory. Make sure you have done all the necessary preparations.
+@xref{Other Dir}.
+
+@item
+If you build GNU CC on a BSD system using a directory stored in a System
+V file system, problems may occur in running @code{fixincludes} if the
+System V file system doesn't support symbolic links. These problems
+result in a failure to fix the declaration of @code{size_t} in
+@file{sys/types.h}. If you find that @code{size_t} is a signed type and
+that type mismatches occur, this could be the cause.
+
+The solution is not to use such a directory for building GNU CC.
+
+@item
+In previous versions of GNU CC, the @code{gcc} driver program looked for
+@code{as} and @code{ld} in various places; for example, in files
+beginning with @file{/usr/local/lib/gcc-}. GNU CC version 2 looks for
+them in the directory
+@file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}.
+
+Thus, to use a version of @code{as} or @code{ld} that is not the system
+default, for example @code{gas} or GNU @code{ld}, you must put them in
+that directory (or make links to them from that directory).
+
+@item
+Some commands executed when making the compiler may fail (return a
+non-zero status) and be ignored by @code{make}. These failures, which
+are often due to files that were not found, are expected, and can safely
+be ignored.
+
+@item
+It is normal to have warnings in compiling certain files about
+unreachable code and about enumeration type clashes. These files' names
+begin with @samp{insn-}. Also, @file{real.c} may get some warnings that
+you can ignore.
+
+@item
+Sometimes @code{make} recompiles parts of the compiler when installing
+the compiler. In one case, this was traced down to a bug in
+@code{make}. Either ignore the problem or switch to GNU Make.
+
+@item
+If you have installed a program known as purify, you may find that it
+causes errors while linking @code{enquire}, which is part of building
+GNU CC. The fix is to get rid of the file @code{real-ld} which purify
+installs---so that GNU CC won't try to use it.
+
+@item
+On Linux SLS 1.01, there is a problem with @file{libc.a}: it does not
+contain the obstack functions. However, GNU CC assumes that the obstack
+functions are in @file{libc.a} when it is the GNU C library. To work
+around this problem, change the @code{__GNU_LIBRARY__} conditional
+around line 31 to @samp{#if 1}.
+
+@item
+On some 386 systems, building the compiler never finishes because
+@code{enquire} hangs due to a hardware problem in the motherboard---it
+reports floating point exceptions to the kernel incorrectly. You can
+install GNU CC except for @file{float.h} by patching out the command to
+run @code{enquire}. You may also be able to fix the problem for real by
+getting a replacement motherboard. This problem was observed in
+Revision E of the Micronics motherboard, and is fixed in Revision F.
+It has also been observed in the MYLEX MXA-33 motherboard.
+
+If you encounter this problem, you may also want to consider removing
+the FPU from the socket during the compilation. Alternatively, if you
+are running SCO Unix, you can reboot and force the FPU to be ignored.
+To do this, type @samp{hd(40)unix auto ignorefpu}.
+
+@item
+On some 386 systems, GNU CC crashes trying to compile @file{enquire.c}.
+This happens on machines that don't have a 387 FPU chip. On 386
+machines, the system kernel is supposed to emulate the 387 when you
+don't have one. The crash is due to a bug in the emulator.
+
+One of these systems is the Unix from Interactive Systems: 386/ix.
+On this system, an alternate emulator is provided, and it does work.
+To use it, execute this command as super-user:
+
+@example
+ln /etc/emulator.rel1 /etc/emulator
+@end example
+
+@noindent
+and then reboot the system. (The default emulator file remains present
+under the name @file{emulator.dflt}.)
+
+Try using @file{/etc/emulator.att}, if you have such a problem on the
+SCO system.
+
+Another system which has this problem is Esix. We don't know whether it
+has an alternate emulator that works.
+
+On NetBSD 0.8, a similar problem manifests itself as these error messages:
+
+@example
+enquire.c: In function `fprop':
+enquire.c:2328: floating overflow
+@end example
+
+@item
+On SCO systems, when compiling GNU CC with the system's compiler,
+do not use @samp{-O}. Some versions of the system's compiler miscompile
+GNU CC with @samp{-O}.
+
+@cindex @code{genflags}, crash on Sun 4
+@item
+Sometimes on a Sun 4 you may observe a crash in the program
+@code{genflags} or @code{genoutput} while building GNU CC. This is said to
+be due to a bug in @code{sh}. You can probably get around it by running
+@code{genflags} or @code{genoutput} manually and then retrying the
+@code{make}.
+
+@item
+On Solaris 2, executables of GNU CC version 2.0.2 are commonly
+available, but they have a bug that shows up when compiling current
+versions of GNU CC: undefined symbol errors occur during assembly if you
+use @samp{-g}.
+
+The solution is to compile the current version of GNU CC without
+@samp{-g}. That makes a working compiler which you can use to recompile
+with @samp{-g}.
+
+@item
+Solaris 2 comes with a number of optional OS packages. Some of these
+packages are needed to use GNU CC fully. If you did not install all
+optional packages when installing Solaris, you will need to verify that
+the packages that GNU CC needs are installed.
+
+To check whether an optional package is installed, use
+the @code{pkginfo} command. To add an optional package, use the
+@code{pkgadd} command. For further details, see the Solaris
+documentation.
+
+For Solaris 2.0 and 2.1, GNU CC needs six packages: @samp{SUNWarc},
+@samp{SUNWbtool}, @samp{SUNWesu}, @samp{SUNWhea}, @samp{SUNWlibm}, and
+@samp{SUNWtoo}.
+
+For Solaris 2.2, GNU CC needs an additional seventh package: @samp{SUNWsprot}.
+
+@item
+On Solaris 2, trying to use the linker and other tools in
+@file{/usr/ucb} to install GNU CC has been observed to cause trouble.
+For example, the linker may hang indefinitely. The fix is to remove
+@file{/usr/ucb} from your @code{PATH}.
+
+@item
+If you use the 1.31 version of the MIPS assembler (such as was shipped
+with Ultrix 3.1), you will need to use the -fno-delayed-branch switch
+when optimizing floating point code. Otherwise, the assembler will
+complain when the GCC compiler fills a branch delay slot with a
+floating point instruction, such as @code{add.d}.
+
+@item
+If on a MIPS system you get an error message saying ``does not have gp
+sections for all it's [sic] sectons [sic]'', don't worry about it. This
+happens whenever you use GAS with the MIPS linker, but there is not
+really anything wrong, and it is okay to use the output file. You can
+stop such warnings by installing the GNU linker.
+
+It would be nice to extend GAS to produce the gp tables, but they are
+optional, and there should not be a warning about their absence.
+
+@item
+In Ultrix 4.0 on the MIPS machine, @file{stdio.h} does not work with GNU
+CC at all unless it has been fixed with @code{fixincludes}. This causes
+problems in building GNU CC. Once GNU CC is installed, the problems go
+away.
+
+To work around this problem, when making the stage 1 compiler, specify
+this option to Make:
+
+@example
+GCC_FOR_TARGET="./xgcc -B./ -I./include"
+@end example
+
+When making stage 2 and stage 3, specify this option:
+
+@example
+CFLAGS="-g -I./include"
+@end example
+
+@item
+Users have reported some problems with version 2.0 of the MIPS
+compiler tools that were shipped with Ultrix 4.1. Version 2.10
+which came with Ultrix 4.2 seems to work fine.
+
+Users have also reported some problems with version 2.20 of the
+MIPS compiler tools that were shipped with RISC/os 4.x. The earlier
+version 2.11 seems to work fine.
+
+@item
+Some versions of the MIPS linker will issue an assertion failure
+when linking code that uses @code{alloca} against shared
+libraries on RISC-OS 5.0, and DEC's OSF/1 systems. This is a bug
+in the linker, that is supposed to be fixed in future revisions.
+To protect against this, GNU CC passes @samp{-non_shared} to the
+linker unless you pass an explicit @samp{-shared} or
+@samp{-call_shared} switch.
+
+@item
+On System V release 3, you may get this error message
+while linking:
+
+@smallexample
+ld fatal: failed to write symbol name @var{something}
+ in strings table for file @var{whatever}
+@end smallexample
+
+This probably indicates that the disk is full or your ULIMIT won't allow
+the file to be as large as it needs to be.
+
+This problem can also result because the kernel parameter @code{MAXUMEM}
+is too small. If so, you must regenerate the kernel and make the value
+much larger. The default value is reported to be 1024; a value of 32768
+is said to work. Smaller values may also work.
+
+@item
+On System V, if you get an error like this,
+
+@example
+/usr/local/lib/bison.simple: In function `yyparse':
+/usr/local/lib/bison.simple:625: virtual memory exhausted
+@end example
+
+@noindent
+that too indicates a problem with disk space, ULIMIT, or @code{MAXUMEM}.
+
+@item
+Current GNU CC versions probably do not work on version 2 of the NeXT
+operating system.
+
+@item
+On NeXTStep 3.0, the Objective C compiler does not work, due,
+apparently, to a kernel bug that it happens to trigger. This problem
+does not happen on 3.1.
+
+@item
+On the Tower models 4@var{n}0 and 6@var{n}0, by default a process is not
+allowed to have more than one megabyte of memory. GNU CC cannot compile
+itself (or many other programs) with @samp{-O} in that much memory.
+
+To solve this problem, reconfigure the kernel adding the following line
+to the configuration file:
+
+@smallexample
+MAXUMEM = 4096
+@end smallexample
+
+@item
+On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a bug
+in the assembler that must be fixed before GNU CC can be built. This
+bug manifests itself during the first stage of compilation, while
+building @file{libgcc2.a}:
+
+@smallexample
+_floatdisf
+cc1: warning: `-g' option not supported on this version of GCC
+cc1: warning: `-g1' option not supported on this version of GCC
+./xgcc: Internal compiler error: program as got fatal signal 11
+@end smallexample
+
+A patched version of the assembler is available by anonymous ftp from
+@code{altdorf.ai.mit.edu} as the file
+@file{archive/cph/hpux-8.0-assembler}. If you have HP software support,
+the patch can also be obtained directly from HP, as described in the
+following note:
+
+@quotation
+This is the patched assembler, to patch SR#1653-010439, where the
+assembler aborts on floating point constants.
+
+The bug is not really in the assembler, but in the shared library
+version of the function ``cvtnum(3c)''. The bug on ``cvtnum(3c)'' is
+SR#4701-078451. Anyway, the attached assembler uses the archive
+library version of ``cvtnum(3c)'' and thus does not exhibit the bug.
+@end quotation
+
+This patch is also known as PHCO_4484.
+
+@item
+On HP-UX version 8.05, but not on 8.07 or more recent versions,
+the @code{fixproto} shell script triggers a bug in the system shell.
+If you encounter this problem, upgrade your operating system or
+use BASH (the GNU shell) to run @code{fixproto}.
+
+@item
+Some versions of the Pyramid C compiler are reported to be unable to
+compile GNU CC. You must use an older version of GNU CC for
+bootstrapping. One indication of this problem is if you get a crash
+when GNU CC compiles the function @code{muldi3} in file @file{libgcc2.c}.
+
+You may be able to succeed by getting GNU CC version 1, installing it,
+and using it to compile GNU CC version 2. The bug in the Pyramid C
+compiler does not seem to affect GNU CC version 1.
+
+@item
+There may be similar problems on System V Release 3.1 on 386 systems.
+
+@item
+On the Intel Paragon (an i860 machine), if you are using operating
+system version 1.0, you will get warnings or errors about redefinition
+of @code{va_arg} when you build GNU CC.
+
+If this happens, then you need to link most programs with the library
+@file{iclib.a}. You must also modify @file{stdio.h} as follows: before
+the lines
+
+@example
+#if defined(__i860__) && !defined(_VA_LIST)
+#include <va_list.h>
+@end example
+
+@noindent
+insert the line
+
+@example
+#if __PGC__
+@end example
+
+@noindent
+and after the lines
+
+@example
+extern int vprintf(const char *, va_list );
+extern int vsprintf(char *, const char *, va_list );
+#endif
+@end example
+
+@noindent
+insert the line
+
+@example
+#endif /* __PGC__ */
+@end example
+
+These problems don't exist in operating system version 1.1.
+
+@item
+On the Altos 3068, programs compiled with GNU CC won't work unless you
+fix a kernel bug. This happens using system versions V.2.2 1.0gT1 and
+V.2.2 1.0e and perhaps later versions as well. See the file
+@file{README.ALTOS}.
+
+@item
+You will get several sorts of compilation and linking errors on the
+we32k if you don't follow the special instructions. @xref{Configurations}.
+
+@item
+A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto
+program to report an error of the form:
+
+@example
+./fixproto: sh internal 1K buffer overflow
+@end example
+
+To fix this, change the first line of the fixproto script to look like:
+
+@example
+#!/bin/ksh
+@end example
+@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 GNU C or
+GNU C++ 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
+GNU C++ 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 GNU CC version
+2. If you have trouble, get GDB version 4.4 or later.
+
+@item
+@cindex DBX
+DBX rejects some files produced by GNU CC, 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.
+
+@item
+Use of @samp{-I/usr/include} may cause trouble.
+
+Many systems come with header files that won't work with GNU CC unless
+corrected by @code{fixincludes}. The corrected header files go in a new
+directory; GNU CC searches this directory before @file{/usr/include}.
+If you use @samp{-I/usr/include}, this tells GNU CC to search
+@file{/usr/include} earlier on, before the corrected headers. The
+result is that you get the uncorrected header files.
+
+Instead, you should use these options (when compiling C programs):
+
+@smallexample
+-I/usr/local/lib/gcc-lib/@var{target}/@var{version}/include -I/usr/include
+@end smallexample
+
+For C++ programs, GNU CC also uses a special directory that defines C++
+interfaces to standard C subroutines. This directory is meant to be
+searched @emph{before} other standard include directories, so that it
+takes precedence. If you are compiling C++ programs and specifying
+include directories explicitly, use this option first, then the two
+options above:
+
+@example
+-I/usr/local/lib/g++-include
+@end example
+
+@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 GNU CC 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 @samp{-O} for those source files.
+@end ignore
+
+@item
+On some SGI systems, when you use @samp{-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 GNU CC.
+You must specify all three options explicitly.
+
+@item
+On a Sparc, GNU CC 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 GNU CC, dereferencing the
+pointer may cause a fatal signal.
+
+One way to solve this problem is to compile your entire program with GNU
+CC. 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 GNU CC 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 @samp{-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 GNU CC
+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 GNU CC correctly. We do not yet know why. However, GNU CC
+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 GNU CC. Specifically, it fails to work on functions that use
+@code{alloca} or variable-size arrays. This is because GNU CC doesn't
+generate HP-UX unwind descriptors for such functions. It may even be
+impossible to generate them.
+
+@item
+Debugging (@samp{-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 GNU CC, but is now exceptionally rare. If you should run
+into it, you can work around by making your function smaller.
+
+@item
+GNU CC 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 @samp{-g} option in GCC from
+working. Note that @file{Makefile.in} uses @samp{-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 presense 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 "-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 ANSI 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 ("." vs "," 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 LANG environment variable to "C" or
+"En_US".
+
+@item
+Even if you specify @samp{-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
+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. GNU CC uses
+@samp{fldcr} on the 88100 to serialize volatile memory references. Use
+the option @samp{-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 GNU CC no matter
+what options are used.
+
+@cindex RT PC
+@cindex IBM RT PC
+@item
+On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
+convention for structure and union returning. Use the option
+@samp{-mhc-struct-return} to tell GNU CC to use a convention compatible
+with it.
+
+@cindex Vax calling convention
+@cindex Ultrix calling convention
+@item
+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.
+
+GNU CC 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 GNU CC 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.7.1 -lgcc -lc_s
+@end smallexample
+
+The first specifies where to find the library @file{libgcc.a}
+specified with the @samp{-lgcc} option.
+
+GNU CC does linking by invoking @code{ld}, just as @code{cc} does, and
+there is no reason why it @emph{should} matter which compilation program
+you use to invoke @code{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.
+
+Or use the @samp{-noasmopt} option when you compile GNU CC 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 @samp{-O0} to the assembler, and never
+passes @samp{-O2} or @samp{-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
+@samp{-I/usr/include/mit} to use the MIT versions of the header files,
+using the @samp{-traditional} switch to turn off ANSI C, or fixing the
+header files by adding this:
+
+@example
+#ifdef __STDC__
+#define NeedFunctionPrototypes 0
+#endif
+@end example
+
+@item
+If you have trouble compiling Perl on a SunOS 4 system, it may be
+because Perl specifies @samp{-I/usr/ucbinclude}. This accesses the
+unfixed header files. Perl specifies the options
+
+@example
+-traditional -Dvolatile=__volatile__
+-I/usr/include/sun -I/usr/ucbinclude
+-fpcc-struct-return
+@end example
+
+@noindent
+most of which are unnecessary with GCC 2.4.5 and newer versions. You
+can make a properly working Perl by setting @code{ccflags} to
+@samp{-fwritable-strings} (implied by the @samp{-traditional} in the
+original options) and @code{cppflags} to empty in @file{config.sh}, then
+typing @samp{./doSH; make depend; make}.
+
+@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 GNU CC 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 GNU CC:
+
+@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
+GNU CC:
+
+@example
+MALLOC=gmalloc.o
+@end example
+@end itemize
+
+@node Incompatibilities
+@section Incompatibilities of GNU CC
+@cindex incompatibilities of GNU CC
+
+There are several noteworthy incompatibilities between GNU C and most
+existing (non-ANSI) versions of C. The @samp{-traditional} option
+eliminates many of these incompatibilities, @emph{but not all}, by
+telling GNU C to behave like the other C compilers.
+
+@itemize @bullet
+@cindex string constants
+@cindex read-only strings
+@cindex shared strings
+@item
+GNU CC normally makes string constants read-only. If several
+identical-looking string constants are used, GNU CC 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}.
+
+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 @samp{-fwritable-strings} flag, which directs GNU CC
+to handle string constants the same way most C compilers do.
+@samp{-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 ANSI C rules) its data type is @code{unsigned long int}.
+Negating this value yields 2147483648 again.
+
+@item
+GNU CC does not substitute macro arguments when they appear inside of
+string constants. For example, the following macro in GNU CC
+
+@example
+#define foo(a) "a"
+@end example
+
+@noindent
+will produce output @code{"a"} regardless of what the argument @var{a} is.
+
+The @samp{-traditional} option directs GNU CC to handle such cases
+(among others) in the old-fashioned (non-ANSI) 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.
+
+If you use the @samp{-W} option with the @samp{-O} option, you will
+get a warning when GNU CC thinks such a problem might be possible.
+
+The @samp{-traditional} option directs GNU C 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 GNU CC. For example, a program like this
+will not work:
+
+@example
+foobar (
+#define luser
+ hack)
+@end example
+
+ANSI C does not permit such a construct. It would make sense to support
+it when @samp{-traditional} is used, but it is too much work to
+implement.
+
+@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 @samp{-traditional} option directs GNU C 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 ANSI 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 @samp{-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.
+
+@cindex whitespace
+@item
+PCC allows whitespace in the middle of compound assignment operators
+such as @samp{+=}. GNU CC, following the ANSI standard, does not
+allow this. The difficulty described immediately above applies here
+too.
+
+@cindex apostrophes
+@cindex '
+@item
+GNU CC 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, GNU CC 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,
+@samp{-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 ANSI 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 @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. GNU CC 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, GNU CC
+output code normally uses a method different from that used on most
+versions of Unix. As a result, code compiled with GNU CC cannot call
+a structure-returning function compiled with PCC, and vice versa.
+
+The method used by GNU CC 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 GNU CC 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. GNU CC 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. GNU CC 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.
+
+You can tell GNU CC to use a compatible convention for all structure and
+union returning with the option @samp{-fpcc-struct-return}.
+
+@cindex preprocessing tokens
+@cindex preprocessing numbers
+@item
+GNU C 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,
+GNU C prints an error message. Although it may appear obvious that what
+is meant is an operator and two values, the ANSI 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+}, or @samp{E-} character
+sequences.
+
+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
+
+GNU CC 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 GNU CC unless they are changed. Some have bugs, some are
+incompatible with ANSI C, and some depend on special features of other
+compilers.
+
+Installing GNU CC 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 GNU CC are not automatically
+updated. The easiest way to update them is to reinstall GNU CC. (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, GNU CC 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 GNU CC's fault, but it
+does mean that there's nothing for us to do about them.
+@end itemize
+
+@node Standard Libraries
+@section Standard Libraries
+
+GNU CC by itself attempts to be what the ISO/ANSI C standard calls a
+@dfn{conforming freestanding implementation}. This means all ANSI
+C language features are available, as well as the contents of
+@file{float.h}, @file{limits.h}, @file{stdarg.h}, and
+@file{stddef.h}. 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 @samp{-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
+GNU CC does not provide one. The GNU C library (called @code{glibc})
+has been ported to a number of operating systems, and provides ANSI/ISO,
+POSIX, BSD and SystemV compatibility. 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 GNU CC 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 GNU CC 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 GNU CC 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 ANSI 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 ANSI C just to avoid an error for the example
+shown above.
+
+@item
+Accesses to bitfields 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 bitfield; it may even
+vary for a given bitfield according to the precise usage.
+
+If you care about controlling the amount of memory that is accessed, use
+volatile but do not use bitfields.
+
+@item
+GNU CC 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 GNU CC 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 GNU CC
+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
+On 68000 systems, 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 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.
+
+You can partially avoid this problem by using the @samp{-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 ANSI standard @file{stdarg.h}
+method of variable arguments, and the prototype is in scope at
+the time of the call, everything will work fine.
+@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 ANSI C++ draft standard) is also evolving. 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
+@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 draft ANSI
+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 the libg++
+@code{String} class, that define a conversion function to type
+@code{char *} or @code{const char *}. 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 *);
+@end example
+
+@noindent
+In this situation, it may seem natural to write @w{@samp{charfunc
+(strfunc ());}} based on the knowledge that class @code{String} has an
+explicit conversion to @code{char} pointers. However, what really
+happens is akin to @samp{charfunc (@w{strfunc ()}.@w{convert ()});},
+where the @code{convert} method is a function to do the same data
+conversion normally performed by a cast. Since the last use of the
+temporary @code{String} object is the call to the conversion function,
+the compiler may delete that object before actually calling
+@code{charfunc}. The compiler has no way of knowing that deleting the
+@code{String} object will invalidate the pointer. The pointer then
+points to garbage, so that by the time @code{charfunc} is called, it
+gets an invalid argument.
+
+Code like this may run successfully under some other compilers,
+especially those that delete temporaries relatively late. However, the
+GNU C++ behavior is also standard-conforming, so if your program depends
+on late destruction of temporaries it is not portable.
+
+If you think this is surprising, you should be aware that the ANSI C++
+committee continues to debate the lifetime-of-temporaries problem.
+
+For now, at least, 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);
+@end example
+
+@node Protoize Caveats
+@section Caveats of using @code{protoize}
+
+The conversion programs @code{protoize} and @code{unprotoize} can
+sometimes change a source file in a way that won't work unless you
+rearrange it.
+
+@itemize @bullet
+@item
+@code{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 @code{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. @code{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. ANSI C does not require declaring the argument types of
+pointer-to-function types.
+
+@item
+Using @code{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 @code{unprotoize} is safe is when
+you are removing prototypes that were made with @code{protoize}; if
+the program worked before without any prototypes, it will work again
+without them.
+
+You can find all the places where this problem might occur by compiling
+the program with the @samp{-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
+@code{protoize} cannot get the argument types for a function whose
+definition was not actually compiled due to preprocessing conditionals.
+When this happens, @code{protoize} changes nothing in regard to such
+a function. @code{protoize} tries to detect such instances and warn
+about them.
+
+You can generally work around this problem by using @code{protoize} step
+by step, each time specifying a different set of @samp{-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
+@code{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 recommand 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 GNU CC 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 about unreachable code.
+
+It's very common to have unreachable code in machine-generated
+programs. For example, this happens normally in some files of GNU C
+itself.
+
+@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
+Assuming (for optimization) that the address of an external symbol is
+never zero.
+
+This assumption is false on certain systems when @samp{#pragma weak} is
+used.
+
+@item
+Making @samp{-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 bitfields unsigned by default on particular machines where ``the
+ABI standard'' says to do so.
+
+The ANSI C standard leaves it up to the implementation whether a bitfield
+declared plain @code{int} is signed or not. This in effect creates two
+alternative dialects of C.
+
+The GNU C compiler supports both dialects; you can specify the signed
+dialect with @samp{-fsigned-bitfields} and the unsigned dialect with
+@samp{-funsigned-bitfields}. However, this leaves open the question of
+which dialect to use by default.
+
+Currently, the preferred dialect makes plain bitfields 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 bitfields
+as well.
+
+Some computer manufacturers have published Application Binary Interface
+standards which specify that plain bitfields should be unsigned. It is
+a mistake, however, to say anything about this issue in an ABI. This is
+because the handling of plain bitfields distinguishes two dialects of C.
+Both dialects are meaningful on every type of machine. Whether a
+particular object file was compiled using signed bitfields or unsigned
+is of no concern to other object files, even if they access the same
+bitfields 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 bitfields 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 GNU CC does and will treat plain bitfields in the same
+fashion on all types of machines (by default).
+
+There are some arguments for making bitfields unsigned by default on all
+machines. If, for example, this becomes a universal de facto standard,
+it would make sense for GNU CC 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 bitfield whether it is signed or not. In this way,
+they write programs which have the same meaning in both C dialects.)
+
+@item
+Undefining @code{__STDC__} when @samp{-ansi} is not used.
+
+Currently, GNU CC defines @code{__STDC__} as long as you don't use
+@samp{-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 ANSI C, such as function
+prototypes or ANSI token concatenation. Since plain @samp{gcc} supports
+all the features of ANSI 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 ANSI
+C program, because the ANSI 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 ANSI C
+library.
+
+Sometimes people say that defining @code{__STDC__} in a compiler that
+does not completely conform to the ANSI C standard somehow violates the
+standard. This is illogical. The standard is a standard for compilers
+that claim to support ANSI C, such as @samp{gcc -ansi}---not for other
+compilers such as plain @samp{gcc}. Whatever the ANSI C standard says
+is relevant to the design of plain @samp{gcc} without @samp{-ansi} only
+for pragmatic reasons, not as a requirement.
+
+@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 ANSI 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 ANSI
+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.
+
+GNU CC does not delete ``empty'' loops because the most likely reason
+you would put one in a program is to have a delay. Deleting them will
+not make real programs run any faster, so it would be pointless.
+
+It would be different if optimization of a nonempty loop could produce
+an empty one. But this generally can't happen.
+
+@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 ANSI 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.
+@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
+@emph{Errors} report problems that make it impossible to compile your
+program. GNU CC reports errors with the source file name and line
+number where the problem is apparent.
+
+@item
+@emph{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 @samp{-W}
+options (for instance, @samp{-Wall} requests a variety of useful
+warnings).
+
+GNU CC 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 @samp{-pedantic} option tells GNU CC to issue warnings in
+such cases; @samp{-pedantic-errors} says to make them errors instead.
+This does not mean that @emph{all} non-ANSI 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 GNU CC 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 GNU CC work
+better. Bug reports are your contribution to the maintenance of GNU CC.
+
+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.
+* Patches: Sending Patches. How to send a patch for GNU CC.
+* Known: Trouble. Known problems.
+* Help: Service. Where to ask for help.
+@end menu
+
+@node Bug Criteria
+@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 GNU CC 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; GNU CC 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 C or C++ compilers, your suggestions
+for improvement of GNU CC or GNU C++ are welcome in any case.
+@end itemize
+
+@node Bug Lists
+@section Where to Report Bugs
+@cindex bug report mailing lists
+@kindex bug-gcc@@prep.ai.mit.edu
+Send bug reports for GNU C to @samp{bug-gcc@@prep.ai.mit.edu}.
+
+@kindex bug-g++@@prep.ai.mit.edu
+@kindex bug-libg++@@prep.ai.mit.edu
+Send bug reports for GNU C++ to @samp{bug-g++@@prep.ai.mit.edu}.
+If your bug involves the C++ class library libg++, send mail to
+@samp{bug-lib-g++@@prep.ai.mit.edu}. If you're not sure, you can send
+the bug report to both lists.
+
+@strong{Do not send bug reports to @samp{help-gcc@@prep.ai.mit.edu} or
+to the newsgroup @samp{gnu.gcc.help}.} Most users of GNU CC do not want
+to receive bug reports. Those that do, have asked to be on
+@samp{bug-gcc} and/or @samp{bug-g++}.
+
+The mailing lists @samp{bug-gcc} and @samp{bug-g++} both have newsgroups
+which serve as repeaters: @samp{gnu.gcc.bug} and @samp{gnu.g++.bug}.
+Each mailing list and its newsgroup carry exactly the same messages.
+
+Often people think of posting bug reports to the newsgroup instead of
+mailing them. This appears to work, but it has one problem which can be
+crucial: a newsgroup posting does not contain a mail path back to the
+sender. Thus, if maintainers need more information, they may be unable
+to reach you. For this reason, you should always send bug reports by
+mail to the proper mailing list.
+
+As a last resort, send bug reports on paper to:
+
+@example
+GNU Compiler Bugs
+Free Software Foundation
+59 Temple Place - Suite 330
+Boston, MA 02111-1307, USA
+@end example
+
+@node Bug Reporting
+@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.
+
+Do not compress and encode any part of your bug report using programs
+such as @file{uuencode}. If you do so it will slow down the processing
+of your bug. If you must submit multiple large files, use @file{shar},
+which allows us to read your message without having to run any
+decompression programs.
+
+To enable someone to investigate the bug, you should include all these
+things:
+
+@itemize @bullet
+@item
+The version of GNU CC. You can get this by running it with the
+@samp{-v} option.
+
+Without this, we won't know whether there is any point in looking for
+the bug in the current version of GNU CC.
+
+@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}), run your
+source file through the C preprocessor by doing @samp{gcc -E
+@var{sourcefile} > @var{outfile}}, then include the contents of
+@var{outfile} in the bug report. (When you do this, use the same
+@samp{-I}, @samp{-D} or @samp{-U} options that you used in actual
+compilation.)
+
+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 GNU CC 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 GNU CC 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 GNU CC or GNU C++ to compile that example
+and observe the bug. For example, did you use @samp{-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
+GNU CC.
+
+@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 GNU CC 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 GNU CC or GNU C++,
+please use @samp{-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 GNU CC 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 GNU CC 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 GNU CC 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 GNU CC 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.
+
+@xref{Sending Patches}, 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 Sending Patches,, Bug Reporting, Bugs
+@section Sending Patches for GNU CC
+
+If you would like to write bug fixes or improvements for the GNU C
+compiler, that is very helpful. Send suggested fixes to the bug report
+mailing list, @code{bug-gcc@@prep.ai.mit.edu}.
+
+Please follow these guidelines so we can study your patches efficiently.
+If you don't follow these guidelines, your information might still be
+useful, but using it will take extra work. Maintaining GNU C is a lot
+of work in the best of circumstances, and we can't keep up unless you do
+your best to help.
+
+@itemize @bullet
+@item
+Send an explanation with your changes of what problem they fix or what
+improvement they bring about. For a bug fix, just include a copy of the
+bug report, and explain why the change fixes the bug.
+
+(Referring to a bug report is not as good as including it, because then
+we will have to look it up, and we have probably already deleted it if
+we've already fixed the bug.)
+
+@item
+Always include a proper bug report for the problem you think you have
+fixed. We need to convince ourselves that the change is right before
+installing it. Even if it is right, we might have trouble judging it if
+we don't have a way to reproduce the problem.
+
+@item
+Include all the comments that are appropriate to help people reading the
+source in the future understand why this change was needed.
+
+@item
+Don't mix together changes made for different reasons.
+Send them @emph{individually}.
+
+If you make two changes for separate reasons, then we might not want to
+install them both. We might want to install just one. If you send them
+all jumbled together in a single set of diffs, we have to do extra work
+to disentangle them---to figure out which parts of the change serve
+which purpose. If we don't have time for this, we might have to ignore
+your changes entirely.
+
+If you send each change as soon as you have written it, with its own
+explanation, then the two changes never get tangled up, and we can
+consider each one properly without any extra work to disentangle them.
+
+Ideally, each change you send should be impossible to subdivide into
+parts that we might want to consider separately, because each of its
+parts gets its motivation from the other parts.
+
+@item
+Send each change as soon as that change is finished. Sometimes people
+think they are helping us by accumulating many changes to send them all
+together. As explained above, this is absolutely the worst thing you
+could do.
+
+Since you should send each change separately, you might as well send it
+right away. That gives us the option of installing it immediately if it
+is important.
+
+@item
+Use @samp{diff -c} to make your diffs. Diffs without context are hard
+for us to install reliably. More than that, they make it hard for us to
+study the diffs to decide whether we want to install them. Unidiff
+format is better than contextless diffs, but not as easy to read as
+@samp{-c} format.
+
+If you have GNU diff, use @samp{diff -cp}, which shows the name of the
+function that each change occurs in.
+
+@item
+Write the change log entries for your changes. We get lots of changes,
+and we don't have time to do all the change log writing ourselves.
+
+Read the @file{ChangeLog} file to see what sorts of information to put
+in, and to learn the style that we use. The purpose of the change log
+is to show people where to find what was changed. So you need to be
+specific about what functions you changed; in large functions, it's
+often helpful to indicate where within the function the change was.
+
+On the other hand, once you have shown people where to find the change,
+you need not explain its purpose. Thus, if you add a new function, all
+you need to say about it is that it is new. If you feel that the
+purpose needs explaining, it probably does---but the explanation will be
+much more useful if you put it in comments in the code.
+
+If you would like your name to appear in the header line for who made
+the change, send us the header line.
+
+@item
+When you write the fix, keep in mind that we can't install a change that
+would break other systems.
+
+People often suggest fixing a problem by changing machine-independent
+files such as @file{toplev.c} to do something special that a particular
+system needs. Sometimes it is totally obvious that such changes would
+break GNU CC for almost all users. We can't possibly make a change like
+that. At best it might tell us how to write another patch that would
+solve the problem acceptably.
+
+Sometimes people send fixes that @emph{might} be an improvement in
+general---but it is hard to be sure of this. It's hard to install
+such changes because we have to study them very carefully. Of course,
+a good explanation of the reasoning by which you concluded the change
+was correct can help convince us.
+
+The safest changes are changes to the configuration files for a
+particular machine. These are safe because they can't create new bugs
+on other machines.
+
+Please help us keep up with the workload by designing the patch in a
+form that is good to install.
+@end itemize
+
+@node Service
+@chapter How To Get Help with GNU CC
+
+If you need help installing, using or changing GNU CC, there are two
+ways to find it:
+
+@itemize @bullet
+@item
+Send a message to a suitable network mailing list. First try
+@code{bug-gcc@@prep.ai.mit.edu}, and if that brings no response, try
+@code{help-gcc@@prep.ai.mit.edu}.
+
+@item
+Look in the service directory for someone who might help you for a fee.
+The service directory is found in the file named @file{SERVICE} in the
+GNU CC distribution.
+@end itemize
+
+@node VMS
+@chapter Using GNU CC on VMS
+
+@c prevent bad page break with this line
+Here is how to use GNU CC 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
+ GNU CC.
+* 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, GNU CC
+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. GNU CC 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 GNU CC. VAX-C
+treats this much like a standard @code{#include <foobar.h>} directive.
+That is incompatible with the ANSI C behavior implemented by GNU CC: 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}. GNU CC 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.
+
+GNU CC for VMS is distributed with a set of include files that is
+sufficient to compile most general purpose programs. Even though the
+GNU CC 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 GNU CC 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
+GNU CC 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 ANSI 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
+GNU CC 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 GNU CC did not provide this default.
+
+GNU CC 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 GNU CC, 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, GNU CC (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, GNU CC (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 GNU
+C++. 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.
+@end ifset
+
+@ifset INTERNALS
+@node Portability
+@chapter GNU CC and Portability
+@cindex portability
+@cindex GNU CC and portability
+
+The main goal of GNU CC was to make a good, fast compiler for machines in
+the class that the GNU system aims to run on: 32-bit machines that address
+8-bit bytes and have several general registers. Elegance, theoretical
+power and simplicity are only secondary.
+
+GNU CC gets most of the information about the target machine from a machine
+description which gives an algebraic formula for each of the machine's
+instructions. This is a very clean way to describe the target. But when
+the compiler needs information that is difficult to express in this
+fashion, I have not hesitated to define an ad-hoc parameter to the machine
+description. The purpose of portability is to reduce the total work needed
+on the compiler; it was not of interest for its own sake.
+
+@cindex endianness
+@cindex autoincrement addressing, availability
+@findex abort
+GNU CC does not contain machine dependent code, but it does contain code
+that depends on machine parameters such as endianness (whether the most
+significant byte has the highest or lowest address of the bytes in a word)
+and the availability of autoincrement addressing. In the RTL-generation
+pass, it is often necessary to have multiple strategies for generating code
+for a particular kind of syntax tree, strategies that are usable for different
+combinations of parameters. Often I have not tried to address all possible
+cases, but only the common ones or only the ones that I have encountered.
+As a result, a new target may require additional strategies. You will know
+if this happens because the compiler will call @code{abort}. Fortunately,
+the new strategies can be added in a machine-independent fashion, and will
+affect only the target machines that need them.
+@end ifset
+
+@ifset INTERNALS
+@node Interface
+@chapter Interfacing to GNU CC Output
+@cindex interfacing to GNU CC output
+@cindex run-time conventions
+@cindex function call conventions
+@cindex conventions, run-time
+
+GNU CC is normally configured to use the same function calling convention
+normally in use on the target system. This is done with the
+machine-description macros described (@pxref{Target Macros}).
+
+@cindex unions, returning
+@cindex structures, returning
+@cindex returning structures and unions
+However, returning of structure and union values is done differently on
+some target machines. As a result, functions compiled with PCC
+returning such types cannot be called from code compiled with GNU CC,
+and vice versa. This does not cause trouble often because few Unix
+library routines return structures or unions.
+
+GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes
+long in the same registers used for @code{int} or @code{double} return
+values. (GNU CC typically allocates variables of such types in
+registers also.) Structures and unions of other sizes are returned by
+storing them into an address passed by the caller (usually in a
+register). The machine-description macros @code{STRUCT_VALUE} and
+@code{STRUCT_INCOMING_VALUE} tell GNU CC 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. This is slower than the method used by GNU CC, and
+fails to be reentrant.
+
+On some target machines, such as RISC machines and the 80386, the
+standard system convention is to pass to the subroutine the address of
+where to return the value. On these machines, GNU CC has been
+configured to be compatible with the standard compiler, when this method
+is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes.
+
+@cindex argument passing
+@cindex passing arguments
+GNU CC uses the system's standard convention for passing arguments. On
+some machines, the first few arguments are passed in registers; in
+others, all are passed on the stack. It would be possible to use
+registers for argument passing on any machine, and this would probably
+result in a significant speedup. But the result would be complete
+incompatibility with code that follows the standard convention. So this
+change is practical only if you are switching to GNU CC as the sole C
+compiler for the system. We may implement register argument passing on
+certain machines once we have a complete GNU system so that we can
+compile the libraries with GNU CC.
+
+On some machines (particularly the Sparc), certain types of arguments
+are passed ``by invisible reference''. This means that the value is
+stored in memory, and the address of the memory location is passed to
+the subroutine.
+
+@cindex @code{longjmp} and automatic variables
+If you use @code{longjmp}, beware of automatic variables. ANSI C says that
+automatic variables that are not declared @code{volatile} have undefined
+values after a @code{longjmp}. And this is all GNU CC promises to do,
+because it is very difficult to restore register variables correctly, and
+one of GNU CC's features is that it can put variables in registers without
+your asking it to.
+
+If you want a variable to be unaltered by @code{longjmp}, and you don't
+want to write @code{volatile} because old C compilers don't accept it,
+just take the address of the variable. If a variable's address is ever
+taken, even if just to compute it and ignore it, then the variable cannot
+go in a register:
+
+@example
+@{
+ int careful;
+ &careful;
+ @dots{}
+@}
+@end example
+
+@cindex arithmetic libraries
+@cindex math libraries
+Code compiled with GNU CC may call certain library routines. Most of
+them handle arithmetic for which there are no instructions. This
+includes multiply and divide on some machines, and floating point
+operations on any machine for which floating point support is disabled
+with @samp{-msoft-float}. Some standard parts of the C library, such as
+@code{bcopy} or @code{memcpy}, are also called automatically. The usual
+function call interface is used for calling the library routines.
+
+These library routines should be defined in the library @file{libgcc.a},
+which GNU CC automatically searches whenever it links a program. On
+machines that have multiply and divide instructions, if hardware
+floating point is in use, normally @file{libgcc.a} is not needed, but it
+is searched just in case.
+
+Each arithmetic function is defined in @file{libgcc1.c} to use the
+corresponding C arithmetic operator. As long as the file is compiled
+with another C compiler, which supports all the C arithmetic operators,
+this file will work portably. However, @file{libgcc1.c} does not work if
+compiled with GNU CC, because each arithmetic function would compile
+into a call to itself!
+@end ifset
+
+@ifset INTERNALS
+@node Passes
+@chapter Passes and Files of the Compiler
+@cindex passes and files of the compiler
+@cindex files and passes of the compiler
+@cindex compiler passes and files
+
+@cindex top level of compiler
+The overall control structure of the compiler is in @file{toplev.c}. This
+file is responsible for initialization, decoding arguments, opening and
+closing files, and sequencing the passes.
+
+@cindex parsing pass
+The parsing pass is invoked only once, to parse the entire input. The RTL
+intermediate code for a function is generated as the function is parsed, a
+statement at a time. Each statement is read in as a syntax tree and then
+converted to RTL; then the storage for the tree for the statement is
+reclaimed. Storage for types (and the expressions for their sizes),
+declarations, and a representation of the binding contours and how they nest,
+remain until the function is finished being compiled; these are all needed
+to output the debugging information.
+
+@findex rest_of_compilation
+@findex rest_of_decl_compilation
+Each time the parsing pass reads a complete function definition or
+top-level declaration, it calls either the function
+@code{rest_of_compilation}, or the function
+@code{rest_of_decl_compilation} in @file{toplev.c}, which are
+responsible for all further processing necessary, ending with output of
+the assembler language. All other compiler passes run, in sequence,
+within @code{rest_of_compilation}. When that function returns from
+compiling a function definition, the storage used for that function
+definition's compilation is entirely freed, unless it is an inline
+function
+@ifset USING
+(@pxref{Inline,,An Inline Function is As Fast As a Macro}).
+@end ifset
+@ifclear USING
+(@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
+@end ifclear
+
+Here is a list of all the passes of the compiler and their source files.
+Also included is a description of where debugging dumps can be requested
+with @samp{-d} options.
+
+@itemize @bullet
+@item
+Parsing. This pass reads the entire text of a function definition,
+constructing partial syntax trees. This and RTL generation are no longer
+truly separate passes (formerly they were), but it is easier to think
+of them as separate.
+
+The tree representation does not entirely follow C syntax, because it is
+intended to support other languages as well.
+
+Language-specific data type analysis is also done in this pass, and every
+tree node that represents an expression has a data type attached.
+Variables are represented as declaration nodes.
+
+@cindex constant folding
+@cindex arithmetic simplifications
+@cindex simplifications, arithmetic
+Constant folding and some arithmetic simplifications are also done
+during this pass.
+
+The language-independent source files for parsing are
+@file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}.
+There are also header files @file{tree.h} and @file{tree.def}
+which define the format of the tree representation.@refill
+
+@c Avoiding overfull is tricky here.
+The source files to parse C are
+@file{c-parse.in},
+@file{c-decl.c},
+@file{c-typeck.c},
+@file{c-aux-info.c},
+@file{c-convert.c},
+and @file{c-lang.c}
+along with header files
+@file{c-lex.h}, and
+@file{c-tree.h}.
+
+The source files for parsing C++ are @file{cp-parse.y},
+@file{cp-class.c},@*
+@file{cp-cvt.c}, @file{cp-decl.c}, @file{cp-decl2.c},
+@file{cp-dem.c}, @file{cp-except.c},@*
+@file{cp-expr.c}, @file{cp-init.c}, @file{cp-lex.c},
+@file{cp-method.c}, @file{cp-ptree.c},@*
+@file{cp-search.c}, @file{cp-tree.c}, @file{cp-type2.c}, and
+@file{cp-typeck.c}, along with header files @file{cp-tree.def},
+@file{cp-tree.h}, and @file{cp-decl.h}.
+
+The special source files for parsing Objective C are
+@file{objc-parse.y}, @file{objc-actions.c}, @file{objc-tree.def}, and
+@file{objc-actions.h}. Certain C-specific files are used for this as
+well.
+
+The file @file{c-common.c} is also used for all of the above languages.
+
+@cindex RTL generation
+@item
+RTL generation. This is the conversion of syntax tree into RTL code.
+It is actually done statement-by-statement during parsing, but for
+most purposes it can be thought of as a separate pass.
+
+@cindex target-parameter-dependent code
+This is where the bulk of target-parameter-dependent code is found,
+since often it is necessary for strategies to apply only when certain
+standard kinds of instructions are available. The purpose of named
+instruction patterns is to provide this information to the RTL
+generation pass.
+
+@cindex tail recursion optimization
+Optimization is done in this pass for @code{if}-conditions that are
+comparisons, boolean operations or conditional expressions. Tail
+recursion is detected at this time also. Decisions are made about how
+best to arrange loops and how to output @code{switch} statements.
+
+@c Avoiding overfull is tricky here.
+The source files for RTL generation include
+@file{stmt.c},
+@file{calls.c},
+@file{expr.c},
+@file{explow.c},
+@file{expmed.c},
+@file{function.c},
+@file{optabs.c}
+and @file{emit-rtl.c}.
+Also, the file
+@file{insn-emit.c}, generated from the machine description by the
+program @code{genemit}, is used in this pass. The header file
+@file{expr.h} is used for communication within this pass.@refill
+
+@findex genflags
+@findex gencodes
+The header files @file{insn-flags.h} and @file{insn-codes.h},
+generated from the machine description by the programs @code{genflags}
+and @code{gencodes}, tell this pass which standard names are available
+for use and which patterns correspond to them.@refill
+
+Aside from debugging information output, none of the following passes
+refers to the tree structure representation of the function (only
+part of which is saved).
+
+@cindex inline, automatic
+The decision of whether the function can and should be expanded inline
+in its subsequent callers is made at the end of rtl generation. The
+function must meet certain criteria, currently related to the size of
+the function and the types and number of parameters it has. Note that
+this function may contain loops, recursive calls to itself
+(tail-recursive functions can be inlined!), gotos, in short, all
+constructs supported by GNU CC. The file @file{integrate.c} contains
+the code to save a function's rtl for later inlining and to inline that
+rtl when the function is called. The header file @file{integrate.h}
+is also used for this purpose.
+
+The option @samp{-dr} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.rtl} to
+the input file name.
+
+@cindex jump optimization
+@cindex unreachable code
+@cindex dead code
+@item
+Jump optimization. This pass simplifies jumps to the following
+instruction, jumps across jumps, and jumps to jumps. It deletes
+unreferenced labels and unreachable code, except that unreachable code
+that contains a loop is not recognized as unreachable in this pass.
+(Such loops are deleted later in the basic block analysis.) It also
+converts some code originally written with jumps into sequences of
+instructions that directly set values from the results of comparisons,
+if the machine has such instructions.
+
+Jump optimization is performed two or three times. The first time is
+immediately following RTL generation. The second time is after CSE,
+but only if CSE says repeated jump optimization is needed. The
+last time is right before the final pass. That time, cross-jumping
+and deletion of no-op move instructions are done together with the
+optimizations described above.
+
+The source file of this pass is @file{jump.c}.
+
+The option @samp{-dj} causes a debugging dump of the RTL code after
+this pass is run for the first time. This dump file's name is made by
+appending @samp{.jump} to the input file name.
+
+@cindex register use analysis
+@item
+Register scan. This pass finds the first and last use of each
+register, as a guide for common subexpression elimination. Its source
+is in @file{regclass.c}.
+
+@cindex jump threading
+@item
+Jump threading. This pass detects a condition jump that branches to an
+identical or inverse test. Such jumps can be @samp{threaded} through
+the second conditional test. The source code for this pass is in
+@file{jump.c}. This optimization is only performed if
+@samp{-fthread-jumps} is enabled.
+
+@cindex common subexpression elimination
+@cindex constant propagation
+@item
+Common subexpression elimination. This pass also does constant
+propagation. Its source file is @file{cse.c}. If constant
+propagation causes conditional jumps to become unconditional or to
+become no-ops, jump optimization is run again when CSE is finished.
+
+The option @samp{-ds} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.cse} to
+the input file name.
+
+@cindex loop optimization
+@cindex code motion
+@cindex strength-reduction
+@item
+Loop optimization. This pass moves constant expressions out of loops,
+and optionally does strength-reduction and loop unrolling as well.
+Its source files are @file{loop.c} and @file{unroll.c}, plus the header
+@file{loop.h} used for communication between them. Loop unrolling uses
+some functions in @file{integrate.c} and the header @file{integrate.h}.
+
+The option @samp{-dL} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.loop} to
+the input file name.
+
+@item
+If @samp{-frerun-cse-after-loop} was enabled, a second common
+subexpression elimination pass is performed after the loop optimization
+pass. Jump threading is also done again at this time if it was specified.
+
+The option @samp{-dt} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.cse2} to
+the input file name.
+
+@cindex register allocation, stupid
+@cindex stupid register allocation
+@item
+Stupid register allocation is performed at this point in a
+nonoptimizing compilation. It does a little data flow analysis as
+well. When stupid register allocation is in use, the next pass
+executed is the reloading pass; the others in between are skipped.
+The source file is @file{stupid.c}.
+
+@cindex data flow analysis
+@cindex analysis, data flow
+@cindex basic blocks
+@item
+Data flow analysis (@file{flow.c}). This pass divides the program
+into basic blocks (and in the process deletes unreachable loops); then
+it computes which pseudo-registers are live at each point in the
+program, and makes the first instruction that uses a value point at
+the instruction that computed the value.
+
+@cindex autoincrement/decrement analysis
+This pass also deletes computations whose results are never used, and
+combines memory references with add or subtract instructions to make
+autoincrement or autodecrement addressing.
+
+The option @samp{-df} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.flow} to
+the input file name. If stupid register allocation is in use, this
+dump file reflects the full results of such allocation.
+
+@cindex instruction combination
+@item
+Instruction combination (@file{combine.c}). This pass attempts to
+combine groups of two or three instructions that are related by data
+flow into single instructions. It combines the RTL expressions for
+the instructions by substitution, simplifies the result using algebra,
+and then attempts to match the result against the machine description.
+
+The option @samp{-dc} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.combine}
+to the input file name.
+
+@cindex instruction scheduling
+@cindex scheduling, instruction
+@item
+Instruction scheduling (@file{sched.c}). This pass looks for
+instructions whose output will not be available by the time that it is
+used in subsequent instructions. (Memory loads and floating point
+instructions often have this behavior on RISC machines). It re-orders
+instructions within a basic block to try to separate the definition and
+use of items that otherwise would cause pipeline stalls.
+
+Instruction scheduling is performed twice. The first time is immediately
+after instruction combination and the second is immediately after reload.
+
+The option @samp{-dS} causes a debugging dump of the RTL code after this
+pass is run for the first time. The dump file's name is made by
+appending @samp{.sched} to the input file name.
+
+@cindex register class preference pass
+@item
+Register class preferencing. The RTL code is scanned to find out
+which register class is best for each pseudo register. The source
+file is @file{regclass.c}.
+
+@cindex register allocation
+@cindex local register allocation
+@item
+Local register allocation (@file{local-alloc.c}). This pass allocates
+hard registers to pseudo registers that are used only within one basic
+block. Because the basic block is linear, it can use fast and
+powerful techniques to do a very good job.
+
+The option @samp{-dl} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.lreg} to
+the input file name.
+
+@cindex global register allocation
+@item
+Global register allocation (@file{global.c}). This pass
+allocates hard registers for the remaining pseudo registers (those
+whose life spans are not contained in one basic block).
+
+@cindex reloading
+@item
+Reloading. This pass renumbers pseudo registers with the hardware
+registers numbers they were allocated. Pseudo registers that did not
+get hard registers are replaced with stack slots. Then it finds
+instructions that are invalid because a value has failed to end up in
+a register, or has ended up in a register of the wrong kind. It fixes
+up these instructions by reloading the problematical values
+temporarily into registers. Additional instructions are generated to
+do the copying.
+
+The reload pass also optionally eliminates the frame pointer and inserts
+instructions to save and restore call-clobbered registers around calls.
+
+Source files are @file{reload.c} and @file{reload1.c}, plus the header
+@file{reload.h} used for communication between them.
+
+The option @samp{-dg} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.greg} to
+the input file name.
+
+@cindex instruction scheduling
+@cindex scheduling, instruction
+@item
+Instruction scheduling is repeated here to try to avoid pipeline stalls
+due to memory loads generated for spilled pseudo registers.
+
+The option @samp{-dR} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.sched2}
+to the input file name.
+
+@cindex cross-jumping
+@cindex no-op move instructions
+@item
+Jump optimization is repeated, this time including cross-jumping
+and deletion of no-op move instructions.
+
+The option @samp{-dJ} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.jump2}
+to the input file name.
+
+@cindex delayed branch scheduling
+@cindex scheduling, delayed branch
+@item
+Delayed branch scheduling. This optional pass attempts to find
+instructions that can go into the delay slots of other instructions,
+usually jumps and calls. The source file name is @file{reorg.c}.
+
+The option @samp{-dd} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.dbr}
+to the input file name.
+
+@cindex register-to-stack conversion
+@item
+Conversion from usage of some hard registers to usage of a register
+stack may be done at this point. Currently, this is supported only
+for the floating-point registers of the Intel 80387 coprocessor. The
+source file name is @file{reg-stack.c}.
+
+The options @samp{-dk} causes a debugging dump of the RTL code after
+this pass. This dump file's name is made by appending @samp{.stack}
+to the input file name.
+
+@cindex final pass
+@cindex peephole optimization
+@item
+Final. This pass outputs the assembler code for the function. It is
+also responsible for identifying spurious test and compare
+instructions. Machine-specific peephole optimizations are performed
+at the same time. The function entry and exit sequences are generated
+directly as assembler code in this pass; they never exist as RTL.
+
+The source files are @file{final.c} plus @file{insn-output.c}; the
+latter is generated automatically from the machine description by the
+tool @file{genoutput}. The header file @file{conditions.h} is used
+for communication between these files.
+
+@cindex debugging information generation
+@item
+Debugging information output. This is run after final because it must
+output the stack slot offsets for pseudo registers that did not get
+hard registers. Source files are @file{dbxout.c} for DBX symbol table
+format, @file{sdbout.c} for SDB symbol table format, and
+@file{dwarfout.c} for DWARF symbol table format.
+@end itemize
+
+Some additional files are used by all or many passes:
+
+@itemize @bullet
+@item
+Every pass uses @file{machmode.def} and @file{machmode.h} which define
+the machine modes.
+
+@item
+Several passes use @file{real.h}, which defines the default
+representation of floating point constants and how to operate on them.
+
+@item
+All the passes that work with RTL use the header files @file{rtl.h}
+and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools
+@code{gen*} also use these files to read and work with the machine
+description RTL.
+
+@findex genconfig
+@item
+Several passes refer to the header file @file{insn-config.h} which
+contains a few parameters (C macro definitions) generated
+automatically from the machine description RTL by the tool
+@code{genconfig}.
+
+@cindex instruction recognizer
+@item
+Several passes use the instruction recognizer, which consists of
+@file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c}
+and @file{insn-extract.c} that are generated automatically from the
+machine description by the tools @file{genrecog} and
+@file{genextract}.@refill
+
+@item
+Several passes use the header files @file{regs.h} which defines the
+information recorded about pseudo register usage, and @file{basic-block.h}
+which defines the information recorded about basic blocks.
+
+@item
+@file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector
+with a bit for each hard register, and some macros to manipulate it.
+This type is just @code{int} if the machine has few enough hard registers;
+otherwise it is an array of @code{int} and some of the macros expand
+into loops.
+
+@item
+Several passes use instruction attributes. A definition of the
+attributes defined for a particular machine is in file
+@file{insn-attr.h}, which is generated from the machine description by
+the program @file{genattr}. The file @file{insn-attrtab.c} contains
+subroutines to obtain the attribute values for insns. It is generated
+from the machine description by the program @file{genattrtab}.@refill
+@end itemize
+@end ifset
+
+@ifset INTERNALS
+@include rtl.texi
+@include md.texi
+@include tm.texi
+@end ifset
+
+@ifset INTERNALS
+@node Config
+@chapter The Configuration File
+@cindex configuration file
+@cindex @file{xm-@var{machine}.h}
+
+The configuration file @file{xm-@var{machine}.h} contains macro
+definitions that describe the machine and system on which the compiler
+is running, unlike the definitions in @file{@var{machine}.h}, which
+describe the machine for which the compiler is producing output. Most
+of the values in @file{xm-@var{machine}.h} are actually the same on all
+machines that GNU CC runs on, so large parts of all configuration files
+are identical. But there are some macros that vary:
+
+@table @code
+@findex USG
+@item USG
+Define this macro if the host system is System V.
+
+@findex VMS
+@item VMS
+Define this macro if the host system is VMS.
+
+@findex FATAL_EXIT_CODE
+@item FATAL_EXIT_CODE
+A C expression for the status code to be returned when the compiler
+exits after serious errors.
+
+@findex SUCCESS_EXIT_CODE
+@item SUCCESS_EXIT_CODE
+A C expression for the status code to be returned when the compiler
+exits without serious errors.
+
+@findex HOST_WORDS_BIG_ENDIAN
+@item HOST_WORDS_BIG_ENDIAN
+Defined if the host machine stores words of multi-word values in
+big-endian order. (GNU CC does not depend on the host byte ordering
+within a word.)
+
+@findex HOST_FLOAT_WORDS_BIG_ENDIAN
+@item HOST_FLOAT_WORDS_BIG_ENDIAN
+Define this macro to be 1 if the host machine stores @code{DFmode},
+@code{XFmode} or @code{TFmode} floating point numbers in memory with the
+word containing the sign bit at the lowest address; otherwise, define it
+to be zero.
+
+This macro need not be defined if the ordering is the same as for
+multi-word integers.
+
+@findex HOST_FLOAT_FORMAT
+@item HOST_FLOAT_FORMAT
+A numeric code distinguishing the floating point format for the host
+machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the
+alternatives and default.
+
+@findex HOST_BITS_PER_CHAR
+@item HOST_BITS_PER_CHAR
+A C expression for the number of bits in @code{char} on the host
+machine.
+
+@findex HOST_BITS_PER_SHORT
+@item HOST_BITS_PER_SHORT
+A C expression for the number of bits in @code{short} on the host
+machine.
+
+@findex HOST_BITS_PER_INT
+@item HOST_BITS_PER_INT
+A C expression for the number of bits in @code{int} on the host
+machine.
+
+@findex HOST_BITS_PER_LONG
+@item HOST_BITS_PER_LONG
+A C expression for the number of bits in @code{long} on the host
+machine.
+
+@findex ONLY_INT_FIELDS
+@item ONLY_INT_FIELDS
+Define this macro to indicate that the host compiler only supports
+@code{int} bit fields, rather than other integral types, including
+@code{enum}, as do most C compilers.
+
+@findex OBSTACK_CHUNK_SIZE
+@item OBSTACK_CHUNK_SIZE
+A C expression for the size of ordinary obstack chunks.
+If you don't define this, a usually-reasonable default is used.
+
+@findex OBSTACK_CHUNK_ALLOC
+@item OBSTACK_CHUNK_ALLOC
+The function used to allocate obstack chunks.
+If you don't define this, @code{xmalloc} is used.
+
+@findex OBSTACK_CHUNK_FREE
+@item OBSTACK_CHUNK_FREE
+The function used to free obstack chunks.
+If you don't define this, @code{free} is used.
+
+@findex USE_C_ALLOCA
+@item USE_C_ALLOCA
+Define this macro to indicate that the compiler is running with the
+@code{alloca} implemented in C. This version of @code{alloca} can be
+found in the file @file{alloca.c}; to use it, you must also alter the
+@file{Makefile} variable @code{ALLOCA}. (This is done automatically
+for the systems on which we know it is needed.)
+
+If you do define this macro, you should probably do it as follows:
+
+@example
+#ifndef __GNUC__
+#define USE_C_ALLOCA
+#else
+#define alloca __builtin_alloca
+#endif
+@end example
+
+@noindent
+so that when the compiler is compiled with GNU CC it uses the more
+efficient built-in @code{alloca} function.
+
+@item FUNCTION_CONVERSION_BUG
+@findex FUNCTION_CONVERSION_BUG
+Define this macro to indicate that the host compiler does not properly
+handle converting a function value to a pointer-to-function when it is
+used in an expression.
+
+@findex HAVE_VPRINTF
+@findex vprintf
+@item HAVE_VPRINTF
+Define this if the library function @code{vprintf} is available on your
+system.
+
+@findex MULTIBYTE_CHARS
+@item MULTIBYTE_CHARS
+Define this macro to enable support for multibyte characters in the
+input to GNU CC. This requires that the host system support the ANSI C
+library functions for converting multibyte characters to wide
+characters.
+
+@findex HAVE_PUTENV
+@findex putenv
+@item HAVE_PUTENV
+Define this if the library function @code{putenv} is available on your
+system.
+
+@findex POSIX
+@item POSIX
+Define this if your system is POSIX.1 compliant.
+
+@findex NO_SYS_SIGLIST
+@item NO_SYS_SIGLIST
+Define this if your system @emph{does not} provide the variable
+@code{sys_siglist}.
+
+@findex DONT_DECLARE_SYS_SIGLIST
+@item DONT_DECLARE_SYS_SIGLIST
+Define this if your system has the variable @code{sys_siglist}, and
+there is already a declaration of it in the system header files.
+
+@findex USE_PROTOTYPES
+@item USE_PROTOTYPES
+Define this to be 1 if you know that the host compiler supports
+prototypes, even if it doesn't define __STDC__, or define
+it to be 0 if you do not want any prototypes used in compiling
+GNU CC. If @samp{USE_PROTOTYPES} is not defined, it will be
+determined automatically whether your compiler supports
+prototypes by checking if @samp{__STDC__} is defined.
+
+@findex NO_MD_PROTOTYPES
+@item NO_MD_PROTOTYPES
+Define this if you wish suppression of prototypes generated from
+the machine description file, but to use other prototypes within
+GNU CC. If @samp{USE_PROTOTYPES} is defined to be 0, or the
+host compiler does not support prototypes, this macro has no
+effect.
+
+@findex MD_CALL_PROTOTYPES
+@item MD_CALL_PROTOTYPES
+Define this if you wish to generate prototypes for the
+@code{gen_call} or @code{gen_call_value} functions generated from
+the machine description file. If @samp{USE_PROTOTYPES} is
+defined to be 0, or the host compiler does not support
+prototypes, or @samp{NO_MD_PROTOTYPES} is defined, this macro has
+no effect. As soon as all of the machine descriptions are
+modified to have the appropriate number of arguments, this macro
+will be removed.
+
+@vindex sys_siglist
+Some systems do provide this variable, but with a different name such
+as @code{_sys_siglist}. On these systems, you can define
+@code{sys_siglist} as a macro which expands into the name actually
+provided.
+
+@findex NO_STAB_H
+@item NO_STAB_H
+Define this if your system does not have the include file
+@file{stab.h}. If @samp{USG} is defined, @samp{NO_STAB_H} is
+assumed.
+
+@findex PATH_SEPARATOR
+@item PATH_SEPARATOR
+Define this macro to be a C character constant representing the
+character used to separate components in paths. The default value is.
+the colon character
+
+@findex DIR_SEPARATOR
+@item DIR_SEPARATOR
+If your system uses some character other than slash to separate
+directory names within a file specification, define this macro to be a C
+character constant specifying that character. When GNU CC displays file
+names, the character you specify will be used. GNU CC will test for
+both slash and the character you specify when parsing filenames.
+
+@findex OBJECT_SUFFIX
+@item OBJECT_SUFFIX
+Define this macro to be a C string representing the suffix for object
+files on your machine. If you do not define this macro, GNU CC will use
+@samp{.o} as the suffix for object files.
+
+@findex EXECUTABLE_SUFFIX
+@item EXECUTABLE_SUFFIX
+Define this macro to be a C string representing the suffix for executable
+files on your machine. If you do not define this macro, GNU CC will use
+the null string as the suffix for object files.
+
+@findex COLLECT_EXPORT_LIST
+@item COLLECT_EXPORT_LIST
+If defined, @code{collect2} will scan the individual object files
+specified on its command line and create an export list for the linker.
+Define this macro for systems like AIX, where the linker discards
+object files that are not referenced from @code{main} and uses export
+lists.
+@end table
+
+@findex bzero
+@findex bcmp
+In addition, configuration files for system V define @code{bcopy},
+@code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca}
+as a macro when compiled with GNU CC, in order to take advantage of the
+benefit of GNU CC's built-in @code{alloca}.
+
+@node Fragments
+@chapter Makefile Fragments
+@cindex makefile fragment
+
+When you configure GNU CC using the @file{configure} script
+(@pxref{Installation}), it will construct the file @file{Makefile} from
+the template file @file{Makefile.in}. When it does this, it will
+incorporate makefile fragment files from the @file{config} directory,
+named @file{t-@var{target}} and @file{x-@var{host}}. If these files do
+not exist, it means nothing needs to be added for a given target or
+host.
+
+@menu
+* Target Fragment:: Writing the @file{t-@var{target}} file.
+* Host Fragment:: Writing the @file{x-@var{host}} file.
+@end menu
+
+@node Target Fragment
+@section The Target Makefile Fragment
+@cindex target makefile fragment
+@cindex @file{t-@var{target}}
+
+The target makefile fragment, @file{t-@var{target}}, defines special
+target dependent variables and targets used in the @file{Makefile}:
+
+@table @code
+@findex LIBGCC1
+@item LIBGCC1
+The rule to use to build @file{libgcc1.a}.
+If your target does not need to use the functions in @file{libgcc1.a},
+set this to empty.
+@xref{Interface}.
+
+@findex CROSS_LIBGCC1
+@item CROSS_LIBGCC1
+The rule to use to build @file{libgcc1.a} when building a cross
+compiler. If your target does not need to use the functions in
+@file{libgcc1.a}, set this to empty. @xref{Cross Runtime}.
+
+@findex LIBGCC2_CFLAGS
+@item LIBGCC2_CFLAGS
+Compiler flags to use when compiling @file{libgcc2.c}.
+
+@findex LIB2FUNCS_EXTRA
+@item LIB2FUNCS_EXTRA
+A list of source file names to be compiled or assembled and inserted
+into @file{libgcc.a}.
+
+@findex CRTSTUFF_T_CFLAGS
+@item CRTSTUFF_T_CFLAGS
+Special flags used when compiling @file{crtstuff.c}.
+@xref{Initialization}.
+
+@findex MULTILIB_OPTIONS
+@item MULTILIB_OPTIONS
+For some targets, invoking GNU CC in different ways produces objects
+that can not be linked together. For example, for some targets GNU CC
+produces both big and little endian code. For these targets, you must
+arrange for multiple versions of @file{libgcc.a} to be compiled, one for
+each set of incompatible options. When GNU CC invokes the linker, it
+arranges to link in the right version of @file{libgcc.a}, based on
+the command line options used.
+
+The @code{MULTILIB_OPTIONS} macro lists the set of options for which
+special versions of @file{libgcc.a} must be built. Write options that
+are mutually incompatible side by side, separated by a slash. Write
+options that may be used together separated by a space. The build
+procedure will build all combinations of compatible options.
+
+For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020
+msoft-float}, @file{Makefile} will build special versions of
+@file{libgcc.a} using the options @samp{-m68000}, @samp{-m68020},
+@samp{-msoft-float}, @samp{-m68000 -msoft-float}, and @samp{-m68020
+-msoft-float}.
+
+@findex MULTILIB_DIRNAMES
+@item MULTILIB_DIRNAMES
+If @code{MULTILIB_OPTIONS} is used, this variable specifies the
+directory names that should be used to hold the various libraries.
+Write one element in @code{MULTILIB_DIRNAMES} for each element in
+@code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the
+default value will be @code{MULTILIB_OPTIONS}, with all slashes treated
+as spaces.
+
+For example, if @code{MULTILIB_OPTIONS} is @samp{m68000/m68020
+msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is
+@samp{m68000 m68020 msoft-float}. You may specify a different value if
+you desire a different set of directory names.
+
+@findex MULTILIB_MATCHES
+@item MULTILIB_MATCHES
+Sometimes the same option may be written in two different ways. If an
+option is listed in @code{MULTILIB_OPTIONS}, GNU CC needs to know about
+any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of
+items of the form @samp{option=option} to describe all relevant
+synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}.
+@end table
+
+@node Host Fragment
+@section The Host Makefile Fragment
+@cindex host makefile fragment
+@cindex @file{x-@var{host}}
+
+The host makefile fragment, @file{x-@var{host}}, defines special host
+dependent variables and targets used in the @file{Makefile}:
+
+@table @code
+@findex CC
+@item CC
+The compiler to use when building the first stage.
+
+@findex CLIB
+@item CLIB
+Additional host libraries to link with.
+
+@findex OLDCC
+@item OLDCC
+The compiler to use when building @file{libgcc1.a} for a native
+compilation.
+
+@findex OLDAR
+@item OLDAR
+The version of @code{ar} to use when building @file{libgcc1.a} for a native
+compilation.
+
+@findex INSTALL
+@item INSTALL
+The install program to use.
+@end table
+
+@node Index
+@unnumbered Index
+@end ifset
+
+@ifclear INTERNALS
+@node Index
+@unnumbered Index
+@end ifclear
+
+@printindex cp
+@summarycontents
+@contents
+@bye
OpenPOWER on IntegriCloud