+++ /dev/null
-This is doc/gcc.info, produced by makeinfo version 4.5 from
-doc/gcc.texi.
-
-INFO-DIR-SECTION Programming
-START-INFO-DIR-ENTRY
-* gcc: (gcc). The GNU Compiler Collection.
-END-INFO-DIR-ENTRY
- This file documents the use of the GNU compilers.
-
- Published by the Free Software Foundation
-59 Temple Place - Suite 330
-Boston, MA 02111-1307 USA
-
- Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-1999, 2000, 2001, 2002 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being "GNU General Public License" and "Funding Free
-Software", the Front-Cover texts being (a) (see below), and with the
-Back-Cover Texts being (b) (see below). A copy of the license is
-included in the section entitled "GNU Free Documentation License".
-
- (a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
- (b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
-software. Copies published by the Free Software Foundation raise
-funds for GNU development.
-
-\1f
-File: gcc.info, Node: Incompatibilities, Next: Fixed Headers, Prev: External Bugs, Up: Trouble
-
-Incompatibilities of GCC
-========================
-
- There are several noteworthy incompatibilities between GNU C and K&R
-(non-ISO) versions of C. The `-traditional' option eliminates many of
-these incompatibilities, _but not all_, by telling GCC to behave like a
-K&R C compiler.
-
- * GCC normally makes string constants read-only. If several
- identical-looking string constants are used, GCC stores only one
- copy of the string.
-
- One consequence is that you cannot call `mktemp' with a string
- constant argument. The function `mktemp' always alters the string
- its argument points to.
-
- Another consequence is that `sscanf' does not work on some systems
- when passed a string constant as its format control string or
- input. This is because `sscanf' incorrectly tries to write into
- the string constant. Likewise `fscanf' and `scanf'.
-
- The best solution to these problems is to change the program to use
- `char'-array variables with initialization strings for these
- purposes instead of string constants. But if this is not possible,
- you can use the `-fwritable-strings' flag, which directs GCC to
- handle string constants the same way most C compilers do.
- `-traditional' also has this effect, among others.
-
- * `-2147483648' is positive.
-
- This is because 2147483648 cannot fit in the type `int', so
- (following the ISO C rules) its data type is `unsigned long int'.
- Negating this value yields 2147483648 again.
-
- * GCC does not substitute macro arguments when they appear inside of
- string constants. For example, the following macro in GCC
-
- #define foo(a) "a"
-
- will produce output `"a"' regardless of what the argument A is.
-
- The `-traditional' option directs GCC to handle such cases (among
- others) in the old-fashioned (non-ISO) fashion.
-
- * When you use `setjmp' and `longjmp', the only automatic variables
- guaranteed to remain valid are those declared `volatile'. This is
- a consequence of automatic register allocation. Consider this
- function:
-
- jmp_buf j;
-
- foo ()
- {
- int a, b;
-
- a = fun1 ();
- if (setjmp (j))
- return a;
-
- a = fun2 ();
- /* `longjmp (j)' may occur in `fun3'. */
- return a + fun3 ();
- }
-
- Here `a' may or may not be restored to its first value when the
- `longjmp' occurs. If `a' is allocated in a register, then its
- first value is restored; otherwise, it keeps the last value stored
- in it.
-
- If you use the `-W' option with the `-O' option, you will get a
- warning when GCC thinks such a problem might be possible.
-
- The `-traditional' option directs GCC to put variables in the
- stack by default, rather than in registers, in functions that call
- `setjmp'. This results in the behavior found in traditional C
- compilers.
-
- * 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:
-
- foobar (
- #define luser
- hack)
-
- ISO C does not permit such a construct. It would make sense to
- support it when `-traditional' is used, but it is too much work to
- implement.
-
- * K&R compilers allow comments to cross over an inclusion boundary
- (i.e. started in an include file and ended in the including file).
- I think this would be quite ugly and can't imagine it could be
- needed.
-
- * 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 `extern' declaration affects all the
- rest of the file even if it happens within a block.
-
- The `-traditional' option directs GCC to treat all `extern'
- declarations as global, like traditional compilers.
-
- * In traditional C, you can combine `long', etc., with a typedef
- name, as shown here:
-
- typedef int foo;
- typedef long foo bar;
-
- In ISO C, this is not allowed: `long' and other type modifiers
- require an explicit `int'. Because this criterion is expressed by
- Bison grammar rules rather than C code, the `-traditional' flag
- cannot alter it.
-
- * PCC allows typedef names to be used as function parameters. The
- difficulty described immediately above applies here too.
-
- * When in `-traditional' mode, GCC allows the following erroneous
- pair of declarations to appear together in a given scope:
-
- typedef int foo;
- typedef foo foo;
-
- * GCC treats all characters of identifiers as significant, even when
- in `-traditional' mode. 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.
-
- * PCC allows whitespace in the middle of compound assignment
- operators such as `+='. GCC, following the ISO standard, does not
- allow this. The difficulty described immediately above applies
- here too.
-
- * 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:
-
- #if 0
- You can't expect this to work.
- #endif
-
- The best solution to such a problem is to put the text into an
- actual C comment delimited by `/*...*/'. However, `-traditional'
- suppresses these error messages.
-
- * Many user programs contain the declaration `long time ();'. In the
- past, the system header files on many systems did not actually
- declare `time', so it did not matter what type your program
- declared it to return. But in systems with ISO C headers, `time'
- is declared to return `time_t', and if that is not the same as
- `long', then `long time ();' is erroneous.
-
- The solution is to change your program to use appropriate system
- headers (`<time.h>' on systems with ISO C headers) and not to
- declare `time' if the system header files declare it, or failing
- that to use `time_t' as the return type of `time'.
-
- * When compiling functions that return `float', PCC converts it to a
- double. GCC actually returns a `float'. If you are concerned
- with PCC compatibility, you should declare your functions to return
- `double'; you might as well say what you mean.
-
- * 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 machine-description
- macros `STRUCT_VALUE' and `STRUCT_INCOMING_VALUE' tell 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.
-
- You can tell GCC to use a compatible convention for all structure
- and union returning with the option `-fpcc-struct-return'.
-
- * GCC complains about program fragments such as `0x74ae-0x4000'
- which appear to be two hexadecimal constants separated by the minus
- operator. Actually, this string is a single "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 "preprocessing token" is a "preprocessing number" if it begins
- with a digit and is followed by letters, underscores, digits,
- periods and `e+', `e-', `E+', `E-', `p+', `p-', `P+', or `P-'
- character sequences. (In strict C89 mode, the sequences `p+',
- `p-', `P+' and `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.
-
-\1f
-File: gcc.info, Node: Fixed Headers, Next: Standard Libraries, Prev: Incompatibilities, Up: Trouble
-
-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 `fixincludes' (or for certain
-targets an alternative such as `fixinc.svr4'). Normally, you don't
-need to pay attention to this. But there are cases where it doesn't do
-the right thing automatically.
-
- * 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. The easiest way to update them is to
- reinstall GCC. (If you want to be clever, look in the makefile
- and you can find a shortcut.)
-
- * On some systems, in particular SunOS 4, 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 SunOS 4 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.
-
- In SunOS 4, only programs that look inside the kernel will notice
- the difference between machine models. Therefore, for most
- purposes, you need not be concerned about this.
-
- 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.
-
- * On Lynxos, GCC by default does not fix the header files. This is
- because bugs in the shell cause the `fixincludes' script to fail.
-
- This means you will encounter problems due to bugs in the system
- header files. It may be no comfort that they aren't GCC's fault,
- but it does mean that there's nothing for us to do about them.
-
-\1f
-File: gcc.info, Node: Standard Libraries, Next: Disappointments, Prev: Fixed Headers, Up: Trouble
-
-Standard Libraries
-==================
-
- GCC by itself attempts to be a conforming freestanding
-implementation. *Note Language Standards Supported by GCC: Standards,
-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 `-Wall') that you don't expect.
-
- For example, the `sprintf' function on SunOS 4.1.3 returns `char *'
-while the C standard says that `sprintf' returns an `int'. The
-`fixincludes' program could make the prototype for this function match
-the Standard, but that would be wrong, since the function will still
-return `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 `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.
-
-\1f
-File: gcc.info, Node: Disappointments, Next: C++ Misunderstandings, Prev: Standard Libraries, Up: Trouble
-
-Disappointments and Misunderstandings
-=====================================
-
- These problems are perhaps regrettable, but we don't know any
-practical way around them.
-
- * 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.
-
- * Users often think it is a bug when GCC reports an error for code
- like this:
-
- int foo (struct mumble *);
-
- struct mumble { ... };
-
- int foo (struct mumble *x)
- { ... }
-
- This code really is erroneous, because the scope of `struct
- mumble' in the prototype is limited to the argument list
- containing it. It does not refer to the `struct mumble' defined
- with file scope immediately below--they are two unrelated types
- with similar names in different scopes.
-
- But in the definition of `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 `struct mumble' above the prototype.
- It's not worth being incompatible with ISO C just to avoid an
- error for the example shown above.
-
- * 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.
-
- * 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. You will have to
- reinstall GCC to fix the new header files. More specifically, go
- to the build directory and delete the files `stmp-fixinc' and
- `stmp-headers', and the subdirectory `include'; then do `make
- install' again.
-
- * 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 `double' in memory. Compiled code moves values between
- memory and floating point registers at its convenience, and moving
- them into memory truncates them.
-
- You can partially avoid this problem by using the `-ffloat-store'
- option (*note Optimize Options::).
-
- * On the MIPS, variable argument functions using `varargs.h' cannot
- have a floating point value for the first argument. The reason
- for this is that in the absence of a prototype in scope, if the
- first argument is a floating point, it is passed in a floating
- point register, rather than an integer register.
-
- If the code is rewritten to use the ISO standard `stdarg.h' method
- of variable arguments, and the prototype is in scope at the time
- of the call, everything will work fine.
-
- * On the H8/300 and H8/300H, variable argument functions must be
- implemented using the ISO standard `stdarg.h' method of variable
- arguments. Furthermore, calls to functions using `stdarg.h'
- variable arguments must have a prototype for the called function
- in scope at the time of the call.
-
- * 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.
-
-\1f
-File: gcc.info, Node: C++ Misunderstandings, Next: Protoize Caveats, Prev: Disappointments, Up: Trouble
-
-Common Misunderstandings with GNU C++
-=====================================
-
- 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
-* Temporaries:: Temporaries may vanish before you expect
-* Copy Assignment:: Copy Assignment operators copy virtual bases twice
-
-\1f
-File: gcc.info, Node: Static Definitions, Next: Temporaries, Up: C++ Misunderstandings
-
-Declare _and_ Define Static Members
------------------------------------
-
- When a class has static data members, it is not enough to _declare_
-the static member; you must also _define_ it. For example:
-
- class Foo
- {
- ...
- void method();
- static int bar;
- };
-
- This declaration only establishes that the class `Foo' has an `int'
-named `Foo::bar', and a member function named `Foo::method'. But you
-still need to define _both_ `method' and `bar' elsewhere. According to
-the ISO standard, you must supply an initializer in one (and only one)
-source file, such as:
-
- int Foo::bar = 0;
-
- Other C++ compilers may not correctly implement the standard
-behavior. As a result, when you switch to `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: `g++' reports as
-undefined symbols any static data members that lack definitions.
-
-\1f
-File: gcc.info, Node: Temporaries, Next: Copy Assignment, Prev: Static Definitions, Up: C++ Misunderstandings
-
-Temporaries May Vanish Before You Expect
-----------------------------------------
-
- It is dangerous to use pointers or references to _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 `char *' or
-`const char *'--which is one reason why the standard `string' class
-requires you to call the `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 `strfunc' that returns
-`string' objects, and another function `charfunc' that operates on
-pointers to `char':
-
- string strfunc ();
- void charfunc (const char *);
-
- void
- f ()
- {
- const char *p = strfunc().c_str();
- ...
- charfunc (p);
- ...
- charfunc (p);
- }
-
-In this situation, it may seem reasonable to save a pointer to the C
-string returned by the `c_str' member function and use that rather than
-call `c_str' repeatedly. However, the temporary string created by the
-call to `strfunc' is destroyed after `p' is initialized, at which point
-`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:
-
- string& tmp = strfunc ();
- charfunc (tmp.c_str ());
-
-\1f
-File: gcc.info, Node: Copy Assignment, Prev: Temporaries, Up: C++ Misunderstandings
-
-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:
-
- 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;
- }
-
- The C++ standard specifies that `Base::Base' is only called once
-when constructing or copy-constructing a Derived object. It is
-unspecified whether `Base::operator=' is called more than once when the
-implicit copy-assignment for Derived objects is invoked (as it is
-inside `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 many times. In the example,
-copying proceeds in the following order: `val', `name' (via `strdup'),
-`bval', and `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.
-
-\1f
-File: gcc.info, Node: Protoize Caveats, Next: Non-bugs, Prev: C++ Misunderstandings, Up: Trouble
-
-Caveats of using `protoize'
-===========================
-
- The conversion programs `protoize' and `unprotoize' can sometimes
-change a source file in a way that won't work unless you rearrange it.
-
- * `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.
-
- * There are some C constructs which `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. `protoize'
- inserts a comment containing `???' 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.
-
- * Using `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 `unprotoize' is safe is when you
- are removing prototypes that were made with `protoize'; if the
- program worked before without any prototypes, it will work again
- without them.
-
- You can find all the places where this problem might occur by
- compiling the program with the `-Wconversion' option. It prints a
- warning whenever an argument is converted.
-
- * 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.
-
- * `protoize' cannot get the argument types for a function whose
- definition was not actually compiled due to preprocessing
- conditionals. When this happens, `protoize' changes nothing in
- regard to such a function. `protoize' tries to detect such
- instances and warn about them.
-
- You can generally work around this problem by using `protoize' step
- by step, each time specifying a different set of `-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.
-
- * 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.
-
- * `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.
-
- * 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.)
-
-\1f
-File: gcc.info, Node: Non-bugs, Next: Warnings and Errors, Prev: Protoize Caveats, Up: Trouble
-
-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.
-
- * 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.
-
- * 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.
-
- * 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.
-
- * Warning when a non-void function value is ignored.
-
- Coming as I do from a Lisp background, I balk at the idea that
- there is something dangerous about discarding a value. There are
- functions that return values which some callers may find useful;
- it makes no sense to clutter the program with a cast to `void'
- whenever the value isn't useful.
-
- * Making `-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.
-
- * 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 `int' is signed or not. This in effect
- creates two alternative dialects of C.
-
- The GNU C compiler supports both dialects; you can specify the
- signed dialect with `-fsigned-bitfields' and the unsigned dialect
- with `-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 `int' is the same as `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.)
-
- * Undefining `__STDC__' when `-ansi' is not used.
-
- Currently, GCC defines `__STDC__' as long as you don't use
- `-traditional'. This provides good results in practice.
-
- Programmers normally use conditionals on `__STDC__' to ask whether
- it is safe to use certain features of ISO C, such as function
- prototypes or ISO token concatenation. Since plain `gcc' supports
- all the features of ISO C, the correct answer to these questions is
- "yes".
-
- Some users try to use `__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 `__STDC__' even though it
- does not have the library facilities. `gcc -ansi -pedantic' is a
- conforming freestanding implementation, and it is therefore
- required to define `__STDC__', even though it does not come with
- an ISO C library.
-
- Sometimes people say that defining `__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 `gcc -ansi'--not
- for other compilers such as plain `gcc'. Whatever the ISO C
- standard says is relevant to the design of plain `gcc' without
- `-ansi' only for pragmatic reasons, not as a requirement.
-
- GCC normally defines `__STDC__' to be 1, and in addition defines
- `__STRICT_ANSI__' if you specify the `-ansi' option, or a `-std'
- option for strict conformance to some version of ISO C. On some
- hosts, system include files use a different convention, where
- `__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.
-
- * Undefining `__STDC__' in C++.
-
- Programs written to compile with C++-to-C translators get the
- value of `__STDC__' that goes with the C compiler that is
- subsequently used. These programs must test `__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 `__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 `__STDC__' is defined. If
- `__STDC__' is not defined, they will all fail, and will all need
- to be changed to test explicitly for C++ as well.
-
- * 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, which holds for C but is not always
- the case for C++.
-
- Moreover, with `-funroll-loops' small "empty" loops are already
- removed, so the current behavior is both sub-optimal and
- inconsistent and will change in the future.
-
- * Making side effects happen in the same order as in some other
- compiler.
-
- 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:
-
- void func (int, int);
-
- int i = 2;
- func (i++, i++);
-
- 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. `func'
- might get the arguments `2, 3', or it might get `3, 2', or even
- `2, 2'.
-
- * Not allowing structures with volatile fields in registers.
-
- Strictly speaking, there is no prohibition in the ISO C standard
- against allowing structures with volatile fields in registers, but
- it does not seem to make any sense and is probably not what you
- wanted to do. So the compiler will give an error message in this
- case.
-
- * 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.
-
- 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 test suites call this "failure", they
- should be run with the GCC option `-pedantic-errors', which will
- turn these warnings into errors.
-
-
-\1f
-File: gcc.info, Node: Warnings and Errors, Prev: Non-bugs, Up: Trouble
-
-Warning Messages and Error Messages
-===================================
-
- The GNU compiler can produce two kinds of diagnostics: errors and
-warnings. Each kind has a different purpose:
-
- "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.
-
- "Warnings" report other unusual conditions in your code that _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 `warning:' to distinguish them from error
- messages.
-
- 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 `-W'
-options (for instance, `-Wall' requests a variety of useful warnings).
-
- 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 _must_ be issued by a conforming compiler.
-The `-pedantic' option tells GCC to issue warnings in such cases;
-`-pedantic-errors' says to make them errors instead. This does not
-mean that _all_ non-ISO constructs get warnings or errors.
-
- *Note Options to Request or Suppress Warnings: Warning Options, for
-more detail on these and related command-line options.
-
-\1f
-File: gcc.info, Node: Bugs, Next: Service, Prev: Trouble, Up: Top
-
-Reporting Bugs
-**************
-
- Your bug reports play an essential role in making GCC reliable.
-
- When you encounter a problem, the first thing to do is to see if it
-is already known. *Note Trouble::. If it isn't known, then you should
-report the problem.
-
- Reporting a bug may help you by bringing a solution to your problem,
-or it may not. (If it does not, look in the service directory; see
-*Note Service::.) In any case, the principal function of a bug report
-is to help the entire community by making the next version of GCC work
-better. Bug reports are your contribution to the maintenance of GCC.
-
- Since the maintainers are very overloaded, we cannot respond to every
-bug report. However, if the bug has not been fixed, we are likely to
-send you a patch and ask you to tell us whether it works.
-
- In order for a bug report to serve its purpose, you must include the
-information that makes for fixing the bug.
-
-* Menu:
-
-* Criteria: Bug Criteria. Have you really found a bug?
-* Where: Bug Lists. Where to send your bug report.
-* Reporting: Bug Reporting. How to report a bug effectively.
-* GNATS: gccbug. You can use a bug reporting tool.
-* Known: Trouble. Known problems.
-* Help: Service. Where to ask for help.
-
-\1f
-File: gcc.info, Node: Bug Criteria, Next: Bug Lists, Up: Bugs
-
-Have You Found a Bug?
-=====================
-
- If you are not sure whether you have found a bug, here are some
-guidelines:
-
- * If the compiler gets a fatal signal, for any input whatever, that
- is a compiler bug. Reliable compilers never crash.
-
- * If the compiler produces invalid assembly code, for any input
- whatever (except an `asm' statement), that is a compiler bug,
- unless the compiler reports errors (not just warnings) which would
- ordinarily prevent the assembler from being run.
-
- * If the compiler produces valid assembly code that does not
- correctly execute the input source code, that is a compiler bug.
-
- However, you must double-check to make sure, because you may have
- run into an incompatibility between GNU C and traditional C (*note
- Incompatibilities::). These incompatibilities might be considered
- bugs, but they are inescapable consequences of valuable features.
-
- Or you may have a program whose behavior is undefined, which
- happened by chance to give the desired results with another C or
- C++ compiler.
-
- For example, in many nonoptimizing compilers, you can write `x;'
- at the end of a function instead of `return x;', with the same
- results. But the value of the function is undefined if `return'
- is omitted; it is not a bug when GCC produces different results.
-
- Problems often result from expressions with two increment
- operators, as in `f (*p++, *p++)'. Your previous compiler might
- have interpreted that expression the way you intended; GCC might
- interpret it another way. Neither compiler is wrong. The bug is
- in your code.
-
- After you have localized the error to a single source line, it
- should be easy to check for these things. If your program is
- correct and well defined, you have found a compiler bug.
-
- * If the compiler produces an error message for valid input, that is
- a compiler bug.
-
- * If the compiler does not produce an error message for invalid
- input, that is a compiler bug. However, you should note that your
- idea of "invalid input" might be my idea of "an extension" or
- "support for traditional practice".
-
- * If you are an experienced user of one of the languages GCC
- supports, your suggestions for improvement of GCC are welcome in
- any case.
-
-\1f
-File: gcc.info, Node: Bug Lists, Next: Bug Reporting, Prev: Bug Criteria, Up: Bugs
-
-Where to Report Bugs
-====================
-
- Send bug reports for the GNU Compiler Collection to
-<gcc-bugs@gcc.gnu.org>. In accordance with the GNU-wide convention, in
-which bug reports for tool "foo" are sent to `bug-foo@gnu.org', the
-address <bug-gcc@gnu.org> may also be used; it will forward to the
-address given above.
-
- Please read `http://gcc.gnu.org/bugs.html' for additional and/or
-more up-to-date bug reporting instructions before you post a bug report.
-
projects / msp430-gcc.git / blobdiff