InfoMagic Source Code 1993 July/THE_SOURCE_CODE_CD_ROM.iso/gnu/gccdist/gcc/gcc.info-4

GNU Info File | 1992-09-10 | 41.7 KB | 1,048 lines

This is Info file gcc.info, produced by Makeinfo-1.47 from the input
file gcc.texinfo.

   This file documents the use and the internals of the GNU compiler.

   Copyright (C) 1988, 1989, 1990 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License" and "Protect
Your Freedom--Fight `Look And Feel'" are included exactly as in the
original, and provided that the entire resulting derived work is
distributed under the terms of a permission notice identical to this
one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License" and "Protect Your Freedom--Fight `Look And Feel'" and this
permission notice may be included in translations approved by the Free
Software Foundation instead of in the original English.


File: gcc.info,  Node: Statement Exprs,  Next: Naming Types,  Prev: Extensions,  Up: Extensions

Statements and Declarations inside of Expressions
=================================================

   A compound statement in parentheses may appear inside an expression
in GNU C.  This allows you to declare variables within an expression.
For example:

     ({ int y = foo (); int z;
        if (y > 0) z = y;
        else z = - y;
        z; })

is a valid (though slightly more complex than necessary) expression for
the absolute value of `foo ()'.

   This feature is especially useful in making macro definitions "safe"
(so that they evaluate each operand exactly once).  For example, the
"maximum" function is commonly defined as a macro in standard C as
follows:

     #define max(a,b) ((a) > (b) ? (a) : (b))

But this definition computes either A or B twice, with bad results if
the operand has side effects.  In GNU C, if you know the type of the
operands (here let's assume `int'), you can define the macro safely as
follows:

     #define maxint(a,b) \
       ({int _a = (a), _b = (b); _a > _b ? _a : _b; })

   Embedded statements are not allowed in constant expressions, such as
the value of an enumeration constant, the width of a bit field, or the
initial value of a static variable.

   If you don't know the type of the operand, you can still do this,
but you must use `typeof' (*note Typeof::.) or type naming (*note
Naming Types::.).


File: gcc.info,  Node: Naming Types,  Next: Typeof,  Prev: Statement Exprs,  Up: Extensions

Naming an Expression's Type
===========================

   You can give a name to the type of an expression using a `typedef'
declaration with an initializer.  Here is how to define NAME as a type
name for the type of EXP:

     typedef NAME = EXP;

   This is useful in conjunction with the statements-within-expressions
feature.  Here is how the two together can be used to define a safe
"maximum" macro that operates on any arithmetic type:

     #define max(a,b) \
       ({typedef _ta = (a), _tb = (b);  \
         _ta _a = (a); _tb _b = (b);     \
         _a > _b ? _a : _b; })

   The reason for using names that start with underscores for the local
variables is to avoid conflicts with variable names that occur within
the expressions that are substituted for `a' and `b'.  Eventually we
hope to design a new form of declaration syntax that allows you to
declare variables whose scopes start only after their initializers;
this will be a more reliable way to prevent such conflicts.


File: gcc.info,  Node: Typeof,  Next: Lvalues,  Prev: Naming Types,  Up: Extensions

Referring to a Type with `typeof'
=================================

   Another way to refer to the type of an expression is with `typeof'.
The syntax of using of this keyword looks like `sizeof', but the
construct acts semantically like a type name defined with `typedef'.

   There are two ways of writing the argument to `typeof': with an
expression or with a type.  Here is an example with an expression:

     typeof (x[0](1))

This assumes that `x' is an array of functions; the type described is
that of the values of the functions.

   Here is an example with a typename as the argument:

     typeof (int *)

