| @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, |
| @c 2001, 2002, 2003, 2004, 2005, 2006 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 C89 or C++ are also, as |
| extensions, accepted by GCC in C89 mode and in C++. |
| |
| @menu |
| * Statement Exprs:: Putting statements and declarations inside expressions. |
| * Local Labels:: Labels local to a 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. |
| * Long Long:: Double-word integers---@code{long long int}. |
| * Complex:: Data types for complex numbers. |
| * Decimal Float:: Decimal Floating Types. |
| * Hex Floats:: Hexadecimal floating-point constants. |
| * Zero Length:: Zero-length arrays. |
| * Variable Length:: Arrays whose length is computed at run time. |
| * Empty Structures:: Structures with no members. |
| * 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. |
| * Cast to Union:: Casting to union type from any member of the union. |
| * Case Ranges:: `case 1 ... 9' and such. |
| * Mixed Declarations:: Mixing declarations and code. |
| * Function Attributes:: Declaring that functions have no side effects, |
| or that they can never return. |
| * Attribute Syntax:: Formal syntax for attributes. |
| * Function Prototypes:: Prototype declarations and old-style definitions. |
| * C++ Comments:: C++ comments are recognized. |
| * Dollar Signs:: Dollar sign is allowed in identifiers. |
| * Character Escapes:: @samp{\e} stands for the character @key{ESC}. |
| @c APPLE LOCAL begin pascal strings |
| * Pascal Strings:: Constructing string literals with a Pascal-style |
| length byte. |
| @c APPLE LOCAL end pascal strings |
| * Variable Attributes:: Specifying attributes of variables. |
| * Type Attributes:: Specifying attributes of types. |
| @c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 |
| * Label Attributes:: Specifying attributes of labels and statements. |
| @c APPLE LOCAL end for-fsf-4_4 3274130 5295549 |
| * Alignment:: Inquiring about the alignment of a type or variable. |
| * Inline:: Defining inline functions (as fast as macros). |
| * Extended Asm:: Assembler instructions with C expressions as operands. |
| (With them you can define ``built-in'' functions.) |
| * Constraints:: Constraints for asm operands |
| * Asm Labels:: Specifying the assembler name to use for a C symbol. |
| * Explicit Reg Vars:: Defining variables residing in specified registers. |
| @c APPLE LOCAL CW asm blocks |
| * Asm Blocks and Functions:: Block and functions of assembly code. |
| * 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}. |
| * Atomic Builtins:: Built-in functions for atomic memory access. |
| * 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. |
| @c APPLE LOCAL blocks 7205047 5811887 |
| * Blocks:: Anonymous functions (closures). |
| @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 |
| will construct a temporary @code{A} object to hold the result of the |
| statement expression, and that will be used to invoke @code{Foo}. |
| Therefore the @code{this} pointer observed by @code{Foo} will not be the |
| address of @code{a}. |
| |
| Any temporaries created within a statement within a statement expression |
| will be destroyed at the statement's end. This makes statement |
| expressions inside macros slightly different from function calls. In |
| the latter case temporaries introduced during argument evaluation will |
| be destroyed at the end of the statement that includes the function |
| call. In the statement expression case they will be 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 |
| will have different places where temporaries are destroyed. For the |
| @code{macro} case, the temporary @code{X} will be destroyed just after |
| the initialization of @code{b}. In the @code{function} case that |
| temporary will be 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-expression 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}) yields 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 |
| will call @code{foo} and @code{bar1} and will not call @code{baz} but |
| may or may not call @code{bar2}. If @code{bar2} is called, it will be |
| 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 was 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 will be 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 |
| will serve as a jump table: |
| |
| @smallexample |
| static void *array[] = @{ &&foo, &&bar, &&hack @}; |
| @end smallexample |
| |
| 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 will happen. The best way to |
| avoid this is to store the label address only in automatic variables and |
| never pass it as an argument. |
| |
| An alternate way to write the above example is |
| |
| @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. |
| |
| @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. |
| @c APPLE LOCAL begin nested functions 4357979 |
| Nested functions are not supported for GNU C++ and are disable by |
| default on Darwin. The @option{-fnested-functions} and |
| @option{-fno-nested-functions} options can be used to enable and |
| disable nested function suppport. 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: |
| @c APPLE LOCAL end nested functions 4357979 |
| |
| @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 has exited, all hell will break loose. If you try |
| to call it after a containing scope level has exited, and if it refers |
| to some of the variables that are no longer in scope, you may be lucky, |
| but it's not wise to take the risk. If, however, the nested function |
| does not refer to anything that has gone out of scope, you should be |
| safe. |
| |
| GCC implements taking the address of a nested function using a technique |
| called @dfn{trampolines}. A paper describing them is available as |
| |
| @noindent |
| @uref{http://people.debian.org/~aaronl/Usenix88-lexic.pdf}. |
| |
| A nested function can jump to a label inherited from a containing |
| function, provided the label was explicitly declared in the containing |
| function (@pxref{Local Labels}). Such a jump returns instantly to the |
| containing function, exiting the nested function which did the |
| @code{goto} and any intermediate functions as well. Here is an example: |
| |
| @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 were passed |
| to the current function. |
| |
| The function saves the arg pointer register, structure value address, |
| and all registers that might be used to pass arguments to a function |
| into a block of memory allocated on the stack. Then it returns the |
| address of that block. |
| @end deftypefn |
| |
| @deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) |
| This built-in function invokes @var{function} |
| with a copy of the parameters described by @var{arguments} |
| and @var{size}. |
| |
| The value of @var{arguments} should be the value returned by |
| @code{__builtin_apply_args}. The argument @var{size} specifies the size |
| of the stack argument data, in bytes. |
| |
| This function returns a pointer to data describing |
| how to return whatever value was returned by @var{function}. The data |
| is saved in a block of memory allocated on the stack. |
| |
| It is not always simple to compute the proper value for @var{size}. The |
| value is used by @code{__builtin_apply} to compute the amount of data |
| that should be pushed on the stack and copied from the incoming argument |
| area. |
| @end deftypefn |
| |
| @deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) |
| This built-in function returns the value described by @var{result} from |
| the containing function. You should specify, for @var{result}, a value |
| returned by @code{__builtin_apply}. |
| @end deftypefn |
| |
| @node 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 could be |
| used. For example, you can use it in a declaration, in a cast, or inside |
| of @code{sizeof} or @code{typeof}. |
| |
| @code{typeof} is often useful in conjunction with the |
| statements-within-expressions feature. Here is how the two together can |
| be used to define a safe ``maximum'' macro that operates on any |
| arithmetic type and evaluates each of its arguments exactly once: |
| |
| @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 which 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 will crash; 3.2.1 and later give an error). Code which |
| relies on it should be rewritten to use @code{typeof}: |
| |
| @smallexample |
| typedef typeof(@var{expr}) @var{T}; |
| @end smallexample |
| |
| @noindent |
| This will work 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 ?: |
| @cindex ?: side effect |
| @noindent |
| In this simple case, the ability to omit the middle operand is not |
| especially useful. When it becomes useful is when the first operand does, |
| or may (if it is a macro argument), contain a side effect. Then repeating |
| the operand in the middle would perform the side effect twice. Omitting |
| the middle operand uses the value already computed without the undesirable |
| effects of recomputing it. |
| |
| @node Long Long |
| @section Double-Word Integers |
| @cindex @code{long long} data types |
| @cindex double-word arithmetic |
| @cindex multiprecision arithmetic |
| @cindex @code{LL} integer suffix |
| @cindex @code{ULL} integer suffix |
| |
| ISO C99 supports data types for integers that are at least 64 bits wide, |
| and as an extension GCC supports them in C89 mode and in C++. |
| Simply write @code{long long int} for a signed integer, or |
| @code{unsigned long long int} for an unsigned integer. To make an |
| integer constant of type @code{long long int}, add the suffix @samp{LL} |
| to the integer. To make an integer constant of type @code{unsigned long |
| long int}, add the suffix @samp{ULL} to the integer. |
| |
| You can use these types in arithmetic like any other integer types. |
| Addition, subtraction, and bitwise boolean operations on these types |
| are open-coded on all types of machines. Multiplication is open-coded |
| if the machine supports fullword-to-doubleword a widening multiply |
| instruction. Division and shifts are open-coded only on machines that |
| provide special support. The operations that are not open-coded use |
| special library routines that come with GCC@. |
| |
| There may be pitfalls when you use @code{long long} types for function |
| arguments, unless you declare function prototypes. If a function |
| expects type @code{int} for its argument, and you pass a value of type |
| @code{long long int}, confusion will result because the caller and the |
| subroutine will disagree about the number of bytes for the argument. |
| Likewise, if the function expects @code{long long int} and you pass |
| @code{int}. The best way to avoid such problems is to use prototypes. |
| |
| @node Complex |
| @section Complex Numbers |
| @cindex complex numbers |
| @cindex @code{_Complex} keyword |
| @cindex @code{__complex__} keyword |
| |
| ISO C99 supports complex floating data types, and as an extension GCC |
| supports them in C89 mode and in C++, and supports complex integer data |
| types which are not part of ISO C99. You can declare complex types |
| using the keyword @code{_Complex}. As an extension, the older GNU |
| keyword @code{__complex__} is also supported. |
| |
| For example, @samp{_Complex double x;} declares @code{x} as a |
| variable whose real part and imaginary part are both of type |
| @code{double}. @samp{_Complex short int y;} declares @code{y} to |
| have real and imaginary parts of type @code{short int}; this is not |
| likely to be useful, but it shows that the set of complex types is |
| complete. |
| |
| To write a constant with a complex data type, use the suffix @samp{i} or |
| @samp{j} (either one; they are equivalent). For example, @code{2.5fi} |
| has type @code{_Complex float} and @code{3i} has type |
| @code{_Complex int}. Such a constant always has a pure imaginary |
| value, but you can form any complex value you like by adding one to a |
| real constant. This is a GNU extension; if you have an ISO C99 |
| conforming C library (such as GNU libc), and want to construct complex |
| constants of floating type, you should include @code{<complex.h>} and |
| use the macros @code{I} or @code{_Complex_I} instead. |
| |
| @cindex @code{__real__} keyword |
| @cindex @code{__imag__} keyword |
| To extract the real part of a complex-valued expression @var{exp}, write |
| @code{__real__ @var{exp}}. Likewise, use @code{__imag__} to |
| extract the imaginary part. This is a GNU extension; for values of |
| floating type, you should use the ISO C99 functions @code{crealf}, |
| @code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and |
| @code{cimagl}, declared in @code{<complex.h>} and also provided as |
| built-in functions by GCC@. |
| |
| @cindex complex conjugation |
| The operator @samp{~} performs complex conjugation when used on a value |
| with a complex type. This is a GNU extension; for values of |
| floating type, you should use the ISO C99 functions @code{conjf}, |
| @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also |
| provided as built-in functions by GCC@. |
| |
| GCC can allocate complex automatic variables in a noncontiguous |
| fashion; it's even possible for the real part to be in a register while |
| the imaginary part is on the stack (or vice-versa). Only the DWARF2 |
| debug info format can represent this, so use of DWARF2 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 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, the GNU C compiler supports decimal floating types as |
| defined in the N1176 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 |
| Translation time data type (TTDT) is not supported. |
| |
| @item |
| Characteristics of decimal floating types are defined in header file |
| @file{decfloat.h} rather than @file{float.h}. |
| |
| @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. |
| @end itemize |
| |
| Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} |
| are supported by the DWARF2 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 C89 mode (except in some cases when strictly |
| conforming) and in C++. In that format the |
| @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are |
| mandatory. The exponent is a decimal number that indicates the power of |
| 2 by which the significant part will be multiplied. Thus @samp{0x1.f} is |
| @tex |
| $1 {15\over16}$, |
| @end tex |
| @ifnottex |
| 1 15/16, |
| @end ifnottex |
| @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} |
| is the same as @code{1.55e1}. |
| |
| Unlike for floating-point numbers in the decimal notation the exponent |
| is always required in the hexadecimal notation. Otherwise the compiler |
| would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This |
| could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the |
| extension for floating-point constants of type @code{float}. |
| |
| @node Zero Length |
| @section Arrays of Length Zero |
| @cindex arrays of length zero |
| @cindex zero-length arrays |
| @cindex length-zero arrays |
| @cindex flexible array members |
| |
| Zero-length arrays are allowed in GNU C@. They are very useful as the |
| last element of a structure which is really a header for a variable-length |
| object: |
| |
| @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. |
| I.e.@: 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 will have 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 C89 mode and in C++. (However, GCC's |
| implementation of variable-length arrays does not yet conform in detail |
| to the ISO C99 standard.) These arrays are |
| declared like any other automatic arrays, but with a length that is not |
| a constant expression. The storage is allocated at the point of |
| declaration and deallocated when the brace-level is exited. For |
| example: |
| |
| @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 |
| will also deallocate 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 |
| |
| 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 |
| |
| 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 |
| |
| 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, GCC allows such arrays to be |
| subscripted in C89 mode, though otherwise they do not decay to |
| pointers outside C99 mode. For example, |
| this is valid in GNU C though not valid in C89: |
| |
| @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 C89 mode and 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. 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 is |
| also allowed, but then the compound literal is equivalent |
| to a cast. |
| |
| As a GNU extension, GCC allows initialization of objects with static storage |
| duration by compound literals (which is not possible in ISO C99, because |
| the initializer is not a constant). |
| It is handled as if the object was initialized only with the bracket |
| enclosed list if 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 |
| |
| @node Designated Inits |
| @section Designated Initializers |
| @cindex initializers with labeled elements |
| @cindex labeled elements in initializers |
| @cindex case labels in initializers |
| @cindex designated initializers |
| |
| Standard C89 requires the elements of an initializer to appear in a fixed |
| order, the same as the order of the elements in the array or structure |
| being initialized. |
| |
| In ISO C99 you can give the elements in any order, specifying the array |
| indices or structure field names they apply to, and GNU C allows this as |
| an extension in C89 mode as well. This extension is not |
| implemented in GNU C++. |
| |
| To specify an array index, write |
| @samp{[@var{index}] =} before the element value. For example, |
| |
| @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 which has been obsolete since GCC 2.5 but |
| GCC still accepts is to write @samp{[@var{index}]} before the element |
| value, with no @samp{=}. |
| |
| To initialize a range of elements to the same value, write |
| @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU |
| extension. For example, |
| |
| @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 will happen only once, |
| not for each initialized field by the range initializer. |
| |
| @noindent |
| Note that the length of the array is the highest value specified |
| plus one. |
| |
| In a structure initializer, specify the name of a field to initialize |
| with @samp{.@var{fieldname} =} before the element value. For example, |
| given the following structure, |
| |
| @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 which 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 |
| will convert 4 to a @code{double} to store it in the union using |
| the second element. By contrast, casting 4 to type @code{union foo} |
| would store it into the union as the integer @code{i}, since it is |
| an integer. (@xref{Cast to Union}.) |
| |
| You can combine this technique of naming elements with ordinary C |
| initialization of successive elements. Each initializer element that |
| does not have a designator applies to the next consecutive element of the |
| array or structure. For example, |
| |
| @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 will have value from |
| the last initialization. If any such overridden initialization has |
| side-effect, it is unspecified whether the side-effect happens or not. |
| Currently, GCC will discard them and issue a warning. |
| |
| @node Case Ranges |
| @section Case Ranges |
| @cindex case ranges |
| @cindex ranges in case statements |
| |
| You can specify a range of consecutive values in a single @code{case} label, |
| like this: |
| |
| @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 though, not a cast, and hence does not yield an lvalue like |
| normal casts. (@xref{Compound Literals}.) |
| |
| The types that may be cast to the union type are those of the members |
| of the union. Thus, given the following union and variables: |
| |
| @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, GCC also allows this in |
| C89 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 |
| |
| 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: |
| @c APPLE LOCAL mainline aligned functions 5933878 |
| @code{aligned}, |
| @code{noreturn}, @code{returns_twice}, @code{noinline}, @code{always_inline}, |
| @c APPLE LOCAL nodebug |
| @code{nodebug}, |
| @c APPLE LOCAL regparmandstackparm |
| @code{regparmandstackparm}, |
| @code{flatten}, @code{pure}, @code{const}, @code{nothrow}, @code{sentinel}, |
| @code{format}, @code{format_arg}, @code{no_instrument_function}, |
| @code{section}, @code{constructor}, @code{destructor}, @code{used}, |
| @code{unused}, @code{deprecated}, @code{weak}, @code{malloc}, |
| @code{alias}, @code{warn_unused_result}, @code{nonnull}, |
| @code{gnu_inline} and @code{externally_visible}. Several other |
| attributes are defined for functions on particular target systems. Other |
| attributes, including @code{section} are supported for variables declarations |
| @c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 |
| (@pxref{Variable Attributes}), for types (@pxref{Type Attributes}), |
| and labels (@pxref{Label Attributes}). |
| |
| @c APPLE LOCAL end for-fsf-4_4 3274130 5295549 |
| 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 |
| |
| 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. |
| |
| @c APPLE LOCAL begin mainline aligned functions 5933878 |
| @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 will override 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}.) |
| @c APPLE LOCAL end mainline aligned functions 5933878 |
| |
| @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 was specified. |
| |
| @item gnu_inline |
| @cindex @code{gnu_inline} function attribute |
| This attribute should be used with a function which is also declared |
| with the @code{inline} keyword. It directs GCC to treat the function |
| as if it were defined in gnu89 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 will cause most calls to the |
| function to be inlined. If any uses of the function remain, they will |
| refer to the single copy in the library. 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. |
| |
| 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}. |
| |
| Note that since the first version of GCC to support C99 inline semantics |
| /* APPLE LOCAL extern inline */ |
| is 4.3 (4.2 for Apple's gcc), earlier versions of GCC which accept this attribute effectively |
| assume that it is always present, whether or not it is given explicitly. |
| /* APPLE LOCAL extern inline */ |
| In versions prior to 4.3 (4.2 for Apple's gcc), the only effect of explicitly including it is |
| to disable warnings about using inline functions in C99 mode. |
| |
| @c APPLE LOCAL begin nodebug |
| @item nodebug |
| @cindex @code{nodebug} function attribute |
| This attribute prevents debug information to be generated for the function. |
| This is to avoid stepping into the function which is of no interest to the |
| user how it is implemented. An example is the x86 vector intrinsics. |
| This is temporary and will be removed in some future version of the compiler. |
| @c APPLE LOCAL end nodebug |
| |
| @cindex @code{flatten} function attribute |
| @item flatten |
| Generally, inlining into a function is limited. For a function marked with |
| this attribute, every call inside this function will be inlined, if possible. |
| Whether the function itself is considered for inlining depends on its size and |
| the current inlining parameters. The @code{flatten} attribute only works |
| reliably in unit-at-a-time mode. |
| |
| @item cdecl |
| @cindex functions that do pop the argument stack on the 386 |
| @opindex mrtd |
| On the Intel 386, the @code{cdecl} attribute causes the compiler to |
| assume that the calling function will pop off the stack space used to |
| pass arguments. This is |
| useful to override the effects of the @option{-mrtd} switch. |
| |
| @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 |
| |
| 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 |
| @cindex @code{constructor} function attribute |
| @cindex @code{destructor} function attribute |
| The @code{constructor} attribute causes the function to be called |
| automatically before execution enters @code{main ()}. Similarly, the |
| @code{destructor} attribute causes the function to be called |
| automatically after @code{main ()} has completed or @code{exit ()} has |
| been called. Functions with these attributes are useful for |
| initializing data that will be used implicitly during the execution of |
| the program. |
| |
| These attributes are not currently implemented for Objective-C@. |
| |
| @item deprecated |
| @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 |
| |
| results in a warning on line 3 but not line 2. |
| |
| The @code{deprecated} attribute can also be used for variables and |
| types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) |
| |
| @item 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, unless a |
| @code{visibility} attribute is explicitly specified. You should avoid |
| the use of @code{dllexport} with ``hidden'' or ``internal'' |
| visibility; in the future GCC may issue an error for those cases. |
| |
| Currently, the @code{dllexport} attribute is ignored for inlined |
| functions, unless the @option{-fkeep-inline-functions} flag has been |
| used. 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} storage. 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. |
| |
| 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 |
| dllimport'ed constructor or a non-inline, non-pure virtual function |
| and, for either of those two conditions, the class also has a inline |
| constructor or destructor and has a key function that is defined in |
| the current translation unit. |
| |
| For Microsoft Windows based 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 function |
| or variable marked as @code{dllimport} cannot be used as a constant |
| address. 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 will generate more efficient code for certain operations |
| on data in the eight bit data area. Note the eight bit data area is limited to |
| 256 bytes of data. |
| |
| You must use GAS and GLD from GNU binutils version 2.7 or later for |
| this attribute to work correctly. |
| |
| @item 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 will generate function entry and |
| exit sequences suitable for use in an exception handler when this |
| attribute is present. |
| |
| @item far |
| @cindex functions which 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 will use the @code{call} and @code{rtc} instructions |
| to call and return from a function. |
| |
| On 68HC11 the compiler will generate 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 will jump to a board-specific routine |
| instead of using @code{rts}. The board-specific return routine simulates |
| the @code{rtc}. |
| |
| @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 will |
| pop the arguments off the stack. If the number of arguments is variable all |
| arguments are pushed on the stack. |
| |
| @item format (@var{archetype}, @var{string-index}, @var{first-to-check}) |
| @cindex @code{format} function attribute |
| @opindex Wformat |
| The @code{format} attribute specifies that a function takes @code{printf}, |
| @code{scanf}, @code{strftime} or @code{strfmon} style arguments which |
| should be type-checked against a format string. For example, the |
| declaration: |
| |
| @smallexample |
| extern int |
| my_printf (void *my_object, const char *my_format, ...) |
| __attribute__ ((format (printf, 2, 3))); |
| @end smallexample |
| |
| @noindent |
| causes the compiler to check the arguments in calls to @code{my_printf} |
| for consistency with the @code{printf} style format string argument |
| @code{my_format}. |
| |
| The parameter @var{archetype} determines how the format string is |
| interpreted, and should be @code{printf}, @code{scanf}, @code{strftime} |
| or @code{strfmon}. (You can also use @code{__printf__}, |
| @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) The |
| parameter @var{string-index} specifies which argument is the format |
| string argument (starting from 1), while @var{first-to-check} is the |
| number of the first argument to check against the format string. For |
| functions where the arguments are not available to be checked (such as |
| @code{vprintf}), specify the third parameter as zero. In this case the |
| compiler only checks the format string for consistency. For |
| @code{strftime} formats, the third parameter is required to be zero. |
| 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 |
| which 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}. |
| |
| The target may 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 which modify format strings, so that GCC can check the |
| calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} |
| type function whose operands are a call to one of your own function. |
| The compiler always treats @code{gettext}, @code{dgettext}, and |
| @code{dcgettext} in this manner except when strict ISO C support is |
| requested by @option{-ansi} or an appropriate @option{-std} option, or |
| @option{-ffreestanding} or @option{-fno-builtin} |
| is used. @xref{C Dialect Options,,Options |
| Controlling C Dialect}. |
| |
| @item function_vector |
| @cindex calling functions through the function vector on the H8/300 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 will reduce code size, however; |
| the function vector has a limited size (maximum 128 entries on the H8/300 |
| and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector. |
| |
| You must use GAS and GLD from GNU binutils version 2.7 or later for |
| this attribute to work correctly. |
| |
| @item interrupt |
| @cindex interrupt handler functions |
| Use this attribute on the ARM, AVR, C4x, CRX, M32C, M32R/D, MS1, and Xstormy16 |
| ports to indicate that the specified function is an interrupt handler. |
| The compiler will generate function entry and exit sequences suitable |
| for use in an interrupt handler when this attribute is present. |
| |
| Note, interrupt handlers for the Blackfin, m68k, H8/300, H8/300H, H8S, and |
| SH processors can be specified via the @code{interrupt_handler} attribute. |
| |
| Note, on the AVR, interrupts will be enabled inside the function. |
| |
| Note, for the ARM, you can specify the kind of interrupt to be handled by |
| adding an optional parameter to the interrupt attribute like this: |
| |
| @smallexample |
| void f () __attribute__ ((interrupt ("IRQ"))); |
| @end smallexample |
| |
| Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@. |
| |
| @item interrupt_handler |
| @cindex interrupt handler functions on the 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 |
| will generate function entry and exit sequences suitable for use in an |
| interrupt handler when this attribute is present. |
| |
| @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 will be generated to load the stack pointer |
| from the USP register in the function prologue. |
| |
| @c APPLE LOCAL prune man page |
| @ignore |
| @item long_call/short_call |
| @cindex indirect calls on ARM |
| This attribute specifies how a particular function is called on |
| ARM@. Both attributes override the @option{-mlong-calls} (@pxref{ARM Options}) |
| command line switch and @code{#pragma long_calls} settings. The |
| @code{long_call} attribute 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. |
| @c APPLE LOCAL prune man page |
| @end ignore |
| |
| @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. |
| |
| @c APPLE LOCAL prune man page |
| @ignore |
| @item long_call |
| @cindex indirect calls on MIPS |
| This attribute specifies how a particular function is called on MIPS@. |
| The attribute overrides the @option{-mlong-calls} (@pxref{MIPS Options}) |
| command line switch. This attribute causes the compiler to always call |
| the function by first loading its address into a register, and then using |
| the contents of that register. |
| @c APPLE LOCAL prune man page |
| @end ignore |
| |
| @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. |
| This will often improve optimization. |
| Standard functions with this property include @code{malloc} and |
| @code{calloc}. @code{realloc}-like functions have this property as |
| long as the old pointer is never referred to (including comparing it |
| to the new pointer) after the function returns a non-@code{NULL} |
| value. |
| |
| @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 will generate @code{seth/add3} instructions to load their addresses), |
| and are callable with the @code{bl} instruction. |
| |
| Large model objects may live anywhere in the 32-bit address space (the |
| compiler will generate @code{seth/add3} instructions to load their addresses), |
| and may not be reachable with the @code{bl} instruction (the compiler will |
| generate the much slower @code{seth/add3/jl} instruction sequence). |
| |
| 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 naked |
| @cindex function without a prologue/epilogue code |
| Use this attribute on the ARM, AVR, C4x and IP2K 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. |
| |
| @item near |
| @cindex functions which 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. |
| |
| @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 will generate 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 will |
| be generated at entry and exit of most user-compiled functions. |
| Functions with this attribute will not be so instrumented. |
| |
| @item noinline |
| @cindex @code{noinline} function attribute |
| This function attribute prevents a function from being considered for |
| inlining. |
| |
| @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 not 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 |
| |
| 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 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 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 will 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 will send 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. |
| GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be |
| safe since the loaders there save all registers. (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 will 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 runtime stack. 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. The alternate |
| prologue and epilogue are slower and bigger than the regular ones, and |
| the alternate prologue requires a scratch register; this lowers the |
| number of registers available if used in conjunction with the |
| @code{regparm} attribute. The @code{force_align_arg_pointer} |
| attribute is incompatible with nested functions; this is considered a |
| hard error. |
| |
| @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 will ensure that all registers |
| are dead before calling such a function and will emit 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 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 long_call/short_call. |
| |
| @item shortcall |
| See longcall/shortcall. |
| |
| @item signal |
| @cindex signal handler functions on the AVR processors |
| Use this attribute on the AVR to indicate that the specified |
| function is a signal handler. The compiler will generate function |
| entry and exit sequences suitable for use in a signal handler when this |
| attribute is present. Interrupts will be disabled inside the function. |
| |
| @c APPLE LOCAL begin regparmandstackparm |
| @item regparmandstackparm |
| |
| This is an X86_32-specific attribute. |
| |
| Two entry points will be created for this function. One will have the |
| traditional calling convention, and the other will have a mangled name |
| and a register-based calling convention. |
| |
| The register-based calling convention will pass up to four float or |
| double values in XMM registers, and up to two integral values in |
| integer registers. Long double values are still passed on the stack, |
| and functions returning long double will still use the x87 stacktop. |
| |
| Other modules linked with this function may use either entry point. |
| If a calling module has seen an extern declaration with the |
| @code{regparmandstackparm} attribute, it will call the register-based |
| entry point; otherwise, it will use the traditional entry point in the |
| usual way. |
| |
| When taking the address of a @code{regparmandstackparm} function, the |
| address of the traditional entry point will be used. Calls through |
| function pointers always use the traditional calling convention. |
| |
| The mangled name is currently created by appending ``$3SSE'' to the |
| original function name (before any C++ name-mangling), but users |
| should not rely upon this. |
| |
| The current implementation associates the original function body with |
| the register-based entry point. The traditional entry point will load |
| some registers from the stack and call the register-based entry point. |
| This means the traditional entry point will be slightly less efficient |
| than a function without the @code{regparmandstackparm} attribute, and the |
| generated code will be slightly larger. Depending upon sizes and |
| optimization levels, the inliner may inline the register-based body |
| into the traditional entry point; nothing is done to preclude this. |
| If the function was declared @code{static}, optimization may discard |
| the original entry point entirely. |
| |
| @smallexample |
| extern double __attribute__ ((regparmandstackparm)) my_cos (double d); |
| @end smallexample |
| @c APPLE LOCAL end regparmandstackparm |
| |
| @item sp_switch |
| Use this attribute on the SH to indicate an @code{interrupt_handler} |
| function should switch to an alternate stack. It expects a string |
| argument that names a global variable holding the address of the |
| alternate stack. |
| |
| @smallexample |
| void *alt_stack; |
| void f () __attribute__ ((interrupt_handler, |
| sp_switch ("alt_stack"))); |
| @end smallexample |
| |
| @item stdcall |
| @cindex functions that pop the argument stack on the 386 |
| On the Intel 386, the @code{stdcall} attribute causes the compiler to |
| assume that the called function will pop off the stack space used to |
| pass arguments, unless it takes a variable number of arguments. |
| |
| @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 will generate more efficient code for loads and stores |
| on data in the tiny data section. Note the tiny data area is limited to |
| slightly under 32kbytes of data. |
| |
| @item trap_exit |
| 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 unused |
| @cindex @code{unused} attribute. |
| This attribute, attached to a function, means that the function is meant |
| to be possibly unused. GCC will not produce a warning for this |
| function. |
| |
| @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. |
| |
| @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 will have a new |
| form of linkage, which we'll 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 will 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 which |
| 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 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 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 |
| |
| 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 which can be overridden in user code, though it can |
| also be used with non-function declarations. Weak symbols are supported |
| for ELF targets, and also for a.out targets when using the GNU assembler |
| and linker. |
| |
| @item 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 the becomes a @code{weak} |
| undefined symbol. If it is directly referenced, however, then such |
| strong references prevail, and a definition will be 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}. |
| |
| @item externally_visible |
| @cindex @code{externally_visible} attribute. |
| This attribute, attached to a global variable or function nullify |
| effect of @option{-fwhole-program} command line option, so the object |
| remain visible outside the current compilation unit |
| |
| @end table |
| |
| You can specify multiple attributes in a declaration by separating them |
| by commas within the double parentheses or by immediately following an |
| attribute declaration with another attribute declaration. |
| |
| @cindex @code{#pragma}, reason for not using |
| @cindex pragma, reason for not using |
| Some people object to the @code{__attribute__} feature, suggesting that |
| ISO C's @code{#pragma} should be used instead. At the time |
| @code{__attribute__} was designed, there were two reasons for not doing |
| this. |
| |
| @enumerate |
| @item |
| It is impossible to generate @code{#pragma} commands from a macro. |
| |
| @item |
| There is no telling what the same @code{#pragma} might mean in another |
| compiler. |
| @end enumerate |
| |
| These two reasons applied to almost any application that might have been |
| proposed for @code{#pragma}. It was basically a mistake to use |
| @code{#pragma} for @emph{anything}. |
| |
| The ISO C99 standard includes @code{_Pragma}, which now allows pragmas |
| to be generated from macros. In addition, a @code{#pragma GCC} |
| namespace is now in use for GCC-specific pragmas. However, it has been |
| found convenient to use @code{__attribute__} to achieve a natural |
| attachment of attributes to their corresponding declarations, whereas |
| @code{#pragma GCC} is of use for constructs that do not naturally form |
| part of the grammar. @xref{Other Directives,,Miscellaneous |
| Preprocessing Directives, cpp, The GNU C Preprocessor}. |
| |
| @node Attribute Syntax |
| @section Attribute Syntax |
| @cindex attribute syntax |
| |
| This section describes the syntax with which @code{__attribute__} may be |
| used, and the constructs to which attribute specifiers bind, for the C |
| language. Some details may vary for C++ and Objective-C@. Because of |
| infelicities in the grammar for attributes, some forms described here |
| may not be successfully parsed in all cases. |
| |
| There are some problems with the semantics of attributes in C++. For |
| example, there are no manglings for attributes, although they may affect |
| code generation, so problems may arise when attributed types are used in |
| conjunction with templates or overloading. Similarly, @code{typeid} |
| does not distinguish between types with different attributes. Support |
| for attributes in C++ may be restricted in future to attributes on |
| declarations only, but not on nested declarators. |
| |
| @xref{Function Attributes}, for details of the semantics of attributes |
| applying to functions. @xref{Variable Attributes}, for details of the |
| @c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 |
| semantics of attributes applying to variables. @xref{Type |
| Attributes}, for details of the semantics of attributes applying to |
| structure, union and enumerated types. @xref{Label Attributes}, for |
| details of the semantics of attributes applying to labels and |
| statements. |
| |
| @c APPLE LOCAL end for-fsf-4_4 3274130 5295549 |
| 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. |
| |
| @c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 |
| In GNU C, an attribute specifier list may appear after the colon |
| following a label, other than a @code{case} or @code{default} label. |
| GNU C++ does not permit such placement of attribute lists, 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. |
| |
| In GNU C an attribute specifier list may also appear after the keyword |
| @code{while} in a while loop, after @code{do} and after @code{for}. |
| |
| @c APPLE LOCAL end for-fsf-4_4 3274130 5295549 |
| 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 which 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. At present, such attribute specifiers apply |
| to the declared object or function, but in future they may attach to the |
| outermost adjacent declarator. In simple cases there is no difference, |
| but, for example, in |
| |
| @smallexample |
| void (****f)(void) __attribute__((noreturn)); |
| @end smallexample |
| |
| @noindent |
| at present the @code{noreturn} attribute applies to @code{f}, which |
| causes a warning since @code{f} is not a function, but in future it may |
| apply to the function @code{****f}. The precise semantics of what |
| attributes in such cases will apply to are not yet specified. Where an |
| assembler name for an object or function is specified (@pxref{Asm |
| Labels}), at present the attribute must follow the @code{asm} |
| specification; in future, attributes before the @code{asm} specification |
| may apply to the adjacent declarator, and those after it to the declared |
| object or function. |
| |
| An attribute specifier list may, in future, be permitted to appear after |
| the declarator in a function definition (before any old-style parameter |
| declarations or the function body). |
| |
| Attribute specifiers may be mixed with type qualifiers appearing inside |
| the @code{[]} of a parameter array declarator, in the C99 construct by |
| which such qualifiers are applied to the pointer to which the array is |
| implicitly converted. Such attribute specifiers apply to the pointer, |
| not to the array, but at present this is not implemented and they are |
| ignored. |
| |
| An attribute specifier list may appear at the start of a nested |
| declarator. At present, there are some limitations in this usage: the |
| attributes correctly apply to the declarator, but for most individual |
| attributes the semantics this implies are not implemented. |
| When attribute specifiers follow the @code{*} of a pointer |
| declarator, they may be mixed with any type qualifiers present. |
| The following describes the formal semantics of this syntax. It will make the |
| most sense if you are familiar with the formal specification of |
| declarators in the ISO C standard. |
| |
| Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T |
| D1}, where @code{T} contains declaration specifiers that specify a type |
| @var{Type} (such as @code{int}) and @code{D1} is a declarator that |
| contains an identifier @var{ident}. The type specified for @var{ident} |
| for derived declarators whose type does not include an attribute |
| specifier is as in the ISO C standard. |
| |
| If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, |
| and the declaration @code{T D} specifies the type |
| ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then |
| @code{T D1} specifies the type ``@var{derived-declarator-type-list} |
| @var{attribute-specifier-list} @var{Type}'' for @var{ident}. |
| |
| If @code{D1} has the form @code{* |
| @var{type-qualifier-and-attribute-specifier-list} D}, and the |
| declaration @code{T D} specifies the type |
| ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then |
| @code{T D1} specifies the type ``@var{derived-declarator-type-list} |
| @var{type-qualifier-and-attribute-specifier-list} @var{Type}'' for |
| @var{ident}. |
| |
| For example, |
| |
| @smallexample |
| void (__attribute__((noreturn)) ****f) (void); |
| @end smallexample |
| |
| @noindent |
| specifies the type ``pointer to pointer to pointer to pointer to |
| non-returning function returning @code{void}''. As another example, |
| |
| @smallexample |
| char *__attribute__((aligned(8))) *f; |
| @end smallexample |
| |
| @noindent |
| specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. |
| Note again that this does not work with most attributes; for example, |
| the usage of @samp{aligned} and @samp{noreturn} attributes given above |
| is not yet supported. |
| |
| For compatibility with existing code written for compiler versions that |
| did not implement attributes on nested declarators, some laxity is |
| allowed in the placing of attributes. If an attribute that only applies |
| to types is applied to a declaration, it will be treated as applying to |
| the type of that declaration. If an attribute that only applies to |
| declarations is applied to the type of a declaration, it will be treated |
| as applying to that declaration; and, for compatibility with code |
| placing the attributes immediately before the identifier declared, such |
| an attribute applied to a function return type will be treated as |
| applying to the function type, and such an attribute applied to an array |
| element type will be treated as applying to the array type. If an |
| attribute that only applies to function types is applied to a |
| pointer-to-function type, it will be treated as applying to the pointer |
| target type; if such an attribute is applied to a function return type |
| that is not a pointer-to-function type, it will be treated as applying |
| to the function type. |
| |
| @node Function Prototypes |
| @section Prototypes and Old-Style Function Definitions |
| @cindex function prototype declarations |
| @cindex old-style function definitions |
| @cindex promotion of formal parameters |
| |
| GNU C extends ISO C to allow a function prototype to override a later |
| old-style non-prototype definition. Consider the following example: |
| |
| @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 // |
| @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=c89}). |
| |
| @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}. |
| |
| @c APPLE LOCAL begin pascal strings |
| @node Pascal Strings |
| @section Constructing String Literals with a Pascal-style Length Byte |
| @cindex Pascal length byte |
| @cindex Pascal strings |
| |
| Specifying the @w{@option{-fpascal-strings}} option will cause the |
| compiler to recognize and construct Pascal-style string literals. This |
| functionality is disabled by default; furthermore, its use in new code |
| is discouraged. |
| |
| Pascal string literals take the form @samp{"\pstring"}. The special |
| escape sequence @samp{\p} denotes the Pascal length byte for the string, |
| and will be replaced at compile time with the number of characters that |
| follow. The @samp{\p} may only appear at the beginning of a string |
| literal, and may @emph{not} appear in wide string literals or as an |
| integral constant. |
| |
| As is the case with C string literals, Pascal string literals are |
| terminated with a NUL character; this character is @emph{not} counted |
| when computing the value of the length byte. The maximum @samp{unsigned |
| char} value that can be stored in the length byte is also the maximum |
| permissible length for the Pascal literal itself. On most target |
| platforms, this value is 255 (excluding both the length byte and the |
| terminating NUL). |
| |
| Pascal-style literals are treated by the compiler as being of type |
| @samp{const unsigned char []} in C++ and @samp{unsigned char []} (or |
| @samp{const unsigned char []}, if the @w{@option{-Wwrite-strings}} |
| option is given) in C. Pascal string literals may be used as static |
| initializers for @samp{char} arrays (whose elements need not be |
| @samp{unsigned} or @samp{const}). They may also be converted to |
| @samp{const unsigned char *} and, in the C language to @samp{const char |
| *} of any signedness (In C, if the @w{@option{-Wwrite-strings}} is not |
| given, then @samp{const} may be omitted as well). For example: |
| |
| @example |
| const unsigned char a[] = "\pHello"; |
| char b[] = "\pGoodbye"; |
| const unsigned char *c = "\pHello"; |
| const signed char *d = "\pHello"; /* error in C++ */ |
| char *e = "\pHi"; /* error in C++; warning in C with -Wwrite-strings */ |
| unsigned char *f = "\pHello"; /* error in C++ */ |
| @end example |
| |
| @noindent |
| In all other respects, Pascal-style string literals behave the same as |
| ordinary string literals. For example, if a program attempts to modify |
| the conents of a Pascal-style string literal at run-time, the behaviour |
| is undefined, unless the @w{@option{-fwritable-strings}} option is used. |
| |
| Pascal-style literals are useful for calling external routines that |
| expect Pascal strings as arguments, as is true with some Apple MacOS |
| Toolbox calls. |
| @c APPLE LOCAL end pascal strings |
| |
| @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 @emph{recommended} alignment of a type. |
| |
| If the operand of @code{__alignof__} is an lvalue rather than a type, |
| its value is the required alignment for its type, taking into account |
| any minimum alignment specified with GCC's @code{__attribute__} |
| extension (@pxref{Variable Attributes}). For example, after this |
| declaration: |
| |
| @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 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 |
| @c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 |
| (@pxref{Function Attributes}), types (@pxref{Type Attributes}) and |
| labels (@pxref{Label Attributes}). Other front ends might define |
| more attributes (@pxref{C++ Extensions,,Extensions to the C++ Language}). |
| |
| @c APPLE LOCAL end for-fsf-4_4 3274130 5295549 |
| You may also specify attributes with @samp{__} preceding and following |
| each keyword. This allows you to use them in header files without |
| being concerned about a possible macro of the same name. For example, |
| you may use @code{__aligned__} instead of @code{aligned}. |
| |
| @xref{Attribute Syntax}, for details of the exact syntax for using |
| attributes. |
| |
| @table @code |
| @cindex @code{aligned} attribute |
| @item aligned (@var{alignment}) |
| This attribute specifies a minimum alignment for the variable or |
| structure field, measured in bytes. For example, the declaration: |
| |
| @smallexample |
| int x __attribute__ ((aligned (16))) = 0; |
| @end smallexample |
| |
| @noindent |
| causes the compiler to allocate the global variable @code{x} on a |
| 16-byte boundary. On a 68040, this could be used in conjunction with |
| an @code{asm} expression to access the @code{move16} instruction which |
| requires 16-byte aligned operands. |
| |
| You can also specify the alignment of structure fields. For example, to |
| create a double-word aligned @code{int} pair, you could write: |
| |
| @smallexample |
| struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; |
| @end smallexample |
| |
| @noindent |
| This is an alternative to creating a union with a @code{double} member |
| that forces the union to be double-word aligned. |
| |
| As in the preceding examples, you can explicitly specify the alignment |
| (in bytes) that you wish the compiler to use for a given variable or |
| structure field. Alternatively, you can leave out the alignment factor |
| and just ask the compiler to align a variable or field to the maximum |
| useful alignment for the target machine you are compiling for. For |
| example, you could write: |
| |
| @smallexample |
| short array[3] __attribute__ ((aligned)); |
| @end smallexample |
| |
| Whenever you leave out the alignment factor in an @code{aligned} attribute |
| specification, the compiler automatically sets the alignment for the declared |
| variable or field to the largest alignment which is ever used for any data |
| type on the target machine you are compiling for. Doing this can often make |
| copy operations more efficient, because the compiler can use whatever |
| instructions copy the biggest chunks of memory when performing copies to |
| or from the variables or fields that you have aligned this way. |
| |
| The @code{aligned} attribute can only increase the alignment; but you |
| can decrease it by specifying @code{packed} as well. See below. |
| |
| Note that the effectiveness of @code{aligned} attributes may be limited |
| by inherent limitations in your linker. On many systems, the linker is |
| only able to arrange for variables to be aligned up to a certain maximum |
| alignment. (For some linkers, the maximum supported alignment may |
| be very very small.) If your linker is only able to align variables |
| up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} |
| in an @code{__attribute__} will still only provide you with 8 byte |
| alignment. See your linker documentation for further information. |
| |
| @c APPLE LOCAL begin aligned functions 5933878 |
| The @code{aligned} attribute can also be used for functions |
| (@pxref{Function Attributes}.) |
| @c APPLE LOCAL end aligned functions 5933878 |
| |
| @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} |
| will be 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 |
| @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 |
| |
| results in a warning on line 3 but not line 2. |
| |
| The @code{deprecated} attribute can also be used for functions and |
| types (@pxref{Function Attributes}, @pxref{Type Attributes}.) |
| |
| @item mode (@var{mode}) |
| @cindex @code{mode} attribute |
| This attribute specifies the data type for the declaration---whichever |
| type corresponds to the mode @var{mode}. This in effect lets you |
| request an integer or floating point type according to its width. |
| |
| You may also specify a mode of @samp{byte} or @samp{__byte__} to |
| indicate the mode corresponding to a one-byte integer, @samp{word} or |
| @samp{__word__} for the mode of a one-word integer, and @samp{pointer} |
| or @samp{__pointer__} for the mode used to represent pointers. |
| |
| @item 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 |
| |
| @item section ("@var{section-name}") |
| @cindex @code{section} variable attribute |
| Normally, the compiler places the objects it generates in sections like |
| @code{data} and @code{bss}. Sometimes, however, you need additional sections, |
| or you need certain particular variables to appear in special sections, |
| for example to map to special hardware. The @code{section} |
| attribute specifies that a variable (or function) lives in a particular |
| section. For example, this small program uses several specific section names: |
| |
| @smallexample |
| struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; |
| struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; |
| char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; |
| int init_data __attribute__ ((section ("INITDATA"))) = 0; |
| |
| main() |
| @{ |
| /* @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 an @emph{initialized} definition |
| of a @emph{global} variable, as shown in the example. GCC issues |
| a warning and otherwise ignores the @code{section} attribute in |
| uninitialized variable declarations. |
| |
| You may only use the @code{section} attribute with a fully initialized |
| global definition because of the way linkers work. The linker requires |
| each object be defined once, with the exception that uninitialized |
| variables tentatively go in the @code{common} (or @code{bss}) section |
| and can be multiply ``defined''. You can force a variable to be |
| initialized with the @option{-fno-common} flag or the @code{nocommon} |
| attribute. |
| |
| Some file formats do not support arbitrary sections so the @code{section} |
| attribute is not available on all platforms. |
| If you need to map the entire contents of a module to a particular |
| section, consider using the facilities of the linker instead. |
| |
| @item shared |
| @cindex @code{shared} variable attribute |
| On 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 will 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. |
| |
| @item vector_size (@var{bytes}) |
| This attribute specifies the vector size for the variable, measured in |
| bytes. For example, the declaration: |
| |
| @smallexample |
| int foo __attribute__ ((vector_size (16))); |
| @end smallexample |
| |
| @noindent |
| causes the compiler to set the mode for @code{foo}, to be 16 bytes, |
| divided into @code{int} sized units. Assuming a 32-bit int (a vector of |
| 4 units of 4 bytes), the corresponding mode of @code{foo} will be V4SI@. |
| |
| This attribute is only applicable to integral and float scalars, |
| although arrays, pointers, and function return values are allowed in |
| conjunction with this construct. |
| |
| Aggregates with this attribute are invalid, even if they are of the same |
| size as a corresponding scalar. For example, the declaration: |
| |
| @smallexample |
| struct S @{ int a; @}; |
| struct S __attribute__ ((vector_size (16))) foo; |
| @end smallexample |
| |
| @noindent |
| is invalid even if the size of the structure is the same as the size of |
| the @code{int}. |
| |
| @item 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 @xref{Function Attributes}. |
| |
| @item dllimport |
| The @code{dllimport} attribute is described in @xref{Function Attributes}. |
| |
| @item dllexport |
| The @code{dllexport} attribute is described in @xref{Function Attributes}. |
| |
| @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 will generate @code{seth/add3} instructions to load their |
| addresses). |
| @end table |
| |
| @c APPLE LOCAL begin 5946347 ms_struct support |
| @anchor{PowerPC Variable Attributes} |
| @subsection PowerPC Variable Attributes |
| |
| One is defined for PowerPC configurations: @code{altivec}. |
| |
| For documentation of the @code{altivec} attribute please see the |
| documentation in the @xref{PowerPC Type Attributes}, section. |
| @c APPLE LOCAL end 5946347 ms_struct support |
| |
| @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 will place the variable in the first 0x100 bytes of |
| memory and use special opcodes to access it. Such variables will be |
| 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 |
| @c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 |
| (@pxref{Function Attributes}), variables (@pxref{Variable |
| Attributes}), and labels (@pxref{Label Attributes}). |
| |
| @c APPLE LOCAL end for-fsf-4_4 3274130 5295549 |
| 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 either in a @code{typedef} declaration |
| or in an enum, struct or union type declaration or definition. |
| |
| 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 insure (as far as it can) that each variable whose |
| type is @code{struct S} or @code{more_aligned_int} will be allocated and |
| aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all |
| variables of type @code{struct S} aligned to 8-byte boundaries allows |
| the compiler to use the @code{ldd} and @code{std} (doubleword load and |
| store) instructions when copying one variable of type @code{struct S} to |
| another, thus improving run-time efficiency. |
| |
| Note that the alignment of any given @code{struct} or @code{union} type |
| is required by the ISO C standard to be at least a perfect multiple of |
| the lowest common multiple of the alignments of all of the members of |
| the @code{struct} or @code{union} in question. This means that you @emph{can} |
| effectively adjust the alignment of a @code{struct} or @code{union} |
| type by attaching an @code{aligned} attribute to any one of the members |
| of such a type, but the notation illustrated in the example above is a |
| more obvious, intuitive, and readable way to request the compiler to |
| adjust the alignment of an entire @code{struct} or @code{union} type. |
| |
| As in the preceding example, you can explicitly specify the alignment |
| (in bytes) that you wish the compiler to use for a given @code{struct} |
| or @code{union} type. Alternatively, you can leave out the alignment factor |
| and just ask the compiler to align a type to the maximum |
| useful alignment for the target machine you are compiling for. For |
| example, you could write: |
| |
| @smallexample |
| struct S @{ short f[3]; @} __attribute__ ((aligned)); |
| @end smallexample |
| |
| Whenever you leave out the alignment factor in an @code{aligned} |
| attribute specification, the compiler automatically sets the alignment |
| for the type to the largest alignment which is ever used for any data |
| type on the target machine you are compiling for. Doing this can often |
| make copy operations more efficient, because the compiler can use |
| whatever instructions copy the biggest chunks of memory when performing |
| copies to or from the variables which have types that you have aligned |
| this way. |
| |
| In the example above, if the size of each @code{short} is 2 bytes, then |
| the size of the entire @code{struct S} type is 6 bytes. The smallest |
| power of two which is greater than or equal to that is 8, so the |
| compiler sets the alignment for the entire @code{struct S} type to 8 |
| bytes. |
| |
| Note that although you can ask the compiler to select a time-efficient |
| alignment for a given type and then declare only individual stand-alone |
| objects of that type, the compiler's ability to select a time-efficient |
| alignment is primarily useful only when you plan to create arrays of |
| variables having the relevant (efficiently aligned) type. If you |
| declare or use arrays of variables of an efficiently-aligned type, then |
| it is likely that your program will also be doing pointer arithmetic (or |
| subscripting, which amounts to the same thing) on pointers to the |
| relevant type, and the code that the compiler generates for these |
| pointer arithmetic operations will often be more efficient for |
| efficiently-aligned types than for other types. |
| |
| The @code{aligned} attribute can only increase the alignment; but you |
| can decrease it by specifying @code{packed} as well. See below. |
| |
| Note that the effectiveness of @code{aligned} attributes may be limited |
| by inherent limitations in your linker. On many systems, the linker is |
| only able to arrange for variables to be aligned up to a certain maximum |
| alignment. (For some linkers, the maximum supported alignment may |
| be very very small.) If your linker is only able to align variables |
| up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} |
| in an @code{__attribute__} will still only provide you with 8 byte |
| alignment. See your linker documentation for further information. |
| |
| @item packed |
| This attribute, attached to @code{struct} or @code{union} type |
| definition, specifies that each member (other than zero-width bitfields) |
| 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} would need 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 a @code{enum}, |
| @code{struct} or @code{union}, not on a @code{typedef} which 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 |
| @{ |
| int *__ip; |
| union wait *__up; |
| @} wait_status_ptr_t __attribute__ ((__transparent_union__)); |
| |
| pid_t wait (wait_status_ptr_t); |
| @end smallexample |
| |
| This interface allows either @code{int *} or @code{union wait *} |
| arguments to be passed, using the @code{int *} calling convention. |
| The program can call @code{wait} with arguments of either type: |
| |
| @smallexample |
| int w1 () @{ int w; return wait (&w); @} |
| int w2 () @{ union wait w; return wait (&w); @} |
| @end smallexample |
| |
| 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 will not produce a warning for any variables of |
| that type, even if the variable appears to do nothing. This is often |
| the case with lock or thread classes, which are usually defined and then |
| not referenced, but contain constructors and destructors that have |
| nontrivial bookkeeping functions. |
| |
| @item deprecated |
| The @code{deprecated} attribute results in a warning if the type |
| is used anywhere in the source file. This is useful when identifying |
| types that are expected to be removed in a future version of a program. |
| If possible, the warning also includes the location of the declaration |
| of the deprecated type, to enable users to easily find further |
| information about why the type is deprecated, or what they should do |
| instead. Note that the warnings only occur for uses and then only |
| if the type is being applied to an identifier that itself is not being |
| declared as deprecated. |
| |
| @smallexample |
| typedef int T1 __attribute__ ((deprecated)); |
| T1 x; |
| typedef T1 T2; |
| T2 y; |
| typedef T1 T3 __attribute__ ((deprecated)); |
| T3 z __attribute__ ((deprecated)); |
| @end smallexample |
| |
| results in a warning on line 2 and 3 but not lines 4, 5, or 6. No |
| warning is issued for line 4 because T2 is not explicitly |
| deprecated. Line 5 has no warning because T3 is explicitly |
| deprecated. Similarly for line 6. |
| |
| The @code{deprecated} attribute can also be used for functions and |
| variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) |
| |
| @item may_alias |
| Accesses to objects with types with this attribute are not subjected to |
| type-based alias analysis, but are instead assumed to be able to alias |
| any other type of objects, just like the @code{char} type. See |
| @option{-fstrict-aliasing} for more information on aliasing issues. |
| |
| 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 |
| |
| 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 will be unable to use the same |
| typeinfo node and exception handling will break. |
| |
| @c APPLE LOCAL begin weak types 5954418 |
| @item weak |
| In C++, attribute weak can be applied to a class to ensure that all |
| non-hidden instances of the type are treated as the same type across |
| shared library boundaries on platforms (such as darwin and arm aapcs) |
| that can emit vtables and the type info meta data as non-comdat |
| symbols. This is useful when the class has a key method and the |
| translation unit that contains the key method is used in more than one |
| shared library or in a shared library and the application. Doing this |
| results in more expensive startup times. This attribute is inherited |
| by subclasses, so it is only necessary to mark a base type. The |
| typical use would be to mark any types used for throwing across shared |
| library boundaries or those used in dynamic_cast operations across a |
| shared library boundary. |
| @c APPLE LOCAL end weak types 5954418 |
| |
| @c APPLE LOCAL begin 5946347 ms_struct support |
| @end table |
| |
| To specify multiple attributes, separate them by commas within the |
| double parentheses: for example, @samp{__attribute__ ((aligned (16), |
| packed))}. |
| |
| @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} 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 packs them differently |
| than GCC would normally pack 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. |
| |
| The Microsoft structure layout algorithm is fairly simple with the exception |
| of the bitfield packing: |
| |
| The padding and alignment of members of structures and whether a bit field |
| can straddle a storage-unit boundary |
| |
| @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 aligned attribute |
| or the 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: |
| |
| offset % alignment-requirement == 0 |
| |
| @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 |
| |
| Handling of zero-length bitfields: |
| |
| MSVC interprets zero-length bitfields in the following ways: |
| |
| @enumerate |
| @item If a zero-length bitfield is inserted between two bitfields that would |
| normally be coalesced, the bitfields will not be coalesced. |
| |
| For example: |
| |
| @smallexample |
| struct |
| @{ |
| unsigned long bf_1 : 12; |
| unsigned long : 0; |
| unsigned long bf_2 : 12; |
| @} t1; |
| @end smallexample |
| |
| The size of @code{t1} would be 8 bytes with the zero-length bitfield. If the |
| zero-length bitfield were removed, @code{t1}'s size would be 4 bytes. |
| |
| @item If a zero-length bitfield is inserted after a bitfield, @code{foo}, and the |
| alignment of the zero-length bitfield is greater than the member that follows it, |
| @code{bar}, @code{bar} will be aligned as the type of the zero-length bitfield. |
| |
| For example: |
| |
| @smallexample |
| struct |
| @{ |
| char foo : 4; |
| short : 0; |
| char bar; |
| @} t2; |
| |
| struct |
| @{ |
| char foo : 4; |
| short : 0; |
| double bar; |
| @} t3; |
| @end smallexample |
| |
| For @code{t2}, @code{bar} will be placed at offset 2, rather than offset 1. |
| Accordingly, the size of @code{t2} will be 4. For @code{t3}, the zero-length |
| bitfield will 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 bitfield follows a normal bitfield, the type of the |
| zero-length bitfield may affect the alignment of the structure as whole. For |
| example, @code{t2} has a size of 4 bytes, since the zero-length bitfield follows a |
| normal bitfield, and is of type short. |
| |
| @item Even if a zero-length bitfield is not followed by a normal bitfield, it may |
| still affect the alignment of the structure: |
| |
| @smallexample |
| struct |
| @{ |
| char foo : 6; |
| long : 0; |
| @} t4; |
| @end smallexample |
| |
| Here, @code{t4} will take up 4 bytes. |
| @end enumerate |
| |
| @item Zero-length bitfields following non-bitfield members are ignored: |
| |
| @smallexample |
| struct |
| @{ |
| char foo; |
| long : 0; |
| char bar; |
| @} t5; |
| @end smallexample |
| |
| Here, @code{t5} will take up 2 bytes. |
| @end enumerate |
| @end table |
| |
| @anchor{ARM Type Attributes} |
| @subsection ARM Type Attributes |
| |
| Two attributes currently are defined for ARM configurations: |
| @code{ms_struct} and @code{gcc_struct}. |
| |
| For full documentation of the struct attributes please see the |
| documentation in the @xref{i386 Type Attributes}, section. |
| |
| 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 |
| |
| 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}.) |
| @c APPLE LOCAL end 5946347 ms_struct support |
| |
| @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 struct attributes please see the |
| documentation in the @xref{i386 Type Attributes}, section. |
| |
| 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. |
| |
| @c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 |
| @node Label Attributes |
| @section Specifying Attributes of Labels and Statements |
| @cindex attribute of labels |
| @cindex label attributes |
| @cindex attribute of statements |
| @cindex statement attributes |
| |
| The keyword @code{__attribute__} allows you to specify special |
| attributes of labels and statements. |
| |
| 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}), types (@pxref{Type Attributes}) and |
| variables (@pxref{Variable 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{__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 label, |
| measured in bytes. For example, the declaration: |
| |
| @smallexample |
| some_label: __attribute__((aligned(16))) |
| @end smallexample |
| |
| @noindent |
| requests the compiler to align the label, inserting @code{nop}s as necessary, |
| to a 16-byte boundary. |
| |
| The alignment is only a request. The compiler will usually be able to |
| honour it but sometimes the label will be eliminated by the compiler, |
| in which case its alignment will be eliminated too. |
| |
| When applied to loops, the @code{aligned} attribute causes the loop to |
| be aligned. |
| |
| @item unused |
| When attached to a label this attribute means that the label might not |
| be used. GCC will not produce a warning for the label, even if the |
| label doesn't seem to be referenced. This feature is intended for |
| code generated by programs which contains labels that may be unused |
| but which is compiled with @option{-Wall}. It would not normally be |
| appropriate to use in it human-written code, though it could be useful |
| in cases where the code that jumps to the label is contained within an |
| @code{#ifdef} conditional. |
| |
| This attribute can only be applied to labels, not statements, because |
| there is no warning if a statement is removed. |
| @end table |
| |
| @c APPLE LOCAL end for-fsf-4_4 3274130 5295549 |
| @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 |
| |
| @c APPLE LOCAL begin mainline 4.3 2006-10-31 4134307 |
| 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} or |
| @option{-std=gnu99} (without @option{-fgnu89-inline}), and the third |
| is used when compiling C++. |
| |
| @c APPLE LOCAL begin Ians 4.2 wording for extern inline |
| The preprocessor macros |
| @code{__GNUC_GNU_INLINE__} and @code{__GNUC_STDC_INLINE__} may be used |
| to determine the handling of @code{inline} during a particular |
| compilation (@pxref{Common Predefined Macros,,,cpp,The C |
| Preprocessor}). |
| @c APPLE LOCAL end Ians 4.2 wording for extern inline |
| |
| To declare a function inline, use the @code{inline} keyword in its |
| declaration, like this: |
| |
| @smallexample |
| static inline int |
| inc (int *a) |
| @{ |
| (*a)++; |
| @} |
| @end smallexample |
| |
| If you are writing a header file to be included in ISO C89 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) |
| @{ |
| (*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: use of varargs, use of |
| alloca, use of variable sized data types (@pxref{Variable Length}), |
| use of computed goto (@pxref{Labels as Values}), use of nonlocal goto, |
| and nested functions (@pxref{Nested Functions}). Using @option{-Winline} |
| will warn when a function marked @code{inline} could not be substituted, |
| and will give the reason for the failure. |
| |
| @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 C89 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 will cause most calls to the function |
| to be inlined. If any uses of the function remain, they will refer to |
| the single copy in the library. |
| @c APPLE LOCAL end mainline 4.3 2006-10-31 4134307 |
| |
| 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 |
| |
| @node Extended Asm |
| @section Assembler Instructions with C Expression Operands |
| @cindex extended @code{asm} |
| @cindex @code{asm} expressions |
| @cindex assembler instructions |
| @cindex registers |
| |
| In an assembler instruction using @code{asm}, you can specify the |
| operands of the instruction using C expressions. This means you need not |
| guess which registers or memory locations will contain the data you want |
| to use. |
| |
| You must specify an assembler instruction template much like what |
| appears in a machine description, plus an operand constraint string for |
| each operand. |
| |
| For example, here is how to use the 68881's @code{fsinx} instruction: |
| |
| @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 |
| will use the register as the output of the @code{asm}, and then store |
| that register into the output. |
| |
| The ordinary output operands must be write-only; GCC will assume that |
| the values in these operands before the instruction are dead and need |
| not be generated. Extended asm supports input-output or read-write |
| operands. Use the constraint character @samp{+} to indicate such an |
| operand and list it with the output operands. You should only use |
| read-write operands when the constraints for the operand (or the |
| operand in which only some of the bits are to be changed) allow a |
| register. |
| |
| You may, as an alternative, logically split its function into two |
| separate operands, one input operand and one write-only output |
| operand. The connection between them is expressed by constraints |
| which say they need to be in the same location when the instruction |
| executes. You can use the same C expression for both operands, or |
| different expressions. For example, here we write the (fictitious) |
| @samp{combine} instruction with @code{bar} as its read-only source |
| operand and @code{foo} as its read-write destination: |
| |
| @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 will be in |
| the same place as another. The mere fact that @code{foo} is the value |
| of both operands is not enough to guarantee that they will be in the |
| same place in the generated assembler code. The following would not |
| work reliably: |
| |
| @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. |
| 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 will then also need to specify |
| @code{volatile} for the @code{asm} construct, as described below, to |
| prevent GCC from deleting the @code{asm} statement as unused. |
| |
| If you refer to a particular hardware register from the assembler code, |
| you will probably have to list the register after the third colon to |
| tell the compiler the register's value is modified. In some assemblers, |
| the register names begin with @samp{%}; to produce one @samp{%} in the |
| assembler code, you must write @samp{%%} in the input. |
| |
| If your assembler instruction can alter the condition code register, add |
| @samp{cc} to the list of clobbered registers. GCC on some machines |
| represents the condition codes as a specific hardware register; |
| @samp{cc} serves to name this register. On other machines, the |
| condition code is handled differently, and specifying @samp{cc} has no |
| effect. But it is valid no matter what the machine. |
| |
| If your assembler instructions access memory in an unpredictable |
| fashion, add @samp{memory} to the list of clobbered registers. This |
| will cause GCC to not keep memory values cached in registers across the |
| assembler instruction and not optimize stores or loads to that memory. |
| You will also want to add the @code{volatile} keyword if the memory |
| affected is not listed in the inputs or outputs of the @code{asm}, as |
| the @samp{memory} clobber does not count as a side-effect of the |
| @code{asm}. 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 will the output operands' addresses, so you can |
| read and write the clobbered registers as many times as you like. Here |
| is an example of multiple instructions in a template; it assumes the |
| subroutine @code{_foo} accepts arguments in registers 9 and 10: |
| |
| @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. |
| |
| @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} which can convert automatically to a @code{double}. |
| |
| Another way to make sure the instruction operates on the correct data |
| type is to use a cast in the @code{asm}. This is different from using a |
| variable @code{__arg} in that it converts more different types. For |
| example, if the desired type were @code{int}, casting the argument to |
| @code{int} would accept a pointer with no complaint, while assigning the |
| argument to an @code{int} variable named @code{__arg} would warn about |
| using a pointer unless the caller explicitly casts it. |
| |
| If an @code{asm} has output operands, GCC assumes for optimization |
| purposes the instruction has no side effects except to change the output |
| operands. This does not mean instructions with a side effect cannot be |
| used, but you must be careful, because the compiler may eliminate them |
| if the output operands aren't used, or move them out of loops, or |
| replace two with one if they constitute a common subexpression. Also, |
| if your instruction does have a side effect on a variable that otherwise |
| appears not to change, the old value of the variable may be reused later |
| if it happens to be found in a register. |
| |
| You can prevent an @code{asm} instruction from being deleted |
| 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 will not delete a volatile @code{asm} if |
| it is reachable. (The instruction can still be deleted if GCC can |
| prove that control-flow will never reach the location of the |
| instruction.) 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 which 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 will 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 will perform some optimizations across a volatile @code{asm} |
| instruction; GCC does not ``forget everything'' when it encounters |
| a volatile @code{asm} instruction the way some other compilers do. |
| |
| An @code{asm} instruction without any output operands will be treated |
| identically to a volatile @code{asm} instruction. |
| |
| It is a natural idea to look for a way to give access to the condition |
| code left by the assembler instruction. However, when we attempted to |
| implement this, we found no way to make it work reliably. The problem |
| is that output operands might need reloading, which would result in |
| additional following ``store'' instructions. On most machines, these |
| instructions would alter the condition code before there was time to |
| test it. This problem doesn't arise for ordinary ``test'' and |
| ``compare'' instructions because they don't have any output operands. |
| |
| For reasons similar to those described above, it is not possible to give |
| an assembler instruction access to the condition code left by previous |
| instructions. |
| |
| If you are writing a header file that should be includable in ISO C |
| programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate |
| Keywords}. |
| |
| @subsection 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 `@code{;}' 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 would be needed for a single instruction. |
| If this happens then the assembler will produce a diagnostic saying that |
| a label is unreachable. |
| |
| @subsection i386 floating point asm operands |
| |
| There are several rules on the usage of stack-like regs in |
| asm_operands insns. These rules apply only to the operands that are |
| stack-like regs: |
| |
| @enumerate |
| @item |
| Given a set of input regs that die in an asm_operands, it is |
| necessary to know which are implicitly popped by the asm, and |
| which must be explicitly popped by gcc. |
| |
| An input reg that is implicitly popped by the asm must be |
| explicitly clobbered, unless it is constrained to match an |
| output operand. |
| |
| @item |
| For any input reg that is implicitly popped by an asm, it is |
| necessary to know how to adjust the stack to compensate for the pop. |
| If any non-popped input is closer to the top of the reg-stack than |
| the implicitly popped reg, it would not be possible to know what the |
| stack looked like---it's not clear how the rest of the stack ``slides |
| up''. |
| |
| All implicitly popped input regs must be closer to the top of |
| the reg-stack than any input that is not implicitly popped. |
| |
| It is possible that if an input dies in an insn, reload might |
| use the input reg for an output reload. Consider this example: |
| |
| @smallexample |
| asm ("foo" : "=t" (a) : "f" (b)); |
| @end smallexample |
| |
| This asm says that input B is not popped by the asm, and that |
| the asm pushes a result onto the reg-stack, i.e., the stack is one |
| deeper after the asm than it was before. But, it is possible that |
| reload will think that it can use the same reg for both the input and |
| the output, if input B dies in this insn. |
| |
| If any input operand uses the @code{f} constraint, all output reg |
| constraints must use the @code{&} earlyclobber. |
| |
| The asm above would be written as |
| |
| @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---there is no other way to |
| know which regs the outputs appear in unless the user indicates |
| this in the constraints. |
| |
| Output operands must specifically indicate which reg an output |
| appears in after an asm. @code{=f} is not allowed: the operand |
| constraints must select a class with a single reg. |
| |
| @item |
| Output operands may not be ``inserted'' between existing stack regs. |
| Since no 387 opcode uses a read/write operand, all output operands |
| are dead before the asm_operands, and are pushed by the asm_operands. |
| It makes no sense to push anywhere but the top of the reg-stack. |
| |
| Output operands must start at the top of the reg-stack: output |
| operands may not ``skip'' a reg. |
| |
| @item |
| Some asm statements may need extra stack space for internal |
| calculations. This can be guaranteed by clobbering stack registers |
| unrelated to the inputs and outputs. |
| |
| @end enumerate |
| |
| Here are a couple of reasonable asms to want to write. This asm |
| takes one input, which is internally popped, and produces two outputs. |
| |
| @smallexample |
| asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); |
| @end smallexample |
| |
| This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode, |
| and replaces them with one output. The user must code the @code{st(1)} |
| clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs. |
| |
| @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 which 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 will work provided the register you specify fits the constraints |
| specified for that operand in the @code{asm}.) |
| @end itemize |
| |
| @menu |
| * Global Reg Vars:: |
| * Local Reg Vars:: |
| @end menu |
| |
| @node Global Reg Vars |
| @subsection Defining Global Register Variables |
| @cindex global register variables |
| @cindex registers, global variables in |
| |
| You can define a global register variable in GNU C like this: |
| |
| @smallexample |
| register int *foo asm ("a5"); |
| @end smallexample |
| |
| @noindent |
| Here @code{a5} is the name of the register which should be used. Choose a |
| register which is normally saved and restored by function calls on your |
| machine, so that library routines will not clobber it. |
| |
| Naturally the register name is cpu-dependent, so you would need to |
| conditionalize your program according to cpu type. The register |
| @code{a5} would be a good choice on a 68000 for a variable of pointer |
| type. On machines with register windows, be sure to choose a ``global'' |
| register that is not affected magically by the function call mechanism. |
| |
| In addition, operating systems on one type of cpu may differ in how they |
| name the registers; then you would need additional conditionals. For |
| example, some 68000 operating systems call this register @code{%a5}. |
| |
| Eventually there may be a way of asking the compiler to choose a register |
| automatically, but first we need to figure out how it should choose and |
| how to enable you to guide the choice. No solution is evident. |
| |
| Defining a global register variable in a certain register reserves that |
| register entirely for this use, at least within the current compilation. |
| The register will not be allocated for any other purpose in the functions |
| in the current compilation. The register will not be saved and restored by |
| these functions. Stores into this register are never deleted even if they |
| would appear to be dead, but references may be deleted or moved or |
| simplified. |
| |
| It is not safe to access the global register variables from signal |
| handlers, or from more than one thread of control, because the system |
| library routines may temporarily use the register for other things (unless |
| you recompile them specially for the task at hand). |
| |
| @cindex @code{qsort}, and global register variables |
| It is not safe for one function that uses a global register variable to |
| call another such function @code{foo} by way of a third function |
| @code{lose} that was compiled without knowledge of this variable (i.e.@: in a |
| different source file in which the variable wasn't declared). This is |
| because @code{lose} might save the register and put some other value there. |
| For example, you can't expect a global register variable to be available in |
| the comparison-function that you pass to @code{qsort}, since @code{qsort} |
| might have put something else in that register. (If you are prepared to |
| recompile @code{qsort} with the same global register variable, you can |
| solve this problem.) |
| |
| If you want to recompile @code{qsort} or other source files which do not |
| actually use your global register variable, so that they will not use that |
| register for any other purpose, then it suffices to specify the compiler |
| option @option{-ffixed-@var{reg}}. You need not actually add a global |
| register declaration to their source code. |
| |
| A function which can alter the value of a global register variable cannot |
| safely be called from a function compiled without this variable, because it |
| could clobber the value the caller expects to find there on return. |
| Therefore, the function which is the entry point into the part of the |
| program that uses the global register variable must explicitly save and |
| restore the value which belongs to its caller. |
| |
| @cindex register variable after @code{longjmp} |
| @cindex global register after @code{longjmp} |
| @cindex value after @code{longjmp} |
| @findex longjmp |
| @findex setjmp |
| On most machines, @code{longjmp} will restore to each global register |
| variable the value it had at the time of the @code{setjmp}. On some |
| machines, however, @code{longjmp} will not change the value of global |
| register variables. To be portable, the function that called @code{setjmp} |
| should make other arrangements to save the values of the global register |
| variables, and to restore them in a @code{longjmp}. This way, the same |
| thing will happen regardless of what @code{longjmp} does. |
| |
| All global register variable declarations must precede all function |
| definitions. If such a declaration could appear after function |
| definitions, the declaration would be too late to prevent the register from |
| being used for other purposes in the preceding functions. |
| |
| Global register variables may not have initial values, because an |
| executable file has no means to supply initial contents for a register. |
| |
| On the SPARC, there are reports that g3 @dots{} g7 are suitable |
| registers, but certain library functions, such as @code{getwd}, as well |
| as the subroutines for division and remainder, modify g3 and g4. g1 and |
| g2 are local temporaries. |
| |
| On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7. |
| Of course, it will not do to use more than a few of those. |
| |
| @node Local Reg Vars |
| @subsection Specifying Registers for Local Variables |
| @cindex local variables, specifying registers |
| @cindex specifying registers for local variables |
| @cindex registers for local variables |
| |
| You can define a local register variable with a specified register |
| like this: |
| |
| @smallexample |
| register int *foo asm ("a5"); |
| @end smallexample |
| |
| @noindent |
| Here @code{a5} is the name of the register which should be used. Note |
| that this is the same syntax used for defining global register |
| variables, but for a local variable it would appear within a function. |
| |
| Naturally the register name is cpu-dependent, but this is not a |
| problem, since specific registers are most often useful with explicit |
| assembler instructions (@pxref{Extended Asm}). Both of these things |
| generally require that you conditionalize your program according to |
| cpu type. |
| |
| In addition, operating systems on one type of cpu may differ in how they |
| name the registers; then you would need additional conditionals. For |
| example, some 68000 operating systems call this register @code{%a5}. |
| |
| Defining such a register variable does not reserve the register; it |
| remains available for other uses in places where flow control determines |
| the variable's value is not live. |
| |
| This option does not guarantee that GCC will generate code that has |
| this variable in the register you specify at all times. You may not |
| code an explicit reference to this register in the @emph{assembler |
| instruction template} part of an @code{asm} statement and assume it will |
| always refer 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 which 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 will overwrite 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 |
| In those cases, a solution is to use a temporary variable for |
| each arbitrary expression. @xref{Example of asm with clobbered asm reg}. |
| |
| @c APPLE LOCAL begin CW asm blocks |
| @node Asm Blocks and Functions |
| @section Blocks and Functions of Assembly Language |
| |
| (This feature is APPLE ONLY.) |
| |
| In addition to writing single statements in assembly, you can also |
| define blocks and entire functions to use a mixed assembly and C |
| syntax. The syntax follows that used in Metrowerks' CodeWarrior on |
| PowerPC and Microsoft Visual Studio on x86. This extension must be |
| explicitly enabled with the @option{-fasm-blocks} option. |
| |
| The block syntax consists of @code{asm} followed by braces, with the |
| assembly instructions on separate lines. (However, @code{';'} may be |
| used to put several instructions on one line in CW-style, and |
| @code{asm} in either style.) You write labels with either a preceding |
| @code{'@@'} or a trailing @code{':'} (or both, if you prefer); labels |
| are always local to the asm blocks of the function. Comments and |
| lexical rules are as for standard C/C++. |
| |
| @verbatim |
| int foo (int arg) { |
| register int bar; |
| asm { |
| li bar, 42 |
| add bar, arg, bar ; nop ; ; nop |
| } |
| return bar; |
| } |
| @end verbatim |
| |
| The function syntax uses @code{asm} as a keyword in the function |
| definition. In this form, C declarations may appear at the beginning |
| of the function body, in order to declare variables that you want to |
| use in the body, but may not be used after the first assembly opcode |
| or label (even in C99 or C++). |
| |
| @verbatim |
| asm int baz (int arg1) { |
| register int loc1, loc2; |
| @123 |
| li loc1,4 * 89 |
| nand. r5,arg1,loc1 |
| ble- cr0, @123 |
| otherlab: nop |
| mr r3,r5 |
| } |
| @end verbatim |
| |
| Note that the compiler just passes the instructions through to the |
| assembler with only necessary changes, such as a substitution of |
| globally unique labels. Assembly syntax errors will therefore be |
| reported by the assembler. |
| |
| Also note that the use of literal registers (such as r3) in functions |
| may not work properly with functions that are being inlined. |
| |
| The following PowerPC instructions are assumed to affect memory: @code{l...} |
| except @code{la}, @code{li} and @code{lis} (all memory loads), |
| @code{st...} (all memory stores), @code{sc}, @code{td...}, |
| @code{trap}, @code{tw...}. All other instructions are assumed to not |
| affect memory. |
| |
| The following PowerPC instructions take a memory operand (address operand) as |
| their second operand, all other instructions are assumed to not: |
| |
| @code{la}, @code{lbzu}, @code{ld}, @code{ldu}, @code{lfd}, |
| @code{lfdu}, @code{lfs}, @code{lfsu}, @code{lha}, @code{lhau}, |
| @code{lhz}, @code{lhzu}, @code{lmw}, @code{lwa}, @code{lwz}, |
| @code{lwzu}, @code{stb}, @code{stbu}, @code{std}, @code{stdu}, |
| @code{stfd}, @code{stfdu}, @code{stfs}, @code{stfsu}, @code{sth}, |
| @code{sthu}, @code{stmw}, @code{stw}, @code{stwu}. |
| |
| Arguments that require substitution beyond vector registers, floating |
| point registers, general registers are not supported; an example |
| would be trying to use the compiler to allocate condition code |
| registers instead of just writting a specific condition code register. |
| |
| On x86, the following instructions are not yet implemented by the assembler: |
| |
| @code{bound r m}, |
| @code{cmovpe r rm}, |
| @code{cmovpo r rm}, |
| @code{cmovz r rm}, |
| @code{ins m d}, |
| @code{lods m}, |
| @code{movs m m} |
| @code{scas m}, |
| @code{stos m}, and |
| @code{xlat m}. |
| |
| Note, the letters after the instructions are the usual x86 contraint |
| letters for the operands. |
| @c APPLE LOCAL end CW asm blocks |
| |
| @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}). The ISO C99 keyword |
| @code{restrict} is only available when @option{-std=gnu99} (which will |
| eventually be the default) or @option{-std=c99} (or the equivalent |
| @option{-std=iso9899:1999}) is used. |
| |
| The way to solve these problems is to put @samp{__} at the beginning and |
| end of each problematical keyword. For example, use @code{__asm__} |
| instead of @code{asm}, 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 |
| which does specify the possible values completes the type. |
| |
| You can't allocate variables or storage using the type while it is |
| incomplete. However, you can work with pointers to that type. |
| |
| This extension may not be very useful, but it makes the handling of |
| @code{enum} more consistent with the way @code{struct} and @code{union} |
| are handled. |
| |
| This extension is not supported by GNU C++. |
| |
| @node Function Names |
| @section Function Names as Strings |
| @cindex @code{__func__} identifier |
| @cindex @code{__FUNCTION__} identifier |
| @cindex @code{__PRETTY_FUNCTION__} identifier |
| |
| GCC provides three magic variables which hold the name of the current |
| function, as a string. The first of these is @code{__func__}, which |
| is part of the C99 standard: |
| |
| @display |
| The identifier @code{__func__} is implicitly declared by the translator |
| as if, immediately following the opening brace of each function |
| definition, the declaration |
| |
| @smallexample |
| static const char __func__[] = "function-name"; |
| @end smallexample |
| |
| appeared, where function-name is the name of the lexically-enclosing |
| function. This name is the unadorned name of the function. |
| @end display |
| |
| @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 will return the address of |
| the function that will be 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 will return @code{0} or a |
| random value. In addition, @code{__builtin_frame_address} may be used |
| to determine if the top of the stack has been reached. |
| |
| This function should only be used with a nonzero argument for debugging |
| purposes. |
| @end deftypefn |
| |
| @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) |
| This function is similar to @code{__builtin_return_address}, but it |
| returns the address of the function frame rather than the return address |
| of the function. Calling @code{__builtin_frame_address} with a value of |
| @code{0} yields the frame address of the current function, a value of |
| @code{1} yields the frame address of the caller of the current function, |
| and so forth. |
| |
| The frame is the area on the stack which holds local variables and saved |
| registers. The frame address is normally the address of the first word |
| pushed on to the stack by the function. However, the exact definition |
| depends upon the processor and the calling convention. If the processor |
| has a dedicated frame pointer register, and the function has a frame, |
| then @code{__builtin_frame_address} will return the value of the frame |
| pointer register. |
| |
| On some machines it may be impossible to determine the frame address of |
| any function other than the current one; in such cases, or when the top |
| of the stack has been reached, this function will return @code{0} if |
| the first frame pointer is properly initialized by the startup code. |
| |
| This function should only be used with a nonzero argument for debugging |
| purposes. |
| @end deftypefn |
| |
| @node Vector Extensions |
| @section Using vector instructions through built-in functions |
| |
| On some targets, the instruction set contains SIMD vector instructions that |
| operate on multiple values contained in one large register at the same time. |
| For example, on the i386 the MMX, 3Dnow! and SSE extensions can be used |
| this way. |
| |
| The first step in using these extensions is to provide the necessary data |
| types. This should be done using an appropriate @code{typedef}: |
| |
| @smallexample |
| typedef int v4si __attribute__ ((vector_size (16))); |
| @end smallexample |
| |
| 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} will be @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. |
| |
| 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 |
| will cause 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 will |
| produce code that uses 4 @code{SIs}. |
| |
| The types defined in this manner can be used with a subset of normal C |
| operations. Currently, GCC will allow 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} will be |
| added to the corresponding 4 elements in @var{b} and the resulting |
| vector will be 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. |
| |
| 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. |
| |
| A port that supports hardware vector operations, usually provides a set |
| of built-in functions that can be used to operate on vectors. For |
| example, a function to add two vectors and multiply the result by a |
| third could look like this: |
| |
| @smallexample |
| v4si f (v4si a, v4si b, v4si c) |
| @{ |
| v4si tmp = __builtin_addv4si (a, b); |
| return __builtin_mulv4si (tmp, c); |
| @} |
| |
| @end smallexample |
| |
| @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 |
| |
| 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 Atomic Builtins |
| @section Built-in functions for atomic memory access |
| |
| The following builtins 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 ``__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 will allow 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 will be |
| generated and a call an external function will be generated. The external |
| function will carry the same name as the builtin, 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 builtins are considered a @dfn{full barrier}. That is, |
| no memory operand will be moved across the operation, either forward or |
| backward. Further, instructions will be 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 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 which 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 builtins 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 |
| |
| @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 builtins 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 |
| |
| @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 builtins 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} was written. The ``val'' version returns the contents |
| of @code{*@var{ptr}} before the operation. |
| |
| @item __sync_synchronize (...) |
| @findex __sync_synchronize |
| This builtin 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 builtin, 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 builtin is not a full barrier, but rather an @dfn{acquire barrier}. |
| This means that references after the builtin cannot move to (or be |
| speculated to) before the builtin, 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 builtin releases the lock acquired by @code{__sync_lock_test_and_set}. |
| Normally this means writing the constant 0 to @code{*@var{ptr}}. |
| |
| This builtin 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 Object Size Checking |
| @section Object Size Checking Builtins |
| @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 runtime. */ |
| 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 runtime. */ |
| 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 will, otherwise the checking function |
| should be 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_isgreater |
| @findex __builtin_isgreaterequal |
| @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 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 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 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 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 will not be |
| documented here because they may change from time to time; we do not |
| recommend general use of these functions. |
| |
| The remaining functions are provided for optimization purposes. |
| |
| @opindex fno-builtin |
| GCC includes built-in versions of many of the functions in the standard |
| C library. The versions prefixed with @code{__builtin_} will always be |
| treated as having the same meaning as the C library function even if you |
| specify the @option{-fno-builtin} option. (@pxref{C Dialect Options}) |
| Many of these functions are only optimized in certain cases; if they are |
| not optimized in a particular case, a call to the library function will |
| be emitted. |
| |
| @opindex ansi |
| @opindex std |
| Outside strict ISO C mode (@option{-ansi}, @option{-std=c89} or |
| @option{-std=c99}), 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{gettext}, |
| @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, |
| @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, |
| @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{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 C89 |
| 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=c89}). |
| |
| 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=c89}). |
| |
| 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{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. |
| |
| @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 would 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 a |
| constant expression that must be able to be determined at compile time, |
| is nonzero. Otherwise it returns 0. |
| |
| This built-in function is analogous to the @samp{? :} operator in C, |
| except that the expression returned has its type unaltered by promotion |
| rules. Also, the built-in function does not evaluate the expression |
| that was not chosen. For example, if @var{const_exp} evaluates to true, |
| @var{exp2} is not evaluated even if it has side-effects. |
| |
| This built-in function can return an lvalue if the chosen argument is an |
| lvalue. |
| |
| If @var{exp1} is returned, the return type is the same as @var{exp1}'s |
| type. Similarly, if @var{exp2} is returned, its return type is the same |
| as @var{exp2}. |
| |
| Example: |
| |
| @smallexample |
| #define foo(x) \ |
| __builtin_choose_expr ( \ |
| __builtin_types_compatible_p (typeof (x), double), \ |
| foo_double (x), \ |
| __builtin_choose_expr ( \ |
| __builtin_types_compatible_p (typeof (x), float), \ |
| foo_float (x), \ |
| /* @r{The void expression results in a compile-time error} \ |
| @r{when assigning the result to something.} */ \ |
| (void)0)) |
| @end smallexample |
| |
| @emph{Note:} This construct is only available for C@. Furthermore, the |
| unused expression (@var{exp1} or @var{exp2} depending on the value of |
| @var{const_exp}) may still generate syntax errors. This may change in |
| future revisions. |
| |
| @end deftypefn |
| |
| @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) |
| You can use the built-in function @code{__builtin_constant_p} to |
| determine if a value is known to be constant at compile-time and hence |
| that GCC can perform constant-folding on expressions involving that |
| value. The argument of the function is the value to test. The function |
| returns the integer 1 if the argument is known to be a compile-time |
| constant and 0 if it is not known to be a compile-time constant. A |
| return of 0 does not indicate that the value is @emph{not} a constant, |
| but merely that GCC cannot prove it is a constant with the specified |
| value of the @option{-O} option. |
| |
| You would typically use this function in an embedded application where |
| memory was a critical resource. If you have some complex calculation, |
| you may want it to be folded if it involves constants, but need to call |
| a function if it does not. For example: |
| |
| @smallexample |
| #define Scale_Value(X) \ |
| (__builtin_constant_p (X) \ |
| ? ((X) * SCALE + OFFSET) : Scale (X)) |
| @end smallexample |
| |
| You may use this built-in function in either a macro or an inline |
| function. However, if you use it in an inlined function and pass an |
| argument of the function as the argument to the built-in, GCC will |
| never return 1 when you call the inline function with a string constant |
| or compound literal (@pxref{Compound Literals}) and will not return 1 |
| when you pass a constant numeric value to the inline function unless you |
| specify the @option{-O} option. |
| |
| You may also use @code{__builtin_constant_p} in initializers for static |
| data. For instance, you can write |
| |
| @smallexample |
| static const int table[] = @{ |
| __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, |
| /* @r{@dots{}} */ |
| @}; |
| @end smallexample |
| |
| @noindent |
| This is an acceptable initializer even if @var{EXPRESSION} is not a |
| constant expression. GCC must be more conservative about evaluating the |
| built-in in this case, because it has no opportunity to perform |
| optimization. |
| |
| Previous versions of GCC did not accept this built-in in data |
| initializers. The earliest version where it is completely safe is |
| 3.0.1. |
| @end deftypefn |
| |
| @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) |
| @opindex fprofile-arcs |
| You may use @code{__builtin_expect} to provide the compiler with |
| branch prediction information. In general, you should prefer to |
| use actual profile feedback for this (@option{-fprofile-arcs}), as |
| programmers are notoriously bad at predicting how their programs |
| actually perform. However, there are applications in which this |
| data is hard to collect. |
| |
| The return value is the value of @var{exp}, which should be an |
| integral expression. The value of @var{c} must be a compile-time |
| constant. The semantics of the built-in are that it is expected |
| that @var{exp} == @var{c}. For example: |
| |
| @smallexample |
| if (__builtin_expect (x, 0)) |
| foo (); |
| @end smallexample |
| |
| @noindent |
| would indicate that we do not expect to call @code{foo}, since |
| we expect @code{x} to be zero. Since you are limited to integral |
| expressions for @var{exp}, you should use constructions such as |
| |
| @smallexample |
| if (__builtin_expect (ptr != NULL, 1)) |
| error (); |
| @end smallexample |
| |
| @noindent |
| when testing pointer or floating-point values. |
| @end deftypefn |
| |
| @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) |
| This function is used to minimize cache-miss latency by moving data into |
| a cache before it is accessed. |
| You can insert calls to @code{__builtin_prefetch} into code for which |
| you know addresses of data in memory that is likely to be accessed soon. |
| If the target supports them, data prefetch instructions will be generated. |
| If the prefetch is done early enough before the access then the data will |
| be in the cache by the time it is accessed. |
| |
| The value of @var{addr} is the address of the memory to prefetch. |
| There are two optional arguments, @var{rw} and @var{locality}. |
| The value of @var{rw} is a compile-time constant one or zero; one |
| means that the prefetch is preparing for a write to the memory address |
| and zero, the default, means that the prefetch is preparing for a read. |
| The value @var{locality} must be a compile-time constant integer between |
| zero and three. A value of zero means that the data has no temporal |
| locality, so it need not be left in the cache after the access. A value |
| of three means that the data has a high degree of temporal locality and |
| should be left in all levels of cache possible. Values of one and two |
| mean, respectively, a low or moderate degree of temporal locality. The |
| default is three. |
| |
| @smallexample |
| for (i = 0; i < n; i++) |
| @{ |
| a[i] = a[i] + b[i]; |
| __builtin_prefetch (&a[i+j], 1, 1); |
| __builtin_prefetch (&b[i+j], 0, 1); |
| /* @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} will not fault if @code{p->next} is not a valid |
| address, but evaluation will fault if @code{p} is not a valid address. |
| |
| If the target does not support data prefetch, the address expression |
| is evaluated if it includes side effects but no other code is generated |
| and GCC does not issue a warning. |
| @end deftypefn |
| |
| @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} 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} 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 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_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_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_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 |
| @c APPLE LOCAL begin mainline |
| @deftypefn {Built-in Function} int32_t __builtin_bswap32 (int32_t x) |
| Returns @var{x} with the order of the bytes reversed; for example, |
| @code{0xaabbccdd} becomes @code{0xddccbbaa}. Byte here always means |
| exactly 8 bits. |
| @end deftypefn |
| |
| @deftypefn {Built-in Function} int64_t __builtin_bswap64 (int64_t x) |
| Similar to @code{__builtin_bswap32}, except the argument and return types |
| are 64-bit. |
| @end deftypefn |
| @c APPLE LOCAL end mainline |
| |
| @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. |
| |
| @c APPLE LOCAL begin ARM NEON support. Merge from Codesourcery |
| @menu |
| * Alpha Built-in Functions:: |
| * ARM Built-in Functions:: |
| * ARM NEON Intrinsics:: |
| * Blackfin Built-in Functions:: |
| * FR-V Built-in Functions:: |
| * X86 Built-in Functions:: |
| * MIPS DSP Built-in Functions:: |
| * MIPS Paired-Single Support:: |
| * PowerPC AltiVec Built-in Functions:: |
| * SPARC VIS Built-in Functions:: |
| @end menu |
| @c APPLE LOCAL end ARM NEON support. Merge from Codesourcery |
| |
| @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 builtins 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 Built-in Functions |
| @subsection ARM 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_getwcx (int) |
| void __builtin_arm_setwcx (int, 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) |
| v4hi __builtin_arm_tinsrh (v4hi, int) |
| v2si __builtin_arm_tinsrw (v2si, 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 (v8qi, v8qi) |
| v2si __builtin_arm_wsadbz (v8qi, v8qi) |
| v2si __builtin_arm_wsadh (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 |
| |
| @c APPLE LOCAL begin ARM NEON support |
| @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 |
| @c APPLE LOCAL end ARM NEON support. Merge from Codesourcery. |
| |
| @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 |
| will select 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 will be 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. |
| |
| Note that, 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 |
| which perform runtime 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 |
| @c APPLE LOCAL begin 4656532 use V1DI for _m64 |
| 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}. |
| |
| 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) |
| @c APPLE LOCAL begin radar 4395773 |
| v1di __builtin_ia32_paddq (v1di, v1di) |
| @c APPLE LOCAL end radar 4395773 |
| v8qi __builtin_ia32_psubb (v8qi, v8qi) |
| v4hi __builtin_ia32_psubw (v4hi, v4hi) |
| v2si __builtin_ia32_psubd (v2si, v2si) |
| @c APPLE LOCAL begin radar 4395773 |
| v1di __builtin_ia32_psubq (v1di, v1di) |
| @c APPLE LOCAL end radar 4395773 |
| 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) |
| v1di __builtin_ia32_pand (v1di, v1di) |
| v1di __builtin_ia32_pandn (v1di,v1di) |
| v1di __builtin_ia32_por (v1di, v1di) |
| v1di __builtin_ia32_pxor (v1di, v1di) |
| 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) |
| @c APPLE LOCAL begin radar 4395773 |
| void __builtin_ia32_emms (void) |
| v4hi __builtin_ia32_psllw (v4hi, v1di) |
| v4hi __builtin_ia32_psllwi (v4hi, int) |
| v2si __builtin_ia32_pslld (v2si, v1di) |
| v2si __builtin_ia32_pslldi (v2si, int) |
| v1di __builtin_ia32_psllq (v1di, v1di) |
| @c APPLE LOCAL radar 4684674 |
| v1di __builtin_ia32_psllqi (v1di, int) |
| v4hi __builtin_ia32_psrlw (v4hi, v1di) |
| v4hi __builtin_ia32_psrlwi (v4hi, int) |
| v2si __builtin_ia32_psrld (v2si, v1di) |
| v2si __builtin_ia32_psrldi (v2si, int) |
| v1di __builtin_ia32_psrlq (v1di, v1di) |
| @c APPLE LOCAL radar 4684674 |
| v1di __builtin_ia32_psrlqi (v1di, int) |
| v4hi __builtin_ia32_psraw (v4hi, v1di) |
| v4hi __builtin_ia32_psrawi (v4hi, int) |
| v2si __builtin_ia32_psrad (v2si, v1di) |
| v2si __builtin_ia32_psradi (v2si, int) |
| v4hi __builtin_ia32_pshufw (v4hi, int) |
| v2si __builtin_ia32_pmaddwd (v4hi, v4hi) |
| v2si __builtin_ia32_vec_init_v2si (int, int) |
| v4hi __builtin_ia32_vec_init_v4hi (short, short, short, short) |
| v8qi __builtin_ia32_vec_init_v8qi (char, char, char, char, char, char, char, char) |
| int __builtin_ia32_vec_ext_v2si (v2si, int) |
| @c APPLE LOCAL end radar 4395773 |
| @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) |
| v4hi __builtin_ia32_psadbw (v8qi, v8qi) |
| v8qi __builtin_ia32_pmaxub (v8qi, v8qi) |
| v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) |
| v8qi __builtin_ia32_pminub (v8qi, v8qi) |
| v4hi __builtin_ia32_pminsw (v4hi, v4hi) |
| int __builtin_ia32_pextrw (v4hi, int) |
| v4hi __builtin_ia32_pinsrw (v4hi, int, int) |
| int __builtin_ia32_pmovmskb (v8qi) |
| void __builtin_ia32_maskmovq (v8qi, v8qi, char *) |
| void __builtin_ia32_movntq (v1di *, v1di) |
| void __builtin_ia32_sfence (void) |
| @c APPLE LOCAL begin radar 4395773 |
| int __builtin_ia32_vec_ext_v4hi (v4hi, int) |
| v4hi __builtin_ia32_vec_set_v4hi (v4hi, int, int) |
| @c APPLE LOCAL end radar 4395773 |
| @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) |
| @c APPLE LOCAL begin radar 4395773 |
| void __builtin_ia32_ldmxcsr (unsigned) |
| unsigned __builtin_ia32_stmxcsr (void) |
| v2df __builtin_ia32_vec_ext_v2df (v2df, int) |
| v2di __builtin_ia32_vec_ext_v2di (v2di, int) |
| v4sf __builtin_ia32_vec_ext_v4sf (v4sf, int) |
| v4si __builtin_ia32_vec_ext_v4si (v4si, int) |
| v8hi __builtin_ia32_vec_set_v8hi (v8hi, int, int) |
| unsigned int __builtin_ia32_vec_ext_v8hi (v8hi, int) |
| @c APPLE LOCAL end radar 4395773 |
| @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, v2si *) |
| Generates the @code{movhps} machine instruction as a load from memory. |
| @item v4sf __builtin_ia32_loadlps (v4sf, v2si *) |
| Generates the @code{movlps} machine instruction as a load from memory |
| @item void __builtin_ia32_storehps (v4sf, v2si *) |
| Generates the @code{movhps} machine instruction as a store to memory. |
| @item void __builtin_ia32_storelps (v4sf, v2si *) |
| Generates the @code{movlps} machine instruction as a store to memory. |
| @end table |
| |
| The following built-in functions are available when @option{-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 (v16qi, v16qi) |
| v8hi __builtin_ia32_packssdw128 (v8hi, v8hi) |
| v16qi __builtin_ia32_packuswb128 (v16qi, v16qi) |
| 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 *) |
| v2df __builtin_ia32_loadlpd (v2df, double *) |
| int __builtin_ia32_movmskpd (v2df) |
| int __builtin_ia32_pmovmskb128 (v16qi) |
| void __builtin_ia32_movnti (int *, 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) |
| unsigned long long __builtin_ia32_pmuludq (v2si, v2si) |
| v2di __builtin_ia32_pmuludq128 (v4si, v4si) |
| v8hi __builtin_ia32_psllw128 (v8hi, v2di) |
| v4si __builtin_ia32_pslld128 (v4si, v2di) |
| v2di __builtin_ia32_psllq128 (v4si, v2di) |
| v8hi __builtin_ia32_psrlw128 (v8hi, v2di) |
| v4si __builtin_ia32_psrld128 (v4si, v2di) |
| v2di __builtin_ia32_psrlq128 (v2di, v2di) |
| v8hi __builtin_ia32_psraw128 (v8hi, v2di) |
| v4si __builtin_ia32_psrad128 (v4si, v2di) |
| 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) |
| @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 |
| |
| @c APPLE LOCAL begin mainline |
| 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) |
| v8qi __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 |
| @c APPLE LOCAL end 4656532 use V1DI for _m64 |
| |
| 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) |
| v16qi __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 |
| @c APPLE LOCAL end mainline |
| 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 |
| |
| @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 integer data, Q15 fractional data 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. |
| |
| 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} and the vector type associated with Q15 is |
| usually called @code{v2q15}. They can be defined in C as follows: |
| |
| @smallexample |
| typedef char v4i8 __attribute__ ((vector_size(4))); |
| typedef short v2q15 __attribute__ ((vector_size(4))); |
| @end smallexample |
| |
| @code{v4i8} 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 will |
| set the lowest byte of @code{a} to @code{1} on little-endian targets |
| and @code{4} on big-endian targets. |
| |
| @emph{Note:} Q15 and Q31 values must be initialized with their integer |
| representation. As shown in this example, the integer representation |
| of a Q15 value can be obtained by multiplying the fractional value 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 |
| |
| 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 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 will |
| be 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_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) |
| i32 __builtin_mips_bposge32 (void) |
| @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 will set the lower half of @code{a} to |
| @code{1.5} on little-endian targets and @code{9.1} on big-endian targets. |
| |
| @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 will be 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 PowerPC AltiVec 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 |
| |
| 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{__pixel}, and @code{__bool}. Macros @option{vector}, |
| @code{pixel}, and @code{bool} are defined in @code{<altivec.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 |
| vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); |
| @end smallexample |
| |
| 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_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); |
| @c APPLE LOCAL begin fixhtml --mrs |
| @end smallexample |
| |
| @smallexample |
| @c APPLE LOCAL end fixhtml --mrs |
| 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_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 |
| |
| @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 v2si __attribute__ ((vector_size (8))); |
| typedef short v4hi __attribute__ ((vector_size (8))); |
| typedef short v2hi __attribute__ ((vector_size (4))); |
| typedef char v8qi __attribute__ ((vector_size (8))); |
| typedef char v4qi __attribute__ ((vector_size (4))); |
| |
| void * __builtin_vis_alignaddr (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, v4hi); |
| v4hi __builtin_vis_fmul8x16al (v4qi, v4hi); |
| 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, v2si); |
| v2hi __builtin_vis_fpackfix (v2si); |
| v8qi __builtin_vis_fpmerge (v4qi, v4qi); |
| |
| int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); |
| @end smallexample |
| |
| @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:: |
| @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 Pragmas |
| @section Pragmas Accepted by GCC |
| @cindex pragmas |
| @cindex #pragma |
| |
| GCC supports several types of pragmas, primarily in order to compile |
| code originally written for other compilers. Note that in general |
| we do not recommend the use of pragmas; @xref{Function Attributes}, |
| for further explanation. |
| |
| @menu |
| * ARM Pragmas:: |
| * M32C Pragmas:: |
| * RS/6000 and PowerPC Pragmas:: |
| * Darwin Pragmas:: |
| * Solaris Pragmas:: |
| * Symbol-Renaming Pragmas:: |
| * Structure-Packing Pragmas:: |
| * Weak Pragmas:: |
| * Diagnostic Pragmas:: |
| * Visibility 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 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. |
| |
| @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 c4x pragmas here. |
| @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}. |
| |
| @c APPLE LOCAL begin radar 4827197 |
| The @code{power} setting, when compiling for the Intel target, does not |
| fully emulate the alignments on native PowerPC targets. When the first |
| field within a struct is of type @code{double}, this causes the struct |
| to be 8-byte aligned on PowerPC target, but only 4-byte aligned on |
| Intel target. When such a struct is nested within another aggregate, |
| differing layouts on the two targets can occur. In such a case, a dummy |
| field @code{char : 0;} can be inserted before the @code{double} to achieve |
| the same layout on both targets. |
| @c APPLE LOCAL end radar 4827197 |
| |
| @item segment @var{tokens}@dots{} |
| @cindex pragma, segment |
| This pragma is accepted, but has no effect. |
| |
| @item unused (@var{var} [, @var{var}]@dots{}) |
| @cindex pragma, unused |
| This pragma declares variables to be possibly unused. GCC will not |
| produce warnings for the listed variables. The effect is similar to |
| that of the @code{unused} attribute, except that this pragma may appear |
| anywhere within the variables' scopes. |
| |
| @c APPLE LOCAL begin optimization pragmas 3124235/3420242 |
| @item optimization_level @{ 0 | 1 | 2 | 3 | reset @} |
| @item optimize_for_size @{ on | off | reset @} |
| @item GCC optimization_level @{ 0 | 1 | 2 | 3 | reset @} |
| @item GCC optimize_for_size @{ on | off | reset @} |
| @cindex pragma, optimization_level |
| (These pragmas are APPLE ONLY.) |
| |
| These pragmas set the current optimization level, similar but not identical |
| to -O0 through -O3, or -Os, on the command line. These pragmas form a |
| stack; the "reset" argument pops the stack, restoring the optimization level |
| to what it was before the previous optimization pragma. The optimization |
| level in effect at the beginning of each function definition is applied to |
| that function. Currently, the pragmas will not affect optimizations whose |
| implementation is based on whole-file analysis; this notably includes |
| inlining and strict aliasing. Also, the feature currently doesn't apply |
| to functions whose body is within a class definition (that is, such |
| functions are compiled with the command line options). |
| |
| The versions without "GCC" have the same syntax and similar effect as |
| CodeWarrior pragmas (although since the optimizations performed by |
| the compilers are not identical, the effect of the options won't be |
| either). These may be convenient for existing code. The versions |
| with "GCC" are recommended for new code. |
| @end table |
| @c APPLE LOCAL end optimization pragmas 3124235/3420242 |
| |
| @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 and Tru64 UNIX system headers, GCC |
| supports two @code{#pragma} directives which change the name used in |
| assembly for a given declaration. These pragmas are only available on |
| platforms whose system headers need them. 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} |
| will be defined if this pragma is available (currently only on |
| Solaris). |
| |
| @item extern_prefix @var{string} |
| @cindex pragma, extern_prefix |
| |
| This pragma causes all subsequent external function and variable |
| declarations to have @var{string} prepended to their assembly symbols. |
| This effect may be terminated with another @code{extern_prefix} pragma |
| whose argument is an empty string. The preprocessor macro |
| @code{__PRAGMA_EXTERN_PREFIX} will be defined if this pragma is |
| available (currently only on Tru64 UNIX)@. |
| @end table |
| |
| These pragmas 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. |
| |
| @item If @code{#pragma extern_prefix} is in effect, and a declaration |
| occurs with an asm label attached, the prefix is silently ignored for |
| that declaration. |
| |
| @item If @code{#pragma extern_prefix} and @code{#pragma redefine_extname} |
| apply to the same declaration, whichever triggered first wins, and a |
| warning issues if they contradict each other. (We would like to have |
| @code{#pragma redefine_extname} always win, for consistency with asm |
| labels, but if @code{#pragma extern_prefix} triggers first we have no |
| way of knowing that that happened.) |
| @end enumerate |
| |
| @node Structure-Packing Pragmas |
| @subsection Structure-Packing Pragmas |
| |
| @c APPLE LOCAL begin radar 4679943 |
| For compatibility with Win32, GCC supports a set of @code{#pragma} |
| directives which change the maximum alignment of members of structures |
| (other than zero-width bitfields), unions, and classes subsequently |
| defined. The @var{n} value below always is required to be a small power |
| of two and specifies the new maximum alignment in bytes. |
| |
| @enumerate |
| @c APPLE LOCAL prune man page |
| @ignore |
| @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[=<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)}. |
| @c APPLE LOCAL prune man page |
| @end ignore |
| |
| @item @code{#pragma pack(@var{n})} pushes the current maximum alignment setting |
| onto an internal stack and then sets the new maximum alignment. (APPLE ONLY) |
| @item @code{#pragma pack()} acts like a @code{#pragma pack(pop)} directive. |
| (APPLE ONLY) |
| @item @code{#pragma pack(push[,@var{n}])} pushes the current maximum alignment |
| setting onto an internal stack and then optionally sets the new maximum |
| alignment. |
| @item @code{#pragma pack(pop)} restores the maximum alignment setting to the |
| one saved at the top of the internal stack (and removes that stack entry). |
| @end enumerate |
| @c APPLE LOCAL end radar 4679943 |
| |
| 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}, but must appear before |
| either its first use or its definition. 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...}) 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 which matches the command line |
| option. |
| |
| @example |
| #pragma GCC diagnostic warning "-Wformat" |
| #pragma GCC diagnostic error "-Wformat" |
| #pragma GCC diagnostic ignored "-Wformat" |
| @end example |
| |
| Note that these pragmas override any command line options. Also, |
| while it is syntactically valid to put these pragmas anywhere in your |
| sources, the only supported location for them is before any data or |
| functions are defined. Doing otherwise may result in unpredictable |
| results depending on how the optimizer manages your sources. If the |
| same option is listed multiple times, the last one specified is the |
| one that is in effect. This pragma is not intended to be a general |
| purpose replacement for command line options, but for implementing |
| strict control over project policies. |
| |
| @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 Unnamed Fields |
| @section Unnamed struct/union fields within structs/unions |
| @cindex struct |
| @cindex union |
| |
| For compatibility with other compilers, GCC allows you to define |
| a structure or union that contains, as fields, structures and unions |
| without names. For example: |
| |
| @smallexample |
| struct @{ |
| int a; |
| union @{ |
| int b; |
| float c; |
| @}; |
| int d; |
| @} foo; |
| @end smallexample |
| |
| In this example, the user would be able to access members of the unnamed |
| union with code like @samp{foo.b}. Note that only unnamed structs and |
| unions are allowed, you may not have, for example, an unnamed |
| @code{int}. |
| |
| You must never create such structures that cause ambiguous field definitions. |
| For example, this structure: |
| |
| @smallexample |
| struct @{ |
| int a; |
| struct @{ |
| int a; |
| @}; |
| @} foo; |
| @end smallexample |
| |
| It is ambiguous which @code{a} is being referred to with @samp{foo.a}. |
| Such constructs are not supported and must be avoided. In the future, |
| such constructs may be detected and treated as compilation errors. |
| |
| @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. |
| |
| @node Thread-Local |
| @section Thread-Local Storage |
| @cindex Thread-Local Storage |
| @cindex @acronym{TLS} |
| @cindex __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 run-time 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://people.redhat.com/drepper/tls.pdf, |
| ELF Handling For Thread-Local Storage} for a detailed explanation of |
| the four thread-local storage addressing models, and how the run-time |
| 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 which 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 |
| |
| @c APPLE LOCAL begin blocks 7205047 5811887 |
| @node Blocks |
| @section Blocks |
| @cindex Blocks |
| @cindex __block |
| |
| Blocks is a language feature that allows one to create anonymous |
| functions. The feature is also known as lambdas or closures in other |
| languages. The feature is controlled by @option{-fblocks}. |
| See @uref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html} for additional details. |
| @c APPLE LOCAL end blocks 7205047 5811887 |
| |
| @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 |
| * 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. |
| * Namespace Association:: Strong using-directives for namespace association. |
| * 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 Volatiles |
| @section When is a Volatile Object Accessed? |
| @cindex accessing volatiles |
| @cindex volatile read |
| @cindex volatile write |
| @cindex volatile access |
| |
| Both the C and C++ standard have the concept of volatile objects. These |
| are normally accessed by pointers and used for accessing hardware. The |
| standards encourage compilers to refrain from optimizations concerning |
| accesses to volatile objects. The C standard leaves it implementation |
| defined as to what constitutes a volatile access. The C++ standard omits |
| to specify this, except to say that C++ should behave in a similar manner |
| to C with respect to volatiles, where possible. The minimum either |
| standard specifies is that at a sequence point all previous accesses to |
| volatile objects have stabilized and no subsequent accesses have |
| occurred. Thus an implementation is free to reorder and combine |
| volatile accesses which occur between sequence points, but cannot do so |
| for accesses across a sequence point. The use of volatiles does not |
| allow you to violate the restriction on updating objects multiple times |
| within a sequence point. |
| |
| @xref{Qualifiers implementation, , Volatile qualifier and the C compiler}. |
| |
| The behavior differs slightly between C and C++ in the non-obvious cases: |
| |
| @smallexample |
| volatile int *src = @var{somevalue}; |
| *src; |
| @end smallexample |
| |
| With C, such expressions are rvalues, and GCC interprets this either as a |
| read of the volatile object being pointed to or only as request to evaluate |
| the side-effects. The C++ standard specifies that such expressions do not |
| undergo lvalue to rvalue conversion, and that the type of the dereferenced |
| object may be incomplete. The C++ standard does not specify explicitly |
| that it is this lvalue to rvalue conversion which may be responsible for |
| causing an access. However, there is reason to believe that it is, |
| because otherwise certain simple expressions become undefined. However, |
| because it would surprise most programmers, G++ treats dereferencing a |
| pointer to volatile object of complete type when the value is unused 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. |
| |
| @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} will have the effective |
| definition @code{T *__restrict__ const this}. Notice that the |
| interpretation of a @code{__restrict__} member function qualifier is |
| different to that of @code{const} or @code{volatile} qualifier, in that it |
| is applied to the pointer rather than the object. This is consistent with |
| other compilers which implement restricted pointers. |
| |
| As with all outermost parameter qualifiers, @code{__restrict__} is |
| ignored in function definition matching. This means you only need to |
| specify @code{__restrict__} in a function definition, rather than |
| in a function prototype as well. |
| |
| @node Vague Linkage |
| @section Vague Linkage |
| @cindex vague linkage |
| |
| There are several constructs in C++ which require space in the object |
| file but are not clearly tied to a single translation unit. We say that |
| these constructs have ``vague linkage''. Typically such constructs are |
| emitted wherever they are needed, though sometimes we can be more |
| clever. |
| |
| @table @asis |
| @item Inline Functions |
| Inline functions are typically defined in a header file which can be |
| included in many different compilations. Hopefully they can usually be |
| inlined, but sometimes an out-of-line copy is necessary, if the address |
| of the function is taken or if inlining fails. In general, we emit an |
| out-of-line copy in all translation units where one is needed. As an |
| exception, we only emit inline virtual functions with the vtable, since |
| it will always require a copy. |
| |
| Local static variables and string constants used in an inline function |
| are also considered to have vague linkage, since they must be shared |
| between all inlined and out-of-line instances of the function. |
| |
| @item VTables |
| @cindex vtable |
| C++ virtual functions are implemented in most compilers using a lookup |
| table, known as a vtable. The vtable contains pointers to the virtual |
| functions provided by a class, and each object of the class contains a |
| pointer to its vtable (or vtables, in some multiple-inheritance |
| situations). If the class declares any non-inline, non-pure virtual |
| functions, the first one is chosen as the ``key method'' for the class, |
| and the vtable is only emitted in the translation unit where the key |
| method is defined. |
| |
| @emph{Note:} If the chosen key method is later defined as inline, the |
| vtable will still be emitted in every translation unit which defines it. |
| Make sure that any inline virtuals are declared inline in the class |
| body, even if they are not defined there. |
| |
| @item type_info objects |
| @cindex type_info |
| @cindex RTTI |
| C++ requires information about types to be written out in order to |
| implement @samp{dynamic_cast}, @samp{typeid} and exception handling. |
| For polymorphic classes (classes with virtual functions), the type_info |
| object is written out along with the vtable so that @samp{dynamic_cast} |
| can determine the dynamic type of a class object at runtime. For all |
| other types, we write out the type_info object when it is used: when |
| applying @samp{typeid} to an expression, throwing an object, or |
| referring to a type in a catch clause or exception specification. |
| |
| @item Template Instantiations |
| Most everything in this section also applies to template instantiations, |
| but there are other options as well. |
| @xref{Template Instantiation,,Where's the Template?}. |
| |
| @end table |
| |
| When used with GNU ld version 2.8 or later on an ELF system such as |
| 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 |
| will use them. This way one copy will override all the others, but |
| the unused copies will still take up space in the executable. |
| |
| For targets which do not support either COMDAT or weak symbols, |
| most entities with vague linkage will be emitted as local symbols to |
| avoid duplicate definition errors from the linker. This will not happen |
| for local statics in inlines, however, as having multiple copies will |
| almost certainly break things. |
| |
| @xref{C++ Interface,,Declarations and Definitions in One Header}, for |
| another way to control placement of these constructs. |
| |
| @node C++ Interface |
| @section #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 will not be generated (unless |
| the main input source file itself uses @samp{#pragma implementation}). |
| Instead, the object files will contain references to be resolved at link |
| time. |
| |
| The second form of this directive is useful for the case where you have |
| multiple headers with the same name in different directories. If you |
| use this form, you must specify the same string to @samp{#pragma |
| implementation}. |
| |
| @item #pragma implementation |
| @itemx #pragma implementation "@var{objects}.h" |
| @kindex #pragma implementation |
| Use this pragma in a @emph{main input file}, when you want full output from |
| included header files to be generated (and made globally visible). The |
| included header file, in turn, should use @samp{#pragma interface}. |
| Backup copies of inline member functions, debugging information, and the |
| internal tables used to implement virtual functions are all generated in |
| implementation files. |
| |
| @cindex implied @code{#pragma implementation} |
| @cindex @code{#pragma implementation}, implied |
| @cindex naming convention, implementation headers |
| If you use @samp{#pragma implementation} with no argument, it applies to |
| an include file with the same basename@footnote{A file's @dfn{basename} |
| was the name stripped of all leading path information and of trailing |
| suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source |
| file. For example, in @file{allclass.cc}, giving just |
| @samp{#pragma implementation} |
| by itself is equivalent to @samp{#pragma implementation "allclass.h"}. |
| |
| In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as |
| an implementation file whenever you would include it from |
| @file{allclass.cc} even if you never specified @samp{#pragma |
| implementation}. This was deemed to be more trouble than it was worth, |
| however, and disabled. |
| |
| 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 were not inlined, you will get linker errors. |
| |
| @node Template Instantiation |
| @section Where's the Template? |
| @cindex template instantiation |
| |
| C++ templates are the first language feature to require more |
| intelligence from the environment than one usually finds on a UNIX |
| system. Somehow the compiler and linker have to make sure that each |
| template instance occurs exactly once in the executable if it is needed, |
| and not at all otherwise. There are two basic approaches to this |
| problem, which 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. |
| |
| A future version of G++ will support a hybrid model whereby the compiler |
| will emit any instantiations for which the template definition is |
| included in the compile, and store template definitions and |
| instantiation context information into the object file for the rest. |
| The link wrapper will extract that information as necessary and invoke |
| the compiler to produce the remaining instantiations. The linker will |
| then combine duplicate instantiations. |
| |
| In the mean time, you have the following options for dealing with |
| template instantiations: |
| |
| @enumerate |
| @item |
| @opindex frepo |
| Compile your template-using code with @option{-frepo}. The compiler will |
| generate files with the extension @samp{.rpo} listing all of the |
| template instantiations used in the corresponding object files which |
| could be instantiated there; the link wrapper, @samp{collect2}, will |
| then update the @samp{.rpo} files to tell the compiler where to place |
| those instantiations and rebuild any affected object files. The |
| link-time overhead is negligible after the first pass, as the compiler |
| will continue to place the instantiations in the same files. |
| |
| This is your best option for application code written for the Borland |
| model, as it will just work. Code written for the Cfront model will |
| need to be modified so that the template definitions are available at |
| one or more points of instantiation; usually this is as simple as adding |
| @code{#include <tmethods.cc>} to the end of each template header. |
| |
| For library code, if you want the library to provide all of the template |
| instantiations it needs, just try to link all of its object files |
| together; the link will fail, but cause the instantiations to be |
| generated as a side effect. Be warned, however, that this may cause |
| conflicts if multiple libraries try to provide the same instantiations. |
| For greater control, use explicit instantiation as described in the next |
| option. |
| |
| @item |
| @opindex fno-implicit-templates |
| Compile your code with @option{-fno-implicit-templates} to disable the |
| implicit generation of template instances, and explicitly instantiate |
| all the ones you use. This approach requires more knowledge of exactly |
| which instances you need than do the others, but it's less |
| mysterious and allows greater control. You can scatter the explicit |
| instantiations throughout your program, perhaps putting them in the |
| translation units where the instances are used or the translation units |
| that define the templates themselves; you can put all of the explicit |
| instantiations you need into one big file; or you can create small files |
| like |
| |
| @smallexample |
| #include "Foo.h" |
| #include "Foo.cc" |
| |
| template class Foo<int>; |
| template ostream& operator << |
| (ostream&, const Foo<int>&); |
| @end smallexample |
| |
| for each of the instances you need, and create a template instantiation |
| library from those. |
| |
| If you are using Cfront-model code, you can probably get away with not |
| using @option{-fno-implicit-templates} when compiling files that don't |
| @samp{#include} the member template definitions. |
| |
| If you use one big file to do the instantiations, you may want to |
| compile it without @option{-fno-implicit-templates} so you get all of the |
| instances required by your explicit instantiations (but not by any |
| other files) without having to specify them as well. |
| |
| G++ has extended the template instantiation syntax given in the ISO |
| standard to allow forward declaration of explicit instantiations |
| (with @code{extern}), instantiation of the compiler support data for a |
| template class (i.e.@: the vtable) without instantiating any of its |
| members (with @code{inline}), and instantiation of only the static data |
| members of a template class, without the support data or member |
| functions (with (@code{static}): |
| |
| @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 will work fine, but |
| each translation unit will contain instances of each of the templates it |
| uses. In a large program, this can lead to an unacceptable amount of code |
| duplication. |
| @end enumerate |
| |
| @node Bound member functions |
| @section Extracting the function pointer from a bound pointer to member function |
| @cindex pmf |
| @cindex pointer to member function |
| @cindex bound pointer to member function |
| |
| In C++, pointer to member functions (PMFs) are implemented using a wide |
| pointer of sorts to handle all the possible call mechanisms; the PMF |
| needs to store information about how to adjust the @samp{this} pointer, |
| and if the function pointed to is virtual, where to find the vtable, and |
| where in the vtable to look for the member function. If you are using |
| PMFs in an inner loop, you should really reconsider that decision. If |
| that is not an option, you can extract the pointer to the function that |
| would be called for a given object/PMF pair and call it directly inside |
| the inner loop, to save a bit of time. |
| |
| Note that you will still be paying the penalty for the call through a |
| function pointer; on most modern architectures, such a call defeats the |
| branch prediction features of the CPU@. This is also true of normal |
| virtual function calls. |
| |
| The syntax for this extension is |
| |
| @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 init_priority (@var{priority}) |
| @cindex init_priority attribute |
| |
| |
| In Standard C++, objects defined at namespace scope are guaranteed to be |
| initialized in an order in strict accordance with that of their definitions |
| @emph{in a given translation unit}. No guarantee is made for initializations |
| across translation units. However, GNU C++ allows users to control the |
| order of initialization of objects defined at namespace scope with the |
| @code{init_priority} attribute by specifying a relative @var{priority}, |
| a constant integral expression currently bounded between 101 and 65535 |
| inclusive. Lower numbers indicate a higher priority. |
| |
| In the following example, @code{A} would normally be created before |
| @code{B}, but the @code{init_priority} attribute has reversed that order: |
| |
| @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 java_interface attribute |
| |
| This type attribute informs C++ that the class is a Java interface. It may |
| only be applied to classes declared within an @code{extern "Java"} block. |
| Calls to methods declared in this interface will be dispatched using GCJ's |
| interface table mechanism, instead of regular virtual table dispatch. |
| |
| @end table |
| |
| See also @xref{Namespace Association}. |
| |
| @node Namespace Association |
| @section Namespace Association |
| |
| @strong{Caution:} The semantics of this extension are not fully |
| defined. Users should refrain from using this extension as its |
| semantics may change subtly over time. It is possible that 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 Java Exceptions |
| @section Java Exceptions |
| |
| The Java language uses a slightly different exception handling model |
| from C++. Normally, GNU C++ will automatically detect when you are |
| writing C++ code that uses Java exceptions, and handle them |
| appropriately. However, if C++ code only needs to execute destructors |
| when Java exceptions are thrown through it, GCC will guess incorrectly. |
| Sample problematic code is: |
| |
| @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 |
| @c APPLE LOCAL begin for-fsf-4_4 5482863 |
| and are now removed from G++. Code using these operators should be |
| modified to use @code{std::min} and @code{std::max} instead. |
| |
| @c APPLE LOCAL end for-fsf-4_4 5482863 |
| 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 which contained the for statement (rather than just |
| within the for scope). G++ retains this, but issues a warning, if such a |
| variable is accessed outside the for scope. |
| |
| @item Implicit C language |
| Old C system header files did not contain an @code{extern "C" @{@dots{}@}} |
| scope to set the language. On such systems, all header files are |
| implicitly scoped inside a C language scope. Also, an empty prototype |
| @code{()} will be treated as an unspecified number of arguments, rather |
| than no arguments, as C++ demands. |
| @end table |