1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
2 @c 1999, 2000, 2001 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
7 @chapter Known Causes of Trouble with GCC
9 @cindex installation trouble
10 @cindex known causes of trouble
12 This section describes known problems that affect users of GCC@. Most
13 of these are not GCC bugs per se---if they were, we would fix them.
14 But the result for a user may be like the result of a bug.
16 Some of these problems are due to bugs in other software, some are
17 missing features that are too much work to add, and some are places
18 where people's opinions differ as to what is best.
21 * Actual Bugs:: Bugs we will fix later.
22 * Cross-Compiler Problems:: Common problems of cross compiling with GCC.
23 * Interoperation:: Problems using GCC with other compilers,
24 and with certain linkers, assemblers and debuggers.
25 * External Bugs:: Problems compiling certain programs.
26 * Incompatibilities:: GCC is incompatible with traditional C.
27 * Fixed Headers:: GCC uses corrected versions of system header files.
28 This is necessary, but doesn't always work smoothly.
29 * Standard Libraries:: GCC uses the system C library, which might not be
30 compliant with the ISO C standard.
31 * Disappointments:: Regrettable things we can't change, but not quite bugs.
32 * C++ Misunderstandings:: Common misunderstandings with GNU C++.
33 * Protoize Caveats:: Things to watch out for when using @code{protoize}.
34 * Non-bugs:: Things we think are right, but some others disagree.
35 * Warnings and Errors:: Which problems in your code get warnings,
40 @section Actual Bugs We Haven't Fixed Yet
44 The @code{fixincludes} script interacts badly with automounters; if the
45 directory of system header files is automounted, it tends to be
46 unmounted while @code{fixincludes} is running. This would seem to be a
47 bug in the automounter. We don't know any good way to work around it.
50 The @code{fixproto} script will sometimes add prototypes for the
51 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
52 @code{jmp_buf} type before that type is defined. To work around this,
53 edit the offending file and place the typedef in front of the
57 @opindex pedantic-errors
58 When @option{-pedantic-errors} is specified, GCC will incorrectly give
59 an error message when a function name is specified in an expression
60 involving the comma operator.
63 @node Cross-Compiler Problems
64 @section Cross-Compiler Problems
66 You may run into problems with cross compilation on certain machines,
71 Cross compilation can run into trouble for certain machines because
72 some target machines' assemblers require floating point numbers to be
73 written as @emph{integer} constants in certain contexts.
75 The compiler writes these integer constants by examining the floating
76 point value as an integer and printing that integer, because this is
77 simple to write and independent of the details of the floating point
78 representation. But this does not work if the compiler is running on
79 a different machine with an incompatible floating point format, or
80 even a different byte-ordering.
82 In addition, correct constant folding of floating point values
83 requires representing them in the target machine's format.
84 (The C standard does not quite require this, but in practice
85 it is the only way to win.)
87 It is now possible to overcome these problems by defining macros such
88 as @code{REAL_VALUE_TYPE}. But doing so is a substantial amount of
89 work for each target machine.
91 @xref{Cross-compilation}.
94 @xref{Cross-compilation,,Cross Compilation and Floating Point Format,
95 gcc.info, Using and Porting GCC}.
99 At present, the program @file{mips-tfile} which adds debug
100 support to object files on MIPS systems does not work in a cross
105 @section Interoperation
107 This section lists various difficulties encountered in using GCC
108 together with other compilers or with the assemblers, linkers,
109 libraries and debuggers on certain systems.
113 Objective-C does not work on the RS/6000.
116 G++ does not do name mangling in the same way as other C++
117 compilers. This means that object files compiled with one compiler
118 cannot be used with another.
120 This effect is intentional, to protect you from more subtle problems.
121 Compilers differ as to many internal details of C++ implementation,
122 including: how class instances are laid out, how multiple inheritance is
123 implemented, and how virtual function calls are handled. If the name
124 encoding were made the same, your programs would link against libraries
125 provided from other compilers---but the programs would then crash when
126 run. Incompatible libraries are then detected at link time, rather than
130 Older GDB versions sometimes fail to read the output of GCC version
131 2. If you have trouble, get GDB version 4.4 or later.
135 DBX rejects some files produced by GCC, though it accepts similar
136 constructs in output from PCC@. Until someone can supply a coherent
137 description of what is valid DBX input and what is not, there is
138 nothing I can do about these problems. You are on your own.
141 The GNU assembler (GAS) does not support PIC@. To generate PIC code, you
142 must use some other assembler, such as @file{/bin/as}.
145 On some BSD systems, including some versions of Ultrix, use of profiling
146 causes static variable destructors (currently used only in C++) not to
150 @cindex @code{vfork}, for the Sun-4
152 There is a bug in @code{vfork} on the Sun-4 which causes the registers
153 of the child process to clobber those of the parent. Because of this,
154 programs that call @code{vfork} are likely to lose when compiled
155 optimized with GCC when the child code alters registers which contain
156 C variables in the parent. This affects variables which are live in the
157 parent across the call to @code{vfork}.
159 If you encounter this, you can work around the problem by declaring
160 variables @code{volatile} in the function that calls @code{vfork}, until
161 the problem goes away, or by not declaring them @code{register} and not
162 using @option{-O} for those source files.
166 On some SGI systems, when you use @option{-lgl_s} as an option,
167 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
168 Naturally, this does not happen when you use GCC@.
169 You must specify all three options explicitly.
172 On a Sparc, GCC aligns all values of type @code{double} on an 8-byte
173 boundary, and it expects every @code{double} to be so aligned. The Sun
174 compiler usually gives @code{double} values 8-byte alignment, with one
175 exception: function arguments of type @code{double} may not be aligned.
177 As a result, if a function compiled with Sun CC takes the address of an
178 argument of type @code{double} and passes this pointer of type
179 @code{double *} to a function compiled with GCC, dereferencing the
180 pointer may cause a fatal signal.
182 One way to solve this problem is to compile your entire program with GCC@.
183 Another solution is to modify the function that is compiled with
184 Sun CC to copy the argument into a local variable; local variables
185 are always properly aligned. A third solution is to modify the function
186 that uses the pointer to dereference it via the following function
187 @code{access_double} instead of directly with @samp{*}:
191 access_double (double *unaligned_ptr)
193 union d2i @{ double d; int i[2]; @};
195 union d2i *p = (union d2i *) unaligned_ptr;
206 Storing into the pointer can be done likewise with the same union.
209 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
210 may allocate memory that is only 4 byte aligned. Since GCC on the
211 Sparc assumes that doubles are 8 byte aligned, this may result in a
212 fatal signal if doubles are stored in memory allocated by the
213 @file{libmalloc.a} library.
215 The solution is to not use the @file{libmalloc.a} library. Use instead
216 @code{malloc} and related functions from @file{libc.a}; they do not have
220 Sun forgot to include a static version of @file{libdl.a} with some
221 versions of SunOS (mainly 4.1). This results in undefined symbols when
222 linking static binaries (that is, if you use @option{-static}). If you
223 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
224 when linking, compile and link against the file
225 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
228 The 128-bit long double format that the Sparc port supports currently
229 works by using the architecturally defined quad-word floating point
230 instructions. Since there is no hardware that supports these
231 instructions they must be emulated by the operating system. Long
232 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
233 kernel emulator uses an obsolete and incompatible format. Long doubles
234 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
235 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
236 does not enable them by default. Long doubles appear to work in Sun OS
240 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
241 compile GCC correctly. We do not yet know why. However, GCC
242 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
243 compile itself properly on 9.01.
246 On the HP PA machine, ADB sometimes fails to work on functions compiled
247 with GCC@. Specifically, it fails to work on functions that use
248 @code{alloca} or variable-size arrays. This is because GCC doesn't
249 generate HP-UX unwind descriptors for such functions. It may even be
250 impossible to generate them.
253 Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
254 the preliminary GNU tools (@pxref{Installation}).
257 Taking the address of a label may generate errors from the HP-UX
258 PA assembler. GAS for the PA does not have this problem.
261 Using floating point parameters for indirect calls to static functions
262 will not work when using the HP assembler. There simply is no way for GCC
263 to specify what registers hold arguments for static functions when using
264 the HP assembler. GAS for the PA does not have this problem.
267 In extremely rare cases involving some very large functions you may
268 receive errors from the HP linker complaining about an out of bounds
269 unconditional branch offset. This used to occur more often in previous
270 versions of GCC, but is now exceptionally rare. If you should run
271 into it, you can work around by making your function smaller.
274 GCC compiled code sometimes emits warnings from the HP-UX assembler of
278 (warning) Use of GR3 when
279 frame >= 8192 may cause conflict.
282 These warnings are harmless and can be safely ignored.
285 The current version of the assembler (@file{/bin/as}) for the RS/6000
286 has certain problems that prevent the @option{-g} option in GCC from
287 working. Note that @file{Makefile.in} uses @option{-g} by default when
288 compiling @file{libgcc2.c}.
290 IBM has produced a fixed version of the assembler. The upgraded
291 assembler unfortunately was not included in any of the AIX 3.2 update
292 PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request
293 PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277.
294 See the file @file{README.RS6000} for more details on these updates.
296 You can test for the presence of a fixed assembler by using the
304 If the command exits normally, the assembler fix already is installed.
305 If the assembler complains that @option{-u} is an unknown flag, you need to
309 On the IBM RS/6000, compiling code of the form
320 will cause the linker to report an undefined symbol @code{foo}.
321 Although this behavior differs from most other systems, it is not a
322 bug because redefining an @code{extern} variable as @code{static}
323 is undefined in ISO C@.
326 AIX on the RS/6000 provides support (NLS) for environments outside of
327 the United States. Compilers and assemblers use NLS to support
328 locale-specific representations of various objects including
329 floating-point numbers (@samp{.} vs @samp{,} for separating decimal fractions).
330 There have been problems reported where the library linked with GCC does
331 not produce the same floating-point formats that the assembler accepts.
332 If you have this problem, set the @env{LANG} environment variable to
333 @samp{C} or @samp{En_US}.
336 @opindex fdollars-in-identifiers
337 Even if you specify @option{-fdollars-in-identifiers},
338 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
339 to a restriction in the IBM assembler. GAS supports these
343 On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC
344 version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2
345 by requesting PTF 421749 from IBM@.
348 @opindex mno-serialize-volatile
349 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
350 occurs when the @samp{fldcr} instruction is used. GCC uses
351 @samp{fldcr} on the 88100 to serialize volatile memory references. Use
352 the option @option{-mno-serialize-volatile} if your version of the
353 assembler has this bug.
356 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
357 messages from the linker. These warning messages complain of mismatched
358 psect attributes. You can ignore them. @xref{VMS Install}.
361 On NewsOS version 3, if you include both of the files @file{stddef.h}
362 and @file{sys/types.h}, you get an error because there are two typedefs
363 of @code{size_t}. You should change @file{sys/types.h} by adding these
364 lines around the definition of @code{size_t}:
369 @var{actual-typedef-here}
375 On the Alliant, the system's own convention for returning structures
376 and unions is unusual, and is not compatible with GCC no matter
377 what options are used.
382 @opindex mhc-struct-return
383 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
384 convention for structure and union returning. Use the option
385 @option{-mhc-struct-return} to tell GCC to use a convention compatible
388 @cindex VAX calling convention
389 @cindex Ultrix calling convention
392 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
393 by function calls. However, the C compiler uses conventions compatible
394 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
396 GCC uses the same convention as the Ultrix C compiler. You can use
397 these options to produce code compatible with the Fortran compiler:
400 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
404 On the WE32k, you may find that programs compiled with GCC do not
405 work with the standard shared C library. You may need to link with
406 the ordinary C compiler. If you do so, you must specify the following
410 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
413 The first specifies where to find the library @file{libgcc.a}
414 specified with the @option{-lgcc} option.
416 GCC does linking by invoking @command{ld}, just as @command{cc} does, and
417 there is no reason why it @emph{should} matter which compilation program
418 you use to invoke @command{ld}. If someone tracks this problem down,
419 it can probably be fixed easily.
422 On the Alpha, you may get assembler errors about invalid syntax as a
423 result of floating point constants. This is due to a bug in the C
424 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid
425 floating point numbers, they sometimes print @samp{NaN}.
428 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
429 sometimes reorders instructions incorrectly when optimization is turned
430 on. If you think this may be happening to you, try using the GNU
431 assembler; GAS version 2.1 supports ECOFF on Irix.
434 Or use the @option{-noasmopt} option when you compile GCC with itself,
435 and then again when you compile your program. (This is a temporary
436 kludge to turn off assembler optimization on Irix.) If this proves to
437 be what you need, edit the assembler spec in the file @file{specs} so
438 that it unconditionally passes @option{-O0} to the assembler, and never
439 passes @option{-O2} or @option{-O3}.
443 @section Problems Compiling Certain Programs
445 @c prevent bad page break with this line
446 Certain programs have problems compiling.
450 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
451 because of problems in DEC's versions of the X11 header files
452 @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
453 @option{-I/usr/include/mit} to use the MIT versions of the header files,
454 using the @option{-traditional} switch to turn off ISO C, or fixing the
455 header files by adding this:
459 #define NeedFunctionPrototypes 0
464 On various 386 Unix systems derived from System V, including SCO, ISC,
465 and ESIX, you may get error messages about running out of virtual memory
466 while compiling certain programs.
468 You can prevent this problem by linking GCC with the GNU malloc
469 (which thus replaces the malloc that comes with the system). GNU malloc
470 is available as a separate package, and also in the file
471 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
473 If you have installed GNU malloc as a separate library package, use this
474 option when you relink GCC:
477 MALLOC=/usr/local/lib/libgmalloc.a
480 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
481 the object file to @file{gmalloc.o} and use this option when you relink
489 @node Incompatibilities
490 @section Incompatibilities of GCC
491 @cindex incompatibilities of GCC
494 There are several noteworthy incompatibilities between GNU C and K&R
495 (non-ISO) versions of C@. The @option{-traditional} option
496 eliminates many of these incompatibilities, @emph{but not all}, by
497 telling GCC to behave like a K&R C compiler.
500 @cindex string constants
501 @cindex read-only strings
502 @cindex shared strings
504 GCC normally makes string constants read-only. If several
505 identical-looking string constants are used, GCC stores only one
508 @cindex @code{mktemp}, and constant strings
509 One consequence is that you cannot call @code{mktemp} with a string
510 constant argument. The function @code{mktemp} always alters the
511 string its argument points to.
513 @cindex @code{sscanf}, and constant strings
514 @cindex @code{fscanf}, and constant strings
515 @cindex @code{scanf}, and constant strings
516 Another consequence is that @code{sscanf} does not work on some systems
517 when passed a string constant as its format control string or input.
518 This is because @code{sscanf} incorrectly tries to write into the string
519 constant. Likewise @code{fscanf} and @code{scanf}.
521 @opindex fwritable-strings
522 The best solution to these problems is to change the program to use
523 @code{char}-array variables with initialization strings for these
524 purposes instead of string constants. But if this is not possible,
525 you can use the @option{-fwritable-strings} flag, which directs GCC
526 to handle string constants the same way most C compilers do.
527 @option{-traditional} also has this effect, among others.
530 @code{-2147483648} is positive.
532 This is because 2147483648 cannot fit in the type @code{int}, so
533 (following the ISO C rules) its data type is @code{unsigned long int}.
534 Negating this value yields 2147483648 again.
537 GCC does not substitute macro arguments when they appear inside of
538 string constants. For example, the following macro in GCC
545 will produce output @code{"a"} regardless of what the argument @var{a} is.
547 The @option{-traditional} option directs GCC to handle such cases
548 (among others) in the old-fashioned (non-ISO) fashion.
550 @cindex @code{setjmp} incompatibilities
551 @cindex @code{longjmp} incompatibilities
553 When you use @code{setjmp} and @code{longjmp}, the only automatic
554 variables guaranteed to remain valid are those declared
555 @code{volatile}. This is a consequence of automatic register
556 allocation. Consider this function:
570 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
575 Here @code{a} may or may not be restored to its first value when the
576 @code{longjmp} occurs. If @code{a} is allocated in a register, then
577 its first value is restored; otherwise, it keeps the last value stored
581 If you use the @option{-W} option with the @option{-O} option, you will
582 get a warning when GCC thinks such a problem might be possible.
584 The @option{-traditional} option directs GCC to put variables in
585 the stack by default, rather than in registers, in functions that
586 call @code{setjmp}. This results in the behavior found in
587 traditional C compilers.
590 Programs that use preprocessing directives in the middle of macro
591 arguments do not work with GCC@. For example, a program like this
602 ISO C does not permit such a construct. It would make sense to support
603 it when @option{-traditional} is used, but it is too much work to
607 K&R compilers allow comments to cross over an inclusion boundary
608 (i.e.@: started in an include file and ended in the including file). I think
609 this would be quite ugly and can't imagine it could be needed.
611 @cindex external declaration scope
612 @cindex scope of external declarations
613 @cindex declaration scope
615 Declarations of external variables and functions within a block apply
616 only to the block containing the declaration. In other words, they
617 have the same scope as any other declaration in the same place.
619 In some other C compilers, a @code{extern} declaration affects all the
620 rest of the file even if it happens within a block.
622 The @option{-traditional} option directs GCC to treat all @code{extern}
623 declarations as global, like traditional compilers.
626 In traditional C, you can combine @code{long}, etc., with a typedef name,
631 typedef long foo bar;
634 In ISO C, this is not allowed: @code{long} and other type modifiers
635 require an explicit @code{int}. Because this criterion is expressed
636 by Bison grammar rules rather than C code, the @option{-traditional}
637 flag cannot alter it.
639 @cindex typedef names as function parameters
641 PCC allows typedef names to be used as function parameters. The
642 difficulty described immediately above applies here too.
645 When in @option{-traditional} mode, GCC allows the following erroneous
646 pair of declarations to appear together in a given scope:
654 GCC treats all characters of identifiers as significant, even when in
655 @option{-traditional} mode. According to K&R-1 (2.2), ``No more than the
656 first eight characters are significant, although more may be used.''.
657 Also according to K&R-1 (2.2), ``An identifier is a sequence of letters
658 and digits; the first character must be a letter. The underscore _
659 counts as a letter.'', but GCC also allows dollar signs in identifiers.
663 PCC allows whitespace in the middle of compound assignment operators
664 such as @samp{+=}. GCC, following the ISO standard, does not
665 allow this. The difficulty described immediately above applies here
671 GCC complains about unterminated character constants inside of
672 preprocessing conditionals that fail. Some programs have English
673 comments enclosed in conditionals that are guaranteed to fail; if these
674 comments contain apostrophes, GCC will probably report an error. For
675 example, this code would produce an error:
679 You can't expect this to work.
683 The best solution to such a problem is to put the text into an actual
684 C comment delimited by @samp{/*@dots{}*/}. However,
685 @option{-traditional} suppresses these error messages.
688 Many user programs contain the declaration @samp{long time ();}. In the
689 past, the system header files on many systems did not actually declare
690 @code{time}, so it did not matter what type your program declared it to
691 return. But in systems with ISO C headers, @code{time} is declared to
692 return @code{time_t}, and if that is not the same as @code{long}, then
693 @samp{long time ();} is erroneous.
695 The solution is to change your program to use appropriate system headers
696 (@code{<time.h>} on systems with ISO C headers) and not to declare
697 @code{time} if the system header files declare it, or failing that to
698 use @code{time_t} as the return type of @code{time}.
700 @cindex @code{float} as function value type
702 When compiling functions that return @code{float}, PCC converts it to
703 a double. GCC actually returns a @code{float}. If you are concerned
704 with PCC compatibility, you should declare your functions to return
705 @code{double}; you might as well say what you mean.
710 When compiling functions that return structures or unions, GCC
711 output code normally uses a method different from that used on most
712 versions of Unix. As a result, code compiled with GCC cannot call
713 a structure-returning function compiled with PCC, and vice versa.
715 The method used by GCC is as follows: a structure or union which is
716 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
717 with any other size is stored into an address supplied by the caller
718 (usually in a special, fixed register, but on some machines it is passed
719 on the stack). The machine-description macros @code{STRUCT_VALUE} and
720 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
722 By contrast, PCC on most target machines returns structures and unions
723 of any size by copying the data into an area of static storage, and then
724 returning the address of that storage as if it were a pointer value.
725 The caller must copy the data from that memory area to the place where
726 the value is wanted. GCC does not use this method because it is
727 slower and nonreentrant.
729 On some newer machines, PCC uses a reentrant convention for all
730 structure and union returning. GCC on most of these machines uses a
731 compatible convention when returning structures and unions in memory,
732 but still returns small structures and unions in registers.
734 @opindex fpcc-struct-return
735 You can tell GCC to use a compatible convention for all structure and
736 union returning with the option @option{-fpcc-struct-return}.
738 @cindex preprocessing tokens
739 @cindex preprocessing numbers
741 GCC complains about program fragments such as @samp{0x74ae-0x4000}
742 which appear to be two hexadecimal constants separated by the minus
743 operator. Actually, this string is a single @dfn{preprocessing token}.
744 Each such token must correspond to one token in C@. Since this does not,
745 GCC prints an error message. Although it may appear obvious that what
746 is meant is an operator and two values, the ISO C standard specifically
747 requires that this be treated as erroneous.
749 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
750 begins with a digit and is followed by letters, underscores, digits,
751 periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
752 @samp{p-}, @samp{P+}, or @samp{P-} character sequences. (In strict C89
753 mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
754 appear in preprocessing numbers.)
756 To make the above program fragment valid, place whitespace in front of
757 the minus sign. This whitespace will end the preprocessing number.
761 @section Fixed Header Files
763 GCC needs to install corrected versions of some system header files.
764 This is because most target systems have some header files that won't
765 work with GCC unless they are changed. Some have bugs, some are
766 incompatible with ISO C, and some depend on special features of other
769 Installing GCC automatically creates and installs the fixed header
770 files, by running a program called @code{fixincludes} (or for certain
771 targets an alternative such as @code{fixinc.svr4}). Normally, you
772 don't need to pay attention to this. But there are cases where it
773 doesn't do the right thing automatically.
777 If you update the system's header files, such as by installing a new
778 system version, the fixed header files of GCC are not automatically
779 updated. The easiest way to update them is to reinstall GCC@. (If
780 you want to be clever, look in the makefile and you can find a
784 On some systems, in particular SunOS 4, header file directories contain
785 machine-specific symbolic links in certain places. This makes it
786 possible to share most of the header files among hosts running the
787 same version of SunOS 4 on different machine models.
789 The programs that fix the header files do not understand this special
790 way of using symbolic links; therefore, the directory of fixed header
791 files is good only for the machine model used to build it.
793 In SunOS 4, only programs that look inside the kernel will notice the
794 difference between machine models. Therefore, for most purposes, you
795 need not be concerned about this.
797 It is possible to make separate sets of fixed header files for the
798 different machine models, and arrange a structure of symbolic links so
799 as to use the proper set, but you'll have to do this by hand.
802 On Lynxos, GCC by default does not fix the header files. This is
803 because bugs in the shell cause the @code{fixincludes} script to fail.
805 This means you will encounter problems due to bugs in the system header
806 files. It may be no comfort that they aren't GCC's fault, but it
807 does mean that there's nothing for us to do about them.
810 @node Standard Libraries
811 @section Standard Libraries
814 GCC by itself attempts to be a conforming freestanding implementation.
815 @xref{Standards,,Language Standards Supported by GCC}, for details of
816 what this means. Beyond the library facilities required of such an
817 implementation, the rest of the C library is supplied by the vendor of
818 the operating system. If that C library doesn't conform to the C
819 standards, then your programs might get warnings (especially when using
820 @option{-Wall}) that you don't expect.
822 For example, the @code{sprintf} function on SunOS 4.1.3 returns
823 @code{char *} while the C standard says that @code{sprintf} returns an
824 @code{int}. The @code{fixincludes} program could make the prototype for
825 this function match the Standard, but that would be wrong, since the
826 function will still return @code{char *}.
828 If you need a Standard compliant library, then you need to find one, as
829 GCC does not provide one. The GNU C library (called @code{glibc})
830 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
831 GNU/Linux and HURD-based GNU systems; no recent version of it supports
832 other systems, though some very old versions did. Version 2.2 of the
833 GNU C library includes nearly complete C99 support. You could also ask
834 your operating system vendor if newer libraries are available.
836 @node Disappointments
837 @section Disappointments and Misunderstandings
839 These problems are perhaps regrettable, but we don't know any practical
844 Certain local variables aren't recognized by debuggers when you compile
847 This occurs because sometimes GCC optimizes the variable out of
848 existence. There is no way to tell the debugger how to compute the
849 value such a variable ``would have had'', and it is not clear that would
850 be desirable anyway. So GCC simply does not mention the eliminated
851 variable when it writes debugging information.
853 You have to expect a certain amount of disagreement between the
854 executable and your source code, when you use optimization.
856 @cindex conflicting types
857 @cindex scope of declaration
859 Users often think it is a bug when GCC reports an error for code
863 int foo (struct mumble *);
865 struct mumble @{ @dots{} @};
867 int foo (struct mumble *x)
871 This code really is erroneous, because the scope of @code{struct
872 mumble} in the prototype is limited to the argument list containing it.
873 It does not refer to the @code{struct mumble} defined with file scope
874 immediately below---they are two unrelated types with similar names in
877 But in the definition of @code{foo}, the file-scope type is used
878 because that is available to be inherited. Thus, the definition and
879 the prototype do not match, and you get an error.
881 This behavior may seem silly, but it's what the ISO standard specifies.
882 It is easy enough for you to make your code work by moving the
883 definition of @code{struct mumble} above the prototype. It's not worth
884 being incompatible with ISO C just to avoid an error for the example
888 Accesses to bit-fields even in volatile objects works by accessing larger
889 objects, such as a byte or a word. You cannot rely on what size of
890 object is accessed in order to read or write the bit-field; it may even
891 vary for a given bit-field according to the precise usage.
893 If you care about controlling the amount of memory that is accessed, use
894 volatile but do not use bit-fields.
897 GCC comes with shell scripts to fix certain known problems in system
898 header files. They install corrected copies of various header files in
899 a special directory where only GCC will normally look for them. The
900 scripts adapt to various systems by searching all the system header
901 files for the problem cases that we know about.
903 If new system header files are installed, nothing automatically arranges
904 to update the corrected header files. You will have to reinstall GCC
905 to fix the new header files. More specifically, go to the build
906 directory and delete the files @file{stmp-fixinc} and
907 @file{stmp-headers}, and the subdirectory @code{include}; then do
908 @samp{make install} again.
911 @cindex floating point precision
912 On 68000 and x86 systems, for instance, you can get paradoxical results
913 if you test the precise values of floating point numbers. For example,
914 you can find that a floating point value which is not a NaN is not equal
915 to itself. This results from the fact that the floating point registers
916 hold a few more bits of precision than fit in a @code{double} in memory.
917 Compiled code moves values between memory and floating point registers
918 at its convenience, and moving them into memory truncates them.
920 @opindex ffloat-store
921 You can partially avoid this problem by using the @option{-ffloat-store}
922 option (@pxref{Optimize Options}).
925 On the MIPS, variable argument functions using @file{varargs.h}
926 cannot have a floating point value for the first argument. The
927 reason for this is that in the absence of a prototype in scope,
928 if the first argument is a floating point, it is passed in a
929 floating point register, rather than an integer register.
931 If the code is rewritten to use the ISO standard @file{stdarg.h}
932 method of variable arguments, and the prototype is in scope at
933 the time of the call, everything will work fine.
936 On the H8/300 and H8/300H, variable argument functions must be
937 implemented using the ISO standard @file{stdarg.h} method of
938 variable arguments. Furthermore, calls to functions using @file{stdarg.h}
939 variable arguments must have a prototype for the called function
940 in scope at the time of the call.
943 @node C++ Misunderstandings
944 @section Common Misunderstandings with GNU C++
946 @cindex misunderstandings in C++
947 @cindex surprises in C++
948 @cindex C++ misunderstandings
949 C++ is a complex language and an evolving one, and its standard
950 definition (the ISO C++ standard) was only recently completed. As a
951 result, your C++ compiler may occasionally surprise you, even when its
952 behavior is correct. This section discusses some areas that frequently
953 give rise to questions of this sort.
956 * Static Definitions:: Static member declarations are not definitions
957 * Temporaries:: Temporaries may vanish before you expect
958 * Copy Assignment:: Copy Assignment operators copy virtual bases twice
961 @node Static Definitions
962 @subsection Declare @emph{and} Define Static Members
964 @cindex C++ static data, declaring and defining
965 @cindex static data in C++, declaring and defining
966 @cindex declaring static data in C++
967 @cindex defining static data in C++
968 When a class has static data members, it is not enough to @emph{declare}
969 the static member; you must also @emph{define} it. For example:
980 This declaration only establishes that the class @code{Foo} has an
981 @code{int} named @code{Foo::bar}, and a member function named
982 @code{Foo::method}. But you still need to define @emph{both}
983 @code{method} and @code{bar} elsewhere. According to the ISO
984 standard, you must supply an initializer in one (and only one) source
991 Other C++ compilers may not correctly implement the standard behavior.
992 As a result, when you switch to @code{g++} from one of these compilers,
993 you may discover that a program that appeared to work correctly in fact
994 does not conform to the standard: @code{g++} reports as undefined
995 symbols any static data members that lack definitions.
998 @subsection Temporaries May Vanish Before You Expect
1000 @cindex temporaries, lifetime of
1001 @cindex portions of temporary objects, pointers to
1002 It is dangerous to use pointers or references to @emph{portions} of a
1003 temporary object. The compiler may very well delete the object before
1004 you expect it to, leaving a pointer to garbage. The most common place
1005 where this problem crops up is in classes like string classes,
1006 especially ones that define a conversion function to type @code{char *}
1007 or @code{const char *}---which is one reason why the standard
1008 @code{string} class requires you to call the @code{c_str} member
1009 function. However, any class that returns a pointer to some internal
1010 structure is potentially subject to this problem.
1012 For example, a program may use a function @code{strfunc} that returns
1013 @code{string} objects, and another function @code{charfunc} that
1014 operates on pointers to @code{char}:
1018 void charfunc (const char *);
1023 const char *p = strfunc().c_str();
1032 In this situation, it may seem reasonable to save a pointer to the C
1033 string returned by the @code{c_str} member function and use that rather
1034 than call @code{c_str} repeatedly. However, the temporary string
1035 created by the call to @code{strfunc} is destroyed after @code{p} is
1036 initialized, at which point @code{p} is left pointing to freed memory.
1038 Code like this may run successfully under some other compilers,
1039 particularly obsolete cfront-based compilers that delete temporaries
1040 along with normal local variables. However, the GNU C++ behavior is
1041 standard-conforming, so if your program depends on late destruction of
1042 temporaries it is not portable.
1044 The safe way to write such code is to give the temporary a name, which
1045 forces it to remain until the end of the scope of the name. For
1049 string& tmp = strfunc ();
1050 charfunc (tmp.c_str ());
1053 @node Copy Assignment
1054 @subsection Implicit Copy-Assignment for Virtual Bases
1056 When a base class is virtual, only one subobject of the base class
1057 belongs to each full object. Also, the constructors and destructors are
1058 invoked only once, and called from the most-derived class. However, such
1059 objects behave unspecified when being assigned. For example:
1064 Base(char *n) : name(strdup(n))@{@}
1065 Base& operator= (const Base& other)@{
1067 name = strdup (other.name);
1071 struct A:virtual Base@{
1076 struct B:virtual Base@{
1081 struct Derived:public A, public B@{
1082 Derived():Base("Derived")@{@}
1085 void func(Derived &d1, Derived &d2)
1091 The C++ standard specifies that @samp{Base::Base} is only called once
1092 when constructing or copy-constructing a Derived object. It is
1093 unspecified whether @samp{Base::operator=} is called more than once when
1094 the implicit copy-assignment for Derived objects is invoked (as it is
1095 inside @samp{func} in the example).
1097 g++ implements the ``intuitive'' algorithm for copy-assignment: assign all
1098 direct bases, then assign all members. In that algorithm, the virtual
1099 base subobject can be encountered many times. In the example, copying
1100 proceeds in the following order: @samp{val}, @samp{name} (via
1101 @code{strdup}), @samp{bval}, and @samp{name} again.
1103 If application code relies on copy-assignment, a user-defined
1104 copy-assignment operator removes any uncertainties. With such an
1105 operator, the application can define whether and how the virtual base
1106 subobject is assigned.
1108 @node Protoize Caveats
1109 @section Caveats of using @command{protoize}
1111 The conversion programs @command{protoize} and @command{unprotoize} can
1112 sometimes change a source file in a way that won't work unless you
1117 @command{protoize} can insert references to a type name or type tag before
1118 the definition, or in a file where they are not defined.
1120 If this happens, compiler error messages should show you where the new
1121 references are, so fixing the file by hand is straightforward.
1124 There are some C constructs which @command{protoize} cannot figure out.
1125 For example, it can't determine argument types for declaring a
1126 pointer-to-function variable; this you must do by hand. @command{protoize}
1127 inserts a comment containing @samp{???} each time it finds such a
1128 variable; so you can find all such variables by searching for this
1129 string. ISO C does not require declaring the argument types of
1130 pointer-to-function types.
1133 Using @command{unprotoize} can easily introduce bugs. If the program
1134 relied on prototypes to bring about conversion of arguments, these
1135 conversions will not take place in the program without prototypes.
1136 One case in which you can be sure @command{unprotoize} is safe is when
1137 you are removing prototypes that were made with @command{protoize}; if
1138 the program worked before without any prototypes, it will work again
1141 @opindex Wconversion
1142 You can find all the places where this problem might occur by compiling
1143 the program with the @option{-Wconversion} option. It prints a warning
1144 whenever an argument is converted.
1147 Both conversion programs can be confused if there are macro calls in and
1148 around the text to be converted. In other words, the standard syntax
1149 for a declaration or definition must not result from expanding a macro.
1150 This problem is inherent in the design of C and cannot be fixed. If
1151 only a few functions have confusing macro calls, you can easily convert
1155 @command{protoize} cannot get the argument types for a function whose
1156 definition was not actually compiled due to preprocessing conditionals.
1157 When this happens, @command{protoize} changes nothing in regard to such
1158 a function. @command{protoize} tries to detect such instances and warn
1161 You can generally work around this problem by using @command{protoize} step
1162 by step, each time specifying a different set of @option{-D} options for
1163 compilation, until all of the functions have been converted. There is
1164 no automatic way to verify that you have got them all, however.
1167 Confusion may result if there is an occasion to convert a function
1168 declaration or definition in a region of source code where there is more
1169 than one formal parameter list present. Thus, attempts to convert code
1170 containing multiple (conditionally compiled) versions of a single
1171 function header (in the same vicinity) may not produce the desired (or
1174 If you plan on converting source files which contain such code, it is
1175 recommended that you first make sure that each conditionally compiled
1176 region of source code which contains an alternative function header also
1177 contains at least one additional follower token (past the final right
1178 parenthesis of the function header). This should circumvent the
1182 @command{unprotoize} can become confused when trying to convert a function
1183 definition or declaration which contains a declaration for a
1184 pointer-to-function formal argument which has the same name as the
1185 function being defined or declared. We recommend you avoid such choices
1186 of formal parameter names.
1189 You might also want to correct some of the indentation by hand and break
1190 long lines. (The conversion programs don't write lines longer than
1191 eighty characters in any case.)
1195 @section Certain Changes We Don't Want to Make
1197 This section lists changes that people frequently request, but which
1198 we do not make because we think GCC is better without them.
1202 Checking the number and type of arguments to a function which has an
1203 old-fashioned definition and no prototype.
1205 Such a feature would work only occasionally---only for calls that appear
1206 in the same file as the called function, following the definition. The
1207 only way to check all calls reliably is to add a prototype for the
1208 function. But adding a prototype eliminates the motivation for this
1209 feature. So the feature is not worthwhile.
1212 Warning about using an expression whose type is signed as a shift count.
1214 Shift count operands are probably signed more often than unsigned.
1215 Warning about this would cause far more annoyance than good.
1218 Warning about assigning a signed value to an unsigned variable.
1220 Such assignments must be very common; warning about them would cause
1221 more annoyance than good.
1224 Warning when a non-void function value is ignored.
1226 Coming as I do from a Lisp background, I balk at the idea that there is
1227 something dangerous about discarding a value. There are functions that
1228 return values which some callers may find useful; it makes no sense to
1229 clutter the program with a cast to @code{void} whenever the value isn't
1233 @opindex fshort-enums
1234 Making @option{-fshort-enums} the default.
1236 This would cause storage layout to be incompatible with most other C
1237 compilers. And it doesn't seem very important, given that you can get
1238 the same result in other ways. The case where it matters most is when
1239 the enumeration-valued object is inside a structure, and in that case
1240 you can specify a field width explicitly.
1243 Making bit-fields unsigned by default on particular machines where ``the
1244 ABI standard'' says to do so.
1246 The ISO C standard leaves it up to the implementation whether a bit-field
1247 declared plain @code{int} is signed or not. This in effect creates two
1248 alternative dialects of C@.
1250 @opindex fsigned-bitfields
1251 @opindex funsigned-bitfields
1252 The GNU C compiler supports both dialects; you can specify the signed
1253 dialect with @option{-fsigned-bitfields} and the unsigned dialect with
1254 @option{-funsigned-bitfields}. However, this leaves open the question of
1255 which dialect to use by default.
1257 Currently, the preferred dialect makes plain bit-fields signed, because
1258 this is simplest. Since @code{int} is the same as @code{signed int} in
1259 every other context, it is cleanest for them to be the same in bit-fields
1262 Some computer manufacturers have published Application Binary Interface
1263 standards which specify that plain bit-fields should be unsigned. It is
1264 a mistake, however, to say anything about this issue in an ABI@. This is
1265 because the handling of plain bit-fields distinguishes two dialects of C@.
1266 Both dialects are meaningful on every type of machine. Whether a
1267 particular object file was compiled using signed bit-fields or unsigned
1268 is of no concern to other object files, even if they access the same
1269 bit-fields in the same data structures.
1271 A given program is written in one or the other of these two dialects.
1272 The program stands a chance to work on most any machine if it is
1273 compiled with the proper dialect. It is unlikely to work at all if
1274 compiled with the wrong dialect.
1276 Many users appreciate the GNU C compiler because it provides an
1277 environment that is uniform across machines. These users would be
1278 inconvenienced if the compiler treated plain bit-fields differently on
1281 Occasionally users write programs intended only for a particular machine
1282 type. On these occasions, the users would benefit if the GNU C compiler
1283 were to support by default the same dialect as the other compilers on
1284 that machine. But such applications are rare. And users writing a
1285 program to run on more than one type of machine cannot possibly benefit
1286 from this kind of compatibility.
1288 This is why GCC does and will treat plain bit-fields in the same
1289 fashion on all types of machines (by default).
1291 There are some arguments for making bit-fields unsigned by default on all
1292 machines. If, for example, this becomes a universal de facto standard,
1293 it would make sense for GCC to go along with it. This is something
1294 to be considered in the future.
1296 (Of course, users strongly concerned about portability should indicate
1297 explicitly in each bit-field whether it is signed or not. In this way,
1298 they write programs which have the same meaning in both C dialects.)
1302 @opindex traditional
1304 Undefining @code{__STDC__} when @option{-ansi} is not used.
1306 Currently, GCC defines @code{__STDC__} as long as you don't use
1307 @option{-traditional}. This provides good results in practice.
1309 Programmers normally use conditionals on @code{__STDC__} to ask whether
1310 it is safe to use certain features of ISO C, such as function
1311 prototypes or ISO token concatenation. Since plain @command{gcc} supports
1312 all the features of ISO C, the correct answer to these questions is
1315 Some users try to use @code{__STDC__} to check for the availability of
1316 certain library facilities. This is actually incorrect usage in an ISO
1317 C program, because the ISO C standard says that a conforming
1318 freestanding implementation should define @code{__STDC__} even though it
1319 does not have the library facilities. @samp{gcc -ansi -pedantic} is a
1320 conforming freestanding implementation, and it is therefore required to
1321 define @code{__STDC__}, even though it does not come with an ISO C
1324 Sometimes people say that defining @code{__STDC__} in a compiler that
1325 does not completely conform to the ISO C standard somehow violates the
1326 standard. This is illogical. The standard is a standard for compilers
1327 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
1328 compilers such as plain @command{gcc}. Whatever the ISO C standard says
1329 is relevant to the design of plain @command{gcc} without @option{-ansi} only
1330 for pragmatic reasons, not as a requirement.
1332 GCC normally defines @code{__STDC__} to be 1, and in addition
1333 defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
1334 or a @option{-std} option for strict conformance to some version of ISO C@.
1335 On some hosts, system include files use a different convention, where
1336 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
1337 conformance to the C Standard. GCC follows the host convention when
1338 processing system include files, but when processing user files it follows
1339 the usual GNU C convention.
1342 Undefining @code{__STDC__} in C++.
1344 Programs written to compile with C++-to-C translators get the
1345 value of @code{__STDC__} that goes with the C compiler that is
1346 subsequently used. These programs must test @code{__STDC__}
1347 to determine what kind of C preprocessor that compiler uses:
1348 whether they should concatenate tokens in the ISO C fashion
1349 or in the traditional fashion.
1351 These programs work properly with GNU C++ if @code{__STDC__} is defined.
1352 They would not work otherwise.
1354 In addition, many header files are written to provide prototypes in ISO
1355 C but not in traditional C@. Many of these header files can work without
1356 change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
1357 is not defined, they will all fail, and will all need to be changed to
1358 test explicitly for C++ as well.
1361 Deleting ``empty'' loops.
1363 Historically, GCC has not deleted ``empty'' loops under the
1364 assumption that the most likely reason you would put one in a program is
1365 to have a delay, so deleting them will not make real programs run any
1368 However, the rationale here is that optimization of a nonempty loop
1369 cannot produce an empty one, which holds for C but is not always the
1372 @opindex funroll-loops
1373 Moreover, with @option{-funroll-loops} small ``empty'' loops are already
1374 removed, so the current behavior is both sub-optimal and inconsistent
1375 and will change in the future.
1378 Making side effects happen in the same order as in some other compiler.
1380 @cindex side effects, order of evaluation
1381 @cindex order of evaluation, side effects
1382 It is never safe to depend on the order of evaluation of side effects.
1383 For example, a function call like this may very well behave differently
1384 from one compiler to another:
1387 void func (int, int);
1393 There is no guarantee (in either the C or the C++ standard language
1394 definitions) that the increments will be evaluated in any particular
1395 order. Either increment might happen first. @code{func} might get the
1396 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
1399 Not allowing structures with volatile fields in registers.
1401 Strictly speaking, there is no prohibition in the ISO C standard
1402 against allowing structures with volatile fields in registers, but
1403 it does not seem to make any sense and is probably not what you wanted
1404 to do. So the compiler will give an error message in this case.
1407 Making certain warnings into errors by default.
1409 Some ISO C testsuites report failure when the compiler does not produce
1410 an error message for a certain program.
1412 @opindex pedantic-errors
1413 ISO C requires a ``diagnostic'' message for certain kinds of invalid
1414 programs, but a warning is defined by GCC to count as a diagnostic. If
1415 GCC produces a warning but not an error, that is correct ISO C support.
1416 If test suites call this ``failure'', they should be run with the GCC
1417 option @option{-pedantic-errors}, which will turn these warnings into
1422 @node Warnings and Errors
1423 @section Warning Messages and Error Messages
1425 @cindex error messages
1426 @cindex warnings vs errors
1427 @cindex messages, warning and error
1428 The GNU compiler can produce two kinds of diagnostics: errors and
1429 warnings. Each kind has a different purpose:
1433 @dfn{Errors} report problems that make it impossible to compile your
1434 program. GCC reports errors with the source file name and line
1435 number where the problem is apparent.
1438 @dfn{Warnings} report other unusual conditions in your code that
1439 @emph{may} indicate a problem, although compilation can (and does)
1440 proceed. Warning messages also report the source file name and line
1441 number, but include the text @samp{warning:} to distinguish them
1442 from error messages.
1445 Warnings may indicate danger points where you should check to make sure
1446 that your program really does what you intend; or the use of obsolete
1447 features; or the use of nonstandard features of GNU C or C++. Many
1448 warnings are issued only if you ask for them, with one of the @option{-W}
1449 options (for instance, @option{-Wall} requests a variety of useful
1453 @opindex pedantic-errors
1454 GCC always tries to compile your program if possible; it never
1455 gratuitously rejects a program whose meaning is clear merely because
1456 (for instance) it fails to conform to a standard. In some cases,
1457 however, the C and C++ standards specify that certain extensions are
1458 forbidden, and a diagnostic @emph{must} be issued by a conforming
1459 compiler. The @option{-pedantic} option tells GCC to issue warnings in
1460 such cases; @option{-pedantic-errors} says to make them errors instead.
1461 This does not mean that @emph{all} non-ISO constructs get warnings
1464 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
1465 more detail on these and related command-line options.