Here the type described is that of pointers to `int'.

   If you are writing a header file that must work when included in
ANSI C programs, write `__typeof__' instead of `typeof'. *Note
Alternate Keywords::.

   A `typeof'-construct can be used anywhere a typedef name could be
used.  For example, you can use it in a declaration, in a cast, or
inside of `sizeof' or `typeof'.

   * This declares `y' with the type of what `x' points to.

          typeof (*x) y;

   * This declares `y' as an array of such values.

          typeof (*x) y[4];

   * This declares `y' as an array of pointers to characters:

          typeof (typeof (char *)[4]) y;

     It is equivalent to the following traditional C declaration:

          char *y[4];

     To see the meaning of the declaration using `typeof', and why it
     might be a useful way to write, let's rewrite it with these macros:

          #define pointer(T)  typeof(T *)
          #define array(T, N) typeof(T [N])

     Now the declaration can be rewritten this way:

          array (pointer (char), 4) y;

     Thus, `array (pointer (char), 4)' is the type of arrays of 4
     pointers to `char'.


File: gcc.info,  Node: Lvalues,  Next: Conditionals,  Prev: Typeof,  Up: Extensions

Generalized Lvalues
===================

   Compound expressions, conditional expressions and casts are allowed
as lvalues provided their operands are lvalues.  This means that you
can take their addresses or store values into them.

   For example, a compound expression can be assigned, provided the last
expression in the sequence is an lvalue.  These two expressions are
equivalent:

     (a, b) += 5
     a, (b += 5)

   Similarly, the address of the compound expression can be taken.
These two expressions are equivalent:

     &(a, b)
     a, &b

   A conditional expression is a valid lvalue if its type is not void
and the true and false branches are both valid lvalues.  For example,
these two expressions are equivalent:

     (a ? b : c) = 5
     (a ? b = 5 : (c = 5))

   A cast is a valid lvalue if its operand is an lvalue.  A simple
assignment whose left-hand side is a cast works by converting the
right-hand side first to the specified type, then to the type of the
inner left-hand side expression.  After this is stored, the value is
converted back to the specified type to become the value of the
assignment.  Thus, if `a' has type `char *', the following two
expressions are equivalent:

     (int)a = 5
     (int)(a = (char *)(int)5)

   An assignment-with-arithmetic operation such as `+=' applied to a
cast performs the arithmetic using the type resulting from the cast,
and then continues as in the previous case.  Therefore, these two
expressions are equivalent:

     (int)a += 5
     (int)(a = (char *)(int) ((int)a + 5))

   You cannot take the address of an lvalue cast, because the use of its
address would not work out coherently.  Suppose that `&(int)f' were
permitted, where `f' has type `float'.  Then the following statement
would try to store an integer bit-pattern where a floating point number
belongs:

     *&(int)f = 1;

   This is quite different from what `(int)f = 1' would do--that would
convert 1 to floating point and store it.  Rather than cause this
inconsistancy, we think it is better to prohibit use of `&' on a cast.

   If you really do want an `int *' pointer with the address of `f',
you can simply write `(int *)&f'.


File: gcc.info,  Node: Conditionals,  Next: Zero-Length,  Prev: Lvalues,  Up: Extensions

Conditional Expressions with Omitted Middle-Operands
====================================================

   The middle operand in a conditional expression may be omitted.  Then
if the first operand is nonzero, its value is the value of the
conditional expression.

   Therefore, the expression

     x ? : y

has the value of `x' if that is nonzero; otherwise, the value of `y'.

   This example is perfectly equivalent to

     x ? x : y

In this simple case, the ability to omit the middle operand is not
especially useful.  When it becomes useful is when the first operand
does, or may (if it is a macro argument), contain a side effect.  Then
repeating the operand in the middle would perform the side effect
twice.  Omitting the middle operand uses the value already computed
without the undesirable effects of recomputing it.


File: gcc.info,  Node: Zero-Length,  Next: Variable-Length,  Prev: Conditionals,  Up: Extensions

Arrays of Length Zero
=====================

   Zero-length arrays are allowed in GNU C.  They are very useful as
the last element of a structure which is really a header for a
variable-length object:

     struct line {
       int length;
       char contents[0];
     };

     {
       struct line *thisline
         = (struct line *) malloc (sizeof (struct line) + this_length);
       thisline->length = this_length;
     }

   In standard C, you would have to give `contents' a length of 1, which
means either you waste space or complicate the argument to `malloc'.


File: gcc.info,  Node: Variable-Length,  Next: Subscripting,  Prev: Zero-Length,  Up: Extensions

