OSDN Git Service

gcc:
[pf3gnuchains/gcc-fork.git] / gcc / gcc.texi
1 \input texinfo  @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename gcc.info
4 @c @setfilename usegcc.info
5 @c @setfilename portgcc.info
6 @c To produce the full manual, use the "gcc.info" setfilename, and
7 @c make sure the following do NOT begin with '@c' (and the @clear lines DO)
8 @set INTERNALS
9 @set USING
10 @c To produce a user-only manual, use the "usegcc.info" setfilename, and
11 @c make sure the following does NOT begin with '@c':
12 @c @clear INTERNALS
13 @c To produce a porter-only manual, use the "portgcc.info" setfilename,
14 @c and make sure the following does NOT begin with '@c':
15 @c @clear USING
16
17 @c (For FSF printing, turn on smallbook, comment out finalout below;
18 @c that is all that is needed.)
19
20 @c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition.
21 @c @smallbook
22
23 @c i also commented out the finalout command, so if there *are* any
24 @c overfulls, you'll (hopefully) see the rectangle in the right hand
25 @c margin. -mew 15june93
26 @c @finalout
27
28 @c NOTE: checks/things to do:
29 @c
30 @c -have bob do a search in all seven files for "mew" (ideally --mew,
31 @c  but i may have forgotten the occasional "--"..).  
32 @c     Just checked... all have `--'!  Bob 22Jul96
33 @c     Use this to search:   grep -n '\-\-mew' *.texi
34 @c -item/itemx, text after all (sub/sub)section titles, etc..
35 @c -consider putting the lists of options on pp 17--> etc in columns or
36 @c  some such.
37 @c -spellcheck
38 @c -continuity of phrasing; ie, bit-field vs bitfield in rtl.texi
39 @c -overfulls.  do a search for "mew" in the files, and you will see
40 @c   overfulls that i noted but could not deal with.
41 @c -have to add text:  beginning of chapter 8
42
43 @c
44 @c anything else?                       --mew 10feb93
45
46 @macro gcctabopt{body}
47 @code{\body\}
48 @end macro
49
50 @ifset INTERNALS
51 @ifset USING
52 @settitle Using and Porting the GNU Compiler Collection (GCC)
53 @end ifset
54 @end ifset
55 @c seems reasonable to assume at least one of INTERNALS or USING is set...
56 @ifclear INTERNALS
57 @settitle Using the GNU Compiler Collection
58 @end ifclear
59 @ifclear USING
60 @settitle Porting the GNU Compiler Collection
61 @end ifclear
62
63 @syncodeindex fn cp
64 @syncodeindex vr cp
65 @c %**end of header
66
67 @c Use with @@smallbook.
68
69 @c Cause even numbered pages to be printed on the left hand side of
70 @c the page and odd numbered pages to be printed on the right hand
71 @c side of the page.  Using this, you can print on both sides of a
72 @c sheet of paper and have the text on the same part of the sheet.
73
74 @c The text on right hand pages is pushed towards the right hand
75 @c margin and the text on left hand pages is pushed toward the left
76 @c hand margin.
77 @c (To provide the reverse effect, set bindingoffset to -0.75in.)
78
79 @c @tex
80 @c \global\bindingoffset=0.75in
81 @c \global\normaloffset =0.75in
82 @c @end tex
83
84 @ifnottex
85 @dircategory Programming
86 @direntry
87 * gcc: (gcc).                  The GNU Compiler Collection.
88 @end direntry
89 @ifset INTERNALS
90 @ifset USING
91 This file documents the use and the internals of the GNU compiler.
92 @end ifset
93 @end ifset
94 @ifclear USING
95 This file documents the internals of the GNU compiler.
96 @end ifclear
97 @ifclear INTERNALS
98 This file documents the use of the GNU compiler.
99 @end ifclear
100 @sp 1
101 Published by the Free Software Foundation@*
102 59 Temple Place - Suite 330@*
103 Boston, MA 02111-1307 USA
104 @sp 1
105 @c When you update the list of years below, search for copyright{} and
106 @c update the other copy too.
107 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
108 1999, 2000, 2001 Free Software Foundation, Inc.
109 @sp 1
110 Permission is granted to make and distribute verbatim copies of
111 this manual provided the copyright notice and this permission notice
112 are preserved on all copies.
113 @sp 1
114 @ignore
115 Permission is granted to process this file through Tex and print the
116 results, provided the printed document carries copying permission
117 notice identical to this one except for the removal of this paragraph
118 (this paragraph not being relevant to the printed manual).
119
120 @end ignore
121 Permission is granted to copy and distribute modified versions of this
122 manual under the conditions for verbatim copying, provided also that the
123 sections entitled ``GNU General Public License'' and ``Funding for Free
124 Software'' are included exactly as in the original, and provided that 
125 the entire resulting derived work is distributed under the terms of a 
126 permission notice identical to this one.
127 @sp 1
128 Permission is granted to copy and distribute translations of this manual
129 into another language, under the above conditions for modified versions,
130 except that the sections entitled ``GNU General Public License'' and
131 ``Funding for Free Software'', and this permission notice, may be 
132 included in translations approved by the Free Software Foundation 
133 instead of in the original English.
134 @end ifnottex
135
136 @setchapternewpage odd
137 @c @finalout
138 @titlepage
139 @ifset INTERNALS
140 @ifset USING
141 @center @titlefont{Using and Porting the GNU Compiler Collection}
142
143 @end ifset
144 @end ifset
145 @ifclear INTERNALS
146 @title Using the GNU Compiler Collection
147 @end ifclear
148 @ifclear USING
149 @title Porting the GNU Compiler Collection
150 @end ifclear
151 @sp 2
152 @center Richard M. Stallman
153 @sp 3
154 @center Last updated 20 December 2000
155 @sp 1
156 @c The version number appears five times more in this file.
157
158 @center for gcc-2.97
159 @page
160 @vskip 0pt plus 1filll
161 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
162 1999, 2000, 2001  Free Software Foundation, Inc.
163 @sp 2
164 For GCC Version 2.97@*
165 @sp 1
166 Published by the Free Software Foundation @*
167 59 Temple Place - Suite 330@*
168 Boston, MA 02111-1307, USA@*
169 Last printed April, 1998.@*
170 Printed copies are available for $50 each.@*
171 ISBN 1-882114-37-X
172 @sp 1
173 Permission is granted to make and distribute verbatim copies of
174 this manual provided the copyright notice and this permission notice
175 are preserved on all copies.
176
177 Permission is granted to copy and distribute modified versions of this
178 manual under the conditions for verbatim copying, provided also that the
179 sections entitled ``GNU General Public License'' and ``Funding for Free
180 Software'' are included exactly as in the original, and provided that 
181 the entire resulting derived work is distributed under the terms of a 
182 permission notice identical to this one.
183
184 Permission is granted to copy and distribute translations of this manual
185 into another language, under the above conditions for modified versions,
186 except that the sections entitled ``GNU General Public License'' and
187 ``Funding for Free Software'', and this permission notice, may be 
188 included in translations approved by the Free Software Foundation 
189 instead of in the original English.
190 @end titlepage
191 @page
192
193 @node Top, G++ and GCC,, (DIR)
194 @top Introduction
195 @cindex introduction
196
197 @ifset INTERNALS
198 @ifset USING
199 This manual documents how to run, install and port the GNU
200 compiler, as well as its new features and incompatibilities, and how to
201 report bugs.  It corresponds to GCC version 2.97.
202 @end ifset
203 @end ifset
204
205 @ifclear INTERNALS
206 This manual documents how to run and install the GNU compiler,
207 as well as its new features and incompatibilities, and how to report
208 bugs.  It corresponds to GCC version 2.97.
209 @end ifclear
210 @ifclear USING
211 This manual documents how to port the GNU compiler,
212 as well as its new features and incompatibilities, and how to report
213 bugs.  It corresponds to GCC version 2.97.
214 @end ifclear
215
216 @menu
217 @ifset USING
218 * G++ and GCC::     You can compile C or C++ programs.
219 * Standards::       Language standards supported by GCC.
220 * Invoking GCC::    Command options supported by @samp{gcc}.
221 * Installation::    How to configure, compile and install GCC.
222 * C Extensions::    GNU extensions to the C language family.
223 * C++ Extensions::  GNU extensions to the C++ language.
224 * Gcov::            gcov: a GCC test coverage program.
225 * Trouble::         If you have trouble installing GCC.
226 * Bugs::            How, why and where to report bugs.
227 * Service::         How to find suppliers of support for GCC.
228 * Contributing::    How to contribute to testing and developing GCC.
229 * VMS::             Using GCC on VMS.
230 @end ifset
231 @ifset INTERNALS
232 * Portability::     Goals of GCC's portability features.
233 * Interface::       Function-call interface of GCC output.
234 * Passes::          Order of passes, what they do, and what each file is for.
235 * RTL::             The intermediate representation that most passes work on.
236 * Machine Desc::    How to write machine description instruction patterns.
237 * Target Macros::   How to write the machine description C macros.
238 * Config::          Writing the @file{xm-@var{machine}.h} file.
239 * Fragments::       Writing the @file{t-@var{target}} and @file{x-@var{host}} files.
240 @end ifset
241
242 * Funding::         How to help assure funding for free software.
243 * GNU/Linux::       Linux and the GNU Project
244
245 * Copying::         GNU General Public License says
246                      how you can copy and share GCC.
247 * Contributors::    People who have contributed to GCC.
248
249 * Index::           Index of concepts and symbol names.
250 @end menu
251
252 @ifset USING
253 @node G++ and GCC
254 @chapter Compile C, C++, Objective C, Fortran, Java or CHILL
255
256 @cindex Objective C
257 Several versions of the compiler (C, C++, Objective C, Fortran, Java
258 and CHILL) are integrated; this is why we use the name 
259 ``GNU Compiler Collection''. GCC can compile programs written in any of these
260 languages. The Fortran and CHILL compilers are described in 
261 separate manuals. The Java compiler currently has no manual documenting it.
262
263 @cindex GCC
264 ``GCC'' is a common shorthand term for the GNU Compiler Collection.  This is both
265 the most general name for the compiler, and the name used when the
266 emphasis is on compiling C programs (as the abbreviation formerly
267 stood for ``GNU C Compiler'').
268
269 @cindex C++
270 @cindex G++
271 When referring to C++ compilation, it is usual to call the compiler
272 ``G++''.  Since there is only one compiler, it is also accurate to call
273 it ``GCC'' no matter what the language context; however, the term
274 ``G++'' is more useful when the emphasis is on compiling C++ programs.
275
276 We use the name ``GCC'' to refer to the compilation system as a
277 whole, and more specifically to the language-independent part of the
278 compiler.  For example, we refer to the optimization options as
279 affecting the behavior of ``GCC'' or sometimes just ``the compiler''.
280
281 Front ends for other languages, such as Ada 95 and Pascal exist but
282 have not yet been integrated into GCC. These front-ends, like that for C++, 
283 are built in subdirectories of GCC and link to it.  The result is an
284 integrated compiler that can compile programs written in C, C++,
285 Objective C, or any of the languages for which you have installed front
286 ends.
287
288 In this manual, we only discuss the options for the C, Objective-C, and
289 C++ compilers and those of the GCC core.  Consult the documentation
290 of the other front ends for the options to use when compiling programs
291 written in other languages.
292
293 @cindex compiler compared to C++ preprocessor
294 @cindex intermediate C version, nonexistent
295 @cindex C intermediate output, nonexistent
296 G++ is a @emph{compiler}, not merely a preprocessor.  G++ builds object
297 code directly from your C++ program source.  There is no intermediate C
298 version of the program.  (By contrast, for example, some other
299 implementations use a program that generates a C program from your C++
300 source.)  Avoiding an intermediate C representation of the program means
301 that you get better object code, and better debugging information.  The
302 GNU debugger, GDB, works with this information in the object code to
303 give you comprehensive C++ source-level editing capabilities
304 (@pxref{C,,C and C++,gdb.info, Debugging with GDB}).
305
306 @c FIXME!  Someone who knows something about Objective C ought to put in
307 @c a paragraph or two about it here, and move the index entry down when
308 @c there is more to point to than the general mention in the 1st par.
309
310 @node Standards
311 @chapter Language Standards Supported by GCC
312 @cindex C standard
313 @cindex C standards
314 @cindex ANSI C standard
315 @cindex ANSI C
316 @cindex ANSI C89
317 @cindex C89
318 @cindex ANSI X3.159-1989
319 @cindex X3.159-1989
320 @cindex ISO C standard
321 @cindex ISO C
322 @cindex ISO C89
323 @cindex ISO C90
324 @cindex ISO/IEC 9899
325 @cindex ISO 9899
326 @cindex C90
327 @cindex ISO C94
328 @cindex C94
329 @cindex ISO C95
330 @cindex C95
331 @cindex ISO C99
332 @cindex C99
333 @cindex ISO C9X
334 @cindex C9X
335 @cindex Technical Corrigenda
336 @cindex TC1
337 @cindex Technical Corrigendum 1
338 @cindex TC2
339 @cindex Technical Corrigendum 2
340 @cindex AMD1
341 @cindex freestanding implementation
342 @cindex freestanding environment
343 @cindex hosted implementation
344 @cindex hosted environment
345 @findex __STDC_HOSTED__
346
347 For each language compiled by GCC for which there is a standard, GCC
348 attempts to follow one or more versions of that standard, possibly
349 with some exceptions, and possibly with some extensions.
350
351 GCC supports three versions of the C standard, although support for
352 the most recent version is not yet complete.
353
354 The original ANSI C standard (X3.159-1989) was ratified in 1989 and
355 published in 1990.  This standard was ratified as an ISO standard
356 (ISO/IEC 9899:1990) later in 1990.  There were no technical
357 differences between these publications, although the sections of the
358 ANSI standard were renumbered and became clauses in the ISO standard.
359 This standard, in both its forms, is commonly known as @dfn{C89}, or
360 occasionally as @dfn{C90}, from the dates of ratification.  The ANSI
361 standard, but not the ISO standard, also came with a Rationale
362 document.  To select this standard in GCC, use one of the options
363 @samp{-ansi}, @samp{-std=c89} or @samp{-std=iso9899:1990}; to obtain
364 all the diagnostics required by the standard, you should also specify
365 @samp{-pedantic} (or @samp{-pedantic-errors} if you want them to be
366 errors rather than warnings).  @xref{C Dialect Options,,Options
367 Controlling C Dialect}.
368
369 Errors in the 1990 ISO C standard were corrected in two Technical
370 Corrigenda published in 1994 and 1996.  GCC does not support the
371 uncorrected version.
372
373 An amendment to the 1990 standard was published in 1995.  This
374 amendment added digraphs and @code{__STDC_VERSION__} to the language,
375 but otherwise concerned the library.  This amendment is commonly known
376 as @dfn{AMD1}; the amended standard is sometimes known as @dfn{C94} or
377 @dfn{C95}.  To select this standard in GCC, use the option
378 @samp{-std=iso9899:199409} (with, as for other standard versions,
379 @samp{-pedantic} to receive all required diagnostics).
380
381 A new edition of the ISO C standard was published in 1999 as ISO/IEC
382 9899:1999, and is commonly known as @dfn{C99}.  GCC has incomplete
383 support for this standard version; see
384 @uref{http://gcc.gnu.org/c99status.html} for details.  To select this
385 standard, use @samp{-std=c99} or @samp{-std=iso9899:1999}.  (While in
386 development, drafts of this standard version were referred to as
387 @dfn{C9X}.)
388
389 GCC also has some limited support for traditional (pre-ISO) C with the
390 @samp{-traditional} option.  This support may be of use for compiling
391 some very old programs that have not been updated to ISO C, but should
392 not be used for new programs.  It will not work with some modern C
393 libraries such as the GNU C library.
394
395 By default, GCC provides some extensions to the C language that on
396 rare occasions conflict with the C standard.  @xref{C
397 Extensions,,Extensions to the C Language Family}.  Use of the
398 @samp{-std} options listed above will disable these extensions where
399 they conflict with the C standard version selected.  You may also
400 select an extended version of the C language explicitly with
401 @samp{-std=gnu89} (for C89 with GNU extensions) or @samp{-std=gnu99}
402 (for C99 with GNU extensions).  The default, if no C language dialect
403 options are given, is @samp{-std=gnu89}; this will change to
404 @samp{-std=gnu99} in some future release when the C99 support is
405 complete.  Some features that are part of the C99 standard are
406 accepted as extensions in C89 mode.
407
408 The ISO C standard defines (in clause 4) two classes of conforming
409 implementation.  A @dfn{conforming hosted implementation} supports the
410 whole standard including all the library facilities; a @dfn{conforming
411 freestanding implementation} is only required to provide certain
412 library facilities: those in @code{<float.h>}, @code{<limits.h>},
413 @code{<stdarg.h>}, and @code{<stddef.h>}; since AMD1, also those in
414 @code{<iso646.h>}; and in C99, also those in @code{<stdbool.h>} and
415 @code{<stdint.h>}.  In addition, complex types, added in C99, are not
416 required for freestanding implementations.  The standard also defines
417 two environments for programs, a @dfn{freestanding environment},
418 required of all implementations and which may not have library
419 facilities beyond those required of freestanding implementations,
420 where the handling of program startup and termination are
421 implementation-defined, and a @dfn{hosted environment}, which is not
422 required, in which all the library facilities are provided and startup
423 is through a function @code{int main (void)} or @code{int main (int,
424 char *[])}.  An OS kernel would be a freestanding environment; a
425 program using the facilities of an operating system would normally be
426 in a hosted implementation.
427
428 GNU CC aims towards being usable as a conforming freestanding
429 implementation, or as the compiler for a conforming hosted
430 implementation.  By default, it will act as the compiler for a hosted
431 implementation, defining @code{__STDC_HOSTED__} as @code{1} and
432 presuming that when the names of ISO C functions are used, they have
433 the semantics defined in the standard.  To make it act as a conforming
434 freestanding implementation for a freestanding environment, use the
435 option @samp{-ffreestanding}; it will then define
436 @code{__STDC_HOSTED__} to @code{0} and not make assumptions about the
437 meanings of function names from the standard library.  To build an OS
438 kernel, you may well still need to make your own arrangements for
439 linking and startup.  @xref{C Dialect Options,,Options Controlling C
440 Dialect}.
441
442 GNU CC does not provide the library facilities required only of hosted
443 implementations, nor yet all the facilities required by C99 of
444 freestanding implementations; to use the facilities of a hosted
445 environment, you will need to find them elsewhere (for example, in the
446 GNU C library).  @xref{Standard Libraries,,Standard Libraries}.
447
448 For references to Technical Corrigenda, Rationale documents and
449 information concerning the history of C that is available online, see
450 @uref{http://gcc.gnu.org/readings.html}
451
452 @c FIXME: details of C++ standard.
453 @c FIXME: definitions of Java and Objective C.
454
455 @xref{Language,,The GNU Fortran Language, g77, Using and Porting GNU
456 Fortran}, for details of the Fortran language supported by GCC.
457
458 @xref{References,,Language Definition References, chill, GNU Chill},
459 for details of the CHILL standard.
460
461 @include invoke.texi
462
463 @include install.texi
464
465 @include extend.texi
466
467 @include gcov.texi
468
469 @node Trouble
470 @chapter Known Causes of Trouble with GCC
471 @cindex bugs, known
472 @cindex installation trouble
473 @cindex known causes of trouble
474
475 This section describes known problems that affect users of GCC.  Most
476 of these are not GCC bugs per se---if they were, we would fix them.
477 But the result for a user may be like the result of a bug.
478
479 Some of these problems are due to bugs in other software, some are
480 missing features that are too much work to add, and some are places
481 where people's opinions differ as to what is best.
482
483 @menu
484 * Actual Bugs::               Bugs we will fix later.
485 * Installation Problems::     Problems that manifest when you install GCC.
486 * Cross-Compiler Problems::   Common problems of cross compiling with GCC.
487 * Interoperation::      Problems using GCC with other compilers,
488                            and with certain linkers, assemblers and debuggers.
489 * External Bugs::       Problems compiling certain programs.
490 * Incompatibilities::   GCC is incompatible with traditional C.
491 * Fixed Headers::       GNU C uses corrected versions of system header files.
492                            This is necessary, but doesn't always work smoothly.
493 * Standard Libraries::  GNU C uses the system C library, which might not be
494                            compliant with the ISO C standard.
495 * Disappointments::     Regrettable things we can't change, but not quite bugs.
496 * C++ Misunderstandings::     Common misunderstandings with GNU C++.
497 * Protoize Caveats::    Things to watch out for when using @code{protoize}.
498 * Non-bugs::            Things we think are right, but some others disagree.
499 * Warnings and Errors:: Which problems in your code get warnings,
500                          and which get errors.
501 @end menu
502
503 @node Actual Bugs
504 @section Actual Bugs We Haven't Fixed Yet
505
506 @itemize @bullet
507 @item
508 The @code{fixincludes} script interacts badly with automounters; if the
509 directory of system header files is automounted, it tends to be
510 unmounted while @code{fixincludes} is running.  This would seem to be a
511 bug in the automounter.  We don't know any good way to work around it.
512
513 @item
514 The @code{fixproto} script will sometimes add prototypes for the
515 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
516 @code{jmp_buf} type before that type is defined.  To work around this,
517 edit the offending file and place the typedef in front of the
518 prototypes.
519
520 @item
521 There are several obscure case of mis-using struct, union, and
522 enum tags that are not detected as errors by the compiler.
523
524 @item
525 When @samp{-pedantic-errors} is specified, GCC will incorrectly give
526 an error message when a function name is specified in an expression
527 involving the comma operator.
528
529 @item
530 Loop unrolling doesn't work properly for certain C++ programs.  This is
531 a bug in the C++ front end.  It sometimes emits incorrect debug info, and
532 the loop unrolling code is unable to recover from this error.
533 @end itemize
534
535 @node Installation Problems
536 @section Installation Problems
537
538 This is a list of problems (and some apparent problems which don't
539 really mean anything is wrong) that show up during installation of GNU
540 CC.
541
542 @itemize @bullet
543 @item
544 On certain systems, defining certain environment variables such as
545 @code{CC} can interfere with the functioning of @code{make}.
546
547 @item
548 If you encounter seemingly strange errors when trying to build the
549 compiler in a directory other than the source directory, it could be
550 because you have previously configured the compiler in the source
551 directory.  Make sure you have done all the necessary preparations.
552 @xref{Other Dir}.
553
554 @item
555 If you build GCC on a BSD system using a directory stored in a System
556 V file system, problems may occur in running @code{fixincludes} if the
557 System V file system doesn't support symbolic links.  These problems
558 result in a failure to fix the declaration of @code{size_t} in
559 @file{sys/types.h}.  If you find that @code{size_t} is a signed type and
560 that type mismatches occur, this could be the cause.
561
562 The solution is not to use such a directory for building GCC.
563
564 @item
565 In previous versions of GCC, the @code{gcc} driver program looked for
566 @code{as} and @code{ld} in various places; for example, in files
567 beginning with @file{/usr/local/lib/gcc-}.  GCC version 2 looks for
568 them in the directory
569 @file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}.
570
571 Thus, to use a version of @code{as} or @code{ld} that is not the system
572 default, for example @code{gas} or GNU @code{ld}, you must put them in
573 that directory (or make links to them from that directory).
574
575 @item
576 Some commands executed when making the compiler may fail (return a
577 non-zero status) and be ignored by @code{make}.  These failures, which
578 are often due to files that were not found, are expected, and can safely
579 be ignored.
580
581 @item
582 It is normal to have warnings in compiling certain files about
583 unreachable code and about enumeration type clashes.  These files' names
584 begin with @samp{insn-}.  Also, @file{real.c} may get some warnings that
585 you can ignore.
586
587 @item
588 Sometimes @code{make} recompiles parts of the compiler when installing
589 the compiler.  In one case, this was traced down to a bug in
590 @code{make}.  Either ignore the problem or switch to GNU Make.
591
592 @item
593 If you have installed a program known as purify, you may find that it
594 causes errors while linking @code{enquire}, which is part of building
595 GCC.  The fix is to get rid of the file @code{real-ld} which purify
596 installs---so that GCC won't try to use it.
597
598 @item
599 On GNU/Linux SLS 1.01, there is a problem with @file{libc.a}: it does not
600 contain the obstack functions.  However, GCC assumes that the obstack
601 functions are in @file{libc.a} when it is the GNU C library.  To work
602 around this problem, change the @code{__GNU_LIBRARY__} conditional
603 around line 31 to @samp{#if 1}.
604
605 @item
606 On some 386 systems, building the compiler never finishes because
607 @code{enquire} hangs due to a hardware problem in the motherboard---it
608 reports floating point exceptions to the kernel incorrectly.  You can
609 install GCC except for @file{float.h} by patching out the command to
610 run @code{enquire}.  You may also be able to fix the problem for real by
611 getting a replacement motherboard.  This problem was observed in
612 Revision E of the Micronics motherboard, and is fixed in Revision F.
613 It has also been observed in the MYLEX MXA-33 motherboard.
614
615 If you encounter this problem, you may also want to consider removing
616 the FPU from the socket during the compilation.  Alternatively, if you
617 are running SCO Unix, you can reboot and force the FPU to be ignored.
618 To do this, type @samp{hd(40)unix auto ignorefpu}.
619
620 @item
621 On some 386 systems, GCC crashes trying to compile @file{enquire.c}.
622 This happens on machines that don't have a 387 FPU chip.  On 386
623 machines, the system kernel is supposed to emulate the 387 when you
624 don't have one.  The crash is due to a bug in the emulator.
625
626 One of these systems is the Unix from Interactive Systems: 386/ix.
627 On this system, an alternate emulator is provided, and it does work.
628 To use it, execute this command as super-user:
629
630 @example
631 ln /etc/emulator.rel1 /etc/emulator
632 @end example
633
634 @noindent
635 and then reboot the system.  (The default emulator file remains present
636 under the name @file{emulator.dflt}.)
637
638 Try using @file{/etc/emulator.att}, if you have such a problem on the
639 SCO system.
640
641 Another system which has this problem is Esix.  We don't know whether it
642 has an alternate emulator that works.
643
644 On NetBSD 0.8, a similar problem manifests itself as these error messages:
645
646 @example
647 enquire.c: In function `fprop':
648 enquire.c:2328: floating overflow
649 @end example
650
651 @item
652 On SCO systems, when compiling GCC with the system's compiler,
653 do not use @samp{-O}.  Some versions of the system's compiler miscompile
654 GCC with @samp{-O}.
655
656 @cindex @code{genflags}, crash on Sun 4
657 @item
658 Sometimes on a Sun 4 you may observe a crash in the program
659 @code{genflags} or @code{genoutput} while building GCC.  This is said to
660 be due to a bug in @code{sh}.  You can probably get around it by running
661 @code{genflags} or @code{genoutput} manually and then retrying the
662 @code{make}.
663
664 @item
665 On Solaris 2, executables of GCC version 2.0.2 are commonly
666 available, but they have a bug that shows up when compiling current
667 versions of GCC: undefined symbol errors occur during assembly if you
668 use @samp{-g}.
669
670 The solution is to compile the current version of GCC without
671 @samp{-g}.  That makes a working compiler which you can use to recompile
672 with @samp{-g}.
673
674 @item
675 Solaris 2 comes with a number of optional OS packages.  Some of these
676 packages are needed to use GCC fully.  If you did not install all
677 optional packages when installing Solaris, you will need to verify that
678 the packages that GCC needs are installed.
679
680 To check whether an optional package is installed, use
681 the @code{pkginfo} command.  To add an optional package, use the
682 @code{pkgadd} command.  For further details, see the Solaris
683 documentation.
684
685 For Solaris 2.0 and 2.1, GCC needs six packages: @samp{SUNWarc},
686 @samp{SUNWbtool}, @samp{SUNWesu}, @samp{SUNWhea}, @samp{SUNWlibm}, and
687 @samp{SUNWtoo}.
688
689 For Solaris 2.2, GCC needs an additional seventh package: @samp{SUNWsprot}.
690
691 @item
692 On Solaris 2, trying to use the linker and other tools in
693 @file{/usr/ucb} to install GCC has been observed to cause trouble.
694 For example, the linker may hang indefinitely.  The fix is to remove
695 @file{/usr/ucb} from your @code{PATH}.
696
697 @item
698 If you use the 1.31 version of the MIPS assembler (such as was shipped
699 with Ultrix 3.1), you will need to use the -fno-delayed-branch switch
700 when optimizing floating point code.  Otherwise, the assembler will
701 complain when the GCC compiler fills a branch delay slot with a
702 floating point instruction, such as @code{add.d}.
703
704 @item
705 If on a MIPS system you get an error message saying ``does not have gp
706 sections for all it's [sic] sectons [sic]'', don't worry about it.  This
707 happens whenever you use GAS with the MIPS linker, but there is not
708 really anything wrong, and it is okay to use the output file.  You can
709 stop such warnings by installing the GNU linker.
710
711 It would be nice to extend GAS to produce the gp tables, but they are
712 optional, and there should not be a warning about their absence.
713
714 @item
715 In Ultrix 4.0 on the MIPS machine, @file{stdio.h} does not work with GNU
716 CC at all unless it has been fixed with @code{fixincludes}.  This causes
717 problems in building GCC.  Once GCC is installed, the problems go
718 away.
719
720 To work around this problem, when making the stage 1 compiler, specify
721 this option to Make:
722
723 @example
724 GCC_FOR_TARGET="./xgcc -B./ -I./include"
725 @end example
726
727 When making stage 2 and stage 3, specify this option:
728
729 @example
730 CFLAGS="-g -I./include"
731 @end example
732
733 @item
734 Users have reported some problems with version 2.0 of the MIPS
735 compiler tools that were shipped with Ultrix 4.1.  Version 2.10
736 which came with Ultrix 4.2 seems to work fine.
737
738 Users have also reported some problems with version 2.20 of the
739 MIPS compiler tools that were shipped with RISC/os 4.x.  The earlier
740 version 2.11 seems to work fine.
741
742 @item
743 Some versions of the MIPS linker will issue an assertion failure
744 when linking code that uses @code{alloca} against shared
745 libraries on RISC-OS 5.0, and DEC's OSF/1 systems.  This is a bug
746 in the linker, that is supposed to be fixed in future revisions.
747 To protect against this, GCC passes @samp{-non_shared} to the
748 linker unless you pass an explicit @samp{-shared} or
749 @samp{-call_shared} switch.
750
751 @item
752 On System V release 3, you may get this error message
753 while linking:
754
755 @smallexample
756 ld fatal: failed to write symbol name @var{something}
757  in strings table for file @var{whatever}
758 @end smallexample
759
760 This probably indicates that the disk is full or your ULIMIT won't allow
761 the file to be as large as it needs to be.
762
763 This problem can also result because the kernel parameter @code{MAXUMEM}
764 is too small.  If so, you must regenerate the kernel and make the value
765 much larger.  The default value is reported to be 1024; a value of 32768
766 is said to work.  Smaller values may also work.
767
768 @item
769 On System V, if you get an error like this,
770
771 @example
772 /usr/local/lib/bison.simple: In function `yyparse':
773 /usr/local/lib/bison.simple:625: virtual memory exhausted
774 @end example
775
776 @noindent
777 that too indicates a problem with disk space, ULIMIT, or @code{MAXUMEM}.
778
779 @item
780 Current GCC versions probably do not work on version 2 of the NeXT
781 operating system.
782
783 @item
784 On NeXTStep 3.0, the Objective C compiler does not work, due,
785 apparently, to a kernel bug that it happens to trigger.  This problem
786 does not happen on 3.1.
787
788 @item
789 On the Tower models 4@var{n}0 and 6@var{n}0, by default a process is not
790 allowed to have more than one megabyte of memory.  GCC cannot compile
791 itself (or many other programs) with @samp{-O} in that much memory.
792
793 To solve this problem, reconfigure the kernel adding the following line
794 to the configuration file:
795
796 @smallexample
797 MAXUMEM = 4096
798 @end smallexample
799
800 @item
801 On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a bug
802 in the assembler that must be fixed before GCC can be built.  This
803 bug manifests itself during the first stage of compilation, while
804 building @file{libgcc2.a}:
805
806 @smallexample
807 _floatdisf
808 cc1: warning: `-g' option not supported on this version of GCC
809 cc1: warning: `-g1' option not supported on this version of GCC
810 ./xgcc: Internal compiler error: program as got fatal signal 11
811 @end smallexample
812
813 A patched version of the assembler is available as the file
814 @uref{ftp://altdorf.ai.mit.edu/archive/cph/hpux-8.0-assembler}.  If you
815 have HP software support, the patch can also be obtained directly from
816 HP, as described in the following note:
817
818 @quotation
819 This is the patched assembler, to patch SR#1653-010439, where the
820 assembler aborts on floating point constants.
821
822 The bug is not really in the assembler, but in the shared library
823 version of the function ``cvtnum(3c)''.  The bug on ``cvtnum(3c)'' is
824 SR#4701-078451.  Anyway, the attached assembler uses the archive
825 library version of ``cvtnum(3c)'' and thus does not exhibit the bug.
826 @end quotation
827
828 This patch is also known as PHCO_4484.
829
830 @item
831 On HP-UX version 8.05, but not on 8.07 or more recent versions,
832 the @code{fixproto} shell script triggers a bug in the system shell.
833 If you encounter this problem, upgrade your operating system or
834 use BASH (the GNU shell) to run @code{fixproto}.
835
836 @item
837 Some versions of the Pyramid C compiler are reported to be unable to
838 compile GCC.  You must use an older version of GCC for
839 bootstrapping.  One indication of this problem is if you get a crash
840 when GCC compiles the function @code{muldi3} in file @file{libgcc2.c}.
841
842 You may be able to succeed by getting GCC version 1, installing it,
843 and using it to compile GCC version 2.  The bug in the Pyramid C
844 compiler does not seem to affect GCC version 1.
845
846 @item
847 There may be similar problems on System V Release 3.1 on 386 systems.
848
849 @item
850 On the Intel Paragon (an i860 machine), if you are using operating
851 system version 1.0, you will get warnings or errors about redefinition
852 of @code{va_arg} when you build GCC.
853
854 If this happens, then you need to link most programs with the library
855 @file{iclib.a}.  You must also modify @file{stdio.h} as follows: before
856 the lines
857
858 @example
859 #if     defined(__i860__) && !defined(_VA_LIST)
860 #include <va_list.h>
861 @end example
862
863 @noindent
864 insert the line
865
866 @example
867 #if __PGC__
868 @end example
869
870 @noindent
871 and after the lines
872
873 @example
874 extern int  vprintf(const char *, va_list );
875 extern int  vsprintf(char *, const char *, va_list );
876 #endif
877 @end example
878
879 @noindent
880 insert the line
881
882 @example
883 #endif /* __PGC__ */
884 @end example
885
886 These problems don't exist in operating system version 1.1.
887
888 @item
889 On the Altos 3068, programs compiled with GCC won't work unless you
890 fix a kernel bug.  This happens using system versions V.2.2 1.0gT1 and
891 V.2.2 1.0e and perhaps later versions as well.  See the file
892 @file{README.ALTOS}.
893
894 @item
895 You will get several sorts of compilation and linking errors on the
896 we32k if you don't follow the special instructions.  @xref{Configurations}.
897
898 @item
899 A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto
900 program to report an error of the form:
901
902 @example
903 ./fixproto: sh internal 1K buffer overflow
904 @end example
905
906 To fix this, change the first line of the fixproto script to look like:
907
908 @example
909 #!/bin/ksh
910 @end example
911 @end itemize
912
913 @node Cross-Compiler Problems
914 @section Cross-Compiler Problems
915
916 You may run into problems with cross compilation on certain machines,
917 for several reasons.
918
919 @itemize @bullet
920 @item
921 Cross compilation can run into trouble for certain machines because
922 some target machines' assemblers require floating point numbers to be
923 written as @emph{integer} constants in certain contexts.
924
925 The compiler writes these integer constants by examining the floating
926 point value as an integer and printing that integer, because this is
927 simple to write and independent of the details of the floating point
928 representation.  But this does not work if the compiler is running on
929 a different machine with an incompatible floating point format, or
930 even a different byte-ordering.
931
932 In addition, correct constant folding of floating point values
933 requires representing them in the target machine's format.
934 (The C standard does not quite require this, but in practice
935 it is the only way to win.)
936
937 It is now possible to overcome these problems by defining macros such
938 as @code{REAL_VALUE_TYPE}.  But doing so is a substantial amount of
939 work for each target machine.
940 @ifset INTERNALS
941 @xref{Cross-compilation}.
942 @end ifset
943 @ifclear INTERNALS
944 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
945 gcc.info, Using and Porting GCC}.
946 @end ifclear
947
948 @item
949 At present, the program @file{mips-tfile} which adds debug
950 support to object files on MIPS systems does not work in a cross
951 compile environment.
952 @end itemize
953
954 @node Interoperation
955 @section Interoperation
956
957 This section lists various difficulties encountered in using GNU C or
958 GNU C++ together with other compilers or with the assemblers, linkers,
959 libraries and debuggers on certain systems.
960
961 @itemize @bullet
962 @item
963 Objective C does not work on the RS/6000.
964
965 @item
966 GNU C++ does not do name mangling in the same way as other C++
967 compilers.  This means that object files compiled with one compiler
968 cannot be used with another.
969
970 This effect is intentional, to protect you from more subtle problems.
971 Compilers differ as to many internal details of C++ implementation,
972 including: how class instances are laid out, how multiple inheritance is
973 implemented, and how virtual function calls are handled.  If the name
974 encoding were made the same, your programs would link against libraries
975 provided from other compilers---but the programs would then crash when
976 run.  Incompatible libraries are then detected at link time, rather than
977 at run time.
978
979 @item
980 Older GDB versions sometimes fail to read the output of GCC version
981 2.  If you have trouble, get GDB version 4.4 or later.
982
983 @item
984 @cindex DBX
985 DBX rejects some files produced by GCC, though it accepts similar
986 constructs in output from PCC.  Until someone can supply a coherent
987 description of what is valid DBX input and what is not, there is
988 nothing I can do about these problems.  You are on your own.
989
990 @item
991 The GNU assembler (GAS) does not support PIC.  To generate PIC code, you
992 must use some other assembler, such as @file{/bin/as}.
993
994 @item
995 On some BSD systems, including some versions of Ultrix, use of profiling
996 causes static variable destructors (currently used only in C++) not to
997 be run.
998
999 @item
1000 Use of @samp{-I/usr/include} may cause trouble.
1001
1002 Many systems come with header files that won't work with GCC unless
1003 corrected by @code{fixincludes}.  The corrected header files go in a new
1004 directory; GCC searches this directory before @file{/usr/include}.
1005 If you use @samp{-I/usr/include}, this tells GCC to search
1006 @file{/usr/include} earlier on, before the corrected headers.  The
1007 result is that you get the uncorrected header files.
1008
1009 Instead, you should use these options (when compiling C programs):
1010
1011 @smallexample
1012 -I/usr/local/lib/gcc-lib/@var{target}/@var{version}/include -I/usr/include
1013 @end smallexample
1014
1015 For C++ programs, GCC also uses a special directory that defines C++
1016 interfaces to standard C subroutines.  This directory is meant to be
1017 searched @emph{before} other standard include directories, so that it
1018 takes precedence.  If you are compiling C++ programs and specifying
1019 include directories explicitly, use this option first, then the two
1020 options above:
1021
1022 @example
1023 -I/usr/local/lib/g++-include
1024 @end example
1025
1026 @ignore
1027 @cindex @code{vfork}, for the Sun-4
1028 @item
1029 There is a bug in @code{vfork} on the Sun-4 which causes the registers
1030 of the child process to clobber those of the parent.  Because of this,
1031 programs that call @code{vfork} are likely to lose when compiled
1032 optimized with GCC when the child code alters registers which contain
1033 C variables in the parent.  This affects variables which are live in the
1034 parent across the call to @code{vfork}.
1035
1036 If you encounter this, you can work around the problem by declaring
1037 variables @code{volatile} in the function that calls @code{vfork}, until
1038 the problem goes away, or by not declaring them @code{register} and not
1039 using @samp{-O} for those source files.
1040 @end ignore
1041
1042 @item
1043 On some SGI systems, when you use @samp{-lgl_s} as an option,
1044 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
1045 Naturally, this does not happen when you use GCC.
1046 You must specify all three options explicitly.
1047
1048 @item
1049 On a Sparc, GCC aligns all values of type @code{double} on an 8-byte
1050 boundary, and it expects every @code{double} to be so aligned.  The Sun
1051 compiler usually gives @code{double} values 8-byte alignment, with one
1052 exception: function arguments of type @code{double} may not be aligned.
1053
1054 As a result, if a function compiled with Sun CC takes the address of an
1055 argument of type @code{double} and passes this pointer of type
1056 @code{double *} to a function compiled with GCC, dereferencing the
1057 pointer may cause a fatal signal.
1058
1059 One way to solve this problem is to compile your entire program with GNU
1060 CC.  Another solution is to modify the function that is compiled with
1061 Sun CC to copy the argument into a local variable; local variables
1062 are always properly aligned.  A third solution is to modify the function
1063 that uses the pointer to dereference it via the following function
1064 @code{access_double} instead of directly with @samp{*}:
1065
1066 @smallexample
1067 inline double
1068 access_double (double *unaligned_ptr)
1069 @{
1070   union d2i @{ double d; int i[2]; @};
1071
1072   union d2i *p = (union d2i *) unaligned_ptr;
1073   union d2i u;
1074
1075   u.i[0] = p->i[0];
1076   u.i[1] = p->i[1];
1077
1078   return u.d;
1079 @}
1080 @end smallexample
1081
1082 @noindent
1083 Storing into the pointer can be done likewise with the same union.
1084
1085 @item
1086 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
1087 may allocate memory that is only 4 byte aligned.  Since GCC on the
1088 Sparc assumes that doubles are 8 byte aligned, this may result in a
1089 fatal signal if doubles are stored in memory allocated by the
1090 @file{libmalloc.a} library.
1091
1092 The solution is to not use the @file{libmalloc.a} library.  Use instead
1093 @code{malloc} and related functions from @file{libc.a}; they do not have
1094 this problem.
1095
1096 @item
1097 Sun forgot to include a static version of @file{libdl.a} with some
1098 versions of SunOS (mainly 4.1).  This results in undefined symbols when
1099 linking static binaries (that is, if you use @samp{-static}).  If you
1100 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
1101 when linking, compile and link against the file
1102 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
1103
1104 @item
1105 The 128-bit long double format that the Sparc port supports currently
1106 works by using the architecturally defined quad-word floating point
1107 instructions.  Since there is no hardware that supports these
1108 instructions they must be emulated by the operating system.  Long
1109 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
1110 kernel emulator uses an obsolete and incompatible format.  Long doubles
1111 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
1112 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
1113 does not enable them by default.  Long doubles appear to work in Sun OS
1114 5.x (Solaris 2.x).
1115
1116 @item
1117 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
1118 compile GCC correctly.  We do not yet know why.  However, GCC
1119 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
1120 compile itself properly on 9.01.
1121
1122 @item
1123 On the HP PA machine, ADB sometimes fails to work on functions compiled
1124 with GCC.  Specifically, it fails to work on functions that use
1125 @code{alloca} or variable-size arrays.  This is because GCC doesn't
1126 generate HP-UX unwind descriptors for such functions.  It may even be
1127 impossible to generate them.
1128
1129 @item
1130 Debugging (@samp{-g}) is not supported on the HP PA machine, unless you use
1131 the preliminary GNU tools (@pxref{Installation}).
1132
1133 @item
1134 Taking the address of a label may generate errors from the HP-UX
1135 PA assembler.  GAS for the PA does not have this problem.
1136
1137 @item
1138 Using floating point parameters for indirect calls to static functions
1139 will not work when using the HP assembler.  There simply is no way for GCC
1140 to specify what registers hold arguments for static functions when using
1141 the HP assembler.  GAS for the PA does not have this problem.
1142
1143 @item
1144 In extremely rare cases involving some very large functions you may
1145 receive errors from the HP linker complaining about an out of bounds
1146 unconditional branch offset.  This used to occur more often in previous
1147 versions of GCC, but is now exceptionally rare.  If you should run
1148 into it, you can work around by making your function smaller.
1149
1150 @item
1151 GCC compiled code sometimes emits warnings from the HP-UX assembler of
1152 the form:
1153
1154 @smallexample
1155 (warning) Use of GR3 when
1156   frame >= 8192 may cause conflict.
1157 @end smallexample
1158
1159 These warnings are harmless and can be safely ignored.
1160
1161 @item
1162 The current version of the assembler (@file{/bin/as}) for the RS/6000
1163 has certain problems that prevent the @samp{-g} option in GCC from
1164 working.  Note that @file{Makefile.in} uses @samp{-g} by default when
1165 compiling @file{libgcc2.c}.
1166
1167 IBM has produced a fixed version of the assembler.  The upgraded
1168 assembler unfortunately was not included in any of the AIX 3.2 update
1169 PTF releases (3.2.2, 3.2.3, or 3.2.3e).  Users of AIX 3.1 should request
1170 PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
1171 See the file @file{README.RS6000} for more details on these updates.
1172
1173 You can test for the presence of a fixed assembler by using the
1174 command
1175
1176 @smallexample
1177 as -u < /dev/null
1178 @end smallexample
1179
1180 @noindent
1181 If the command exits normally, the assembler fix already is installed.
1182 If the assembler complains that "-u" is an unknown flag, you need to
1183 order the fix.
1184
1185 @item
1186 On the IBM RS/6000, compiling code of the form
1187
1188 @smallexample
1189 extern int foo;
1190
1191 @dots{} foo @dots{}
1192
1193 static int foo;
1194 @end smallexample
1195
1196 @noindent
1197 will cause the linker to report an undefined symbol @code{foo}.
1198 Although this behavior differs from most other systems, it is not a
1199 bug because redefining an @code{extern} variable as @code{static}
1200 is undefined in ISO C.
1201
1202 @item
1203 AIX on the RS/6000 provides support (NLS) for environments outside of
1204 the United States.  Compilers and assemblers use NLS to support
1205 locale-specific representations of various objects including
1206 floating-point numbers ("." vs "," for separating decimal fractions).
1207 There have been problems reported where the library linked with GCC does
1208 not produce the same floating-point formats that the assembler accepts.
1209 If you have this problem, set the LANG environment variable to "C" or
1210 "En_US".
1211
1212 @item
1213 Even if you specify @samp{-fdollars-in-identifiers},
1214 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
1215 to a restriction in the IBM assembler.  GAS supports these
1216 identifiers.
1217
1218 @item
1219 On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}.  XLC
1220 version 1.3.0.1 or later fixes this problem.  You can obtain XLC-1.3.0.2
1221 by requesting PTF 421749 from IBM.
1222
1223 @item
1224 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
1225 occurs when the @samp{fldcr} instruction is used.  GCC uses
1226 @samp{fldcr} on the 88100 to serialize volatile memory references.  Use
1227 the option @samp{-mno-serialize-volatile} if your version of the
1228 assembler has this bug.
1229
1230 @item
1231 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
1232 messages from the linker.  These warning messages complain of mismatched
1233 psect attributes.  You can ignore them.  @xref{VMS Install}.
1234
1235 @item
1236 On NewsOS version 3, if you include both of the files @file{stddef.h}
1237 and @file{sys/types.h}, you get an error because there are two typedefs
1238 of @code{size_t}.  You should change @file{sys/types.h} by adding these
1239 lines around the definition of @code{size_t}:
1240
1241 @smallexample
1242 #ifndef _SIZE_T
1243 #define _SIZE_T
1244 @var{actual typedef here}
1245 #endif
1246 @end smallexample
1247
1248 @cindex Alliant
1249 @item
1250 On the Alliant, the system's own convention for returning structures
1251 and unions is unusual, and is not compatible with GCC no matter
1252 what options are used.
1253
1254 @cindex RT PC
1255 @cindex IBM RT PC
1256 @item
1257 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
1258 convention for structure and union returning.  Use the option
1259 @samp{-mhc-struct-return} to tell GCC to use a convention compatible
1260 with it.
1261
1262 @cindex Vax calling convention
1263 @cindex Ultrix calling convention
1264 @item
1265 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
1266 by function calls.  However, the C compiler uses conventions compatible
1267 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
1268
1269 GCC uses the same convention as the Ultrix C compiler.  You can use
1270 these options to produce code compatible with the Fortran compiler:
1271
1272 @smallexample
1273 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
1274 @end smallexample
1275
1276 @item
1277 On the WE32k, you may find that programs compiled with GCC do not
1278 work with the standard shared C library.  You may need to link with
1279 the ordinary C compiler.  If you do so, you must specify the following
1280 options:
1281
1282 @smallexample
1283 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
1284 @end smallexample
1285
1286 The first specifies where to find the library @file{libgcc.a}
1287 specified with the @samp{-lgcc} option.
1288
1289 GCC does linking by invoking @code{ld}, just as @code{cc} does, and
1290 there is no reason why it @emph{should} matter which compilation program
1291 you use to invoke @code{ld}.  If someone tracks this problem down,
1292 it can probably be fixed easily.
1293
1294 @item
1295 On the Alpha, you may get assembler errors about invalid syntax as a
1296 result of floating point constants.  This is due to a bug in the C
1297 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}.  Given valid
1298 floating point numbers, they sometimes print @samp{NaN}.
1299
1300 @item
1301 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
1302 sometimes reorders instructions incorrectly when optimization is turned
1303 on.  If you think this may be happening to you, try using the GNU
1304 assembler; GAS version 2.1 supports ECOFF on Irix.
1305
1306 Or use the @samp{-noasmopt} option when you compile GCC with itself,
1307 and then again when you compile your program.  (This is a temporary
1308 kludge to turn off assembler optimization on Irix.)  If this proves to
1309 be what you need, edit the assembler spec in the file @file{specs} so
1310 that it unconditionally passes @samp{-O0} to the assembler, and never
1311 passes @samp{-O2} or @samp{-O3}.
1312 @end itemize
1313
1314 @node External Bugs
1315 @section Problems Compiling Certain Programs
1316
1317 @c prevent bad page break with this line
1318 Certain programs have problems compiling.
1319
1320 @itemize @bullet
1321 @item
1322 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
1323 because of problems in DEC's versions of the X11 header files
1324 @file{X11/Xlib.h} and @file{X11/Xutil.h}.  People recommend adding
1325 @samp{-I/usr/include/mit} to use the MIT versions of the header files,
1326 using the @samp{-traditional} switch to turn off ISO C, or fixing the
1327 header files by adding this:
1328
1329 @example
1330 #ifdef __STDC__
1331 #define NeedFunctionPrototypes 0
1332 #endif
1333 @end example
1334
1335 @item
1336 On various 386 Unix systems derived from System V, including SCO, ISC,
1337 and ESIX, you may get error messages about running out of virtual memory
1338 while compiling certain programs.
1339
1340 You can prevent this problem by linking GCC with the GNU malloc
1341 (which thus replaces the malloc that comes with the system).  GNU malloc
1342 is available as a separate package, and also in the file
1343 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
1344
1345 If you have installed GNU malloc as a separate library package, use this
1346 option when you relink GCC:
1347
1348 @example
1349 MALLOC=/usr/local/lib/libgmalloc.a
1350 @end example
1351
1352 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
1353 the object file to @file{gmalloc.o} and use this option when you relink
1354 GCC:
1355
1356 @example
1357 MALLOC=gmalloc.o
1358 @end example
1359 @end itemize
1360
1361 @node Incompatibilities
1362 @section Incompatibilities of GCC
1363 @cindex incompatibilities of GCC
1364
1365 There are several noteworthy incompatibilities between GNU C and K&R 
1366 (non-ISO) versions of C.  The @samp{-traditional} option
1367 eliminates many of these incompatibilities, @emph{but not all}, by
1368 telling GNU C to behave like a K&R C compiler.
1369
1370 @itemize @bullet
1371 @cindex string constants
1372 @cindex read-only strings
1373 @cindex shared strings
1374 @item
1375 GCC normally makes string constants read-only.  If several
1376 identical-looking string constants are used, GCC stores only one
1377 copy of the string.
1378
1379 @cindex @code{mktemp}, and constant strings
1380 One consequence is that you cannot call @code{mktemp} with a string
1381 constant argument.  The function @code{mktemp} always alters the
1382 string its argument points to.
1383
1384 @cindex @code{sscanf}, and constant strings
1385 @cindex @code{fscanf}, and constant strings
1386 @cindex @code{scanf}, and constant strings
1387 Another consequence is that @code{sscanf} does not work on some systems
1388 when passed a string constant as its format control string or input.
1389 This is because @code{sscanf} incorrectly tries to write into the string
1390 constant.  Likewise @code{fscanf} and @code{scanf}.
1391
1392 The best solution to these problems is to change the program to use
1393 @code{char}-array variables with initialization strings for these
1394 purposes instead of string constants.  But if this is not possible,
1395 you can use the @samp{-fwritable-strings} flag, which directs GCC
1396 to handle string constants the same way most C compilers do.
1397 @samp{-traditional} also has this effect, among others.
1398
1399 @item
1400 @code{-2147483648} is positive.
1401
1402 This is because 2147483648 cannot fit in the type @code{int}, so
1403 (following the ISO C rules) its data type is @code{unsigned long int}.
1404 Negating this value yields 2147483648 again.
1405
1406 @item
1407 GCC does not substitute macro arguments when they appear inside of
1408 string constants.  For example, the following macro in GCC
1409
1410 @example
1411 #define foo(a) "a"
1412 @end example
1413
1414 @noindent
1415 will produce output @code{"a"} regardless of what the argument @var{a} is.
1416
1417 The @samp{-traditional} option directs GCC to handle such cases
1418 (among others) in the old-fashioned (non-ISO) fashion.
1419
1420 @cindex @code{setjmp} incompatibilities
1421 @cindex @code{longjmp} incompatibilities
1422 @item
1423 When you use @code{setjmp} and @code{longjmp}, the only automatic
1424 variables guaranteed to remain valid are those declared
1425 @code{volatile}.  This is a consequence of automatic register
1426 allocation.  Consider this function:
1427
1428 @example
1429 jmp_buf j;
1430
1431 foo ()
1432 @{
1433   int a, b;
1434
1435   a = fun1 ();
1436   if (setjmp (j))
1437     return a;
1438
1439   a = fun2 ();
1440   /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
1441   return a + fun3 ();
1442 @}
1443 @end example
1444
1445 Here @code{a} may or may not be restored to its first value when the
1446 @code{longjmp} occurs.  If @code{a} is allocated in a register, then
1447 its first value is restored; otherwise, it keeps the last value stored
1448 in it.
1449
1450 If you use the @samp{-W} option with the @samp{-O} option, you will
1451 get a warning when GCC thinks such a problem might be possible.
1452
1453 The @samp{-traditional} option directs GNU C to put variables in
1454 the stack by default, rather than in registers, in functions that
1455 call @code{setjmp}.  This results in the behavior found in
1456 traditional C compilers.
1457
1458 @item
1459 Programs that use preprocessing directives in the middle of macro
1460 arguments do not work with GCC.  For example, a program like this
1461 will not work:
1462
1463 @example
1464 foobar (
1465 #define luser
1466         hack)
1467 @end example
1468
1469 ISO C does not permit such a construct.  It would make sense to support
1470 it when @samp{-traditional} is used, but it is too much work to
1471 implement.
1472
1473 @item
1474 K&R compilers allow comments to cross over an inclusion boundary (i.e.
1475 started in an include file and ended in the including file).  I think
1476 this would be quite ugly and can't imagine it could be needed.
1477
1478 @cindex external declaration scope
1479 @cindex scope of external declarations
1480 @cindex declaration scope
1481 @item
1482 Declarations of external variables and functions within a block apply
1483 only to the block containing the declaration.  In other words, they
1484 have the same scope as any other declaration in the same place.
1485
1486 In some other C compilers, a @code{extern} declaration affects all the
1487 rest of the file even if it happens within a block.
1488
1489 The @samp{-traditional} option directs GNU C to treat all @code{extern}
1490 declarations as global, like traditional compilers.
1491
1492 @item
1493 In traditional C, you can combine @code{long}, etc., with a typedef name,
1494 as shown here:
1495
1496 @example
1497 typedef int foo;
1498 typedef long foo bar;
1499 @end example
1500
1501 In ISO C, this is not allowed: @code{long} and other type modifiers
1502 require an explicit @code{int}.  Because this criterion is expressed
1503 by Bison grammar rules rather than C code, the @samp{-traditional}
1504 flag cannot alter it.
1505
1506 @cindex typedef names as function parameters
1507 @item
1508 PCC allows typedef names to be used as function parameters.  The
1509 difficulty described immediately above applies here too.
1510
1511 @item
1512 When in @samp{-traditional} mode, GCC allows the following erroneous
1513 pair of declarations to appear together in a given scope:
1514
1515 @example
1516 typedef int foo;
1517 typedef foo foo;
1518 @end example
1519
1520 @item
1521 GCC treats all characters of identifiers as significant, even when in
1522 @samp{-traditional} mode.  According to K&R-1 (2.2), ``No more than the
1523 first eight characters are significant, although more may be used.''.
1524 Also according to K&R-1 (2.2), ``An identifier is a sequence of letters
1525 and digits; the first character must be a letter.  The underscore _
1526 counts as a letter.'', but GCC also allows dollar signs in identifiers.
1527
1528 @cindex whitespace
1529 @item
1530 PCC allows whitespace in the middle of compound assignment operators
1531 such as @samp{+=}.  GCC, following the ISO standard, does not
1532 allow this.  The difficulty described immediately above applies here
1533 too.
1534
1535 @cindex apostrophes
1536 @cindex '
1537 @item
1538 GCC complains about unterminated character constants inside of
1539 preprocessing conditionals that fail.  Some programs have English
1540 comments enclosed in conditionals that are guaranteed to fail; if these
1541 comments contain apostrophes, GCC will probably report an error.  For
1542 example, this code would produce an error:
1543
1544 @example
1545 #if 0
1546 You can't expect this to work.
1547 #endif
1548 @end example
1549
1550 The best solution to such a problem is to put the text into an actual
1551 C comment delimited by @samp{/*@dots{}*/}.  However,
1552 @samp{-traditional} suppresses these error messages.
1553
1554 @item
1555 Many user programs contain the declaration @samp{long time ();}.  In the
1556 past, the system header files on many systems did not actually declare
1557 @code{time}, so it did not matter what type your program declared it to
1558 return.  But in systems with ISO C headers, @code{time} is declared to
1559 return @code{time_t}, and if that is not the same as @code{long}, then
1560 @samp{long time ();} is erroneous.
1561
1562 The solution is to change your program to use appropriate system headers
1563 (@code{<time.h>} on systems with ISO C headers) and not to declare
1564 @code{time} if the system header files declare it, or failing that to
1565 use @code{time_t} as the return type of @code{time}.
1566
1567 @cindex @code{float} as function value type
1568 @item
1569 When compiling functions that return @code{float}, PCC converts it to
1570 a double.  GCC actually returns a @code{float}.  If you are concerned
1571 with PCC compatibility, you should declare your functions to return
1572 @code{double}; you might as well say what you mean.
1573
1574 @cindex structures
1575 @cindex unions
1576 @item
1577 When compiling functions that return structures or unions, GCC
1578 output code normally uses a method different from that used on most
1579 versions of Unix.  As a result, code compiled with GCC cannot call
1580 a structure-returning function compiled with PCC, and vice versa.
1581
1582 The method used by GCC is as follows: a structure or union which is
1583 1, 2, 4 or 8 bytes long is returned like a scalar.  A structure or union
1584 with any other size is stored into an address supplied by the caller
1585 (usually in a special, fixed register, but on some machines it is passed
1586 on the stack).  The machine-description macros @code{STRUCT_VALUE} and
1587 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
1588
1589 By contrast, PCC on most target machines returns structures and unions
1590 of any size by copying the data into an area of static storage, and then
1591 returning the address of that storage as if it were a pointer value.
1592 The caller must copy the data from that memory area to the place where
1593 the value is wanted.  GCC does not use this method because it is
1594 slower and nonreentrant.
1595
1596 On some newer machines, PCC uses a reentrant convention for all
1597 structure and union returning.  GCC on most of these machines uses a
1598 compatible convention when returning structures and unions in memory,
1599 but still returns small structures and unions in registers.
1600
1601 You can tell GCC to use a compatible convention for all structure and
1602 union returning with the option @samp{-fpcc-struct-return}.
1603
1604 @cindex preprocessing tokens
1605 @cindex preprocessing numbers
1606 @item
1607 GNU C complains about program fragments such as @samp{0x74ae-0x4000}
1608 which appear to be two hexadecimal constants separated by the minus
1609 operator.  Actually, this string is a single @dfn{preprocessing token}.
1610 Each such token must correspond to one token in C.  Since this does not,
1611 GNU C prints an error message.  Although it may appear obvious that what
1612 is meant is an operator and two values, the ISO C standard specifically
1613 requires that this be treated as erroneous.
1614
1615 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
1616 begins with a digit and is followed by letters, underscores, digits,
1617 periods and @samp{e+}, @samp{e-}, @samp{E+}, or @samp{E-} character
1618 sequences.
1619
1620 To make the above program fragment valid, place whitespace in front of
1621 the minus sign.  This whitespace will end the preprocessing number.
1622 @end itemize
1623
1624 @node Fixed Headers
1625 @section Fixed Header Files
1626
1627 GCC needs to install corrected versions of some system header files.
1628 This is because most target systems have some header files that won't
1629 work with GCC unless they are changed.  Some have bugs, some are
1630 incompatible with ISO C, and some depend on special features of other
1631 compilers.
1632
1633 Installing GCC automatically creates and installs the fixed header
1634 files, by running a program called @code{fixincludes} (or for certain
1635 targets an alternative such as @code{fixinc.svr4}).  Normally, you
1636 don't need to pay attention to this.  But there are cases where it
1637 doesn't do the right thing automatically.
1638
1639 @itemize @bullet
1640 @item
1641 If you update the system's header files, such as by installing a new
1642 system version, the fixed header files of GCC are not automatically
1643 updated.  The easiest way to update them is to reinstall GCC.  (If
1644 you want to be clever, look in the makefile and you can find a
1645 shortcut.)
1646
1647 @item
1648 On some systems, in particular SunOS 4, header file directories contain
1649 machine-specific symbolic links in certain places.  This makes it
1650 possible to share most of the header files among hosts running the
1651 same version of SunOS 4 on different machine models.
1652
1653 The programs that fix the header files do not understand this special
1654 way of using symbolic links; therefore, the directory of fixed header
1655 files is good only for the machine model used to build it.
1656
1657 In SunOS 4, only programs that look inside the kernel will notice the
1658 difference between machine models.  Therefore, for most purposes, you
1659 need not be concerned about this.
1660
1661 It is possible to make separate sets of fixed header files for the
1662 different machine models, and arrange a structure of symbolic links so
1663 as to use the proper set, but you'll have to do this by hand.
1664
1665 @item
1666 On Lynxos, GCC by default does not fix the header files.  This is
1667 because bugs in the shell cause the @code{fixincludes} script to fail.
1668
1669 This means you will encounter problems due to bugs in the system header
1670 files.  It may be no comfort that they aren't GCC's fault, but it
1671 does mean that there's nothing for us to do about them.
1672 @end itemize
1673
1674 @node Standard Libraries
1675 @section Standard Libraries
1676
1677 GCC by itself attempts to be a conforming freestanding implementation.
1678 @xref{Standards,,Language Standards Supported by GCC}, for details of
1679 what this means.  Beyond the library facilities required of such an
1680 implementation, the rest of the C library is supplied by the vendor of
1681 the operating system.  If that C library doesn't conform to the C
1682 standards, then your programs might get warnings (especially when using
1683 @samp{-Wall}) that you don't expect.
1684
1685 For example, the @code{sprintf} function on SunOS 4.1.3 returns
1686 @code{char *} while the C standard says that @code{sprintf} returns an
1687 @code{int}.  The @code{fixincludes} program could make the prototype for
1688 this function match the Standard, but that would be wrong, since the
1689 function will still return @code{char *}.
1690
1691 If you need a Standard compliant library, then you need to find one, as
1692 GCC does not provide one.  The GNU C library (called @code{glibc})
1693 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
1694 GNU/Linux and HURD-based GNU systems; no recent version of it supports
1695 other systems, though some very old versions did.  Version 2.2 of the
1696 GNU C library includes nearly complete C99 support.  You could also ask
1697 your operating system vendor if newer libraries are available.
1698
1699 @node Disappointments
1700 @section Disappointments and Misunderstandings
1701
1702 These problems are perhaps regrettable, but we don't know any practical
1703 way around them.
1704
1705 @itemize @bullet
1706 @item
1707 Certain local variables aren't recognized by debuggers when you compile
1708 with optimization.
1709
1710 This occurs because sometimes GCC optimizes the variable out of
1711 existence.  There is no way to tell the debugger how to compute the
1712 value such a variable ``would have had'', and it is not clear that would
1713 be desirable anyway.  So GCC simply does not mention the eliminated
1714 variable when it writes debugging information.
1715
1716 You have to expect a certain amount of disagreement between the
1717 executable and your source code, when you use optimization.
1718
1719 @cindex conflicting types
1720 @cindex scope of declaration
1721 @item
1722 Users often think it is a bug when GCC reports an error for code
1723 like this:
1724
1725 @example
1726 int foo (struct mumble *);
1727
1728 struct mumble @{ @dots{} @};
1729
1730 int foo (struct mumble *x)
1731 @{ @dots{} @}
1732 @end example
1733
1734 This code really is erroneous, because the scope of @code{struct
1735 mumble} in the prototype is limited to the argument list containing it.
1736 It does not refer to the @code{struct mumble} defined with file scope
1737 immediately below---they are two unrelated types with similar names in
1738 different scopes.
1739
1740 But in the definition of @code{foo}, the file-scope type is used
1741 because that is available to be inherited.  Thus, the definition and
1742 the prototype do not match, and you get an error.
1743
1744 This behavior may seem silly, but it's what the ISO standard specifies.
1745 It is easy enough for you to make your code work by moving the
1746 definition of @code{struct mumble} above the prototype.  It's not worth
1747 being incompatible with ISO C just to avoid an error for the example
1748 shown above.
1749
1750 @item
1751 Accesses to bitfields even in volatile objects works by accessing larger
1752 objects, such as a byte or a word.  You cannot rely on what size of
1753 object is accessed in order to read or write the bitfield; it may even
1754 vary for a given bitfield according to the precise usage.
1755
1756 If you care about controlling the amount of memory that is accessed, use
1757 volatile but do not use bitfields.
1758
1759 @item
1760 GCC comes with shell scripts to fix certain known problems in system
1761 header files.  They install corrected copies of various header files in
1762 a special directory where only GCC will normally look for them.  The
1763 scripts adapt to various systems by searching all the system header
1764 files for the problem cases that we know about.
1765
1766 If new system header files are installed, nothing automatically arranges
1767 to update the corrected header files.  You will have to reinstall GCC
1768 to fix the new header files.  More specifically, go to the build
1769 directory and delete the files @file{stmp-fixinc} and
1770 @file{stmp-headers}, and the subdirectory @code{include}; then do
1771 @samp{make install} again.
1772
1773 @item
1774 @cindex floating point precision
1775 On 68000 and x86 systems, for instance, you can get paradoxical results
1776 if you test the precise values of floating point numbers.  For example,
1777 you can find that a floating point value which is not a NaN is not equal
1778 to itself.  This results from the fact that the floating point registers
1779 hold a few more bits of precision than fit in a @code{double} in memory.
1780 Compiled code moves values between memory and floating point registers
1781 at its convenience, and moving them into memory truncates them.
1782
1783 You can partially avoid this problem by using the @samp{-ffloat-store}
1784 option (@pxref{Optimize Options}).
1785
1786 @item
1787 On the MIPS, variable argument functions using @file{varargs.h}
1788 cannot have a floating point value for the first argument.  The
1789 reason for this is that in the absence of a prototype in scope,
1790 if the first argument is a floating point, it is passed in a
1791 floating point register, rather than an integer register.
1792
1793 If the code is rewritten to use the ISO standard @file{stdarg.h}
1794 method of variable arguments, and the prototype is in scope at
1795 the time of the call, everything will work fine.
1796
1797 @item
1798 On the H8/300 and H8/300H, variable argument functions must be
1799 implemented using the ISO standard @file{stdarg.h} method of
1800 variable arguments.  Furthermore, calls to functions using @file{stdarg.h}
1801 variable arguments must have a prototype for the called function
1802 in scope at the time of the call.
1803 @end itemize
1804
1805 @node C++ Misunderstandings
1806 @section Common Misunderstandings with GNU C++
1807
1808 @cindex misunderstandings in C++
1809 @cindex surprises in C++
1810 @cindex C++ misunderstandings
1811 C++ is a complex language and an evolving one, and its standard
1812 definition (the ISO C++ standard) was only recently completed.  As a
1813 result, your C++ compiler may occasionally surprise you, even when its
1814 behavior is correct.  This section discusses some areas that frequently
1815 give rise to questions of this sort.
1816
1817 @menu
1818 * Static Definitions::  Static member declarations are not definitions
1819 * Temporaries::         Temporaries may vanish before you expect
1820 * Copy Assignment::     Copy Assignment operators copy virtual bases twice
1821 @end menu
1822
1823 @node Static Definitions
1824 @subsection Declare @emph{and} Define Static Members
1825
1826 @cindex C++ static data, declaring and defining
1827 @cindex static data in C++, declaring and defining
1828 @cindex declaring static data in C++
1829 @cindex defining static data in C++
1830 When a class has static data members, it is not enough to @emph{declare}
1831 the static member; you must also @emph{define} it.  For example:
1832
1833 @example
1834 class Foo
1835 @{
1836   @dots{}
1837   void method();
1838   static int bar;
1839 @};
1840 @end example
1841
1842 This declaration only establishes that the class @code{Foo} has an
1843 @code{int} named @code{Foo::bar}, and a member function named
1844 @code{Foo::method}.  But you still need to define @emph{both}
1845 @code{method} and @code{bar} elsewhere.  According to the ISO
1846 standard, you must supply an initializer in one (and only one) source
1847 file, such as:
1848
1849 @example
1850 int Foo::bar = 0;
1851 @end example
1852
1853 Other C++ compilers may not correctly implement the standard behavior.
1854 As a result, when you switch to @code{g++} from one of these compilers,
1855 you may discover that a program that appeared to work correctly in fact
1856 does not conform to the standard: @code{g++} reports as undefined
1857 symbols any static data members that lack definitions.
1858
1859 @node Temporaries
1860 @subsection Temporaries May Vanish Before You Expect
1861
1862 @cindex temporaries, lifetime of
1863 @cindex portions of temporary objects, pointers to
1864 It is dangerous to use pointers or references to @emph{portions} of a
1865 temporary object.  The compiler may very well delete the object before
1866 you expect it to, leaving a pointer to garbage.  The most common place
1867 where this problem crops up is in classes like string classes,
1868 especially ones that define a conversion function to type @code{char *}
1869 or @code{const char *} -- which is one reason why the standard
1870 @code{string} class requires you to call the @code{c_str} member
1871 function.  However, any class that returns a pointer to some internal
1872 structure is potentially subject to this problem.
1873
1874 For example, a program may use a function @code{strfunc} that returns
1875 @code{string} objects, and another function @code{charfunc} that
1876 operates on pointers to @code{char}:
1877
1878 @example
1879 string strfunc ();
1880 void charfunc (const char *);
1881
1882 void 
1883 f ()
1884 @{
1885   const char *p = strfunc().c_str();
1886   ...
1887   charfunc (p);
1888   ...
1889   charfunc (p);
1890 @}
1891 @end example
1892
1893 @noindent
1894 In this situation, it may seem reasonable to save a pointer to the C
1895 string returned by the @code{c_str} member function and use that rather
1896 than call @code{c_str} repeatedly.  However, the temporary string
1897 created by the call to @code{strfunc} is destroyed after @code{p} is
1898 initialized, at which point @code{p} is left pointing to freed memory.
1899
1900 Code like this may run successfully under some other compilers,
1901 particularly obsolete cfront-based compilers that delete temporaries
1902 along with normal local variables.  However, the GNU C++ behavior is
1903 standard-conforming, so if your program depends on late destruction of
1904 temporaries it is not portable.
1905
1906 The safe way to write such code is to give the temporary a name, which
1907 forces it to remain until the end of the scope of the name.  For
1908 example:
1909
1910 @example
1911 string& tmp = strfunc ();
1912 charfunc (tmp.c_str ());
1913 @end example
1914
1915 @node Copy Assignment
1916 @subsection Implicit Copy-Assignment for Virtual Bases
1917
1918 When a base class is virtual, only one subobject of the base class
1919 belongs to each full object. Also, the constructors and destructors are
1920 invoked only once, and called from the most-derived class. However, such
1921 objects behave unspecified when being assigned. For example:
1922
1923 @example
1924 struct Base@{
1925   char *name;
1926   Base(char *n) : name(strdup(n))@{@}
1927   Base& operator= (const Base& other)@{
1928    free (name);
1929    name = strdup (other.name);
1930   @}
1931 @};
1932
1933 struct A:virtual Base@{
1934   int val;
1935   A():Base("A")@{@}
1936 @};
1937
1938 struct B:virtual Base@{
1939   int bval;
1940   B():Base("B")@{@}
1941 @};
1942
1943 struct Derived:public A, public B@{
1944   Derived():Base("Derived")@{@}
1945 @};
1946
1947 void func(Derived &d1, Derived &d2)
1948 @{
1949   d1 = d2;
1950 @}
1951 @end example
1952
1953 The C++ standard specifies that @samp{Base::Base} is only called once
1954 when constructing or copy-constructing a Derived object. It is
1955 unspecified whether @samp{Base::operator=} is called more than once when
1956 the implicit copy-assignment for Derived objects is invoked (as it is
1957 inside @samp{func} in the example).
1958
1959 g++ implements the "intuitive" algorithm for copy-assignment: assign all
1960 direct bases, then assign all members. In that algorithm, the virtual
1961 base subobject can be encountered many times. In the example, copying
1962 proceeds in the following order: @samp{val}, @samp{name} (via
1963 @code{strdup}), @samp{bval}, and @samp{name} again.
1964
1965 If application code relies on copy-assignment, a user-defined
1966 copy-assignment operator removes any uncertainties. With such an
1967 operator, the application can define whether and how the virtual base
1968 subobject is assigned.
1969
1970 @node Protoize Caveats
1971 @section Caveats of using @code{protoize}
1972
1973 The conversion programs @code{protoize} and @code{unprotoize} can
1974 sometimes change a source file in a way that won't work unless you
1975 rearrange it.
1976
1977 @itemize @bullet
1978 @item
1979 @code{protoize} can insert references to a type name or type tag before
1980 the definition, or in a file where they are not defined.
1981
1982 If this happens, compiler error messages should show you where the new
1983 references are, so fixing the file by hand is straightforward.
1984
1985 @item
1986 There are some C constructs which @code{protoize} cannot figure out.
1987 For example, it can't determine argument types for declaring a
1988 pointer-to-function variable; this you must do by hand.  @code{protoize}
1989 inserts a comment containing @samp{???} each time it finds such a
1990 variable; so you can find all such variables by searching for this
1991 string.  ISO C does not require declaring the argument types of
1992 pointer-to-function types.
1993
1994 @item
1995 Using @code{unprotoize} can easily introduce bugs.  If the program
1996 relied on prototypes to bring about conversion of arguments, these
1997 conversions will not take place in the program without prototypes.
1998 One case in which you can be sure @code{unprotoize} is safe is when
1999 you are removing prototypes that were made with @code{protoize}; if
2000 the program worked before without any prototypes, it will work again
2001 without them.
2002
2003 You can find all the places where this problem might occur by compiling
2004 the program with the @samp{-Wconversion} option.  It prints a warning
2005 whenever an argument is converted.
2006
2007 @item
2008 Both conversion programs can be confused if there are macro calls in and
2009 around the text to be converted.  In other words, the standard syntax
2010 for a declaration or definition must not result from expanding a macro.
2011 This problem is inherent in the design of C and cannot be fixed.  If
2012 only a few functions have confusing macro calls, you can easily convert
2013 them manually.
2014
2015 @item
2016 @code{protoize} cannot get the argument types for a function whose
2017 definition was not actually compiled due to preprocessing conditionals.
2018 When this happens, @code{protoize} changes nothing in regard to such
2019 a function.  @code{protoize} tries to detect such instances and warn
2020 about them.
2021
2022 You can generally work around this problem by using @code{protoize} step
2023 by step, each time specifying a different set of @samp{-D} options for
2024 compilation, until all of the functions have been converted.  There is
2025 no automatic way to verify that you have got them all, however.
2026
2027 @item
2028 Confusion may result if there is an occasion to convert a function
2029 declaration or definition in a region of source code where there is more
2030 than one formal parameter list present.  Thus, attempts to convert code
2031 containing multiple (conditionally compiled) versions of a single
2032 function header (in the same vicinity) may not produce the desired (or
2033 expected) results.
2034
2035 If you plan on converting source files which contain such code, it is
2036 recommended that you first make sure that each conditionally compiled
2037 region of source code which contains an alternative function header also
2038 contains at least one additional follower token (past the final right
2039 parenthesis of the function header).  This should circumvent the
2040 problem.
2041
2042 @item
2043 @code{unprotoize} can become confused when trying to convert a function
2044 definition or declaration which contains a declaration for a
2045 pointer-to-function formal argument which has the same name as the
2046 function being defined or declared.  We recommend you avoid such choices
2047 of formal parameter names.
2048
2049 @item
2050 You might also want to correct some of the indentation by hand and break
2051 long lines.  (The conversion programs don't write lines longer than
2052 eighty characters in any case.)
2053 @end itemize
2054
2055 @node Non-bugs
2056 @section Certain Changes We Don't Want to Make
2057
2058 This section lists changes that people frequently request, but which
2059 we do not make because we think GCC is better without them.
2060
2061 @itemize @bullet
2062 @item
2063 Checking the number and type of arguments to a function which has an
2064 old-fashioned definition and no prototype.
2065
2066 Such a feature would work only occasionally---only for calls that appear
2067 in the same file as the called function, following the definition.  The
2068 only way to check all calls reliably is to add a prototype for the
2069 function.  But adding a prototype eliminates the motivation for this
2070 feature.  So the feature is not worthwhile.
2071
2072 @item
2073 Warning about using an expression whose type is signed as a shift count.
2074
2075 Shift count operands are probably signed more often than unsigned.
2076 Warning about this would cause far more annoyance than good.
2077
2078 @item
2079 Warning about assigning a signed value to an unsigned variable.
2080
2081 Such assignments must be very common; warning about them would cause
2082 more annoyance than good.
2083
2084 @item
2085 Warning when a non-void function value is ignored.
2086
2087 Coming as I do from a Lisp background, I balk at the idea that there is
2088 something dangerous about discarding a value.  There are functions that
2089 return values which some callers may find useful; it makes no sense to
2090 clutter the program with a cast to @code{void} whenever the value isn't
2091 useful.
2092
2093 @item
2094 Assuming (for optimization) that the address of an external symbol is
2095 never zero.
2096
2097 This assumption is false on certain systems when @samp{#pragma weak} is
2098 used.
2099
2100 @item
2101 Making @samp{-fshort-enums} the default.
2102
2103 This would cause storage layout to be incompatible with most other C
2104 compilers.  And it doesn't seem very important, given that you can get
2105 the same result in other ways.  The case where it matters most is when
2106 the enumeration-valued object is inside a structure, and in that case
2107 you can specify a field width explicitly.
2108
2109 @item
2110 Making bitfields unsigned by default on particular machines where ``the
2111 ABI standard'' says to do so.
2112
2113 The ISO C standard leaves it up to the implementation whether a bitfield
2114 declared plain @code{int} is signed or not.  This in effect creates two
2115 alternative dialects of C.
2116
2117 The GNU C compiler supports both dialects; you can specify the signed
2118 dialect with @samp{-fsigned-bitfields} and the unsigned dialect with
2119 @samp{-funsigned-bitfields}.  However, this leaves open the question of
2120 which dialect to use by default.
2121
2122 Currently, the preferred dialect makes plain bitfields signed, because
2123 this is simplest.  Since @code{int} is the same as @code{signed int} in
2124 every other context, it is cleanest for them to be the same in bitfields
2125 as well.
2126
2127 Some computer manufacturers have published Application Binary Interface
2128 standards which specify that plain bitfields should be unsigned.  It is
2129 a mistake, however, to say anything about this issue in an ABI.  This is
2130 because the handling of plain bitfields distinguishes two dialects of C.
2131 Both dialects are meaningful on every type of machine.  Whether a
2132 particular object file was compiled using signed bitfields or unsigned
2133 is of no concern to other object files, even if they access the same
2134 bitfields in the same data structures.
2135
2136 A given program is written in one or the other of these two dialects.
2137 The program stands a chance to work on most any machine if it is
2138 compiled with the proper dialect.  It is unlikely to work at all if
2139 compiled with the wrong dialect.
2140
2141 Many users appreciate the GNU C compiler because it provides an
2142 environment that is uniform across machines.  These users would be
2143 inconvenienced if the compiler treated plain bitfields differently on
2144 certain machines.
2145
2146 Occasionally users write programs intended only for a particular machine
2147 type.  On these occasions, the users would benefit if the GNU C compiler
2148 were to support by default the same dialect as the other compilers on
2149 that machine.  But such applications are rare.  And users writing a
2150 program to run on more than one type of machine cannot possibly benefit
2151 from this kind of compatibility.
2152
2153 This is why GCC does and will treat plain bitfields in the same
2154 fashion on all types of machines (by default).
2155
2156 There are some arguments for making bitfields unsigned by default on all
2157 machines.  If, for example, this becomes a universal de facto standard,
2158 it would make sense for GCC to go along with it.  This is something
2159 to be considered in the future.
2160
2161 (Of course, users strongly concerned about portability should indicate
2162 explicitly in each bitfield whether it is signed or not.  In this way,
2163 they write programs which have the same meaning in both C dialects.)
2164
2165 @item
2166 Undefining @code{__STDC__} when @samp{-ansi} is not used.
2167
2168 Currently, GCC defines @code{__STDC__} as long as you don't use
2169 @samp{-traditional}.  This provides good results in practice.
2170
2171 Programmers normally use conditionals on @code{__STDC__} to ask whether
2172 it is safe to use certain features of ISO C, such as function
2173 prototypes or ISO token concatenation.  Since plain @samp{gcc} supports
2174 all the features of ISO C, the correct answer to these questions is
2175 ``yes''.
2176
2177 Some users try to use @code{__STDC__} to check for the availability of
2178 certain library facilities.  This is actually incorrect usage in an ISO
2179 C program, because the ISO C standard says that a conforming
2180 freestanding implementation should define @code{__STDC__} even though it
2181 does not have the library facilities.  @samp{gcc -ansi -pedantic} is a
2182 conforming freestanding implementation, and it is therefore required to
2183 define @code{__STDC__}, even though it does not come with an ISO C
2184 library.
2185
2186 Sometimes people say that defining @code{__STDC__} in a compiler that
2187 does not completely conform to the ISO C standard somehow violates the
2188 standard.  This is illogical.  The standard is a standard for compilers
2189 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
2190 compilers such as plain @samp{gcc}.  Whatever the ISO C standard says
2191 is relevant to the design of plain @samp{gcc} without @samp{-ansi} only
2192 for pragmatic reasons, not as a requirement.
2193
2194 GCC normally defines @code{__STDC__} to be 1, and in addition
2195 defines @code{__STRICT_ANSI__} if you specify the @samp{-ansi} option.
2196 On some hosts, system include files use a different convention, where
2197 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
2198 conformance to the C Standard.  GCC follows the host convention when
2199 processing system include files, but when processing user files it follows
2200 the usual GNU C convention.
2201
2202 @item
2203 Undefining @code{__STDC__} in C++.
2204
2205 Programs written to compile with C++-to-C translators get the
2206 value of @code{__STDC__} that goes with the C compiler that is
2207 subsequently used.  These programs must test @code{__STDC__}
2208 to determine what kind of C preprocessor that compiler uses:
2209 whether they should concatenate tokens in the ISO C fashion
2210 or in the traditional fashion.
2211
2212 These programs work properly with GNU C++ if @code{__STDC__} is defined.
2213 They would not work otherwise.
2214
2215 In addition, many header files are written to provide prototypes in ISO
2216 C but not in traditional C.  Many of these header files can work without
2217 change in C++ provided @code{__STDC__} is defined.  If @code{__STDC__}
2218 is not defined, they will all fail, and will all need to be changed to
2219 test explicitly for C++ as well.
2220
2221 @item
2222 Deleting ``empty'' loops.
2223
2224 Historically, GCC has not deleted ``empty'' loops under the
2225 assumption that the most likely reason you would put one in a program is
2226 to have a delay, so deleting them will not make real programs run any
2227 faster.
2228
2229 However, the rationale here is that optimization of a nonempty loop
2230 cannot produce an empty one, which holds for C but is not always the
2231 case for C++.
2232
2233 Moreover, with @samp{-funroll-loops} small ``empty'' loops are already
2234 removed, so the current behavior is both sub-optimal and inconsistent
2235 and will change in the future.
2236
2237 @item
2238 Making side effects happen in the same order as in some other compiler.
2239
2240 @cindex side effects, order of evaluation
2241 @cindex order of evaluation, side effects
2242 It is never safe to depend on the order of evaluation of side effects.
2243 For example, a function call like this may very well behave differently
2244 from one compiler to another:
2245
2246 @example
2247 void func (int, int);
2248
2249 int i = 2;
2250 func (i++, i++);
2251 @end example
2252
2253 There is no guarantee (in either the C or the C++ standard language
2254 definitions) that the increments will be evaluated in any particular
2255 order.  Either increment might happen first.  @code{func} might get the
2256 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
2257
2258 @item
2259 Not allowing structures with volatile fields in registers.
2260
2261 Strictly speaking, there is no prohibition in the ISO C standard
2262 against allowing structures with volatile fields in registers, but
2263 it does not seem to make any sense and is probably not what you wanted
2264 to do.  So the compiler will give an error message in this case.
2265
2266 @item
2267 Making certain warnings into errors by default.
2268
2269 Some ISO C testsuites report failure when the compiler does not produce
2270 an error message for a certain program.
2271
2272 ISO C requires a ``diagnostic'' message for certain kinds of invalid
2273 programs, but a warning is defined by GCC to count as a diagnostic.  If
2274 GCC produces a warning but not an error, that is correct ISO C support.
2275 If test suites call this ``failure'', they should be run with the GCC
2276 option @samp{-pedantic-errors}, which will turn these warnings into
2277 errors.
2278
2279 @end itemize
2280
2281 @node Warnings and Errors
2282 @section Warning Messages and Error Messages
2283
2284 @cindex error messages
2285 @cindex warnings vs errors
2286 @cindex messages, warning and error
2287 The GNU compiler can produce two kinds of diagnostics: errors and
2288 warnings.  Each kind has a different purpose:
2289
2290 @itemize @w{}
2291 @item
2292 @emph{Errors} report problems that make it impossible to compile your
2293 program.  GCC reports errors with the source file name and line
2294 number where the problem is apparent.
2295
2296 @item
2297 @emph{Warnings} report other unusual conditions in your code that
2298 @emph{may} indicate a problem, although compilation can (and does)
2299 proceed.  Warning messages also report the source file name and line
2300 number, but include the text @samp{warning:} to distinguish them
2301 from error messages.
2302 @end itemize
2303
2304 Warnings may indicate danger points where you should check to make sure
2305 that your program really does what you intend; or the use of obsolete
2306 features; or the use of nonstandard features of GNU C or C++.  Many
2307 warnings are issued only if you ask for them, with one of the @samp{-W}
2308 options (for instance, @samp{-Wall} requests a variety of useful
2309 warnings).
2310
2311 GCC always tries to compile your program if possible; it never
2312 gratuitously rejects a program whose meaning is clear merely because
2313 (for instance) it fails to conform to a standard.  In some cases,
2314 however, the C and C++ standards specify that certain extensions are
2315 forbidden, and a diagnostic @emph{must} be issued by a conforming
2316 compiler.  The @samp{-pedantic} option tells GCC to issue warnings in
2317 such cases; @samp{-pedantic-errors} says to make them errors instead.
2318 This does not mean that @emph{all} non-ISO constructs get warnings
2319 or errors.
2320
2321 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
2322 more detail on these and related command-line options.
2323
2324 @node Bugs
2325 @chapter Reporting Bugs
2326 @cindex bugs
2327 @cindex reporting bugs
2328
2329 Your bug reports play an essential role in making GCC reliable.
2330
2331 When you encounter a problem, the first thing to do is to see if it is
2332 already known.  @xref{Trouble}.  If it isn't known, then you should
2333 report the problem.
2334
2335 Reporting a bug may help you by bringing a solution to your problem, or
2336 it may not.  (If it does not, look in the service directory; see
2337 @ref{Service}.)  In any case, the principal function of a bug report is
2338 to help the entire community by making the next version of GCC work
2339 better.  Bug reports are your contribution to the maintenance of GCC.
2340
2341 Since the maintainers are very overloaded, we cannot respond to every
2342 bug report.  However, if the bug has not been fixed, we are likely to
2343 send you a patch and ask you to tell us whether it works.
2344
2345 In order for a bug report to serve its purpose, you must include the
2346 information that makes for fixing the bug.
2347
2348 @menu
2349 * Criteria:  Bug Criteria.   Have you really found a bug?
2350 * Where: Bug Lists.          Where to send your bug report.
2351 * Reporting: Bug Reporting.  How to report a bug effectively.
2352 * GNATS: gccbug.             You can use a bug reporting tool.
2353 * Patches: Sending Patches.  How to send a patch for GCC.
2354 * Known: Trouble.            Known problems.
2355 * Help: Service.             Where to ask for help.
2356 @end menu
2357
2358 @node Bug Criteria,Bug Lists,,Bugs
2359 @section Have You Found a Bug?
2360 @cindex bug criteria
2361
2362 If you are not sure whether you have found a bug, here are some guidelines:
2363
2364 @itemize @bullet
2365 @cindex fatal signal
2366 @cindex core dump
2367 @item
2368 If the compiler gets a fatal signal, for any input whatever, that is a
2369 compiler bug.  Reliable compilers never crash.
2370
2371 @cindex invalid assembly code
2372 @cindex assembly code, invalid
2373 @item
2374 If the compiler produces invalid assembly code, for any input whatever
2375 (except an @code{asm} statement), that is a compiler bug, unless the
2376 compiler reports errors (not just warnings) which would ordinarily
2377 prevent the assembler from being run.
2378
2379 @cindex undefined behavior
2380 @cindex undefined function value
2381 @cindex increment operators
2382 @item
2383 If the compiler produces valid assembly code that does not correctly
2384 execute the input source code, that is a compiler bug.
2385
2386 However, you must double-check to make sure, because you may have run
2387 into an incompatibility between GNU C and traditional C
2388 (@pxref{Incompatibilities}).  These incompatibilities might be considered
2389 bugs, but they are inescapable consequences of valuable features.
2390
2391 Or you may have a program whose behavior is undefined, which happened
2392 by chance to give the desired results with another C or C++ compiler.
2393
2394 For example, in many nonoptimizing compilers, you can write @samp{x;}
2395 at the end of a function instead of @samp{return x;}, with the same
2396 results.  But the value of the function is undefined if @code{return}
2397 is omitted; it is not a bug when GCC produces different results.
2398
2399 Problems often result from expressions with two increment operators,
2400 as in @code{f (*p++, *p++)}.  Your previous compiler might have
2401 interpreted that expression the way you intended; GCC might
2402 interpret it another way.  Neither compiler is wrong.  The bug is
2403 in your code.
2404
2405 After you have localized the error to a single source line, it should
2406 be easy to check for these things.  If your program is correct and
2407 well defined, you have found a compiler bug.
2408
2409 @item
2410 If the compiler produces an error message for valid input, that is a
2411 compiler bug.
2412
2413 @cindex invalid input
2414 @item
2415 If the compiler does not produce an error message for invalid input,
2416 that is a compiler bug.  However, you should note that your idea of
2417 ``invalid input'' might be my idea of ``an extension'' or ``support
2418 for traditional practice''.
2419
2420 @item
2421 If you are an experienced user of one of the languages GCC supports, your 
2422 suggestions for improvement of GCC are welcome in any case.
2423 @end itemize
2424
2425 @node Bug Lists,Bug Reporting,Bug Criteria,Bugs
2426 @section Where to Report Bugs
2427 @cindex bug report mailing lists
2428 @kindex gcc-bugs@@gcc.gnu.org or bug-gcc@@gnu.org
2429 Send bug reports for the GNU Compiler Collection to
2430 @email{gcc-bugs@@gcc.gnu.org}.  In accordance with the GNU-wide
2431 convention, in which bug reports for tool ``foo'' are sent
2432 to @samp{bug-foo@@gnu.org}, the address @email{bug-gcc@@gnu.org}
2433 may also be used; it will forward to the address given above.
2434
2435 Please read @uref{http://www.gnu.org/software/gcc/bugs.html} for
2436 bug reporting instructions before you post a bug report.
2437
2438 Often people think of posting bug reports to the newsgroup instead of
2439 mailing them.  This appears to work, but it has one problem which can be
2440 crucial: a newsgroup posting does not contain a mail path back to the
2441 sender.  Thus, if maintainers need more information, they may be unable
2442 to reach you.  For this reason, you should always send bug reports by
2443 mail to the proper mailing list.
2444
2445 As a last resort, send bug reports on paper to:
2446
2447 @example
2448 GNU Compiler Bugs
2449 Free Software Foundation
2450 59 Temple Place - Suite 330
2451 Boston, MA 02111-1307, USA
2452 @end example
2453
2454 @node Bug Reporting,gccbug,Bug Lists,Bugs
2455 @section How to Report Bugs
2456 @cindex compiler bugs, reporting
2457
2458 You may find additional and/or more up-to-date instructions at
2459 @uref{http://www.gnu.org/software/gcc/bugs.html}.
2460
2461 The fundamental principle of reporting bugs usefully is this:
2462 @strong{report all the facts}.  If you are not sure whether to state a
2463 fact or leave it out, state it!
2464
2465 Often people omit facts because they think they know what causes the
2466 problem and they conclude that some details don't matter.  Thus, you might
2467 assume that the name of the variable you use in an example does not matter.
2468 Well, probably it doesn't, but one cannot be sure.  Perhaps the bug is a
2469 stray memory reference which happens to fetch from the location where that
2470 name is stored in memory; perhaps, if the name were different, the contents
2471 of that location would fool the compiler into doing the right thing despite
2472 the bug.  Play it safe and give a specific, complete example.  That is the
2473 easiest thing for you to do, and the most helpful.
2474
2475 Keep in mind that the purpose of a bug report is to enable someone to
2476 fix the bug if it is not known.  It isn't very important what happens if
2477 the bug is already known.  Therefore, always write your bug reports on
2478 the assumption that the bug is not known.
2479
2480 Sometimes people give a few sketchy facts and ask, ``Does this ring a
2481 bell?''  This cannot help us fix a bug, so it is basically useless.  We
2482 respond by asking for enough details to enable us to investigate.
2483 You might as well expedite matters by sending them to begin with.
2484
2485 Try to make your bug report self-contained.  If we have to ask you for
2486 more information, it is best if you include all the previous information
2487 in your response, as well as the information that was missing.
2488
2489 Please report each bug in a separate message.  This makes it easier for
2490 us to track which bugs have been fixed and to forward your bugs reports
2491 to the appropriate maintainer.
2492
2493 To enable someone to investigate the bug, you should include all these
2494 things:
2495
2496 @itemize @bullet
2497 @item
2498 The version of GCC.  You can get this by running it with the
2499 @samp{-v} option.
2500
2501 Without this, we won't know whether there is any point in looking for
2502 the bug in the current version of GCC.
2503
2504 @item
2505 A complete input file that will reproduce the bug.  If the bug is in the
2506 C preprocessor, send a source file and any header files that it
2507 requires.  If the bug is in the compiler proper (@file{cc1}), send the
2508 preprocessor output generated by adding @samp{-save-temps} to the
2509 compilation command (@pxref{Debugging Options}).  When you do this, use
2510 the same @samp{-I}, @samp{-D} or @samp{-U} options that you used in
2511 actual compilation. Then send the @var{input}.i or @var{input}.ii files
2512 generated.
2513
2514 A single statement is not enough of an example.  In order to compile it,
2515 it must be embedded in a complete file of compiler input; and the bug
2516 might depend on the details of how this is done.
2517
2518 Without a real example one can compile, all anyone can do about your bug
2519 report is wish you luck.  It would be futile to try to guess how to
2520 provoke the bug.  For example, bugs in register allocation and reloading
2521 frequently depend on every little detail of the function they happen in.
2522
2523 Even if the input file that fails comes from a GNU program, you should
2524 still send the complete test case.  Don't ask the GCC maintainers to
2525 do the extra work of obtaining the program in question---they are all
2526 overworked as it is.  Also, the problem may depend on what is in the
2527 header files on your system; it is unreliable for the GCC maintainers
2528 to try the problem with the header files available to them.  By sending
2529 CPP output, you can eliminate this source of uncertainty and save us
2530 a certain percentage of wild goose chases.
2531
2532 @item
2533 The command arguments you gave GCC to compile that example
2534 and observe the bug.  For example, did you use @samp{-O}?  To guarantee
2535 you won't omit something important, list all the options.
2536
2537 If we were to try to guess the arguments, we would probably guess wrong
2538 and then we would not encounter the bug.
2539
2540 @item
2541 The type of machine you are using, and the operating system name and
2542 version number.
2543
2544 @item
2545 The operands you gave to the @code{configure} command when you installed
2546 the compiler.
2547
2548 @item
2549 A complete list of any modifications you have made to the compiler
2550 source.  (We don't promise to investigate the bug unless it happens in
2551 an unmodified compiler.  But if you've made modifications and don't tell
2552 us, then you are sending us on a wild goose chase.)
2553
2554 Be precise about these changes.  A description in English is not
2555 enough---send a context diff for them.
2556
2557 Adding files of your own (such as a machine description for a machine we
2558 don't support) is a modification of the compiler source.
2559
2560 @item
2561 Details of any other deviations from the standard procedure for installing
2562 GCC.
2563
2564 @item
2565 A description of what behavior you observe that you believe is
2566 incorrect.  For example, ``The compiler gets a fatal signal,'' or,
2567 ``The assembler instruction at line 208 in the output is incorrect.''
2568
2569 Of course, if the bug is that the compiler gets a fatal signal, then one
2570 can't miss it.  But if the bug is incorrect output, the maintainer might
2571 not notice unless it is glaringly wrong.  None of us has time to study
2572 all the assembler code from a 50-line C program just on the chance that
2573 one instruction might be wrong.  We need @emph{you} to do this part!
2574
2575 Even if the problem you experience is a fatal signal, you should still
2576 say so explicitly.  Suppose something strange is going on, such as, your
2577 copy of the compiler is out of synch, or you have encountered a bug in
2578 the C library on your system.  (This has happened!)  Your copy might
2579 crash and the copy here would not.  If you @i{said} to expect a crash,
2580 then when the compiler here fails to crash, we would know that the bug
2581 was not happening.  If you don't say to expect a crash, then we would
2582 not know whether the bug was happening.  We would not be able to draw
2583 any conclusion from our observations.
2584
2585 If the problem is a diagnostic when compiling GCC with some other
2586 compiler, say whether it is a warning or an error.
2587
2588 Often the observed symptom is incorrect output when your program is run.
2589 Sad to say, this is not enough information unless the program is short
2590 and simple.  None of us has time to study a large program to figure out
2591 how it would work if compiled correctly, much less which line of it was
2592 compiled wrong.  So you will have to do that.  Tell us which source line
2593 it is, and what incorrect result happens when that line is executed.  A
2594 person who understands the program can find this as easily as finding a
2595 bug in the program itself.
2596
2597 @item
2598 If you send examples of assembler code output from GCC,
2599 please use @samp{-g} when you make them.  The debugging information
2600 includes source line numbers which are essential for correlating the
2601 output with the input.
2602
2603 @item
2604 If you wish to mention something in the GCC source, refer to it by
2605 context, not by line number.
2606
2607 The line numbers in the development sources don't match those in your
2608 sources.  Your line numbers would convey no useful information to the
2609 maintainers.
2610
2611 @item
2612 Additional information from a debugger might enable someone to find a
2613 problem on a machine which he does not have available.  However, you
2614 need to think when you collect this information if you want it to have
2615 any chance of being useful.
2616
2617 @cindex backtrace for bug reports
2618 For example, many people send just a backtrace, but that is never
2619 useful by itself.  A simple backtrace with arguments conveys little
2620 about GCC because the compiler is largely data-driven; the same
2621 functions are called over and over for different RTL insns, doing
2622 different things depending on the details of the insn.
2623
2624 Most of the arguments listed in the backtrace are useless because they
2625 are pointers to RTL list structure.  The numeric values of the
2626 pointers, which the debugger prints in the backtrace, have no
2627 significance whatever; all that matters is the contents of the objects
2628 they point to (and most of the contents are other such pointers).
2629
2630 In addition, most compiler passes consist of one or more loops that
2631 scan the RTL insn sequence.  The most vital piece of information about
2632 such a loop---which insn it has reached---is usually in a local variable,
2633 not in an argument.
2634
2635 @findex debug_rtx
2636 What you need to provide in addition to a backtrace are the values of
2637 the local variables for several stack frames up.  When a local
2638 variable or an argument is an RTX, first print its value and then use
2639 the GDB command @code{pr} to print the RTL expression that it points
2640 to.  (If GDB doesn't run on your machine, use your debugger to call
2641 the function @code{debug_rtx} with the RTX as an argument.)  In
2642 general, whenever a variable is a pointer, its value is no use
2643 without the data it points to.
2644 @end itemize
2645
2646 Here are some things that are not necessary:
2647
2648 @itemize @bullet
2649 @item
2650 A description of the envelope of the bug.
2651
2652 Often people who encounter a bug spend a lot of time investigating
2653 which changes to the input file will make the bug go away and which
2654 changes will not affect it.
2655
2656 This is often time consuming and not very useful, because the way we
2657 will find the bug is by running a single example under the debugger with
2658 breakpoints, not by pure deduction from a series of examples.  You might
2659 as well save your time for something else.
2660
2661 Of course, if you can find a simpler example to report @emph{instead} of
2662 the original one, that is a convenience.  Errors in the output will be
2663 easier to spot, running under the debugger will take less time, etc.
2664 Most GCC bugs involve just one function, so the most straightforward
2665 way to simplify an example is to delete all the function definitions
2666 except the one where the bug occurs.  Those earlier in the file may be
2667 replaced by external declarations if the crucial function depends on
2668 them.  (Exception: inline functions may affect compilation of functions
2669 defined later in the file.)
2670
2671 However, simplification is not vital; if you don't want to do this,
2672 report the bug anyway and send the entire test case you used.
2673
2674 @item
2675 In particular, some people insert conditionals @samp{#ifdef BUG} around
2676 a statement which, if removed, makes the bug not happen.  These are just
2677 clutter; we won't pay any attention to them anyway.  Besides, you should
2678 send us cpp output, and that can't have conditionals.
2679
2680 @item
2681 A patch for the bug.
2682
2683 A patch for the bug is useful if it is a good one.  But don't omit the
2684 necessary information, such as the test case, on the assumption that a
2685 patch is all we need.  We might see problems with your patch and decide
2686 to fix the problem another way, or we might not understand it at all.
2687
2688 Sometimes with a program as complicated as GCC it is very hard to
2689 construct an example that will make the program follow a certain path
2690 through the code.  If you don't send the example, we won't be able to
2691 construct one, so we won't be able to verify that the bug is fixed.
2692
2693 And if we can't understand what bug you are trying to fix, or why your
2694 patch should be an improvement, we won't install it.  A test case will
2695 help us to understand.
2696
2697 @xref{Sending Patches}, for guidelines on how to make it easy for us to
2698 understand and install your patches.
2699
2700 @item
2701 A guess about what the bug is or what it depends on.
2702
2703 Such guesses are usually wrong.  Even I can't guess right about such
2704 things without first using the debugger to find the facts.
2705
2706 @item
2707 A core dump file.
2708
2709 We have no way of examining a core dump for your type of machine
2710 unless we have an identical system---and if we do have one,
2711 we should be able to reproduce the crash ourselves.
2712 @end itemize
2713
2714 @node gccbug,Sending Patches, Bug Reporting, Bugs
2715 @section The gccbug script
2716 @cindex gccbug script
2717
2718 To simplify creation of bug reports, and to allow better tracking of
2719 reports, we use the GNATS bug tracking system. Part of that system is
2720 the @code{gccbug} script. This is a Unix shell script, so you need a
2721 shell to run it. It is normally installed in the same directory where
2722 @code{gcc} is installed.
2723
2724 The gccbug script is derived from send-pr, @pxref{using
2725 send-pr,,Creating new Problem Reports,send-pr,Reporting Problems}. When
2726 invoked, it starts a text editor so you can fill out the various fields
2727 of the report. When the you quit the editor, the report is automatically
2728 send to the bug reporting address.
2729
2730 A number of fields in this bug report form are specific to GCC, and are
2731 explained here.
2732
2733 @table @code
2734
2735 @cindex @code{Category} field
2736 @cindex @code{>Category:}
2737 @item >Category:
2738 The category of a GCC problem can be one of the following:
2739
2740 @table @code
2741 @item c
2742 A problem with the C compiler proper.
2743 driver.
2744
2745 @item c++
2746 A problem with the C++ compiler.
2747 driver.
2748
2749 @item fortran
2750 A problem with the Fortran 77.
2751
2752 @item java
2753 A problem with the Java compiler.
2754
2755 @item objc
2756 A problem with the Objective C compiler.
2757
2758 @item libstdc++
2759 A problem with the C++ standard library.
2760
2761 @item libf2c
2762 A problem with the Fortran 77 library.
2763
2764 @item libobjc
2765 A problem with the Objective C library.
2766
2767 @item optimization
2768 The problem occurs only when generating optimized code.
2769
2770 @item debug
2771 The problem occurs only when generating code for debugging.
2772
2773 @item target
2774 The problem is specific to the target architecture.
2775
2776 @item middle-end
2777 The problem is independent from target architecture and programming
2778 language.
2779
2780 @item other
2781 It is a problem in some other part of the GCC software.
2782
2783 @item web
2784 There is a problem with the GCC home page.
2785
2786 @end table
2787
2788 @cindex @code{Class} field
2789 @cindex @code{>Class:}
2790 @item >Class:
2791 The class of a problem can be one of the following:
2792
2793 @table @code
2794 @cindex @emph{doc-bug} class
2795 @item doc-bug
2796 A problem with the documentation.
2797
2798 @cindex @emph{accepts-illegal} class
2799 @item accepts-illegal
2800 GCC fails to reject erroneous code.
2801
2802 @cindex @emph{rejects-legal} class
2803 @item rejects-legal    
2804 GCC gives an error message for correct code.
2805
2806 @cindex @emph{wrong-code} class
2807 @item wrong-code       
2808 The machine code generated by gcc is incorrect.
2809
2810 @cindex @emph{ice-on-legal-code} class
2811 @item ice-on-legal-code   
2812 GCC gives an Internal Compiler Error (ICE) for correct code.
2813
2814 @cindex @emph{ice-on-illegal-code} class
2815 @item ice-on-illegal-code 
2816 GCC gives an ICE instead of reporting an error
2817
2818 @cindex @emph{pessimizes-code} class
2819 @item pessimizes-code     
2820 GCC misses an important optimization opportunity.
2821
2822 @cindex @emph{sw-bug} class
2823 @item sw-bug
2824 A general product problem.  (@samp{sw} stands for ``software''.)
2825
2826 @cindex @emph{change-request} class
2827 @item change-request
2828 A request for a change in behavior, etc.
2829
2830 @cindex @emph{support} class
2831 @item support
2832 A support problem or question.
2833
2834 @cindex @emph{duplicate} class
2835 @item duplicate (@var{pr-number})
2836 Duplicate PR.  @var{pr-number} should be the number of the original PR.
2837
2838 @noindent
2839 The default is @samp{sw-bug}.
2840 @sp 1
2841 @end table
2842
2843 @end table
2844
2845 @node Sending Patches,, gccbug, Bugs
2846 @section Sending Patches for GCC
2847
2848 If you would like to write bug fixes or improvements for the GNU C
2849 compiler, that is very helpful.  Send suggested fixes to the patches
2850 mailing list, @email{gcc-patches@@gcc.gnu.org}.
2851
2852 Please follow these guidelines so we can study your patches efficiently.
2853 If you don't follow these guidelines, your information might still be
2854 useful, but using it will take extra work.  Maintaining GNU C is a lot
2855 of work in the best of circumstances, and we can't keep up unless you do
2856 your best to help.
2857
2858 @itemize @bullet
2859 @item
2860 Send an explanation with your changes of what problem they fix or what
2861 improvement they bring about.  For a bug fix, just include a copy of the
2862 bug report, and explain why the change fixes the bug.
2863
2864 (Referring to a bug report is not as good as including it, because then
2865 we will have to look it up, and we have probably already deleted it if
2866 we've already fixed the bug.)
2867
2868 @item
2869 Always include a proper bug report for the problem you think you have
2870 fixed.  We need to convince ourselves that the change is right before
2871 installing it.  Even if it is right, we might have trouble judging it if
2872 we don't have a way to reproduce the problem.
2873
2874 @item
2875 Include all the comments that are appropriate to help people reading the
2876 source in the future understand why this change was needed.
2877
2878 @item
2879 Don't mix together changes made for different reasons.
2880 Send them @emph{individually}.
2881
2882 If you make two changes for separate reasons, then we might not want to
2883 install them both.  We might want to install just one.  If you send them
2884 all jumbled together in a single set of diffs, we have to do extra work
2885 to disentangle them---to figure out which parts of the change serve
2886 which purpose.  If we don't have time for this, we might have to ignore
2887 your changes entirely.
2888
2889 If you send each change as soon as you have written it, with its own
2890 explanation, then the two changes never get tangled up, and we can
2891 consider each one properly without any extra work to disentangle them.
2892
2893 Ideally, each change you send should be impossible to subdivide into
2894 parts that we might want to consider separately, because each of its
2895 parts gets its motivation from the other parts.
2896
2897 @item
2898 Send each change as soon as that change is finished.  Sometimes people
2899 think they are helping us by accumulating many changes to send them all
2900 together.  As explained above, this is absolutely the worst thing you
2901 could do.
2902
2903 Since you should send each change separately, you might as well send it
2904 right away.  That gives us the option of installing it immediately if it
2905 is important.
2906
2907 @item
2908 Use @samp{diff -c} to make your diffs.  Diffs without context are hard
2909 for us to install reliably.  More than that, they make it hard for us to
2910 study the diffs to decide whether we want to install them.  Unidiff
2911 format is better than contextless diffs, but not as easy to read as
2912 @samp{-c} format.
2913
2914 If you have GNU diff, use @samp{diff -cp}, which shows the name of the
2915 function that each change occurs in.
2916
2917 @item
2918 Write the change log entries for your changes.  We get lots of changes,
2919 and we don't have time to do all the change log writing ourselves.
2920
2921 Read the @file{ChangeLog} file to see what sorts of information to put
2922 in, and to learn the style that we use.  The purpose of the change log
2923 is to show people where to find what was changed.  So you need to be
2924 specific about what functions you changed; in large functions, it's
2925 often helpful to indicate where within the function the change was.
2926
2927 On the other hand, once you have shown people where to find the change,
2928 you need not explain its purpose.  Thus, if you add a new function, all
2929 you need to say about it is that it is new.  If you feel that the
2930 purpose needs explaining, it probably does---but the explanation will be
2931 much more useful if you put it in comments in the code.
2932
2933 If you would like your name to appear in the header line for who made
2934 the change, send us the header line.
2935
2936 @item
2937 When you write the fix, keep in mind that we can't install a change that
2938 would break other systems.
2939
2940 People often suggest fixing a problem by changing machine-independent
2941 files such as @file{toplev.c} to do something special that a particular
2942 system needs.  Sometimes it is totally obvious that such changes would
2943 break GCC for almost all users.  We can't possibly make a change like
2944 that.  At best it might tell us how to write another patch that would
2945 solve the problem acceptably.
2946
2947 Sometimes people send fixes that @emph{might} be an improvement in
2948 general---but it is hard to be sure of this.  It's hard to install
2949 such changes because we have to study them very carefully.  Of course,
2950 a good explanation of the reasoning by which you concluded the change
2951 was correct can help convince us.
2952
2953 The safest changes are changes to the configuration files for a
2954 particular machine.  These are safe because they can't create new bugs
2955 on other machines.
2956
2957 Please help us keep up with the workload by designing the patch in a
2958 form that is good to install.
2959 @end itemize
2960
2961 @node Service
2962 @chapter How To Get Help with GCC
2963
2964 If you need help installing, using or changing GCC, there are two
2965 ways to find it:
2966
2967 @itemize @bullet
2968 @item
2969 Send a message to a suitable network mailing list.  First try
2970 @email{gcc-help@@gcc.gnu.org} (for help installing or using GCC), and if
2971 that brings no response, try @email{gcc@@gcc.gnu.org}.  For help
2972 changing GCC, ask @email{gcc@@gcc.gnu.org}.  If you think you have found
2973 a bug in GCC, please report it following the instructions at
2974 @uref{http://gcc.gnu.org/bugs.html}.
2975
2976 @item
2977 Look in the service directory for someone who might help you for a fee.
2978 The service directory is found at
2979 @uref{http://www.gnu.org/prep/service.html}.
2980 @end itemize
2981
2982 @c For further information, see
2983 @c @uref{http://gcc.gnu.org/cgi-bin/fom.cgi?file=12}.
2984 @c FIXME: this URL may be too volatile, this FAQ entry needs to move to
2985 @c the regular web pages before we can uncomment the reference.
2986
2987 @node Contributing
2988 @chapter Contributing to GCC Development
2989
2990 If you would like to help pretest GCC releases to assure they work well,
2991 our current development sources are available by CVS (see
2992 @uref{http://gcc.gnu.org/cvs.html}).  Source and binary snapshots are
2993 also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
2994 Remember that snapshots of the current development sources may not be of
2995 production quality; if you find problems (whether compiler crashes,
2996 miscompiled code, poor optimization or any other problem), please report
2997 them following our bug reporting instructions at
2998 @uref{http://gcc.gnu.org/bugs.html}.
2999
3000 If you would like to work on improvements to GCC, please read
3001 @uref{http://gcc.gnu.org/contribute.html} and
3002 @uref{http://gcc.gnu.org/contributewhy.html} for information on how to
3003 make useful contributions and avoid duplication of effort.  Suggested
3004 projects are listed at @uref{http://gcc.gnu.org/projects/}.
3005
3006 @node VMS
3007 @chapter Using GCC on VMS
3008
3009 @c prevent bad page break with this line
3010 Here is how to use GCC on VMS.
3011
3012 @menu
3013 * Include Files and VMS::  Where the preprocessor looks for the include files.
3014 * Global Declarations::    How to do globaldef, globalref and globalvalue with
3015                            GCC.
3016 * VMS Misc::               Misc information.
3017 @end menu
3018
3019 @node Include Files and VMS
3020 @section Include Files and VMS
3021
3022 @cindex include files and VMS
3023 @cindex VMS and include files
3024 @cindex header files and VMS
3025 Due to the differences between the filesystems of Unix and VMS, GCC
3026 attempts to translate file names in @samp{#include} into names that VMS
3027 will understand.  The basic strategy is to prepend a prefix to the
3028 specification of the include file, convert the whole filename to a VMS
3029 filename, and then try to open the file.  GCC tries various prefixes
3030 one by one until one of them succeeds:
3031
3032 @enumerate
3033 @item
3034 The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is
3035 where GNU C header files are traditionally stored.  If you wish to store
3036 header files in non-standard locations, then you can assign the logical
3037 @samp{GNU_CC_INCLUDE} to be a search list, where each element of the
3038 list is suitable for use with a rooted logical.
3039
3040 @item
3041 The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}.  This is where
3042 VAX-C header files are traditionally stored.
3043
3044 @item
3045 If the include file specification by itself is a valid VMS filename, the
3046 preprocessor then uses this name with no prefix in an attempt to open
3047 the include file.
3048
3049 @item
3050 If the file specification is not a valid VMS filename (i.e. does not
3051 contain a device or a directory specifier, and contains a @samp{/}
3052 character), the preprocessor tries to convert it from Unix syntax to
3053 VMS syntax.
3054
3055 Conversion works like this: the first directory name becomes a device,
3056 and the rest of the directories are converted into VMS-format directory
3057 names.  For example, the name @file{X11/foobar.h} is
3058 translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h},
3059 whichever one can be opened.  This strategy allows you to assign a
3060 logical name to point to the actual location of the header files.
3061
3062 @item
3063 If none of these strategies succeeds, the @samp{#include} fails.
3064 @end enumerate
3065
3066 Include directives of the form:
3067
3068 @example
3069 #include foobar
3070 @end example
3071
3072 @noindent
3073 are a common source of incompatibility between VAX-C and GCC.  VAX-C
3074 treats this much like a standard @code{#include <foobar.h>} directive.
3075 That is incompatible with the ISO C behavior implemented by GCC: to
3076 expand the name @code{foobar} as a macro.  Macro expansion should
3077 eventually yield one of the two standard formats for @code{#include}:
3078
3079 @example
3080 #include "@var{file}"
3081 #include <@var{file}>
3082 @end example
3083
3084 If you have this problem, the best solution is to modify the source to
3085 convert the @code{#include} directives to one of the two standard forms.
3086 That will work with either compiler.  If you want a quick and dirty fix,
3087 define the file names as macros with the proper expansion, like this:
3088
3089 @example
3090 #define stdio <stdio.h>
3091 @end example
3092
3093 @noindent
3094 This will work, as long as the name doesn't conflict with anything else
3095 in the program.
3096
3097 Another source of incompatibility is that VAX-C assumes that:
3098
3099 @example
3100 #include "foobar"
3101 @end example
3102
3103 @noindent
3104 is actually asking for the file @file{foobar.h}.  GCC does not
3105 make this assumption, and instead takes what you ask for literally;
3106 it tries to read the file @file{foobar}.  The best way to avoid this
3107 problem is to always specify the desired file extension in your include
3108 directives.
3109
3110 GCC for VMS is distributed with a set of include files that is
3111 sufficient to compile most general purpose programs.  Even though the
3112 GCC distribution does not contain header files to define constants
3113 and structures for some VMS system-specific functions, there is no
3114 reason why you cannot use GCC with any of these functions.  You first
3115 may have to generate or create header files, either by using the public
3116 domain utility @code{UNSDL} (which can be found on a DECUS tape), or by
3117 extracting the relevant modules from one of the system macro libraries,
3118 and using an editor to construct a C header file.
3119
3120 A @code{#include} file name cannot contain a DECNET node name.  The
3121 preprocessor reports an I/O error if you attempt to use a node name,
3122 whether explicitly, or implicitly via a logical name.
3123
3124 @node Global Declarations
3125 @section Global Declarations and VMS
3126
3127 @findex GLOBALREF
3128 @findex GLOBALDEF
3129 @findex GLOBALVALUEDEF
3130 @findex GLOBALVALUEREF
3131 GCC does not provide the @code{globalref}, @code{globaldef} and
3132 @code{globalvalue} keywords of VAX-C.  You can get the same effect with
3133 an obscure feature of GAS, the GNU assembler.  (This requires GAS
3134 version 1.39 or later.)  The following macros allow you to use this
3135 feature in a fairly natural way:
3136
3137 @smallexample
3138 #ifdef __GNUC__
3139 #define GLOBALREF(TYPE,NAME)                      \
3140   TYPE NAME                                       \
3141   asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
3142 #define GLOBALDEF(TYPE,NAME,VALUE)                \
3143   TYPE NAME                                       \
3144   asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
3145     = VALUE
3146 #define GLOBALVALUEREF(TYPE,NAME)                 \
3147   const TYPE NAME[1]                              \
3148   asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
3149 #define GLOBALVALUEDEF(TYPE,NAME,VALUE)           \
3150   const TYPE NAME[1]                              \
3151   asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)  \
3152     = @{VALUE@}
3153 #else
3154 #define GLOBALREF(TYPE,NAME) \
3155   globalref TYPE NAME
3156 #define GLOBALDEF(TYPE,NAME,VALUE) \
3157   globaldef TYPE NAME = VALUE
3158 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
3159   globalvalue TYPE NAME = VALUE
3160 #define GLOBALVALUEREF(TYPE,NAME) \
3161   globalvalue TYPE NAME
3162 #endif
3163 @end smallexample
3164
3165 @noindent
3166 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
3167 name is removed by the assembler, after it has modified the attributes
3168 of the symbol).  These macros are provided in the VMS binaries
3169 distribution in a header file @file{GNU_HACKS.H}.  An example of the
3170 usage is:
3171
3172 @example
3173 GLOBALREF (int, ijk);
3174 GLOBALDEF (int, jkl, 0);
3175 @end example
3176
3177 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
3178 straightforwardly for arrays, since there is no way to insert the array
3179 dimension into the declaration at the right place.  However, you can
3180 declare an array with these macros if you first define a typedef for the
3181 array type, like this:
3182
3183 @example
3184 typedef int intvector[10];
3185 GLOBALREF (intvector, foo);
3186 @end example
3187
3188 Array and structure initializers will also break the macros; you can
3189 define the initializer to be a macro of its own, or you can expand the
3190 @code{GLOBALDEF} macro by hand.  You may find a case where you wish to
3191 use the @code{GLOBALDEF} macro with a large array, but you are not
3192 interested in explicitly initializing each element of the array.  In
3193 such cases you can use an initializer like: @code{@{0,@}}, which will
3194 initialize the entire array to @code{0}.
3195
3196 A shortcoming of this implementation is that a variable declared with
3197 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array.  For
3198 example, the declaration:
3199
3200 @example
3201 GLOBALVALUEREF(int, ijk);
3202 @end example
3203
3204 @noindent
3205 declares the variable @code{ijk} as an array of type @code{int [1]}.
3206 This is done because a globalvalue is actually a constant; its ``value''
3207 is what the linker would normally consider an address.  That is not how
3208 an integer value works in C, but it is how an array works.  So treating
3209 the symbol as an array name gives consistent results---with the
3210 exception that the value seems to have the wrong type.  @strong{Don't
3211 try to access an element of the array.}  It doesn't have any elements.
3212 The array ``address'' may not be the address of actual storage.
3213
3214 The fact that the symbol is an array may lead to warnings where the
3215 variable is used.  Insert type casts to avoid the warnings.  Here is an
3216 example; it takes advantage of the ISO C feature allowing macros that
3217 expand to use the same name as the macro itself.
3218
3219 @example
3220 GLOBALVALUEREF (int, ss$_normal);
3221 GLOBALVALUEDEF (int, xyzzy,123);
3222 #ifdef __GNUC__
3223 #define ss$_normal ((int) ss$_normal)
3224 #define xyzzy ((int) xyzzy)
3225 #endif
3226 @end example
3227
3228 Don't use @code{globaldef} or @code{globalref} with a variable whose
3229 type is an enumeration type; this is not implemented.  Instead, make the
3230 variable an integer, and use a @code{globalvaluedef} for each of the
3231 enumeration values.  An example of this would be:
3232
3233 @example
3234 #ifdef __GNUC__
3235 GLOBALDEF (int, color, 0);
3236 GLOBALVALUEDEF (int, RED, 0);
3237 GLOBALVALUEDEF (int, BLUE, 1);
3238 GLOBALVALUEDEF (int, GREEN, 3);
3239 #else
3240 enum globaldef color @{RED, BLUE, GREEN = 3@};
3241 #endif
3242 @end example
3243
3244 @node VMS Misc
3245 @section Other VMS Issues
3246
3247 @cindex exit status and VMS
3248 @cindex return value of @code{main}
3249 @cindex @code{main} and the exit status
3250 GCC automatically arranges for @code{main} to return 1 by default if
3251 you fail to specify an explicit return value.  This will be interpreted
3252 by VMS as a status code indicating a normal successful completion.
3253 Version 1 of GCC did not provide this default.
3254
3255 GCC on VMS works only with the GNU assembler, GAS.  You need version
3256 1.37 or later of GAS in order to produce value debugging information for
3257 the VMS debugger.  Use the ordinary VMS linker with the object files
3258 produced by GAS.
3259
3260 @cindex shared VMS run time system
3261 @cindex @file{VAXCRTL}
3262 Under previous versions of GCC, the generated code would occasionally
3263 give strange results when linked to the sharable @file{VAXCRTL} library.
3264 Now this should work.
3265
3266 A caveat for use of @code{const} global variables: the @code{const}
3267 modifier must be specified in every external declaration of the variable
3268 in all of the source files that use that variable.  Otherwise the linker
3269 will issue warnings about conflicting attributes for the variable.  Your
3270 program will still work despite the warnings, but the variable will be
3271 placed in writable storage.
3272
3273 @cindex name augmentation
3274 @cindex case sensitivity and VMS
3275 @cindex VMS and case sensitivity
3276 Although the VMS linker does distinguish between upper and lower case
3277 letters in global symbols, most VMS compilers convert all such symbols
3278 into upper case and most run-time library routines also have upper case
3279 names.  To be able to reliably call such routines, GCC (by means of
3280 the assembler GAS) converts global symbols into upper case like other
3281 VMS compilers.  However, since the usual practice in C is to distinguish
3282 case, GCC (via GAS) tries to preserve usual C behavior by augmenting
3283 each name that is not all lower case.  This means truncating the name
3284 to at most 23 characters and then adding more characters at the end
3285 which encode the case pattern of those 23.   Names which contain at
3286 least one dollar sign are an exception; they are converted directly into
3287 upper case without augmentation.
3288
3289 Name augmentation yields bad results for programs that use precompiled
3290 libraries (such as Xlib) which were generated by another compiler.  You
3291 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
3292 it makes external C functions and variables case-independent as is usual
3293 on VMS.  Alternatively, you could write all references to the functions
3294 and variables in such libraries using lower case; this will work on VMS,
3295 but is not portable to other systems.  The compiler option @samp{/NAMES}
3296 also provides control over global name handling.
3297
3298 Function and variable names are handled somewhat differently with GNU
3299 C++.  The GNU C++ compiler performs @dfn{name mangling} on function
3300 names, which means that it adds information to the function name to
3301 describe the data types of the arguments that the function takes.  One
3302 result of this is that the name of a function can become very long.
3303 Since the VMS linker only recognizes the first 31 characters in a name,
3304 special action is taken to ensure that each function and variable has a
3305 unique name that can be represented in 31 characters.
3306
3307 If the name (plus a name augmentation, if required) is less than 32
3308 characters in length, then no special action is performed.  If the name
3309 is longer than 31 characters, the assembler (GAS) will generate a
3310 hash string based upon the function name, truncate the function name to
3311 23 characters, and append the hash string to the truncated name.  If the
3312 @samp{/VERBOSE} compiler option is used, the assembler will print both
3313 the full and truncated names of each symbol that is truncated.
3314
3315 The @samp{/NOCASE_HACK} compiler option should not be used when you are
3316 compiling programs that use libg++.  libg++ has several instances of
3317 objects (i.e.  @code{Filebuf} and @code{filebuf}) which become
3318 indistinguishable in a case-insensitive environment.  This leads to
3319 cases where you need to inhibit augmentation selectively (if you were
3320 using libg++ and Xlib in the same program, for example).  There is no
3321 special feature for doing this, but you can get the result by defining a
3322 macro for each mixed case symbol for which you wish to inhibit
3323 augmentation.  The macro should expand into the lower case equivalent of
3324 itself.  For example:
3325
3326 @example
3327 #define StuDlyCapS studlycaps
3328 @end example
3329
3330 These macro definitions can be placed in a header file to minimize the
3331 number of changes to your source code.
3332 @end ifset
3333
3334 @ifset INTERNALS
3335 @node Portability
3336 @chapter GCC and Portability
3337 @cindex portability
3338 @cindex GCC and portability
3339
3340 The main goal of GCC was to make a good, fast compiler for machines in
3341 the class that the GNU system aims to run on: 32-bit machines that address
3342 8-bit bytes and have several general registers.  Elegance, theoretical
3343 power and simplicity are only secondary.
3344
3345 GCC gets most of the information about the target machine from a machine
3346 description which gives an algebraic formula for each of the machine's
3347 instructions.  This is a very clean way to describe the target.  But when
3348 the compiler needs information that is difficult to express in this
3349 fashion, I have not hesitated to define an ad-hoc parameter to the machine
3350 description.  The purpose of portability is to reduce the total work needed
3351 on the compiler; it was not of interest for its own sake.
3352
3353 @cindex endianness
3354 @cindex autoincrement addressing, availability
3355 @findex abort
3356 GCC does not contain machine dependent code, but it does contain code
3357 that depends on machine parameters such as endianness (whether the most
3358 significant byte has the highest or lowest address of the bytes in a word)
3359 and the availability of autoincrement addressing.  In the RTL-generation
3360 pass, it is often necessary to have multiple strategies for generating code
3361 for a particular kind of syntax tree, strategies that are usable for different
3362 combinations of parameters.  Often I have not tried to address all possible
3363 cases, but only the common ones or only the ones that I have encountered.
3364 As a result, a new target may require additional strategies.  You will know
3365 if this happens because the compiler will call @code{abort}.  Fortunately,
3366 the new strategies can be added in a machine-independent fashion, and will
3367 affect only the target machines that need them.
3368 @end ifset
3369
3370 @ifset INTERNALS
3371 @node Interface
3372 @chapter Interfacing to GCC Output
3373 @cindex interfacing to GCC output
3374 @cindex run-time conventions
3375 @cindex function call conventions
3376 @cindex conventions, run-time
3377
3378 GCC is normally configured to use the same function calling convention
3379 normally in use on the target system.  This is done with the
3380 machine-description macros described (@pxref{Target Macros}).
3381
3382 @cindex unions, returning
3383 @cindex structures, returning
3384 @cindex returning structures and unions
3385 However, returning of structure and union values is done differently on
3386 some target machines.  As a result, functions compiled with PCC
3387 returning such types cannot be called from code compiled with GCC,
3388 and vice versa.  This does not cause trouble often because few Unix
3389 library routines return structures or unions.
3390
3391 GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
3392 long in the same registers used for @code{int} or @code{double} return
3393 values.  (GCC typically allocates variables of such types in
3394 registers also.)  Structures and unions of other sizes are returned by
3395 storing them into an address passed by the caller (usually in a
3396 register).  The machine-description macros @code{STRUCT_VALUE} and
3397 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
3398
3399 By contrast, PCC on most target machines returns structures and unions
3400 of any size by copying the data into an area of static storage, and then
3401 returning the address of that storage as if it were a pointer value.
3402 The caller must copy the data from that memory area to the place where
3403 the value is wanted.  This is slower than the method used by GCC, and
3404 fails to be reentrant.
3405
3406 On some target machines, such as RISC machines and the 80386, the
3407 standard system convention is to pass to the subroutine the address of
3408 where to return the value.  On these machines, GCC has been
3409 configured to be compatible with the standard compiler, when this method
3410 is used.  It may not be compatible for structures of 1, 2, 4 or 8 bytes.
3411
3412 @cindex argument passing
3413 @cindex passing arguments
3414 GCC uses the system's standard convention for passing arguments.  On
3415 some machines, the first few arguments are passed in registers; in
3416 others, all are passed on the stack.  It would be possible to use
3417 registers for argument passing on any machine, and this would probably
3418 result in a significant speedup.  But the result would be complete
3419 incompatibility with code that follows the standard convention.  So this
3420 change is practical only if you are switching to GCC as the sole C
3421 compiler for the system.  We may implement register argument passing on
3422 certain machines once we have a complete GNU system so that we can
3423 compile the libraries with GCC.
3424
3425 On some machines (particularly the Sparc), certain types of arguments
3426 are passed ``by invisible reference''.  This means that the value is
3427 stored in memory, and the address of the memory location is passed to
3428 the subroutine.
3429
3430 @cindex @code{longjmp} and automatic variables
3431 If you use @code{longjmp}, beware of automatic variables.  ISO C says that
3432 automatic variables that are not declared @code{volatile} have undefined
3433 values after a @code{longjmp}.  And this is all GCC promises to do,
3434 because it is very difficult to restore register variables correctly, and
3435 one of GCC's features is that it can put variables in registers without
3436 your asking it to.
3437
3438 If you want a variable to be unaltered by @code{longjmp}, and you don't
3439 want to write @code{volatile} because old C compilers don't accept it,
3440 just take the address of the variable.  If a variable's address is ever
3441 taken, even if just to compute it and ignore it, then the variable cannot
3442 go in a register:
3443
3444 @example
3445 @{
3446   int careful;
3447   &careful;
3448   @dots{}
3449 @}
3450 @end example
3451
3452 @cindex arithmetic libraries
3453 @cindex math libraries
3454 Code compiled with GCC may call certain library routines.  Most of
3455 them handle arithmetic for which there are no instructions.  This
3456 includes multiply and divide on some machines, and floating point
3457 operations on any machine for which floating point support is disabled
3458 with @samp{-msoft-float}.  Some standard parts of the C library, such as
3459 @code{bcopy} or @code{memcpy}, are also called automatically.  The usual
3460 function call interface is used for calling the library routines.
3461
3462 These library routines should be defined in the library @file{libgcc.a},
3463 which GCC automatically searches whenever it links a program.  On
3464 machines that have multiply and divide instructions, if hardware
3465 floating point is in use, normally @file{libgcc.a} is not needed, but it
3466 is searched just in case.
3467
3468 Each arithmetic function is defined in @file{libgcc1.c} to use the
3469 corresponding C arithmetic operator.  As long as the file is compiled
3470 with another C compiler, which supports all the C arithmetic operators,
3471 this file will work portably.  However, @file{libgcc1.c} does not work if
3472 compiled with GCC, because each arithmetic function would compile
3473 into a call to itself!
3474 @end ifset
3475
3476 @ifset INTERNALS
3477 @node Passes
3478 @chapter Passes and Files of the Compiler
3479 @cindex passes and files of the compiler
3480 @cindex files and passes of the compiler
3481 @cindex compiler passes and files
3482
3483 @cindex top level of compiler
3484 The overall control structure of the compiler is in @file{toplev.c}.  This
3485 file is responsible for initialization, decoding arguments, opening and
3486 closing files, and sequencing the passes.
3487
3488 @cindex parsing pass
3489 The parsing pass is invoked only once, to parse the entire input.  The RTL
3490 intermediate code for a function is generated as the function is parsed, a
3491 statement at a time.  Each statement is read in as a syntax tree and then
3492 converted to RTL; then the storage for the tree for the statement is
3493 reclaimed.  Storage for types (and the expressions for their sizes),
3494 declarations, and a representation of the binding contours and how they nest,
3495 remain until the function is finished being compiled; these are all needed
3496 to output the debugging information.
3497
3498 @findex rest_of_compilation
3499 @findex rest_of_decl_compilation
3500 Each time the parsing pass reads a complete function definition or
3501 top-level declaration, it calls either the function
3502 @code{rest_of_compilation}, or the function
3503 @code{rest_of_decl_compilation} in @file{toplev.c}, which are
3504 responsible for all further processing necessary, ending with output of
3505 the assembler language.  All other compiler passes run, in sequence,
3506 within @code{rest_of_compilation}.  When that function returns from
3507 compiling a function definition, the storage used for that function
3508 definition's compilation is entirely freed, unless it is an inline
3509 function
3510 @ifset USING
3511 (@pxref{Inline,,An Inline Function is As Fast As a Macro}).
3512 @end ifset
3513 @ifclear USING
3514 (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}).
3515 @end ifclear
3516
3517 Here is a list of all the passes of the compiler and their source files.
3518 Also included is a description of where debugging dumps can be requested
3519 with @samp{-d} options.
3520
3521 @itemize @bullet
3522 @item
3523 Parsing.  This pass reads the entire text of a function definition,
3524 constructing partial syntax trees.  This and RTL generation are no longer
3525 truly separate passes (formerly they were), but it is easier to think
3526 of them as separate.
3527
3528 The tree representation does not entirely follow C syntax, because it is
3529 intended to support other languages as well.
3530
3531 Language-specific data type analysis is also done in this pass, and every
3532 tree node that represents an expression has a data type attached.
3533 Variables are represented as declaration nodes.
3534
3535 @cindex constant folding
3536 @cindex arithmetic simplifications
3537 @cindex simplifications, arithmetic
3538 Constant folding and some arithmetic simplifications are also done
3539 during this pass.
3540
3541 The language-independent source files for parsing are
3542 @file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}.
3543 There are also header files @file{tree.h} and @file{tree.def}
3544 which define the format of the tree representation.@refill
3545
3546 @c Avoiding overfull is tricky here.
3547 The source files to parse C are
3548 @file{c-parse.in},
3549 @file{c-decl.c},
3550 @file{c-typeck.c},
3551 @file{c-aux-info.c},
3552 @file{c-convert.c},
3553 and @file{c-lang.c}
3554 along with header files
3555 @file{c-lex.h}, and
3556 @file{c-tree.h}.
3557
3558 The source files for parsing C++ are in @file{cp/}.
3559 They are @file{parse.y},
3560 @file{class.c},@*
3561 @file{cvt.c}, @file{decl.c}, @file{decl2.c}, 
3562 @file{except.c},@*
3563 @file{expr.c}, @file{init.c}, @file{lex.c},
3564 @file{method.c}, @file{ptree.c},@*
3565 @file{search.c}, @file{tree.c}, 
3566 @file{typeck2.c}, and
3567 @file{typeck.c}, along with header files @file{cp-tree.def},
3568 @file{cp-tree.h}, and @file{decl.h}.
3569
3570 The special source files for parsing Objective C are in @file{objc/}.
3571 They are @file{objc-parse.y}, @file{objc-act.c}, @file{objc-tree.def}, and
3572 @file{objc-act.h}.  Certain C-specific files are used for this as
3573 well.
3574
3575 The file @file{c-common.c} is also used for all of the above languages.
3576
3577 @cindex RTL generation
3578 @item
3579 RTL generation.  This is the conversion of syntax tree into RTL code.
3580 It is actually done statement-by-statement during parsing, but for
3581 most purposes it can be thought of as a separate pass.
3582
3583 @cindex target-parameter-dependent code
3584 This is where the bulk of target-parameter-dependent code is found,
3585 since often it is necessary for strategies to apply only when certain
3586 standard kinds of instructions are available.  The purpose of named
3587 instruction patterns is to provide this information to the RTL
3588 generation pass.
3589
3590 @cindex tail recursion optimization
3591 Optimization is done in this pass for @code{if}-conditions that are
3592 comparisons, boolean operations or conditional expressions.  Tail
3593 recursion is detected at this time also.  Decisions are made about how
3594 best to arrange loops and how to output @code{switch} statements.
3595
3596 @c Avoiding overfull is tricky here.
3597 The source files for RTL generation include
3598 @file{stmt.c},
3599 @file{calls.c},
3600 @file{expr.c},
3601 @file{explow.c},
3602 @file{expmed.c},
3603 @file{function.c},
3604 @file{optabs.c}
3605 and @file{emit-rtl.c}.
3606 Also, the file
3607 @file{insn-emit.c}, generated from the machine description by the
3608 program @code{genemit}, is used in this pass.  The header file
3609 @file{expr.h} is used for communication within this pass.@refill
3610
3611 @findex genflags
3612 @findex gencodes
3613 The header files @file{insn-flags.h} and @file{insn-codes.h},
3614 generated from the machine description by the programs @code{genflags}
3615 and @code{gencodes}, tell this pass which standard names are available
3616 for use and which patterns correspond to them.@refill
3617
3618 Aside from debugging information output, none of the following passes
3619 refers to the tree structure representation of the function (only
3620 part of which is saved).
3621
3622 @cindex inline, automatic
3623 The decision of whether the function can and should be expanded inline
3624 in its subsequent callers is made at the end of rtl generation.  The
3625 function must meet certain criteria, currently related to the size of
3626 the function and the types and number of parameters it has.  Note that
3627 this function may contain loops, recursive calls to itself
3628 (tail-recursive functions can be inlined!), gotos, in short, all
3629 constructs supported by GCC.  The file @file{integrate.c} contains
3630 the code to save a function's rtl for later inlining and to inline that
3631 rtl when the function is called.  The header file @file{integrate.h}
3632 is also used for this purpose.
3633
3634 The option @samp{-dr} causes a debugging dump of the RTL code after
3635 this pass.  This dump file's name is made by appending @samp{.rtl} to
3636 the input file name.
3637
3638 @cindex jump optimization
3639 @cindex unreachable code
3640 @cindex dead code
3641 @item
3642 Jump optimization.  This pass simplifies jumps to the following
3643 instruction, jumps across jumps, and jumps to jumps.  It deletes
3644 unreferenced labels and unreachable code, except that unreachable code
3645 that contains a loop is not recognized as unreachable in this pass.
3646 (Such loops are deleted later in the basic block analysis.)  It also
3647 converts some code originally written with jumps into sequences of
3648 instructions that directly set values from the results of comparisons,
3649 if the machine has such instructions.
3650
3651 Jump optimization is performed two or three times.  The first time is
3652 immediately following RTL generation.  The second time is after CSE,
3653 but only if CSE says repeated jump optimization is needed.  The
3654 last time is right before the final pass.  That time, cross-jumping
3655 and deletion of no-op move instructions are done together with the
3656 optimizations described above.
3657
3658 The source file of this pass is @file{jump.c}.
3659
3660 The option @samp{-dj} causes a debugging dump of the RTL code after
3661 this pass is run for the first time.  This dump file's name is made by
3662 appending @samp{.jump} to the input file name.
3663
3664 @cindex register use analysis
3665 @item
3666 Register scan.  This pass finds th