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. 5 6@node Trouble 7@chapter Known Causes of Trouble with GCC 8@cindex bugs, known 9@cindex installation trouble 10@cindex known causes of trouble 11 12This section describes known problems that affect users of GCC@. Most 13of these are not GCC bugs per se---if they were, we would fix them. 14But the result for a user may be like the result of a bug. 15 16Some of these problems are due to bugs in other software, some are 17missing features that are too much work to add, and some are places 18where people's opinions differ as to what is best. 19 20@menu 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* Incompatibilities:: GCC is incompatible with traditional C. 26* Fixed Headers:: GCC uses corrected versions of system header files. 27 This is necessary, but doesn't always work smoothly. 28* Standard Libraries:: GCC uses the system C library, which might not be 29 compliant with the ISO C standard. 30* Disappointments:: Regrettable things we can't change, but not quite bugs. 31* C++ Misunderstandings:: Common misunderstandings with GNU C++. 32* Protoize Caveats:: Things to watch out for when using @code{protoize}. 33* Non-bugs:: Things we think are right, but some others disagree. 34* Warnings and Errors:: Which problems in your code get warnings, 35 and which get errors. 36@end menu 37 38@node Actual Bugs 39@section Actual Bugs We Haven't Fixed Yet 40 41@itemize @bullet 42@item 43The @code{fixincludes} script interacts badly with automounters; if the 44directory of system header files is automounted, it tends to be 45unmounted while @code{fixincludes} is running. This would seem to be a 46bug in the automounter. We don't know any good way to work around it. 47 48@item 49The @code{fixproto} script will sometimes add prototypes for the 50@code{sigsetjmp} and @code{siglongjmp} functions that reference the 51@code{jmp_buf} type before that type is defined. To work around this, 52edit the offending file and place the typedef in front of the 53prototypes. 54@end itemize 55 56@node Cross-Compiler Problems 57@section Cross-Compiler Problems 58 59You may run into problems with cross compilation on certain machines, 60for several reasons. 61 62@itemize @bullet 63@item 64At present, the program @file{mips-tfile} which adds debug 65support to object files on MIPS systems does not work in a cross 66compile environment. 67@end itemize 68 69@node Interoperation 70@section Interoperation 71 72This section lists various difficulties encountered in using GCC 73together with other compilers or with the assemblers, linkers, 74libraries and debuggers on certain systems. 75 76@itemize @bullet 77@item 78On many platforms, GCC supports a different ABI for C++ than do other 79compilers, so the object files compiled by GCC cannot be used with object 80files generated by another C++ compiler. 81 82An area where the difference is most apparent is name mangling. The use 83of different name mangling is intentional, to protect you from more subtle 84problems. 85Compilers differ as to many internal details of C++ implementation, 86including: how class instances are laid out, how multiple inheritance is 87implemented, and how virtual function calls are handled. If the name 88encoding were made the same, your programs would link against libraries 89provided from other compilers---but the programs would then crash when 90run. Incompatible libraries are then detected at link time, rather than 91at run time. 92 93@item 94On some BSD systems, including some versions of Ultrix, use of profiling 95causes static variable destructors (currently used only in C++) not to 96be run. 97 98@item 99On some SGI systems, when you use @option{-lgl_s} as an option, 100it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}. 101Naturally, this does not happen when you use GCC@. 102You must specify all three options explicitly. 103 104@item 105On a SPARC, GCC aligns all values of type @code{double} on an 8-byte 106boundary, and it expects every @code{double} to be so aligned. The Sun 107compiler usually gives @code{double} values 8-byte alignment, with one 108exception: function arguments of type @code{double} may not be aligned. 109 110As a result, if a function compiled with Sun CC takes the address of an 111argument of type @code{double} and passes this pointer of type 112@code{double *} to a function compiled with GCC, dereferencing the 113pointer may cause a fatal signal. 114 115One way to solve this problem is to compile your entire program with GCC@. 116Another solution is to modify the function that is compiled with 117Sun CC to copy the argument into a local variable; local variables 118are always properly aligned. A third solution is to modify the function 119that uses the pointer to dereference it via the following function 120@code{access_double} instead of directly with @samp{*}: 121 122@smallexample 123inline double 124access_double (double *unaligned_ptr) 125@{ 126 union d2i @{ double d; int i[2]; @}; 127 128 union d2i *p = (union d2i *) unaligned_ptr; 129 union d2i u; 130 131 u.i[0] = p->i[0]; 132 u.i[1] = p->i[1]; 133 134 return u.d; 135@} 136@end smallexample 137 138@noindent 139Storing into the pointer can be done likewise with the same union. 140 141@item 142On Solaris, the @code{malloc} function in the @file{libmalloc.a} library 143may allocate memory that is only 4 byte aligned. Since GCC on the 144SPARC assumes that doubles are 8 byte aligned, this may result in a 145fatal signal if doubles are stored in memory allocated by the 146@file{libmalloc.a} library. 147 148The solution is to not use the @file{libmalloc.a} library. Use instead 149@code{malloc} and related functions from @file{libc.a}; they do not have 150this problem. 151 152@item 153On the HP PA machine, ADB sometimes fails to work on functions compiled 154with GCC@. Specifically, it fails to work on functions that use 155@code{alloca} or variable-size arrays. This is because GCC doesn't 156generate HP-UX unwind descriptors for such functions. It may even be 157impossible to generate them. 158 159@item 160Debugging (@option{-g}) is not supported on the HP PA machine, unless you use 161the preliminary GNU tools. 162 163@item 164Taking the address of a label may generate errors from the HP-UX 165PA assembler. GAS for the PA does not have this problem. 166 167@item 168Using floating point parameters for indirect calls to static functions 169will not work when using the HP assembler. There simply is no way for GCC 170to specify what registers hold arguments for static functions when using 171the HP assembler. GAS for the PA does not have this problem. 172 173@item 174In extremely rare cases involving some very large functions you may 175receive errors from the HP linker complaining about an out of bounds 176unconditional branch offset. This used to occur more often in previous 177versions of GCC, but is now exceptionally rare. If you should run 178into it, you can work around by making your function smaller. 179 180@item 181GCC compiled code sometimes emits warnings from the HP-UX assembler of 182the form: 183 184@smallexample 185(warning) Use of GR3 when 186 frame >= 8192 may cause conflict. 187@end smallexample 188 189These warnings are harmless and can be safely ignored. 190 191@item 192In extremely rare cases involving some very large functions you may 193receive errors from the AIX Assembler complaining about a displacement 194that is too large. If you should run into it, you can work around by 195making your function smaller. 196 197@item 198The @file{libstdc++.a} library in GCC relies on the SVR4 dynamic 199linker semantics which merges global symbols between libraries and 200applications, especially necessary for C++ streams functionality. 201This is not the default behavior of AIX shared libraries and dynamic 202linking. @file{libstdc++.a} is built on AIX with ``runtime-linking'' 203enabled so that symbol merging can occur. To utilize this feature, 204the application linked with @file{libstdc++.a} must include the 205@option{-Wl,-brtl} flag on the link line. G++ cannot impose this 206because this option may interfere with the semantics of the user 207program and users may not always use @samp{g++} to link his or her 208application. Applications are not required to use the 209@option{-Wl,-brtl} flag on the link line---the rest of the 210@file{libstdc++.a} library which is not dependent on the symbol 211merging semantics will continue to function correctly. 212 213@item 214An application can interpose its own definition of functions for 215functions invoked by @file{libstdc++.a} with ``runtime-linking'' 216enabled on AIX@. To accomplish this the application must be linked 217with ``runtime-linking'' option and the functions explicitly must be 218exported by the application (@option{-Wl,-brtl,-bE:exportfile}). 219 220@item 221AIX on the RS/6000 provides support (NLS) for environments outside of 222the United States. Compilers and assemblers use NLS to support 223locale-specific representations of various objects including 224floating-point numbers (@samp{.} vs @samp{,} for separating decimal 225fractions). There have been problems reported where the library linked 226with GCC does not produce the same floating-point formats that the 227assembler accepts. If you have this problem, set the @env{LANG} 228environment variable to @samp{C} or @samp{En_US}. 229 230@item 231@opindex fdollars-in-identifiers 232Even if you specify @option{-fdollars-in-identifiers}, 233you cannot successfully use @samp{$} in identifiers on the RS/6000 due 234to a restriction in the IBM assembler. GAS supports these 235identifiers. 236 237@cindex VAX calling convention 238@cindex Ultrix calling convention 239@item 240@opindex fcall-saved 241On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved 242by function calls. However, the C compiler uses conventions compatible 243with BSD Unix: registers 2 through 5 may be clobbered by function calls. 244 245GCC uses the same convention as the Ultrix C compiler. You can use 246these options to produce code compatible with the Fortran compiler: 247 248@smallexample 249-fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5 250@end smallexample 251@end itemize 252 253@node Incompatibilities 254@section Incompatibilities of GCC 255@cindex incompatibilities of GCC 256@opindex traditional 257 258There are several noteworthy incompatibilities between GNU C and K&R 259(non-ISO) versions of C@. 260 261@itemize @bullet 262@cindex string constants 263@cindex read-only strings 264@cindex shared strings 265@item 266GCC normally makes string constants read-only. If several 267identical-looking string constants are used, GCC stores only one 268copy of the string. 269 270@cindex @code{mktemp}, and constant strings 271One consequence is that you cannot call @code{mktemp} with a string 272constant argument. The function @code{mktemp} always alters the 273string its argument points to. 274 275@cindex @code{sscanf}, and constant strings 276@cindex @code{fscanf}, and constant strings 277@cindex @code{scanf}, and constant strings 278Another consequence is that @code{sscanf} does not work on some very 279old systems when passed a string constant as its format control string 280or input. This is because @code{sscanf} incorrectly tries to write 281into the string constant. Likewise @code{fscanf} and @code{scanf}. 282 283The solution to these problems is to change the program to use 284@code{char}-array variables with initialization strings for these 285purposes instead of string constants. 286 287@item 288@code{-2147483648} is positive. 289 290This is because 2147483648 cannot fit in the type @code{int}, so 291(following the ISO C rules) its data type is @code{unsigned long int}. 292Negating this value yields 2147483648 again. 293 294@item 295GCC does not substitute macro arguments when they appear inside of 296string constants. For example, the following macro in GCC 297 298@smallexample 299#define foo(a) "a" 300@end smallexample 301 302@noindent 303will produce output @code{"a"} regardless of what the argument @var{a} is. 304 305@cindex @code{setjmp} incompatibilities 306@cindex @code{longjmp} incompatibilities 307@item 308When you use @code{setjmp} and @code{longjmp}, the only automatic 309variables guaranteed to remain valid are those declared 310@code{volatile}. This is a consequence of automatic register 311allocation. Consider this function: 312 313@smallexample 314jmp_buf j; 315 316foo () 317@{ 318 int a, b; 319 320 a = fun1 (); 321 if (setjmp (j)) 322 return a; 323 324 a = fun2 (); 325 /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */ 326 return a + fun3 (); 327@} 328@end smallexample 329 330Here @code{a} may or may not be restored to its first value when the 331@code{longjmp} occurs. If @code{a} is allocated in a register, then 332its first value is restored; otherwise, it keeps the last value stored 333in it. 334 335@opindex W 336If you use the @option{-W} option with the @option{-O} option, you will 337get a warning when GCC thinks such a problem might be possible. 338 339@item 340Programs that use preprocessing directives in the middle of macro 341arguments do not work with GCC@. For example, a program like this 342will not work: 343 344@smallexample 345@group 346foobar ( 347#define luser 348 hack) 349@end group 350@end smallexample 351 352ISO C does not permit such a construct. 353 354@item 355K&R compilers allow comments to cross over an inclusion boundary 356(i.e.@: started in an include file and ended in the including file). 357 358@cindex external declaration scope 359@cindex scope of external declarations 360@cindex declaration scope 361@item 362Declarations of external variables and functions within a block apply 363only to the block containing the declaration. In other words, they 364have the same scope as any other declaration in the same place. 365 366In some other C compilers, a @code{extern} declaration affects all the 367rest of the file even if it happens within a block. 368 369@item 370In traditional C, you can combine @code{long}, etc., with a typedef name, 371as shown here: 372 373@smallexample 374typedef int foo; 375typedef long foo bar; 376@end smallexample 377 378In ISO C, this is not allowed: @code{long} and other type modifiers 379require an explicit @code{int}. 380 381@cindex typedef names as function parameters 382@item 383PCC allows typedef names to be used as function parameters. 384 385@item 386Traditional C allows the following erroneous pair of declarations to 387appear together in a given scope: 388 389@smallexample 390typedef int foo; 391typedef foo foo; 392@end smallexample 393 394@item 395GCC treats all characters of identifiers as significant. According to 396K&R-1 (2.2), ``No more than the first eight characters are significant, 397although more may be used.''. Also according to K&R-1 (2.2), ``An 398identifier is a sequence of letters and digits; the first character must 399be a letter. The underscore _ counts as a letter.'', but GCC also 400allows dollar signs in identifiers. 401 402@cindex whitespace 403@item 404PCC allows whitespace in the middle of compound assignment operators 405such as @samp{+=}. GCC, following the ISO standard, does not 406allow this. 407 408@cindex apostrophes 409@cindex ' 410@item 411GCC complains about unterminated character constants inside of 412preprocessing conditionals that fail. Some programs have English 413comments enclosed in conditionals that are guaranteed to fail; if these 414comments contain apostrophes, GCC will probably report an error. For 415example, this code would produce an error: 416 417@smallexample 418#if 0 419You can't expect this to work. 420#endif 421@end smallexample 422 423The best solution to such a problem is to put the text into an actual 424C comment delimited by @samp{/*@dots{}*/}. 425 426@item 427Many user programs contain the declaration @samp{long time ();}. In the 428past, the system header files on many systems did not actually declare 429@code{time}, so it did not matter what type your program declared it to 430return. But in systems with ISO C headers, @code{time} is declared to 431return @code{time_t}, and if that is not the same as @code{long}, then 432@samp{long time ();} is erroneous. 433 434The solution is to change your program to use appropriate system headers 435(@code{<time.h>} on systems with ISO C headers) and not to declare 436@code{time} if the system header files declare it, or failing that to 437use @code{time_t} as the return type of @code{time}. 438 439@cindex @code{float} as function value type 440@item 441When compiling functions that return @code{float}, PCC converts it to 442a double. GCC actually returns a @code{float}. If you are concerned 443with PCC compatibility, you should declare your functions to return 444@code{double}; you might as well say what you mean. 445 446@cindex structures 447@cindex unions 448@item 449When compiling functions that return structures or unions, GCC 450output code normally uses a method different from that used on most 451versions of Unix. As a result, code compiled with GCC cannot call 452a structure-returning function compiled with PCC, and vice versa. 453 454The method used by GCC is as follows: a structure or union which is 4551, 2, 4 or 8 bytes long is returned like a scalar. A structure or union 456with any other size is stored into an address supplied by the caller 457(usually in a special, fixed register, but on some machines it is passed 458on the stack). The target hook @code{TARGET_STRUCT_VALUE_RTX} 459tells GCC where to pass this address. 460 461By contrast, PCC on most target machines returns structures and unions 462of any size by copying the data into an area of static storage, and then 463returning the address of that storage as if it were a pointer value. 464The caller must copy the data from that memory area to the place where 465the value is wanted. GCC does not use this method because it is 466slower and nonreentrant. 467 468On some newer machines, PCC uses a reentrant convention for all 469structure and union returning. GCC on most of these machines uses a 470compatible convention when returning structures and unions in memory, 471but still returns small structures and unions in registers. 472 473@opindex fpcc-struct-return 474You can tell GCC to use a compatible convention for all structure and 475union returning with the option @option{-fpcc-struct-return}. 476 477@cindex preprocessing tokens 478@cindex preprocessing numbers 479@item 480GCC complains about program fragments such as @samp{0x74ae-0x4000} 481which appear to be two hexadecimal constants separated by the minus 482operator. Actually, this string is a single @dfn{preprocessing token}. 483Each such token must correspond to one token in C@. Since this does not, 484GCC prints an error message. Although it may appear obvious that what 485is meant is an operator and two values, the ISO C standard specifically 486requires that this be treated as erroneous. 487 488A @dfn{preprocessing token} is a @dfn{preprocessing number} if it 489begins with a digit and is followed by letters, underscores, digits, 490periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+}, 491@samp{p-}, @samp{P+}, or @samp{P-} character sequences. (In strict C89 492mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot 493appear in preprocessing numbers.) 494 495To make the above program fragment valid, place whitespace in front of 496the minus sign. This whitespace will end the preprocessing number. 497@end itemize 498 499@node Fixed Headers 500@section Fixed Header Files 501 502GCC needs to install corrected versions of some system header files. 503This is because most target systems have some header files that won't 504work with GCC unless they are changed. Some have bugs, some are 505incompatible with ISO C, and some depend on special features of other 506compilers. 507 508Installing GCC automatically creates and installs the fixed header 509files, by running a program called @code{fixincludes}. Normally, you 510don't need to pay attention to this. But there are cases where it 511doesn't do the right thing automatically. 512 513@itemize @bullet 514@item 515If you update the system's header files, such as by installing a new 516system version, the fixed header files of GCC are not automatically 517updated. They can be updated using the @command{mkheaders} script 518installed in 519@file{@var{libexecdir}/gcc/@var{target}/@var{version}/install-tools/}. 520 521@item 522On some systems, header file directories contain 523machine-specific symbolic links in certain places. This makes it 524possible to share most of the header files among hosts running the 525same version of the system on different machine models. 526 527The programs that fix the header files do not understand this special 528way of using symbolic links; therefore, the directory of fixed header 529files is good only for the machine model used to build it. 530 531It is possible to make separate sets of fixed header files for the 532different machine models, and arrange a structure of symbolic links so 533as to use the proper set, but you'll have to do this by hand. 534@end itemize 535 536@node Standard Libraries 537@section Standard Libraries 538 539@opindex Wall 540GCC by itself attempts to be a conforming freestanding implementation. 541@xref{Standards,,Language Standards Supported by GCC}, for details of 542what this means. Beyond the library facilities required of such an 543implementation, the rest of the C library is supplied by the vendor of 544the operating system. If that C library doesn't conform to the C 545standards, then your programs might get warnings (especially when using 546@option{-Wall}) that you don't expect. 547 548For example, the @code{sprintf} function on SunOS 4.1.3 returns 549@code{char *} while the C standard says that @code{sprintf} returns an 550@code{int}. The @code{fixincludes} program could make the prototype for 551this function match the Standard, but that would be wrong, since the 552function will still return @code{char *}. 553 554If you need a Standard compliant library, then you need to find one, as 555GCC does not provide one. The GNU C library (called @code{glibc}) 556provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for 557GNU/Linux and HURD-based GNU systems; no recent version of it supports 558other systems, though some very old versions did. Version 2.2 of the 559GNU C library includes nearly complete C99 support. You could also ask 560your operating system vendor if newer libraries are available. 561 562@node Disappointments 563@section Disappointments and Misunderstandings 564 565These problems are perhaps regrettable, but we don't know any practical 566way around them. 567 568@itemize @bullet 569@item 570Certain local variables aren't recognized by debuggers when you compile 571with optimization. 572 573This occurs because sometimes GCC optimizes the variable out of 574existence. There is no way to tell the debugger how to compute the 575value such a variable ``would have had'', and it is not clear that would 576be desirable anyway. So GCC simply does not mention the eliminated 577variable when it writes debugging information. 578 579You have to expect a certain amount of disagreement between the 580executable and your source code, when you use optimization. 581 582@cindex conflicting types 583@cindex scope of declaration 584@item 585Users often think it is a bug when GCC reports an error for code 586like this: 587 588@smallexample 589int foo (struct mumble *); 590 591struct mumble @{ @dots{} @}; 592 593int foo (struct mumble *x) 594@{ @dots{} @} 595@end smallexample 596 597This code really is erroneous, because the scope of @code{struct 598mumble} in the prototype is limited to the argument list containing it. 599It does not refer to the @code{struct mumble} defined with file scope 600immediately below---they are two unrelated types with similar names in 601different scopes. 602 603But in the definition of @code{foo}, the file-scope type is used 604because that is available to be inherited. Thus, the definition and 605the prototype do not match, and you get an error. 606 607This behavior may seem silly, but it's what the ISO standard specifies. 608It is easy enough for you to make your code work by moving the 609definition of @code{struct mumble} above the prototype. It's not worth 610being incompatible with ISO C just to avoid an error for the example 611shown above. 612 613@item 614Accesses to bit-fields even in volatile objects works by accessing larger 615objects, such as a byte or a word. You cannot rely on what size of 616object is accessed in order to read or write the bit-field; it may even 617vary for a given bit-field according to the precise usage. 618 619If you care about controlling the amount of memory that is accessed, use 620volatile but do not use bit-fields. 621 622@item 623GCC comes with shell scripts to fix certain known problems in system 624header files. They install corrected copies of various header files in 625a special directory where only GCC will normally look for them. The 626scripts adapt to various systems by searching all the system header 627files for the problem cases that we know about. 628 629If new system header files are installed, nothing automatically arranges 630to update the corrected header files. They can be updated using the 631@command{mkheaders} script installed in 632@file{@var{libexecdir}/gcc/@var{target}/@var{version}/install-tools/}. 633 634@item 635@cindex floating point precision 636On 68000 and x86 systems, for instance, you can get paradoxical results 637if you test the precise values of floating point numbers. For example, 638you can find that a floating point value which is not a NaN is not equal 639to itself. This results from the fact that the floating point registers 640hold a few more bits of precision than fit in a @code{double} in memory. 641Compiled code moves values between memory and floating point registers 642at its convenience, and moving them into memory truncates them. 643 644@opindex ffloat-store 645You can partially avoid this problem by using the @option{-ffloat-store} 646option (@pxref{Optimize Options}). 647 648@item 649On AIX and other platforms without weak symbol support, templates 650need to be instantiated explicitly and symbols for static members 651of templates will not be generated. 652 653@item 654On AIX, GCC scans object files and library archives for static 655constructors and destructors when linking an application before the 656linker prunes unreferenced symbols. This is necessary to prevent the 657AIX linker from mistakenly assuming that static constructor or 658destructor are unused and removing them before the scanning can occur. 659All static constructors and destructors found will be referenced even 660though the modules in which they occur may not be used by the program. 661This may lead to both increased executable size and unexpected symbol 662references. 663@end itemize 664 665@node C++ Misunderstandings 666@section Common Misunderstandings with GNU C++ 667 668@cindex misunderstandings in C++ 669@cindex surprises in C++ 670@cindex C++ misunderstandings 671C++ is a complex language and an evolving one, and its standard 672definition (the ISO C++ standard) was only recently completed. As a 673result, your C++ compiler may occasionally surprise you, even when its 674behavior is correct. This section discusses some areas that frequently 675give rise to questions of this sort. 676 677@menu 678* Static Definitions:: Static member declarations are not definitions 679* Name lookup:: Name lookup, templates, and accessing members of base classes 680* Temporaries:: Temporaries may vanish before you expect 681* Copy Assignment:: Copy Assignment operators copy virtual bases twice 682@end menu 683 684@node Static Definitions 685@subsection Declare @emph{and} Define Static Members 686 687@cindex C++ static data, declaring and defining 688@cindex static data in C++, declaring and defining 689@cindex declaring static data in C++ 690@cindex defining static data in C++ 691When a class has static data members, it is not enough to @emph{declare} 692the static member; you must also @emph{define} it. For example: 693 694@smallexample 695class Foo 696@{ 697 @dots{} 698 void method(); 699 static int bar; 700@}; 701@end smallexample 702 703This declaration only establishes that the class @code{Foo} has an 704@code{int} named @code{Foo::bar}, and a member function named 705@code{Foo::method}. But you still need to define @emph{both} 706@code{method} and @code{bar} elsewhere. According to the ISO 707standard, you must supply an initializer in one (and only one) source 708file, such as: 709 710@smallexample 711int Foo::bar = 0; 712@end smallexample 713 714Other C++ compilers may not correctly implement the standard behavior. 715As a result, when you switch to @command{g++} from one of these compilers, 716you may discover that a program that appeared to work correctly in fact 717does not conform to the standard: @command{g++} reports as undefined 718symbols any static data members that lack definitions. 719 720 721@node Name lookup 722@subsection Name lookup, templates, and accessing members of base classes 723 724@cindex base class members 725@cindex two-stage name lookup 726@cindex dependent name lookup 727 728The C++ standard prescribes that all names that are not dependent on 729template parameters are bound to their present definitions when parsing 730a template function or class.@footnote{The C++ standard just uses the 731term ``dependent'' for names that depend on the type or value of 732template parameters. This shorter term will also be used in the rest of 733this section.} Only names that are dependent are looked up at the point 734of instantiation. For example, consider 735 736@smallexample 737 void foo(double); 738 739 struct A @{ 740 template <typename T> 741 void f () @{ 742 foo (1); // @r{1} 743 int i = N; // @r{2} 744 T t; 745 t.bar(); // @r{3} 746 foo (t); // @r{4} 747 @} 748 749 static const int N; 750 @}; 751@end smallexample 752 753Here, the names @code{foo} and @code{N} appear in a context that does 754not depend on the type of @code{T}. The compiler will thus require that 755they are defined in the context of use in the template, not only before 756the point of instantiation, and will here use @code{::foo(double)} and 757@code{A::N}, respectively. In particular, it will convert the integer 758value to a @code{double} when passing it to @code{::foo(double)}. 759 760Conversely, @code{bar} and the call to @code{foo} in the fourth marked 761line are used in contexts that do depend on the type of @code{T}, so 762they are only looked up at the point of instantiation, and you can 763provide declarations for them after declaring the template, but before 764instantiating it. In particular, if you instantiate @code{A::f<int>}, 765the last line will call an overloaded @code{::foo(int)} if one was 766provided, even if after the declaration of @code{struct A}. 767 768This distinction between lookup of dependent and non-dependent names is 769called two-stage (or dependent) name lookup. G++ implements it 770since version 3.4. 771 772Two-stage name lookup sometimes leads to situations with behavior 773different from non-template codes. The most common is probably this: 774 775@smallexample 776 template <typename T> struct Base @{ 777 int i; 778 @}; 779 780 template <typename T> struct Derived : public Base<T> @{ 781 int get_i() @{ return i; @} 782 @}; 783@end smallexample 784 785In @code{get_i()}, @code{i} is not used in a dependent context, so the 786compiler will look for a name declared at the enclosing namespace scope 787(which is the global scope here). It will not look into the base class, 788since that is dependent and you may declare specializations of 789@code{Base} even after declaring @code{Derived}, so the compiler can't 790really know what @code{i} would refer to. If there is no global 791variable @code{i}, then you will get an error message. 792 793In order to make it clear that you want the member of the base class, 794you need to defer lookup until instantiation time, at which the base 795class is known. For this, you need to access @code{i} in a dependent 796context, by either using @code{this->i} (remember that @code{this} is of 797type @code{Derived<T>*}, so is obviously dependent), or using 798@code{Base<T>::i}. Alternatively, @code{Base<T>::i} might be brought 799into scope by a @code{using}-declaration. 800 801Another, similar example involves calling member functions of a base 802class: 803 804@smallexample 805 template <typename T> struct Base @{ 806 int f(); 807 @}; 808 809 template <typename T> struct Derived : Base<T> @{ 810 int g() @{ return f(); @}; 811 @}; 812@end smallexample 813 814Again, the call to @code{f()} is not dependent on template arguments 815(there are no arguments that depend on the type @code{T}, and it is also 816not otherwise specified that the call should be in a dependent context). 817Thus a global declaration of such a function must be available, since 818the one in the base class is not visible until instantiation time. The 819compiler will consequently produce the following error message: 820 821@smallexample 822 x.cc: In member function `int Derived<T>::g()': 823 x.cc:6: error: there are no arguments to `f' that depend on a template 824 parameter, so a declaration of `f' must be available 825 x.cc:6: error: (if you use `-fpermissive', G++ will accept your code, but 826 allowing the use of an undeclared name is deprecated) 827@end smallexample 828 829To make the code valid either use @code{this->f()}, or 830@code{Base<T>::f()}. Using the @option{-fpermissive} flag will also let 831the compiler accept the code, by marking all function calls for which no 832declaration is visible at the time of definition of the template for 833later lookup at instantiation time, as if it were a dependent call. 834We do not recommend using @option{-fpermissive} to work around invalid 835code, and it will also only catch cases where functions in base classes 836are called, not where variables in base classes are used (as in the 837example above). 838 839Note that some compilers (including G++ versions prior to 3.4) get these 840examples wrong and accept above code without an error. Those compilers 841do not implement two-stage name lookup correctly. 842 843 844@node Temporaries 845@subsection Temporaries May Vanish Before You Expect 846 847@cindex temporaries, lifetime of 848@cindex portions of temporary objects, pointers to 849It is dangerous to use pointers or references to @emph{portions} of a 850temporary object. The compiler may very well delete the object before 851you expect it to, leaving a pointer to garbage. The most common place 852where this problem crops up is in classes like string classes, 853especially ones that define a conversion function to type @code{char *} 854or @code{const char *}---which is one reason why the standard 855@code{string} class requires you to call the @code{c_str} member 856function. However, any class that returns a pointer to some internal 857structure is potentially subject to this problem. 858 859For example, a program may use a function @code{strfunc} that returns 860@code{string} objects, and another function @code{charfunc} that 861operates on pointers to @code{char}: 862 863@smallexample 864string strfunc (); 865void charfunc (const char *); 866 867void 868f () 869@{ 870 const char *p = strfunc().c_str(); 871 @dots{} 872 charfunc (p); 873 @dots{} 874 charfunc (p); 875@} 876@end smallexample 877 878@noindent 879In this situation, it may seem reasonable to save a pointer to the C 880string returned by the @code{c_str} member function and use that rather 881than call @code{c_str} repeatedly. However, the temporary string 882created by the call to @code{strfunc} is destroyed after @code{p} is 883initialized, at which point @code{p} is left pointing to freed memory. 884 885Code like this may run successfully under some other compilers, 886particularly obsolete cfront-based compilers that delete temporaries 887along with normal local variables. However, the GNU C++ behavior is 888standard-conforming, so if your program depends on late destruction of 889temporaries it is not portable. 890 891The safe way to write such code is to give the temporary a name, which 892forces it to remain until the end of the scope of the name. For 893example: 894 895@smallexample 896const string& tmp = strfunc (); 897charfunc (tmp.c_str ()); 898@end smallexample 899 900@node Copy Assignment 901@subsection Implicit Copy-Assignment for Virtual Bases 902 903When a base class is virtual, only one subobject of the base class 904belongs to each full object. Also, the constructors and destructors are 905invoked only once, and called from the most-derived class. However, such 906objects behave unspecified when being assigned. For example: 907 908@smallexample 909struct Base@{ 910 char *name; 911 Base(char *n) : name(strdup(n))@{@} 912 Base& operator= (const Base& other)@{ 913 free (name); 914 name = strdup (other.name); 915 @} 916@}; 917 918struct A:virtual Base@{ 919 int val; 920 A():Base("A")@{@} 921@}; 922 923struct B:virtual Base@{ 924 int bval; 925 B():Base("B")@{@} 926@}; 927 928struct Derived:public A, public B@{ 929 Derived():Base("Derived")@{@} 930@}; 931 932void func(Derived &d1, Derived &d2) 933@{ 934 d1 = d2; 935@} 936@end smallexample 937 938The C++ standard specifies that @samp{Base::Base} is only called once 939when constructing or copy-constructing a Derived object. It is 940unspecified whether @samp{Base::operator=} is called more than once when 941the implicit copy-assignment for Derived objects is invoked (as it is 942inside @samp{func} in the example). 943 944G++ implements the ``intuitive'' algorithm for copy-assignment: assign all 945direct bases, then assign all members. In that algorithm, the virtual 946base subobject can be encountered more than once. In the example, copying 947proceeds in the following order: @samp{val}, @samp{name} (via 948@code{strdup}), @samp{bval}, and @samp{name} again. 949 950If application code relies on copy-assignment, a user-defined 951copy-assignment operator removes any uncertainties. With such an 952operator, the application can define whether and how the virtual base 953subobject is assigned. 954 955@node Protoize Caveats 956@section Caveats of using @command{protoize} 957 958The conversion programs @command{protoize} and @command{unprotoize} can 959sometimes change a source file in a way that won't work unless you 960rearrange it. 961 962@itemize @bullet 963@item 964@command{protoize} can insert references to a type name or type tag before 965the definition, or in a file where they are not defined. 966 967If this happens, compiler error messages should show you where the new 968references are, so fixing the file by hand is straightforward. 969 970@item 971There are some C constructs which @command{protoize} cannot figure out. 972For example, it can't determine argument types for declaring a 973pointer-to-function variable; this you must do by hand. @command{protoize} 974inserts a comment containing @samp{???} each time it finds such a 975variable; so you can find all such variables by searching for this 976string. ISO C does not require declaring the argument types of 977pointer-to-function types. 978 979@item 980Using @command{unprotoize} can easily introduce bugs. If the program 981relied on prototypes to bring about conversion of arguments, these 982conversions will not take place in the program without prototypes. 983One case in which you can be sure @command{unprotoize} is safe is when 984you are removing prototypes that were made with @command{protoize}; if 985the program worked before without any prototypes, it will work again 986without them. 987 988@opindex Wconversion 989You can find all the places where this problem might occur by compiling 990the program with the @option{-Wconversion} option. It prints a warning 991whenever an argument is converted. 992 993@item 994Both conversion programs can be confused if there are macro calls in and 995around the text to be converted. In other words, the standard syntax 996for a declaration or definition must not result from expanding a macro. 997This problem is inherent in the design of C and cannot be fixed. If 998only a few functions have confusing macro calls, you can easily convert 999them manually. 1000 1001@item 1002@command{protoize} cannot get the argument types for a function whose 1003definition was not actually compiled due to preprocessing conditionals. 1004When this happens, @command{protoize} changes nothing in regard to such 1005a function. @command{protoize} tries to detect such instances and warn 1006about them. 1007 1008You can generally work around this problem by using @command{protoize} step 1009by step, each time specifying a different set of @option{-D} options for 1010compilation, until all of the functions have been converted. There is 1011no automatic way to verify that you have got them all, however. 1012 1013@item 1014Confusion may result if there is an occasion to convert a function 1015declaration or definition in a region of source code where there is more 1016than one formal parameter list present. Thus, attempts to convert code 1017containing multiple (conditionally compiled) versions of a single 1018function header (in the same vicinity) may not produce the desired (or 1019expected) results. 1020 1021If you plan on converting source files which contain such code, it is 1022recommended that you first make sure that each conditionally compiled 1023region of source code which contains an alternative function header also 1024contains at least one additional follower token (past the final right 1025parenthesis of the function header). This should circumvent the 1026problem. 1027 1028@item 1029@command{unprotoize} can become confused when trying to convert a function 1030definition or declaration which contains a declaration for a 1031pointer-to-function formal argument which has the same name as the 1032function being defined or declared. We recommend you avoid such choices 1033of formal parameter names. 1034 1035@item 1036You might also want to correct some of the indentation by hand and break 1037long lines. (The conversion programs don't write lines longer than 1038eighty characters in any case.) 1039@end itemize 1040 1041@node Non-bugs 1042@section Certain Changes We Don't Want to Make 1043 1044This section lists changes that people frequently request, but which 1045we do not make because we think GCC is better without them. 1046 1047@itemize @bullet 1048@item 1049Checking the number and type of arguments to a function which has an 1050old-fashioned definition and no prototype. 1051 1052Such a feature would work only occasionally---only for calls that appear 1053in the same file as the called function, following the definition. The 1054only way to check all calls reliably is to add a prototype for the 1055function. But adding a prototype eliminates the motivation for this 1056feature. So the feature is not worthwhile. 1057 1058@item 1059Warning about using an expression whose type is signed as a shift count. 1060 1061Shift count operands are probably signed more often than unsigned. 1062Warning about this would cause far more annoyance than good. 1063 1064@item 1065Warning about assigning a signed value to an unsigned variable. 1066 1067Such assignments must be very common; warning about them would cause 1068more annoyance than good. 1069 1070@item 1071Warning when a non-void function value is ignored. 1072 1073C contains many standard functions that return a value that most 1074programs choose to ignore. One obvious example is @code{printf}. 1075Warning about this practice only leads the defensive programmer to 1076clutter programs with dozens of casts to @code{void}. Such casts are 1077required so frequently that they become visual noise. Writing those 1078casts becomes so automatic that they no longer convey useful 1079information about the intentions of the programmer. For functions 1080where the return value should never be ignored, use the 1081@code{warn_unused_result} function attribute (@pxref{Function 1082Attributes}). 1083 1084@item 1085@opindex fshort-enums 1086Making @option{-fshort-enums} the default. 1087 1088This would cause storage layout to be incompatible with most other C 1089compilers. And it doesn't seem very important, given that you can get 1090the same result in other ways. The case where it matters most is when 1091the enumeration-valued object is inside a structure, and in that case 1092you can specify a field width explicitly. 1093 1094@item 1095Making bit-fields unsigned by default on particular machines where ``the 1096ABI standard'' says to do so. 1097 1098The ISO C standard leaves it up to the implementation whether a bit-field 1099declared plain @code{int} is signed or not. This in effect creates two 1100alternative dialects of C@. 1101 1102@opindex fsigned-bitfields 1103@opindex funsigned-bitfields 1104The GNU C compiler supports both dialects; you can specify the signed 1105dialect with @option{-fsigned-bitfields} and the unsigned dialect with 1106@option{-funsigned-bitfields}. However, this leaves open the question of 1107which dialect to use by default. 1108 1109Currently, the preferred dialect makes plain bit-fields signed, because 1110this is simplest. Since @code{int} is the same as @code{signed int} in 1111every other context, it is cleanest for them to be the same in bit-fields 1112as well. 1113 1114Some computer manufacturers have published Application Binary Interface 1115standards which specify that plain bit-fields should be unsigned. It is 1116a mistake, however, to say anything about this issue in an ABI@. This is 1117because the handling of plain bit-fields distinguishes two dialects of C@. 1118Both dialects are meaningful on every type of machine. Whether a 1119particular object file was compiled using signed bit-fields or unsigned 1120is of no concern to other object files, even if they access the same 1121bit-fields in the same data structures. 1122 1123A given program is written in one or the other of these two dialects. 1124The program stands a chance to work on most any machine if it is 1125compiled with the proper dialect. It is unlikely to work at all if 1126compiled with the wrong dialect. 1127 1128Many users appreciate the GNU C compiler because it provides an 1129environment that is uniform across machines. These users would be 1130inconvenienced if the compiler treated plain bit-fields differently on 1131certain machines. 1132 1133Occasionally users write programs intended only for a particular machine 1134type. On these occasions, the users would benefit if the GNU C compiler 1135were to support by default the same dialect as the other compilers on 1136that machine. But such applications are rare. And users writing a 1137program to run on more than one type of machine cannot possibly benefit 1138from this kind of compatibility. 1139 1140This is why GCC does and will treat plain bit-fields in the same 1141fashion on all types of machines (by default). 1142 1143There are some arguments for making bit-fields unsigned by default on all 1144machines. If, for example, this becomes a universal de facto standard, 1145it would make sense for GCC to go along with it. This is something 1146to be considered in the future. 1147 1148(Of course, users strongly concerned about portability should indicate 1149explicitly in each bit-field whether it is signed or not. In this way, 1150they write programs which have the same meaning in both C dialects.) 1151 1152@item 1153@opindex ansi 1154@opindex std 1155Undefining @code{__STDC__} when @option{-ansi} is not used. 1156 1157Currently, GCC defines @code{__STDC__} unconditionally. This provides 1158good results in practice. 1159 1160Programmers normally use conditionals on @code{__STDC__} to ask whether 1161it is safe to use certain features of ISO C, such as function 1162prototypes or ISO token concatenation. Since plain @command{gcc} supports 1163all the features of ISO C, the correct answer to these questions is 1164``yes''. 1165 1166Some users try to use @code{__STDC__} to check for the availability of 1167certain library facilities. This is actually incorrect usage in an ISO 1168C program, because the ISO C standard says that a conforming 1169freestanding implementation should define @code{__STDC__} even though it 1170does not have the library facilities. @samp{gcc -ansi -pedantic} is a 1171conforming freestanding implementation, and it is therefore required to 1172define @code{__STDC__}, even though it does not come with an ISO C 1173library. 1174 1175Sometimes people say that defining @code{__STDC__} in a compiler that 1176does not completely conform to the ISO C standard somehow violates the 1177standard. This is illogical. The standard is a standard for compilers 1178that claim to support ISO C, such as @samp{gcc -ansi}---not for other 1179compilers such as plain @command{gcc}. Whatever the ISO C standard says 1180is relevant to the design of plain @command{gcc} without @option{-ansi} only 1181for pragmatic reasons, not as a requirement. 1182 1183GCC normally defines @code{__STDC__} to be 1, and in addition 1184defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option, 1185or a @option{-std} option for strict conformance to some version of ISO C@. 1186On some hosts, system include files use a different convention, where 1187@code{__STDC__} is normally 0, but is 1 if the user specifies strict 1188conformance to the C Standard. GCC follows the host convention when 1189processing system include files, but when processing user files it follows 1190the usual GNU C convention. 1191 1192@item 1193Undefining @code{__STDC__} in C++. 1194 1195Programs written to compile with C++-to-C translators get the 1196value of @code{__STDC__} that goes with the C compiler that is 1197subsequently used. These programs must test @code{__STDC__} 1198to determine what kind of C preprocessor that compiler uses: 1199whether they should concatenate tokens in the ISO C fashion 1200or in the traditional fashion. 1201 1202These programs work properly with GNU C++ if @code{__STDC__} is defined. 1203They would not work otherwise. 1204 1205In addition, many header files are written to provide prototypes in ISO 1206C but not in traditional C@. Many of these header files can work without 1207change in C++ provided @code{__STDC__} is defined. If @code{__STDC__} 1208is not defined, they will all fail, and will all need to be changed to 1209test explicitly for C++ as well. 1210 1211@item 1212Deleting ``empty'' loops. 1213 1214Historically, GCC has not deleted ``empty'' loops under the 1215assumption that the most likely reason you would put one in a program is 1216to have a delay, so deleting them will not make real programs run any 1217faster. 1218 1219However, the rationale here is that optimization of a nonempty loop 1220cannot produce an empty one. This held for carefully written C compiled 1221with less powerful optimizers but is not always the case for carefully 1222written C++ or with more powerful optimizers. 1223Thus GCC will remove operations from loops whenever it can determine 1224those operations are not externally visible (apart from the time taken 1225to execute them, of course). In case the loop can be proved to be finite, 1226GCC will also remove the loop itself. 1227 1228Be aware of this when performing timing tests, for instance the 1229following loop can be completely removed, provided 1230@code{some_expression} can provably not change any global state. 1231 1232@smallexample 1233@{ 1234 int sum = 0; 1235 int ix; 1236 1237 for (ix = 0; ix != 10000; ix++) 1238 sum += some_expression; 1239@} 1240@end smallexample 1241 1242Even though @code{sum} is accumulated in the loop, no use is made of 1243that summation, so the accumulation can be removed. 1244 1245@item 1246Making side effects happen in the same order as in some other compiler. 1247 1248@cindex side effects, order of evaluation 1249@cindex order of evaluation, side effects 1250It is never safe to depend on the order of evaluation of side effects. 1251For example, a function call like this may very well behave differently 1252from one compiler to another: 1253 1254@smallexample 1255void func (int, int); 1256 1257int i = 2; 1258func (i++, i++); 1259@end smallexample 1260 1261There is no guarantee (in either the C or the C++ standard language 1262definitions) that the increments will be evaluated in any particular 1263order. Either increment might happen first. @code{func} might get the 1264arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}. 1265 1266@item 1267Making certain warnings into errors by default. 1268 1269Some ISO C testsuites report failure when the compiler does not produce 1270an error message for a certain program. 1271 1272@opindex pedantic-errors 1273ISO C requires a ``diagnostic'' message for certain kinds of invalid 1274programs, but a warning is defined by GCC to count as a diagnostic. If 1275GCC produces a warning but not an error, that is correct ISO C support. 1276If testsuites call this ``failure'', they should be run with the GCC 1277option @option{-pedantic-errors}, which will turn these warnings into 1278errors. 1279 1280@end itemize 1281 1282@node Warnings and Errors 1283@section Warning Messages and Error Messages 1284 1285@cindex error messages 1286@cindex warnings vs errors 1287@cindex messages, warning and error 1288The GNU compiler can produce two kinds of diagnostics: errors and 1289warnings. Each kind has a different purpose: 1290 1291@itemize @w{} 1292@item 1293@dfn{Errors} report problems that make it impossible to compile your 1294program. GCC reports errors with the source file name and line 1295number where the problem is apparent. 1296 1297@item 1298@dfn{Warnings} report other unusual conditions in your code that 1299@emph{may} indicate a problem, although compilation can (and does) 1300proceed. Warning messages also report the source file name and line 1301number, but include the text @samp{warning:} to distinguish them 1302from error messages. 1303@end itemize 1304 1305Warnings may indicate danger points where you should check to make sure 1306that your program really does what you intend; or the use of obsolete 1307features; or the use of nonstandard features of GNU C or C++. Many 1308warnings are issued only if you ask for them, with one of the @option{-W} 1309options (for instance, @option{-Wall} requests a variety of useful 1310warnings). 1311 1312@opindex pedantic 1313@opindex pedantic-errors 1314GCC always tries to compile your program if possible; it never 1315gratuitously rejects a program whose meaning is clear merely because 1316(for instance) it fails to conform to a standard. In some cases, 1317however, the C and C++ standards specify that certain extensions are 1318forbidden, and a diagnostic @emph{must} be issued by a conforming 1319compiler. The @option{-pedantic} option tells GCC to issue warnings in 1320such cases; @option{-pedantic-errors} says to make them errors instead. 1321This does not mean that @emph{all} non-ISO constructs get warnings 1322or errors. 1323 1324@xref{Warning Options,,Options to Request or Suppress Warnings}, for 1325more detail on these and related command-line options. 1326