Arrays of Variable Length
=========================

   Variable-length automatic arrays are allowed in GNU C.  These arrays
are declared like any other automatic arrays, but with a length that is
not a constant expression.  The storage is allocated at that time and
deallocated when the brace-level is exited.  For example:

     FILE *concat_fopen (char *s1, char *s2, char *mode)
     {
       char str[strlen (s1) + strlen (s2) + 1];
       strcpy (str, s1);
       strcat (str, s2);
       return fopen (str, mode);
     }

   You can also use variable-length arrays as arguments to functions:

     struct entry
     tester (int len, char data[len])
     {
       ...
     }

   The length of an array is computed on entry to the brace-level where
the array is declared and is remembered for the scope of the array in
case you access it with `sizeof'.

   Jumping or breaking out of the scope of the array name will also
deallocate the storage.  Jumping into the scope is not allowed; you
will get an error message for it.

   You can use the function `alloca' to get an effect much like
variable-length arrays.  The function `alloca' is available in many
other C implementations (but not in all).  On the other hand,
variable-length arrays are more elegant.

   There are other differences between these two methods.  Space
allocated with `alloca' exists until the containing *function* returns.
The space for a variable-length array is deallocated as soon as the
array name's scope ends.  (If you use both variable-length arrays and
`alloca' in the same function, deallocation of a variable-length array
will also deallocate anything more recently allocated with `alloca'.)


File: gcc.info,  Node: Subscripting,  Next: Pointer Arith,  Prev: Variable-Length,  Up: Extensions

Non-Lvalue Arrays May Have Subscripts
=====================================

   Subscripting is allowed on arrays that are not lvalues, even though
the unary `&' operator is not.  For example, this is valid in GNU C
though not valid in other C dialects:

     struct foo {int a[4];};

     struct foo f();

     bar (int index)
     {
       return f().a[index];
     }


File: gcc.info,  Node: Pointer Arith,  Next: Initializers,  Prev: Subscripting,  Up: Extensions

Arithmetic on `void'-Pointers and Function Pointers
===================================================

   In GNU C, addition and subtraction operations are supported on
pointers to `void' and on pointers to functions.  This is done by
treating the size of a `void' or of a function as 1.

   A consequence of this is that `sizeof' is also allowed on `void' and
on function types, and returns 1.

   The option `-Wpointer-arith' requests a warning if these extensions
are used.


File: gcc.info,  Node: Initializers,  Next: Constructors,  Prev: Pointer Arith,  Up: Extensions

Non-Constant Initializers
=========================

   The elements of an aggregate initializer for an automatic variable
are not required to be constant expressions in GNU C.  Here is an
example of an initializer with run-time varying elements:

     foo (float f, float g)
     {
       float beat_freqs[2] = { f-g, f+g };
       ...
     }


File: gcc.info,  Node: Constructors,  Next: Function Attributes,  Prev: Initializers,  Up: Extensions

Constructor Expressions
=======================

   GNU C supports constructor expressions.  A constructor looks like a
cast containing an initializer.  Its value is an object of the type
specified in the cast, containing the elements specified in the
initializer.  The type must be a structure, union or array type.

   Assume that `struct foo' and `structure' are declared as shown:

     struct foo {int a; char b[2];} structure;

Here is an example of constructing a `struct foo' with a constructor:

     structure = ((struct foo) {x + y, 'a', 0});

This is equivalent to writing the following:

     {
       struct foo temp = {x + y, 'a', 0};
       structure = temp;
     }

   You can also construct an array.  If all the elements of the
constructor are (made up of) simple constant expressions, suitable for
use in initializers, then the constructor is an lvalue and can be
coerced to a pointer to its first element, as shown here:

     char **foo = (char *[]) { "x", "y", "z" };

   Array constructors whose elements are not simple constants are not
very useful, because the constructor is not an lvalue.  There are only
two valid ways to use it: to subscript it, or initialize an array
variable with it. The former is probably slower than a `switch'
statement, while the latter does the same thing an ordinary C
initializer would do.

     output = ((int[]) { 2, x, 28 }) [input];


