diff options
Diffstat (limited to 'gnu/usr.bin/cc/doc/gcc.texi')
| -rw-r--r-- | gnu/usr.bin/cc/doc/gcc.texi | 4525 |
1 files changed, 0 insertions, 4525 deletions
diff --git a/gnu/usr.bin/cc/doc/gcc.texi b/gnu/usr.bin/cc/doc/gcc.texi deleted file mode 100644 index 3523ae5..0000000 --- a/gnu/usr.bin/cc/doc/gcc.texi +++ /dev/null @@ -1,4525 +0,0 @@ -\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 somesuch. -@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 -675 Massachusetts Avenue -Cambridge, MA 02139 USA - -Copyright (C) 1988, 1989, 1992, 1993, 1994 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 19 September 1994 -@sp 1 -@c The version number appears twice more in this file. - -@center for version 2.6 -@c @center (preliminary draft, which will change) -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1988, 89, 92, 93, 1994 Free Software Foundation, Inc. -@sp 2 -For GCC Version 2.6.@* -@c Printed November, 1994.@* - -@c ISBN 1-882114-35-3 -@sp 1 -Published by the Free Software Foundation @* -675 Massachusetts Avenue @* -Cambridge, MA 02139 USA -@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.6. -@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.6. -@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.6. -@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. -@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. -675 Mass Ave, Cambridge, MA 02139, 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., 675 Mass Ave, Cambridge, MA 02139, 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 the Vomit-Making System (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 of the Swedish Institute of Computer Science -implemented multiply-by-constant optimization and better 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. -@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 and Lotus 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. Lotus has won lawsuits against two -small companies, which were thus put out of business. Then they sued -Borland; this case is now before the court of appeals. Apple's lawsuit -against HP and Microsoft is also being decided by an appeals court. -Widespread rumors that Apple had lost the case are untrue; as of July -1994, the final outcome is unknown. - -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 Borland's appeal against Lotus fails. - -@item -Open Computing magazine reported a Microsoft vice president as threatening -to sue people who copy 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 issue, as is being done -here, and filing friend-of-the-court briefs on behalf of defendants sued -by monopolists. Recently the League filed a friend-of-the-court brief -for Borland in its appeal against Lotus. - -The League's membership rolls include 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. 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 or 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 this issue. - -@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. -* 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 eumulator uses an -obsolete and incompatible format. Long doubles do not work in Sun OS -versions 4.1.1 to 4.1.3 because of emululator bugs that cause random -unpredicatable failures. 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 -For some very large functions you may receive errors from the HP linker -complaining about an out of bounds unconditional branch offset. Fixing -this problem correctly requires fixing problems in GNU CC and GAS. We -hope to fix this in time for GNU CC 2.6. Until then you can work around -by making your function smaller, and if you are using GAS, splitting the -function into multiple source files may be necessary. - -@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 ilbrary. 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.6.0 -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 preprocessor 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 -preprocessor 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 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-conformant, 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 preprocessor 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{3, 4}, or it might get @samp{4, 3}, or even @samp{3, 3}. - -@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 -gratuituously 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 -675 Mass Ave -Cambridge, MA 02139 -@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. - -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. When you send your changes, please -follow these guidelines to avoid causing extra work for us in studying -the patches. - -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 FAILURE_EXIT_CODE -@item FAILURE_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 EXECUTABLE_SUFFIX -@item EXECUTABLE_SUFFIX -Define this macro if the host system uses a naming convention for -executable files that involves a common suffix (such as, in some -systems, @samp{.exe}) that must be mentioned explicitly when you run -the program. - -@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 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. -@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 Index -@unnumbered Index -@end ifset - -@ifclear INTERNALS -@node Index -@unnumbered Index -@end ifclear - -@printindex cp -@summarycontents -@contents -@bye |
