+ #define max(a,b) ((a) > (b) ? (a) : (b))
+
+But this definition computes either A or B twice, with bad results if
+the operand has side effects. In GNU C, if you know the type of the
+operands (here let's assume `int'), you can define the macro safely as
+follows:
+
+ #define maxint(a,b) \
+ ({int _a = (a), _b = (b); _a > _b ? _a : _b; })
+
+ Embedded statements are not allowed in constant expressions, such as
+the value of an enumeration constant, the width of a bit-field, or the
+initial value of a static variable.
+
+ If you don't know the type of the operand, you can still do this,
+but you must use `typeof' (*note Typeof::).
+
+ Statement expressions are not supported fully in G++, and their fate
+there is unclear. (It is possible that they will become fully supported
+at some point, or that they will be deprecated, or that the bugs that
+are present will continue to exist indefinitely.) Presently, statement
+expressions do not work well as default arguments.
+
+ In addition, there are semantic issues with statement-expressions in
+C++. If you try to use statement-expressions instead of inline
+functions in C++, you may be surprised at the way object destruction is
+handled. For example:
+
+ #define foo(a) ({int b = (a); b + 3; })
+
+does not work the same way as:
+
+ inline int foo(int a) { int b = a; return b + 3; }
+
+In particular, if the expression passed into `foo' involves the
+creation of temporaries, the destructors for those temporaries will be
+run earlier in the case of the macro than in the case of the function.
+
+ These considerations mean that it is probably a bad idea to use
+statement-expressions of this form in header files that are designed to
+work with C++. (Note that some versions of the GNU C Library contained
+header files using statement-expression that lead to precisely this
+bug.)
+
+\1f
+File: gcc.info, Node: Local Labels, Next: Labels as Values, Prev: Statement Exprs, Up: C Extensions
+
+5.2 Locally Declared Labels
+===========================
+
+Each statement expression is a scope in which "local labels" can be
+declared. A local label is simply an identifier; you can jump to it
+with an ordinary `goto' statement, but only from within the statement
+expression it belongs to.
+
+ A local label declaration looks like this:
+
+ __label__ LABEL;
+
+or
+
+ __label__ LABEL1, LABEL2, ...;
+
+ Local label declarations must come at the beginning of the statement
+expression, right after the `({', before any ordinary declarations.
+
+ The label declaration defines the label _name_, but does not define
+the label itself. You must do this in the usual way, with `LABEL:',
+within the statements of the statement expression.
+
+ The local label feature is useful because statement expressions are
+often used in macros. If the macro contains nested loops, a `goto' can
+be useful for breaking out of them. However, an ordinary label whose
+scope is the whole function cannot be used: if the macro can be
+expanded several times in one function, the label will be multiply
+defined in that function. A local label avoids this problem. For
+example:
+
+ #define SEARCH(array, target) \
+ ({ \
+ __label__ found; \
+ typeof (target) _SEARCH_target = (target); \
+ typeof (*(array)) *_SEARCH_array = (array); \
+ int i, j; \
+ int value; \
+ for (i = 0; i < max; i++) \
+ for (j = 0; j < max; j++) \
+ if (_SEARCH_array[i][j] == _SEARCH_target) \
+ { value = i; goto found; } \
+ value = -1; \
+ found: \
+ value; \
+ })
+
+\1f
+File: gcc.info, Node: Labels as Values, Next: Nested Functions, Prev: Local Labels, Up: C Extensions
+
+5.3 Labels as Values
+====================
+
+You can get the address of a label defined in the current function (or
+a containing function) with the unary operator `&&'. The value has
+type `void *'. This value is a constant and can be used wherever a
+constant of that type is valid. For example:
+
+ void *ptr;
+ ...
+ ptr = &&foo;
+
+ To use these values, you need to be able to jump to one. This is
+done with the computed goto statement(1), `goto *EXP;'. For example,
+
+ goto *ptr;
+
+Any expression of type `void *' is allowed.
+
+ One way of using these constants is in initializing a static array
+that will serve as a jump table:
+
+ static void *array[] = { &&foo, &&bar, &&hack };
+
+ Then you can select a label with indexing, like this:
+
+ goto *array[i];
+
+Note that this does not check whether the subscript is in bounds--array
+indexing in C never does that.
+
+ Such an array of label values serves a purpose much like that of the
+`switch' statement. The `switch' statement is cleaner, so use that
+rather than an array unless the problem does not fit a `switch'
+statement very well.
+
+ Another use of label values is in an interpreter for threaded code.
+The labels within the interpreter function can be stored in the
+threaded code for super-fast dispatching.
+
+ You may not use this mechanism to jump to code in a different
+function. If you do that, totally unpredictable things will happen.
+The best way to avoid this is to store the label address only in
+automatic variables and never pass it as an argument.
+
+ An alternate way to write the above example is
+
+ static const int array[] = { &&foo - &&foo, &&bar - &&foo,
+ &&hack - &&foo };
+ goto *(&&foo + array[i]);
+
+This is more friendly to code living in shared libraries, as it reduces
+the number of dynamic relocations that are needed, and by consequence,
+allows the data to be read-only.
+
+ ---------- Footnotes ----------
+
+ (1) The analogous feature in Fortran is called an assigned goto, but
+that name seems inappropriate in C, where one can do more than simply
+store label addresses in label variables.
+
+\1f
+File: gcc.info, Node: Nested Functions, Next: Constructing Calls, Prev: Labels as Values, Up: C Extensions
+
+5.4 Nested Functions
+====================
+
+A "nested function" is a function defined inside another function.
+(Nested functions are not supported for GNU C++.) The nested function's
+name is local to the block where it is defined. For example, here we
+define a nested function named `square', and call it twice:
+
+ foo (double a, double b)
+ {
+ double square (double z) { return z * z; }
+
+ return square (a) + square (b);
+ }
+
+ The nested function can access all the variables of the containing
+function that are visible at the point of its definition. This is
+called "lexical scoping". For example, here we show a nested function
+which uses an inherited variable named `offset':
+
+ bar (int *array, int offset, int size)
+ {
+ int access (int *array, int index)
+ { return array[index + offset]; }
+ int i;
+ ...
+ for (i = 0; i < size; i++)
+ ... access (array, i) ...
+ }
+
+ Nested function definitions are permitted within functions in the
+places where variable definitions are allowed; that is, in any block,
+before the first statement in the block.
+
+ It is possible to call the nested function from outside the scope of
+its name by storing its address or passing the address to another
+function:
+
+ hack (int *array, int size)
+ {
+ void store (int index, int value)
+ { array[index] = value; }
+
+ intermediate (store, size);
+ }
+
+ Here, the function `intermediate' receives the address of `store' as
+an argument. If `intermediate' calls `store', the arguments given to
+`store' are used to store into `array'. But this technique works only
+so long as the containing function (`hack', in this example) does not
+exit.
+
+ If you try to call the nested function through its address after the
+containing function has exited, all hell will break loose. If you try
+to call it after a containing scope level has exited, and if it refers
+to some of the variables that are no longer in scope, you may be lucky,
+but it's not wise to take the risk. If, however, the nested function
+does not refer to anything that has gone out of scope, you should be
+safe.
+
+ GCC implements taking the address of a nested function using a
+technique called "trampolines". A paper describing them is available as
+
+`http://people.debian.org/~aaronl/Usenix88-lexic.pdf'.
+
+ A nested function can jump to a label inherited from a containing
+function, provided the label was explicitly declared in the containing
+function (*note Local Labels::). Such a jump returns instantly to the
+containing function, exiting the nested function which did the `goto'
+and any intermediate functions as well. Here is an example:
+
+ bar (int *array, int offset, int size)
+ {
+ __label__ failure;
+ int access (int *array, int index)
+ {
+ if (index > size)
+ goto failure;
+ return array[index + offset];
+ }
+ int i;
+ ...
+ for (i = 0; i < size; i++)
+ ... access (array, i) ...
+ ...
+ return 0;
+
+ /* Control comes here from `access'
+ if it detects an error. */
+ failure:
+ return -1;
+ }
+
+ A nested function always has internal linkage. Declaring one with
+`extern' is erroneous. If you need to declare the nested function
+before its definition, use `auto' (which is otherwise meaningless for
+function declarations).
+
+ bar (int *array, int offset, int size)
+ {
+ __label__ failure;
+ auto int access (int *, int);
+ ...
+ int access (int *array, int index)
+ {
+ if (index > size)
+ goto failure;
+ return array[index + offset];
+ }
+ ...
+ }
+
+\1f
+File: gcc.info, Node: Constructing Calls, Next: Typeof, Prev: Nested Functions, Up: C Extensions
+
+5.5 Constructing Function Calls
+===============================
+
+Using the built-in functions described below, you can record the
+arguments a function received, and call another function with the same
+arguments, without knowing the number or types of the arguments.
+
+ You can also record the return value of that function call, and
+later return that value, without knowing what data type the function
+tried to return (as long as your caller expects that data type).
+
+ -- Built-in Function: void * __builtin_apply_args ()
+ This built-in function returns a pointer to data describing how to
+ perform a call with the same arguments as were passed to the
+ current function.
+
+ The function saves the arg pointer register, structure value
+ address, and all registers that might be used to pass arguments to
+ a function into a block of memory allocated on the stack. Then it
+ returns the address of that block.
+
+ -- Built-in Function: void * __builtin_apply (void (*FUNCTION)(), void
+ *ARGUMENTS, size_t SIZE)
+ This built-in function invokes FUNCTION with a copy of the
+ parameters described by ARGUMENTS and SIZE.
+
+ The value of ARGUMENTS should be the value returned by
+ `__builtin_apply_args'. The argument SIZE specifies the size of
+ the stack argument data, in bytes.
+
+ This function returns a pointer to data describing how to return
+ whatever value was returned by FUNCTION. The data is saved in a
+ block of memory allocated on the stack.
+
+ It is not always simple to compute the proper value for SIZE. The
+ value is used by `__builtin_apply' to compute the amount of data
+ that should be pushed on the stack and copied from the incoming
+ argument area.
+
+ -- Built-in Function: void __builtin_return (void *RESULT)
+ This built-in function returns the value described by RESULT from
+ the containing function. You should specify, for RESULT, a value
+ returned by `__builtin_apply'.
+
+\1f
+File: gcc.info, Node: Typeof, Next: Lvalues, Prev: Constructing Calls, Up: C Extensions
+
+5.6 Referring to a Type with `typeof'
+=====================================
+
+Another way to refer to the type of an expression is with `typeof'.
+The syntax of using of this keyword looks like `sizeof', but the
+construct acts semantically like a type name defined with `typedef'.
+
+ There are two ways of writing the argument to `typeof': with an
+expression or with a type. Here is an example with an expression:
+
+ typeof (x[0](1))
+
+This assumes that `x' is an array of pointers to functions; the type
+described is that of the values of the functions.
+
+ Here is an example with a typename as the argument:
+
+ typeof (int *)
+
+Here the type described is that of pointers to `int'.
+
+ If you are writing a header file that must work when included in ISO
+C programs, write `__typeof__' instead of `typeof'. *Note Alternate
+Keywords::.
+
+ A `typeof'-construct can be used anywhere a typedef name could be
+used. For example, you can use it in a declaration, in a cast, or
+inside of `sizeof' or `typeof'.
+
+ `typeof' is often useful in conjunction with the
+statements-within-expressions feature. Here is how the two together can
+be used to define a safe "maximum" macro that operates on any
+arithmetic type and evaluates each of its arguments exactly once:
+
+ #define max(a,b) \
+ ({ typeof (a) _a = (a); \
+ typeof (b) _b = (b); \
+ _a > _b ? _a : _b; })
+
+ The reason for using names that start with underscores for the local
+variables is to avoid conflicts with variable names that occur within
+the expressions that are substituted for `a' and `b'. Eventually we
+hope to design a new form of declaration syntax that allows you to
+declare variables whose scopes start only after their initializers;
+this will be a more reliable way to prevent such conflicts.
+
+Some more examples of the use of `typeof':
+
+ * This declares `y' with the type of what `x' points to.
+
+ typeof (*x) y;
+
+ * This declares `y' as an array of such values.
+
+ typeof (*x) y[4];
+
+ * This declares `y' as an array of pointers to characters:
+
+ typeof (typeof (char *)[4]) y;
+
+ It is equivalent to the following traditional C declaration:
+
+ char *y[4];
+
+ To see the meaning of the declaration using `typeof', and why it
+ might be a useful way to write, let's rewrite it with these macros:
+
+ #define pointer(T) typeof(T *)
+ #define array(T, N) typeof(T [N])
+
+ Now the declaration can be rewritten this way:
+
+ array (pointer (char), 4) y;
+
+ Thus, `array (pointer (char), 4)' is the type of arrays of 4
+ pointers to `char'.
+
+ _Compatibility Note:_ In addition to `typeof', GCC 2 supported a
+more limited extension which permitted one to write
+
+ typedef T = EXPR;
+
+with the effect of declaring T to have the type of the expression EXPR.
+This extension does not work with GCC 3 (versions between 3.0 and 3.2
+will crash; 3.2.1 and later give an error). Code which relies on it
+should be rewritten to use `typeof':
+
+ typedef typeof(EXPR) T;
+
+This will work with all versions of GCC.
+
+\1f
+File: gcc.info, Node: Lvalues, Next: Conditionals, Prev: Typeof, Up: C Extensions
+
+5.7 Generalized Lvalues
+=======================
+
+Compound expressions, conditional expressions and casts are allowed as
+lvalues provided their operands are lvalues. This means that you can
+take their addresses or store values into them.
+
+ Standard C++ allows compound expressions and conditional expressions
+as lvalues, and permits casts to reference type, so use of this
+extension is deprecated for C++ code.
+
+ For example, a compound expression can be assigned, provided the last
+expression in the sequence is an lvalue. These two expressions are
+equivalent:
+
+ (a, b) += 5
+ a, (b += 5)
+
+ Similarly, the address of the compound expression can be taken.
+These two expressions are equivalent:
+
+ &(a, b)
+ a, &b
+
+ A conditional expression is a valid lvalue if its type is not void
+and the true and false branches are both valid lvalues. For example,
+these two expressions are equivalent:
+
+ (a ? b : c) = 5
+ (a ? b = 5 : (c = 5))
+
+ A cast is a valid lvalue if its operand is an lvalue. A simple
+assignment whose left-hand side is a cast works by converting the
+right-hand side first to the specified type, then to the type of the
+inner left-hand side expression. After this is stored, the value is
+converted back to the specified type to become the value of the
+assignment. Thus, if `a' has type `char *', the following two
+expressions are equivalent:
+
+ (int)a = 5
+ (int)(a = (char *)(int)5)
+
+ An assignment-with-arithmetic operation such as `+=' applied to a
+cast performs the arithmetic using the type resulting from the cast,
+and then continues as in the previous case. Therefore, these two
+expressions are equivalent:
+
+ (int)a += 5
+ (int)(a = (char *)(int) ((int)a + 5))
+
+ You cannot take the address of an lvalue cast, because the use of its
+address would not work out coherently. Suppose that `&(int)f' were
+permitted, where `f' has type `float'. Then the following statement
+would try to store an integer bit-pattern where a floating point number
+belongs:
+
+ *&(int)f = 1;
+
+ This is quite different from what `(int)f = 1' would do--that would
+convert 1 to floating point and store it. Rather than cause this
+inconsistency, we think it is better to prohibit use of `&' on a cast.
+
+ If you really do want an `int *' pointer with the address of `f',
+you can simply write `(int *)&f'.
+
+\1f
+File: gcc.info, Node: Conditionals, Next: Long Long, Prev: Lvalues, Up: C Extensions
+
+5.8 Conditionals with Omitted Operands
+======================================
+
+The middle operand in a conditional expression may be omitted. Then if
+the first operand is nonzero, its value is the value of the conditional
+expression.
+
+ Therefore, the expression
+
+ x ? : y
+
+has the value of `x' if that is nonzero; otherwise, the value of `y'.
+
+ This example is perfectly equivalent to
+
+ x ? x : y
+
+In this simple case, the ability to omit the middle operand is not
+especially useful. When it becomes useful is when the first operand
+does, or may (if it is a macro argument), contain a side effect. Then
+repeating the operand in the middle would perform the side effect
+twice. Omitting the middle operand uses the value already computed
+without the undesirable effects of recomputing it.
+
+\1f
+File: gcc.info, Node: Long Long, Next: Complex, Prev: Conditionals, Up: C Extensions
+
+5.9 Double-Word Integers
+========================
+
+ISO C99 supports data types for integers that are at least 64 bits wide,
+and as an extension GCC supports them in C89 mode and in C++. Simply
+write `long long int' for a signed integer, or `unsigned long long int'
+for an unsigned integer. To make an integer constant of type `long
+long int', add the suffix `LL' to the integer. To make an integer
+constant of type `unsigned long long int', add the suffix `ULL' to the
+integer.
+
+ You can use these types in arithmetic like any other integer types.
+Addition, subtraction, and bitwise boolean operations on these types
+are open-coded on all types of machines. Multiplication is open-coded
+if the machine supports fullword-to-doubleword a widening multiply
+instruction. Division and shifts are open-coded only on machines that
+provide special support. The operations that are not open-coded use
+special library routines that come with GCC.
+
+ There may be pitfalls when you use `long long' types for function
+arguments, unless you declare function prototypes. If a function
+expects type `int' for its argument, and you pass a value of type `long
+long int', confusion will result because the caller and the subroutine
+will disagree about the number of bytes for the argument. Likewise, if
+the function expects `long long int' and you pass `int'. The best way
+to avoid such problems is to use prototypes.
+
+\1f
+File: gcc.info, Node: Complex, Next: Hex Floats, Prev: Long Long, Up: C Extensions
+
+5.10 Complex Numbers
+====================
+
+ISO C99 supports complex floating data types, and as an extension GCC
+supports them in C89 mode and in C++, and supports complex integer data
+types which are not part of ISO C99. You can declare complex types
+using the keyword `_Complex'. As an extension, the older GNU keyword
+`__complex__' is also supported.
+
+ For example, `_Complex double x;' declares `x' as a variable whose
+real part and imaginary part are both of type `double'. `_Complex
+short int y;' declares `y' to have real and imaginary parts of type
+`short int'; this is not likely to be useful, but it shows that the set
+of complex types is complete.
+
+ To write a constant with a complex data type, use the suffix `i' or
+`j' (either one; they are equivalent). For example, `2.5fi' has type
+`_Complex float' and `3i' has type `_Complex int'. Such a constant
+always has a pure imaginary value, but you can form any complex value
+you like by adding one to a real constant. This is a GNU extension; if
+you have an ISO C99 conforming C library (such as GNU libc), and want
+to construct complex constants of floating type, you should include
+`<complex.h>' and use the macros `I' or `_Complex_I' instead.
+
+ To extract the real part of a complex-valued expression EXP, write
+`__real__ EXP'. Likewise, use `__imag__' to extract the imaginary
+part. This is a GNU extension; for values of floating type, you should
+use the ISO C99 functions `crealf', `creal', `creall', `cimagf',
+`cimag' and `cimagl', declared in `<complex.h>' and also provided as
+built-in functions by GCC.
+
+ The operator `~' performs complex conjugation when used on a value
+with a complex type. This is a GNU extension; for values of floating
+type, you should use the ISO C99 functions `conjf', `conj' and `conjl',
+declared in `<complex.h>' and also provided as built-in functions by
+GCC.
+
+ GCC can allocate complex automatic variables in a noncontiguous
+fashion; it's even possible for the real part to be in a register while
+the imaginary part is on the stack (or vice-versa). None of the
+supported debugging info formats has a way to represent noncontiguous
+allocation like this, so GCC describes a noncontiguous complex variable
+as if it were two separate variables of noncomplex type. If the
+variable's actual name is `foo', the two fictitious variables are named
+`foo$real' and `foo$imag'. You can examine and set these two
+fictitious variables with your debugger.
+
+ A future version of GDB will know how to recognize such pairs and
+treat them as a single variable with a complex type.
+
+\1f
+File: gcc.info, Node: Hex Floats, Next: Zero Length, Prev: Complex, Up: C Extensions
+
+5.11 Hex Floats
+===============
+
+ISO C99 supports floating-point numbers written not only in the usual
+decimal notation, such as `1.55e1', but also numbers such as `0x1.fp3'
+written in hexadecimal format. As a GNU extension, GCC supports this
+in C89 mode (except in some cases when strictly conforming) and in C++.
+In that format the `0x' hex introducer and the `p' or `P' exponent
+field are mandatory. The exponent is a decimal number that indicates
+the power of 2 by which the significant part will be multiplied. Thus
+`0x1.f' is 1 15/16, `p3' multiplies it by 8, and the value of `0x1.fp3'
+is the same as `1.55e1'.
+
+ Unlike for floating-point numbers in the decimal notation the
+exponent is always required in the hexadecimal notation. Otherwise the
+compiler would not be able to resolve the ambiguity of, e.g., `0x1.f'.
+This could mean `1.0f' or `1.9375' since `f' is also the extension for
+floating-point constants of type `float'.
+
+\1f
+File: gcc.info, Node: Zero Length, Next: Variable Length, Prev: Hex Floats, Up: C Extensions
+
+5.12 Arrays of Length Zero
+==========================
+
+Zero-length arrays are allowed in GNU C. They are very useful as the
+last element of a structure which is really a header for a
+variable-length object:
+
+ struct line {
+ int length;
+ char contents[0];
+ };
+
+ struct line *thisline = (struct line *)
+ malloc (sizeof (struct line) + this_length);
+ thisline->length = this_length;
+
+ In ISO C89, you would have to give `contents' a length of 1, which
+means either you waste space or complicate the argument to `malloc'.
+
+ In ISO C99, you would use a "flexible array member", which is
+slightly different in syntax and semantics:
+
+ * Flexible array members are written as `contents[]' without the `0'.
+
+ * Flexible array members have incomplete type, and so the `sizeof'
+ operator may not be applied. As a quirk of the original
+ implementation of zero-length arrays, `sizeof' evaluates to zero.
+
+ * Flexible array members may only appear as the last member of a
+ `struct' that is otherwise non-empty.
+
+ GCC versions before 3.0 allowed zero-length arrays to be statically
+initialized, as if they were flexible arrays. In addition to those
+cases that were useful, it also allowed initializations in situations
+that would corrupt later data. Non-empty initialization of zero-length
+arrays is now treated like any case where there are more initializer
+elements than the array holds, in that a suitable warning about "excess
+elements in array" is given, and the excess elements (all of them, in
+this case) are ignored.
+
+ Instead GCC allows static initialization of flexible array members.
+This is equivalent to defining a new structure containing the original
+structure followed by an array of sufficient size to contain the data.
+I.e. in the following, `f1' is constructed as if it were declared like
+`f2'.
+
+ struct f1 {
+ int x; int y[];
+ } f1 = { 1, { 2, 3, 4 } };
+
+ struct f2 {
+ struct f1 f1; int data[3];
+ } f2 = { { 1 }, { 2, 3, 4 } };
+
+The convenience of this extension is that `f1' has the desired type,
+eliminating the need to consistently refer to `f2.f1'.
+
+ This has symmetry with normal static arrays, in that an array of
+unknown size is also written with `[]'.
+
+ Of course, this extension only makes sense if the extra data comes at
+the end of a top-level object, as otherwise we would be overwriting
+data at subsequent offsets. To avoid undue complication and confusion
+with initialization of deeply nested arrays, we simply disallow any
+non-empty initialization except when the structure is the top-level
+object. For example:
+
+ struct foo { int x; int y[]; };
+ struct bar { struct foo z; };
+
+ struct foo a = { 1, { 2, 3, 4 } }; // Valid.
+ struct bar b = { { 1, { 2, 3, 4 } } }; // Invalid.
+ struct bar c = { { 1, { } } }; // Valid.
+ struct foo d[1] = { { 1 { 2, 3, 4 } } }; // Invalid.
+
+\1f
+File: gcc.info, Node: Variable Length, Next: Variadic Macros, Prev: Zero Length, Up: C Extensions
+
+5.13 Arrays of Variable Length
+==============================
+
+Variable-length automatic arrays are allowed in ISO C99, and as an
+extension GCC accepts them in C89 mode and in C++. (However, GCC's
+implementation of variable-length arrays does not yet conform in detail
+to the ISO C99 standard.) These arrays are declared like any other
+automatic arrays, but with a length that is not a constant expression.
+The storage is allocated at the point of declaration and deallocated
+when the brace-level is exited. For example:
+
+ FILE *
+ concat_fopen (char *s1, char *s2, char *mode)
+ {
+ char str[strlen (s1) + strlen (s2) + 1];
+ strcpy (str, s1);
+ strcat (str, s2);
+ return fopen (str, mode);
+ }
+
+ Jumping or breaking out of the scope of the array name deallocates
+the storage. Jumping into the scope is not allowed; you get an error
+message for it.
+
+ You can use the function `alloca' to get an effect much like
+variable-length arrays. The function `alloca' is available in many
+other C implementations (but not in all). On the other hand,
+variable-length arrays are more elegant.
+
+ There are other differences between these two methods. Space
+allocated with `alloca' exists until the containing _function_ returns.
+The space for a variable-length array is deallocated as soon as the
+array name's scope ends. (If you use both variable-length arrays and
+`alloca' in the same function, deallocation of a variable-length array
+will also deallocate anything more recently allocated with `alloca'.)
+
+ You can also use variable-length arrays as arguments to functions:
+
+ struct entry
+ tester (int len, char data[len][len])
+ {
+ ...
+ }
+
+ The length of an array is computed once when the storage is allocated
+and is remembered for the scope of the array in case you access it with
+`sizeof'.
+
+ If you want to pass the array first and the length afterward, you can
+use a forward declaration in the parameter list--another GNU extension.
+
+ struct entry
+ tester (int len; char data[len][len], int len)
+ {
+ ...
+ }
+
+ The `int len' before the semicolon is a "parameter forward
+declaration", and it serves the purpose of making the name `len' known
+when the declaration of `data' is parsed.
+
+ You can write any number of such parameter forward declarations in
+the parameter list. They can be separated by commas or semicolons, but
+the last one must end with a semicolon, which is followed by the "real"
+parameter declarations. Each forward declaration must match a "real"
+declaration in parameter name and data type. ISO C99 does not support
+parameter forward declarations.
+
+\1f
+File: gcc.info, Node: Variadic Macros, Next: Escaped Newlines, Prev: Variable Length, Up: C Extensions
+
+5.14 Macros with a Variable Number of Arguments.
+================================================
+
+In the ISO C standard of 1999, a macro can be declared to accept a
+variable number of arguments much as a function can. The syntax for
+defining the macro is similar to that of a function. Here is an
+example:
+
+ #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
+
+ Here `...' is a "variable argument". In the invocation of such a
+macro, it represents the zero or more tokens until the closing
+parenthesis that ends the invocation, including any commas. This set of
+tokens replaces the identifier `__VA_ARGS__' in the macro body wherever
+it appears. See the CPP manual for more information.
+
+ GCC has long supported variadic macros, and used a different syntax
+that allowed you to give a name to the variable arguments just like any
+other argument. Here is an example:
+
+ #define debug(format, args...) fprintf (stderr, format, args)
+
+ This is in all ways equivalent to the ISO C example above, but
+arguably more readable and descriptive.
+
+ GNU CPP has two further variadic macro extensions, and permits them
+to be used with either of the above forms of macro definition.
+
+ In standard C, you are not allowed to leave the variable argument out
+entirely; but you are allowed to pass an empty argument. For example,
+this invocation is invalid in ISO C, because there is no comma after
+the string:
+
+ debug ("A message")
+
+ GNU CPP permits you to completely omit the variable arguments in this
+way. In the above examples, the compiler would complain, though since
+the expansion of the macro still has the extra comma after the format
+string.
+
+ To help solve this problem, CPP behaves specially for variable
+arguments used with the token paste operator, `##'. If instead you
+write
+
+ #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
+
+ and if the variable arguments are omitted or empty, the `##'
+operator causes the preprocessor to remove the comma before it. If you
+do provide some variable arguments in your macro invocation, GNU CPP
+does not complain about the paste operation and instead places the
+variable arguments after the comma. Just like any other pasted macro
+argument, these arguments are not macro expanded.
+
+\1f
+File: gcc.info, Node: Escaped Newlines, Next: Multi-line Strings, Prev: Variadic Macros, Up: C Extensions
+
+5.15 Slightly Looser Rules for Escaped Newlines
+===============================================
+
+Recently, the non-traditional preprocessor has relaxed its treatment of
+escaped newlines. Previously, the newline had to immediately follow a
+backslash. The current implementation allows whitespace in the form of
+spaces, horizontal and vertical tabs, and form feeds between the
+backslash and the subsequent newline. The preprocessor issues a
+warning, but treats it as a valid escaped newline and combines the two
+lines to form a single logical line. This works within comments and
+tokens, including multi-line strings, as well as between tokens.
+Comments are _not_ treated as whitespace for the purposes of this
+relaxation, since they have not yet been replaced with spaces.
+
+\1f
+File: gcc.info, Node: Multi-line Strings, Next: Subscripting, Prev: Escaped Newlines, Up: C Extensions
+
+5.16 String Literals with Embedded Newlines
+===========================================
+
+As an extension, GNU CPP permits string literals to cross multiple lines
+without escaping the embedded newlines. Each embedded newline is
+replaced with a single `\n' character in the resulting string literal,
+regardless of what form the newline took originally.
+
+ CPP currently allows such strings in directives as well (other than
+the `#include' family). This is deprecated and will eventually be
+removed.
+
+\1f
+File: gcc.info, Node: Subscripting, Next: Pointer Arith, Prev: Multi-line Strings, Up: C Extensions
+
+5.17 Non-Lvalue Arrays May Have Subscripts
+==========================================
+
+In ISO C99, arrays that are not lvalues still decay to pointers, and
+may be subscripted, although they may not be modified or used after the
+next sequence point and the unary `&' operator may not be applied to
+them. As an extension, GCC allows such arrays to be subscripted in C89
+mode, though otherwise they do not decay to pointers outside C99 mode.
+For example, this is valid in GNU C though not valid in C89:
+
+ struct foo {int a[4];};
+
+ struct foo f();
+
+ bar (int index)
+ {
+ return f().a[index];
+ }
+
+\1f
+File: gcc.info, Node: Pointer Arith, Next: Initializers, Prev: Subscripting, Up: C Extensions
+
+5.18 Arithmetic on `void'- and Function-Pointers
+================================================
+
+In GNU C, addition and subtraction operations are supported on pointers
+to `void' and on pointers to functions. This is done by treating the
+size of a `void' or of a function as 1.
+
+ A consequence of this is that `sizeof' is also allowed on `void' and
+on function types, and returns 1.
+
+ The option `-Wpointer-arith' requests a warning if these extensions
+are used.
+
+\1f
+File: gcc.info, Node: Initializers, Next: Compound Literals, Prev: Pointer Arith, Up: C Extensions
+
+5.19 Non-Constant Initializers
+==============================
+
+As in standard C++ and ISO C99, the elements of an aggregate
+initializer for an automatic variable are not required to be constant
+expressions in GNU C. Here is an example of an initializer with
+run-time varying elements:
+
+ foo (float f, float g)
+ {
+ float beat_freqs[2] = { f-g, f+g };
+ ...
+ }
+
+\1f
+File: gcc.info, Node: Compound Literals, Next: Designated Inits, Prev: Initializers, Up: C Extensions
+
+5.20 Compound Literals
+======================
+
+ISO C99 supports compound literals. A compound literal looks like a
+cast containing an initializer. Its value is an object of the type
+specified in the cast, containing the elements specified in the
+initializer; it is an lvalue. As an extension, GCC supports compound
+literals in C89 mode and in C++.
+
+ Usually, the specified type is a structure. Assume that `struct
+foo' and `structure' are declared as shown:
+
+ struct foo {int a; char b[2];} structure;
+
+Here is an example of constructing a `struct foo' with a compound
+literal:
+
+ structure = ((struct foo) {x + y, 'a', 0});
+
+This is equivalent to writing the following:
+
+ {
+ struct foo temp = {x + y, 'a', 0};
+ structure = temp;
+ }
+
+ You can also construct an array. If all the elements of the
+compound literal are (made up of) simple constant expressions, suitable
+for use in initializers of objects of static storage duration, then the
+compound literal can be coerced to a pointer to its first element and
+used in such an initializer, as shown here:
+
+ char **foo = (char *[]) { "x", "y", "z" };
+
+ Compound literals for scalar types and union types are is also
+allowed, but then the compound literal is equivalent to a cast.
+
+ As a GNU extension, GCC allows initialization of objects with static
+storage duration by compound literals (which is not possible in ISO
+C99, because the initializer is not a constant). It is handled as if
+the object was initialized only with the bracket enclosed list if
+compound literal's and object types match. The initializer list of the
+compound literal must be constant. If the object being initialized has
+array type of unknown size, the size is determined by compound literal
+size.
+
+ static struct foo x = (struct foo) {1, 'a', 'b'};
+ static int y[] = (int []) {1, 2, 3};
+ static int z[] = (int [3]) {1};
+
+The above lines are equivalent to the following:
+ static struct foo x = {1, 'a', 'b'};
+ static int y[] = {1, 2, 3};
+ static int z[] = {1, 0, 0};
+
+\1f
+File: gcc.info, Node: Designated Inits, Next: Cast to Union, Prev: Compound Literals, Up: C Extensions
+
+5.21 Designated Initializers
+============================
+
+Standard C89 requires the elements of an initializer to appear in a
+fixed order, the same as the order of the elements in the array or
+structure being initialized.
+
+ In ISO C99 you can give the elements in any order, specifying the
+array indices or structure field names they apply to, and GNU C allows
+this as an extension in C89 mode as well. This extension is not
+implemented in GNU C++.
+
+ To specify an array index, write `[INDEX] =' before the element
+value. For example,
+
+ int a[6] = { [4] = 29, [2] = 15 };
+
+is equivalent to
+
+ int a[6] = { 0, 0, 15, 0, 29, 0 };
+
+The index values must be constant expressions, even if the array being
+initialized is automatic.
+
+ An alternative syntax for this which has been obsolete since GCC 2.5
+but GCC still accepts is to write `[INDEX]' before the element value,
+with no `='.
+
+ To initialize a range of elements to the same value, write `[FIRST
+... LAST] = VALUE'. This is a GNU extension. For example,
+
+ int widths[] = { [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 };
+
+If the value in it has side-effects, the side-effects will happen only
+once, not for each initialized field by the range initializer.
+
+Note that the length of the array is the highest value specified plus
+one.
+
+ In a structure initializer, specify the name of a field to initialize
+with `.FIELDNAME =' before the element value. For example, given the
+following structure,
+
+ struct point { int x, y; };
+
+the following initialization
+
+ struct point p = { .y = yvalue, .x = xvalue };
+
+is equivalent to
+
+ struct point p = { xvalue, yvalue };
+
+ Another syntax which has the same meaning, obsolete since GCC 2.5, is
+`FIELDNAME:', as shown here:
+
+ struct point p = { y: yvalue, x: xvalue };
+
+ The `[INDEX]' or `.FIELDNAME' is known as a "designator". You can
+also use a designator (or the obsolete colon syntax) when initializing
+a union, to specify which element of the union should be used. For
+example,
+
+ union foo { int i; double d; };
+
+ union foo f = { .d = 4 };
+
+will convert 4 to a `double' to store it in the union using the second
+element. By contrast, casting 4 to type `union foo' would store it
+into the union as the integer `i', since it is an integer. (*Note Cast
+to Union::.)
+
+ You can combine this technique of naming elements with ordinary C
+initialization of successive elements. Each initializer element that
+does not have a designator applies to the next consecutive element of
+the array or structure. For example,
+
+ int a[6] = { [1] = v1, v2, [4] = v4 };
+
+is equivalent to
+
+ int a[6] = { 0, v1, v2, 0, v4, 0 };
+
+ Labeling the elements of an array initializer is especially useful
+when the indices are characters or belong to an `enum' type. For
+example:
+
+ int whitespace[256]
+ = { [' '] = 1, ['\t'] = 1, ['\h'] = 1,
+ ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 };
+
+ You can also write a series of `.FIELDNAME' and `[INDEX]'
+designators before an `=' to specify a nested subobject to initialize;
+the list is taken relative to the subobject corresponding to the
+closest surrounding brace pair. For example, with the `struct point'
+declaration above:
+
+ struct point ptarray[10] = { [2].y = yv2, [2].x = xv2, [0].x = xv0 };
+
+If the same field is initialized multiple times, it will have value from
+the last initialization. If any such overridden initialization has
+side-effect, it is unspecified whether the side-effect happens or not.
+Currently, gcc will discard them and issue a warning.
+
+\1f
+File: gcc.info, Node: Case Ranges, Next: Mixed Declarations, Prev: Cast to Union, Up: C Extensions
+
+5.22 Case Ranges
+================
+
+You can specify a range of consecutive values in a single `case' label,
+like this:
+
+ case LOW ... HIGH:
+
+This has the same effect as the proper number of individual `case'
+labels, one for each integer value from LOW to HIGH, inclusive.
+
+ This feature is especially useful for ranges of ASCII character
+codes:
+
+ case 'A' ... 'Z':
+
+ *Be careful:* Write spaces around the `...', for otherwise it may be
+parsed wrong when you use it with integer values. For example, write
+this:
+
+ case 1 ... 5:
+
+rather than this:
+
+ case 1...5:
+
+\1f
+File: gcc.info, Node: Cast to Union, Next: Case Ranges, Prev: Designated Inits, Up: C Extensions
+
+5.23 Cast to a Union Type
+=========================
+
+A cast to union type is similar to other casts, except that the type
+specified is a union type. You can specify the type either with `union
+TAG' or with a typedef name. A cast to union is actually a constructor
+though, not a cast, and hence does not yield an lvalue like normal
+casts. (*Note Compound Literals::.)
+
+ The types that may be cast to the union type are those of the members
+of the union. Thus, given the following union and variables:
+
+ union foo { int i; double d; };
+ int x;
+ double y;
+
+both `x' and `y' can be cast to type `union foo'.
+
+ Using the cast as the right-hand side of an assignment to a variable
+of union type is equivalent to storing in a member of the union:
+
+ union foo u;
+ ...
+ u = (union foo) x == u.i = x
+ u = (union foo) y == u.d = y
+
+ You can also use the union cast as a function argument:
+
+ void hack (union foo);
+ ...
+ hack ((union foo) x);
+
+\1f
+File: gcc.info, Node: Mixed Declarations, Next: Function Attributes, Prev: Case Ranges, Up: C Extensions
+
+5.24 Mixed Declarations and Code
+================================
+
+ISO C99 and ISO C++ allow declarations and code to be freely mixed
+within compound statements. As an extension, GCC also allows this in
+C89 mode. For example, you could do:
+
+ int i;
+ ...
+ i++;
+ int j = i + 2;
+
+ Each identifier is visible from where it is declared until the end of
+the enclosing block.
+
+\1f
+File: gcc.info, Node: Function Attributes, Next: Attribute Syntax, Prev: Mixed Declarations, Up: C Extensions
+
+5.25 Declaring Attributes of Functions
+======================================
+
+In GNU C, you declare certain things about functions called in your
+program which help the compiler optimize function calls and check your
+code more carefully.
+
+ The keyword `__attribute__' allows you to specify special attributes
+when making a declaration. This keyword is followed by an attribute
+specification inside double parentheses. The following attributes are
+currently defined for functions on all targets: `noreturn', `noinline',
+`always_inline', `pure', `const', `format', `format_arg',
+`no_instrument_function', `section', `constructor', `destructor',
+`used', `unused', `deprecated', `weak', `malloc', and `alias'. Several
+other attributes are defined for functions on particular target
+systems. Other attributes, including `section' are supported for
+variables declarations (*note Variable Attributes::) and for types
+(*note Type Attributes::).
+
+ 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 `__noreturn__' instead of `noreturn'.
+
+ *Note Attribute Syntax::, for details of the exact syntax for using
+attributes.
+
+`noreturn'
+ A few standard library functions, such as `abort' and `exit',
+ cannot return. GCC knows this automatically. Some programs define
+ their own functions that never return. You can declare them
+ `noreturn' to tell the compiler this fact. For example,
+
+ void fatal () __attribute__ ((noreturn));
+
+ void
+ fatal (...)
+ {
+ ... /* Print error message. */ ...
+ exit (1);
+ }
+
+ The `noreturn' keyword tells the compiler to assume that `fatal'
+ cannot return. It can then optimize without regard to what would
+ happen if `fatal' ever did return. This makes slightly better
+ code. More importantly, it helps avoid spurious warnings of
+ uninitialized variables.
+
+ Do not assume that registers saved by the calling function are
+ restored before calling the `noreturn' function.
+
+ It does not make sense for a `noreturn' function to have a return
+ type other than `void'.
+
+ The attribute `noreturn' is not implemented in GCC versions
+ earlier than 2.5. An alternative way to declare that a function
+ does not return, which works in the current version and in some
+ older versions, is as follows:
+
+ typedef void voidfn ();
+
+ volatile voidfn fatal;
+
+`noinline'
+ This function attribute prevents a function from being considered
+ for inlining.
+
+`always_inline'
+ Generally, functions are not inlined unless optimization is
+ specified. For functions declared inline, this attribute inlines
+ the function even if no optimization level was specified.
+
+`pure'
+ Many functions have no effects except the return value and their
+ return value depends only on the parameters and/or global
+ variables. Such a function can be subject to common subexpression
+ elimination and loop optimization just as an arithmetic operator
+ would be. These functions should be declared with the attribute
+ `pure'. For example,
+
+ int square (int) __attribute__ ((pure));
+
+ says that the hypothetical function `square' is safe to call fewer
+ times than the program says.
+
+ Some of common examples of pure functions are `strlen' or `memcmp'.
+ Interesting non-pure functions are functions with infinite loops
+ or those depending on volatile memory or other system resource,
+ that may change between two consecutive calls (such as `feof' in a
+ multithreading environment).
+
+ The attribute `pure' is not implemented in GCC versions earlier
+ than 2.96.
+
+`const'
+ Many functions do not examine any values except their arguments,
+ and have no effects except the return value. Basically this is
+ just slightly more strict class than the `pure' attribute above,
+ since function is not allowed to read global memory.
+
+ Note that a function that has pointer arguments and examines the
+ data pointed to must _not_ be declared `const'. Likewise, a
+ function that calls a non-`const' function usually must not be
+ `const'. It does not make sense for a `const' function to return
+ `void'.
+
+ The attribute `const' is not implemented in GCC versions earlier
+ than 2.5. An alternative way to declare that a function has no
+ side effects, which works in the current version and in some older
+ versions, is as follows:
+
+ typedef int intfn ();
+
+ extern const intfn square;
+
+ This approach does not work in GNU C++ from 2.6.0 on, since the
+ language specifies that the `const' must be attached to the return
+ value.
+
+`format (ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)'
+ The `format' attribute specifies that a function takes `printf',
+ `scanf', `strftime' or `strfmon' style arguments which should be
+ type-checked against a format string. For example, the
+ declaration:
+
+ extern int
+ my_printf (void *my_object, const char *my_format, ...)
+ __attribute__ ((format (printf, 2, 3)));
+
+ causes the compiler to check the arguments in calls to `my_printf'
+ for consistency with the `printf' style format string argument
+ `my_format'.
+
+ The parameter ARCHETYPE determines how the format string is
+ interpreted, and should be `printf', `scanf', `strftime' or
+ `strfmon'. (You can also use `__printf__', `__scanf__',
+ `__strftime__' or `__strfmon__'.) The parameter STRING-INDEX
+ specifies which argument is the format string argument (starting
+ from 1), while FIRST-TO-CHECK is the number of the first argument
+ to check against the format string. For functions where the
+ arguments are not available to be checked (such as `vprintf'),
+ specify the third parameter as zero. In this case the compiler
+ only checks the format string for consistency. For `strftime'
+ formats, the third parameter is required to be zero.
+
+ In the example above, the format string (`my_format') is the second
+ argument of the function `my_print', and the arguments to check
+ start with the third argument, so the correct parameters for the
+ format attribute are 2 and 3.
+
+ The `format' attribute allows you to identify your own functions
+ which take format strings as arguments, so that GCC can check the
+ calls to these functions for errors. The compiler always (unless
+ `-ffreestanding' is used) checks formats for the standard library
+ functions `printf', `fprintf', `sprintf', `scanf', `fscanf',
+ `sscanf', `strftime', `vprintf', `vfprintf' and `vsprintf'
+ whenever such warnings are requested (using `-Wformat'), so there
+ is no need to modify the header file `stdio.h'. In C99 mode, the
+ functions `snprintf', `vsnprintf', `vscanf', `vfscanf' and
+ `vsscanf' are also checked. Except in strictly conforming C
+ standard modes, the X/Open function `strfmon' is also checked as
+ are `printf_unlocked' and `fprintf_unlocked'. *Note Options
+ Controlling C Dialect: C Dialect Options.
+
+`format_arg (STRING-INDEX)'
+ The `format_arg' attribute specifies that a function takes a format
+ string for a `printf', `scanf', `strftime' or `strfmon' style
+ function and modifies it (for example, to translate it into
+ another language), so the result can be passed to a `printf',
+ `scanf', `strftime' or `strfmon' style function (with the
+ remaining arguments to the format function the same as they would
+ have been for the unmodified string). For example, the
+ declaration:
+
+ extern char *
+ my_dgettext (char *my_domain, const char *my_format)
+ __attribute__ ((format_arg (2)));
+
+ causes the compiler to check the arguments in calls to a `printf',
+ `scanf', `strftime' or `strfmon' type function, whose format
+ string argument is a call to the `my_dgettext' function, for
+ consistency with the format string argument `my_format'. If the
+ `format_arg' attribute had not been specified, all the compiler
+ could tell in such calls to format functions would be that the
+ format string argument is not constant; this would generate a
+ warning when `-Wformat-nonliteral' is used, but the calls could
+ not be checked without the attribute.
+
+ The parameter STRING-INDEX specifies which argument is the format
+ string argument (starting from 1).
+
+ The `format-arg' attribute allows you to identify your own
+ functions which modify format strings, so that GCC can check the
+ calls to `printf', `scanf', `strftime' or `strfmon' type function
+ whose operands are a call to one of your own function. The
+ compiler always treats `gettext', `dgettext', and `dcgettext' in
+ this manner except when strict ISO C support is requested by
+ `-ansi' or an appropriate `-std' option, or `-ffreestanding' is
+ used. *Note Options Controlling C Dialect: C Dialect Options.
+
+`no_instrument_function'
+ If `-finstrument-functions' is given, profiling function calls will
+ be generated at entry and exit of most user-compiled functions.
+ Functions with this attribute will not be so instrumented.
+
+`section ("SECTION-NAME")'
+ Normally, the compiler places the code it generates in the `text'
+ section. Sometimes, however, you need additional sections, or you
+ need certain particular functions to appear in special sections.
+ The `section' attribute specifies that a function lives in a
+ particular section. For example, the declaration:
+
+ extern void foobar (void) __attribute__ ((section ("bar")));
+
+ puts the function `foobar' in the `bar' section.
+
+ 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.
+
+`constructor'
+`destructor'
+ The `constructor' attribute causes the function to be called
+ automatically before execution enters `main ()'. Similarly, the
+ `destructor' attribute causes the function to be called
+ automatically after `main ()' has completed or `exit ()' has been
+ called. Functions with these attributes are useful for
+ initializing data that will be used implicitly during the
+ execution of the program.
+
+ These attributes are not currently implemented for Objective-C.
+
+`unused'
+ This attribute, attached to a function, means that the function is
+ meant to be possibly unused. GCC will not produce a warning for
+ this function. GNU C++ does not currently support this attribute
+ as definitions without parameters are valid in C++.
+
+`used'
+ This attribute, attached to a function, means that code must be
+ emitted for the function even if it appears that the function is
+ not referenced. This is useful, for example, when the function is
+ referenced only in inline assembly.
+
+`deprecated'
+ The `deprecated' attribute results in a warning if the function is
+ used anywhere in the source file. This is useful when identifying
+ functions 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 function, to enable users to easily find further
+ information about why the function is deprecated, or what they
+ should do instead. Note that the warnings only occurs for uses:
+
+ int old_fn () __attribute__ ((deprecated));
+ int old_fn ();
+ int (*fn_ptr)() = old_fn;
+
+ results in a warning on line 3 but not line 2.
+
+ The `deprecated' attribute can also be used for variables and
+ types (*note Variable Attributes::, *note Type Attributes::.)
+
+`weak'
+ The `weak' attribute causes the declaration to be emitted as a weak
+ symbol rather than a global. This is primarily useful in defining
+ library functions which can be overridden in user code, though it
+ can also be used with non-function declarations. Weak symbols are
+ supported for ELF targets, and also for a.out targets when using
+ the GNU assembler and linker.
+
+`malloc'
+ The `malloc' attribute is used to tell the compiler that a function
+ may be treated as if it were the malloc function. The compiler
+ assumes that calls to malloc result in a pointers that cannot
+ alias anything. This will often improve optimization.
+
+`alias ("TARGET")'
+ The `alias' attribute causes the declaration to be emitted as an
+ alias for another symbol, which must be specified. For instance,
+
+ void __f () { /* do something */; }
+ void f () __attribute__ ((weak, alias ("__f")));
+
+ declares `f' to be a weak alias for `__f'. In C++, the mangled
+ name for the target must be used.
+
+ Not all target machines support this attribute.
+
+`regparm (NUMBER)'
+ On the Intel 386, the `regparm' attribute causes the compiler to
+ pass up to NUMBER integer arguments in registers EAX, EDX, and ECX
+ instead of on the stack. Functions that take a variable number of
+ arguments will continue to be passed all of their arguments on the
+ stack.
+
+`stdcall'
+ On the Intel 386, the `stdcall' attribute causes the compiler to
+ assume that the called function will pop off the stack space used
+ to pass arguments, unless it takes a variable number of arguments.
+
+ The PowerPC compiler for Windows NT currently ignores the `stdcall'
+ attribute.
+
+`cdecl'
+ On the Intel 386, the `cdecl' attribute causes the compiler to
+ assume that the calling function will pop off the stack space used
+ to pass arguments. This is useful to override the effects of the
+ `-mrtd' switch.
+
+ The PowerPC compiler for Windows NT currently ignores the `cdecl'
+ attribute.
+
+`longcall'
+ On the RS/6000 and PowerPC, the `longcall' attribute causes the
+ compiler to always call the function via a pointer, so that
+ functions which reside further than 64 megabytes (67,108,864
+ bytes) from the current location can be called.
+
+`long_call/short_call'
+ This attribute allows to specify how to call a particular function
+ on ARM. Both attributes override the `-mlong-calls' (*note ARM
+ Options::) command line switch and `#pragma long_calls' settings.
+ The `long_call' attribute causes the compiler to always call the
+ function by first loading its address into a register and then
+ using the contents of that register. The `short_call' attribute
+ always places the offset to the function from the call site into
+ the `BL' instruction directly.
+
+`dllimport'
+ On the PowerPC running Windows NT, the `dllimport' attribute causes
+ the compiler to call the function via a global pointer to the
+ function pointer that is set up by the Windows NT dll library.
+ The pointer name is formed by combining `__imp_' and the function
+ name.
+
+`dllexport'
+ On the PowerPC running Windows NT, the `dllexport' attribute causes
+ the compiler to provide a global pointer to the function pointer,
+ so that it can be called with the `dllimport' attribute. The
+ pointer name is formed by combining `__imp_' and the function name.
+
+`exception (EXCEPT-FUNC [, EXCEPT-ARG])'
+ On the PowerPC running Windows NT, the `exception' attribute causes
+ the compiler to modify the structured exception table entry it
+ emits for the declared function. The string or identifier
+ EXCEPT-FUNC is placed in the third entry of the structured
+ exception table. It represents a function, which is called by the
+ exception handling mechanism if an exception occurs. If it was
+ specified, the string or identifier EXCEPT-ARG is placed in the
+ fourth entry of the structured exception table.
+
+`function_vector'
+ Use this attribute on the H8/300 and H8/300H to indicate that the
+ specified function should be called through the function vector.
+ Calling a function through the function vector will reduce code
+ size, however; the function vector has a limited size (maximum 128
+ entries on the H8/300 and 64 entries on the H8/300H) and shares
+ space with the interrupt vector.
+
+ You must use GAS and GLD from GNU binutils version 2.7 or later for
+ this attribute to work correctly.
+
+`interrupt'
+ Use this attribute on the ARM, AVR, M32R/D and Xstormy16 ports to
+ indicate that the specified function is an interrupt handler. The
+ compiler will generate function entry and exit sequences suitable
+ for use in an interrupt handler when this attribute is present.
+
+ Note, interrupt handlers for the H8/300, H8/300H and SH processors
+ can be specified via the `interrupt_handler' attribute.
+
+ Note, on the AVR interrupts will be enabled inside the function.
+
+ Note, for the ARM you can specify the kind of interrupt to be
+ handled by adding an optional parameter to the interrupt attribute
+ like this:
+
+ void f () __attribute__ ((interrupt ("IRQ")));
+
+ Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT
+ and UNDEF.
+
+`interrupt_handler'
+ Use this attribute on the H8/300, H8/300H and SH to indicate that
+ the specified function is an interrupt handler. The compiler will
+ generate function entry and exit sequences suitable for use in an
+ interrupt handler when this attribute is present.
+
+`sp_switch'
+ Use this attribute on the SH to indicate an `interrupt_handler'
+ function should switch to an alternate stack. It expects a string
+ argument that names a global variable holding the address of the
+ alternate stack.
+
+ void *alt_stack;
+ void f () __attribute__ ((interrupt_handler,
+ sp_switch ("alt_stack")));
+
+`trap_exit'
+ Use this attribute on the SH for an `interrupt_handle' to return
+ using `trapa' instead of `rte'. This attribute expects an integer
+ argument specifying the trap number to be used.
+
+`eightbit_data'
+ Use this attribute on the H8/300 and H8/300H to indicate that the
+ specified variable should be placed into the eight bit data
+ section. The compiler will generate more efficient code for
+ certain operations on data in the eight bit data area. Note the
+ eight bit data area is limited to 256 bytes of data.
+
+ You must use GAS and GLD from GNU binutils version 2.7 or later for
+ this attribute to work correctly.
+
+`tiny_data'
+ Use this attribute on the H8/300H to indicate that the specified
+ variable should be placed into the tiny data section. The
+ compiler will generate more efficient code for loads and stores on
+ data in the tiny data section. Note the tiny data area is limited
+ to slightly under 32kbytes of data.
+
+`signal'
+ Use this attribute on the AVR to indicate that the specified
+ function is an signal handler. The compiler will generate function
+ entry and exit sequences suitable for use in an signal handler
+ when this attribute is present. Interrupts will be disabled
+ inside function.
+
+`naked'
+ Use this attribute on the ARM or AVR ports to indicate that the
+ specified function do not need prologue/epilogue sequences
+ generated by the compiler. It is up to the programmer to provide
+ these sequences.
+
+`model (MODEL-NAME)'
+ Use this attribute on the M32R/D to set the addressability of an
+ object, and the code generated for a function. 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), and are
+ callable with the `bl' instruction.
+
+ Medium model objects may live anywhere in the 32-bit address space
+ (the compiler will generate `seth/add3' instructions to load their
+ addresses), and are callable with the `bl' instruction.
+
+ Large model objects may live anywhere in the 32-bit address space
+ (the compiler will generate `seth/add3' instructions to load their
+ addresses), and may not be reachable with the `bl' instruction
+ (the compiler will generate the much slower `seth/add3/jl'
+ instruction sequence).
+
+
+ You can specify multiple attributes in a declaration by separating
+them by commas within the double parentheses or by immediately
+following an attribute declaration with another attribute declaration.
+
+ Some people object to the `__attribute__' feature, suggesting that
+ISO C's `#pragma' should be used instead. At the time `__attribute__'
+was designed, there were two reasons for not doing this.
+
+ 1. It is impossible to generate `#pragma' commands from a macro.
+
+ 2. There is no telling what the same `#pragma' might mean in another
+ compiler.
+
+ These two reasons applied to almost any application that might have
+been proposed for `#pragma'. It was basically a mistake to use
+`#pragma' for _anything_.
+
+ The ISO C99 standard includes `_Pragma', which now allows pragmas to
+be generated from macros. In addition, a `#pragma GCC' namespace is
+now in use for GCC-specific pragmas. However, it has been found
+convenient to use `__attribute__' to achieve a natural attachment of
+attributes to their corresponding declarations, whereas `#pragma GCC'
+is of use for constructs that do not naturally form part of the
+grammar. *Note Miscellaneous Preprocessing Directives: (cpp)Other
+Directives.
+
+\1f
+File: gcc.info, Node: Attribute Syntax, Next: Function Prototypes, Prev: Function Attributes, Up: C Extensions
+
+5.26 Attribute Syntax
+=====================
+
+This section describes the syntax with which `__attribute__' may be
+used, and the constructs to which attribute specifiers bind, for the C
+language. Some details may vary for C++ and Objective-C. Because of
+infelicities in the grammar for attributes, some forms described here
+may not be successfully parsed in all cases.
+
+ There are some problems with the semantics of attributes in C++. For
+example, there are no manglings for attributes, although they may affect
+code generation, so problems may arise when attributed types are used in
+conjunction with templates or overloading. Similarly, `typeid' does
+not distinguish between types with different attributes. Support for
+attributes in C++ may be restricted in future to attributes on
+declarations only, but not on nested declarators.
+
+ *Note Function Attributes::, for details of the semantics of
+attributes applying to functions. *Note Variable Attributes::, for
+details of the semantics of attributes applying to variables. *Note
+Type Attributes::, for details of the semantics of attributes applying
+to structure, union and enumerated types.
+
+ An "attribute specifier" is of the form `__attribute__
+((ATTRIBUTE-LIST))'. An "attribute list" is a possibly empty
+comma-separated sequence of "attributes", where each attribute is one
+of the following:
+
+ * Empty. Empty attributes are ignored.
+
+ * A word (which may be an identifier such as `unused', or a reserved
+ word such as `const').
+
+ * A word, followed by, in parentheses, parameters for the attribute.
+ These parameters take one of the following forms:
+
+ * An identifier. For example, `mode' attributes use this form.
+
+ * An identifier followed by a comma and a non-empty
+ comma-separated list of expressions. For example, `format'
+ attributes use this form.
+
+ * A possibly empty comma-separated list of expressions. For
+ example, `format_arg' attributes use this form with the list
+ being a single integer constant expression, and `alias'
+ attributes use this form with the list being a single string
+ constant.
+
+ An "attribute specifier list" is a sequence of one or more attribute
+specifiers, not separated by any other tokens.
+
+ An attribute specifier list may appear after the colon following a
+label, other than a `case' or `default' label. The only attribute it
+makes sense to use after a label is `unused'. This feature is intended
+for code generated by programs which contains labels that may be unused
+but which is compiled with `-Wall'. It would not normally be
+appropriate to use in it human-written code, though it could be useful
+in cases where the code that jumps to the label is contained within an
+`#ifdef' conditional.
+
+ An attribute specifier list may appear as part of a `struct',
+`union' or `enum' specifier. It may go either immediately after the
+`struct', `union' or `enum' keyword, or after the closing brace. It is
+ignored if the content of the structure, union or enumerated type is
+not defined in the specifier in which the attribute specifier list is
+used--that is, in usages such as `struct __attribute__((foo)) bar' with
+no following opening brace. Where attribute specifiers follow the
+closing brace, they are considered to relate to the structure, union or
+enumerated type defined, not to any enclosing declaration the type
+specifier appears in, and the type defined is not complete until after
+the attribute specifiers.
+
+ Otherwise, an attribute specifier appears as part of a declaration,
+counting declarations of unnamed parameters and type names, and relates
+to that declaration (which may be nested in another declaration, for
+example in the case of a parameter declaration), or to a particular
+declarator within a declaration. Where an attribute specifier is
+applied to a parameter declared as a function or an array, it should
+apply to the function or array rather than the pointer to which the
+parameter is implicitly converted, but this is not yet correctly
+implemented.
+
+ Any list of specifiers and qualifiers at the start of a declaration
+may contain attribute specifiers, whether or not such a list may in that
+context contain storage class specifiers. (Some attributes, however,
+are essentially in the nature of storage class specifiers, and only make
+sense where storage class specifiers may be used; for example,
+`section'.) There is one necessary limitation to this syntax: the
+first old-style parameter declaration in a function definition cannot
+begin with an attribute specifier, because such an attribute applies to
+the function instead by syntax described below (which, however, is not
+yet implemented in this case). In some other cases, attribute
+specifiers are permitted by this grammar but not yet supported by the
+compiler. All attribute specifiers in this place relate to the
+declaration as a whole. In the obsolescent usage where a type of `int'
+is implied by the absence of type specifiers, such a list of specifiers
+and qualifiers may be an attribute specifier list with no other
+specifiers or qualifiers.
+
+ An attribute specifier list may appear immediately before a
+declarator (other than the first) in a comma-separated list of
+declarators in a declaration of more than one identifier using a single
+list of specifiers and qualifiers. Such attribute specifiers apply
+only to the identifier before whose declarator they appear. For
+example, in
+
+ __attribute__((noreturn)) void d0 (void),
+ __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
+ d2 (void)
+
+the `noreturn' attribute applies to all the functions declared; the
+`format' attribute only applies to `d1'.
+
+ An attribute specifier list may appear immediately before the comma,
+`=' or semicolon terminating the declaration of an identifier other
+than a function definition. At present, such attribute specifiers apply
+to the declared object or function, but in future they may attach to the
+outermost adjacent declarator. In simple cases there is no difference,
+but, for example, in
+
+ void (****f)(void) __attribute__((noreturn));
+
+at present the `noreturn' attribute applies to `f', which causes a
+warning since `f' is not a function, but in future it may apply to the
+function `****f'. The precise semantics of what attributes in such
+cases will apply to are not yet specified. Where an assembler name for
+an object or function is specified (*note Asm Labels::), at present the
+attribute must follow the `asm' specification; in future, attributes
+before the `asm' specification may apply to the adjacent declarator,
+and those after it to the declared object or function.
+
+ An attribute specifier list may, in future, be permitted to appear
+after the declarator in a function definition (before any old-style
+parameter declarations or the function body).
+
+ Attribute specifiers may be mixed with type qualifiers appearing
+inside the `[]' of a parameter array declarator, in the C99 construct by
+which such qualifiers are applied to the pointer to which the array is
+implicitly converted. Such attribute specifiers apply to the pointer,
+not to the array, but at present this is not implemented and they are
+ignored.
+
+ An attribute specifier list may appear at the start of a nested
+declarator. At present, there are some limitations in this usage: the
+attributes correctly apply to the declarator, but for most individual
+attributes the semantics this implies are not implemented. When
+attribute specifiers follow the `*' of a pointer declarator, they may
+be mixed with any type qualifiers present. The following describes the
+formal semantics of this syntax. It will make the most sense if you
+are familiar with the formal specification of declarators in the ISO C
+standard.
+
+ Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration `T
+D1', where `T' contains declaration specifiers that specify a type TYPE
+(such as `int') and `D1' is a declarator that contains an identifier
+IDENT. The type specified for IDENT for derived declarators whose type
+does not include an attribute specifier is as in the ISO C standard.
+
+ If `D1' has the form `( ATTRIBUTE-SPECIFIER-LIST D )', and the
+declaration `T D' specifies the type "DERIVED-DECLARATOR-TYPE-LIST
+TYPE" for IDENT, then `T D1' specifies the type
+"DERIVED-DECLARATOR-TYPE-LIST ATTRIBUTE-SPECIFIER-LIST TYPE" for IDENT.
+
+ If `D1' has the form `* TYPE-QUALIFIER-AND-ATTRIBUTE-SPECIFIER-LIST
+D', and the declaration `T D' specifies the type
+"DERIVED-DECLARATOR-TYPE-LIST TYPE" for IDENT, then `T D1' specifies
+the type "DERIVED-DECLARATOR-TYPE-LIST
+TYPE-QUALIFIER-AND-ATTRIBUTE-SPECIFIER-LIST TYPE" for IDENT.
+
+ For example,
+
+ void (__attribute__((noreturn)) ****f) (void);
+
+specifies the type "pointer to pointer to pointer to pointer to
+non-returning function returning `void'". As another example,
+
+ char *__attribute__((aligned(8))) *f;
+
+specifies the type "pointer to 8-byte-aligned pointer to `char'". Note
+again that this does not work with most attributes; for example, the
+usage of `aligned' and `noreturn' attributes given above is not yet
+supported.
+
+ For compatibility with existing code written for compiler versions
+that did not implement attributes on nested declarators, some laxity is
+allowed in the placing of attributes. If an attribute that only applies
+to types is applied to a declaration, it will be treated as applying to
+the type of that declaration. If an attribute that only applies to
+declarations is applied to the type of a declaration, it will be treated
+as applying to that declaration; and, for compatibility with code
+placing the attributes immediately before the identifier declared, such
+an attribute applied to a function return type will be treated as
+applying to the function type, and such an attribute applied to an array
+element type will be treated as applying to the array type. If an
+attribute that only applies to function types is applied to a
+pointer-to-function type, it will be treated as applying to the pointer
+target type; if such an attribute is applied to a function return type
+that is not a pointer-to-function type, it will be treated as applying
+to the function type.
+
+\1f
+File: gcc.info, Node: Function Prototypes, Next: C++ Comments, Prev: Attribute Syntax, Up: C Extensions
+
+5.27 Prototypes and Old-Style Function Definitions
+==================================================
+
+GNU C extends ISO C to allow a function prototype to override a later
+old-style non-prototype definition. Consider the following example:
+
+ /* Use prototypes unless the compiler is old-fashioned. */
+ #ifdef __STDC__
+ #define P(x) x
+ #else
+ #define P(x) ()
+ #endif
+
+ /* Prototype function declaration. */
+ int isroot P((uid_t));
+
+ /* Old-style function definition. */
+ int
+ isroot (x) /* ??? lossage here ??? */
+ uid_t x;
+ {
+ return x == 0;
+ }
+
+ Suppose the type `uid_t' happens to be `short'. ISO C does not
+allow this example, because subword arguments in old-style
+non-prototype definitions are promoted. Therefore in this example the
+function definition's argument is really an `int', which does not match
+the prototype argument type of `short'.
+
+ This restriction of ISO C makes it hard to write code that is
+portable to traditional C compilers, because the programmer does not
+know whether the `uid_t' type is `short', `int', or `long'. Therefore,
+in cases like these GNU C allows a prototype to override a later
+old-style definition. More precisely, in GNU C, a function prototype
+argument type overrides the argument type specified by a later
+old-style definition if the former type is the same as the latter type
+before promotion. Thus in GNU C the above example is equivalent to the
+following:
+
+ int isroot (uid_t);
+
+ int
+ isroot (uid_t x)
+ {
+ return x == 0;
+ }
+
+GNU C++ does not support old-style function definitions, so this
+extension is irrelevant.
+
+\1f
+File: gcc.info, Node: C++ Comments, Next: Dollar Signs, Prev: Function Prototypes, Up: C Extensions
+
+5.28 C++ Style Comments
+=======================
+
+In GNU C, you may use C++ style comments, which start with `//' and
+continue until the end of the line. Many other C implementations allow
+such comments, and they are likely to be in a future C standard.
+However, C++ style comments are not recognized if you specify `-ansi',
+a `-std' option specifying a version of ISO C before C99, or
+`-traditional', since they are incompatible with traditional constructs
+like `dividend//*comment*/divisor'.
+
+\1f
+File: gcc.info, Node: Dollar Signs, Next: Character Escapes, Prev: C++ Comments, Up: C Extensions
+
+5.29 Dollar Signs in Identifier Names
+=====================================
+
+In GNU C, you may normally use dollar signs in identifier names. This
+is because many traditional C implementations allow such identifiers.
+However, dollar signs in identifiers are not supported on a few target
+machines, typically because the target assembler does not allow them.
+
+\1f
+File: gcc.info, Node: Character Escapes, Next: Variable Attributes, Prev: Dollar Signs, Up: C Extensions
+
+5.30 The Character <ESC> in Constants
+=====================================
+
+You can use the sequence `\e' in a string or character constant to
+stand for the ASCII character <ESC>.
+
+\1f
+File: gcc.info, Node: Alignment, Next: Inline, Prev: Type Attributes, Up: C Extensions
+
+5.31 Inquiring on Alignment of Types or Variables
+=================================================
+
+The keyword `__alignof__' allows you to inquire about how an object is
+aligned, or the minimum alignment usually required by a type. Its
+syntax is just like `sizeof'.
+
+ For example, if the target machine requires a `double' value to be
+aligned on an 8-byte boundary, then `__alignof__ (double)' is 8. This
+is true on many RISC machines. On more traditional machine designs,
+`__alignof__ (double)' is 4 or even 2.
+
+ Some machines never actually require alignment; they allow reference
+to any data type even at an odd addresses. For these machines,
+`__alignof__' reports the _recommended_ alignment of a type.
+
+ If the operand of `__alignof__' is an lvalue rather than a type, its
+value is the required alignment for its type, taking into account any
+minimum alignment specified with GCC's `__attribute__' extension (*note
+Variable Attributes::). For example, after this declaration:
+
+ struct foo { int x; char y; } foo1;
+
+the value of `__alignof__ (foo1.y)' is 1, even though its actual
+alignment is probably 2 or 4, the same as `__alignof__ (int)'.
+
+ It is an error to ask for the alignment of an incomplete type.
+
+\1f
+File: gcc.info, Node: Variable Attributes, Next: Type Attributes, Prev: Character Escapes, Up: C Extensions
+
+5.32 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. Ten attributes are
+currently defined for variables: `aligned', `mode', `nocommon',
+`packed', `section', `transparent_union', `unused', `deprecated',
+`vector_size', and `weak'. Some 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.
+
+`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.
+
+`nocommon'
+ This attribute specifies requests GCC not to place a variable
+ "common" but instead to allocate space for it directly. If you
+ specify the `-fno-common' flag, GCC will do this for all variables.
+
+ Specifying the `nocommon' attribute for a variable provides an
+ initialization of zeros. A variable may only be initialized in one
+ source file.
+
+`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 NT, 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 NT.
+
+`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.
+
+`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 warnings 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::.)
+
+`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).
+
+
+ To specify multiple attributes, separate them by commas within the
+double parentheses: for example, `__attribute__ ((aligned (16),
+packed))'.
+
+\1f
+File: gcc.info, Node: Type Attributes, Next: Alignment, Prev: Variable Attributes, Up: C Extensions
+
+5.33 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. Five
+attributes are currently defined for types: `aligned', `packed',
+`transparent_union', `unused', and `deprecated'. 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, specified 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 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::.)
+
+
+ To specify multiple attributes, separate them by commas within the
+double parentheses: for example, `__attribute__ ((aligned (16),
+packed))'.
+
+\1f
+File: gcc.info, Node: Inline, Next: Extended Asm, Prev: Alignment, Up: C Extensions
+
+5.34 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.
+
+ For future compatibility with when GCC implements ISO C99 semantics
+for inline functions, it is best to use `static inline' only. (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));
+
+\1f
+File: gcc.info, Node: Extended Asm, Next: Constraints, Prev: Inline, Up: C Extensions
+
+5.35 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::.
+
+5.35.1 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)");
+
+\1f
+File: gcc.info, Node: Constraints, Next: Asm Labels, Prev: Extended Asm, Up: C Extensions
+
+5.36 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.
+
+\1f
+File: gcc.info, Node: Simple Constraints, Next: Multi-Alternative, Up: Constraints
+
+5.36.1 Simple Constraints
+-------------------------
+
+The simplest kind of constraint is a string full of letters, each of
+which describes one kind of operand that is permitted. Here are the
+letters that are allowed:
+
+whitespace
+ Whitespace characters are ignored and can be inserted at any
+ position except the first. This enables each alternative for
+ different operands to be visually aligned in the machine
+ description even if they have different number of constraints and
+ modifiers.
+
+`m'
+ A memory operand is allowed, with any kind of address that the
+ machine supports in general.
+
+`o'
+ A memory operand is allowed, but only if the address is
+ "offsettable". This means that adding a small integer (actually,
+ the width in bytes of the operand, as determined by its machine
+ mode) may be added to the address and the result is also a valid
+ memory address.
+
+ For example, an address which is constant is offsettable; so is an
+ address that is the sum of a register and a constant (as long as a
+ slightly larger constant is also within the range of
+ address-offsets supported by the machine); but an autoincrement or
+ autodecrement address is not offsettable. More complicated
+ indirect/indexed addresses may or may not be offsettable depending
+ on the other addressing modes that the machine supports.
+
+ Note that in an output operand which can be matched by another
+ operand, the constraint letter `o' is valid only when accompanied
+ by both `<' (if the target machine has predecrement addressing)
+ and `>' (if the target machine has preincrement addressing).
+
+`V'
+ A memory operand that is not offsettable. In other words,
+ anything that would fit the `m' constraint but not the `o'
+ constraint.
+
+`<'
+ A memory operand with autodecrement addressing (either
+ predecrement or postdecrement) is allowed.
+
+`>'
+ A memory operand with autoincrement addressing (either
+ preincrement or postincrement) is allowed.
+
+`r'
+ A register operand is allowed provided that it is in a general
+ register.
+
+`i'
+ An immediate integer operand (one with constant value) is allowed.
+ This includes symbolic constants whose values will be known only at
+ assembly time.
+
+`n'
+ An immediate integer operand with a known numeric value is allowed.
+ Many systems cannot support assembly-time constants for operands
+ less than a word wide. Constraints for these operands should use
+ `n' rather than `i'.
+
+`I', `J', `K', ... `P'
+ Other letters in the range `I' through `P' may be defined in a
+ machine-dependent fashion to permit immediate integer operands with
+ explicit integer values in specified ranges. For example, on the
+ 68000, `I' is defined to stand for the range of values 1 to 8.
+ This is the range permitted as a shift count in the shift
+ instructions.
+
+`E'
+ An immediate floating operand (expression code `const_double') is
+ allowed, but only if the target floating point format is the same
+ as that of the host machine (on which the compiler is running).
+
+`F'
+ An immediate floating operand (expression code `const_double') is
+ allowed.
+
+`G', `H'
+ `G' and `H' may be defined in a machine-dependent fashion to
+ permit immediate floating operands in particular ranges of values.
+
+`s'
+ An immediate integer operand whose value is not an explicit
+ integer is allowed.
+
+ This might appear strange; if an insn allows a constant operand
+ with a value not known at compile time, it certainly must allow
+ any known value. So why use `s' instead of `i'? Sometimes it
+ allows better code to be generated.
+
+ For example, on the 68000 in a fullword instruction it is possible
+ to use an immediate operand; but if the immediate value is between
+ -128 and 127, better code results from loading the value into a
+ register and using the register. This is because the load into
+ the register can be done with a `moveq' instruction. We arrange
+ for this to happen by defining the letter `K' to mean "any integer
+ outside the range -128 to 127", and then specifying `Ks' in the
+ operand constraints.
+
+`g'
+ Any register, memory or immediate integer operand is allowed,
+ except for registers that are not general registers.
+
+`X'
+ Any operand whatsoever is allowed.
+
+`0', `1', `2', ... `9'
+ An operand that matches the specified operand number is allowed.
+ If a digit is used together with letters within the same
+ alternative, the digit should come last.
+
+ This number is allowed to be more than a single digit. If multiple
+ digits are encountered consecutavely, they are interpreted as a
+ single decimal integer. There is scant chance for ambiguity,
+ since to-date it has never been desirable that `10' be interpreted
+ as matching either operand 1 _or_ operand 0. Should this be
+ desired, one can use multiple alternatives instead.
+
+ This is called a "matching constraint" and what it really means is
+ that the assembler has only a single operand that fills two roles
+ which `asm' distinguishes. For example, an add instruction uses
+ two input operands and an output operand, but on most CISC
+ machines an add instruction really has only two operands, one of
+ them an input-output operand:
+
+ addl #35,r12
+
+ Matching constraints are used in these circumstances. More
+ precisely, the two operands that match must include one input-only
+ operand and one output-only operand. Moreover, the digit must be a
+ smaller number than the number of the operand that uses it in the
+ constraint.
+
+`p'
+ An operand that is a valid memory address is allowed. This is for
+ "load address" and "push address" instructions.
+
+ `p' in the constraint must be accompanied by `address_operand' as
+ the predicate in the `match_operand'. This predicate interprets
+ the mode specified in the `match_operand' as the mode of the memory
+ reference for which the address would be valid.
+
+OTHER-LETTERS
+ Other letters can be defined in machine-dependent fashion to stand
+ for particular classes of registers or other arbitrary operand
+ types. `d', `a' and `f' are defined on the 68000/68020 to stand
+ for data, address and floating point registers.
+
+
+\1f
+File: gcc.info, Node: Multi-Alternative, Next: Modifiers, Prev: Simple Constraints, Up: Constraints
+
+5.36.2 Multiple Alternative Constraints
+---------------------------------------
+
+Sometimes a single instruction has multiple alternative sets of possible
+operands. For example, on the 68000, a logical-or instruction can
+combine register or an immediate value into memory, or it can combine
+any kind of operand into a register; but it cannot combine one memory
+location into another.
+
+ These constraints are represented as multiple alternatives. An
+alternative can be described by a series of letters for each operand.
+The overall constraint for an operand is made from the letters for this
+operand from the first alternative, a comma, the letters for this
+operand from the second alternative, a comma, and so on until the last
+alternative.
+
+ If all the operands fit any one alternative, the instruction is
+valid. Otherwise, for each alternative, the compiler counts how many
+instructions must be added to copy the operands so that that
+alternative applies. The alternative requiring the least copying is
+chosen. If two alternatives need the same amount of copying, the one
+that comes first is chosen. These choices can be altered with the `?'
+and `!' characters:
+
+`?'
+ Disparage slightly the alternative that the `?' appears in, as a
+ choice when no alternative applies exactly. The compiler regards
+ this alternative as one unit more costly for each `?' that appears
+ in it.
+
+`!'
+ Disparage severely the alternative that the `!' appears in. This
+ alternative can still be used if it fits without reloading, but if
+ reloading is needed, some other alternative will be used.
+
+\1f
+File: gcc.info, Node: Modifiers, Next: Machine Constraints, Prev: Multi-Alternative, Up: Constraints
+
+5.36.3 Constraint Modifier Characters
+-------------------------------------
+
+Here are constraint modifier characters.
+
+`='
+ Means that this operand is write-only for this instruction: the
+ previous value is discarded and replaced by output data.
+
+`+'
+ Means that this operand is both read and written by the
+ instruction.
+
+ When the compiler fixes up the operands to satisfy the constraints,
+ it needs to know which operands are inputs to the instruction and
+ which are outputs from it. `=' identifies an output; `+'
+ identifies an operand that is both input and output; all other
+ operands are assumed to be input only.
+
+ If you specify `=' or `+' in a constraint, you put it in the first
+ character of the constraint string.
+
+`&'
+ Means (in a particular alternative) that this operand is an
+ "earlyclobber" operand, which is modified before the instruction is
+ finished using the input operands. Therefore, this operand may
+ not lie in a register that is used as an input operand or as part
+ of any memory address.
+
+ `&' applies only to the alternative in which it is written. In
+ constraints with multiple alternatives, sometimes one alternative
+ requires `&' while others do not. See, for example, the `movdf'
+ insn of the 68000.
+
+ An input operand can be tied to an earlyclobber operand if its only
+ use as an input occurs before the early result is written. Adding
+ alternatives of this form often allows GCC to produce better code
+ when only some of the inputs can be affected by the earlyclobber.
+ See, for example, the `mulsi3' insn of the ARM.
+
+ `&' does not obviate the need to write `='.
+
+`%'
+ Declares the instruction to be commutative for this operand and the
+ following operand. This means that the compiler may interchange
+ the two operands if that is the cheapest way to make all operands
+ fit the constraints.
+
+`#'
+ Says that all following characters, up to the next comma, are to be
+ ignored as a constraint. They are significant only for choosing
+ register preferences.
+
+`*'
+ Says that the following character should be ignored when choosing
+ register preferences. `*' has no effect on the meaning of the
+ constraint as a constraint, and no effect on reloading.
+
+
+\1f
+File: gcc.info, Node: Machine Constraints, Prev: Modifiers, Up: Constraints
+
+5.36.4 Constraints for Particular Machines
+------------------------------------------
+
+Whenever possible, you should use the general-purpose constraint letters
+in `asm' arguments, since they will convey meaning more readily to
+people reading your code. Failing that, use the constraint letters
+that usually have very similar meanings across architectures. The most
+commonly used constraints are `m' and `r' (for memory and
+general-purpose registers respectively; *note Simple Constraints::), and
+`I', usually the letter indicating the most common immediate-constant
+format.
+
+ For each machine architecture, the `config/MACHINE/MACHINE.h' file
+defines additional constraints. These constraints are used by the
+compiler itself for instruction generation, as well as for `asm'
+statements; therefore, some of the constraints are not particularly
+interesting for `asm'. The constraints are defined through these
+macros:
+
+`REG_CLASS_FROM_LETTER'
+ Register class constraints (usually lower case).
+
+`CONST_OK_FOR_LETTER_P'
+ Immediate constant constraints, for non-floating point constants of
+ word size or smaller precision (usually upper case).
+
+`CONST_DOUBLE_OK_FOR_LETTER_P'
+ Immediate constant constraints, for all floating point constants
+ and for constants of greater than word size precision (usually
+ upper case).
+
+`EXTRA_CONSTRAINT'
+ Special cases of registers or memory. This macro is not required,
+ and is only defined for some machines.
+
+ Inspecting these macro definitions in the compiler source for your
+machine is the best way to be certain you have the right constraints.
+However, here is a summary of the machine-dependent constraints
+available on some particular machines.
+
+_ARM family--`arm.h'_
+
+ `f'
+ Floating-point register
+
+ `F'
+ One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0,
+ 4.0, 5.0 or 10.0
+
+ `G'
+ Floating-point constant that would satisfy the constraint `F'
+ if it were negated
+
+ `I'
+ Integer that is valid as an immediate operand in a data
+ processing instruction. That is, an integer in the range 0
+ to 255 rotated by a multiple of 2
+
+ `J'
+ Integer in the range -4095 to 4095
+
+ `K'
+ Integer that satisfies constraint `I' when inverted (ones
+ complement)
+
+ `L'
+ Integer that satisfies constraint `I' when negated (twos
+ complement)
+
+ `M'
+ Integer in the range 0 to 32
+
+ `Q'
+ A memory reference where the exact address is in a single
+ register (``m'' is preferable for `asm' statements)
+
+ `R'
+ An item in the constant pool
+
+ `S'
+ A symbol in the text segment of the current file
+
+_AMD 29000 family--`a29k.h'_
+
+ `l'
+ Local register 0
+
+ `b'
+ Byte Pointer (`BP') register
+
+ `q'
+ `Q' register
+
+ `h'
+ Special purpose register
+
+ `A'
+ First accumulator register
+
+ `a'
+ Other accumulator register
+
+ `f'
+ Floating point register
+
+ `I'
+ Constant greater than 0, less than 0x100
+
+ `J'
+ Constant greater than 0, less than 0x10000
+
+ `K'
+ Constant whose high 24 bits are on (1)
+
+ `L'
+ 16-bit constant whose high 8 bits are on (1)
+
+ `M'
+ 32-bit constant whose high 16 bits are on (1)
+
+ `N'
+ 32-bit negative constant that fits in 8 bits
+
+ `O'
+ The constant 0x80000000 or, on the 29050, any 32-bit constant
+ whose low 16 bits are 0.
+
+ `P'
+ 16-bit negative constant that fits in 8 bits
+
+ `G'
+ `H'
+ A floating point constant (in `asm' statements, use the
+ machine independent `E' or `F' instead)
+
+_AVR family--`avr.h'_
+
+ `l'
+ Registers from r0 to r15
+
+ `a'
+ Registers from r16 to r23
+
+ `d'
+ Registers from r16 to r31
+
+ `w'
+ Registers from r24 to r31. These registers can be used in
+ `adiw' command
+
+ `e'
+ Pointer register (r26-r31)
+
+ `b'
+ Base pointer register (r28-r31)
+
+ `q'
+ Stack pointer register (SPH:SPL)
+
+ `t'
+ Temporary register r0
+
+ `x'
+ Register pair X (r27:r26)
+
+ `y'
+ Register pair Y (r29:r28)
+
+ `z'
+ Register pair Z (r31:r30)
+
+ `I'
+ Constant greater than -1, less than 64
+
+ `J'
+ Constant greater than -64, less than 1
+
+ `K'
+ Constant integer 2
+
+ `L'
+ Constant integer 0
+
+ `M'
+ Constant that fits in 8 bits
+
+ `N'
+ Constant integer -1
+
+ `O'
+ Constant integer 8, 16, or 24
+
+ `P'
+ Constant integer 1
+
+ `G'
+ A floating point constant 0.0
+
+_IBM RS6000--`rs6000.h'_
+
+ `b'
+ Address base register
+
+ `f'
+ Floating point register
+
+ `h'
+ `MQ', `CTR', or `LINK' register
+
+ `q'
+ `MQ' register
+
+ `c'
+ `CTR' register
+
+ `l'
+ `LINK' register
+
+ `x'
+ `CR' register (condition register) number 0
+
+ `y'
+ `CR' register (condition register)
+
+ `z'
+ `FPMEM' stack memory for FPR-GPR transfers
+
+ `I'
+ Signed 16-bit constant
+
+ `J'
+ Unsigned 16-bit constant shifted left 16 bits (use `L'
+ instead for `SImode' constants)
+
+ `K'
+ Unsigned 16-bit constant
+
+ `L'
+ Signed 16-bit constant shifted left 16 bits
+
+ `M'
+ Constant larger than 31
+
+ `N'
+ Exact power of 2
+
+ `O'
+ Zero
+
+ `P'
+ Constant whose negation is a signed 16-bit constant
+
+ `G'
+ Floating point constant that can be loaded into a register
+ with one instruction per word
+
+ `Q'
+ Memory operand that is an offset from a register (`m' is
+ preferable for `asm' statements)
+
+ `R'
+ AIX TOC entry
+
+ `S'
+ Constant suitable as a 64-bit mask operand
+
+ `T'
+ Constant suitable as a 32-bit mask operand
+
+ `U'
+ System V Release 4 small data area reference
+
+_Intel 386--`i386.h'_
+
+ `q'
+ `a', `b', `c', or `d' register for the i386. For x86-64 it
+ is equivalent to `r' class. (for 8-bit instructions that do
+ not use upper halves)
+
+ `Q'
+ `a', `b', `c', or `d' register. (for 8-bit instructions, that
+ do use upper halves)
+
+ `R'
+ Legacy register--equivalent to `r' class in i386 mode. (for
+ non-8-bit registers used together with 8-bit upper halves in
+ a single instruction)
+
+ `A'
+ Specifies the `a' or `d' registers. This is primarily useful
+ for 64-bit integer values (when in 32-bit mode) intended to
+ be returned with the `d' register holding the most
+ significant bits and the `a' register holding the least
+ significant bits.
+
+ `f'
+ Floating point register
+
+ `t'
+ First (top of stack) floating point register
+
+ `u'
+ Second floating point register
+
+ `a'
+ `a' register
+
+ `b'
+ `b' register
+
+ `c'
+ `c' register
+
+ `d'
+ `d' register
+
+ `D'
+ `di' register
+
+ `S'
+ `si' register
+
+ `x'
+ `xmm' SSE register
+
+ `y'
+ MMX register
+
+ `I'
+ Constant in range 0 to 31 (for 32-bit shifts)
+
+ `J'
+ Constant in range 0 to 63 (for 64-bit shifts)
+
+ `K'
+ `0xff'
+
+ `L'
+ `0xffff'
+
+ `M'
+ 0, 1, 2, or 3 (shifts for `lea' instruction)
+
+ `N'
+ Constant in range 0 to 255 (for `out' instruction)
+
+ `Z'
+ Constant in range 0 to `0xffffffff' or symbolic reference
+ known to fit specified range. (for using immediates in zero
+ extending 32-bit to 64-bit x86-64 instructions)
+
+ `e'
+ Constant in range -2147483648 to 2147483647 or symbolic
+ reference known to fit specified range. (for using
+ immediates in 64-bit x86-64 instructions)
+
+ `G'
+ Standard 80387 floating point constant
+
+_Intel 960--`i960.h'_
+
+ `f'
+ Floating point register (`fp0' to `fp3')
+
+ `l'
+ Local register (`r0' to `r15')
+
+ `b'
+ Global register (`g0' to `g15')
+
+ `d'
+ Any local or global register
+
+ `I'
+ Integers from 0 to 31
+
+ `J'
+ 0
+
+ `K'
+ Integers from -31 to 0
+
+ `G'
+ Floating point 0
+
+ `H'
+ Floating point 1
+
+_MIPS--`mips.h'_
+
+ `d'
+ General-purpose integer register
+
+ `f'
+ Floating-point register (if available)
+
+ `h'
+ `Hi' register
+
+ `l'
+ `Lo' register
+
+ `x'
+ `Hi' or `Lo' register
+
+ `y'
+ General-purpose integer register
+
+ `z'
+ Floating-point status register
+
+ `I'
+ Signed 16-bit constant (for arithmetic instructions)
+
+ `J'
+ Zero
+
+ `K'
+ Zero-extended 16-bit constant (for logic instructions)
+
+ `L'
+ Constant with low 16 bits zero (can be loaded with `lui')
+
+ `M'
+ 32-bit constant which requires two instructions to load (a
+ constant which is not `I', `K', or `L')
+
+ `N'
+ Negative 16-bit constant
+
+ `O'
+ Exact power of two
+
+ `P'
+ Positive 16-bit constant
+
+ `G'
+ Floating point zero
+
+ `Q'
+ Memory reference that can be loaded with more than one
+ instruction (`m' is preferable for `asm' statements)
+
+ `R'
+ Memory reference that can be loaded with one instruction (`m'
+ is preferable for `asm' statements)
+
+ `S'
+ Memory reference in external OSF/rose PIC format (`m' is
+ preferable for `asm' statements)
+
+_Motorola 680x0--`m68k.h'_
+
+ `a'
+ Address register
+
+ `d'
+ Data register
+
+ `f'
+ 68881 floating-point register, if available
+
+ `x'
+ Sun FPA (floating-point) register, if available
+
+ `y'
+ First 16 Sun FPA registers, if available
+
+ `I'
+ Integer in the range 1 to 8
+
+ `J'
+ 16-bit signed number
+
+ `K'
+ Signed number whose magnitude is greater than 0x80
+
+ `L'
+ Integer in the range -8 to -1
+
+ `M'
+ Signed number whose magnitude is greater than 0x100
+
+ `G'
+ Floating point constant that is not a 68881 constant
+
+ `H'
+ Floating point constant that can be used by Sun FPA
+
+_Motorola 68HC11 & 68HC12 families--`m68hc11.h'_
+
+ `a'
+ Register 'a'
+
+ `b'
+ Register 'b'
+
+ `d'
+ Register 'd'
+
+ `q'
+ An 8-bit register
+
+ `t'
+ Temporary soft register _.tmp
+
+ `u'
+ A soft register _.d1 to _.d31
+
+ `w'
+ Stack pointer register
+
+ `x'
+ Register 'x'
+
+ `y'
+ Register 'y'
+
+ `z'
+ Pseudo register 'z' (replaced by 'x' or 'y' at the end)
+
+ `A'
+ An address register: x, y or z
+
+ `B'
+ An address register: x or y
+
+ `D'
+ Register pair (x:d) to form a 32-bit value
+
+ `L'
+ Constants in the range -65536 to 65535
+
+ `M'
+ Constants whose 16-bit low part is zero
+
+ `N'
+ Constant integer 1 or -1
+
+ `O'
+ Constant integer 16
+
+ `P'
+ Constants in the range -8 to 2
+
+
+_SPARC--`sparc.h'_
+
+ `f'
+ Floating-point register that can hold 32- or 64-bit values.
+
+ `e'
+ Floating-point register that can hold 64- or 128-bit values.
+
+ `I'
+ Signed 13-bit constant
+
+ `J'
+ Zero
+
+ `K'
+ 32-bit constant with the low 12 bits clear (a constant that
+ can be loaded with the `sethi' instruction)
+
+ `L'
+ A constant in the range supported by `movcc' instructions
+
+ `M'
+ A constant in the range supported by `movrcc' instructions
+
+ `N'
+ Same as `K', except that it verifies that bits that are not
+ in the lower 32-bit range are all zero. Must be used instead
+ of `K' for modes wider than `SImode'
+
+ `G'
+ Floating-point zero
+
+ `H'
+ Signed 13-bit constant, sign-extended to 32 or 64 bits
+
+ `Q'
+ Floating-point constant whose integral representation can be
+ moved into an integer register using a single sethi
+ instruction
+
+ `R'
+ Floating-point constant whose integral representation can be
+ moved into an integer register using a single mov instruction
+
+ `S'
+ Floating-point constant whose integral representation can be
+ moved into an integer register using a high/lo_sum
+ instruction sequence
+
+ `T'
+ Memory address aligned to an 8-byte boundary
+
+ `U'
+ Even register
+
+ `W'
+ Memory address for `e' constraint registers.
+
+
+_TMS320C3x/C4x--`c4x.h'_
+
+ `a'
+ Auxiliary (address) register (ar0-ar7)
+
+ `b'
+ Stack pointer register (sp)
+
+ `c'
+ Standard (32-bit) precision integer register
+
+ `f'
+ Extended (40-bit) precision register (r0-r11)
+
+ `k'
+ Block count register (bk)
+
+ `q'
+ Extended (40-bit) precision low register (r0-r7)
+
+ `t'
+ Extended (40-bit) precision register (r0-r1)
+
+ `u'
+ Extended (40-bit) precision register (r2-r3)
+
+ `v'
+ Repeat count register (rc)
+
+ `x'
+ Index register (ir0-ir1)
+
+ `y'
+ Status (condition code) register (st)
+
+ `z'
+ Data page register (dp)
+
+ `G'
+ Floating-point zero
+
+ `H'
+ Immediate 16-bit floating-point constant
+
+ `I'
+ Signed 16-bit constant
+
+ `J'
+ Signed 8-bit constant
+
+ `K'
+ Signed 5-bit constant
+
+ `L'
+ Unsigned 16-bit constant
+
+ `M'
+ Unsigned 8-bit constant
+
+ `N'
+ Ones complement of unsigned 16-bit constant
+
+ `O'
+ High 16-bit constant (32-bit constant with 16 LSBs zero)
+
+ `Q'
+ Indirect memory reference with signed 8-bit or index register
+ displacement
+
+ `R'
+ Indirect memory reference with unsigned 5-bit displacement
+
+ `S'
+ Indirect memory reference with 1 bit or index register
+ displacement
+
+ `T'
+ Direct memory reference
+
+ `U'
+ Symbolic address
+
+
+_S/390 and zSeries--`s390.h'_
+
+ `a'
+ Address register (general purpose register except r0)
+
+ `d'
+ Data register (arbitrary general purpose register)
+
+ `f'
+ Floating-point register
+
+ `I'
+ Unsigned 8-bit constant (0-255)
+
+ `J'
+ Unsigned 12-bit constant (0-4095)
+
+ `K'
+ Signed 16-bit constant (-32768-32767)
+
+ `L'
+ Unsigned 16-bit constant (0-65535)
+
+ `Q'
+ Memory reference without index register
+
+ `S'
+ Symbolic constant suitable for use with the `larl' instruction
+
+
+_Xstormy16--`stormy16.h'_
+
+ `a'
+ Register r0.
+
+ `b'
+ Register r1.
+
+ `c'
+ Register r2.
+
+ `d'
+ Register r8.
+
+ `e'
+ Registers r0 through r7.
+
+ `t'
+ Registers r0 and r1.
+
+ `y'
+ The carry register.
+
+ `z'
+ Registers r8 and r9.
+
+ `I'
+ A constant between 0 and 3 inclusive.
+
+ `J'
+ A constant that has exactly one bit set.
+
+ `K'
+ A constant that has exactly one bit clear.
+
+ `L'
+ A constant between 0 and 255 inclusive.
+
+ `M'
+ A constant between -255 and 0 inclusive.
+
+ `N'
+ A constant between -3 and 0 inclusive.
+
+ `O'
+ A constant between 1 and 4 inclusive.
+
+ `P'
+ A constant between -4 and -1 inclusive.
+
+ `Q'
+ A memory reference that is a stack push.
+
+ `R'
+ A memory reference that is a stack pop.
+
+ `S'
+ A memory reference that refers to an constant address of
+ known value.
+
+ `T'
+ The register indicated by Rx (not implemented yet).
+
+ `U'
+ A constant that is not between 2 and 15 inclusive.
+
+
+_Xtensa--`xtensa.h'_
+
+ `a'
+ General-purpose 32-bit register
+
+ `b'
+ One-bit boolean register
+
+ `A'
+ MAC16 40-bit accumulator register
+
+ `I'
+ Signed 12-bit integer constant, for use in MOVI instructions
+
+ `J'
+ Signed 8-bit integer constant, for use in ADDI instructions
+
+ `K'
+ Integer constant valid for BccI instructions
+
+ `L'
+ Unsigned constant valid for BccUI instructions
+
+
+
+\1f
+File: gcc.info, Node: Asm Labels, Next: Explicit Reg Vars, Prev: Constraints, Up: C Extensions
+
+5.37 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.
+
+\1f
+File: gcc.info, Node: Explicit Reg Vars, Next: Alternate Keywords, Prev: Asm Labels, Up: C Extensions
+
+5.38 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::
+
+\1f
+File: gcc.info, Node: Global Reg Vars, Next: Local Reg Vars, Up: Explicit Reg Vars
+
+5.38.1 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.
+
+\1f
+File: gcc.info, Node: Local Reg Vars, Prev: Global Reg Vars, Up: Explicit Reg Vars
+
+5.38.2 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.
+
+\1f
+File: gcc.info, Node: Alternate Keywords, Next: Incomplete Enums, Prev: Explicit Reg Vars, Up: C Extensions
+
+5.39 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.
+
+\1f
+File: gcc.info, Node: Incomplete Enums, Next: Function Names, Prev: Alternate Keywords, Up: C Extensions
+
+5.40 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++.
+
+\1f
+File: gcc.info, Node: Function Names, Next: Return Address, Prev: Incomplete Enums, Up: C Extensions
+
+5.41 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__'.
+
+ Note that these semantics are deprecated, and that GCC 3.2 will
+handle `__FUNCTION__' and `__PRETTY_FUNCTION__' the same way as
+`__func__'. `__func__' is 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__'.
+
+\1f
+File: gcc.info, Node: Return Address, Next: Vector Extensions, Prev: Function Names, Up: C Extensions
+
+5.42 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.
+
+\1f
+File: gcc.info, Node: Vector Extensions, Next: Other Builtins, Prev: Return Address, Up: C Extensions
+
+5.43 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);
+ }