File: gcc.info,  Node: Function Attributes,  Next: Dollar Signs,  Prev: Constructors,  Up: Extensions

Declaring Attributes of Functions
=================================

   In GNU C, you declare certain things about functions called in your
program which help the compiler optimize function calls.

   A few functions, such as `abort' and `exit', cannot return. These
functions should be declared `volatile'.  For example,

     extern volatile void abort ();

tells the compiler that it can assume that `abort' will not return.
This makes slightly better code, but more importantly it helps avoid
spurious warnings of uninitialized variables.

   Many functions do not examine any values except their arguments, and
have no effects except the return value.  Such a function can be subject
to common subexpression elimination and loop optimization just as an
arithmetic operator would be.  These functions should be declared
`const'.  For example,

     extern const int square ();

says that the hypothetical function `square' is safe to call fewer
times than the program says.

   Note that a function that has pointer arguments and examines the data
pointed to must *not* be declared `const'.  Likewise, a function that
calls a non-`const' function usually must not be `const'.

   Some people object to this feature, claiming that ANSI C's `#pragma'
should be used instead.  There are two reasons I did not do this.

  1. It is impossible to generate `#pragma' commands from a macro.

  2. The `#pragma' command is just as likely as these keywords to mean
     something else in another compiler.

   These two reasons apply to *any* application whatever: as far as I
can see, `#pragma' is never useful.


File: gcc.info,  Node: Dollar Signs,  Next: Alignment,  Prev: Function Attributes,  Up: Extensions

Dollar Signs in Identifier Names
================================

   In GNU C, you may use dollar signs in identifier names.  This is
because many traditional C implementations allow such identifiers.

   Dollar signs are allowed if you specify `-traditional'; they are not
allowed if you specify `-ansi'.  Whether they are allowed by default
depends on the target machine; usually, they are not.


File: gcc.info,  Node: Alignment,  Next: Inline,  Prev: Dollar Signs,  Up: Extensions

Inquiring about the Alignment of a Type or Variable
===================================================

   The keyword `__alignof__' allows you to inquire about how an object
is aligned, or the minimum alignment usually required by a type.  Its
syntax is just like `sizeof'.

   For example, if the target machine requires a `double' value to be
aligned on an 8-byte boundary, then `__alignof__ (double)' is 8. This
is true on many RISC machines.  On more traditional machine designs,
`__alignof__ (double)' is 4 or even 2.

   Some machines never actually require alignment; they allow reference
to any data type even at an odd addresses.  For these machines,
`__alignof__' reports the *recommended* alignment of a type.

   When the operand of `__alignof__' is an lvalue rather than a type,
the value is the largest alignment that the lvalue is known to have.
It may have this alignment as a result of its data type, or because it
is part of a structure and inherits alignment from that structure. For
example, after this declaration:

     struct foo { int x; char y; } foo1;

the value of `__alignof__ (foo1.y)' is probably 2 or 4, the same as
`__alignof__ (int)', even though the data type of `foo1.y' does not
itself demand any alignment.


File: gcc.info,  Node: Inline,  Next: Extended Asm,  Prev: Alignment,  Up: Extensions

An Inline Function is As Fast As a Macro
========================================

   By declaring a function `inline', you can direct GNU CC to integrate
that function's code into the code for its callers.  This makes
execution faster by eliminating the function-call overhead; in
addition, if any of the actual argument values are constant, their
known values may permit simplifications at compile time so that not all
of the inline function's code needs to be included.

   To declare a function inline, use the `inline' keyword in its
