1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
2 @c 1999, 2000, 2001, 2003, 2004 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 On many platforms, GCC supports a different ABI for C++ than do other
109 compilers, so the object files compiled by GCC cannot be used with object
110 files generated by another C++ compiler.
112 An area where the difference is most apparent is name mangling. The use
113 of different name mangling is intentional, to protect you from more subtle
115 Compilers differ as to many internal details of C++ implementation,
116 including: how class instances are laid out, how multiple inheritance is
117 implemented, and how virtual function calls are handled. If the name
118 encoding were made the same, your programs would link against libraries
119 provided from other compilers---but the programs would then crash when
120 run. Incompatible libraries are then detected at link time, rather than
124 Older GDB versions sometimes fail to read the output of GCC version
125 2. If you have trouble, get GDB version 4.4 or later.
129 DBX rejects some files produced by GCC, though it accepts similar
130 constructs in output from PCC@. Until someone can supply a coherent
131 description of what is valid DBX input and what is not, there is
132 nothing that can be done about these problems.
135 The GNU assembler (GAS) does not support PIC@. To generate PIC code, you
136 must use some other assembler, such as @file{/bin/as}.
139 On some BSD systems, including some versions of Ultrix, use of profiling
140 causes static variable destructors (currently used only in C++) not to
144 @cindex @code{vfork}, for the Sun-4
146 There is a bug in @code{vfork} on the Sun-4 which causes the registers
147 of the child process to clobber those of the parent. Because of this,
148 programs that call @code{vfork} are likely to lose when compiled
149 optimized with GCC when the child code alters registers which contain
150 C variables in the parent. This affects variables which are live in the
151 parent across the call to @code{vfork}.
153 If you encounter this, you can work around the problem by declaring
154 variables @code{volatile} in the function that calls @code{vfork}, until
155 the problem goes away, or by not declaring them @code{register} and not
156 using @option{-O} for those source files.
160 On some SGI systems, when you use @option{-lgl_s} as an option,
161 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
162 Naturally, this does not happen when you use GCC@.
163 You must specify all three options explicitly.
166 On a SPARC, GCC aligns all values of type @code{double} on an 8-byte
167 boundary, and it expects every @code{double} to be so aligned. The Sun
168 compiler usually gives @code{double} values 8-byte alignment, with one
169 exception: function arguments of type @code{double} may not be aligned.
171 As a result, if a function compiled with Sun CC takes the address of an
172 argument of type @code{double} and passes this pointer of type
173 @code{double *} to a function compiled with GCC, dereferencing the
174 pointer may cause a fatal signal.
176 One way to solve this problem is to compile your entire program with GCC@.
177 Another solution is to modify the function that is compiled with
178 Sun CC to copy the argument into a local variable; local variables
179 are always properly aligned. A third solution is to modify the function
180 that uses the pointer to dereference it via the following function
181 @code{access_double} instead of directly with @samp{*}:
185 access_double (double *unaligned_ptr)
187 union d2i @{ double d; int i[2]; @};
189 union d2i *p = (union d2i *) unaligned_ptr;
200 Storing into the pointer can be done likewise with the same union.
203 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
204 may allocate memory that is only 4 byte aligned. Since GCC on the
205 SPARC assumes that doubles are 8 byte aligned, this may result in a
206 fatal signal if doubles are stored in memory allocated by the
207 @file{libmalloc.a} library.
209 The solution is to not use the @file{libmalloc.a} library. Use instead
210 @code{malloc} and related functions from @file{libc.a}; they do not have
214 Sun forgot to include a static version of @file{libdl.a} with some
215 versions of SunOS (mainly 4.1). This results in undefined symbols when
216 linking static binaries (that is, if you use @option{-static}). If you
217 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
218 when linking, compile and link against the file
219 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
222 The 128-bit long double format that the SPARC port supports currently
223 works by using the architecturally defined quad-word floating point
224 instructions. Since there is no hardware that supports these
225 instructions they must be emulated by the operating system. Long
226 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
227 kernel emulator uses an obsolete and incompatible format. Long doubles
228 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
229 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
230 does not enable them by default. Long doubles appear to work in Sun OS
234 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
235 compile GCC correctly. We do not yet know why. However, GCC
236 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
237 compile itself properly on 9.01.
240 On the HP PA machine, ADB sometimes fails to work on functions compiled
241 with GCC@. Specifically, it fails to work on functions that use
242 @code{alloca} or variable-size arrays. This is because GCC doesn't
243 generate HP-UX unwind descriptors for such functions. It may even be
244 impossible to generate them.
247 Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
248 the preliminary GNU tools.
251 Taking the address of a label may generate errors from the HP-UX
252 PA assembler. GAS for the PA does not have this problem.
255 Using floating point parameters for indirect calls to static functions
256 will not work when using the HP assembler. There simply is no way for GCC
257 to specify what registers hold arguments for static functions when using
258 the HP assembler. GAS for the PA does not have this problem.
261 In extremely rare cases involving some very large functions you may
262 receive errors from the HP linker complaining about an out of bounds
263 unconditional branch offset. This used to occur more often in previous
264 versions of GCC, but is now exceptionally rare. If you should run
265 into it, you can work around by making your function smaller.
268 GCC compiled code sometimes emits warnings from the HP-UX assembler of
272 (warning) Use of GR3 when
273 frame >= 8192 may cause conflict.
276 These warnings are harmless and can be safely ignored.
279 On the IBM RS/6000, compiling code of the form
290 will cause the linker to report an undefined symbol @code{foo}.
291 Although this behavior differs from most other systems, it is not a
292 bug because redefining an @code{extern} variable as @code{static}
293 is undefined in ISO C@.
296 In extremely rare cases involving some very large functions you may
297 receive errors from the AIX Assembler complaining about a displacement
298 that is too large. If you should run into it, you can work around by
299 making your function smaller.
302 The @file{libstdc++.a} library in GCC relies on the SVR4 dynamic
303 linker semantics which merges global symbols between libraries and
304 applications, especially necessary for C++ streams functionality.
305 This is not the default behavior of AIX shared libraries and dynamic
306 linking. @file{libstdc++.a} is built on AIX with ``runtime-linking''
307 enabled so that symbol merging can occur. To utilize this feature,
308 the application linked with @file{libstdc++.a} must include the
309 @option{-Wl,-brtl} flag on the link line. G++ cannot impose this
310 because this option may interfere with the semantics of the user
311 program and users may not always use @samp{g++} to link his or her
312 application. Applications are not required to use the
313 @option{-Wl,-brtl} flag on the link line---the rest of the
314 @file{libstdc++.a} library which is not dependent on the symbol
315 merging semantics will continue to function correctly.
318 An application can interpose its own definition of functions for
319 functions invoked by @file{libstdc++.a} with ``runtime-linking''
320 enabled on AIX. To accomplish this the application must be linked
321 with ``runtime-linking'' option and the functions explicitly must be
322 exported by the application (@option{-Wl,-brtl,-bE:exportfile}).
325 AIX on the RS/6000 provides support (NLS) for environments outside of
326 the United States. Compilers and assemblers use NLS to support
327 locale-specific representations of various objects including
328 floating-point numbers (@samp{.} vs @samp{,} for separating decimal
329 fractions). There have been problems reported where the library linked
330 with GCC does not produce the same floating-point formats that the
331 assembler accepts. If you have this problem, set the @env{LANG}
332 environment variable to @samp{C} or @samp{En_US}.
335 @opindex fdollars-in-identifiers
336 Even if you specify @option{-fdollars-in-identifiers},
337 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
338 to a restriction in the IBM assembler. GAS supports these
341 @cindex VAX calling convention
342 @cindex Ultrix calling convention
345 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
346 by function calls. However, the C compiler uses conventions compatible
347 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
349 GCC uses the same convention as the Ultrix C compiler. You can use
350 these options to produce code compatible with the Fortran compiler:
353 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
357 On the Alpha, you may get assembler errors about invalid syntax as a
358 result of floating point constants. This is due to a bug in the C
359 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}. Given valid
360 floating point numbers, they sometimes print @samp{NaN}.
364 @section Problems Compiling Certain Programs
366 @c prevent bad page break with this line
367 Certain programs have problems compiling.
371 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
372 because of problems in DEC's versions of the X11 header files
373 @file{X11/Xlib.h} and @file{X11/Xutil.h}. People recommend adding
374 @option{-I/usr/include/mit} to use the MIT versions of the header files,
375 or fixing the header files by adding this:
379 #define NeedFunctionPrototypes 0
384 On various 386 Unix systems derived from System V, including SCO, ISC,
385 and ESIX, you may get error messages about running out of virtual memory
386 while compiling certain programs.
388 You can prevent this problem by linking GCC with the GNU malloc
389 (which thus replaces the malloc that comes with the system). GNU malloc
390 is available as a separate package, and also in the file
391 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
393 If you have installed GNU malloc as a separate library package, use this
394 option when you relink GCC:
397 MALLOC=/usr/local/lib/libgmalloc.a
400 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
401 the object file to @file{gmalloc.o} and use this option when you relink
409 @node Incompatibilities
410 @section Incompatibilities of GCC
411 @cindex incompatibilities of GCC
414 There are several noteworthy incompatibilities between GNU C and K&R
415 (non-ISO) versions of C@.
418 @cindex string constants
419 @cindex read-only strings
420 @cindex shared strings
422 GCC normally makes string constants read-only. If several
423 identical-looking string constants are used, GCC stores only one
426 @cindex @code{mktemp}, and constant strings
427 One consequence is that you cannot call @code{mktemp} with a string
428 constant argument. The function @code{mktemp} always alters the
429 string its argument points to.
431 @cindex @code{sscanf}, and constant strings
432 @cindex @code{fscanf}, and constant strings
433 @cindex @code{scanf}, and constant strings
434 Another consequence is that @code{sscanf} does not work on some systems
435 when passed a string constant as its format control string or input.
436 This is because @code{sscanf} incorrectly tries to write into the string
437 constant. Likewise @code{fscanf} and @code{scanf}.
439 @opindex fwritable-strings
440 The best solution to these problems is to change the program to use
441 @code{char}-array variables with initialization strings for these
442 purposes instead of string constants. But if this is not possible,
443 you can use the @option{-fwritable-strings} flag, which directs GCC
444 to handle string constants the same way most C compilers do.
447 @code{-2147483648} is positive.
449 This is because 2147483648 cannot fit in the type @code{int}, so
450 (following the ISO C rules) its data type is @code{unsigned long int}.
451 Negating this value yields 2147483648 again.
454 GCC does not substitute macro arguments when they appear inside of
455 string constants. For example, the following macro in GCC
462 will produce output @code{"a"} regardless of what the argument @var{a} is.
464 @cindex @code{setjmp} incompatibilities
465 @cindex @code{longjmp} incompatibilities
467 When you use @code{setjmp} and @code{longjmp}, the only automatic
468 variables guaranteed to remain valid are those declared
469 @code{volatile}. This is a consequence of automatic register
470 allocation. Consider this function:
484 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
489 Here @code{a} may or may not be restored to its first value when the
490 @code{longjmp} occurs. If @code{a} is allocated in a register, then
491 its first value is restored; otherwise, it keeps the last value stored
495 If you use the @option{-W} option with the @option{-O} option, you will
496 get a warning when GCC thinks such a problem might be possible.
499 Programs that use preprocessing directives in the middle of macro
500 arguments do not work with GCC@. For example, a program like this
511 ISO C does not permit such a construct.
514 K&R compilers allow comments to cross over an inclusion boundary
515 (i.e.@: started in an include file and ended in the including file).
517 @cindex external declaration scope
518 @cindex scope of external declarations
519 @cindex declaration scope
521 Declarations of external variables and functions within a block apply
522 only to the block containing the declaration. In other words, they
523 have the same scope as any other declaration in the same place.
525 In some other C compilers, a @code{extern} declaration affects all the
526 rest of the file even if it happens within a block.
529 In traditional C, you can combine @code{long}, etc., with a typedef name,
534 typedef long foo bar;
537 In ISO C, this is not allowed: @code{long} and other type modifiers
538 require an explicit @code{int}.
540 @cindex typedef names as function parameters
542 PCC allows typedef names to be used as function parameters.
545 Traditional C allows the following erroneous pair of declarations to
546 appear together in a given scope:
554 GCC treats all characters of identifiers as significant. According to
555 K&R-1 (2.2), ``No more than the first eight characters are significant,
556 although more may be used.''. Also according to K&R-1 (2.2), ``An
557 identifier is a sequence of letters and digits; the first character must
558 be a letter. The underscore _ counts as a letter.'', but GCC also
559 allows dollar signs in identifiers.
563 PCC allows whitespace in the middle of compound assignment operators
564 such as @samp{+=}. GCC, following the ISO standard, does not
570 GCC complains about unterminated character constants inside of
571 preprocessing conditionals that fail. Some programs have English
572 comments enclosed in conditionals that are guaranteed to fail; if these
573 comments contain apostrophes, GCC will probably report an error. For
574 example, this code would produce an error:
578 You can't expect this to work.
582 The best solution to such a problem is to put the text into an actual
583 C comment delimited by @samp{/*@dots{}*/}.
586 Many user programs contain the declaration @samp{long time ();}. In the
587 past, the system header files on many systems did not actually declare
588 @code{time}, so it did not matter what type your program declared it to
589 return. But in systems with ISO C headers, @code{time} is declared to
590 return @code{time_t}, and if that is not the same as @code{long}, then
591 @samp{long time ();} is erroneous.
593 The solution is to change your program to use appropriate system headers
594 (@code{<time.h>} on systems with ISO C headers) and not to declare
595 @code{time} if the system header files declare it, or failing that to
596 use @code{time_t} as the return type of @code{time}.
598 @cindex @code{float} as function value type
600 When compiling functions that return @code{float}, PCC converts it to
601 a double. GCC actually returns a @code{float}. If you are concerned
602 with PCC compatibility, you should declare your functions to return
603 @code{double}; you might as well say what you mean.
608 When compiling functions that return structures or unions, GCC
609 output code normally uses a method different from that used on most
610 versions of Unix. As a result, code compiled with GCC cannot call
611 a structure-returning function compiled with PCC, and vice versa.
613 The method used by GCC is as follows: a structure or union which is
614 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union
615 with any other size is stored into an address supplied by the caller
616 (usually in a special, fixed register, but on some machines it is passed
617 on the stack). The target hook @code{TARGET_STRUCT_VALUE_RTX}
618 tells GCC where to pass this address.
620 By contrast, PCC on most target machines returns structures and unions
621 of any size by copying the data into an area of static storage, and then
622 returning the address of that storage as if it were a pointer value.
623 The caller must copy the data from that memory area to the place where
624 the value is wanted. GCC does not use this method because it is
625 slower and nonreentrant.
627 On some newer machines, PCC uses a reentrant convention for all
628 structure and union returning. GCC on most of these machines uses a
629 compatible convention when returning structures and unions in memory,
630 but still returns small structures and unions in registers.
632 @opindex fpcc-struct-return
633 You can tell GCC to use a compatible convention for all structure and
634 union returning with the option @option{-fpcc-struct-return}.
636 @cindex preprocessing tokens
637 @cindex preprocessing numbers
639 GCC complains about program fragments such as @samp{0x74ae-0x4000}
640 which appear to be two hexadecimal constants separated by the minus
641 operator. Actually, this string is a single @dfn{preprocessing token}.
642 Each such token must correspond to one token in C@. Since this does not,
643 GCC prints an error message. Although it may appear obvious that what
644 is meant is an operator and two values, the ISO C standard specifically
645 requires that this be treated as erroneous.
647 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
648 begins with a digit and is followed by letters, underscores, digits,
649 periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
650 @samp{p-}, @samp{P+}, or @samp{P-} character sequences. (In strict C89
651 mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
652 appear in preprocessing numbers.)
654 To make the above program fragment valid, place whitespace in front of
655 the minus sign. This whitespace will end the preprocessing number.
659 @section Fixed Header Files
661 GCC needs to install corrected versions of some system header files.
662 This is because most target systems have some header files that won't
663 work with GCC unless they are changed. Some have bugs, some are
664 incompatible with ISO C, and some depend on special features of other
667 Installing GCC automatically creates and installs the fixed header
668 files, by running a program called @code{fixincludes} (or for certain
669 targets an alternative such as @code{fixinc.svr4}). Normally, you
670 don't need to pay attention to this. But there are cases where it
671 doesn't do the right thing automatically.
675 If you update the system's header files, such as by installing a new
676 system version, the fixed header files of GCC are not automatically
677 updated. The easiest way to update them is to reinstall GCC@. (If
678 you want to be clever, look in the makefile and you can find a
682 On some systems, in particular SunOS 4, header file directories contain
683 machine-specific symbolic links in certain places. This makes it
684 possible to share most of the header files among hosts running the
685 same version of SunOS 4 on different machine models.
687 The programs that fix the header files do not understand this special
688 way of using symbolic links; therefore, the directory of fixed header
689 files is good only for the machine model used to build it.
691 In SunOS 4, only programs that look inside the kernel will notice the
692 difference between machine models. Therefore, for most purposes, you
693 need not be concerned about this.
695 It is possible to make separate sets of fixed header files for the
696 different machine models, and arrange a structure of symbolic links so
697 as to use the proper set, but you'll have to do this by hand.
700 On Lynxos, GCC by default does not fix the header files. This is
701 because bugs in the shell cause the @code{fixincludes} script to fail.
703 This means you will encounter problems due to bugs in the system header
704 files. It may be no comfort that they aren't GCC's fault, but it
705 does mean that there's nothing for us to do about them.
708 @node Standard Libraries
709 @section Standard Libraries
712 GCC by itself attempts to be a conforming freestanding implementation.
713 @xref{Standards,,Language Standards Supported by GCC}, for details of
714 what this means. Beyond the library facilities required of such an
715 implementation, the rest of the C library is supplied by the vendor of
716 the operating system. If that C library doesn't conform to the C
717 standards, then your programs might get warnings (especially when using
718 @option{-Wall}) that you don't expect.
720 For example, the @code{sprintf} function on SunOS 4.1.3 returns
721 @code{char *} while the C standard says that @code{sprintf} returns an
722 @code{int}. The @code{fixincludes} program could make the prototype for
723 this function match the Standard, but that would be wrong, since the
724 function will still return @code{char *}.
726 If you need a Standard compliant library, then you need to find one, as
727 GCC does not provide one. The GNU C library (called @code{glibc})
728 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
729 GNU/Linux and HURD-based GNU systems; no recent version of it supports
730 other systems, though some very old versions did. Version 2.2 of the
731 GNU C library includes nearly complete C99 support. You could also ask
732 your operating system vendor if newer libraries are available.
734 @node Disappointments
735 @section Disappointments and Misunderstandings
737 These problems are perhaps regrettable, but we don't know any practical
742 Certain local variables aren't recognized by debuggers when you compile
745 This occurs because sometimes GCC optimizes the variable out of
746 existence. There is no way to tell the debugger how to compute the
747 value such a variable ``would have had'', and it is not clear that would
748 be desirable anyway. So GCC simply does not mention the eliminated
749 variable when it writes debugging information.
751 You have to expect a certain amount of disagreement between the
752 executable and your source code, when you use optimization.
754 @cindex conflicting types
755 @cindex scope of declaration
757 Users often think it is a bug when GCC reports an error for code
761 int foo (struct mumble *);
763 struct mumble @{ @dots{} @};
765 int foo (struct mumble *x)
769 This code really is erroneous, because the scope of @code{struct
770 mumble} in the prototype is limited to the argument list containing it.
771 It does not refer to the @code{struct mumble} defined with file scope
772 immediately below---they are two unrelated types with similar names in
775 But in the definition of @code{foo}, the file-scope type is used
776 because that is available to be inherited. Thus, the definition and
777 the prototype do not match, and you get an error.
779 This behavior may seem silly, but it's what the ISO standard specifies.
780 It is easy enough for you to make your code work by moving the
781 definition of @code{struct mumble} above the prototype. It's not worth
782 being incompatible with ISO C just to avoid an error for the example
786 Accesses to bit-fields even in volatile objects works by accessing larger
787 objects, such as a byte or a word. You cannot rely on what size of
788 object is accessed in order to read or write the bit-field; it may even
789 vary for a given bit-field according to the precise usage.
791 If you care about controlling the amount of memory that is accessed, use
792 volatile but do not use bit-fields.
795 GCC comes with shell scripts to fix certain known problems in system
796 header files. They install corrected copies of various header files in
797 a special directory where only GCC will normally look for them. The
798 scripts adapt to various systems by searching all the system header
799 files for the problem cases that we know about.
801 If new system header files are installed, nothing automatically arranges
802 to update the corrected header files. You will have to reinstall GCC
803 to fix the new header files. More specifically, go to the build
804 directory and delete the files @file{stmp-fixinc} and
805 @file{stmp-headers}, and the subdirectory @code{include}; then do
806 @samp{make install} again.
809 @cindex floating point precision
810 On 68000 and x86 systems, for instance, you can get paradoxical results
811 if you test the precise values of floating point numbers. For example,
812 you can find that a floating point value which is not a NaN is not equal
813 to itself. This results from the fact that the floating point registers
814 hold a few more bits of precision than fit in a @code{double} in memory.
815 Compiled code moves values between memory and floating point registers
816 at its convenience, and moving them into memory truncates them.
818 @opindex ffloat-store
819 You can partially avoid this problem by using the @option{-ffloat-store}
820 option (@pxref{Optimize Options}).
823 On AIX and other platforms without weak symbol support, templates
824 need to be instantiated explicitly and symbols for static members
825 of templates will not be generated.
828 On AIX, GCC scans object files and library archives for static
829 constructors and destructors when linking an application before the
830 linker prunes unreferenced symbols. This is necessary to prevent the
831 AIX linker from mistakenly assuming that static constructor or
832 destructor are unused and removing them before the scanning can occur.
833 All static constructors and destructors found will be referenced even
834 though the modules in which they occur may not be used by the program.
835 This may lead to both increased executable size and unexpected symbol
839 @node C++ Misunderstandings
840 @section Common Misunderstandings with GNU C++
842 @cindex misunderstandings in C++
843 @cindex surprises in C++
844 @cindex C++ misunderstandings
845 C++ is a complex language and an evolving one, and its standard
846 definition (the ISO C++ standard) was only recently completed. As a
847 result, your C++ compiler may occasionally surprise you, even when its
848 behavior is correct. This section discusses some areas that frequently
849 give rise to questions of this sort.
852 * Static Definitions:: Static member declarations are not definitions
853 * Name lookup:: Name lookup, templates, and accessing members of base classes
854 * Temporaries:: Temporaries may vanish before you expect
855 * Copy Assignment:: Copy Assignment operators copy virtual bases twice
858 @node Static Definitions
859 @subsection Declare @emph{and} Define Static Members
861 @cindex C++ static data, declaring and defining
862 @cindex static data in C++, declaring and defining
863 @cindex declaring static data in C++
864 @cindex defining static data in C++
865 When a class has static data members, it is not enough to @emph{declare}
866 the static member; you must also @emph{define} it. For example:
877 This declaration only establishes that the class @code{Foo} has an
878 @code{int} named @code{Foo::bar}, and a member function named
879 @code{Foo::method}. But you still need to define @emph{both}
880 @code{method} and @code{bar} elsewhere. According to the ISO
881 standard, you must supply an initializer in one (and only one) source
888 Other C++ compilers may not correctly implement the standard behavior.
889 As a result, when you switch to @command{g++} from one of these compilers,
890 you may discover that a program that appeared to work correctly in fact
891 does not conform to the standard: @command{g++} reports as undefined
892 symbols any static data members that lack definitions.
896 @subsection Name lookup, templates, and accessing members of base classes
898 @cindex base class members
899 @cindex two-stage name lookup
900 @cindex dependent name lookup
902 The C++ standard prescribes that all names that are not dependent on
903 template parameters are bound to their present definitions when parsing
904 a template function or class.@footnote{The C++ standard just uses the
905 term ``dependent'' for names that depend on the type or value of
906 template parameters. This shorter term will also be used in the rest of
907 this section.} Only names that are dependent are looked up at the point
908 of instantiation. For example, consider
914 template <typename T>
927 Here, the names @code{foo} and @code{N} appear in a context that does
928 not depend on the type of @code{T}. The compiler will thus require that
929 they are defined in the context of use in the template, not only before
930 the point of instantiation, and will here use @code{::foo(double)} and
931 @code{A::N}, respectively. In particular, it will convert the integer
932 value to a @code{double} when passing it to @code{::foo(double)}.
934 Conversely, @code{bar} and the call to @code{foo} in the fourth marked
935 line are used in contexts that do depend on the type of @code{T}, so
936 they are only looked up at the point of instantiation, and you can
937 provide declarations for them after declaring the template, but before
938 instantiating it. In particular, if you instantiate @code{A::f<int>},
939 the last line will call an overloaded @code{::foo(int)} if one was
940 provided, even if after the declaration of @code{struct A}.
942 This distinction between lookup of dependent and non-dependent names is
943 called two-stage (or dependent) name lookup. G++ implements it
946 Two-stage name lookup sometimes leads to situations with behavior
947 different from non-template codes. The most common is probably this:
950 template <typename T> struct Base @{
954 template <typename T> struct Derived : public Base<T> @{
955 int get_i() @{ return i; @}
959 In @code{get_i()}, @code{i} is not used in a dependent context, so the
960 compiler will look for a name declared at the enclosing namespace scope
961 (which is the global scope here). It will not look into the base class,
962 since that is dependent and you may declare specializations of
963 @code{Base} even after declaring @code{Derived}, so the compiler can't
964 really know what @code{i} would refer to. If there is no global
965 variable @code{i}, then you will get an error message.
967 In order to make it clear that you want the member of the base class,
968 you need to defer lookup until instantiation time, at which the base
969 class is known. For this, you need to access @code{i} in a dependent
970 context, by either using @code{this->i} (remember that @code{this} is of
971 type @code{Derived<T>*}, so is obviously dependent), or using
972 @code{Base<T>::i}. Alternatively, @code{Base<T>::i} might be brought
973 into scope by a @code{using}-declaration.
975 Another, similar example involves calling member functions of a base
979 template <typename T> struct Base @{
983 template <typename T> struct Derived : Base<T> @{
984 int g() @{ return f(); @};
988 Again, the call to @code{f()} is not dependent on template arguments
989 (there are no arguments that depend on the type @code{T}, and it is also
990 not otherwise specified that the call should be in a dependent context).
991 Thus a global declaration of such a function must be available, since
992 the one in the base class is not visible until instantiation time. The
993 compiler will consequently produce the following error message:
996 x.cc: In member function `int Derived<T>::g()':
997 x.cc:6: error: there are no arguments to `f' that depend on a template
998 parameter, so a declaration of `f' must be available
999 x.cc:6: error: (if you use `-fpermissive', G++ will accept your code, but
1000 allowing the use of an undeclared name is deprecated)
1003 To make the code valid either use @code{this->f()}, or
1004 @code{Base<T>::f()}. Using the @code{-fpermissive} flag will also let
1005 the compiler accept the code, by marking all function calls for which no
1006 declaration is visible at the time of definition of the template for
1007 later lookup at instantiation time, as if it were a dependent call.
1008 We do not recommend using @code{-fpermissive} to work around invalid
1009 code, and it will also only catch cases where functions in base classes
1010 are called, not where variables in base classes are used (as in the
1013 Note that some compilers (including G++ versions prior to 3.4) get these
1014 examples wrong and accept above code without an error. Those compilers
1015 do not implement two-stage name lookup correctly.
1019 @subsection Temporaries May Vanish Before You Expect
1021 @cindex temporaries, lifetime of
1022 @cindex portions of temporary objects, pointers to
1023 It is dangerous to use pointers or references to @emph{portions} of a
1024 temporary object. The compiler may very well delete the object before
1025 you expect it to, leaving a pointer to garbage. The most common place
1026 where this problem crops up is in classes like string classes,
1027 especially ones that define a conversion function to type @code{char *}
1028 or @code{const char *}---which is one reason why the standard
1029 @code{string} class requires you to call the @code{c_str} member
1030 function. However, any class that returns a pointer to some internal
1031 structure is potentially subject to this problem.
1033 For example, a program may use a function @code{strfunc} that returns
1034 @code{string} objects, and another function @code{charfunc} that
1035 operates on pointers to @code{char}:
1039 void charfunc (const char *);
1044 const char *p = strfunc().c_str();
1053 In this situation, it may seem reasonable to save a pointer to the C
1054 string returned by the @code{c_str} member function and use that rather
1055 than call @code{c_str} repeatedly. However, the temporary string
1056 created by the call to @code{strfunc} is destroyed after @code{p} is
1057 initialized, at which point @code{p} is left pointing to freed memory.
1059 Code like this may run successfully under some other compilers,
1060 particularly obsolete cfront-based compilers that delete temporaries
1061 along with normal local variables. However, the GNU C++ behavior is
1062 standard-conforming, so if your program depends on late destruction of
1063 temporaries it is not portable.
1065 The safe way to write such code is to give the temporary a name, which
1066 forces it to remain until the end of the scope of the name. For
1070 const string& tmp = strfunc ();
1071 charfunc (tmp.c_str ());
1074 @node Copy Assignment
1075 @subsection Implicit Copy-Assignment for Virtual Bases
1077 When a base class is virtual, only one subobject of the base class
1078 belongs to each full object. Also, the constructors and destructors are
1079 invoked only once, and called from the most-derived class. However, such
1080 objects behave unspecified when being assigned. For example:
1085 Base(char *n) : name(strdup(n))@{@}
1086 Base& operator= (const Base& other)@{
1088 name = strdup (other.name);
1092 struct A:virtual Base@{
1097 struct B:virtual Base@{
1102 struct Derived:public A, public B@{
1103 Derived():Base("Derived")@{@}
1106 void func(Derived &d1, Derived &d2)
1112 The C++ standard specifies that @samp{Base::Base} is only called once
1113 when constructing or copy-constructing a Derived object. It is
1114 unspecified whether @samp{Base::operator=} is called more than once when
1115 the implicit copy-assignment for Derived objects is invoked (as it is
1116 inside @samp{func} in the example).
1118 G++ implements the ``intuitive'' algorithm for copy-assignment: assign all
1119 direct bases, then assign all members. In that algorithm, the virtual
1120 base subobject can be encountered more than once. In the example, copying
1121 proceeds in the following order: @samp{val}, @samp{name} (via
1122 @code{strdup}), @samp{bval}, and @samp{name} again.
1124 If application code relies on copy-assignment, a user-defined
1125 copy-assignment operator removes any uncertainties. With such an
1126 operator, the application can define whether and how the virtual base
1127 subobject is assigned.
1129 @node Protoize Caveats
1130 @section Caveats of using @command{protoize}
1132 The conversion programs @command{protoize} and @command{unprotoize} can
1133 sometimes change a source file in a way that won't work unless you
1138 @command{protoize} can insert references to a type name or type tag before
1139 the definition, or in a file where they are not defined.
1141 If this happens, compiler error messages should show you where the new
1142 references are, so fixing the file by hand is straightforward.
1145 There are some C constructs which @command{protoize} cannot figure out.
1146 For example, it can't determine argument types for declaring a
1147 pointer-to-function variable; this you must do by hand. @command{protoize}
1148 inserts a comment containing @samp{???} each time it finds such a
1149 variable; so you can find all such variables by searching for this
1150 string. ISO C does not require declaring the argument types of
1151 pointer-to-function types.
1154 Using @command{unprotoize} can easily introduce bugs. If the program
1155 relied on prototypes to bring about conversion of arguments, these
1156 conversions will not take place in the program without prototypes.
1157 One case in which you can be sure @command{unprotoize} is safe is when
1158 you are removing prototypes that were made with @command{protoize}; if
1159 the program worked before without any prototypes, it will work again
1162 @opindex Wconversion
1163 You can find all the places where this problem might occur by compiling
1164 the program with the @option{-Wconversion} option. It prints a warning
1165 whenever an argument is converted.
1168 Both conversion programs can be confused if there are macro calls in and
1169 around the text to be converted. In other words, the standard syntax
1170 for a declaration or definition must not result from expanding a macro.
1171 This problem is inherent in the design of C and cannot be fixed. If
1172 only a few functions have confusing macro calls, you can easily convert
1176 @command{protoize} cannot get the argument types for a function whose
1177 definition was not actually compiled due to preprocessing conditionals.
1178 When this happens, @command{protoize} changes nothing in regard to such
1179 a function. @command{protoize} tries to detect such instances and warn
1182 You can generally work around this problem by using @command{protoize} step
1183 by step, each time specifying a different set of @option{-D} options for
1184 compilation, until all of the functions have been converted. There is
1185 no automatic way to verify that you have got them all, however.
1188 Confusion may result if there is an occasion to convert a function
1189 declaration or definition in a region of source code where there is more
1190 than one formal parameter list present. Thus, attempts to convert code
1191 containing multiple (conditionally compiled) versions of a single
1192 function header (in the same vicinity) may not produce the desired (or
1195 If you plan on converting source files which contain such code, it is
1196 recommended that you first make sure that each conditionally compiled
1197 region of source code which contains an alternative function header also
1198 contains at least one additional follower token (past the final right
1199 parenthesis of the function header). This should circumvent the
1203 @command{unprotoize} can become confused when trying to convert a function
1204 definition or declaration which contains a declaration for a
1205 pointer-to-function formal argument which has the same name as the
1206 function being defined or declared. We recommend you avoid such choices
1207 of formal parameter names.
1210 You might also want to correct some of the indentation by hand and break
1211 long lines. (The conversion programs don't write lines longer than
1212 eighty characters in any case.)
1216 @section Certain Changes We Don't Want to Make
1218 This section lists changes that people frequently request, but which
1219 we do not make because we think GCC is better without them.
1223 Checking the number and type of arguments to a function which has an
1224 old-fashioned definition and no prototype.
1226 Such a feature would work only occasionally---only for calls that appear
1227 in the same file as the called function, following the definition. The
1228 only way to check all calls reliably is to add a prototype for the
1229 function. But adding a prototype eliminates the motivation for this
1230 feature. So the feature is not worthwhile.
1233 Warning about using an expression whose type is signed as a shift count.
1235 Shift count operands are probably signed more often than unsigned.
1236 Warning about this would cause far more annoyance than good.
1239 Warning about assigning a signed value to an unsigned variable.
1241 Such assignments must be very common; warning about them would cause
1242 more annoyance than good.
1245 Warning when a non-void function value is ignored.
1247 C contains many standard functions that return a value that most
1248 programs choose to ignore. One obvious example is @code{printf}.
1249 Warning about this practice only leads the defensive programmer to
1250 clutter programs with dozens of casts to @code{void}. Such casts are
1251 required so frequently that they become visual noise. Writing those
1252 casts becomes so automatic that they no longer convey useful
1253 information about the intentions of the programmer. For functions
1254 where the return value should never be ignored, use the
1255 @code{warn_unused_result} function attribute (@pxref{Function
1259 @opindex fshort-enums
1260 Making @option{-fshort-enums} the default.
1262 This would cause storage layout to be incompatible with most other C
1263 compilers. And it doesn't seem very important, given that you can get
1264 the same result in other ways. The case where it matters most is when
1265 the enumeration-valued object is inside a structure, and in that case
1266 you can specify a field width explicitly.
1269 Making bit-fields unsigned by default on particular machines where ``the
1270 ABI standard'' says to do so.
1272 The ISO C standard leaves it up to the implementation whether a bit-field
1273 declared plain @code{int} is signed or not. This in effect creates two
1274 alternative dialects of C@.
1276 @opindex fsigned-bitfields
1277 @opindex funsigned-bitfields
1278 The GNU C compiler supports both dialects; you can specify the signed
1279 dialect with @option{-fsigned-bitfields} and the unsigned dialect with
1280 @option{-funsigned-bitfields}. However, this leaves open the question of
1281 which dialect to use by default.
1283 Currently, the preferred dialect makes plain bit-fields signed, because
1284 this is simplest. Since @code{int} is the same as @code{signed int} in
1285 every other context, it is cleanest for them to be the same in bit-fields
1288 Some computer manufacturers have published Application Binary Interface
1289 standards which specify that plain bit-fields should be unsigned. It is
1290 a mistake, however, to say anything about this issue in an ABI@. This is
1291 because the handling of plain bit-fields distinguishes two dialects of C@.
1292 Both dialects are meaningful on every type of machine. Whether a
1293 particular object file was compiled using signed bit-fields or unsigned
1294 is of no concern to other object files, even if they access the same
1295 bit-fields in the same data structures.
1297 A given program is written in one or the other of these two dialects.
1298 The program stands a chance to work on most any machine if it is
1299 compiled with the proper dialect. It is unlikely to work at all if
1300 compiled with the wrong dialect.
1302 Many users appreciate the GNU C compiler because it provides an
1303 environment that is uniform across machines. These users would be
1304 inconvenienced if the compiler treated plain bit-fields differently on
1307 Occasionally users write programs intended only for a particular machine
1308 type. On these occasions, the users would benefit if the GNU C compiler
1309 were to support by default the same dialect as the other compilers on
1310 that machine. But such applications are rare. And users writing a
1311 program to run on more than one type of machine cannot possibly benefit
1312 from this kind of compatibility.
1314 This is why GCC does and will treat plain bit-fields in the same
1315 fashion on all types of machines (by default).
1317 There are some arguments for making bit-fields unsigned by default on all
1318 machines. If, for example, this becomes a universal de facto standard,
1319 it would make sense for GCC to go along with it. This is something
1320 to be considered in the future.
1322 (Of course, users strongly concerned about portability should indicate
1323 explicitly in each bit-field whether it is signed or not. In this way,
1324 they write programs which have the same meaning in both C dialects.)
1329 Undefining @code{__STDC__} when @option{-ansi} is not used.
1331 Currently, GCC defines @code{__STDC__} unconditionally. This provides
1332 good results in practice.
1334 Programmers normally use conditionals on @code{__STDC__} to ask whether
1335 it is safe to use certain features of ISO C, such as function
1336 prototypes or ISO token concatenation. Since plain @command{gcc} supports
1337 all the features of ISO C, the correct answer to these questions is
1340 Some users try to use @code{__STDC__} to check for the availability of
1341 certain library facilities. This is actually incorrect usage in an ISO
1342 C program, because the ISO C standard says that a conforming
1343 freestanding implementation should define @code{__STDC__} even though it
1344 does not have the library facilities. @samp{gcc -ansi -pedantic} is a
1345 conforming freestanding implementation, and it is therefore required to
1346 define @code{__STDC__}, even though it does not come with an ISO C
1349 Sometimes people say that defining @code{__STDC__} in a compiler that
1350 does not completely conform to the ISO C standard somehow violates the
1351 standard. This is illogical. The standard is a standard for compilers
1352 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
1353 compilers such as plain @command{gcc}. Whatever the ISO C standard says
1354 is relevant to the design of plain @command{gcc} without @option{-ansi} only
1355 for pragmatic reasons, not as a requirement.
1357 GCC normally defines @code{__STDC__} to be 1, and in addition
1358 defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
1359 or a @option{-std} option for strict conformance to some version of ISO C@.
1360 On some hosts, system include files use a different convention, where
1361 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
1362 conformance to the C Standard. GCC follows the host convention when
1363 processing system include files, but when processing user files it follows
1364 the usual GNU C convention.
1367 Undefining @code{__STDC__} in C++.
1369 Programs written to compile with C++-to-C translators get the
1370 value of @code{__STDC__} that goes with the C compiler that is
1371 subsequently used. These programs must test @code{__STDC__}
1372 to determine what kind of C preprocessor that compiler uses:
1373 whether they should concatenate tokens in the ISO C fashion
1374 or in the traditional fashion.
1376 These programs work properly with GNU C++ if @code{__STDC__} is defined.
1377 They would not work otherwise.
1379 In addition, many header files are written to provide prototypes in ISO
1380 C but not in traditional C@. Many of these header files can work without
1381 change in C++ provided @code{__STDC__} is defined. If @code{__STDC__}
1382 is not defined, they will all fail, and will all need to be changed to
1383 test explicitly for C++ as well.
1386 Deleting ``empty'' loops.
1388 Historically, GCC has not deleted ``empty'' loops under the
1389 assumption that the most likely reason you would put one in a program is
1390 to have a delay, so deleting them will not make real programs run any
1393 However, the rationale here is that optimization of a nonempty loop
1394 cannot produce an empty one, which holds for C but is not always the
1397 @opindex funroll-loops
1398 Moreover, with @option{-funroll-loops} small ``empty'' loops are already
1399 removed, so the current behavior is both sub-optimal and inconsistent
1400 and will change in the future.
1403 Making side effects happen in the same order as in some other compiler.
1405 @cindex side effects, order of evaluation
1406 @cindex order of evaluation, side effects
1407 It is never safe to depend on the order of evaluation of side effects.
1408 For example, a function call like this may very well behave differently
1409 from one compiler to another:
1412 void func (int, int);
1418 There is no guarantee (in either the C or the C++ standard language
1419 definitions) that the increments will be evaluated in any particular
1420 order. Either increment might happen first. @code{func} might get the
1421 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
1424 Not allowing structures with volatile fields in registers.
1426 Strictly speaking, there is no prohibition in the ISO C standard
1427 against allowing structures with volatile fields in registers, but
1428 it does not seem to make any sense and is probably not what you wanted
1429 to do. So the compiler will give an error message in this case.
1432 Making certain warnings into errors by default.
1434 Some ISO C testsuites report failure when the compiler does not produce
1435 an error message for a certain program.
1437 @opindex pedantic-errors
1438 ISO C requires a ``diagnostic'' message for certain kinds of invalid
1439 programs, but a warning is defined by GCC to count as a diagnostic. If
1440 GCC produces a warning but not an error, that is correct ISO C support.
1441 If testsuites call this ``failure'', they should be run with the GCC
1442 option @option{-pedantic-errors}, which will turn these warnings into
1447 @node Warnings and Errors
1448 @section Warning Messages and Error Messages
1450 @cindex error messages
1451 @cindex warnings vs errors
1452 @cindex messages, warning and error
1453 The GNU compiler can produce two kinds of diagnostics: errors and
1454 warnings. Each kind has a different purpose:
1458 @dfn{Errors} report problems that make it impossible to compile your
1459 program. GCC reports errors with the source file name and line
1460 number where the problem is apparent.
1463 @dfn{Warnings} report other unusual conditions in your code that
1464 @emph{may} indicate a problem, although compilation can (and does)
1465 proceed. Warning messages also report the source file name and line
1466 number, but include the text @samp{warning:} to distinguish them
1467 from error messages.
1470 Warnings may indicate danger points where you should check to make sure
1471 that your program really does what you intend; or the use of obsolete
1472 features; or the use of nonstandard features of GNU C or C++. Many
1473 warnings are issued only if you ask for them, with one of the @option{-W}
1474 options (for instance, @option{-Wall} requests a variety of useful
1478 @opindex pedantic-errors
1479 GCC always tries to compile your program if possible; it never
1480 gratuitously rejects a program whose meaning is clear merely because
1481 (for instance) it fails to conform to a standard. In some cases,
1482 however, the C and C++ standards specify that certain extensions are
1483 forbidden, and a diagnostic @emph{must} be issued by a conforming
1484 compiler. The @option{-pedantic} option tells GCC to issue warnings in
1485 such cases; @option{-pedantic-errors} says to make them errors instead.
1486 This does not mean that @emph{all} non-ISO constructs get warnings
1489 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
1490 more detail on these and related command-line options.