This is doc/gcc.info, produced by makeinfo version 4.0b 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 and the internals of the GNU compiler.


   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 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.


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

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

   In an assembler instruction using `asm', you can specify the
operands of the instruction using C expressions.  This means you need
not guess 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 the
operands within each group.  The total number of operands is currently
limited to 30; this limitation may be lifted in some future version of
GCC.

   If there are no output operands but there are input operands, you
must place two consecutive colons surrounding the place where the output
operands would go.

   As of GCC version 3.1, it is also possible to specify input and
output operands using symbolic names which can be referenced within the
assembler code.  These names are specified inside square brackets
preceding the constraint string, and can be referenced inside the
assembler code using `%[NAME]' instead of a percentage sign followed by
the operand number.  Using named operands the above example could look
like:

     asm ("fsinx %[angle],%[output]"
          : [output] "=f" (result)
          : [angle] "f" (angle));

Note that the symbolic operand names have no relation whatsoever to
other C identifiers.  You may use any name you like, even those of
existing C symbols, but must ensure that no two operands within the same
assembler construct use the same symbolic name.

   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 even whether it is valid
assembler input.  The extended `asm' feature is most often used for
machine instructions the compiler itself does not know exist.  If the
output expression cannot be directly addressed (for example, it is a
bit-field), your constraint must allow a register.  In that case, GCC
will use the register as the output of the `asm', and then store that
register into the output.

   The ordinary output operands must be write-only; GCC will assume that
the values in these operands before the instruction are dead and need
not be generated.  Extended asm supports input-output or read-write
operands.  Use the constraint character `+' to indicate such an operand
and list it with the output operands.

   When the constraints for the read-write operand (or the operand in
which only some of the bits are to be changed) allows a register, you
may, as an alternative, 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 number in constraint is allowed only in an
input operand and it must refer to an output operand.

   Only a number 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 reliably:

     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; GCC 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 GCC can't tell that.

   As of GCC version 3.1, one may write `[NAME]' instead of the operand
number for a matching constraint.  For example:

     asm ("cmoveq %1,%2,%[result]"
          : [result] "=r"(result)
          : "r" (test), "r"(new), "[result]"(old));

   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 may not write a clobber description in a way that overlaps with
an input or output operand.  For example, you may not have an operand
describing a register class with one member if you mention that register
in the clobber list.  There is no way for you to specify that an input
operand is modified without also specifying it as an output operand.
Note that if all the output operands you specify are for this purpose
(and hence unused), you will then also need to specify `volatile' for
the `asm' construct, as described below, to prevent GCC from deleting
the `asm' statement as unused.

   If you refer to a particular hardware register from the assembler
code, you will probably have to list the register after the third colon
to tell the compiler the register's value is modified.  In some
assemblers, the register names begin with `%'; to produce one `%' in the
assembler code, you must write `%%' in the input.

   If your assembler instruction can alter the condition code register,
add `cc' to the list of clobbered registers.  GCC on some machines
represents the condition codes as a specific hardware register; `cc'
serves to name this register.  On other machines, the condition code is
handled differently, and specifying `cc' has no effect.  But it is
valid no matter what the machine.

   If your assembler instruction modifies memory in an unpredictable