declaration, like this:

     inline int
     inc (int *a)
     {
       (*a)++;
     }

   (If you are writing a header file to be included in ANSI C programs,
write `__inline__' instead of `inline'.  *Note Alternate Keywords::.)

   You can also make all "simple enough" functions inline with the
option `-finline-functions'.  Note that certain usages in a function
definition can make it unsuitable for inline substitution.

   When a function is both inline and `static', if all calls to the
function are integrated into the caller, and the function's address is
never used, then the function's own assembler code is never referenced.
In this case, GNU CC does not actually output assembler code for the
function, unless you specify the option `-fkeep-inline-functions'. Some
calls cannot be integrated for various reasons (in particular, calls
that precede the function's definition cannot be integrated, and
neither can recursive calls within the definition).  If there is a
nonintegrated call, then the function is compiled to assembler code as
usual.  The function must also be compiled as usual if the program
refers to its address, because that can't be inlined.

   When an inline function is not `static', then the compiler must
assume that there may be calls from other source files; since a global
symbol can be defined only once in any program, the function must not
be defined in the other source files, so the calls therein cannot be
integrated. Therefore, a non-`static' inline function is always
compiled on its own in the usual fashion.

   If you specify both `inline' and `extern' in the function
definition, then the definition is used only for inlining.  In no case
is the function compiled on its own, not even if you refer to its
address explicitly.  Such an address becomes an external reference, as
if you had only declared the function, and had not defined it.

   This combination of `inline' and `extern' has almost the effect of a
macro.  The way to use it is to put a function definition in a header
file with these keywords, and put another copy of the definition
(lacking `inline' and `extern') in a library file. The definition in
the header file will cause most calls to the function to be inlined.
If any uses of the function remain, they will refer to the single copy
in the library.


File: gcc.info,  Node: Extended Asm,  Next: Asm Labels,  Prev: Inline,  Up: Extensions

Assembler Instructions with C Expression Operands
=================================================

   In an assembler instruction using `asm', you can now specify the
operands of the instruction using C expressions.  This means no more
guessing which registers or memory locations will contain the data you
want to use.

   You must specify an assembler instruction template much like what
appears in a machine description, plus an operand constraint string for
each operand.

   For example, here is how to use the 68881's `fsinx' instruction:

     asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));

Here `angle' is the C expression for the input operand while `result'
is that of the output operand.  Each has `"f"' as its operand
constraint, saying that a floating-point register is required.  The `='
in `=f' indicates that the operand is an output; all output operands'
constraints must use `='.  The constraints use the same language used
in the machine description (*note Constraints::.).

   Each operand is described by an operand-constraint string followed
by the C expression in parentheses.  A colon separates the assembler
template from the first output operand, and another separates the last
output operand from the first input, if any.  Commas separate output
operands and separate inputs.  The total number of operands is limited
to the maximum number of operands in any instruction pattern in the
machine description.

   If there are no output operands, and there are input operands, then
there must be two consecutive colons surrounding the place where the
output operands would go.

   Output operand expressions must be lvalues; the compiler can check
this. The input operands need not be lvalues.  The compiler cannot
check whether the operands have data types that are reasonable for the
instruction being executed.  It does not parse the assembler
instruction template and does not know what it means, or whether it is
valid assembler input.  The extended `asm' feature is most often used
for machine instructions that the compiler itself does not know exist.

   The output operands must be write-only; GNU CC will assume that the
values in these operands before the instruction are dead and need not be
generated.  Extended asm does not support input-output or read-write
operands.  For this reason, the constraint character `+', which
indicates such an operand, may not be used.

   When the assembler instruction has a read-write operand, or an
operand in which only some of the bits are to be changed, you must
logically split its function into two separate operands, one input
operand and one write-only output operand.  The connection between them
is expressed by constraints which say they need to be in the same
location when the instruction executes.  You can use the same C
expression for both operands, or different expressions.  For example,
here we write the (fictitious) `combine' instruction with `bar' as its
read-only source operand and `foo' as its read-write destination:

     asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));

The constraint `"0"' for operand 1 says that it must occupy the same
location as operand 0.  A digit in constraint is allowed only in an
input operand, and it must refer to an output operand.

   Only a digit in the constraint can guarantee that one operand will
