From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- gcc/doc/trouble.texi | 1218 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1218 insertions(+) create mode 100644 gcc/doc/trouble.texi (limited to 'gcc/doc/trouble.texi') diff --git a/gcc/doc/trouble.texi b/gcc/doc/trouble.texi new file mode 100644 index 000000000..03e399373 --- /dev/null +++ b/gcc/doc/trouble.texi @@ -0,0 +1,1218 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, +@c 1999, 2000, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 +@c 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++. +* 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. +@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. + +@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 +Another consequence is that @code{sscanf} does not work on some very +old 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}. + +The 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. + +@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, an @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 @code{'} +@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{} 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 C90 +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 + 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}, +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 struct Base @{ + int i; + @}; + + template struct Derived : public Base @{ + 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*}, so is obviously dependent), or using +@code{Base::i}. Alternatively, @code{Base::i} might be brought +into scope by a @code{using}-declaration. + +Another, similar example involves calling member functions of a base +class: + +@smallexample + template struct Base @{ + int f(); + @}; + + template struct Derived : Base @{ + 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::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::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 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. -- cgit v1.2.3