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.
90 @xref{Cross-compilation,,Cross Compilation and Floating Point,
91 gccint, GNU Compiler Collection (GCC) Internals}.
94 At present, the program @file{mips-tfile} which adds debug
95 support to object files on MIPS systems does not work in a cross
100 @section Interoperation
102 This section lists various difficulties encountered in using GCC
103 together with other compilers or with the assemblers, linkers,
104 libraries and debuggers on certain systems.
108 G++ does not do name mangling in the same way as other C++
109 compilers. This means that object files compiled with one compiler
110 cannot be used with another.
112 This effect is intentional, to protect you from more subtle problems.
113 Compilers differ as to many internal details of C++ implementation,
114 including: how class instances are laid out, how multiple inheritance is
115 implemented, and how virtual function calls are handled. If the name
116 encoding were made the same, your programs would link against libraries
117 provided from other compilers---but the programs would then crash when
118 run. Incompatible libraries are then detected at link time, rather than
122 Older GDB versions sometimes fail to read the output of GCC version
123 2. If you have trouble, get GDB version 4.4 or later.
127 DBX rejects some files produced by GCC, though it accepts similar
128 constructs in output from PCC@. Until someone can supply a coherent
129 description of what is valid DBX input and what is not, there is
130 nothing I can do about these problems. You are on your own.
133 The GNU assembler (GAS) does not support PIC@. To generate PIC code, you
134 must use some other assembler, such as @file{/bin/as}.
137 On some BSD systems, including some versions of Ultrix, use of profiling
138 causes static variable destructors (currently used only in C++) not to
142 @cindex @code{vfork}, for the Sun-4
144 There is a bug in @code{vfork} on the Sun-4 which causes the registers
145 of the child process to clobber those of the parent. Because of this,
146 programs that call @code{vfork} are likely to lose when compiled
147 optimized with GCC when the child code alters registers which contain
148 C variables in the parent. This affects variables which are live in the
149 parent across the call to @code{vfork}.
151 If you encounter this, you can work around the problem by declaring
152 variables @code{volatile} in the function that calls @code{vfork}, until
153 the problem goes away, or by not declaring them @code{register} and not
154 using @option{-O} for those source files.
158 On some SGI systems, when you use @option{-lgl_s} as an option,
159 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
160 Naturally, this does not happen when you use GCC@.
161 You must specify all three options explicitly.
164 On a Sparc, GCC aligns all values of type @code{double} on an 8-byte
165 boundary, and it expects every @code{double} to be so aligned. The Sun
166 compiler usually gives @code{double} values 8-byte alignment, with one
167 exception: function arguments of type @code{double} may not be aligned.
169 As a result, if a function compiled with Sun CC takes the address of an
170 argument of type @code{double} and passes this pointer of type
171 @code{double *} to a function compiled with GCC, dereferencing the
172 pointer may cause a fatal signal.
174 One way to solve this problem is to compile your entire program with GCC@.
175 Another solution is to modify the function that is compiled with
176 Sun CC to copy the argument into a local variable; local variables
177 are always properly aligned. A third solution is to modify the function
178 that uses the pointer to dereference it via the following function
179 @code{access_double} instead of directly with @samp{*}:
183 access_double (double *unaligned_ptr)
185 union d2i @{ double d; int i[2]; @};
187 union d2i *p = (union d2i *) unaligned_ptr;
198 Storing into the pointer can be done likewise with the same union.
201 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
202 may allocate memory that is only 4 byte aligned. Since GCC on the
203 Sparc assumes that doubles are 8 byte aligned, this may result in a
204 fatal signal if doubles are stored in memory allocated by the
205 @file{libmalloc.a} library.
207 The solution is to not use the @file{libmalloc.a} library. Use instead
208 @code{malloc} and related functions from @file{libc.a}; they do not have
212 Sun forgot to include a static version of @file{libdl.a} with some
213 versions of SunOS (mainly 4.1). This results in undefined symbols when
214 linking static binaries (that is, if you use @option{-static}). If you
215 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
216 when linking, compile and link against the file
217 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
220 The 128-bit long double format that the Sparc port supports currently
221 works by using the architecturally defined quad-word floating point
222 instructions. Since there is no hardware that supports these
223 instructions they must be emulated by the operating system. Long
224 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
225 kernel emulator uses an obsolete and incompatible format. Long doubles
226 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
227 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
228 does not enable them by default. Long doubles appear to work in Sun OS
232 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
233 compile GCC correctly. We do not yet know why. However, GCC
234 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
235 compile itself properly on 9.01.
238 On the HP PA machine, ADB sometimes fails to work on functions compiled
239 with GCC@. Specifically, it fails to work on functions that use
240 @code{alloca} or variable-size arrays. This is because GCC doesn't
241 generate HP-UX unwind descriptors for such functions. It may even be
242 impossible to generate them.
245 Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
246 the preliminary GNU tools.
249 Taking the address of a label may generate errors from the HP-UX
250 PA assembler. GAS for the PA does not have this problem.
253 Using floating point parameters for indirect calls to static functions
254 will not work when using the HP assembler. There simply is no way for GCC
255 to specify what registers hold arguments for static functions when using
256 the HP assembler. GAS for the PA does not have this problem.
259 In extremely rare cases involving some very large functions you may
260 receive errors from the HP linker complaining about an out of bounds
261 unconditional branch offset. This used to occur more often in previous
262 versions of GCC, but is now exceptionally rare. If you should run
263 into it, you can work around by making your function smaller.
266 GCC compiled code sometimes emits warnings from the HP-UX assembler of
270 (warning) Use of GR3 when
271 frame >= 8192 may cause conflict.
274 These warnings are harmless and can be safely ignored.
277 On the IBM RS/6000, compiling code of the form
288 will cause the linker to report an undefined symbol @code{foo}.
289 Although this behavior differs from most other systems, it is not a
290 bug because redefining an @code{extern} variable as @code{static}
291 is undefined in ISO C@.
294 In extremely rare cases involving some very large functions you may
295 receive errors from the AIX Assembler complaining about a displacement
296 that is too large. If you should run into it, you can work around by
297 making your function smaller.
300 The @file{libstdc++.a} library in GCC relies on the SVR4 dynamic
301 linker semantics which merges global symbols between libraries and
302 applications, especially necessary for C++ streams functionality.
303 This is not the default behavior of AIX shared libraries and dynamic
304 linking. @file{libstdc++.a} is built on AIX with ``runtime-linking''
305 enabled so that symbol merging can occur. To utilize this feature,
306 the application linked with @file{libstdc++.a} must include the
307 @option{-Wl,-brtl} flag on the link line. G++ cannot impose this
308 because this option may interfere with the semantics of the user
309 program and users may not always use @samp{g++} to link his or her
310 application. Applications are not required to use the
311 @option{-Wl,-brtl} flag on the link line---the rest of the
312 @file{libstdc++.a} library which is not dependent on the symbol
313 merging semantics will continue to function correctly.
316 An application can interpose its own definition of functions for
317 functions invoked by @file{libstdc++.a} with ``runtime-linking''
318 enabled on AIX. To accomplish this the application must be linked
319 with ``runtime-linking'' option and the functions explicitly must be
320 exported by the application (@option{-Wl,-brtl,-bE:exportfile}).
323 AIX on the RS/6000 provides support (NLS) for environments outside of
324 the United States. Compilers and assemblers use NLS to support
325 locale-specific representations of various objects including
326 floating-point numbers (@samp{.} vs @samp{,} for separating decimal
327 fractions). There have been problems reported where the library linked
328 with GCC does not produce the same floating-point formats that the
329 assembler accepts. If you have this problem, set the @env{LANG}
330 environment variable to @samp{C} or @samp{En_US}.
333 @opindex fdollars-in-identifiers
334 Even if you specify @option{-fdollars-in-identifiers},
335 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
336 to a restriction in the IBM assembler. GAS supports these
340 @opindex mno-serialize-volatile
341 There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that
342 occurs when the @samp{fldcr} instruction is used. GCC uses
343 @samp{fldcr} on the 88100 to serialize volatile memory references. Use
344 the option @option{-mno-serialize-volatile} if your version of the
345 assembler has this bug.
348 On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
349 messages from the linker. These warning messages complain of mismatched
350 psect attributes. You can ignore them.
353 On NewsOS version 3, if you include both of the files @file{stddef.h}
354 and @file{sys/types.h}, you get an error because there are two typedefs
355 of @code{size_t}. You should change @file{sys/types.h} by adding these
356 lines around the definition of @code{size_t}:
361 @var{actual-typedef-here}
367 On the Alliant, the system's own convention for returning structures
368 and unions is unusual, and is not compatible with GCC no matter
369 what options are used.
374 @opindex mhc-struct-return
375 On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
376 convention for structure and union returning. Use the option
377 @option{-mhc-struct-return} to tell GCC to use a convention compatible
380 @cindex VAX calling convention
381 @cindex Ultrix calling convention
384 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
385 by function calls. However, the C compiler uses conventions compatible
386 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
388 GCC uses the same convention as the Ultrix C compiler. You can use
389 these options to produce code compatible with the Fortran compiler:
392 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
396 On the WE32k, you may find that programs compiled with GCC do not
397 work with the standard shared C library. You may need to link with
398 the ordinary C compiler. If you do so, you must specify the following
402 -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
405 The first specifies where to find the library @file{libgcc.a}
406 specified with the @option{-lgcc} option.
408 GCC does linking by invoking @command{ld}, just as @command{cc} does, and
409 there is no reason why it @emph{should} matter which compilation program
410 you use to invoke @command{ld}. If someone tracks this problem down,
411 it can probably be fixed easily.
414 On the Alpha, you may get assembler errors about invalid syntax as a
415 result of floating point constants. This is due to a bug in the C
416 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid
417 floating point numbers, they sometimes print @samp{NaN}.
420 On Irix 4.0.5F (and perhaps in some other versions), an assembler bug
421 sometimes reorders instructions incorrectly when optimization is turned
422 on. If you think this may be happening to you, try using the GNU
423 assembler; GAS version 2.1 supports ECOFF on Irix.
426 Or use the @option{-noasmopt} option when you compile GCC with itself,
427 and then again when you compile your program. (This is a temporary
428 kludge to turn off assembler optimization on Irix.) If this proves to
429 be what you need, edit the assembler spec in the file @file{specs} so
430 that it unconditionally passes @option{-O0} to the assembler, and never
431 passes @option{-O2} or @option{-O3}.
435 @section Problems Compiling Certain Programs
437 @c prevent bad page break with this line
438 Certain programs have problems compiling.
442 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
443 because of problems in DEC's versions of the X11 header files
444 @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
445 @option{-I/usr/include/mit} to use the MIT versions of the header files,
446 or fixing the header files by adding this:
450 #define NeedFunctionPrototypes 0
455 On various 386 Unix systems derived from System V, including SCO, ISC,
456 and ESIX, you may get error messages about running out of virtual memory
457 while compiling certain programs.
459 You can prevent this problem by linking GCC with the GNU malloc
460 (which thus replaces the malloc that comes with the system). GNU malloc
461 is available as a separate package, and also in the file
462 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
464 If you have installed GNU malloc as a separate library package, use this
465 option when you relink GCC:
468 MALLOC=/usr/local/lib/libgmalloc.a
471 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
472 the object file to @file{gmalloc.o} and use this option when you relink
480 @node Incompatibilities
481 @section Incompatibilities of GCC
482 @cindex incompatibilities of GCC
485 There are several noteworthy incompatibilities between GNU C and K&R
486 (non-ISO) versions of C@.
489 @cindex string constants
490 @cindex read-only strings
491 @cindex shared strings
493 GCC normally makes string constants read-only. If several
494 identical-looking string constants are used, GCC stores only one
497 @cindex @code{mktemp}, and constant strings
498 One consequence is that you cannot call @code{mktemp} with a string
499 constant argument. The function @code{mktemp} always alters the
500 string its argument points to.
502 @cindex @code{sscanf}, and constant strings
503 @cindex @code{fscanf}, and constant strings
504 @cindex @code{scanf}, and constant strings
505 Another consequence is that @code{sscanf} does not work on some systems
506 when passed a string constant as its format control string or input.
507 This is because @code{sscanf} incorrectly tries to write into the string
508 constant. Likewise @code{fscanf} and @code{scanf}.
510 @opindex fwritable-strings
511 The best solution to these problems is to change the program to use
512 @code{char}-array variables with initialization strings for these
513 purposes instead of string constants. But if this is not possible,
514 you can use the @option{-fwritable-strings} flag, which directs GCC
515 to handle string constants the same way most C compilers do.
518 @code{-2147483648} is positive.
520 This is because 2147483648 cannot fit in the type @code{int}, so
521 (following the ISO C rules) its data type is @code{unsigned long int}.
522 Negating this value yields 2147483648 again.
525 GCC does not substitute macro arguments when they appear inside of
526 string constants. For example, the following macro in GCC
533 will produce output @code{"a"} regardless of what the argument @var{a} is.
535 @cindex @code{setjmp} incompatibilities
536 @cindex @code{longjmp} incompatibilities
538 When you use @code{setjmp} and @code{longjmp}, the only automatic
539 variables guaranteed to remain valid are those declared
540 @code{volatile}. This is a consequence of automatic register
541 allocation. Consider this function:
555 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
560 Here @code{a} may or may not be restored to its first value when the
561 @code{longjmp} occurs. If @code{a} is allocated in a register, then
562 its first value is restored; otherwise, it keeps the last value stored
566 If you use the @option{-W} option with the @option{-O} option, you will
567 get a warning when GCC thinks such a problem might be possible.
570 Programs that use preprocessing directives in the middle of macro
571 arguments do not work with GCC@. For example, a program like this
582 ISO C does not permit such a construct.
585 K&R compilers allow comments to cross over an inclusion boundary
586 (i.e.@: started in an include file and ended in the including file). I think
587 this would be quite ugly and can't imagine it could be needed.
589 @cindex external declaration scope
590 @cindex scope of external declarations
591 @cindex declaration scope
593 Declarations of external variables and functions within a block apply
594 only to the block containing the declaration. In other words, they
595 have the same scope as any other declaration in the same place.
597 In some other C compilers, a @code{extern} declaration affects all the
598 rest of the file even if it happens within a block.
601 In traditional C, you can combine @code{long}, etc., with a typedef name,
606 typedef long foo bar;
609 In ISO C, this is not allowed: @code{long} and other type modifiers
610 require an explicit @code{int}.
612 @cindex typedef names as function parameters
614 PCC allows typedef names to be used as function parameters.
617 Traditional C allows the following erroneous pair of declarations to
618 appear together in a given scope:
626 GCC treats all characters of identifiers as significant. According to
627 K&R-1 (2.2), ``No more than the first eight characters are significant,
628 although more may be used.''. Also according to K&R-1 (2.2), ``An
629 identifier is a sequence of letters and digits; the first character must
630 be a letter. The underscore _ counts as a letter.'', but GCC also
631 allows dollar signs in identifiers.
635 PCC allows whitespace in the middle of compound assignment operators
636 such as @samp{+=}. GCC, following the ISO standard, does not
642 GCC complains about unterminated character constants inside of
643 preprocessing conditionals that fail. Some programs have English
644 comments enclosed in conditionals that are guaranteed to fail; if these
645 comments contain apostrophes, GCC will probably report an error. For
646 example, this code would produce an error:
650 You can't expect this to work.
654 The best solution to such a problem is to put the text into an actual
655 C comment delimited by @samp{/*@dots{}*/}.
658 Many user programs contain the declaration @samp{long time ();}. In the
659 past, the system header files on many systems did not actually declare
660 @code{time}, so it did not matter what type your program declared it to
661 return. But in systems with ISO C headers, @code{time} is declared to
662 return @code{time_t}, and if that is not the same as @code{long}, then
663 @samp{long time ();} is erroneous.
665 The solution is to change your program to use appropriate system headers
666 (@code{<time.h>} on systems with ISO C headers) and not to declare
667 @code{time} if the system header files declare it, or failing that to
668 use @code{time_t} as the return type of @code{time}.
670 @cindex @code{float} as function value type
672 When compiling functions that return @code{float}, PCC converts it to
673 a double. GCC actually returns a @code{float}. If you are concerned
674 with PCC compatibility, you should declare your functions to return
675 @code{double}; you might as well say what you mean.
680 When compiling functions that return structures or unions, GCC
681 output code normally uses a method different from that used on most
682 versions of Unix. As a result, code compiled with GCC cannot call
683 a structure-returning function compiled with PCC, and vice versa.
685 The method used by GCC is as follows: a structure or union which is
686 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
687 with any other size is stored into an address supplied by the caller
688 (usually in a special, fixed register, but on some machines it is passed
689 on the stack). The machine-description macros @code{STRUCT_VALUE} and
690 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
692 By contrast, PCC on most target machines returns structures and unions
693 of any size by copying the data into an area of static storage, and then
694 returning the address of that storage as if it were a pointer value.
695 The caller must copy the data from that memory area to the place where
696 the value is wanted. GCC does not use this method because it is
697 slower and nonreentrant.
699 On some newer machines, PCC uses a reentrant convention for all
700 structure and union returning. GCC on most of these machines uses a
701 compatible convention when returning structures and unions in memory,
702 but still returns small structures and unions in registers.
704 @opindex fpcc-struct-return
705 You can tell GCC to use a compatible convention for all structure and
706 union returning with the option @option{-fpcc-struct-return}.
708 @cindex preprocessing tokens
709 @cindex preprocessing numbers
711 GCC complains about program fragments such as @samp{0x74ae-0x4000}
712 which appear to be two hexadecimal constants separated by the minus
713 operator. Actually, this string is a single @dfn{preprocessing token}.
714 Each such token must correspond to one token in C@. Since this does not,
715 GCC prints an error message. Although it may appear obvious that what
716 is meant is an operator and two values, the ISO C standard specifically
717 requires that this be treated as erroneous.
719 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
720 begins with a digit and is followed by letters, underscores, digits,
721 periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
722 @samp{p-}, @samp{P+}, or @samp{P-} character sequences. (In strict C89
723 mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
724 appear in preprocessing numbers.)
726 To make the above program fragment valid, place whitespace in front of
727 the minus sign. This whitespace will end the preprocessing number.
731 @section Fixed Header Files
733 GCC needs to install corrected versions of some system header files.
734 This is because most target systems have some header files that won't
735 work with GCC unless they are changed. Some have bugs, some are
736 incompatible with ISO C, and some depend on special features of other
739 Installing GCC automatically creates and installs the fixed header
740 files, by running a program called @code{fixincludes} (or for certain
741 targets an alternative such as @code{fixinc.svr4}). Normally, you
742 don't need to pay attention to this. But there are cases where it
743 doesn't do the right thing automatically.
747 If you update the system's header files, such as by installing a new
748 system version, the fixed header files of GCC are not automatically
749 updated. The easiest way to update them is to reinstall GCC@. (If
750 you want to be clever, look in the makefile and you can find a
754 On some systems, in particular SunOS 4, header file directories contain
755 machine-specific symbolic links in certain places. This makes it
756 possible to share most of the header files among hosts running the
757 same version of SunOS 4 on different machine models.
759 The programs that fix the header files do not understand this special
760 way of using symbolic links; therefore, the directory of fixed header
761 files is good only for the machine model used to build it.
763 In SunOS 4, only programs that look inside the kernel will notice the
764 difference between machine models. Therefore, for most purposes, you
765 need not be concerned about this.
767 It is possible to make separate sets of fixed header files for the
768 different machine models, and arrange a structure of symbolic links so
769 as to use the proper set, but you'll have to do this by hand.
772 On Lynxos, GCC by default does not fix the header files. This is
773 because bugs in the shell cause the @code{fixincludes} script to fail.
775 This means you will encounter problems due to bugs in the system header
776 files. It may be no comfort that they aren't GCC's fault, but it
777 does mean that there's nothing for us to do about them.
780 @node Standard Libraries
781 @section Standard Libraries
784 GCC by itself attempts to be a conforming freestanding implementation.
785 @xref{Standards,,Language Standards Supported by GCC}, for details of
786 what this means. Beyond the library facilities required of such an
787 implementation, the rest of the C library is supplied by the vendor of
788 the operating system. If that C library doesn't conform to the C
789 standards, then your programs might get warnings (especially when using
790 @option{-Wall}) that you don't expect.
792 For example, the @code{sprintf} function on SunOS 4.1.3 returns
793 @code{char *} while the C standard says that @code{sprintf} returns an
794 @code{int}. The @code{fixincludes} program could make the prototype for
795 this function match the Standard, but that would be wrong, since the
796 function will still return @code{char *}.
798 If you need a Standard compliant library, then you need to find one, as
799 GCC does not provide one. The GNU C library (called @code{glibc})
800 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
801 GNU/Linux and HURD-based GNU systems; no recent version of it supports
802 other systems, though some very old versions did. Version 2.2 of the
803 GNU C library includes nearly complete C99 support. You could also ask
804 your operating system vendor if newer libraries are available.
806 @node Disappointments
807 @section Disappointments and Misunderstandings
809 These problems are perhaps regrettable, but we don't know any practical
814 Certain local variables aren't recognized by debuggers when you compile
817 This occurs because sometimes GCC optimizes the variable out of
818 existence. There is no way to tell the debugger how to compute the
819 value such a variable ``would have had'', and it is not clear that would
820 be desirable anyway. So GCC simply does not mention the eliminated
821 variable when it writes debugging information.
823 You have to expect a certain amount of disagreement between the
824 executable and your source code, when you use optimization.
826 @cindex conflicting types
827 @cindex scope of declaration
829 Users often think it is a bug when GCC reports an error for code
833 int foo (struct mumble *);
835 struct mumble @{ @dots{} @};
837 int foo (struct mumble *x)
841 This code really is erroneous, because the scope of @code{struct
842 mumble} in the prototype is limited to the argument list containing it.
843 It does not refer to the @code{struct mumble} defined with file scope
844 immediately below---they are two unrelated types with similar names in
847 But in the definition of @code{foo}, the file-scope type is used
848 because that is available to be inherited. Thus, the definition and
849 the prototype do not match, and you get an error.
851 This behavior may seem silly, but it's what the ISO standard specifies.
852 It is easy enough for you to make your code work by moving the
853 definition of @code{struct mumble} above the prototype. It's not worth
854 being incompatible with ISO C just to avoid an error for the example
858 Accesses to bit-fields even in volatile objects works by accessing larger
859 objects, such as a byte or a word. You cannot rely on what size of
860 object is accessed in order to read or write the bit-field; it may even
861 vary for a given bit-field according to the precise usage.
863 If you care about controlling the amount of memory that is accessed, use
864 volatile but do not use bit-fields.
867 GCC comes with shell scripts to fix certain known problems in system
868 header files. They install corrected copies of various header files in
869 a special directory where only GCC will normally look for them. The
870 scripts adapt to various systems by searching all the system header
871 files for the problem cases that we know about.
873 If new system header files are installed, nothing automatically arranges
874 to update the corrected header files. You will have to reinstall GCC
875 to fix the new header files. More specifically, go to the build
876 directory and delete the files @file{stmp-fixinc} and
877 @file{stmp-headers}, and the subdirectory @code{include}; then do
878 @samp{make install} again.
881 @cindex floating point precision
882 On 68000 and x86 systems, for instance, you can get paradoxical results
883 if you test the precise values of floating point numbers. For example,
884 you can find that a floating point value which is not a NaN is not equal
885 to itself. This results from the fact that the floating point registers
886 hold a few more bits of precision than fit in a @code{double} in memory.
887 Compiled code moves values between memory and floating point registers
888 at its convenience, and moving them into memory truncates them.
890 @opindex ffloat-store
891 You can partially avoid this problem by using the @option{-ffloat-store}
892 option (@pxref{Optimize Options}).
895 On AIX and other platforms without weak symbol support, templates
896 need to be instantiated explicitly and symbols for static members
897 of templates will not be generated.
900 @node C++ Misunderstandings
901 @section Common Misunderstandings with GNU C++
903 @cindex misunderstandings in C++
904 @cindex surprises in C++
905 @cindex C++ misunderstandings
906 C++ is a complex language and an evolving one, and its standard
907 definition (the ISO C++ standard) was only recently completed. As a
908 result, your C++ compiler may occasionally surprise you, even when its
909 behavior is correct. This section discusses some areas that frequently
910 give rise to questions of this sort.
913 * Static Definitions:: Static member declarations are not definitions
914 * Temporaries:: Temporaries may vanish before you expect
915 * Copy Assignment:: Copy Assignment operators copy virtual bases twice
918 @node Static Definitions
919 @subsection Declare @emph{and} Define Static Members
921 @cindex C++ static data, declaring and defining
922 @cindex static data in C++, declaring and defining
923 @cindex declaring static data in C++
924 @cindex defining static data in C++
925 When a class has static data members, it is not enough to @emph{declare}
926 the static member; you must also @emph{define} it. For example:
937 This declaration only establishes that the class @code{Foo} has an
938 @code{int} named @code{Foo::bar}, and a member function named
939 @code{Foo::method}. But you still need to define @emph{both}
940 @code{method} and @code{bar} elsewhere. According to the ISO
941 standard, you must supply an initializer in one (and only one) source
948 Other C++ compilers may not correctly implement the standard behavior.
949 As a result, when you switch to @code{g++} from one of these compilers,
950 you may discover that a program that appeared to work correctly in fact
951 does not conform to the standard: @code{g++} reports as undefined
952 symbols any static data members that lack definitions.
955 @subsection Temporaries May Vanish Before You Expect
957 @cindex temporaries, lifetime of
958 @cindex portions of temporary objects, pointers to
959 It is dangerous to use pointers or references to @emph{portions} of a
960 temporary object. The compiler may very well delete the object before
961 you expect it to, leaving a pointer to garbage. The most common place
962 where this problem crops up is in classes like string classes,
963 especially ones that define a conversion function to type @code{char *}
964 or @code{const char *}---which is one reason why the standard
965 @code{string} class requires you to call the @code{c_str} member
966 function. However, any class that returns a pointer to some internal
967 structure is potentially subject to this problem.
969 For example, a program may use a function @code{strfunc} that returns
970 @code{string} objects, and another function @code{charfunc} that
971 operates on pointers to @code{char}:
975 void charfunc (const char *);
980 const char *p = strfunc().c_str();
989 In this situation, it may seem reasonable to save a pointer to the C
990 string returned by the @code{c_str} member function and use that rather
991 than call @code{c_str} repeatedly. However, the temporary string
992 created by the call to @code{strfunc} is destroyed after @code{p} is
993 initialized, at which point @code{p} is left pointing to freed memory.
995 Code like this may run successfully under some other compilers,
996 particularly obsolete cfront-based compilers that delete temporaries
997 along with normal local variables. However, the GNU C++ behavior is
998 standard-conforming, so if your program depends on late destruction of
999 temporaries it is not portable.
1001 The safe way to write such code is to give the temporary a name, which
1002 forces it to remain until the end of the scope of the name. For
1006 string& tmp = strfunc ();
1007 charfunc (tmp.c_str ());
1010 @node Copy Assignment
1011 @subsection Implicit Copy-Assignment for Virtual Bases
1013 When a base class is virtual, only one subobject of the base class
1014 belongs to each full object. Also, the constructors and destructors are
1015 invoked only once, and called from the most-derived class. However, such
1016 objects behave unspecified when being assigned. For example:
1021 Base(char *n) : name(strdup(n))@{@}
1022 Base& operator= (const Base& other)@{
1024 name = strdup (other.name);
1028 struct A:virtual Base@{
1033 struct B:virtual Base@{
1038 struct Derived:public A, public B@{
1039 Derived():Base("Derived")@{@}
1042 void func(Derived &d1, Derived &d2)
1048 The C++ standard specifies that @samp{Base::Base} is only called once
1049 when constructing or copy-constructing a Derived object. It is
1050 unspecified whether @samp{Base::operator=} is called more than once when
1051 the implicit copy-assignment for Derived objects is invoked (as it is
1052 inside @samp{func} in the example).
1054 g++ implements the ``intuitive'' algorithm for copy-assignment: assign all
1055 direct bases, then assign all members. In that algorithm, the virtual
1056 base subobject can be encountered many times. In the example, copying
1057 proceeds in the following order: @samp{val}, @samp{name} (via
1058 @code{strdup}), @samp{bval}, and @samp{name} again.
1060 If application code relies on copy-assignment, a user-defined
1061 copy-assignment operator removes any uncertainties. With such an
1062 operator, the application can define whether and how the virtual base
1063 subobject is assigned.
1065 @node Protoize Caveats
1066 @section Caveats of using @command{protoize}
1068 The conversion programs @command{protoize} and @command{unprotoize} can
1069 sometimes change a source file in a way that won't work unless you
1074 @command{protoize} can insert references to a type name or type tag before
1075 the definition, or in a file where they are not defined.
1077 If this happens, compiler error messages should show you where the new
1078 references are, so fixing the file by hand is straightforward.
1081 There are some C constructs which @command{protoize} cannot figure out.
1082 For example, it can't determine argument types for declaring a
1083 pointer-to-function variable; this you must do by hand. @command{protoize}
1084 inserts a comment containing @samp{???} each time it finds such a
1085 variable; so you can find all such variables by searching for this
1086 string. ISO C does not require declaring the argument types of
1087 pointer-to-function types.
1090 Using @command{unprotoize} can easily introduce bugs. If the program
1091 relied on prototypes to bring about conversion of arguments, these
1092 conversions will not take place in the program without prototypes.
1093 One case in which you can be sure @command{unprotoize} is safe is when
1094 you are removing prototypes that were made with @command{protoize}; if
1095 the program worked before without any prototypes, it will work again
1098 @opindex Wconversion
1099 You can find all the places where this problem might occur by compiling
1100 the program with the @option{-Wconversion} option. It prints a warning
1101 whenever an argument is converted.
1104 Both conversion programs can be confused if there are macro calls in and
1105 around the text to be converted. In other words, the standard syntax
1106 for a declaration or definition must not result from expanding a macro.
1107 This problem is inherent in the design of C and cannot be fixed. If
1108 only a few functions have confusing macro calls, you can easily convert
1112 @command{protoize} cannot get the argument types for a function whose
1113 definition was not actually compiled due to preprocessing conditionals.
1114 When this happens, @command{protoize} changes nothing in regard to such
1115 a function. @command{protoize} tries to detect such instances and warn
1118 You can generally work around this problem by using @command{protoize} step
1119 by step, each time specifying a different set of @option{-D} options for
1120 compilation, until all of the functions have been converted. There is
1121 no automatic way to verify that you have got them all, however.
1124 Confusion may result if there is an occasion to convert a function
1125 declaration or definition in a region of source code where there is more
1126 than one formal parameter list present. Thus, attempts to convert code
1127 containing multiple (conditionally compiled) versions of a single
1128 function header (in the same vicinity) may not produce the desired (or
1131 If you plan on converting source files which contain such code, it is
1132 recommended that you first make sure that each conditionally compiled
1133 region of source code which contains an alternative function header also
1134 contains at least one additional follower token (past the final right
1135 parenthesis of the function header). This should circumvent the
1139 @command{unprotoize} can become confused when trying to convert a function
1140 definition or declaration which contains a declaration for a
1141 pointer-to-function formal argument which has the same name as the
1142 function being defined or declared. We recommend you avoid such choices
1143 of formal parameter names.
1146 You might also want to correct some of the indentation by hand and break
1147 long lines. (The conversion programs don't write lines longer than
1148 eighty characters in any case.)
1152 @section Certain Changes We Don't Want to Make
1154 This section lists changes that people frequently request, but which
1155 we do not make because we think GCC is better without them.
1159 Checking the number and type of arguments to a function which has an
1160 old-fashioned definition and no prototype.
1162 Such a feature would work only occasionally---only for calls that appear
1163 in the same file as the called function, following the definition. The
1164 only way to check all calls reliably is to add a prototype for the
1165 function. But adding a prototype eliminates the motivation for this
1166 feature. So the feature is not worthwhile.
1169 Warning about using an expression whose type is signed as a shift count.
1171 Shift count operands are probably signed more often than unsigned.
1172 Warning about this would cause far more annoyance than good.
1175 Warning about assigning a signed value to an unsigned variable.
1177 Such assignments must be very common; warning about them would cause
1178 more annoyance than good.
1181 Warning when a non-void function value is ignored.
1183 Coming as I do from a Lisp background, I balk at the idea that there is
1184 something dangerous about discarding a value. There are functions that
1185 return values which some callers may find useful; it makes no sense to
1186 clutter the program with a cast to @code{void} whenever the value isn't
1190 @opindex fshort-enums
1191 Making @option{-fshort-enums} the default.
1193 This would cause storage layout to be incompatible with most other C
1194 compilers. And it doesn't seem very important, given that you can get
1195 the same result in other ways. The case where it matters most is when
1196 the enumeration-valued object is inside a structure, and in that case
1197 you can specify a field width explicitly.
1200 Making bit-fields unsigned by default on particular machines where ``the
1201 ABI standard'' says to do so.
1203 The ISO C standard leaves it up to the implementation whether a bit-field
1204 declared plain @code{int} is signed or not. This in effect creates two
1205 alternative dialects of C@.
1207 @opindex fsigned-bitfields
1208 @opindex funsigned-bitfields
1209 The GNU C compiler supports both dialects; you can specify the signed
1210 dialect with @option{-fsigned-bitfields} and the unsigned dialect with
1211 @option{-funsigned-bitfields}. However, this leaves open the question of
1212 which dialect to use by default.
1214 Currently, the preferred dialect makes plain bit-fields signed, because
1215 this is simplest. Since @code{int} is the same as @code{signed int} in
1216 every other context, it is cleanest for them to be the same in bit-fields
1219 Some computer manufacturers have published Application Binary Interface
1220 standards which specify that plain bit-fields should be unsigned. It is
1221 a mistake, however, to say anything about this issue in an ABI@. This is
1222 because the handling of plain bit-fields distinguishes two dialects of C@.
1223 Both dialects are meaningful on every type of machine. Whether a
1224 particular object file was compiled using signed bit-fields or unsigned
1225 is of no concern to other object files, even if they access the same
1226 bit-fields in the same data structures.
1228 A given program is written in one or the other of these two dialects.
1229 The program stands a chance to work on most any machine if it is
1230 compiled with the proper dialect. It is unlikely to work at all if
1231 compiled with the wrong dialect.
1233 Many users appreciate the GNU C compiler because it provides an
1234 environment that is uniform across machines. These users would be
1235 inconvenienced if the compiler treated plain bit-fields differently on
1238 Occasionally users write programs intended only for a particular machine
1239 type. On these occasions, the users would benefit if the GNU C compiler
1240 were to support by default the same dialect as the other compilers on
1241 that machine. But such applications are rare. And users writing a
1242 program to run on more than one type of machine cannot possibly benefit
1243 from this kind of compatibility.
1245 This is why GCC does and will treat plain bit-fields in the same
1246 fashion on all types of machines (by default).
1248 There are some arguments for making bit-fields unsigned by default on all
1249 machines. If, for example, this becomes a universal de facto standard,
1250 it would make sense for GCC to go along with it. This is something
1251 to be considered in the future.
1253 (Of course, users strongly concerned about portability should indicate
1254 explicitly in each bit-field whether it is signed or not. In this way,
1255 they write programs which have the same meaning in both C dialects.)
1260 Undefining @code{__STDC__} when @option{-ansi} is not used.
1262 Currently, GCC defines @code{__STDC__} unconditionally. This provides
1263 good results in practice.
1265 Programmers normally use conditionals on @code{__STDC__} to ask whether
1266 it is safe to use certain features of ISO C, such as function
1267 prototypes or ISO token concatenation. Since plain @command{gcc} supports
1268 all the features of ISO C, the correct answer to these questions is
1271 Some users try to use @code{__STDC__} to check for the availability of
1272 certain library facilities. This is actually incorrect usage in an ISO
1273 C program, because the ISO C standard says that a conforming
1274 freestanding implementation should define @code{__STDC__} even though it
1275 does not have the library facilities. @samp{gcc -ansi -pedantic} is a
1276 conforming freestanding implementation, and it is therefore required to
1277 define @code{__STDC__}, even though it does not come with an ISO C
1280 Sometimes people say that defining @code{__STDC__} in a compiler that
1281 does not completely conform to the ISO C standard somehow violates the
1282 standard. This is illogical. The standard is a standard for compilers
1283 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
1284 compilers such as plain @command{gcc}. Whatever the ISO C standard says
1285 is relevant to the design of plain @command{gcc} without @option{-ansi} only
1286 for pragmatic reasons, not as a requirement.
1288 GCC normally defines @code{__STDC__} to be 1, and in addition
1289 defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
1290 or a @option{-std} option for strict conformance to some version of ISO C@.
1291 On some hosts, system include files use a different convention, where
1292 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
1293 conformance to the C Standard. GCC follows the host convention when
1294 processing system include files, but when processing user files it follows
1295 the usual GNU C convention.
1298 Undefining @code{__STDC__} in C++.
1300 Programs written to compile with C++-to-C translators get the
1301 value of @code{__STDC__} that goes with the C compiler that is
1302 subsequently used. These programs must test @code{__STDC__}
1303 to determine what kind of C preprocessor that compiler uses:
1304 whether they should concatenate tokens in the ISO C fashion
1305 or in the traditional fashion.
1307 These programs work properly with GNU C++ if @code{__STDC__} is defined.
1308 They would not work otherwise.
1310 In addition, many header files are written to provide prototypes in ISO
1311 C but not in traditional C@. Many of these header files can work without
1312 change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
1313 is not defined, they will all fail, and will all need to be changed to
1314 test explicitly for C++ as well.
1317 Deleting ``empty'' loops.
1319 Historically, GCC has not deleted ``empty'' loops under the
1320 assumption that the most likely reason you would put one in a program is
1321 to have a delay, so deleting them will not make real programs run any
1324 However, the rationale here is that optimization of a nonempty loop
1325 cannot produce an empty one, which holds for C but is not always the
1328 @opindex funroll-loops
1329 Moreover, with @option{-funroll-loops} small ``empty'' loops are already
1330 removed, so the current behavior is both sub-optimal and inconsistent
1331 and will change in the future.
1334 Making side effects happen in the same order as in some other compiler.
1336 @cindex side effects, order of evaluation
1337 @cindex order of evaluation, side effects
1338 It is never safe to depend on the order of evaluation of side effects.
1339 For example, a function call like this may very well behave differently
1340 from one compiler to another:
1343 void func (int, int);
1349 There is no guarantee (in either the C or the C++ standard language
1350 definitions) that the increments will be evaluated in any particular
1351 order. Either increment might happen first. @code{func} might get the
1352 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
1355 Not allowing structures with volatile fields in registers.
1357 Strictly speaking, there is no prohibition in the ISO C standard
1358 against allowing structures with volatile fields in registers, but
1359 it does not seem to make any sense and is probably not what you wanted
1360 to do. So the compiler will give an error message in this case.
1363 Making certain warnings into errors by default.
1365 Some ISO C testsuites report failure when the compiler does not produce
1366 an error message for a certain program.
1368 @opindex pedantic-errors
1369 ISO C requires a ``diagnostic'' message for certain kinds of invalid
1370 programs, but a warning is defined by GCC to count as a diagnostic. If
1371 GCC produces a warning but not an error, that is correct ISO C support.
1372 If test suites call this ``failure'', they should be run with the GCC
1373 option @option{-pedantic-errors}, which will turn these warnings into
1378 @node Warnings and Errors
1379 @section Warning Messages and Error Messages
1381 @cindex error messages
1382 @cindex warnings vs errors
1383 @cindex messages, warning and error
1384 The GNU compiler can produce two kinds of diagnostics: errors and
1385 warnings. Each kind has a different purpose:
1389 @dfn{Errors} report problems that make it impossible to compile your
1390 program. GCC reports errors with the source file name and line
1391 number where the problem is apparent.
1394 @dfn{Warnings} report other unusual conditions in your code that
1395 @emph{may} indicate a problem, although compilation can (and does)
1396 proceed. Warning messages also report the source file name and line
1397 number, but include the text @samp{warning:} to distinguish them
1398 from error messages.
1401 Warnings may indicate danger points where you should check to make sure
1402 that your program really does what you intend; or the use of obsolete
1403 features; or the use of nonstandard features of GNU C or C++. Many
1404 warnings are issued only if you ask for them, with one of the @option{-W}
1405 options (for instance, @option{-Wall} requests a variety of useful
1409 @opindex pedantic-errors
1410 GCC always tries to compile your program if possible; it never
1411 gratuitously rejects a program whose meaning is clear merely because
1412 (for instance) it fails to conform to a standard. In some cases,
1413 however, the C and C++ standards specify that certain extensions are
1414 forbidden, and a diagnostic @emph{must} be issued by a conforming
1415 compiler. The @option{-pedantic} option tells GCC to issue warnings in
1416 such cases; @option{-pedantic-errors} says to make them errors instead.
1417 This does not mean that @emph{all} non-ISO constructs get warnings
1420 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
1421 more detail on these and related command-line options.