be in the same place as another.  The mere fact that `foo' is the value
of both operands is not enough to guarantee that they will be in the
same place in the generated assembler code.  The following would not
work:

     asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));

   Various optimizations or reloading could cause operands 0 and 1 to
be in different registers; GNU CC knows no reason not to do so.  For
example, the compiler might find a copy of the value of `foo' in one
register and use it for operand 1, but generate the output operand 0 in
a different register (copying it afterward to `foo''s own address).  Of
course, since the register for operand 1 is not even mentioned in the
assembler code, the result will not work, but GNU CC can't tell that.

   Unless an output operand has the `&' constraint modifier, GNU CC may
allocate it in the same register as an unrelated input operand, on the
assumption that the inputs are consumed before the outputs are produced.
This assumption may be false if the assembler code actually consists of
more than one instruction.  In such a case, use `&' for each output
operand that may not overlap an input.  *Note Modifiers::.

   Some instructions clobber specific hard registers.  To describe
this, write a third colon after the input operands, followed by the
names of the clobbered hard registers (given as strings).  Here is a
realistic example for the vax:

     asm volatile ("movc3 %0,%1,%2"
                   : /* no outputs */
                   : "g" (from), "g" (to), "g" (count)
                   : "r0", "r1", "r2", "r3", "r4", "r5");

   You can put multiple assembler instructions together in a single
`asm' template, separated either with newlines (written as `\n') or with
semicolons if the assembler allows such semicolons.  The GNU assembler
allows semicolons and all Unix assemblers seem to do so.  The input
operands are guaranteed not to use any of the clobbered registers, and
neither will the output operands' addresses, so you can read and write
the clobbered registers as many times as you like.  Here is an example
of multiple instructions in a template; it assumes that the subroutine
`_foo' accepts arguments in registers 9 and 10:

     asm ("movl %0,r9;movl %1,r10;call _foo"
          : /* no outputs */
          : "g" (from), "g" (to)
          : "r9", "r10");

   If you want to test the condition code produced by an assembler
instruction, you must include a branch and a label in the `asm'
construct, as follows:

     asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
          : "g" (result)
          : "g" (input));

This assumes your assembler supports local labels, as the GNU assembler
and most Unix assemblers do.

   Usually the most convenient way to use these `asm' instructions is to
encapsulate them in macros that look like functions.  For example,

     #define sin(x)       \
     ({ double __value, __arg = (x);   \
        asm ("fsinx %1,%0": "=f" (__value): "f" (__arg));  \
        __value; })

Here the variable `__arg' is used to make sure that the instruction
operates on a proper `double' value, and to accept only those arguments
`x' which can convert automatically to a `double'.

   Another way to make sure the instruction operates on the correct
data type is to use a cast in the `asm'.  This is different from using a
variable `__arg' in that it converts more different types.  For
example, if the desired type were `int', casting the argument to `int'
would accept a pointer with no complaint, while assigning the argument
to an `int' variable named `__arg' would warn about using a pointer
unless the caller explicitly casts it.

   If an `asm' has output operands, GNU CC assumes for optimization
purposes that the instruction has no side effects except to change the
output operands.  This does not mean that instructions with a side
effect cannot be used, but you must be careful, because the compiler
may eliminate them if the output operands aren't used, or move them out
of loops, or replace two with one if they constitute a common
subexpression.  Also, if your instruction does have a side effect on a
variable that otherwise appears not to change, the old value of the
variable may be reused later if it happens to be found in a register.

   You can prevent an `asm' instruction from being deleted, moved or
combined by writing the keyword `volatile' after the `asm'.  For
example:

     #define set_priority(x)  \
     asm volatile ("set_priority %0": /* no outputs */ : "g" (x))

(However, an instruction without output operands will not be deleted or
moved, regardless, unless it is unreachable.)

   It is a natural idea to look for a way to give access to the
condition code left by the assembler instruction.  However, when we
attempted to implement this, we found no way to make it work reliably.
The problem is that output operands might need reloading, which would
result in additional following "store" instructions.  On most machines,
these instructions would alter the condition code before there was time
to test it.  This problem doesn't arise for ordinary "test" and
"compare" instructions because they don't have any output operands.

   If you are writing a header file that should be includable in ANSI C
programs, write `__asm__' instead of `asm'.  *Note Alternate Keywords::.


File: gcc.info,  Node: Asm Labels,  Next: Explicit Reg Vars,  Prev: Extended Asm,  Up: Extensions

