This is gcc.info, produced by makeinfo version 4.2 from
/usr/src/gnu/usr.bin/gcc/gcc/doc/gcc.texi.

Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003 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.2 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.
INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* gcc: (gcc).                  The GNU Compiler Collection.
END-INFO-DIR-ENTRY
   This file documents the use of the GNU compilers.

   Published by the Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

File: gcc.info,  Node: Variable Attributes,  Next: Type Attributes,  Prev: Character Escapes,  Up: C Extensions

Specifying Attributes of Variables
==================================

   The keyword `__attribute__' allows you to specify special attributes
of variables or structure fields.  This keyword is followed by an
attribute specification inside double parentheses.  Some attributes are
currently defined generically for variables.  Other attributes are
defined for variables on particular target systems.  Other attributes
are available for functions (*note Function Attributes::) and for types
(*note Type Attributes::).  Other front ends might define more
attributes (*note Extensions to the C++ Language: C++ Extensions.).

   You may also specify attributes with `__' preceding and following
each keyword.  This allows you to use them in header files without
being concerned about a possible macro of the same name.  For example,
you may use `__aligned__' instead of `aligned'.

   *Note Attribute Syntax::, for details of the exact syntax for using
attributes.

`aligned (ALIGNMENT)'
     This attribute specifies a minimum alignment for the variable or
     structure field, measured in bytes.  For example, the declaration:

          int x __attribute__ ((aligned (16))) = 0;

     causes the compiler to allocate the global variable `x' on a
     16-byte boundary.  On a 68040, this could be used in conjunction
     with an `asm' expression to access the `move16' instruction which
     requires 16-byte aligned operands.

     You can also specify the alignment of structure fields.  For
     example, to create a double-word aligned `int' pair, you could
     write:

          struct foo { int x[2] __attribute__ ((aligned (8))); };

     This is an alternative to creating a union with a `double' member
     that forces the union to be double-word aligned.

     As in the preceding examples, you can explicitly specify the
     alignment (in bytes) that you wish the compiler to use for a given
     variable or structure field.  Alternatively, you can leave out the
     alignment factor and just ask the compiler to align a variable or
     field to the maximum useful alignment for the target machine you
     are compiling for.  For example, you could write:

          short array[3] __attribute__ ((aligned));

     Whenever you leave out the alignment factor in an `aligned'
     attribute specification, the compiler automatically sets the
     alignment for the declared variable or field to the largest
     alignment which is ever used for any data type on the target
     machine you are compiling for.  Doing this can often make copy
     operations more efficient, because the compiler can use whatever
     instructions copy the biggest chunks of memory when performing
     copies to or from the variables or fields that you have aligned
     this way.

     The `aligned' attribute can only increase the alignment; but you
     can decrease it by specifying `packed' as well.  See below.

     Note that the effectiveness of `aligned' attributes may be limited
     by inherent limitations in your linker.  On many systems, the
     linker is only able to arrange for variables to be aligned up to a
     certain maximum alignment.  (For some linkers, the maximum
     supported alignment may be very very small.)  If your linker is
     only able to align variables up to a maximum of 8 byte alignment,
     then specifying `aligned(16)' in an `__attribute__' will still
     only provide you with 8 byte alignment.  See your linker
     documentation for further information.

`cleanup (CLEANUP_FUNCTION)'
     The `cleanup' attribute runs a function when the variable goes out
     of scope.  This attribute can only be applied to auto function
     scope variables; it may not be applied to parameters or variables
     with static storage duration.  The function must take one
     parameter, a pointer to a type compatible with the variable.  The
     return value of the function (if any) is ignored.

     If `-fexceptions' is enabled, then CLEANUP_FUNCTION will be run
     during the stack unwinding that happens during the processing of
     the exception.  Note that the `cleanup' attribute does not allow
     the exception to be caught, only to perform an action.  It is
     undefined what happens if CLEANUP_FUNCTION does not return
     normally.

`common'
`nocommon'
     The `common' attribute requests GCC to place a variable in
     "common" storage.  The `nocommon' attribute requests the opposite
     - to allocate space for it directly.

     These attributes override the default chosen by the `-fno-common'
     and `-fcommon' flags respectively.

