diff options
Diffstat (limited to 'gcc-4.2.1-5666.3/gcc/doc/trouble.texi')
| -rw-r--r-- | gcc-4.2.1-5666.3/gcc/doc/trouble.texi | 1329 |
1 files changed, 0 insertions, 1329 deletions
diff --git a/gcc-4.2.1-5666.3/gcc/doc/trouble.texi b/gcc-4.2.1-5666.3/gcc/doc/trouble.texi deleted file mode 100644 index ade026d51..000000000 --- a/gcc-4.2.1-5666.3/gcc/doc/trouble.texi +++ /dev/null @@ -1,1329 +0,0 @@ -@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -@c 1999, 2000, 2001, 2003, 2004 Free Software Foundation, Inc. -@c This is part of the GCC manual. -@c For copying conditions, see the file gcc.texi. - -@node Trouble -@chapter Known Causes of Trouble with GCC -@cindex bugs, known -@cindex installation trouble -@cindex known causes of trouble - -This section describes known problems that affect users of GCC@. Most -of these are not GCC bugs per se---if they were, we would fix them. -But the result for a user may be like the result of a bug. - -Some of these problems are due to bugs in other software, some are -missing features that are too much work to add, and some are places -where people's opinions differ as to what is best. - -@menu -* Actual Bugs:: Bugs we will fix later. -* Cross-Compiler Problems:: Common problems of cross compiling with GCC. -* Interoperation:: Problems using GCC with other compilers, - and with certain linkers, assemblers and debuggers. -* Incompatibilities:: GCC is incompatible with traditional C. -* Fixed Headers:: GCC uses corrected versions of system header files. - This is necessary, but doesn't always work smoothly. -* Standard Libraries:: GCC uses the system C library, which might not be - compliant with the ISO C standard. -* Disappointments:: Regrettable things we can't change, but not quite bugs. -* C++ Misunderstandings:: Common misunderstandings with GNU C++. -* Protoize Caveats:: Things to watch out for when using @code{protoize}. -* Non-bugs:: Things we think are right, but some others disagree. -* Warnings and Errors:: Which problems in your code get warnings, - and which get errors. -@end menu - -@node Actual Bugs -@section Actual Bugs We Haven't Fixed Yet - -@itemize @bullet -@item -The @code{fixincludes} script interacts badly with automounters; if the -directory of system header files is automounted, it tends to be -unmounted while @code{fixincludes} is running. This would seem to be a -bug in the automounter. We don't know any good way to work around it. - -@item -The @code{fixproto} script will sometimes add prototypes for the -@code{sigsetjmp} and @code{siglongjmp} functions that reference the -@code{jmp_buf} type before that type is defined. To work around this, -edit the offending file and place the typedef in front of the -prototypes. -@end itemize - -@node Cross-Compiler Problems -@section Cross-Compiler Problems - -You may run into problems with cross compilation on certain machines, -for several reasons. - -@itemize @bullet -@item -At present, the program @file{mips-tfile} which adds debug -support to object files on MIPS systems does not work in a cross -compile environment. -@end itemize - -@node Interoperation -@section Interoperation - -This section lists various difficulties encountered in using GCC -together with other compilers or with the assemblers, linkers, -libraries and debuggers on certain systems. - -@itemize @bullet -@item -On many platforms, GCC supports a different ABI for C++ than do other -compilers, so the object files compiled by GCC cannot be used with object -files generated by another C++ compiler. - -An area where the difference is most apparent is name mangling. The use -of different name mangling is intentional, to protect you from more subtle -problems. -Compilers differ as to many internal details of C++ implementation, -including: how class instances are laid out, how multiple inheritance is -implemented, and how virtual function calls are handled. If the name -encoding were made the same, your programs would link against libraries -provided from other compilers---but the programs would then crash when -run. Incompatible libraries are then detected at link time, rather than -at run time. - -@item -On some BSD systems, including some versions of Ultrix, use of profiling -causes static variable destructors (currently used only in C++) not to -be run. - -@item -On some SGI systems, when you use @option{-lgl_s} as an option, -it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}. -Naturally, this does not happen when you use GCC@. -You must specify all three options explicitly. - -@item -On a SPARC, GCC aligns all values of type @code{double} on an 8-byte -boundary, and it expects every @code{double} to be so aligned. The Sun -compiler usually gives @code{double} values 8-byte alignment, with one -exception: function arguments of type @code{double} may not be aligned. - -As a result, if a function compiled with Sun CC takes the address of an -argument of type @code{double} and passes this pointer of type -@code{double *} to a function compiled with GCC, dereferencing the -pointer may cause a fatal signal. - -One way to solve this problem is to compile your entire program with GCC@. -Another solution is to modify the function that is compiled with -Sun CC to copy the argument into a local variable; local variables -are always properly aligned. A third solution is to modify the function -that uses the pointer to dereference it via the following function -@code{access_double} instead of directly with @samp{*}: - -@smallexample -inline double -access_double (double *unaligned_ptr) -@{ - union d2i @{ double d; int i[2]; @}; - - union d2i *p = (union d2i *) unaligned_ptr; - union d2i u; - - u.i[0] = p->i[0]; - u.i[1] = p->i[1]; - - return u.d; -@} -@end smallexample - -@noindent -Storing into the pointer can be done likewise with the same union. - -@item -On Solaris, the @code{malloc} function in the @file{libmalloc.a} library -may allocate memory that is only 4 byte aligned. Since GCC on the -SPARC assumes that doubles are 8 byte aligned, this may result in a -fatal signal if doubles are stored in memory allocated by the -@file{libmalloc.a} library. - -The solution is to not use the @file{libmalloc.a} library. Use instead -@code{malloc} and related functions from @file{libc.a}; they do not have -this problem. - -@item -On the HP PA machine, ADB sometimes fails to work on functions compiled -with GCC@. Specifically, it fails to work on functions that use -@code{alloca} or variable-size arrays. This is because GCC doesn't -generate HP-UX unwind descriptors for such functions. It may even be -impossible to generate them. - -@item -Debugging (@option{-g}) is not supported on the HP PA machine, unless you use -the preliminary GNU tools. - -@item -Taking the address of a label may generate errors from the HP-UX -PA assembler. GAS for the PA does not have this problem. - -@item -Using floating point parameters for indirect calls to static functions -will not work when using the HP assembler. There simply is no way for GCC -to specify what registers hold arguments for static functions when using -the HP assembler. GAS for the PA does not have this problem. - -@item -In extremely rare cases involving some very large functions you may -receive errors from the HP linker complaining about an out of bounds -unconditional branch offset. This used to occur more often in previous -versions of GCC, but is now exceptionally rare. If you should run -into it, you can work around by making your function smaller. - -@item -GCC compiled code sometimes emits warnings from the HP-UX assembler of -the form: - -@smallexample -(warning) Use of GR3 when - frame >= 8192 may cause conflict. -@end smallexample - -These warnings are harmless and can be safely ignored. - -@item -In extremely rare cases involving some very large functions you may -receive errors from the AIX Assembler complaining about a displacement -that is too large. If you should run into it, you can work around by -making your function smaller. - -@item -The @file{libstdc++.a} library in GCC relies on the SVR4 dynamic -linker semantics which merges global symbols between libraries and -applications, especially necessary for C++ streams functionality. -This is not the default behavior of AIX shared libraries and dynamic -linking. @file{libstdc++.a} is built on AIX with ``runtime-linking'' -enabled so that symbol merging can occur. To utilize this feature, -the application linked with @file{libstdc++.a} must include the -@option{-Wl,-brtl} flag on the link line. G++ cannot impose this -because this option may interfere with the semantics of the user -program and users may not always use @samp{g++} to link his or her -application. Applications are not required to use the -@option{-Wl,-brtl} flag on the link line---the rest of the -@file{libstdc++.a} library which is not dependent on the symbol -merging semantics will continue to function correctly. - -@item -An application can interpose its own definition of functions for -functions invoked by @file{libstdc++.a} with ``runtime-linking'' -enabled on AIX@. To accomplish this the application must be linked -with ``runtime-linking'' option and the functions explicitly must be -exported by the application (@option{-Wl,-brtl,-bE:exportfile}). - -@item -AIX on the RS/6000 provides support (NLS) for environments outside of -the United States. Compilers and assemblers use NLS to support -locale-specific representations of various objects including -floating-point numbers (@samp{.} vs @samp{,} for separating decimal -fractions). There have been problems reported where the library linked -with GCC does not produce the same floating-point formats that the -assembler accepts. If you have this problem, set the @env{LANG} -environment variable to @samp{C} or @samp{En_US}. - -@item -@opindex fdollars-in-identifiers -Even if you specify @option{-fdollars-in-identifiers}, -you cannot successfully use @samp{$} in identifiers on the RS/6000 due -to a restriction in the IBM assembler. GAS supports these -identifiers. - -@cindex VAX calling convention -@cindex Ultrix calling convention -@item -@opindex fcall-saved -On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved -by function calls. However, the C compiler uses conventions compatible -with BSD Unix: registers 2 through 5 may be clobbered by function calls. - -GCC uses the same convention as the Ultrix C compiler. You can use -these options to produce code compatible with the Fortran compiler: - -@smallexample --fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5 -@end smallexample -@end itemize - -@node Incompatibilities -@section Incompatibilities of GCC -@cindex incompatibilities of GCC -@opindex traditional - -There are several noteworthy incompatibilities between GNU C and K&R -(non-ISO) versions of C@. - -@itemize @bullet -@cindex string constants -@cindex read-only strings -@cindex shared strings -@item -GCC normally makes string constants read-only. If several -identical-looking string constants are used, GCC stores only one -copy of the string. - -@cindex @code{mktemp}, and constant strings -One consequence is that you cannot call @code{mktemp} with a string -constant argument. The function @code{mktemp} always alters the -string its argument points to. - -@cindex @code{sscanf}, and constant strings -@cindex @code{fscanf}, and constant strings -@cindex @code{scanf}, and constant strings -@c APPLE LOCAL begin fwritable strings. -Another consequence is that @code{sscanf} does not work on some systems -when passed a string constant as its format control string or input. -This is because @code{sscanf} incorrectly tries to write into the string -constant. Likewise @code{fscanf} and @code{scanf}. - -@opindex fwritable-strings -The best solution to these problems is to change the program to use -@code{char}-array variables with initialization strings for these -purposes instead of string constants. But if this is not possible, -you can use the @option{-fwritable-strings} flag, which directs GCC -to handle string constants the same way most C compilers do. -@c APPLE LOCAL end fwritable strings. -@item -@code{-2147483648} is positive. - -This is because 2147483648 cannot fit in the type @code{int}, so -(following the ISO C rules) its data type is @code{unsigned long int}. -Negating this value yields 2147483648 again. - -@item -GCC does not substitute macro arguments when they appear inside of -string constants. For example, the following macro in GCC - -@smallexample -#define foo(a) "a" -@end smallexample - -@noindent -will produce output @code{"a"} regardless of what the argument @var{a} is. - -@cindex @code{setjmp} incompatibilities -@cindex @code{longjmp} incompatibilities -@item -When you use @code{setjmp} and @code{longjmp}, the only automatic -variables guaranteed to remain valid are those declared -@code{volatile}. This is a consequence of automatic register -allocation. Consider this function: - -@smallexample -jmp_buf j; - -foo () -@{ - int a, b; - - a = fun1 (); - if (setjmp (j)) - return a; - - a = fun2 (); - /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */ - return a + fun3 (); -@} -@end smallexample - -Here @code{a} may or may not be restored to its first value when the -@code{longjmp} occurs. If @code{a} is allocated in a register, then -its first value is restored; otherwise, it keeps the last value stored -in it. - -@opindex W -If you use the @option{-W} option with the @option{-O} option, you will -get a warning when GCC thinks such a problem might be possible. - -@item -Programs that use preprocessing directives in the middle of macro -arguments do not work with GCC@. For example, a program like this -will not work: - -@smallexample -@group -foobar ( -#define luser - hack) -@end group -@end smallexample - -ISO C does not permit such a construct. - -@item -K&R compilers allow comments to cross over an inclusion boundary -(i.e.@: started in an include file and ended in the including file). - -@cindex external declaration scope -@cindex scope of external declarations -@cindex declaration scope -@item -Declarations of external variables and functions within a block apply -only to the block containing the declaration. In other words, they -have the same scope as any other declaration in the same place. - -In some other C compilers, a @code{extern} declaration affects all the -rest of the file even if it happens within a block. - -@item -In traditional C, you can combine @code{long}, etc., with a typedef name, -as shown here: - -@smallexample -typedef int foo; -typedef long foo bar; -@end smallexample - -In ISO C, this is not allowed: @code{long} and other type modifiers -require an explicit @code{int}. - -@cindex typedef names as function parameters -@item -PCC allows typedef names to be used as function parameters. - -@item -Traditional C allows the following erroneous pair of declarations to -appear together in a given scope: - -@smallexample -typedef int foo; -typedef foo foo; -@end smallexample - -@item -GCC treats all characters of identifiers as significant. According to -K&R-1 (2.2), ``No more than the first eight characters are significant, -although more may be used.''. Also according to K&R-1 (2.2), ``An -identifier is a sequence of letters and digits; the first character must -be a letter. The underscore _ counts as a letter.'', but GCC also -allows dollar signs in identifiers. - -@cindex whitespace -@item -PCC allows whitespace in the middle of compound assignment operators -such as @samp{+=}. GCC, following the ISO standard, does not -allow this. - -@cindex apostrophes -@cindex ' -@item -GCC complains about unterminated character constants inside of -preprocessing conditionals that fail. Some programs have English -comments enclosed in conditionals that are guaranteed to fail; if these -comments contain apostrophes, GCC will probably report an error. For -example, this code would produce an error: - -@smallexample -#if 0 -You can't expect this to work. -#endif -@end smallexample - -The best solution to such a problem is to put the text into an actual -C comment delimited by @samp{/*@dots{}*/}. - -@item -Many user programs contain the declaration @samp{long time ();}. In the -past, the system header files on many systems did not actually declare -@code{time}, so it did not matter what type your program declared it to -return. But in systems with ISO C headers, @code{time} is declared to -return @code{time_t}, and if that is not the same as @code{long}, then -@samp{long time ();} is erroneous. - -The solution is to change your program to use appropriate system headers -(@code{<time.h>} on systems with ISO C headers) and not to declare -@code{time} if the system header files declare it, or failing that to -use @code{time_t} as the return type of @code{time}. - -@cindex @code{float} as function value type -@item -When compiling functions that return @code{float}, PCC converts it to -a double. GCC actually returns a @code{float}. If you are concerned -with PCC compatibility, you should declare your functions to return -@code{double}; you might as well say what you mean. - -@cindex structures -@cindex unions -@item -When compiling functions that return structures or unions, GCC -output code normally uses a method different from that used on most -versions of Unix. As a result, code compiled with GCC cannot call -a structure-returning function compiled with PCC, and vice versa. - -The method used by GCC is as follows: a structure or union which is -1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union -with any other size is stored into an address supplied by the caller -(usually in a special, fixed register, but on some machines it is passed -on the stack). The target hook @code{TARGET_STRUCT_VALUE_RTX} -tells GCC where to pass this address. - -By contrast, PCC on most target machines returns structures and unions -of any size by copying the data into an area of static storage, and then -returning the address of that storage as if it were a pointer value. -The caller must copy the data from that memory area to the place where -the value is wanted. GCC does not use this method because it is -slower and nonreentrant. - -On some newer machines, PCC uses a reentrant convention for all -structure and union returning. GCC on most of these machines uses a -compatible convention when returning structures and unions in memory, -but still returns small structures and unions in registers. - -@opindex fpcc-struct-return -You can tell GCC to use a compatible convention for all structure and -union returning with the option @option{-fpcc-struct-return}. - -@cindex preprocessing tokens -@cindex preprocessing numbers -@item -GCC complains about program fragments such as @samp{0x74ae-0x4000} -which appear to be two hexadecimal constants separated by the minus -operator. Actually, this string is a single @dfn{preprocessing token}. -Each such token must correspond to one token in C@. Since this does not, -GCC prints an error message. Although it may appear obvious that what -is meant is an operator and two values, the ISO C standard specifically -requires that this be treated as erroneous. - -A @dfn{preprocessing token} is a @dfn{preprocessing number} if it -begins with a digit and is followed by letters, underscores, digits, -periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+}, -@samp{p-}, @samp{P+}, or @samp{P-} character sequences. (In strict C89 -mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot -appear in preprocessing numbers.) - -To make the above program fragment valid, place whitespace in front of -the minus sign. This whitespace will end the preprocessing number. -@end itemize - -@node Fixed Headers -@section Fixed Header Files - -GCC needs to install corrected versions of some system header files. -This is because most target systems have some header files that won't -work with GCC unless they are changed. Some have bugs, some are -incompatible with ISO C, and some depend on special features of other -compilers. - -Installing GCC automatically creates and installs the fixed header -files, by running a program called @code{fixincludes}. Normally, you -don't need to pay attention to this. But there are cases where it -doesn't do the right thing automatically. - -@itemize @bullet -@item -If you update the system's header files, such as by installing a new -system version, the fixed header files of GCC are not automatically -updated. They can be updated using the @command{mkheaders} script -installed in -@file{@var{libexecdir}/gcc/@var{target}/@var{version}/install-tools/}. - -@item -On some systems, header file directories contain -machine-specific symbolic links in certain places. This makes it -possible to share most of the header files among hosts running the -same version of the system on different machine models. - -The programs that fix the header files do not understand this special -way of using symbolic links; therefore, the directory of fixed header -files is good only for the machine model used to build it. - -It is possible to make separate sets of fixed header files for the -different machine models, and arrange a structure of symbolic links so -as to use the proper set, but you'll have to do this by hand. -@end itemize - -@node Standard Libraries -@section Standard Libraries - -@opindex Wall -GCC by itself attempts to be a conforming freestanding implementation. -@xref{Standards,,Language Standards Supported by GCC}, for details of -what this means. Beyond the library facilities required of such an -implementation, the rest of the C library is supplied by the vendor of -the operating system. If that C library doesn't conform to the C -standards, then your programs might get warnings (especially when using -@option{-Wall}) that you don't expect. - -For example, the @code{sprintf} function on SunOS 4.1.3 returns -@code{char *} while the C standard says that @code{sprintf} returns an -@code{int}. The @code{fixincludes} program could make the prototype for -this function match the Standard, but that would be wrong, since the -function will still return @code{char *}. - -If you need a Standard compliant library, then you need to find one, as -GCC does not provide one. The GNU C library (called @code{glibc}) -provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for -GNU/Linux and HURD-based GNU systems; no recent version of it supports -other systems, though some very old versions did. Version 2.2 of the -GNU C library includes nearly complete C99 support. You could also ask -your operating system vendor if newer libraries are available. - -@node Disappointments -@section Disappointments and Misunderstandings - -These problems are perhaps regrettable, but we don't know any practical -way around them. - -@itemize @bullet -@item -Certain local variables aren't recognized by debuggers when you compile -with optimization. - -This occurs because sometimes GCC optimizes the variable out of -existence. There is no way to tell the debugger how to compute the -value such a variable ``would have had'', and it is not clear that would -be desirable anyway. So GCC simply does not mention the eliminated -variable when it writes debugging information. - -You have to expect a certain amount of disagreement between the -executable and your source code, when you use optimization. - -@cindex conflicting types -@cindex scope of declaration -@item -Users often think it is a bug when GCC reports an error for code -like this: - -@smallexample -int foo (struct mumble *); - -struct mumble @{ @dots{} @}; - -int foo (struct mumble *x) -@{ @dots{} @} -@end smallexample - -This code really is erroneous, because the scope of @code{struct -mumble} in the prototype is limited to the argument list containing it. -It does not refer to the @code{struct mumble} defined with file scope -immediately below---they are two unrelated types with similar names in -different scopes. - -But in the definition of @code{foo}, the file-scope type is used -because that is available to be inherited. Thus, the definition and -the prototype do not match, and you get an error. - -This behavior may seem silly, but it's what the ISO standard specifies. -It is easy enough for you to make your code work by moving the -definition of @code{struct mumble} above the prototype. It's not worth -being incompatible with ISO C just to avoid an error for the example -shown above. - -@item -Accesses to bit-fields even in volatile objects works by accessing larger -objects, such as a byte or a word. You cannot rely on what size of -object is accessed in order to read or write the bit-field; it may even -vary for a given bit-field according to the precise usage. - -If you care about controlling the amount of memory that is accessed, use -volatile but do not use bit-fields. - -@item -GCC comes with shell scripts to fix certain known problems in system -header files. They install corrected copies of various header files in -a special directory where only GCC will normally look for them. The -scripts adapt to various systems by searching all the system header -files for the problem cases that we know about. - -If new system header files are installed, nothing automatically arranges -to update the corrected header files. They can be updated using the -@command{mkheaders} script installed in -@file{@var{libexecdir}/gcc/@var{target}/@var{version}/install-tools/}. - -@item -@cindex floating point precision -On 68000 and x86 systems, for instance, you can get paradoxical results -if you test the precise values of floating point numbers. For example, -you can find that a floating point value which is not a NaN is not equal -to itself. This results from the fact that the floating point registers -hold a few more bits of precision than fit in a @code{double} in memory. -Compiled code moves values between memory and floating point registers -at its convenience, and moving them into memory truncates them. - -@opindex ffloat-store -You can partially avoid this problem by using the @option{-ffloat-store} -option (@pxref{Optimize Options}). - -@item -On AIX and other platforms without weak symbol support, templates -need to be instantiated explicitly and symbols for static members -of templates will not be generated. - -@item -On AIX, GCC scans object files and library archives for static -constructors and destructors when linking an application before the -linker prunes unreferenced symbols. This is necessary to prevent the -AIX linker from mistakenly assuming that static constructor or -destructor are unused and removing them before the scanning can occur. -All static constructors and destructors found will be referenced even -though the modules in which they occur may not be used by the program. -This may lead to both increased executable size and unexpected symbol -references. -@end itemize - -@node C++ Misunderstandings -@section Common Misunderstandings with GNU C++ - -@cindex misunderstandings in C++ -@cindex surprises in C++ -@cindex C++ misunderstandings -C++ is a complex language and an evolving one, and its standard -definition (the ISO C++ standard) was only recently completed. As a -result, your C++ compiler may occasionally surprise you, even when its -behavior is correct. This section discusses some areas that frequently -give rise to questions of this sort. - -@menu -* Static Definitions:: Static member declarations are not definitions -* Name lookup:: Name lookup, templates, and accessing members of base classes -* Temporaries:: Temporaries may vanish before you expect -* Copy Assignment:: Copy Assignment operators copy virtual bases twice -@end menu - -@node Static Definitions -@subsection Declare @emph{and} Define Static Members - -@cindex C++ static data, declaring and defining -@cindex static data in C++, declaring and defining -@cindex declaring static data in C++ -@cindex defining static data in C++ -When a class has static data members, it is not enough to @emph{declare} -the static member; you must also @emph{define} it. For example: - -@smallexample -class Foo -@{ - @dots{} - void method(); - static int bar; -@}; -@end smallexample - -This declaration only establishes that the class @code{Foo} has an -@code{int} named @code{Foo::bar}, and a member function named -@code{Foo::method}. But you still need to define @emph{both} -@code{method} and @code{bar} elsewhere. According to the ISO -standard, you must supply an initializer in one (and only one) source -file, such as: - -@smallexample -int Foo::bar = 0; -@end smallexample - -Other C++ compilers may not correctly implement the standard behavior. -As a result, when you switch to @command{g++} from one of these compilers, -you may discover that a program that appeared to work correctly in fact -does not conform to the standard: @command{g++} reports as undefined -symbols any static data members that lack definitions. - - -@node Name lookup -@subsection Name lookup, templates, and accessing members of base classes - -@cindex base class members -@cindex two-stage name lookup -@cindex dependent name lookup - -The C++ standard prescribes that all names that are not dependent on -template parameters are bound to their present definitions when parsing -a template function or class.@footnote{The C++ standard just uses the -term ``dependent'' for names that depend on the type or value of -template parameters. This shorter term will also be used in the rest of -this section.} Only names that are dependent are looked up at the point -of instantiation. For example, consider - -@smallexample - void foo(double); - - struct A @{ - template <typename T> - void f () @{ - foo (1); // @r{1} - int i = N; // @r{2} - T t; - t.bar(); // @r{3} - foo (t); // @r{4} - @} - - static const int N; - @}; -@end smallexample - -Here, the names @code{foo} and @code{N} appear in a context that does -not depend on the type of @code{T}. The compiler will thus require that -they are defined in the context of use in the template, not only before -the point of instantiation, and will here use @code{::foo(double)} and -@code{A::N}, respectively. In particular, it will convert the integer -value to a @code{double} when passing it to @code{::foo(double)}. - -Conversely, @code{bar} and the call to @code{foo} in the fourth marked -line are used in contexts that do depend on the type of @code{T}, so -they are only looked up at the point of instantiation, and you can -provide declarations for them after declaring the template, but before -instantiating it. In particular, if you instantiate @code{A::f<int>}, -the last line will call an overloaded @code{::foo(int)} if one was -provided, even if after the declaration of @code{struct A}. - -This distinction between lookup of dependent and non-dependent names is -called two-stage (or dependent) name lookup. G++ implements it -since version 3.4. - -Two-stage name lookup sometimes leads to situations with behavior -different from non-template codes. The most common is probably this: - -@smallexample - template <typename T> struct Base @{ - int i; - @}; - - template <typename T> struct Derived : public Base<T> @{ - int get_i() @{ return i; @} - @}; -@end smallexample - -In @code{get_i()}, @code{i} is not used in a dependent context, so the -compiler will look for a name declared at the enclosing namespace scope -(which is the global scope here). It will not look into the base class, -since that is dependent and you may declare specializations of -@code{Base} even after declaring @code{Derived}, so the compiler can't -really know what @code{i} would refer to. If there is no global -variable @code{i}, then you will get an error message. - -In order to make it clear that you want the member of the base class, -you need to defer lookup until instantiation time, at which the base -class is known. For this, you need to access @code{i} in a dependent -context, by either using @code{this->i} (remember that @code{this} is of -type @code{Derived<T>*}, so is obviously dependent), or using -@code{Base<T>::i}. Alternatively, @code{Base<T>::i} might be brought -into scope by a @code{using}-declaration. - -Another, similar example involves calling member functions of a base -class: - -@smallexample - template <typename T> struct Base @{ - int f(); - @}; - - template <typename T> struct Derived : Base<T> @{ - int g() @{ return f(); @}; - @}; -@end smallexample - -Again, the call to @code{f()} is not dependent on template arguments -(there are no arguments that depend on the type @code{T}, and it is also -not otherwise specified that the call should be in a dependent context). -Thus a global declaration of such a function must be available, since -the one in the base class is not visible until instantiation time. The -compiler will consequently produce the following error message: - -@smallexample - x.cc: In member function `int Derived<T>::g()': - x.cc:6: error: there are no arguments to `f' that depend on a template - parameter, so a declaration of `f' must be available - x.cc:6: error: (if you use `-fpermissive', G++ will accept your code, but - allowing the use of an undeclared name is deprecated) -@end smallexample - -To make the code valid either use @code{this->f()}, or -@code{Base<T>::f()}. Using the @option{-fpermissive} flag will also let -the compiler accept the code, by marking all function calls for which no -declaration is visible at the time of definition of the template for -later lookup at instantiation time, as if it were a dependent call. -We do not recommend using @option{-fpermissive} to work around invalid -code, and it will also only catch cases where functions in base classes -are called, not where variables in base classes are used (as in the -example above). - -Note that some compilers (including G++ versions prior to 3.4) get these -examples wrong and accept above code without an error. Those compilers -do not implement two-stage name lookup correctly. - - -@node Temporaries -@subsection Temporaries May Vanish Before You Expect - -@cindex temporaries, lifetime of -@cindex portions of temporary objects, pointers to -It is dangerous to use pointers or references to @emph{portions} of a -temporary object. The compiler may very well delete the object before -you expect it to, leaving a pointer to garbage. The most common place -where this problem crops up is in classes like string classes, -especially ones that define a conversion function to type @code{char *} -or @code{const char *}---which is one reason why the standard -@code{string} class requires you to call the @code{c_str} member -function. However, any class that returns a pointer to some internal -structure is potentially subject to this problem. - -For example, a program may use a function @code{strfunc} that returns -@code{string} objects, and another function @code{charfunc} that -operates on pointers to @code{char}: - -@smallexample -string strfunc (); -void charfunc (const char *); - -void -f () -@{ - const char *p = strfunc().c_str(); - @dots{} - charfunc (p); - @dots{} - charfunc (p); -@} -@end smallexample - -@noindent -In this situation, it may seem reasonable to save a pointer to the C -string returned by the @code{c_str} member function and use that rather -than call @code{c_str} repeatedly. However, the temporary string -created by the call to @code{strfunc} is destroyed after @code{p} is -initialized, at which point @code{p} is left pointing to freed memory. - -Code like this may run successfully under some other compilers, -particularly obsolete cfront-based compilers that delete temporaries -along with normal local variables. However, the GNU C++ behavior is -standard-conforming, so if your program depends on late destruction of -temporaries it is not portable. - -The safe way to write such code is to give the temporary a name, which -forces it to remain until the end of the scope of the name. For -example: - -@smallexample -const string& tmp = strfunc (); -charfunc (tmp.c_str ()); -@end smallexample - -@node Copy Assignment -@subsection Implicit Copy-Assignment for Virtual Bases - -When a base class is virtual, only one subobject of the base class -belongs to each full object. Also, the constructors and destructors are -invoked only once, and called from the most-derived class. However, such -objects behave unspecified when being assigned. For example: - -@smallexample -struct Base@{ - char *name; - Base(char *n) : name(strdup(n))@{@} - Base& operator= (const Base& other)@{ - free (name); - name = strdup (other.name); - @} -@}; - -struct A:virtual Base@{ - int val; - A():Base("A")@{@} -@}; - -struct B:virtual Base@{ - int bval; - B():Base("B")@{@} -@}; - -struct Derived:public A, public B@{ - Derived():Base("Derived")@{@} -@}; - -void func(Derived &d1, Derived &d2) -@{ - d1 = d2; -@} -@end smallexample - -The C++ standard specifies that @samp{Base::Base} is only called once -when constructing or copy-constructing a Derived object. It is -unspecified whether @samp{Base::operator=} is called more than once when -the implicit copy-assignment for Derived objects is invoked (as it is -inside @samp{func} in the example). - -G++ implements the ``intuitive'' algorithm for copy-assignment: assign all -direct bases, then assign all members. In that algorithm, the virtual -base subobject can be encountered more than once. In the example, copying -proceeds in the following order: @samp{val}, @samp{name} (via -@code{strdup}), @samp{bval}, and @samp{name} again. - -If application code relies on copy-assignment, a user-defined -copy-assignment operator removes any uncertainties. With such an -operator, the application can define whether and how the virtual base -subobject is assigned. - -@node Protoize Caveats -@section Caveats of using @command{protoize} - -The conversion programs @command{protoize} and @command{unprotoize} can -sometimes change a source file in a way that won't work unless you -rearrange it. - -@itemize @bullet -@item -@command{protoize} can insert references to a type name or type tag before -the definition, or in a file where they are not defined. - -If this happens, compiler error messages should show you where the new -references are, so fixing the file by hand is straightforward. - -@item -There are some C constructs which @command{protoize} cannot figure out. -For example, it can't determine argument types for declaring a -pointer-to-function variable; this you must do by hand. @command{protoize} -inserts a comment containing @samp{???} each time it finds such a -variable; so you can find all such variables by searching for this -string. ISO C does not require declaring the argument types of -pointer-to-function types. - -@item -Using @command{unprotoize} can easily introduce bugs. If the program -relied on prototypes to bring about conversion of arguments, these -conversions will not take place in the program without prototypes. -One case in which you can be sure @command{unprotoize} is safe is when -you are removing prototypes that were made with @command{protoize}; if -the program worked before without any prototypes, it will work again -without them. - -@opindex Wconversion -You can find all the places where this problem might occur by compiling -the program with the @option{-Wconversion} option. It prints a warning -whenever an argument is converted. - -@item -Both conversion programs can be confused if there are macro calls in and -around the text to be converted. In other words, the standard syntax -for a declaration or definition must not result from expanding a macro. -This problem is inherent in the design of C and cannot be fixed. If -only a few functions have confusing macro calls, you can easily convert -them manually. - -@item -@command{protoize} cannot get the argument types for a function whose -definition was not actually compiled due to preprocessing conditionals. -When this happens, @command{protoize} changes nothing in regard to such -a function. @command{protoize} tries to detect such instances and warn -about them. - -You can generally work around this problem by using @command{protoize} step -by step, each time specifying a different set of @option{-D} options for -compilation, until all of the functions have been converted. There is -no automatic way to verify that you have got them all, however. - -@item -Confusion may result if there is an occasion to convert a function -declaration or definition in a region of source code where there is more -than one formal parameter list present. Thus, attempts to convert code -containing multiple (conditionally compiled) versions of a single -function header (in the same vicinity) may not produce the desired (or -expected) results. - -If you plan on converting source files which contain such code, it is -recommended that you first make sure that each conditionally compiled -region of source code which contains an alternative function header also -contains at least one additional follower token (past the final right -parenthesis of the function header). This should circumvent the -problem. - -@item -@command{unprotoize} can become confused when trying to convert a function -definition or declaration which contains a declaration for a -pointer-to-function formal argument which has the same name as the -function being defined or declared. We recommend you avoid such choices -of formal parameter names. - -@item -You might also want to correct some of the indentation by hand and break -long lines. (The conversion programs don't write lines longer than -eighty characters in any case.) -@end itemize - -@node Non-bugs -@section Certain Changes We Don't Want to Make - -This section lists changes that people frequently request, but which -we do not make because we think GCC is better without them. - -@itemize @bullet -@item -Checking the number and type of arguments to a function which has an -old-fashioned definition and no prototype. - -Such a feature would work only occasionally---only for calls that appear -in the same file as the called function, following the definition. The -only way to check all calls reliably is to add a prototype for the -function. But adding a prototype eliminates the motivation for this -feature. So the feature is not worthwhile. - -@item -Warning about using an expression whose type is signed as a shift count. - -Shift count operands are probably signed more often than unsigned. -Warning about this would cause far more annoyance than good. - -@item -Warning about assigning a signed value to an unsigned variable. - -Such assignments must be very common; warning about them would cause -more annoyance than good. - -@item -Warning when a non-void function value is ignored. - -C contains many standard functions that return a value that most -programs choose to ignore. One obvious example is @code{printf}. -Warning about this practice only leads the defensive programmer to -clutter programs with dozens of casts to @code{void}. Such casts are -required so frequently that they become visual noise. Writing those -casts becomes so automatic that they no longer convey useful -information about the intentions of the programmer. For functions -where the return value should never be ignored, use the -@code{warn_unused_result} function attribute (@pxref{Function -Attributes}). - -@item -@opindex fshort-enums -Making @option{-fshort-enums} the default. - -This would cause storage layout to be incompatible with most other C -compilers. And it doesn't seem very important, given that you can get -the same result in other ways. The case where it matters most is when -the enumeration-valued object is inside a structure, and in that case -you can specify a field width explicitly. - -@item -Making bit-fields unsigned by default on particular machines where ``the -ABI standard'' says to do so. - -The ISO C standard leaves it up to the implementation whether a bit-field -declared plain @code{int} is signed or not. This in effect creates two -alternative dialects of C@. - -@opindex fsigned-bitfields -@opindex funsigned-bitfields -The GNU C compiler supports both dialects; you can specify the signed -dialect with @option{-fsigned-bitfields} and the unsigned dialect with -@option{-funsigned-bitfields}. However, this leaves open the question of -which dialect to use by default. - -Currently, the preferred dialect makes plain bit-fields signed, because -this is simplest. Since @code{int} is the same as @code{signed int} in -every other context, it is cleanest for them to be the same in bit-fields -as well. - -Some computer manufacturers have published Application Binary Interface -standards which specify that plain bit-fields should be unsigned. It is -a mistake, however, to say anything about this issue in an ABI@. This is -because the handling of plain bit-fields distinguishes two dialects of C@. -Both dialects are meaningful on every type of machine. Whether a -particular object file was compiled using signed bit-fields or unsigned -is of no concern to other object files, even if they access the same -bit-fields in the same data structures. - -A given program is written in one or the other of these two dialects. -The program stands a chance to work on most any machine if it is -compiled with the proper dialect. It is unlikely to work at all if -compiled with the wrong dialect. - -Many users appreciate the GNU C compiler because it provides an -environment that is uniform across machines. These users would be -inconvenienced if the compiler treated plain bit-fields differently on -certain machines. - -Occasionally users write programs intended only for a particular machine -type. On these occasions, the users would benefit if the GNU C compiler -were to support by default the same dialect as the other compilers on -that machine. But such applications are rare. And users writing a -program to run on more than one type of machine cannot possibly benefit -from this kind of compatibility. - -This is why GCC does and will treat plain bit-fields in the same -fashion on all types of machines (by default). - -There are some arguments for making bit-fields unsigned by default on all -machines. If, for example, this becomes a universal de facto standard, -it would make sense for GCC to go along with it. This is something -to be considered in the future. - -(Of course, users strongly concerned about portability should indicate -explicitly in each bit-field whether it is signed or not. In this way, -they write programs which have the same meaning in both C dialects.) - -@item -@opindex ansi -@opindex std -Undefining @code{__STDC__} when @option{-ansi} is not used. - -Currently, GCC defines @code{__STDC__} unconditionally. This provides -good results in practice. - -Programmers normally use conditionals on @code{__STDC__} to ask whether -it is safe to use certain features of ISO C, such as function -prototypes or ISO token concatenation. Since plain @command{gcc} supports -all the features of ISO C, the correct answer to these questions is -``yes''. - -Some users try to use @code{__STDC__} to check for the availability of -certain library facilities. This is actually incorrect usage in an ISO -C program, because the ISO C standard says that a conforming -freestanding implementation should define @code{__STDC__} even though it -does not have the library facilities. @samp{gcc -ansi -pedantic} is a -conforming freestanding implementation, and it is therefore required to -define @code{__STDC__}, even though it does not come with an ISO C -library. - -Sometimes people say that defining @code{__STDC__} in a compiler that -does not completely conform to the ISO C standard somehow violates the -standard. This is illogical. The standard is a standard for compilers -that claim to support ISO C, such as @samp{gcc -ansi}---not for other -compilers such as plain @command{gcc}. Whatever the ISO C standard says -is relevant to the design of plain @command{gcc} without @option{-ansi} only -for pragmatic reasons, not as a requirement. - -GCC normally defines @code{__STDC__} to be 1, and in addition -defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option, -or a @option{-std} option for strict conformance to some version of ISO C@. -On some hosts, system include files use a different convention, where -@code{__STDC__} is normally 0, but is 1 if the user specifies strict -conformance to the C Standard. GCC follows the host convention when -processing system include files, but when processing user files it follows -the usual GNU C convention. - -@item -Undefining @code{__STDC__} in C++. - -Programs written to compile with C++-to-C translators get the -value of @code{__STDC__} that goes with the C compiler that is -subsequently used. These programs must test @code{__STDC__} -to determine what kind of C preprocessor that compiler uses: -whether they should concatenate tokens in the ISO C fashion -or in the traditional fashion. - -These programs work properly with GNU C++ if @code{__STDC__} is defined. -They would not work otherwise. - -In addition, many header files are written to provide prototypes in ISO -C but not in traditional C@. Many of these header files can work without -change in C++ provided @code{__STDC__} is defined. If @code{__STDC__} -is not defined, they will all fail, and will all need to be changed to -test explicitly for C++ as well. - -@item -Deleting ``empty'' loops. - -Historically, GCC has not deleted ``empty'' loops under the -assumption that the most likely reason you would put one in a program is -to have a delay, so deleting them will not make real programs run any -faster. - -However, the rationale here is that optimization of a nonempty loop -cannot produce an empty one. This held for carefully written C compiled -with less powerful optimizers but is not always the case for carefully -written C++ or with more powerful optimizers. -Thus GCC will remove operations from loops whenever it can determine -those operations are not externally visible (apart from the time taken -to execute them, of course). In case the loop can be proved to be finite, -GCC will also remove the loop itself. - -Be aware of this when performing timing tests, for instance the -following loop can be completely removed, provided -@code{some_expression} can provably not change any global state. - -@smallexample -@{ - int sum = 0; - int ix; - - for (ix = 0; ix != 10000; ix++) - sum += some_expression; -@} -@end smallexample - -Even though @code{sum} is accumulated in the loop, no use is made of -that summation, so the accumulation can be removed. - -@item -Making side effects happen in the same order as in some other compiler. - -@cindex side effects, order of evaluation -@cindex order of evaluation, side effects -It is never safe to depend on the order of evaluation of side effects. -For example, a function call like this may very well behave differently -from one compiler to another: - -@smallexample -void func (int, int); - -int i = 2; -func (i++, i++); -@end smallexample - -There is no guarantee (in either the C or the C++ standard language -definitions) that the increments will be evaluated in any particular -order. Either increment might happen first. @code{func} might get the -arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}. - -@item -Making certain warnings into errors by default. - -Some ISO C testsuites report failure when the compiler does not produce -an error message for a certain program. - -@opindex pedantic-errors -ISO C requires a ``diagnostic'' message for certain kinds of invalid -programs, but a warning is defined by GCC to count as a diagnostic. If -GCC produces a warning but not an error, that is correct ISO C support. -If testsuites call this ``failure'', they should be run with the GCC -option @option{-pedantic-errors}, which will turn these warnings into -errors. - -@end itemize - -@node Warnings and Errors -@section Warning Messages and Error Messages - -@cindex error messages -@cindex warnings vs errors -@cindex messages, warning and error -The GNU compiler can produce two kinds of diagnostics: errors and -warnings. Each kind has a different purpose: - -@itemize @w{} -@item -@dfn{Errors} report problems that make it impossible to compile your -program. GCC reports errors with the source file name and line -number where the problem is apparent. - -@item -@dfn{Warnings} report other unusual conditions in your code that -@emph{may} indicate a problem, although compilation can (and does) -proceed. Warning messages also report the source file name and line -number, but include the text @samp{warning:} to distinguish them -from error messages. -@end itemize - -Warnings may indicate danger points where you should check to make sure -that your program really does what you intend; or the use of obsolete -features; or the use of nonstandard features of GNU C or C++. Many -warnings are issued only if you ask for them, with one of the @option{-W} -options (for instance, @option{-Wall} requests a variety of useful -warnings). - -@opindex pedantic -@opindex pedantic-errors -GCC always tries to compile your program if possible; it never -gratuitously rejects a program whose meaning is clear merely because -(for instance) it fails to conform to a standard. In some cases, -however, the C and C++ standards specify that certain extensions are -forbidden, and a diagnostic @emph{must} be issued by a conforming -compiler. The @option{-pedantic} option tells GCC to issue warnings in -such cases; @option{-pedantic-errors} says to make them errors instead. -This does not mean that @emph{all} non-ISO constructs get warnings -or errors. - -@xref{Warning Options,,Options to Request or Suppress Warnings}, for -more detail on these and related command-line options. |