diff options
Diffstat (limited to 'gcc-4.8.1/gcc/doc/extend.texi')
| -rw-r--r-- | gcc-4.8.1/gcc/doc/extend.texi | 16241 |
1 files changed, 0 insertions, 16241 deletions
diff --git a/gcc-4.8.1/gcc/doc/extend.texi b/gcc-4.8.1/gcc/doc/extend.texi deleted file mode 100644 index 4eb732ef8..000000000 --- a/gcc-4.8.1/gcc/doc/extend.texi +++ /dev/null @@ -1,16241 +0,0 @@ -@c Copyright (C) 1988-2013 Free Software Foundation, Inc. - -@c This is part of the GCC manual. -@c For copying conditions, see the file gcc.texi. - -@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 C90 or C++ are also, as -extensions, accepted by GCC in C90 mode and in C++. - -@menu -* Statement Exprs:: Putting statements and declarations inside expressions. -* Local Labels:: Labels local to a block. -* 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. -* Typeof:: @code{typeof}: referring to the type of an expression. -* Conditionals:: Omitting the middle operand of a @samp{?:} expression. -* __int128:: 128-bit integers---@code{__int128}. -* Long Long:: Double-word integers---@code{long long int}. -* Complex:: Data types for complex numbers. -* Floating Types:: Additional Floating Types. -* Half-Precision:: Half-Precision Floating Point. -* Decimal Float:: Decimal Floating Types. -* Hex Floats:: Hexadecimal floating-point constants. -* Fixed-Point:: Fixed-Point Types. -* Named Address Spaces::Named address spaces. -* Zero Length:: Zero-length arrays. -* Empty Structures:: Structures with no members. -* 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. -* 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. -* Case Ranges:: `case 1 ... 9' and such. -* Cast to Union:: Casting to union type from any member of the union. -* 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). -* Volatiles:: What constitutes an access to a volatile object. -* 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. -* Offsetof:: Special syntax for implementing @code{offsetof}. -* __sync Builtins:: Legacy built-in functions for atomic memory access. -* __atomic Builtins:: Atomic built-in functions with memory model. -* x86 specific memory model extensions for transactional memory:: x86 memory models. -* Object Size Checking:: Built-in functions for limited buffer overflow - checking. -* Other Builtins:: Other built-in functions. -* Target Builtins:: Built-in functions specific to particular targets. -* Target Format Checks:: Format checks specific to particular targets. -* Pragmas:: Pragmas accepted by GCC. -* Unnamed Fields:: Unnamed struct/union fields within structs/unions. -* Thread-Local:: Per-thread variables. -* Binary constants:: Binary constants using the @samp{0b} prefix. -@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: - -@smallexample -(@{ int y = foo (); int z; - if (y > 0) z = y; - else z = - y; - z; @}) -@end smallexample - -@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: - -@smallexample -#define max(a,b) ((a) > (b) ? (a) : (b)) -@end smallexample - -@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 taken as @code{int}), you can define -the macro safely as follows: - -@smallexample -#define maxint(a,b) \ - (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) -@end smallexample - -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}). - -In G++, the result value of a statement expression undergoes array and -function pointer decay, and is returned by value to the enclosing -expression. For instance, if @code{A} is a class, then - -@smallexample - A a; - - (@{a;@}).Foo () -@end smallexample - -@noindent -constructs a temporary @code{A} object to hold the result of the -statement expression, and that is used to invoke @code{Foo}. -Therefore the @code{this} pointer observed by @code{Foo} is not the -address of @code{a}. - -In a statement expression, any temporaries created within a statement -are destroyed at that statement's end. This makes statement -expressions inside macros slightly different from function calls. In -the latter case temporaries introduced during argument evaluation are -destroyed at the end of the statement that includes the function -call. In the statement expression case they are destroyed during -the statement expression. For instance, - -@smallexample -#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) -template<typename T> T function(T a) @{ T b = a; return b + 3; @} - -void foo () -@{ - macro (X ()); - function (X ()); -@} -@end smallexample - -@noindent -has different places where temporaries are destroyed. For the -@code{macro} case, the temporary @code{X} is destroyed just after -the initialization of @code{b}. In the @code{function} case that -temporary is destroyed when the function returns. - -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 expressions that lead to precisely this -bug.) - -Jumping into a statement expression with @code{goto} or using a -@code{switch} statement outside the statement expression with a -@code{case} or @code{default} label inside the statement expression is -not permitted. Jumping into a statement expression with a computed -@code{goto} (@pxref{Labels as Values}) has undefined behavior. -Jumping out of a statement expression is permitted, but if the -statement expression is part of a larger expression then it is -unspecified which other subexpressions of that expression have been -evaluated except where the language definition requires certain -subexpressions to be evaluated before or after the statement -expression. In any case, as with a function call, the evaluation of a -statement expression is not interleaved with the evaluation of other -parts of the containing expression. For example, - -@smallexample - foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); -@end smallexample - -@noindent -calls @code{foo} and @code{bar1} and does not call @code{baz} but -may or may not call @code{bar2}. If @code{bar2} is called, it is -called after @code{foo} and before @code{bar1}. - -@node Local Labels -@section Locally Declared Labels -@cindex local labels -@cindex macros, local labels - -GCC allows you to declare @dfn{local labels} in any nested block -scope. A local label is just like an ordinary label, but you can -only reference it (with a @code{goto} statement, or by taking its -address) within the block in which it is declared. - -A local label declaration looks like this: - -@smallexample -__label__ @var{label}; -@end smallexample - -@noindent -or - -@smallexample -__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; -@end smallexample - -Local label declarations must come at the beginning of the block, -before any ordinary declarations or statements. - -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 for complex macros. If a 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 is multiply defined in that function. A -local label avoids this problem. For example: - -@smallexample -#define SEARCH(value, array, target) \ -do @{ \ - __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:; \ -@} while (0) -@end smallexample - -This could also be written using a statement expression: - -@smallexample -#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 smallexample - -Local label declarations also make the labels they declare visible to -nested functions, if there are any. @xref{Nested Functions}, for details. - -@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: - -@smallexample -void *ptr; -/* @r{@dots{}} */ -ptr = &&foo; -@end smallexample - -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, - -@smallexample -goto *ptr; -@end smallexample - -@noindent -Any expression of type @code{void *} is allowed. - -One way of using these constants is in initializing a static array that -serves as a jump table: - -@smallexample -static void *array[] = @{ &&foo, &&bar, &&hack @}; -@end smallexample - -@noindent -Then you can select a label with indexing, like this: - -@smallexample -goto *array[i]; -@end smallexample - -@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 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 - -@smallexample -static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, - &&hack - &&foo @}; -goto *(&&foo + array[i]); -@end smallexample - -@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. - -The @code{&&foo} expressions for the same label might have different -values if the containing function is inlined or cloned. If a program -relies on them being always the same, -@code{__attribute__((__noinline__,__noclone__))} should be used to -prevent inlining and cloning. If @code{&&foo} is used in a static -variable initializer, inlining and cloning is forbidden. - -@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 supported as an extension in GNU C, but are not -supported by 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: - -@smallexample -@group -foo (double a, double b) -@{ - double square (double z) @{ return z * z; @} - - return square (a) + square (b); -@} -@end group -@end smallexample - -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}: - -@smallexample -@group -bar (int *array, int offset, int size) -@{ - int access (int *array, int index) - @{ return array[index + offset]; @} - int i; - /* @r{@dots{}} */ - for (i = 0; i < size; i++) - /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ -@} -@end group -@end smallexample - -Nested function definitions are permitted within functions in the places -where variable definitions are allowed; that is, in any block, mixed -with the other declarations and statements 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: - -@smallexample -hack (int *array, int size) -@{ - void store (int index, int value) - @{ array[index] = value; @} - - intermediate (store, size); -@} -@end smallexample - -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 exits, all hell breaks loose. If you try -to call it after a containing scope level exits, 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}. This technique was described in -@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX -C++ Conference Proceedings, October 17-21, 1988). - -A nested function can jump to a label inherited from a containing -function, provided the label is explicitly declared in the containing -function (@pxref{Local Labels}). Such a jump returns instantly to the -containing function, exiting the nested function that did the -@code{goto} and any intermediate functions as well. Here is an example: - -@smallexample -@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; - /* @r{@dots{}} */ - for (i = 0; i < size; i++) - /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ - /* @r{@dots{}} */ - return 0; - - /* @r{Control comes here from @code{access} - if it detects an error.} */ - failure: - return -1; -@} -@end group -@end smallexample - -A nested function always has no linkage. Declaring one with -@code{extern} or @code{static} is erroneous. If you need to declare the nested function -before its definition, use @code{auto} (which is otherwise meaningless -for function declarations). - -@smallexample -bar (int *array, int offset, int size) -@{ - __label__ failure; - auto int access (int *, int); - /* @r{@dots{}} */ - int access (int *array, int index) - @{ - if (index > size) - goto failure; - return array[index + offset]; - @} - /* @r{@dots{}} */ -@} -@end smallexample - -@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). - -However, these built-in functions may interact badly with some -sophisticated features or other extensions of the language. It -is, therefore, not recommended to use them outside very simple -functions acting as mere forwarders for their arguments. - -@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 are 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 is 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 - -@deftypefn {Built-in Function} {} __builtin_va_arg_pack () -This built-in function represents all anonymous arguments of an inline -function. It can be used only in inline functions that are always -inlined, never compiled as a separate function, such as those using -@code{__attribute__ ((__always_inline__))} or -@code{__attribute__ ((__gnu_inline__))} extern inline functions. -It must be only passed as last argument to some other function -with variable arguments. This is useful for writing small wrapper -inlines for variable argument functions, when using preprocessor -macros is undesirable. For example: -@smallexample -extern int myprintf (FILE *f, const char *format, ...); -extern inline __attribute__ ((__gnu_inline__)) int -myprintf (FILE *f, const char *format, ...) -@{ - int r = fprintf (f, "myprintf: "); - if (r < 0) - return r; - int s = fprintf (f, format, __builtin_va_arg_pack ()); - if (s < 0) - return s; - return r + s; -@} -@end smallexample -@end deftypefn - -@deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len () -This built-in function returns the number of anonymous arguments of -an inline function. It can be used only in inline functions that -are always inlined, never compiled as a separate function, such -as those using @code{__attribute__ ((__always_inline__))} or -@code{__attribute__ ((__gnu_inline__))} extern inline functions. -For example following does link- or run-time checking of open -arguments for optimized code: -@smallexample -#ifdef __OPTIMIZE__ -extern inline __attribute__((__gnu_inline__)) int -myopen (const char *path, int oflag, ...) -@{ - if (__builtin_va_arg_pack_len () > 1) - warn_open_too_many_arguments (); - - if (__builtin_constant_p (oflag)) - @{ - if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1) - @{ - warn_open_missing_mode (); - return __open_2 (path, oflag); - @} - return open (path, oflag, __builtin_va_arg_pack ()); - @} - - if (__builtin_va_arg_pack_len () < 1) - return __open_2 (path, oflag); - - return open (path, oflag, __builtin_va_arg_pack ()); -@} -#endif -@end smallexample -@end deftypefn - -@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: - -@smallexample -typeof (x[0](1)) -@end smallexample - -@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: - -@smallexample -typeof (int *) -@end smallexample - -@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 can be -used. For example, you can use it in a declaration, in a cast, or inside -of @code{sizeof} or @code{typeof}. - -The operand of @code{typeof} is evaluated for its side effects if and -only if it is an expression of variably modified type or the name of -such a type. - -@code{typeof} is often useful in conjunction with -statement expressions (@pxref{Statement Exprs}). -Here is how the two together can -be used to define a safe ``maximum'' macro which operates on any -arithmetic type and evaluates each of its arguments exactly once: - -@smallexample -#define max(a,b) \ - (@{ typeof (a) _a = (a); \ - typeof (b) _b = (b); \ - _a > _b ? _a : _b; @}) -@end smallexample - -@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. - -@noindent -Some more examples of the use of @code{typeof}: - -@itemize @bullet -@item -This declares @code{y} with the type of what @code{x} points to. - -@smallexample -typeof (*x) y; -@end smallexample - -@item -This declares @code{y} as an array of such values. - -@smallexample -typeof (*x) y[4]; -@end smallexample - -@item -This declares @code{y} as an array of pointers to characters: - -@smallexample -typeof (typeof (char *)[4]) y; -@end smallexample - -@noindent -It is equivalent to the following traditional C declaration: - -@smallexample -char *y[4]; -@end smallexample - -To see the meaning of the declaration using @code{typeof}, and why it -might be a useful way to write, rewrite it with these macros: - -@smallexample -#define pointer(T) typeof(T *) -#define array(T, N) typeof(T [N]) -@end smallexample - -@noindent -Now the declaration can be rewritten this way: - -@smallexample -array (pointer (char), 4) y; -@end smallexample - -@noindent -Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 -pointers to @code{char}. -@end itemize - -@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported -a more limited extension that permitted one to write - -@smallexample -typedef @var{T} = @var{expr}; -@end smallexample - -@noindent -with the effect of declaring @var{T} to have the type of the expression -@var{expr}. This extension does not work with GCC 3 (versions between -3.0 and 3.2 crash; 3.2.1 and later give an error). Code that -relies on it should be rewritten to use @code{typeof}: - -@smallexample -typedef typeof(@var{expr}) @var{T}; -@end smallexample - -@noindent -This works with all versions of GCC@. - -@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 - -@smallexample -x ? : y -@end smallexample - -@noindent -has the value of @code{x} if that is nonzero; otherwise, the value of -@code{y}. - -This example is perfectly equivalent to - -@smallexample -x ? x : y -@end smallexample - -@cindex side effect in @code{?:} -@cindex @code{?:} 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 __int128 -@section 128-bit integers -@cindex @code{__int128} data types - -As an extension the integer scalar type @code{__int128} is supported for -targets which have an integer mode wide enough to hold 128 bits. -Simply write @code{__int128} for a signed 128-bit integer, or -@code{unsigned __int128} for an unsigned 128-bit integer. There is no -support in GCC for expressing an integer constant of type @code{__int128} -for targets with @code{long long} integer less than 128 bits wide. - -@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 C90 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 a fullword-to-doubleword 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 without function prototypes. If a function -expects type @code{int} for its argument, and you pass a value of type -@code{long long int}, confusion results because the caller and the -subroutine 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 C90 mode and in C++. GCC also 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 the GNU C Library), 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). Only the DWARF 2 -debug info format can represent this, so use of DWARF 2 is recommended. -If you are using the stabs debug info format, 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. - -@node Floating Types -@section Additional Floating Types -@cindex additional floating types -@cindex @code{__float80} data type -@cindex @code{__float128} data type -@cindex @code{w} floating point suffix -@cindex @code{q} floating point suffix -@cindex @code{W} floating point suffix -@cindex @code{Q} floating point suffix - -As an extension, GNU C supports additional floating -types, @code{__float80} and @code{__float128} to support 80-bit -(@code{XFmode}) and 128-bit (@code{TFmode}) floating types. -Support for additional types includes the arithmetic operators: -add, subtract, multiply, divide; unary arithmetic operators; -relational operators; equality operators; and conversions to and from -integer and other floating types. Use a suffix @samp{w} or @samp{W} -in a literal constant of type @code{__float80} and @samp{q} or @samp{Q} -for @code{_float128}. You can declare complex types using the -corresponding internal complex type, @code{XCmode} for @code{__float80} -type and @code{TCmode} for @code{__float128} type: - -@smallexample -typedef _Complex float __attribute__((mode(TC))) _Complex128; -typedef _Complex float __attribute__((mode(XC))) _Complex80; -@end smallexample - -Not all targets support additional floating-point types. @code{__float80} -and @code{__float128} types are supported on i386, x86_64 and IA-64 targets. -The @code{__float128} type is supported on hppa HP-UX targets. - -@node Half-Precision -@section Half-Precision Floating Point -@cindex half-precision floating point -@cindex @code{__fp16} data type - -On ARM targets, GCC supports half-precision (16-bit) floating point via -the @code{__fp16} type. You must enable this type explicitly -with the @option{-mfp16-format} command-line option in order to use it. - -ARM supports two incompatible representations for half-precision -floating-point values. You must choose one of the representations and -use it consistently in your program. - -Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format. -This format can represent normalized values in the range of @math{2^{-14}} to 65504. -There are 11 bits of significand precision, approximately 3 -decimal digits. - -Specifying @option{-mfp16-format=alternative} selects the ARM -alternative format. This representation is similar to the IEEE -format, but does not support infinities or NaNs. Instead, the range -of exponents is extended, so that this format can represent normalized -values in the range of @math{2^{-14}} to 131008. - -The @code{__fp16} type is a storage format only. For purposes -of arithmetic and other operations, @code{__fp16} values in C or C++ -expressions are automatically promoted to @code{float}. In addition, -you cannot declare a function with a return value or parameters -of type @code{__fp16}. - -Note that conversions from @code{double} to @code{__fp16} -involve an intermediate conversion to @code{float}. Because -of rounding, this can sometimes produce a different result than a -direct conversion. - -ARM provides hardware support for conversions between -@code{__fp16} and @code{float} values -as an extension to VFP and NEON (Advanced SIMD). GCC generates -code using these hardware instructions if you compile with -options to select an FPU that provides them; -for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp}, -in addition to the @option{-mfp16-format} option to select -a half-precision format. - -Language-level support for the @code{__fp16} data type is -independent of whether GCC generates code using hardware floating-point -instructions. In cases where hardware support is not specified, GCC -implements conversions between @code{__fp16} and @code{float} values -as library calls. - -@node Decimal Float -@section Decimal Floating Types -@cindex decimal floating types -@cindex @code{_Decimal32} data type -@cindex @code{_Decimal64} data type -@cindex @code{_Decimal128} data type -@cindex @code{df} integer suffix -@cindex @code{dd} integer suffix -@cindex @code{dl} integer suffix -@cindex @code{DF} integer suffix -@cindex @code{DD} integer suffix -@cindex @code{DL} integer suffix - -As an extension, GNU C supports decimal floating types as -defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal -floating types in GCC will evolve as the draft technical report changes. -Calling conventions for any target might also change. Not all targets -support decimal floating types. - -The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and -@code{_Decimal128}. They use a radix of ten, unlike the floating types -@code{float}, @code{double}, and @code{long double} whose radix is not -specified by the C standard but is usually two. - -Support for decimal floating types includes the arithmetic operators -add, subtract, multiply, divide; unary arithmetic operators; -relational operators; equality operators; and conversions to and from -integer and other floating types. Use a suffix @samp{df} or -@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} -or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for -@code{_Decimal128}. - -GCC support of decimal float as specified by the draft technical report -is incomplete: - -@itemize @bullet -@item -When the value of a decimal floating type cannot be represented in the -integer type to which it is being converted, the result is undefined -rather than the result value specified by the draft technical report. - -@item -GCC does not provide the C library functionality associated with -@file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and -@file{wchar.h}, which must come from a separate C library implementation. -Because of this the GNU C compiler does not define macro -@code{__STDC_DEC_FP__} to indicate that the implementation conforms to -the technical report. -@end itemize - -Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} -are supported by the DWARF 2 debug information format. - -@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 C90 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 is 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 Fixed-Point -@section Fixed-Point Types -@cindex fixed-point types -@cindex @code{_Fract} data type -@cindex @code{_Accum} data type -@cindex @code{_Sat} data type -@cindex @code{hr} fixed-suffix -@cindex @code{r} fixed-suffix -@cindex @code{lr} fixed-suffix -@cindex @code{llr} fixed-suffix -@cindex @code{uhr} fixed-suffix -@cindex @code{ur} fixed-suffix -@cindex @code{ulr} fixed-suffix -@cindex @code{ullr} fixed-suffix -@cindex @code{hk} fixed-suffix -@cindex @code{k} fixed-suffix -@cindex @code{lk} fixed-suffix -@cindex @code{llk} fixed-suffix -@cindex @code{uhk} fixed-suffix -@cindex @code{uk} fixed-suffix -@cindex @code{ulk} fixed-suffix -@cindex @code{ullk} fixed-suffix -@cindex @code{HR} fixed-suffix -@cindex @code{R} fixed-suffix -@cindex @code{LR} fixed-suffix -@cindex @code{LLR} fixed-suffix -@cindex @code{UHR} fixed-suffix -@cindex @code{UR} fixed-suffix -@cindex @code{ULR} fixed-suffix -@cindex @code{ULLR} fixed-suffix -@cindex @code{HK} fixed-suffix -@cindex @code{K} fixed-suffix -@cindex @code{LK} fixed-suffix -@cindex @code{LLK} fixed-suffix -@cindex @code{UHK} fixed-suffix -@cindex @code{UK} fixed-suffix -@cindex @code{ULK} fixed-suffix -@cindex @code{ULLK} fixed-suffix - -As an extension, GNU C supports fixed-point types as -defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point -types in GCC will evolve as the draft technical report changes. -Calling conventions for any target might also change. Not all targets -support fixed-point types. - -The fixed-point types are -@code{short _Fract}, -@code{_Fract}, -@code{long _Fract}, -@code{long long _Fract}, -@code{unsigned short _Fract}, -@code{unsigned _Fract}, -@code{unsigned long _Fract}, -@code{unsigned long long _Fract}, -@code{_Sat short _Fract}, -@code{_Sat _Fract}, -@code{_Sat long _Fract}, -@code{_Sat long long _Fract}, -@code{_Sat unsigned short _Fract}, -@code{_Sat unsigned _Fract}, -@code{_Sat unsigned long _Fract}, -@code{_Sat unsigned long long _Fract}, -@code{short _Accum}, -@code{_Accum}, -@code{long _Accum}, -@code{long long _Accum}, -@code{unsigned short _Accum}, -@code{unsigned _Accum}, -@code{unsigned long _Accum}, -@code{unsigned long long _Accum}, -@code{_Sat short _Accum}, -@code{_Sat _Accum}, -@code{_Sat long _Accum}, -@code{_Sat long long _Accum}, -@code{_Sat unsigned short _Accum}, -@code{_Sat unsigned _Accum}, -@code{_Sat unsigned long _Accum}, -@code{_Sat unsigned long long _Accum}. - -Fixed-point data values contain fractional and optional integral parts. -The format of fixed-point data varies and depends on the target machine. - -Support for fixed-point types includes: -@itemize @bullet -@item -prefix and postfix increment and decrement operators (@code{++}, @code{--}) -@item -unary arithmetic operators (@code{+}, @code{-}, @code{!}) -@item -binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/}) -@item -binary shift operators (@code{<<}, @code{>>}) -@item -relational operators (@code{<}, @code{<=}, @code{>=}, @code{>}) -@item -equality operators (@code{==}, @code{!=}) -@item -assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=}, -@code{<<=}, @code{>>=}) -@item -conversions to and from integer, floating-point, or fixed-point types -@end itemize - -Use a suffix in a fixed-point literal constant: -@itemize -@item @samp{hr} or @samp{HR} for @code{short _Fract} and -@code{_Sat short _Fract} -@item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract} -@item @samp{lr} or @samp{LR} for @code{long _Fract} and -@code{_Sat long _Fract} -@item @samp{llr} or @samp{LLR} for @code{long long _Fract} and -@code{_Sat long long _Fract} -@item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and -@code{_Sat unsigned short _Fract} -@item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and -@code{_Sat unsigned _Fract} -@item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and -@code{_Sat unsigned long _Fract} -@item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract} -and @code{_Sat unsigned long long _Fract} -@item @samp{hk} or @samp{HK} for @code{short _Accum} and -@code{_Sat short _Accum} -@item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum} -@item @samp{lk} or @samp{LK} for @code{long _Accum} and -@code{_Sat long _Accum} -@item @samp{llk} or @samp{LLK} for @code{long long _Accum} and -@code{_Sat long long _Accum} -@item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and -@code{_Sat unsigned short _Accum} -@item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and -@code{_Sat unsigned _Accum} -@item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and -@code{_Sat unsigned long _Accum} -@item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum} -and @code{_Sat unsigned long long _Accum} -@end itemize - -GCC support of fixed-point types as specified by the draft technical report -is incomplete: - -@itemize @bullet -@item -Pragmas to control overflow and rounding behaviors are not implemented. -@end itemize - -Fixed-point types are supported by the DWARF 2 debug information format. - -@node Named Address Spaces -@section Named Address Spaces -@cindex Named Address Spaces - -As an extension, GNU C supports named address spaces as -defined in the N1275 draft of ISO/IEC DTR 18037. Support for named -address spaces in GCC will evolve as the draft technical report -changes. Calling conventions for any target might also change. At -present, only the AVR, SPU, M32C, and RL78 targets support address -spaces other than the generic address space. - -Address space identifiers may be used exactly like any other C type -qualifier (e.g., @code{const} or @code{volatile}). See the N1275 -document for more details. - -@anchor{AVR Named Address Spaces} -@subsection AVR Named Address Spaces - -On the AVR target, there are several address spaces that can be used -in order to put read-only data into the flash memory and access that -data by means of the special instructions @code{LPM} or @code{ELPM} -needed to read from flash. - -Per default, any data including read-only data is located in RAM -(the generic address space) so that non-generic address spaces are -needed to locate read-only data in flash memory -@emph{and} to generate the right instructions to access this data -without using (inline) assembler code. - -@table @code -@item __flash -@cindex @code{__flash} AVR Named Address Spaces -The @code{__flash} qualifier locates data in the -@code{.progmem.data} section. Data is read using the @code{LPM} -instruction. Pointers to this address space are 16 bits wide. - -@item __flash1 -@itemx __flash2 -@itemx __flash3 -@itemx __flash4 -@itemx __flash5 -@cindex @code{__flash1} AVR Named Address Spaces -@cindex @code{__flash2} AVR Named Address Spaces -@cindex @code{__flash3} AVR Named Address Spaces -@cindex @code{__flash4} AVR Named Address Spaces -@cindex @code{__flash5} AVR Named Address Spaces -These are 16-bit address spaces locating data in section -@code{.progmem@var{N}.data} where @var{N} refers to -address space @code{__flash@var{N}}. -The compiler sets the @code{RAMPZ} segment register appropriately -before reading data by means of the @code{ELPM} instruction. - -@item __memx -@cindex @code{__memx} AVR Named Address Spaces -This is a 24-bit address space that linearizes flash and RAM: -If the high bit of the address is set, data is read from -RAM using the lower two bytes as RAM address. -If the high bit of the address is clear, data is read from flash -with @code{RAMPZ} set according to the high byte of the address. -@xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}. - -Objects in this address space are located in @code{.progmemx.data}. -@end table - -@b{Example} - -@smallexample -char my_read (const __flash char ** p) -@{ - /* p is a pointer to RAM that points to a pointer to flash. - The first indirection of p reads that flash pointer - from RAM and the second indirection reads a char from this - flash address. */ - - return **p; -@} - -/* Locate array[] in flash memory */ -const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; - -int i = 1; - -int main (void) -@{ - /* Return 17 by reading from flash memory */ - return array[array[i]]; -@} -@end smallexample - -@noindent -For each named address space supported by avr-gcc there is an equally -named but uppercase built-in macro defined. -The purpose is to facilitate testing if respective address space -support is available or not: - -@smallexample -#ifdef __FLASH -const __flash int var = 1; - -int read_var (void) -@{ - return var; -@} -#else -#include <avr/pgmspace.h> /* From AVR-LibC */ - -const int var PROGMEM = 1; - -int read_var (void) -@{ - return (int) pgm_read_word (&var); -@} -#endif /* __FLASH */ -@end smallexample - -@noindent -Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}} -locates data in flash but -accesses to these data read from generic address space, i.e.@: -from RAM, -so that you need special accessors like @code{pgm_read_byte} -from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} -together with attribute @code{progmem}. - -@noindent -@b{Limitations and caveats} - -@itemize -@item -Reading across the 64@tie{}KiB section boundary of -the @code{__flash} or @code{__flash@var{N}} address spaces -shows undefined behavior. The only address space that -supports reading across the 64@tie{}KiB flash segment boundaries is -@code{__memx}. - -@item -If you use one of the @code{__flash@var{N}} address spaces -you must arrange your linker script to locate the -@code{.progmem@var{N}.data} sections according to your needs. - -@item -Any data or pointers to the non-generic address spaces must -be qualified as @code{const}, i.e.@: as read-only data. -This still applies if the data in one of these address -spaces like software version number or calibration lookup table are intended to -be changed after load time by, say, a boot loader. In this case -the right qualification is @code{const} @code{volatile} so that the compiler -must not optimize away known values or insert them -as immediates into operands of instructions. - -@item -The following code initializes a variable @code{pfoo} -located in static storage with a 24-bit address: -@smallexample -extern const __memx char foo; -const __memx void *pfoo = &foo; -@end smallexample - -@noindent -Such code requires at least binutils 2.23, see -@w{@uref{http://sourceware.org/PR13503,PR13503}}. - -@end itemize - -@subsection M32C Named Address Spaces -@cindex @code{__far} M32C Named Address Spaces - -On the M32C target, with the R8C and M16C CPU variants, variables -qualified with @code{__far} are accessed using 32-bit addresses in -order to access memory beyond the first 64@tie{}Ki bytes. If -@code{__far} is used with the M32CM or M32C CPU variants, it has no -effect. - -@subsection RL78 Named Address Spaces -@cindex @code{__far} RL78 Named Address Spaces - -On the RL78 target, variables qualified with @code{__far} are accessed -with 32-bit pointers (20-bit addresses) rather than the default 16-bit -addresses. Non-far variables are assumed to appear in the topmost -64@tie{}KiB of the address space. - -@subsection SPU Named Address Spaces -@cindex @code{__ea} SPU Named Address Spaces - -On the SPU target variables may be declared as -belonging to another address space by qualifying the type with the -@code{__ea} address space identifier: - -@smallexample -extern int __ea i; -@end smallexample - -@noindent -The compiler generates special code to access the variable @code{i}. -It may use runtime library -support, or generate special machine instructions to access that address -space. - -@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 that is really a header for a variable-length -object: - -@smallexample -struct line @{ - int length; - char contents[0]; -@}; - -struct line *thisline = (struct line *) - malloc (sizeof (struct line) + this_length); -thisline->length = this_length; -@end smallexample - -In ISO C90, 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. - -@item -A structure containing a flexible array member, or a union containing -such a structure (possibly recursively), may not be a member of a -structure or an element of an array. (However, these uses are -permitted by GCC as extensions.) -@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. -E.g.@: in the following, @code{f1} is constructed as if it were declared -like @code{f2}. - -@smallexample -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 smallexample - -@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: - -@smallexample -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 smallexample - -@node Empty Structures -@section Structures With No Members -@cindex empty structures -@cindex zero-size structures - -GCC permits a C structure to have no members: - -@smallexample -struct empty @{ -@}; -@end smallexample - -The structure has size zero. In C++, empty structures are part -of the language. G++ treats empty structures as if they had a single -member of type @code{char}. - -@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 C90 mode and in C++. These arrays are -declared like any other automatic arrays, but with a length that is not -a constant expression. The storage is allocated at the point of -declaration and deallocated when the block scope containing the declaration -exits. For -example: - -@smallexample -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 smallexample - -@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 -also deallocates anything more recently allocated with @code{alloca}.) - -You can also use variable-length arrays as arguments to functions: - -@smallexample -struct entry -tester (int len, char data[len][len]) -@{ - /* @r{@dots{}} */ -@} -@end smallexample - -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. - -@smallexample -struct entry -tester (int len; char data[len][len], int len) -@{ - /* @r{@dots{}} */ -@} -@end smallexample - -@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: - -@smallexample -#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) -@end smallexample - -@noindent -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: - -@smallexample -#define debug(format, args...) fprintf (stderr, format, args) -@end smallexample - -@noindent -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: - -@smallexample -debug ("A message") -@end smallexample - -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 - -@smallexample -#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) -@end smallexample - -@noindent -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 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, 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 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, GNU C allows such arrays to be -subscripted in C90 mode, though otherwise they do not decay to -pointers outside C99 mode. For example, -this is valid in GNU C though not valid in C90: - -@smallexample -@group -struct foo @{int a[4];@}; - -struct foo f(); - -bar (int index) -@{ - return f().a[index]; -@} -@end group -@end smallexample - -@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: - -@smallexample -foo (float f, float g) -@{ - float beat_freqs[2] = @{ f-g, f+g @}; - /* @r{@dots{}} */ -@} -@end smallexample - -@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 C90 mode and in C++, though the semantics are -somewhat different in C++. - -Usually, the specified type is a structure. Assume that -@code{struct foo} and @code{structure} are declared as shown: - -@smallexample -struct foo @{int a; char b[2];@} structure; -@end smallexample - -@noindent -Here is an example of constructing a @code{struct foo} with a compound literal: - -@smallexample -structure = ((struct foo) @{x + y, 'a', 0@}); -@end smallexample - -@noindent -This is equivalent to writing the following: - -@smallexample -@{ - struct foo temp = @{x + y, 'a', 0@}; - structure = temp; -@} -@end smallexample - -You can also construct an array, though this is dangerous in C++, as -explained below. 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: - -@smallexample -char **foo = (char *[]) @{ "x", "y", "z" @}; -@end smallexample - -Compound literals for scalar types and union types are -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 is initialized only with the bracket -enclosed list if the types of the compound literal and the object 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. - -@smallexample -static struct foo x = (struct foo) @{1, 'a', 'b'@}; -static int y[] = (int []) @{1, 2, 3@}; -static int z[] = (int [3]) @{1@}; -@end smallexample - -@noindent -The above lines are equivalent to the following: -@smallexample -static struct foo x = @{1, 'a', 'b'@}; -static int y[] = @{1, 2, 3@}; -static int z[] = @{1, 0, 0@}; -@end smallexample - -In C, a compound literal designates an unnamed object with static or -automatic storage duration. In C++, a compound literal designates a -temporary object, which only lives until the end of its -full-expression. As a result, well-defined C code that takes the -address of a subobject of a compound literal can be undefined in C++. -For instance, if the array compound literal example above appeared -inside a function, any subsequent use of @samp{foo} in C++ has -undefined behavior because the lifetime of the array ends after the -declaration of @samp{foo}. As a result, the C++ compiler now rejects -the conversion of a temporary array to a pointer. - -As an optimization, the C++ compiler sometimes gives array compound -literals longer lifetimes: when the array either appears outside a -function or has const-qualified type. If @samp{foo} and its -initializer had elements of @samp{char *const} type rather than -@samp{char *}, or if @samp{foo} were a global variable, the array -would have static storage duration. But it is probably safest just to -avoid the use of array compound literals in code compiled as C++. - -@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 C90 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 C90 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, - -@smallexample -int a[6] = @{ [4] = 29, [2] = 15 @}; -@end smallexample - -@noindent -is equivalent to - -@smallexample -int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; -@end smallexample - -@noindent -The index values must be constant expressions, even if the array being -initialized is automatic. - -An alternative syntax for this that 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, - -@smallexample -int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; -@end smallexample - -@noindent -If the value in it has side-effects, the side-effects 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, - -@smallexample -struct point @{ int x, y; @}; -@end smallexample - -@noindent -the following initialization - -@smallexample -struct point p = @{ .y = yvalue, .x = xvalue @}; -@end smallexample - -@noindent -is equivalent to - -@smallexample -struct point p = @{ xvalue, yvalue @}; -@end smallexample - -Another syntax that has the same meaning, obsolete since GCC 2.5, is -@samp{@var{fieldname}:}, as shown here: - -@smallexample -struct point p = @{ y: yvalue, x: xvalue @}; -@end smallexample - -@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, - -@smallexample -union foo @{ int i; double d; @}; - -union foo f = @{ .d = 4 @}; -@end smallexample - -@noindent -converts 4 to a @code{double} to store it in the union using -the second element. By contrast, casting 4 to type @code{union foo} -stores 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, - -@smallexample -int a[6] = @{ [1] = v1, v2, [4] = v4 @}; -@end smallexample - -@noindent -is equivalent to - -@smallexample -int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; -@end smallexample - -Labeling the elements of an array initializer is especially useful -when the indices are characters or belong to an @code{enum} type. -For example: - -@smallexample -int whitespace[256] - = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, - ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; -@end smallexample - -@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: - -@smallexample -struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; -@end smallexample - -@noindent -If the same field is initialized multiple times, it has the 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 discards them and issues 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: - -@smallexample -case @var{low} ... @var{high}: -@end smallexample - -@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: - -@smallexample -case 'A' ... 'Z': -@end smallexample - -@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: - -@smallexample -case 1 ... 5: -@end smallexample - -@noindent -rather than this: - -@smallexample -case 1...5: -@end smallexample - -@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, 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: - -@smallexample -union foo @{ int i; double d; @}; -int x; -double y; -@end smallexample - -@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: - -@smallexample -union foo u; -/* @r{@dots{}} */ -u = (union foo) x @equiv{} u.i = x -u = (union foo) y @equiv{} u.d = y -@end smallexample - -You can also use the union cast as a function argument: - -@smallexample -void hack (union foo); -/* @r{@dots{}} */ -hack ((union foo) x); -@end smallexample - -@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, GNU C also allows this in -C90 mode. For example, you could do: - -@smallexample -int i; -/* @r{@dots{}} */ -i++; -int j = i + 2; -@end smallexample - -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 return more than once -@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 with non-null pointer 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 -@cindex functions that have different compilation options on the 386 -@cindex functions that have different optimization options -@cindex functions that are dynamically resolved - -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{aligned}, @code{alloc_size}, @code{noreturn}, -@code{returns_twice}, @code{noinline}, @code{noclone}, -@code{always_inline}, @code{flatten}, @code{pure}, @code{const}, -@code{nothrow}, @code{sentinel}, @code{format}, @code{format_arg}, -@code{no_instrument_function}, @code{no_split_stack}, -@code{section}, @code{constructor}, -@code{destructor}, @code{used}, @code{unused}, @code{deprecated}, -@code{weak}, @code{malloc}, @code{alias}, @code{ifunc}, -@code{warn_unused_result}, @code{nonnull}, @code{gnu_inline}, -@code{externally_visible}, @code{hot}, @code{cold}, @code{artificial}, -@code{no_sanitize_address}, @code{no_address_safety_analysis}, -@code{error} and @code{warning}. -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}). - -GCC plugins may provide their own 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 -@c Keep this table alphabetized by attribute name. Treat _ as space. - -@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 () @{ /* @r{Do something.} */; @} -void f () __attribute__ ((weak, alias ("__f"))); -@end smallexample - -@noindent -defines @samp{f} to be a weak alias for @samp{__f}. In C++, the -mangled name for the target must be used. It is an error if @samp{__f} -is not defined in the same translation unit. - -Not all target machines support this attribute. - -@item aligned (@var{alignment}) -@cindex @code{aligned} attribute -This attribute specifies a minimum alignment for the function, -measured in bytes. - -You cannot use this attribute to decrease the alignment of a function, -only to increase it. However, when you explicitly specify a function -alignment this overrides the effect of the -@option{-falign-functions} (@pxref{Optimize Options}) option for this -function. - -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 functions to be aligned up to a -certain maximum alignment. (For some linkers, the maximum supported -alignment may be very very small.) See your linker documentation for -further information. - -The @code{aligned} attribute can also be used for variables and fields -(@pxref{Variable Attributes}.) - -@item alloc_size -@cindex @code{alloc_size} attribute -The @code{alloc_size} attribute is used to tell the compiler that the -function return value points to memory, where the size is given by -one or two of the functions parameters. GCC uses this -information to improve the correctness of @code{__builtin_object_size}. - -The function parameter(s) denoting the allocated size are specified by -one or two integer arguments supplied to the attribute. The allocated size -is either the value of the single function argument specified or the product -of the two function arguments specified. Argument numbering starts at -one. - -For instance, - -@smallexample -void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2))) -void my_realloc(void*, size_t) __attribute__((alloc_size(2))) -@end smallexample - -@noindent -declares that @code{my_calloc} returns memory of the size given by -the product of parameter 1 and 2 and that @code{my_realloc} returns memory -of the size given by parameter 2. - -@item always_inline -@cindex @code{always_inline} function attribute -Generally, functions are not inlined unless optimization is specified. -For functions declared inline, this attribute inlines the function even -if no optimization level is specified. - -@item gnu_inline -@cindex @code{gnu_inline} function attribute -This attribute should be used with a function that is also declared -with the @code{inline} keyword. It directs GCC to treat the function -as if it were defined in gnu90 mode even when compiling in C99 or -gnu99 mode. - -If the function is declared @code{extern}, then this definition of the -function is used only for inlining. In no case is the function -compiled as a standalone function, not even if you take its address -explicitly. Such an address becomes an external reference, as if you -had only declared the function, and had not defined it. This has -almost the effect of a macro. The way to use this is to put a -function definition in a header file with this attribute, and put -another copy of the function, without @code{extern}, in a library -file. The definition in the header file causes most calls to the -function to be inlined. If any uses of the function remain, they -refer to the single copy in the library. Note that the two -definitions of the functions need not be precisely the same, although -if they do not have the same effect your program may behave oddly. - -In C, if the function is neither @code{extern} nor @code{static}, then -the function is compiled as a standalone function, as well as being -inlined where possible. - -This is how GCC traditionally handled functions declared -@code{inline}. Since ISO C99 specifies a different semantics for -@code{inline}, this function attribute is provided as a transition -measure and as a useful feature in its own right. This attribute is -available in GCC 4.1.3 and later. It is available if either of the -preprocessor macros @code{__GNUC_GNU_INLINE__} or -@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline -Function is As Fast As a Macro}. - -In C++, this attribute does not depend on @code{extern} in any way, -but it still requires the @code{inline} keyword to enable its special -behavior. - -@item artificial -@cindex @code{artificial} function attribute -This attribute is useful for small inline wrappers that if possible -should appear during debugging as a unit. Depending on the debug -info format it either means marking the function as artificial -or using the caller location for all instructions within the inlined -body. - -@item bank_switch -@cindex interrupt handler functions -When added to an interrupt handler with the M32C port, causes the -prologue and epilogue to use bank switching to preserve the registers -rather than saving them on the stack. - -@item flatten -@cindex @code{flatten} function attribute -Generally, inlining into a function is limited. For a function marked with -this attribute, every call inside this function is inlined, if possible. -Whether the function itself is considered for inlining depends on its size and -the current inlining parameters. - -@item error ("@var{message}") -@cindex @code{error} function attribute -If this attribute is used on a function declaration and a call to such a function -is not eliminated through dead code elimination or other optimizations, an error -that includes @var{message} is diagnosed. This is useful -for compile-time checking, especially together with @code{__builtin_constant_p} -and inline functions where checking the inline function arguments is not -possible through @code{extern char [(condition) ? 1 : -1];} tricks. -While it is possible to leave the function undefined and thus invoke -a link failure, when using this attribute the problem is diagnosed -earlier and with exact location of the call even in presence of inline -functions or when not emitting debugging information. - -@item warning ("@var{message}") -@cindex @code{warning} function attribute -If this attribute is used on a function declaration and a call to such a function -is not eliminated through dead code elimination or other optimizations, a warning -that includes @var{message} is diagnosed. This is useful -for compile-time checking, especially together with @code{__builtin_constant_p} -and inline functions. While it is possible to define the function with -a message in @code{.gnu.warning*} section, when using this attribute the problem -is diagnosed earlier and with exact location of the call even in presence -of inline functions or when not emitting debugging information. - -@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 pops off the stack space used to -pass arguments. This is -useful to override the effects of the @option{-mrtd} switch. - -@item const -@cindex @code{const} function attribute -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 below, 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 - -@noindent -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 constructor -@itemx destructor -@itemx constructor (@var{priority}) -@itemx destructor (@var{priority}) -@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 ()} completes or @code{exit ()} is -called. Functions with these attributes are useful for -initializing data that is used implicitly during the execution of -the program. - -You may provide an optional integer priority to control the order in -which constructor and destructor functions are run. A constructor -with a smaller priority number runs before a constructor with a larger -priority number; the opposite relationship holds for destructors. So, -if you have a constructor that allocates a resource and a destructor -that deallocates the same resource, both functions typically have the -same priority. The priorities for constructor and destructor -functions are the same as those specified for namespace-scope C++ -objects (@pxref{C++ Attributes}). - -These attributes are not currently implemented for Objective-C@. - -@item deprecated -@itemx deprecated (@var{msg}) -@cindex @code{deprecated} attribute. -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 - -@noindent -results in a warning on line 3 but not line 2. The optional @var{msg} -argument, which must be a string, is printed in the warning if -present. - -The @code{deprecated} attribute can also be used for variables and -types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) - -@item disinterrupt -@cindex @code{disinterrupt} attribute -On Epiphany and MeP targets, this attribute causes the compiler to emit -instructions to disable interrupts for the duration of the given -function. - -@item dllexport -@cindex @code{__declspec(dllexport)} -On Microsoft Windows targets and Symbian OS targets the -@code{dllexport} attribute causes the compiler to provide a global -pointer to a pointer in a DLL, so that it can be referenced with the -@code{dllimport} attribute. On Microsoft Windows targets, the pointer -name is formed by combining @code{_imp__} and the function or variable -name. - -You can use @code{__declspec(dllexport)} as a synonym for -@code{__attribute__ ((dllexport))} for compatibility with other -compilers. - -On systems that support the @code{visibility} attribute, this -attribute also implies ``default'' visibility. It is an error to -explicitly specify any other visibility. - -In previous versions of GCC, the @code{dllexport} attribute was ignored -for inlined functions, unless the @option{-fkeep-inline-functions} flag -had been used. The default behavior now is to emit all dllexported -inline functions; however, this can cause object file-size bloat, in -which case the old behavior can be restored by using -@option{-fno-keep-inline-dllexport}. - -The attribute is also ignored for undefined symbols. - -When applied to C++ classes, the attribute marks defined non-inlined -member functions and static data members as exports. Static consts -initialized in-class are not marked unless they are also defined -out-of-class. - -For Microsoft Windows targets there are alternative methods for -including the symbol in the DLL's export table such as using a -@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using -the @option{--export-all} linker flag. - -@item dllimport -@cindex @code{__declspec(dllimport)} -On Microsoft Windows and Symbian OS targets, the @code{dllimport} -attribute causes the compiler to reference a function or variable via -a global pointer to a pointer that is set up by the DLL exporting the -symbol. The attribute implies @code{extern}. On Microsoft Windows -targets, the pointer name is formed by combining @code{_imp__} and the -function or variable name. - -You can use @code{__declspec(dllimport)} as a synonym for -@code{__attribute__ ((dllimport))} for compatibility with other -compilers. - -On systems that support the @code{visibility} attribute, this -attribute also implies ``default'' visibility. It is an error to -explicitly specify any other visibility. - -Currently, the attribute is ignored for inlined functions. If the -attribute is applied to a symbol @emph{definition}, an error is reported. -If a symbol previously declared @code{dllimport} is later defined, the -attribute is ignored in subsequent references, and a warning is emitted. -The attribute is also overridden by a subsequent declaration as -@code{dllexport}. - -When applied to C++ classes, the attribute marks non-inlined -member functions and static data members as imports. However, the -attribute is ignored for virtual methods to allow creation of vtables -using thunks. - -On the SH Symbian OS target the @code{dllimport} attribute also has -another affect---it can cause the vtable and run-time type information -for a class to be exported. This happens when the class has a -dllimported constructor or a non-inline, non-pure virtual function -and, for either of those two conditions, the class also has an inline -constructor or destructor and has a key function that is defined in -the current translation unit. - -For Microsoft Windows targets the use of the @code{dllimport} -attribute on functions is not necessary, but provides a small -performance benefit by eliminating a thunk in the DLL@. The use of the -@code{dllimport} attribute on imported variables was required on older -versions of the GNU linker, but can now be avoided by passing the -@option{--enable-auto-import} switch to the GNU linker. As with -functions, using the attribute for a variable eliminates a thunk in -the DLL@. - -One drawback to using this attribute is that a pointer to a -@emph{variable} marked as @code{dllimport} cannot be used as a constant -address. However, a pointer to a @emph{function} with the -@code{dllimport} attribute can be used as a constant initializer; in -this case, the address of a stub function in the import lib is -referenced. On Microsoft Windows targets, the attribute can be disabled -for functions by setting the @option{-mnop-fun-dllimport} flag. - -@item eightbit_data -@cindex eight-bit data on the H8/300, H8/300H, and H8S -Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified -variable should be placed into the eight-bit data section. -The compiler generates 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 exception_handler -@cindex exception handler functions on the Blackfin processor -Use this attribute on the Blackfin to indicate that the specified function -is an exception handler. The compiler generates function entry and -exit sequences suitable for use in an exception handler when this -attribute is present. - -@item externally_visible -@cindex @code{externally_visible} attribute. -This attribute, attached to a global variable or function, nullifies -the effect of the @option{-fwhole-program} command-line option, so the -object remains visible outside the current compilation unit. - -If @option{-fwhole-program} is used together with @option{-flto} and -@command{gold} is used as the linker plugin, -@code{externally_visible} attributes are automatically added to functions -(not variable yet due to a current @command{gold} issue) -that are accessed outside of LTO objects according to resolution file -produced by @command{gold}. -For other linkers that cannot generate resolution file, -explicit @code{externally_visible} attributes are still necessary. - -@item far -@cindex functions that handle memory bank switching -On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to -use a calling convention that takes care of switching memory banks when -entering and leaving a function. This calling convention is also the -default when using the @option{-mlong-calls} option. - -On 68HC12 the compiler uses the @code{call} and @code{rtc} instructions -to call and return from a function. - -On 68HC11 the compiler generates a sequence of instructions -to invoke a board-specific routine to switch the memory bank and call the -real function. The board-specific routine simulates a @code{call}. -At the end of a function, it jumps to a board-specific routine -instead of using @code{rts}. The board-specific return routine simulates -the @code{rtc}. - -On MeP targets this causes the compiler to use a calling convention -that assumes the called function is too far away for the built-in -addressing modes. - -@item fast_interrupt -@cindex interrupt handler functions -Use this attribute on the M32C and RX ports to indicate that the specified -function is a fast interrupt handler. This is just like the -@code{interrupt} attribute, except that @code{freit} is used to return -instead of @code{reit}. - -@item fastcall -@cindex functions that pop the argument stack on the 386 -On the Intel 386, the @code{fastcall} attribute causes the compiler to -pass the first argument (if of integral type) in the register ECX and -the second argument (if of integral type) in the register EDX@. Subsequent -and other typed arguments are passed on the stack. The called function -pops the arguments off the stack. If the number of arguments is variable all -arguments are pushed on the stack. - -@item thiscall -@cindex functions that pop the argument stack on the 386 -On the Intel 386, the @code{thiscall} attribute causes the compiler to -pass the first argument (if of integral type) in the register ECX. -Subsequent and other typed arguments are passed on the stack. The called -function pops the arguments off the stack. -If the number of arguments is variable all arguments are pushed on the -stack. -The @code{thiscall} attribute is intended for C++ non-static member functions. -As a GCC extension, this calling convention can be used for C functions -and for static member methods. - -@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 that -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}, -@code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or -@code{strfmon}. (You can also use @code{__printf__}, -@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On -MinGW targets, @code{ms_printf}, @code{ms_scanf}, and -@code{ms_strftime} are also present. -@var{archetype} values such as @code{printf} refer to the formats accepted -by the system's C runtime library, -while values prefixed with @samp{gnu_} always refer -to the formats accepted by the GNU C Library. On Microsoft Windows -targets, values prefixed with @samp{ms_} refer to the formats accepted by the -@file{msvcrt.dll} library. -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. -Since non-static C++ methods have an implicit @code{this} argument, the -arguments of such methods should be counted from two, not one, when -giving values for @var{string-index} and @var{first-to-check}. - -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 -@opindex fno-builtin -The @code{format} attribute allows you to identify your own functions -that take format strings as arguments, so that GCC can check the -calls to these functions for errors. The compiler always (unless -@option{-ffreestanding} or @option{-fno-builtin} 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}. - -For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is -recognized in the same context. Declarations including these format attributes -are parsed for correct syntax, however the result of checking of such format -strings is not yet defined, and is not carried out by this version of the -compiler. - -The target may also provide additional types of format checks. -@xref{Target Format Checks,,Format Checks Specific to Particular -Target Machines}. - -@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 one). Since non-static C++ methods have -an implicit @code{this} argument, the arguments of such methods should -be counted from two. - -The @code{format_arg} attribute allows you to identify your own -functions that 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} or @option{-fno-builtin} -is used. @xref{C Dialect Options,,Options -Controlling C Dialect}. - -For Objective-C dialects, the @code{format-arg} attribute may refer to an -@code{NSString} reference for compatibility with the @code{format} attribute -above. - -The target may also allow additional types in @code{format-arg} attributes. -@xref{Target Format Checks,,Format Checks Specific to Particular -Target Machines}. - -@item function_vector -@cindex calling functions through the function vector on H8/300, M16C, M32C and SH2A processors -Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified -function should be called through the function vector. Calling a -function through the function vector reduces 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 H8S) and shares space with the interrupt vector. - -On SH2A targets, this attribute declares a function to be called using the -TBR relative addressing mode. The argument to this attribute is the entry -number of the same function in a vector table containing all the TBR -relative addressable functions. For correct operation the TBR must be setup -accordingly to point to the start of the vector table before any functions with -this attribute are invoked. Usually a good place to do the initialization is -the startup routine. The TBR relative vector table can have at max 256 function -entries. The jumps to these functions are generated using a SH2A specific, -non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD -from GNU binutils version 2.7 or later for this attribute to work correctly. - -Please refer the example of M16C target, to see the use of this -attribute while declaring a function, - -In an application, for a function being called once, this attribute -saves at least 8 bytes of code; and if other successive calls are being -made to the same function, it saves 2 bytes of code per each of these -calls. - -On M16C/M32C targets, the @code{function_vector} attribute declares a -special page subroutine call function. Use of this attribute reduces -the code size by 2 bytes for each call generated to the -subroutine. The argument to the attribute is the vector number entry -from the special page vector table which contains the 16 low-order -bits of the subroutine's entry address. Each vector table has special -page number (18 to 255) that is used in @code{jsrs} instructions. -Jump addresses of the routines are generated by adding 0x0F0000 (in -case of M16C targets) or 0xFF0000 (in case of M32C targets), to the -2-byte addresses set in the vector table. Therefore you need to ensure -that all the special page vector routines should get mapped within the -address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF -(for M32C). - -In the following example 2 bytes are saved for each call to -function @code{foo}. - -@smallexample -void foo (void) __attribute__((function_vector(0x18))); -void foo (void) -@{ -@} - -void bar (void) -@{ - foo(); -@} -@end smallexample - -If functions are defined in one file and are called in another file, -then be sure to write this declaration in both files. - -This attribute is ignored for R8C target. - -@item ifunc ("@var{resolver}") -@cindex @code{ifunc} attribute -The @code{ifunc} attribute is used to mark a function as an indirect -function using the STT_GNU_IFUNC symbol type extension to the ELF -standard. This allows the resolution of the symbol value to be -determined dynamically at load time, and an optimized version of the -routine can be selected for the particular processor or other system -characteristics determined then. To use this attribute, first define -the implementation functions available, and a resolver function that -returns a pointer to the selected implementation function. The -implementation functions' declarations must match the API of the -function being implemented, the resolver's declaration is be a -function returning pointer to void function returning void: - -@smallexample -void *my_memcpy (void *dst, const void *src, size_t len) -@{ - @dots{} -@} - -static void (*resolve_memcpy (void)) (void) -@{ - return my_memcpy; // we'll just always select this routine -@} -@end smallexample - -@noindent -The exported header file declaring the function the user calls would -contain: - -@smallexample -extern void *memcpy (void *, const void *, size_t); -@end smallexample - -@noindent -allowing the user to call this as a regular function, unaware of the -implementation. Finally, the indirect function needs to be defined in -the same translation unit as the resolver function: - -@smallexample -void *memcpy (void *, const void *, size_t) - __attribute__ ((ifunc ("resolve_memcpy"))); -@end smallexample - -Indirect functions cannot be weak, and require a recent binutils (at -least version 2.20.1), and GNU C library (at least version 2.11.1). - -@item interrupt -@cindex interrupt handler functions -Use this attribute on the ARM, AVR, CR16, Epiphany, M32C, M32R/D, m68k, MeP, MIPS, -RL78, RX and Xstormy16 ports to indicate that the specified function is an -interrupt handler. The compiler generates function entry and exit -sequences suitable for use in an interrupt handler when this attribute -is present. With Epiphany targets it may also generate a special section with -code to initialize the interrupt vector table. - -Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, MicroBlaze, -and SH processors can be specified via the @code{interrupt_handler} attribute. - -Note, on the AVR, the hardware globally disables interrupts when an -interrupt is executed. The first instruction of an interrupt handler -declared with this attribute is a @code{SEI} instruction to -re-enable interrupts. See also the @code{signal} function attribute -that does not insert a @code{SEI} instruction. If both @code{signal} and -@code{interrupt} are specified for the same function, @code{signal} -is silently ignored. - -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 - -@noindent -Permissible values for this parameter are: @code{IRQ}, @code{FIQ}, -@code{SWI}, @code{ABORT} and @code{UNDEF}. - -On ARMv7-M the interrupt type is ignored, and the attribute means the function -may be called with a word-aligned stack pointer. - -On Epiphany targets one or more optional parameters can be added like this: - -@smallexample -void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); -@end smallexample - -Permissible values for these parameters are: @w{@code{reset}}, -@w{@code{software_exception}}, @w{@code{page_miss}}, -@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}}, -@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}. -Multiple parameters indicate that multiple entries in the interrupt -vector table should be initialized for this function, i.e.@: for each -parameter @w{@var{name}}, a jump to the function is emitted in -the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted -entirely, in which case no interrupt vector table entry is provided. - -Note, on Epiphany targets, interrupts are enabled inside the function -unless the @code{disinterrupt} attribute is also specified. - -On Epiphany targets, you can also use the following attribute to -modify the behavior of an interrupt handler: -@table @code -@item forwarder_section -@cindex @code{forwarder_section} attribute -The interrupt handler may be in external memory which cannot be -reached by a branch instruction, so generate a local memory trampoline -to transfer control. The single parameter identifies the section where -the trampoline is placed. -@end table - -The following examples are all valid uses of these attributes on -Epiphany targets: -@smallexample -void __attribute__ ((interrupt)) universal_handler (); -void __attribute__ ((interrupt ("dma1"))) dma1_handler (); -void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); -void __attribute__ ((interrupt ("timer0"), disinterrupt)) - fast_timer_handler (); -void __attribute__ ((interrupt ("dma0, dma1"), forwarder_section ("tramp"))) - external_dma_handler (); -@end smallexample - -On MIPS targets, you can use the following attributes to modify the behavior -of an interrupt handler: -@table @code -@item use_shadow_register_set -@cindex @code{use_shadow_register_set} attribute -Assume that the handler uses a shadow register set, instead of -the main general-purpose registers. - -@item keep_interrupts_masked -@cindex @code{keep_interrupts_masked} attribute -Keep interrupts masked for the whole function. Without this attribute, -GCC tries to reenable interrupts for as much of the function as it can. - -@item use_debug_exception_return -@cindex @code{use_debug_exception_return} attribute -Return using the @code{deret} instruction. Interrupt handlers that don't -have this attribute return using @code{eret} instead. -@end table - -You can use any combination of these attributes, as shown below: -@smallexample -void __attribute__ ((interrupt)) v0 (); -void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); -void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); -void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); -void __attribute__ ((interrupt, use_shadow_register_set, - keep_interrupts_masked)) v4 (); -void __attribute__ ((interrupt, use_shadow_register_set, - use_debug_exception_return)) v5 (); -void __attribute__ ((interrupt, keep_interrupts_masked, - use_debug_exception_return)) v6 (); -void __attribute__ ((interrupt, use_shadow_register_set, - keep_interrupts_masked, - use_debug_exception_return)) v7 (); -@end smallexample - -On RL78, use @code{brk_interrupt} instead of @code{interrupt} for -handlers intended to be used with the @code{BRK} opcode (i.e.@: those -that must end with @code{RETB} instead of @code{RETI}). - -@item interrupt_handler -@cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors -Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to -indicate that the specified function is an interrupt handler. The compiler -generates function entry and exit sequences suitable for use in an -interrupt handler when this attribute is present. - -@item interrupt_thread -@cindex interrupt thread functions on fido -Use this attribute on fido, a subarchitecture of the m68k, to indicate -that the specified function is an interrupt handler that is designed -to run as a thread. The compiler omits generate prologue/epilogue -sequences and replaces the return instruction with a @code{sleep} -instruction. This attribute is available only on fido. - -@item isr -@cindex interrupt service routines on ARM -Use this attribute on ARM to write Interrupt Service Routines. This is an -alias to the @code{interrupt} attribute above. - -@item kspisusp -@cindex User stack pointer in interrupts on the Blackfin -When used together with @code{interrupt_handler}, @code{exception_handler} -or @code{nmi_handler}, code is generated to load the stack pointer -from the USP register in the function prologue. - -@item l1_text -@cindex @code{l1_text} function attribute -This attribute specifies a function to be placed into L1 Instruction -SRAM@. The function is put into a specific section named @code{.l1.text}. -With @option{-mfdpic}, function calls with a such function as the callee -or caller uses inlined PLT. - -@item l2 -@cindex @code{l2} function attribute -On the Blackfin, this attribute specifies a function to be placed into L2 -SRAM. The function is put into a specific section named -@code{.l1.text}. With @option{-mfdpic}, callers of such functions use -an inlined PLT. - -@item leaf -@cindex @code{leaf} function attribute -Calls to external functions with this attribute must return to the current -compilation unit only by return or by exception handling. In particular, leaf -functions are not allowed to call callback function passed to it from the current -compilation unit or directly call functions exported by the unit or longjmp -into the unit. Leaf function might still call functions from other compilation -units and thus they are not necessarily leaf in the sense that they contain no -function calls at all. - -The attribute is intended for library functions to improve dataflow analysis. -The compiler takes the hint that any data not escaping the current compilation unit can -not be used or modified by the leaf function. For example, the @code{sin} function -is a leaf function, but @code{qsort} is not. - -Note that leaf functions might invoke signals and signal handlers might be -defined in the current compilation unit and use static variables. The only -compliant way to write such a signal handler is to declare such variables -@code{volatile}. - -The attribute has no effect on functions defined within the current compilation -unit. This is to allow easy merging of multiple compilation units into one, -for example, by using the link-time optimization. For this reason the -attribute is not allowed on types to annotate indirect calls. - -@item long_call/short_call -@cindex indirect calls on ARM -This attribute specifies how a particular function is called on -ARM and Epiphany. Both attributes override the -@option{-mlong-calls} (@pxref{ARM Options}) -command-line switch and @code{#pragma long_calls} settings. The -@code{long_call} attribute indicates that the function might be far -away from the call site and require a different (more expensive) -calling sequence. The @code{short_call} attribute always places -the offset to the function from the call site into the @samp{BL} -instruction directly. - -@item longcall/shortcall -@cindex functions called via pointer on the RS/6000 and PowerPC -On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute -indicates that the function might be far away from the call site and -require a different (more expensive) calling sequence. The -@code{shortcall} attribute indicates that the function is always close -enough for the shorter calling sequence to be used. These attributes -override both the @option{-mlongcall} switch and, on the RS/6000 and -PowerPC, the @code{#pragma longcall} setting. - -@xref{RS/6000 and PowerPC Options}, for more information on whether long -calls are necessary. - -@item long_call/near/far -@cindex indirect calls on MIPS -These attributes specify how a particular function is called on MIPS@. -The attributes override the @option{-mlong-calls} (@pxref{MIPS Options}) -command-line switch. The @code{long_call} and @code{far} attributes are -synonyms, and cause 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{near} attribute has the opposite -effect; it specifies that non-PIC calls should be made using the more -efficient @code{jal} instruction. - -@item malloc -@cindex @code{malloc} attribute -The @code{malloc} attribute is used to tell the compiler that a function -may be treated as if any non-@code{NULL} pointer it returns cannot -alias any other pointer valid when the function returns and that the memory -has undefined content. -This often improves optimization. -Standard functions with this property include @code{malloc} and -@code{calloc}. @code{realloc}-like functions do not have this -property as the memory pointed to does not have undefined content. - -@item mips16/nomips16 -@cindex @code{mips16} attribute -@cindex @code{nomips16} attribute - -On MIPS targets, you can use the @code{mips16} and @code{nomips16} -function attributes to locally select or turn off MIPS16 code generation. -A function with the @code{mips16} attribute is emitted as MIPS16 code, -while MIPS16 code generation is disabled for functions with the -@code{nomips16} attribute. These attributes override the -@option{-mips16} and @option{-mno-mips16} options on the command line -(@pxref{MIPS Options}). - -When compiling files containing mixed MIPS16 and non-MIPS16 code, the -preprocessor symbol @code{__mips16} reflects the setting on the command line, -not that within individual functions. Mixed MIPS16 and non-MIPS16 code -may interact badly with some GCC extensions such as @code{__builtin_apply} -(@pxref{Constructing Calls}). - -@item model (@var{model-name}) -@cindex function addressability on the M32R/D -@cindex variable addressability on the IA-64 - -On the M32R/D, use this attribute to set the addressability of an -object, and of 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 generates @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 generates @code{seth/add3} instructions to load their addresses), -and may not be reachable with the @code{bl} instruction (the compiler -generates the much slower @code{seth/add3/jl} instruction sequence). - -On IA-64, use this attribute to set the addressability of an object. -At present, the only supported identifier for @var{model-name} is -@code{small}, indicating addressability via ``small'' (22-bit) -addresses (so that their addresses can be loaded with the @code{addl} -instruction). Caveat: such addressing is by definition not position -independent and hence this attribute must not be used for objects -defined by shared libraries. - -@item ms_abi/sysv_abi -@cindex @code{ms_abi} attribute -@cindex @code{sysv_abi} attribute - -On 32-bit and 64-bit (i?86|x86_64)-*-* targets, you can use an ABI attribute -to indicate which calling convention should be used for a function. The -@code{ms_abi} attribute tells the compiler to use the Microsoft ABI, -while the @code{sysv_abi} attribute tells the compiler to use the ABI -used on GNU/Linux and other systems. The default is to use the Microsoft ABI -when targeting Windows. On all other systems, the default is the x86/AMD ABI. - -Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently -requires the @option{-maccumulate-outgoing-args} option. - -@item callee_pop_aggregate_return (@var{number}) -@cindex @code{callee_pop_aggregate_return} attribute - -On 32-bit i?86-*-* targets, you can use this attribute to control how -aggregates are returned in memory. If the caller is responsible for -popping the hidden pointer together with the rest of the arguments, specify -@var{number} equal to zero. If callee is responsible for popping the -hidden pointer, specify @var{number} equal to one. - -The default i386 ABI assumes that the callee pops the -stack for hidden pointer. However, on 32-bit i386 Microsoft Windows targets, -the compiler assumes that the -caller pops the stack for hidden pointer. - -@item ms_hook_prologue -@cindex @code{ms_hook_prologue} attribute - -On 32-bit i[34567]86-*-* targets and 64-bit x86_64-*-* targets, you can use -this function attribute to make GCC generate the ``hot-patching'' function -prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 -and newer. - -@item naked -@cindex function without a prologue/epilogue code -Use this attribute on the ARM, AVR, MCORE, RX and SPU ports to indicate that -the specified function does not need prologue/epilogue sequences generated by -the compiler. It is up to the programmer to provide these sequences. The -only statements that can be safely included in naked functions are -@code{asm} statements that do not have operands. All other statements, -including declarations of local variables, @code{if} statements, and so -forth, should be avoided. Naked functions should be used to implement the -body of an assembly function, while allowing the compiler to construct -the requisite function declaration for the assembler. - -@item near -@cindex functions that do not handle memory bank switching on 68HC11/68HC12 -On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to -use the normal calling convention based on @code{jsr} and @code{rts}. -This attribute can be used to cancel the effect of the @option{-mlong-calls} -option. - -On MeP targets this attribute causes the compiler to assume the called -function is close enough to use the normal calling convention, -overriding the @option{-mtf} command-line option. - -@item nesting -@cindex Allow nesting in an interrupt handler on the Blackfin processor. -Use this attribute together with @code{interrupt_handler}, -@code{exception_handler} or @code{nmi_handler} to indicate that the function -entry code should enable nested interrupts or exceptions. - -@item nmi_handler -@cindex NMI handler functions on the Blackfin processor -Use this attribute on the Blackfin to indicate that the specified function -is an NMI handler. The compiler generates function entry and -exit sequences suitable for use in an NMI handler when this -attribute is present. - -@item no_instrument_function -@cindex @code{no_instrument_function} function attribute -@opindex finstrument-functions -If @option{-finstrument-functions} is given, profiling function calls are -generated at entry and exit of most user-compiled functions. -Functions with this attribute are not so instrumented. - -@item no_split_stack -@cindex @code{no_split_stack} function attribute -@opindex fsplit-stack -If @option{-fsplit-stack} is given, functions have a small -prologue which decides whether to split the stack. Functions with the -@code{no_split_stack} attribute do not have that prologue, and thus -may run with only a small amount of stack space available. - -@item noinline -@cindex @code{noinline} function attribute -This function attribute prevents a function from being considered for -inlining. -@c Don't enumerate the optimizations by name here; we try to be -@c future-compatible with this mechanism. -If the function does not have side-effects, there are optimizations -other than inlining that cause function calls to be optimized away, -although the function call is live. To keep such calls from being -optimized away, put -@smallexample -asm (""); -@end smallexample - -@noindent -(@pxref{Extended Asm}) in the called function, to serve as a special -side-effect. - -@item noclone -@cindex @code{noclone} function attribute -This function attribute prevents a function from being considered for -cloning---a mechanism that produces specialized copies of functions -and which is (currently) performed by interprocedural constant -propagation. - -@item nonnull (@var{arg-index}, @dots{}) -@cindex @code{nonnull} function attribute -The @code{nonnull} attribute specifies that some function parameters should -be non-null pointers. For instance, the declaration: - -@smallexample -extern void * -my_memcpy (void *dest, const void *src, size_t len) - __attribute__((nonnull (1, 2))); -@end smallexample - -@noindent -causes the compiler to check that, in calls to @code{my_memcpy}, -arguments @var{dest} and @var{src} are non-null. If the compiler -determines that a null pointer is passed in an argument slot marked -as non-null, and the @option{-Wnonnull} option is enabled, a warning -is issued. The compiler may also choose to make optimizations based -on the knowledge that certain function arguments will never be null. - -If no argument index list is given to the @code{nonnull} attribute, -all pointer arguments are marked as non-null. To illustrate, the -following declaration is equivalent to the previous example: - -@smallexample -extern void * -my_memcpy (void *dest, const void *src, size_t len) - __attribute__((nonnull)); -@end smallexample - -@item noreturn -@cindex @code{noreturn} function attribute -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 (/* @r{@dots{}} */) -@{ - /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@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. - -The @code{noreturn} keyword does not affect the exceptional path when that -applies: a @code{noreturn}-marked function may still return to the caller -by throwing an exception or calling @code{longjmp}. - -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 - -@noindent -This approach does not work in GNU C++. - -@item nothrow -@cindex @code{nothrow} function attribute -The @code{nothrow} attribute is used to inform the compiler that a -function cannot throw an exception. For example, most functions in -the standard C library can be guaranteed not to throw an exception -with the notable exceptions of @code{qsort} and @code{bsearch} that -take function pointer arguments. The @code{nothrow} attribute is not -implemented in GCC versions earlier than 3.3. - -@item nosave_low_regs -@cindex @code{nosave_low_regs} attribute -Use this attribute on SH targets to indicate that an @code{interrupt_handler} -function should not save and restore registers R0..R7. This can be used on SH3* -and SH4* targets that have a second R0..R7 register bank for non-reentrant -interrupt handlers. - -@item optimize -@cindex @code{optimize} function attribute -The @code{optimize} attribute is used to specify that a function is to -be compiled with different optimization options than specified on the -command line. Arguments can either be numbers or strings. Numbers -are assumed to be an optimization level. Strings that begin with -@code{O} are assumed to be an optimization option, while other options -are assumed to be used with a @code{-f} prefix. You can also use the -@samp{#pragma GCC optimize} pragma to set the optimization options -that affect more than one function. -@xref{Function Specific Option Pragmas}, for details about the -@samp{#pragma GCC optimize} pragma. - -This can be used for instance to have frequently-executed functions -compiled with more aggressive optimization options that produce faster -and larger code, while other functions can be compiled with less -aggressive options. - -@item OS_main/OS_task -@cindex @code{OS_main} AVR function attribute -@cindex @code{OS_task} AVR function attribute -On AVR, functions with the @code{OS_main} or @code{OS_task} attribute -do not save/restore any call-saved register in their prologue/epilogue. - -The @code{OS_main} attribute can be used when there @emph{is -guarantee} that interrupts are disabled at the time when the function -is entered. This saves resources when the stack pointer has to be -changed to set up a frame for local variables. - -The @code{OS_task} attribute can be used when there is @emph{no -guarantee} that interrupts are disabled at that time when the function -is entered like for, e@.g@. task functions in a multi-threading operating -system. In that case, changing the stack pointer register is -guarded by save/clear/restore of the global interrupt enable flag. - -The differences to the @code{naked} function attribute are: -@itemize @bullet -@item @code{naked} functions do not have a return instruction whereas -@code{OS_main} and @code{OS_task} functions have a @code{RET} or -@code{RETI} return instruction. -@item @code{naked} functions do not set up a frame for local variables -or a frame pointer whereas @code{OS_main} and @code{OS_task} do this -as needed. -@end itemize - -@item pcs -@cindex @code{pcs} function attribute - -The @code{pcs} attribute can be used to control the calling convention -used for a function on ARM. The attribute takes an argument that specifies -the calling convention to use. - -When compiling using the AAPCS ABI (or a variant of it) then valid -values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In -order to use a variant other than @code{"aapcs"} then the compiler must -be permitted to use the appropriate co-processor registers (i.e., the -VFP registers must be available in order to use @code{"aapcs-vfp"}). -For example, - -@smallexample -/* Argument passed in r0, and result returned in r0+r1. */ -double f2d (float) __attribute__((pcs("aapcs"))); -@end smallexample - -Variadic functions always use the @code{"aapcs"} calling convention and -the compiler rejects attempts to specify an alternative. - -@item pure -@cindex @code{pure} function attribute -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. - -@item hot -@cindex @code{hot} function attribute -The @code{hot} attribute on a function is used to inform the compiler that -the function is a hot spot of the compiled program. The function is -optimized more aggressively and on many target it is placed into special -subsection of the text section so all hot functions appears close together -improving locality. - -When profile feedback is available, via @option{-fprofile-use}, hot functions -are automatically detected and this attribute is ignored. - -The @code{hot} attribute on functions is not implemented in GCC versions -earlier than 4.3. - -@cindex @code{hot} label attribute -The @code{hot} attribute on a label is used to inform the compiler that -path following the label are more likely than paths that are not so -annotated. This attribute is used in cases where @code{__builtin_expect} -cannot be used, for instance with computed goto or @code{asm goto}. - -The @code{hot} attribute on labels is not implemented in GCC versions -earlier than 4.8. - -@item cold -@cindex @code{cold} function attribute -The @code{cold} attribute on functions is used to inform the compiler that -the function is unlikely to be executed. The function is optimized for -size rather than speed and on many targets it is placed into special -subsection of the text section so all cold functions appears close together -improving code locality of non-cold parts of program. The paths leading -to call of cold functions within code are marked as unlikely by the branch -prediction mechanism. It is thus useful to mark functions used to handle -unlikely conditions, such as @code{perror}, as cold to improve optimization -of hot functions that do call marked functions in rare occasions. - -When profile feedback is available, via @option{-fprofile-use}, cold functions -are automatically detected and this attribute is ignored. - -The @code{cold} attribute on functions is not implemented in GCC versions -earlier than 4.3. - -@cindex @code{cold} label attribute -The @code{cold} attribute on labels is used to inform the compiler that -the path following the label is unlikely to be executed. This attribute -is used in cases where @code{__builtin_expect} cannot be used, for instance -with computed goto or @code{asm goto}. - -The @code{cold} attribute on labels is not implemented in GCC versions -earlier than 4.8. - -@item no_sanitize_address -@itemx no_address_safety_analysis -@cindex @code{no_sanitize_address} function attribute -The @code{no_sanitize_address} attribute on functions is used -to inform the compiler that it should not instrument memory accesses -in the function when compiling with the @option{-fsanitize=address} option. -The @code{no_address_safety_analysis} is a deprecated alias of the -@code{no_sanitize_address} attribute, new code should use -@code{no_sanitize_address}. - -@item regparm (@var{number}) -@cindex @code{regparm} attribute -@cindex functions that are passed arguments in registers on the 386 -On the Intel 386, the @code{regparm} attribute causes the compiler to -pass arguments number one to @var{number} if they are of integral type -in registers EAX, EDX, and ECX instead of on the stack. Functions that -take a variable number of arguments continue to be passed all of their -arguments on the stack. - -Beware that on some ELF systems this attribute is unsuitable for -global functions in shared libraries with lazy binding (which is the -default). Lazy binding sends the first call via resolving code in -the loader, which might assume EAX, EDX and ECX can be clobbered, as -per the standard calling conventions. Solaris 8 is affected by this. -Systems with the GNU C Library version 2.1 or higher -and FreeBSD are believed to be -safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be -disabled with the linker or the loader if desired, to avoid the -problem.) - -@item sseregparm -@cindex @code{sseregparm} attribute -On the Intel 386 with SSE support, the @code{sseregparm} attribute -causes the compiler to pass up to 3 floating-point arguments in -SSE registers instead of on the stack. Functions that take a -variable number of arguments continue to pass all of their -floating-point arguments on the stack. - -@item force_align_arg_pointer -@cindex @code{force_align_arg_pointer} attribute -On the Intel x86, the @code{force_align_arg_pointer} attribute may be -applied to individual function definitions, generating an alternate -prologue and epilogue that realigns the run-time stack if necessary. -This supports mixing legacy codes that run with a 4-byte aligned stack -with modern codes that keep a 16-byte stack for SSE compatibility. - -@item renesas -@cindex @code{renesas} attribute -On SH targets this attribute specifies that the function or struct follows the -Renesas ABI. - -@item resbank -@cindex @code{resbank} attribute -On the SH2A target, this attribute enables the high-speed register -saving and restoration using a register bank for @code{interrupt_handler} -routines. Saving to the bank is performed automatically after the CPU -accepts an interrupt that uses a register bank. - -The nineteen 32-bit registers comprising general register R0 to R14, -control register GBR, and system registers MACH, MACL, and PR and the -vector table address offset are saved into a register bank. Register -banks are stacked in first-in last-out (FILO) sequence. Restoration -from the bank is executed by issuing a RESBANK instruction. - -@item returns_twice -@cindex @code{returns_twice} attribute -The @code{returns_twice} attribute tells the compiler that a function may -return more than one time. The compiler ensures that all registers -are dead before calling such a function and emits a warning about -the variables that may be clobbered after the second return from the -function. Examples of such functions are @code{setjmp} and @code{vfork}. -The @code{longjmp}-like counterpart of such function, if any, might need -to be marked with the @code{noreturn} attribute. - -@item saveall -@cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S -Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that -all registers except the stack pointer should be saved in the prologue -regardless of whether they are used or not. - -@item save_volatiles -@cindex save volatile registers on the MicroBlaze -Use this attribute on the MicroBlaze to indicate that the function is -an interrupt handler. All volatile registers (in addition to non-volatile -registers) are saved in the function prologue. If the function is a leaf -function, only volatiles used by the function are saved. A normal function -return is generated instead of a return from interrupt. - -@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 sentinel -@cindex @code{sentinel} function attribute -This function attribute ensures that a parameter in a function call is -an explicit @code{NULL}. The attribute is only valid on variadic -functions. By default, the sentinel is located at position zero, the -last parameter of the function call. If an optional integer position -argument P is supplied to the attribute, the sentinel must be located at -position P counting backwards from the end of the argument list. - -@smallexample -__attribute__ ((sentinel)) -is equivalent to -__attribute__ ((sentinel(0))) -@end smallexample - -The attribute is automatically set with a position of 0 for the built-in -functions @code{execl} and @code{execlp}. The built-in function -@code{execle} has the attribute set with a position of 1. - -A valid @code{NULL} in this context is defined as zero with any pointer -type. If your system defines the @code{NULL} macro with an integer type -then you need to add an explicit cast. GCC replaces @code{stddef.h} -with a copy that redefines NULL appropriately. - -The warnings for missing or incorrect sentinels are enabled with -@option{-Wformat}. - -@item short_call -See @code{long_call/short_call}. - -@item shortcall -See @code{longcall/shortcall}. - -@item signal -@cindex interrupt handler functions on the AVR processors -Use this attribute on the AVR to indicate that the specified -function is an interrupt handler. The compiler generates function -entry and exit sequences suitable for use in an interrupt handler when this -attribute is present. - -See also the @code{interrupt} function attribute. - -The AVR hardware globally disables interrupts when an interrupt is executed. -Interrupt handler functions defined with the @code{signal} attribute -do not re-enable interrupts. It is save to enable interrupts in a -@code{signal} handler. This ``save'' only applies to the code -generated by the compiler and not to the IRQ layout of the -application which is responsibility of the application. - -If both @code{signal} and @code{interrupt} are specified for the same -function, @code{signal} is silently ignored. - -@item sp_switch -@cindex @code{sp_switch} attribute -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 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 pops off the stack space used to -pass arguments, unless it takes a variable number of arguments. - -@item syscall_linkage -@cindex @code{syscall_linkage} attribute -This attribute is used to modify the IA-64 calling convention by marking -all input registers as live at all function exits. This makes it possible -to restart a system call after an interrupt without having to save/restore -the input registers. This also prevents kernel data from leaking into -application code. - -@item target -@cindex @code{target} function attribute -The @code{target} attribute is used to specify that a function is to -be compiled with different target options than specified on the -command line. This can be used for instance to have functions -compiled with a different ISA (instruction set architecture) than the -default. You can also use the @samp{#pragma GCC target} pragma to set -more than one function to be compiled with specific target options. -@xref{Function Specific Option Pragmas}, for details about the -@samp{#pragma GCC target} pragma. - -For instance on a 386, you could compile one function with -@code{target("sse4.1,arch=core2")} and another with -@code{target("sse4a,arch=amdfam10")}. This is equivalent to -compiling the first function with @option{-msse4.1} and -@option{-march=core2} options, and the second function with -@option{-msse4a} and @option{-march=amdfam10} options. It is up to the -user to make sure that a function is only invoked on a machine that -supports the particular ISA it is compiled for (for example by using -@code{cpuid} on 386 to determine what feature bits and architecture -family are used). - -@smallexample -int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); -int sse3_func (void) __attribute__ ((__target__ ("sse3"))); -@end smallexample - -On the 386, the following options are allowed: - -@table @samp -@item abm -@itemx no-abm -@cindex @code{target("abm")} attribute -Enable/disable the generation of the advanced bit instructions. - -@item aes -@itemx no-aes -@cindex @code{target("aes")} attribute -Enable/disable the generation of the AES instructions. - -@item default -@cindex @code{target("default")} attribute -@xref{Function Multiversioning}, where it is used to specify the -default function version. - -@item mmx -@itemx no-mmx -@cindex @code{target("mmx")} attribute -Enable/disable the generation of the MMX instructions. - -@item pclmul -@itemx no-pclmul -@cindex @code{target("pclmul")} attribute -Enable/disable the generation of the PCLMUL instructions. - -@item popcnt -@itemx no-popcnt -@cindex @code{target("popcnt")} attribute -Enable/disable the generation of the POPCNT instruction. - -@item sse -@itemx no-sse -@cindex @code{target("sse")} attribute -Enable/disable the generation of the SSE instructions. - -@item sse2 -@itemx no-sse2 -@cindex @code{target("sse2")} attribute -Enable/disable the generation of the SSE2 instructions. - -@item sse3 -@itemx no-sse3 -@cindex @code{target("sse3")} attribute -Enable/disable the generation of the SSE3 instructions. - -@item sse4 -@itemx no-sse4 -@cindex @code{target("sse4")} attribute -Enable/disable the generation of the SSE4 instructions (both SSE4.1 -and SSE4.2). - -@item sse4.1 -@itemx no-sse4.1 -@cindex @code{target("sse4.1")} attribute -Enable/disable the generation of the sse4.1 instructions. - -@item sse4.2 -@itemx no-sse4.2 -@cindex @code{target("sse4.2")} attribute -Enable/disable the generation of the sse4.2 instructions. - -@item sse4a -@itemx no-sse4a -@cindex @code{target("sse4a")} attribute -Enable/disable the generation of the SSE4A instructions. - -@item fma4 -@itemx no-fma4 -@cindex @code{target("fma4")} attribute -Enable/disable the generation of the FMA4 instructions. - -@item xop -@itemx no-xop -@cindex @code{target("xop")} attribute -Enable/disable the generation of the XOP instructions. - -@item lwp -@itemx no-lwp -@cindex @code{target("lwp")} attribute -Enable/disable the generation of the LWP instructions. - -@item ssse3 -@itemx no-ssse3 -@cindex @code{target("ssse3")} attribute -Enable/disable the generation of the SSSE3 instructions. - -@item cld -@itemx no-cld -@cindex @code{target("cld")} attribute -Enable/disable the generation of the CLD before string moves. - -@item fancy-math-387 -@itemx no-fancy-math-387 -@cindex @code{target("fancy-math-387")} attribute -Enable/disable the generation of the @code{sin}, @code{cos}, and -@code{sqrt} instructions on the 387 floating-point unit. - -@item fused-madd -@itemx no-fused-madd -@cindex @code{target("fused-madd")} attribute -Enable/disable the generation of the fused multiply/add instructions. - -@item ieee-fp -@itemx no-ieee-fp -@cindex @code{target("ieee-fp")} attribute -Enable/disable the generation of floating point that depends on IEEE arithmetic. - -@item inline-all-stringops -@itemx no-inline-all-stringops -@cindex @code{target("inline-all-stringops")} attribute -Enable/disable inlining of string operations. - -@item inline-stringops-dynamically -@itemx no-inline-stringops-dynamically -@cindex @code{target("inline-stringops-dynamically")} attribute -Enable/disable the generation of the inline code to do small string -operations and calling the library routines for large operations. - -@item align-stringops -@itemx no-align-stringops -@cindex @code{target("align-stringops")} attribute -Do/do not align destination of inlined string operations. - -@item recip -@itemx no-recip -@cindex @code{target("recip")} attribute -Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS -instructions followed an additional Newton-Raphson step instead of -doing a floating-point division. - -@item arch=@var{ARCH} -@cindex @code{target("arch=@var{ARCH}")} attribute -Specify the architecture to generate code for in compiling the function. - -@item tune=@var{TUNE} -@cindex @code{target("tune=@var{TUNE}")} attribute -Specify the architecture to tune for in compiling the function. - -@item fpmath=@var{FPMATH} -@cindex @code{target("fpmath=@var{FPMATH}")} attribute -Specify which floating-point unit to use. The -@code{target("fpmath=sse,387")} option must be specified as -@code{target("fpmath=sse+387")} because the comma would separate -different options. -@end table - -On the PowerPC, the following options are allowed: - -@table @samp -@item altivec -@itemx no-altivec -@cindex @code{target("altivec")} attribute -Generate code that uses (does not use) AltiVec instructions. In -32-bit code, you cannot enable AltiVec instructions unless -@option{-mabi=altivec} is used on the command line. - -@item cmpb -@itemx no-cmpb -@cindex @code{target("cmpb")} attribute -Generate code that uses (does not use) the compare bytes instruction -implemented on the POWER6 processor and other processors that support -the PowerPC V2.05 architecture. - -@item dlmzb -@itemx no-dlmzb -@cindex @code{target("dlmzb")} attribute -Generate code that uses (does not use) the string-search @samp{dlmzb} -instruction on the IBM 405, 440, 464 and 476 processors. This instruction is -generated by default when targeting those processors. - -@item fprnd -@itemx no-fprnd -@cindex @code{target("fprnd")} attribute -Generate code that uses (does not use) the FP round to integer -instructions implemented on the POWER5+ processor and other processors -that support the PowerPC V2.03 architecture. - -@item hard-dfp -@itemx no-hard-dfp -@cindex @code{target("hard-dfp")} attribute -Generate code that uses (does not use) the decimal floating-point -instructions implemented on some POWER processors. - -@item isel -@itemx no-isel -@cindex @code{target("isel")} attribute -Generate code that uses (does not use) ISEL instruction. - -@item mfcrf -@itemx no-mfcrf -@cindex @code{target("mfcrf")} attribute -Generate code that uses (does not use) the move from condition -register field instruction implemented on the POWER4 processor and -other processors that support the PowerPC V2.01 architecture. - -@item mfpgpr -@itemx no-mfpgpr -@cindex @code{target("mfpgpr")} attribute -Generate code that uses (does not use) the FP move to/from general -purpose register instructions implemented on the POWER6X processor and -other processors that support the extended PowerPC V2.05 architecture. - -@item mulhw -@itemx no-mulhw -@cindex @code{target("mulhw")} attribute -Generate code that uses (does not use) the half-word multiply and -multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. -These instructions are generated by default when targeting those -processors. - -@item multiple -@itemx no-multiple -@cindex @code{target("multiple")} attribute -Generate code that uses (does not use) the load multiple word -instructions and the store multiple word instructions. - -@item update -@itemx no-update -@cindex @code{target("update")} attribute -Generate code that uses (does not use) the load or store instructions -that update the base register to the address of the calculated memory -location. - -@item popcntb -@itemx no-popcntb -@cindex @code{target("popcntb")} attribute -Generate code that uses (does not use) the popcount and double-precision -FP reciprocal estimate instruction implemented on the POWER5 -processor and other processors that support the PowerPC V2.02 -architecture. - -@item popcntd -@itemx no-popcntd -@cindex @code{target("popcntd")} attribute -Generate code that uses (does not use) the popcount instruction -implemented on the POWER7 processor and other processors that support -the PowerPC V2.06 architecture. - -@item powerpc-gfxopt -@itemx no-powerpc-gfxopt -@cindex @code{target("powerpc-gfxopt")} attribute -Generate code that uses (does not use) the optional PowerPC -architecture instructions in the Graphics group, including -floating-point select. - -@item powerpc-gpopt -@itemx no-powerpc-gpopt -@cindex @code{target("powerpc-gpopt")} attribute -Generate code that uses (does not use) the optional PowerPC -architecture instructions in the General Purpose group, including -floating-point square root. - -@item recip-precision -@itemx no-recip-precision -@cindex @code{target("recip-precision")} attribute -Assume (do not assume) that the reciprocal estimate instructions -provide higher-precision estimates than is mandated by the powerpc -ABI. - -@item string -@itemx no-string -@cindex @code{target("string")} attribute -Generate code that uses (does not use) the load string instructions -and the store string word instructions to save multiple registers and -do small block moves. - -@item vsx -@itemx no-vsx -@cindex @code{target("vsx")} attribute -Generate code that uses (does not use) vector/scalar (VSX) -instructions, and also enable the use of built-in functions that allow -more direct access to the VSX instruction set. In 32-bit code, you -cannot enable VSX or AltiVec instructions unless -@option{-mabi=altivec} is used on the command line. - -@item friz -@itemx no-friz -@cindex @code{target("friz")} attribute -Generate (do not generate) the @code{friz} instruction when the -@option{-funsafe-math-optimizations} option is used to optimize -rounding a floating-point value to 64-bit integer and back to floating -point. The @code{friz} instruction does not return the same value if -the floating-point number is too large to fit in an integer. - -@item avoid-indexed-addresses -@itemx no-avoid-indexed-addresses -@cindex @code{target("avoid-indexed-addresses")} attribute -Generate code that tries to avoid (not avoid) the use of indexed load -or store instructions. - -@item paired -@itemx no-paired -@cindex @code{target("paired")} attribute -Generate code that uses (does not use) the generation of PAIRED simd -instructions. - -@item longcall -@itemx no-longcall -@cindex @code{target("longcall")} attribute -Generate code that assumes (does not assume) that all calls are far -away so that a longer more expensive calling sequence is required. - -@item cpu=@var{CPU} -@cindex @code{target("cpu=@var{CPU}")} attribute -Specify the architecture to generate code for when compiling the -function. If you select the @code{target("cpu=power7")} attribute when -generating 32-bit code, VSX and AltiVec instructions are not generated -unless you use the @option{-mabi=altivec} option on the command line. - -@item tune=@var{TUNE} -@cindex @code{target("tune=@var{TUNE}")} attribute -Specify the architecture to tune for when compiling the function. If -you do not specify the @code{target("tune=@var{TUNE}")} attribute and -you do specify the @code{target("cpu=@var{CPU}")} attribute, -compilation tunes for the @var{CPU} architecture, and not the -default tuning specified on the command line. -@end table - -On the 386/x86_64 and PowerPC back ends, you can use either multiple -strings to specify multiple options, or you can separate the option -with a comma (@code{,}). - -On the 386/x86_64 and PowerPC back ends, the inliner does not inline a -function that has different target options than the caller, unless the -callee has a subset of the target options of the caller. For example -a function declared with @code{target("sse3")} can inline a function -with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}. - -The @code{target} attribute is not implemented in GCC versions earlier -than 4.4 for the i386/x86_64 and 4.6 for the PowerPC back ends. It is -not currently implemented for other back ends. - -@item tiny_data -@cindex tiny data section on the H8/300H and H8S -Use this attribute on the H8/300H and H8S to indicate that the specified -variable should be placed into the tiny data section. -The compiler generates more efficient code for loads and stores -on data in the tiny data section. Note the tiny data area is limited to -slightly under 32KB of data. - -@item trap_exit -@cindex @code{trap_exit} attribute -Use this attribute on the SH for an @code{interrupt_handler} to return using -@code{trapa} instead of @code{rte}. This attribute expects an integer -argument specifying the trap number to be used. - -@item trapa_handler -@cindex @code{trapa_handler} attribute -On SH targets this function attribute is similar to @code{interrupt_handler} -but it does not save and restore all registers. - -@item unused -@cindex @code{unused} attribute. -This attribute, attached to a function, means that the function is meant -to be possibly unused. GCC does not produce a warning for this -function. - -@item used -@cindex @code{used} attribute. -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. - -When applied to a member function of a C++ class template, the -attribute also means that the function is instantiated if the -class itself is instantiated. - -@item version_id -@cindex @code{version_id} attribute -This IA-64 HP-UX attribute, attached to a global variable or function, renames a -symbol to contain a version string, thus allowing for function level -versioning. HP-UX system header files may use version level functioning -for some system calls. - -@smallexample -extern int foo () __attribute__((version_id ("20040821"))); -@end smallexample - -@noindent -Calls to @var{foo} are mapped to calls to @var{foo@{20040821@}}. - -@item visibility ("@var{visibility_type}") -@cindex @code{visibility} attribute -This attribute affects the linkage of the declaration to which it is attached. -There are four supported @var{visibility_type} values: default, -hidden, protected or internal visibility. - -@smallexample -void __attribute__ ((visibility ("protected"))) -f () @{ /* @r{Do something.} */; @} -int i __attribute__ ((visibility ("hidden"))); -@end smallexample - -The possible values of @var{visibility_type} correspond to the -visibility settings in the ELF gABI. - -@table @dfn -@c keep this list of visibilities in alphabetical order. - -@item default -Default visibility is the normal case for the object file format. -This value is available for the visibility attribute to override other -options that may change the assumed visibility of entities. - -On ELF, default visibility means that the declaration is visible to other -modules and, in shared libraries, means that the declared entity may be -overridden. - -On Darwin, default visibility means that the declaration is visible to -other modules. - -Default visibility corresponds to ``external linkage'' in the language. - -@item hidden -Hidden visibility indicates that the entity declared has a new -form of linkage, which we call ``hidden linkage''. Two -declarations of an object with hidden linkage refer to the same object -if they are in the same shared object. - -@item internal -Internal visibility is like hidden visibility, but with additional -processor specific semantics. Unless otherwise specified by the -psABI, GCC defines internal visibility to mean that a function is -@emph{never} called from another module. Compare this with hidden -functions which, while they cannot be referenced directly by other -modules, can be referenced indirectly via function pointers. By -indicating that a function cannot be called from outside the module, -GCC may for instance omit the load of a PIC register since it is known -that the calling function loaded the correct value. - -@item protected -Protected visibility is like default visibility except that it -indicates that references within the defining module bind to the -definition in that module. That is, the declared entity cannot be -overridden by another module. - -@end table - -All visibilities are supported on many, but not all, ELF targets -(supported when the assembler supports the @samp{.visibility} -pseudo-op). Default visibility is supported everywhere. Hidden -visibility is supported on Darwin targets. - -The visibility attribute should be applied only to declarations that -would otherwise have external linkage. The attribute should be applied -consistently, so that the same entity should not be declared with -different settings of the attribute. - -In C++, the visibility attribute applies to types as well as functions -and objects, because in C++ types have linkage. A class must not have -greater visibility than its non-static data member types and bases, -and class members default to the visibility of their class. Also, a -declaration without explicit visibility is limited to the visibility -of its type. - -In C++, you can mark member functions and static member variables of a -class with the visibility attribute. This is useful if you know a -particular method or static member variable should only be used from -one shared object; then you can mark it hidden while the rest of the -class has default visibility. Care must be taken to avoid breaking -the One Definition Rule; for example, it is usually not useful to mark -an inline method as hidden without marking the whole class as hidden. - -A C++ namespace declaration can also have the visibility attribute. -This attribute applies only to the particular namespace body, not to -other definitions of the same namespace; it is equivalent to using -@samp{#pragma GCC visibility} before and after the namespace -definition (@pxref{Visibility Pragmas}). - -In C++, if a template argument has limited visibility, this -restriction is implicitly propagated to the template instantiation. -Otherwise, template instantiations and specializations default to the -visibility of their template. - -If both the template and enclosing class have explicit visibility, the -visibility from the template is used. - -@item vliw -@cindex @code{vliw} attribute -On MeP, the @code{vliw} attribute tells the compiler to emit -instructions in VLIW mode instead of core mode. Note that this -attribute is not allowed unless a VLIW coprocessor has been configured -and enabled through command-line options. - -@item warn_unused_result -@cindex @code{warn_unused_result} attribute -The @code{warn_unused_result} attribute causes a warning to be emitted -if a caller of the function with this attribute does not use its -return value. This is useful for functions where not checking -the result is either a security problem or always a bug, such as -@code{realloc}. - -@smallexample -int fn () __attribute__ ((warn_unused_result)); -int foo () -@{ - if (fn () < 0) return -1; - fn (); - return 0; -@} -@end smallexample - -@noindent -results in warning on line 5. - -@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 that 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 weakref -@itemx weakref ("@var{target}") -@cindex @code{weakref} attribute -The @code{weakref} attribute marks a declaration as a weak reference. -Without arguments, it should be accompanied by an @code{alias} attribute -naming the target symbol. Optionally, the @var{target} may be given as -an argument to @code{weakref} itself. In either case, @code{weakref} -implicitly marks the declaration as @code{weak}. Without a -@var{target}, given as an argument to @code{weakref} or to @code{alias}, -@code{weakref} is equivalent to @code{weak}. - -@smallexample -static int x() __attribute__ ((weakref ("y"))); -/* is equivalent to... */ -static int x() __attribute__ ((weak, weakref, alias ("y"))); -/* and to... */ -static int x() __attribute__ ((weakref)); -static int x() __attribute__ ((alias ("y"))); -@end smallexample - -A weak reference is an alias that does not by itself require a -definition to be given for the target symbol. If the target symbol is -only referenced through weak references, then it becomes a @code{weak} -undefined symbol. If it is directly referenced, however, then such -strong references prevail, and a definition is required for the -symbol, not necessarily in the same translation unit. - -The effect is equivalent to moving all references to the alias to a -separate translation unit, renaming the alias to the aliased symbol, -declaring it as weak, compiling the two separate translation units and -performing a reloadable link on them. - -At present, a declaration to which @code{weakref} is attached can -only be @code{static}. - -@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{Pragmas,,Pragmas Accepted by GCC}. - -@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. - -In GNU C, 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 program-generated code that may contain unused labels, -but which is compiled with @option{-Wall}. It is -not normally 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. GNU C++ only permits -attributes on labels if the attribute specifier is immediately -followed by a semicolon (i.e., the label applies to an empty -statement). If the semicolon is missing, C++ label attributes are -ambiguous, as it is permissible for a declaration, which could begin -with an attribute list, to be labelled in C++. Declarations cannot be -labelled in C90 or C99, so the ambiguity does not arise there. - -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. The former syntax is preferred. -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. - -At present, the first parameter in a function prototype must have some -type specifier that is not an attribute specifier; this resolves an -ambiguity in the interpretation of @code{void f(int -(__attribute__((foo)) x))}, but is subject to change. At present, if -the parentheses of a function declarator contain only attributes then -those attributes are ignored, rather than yielding an error or warning -or implying a single parameter of type int, but this is subject to -change. - -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. Such attribute specifiers apply -to the declared object or function. Where an -assembler name for an object or function is specified (@pxref{Asm -Labels}), the attribute must follow the @code{asm} -specification. - -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 makes 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} pointer to @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 is 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 is 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 is treated as -applying to the function type, and such an attribute applied to an array -element type is 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 is 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 is 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: - -@smallexample -/* @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) /* @r{??? lossage here ???} */ - uid_t x; -@{ - return x == 0; -@} -@end smallexample - -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: - -@smallexample -int isroot (uid_t); - -int -isroot (uid_t x) -@{ - return x == 0; -@} -@end smallexample - -@noindent -GNU C++ does not support old-style function definitions, so this -extension is irrelevant. - -@node C++ Comments -@section C++ Style Comments -@cindex @code{//} -@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 included in the 1999 C standard. However, -C++ style comments are not recognized if you specify an @option{-std} -option specifying a version of ISO C before C99, or @option{-ansi} -(equivalent to @option{-std=c90}). - -@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 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. Some -attributes are currently defined generically for variables. -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, -which forces the union to be double-word aligned. - -As in the preceding examples, you can explicitly specify the alignment -(in bytes) that you wish the compiler to use for a given variable or -structure field. Alternatively, you can leave out the alignment factor -and just ask the compiler to align a variable or field to the -default alignment for the target architecture you are compiling for. -The default alignment is sufficient for all scalar types, but may not be -enough for all vector types on a target that supports vector operations. -The default alignment is fixed for a particular target ABI. - -GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, -which is the largest alignment ever used for any data type on the -target machine you are compiling for. For example, you could write: - -@smallexample -short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); -@end smallexample - -The compiler automatically sets the alignment for the declared -variable or field to @code{__BIGGEST_ALIGNMENT__}. 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. Note that the value of @code{__BIGGEST_ALIGNMENT__} -may change depending on command-line options. - -When used on a struct, or struct member, the @code{aligned} attribute can -only increase the alignment; in order to decrease it, the @code{packed} -attribute must be specified as well. When used as part of a typedef, the -@code{aligned} attribute can both increase and decrease alignment, and -specifying the @code{packed} attribute generates a warning. - -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__} still only provides you with 8-byte -alignment. See your linker documentation for further information. - -The @code{aligned} attribute can also be used for functions -(@pxref{Function Attributes}.) - -@item cleanup (@var{cleanup_function}) -@cindex @code{cleanup} attribute -The @code{cleanup} attribute runs a function when the variable goes -out of scope. This attribute can only be applied to auto function -scope variables; it may not be applied to parameters or variables -with static storage duration. The function must take one parameter, -a pointer to a type compatible with the variable. The return value -of the function (if any) is ignored. - -If @option{-fexceptions} is enabled, then @var{cleanup_function} -is run during the stack unwinding that happens during the -processing of the exception. Note that the @code{cleanup} attribute -does not allow the exception to be caught, only to perform an action. -It is undefined what happens if @var{cleanup_function} does not -return normally. - -@item common -@itemx nocommon -@cindex @code{common} attribute -@cindex @code{nocommon} attribute -@opindex fcommon -@opindex fno-common -The @code{common} attribute requests GCC to place a variable in -``common'' storage. The @code{nocommon} attribute requests the -opposite---to allocate space for it directly. - -These attributes override the default chosen by the -@option{-fno-common} and @option{-fcommon} flags respectively. - -@item deprecated -@itemx deprecated (@var{msg}) -@cindex @code{deprecated} attribute -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 warning only occurs for uses: - -@smallexample -extern int old_var __attribute__ ((deprecated)); -extern int old_var; -int new_fn () @{ return old_var; @} -@end smallexample - -@noindent -results in a warning on line 3 but not line 2. The optional @var{msg} -argument, which must be a string, is printed in the warning if -present. - -The @code{deprecated} attribute can also be used for functions and -types (@pxref{Function Attributes}, @pxref{Type Attributes}.) - -@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 @code{byte} or @code{__byte__} to -indicate the mode corresponding to a one-byte integer, @code{word} or -@code{__word__} for the mode of a one-word integer, and @code{pointer} -or @code{__pointer__} for the mode used to represent pointers. - -@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}: - -@smallexample -struct foo -@{ - char a; - int x[2] __attribute__ ((packed)); -@}; -@end smallexample - -@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the -@code{packed} attribute on bit-fields of type @code{char}. This has -been fixed in GCC 4.4 but the change can lead to differences in the -structure layout. See the documentation of -@option{-Wpacked-bitfield-compat} for more information. - -@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"))); - -main() -@{ - /* @r{Initialize stack pointer} */ - init_sp (stack + sizeof (stack)); - - /* @r{Initialize initialized data} */ - memcpy (&init_data, &data, &edata - &data); - - /* @r{Turn on the serial ports} */ - init_duart (&a); - init_duart (&b); -@} -@end smallexample - -@noindent -Use the @code{section} attribute with -@emph{global} variables and not @emph{local} variables, -as shown in the example. - -You may use the @code{section} attribute with initialized or -uninitialized global variables but 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''. Using the @code{section} attribute -changes what section the variable goes into and may cause the -linker to issue an error if an uninitialized variable has multiple -definitions. 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 Microsoft Windows, in addition to putting variable definitions in a named -section, the section can also be shared among all running copies of an -executable or DLL@. For example, this small program defines shared data -by putting it in a named section @code{shared} and marking the section -shareable: - -@smallexample -int foo __attribute__((section ("shared"), shared)) = 0; - -int -main() -@{ - /* @r{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 Microsoft Windows@. - -@item tls_model ("@var{tls_model}") -@cindex @code{tls_model} attribute -The @code{tls_model} attribute sets thread-local storage model -(@pxref{Thread-Local}) of a particular @code{__thread} variable, -overriding @option{-ftls-model=} command-line switch on a per-variable -basis. -The @var{tls_model} argument should be one of @code{global-dynamic}, -@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. - -Not all targets support this attribute. - -@item unused -This attribute, attached to a variable, means that the variable is meant -to be possibly unused. GCC does not produce a warning for this -variable. - -@item used -This attribute, attached to a variable, means that the variable must be -emitted even if it appears that the variable is not referenced. - -When applied to a static data member of a C++ class template, the -attribute also means that the member is instantiated if the -class itself is instantiated. - -@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} is 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 selectany -The @code{selectany} attribute causes an initialized global variable to -have link-once semantics. When multiple definitions of the variable are -encountered by the linker, the first is selected and the remainder are -discarded. Following usage by the Microsoft compiler, the linker is told -@emph{not} to warn about size or content differences of the multiple -definitions. - -Although the primary usage of this attribute is for POD types, the -attribute can also be applied to global C++ objects that are initialized -by a constructor. In this case, the static initialization and destruction -code for the object is emitted in each translation defining the object, -but the calls to the constructor and destructor are protected by a -link-once guard variable. - -The @code{selectany} attribute is only available on Microsoft Windows -targets. You can use @code{__declspec (selectany)} as a synonym for -@code{__attribute__ ((selectany))} for compatibility with other -compilers. - -@item weak -The @code{weak} attribute is described in @ref{Function Attributes}. - -@item dllimport -The @code{dllimport} attribute is described in @ref{Function Attributes}. - -@item dllexport -The @code{dllexport} attribute is described in @ref{Function Attributes}. - -@end table - -@anchor{AVR Variable Attributes} -@subsection AVR Variable Attributes - -@table @code -@item progmem -@cindex @code{progmem} AVR variable attribute -The @code{progmem} attribute is used on the AVR to place read-only -data in the non-volatile program memory (flash). The @code{progmem} -attribute accomplishes this by putting respective variables into a -section whose name starts with @code{.progmem}. - -This attribute works similar to the @code{section} attribute -but adds additional checking. Notice that just like the -@code{section} attribute, @code{progmem} affects the location -of the data but not how this data is accessed. - -In order to read data located with the @code{progmem} attribute -(inline) assembler must be used. -@smallexample -/* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */ -#include <avr/pgmspace.h> - -/* Locate var in flash memory */ -const int var[2] PROGMEM = @{ 1, 2 @}; - -int read_var (int i) -@{ - /* Access var[] by accessor macro from avr/pgmspace.h */ - return (int) pgm_read_word (& var[i]); -@} -@end smallexample - -AVR is a Harvard architecture processor and data and read-only data -normally resides in the data memory (RAM). - -See also the @ref{AVR Named Address Spaces} section for -an alternate way to locate and access data in flash memory. -@end table - -@subsection Blackfin Variable Attributes - -Three attributes are currently defined for the Blackfin. - -@table @code -@item l1_data -@itemx l1_data_A -@itemx l1_data_B -@cindex @code{l1_data} variable attribute -@cindex @code{l1_data_A} variable attribute -@cindex @code{l1_data_B} variable attribute -Use these attributes on the Blackfin to place the variable into L1 Data SRAM. -Variables with @code{l1_data} attribute are put into the specific section -named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into -the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} -attribute are put into the specific section named @code{.l1.data.B}. - -@item l2 -@cindex @code{l2} variable attribute -Use this attribute on the Blackfin to place the variable into L2 SRAM. -Variables with @code{l2} attribute are put into the specific section -named @code{.l2.data}. -@end table - -@subsection M32R/D Variable Attributes - -One attribute is currently defined for the M32R/D@. - -@table @code -@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 generates @code{seth/add3} instructions to load their -addresses). -@end table - -@anchor{MeP Variable Attributes} -@subsection MeP Variable Attributes - -The MeP target has a number of addressing modes and busses. The -@code{near} space spans the standard memory space's first 16 megabytes -(24 bits). The @code{far} space spans the entire 32-bit memory space. -The @code{based} space is a 128-byte region in the memory space that -is addressed relative to the @code{$tp} register. The @code{tiny} -space is a 65536-byte region relative to the @code{$gp} register. In -addition to these memory regions, the MeP target has a separate 16-bit -control bus which is specified with @code{cb} attributes. - -@table @code - -@item based -Any variable with the @code{based} attribute is assigned to the -@code{.based} section, and is accessed with relative to the -@code{$tp} register. - -@item tiny -Likewise, the @code{tiny} attribute assigned variables to the -@code{.tiny} section, relative to the @code{$gp} register. - -@item near -Variables with the @code{near} attribute are assumed to have addresses -that fit in a 24-bit addressing mode. This is the default for large -variables (@code{-mtiny=4} is the default) but this attribute can -override @code{-mtiny=} for small variables, or override @code{-ml}. - -@item far -Variables with the @code{far} attribute are addressed using a full -32-bit address. Since this covers the entire memory space, this -allows modules to make no assumptions about where variables might be -stored. - -@item io -@itemx io (@var{addr}) -Variables with the @code{io} attribute are used to address -memory-mapped peripherals. If an address is specified, the variable -is assigned that address, else it is not assigned an address (it is -assumed some other module assigns an address). Example: - -@smallexample -int timer_count __attribute__((io(0x123))); -@end smallexample - -@item cb -@itemx cb (@var{addr}) -Variables with the @code{cb} attribute are used to access the control -bus, using special instructions. @code{addr} indicates the control bus -address. Example: - -@smallexample -int cpu_clock __attribute__((cb(0x123))); -@end smallexample - -@end table - -@anchor{i386 Variable Attributes} -@subsection i386 Variable Attributes - -Two attributes are currently defined for i386 configurations: -@code{ms_struct} and @code{gcc_struct} - -@table @code -@item ms_struct -@itemx gcc_struct -@cindex @code{ms_struct} attribute -@cindex @code{gcc_struct} attribute - -If @code{packed} is used on a structure, or if bit-fields are used, -it may be that the Microsoft ABI lays out the structure differently -than the way GCC normally does. Particularly when moving packed -data between functions compiled with GCC and the native Microsoft compiler -(either via function call or as data in a file), it may be necessary to access -either format. - -Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 -compilers to match the native Microsoft compiler. - -The Microsoft structure layout algorithm is fairly simple with the exception -of the bit-field packing. -The padding and alignment of members of structures and whether a bit-field -can straddle a storage-unit boundary are determine by these rules: - -@enumerate -@item Structure members are stored sequentially in the order in which they are -declared: the first member has the lowest memory address and the last member -the highest. - -@item Every data object has an alignment requirement. The alignment requirement -for all data except structures, unions, and arrays is either the size of the -object or the current packing size (specified with either the -@code{aligned} attribute or the @code{pack} pragma), -whichever is less. For structures, unions, and arrays, -the alignment requirement is the largest alignment requirement of its members. -Every object is allocated an offset so that: - -@smallexample -offset % alignment_requirement == 0 -@end smallexample - -@item Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation -unit if the integral types are the same size and if the next bit-field fits -into the current allocation unit without crossing the boundary imposed by the -common alignment requirements of the bit-fields. -@end enumerate - -MSVC interprets zero-length bit-fields in the following ways: - -@enumerate -@item If a zero-length bit-field is inserted between two bit-fields that -are normally coalesced, the bit-fields are not coalesced. - -For example: - -@smallexample -struct - @{ - unsigned long bf_1 : 12; - unsigned long : 0; - unsigned long bf_2 : 12; - @} t1; -@end smallexample - -@noindent -The size of @code{t1} is 8 bytes with the zero-length bit-field. If the -zero-length bit-field were removed, @code{t1}'s size would be 4 bytes. - -@item If a zero-length bit-field is inserted after a bit-field, @code{foo}, and the -alignment of the zero-length bit-field is greater than the member that follows it, -@code{bar}, @code{bar} is aligned as the type of the zero-length bit-field. - -For example: - -@smallexample -struct - @{ - char foo : 4; - short : 0; - char bar; - @} t2; - -struct - @{ - char foo : 4; - short : 0; - double bar; - @} t3; -@end smallexample - -@noindent -For @code{t2}, @code{bar} is placed at offset 2, rather than offset 1. -Accordingly, the size of @code{t2} is 4. For @code{t3}, the zero-length -bit-field does not affect the alignment of @code{bar} or, as a result, the size -of the structure. - -Taking this into account, it is important to note the following: - -@enumerate -@item If a zero-length bit-field follows a normal bit-field, the type of the -zero-length bit-field may affect the alignment of the structure as whole. For -example, @code{t2} has a size of 4 bytes, since the zero-length bit-field follows a -normal bit-field, and is of type short. - -@item Even if a zero-length bit-field is not followed by a normal bit-field, it may -still affect the alignment of the structure: - -@smallexample -struct - @{ - char foo : 6; - long : 0; - @} t4; -@end smallexample - -@noindent -Here, @code{t4} takes up 4 bytes. -@end enumerate - -@item Zero-length bit-fields following non-bit-field members are ignored: - -@smallexample -struct - @{ - char foo; - long : 0; - char bar; - @} t5; -@end smallexample - -@noindent -Here, @code{t5} takes up 2 bytes. -@end enumerate -@end table - -@subsection PowerPC Variable Attributes - -Three attributes currently are defined for PowerPC configurations: -@code{altivec}, @code{ms_struct} and @code{gcc_struct}. - -For full documentation of the struct attributes please see the -documentation in @ref{i386 Variable Attributes}. - -For documentation of @code{altivec} attribute please see the -documentation in @ref{PowerPC Type Attributes}. - -@subsection SPU Variable Attributes - -The SPU supports the @code{spu_vector} attribute for variables. For -documentation of this attribute please see the documentation in -@ref{SPU Type Attributes}. - -@subsection Xstormy16 Variable Attributes - -One attribute is currently defined for xstormy16 configurations: -@code{below100}. - -@table @code -@item below100 -@cindex @code{below100} attribute - -If a variable has the @code{below100} attribute (@code{BELOW100} is -allowed also), GCC places the variable in the first 0x100 bytes of -memory and use special opcodes to access it. Such variables are -placed in either the @code{.bss_below100} section or the -@code{.data_below100} section. - -@end table - -@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. Seven attributes are currently defined for -types: @code{aligned}, @code{packed}, @code{transparent_union}, -@code{unused}, @code{deprecated}, @code{visibility}, and -@code{may_alias}. 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 type attributes in an enum, struct or union type -declaration or definition, or for other types in a @code{typedef} -declaration. - -For an enum, struct or union type, you may specify attributes either -between the enum, struct or union tag and the name of the type, or -just past the closing curly brace of the @emph{definition}. The -former syntax is preferred. - -@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 ensure (as far as it can) that each variable whose -type is @code{struct S} or @code{more_aligned_int} is 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 that 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 that 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 that 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 also does 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 is often 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__} still only provides you with 8-byte -alignment. See your linker documentation for further information. - -@item packed -This attribute, attached to @code{struct} or @code{union} type -definition, specifies that each member (other than zero-width bit-fields) -of the structure or union is placed to minimize the memory required. When -attached to an @code{enum} definition, it indicates that the smallest -integral type should be used. - -@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. - -In the following example @code{struct my_packed_struct}'s members are -packed closely together, but the internal layout of its @code{s} member -is not packed---to do that, @code{struct my_unpacked_struct} needs to -be packed too. - -@smallexample -struct my_unpacked_struct - @{ - char c; - int i; - @}; - -struct __attribute__ ((__packed__)) my_packed_struct - @{ - char c; - int i; - struct my_unpacked_struct s; - @}; -@end smallexample - -You may only specify this attribute on the definition of an @code{enum}, -@code{struct} or @code{union}, not on a @code{typedef} that does not -also define the enumerated type, structure or union. - -@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 the first member of the transparent union, not the calling -conventions of the union itself. All members of the union must have the -same machine representation; this is necessary for this argument passing -to work properly. - -Transparent unions are designed for library functions that have multiple -interfaces for compatibility reasons. For example, suppose the -@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 __attribute__ ((__transparent_union__)) - @{ - int *__ip; - union wait *__up; - @} wait_status_ptr_t; - -pid_t wait (wait_status_ptr_t); -@end smallexample - -@noindent -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: - -@smallexample -int w1 () @{ int w; return wait (&w); @} -int w2 () @{ union wait w; return wait (&w); @} -@end smallexample - -@noindent -With this interface, @code{wait}'s implementation might look like this: - -@smallexample -pid_t wait (wait_status_ptr_t p) -@{ - return waitpid (-1, p.__ip, 0); -@} -@end smallexample - -@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 does 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 -@itemx deprecated (@var{msg}) -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 - -@noindent -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 optional @var{msg} -argument, which must be a string, is printed in the warning if -present. - -The @code{deprecated} attribute can also be used for functions and -variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) - -@item may_alias -Accesses through pointers to types with this attribute are not subject -to type-based alias analysis, but are instead assumed to be able to alias -any other type of objects. -In the context of section 6.5 paragraph 7 of the C99 standard, -an lvalue expression -dereferencing such a pointer is treated like having a character type. -See @option{-fstrict-aliasing} for more information on aliasing issues. -This extension exists to support some vector APIs, in which pointers to -one vector type are permitted to alias pointers to a different vector type. - -Note that an object of a type with this attribute does not have any -special semantics. - -Example of use: - -@smallexample -typedef short __attribute__((__may_alias__)) short_a; - -int -main (void) -@{ - int a = 0x12345678; - short_a *b = (short_a *) &a; - - b[1] = 0; - - if (a == 0x12345678) - abort(); - - exit(0); -@} -@end smallexample - -@noindent -If you replaced @code{short_a} with @code{short} in the variable -declaration, the above program would abort when compiled with -@option{-fstrict-aliasing}, which is on by default at @option{-O2} or -above in recent GCC versions. - -@item visibility -In C++, attribute visibility (@pxref{Function Attributes}) can also be -applied to class, struct, union and enum types. Unlike other type -attributes, the attribute must appear between the initial keyword and -the name of the type; it cannot appear after the body of the type. - -Note that the type visibility is applied to vague linkage entities -associated with the class (vtable, typeinfo node, etc.). In -particular, if a class is thrown as an exception in one shared object -and caught in another, the class must have default visibility. -Otherwise the two shared objects are unable to use the same -typeinfo node and exception handling will break. - -@end table - -To specify multiple attributes, separate them by commas within the -double parentheses: for example, @samp{__attribute__ ((aligned (16), -packed))}. - -@subsection ARM Type Attributes - -On those ARM targets that support @code{dllimport} (such as Symbian -OS), you can use the @code{notshared} attribute to indicate that the -virtual table and other similar data for a class should not be -exported from a DLL@. For example: - -@smallexample -class __declspec(notshared) C @{ -public: - __declspec(dllimport) C(); - virtual void f(); -@} - -__declspec(dllexport) -C::C() @{@} -@end smallexample - -@noindent -In this code, @code{C::C} is exported from the current DLL, but the -virtual table for @code{C} is not exported. (You can use -@code{__attribute__} instead of @code{__declspec} if you prefer, but -most Symbian OS code uses @code{__declspec}.) - -@anchor{MeP Type Attributes} -@subsection MeP Type Attributes - -Many of the MeP variable attributes may be applied to types as well. -Specifically, the @code{based}, @code{tiny}, @code{near}, and -@code{far} attributes may be applied to either. The @code{io} and -@code{cb} attributes may not be applied to types. - -@anchor{i386 Type Attributes} -@subsection i386 Type Attributes - -Two attributes are currently defined for i386 configurations: -@code{ms_struct} and @code{gcc_struct}. - -@table @code - -@item ms_struct -@itemx gcc_struct -@cindex @code{ms_struct} -@cindex @code{gcc_struct} - -If @code{packed} is used on a structure, or if bit-fields are used -it may be that the Microsoft ABI packs them differently -than GCC normally packs them. Particularly when moving packed -data between functions compiled with GCC and the native Microsoft compiler -(either via function call or as data in a file), it may be necessary to access -either format. - -Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 -compilers to match the native Microsoft compiler. -@end table - -@anchor{PowerPC Type Attributes} -@subsection PowerPC Type Attributes - -Three attributes currently are defined for PowerPC configurations: -@code{altivec}, @code{ms_struct} and @code{gcc_struct}. - -For full documentation of the @code{ms_struct} and @code{gcc_struct} -attributes please see the documentation in @ref{i386 Type Attributes}. - -The @code{altivec} attribute allows one to declare AltiVec vector data -types supported by the AltiVec Programming Interface Manual. The -attribute requires an argument to specify one of three vector types: -@code{vector__}, @code{pixel__} (always followed by unsigned short), -and @code{bool__} (always followed by unsigned). - -@smallexample -__attribute__((altivec(vector__))) -__attribute__((altivec(pixel__))) unsigned short -__attribute__((altivec(bool__))) unsigned -@end smallexample - -These attributes mainly are intended to support the @code{__vector}, -@code{__pixel}, and @code{__bool} AltiVec keywords. - -@anchor{SPU Type Attributes} -@subsection SPU Type Attributes - -The SPU supports the @code{spu_vector} attribute for types. This attribute -allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU -Language Extensions Specification. It is intended to support the -@code{__vector} keyword. - -@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 address. For these machines, @code{__alignof__} -reports the smallest alignment that GCC gives the data type, usually as -mandated by the target ABI. - -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: - -@smallexample -struct foo @{ int x; char y; @} foo1; -@end smallexample - -@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 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 inline, you can direct GCC to make -calls to that function faster. One way GCC can achieve this is 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. You can -also direct GCC to try to integrate all ``simple enough'' functions -into their callers with the option @option{-finline-functions}. - -GCC implements three different semantics of declaring a function -inline. One is available with @option{-std=gnu89} or -@option{-fgnu89-inline} or when @code{gnu_inline} attribute is present -on all inline declarations, another when -@option{-std=c99}, @option{-std=c11}, -@option{-std=gnu99} or @option{-std=gnu11} -(without @option{-fgnu89-inline}), and the third -is used when compiling C++. - -To declare a function inline, use the @code{inline} keyword in its -declaration, like this: - -@smallexample -static inline int -inc (int *a) -@{ - return (*a)++; -@} -@end smallexample - -If you are writing a header file to be included in ISO C90 programs, write -@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. - -The three types of inlining behave similarly in two important cases: -when the @code{inline} keyword is used on a @code{static} function, -like the example above, and when a function is first declared without -using the @code{inline} keyword and then is defined with -@code{inline}, like this: - -@smallexample -extern int inc (int *a); -inline int -inc (int *a) -@{ - return (*a)++; -@} -@end smallexample - -In both of these common cases, the program behaves the same as if you -had not used the @code{inline} keyword, except for its speed. - -@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. - -@opindex Winline -Note that certain usages in a function definition can make it unsuitable -for inline substitution. Among these usages are: variadic functions, use of -@code{alloca}, use of variable-length 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} -warns when a function marked @code{inline} could not be substituted, -and gives the reason for the failure. - -@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 -As required by ISO C++, GCC considers member functions defined within -the body of a class to be marked inline even if they are -not explicitly declared with the @code{inline} keyword. You can -override this with @option{-fno-default-inline}; @pxref{C++ Dialect -Options,,Options Controlling C++ Dialect}. - -GCC does not inline any functions when not optimizing unless you specify -the @samp{always_inline} attribute for the function, like this: - -@smallexample -/* @r{Prototype.} */ -inline void foo (const char) __attribute__((always_inline)); -@end smallexample - -The remainder of this section is specific to GNU C90 inlining. - -@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 causes most calls to the function -to be inlined. If any uses of the function remain, they refer to -the single copy in the library. - -@node Volatiles -@section When is a Volatile Object Accessed? -@cindex accessing volatiles -@cindex volatile read -@cindex volatile write -@cindex volatile access - -C has the concept of volatile objects. These are normally accessed by -pointers and used for accessing hardware or inter-thread -communication. The standard encourages compilers to refrain from -optimizations concerning accesses to volatile objects, but leaves it -implementation defined as to what constitutes a volatile access. The -minimum requirement 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 that occur between sequence points, but cannot do -so for accesses across a sequence point. The use of volatile does -not allow you to violate the restriction on updating objects multiple -times between two sequence points. - -Accesses to non-volatile objects are not ordered with respect to -volatile accesses. You cannot use a volatile object as a memory -barrier to order a sequence of writes to non-volatile memory. For -instance: - -@smallexample -int *ptr = @var{something}; -volatile int vobj; -*ptr = @var{something}; -vobj = 1; -@end smallexample - -@noindent -Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed -that the write to @var{*ptr} occurs by the time the update -of @var{vobj} happens. If you need this guarantee, you must use -a stronger memory barrier such as: - -@smallexample -int *ptr = @var{something}; -volatile int vobj; -*ptr = @var{something}; -asm volatile ("" : : : "memory"); -vobj = 1; -@end smallexample - -A scalar volatile object is read when it is accessed in a void context: - -@smallexample -volatile int *src = @var{somevalue}; -*src; -@end smallexample - -Such expressions are rvalues, and GCC implements this as a -read of the volatile object being pointed to. - -Assignments are also expressions and have an rvalue. However when -assigning to a scalar volatile, the volatile object is not reread, -regardless of whether the assignment expression's rvalue is used or -not. If the assignment's rvalue is used, the value is that assigned -to the volatile object. For instance, there is no read of @var{vobj} -in all the following cases: - -@smallexample -int obj; -volatile int vobj; -vobj = @var{something}; -obj = vobj = @var{something}; -obj ? vobj = @var{onething} : vobj = @var{anotherthing}; -obj = (@var{something}, vobj = @var{anotherthing}); -@end smallexample - -If you need to read the volatile object after an assignment has -occurred, you must use a separate expression with an intervening -sequence point. - -As bit-fields are not individually addressable, volatile bit-fields may -be implicitly read when written to, or when adjacent bit-fields are -accessed. Bit-field operations may be optimized such that adjacent -bit-fields are only partially accessed, if they straddle a storage unit -boundary. For these reasons it is unwise to use volatile bit-fields to -access hardware. - -@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 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: - -@smallexample -asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); -@end smallexample - -@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: - -@smallexample -asm ("fsinx %[angle],%[output]" - : [output] "=f" (result) - : [angle] "f" (angle)); -@end smallexample - -@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 you must ensure that no two operands within the same -assembler construct use the same symbolic name. - -Output operand expressions must be lvalues; the compiler can check this. -The input operands need not be lvalues. The compiler cannot check -whether the operands have data types that are reasonable for the -instruction being executed. It does not parse the assembler instruction -template and does not know what it means or even whether it is valid -assembler input. The extended @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 -uses the register as the output of the @code{asm}, and then stores -that register into the output. - -The ordinary output operands must be write-only; GCC assumes 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. - -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 -that 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: - -@smallexample -asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); -@end smallexample - -@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 is 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 are in the -same place in the generated assembler code. The following does not -work reliably: - -@smallexample -asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); -@end smallexample - -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: - -@smallexample -asm ("cmoveq %1,%2,%[result]" - : [result] "=r"(result) - : "r" (test), "r"(new), "[result]"(old)); -@end smallexample - -Sometimes you need to make an @code{asm} operand be a specific register, -but there's no matching constraint letter for that register @emph{by -itself}. To force the operand into that register, use a local variable -for the operand and specify the register in the variable declaration. -@xref{Explicit Reg Vars}. Then for the @code{asm} operand, use any -register constraint letter that matches the register: - -@smallexample -register int *p1 asm ("r0") = @dots{}; -register int *p2 asm ("r1") = @dots{}; -register int *result asm ("r0"); -asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); -@end smallexample - -@anchor{Example of asm with clobbered asm reg} -In the above example, beware that a register that is call-clobbered by -the target ABI will be overwritten by any function call in the -assignment, including library calls for arithmetic operators. -Also a register may be clobbered when generating some operations, -like variable shift, memory copy or memory move on x86. -Assuming it is a call-clobbered register, this may happen to @code{r0} -above by the assignment to @code{p2}. If you have to use such a -register, use temporary variables for expressions between the register -assignment and use: - -@smallexample -int t1 = @dots{}; -register int *p1 asm ("r0") = @dots{}; -register int *p2 asm ("r1") = t1; -register int *result asm ("r0"); -asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); -@end smallexample - -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: - -@smallexample -asm volatile ("movc3 %0,%1,%2" - : /* @r{no outputs} */ - : "g" (from), "g" (to), "g" (count) - : "r0", "r1", "r2", "r3", "r4", "r5"); -@end smallexample - -You may not write a clobber description in a way that overlaps with an -input or output operand. For example, you may not have an operand -describing a register class with one member if you mention that register -in the clobber list. Variables declared to live in specific registers -(@pxref{Explicit Reg Vars}), and used as asm input or output operands must -have no part mentioned in the clobber description. -There is no way for you to specify that an input -operand is modified without also specifying it as an output -operand. Note that if all the output operands you specify are for this -purpose (and hence unused), you 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 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 instructions access memory in an unpredictable -fashion, add @samp{memory} to the list of clobbered registers. This -causes GCC to not keep memory values cached in registers across the -assembler instruction and not optimize stores or loads to that memory. -You also should 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}. If you know how large the accessed memory is, you can add -it as input or output but if this is not known, you should add -@samp{memory}. As an example, if you access ten bytes of a string, you -can use a memory input like: - -@smallexample -@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}. -@end smallexample - -Note that in the following example the memory input is necessary, -otherwise GCC might optimize the store to @code{x} away: -@smallexample -int foo () -@{ - int x = 42; - int *y = &x; - int result; - asm ("magic stuff accessing an 'int' pointed to by '%1'" - : "=&d" (r) : "a" (y), "m" (*y)); - return result; -@} -@end smallexample - -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 do 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: - -@smallexample -asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo" - : /* no outputs */ - : "g" (from), "g" (to) - : "r9", "r10"); -@end smallexample - -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: - -@smallexample -asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:" - : "g" (result) - : "g" (input)); -@end smallexample - -@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. @xref{Extended asm with goto}. - -@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, - -@smallexample -#define sin(x) \ -(@{ double __value, __arg = (x); \ - asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ - __value; @}) -@end smallexample - -@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} that 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 is @code{int}, casting the argument to -@code{int} accepts a pointer with no complaint, while assigning the -argument to an @code{int} variable named @code{__arg} warns 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 -by writing the keyword @code{volatile} after -the @code{asm}. For example: - -@smallexample -#define get_and_set_priority(new) \ -(@{ int __old; \ - asm volatile ("get_and_set_priority %0, %1" \ - : "=g" (__old) : "g" (new)); \ - __old; @}) -@end smallexample - -@noindent -The @code{volatile} keyword indicates that the instruction has -important side-effects. GCC does not delete a volatile @code{asm} if -it is reachable. (The instruction can still be deleted if GCC can -prove that control flow never reaches the location of the -instruction.) Note that even a volatile @code{asm} instruction -can be moved relative to other code, including across jump -instructions. For example, on many targets there is a system -register that can be set to control the rounding mode of -floating-point operations. You might try -setting it with a volatile @code{asm}, like this PowerPC example: - -@smallexample - asm volatile("mtfsf 255,%0" : : "f" (fpenv)); - sum = x + y; -@end smallexample - -@noindent -This does not work reliably, as the compiler may move the addition back -before the volatile @code{asm}. To make it work you need to add an -artificial dependency to the @code{asm} referencing a variable in the code -you don't want moved, for example: - -@smallexample - asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv)); - sum = x + y; -@end smallexample - -Similarly, 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 performs 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 output operands is 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 result in -additional following ``store'' instructions. On most machines, these -instructions alter the condition code before there is 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. - -@anchor{Extended asm with goto} -As of GCC version 4.5, @code{asm goto} may be used to have the assembly -jump to one or more C labels. In this form, a fifth section after the -clobber list contains a list of all C labels to which the assembly may jump. -Each label operand is implicitly self-named. The @code{asm} is also assumed -to fall through to the next statement. - -This form of @code{asm} is restricted to not have outputs. This is due -to a internal restriction in the compiler that control transfer instructions -cannot have outputs. This restriction on @code{asm goto} may be lifted -in some future version of the compiler. In the meantime, @code{asm goto} -may include a memory clobber, and so leave outputs in memory. - -@smallexample -int frob(int x) -@{ - int y; - asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5" - : : "r"(x), "r"(&y) : "r5", "memory" : error); - return y; - error: - return -1; -@} -@end smallexample - -@noindent -In this (inefficient) example, the @code{frob} instruction sets the -carry bit to indicate an error. The @code{jc} instruction detects -this and branches to the @code{error} label. Finally, the output -of the @code{frob} instruction (@code{%r5}) is stored into the memory -for variable @code{y}, which is later read by the @code{return} statement. - -@smallexample -void doit(void) -@{ - int i = 0; - asm goto ("mfsr %%r1, 123; jmp %%r1;" - ".pushsection doit_table;" - ".long %l0, %l1, %l2, %l3;" - ".popsection" - : : : "r1" : label1, label2, label3, label4); - __builtin_unreachable (); - - label1: - f1(); - return; - label2: - f2(); - return; - label3: - i = 1; - label4: - f3(i); -@} -@end smallexample - -@noindent -In this (also inefficient) example, the @code{mfsr} instruction reads -an address from some out-of-band machine register, and the following -@code{jmp} instruction branches to that address. The address read by -the @code{mfsr} instruction is assumed to have been previously set via -some application-specific mechanism to be one of the four values stored -in the @code{doit_table} section. Finally, the @code{asm} is followed -by a call to @code{__builtin_unreachable} to indicate that the @code{asm} -does not in fact fall through. - -@smallexample -#define TRACE1(NUM) \ - do @{ \ - asm goto ("0: nop;" \ - ".pushsection trace_table;" \ - ".long 0b, %l0;" \ - ".popsection" \ - : : : : trace#NUM); \ - if (0) @{ trace#NUM: trace(); @} \ - @} while (0) -#define TRACE TRACE1(__COUNTER__) -@end smallexample - -@noindent -In this example (which in fact inspired the @code{asm goto} feature) -we want on rare occasions to call the @code{trace} function; on other -occasions we'd like to keep the overhead to the absolute minimum. -The normal code path consists of a single @code{nop} instruction. -However, we record the address of this @code{nop} together with the -address of a label that calls the @code{trace} function. This allows -the @code{nop} instruction to be patched at run time to be an -unconditional branch to the stored label. It is assumed that an -optimizing compiler moves the labeled block out of line, to -optimize the fall through path from the @code{asm}. - -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 Size of an @code{asm} - -Some targets require that GCC track the size of each instruction used in -order to generate correct code. Because the final length of an -@code{asm} is only known by the assembler, GCC must make an estimate as -to how big it will be. The estimate is formed by counting the number of -statements in the pattern of the @code{asm} and multiplying that by the -length of the longest instruction on that processor. Statements in the -@code{asm} are identified by newline characters and whatever statement -separator characters are supported by the assembler; on most processors -this is the @samp{;} character. - -Normally, GCC's estimate is perfectly adequate to ensure that correct -code is generated, but it is possible to confuse the compiler if you use -pseudo instructions or assembler macros that expand into multiple real -instructions or if you use assembler directives that expand to more -space in the object file than is needed for a single instruction. -If this happens then the assembler produces a diagnostic saying that -a label is unreachable. - -@subsection i386 floating-point asm operands - -On i386 targets, there are several rules on the usage of stack-like registers -in the operands of an @code{asm}. These rules apply only to the operands -that are stack-like registers: - -@enumerate -@item -Given a set of input registers that die in an @code{asm}, it is -necessary to know which are implicitly popped by the @code{asm}, and -which must be explicitly popped by GCC@. - -An input register that is implicitly popped by the @code{asm} must be -explicitly clobbered, unless it is constrained to match an -output operand. - -@item -For any input register that is implicitly popped by an @code{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 register, 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 registers 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 @code{asm}, the compiler might -use the input register for an output reload. Consider this example: - -@smallexample -asm ("foo" : "=t" (a) : "f" (b)); -@end smallexample - -@noindent -This code says that input @code{b} is not popped by the @code{asm}, and that -the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one -deeper after the @code{asm} than it was before. But, it is possible that -reload may think that it can use the same register for both the input and -the output. - -To prevent this from happening, -if any input operand uses the @code{f} constraint, all output register -constraints must use the @code{&} early-clobber modifier. - -The example above would be correctly written as: - -@smallexample -asm ("foo" : "=&t" (a) : "f" (b)); -@end smallexample - -@item -Some operands need to be in particular places on the stack. All -output operands fall in this category---GCC has no other way to -know which registers the outputs appear in unless you indicate -this in the constraints. - -Output operands must specifically indicate which register an output -appears in after an @code{asm}. @code{=f} is not allowed: the operand -constraints must select a class with a single register. - -@item -Output operands may not be ``inserted'' between existing stack registers. -Since no 387 opcode uses a read/write operand, all output operands -are dead before the @code{asm}, and are pushed by the @code{asm}. -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 register. - -@item -Some @code{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 @code{asm}s to want to write. This -@code{asm} -takes one input, which is internally popped, and produces two outputs. - -@smallexample -asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); -@end smallexample - -@noindent -This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode, -and replaces them with one output. The @code{st(1)} clobber is necessary -for the compiler to know that @code{fyl2xp1} pops both inputs. - -@smallexample -asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); -@end smallexample - -@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: - -@smallexample -int foo asm ("myfoo") = 2; -@end smallexample - -@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: - -@smallexample -extern func () asm ("FUNC"); - -func (x, y) - int x, y; -/* @r{@dots{}} */ -@end smallexample - -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 that have a couple of global variables that are accessed -very often. - -@item -Local register variables in specific registers do not reserve the -registers, except at the point where they are used as input or output -operands in an @code{asm} statement and the @code{asm} statement itself is -not deleted. 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 works 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: - -@smallexample -register int *foo asm ("a5"); -@end smallexample - -@noindent -Here @code{a5} is the name of the register that should be used. Choose a -register that 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 need to -conditionalize your program according to cpu type. The register -@code{a5} is 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, different operating systems on the same CPU may differ in how they -name the registers; then you 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 is not allocated for any other purpose in the functions -in the current compilation, and is not saved and restored by -these functions. Stores into this register are never deleted even if they -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 is compiled without knowledge of this variable (i.e.@: in a -different source file in which the variable isn'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 that do not -actually use your global register variable, so that they do 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 that 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 that is the entry point into the part of the -program that uses the global register variable must explicitly save and -restore the value that 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} restores to each global register -variable the value it had at the time of the @code{setjmp}. On some -machines, however, @code{longjmp} does 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 happens 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 does 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: - -@smallexample -register int *foo asm ("a5"); -@end smallexample - -@noindent -Here @code{a5} is the name of the register that should be used. Note -that this is the same syntax used for defining global register -variables, but for a local variable it appears 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 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. - -This option does not guarantee that GCC generates code that has -this variable in the register you specify at all times. You may not -code an explicit reference to this register in the @emph{assembler -instruction template} part of an @code{asm} statement and assume it -always refers to this variable. However, using the variable as an -@code{asm} @emph{operand} guarantees that the specified register is used -for the operand. - -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. - -As for global register variables, it's recommended that you choose a -register that is normally saved and restored by function calls on -your machine, so that library routines will not clobber it. A common -pitfall is to initialize multiple call-clobbered registers with -arbitrary expressions, where a function call or library call for an -arithmetic operator overwrites a register value from a previous -assignment, for example @code{r0} below: -@smallexample -register int *p1 asm ("r0") = @dots{}; -register int *p2 asm ("r1") = @dots{}; -@end smallexample - -@noindent -In those cases, a solution is to use a temporary variable for -each arbitrary expression. @xref{Example of asm with clobbered asm reg}. - -@node Alternate Keywords -@section Alternate Keywords -@cindex alternate keywords -@cindex keywords, alternate - -@option{-ansi} and the various @option{-std} options disable certain -keywords. This causes trouble when you want to use GNU C extensions, or -a general-purpose header file that should be usable by all programs, -including ISO C programs. The keywords @code{asm}, @code{typeof} and -@code{inline} are not available in programs compiled with -@option{-ansi} or @option{-std} (although @code{inline} can be used in a -program compiled with @option{-std=c99} or @option{-std=c11}). 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}), or an option for a later standard -version, 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}, 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: - -@smallexample -#ifndef __GNUC__ -#define __asm__ asm -#endif -@end smallexample - -@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 -that 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{__func__} identifier -@cindex @code{__FUNCTION__} identifier -@cindex @code{__PRETTY_FUNCTION__} identifier - -GCC provides three magic variables that hold the name of the current -function, as a string. The first of these is @code{__func__}, which -is part of the C99 standard: - -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 - -@noindent -appeared, where function-name is the name of the lexically-enclosing -function. This name is the unadorned name of the function. - -@code{__FUNCTION__} is another name for @code{__func__}. Older -versions of GCC recognize only this name. However, it is not -standardized. For maximum portability, we recommend you use -@code{__func__}, but provide a fallback definition with the -preprocessor: - -@smallexample -#if __STDC_VERSION__ < 199901L -# if __GNUC__ >= 2 -# define __func__ __FUNCTION__ -# else -# define __func__ "<unknown>" -# endif -#endif -@end smallexample - -In C, @code{__PRETTY_FUNCTION__} is yet another name for -@code{__func__}. However, in C++, @code{__PRETTY_FUNCTION__} contains -the type signature of the function as well as its bare name. For -example, this program: - -@smallexample -extern "C" @{ -extern int printf (char *, ...); -@} - -class a @{ - public: - void 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__ = void a::sub(int) -@end smallexample - -These identifiers are not preprocessor macros. In GCC 3.3 and -earlier, in C only, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} -were treated as string literals; they could be used to initialize -@code{char} arrays, and they could be concatenated with other string -literals. GCC 3.4 and later treat them as variables, like -@code{__func__}. In C++, @code{__FUNCTION__} and -@code{__PRETTY_FUNCTION__} have always been variables. - -@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. When inlining -the expected behavior is that the function returns the address of -the function that is returned to. To work around this behavior use -the @code{noinline} function attribute. - -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 returns @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. - -Additional post-processing of the returned value may be needed, see -@code{__builtin_extract_return_addr}. - -This function should only be used with a nonzero argument for debugging -purposes. -@end deftypefn - -@deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr}) -The address as returned by @code{__builtin_return_address} may have to be fed -through this function to get the actual encoded address. For example, on the -31-bit S/390 platform the highest bit has to be masked out, or on SPARC -platforms an offset has to be added for the true next instruction to be -executed. - -If no fixup is needed, this function simply passes through @var{addr}. -@end deftypefn - -@deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr}) -This function does the reverse of @code{__builtin_extract_return_addr}. -@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 that 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} returns 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 returns @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 which -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}: - -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); -@end smallexample - -@noindent -The @code{int} type specifies the base type, while the attribute specifies -the vector size for the variable, measured in bytes. For example, the -declaration above causes the compiler to set the mode for the @code{v4si} -type to be 16 bytes wide and divided into @code{int} sized units. For -a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the -corresponding mode of @code{foo} is @acronym{V4SI}. - -The @code{vector_size} attribute is only applicable to integral and -float scalars, although arrays, pointers, and function return values -are allowed in conjunction with this construct. Only sizes that are -a power of two are currently allowed. - -All the basic integer types can be used as base types, both as signed -and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, -@code{long long}. In addition, @code{float} and @code{double} can be -used to build floating-point vector types. - -Specifying a combination that is not valid for the current architecture -causes GCC to synthesize the instructions using a narrower mode. -For example, if you specify a variable of type @code{V4SI} and your -architecture does not allow for this specific SIMD type, GCC -produces code that uses 4 @code{SIs}. - -The types defined in this manner can be used with a subset of normal C -operations. Currently, GCC allows using the following operators -on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. - -The operations behave like C++ @code{valarrays}. Addition is defined as -the addition of the corresponding elements of the operands. For -example, in the code below, each of the 4 elements in @var{a} is -added to the corresponding 4 elements in @var{b} and the resulting -vector is stored in @var{c}. - -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); - -v4si a, b, c; - -c = a + b; -@end smallexample - -Subtraction, multiplication, division, and the logical operations -operate in a similar manner. Likewise, the result of using the unary -minus or complement operators on a vector type is a vector whose -elements are the negative or complemented values of the corresponding -elements in the operand. - -It is possible to use shifting operators @code{<<}, @code{>>} on -integer-type vectors. The operation is defined as following: @code{@{a0, -a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, -@dots{}, an >> bn@}}@. Vector operands must have the same number of -elements. - -For convenience, it is allowed to use a binary vector operation -where one operand is a scalar. In that case the compiler transforms -the scalar operand into a vector where each element is the scalar from -the operation. The transformation happens only if the scalar could be -safely converted to the vector-element type. -Consider the following code. - -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); - -v4si a, b, c; -long l; - -a = b + 1; /* a = b + @{1,1,1,1@}; */ -a = 2 * b; /* a = @{2,2,2,2@} * b; */ - -a = l + a; /* Error, cannot convert long to int. */ -@end smallexample - -Vectors can be subscripted as if the vector were an array with -the same number of elements and base type. Out of bound accesses -invoke undefined behavior at run time. Warnings for out of bound -accesses for vector subscription can be enabled with -@option{-Warray-bounds}. - -Vector comparison is supported with standard comparison -operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be -vector expressions of integer-type or real-type. Comparison between -integer-type vectors and real-type vectors are not supported. The -result of the comparison is a vector of the same width and number of -elements as the comparison operands with a signed integral element -type. - -Vectors are compared element-wise producing 0 when comparison is false -and -1 (constant of the appropriate type where all bits are set) -otherwise. Consider the following example. - -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); - -v4si a = @{1,2,3,4@}; -v4si b = @{3,2,1,4@}; -v4si c; - -c = a > b; /* The result would be @{0, 0,-1, 0@} */ -c = a == b; /* The result would be @{0,-1, 0,-1@} */ -@end smallexample - -Vector shuffling is available using functions -@code{__builtin_shuffle (vec, mask)} and -@code{__builtin_shuffle (vec0, vec1, mask)}. -Both functions construct a permutation of elements from one or two -vectors and return a vector of the same type as the input vector(s). -The @var{mask} is an integral vector with the same width (@var{W}) -and element count (@var{N}) as the output vector. - -The elements of the input vectors are numbered in memory ordering of -@var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The -elements of @var{mask} are considered modulo @var{N} in the single-operand -case and modulo @math{2*@var{N}} in the two-operand case. - -Consider the following example, - -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); - -v4si a = @{1,2,3,4@}; -v4si b = @{5,6,7,8@}; -v4si mask1 = @{0,1,1,3@}; -v4si mask2 = @{0,4,2,5@}; -v4si res; - -res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */ -res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */ -@end smallexample - -Note that @code{__builtin_shuffle} is intentionally semantically -compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions. - -You can declare variables and use them in function calls and returns, as -well as in assignments and some casts. You can specify a vector type as -a return type for a function. Vector types can also be used as function -arguments. 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). - -You cannot operate between vectors of different lengths or different -signedness without a cast. - -@node Offsetof -@section Offsetof -@findex __builtin_offsetof - -GCC implements for both C and C++ a syntactic extension to implement -the @code{offsetof} macro. - -@smallexample -primary: - "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" - -offsetof_member_designator: - @code{identifier} - | offsetof_member_designator "." @code{identifier} - | offsetof_member_designator "[" @code{expr} "]" -@end smallexample - -This extension is sufficient such that - -@smallexample -#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) -@end smallexample - -@noindent -is a suitable definition of the @code{offsetof} macro. In C++, @var{type} -may be dependent. In either case, @var{member} may consist of a single -identifier, or a sequence of member accesses and array references. - -@node __sync Builtins -@section Legacy __sync Built-in Functions for Atomic Memory Access - -The following built-in functions -are intended to be compatible with those described -in the @cite{Intel Itanium Processor-specific Application Binary Interface}, -section 7.4. As such, they depart from the normal GCC practice of using -the @samp{__builtin_} prefix, and further that they are overloaded such that -they work on multiple types. - -The definition given in the Intel documentation allows only for the use of -the types @code{int}, @code{long}, @code{long long} as well as their unsigned -counterparts. GCC allows any integral scalar or pointer type that is -1, 2, 4 or 8 bytes in length. - -Not all operations are supported by all target processors. If a particular -operation cannot be implemented on the target processor, a warning is -generated and a call an external function is generated. The external -function carries the same name as the built-in version, -with an additional suffix -@samp{_@var{n}} where @var{n} is the size of the data type. - -@c ??? Should we have a mechanism to suppress this warning? This is almost -@c useful for implementing the operation under the control of an external -@c mutex. - -In most cases, these built-in functions are considered a @dfn{full barrier}. -That is, -no memory operand is moved across the operation, either forward or -backward. Further, instructions are issued as necessary to prevent the -processor from speculating loads across the operation and from queuing stores -after the operation. - -All of the routines are described in the Intel documentation to take -``an optional list of variables protected by the memory barrier''. It's -not clear what is meant by that; it could mean that @emph{only} the -following variables are protected, or it could mean that these variables -should in addition be protected. At present GCC ignores this list and -protects all variables that are globally accessible. If in the future -we make some use of this list, an empty list will continue to mean all -globally accessible variables. - -@table @code -@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) -@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) -@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) -@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) -@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) -@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) -@findex __sync_fetch_and_add -@findex __sync_fetch_and_sub -@findex __sync_fetch_and_or -@findex __sync_fetch_and_and -@findex __sync_fetch_and_xor -@findex __sync_fetch_and_nand -These built-in functions perform the operation suggested by the name, and -returns the value that had previously been in memory. That is, - -@smallexample -@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} -@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand -@end smallexample - -@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} -as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. - -@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) -@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) -@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) -@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) -@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) -@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) -@findex __sync_add_and_fetch -@findex __sync_sub_and_fetch -@findex __sync_or_and_fetch -@findex __sync_and_and_fetch -@findex __sync_xor_and_fetch -@findex __sync_nand_and_fetch -These built-in functions perform the operation suggested by the name, and -return the new value. That is, - -@smallexample -@{ *ptr @var{op}= value; return *ptr; @} -@{ *ptr = ~(*ptr & value); return *ptr; @} // nand -@end smallexample - -@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} -as @code{*ptr = ~(*ptr & value)} instead of -@code{*ptr = ~*ptr & value}. - -@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) -@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) -@findex __sync_bool_compare_and_swap -@findex __sync_val_compare_and_swap -These built-in functions perform an atomic compare and swap. -That is, if the current -value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into -@code{*@var{ptr}}. - -The ``bool'' version returns true if the comparison is successful and -@var{newval} is written. The ``val'' version returns the contents -of @code{*@var{ptr}} before the operation. - -@item __sync_synchronize (...) -@findex __sync_synchronize -This built-in function issues a full memory barrier. - -@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) -@findex __sync_lock_test_and_set -This built-in function, as described by Intel, is not a traditional test-and-set -operation, but rather an atomic exchange operation. It writes @var{value} -into @code{*@var{ptr}}, and returns the previous contents of -@code{*@var{ptr}}. - -Many targets have only minimal support for such locks, and do not support -a full exchange operation. In this case, a target may support reduced -functionality here by which the @emph{only} valid value to store is the -immediate constant 1. The exact value actually stored in @code{*@var{ptr}} -is implementation defined. - -This built-in function is not a full barrier, -but rather an @dfn{acquire barrier}. -This means that references after the operation cannot move to (or be -speculated to) before the operation, but previous memory stores may not -be globally visible yet, and previous memory loads may not yet be -satisfied. - -@item void __sync_lock_release (@var{type} *ptr, ...) -@findex __sync_lock_release -This built-in function releases the lock acquired by -@code{__sync_lock_test_and_set}. -Normally this means writing the constant 0 to @code{*@var{ptr}}. - -This built-in function is not a full barrier, -but rather a @dfn{release barrier}. -This means that all previous memory stores are globally visible, and all -previous memory loads have been satisfied, but following memory reads -are not prevented from being speculated to before the barrier. -@end table - -@node __atomic Builtins -@section Built-in functions for memory model aware atomic operations - -The following built-in functions approximately match the requirements for -C++11 memory model. Many are similar to the @samp{__sync} prefixed built-in -functions, but all also have a memory model parameter. These are all -identified by being prefixed with @samp{__atomic}, and most are overloaded -such that they work with multiple types. - -GCC allows any integral scalar or pointer type that is 1, 2, 4, or 8 -bytes in length. 16-byte integral types are also allowed if -@samp{__int128} (@pxref{__int128}) is supported by the architecture. - -Target architectures are encouraged to provide their own patterns for -each of these built-in functions. If no target is provided, the original -non-memory model set of @samp{__sync} atomic built-in functions are -utilized, along with any required synchronization fences surrounding it in -order to achieve the proper behavior. Execution in this case is subject -to the same restrictions as those built-in functions. - -If there is no pattern or mechanism to provide a lock free instruction -sequence, a call is made to an external routine with the same parameters -to be resolved at run time. - -The four non-arithmetic functions (load, store, exchange, and -compare_exchange) all have a generic version as well. This generic -version works on any data type. If the data type size maps to one -of the integral sizes that may have lock free support, the generic -version utilizes the lock free built-in function. Otherwise an -external call is left to be resolved at run time. This external call is -the same format with the addition of a @samp{size_t} parameter inserted -as the first parameter indicating the size of the object being pointed to. -All objects must be the same size. - -There are 6 different memory models that can be specified. These map -to the same names in the C++11 standard. Refer there or to the -@uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki on -atomic synchronization} for more detailed definitions. These memory -models integrate both barriers to code motion as well as synchronization -requirements with other threads. These are listed in approximately -ascending order of strength. It is also possible to use target specific -flags for memory model flags, like Hardware Lock Elision. - -@table @code -@item __ATOMIC_RELAXED -No barriers or synchronization. -@item __ATOMIC_CONSUME -Data dependency only for both barrier and synchronization with another -thread. -@item __ATOMIC_ACQUIRE -Barrier to hoisting of code and synchronizes with release (or stronger) -semantic stores from another thread. -@item __ATOMIC_RELEASE -Barrier to sinking of code and synchronizes with acquire (or stronger) -semantic loads from another thread. -@item __ATOMIC_ACQ_REL -Full barrier in both directions and synchronizes with acquire loads and -release stores in another thread. -@item __ATOMIC_SEQ_CST -Full barrier in both directions and synchronizes with acquire loads and -release stores in all threads. -@end table - -When implementing patterns for these built-in functions, the memory model -parameter can be ignored as long as the pattern implements the most -restrictive @code{__ATOMIC_SEQ_CST} model. Any of the other memory models -execute correctly with this memory model but they may not execute as -efficiently as they could with a more appropriate implementation of the -relaxed requirements. - -Note that the C++11 standard allows for the memory model parameter to be -determined at run time rather than at compile time. These built-in -functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather -than invoke a runtime library call or inline a switch statement. This is -standard compliant, safe, and the simplest approach for now. - -The memory model parameter is a signed int, but only the lower 8 bits are -reserved for the memory model. The remainder of the signed int is reserved -for future use and should be 0. Use of the predefined atomic values -ensures proper usage. - -@deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memmodel) -This built-in function implements an atomic load operation. It returns the -contents of @code{*@var{ptr}}. - -The valid memory model variants are -@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, -and @code{__ATOMIC_CONSUME}. - -@end deftypefn - -@deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memmodel) -This is the generic version of an atomic load. It returns the -contents of @code{*@var{ptr}} in @code{*@var{ret}}. - -@end deftypefn - -@deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memmodel) -This built-in function implements an atomic store operation. It writes -@code{@var{val}} into @code{*@var{ptr}}. - -The valid memory model variants are -@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}. - -@end deftypefn - -@deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memmodel) -This is the generic version of an atomic store. It stores the value -of @code{*@var{val}} into @code{*@var{ptr}}. - -@end deftypefn - -@deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memmodel) -This built-in function implements an atomic exchange operation. It writes -@var{val} into @code{*@var{ptr}}, and returns the previous contents of -@code{*@var{ptr}}. - -The valid memory model variants are -@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, -@code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}. - -@end deftypefn - -@deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memmodel) -This is the generic version of an atomic exchange. It stores the -contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value -of @code{*@var{ptr}} is copied into @code{*@var{ret}}. - -@end deftypefn - -@deftypefn {Built-in Function} bool __atomic_compare_exchange_n (@var{type} *ptr, @var{type} *expected, @var{type} desired, bool weak, int success_memmodel, int failure_memmodel) -This built-in function implements an atomic compare and exchange operation. -This compares the contents of @code{*@var{ptr}} with the contents of -@code{*@var{expected}} and if equal, writes @var{desired} into -@code{*@var{ptr}}. If they are not equal, the current contents of -@code{*@var{ptr}} is written into @code{*@var{expected}}. @var{weak} is true -for weak compare_exchange, and false for the strong variation. Many targets -only offer the strong variation and ignore the parameter. When in doubt, use -the strong variation. - -True is returned if @var{desired} is written into -@code{*@var{ptr}} and the execution is considered to conform to the -memory model specified by @var{success_memmodel}. There are no -restrictions on what memory model can be used here. - -False is returned otherwise, and the execution is considered to conform -to @var{failure_memmodel}. This memory model cannot be -@code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a -stronger model than that specified by @var{success_memmodel}. - -@end deftypefn - -@deftypefn {Built-in Function} bool __atomic_compare_exchange (@var{type} *ptr, @var{type} *expected, @var{type} *desired, bool weak, int success_memmodel, int failure_memmodel) -This built-in function implements the generic version of -@code{__atomic_compare_exchange}. The function is virtually identical to -@code{__atomic_compare_exchange_n}, except the desired value is also a -pointer. - -@end deftypefn - -@deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memmodel) -@deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memmodel) -@deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memmodel) -@deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memmodel) -@deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memmodel) -@deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memmodel) -These built-in functions perform the operation suggested by the name, and -return the result of the operation. That is, - -@smallexample -@{ *ptr @var{op}= val; return *ptr; @} -@end smallexample - -All memory models are valid. - -@end deftypefn - -@deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memmodel) -@deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memmodel) -@deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memmodel) -@deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memmodel) -@deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memmodel) -@deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memmodel) -These built-in functions perform the operation suggested by the name, and -return the value that had previously been in @code{*@var{ptr}}. That is, - -@smallexample -@{ tmp = *ptr; *ptr @var{op}= val; return tmp; @} -@end smallexample - -All memory models are valid. - -@end deftypefn - -@deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memmodel) - -This built-in function performs an atomic test-and-set operation on -the byte at @code{*@var{ptr}}. The byte is set to some implementation -defined nonzero ``set'' value and the return value is @code{true} if and only -if the previous contents were ``set''. - -All memory models are valid. - -@end deftypefn - -@deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memmodel) - -This built-in function performs an atomic clear operation on -@code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0. - -The valid memory model variants are -@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and -@code{__ATOMIC_RELEASE}. - -@end deftypefn - -@deftypefn {Built-in Function} void __atomic_thread_fence (int memmodel) - -This built-in function acts as a synchronization fence between threads -based on the specified memory model. - -All memory orders are valid. - -@end deftypefn - -@deftypefn {Built-in Function} void __atomic_signal_fence (int memmodel) - -This built-in function acts as a synchronization fence between a thread -and signal handlers based in the same thread. - -All memory orders are valid. - -@end deftypefn - -@deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr) - -This built-in function returns true if objects of @var{size} bytes always -generate lock free atomic instructions for the target architecture. -@var{size} must resolve to a compile-time constant and the result also -resolves to a compile-time constant. - -@var{ptr} is an optional pointer to the object that may be used to determine -alignment. A value of 0 indicates typical alignment should be used. The -compiler may also ignore this parameter. - -@smallexample -if (_atomic_always_lock_free (sizeof (long long), 0)) -@end smallexample - -@end deftypefn - -@deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr) - -This built-in function returns true if objects of @var{size} bytes always -generate lock free atomic instructions for the target architecture. If -it is not known to be lock free a call is made to a runtime routine named -@code{__atomic_is_lock_free}. - -@var{ptr} is an optional pointer to the object that may be used to determine -alignment. A value of 0 indicates typical alignment should be used. The -compiler may also ignore this parameter. -@end deftypefn - -@node x86 specific memory model extensions for transactional memory -@section x86 specific memory model extensions for transactional memory - -The i386 architecture supports additional memory ordering flags -to mark lock critical sections for hardware lock elision. -These must be specified in addition to an existing memory model to -atomic intrinsics. - -@table @code -@item __ATOMIC_HLE_ACQUIRE -Start lock elision on a lock variable. -Memory model must be @code{__ATOMIC_ACQUIRE} or stronger. -@item __ATOMIC_HLE_RELEASE -End lock elision on a lock variable. -Memory model must be @code{__ATOMIC_RELEASE} or stronger. -@end table - -When a lock acquire fails it's required for good performance to abort -the transaction quickly. This can be done with a @code{_mm_pause} - -@smallexample -#include <immintrin.h> // For _mm_pause - -/* Acquire lock with lock elision */ -while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) - _mm_pause(); /* Abort failed transaction */ -... -/* Free lock with lock elision */ -__atomic_clear(&lockvar, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); -@end smallexample - -@node Object Size Checking -@section Object Size Checking Built-in Functions -@findex __builtin_object_size -@findex __builtin___memcpy_chk -@findex __builtin___mempcpy_chk -@findex __builtin___memmove_chk -@findex __builtin___memset_chk -@findex __builtin___strcpy_chk -@findex __builtin___stpcpy_chk -@findex __builtin___strncpy_chk -@findex __builtin___strcat_chk -@findex __builtin___strncat_chk -@findex __builtin___sprintf_chk -@findex __builtin___snprintf_chk -@findex __builtin___vsprintf_chk -@findex __builtin___vsnprintf_chk -@findex __builtin___printf_chk -@findex __builtin___vprintf_chk -@findex __builtin___fprintf_chk -@findex __builtin___vfprintf_chk - -GCC implements a limited buffer overflow protection mechanism -that can prevent some buffer overflow attacks. - -@deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type}) -is a built-in construct that returns a constant number of bytes from -@var{ptr} to the end of the object @var{ptr} pointer points to -(if known at compile time). @code{__builtin_object_size} never evaluates -its arguments for side-effects. If there are any side-effects in them, it -returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} -for @var{type} 2 or 3. If there are multiple objects @var{ptr} can -point to and all of them are known at compile time, the returned number -is the maximum of remaining byte counts in those objects if @var{type} & 2 is -0 and minimum if nonzero. If it is not possible to determine which objects -@var{ptr} points to at compile time, @code{__builtin_object_size} should -return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} -for @var{type} 2 or 3. - -@var{type} is an integer constant from 0 to 3. If the least significant -bit is clear, objects are whole variables, if it is set, a closest -surrounding subobject is considered the object a pointer points to. -The second bit determines if maximum or minimum of remaining bytes -is computed. - -@smallexample -struct V @{ char buf1[10]; int b; char buf2[10]; @} var; -char *p = &var.buf1[1], *q = &var.b; - -/* Here the object p points to is var. */ -assert (__builtin_object_size (p, 0) == sizeof (var) - 1); -/* The subobject p points to is var.buf1. */ -assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); -/* The object q points to is var. */ -assert (__builtin_object_size (q, 0) - == (char *) (&var + 1) - (char *) &var.b); -/* The subobject q points to is var.b. */ -assert (__builtin_object_size (q, 1) == sizeof (var.b)); -@end smallexample -@end deftypefn - -There are built-in functions added for many common string operation -functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk} -built-in is provided. This built-in has an additional last argument, -which is the number of bytes remaining in object the @var{dest} -argument points to or @code{(size_t) -1} if the size is not known. - -The built-in functions are optimized into the normal string functions -like @code{memcpy} if the last argument is @code{(size_t) -1} or if -it is known at compile time that the destination object will not -be overflown. If the compiler can determine at compile time the -object will be always overflown, it issues a warning. - -The intended use can be e.g.@: - -@smallexample -#undef memcpy -#define bos0(dest) __builtin_object_size (dest, 0) -#define memcpy(dest, src, n) \ - __builtin___memcpy_chk (dest, src, n, bos0 (dest)) - -char *volatile p; -char buf[10]; -/* It is unknown what object p points to, so this is optimized - into plain memcpy - no checking is possible. */ -memcpy (p, "abcde", n); -/* Destination is known and length too. It is known at compile - time there will be no overflow. */ -memcpy (&buf[5], "abcde", 5); -/* Destination is known, but the length is not known at compile time. - This will result in __memcpy_chk call that can check for overflow - at run time. */ -memcpy (&buf[5], "abcde", n); -/* Destination is known and it is known at compile time there will - be overflow. There will be a warning and __memcpy_chk call that - will abort the program at run time. */ -memcpy (&buf[6], "abcde", 5); -@end smallexample - -Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, -@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, -@code{strcat} and @code{strncat}. - -There are also checking built-in functions for formatted output functions. -@smallexample -int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); -int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, - const char *fmt, ...); -int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, - va_list ap); -int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, - const char *fmt, va_list ap); -@end smallexample - -The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} -etc.@: functions and can contain implementation specific flags on what -additional security measures the checking function might take, such as -handling @code{%n} differently. - -The @var{os} argument is the object size @var{s} points to, like in the -other built-in functions. There is a small difference in the behavior -though, if @var{os} is @code{(size_t) -1}, the built-in functions are -optimized into the non-checking functions only if @var{flag} is 0, otherwise -the checking function is called with @var{os} argument set to -@code{(size_t) -1}. - -In addition to this, there are checking built-in functions -@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, -@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. -These have just one additional argument, @var{flag}, right before -format string @var{fmt}. If the compiler is able to optimize them to -@code{fputc} etc.@: functions, it does, otherwise the checking function -is called and the @var{flag} argument passed to it. - -@node Other Builtins -@section Other Built-in Functions Provided by GCC -@cindex built-in functions -@findex __builtin_fpclassify -@findex __builtin_isfinite -@findex __builtin_isnormal -@findex __builtin_isgreater -@findex __builtin_isgreaterequal -@findex __builtin_isinf_sign -@findex __builtin_isless -@findex __builtin_islessequal -@findex __builtin_islessgreater -@findex __builtin_isunordered -@findex __builtin_powi -@findex __builtin_powif -@findex __builtin_powil -@findex _Exit -@findex _exit -@findex abort -@findex abs -@findex acos -@findex acosf -@findex acosh -@findex acoshf -@findex acoshl -@findex acosl -@findex alloca -@findex asin -@findex asinf -@findex asinh -@findex asinhf -@findex asinhl -@findex asinl -@findex atan -@findex atan2 -@findex atan2f -@findex atan2l -@findex atanf -@findex atanh -@findex atanhf -@findex atanhl -@findex atanl -@findex bcmp -@findex bzero -@findex cabs -@findex cabsf -@findex cabsl -@findex cacos -@findex cacosf -@findex cacosh -@findex cacoshf -@findex cacoshl -@findex cacosl -@findex calloc -@findex carg -@findex cargf -@findex cargl -@findex casin -@findex casinf -@findex casinh -@findex casinhf -@findex casinhl -@findex casinl -@findex catan -@findex catanf -@findex catanh -@findex catanhf -@findex catanhl -@findex catanl -@findex cbrt -@findex cbrtf -@findex cbrtl -@findex ccos -@findex ccosf -@findex ccosh -@findex ccoshf -@findex ccoshl -@findex ccosl -@findex ceil -@findex ceilf -@findex ceill -@findex cexp -@findex cexpf -@findex cexpl -@findex cimag -@findex cimagf -@findex cimagl -@findex clog -@findex clogf -@findex clogl -@findex conj -@findex conjf -@findex conjl -@findex copysign -@findex copysignf -@findex copysignl -@findex cos -@findex cosf -@findex cosh -@findex coshf -@findex coshl -@findex cosl -@findex cpow -@findex cpowf -@findex cpowl -@findex cproj -@findex cprojf -@findex cprojl -@findex creal -@findex crealf -@findex creall -@findex csin -@findex csinf -@findex csinh -@findex csinhf -@findex csinhl -@findex csinl -@findex csqrt -@findex csqrtf -@findex csqrtl -@findex ctan -@findex ctanf -@findex ctanh -@findex ctanhf -@findex ctanhl -@findex ctanl -@findex dcgettext -@findex dgettext -@findex drem -@findex dremf -@findex dreml -@findex erf -@findex erfc -@findex erfcf -@findex erfcl -@findex erff -@findex erfl -@findex exit -@findex exp -@findex exp10 -@findex exp10f -@findex exp10l -@findex exp2 -@findex exp2f -@findex exp2l -@findex expf -@findex expl -@findex expm1 -@findex expm1f -@findex expm1l -@findex fabs -@findex fabsf -@findex fabsl -@findex fdim -@findex fdimf -@findex fdiml -@findex ffs -@findex floor -@findex floorf -@findex floorl -@findex fma -@findex fmaf -@findex fmal -@findex fmax -@findex fmaxf -@findex fmaxl -@findex fmin -@findex fminf -@findex fminl -@findex fmod -@findex fmodf -@findex fmodl -@findex fprintf -@findex fprintf_unlocked -@findex fputs -@findex fputs_unlocked -@findex frexp -@findex frexpf -@findex frexpl -@findex fscanf -@findex gamma -@findex gammaf -@findex gammal -@findex gamma_r -@findex gammaf_r -@findex gammal_r -@findex gettext -@findex hypot -@findex hypotf -@findex hypotl -@findex ilogb -@findex ilogbf -@findex ilogbl -@findex imaxabs -@findex index -@findex isalnum -@findex isalpha -@findex isascii -@findex isblank -@findex iscntrl -@findex isdigit -@findex isgraph -@findex islower -@findex isprint -@findex ispunct -@findex isspace -@findex isupper -@findex iswalnum -@findex iswalpha -@findex iswblank -@findex iswcntrl -@findex iswdigit -@findex iswgraph -@findex iswlower -@findex iswprint -@findex iswpunct -@findex iswspace -@findex iswupper -@findex iswxdigit -@findex isxdigit -@findex j0 -@findex j0f -@findex j0l -@findex j1 -@findex j1f -@findex j1l -@findex jn -@findex jnf -@findex jnl -@findex labs -@findex ldexp -@findex ldexpf -@findex ldexpl -@findex lgamma -@findex lgammaf -@findex lgammal -@findex lgamma_r -@findex lgammaf_r -@findex lgammal_r -@findex llabs -@findex llrint -@findex llrintf -@findex llrintl -@findex llround -@findex llroundf -@findex llroundl -@findex log -@findex log10 -@findex log10f -@findex log10l -@findex log1p -@findex log1pf -@findex log1pl -@findex log2 -@findex log2f -@findex log2l -@findex logb -@findex logbf -@findex logbl -@findex logf -@findex logl -@findex lrint -@findex lrintf -@findex lrintl -@findex lround -@findex lroundf -@findex lroundl -@findex malloc -@findex memchr -@findex memcmp -@findex memcpy -@findex mempcpy -@findex memset -@findex modf -@findex modff -@findex modfl -@findex nearbyint -@findex nearbyintf -@findex nearbyintl -@findex nextafter -@findex nextafterf -@findex nextafterl -@findex nexttoward -@findex nexttowardf -@findex nexttowardl -@findex pow -@findex pow10 -@findex pow10f -@findex pow10l -@findex powf -@findex powl -@findex printf -@findex printf_unlocked -@findex putchar -@findex puts -@findex remainder -@findex remainderf -@findex remainderl -@findex remquo -@findex remquof -@findex remquol -@findex rindex -@findex rint -@findex rintf -@findex rintl -@findex round -@findex roundf -@findex roundl -@findex scalb -@findex scalbf -@findex scalbl -@findex scalbln -@findex scalblnf -@findex scalblnf -@findex scalbn -@findex scalbnf -@findex scanfnl -@findex signbit -@findex signbitf -@findex signbitl -@findex signbitd32 -@findex signbitd64 -@findex signbitd128 -@findex significand -@findex significandf -@findex significandl -@findex sin -@findex sincos -@findex sincosf -@findex sincosl -@findex sinf -@findex sinh -@findex sinhf -@findex sinhl -@findex sinl -@findex snprintf -@findex sprintf -@findex sqrt -@findex sqrtf -@findex sqrtl -@findex sscanf -@findex stpcpy -@findex stpncpy -@findex strcasecmp -@findex strcat -@findex strchr -@findex strcmp -@findex strcpy -@findex strcspn -@findex strdup -@findex strfmon -@findex strftime -@findex strlen -@findex strncasecmp -@findex strncat -@findex strncmp -@findex strncpy -@findex strndup -@findex strpbrk -@findex strrchr -@findex strspn -@findex strstr -@findex tan -@findex tanf -@findex tanh -@findex tanhf -@findex tanhl -@findex tanl -@findex tgamma -@findex tgammaf -@findex tgammal -@findex toascii -@findex tolower -@findex toupper -@findex towlower -@findex towupper -@findex trunc -@findex truncf -@findex truncl -@findex vfprintf -@findex vfscanf -@findex vprintf -@findex vscanf -@findex vsnprintf -@findex vsprintf -@findex vsscanf -@findex y0 -@findex y0f -@findex y0l -@findex y1 -@findex y1f -@findex y1l -@findex yn -@findex ynf -@findex ynl - -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 are not -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_} are always -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 is -emitted. - -@opindex ansi -@opindex std -Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, -@option{-std=c99} or @option{-std=c11}), the functions -@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, -@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, -@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, -@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, -@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, -@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, -@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, -@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, -@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, -@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, -@code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb}, -@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, -@code{signbitd64}, @code{signbitd128}, @code{significandf}, -@code{significandl}, @code{significand}, @code{sincosf}, -@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, -@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, -@code{strndup}, @code{toascii}, @code{y0f}, @code{y0l}, @code{y0}, -@code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and -@code{yn} -may be handled as built-in functions. -All these functions have corresponding versions -prefixed with @code{__builtin_}, which may be used even in strict C90 -mode. - -The ISO C99 functions -@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, -@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, -@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, -@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, -@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, -@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, -@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, -@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, -@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, -@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, -@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, -@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, -@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, -@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, -@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, -@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, -@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, -@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, -@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, -@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, -@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, -@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, -@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, -@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, -@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, -@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, -@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, -@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, -@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, -@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, -@code{nextafterf}, @code{nextafterl}, @code{nextafter}, -@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, -@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, -@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, -@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, -@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, -@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, -@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, -@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} -are handled as built-in functions -except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). - -There are also built-in versions of the ISO C99 functions -@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, -@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, -@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, -@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, -@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, -@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, -@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, -@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, -@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} -that are recognized in any mode since ISO C90 reserves these names for -the purpose to which ISO C99 puts them. All these functions have -corresponding versions prefixed with @code{__builtin_}. - -The ISO C94 functions -@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, -@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, -@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and -@code{towupper} -are handled as built-in functions -except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). - -The ISO C90 functions -@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, -@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, -@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, -@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf}, -@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, -@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, -@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, -@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, -@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, -@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, -@code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf}, -@code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, -@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, -@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, -@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, -@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} -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. -In the same fashion, GCC provides @code{fpclassify}, @code{isfinite}, -@code{isinf_sign} and @code{isnormal} built-ins used with -@code{__builtin_} prefixed. The @code{isinf} and @code{isnan} -built-in functions appear both with and without the @code{__builtin_} prefix. - -@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 not considered to be compatible with another -@code{enum} type even if both are compatible with the same integer -type; this is what the C standard specifies. -For example, @code{enum @{foo, bar@}} is not similar to -@code{enum @{hot, dog@}}. - -You typically use this function in code whose execution varies -depending on the arguments' types. For example: - -@smallexample -#define foo(x) \ - (@{ \ - typeof (x) tmp = (x); \ - 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 an -integer constant expression, is nonzero. Otherwise it returns @var{exp2}. - -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 is 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} @var{type} __builtin_complex (@var{real}, @var{imag}) - -The built-in function @code{__builtin_complex} is provided for use in -implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and -@code{CMPLXL}. @var{real} and @var{imag} must have the same type, a -real binary floating-point type, and the result has the corresponding -complex type with real and imaginary parts @var{real} and @var{imag}. -Unlike @samp{@var{real} + I * @var{imag}}, this works even when -infinities, NaNs and negative zeros are involved. - -@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 typically use this function in an embedded application where -memory is 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 -never returns 1 when you call the inline function with a string constant -or compound literal (@pxref{Compound Literals}) and does 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, - /* @r{@dots{}} */ -@}; -@end smallexample - -@noindent -This is an acceptable initializer even if @var{EXPRESSION} is not a -constant expression, including the case where -@code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be -folded to a constant but @var{EXPRESSION} contains operands that are -not otherwise permitted in a static initializer (for example, -@code{0 && foo ()}). 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 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 -indicates 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)) - foo (*ptr); -@end smallexample - -@noindent -when testing pointer or floating-point values. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_trap (void) -This function causes the program to exit abnormally. GCC implements -this function by using a target-dependent mechanism (such as -intentionally executing an illegal instruction) or by calling -@code{abort}. The mechanism used may vary from release to release so -you should not rely on any particular implementation. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_unreachable (void) -If control flow reaches the point of the @code{__builtin_unreachable}, -the program is undefined. It is useful in situations where the -compiler cannot deduce the unreachability of the code. - -One such case is immediately following an @code{asm} statement that -either never terminates, or one that transfers control elsewhere -and never returns. In this example, without the -@code{__builtin_unreachable}, GCC issues a warning that control -reaches the end of a non-void function. It also generates code -to return after the @code{asm}. - -@smallexample -int f (int c, int v) -@{ - if (c) - @{ - return v; - @} - else - @{ - asm("jmp error_handler"); - __builtin_unreachable (); - @} -@} -@end smallexample - -@noindent -Because the @code{asm} statement unconditionally transfers control out -of the function, control never reaches the end of the function -body. The @code{__builtin_unreachable} is in fact unreachable and -communicates this fact to the compiler. - -Another use for @code{__builtin_unreachable} is following a call a -function that never returns but that is not declared -@code{__attribute__((noreturn))}, as in this example: - -@smallexample -void function_that_never_returns (void); - -int g (int c) -@{ - if (c) - @{ - return 1; - @} - else - @{ - function_that_never_returns (); - __builtin_unreachable (); - @} -@} -@end smallexample - -@end deftypefn - -@deftypefn {Built-in Function} void *__builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...) -This function returns its first argument, and allows the compiler -to assume that the returned pointer is at least @var{align} bytes -aligned. This built-in can have either two or three arguments, -if it has three, the third argument should have integer type, and -if it is nonzero means misalignment offset. For example: - -@smallexample -void *x = __builtin_assume_aligned (arg, 16); -@end smallexample - -@noindent -means that the compiler can assume @code{x}, set to @code{arg}, is at least -16-byte aligned, while: - -@smallexample -void *x = __builtin_assume_aligned (arg, 32, 8); -@end smallexample - -@noindent -means that the compiler can assume for @code{x}, set to @code{arg}, that -@code{(char *) x - 8} is 32-byte aligned. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_LINE () -This function is the equivalent to the preprocessor @code{__LINE__} -macro and returns the line number of the invocation of the built-in. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_FUNCTION () -This function is the equivalent to the preprocessor @code{__FUNCTION__} -macro and returns the function name the invocation of the built-in is in. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_FILE () -This function is the equivalent to the preprocessor @code{__FILE__} -macro and returns the file name the invocation of the built-in is in. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin___clear_cache (char *@var{begin}, char *@var{end}) -This function is used to flush the processor's instruction cache for -the region of memory between @var{begin} inclusive and @var{end} -exclusive. Some targets require that the instruction cache be -flushed, after modifying memory containing code, in order to obtain -deterministic behavior. - -If the target does not require instruction cache flushes, -@code{__builtin___clear_cache} has no effect. Otherwise either -instructions are emitted in-line to clear the instruction cache or a -call to the @code{__clear_cache} function in libgcc is made. -@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 are 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); - /* @r{@dots{}} */ - @} -@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} does not fault if @code{p->next} is not a valid -address, but evaluation faults 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 - -@deftypefn {Built-in Function} double __builtin_huge_val (void) -Returns a positive infinity, if supported by the floating-point format, -else @code{DBL_MAX}. This function is suitable for implementing the -ISO C macro @code{HUGE_VAL}. -@end deftypefn - -@deftypefn {Built-in Function} float __builtin_huge_valf (void) -Similar to @code{__builtin_huge_val}, except the return type is @code{float}. -@end deftypefn - -@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) -Similar to @code{__builtin_huge_val}, except the return -type is @code{long double}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...) -This built-in implements the C99 fpclassify functionality. The first -five int arguments should be the target library's notion of the -possible FP classes and are used for return values. They must be -constant values and they must appear in this order: @code{FP_NAN}, -@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and -@code{FP_ZERO}. The ellipsis is for exactly one floating-point value -to classify. GCC treats the last argument as type-generic, which -means it does not do default promotion from float to double. -@end deftypefn - -@deftypefn {Built-in Function} double __builtin_inf (void) -Similar to @code{__builtin_huge_val}, except a warning is generated -if the target floating-point format does not support infinities. -@end deftypefn - -@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. -@end deftypefn - -@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. -@end deftypefn - -@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. -@end deftypefn - -@deftypefn {Built-in Function} float __builtin_inff (void) -Similar to @code{__builtin_inf}, except the return type is @code{float}. -This function is suitable for implementing the ISO C99 macro @code{INFINITY}. -@end deftypefn - -@deftypefn {Built-in Function} {long double} __builtin_infl (void) -Similar to @code{__builtin_inf}, except the return -type is @code{long double}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_isinf_sign (...) -Similar to @code{isinf}, except the return value is negative for -an argument of @code{-Inf}. Note while the parameter list is an -ellipsis, this function only accepts exactly one floating-point -argument. GCC treats this parameter as type-generic, which means it -does not do default promotion from float to double. -@end deftypefn - -@deftypefn {Built-in Function} double __builtin_nan (const char *str) -This is an implementation of the ISO C99 function @code{nan}. - -Since ISO C99 defines this function in terms of @code{strtod}, which we -do not implement, a description of the parsing is in order. The string -is parsed as by @code{strtol}; that is, the base is recognized by -leading @samp{0} or @samp{0x} prefixes. The number parsed is placed -in the significand such that the least significant bit of the number -is at the least significant bit of the significand. The number is -truncated to fit the significand field provided. The significand is -forced to be a quiet NaN@. - -This function, if given a string literal all of which would have been -consumed by @code{strtol}, is evaluated early enough that it is considered a -compile-time constant. -@end deftypefn - -@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) -Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. -@end deftypefn - -@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) -Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. -@end deftypefn - -@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) -Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. -@end deftypefn - -@deftypefn {Built-in Function} float __builtin_nanf (const char *str) -Similar to @code{__builtin_nan}, except the return type is @code{float}. -@end deftypefn - -@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) -Similar to @code{__builtin_nan}, except the return type is @code{long double}. -@end deftypefn - -@deftypefn {Built-in Function} double __builtin_nans (const char *str) -Similar to @code{__builtin_nan}, except the significand is forced -to be a signaling NaN@. The @code{nans} function is proposed by -@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. -@end deftypefn - -@deftypefn {Built-in Function} float __builtin_nansf (const char *str) -Similar to @code{__builtin_nans}, except the return type is @code{float}. -@end deftypefn - -@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) -Similar to @code{__builtin_nans}, except the return type is @code{long double}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_ffs (unsigned int x) -Returns one plus the index of the least significant 1-bit of @var{x}, or -if @var{x} is zero, returns zero. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) -Returns the number of leading 0-bits in @var{x}, starting at the most -significant bit position. If @var{x} is 0, the result is undefined. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) -Returns the number of trailing 0-bits in @var{x}, starting at the least -significant bit position. If @var{x} is 0, the result is undefined. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_clrsb (int x) -Returns the number of leading redundant sign bits in @var{x}, i.e.@: the -number of bits following the most significant bit that are identical -to it. There are no special cases for 0 or other values. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) -Returns the number of 1-bits in @var{x}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) -Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} -modulo 2. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_ffsl (unsigned long) -Similar to @code{__builtin_ffs}, except the argument type is -@code{unsigned long}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) -Similar to @code{__builtin_clz}, except the argument type is -@code{unsigned long}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) -Similar to @code{__builtin_ctz}, except the argument type is -@code{unsigned long}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_clrsbl (long) -Similar to @code{__builtin_clrsb}, except the argument type is -@code{long}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) -Similar to @code{__builtin_popcount}, except the argument type is -@code{unsigned long}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) -Similar to @code{__builtin_parity}, except the argument type is -@code{unsigned long}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_ffsll (unsigned long long) -Similar to @code{__builtin_ffs}, except the argument type is -@code{unsigned long long}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) -Similar to @code{__builtin_clz}, except the argument type is -@code{unsigned long long}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) -Similar to @code{__builtin_ctz}, except the argument type is -@code{unsigned long long}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_clrsbll (long long) -Similar to @code{__builtin_clrsb}, except the argument type is -@code{long long}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) -Similar to @code{__builtin_popcount}, except the argument type is -@code{unsigned long long}. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) -Similar to @code{__builtin_parity}, except the argument type is -@code{unsigned long long}. -@end deftypefn - -@deftypefn {Built-in Function} double __builtin_powi (double, int) -Returns the first argument raised to the power of the second. Unlike the -@code{pow} function no guarantees about precision and rounding are made. -@end deftypefn - -@deftypefn {Built-in Function} float __builtin_powif (float, int) -Similar to @code{__builtin_powi}, except the argument and return types -are @code{float}. -@end deftypefn - -@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) -Similar to @code{__builtin_powi}, except the argument and return types -are @code{long double}. -@end deftypefn - -@deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x) -Returns @var{x} with the order of the bytes reversed; for example, -@code{0xaabb} becomes @code{0xbbaa}. Byte here always means -exactly 8 bits. -@end deftypefn - -@deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x) -Similar to @code{__builtin_bswap16}, except the argument and return types -are 32 bit. -@end deftypefn - -@deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x) -Similar to @code{__builtin_bswap32}, except the argument and return types -are 64 bit. -@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 -* Alpha Built-in Functions:: -* ARM iWMMXt Built-in Functions:: -* ARM NEON Intrinsics:: -* AVR Built-in Functions:: -* Blackfin Built-in Functions:: -* FR-V Built-in Functions:: -* X86 Built-in Functions:: -* X86 transactional memory intrinsics:: -* MIPS DSP Built-in Functions:: -* MIPS Paired-Single Support:: -* MIPS Loongson Built-in Functions:: -* Other MIPS Built-in Functions:: -* picoChip Built-in Functions:: -* PowerPC Built-in Functions:: -* PowerPC AltiVec/VSX Built-in Functions:: -* RX Built-in Functions:: -* SH Built-in Functions:: -* SPARC VIS Built-in Functions:: -* SPU Built-in Functions:: -* TI C6X Built-in Functions:: -* TILE-Gx Built-in Functions:: -* TILEPro Built-in Functions:: -@end menu - -@node Alpha Built-in Functions -@subsection Alpha Built-in Functions - -These built-in functions are available for the Alpha family of -processors, depending on the command-line switches used. - -The following built-in functions are always available. They -all generate the machine instruction that is part of the name. - -@smallexample -long __builtin_alpha_implver (void) -long __builtin_alpha_rpcc (void) -long __builtin_alpha_amask (long) -long __builtin_alpha_cmpbge (long, long) -long __builtin_alpha_extbl (long, long) -long __builtin_alpha_extwl (long, long) -long __builtin_alpha_extll (long, long) -long __builtin_alpha_extql (long, long) -long __builtin_alpha_extwh (long, long) -long __builtin_alpha_extlh (long, long) -long __builtin_alpha_extqh (long, long) -long __builtin_alpha_insbl (long, long) -long __builtin_alpha_inswl (long, long) -long __builtin_alpha_insll (long, long) -long __builtin_alpha_insql (long, long) -long __builtin_alpha_inswh (long, long) -long __builtin_alpha_inslh (long, long) -long __builtin_alpha_insqh (long, long) -long __builtin_alpha_mskbl (long, long) -long __builtin_alpha_mskwl (long, long) -long __builtin_alpha_mskll (long, long) -long __builtin_alpha_mskql (long, long) -long __builtin_alpha_mskwh (long, long) -long __builtin_alpha_msklh (long, long) -long __builtin_alpha_mskqh (long, long) -long __builtin_alpha_umulh (long, long) -long __builtin_alpha_zap (long, long) -long __builtin_alpha_zapnot (long, long) -@end smallexample - -The following built-in functions are always with @option{-mmax} -or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or -later. They all generate the machine instruction that is part -of the name. - -@smallexample -long __builtin_alpha_pklb (long) -long __builtin_alpha_pkwb (long) -long __builtin_alpha_unpkbl (long) -long __builtin_alpha_unpkbw (long) -long __builtin_alpha_minub8 (long, long) -long __builtin_alpha_minsb8 (long, long) -long __builtin_alpha_minuw4 (long, long) -long __builtin_alpha_minsw4 (long, long) -long __builtin_alpha_maxub8 (long, long) -long __builtin_alpha_maxsb8 (long, long) -long __builtin_alpha_maxuw4 (long, long) -long __builtin_alpha_maxsw4 (long, long) -long __builtin_alpha_perr (long, long) -@end smallexample - -The following built-in functions are always with @option{-mcix} -or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or -later. They all generate the machine instruction that is part -of the name. - -@smallexample -long __builtin_alpha_cttz (long) -long __builtin_alpha_ctlz (long) -long __builtin_alpha_ctpop (long) -@end smallexample - -The following built-in functions are available on systems that use the OSF/1 -PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} -PAL calls, but when invoked with @option{-mtls-kernel}, they invoke -@code{rdval} and @code{wrval}. - -@smallexample -void *__builtin_thread_pointer (void) -void __builtin_set_thread_pointer (void *) -@end smallexample - -@node ARM iWMMXt Built-in Functions -@subsection ARM iWMMXt Built-in Functions - -These built-in functions are available for the ARM family of -processors when the @option{-mcpu=iwmmxt} switch is used: - -@smallexample -typedef int v2si __attribute__ ((vector_size (8))); -typedef short v4hi __attribute__ ((vector_size (8))); -typedef char v8qi __attribute__ ((vector_size (8))); - -int __builtin_arm_getwcgr0 (void) -void __builtin_arm_setwcgr0 (int) -int __builtin_arm_getwcgr1 (void) -void __builtin_arm_setwcgr1 (int) -int __builtin_arm_getwcgr2 (void) -void __builtin_arm_setwcgr2 (int) -int __builtin_arm_getwcgr3 (void) -void __builtin_arm_setwcgr3 (int) -int __builtin_arm_textrmsb (v8qi, int) -int __builtin_arm_textrmsh (v4hi, int) -int __builtin_arm_textrmsw (v2si, int) -int __builtin_arm_textrmub (v8qi, int) -int __builtin_arm_textrmuh (v4hi, int) -int __builtin_arm_textrmuw (v2si, int) -v8qi __builtin_arm_tinsrb (v8qi, int, int) -v4hi __builtin_arm_tinsrh (v4hi, int, int) -v2si __builtin_arm_tinsrw (v2si, int, int) -long long __builtin_arm_tmia (long long, int, int) -long long __builtin_arm_tmiabb (long long, int, int) -long long __builtin_arm_tmiabt (long long, int, int) -long long __builtin_arm_tmiaph (long long, int, int) -long long __builtin_arm_tmiatb (long long, int, int) -long long __builtin_arm_tmiatt (long long, int, int) -int __builtin_arm_tmovmskb (v8qi) -int __builtin_arm_tmovmskh (v4hi) -int __builtin_arm_tmovmskw (v2si) -long long __builtin_arm_waccb (v8qi) -long long __builtin_arm_wacch (v4hi) -long long __builtin_arm_waccw (v2si) -v8qi __builtin_arm_waddb (v8qi, v8qi) -v8qi __builtin_arm_waddbss (v8qi, v8qi) -v8qi __builtin_arm_waddbus (v8qi, v8qi) -v4hi __builtin_arm_waddh (v4hi, v4hi) -v4hi __builtin_arm_waddhss (v4hi, v4hi) -v4hi __builtin_arm_waddhus (v4hi, v4hi) -v2si __builtin_arm_waddw (v2si, v2si) -v2si __builtin_arm_waddwss (v2si, v2si) -v2si __builtin_arm_waddwus (v2si, v2si) -v8qi __builtin_arm_walign (v8qi, v8qi, int) -long long __builtin_arm_wand(long long, long long) -long long __builtin_arm_wandn (long long, long long) -v8qi __builtin_arm_wavg2b (v8qi, v8qi) -v8qi __builtin_arm_wavg2br (v8qi, v8qi) -v4hi __builtin_arm_wavg2h (v4hi, v4hi) -v4hi __builtin_arm_wavg2hr (v4hi, v4hi) -v8qi __builtin_arm_wcmpeqb (v8qi, v8qi) -v4hi __builtin_arm_wcmpeqh (v4hi, v4hi) -v2si __builtin_arm_wcmpeqw (v2si, v2si) -v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) -v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) -v2si __builtin_arm_wcmpgtsw (v2si, v2si) -v8qi __builtin_arm_wcmpgtub (v8qi, v8qi) -v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) -v2si __builtin_arm_wcmpgtuw (v2si, v2si) -long long __builtin_arm_wmacs (long long, v4hi, v4hi) -long long __builtin_arm_wmacsz (v4hi, v4hi) -long long __builtin_arm_wmacu (long long, v4hi, v4hi) -long long __builtin_arm_wmacuz (v4hi, v4hi) -v4hi __builtin_arm_wmadds (v4hi, v4hi) -v4hi __builtin_arm_wmaddu (v4hi, v4hi) -v8qi __builtin_arm_wmaxsb (v8qi, v8qi) -v4hi __builtin_arm_wmaxsh (v4hi, v4hi) -v2si __builtin_arm_wmaxsw (v2si, v2si) -v8qi __builtin_arm_wmaxub (v8qi, v8qi) -v4hi __builtin_arm_wmaxuh (v4hi, v4hi) -v2si __builtin_arm_wmaxuw (v2si, v2si) -v8qi __builtin_arm_wminsb (v8qi, v8qi) -v4hi __builtin_arm_wminsh (v4hi, v4hi) -v2si __builtin_arm_wminsw (v2si, v2si) -v8qi __builtin_arm_wminub (v8qi, v8qi) -v4hi __builtin_arm_wminuh (v4hi, v4hi) -v2si __builtin_arm_wminuw (v2si, v2si) -v4hi __builtin_arm_wmulsm (v4hi, v4hi) -v4hi __builtin_arm_wmulul (v4hi, v4hi) -v4hi __builtin_arm_wmulum (v4hi, v4hi) -long long __builtin_arm_wor (long long, long long) -v2si __builtin_arm_wpackdss (long long, long long) -v2si __builtin_arm_wpackdus (long long, long long) -v8qi __builtin_arm_wpackhss (v4hi, v4hi) -v8qi __builtin_arm_wpackhus (v4hi, v4hi) -v4hi __builtin_arm_wpackwss (v2si, v2si) -v4hi __builtin_arm_wpackwus (v2si, v2si) -long long __builtin_arm_wrord (long long, long long) -long long __builtin_arm_wrordi (long long, int) -v4hi __builtin_arm_wrorh (v4hi, long long) -v4hi __builtin_arm_wrorhi (v4hi, int) -v2si __builtin_arm_wrorw (v2si, long long) -v2si __builtin_arm_wrorwi (v2si, int) -v2si __builtin_arm_wsadb (v2si, v8qi, v8qi) -v2si __builtin_arm_wsadbz (v8qi, v8qi) -v2si __builtin_arm_wsadh (v2si, v4hi, v4hi) -v2si __builtin_arm_wsadhz (v4hi, v4hi) -v4hi __builtin_arm_wshufh (v4hi, int) -long long __builtin_arm_wslld (long long, long long) -long long __builtin_arm_wslldi (long long, int) -v4hi __builtin_arm_wsllh (v4hi, long long) -v4hi __builtin_arm_wsllhi (v4hi, int) -v2si __builtin_arm_wsllw (v2si, long long) -v2si __builtin_arm_wsllwi (v2si, int) -long long __builtin_arm_wsrad (long long, long long) -long long __builtin_arm_wsradi (long long, int) -v4hi __builtin_arm_wsrah (v4hi, long long) -v4hi __builtin_arm_wsrahi (v4hi, int) -v2si __builtin_arm_wsraw (v2si, long long) -v2si __builtin_arm_wsrawi (v2si, int) -long long __builtin_arm_wsrld (long long, long long) -long long __builtin_arm_wsrldi (long long, int) -v4hi __builtin_arm_wsrlh (v4hi, long long) -v4hi __builtin_arm_wsrlhi (v4hi, int) -v2si __builtin_arm_wsrlw (v2si, long long) -v2si __builtin_arm_wsrlwi (v2si, int) -v8qi __builtin_arm_wsubb (v8qi, v8qi) -v8qi __builtin_arm_wsubbss (v8qi, v8qi) -v8qi __builtin_arm_wsubbus (v8qi, v8qi) -v4hi __builtin_arm_wsubh (v4hi, v4hi) -v4hi __builtin_arm_wsubhss (v4hi, v4hi) -v4hi __builtin_arm_wsubhus (v4hi, v4hi) -v2si __builtin_arm_wsubw (v2si, v2si) -v2si __builtin_arm_wsubwss (v2si, v2si) -v2si __builtin_arm_wsubwus (v2si, v2si) -v4hi __builtin_arm_wunpckehsb (v8qi) -v2si __builtin_arm_wunpckehsh (v4hi) -long long __builtin_arm_wunpckehsw (v2si) -v4hi __builtin_arm_wunpckehub (v8qi) -v2si __builtin_arm_wunpckehuh (v4hi) -long long __builtin_arm_wunpckehuw (v2si) -v4hi __builtin_arm_wunpckelsb (v8qi) -v2si __builtin_arm_wunpckelsh (v4hi) -long long __builtin_arm_wunpckelsw (v2si) -v4hi __builtin_arm_wunpckelub (v8qi) -v2si __builtin_arm_wunpckeluh (v4hi) -long long __builtin_arm_wunpckeluw (v2si) -v8qi __builtin_arm_wunpckihb (v8qi, v8qi) -v4hi __builtin_arm_wunpckihh (v4hi, v4hi) -v2si __builtin_arm_wunpckihw (v2si, v2si) -v8qi __builtin_arm_wunpckilb (v8qi, v8qi) -v4hi __builtin_arm_wunpckilh (v4hi, v4hi) -v2si __builtin_arm_wunpckilw (v2si, v2si) -long long __builtin_arm_wxor (long long, long long) -long long __builtin_arm_wzero () -@end smallexample - -@node ARM NEON Intrinsics -@subsection ARM NEON Intrinsics - -These built-in intrinsics for the ARM Advanced SIMD extension are available -when the @option{-mfpu=neon} switch is used: - -@include arm-neon-intrinsics.texi - -@node AVR Built-in Functions -@subsection AVR Built-in Functions - -For each built-in function for AVR, there is an equally named, -uppercase built-in macro defined. That way users can easily query if -or if not a specific built-in is implemented or not. For example, if -@code{__builtin_avr_nop} is available the macro -@code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise. - -The following built-in functions map to the respective machine -instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep}, -@code{wdr}, @code{swap}, @code{fmul}, @code{fmuls} -resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented -as library call if no hardware multiplier is available. - -@smallexample -void __builtin_avr_nop (void) -void __builtin_avr_sei (void) -void __builtin_avr_cli (void) -void __builtin_avr_sleep (void) -void __builtin_avr_wdr (void) -unsigned char __builtin_avr_swap (unsigned char) -unsigned int __builtin_avr_fmul (unsigned char, unsigned char) -int __builtin_avr_fmuls (char, char) -int __builtin_avr_fmulsu (char, unsigned char) -@end smallexample - -In order to delay execution for a specific number of cycles, GCC -implements -@smallexample -void __builtin_avr_delay_cycles (unsigned long ticks) -@end smallexample - -@noindent -@code{ticks} is the number of ticks to delay execution. Note that this -built-in does not take into account the effect of interrupts that -might increase delay time. @code{ticks} must be a compile-time -integer constant; delays with a variable number of cycles are not supported. - -@smallexample -char __builtin_avr_flash_segment (const __memx void*) -@end smallexample - -@noindent -This built-in takes a byte address to the 24-bit -@ref{AVR Named Address Spaces,address space} @code{__memx} and returns -the number of the flash segment (the 64 KiB chunk) where the address -points to. Counting starts at @code{0}. -If the address does not point to flash memory, return @code{-1}. - -@smallexample -unsigned char __builtin_avr_insert_bits (unsigned long map, unsigned char bits, unsigned char val) -@end smallexample - -@noindent -Insert bits from @var{bits} into @var{val} and return the resulting -value. The nibbles of @var{map} determine how the insertion is -performed: Let @var{X} be the @var{n}-th nibble of @var{map} -@enumerate -@item If @var{X} is @code{0xf}, -then the @var{n}-th bit of @var{val} is returned unaltered. - -@item If X is in the range 0@dots{}7, -then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits} - -@item If X is in the range 8@dots{}@code{0xe}, -then the @var{n}-th result bit is undefined. -@end enumerate - -@noindent -One typical use case for this built-in is adjusting input and -output values to non-contiguous port layouts. Some examples: - -@smallexample -// same as val, bits is unused -__builtin_avr_insert_bits (0xffffffff, bits, val) -@end smallexample - -@smallexample -// same as bits, val is unused -__builtin_avr_insert_bits (0x76543210, bits, val) -@end smallexample - -@smallexample -// same as rotating bits by 4 -__builtin_avr_insert_bits (0x32107654, bits, 0) -@end smallexample - -@smallexample -// high nibble of result is the high nibble of val -// low nibble of result is the low nibble of bits -__builtin_avr_insert_bits (0xffff3210, bits, val) -@end smallexample - -@smallexample -// reverse the bit order of bits -__builtin_avr_insert_bits (0x01234567, bits, 0) -@end smallexample - -@node Blackfin Built-in Functions -@subsection Blackfin Built-in Functions - -Currently, there are two Blackfin-specific built-in functions. These are -used for generating @code{CSYNC} and @code{SSYNC} machine insns without -using inline assembly; by using these built-in functions the compiler can -automatically add workarounds for hardware errata involving these -instructions. These functions are named as follows: - -@smallexample -void __builtin_bfin_csync (void) -void __builtin_bfin_ssync (void) -@end smallexample - -@node FR-V Built-in Functions -@subsection FR-V Built-in Functions - -GCC provides many FR-V-specific built-in functions. In general, -these functions are intended to be compatible with those described -by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu -Semiconductor}. The two exceptions are @code{__MDUNPACKH} and -@code{__MBTOHE}, the GCC forms of which pass 128-bit values by -pointer rather than by value. - -Most of the functions are named after specific FR-V instructions. -Such functions are said to be ``directly mapped'' and are summarized -here in tabular form. - -@menu -* Argument Types:: -* Directly-mapped Integer Functions:: -* Directly-mapped Media Functions:: -* Raw read/write Functions:: -* Other Built-in Functions:: -@end menu - -@node Argument Types -@subsubsection Argument Types - -The arguments to the built-in functions can be divided into three groups: -register numbers, compile-time constants and run-time values. In order -to make this classification clear at a glance, the arguments and return -values are given the following pseudo types: - -@multitable @columnfractions .20 .30 .15 .35 -@item Pseudo type @tab Real C type @tab Constant? @tab Description -@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword -@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word -@item @code{sw1} @tab @code{int} @tab No @tab a signed word -@item @code{uw2} @tab @code{unsigned long long} @tab No -@tab an unsigned doubleword -@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword -@item @code{const} @tab @code{int} @tab Yes @tab an integer constant -@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number -@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number -@end multitable - -These pseudo types are not defined by GCC, they are simply a notational -convenience used in this manual. - -Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} -and @code{sw2} are evaluated at run time. They correspond to -register operands in the underlying FR-V instructions. - -@code{const} arguments represent immediate operands in the underlying -FR-V instructions. They must be compile-time constants. - -@code{acc} arguments are evaluated at compile time and specify the number -of an accumulator register. For example, an @code{acc} argument of 2 -selects the ACC2 register. - -@code{iacc} arguments are similar to @code{acc} arguments but specify the -number of an IACC register. See @pxref{Other Built-in Functions} -for more details. - -@node Directly-mapped Integer Functions -@subsubsection Directly-mapped Integer Functions - -The functions listed below map directly to FR-V I-type instructions. - -@multitable @columnfractions .45 .32 .23 -@item Function prototype @tab Example usage @tab Assembly output -@item @code{sw1 __ADDSS (sw1, sw1)} -@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} -@tab @code{ADDSS @var{a},@var{b},@var{c}} -@item @code{sw1 __SCAN (sw1, sw1)} -@tab @code{@var{c} = __SCAN (@var{a}, @var{b})} -@tab @code{SCAN @var{a},@var{b},@var{c}} -@item @code{sw1 __SCUTSS (sw1)} -@tab @code{@var{b} = __SCUTSS (@var{a})} -@tab @code{SCUTSS @var{a},@var{b}} -@item @code{sw1 __SLASS (sw1, sw1)} -@tab @code{@var{c} = __SLASS (@var{a}, @var{b})} -@tab @code{SLASS @var{a},@var{b},@var{c}} -@item @code{void __SMASS (sw1, sw1)} -@tab @code{__SMASS (@var{a}, @var{b})} -@tab @code{SMASS @var{a},@var{b}} -@item @code{void __SMSSS (sw1, sw1)} -@tab @code{__SMSSS (@var{a}, @var{b})} -@tab @code{SMSSS @var{a},@var{b}} -@item @code{void __SMU (sw1, sw1)} -@tab @code{__SMU (@var{a}, @var{b})} -@tab @code{SMU @var{a},@var{b}} -@item @code{sw2 __SMUL (sw1, sw1)} -@tab @code{@var{c} = __SMUL (@var{a}, @var{b})} -@tab @code{SMUL @var{a},@var{b},@var{c}} -@item @code{sw1 __SUBSS (sw1, sw1)} -@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} -@tab @code{SUBSS @var{a},@var{b},@var{c}} -@item @code{uw2 __UMUL (uw1, uw1)} -@tab @code{@var{c} = __UMUL (@var{a}, @var{b})} -@tab @code{UMUL @var{a},@var{b},@var{c}} -@end multitable - -@node Directly-mapped Media Functions -@subsubsection Directly-mapped Media Functions - -The functions listed below map directly to FR-V M-type instructions. - -@multitable @columnfractions .45 .32 .23 -@item Function prototype @tab Example usage @tab Assembly output -@item @code{uw1 __MABSHS (sw1)} -@tab @code{@var{b} = __MABSHS (@var{a})} -@tab @code{MABSHS @var{a},@var{b}} -@item @code{void __MADDACCS (acc, acc)} -@tab @code{__MADDACCS (@var{b}, @var{a})} -@tab @code{MADDACCS @var{a},@var{b}} -@item @code{sw1 __MADDHSS (sw1, sw1)} -@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} -@tab @code{MADDHSS @var{a},@var{b},@var{c}} -@item @code{uw1 __MADDHUS (uw1, uw1)} -@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} -@tab @code{MADDHUS @var{a},@var{b},@var{c}} -@item @code{uw1 __MAND (uw1, uw1)} -@tab @code{@var{c} = __MAND (@var{a}, @var{b})} -@tab @code{MAND @var{a},@var{b},@var{c}} -@item @code{void __MASACCS (acc, acc)} -@tab @code{__MASACCS (@var{b}, @var{a})} -@tab @code{MASACCS @var{a},@var{b}} -@item @code{uw1 __MAVEH (uw1, uw1)} -@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} -@tab @code{MAVEH @var{a},@var{b},@var{c}} -@item @code{uw2 __MBTOH (uw1)} -@tab @code{@var{b} = __MBTOH (@var{a})} -@tab @code{MBTOH @var{a},@var{b}} -@item @code{void __MBTOHE (uw1 *, uw1)} -@tab @code{__MBTOHE (&@var{b}, @var{a})} -@tab @code{MBTOHE @var{a},@var{b}} -@item @code{void __MCLRACC (acc)} -@tab @code{__MCLRACC (@var{a})} -@tab @code{MCLRACC @var{a}} -@item @code{void __MCLRACCA (void)} -@tab @code{__MCLRACCA ()} -@tab @code{MCLRACCA} -@item @code{uw1 __Mcop1 (uw1, uw1)} -@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} -@tab @code{Mcop1 @var{a},@var{b},@var{c}} -@item @code{uw1 __Mcop2 (uw1, uw1)} -@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} -@tab @code{Mcop2 @var{a},@var{b},@var{c}} -@item @code{uw1 __MCPLHI (uw2, const)} -@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} -@tab @code{MCPLHI @var{a},#@var{b},@var{c}} -@item @code{uw1 __MCPLI (uw2, const)} -@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} -@tab @code{MCPLI @var{a},#@var{b},@var{c}} -@item @code{void __MCPXIS (acc, sw1, sw1)} -@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} -@tab @code{MCPXIS @var{a},@var{b},@var{c}} -@item @code{void __MCPXIU (acc, uw1, uw1)} -@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} -@tab @code{MCPXIU @var{a},@var{b},@var{c}} -@item @code{void __MCPXRS (acc, sw1, sw1)} -@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} -@tab @code{MCPXRS @var{a},@var{b},@var{c}} -@item @code{void __MCPXRU (acc, uw1, uw1)} -@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} -@tab @code{MCPXRU @var{a},@var{b},@var{c}} -@item @code{uw1 __MCUT (acc, uw1)} -@tab @code{@var{c} = __MCUT (@var{a}, @var{b})} -@tab @code{MCUT @var{a},@var{b},@var{c}} -@item @code{uw1 __MCUTSS (acc, sw1)} -@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} -@tab @code{MCUTSS @var{a},@var{b},@var{c}} -@item @code{void __MDADDACCS (acc, acc)} -@tab @code{__MDADDACCS (@var{b}, @var{a})} -@tab @code{MDADDACCS @var{a},@var{b}} -@item @code{void __MDASACCS (acc, acc)} -@tab @code{__MDASACCS (@var{b}, @var{a})} -@tab @code{MDASACCS @var{a},@var{b}} -@item @code{uw2 __MDCUTSSI (acc, const)} -@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} -@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} -@item @code{uw2 __MDPACKH (uw2, uw2)} -@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} -@tab @code{MDPACKH @var{a},@var{b},@var{c}} -@item @code{uw2 __MDROTLI (uw2, const)} -@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} -@tab @code{MDROTLI @var{a},#@var{b},@var{c}} -@item @code{void __MDSUBACCS (acc, acc)} -@tab @code{__MDSUBACCS (@var{b}, @var{a})} -@tab @code{MDSUBACCS @var{a},@var{b}} -@item @code{void __MDUNPACKH (uw1 *, uw2)} -@tab @code{__MDUNPACKH (&@var{b}, @var{a})} -@tab @code{MDUNPACKH @var{a},@var{b}} -@item @code{uw2 __MEXPDHD (uw1, const)} -@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} -@tab @code{MEXPDHD @var{a},#@var{b},@var{c}} -@item @code{uw1 __MEXPDHW (uw1, const)} -@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} -@tab @code{MEXPDHW @var{a},#@var{b},@var{c}} -@item @code{uw1 __MHDSETH (uw1, const)} -@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} -@tab @code{MHDSETH @var{a},#@var{b},@var{c}} -@item @code{sw1 __MHDSETS (const)} -@tab @code{@var{b} = __MHDSETS (@var{a})} -@tab @code{MHDSETS #@var{a},@var{b}} -@item @code{uw1 __MHSETHIH (uw1, const)} -@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} -@tab @code{MHSETHIH #@var{a},@var{b}} -@item @code{sw1 __MHSETHIS (sw1, const)} -@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} -@tab @code{MHSETHIS #@var{a},@var{b}} -@item @code{uw1 __MHSETLOH (uw1, const)} -@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} -@tab @code{MHSETLOH #@var{a},@var{b}} -@item @code{sw1 __MHSETLOS (sw1, const)} -@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} -@tab @code{MHSETLOS #@var{a},@var{b}} -@item @code{uw1 __MHTOB (uw2)} -@tab @code{@var{b} = __MHTOB (@var{a})} -@tab @code{MHTOB @var{a},@var{b}} -@item @code{void __MMACHS (acc, sw1, sw1)} -@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} -@tab @code{MMACHS @var{a},@var{b},@var{c}} -@item @code{void __MMACHU (acc, uw1, uw1)} -@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} -@tab @code{MMACHU @var{a},@var{b},@var{c}} -@item @code{void __MMRDHS (acc, sw1, sw1)} -@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} -@tab @code{MMRDHS @var{a},@var{b},@var{c}} -@item @code{void __MMRDHU (acc, uw1, uw1)} -@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} -@tab @code{MMRDHU @var{a},@var{b},@var{c}} -@item @code{void __MMULHS (acc, sw1, sw1)} -@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} -@tab @code{MMULHS @var{a},@var{b},@var{c}} -@item @code{void __MMULHU (acc, uw1, uw1)} -@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} -@tab @code{MMULHU @var{a},@var{b},@var{c}} -@item @code{void __MMULXHS (acc, sw1, sw1)} -@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} -@tab @code{MMULXHS @var{a},@var{b},@var{c}} -@item @code{void __MMULXHU (acc, uw1, uw1)} -@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} -@tab @code{MMULXHU @var{a},@var{b},@var{c}} -@item @code{uw1 __MNOT (uw1)} -@tab @code{@var{b} = __MNOT (@var{a})} -@tab @code{MNOT @var{a},@var{b}} -@item @code{uw1 __MOR (uw1, uw1)} -@tab @code{@var{c} = __MOR (@var{a}, @var{b})} -@tab @code{MOR @var{a},@var{b},@var{c}} -@item @code{uw1 __MPACKH (uh, uh)} -@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} -@tab @code{MPACKH @var{a},@var{b},@var{c}} -@item @code{sw2 __MQADDHSS (sw2, sw2)} -@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} -@tab @code{MQADDHSS @var{a},@var{b},@var{c}} -@item @code{uw2 __MQADDHUS (uw2, uw2)} -@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} -@tab @code{MQADDHUS @var{a},@var{b},@var{c}} -@item @code{void __MQCPXIS (acc, sw2, sw2)} -@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} -@tab @code{MQCPXIS @var{a},@var{b},@var{c}} -@item @code{void __MQCPXIU (acc, uw2, uw2)} -@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} -@tab @code{MQCPXIU @var{a},@var{b},@var{c}} -@item @code{void __MQCPXRS (acc, sw2, sw2)} -@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} -@tab @code{MQCPXRS @var{a},@var{b},@var{c}} -@item @code{void __MQCPXRU (acc, uw2, uw2)} -@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} -@tab @code{MQCPXRU @var{a},@var{b},@var{c}} -@item @code{sw2 __MQLCLRHS (sw2, sw2)} -@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} -@tab @code{MQLCLRHS @var{a},@var{b},@var{c}} -@item @code{sw2 __MQLMTHS (sw2, sw2)} -@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} -@tab @code{MQLMTHS @var{a},@var{b},@var{c}} -@item @code{void __MQMACHS (acc, sw2, sw2)} -@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} -@tab @code{MQMACHS @var{a},@var{b},@var{c}} -@item @code{void __MQMACHU (acc, uw2, uw2)} -@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} -@tab @code{MQMACHU @var{a},@var{b},@var{c}} -@item @code{void __MQMACXHS (acc, sw2, sw2)} -@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} -@tab @code{MQMACXHS @var{a},@var{b},@var{c}} -@item @code{void __MQMULHS (acc, sw2, sw2)} -@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} -@tab @code{MQMULHS @var{a},@var{b},@var{c}} -@item @code{void __MQMULHU (acc, uw2, uw2)} -@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} -@tab @code{MQMULHU @var{a},@var{b},@var{c}} -@item @code{void __MQMULXHS (acc, sw2, sw2)} -@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} -@tab @code{MQMULXHS @var{a},@var{b},@var{c}} -@item @code{void __MQMULXHU (acc, uw2, uw2)} -@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} -@tab @code{MQMULXHU @var{a},@var{b},@var{c}} -@item @code{sw2 __MQSATHS (sw2, sw2)} -@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} -@tab @code{MQSATHS @var{a},@var{b},@var{c}} -@item @code{uw2 __MQSLLHI (uw2, int)} -@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} -@tab @code{MQSLLHI @var{a},@var{b},@var{c}} -@item @code{sw2 __MQSRAHI (sw2, int)} -@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} -@tab @code{MQSRAHI @var{a},@var{b},@var{c}} -@item @code{sw2 __MQSUBHSS (sw2, sw2)} -@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} -@tab @code{MQSUBHSS @var{a},@var{b},@var{c}} -@item @code{uw2 __MQSUBHUS (uw2, uw2)} -@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} -@tab @code{MQSUBHUS @var{a},@var{b},@var{c}} -@item @code{void __MQXMACHS (acc, sw2, sw2)} -@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} -@tab @code{MQXMACHS @var{a},@var{b},@var{c}} -@item @code{void __MQXMACXHS (acc, sw2, sw2)} -@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} -@tab @code{MQXMACXHS @var{a},@var{b},@var{c}} -@item @code{uw1 __MRDACC (acc)} -@tab @code{@var{b} = __MRDACC (@var{a})} -@tab @code{MRDACC @var{a},@var{b}} -@item @code{uw1 __MRDACCG (acc)} -@tab @code{@var{b} = __MRDACCG (@var{a})} -@tab @code{MRDACCG @var{a},@var{b}} -@item @code{uw1 __MROTLI (uw1, const)} -@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} -@tab @code{MROTLI @var{a},#@var{b},@var{c}} -@item @code{uw1 __MROTRI (uw1, const)} -@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} -@tab @code{MROTRI @var{a},#@var{b},@var{c}} -@item @code{sw1 __MSATHS (sw1, sw1)} -@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} -@tab @code{MSATHS @var{a},@var{b},@var{c}} -@item @code{uw1 __MSATHU (uw1, uw1)} -@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} -@tab @code{MSATHU @var{a},@var{b},@var{c}} -@item @code{uw1 __MSLLHI (uw1, const)} -@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} -@tab @code{MSLLHI @var{a},#@var{b},@var{c}} -@item @code{sw1 __MSRAHI (sw1, const)} -@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} -@tab @code{MSRAHI @var{a},#@var{b},@var{c}} -@item @code{uw1 __MSRLHI (uw1, const)} -@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} -@tab @code{MSRLHI @var{a},#@var{b},@var{c}} -@item @code{void __MSUBACCS (acc, acc)} -@tab @code{__MSUBACCS (@var{b}, @var{a})} -@tab @code{MSUBACCS @var{a},@var{b}} -@item @code{sw1 __MSUBHSS (sw1, sw1)} -@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} -@tab @code{MSUBHSS @var{a},@var{b},@var{c}} -@item @code{uw1 __MSUBHUS (uw1, uw1)} -@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} -@tab @code{MSUBHUS @var{a},@var{b},@var{c}} -@item @code{void __MTRAP (void)} -@tab @code{__MTRAP ()} -@tab @code{MTRAP} -@item @code{uw2 __MUNPACKH (uw1)} -@tab @code{@var{b} = __MUNPACKH (@var{a})} -@tab @code{MUNPACKH @var{a},@var{b}} -@item @code{uw1 __MWCUT (uw2, uw1)} -@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} -@tab @code{MWCUT @var{a},@var{b},@var{c}} -@item @code{void __MWTACC (acc, uw1)} -@tab @code{__MWTACC (@var{b}, @var{a})} -@tab @code{MWTACC @var{a},@var{b}} -@item @code{void __MWTACCG (acc, uw1)} -@tab @code{__MWTACCG (@var{b}, @var{a})} -@tab @code{MWTACCG @var{a},@var{b}} -@item @code{uw1 __MXOR (uw1, uw1)} -@tab @code{@var{c} = __MXOR (@var{a}, @var{b})} -@tab @code{MXOR @var{a},@var{b},@var{c}} -@end multitable - -@node Raw read/write Functions -@subsubsection Raw read/write Functions - -This sections describes built-in functions related to read and write -instructions to access memory. These functions generate -@code{membar} instructions to flush the I/O load and stores where -appropriate, as described in Fujitsu's manual described above. - -@table @code - -@item unsigned char __builtin_read8 (void *@var{data}) -@item unsigned short __builtin_read16 (void *@var{data}) -@item unsigned long __builtin_read32 (void *@var{data}) -@item unsigned long long __builtin_read64 (void *@var{data}) - -@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) -@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) -@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) -@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) -@end table - -@node Other Built-in Functions -@subsubsection Other Built-in Functions - -This section describes built-in functions that are not named after -a specific FR-V instruction. - -@table @code -@item sw2 __IACCreadll (iacc @var{reg}) -Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved -for future expansion and must be 0. - -@item sw1 __IACCreadl (iacc @var{reg}) -Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. -Other values of @var{reg} are rejected as invalid. - -@item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) -Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument -is reserved for future expansion and must be 0. - -@item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) -Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} -is 1. Other values of @var{reg} are rejected as invalid. - -@item void __data_prefetch0 (const void *@var{x}) -Use the @code{dcpl} instruction to load the contents of address @var{x} -into the data cache. - -@item void __data_prefetch (const void *@var{x}) -Use the @code{nldub} instruction to load the contents of address @var{x} -into the data cache. The instruction is issued in slot I1@. -@end table - -@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. - -If you specify command-line switches such as @option{-msse}, -the compiler could use the extended instruction sets even if the built-ins -are not used explicitly in the program. For this reason, applications -that perform run-time CPU detection must compile separate files for each -supported architecture, using the appropriate flags. In particular, -the file containing the CPU detection code should be compiled without -these options. - -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{V1DI} 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}. - -In 64-bit mode, the x86-64 family of processors uses additional built-in -functions for efficient use of @code{TF} (@code{__float128}) 128-bit -floating point and @code{TC} 128-bit complex floating-point values. - -The following floating-point built-in functions are available in 64-bit -mode. All of them implement the function that is part of the name. - -@smallexample -__float128 __builtin_fabsq (__float128) -__float128 __builtin_copysignq (__float128, __float128) -@end smallexample - -The following built-in function is always available. - -@table @code -@item void __builtin_ia32_pause (void) -Generates the @code{pause} machine instruction with a compiler memory -barrier. -@end table - -The following floating-point built-in functions are made available in the -64-bit mode. - -@table @code -@item __float128 __builtin_infq (void) -Similar to @code{__builtin_inf}, except the return type is @code{__float128}. -@findex __builtin_infq - -@item __float128 __builtin_huge_valq (void) -Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}. -@findex __builtin_huge_valq -@end table - -The following built-in functions are always available and can be used to -check the target platform type. - -@deftypefn {Built-in Function} void __builtin_cpu_init (void) -This function runs the CPU detection code to check the type of CPU and the -features supported. This built-in function needs to be invoked along with the built-in functions -to check CPU type and features, @code{__builtin_cpu_is} and -@code{__builtin_cpu_supports}, only when used in a function that is -executed before any constructors are called. The CPU detection code is -automatically executed in a very high priority constructor. - -For example, this function has to be used in @code{ifunc} resolvers that -check for CPU type using the built-in functions @code{__builtin_cpu_is} -and @code{__builtin_cpu_supports}, or in constructors on targets that -don't support constructor priority. -@smallexample - -static void (*resolve_memcpy (void)) (void) -@{ - // ifunc resolvers fire before constructors, explicitly call the init - // function. - __builtin_cpu_init (); - if (__builtin_cpu_supports ("ssse3")) - return ssse3_memcpy; // super fast memcpy with ssse3 instructions. - else - return default_memcpy; -@} - -void *memcpy (void *, const void *, size_t) - __attribute__ ((ifunc ("resolve_memcpy"))); -@end smallexample - -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname}) -This function returns a positive integer if the run-time CPU -is of type @var{cpuname} -and returns @code{0} otherwise. The following CPU names can be detected: - -@table @samp -@item intel -Intel CPU. - -@item atom -Intel Atom CPU. - -@item core2 -Intel Core 2 CPU. - -@item corei7 -Intel Core i7 CPU. - -@item nehalem -Intel Core i7 Nehalem CPU. - -@item westmere -Intel Core i7 Westmere CPU. - -@item sandybridge -Intel Core i7 Sandy Bridge CPU. - -@item amd -AMD CPU. - -@item amdfam10h -AMD Family 10h CPU. - -@item barcelona -AMD Family 10h Barcelona CPU. - -@item shanghai -AMD Family 10h Shanghai CPU. - -@item istanbul -AMD Family 10h Istanbul CPU. - -@item btver1 -AMD Family 14h CPU. - -@item amdfam15h -AMD Family 15h CPU. - -@item bdver1 -AMD Family 15h Bulldozer version 1. - -@item bdver2 -AMD Family 15h Bulldozer version 2. - -@item bdver3 -AMD Family 15h Bulldozer version 3. - -@item btver2 -AMD Family 16h CPU. -@end table - -Here is an example: -@smallexample -if (__builtin_cpu_is ("corei7")) - @{ - do_corei7 (); // Core i7 specific implementation. - @} -else - @{ - do_generic (); // Generic implementation. - @} -@end smallexample -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature}) -This function returns a positive integer if the run-time CPU -supports @var{feature} -and returns @code{0} otherwise. The following features can be detected: - -@table @samp -@item cmov -CMOV instruction. -@item mmx -MMX instructions. -@item popcnt -POPCNT instruction. -@item sse -SSE instructions. -@item sse2 -SSE2 instructions. -@item sse3 -SSE3 instructions. -@item ssse3 -SSSE3 instructions. -@item sse4.1 -SSE4.1 instructions. -@item sse4.2 -SSE4.2 instructions. -@item avx -AVX instructions. -@item avx2 -AVX2 instructions. -@end table - -Here is an example: -@smallexample -if (__builtin_cpu_supports ("popcnt")) - @{ - asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc"); - @} -else - @{ - count = generic_countbits (n); //generic implementation. - @} -@end smallexample -@end deftypefn - - -The following built-in functions are made available by @option{-mmmx}. -All of them generate the machine instruction that is part of the name. - -@smallexample -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) - -v4hi __builtin_ia32_psllw (v4hi, v4hi) -v2si __builtin_ia32_pslld (v2si, v2si) -v1di __builtin_ia32_psllq (v1di, v1di) -v4hi __builtin_ia32_psrlw (v4hi, v4hi) -v2si __builtin_ia32_psrld (v2si, v2si) -v1di __builtin_ia32_psrlq (v1di, v1di) -v4hi __builtin_ia32_psraw (v4hi, v4hi) -v2si __builtin_ia32_psrad (v2si, v2si) -v4hi __builtin_ia32_psllwi (v4hi, int) -v2si __builtin_ia32_pslldi (v2si, int) -v1di __builtin_ia32_psllqi (v1di, int) -v4hi __builtin_ia32_psrlwi (v4hi, int) -v2si __builtin_ia32_psrldi (v2si, int) -v1di __builtin_ia32_psrlqi (v1di, int) -v4hi __builtin_ia32_psrawi (v4hi, int) -v2si __builtin_ia32_psradi (v2si, int) - -@end smallexample - -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. - -@smallexample -v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) -v8qi __builtin_ia32_pavgb (v8qi, v8qi) -v4hi __builtin_ia32_pavgw (v4hi, v4hi) -v1di __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 smallexample - -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. - -@smallexample -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_cmpunordss (v4sf, v4sf) -v4si __builtin_ia32_cmpneqss (v4sf, v4sf) -v4si __builtin_ia32_cmpnlts (v4sf, v4sf) -v4si __builtin_ia32_cmpnless (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 smallexample - -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, const v2sf *) -Generates the @code{movhps} machine instruction as a load from memory. -@item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *) -Generates the @code{movlps} machine instruction as a load from memory -@item void __builtin_ia32_storehps (v2sf *, v4sf) -Generates the @code{movhps} machine instruction as a store to memory. -@item void __builtin_ia32_storelps (v2sf *, v4sf) -Generates the @code{movlps} machine instruction as a store to memory. -@end table - -The following built-in functions are available when @option{-msse2} is used. -All of them generate the machine instruction that is part of the name. - -@smallexample -int __builtin_ia32_comisdeq (v2df, v2df) -int __builtin_ia32_comisdlt (v2df, v2df) -int __builtin_ia32_comisdle (v2df, v2df) -int __builtin_ia32_comisdgt (v2df, v2df) -int __builtin_ia32_comisdge (v2df, v2df) -int __builtin_ia32_comisdneq (v2df, v2df) -int __builtin_ia32_ucomisdeq (v2df, v2df) -int __builtin_ia32_ucomisdlt (v2df, v2df) -int __builtin_ia32_ucomisdle (v2df, v2df) -int __builtin_ia32_ucomisdgt (v2df, v2df) -int __builtin_ia32_ucomisdge (v2df, v2df) -int __builtin_ia32_ucomisdneq (v2df, v2df) -v2df __builtin_ia32_cmpeqpd (v2df, v2df) -v2df __builtin_ia32_cmpltpd (v2df, v2df) -v2df __builtin_ia32_cmplepd (v2df, v2df) -v2df __builtin_ia32_cmpgtpd (v2df, v2df) -v2df __builtin_ia32_cmpgepd (v2df, v2df) -v2df __builtin_ia32_cmpunordpd (v2df, v2df) -v2df __builtin_ia32_cmpneqpd (v2df, v2df) -v2df __builtin_ia32_cmpnltpd (v2df, v2df) -v2df __builtin_ia32_cmpnlepd (v2df, v2df) -v2df __builtin_ia32_cmpngtpd (v2df, v2df) -v2df __builtin_ia32_cmpngepd (v2df, v2df) -v2df __builtin_ia32_cmpordpd (v2df, v2df) -v2df __builtin_ia32_cmpeqsd (v2df, v2df) -v2df __builtin_ia32_cmpltsd (v2df, v2df) -v2df __builtin_ia32_cmplesd (v2df, v2df) -v2df __builtin_ia32_cmpunordsd (v2df, v2df) -v2df __builtin_ia32_cmpneqsd (v2df, v2df) -v2df __builtin_ia32_cmpnltsd (v2df, v2df) -v2df __builtin_ia32_cmpnlesd (v2df, v2df) -v2df __builtin_ia32_cmpordsd (v2df, v2df) -v2di __builtin_ia32_paddq (v2di, v2di) -v2di __builtin_ia32_psubq (v2di, v2di) -v2df __builtin_ia32_addpd (v2df, v2df) -v2df __builtin_ia32_subpd (v2df, v2df) -v2df __builtin_ia32_mulpd (v2df, v2df) -v2df __builtin_ia32_divpd (v2df, v2df) -v2df __builtin_ia32_addsd (v2df, v2df) -v2df __builtin_ia32_subsd (v2df, v2df) -v2df __builtin_ia32_mulsd (v2df, v2df) -v2df __builtin_ia32_divsd (v2df, v2df) -v2df __builtin_ia32_minpd (v2df, v2df) -v2df __builtin_ia32_maxpd (v2df, v2df) -v2df __builtin_ia32_minsd (v2df, v2df) -v2df __builtin_ia32_maxsd (v2df, v2df) -v2df __builtin_ia32_andpd (v2df, v2df) -v2df __builtin_ia32_andnpd (v2df, v2df) -v2df __builtin_ia32_orpd (v2df, v2df) -v2df __builtin_ia32_xorpd (v2df, v2df) -v2df __builtin_ia32_movsd (v2df, v2df) -v2df __builtin_ia32_unpckhpd (v2df, v2df) -v2df __builtin_ia32_unpcklpd (v2df, v2df) -v16qi __builtin_ia32_paddb128 (v16qi, v16qi) -v8hi __builtin_ia32_paddw128 (v8hi, v8hi) -v4si __builtin_ia32_paddd128 (v4si, v4si) -v2di __builtin_ia32_paddq128 (v2di, v2di) -v16qi __builtin_ia32_psubb128 (v16qi, v16qi) -v8hi __builtin_ia32_psubw128 (v8hi, v8hi) -v4si __builtin_ia32_psubd128 (v4si, v4si) -v2di __builtin_ia32_psubq128 (v2di, v2di) -v8hi __builtin_ia32_pmullw128 (v8hi, v8hi) -v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi) -v2di __builtin_ia32_pand128 (v2di, v2di) -v2di __builtin_ia32_pandn128 (v2di, v2di) -v2di __builtin_ia32_por128 (v2di, v2di) -v2di __builtin_ia32_pxor128 (v2di, v2di) -v16qi __builtin_ia32_pavgb128 (v16qi, v16qi) -v8hi __builtin_ia32_pavgw128 (v8hi, v8hi) -v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi) -v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi) -v4si __builtin_ia32_pcmpeqd128 (v4si, v4si) -v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi) -v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi) -v4si __builtin_ia32_pcmpgtd128 (v4si, v4si) -v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi) -v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi) -v16qi __builtin_ia32_pminub128 (v16qi, v16qi) -v8hi __builtin_ia32_pminsw128 (v8hi, v8hi) -v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi) -v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi) -v4si __builtin_ia32_punpckhdq128 (v4si, v4si) -v2di __builtin_ia32_punpckhqdq128 (v2di, v2di) -v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi) -v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi) -v4si __builtin_ia32_punpckldq128 (v4si, v4si) -v2di __builtin_ia32_punpcklqdq128 (v2di, v2di) -v16qi __builtin_ia32_packsswb128 (v8hi, v8hi) -v8hi __builtin_ia32_packssdw128 (v4si, v4si) -v16qi __builtin_ia32_packuswb128 (v8hi, v8hi) -v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi) -void __builtin_ia32_maskmovdqu (v16qi, v16qi) -v2df __builtin_ia32_loadupd (double *) -void __builtin_ia32_storeupd (double *, v2df) -v2df __builtin_ia32_loadhpd (v2df, double const *) -v2df __builtin_ia32_loadlpd (v2df, double const *) -int __builtin_ia32_movmskpd (v2df) -int __builtin_ia32_pmovmskb128 (v16qi) -void __builtin_ia32_movnti (int *, int) -void __builtin_ia32_movnti64 (long long int *, long long int) -void __builtin_ia32_movntpd (double *, v2df) -void __builtin_ia32_movntdq (v2df *, v2df) -v4si __builtin_ia32_pshufd (v4si, int) -v8hi __builtin_ia32_pshuflw (v8hi, int) -v8hi __builtin_ia32_pshufhw (v8hi, int) -v2di __builtin_ia32_psadbw128 (v16qi, v16qi) -v2df __builtin_ia32_sqrtpd (v2df) -v2df __builtin_ia32_sqrtsd (v2df) -v2df __builtin_ia32_shufpd (v2df, v2df, int) -v2df __builtin_ia32_cvtdq2pd (v4si) -v4sf __builtin_ia32_cvtdq2ps (v4si) -v4si __builtin_ia32_cvtpd2dq (v2df) -v2si __builtin_ia32_cvtpd2pi (v2df) -v4sf __builtin_ia32_cvtpd2ps (v2df) -v4si __builtin_ia32_cvttpd2dq (v2df) -v2si __builtin_ia32_cvttpd2pi (v2df) -v2df __builtin_ia32_cvtpi2pd (v2si) -int __builtin_ia32_cvtsd2si (v2df) -int __builtin_ia32_cvttsd2si (v2df) -long long __builtin_ia32_cvtsd2si64 (v2df) -long long __builtin_ia32_cvttsd2si64 (v2df) -v4si __builtin_ia32_cvtps2dq (v4sf) -v2df __builtin_ia32_cvtps2pd (v4sf) -v4si __builtin_ia32_cvttps2dq (v4sf) -v2df __builtin_ia32_cvtsi2sd (v2df, int) -v2df __builtin_ia32_cvtsi642sd (v2df, long long) -v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df) -v2df __builtin_ia32_cvtss2sd (v2df, v4sf) -void __builtin_ia32_clflush (const void *) -void __builtin_ia32_lfence (void) -void __builtin_ia32_mfence (void) -v16qi __builtin_ia32_loaddqu (const char *) -void __builtin_ia32_storedqu (char *, v16qi) -v1di __builtin_ia32_pmuludq (v2si, v2si) -v2di __builtin_ia32_pmuludq128 (v4si, v4si) -v8hi __builtin_ia32_psllw128 (v8hi, v8hi) -v4si __builtin_ia32_pslld128 (v4si, v4si) -v2di __builtin_ia32_psllq128 (v2di, v2di) -v8hi __builtin_ia32_psrlw128 (v8hi, v8hi) -v4si __builtin_ia32_psrld128 (v4si, v4si) -v2di __builtin_ia32_psrlq128 (v2di, v2di) -v8hi __builtin_ia32_psraw128 (v8hi, v8hi) -v4si __builtin_ia32_psrad128 (v4si, v4si) -v2di __builtin_ia32_pslldqi128 (v2di, int) -v8hi __builtin_ia32_psllwi128 (v8hi, int) -v4si __builtin_ia32_pslldi128 (v4si, int) -v2di __builtin_ia32_psllqi128 (v2di, int) -v2di __builtin_ia32_psrldqi128 (v2di, int) -v8hi __builtin_ia32_psrlwi128 (v8hi, int) -v4si __builtin_ia32_psrldi128 (v4si, int) -v2di __builtin_ia32_psrlqi128 (v2di, int) -v8hi __builtin_ia32_psrawi128 (v8hi, int) -v4si __builtin_ia32_psradi128 (v4si, int) -v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi) -v2di __builtin_ia32_movq128 (v2di) -@end smallexample - -The following built-in functions are available when @option{-msse3} is used. -All of them generate the machine instruction that is part of the name. - -@smallexample -v2df __builtin_ia32_addsubpd (v2df, v2df) -v4sf __builtin_ia32_addsubps (v4sf, v4sf) -v2df __builtin_ia32_haddpd (v2df, v2df) -v4sf __builtin_ia32_haddps (v4sf, v4sf) -v2df __builtin_ia32_hsubpd (v2df, v2df) -v4sf __builtin_ia32_hsubps (v4sf, v4sf) -v16qi __builtin_ia32_lddqu (char const *) -void __builtin_ia32_monitor (void *, unsigned int, unsigned int) -v2df __builtin_ia32_movddup (v2df) -v4sf __builtin_ia32_movshdup (v4sf) -v4sf __builtin_ia32_movsldup (v4sf) -void __builtin_ia32_mwait (unsigned int, unsigned int) -@end smallexample - -The following built-in functions are available when @option{-msse3} is used. - -@table @code -@item v2df __builtin_ia32_loadddup (double const *) -Generates the @code{movddup} machine instruction as a load from memory. -@end table - -The following built-in functions are available when @option{-mssse3} is used. -All of them generate the machine instruction that is part of the name -with MMX registers. - -@smallexample -v2si __builtin_ia32_phaddd (v2si, v2si) -v4hi __builtin_ia32_phaddw (v4hi, v4hi) -v4hi __builtin_ia32_phaddsw (v4hi, v4hi) -v2si __builtin_ia32_phsubd (v2si, v2si) -v4hi __builtin_ia32_phsubw (v4hi, v4hi) -v4hi __builtin_ia32_phsubsw (v4hi, v4hi) -v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi) -v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi) -v8qi __builtin_ia32_pshufb (v8qi, v8qi) -v8qi __builtin_ia32_psignb (v8qi, v8qi) -v2si __builtin_ia32_psignd (v2si, v2si) -v4hi __builtin_ia32_psignw (v4hi, v4hi) -v1di __builtin_ia32_palignr (v1di, v1di, int) -v8qi __builtin_ia32_pabsb (v8qi) -v2si __builtin_ia32_pabsd (v2si) -v4hi __builtin_ia32_pabsw (v4hi) -@end smallexample - -The following built-in functions are available when @option{-mssse3} is used. -All of them generate the machine instruction that is part of the name -with SSE registers. - -@smallexample -v4si __builtin_ia32_phaddd128 (v4si, v4si) -v8hi __builtin_ia32_phaddw128 (v8hi, v8hi) -v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi) -v4si __builtin_ia32_phsubd128 (v4si, v4si) -v8hi __builtin_ia32_phsubw128 (v8hi, v8hi) -v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi) -v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi) -v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi) -v16qi __builtin_ia32_pshufb128 (v16qi, v16qi) -v16qi __builtin_ia32_psignb128 (v16qi, v16qi) -v4si __builtin_ia32_psignd128 (v4si, v4si) -v8hi __builtin_ia32_psignw128 (v8hi, v8hi) -v2di __builtin_ia32_palignr128 (v2di, v2di, int) -v16qi __builtin_ia32_pabsb128 (v16qi) -v4si __builtin_ia32_pabsd128 (v4si) -v8hi __builtin_ia32_pabsw128 (v8hi) -@end smallexample - -The following built-in functions are available when @option{-msse4.1} is -used. All of them generate the machine instruction that is part of the -name. - -@smallexample -v2df __builtin_ia32_blendpd (v2df, v2df, const int) -v4sf __builtin_ia32_blendps (v4sf, v4sf, const int) -v2df __builtin_ia32_blendvpd (v2df, v2df, v2df) -v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf) -v2df __builtin_ia32_dppd (v2df, v2df, const int) -v4sf __builtin_ia32_dpps (v4sf, v4sf, const int) -v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int) -v2di __builtin_ia32_movntdqa (v2di *); -v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int) -v8hi __builtin_ia32_packusdw128 (v4si, v4si) -v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi) -v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int) -v2di __builtin_ia32_pcmpeqq (v2di, v2di) -v8hi __builtin_ia32_phminposuw128 (v8hi) -v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi) -v4si __builtin_ia32_pmaxsd128 (v4si, v4si) -v4si __builtin_ia32_pmaxud128 (v4si, v4si) -v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi) -v16qi __builtin_ia32_pminsb128 (v16qi, v16qi) -v4si __builtin_ia32_pminsd128 (v4si, v4si) -v4si __builtin_ia32_pminud128 (v4si, v4si) -v8hi __builtin_ia32_pminuw128 (v8hi, v8hi) -v4si __builtin_ia32_pmovsxbd128 (v16qi) -v2di __builtin_ia32_pmovsxbq128 (v16qi) -v8hi __builtin_ia32_pmovsxbw128 (v16qi) -v2di __builtin_ia32_pmovsxdq128 (v4si) -v4si __builtin_ia32_pmovsxwd128 (v8hi) -v2di __builtin_ia32_pmovsxwq128 (v8hi) -v4si __builtin_ia32_pmovzxbd128 (v16qi) -v2di __builtin_ia32_pmovzxbq128 (v16qi) -v8hi __builtin_ia32_pmovzxbw128 (v16qi) -v2di __builtin_ia32_pmovzxdq128 (v4si) -v4si __builtin_ia32_pmovzxwd128 (v8hi) -v2di __builtin_ia32_pmovzxwq128 (v8hi) -v2di __builtin_ia32_pmuldq128 (v4si, v4si) -v4si __builtin_ia32_pmulld128 (v4si, v4si) -int __builtin_ia32_ptestc128 (v2di, v2di) -int __builtin_ia32_ptestnzc128 (v2di, v2di) -int __builtin_ia32_ptestz128 (v2di, v2di) -v2df __builtin_ia32_roundpd (v2df, const int) -v4sf __builtin_ia32_roundps (v4sf, const int) -v2df __builtin_ia32_roundsd (v2df, v2df, const int) -v4sf __builtin_ia32_roundss (v4sf, v4sf, const int) -@end smallexample - -The following built-in functions are available when @option{-msse4.1} is -used. - -@table @code -@item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int) -Generates the @code{insertps} machine instruction. -@item int __builtin_ia32_vec_ext_v16qi (v16qi, const int) -Generates the @code{pextrb} machine instruction. -@item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int) -Generates the @code{pinsrb} machine instruction. -@item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int) -Generates the @code{pinsrd} machine instruction. -@item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int) -Generates the @code{pinsrq} machine instruction in 64bit mode. -@end table - -The following built-in functions are changed to generate new SSE4.1 -instructions when @option{-msse4.1} is used. - -@table @code -@item float __builtin_ia32_vec_ext_v4sf (v4sf, const int) -Generates the @code{extractps} machine instruction. -@item int __builtin_ia32_vec_ext_v4si (v4si, const int) -Generates the @code{pextrd} machine instruction. -@item long long __builtin_ia32_vec_ext_v2di (v2di, const int) -Generates the @code{pextrq} machine instruction in 64bit mode. -@end table - -The following built-in functions are available when @option{-msse4.2} is -used. All of them generate the machine instruction that is part of the -name. - -@smallexample -v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int) -int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int) -int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int) -int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int) -int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int) -int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int) -int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int) -v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int) -int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int) -int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int) -int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int) -int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int) -int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int) -int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int) -v2di __builtin_ia32_pcmpgtq (v2di, v2di) -@end smallexample - -The following built-in functions are available when @option{-msse4.2} is -used. - -@table @code -@item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char) -Generates the @code{crc32b} machine instruction. -@item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short) -Generates the @code{crc32w} machine instruction. -@item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int) -Generates the @code{crc32l} machine instruction. -@item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long) -Generates the @code{crc32q} machine instruction. -@end table - -The following built-in functions are changed to generate new SSE4.2 -instructions when @option{-msse4.2} is used. - -@table @code -@item int __builtin_popcount (unsigned int) -Generates the @code{popcntl} machine instruction. -@item int __builtin_popcountl (unsigned long) -Generates the @code{popcntl} or @code{popcntq} machine instruction, -depending on the size of @code{unsigned long}. -@item int __builtin_popcountll (unsigned long long) -Generates the @code{popcntq} machine instruction. -@end table - -The following built-in functions are available when @option{-mavx} is -used. All of them generate the machine instruction that is part of the -name. - -@smallexample -v4df __builtin_ia32_addpd256 (v4df,v4df) -v8sf __builtin_ia32_addps256 (v8sf,v8sf) -v4df __builtin_ia32_addsubpd256 (v4df,v4df) -v8sf __builtin_ia32_addsubps256 (v8sf,v8sf) -v4df __builtin_ia32_andnpd256 (v4df,v4df) -v8sf __builtin_ia32_andnps256 (v8sf,v8sf) -v4df __builtin_ia32_andpd256 (v4df,v4df) -v8sf __builtin_ia32_andps256 (v8sf,v8sf) -v4df __builtin_ia32_blendpd256 (v4df,v4df,int) -v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int) -v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df) -v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf) -v2df __builtin_ia32_cmppd (v2df,v2df,int) -v4df __builtin_ia32_cmppd256 (v4df,v4df,int) -v4sf __builtin_ia32_cmpps (v4sf,v4sf,int) -v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int) -v2df __builtin_ia32_cmpsd (v2df,v2df,int) -v4sf __builtin_ia32_cmpss (v4sf,v4sf,int) -v4df __builtin_ia32_cvtdq2pd256 (v4si) -v8sf __builtin_ia32_cvtdq2ps256 (v8si) -v4si __builtin_ia32_cvtpd2dq256 (v4df) -v4sf __builtin_ia32_cvtpd2ps256 (v4df) -v8si __builtin_ia32_cvtps2dq256 (v8sf) -v4df __builtin_ia32_cvtps2pd256 (v4sf) -v4si __builtin_ia32_cvttpd2dq256 (v4df) -v8si __builtin_ia32_cvttps2dq256 (v8sf) -v4df __builtin_ia32_divpd256 (v4df,v4df) -v8sf __builtin_ia32_divps256 (v8sf,v8sf) -v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int) -v4df __builtin_ia32_haddpd256 (v4df,v4df) -v8sf __builtin_ia32_haddps256 (v8sf,v8sf) -v4df __builtin_ia32_hsubpd256 (v4df,v4df) -v8sf __builtin_ia32_hsubps256 (v8sf,v8sf) -v32qi __builtin_ia32_lddqu256 (pcchar) -v32qi __builtin_ia32_loaddqu256 (pcchar) -v4df __builtin_ia32_loadupd256 (pcdouble) -v8sf __builtin_ia32_loadups256 (pcfloat) -v2df __builtin_ia32_maskloadpd (pcv2df,v2df) -v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df) -v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf) -v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf) -void __builtin_ia32_maskstorepd (pv2df,v2df,v2df) -void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df) -void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf) -void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf) -v4df __builtin_ia32_maxpd256 (v4df,v4df) -v8sf __builtin_ia32_maxps256 (v8sf,v8sf) -v4df __builtin_ia32_minpd256 (v4df,v4df) -v8sf __builtin_ia32_minps256 (v8sf,v8sf) -v4df __builtin_ia32_movddup256 (v4df) -int __builtin_ia32_movmskpd256 (v4df) -int __builtin_ia32_movmskps256 (v8sf) -v8sf __builtin_ia32_movshdup256 (v8sf) -v8sf __builtin_ia32_movsldup256 (v8sf) -v4df __builtin_ia32_mulpd256 (v4df,v4df) -v8sf __builtin_ia32_mulps256 (v8sf,v8sf) -v4df __builtin_ia32_orpd256 (v4df,v4df) -v8sf __builtin_ia32_orps256 (v8sf,v8sf) -v2df __builtin_ia32_pd_pd256 (v4df) -v4df __builtin_ia32_pd256_pd (v2df) -v4sf __builtin_ia32_ps_ps256 (v8sf) -v8sf __builtin_ia32_ps256_ps (v4sf) -int __builtin_ia32_ptestc256 (v4di,v4di,ptest) -int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest) -int __builtin_ia32_ptestz256 (v4di,v4di,ptest) -v8sf __builtin_ia32_rcpps256 (v8sf) -v4df __builtin_ia32_roundpd256 (v4df,int) -v8sf __builtin_ia32_roundps256 (v8sf,int) -v8sf __builtin_ia32_rsqrtps_nr256 (v8sf) -v8sf __builtin_ia32_rsqrtps256 (v8sf) -v4df __builtin_ia32_shufpd256 (v4df,v4df,int) -v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int) -v4si __builtin_ia32_si_si256 (v8si) -v8si __builtin_ia32_si256_si (v4si) -v4df __builtin_ia32_sqrtpd256 (v4df) -v8sf __builtin_ia32_sqrtps_nr256 (v8sf) -v8sf __builtin_ia32_sqrtps256 (v8sf) -void __builtin_ia32_storedqu256 (pchar,v32qi) -void __builtin_ia32_storeupd256 (pdouble,v4df) -void __builtin_ia32_storeups256 (pfloat,v8sf) -v4df __builtin_ia32_subpd256 (v4df,v4df) -v8sf __builtin_ia32_subps256 (v8sf,v8sf) -v4df __builtin_ia32_unpckhpd256 (v4df,v4df) -v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf) -v4df __builtin_ia32_unpcklpd256 (v4df,v4df) -v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf) -v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df) -v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf) -v4df __builtin_ia32_vbroadcastsd256 (pcdouble) -v4sf __builtin_ia32_vbroadcastss (pcfloat) -v8sf __builtin_ia32_vbroadcastss256 (pcfloat) -v2df __builtin_ia32_vextractf128_pd256 (v4df,int) -v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int) -v4si __builtin_ia32_vextractf128_si256 (v8si,int) -v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int) -v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int) -v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int) -v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int) -v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int) -v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int) -v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int) -v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int) -v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int) -v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int) -v2df __builtin_ia32_vpermilpd (v2df,int) -v4df __builtin_ia32_vpermilpd256 (v4df,int) -v4sf __builtin_ia32_vpermilps (v4sf,int) -v8sf __builtin_ia32_vpermilps256 (v8sf,int) -v2df __builtin_ia32_vpermilvarpd (v2df,v2di) -v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di) -v4sf __builtin_ia32_vpermilvarps (v4sf,v4si) -v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si) -int __builtin_ia32_vtestcpd (v2df,v2df,ptest) -int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest) -int __builtin_ia32_vtestcps (v4sf,v4sf,ptest) -int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest) -int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest) -int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest) -int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest) -int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest) -int __builtin_ia32_vtestzpd (v2df,v2df,ptest) -int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest) -int __builtin_ia32_vtestzps (v4sf,v4sf,ptest) -int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest) -void __builtin_ia32_vzeroall (void) -void __builtin_ia32_vzeroupper (void) -v4df __builtin_ia32_xorpd256 (v4df,v4df) -v8sf __builtin_ia32_xorps256 (v8sf,v8sf) -@end smallexample - -The following built-in functions are available when @option{-mavx2} is -used. All of them generate the machine instruction that is part of the -name. - -@smallexample -v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,v32qi,int) -v32qi __builtin_ia32_pabsb256 (v32qi) -v16hi __builtin_ia32_pabsw256 (v16hi) -v8si __builtin_ia32_pabsd256 (v8si) -v16hi __builtin_ia32_packssdw256 (v8si,v8si) -v32qi __builtin_ia32_packsswb256 (v16hi,v16hi) -v16hi __builtin_ia32_packusdw256 (v8si,v8si) -v32qi __builtin_ia32_packuswb256 (v16hi,v16hi) -v32qi __builtin_ia32_paddb256 (v32qi,v32qi) -v16hi __builtin_ia32_paddw256 (v16hi,v16hi) -v8si __builtin_ia32_paddd256 (v8si,v8si) -v4di __builtin_ia32_paddq256 (v4di,v4di) -v32qi __builtin_ia32_paddsb256 (v32qi,v32qi) -v16hi __builtin_ia32_paddsw256 (v16hi,v16hi) -v32qi __builtin_ia32_paddusb256 (v32qi,v32qi) -v16hi __builtin_ia32_paddusw256 (v16hi,v16hi) -v4di __builtin_ia32_palignr256 (v4di,v4di,int) -v4di __builtin_ia32_andsi256 (v4di,v4di) -v4di __builtin_ia32_andnotsi256 (v4di,v4di) -v32qi __builtin_ia32_pavgb256 (v32qi,v32qi) -v16hi __builtin_ia32_pavgw256 (v16hi,v16hi) -v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi) -v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int) -v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi) -v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi) -v8si __builtin_ia32_pcmpeqd256 (c8si,v8si) -v4di __builtin_ia32_pcmpeqq256 (v4di,v4di) -v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi) -v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi) -v8si __builtin_ia32_pcmpgtd256 (v8si,v8si) -v4di __builtin_ia32_pcmpgtq256 (v4di,v4di) -v16hi __builtin_ia32_phaddw256 (v16hi,v16hi) -v8si __builtin_ia32_phaddd256 (v8si,v8si) -v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi) -v16hi __builtin_ia32_phsubw256 (v16hi,v16hi) -v8si __builtin_ia32_phsubd256 (v8si,v8si) -v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi) -v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi) -v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi) -v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi) -v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi) -v8si __builtin_ia32_pmaxsd256 (v8si,v8si) -v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi) -v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi) -v8si __builtin_ia32_pmaxud256 (v8si,v8si) -v32qi __builtin_ia32_pminsb256 (v32qi,v32qi) -v16hi __builtin_ia32_pminsw256 (v16hi,v16hi) -v8si __builtin_ia32_pminsd256 (v8si,v8si) -v32qi __builtin_ia32_pminub256 (v32qi,v32qi) -v16hi __builtin_ia32_pminuw256 (v16hi,v16hi) -v8si __builtin_ia32_pminud256 (v8si,v8si) -int __builtin_ia32_pmovmskb256 (v32qi) -v16hi __builtin_ia32_pmovsxbw256 (v16qi) -v8si __builtin_ia32_pmovsxbd256 (v16qi) -v4di __builtin_ia32_pmovsxbq256 (v16qi) -v8si __builtin_ia32_pmovsxwd256 (v8hi) -v4di __builtin_ia32_pmovsxwq256 (v8hi) -v4di __builtin_ia32_pmovsxdq256 (v4si) -v16hi __builtin_ia32_pmovzxbw256 (v16qi) -v8si __builtin_ia32_pmovzxbd256 (v16qi) -v4di __builtin_ia32_pmovzxbq256 (v16qi) -v8si __builtin_ia32_pmovzxwd256 (v8hi) -v4di __builtin_ia32_pmovzxwq256 (v8hi) -v4di __builtin_ia32_pmovzxdq256 (v4si) -v4di __builtin_ia32_pmuldq256 (v8si,v8si) -v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi) -v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi) -v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi) -v16hi __builtin_ia32_pmullw256 (v16hi,v16hi) -v8si __builtin_ia32_pmulld256 (v8si,v8si) -v4di __builtin_ia32_pmuludq256 (v8si,v8si) -v4di __builtin_ia32_por256 (v4di,v4di) -v16hi __builtin_ia32_psadbw256 (v32qi,v32qi) -v32qi __builtin_ia32_pshufb256 (v32qi,v32qi) -v8si __builtin_ia32_pshufd256 (v8si,int) -v16hi __builtin_ia32_pshufhw256 (v16hi,int) -v16hi __builtin_ia32_pshuflw256 (v16hi,int) -v32qi __builtin_ia32_psignb256 (v32qi,v32qi) -v16hi __builtin_ia32_psignw256 (v16hi,v16hi) -v8si __builtin_ia32_psignd256 (v8si,v8si) -v4di __builtin_ia32_pslldqi256 (v4di,int) -v16hi __builtin_ia32_psllwi256 (16hi,int) -v16hi __builtin_ia32_psllw256(v16hi,v8hi) -v8si __builtin_ia32_pslldi256 (v8si,int) -v8si __builtin_ia32_pslld256(v8si,v4si) -v4di __builtin_ia32_psllqi256 (v4di,int) -v4di __builtin_ia32_psllq256(v4di,v2di) -v16hi __builtin_ia32_psrawi256 (v16hi,int) -v16hi __builtin_ia32_psraw256 (v16hi,v8hi) -v8si __builtin_ia32_psradi256 (v8si,int) -v8si __builtin_ia32_psrad256 (v8si,v4si) -v4di __builtin_ia32_psrldqi256 (v4di, int) -v16hi __builtin_ia32_psrlwi256 (v16hi,int) -v16hi __builtin_ia32_psrlw256 (v16hi,v8hi) -v8si __builtin_ia32_psrldi256 (v8si,int) -v8si __builtin_ia32_psrld256 (v8si,v4si) -v4di __builtin_ia32_psrlqi256 (v4di,int) -v4di __builtin_ia32_psrlq256(v4di,v2di) -v32qi __builtin_ia32_psubb256 (v32qi,v32qi) -v32hi __builtin_ia32_psubw256 (v16hi,v16hi) -v8si __builtin_ia32_psubd256 (v8si,v8si) -v4di __builtin_ia32_psubq256 (v4di,v4di) -v32qi __builtin_ia32_psubsb256 (v32qi,v32qi) -v16hi __builtin_ia32_psubsw256 (v16hi,v16hi) -v32qi __builtin_ia32_psubusb256 (v32qi,v32qi) -v16hi __builtin_ia32_psubusw256 (v16hi,v16hi) -v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi) -v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi) -v8si __builtin_ia32_punpckhdq256 (v8si,v8si) -v4di __builtin_ia32_punpckhqdq256 (v4di,v4di) -v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi) -v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi) -v8si __builtin_ia32_punpckldq256 (v8si,v8si) -v4di __builtin_ia32_punpcklqdq256 (v4di,v4di) -v4di __builtin_ia32_pxor256 (v4di,v4di) -v4di __builtin_ia32_movntdqa256 (pv4di) -v4sf __builtin_ia32_vbroadcastss_ps (v4sf) -v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf) -v4df __builtin_ia32_vbroadcastsd_pd256 (v2df) -v4di __builtin_ia32_vbroadcastsi256 (v2di) -v4si __builtin_ia32_pblendd128 (v4si,v4si) -v8si __builtin_ia32_pblendd256 (v8si,v8si) -v32qi __builtin_ia32_pbroadcastb256 (v16qi) -v16hi __builtin_ia32_pbroadcastw256 (v8hi) -v8si __builtin_ia32_pbroadcastd256 (v4si) -v4di __builtin_ia32_pbroadcastq256 (v2di) -v16qi __builtin_ia32_pbroadcastb128 (v16qi) -v8hi __builtin_ia32_pbroadcastw128 (v8hi) -v4si __builtin_ia32_pbroadcastd128 (v4si) -v2di __builtin_ia32_pbroadcastq128 (v2di) -v8si __builtin_ia32_permvarsi256 (v8si,v8si) -v4df __builtin_ia32_permdf256 (v4df,int) -v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf) -v4di __builtin_ia32_permdi256 (v4di,int) -v4di __builtin_ia32_permti256 (v4di,v4di,int) -v4di __builtin_ia32_extract128i256 (v4di,int) -v4di __builtin_ia32_insert128i256 (v4di,v2di,int) -v8si __builtin_ia32_maskloadd256 (pcv8si,v8si) -v4di __builtin_ia32_maskloadq256 (pcv4di,v4di) -v4si __builtin_ia32_maskloadd (pcv4si,v4si) -v2di __builtin_ia32_maskloadq (pcv2di,v2di) -void __builtin_ia32_maskstored256 (pv8si,v8si,v8si) -void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di) -void __builtin_ia32_maskstored (pv4si,v4si,v4si) -void __builtin_ia32_maskstoreq (pv2di,v2di,v2di) -v8si __builtin_ia32_psllv8si (v8si,v8si) -v4si __builtin_ia32_psllv4si (v4si,v4si) -v4di __builtin_ia32_psllv4di (v4di,v4di) -v2di __builtin_ia32_psllv2di (v2di,v2di) -v8si __builtin_ia32_psrav8si (v8si,v8si) -v4si __builtin_ia32_psrav4si (v4si,v4si) -v8si __builtin_ia32_psrlv8si (v8si,v8si) -v4si __builtin_ia32_psrlv4si (v4si,v4si) -v4di __builtin_ia32_psrlv4di (v4di,v4di) -v2di __builtin_ia32_psrlv2di (v2di,v2di) -v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int) -v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int) -v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int) -v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int) -v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int) -v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int) -v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int) -v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int) -v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int) -v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int) -v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int) -v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int) -v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int) -v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int) -v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int) -v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int) -@end smallexample - -The following built-in functions are available when @option{-maes} is -used. All of them generate the machine instruction that is part of the -name. - -@smallexample -v2di __builtin_ia32_aesenc128 (v2di, v2di) -v2di __builtin_ia32_aesenclast128 (v2di, v2di) -v2di __builtin_ia32_aesdec128 (v2di, v2di) -v2di __builtin_ia32_aesdeclast128 (v2di, v2di) -v2di __builtin_ia32_aeskeygenassist128 (v2di, const int) -v2di __builtin_ia32_aesimc128 (v2di) -@end smallexample - -The following built-in function is available when @option{-mpclmul} is -used. - -@table @code -@item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int) -Generates the @code{pclmulqdq} machine instruction. -@end table - -The following built-in function is available when @option{-mfsgsbase} is -used. All of them generate the machine instruction that is part of the -name. - -@smallexample -unsigned int __builtin_ia32_rdfsbase32 (void) -unsigned long long __builtin_ia32_rdfsbase64 (void) -unsigned int __builtin_ia32_rdgsbase32 (void) -unsigned long long __builtin_ia32_rdgsbase64 (void) -void _writefsbase_u32 (unsigned int) -void _writefsbase_u64 (unsigned long long) -void _writegsbase_u32 (unsigned int) -void _writegsbase_u64 (unsigned long long) -@end smallexample - -The following built-in function is available when @option{-mrdrnd} is -used. All of them generate the machine instruction that is part of the -name. - -@smallexample -unsigned int __builtin_ia32_rdrand16_step (unsigned short *) -unsigned int __builtin_ia32_rdrand32_step (unsigned int *) -unsigned int __builtin_ia32_rdrand64_step (unsigned long long *) -@end smallexample - -The following built-in functions are available when @option{-msse4a} is used. -All of them generate the machine instruction that is part of the name. - -@smallexample -void __builtin_ia32_movntsd (double *, v2df) -void __builtin_ia32_movntss (float *, v4sf) -v2di __builtin_ia32_extrq (v2di, v16qi) -v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int) -v2di __builtin_ia32_insertq (v2di, v2di) -v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int) -@end smallexample - -The following built-in functions are available when @option{-mxop} is used. -@smallexample -v2df __builtin_ia32_vfrczpd (v2df) -v4sf __builtin_ia32_vfrczps (v4sf) -v2df __builtin_ia32_vfrczsd (v2df, v2df) -v4sf __builtin_ia32_vfrczss (v4sf, v4sf) -v4df __builtin_ia32_vfrczpd256 (v4df) -v8sf __builtin_ia32_vfrczps256 (v8sf) -v2di __builtin_ia32_vpcmov (v2di, v2di, v2di) -v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di) -v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si) -v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi) -v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi) -v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df) -v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf) -v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di) -v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si) -v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi) -v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi) -v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df) -v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf) -v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi) -v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) -v4si __builtin_ia32_vpcomeqd (v4si, v4si) -v2di __builtin_ia32_vpcomeqq (v2di, v2di) -v16qi __builtin_ia32_vpcomequb (v16qi, v16qi) -v4si __builtin_ia32_vpcomequd (v4si, v4si) -v2di __builtin_ia32_vpcomequq (v2di, v2di) -v8hi __builtin_ia32_vpcomequw (v8hi, v8hi) -v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) -v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi) -v4si __builtin_ia32_vpcomfalsed (v4si, v4si) -v2di __builtin_ia32_vpcomfalseq (v2di, v2di) -v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi) -v4si __builtin_ia32_vpcomfalseud (v4si, v4si) -v2di __builtin_ia32_vpcomfalseuq (v2di, v2di) -v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi) -v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi) -v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi) -v4si __builtin_ia32_vpcomged (v4si, v4si) -v2di __builtin_ia32_vpcomgeq (v2di, v2di) -v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi) -v4si __builtin_ia32_vpcomgeud (v4si, v4si) -v2di __builtin_ia32_vpcomgeuq (v2di, v2di) -v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi) -v8hi __builtin_ia32_vpcomgew (v8hi, v8hi) -v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi) -v4si __builtin_ia32_vpcomgtd (v4si, v4si) -v2di __builtin_ia32_vpcomgtq (v2di, v2di) -v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi) -v4si __builtin_ia32_vpcomgtud (v4si, v4si) -v2di __builtin_ia32_vpcomgtuq (v2di, v2di) -v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi) -v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi) -v16qi __builtin_ia32_vpcomleb (v16qi, v16qi) -v4si __builtin_ia32_vpcomled (v4si, v4si) -v2di __builtin_ia32_vpcomleq (v2di, v2di) -v16qi __builtin_ia32_vpcomleub (v16qi, v16qi) -v4si __builtin_ia32_vpcomleud (v4si, v4si) -v2di __builtin_ia32_vpcomleuq (v2di, v2di) -v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi) -v8hi __builtin_ia32_vpcomlew (v8hi, v8hi) -v16qi __builtin_ia32_vpcomltb (v16qi, v16qi) -v4si __builtin_ia32_vpcomltd (v4si, v4si) -v2di __builtin_ia32_vpcomltq (v2di, v2di) -v16qi __builtin_ia32_vpcomltub (v16qi, v16qi) -v4si __builtin_ia32_vpcomltud (v4si, v4si) -v2di __builtin_ia32_vpcomltuq (v2di, v2di) -v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi) -v8hi __builtin_ia32_vpcomltw (v8hi, v8hi) -v16qi __builtin_ia32_vpcomneb (v16qi, v16qi) -v4si __builtin_ia32_vpcomned (v4si, v4si) -v2di __builtin_ia32_vpcomneq (v2di, v2di) -v16qi __builtin_ia32_vpcomneub (v16qi, v16qi) -v4si __builtin_ia32_vpcomneud (v4si, v4si) -v2di __builtin_ia32_vpcomneuq (v2di, v2di) -v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi) -v8hi __builtin_ia32_vpcomnew (v8hi, v8hi) -v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi) -v4si __builtin_ia32_vpcomtrued (v4si, v4si) -v2di __builtin_ia32_vpcomtrueq (v2di, v2di) -v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi) -v4si __builtin_ia32_vpcomtrueud (v4si, v4si) -v2di __builtin_ia32_vpcomtrueuq (v2di, v2di) -v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi) -v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi) -v4si __builtin_ia32_vphaddbd (v16qi) -v2di __builtin_ia32_vphaddbq (v16qi) -v8hi __builtin_ia32_vphaddbw (v16qi) -v2di __builtin_ia32_vphadddq (v4si) -v4si __builtin_ia32_vphaddubd (v16qi) -v2di __builtin_ia32_vphaddubq (v16qi) -v8hi __builtin_ia32_vphaddubw (v16qi) -v2di __builtin_ia32_vphaddudq (v4si) -v4si __builtin_ia32_vphadduwd (v8hi) -v2di __builtin_ia32_vphadduwq (v8hi) -v4si __builtin_ia32_vphaddwd (v8hi) -v2di __builtin_ia32_vphaddwq (v8hi) -v8hi __builtin_ia32_vphsubbw (v16qi) -v2di __builtin_ia32_vphsubdq (v4si) -v4si __builtin_ia32_vphsubwd (v8hi) -v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si) -v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di) -v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di) -v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si) -v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di) -v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di) -v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si) -v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi) -v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si) -v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi) -v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si) -v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si) -v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi) -v16qi __builtin_ia32_vprotb (v16qi, v16qi) -v4si __builtin_ia32_vprotd (v4si, v4si) -v2di __builtin_ia32_vprotq (v2di, v2di) -v8hi __builtin_ia32_vprotw (v8hi, v8hi) -v16qi __builtin_ia32_vpshab (v16qi, v16qi) -v4si __builtin_ia32_vpshad (v4si, v4si) -v2di __builtin_ia32_vpshaq (v2di, v2di) -v8hi __builtin_ia32_vpshaw (v8hi, v8hi) -v16qi __builtin_ia32_vpshlb (v16qi, v16qi) -v4si __builtin_ia32_vpshld (v4si, v4si) -v2di __builtin_ia32_vpshlq (v2di, v2di) -v8hi __builtin_ia32_vpshlw (v8hi, v8hi) -@end smallexample - -The following built-in functions are available when @option{-mfma4} is used. -All of them generate the machine instruction that is part of the name -with MMX registers. - -@smallexample -v2df __builtin_ia32_fmaddpd (v2df, v2df, v2df) -v4sf __builtin_ia32_fmaddps (v4sf, v4sf, v4sf) -v2df __builtin_ia32_fmaddsd (v2df, v2df, v2df) -v4sf __builtin_ia32_fmaddss (v4sf, v4sf, v4sf) -v2df __builtin_ia32_fmsubpd (v2df, v2df, v2df) -v4sf __builtin_ia32_fmsubps (v4sf, v4sf, v4sf) -v2df __builtin_ia32_fmsubsd (v2df, v2df, v2df) -v4sf __builtin_ia32_fmsubss (v4sf, v4sf, v4sf) -v2df __builtin_ia32_fnmaddpd (v2df, v2df, v2df) -v4sf __builtin_ia32_fnmaddps (v4sf, v4sf, v4sf) -v2df __builtin_ia32_fnmaddsd (v2df, v2df, v2df) -v4sf __builtin_ia32_fnmaddss (v4sf, v4sf, v4sf) -v2df __builtin_ia32_fnmsubpd (v2df, v2df, v2df) -v4sf __builtin_ia32_fnmsubps (v4sf, v4sf, v4sf) -v2df __builtin_ia32_fnmsubsd (v2df, v2df, v2df) -v4sf __builtin_ia32_fnmsubss (v4sf, v4sf, v4sf) -v2df __builtin_ia32_fmaddsubpd (v2df, v2df, v2df) -v4sf __builtin_ia32_fmaddsubps (v4sf, v4sf, v4sf) -v2df __builtin_ia32_fmsubaddpd (v2df, v2df, v2df) -v4sf __builtin_ia32_fmsubaddps (v4sf, v4sf, v4sf) -v4df __builtin_ia32_fmaddpd256 (v4df, v4df, v4df) -v8sf __builtin_ia32_fmaddps256 (v8sf, v8sf, v8sf) -v4df __builtin_ia32_fmsubpd256 (v4df, v4df, v4df) -v8sf __builtin_ia32_fmsubps256 (v8sf, v8sf, v8sf) -v4df __builtin_ia32_fnmaddpd256 (v4df, v4df, v4df) -v8sf __builtin_ia32_fnmaddps256 (v8sf, v8sf, v8sf) -v4df __builtin_ia32_fnmsubpd256 (v4df, v4df, v4df) -v8sf __builtin_ia32_fnmsubps256 (v8sf, v8sf, v8sf) -v4df __builtin_ia32_fmaddsubpd256 (v4df, v4df, v4df) -v8sf __builtin_ia32_fmaddsubps256 (v8sf, v8sf, v8sf) -v4df __builtin_ia32_fmsubaddpd256 (v4df, v4df, v4df) -v8sf __builtin_ia32_fmsubaddps256 (v8sf, v8sf, v8sf) - -@end smallexample - -The following built-in functions are available when @option{-mlwp} is used. - -@smallexample -void __builtin_ia32_llwpcb16 (void *); -void __builtin_ia32_llwpcb32 (void *); -void __builtin_ia32_llwpcb64 (void *); -void * __builtin_ia32_llwpcb16 (void); -void * __builtin_ia32_llwpcb32 (void); -void * __builtin_ia32_llwpcb64 (void); -void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short) -void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int) -void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int) -unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short) -unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int) -unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int) -@end smallexample - -The following built-in functions are available when @option{-mbmi} is used. -All of them generate the machine instruction that is part of the name. -@smallexample -unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int); -unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long); -@end smallexample - -The following built-in functions are available when @option{-mbmi2} is used. -All of them generate the machine instruction that is part of the name. -@smallexample -unsigned int _bzhi_u32 (unsigned int, unsigned int) -unsigned int _pdep_u32 (unsigned int, unsigned int) -unsigned int _pext_u32 (unsigned int, unsigned int) -unsigned long long _bzhi_u64 (unsigned long long, unsigned long long) -unsigned long long _pdep_u64 (unsigned long long, unsigned long long) -unsigned long long _pext_u64 (unsigned long long, unsigned long long) -@end smallexample - -The following built-in functions are available when @option{-mlzcnt} is used. -All of them generate the machine instruction that is part of the name. -@smallexample -unsigned short __builtin_ia32_lzcnt_16(unsigned short); -unsigned int __builtin_ia32_lzcnt_u32(unsigned int); -unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long); -@end smallexample - -The following built-in functions are available when @option{-mtbm} is used. -Both of them generate the immediate form of the bextr machine instruction. -@smallexample -unsigned int __builtin_ia32_bextri_u32 (unsigned int, const unsigned int); -unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, const unsigned long long); -@end smallexample - - -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. - -@smallexample -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 smallexample - -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. - -@smallexample -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 smallexample - -The following built-in functions are available when @option{-mrtm} is used -They are used for restricted transactional memory. These are the internal -low level functions. Normally the functions in -@ref{X86 transactional memory intrinsics} should be used instead. - -@smallexample -int __builtin_ia32_xbegin () -void __builtin_ia32_xend () -void __builtin_ia32_xabort (status) -int __builtin_ia32_xtest () -@end smallexample - -@node X86 transactional memory intrinsics -@subsection X86 transaction memory intrinsics - -Hardware transactional memory intrinsics for i386. These allow to use -memory transactions with RTM (Restricted Transactional Memory). -For using HLE (Hardware Lock Elision) see @ref{x86 specific memory model extensions for transactional memory} instead. -This support is enabled with the @option{-mrtm} option. - -A memory transaction commits all changes to memory in an atomic way, -as visible to other threads. If the transaction fails it is rolled back -and all side effects discarded. - -Generally there is no guarantee that a memory transaction ever suceeds -and suitable fallback code always needs to be supplied. - -@deftypefn {RTM Function} {unsigned} _xbegin () -Start a RTM (Restricted Transactional Memory) transaction. -Returns _XBEGIN_STARTED when the transaction -started successfully (note this is not 0, so the constant has to be -explicitely tested). When the transaction aborts all side effects -are undone and an abort code is returned. There is no guarantee -any transaction ever succeeds, so there always needs to be a valid -tested fallback path. -@end deftypefn - -@smallexample -#include <immintrin.h> - -if ((status = _xbegin ()) == _XBEGIN_STARTED) @{ - ... transaction code... - _xend (); -@} else @{ - ... non transactional fallback path... -@} -@end smallexample - -Valid abort status bits (when the value is not @code{_XBEGIN_STARTED}) are: - -@table @code -@item _XABORT_EXPLICIT -Transaction explicitely aborted with @code{_xabort}. The parameter passed -to @code{_xabort} is available with @code{_XABORT_CODE(status)} -@item _XABORT_RETRY -Transaction retry is possible. -@item _XABORT_CONFLICT -Transaction abort due to a memory conflict with another thread -@item _XABORT_CAPACITY -Transaction abort due to the transaction using too much memory -@item _XABORT_DEBUG -Transaction abort due to a debug trap -@item _XABORT_NESTED -Transaction abort in a inner nested transaction -@end table - -@deftypefn {RTM Function} {void} _xend () -Commit the current transaction. When no transaction is active this will -fault. All memory side effects of the transactions will become visible -to other threads in an atomic matter. -@end deftypefn - -@deftypefn {RTM Function} {int} _xtest () -Return a value not zero when a transaction is currently active, otherwise 0. -@end deftypefn - -@deftypefn {RTM Function} {void} _xabort (status) -Abort the current transaction. When no transaction is active this is a no-op. -status must be a 8bit constant, that is included in the status code returned -by @code{_xbegin} -@end deftypefn - -@node MIPS DSP Built-in Functions -@subsection MIPS DSP Built-in Functions - -The MIPS DSP Application-Specific Extension (ASE) includes new -instructions that are designed to improve the performance of DSP and -media applications. It provides instructions that operate on packed -8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data. - -GCC supports MIPS DSP operations using both the generic -vector extensions (@pxref{Vector Extensions}) and a collection of -MIPS-specific built-in functions. Both kinds of support are -enabled by the @option{-mdsp} command-line option. - -Revision 2 of the ASE was introduced in the second half of 2006. -This revision adds extra instructions to the original ASE, but is -otherwise backwards-compatible with it. You can select revision 2 -using the command-line option @option{-mdspr2}; this option implies -@option{-mdsp}. - -The SCOUNT and POS bits of the DSP control register are global. The -WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and -POS bits. During optimization, the compiler does not delete these -instructions and it does not delete calls to functions containing -these instructions. - -At present, GCC only provides support for operations on 32-bit -vectors. The vector type associated with 8-bit integer data is -usually called @code{v4i8}, the vector type associated with Q7 -is usually called @code{v4q7}, the vector type associated with 16-bit -integer data is usually called @code{v2i16}, and the vector type -associated with Q15 is usually called @code{v2q15}. They can be -defined in C as follows: - -@smallexample -typedef signed char v4i8 __attribute__ ((vector_size(4))); -typedef signed char v4q7 __attribute__ ((vector_size(4))); -typedef short v2i16 __attribute__ ((vector_size(4))); -typedef short v2q15 __attribute__ ((vector_size(4))); -@end smallexample - -@code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are -initialized in the same way as aggregates. For example: - -@smallexample -v4i8 a = @{1, 2, 3, 4@}; -v4i8 b; -b = (v4i8) @{5, 6, 7, 8@}; - -v2q15 c = @{0x0fcb, 0x3a75@}; -v2q15 d; -d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; -@end smallexample - -@emph{Note:} The CPU's endianness determines the order in which values -are packed. On little-endian targets, the first value is the least -significant and the last value is the most significant. The opposite -order applies to big-endian targets. For example, the code above -sets the lowest byte of @code{a} to @code{1} on little-endian targets -and @code{4} on big-endian targets. - -@emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer -representation. As shown in this example, the integer representation -of a Q7 value can be obtained by multiplying the fractional value by -@code{0x1.0p7}. The equivalent for Q15 values is to multiply by -@code{0x1.0p15}. The equivalent for Q31 values is to multiply by -@code{0x1.0p31}. - -The table below lists the @code{v4i8} and @code{v2q15} operations for which -hardware support exists. @code{a} and @code{b} are @code{v4i8} values, -and @code{c} and @code{d} are @code{v2q15} values. - -@multitable @columnfractions .50 .50 -@item C code @tab MIPS instruction -@item @code{a + b} @tab @code{addu.qb} -@item @code{c + d} @tab @code{addq.ph} -@item @code{a - b} @tab @code{subu.qb} -@item @code{c - d} @tab @code{subq.ph} -@end multitable - -The table below lists the @code{v2i16} operation for which -hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are -@code{v2i16} values. - -@multitable @columnfractions .50 .50 -@item C code @tab MIPS instruction -@item @code{e * f} @tab @code{mul.ph} -@end multitable - -It is easier to describe the DSP built-in functions if we first define -the following types: - -@smallexample -typedef int q31; -typedef int i32; -typedef unsigned int ui32; -typedef long long a64; -@end smallexample - -@code{q31} and @code{i32} are actually the same as @code{int}, but we -use @code{q31} to indicate a Q31 fractional value and @code{i32} to -indicate a 32-bit integer value. Similarly, @code{a64} is the same as -@code{long long}, but we use @code{a64} to indicate values that are -placed in one of the four DSP accumulators (@code{$ac0}, -@code{$ac1}, @code{$ac2} or @code{$ac3}). - -Also, some built-in functions prefer or require immediate numbers as -parameters, because the corresponding DSP instructions accept both immediate -numbers and register operands, or accept immediate numbers only. The -immediate parameters are listed as follows. - -@smallexample -imm0_3: 0 to 3. -imm0_7: 0 to 7. -imm0_15: 0 to 15. -imm0_31: 0 to 31. -imm0_63: 0 to 63. -imm0_255: 0 to 255. -imm_n32_31: -32 to 31. -imm_n512_511: -512 to 511. -@end smallexample - -The following built-in functions map directly to a particular MIPS DSP -instruction. Please refer to the architecture specification -for details on what each instruction does. - -@smallexample -v2q15 __builtin_mips_addq_ph (v2q15, v2q15) -v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) -q31 __builtin_mips_addq_s_w (q31, q31) -v4i8 __builtin_mips_addu_qb (v4i8, v4i8) -v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) -v2q15 __builtin_mips_subq_ph (v2q15, v2q15) -v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) -q31 __builtin_mips_subq_s_w (q31, q31) -v4i8 __builtin_mips_subu_qb (v4i8, v4i8) -v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) -i32 __builtin_mips_addsc (i32, i32) -i32 __builtin_mips_addwc (i32, i32) -i32 __builtin_mips_modsub (i32, i32) -i32 __builtin_mips_raddu_w_qb (v4i8) -v2q15 __builtin_mips_absq_s_ph (v2q15) -q31 __builtin_mips_absq_s_w (q31) -v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) -v2q15 __builtin_mips_precrq_ph_w (q31, q31) -v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) -v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) -q31 __builtin_mips_preceq_w_phl (v2q15) -q31 __builtin_mips_preceq_w_phr (v2q15) -v2q15 __builtin_mips_precequ_ph_qbl (v4i8) -v2q15 __builtin_mips_precequ_ph_qbr (v4i8) -v2q15 __builtin_mips_precequ_ph_qbla (v4i8) -v2q15 __builtin_mips_precequ_ph_qbra (v4i8) -v2q15 __builtin_mips_preceu_ph_qbl (v4i8) -v2q15 __builtin_mips_preceu_ph_qbr (v4i8) -v2q15 __builtin_mips_preceu_ph_qbla (v4i8) -v2q15 __builtin_mips_preceu_ph_qbra (v4i8) -v4i8 __builtin_mips_shll_qb (v4i8, imm0_7) -v4i8 __builtin_mips_shll_qb (v4i8, i32) -v2q15 __builtin_mips_shll_ph (v2q15, imm0_15) -v2q15 __builtin_mips_shll_ph (v2q15, i32) -v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) -v2q15 __builtin_mips_shll_s_ph (v2q15, i32) -q31 __builtin_mips_shll_s_w (q31, imm0_31) -q31 __builtin_mips_shll_s_w (q31, i32) -v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) -v4i8 __builtin_mips_shrl_qb (v4i8, i32) -v2q15 __builtin_mips_shra_ph (v2q15, imm0_15) -v2q15 __builtin_mips_shra_ph (v2q15, i32) -v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) -v2q15 __builtin_mips_shra_r_ph (v2q15, i32) -q31 __builtin_mips_shra_r_w (q31, imm0_31) -q31 __builtin_mips_shra_r_w (q31, i32) -v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) -v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) -v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) -q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) -q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) -a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) -a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) -a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) -a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) -a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) -a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) -a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) -a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) -a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) -a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) -a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) -a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) -a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) -i32 __builtin_mips_bitrev (i32) -i32 __builtin_mips_insv (i32, i32) -v4i8 __builtin_mips_repl_qb (imm0_255) -v4i8 __builtin_mips_repl_qb (i32) -v2q15 __builtin_mips_repl_ph (imm_n512_511) -v2q15 __builtin_mips_repl_ph (i32) -void __builtin_mips_cmpu_eq_qb (v4i8, v4i8) -void __builtin_mips_cmpu_lt_qb (v4i8, v4i8) -void __builtin_mips_cmpu_le_qb (v4i8, v4i8) -i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) -i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) -i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) -void __builtin_mips_cmp_eq_ph (v2q15, v2q15) -void __builtin_mips_cmp_lt_ph (v2q15, v2q15) -void __builtin_mips_cmp_le_ph (v2q15, v2q15) -v4i8 __builtin_mips_pick_qb (v4i8, v4i8) -v2q15 __builtin_mips_pick_ph (v2q15, v2q15) -v2q15 __builtin_mips_packrl_ph (v2q15, v2q15) -i32 __builtin_mips_extr_w (a64, imm0_31) -i32 __builtin_mips_extr_w (a64, i32) -i32 __builtin_mips_extr_r_w (a64, imm0_31) -i32 __builtin_mips_extr_s_h (a64, i32) -i32 __builtin_mips_extr_rs_w (a64, imm0_31) -i32 __builtin_mips_extr_rs_w (a64, i32) -i32 __builtin_mips_extr_s_h (a64, imm0_31) -i32 __builtin_mips_extr_r_w (a64, i32) -i32 __builtin_mips_extp (a64, imm0_31) -i32 __builtin_mips_extp (a64, i32) -i32 __builtin_mips_extpdp (a64, imm0_31) -i32 __builtin_mips_extpdp (a64, i32) -a64 __builtin_mips_shilo (a64, imm_n32_31) -a64 __builtin_mips_shilo (a64, i32) -a64 __builtin_mips_mthlip (a64, i32) -void __builtin_mips_wrdsp (i32, imm0_63) -i32 __builtin_mips_rddsp (imm0_63) -i32 __builtin_mips_lbux (void *, i32) -i32 __builtin_mips_lhx (void *, i32) -i32 __builtin_mips_lwx (void *, i32) -a64 __builtin_mips_ldx (void *, i32) [MIPS64 only] -i32 __builtin_mips_bposge32 (void) -a64 __builtin_mips_madd (a64, i32, i32); -a64 __builtin_mips_maddu (a64, ui32, ui32); -a64 __builtin_mips_msub (a64, i32, i32); -a64 __builtin_mips_msubu (a64, ui32, ui32); -a64 __builtin_mips_mult (i32, i32); -a64 __builtin_mips_multu (ui32, ui32); -@end smallexample - -The following built-in functions map directly to a particular MIPS DSP REV 2 -instruction. Please refer to the architecture specification -for details on what each instruction does. - -@smallexample -v4q7 __builtin_mips_absq_s_qb (v4q7); -v2i16 __builtin_mips_addu_ph (v2i16, v2i16); -v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16); -v4i8 __builtin_mips_adduh_qb (v4i8, v4i8); -v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8); -i32 __builtin_mips_append (i32, i32, imm0_31); -i32 __builtin_mips_balign (i32, i32, imm0_3); -i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8); -i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8); -i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8); -a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16); -a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16); -v2i16 __builtin_mips_mul_ph (v2i16, v2i16); -v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16); -q31 __builtin_mips_mulq_rs_w (q31, q31); -v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15); -q31 __builtin_mips_mulq_s_w (q31, q31); -a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16); -v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16); -v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31); -v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31); -i32 __builtin_mips_prepend (i32, i32, imm0_31); -v4i8 __builtin_mips_shra_qb (v4i8, imm0_7); -v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7); -v4i8 __builtin_mips_shra_qb (v4i8, i32); -v4i8 __builtin_mips_shra_r_qb (v4i8, i32); -v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15); -v2i16 __builtin_mips_shrl_ph (v2i16, i32); -v2i16 __builtin_mips_subu_ph (v2i16, v2i16); -v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16); -v4i8 __builtin_mips_subuh_qb (v4i8, v4i8); -v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8); -v2q15 __builtin_mips_addqh_ph (v2q15, v2q15); -v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15); -q31 __builtin_mips_addqh_w (q31, q31); -q31 __builtin_mips_addqh_r_w (q31, q31); -v2q15 __builtin_mips_subqh_ph (v2q15, v2q15); -v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15); -q31 __builtin_mips_subqh_w (q31, q31); -q31 __builtin_mips_subqh_r_w (q31, q31); -a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16); -a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16); -a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15); -a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15); -a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15); -a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15); -@end smallexample - - -@node MIPS Paired-Single Support -@subsection MIPS Paired-Single Support - -The MIPS64 architecture includes a number of instructions that -operate on pairs of single-precision floating-point values. -Each pair is packed into a 64-bit floating-point register, -with one element being designated the ``upper half'' and -the other being designated the ``lower half''. - -GCC supports paired-single operations using both the generic -vector extensions (@pxref{Vector Extensions}) and a collection of -MIPS-specific built-in functions. Both kinds of support are -enabled by the @option{-mpaired-single} command-line option. - -The vector type associated with paired-single values is usually -called @code{v2sf}. It can be defined in C as follows: - -@smallexample -typedef float v2sf __attribute__ ((vector_size (8))); -@end smallexample - -@code{v2sf} values are initialized in the same way as aggregates. -For example: - -@smallexample -v2sf a = @{1.5, 9.1@}; -v2sf b; -float e, f; -b = (v2sf) @{e, f@}; -@end smallexample - -@emph{Note:} The CPU's endianness determines which value is stored in -the upper half of a register and which value is stored in the lower half. -On little-endian targets, the first value is the lower one and the second -value is the upper one. The opposite order applies to big-endian targets. -For example, the code above sets the lower half of @code{a} to -@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. - -@node MIPS Loongson Built-in Functions -@subsection MIPS Loongson Built-in Functions - -GCC provides intrinsics to access the SIMD instructions provided by the -ST Microelectronics Loongson-2E and -2F processors. These intrinsics, -available after inclusion of the @code{loongson.h} header file, -operate on the following 64-bit vector types: - -@itemize -@item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers; -@item @code{uint16x4_t}, a vector of four unsigned 16-bit integers; -@item @code{uint32x2_t}, a vector of two unsigned 32-bit integers; -@item @code{int8x8_t}, a vector of eight signed 8-bit integers; -@item @code{int16x4_t}, a vector of four signed 16-bit integers; -@item @code{int32x2_t}, a vector of two signed 32-bit integers. -@end itemize - -The intrinsics provided are listed below; each is named after the -machine instruction to which it corresponds, with suffixes added as -appropriate to distinguish intrinsics that expand to the same machine -instruction yet have different argument types. Refer to the architecture -documentation for a description of the functionality of each -instruction. - -@smallexample -int16x4_t packsswh (int32x2_t s, int32x2_t t); -int8x8_t packsshb (int16x4_t s, int16x4_t t); -uint8x8_t packushb (uint16x4_t s, uint16x4_t t); -uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t); -uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t); -uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t); -int32x2_t paddw_s (int32x2_t s, int32x2_t t); -int16x4_t paddh_s (int16x4_t s, int16x4_t t); -int8x8_t paddb_s (int8x8_t s, int8x8_t t); -uint64_t paddd_u (uint64_t s, uint64_t t); -int64_t paddd_s (int64_t s, int64_t t); -int16x4_t paddsh (int16x4_t s, int16x4_t t); -int8x8_t paddsb (int8x8_t s, int8x8_t t); -uint16x4_t paddush (uint16x4_t s, uint16x4_t t); -uint8x8_t paddusb (uint8x8_t s, uint8x8_t t); -uint64_t pandn_ud (uint64_t s, uint64_t t); -uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t); -uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t); -uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t); -int64_t pandn_sd (int64_t s, int64_t t); -int32x2_t pandn_sw (int32x2_t s, int32x2_t t); -int16x4_t pandn_sh (int16x4_t s, int16x4_t t); -int8x8_t pandn_sb (int8x8_t s, int8x8_t t); -uint16x4_t pavgh (uint16x4_t s, uint16x4_t t); -uint8x8_t pavgb (uint8x8_t s, uint8x8_t t); -uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t); -uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t); -uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t); -int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t); -int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t); -int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t); -uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t); -uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t); -uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t); -int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t); -int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t); -int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t); -uint16x4_t pextrh_u (uint16x4_t s, int field); -int16x4_t pextrh_s (int16x4_t s, int field); -uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t); -uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t); -uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t); -uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t); -int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t); -int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t); -int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t); -int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t); -int32x2_t pmaddhw (int16x4_t s, int16x4_t t); -int16x4_t pmaxsh (int16x4_t s, int16x4_t t); -uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t); -int16x4_t pminsh (int16x4_t s, int16x4_t t); -uint8x8_t pminub (uint8x8_t s, uint8x8_t t); -uint8x8_t pmovmskb_u (uint8x8_t s); -int8x8_t pmovmskb_s (int8x8_t s); -uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t); -int16x4_t pmulhh (int16x4_t s, int16x4_t t); -int16x4_t pmullh (int16x4_t s, int16x4_t t); -int64_t pmuluw (uint32x2_t s, uint32x2_t t); -uint8x8_t pasubub (uint8x8_t s, uint8x8_t t); -uint16x4_t biadd (uint8x8_t s); -uint16x4_t psadbh (uint8x8_t s, uint8x8_t t); -uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order); -int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order); -uint16x4_t psllh_u (uint16x4_t s, uint8_t amount); -int16x4_t psllh_s (int16x4_t s, uint8_t amount); -uint32x2_t psllw_u (uint32x2_t s, uint8_t amount); -int32x2_t psllw_s (int32x2_t s, uint8_t amount); -uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount); -int16x4_t psrlh_s (int16x4_t s, uint8_t amount); -uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount); -int32x2_t psrlw_s (int32x2_t s, uint8_t amount); -uint16x4_t psrah_u (uint16x4_t s, uint8_t amount); -int16x4_t psrah_s (int16x4_t s, uint8_t amount); -uint32x2_t psraw_u (uint32x2_t s, uint8_t amount); -int32x2_t psraw_s (int32x2_t s, uint8_t amount); -uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t); -uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t); -uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t); -int32x2_t psubw_s (int32x2_t s, int32x2_t t); -int16x4_t psubh_s (int16x4_t s, int16x4_t t); -int8x8_t psubb_s (int8x8_t s, int8x8_t t); -uint64_t psubd_u (uint64_t s, uint64_t t); -int64_t psubd_s (int64_t s, int64_t t); -int16x4_t psubsh (int16x4_t s, int16x4_t t); -int8x8_t psubsb (int8x8_t s, int8x8_t t); -uint16x4_t psubush (uint16x4_t s, uint16x4_t t); -uint8x8_t psubusb (uint8x8_t s, uint8x8_t t); -uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t); -uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t); -uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t); -int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t); -int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t); -int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t); -uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t); -uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t); -uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t); -int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t); -int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t); -int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t); -@end smallexample - -@menu -* Paired-Single Arithmetic:: -* Paired-Single Built-in Functions:: -* MIPS-3D Built-in Functions:: -@end menu - -@node Paired-Single Arithmetic -@subsubsection Paired-Single Arithmetic - -The table below lists the @code{v2sf} operations for which hardware -support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} -values and @code{x} is an integral value. - -@multitable @columnfractions .50 .50 -@item C code @tab MIPS instruction -@item @code{a + b} @tab @code{add.ps} -@item @code{a - b} @tab @code{sub.ps} -@item @code{-a} @tab @code{neg.ps} -@item @code{a * b} @tab @code{mul.ps} -@item @code{a * b + c} @tab @code{madd.ps} -@item @code{a * b - c} @tab @code{msub.ps} -@item @code{-(a * b + c)} @tab @code{nmadd.ps} -@item @code{-(a * b - c)} @tab @code{nmsub.ps} -@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} -@end multitable - -Note that the multiply-accumulate instructions can be disabled -using the command-line option @code{-mno-fused-madd}. - -@node Paired-Single Built-in Functions -@subsubsection Paired-Single Built-in Functions - -The following paired-single functions map directly to a particular -MIPS instruction. Please refer to the architecture specification -for details on what each instruction does. - -@table @code -@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) -Pair lower lower (@code{pll.ps}). - -@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) -Pair upper lower (@code{pul.ps}). - -@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) -Pair lower upper (@code{plu.ps}). - -@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) -Pair upper upper (@code{puu.ps}). - -@item v2sf __builtin_mips_cvt_ps_s (float, float) -Convert pair to paired single (@code{cvt.ps.s}). - -@item float __builtin_mips_cvt_s_pl (v2sf) -Convert pair lower to single (@code{cvt.s.pl}). - -@item float __builtin_mips_cvt_s_pu (v2sf) -Convert pair upper to single (@code{cvt.s.pu}). - -@item v2sf __builtin_mips_abs_ps (v2sf) -Absolute value (@code{abs.ps}). - -@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) -Align variable (@code{alnv.ps}). - -@emph{Note:} The value of the third parameter must be 0 or 4 -modulo 8, otherwise the result is unpredictable. Please read the -instruction description for details. -@end table - -The following multi-instruction functions are also available. -In each case, @var{cond} can be any of the 16 floating-point conditions: -@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, -@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, -@code{lt}, @code{nge}, @code{le} or @code{ngt}. - -@table @code -@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) -@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) -Conditional move based on floating-point comparison (@code{c.@var{cond}.ps}, -@code{movt.ps}/@code{movf.ps}). - -The @code{movt} functions return the value @var{x} computed by: - -@smallexample -c.@var{cond}.ps @var{cc},@var{a},@var{b} -mov.ps @var{x},@var{c} -movt.ps @var{x},@var{d},@var{cc} -@end smallexample - -The @code{movf} functions are similar but use @code{movf.ps} instead -of @code{movt.ps}. - -@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) -@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) -Comparison of two paired-single values (@code{c.@var{cond}.ps}, -@code{bc1t}/@code{bc1f}). - -These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} -and return either the upper or lower half of the result. For example: - -@smallexample -v2sf a, b; -if (__builtin_mips_upper_c_eq_ps (a, b)) - upper_halves_are_equal (); -else - upper_halves_are_unequal (); - -if (__builtin_mips_lower_c_eq_ps (a, b)) - lower_halves_are_equal (); -else - lower_halves_are_unequal (); -@end smallexample -@end table - -@node MIPS-3D Built-in Functions -@subsubsection MIPS-3D Built-in Functions - -The MIPS-3D Application-Specific Extension (ASE) includes additional -paired-single instructions that are designed to improve the performance -of 3D graphics operations. Support for these instructions is controlled -by the @option{-mips3d} command-line option. - -The functions listed below map directly to a particular MIPS-3D -instruction. Please refer to the architecture specification for -more details on what each instruction does. - -@table @code -@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) -Reduction add (@code{addr.ps}). - -@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) -Reduction multiply (@code{mulr.ps}). - -@item v2sf __builtin_mips_cvt_pw_ps (v2sf) -Convert paired single to paired word (@code{cvt.pw.ps}). - -@item v2sf __builtin_mips_cvt_ps_pw (v2sf) -Convert paired word to paired single (@code{cvt.ps.pw}). - -@item float __builtin_mips_recip1_s (float) -@itemx double __builtin_mips_recip1_d (double) -@itemx v2sf __builtin_mips_recip1_ps (v2sf) -Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). - -@item float __builtin_mips_recip2_s (float, float) -@itemx double __builtin_mips_recip2_d (double, double) -@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) -Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). - -@item float __builtin_mips_rsqrt1_s (float) -@itemx double __builtin_mips_rsqrt1_d (double) -@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) -Reduced-precision reciprocal square root (sequence step 1) -(@code{rsqrt1.@var{fmt}}). - -@item float __builtin_mips_rsqrt2_s (float, float) -@itemx double __builtin_mips_rsqrt2_d (double, double) -@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) -Reduced-precision reciprocal square root (sequence step 2) -(@code{rsqrt2.@var{fmt}}). -@end table - -The following multi-instruction functions are also available. -In each case, @var{cond} can be any of the 16 floating-point conditions: -@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, -@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, -@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. - -@table @code -@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) -@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) -Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, -@code{bc1t}/@code{bc1f}). - -These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} -or @code{cabs.@var{cond}.d} and return the result as a boolean value. -For example: - -@smallexample -float a, b; -if (__builtin_mips_cabs_eq_s (a, b)) - true (); -else - false (); -@end smallexample - -@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) -@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) -Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, -@code{bc1t}/@code{bc1f}). - -These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} -and return either the upper or lower half of the result. For example: - -@smallexample -v2sf a, b; -if (__builtin_mips_upper_cabs_eq_ps (a, b)) - upper_halves_are_equal (); -else - upper_halves_are_unequal (); - -if (__builtin_mips_lower_cabs_eq_ps (a, b)) - lower_halves_are_equal (); -else - lower_halves_are_unequal (); -@end smallexample - -@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) -@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) -Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, -@code{movt.ps}/@code{movf.ps}). - -The @code{movt} functions return the value @var{x} computed by: - -@smallexample -cabs.@var{cond}.ps @var{cc},@var{a},@var{b} -mov.ps @var{x},@var{c} -movt.ps @var{x},@var{d},@var{cc} -@end smallexample - -The @code{movf} functions are similar but use @code{movf.ps} instead -of @code{movt.ps}. - -@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) -@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) -@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) -@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) -Comparison of two paired-single values -(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, -@code{bc1any2t}/@code{bc1any2f}). - -These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} -or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either -result is true and the @code{all} forms return true if both results are true. -For example: - -@smallexample -v2sf a, b; -if (__builtin_mips_any_c_eq_ps (a, b)) - one_is_true (); -else - both_are_false (); - -if (__builtin_mips_all_c_eq_ps (a, b)) - both_are_true (); -else - one_is_false (); -@end smallexample - -@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) -@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) -@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) -@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) -Comparison of four paired-single values -(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, -@code{bc1any4t}/@code{bc1any4f}). - -These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} -to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. -The @code{any} forms return true if any of the four results are true -and the @code{all} forms return true if all four results are true. -For example: - -@smallexample -v2sf a, b, c, d; -if (__builtin_mips_any_c_eq_4s (a, b, c, d)) - some_are_true (); -else - all_are_false (); - -if (__builtin_mips_all_c_eq_4s (a, b, c, d)) - all_are_true (); -else - some_are_false (); -@end smallexample -@end table - -@node Other MIPS Built-in Functions -@subsection Other MIPS Built-in Functions - -GCC provides other MIPS-specific built-in functions: - -@table @code -@item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr}) -Insert a @samp{cache} instruction with operands @var{op} and @var{addr}. -GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE} -when this function is available. -@end table - -@node picoChip Built-in Functions -@subsection picoChip Built-in Functions - -GCC provides an interface to selected machine instructions from the -picoChip instruction set. - -@table @code -@item int __builtin_sbc (int @var{value}) -Sign bit count. Return the number of consecutive bits in @var{value} -that have the same value as the sign bit. The result is the number of -leading sign bits minus one, giving the number of redundant sign bits in -@var{value}. - -@item int __builtin_byteswap (int @var{value}) -Byte swap. Return the result of swapping the upper and lower bytes of -@var{value}. - -@item int __builtin_brev (int @var{value}) -Bit reversal. Return the result of reversing the bits in -@var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1, -and so on. - -@item int __builtin_adds (int @var{x}, int @var{y}) -Saturating addition. Return the result of adding @var{x} and @var{y}, -storing the value 32767 if the result overflows. - -@item int __builtin_subs (int @var{x}, int @var{y}) -Saturating subtraction. Return the result of subtracting @var{y} from -@var{x}, storing the value @minus{}32768 if the result overflows. - -@item void __builtin_halt (void) -Halt. The processor stops execution. This built-in is useful for -implementing assertions. - -@end table - -@node PowerPC Built-in Functions -@subsection PowerPC Built-in Functions - -These built-in functions are available for the PowerPC family of -processors: -@smallexample -float __builtin_recipdivf (float, float); -float __builtin_rsqrtf (float); -double __builtin_recipdiv (double, double); -double __builtin_rsqrt (double); -long __builtin_bpermd (long, long); -uint64_t __builtin_ppc_get_timebase (); -unsigned long __builtin_ppc_mftb (); -@end smallexample - -The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and -@code{__builtin_rsqrtf} functions generate multiple instructions to -implement the reciprocal sqrt functionality using reciprocal sqrt -estimate instructions. - -The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf} -functions generate multiple instructions to implement division using -the reciprocal estimate instructions. - -The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb} -functions generate instructions to read the Time Base Register. The -@code{__builtin_ppc_get_timebase} function may generate multiple -instructions and always returns the 64 bits of the Time Base Register. -The @code{__builtin_ppc_mftb} function always generates one instruction and -returns the Time Base Register value as an unsigned long, throwing away -the most significant word on 32-bit environments. - -@node PowerPC AltiVec/VSX Built-in Functions -@subsection PowerPC AltiVec Built-in Functions - -GCC provides an interface for the PowerPC family of processors to access -the AltiVec operations described in Motorola's AltiVec Programming -Interface Manual. The interface is made available by including -@code{<altivec.h>} and using @option{-maltivec} and -@option{-mabi=altivec}. The interface supports the following vector -types. - -@smallexample -vector unsigned char -vector signed char -vector bool char - -vector unsigned short -vector signed short -vector bool short -vector pixel - -vector unsigned int -vector signed int -vector bool int -vector float -@end smallexample - -If @option{-mvsx} is used the following additional vector types are -implemented. - -@smallexample -vector unsigned long -vector signed long -vector double -@end smallexample - -The long types are only implemented for 64-bit code generation, and -the long type is only used in the floating point/integer conversion -instructions. - -GCC's implementation of the high-level language interface available from -C and C++ code differs from Motorola's documentation in several ways. - -@itemize @bullet - -@item -A vector constant is a list of constant expressions within curly braces. - -@item -A vector initializer requires no cast if the vector constant is of the -same type as the variable it is initializing. - -@item -If @code{signed} or @code{unsigned} is omitted, the signedness of the -vector type is the default signedness of the base type. The default -varies depending on the operating system, so a portable program should -always specify the signedness. - -@item -Compiling with @option{-maltivec} adds keywords @code{__vector}, -@code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and -@code{bool}. When compiling ISO C, the context-sensitive substitution -of the keywords @code{vector}, @code{pixel} and @code{bool} is -disabled. To use them, you must include @code{<altivec.h>} instead. - -@item -GCC allows using a @code{typedef} name as the type specifier for a -vector type. - -@item -For C, overloaded functions are implemented with macros so the following -does not work: - -@smallexample - vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); -@end smallexample - -@noindent -Since @code{vec_add} is a macro, the vector constant in the example -is treated as four separate arguments. Wrap the entire argument in -parentheses for this to work. -@end itemize - -@emph{Note:} Only the @code{<altivec.h>} interface is supported. -Internally, GCC uses built-in functions to achieve the functionality in -the aforementioned header file, but they are not supported and are -subject to change without notice. - -The following interfaces are supported for the generic and specific -AltiVec operations and the AltiVec predicates. In cases where there -is a direct mapping between generic and specific operations, only the -generic names are shown here, although the specific operations can also -be used. - -Arguments that are documented as @code{const int} require literal -integral values within the range required for that operation. - -@smallexample -vector signed char vec_abs (vector signed char); -vector signed short vec_abs (vector signed short); -vector signed int vec_abs (vector signed int); -vector float vec_abs (vector float); - -vector signed char vec_abss (vector signed char); -vector signed short vec_abss (vector signed short); -vector signed int vec_abss (vector signed int); - -vector signed char vec_add (vector bool char, vector signed char); -vector signed char vec_add (vector signed char, vector bool char); -vector signed char vec_add (vector signed char, vector signed char); -vector unsigned char vec_add (vector bool char, vector unsigned char); -vector unsigned char vec_add (vector unsigned char, vector bool char); -vector unsigned char vec_add (vector unsigned char, - vector unsigned char); -vector signed short vec_add (vector bool short, vector signed short); -vector signed short vec_add (vector signed short, vector bool short); -vector signed short vec_add (vector signed short, vector signed short); -vector unsigned short vec_add (vector bool short, - vector unsigned short); -vector unsigned short vec_add (vector unsigned short, - vector bool short); -vector unsigned short vec_add (vector unsigned short, - vector unsigned short); -vector signed int vec_add (vector bool int, vector signed int); -vector signed int vec_add (vector signed int, vector bool int); -vector signed int vec_add (vector signed int, vector signed int); -vector unsigned int vec_add (vector bool int, vector unsigned int); -vector unsigned int vec_add (vector unsigned int, vector bool int); -vector unsigned int vec_add (vector unsigned int, vector unsigned int); -vector float vec_add (vector float, vector float); - -vector float vec_vaddfp (vector float, vector float); - -vector signed int vec_vadduwm (vector bool int, vector signed int); -vector signed int vec_vadduwm (vector signed int, vector bool int); -vector signed int vec_vadduwm (vector signed int, vector signed int); -vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); -vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); -vector unsigned int vec_vadduwm (vector unsigned int, - vector unsigned int); - -vector signed short vec_vadduhm (vector bool short, - vector signed short); -vector signed short vec_vadduhm (vector signed short, - vector bool short); -vector signed short vec_vadduhm (vector signed short, - vector signed short); -vector unsigned short vec_vadduhm (vector bool short, - vector unsigned short); -vector unsigned short vec_vadduhm (vector unsigned short, - vector bool short); -vector unsigned short vec_vadduhm (vector unsigned short, - vector unsigned short); - -vector signed char vec_vaddubm (vector bool char, vector signed char); -vector signed char vec_vaddubm (vector signed char, vector bool char); -vector signed char vec_vaddubm (vector signed char, vector signed char); -vector unsigned char vec_vaddubm (vector bool char, - vector unsigned char); -vector unsigned char vec_vaddubm (vector unsigned char, - vector bool char); -vector unsigned char vec_vaddubm (vector unsigned char, - vector unsigned char); - -vector unsigned int vec_addc (vector unsigned int, vector unsigned int); - -vector unsigned char vec_adds (vector bool char, vector unsigned char); -vector unsigned char vec_adds (vector unsigned char, vector bool char); -vector unsigned char vec_adds (vector unsigned char, - vector unsigned char); -vector signed char vec_adds (vector bool char, vector signed char); -vector signed char vec_adds (vector signed char, vector bool char); -vector signed char vec_adds (vector signed char, vector signed char); -vector unsigned short vec_adds (vector bool short, - vector unsigned short); -vector unsigned short vec_adds (vector unsigned short, - vector bool short); -vector unsigned short vec_adds (vector unsigned short, - vector unsigned short); -vector signed short vec_adds (vector bool short, vector signed short); -vector signed short vec_adds (vector signed short, vector bool short); -vector signed short vec_adds (vector signed short, vector signed short); -vector unsigned int vec_adds (vector bool int, vector unsigned int); -vector unsigned int vec_adds (vector unsigned int, vector bool int); -vector unsigned int vec_adds (vector unsigned int, vector unsigned int); -vector signed int vec_adds (vector bool int, vector signed int); -vector signed int vec_adds (vector signed int, vector bool int); -vector signed int vec_adds (vector signed int, vector signed int); - -vector signed int vec_vaddsws (vector bool int, vector signed int); -vector signed int vec_vaddsws (vector signed int, vector bool int); -vector signed int vec_vaddsws (vector signed int, vector signed int); - -vector unsigned int vec_vadduws (vector bool int, vector unsigned int); -vector unsigned int vec_vadduws (vector unsigned int, vector bool int); -vector unsigned int vec_vadduws (vector unsigned int, - vector unsigned int); - -vector signed short vec_vaddshs (vector bool short, - vector signed short); -vector signed short vec_vaddshs (vector signed short, - vector bool short); -vector signed short vec_vaddshs (vector signed short, - vector signed short); - -vector unsigned short vec_vadduhs (vector bool short, - vector unsigned short); -vector unsigned short vec_vadduhs (vector unsigned short, - vector bool short); -vector unsigned short vec_vadduhs (vector unsigned short, - vector unsigned short); - -vector signed char vec_vaddsbs (vector bool char, vector signed char); -vector signed char vec_vaddsbs (vector signed char, vector bool char); -vector signed char vec_vaddsbs (vector signed char, vector signed char); - -vector unsigned char vec_vaddubs (vector bool char, - vector unsigned char); -vector unsigned char vec_vaddubs (vector unsigned char, - vector bool char); -vector unsigned char vec_vaddubs (vector unsigned char, - vector unsigned char); - -vector float vec_and (vector float, vector float); -vector float vec_and (vector float, vector bool int); -vector float vec_and (vector bool int, vector float); -vector bool int vec_and (vector bool int, vector bool int); -vector signed int vec_and (vector bool int, vector signed int); -vector signed int vec_and (vector signed int, vector bool int); -vector signed int vec_and (vector signed int, vector signed int); -vector unsigned int vec_and (vector bool int, vector unsigned int); -vector unsigned int vec_and (vector unsigned int, vector bool int); -vector unsigned int vec_and (vector unsigned int, vector unsigned int); -vector bool short vec_and (vector bool short, vector bool short); -vector signed short vec_and (vector bool short, vector signed short); -vector signed short vec_and (vector signed short, vector bool short); -vector signed short vec_and (vector signed short, vector signed short); -vector unsigned short vec_and (vector bool short, - vector unsigned short); -vector unsigned short vec_and (vector unsigned short, - vector bool short); -vector unsigned short vec_and (vector unsigned short, - vector unsigned short); -vector signed char vec_and (vector bool char, vector signed char); -vector bool char vec_and (vector bool char, vector bool char); -vector signed char vec_and (vector signed char, vector bool char); -vector signed char vec_and (vector signed char, vector signed char); -vector unsigned char vec_and (vector bool char, vector unsigned char); -vector unsigned char vec_and (vector unsigned char, vector bool 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 bool int); -vector float vec_andc (vector bool int, vector float); -vector bool int vec_andc (vector bool int, vector bool int); -vector signed int vec_andc (vector bool int, vector signed int); -vector signed int vec_andc (vector signed int, vector bool int); -vector signed int vec_andc (vector signed int, vector signed int); -vector unsigned int vec_andc (vector bool int, vector unsigned int); -vector unsigned int vec_andc (vector unsigned int, vector bool int); -vector unsigned int vec_andc (vector unsigned int, vector unsigned int); -vector bool short vec_andc (vector bool short, vector bool short); -vector signed short vec_andc (vector bool short, vector signed short); -vector signed short vec_andc (vector signed short, vector bool short); -vector signed short vec_andc (vector signed short, vector signed short); -vector unsigned short vec_andc (vector bool short, - vector unsigned short); -vector unsigned short vec_andc (vector unsigned short, - vector bool short); -vector unsigned short vec_andc (vector unsigned short, - vector unsigned short); -vector signed char vec_andc (vector bool char, vector signed char); -vector bool char vec_andc (vector bool char, vector bool char); -vector signed char vec_andc (vector signed char, vector bool char); -vector signed char vec_andc (vector signed char, vector signed char); -vector unsigned char vec_andc (vector bool char, vector unsigned char); -vector unsigned char vec_andc (vector unsigned char, vector bool 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 signed int vec_vavgsw (vector signed int, vector signed int); - -vector unsigned int vec_vavguw (vector unsigned int, - vector unsigned int); - -vector signed short vec_vavgsh (vector signed short, - vector signed short); - -vector unsigned short vec_vavguh (vector unsigned short, - vector unsigned short); - -vector signed char vec_vavgsb (vector signed char, vector signed char); - -vector unsigned char vec_vavgub (vector unsigned char, - vector unsigned char); - -vector float vec_copysign (vector float); - -vector float vec_ceil (vector float); - -vector signed int vec_cmpb (vector float, vector float); - -vector bool char vec_cmpeq (vector signed char, vector signed char); -vector bool char vec_cmpeq (vector unsigned char, vector unsigned char); -vector bool short vec_cmpeq (vector signed short, vector signed short); -vector bool short vec_cmpeq (vector unsigned short, - vector unsigned short); -vector bool int vec_cmpeq (vector signed int, vector signed int); -vector bool int vec_cmpeq (vector unsigned int, vector unsigned int); -vector bool int vec_cmpeq (vector float, vector float); - -vector bool int vec_vcmpeqfp (vector float, vector float); - -vector bool int vec_vcmpequw (vector signed int, vector signed int); -vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); - -vector bool short vec_vcmpequh (vector signed short, - vector signed short); -vector bool short vec_vcmpequh (vector unsigned short, - vector unsigned short); - -vector bool char vec_vcmpequb (vector signed char, vector signed char); -vector bool char vec_vcmpequb (vector unsigned char, - vector unsigned char); - -vector bool int vec_cmpge (vector float, vector float); - -vector bool char vec_cmpgt (vector unsigned char, vector unsigned char); -vector bool char vec_cmpgt (vector signed char, vector signed char); -vector bool short vec_cmpgt (vector unsigned short, - vector unsigned short); -vector bool short vec_cmpgt (vector signed short, vector signed short); -vector bool int vec_cmpgt (vector unsigned int, vector unsigned int); -vector bool int vec_cmpgt (vector signed int, vector signed int); -vector bool int vec_cmpgt (vector float, vector float); - -vector bool int vec_vcmpgtfp (vector float, vector float); - -vector bool int vec_vcmpgtsw (vector signed int, vector signed int); - -vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); - -vector bool short vec_vcmpgtsh (vector signed short, - vector signed short); - -vector bool short vec_vcmpgtuh (vector unsigned short, - vector unsigned short); - -vector bool char vec_vcmpgtsb (vector signed char, vector signed char); - -vector bool char vec_vcmpgtub (vector unsigned char, - vector unsigned char); - -vector bool int vec_cmple (vector float, vector float); - -vector bool char vec_cmplt (vector unsigned char, vector unsigned char); -vector bool char vec_cmplt (vector signed char, vector signed char); -vector bool short vec_cmplt (vector unsigned short, - vector unsigned short); -vector bool short vec_cmplt (vector signed short, vector signed short); -vector bool int vec_cmplt (vector unsigned int, vector unsigned int); -vector bool int vec_cmplt (vector signed int, vector signed int); -vector bool int vec_cmplt (vector float, vector float); - -vector float vec_ctf (vector unsigned int, const int); -vector float vec_ctf (vector signed int, const int); - -vector float vec_vcfsx (vector signed int, const int); - -vector float vec_vcfux (vector unsigned int, const int); - -vector signed int vec_cts (vector float, const int); - -vector unsigned int vec_ctu (vector float, const int); - -void vec_dss (const int); - -void vec_dssall (void); - -void vec_dst (const vector unsigned char *, int, const int); -void vec_dst (const vector signed char *, int, const int); -void vec_dst (const vector bool char *, int, const int); -void vec_dst (const vector unsigned short *, int, const int); -void vec_dst (const vector signed short *, int, const int); -void vec_dst (const vector bool short *, int, const int); -void vec_dst (const vector pixel *, int, const int); -void vec_dst (const vector unsigned int *, int, const int); -void vec_dst (const vector signed int *, int, const int); -void vec_dst (const vector bool int *, int, const int); -void vec_dst (const vector float *, int, const int); -void vec_dst (const unsigned char *, int, const int); -void vec_dst (const signed char *, int, const int); -void vec_dst (const unsigned short *, int, const int); -void vec_dst (const short *, int, const int); -void vec_dst (const unsigned int *, int, const int); -void vec_dst (const int *, int, const int); -void vec_dst (const unsigned long *, int, const int); -void vec_dst (const long *, int, const int); -void vec_dst (const float *, int, const int); - -void vec_dstst (const vector unsigned char *, int, const int); -void vec_dstst (const vector signed char *, int, const int); -void vec_dstst (const vector bool char *, int, const int); -void vec_dstst (const vector unsigned short *, int, const int); -void vec_dstst (const vector signed short *, int, const int); -void vec_dstst (const vector bool short *, int, const int); -void vec_dstst (const vector pixel *, int, const int); -void vec_dstst (const vector unsigned int *, int, const int); -void vec_dstst (const vector signed int *, int, const int); -void vec_dstst (const vector bool int *, int, const int); -void vec_dstst (const vector float *, int, const int); -void vec_dstst (const unsigned char *, int, const int); -void vec_dstst (const signed char *, int, const int); -void vec_dstst (const unsigned short *, int, const int); -void vec_dstst (const short *, int, const int); -void vec_dstst (const unsigned int *, int, const int); -void vec_dstst (const int *, int, const int); -void vec_dstst (const unsigned long *, int, const int); -void vec_dstst (const long *, int, const int); -void vec_dstst (const float *, int, const int); - -void vec_dststt (const vector unsigned char *, int, const int); -void vec_dststt (const vector signed char *, int, const int); -void vec_dststt (const vector bool char *, int, const int); -void vec_dststt (const vector unsigned short *, int, const int); -void vec_dststt (const vector signed short *, int, const int); -void vec_dststt (const vector bool short *, int, const int); -void vec_dststt (const vector pixel *, int, const int); -void vec_dststt (const vector unsigned int *, int, const int); -void vec_dststt (const vector signed int *, int, const int); -void vec_dststt (const vector bool int *, int, const int); -void vec_dststt (const vector float *, int, const int); -void vec_dststt (const unsigned char *, int, const int); -void vec_dststt (const signed char *, int, const int); -void vec_dststt (const unsigned short *, int, const int); -void vec_dststt (const short *, int, const int); -void vec_dststt (const unsigned int *, int, const int); -void vec_dststt (const int *, int, const int); -void vec_dststt (const unsigned long *, int, const int); -void vec_dststt (const long *, int, const int); -void vec_dststt (const float *, int, const int); - -void vec_dstt (const vector unsigned char *, int, const int); -void vec_dstt (const vector signed char *, int, const int); -void vec_dstt (const vector bool char *, int, const int); -void vec_dstt (const vector unsigned short *, int, const int); -void vec_dstt (const vector signed short *, int, const int); -void vec_dstt (const vector bool short *, int, const int); -void vec_dstt (const vector pixel *, int, const int); -void vec_dstt (const vector unsigned int *, int, const int); -void vec_dstt (const vector signed int *, int, const int); -void vec_dstt (const vector bool int *, int, const int); -void vec_dstt (const vector float *, int, const int); -void vec_dstt (const unsigned char *, int, const int); -void vec_dstt (const signed char *, int, const int); -void vec_dstt (const unsigned short *, int, const int); -void vec_dstt (const short *, int, const int); -void vec_dstt (const unsigned int *, int, const int); -void vec_dstt (const int *, int, const int); -void vec_dstt (const unsigned long *, int, const int); -void vec_dstt (const long *, int, const int); -void vec_dstt (const float *, int, const int); - -vector float vec_expte (vector float); - -vector float vec_floor (vector float); - -vector float vec_ld (int, const vector float *); -vector float vec_ld (int, const float *); -vector bool int vec_ld (int, const vector bool int *); -vector signed int vec_ld (int, const vector signed int *); -vector signed int vec_ld (int, const int *); -vector signed int vec_ld (int, const long *); -vector unsigned int vec_ld (int, const vector unsigned int *); -vector unsigned int vec_ld (int, const unsigned int *); -vector unsigned int vec_ld (int, const unsigned long *); -vector bool short vec_ld (int, const vector bool short *); -vector pixel vec_ld (int, const vector pixel *); -vector signed short vec_ld (int, const vector signed short *); -vector signed short vec_ld (int, const short *); -vector unsigned short vec_ld (int, const vector unsigned short *); -vector unsigned short vec_ld (int, const unsigned short *); -vector bool char vec_ld (int, const vector bool char *); -vector signed char vec_ld (int, const vector signed char *); -vector signed char vec_ld (int, const signed char *); -vector unsigned char vec_ld (int, const vector unsigned char *); -vector unsigned char vec_ld (int, const unsigned char *); - -vector signed char vec_lde (int, const signed char *); -vector unsigned char vec_lde (int, const unsigned char *); -vector signed short vec_lde (int, const short *); -vector unsigned short vec_lde (int, const unsigned short *); -vector float vec_lde (int, const float *); -vector signed int vec_lde (int, const int *); -vector unsigned int vec_lde (int, const unsigned int *); -vector signed int vec_lde (int, const long *); -vector unsigned int vec_lde (int, const unsigned long *); - -vector float vec_lvewx (int, float *); -vector signed int vec_lvewx (int, int *); -vector unsigned int vec_lvewx (int, unsigned int *); -vector signed int vec_lvewx (int, long *); -vector unsigned int vec_lvewx (int, unsigned long *); - -vector signed short vec_lvehx (int, short *); -vector unsigned short vec_lvehx (int, unsigned short *); - -vector signed char vec_lvebx (int, char *); -vector unsigned char vec_lvebx (int, unsigned char *); - -vector float vec_ldl (int, const vector float *); -vector float vec_ldl (int, const float *); -vector bool int vec_ldl (int, const vector bool int *); -vector signed int vec_ldl (int, const vector signed int *); -vector signed int vec_ldl (int, const int *); -vector signed int vec_ldl (int, const long *); -vector unsigned int vec_ldl (int, const vector unsigned int *); -vector unsigned int vec_ldl (int, const unsigned int *); -vector unsigned int vec_ldl (int, const unsigned long *); -vector bool short vec_ldl (int, const vector bool short *); -vector pixel vec_ldl (int, const vector pixel *); -vector signed short vec_ldl (int, const vector signed short *); -vector signed short vec_ldl (int, const short *); -vector unsigned short vec_ldl (int, const vector unsigned short *); -vector unsigned short vec_ldl (int, const unsigned short *); -vector bool char vec_ldl (int, const vector bool char *); -vector signed char vec_ldl (int, const vector signed char *); -vector signed char vec_ldl (int, const signed char *); -vector unsigned char vec_ldl (int, const vector unsigned char *); -vector unsigned char vec_ldl (int, const unsigned char *); - -vector float vec_loge (vector float); - -vector unsigned char vec_lvsl (int, const volatile unsigned char *); -vector unsigned char vec_lvsl (int, const volatile signed char *); -vector unsigned char vec_lvsl (int, const volatile unsigned short *); -vector unsigned char vec_lvsl (int, const volatile short *); -vector unsigned char vec_lvsl (int, const volatile unsigned int *); -vector unsigned char vec_lvsl (int, const volatile int *); -vector unsigned char vec_lvsl (int, const volatile unsigned long *); -vector unsigned char vec_lvsl (int, const volatile long *); -vector unsigned char vec_lvsl (int, const volatile float *); - -vector unsigned char vec_lvsr (int, const volatile unsigned char *); -vector unsigned char vec_lvsr (int, const volatile signed char *); -vector unsigned char vec_lvsr (int, const volatile unsigned short *); -vector unsigned char vec_lvsr (int, const volatile short *); -vector unsigned char vec_lvsr (int, const volatile unsigned int *); -vector unsigned char vec_lvsr (int, const volatile int *); -vector unsigned char vec_lvsr (int, const volatile unsigned long *); -vector unsigned char vec_lvsr (int, const volatile long *); -vector unsigned char vec_lvsr (int, const volatile float *); - -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 bool char, vector unsigned char); -vector unsigned char vec_max (vector unsigned char, vector bool char); -vector unsigned char vec_max (vector unsigned char, - vector unsigned char); -vector signed char vec_max (vector bool char, vector signed char); -vector signed char vec_max (vector signed char, vector bool char); -vector signed char vec_max (vector signed char, vector signed char); -vector unsigned short vec_max (vector bool short, - vector unsigned short); -vector unsigned short vec_max (vector unsigned short, - vector bool short); -vector unsigned short vec_max (vector unsigned short, - vector unsigned short); -vector signed short vec_max (vector bool short, vector signed short); -vector signed short vec_max (vector signed short, vector bool short); -vector signed short vec_max (vector signed short, vector signed short); -vector unsigned int vec_max (vector bool int, vector unsigned int); -vector unsigned int vec_max (vector unsigned int, vector bool int); -vector unsigned int vec_max (vector unsigned int, vector unsigned int); -vector signed int vec_max (vector bool int, vector signed int); -vector signed int vec_max (vector signed int, vector bool int); -vector signed int vec_max (vector signed int, vector signed int); -vector float vec_max (vector float, vector float); - -vector float vec_vmaxfp (vector float, vector float); - -vector signed int vec_vmaxsw (vector bool int, vector signed int); -vector signed int vec_vmaxsw (vector signed int, vector bool int); -vector signed int vec_vmaxsw (vector signed int, vector signed int); - -vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); -vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); -vector unsigned int vec_vmaxuw (vector unsigned int, - vector unsigned int); - -vector signed short vec_vmaxsh (vector bool short, vector signed short); -vector signed short vec_vmaxsh (vector signed short, vector bool short); -vector signed short vec_vmaxsh (vector signed short, - vector signed short); - -vector unsigned short vec_vmaxuh (vector bool short, - vector unsigned short); -vector unsigned short vec_vmaxuh (vector unsigned short, - vector bool short); -vector unsigned short vec_vmaxuh (vector unsigned short, - vector unsigned short); - -vector signed char vec_vmaxsb (vector bool char, vector signed char); -vector signed char vec_vmaxsb (vector signed char, vector bool char); -vector signed char vec_vmaxsb (vector signed char, vector signed char); - -vector unsigned char vec_vmaxub (vector bool char, - vector unsigned char); -vector unsigned char vec_vmaxub (vector unsigned char, - vector bool char); -vector unsigned char vec_vmaxub (vector unsigned char, - vector unsigned char); - -vector bool char vec_mergeh (vector bool char, vector bool char); -vector signed char vec_mergeh (vector signed char, vector signed char); -vector unsigned char vec_mergeh (vector unsigned char, - vector unsigned char); -vector bool short vec_mergeh (vector bool short, vector bool short); -vector pixel vec_mergeh (vector pixel, vector pixel); -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 bool int vec_mergeh (vector bool int, vector bool int); -vector signed int vec_mergeh (vector signed int, vector signed int); -vector unsigned int vec_mergeh (vector unsigned int, - vector unsigned int); - -vector float vec_vmrghw (vector float, vector float); -vector bool int vec_vmrghw (vector bool int, vector bool int); -vector signed int vec_vmrghw (vector signed int, vector signed int); -vector unsigned int vec_vmrghw (vector unsigned int, - vector unsigned int); - -vector bool short vec_vmrghh (vector bool short, vector bool short); -vector signed short vec_vmrghh (vector signed short, - vector signed short); -vector unsigned short vec_vmrghh (vector unsigned short, - vector unsigned short); -vector pixel vec_vmrghh (vector pixel, vector pixel); - -vector bool char vec_vmrghb (vector bool char, vector bool char); -vector signed char vec_vmrghb (vector signed char, vector signed char); -vector unsigned char vec_vmrghb (vector unsigned char, - vector unsigned char); - -vector bool char vec_mergel (vector bool char, vector bool char); -vector signed char vec_mergel (vector signed char, vector signed char); -vector unsigned char vec_mergel (vector unsigned char, - vector unsigned char); -vector bool short vec_mergel (vector bool short, vector bool short); -vector pixel vec_mergel (vector pixel, vector pixel); -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 bool int vec_mergel (vector bool int, vector bool int); -vector signed int vec_mergel (vector signed int, vector signed int); -vector unsigned int vec_mergel (vector unsigned int, - vector unsigned int); - -vector float vec_vmrglw (vector float, vector float); -vector signed int vec_vmrglw (vector signed int, vector signed int); -vector unsigned int vec_vmrglw (vector unsigned int, - vector unsigned int); -vector bool int vec_vmrglw (vector bool int, vector bool int); - -vector bool short vec_vmrglh (vector bool short, vector bool short); -vector signed short vec_vmrglh (vector signed short, - vector signed short); -vector unsigned short vec_vmrglh (vector unsigned short, - vector unsigned short); -vector pixel vec_vmrglh (vector pixel, vector pixel); - -vector bool char vec_vmrglb (vector bool char, vector bool char); -vector signed char vec_vmrglb (vector signed char, vector signed char); -vector unsigned char vec_vmrglb (vector unsigned char, - vector unsigned char); - -vector unsigned short vec_mfvscr (void); - -vector unsigned char vec_min (vector bool char, vector unsigned char); -vector unsigned char vec_min (vector unsigned char, vector bool char); -vector unsigned char vec_min (vector unsigned char, - vector unsigned char); -vector signed char vec_min (vector bool char, vector signed char); -vector signed char vec_min (vector signed char, vector bool char); -vector signed char vec_min (vector signed char, vector signed char); -vector unsigned short vec_min (vector bool short, - vector unsigned short); -vector unsigned short vec_min (vector unsigned short, - vector bool short); -vector unsigned short vec_min (vector unsigned short, - vector unsigned short); -vector signed short vec_min (vector bool short, vector signed short); -vector signed short vec_min (vector signed short, vector bool short); -vector signed short vec_min (vector signed short, vector signed short); -vector unsigned int vec_min (vector bool int, vector unsigned int); -vector unsigned int vec_min (vector unsigned int, vector bool int); -vector unsigned int vec_min (vector unsigned int, vector unsigned int); -vector signed int vec_min (vector bool int, vector signed int); -vector signed int vec_min (vector signed int, vector bool int); -vector signed int vec_min (vector signed int, vector signed int); -vector float vec_min (vector float, vector float); - -vector float vec_vminfp (vector float, vector float); - -vector signed int vec_vminsw (vector bool int, vector signed int); -vector signed int vec_vminsw (vector signed int, vector bool int); -vector signed int vec_vminsw (vector signed int, vector signed int); - -vector unsigned int vec_vminuw (vector bool int, vector unsigned int); -vector unsigned int vec_vminuw (vector unsigned int, vector bool int); -vector unsigned int vec_vminuw (vector unsigned int, - vector unsigned int); - -vector signed short vec_vminsh (vector bool short, vector signed short); -vector signed short vec_vminsh (vector signed short, vector bool short); -vector signed short vec_vminsh (vector signed short, - vector signed short); - -vector unsigned short vec_vminuh (vector bool short, - vector unsigned short); -vector unsigned short vec_vminuh (vector unsigned short, - vector bool short); -vector unsigned short vec_vminuh (vector unsigned short, - vector unsigned short); - -vector signed char vec_vminsb (vector bool char, vector signed char); -vector signed char vec_vminsb (vector signed char, vector bool char); -vector signed char vec_vminsb (vector signed char, vector signed char); - -vector unsigned char vec_vminub (vector bool char, - vector unsigned char); -vector unsigned char vec_vminub (vector unsigned char, - vector bool char); -vector unsigned char vec_vminub (vector unsigned char, - vector unsigned char); - -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 signed int vec_vmsumshm (vector signed short, - vector signed short, - vector signed int); - -vector unsigned int vec_vmsumuhm (vector unsigned short, - vector unsigned short, - vector unsigned int); - -vector signed int vec_vmsummbm (vector signed char, - vector unsigned char, - vector signed int); - -vector unsigned int vec_vmsumubm (vector unsigned char, - vector unsigned char, - vector unsigned 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); - -vector signed int vec_vmsumshs (vector signed short, - vector signed short, - vector signed int); - -vector unsigned int vec_vmsumuhs (vector unsigned short, - vector unsigned short, - vector unsigned int); - -void vec_mtvscr (vector signed int); -void vec_mtvscr (vector unsigned int); -void vec_mtvscr (vector bool int); -void vec_mtvscr (vector signed short); -void vec_mtvscr (vector unsigned short); -void vec_mtvscr (vector bool short); -void vec_mtvscr (vector pixel); -void vec_mtvscr (vector signed char); -void vec_mtvscr (vector unsigned char); -void vec_mtvscr (vector bool 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 signed int vec_vmulesh (vector signed short, - vector signed short); - -vector unsigned int vec_vmuleuh (vector unsigned short, - vector unsigned short); - -vector signed short vec_vmulesb (vector signed char, - vector signed char); - -vector unsigned short vec_vmuleub (vector unsigned char, - vector unsigned char); - -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 signed int vec_vmulosh (vector signed short, - vector signed short); - -vector unsigned int vec_vmulouh (vector unsigned short, - vector unsigned short); - -vector signed short vec_vmulosb (vector signed char, - vector signed char); - -vector unsigned short vec_vmuloub (vector unsigned char, - vector unsigned char); - -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 bool int vec_nor (vector bool int, vector bool int); -vector signed short vec_nor (vector signed short, vector signed short); -vector unsigned short vec_nor (vector unsigned short, - vector unsigned short); -vector bool short vec_nor (vector bool short, vector bool short); -vector signed char vec_nor (vector signed char, vector signed char); -vector unsigned char vec_nor (vector unsigned char, - vector unsigned char); -vector bool char vec_nor (vector bool char, vector bool char); - -vector float vec_or (vector float, vector float); -vector float vec_or (vector float, vector bool int); -vector float vec_or (vector bool int, vector float); -vector bool int vec_or (vector bool int, vector bool int); -vector signed int vec_or (vector bool int, vector signed int); -vector signed int vec_or (vector signed int, vector bool int); -vector signed int vec_or (vector signed int, vector signed int); -vector unsigned int vec_or (vector bool int, vector unsigned int); -vector unsigned int vec_or (vector unsigned int, vector bool int); -vector unsigned int vec_or (vector unsigned int, vector unsigned int); -vector bool short vec_or (vector bool short, vector bool short); -vector signed short vec_or (vector bool short, vector signed short); -vector signed short vec_or (vector signed short, vector bool short); -vector signed short vec_or (vector signed short, vector signed short); -vector unsigned short vec_or (vector bool short, vector unsigned short); -vector unsigned short vec_or (vector unsigned short, vector bool short); -vector unsigned short vec_or (vector unsigned short, - vector unsigned short); -vector signed char vec_or (vector bool char, vector signed char); -vector bool char vec_or (vector bool char, vector bool char); -vector signed char vec_or (vector signed char, vector bool char); -vector signed char vec_or (vector signed char, vector signed char); -vector unsigned char vec_or (vector bool char, vector unsigned char); -vector unsigned char vec_or (vector unsigned char, vector bool 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 bool char vec_pack (vector bool short, vector bool short); -vector signed short vec_pack (vector signed int, vector signed int); -vector unsigned short vec_pack (vector unsigned int, - vector unsigned int); -vector bool short vec_pack (vector bool int, vector bool int); - -vector bool short vec_vpkuwum (vector bool int, vector bool int); -vector signed short vec_vpkuwum (vector signed int, vector signed int); -vector unsigned short vec_vpkuwum (vector unsigned int, - vector unsigned int); - -vector bool char vec_vpkuhum (vector bool short, vector bool short); -vector signed char vec_vpkuhum (vector signed short, - vector signed short); -vector unsigned char vec_vpkuhum (vector unsigned short, - vector unsigned short); - -vector pixel 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 signed short vec_vpkswss (vector signed int, vector signed int); - -vector unsigned short vec_vpkuwus (vector unsigned int, - vector unsigned int); - -vector signed char vec_vpkshss (vector signed short, - vector signed short); - -vector unsigned char vec_vpkuhus (vector unsigned short, - vector unsigned short); - -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 unsigned short vec_vpkswus (vector signed int, - vector signed int); - -vector unsigned char vec_vpkshus (vector signed short, - vector signed short); - -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 bool int vec_perm (vector bool int, - vector bool 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 bool short vec_perm (vector bool short, - vector bool short, - vector unsigned char); -vector pixel vec_perm (vector pixel, - vector pixel, - 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 bool char vec_perm (vector bool char, - vector bool 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 signed int vec_vrlw (vector signed int, vector unsigned int); -vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); - -vector signed short vec_vrlh (vector signed short, - vector unsigned short); -vector unsigned short vec_vrlh (vector unsigned short, - vector unsigned short); - -vector signed char vec_vrlb (vector signed char, vector unsigned char); -vector unsigned char vec_vrlb (vector unsigned char, - vector unsigned char); - -vector float vec_round (vector float); - -vector float vec_recip (vector float, vector float); - -vector float vec_rsqrt (vector float); - -vector float vec_rsqrte (vector float); - -vector float vec_sel (vector float, vector float, vector bool int); -vector float vec_sel (vector float, vector float, vector unsigned int); -vector signed int vec_sel (vector signed int, - vector signed int, - vector bool 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 bool int); -vector unsigned int vec_sel (vector unsigned int, - vector unsigned int, - vector unsigned int); -vector bool int vec_sel (vector bool int, - vector bool int, - vector bool int); -vector bool int vec_sel (vector bool int, - vector bool int, - vector unsigned int); -vector signed short vec_sel (vector signed short, - vector signed short, - vector bool 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 bool short); -vector unsigned short vec_sel (vector unsigned short, - vector unsigned short, - vector unsigned short); -vector bool short vec_sel (vector bool short, - vector bool short, - vector bool short); -vector bool short vec_sel (vector bool short, - vector bool short, - vector unsigned short); -vector signed char vec_sel (vector signed char, - vector signed char, - vector bool 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 bool char); -vector unsigned char vec_sel (vector unsigned char, - vector unsigned char, - vector unsigned char); -vector bool char vec_sel (vector bool char, - vector bool char, - vector bool char); -vector bool char vec_sel (vector bool char, - vector bool 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 signed int vec_vslw (vector signed int, vector unsigned int); -vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); - -vector signed short vec_vslh (vector signed short, - vector unsigned short); -vector unsigned short vec_vslh (vector unsigned short, - vector unsigned short); - -vector signed char vec_vslb (vector signed char, vector unsigned char); -vector unsigned char vec_vslb (vector unsigned char, - vector unsigned char); - -vector float vec_sld (vector float, vector float, const int); -vector signed int vec_sld (vector signed int, - vector signed int, - const int); -vector unsigned int vec_sld (vector unsigned int, - vector unsigned int, - const int); -vector bool int vec_sld (vector bool int, - vector bool int, - const int); -vector signed short vec_sld (vector signed short, - vector signed short, - const int); -vector unsigned short vec_sld (vector unsigned short, - vector unsigned short, - const int); -vector bool short vec_sld (vector bool short, - vector bool short, - const int); -vector pixel vec_sld (vector pixel, - vector pixel, - const int); -vector signed char vec_sld (vector signed char, - vector signed char, - const int); -vector unsigned char vec_sld (vector unsigned char, - vector unsigned char, - const int); -vector bool char vec_sld (vector bool char, - vector bool char, - const int); - -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 bool int vec_sll (vector bool int, - vector unsigned int); -vector bool int vec_sll (vector bool int, - vector unsigned short); -vector bool int vec_sll (vector bool 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 bool short vec_sll (vector bool short, vector unsigned int); -vector bool short vec_sll (vector bool short, vector unsigned short); -vector bool short vec_sll (vector bool short, vector unsigned char); -vector pixel vec_sll (vector pixel, vector unsigned int); -vector pixel vec_sll (vector pixel, vector unsigned short); -vector pixel vec_sll (vector pixel, 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 bool char vec_sll (vector bool char, vector unsigned int); -vector bool char vec_sll (vector bool char, vector unsigned short); -vector bool char vec_sll (vector bool 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 pixel vec_slo (vector pixel, vector signed char); -vector pixel vec_slo (vector pixel, 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 int); -vector unsigned char vec_splat (vector unsigned char, const int); -vector bool char vec_splat (vector bool char, const int); -vector signed short vec_splat (vector signed short, const int); -vector unsigned short vec_splat (vector unsigned short, const int); -vector bool short vec_splat (vector bool short, const int); -vector pixel vec_splat (vector pixel, const int); -vector float vec_splat (vector float, const int); -vector signed int vec_splat (vector signed int, const int); -vector unsigned int vec_splat (vector unsigned int, const int); -vector bool int vec_splat (vector bool int, const int); - -vector float vec_vspltw (vector float, const int); -vector signed int vec_vspltw (vector signed int, const int); -vector unsigned int vec_vspltw (vector unsigned int, const int); -vector bool int vec_vspltw (vector bool int, const int); - -vector bool short vec_vsplth (vector bool short, const int); -vector signed short vec_vsplth (vector signed short, const int); -vector unsigned short vec_vsplth (vector unsigned short, const int); -vector pixel vec_vsplth (vector pixel, const int); - -vector signed char vec_vspltb (vector signed char, const int); -vector unsigned char vec_vspltb (vector unsigned char, const int); -vector bool char vec_vspltb (vector bool char, const int); - -vector signed char vec_splat_s8 (const int); - -vector signed short vec_splat_s16 (const int); - -vector signed int vec_splat_s32 (const int); - -vector unsigned char vec_splat_u8 (const int); - -vector unsigned short vec_splat_u16 (const int); - -vector unsigned int vec_splat_u32 (const int); - -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 int vec_vsrw (vector signed int, vector unsigned int); -vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); - -vector signed short vec_vsrh (vector signed short, - vector unsigned short); -vector unsigned short vec_vsrh (vector unsigned short, - vector unsigned short); - -vector signed char vec_vsrb (vector signed char, vector unsigned char); -vector unsigned char vec_vsrb (vector unsigned char, - vector unsigned char); - -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_vsraw (vector signed int, vector unsigned int); -vector unsigned int vec_vsraw (vector unsigned int, - vector unsigned int); - -vector signed short vec_vsrah (vector signed short, - vector unsigned short); -vector unsigned short vec_vsrah (vector unsigned short, - vector unsigned short); - -vector signed char vec_vsrab (vector signed char, vector unsigned char); -vector unsigned char vec_vsrab (vector unsigned char, - vector unsigned char); - -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 bool int vec_srl (vector bool int, vector unsigned int); -vector bool int vec_srl (vector bool int, vector unsigned short); -vector bool int vec_srl (vector bool 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 bool short vec_srl (vector bool short, vector unsigned int); -vector bool short vec_srl (vector bool short, vector unsigned short); -vector bool short vec_srl (vector bool short, vector unsigned char); -vector pixel vec_srl (vector pixel, vector unsigned int); -vector pixel vec_srl (vector pixel, vector unsigned short); -vector pixel vec_srl (vector pixel, 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 bool char vec_srl (vector bool char, vector unsigned int); -vector bool char vec_srl (vector bool char, vector unsigned short); -vector bool char vec_srl (vector bool 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 pixel vec_sro (vector pixel, vector signed char); -vector pixel vec_sro (vector pixel, 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, vector float *); -void vec_st (vector float, int, float *); -void vec_st (vector signed int, int, vector signed int *); -void vec_st (vector signed int, int, int *); -void vec_st (vector unsigned int, int, vector unsigned int *); -void vec_st (vector unsigned int, int, unsigned int *); -void vec_st (vector bool int, int, vector bool int *); -void vec_st (vector bool int, int, unsigned int *); -void vec_st (vector bool int, int, int *); -void vec_st (vector signed short, int, vector signed short *); -void vec_st (vector signed short, int, short *); -void vec_st (vector unsigned short, int, vector unsigned short *); -void vec_st (vector unsigned short, int, unsigned short *); -void vec_st (vector bool short, int, vector bool short *); -void vec_st (vector bool short, int, unsigned short *); -void vec_st (vector pixel, int, vector pixel *); -void vec_st (vector pixel, int, unsigned short *); -void vec_st (vector pixel, int, short *); -void vec_st (vector bool short, int, short *); -void vec_st (vector signed char, int, vector signed char *); -void vec_st (vector signed char, int, signed char *); -void vec_st (vector unsigned char, int, vector unsigned char *); -void vec_st (vector unsigned char, int, unsigned char *); -void vec_st (vector bool char, int, vector bool char *); -void vec_st (vector bool char, int, unsigned char *); -void vec_st (vector bool char, int, signed char *); - -void vec_ste (vector signed char, int, signed char *); -void vec_ste (vector unsigned char, int, unsigned char *); -void vec_ste (vector bool char, int, signed char *); -void vec_ste (vector bool char, int, unsigned char *); -void vec_ste (vector signed short, int, short *); -void vec_ste (vector unsigned short, int, unsigned short *); -void vec_ste (vector bool short, int, short *); -void vec_ste (vector bool short, int, unsigned short *); -void vec_ste (vector pixel, int, short *); -void vec_ste (vector pixel, int, unsigned short *); -void vec_ste (vector float, int, float *); -void vec_ste (vector signed int, int, int *); -void vec_ste (vector unsigned int, int, unsigned int *); -void vec_ste (vector bool int, int, int *); -void vec_ste (vector bool int, int, unsigned int *); - -void vec_stvewx (vector float, int, float *); -void vec_stvewx (vector signed int, int, int *); -void vec_stvewx (vector unsigned int, int, unsigned int *); -void vec_stvewx (vector bool int, int, int *); -void vec_stvewx (vector bool int, int, unsigned int *); - -void vec_stvehx (vector signed short, int, short *); -void vec_stvehx (vector unsigned short, int, unsigned short *); -void vec_stvehx (vector bool short, int, short *); -void vec_stvehx (vector bool short, int, unsigned short *); -void vec_stvehx (vector pixel, int, short *); -void vec_stvehx (vector pixel, int, unsigned short *); - -void vec_stvebx (vector signed char, int, signed char *); -void vec_stvebx (vector unsigned char, int, unsigned char *); -void vec_stvebx (vector bool char, int, signed char *); -void vec_stvebx (vector bool char, int, unsigned char *); - -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 unsigned int, int, vector unsigned int *); -void vec_stl (vector unsigned int, int, unsigned int *); -void vec_stl (vector bool int, int, vector bool int *); -void vec_stl (vector bool int, int, unsigned int *); -void vec_stl (vector bool int, int, int *); -void vec_stl (vector signed short, int, vector signed short *); -void vec_stl (vector signed short, int, short *); -void vec_stl (vector unsigned short, int, vector unsigned short *); -void vec_stl (vector unsigned short, int, unsigned short *); -void vec_stl (vector bool short, int, vector bool short *); -void vec_stl (vector bool short, int, unsigned short *); -void vec_stl (vector bool short, int, short *); -void vec_stl (vector pixel, int, vector pixel *); -void vec_stl (vector pixel, int, unsigned short *); -void vec_stl (vector pixel, int, short *); -void vec_stl (vector signed char, int, vector signed char *); -void vec_stl (vector signed char, int, signed char *); -void vec_stl (vector unsigned char, int, vector unsigned char *); -void vec_stl (vector unsigned char, int, unsigned char *); -void vec_stl (vector bool char, int, vector bool char *); -void vec_stl (vector bool char, int, unsigned char *); -void vec_stl (vector bool char, int, signed char *); - -vector signed char vec_sub (vector bool char, vector signed char); -vector signed char vec_sub (vector signed char, vector bool char); -vector signed char vec_sub (vector signed char, vector signed char); -vector unsigned char vec_sub (vector bool char, vector unsigned char); -vector unsigned char vec_sub (vector unsigned char, vector bool char); -vector unsigned char vec_sub (vector unsigned char, - vector unsigned char); -vector signed short vec_sub (vector bool short, vector signed short); -vector signed short vec_sub (vector signed short, vector bool short); -vector signed short vec_sub (vector signed short, vector signed short); -vector unsigned short vec_sub (vector bool short, - vector unsigned short); -vector unsigned short vec_sub (vector unsigned short, - vector bool short); -vector unsigned short vec_sub (vector unsigned short, - vector unsigned short); -vector signed int vec_sub (vector bool int, vector signed int); -vector signed int vec_sub (vector signed int, vector bool int); -vector signed int vec_sub (vector signed int, vector signed int); -vector unsigned int vec_sub (vector bool int, vector unsigned int); -vector unsigned int vec_sub (vector unsigned int, vector bool int); -vector unsigned int vec_sub (vector unsigned int, vector unsigned int); -vector float vec_sub (vector float, vector float); - -vector float vec_vsubfp (vector float, vector float); - -vector signed int vec_vsubuwm (vector bool int, vector signed int); -vector signed int vec_vsubuwm (vector signed int, vector bool int); -vector signed int vec_vsubuwm (vector signed int, vector signed int); -vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); -vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); -vector unsigned int vec_vsubuwm (vector unsigned int, - vector unsigned int); - -vector signed short vec_vsubuhm (vector bool short, - vector signed short); -vector signed short vec_vsubuhm (vector signed short, - vector bool short); -vector signed short vec_vsubuhm (vector signed short, - vector signed short); -vector unsigned short vec_vsubuhm (vector bool short, - vector unsigned short); -vector unsigned short vec_vsubuhm (vector unsigned short, - vector bool short); -vector unsigned short vec_vsubuhm (vector unsigned short, - vector unsigned short); - -vector signed char vec_vsububm (vector bool char, vector signed char); -vector signed char vec_vsububm (vector signed char, vector bool char); -vector signed char vec_vsububm (vector signed char, vector signed char); -vector unsigned char vec_vsububm (vector bool char, - vector unsigned char); -vector unsigned char vec_vsububm (vector unsigned char, - vector bool char); -vector unsigned char vec_vsububm (vector unsigned char, - vector unsigned char); - -vector unsigned int vec_subc (vector unsigned int, vector unsigned int); - -vector unsigned char vec_subs (vector bool char, vector unsigned char); -vector unsigned char vec_subs (vector unsigned char, vector bool char); -vector unsigned char vec_subs (vector unsigned char, - vector unsigned char); -vector signed char vec_subs (vector bool char, vector signed char); -vector signed char vec_subs (vector signed char, vector bool char); -vector signed char vec_subs (vector signed char, vector signed char); -vector unsigned short vec_subs (vector bool short, - vector unsigned short); -vector unsigned short vec_subs (vector unsigned short, - vector bool short); -vector unsigned short vec_subs (vector unsigned short, - vector unsigned short); -vector signed short vec_subs (vector bool short, vector signed short); -vector signed short vec_subs (vector signed short, vector bool short); -vector signed short vec_subs (vector signed short, vector signed short); -vector unsigned int vec_subs (vector bool int, vector unsigned int); -vector unsigned int vec_subs (vector unsigned int, vector bool int); -vector unsigned int vec_subs (vector unsigned int, vector unsigned int); -vector signed int vec_subs (vector bool int, vector signed int); -vector signed int vec_subs (vector signed int, vector bool int); -vector signed int vec_subs (vector signed int, vector signed int); - -vector signed int vec_vsubsws (vector bool int, vector signed int); -vector signed int vec_vsubsws (vector signed int, vector bool int); -vector signed int vec_vsubsws (vector signed int, vector signed int); - -vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); -vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); -vector unsigned int vec_vsubuws (vector unsigned int, - vector unsigned int); - -vector signed short vec_vsubshs (vector bool short, - vector signed short); -vector signed short vec_vsubshs (vector signed short, - vector bool short); -vector signed short vec_vsubshs (vector signed short, - vector signed short); - -vector unsigned short vec_vsubuhs (vector bool short, - vector unsigned short); -vector unsigned short vec_vsubuhs (vector unsigned short, - vector bool short); -vector unsigned short vec_vsubuhs (vector unsigned short, - vector unsigned short); - -vector signed char vec_vsubsbs (vector bool char, vector signed char); -vector signed char vec_vsubsbs (vector signed char, vector bool char); -vector signed char vec_vsubsbs (vector signed char, vector signed char); - -vector unsigned char vec_vsububs (vector bool char, - vector unsigned char); -vector unsigned char vec_vsububs (vector unsigned char, - vector bool char); -vector unsigned char vec_vsububs (vector unsigned char, - vector unsigned char); - -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_vsum4shs (vector signed short, vector signed int); - -vector signed int vec_vsum4sbs (vector signed char, vector signed int); - -vector unsigned int vec_vsum4ubs (vector unsigned char, - vector unsigned 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 bool short vec_unpackh (vector bool char); -vector signed int vec_unpackh (vector signed short); -vector bool int vec_unpackh (vector bool short); -vector unsigned int vec_unpackh (vector pixel); - -vector bool int vec_vupkhsh (vector bool short); -vector signed int vec_vupkhsh (vector signed short); - -vector unsigned int vec_vupkhpx (vector pixel); - -vector bool short vec_vupkhsb (vector bool char); -vector signed short vec_vupkhsb (vector signed char); - -vector signed short vec_unpackl (vector signed char); -vector bool short vec_unpackl (vector bool char); -vector unsigned int vec_unpackl (vector pixel); -vector signed int vec_unpackl (vector signed short); -vector bool int vec_unpackl (vector bool short); - -vector unsigned int vec_vupklpx (vector pixel); - -vector bool int vec_vupklsh (vector bool short); -vector signed int vec_vupklsh (vector signed short); - -vector bool short vec_vupklsb (vector bool char); -vector signed short vec_vupklsb (vector signed char); - -vector float vec_xor (vector float, vector float); -vector float vec_xor (vector float, vector bool int); -vector float vec_xor (vector bool int, vector float); -vector bool int vec_xor (vector bool int, vector bool int); -vector signed int vec_xor (vector bool int, vector signed int); -vector signed int vec_xor (vector signed int, vector bool int); -vector signed int vec_xor (vector signed int, vector signed int); -vector unsigned int vec_xor (vector bool int, vector unsigned int); -vector unsigned int vec_xor (vector unsigned int, vector bool int); -vector unsigned int vec_xor (vector unsigned int, vector unsigned int); -vector bool short vec_xor (vector bool short, vector bool short); -vector signed short vec_xor (vector bool short, vector signed short); -vector signed short vec_xor (vector signed short, vector bool short); -vector signed short vec_xor (vector signed short, vector signed short); -vector unsigned short vec_xor (vector bool short, - vector unsigned short); -vector unsigned short vec_xor (vector unsigned short, - vector bool short); -vector unsigned short vec_xor (vector unsigned short, - vector unsigned short); -vector signed char vec_xor (vector bool char, vector signed char); -vector bool char vec_xor (vector bool char, vector bool char); -vector signed char vec_xor (vector signed char, vector bool char); -vector signed char vec_xor (vector signed char, vector signed char); -vector unsigned char vec_xor (vector bool char, vector unsigned char); -vector unsigned char vec_xor (vector unsigned char, vector bool char); -vector unsigned char vec_xor (vector unsigned char, - vector unsigned char); - -int vec_all_eq (vector signed char, vector bool char); -int vec_all_eq (vector signed char, vector signed char); -int vec_all_eq (vector unsigned char, vector bool char); -int vec_all_eq (vector unsigned char, vector unsigned char); -int vec_all_eq (vector bool char, vector bool char); -int vec_all_eq (vector bool char, vector unsigned char); -int vec_all_eq (vector bool char, vector signed char); -int vec_all_eq (vector signed short, vector bool short); -int vec_all_eq (vector signed short, vector signed short); -int vec_all_eq (vector unsigned short, vector bool short); -int vec_all_eq (vector unsigned short, vector unsigned short); -int vec_all_eq (vector bool short, vector bool short); -int vec_all_eq (vector bool short, vector unsigned short); -int vec_all_eq (vector bool short, vector signed short); -int vec_all_eq (vector pixel, vector pixel); -int vec_all_eq (vector signed int, vector bool int); -int vec_all_eq (vector signed int, vector signed int); -int vec_all_eq (vector unsigned int, vector bool int); -int vec_all_eq (vector unsigned int, vector unsigned int); -int vec_all_eq (vector bool int, vector bool int); -int vec_all_eq (vector bool int, vector unsigned int); -int vec_all_eq (vector bool int, vector signed int); -int vec_all_eq (vector float, vector float); - -int vec_all_ge (vector bool char, vector unsigned char); -int vec_all_ge (vector unsigned char, vector bool char); -int vec_all_ge (vector unsigned char, vector unsigned char); -int vec_all_ge (vector bool char, vector signed char); -int vec_all_ge (vector signed char, vector bool char); -int vec_all_ge (vector signed char, vector signed char); -int vec_all_ge (vector bool short, vector unsigned short); -int vec_all_ge (vector unsigned short, vector bool short); -int vec_all_ge (vector unsigned short, vector unsigned short); -int vec_all_ge (vector signed short, vector signed short); -int vec_all_ge (vector bool short, vector signed short); -int vec_all_ge (vector signed short, vector bool short); -int vec_all_ge (vector bool int, vector unsigned int); -int vec_all_ge (vector unsigned int, vector bool int); -int vec_all_ge (vector unsigned int, vector unsigned int); -int vec_all_ge (vector bool int, vector signed int); -int vec_all_ge (vector signed int, vector bool int); -int vec_all_ge (vector signed int, vector signed int); -int vec_all_ge (vector float, vector float); - -int vec_all_gt (vector bool char, vector unsigned char); -int vec_all_gt (vector unsigned char, vector bool char); -int vec_all_gt (vector unsigned char, vector unsigned char); -int vec_all_gt (vector bool char, vector signed char); -int vec_all_gt (vector signed char, vector bool char); -int vec_all_gt (vector signed char, vector signed char); -int vec_all_gt (vector bool short, vector unsigned short); -int vec_all_gt (vector unsigned short, vector bool short); -int vec_all_gt (vector unsigned short, vector unsigned short); -int vec_all_gt (vector bool short, vector signed short); -int vec_all_gt (vector signed short, vector bool short); -int vec_all_gt (vector signed short, vector signed short); -int vec_all_gt (vector bool int, vector unsigned int); -int vec_all_gt (vector unsigned int, vector bool int); -int vec_all_gt (vector unsigned int, vector unsigned int); -int vec_all_gt (vector bool int, vector signed int); -int vec_all_gt (vector signed int, vector bool int); -int vec_all_gt (vector signed int, vector signed int); -int vec_all_gt (vector float, vector float); - -int vec_all_in (vector float, vector float); - -int vec_all_le (vector bool char, vector unsigned char); -int vec_all_le (vector unsigned char, vector bool char); -int vec_all_le (vector unsigned char, vector unsigned char); -int vec_all_le (vector bool char, vector signed char); -int vec_all_le (vector signed char, vector bool char); -int vec_all_le (vector signed char, vector signed char); -int vec_all_le (vector bool short, vector unsigned short); -int vec_all_le (vector unsigned short, vector bool short); -int vec_all_le (vector unsigned short, vector unsigned short); -int vec_all_le (vector bool short, vector signed short); -int vec_all_le (vector signed short, vector bool short); -int vec_all_le (vector signed short, vector signed short); -int vec_all_le (vector bool int, vector unsigned int); -int vec_all_le (vector unsigned int, vector bool int); -int vec_all_le (vector unsigned int, vector unsigned int); -int vec_all_le (vector bool int, vector signed int); -int vec_all_le (vector signed int, vector bool int); -int vec_all_le (vector signed int, vector signed int); -int vec_all_le (vector float, vector float); - -int vec_all_lt (vector bool char, vector unsigned char); -int vec_all_lt (vector unsigned char, vector bool char); -int vec_all_lt (vector unsigned char, vector unsigned char); -int vec_all_lt (vector bool char, vector signed char); -int vec_all_lt (vector signed char, vector bool char); -int vec_all_lt (vector signed char, vector signed char); -int vec_all_lt (vector bool short, vector unsigned short); -int vec_all_lt (vector unsigned short, vector bool short); -int vec_all_lt (vector unsigned short, vector unsigned short); -int vec_all_lt (vector bool short, vector signed short); -int vec_all_lt (vector signed short, vector bool short); -int vec_all_lt (vector signed short, vector signed short); -int vec_all_lt (vector bool int, vector unsigned int); -int vec_all_lt (vector unsigned int, vector bool int); -int vec_all_lt (vector unsigned int, vector unsigned int); -int vec_all_lt (vector bool int, vector signed int); -int vec_all_lt (vector signed int, vector bool int); -int vec_all_lt (vector signed int, vector signed int); -int vec_all_lt (vector float, vector float); - -int vec_all_nan (vector float); - -int vec_all_ne (vector signed char, vector bool char); -int vec_all_ne (vector signed char, vector signed char); -int vec_all_ne (vector unsigned char, vector bool char); -int vec_all_ne (vector unsigned char, vector unsigned char); -int vec_all_ne (vector bool char, vector bool char); -int vec_all_ne (vector bool char, vector unsigned char); -int vec_all_ne (vector bool char, vector signed char); -int vec_all_ne (vector signed short, vector bool short); -int vec_all_ne (vector signed short, vector signed short); -int vec_all_ne (vector unsigned short, vector bool short); -int vec_all_ne (vector unsigned short, vector unsigned short); -int vec_all_ne (vector bool short, vector bool short); -int vec_all_ne (vector bool short, vector unsigned short); -int vec_all_ne (vector bool short, vector signed short); -int vec_all_ne (vector pixel, vector pixel); -int vec_all_ne (vector signed int, vector bool int); -int vec_all_ne (vector signed int, vector signed int); -int vec_all_ne (vector unsigned int, vector bool int); -int vec_all_ne (vector unsigned int, vector unsigned int); -int vec_all_ne (vector bool int, vector bool int); -int vec_all_ne (vector bool int, vector unsigned int); -int vec_all_ne (vector bool int, vector signed int); -int vec_all_ne (vector float, vector float); - -int vec_all_nge (vector float, vector float); - -int vec_all_ngt (vector float, vector float); - -int vec_all_nle (vector float, vector float); - -int vec_all_nlt (vector float, vector float); - -int vec_all_numeric (vector float); - -int vec_any_eq (vector signed char, vector bool char); -int vec_any_eq (vector signed char, vector signed char); -int vec_any_eq (vector unsigned char, vector bool char); -int vec_any_eq (vector unsigned char, vector unsigned char); -int vec_any_eq (vector bool char, vector bool char); -int vec_any_eq (vector bool char, vector unsigned char); -int vec_any_eq (vector bool char, vector signed char); -int vec_any_eq (vector signed short, vector bool short); -int vec_any_eq (vector signed short, vector signed short); -int vec_any_eq (vector unsigned short, vector bool short); -int vec_any_eq (vector unsigned short, vector unsigned short); -int vec_any_eq (vector bool short, vector bool short); -int vec_any_eq (vector bool short, vector unsigned short); -int vec_any_eq (vector bool short, vector signed short); -int vec_any_eq (vector pixel, vector pixel); -int vec_any_eq (vector signed int, vector bool int); -int vec_any_eq (vector signed int, vector signed int); -int vec_any_eq (vector unsigned int, vector bool int); -int vec_any_eq (vector unsigned int, vector unsigned int); -int vec_any_eq (vector bool int, vector bool int); -int vec_any_eq (vector bool int, vector unsigned int); -int vec_any_eq (vector bool int, vector signed int); -int vec_any_eq (vector float, vector float); - -int vec_any_ge (vector signed char, vector bool char); -int vec_any_ge (vector unsigned char, vector bool char); -int vec_any_ge (vector unsigned char, vector unsigned char); -int vec_any_ge (vector signed char, vector signed char); -int vec_any_ge (vector bool char, vector unsigned char); -int vec_any_ge (vector bool char, vector signed char); -int vec_any_ge (vector unsigned short, vector bool short); -int vec_any_ge (vector unsigned short, vector unsigned short); -int vec_any_ge (vector signed short, vector signed short); -int vec_any_ge (vector signed short, vector bool short); -int vec_any_ge (vector bool short, vector unsigned short); -int vec_any_ge (vector bool short, vector signed short); -int vec_any_ge (vector signed int, vector bool int); -int vec_any_ge (vector unsigned int, vector bool int); -int vec_any_ge (vector unsigned int, vector unsigned int); -int vec_any_ge (vector signed int, vector signed int); -int vec_any_ge (vector bool int, vector unsigned int); -int vec_any_ge (vector bool int, vector signed int); -int vec_any_ge (vector float, vector float); - -int vec_any_gt (vector bool char, vector unsigned char); -int vec_any_gt (vector unsigned char, vector bool char); -int vec_any_gt (vector unsigned char, vector unsigned char); -int vec_any_gt (vector bool char, vector signed char); -int vec_any_gt (vector signed char, vector bool char); -int vec_any_gt (vector signed char, vector signed char); -int vec_any_gt (vector bool short, vector unsigned short); -int vec_any_gt (vector unsigned short, vector bool short); -int vec_any_gt (vector unsigned short, vector unsigned short); -int vec_any_gt (vector bool short, vector signed short); -int vec_any_gt (vector signed short, vector bool short); -int vec_any_gt (vector signed short, vector signed short); -int vec_any_gt (vector bool int, vector unsigned int); -int vec_any_gt (vector unsigned int, vector bool int); -int vec_any_gt (vector unsigned int, vector unsigned int); -int vec_any_gt (vector bool int, vector signed int); -int vec_any_gt (vector signed int, vector bool int); -int vec_any_gt (vector signed int, vector signed int); -int vec_any_gt (vector float, vector float); - -int vec_any_le (vector bool char, vector unsigned char); -int vec_any_le (vector unsigned char, vector bool char); -int vec_any_le (vector unsigned char, vector unsigned char); -int vec_any_le (vector bool char, vector signed char); -int vec_any_le (vector signed char, vector bool char); -int vec_any_le (vector signed char, vector signed char); -int vec_any_le (vector bool short, vector unsigned short); -int vec_any_le (vector unsigned short, vector bool short); -int vec_any_le (vector unsigned short, vector unsigned short); -int vec_any_le (vector bool short, vector signed short); -int vec_any_le (vector signed short, vector bool short); -int vec_any_le (vector signed short, vector signed short); -int vec_any_le (vector bool int, vector unsigned int); -int vec_any_le (vector unsigned int, vector bool int); -int vec_any_le (vector unsigned int, vector unsigned int); -int vec_any_le (vector bool int, vector signed int); -int vec_any_le (vector signed int, vector bool int); -int vec_any_le (vector signed int, vector signed int); -int vec_any_le (vector float, vector float); - -int vec_any_lt (vector bool char, vector unsigned char); -int vec_any_lt (vector unsigned char, vector bool char); -int vec_any_lt (vector unsigned char, vector unsigned char); -int vec_any_lt (vector bool char, vector signed char); -int vec_any_lt (vector signed char, vector bool char); -int vec_any_lt (vector signed char, vector signed char); -int vec_any_lt (vector bool short, vector unsigned short); -int vec_any_lt (vector unsigned short, vector bool short); -int vec_any_lt (vector unsigned short, vector unsigned short); -int vec_any_lt (vector bool short, vector signed short); -int vec_any_lt (vector signed short, vector bool short); -int vec_any_lt (vector signed short, vector signed short); -int vec_any_lt (vector bool int, vector unsigned int); -int vec_any_lt (vector unsigned int, vector bool int); -int vec_any_lt (vector unsigned int, vector unsigned int); -int vec_any_lt (vector bool int, vector signed int); -int vec_any_lt (vector signed int, vector bool int); -int vec_any_lt (vector signed int, vector signed int); -int vec_any_lt (vector float, vector float); - -int vec_any_nan (vector float); - -int vec_any_ne (vector signed char, vector bool char); -int vec_any_ne (vector signed char, vector signed char); -int vec_any_ne (vector unsigned char, vector bool char); -int vec_any_ne (vector unsigned char, vector unsigned char); -int vec_any_ne (vector bool char, vector bool char); -int vec_any_ne (vector bool char, vector unsigned char); -int vec_any_ne (vector bool char, vector signed char); -int vec_any_ne (vector signed short, vector bool short); -int vec_any_ne (vector signed short, vector signed short); -int vec_any_ne (vector unsigned short, vector bool short); -int vec_any_ne (vector unsigned short, vector unsigned short); -int vec_any_ne (vector bool short, vector bool short); -int vec_any_ne (vector bool short, vector unsigned short); -int vec_any_ne (vector bool short, vector signed short); -int vec_any_ne (vector pixel, vector pixel); -int vec_any_ne (vector signed int, vector bool int); -int vec_any_ne (vector signed int, vector signed int); -int vec_any_ne (vector unsigned int, vector bool int); -int vec_any_ne (vector unsigned int, vector unsigned int); -int vec_any_ne (vector bool int, vector bool int); -int vec_any_ne (vector bool int, vector unsigned int); -int vec_any_ne (vector bool int, vector signed int); -int vec_any_ne (vector float, vector float); - -int vec_any_nge (vector float, vector float); - -int vec_any_ngt (vector float, vector float); - -int vec_any_nle (vector float, vector float); - -int vec_any_nlt (vector float, vector float); - -int vec_any_numeric (vector float); - -int vec_any_out (vector float, vector float); -@end smallexample - -If the vector/scalar (VSX) instruction set is available, the following -additional functions are available: - -@smallexample -vector double vec_abs (vector double); -vector double vec_add (vector double, vector double); -vector double vec_and (vector double, vector double); -vector double vec_and (vector double, vector bool long); -vector double vec_and (vector bool long, vector double); -vector double vec_andc (vector double, vector double); -vector double vec_andc (vector double, vector bool long); -vector double vec_andc (vector bool long, vector double); -vector double vec_ceil (vector double); -vector bool long vec_cmpeq (vector double, vector double); -vector bool long vec_cmpge (vector double, vector double); -vector bool long vec_cmpgt (vector double, vector double); -vector bool long vec_cmple (vector double, vector double); -vector bool long vec_cmplt (vector double, vector double); -vector float vec_div (vector float, vector float); -vector double vec_div (vector double, vector double); -vector double vec_floor (vector double); -vector double vec_ld (int, const vector double *); -vector double vec_ld (int, const double *); -vector double vec_ldl (int, const vector double *); -vector double vec_ldl (int, const double *); -vector unsigned char vec_lvsl (int, const volatile double *); -vector unsigned char vec_lvsr (int, const volatile double *); -vector double vec_madd (vector double, vector double, vector double); -vector double vec_max (vector double, vector double); -vector double vec_min (vector double, vector double); -vector float vec_msub (vector float, vector float, vector float); -vector double vec_msub (vector double, vector double, vector double); -vector float vec_mul (vector float, vector float); -vector double vec_mul (vector double, vector double); -vector float vec_nearbyint (vector float); -vector double vec_nearbyint (vector double); -vector float vec_nmadd (vector float, vector float, vector float); -vector double vec_nmadd (vector double, vector double, vector double); -vector double vec_nmsub (vector double, vector double, vector double); -vector double vec_nor (vector double, vector double); -vector double vec_or (vector double, vector double); -vector double vec_or (vector double, vector bool long); -vector double vec_or (vector bool long, vector double); -vector double vec_perm (vector double, - vector double, - vector unsigned char); -vector double vec_rint (vector double); -vector double vec_recip (vector double, vector double); -vector double vec_rsqrt (vector double); -vector double vec_rsqrte (vector double); -vector double vec_sel (vector double, vector double, vector bool long); -vector double vec_sel (vector double, vector double, vector unsigned long); -vector double vec_sub (vector double, vector double); -vector float vec_sqrt (vector float); -vector double vec_sqrt (vector double); -void vec_st (vector double, int, vector double *); -void vec_st (vector double, int, double *); -vector double vec_trunc (vector double); -vector double vec_xor (vector double, vector double); -vector double vec_xor (vector double, vector bool long); -vector double vec_xor (vector bool long, vector double); -int vec_all_eq (vector double, vector double); -int vec_all_ge (vector double, vector double); -int vec_all_gt (vector double, vector double); -int vec_all_le (vector double, vector double); -int vec_all_lt (vector double, vector double); -int vec_all_nan (vector double); -int vec_all_ne (vector double, vector double); -int vec_all_nge (vector double, vector double); -int vec_all_ngt (vector double, vector double); -int vec_all_nle (vector double, vector double); -int vec_all_nlt (vector double, vector double); -int vec_all_numeric (vector double); -int vec_any_eq (vector double, vector double); -int vec_any_ge (vector double, vector double); -int vec_any_gt (vector double, vector double); -int vec_any_le (vector double, vector double); -int vec_any_lt (vector double, vector double); -int vec_any_nan (vector double); -int vec_any_ne (vector double, vector double); -int vec_any_nge (vector double, vector double); -int vec_any_ngt (vector double, vector double); -int vec_any_nle (vector double, vector double); -int vec_any_nlt (vector double, vector double); -int vec_any_numeric (vector double); - -vector double vec_vsx_ld (int, const vector double *); -vector double vec_vsx_ld (int, const double *); -vector float vec_vsx_ld (int, const vector float *); -vector float vec_vsx_ld (int, const float *); -vector bool int vec_vsx_ld (int, const vector bool int *); -vector signed int vec_vsx_ld (int, const vector signed int *); -vector signed int vec_vsx_ld (int, const int *); -vector signed int vec_vsx_ld (int, const long *); -vector unsigned int vec_vsx_ld (int, const vector unsigned int *); -vector unsigned int vec_vsx_ld (int, const unsigned int *); -vector unsigned int vec_vsx_ld (int, const unsigned long *); -vector bool short vec_vsx_ld (int, const vector bool short *); -vector pixel vec_vsx_ld (int, const vector pixel *); -vector signed short vec_vsx_ld (int, const vector signed short *); -vector signed short vec_vsx_ld (int, const short *); -vector unsigned short vec_vsx_ld (int, const vector unsigned short *); -vector unsigned short vec_vsx_ld (int, const unsigned short *); -vector bool char vec_vsx_ld (int, const vector bool char *); -vector signed char vec_vsx_ld (int, const vector signed char *); -vector signed char vec_vsx_ld (int, const signed char *); -vector unsigned char vec_vsx_ld (int, const vector unsigned char *); -vector unsigned char vec_vsx_ld (int, const unsigned char *); - -void vec_vsx_st (vector double, int, vector double *); -void vec_vsx_st (vector double, int, double *); -void vec_vsx_st (vector float, int, vector float *); -void vec_vsx_st (vector float, int, float *); -void vec_vsx_st (vector signed int, int, vector signed int *); -void vec_vsx_st (vector signed int, int, int *); -void vec_vsx_st (vector unsigned int, int, vector unsigned int *); -void vec_vsx_st (vector unsigned int, int, unsigned int *); -void vec_vsx_st (vector bool int, int, vector bool int *); -void vec_vsx_st (vector bool int, int, unsigned int *); -void vec_vsx_st (vector bool int, int, int *); -void vec_vsx_st (vector signed short, int, vector signed short *); -void vec_vsx_st (vector signed short, int, short *); -void vec_vsx_st (vector unsigned short, int, vector unsigned short *); -void vec_vsx_st (vector unsigned short, int, unsigned short *); -void vec_vsx_st (vector bool short, int, vector bool short *); -void vec_vsx_st (vector bool short, int, unsigned short *); -void vec_vsx_st (vector pixel, int, vector pixel *); -void vec_vsx_st (vector pixel, int, unsigned short *); -void vec_vsx_st (vector pixel, int, short *); -void vec_vsx_st (vector bool short, int, short *); -void vec_vsx_st (vector signed char, int, vector signed char *); -void vec_vsx_st (vector signed char, int, signed char *); -void vec_vsx_st (vector unsigned char, int, vector unsigned char *); -void vec_vsx_st (vector unsigned char, int, unsigned char *); -void vec_vsx_st (vector bool char, int, vector bool char *); -void vec_vsx_st (vector bool char, int, unsigned char *); -void vec_vsx_st (vector bool char, int, signed char *); -@end smallexample - -Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always -generate the AltiVec @samp{LVX} and @samp{STVX} instructions even -if the VSX instruction set is available. The @samp{vec_vsx_ld} and -@samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X}, -@samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions. - -@node RX Built-in Functions -@subsection RX Built-in Functions -GCC supports some of the RX instructions which cannot be expressed in -the C programming language via the use of built-in functions. The -following functions are supported: - -@deftypefn {Built-in Function} void __builtin_rx_brk (void) -Generates the @code{brk} machine instruction. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_clrpsw (int) -Generates the @code{clrpsw} machine instruction to clear the specified -bit in the processor status word. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_int (int) -Generates the @code{int} machine instruction to generate an interrupt -with the specified value. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_machi (int, int) -Generates the @code{machi} machine instruction to add the result of -multiplying the top 16 bits of the two arguments into the -accumulator. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_maclo (int, int) -Generates the @code{maclo} machine instruction to add the result of -multiplying the bottom 16 bits of the two arguments into the -accumulator. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int) -Generates the @code{mulhi} machine instruction to place the result of -multiplying the top 16 bits of the two arguments into the -accumulator. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_mullo (int, int) -Generates the @code{mullo} machine instruction to place the result of -multiplying the bottom 16 bits of the two arguments into the -accumulator. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_rx_mvfachi (void) -Generates the @code{mvfachi} machine instruction to read the top -32 bits of the accumulator. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void) -Generates the @code{mvfacmi} machine instruction to read the middle -32 bits of the accumulator. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_rx_mvfc (int) -Generates the @code{mvfc} machine instruction which reads the control -register specified in its argument and returns its value. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_mvtachi (int) -Generates the @code{mvtachi} machine instruction to set the top -32 bits of the accumulator. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int) -Generates the @code{mvtaclo} machine instruction to set the bottom -32 bits of the accumulator. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val) -Generates the @code{mvtc} machine instruction which sets control -register number @code{reg} to @code{val}. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_mvtipl (int) -Generates the @code{mvtipl} machine instruction set the interrupt -priority level. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_racw (int) -Generates the @code{racw} machine instruction to round the accumulator -according to the specified mode. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_rx_revw (int) -Generates the @code{revw} machine instruction which swaps the bytes in -the argument so that bits 0--7 now occupy bits 8--15 and vice versa, -and also bits 16--23 occupy bits 24--31 and vice versa. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_rmpa (void) -Generates the @code{rmpa} machine instruction which initiates a -repeated multiply and accumulate sequence. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_round (float) -Generates the @code{round} machine instruction which returns the -floating-point argument rounded according to the current rounding mode -set in the floating-point status word register. -@end deftypefn - -@deftypefn {Built-in Function} int __builtin_rx_sat (int) -Generates the @code{sat} machine instruction which returns the -saturated value of the argument. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_setpsw (int) -Generates the @code{setpsw} machine instruction to set the specified -bit in the processor status word. -@end deftypefn - -@deftypefn {Built-in Function} void __builtin_rx_wait (void) -Generates the @code{wait} machine instruction. -@end deftypefn - -@node SH Built-in Functions -@subsection SH Built-in Functions -The following built-in functions are supported on the SH1, SH2, SH3 and SH4 -families of processors: - -@deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr}) -Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually -used by system code that manages threads and execution contexts. The compiler -normally does not generate code that modifies the contents of @samp{GBR} and -thus the value is preserved across function calls. Changing the @samp{GBR} -value in user code must be done with caution, since the compiler might use -@samp{GBR} in order to access thread local variables. - -@end deftypefn - -@deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void) -Returns the value that is currently set in the @samp{GBR} register. -Memory loads and stores that use the thread pointer as a base address are -turned into @samp{GBR} based displacement loads and stores, if possible. -For example: -@smallexample -struct my_tcb -@{ - int a, b, c, d, e; -@}; - -int get_tcb_value (void) -@{ - // Generate @samp{mov.l @@(8,gbr),r0} instruction - return ((my_tcb*)__builtin_thread_pointer ())->c; -@} - -@end smallexample -@end deftypefn - -@node SPARC VIS Built-in Functions -@subsection SPARC VIS Built-in Functions - -GCC supports SIMD operations on the SPARC using both the generic vector -extensions (@pxref{Vector Extensions}) as well as built-in functions for -the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} -switch, the VIS extension is exposed as the following built-in functions: - -@smallexample -typedef int v1si __attribute__ ((vector_size (4))); -typedef int v2si __attribute__ ((vector_size (8))); -typedef short v4hi __attribute__ ((vector_size (8))); -typedef short v2hi __attribute__ ((vector_size (4))); -typedef unsigned char v8qi __attribute__ ((vector_size (8))); -typedef unsigned char v4qi __attribute__ ((vector_size (4))); - -void __builtin_vis_write_gsr (int64_t); -int64_t __builtin_vis_read_gsr (void); - -void * __builtin_vis_alignaddr (void *, long); -void * __builtin_vis_alignaddrl (void *, long); -int64_t __builtin_vis_faligndatadi (int64_t, int64_t); -v2si __builtin_vis_faligndatav2si (v2si, v2si); -v4hi __builtin_vis_faligndatav4hi (v4si, v4si); -v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); - -v4hi __builtin_vis_fexpand (v4qi); - -v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); -v4hi __builtin_vis_fmul8x16au (v4qi, v2hi); -v4hi __builtin_vis_fmul8x16al (v4qi, v2hi); -v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); -v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); -v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); -v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); - -v4qi __builtin_vis_fpack16 (v4hi); -v8qi __builtin_vis_fpack32 (v2si, v8qi); -v2hi __builtin_vis_fpackfix (v2si); -v8qi __builtin_vis_fpmerge (v4qi, v4qi); - -int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); - -long __builtin_vis_edge8 (void *, void *); -long __builtin_vis_edge8l (void *, void *); -long __builtin_vis_edge16 (void *, void *); -long __builtin_vis_edge16l (void *, void *); -long __builtin_vis_edge32 (void *, void *); -long __builtin_vis_edge32l (void *, void *); - -long __builtin_vis_fcmple16 (v4hi, v4hi); -long __builtin_vis_fcmple32 (v2si, v2si); -long __builtin_vis_fcmpne16 (v4hi, v4hi); -long __builtin_vis_fcmpne32 (v2si, v2si); -long __builtin_vis_fcmpgt16 (v4hi, v4hi); -long __builtin_vis_fcmpgt32 (v2si, v2si); -long __builtin_vis_fcmpeq16 (v4hi, v4hi); -long __builtin_vis_fcmpeq32 (v2si, v2si); - -v4hi __builtin_vis_fpadd16 (v4hi, v4hi); -v2hi __builtin_vis_fpadd16s (v2hi, v2hi); -v2si __builtin_vis_fpadd32 (v2si, v2si); -v1si __builtin_vis_fpadd32s (v1si, v1si); -v4hi __builtin_vis_fpsub16 (v4hi, v4hi); -v2hi __builtin_vis_fpsub16s (v2hi, v2hi); -v2si __builtin_vis_fpsub32 (v2si, v2si); -v1si __builtin_vis_fpsub32s (v1si, v1si); - -long __builtin_vis_array8 (long, long); -long __builtin_vis_array16 (long, long); -long __builtin_vis_array32 (long, long); -@end smallexample - -When you use the @option{-mvis2} switch, the VIS version 2.0 built-in -functions also become available: - -@smallexample -long __builtin_vis_bmask (long, long); -int64_t __builtin_vis_bshuffledi (int64_t, int64_t); -v2si __builtin_vis_bshufflev2si (v2si, v2si); -v4hi __builtin_vis_bshufflev2si (v4hi, v4hi); -v8qi __builtin_vis_bshufflev2si (v8qi, v8qi); - -long __builtin_vis_edge8n (void *, void *); -long __builtin_vis_edge8ln (void *, void *); -long __builtin_vis_edge16n (void *, void *); -long __builtin_vis_edge16ln (void *, void *); -long __builtin_vis_edge32n (void *, void *); -long __builtin_vis_edge32ln (void *, void *); -@end smallexample - -When you use the @option{-mvis3} switch, the VIS version 3.0 built-in -functions also become available: - -@smallexample -void __builtin_vis_cmask8 (long); -void __builtin_vis_cmask16 (long); -void __builtin_vis_cmask32 (long); - -v4hi __builtin_vis_fchksm16 (v4hi, v4hi); - -v4hi __builtin_vis_fsll16 (v4hi, v4hi); -v4hi __builtin_vis_fslas16 (v4hi, v4hi); -v4hi __builtin_vis_fsrl16 (v4hi, v4hi); -v4hi __builtin_vis_fsra16 (v4hi, v4hi); -v2si __builtin_vis_fsll16 (v2si, v2si); -v2si __builtin_vis_fslas16 (v2si, v2si); -v2si __builtin_vis_fsrl16 (v2si, v2si); -v2si __builtin_vis_fsra16 (v2si, v2si); - -long __builtin_vis_pdistn (v8qi, v8qi); - -v4hi __builtin_vis_fmean16 (v4hi, v4hi); - -int64_t __builtin_vis_fpadd64 (int64_t, int64_t); -int64_t __builtin_vis_fpsub64 (int64_t, int64_t); - -v4hi __builtin_vis_fpadds16 (v4hi, v4hi); -v2hi __builtin_vis_fpadds16s (v2hi, v2hi); -v4hi __builtin_vis_fpsubs16 (v4hi, v4hi); -v2hi __builtin_vis_fpsubs16s (v2hi, v2hi); -v2si __builtin_vis_fpadds32 (v2si, v2si); -v1si __builtin_vis_fpadds32s (v1si, v1si); -v2si __builtin_vis_fpsubs32 (v2si, v2si); -v1si __builtin_vis_fpsubs32s (v1si, v1si); - -long __builtin_vis_fucmple8 (v8qi, v8qi); -long __builtin_vis_fucmpne8 (v8qi, v8qi); -long __builtin_vis_fucmpgt8 (v8qi, v8qi); -long __builtin_vis_fucmpeq8 (v8qi, v8qi); - -float __builtin_vis_fhadds (float, float); -double __builtin_vis_fhaddd (double, double); -float __builtin_vis_fhsubs (float, float); -double __builtin_vis_fhsubd (double, double); -float __builtin_vis_fnhadds (float, float); -double __builtin_vis_fnhaddd (double, double); - -int64_t __builtin_vis_umulxhi (int64_t, int64_t); -int64_t __builtin_vis_xmulx (int64_t, int64_t); -int64_t __builtin_vis_xmulxhi (int64_t, int64_t); -@end smallexample - -@node SPU Built-in Functions -@subsection SPU Built-in Functions - -GCC provides extensions for the SPU processor as described in the -Sony/Toshiba/IBM SPU Language Extensions Specification, which can be -found at @uref{http://cell.scei.co.jp/} or -@uref{http://www.ibm.com/developerworks/power/cell/}. GCC's -implementation differs in several ways. - -@itemize @bullet - -@item -The optional extension of specifying vector constants in parentheses is -not supported. - -@item -A vector initializer requires no cast if the vector constant is of the -same type as the variable it is initializing. - -@item -If @code{signed} or @code{unsigned} is omitted, the signedness of the -vector type is the default signedness of the base type. The default -varies depending on the operating system, so a portable program should -always specify the signedness. - -@item -By default, the keyword @code{__vector} is added. The macro -@code{vector} is defined in @code{<spu_intrinsics.h>} and can be -undefined. - -@item -GCC allows using a @code{typedef} name as the type specifier for a -vector type. - -@item -For C, overloaded functions are implemented with macros so the following -does not work: - -@smallexample - spu_add ((vector signed int)@{1, 2, 3, 4@}, foo); -@end smallexample - -@noindent -Since @code{spu_add} is a macro, the vector constant in the example -is treated as four separate arguments. Wrap the entire argument in -parentheses for this to work. - -@item -The extended version of @code{__builtin_expect} is not supported. - -@end itemize - -@emph{Note:} Only the interface described in the aforementioned -specification is supported. Internally, GCC uses built-in functions to -implement the required functionality, but these are not supported and -are subject to change without notice. - -@node TI C6X Built-in Functions -@subsection TI C6X Built-in Functions - -GCC provides intrinsics to access certain instructions of the TI C6X -processors. These intrinsics, listed below, are available after -inclusion of the @code{c6x_intrinsics.h} header file. They map directly -to C6X instructions. - -@smallexample - -int _sadd (int, int) -int _ssub (int, int) -int _sadd2 (int, int) -int _ssub2 (int, int) -long long _mpy2 (int, int) -long long _smpy2 (int, int) -int _add4 (int, int) -int _sub4 (int, int) -int _saddu4 (int, int) - -int _smpy (int, int) -int _smpyh (int, int) -int _smpyhl (int, int) -int _smpylh (int, int) - -int _sshl (int, int) -int _subc (int, int) - -int _avg2 (int, int) -int _avgu4 (int, int) - -int _clrr (int, int) -int _extr (int, int) -int _extru (int, int) -int _abs (int) -int _abs2 (int) - -@end smallexample - -@node TILE-Gx Built-in Functions -@subsection TILE-Gx Built-in Functions - -GCC provides intrinsics to access every instruction of the TILE-Gx -processor. The intrinsics are of the form: - -@smallexample - -unsigned long long __insn_@var{op} (...) - -@end smallexample - -Where @var{op} is the name of the instruction. Refer to the ISA manual -for the complete list of instructions. - -GCC also provides intrinsics to directly access the network registers. -The intrinsics are: - -@smallexample - -unsigned long long __tile_idn0_receive (void) -unsigned long long __tile_idn1_receive (void) -unsigned long long __tile_udn0_receive (void) -unsigned long long __tile_udn1_receive (void) -unsigned long long __tile_udn2_receive (void) -unsigned long long __tile_udn3_receive (void) -void __tile_idn_send (unsigned long long) -void __tile_udn_send (unsigned long long) - -@end smallexample - -The intrinsic @code{void __tile_network_barrier (void)} is used to -guarantee that no network operations before it are reordered with -those after it. - -@node TILEPro Built-in Functions -@subsection TILEPro Built-in Functions - -GCC provides intrinsics to access every instruction of the TILEPro -processor. The intrinsics are of the form: - -@smallexample - -unsigned __insn_@var{op} (...) - -@end smallexample - -@noindent -where @var{op} is the name of the instruction. Refer to the ISA manual -for the complete list of instructions. - -GCC also provides intrinsics to directly access the network registers. -The intrinsics are: - -@smallexample - -unsigned __tile_idn0_receive (void) -unsigned __tile_idn1_receive (void) -unsigned __tile_sn_receive (void) -unsigned __tile_udn0_receive (void) -unsigned __tile_udn1_receive (void) -unsigned __tile_udn2_receive (void) -unsigned __tile_udn3_receive (void) -void __tile_idn_send (unsigned) -void __tile_sn_send (unsigned) -void __tile_udn_send (unsigned) - -@end smallexample - -The intrinsic @code{void __tile_network_barrier (void)} is used to -guarantee that no network operations before it are reordered with -those after it. - -@node Target Format Checks -@section Format Checks Specific to Particular Target Machines - -For some target machines, GCC supports additional options to the -format attribute -(@pxref{Function Attributes,,Declaring Attributes of Functions}). - -@menu -* Solaris Format Checks:: -* Darwin Format Checks:: -@end menu - -@node Solaris Format Checks -@subsection Solaris Format Checks - -Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format -check. @code{cmn_err} accepts a subset of the standard @code{printf} -conversions, and the two-argument @code{%b} conversion for displaying -bit-fields. See the Solaris man page for @code{cmn_err} for more information. - -@node Darwin Format Checks -@subsection Darwin Format Checks - -Darwin targets support the @code{CFString} (or @code{__CFString__}) in the format -attribute context. Declarations made with such attribution are parsed for correct syntax -and format argument types. However, parsing of the format string itself is currently undefined -and is not carried out by this version of the compiler. - -Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may -also be used as format arguments. Note that the relevant headers are only likely to be -available on Darwin (OSX) installations. On such installations, the XCode and system -documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and -associated functions. - -@node Pragmas -@section Pragmas Accepted by GCC -@cindex pragmas -@cindex @code{#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:: -* M32C Pragmas:: -* MeP Pragmas:: -* RS/6000 and PowerPC Pragmas:: -* Darwin Pragmas:: -* Solaris Pragmas:: -* Symbol-Renaming Pragmas:: -* Structure-Packing Pragmas:: -* Weak Pragmas:: -* Diagnostic Pragmas:: -* Visibility Pragmas:: -* Push/Pop Macro Pragmas:: -* Function Specific Option 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 - -@node M32C Pragmas -@subsection M32C Pragmas - -@table @code -@item GCC memregs @var{number} -@cindex pragma, memregs -Overrides the command-line option @code{-memregs=} for the current -file. Use with care! This pragma must be before any function in the -file, and mixing different memregs values in different objects may -make them incompatible. This pragma is useful when a -performance-critical function uses a memreg for temporary values, -as it may allow you to reduce the number of memregs used. - -@item ADDRESS @var{name} @var{address} -@cindex pragma, address -For any declared symbols matching @var{name}, this does three things -to that symbol: it forces the symbol to be located at the given -address (a number), it forces the symbol to be volatile, and it -changes the symbol's scope to be static. This pragma exists for -compatibility with other compilers, but note that the common -@code{1234H} numeric syntax is not supported (use @code{0x1234} -instead). Example: - -@smallexample -#pragma ADDRESS port3 0x103 -char port3; -@end smallexample - -@end table - -@node MeP Pragmas -@subsection MeP Pragmas - -@table @code - -@item custom io_volatile (on|off) -@cindex pragma, custom io_volatile -Overrides the command-line option @code{-mio-volatile} for the current -file. Note that for compatibility with future GCC releases, this -option should only be used once before any @code{io} variables in each -file. - -@item GCC coprocessor available @var{registers} -@cindex pragma, coprocessor available -Specifies which coprocessor registers are available to the register -allocator. @var{registers} may be a single register, register range -separated by ellipses, or comma-separated list of those. Example: - -@smallexample -#pragma GCC coprocessor available $c0...$c10, $c28 -@end smallexample - -@item GCC coprocessor call_saved @var{registers} -@cindex pragma, coprocessor call_saved -Specifies which coprocessor registers are to be saved and restored by -any function using them. @var{registers} may be a single register, -register range separated by ellipses, or comma-separated list of -those. Example: - -@smallexample -#pragma GCC coprocessor call_saved $c4...$c6, $c31 -@end smallexample - -@item GCC coprocessor subclass '(A|B|C|D)' = @var{registers} -@cindex pragma, coprocessor subclass -Creates and defines a register class. These register classes can be -used by inline @code{asm} constructs. @var{registers} may be a single -register, register range separated by ellipses, or comma-separated -list of those. Example: - -@smallexample -#pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6 - -asm ("cpfoo %0" : "=B" (x)); -@end smallexample - -@item GCC disinterrupt @var{name} , @var{name} @dots{} -@cindex pragma, disinterrupt -For the named functions, the compiler adds code to disable interrupts -for the duration of those functions. If any functions so named -are not encountered in the source, a warning is emitted that the pragma is -not used. Examples: - -@smallexample -#pragma disinterrupt foo -#pragma disinterrupt bar, grill -int foo () @{ @dots{} @} -@end smallexample - -@item GCC call @var{name} , @var{name} @dots{} -@cindex pragma, call -For the named functions, the compiler always uses a register-indirect -call model when calling the named functions. Examples: - -@smallexample -extern int foo (); -#pragma call foo -@end smallexample - -@end table - -@node RS/6000 and PowerPC Pragmas -@subsection RS/6000 and PowerPC Pragmas - -The RS/6000 and PowerPC targets define one pragma for controlling -whether or not the @code{longcall} attribute is added to function -declarations by default. This pragma overrides the @option{-mlongcall} -option, but not the @code{longcall} and @code{shortcall} attributes. -@xref{RS/6000 and PowerPC Options}, for more information about when long -calls are and are not necessary. - -@table @code -@item longcall (1) -@cindex pragma, longcall -Apply the @code{longcall} attribute to all subsequent function -declarations. - -@item longcall (0) -Do not apply the @code{longcall} attribute to subsequent function -declarations. -@end table - -@c Describe h8300 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 -Mac OS 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 does 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 Solaris Pragmas -@subsection Solaris Pragmas - -The Solaris target supports @code{#pragma redefine_extname} -(@pxref{Symbol-Renaming Pragmas}). It also supports additional -@code{#pragma} directives for compatibility with the system compiler. - -@table @code -@item align @var{alignment} (@var{variable} [, @var{variable}]...) -@cindex pragma, align - -Increase the minimum alignment of each @var{variable} to @var{alignment}. -This is the same as GCC's @code{aligned} attribute @pxref{Variable -Attributes}). Macro expansion occurs on the arguments to this pragma -when compiling C and Objective-C@. It does not currently occur when -compiling C++, but this is a bug which may be fixed in a future -release. - -@item fini (@var{function} [, @var{function}]...) -@cindex pragma, fini - -This pragma causes each listed @var{function} to be called after -main, or during shared module unloading, by adding a call to the -@code{.fini} section. - -@item init (@var{function} [, @var{function}]...) -@cindex pragma, init - -This pragma causes each listed @var{function} to be called during -initialization (before @code{main}) or during shared module loading, by -adding a call to the @code{.init} section. - -@end table - -@node Symbol-Renaming Pragmas -@subsection Symbol-Renaming Pragmas - -For compatibility with the Solaris system headers, GCC -supports two @code{#pragma} directives that change the name used in -assembly for a given declaration. To get this effect -on all platforms supported by GCC, use the asm labels extension (@pxref{Asm -Labels}). - -@table @code -@item redefine_extname @var{oldname} @var{newname} -@cindex pragma, redefine_extname - -This pragma gives the C function @var{oldname} the assembly symbol -@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} -is defined if this pragma is available (currently on all platforms). -@end table - -This pragma and the asm labels extension interact in a complicated -manner. Here are some corner cases you may want to be aware of. - -@enumerate -@item Both pragmas silently apply only to declarations with external -linkage. Asm labels do not have this restriction. - -@item In C++, both pragmas silently apply only to declarations with -``C'' linkage. Again, asm labels do not have this restriction. - -@item If any of the three ways of changing the assembly name of a -declaration is applied to a declaration whose assembly name has -already been determined (either by a previous use of one of these -features, or because the compiler needed the assembly name in order to -generate code), and the new name is different, a warning issues and -the name does not change. - -@item The @var{oldname} used by @code{#pragma redefine_extname} is -always the C-language name. -@end enumerate - -@node Structure-Packing Pragmas -@subsection Structure-Packing Pragmas - -For compatibility with Microsoft Windows compilers, GCC supports a -set of @code{#pragma} directives that change the maximum alignment of -members of structures (other than zero-width bit-fields), unions, and -classes subsequently defined. The @var{n} value below always is required -to be a small power of two and specifies the new alignment in bytes. - -@enumerate -@item @code{#pragma pack(@var{n})} simply sets the new alignment. -@item @code{#pragma pack()} sets the alignment to the one that was in -effect when compilation started (see also command-line option -@option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). -@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment -setting on an internal stack and then optionally sets the new alignment. -@item @code{#pragma pack(pop)} restores the alignment setting to the one -saved at the top of the internal stack (and removes that stack entry). -Note that @code{#pragma pack([@var{n}])} does not influence this internal -stack; thus it is possible to have @code{#pragma pack(push)} followed by -multiple @code{#pragma pack(@var{n})} instances and finalized by a single -@code{#pragma pack(pop)}. -@end enumerate - -Some targets, e.g.@: i386 and PowerPC, support the @code{ms_struct} -@code{#pragma} which lays out a structure as the documented -@code{__attribute__ ((ms_struct))}. -@enumerate -@item @code{#pragma ms_struct on} turns on the layout for structures -declared. -@item @code{#pragma ms_struct off} turns off the layout for structures -declared. -@item @code{#pragma ms_struct reset} goes back to the default layout. -@end enumerate - -@node Weak Pragmas -@subsection Weak Pragmas - -For compatibility with SVR4, GCC supports a set of @code{#pragma} -directives for declaring symbols to be weak, and defining weak -aliases. - -@table @code -@item #pragma weak @var{symbol} -@cindex pragma, weak -This pragma declares @var{symbol} to be weak, as if the declaration -had the attribute of the same name. The pragma may appear before -or after the declaration of @var{symbol}. It is not an error for -@var{symbol} to never be defined at all. - -@item #pragma weak @var{symbol1} = @var{symbol2} -This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. -It is an error if @var{symbol2} is not defined in the current -translation unit. -@end table - -@node Diagnostic Pragmas -@subsection Diagnostic Pragmas - -GCC allows the user to selectively enable or disable certain types of -diagnostics, and change the kind of the diagnostic. For example, a -project's policy might require that all sources compile with -@option{-Werror} but certain files might have exceptions allowing -specific types of warnings. Or, a project might selectively enable -diagnostics and treat them as errors depending on which preprocessor -macros are defined. - -@table @code -@item #pragma GCC diagnostic @var{kind} @var{option} -@cindex pragma, diagnostic - -Modifies the disposition of a diagnostic. Note that not all -diagnostics are modifiable; at the moment only warnings (normally -controlled by @samp{-W@dots{}}) can be controlled, and not all of them. -Use @option{-fdiagnostics-show-option} to determine which diagnostics -are controllable and which option controls them. - -@var{kind} is @samp{error} to treat this diagnostic as an error, -@samp{warning} to treat it like a warning (even if @option{-Werror} is -in effect), or @samp{ignored} if the diagnostic is to be ignored. -@var{option} is a double quoted string that matches the command-line -option. - -@smallexample -#pragma GCC diagnostic warning "-Wformat" -#pragma GCC diagnostic error "-Wformat" -#pragma GCC diagnostic ignored "-Wformat" -@end smallexample - -Note that these pragmas override any command-line options. GCC keeps -track of the location of each pragma, and issues diagnostics according -to the state as of that point in the source file. Thus, pragmas occurring -after a line do not affect diagnostics caused by that line. - -@item #pragma GCC diagnostic push -@itemx #pragma GCC diagnostic pop - -Causes GCC to remember the state of the diagnostics as of each -@code{push}, and restore to that point at each @code{pop}. If a -@code{pop} has no matching @code{push}, the command-line options are -restored. - -@smallexample -#pragma GCC diagnostic error "-Wuninitialized" - foo(a); /* error is given for this one */ -#pragma GCC diagnostic push -#pragma GCC diagnostic ignored "-Wuninitialized" - foo(b); /* no diagnostic for this one */ -#pragma GCC diagnostic pop - foo(c); /* error is given for this one */ -#pragma GCC diagnostic pop - foo(d); /* depends on command-line options */ -@end smallexample - -@end table - -GCC also offers a simple mechanism for printing messages during -compilation. - -@table @code -@item #pragma message @var{string} -@cindex pragma, diagnostic - -Prints @var{string} as a compiler message on compilation. The message -is informational only, and is neither a compilation warning nor an error. - -@smallexample -#pragma message "Compiling " __FILE__ "..." -@end smallexample - -@var{string} may be parenthesized, and is printed with location -information. For example, - -@smallexample -#define DO_PRAGMA(x) _Pragma (#x) -#define TODO(x) DO_PRAGMA(message ("TODO - " #x)) - -TODO(Remember to fix this) -@end smallexample - -@noindent -prints @samp{/tmp/file.c:4: note: #pragma message: -TODO - Remember to fix this}. - -@end table - -@node Visibility Pragmas -@subsection Visibility Pragmas - -@table @code -@item #pragma GCC visibility push(@var{visibility}) -@itemx #pragma GCC visibility pop -@cindex pragma, visibility - -This pragma allows the user to set the visibility for multiple -declarations without having to give each a visibility attribute -@xref{Function Attributes}, for more information about visibility and -the attribute syntax. - -In C++, @samp{#pragma GCC visibility} affects only namespace-scope -declarations. Class members and template specializations are not -affected; if you want to override the visibility for a particular -member or instantiation, you must use an attribute. - -@end table - - -@node Push/Pop Macro Pragmas -@subsection Push/Pop Macro Pragmas - -For compatibility with Microsoft Windows compilers, GCC supports -@samp{#pragma push_macro(@var{"macro_name"})} -and @samp{#pragma pop_macro(@var{"macro_name"})}. - -@table @code -@item #pragma push_macro(@var{"macro_name"}) -@cindex pragma, push_macro -This pragma saves the value of the macro named as @var{macro_name} to -the top of the stack for this macro. - -@item #pragma pop_macro(@var{"macro_name"}) -@cindex pragma, pop_macro -This pragma sets the value of the macro named as @var{macro_name} to -the value on top of the stack for this macro. If the stack for -@var{macro_name} is empty, the value of the macro remains unchanged. -@end table - -For example: - -@smallexample -#define X 1 -#pragma push_macro("X") -#undef X -#define X -1 -#pragma pop_macro("X") -int x [X]; -@end smallexample - -@noindent -In this example, the definition of X as 1 is saved by @code{#pragma -push_macro} and restored by @code{#pragma pop_macro}. - -@node Function Specific Option Pragmas -@subsection Function Specific Option Pragmas - -@table @code -@item #pragma GCC target (@var{"string"}...) -@cindex pragma GCC target - -This pragma allows you to set target specific options for functions -defined later in the source file. One or more strings can be -specified. Each function that is defined after this point is as -if @code{attribute((target("STRING")))} was specified for that -function. The parenthesis around the options is optional. -@xref{Function Attributes}, for more information about the -@code{target} attribute and the attribute syntax. - -The @code{#pragma GCC target} attribute is not implemented in GCC versions earlier -than 4.4 for the i386/x86_64 and 4.6 for the PowerPC back ends. At -present, it is not implemented for other back ends. -@end table - -@table @code -@item #pragma GCC optimize (@var{"string"}...) -@cindex pragma GCC optimize - -This pragma allows you to set global optimization options for functions -defined later in the source file. One or more strings can be -specified. Each function that is defined after this point is as -if @code{attribute((optimize("STRING")))} was specified for that -function. The parenthesis around the options is optional. -@xref{Function Attributes}, for more information about the -@code{optimize} attribute and the attribute syntax. - -The @samp{#pragma GCC optimize} pragma is not implemented in GCC -versions earlier than 4.4. -@end table - -@table @code -@item #pragma GCC push_options -@itemx #pragma GCC pop_options -@cindex pragma GCC push_options -@cindex pragma GCC pop_options - -These pragmas maintain a stack of the current target and optimization -options. It is intended for include files where you temporarily want -to switch to using a different @samp{#pragma GCC target} or -@samp{#pragma GCC optimize} and then to pop back to the previous -options. - -The @samp{#pragma GCC push_options} and @samp{#pragma GCC pop_options} -pragmas are not implemented in GCC versions earlier than 4.4. -@end table - -@table @code -@item #pragma GCC reset_options -@cindex pragma GCC reset_options - -This pragma clears the current @code{#pragma GCC target} and -@code{#pragma GCC optimize} to use the default switches as specified -on the command line. - -The @samp{#pragma GCC reset_options} pragma is not implemented in GCC -versions earlier than 4.4. -@end table - -@node Unnamed Fields -@section Unnamed struct/union fields within structs/unions -@cindex @code{struct} -@cindex @code{union} - -As permitted by ISO C11 and 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: - -@smallexample -struct @{ - int a; - union @{ - int b; - float c; - @}; - int d; -@} foo; -@end smallexample - -@noindent -In this example, you are 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, in this structure: - -@smallexample -struct @{ - int a; - struct @{ - int a; - @}; -@} foo; -@end smallexample - -@noindent -it is ambiguous which @code{a} is being referred to with @samp{foo.a}. -The compiler gives errors for such constructs. - -@opindex fms-extensions -Unless @option{-fms-extensions} is used, the unnamed field must be a -structure or union definition without a tag (for example, @samp{struct -@{ int a; @};}). If @option{-fms-extensions} is used, the field may -also be a definition with a tag such as @samp{struct foo @{ int a; -@};}, a reference to a previously defined structure or union such as -@samp{struct foo;}, or a reference to a @code{typedef} name for a -previously defined structure or union type. - -@opindex fplan9-extensions -The option @option{-fplan9-extensions} enables -@option{-fms-extensions} as well as two other extensions. First, a -pointer to a structure is automatically converted to a pointer to an -anonymous field for assignments and function calls. For example: - -@smallexample -struct s1 @{ int a; @}; -struct s2 @{ struct s1; @}; -extern void f1 (struct s1 *); -void f2 (struct s2 *p) @{ f1 (p); @} -@end smallexample - -@noindent -In the call to @code{f1} inside @code{f2}, the pointer @code{p} is -converted into a pointer to the anonymous field. - -Second, when the type of an anonymous field is a @code{typedef} for a -@code{struct} or @code{union}, code may refer to the field using the -name of the @code{typedef}. - -@smallexample -typedef struct @{ int a; @} s1; -struct s2 @{ s1; @}; -s1 f1 (struct s2 *p) @{ return p->s1; @} -@end smallexample - -These usages are only permitted when they are not ambiguous. - -@node Thread-Local -@section Thread-Local Storage -@cindex Thread-Local Storage -@cindex @acronym{TLS} -@cindex @code{__thread} - -Thread-local storage (@acronym{TLS}) is a mechanism by which variables -are allocated such that there is one instance of the variable per extant -thread. The runtime model GCC uses to implement this originates -in the IA-64 processor-specific ABI, but has since been migrated -to other processors as well. It requires significant support from -the linker (@command{ld}), dynamic linker (@command{ld.so}), and -system libraries (@file{libc.so} and @file{libpthread.so}), so it -is not available everywhere. - -At the user level, the extension is visible with a new storage -class keyword: @code{__thread}. For example: - -@smallexample -__thread int i; -extern __thread struct state s; -static __thread char *p; -@end smallexample - -The @code{__thread} specifier may be used alone, with the @code{extern} -or @code{static} specifiers, but with no other storage class specifier. -When used with @code{extern} or @code{static}, @code{__thread} must appear -immediately after the other storage class specifier. - -The @code{__thread} specifier may be applied to any global, file-scoped -static, function-scoped static, or static data member of a class. It may -not be applied to block-scoped automatic or non-static data member. - -When the address-of operator is applied to a thread-local variable, it is -evaluated at run time and returns the address of the current thread's -instance of that variable. An address so obtained may be used by any -thread. When a thread terminates, any pointers to thread-local variables -in that thread become invalid. - -No static initialization may refer to the address of a thread-local variable. - -In C++, if an initializer is present for a thread-local variable, it must -be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ -standard. - -See @uref{http://www.akkadia.org/drepper/tls.pdf, -ELF Handling For Thread-Local Storage} for a detailed explanation of -the four thread-local storage addressing models, and how the runtime -is expected to function. - -@menu -* C99 Thread-Local Edits:: -* C++98 Thread-Local Edits:: -@end menu - -@node C99 Thread-Local Edits -@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage - -The following are a set of changes to ISO/IEC 9899:1999 (aka C99) -that document the exact semantics of the language extension. - -@itemize @bullet -@item -@cite{5.1.2 Execution environments} - -Add new text after paragraph 1 - -@quotation -Within either execution environment, a @dfn{thread} is a flow of -control within a program. It is implementation defined whether -or not there may be more than one thread associated with a program. -It is implementation defined how threads beyond the first are -created, the name and type of the function called at thread -startup, and how threads may be terminated. However, objects -with thread storage duration shall be initialized before thread -startup. -@end quotation - -@item -@cite{6.2.4 Storage durations of objects} - -Add new text before paragraph 3 - -@quotation -An object whose identifier is declared with the storage-class -specifier @w{@code{__thread}} has @dfn{thread storage duration}. -Its lifetime is the entire execution of the thread, and its -stored value is initialized only once, prior to thread startup. -@end quotation - -@item -@cite{6.4.1 Keywords} - -Add @code{__thread}. - -@item -@cite{6.7.1 Storage-class specifiers} - -Add @code{__thread} to the list of storage class specifiers in -paragraph 1. - -Change paragraph 2 to - -@quotation -With the exception of @code{__thread}, at most one storage-class -specifier may be given [@dots{}]. The @code{__thread} specifier may -be used alone, or immediately following @code{extern} or -@code{static}. -@end quotation - -Add new text after paragraph 6 - -@quotation -The declaration of an identifier for a variable that has -block scope that specifies @code{__thread} shall also -specify either @code{extern} or @code{static}. - -The @code{__thread} specifier shall be used only with -variables. -@end quotation -@end itemize - -@node C++98 Thread-Local Edits -@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage - -The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) -that document the exact semantics of the language extension. - -@itemize @bullet -@item -@b{[intro.execution]} - -New text after paragraph 4 - -@quotation -A @dfn{thread} is a flow of control within the abstract machine. -It is implementation defined whether or not there may be more than -one thread. -@end quotation - -New text after paragraph 7 - -@quotation -It is unspecified whether additional action must be taken to -ensure when and whether side effects are visible to other threads. -@end quotation - -@item -@b{[lex.key]} - -Add @code{__thread}. - -@item -@b{[basic.start.main]} - -Add after paragraph 5 - -@quotation -The thread that begins execution at the @code{main} function is called -the @dfn{main thread}. It is implementation defined how functions -beginning threads other than the main thread are designated or typed. -A function so designated, as well as the @code{main} function, is called -a @dfn{thread startup function}. It is implementation defined what -happens if a thread startup function returns. It is implementation -defined what happens to other threads when any thread calls @code{exit}. -@end quotation - -@item -@b{[basic.start.init]} - -Add after paragraph 4 - -@quotation -The storage for an object of thread storage duration shall be -statically initialized before the first statement of the thread startup -function. An object of thread storage duration shall not require -dynamic initialization. -@end quotation - -@item -@b{[basic.start.term]} - -Add after paragraph 3 - -@quotation -The type of an object with thread storage duration shall not have a -non-trivial destructor, nor shall it be an array type whose elements -(directly or indirectly) have non-trivial destructors. -@end quotation - -@item -@b{[basic.stc]} - -Add ``thread storage duration'' to the list in paragraph 1. - -Change paragraph 2 - -@quotation -Thread, static, and automatic storage durations are associated with -objects introduced by declarations [@dots{}]. -@end quotation - -Add @code{__thread} to the list of specifiers in paragraph 3. - -@item -@b{[basic.stc.thread]} - -New section before @b{[basic.stc.static]} - -@quotation -The keyword @code{__thread} applied to a non-local object gives the -object thread storage duration. - -A local variable or class data member declared both @code{static} -and @code{__thread} gives the variable or member thread storage -duration. -@end quotation - -@item -@b{[basic.stc.static]} - -Change paragraph 1 - -@quotation -All objects that have neither thread storage duration, dynamic -storage duration nor are local [@dots{}]. -@end quotation - -@item -@b{[dcl.stc]} - -Add @code{__thread} to the list in paragraph 1. - -Change paragraph 1 - -@quotation -With the exception of @code{__thread}, at most one -@var{storage-class-specifier} shall appear in a given -@var{decl-specifier-seq}. The @code{__thread} specifier may -be used alone, or immediately following the @code{extern} or -@code{static} specifiers. [@dots{}] -@end quotation - -Add after paragraph 5 - -@quotation -The @code{__thread} specifier can be applied only to the names of objects -and to anonymous unions. -@end quotation - -@item -@b{[class.mem]} - -Add after paragraph 6 - -@quotation -Non-@code{static} members shall not be @code{__thread}. -@end quotation -@end itemize - -@node Binary constants -@section Binary constants using the @samp{0b} prefix -@cindex Binary constants using the @samp{0b} prefix - -Integer constants can be written as binary constants, consisting of a -sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or -@samp{0B}. This is particularly useful in environments that operate a -lot on the bit level (like microcontrollers). - -The following statements are identical: - -@smallexample -i = 42; -i = 0x2a; -i = 052; -i = 0b101010; -@end smallexample - -The type of these constants follows the same rules as for octal or -hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} -can be applied. - -@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{Common Predefined Macros,, -Predefined Macros,cpp,The GNU C Preprocessor}). - -@menu -* C++ 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. -* Function Multiversioning:: Declaring multiple function versions. -* Namespace Association:: Strong using-directives for namespace association. -* Type Traits:: Compiler support for type traits -* Java Exceptions:: Tweaking exception handling to work with Java. -* Deprecated Features:: Things will disappear from G++. -* Backwards Compatibility:: Compatibilities with earlier definitions of C++. -@end menu - -@node C++ Volatiles -@section When is a Volatile C++ Object Accessed? -@cindex accessing volatiles -@cindex volatile read -@cindex volatile write -@cindex volatile access - -The C++ standard differs from the C standard in its treatment of -volatile objects. It fails to specify what constitutes a volatile -access, except to say that C++ should behave in a similar manner to C -with respect to volatiles, where possible. However, the different -lvalueness of expressions between C and C++ complicate the behavior. -G++ behaves the same as GCC for volatile access, @xref{C -Extensions,,Volatiles}, for a description of GCC's behavior. - -The C and C++ language specifications differ when an object is -accessed in a void context: - -@smallexample -volatile int *src = @var{somevalue}; -*src; -@end smallexample - -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 lvalue to rvalue conversion that is responsible for causing an -access. 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 as GCC would do for an equivalent -type in C@. When the object has incomplete type, G++ issues a -warning; if you wish to force an error, you must force a conversion to -rvalue with, for instance, a static cast. - -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. - -G++ implements the same behavior as GCC does when assigning to a -volatile object---there is no reread of the assigned-to object, the -assigned rvalue is reused. Note that in C++ assignment expressions -are lvalues, and if used as an lvalue, the volatile object is -referred to. For instance, @var{vref} refers to @var{vobj}, as -expected, in the following example: - -@smallexample -volatile int vobj; -volatile int &vref = vobj = @var{something}; -@end smallexample - -@node Restricted Pointers -@section Restricting Pointer Aliasing -@cindex restricted pointers -@cindex restricted references -@cindex restricted this pointer - -As with the C front end, 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. - -@smallexample -void fn (int *__restrict__ rptr, int &__restrict__ rref) -@{ - /* @r{@dots{}} */ -@} -@end smallexample - -@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. - -@smallexample -void T::fn () __restrict__ -@{ - /* @r{@dots{}} */ -@} -@end smallexample - -@noindent -Within the body of @code{T::fn}, @var{this} has 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 that 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++ that 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 always requires 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 is still emitted in every translation unit that defines it. -Make sure that any inline virtuals are declared inline in the class -body, even if they are not defined there. - -@item @code{type_info} objects -@cindex @code{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 @samp{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 run time. For all -other types, we write out the @samp{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 -GNU/Linux 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 -uses them. This way one copy overrides all the others, but -the unused copies still take up space in the executable. - -For targets that do not support either COMDAT or weak symbols, -most entities with vague linkage are emitted as local symbols to -avoid duplicate definition errors from the linker. This does not happen -for local statics in inlines, however, as having multiple copies -almost certainly breaks things. - -@xref{C++ Interface,,Declarations and Definitions in One Header}, for -another way to control placement of these constructs. - -@node C++ Interface -@section #pragma interface and implementation - -@cindex interface and implementation headers, C++ -@cindex C++ interface and implementation headers -@cindex pragmas, interface and implementation - -@code{#pragma interface} and @code{#pragma implementation} provide the -user with a way of explicitly directing the compiler to emit entities -with vague linkage (and debugging information) in a particular -translation unit. - -@emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in -most cases, because of COMDAT support and the ``key method'' heuristic -mentioned in @ref{Vague Linkage}. Using them can actually cause your -program to grow due to unnecessary out-of-line copies of inline -functions. Currently (3.4) the only benefit of these -@code{#pragma}s is reduced duplication of debugging information, and -that should be addressed soon on DWARF 2 targets with the use of -COMDAT groups. - -@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 is not generated (unless -the main input source file itself uses @samp{#pragma implementation}). -Instead, the object files 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} -is 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. - -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 an inline 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 are 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 are referred 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 -GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the -Borland model. On other systems, G++ implements neither automatic -model. - -You have the following options for dealing with template instantiations: - -@enumerate -@item -@opindex frepo -Compile your template-using code with @option{-frepo}. The compiler -generates files with the extension @samp{.rpo} listing all of the -template instantiations used in the corresponding object files that -could be instantiated there; the link wrapper, @samp{collect2}, -then updates 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 -continues to place the instantiations in the same files. - -This is your best option for application code written for the Borland -model, as it just works. Code written for the Cfront model -needs 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 - -@smallexample -#include "Foo.h" -#include "Foo.cc" - -template class Foo<int>; -template ostream& operator << - (ostream&, const Foo<int>&); -@end smallexample - -@noindent -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. - -The ISO C++ 2011 standard allows forward declaration of explicit -instantiations (with @code{extern}). G++ supports explicit instantiation -declarations in C++98 mode and has extended the template instantiation -syntax to support 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}): - -@smallexample -extern template int max (int, int); -inline template class Foo<int>; -static template class Foo<int>; -@end smallexample - -@item -Do nothing. Pretend G++ does implement automatic instantiation -management. Code written for the Borland model works fine, but -each translation unit contains instances of each of the templates it -uses. In a large program, this can lead to an unacceptable amount of code -duplication. -@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 still pay 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 - -@smallexample -extern A a; -extern int (A::*fp)(); -typedef int (*fptr)(A *); - -fptr p = (fptr)(a.*fp); -@end smallexample - -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: - -@smallexample -fptr p1 = (fptr)(&A::foo); -@end smallexample - -@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 abi_tag ("@var{tag}", ...) -@cindex @code{abi_tag} attribute -The @code{abi_tag} attribute can be applied to a function or class -declaration. It modifies the mangled name of the function or class to -incorporate the tag name, in order to distinguish the function or -class from an earlier version with a different ABI; perhaps the class -has changed size, or the function has a different return type that is -not encoded in the mangled name. - -The argument can be a list of strings of arbitrary length. The -strings are sorted on output, so the order of the list is -unimportant. - -A redeclaration of a function or class must not add new ABI tags, -since doing so would change the mangled name. - -The @option{-Wabi-tag} flag enables a warning about a class which does -not have all the ABI tags used by its subobjects and virtual functions; for users with code -that needs to coexist with an earlier ABI, using this option can help -to find all affected types that need to be tagged. - -@item init_priority (@var{priority}) -@cindex @code{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 reverses that order: - -@smallexample -Some_Class A __attribute__ ((init_priority (2000))); -Some_Class B __attribute__ ((init_priority (543))); -@end smallexample - -@noindent -Note that the particular values of @var{priority} do not matter; only their -relative ordering. - -@item java_interface -@cindex @code{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 are dispatched using GCJ's -interface table mechanism, instead of regular virtual table dispatch. - -@end table - -See also @ref{Namespace Association}. - -@node Function Multiversioning -@section Function Multiversioning -@cindex function versions - -With the GNU C++ front end, for target i386, you may specify multiple -versions of a function, where each function is specialized for a -specific target feature. At runtime, the appropriate version of the -function is automatically executed depending on the characteristics of -the execution platform. Here is an example. - -@smallexample -__attribute__ ((target ("default"))) -int foo () -@{ - // The default version of foo. - return 0; -@} - -__attribute__ ((target ("sse4.2"))) -int foo () -@{ - // foo version for SSE4.2 - return 1; -@} - -__attribute__ ((target ("arch=atom"))) -int foo () -@{ - // foo version for the Intel ATOM processor - return 2; -@} - -__attribute__ ((target ("arch=amdfam10"))) -int foo () -@{ - // foo version for the AMD Family 0x10 processors. - return 3; -@} - -int main () -@{ - int (*p)() = &foo; - assert ((*p) () == foo ()); - return 0; -@} -@end smallexample - -In the above example, four versions of function foo are created. The -first version of foo with the target attribute "default" is the default -version. This version gets executed when no other target specific -version qualifies for execution on a particular platform. A new version -of foo is created by using the same function signature but with a -different target string. Function foo is called or a pointer to it is -taken just like a regular function. GCC takes care of doing the -dispatching to call the right version at runtime. Refer to the -@uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on -Function Multiversioning} for more details. - -@node Namespace Association -@section Namespace Association - -@strong{Caution:} The semantics of this extension are equivalent -to C++ 2011 inline namespaces. Users should use inline namespaces -instead as this extension will be removed in future versions of G++. - -A using-directive with @code{__attribute ((strong))} is stronger -than a normal using-directive in two ways: - -@itemize @bullet -@item -Templates from the used namespace can be specialized and explicitly -instantiated as though they were members of the using namespace. - -@item -The using namespace is considered an associated namespace of all -templates in the used namespace for purposes of argument-dependent -name lookup. -@end itemize - -The used namespace must be nested within the using namespace so that -normal unqualified lookup works properly. - -This is useful for composing a namespace transparently from -implementation namespaces. For example: - -@smallexample -namespace std @{ - namespace debug @{ - template <class T> struct A @{ @}; - @} - using namespace debug __attribute ((__strong__)); - template <> struct A<int> @{ @}; // @r{ok to specialize} - - template <class T> void f (A<T>); -@} - -int main() -@{ - f (std::A<float>()); // @r{lookup finds} std::f - f (std::A<int>()); -@} -@end smallexample - -@node Type Traits -@section Type Traits - -The C++ front end implements syntactic extensions that allow -compile-time determination of -various characteristics of a type (or of a -pair of types). - -@table @code -@item __has_nothrow_assign (type) -If @code{type} is const qualified or is a reference type then the trait is -false. Otherwise if @code{__has_trivial_assign (type)} is true then the trait -is true, else if @code{type} is a cv class or union type with copy assignment -operators that are known not to throw an exception then the trait is true, -else it is false. Requires: @code{type} shall be a complete type, -(possibly cv-qualified) @code{void}, or an array of unknown bound. - -@item __has_nothrow_copy (type) -If @code{__has_trivial_copy (type)} is true then the trait is true, else if -@code{type} is a cv class or union type with copy constructors that -are known not to throw an exception then the trait is true, else it is false. -Requires: @code{type} shall be a complete type, (possibly cv-qualified) -@code{void}, or an array of unknown bound. - -@item __has_nothrow_constructor (type) -If @code{__has_trivial_constructor (type)} is true then the trait is -true, else if @code{type} is a cv class or union type (or array -thereof) with a default constructor that is known not to throw an -exception then the trait is true, else it is false. Requires: -@code{type} shall be a complete type, (possibly cv-qualified) -@code{void}, or an array of unknown bound. - -@item __has_trivial_assign (type) -If @code{type} is const qualified or is a reference type then the trait is -false. Otherwise if @code{__is_pod (type)} is true then the trait is -true, else if @code{type} is a cv class or union type with a trivial -copy assignment ([class.copy]) then the trait is true, else it is -false. Requires: @code{type} shall be a complete type, (possibly -cv-qualified) @code{void}, or an array of unknown bound. - -@item __has_trivial_copy (type) -If @code{__is_pod (type)} is true or @code{type} is a reference type -then the trait is true, else if @code{type} is a cv class or union type -with a trivial copy constructor ([class.copy]) then the trait -is true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. - -@item __has_trivial_constructor (type) -If @code{__is_pod (type)} is true then the trait is true, else if -@code{type} is a cv class or union type (or array thereof) with a -trivial default constructor ([class.ctor]) then the trait is true, -else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. - -@item __has_trivial_destructor (type) -If @code{__is_pod (type)} is true or @code{type} is a reference type then -the trait is true, else if @code{type} is a cv class or union type (or -array thereof) with a trivial destructor ([class.dtor]) then the trait -is true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. - -@item __has_virtual_destructor (type) -If @code{type} is a class type with a virtual destructor -([class.dtor]) then the trait is true, else it is false. Requires: -@code{type} shall be a complete type, (possibly cv-qualified) -@code{void}, or an array of unknown bound. - -@item __is_abstract (type) -If @code{type} is an abstract class ([class.abstract]) then the trait -is true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. - -@item __is_base_of (base_type, derived_type) -If @code{base_type} is a base class of @code{derived_type} -([class.derived]) then the trait is true, otherwise it is false. -Top-level cv qualifications of @code{base_type} and -@code{derived_type} are ignored. For the purposes of this trait, a -class type is considered is own base. Requires: if @code{__is_class -(base_type)} and @code{__is_class (derived_type)} are true and -@code{base_type} and @code{derived_type} are not the same type -(disregarding cv-qualifiers), @code{derived_type} shall be a complete -type. Diagnostic is produced if this requirement is not met. - -@item __is_class (type) -If @code{type} is a cv class type, and not a union type -([basic.compound]) the trait is true, else it is false. - -@item __is_empty (type) -If @code{__is_class (type)} is false then the trait is false. -Otherwise @code{type} is considered empty if and only if: @code{type} -has no non-static data members, or all non-static data members, if -any, are bit-fields of length 0, and @code{type} has no virtual -members, and @code{type} has no virtual base classes, and @code{type} -has no base classes @code{base_type} for which -@code{__is_empty (base_type)} is false. Requires: @code{type} shall -be a complete type, (possibly cv-qualified) @code{void}, or an array -of unknown bound. - -@item __is_enum (type) -If @code{type} is a cv enumeration type ([basic.compound]) the trait is -true, else it is false. - -@item __is_literal_type (type) -If @code{type} is a literal type ([basic.types]) the trait is -true, else it is false. Requires: @code{type} shall be a complete type, -(possibly cv-qualified) @code{void}, or an array of unknown bound. - -@item __is_pod (type) -If @code{type} is a cv POD type ([basic.types]) then the trait is true, -else it is false. Requires: @code{type} shall be a complete type, -(possibly cv-qualified) @code{void}, or an array of unknown bound. - -@item __is_polymorphic (type) -If @code{type} is a polymorphic class ([class.virtual]) then the trait -is true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. - -@item __is_standard_layout (type) -If @code{type} is a standard-layout type ([basic.types]) the trait is -true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. - -@item __is_trivial (type) -If @code{type} is a trivial type ([basic.types]) the trait is -true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. - -@item __is_union (type) -If @code{type} is a cv union type ([basic.compound]) the trait is -true, else it is false. - -@item __underlying_type (type) -The underlying type of @code{type}. Requires: @code{type} shall be -an enumeration type ([dcl.enum]). - -@end table - -@node Java Exceptions -@section Java Exceptions - -The Java language uses a slightly different exception handling model -from C++. Normally, GNU C++ automatically detects 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 guesses incorrectly. -Sample problematic code is: - -@smallexample - struct S @{ ~S(); @}; - extern void bar(); // @r{is written in Java, and may throw exceptions} - void foo() - @{ - S s; - bar(); - @} -@end smallexample - -@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 - -G++ allows a virtual function returning @samp{void *} to be overridden -by one returning a different pointer type. This extension to the -covariant return type rules is now deprecated and will be removed from a -future version. - -The G++ minimum and maximum operators (@samp{<?} and @samp{>?}) and -their compound forms (@samp{<?=}) and @samp{>?=}) have been deprecated -and are now removed from G++. Code using these operators should be -modified to use @code{std::min} and @code{std::max} instead. - -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 is now -removed from G++. - -The use of default arguments in function pointers, function typedefs -and other places where they are not permitted by the standard is -deprecated and will be removed from a future version of G++. - -G++ allows floating-point literals to appear in integral constant expressions, -e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} } -This extension is deprecated and will be removed from a future version. - -G++ allows static data members of const floating-point type to be declared -with an initializer in a class definition. The standard only allows -initializers for static members of const integral types and const -enumeration types so this extension has been deprecated and will be removed -from a future version. - -@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 that 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{()} is treated as an unspecified number of arguments, rather -than no arguments, as C++ demands. -@end table |