Controlling Names Used in Assembler Code
========================================

   You can specify the name to be used in the assembler code for a C
function or variable by writing the `asm' (or `__asm__') keyword after
the declarator as follows:

     int foo asm ("myfoo") = 2;

This specifies that the name to be used for the variable `foo' in the
assembler code should be `myfoo' rather than the usual `_foo'.

   On systems where an underscore is normally prepended to the name of
a C function or variable, this feature allows you to define names for
the linker that do not start with an underscore.

   You cannot use `asm' in this way in a function *definition*; but you
can get the same effect by writing a declaration for the function
before its definition and putting `asm' there, like this:

     extern func () asm ("FUNC");

     func (x, y)
          int x, y;
     ...

   It is up to you to make sure that the assembler names you choose do
not conflict with any other assembler symbols.  Also, you must not use a
register name; that would produce completely invalid assembler code.
GNU CC does not as yet have the ability to store static variables in
registers. Perhaps that will be added.


File: gcc.info,  Node: Explicit Reg Vars,  Next: Alternate Keywords,  Prev: Asm Labels,  Up: Extensions

Variables in Specified Registers
================================

   GNU C allows you to put a few global variables into specified
hardware registers.  You can also specify the register in which an
ordinary register variable should be allocated.

   * Global register variables reserve registers throughout the program.
     This may be useful in programs such as programming language
     interpreters which have a couple of global variables that are
     accessed very often.

   * Local register variables in specific registers do not reserve the
     registers.  The compiler's data flow analysis is capable of
     determining where the specified registers contain live values, and
     where they are available for other uses.  These local variables are
     sometimes convenient for use with the extended `asm' feature
     (*note Extended Asm::.).

* Menu:

* Global Reg Vars::
* Local Reg Vars::


File: gcc.info,  Node: Global Reg Vars,  Next: Local Reg Vars,  Prev: Explicit Reg Vars,  Up: Explicit Reg Vars

Defining Global Register Variables
----------------------------------

   You can define a global register variable in GNU C like this:

     register int *foo asm ("a5");

Here `a5' is the name of the register which should be used.  Choose a
register which is normally saved and restored by function calls on your
machine, so that library routines will not clobber it.

   Naturally the register name is cpu-dependent, so you would need to
conditionalize your program according to cpu type.  The register `a5'
would be a good choice on a 68000 for a variable of pointer type.  On
machines with register windows, be sure to choose a "global" register
that is not affected magically by the function call mechanism.

   In addition, operating systems on one type of cpu may differ in how
they name the registers; then you would need additional conditionals.
For example, some 68000 operating systems call this register `%a5'.

   Eventually there may be a way of asking the compiler to choose a
register automatically, but first we need to figure out how it should
choose and how to enable you to guide the choice.  No solution is
evident.

   Defining a global register variable in a certain register reserves
that register entirely for this use, at least within the current
compilation. The register will not be allocated for any other purpose
in the functions in the current compilation.  The register will not be
saved and restored by these functions.  Stores into this register are
never deleted even if they would appear to be dead, but references may
be deleted or moved or simplified.

   It is not safe to access the global register variables from signal
handlers, or from more than one thread of control, because the system
library routines may temporarily use the register for other things
(unless you recompile them specially for the task at hand).

   It is not safe for one function that uses a global register variable
to call another such function `foo' by way of a third function `lose'
that was compiled without knowledge of this variable (i.e. in a
different source file in which the variable wasn't declared).  This is
because `lose' might save the register and put some other value there.
For example, you can't expect a global register variable to be
available in the comparison-function that you pass to `qsort', since
`qsort' might have put something else in that register.  (If you are
prepared to recompile `qsort' with the same global register variable,
you can solve this problem.)

   If you want to recompile `qsort' or other source files which do not
actually use your global register variable, so that they will not use
that register for any other purpose, then it suffices to specify the
compiler option `-ffixed-REG'.  You need not actually add a global
register declaration to their source code.

   A function which can alter the value of a global register variable