fashion, add `memory' to the list of clobbered registers.  This will
cause GCC to not keep memory values cached in registers across the
assembler instruction.  You will also want to add the `volatile'
keyword if the memory affected is not listed in the inputs or outputs
of the `asm', as the `memory' clobber does not count as a side-effect
of the `asm'.

   You can put multiple assembler instructions together in a single
`asm' template, separated by the characters normally used in assembly
code for the system.  A combination that works in most places is a
newline to break the line, plus a tab character to move to the
instruction field (written as `\n\t').  Sometimes semicolons can be
used, if the assembler allows semicolons as a line-breaking character.
Note that some assembler dialects use semicolons to start a comment.
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 the
subroutine `_foo' accepts arguments in registers 9 and 10:

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

   Unless an output operand has the `&' constraint modifier, GCC may
allocate it in the same register as an unrelated input operand, on the
assumption 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::.

   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\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
          : "g" (result)
          : "g" (input));

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

   Speaking of labels, jumps from one `asm' to another are not
supported.  The compiler's optimizers do not know about these jumps, and
therefore they cannot take account of them when deciding how to
optimize.

   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, GCC assumes for optimization
purposes the instruction has no side effects except to change the output
operands.  This does not mean 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
significantly, or combined, by writing the keyword `volatile' after the
`asm'.  For example:

     #define get_and_set_priority(new)              \
     ({ int __old;                                  \
        asm volatile ("get_and_set_priority %0, %1" \
                      : "=g" (__old) : "g" (new));  \
        __old; })

If you write an `asm' instruction with no outputs, GCC will know the
instruction has side-effects and will not delete the instruction or
move it outside of loops.

   The `volatile' keyword indicates that the instruction has important
side-effects.  GCC will not delete a volatile `asm' if it is reachable.
(The instruction can still be deleted if GCC can prove that
control-flow will never reach the location of the instruction.)  In
addition, GCC will not reschedule instructions across a volatile `asm'
instruction.  For example:

     *(volatile int *)addr = foo;
     asm volatile ("eieio" : : );

Assume `addr' contains the address of a memory mapped device register.
The PowerPC `eieio' instruction (Enforce In-order Execution of I/O)
tells the CPU to make sure that the store to that device register
happens before it issues any other I/O.

   Note that even a volatile `asm' instruction can be moved in ways
that appear insignificant to the compiler, such as across jump
instructions.  You can't expect a sequence of volatile `asm'
instructions to remain perfectly consecutive.  If you want consecutive
output, use a single `asm'.  Also, GCC will perform some optimizations
across a volatile `asm' instruction; GCC does not "forget everything"
when it encounters a volatile `asm' instruction the way some other
compilers do.

   An `asm' instruction without any operands or clobbers (an "old
style" `asm') will be treated identically to a volatile `asm'
instruction.

   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.

   For reasons similar to those described above, it is not possible to
give an assembler instruction access to the condition code left by
previous instructions.

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

i386 floating point asm operands
--------------------------------

   There are several rules on the usage of stack-like regs in
asm_operands insns.  These rules apply only to the operands that are
stack-like regs:

  1. Given a set of input regs that die in an asm_operands, it is
     necessary to know which are implicitly popped by the asm, and
     which must be explicitly popped by gcc.

     An input reg that is implicitly popped by the asm must be
     explicitly clobbered, unless it is constrained to match an output
     operand.

  2. For any input reg that is implicitly popped by an asm, it is
     necessary to know how to adjust the stack to compensate for the
     pop.  If any non-popped input is closer to the top of the
     reg-stack than the implicitly popped reg, it would not be possible
     to know what the stack looked like--it's not clear how the rest of
     the stack "slides up".

     All implicitly popped input regs must be closer to the top of the
     reg-stack than any input that is not implicitly popped.

     It is possible that if an input dies in an insn, reload might use
     the input reg for an output reload.  Consider this example:

          asm ("foo" : "=t" (a) : "f" (b));

     This asm says that input B is not popped by the asm, and that the
     asm pushes a result onto the reg-stack, i.e., the stack is one
     deeper after the asm than it was before.  But, it is possible that
     reload will think that it can use the same reg for both the input
     and the output, if input B dies in this insn.

     If any input operand uses the `f' constraint, all output reg
     constraints must use the `&' earlyclobber.

     The asm above would be written as

          asm ("foo" : "=&t" (a) : "f" (b));

  3. Some operands need to be in particular places on the stack.  All
     output operands fall in this category--there is no other way to
     know which regs the outputs appear in unless the user indicates
     this in the constraints.

     Output operands must specifically indicate which reg an output
     appears in after an asm.  `=f' is not allowed: the operand
     constraints must select a class with a single reg.

  4. Output operands may not be "inserted" between existing stack regs.
     Since no 387 opcode uses a read/write operand, all output operands
     are dead before the asm_operands, and are pushed by the
     asm_operands.  It makes no sense to push anywhere but the top of
     the reg-stack.

     Output operands must start at the top of the reg-stack: output
     operands may not "skip" a reg.

  5. Some asm statements may need extra stack space for internal
     calculations.  This can be guaranteed by clobbering stack registers
     unrelated to the inputs and outputs.


   Here are a couple of reasonable asms to want to write.  This asm
takes one input, which is internally popped, and produces two outputs.

     asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));

   This asm takes two inputs, which are popped by the `fyl2xp1' opcode,
and replaces them with one output.  The user must code the `st(1)'
clobber for reg-stack.c to know that `fyl2xp1' pops both inputs.

     asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");


File: gcc.info,  Node: Asm Labels,  Next: Explicit Reg Vars,  Prev: Extended Asm,  Up: C 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.

   It does not make sense to use this feature with a non-static local
variable since such variables do not have assembler names.  If you are
trying to put the variable in a particular register, see *Note Explicit
Reg Vars::.  GCC presently accepts such code with a warning, but will
probably be changed to issue an error, rather than a warning, in the
future.

   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.
GCC 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: C 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.  Stores into local
     register variables may be deleted when they appear to be dead
     according to dataflow analysis.  References to local register
     variables may be deleted or moved or simplified.

     These local variables are sometimes convenient for use with the
     extended `asm' feature (*note Extended Asm::), if you want to
     write one output of the assembler instruction directly into a
     particular register.  (This will work provided the register you
     specify fits the constraints specified for that operand in the
     `asm'.)

* Menu:

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


File: gcc.info,  Node: Global Reg Vars,  Next: Local 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.

   On the Sparc, there are reports that g3 ... g7 are suitable
registers, but certain library functions, such as `getwd', as well as
the subroutines for division and remainder, modify g3 and g4.  g1 and
g2 are local temporaries.

   On the 68000, a2 ... a5 should be suitable, as should d2 ... d7.  Of
course, it will not do to use more than a few of those.


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'.

   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; excessive use of this feature
leaves the compiler too few available registers to compile certain
functions.

   This option does not guarantee that GCC will generate code that has
this variable in the register you specify at all times.  You may not
code an explicit reference to this register in an `asm' statement and
assume it will always refer to this variable.

   Stores into local register variables may be deleted when they appear
to be dead according to dataflow analysis.  References to local
register variables may be deleted or moved or simplified.


File: gcc.info,  Node: Alternate Keywords,  Next: Incomplete Enums,  Prev: Explicit Reg Vars,  Up: C Extensions

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

   The option `-traditional' disables certain keywords; `-ansi' and the
various `-std' options disable certain others.  This causes trouble
when you want to use GNU C extensions, or ISO C features, in a
general-purpose header file that should be usable by all programs,
including ISO 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' (although `inline' can be used in a program
compiled with `-std=c99'), while the keywords `const', `volatile',
`signed', `typeof' and `inline' won't work in a program compiled with
`-traditional'.  The ISO C99 keyword `restrict' is only available when
`-std=gnu99' (which will eventually be the default) or `-std=c99' (or
the equivalent `-std=iso9899:1999') is used.

   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

   `-pedantic' and other options cause warnings for many GNU C
extensions.  You can prevent such warnings within one expression by
writing `__extension__' before the expression.  `__extension__' has no
effect aside from this.


File: gcc.info,  Node: Incomplete Enums,  Next: Function Names,  Prev: Alternate Keywords,  Up: C Extensions

Incomplete `enum' Types
=======================

   You can define an `enum' tag without specifying its possible values.
This results in an incomplete type, much like what you get if you write
`struct foo' without describing the elements.  A later declaration
which does specify the possible values completes the type.

   You can't allocate variables or storage using the type while it is
incomplete.  However, you can work with pointers to that type.

   This extension may not be very useful, but it makes the handling of
`enum' more consistent with the way `struct' and `union' are handled.

   This extension is not supported by GNU C++.


File: gcc.info,  Node: Function Names,  Next: Return Address,  Prev: Incomplete Enums,  Up: C Extensions

Function Names as Strings
=========================

   GCC predefines two magic identifiers to hold the name of the current
function.  The identifier `__FUNCTION__' holds the name of the function
as it appears in the source.  The identifier `__PRETTY_FUNCTION__'
holds the name of the function pretty printed in a language specific
fashion.

   These names are always the same in a C function, but in a C++
function they may be different.  For example, this program:

     extern "C" {
     extern int printf (char *, ...);
     }
     
     class a {
      public:
       sub (int i)
         {
           printf ("__FUNCTION__ = %s\n", __FUNCTION__);
           printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
         }
     };
     
     int
     main (void)
     {
       a ax;
       ax.sub (0);
       return 0;
     }

gives this output:

     __FUNCTION__ = sub
     __PRETTY_FUNCTION__ = int  a::sub (int)

   The compiler automagically replaces the identifiers with a string
literal containing the appropriate name.  Thus, they are neither
preprocessor macros, like `__FILE__' and `__LINE__', nor variables.
This means that they catenate with other string literals, and that they
can be used to initialize char arrays.  For example

     char here[] = "Function " __FUNCTION__ " in " __FILE__;

   On the other hand, `#ifdef __FUNCTION__' does not have any special
meaning inside a function, since the preprocessor does not do anything
special with the identifier `__FUNCTION__'.

   GCC also supports the magic word `__func__', defined by the ISO
standard C99:

     The identifier `__func__' is implicitly declared by the translator
     as if, immediately following the opening brace of each function
     definition, the declaration
          static const char __func__[] = "function-name";
     
     appeared, where function-name is the name of the lexically-enclosing
     function.  This name is the unadorned name of the function.

   By this definition, `__func__' is a variable, not a string literal.
In particular, `__func__' does not catenate with other string literals.

   In `C++', `__FUNCTION__' and `__PRETTY_FUNCTION__' are variables,
declared in the same way as `__func__'.


File: gcc.info,  Node: Return Address,  Next: Vector Extensions,  Prev: Function Names,  Up: C Extensions

Getting the Return or Frame Address of a Function
=================================================

   These functions may be used to get information about the callers of a
function.

 - Built-in Function: void * __builtin_return_address (unsigned int
          LEVEL)
     This function returns the return address of the current function,
     or of one of its callers.  The LEVEL argument is number of frames
     to scan up the call stack.  A value of `0' yields the return
     address of the current function, a value of `1' yields the return
     address of the caller of the current function, and so forth.

     The LEVEL argument must be a constant integer.

     On some machines it may be impossible to determine the return
     address of any function other than the current one; in such cases,
     or when the top of the stack has been reached, this function will
     return `0' or a random value. In addition,
     `__builtin_frame_address' may be used to determine if the top of
     the stack has been reached.

     This function should only be used with a nonzero argument for
     debugging purposes.

 - Built-in Function: void * __builtin_frame_address (unsigned int
          LEVEL)
     This function is similar to `__builtin_return_address', but it
     returns the address of the function frame rather than the return
     address of the function.  Calling `__builtin_frame_address' with a
     value of `0' yields the frame address of the current function, a
     value of `1' yields the frame address of the caller of the current
     function, and so forth.

     The frame is the area on the stack which holds local variables and
     saved registers.  The frame address is normally the address of the
     first word pushed on to the stack by the function.  However, the
     exact definition depends upon the processor and the calling
     convention.  If the processor has a dedicated frame pointer
     register, and the function has a frame, then
     `__builtin_frame_address' will return the value of the frame
     pointer register.

     On some machines it may be impossible to determine the frame
     address of any function other than the current one; in such cases,
     or when the top of the stack has been reached, this function will
     return `0' if the first frame pointer is properly initialized by
     the startup code.

     This function should only be used with a nonzero argument for
     debugging purposes.


File: gcc.info,  Node: Vector Extensions,  Next: Other Builtins,  Prev: Return Address,  Up: C Extensions

Using vector instructions through built-in functions
====================================================

   On some targets, the instruction set contains SIMD vector
instructions that operate on multiple values contained in one large
register at the same time.  For example, on the i386 the MMX, 3Dnow!
and SSE extensions can be used this way.

   The first step in using these extensions is to provide the necessary
data types.  This should be done using an appropriate `typedef':

     typedef int v4si __attribute__ ((mode(V4SI)));

   The base type `int' is effectively ignored by the compiler, the
actual properties of the new type `v4si' are defined by the
`__attribute__'.  It defines the machine mode to be used; for vector
types these have the form `VNB'; N should be the number of elements in
the vector, and B should be the base mode of the individual elements.
The following can be used as base modes:

`QI'
     An integer that is as wide as the smallest addressable unit,
     usually 8 bits.

`HI'
     An integer, twice as wide as a QI mode integer, usually 16 bits.

`SI'
     An integer, four times as wide as a QI mode integer, usually 32
     bits.

`DI'
     An integer, eight times as wide as a QI mode integer, usually 64
     bits.

`SF'
     A floating point value, as wide as a SI mode integer, usually 32
     bits.

`DF'
     A floating point value, as wide as a DI mode integer, usually 64
     bits.

   Not all base types or combinations are always valid; which modes can
be used is determined by the target machine.  For example, if
targetting the i386 MMX extensions, only `V8QI', `V4HI' and `V2SI' are
allowed modes.

   There are no `V1xx' vector modes - they would be identical to the
corresponding base mode.

   There is no distinction between signed and unsigned vector modes.
This distinction is made by the operations that perform on the vectors,
not by the data type.

   The types defined in this manner are somewhat special, they cannot be
used with most normal C operations (i.e., a vector addition can _not_
be represented by a normal addition of two vector type variables).  You
can declare only variables and use them in function calls and returns,
as well as in assignments and some casts.  It is possible to cast from
one vector type to another, provided they are of the same size (in
fact, you can also cast vectors to and from other datatypes of the same
size).

   A port that supports vector operations provides a set of built-in
functions that can be used to operate on vectors.  For example, a
function to add two vectors and multiply the result by a third could
look like this:

     v4si f (v4si a, v4si b, v4si c)
     {
       v4si tmp = __builtin_addv4si (a, b);
       return __builtin_mulv4si (tmp, c);
     }


File: gcc.info,  Node: Other Builtins,  Next: Pragmas,  Prev: Vector Extensions,  Up: C Extensions

Other built-in functions provided by GCC
========================================

   GCC provides a large number of built-in functions other than the ones
mentioned above.  Some of these are for internal use in the processing
of exceptions or variable-length argument lists and will not be
documented here because they may change from time to time; we do not
recommend general use of these functions.

   The remaining functions are provided for optimization purposes.

   GCC includes built-in versions of many of the functions in the
standard C library.  The versions prefixed with `__builtin_' will
always be treated as having the same meaning as the C library function
even if you specify the `-fno-builtin' option. (*note C Dialect
Options::) Many of these functions are only optimized in certain cases;
if they are not optimized in a particular case, a call to the library
function will be emitted.

   The functions `abort', `exit', `_Exit' and `_exit' are recognized
and presumed not to return, but otherwise are not built in.  `_exit' is
not recognized in strict ISO C mode (`-ansi', `-std=c89' or
`-std=c99').  `_Exit' is not recognized in strict C89 mode (`-ansi' or
`-std=c89').

   Outside strict ISO C mode, the functions `alloca', `bcmp', `bzero',
`index', `rindex' and `ffs' may be handled as built-in functions.  All
these functions have corresponding versions prefixed with `__builtin_',
which may be used even in strict C89 mode.

   The ISO C99 functions `conj', `conjf', `conjl', `creal', `crealf',
`creall', `cimag', `cimagf', `cimagl', `llabs' and `imaxabs' are
handled as built-in functions except in strict ISO C89 mode.  There are
also built-in versions of the ISO C99 functions `cosf', `cosl',
`fabsf', `fabsl', `sinf', `sinl', `sqrtf', and `sqrtl', that are
recognized in any mode since ISO C89 reserves these names for the
purpose to which ISO C99 puts them.  All these functions have
corresponding versions prefixed with `__builtin_'.

   The ISO C89 functions `abs', `cos', `fabs', `fprintf', `fputs',
`labs', `memcmp', `memcpy', `memset', `printf', `sin', `sqrt', `strcat',
`strchr', `strcmp', `strcpy', `strcspn', `strlen', `strncat',
`strncmp', `strncpy', `strpbrk', `strrchr', `strspn', and `strstr' are
all recognized as built-in functions unless `-fno-builtin' is
specified.  All of these functions have corresponding versions prefixed
with `__builtin_', except that the version for `sqrt' is called
`__builtin_fsqrt'.

   GCC provides built-in versions of the ISO C99 floating point
comparison macros that avoid raising exceptions for unordered operands.
They have the same names as the standard macros ( `isgreater',
`isgreaterequal', `isless', `islessequal', `islessgreater', and
`isunordered') , with `__builtin_' prefixed.  We intend for a library
implementor to be able to simply `#define' each standard macro to its
built-in equivalent.

 - Built-in Function: int __builtin_constant_p (EXP)
     You can use the built-in function `__builtin_constant_p' to
     determine if a value is known to be constant at compile-time and
     hence that GCC can perform constant-folding on expressions
     involving that value.  The argument of the function is the value
     to test.  The function returns the integer 1 if the argument is
     known to be a compile-time constant and 0 if it is not known to be
     a compile-time constant.  A return of 0 does not indicate that the
     value is _not_ a constant, but merely that GCC cannot prove it is
     a constant with the specified value of the `-O' option.

     You would typically use this function in an embedded application
     where memory was a critical resource.  If you have some complex
     calculation, you may want it to be folded if it involves
     constants, but need to call a function if it does not.  For
     example:

          #define Scale_Value(X)      \
            (__builtin_constant_p (X) \
            ? ((X) * SCALE + OFFSET) : Scale (X))

     You may use this built-in function in either a macro or an inline
     function.  However, if you use it in an inlined function and pass
     an argument of the function as the argument to the built-in, GCC
     will never return 1 when you call the inline function with a
     string constant or compound literal (*note Compound Literals::)
     and will not return 1 when you pass a constant numeric value to
     the inline function unless you specify the `-O' option.

     You may also use `__builtin_constant_p' in initializers for static
     data.  For instance, you can write

          static const int table[] = {
             __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
             /* ... */
          };

     This is an acceptable initializer even if EXPRESSION is not a
     constant expression.  GCC must be more conservative about
     evaluating the built-in in this case, because it has no
     opportunity to perform optimization.

     Previous versions of GCC did not accept this built-in in data
     initializers.  The earliest version where it is completely safe is
     3.0.1.

 - Built-in Function: long __builtin_expect (long EXP, long C)
     You may use `__builtin_expect' to provide the compiler with branch
     prediction information.  In general, you should prefer to use
     actual profile feedback for this (`-fprofile-arcs'), as
     programmers are notoriously bad at predicting how their programs
     actually perform.  However, there are applications in which this
     data is hard to collect.

     The return value is the value of EXP, which should be an integral
     expression.  The value of C must be a compile-time constant.  The
     semantics of the built-in are that it is expected that EXP == C.
     For example:

          if (__builtin_expect (x, 0))
            foo ();

     would indicate that we do not expect to call `foo', since we
     expect `x' to be zero.  Since you are limited to integral
     expressions for EXP, you should use constructions such as

          if (__builtin_expect (ptr != NULL, 1))
            error ();

     when testing pointer or floating-point values.


File: gcc.info,  Node: Pragmas,  Next: Unnamed Fields,  Prev: Other Builtins,  Up: C Extensions

Pragmas Accepted by GCC
=======================

   GCC supports several types of pragmas, primarily in order to compile
code originally written for other compilers.  Note that in general we
do not recommend the use of pragmas; *Note Function Attributes::, for
further explanation.

* Menu:

* ARM Pragmas::
* Darwin Pragmas::


File: gcc.info,  Node: ARM Pragmas,  Next: Darwin Pragmas,  Up: Pragmas

ARM Pragmas
-----------

   The ARM target defines pragmas for controlling the default addition
of `long_call' and `short_call' attributes to functions.  *Note
Function Attributes::, for information about the effects of these
attributes.

`long_calls'
     Set all subsequent functions to have the `long_call' attribute.

`no_long_calls'
     Set all subsequent functions to have the `short_call' attribute.

`long_calls_off'
     Do not affect the `long_call' or `short_call' attributes of
     subsequent functions.


File: gcc.info,  Node: Darwin Pragmas,  Prev: ARM Pragmas,  Up: Pragmas

Darwin Pragmas
--------------

   The following pragmas are available for all architectures running the
Darwin operating system.  These are useful for compatibility with other
MacOS compilers.

`mark TOKENS...'
     This pragma is accepted, but has no effect.

`options align=ALIGNMENT'
     This pragma sets the alignment of fields in structures.  The
     values of ALIGNMENT may be `mac68k', to emulate m68k alignment, or
     `power', to emulate PowerPC alignment.  Uses of this pragma nest
     properly; to restore the previous setting, use `reset' for the
     ALIGNMENT.

`segment TOKENS...'
     This pragma is accepted, but has no effect.

`unused (VAR [, VAR]...)'
     This pragma declares variables to be possibly unused.  GCC will not
     produce warnings for the listed variables.  The effect is similar
     to that of the `unused' attribute, except that this pragma may
     appear anywhere within the variables' scopes.


File: gcc.info,  Node: Unnamed Fields,  Prev: Pragmas,  Up: C Extensions

Unnamed struct/union fields within structs/unions.
==================================================

   For compatibility with other compilers, GCC allows you to define a
structure or union that contains, as fields, structures and unions
without names.  For example:

     struct {
       int a;
       union {
         int b;
         float c;
       };
       int d;
     } foo;

   In this example, the user would be able to access members of the
unnamed union with code like `foo.b'.  Note that only unnamed structs
and unions are allowed, you may not have, for example, an unnamed `int'.

   You must never create such structures that cause ambiguous field
definitions.  For example, this structure:

     struct {
       int a;
       struct {
         int a;
       };
     } foo;

   It is ambiguous which `a' is being referred to with `foo.a'.  Such
constructs are not supported and must be avoided.  In the future, such
constructs may be detected and treated as compilation errors.


File: gcc.info,  Node: C++ Extensions,  Next: Objective-C,  Prev: C Extensions,  Up: Top

Extensions to the C++ Language
******************************

   The GNU compiler provides these extensions to the C++ language (and
you can also use most of the C language extensions in your C++
programs).  If you want to write code that checks whether these
features are available, you can test for the GNU compiler the same way
as for C programs: check for a predefined macro `__GNUC__'.  You can
also use `__GNUG__' to test specifically for GNU C++ (*note Standard
Predefined Macros: (cpp.info)Standard Predefined.).

* Menu:

* Min and Max::		C++ Minimum and maximum operators.
* Volatiles::		What constitutes an access to a volatile object.
* Restricted Pointers:: C99 restricted pointers and references.
* Vague Linkage::       Where G++ puts inlines, vtables and such.
* C++ Interface::       You can use a single C++ header file for both
                        declarations and definitions.
* Template Instantiation:: Methods for ensuring that exactly one copy of
                        each needed template instantiation is emitted.
* Bound member functions:: You can extract a function pointer to the
                        method denoted by a `->*' or `.*' expression.
* C++ Attributes::      Variable, function, and type attributes for C++ only.
* Java Exceptions::     Tweaking exception handling to work with Java.
* Deprecated Features:: Things might disappear from g++.
* Backwards Compatibility:: Compatibilities with earlier definitions of C++.


File: gcc.info,  Node: Min and Max,  Next: Volatiles,  Up: C++ Extensions

Minimum and Maximum Operators in C++
====================================

   It is very convenient to have operators which return the "minimum"
or the "maximum" of two arguments.  In GNU C++ (but not in GNU C),

`A <? B'
     is the "minimum", returning the smaller of the numeric values A
     and B;

`A >? B'
     is the "maximum", returning the larger of the numeric values A and
     B.

   These operations are not primitive in ordinary C++, since you can
use a macro to return the minimum of two things in C++, as in the
following example.

     #define MIN(X,Y) ((X) < (Y) ? : (X) : (Y))

You might then use `int min = MIN (i, j);' to set MIN to the minimum
value of variables I and J.

   However, side effects in `X' or `Y' may cause unintended behavior.
For example, `MIN (i++, j++)' will fail, incrementing the smaller
counter twice.  A GNU C extension allows you to write safe macros that
avoid this kind of problem (*note Naming an Expression's Type: Naming
Types.).  However, writing `MIN' and `MAX' as macros also forces you to
use function-call notation for a fundamental arithmetic operation.
Using GNU C++ extensions, you can write `int min = i <? j;' instead.

   Since `<?' and `>?' are built into the compiler, they properly
handle expressions with side-effects;  `int min = i++ <? j++;' works
correctly.

