diff options
Diffstat (limited to 'contrib/gcc/doc/extend.texi')
| -rw-r--r-- | contrib/gcc/doc/extend.texi | 6616 |
1 files changed, 6616 insertions, 0 deletions
diff --git a/contrib/gcc/doc/extend.texi b/contrib/gcc/doc/extend.texi new file mode 100644 index 000000000000..ad88a2a83afc --- /dev/null +++ b/contrib/gcc/doc/extend.texi @@ -0,0 +1,6616 @@ +@c Copyright (C) 1988,1989,1992,1993,1994,1996,1998,1999,2000,2001,2002 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node C Implementation +@chapter C Implementation-defined behavior +@cindex implementation-defined behavior, C language + +A conforming implementation of ISO C is required to document its +choice of behavior in each of the areas that are designated +``implementation defined.'' The following lists all such areas, +along with the section number from the ISO/IEC 9899:1999 standard. + +@menu +* Translation implementation:: +* Environment implementation:: +* Identifiers implementation:: +* Characters implementation:: +* Integers implementation:: +* Floating point implementation:: +* Arrays and pointers implementation:: +* Hints implementation:: +* Structures unions enumerations and bit-fields implementation:: +* Qualifiers implementation:: +* Preprocessing directives implementation:: +* Library functions implementation:: +* Architecture implementation:: +* Locale-specific behavior implementation:: +@end menu + +@node Translation implementation +@section Translation + +@itemize @bullet +@item +@cite{How a diagnostic is identified (3.10, 5.1.1.3).} + +@item +@cite{Whether each nonempty sequence of white-space characters other than +new-line is retained or replaced by one space character in translation +phase 3 (5.1.1.2).} +@end itemize + +@node Environment implementation +@section Environment + +The behavior of these points are dependent on the implementation +of the C library, and are not defined by GCC itself. + +@node Identifiers implementation +@section Identifiers + +@itemize @bullet +@item +@cite{Which additional multibyte characters may appear in identifiers +and their correspondence to universal character names (6.4.2).} + +@item +@cite{The number of significant initial characters in an identifier +(5.2.4.1, 6.4.2).} +@end itemize + +@node Characters implementation +@section Characters + +@itemize @bullet +@item +@cite{The number of bits in a byte (3.6).} + +@item +@cite{The values of the members of the execution character set (5.2.1).} + +@item +@cite{The unique value of the member of the execution character set produced +for each of the standard alphabetic escape sequences (5.2.2).} + +@item +@cite{The value of a @code{char} object into which has been stored any +character other than a member of the basic execution character set (6.2.5).} + +@item +@cite{Which of @code{signed char} or @code{unsigned char} has the same range, +representation, and behavior as ``plain'' @code{char} (6.2.5, 6.3.1.1).} + +@item +@cite{The mapping of members of the source character set (in character +constants and string literals) to members of the execution character +set (6.4.4.4, 5.1.1.2).} + +@item +@cite{The value of an integer character constant containing more than one +character or containing a character or escape sequence that does not map +to a single-byte execution character (6.4.4.4).} + +@item +@cite{The value of a wide character constant containing more than one +multibyte character, or containing a multibyte character or escape +sequence not represented in the extended execution character set (6.4.4.4).} + +@item +@cite{The current locale used to convert a wide character constant consisting +of a single multibyte character that maps to a member of the extended +execution character set into a corresponding wide character code (6.4.4.4).} + +@item +@cite{The current locale used to convert a wide string literal into +corresponding wide character codes (6.4.5).} + +@item +@cite{The value of a string literal containing a multibyte character or escape +sequence not represented in the execution character set (6.4.5).} +@end itemize + +@node Integers implementation +@section Integers + +@itemize @bullet +@item +@cite{Any extended integer types that exist in the implementation (6.2.5).} + +@item +@cite{Whether signed integer types are represented using sign and magnitude, +two's complement, or one's complement, and whether the extraordinary value +is a trap representation or an ordinary value (6.2.6.2).} + +@item +@cite{The rank of any extended integer type relative to another extended +integer type with the same precision (6.3.1.1).} + +@item +@cite{The result of, or the signal raised by, converting an integer to a +signed integer type when the value cannot be represented in an object of +that type (6.3.1.3).} + +@item +@cite{The results of some bitwise operations on signed integers (6.5).} +@end itemize + +@node Floating point implementation +@section Floating point + +@itemize @bullet +@item +@cite{The accuracy of the floating-point operations and of the library +functions in @code{<math.h>} and @code{<complex.h>} that return floating-point +results (5.2.4.2.2).} + +@item +@cite{The rounding behaviors characterized by non-standard values +of @code{FLT_ROUNDS} @gol +(5.2.4.2.2).} + +@item +@cite{The evaluation methods characterized by non-standard negative +values of @code{FLT_EVAL_METHOD} (5.2.4.2.2).} + +@item +@cite{The direction of rounding when an integer is converted to a +floating-point number that cannot exactly represent the original +value (6.3.1.4).} + +@item +@cite{The direction of rounding when a floating-point number is +converted to a narrower floating-point number (6.3.1.5).} + +@item +@cite{How the nearest representable value or the larger or smaller +representable value immediately adjacent to the nearest representable +value is chosen for certain floating constants (6.4.4.2).} + +@item +@cite{Whether and how floating expressions are contracted when not +disallowed by the @code{FP_CONTRACT} pragma (6.5).} + +@item +@cite{The default state for the @code{FENV_ACCESS} pragma (7.6.1).} + +@item +@cite{Additional floating-point exceptions, rounding modes, environments, +and classifications, and their macro names (7.6, 7.12).} + +@item +@cite{The default state for the @code{FP_CONTRACT} pragma (7.12.2).} + +@item +@cite{Whether the ``inexact'' floating-point exception can be raised +when the rounded result actually does equal the mathematical result +in an IEC 60559 conformant implementation (F.9).} + +@item +@cite{Whether the ``underflow'' (and ``inexact'') floating-point +exception can be raised when a result is tiny but not inexact in an +IEC 60559 conformant implementation (F.9).} + +@end itemize + +@node Arrays and pointers implementation +@section Arrays and pointers + +@itemize @bullet +@item +@cite{The result of converting a pointer to an integer or +vice versa (6.3.2.3).} + +A cast from pointer to integer discards most-significant bits if the +pointer representation is larger than the integer type, +sign-extends@footnote{Future versions of GCC may zero-extend, or use +a target-defined @code{ptr_extend} pattern. Do not rely on sign extension.} +if the pointer representation is smaller than the integer type, otherwise +the bits are unchanged. +@c ??? We've always claimed that pointers were unsigned entities. +@c Shouldn't we therefore be doing zero-extension? If so, the bug +@c is in convert_to_integer, where we call type_for_size and request +@c a signed integral type. On the other hand, it might be most useful +@c for the target if we extend according to POINTERS_EXTEND_UNSIGNED. + +A cast from integer to pointer discards most-significant bits if the +pointer representation is smaller than the integer type, extends according +to the signedness of the integer type if the pointer representation +is larger than the integer type, otherwise the bits are unchanged. + +When casting from pointer to integer and back again, the resulting +pointer must reference the same object as the original pointer, otherwise +the behavior is undefined. That is, one may not use integer arithmetic to +avoid the undefined behavior of pointer arithmetic as proscribed in 6.5.6/8. + +@item +@cite{The size of the result of subtracting two pointers to elements +of the same array (6.5.6).} + +@end itemize + +@node Hints implementation +@section Hints + +@itemize @bullet +@item +@cite{The extent to which suggestions made by using the @code{register} +storage-class specifier are effective (6.7.1).} + +@item +@cite{The extent to which suggestions made by using the inline function +specifier are effective (6.7.4).} + +@end itemize + +@node Structures unions enumerations and bit-fields implementation +@section Structures, unions, enumerations, and bit-fields + +@itemize @bullet +@item +@cite{Whether a ``plain'' int bit-field is treated as a @code{signed int} +bit-field or as an @code{unsigned int} bit-field (6.7.2, 6.7.2.1).} + +@item +@cite{Allowable bit-field types other than @code{_Bool}, @code{signed int}, +and @code{unsigned int} (6.7.2.1).} + +@item +@cite{Whether a bit-field can straddle a storage-unit boundary (6.7.2.1).} + +@item +@cite{The order of allocation of bit-fields within a unit (6.7.2.1).} + +@item +@cite{The alignment of non-bit-field members of structures (6.7.2.1).} + +@item +@cite{The integer type compatible with each enumerated type (6.7.2.2).} + +@end itemize + +@node Qualifiers implementation +@section Qualifiers + +@itemize @bullet +@item +@cite{What constitutes an access to an object that has volatile-qualified +type (6.7.3).} + +@end itemize + +@node Preprocessing directives implementation +@section Preprocessing directives + +@itemize @bullet +@item +@cite{How sequences in both forms of header names are mapped to headers +or external source file names (6.4.7).} + +@item +@cite{Whether the value of a character constant in a constant expression +that controls conditional inclusion matches the value of the same character +constant in the execution character set (6.10.1).} + +@item +@cite{Whether the value of a single-character character constant in a +constant expression that controls conditional inclusion may have a +negative value (6.10.1).} + +@item +@cite{The places that are searched for an included @samp{<>} delimited +header, and how the places are specified or the header is +identified (6.10.2).} + +@item +@cite{How the named source file is searched for in an included @samp{""} +delimited header (6.10.2).} + +@item +@cite{The method by which preprocessing tokens (possibly resulting from +macro expansion) in a @code{#include} directive are combined into a header +name (6.10.2).} + +@item +@cite{The nesting limit for @code{#include} processing (6.10.2).} + +@item +@cite{Whether the @samp{#} operator inserts a @samp{\} character before +the @samp{\} character that begins a universal character name in a +character constant or string literal (6.10.3.2).} + +@item +@cite{The behavior on each recognized non-@code{STDC #pragma} +directive (6.10.6).} + +@item +@cite{The definitions for @code{__DATE__} and @code{__TIME__} when +respectively, the date and time of translation are not available (6.10.8).} + +@end itemize + +@node Library functions implementation +@section Library functions + +The behavior of these points are dependent on the implementation +of the C library, and are not defined by GCC itself. + +@node Architecture implementation +@section Architecture + +@itemize @bullet +@item +@cite{The values or expressions assigned to the macros specified in the +headers @code{<float.h>}, @code{<limits.h>}, and @code{<stdint.h>} +(5.2.4.2, 7.18.2, 7.18.3).} + +@item +@cite{The number, order, and encoding of bytes in any object +(when not explicitly specified in this International Standard) (6.2.6.1).} + +@item +@cite{The value of the result of the sizeof operator (6.5.3.4).} + +@end itemize + +@node Locale-specific behavior implementation +@section Locale-specific behavior + +The behavior of these points are dependent on the implementation +of the C library, and are not defined by GCC itself. + +@node C Extensions +@chapter Extensions to the C Language Family +@cindex extensions, C language +@cindex C language extensions + +@opindex pedantic +GNU C provides several language features not found in ISO standard C@. +(The @option{-pedantic} option directs GCC to print a warning message if +any of these features is used.) To test for the availability of these +features in conditional compilation, check for a predefined macro +@code{__GNUC__}, which is always defined under GCC@. + +These extensions are available in C and Objective-C@. Most of them are +also available in C++. @xref{C++ Extensions,,Extensions to the +C++ Language}, for extensions that apply @emph{only} to C++. + +Some features that are in ISO C99 but not C89 or C++ are also, as +extensions, accepted by GCC in C89 mode and in C++. + +@menu +* Statement Exprs:: Putting statements and declarations inside expressions. +* Local Labels:: Labels local to a statement-expression. +* Labels as Values:: Getting pointers to labels, and computed gotos. +* Nested Functions:: As in Algol and Pascal, lexical scoping of functions. +* Constructing Calls:: Dispatching a call to another function. +* Naming Types:: Giving a name to the type of some expression. +* Typeof:: @code{typeof}: referring to the type of an expression. +* Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues. +* Conditionals:: Omitting the middle operand of a @samp{?:} expression. +* Long Long:: Double-word integers---@code{long long int}. +* Complex:: Data types for complex numbers. +* Hex Floats:: Hexadecimal floating-point constants. +* Zero Length:: Zero-length arrays. +* Variable Length:: Arrays whose length is computed at run time. +* Variadic Macros:: Macros with a variable number of arguments. +* Escaped Newlines:: Slightly looser rules for escaped newlines. +* Multi-line Strings:: String literals with embedded newlines. +* Subscripting:: Any array can be subscripted, even if not an lvalue. +* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. +* Initializers:: Non-constant initializers. +* Compound Literals:: Compound literals give structures, unions + or arrays as values. +* Designated Inits:: Labeling elements of initializers. +* Cast to Union:: Casting to union type from any member of the union. +* Case Ranges:: `case 1 ... 9' and such. +* Mixed Declarations:: Mixing declarations and code. +* Function Attributes:: Declaring that functions have no side effects, + or that they can never return. +* Attribute Syntax:: Formal syntax for attributes. +* Function Prototypes:: Prototype declarations and old-style definitions. +* C++ Comments:: C++ comments are recognized. +* Dollar Signs:: Dollar sign is allowed in identifiers. +* Character Escapes:: @samp{\e} stands for the character @key{ESC}. +* Variable Attributes:: Specifying attributes of variables. +* Type Attributes:: Specifying attributes of types. +* Alignment:: Inquiring about the alignment of a type or variable. +* Inline:: Defining inline functions (as fast as macros). +* Extended Asm:: Assembler instructions with C expressions as operands. + (With them you can define ``built-in'' functions.) +* Constraints:: Constraints for asm operands +* Asm Labels:: Specifying the assembler name to use for a C symbol. +* Explicit Reg Vars:: Defining variables residing in specified registers. +* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. +* Incomplete Enums:: @code{enum foo;}, with details to follow. +* Function Names:: Printable strings which are the name of the current + function. +* Return Address:: Getting the return or frame address of a function. +* Vector Extensions:: Using vector instructions through built-in functions. +* Other Builtins:: Other built-in functions. +* Target Builtins:: Built-in functions specific to particular targets. +* Pragmas:: Pragmas accepted by GCC. +* Unnamed Fields:: Unnamed struct/union fields within structs/unions. +@end menu + +@node Statement Exprs +@section Statements and Declarations in Expressions +@cindex statements inside expressions +@cindex declarations inside expressions +@cindex expressions containing statements +@cindex macros, statements in expressions + +@c the above section title wrapped and causes an underfull hbox.. i +@c changed it from "within" to "in". --mew 4feb93 + +A compound statement enclosed in parentheses may appear as an expression +in GNU C@. This allows you to use loops, switches, and local variables +within an expression. + +Recall that a compound statement is a sequence of statements surrounded +by braces; in this construct, parentheses go around the braces. For +example: + +@example +(@{ int y = foo (); int z; + if (y > 0) z = y; + else z = - y; + z; @}) +@end example + +@noindent +is a valid (though slightly more complex than necessary) expression +for the absolute value of @code{foo ()}. + +The last thing in the compound statement should be an expression +followed by a semicolon; the value of this subexpression serves as the +value of the entire construct. (If you use some other kind of statement +last within the braces, the construct has type @code{void}, and thus +effectively no value.) + +This feature is especially useful in making macro definitions ``safe'' (so +that they evaluate each operand exactly once). For example, the +``maximum'' function is commonly defined as a macro in standard C as +follows: + +@example +#define max(a,b) ((a) > (b) ? (a) : (b)) +@end example + +@noindent +@cindex side effects, macro argument +But this definition computes either @var{a} or @var{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 @code{int}), you can define +the macro safely as follows: + +@example +#define maxint(a,b) \ + (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) +@end example + +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 @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming +Types}). + +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: + +@example +#define foo(a) (@{int b = (a); b + 3; @}) +@end example + +@noindent +does not work the same way as: + +@example +inline int foo(int a) @{ int b = a; return b + 3; @} +@end example + +@noindent +In particular, if the expression passed into @code{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.) + +@node Local Labels +@section Locally Declared Labels +@cindex local labels +@cindex macros, local labels + +Each statement expression is a scope in which @dfn{local labels} can be +declared. A local label is simply an identifier; you can jump to it +with an ordinary @code{goto} statement, but only from within the +statement expression it belongs to. + +A local label declaration looks like this: + +@example +__label__ @var{label}; +@end example + +@noindent +or + +@example +__label__ @var{label1}, @var{label2}, @dots{}; +@end example + +Local label declarations must come at the beginning of the statement +expression, right after the @samp{(@{}, before any ordinary +declarations. + +The label declaration defines the label @emph{name}, but does not define +the label itself. You must do this in the usual way, with +@code{@var{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 @code{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: + +@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; \ +@}) +@end example + +@node Labels as Values +@section Labels as Values +@cindex labels as values +@cindex computed gotos +@cindex goto with computed label +@cindex address of a label + +You can get the address of a label defined in the current function +(or a containing function) with the unary operator @samp{&&}. The +value has type @code{void *}. This value is a constant and can be used +wherever a constant of that type is valid. For example: + +@example +void *ptr; +@dots{} +ptr = &&foo; +@end example + +To use these values, you need to be able to jump to one. This is done +with the computed goto statement@footnote{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.}, @code{goto *@var{exp};}. For example, + +@example +goto *ptr; +@end example + +@noindent +Any expression of type @code{void *} is allowed. + +One way of using these constants is in initializing a static array that +will serve as a jump table: + +@example +static void *array[] = @{ &&foo, &&bar, &&hack @}; +@end example + +Then you can select a label with indexing, like this: + +@example +goto *array[i]; +@end example + +@noindent +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 +@code{switch} statement. The @code{switch} statement is cleaner, so +use that rather than an array unless the problem does not fit a +@code{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 + +@example +static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, + &&hack - &&foo @}; +goto *(&&foo + array[i]); +@end example + +@noindent +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. + +@node Nested Functions +@section Nested Functions +@cindex nested functions +@cindex downward funargs +@cindex thunks + +A @dfn{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 @code{square}, and call it twice: + +@example +@group +foo (double a, double b) +@{ + double square (double z) @{ return z * z; @} + + return square (a) + square (b); +@} +@end group +@end example + +The nested function can access all the variables of the containing +function that are visible at the point of its definition. This is +called @dfn{lexical scoping}. For example, here we show a nested +function which uses an inherited variable named @code{offset}: + +@example +@group +bar (int *array, int offset, int size) +@{ + int access (int *array, int index) + @{ return array[index + offset]; @} + int i; + @dots{} + for (i = 0; i < size; i++) + @dots{} access (array, i) @dots{} +@} +@end group +@end example + +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: + +@example +hack (int *array, int size) +@{ + void store (int index, int value) + @{ array[index] = value; @} + + intermediate (store, size); +@} +@end example + +Here, the function @code{intermediate} receives the address of +@code{store} as an argument. If @code{intermediate} calls @code{store}, +the arguments given to @code{store} are used to store into @code{array}. +But this technique works only so long as the containing function +(@code{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 @dfn{trampolines}. A paper describing them is available as + +@noindent +@uref{http://people.debian.org/~karlheg/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 (@pxref{Local Labels}). Such a jump returns instantly to the +containing function, exiting the nested function which did the +@code{goto} and any intermediate functions as well. Here is an example: + +@example +@group +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; + @dots{} + for (i = 0; i < size; i++) + @dots{} access (array, i) @dots{} + @dots{} + return 0; + + /* @r{Control comes here from @code{access} + if it detects an error.} */ + failure: + return -1; +@} +@end group +@end example + +A nested function always has internal linkage. Declaring one with +@code{extern} is erroneous. If you need to declare the nested function +before its definition, use @code{auto} (which is otherwise meaningless +for function declarations). + +@example +bar (int *array, int offset, int size) +@{ + __label__ failure; + auto int access (int *, int); + @dots{} + int access (int *array, int index) + @{ + if (index > size) + goto failure; + return array[index + offset]; + @} + @dots{} +@} +@end example + +@node Constructing Calls +@section Constructing Function Calls +@cindex constructing calls +@cindex forwarding 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). + +@deftypefn {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. +@end deftypefn + +@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) +This built-in function invokes @var{function} +with a copy of the parameters described by @var{arguments} +and @var{size}. + +The value of @var{arguments} should be the value returned by +@code{__builtin_apply_args}. The argument @var{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 @var{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 @var{size}. The +value is used by @code{__builtin_apply} to compute the amount of data +that should be pushed on the stack and copied from the incoming argument +area. +@end deftypefn + +@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) +This built-in function returns the value described by @var{result} from +the containing function. You should specify, for @var{result}, a value +returned by @code{__builtin_apply}. +@end deftypefn + +@node Naming Types +@section Naming an Expression's Type +@cindex naming types + +You can give a name to the type of an expression using a @code{typedef} +declaration with an initializer. Here is how to define @var{name} as a +type name for the type of @var{exp}: + +@example +typedef @var{name} = @var{exp}; +@end example + +This is useful in conjunction with the statements-within-expressions +feature. Here is how the two together can be used to define a safe +``maximum'' macro that operates on any arithmetic type: + +@example +#define max(a,b) \ + (@{typedef _ta = (a), _tb = (b); \ + _ta _a = (a); _tb _b = (b); \ + _a > _b ? _a : _b; @}) +@end example + +@cindex underscores in variables in macros +@cindex @samp{_} in variables in macros +@cindex local variables in macros +@cindex variables, local, in macros +@cindex macros, local variables in + +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 @code{a} and @code{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. + +@node Typeof +@section Referring to a Type with @code{typeof} +@findex typeof +@findex sizeof +@cindex macros, types of arguments + +Another way to refer to the type of an expression is with @code{typeof}. +The syntax of using of this keyword looks like @code{sizeof}, but the +construct acts semantically like a type name defined with @code{typedef}. + +There are two ways of writing the argument to @code{typeof}: with an +expression or with a type. Here is an example with an expression: + +@example +typeof (x[0](1)) +@end example + +@noindent +This assumes that @code{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: + +@example +typeof (int *) +@end example + +@noindent +Here the type described is that of pointers to @code{int}. + +If you are writing a header file that must work when included in ISO C +programs, write @code{__typeof__} instead of @code{typeof}. +@xref{Alternate Keywords}. + +A @code{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 @code{sizeof} or @code{typeof}. + +@itemize @bullet +@item +This declares @code{y} with the type of what @code{x} points to. + +@example +typeof (*x) y; +@end example + +@item +This declares @code{y} as an array of such values. + +@example +typeof (*x) y[4]; +@end example + +@item +This declares @code{y} as an array of pointers to characters: + +@example +typeof (typeof (char *)[4]) y; +@end example + +@noindent +It is equivalent to the following traditional C declaration: + +@example +char *y[4]; +@end example + +To see the meaning of the declaration using @code{typeof}, and why it +might be a useful way to write, let's rewrite it with these macros: + +@example +#define pointer(T) typeof(T *) +#define array(T, N) typeof(T [N]) +@end example + +@noindent +Now the declaration can be rewritten this way: + +@example +array (pointer (char), 4) y; +@end example + +@noindent +Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 +pointers to @code{char}. +@end itemize + +@node Lvalues +@section Generalized Lvalues +@cindex compound expressions as lvalues +@cindex expressions, compound, as lvalues +@cindex conditional expressions as lvalues +@cindex expressions, conditional, as lvalues +@cindex casts as lvalues +@cindex generalized lvalues +@cindex lvalues, generalized +@cindex extensions, @code{?:} +@cindex @code{?:} extensions +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: + +@example +(a, b) += 5 +a, (b += 5) +@end example + +Similarly, the address of the compound expression can be taken. These two +expressions are equivalent: + +@example +&(a, b) +a, &b +@end example + +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: + +@example +(a ? b : c) = 5 +(a ? b = 5 : (c = 5)) +@end example + +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 @code{a} has type @code{char *}, the following two +expressions are equivalent: + +@example +(int)a = 5 +(int)(a = (char *)(int)5) +@end example + +An assignment-with-arithmetic operation such as @samp{+=} 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: + +@example +(int)a += 5 +(int)(a = (char *)(int) ((int)a + 5)) +@end example + +You cannot take the address of an lvalue cast, because the use of its +address would not work out coherently. Suppose that @code{&(int)f} were +permitted, where @code{f} has type @code{float}. Then the following +statement would try to store an integer bit-pattern where a floating +point number belongs: + +@example +*&(int)f = 1; +@end example + +This is quite different from what @code{(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 @samp{&} on a cast. + +If you really do want an @code{int *} pointer with the address of +@code{f}, you can simply write @code{(int *)&f}. + +@node Conditionals +@section Conditionals with Omitted Operands +@cindex conditional expressions, extensions +@cindex omitted middle-operands +@cindex middle-operands, omitted +@cindex extensions, @code{?:} +@cindex @code{?:} extensions + +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 + +@example +x ? : y +@end example + +@noindent +has the value of @code{x} if that is nonzero; otherwise, the value of +@code{y}. + +This example is perfectly equivalent to + +@example +x ? x : y +@end example + +@cindex side effect in ?: +@cindex ?: side effect +@noindent +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. + +@node Long Long +@section Double-Word Integers +@cindex @code{long long} data types +@cindex double-word arithmetic +@cindex multiprecision arithmetic +@cindex @code{LL} integer suffix +@cindex @code{ULL} integer suffix + +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 @code{long long int} for a signed integer, or +@code{unsigned long long int} for an unsigned integer. To make an +integer constant of type @code{long long int}, add the suffix @samp{LL} +to the integer. To make an integer constant of type @code{unsigned long +long int}, add the suffix @samp{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 @code{long long} types for function +arguments, unless you declare function prototypes. If a function +expects type @code{int} for its argument, and you pass a value of type +@code{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 @code{long long int} and you pass +@code{int}. The best way to avoid such problems is to use prototypes. + +@node Complex +@section Complex Numbers +@cindex complex numbers +@cindex @code{_Complex} keyword +@cindex @code{__complex__} keyword + +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 @code{_Complex}. As an extension, the older GNU +keyword @code{__complex__} is also supported. + +For example, @samp{_Complex double x;} declares @code{x} as a +variable whose real part and imaginary part are both of type +@code{double}. @samp{_Complex short int y;} declares @code{y} to +have real and imaginary parts of type @code{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 @samp{i} or +@samp{j} (either one; they are equivalent). For example, @code{2.5fi} +has type @code{_Complex float} and @code{3i} has type +@code{_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 @code{<complex.h>} and +use the macros @code{I} or @code{_Complex_I} instead. + +@cindex @code{__real__} keyword +@cindex @code{__imag__} keyword +To extract the real part of a complex-valued expression @var{exp}, write +@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to +extract the imaginary part. This is a GNU extension; for values of +floating type, you should use the ISO C99 functions @code{crealf}, +@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and +@code{cimagl}, declared in @code{<complex.h>} and also provided as +built-in functions by GCC@. + +@cindex complex conjugation +The operator @samp{~} 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 @code{conjf}, +@code{conj} and @code{conjl}, declared in @code{<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 @code{foo}, the two fictitious +variables are named @code{foo$real} and @code{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. + +@node Hex Floats +@section Hex Floats +@cindex hex floats + +ISO C99 supports floating-point numbers written not only in the usual +decimal notation, such as @code{1.55e1}, but also numbers such as +@code{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 +@samp{0x} hex introducer and the @samp{p} or @samp{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 @samp{0x1.f} is +@tex +$1 {15\over16}$, +@end tex +@ifnottex +1 15/16, +@end ifnottex +@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} +is the same as @code{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., @code{0x1.f}. This +could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the +extension for floating-point constants of type @code{float}. + +@node Zero Length +@section Arrays of Length Zero +@cindex arrays of length zero +@cindex zero-length arrays +@cindex length-zero arrays +@cindex flexible array members + +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: + +@example +struct line @{ + int length; + char contents[0]; +@}; + +struct line *thisline = (struct line *) + malloc (sizeof (struct line) + this_length); +thisline->length = this_length; +@end example + +In ISO C89, you would have to give @code{contents} a length of 1, which +means either you waste space or complicate the argument to @code{malloc}. + +In ISO C99, you would use a @dfn{flexible array member}, which is +slightly different in syntax and semantics: + +@itemize @bullet +@item +Flexible array members are written as @code{contents[]} without +the @code{0}. + +@item +Flexible array members have incomplete type, and so the @code{sizeof} +operator may not be applied. As a quirk of the original implementation +of zero-length arrays, @code{sizeof} evaluates to zero. + +@item +Flexible array members may only appear as the last member of a +@code{struct} that is otherwise non-empty. +@end itemize + +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, @code{f1} is constructed as if it were declared +like @code{f2}. + +@example +struct f1 @{ + int x; int y[]; +@} f1 = @{ 1, @{ 2, 3, 4 @} @}; + +struct f2 @{ + struct f1 f1; int data[3]; +@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; +@end example + +@noindent +The convenience of this extension is that @code{f1} has the desired +type, eliminating the need to consistently refer to @code{f2.f1}. + +This has symmetry with normal static arrays, in that an array of +unknown size is also written with @code{[]}. + +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: + +@example +struct foo @{ int x; int y[]; @}; +struct bar @{ struct foo z; @}; + +struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} +struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} +struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} +struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.} +@end example + +@node Variable Length +@section Arrays of Variable Length +@cindex variable-length arrays +@cindex arrays of variable length +@cindex VLAs + +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: + +@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); +@} +@end example + +@cindex scope of a variable length array +@cindex variable-length array scope +@cindex deallocating variable length arrays +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. + +@cindex @code{alloca} vs variable-length arrays +You can use the function @code{alloca} to get an effect much like +variable-length arrays. The function @code{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 @code{alloca} exists until the containing @emph{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 +@code{alloca} in the same function, deallocation of a variable-length array +will also deallocate anything more recently allocated with @code{alloca}.) + +You can also use variable-length arrays as arguments to functions: + +@example +struct entry +tester (int len, char data[len][len]) +@{ + @dots{} +@} +@end example + +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 +@code{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. + +@example +struct entry +tester (int len; char data[len][len], int len) +@{ + @dots{} +@} +@end example + +@cindex parameter forward declaration +The @samp{int len} before the semicolon is a @dfn{parameter forward +declaration}, and it serves the purpose of making the name @code{len} +known when the declaration of @code{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. + +@node Variadic Macros +@section Macros with a Variable Number of Arguments. +@cindex variable number of arguments +@cindex macro with variable arguments +@cindex rest argument (in macro) +@cindex variadic macros + +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: + +@example +#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) +@end example + +Here @samp{@dots{}} is a @dfn{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 @code{__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: + +@example +#define debug(format, args...) fprintf (stderr, format, args) +@end example + +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: + +@example +debug ("A message") +@end example + +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, @samp{##}. If instead you write + +@example +#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) +@end example + +and if the variable arguments are omitted or empty, the @samp{##} +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. + +@node Escaped Newlines +@section Slightly Looser Rules for Escaped Newlines +@cindex escaped newlines +@cindex newlines (escaped) + +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 @emph{not} treated as whitespace for the purposes of this +relaxation, since they have not yet been replaced with spaces. + +@node Multi-line Strings +@section String Literals with Embedded Newlines +@cindex multi-line string literals + +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 @samp{\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 +@samp{#include} family). This is deprecated and will eventually be +removed. + +@node Subscripting +@section Non-Lvalue Arrays May Have Subscripts +@cindex subscripting +@cindex arrays, non-lvalue + +@cindex subscripting and function values +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 @samp{&} 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: + +@example +@group +struct foo @{int a[4];@}; + +struct foo f(); + +bar (int index) +@{ + return f().a[index]; +@} +@end group +@end example + +@node Pointer Arith +@section Arithmetic on @code{void}- and Function-Pointers +@cindex void pointers, arithmetic +@cindex void, size of pointer to +@cindex function pointers, arithmetic +@cindex function, size of pointer to + +In GNU C, addition and subtraction operations are supported on pointers to +@code{void} and on pointers to functions. This is done by treating the +size of a @code{void} or of a function as 1. + +A consequence of this is that @code{sizeof} is also allowed on @code{void} +and on function types, and returns 1. + +@opindex Wpointer-arith +The option @option{-Wpointer-arith} requests a warning if these extensions +are used. + +@node Initializers +@section Non-Constant Initializers +@cindex initializers, non-constant +@cindex 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: + +@example +foo (float f, float g) +@{ + float beat_freqs[2] = @{ f-g, f+g @}; + @dots{} +@} +@end example + +@node Compound Literals +@section Compound Literals +@cindex constructor expressions +@cindex initializations in expressions +@cindex structures, constructor expression +@cindex expressions, constructor +@cindex compound literals +@c The GNU C name for what C99 calls compound literals was "constructor expressions". + +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 +@code{struct foo} and @code{structure} are declared as shown: + +@example +struct foo @{int a; char b[2];@} structure; +@end example + +@noindent +Here is an example of constructing a @code{struct foo} with a compound literal: + +@example +structure = ((struct foo) @{x + y, 'a', 0@}); +@end example + +@noindent +This is equivalent to writing the following: + +@example +@{ + struct foo temp = @{x + y, 'a', 0@}; + structure = temp; +@} +@end example + +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: + +@example +char **foo = (char *[]) @{ "x", "y", "z" @}; +@end example + +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. + +@example +static struct foo x = (struct foo) @{1, 'a', 'b'@}; +static int y[] = (int []) @{1, 2, 3@}; +static int z[] = (int [3]) @{1@}; +@end example + +@noindent +The above lines are equivalent to the following: +@example +static struct foo x = @{1, 'a', 'b'@}; +static int y[] = @{1, 2, 3@}; +static int z[] = @{1, 0, 0@}; +@end example + +@node Designated Inits +@section Designated Initializers +@cindex initializers with labeled elements +@cindex labeled elements in initializers +@cindex case labels in initializers +@cindex 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 +@samp{[@var{index}] =} before the element value. For example, + +@example +int a[6] = @{ [4] = 29, [2] = 15 @}; +@end example + +@noindent +is equivalent to + +@example +int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; +@end example + +@noindent +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 @samp{[@var{index}]} before the element +value, with no @samp{=}. + +To initialize a range of elements to the same value, write +@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU +extension. For example, + +@example +int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; +@end example + +@noindent +If the value in it has side-effects, the side-effects will happen only once, +not for each initialized field by the range initializer. + +@noindent +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 @samp{.@var{fieldname} =} before the element value. For example, +given the following structure, + +@example +struct point @{ int x, y; @}; +@end example + +@noindent +the following initialization + +@example +struct point p = @{ .y = yvalue, .x = xvalue @}; +@end example + +@noindent +is equivalent to + +@example +struct point p = @{ xvalue, yvalue @}; +@end example + +Another syntax which has the same meaning, obsolete since GCC 2.5, is +@samp{@var{fieldname}:}, as shown here: + +@example +struct point p = @{ y: yvalue, x: xvalue @}; +@end example + +@cindex designators +The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a +@dfn{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, + +@example +union foo @{ int i; double d; @}; + +union foo f = @{ .d = 4 @}; +@end example + +@noindent +will convert 4 to a @code{double} to store it in the union using +the second element. By contrast, casting 4 to type @code{union foo} +would store it into the union as the integer @code{i}, since it is +an integer. (@xref{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, + +@example +int a[6] = @{ [1] = v1, v2, [4] = v4 @}; +@end example + +@noindent +is equivalent to + +@example +int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; +@end example + +Labeling the elements of an array initializer is especially useful +when the indices are characters or belong to an @code{enum} type. +For example: + +@example +int whitespace[256] + = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, + ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; +@end example + +@cindex designator lists +You can also write a series of @samp{.@var{fieldname}} and +@samp{[@var{index}]} designators before an @samp{=} 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 @samp{struct point} declaration above: + +@example +struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; +@end example + +@noindent +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. + +@node Case Ranges +@section Case Ranges +@cindex case ranges +@cindex ranges in case statements + +You can specify a range of consecutive values in a single @code{case} label, +like this: + +@example +case @var{low} ... @var{high}: +@end example + +@noindent +This has the same effect as the proper number of individual @code{case} +labels, one for each integer value from @var{low} to @var{high}, inclusive. + +This feature is especially useful for ranges of ASCII character codes: + +@example +case 'A' ... 'Z': +@end example + +@strong{Be careful:} Write spaces around the @code{...}, for otherwise +it may be parsed wrong when you use it with integer values. For example, +write this: + +@example +case 1 ... 5: +@end example + +@noindent +rather than this: + +@example +case 1...5: +@end example + +@node Cast to Union +@section Cast to a Union Type +@cindex cast to a union +@cindex union, casting to a + +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 +@code{union @var{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. (@xref{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: + +@example +union foo @{ int i; double d; @}; +int x; +double y; +@end example + +@noindent +both @code{x} and @code{y} can be cast to type @code{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: + +@example +union foo u; +@dots{} +u = (union foo) x @equiv{} u.i = x +u = (union foo) y @equiv{} u.d = y +@end example + +You can also use the union cast as a function argument: + +@example +void hack (union foo); +@dots{} +hack ((union foo) x); +@end example + +@node Mixed Declarations +@section Mixed Declarations and Code +@cindex mixed declarations and code +@cindex declarations, mixed with code +@cindex code, mixed with declarations + +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: + +@example +int i; +@dots{} +i++; +int j = i + 2; +@end example + +Each identifier is visible from where it is declared until the end of +the enclosing block. + +@node Function Attributes +@section Declaring Attributes of Functions +@cindex function attributes +@cindex declaring attributes of functions +@cindex functions that never return +@cindex functions that have no side effects +@cindex functions in arbitrary sections +@cindex functions that behave like malloc +@cindex @code{volatile} applied to function +@cindex @code{const} applied to function +@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments +@cindex functions that are passed arguments in registers on the 386 +@cindex functions that pop the argument stack on the 386 +@cindex functions that do not pop the argument stack on the 386 + +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 @code{__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: +@code{noreturn}, @code{noinline}, @code{pure}, @code{const}, +@code{format}, @code{format_arg}, @code{no_instrument_function}, +@code{section}, @code{constructor}, @code{destructor}, @code{used}, +@code{unused}, @code{deprecated}, @code{weak}, @code{malloc}, and +@code{alias}. Several other attributes are defined for functions on +particular target systems. Other attributes, including @code{section} +are supported for variables declarations (@pxref{Variable Attributes}) +and for types (@pxref{Type Attributes}). + +You may also specify attributes with @samp{__} 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 @code{__noreturn__} instead of @code{noreturn}. + +@xref{Attribute Syntax}, for details of the exact syntax for using +attributes. + +@table @code +@cindex @code{noreturn} function attribute +@item noreturn +A few standard library functions, such as @code{abort} and @code{exit}, +cannot return. GCC knows this automatically. Some programs define +their own functions that never return. You can declare them +@code{noreturn} to tell the compiler this fact. For example, + +@smallexample +@group +void fatal () __attribute__ ((noreturn)); + +void +fatal (@dots{}) +@{ + @dots{} /* @r{Print error message.} */ @dots{} + exit (1); +@} +@end group +@end smallexample + +The @code{noreturn} keyword tells the compiler to assume that +@code{fatal} cannot return. It can then optimize without regard to what +would happen if @code{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 @code{noreturn} function. + +It does not make sense for a @code{noreturn} function to have a return +type other than @code{void}. + +The attribute @code{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: + +@smallexample +typedef void voidfn (); + +volatile voidfn fatal; +@end smallexample + +@cindex @code{noinline} function attribute +@item noinline +This function attribute prevents a function from being considered for +inlining. + +@cindex @code{pure} function attribute +@item 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 @code{pure}. For example, + +@smallexample +int square (int) __attribute__ ((pure)); +@end smallexample + +@noindent +says that the hypothetical function @code{square} is safe to call +fewer times than the program says. + +Some of common examples of pure functions are @code{strlen} or @code{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 @code{feof} in a multithreading environment). + +The attribute @code{pure} is not implemented in GCC versions earlier +than 2.96. +@cindex @code{const} function attribute +@item 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 @code{pure} attribute above, since function is not +allowed to read global memory. + +@cindex pointer arguments +Note that a function that has pointer arguments and examines the data +pointed to must @emph{not} be declared @code{const}. Likewise, a +function that calls a non-@code{const} function usually must not be +@code{const}. It does not make sense for a @code{const} function to +return @code{void}. + +The attribute @code{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: + +@smallexample +typedef int intfn (); + +extern const intfn square; +@end smallexample + +This approach does not work in GNU C++ from 2.6.0 on, since the language +specifies that the @samp{const} must be attached to the return value. + + +@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) +@cindex @code{format} function attribute +@opindex Wformat +The @code{format} attribute specifies that a function takes @code{printf}, +@code{scanf}, @code{strftime} or @code{strfmon} style arguments which +should be type-checked against a format string. For example, the +declaration: + +@smallexample +extern int +my_printf (void *my_object, const char *my_format, ...) + __attribute__ ((format (printf, 2, 3))); +@end smallexample + +@noindent +causes the compiler to check the arguments in calls to @code{my_printf} +for consistency with the @code{printf} style format string argument +@code{my_format}. + +The parameter @var{archetype} determines how the format string is +interpreted, and should be @code{printf}, @code{scanf}, @code{strftime} +or @code{strfmon}. (You can also use @code{__printf__}, +@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) The +parameter @var{string-index} specifies which argument is the format +string argument (starting from 1), while @var{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 +@code{vprintf}), specify the third parameter as zero. In this case the +compiler only checks the format string for consistency. For +@code{strftime} formats, the third parameter is required to be zero. + +In the example above, the format string (@code{my_format}) is the second +argument of the function @code{my_print}, and the arguments to check +start with the third argument, so the correct parameters for the format +attribute are 2 and 3. + +@opindex ffreestanding +The @code{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 +@option{-ffreestanding} is used) checks formats +for the standard library functions @code{printf}, @code{fprintf}, +@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, +@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such +warnings are requested (using @option{-Wformat}), so there is no need to +modify the header file @file{stdio.h}. In C99 mode, the functions +@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and +@code{vsscanf} are also checked. Except in strictly conforming C +standard modes, the X/Open function @code{strfmon} is also checked as +are @code{printf_unlocked} and @code{fprintf_unlocked}. +@xref{C Dialect Options,,Options Controlling C Dialect}. + +@item format_arg (@var{string-index}) +@cindex @code{format_arg} function attribute +@opindex Wformat-nonliteral +The @code{format_arg} attribute specifies that a function takes a format +string for a @code{printf}, @code{scanf}, @code{strftime} or +@code{strfmon} style function and modifies it (for example, to translate +it into another language), so the result can be passed to a +@code{printf}, @code{scanf}, @code{strftime} or @code{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: + +@smallexample +extern char * +my_dgettext (char *my_domain, const char *my_format) + __attribute__ ((format_arg (2))); +@end smallexample + +@noindent +causes the compiler to check the arguments in calls to a @code{printf}, +@code{scanf}, @code{strftime} or @code{strfmon} type function, whose +format string argument is a call to the @code{my_dgettext} function, for +consistency with the format string argument @code{my_format}. If the +@code{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 +@option{-Wformat-nonliteral} is used, but the calls could not be checked +without the attribute. + +The parameter @var{string-index} specifies which argument is the format +string argument (starting from 1). + +The @code{format-arg} attribute allows you to identify your own +functions which modify format strings, so that GCC can check the +calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} +type function whose operands are a call to one of your own function. +The compiler always treats @code{gettext}, @code{dgettext}, and +@code{dcgettext} in this manner except when strict ISO C support is +requested by @option{-ansi} or an appropriate @option{-std} option, or +@option{-ffreestanding} is used. @xref{C Dialect Options,,Options +Controlling C Dialect}. + +@item no_instrument_function +@cindex @code{no_instrument_function} function attribute +@opindex finstrument-functions +If @option{-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. + +@item section ("@var{section-name}") +@cindex @code{section} function attribute +Normally, the compiler places the code it generates in the @code{text} section. +Sometimes, however, you need additional sections, or you need certain +particular functions to appear in special sections. The @code{section} +attribute specifies that a function lives in a particular section. +For example, the declaration: + +@smallexample +extern void foobar (void) __attribute__ ((section ("bar"))); +@end smallexample + +@noindent +puts the function @code{foobar} in the @code{bar} section. + +Some file formats do not support arbitrary sections so the @code{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. + +@item constructor +@itemx destructor +@cindex @code{constructor} function attribute +@cindex @code{destructor} function attribute +The @code{constructor} attribute causes the function to be called +automatically before execution enters @code{main ()}. Similarly, the +@code{destructor} attribute causes the function to be called +automatically after @code{main ()} has completed or @code{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@. + +@cindex @code{unused} attribute. +@item 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++. + +@cindex @code{used} attribute. +@item 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. + +@cindex @code{deprecated} attribute. +@item deprecated +The @code{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: + +@smallexample +int old_fn () __attribute__ ((deprecated)); +int old_fn (); +int (*fn_ptr)() = old_fn; +@end smallexample + +results in a warning on line 3 but not line 2. + +The @code{deprecated} attribute can also be used for variables and +types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) + +@item weak +@cindex @code{weak} attribute +The @code{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. + +@item malloc +@cindex @code{malloc} attribute +The @code{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. + +@item alias ("@var{target}") +@cindex @code{alias} attribute +The @code{alias} attribute causes the declaration to be emitted as an +alias for another symbol, which must be specified. For instance, + +@smallexample +void __f () @{ /* do something */; @} +void f () __attribute__ ((weak, alias ("__f"))); +@end smallexample + +declares @samp{f} to be a weak alias for @samp{__f}. In C++, the +mangled name for the target must be used. + +Not all target machines support this attribute. + +@item regparm (@var{number}) +@cindex functions that are passed arguments in registers on the 386 +On the Intel 386, the @code{regparm} attribute causes the compiler to +pass up to @var{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. + +@item stdcall +@cindex functions that pop the argument stack on the 386 +On the Intel 386, the @code{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 @code{stdcall} +attribute. + +@item cdecl +@cindex functions that do pop the argument stack on the 386 +@opindex mrtd +On the Intel 386, the @code{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 @option{-mrtd} switch. + +The PowerPC compiler for Windows NT currently ignores the @code{cdecl} +attribute. + +@item longcall +@cindex functions called via pointer on the RS/6000 and PowerPC +On the RS/6000 and PowerPC, the @code{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. + +@item long_call/short_call +@cindex indirect calls on ARM +This attribute allows to specify how to call a particular function on +ARM@. Both attributes override the @option{-mlong-calls} (@pxref{ARM Options}) +command line switch and @code{#pragma long_calls} settings. The +@code{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 @code{short_call} attribute always places +the offset to the function from the call site into the @samp{BL} +instruction directly. + +@item dllimport +@cindex functions which are imported from a dll on PowerPC Windows NT +On the PowerPC running Windows NT, the @code{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 @code{__imp_} and the function name. + +@item dllexport +@cindex functions which are exported from a dll on PowerPC Windows NT +On the PowerPC running Windows NT, the @code{dllexport} attribute causes +the compiler to provide a global pointer to the function pointer, so +that it can be called with the @code{dllimport} attribute. The pointer +name is formed by combining @code{__imp_} and the function name. + +@item exception (@var{except-func} [, @var{except-arg}]) +@cindex functions which specify exception handling on PowerPC Windows NT +On the PowerPC running Windows NT, the @code{exception} attribute causes +the compiler to modify the structured exception table entry it emits for +the declared function. The string or identifier @var{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 @var{except-arg} is placed in the fourth entry of the +structured exception table. + +@item function_vector +@cindex calling functions through the function vector on the H8/300 processors +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. + +@item interrupt +@cindex interrupt handler functions +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 @code{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: + +@smallexample +void f () __attribute__ ((interrupt ("IRQ"))); +@end smallexample + +Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@. + +@item interrupt_handler +@cindex interrupt handler functions on the H8/300 and SH processors +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. + +@item sp_switch +Use this attribute on the SH to indicate an @code{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. + +@smallexample +void *alt_stack; +void f () __attribute__ ((interrupt_handler, + sp_switch ("alt_stack"))); +@end smallexample + +@item trap_exit +Use this attribute on the SH for an @code{interrupt_handle} to return using +@code{trapa} instead of @code{rte}. This attribute expects an integer +argument specifying the trap number to be used. + +@item eightbit_data +@cindex eight bit data on the H8/300 and H8/300H +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. + +@item tiny_data +@cindex tiny data section on the H8/300H +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. + +@item signal +@cindex signal handler functions on the AVR processors +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. + +@item naked +@cindex function without a prologue/epilogue code +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. + +@item model (@var{model-name}) +@cindex function addressability on the M32R/D +Use this attribute on the M32R/D to set the addressability of an object, +and the code generated for a function. +The identifier @var{model-name} is one of @code{small}, @code{medium}, +or @code{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 @code{ld24} instruction), and are +callable with the @code{bl} instruction. + +Medium model objects may live anywhere in the 32-bit address space (the +compiler will generate @code{seth/add3} instructions to load their addresses), +and are callable with the @code{bl} instruction. + +Large model objects may live anywhere in the 32-bit address space (the +compiler will generate @code{seth/add3} instructions to load their addresses), +and may not be reachable with the @code{bl} instruction (the compiler will +generate the much slower @code{seth/add3/jl} instruction sequence). + +@end table + +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. + +@cindex @code{#pragma}, reason for not using +@cindex pragma, reason for not using +Some people object to the @code{__attribute__} feature, suggesting that +ISO C's @code{#pragma} should be used instead. At the time +@code{__attribute__} was designed, there were two reasons for not doing +this. + +@enumerate +@item +It is impossible to generate @code{#pragma} commands from a macro. + +@item +There is no telling what the same @code{#pragma} might mean in another +compiler. +@end enumerate + +These two reasons applied to almost any application that might have been +proposed for @code{#pragma}. It was basically a mistake to use +@code{#pragma} for @emph{anything}. + +The ISO C99 standard includes @code{_Pragma}, which now allows pragmas +to be generated from macros. In addition, a @code{#pragma GCC} +namespace is now in use for GCC-specific pragmas. However, it has been +found convenient to use @code{__attribute__} to achieve a natural +attachment of attributes to their corresponding declarations, whereas +@code{#pragma GCC} is of use for constructs that do not naturally form +part of the grammar. @xref{Other Directives,,Miscellaneous +Preprocessing Directives, cpp, The C Preprocessor}. + +@node Attribute Syntax +@section Attribute Syntax +@cindex attribute syntax + +This section describes the syntax with which @code{__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, @code{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. + +@xref{Function Attributes}, for details of the semantics of attributes +applying to functions. @xref{Variable Attributes}, for details of the +semantics of attributes applying to variables. @xref{Type Attributes}, +for details of the semantics of attributes applying to structure, union +and enumerated types. + +An @dfn{attribute specifier} is of the form +@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} +is a possibly empty comma-separated sequence of @dfn{attributes}, where +each attribute is one of the following: + +@itemize @bullet +@item +Empty. Empty attributes are ignored. + +@item +A word (which may be an identifier such as @code{unused}, or a reserved +word such as @code{const}). + +@item +A word, followed by, in parentheses, parameters for the attribute. +These parameters take one of the following forms: + +@itemize @bullet +@item +An identifier. For example, @code{mode} attributes use this form. + +@item +An identifier followed by a comma and a non-empty comma-separated list +of expressions. For example, @code{format} attributes use this form. + +@item +A possibly empty comma-separated list of expressions. For example, +@code{format_arg} attributes use this form with the list being a single +integer constant expression, and @code{alias} attributes use this form +with the list being a single string constant. +@end itemize +@end itemize + +An @dfn{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 @code{case} or @code{default} label. The only +attribute it makes sense to use after a label is @code{unused}. This +feature is intended for code generated by programs which contains labels +that may be unused but which is compiled with @option{-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 @code{#ifdef} conditional. + +An attribute specifier list may appear as part of a @code{struct}, +@code{union} or @code{enum} specifier. It may go either immediately +after the @code{struct}, @code{union} or @code{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 +@code{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. +@c Otherwise, there would be the following problems: a shift/reduce +@c conflict between attributes binding the struct/union/enum and +@c binding to the list of specifiers/qualifiers; and "aligned" +@c attributes could use sizeof for the structure, but the size could be +@c changed later by "packed" attributes. + +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, +@code{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 +@code{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 + +@smallexample +__attribute__((noreturn)) void d0 (void), + __attribute__((format(printf, 1, 2))) d1 (const char *, ...), + d2 (void) +@end smallexample + +@noindent +the @code{noreturn} attribute applies to all the functions +declared; the @code{format} attribute only applies to @code{d1}. + +An attribute specifier list may appear immediately before the comma, +@code{=} 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 + +@smallexample +void (****f)(void) __attribute__((noreturn)); +@end smallexample + +@noindent +at present the @code{noreturn} attribute applies to @code{f}, which +causes a warning since @code{f} is not a function, but in future it may +apply to the function @code{****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 (@pxref{Asm +Labels}), at present the attribute must follow the @code{asm} +specification; in future, attributes before the @code{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 @code{[]} 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 @code{*} 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 @code{T +D1}, where @code{T} contains declaration specifiers that specify a type +@var{Type} (such as @code{int}) and @code{D1} is a declarator that +contains an identifier @var{ident}. The type specified for @var{ident} +for derived declarators whose type does not include an attribute +specifier is as in the ISO C standard. + +If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, +and the declaration @code{T D} specifies the type +``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then +@code{T D1} specifies the type ``@var{derived-declarator-type-list} +@var{attribute-specifier-list} @var{Type}'' for @var{ident}. + +If @code{D1} has the form @code{* +@var{type-qualifier-and-attribute-specifier-list} D}, and the +declaration @code{T D} specifies the type +``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then +@code{T D1} specifies the type ``@var{derived-declarator-type-list} +@var{type-qualifier-and-attribute-specifier-list} @var{Type}'' for +@var{ident}. + +For example, + +@smallexample +void (__attribute__((noreturn)) ****f) (void); +@end smallexample + +@noindent +specifies the type ``pointer to pointer to pointer to pointer to +non-returning function returning @code{void}''. As another example, + +@smallexample +char *__attribute__((aligned(8))) *f; +@end smallexample + +@noindent +specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. +Note again that this does not work with most attributes; for example, +the usage of @samp{aligned} and @samp{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. + +@node Function Prototypes +@section Prototypes and Old-Style Function Definitions +@cindex function prototype declarations +@cindex old-style function definitions +@cindex promotion of formal parameters + +GNU C extends ISO C to allow a function prototype to override a later +old-style non-prototype definition. Consider the following example: + +@example +/* @r{Use prototypes unless the compiler is old-fashioned.} */ +#ifdef __STDC__ +#define P(x) x +#else +#define P(x) () +#endif + +/* @r{Prototype function declaration.} */ +int isroot P((uid_t)); + +/* @r{Old-style function definition.} */ +int +isroot (x) /* ??? lossage here ??? */ + uid_t x; +@{ + return x == 0; +@} +@end example + +Suppose the type @code{uid_t} happens to be @code{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 @code{int}, which does not +match the prototype argument type of @code{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 @code{uid_t} type is @code{short}, @code{int}, or +@code{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: + +@example +int isroot (uid_t); + +int +isroot (uid_t x) +@{ + return x == 0; +@} +@end example + +@noindent +GNU C++ does not support old-style function definitions, so this +extension is irrelevant. + +@node C++ Comments +@section C++ Style Comments +@cindex // +@cindex C++ comments +@cindex comments, C++ style + +In GNU C, you may use C++ style comments, which start with @samp{//} 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 +@w{@option{-ansi}}, a @option{-std} option specifying a version of ISO C +before C99, or @w{@option{-traditional}}, since they are incompatible +with traditional constructs like @code{dividend//*comment*/divisor}. + +@node Dollar Signs +@section Dollar Signs in Identifier Names +@cindex $ +@cindex dollar signs in identifier names +@cindex identifier names, dollar signs in + +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. + +@node Character Escapes +@section The Character @key{ESC} in Constants + +You can use the sequence @samp{\e} in a string or character constant to +stand for the ASCII character @key{ESC}. + +@node Alignment +@section Inquiring on Alignment of Types or Variables +@cindex alignment +@cindex type alignment +@cindex variable alignment + +The keyword @code{__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 @code{sizeof}. + +For example, if the target machine requires a @code{double} value to be +aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. +This is true on many RISC machines. On more traditional machine +designs, @code{__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, @code{__alignof__} +reports the @emph{recommended} alignment of a type. + +If the operand of @code{__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 @code{__attribute__} +extension (@pxref{Variable Attributes}). For example, after this +declaration: + +@example +struct foo @{ int x; char y; @} foo1; +@end example + +@noindent +the value of @code{__alignof__ (foo1.y)} is 1, even though its actual +alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. + +It is an error to ask for the alignment of an incomplete type. + +@node Variable Attributes +@section Specifying Attributes of Variables +@cindex attribute of variables +@cindex variable attributes + +The keyword @code{__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: @code{aligned}, +@code{mode}, @code{nocommon}, @code{packed}, @code{section}, +@code{transparent_union}, @code{unused}, @code{deprecated}, +@code{vector_size}, and @code{weak}. Some other attributes are defined +for variables on particular target systems. Other attributes are +available for functions (@pxref{Function Attributes}) and for types +(@pxref{Type Attributes}). Other front ends might define more +attributes (@pxref{C++ Extensions,,Extensions to the C++ Language}). + +You may also specify attributes with @samp{__} 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 @code{__aligned__} instead of @code{aligned}. + +@xref{Attribute Syntax}, for details of the exact syntax for using +attributes. + +@table @code +@cindex @code{aligned} attribute +@item aligned (@var{alignment}) +This attribute specifies a minimum alignment for the variable or +structure field, measured in bytes. For example, the declaration: + +@smallexample +int x __attribute__ ((aligned (16))) = 0; +@end smallexample + +@noindent +causes the compiler to allocate the global variable @code{x} on a +16-byte boundary. On a 68040, this could be used in conjunction with +an @code{asm} expression to access the @code{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 @code{int} pair, you could write: + +@smallexample +struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; +@end smallexample + +@noindent +This is an alternative to creating a union with a @code{double} member +that forces the union to be double-word aligned. + +It is not possible to specify the alignment of functions; the alignment +of functions is determined by the machine's requirements and cannot be +changed. You cannot specify alignment for a typedef name because such a +name is just an alias, not a distinct type. + +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: + +@smallexample +short array[3] __attribute__ ((aligned)); +@end smallexample + +Whenever you leave out the alignment factor in an @code{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 @code{aligned} attribute can only increase the alignment; but you +can decrease it by specifying @code{packed} as well. See below. + +Note that the effectiveness of @code{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 @code{aligned(16)} +in an @code{__attribute__} will still only provide you with 8 byte +alignment. See your linker documentation for further information. + +@item mode (@var{mode}) +@cindex @code{mode} attribute +This attribute specifies the data type for the declaration---whichever +type corresponds to the mode @var{mode}. This in effect lets you +request an integer or floating point type according to its width. + +You may also specify a mode of @samp{byte} or @samp{__byte__} to +indicate the mode corresponding to a one-byte integer, @samp{word} or +@samp{__word__} for the mode of a one-word integer, and @samp{pointer} +or @samp{__pointer__} for the mode used to represent pointers. + +@item nocommon +@cindex @code{nocommon} attribute +@opindex fno-common +This attribute specifies requests GCC not to place a variable +``common'' but instead to allocate space for it directly. If you +specify the @option{-fno-common} flag, GCC will do this for all +variables. + +Specifying the @code{nocommon} attribute for a variable provides an +initialization of zeros. A variable may only be initialized in one +source file. + +@item packed +@cindex @code{packed} attribute +The @code{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 +@code{aligned} attribute. + +Here is a structure in which the field @code{x} is packed, so that it +immediately follows @code{a}: + +@example +struct foo +@{ + char a; + int x[2] __attribute__ ((packed)); +@}; +@end example + +@item section ("@var{section-name}") +@cindex @code{section} variable attribute +Normally, the compiler places the objects it generates in sections like +@code{data} and @code{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 @code{section} +attribute specifies that a variable (or function) lives in a particular +section. For example, this small program uses several specific section names: + +@smallexample +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); +@} +@end smallexample + +@noindent +Use the @code{section} attribute with an @emph{initialized} definition +of a @emph{global} variable, as shown in the example. GCC issues +a warning and otherwise ignores the @code{section} attribute in +uninitialized variable declarations. + +You may only use the @code{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 @code{common} (or @code{bss}) section +and can be multiply ``defined''. You can force a variable to be +initialized with the @option{-fno-common} flag or the @code{nocommon} +attribute. + +Some file formats do not support arbitrary sections so the @code{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. + +@item shared +@cindex @code{shared} variable attribute +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 @code{shared} and marking the section +shareable: + +@smallexample +int foo __attribute__((section ("shared"), shared)) = 0; + +int +main() +@{ + /* Read and write foo. All running + copies see the same value. */ + return 0; +@} +@end smallexample + +@noindent +You may only use the @code{shared} attribute along with @code{section} +attribute with a fully initialized global definition because of the way +linkers work. See @code{section} attribute for more information. + +The @code{shared} attribute is only available on Windows NT@. + +@item 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 @xref{Type Attributes}. You can also use +this attribute on a @code{typedef} for a union data type; then it +applies to all function parameters with that type. + +@item 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. + +@item deprecated +The @code{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: + +@smallexample +extern int old_var __attribute__ ((deprecated)); +extern int old_var; +int new_fn () @{ return old_var; @} +@end smallexample + +results in a warning on line 3 but not line 2. + +The @code{deprecated} attribute can also be used for functions and +types (@pxref{Function Attributes}, @pxref{Type Attributes}.) + +@item vector_size (@var{bytes}) +This attribute specifies the vector size for the variable, measured in +bytes. For example, the declaration: + +@smallexample +int foo __attribute__ ((vector_size (16))); +@end smallexample + +@noindent +causes the compiler to set the mode for @code{foo}, to be 16 bytes, +divided into @code{int} sized units. Assuming a 32-bit int (a vector of +4 units of 4 bytes), the corresponding mode of @code{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: + +@smallexample +struct S @{ int a; @}; +struct S __attribute__ ((vector_size (16))) foo; +@end smallexample + +@noindent +is invalid even if the size of the structure is the same as the size of +the @code{int}. + +@item weak +The @code{weak} attribute is described in @xref{Function Attributes}. + +@item model (@var{model-name}) +@cindex variable addressability on the M32R/D +Use this attribute on the M32R/D to set the addressability of an object. +The identifier @var{model-name} is one of @code{small}, @code{medium}, +or @code{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 @code{ld24} instruction). + +Medium and large model objects may live anywhere in the 32-bit address space +(the compiler will generate @code{seth/add3} instructions to load their +addresses). + +@end table + +To specify multiple attributes, separate them by commas within the +double parentheses: for example, @samp{__attribute__ ((aligned (16), +packed))}. + +@node Type Attributes +@section Specifying Attributes of Types +@cindex attribute of types +@cindex type attributes + +The keyword @code{__attribute__} allows you to specify special +attributes of @code{struct} and @code{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: +@code{aligned}, @code{packed}, @code{transparent_union}, @code{unused}, +and @code{deprecated}. Other attributes are defined for functions +(@pxref{Function Attributes}) and for variables (@pxref{Variable Attributes}). + +You may also specify any one of these attributes with @samp{__} +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 @code{__aligned__} +instead of @code{aligned}. + +You may specify the @code{aligned} and @code{transparent_union} +attributes either in a @code{typedef} declaration or just past the +closing curly brace of a complete enum, struct or union type +@emph{definition} and the @code{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. + +@xref{Attribute Syntax}, for details of the exact syntax for using +attributes. + +@table @code +@cindex @code{aligned} attribute +@item aligned (@var{alignment}) +This attribute specifies a minimum alignment (in bytes) for variables +of the specified type. For example, the declarations: + +@smallexample +struct S @{ short f[3]; @} __attribute__ ((aligned (8))); +typedef int more_aligned_int __attribute__ ((aligned (8))); +@end smallexample + +@noindent +force the compiler to insure (as far as it can) that each variable whose +type is @code{struct S} or @code{more_aligned_int} will be allocated and +aligned @emph{at least} on a 8-byte boundary. On a Sparc, having all +variables of type @code{struct S} aligned to 8-byte boundaries allows +the compiler to use the @code{ldd} and @code{std} (doubleword load and +store) instructions when copying one variable of type @code{struct S} to +another, thus improving run-time efficiency. + +Note that the alignment of any given @code{struct} or @code{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 @code{struct} or @code{union} in question. This means that you @emph{can} +effectively adjust the alignment of a @code{struct} or @code{union} +type by attaching an @code{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 @code{struct} or @code{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 @code{struct} +or @code{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: + +@smallexample +struct S @{ short f[3]; @} __attribute__ ((aligned)); +@end smallexample + +Whenever you leave out the alignment factor in an @code{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 @code{short} is 2 bytes, then +the size of the entire @code{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 @code{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 @code{aligned} attribute can only increase the alignment; but you +can decrease it by specifying @code{packed} as well. See below. + +Note that the effectiveness of @code{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 @code{aligned(16)} +in an @code{__attribute__} will still only provide you with 8 byte +alignment. See your linker documentation for further information. + +@item packed +This attribute, attached to an @code{enum}, @code{struct}, or +@code{union} type definition, specified that the minimum required memory +be used to represent the type. + +@opindex fshort-enums +Specifying this attribute for @code{struct} and @code{union} types is +equivalent to specifying the @code{packed} attribute on each of the +structure or union members. Specifying the @option{-fshort-enums} +flag on the line is equivalent to specifying the @code{packed} +attribute on all @code{enum} definitions. + +You may only specify this attribute after a closing curly brace on an +@code{enum} definition, not in a @code{typedef} declaration, unless that +declaration also contains the definition of the @code{enum}. + +@item transparent_union +This attribute, attached to a @code{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 @code{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 +@code{wait} function must accept either a value of type @code{int *} to +comply with Posix, or a value of type @code{union wait *} to comply with +the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, +@code{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, @code{<sys/wait.h>} might define the interface +as follows: + +@smallexample +typedef union + @{ + int *__ip; + union wait *__up; + @} wait_status_ptr_t __attribute__ ((__transparent_union__)); + +pid_t wait (wait_status_ptr_t); +@end smallexample + +This interface allows either @code{int *} or @code{union wait *} +arguments to be passed, using the @code{int *} calling convention. +The program can call @code{wait} with arguments of either type: + +@example +int w1 () @{ int w; return wait (&w); @} +int w2 () @{ union wait w; return wait (&w); @} +@end example + +With this interface, @code{wait}'s implementation might look like this: + +@example +pid_t wait (wait_status_ptr_t p) +@{ + return waitpid (-1, p.__ip, 0); +@} +@end example + +@item unused +When attached to a type (including a @code{union} or a @code{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. + +@item deprecated +The @code{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. + +@smallexample +typedef int T1 __attribute__ ((deprecated)); +T1 x; +typedef T1 T2; +T2 y; +typedef T1 T3 __attribute__ ((deprecated)); +T3 z __attribute__ ((deprecated)); +@end smallexample + +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 @code{deprecated} attribute can also be used for functions and +variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) + +@end table + +To specify multiple attributes, separate them by commas within the +double parentheses: for example, @samp{__attribute__ ((aligned (16), +packed))}. + +@node Inline +@section An Inline Function is As Fast As a Macro +@cindex inline functions +@cindex integrating function code +@cindex open coding +@cindex macros, inline alternative + +By declaring a function @code{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 @option{-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 @code{inline} keyword in its +declaration, like this: + +@example +inline int +inc (int *a) +@{ + (*a)++; +@} +@end example + +(If you are writing a header file to be included in ISO C programs, write +@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.) +You can also make all ``simple enough'' functions inline with the option +@option{-finline-functions}. + +@opindex Winline +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 (@pxref{Variable Length}), +use of computed goto (@pxref{Labels as Values}), use of nonlocal goto, +and nested functions (@pxref{Nested Functions}). Using @option{-Winline} +will warn when a function marked @code{inline} could not be substituted, +and will give the reason for the failure. + +Note that in C and Objective-C, unlike C++, the @code{inline} keyword +does not affect the linkage of the function. + +@cindex automatic @code{inline} for C++ member fns +@cindex @code{inline} automatic for C++ member fns +@cindex member fns, automatically @code{inline} +@cindex C++ member fns, automatically @code{inline} +@opindex fno-default-inline +GCC automatically inlines member functions defined within the class +body of C++ programs even if they are not explicitly declared +@code{inline}. (You can override this with @option{-fno-default-inline}; +@pxref{C++ Dialect Options,,Options Controlling C++ Dialect}.) + +@cindex inline functions, omission of +@opindex fkeep-inline-functions +When a function is both inline and @code{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 @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. + +@cindex non-static inline function +When an inline function is not @code{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-@code{static} inline function is always compiled on its +own in the usual fashion. + +If you specify both @code{inline} and @code{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 @code{inline} and @code{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 @code{inline} and @code{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 @code{static inline} only. (The +existing semantics will remain available when @option{-std=gnu89} is +specified, but eventually the default will be @option{-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. It is not +clear whether it is better to inline or not, in this case, but we found +that a correct implementation when not optimizing was difficult. So we +did the easy thing, and turned it off. + +@node Extended Asm +@section Assembler Instructions with C Expression Operands +@cindex extended @code{asm} +@cindex @code{asm} expressions +@cindex assembler instructions +@cindex registers + +In an assembler instruction using @code{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 @code{fsinx} instruction: + +@example +asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); +@end example + +@noindent +Here @code{angle} is the C expression for the input operand while +@code{result} is that of the output operand. Each has @samp{"f"} as its +operand constraint, saying that a floating point register is required. +The @samp{=} in @samp{=f} indicates that the operand is an output; all +output operands' constraints must use @samp{=}. The constraints use the +same language used in the machine description (@pxref{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 @code{%[@var{name}]} instead of a percentage sign +followed by the operand number. Using named operands the above example +could look like: + +@example +asm ("fsinx %[angle],%[output]" + : [output] "=f" (result) + : [angle] "f" (angle)); +@end example + +@noindent +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 @code{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 @code{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 @samp{+} 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) @samp{combine} instruction with +@code{bar} as its read-only source operand and @code{foo} as its +read-write destination: + +@example +asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); +@end example + +@noindent +The constraint @samp{"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 @code{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: + +@example +asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); +@end example + +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 @code{foo} in one register and +use it for operand 1, but generate the output operand 0 in a different +register (copying it afterward to @code{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 @code{[@var{name}]} instead of +the operand number for a matching constraint. For example: + +@example +asm ("cmoveq %1,%2,%[result]" + : [result] "=r"(result) + : "r" (test), "r"(new), "[result]"(old)); +@end example + +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: + +@example +asm volatile ("movc3 %0,%1,%2" + : /* no outputs */ + : "g" (from), "g" (to), "g" (count) + : "r0", "r1", "r2", "r3", "r4", "r5"); +@end example + +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 +@code{volatile} for the @code{asm} construct, as described below, to +prevent GCC from deleting the @code{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 @samp{%}; to produce one @samp{%} in the +assembler code, you must write @samp{%%} in the input. + +If your assembler instruction can alter the condition code register, add +@samp{cc} to the list of clobbered registers. GCC on some machines +represents the condition codes as a specific hardware register; +@samp{cc} serves to name this register. On other machines, the +condition code is handled differently, and specifying @samp{cc} has no +effect. But it is valid no matter what the machine. + +If your assembler instruction modifies memory in an unpredictable +fashion, add @samp{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 +@code{volatile} keyword if the memory affected is not listed in the +inputs or outputs of the @code{asm}, as the @samp{memory} clobber does +not count as a side-effect of the @code{asm}. + +You can put multiple assembler instructions together in a single +@code{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 @samp{\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 @code{_foo} accepts arguments in registers 9 and 10: + +@example +asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo" + : /* no outputs */ + : "g" (from), "g" (to) + : "r9", "r10"); +@end example + +Unless an output operand has the @samp{&} 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 @samp{&} for each output +operand that may not overlap an input. @xref{Modifiers}. + +If you want to test the condition code produced by an assembler +instruction, you must include a branch and a label in the @code{asm} +construct, as follows: + +@example +asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:" + : "g" (result) + : "g" (input)); +@end example + +@noindent +This assumes your assembler supports local labels, as the GNU assembler +and most Unix assemblers do. + +Speaking of labels, jumps from one @code{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. + +@cindex macros containing @code{asm} +Usually the most convenient way to use these @code{asm} instructions is to +encapsulate them in macros that look like functions. For example, + +@example +#define sin(x) \ +(@{ double __value, __arg = (x); \ + asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ + __value; @}) +@end example + +@noindent +Here the variable @code{__arg} is used to make sure that the instruction +operates on a proper @code{double} value, and to accept only those +arguments @code{x} which can convert automatically to a @code{double}. + +Another way to make sure the instruction operates on the correct data +type is to use a cast in the @code{asm}. This is different from using a +variable @code{__arg} in that it converts more different types. For +example, if the desired type were @code{int}, casting the argument to +@code{int} would accept a pointer with no complaint, while assigning the +argument to an @code{int} variable named @code{__arg} would warn about +using a pointer unless the caller explicitly casts it. + +If an @code{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 @code{asm} instruction from being deleted, moved +significantly, or combined, by writing the keyword @code{volatile} after +the @code{asm}. For example: + +@example +#define get_and_set_priority(new) \ +(@{ int __old; \ + asm volatile ("get_and_set_priority %0, %1" \ + : "=g" (__old) : "g" (new)); \ + __old; @}) +@end example + +@noindent +If you write an @code{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 @code{volatile} keyword indicates that the instruction has +important side-effects. GCC will not delete a volatile @code{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 @code{asm} instruction. For example: + +@example +*(volatile int *)addr = foo; +asm volatile ("eieio" : : ); +@end example + +@noindent +Assume @code{addr} contains the address of a memory mapped device +register. The PowerPC @code{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 @code{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 @code{asm} +instructions to remain perfectly consecutive. If you want consecutive +output, use a single @code{asm}. Also, GCC will perform some +optimizations across a volatile @code{asm} instruction; GCC does not +``forget everything'' when it encounters a volatile @code{asm} +instruction the way some other compilers do. + +An @code{asm} instruction without any operands or clobbers (an ``old +style'' @code{asm}) will be treated identically to a volatile +@code{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 @code{__asm__} instead of @code{asm}. @xref{Alternate +Keywords}. + +@subsection 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: + +@enumerate +@item +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. + +@item +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: + +@example +asm ("foo" : "=t" (a) : "f" (b)); +@end example + +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 @code{f} constraint, all output reg +constraints must use the @code{&} earlyclobber. + +The asm above would be written as + +@example +asm ("foo" : "=&t" (a) : "f" (b)); +@end example + +@item +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. @code{=f} is not allowed: the operand +constraints must select a class with a single reg. + +@item +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. + +@item +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. + +@end enumerate + +Here are a couple of reasonable asms to want to write. This asm +takes one input, which is internally popped, and produces two outputs. + +@example +asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); +@end example + +This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode, +and replaces them with one output. The user must code the @code{st(1)} +clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs. + +@example +asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); +@end example + +@include md.texi + +@node Asm Labels +@section Controlling Names Used in Assembler Code +@cindex assembler names for identifiers +@cindex names used in assembler code +@cindex identifiers, names in assembler code + +You can specify the name to be used in the assembler code for a C +function or variable by writing the @code{asm} (or @code{__asm__}) +keyword after the declarator as follows: + +@example +int foo asm ("myfoo") = 2; +@end example + +@noindent +This specifies that the name to be used for the variable @code{foo} in +the assembler code should be @samp{myfoo} rather than the usual +@samp{_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 @ref{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 @code{asm} in this way in a function @emph{definition}; but +you can get the same effect by writing a declaration for the function +before its definition and putting @code{asm} there, like this: + +@example +extern func () asm ("FUNC"); + +func (x, y) + int x, y; +@dots{} +@end example + +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. + +@node Explicit Reg Vars +@section Variables in Specified Registers +@cindex explicit register variables +@cindex variables in specified registers +@cindex specified registers +@cindex registers, global allocation + +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. + +@itemize @bullet +@item +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. + +@item +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 +@code{asm} feature (@pxref{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 @code{asm}.) +@end itemize + +@menu +* Global Reg Vars:: +* Local Reg Vars:: +@end menu + +@node Global Reg Vars +@subsection Defining Global Register Variables +@cindex global register variables +@cindex registers, global variables in + +You can define a global register variable in GNU C like this: + +@example +register int *foo asm ("a5"); +@end example + +@noindent +Here @code{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 +@code{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 @code{%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). + +@cindex @code{qsort}, and global register variables +It is not safe for one function that uses a global register variable to +call another such function @code{foo} by way of a third function +@code{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 @code{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 @code{qsort}, since @code{qsort} +might have put something else in that register. (If you are prepared to +recompile @code{qsort} with the same global register variable, you can +solve this problem.) + +If you want to recompile @code{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 @option{-ffixed-@var{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. + +@cindex register variable after @code{longjmp} +@cindex global register after @code{longjmp} +@cindex value after @code{longjmp} +@findex longjmp +@findex setjmp +On most machines, @code{longjmp} will restore to each global register +variable the value it had at the time of the @code{setjmp}. On some +machines, however, @code{longjmp} will not change the value of global +register variables. To be portable, the function that called @code{setjmp} +should make other arrangements to save the values of the global register +variables, and to restore them in a @code{longjmp}. This way, the same +thing will happen regardless of what @code{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 @dots{} g7 are suitable +registers, but certain library functions, such as @code{getwd}, as well +as the subroutines for division and remainder, modify g3 and g4. g1 and +g2 are local temporaries. + +On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7. +Of course, it will not do to use more than a few of those. + +@node Local Reg Vars +@subsection Specifying Registers for Local Variables +@cindex local variables, specifying registers +@cindex specifying registers for local variables +@cindex registers for local variables + +You can define a local register variable with a specified register +like this: + +@example +register int *foo asm ("a5"); +@end example + +@noindent +Here @code{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 (@pxref{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 @code{%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 @code{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. + +@node Alternate Keywords +@section Alternate Keywords +@cindex alternate keywords +@cindex keywords, alternate + +The option @option{-traditional} disables certain keywords; +@option{-ansi} and the various @option{-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 @code{asm}, @code{typeof} and @code{inline} cannot be used +since they won't work in a program compiled with @option{-ansi} +(although @code{inline} can be used in a program compiled with +@option{-std=c99}), while the keywords @code{const}, @code{volatile}, +@code{signed}, @code{typeof} and @code{inline} won't work in a program +compiled with @option{-traditional}. The ISO C99 keyword +@code{restrict} is only available when @option{-std=gnu99} (which will +eventually be the default) or @option{-std=c99} (or the equivalent +@option{-std=iso9899:1999}) is used. + +The way to solve these problems is to put @samp{__} at the beginning and +end of each problematical keyword. For example, use @code{__asm__} +instead of @code{asm}, @code{__const__} instead of @code{const}, and +@code{__inline__} instead of @code{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: + +@example +#ifndef __GNUC__ +#define __asm__ asm +#endif +@end example + +@findex __extension__ +@opindex pedantic +@option{-pedantic} and other options cause warnings for many GNU C extensions. +You can +prevent such warnings within one expression by writing +@code{__extension__} before the expression. @code{__extension__} has no +effect aside from this. + +@node Incomplete Enums +@section Incomplete @code{enum} Types + +You can define an @code{enum} tag without specifying its possible values. +This results in an incomplete type, much like what you get if you write +@code{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 +@code{enum} more consistent with the way @code{struct} and @code{union} +are handled. + +This extension is not supported by GNU C++. + +@node Function Names +@section Function Names as Strings +@cindex @code{__FUNCTION__} identifier +@cindex @code{__PRETTY_FUNCTION__} identifier +@cindex @code{__func__} identifier + +GCC predefines two magic identifiers to hold the name of the current +function. The identifier @code{__FUNCTION__} holds the name of the function +as it appears in the source. The identifier @code{__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: + +@smallexample +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; +@} +@end smallexample + +@noindent +gives this output: + +@smallexample +__FUNCTION__ = sub +__PRETTY_FUNCTION__ = int a::sub (int) +@end smallexample + +The compiler automagically replaces the identifiers with a string +literal containing the appropriate name. Thus, they are neither +preprocessor macros, like @code{__FILE__} and @code{__LINE__}, nor +variables. This means that they catenate with other string literals, and +that they can be used to initialize char arrays. For example + +@smallexample +char here[] = "Function " __FUNCTION__ " in " __FILE__; +@end smallexample + +On the other hand, @samp{#ifdef __FUNCTION__} does not have any special +meaning inside a function, since the preprocessor does not do anything +special with the identifier @code{__FUNCTION__}. + +Note that these semantics are deprecated, and that GCC 3.2 will handle +@code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} the same way as +@code{__func__}. @code{__func__} is defined by the ISO standard C99: + +@display +The identifier @code{__func__} is implicitly declared by the translator +as if, immediately following the opening brace of each function +definition, the declaration + +@smallexample +static const char __func__[] = "function-name"; +@end smallexample + +appeared, where function-name is the name of the lexically-enclosing +function. This name is the unadorned name of the function. +@end display + +By this definition, @code{__func__} is a variable, not a string literal. +In particular, @code{__func__} does not catenate with other string +literals. + +In @code{C++}, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} are +variables, declared in the same way as @code{__func__}. + +@node Return Address +@section Getting the Return or Frame Address of a Function + +These functions may be used to get information about the callers of a +function. + +@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) +This function returns the return address of the current function, or of +one of its callers. The @var{level} argument is number of frames to +scan up the call stack. A value of @code{0} yields the return address +of the current function, a value of @code{1} yields the return address +of the caller of the current function, and so forth. + +The @var{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 @code{0} or a +random value. In addition, @code{__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. +@end deftypefn + +@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) +This function is similar to @code{__builtin_return_address}, but it +returns the address of the function frame rather than the return address +of the function. Calling @code{__builtin_frame_address} with a value of +@code{0} yields the frame address of the current function, a value of +@code{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 @code{__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 @code{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. +@end deftypefn + +@node Vector Extensions +@section 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 @code{typedef}: + +@example +typedef int v4si __attribute__ ((mode(V4SI))); +@end example + +The base type @code{int} is effectively ignored by the compiler, the +actual properties of the new type @code{v4si} are defined by the +@code{__attribute__}. It defines the machine mode to be used; for vector +types these have the form @code{V@var{n}@var{B}}; @var{n} should be the +number of elements in the vector, and @var{B} should be the base mode of the +individual elements. The following can be used as base modes: + +@table @code +@item QI +An integer that is as wide as the smallest addressable unit, usually 8 bits. +@item HI +An integer, twice as wide as a QI mode integer, usually 16 bits. +@item SI +An integer, four times as wide as a QI mode integer, usually 32 bits. +@item DI +An integer, eight times as wide as a QI mode integer, usually 64 bits. +@item SF +A floating point value, as wide as a SI mode integer, usually 32 bits. +@item DF +A floating point value, as wide as a DI mode integer, usually 64 bits. +@end table + +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 @code{V8QI}, @code{V4HI} and @code{V2SI} are allowed modes. + +There are no @code{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 @emph{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: + +@example +v4si f (v4si a, v4si b, v4si c) +@{ + v4si tmp = __builtin_addv4si (a, b); + return __builtin_mulv4si (tmp, c); +@} + +@end example + +@node Other Builtins +@section Other built-in functions provided by GCC +@cindex built-in functions +@findex __builtin_isgreater +@findex __builtin_isgreaterequal +@findex __builtin_isless +@findex __builtin_islessequal +@findex __builtin_islessgreater +@findex __builtin_isunordered +@findex abort +@findex abs +@findex alloca +@findex bcmp +@findex bzero +@findex cimag +@findex cimagf +@findex cimagl +@findex conj +@findex conjf +@findex conjl +@findex cos +@findex cosf +@findex cosl +@findex creal +@findex crealf +@findex creall +@findex exit +@findex _exit +@findex _Exit +@findex fabs +@findex fabsf +@findex fabsl +@findex ffs +@findex fprintf +@findex fprintf_unlocked +@findex fputs +@findex fputs_unlocked +@findex imaxabs +@findex index +@findex labs +@findex llabs +@findex memcmp +@findex memcpy +@findex memset +@findex printf +@findex printf_unlocked +@findex rindex +@findex sin +@findex sinf +@findex sinl +@findex sqrt +@findex sqrtf +@findex sqrtl +@findex strcat +@findex strchr +@findex strcmp +@findex strcpy +@findex strcspn +@findex strlen +@findex strncat +@findex strncmp +@findex strncpy +@findex strpbrk +@findex strrchr +@findex strspn +@findex strstr + +GCC provides a large number of built-in functions other than the ones +mentioned above. Some of these are for internal use in the processing +of exceptions or variable-length argument lists and will not be +documented here because they may change from time to time; we do not +recommend general use of these functions. + +The remaining functions are provided for optimization purposes. + +@opindex fno-builtin +GCC includes built-in versions of many of the functions in the standard +C library. The versions prefixed with @code{__builtin_} will always be +treated as having the same meaning as the C library function even if you +specify the @option{-fno-builtin} option. (@pxref{C Dialect Options}) +Many of these functions are only optimized in certain cases; if they are +not optimized in a particular case, a call to the library function will +be emitted. + +@opindex ansi +@opindex std +The functions @code{abort}, @code{exit}, @code{_Exit} and @code{_exit} +are recognized and presumed not to return, but otherwise are not built +in. @code{_exit} is not recognized in strict ISO C mode (@option{-ansi}, +@option{-std=c89} or @option{-std=c99}). @code{_Exit} is not recognized in +strict C89 mode (@option{-ansi} or @option{-std=c89}). + +Outside strict ISO C mode, the functions @code{alloca}, @code{bcmp}, +@code{bzero}, @code{index}, @code{rindex}, @code{ffs}, @code{fputs_unlocked}, +@code{printf_unlocked} and @code{fprintf_unlocked} may be handled as +built-in functions. All these functions have corresponding versions +prefixed with @code{__builtin_}, which may be used even in strict C89 +mode. + +The ISO C99 functions @code{conj}, @code{conjf}, @code{conjl}, +@code{creal}, @code{crealf}, @code{creall}, @code{cimag}, @code{cimagf}, +@code{cimagl}, @code{llabs} and @code{imaxabs} are handled as built-in +functions except in strict ISO C89 mode. There are also built-in +versions of the ISO C99 functions @code{cosf}, @code{cosl}, +@code{fabsf}, @code{fabsl}, @code{sinf}, @code{sinl}, @code{sqrtf}, and +@code{sqrtl}, that are recognized in any mode since ISO C89 reserves +these names for the purpose to which ISO C99 puts them. All these +functions have corresponding versions prefixed with @code{__builtin_}. + +The ISO C89 functions @code{abs}, @code{cos}, @code{fabs}, +@code{fprintf}, @code{fputs}, @code{labs}, @code{memcmp}, @code{memcpy}, +@code{memset}, @code{printf}, @code{sin}, @code{sqrt}, @code{strcat}, +@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, +@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, +@code{strpbrk}, @code{strrchr}, @code{strspn}, and @code{strstr} are all +recognized as built-in functions unless @option{-fno-builtin} is +specified (or @option{-fno-builtin-@var{function}} is specified for an +individual function). All of these functions have corresponding +versions prefixed with @code{__builtin_}. + +GCC provides built-in versions of the ISO C99 floating point comparison +macros that avoid raising exceptions for unordered operands. They have +the same names as the standard macros ( @code{isgreater}, +@code{isgreaterequal}, @code{isless}, @code{islessequal}, +@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} +prefixed. We intend for a library implementor to be able to simply +@code{#define} each standard macro to its built-in equivalent. + +@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) + +You can use the built-in function @code{__builtin_types_compatible_p} to +determine whether two types are the same. + +This built-in function returns 1 if the unqualified versions of the +types @var{type1} and @var{type2} (which are types, not expressions) are +compatible, 0 otherwise. The result of this built-in function can be +used in integer constant expressions. + +This built-in function ignores top level qualifiers (e.g., @code{const}, +@code{volatile}). For example, @code{int} is equivalent to @code{const +int}. + +The type @code{int[]} and @code{int[5]} are compatible. On the other +hand, @code{int} and @code{char *} are not compatible, even if the size +of their types, on the particular architecture are the same. Also, the +amount of pointer indirection is taken into account when determining +similarity. Consequently, @code{short *} is not similar to +@code{short **}. Furthermore, two types that are typedefed are +considered compatible if their underlying types are compatible. + +An @code{enum} type is considered to be compatible with another +@code{enum} type. For example, @code{enum @{foo, bar@}} is similar to +@code{enum @{hot, dog@}}. + +You would typically use this function in code whose execution varies +depending on the arguments' types. For example: + +@smallexample +#define foo(x) \ + (@{ \ + typeof (x) tmp; \ + if (__builtin_types_compatible_p (typeof (x), long double)) \ + tmp = foo_long_double (tmp); \ + else if (__builtin_types_compatible_p (typeof (x), double)) \ + tmp = foo_double (tmp); \ + else if (__builtin_types_compatible_p (typeof (x), float)) \ + tmp = foo_float (tmp); \ + else \ + abort (); \ + tmp; \ + @}) +@end smallexample + +@emph{Note:} This construct is only available for C. + +@end deftypefn + +@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) + +You can use the built-in function @code{__builtin_choose_expr} to +evaluate code depending on the value of a constant expression. This +built-in function returns @var{exp1} if @var{const_exp}, which is a +constant expression that must be able to be determined at compile time, +is nonzero. Otherwise it returns 0. + +This built-in function is analogous to the @samp{? :} operator in C, +except that the expression returned has its type unaltered by promotion +rules. Also, the built-in function does not evaluate the expression +that was not chosen. For example, if @var{const_exp} evaluates to true, +@var{exp2} is not evaluated even if it has side-effects. + +This built-in function can return an lvalue if the chosen argument is an +lvalue. + +If @var{exp1} is returned, the return type is the same as @var{exp1}'s +type. Similarly, if @var{exp2} is returned, its return type is the same +as @var{exp2}. + +Example: + +@smallexample +#define foo(x) \ + __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), double), \ + foo_double (x), \ + __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), float), \ + foo_float (x), \ + /* @r{The void expression results in a compile-time error} \ + @r{when assigning the result to something.} */ \ + (void)0)) +@end smallexample + +@emph{Note:} This construct is only available for C. Furthermore, the +unused expression (@var{exp1} or @var{exp2} depending on the value of +@var{const_exp}) may still generate syntax errors. This may change in +future revisions. + +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) +You can use the built-in function @code{__builtin_constant_p} to +determine if a value is known to be constant at compile-time and hence +that GCC can perform constant-folding on expressions involving that +value. The argument of the function is the value to test. The function +returns the integer 1 if the argument is known to be a compile-time +constant and 0 if it is not known to be a compile-time constant. A +return of 0 does not indicate that the value is @emph{not} a constant, +but merely that GCC cannot prove it is a constant with the specified +value of the @option{-O} option. + +You would typically use this function in an embedded application where +memory was a critical resource. If you have some complex calculation, +you may want it to be folded if it involves constants, but need to call +a function if it does not. For example: + +@smallexample +#define Scale_Value(X) \ + (__builtin_constant_p (X) \ + ? ((X) * SCALE + OFFSET) : Scale (X)) +@end smallexample + +You may use this built-in function in either a macro or an inline +function. However, if you use it in an inlined function and pass an +argument of the function as the argument to the built-in, GCC will +never return 1 when you call the inline function with a string constant +or compound literal (@pxref{Compound Literals}) and will not return 1 +when you pass a constant numeric value to the inline function unless you +specify the @option{-O} option. + +You may also use @code{__builtin_constant_p} in initializers for static +data. For instance, you can write + +@smallexample +static const int table[] = @{ + __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, + /* ... */ +@}; +@end smallexample + +@noindent +This is an acceptable initializer even if @var{EXPRESSION} is not a +constant expression. GCC must be more conservative about evaluating the +built-in in this case, because it has no opportunity to perform +optimization. + +Previous versions of GCC did not accept this built-in in data +initializers. The earliest version where it is completely safe is +3.0.1. +@end deftypefn + +@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) +@opindex fprofile-arcs +You may use @code{__builtin_expect} to provide the compiler with +branch prediction information. In general, you should prefer to +use actual profile feedback for this (@option{-fprofile-arcs}), as +programmers are notoriously bad at predicting how their programs +actually perform. However, there are applications in which this +data is hard to collect. + +The return value is the value of @var{exp}, which should be an +integral expression. The value of @var{c} must be a compile-time +constant. The semantics of the built-in are that it is expected +that @var{exp} == @var{c}. For example: + +@smallexample +if (__builtin_expect (x, 0)) + foo (); +@end smallexample + +@noindent +would indicate that we do not expect to call @code{foo}, since +we expect @code{x} to be zero. Since you are limited to integral +expressions for @var{exp}, you should use constructions such as + +@smallexample +if (__builtin_expect (ptr != NULL, 1)) + error (); +@end smallexample + +@noindent +when testing pointer or floating-point values. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) +This function is used to minimize cache-miss latency by moving data into +a cache before it is accessed. +You can insert calls to @code{__builtin_prefetch} into code for which +you know addresses of data in memory that is likely to be accessed soon. +If the target supports them, data prefetch instructions will be generated. +If the prefetch is done early enough before the access then the data will +be in the cache by the time it is accessed. + +The value of @var{addr} is the address of the memory to prefetch. +There are two optional arguments, @var{rw} and @var{locality}. +The value of @var{rw} is a compile-time constant one or zero; one +means that the prefetch is preparing for a write to the memory address +and zero, the default, means that the prefetch is preparing for a read. +The value @var{locality} must be a compile-time constant integer between +zero and three. A value of zero means that the data has no temporal +locality, so it need not be left in the cache after the access. A value +of three means that the data has a high degree of temporal locality and +should be left in all levels of cache possible. Values of one and two +mean, respectively, a low or moderate degree of temporal locality. The +default is three. + +@smallexample +for (i = 0; i < n; i++) + @{ + a[i] = a[i] + b[i]; + __builtin_prefetch (&a[i+j], 1, 1); + __builtin_prefetch (&b[i+j], 0, 1); + /* ... */ + @} +@end smallexample + +Data prefetch does not generate faults if @var{addr} is invalid, but +the address expression itself must be valid. For example, a prefetch +of @code{p->next} will not fault if @code{p->next} is not a valid +address, but evaluation will fault if @code{p} is not a valid address. + +If the target does not support data prefetch, the address expression +is evaluated if it includes side effects but no other code is generated +and GCC does not issue a warning. +@end deftypefn + +@node Target Builtins +@section Built-in Functions Specific to Particular Target Machines + +On some target machines, GCC supports many built-in functions specific +to those machines. Generally these generate calls to specific machine +instructions, but allow the compiler to schedule those calls. + +@menu +* X86 Built-in Functions:: +* PowerPC AltiVec Built-in Functions:: +@end menu + +@node X86 Built-in Functions +@subsection X86 Built-in Functions + +These built-in functions are available for the i386 and x86-64 family +of computers, depending on the command-line switches used. + +The following machine modes are available for use with MMX built-in functions +(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, +@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a +vector of eight 8-bit integers. Some of the built-in functions operate on +MMX registers as a whole 64-bit entity, these use @code{DI} as their mode. + +If 3Dnow extensions are enabled, @code{V2SF} is used as a mode for a vector +of two 32-bit floating point values. + +If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit +floating point values. Some instructions use a vector of four 32-bit +integers, these use @code{V4SI}. Finally, some instructions operate on an +entire vector register, interpreting it as a 128-bit integer, these use mode +@code{TI}. + +The following built-in functions are made available by @option{-mmmx}. +All of them generate the machine instruction that is part of the name. + +@example +v8qi __builtin_ia32_paddb (v8qi, v8qi) +v4hi __builtin_ia32_paddw (v4hi, v4hi) +v2si __builtin_ia32_paddd (v2si, v2si) +v8qi __builtin_ia32_psubb (v8qi, v8qi) +v4hi __builtin_ia32_psubw (v4hi, v4hi) +v2si __builtin_ia32_psubd (v2si, v2si) +v8qi __builtin_ia32_paddsb (v8qi, v8qi) +v4hi __builtin_ia32_paddsw (v4hi, v4hi) +v8qi __builtin_ia32_psubsb (v8qi, v8qi) +v4hi __builtin_ia32_psubsw (v4hi, v4hi) +v8qi __builtin_ia32_paddusb (v8qi, v8qi) +v4hi __builtin_ia32_paddusw (v4hi, v4hi) +v8qi __builtin_ia32_psubusb (v8qi, v8qi) +v4hi __builtin_ia32_psubusw (v4hi, v4hi) +v4hi __builtin_ia32_pmullw (v4hi, v4hi) +v4hi __builtin_ia32_pmulhw (v4hi, v4hi) +di __builtin_ia32_pand (di, di) +di __builtin_ia32_pandn (di,di) +di __builtin_ia32_por (di, di) +di __builtin_ia32_pxor (di, di) +v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) +v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) +v2si __builtin_ia32_pcmpeqd (v2si, v2si) +v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) +v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) +v2si __builtin_ia32_pcmpgtd (v2si, v2si) +v8qi __builtin_ia32_punpckhbw (v8qi, v8qi) +v4hi __builtin_ia32_punpckhwd (v4hi, v4hi) +v2si __builtin_ia32_punpckhdq (v2si, v2si) +v8qi __builtin_ia32_punpcklbw (v8qi, v8qi) +v4hi __builtin_ia32_punpcklwd (v4hi, v4hi) +v2si __builtin_ia32_punpckldq (v2si, v2si) +v8qi __builtin_ia32_packsswb (v4hi, v4hi) +v4hi __builtin_ia32_packssdw (v2si, v2si) +v8qi __builtin_ia32_packuswb (v4hi, v4hi) +@end example + +The following built-in functions are made available either with +@option{-msse}, or with a combination of @option{-m3dnow} and +@option{-march=athlon}. All of them generate the machine +instruction that is part of the name. + +@example +v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) +v8qi __builtin_ia32_pavgb (v8qi, v8qi) +v4hi __builtin_ia32_pavgw (v4hi, v4hi) +v4hi __builtin_ia32_psadbw (v8qi, v8qi) +v8qi __builtin_ia32_pmaxub (v8qi, v8qi) +v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) +v8qi __builtin_ia32_pminub (v8qi, v8qi) +v4hi __builtin_ia32_pminsw (v4hi, v4hi) +int __builtin_ia32_pextrw (v4hi, int) +v4hi __builtin_ia32_pinsrw (v4hi, int, int) +int __builtin_ia32_pmovmskb (v8qi) +void __builtin_ia32_maskmovq (v8qi, v8qi, char *) +void __builtin_ia32_movntq (di *, di) +void __builtin_ia32_sfence (void) +@end example + +The following built-in functions are available when @option{-msse} is used. +All of them generate the machine instruction that is part of the name. + +@example +int __builtin_ia32_comieq (v4sf, v4sf) +int __builtin_ia32_comineq (v4sf, v4sf) +int __builtin_ia32_comilt (v4sf, v4sf) +int __builtin_ia32_comile (v4sf, v4sf) +int __builtin_ia32_comigt (v4sf, v4sf) +int __builtin_ia32_comige (v4sf, v4sf) +int __builtin_ia32_ucomieq (v4sf, v4sf) +int __builtin_ia32_ucomineq (v4sf, v4sf) +int __builtin_ia32_ucomilt (v4sf, v4sf) +int __builtin_ia32_ucomile (v4sf, v4sf) +int __builtin_ia32_ucomigt (v4sf, v4sf) +int __builtin_ia32_ucomige (v4sf, v4sf) +v4sf __builtin_ia32_addps (v4sf, v4sf) +v4sf __builtin_ia32_subps (v4sf, v4sf) +v4sf __builtin_ia32_mulps (v4sf, v4sf) +v4sf __builtin_ia32_divps (v4sf, v4sf) +v4sf __builtin_ia32_addss (v4sf, v4sf) +v4sf __builtin_ia32_subss (v4sf, v4sf) +v4sf __builtin_ia32_mulss (v4sf, v4sf) +v4sf __builtin_ia32_divss (v4sf, v4sf) +v4si __builtin_ia32_cmpeqps (v4sf, v4sf) +v4si __builtin_ia32_cmpltps (v4sf, v4sf) +v4si __builtin_ia32_cmpleps (v4sf, v4sf) +v4si __builtin_ia32_cmpgtps (v4sf, v4sf) +v4si __builtin_ia32_cmpgeps (v4sf, v4sf) +v4si __builtin_ia32_cmpunordps (v4sf, v4sf) +v4si __builtin_ia32_cmpneqps (v4sf, v4sf) +v4si __builtin_ia32_cmpnltps (v4sf, v4sf) +v4si __builtin_ia32_cmpnleps (v4sf, v4sf) +v4si __builtin_ia32_cmpngtps (v4sf, v4sf) +v4si __builtin_ia32_cmpngeps (v4sf, v4sf) +v4si __builtin_ia32_cmpordps (v4sf, v4sf) +v4si __builtin_ia32_cmpeqss (v4sf, v4sf) +v4si __builtin_ia32_cmpltss (v4sf, v4sf) +v4si __builtin_ia32_cmpless (v4sf, v4sf) +v4si __builtin_ia32_cmpgtss (v4sf, v4sf) +v4si __builtin_ia32_cmpgess (v4sf, v4sf) +v4si __builtin_ia32_cmpunordss (v4sf, v4sf) +v4si __builtin_ia32_cmpneqss (v4sf, v4sf) +v4si __builtin_ia32_cmpnlts (v4sf, v4sf) +v4si __builtin_ia32_cmpnless (v4sf, v4sf) +v4si __builtin_ia32_cmpngtss (v4sf, v4sf) +v4si __builtin_ia32_cmpngess (v4sf, v4sf) +v4si __builtin_ia32_cmpordss (v4sf, v4sf) +v4sf __builtin_ia32_maxps (v4sf, v4sf) +v4sf __builtin_ia32_maxss (v4sf, v4sf) +v4sf __builtin_ia32_minps (v4sf, v4sf) +v4sf __builtin_ia32_minss (v4sf, v4sf) +v4sf __builtin_ia32_andps (v4sf, v4sf) +v4sf __builtin_ia32_andnps (v4sf, v4sf) +v4sf __builtin_ia32_orps (v4sf, v4sf) +v4sf __builtin_ia32_xorps (v4sf, v4sf) +v4sf __builtin_ia32_movss (v4sf, v4sf) +v4sf __builtin_ia32_movhlps (v4sf, v4sf) +v4sf __builtin_ia32_movlhps (v4sf, v4sf) +v4sf __builtin_ia32_unpckhps (v4sf, v4sf) +v4sf __builtin_ia32_unpcklps (v4sf, v4sf) +v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) +v4sf __builtin_ia32_cvtsi2ss (v4sf, int) +v2si __builtin_ia32_cvtps2pi (v4sf) +int __builtin_ia32_cvtss2si (v4sf) +v2si __builtin_ia32_cvttps2pi (v4sf) +int __builtin_ia32_cvttss2si (v4sf) +v4sf __builtin_ia32_rcpps (v4sf) +v4sf __builtin_ia32_rsqrtps (v4sf) +v4sf __builtin_ia32_sqrtps (v4sf) +v4sf __builtin_ia32_rcpss (v4sf) +v4sf __builtin_ia32_rsqrtss (v4sf) +v4sf __builtin_ia32_sqrtss (v4sf) +v4sf __builtin_ia32_shufps (v4sf, v4sf, int) +void __builtin_ia32_movntps (float *, v4sf) +int __builtin_ia32_movmskps (v4sf) +@end example + +The following built-in functions are available when @option{-msse} is used. + +@table @code +@item v4sf __builtin_ia32_loadaps (float *) +Generates the @code{movaps} machine instruction as a load from memory. +@item void __builtin_ia32_storeaps (float *, v4sf) +Generates the @code{movaps} machine instruction as a store to memory. +@item v4sf __builtin_ia32_loadups (float *) +Generates the @code{movups} machine instruction as a load from memory. +@item void __builtin_ia32_storeups (float *, v4sf) +Generates the @code{movups} machine instruction as a store to memory. +@item v4sf __builtin_ia32_loadsss (float *) +Generates the @code{movss} machine instruction as a load from memory. +@item void __builtin_ia32_storess (float *, v4sf) +Generates the @code{movss} machine instruction as a store to memory. +@item v4sf __builtin_ia32_loadhps (v4sf, v2si *) +Generates the @code{movhps} machine instruction as a load from memory. +@item v4sf __builtin_ia32_loadlps (v4sf, v2si *) +Generates the @code{movlps} machine instruction as a load from memory +@item void __builtin_ia32_storehps (v4sf, v2si *) +Generates the @code{movhps} machine instruction as a store to memory. +@item void __builtin_ia32_storelps (v4sf, v2si *) +Generates the @code{movlps} machine instruction as a store to memory. +@end table + +The following built-in functions are available when @option{-m3dnow} is used. +All of them generate the machine instruction that is part of the name. + +@example +void __builtin_ia32_femms (void) +v8qi __builtin_ia32_pavgusb (v8qi, v8qi) +v2si __builtin_ia32_pf2id (v2sf) +v2sf __builtin_ia32_pfacc (v2sf, v2sf) +v2sf __builtin_ia32_pfadd (v2sf, v2sf) +v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) +v2si __builtin_ia32_pfcmpge (v2sf, v2sf) +v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) +v2sf __builtin_ia32_pfmax (v2sf, v2sf) +v2sf __builtin_ia32_pfmin (v2sf, v2sf) +v2sf __builtin_ia32_pfmul (v2sf, v2sf) +v2sf __builtin_ia32_pfrcp (v2sf) +v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) +v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) +v2sf __builtin_ia32_pfrsqrt (v2sf) +v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf) +v2sf __builtin_ia32_pfsub (v2sf, v2sf) +v2sf __builtin_ia32_pfsubr (v2sf, v2sf) +v2sf __builtin_ia32_pi2fd (v2si) +v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) +@end example + +The following built-in functions are available when both @option{-m3dnow} +and @option{-march=athlon} are used. All of them generate the machine +instruction that is part of the name. + +@example +v2si __builtin_ia32_pf2iw (v2sf) +v2sf __builtin_ia32_pfnacc (v2sf, v2sf) +v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) +v2sf __builtin_ia32_pi2fw (v2si) +v2sf __builtin_ia32_pswapdsf (v2sf) +v2si __builtin_ia32_pswapdsi (v2si) +@end example + +@node PowerPC AltiVec Built-in Functions +@subsection PowerPC AltiVec Built-in Functions + +These built-in functions are available for the PowerPC family +of computers, depending on the command-line switches used. + +The following machine modes are available for use with AltiVec built-in +functions (@pxref{Vector Extensions}): @code{V4SI} for a vector of four +32-bit integers, @code{V4SF} for a vector of four 32-bit floating point +numbers, @code{V8HI} for a vector of eight 16-bit integers, and +@code{V16QI} for a vector of sixteen 8-bit integers. + +The following functions are made available by including +@code{<altivec.h>} and using @option{-maltivec} and +@option{-mabi=altivec}. The functions implement the functionality +described in Motorola's AltiVec Programming Interface Manual. + +@smallexample +vector signed char vec_abs (vector signed char, vector signed char); +vector signed short vec_abs (vector signed short, vector signed short); +vector signed int vec_abs (vector signed int, vector signed int); +vector signed float vec_abs (vector signed float, vector signed float); + +vector signed char vec_abss (vector signed char, vector signed char); +vector signed short vec_abss (vector signed short, vector signed short); + +vector signed char vec_add (vector signed char, vector signed char); +vector unsigned char vec_add (vector signed char, vector unsigned char); + +vector unsigned char vec_add (vector unsigned char, vector signed char); + +vector unsigned char vec_add (vector unsigned char, vector unsigned char); +vector signed short vec_add (vector signed short, vector signed short); +vector unsigned short vec_add (vector signed short, vector unsigned short); +vector unsigned short vec_add (vector unsigned short, vector signed short); +vector unsigned short vec_add (vector unsigned short, vector unsigned short); +vector signed int vec_add (vector signed int, vector signed int); +vector unsigned int vec_add (vector signed int, vector unsigned int); +vector unsigned int vec_add (vector unsigned int, vector signed int); +vector unsigned int vec_add (vector unsigned int, vector unsigned int); +vector float vec_add (vector float, vector float); + +vector unsigned int vec_addc (vector unsigned int, vector unsigned int); + +vector unsigned char vec_adds (vector signed char, vector unsigned char); +vector unsigned char vec_adds (vector unsigned char, vector signed char); +vector unsigned char vec_adds (vector unsigned char, vector unsigned char); +vector signed char vec_adds (vector signed char, vector signed char); +vector unsigned short vec_adds (vector signed short, vector unsigned short); +vector unsigned short vec_adds (vector unsigned short, vector signed short); +vector unsigned short vec_adds (vector unsigned short, vector unsigned short); +vector signed short vec_adds (vector signed short, vector signed short); + +vector unsigned int vec_adds (vector signed int, vector unsigned int); +vector unsigned int vec_adds (vector unsigned int, vector signed int); +vector unsigned int vec_adds (vector unsigned int, vector unsigned int); + +vector signed int vec_adds (vector signed int, vector signed int); + +vector float vec_and (vector float, vector float); +vector float vec_and (vector float, vector signed int); +vector float vec_and (vector signed int, vector float); +vector signed int vec_and (vector signed int, vector signed int); +vector unsigned int vec_and (vector signed int, vector unsigned int); +vector unsigned int vec_and (vector unsigned int, vector signed int); +vector unsigned int vec_and (vector unsigned int, vector unsigned int); +vector signed short vec_and (vector signed short, vector signed short); +vector unsigned short vec_and (vector signed short, vector unsigned short); +vector unsigned short vec_and (vector unsigned short, vector signed short); +vector unsigned short vec_and (vector unsigned short, vector unsigned short); +vector signed char vec_and (vector signed char, vector signed char); +vector unsigned char vec_and (vector signed char, vector unsigned char); + +vector unsigned char vec_and (vector unsigned char, vector signed char); + +vector unsigned char vec_and (vector unsigned char, vector unsigned char); + +vector float vec_andc (vector float, vector float); +vector float vec_andc (vector float, vector signed int); +vector float vec_andc (vector signed int, vector float); +vector signed int vec_andc (vector signed int, vector signed int); +vector unsigned int vec_andc (vector signed int, vector unsigned int); +vector unsigned int vec_andc (vector unsigned int, vector signed int); +vector unsigned int vec_andc (vector unsigned int, vector unsigned int); + +vector signed short vec_andc (vector signed short, vector signed short); + +vector unsigned short vec_andc (vector signed short, vector unsigned short); +vector unsigned short vec_andc (vector unsigned short, vector signed short); +vector unsigned short vec_andc (vector unsigned short, vector unsigned short); +vector signed char vec_andc (vector signed char, vector signed char); +vector unsigned char vec_andc (vector signed char, vector unsigned char); +vector unsigned char vec_andc (vector unsigned char, vector signed char); +vector unsigned char vec_andc (vector unsigned char, vector unsigned char); + +vector unsigned char vec_avg (vector unsigned char, vector unsigned char); +vector signed char vec_avg (vector signed char, vector signed char); +vector unsigned short vec_avg (vector unsigned short, vector unsigned short); +vector signed short vec_avg (vector signed short, vector signed short); +vector unsigned int vec_avg (vector unsigned int, vector unsigned int); +vector signed int vec_avg (vector signed int, vector signed int); + +vector float vec_ceil (vector float); + +vector signed int vec_cmpb (vector float, vector float); + +vector signed char vec_cmpeq (vector signed char, vector signed char); +vector signed char vec_cmpeq (vector unsigned char, vector unsigned char); +vector signed short vec_cmpeq (vector signed short, vector signed short); +vector signed short vec_cmpeq (vector unsigned short, vector unsigned short); +vector signed int vec_cmpeq (vector signed int, vector signed int); +vector signed int vec_cmpeq (vector unsigned int, vector unsigned int); +vector signed int vec_cmpeq (vector float, vector float); + +vector signed int vec_cmpge (vector float, vector float); + +vector signed char vec_cmpgt (vector unsigned char, vector unsigned char); +vector signed char vec_cmpgt (vector signed char, vector signed char); +vector signed short vec_cmpgt (vector unsigned short, vector unsigned short); +vector signed short vec_cmpgt (vector signed short, vector signed short); +vector signed int vec_cmpgt (vector unsigned int, vector unsigned int); +vector signed int vec_cmpgt (vector signed int, vector signed int); +vector signed int vec_cmpgt (vector float, vector float); + +vector signed int vec_cmple (vector float, vector float); + +vector signed char vec_cmplt (vector unsigned char, vector unsigned char); +vector signed char vec_cmplt (vector signed char, vector signed char); +vector signed short vec_cmplt (vector unsigned short, vector unsigned short); +vector signed short vec_cmplt (vector signed short, vector signed short); +vector signed int vec_cmplt (vector unsigned int, vector unsigned int); +vector signed int vec_cmplt (vector signed int, vector signed int); +vector signed int vec_cmplt (vector float, vector float); + +vector float vec_ctf (vector unsigned int, const char); +vector float vec_ctf (vector signed int, const char); + +vector signed int vec_cts (vector float, const char); + +vector unsigned int vec_ctu (vector float, const char); + +void vec_dss (const char); + +void vec_dssall (void); + +void vec_dst (void *, int, const char); + +void vec_dstst (void *, int, const char); + +void vec_dststt (void *, int, const char); + +void vec_dstt (void *, int, const char); + +vector float vec_expte (vector float, vector float); + +vector float vec_floor (vector float, vector float); + +vector float vec_ld (int, vector float *); +vector float vec_ld (int, float *): +vector signed int vec_ld (int, int *); +vector signed int vec_ld (int, vector signed int *); +vector unsigned int vec_ld (int, vector unsigned int *); +vector unsigned int vec_ld (int, unsigned int *); +vector signed short vec_ld (int, short *, vector signed short *); +vector unsigned short vec_ld (int, unsigned short *, vector unsigned short *); +vector signed char vec_ld (int, signed char *); +vector signed char vec_ld (int, vector signed char *); +vector unsigned char vec_ld (int, unsigned char *); +vector unsigned char vec_ld (int, vector unsigned char *); + +vector signed char vec_lde (int, signed char *); +vector unsigned char vec_lde (int, unsigned char *); +vector signed short vec_lde (int, short *); +vector unsigned short vec_lde (int, unsigned short *); +vector float vec_lde (int, float *); +vector signed int vec_lde (int, int *); +vector unsigned int vec_lde (int, unsigned int *); + +void float vec_ldl (int, float *); +void float vec_ldl (int, vector float *); +void signed int vec_ldl (int, vector signed int *); +void signed int vec_ldl (int, int *); +void unsigned int vec_ldl (int, unsigned int *); +void unsigned int vec_ldl (int, vector unsigned int *); +void signed short vec_ldl (int, vector signed short *); +void signed short vec_ldl (int, short *); +void unsigned short vec_ldl (int, vector unsigned short *); +void unsigned short vec_ldl (int, unsigned short *); +void signed char vec_ldl (int, vector signed char *); +void signed char vec_ldl (int, signed char *); +void unsigned char vec_ldl (int, vector unsigned char *); +void unsigned char vec_ldl (int, unsigned char *); + +vector float vec_loge (vector float); + +vector unsigned char vec_lvsl (int, void *, int *); + +vector unsigned char vec_lvsr (int, void *, int *); + +vector float vec_madd (vector float, vector float, vector float); + +vector signed short vec_madds (vector signed short, vector signed short, vector signed short); + +vector unsigned char vec_max (vector signed char, vector unsigned char); + +vector unsigned char vec_max (vector unsigned char, vector signed char); + +vector unsigned char vec_max (vector unsigned char, vector unsigned char); +vector signed char vec_max (vector signed char, vector signed char); +vector unsigned short vec_max (vector signed short, vector unsigned short); +vector unsigned short vec_max (vector unsigned short, vector signed short); +vector unsigned short vec_max (vector unsigned short, vector unsigned short); +vector signed short vec_max (vector signed short, vector signed short); +vector unsigned int vec_max (vector signed int, vector unsigned int); +vector unsigned int vec_max (vector unsigned int, vector signed int); +vector unsigned int vec_max (vector unsigned int, vector unsigned int); +vector signed int vec_max (vector signed int, vector signed int); +vector float vec_max (vector float, vector float); + +vector signed char vec_mergeh (vector signed char, vector signed char); +vector unsigned char vec_mergeh (vector unsigned char, vector unsigned char); +vector signed short vec_mergeh (vector signed short, vector signed short); +vector unsigned short vec_mergeh (vector unsigned short, vector unsigned short); +vector float vec_mergeh (vector float, vector float); +vector signed int vec_mergeh (vector signed int, vector signed int); +vector unsigned int vec_mergeh (vector unsigned int, vector unsigned int); + +vector signed char vec_mergel (vector signed char, vector signed char); +vector unsigned char vec_mergel (vector unsigned char, vector unsigned char); +vector signed short vec_mergel (vector signed short, vector signed short); +vector unsigned short vec_mergel (vector unsigned short, vector unsigned short); +vector float vec_mergel (vector float, vector float); +vector signed int vec_mergel (vector signed int, vector signed int); +vector unsigned int vec_mergel (vector unsigned int, vector unsigned int); + +vector unsigned short vec_mfvscr (void); + +vector unsigned char vec_min (vector signed char, vector unsigned char); + +vector unsigned char vec_min (vector unsigned char, vector signed char); + +vector unsigned char vec_min (vector unsigned char, vector unsigned char); +vector signed char vec_min (vector signed char, vector signed char); +vector unsigned short vec_min (vector signed short, vector unsigned short); +vector unsigned short vec_min (vector unsigned short, vector signed short); +vector unsigned short vec_min (vector unsigned short, vector unsigned short); +vector signed short vec_min (vector signed short, vector signed short); +vector unsigned int vec_min (vector signed int, vector unsigned int); +vector unsigned int vec_min (vector unsigned int, vector signed int); +vector unsigned int vec_min (vector unsigned int, vector unsigned int); +vector signed int vec_min (vector signed int, vector signed int); +vector float vec_min (vector float, vector float); + +vector signed short vec_mladd (vector signed short, vector signed short, vector signed short); +vector signed short vec_mladd (vector signed short, vector unsigned short, vector unsigned short); +vector signed short vec_mladd (vector unsigned short, vector signed short, vector signed short); +vector unsigned short vec_mladd (vector unsigned short, vector unsigned short, vector unsigned short); + +vector signed short vec_mradds (vector signed short, vector signed short, vector signed short); + +vector unsigned int vec_msum (vector unsigned char, vector unsigned char, vector unsigned int); +vector signed int vec_msum (vector signed char, vector unsigned char, vector signed int); +vector unsigned int vec_msum (vector unsigned short, vector unsigned short, vector unsigned int); +vector signed int vec_msum (vector signed short, vector signed short, vector signed int); + +vector unsigned int vec_msums (vector unsigned short, vector unsigned short, vector unsigned int); +vector signed int vec_msums (vector signed short, vector signed short, vector signed int); + +void vec_mtvscr (vector signed int); +void vec_mtvscr (vector unsigned int); +void vec_mtvscr (vector signed short); +void vec_mtvscr (vector unsigned short); +void vec_mtvscr (vector signed char); +void vec_mtvscr (vector unsigned char); + +vector unsigned short vec_mule (vector unsigned char, vector unsigned char); +vector signed short vec_mule (vector signed char, vector signed char); +vector unsigned int vec_mule (vector unsigned short, vector unsigned short); +vector signed int vec_mule (vector signed short, vector signed short); + +vector unsigned short vec_mulo (vector unsigned char, vector unsigned char); +vector signed short vec_mulo (vector signed char, vector signed char); +vector unsigned int vec_mulo (vector unsigned short, vector unsigned short); +vector signed int vec_mulo (vector signed short, vector signed short); + +vector float vec_nmsub (vector float, vector float, vector float); + +vector float vec_nor (vector float, vector float); +vector signed int vec_nor (vector signed int, vector signed int); +vector unsigned int vec_nor (vector unsigned int, vector unsigned int); +vector signed short vec_nor (vector signed short, vector signed short); +vector unsigned short vec_nor (vector unsigned short, vector unsigned short); +vector signed char vec_nor (vector signed char, vector signed char); +vector unsigned char vec_nor (vector unsigned char, vector unsigned char); + +vector float vec_or (vector float, vector float); +vector float vec_or (vector float, vector signed int); +vector float vec_or (vector signed int, vector float); +vector signed int vec_or (vector signed int, vector signed int); +vector unsigned int vec_or (vector signed int, vector unsigned int); +vector unsigned int vec_or (vector unsigned int, vector signed int); +vector unsigned int vec_or (vector unsigned int, vector unsigned int); +vector signed short vec_or (vector signed short, vector signed short); +vector unsigned short vec_or (vector signed short, vector unsigned short); +vector unsigned short vec_or (vector unsigned short, vector signed short); +vector unsigned short vec_or (vector unsigned short, vector unsigned short); +vector signed char vec_or (vector signed char, vector signed char); +vector unsigned char vec_or (vector signed char, vector unsigned char); +vector unsigned char vec_or (vector unsigned char, vector signed char); +vector unsigned char vec_or (vector unsigned char, vector unsigned char); + +vector signed char vec_pack (vector signed short, vector signed short); +vector unsigned char vec_pack (vector unsigned short, vector unsigned short); +vector signed short vec_pack (vector signed int, vector signed int); +vector unsigned short vec_pack (vector unsigned int, vector unsigned int); + +vector signed short vec_packpx (vector unsigned int, vector unsigned int); + +vector unsigned char vec_packs (vector unsigned short, vector unsigned short); +vector signed char vec_packs (vector signed short, vector signed short); + +vector unsigned short vec_packs (vector unsigned int, vector unsigned int); +vector signed short vec_packs (vector signed int, vector signed int); + +vector unsigned char vec_packsu (vector unsigned short, vector unsigned short); +vector unsigned char vec_packsu (vector signed short, vector signed short); +vector unsigned short vec_packsu (vector unsigned int, vector unsigned int); +vector unsigned short vec_packsu (vector signed int, vector signed int); + +vector float vec_perm (vector float, vector float, vector unsigned char); +vector signed int vec_perm (vector signed int, vector signed int, vector unsigned char); +vector unsigned int vec_perm (vector unsigned int, vector unsigned int, vector unsigned char); +vector signed short vec_perm (vector signed short, vector signed short, vector unsigned char); +vector unsigned short vec_perm (vector unsigned short, vector unsigned short, vector unsigned char); +vector signed char vec_perm (vector signed char, vector signed char, vector unsigned char); +vector unsigned char vec_perm (vector unsigned char, vector unsigned char, vector unsigned char); + +vector float vec_re (vector float); + +vector signed char vec_rl (vector signed char, vector unsigned char); +vector unsigned char vec_rl (vector unsigned char, vector unsigned char); +vector signed short vec_rl (vector signed short, vector unsigned short); + +vector unsigned short vec_rl (vector unsigned short, vector unsigned short); +vector signed int vec_rl (vector signed int, vector unsigned int); +vector unsigned int vec_rl (vector unsigned int, vector unsigned int); + +vector float vec_round (vector float); + +vector float vec_rsqrte (vector float); + +vector float vec_sel (vector float, vector float, vector signed int); +vector float vec_sel (vector float, vector float, vector unsigned int); +vector signed int vec_sel (vector signed int, vector signed int, vector signed int); +vector signed int vec_sel (vector signed int, vector signed int, vector unsigned int); +vector unsigned int vec_sel (vector unsigned int, vector unsigned int, vector signed int); +vector unsigned int vec_sel (vector unsigned int, vector unsigned int, vector unsigned int); +vector signed short vec_sel (vector signed short, vector signed short, vector signed short); +vector signed short vec_sel (vector signed short, vector signed short, vector unsigned short); +vector unsigned short vec_sel (vector unsigned short, vector unsigned short, vector signed short); +vector unsigned short vec_sel (vector unsigned short, vector unsigned short, vector unsigned short); +vector signed char vec_sel (vector signed char, vector signed char, vector signed char); +vector signed char vec_sel (vector signed char, vector signed char, vector unsigned char); +vector unsigned char vec_sel (vector unsigned char, vector unsigned char, vector signed char); +vector unsigned char vec_sel (vector unsigned char, vector unsigned char, vector unsigned char); + +vector signed char vec_sl (vector signed char, vector unsigned char); +vector unsigned char vec_sl (vector unsigned char, vector unsigned char); +vector signed short vec_sl (vector signed short, vector unsigned short); + +vector unsigned short vec_sl (vector unsigned short, vector unsigned short); +vector signed int vec_sl (vector signed int, vector unsigned int); +vector unsigned int vec_sl (vector unsigned int, vector unsigned int); + +vector float vec_sld (vector float, vector float, const char); +vector signed int vec_sld (vector signed int, vector signed int, const char); +vector unsigned int vec_sld (vector unsigned int, vector unsigned int, const char); +vector signed short vec_sld (vector signed short, vector signed short, const char); +vector unsigned short vec_sld (vector unsigned short, vector unsigned short, const char); +vector signed char vec_sld (vector signed char, vector signed char, const char); +vector unsigned char vec_sld (vector unsigned char, vector unsigned char, const char); + +vector signed int vec_sll (vector signed int, vector unsigned int); +vector signed int vec_sll (vector signed int, vector unsigned short); +vector signed int vec_sll (vector signed int, vector unsigned char); +vector unsigned int vec_sll (vector unsigned int, vector unsigned int); +vector unsigned int vec_sll (vector unsigned int, vector unsigned short); +vector unsigned int vec_sll (vector unsigned int, vector unsigned char); + +vector signed short vec_sll (vector signed short, vector unsigned int); +vector signed short vec_sll (vector signed short, vector unsigned short); +vector signed short vec_sll (vector signed short, vector unsigned char); + +vector unsigned short vec_sll (vector unsigned short, vector unsigned int); +vector unsigned short vec_sll (vector unsigned short, vector unsigned short); +vector unsigned short vec_sll (vector unsigned short, vector unsigned char); +vector signed char vec_sll (vector signed char, vector unsigned int); +vector signed char vec_sll (vector signed char, vector unsigned short); +vector signed char vec_sll (vector signed char, vector unsigned char); +vector unsigned char vec_sll (vector unsigned char, vector unsigned int); +vector unsigned char vec_sll (vector unsigned char, vector unsigned short); +vector unsigned char vec_sll (vector unsigned char, vector unsigned char); + +vector float vec_slo (vector float, vector signed char); +vector float vec_slo (vector float, vector unsigned char); +vector signed int vec_slo (vector signed int, vector signed char); +vector signed int vec_slo (vector signed int, vector unsigned char); +vector unsigned int vec_slo (vector unsigned int, vector signed char); +vector unsigned int vec_slo (vector unsigned int, vector unsigned char); + +vector signed short vec_slo (vector signed short, vector signed char); +vector signed short vec_slo (vector signed short, vector unsigned char); + +vector unsigned short vec_slo (vector unsigned short, vector signed char); +vector unsigned short vec_slo (vector unsigned short, vector unsigned char); +vector signed char vec_slo (vector signed char, vector signed char); +vector signed char vec_slo (vector signed char, vector unsigned char); +vector unsigned char vec_slo (vector unsigned char, vector signed char); + +vector unsigned char vec_slo (vector unsigned char, vector unsigned char); + +vector signed char vec_splat (vector signed char, const char); +vector unsigned char vec_splat (vector unsigned char, const char); +vector signed short vec_splat (vector signed short, const char); +vector unsigned short vec_splat (vector unsigned short, const char); +vector float vec_splat (vector float, const char); +vector signed int vec_splat (vector signed int, const char); +vector unsigned int vec_splat (vector unsigned int, const char); + +vector signed char vec_splat_s8 (const char); + +vector signed short vec_splat_s16 (const char); + +vector signed int vec_splat_s32 (const char); + +vector unsigned char vec_splat_u8 (const char); + +vector unsigned short vec_splat_u16 (const char); + +vector unsigned int vec_splat_u32 (const char); + +vector signed char vec_sr (vector signed char, vector unsigned char); +vector unsigned char vec_sr (vector unsigned char, vector unsigned char); +vector signed short vec_sr (vector signed short, vector unsigned short); + +vector unsigned short vec_sr (vector unsigned short, vector unsigned short); +vector signed int vec_sr (vector signed int, vector unsigned int); +vector unsigned int vec_sr (vector unsigned int, vector unsigned int); + +vector signed char vec_sra (vector signed char, vector unsigned char); +vector unsigned char vec_sra (vector unsigned char, vector unsigned char); +vector signed short vec_sra (vector signed short, vector unsigned short); +vector unsigned short vec_sra (vector unsigned short, vector unsigned short); +vector signed int vec_sra (vector signed int, vector unsigned int); +vector unsigned int vec_sra (vector unsigned int, vector unsigned int); + +vector signed int vec_srl (vector signed int, vector unsigned int); +vector signed int vec_srl (vector signed int, vector unsigned short); +vector signed int vec_srl (vector signed int, vector unsigned char); +vector unsigned int vec_srl (vector unsigned int, vector unsigned int); +vector unsigned int vec_srl (vector unsigned int, vector unsigned short); +vector unsigned int vec_srl (vector unsigned int, vector unsigned char); + +vector signed short vec_srl (vector signed short, vector unsigned int); +vector signed short vec_srl (vector signed short, vector unsigned short); +vector signed short vec_srl (vector signed short, vector unsigned char); + +vector unsigned short vec_srl (vector unsigned short, vector unsigned int); +vector unsigned short vec_srl (vector unsigned short, vector unsigned short); +vector unsigned short vec_srl (vector unsigned short, vector unsigned char); +vector signed char vec_srl (vector signed char, vector unsigned int); +vector signed char vec_srl (vector signed char, vector unsigned short); +vector signed char vec_srl (vector signed char, vector unsigned char); +vector unsigned char vec_srl (vector unsigned char, vector unsigned int); +vector unsigned char vec_srl (vector unsigned char, vector unsigned short); +vector unsigned char vec_srl (vector unsigned char, vector unsigned char); + +vector float vec_sro (vector float, vector signed char); +vector float vec_sro (vector float, vector unsigned char); +vector signed int vec_sro (vector signed int, vector signed char); +vector signed int vec_sro (vector signed int, vector unsigned char); +vector unsigned int vec_sro (vector unsigned int, vector signed char); +vector unsigned int vec_sro (vector unsigned int, vector unsigned char); + +vector signed short vec_sro (vector signed short, vector signed char); +vector signed short vec_sro (vector signed short, vector unsigned char); + +vector unsigned short vec_sro (vector unsigned short, vector signed char); +vector unsigned short vec_sro (vector unsigned short, vector unsigned char); +vector signed char vec_sro (vector signed char, vector signed char); +vector signed char vec_sro (vector signed char, vector unsigned char); +vector unsigned char vec_sro (vector unsigned char, vector signed char); + +vector unsigned char vec_sro (vector unsigned char, vector unsigned char); + +void vec_st (vector float, int, float *); +void vec_st (vector float, int, vector float *); +void vec_st (vector signed int, int, int *); +void vec_st (vector signed int, int, unsigned int *); +void vec_st (vector unsigned int, int, unsigned int *); +void vec_st (vector unsigned int, int, vector unsigned int *); +void vec_st (vector signed short, int, short *); +void vec_st (vector signed short, int, vector unsigned short *); +void vec_st (vector signed short, int, vector signed short *); +void vec_st (vector unsigned short, int, unsigned short *); +void vec_st (vector unsigned short, int, vector unsigned short *); +void vec_st (vector signed char, int, signed char *); +void vec_st (vector signed char, int, unsigned char *); +void vec_st (vector signed char, int, vector signed char *); +void vec_st (vector unsigned char, int, unsigned char *); +void vec_st (vector unsigned char, int, vector unsigned char *); + +void vec_ste (vector signed char, int, unsigned char *); +void vec_ste (vector signed char, int, signed char *); +void vec_ste (vector unsigned char, int, unsigned char *); +void vec_ste (vector signed short, int, short *); +void vec_ste (vector signed short, int, unsigned short *); +void vec_ste (vector unsigned short, int, void *); +void vec_ste (vector signed int, int, unsigned int *); +void vec_ste (vector signed int, int, int *); +void vec_ste (vector unsigned int, int, unsigned int *); +void vec_ste (vector float, int, float *); + +void vec_stl (vector float, int, vector float *); +void vec_stl (vector float, int, float *); +void vec_stl (vector signed int, int, vector signed int *); +void vec_stl (vector signed int, int, int *); +void vec_stl (vector signed int, int, unsigned int *); +void vec_stl (vector unsigned int, int, vector unsigned int *); +void vec_stl (vector unsigned int, int, unsigned int *); +void vec_stl (vector signed short, int, short *); +void vec_stl (vector signed short, int, unsigned short *); +void vec_stl (vector signed short, int, vector signed short *); +void vec_stl (vector unsigned short, int, unsigned short *); +void vec_stl (vector unsigned short, int, vector signed short *); +void vec_stl (vector signed char, int, signed char *); +void vec_stl (vector signed char, int, unsigned char *); +void vec_stl (vector signed char, int, vector signed char *); +void vec_stl (vector unsigned char, int, unsigned char *); +void vec_stl (vector unsigned char, int, vector unsigned char *); + +vector signed char vec_sub (vector signed char, vector signed char); +vector unsigned char vec_sub (vector signed char, vector unsigned char); + +vector unsigned char vec_sub (vector unsigned char, vector signed char); + +vector unsigned char vec_sub (vector unsigned char, vector unsigned char); +vector signed short vec_sub (vector signed short, vector signed short); +vector unsigned short vec_sub (vector signed short, vector unsigned short); +vector unsigned short vec_sub (vector unsigned short, vector signed short); +vector unsigned short vec_sub (vector unsigned short, vector unsigned short); +vector signed int vec_sub (vector signed int, vector signed int); +vector unsigned int vec_sub (vector signed int, vector unsigned int); +vector unsigned int vec_sub (vector unsigned int, vector signed int); +vector unsigned int vec_sub (vector unsigned int, vector unsigned int); +vector float vec_sub (vector float, vector float); + +vector unsigned int vec_subc (vector unsigned int, vector unsigned int); + +vector unsigned char vec_subs (vector signed char, vector unsigned char); +vector unsigned char vec_subs (vector unsigned char, vector signed char); +vector unsigned char vec_subs (vector unsigned char, vector unsigned char); +vector signed char vec_subs (vector signed char, vector signed char); +vector unsigned short vec_subs (vector signed short, vector unsigned short); +vector unsigned short vec_subs (vector unsigned short, vector signed short); +vector unsigned short vec_subs (vector unsigned short, vector unsigned short); +vector signed short vec_subs (vector signed short, vector signed short); + +vector unsigned int vec_subs (vector signed int, vector unsigned int); +vector unsigned int vec_subs (vector unsigned int, vector signed int); +vector unsigned int vec_subs (vector unsigned int, vector unsigned int); + +vector signed int vec_subs (vector signed int, vector signed int); + +vector unsigned int vec_sum4s (vector unsigned char, vector unsigned int); +vector signed int vec_sum4s (vector signed char, vector signed int); +vector signed int vec_sum4s (vector signed short, vector signed int); + +vector signed int vec_sum2s (vector signed int, vector signed int); + +vector signed int vec_sums (vector signed int, vector signed int); + +vector float vec_trunc (vector float); + +vector signed short vec_unpackh (vector signed char); +vector unsigned int vec_unpackh (vector signed short); +vector signed int vec_unpackh (vector signed short); + +vector signed short vec_unpackl (vector signed char); +vector unsigned int vec_unpackl (vector signed short); +vector signed int vec_unpackl (vector signed short); + +vector float vec_xor (vector float, vector float); +vector float vec_xor (vector float, vector signed int); +vector float vec_xor (vector signed int, vector float); +vector signed int vec_xor (vector signed int, vector signed int); +vector unsigned int vec_xor (vector signed int, vector unsigned int); +vector unsigned int vec_xor (vector unsigned int, vector signed int); +vector unsigned int vec_xor (vector unsigned int, vector unsigned int); +vector signed short vec_xor (vector signed short, vector signed short); +vector unsigned short vec_xor (vector signed short, vector unsigned short); +vector unsigned short vec_xor (vector unsigned short, vector signed short); +vector unsigned short vec_xor (vector unsigned short, vector unsigned short); +vector signed char vec_xor (vector signed char, vector signed char); +vector unsigned char vec_xor (vector signed char, vector unsigned char); + +vector unsigned char vec_xor (vector unsigned char, vector signed char); + +vector unsigned char vec_xor (vector unsigned char, vector unsigned char); + +vector signed int vec_all_eq (vector signed char, vector unsigned char); + +vector signed int vec_all_eq (vector signed char, vector signed char); +vector signed int vec_all_eq (vector unsigned char, vector signed char); + +vector signed int vec_all_eq (vector unsigned char, vector unsigned char); +vector signed int vec_all_eq (vector signed short, vector unsigned short); +vector signed int vec_all_eq (vector signed short, vector signed short); + +vector signed int vec_all_eq (vector unsigned short, vector signed short); +vector signed int vec_all_eq (vector unsigned short, vector unsigned short); +vector signed int vec_all_eq (vector signed int, vector unsigned int); +vector signed int vec_all_eq (vector signed int, vector signed int); +vector signed int vec_all_eq (vector unsigned int, vector signed int); +vector signed int vec_all_eq (vector unsigned int, vector unsigned int); + +vector signed int vec_all_eq (vector float, vector float); + +vector signed int vec_all_ge (vector signed char, vector unsigned char); + +vector signed int vec_all_ge (vector unsigned char, vector signed char); + +vector signed int vec_all_ge (vector unsigned char, vector unsigned char); +vector signed int vec_all_ge (vector signed char, vector signed char); +vector signed int vec_all_ge (vector signed short, vector unsigned short); +vector signed int vec_all_ge (vector unsigned short, vector signed short); +vector signed int vec_all_ge (vector unsigned short, vector unsigned short); +vector signed int vec_all_ge (vector signed short, vector signed short); + +vector signed int vec_all_ge (vector signed int, vector unsigned int); +vector signed int vec_all_ge (vector unsigned int, vector signed int); +vector signed int vec_all_ge (vector unsigned int, vector unsigned int); + +vector signed int vec_all_ge (vector signed int, vector signed int); +vector signed int vec_all_ge (vector float, vector float); + +vector signed int vec_all_gt (vector signed char, vector unsigned char); + +vector signed int vec_all_gt (vector unsigned char, vector signed char); + +vector signed int vec_all_gt (vector unsigned char, vector unsigned char); +vector signed int vec_all_gt (vector signed char, vector signed char); +vector signed int vec_all_gt (vector signed short, vector unsigned short); +vector signed int vec_all_gt (vector unsigned short, vector signed short); +vector signed int vec_all_gt (vector unsigned short, vector unsigned short); +vector signed int vec_all_gt (vector signed short, vector signed short); + +vector signed int vec_all_gt (vector signed int, vector unsigned int); +vector signed int vec_all_gt (vector unsigned int, vector signed int); +vector signed int vec_all_gt (vector unsigned int, vector unsigned int); + +vector signed int vec_all_gt (vector signed int, vector signed int); +vector signed int vec_all_gt (vector float, vector float); + +vector signed int vec_all_in (vector float, vector float); + +vector signed int vec_all_le (vector signed char, vector unsigned char); + +vector signed int vec_all_le (vector unsigned char, vector signed char); + +vector signed int vec_all_le (vector unsigned char, vector unsigned char); +vector signed int vec_all_le (vector signed char, vector signed char); +vector signed int vec_all_le (vector signed short, vector unsigned short); +vector signed int vec_all_le (vector unsigned short, vector signed short); +vector signed int vec_all_le (vector unsigned short, vector unsigned short); +vector signed int vec_all_le (vector signed short, vector signed short); + +vector signed int vec_all_le (vector signed int, vector unsigned int); +vector signed int vec_all_le (vector unsigned int, vector signed int); +vector signed int vec_all_le (vector unsigned int, vector unsigned int); + +vector signed int vec_all_le (vector signed int, vector signed int); +vector signed int vec_all_le (vector float, vector float); + +vector signed int vec_all_lt (vector signed char, vector unsigned char); + +vector signed int vec_all_lt (vector unsigned char, vector signed char); + +vector signed int vec_all_lt (vector unsigned char, vector unsigned char); +vector signed int vec_all_lt (vector signed char, vector signed char); +vector signed int vec_all_lt (vector signed short, vector unsigned short); +vector signed int vec_all_lt (vector unsigned short, vector signed short); +vector signed int vec_all_lt (vector unsigned short, vector unsigned short); +vector signed int vec_all_lt (vector signed short, vector signed short); + +vector signed int vec_all_lt (vector signed int, vector unsigned int); +vector signed int vec_all_lt (vector unsigned int, vector signed int); +vector signed int vec_all_lt (vector unsigned int, vector unsigned int); + +vector signed int vec_all_lt (vector signed int, vector signed int); +vector signed int vec_all_lt (vector float, vector float); + +vector signed int vec_all_nan (vector float); + +vector signed int vec_all_ne (vector signed char, vector unsigned char); + +vector signed int vec_all_ne (vector signed char, vector signed char); +vector signed int vec_all_ne (vector unsigned char, vector signed char); + +vector signed int vec_all_ne (vector unsigned char, vector unsigned char); +vector signed int vec_all_ne (vector signed short, vector unsigned short); +vector signed int vec_all_ne (vector signed short, vector signed short); + +vector signed int vec_all_ne (vector unsigned short, vector signed short); +vector signed int vec_all_ne (vector unsigned short, vector unsigned short); +vector signed int vec_all_ne (vector signed int, vector unsigned int); +vector signed int vec_all_ne (vector signed int, vector signed int); +vector signed int vec_all_ne (vector unsigned int, vector signed int); +vector signed int vec_all_ne (vector unsigned int, vector unsigned int); + +vector signed int vec_all_ne (vector float, vector float); + +vector signed int vec_all_nge (vector float, vector float); + +vector signed int vec_all_ngt (vector float, vector float); + +vector signed int vec_all_nle (vector float, vector float); + +vector signed int vec_all_nlt (vector float, vector float); + +vector signed int vec_all_numeric (vector float); + +vector signed int vec_any_eq (vector signed char, vector unsigned char); + +vector signed int vec_any_eq (vector signed char, vector signed char); +vector signed int vec_any_eq (vector unsigned char, vector signed char); + +vector signed int vec_any_eq (vector unsigned char, vector unsigned char); +vector signed int vec_any_eq (vector signed short, vector unsigned short); +vector signed int vec_any_eq (vector signed short, vector signed short); + +vector signed int vec_any_eq (vector unsigned short, vector signed short); +vector signed int vec_any_eq (vector unsigned short, vector unsigned short); +vector signed int vec_any_eq (vector signed int, vector unsigned int); +vector signed int vec_any_eq (vector signed int, vector signed int); +vector signed int vec_any_eq (vector unsigned int, vector signed int); +vector signed int vec_any_eq (vector unsigned int, vector unsigned int); + +vector signed int vec_any_eq (vector float, vector float); + +vector signed int vec_any_ge (vector signed char, vector unsigned char); + +vector signed int vec_any_ge (vector unsigned char, vector signed char); + +vector signed int vec_any_ge (vector unsigned char, vector unsigned char); +vector signed int vec_any_ge (vector signed char, vector signed char); +vector signed int vec_any_ge (vector signed short, vector unsigned short); +vector signed int vec_any_ge (vector unsigned short, vector signed short); +vector signed int vec_any_ge (vector unsigned short, vector unsigned short); +vector signed int vec_any_ge (vector signed short, vector signed short); + +vector signed int vec_any_ge (vector signed int, vector unsigned int); +vector signed int vec_any_ge (vector unsigned int, vector signed int); +vector signed int vec_any_ge (vector unsigned int, vector unsigned int); + +vector signed int vec_any_ge (vector signed int, vector signed int); +vector signed int vec_any_ge (vector float, vector float); + +vector signed int vec_any_gt (vector signed char, vector unsigned char); + +vector signed int vec_any_gt (vector unsigned char, vector signed char); + +vector signed int vec_any_gt (vector unsigned char, vector unsigned char); +vector signed int vec_any_gt (vector signed char, vector signed char); +vector signed int vec_any_gt (vector signed short, vector unsigned short); +vector signed int vec_any_gt (vector unsigned short, vector signed short); +vector signed int vec_any_gt (vector unsigned short, vector unsigned short); +vector signed int vec_any_gt (vector signed short, vector signed short); + +vector signed int vec_any_gt (vector signed int, vector unsigned int); +vector signed int vec_any_gt (vector unsigned int, vector signed int); +vector signed int vec_any_gt (vector unsigned int, vector unsigned int); + +vector signed int vec_any_gt (vector signed int, vector signed int); +vector signed int vec_any_gt (vector float, vector float); + +vector signed int vec_any_le (vector signed char, vector unsigned char); + +vector signed int vec_any_le (vector unsigned char, vector signed char); + +vector signed int vec_any_le (vector unsigned char, vector unsigned char); +vector signed int vec_any_le (vector signed char, vector signed char); +vector signed int vec_any_le (vector signed short, vector unsigned short); +vector signed int vec_any_le (vector unsigned short, vector signed short); +vector signed int vec_any_le (vector unsigned short, vector unsigned short); +vector signed int vec_any_le (vector signed short, vector signed short); + +vector signed int vec_any_le (vector signed int, vector unsigned int); +vector signed int vec_any_le (vector unsigned int, vector signed int); +vector signed int vec_any_le (vector unsigned int, vector unsigned int); + +vector signed int vec_any_le (vector signed int, vector signed int); +vector signed int vec_any_le (vector float, vector float); + +vector signed int vec_any_lt (vector signed char, vector unsigned char); + +vector signed int vec_any_lt (vector unsigned char, vector signed char); + +vector signed int vec_any_lt (vector unsigned char, vector unsigned char); +vector signed int vec_any_lt (vector signed char, vector signed char); +vector signed int vec_any_lt (vector signed short, vector unsigned short); +vector signed int vec_any_lt (vector unsigned short, vector signed short); +vector signed int vec_any_lt (vector unsigned short, vector unsigned short); +vector signed int vec_any_lt (vector signed short, vector signed short); + +vector signed int vec_any_lt (vector signed int, vector unsigned int); +vector signed int vec_any_lt (vector unsigned int, vector signed int); +vector signed int vec_any_lt (vector unsigned int, vector unsigned int); + +vector signed int vec_any_lt (vector signed int, vector signed int); +vector signed int vec_any_lt (vector float, vector float); + +vector signed int vec_any_nan (vector float); + +vector signed int vec_any_ne (vector signed char, vector unsigned char); + +vector signed int vec_any_ne (vector signed char, vector signed char); +vector signed int vec_any_ne (vector unsigned char, vector signed char); + +vector signed int vec_any_ne (vector unsigned char, vector unsigned char); +vector signed int vec_any_ne (vector signed short, vector unsigned short); +vector signed int vec_any_ne (vector signed short, vector signed short); + +vector signed int vec_any_ne (vector unsigned short, vector signed short); +vector signed int vec_any_ne (vector unsigned short, vector unsigned short); +vector signed int vec_any_ne (vector signed int, vector unsigned int); +vector signed int vec_any_ne (vector signed int, vector signed int); +vector signed int vec_any_ne (vector unsigned int, vector signed int); +vector signed int vec_any_ne (vector unsigned int, vector unsigned int); + +vector signed int vec_any_ne (vector float, vector float); + +vector signed int vec_any_nge (vector float, vector float); + +vector signed int vec_any_ngt (vector float, vector float); + +vector signed int vec_any_nle (vector float, vector float); + +vector signed int vec_any_nlt (vector float, vector float); + +vector signed int vec_any_numeric (vector float); + +vector signed int vec_any_out (vector float, vector float); +@end smallexample + +@node Pragmas +@section Pragmas Accepted by GCC +@cindex pragmas +@cindex #pragma + +GCC supports several types of pragmas, primarily in order to compile +code originally written for other compilers. Note that in general +we do not recommend the use of pragmas; @xref{Function Attributes}, +for further explanation. + +@menu +* ARM Pragmas:: +* Darwin Pragmas:: +@end menu + +@node ARM Pragmas +@subsection ARM Pragmas + +The ARM target defines pragmas for controlling the default addition of +@code{long_call} and @code{short_call} attributes to functions. +@xref{Function Attributes}, for information about the effects of these +attributes. + +@table @code +@item long_calls +@cindex pragma, long_calls +Set all subsequent functions to have the @code{long_call} attribute. + +@item no_long_calls +@cindex pragma, no_long_calls +Set all subsequent functions to have the @code{short_call} attribute. + +@item long_calls_off +@cindex pragma, long_calls_off +Do not affect the @code{long_call} or @code{short_call} attributes of +subsequent functions. +@end table + +@c Describe c4x pragmas here. +@c Describe h8300 pragmas here. +@c Describe i370 pragmas here. +@c Describe i960 pragmas here. +@c Describe sh pragmas here. +@c Describe v850 pragmas here. + +@node Darwin Pragmas +@subsection Darwin Pragmas + +The following pragmas are available for all architectures running the +Darwin operating system. These are useful for compatibility with other +MacOS compilers. + +@table @code +@item mark @var{tokens}@dots{} +@cindex pragma, mark +This pragma is accepted, but has no effect. + +@item options align=@var{alignment} +@cindex pragma, options align +This pragma sets the alignment of fields in structures. The values of +@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or +@code{power}, to emulate PowerPC alignment. Uses of this pragma nest +properly; to restore the previous setting, use @code{reset} for the +@var{alignment}. + +@item segment @var{tokens}@dots{} +@cindex pragma, segment +This pragma is accepted, but has no effect. + +@item unused (@var{var} [, @var{var}]@dots{}) +@cindex pragma, unused +This pragma declares variables to be possibly unused. GCC will not +produce warnings for the listed variables. The effect is similar to +that of the @code{unused} attribute, except that this pragma may appear +anywhere within the variables' scopes. +@end table + +@node Unnamed Fields +@section Unnamed struct/union fields within structs/unions. +@cindex struct +@cindex union + +For compatibility with other compilers, GCC allows you to define +a structure or union that contains, as fields, structures and unions +without names. For example: + +@example +struct @{ + int a; + union @{ + int b; + float c; + @}; + int d; +@} foo; +@end example + +In this example, the user would be able to access members of the unnamed +union with code like @samp{foo.b}. Note that only unnamed structs and +unions are allowed, you may not have, for example, an unnamed +@code{int}. + +You must never create such structures that cause ambiguous field definitions. +For example, this structure: + +@example +struct @{ + int a; + struct @{ + int a; + @}; +@} foo; +@end example + +It is ambiguous which @code{a} is being referred to with @samp{foo.a}. +Such constructs are not supported and must be avoided. In the future, +such constructs may be detected and treated as compilation errors. + +@node C++ Extensions +@chapter Extensions to the C++ Language +@cindex extensions, C++ language +@cindex C++ language extensions + +The GNU compiler provides these extensions to the C++ language (and you +can also use most of the C language extensions in your C++ programs). If you +want to write code that checks whether these features are available, you can +test for the GNU compiler the same way as for C programs: check for a +predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to +test specifically for GNU C++ (@pxref{Standard Predefined,,Standard +Predefined Macros,cpp.info,The C Preprocessor}). + +@menu +* Min and Max:: C++ Minimum and maximum operators. +* Volatiles:: What constitutes an access to a volatile object. +* Restricted Pointers:: C99 restricted pointers and references. +* Vague Linkage:: Where G++ puts inlines, vtables and such. +* C++ Interface:: You can use a single C++ header file for both + declarations and definitions. +* Template Instantiation:: Methods for ensuring that exactly one copy of + each needed template instantiation is emitted. +* Bound member functions:: You can extract a function pointer to the + method denoted by a @samp{->*} or @samp{.*} expression. +* C++ Attributes:: Variable, function, and type attributes for C++ only. +* Java Exceptions:: Tweaking exception handling to work with Java. +* Deprecated Features:: Things might disappear from g++. +* Backwards Compatibility:: Compatibilities with earlier definitions of C++. +@end menu + +@node Min and Max +@section Minimum and Maximum Operators in C++ + +It is very convenient to have operators which return the ``minimum'' or the +``maximum'' of two arguments. In GNU C++ (but not in GNU C), + +@table @code +@item @var{a} <? @var{b} +@findex <? +@cindex minimum operator +is the @dfn{minimum}, returning the smaller of the numeric values +@var{a} and @var{b}; + +@item @var{a} >? @var{b} +@findex >? +@cindex maximum operator +is the @dfn{maximum}, returning the larger of the numeric values @var{a} +and @var{b}. +@end table + +These operations are not primitive in ordinary C++, since you can +use a macro to return the minimum of two things in C++, as in the +following example. + +@example +#define MIN(X,Y) ((X) < (Y) ? : (X) : (Y)) +@end example + +@noindent +You might then use @w{@samp{int min = MIN (i, j);}} to set @var{min} to +the minimum value of variables @var{i} and @var{j}. + +However, side effects in @code{X} or @code{Y} may cause unintended +behavior. For example, @code{MIN (i++, j++)} will fail, incrementing +the smaller counter twice. A GNU C extension allows you to write safe +macros that avoid this kind of problem (@pxref{Naming Types,,Naming an +Expression's Type}). However, writing @code{MIN} and @code{MAX} as +macros also forces you to use function-call notation for a +fundamental arithmetic operation. Using GNU C++ extensions, you can +write @w{@samp{int min = i <? j;}} instead. + +Since @code{<?} and @code{>?} are built into the compiler, they properly +handle expressions with side-effects; @w{@samp{int min = i++ <? j++;}} +works correctly. + +@node Volatiles +@section When is a Volatile Object Accessed? +@cindex accessing volatiles +@cindex volatile read +@cindex volatile write +@cindex volatile access + +Both the C and C++ standard have the concept of volatile objects. These +are normally accessed by pointers and used for accessing hardware. The +standards encourage compilers to refrain from optimizations +concerning accesses to volatile objects that it might perform on +non-volatile objects. The C standard leaves it implementation defined +as to what constitutes a volatile access. The C++ standard omits to +specify this, except to say that C++ should behave in a similar manner +to C with respect to volatiles, where possible. The minimum either +standard specifies is that at a sequence point all previous accesses to +volatile objects have stabilized and no subsequent accesses have +occurred. Thus an implementation is free to reorder and combine +volatile accesses which occur between sequence points, but cannot do so +for accesses across a sequence point. The use of volatiles does not +allow you to violate the restriction on updating objects multiple times +within a sequence point. + +In most expressions, it is intuitively obvious what is a read and what is +a write. For instance + +@example +volatile int *dst = @var{somevalue}; +volatile int *src = @var{someothervalue}; +*dst = *src; +@end example + +@noindent +will cause a read of the volatile object pointed to by @var{src} and stores the +value into the volatile object pointed to by @var{dst}. There is no +guarantee that these reads and writes are atomic, especially for objects +larger than @code{int}. + +Less obvious expressions are where something which looks like an access +is used in a void context. An example would be, + +@example +volatile int *src = @var{somevalue}; +*src; +@end example + +With C, such expressions are rvalues, and as rvalues cause a read of +the object, GCC interprets this as a read of the volatile being pointed +to. The C++ standard specifies that such expressions do not undergo +lvalue to rvalue conversion, and that the type of the dereferenced +object may be incomplete. The C++ standard does not specify explicitly +that it is this lvalue to rvalue conversion which is responsible for +causing an access. However, there is reason to believe that it is, +because otherwise certain simple expressions become undefined. However, +because it would surprise most programmers, G++ treats dereferencing a +pointer to volatile object of complete type in a void context as a read +of the object. When the object has incomplete type, G++ issues a +warning. + +@example +struct S; +struct T @{int m;@}; +volatile S *ptr1 = @var{somevalue}; +volatile T *ptr2 = @var{somevalue}; +*ptr1; +*ptr2; +@end example + +In this example, a warning is issued for @code{*ptr1}, and @code{*ptr2} +causes a read of the object pointed to. If you wish to force an error on +the first case, you must force a conversion to rvalue with, for instance +a static cast, @code{static_cast<S>(*ptr1)}. + +When using a reference to volatile, G++ does not treat equivalent +expressions as accesses to volatiles, but instead issues a warning that +no volatile is accessed. The rationale for this is that otherwise it +becomes difficult to determine where volatile access occur, and not +possible to ignore the return value from functions returning volatile +references. Again, if you wish to force a read, cast the reference to +an rvalue. + +@node Restricted Pointers +@section Restricting Pointer Aliasing +@cindex restricted pointers +@cindex restricted references +@cindex restricted this pointer + +As with gcc, g++ understands the C99 feature of restricted pointers, +specified with the @code{__restrict__}, or @code{__restrict} type +qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} +language flag, @code{restrict} is not a keyword in C++. + +In addition to allowing restricted pointers, you can specify restricted +references, which indicate that the reference is not aliased in the local +context. + +@example +void fn (int *__restrict__ rptr, int &__restrict__ rref) +@{ + @dots{} +@} +@end example + +@noindent +In the body of @code{fn}, @var{rptr} points to an unaliased integer and +@var{rref} refers to a (different) unaliased integer. + +You may also specify whether a member function's @var{this} pointer is +unaliased by using @code{__restrict__} as a member function qualifier. + +@example +void T::fn () __restrict__ +@{ + @dots{} +@} +@end example + +@noindent +Within the body of @code{T::fn}, @var{this} will have the effective +definition @code{T *__restrict__ const this}. Notice that the +interpretation of a @code{__restrict__} member function qualifier is +different to that of @code{const} or @code{volatile} qualifier, in that it +is applied to the pointer rather than the object. This is consistent with +other compilers which implement restricted pointers. + +As with all outermost parameter qualifiers, @code{__restrict__} is +ignored in function definition matching. This means you only need to +specify @code{__restrict__} in a function definition, rather than +in a function prototype as well. + +@node Vague Linkage +@section Vague Linkage +@cindex vague linkage + +There are several constructs in C++ which require space in the object +file but are not clearly tied to a single translation unit. We say that +these constructs have ``vague linkage''. Typically such constructs are +emitted wherever they are needed, though sometimes we can be more +clever. + +@table @asis +@item Inline Functions +Inline functions are typically defined in a header file which can be +included in many different compilations. Hopefully they can usually be +inlined, but sometimes an out-of-line copy is necessary, if the address +of the function is taken or if inlining fails. In general, we emit an +out-of-line copy in all translation units where one is needed. As an +exception, we only emit inline virtual functions with the vtable, since +it will always require a copy. + +Local static variables and string constants used in an inline function +are also considered to have vague linkage, since they must be shared +between all inlined and out-of-line instances of the function. + +@item VTables +@cindex vtable +C++ virtual functions are implemented in most compilers using a lookup +table, known as a vtable. The vtable contains pointers to the virtual +functions provided by a class, and each object of the class contains a +pointer to its vtable (or vtables, in some multiple-inheritance +situations). If the class declares any non-inline, non-pure virtual +functions, the first one is chosen as the ``key method'' for the class, +and the vtable is only emitted in the translation unit where the key +method is defined. + +@emph{Note:} If the chosen key method is later defined as inline, the +vtable will still be emitted in every translation unit which defines it. +Make sure that any inline virtuals are declared inline in the class +body, even if they are not defined there. + +@item type_info objects +@cindex type_info +@cindex RTTI +C++ requires information about types to be written out in order to +implement @samp{dynamic_cast}, @samp{typeid} and exception handling. +For polymorphic classes (classes with virtual functions), the type_info +object is written out along with the vtable so that @samp{dynamic_cast} +can determine the dynamic type of a class object at runtime. For all +other types, we write out the type_info object when it is used: when +applying @samp{typeid} to an expression, throwing an object, or +referring to a type in a catch clause or exception specification. + +@item Template Instantiations +Most everything in this section also applies to template instantiations, +but there are other options as well. +@xref{Template Instantiation,,Where's the Template?}. + +@end table + +When used with GNU ld version 2.8 or later on an ELF system such as +Linux/GNU or Solaris 2, or on Microsoft Windows, duplicate copies of +these constructs will be discarded at link time. This is known as +COMDAT support. + +On targets that don't support COMDAT, but do support weak symbols, GCC +will use them. This way one copy will override all the others, but +the unused copies will still take up space in the executable. + +For targets which do not support either COMDAT or weak symbols, +most entities with vague linkage will be emitted as local symbols to +avoid duplicate definition errors from the linker. This will not happen +for local statics in inlines, however, as having multiple copies will +almost certainly break things. + +@xref{C++ Interface,,Declarations and Definitions in One Header}, for +another way to control placement of these constructs. + +@node C++ Interface +@section Declarations and Definitions in One Header + +@cindex interface and implementation headers, C++ +@cindex C++ interface and implementation headers +C++ object definitions can be quite complex. In principle, your source +code will need two kinds of things for each object that you use across +more than one source file. First, you need an @dfn{interface} +specification, describing its structure with type declarations and +function prototypes. Second, you need the @dfn{implementation} itself. +It can be tedious to maintain a separate interface description in a +header file, in parallel to the actual implementation. It is also +dangerous, since separate interface and implementation definitions may +not remain parallel. + +@cindex pragmas, interface and implementation +With GNU C++, you can use a single header file for both purposes. + +@quotation +@emph{Warning:} The mechanism to specify this is in transition. For the +nonce, you must use one of two @code{#pragma} commands; in a future +release of GNU C++, an alternative mechanism will make these +@code{#pragma} commands unnecessary. +@end quotation + +The header file contains the full definitions, but is marked with +@samp{#pragma interface} in the source code. This allows the compiler +to use the header file only as an interface specification when ordinary +source files incorporate it with @code{#include}. In the single source +file where the full implementation belongs, you can use either a naming +convention or @samp{#pragma implementation} to indicate this alternate +use of the header file. + +@table @code +@item #pragma interface +@itemx #pragma interface "@var{subdir}/@var{objects}.h" +@kindex #pragma interface +Use this directive in @emph{header files} that define object classes, to save +space in most of the object files that use those classes. Normally, +local copies of certain information (backup copies of inline member +functions, debugging information, and the internal tables that implement +virtual functions) must be kept in each object file that includes class +definitions. You can use this pragma to avoid such duplication. When a +header file containing @samp{#pragma interface} is included in a +compilation, this auxiliary information will not be generated (unless +the main input source file itself uses @samp{#pragma implementation}). +Instead, the object files will contain references to be resolved at link +time. + +The second form of this directive is useful for the case where you have +multiple headers with the same name in different directories. If you +use this form, you must specify the same string to @samp{#pragma +implementation}. + +@item #pragma implementation +@itemx #pragma implementation "@var{objects}.h" +@kindex #pragma implementation +Use this pragma in a @emph{main input file}, when you want full output from +included header files to be generated (and made globally visible). The +included header file, in turn, should use @samp{#pragma interface}. +Backup copies of inline member functions, debugging information, and the +internal tables used to implement virtual functions are all generated in +implementation files. + +@cindex implied @code{#pragma implementation} +@cindex @code{#pragma implementation}, implied +@cindex naming convention, implementation headers +If you use @samp{#pragma implementation} with no argument, it applies to +an include file with the same basename@footnote{A file's @dfn{basename} +was the name stripped of all leading path information and of trailing +suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source +file. For example, in @file{allclass.cc}, giving just +@samp{#pragma implementation} +by itself is equivalent to @samp{#pragma implementation "allclass.h"}. + +In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as +an implementation file whenever you would include it from +@file{allclass.cc} even if you never specified @samp{#pragma +implementation}. This was deemed to be more trouble than it was worth, +however, and disabled. + +If you use an explicit @samp{#pragma implementation}, it must appear in +your source file @emph{before} you include the affected header files. + +Use the string argument if you want a single implementation file to +include code from multiple header files. (You must also use +@samp{#include} to include the header file; @samp{#pragma +implementation} only specifies how to use the file---it doesn't actually +include it.) + +There is no way to split up the contents of a single header file into +multiple implementation files. +@end table + +@cindex inlining and C++ pragmas +@cindex C++ pragmas, effect on inlining +@cindex pragmas in C++, effect on inlining +@samp{#pragma implementation} and @samp{#pragma interface} also have an +effect on function inlining. + +If you define a class in a header file marked with @samp{#pragma +interface}, the effect on a function defined in that class is similar to +an explicit @code{extern} declaration---the compiler emits no code at +all to define an independent version of the function. Its definition +is used only for inlining with its callers. + +@opindex fno-implement-inlines +Conversely, when you include the same header file in a main source file +that declares it as @samp{#pragma implementation}, the compiler emits +code for the function itself; this defines a version of the function +that can be found via pointers (or by callers compiled without +inlining). If all calls to the function can be inlined, you can avoid +emitting the function by compiling with @option{-fno-implement-inlines}. +If any calls were not inlined, you will get linker errors. + +@node Template Instantiation +@section Where's the Template? + +@cindex template instantiation + +C++ templates are the first language feature to require more +intelligence from the environment than one usually finds on a UNIX +system. Somehow the compiler and linker have to make sure that each +template instance occurs exactly once in the executable if it is needed, +and not at all otherwise. There are two basic approaches to this +problem, which I will refer to as the Borland model and the Cfront model. + +@table @asis +@item Borland model +Borland C++ solved the template instantiation problem by adding the code +equivalent of common blocks to their linker; the compiler emits template +instances in each translation unit that uses them, and the linker +collapses them together. The advantage of this model is that the linker +only has to consider the object files themselves; there is no external +complexity to worry about. This disadvantage is that compilation time +is increased because the template code is being compiled repeatedly. +Code written for this model tends to include definitions of all +templates in the header file, since they must be seen to be +instantiated. + +@item Cfront model +The AT&T C++ translator, Cfront, solved the template instantiation +problem by creating the notion of a template repository, an +automatically maintained place where template instances are stored. A +more modern version of the repository works as follows: As individual +object files are built, the compiler places any template definitions and +instantiations encountered in the repository. At link time, the link +wrapper adds in the objects in the repository and compiles any needed +instances that were not previously emitted. The advantages of this +model are more optimal compilation speed and the ability to use the +system linker; to implement the Borland model a compiler vendor also +needs to replace the linker. The disadvantages are vastly increased +complexity, and thus potential for error; for some code this can be +just as transparent, but in practice it can been very difficult to build +multiple programs in one directory and one program in multiple +directories. Code written for this model tends to separate definitions +of non-inline member templates into a separate file, which should be +compiled separately. +@end table + +When used with GNU ld version 2.8 or later on an ELF system such as +Linux/GNU or Solaris 2, or on Microsoft Windows, g++ supports the +Borland model. On other systems, g++ implements neither automatic +model. + +A future version of g++ will support a hybrid model whereby the compiler +will emit any instantiations for which the template definition is +included in the compile, and store template definitions and +instantiation context information into the object file for the rest. +The link wrapper will extract that information as necessary and invoke +the compiler to produce the remaining instantiations. The linker will +then combine duplicate instantiations. + +In the mean time, you have the following options for dealing with +template instantiations: + +@enumerate +@item +@opindex frepo +Compile your template-using code with @option{-frepo}. The compiler will +generate files with the extension @samp{.rpo} listing all of the +template instantiations used in the corresponding object files which +could be instantiated there; the link wrapper, @samp{collect2}, will +then update the @samp{.rpo} files to tell the compiler where to place +those instantiations and rebuild any affected object files. The +link-time overhead is negligible after the first pass, as the compiler +will continue to place the instantiations in the same files. + +This is your best option for application code written for the Borland +model, as it will just work. Code written for the Cfront model will +need to be modified so that the template definitions are available at +one or more points of instantiation; usually this is as simple as adding +@code{#include <tmethods.cc>} to the end of each template header. + +For library code, if you want the library to provide all of the template +instantiations it needs, just try to link all of its object files +together; the link will fail, but cause the instantiations to be +generated as a side effect. Be warned, however, that this may cause +conflicts if multiple libraries try to provide the same instantiations. +For greater control, use explicit instantiation as described in the next +option. + +@item +@opindex fno-implicit-templates +Compile your code with @option{-fno-implicit-templates} to disable the +implicit generation of template instances, and explicitly instantiate +all the ones you use. This approach requires more knowledge of exactly +which instances you need than do the others, but it's less +mysterious and allows greater control. You can scatter the explicit +instantiations throughout your program, perhaps putting them in the +translation units where the instances are used or the translation units +that define the templates themselves; you can put all of the explicit +instantiations you need into one big file; or you can create small files +like + +@example +#include "Foo.h" +#include "Foo.cc" + +template class Foo<int>; +template ostream& operator << + (ostream&, const Foo<int>&); +@end example + +for each of the instances you need, and create a template instantiation +library from those. + +If you are using Cfront-model code, you can probably get away with not +using @option{-fno-implicit-templates} when compiling files that don't +@samp{#include} the member template definitions. + +If you use one big file to do the instantiations, you may want to +compile it without @option{-fno-implicit-templates} so you get all of the +instances required by your explicit instantiations (but not by any +other files) without having to specify them as well. + +g++ has extended the template instantiation syntax outlined in the +Working Paper to allow forward declaration of explicit instantiations +(with @code{extern}), instantiation of the compiler support data for a +template class (i.e.@: the vtable) without instantiating any of its +members (with @code{inline}), and instantiation of only the static data +members of a template class, without the support data or member +functions (with (@code{static}): + +@example +extern template int max (int, int); +inline template class Foo<int>; +static template class Foo<int>; +@end example + +@item +Do nothing. Pretend g++ does implement automatic instantiation +management. Code written for the Borland model will work fine, but +each translation unit will contain instances of each of the templates it +uses. In a large program, this can lead to an unacceptable amount of code +duplication. + +@item +@opindex fexternal-templates +Add @samp{#pragma interface} to all files containing template +definitions. For each of these files, add @samp{#pragma implementation +"@var{filename}"} to the top of some @samp{.C} file which +@samp{#include}s it. Then compile everything with +@option{-fexternal-templates}. The templates will then only be expanded +in the translation unit which implements them (i.e.@: has a @samp{#pragma +implementation} line for the file where they live); all other files will +use external references. If you're lucky, everything should work +properly. If you get undefined symbol errors, you need to make sure +that each template instance which is used in the program is used in the +file which implements that template. If you don't have any use for a +particular instance in that file, you can just instantiate it +explicitly, using the syntax from the latest C++ working paper: + +@example +template class A<int>; +template ostream& operator << (ostream&, const A<int>&); +@end example + +This strategy will work with code written for either model. If you are +using code written for the Cfront model, the file containing a class +template and the file containing its member templates should be +implemented in the same translation unit. + +@item +@opindex falt-external-templates +A slight variation on this approach is to use the flag +@option{-falt-external-templates} instead. This flag causes template +instances to be emitted in the translation unit that implements the +header where they are first instantiated, rather than the one which +implements the file where the templates are defined. This header must +be the same in all translation units, or things are likely to break. + +@xref{C++ Interface,,Declarations and Definitions in One Header}, for +more discussion of these pragmas. +@end enumerate + +@node Bound member functions +@section Extracting the function pointer from a bound pointer to member function + +@cindex pmf +@cindex pointer to member function +@cindex bound pointer to member function + +In C++, pointer to member functions (PMFs) are implemented using a wide +pointer of sorts to handle all the possible call mechanisms; the PMF +needs to store information about how to adjust the @samp{this} pointer, +and if the function pointed to is virtual, where to find the vtable, and +where in the vtable to look for the member function. If you are using +PMFs in an inner loop, you should really reconsider that decision. If +that is not an option, you can extract the pointer to the function that +would be called for a given object/PMF pair and call it directly inside +the inner loop, to save a bit of time. + +Note that you will still be paying the penalty for the call through a +function pointer; on most modern architectures, such a call defeats the +branch prediction features of the CPU@. This is also true of normal +virtual function calls. + +The syntax for this extension is + +@example +extern A a; +extern int (A::*fp)(); +typedef int (*fptr)(A *); + +fptr p = (fptr)(a.*fp); +@end example + +For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), +no object is needed to obtain the address of the function. They can be +converted to function pointers directly: + +@example +fptr p1 = (fptr)(&A::foo); +@end example + +@opindex Wno-pmf-conversions +You must specify @option{-Wno-pmf-conversions} to use this extension. + +@node C++ Attributes +@section C++-Specific Variable, Function, and Type Attributes + +Some attributes only make sense for C++ programs. + +@table @code +@item init_priority (@var{priority}) +@cindex init_priority attribute + + +In Standard C++, objects defined at namespace scope are guaranteed to be +initialized in an order in strict accordance with that of their definitions +@emph{in a given translation unit}. No guarantee is made for initializations +across translation units. However, GNU C++ allows users to control the +order of initialization of objects defined at namespace scope with the +@code{init_priority} attribute by specifying a relative @var{priority}, +a constant integral expression currently bounded between 101 and 65535 +inclusive. Lower numbers indicate a higher priority. + +In the following example, @code{A} would normally be created before +@code{B}, but the @code{init_priority} attribute has reversed that order: + +@example +Some_Class A __attribute__ ((init_priority (2000))); +Some_Class B __attribute__ ((init_priority (543))); +@end example + +@noindent +Note that the particular values of @var{priority} do not matter; only their +relative ordering. + +@item java_interface +@cindex java_interface attribute + +This type attribute informs C++ that the class is a Java interface. It may +only be applied to classes declared within an @code{extern "Java"} block. +Calls to methods declared in this interface will be dispatched using GCJ's +interface table mechanism, instead of regular virtual table dispatch. + +@end table + +@node Java Exceptions +@section Java Exceptions + +The Java language uses a slightly different exception handling model +from C++. Normally, GNU C++ will automatically detect when you are +writing C++ code that uses Java exceptions, and handle them +appropriately. However, if C++ code only needs to execute destructors +when Java exceptions are thrown through it, GCC will guess incorrectly. +Sample problematic code is: + +@example + struct S @{ ~S(); @}; + extern void bar(); // is written in Java, and may throw exceptions + void foo() + @{ + S s; + bar(); + @} +@end example + +@noindent +The usual effect of an incorrect guess is a link failure, complaining of +a missing routine called @samp{__gxx_personality_v0}. + +You can inform the compiler that Java exceptions are to be used in a +translation unit, irrespective of what it might think, by writing +@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This +@samp{#pragma} must appear before any functions that throw or catch +exceptions, or run destructors when exceptions are thrown through them. + +You cannot mix Java and C++ exceptions in the same translation unit. It +is believed to be safe to throw a C++ exception from one file through +another file compiled for the Java exception model, or vice versa, but +there may be bugs in this area. + +@node Deprecated Features +@section Deprecated Features + +In the past, the GNU C++ compiler was extended to experiment with new +features, at a time when the C++ language was still evolving. Now that +the C++ standard is complete, some of those features are superseded by +superior alternatives. Using the old features might cause a warning in +some cases that the feature will be dropped in the future. In other +cases, the feature might be gone already. + +While the list below is not exhaustive, it documents some of the options +that are now deprecated: + +@table @code +@item -fexternal-templates +@itemx -falt-external-templates +These are two of the many ways for g++ to implement template +instantiation. @xref{Template Instantiation}. The C++ standard clearly +defines how template definitions have to be organized across +implementation units. g++ has an implicit instantiation mechanism that +should work just fine for standard-conforming code. + +@item -fstrict-prototype +@itemx -fno-strict-prototype +Previously it was possible to use an empty prototype parameter list to +indicate an unspecified number of parameters (like C), rather than no +parameters, as C++ demands. This feature has been removed, except where +it is required for backwards compatibility @xref{Backwards Compatibility}. +@end table + +The named return value extension has been deprecated, and is now +removed from g++. + +The use of initializer lists with new expressions has been deprecated, +and is now removed from g++. + +Floating and complex non-type template parameters have been deprecated, +and are now removed from g++. + +The implicit typename extension has been deprecated and will be removed +from g++ at some point. In some cases g++ determines that a dependant +type such as @code{TPL<T>::X} is a type without needing a +@code{typename} keyword, contrary to the standard. + +@node Backwards Compatibility +@section Backwards Compatibility +@cindex Backwards Compatibility +@cindex ARM [Annotated C++ Reference Manual] + +Now that there is a definitive ISO standard C++, G++ has a specification +to adhere to. The C++ language evolved over time, and features that +used to be acceptable in previous drafts of the standard, such as the ARM +[Annotated C++ Reference Manual], are no longer accepted. In order to allow +compilation of C++ written to such drafts, G++ contains some backwards +compatibilities. @emph{All such backwards compatibility features are +liable to disappear in future versions of G++.} They should be considered +deprecated @xref{Deprecated Features}. + +@table @code +@item For scope +If a variable is declared at for scope, it used to remain in scope until +the end of the scope which contained the for statement (rather than just +within the for scope). G++ retains this, but issues a warning, if such a +variable is accessed outside the for scope. + +@item Implicit C language +Old C system header files did not contain an @code{extern "C" @{@dots{}@}} +scope to set the language. On such systems, all header files are +implicitly scoped inside a C language scope. Also, an empty prototype +@code{()} will be treated as an unspecified number of arguments, rather +than no arguments, as C++ demands. +@end table |