cannot safely be called from a function compiled without this variable,
because it could clobber the value the caller expects to find there on
return. Therefore, the function which is the entry point into the part
of the program that uses the global register variable must explicitly
save and restore the value which belongs to its caller.

   On most machines, `longjmp' will restore to each global register
variable the value it had at the time of the `setjmp'.  On some
machines, however, `longjmp' will not change the value of global
register variables.  To be portable, the function that called `setjmp'
should make other arrangements to save the values of the global register
variables, and to restore them in a `longjmp'.  This way, the same
thing will happen regardless of what `longjmp' does.

   All global register variable declarations must precede all function
definitions.  If such a declaration could appear after function
definitions, the declaration would be too late to prevent the register
from being used for other purposes in the preceding functions.

   Global register variables may not have initial values, because an
executable file has no means to supply initial contents for a register.


File: gcc.info,  Node: Local Reg Vars,  Prev: Global Reg Vars,  Up: Explicit Reg Vars

Specifying Registers for Local Variables
----------------------------------------

   You can define a local register variable with a specified register
like this:

     register int *foo asm ("a5");

Here `a5' is the name of the register which should be used.  Note that
this is the same syntax used for defining global register variables,
but for a local variable it would appear within a function.

   Naturally the register name is cpu-dependent, but this is not a
problem, since specific registers are most often useful with explicit
assembler instructions (*note Extended Asm::.).  Both of these things
generally require that you conditionalize your program according to cpu
type.

   In addition, operating systems on one type of cpu may differ in how
they name the registers; then you would need additional conditionals.
For example, some 68000 operating systems call this register `%a5'.

   Eventually there may be a way of asking the compiler to choose a
register automatically, but first we need to figure out how it should
choose and how to enable you to guide the choice.  No solution is
evident.

   Defining such a register variable does not reserve the register; it
remains available for other uses in places where flow control determines
the variable's value is not live.  However, these registers are made
unavailable for use in the reload pass.  I would not be surprised if
excessive use of this feature leaves the compiler too few available
registers to compile certain functions.


File: gcc.info,  Node: Alternate Keywords,  Prev: Explicit Reg Vars,  Up: Extensions

Alternate Keywords
==================

   The option `-traditional' disables certain keywords; `-ansi'
disables certain others.  This causes trouble when you want to use GNU C
extensions, or ANSI C features, in a general-purpose header file that
should be usable by all programs, including ANSI C programs and
traditional ones.  The keywords `asm', `typeof' and `inline' cannot be
used since they won't work in a program compiled with `-ansi', while
the keywords `const', `volatile', `signed', `typeof' and `inline' won't
work in a program compiled with `-traditional'.

   The way to solve these problems is to put `__' at the beginning and
end of each problematical keyword.  For example, use `__asm__' instead
of `asm', `__const__' instead of `const', and `__inline__' instead of
`inline'.

   Other C compilers won't accept these alternative keywords; if you
want to compile with another compiler, you can define the alternate
keywords as macros to replace them with the customary keywords.  It
looks like this:

     #ifndef __GNUC__
     #define __asm__ asm
     #endif


File: gcc.info,  Node: Bugs,  Next: Portability,  Prev: Extensions,  Up: Top

Reporting Bugs
**************

   Your bug reports play an essential role in making GNU CC reliable.

   When you encounter a problem, the first thing to do is to see if it
is already known.  *Note Trouble::.  Also look in *Note
Incompatibilities::. 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 GNU CC
work better.  Bug reports are your contribution to the maintenance of
GNU CC.

   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?
* Reporting: Bug Reporting.  How to report a bug effectively.


File: gcc.info,  Node: Bug Criteria,  Next: Bug Reporting,  Prev: Bugs,  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
     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 GNU CC 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; GNU CC 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.

     Note that the following is not valid input, and the error message
     for it is not a bug:

          int foo (char);

          int
          foo (x)
               char x;
          { ... }

     The prototype says to pass a `char', while the definition says to
     pass an `int' and treat the value as a `char'.  This is what the
     ANSI standard says, and it makes sense.

   * 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 C compilers, your suggestions
     for improvement of GNU CC are welcome in any case.