`deprecated'
     The `deprecated' attribute results in a warning if the variable is
     used anywhere in the source file.  This is useful when identifying
     variables that are expected to be removed in a future version of a
     program.  The warning also includes the location of the declaration
     of the deprecated variable, to enable users to easily find further
     information about why the variable is deprecated, or what they
     should do instead.  Note that the warning only occurs for uses:

          extern int old_var __attribute__ ((deprecated));
          extern int old_var;
          int new_fn () { return old_var; }

     results in a warning on line 3 but not line 2.

     The `deprecated' attribute can also be used for functions and
     types (*note Function Attributes::, *note Type Attributes::.)

`mode (MODE)'
     This attribute specifies the data type for the
     declaration--whichever type corresponds to the mode MODE.  This in
     effect lets you request an integer or floating point type
     according to its width.

     You may also specify a mode of `byte' or `__byte__' to indicate
     the mode corresponding to a one-byte integer, `word' or `__word__'
     for the mode of a one-word integer, and `pointer' or `__pointer__'
     for the mode used to represent pointers.

`packed'
     The `packed' attribute specifies that a variable or structure field
     should have the smallest possible alignment--one byte for a
     variable, and one bit for a field, unless you specify a larger
     value with the `aligned' attribute.

     Here is a structure in which the field `x' is packed, so that it
     immediately follows `a':

          struct foo
          {
            char a;
            int x[2] __attribute__ ((packed));
          };

`section ("SECTION-NAME")'
     Normally, the compiler places the objects it generates in sections
     like `data' and `bss'.  Sometimes, however, you need additional
     sections, or you need certain particular variables to appear in
     special sections, for example to map to special hardware.  The
     `section' attribute specifies that a variable (or function) lives
     in a particular section.  For example, this small program uses
     several specific section names:

          struct duart a __attribute__ ((section ("DUART_A"))) = { 0 };
          struct duart b __attribute__ ((section ("DUART_B"))) = { 0 };
          char stack[10000] __attribute__ ((section ("STACK"))) = { 0 };
          int init_data __attribute__ ((section ("INITDATA"))) = 0;
          
          main()
          {
            /* Initialize stack pointer */
            init_sp (stack + sizeof (stack));
          
            /* Initialize initialized data */
            memcpy (&init_data, &data, &edata - &data);
          
            /* Turn on the serial ports */
            init_duart (&a);
            init_duart (&b);
          }

     Use the `section' attribute with an _initialized_ definition of a
     _global_ variable, as shown in the example.  GCC issues a warning
     and otherwise ignores the `section' attribute in uninitialized
     variable declarations.

     You may only use the `section' attribute with a fully initialized
     global definition because of the way linkers work.  The linker
     requires each object be defined once, with the exception that
     uninitialized variables tentatively go in the `common' (or `bss')
     section and can be multiply "defined".  You can force a variable
     to be initialized with the `-fno-common' flag or the `nocommon'
     attribute.

     Some file formats do not support arbitrary sections so the
     `section' attribute is not available on all platforms.  If you
     need to map the entire contents of a module to a particular
     section, consider using the facilities of the linker instead.

`shared'
     On Windows, in addition to putting variable definitions in a named
     section, the section can also be shared among all running copies
     of an executable or DLL.  For example, this small program defines
     shared data by putting it in a named section `shared' and marking
     the section shareable:

          int foo __attribute__((section ("shared"), shared)) = 0;
          
          int
          main()
          {
            /* Read and write foo.  All running
               copies see the same value.  */
            return 0;
          }

     You may only use the `shared' attribute along with `section'
     attribute with a fully initialized global definition because of
     the way linkers work.  See `section' attribute for more
     information.

     The `shared' attribute is only available on Windows.

`tls_model ("TLS_MODEL")'
     The `tls_model' attribute sets thread-local storage model (*note
     Thread-Local::) of a particular `__thread' variable, overriding
     `-ftls-model=' command line switch on a per-variable basis.  The
     TLS_MODEL argument should be one of `global-dynamic',
     `local-dynamic', `initial-exec' or `local-exec'.

     Not all targets support this attribute.

`transparent_union'
     This attribute, attached to a function parameter which is a union,
     means that the corresponding argument may have the type of any
     union member, but the argument is passed as if its type were that
     of the first union member.  For more details see *Note Type
     Attributes::.  You can also use this attribute on a `typedef' for
     a union data type; then it applies to all function parameters with
     that type.

`unused'
     This attribute, attached to a variable, means that the variable is
     meant to be possibly unused.  GCC will not produce a warning for
     this variable.

`vector_size (BYTES)'
     This attribute specifies the vector size for the variable,
     measured in bytes.  For example, the declaration:

          int foo __attribute__ ((vector_size (16)));

     causes the compiler to set the mode for `foo', to be 16 bytes,
     divided into `int' sized units.  Assuming a 32-bit int (a vector of
     4 units of 4 bytes), the corresponding mode of `foo' will be V4SI.

     This attribute is only applicable to integral and float scalars,
     although arrays, pointers, and function return values are allowed
     in conjunction with this construct.

     Aggregates with this attribute are invalid, even if they are of
     the same size as a corresponding scalar.  For example, the
     declaration:

          struct S { int a; };
          struct S  __attribute__ ((vector_size (16))) foo;

     is invalid even if the size of the structure is the same as the
     size of the `int'.

`weak'
     The `weak' attribute is described in *Note Function Attributes::.

`model (MODEL-NAME)'
     Use this attribute on the M32R/D to set the addressability of an
     object.  The identifier MODEL-NAME is one of `small', `medium', or
     `large', representing each of the code models.

     Small model objects live in the lower 16MB of memory (so that their
     addresses can be loaded with the `ld24' instruction).

     Medium and large model objects may live anywhere in the 32-bit
     address space (the compiler will generate `seth/add3' instructions
     to load their addresses).

`dllimport'
     The `dllimport' attribute is described in *Note Function
     Attributes::.

`dlexport'
     The `dllexport' attribute is described in *Note Function
     Attributes::.

   To specify multiple attributes, separate them by commas within the
double parentheses: for example, `__attribute__ ((aligned (16),
packed))'.


File: gcc.info,  Node: Type Attributes,  Next: Alignment,  Prev: Variable Attributes,  Up: C Extensions

Specifying Attributes of Types
==============================

   The keyword `__attribute__' allows you to specify special attributes
of `struct' and `union' types when you define such types.  This keyword
is followed by an attribute specification inside double parentheses.
Six attributes are currently defined for types: `aligned', `packed',
`transparent_union', `unused', `deprecated' and `may_alias'.  Other
attributes are defined for functions (*note Function Attributes::) and
for variables (*note Variable Attributes::).

   You may also specify any one of these attributes with `__' preceding
and following its keyword.  This allows you to use these attributes in
header files without being concerned about a possible macro of the same
name.  For example, you may use `__aligned__' instead of `aligned'.

   You may specify the `aligned' and `transparent_union' attributes
either in a `typedef' declaration or just past the closing curly brace
of a complete enum, struct or union type _definition_ and the `packed'
attribute only past the closing brace of a definition.

   You may also specify attributes between the enum, struct or union
tag and the name of the type rather than after the closing brace.

   *Note Attribute Syntax::, for details of the exact syntax for using
attributes.

`aligned (ALIGNMENT)'
     This attribute specifies a minimum alignment (in bytes) for
     variables of the specified type.  For example, the declarations:

          struct S { short f[3]; } __attribute__ ((aligned (8)));
          typedef int more_aligned_int __attribute__ ((aligned (8)));

     force the compiler to insure (as far as it can) that each variable
     whose type is `struct S' or `more_aligned_int' will be allocated
     and aligned _at least_ on a 8-byte boundary.  On a SPARC, having
     all variables of type `struct S' aligned to 8-byte boundaries
     allows the compiler to use the `ldd' and `std' (doubleword load and
     store) instructions when copying one variable of type `struct S' to
     another, thus improving run-time efficiency.

     Note that the alignment of any given `struct' or `union' type is
     required by the ISO C standard to be at least a perfect multiple of
     the lowest common multiple of the alignments of all of the members
     of the `struct' or `union' in question.  This means that you _can_
     effectively adjust the alignment of a `struct' or `union' type by
     attaching an `aligned' attribute to any one of the members of such
     a type, but the notation illustrated in the example above is a
     more obvious, intuitive, and readable way to request the compiler
     to adjust the alignment of an entire `struct' or `union' type.

     As in the preceding example, you can explicitly specify the
     alignment (in bytes) that you wish the compiler to use for a given
     `struct' or `union' type.  Alternatively, you can leave out the
     alignment factor and just ask the compiler to align a type to the
     maximum useful alignment for the target machine you are compiling
     for.  For example, you could write:

          struct S { short f[3]; } __attribute__ ((aligned));

     Whenever you leave out the alignment factor in an `aligned'
     attribute specification, the compiler automatically sets the
     alignment for the type to the largest alignment which is ever used
     for any data type on the target machine you are compiling for.
     Doing this can often make copy operations more efficient, because
     the compiler can use whatever instructions copy the biggest chunks
     of memory when performing copies to or from the variables which
     have types that you have aligned this way.

     In the example above, if the size of each `short' is 2 bytes, then
     the size of the entire `struct S' type is 6 bytes.  The smallest
     power of two which is greater than or equal to that is 8, so the
     compiler sets the alignment for the entire `struct S' type to 8
     bytes.

     Note that although you can ask the compiler to select a
     time-efficient alignment for a given type and then declare only
     individual stand-alone objects of that type, the compiler's
     ability to select a time-efficient alignment is primarily useful
     only when you plan to create arrays of variables having the
     relevant (efficiently aligned) type.  If you declare or use arrays
     of variables of an efficiently-aligned type, then it is likely
     that your program will also be doing pointer arithmetic (or
     subscripting, which amounts to the same thing) on pointers to the
     relevant type, and the code that the compiler generates for these
     pointer arithmetic operations will often be more efficient for
     efficiently-aligned types than for other types.

     The `aligned' attribute can only increase the alignment; but you
     can decrease it by specifying `packed' as well.  See below.

     Note that the effectiveness of `aligned' attributes may be limited
     by inherent limitations in your linker.  On many systems, the
     linker is only able to arrange for variables to be aligned up to a
     certain maximum alignment.  (For some linkers, the maximum
     supported alignment may be very very small.)  If your linker is
     only able to align variables up to a maximum of 8 byte alignment,
     then specifying `aligned(16)' in an `__attribute__' will still
     only provide you with 8 byte alignment.  See your linker
     documentation for further information.

`packed'
     This attribute, attached to an `enum', `struct', or `union' type
     definition, specifies that the minimum required memory be used to
     represent the type.

     Specifying this attribute for `struct' and `union' types is
     equivalent to specifying the `packed' attribute on each of the
     structure or union members.  Specifying the `-fshort-enums' flag
     on the line is equivalent to specifying the `packed' attribute on
     all `enum' definitions.

     You may only specify this attribute after a closing curly brace on
     an `enum' definition, not in a `typedef' declaration, unless that
     declaration also contains the definition of the `enum'.

`transparent_union'
     This attribute, attached to a `union' type definition, indicates
     that any function parameter having that union type causes calls to
     that function to be treated in a special way.

     First, the argument corresponding to a transparent union type can
     be of any type in the union; no cast is required.  Also, if the
     union contains a pointer type, the corresponding argument can be a
     null pointer constant or a void pointer expression; and if the
     union contains a void pointer type, the corresponding argument can
     be any pointer expression.  If the union member type is a pointer,
     qualifiers like `const' on the referenced type must be respected,
     just as with normal pointer conversions.

     Second, the argument is passed to the function using the calling
     conventions of the first member of the transparent union, not the
     calling conventions of the union itself.  All members of the union
     must have the same machine representation; this is necessary for
     this argument passing to work properly.

     Transparent unions are designed for library functions that have
     multiple interfaces for compatibility reasons.  For example,
     suppose the `wait' function must accept either a value of type
     `int *' to comply with Posix, or a value of type `union wait *' to
     comply with the 4.1BSD interface.  If `wait''s parameter were
     `void *', `wait' would accept both kinds of arguments, but it
     would also accept any other pointer type and this would make
     argument type checking less useful.  Instead, `<sys/wait.h>' might
     define the interface as follows:

          typedef union
            {
              int *__ip;
              union wait *__up;
            } wait_status_ptr_t __attribute__ ((__transparent_union__));
          
          pid_t wait (wait_status_ptr_t);

     This interface allows either `int *' or `union wait *' arguments
     to be passed, using the `int *' calling convention.  The program
     can call `wait' with arguments of either type:

          int w1 () { int w; return wait (&w); }
          int w2 () { union wait w; return wait (&w); }

     With this interface, `wait''s implementation might look like this:

          pid_t wait (wait_status_ptr_t p)
          {
            return waitpid (-1, p.__ip, 0);
          }

`unused'
     When attached to a type (including a `union' or a `struct'), this
     attribute means that variables of that type are meant to appear
     possibly unused.  GCC will not produce a warning for any variables
     of that type, even if the variable appears to do nothing.  This is
     often the case with lock or thread classes, which are usually
     defined and then not referenced, but contain constructors and
     destructors that have nontrivial bookkeeping functions.

`deprecated'
     The `deprecated' attribute results in a warning if the type is
     used anywhere in the source file.  This is useful when identifying
     types that are expected to be removed in a future version of a
     program.  If possible, the warning also includes the location of
     the declaration of the deprecated type, to enable users to easily
     find further information about why the type is deprecated, or what
     they should do instead.  Note that the warnings only occur for
     uses and then only if the type is being applied to an identifier
     that itself is not being declared as deprecated.

          typedef int T1 __attribute__ ((deprecated));
          T1 x;
          typedef T1 T2;
          T2 y;
          typedef T1 T3 __attribute__ ((deprecated));
          T3 z __attribute__ ((deprecated));

     results in a warning on line 2 and 3 but not lines 4, 5, or 6.  No
     warning is issued for line 4 because T2 is not explicitly
     deprecated.  Line 5 has no warning because T3 is explicitly
     deprecated.  Similarly for line 6.

     The `deprecated' attribute can also be used for functions and
     variables (*note Function Attributes::, *note Variable
     Attributes::.)

`may_alias'
     Accesses to objects with types with this attribute are not
     subjected to type-based alias analysis, but are instead assumed to
     be able to alias any other type of objects, just like the `char'
     type.  See `-fstrict-aliasing' for more information on aliasing
     issues.

     Example of use:

          typedef short __attribute__((__may_alias__)) short_a;
          
          int
          main (void)
          {
            int a = 0x12345678;
            short_a *b = (short_a *) &a;
          
            b[1] = 0;
          
            if (a == 0x12345678)
              abort();
          
            exit(0);
          }

     If you replaced `short_a' with `short' in the variable
     declaration, the above program would abort when compiled with
     `-fstrict-aliasing', which is on by default at `-O2' or above in
     recent GCC versions.

   To specify multiple attributes, separate them by commas within the
double parentheses: for example, `__attribute__ ((aligned (16),
packed))'.


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

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

   By declaring a function `inline', you can direct GCC 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.  The effect on code size is
less predictable; object code may be larger or smaller with function
inlining, depending on the particular case.  Inlining of functions is an
optimization and it really "works" only in optimizing compilation.  If
you don't use `-O', no function is really inline.

   Inline functions are included in the ISO C99 standard, but there are
currently substantial differences between what GCC implements and what
the ISO C99 standard requires.

   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 ISO 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.  Among these usages are: use of
varargs, use of alloca, use of variable sized data types (*note
Variable Length::), use of computed goto (*note Labels as Values::),
use of nonlocal goto, and nested functions (*note Nested Functions::).
Using `-Winline' will warn when a function marked `inline' could not be
substituted, and will give the reason for the failure.

   Note that in C and Objective-C, unlike C++, the `inline' keyword
does not affect the linkage of the function.

   GCC automatically inlines member functions defined within the class
body of C++ programs even if they are not explicitly declared `inline'.
(You can override this with `-fno-default-inline'; *note Options
Controlling C++ Dialect: C++ Dialect Options..)

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

   Since GCC eventually will implement ISO C99 semantics for inline
functions, it is best to use `static inline' only to guarentee
compatibility.  (The existing semantics will remain available when
`-std=gnu89' is specified, but eventually the default will be
`-std=gnu99' and that will implement the C99 semantics, though it does
not do so yet.)

   GCC does not inline any functions when not optimizing unless you
specify the `always_inline' attribute for the function, like this:

     /* Prototype.  */
     inline void foo (const char) __attribute__((always_inline));


File: gcc.info,  Node: Extended Asm,  Next: Constraints,  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 you 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.  Variables declared to live in specific registers
(*note Explicit Reg Vars::), and used as asm input or output operands
must have no part mentioned in the clobber description.  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: Constraints,  Next: Asm Labels,  Prev: Extended Asm,  Up: C Extensions

Constraints for `asm' Operands
==============================

   Here are specific details on what constraint letters you can use with
`asm' operands.  Constraints can say whether an operand may be in a
register, and which kinds of register; whether the operand can be a
memory reference, and which kinds of address; whether the operand may
be an immediate constant, and which possible values it may have.
Constraints can also require two operands to match.

* Menu:

* Simple Constraints::  Basic use of constraints.
* Multi-Alternative::   When an insn has two alternative constraint-patterns.
* Modifiers::           More precise control over effects of constraints.
* Machine Constraints:: Special constraints for some particular machines.

