1 @c Copyright (C) 1988-2016 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
7 @chapter Extensions to the C Language Family
8 @cindex extensions, C language
9 @cindex C language extensions
12 GNU C provides several language features not found in ISO standard C@.
13 (The @option{-pedantic} option directs GCC to print a warning message if
14 any of these features is used.) To test for the availability of these
15 features in conditional compilation, check for a predefined macro
16 @code{__GNUC__}, which is always defined under GCC@.
18 These extensions are available in C and Objective-C@. Most of them are
19 also available in C++. @xref{C++ Extensions,,Extensions to the
20 C++ Language}, for extensions that apply @emph{only} to C++.
22 Some features that are in ISO C99 but not C90 or C++ are also, as
23 extensions, accepted by GCC in C90 mode and in C++.
26 * Statement Exprs:: Putting statements and declarations inside expressions.
27 * Local Labels:: Labels local to a block.
28 * Labels as Values:: Getting pointers to labels, and computed gotos.
29 * Nested Functions:: As in Algol and Pascal, lexical scoping of functions.
30 * Constructing Calls:: Dispatching a call to another function.
31 * Typeof:: @code{typeof}: referring to the type of an expression.
32 * Conditionals:: Omitting the middle operand of a @samp{?:} expression.
33 * __int128:: 128-bit integers---@code{__int128}.
34 * Long Long:: Double-word integers---@code{long long int}.
35 * Complex:: Data types for complex numbers.
36 * Floating Types:: Additional Floating Types.
37 * Half-Precision:: Half-Precision Floating Point.
38 * Decimal Float:: Decimal Floating Types.
39 * Hex Floats:: Hexadecimal floating-point constants.
40 * Fixed-Point:: Fixed-Point Types.
41 * Named Address Spaces::Named address spaces.
42 * Zero Length:: Zero-length arrays.
43 * Empty Structures:: Structures with no members.
44 * Variable Length:: Arrays whose length is computed at run time.
45 * Variadic Macros:: Macros with a variable number of arguments.
46 * Escaped Newlines:: Slightly looser rules for escaped newlines.
47 * Subscripting:: Any array can be subscripted, even if not an lvalue.
48 * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
49 * Pointers to Arrays:: Pointers to arrays with qualifiers work as expected.
50 * Initializers:: Non-constant initializers.
51 * Compound Literals:: Compound literals give structures, unions
53 * Designated Inits:: Labeling elements of initializers.
54 * Case Ranges:: `case 1 ... 9' and such.
55 * Cast to Union:: Casting to union type from any member of the union.
56 * Mixed Declarations:: Mixing declarations and code.
57 * Function Attributes:: Declaring that functions have no side effects,
58 or that they can never return.
59 * Variable Attributes:: Specifying attributes of variables.
60 * Type Attributes:: Specifying attributes of types.
61 * Label Attributes:: Specifying attributes on labels.
62 * Enumerator Attributes:: Specifying attributes on enumerators.
63 * Attribute Syntax:: Formal syntax for attributes.
64 * Function Prototypes:: Prototype declarations and old-style definitions.
65 * C++ Comments:: C++ comments are recognized.
66 * Dollar Signs:: Dollar sign is allowed in identifiers.
67 * Character Escapes:: @samp{\e} stands for the character @key{ESC}.
68 * Alignment:: Inquiring about the alignment of a type or variable.
69 * Inline:: Defining inline functions (as fast as macros).
70 * Volatiles:: What constitutes an access to a volatile object.
71 * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
72 * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
73 * Incomplete Enums:: @code{enum foo;}, with details to follow.
74 * Function Names:: Printable strings which are the name of the current
76 * Return Address:: Getting the return or frame address of a function.
77 * Vector Extensions:: Using vector instructions through built-in functions.
78 * Offsetof:: Special syntax for implementing @code{offsetof}.
79 * __sync Builtins:: Legacy built-in functions for atomic memory access.
80 * __atomic Builtins:: Atomic built-in functions with memory model.
81 * Integer Overflow Builtins:: Built-in functions to perform arithmetics and
82 arithmetic overflow checking.
83 * x86 specific memory model extensions for transactional memory:: x86 memory models.
84 * Object Size Checking:: Built-in functions for limited buffer overflow
86 * Pointer Bounds Checker builtins:: Built-in functions for Pointer Bounds Checker.
87 * Cilk Plus Builtins:: Built-in functions for the Cilk Plus language extension.
88 * Other Builtins:: Other built-in functions.
89 * Target Builtins:: Built-in functions specific to particular targets.
90 * Target Format Checks:: Format checks specific to particular targets.
91 * Pragmas:: Pragmas accepted by GCC.
92 * Unnamed Fields:: Unnamed struct/union fields within structs/unions.
93 * Thread-Local:: Per-thread variables.
94 * Binary constants:: Binary constants using the @samp{0b} prefix.
98 @section Statements and Declarations in Expressions
99 @cindex statements inside expressions
100 @cindex declarations inside expressions
101 @cindex expressions containing statements
102 @cindex macros, statements in expressions
104 @c the above section title wrapped and causes an underfull hbox.. i
105 @c changed it from "within" to "in". --mew 4feb93
106 A compound statement enclosed in parentheses may appear as an expression
107 in GNU C@. This allows you to use loops, switches, and local variables
108 within an expression.
110 Recall that a compound statement is a sequence of statements surrounded
111 by braces; in this construct, parentheses go around the braces. For
115 (@{ int y = foo (); int z;
122 is a valid (though slightly more complex than necessary) expression
123 for the absolute value of @code{foo ()}.
125 The last thing in the compound statement should be an expression
126 followed by a semicolon; the value of this subexpression serves as the
127 value of the entire construct. (If you use some other kind of statement
128 last within the braces, the construct has type @code{void}, and thus
129 effectively no value.)
131 This feature is especially useful in making macro definitions ``safe'' (so
132 that they evaluate each operand exactly once). For example, the
133 ``maximum'' function is commonly defined as a macro in standard C as
137 #define max(a,b) ((a) > (b) ? (a) : (b))
141 @cindex side effects, macro argument
142 But this definition computes either @var{a} or @var{b} twice, with bad
143 results if the operand has side effects. In GNU C, if you know the
144 type of the operands (here taken as @code{int}), you can define
145 the macro safely as follows:
148 #define maxint(a,b) \
149 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
152 Embedded statements are not allowed in constant expressions, such as
153 the value of an enumeration constant, the width of a bit-field, or
154 the initial value of a static variable.
156 If you don't know the type of the operand, you can still do this, but you
157 must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}).
159 In G++, the result value of a statement expression undergoes array and
160 function pointer decay, and is returned by value to the enclosing
161 expression. For instance, if @code{A} is a class, then
170 constructs a temporary @code{A} object to hold the result of the
171 statement expression, and that is used to invoke @code{Foo}.
172 Therefore the @code{this} pointer observed by @code{Foo} is not the
175 In a statement expression, any temporaries created within a statement
176 are destroyed at that statement's end. This makes statement
177 expressions inside macros slightly different from function calls. In
178 the latter case temporaries introduced during argument evaluation are
179 destroyed at the end of the statement that includes the function
180 call. In the statement expression case they are destroyed during
181 the statement expression. For instance,
184 #define macro(a) (@{__typeof__(a) b = (a); b + 3; @})
185 template<typename T> T function(T a) @{ T b = a; return b + 3; @}
195 has different places where temporaries are destroyed. For the
196 @code{macro} case, the temporary @code{X} is destroyed just after
197 the initialization of @code{b}. In the @code{function} case that
198 temporary is destroyed when the function returns.
200 These considerations mean that it is probably a bad idea to use
201 statement expressions of this form in header files that are designed to
202 work with C++. (Note that some versions of the GNU C Library contained
203 header files using statement expressions that lead to precisely this
206 Jumping into a statement expression with @code{goto} or using a
207 @code{switch} statement outside the statement expression with a
208 @code{case} or @code{default} label inside the statement expression is
209 not permitted. Jumping into a statement expression with a computed
210 @code{goto} (@pxref{Labels as Values}) has undefined behavior.
211 Jumping out of a statement expression is permitted, but if the
212 statement expression is part of a larger expression then it is
213 unspecified which other subexpressions of that expression have been
214 evaluated except where the language definition requires certain
215 subexpressions to be evaluated before or after the statement
216 expression. In any case, as with a function call, the evaluation of a
217 statement expression is not interleaved with the evaluation of other
218 parts of the containing expression. For example,
221 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();
225 calls @code{foo} and @code{bar1} and does not call @code{baz} but
226 may or may not call @code{bar2}. If @code{bar2} is called, it is
227 called after @code{foo} and before @code{bar1}.
230 @section Locally Declared Labels
232 @cindex macros, local labels
234 GCC allows you to declare @dfn{local labels} in any nested block
235 scope. A local label is just like an ordinary label, but you can
236 only reference it (with a @code{goto} statement, or by taking its
237 address) within the block in which it is declared.
239 A local label declaration looks like this:
242 __label__ @var{label};
249 __label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
252 Local label declarations must come at the beginning of the block,
253 before any ordinary declarations or statements.
255 The label declaration defines the label @emph{name}, but does not define
256 the label itself. You must do this in the usual way, with
257 @code{@var{label}:}, within the statements of the statement expression.
259 The local label feature is useful for complex macros. If a macro
260 contains nested loops, a @code{goto} can be useful for breaking out of
261 them. However, an ordinary label whose scope is the whole function
262 cannot be used: if the macro can be expanded several times in one
263 function, the label is multiply defined in that function. A
264 local label avoids this problem. For example:
267 #define SEARCH(value, array, target) \
270 typeof (target) _SEARCH_target = (target); \
271 typeof (*(array)) *_SEARCH_array = (array); \
274 for (i = 0; i < max; i++) \
275 for (j = 0; j < max; j++) \
276 if (_SEARCH_array[i][j] == _SEARCH_target) \
277 @{ (value) = i; goto found; @} \
283 This could also be written using a statement expression:
286 #define SEARCH(array, target) \
289 typeof (target) _SEARCH_target = (target); \
290 typeof (*(array)) *_SEARCH_array = (array); \
293 for (i = 0; i < max; i++) \
294 for (j = 0; j < max; j++) \
295 if (_SEARCH_array[i][j] == _SEARCH_target) \
296 @{ value = i; goto found; @} \
303 Local label declarations also make the labels they declare visible to
304 nested functions, if there are any. @xref{Nested Functions}, for details.
306 @node Labels as Values
307 @section Labels as Values
308 @cindex labels as values
309 @cindex computed gotos
310 @cindex goto with computed label
311 @cindex address of a label
313 You can get the address of a label defined in the current function
314 (or a containing function) with the unary operator @samp{&&}. The
315 value has type @code{void *}. This value is a constant and can be used
316 wherever a constant of that type is valid. For example:
324 To use these values, you need to be able to jump to one. This is done
325 with the computed goto statement@footnote{The analogous feature in
326 Fortran is called an assigned goto, but that name seems inappropriate in
327 C, where one can do more than simply store label addresses in label
328 variables.}, @code{goto *@var{exp};}. For example,
335 Any expression of type @code{void *} is allowed.
337 One way of using these constants is in initializing a static array that
338 serves as a jump table:
341 static void *array[] = @{ &&foo, &&bar, &&hack @};
345 Then you can select a label with indexing, like this:
352 Note that this does not check whether the subscript is in bounds---array
353 indexing in C never does that.
355 Such an array of label values serves a purpose much like that of the
356 @code{switch} statement. The @code{switch} statement is cleaner, so
357 use that rather than an array unless the problem does not fit a
358 @code{switch} statement very well.
360 Another use of label values is in an interpreter for threaded code.
361 The labels within the interpreter function can be stored in the
362 threaded code for super-fast dispatching.
364 You may not use this mechanism to jump to code in a different function.
365 If you do that, totally unpredictable things happen. The best way to
366 avoid this is to store the label address only in automatic variables and
367 never pass it as an argument.
369 An alternate way to write the above example is
372 static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
374 goto *(&&foo + array[i]);
378 This is more friendly to code living in shared libraries, as it reduces
379 the number of dynamic relocations that are needed, and by consequence,
380 allows the data to be read-only.
381 This alternative with label differences is not supported for the AVR target,
382 please use the first approach for AVR programs.
384 The @code{&&foo} expressions for the same label might have different
385 values if the containing function is inlined or cloned. If a program
386 relies on them being always the same,
387 @code{__attribute__((__noinline__,__noclone__))} should be used to
388 prevent inlining and cloning. If @code{&&foo} is used in a static
389 variable initializer, inlining and cloning is forbidden.
391 @node Nested Functions
392 @section Nested Functions
393 @cindex nested functions
394 @cindex downward funargs
397 A @dfn{nested function} is a function defined inside another function.
398 Nested functions are supported as an extension in GNU C, but are not
399 supported by GNU C++.
401 The nested function's name is local to the block where it is defined.
402 For example, here we define a nested function named @code{square}, and
407 foo (double a, double b)
409 double square (double z) @{ return z * z; @}
411 return square (a) + square (b);
416 The nested function can access all the variables of the containing
417 function that are visible at the point of its definition. This is
418 called @dfn{lexical scoping}. For example, here we show a nested
419 function which uses an inherited variable named @code{offset}:
423 bar (int *array, int offset, int size)
425 int access (int *array, int index)
426 @{ return array[index + offset]; @}
429 for (i = 0; i < size; i++)
430 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
435 Nested function definitions are permitted within functions in the places
436 where variable definitions are allowed; that is, in any block, mixed
437 with the other declarations and statements in the block.
439 It is possible to call the nested function from outside the scope of its
440 name by storing its address or passing the address to another function:
443 hack (int *array, int size)
445 void store (int index, int value)
446 @{ array[index] = value; @}
448 intermediate (store, size);
452 Here, the function @code{intermediate} receives the address of
453 @code{store} as an argument. If @code{intermediate} calls @code{store},
454 the arguments given to @code{store} are used to store into @code{array}.
455 But this technique works only so long as the containing function
456 (@code{hack}, in this example) does not exit.
458 If you try to call the nested function through its address after the
459 containing function exits, all hell breaks loose. If you try
460 to call it after a containing scope level exits, and if it refers
461 to some of the variables that are no longer in scope, you may be lucky,
462 but it's not wise to take the risk. If, however, the nested function
463 does not refer to anything that has gone out of scope, you should be
466 GCC implements taking the address of a nested function using a technique
467 called @dfn{trampolines}. This technique was described in
468 @cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX
469 C++ Conference Proceedings, October 17-21, 1988).
471 A nested function can jump to a label inherited from a containing
472 function, provided the label is explicitly declared in the containing
473 function (@pxref{Local Labels}). Such a jump returns instantly to the
474 containing function, exiting the nested function that did the
475 @code{goto} and any intermediate functions as well. Here is an example:
479 bar (int *array, int offset, int size)
482 int access (int *array, int index)
486 return array[index + offset];
490 for (i = 0; i < size; i++)
491 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
495 /* @r{Control comes here from @code{access}
496 if it detects an error.} */
503 A nested function always has no linkage. Declaring one with
504 @code{extern} or @code{static} is erroneous. If you need to declare the nested function
505 before its definition, use @code{auto} (which is otherwise meaningless
506 for function declarations).
509 bar (int *array, int offset, int size)
512 auto int access (int *, int);
514 int access (int *array, int index)
518 return array[index + offset];
524 @node Constructing Calls
525 @section Constructing Function Calls
526 @cindex constructing calls
527 @cindex forwarding calls
529 Using the built-in functions described below, you can record
530 the arguments a function received, and call another function
531 with the same arguments, without knowing the number or types
534 You can also record the return value of that function call,
535 and later return that value, without knowing what data type
536 the function tried to return (as long as your caller expects
539 However, these built-in functions may interact badly with some
540 sophisticated features or other extensions of the language. It
541 is, therefore, not recommended to use them outside very simple
542 functions acting as mere forwarders for their arguments.
544 @deftypefn {Built-in Function} {void *} __builtin_apply_args ()
545 This built-in function returns a pointer to data
546 describing how to perform a call with the same arguments as are passed
547 to the current function.
549 The function saves the arg pointer register, structure value address,
550 and all registers that might be used to pass arguments to a function
551 into a block of memory allocated on the stack. Then it returns the
552 address of that block.
555 @deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})
556 This built-in function invokes @var{function}
557 with a copy of the parameters described by @var{arguments}
560 The value of @var{arguments} should be the value returned by
561 @code{__builtin_apply_args}. The argument @var{size} specifies the size
562 of the stack argument data, in bytes.
564 This function returns a pointer to data describing
565 how to return whatever value is returned by @var{function}. The data
566 is saved in a block of memory allocated on the stack.
568 It is not always simple to compute the proper value for @var{size}. The
569 value is used by @code{__builtin_apply} to compute the amount of data
570 that should be pushed on the stack and copied from the incoming argument
574 @deftypefn {Built-in Function} {void} __builtin_return (void *@var{result})
575 This built-in function returns the value described by @var{result} from
576 the containing function. You should specify, for @var{result}, a value
577 returned by @code{__builtin_apply}.
580 @deftypefn {Built-in Function} {} __builtin_va_arg_pack ()
581 This built-in function represents all anonymous arguments of an inline
582 function. It can be used only in inline functions that are always
583 inlined, never compiled as a separate function, such as those using
584 @code{__attribute__ ((__always_inline__))} or
585 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
586 It must be only passed as last argument to some other function
587 with variable arguments. This is useful for writing small wrapper
588 inlines for variable argument functions, when using preprocessor
589 macros is undesirable. For example:
591 extern int myprintf (FILE *f, const char *format, ...);
592 extern inline __attribute__ ((__gnu_inline__)) int
593 myprintf (FILE *f, const char *format, ...)
595 int r = fprintf (f, "myprintf: ");
598 int s = fprintf (f, format, __builtin_va_arg_pack ());
606 @deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len ()
607 This built-in function returns the number of anonymous arguments of
608 an inline function. It can be used only in inline functions that
609 are always inlined, never compiled as a separate function, such
610 as those using @code{__attribute__ ((__always_inline__))} or
611 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
612 For example following does link- or run-time checking of open
613 arguments for optimized code:
616 extern inline __attribute__((__gnu_inline__)) int
617 myopen (const char *path, int oflag, ...)
619 if (__builtin_va_arg_pack_len () > 1)
620 warn_open_too_many_arguments ();
622 if (__builtin_constant_p (oflag))
624 if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
626 warn_open_missing_mode ();
627 return __open_2 (path, oflag);
629 return open (path, oflag, __builtin_va_arg_pack ());
632 if (__builtin_va_arg_pack_len () < 1)
633 return __open_2 (path, oflag);
635 return open (path, oflag, __builtin_va_arg_pack ());
642 @section Referring to a Type with @code{typeof}
645 @cindex macros, types of arguments
647 Another way to refer to the type of an expression is with @code{typeof}.
648 The syntax of using of this keyword looks like @code{sizeof}, but the
649 construct acts semantically like a type name defined with @code{typedef}.
651 There are two ways of writing the argument to @code{typeof}: with an
652 expression or with a type. Here is an example with an expression:
659 This assumes that @code{x} is an array of pointers to functions;
660 the type described is that of the values of the functions.
662 Here is an example with a typename as the argument:
669 Here the type described is that of pointers to @code{int}.
671 If you are writing a header file that must work when included in ISO C
672 programs, write @code{__typeof__} instead of @code{typeof}.
673 @xref{Alternate Keywords}.
675 A @code{typeof} construct can be used anywhere a typedef name can be
676 used. For example, you can use it in a declaration, in a cast, or inside
677 of @code{sizeof} or @code{typeof}.
679 The operand of @code{typeof} is evaluated for its side effects if and
680 only if it is an expression of variably modified type or the name of
683 @code{typeof} is often useful in conjunction with
684 statement expressions (@pxref{Statement Exprs}).
685 Here is how the two together can
686 be used to define a safe ``maximum'' macro which operates on any
687 arithmetic type and evaluates each of its arguments exactly once:
691 (@{ typeof (a) _a = (a); \
692 typeof (b) _b = (b); \
693 _a > _b ? _a : _b; @})
696 @cindex underscores in variables in macros
697 @cindex @samp{_} in variables in macros
698 @cindex local variables in macros
699 @cindex variables, local, in macros
700 @cindex macros, local variables in
702 The reason for using names that start with underscores for the local
703 variables is to avoid conflicts with variable names that occur within the
704 expressions that are substituted for @code{a} and @code{b}. Eventually we
705 hope to design a new form of declaration syntax that allows you to declare
706 variables whose scopes start only after their initializers; this will be a
707 more reliable way to prevent such conflicts.
710 Some more examples of the use of @code{typeof}:
714 This declares @code{y} with the type of what @code{x} points to.
721 This declares @code{y} as an array of such values.
728 This declares @code{y} as an array of pointers to characters:
731 typeof (typeof (char *)[4]) y;
735 It is equivalent to the following traditional C declaration:
741 To see the meaning of the declaration using @code{typeof}, and why it
742 might be a useful way to write, rewrite it with these macros:
745 #define pointer(T) typeof(T *)
746 #define array(T, N) typeof(T [N])
750 Now the declaration can be rewritten this way:
753 array (pointer (char), 4) y;
757 Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
758 pointers to @code{char}.
761 In GNU C, but not GNU C++, you may also declare the type of a variable
762 as @code{__auto_type}. In that case, the declaration must declare
763 only one variable, whose declarator must just be an identifier, the
764 declaration must be initialized, and the type of the variable is
765 determined by the initializer; the name of the variable is not in
766 scope until after the initializer. (In C++, you should use C++11
767 @code{auto} for this purpose.) Using @code{__auto_type}, the
768 ``maximum'' macro above could be written as:
772 (@{ __auto_type _a = (a); \
773 __auto_type _b = (b); \
774 _a > _b ? _a : _b; @})
777 Using @code{__auto_type} instead of @code{typeof} has two advantages:
780 @item Each argument to the macro appears only once in the expansion of
781 the macro. This prevents the size of the macro expansion growing
782 exponentially when calls to such macros are nested inside arguments of
785 @item If the argument to the macro has variably modified type, it is
786 evaluated only once when using @code{__auto_type}, but twice if
787 @code{typeof} is used.
791 @section Conditionals with Omitted Operands
792 @cindex conditional expressions, extensions
793 @cindex omitted middle-operands
794 @cindex middle-operands, omitted
795 @cindex extensions, @code{?:}
796 @cindex @code{?:} extensions
798 The middle operand in a conditional expression may be omitted. Then
799 if the first operand is nonzero, its value is the value of the conditional
802 Therefore, the expression
809 has the value of @code{x} if that is nonzero; otherwise, the value of
812 This example is perfectly equivalent to
818 @cindex side effect in @code{?:}
819 @cindex @code{?:} side effect
821 In this simple case, the ability to omit the middle operand is not
822 especially useful. When it becomes useful is when the first operand does,
823 or may (if it is a macro argument), contain a side effect. Then repeating
824 the operand in the middle would perform the side effect twice. Omitting
825 the middle operand uses the value already computed without the undesirable
826 effects of recomputing it.
829 @section 128-bit Integers
830 @cindex @code{__int128} data types
832 As an extension the integer scalar type @code{__int128} is supported for
833 targets which have an integer mode wide enough to hold 128 bits.
834 Simply write @code{__int128} for a signed 128-bit integer, or
835 @code{unsigned __int128} for an unsigned 128-bit integer. There is no
836 support in GCC for expressing an integer constant of type @code{__int128}
837 for targets with @code{long long} integer less than 128 bits wide.
840 @section Double-Word Integers
841 @cindex @code{long long} data types
842 @cindex double-word arithmetic
843 @cindex multiprecision arithmetic
844 @cindex @code{LL} integer suffix
845 @cindex @code{ULL} integer suffix
847 ISO C99 supports data types for integers that are at least 64 bits wide,
848 and as an extension GCC supports them in C90 mode and in C++.
849 Simply write @code{long long int} for a signed integer, or
850 @code{unsigned long long int} for an unsigned integer. To make an
851 integer constant of type @code{long long int}, add the suffix @samp{LL}
852 to the integer. To make an integer constant of type @code{unsigned long
853 long int}, add the suffix @samp{ULL} to the integer.
855 You can use these types in arithmetic like any other integer types.
856 Addition, subtraction, and bitwise boolean operations on these types
857 are open-coded on all types of machines. Multiplication is open-coded
858 if the machine supports a fullword-to-doubleword widening multiply
859 instruction. Division and shifts are open-coded only on machines that
860 provide special support. The operations that are not open-coded use
861 special library routines that come with GCC@.
863 There may be pitfalls when you use @code{long long} types for function
864 arguments without function prototypes. If a function
865 expects type @code{int} for its argument, and you pass a value of type
866 @code{long long int}, confusion results because the caller and the
867 subroutine disagree about the number of bytes for the argument.
868 Likewise, if the function expects @code{long long int} and you pass
869 @code{int}. The best way to avoid such problems is to use prototypes.
872 @section Complex Numbers
873 @cindex complex numbers
874 @cindex @code{_Complex} keyword
875 @cindex @code{__complex__} keyword
877 ISO C99 supports complex floating data types, and as an extension GCC
878 supports them in C90 mode and in C++. GCC also supports complex integer data
879 types which are not part of ISO C99. You can declare complex types
880 using the keyword @code{_Complex}. As an extension, the older GNU
881 keyword @code{__complex__} is also supported.
883 For example, @samp{_Complex double x;} declares @code{x} as a
884 variable whose real part and imaginary part are both of type
885 @code{double}. @samp{_Complex short int y;} declares @code{y} to
886 have real and imaginary parts of type @code{short int}; this is not
887 likely to be useful, but it shows that the set of complex types is
890 To write a constant with a complex data type, use the suffix @samp{i} or
891 @samp{j} (either one; they are equivalent). For example, @code{2.5fi}
892 has type @code{_Complex float} and @code{3i} has type
893 @code{_Complex int}. Such a constant always has a pure imaginary
894 value, but you can form any complex value you like by adding one to a
895 real constant. This is a GNU extension; if you have an ISO C99
896 conforming C library (such as the GNU C Library), and want to construct complex
897 constants of floating type, you should include @code{<complex.h>} and
898 use the macros @code{I} or @code{_Complex_I} instead.
900 @cindex @code{__real__} keyword
901 @cindex @code{__imag__} keyword
902 To extract the real part of a complex-valued expression @var{exp}, write
903 @code{__real__ @var{exp}}. Likewise, use @code{__imag__} to
904 extract the imaginary part. This is a GNU extension; for values of
905 floating type, you should use the ISO C99 functions @code{crealf},
906 @code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
907 @code{cimagl}, declared in @code{<complex.h>} and also provided as
908 built-in functions by GCC@.
910 @cindex complex conjugation
911 The operator @samp{~} performs complex conjugation when used on a value
912 with a complex type. This is a GNU extension; for values of
913 floating type, you should use the ISO C99 functions @code{conjf},
914 @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
915 provided as built-in functions by GCC@.
917 GCC can allocate complex automatic variables in a noncontiguous
918 fashion; it's even possible for the real part to be in a register while
919 the imaginary part is on the stack (or vice versa). Only the DWARF 2
920 debug info format can represent this, so use of DWARF 2 is recommended.
921 If you are using the stabs debug info format, GCC describes a noncontiguous
922 complex variable as if it were two separate variables of noncomplex type.
923 If the variable's actual name is @code{foo}, the two fictitious
924 variables are named @code{foo$real} and @code{foo$imag}. You can
925 examine and set these two fictitious variables with your debugger.
928 @section Additional Floating Types
929 @cindex additional floating types
930 @cindex @code{__float80} data type
931 @cindex @code{__float128} data type
932 @cindex @code{__ibm128} data type
933 @cindex @code{w} floating point suffix
934 @cindex @code{q} floating point suffix
935 @cindex @code{W} floating point suffix
936 @cindex @code{Q} floating point suffix
938 As an extension, GNU C supports additional floating
939 types, @code{__float80} and @code{__float128} to support 80-bit
940 (@code{XFmode}) and 128-bit (@code{TFmode}) floating types.
941 Support for additional types includes the arithmetic operators:
942 add, subtract, multiply, divide; unary arithmetic operators;
943 relational operators; equality operators; and conversions to and from
944 integer and other floating types. Use a suffix @samp{w} or @samp{W}
945 in a literal constant of type @code{__float80} or type
946 @code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{_float128}.
948 On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex
949 types using the corresponding internal complex type, @code{XCmode} for
950 @code{__float80} type and @code{TCmode} for @code{__float128} type:
953 typedef _Complex float __attribute__((mode(TC))) _Complex128;
954 typedef _Complex float __attribute__((mode(XC))) _Complex80;
957 On PowerPC 64-bit Linux systems there are currently problems in using
958 the complex @code{__float128} type. When these problems are fixed,
962 typedef _Complex float __attribute__((mode(KC))) _Complex128;
965 Not all targets support additional floating-point types.
966 @code{__float80} and @code{__float128} types are supported on x86 and
967 IA-64 targets. The @code{__float128} type is supported on hppa HP-UX.
968 The @code{__float128} type is supported on PowerPC 64-bit Linux
969 systems by default if the vector scalar instruction set (VSX) is
972 On the PowerPC, @code{__ibm128} provides access to the IBM extended
973 double format, and it is intended to be used by the library functions
974 that handle conversions if/when long double is changed to be IEEE
975 128-bit floating point.
978 @section Half-Precision Floating Point
979 @cindex half-precision floating point
980 @cindex @code{__fp16} data type
982 On ARM targets, GCC supports half-precision (16-bit) floating point via
983 the @code{__fp16} type. You must enable this type explicitly
984 with the @option{-mfp16-format} command-line option in order to use it.
986 ARM supports two incompatible representations for half-precision
987 floating-point values. You must choose one of the representations and
988 use it consistently in your program.
990 Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
991 This format can represent normalized values in the range of @math{2^{-14}} to 65504.
992 There are 11 bits of significand precision, approximately 3
995 Specifying @option{-mfp16-format=alternative} selects the ARM
996 alternative format. This representation is similar to the IEEE
997 format, but does not support infinities or NaNs. Instead, the range
998 of exponents is extended, so that this format can represent normalized
999 values in the range of @math{2^{-14}} to 131008.
1001 The @code{__fp16} type is a storage format only. For purposes
1002 of arithmetic and other operations, @code{__fp16} values in C or C++
1003 expressions are automatically promoted to @code{float}. In addition,
1004 you cannot declare a function with a return value or parameters
1005 of type @code{__fp16}.
1007 Note that conversions from @code{double} to @code{__fp16}
1008 involve an intermediate conversion to @code{float}. Because
1009 of rounding, this can sometimes produce a different result than a
1012 ARM provides hardware support for conversions between
1013 @code{__fp16} and @code{float} values
1014 as an extension to VFP and NEON (Advanced SIMD). GCC generates
1015 code using these hardware instructions if you compile with
1016 options to select an FPU that provides them;
1017 for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
1018 in addition to the @option{-mfp16-format} option to select
1019 a half-precision format.
1021 Language-level support for the @code{__fp16} data type is
1022 independent of whether GCC generates code using hardware floating-point
1023 instructions. In cases where hardware support is not specified, GCC
1024 implements conversions between @code{__fp16} and @code{float} values
1028 @section Decimal Floating Types
1029 @cindex decimal floating types
1030 @cindex @code{_Decimal32} data type
1031 @cindex @code{_Decimal64} data type
1032 @cindex @code{_Decimal128} data type
1033 @cindex @code{df} integer suffix
1034 @cindex @code{dd} integer suffix
1035 @cindex @code{dl} integer suffix
1036 @cindex @code{DF} integer suffix
1037 @cindex @code{DD} integer suffix
1038 @cindex @code{DL} integer suffix
1040 As an extension, GNU C supports decimal floating types as
1041 defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal
1042 floating types in GCC will evolve as the draft technical report changes.
1043 Calling conventions for any target might also change. Not all targets
1044 support decimal floating types.
1046 The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
1047 @code{_Decimal128}. They use a radix of ten, unlike the floating types
1048 @code{float}, @code{double}, and @code{long double} whose radix is not
1049 specified by the C standard but is usually two.
1051 Support for decimal floating types includes the arithmetic operators
1052 add, subtract, multiply, divide; unary arithmetic operators;
1053 relational operators; equality operators; and conversions to and from
1054 integer and other floating types. Use a suffix @samp{df} or
1055 @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
1056 or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
1059 GCC support of decimal float as specified by the draft technical report
1064 When the value of a decimal floating type cannot be represented in the
1065 integer type to which it is being converted, the result is undefined
1066 rather than the result value specified by the draft technical report.
1069 GCC does not provide the C library functionality associated with
1070 @file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
1071 @file{wchar.h}, which must come from a separate C library implementation.
1072 Because of this the GNU C compiler does not define macro
1073 @code{__STDC_DEC_FP__} to indicate that the implementation conforms to
1074 the technical report.
1077 Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
1078 are supported by the DWARF 2 debug information format.
1084 ISO C99 supports floating-point numbers written not only in the usual
1085 decimal notation, such as @code{1.55e1}, but also numbers such as
1086 @code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
1087 supports this in C90 mode (except in some cases when strictly
1088 conforming) and in C++. In that format the
1089 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
1090 mandatory. The exponent is a decimal number that indicates the power of
1091 2 by which the significant part is multiplied. Thus @samp{0x1.f} is
1098 @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
1099 is the same as @code{1.55e1}.
1101 Unlike for floating-point numbers in the decimal notation the exponent
1102 is always required in the hexadecimal notation. Otherwise the compiler
1103 would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
1104 could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
1105 extension for floating-point constants of type @code{float}.
1108 @section Fixed-Point Types
1109 @cindex fixed-point types
1110 @cindex @code{_Fract} data type
1111 @cindex @code{_Accum} data type
1112 @cindex @code{_Sat} data type
1113 @cindex @code{hr} fixed-suffix
1114 @cindex @code{r} fixed-suffix
1115 @cindex @code{lr} fixed-suffix
1116 @cindex @code{llr} fixed-suffix
1117 @cindex @code{uhr} fixed-suffix
1118 @cindex @code{ur} fixed-suffix
1119 @cindex @code{ulr} fixed-suffix
1120 @cindex @code{ullr} fixed-suffix
1121 @cindex @code{hk} fixed-suffix
1122 @cindex @code{k} fixed-suffix
1123 @cindex @code{lk} fixed-suffix
1124 @cindex @code{llk} fixed-suffix
1125 @cindex @code{uhk} fixed-suffix
1126 @cindex @code{uk} fixed-suffix
1127 @cindex @code{ulk} fixed-suffix
1128 @cindex @code{ullk} fixed-suffix
1129 @cindex @code{HR} fixed-suffix
1130 @cindex @code{R} fixed-suffix
1131 @cindex @code{LR} fixed-suffix
1132 @cindex @code{LLR} fixed-suffix
1133 @cindex @code{UHR} fixed-suffix
1134 @cindex @code{UR} fixed-suffix
1135 @cindex @code{ULR} fixed-suffix
1136 @cindex @code{ULLR} fixed-suffix
1137 @cindex @code{HK} fixed-suffix
1138 @cindex @code{K} fixed-suffix
1139 @cindex @code{LK} fixed-suffix
1140 @cindex @code{LLK} fixed-suffix
1141 @cindex @code{UHK} fixed-suffix
1142 @cindex @code{UK} fixed-suffix
1143 @cindex @code{ULK} fixed-suffix
1144 @cindex @code{ULLK} fixed-suffix
1146 As an extension, GNU C supports fixed-point types as
1147 defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point
1148 types in GCC will evolve as the draft technical report changes.
1149 Calling conventions for any target might also change. Not all targets
1150 support fixed-point types.
1152 The fixed-point types are
1153 @code{short _Fract},
1156 @code{long long _Fract},
1157 @code{unsigned short _Fract},
1158 @code{unsigned _Fract},
1159 @code{unsigned long _Fract},
1160 @code{unsigned long long _Fract},
1161 @code{_Sat short _Fract},
1163 @code{_Sat long _Fract},
1164 @code{_Sat long long _Fract},
1165 @code{_Sat unsigned short _Fract},
1166 @code{_Sat unsigned _Fract},
1167 @code{_Sat unsigned long _Fract},
1168 @code{_Sat unsigned long long _Fract},
1169 @code{short _Accum},
1172 @code{long long _Accum},
1173 @code{unsigned short _Accum},
1174 @code{unsigned _Accum},
1175 @code{unsigned long _Accum},
1176 @code{unsigned long long _Accum},
1177 @code{_Sat short _Accum},
1179 @code{_Sat long _Accum},
1180 @code{_Sat long long _Accum},
1181 @code{_Sat unsigned short _Accum},
1182 @code{_Sat unsigned _Accum},
1183 @code{_Sat unsigned long _Accum},
1184 @code{_Sat unsigned long long _Accum}.
1186 Fixed-point data values contain fractional and optional integral parts.
1187 The format of fixed-point data varies and depends on the target machine.
1189 Support for fixed-point types includes:
1192 prefix and postfix increment and decrement operators (@code{++}, @code{--})
1194 unary arithmetic operators (@code{+}, @code{-}, @code{!})
1196 binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
1198 binary shift operators (@code{<<}, @code{>>})
1200 relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
1202 equality operators (@code{==}, @code{!=})
1204 assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
1205 @code{<<=}, @code{>>=})
1207 conversions to and from integer, floating-point, or fixed-point types
1210 Use a suffix in a fixed-point literal constant:
1212 @item @samp{hr} or @samp{HR} for @code{short _Fract} and
1213 @code{_Sat short _Fract}
1214 @item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
1215 @item @samp{lr} or @samp{LR} for @code{long _Fract} and
1216 @code{_Sat long _Fract}
1217 @item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
1218 @code{_Sat long long _Fract}
1219 @item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
1220 @code{_Sat unsigned short _Fract}
1221 @item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
1222 @code{_Sat unsigned _Fract}
1223 @item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
1224 @code{_Sat unsigned long _Fract}
1225 @item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
1226 and @code{_Sat unsigned long long _Fract}
1227 @item @samp{hk} or @samp{HK} for @code{short _Accum} and
1228 @code{_Sat short _Accum}
1229 @item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
1230 @item @samp{lk} or @samp{LK} for @code{long _Accum} and
1231 @code{_Sat long _Accum}
1232 @item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
1233 @code{_Sat long long _Accum}
1234 @item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
1235 @code{_Sat unsigned short _Accum}
1236 @item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
1237 @code{_Sat unsigned _Accum}
1238 @item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
1239 @code{_Sat unsigned long _Accum}
1240 @item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
1241 and @code{_Sat unsigned long long _Accum}
1244 GCC support of fixed-point types as specified by the draft technical report
1249 Pragmas to control overflow and rounding behaviors are not implemented.
1252 Fixed-point types are supported by the DWARF 2 debug information format.
1254 @node Named Address Spaces
1255 @section Named Address Spaces
1256 @cindex Named Address Spaces
1258 As an extension, GNU C supports named address spaces as
1259 defined in the N1275 draft of ISO/IEC DTR 18037. Support for named
1260 address spaces in GCC will evolve as the draft technical report
1261 changes. Calling conventions for any target might also change. At
1262 present, only the AVR, SPU, M32C, RL78, and x86 targets support
1263 address spaces other than the generic address space.
1265 Address space identifiers may be used exactly like any other C type
1266 qualifier (e.g., @code{const} or @code{volatile}). See the N1275
1267 document for more details.
1269 @anchor{AVR Named Address Spaces}
1270 @subsection AVR Named Address Spaces
1272 On the AVR target, there are several address spaces that can be used
1273 in order to put read-only data into the flash memory and access that
1274 data by means of the special instructions @code{LPM} or @code{ELPM}
1275 needed to read from flash.
1277 Per default, any data including read-only data is located in RAM
1278 (the generic address space) so that non-generic address spaces are
1279 needed to locate read-only data in flash memory
1280 @emph{and} to generate the right instructions to access this data
1281 without using (inline) assembler code.
1285 @cindex @code{__flash} AVR Named Address Spaces
1286 The @code{__flash} qualifier locates data in the
1287 @code{.progmem.data} section. Data is read using the @code{LPM}
1288 instruction. Pointers to this address space are 16 bits wide.
1295 @cindex @code{__flash1} AVR Named Address Spaces
1296 @cindex @code{__flash2} AVR Named Address Spaces
1297 @cindex @code{__flash3} AVR Named Address Spaces
1298 @cindex @code{__flash4} AVR Named Address Spaces
1299 @cindex @code{__flash5} AVR Named Address Spaces
1300 These are 16-bit address spaces locating data in section
1301 @code{.progmem@var{N}.data} where @var{N} refers to
1302 address space @code{__flash@var{N}}.
1303 The compiler sets the @code{RAMPZ} segment register appropriately
1304 before reading data by means of the @code{ELPM} instruction.
1307 @cindex @code{__memx} AVR Named Address Spaces
1308 This is a 24-bit address space that linearizes flash and RAM:
1309 If the high bit of the address is set, data is read from
1310 RAM using the lower two bytes as RAM address.
1311 If the high bit of the address is clear, data is read from flash
1312 with @code{RAMPZ} set according to the high byte of the address.
1313 @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
1315 Objects in this address space are located in @code{.progmemx.data}.
1321 char my_read (const __flash char ** p)
1323 /* p is a pointer to RAM that points to a pointer to flash.
1324 The first indirection of p reads that flash pointer
1325 from RAM and the second indirection reads a char from this
1331 /* Locate array[] in flash memory */
1332 const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
1338 /* Return 17 by reading from flash memory */
1339 return array[array[i]];
1344 For each named address space supported by avr-gcc there is an equally
1345 named but uppercase built-in macro defined.
1346 The purpose is to facilitate testing if respective address space
1347 support is available or not:
1351 const __flash int var = 1;
1358 #include <avr/pgmspace.h> /* From AVR-LibC */
1360 const int var PROGMEM = 1;
1364 return (int) pgm_read_word (&var);
1366 #endif /* __FLASH */
1370 Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
1371 locates data in flash but
1372 accesses to these data read from generic address space, i.e.@:
1374 so that you need special accessors like @code{pgm_read_byte}
1375 from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}}
1376 together with attribute @code{progmem}.
1379 @b{Limitations and caveats}
1383 Reading across the 64@tie{}KiB section boundary of
1384 the @code{__flash} or @code{__flash@var{N}} address spaces
1385 shows undefined behavior. The only address space that
1386 supports reading across the 64@tie{}KiB flash segment boundaries is
1390 If you use one of the @code{__flash@var{N}} address spaces
1391 you must arrange your linker script to locate the
1392 @code{.progmem@var{N}.data} sections according to your needs.
1395 Any data or pointers to the non-generic address spaces must
1396 be qualified as @code{const}, i.e.@: as read-only data.
1397 This still applies if the data in one of these address
1398 spaces like software version number or calibration lookup table are intended to
1399 be changed after load time by, say, a boot loader. In this case
1400 the right qualification is @code{const} @code{volatile} so that the compiler
1401 must not optimize away known values or insert them
1402 as immediates into operands of instructions.
1405 The following code initializes a variable @code{pfoo}
1406 located in static storage with a 24-bit address:
1408 extern const __memx char foo;
1409 const __memx void *pfoo = &foo;
1413 Such code requires at least binutils 2.23, see
1414 @w{@uref{http://sourceware.org/PR13503,PR13503}}.
1418 @subsection M32C Named Address Spaces
1419 @cindex @code{__far} M32C Named Address Spaces
1421 On the M32C target, with the R8C and M16C CPU variants, variables
1422 qualified with @code{__far} are accessed using 32-bit addresses in
1423 order to access memory beyond the first 64@tie{}Ki bytes. If
1424 @code{__far} is used with the M32CM or M32C CPU variants, it has no
1427 @subsection RL78 Named Address Spaces
1428 @cindex @code{__far} RL78 Named Address Spaces
1430 On the RL78 target, variables qualified with @code{__far} are accessed
1431 with 32-bit pointers (20-bit addresses) rather than the default 16-bit
1432 addresses. Non-far variables are assumed to appear in the topmost
1433 64@tie{}KiB of the address space.
1435 @subsection SPU Named Address Spaces
1436 @cindex @code{__ea} SPU Named Address Spaces
1438 On the SPU target variables may be declared as
1439 belonging to another address space by qualifying the type with the
1440 @code{__ea} address space identifier:
1447 The compiler generates special code to access the variable @code{i}.
1448 It may use runtime library
1449 support, or generate special machine instructions to access that address
1452 @subsection x86 Named Address Spaces
1453 @cindex x86 named address spaces
1455 On the x86 target, variables may be declared as being relative
1456 to the @code{%fs} or @code{%gs} segments.
1461 @cindex @code{__seg_fs} x86 named address space
1462 @cindex @code{__seg_gs} x86 named address space
1463 The object is accessed with the respective segment override prefix.
1465 The respective segment base must be set via some method specific to
1466 the operating system. Rather than require an expensive system call
1467 to retrieve the segment base, these address spaces are not considered
1468 to be subspaces of the generic (flat) address space. This means that
1469 explicit casts are required to convert pointers between these address
1470 spaces and the generic address space. In practice the application
1471 should cast to @code{uintptr_t} and apply the segment base offset
1472 that it installed previously.
1474 The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are
1475 defined when these address spaces are supported.
1478 @cindex @code{__seg_tls} x86 named address space
1479 Some operating systems define either the @code{%fs} or @code{%gs}
1480 segment as the thread-local storage base for each thread. Objects
1481 within this address space are accessed with the appropriate
1482 segment override prefix.
1484 The pointer located at address 0 within the segment contains the
1485 offset of the segment within the generic address space. Thus this
1486 address space is considered a subspace of the generic address space,
1487 and the known segment offset is applied when converting addresses
1488 to and from the generic address space.
1490 The preprocessor symbol @code{__SEG_TLS} is defined when this
1491 address space is supported.
1496 @section Arrays of Length Zero
1497 @cindex arrays of length zero
1498 @cindex zero-length arrays
1499 @cindex length-zero arrays
1500 @cindex flexible array members
1502 Zero-length arrays are allowed in GNU C@. They are very useful as the
1503 last element of a structure that is really a header for a variable-length
1512 struct line *thisline = (struct line *)
1513 malloc (sizeof (struct line) + this_length);
1514 thisline->length = this_length;
1517 In ISO C90, you would have to give @code{contents} a length of 1, which
1518 means either you waste space or complicate the argument to @code{malloc}.
1520 In ISO C99, you would use a @dfn{flexible array member}, which is
1521 slightly different in syntax and semantics:
1525 Flexible array members are written as @code{contents[]} without
1529 Flexible array members have incomplete type, and so the @code{sizeof}
1530 operator may not be applied. As a quirk of the original implementation
1531 of zero-length arrays, @code{sizeof} evaluates to zero.
1534 Flexible array members may only appear as the last member of a
1535 @code{struct} that is otherwise non-empty.
1538 A structure containing a flexible array member, or a union containing
1539 such a structure (possibly recursively), may not be a member of a
1540 structure or an element of an array. (However, these uses are
1541 permitted by GCC as extensions.)
1544 Non-empty initialization of zero-length
1545 arrays is treated like any case where there are more initializer
1546 elements than the array holds, in that a suitable warning about ``excess
1547 elements in array'' is given, and the excess elements (all of them, in
1548 this case) are ignored.
1550 GCC allows static initialization of flexible array members.
1551 This is equivalent to defining a new structure containing the original
1552 structure followed by an array of sufficient size to contain the data.
1553 E.g.@: in the following, @code{f1} is constructed as if it were declared
1559 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
1562 struct f1 f1; int data[3];
1563 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
1567 The convenience of this extension is that @code{f1} has the desired
1568 type, eliminating the need to consistently refer to @code{f2.f1}.
1570 This has symmetry with normal static arrays, in that an array of
1571 unknown size is also written with @code{[]}.
1573 Of course, this extension only makes sense if the extra data comes at
1574 the end of a top-level object, as otherwise we would be overwriting
1575 data at subsequent offsets. To avoid undue complication and confusion
1576 with initialization of deeply nested arrays, we simply disallow any
1577 non-empty initialization except when the structure is the top-level
1578 object. For example:
1581 struct foo @{ int x; int y[]; @};
1582 struct bar @{ struct foo z; @};
1584 struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
1585 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1586 struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
1587 struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1590 @node Empty Structures
1591 @section Structures with No Members
1592 @cindex empty structures
1593 @cindex zero-size structures
1595 GCC permits a C structure to have no members:
1602 The structure has size zero. In C++, empty structures are part
1603 of the language. G++ treats empty structures as if they had a single
1604 member of type @code{char}.
1606 @node Variable Length
1607 @section Arrays of Variable Length
1608 @cindex variable-length arrays
1609 @cindex arrays of variable length
1612 Variable-length automatic arrays are allowed in ISO C99, and as an
1613 extension GCC accepts them in C90 mode and in C++. These arrays are
1614 declared like any other automatic arrays, but with a length that is not
1615 a constant expression. The storage is allocated at the point of
1616 declaration and deallocated when the block scope containing the declaration
1622 concat_fopen (char *s1, char *s2, char *mode)
1624 char str[strlen (s1) + strlen (s2) + 1];
1627 return fopen (str, mode);
1631 @cindex scope of a variable length array
1632 @cindex variable-length array scope
1633 @cindex deallocating variable length arrays
1634 Jumping or breaking out of the scope of the array name deallocates the
1635 storage. Jumping into the scope is not allowed; you get an error
1638 @cindex variable-length array in a structure
1639 As an extension, GCC accepts variable-length arrays as a member of
1640 a structure or a union. For example:
1646 struct S @{ int x[n]; @};
1650 @cindex @code{alloca} vs variable-length arrays
1651 You can use the function @code{alloca} to get an effect much like
1652 variable-length arrays. The function @code{alloca} is available in
1653 many other C implementations (but not in all). On the other hand,
1654 variable-length arrays are more elegant.
1656 There are other differences between these two methods. Space allocated
1657 with @code{alloca} exists until the containing @emph{function} returns.
1658 The space for a variable-length array is deallocated as soon as the array
1659 name's scope ends, unless you also use @code{alloca} in this scope.
1661 You can also use variable-length arrays as arguments to functions:
1665 tester (int len, char data[len][len])
1671 The length of an array is computed once when the storage is allocated
1672 and is remembered for the scope of the array in case you access it with
1675 If you want to pass the array first and the length afterward, you can
1676 use a forward declaration in the parameter list---another GNU extension.
1680 tester (int len; char data[len][len], int len)
1686 @cindex parameter forward declaration
1687 The @samp{int len} before the semicolon is a @dfn{parameter forward
1688 declaration}, and it serves the purpose of making the name @code{len}
1689 known when the declaration of @code{data} is parsed.
1691 You can write any number of such parameter forward declarations in the
1692 parameter list. They can be separated by commas or semicolons, but the
1693 last one must end with a semicolon, which is followed by the ``real''
1694 parameter declarations. Each forward declaration must match a ``real''
1695 declaration in parameter name and data type. ISO C99 does not support
1696 parameter forward declarations.
1698 @node Variadic Macros
1699 @section Macros with a Variable Number of Arguments.
1700 @cindex variable number of arguments
1701 @cindex macro with variable arguments
1702 @cindex rest argument (in macro)
1703 @cindex variadic macros
1705 In the ISO C standard of 1999, a macro can be declared to accept a
1706 variable number of arguments much as a function can. The syntax for
1707 defining the macro is similar to that of a function. Here is an
1711 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1715 Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
1716 such a macro, it represents the zero or more tokens until the closing
1717 parenthesis that ends the invocation, including any commas. This set of
1718 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1719 wherever it appears. See the CPP manual for more information.
1721 GCC has long supported variadic macros, and used a different syntax that
1722 allowed you to give a name to the variable arguments just like any other
1723 argument. Here is an example:
1726 #define debug(format, args...) fprintf (stderr, format, args)
1730 This is in all ways equivalent to the ISO C example above, but arguably
1731 more readable and descriptive.
1733 GNU CPP has two further variadic macro extensions, and permits them to
1734 be used with either of the above forms of macro definition.
1736 In standard C, you are not allowed to leave the variable argument out
1737 entirely; but you are allowed to pass an empty argument. For example,
1738 this invocation is invalid in ISO C, because there is no comma after
1745 GNU CPP permits you to completely omit the variable arguments in this
1746 way. In the above examples, the compiler would complain, though since
1747 the expansion of the macro still has the extra comma after the format
1750 To help solve this problem, CPP behaves specially for variable arguments
1751 used with the token paste operator, @samp{##}. If instead you write
1754 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1758 and if the variable arguments are omitted or empty, the @samp{##}
1759 operator causes the preprocessor to remove the comma before it. If you
1760 do provide some variable arguments in your macro invocation, GNU CPP
1761 does not complain about the paste operation and instead places the
1762 variable arguments after the comma. Just like any other pasted macro
1763 argument, these arguments are not macro expanded.
1765 @node Escaped Newlines
1766 @section Slightly Looser Rules for Escaped Newlines
1767 @cindex escaped newlines
1768 @cindex newlines (escaped)
1770 The preprocessor treatment of escaped newlines is more relaxed
1771 than that specified by the C90 standard, which requires the newline
1772 to immediately follow a backslash.
1773 GCC's implementation allows whitespace in the form
1774 of spaces, horizontal and vertical tabs, and form feeds between the
1775 backslash and the subsequent newline. The preprocessor issues a
1776 warning, but treats it as a valid escaped newline and combines the two
1777 lines to form a single logical line. This works within comments and
1778 tokens, as well as between tokens. Comments are @emph{not} treated as
1779 whitespace for the purposes of this relaxation, since they have not
1780 yet been replaced with spaces.
1783 @section Non-Lvalue Arrays May Have Subscripts
1784 @cindex subscripting
1785 @cindex arrays, non-lvalue
1787 @cindex subscripting and function values
1788 In ISO C99, arrays that are not lvalues still decay to pointers, and
1789 may be subscripted, although they may not be modified or used after
1790 the next sequence point and the unary @samp{&} operator may not be
1791 applied to them. As an extension, GNU C allows such arrays to be
1792 subscripted in C90 mode, though otherwise they do not decay to
1793 pointers outside C99 mode. For example,
1794 this is valid in GNU C though not valid in C90:
1798 struct foo @{int a[4];@};
1804 return f().a[index];
1810 @section Arithmetic on @code{void}- and Function-Pointers
1811 @cindex void pointers, arithmetic
1812 @cindex void, size of pointer to
1813 @cindex function pointers, arithmetic
1814 @cindex function, size of pointer to
1816 In GNU C, addition and subtraction operations are supported on pointers to
1817 @code{void} and on pointers to functions. This is done by treating the
1818 size of a @code{void} or of a function as 1.
1820 A consequence of this is that @code{sizeof} is also allowed on @code{void}
1821 and on function types, and returns 1.
1823 @opindex Wpointer-arith
1824 The option @option{-Wpointer-arith} requests a warning if these extensions
1827 @node Pointers to Arrays
1828 @section Pointers to Arrays with Qualifiers Work as Expected
1829 @cindex pointers to arrays
1830 @cindex const qualifier
1832 In GNU C, pointers to arrays with qualifiers work similar to pointers
1833 to other qualified types. For example, a value of type @code{int (*)[5]}
1834 can be used to initialize a variable of type @code{const int (*)[5]}.
1835 These types are incompatible in ISO C because the @code{const} qualifier
1836 is formally attached to the element type of the array and not the
1841 transpose (int N, int M, double out[M][N], const double in[N][M]);
1845 transpose(3, 2, y, x);
1849 @section Non-Constant Initializers
1850 @cindex initializers, non-constant
1851 @cindex non-constant initializers
1853 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
1854 automatic variable are not required to be constant expressions in GNU C@.
1855 Here is an example of an initializer with run-time varying elements:
1858 foo (float f, float g)
1860 float beat_freqs[2] = @{ f-g, f+g @};
1865 @node Compound Literals
1866 @section Compound Literals
1867 @cindex constructor expressions
1868 @cindex initializations in expressions
1869 @cindex structures, constructor expression
1870 @cindex expressions, constructor
1871 @cindex compound literals
1872 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
1874 ISO C99 supports compound literals. A compound literal looks like
1875 a cast containing an initializer. Its value is an object of the
1876 type specified in the cast, containing the elements specified in
1877 the initializer; it is an lvalue. As an extension, GCC supports
1878 compound literals in C90 mode and in C++, though the semantics are
1879 somewhat different in C++.
1881 Usually, the specified type is a structure. Assume that
1882 @code{struct foo} and @code{structure} are declared as shown:
1885 struct foo @{int a; char b[2];@} structure;
1889 Here is an example of constructing a @code{struct foo} with a compound literal:
1892 structure = ((struct foo) @{x + y, 'a', 0@});
1896 This is equivalent to writing the following:
1900 struct foo temp = @{x + y, 'a', 0@};
1905 You can also construct an array, though this is dangerous in C++, as
1906 explained below. If all the elements of the compound literal are
1907 (made up of) simple constant expressions, suitable for use in
1908 initializers of objects of static storage duration, then the compound
1909 literal can be coerced to a pointer to its first element and used in
1910 such an initializer, as shown here:
1913 char **foo = (char *[]) @{ "x", "y", "z" @};
1916 Compound literals for scalar types and union types are
1917 also allowed, but then the compound literal is equivalent
1920 As a GNU extension, GCC allows initialization of objects with static storage
1921 duration by compound literals (which is not possible in ISO C99, because
1922 the initializer is not a constant).
1923 It is handled as if the object is initialized only with the bracket
1924 enclosed list if the types of the compound literal and the object match.
1925 The initializer list of the compound literal must be constant.
1926 If the object being initialized has array type of unknown size, the size is
1927 determined by compound literal size.
1930 static struct foo x = (struct foo) @{1, 'a', 'b'@};
1931 static int y[] = (int []) @{1, 2, 3@};
1932 static int z[] = (int [3]) @{1@};
1936 The above lines are equivalent to the following:
1938 static struct foo x = @{1, 'a', 'b'@};
1939 static int y[] = @{1, 2, 3@};
1940 static int z[] = @{1, 0, 0@};
1943 In C, a compound literal designates an unnamed object with static or
1944 automatic storage duration. In C++, a compound literal designates a
1945 temporary object, which only lives until the end of its
1946 full-expression. As a result, well-defined C code that takes the
1947 address of a subobject of a compound literal can be undefined in C++,
1948 so the C++ compiler rejects the conversion of a temporary array to a pointer.
1949 For instance, if the array compound literal example above appeared
1950 inside a function, any subsequent use of @samp{foo} in C++ has
1951 undefined behavior because the lifetime of the array ends after the
1952 declaration of @samp{foo}.
1954 As an optimization, the C++ compiler sometimes gives array compound
1955 literals longer lifetimes: when the array either appears outside a
1956 function or has const-qualified type. If @samp{foo} and its
1957 initializer had elements of @samp{char *const} type rather than
1958 @samp{char *}, or if @samp{foo} were a global variable, the array
1959 would have static storage duration. But it is probably safest just to
1960 avoid the use of array compound literals in code compiled as C++.
1962 @node Designated Inits
1963 @section Designated Initializers
1964 @cindex initializers with labeled elements
1965 @cindex labeled elements in initializers
1966 @cindex case labels in initializers
1967 @cindex designated initializers
1969 Standard C90 requires the elements of an initializer to appear in a fixed
1970 order, the same as the order of the elements in the array or structure
1973 In ISO C99 you can give the elements in any order, specifying the array
1974 indices or structure field names they apply to, and GNU C allows this as
1975 an extension in C90 mode as well. This extension is not
1976 implemented in GNU C++.
1978 To specify an array index, write
1979 @samp{[@var{index}] =} before the element value. For example,
1982 int a[6] = @{ [4] = 29, [2] = 15 @};
1989 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
1993 The index values must be constant expressions, even if the array being
1994 initialized is automatic.
1996 An alternative syntax for this that has been obsolete since GCC 2.5 but
1997 GCC still accepts is to write @samp{[@var{index}]} before the element
1998 value, with no @samp{=}.
2000 To initialize a range of elements to the same value, write
2001 @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
2002 extension. For example,
2005 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
2009 If the value in it has side-effects, the side-effects happen only once,
2010 not for each initialized field by the range initializer.
2013 Note that the length of the array is the highest value specified
2016 In a structure initializer, specify the name of a field to initialize
2017 with @samp{.@var{fieldname} =} before the element value. For example,
2018 given the following structure,
2021 struct point @{ int x, y; @};
2025 the following initialization
2028 struct point p = @{ .y = yvalue, .x = xvalue @};
2035 struct point p = @{ xvalue, yvalue @};
2038 Another syntax that has the same meaning, obsolete since GCC 2.5, is
2039 @samp{@var{fieldname}:}, as shown here:
2042 struct point p = @{ y: yvalue, x: xvalue @};
2045 Omitted field members are implicitly initialized the same as objects
2046 that have static storage duration.
2049 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
2050 @dfn{designator}. You can also use a designator (or the obsolete colon
2051 syntax) when initializing a union, to specify which element of the union
2052 should be used. For example,
2055 union foo @{ int i; double d; @};
2057 union foo f = @{ .d = 4 @};
2061 converts 4 to a @code{double} to store it in the union using
2062 the second element. By contrast, casting 4 to type @code{union foo}
2063 stores it into the union as the integer @code{i}, since it is
2064 an integer. (@xref{Cast to Union}.)
2066 You can combine this technique of naming elements with ordinary C
2067 initialization of successive elements. Each initializer element that
2068 does not have a designator applies to the next consecutive element of the
2069 array or structure. For example,
2072 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
2079 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
2082 Labeling the elements of an array initializer is especially useful
2083 when the indices are characters or belong to an @code{enum} type.
2088 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
2089 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
2092 @cindex designator lists
2093 You can also write a series of @samp{.@var{fieldname}} and
2094 @samp{[@var{index}]} designators before an @samp{=} to specify a
2095 nested subobject to initialize; the list is taken relative to the
2096 subobject corresponding to the closest surrounding brace pair. For
2097 example, with the @samp{struct point} declaration above:
2100 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
2104 If the same field is initialized multiple times, it has the value from
2105 the last initialization. If any such overridden initialization has
2106 side-effect, it is unspecified whether the side-effect happens or not.
2107 Currently, GCC discards them and issues a warning.
2110 @section Case Ranges
2112 @cindex ranges in case statements
2114 You can specify a range of consecutive values in a single @code{case} label,
2118 case @var{low} ... @var{high}:
2122 This has the same effect as the proper number of individual @code{case}
2123 labels, one for each integer value from @var{low} to @var{high}, inclusive.
2125 This feature is especially useful for ranges of ASCII character codes:
2131 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
2132 it may be parsed wrong when you use it with integer values. For example,
2147 @section Cast to a Union Type
2148 @cindex cast to a union
2149 @cindex union, casting to a
2151 A cast to union type is similar to other casts, except that the type
2152 specified is a union type. You can specify the type either with
2153 @code{union @var{tag}} or with a typedef name. A cast to union is actually
2154 a constructor, not a cast, and hence does not yield an lvalue like
2155 normal casts. (@xref{Compound Literals}.)
2157 The types that may be cast to the union type are those of the members
2158 of the union. Thus, given the following union and variables:
2161 union foo @{ int i; double d; @};
2167 both @code{x} and @code{y} can be cast to type @code{union foo}.
2169 Using the cast as the right-hand side of an assignment to a variable of
2170 union type is equivalent to storing in a member of the union:
2175 u = (union foo) x @equiv{} u.i = x
2176 u = (union foo) y @equiv{} u.d = y
2179 You can also use the union cast as a function argument:
2182 void hack (union foo);
2184 hack ((union foo) x);
2187 @node Mixed Declarations
2188 @section Mixed Declarations and Code
2189 @cindex mixed declarations and code
2190 @cindex declarations, mixed with code
2191 @cindex code, mixed with declarations
2193 ISO C99 and ISO C++ allow declarations and code to be freely mixed
2194 within compound statements. As an extension, GNU C also allows this in
2195 C90 mode. For example, you could do:
2204 Each identifier is visible from where it is declared until the end of
2205 the enclosing block.
2207 @node Function Attributes
2208 @section Declaring Attributes of Functions
2209 @cindex function attributes
2210 @cindex declaring attributes of functions
2211 @cindex @code{volatile} applied to function
2212 @cindex @code{const} applied to function
2214 In GNU C, you can use function attributes to declare certain things
2215 about functions called in your program which help the compiler
2216 optimize calls and check your code more carefully. For example, you
2217 can use attributes to declare that a function never returns
2218 (@code{noreturn}), returns a value depending only on its arguments
2219 (@code{pure}), or has @code{printf}-style arguments (@code{format}).
2221 You can also use attributes to control memory placement, code
2222 generation options or call/return conventions within the function
2223 being annotated. Many of these attributes are target-specific. For
2224 example, many targets support attributes for defining interrupt
2225 handler functions, which typically must follow special register usage
2226 and return conventions.
2228 Function attributes are introduced by the @code{__attribute__} keyword
2229 on a declaration, followed by an attribute specification inside double
2230 parentheses. You can specify multiple attributes in a declaration by
2231 separating them by commas within the double parentheses or by
2232 immediately following an attribute declaration with another attribute
2233 declaration. @xref{Attribute Syntax}, for the exact rules on
2234 attribute syntax and placement.
2236 GCC also supports attributes on
2237 variable declarations (@pxref{Variable Attributes}),
2238 labels (@pxref{Label Attributes}),
2239 enumerators (@pxref{Enumerator Attributes}),
2240 and types (@pxref{Type Attributes}).
2242 There is some overlap between the purposes of attributes and pragmas
2243 (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
2244 found convenient to use @code{__attribute__} to achieve a natural
2245 attachment of attributes to their corresponding declarations, whereas
2246 @code{#pragma} is of use for compatibility with other compilers
2247 or constructs that do not naturally form part of the grammar.
2249 In addition to the attributes documented here,
2250 GCC plugins may provide their own attributes.
2253 * Common Function Attributes::
2254 * AArch64 Function Attributes::
2255 * ARC Function Attributes::
2256 * ARM Function Attributes::
2257 * AVR Function Attributes::
2258 * Blackfin Function Attributes::
2259 * CR16 Function Attributes::
2260 * Epiphany Function Attributes::
2261 * H8/300 Function Attributes::
2262 * IA-64 Function Attributes::
2263 * M32C Function Attributes::
2264 * M32R/D Function Attributes::
2265 * m68k Function Attributes::
2266 * MCORE Function Attributes::
2267 * MeP Function Attributes::
2268 * MicroBlaze Function Attributes::
2269 * Microsoft Windows Function Attributes::
2270 * MIPS Function Attributes::
2271 * MSP430 Function Attributes::
2272 * NDS32 Function Attributes::
2273 * Nios II Function Attributes::
2274 * PowerPC Function Attributes::
2275 * RL78 Function Attributes::
2276 * RX Function Attributes::
2277 * S/390 Function Attributes::
2278 * SH Function Attributes::
2279 * SPU Function Attributes::
2280 * Symbian OS Function Attributes::
2281 * Visium Function Attributes::
2282 * x86 Function Attributes::
2283 * Xstormy16 Function Attributes::
2286 @node Common Function Attributes
2287 @subsection Common Function Attributes
2289 The following attributes are supported on most targets.
2292 @c Keep this table alphabetized by attribute name. Treat _ as space.
2294 @item alias ("@var{target}")
2295 @cindex @code{alias} function attribute
2296 The @code{alias} attribute causes the declaration to be emitted as an
2297 alias for another symbol, which must be specified. For instance,
2300 void __f () @{ /* @r{Do something.} */; @}
2301 void f () __attribute__ ((weak, alias ("__f")));
2305 defines @samp{f} to be a weak alias for @samp{__f}. In C++, the
2306 mangled name for the target must be used. It is an error if @samp{__f}
2307 is not defined in the same translation unit.
2309 This attribute requires assembler and object file support,
2310 and may not be available on all targets.
2312 @item aligned (@var{alignment})
2313 @cindex @code{aligned} function attribute
2314 This attribute specifies a minimum alignment for the function,
2317 You cannot use this attribute to decrease the alignment of a function,
2318 only to increase it. However, when you explicitly specify a function
2319 alignment this overrides the effect of the
2320 @option{-falign-functions} (@pxref{Optimize Options}) option for this
2323 Note that the effectiveness of @code{aligned} attributes may be
2324 limited by inherent limitations in your linker. On many systems, the
2325 linker is only able to arrange for functions to be aligned up to a
2326 certain maximum alignment. (For some linkers, the maximum supported
2327 alignment may be very very small.) See your linker documentation for
2328 further information.
2330 The @code{aligned} attribute can also be used for variables and fields
2331 (@pxref{Variable Attributes}.)
2334 @cindex @code{alloc_align} function attribute
2335 The @code{alloc_align} attribute is used to tell the compiler that the
2336 function return value points to memory, where the returned pointer minimum
2337 alignment is given by one of the functions parameters. GCC uses this
2338 information to improve pointer alignment analysis.
2340 The function parameter denoting the allocated alignment is specified by
2341 one integer argument, whose number is the argument of the attribute.
2342 Argument numbering starts at one.
2347 void* my_memalign(size_t, size_t) __attribute__((alloc_align(1)))
2351 declares that @code{my_memalign} returns memory with minimum alignment
2352 given by parameter 1.
2355 @cindex @code{alloc_size} function attribute
2356 The @code{alloc_size} attribute is used to tell the compiler that the
2357 function return value points to memory, where the size is given by
2358 one or two of the functions parameters. GCC uses this
2359 information to improve the correctness of @code{__builtin_object_size}.
2361 The function parameter(s) denoting the allocated size are specified by
2362 one or two integer arguments supplied to the attribute. The allocated size
2363 is either the value of the single function argument specified or the product
2364 of the two function arguments specified. Argument numbering starts at
2370 void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2)))
2371 void* my_realloc(void*, size_t) __attribute__((alloc_size(2)))
2375 declares that @code{my_calloc} returns memory of the size given by
2376 the product of parameter 1 and 2 and that @code{my_realloc} returns memory
2377 of the size given by parameter 2.
2380 @cindex @code{always_inline} function attribute
2381 Generally, functions are not inlined unless optimization is specified.
2382 For functions declared inline, this attribute inlines the function
2383 independent of any restrictions that otherwise apply to inlining.
2384 Failure to inline such a function is diagnosed as an error.
2385 Note that if such a function is called indirectly the compiler may
2386 or may not inline it depending on optimization level and a failure
2387 to inline an indirect call may or may not be diagnosed.
2390 @cindex @code{artificial} function attribute
2391 This attribute is useful for small inline wrappers that if possible
2392 should appear during debugging as a unit. Depending on the debug
2393 info format it either means marking the function as artificial
2394 or using the caller location for all instructions within the inlined
2397 @item assume_aligned
2398 @cindex @code{assume_aligned} function attribute
2399 The @code{assume_aligned} attribute is used to tell the compiler that the
2400 function return value points to memory, where the returned pointer minimum
2401 alignment is given by the first argument.
2402 If the attribute has two arguments, the second argument is misalignment offset.
2407 void* my_alloc1(size_t) __attribute__((assume_aligned(16)))
2408 void* my_alloc2(size_t) __attribute__((assume_aligned(32, 8)))
2412 declares that @code{my_alloc1} returns 16-byte aligned pointer and
2413 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
2416 @item bnd_instrument
2417 @cindex @code{bnd_instrument} function attribute
2418 The @code{bnd_instrument} attribute on functions is used to inform the
2419 compiler that the function should be instrumented when compiled
2420 with the @option{-fchkp-instrument-marked-only} option.
2423 @cindex @code{bnd_legacy} function attribute
2424 @cindex Pointer Bounds Checker attributes
2425 The @code{bnd_legacy} attribute on functions is used to inform the
2426 compiler that the function should not be instrumented when compiled
2427 with the @option{-fcheck-pointer-bounds} option.
2430 @cindex @code{cold} function attribute
2431 The @code{cold} attribute on functions is used to inform the compiler that
2432 the function is unlikely to be executed. The function is optimized for
2433 size rather than speed and on many targets it is placed into a special
2434 subsection of the text section so all cold functions appear close together,
2435 improving code locality of non-cold parts of program. The paths leading
2436 to calls of cold functions within code are marked as unlikely by the branch
2437 prediction mechanism. It is thus useful to mark functions used to handle
2438 unlikely conditions, such as @code{perror}, as cold to improve optimization
2439 of hot functions that do call marked functions in rare occasions.
2441 When profile feedback is available, via @option{-fprofile-use}, cold functions
2442 are automatically detected and this attribute is ignored.
2445 @cindex @code{const} function attribute
2446 @cindex functions that have no side effects
2447 Many functions do not examine any values except their arguments, and
2448 have no effects except the return value. Basically this is just slightly
2449 more strict class than the @code{pure} attribute below, since function is not
2450 allowed to read global memory.
2452 @cindex pointer arguments
2453 Note that a function that has pointer arguments and examines the data
2454 pointed to must @emph{not} be declared @code{const}. Likewise, a
2455 function that calls a non-@code{const} function usually must not be
2456 @code{const}. It does not make sense for a @code{const} function to
2461 @itemx constructor (@var{priority})
2462 @itemx destructor (@var{priority})
2463 @cindex @code{constructor} function attribute
2464 @cindex @code{destructor} function attribute
2465 The @code{constructor} attribute causes the function to be called
2466 automatically before execution enters @code{main ()}. Similarly, the
2467 @code{destructor} attribute causes the function to be called
2468 automatically after @code{main ()} completes or @code{exit ()} is
2469 called. Functions with these attributes are useful for
2470 initializing data that is used implicitly during the execution of
2473 You may provide an optional integer priority to control the order in
2474 which constructor and destructor functions are run. A constructor
2475 with a smaller priority number runs before a constructor with a larger
2476 priority number; the opposite relationship holds for destructors. So,
2477 if you have a constructor that allocates a resource and a destructor
2478 that deallocates the same resource, both functions typically have the
2479 same priority. The priorities for constructor and destructor
2480 functions are the same as those specified for namespace-scope C++
2481 objects (@pxref{C++ Attributes}).
2483 These attributes are not currently implemented for Objective-C@.
2486 @itemx deprecated (@var{msg})
2487 @cindex @code{deprecated} function attribute
2488 The @code{deprecated} attribute results in a warning if the function
2489 is used anywhere in the source file. This is useful when identifying
2490 functions that are expected to be removed in a future version of a
2491 program. The warning also includes the location of the declaration
2492 of the deprecated function, to enable users to easily find further
2493 information about why the function is deprecated, or what they should
2494 do instead. Note that the warnings only occurs for uses:
2497 int old_fn () __attribute__ ((deprecated));
2499 int (*fn_ptr)() = old_fn;
2503 results in a warning on line 3 but not line 2. The optional @var{msg}
2504 argument, which must be a string, is printed in the warning if
2507 The @code{deprecated} attribute can also be used for variables and
2508 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2510 @item error ("@var{message}")
2511 @itemx warning ("@var{message}")
2512 @cindex @code{error} function attribute
2513 @cindex @code{warning} function attribute
2514 If the @code{error} or @code{warning} attribute
2515 is used on a function declaration and a call to such a function
2516 is not eliminated through dead code elimination or other optimizations,
2517 an error or warning (respectively) that includes @var{message} is diagnosed.
2519 for compile-time checking, especially together with @code{__builtin_constant_p}
2520 and inline functions where checking the inline function arguments is not
2521 possible through @code{extern char [(condition) ? 1 : -1];} tricks.
2523 While it is possible to leave the function undefined and thus invoke
2524 a link failure (to define the function with
2525 a message in @code{.gnu.warning*} section),
2526 when using these attributes the problem is diagnosed
2527 earlier and with exact location of the call even in presence of inline
2528 functions or when not emitting debugging information.
2530 @item externally_visible
2531 @cindex @code{externally_visible} function attribute
2532 This attribute, attached to a global variable or function, nullifies
2533 the effect of the @option{-fwhole-program} command-line option, so the
2534 object remains visible outside the current compilation unit.
2536 If @option{-fwhole-program} is used together with @option{-flto} and
2537 @command{gold} is used as the linker plugin,
2538 @code{externally_visible} attributes are automatically added to functions
2539 (not variable yet due to a current @command{gold} issue)
2540 that are accessed outside of LTO objects according to resolution file
2541 produced by @command{gold}.
2542 For other linkers that cannot generate resolution file,
2543 explicit @code{externally_visible} attributes are still necessary.
2546 @cindex @code{flatten} function attribute
2547 Generally, inlining into a function is limited. For a function marked with
2548 this attribute, every call inside this function is inlined, if possible.
2549 Whether the function itself is considered for inlining depends on its size and
2550 the current inlining parameters.
2552 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
2553 @cindex @code{format} function attribute
2554 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
2556 The @code{format} attribute specifies that a function takes @code{printf},
2557 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that
2558 should be type-checked against a format string. For example, the
2563 my_printf (void *my_object, const char *my_format, ...)
2564 __attribute__ ((format (printf, 2, 3)));
2568 causes the compiler to check the arguments in calls to @code{my_printf}
2569 for consistency with the @code{printf} style format string argument
2572 The parameter @var{archetype} determines how the format string is
2573 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
2574 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
2575 @code{strfmon}. (You can also use @code{__printf__},
2576 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
2577 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
2578 @code{ms_strftime} are also present.
2579 @var{archetype} values such as @code{printf} refer to the formats accepted
2580 by the system's C runtime library,
2581 while values prefixed with @samp{gnu_} always refer
2582 to the formats accepted by the GNU C Library. On Microsoft Windows
2583 targets, values prefixed with @samp{ms_} refer to the formats accepted by the
2584 @file{msvcrt.dll} library.
2585 The parameter @var{string-index}
2586 specifies which argument is the format string argument (starting
2587 from 1), while @var{first-to-check} is the number of the first
2588 argument to check against the format string. For functions
2589 where the arguments are not available to be checked (such as
2590 @code{vprintf}), specify the third parameter as zero. In this case the
2591 compiler only checks the format string for consistency. For
2592 @code{strftime} formats, the third parameter is required to be zero.
2593 Since non-static C++ methods have an implicit @code{this} argument, the
2594 arguments of such methods should be counted from two, not one, when
2595 giving values for @var{string-index} and @var{first-to-check}.
2597 In the example above, the format string (@code{my_format}) is the second
2598 argument of the function @code{my_print}, and the arguments to check
2599 start with the third argument, so the correct parameters for the format
2600 attribute are 2 and 3.
2602 @opindex ffreestanding
2603 @opindex fno-builtin
2604 The @code{format} attribute allows you to identify your own functions
2605 that take format strings as arguments, so that GCC can check the
2606 calls to these functions for errors. The compiler always (unless
2607 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
2608 for the standard library functions @code{printf}, @code{fprintf},
2609 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
2610 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
2611 warnings are requested (using @option{-Wformat}), so there is no need to
2612 modify the header file @file{stdio.h}. In C99 mode, the functions
2613 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
2614 @code{vsscanf} are also checked. Except in strictly conforming C
2615 standard modes, the X/Open function @code{strfmon} is also checked as
2616 are @code{printf_unlocked} and @code{fprintf_unlocked}.
2617 @xref{C Dialect Options,,Options Controlling C Dialect}.
2619 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
2620 recognized in the same context. Declarations including these format attributes
2621 are parsed for correct syntax, however the result of checking of such format
2622 strings is not yet defined, and is not carried out by this version of the
2625 The target may also provide additional types of format checks.
2626 @xref{Target Format Checks,,Format Checks Specific to Particular
2629 @item format_arg (@var{string-index})
2630 @cindex @code{format_arg} function attribute
2631 @opindex Wformat-nonliteral
2632 The @code{format_arg} attribute specifies that a function takes a format
2633 string for a @code{printf}, @code{scanf}, @code{strftime} or
2634 @code{strfmon} style function and modifies it (for example, to translate
2635 it into another language), so the result can be passed to a
2636 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
2637 function (with the remaining arguments to the format function the same
2638 as they would have been for the unmodified string). For example, the
2643 my_dgettext (char *my_domain, const char *my_format)
2644 __attribute__ ((format_arg (2)));
2648 causes the compiler to check the arguments in calls to a @code{printf},
2649 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
2650 format string argument is a call to the @code{my_dgettext} function, for
2651 consistency with the format string argument @code{my_format}. If the
2652 @code{format_arg} attribute had not been specified, all the compiler
2653 could tell in such calls to format functions would be that the format
2654 string argument is not constant; this would generate a warning when
2655 @option{-Wformat-nonliteral} is used, but the calls could not be checked
2656 without the attribute.
2658 The parameter @var{string-index} specifies which argument is the format
2659 string argument (starting from one). Since non-static C++ methods have
2660 an implicit @code{this} argument, the arguments of such methods should
2661 be counted from two.
2663 The @code{format_arg} attribute allows you to identify your own
2664 functions that modify format strings, so that GCC can check the
2665 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
2666 type function whose operands are a call to one of your own function.
2667 The compiler always treats @code{gettext}, @code{dgettext}, and
2668 @code{dcgettext} in this manner except when strict ISO C support is
2669 requested by @option{-ansi} or an appropriate @option{-std} option, or
2670 @option{-ffreestanding} or @option{-fno-builtin}
2671 is used. @xref{C Dialect Options,,Options
2672 Controlling C Dialect}.
2674 For Objective-C dialects, the @code{format-arg} attribute may refer to an
2675 @code{NSString} reference for compatibility with the @code{format} attribute
2678 The target may also allow additional types in @code{format-arg} attributes.
2679 @xref{Target Format Checks,,Format Checks Specific to Particular
2683 @cindex @code{gnu_inline} function attribute
2684 This attribute should be used with a function that is also declared
2685 with the @code{inline} keyword. It directs GCC to treat the function
2686 as if it were defined in gnu90 mode even when compiling in C99 or
2689 If the function is declared @code{extern}, then this definition of the
2690 function is used only for inlining. In no case is the function
2691 compiled as a standalone function, not even if you take its address
2692 explicitly. Such an address becomes an external reference, as if you
2693 had only declared the function, and had not defined it. This has
2694 almost the effect of a macro. The way to use this is to put a
2695 function definition in a header file with this attribute, and put
2696 another copy of the function, without @code{extern}, in a library
2697 file. The definition in the header file causes most calls to the
2698 function to be inlined. If any uses of the function remain, they
2699 refer to the single copy in the library. Note that the two
2700 definitions of the functions need not be precisely the same, although
2701 if they do not have the same effect your program may behave oddly.
2703 In C, if the function is neither @code{extern} nor @code{static}, then
2704 the function is compiled as a standalone function, as well as being
2705 inlined where possible.
2707 This is how GCC traditionally handled functions declared
2708 @code{inline}. Since ISO C99 specifies a different semantics for
2709 @code{inline}, this function attribute is provided as a transition
2710 measure and as a useful feature in its own right. This attribute is
2711 available in GCC 4.1.3 and later. It is available if either of the
2712 preprocessor macros @code{__GNUC_GNU_INLINE__} or
2713 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
2714 Function is As Fast As a Macro}.
2716 In C++, this attribute does not depend on @code{extern} in any way,
2717 but it still requires the @code{inline} keyword to enable its special
2721 @cindex @code{hot} function attribute
2722 The @code{hot} attribute on a function is used to inform the compiler that
2723 the function is a hot spot of the compiled program. The function is
2724 optimized more aggressively and on many targets it is placed into a special
2725 subsection of the text section so all hot functions appear close together,
2728 When profile feedback is available, via @option{-fprofile-use}, hot functions
2729 are automatically detected and this attribute is ignored.
2731 @item ifunc ("@var{resolver}")
2732 @cindex @code{ifunc} function attribute
2733 @cindex indirect functions
2734 @cindex functions that are dynamically resolved
2735 The @code{ifunc} attribute is used to mark a function as an indirect
2736 function using the STT_GNU_IFUNC symbol type extension to the ELF
2737 standard. This allows the resolution of the symbol value to be
2738 determined dynamically at load time, and an optimized version of the
2739 routine can be selected for the particular processor or other system
2740 characteristics determined then. To use this attribute, first define
2741 the implementation functions available, and a resolver function that
2742 returns a pointer to the selected implementation function. The
2743 implementation functions' declarations must match the API of the
2744 function being implemented, the resolver's declaration is be a
2745 function returning pointer to void function returning void:
2748 void *my_memcpy (void *dst, const void *src, size_t len)
2753 static void (*resolve_memcpy (void)) (void)
2755 return my_memcpy; // we'll just always select this routine
2760 The exported header file declaring the function the user calls would
2764 extern void *memcpy (void *, const void *, size_t);
2768 allowing the user to call this as a regular function, unaware of the
2769 implementation. Finally, the indirect function needs to be defined in
2770 the same translation unit as the resolver function:
2773 void *memcpy (void *, const void *, size_t)
2774 __attribute__ ((ifunc ("resolve_memcpy")));
2777 Indirect functions cannot be weak. Binutils version 2.20.1 or higher
2778 and GNU C Library version 2.11.1 are required to use this feature.
2781 @itemx interrupt_handler
2782 Many GCC back ends support attributes to indicate that a function is
2783 an interrupt handler, which tells the compiler to generate function
2784 entry and exit sequences that differ from those from regular
2785 functions. The exact syntax and behavior are target-specific;
2786 refer to the following subsections for details.
2789 @cindex @code{leaf} function attribute
2790 Calls to external functions with this attribute must return to the current
2791 compilation unit only by return or by exception handling. In particular, leaf
2792 functions are not allowed to call callback function passed to it from the current
2793 compilation unit or directly call functions exported by the unit or longjmp
2794 into the unit. Leaf function might still call functions from other compilation
2795 units and thus they are not necessarily leaf in the sense that they contain no
2796 function calls at all.
2798 The attribute is intended for library functions to improve dataflow analysis.
2799 The compiler takes the hint that any data not escaping the current compilation unit can
2800 not be used or modified by the leaf function. For example, the @code{sin} function
2801 is a leaf function, but @code{qsort} is not.
2803 Note that leaf functions might invoke signals and signal handlers might be
2804 defined in the current compilation unit and use static variables. The only
2805 compliant way to write such a signal handler is to declare such variables
2808 The attribute has no effect on functions defined within the current compilation
2809 unit. This is to allow easy merging of multiple compilation units into one,
2810 for example, by using the link-time optimization. For this reason the
2811 attribute is not allowed on types to annotate indirect calls.
2815 @cindex @code{malloc} function attribute
2816 @cindex functions that behave like malloc
2817 This tells the compiler that a function is @code{malloc}-like, i.e.,
2818 that the pointer @var{P} returned by the function cannot alias any
2819 other pointer valid when the function returns, and moreover no
2820 pointers to valid objects occur in any storage addressed by @var{P}.
2822 Using this attribute can improve optimization. Functions like
2823 @code{malloc} and @code{calloc} have this property because they return
2824 a pointer to uninitialized or zeroed-out storage. However, functions
2825 like @code{realloc} do not have this property, as they can return a
2826 pointer to storage containing pointers.
2829 @cindex @code{no_icf} function attribute
2830 This function attribute prevents a functions from being merged with another
2831 semantically equivalent function.
2833 @item no_instrument_function
2834 @cindex @code{no_instrument_function} function attribute
2835 @opindex finstrument-functions
2836 If @option{-finstrument-functions} is given, profiling function calls are
2837 generated at entry and exit of most user-compiled functions.
2838 Functions with this attribute are not so instrumented.
2841 @cindex @code{no_reorder} function attribute
2842 Do not reorder functions or variables marked @code{no_reorder}
2843 against each other or top level assembler statements the executable.
2844 The actual order in the program will depend on the linker command
2845 line. Static variables marked like this are also not removed.
2846 This has a similar effect
2847 as the @option{-fno-toplevel-reorder} option, but only applies to the
2850 @item no_sanitize_address
2851 @itemx no_address_safety_analysis
2852 @cindex @code{no_sanitize_address} function attribute
2853 The @code{no_sanitize_address} attribute on functions is used
2854 to inform the compiler that it should not instrument memory accesses
2855 in the function when compiling with the @option{-fsanitize=address} option.
2856 The @code{no_address_safety_analysis} is a deprecated alias of the
2857 @code{no_sanitize_address} attribute, new code should use
2858 @code{no_sanitize_address}.
2860 @item no_sanitize_thread
2861 @cindex @code{no_sanitize_thread} function attribute
2862 The @code{no_sanitize_thread} attribute on functions is used
2863 to inform the compiler that it should not instrument memory accesses
2864 in the function when compiling with the @option{-fsanitize=thread} option.
2866 @item no_sanitize_undefined
2867 @cindex @code{no_sanitize_undefined} function attribute
2868 The @code{no_sanitize_undefined} attribute on functions is used
2869 to inform the compiler that it should not check for undefined behavior
2870 in the function when compiling with the @option{-fsanitize=undefined} option.
2872 @item no_split_stack
2873 @cindex @code{no_split_stack} function attribute
2874 @opindex fsplit-stack
2875 If @option{-fsplit-stack} is given, functions have a small
2876 prologue which decides whether to split the stack. Functions with the
2877 @code{no_split_stack} attribute do not have that prologue, and thus
2878 may run with only a small amount of stack space available.
2880 @item no_stack_limit
2881 @cindex @code{no_stack_limit} function attribute
2882 This attribute locally overrides the @option{-fstack-limit-register}
2883 and @option{-fstack-limit-symbol} command-line options; it has the effect
2884 of disabling stack limit checking in the function it applies to.
2887 @cindex @code{noclone} function attribute
2888 This function attribute prevents a function from being considered for
2889 cloning---a mechanism that produces specialized copies of functions
2890 and which is (currently) performed by interprocedural constant
2894 @cindex @code{noinline} function attribute
2895 This function attribute prevents a function from being considered for
2897 @c Don't enumerate the optimizations by name here; we try to be
2898 @c future-compatible with this mechanism.
2899 If the function does not have side-effects, there are optimizations
2900 other than inlining that cause function calls to be optimized away,
2901 although the function call is live. To keep such calls from being
2908 (@pxref{Extended Asm}) in the called function, to serve as a special
2911 @item nonnull (@var{arg-index}, @dots{})
2912 @cindex @code{nonnull} function attribute
2913 @cindex functions with non-null pointer arguments
2914 The @code{nonnull} attribute specifies that some function parameters should
2915 be non-null pointers. For instance, the declaration:
2919 my_memcpy (void *dest, const void *src, size_t len)
2920 __attribute__((nonnull (1, 2)));
2924 causes the compiler to check that, in calls to @code{my_memcpy},
2925 arguments @var{dest} and @var{src} are non-null. If the compiler
2926 determines that a null pointer is passed in an argument slot marked
2927 as non-null, and the @option{-Wnonnull} option is enabled, a warning
2928 is issued. The compiler may also choose to make optimizations based
2929 on the knowledge that certain function arguments will never be null.
2931 If no argument index list is given to the @code{nonnull} attribute,
2932 all pointer arguments are marked as non-null. To illustrate, the
2933 following declaration is equivalent to the previous example:
2937 my_memcpy (void *dest, const void *src, size_t len)
2938 __attribute__((nonnull));
2942 @cindex @code{noplt} function attribute
2943 The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
2944 Calls to functions marked with this attribute in position-independent code
2949 /* Externally defined function foo. */
2950 int foo () __attribute__ ((noplt));
2953 main (/* @r{@dots{}} */)
2962 The @code{noplt} attribute on function @code{foo}
2963 tells the compiler to assume that
2964 the function @code{foo} is externally defined and that the call to
2965 @code{foo} must avoid the PLT
2966 in position-independent code.
2968 In position-dependent code, a few targets also convert calls to
2969 functions that are marked to not use the PLT to use the GOT instead.
2972 @cindex @code{noreturn} function attribute
2973 @cindex functions that never return
2974 A few standard library functions, such as @code{abort} and @code{exit},
2975 cannot return. GCC knows this automatically. Some programs define
2976 their own functions that never return. You can declare them
2977 @code{noreturn} to tell the compiler this fact. For example,
2981 void fatal () __attribute__ ((noreturn));
2984 fatal (/* @r{@dots{}} */)
2986 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
2992 The @code{noreturn} keyword tells the compiler to assume that
2993 @code{fatal} cannot return. It can then optimize without regard to what
2994 would happen if @code{fatal} ever did return. This makes slightly
2995 better code. More importantly, it helps avoid spurious warnings of
2996 uninitialized variables.
2998 The @code{noreturn} keyword does not affect the exceptional path when that
2999 applies: a @code{noreturn}-marked function may still return to the caller
3000 by throwing an exception or calling @code{longjmp}.
3002 Do not assume that registers saved by the calling function are
3003 restored before calling the @code{noreturn} function.
3005 It does not make sense for a @code{noreturn} function to have a return
3006 type other than @code{void}.
3009 @cindex @code{nothrow} function attribute
3010 The @code{nothrow} attribute is used to inform the compiler that a
3011 function cannot throw an exception. For example, most functions in
3012 the standard C library can be guaranteed not to throw an exception
3013 with the notable exceptions of @code{qsort} and @code{bsearch} that
3014 take function pointer arguments.
3017 @cindex @code{optimize} function attribute
3018 The @code{optimize} attribute is used to specify that a function is to
3019 be compiled with different optimization options than specified on the
3020 command line. Arguments can either be numbers or strings. Numbers
3021 are assumed to be an optimization level. Strings that begin with
3022 @code{O} are assumed to be an optimization option, while other options
3023 are assumed to be used with a @code{-f} prefix. You can also use the
3024 @samp{#pragma GCC optimize} pragma to set the optimization options
3025 that affect more than one function.
3026 @xref{Function Specific Option Pragmas}, for details about the
3027 @samp{#pragma GCC optimize} pragma.
3029 This can be used for instance to have frequently-executed functions
3030 compiled with more aggressive optimization options that produce faster
3031 and larger code, while other functions can be compiled with less
3035 @cindex @code{pure} function attribute
3036 @cindex functions that have no side effects
3037 Many functions have no effects except the return value and their
3038 return value depends only on the parameters and/or global variables.
3039 Such a function can be subject
3040 to common subexpression elimination and loop optimization just as an
3041 arithmetic operator would be. These functions should be declared
3042 with the attribute @code{pure}. For example,
3045 int square (int) __attribute__ ((pure));
3049 says that the hypothetical function @code{square} is safe to call
3050 fewer times than the program says.
3052 Some of common examples of pure functions are @code{strlen} or @code{memcmp}.
3053 Interesting non-pure functions are functions with infinite loops or those
3054 depending on volatile memory or other system resource, that may change between
3055 two consecutive calls (such as @code{feof} in a multithreading environment).
3057 @item returns_nonnull
3058 @cindex @code{returns_nonnull} function attribute
3059 The @code{returns_nonnull} attribute specifies that the function
3060 return value should be a non-null pointer. For instance, the declaration:
3064 mymalloc (size_t len) __attribute__((returns_nonnull));
3068 lets the compiler optimize callers based on the knowledge
3069 that the return value will never be null.
3072 @cindex @code{returns_twice} function attribute
3073 @cindex functions that return more than once
3074 The @code{returns_twice} attribute tells the compiler that a function may
3075 return more than one time. The compiler ensures that all registers
3076 are dead before calling such a function and emits a warning about
3077 the variables that may be clobbered after the second return from the
3078 function. Examples of such functions are @code{setjmp} and @code{vfork}.
3079 The @code{longjmp}-like counterpart of such function, if any, might need
3080 to be marked with the @code{noreturn} attribute.
3082 @item section ("@var{section-name}")
3083 @cindex @code{section} function attribute
3084 @cindex functions in arbitrary sections
3085 Normally, the compiler places the code it generates in the @code{text} section.
3086 Sometimes, however, you need additional sections, or you need certain
3087 particular functions to appear in special sections. The @code{section}
3088 attribute specifies that a function lives in a particular section.
3089 For example, the declaration:
3092 extern void foobar (void) __attribute__ ((section ("bar")));
3096 puts the function @code{foobar} in the @code{bar} section.
3098 Some file formats do not support arbitrary sections so the @code{section}
3099 attribute is not available on all platforms.
3100 If you need to map the entire contents of a module to a particular
3101 section, consider using the facilities of the linker instead.
3104 @cindex @code{sentinel} function attribute
3105 This function attribute ensures that a parameter in a function call is
3106 an explicit @code{NULL}. The attribute is only valid on variadic
3107 functions. By default, the sentinel is located at position zero, the
3108 last parameter of the function call. If an optional integer position
3109 argument P is supplied to the attribute, the sentinel must be located at
3110 position P counting backwards from the end of the argument list.
3113 __attribute__ ((sentinel))
3115 __attribute__ ((sentinel(0)))
3118 The attribute is automatically set with a position of 0 for the built-in
3119 functions @code{execl} and @code{execlp}. The built-in function
3120 @code{execle} has the attribute set with a position of 1.
3122 A valid @code{NULL} in this context is defined as zero with any pointer
3123 type. If your system defines the @code{NULL} macro with an integer type
3124 then you need to add an explicit cast. GCC replaces @code{stddef.h}
3125 with a copy that redefines NULL appropriately.
3127 The warnings for missing or incorrect sentinels are enabled with
3131 @itemx simd("@var{mask}")
3132 @cindex @code{simd} function attribute
3133 This attribute enables creation of one or more function versions that
3134 can process multiple arguments using SIMD instructions from a
3135 single invocation. Specifying this attribute allows compiler to
3136 assume that such versions are available at link time (provided
3137 in the same or another translation unit). Generated versions are
3138 target-dependent and described in the corresponding Vector ABI document. For
3139 x86_64 target this document can be found
3140 @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}.
3142 The optional argument @var{mask} may have the value
3143 @code{notinbranch} or @code{inbranch},
3144 and instructs the compiler to generate non-masked or masked
3145 clones correspondingly. By default, all clones are generated.
3147 The attribute should not be used together with Cilk Plus @code{vector}
3148 attribute on the same function.
3150 If the attribute is specified and @code{#pragma omp declare simd} is
3151 present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd}
3152 switch is specified, then the attribute is ignored.
3155 @cindex @code{stack_protect} function attribute
3156 This attribute adds stack protection code to the function if
3157 flags @option{-fstack-protector}, @option{-fstack-protector-strong}
3158 or @option{-fstack-protector-explicit} are set.
3160 @item target (@var{options})
3161 @cindex @code{target} function attribute
3162 Multiple target back ends implement the @code{target} attribute
3163 to specify that a function is to
3164 be compiled with different target options than specified on the
3165 command line. This can be used for instance to have functions
3166 compiled with a different ISA (instruction set architecture) than the
3167 default. You can also use the @samp{#pragma GCC target} pragma to set
3168 more than one function to be compiled with specific target options.
3169 @xref{Function Specific Option Pragmas}, for details about the
3170 @samp{#pragma GCC target} pragma.
3172 For instance, on an x86, you could declare one function with the
3173 @code{target("sse4.1,arch=core2")} attribute and another with
3174 @code{target("sse4a,arch=amdfam10")}. This is equivalent to
3175 compiling the first function with @option{-msse4.1} and
3176 @option{-march=core2} options, and the second function with
3177 @option{-msse4a} and @option{-march=amdfam10} options. It is up to you
3178 to make sure that a function is only invoked on a machine that
3179 supports the particular ISA it is compiled for (for example by using
3180 @code{cpuid} on x86 to determine what feature bits and architecture
3184 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
3185 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
3188 You can either use multiple
3189 strings separated by commas to specify multiple options,
3190 or separate the options with a comma (@samp{,}) within a single string.
3192 The options supported are specific to each target; refer to @ref{x86
3193 Function Attributes}, @ref{PowerPC Function Attributes},
3194 @ref{ARM Function Attributes},and @ref{Nios II Function Attributes},
3197 @item target_clones (@var{options})
3198 @cindex @code{target_clones} function attribute
3199 The @code{target_clones} attribute is used to specify that a function
3200 be cloned into multiple versions compiled with different target options
3201 than specified on the command line. The supported options and restrictions
3202 are the same as for @code{target} attribute.
3204 For instance, on an x86, you could compile a function with
3205 @code{target_clones("sse4.1,avx")}. GCC creates two function clones,
3206 one compiled with @option{-msse4.1} and another with @option{-mavx}.
3207 It also creates a resolver function (see the @code{ifunc} attribute
3208 above) that dynamically selects a clone suitable for current architecture.
3211 @cindex @code{unused} function attribute
3212 This attribute, attached to a function, means that the function is meant
3213 to be possibly unused. GCC does not produce a warning for this
3217 @cindex @code{used} function attribute
3218 This attribute, attached to a function, means that code must be emitted
3219 for the function even if it appears that the function is not referenced.
3220 This is useful, for example, when the function is referenced only in
3223 When applied to a member function of a C++ class template, the
3224 attribute also means that the function is instantiated if the
3225 class itself is instantiated.
3227 @item visibility ("@var{visibility_type}")
3228 @cindex @code{visibility} function attribute
3229 This attribute affects the linkage of the declaration to which it is attached.
3230 It can be applied to variables (@pxref{Common Variable Attributes}) and types
3231 (@pxref{Common Type Attributes}) as well as functions.
3233 There are four supported @var{visibility_type} values: default,
3234 hidden, protected or internal visibility.
3237 void __attribute__ ((visibility ("protected")))
3238 f () @{ /* @r{Do something.} */; @}
3239 int i __attribute__ ((visibility ("hidden")));
3242 The possible values of @var{visibility_type} correspond to the
3243 visibility settings in the ELF gABI.
3246 @c keep this list of visibilities in alphabetical order.
3249 Default visibility is the normal case for the object file format.
3250 This value is available for the visibility attribute to override other
3251 options that may change the assumed visibility of entities.
3253 On ELF, default visibility means that the declaration is visible to other
3254 modules and, in shared libraries, means that the declared entity may be
3257 On Darwin, default visibility means that the declaration is visible to
3260 Default visibility corresponds to ``external linkage'' in the language.
3263 Hidden visibility indicates that the entity declared has a new
3264 form of linkage, which we call ``hidden linkage''. Two
3265 declarations of an object with hidden linkage refer to the same object
3266 if they are in the same shared object.
3269 Internal visibility is like hidden visibility, but with additional
3270 processor specific semantics. Unless otherwise specified by the
3271 psABI, GCC defines internal visibility to mean that a function is
3272 @emph{never} called from another module. Compare this with hidden
3273 functions which, while they cannot be referenced directly by other
3274 modules, can be referenced indirectly via function pointers. By
3275 indicating that a function cannot be called from outside the module,
3276 GCC may for instance omit the load of a PIC register since it is known
3277 that the calling function loaded the correct value.
3280 Protected visibility is like default visibility except that it
3281 indicates that references within the defining module bind to the
3282 definition in that module. That is, the declared entity cannot be
3283 overridden by another module.
3287 All visibilities are supported on many, but not all, ELF targets
3288 (supported when the assembler supports the @samp{.visibility}
3289 pseudo-op). Default visibility is supported everywhere. Hidden
3290 visibility is supported on Darwin targets.
3292 The visibility attribute should be applied only to declarations that
3293 would otherwise have external linkage. The attribute should be applied
3294 consistently, so that the same entity should not be declared with
3295 different settings of the attribute.
3297 In C++, the visibility attribute applies to types as well as functions
3298 and objects, because in C++ types have linkage. A class must not have
3299 greater visibility than its non-static data member types and bases,
3300 and class members default to the visibility of their class. Also, a
3301 declaration without explicit visibility is limited to the visibility
3304 In C++, you can mark member functions and static member variables of a
3305 class with the visibility attribute. This is useful if you know a
3306 particular method or static member variable should only be used from
3307 one shared object; then you can mark it hidden while the rest of the
3308 class has default visibility. Care must be taken to avoid breaking
3309 the One Definition Rule; for example, it is usually not useful to mark
3310 an inline method as hidden without marking the whole class as hidden.
3312 A C++ namespace declaration can also have the visibility attribute.
3315 namespace nspace1 __attribute__ ((visibility ("protected")))
3316 @{ /* @r{Do something.} */; @}
3319 This attribute applies only to the particular namespace body, not to
3320 other definitions of the same namespace; it is equivalent to using
3321 @samp{#pragma GCC visibility} before and after the namespace
3322 definition (@pxref{Visibility Pragmas}).
3324 In C++, if a template argument has limited visibility, this
3325 restriction is implicitly propagated to the template instantiation.
3326 Otherwise, template instantiations and specializations default to the
3327 visibility of their template.
3329 If both the template and enclosing class have explicit visibility, the
3330 visibility from the template is used.
3332 @item warn_unused_result
3333 @cindex @code{warn_unused_result} function attribute
3334 The @code{warn_unused_result} attribute causes a warning to be emitted
3335 if a caller of the function with this attribute does not use its
3336 return value. This is useful for functions where not checking
3337 the result is either a security problem or always a bug, such as
3341 int fn () __attribute__ ((warn_unused_result));
3344 if (fn () < 0) return -1;
3351 results in warning on line 5.
3354 @cindex @code{weak} function attribute
3355 The @code{weak} attribute causes the declaration to be emitted as a weak
3356 symbol rather than a global. This is primarily useful in defining
3357 library functions that can be overridden in user code, though it can
3358 also be used with non-function declarations. Weak symbols are supported
3359 for ELF targets, and also for a.out targets when using the GNU assembler
3363 @itemx weakref ("@var{target}")
3364 @cindex @code{weakref} function attribute
3365 The @code{weakref} attribute marks a declaration as a weak reference.
3366 Without arguments, it should be accompanied by an @code{alias} attribute
3367 naming the target symbol. Optionally, the @var{target} may be given as
3368 an argument to @code{weakref} itself. In either case, @code{weakref}
3369 implicitly marks the declaration as @code{weak}. Without a
3370 @var{target}, given as an argument to @code{weakref} or to @code{alias},
3371 @code{weakref} is equivalent to @code{weak}.
3374 static int x() __attribute__ ((weakref ("y")));
3375 /* is equivalent to... */
3376 static int x() __attribute__ ((weak, weakref, alias ("y")));
3378 static int x() __attribute__ ((weakref));
3379 static int x() __attribute__ ((alias ("y")));
3382 A weak reference is an alias that does not by itself require a
3383 definition to be given for the target symbol. If the target symbol is
3384 only referenced through weak references, then it becomes a @code{weak}
3385 undefined symbol. If it is directly referenced, however, then such
3386 strong references prevail, and a definition is required for the
3387 symbol, not necessarily in the same translation unit.
3389 The effect is equivalent to moving all references to the alias to a
3390 separate translation unit, renaming the alias to the aliased symbol,
3391 declaring it as weak, compiling the two separate translation units and
3392 performing a reloadable link on them.
3394 At present, a declaration to which @code{weakref} is attached can
3395 only be @code{static}.
3400 @c This is the end of the target-independent attribute table
3402 @node AArch64 Function Attributes
3403 @subsection AArch64 Function Attributes
3405 The following target-specific function attributes are available for the
3406 AArch64 target. For the most part, these options mirror the behavior of
3407 similar command-line options (@pxref{AArch64 Options}), but on a
3411 @item general-regs-only
3412 @cindex @code{general-regs-only} function attribute, AArch64
3413 Indicates that no floating-point or Advanced SIMD registers should be
3414 used when generating code for this function. If the function explicitly
3415 uses floating-point code, then the compiler gives an error. This is
3416 the same behavior as that of the command-line option
3417 @option{-mgeneral-regs-only}.
3419 @item fix-cortex-a53-835769
3420 @cindex @code{fix-cortex-a53-835769} function attribute, AArch64
3421 Indicates that the workaround for the Cortex-A53 erratum 835769 should be
3422 applied to this function. To explicitly disable the workaround for this
3423 function specify the negated form: @code{no-fix-cortex-a53-835769}.
3424 This corresponds to the behavior of the command line options
3425 @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
3428 @cindex @code{cmodel=} function attribute, AArch64
3429 Indicates that code should be generated for a particular code model for
3430 this function. The behavior and permissible arguments are the same as
3431 for the command line option @option{-mcmodel=}.
3434 @cindex @code{strict-align} function attribute, AArch64
3435 Indicates that the compiler should not assume that unaligned memory references
3436 are handled by the system. The behavior is the same as for the command-line
3437 option @option{-mstrict-align}.
3439 @item omit-leaf-frame-pointer
3440 @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
3441 Indicates that the frame pointer should be omitted for a leaf function call.
3442 To keep the frame pointer, the inverse attribute
3443 @code{no-omit-leaf-frame-pointer} can be specified. These attributes have
3444 the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
3445 and @option{-mno-omit-leaf-frame-pointer}.
3448 @cindex @code{tls-dialect=} function attribute, AArch64
3449 Specifies the TLS dialect to use for this function. The behavior and
3450 permissible arguments are the same as for the command-line option
3451 @option{-mtls-dialect=}.
3454 @cindex @code{arch=} function attribute, AArch64
3455 Specifies the architecture version and architectural extensions to use
3456 for this function. The behavior and permissible arguments are the same as
3457 for the @option{-march=} command-line option.
3460 @cindex @code{tune=} function attribute, AArch64
3461 Specifies the core for which to tune the performance of this function.
3462 The behavior and permissible arguments are the same as for the @option{-mtune=}
3463 command-line option.
3466 @cindex @code{cpu=} function attribute, AArch64
3467 Specifies the core for which to tune the performance of this function and also
3468 whose architectural features to use. The behavior and valid arguments are the
3469 same as for the @option{-mcpu=} command-line option.
3473 The above target attributes can be specified as follows:
3476 __attribute__((target("@var{attr-string}")))
3484 where @code{@var{attr-string}} is one of the attribute strings specified above.
3486 Additionally, the architectural extension string may be specified on its
3487 own. This can be used to turn on and off particular architectural extensions
3488 without having to specify a particular architecture version or core. Example:
3491 __attribute__((target("+crc+nocrypto")))
3499 In this example @code{target("+crc+nocrypto")} enables the @code{crc}
3500 extension and disables the @code{crypto} extension for the function @code{foo}
3501 without modifying an existing @option{-march=} or @option{-mcpu} option.
3503 Multiple target function attributes can be specified by separating them with
3504 a comma. For example:
3506 __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
3514 is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
3515 and @code{crypto} extensions and tunes it for @code{cortex-a53}.
3517 @subsubsection Inlining rules
3518 Specifying target attributes on individual functions or performing link-time
3519 optimization across translation units compiled with different target options
3520 can affect function inlining rules:
3522 In particular, a caller function can inline a callee function only if the
3523 architectural features available to the callee are a subset of the features
3524 available to the caller.
3525 For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
3526 or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
3527 can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
3528 because the all the architectural features that function @code{bar} requires
3529 are available to function @code{foo}. Conversely, function @code{bar} cannot
3530 inline function @code{foo}.
3532 Additionally inlining a function compiled with @option{-mstrict-align} into a
3533 function compiled without @code{-mstrict-align} is not allowed.
3534 However, inlining a function compiled without @option{-mstrict-align} into a
3535 function compiled with @option{-mstrict-align} is allowed.
3537 Note that CPU tuning options and attributes such as the @option{-mcpu=},
3538 @option{-mtune=} do not inhibit inlining unless the CPU specified by the
3539 @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
3540 architectural feature rules specified above.
3542 @node ARC Function Attributes
3543 @subsection ARC Function Attributes
3545 These function attributes are supported by the ARC back end:
3549 @cindex @code{interrupt} function attribute, ARC
3550 Use this attribute to indicate
3551 that the specified function is an interrupt handler. The compiler generates
3552 function entry and exit sequences suitable for use in an interrupt handler
3553 when this attribute is present.
3555 On the ARC, you must specify the kind of interrupt to be handled
3556 in a parameter to the interrupt attribute like this:
3559 void f () __attribute__ ((interrupt ("ilink1")));
3562 Permissible values for this parameter are: @w{@code{ilink1}} and
3568 @cindex @code{long_call} function attribute, ARC
3569 @cindex @code{medium_call} function attribute, ARC
3570 @cindex @code{short_call} function attribute, ARC
3571 @cindex indirect calls, ARC
3572 These attributes specify how a particular function is called.
3573 These attributes override the
3574 @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
3575 command-line switches and @code{#pragma long_calls} settings.
3577 For ARC, a function marked with the @code{long_call} attribute is
3578 always called using register-indirect jump-and-link instructions,
3579 thereby enabling the called function to be placed anywhere within the
3580 32-bit address space. A function marked with the @code{medium_call}
3581 attribute will always be close enough to be called with an unconditional
3582 branch-and-link instruction, which has a 25-bit offset from
3583 the call site. A function marked with the @code{short_call}
3584 attribute will always be close enough to be called with a conditional
3585 branch-and-link instruction, which has a 21-bit offset from
3589 @node ARM Function Attributes
3590 @subsection ARM Function Attributes
3592 These function attributes are supported for ARM targets:
3596 @cindex @code{interrupt} function attribute, ARM
3597 Use this attribute to indicate
3598 that the specified function is an interrupt handler. The compiler generates
3599 function entry and exit sequences suitable for use in an interrupt handler
3600 when this attribute is present.
3602 You can specify the kind of interrupt to be handled by
3603 adding an optional parameter to the interrupt attribute like this:
3606 void f () __attribute__ ((interrupt ("IRQ")));
3610 Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
3611 @code{SWI}, @code{ABORT} and @code{UNDEF}.
3613 On ARMv7-M the interrupt type is ignored, and the attribute means the function
3614 may be called with a word-aligned stack pointer.
3617 @cindex @code{isr} function attribute, ARM
3618 Use this attribute on ARM to write Interrupt Service Routines. This is an
3619 alias to the @code{interrupt} attribute above.
3623 @cindex @code{long_call} function attribute, ARM
3624 @cindex @code{short_call} function attribute, ARM
3625 @cindex indirect calls, ARM
3626 These attributes specify how a particular function is called.
3627 These attributes override the
3628 @option{-mlong-calls} (@pxref{ARM Options})
3629 command-line switch and @code{#pragma long_calls} settings. For ARM, the
3630 @code{long_call} attribute indicates that the function might be far
3631 away from the call site and require a different (more expensive)
3632 calling sequence. The @code{short_call} attribute always places
3633 the offset to the function from the call site into the @samp{BL}
3634 instruction directly.
3637 @cindex @code{naked} function attribute, ARM
3638 This attribute allows the compiler to construct the
3639 requisite function declaration, while allowing the body of the
3640 function to be assembly code. The specified function will not have
3641 prologue/epilogue sequences generated by the compiler. Only basic
3642 @code{asm} statements can safely be included in naked functions
3643 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
3644 basic @code{asm} and C code may appear to work, they cannot be
3645 depended upon to work reliably and are not supported.
3648 @cindex @code{pcs} function attribute, ARM
3650 The @code{pcs} attribute can be used to control the calling convention
3651 used for a function on ARM. The attribute takes an argument that specifies
3652 the calling convention to use.
3654 When compiling using the AAPCS ABI (or a variant of it) then valid
3655 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
3656 order to use a variant other than @code{"aapcs"} then the compiler must
3657 be permitted to use the appropriate co-processor registers (i.e., the
3658 VFP registers must be available in order to use @code{"aapcs-vfp"}).
3662 /* Argument passed in r0, and result returned in r0+r1. */
3663 double f2d (float) __attribute__((pcs("aapcs")));
3666 Variadic functions always use the @code{"aapcs"} calling convention and
3667 the compiler rejects attempts to specify an alternative.
3669 @item target (@var{options})
3670 @cindex @code{target} function attribute
3671 As discussed in @ref{Common Function Attributes}, this attribute
3672 allows specification of target-specific compilation options.
3674 On ARM, the following options are allowed:
3678 @cindex @code{target("thumb")} function attribute, ARM
3679 Force code generation in the Thumb (T16/T32) ISA, depending on the
3683 @cindex @code{target("arm")} function attribute, ARM
3684 Force code generation in the ARM (A32) ISA.
3686 Functions from different modes can be inlined in the caller's mode.
3689 @cindex @code{target("fpu=")} function attribute, ARM
3690 Specifies the fpu for which to tune the performance of this function.
3691 The behavior and permissible arguments are the same as for the @option{-mfpu=}
3692 command-line option.
3698 @node AVR Function Attributes
3699 @subsection AVR Function Attributes
3701 These function attributes are supported by the AVR back end:
3705 @cindex @code{interrupt} function attribute, AVR
3706 Use this attribute to indicate
3707 that the specified function is an interrupt handler. The compiler generates
3708 function entry and exit sequences suitable for use in an interrupt handler
3709 when this attribute is present.
3711 On the AVR, the hardware globally disables interrupts when an
3712 interrupt is executed. The first instruction of an interrupt handler
3713 declared with this attribute is a @code{SEI} instruction to
3714 re-enable interrupts. See also the @code{signal} function attribute
3715 that does not insert a @code{SEI} instruction. If both @code{signal} and
3716 @code{interrupt} are specified for the same function, @code{signal}
3717 is silently ignored.
3720 @cindex @code{naked} function attribute, AVR
3721 This attribute allows the compiler to construct the
3722 requisite function declaration, while allowing the body of the
3723 function to be assembly code. The specified function will not have
3724 prologue/epilogue sequences generated by the compiler. Only basic
3725 @code{asm} statements can safely be included in naked functions
3726 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
3727 basic @code{asm} and C code may appear to work, they cannot be
3728 depended upon to work reliably and are not supported.
3732 @cindex @code{OS_main} function attribute, AVR
3733 @cindex @code{OS_task} function attribute, AVR
3734 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
3735 do not save/restore any call-saved register in their prologue/epilogue.
3737 The @code{OS_main} attribute can be used when there @emph{is
3738 guarantee} that interrupts are disabled at the time when the function
3739 is entered. This saves resources when the stack pointer has to be
3740 changed to set up a frame for local variables.
3742 The @code{OS_task} attribute can be used when there is @emph{no
3743 guarantee} that interrupts are disabled at that time when the function
3744 is entered like for, e@.g@. task functions in a multi-threading operating
3745 system. In that case, changing the stack pointer register is
3746 guarded by save/clear/restore of the global interrupt enable flag.
3748 The differences to the @code{naked} function attribute are:
3750 @item @code{naked} functions do not have a return instruction whereas
3751 @code{OS_main} and @code{OS_task} functions have a @code{RET} or
3752 @code{RETI} return instruction.
3753 @item @code{naked} functions do not set up a frame for local variables
3754 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
3759 @cindex @code{signal} function attribute, AVR
3760 Use this attribute on the AVR to indicate that the specified
3761 function is an interrupt handler. The compiler generates function
3762 entry and exit sequences suitable for use in an interrupt handler when this
3763 attribute is present.
3765 See also the @code{interrupt} function attribute.
3767 The AVR hardware globally disables interrupts when an interrupt is executed.
3768 Interrupt handler functions defined with the @code{signal} attribute
3769 do not re-enable interrupts. It is save to enable interrupts in a
3770 @code{signal} handler. This ``save'' only applies to the code
3771 generated by the compiler and not to the IRQ layout of the
3772 application which is responsibility of the application.
3774 If both @code{signal} and @code{interrupt} are specified for the same
3775 function, @code{signal} is silently ignored.
3778 @node Blackfin Function Attributes
3779 @subsection Blackfin Function Attributes
3781 These function attributes are supported by the Blackfin back end:
3785 @item exception_handler
3786 @cindex @code{exception_handler} function attribute
3787 @cindex exception handler functions, Blackfin
3788 Use this attribute on the Blackfin to indicate that the specified function
3789 is an exception handler. The compiler generates function entry and
3790 exit sequences suitable for use in an exception handler when this
3791 attribute is present.
3793 @item interrupt_handler
3794 @cindex @code{interrupt_handler} function attribute, Blackfin
3795 Use this attribute to
3796 indicate that the specified function is an interrupt handler. The compiler
3797 generates function entry and exit sequences suitable for use in an
3798 interrupt handler when this attribute is present.
3801 @cindex @code{kspisusp} function attribute, Blackfin
3802 @cindex User stack pointer in interrupts on the Blackfin
3803 When used together with @code{interrupt_handler}, @code{exception_handler}
3804 or @code{nmi_handler}, code is generated to load the stack pointer
3805 from the USP register in the function prologue.
3808 @cindex @code{l1_text} function attribute, Blackfin
3809 This attribute specifies a function to be placed into L1 Instruction
3810 SRAM@. The function is put into a specific section named @code{.l1.text}.
3811 With @option{-mfdpic}, function calls with a such function as the callee
3812 or caller uses inlined PLT.
3815 @cindex @code{l2} function attribute, Blackfin
3816 This attribute specifies a function to be placed into L2
3817 SRAM. The function is put into a specific section named
3818 @code{.l2.text}. With @option{-mfdpic}, callers of such functions use
3823 @cindex indirect calls, Blackfin
3824 @cindex @code{longcall} function attribute, Blackfin
3825 @cindex @code{shortcall} function attribute, Blackfin
3826 The @code{longcall} attribute
3827 indicates that the function might be far away from the call site and
3828 require a different (more expensive) calling sequence. The
3829 @code{shortcall} attribute indicates that the function is always close
3830 enough for the shorter calling sequence to be used. These attributes
3831 override the @option{-mlongcall} switch.
3834 @cindex @code{nesting} function attribute, Blackfin
3835 @cindex Allow nesting in an interrupt handler on the Blackfin processor
3836 Use this attribute together with @code{interrupt_handler},
3837 @code{exception_handler} or @code{nmi_handler} to indicate that the function
3838 entry code should enable nested interrupts or exceptions.
3841 @cindex @code{nmi_handler} function attribute, Blackfin
3842 @cindex NMI handler functions on the Blackfin processor
3843 Use this attribute on the Blackfin to indicate that the specified function
3844 is an NMI handler. The compiler generates function entry and
3845 exit sequences suitable for use in an NMI handler when this
3846 attribute is present.
3849 @cindex @code{saveall} function attribute, Blackfin
3850 @cindex save all registers on the Blackfin
3851 Use this attribute to indicate that
3852 all registers except the stack pointer should be saved in the prologue
3853 regardless of whether they are used or not.
3856 @node CR16 Function Attributes
3857 @subsection CR16 Function Attributes
3859 These function attributes are supported by the CR16 back end:
3863 @cindex @code{interrupt} function attribute, CR16
3864 Use this attribute to indicate
3865 that the specified function is an interrupt handler. The compiler generates
3866 function entry and exit sequences suitable for use in an interrupt handler
3867 when this attribute is present.
3870 @node Epiphany Function Attributes
3871 @subsection Epiphany Function Attributes
3873 These function attributes are supported by the Epiphany back end:
3877 @cindex @code{disinterrupt} function attribute, Epiphany
3878 This attribute causes the compiler to emit
3879 instructions to disable interrupts for the duration of the given
3882 @item forwarder_section
3883 @cindex @code{forwarder_section} function attribute, Epiphany
3884 This attribute modifies the behavior of an interrupt handler.
3885 The interrupt handler may be in external memory which cannot be
3886 reached by a branch instruction, so generate a local memory trampoline
3887 to transfer control. The single parameter identifies the section where
3888 the trampoline is placed.
3891 @cindex @code{interrupt} function attribute, Epiphany
3892 Use this attribute to indicate
3893 that the specified function is an interrupt handler. The compiler generates
3894 function entry and exit sequences suitable for use in an interrupt handler
3895 when this attribute is present. It may also generate
3896 a special section with code to initialize the interrupt vector table.
3898 On Epiphany targets one or more optional parameters can be added like this:
3901 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
3904 Permissible values for these parameters are: @w{@code{reset}},
3905 @w{@code{software_exception}}, @w{@code{page_miss}},
3906 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
3907 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
3908 Multiple parameters indicate that multiple entries in the interrupt
3909 vector table should be initialized for this function, i.e.@: for each
3910 parameter @w{@var{name}}, a jump to the function is emitted in
3911 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
3912 entirely, in which case no interrupt vector table entry is provided.
3914 Note that interrupts are enabled inside the function
3915 unless the @code{disinterrupt} attribute is also specified.
3917 The following examples are all valid uses of these attributes on
3920 void __attribute__ ((interrupt)) universal_handler ();
3921 void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
3922 void __attribute__ ((interrupt ("dma0, dma1")))
3923 universal_dma_handler ();
3924 void __attribute__ ((interrupt ("timer0"), disinterrupt))
3925 fast_timer_handler ();
3926 void __attribute__ ((interrupt ("dma0, dma1"),
3927 forwarder_section ("tramp")))
3928 external_dma_handler ();
3933 @cindex @code{long_call} function attribute, Epiphany
3934 @cindex @code{short_call} function attribute, Epiphany
3935 @cindex indirect calls, Epiphany
3936 These attributes specify how a particular function is called.
3937 These attributes override the
3938 @option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
3939 command-line switch and @code{#pragma long_calls} settings.
3943 @node H8/300 Function Attributes
3944 @subsection H8/300 Function Attributes
3946 These function attributes are available for H8/300 targets:
3949 @item function_vector
3950 @cindex @code{function_vector} function attribute, H8/300
3951 Use this attribute on the H8/300, H8/300H, and H8S to indicate
3952 that the specified function should be called through the function vector.
3953 Calling a function through the function vector reduces code size; however,
3954 the function vector has a limited size (maximum 128 entries on the H8/300
3955 and 64 entries on the H8/300H and H8S)
3956 and shares space with the interrupt vector.
3958 @item interrupt_handler
3959 @cindex @code{interrupt_handler} function attribute, H8/300
3960 Use this attribute on the H8/300, H8/300H, and H8S to
3961 indicate that the specified function is an interrupt handler. The compiler
3962 generates function entry and exit sequences suitable for use in an
3963 interrupt handler when this attribute is present.
3966 @cindex @code{saveall} function attribute, H8/300
3967 @cindex save all registers on the H8/300, H8/300H, and H8S
3968 Use this attribute on the H8/300, H8/300H, and H8S to indicate that
3969 all registers except the stack pointer should be saved in the prologue
3970 regardless of whether they are used or not.
3973 @node IA-64 Function Attributes
3974 @subsection IA-64 Function Attributes
3976 These function attributes are supported on IA-64 targets:
3979 @item syscall_linkage
3980 @cindex @code{syscall_linkage} function attribute, IA-64
3981 This attribute is used to modify the IA-64 calling convention by marking
3982 all input registers as live at all function exits. This makes it possible
3983 to restart a system call after an interrupt without having to save/restore
3984 the input registers. This also prevents kernel data from leaking into
3988 @cindex @code{version_id} function attribute, IA-64
3989 This IA-64 HP-UX attribute, attached to a global variable or function, renames a
3990 symbol to contain a version string, thus allowing for function level
3991 versioning. HP-UX system header files may use function level versioning
3992 for some system calls.
3995 extern int foo () __attribute__((version_id ("20040821")));
3999 Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
4002 @node M32C Function Attributes
4003 @subsection M32C Function Attributes
4005 These function attributes are supported by the M32C back end:
4009 @cindex @code{bank_switch} function attribute, M32C
4010 When added to an interrupt handler with the M32C port, causes the
4011 prologue and epilogue to use bank switching to preserve the registers
4012 rather than saving them on the stack.
4014 @item fast_interrupt
4015 @cindex @code{fast_interrupt} function attribute, M32C
4016 Use this attribute on the M32C port to indicate that the specified
4017 function is a fast interrupt handler. This is just like the
4018 @code{interrupt} attribute, except that @code{freit} is used to return
4019 instead of @code{reit}.
4021 @item function_vector
4022 @cindex @code{function_vector} function attribute, M16C/M32C
4023 On M16C/M32C targets, the @code{function_vector} attribute declares a
4024 special page subroutine call function. Use of this attribute reduces
4025 the code size by 2 bytes for each call generated to the
4026 subroutine. The argument to the attribute is the vector number entry
4027 from the special page vector table which contains the 16 low-order
4028 bits of the subroutine's entry address. Each vector table has special
4029 page number (18 to 255) that is used in @code{jsrs} instructions.
4030 Jump addresses of the routines are generated by adding 0x0F0000 (in
4031 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
4032 2-byte addresses set in the vector table. Therefore you need to ensure
4033 that all the special page vector routines should get mapped within the
4034 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
4037 In the following example 2 bytes are saved for each call to
4038 function @code{foo}.
4041 void foo (void) __attribute__((function_vector(0x18)));
4052 If functions are defined in one file and are called in another file,
4053 then be sure to write this declaration in both files.
4055 This attribute is ignored for R8C target.
4058 @cindex @code{interrupt} function attribute, M32C
4059 Use this attribute to indicate
4060 that the specified function is an interrupt handler. The compiler generates
4061 function entry and exit sequences suitable for use in an interrupt handler
4062 when this attribute is present.
4065 @node M32R/D Function Attributes
4066 @subsection M32R/D Function Attributes
4068 These function attributes are supported by the M32R/D back end:
4072 @cindex @code{interrupt} function attribute, M32R/D
4073 Use this attribute to indicate
4074 that the specified function is an interrupt handler. The compiler generates
4075 function entry and exit sequences suitable for use in an interrupt handler
4076 when this attribute is present.
4078 @item model (@var{model-name})
4079 @cindex @code{model} function attribute, M32R/D
4080 @cindex function addressability on the M32R/D
4082 On the M32R/D, use this attribute to set the addressability of an
4083 object, and of the code generated for a function. The identifier
4084 @var{model-name} is one of @code{small}, @code{medium}, or
4085 @code{large}, representing each of the code models.
4087 Small model objects live in the lower 16MB of memory (so that their
4088 addresses can be loaded with the @code{ld24} instruction), and are
4089 callable with the @code{bl} instruction.
4091 Medium model objects may live anywhere in the 32-bit address space (the
4092 compiler generates @code{seth/add3} instructions to load their addresses),
4093 and are callable with the @code{bl} instruction.
4095 Large model objects may live anywhere in the 32-bit address space (the
4096 compiler generates @code{seth/add3} instructions to load their addresses),
4097 and may not be reachable with the @code{bl} instruction (the compiler
4098 generates the much slower @code{seth/add3/jl} instruction sequence).
4101 @node m68k Function Attributes
4102 @subsection m68k Function Attributes
4104 These function attributes are supported by the m68k back end:
4108 @itemx interrupt_handler
4109 @cindex @code{interrupt} function attribute, m68k
4110 @cindex @code{interrupt_handler} function attribute, m68k
4111 Use this attribute to
4112 indicate that the specified function is an interrupt handler. The compiler
4113 generates function entry and exit sequences suitable for use in an
4114 interrupt handler when this attribute is present. Either name may be used.
4116 @item interrupt_thread
4117 @cindex @code{interrupt_thread} function attribute, fido
4118 Use this attribute on fido, a subarchitecture of the m68k, to indicate
4119 that the specified function is an interrupt handler that is designed
4120 to run as a thread. The compiler omits generate prologue/epilogue
4121 sequences and replaces the return instruction with a @code{sleep}
4122 instruction. This attribute is available only on fido.
4125 @node MCORE Function Attributes
4126 @subsection MCORE Function Attributes
4128 These function attributes are supported by the MCORE back end:
4132 @cindex @code{naked} function attribute, MCORE
4133 This attribute allows the compiler to construct the
4134 requisite function declaration, while allowing the body of the
4135 function to be assembly code. The specified function will not have
4136 prologue/epilogue sequences generated by the compiler. Only basic
4137 @code{asm} statements can safely be included in naked functions
4138 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4139 basic @code{asm} and C code may appear to work, they cannot be
4140 depended upon to work reliably and are not supported.
4143 @node MeP Function Attributes
4144 @subsection MeP Function Attributes
4146 These function attributes are supported by the MeP back end:
4150 @cindex @code{disinterrupt} function attribute, MeP
4151 On MeP targets, this attribute causes the compiler to emit
4152 instructions to disable interrupts for the duration of the given
4156 @cindex @code{interrupt} function attribute, MeP
4157 Use this attribute to indicate
4158 that the specified function is an interrupt handler. The compiler generates
4159 function entry and exit sequences suitable for use in an interrupt handler
4160 when this attribute is present.
4163 @cindex @code{near} function attribute, MeP
4164 This attribute causes the compiler to assume the called
4165 function is close enough to use the normal calling convention,
4166 overriding the @option{-mtf} command-line option.
4169 @cindex @code{far} function attribute, MeP
4170 On MeP targets this causes the compiler to use a calling convention
4171 that assumes the called function is too far away for the built-in
4175 @cindex @code{vliw} function attribute, MeP
4176 The @code{vliw} attribute tells the compiler to emit
4177 instructions in VLIW mode instead of core mode. Note that this
4178 attribute is not allowed unless a VLIW coprocessor has been configured
4179 and enabled through command-line options.
4182 @node MicroBlaze Function Attributes
4183 @subsection MicroBlaze Function Attributes
4185 These function attributes are supported on MicroBlaze targets:
4188 @item save_volatiles
4189 @cindex @code{save_volatiles} function attribute, MicroBlaze
4190 Use this attribute to indicate that the function is
4191 an interrupt handler. All volatile registers (in addition to non-volatile
4192 registers) are saved in the function prologue. If the function is a leaf
4193 function, only volatiles used by the function are saved. A normal function
4194 return is generated instead of a return from interrupt.
4197 @cindex @code{break_handler} function attribute, MicroBlaze
4198 @cindex break handler functions
4199 Use this attribute to indicate that
4200 the specified function is a break handler. The compiler generates function
4201 entry and exit sequences suitable for use in an break handler when this
4202 attribute is present. The return from @code{break_handler} is done through
4203 the @code{rtbd} instead of @code{rtsd}.
4206 void f () __attribute__ ((break_handler));
4209 @item interrupt_handler
4210 @itemx fast_interrupt
4211 @cindex @code{interrupt_handler} function attribute, MicroBlaze
4212 @cindex @code{fast_interrupt} function attribute, MicroBlaze
4213 These attributes indicate that the specified function is an interrupt
4214 handler. Use the @code{fast_interrupt} attribute to indicate handlers
4215 used in low-latency interrupt mode, and @code{interrupt_handler} for
4216 interrupts that do not use low-latency handlers. In both cases, GCC
4217 emits appropriate prologue code and generates a return from the handler
4218 using @code{rtid} instead of @code{rtsd}.
4221 @node Microsoft Windows Function Attributes
4222 @subsection Microsoft Windows Function Attributes
4224 The following attributes are available on Microsoft Windows and Symbian OS
4229 @cindex @code{dllexport} function attribute
4230 @cindex @code{__declspec(dllexport)}
4231 On Microsoft Windows targets and Symbian OS targets the
4232 @code{dllexport} attribute causes the compiler to provide a global
4233 pointer to a pointer in a DLL, so that it can be referenced with the
4234 @code{dllimport} attribute. On Microsoft Windows targets, the pointer
4235 name is formed by combining @code{_imp__} and the function or variable
4238 You can use @code{__declspec(dllexport)} as a synonym for
4239 @code{__attribute__ ((dllexport))} for compatibility with other
4242 On systems that support the @code{visibility} attribute, this
4243 attribute also implies ``default'' visibility. It is an error to
4244 explicitly specify any other visibility.
4246 GCC's default behavior is to emit all inline functions with the
4247 @code{dllexport} attribute. Since this can cause object file-size bloat,
4248 you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
4249 ignore the attribute for inlined functions unless the
4250 @option{-fkeep-inline-functions} flag is used instead.
4252 The attribute is ignored for undefined symbols.
4254 When applied to C++ classes, the attribute marks defined non-inlined
4255 member functions and static data members as exports. Static consts
4256 initialized in-class are not marked unless they are also defined
4259 For Microsoft Windows targets there are alternative methods for
4260 including the symbol in the DLL's export table such as using a
4261 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
4262 the @option{--export-all} linker flag.
4265 @cindex @code{dllimport} function attribute
4266 @cindex @code{__declspec(dllimport)}
4267 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
4268 attribute causes the compiler to reference a function or variable via
4269 a global pointer to a pointer that is set up by the DLL exporting the
4270 symbol. The attribute implies @code{extern}. On Microsoft Windows
4271 targets, the pointer name is formed by combining @code{_imp__} and the
4272 function or variable name.
4274 You can use @code{__declspec(dllimport)} as a synonym for
4275 @code{__attribute__ ((dllimport))} for compatibility with other
4278 On systems that support the @code{visibility} attribute, this
4279 attribute also implies ``default'' visibility. It is an error to
4280 explicitly specify any other visibility.
4282 Currently, the attribute is ignored for inlined functions. If the
4283 attribute is applied to a symbol @emph{definition}, an error is reported.
4284 If a symbol previously declared @code{dllimport} is later defined, the
4285 attribute is ignored in subsequent references, and a warning is emitted.
4286 The attribute is also overridden by a subsequent declaration as
4289 When applied to C++ classes, the attribute marks non-inlined
4290 member functions and static data members as imports. However, the
4291 attribute is ignored for virtual methods to allow creation of vtables
4294 On the SH Symbian OS target the @code{dllimport} attribute also has
4295 another affect---it can cause the vtable and run-time type information
4296 for a class to be exported. This happens when the class has a
4297 dllimported constructor or a non-inline, non-pure virtual function
4298 and, for either of those two conditions, the class also has an inline
4299 constructor or destructor and has a key function that is defined in
4300 the current translation unit.
4302 For Microsoft Windows targets the use of the @code{dllimport}
4303 attribute on functions is not necessary, but provides a small
4304 performance benefit by eliminating a thunk in the DLL@. The use of the
4305 @code{dllimport} attribute on imported variables can be avoided by passing the
4306 @option{--enable-auto-import} switch to the GNU linker. As with
4307 functions, using the attribute for a variable eliminates a thunk in
4310 One drawback to using this attribute is that a pointer to a
4311 @emph{variable} marked as @code{dllimport} cannot be used as a constant
4312 address. However, a pointer to a @emph{function} with the
4313 @code{dllimport} attribute can be used as a constant initializer; in
4314 this case, the address of a stub function in the import lib is
4315 referenced. On Microsoft Windows targets, the attribute can be disabled
4316 for functions by setting the @option{-mnop-fun-dllimport} flag.
4319 @node MIPS Function Attributes
4320 @subsection MIPS Function Attributes
4322 These function attributes are supported by the MIPS back end:
4326 @cindex @code{interrupt} function attribute, MIPS
4327 Use this attribute to indicate that the specified function is an interrupt
4328 handler. The compiler generates function entry and exit sequences suitable
4329 for use in an interrupt handler when this attribute is present.
4330 An optional argument is supported for the interrupt attribute which allows
4331 the interrupt mode to be described. By default GCC assumes the external
4332 interrupt controller (EIC) mode is in use, this can be explicitly set using
4333 @code{eic}. When interrupts are non-masked then the requested Interrupt
4334 Priority Level (IPL) is copied to the current IPL which has the effect of only
4335 enabling higher priority interrupts. To use vectored interrupt mode use
4336 the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
4337 the behaviour of the non-masked interrupt support and GCC will arrange to mask
4338 all interrupts from sw0 up to and including the specified interrupt vector.
4340 You can use the following attributes to modify the behavior
4341 of an interrupt handler:
4343 @item use_shadow_register_set
4344 @cindex @code{use_shadow_register_set} function attribute, MIPS
4345 Assume that the handler uses a shadow register set, instead of
4346 the main general-purpose registers. An optional argument @code{intstack} is
4347 supported to indicate that the shadow register set contains a valid stack
4350 @item keep_interrupts_masked
4351 @cindex @code{keep_interrupts_masked} function attribute, MIPS
4352 Keep interrupts masked for the whole function. Without this attribute,
4353 GCC tries to reenable interrupts for as much of the function as it can.
4355 @item use_debug_exception_return
4356 @cindex @code{use_debug_exception_return} function attribute, MIPS
4357 Return using the @code{deret} instruction. Interrupt handlers that don't
4358 have this attribute return using @code{eret} instead.
4361 You can use any combination of these attributes, as shown below:
4363 void __attribute__ ((interrupt)) v0 ();
4364 void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
4365 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
4366 void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
4367 void __attribute__ ((interrupt, use_shadow_register_set,
4368 keep_interrupts_masked)) v4 ();
4369 void __attribute__ ((interrupt, use_shadow_register_set,
4370 use_debug_exception_return)) v5 ();
4371 void __attribute__ ((interrupt, keep_interrupts_masked,
4372 use_debug_exception_return)) v6 ();
4373 void __attribute__ ((interrupt, use_shadow_register_set,
4374 keep_interrupts_masked,
4375 use_debug_exception_return)) v7 ();
4376 void __attribute__ ((interrupt("eic"))) v8 ();
4377 void __attribute__ ((interrupt("vector=hw3"))) v9 ();
4383 @cindex indirect calls, MIPS
4384 @cindex @code{long_call} function attribute, MIPS
4385 @cindex @code{near} function attribute, MIPS
4386 @cindex @code{far} function attribute, MIPS
4387 These attributes specify how a particular function is called on MIPS@.
4388 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
4389 command-line switch. The @code{long_call} and @code{far} attributes are
4390 synonyms, and cause the compiler to always call
4391 the function by first loading its address into a register, and then using
4392 the contents of that register. The @code{near} attribute has the opposite
4393 effect; it specifies that non-PIC calls should be made using the more
4394 efficient @code{jal} instruction.
4398 @cindex @code{mips16} function attribute, MIPS
4399 @cindex @code{nomips16} function attribute, MIPS
4401 On MIPS targets, you can use the @code{mips16} and @code{nomips16}
4402 function attributes to locally select or turn off MIPS16 code generation.
4403 A function with the @code{mips16} attribute is emitted as MIPS16 code,
4404 while MIPS16 code generation is disabled for functions with the
4405 @code{nomips16} attribute. These attributes override the
4406 @option{-mips16} and @option{-mno-mips16} options on the command line
4407 (@pxref{MIPS Options}).
4409 When compiling files containing mixed MIPS16 and non-MIPS16 code, the
4410 preprocessor symbol @code{__mips16} reflects the setting on the command line,
4411 not that within individual functions. Mixed MIPS16 and non-MIPS16 code
4412 may interact badly with some GCC extensions such as @code{__builtin_apply}
4413 (@pxref{Constructing Calls}).
4415 @item micromips, MIPS
4416 @itemx nomicromips, MIPS
4417 @cindex @code{micromips} function attribute
4418 @cindex @code{nomicromips} function attribute
4420 On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
4421 function attributes to locally select or turn off microMIPS code generation.
4422 A function with the @code{micromips} attribute is emitted as microMIPS code,
4423 while microMIPS code generation is disabled for functions with the
4424 @code{nomicromips} attribute. These attributes override the
4425 @option{-mmicromips} and @option{-mno-micromips} options on the command line
4426 (@pxref{MIPS Options}).
4428 When compiling files containing mixed microMIPS and non-microMIPS code, the
4429 preprocessor symbol @code{__mips_micromips} reflects the setting on the
4431 not that within individual functions. Mixed microMIPS and non-microMIPS code
4432 may interact badly with some GCC extensions such as @code{__builtin_apply}
4433 (@pxref{Constructing Calls}).
4436 @cindex @code{nocompression} function attribute, MIPS
4437 On MIPS targets, you can use the @code{nocompression} function attribute
4438 to locally turn off MIPS16 and microMIPS code generation. This attribute
4439 overrides the @option{-mips16} and @option{-mmicromips} options on the
4440 command line (@pxref{MIPS Options}).
4443 @node MSP430 Function Attributes
4444 @subsection MSP430 Function Attributes
4446 These function attributes are supported by the MSP430 back end:
4450 @cindex @code{critical} function attribute, MSP430
4451 Critical functions disable interrupts upon entry and restore the
4452 previous interrupt state upon exit. Critical functions cannot also
4453 have the @code{naked} or @code{reentrant} attributes. They can have
4454 the @code{interrupt} attribute.
4457 @cindex @code{interrupt} function attribute, MSP430
4458 Use this attribute to indicate
4459 that the specified function is an interrupt handler. The compiler generates
4460 function entry and exit sequences suitable for use in an interrupt handler
4461 when this attribute is present.
4463 You can provide an argument to the interrupt
4464 attribute which specifies a name or number. If the argument is a
4465 number it indicates the slot in the interrupt vector table (0 - 31) to
4466 which this handler should be assigned. If the argument is a name it
4467 is treated as a symbolic name for the vector slot. These names should
4468 match up with appropriate entries in the linker script. By default
4469 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
4470 @code{reset} for vector 31 are recognized.
4473 @cindex @code{naked} function attribute, MSP430
4474 This attribute allows the compiler to construct the
4475 requisite function declaration, while allowing the body of the
4476 function to be assembly code. The specified function will not have
4477 prologue/epilogue sequences generated by the compiler. Only basic
4478 @code{asm} statements can safely be included in naked functions
4479 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4480 basic @code{asm} and C code may appear to work, they cannot be
4481 depended upon to work reliably and are not supported.
4484 @cindex @code{reentrant} function attribute, MSP430
4485 Reentrant functions disable interrupts upon entry and enable them
4486 upon exit. Reentrant functions cannot also have the @code{naked}
4487 or @code{critical} attributes. They can have the @code{interrupt}
4491 @cindex @code{wakeup} function attribute, MSP430
4492 This attribute only applies to interrupt functions. It is silently
4493 ignored if applied to a non-interrupt function. A wakeup interrupt
4494 function will rouse the processor from any low-power state that it
4495 might be in when the function exits.
4500 @cindex @code{lower} function attribute, MSP430
4501 @cindex @code{upper} function attribute, MSP430
4502 @cindex @code{either} function attribute, MSP430
4503 On the MSP430 target these attributes can be used to specify whether
4504 the function or variable should be placed into low memory, high
4505 memory, or the placement should be left to the linker to decide. The
4506 attributes are only significant if compiling for the MSP430X
4509 The attributes work in conjunction with a linker script that has been
4510 augmented to specify where to place sections with a @code{.lower} and
4511 a @code{.upper} prefix. So, for example, as well as placing the
4512 @code{.data} section, the script also specifies the placement of a
4513 @code{.lower.data} and a @code{.upper.data} section. The intention
4514 is that @code{lower} sections are placed into a small but easier to
4515 access memory region and the upper sections are placed into a larger, but
4516 slower to access, region.
4518 The @code{either} attribute is special. It tells the linker to place
4519 the object into the corresponding @code{lower} section if there is
4520 room for it. If there is insufficient room then the object is placed
4521 into the corresponding @code{upper} section instead. Note that the
4522 placement algorithm is not very sophisticated. It does not attempt to
4523 find an optimal packing of the @code{lower} sections. It just makes
4524 one pass over the objects and does the best that it can. Using the
4525 @option{-ffunction-sections} and @option{-fdata-sections} command-line
4526 options can help the packing, however, since they produce smaller,
4527 easier to pack regions.
4530 @node NDS32 Function Attributes
4531 @subsection NDS32 Function Attributes
4533 These function attributes are supported by the NDS32 back end:
4537 @cindex @code{exception} function attribute
4538 @cindex exception handler functions, NDS32
4539 Use this attribute on the NDS32 target to indicate that the specified function
4540 is an exception handler. The compiler will generate corresponding sections
4541 for use in an exception handler.
4544 @cindex @code{interrupt} function attribute, NDS32
4545 On NDS32 target, this attribute indicates that the specified function
4546 is an interrupt handler. The compiler generates corresponding sections
4547 for use in an interrupt handler. You can use the following attributes
4548 to modify the behavior:
4551 @cindex @code{nested} function attribute, NDS32
4552 This interrupt service routine is interruptible.
4554 @cindex @code{not_nested} function attribute, NDS32
4555 This interrupt service routine is not interruptible.
4557 @cindex @code{nested_ready} function attribute, NDS32
4558 This interrupt service routine is interruptible after @code{PSW.GIE}
4559 (global interrupt enable) is set. This allows interrupt service routine to
4560 finish some short critical code before enabling interrupts.
4562 @cindex @code{save_all} function attribute, NDS32
4563 The system will help save all registers into stack before entering
4566 @cindex @code{partial_save} function attribute, NDS32
4567 The system will help save caller registers into stack before entering
4572 @cindex @code{naked} function attribute, NDS32
4573 This attribute allows the compiler to construct the
4574 requisite function declaration, while allowing the body of the
4575 function to be assembly code. The specified function will not have
4576 prologue/epilogue sequences generated by the compiler. Only basic
4577 @code{asm} statements can safely be included in naked functions
4578 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4579 basic @code{asm} and C code may appear to work, they cannot be
4580 depended upon to work reliably and are not supported.
4583 @cindex @code{reset} function attribute, NDS32
4584 @cindex reset handler functions
4585 Use this attribute on the NDS32 target to indicate that the specified function
4586 is a reset handler. The compiler will generate corresponding sections
4587 for use in a reset handler. You can use the following attributes
4588 to provide extra exception handling:
4591 @cindex @code{nmi} function attribute, NDS32
4592 Provide a user-defined function to handle NMI exception.
4594 @cindex @code{warm} function attribute, NDS32
4595 Provide a user-defined function to handle warm reset exception.
4599 @node Nios II Function Attributes
4600 @subsection Nios II Function Attributes
4602 These function attributes are supported by the Nios II back end:
4605 @item target (@var{options})
4606 @cindex @code{target} function attribute
4607 As discussed in @ref{Common Function Attributes}, this attribute
4608 allows specification of target-specific compilation options.
4610 When compiling for Nios II, the following options are allowed:
4613 @item custom-@var{insn}=@var{N}
4614 @itemx no-custom-@var{insn}
4615 @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II
4616 @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II
4617 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
4618 custom instruction with encoding @var{N} when generating code that uses
4619 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
4620 the custom instruction @var{insn}.
4621 These target attributes correspond to the
4622 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
4623 command-line options, and support the same set of @var{insn} keywords.
4624 @xref{Nios II Options}, for more information.
4626 @item custom-fpu-cfg=@var{name}
4627 @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II
4628 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
4629 command-line option, to select a predefined set of custom instructions
4631 @xref{Nios II Options}, for more information.
4635 @node PowerPC Function Attributes
4636 @subsection PowerPC Function Attributes
4638 These function attributes are supported by the PowerPC back end:
4643 @cindex indirect calls, PowerPC
4644 @cindex @code{longcall} function attribute, PowerPC
4645 @cindex @code{shortcall} function attribute, PowerPC
4646 The @code{longcall} attribute
4647 indicates that the function might be far away from the call site and
4648 require a different (more expensive) calling sequence. The
4649 @code{shortcall} attribute indicates that the function is always close
4650 enough for the shorter calling sequence to be used. These attributes
4651 override both the @option{-mlongcall} switch and
4652 the @code{#pragma longcall} setting.
4654 @xref{RS/6000 and PowerPC Options}, for more information on whether long
4655 calls are necessary.
4657 @item target (@var{options})
4658 @cindex @code{target} function attribute
4659 As discussed in @ref{Common Function Attributes}, this attribute
4660 allows specification of target-specific compilation options.
4662 On the PowerPC, the following options are allowed:
4667 @cindex @code{target("altivec")} function attribute, PowerPC
4668 Generate code that uses (does not use) AltiVec instructions. In
4669 32-bit code, you cannot enable AltiVec instructions unless
4670 @option{-mabi=altivec} is used on the command line.
4674 @cindex @code{target("cmpb")} function attribute, PowerPC
4675 Generate code that uses (does not use) the compare bytes instruction
4676 implemented on the POWER6 processor and other processors that support
4677 the PowerPC V2.05 architecture.
4681 @cindex @code{target("dlmzb")} function attribute, PowerPC
4682 Generate code that uses (does not use) the string-search @samp{dlmzb}
4683 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
4684 generated by default when targeting those processors.
4688 @cindex @code{target("fprnd")} function attribute, PowerPC
4689 Generate code that uses (does not use) the FP round to integer
4690 instructions implemented on the POWER5+ processor and other processors
4691 that support the PowerPC V2.03 architecture.
4695 @cindex @code{target("hard-dfp")} function attribute, PowerPC
4696 Generate code that uses (does not use) the decimal floating-point
4697 instructions implemented on some POWER processors.
4701 @cindex @code{target("isel")} function attribute, PowerPC
4702 Generate code that uses (does not use) ISEL instruction.
4706 @cindex @code{target("mfcrf")} function attribute, PowerPC
4707 Generate code that uses (does not use) the move from condition
4708 register field instruction implemented on the POWER4 processor and
4709 other processors that support the PowerPC V2.01 architecture.
4713 @cindex @code{target("mfpgpr")} function attribute, PowerPC
4714 Generate code that uses (does not use) the FP move to/from general
4715 purpose register instructions implemented on the POWER6X processor and
4716 other processors that support the extended PowerPC V2.05 architecture.
4720 @cindex @code{target("mulhw")} function attribute, PowerPC
4721 Generate code that uses (does not use) the half-word multiply and
4722 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
4723 These instructions are generated by default when targeting those
4728 @cindex @code{target("multiple")} function attribute, PowerPC
4729 Generate code that uses (does not use) the load multiple word
4730 instructions and the store multiple word instructions.
4734 @cindex @code{target("update")} function attribute, PowerPC
4735 Generate code that uses (does not use) the load or store instructions
4736 that update the base register to the address of the calculated memory
4741 @cindex @code{target("popcntb")} function attribute, PowerPC
4742 Generate code that uses (does not use) the popcount and double-precision
4743 FP reciprocal estimate instruction implemented on the POWER5
4744 processor and other processors that support the PowerPC V2.02
4749 @cindex @code{target("popcntd")} function attribute, PowerPC
4750 Generate code that uses (does not use) the popcount instruction
4751 implemented on the POWER7 processor and other processors that support
4752 the PowerPC V2.06 architecture.
4754 @item powerpc-gfxopt
4755 @itemx no-powerpc-gfxopt
4756 @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
4757 Generate code that uses (does not use) the optional PowerPC
4758 architecture instructions in the Graphics group, including
4759 floating-point select.
4762 @itemx no-powerpc-gpopt
4763 @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
4764 Generate code that uses (does not use) the optional PowerPC
4765 architecture instructions in the General Purpose group, including
4766 floating-point square root.
4768 @item recip-precision
4769 @itemx no-recip-precision
4770 @cindex @code{target("recip-precision")} function attribute, PowerPC
4771 Assume (do not assume) that the reciprocal estimate instructions
4772 provide higher-precision estimates than is mandated by the PowerPC
4777 @cindex @code{target("string")} function attribute, PowerPC
4778 Generate code that uses (does not use) the load string instructions
4779 and the store string word instructions to save multiple registers and
4780 do small block moves.
4784 @cindex @code{target("vsx")} function attribute, PowerPC
4785 Generate code that uses (does not use) vector/scalar (VSX)
4786 instructions, and also enable the use of built-in functions that allow
4787 more direct access to the VSX instruction set. In 32-bit code, you
4788 cannot enable VSX or AltiVec instructions unless
4789 @option{-mabi=altivec} is used on the command line.
4793 @cindex @code{target("friz")} function attribute, PowerPC
4794 Generate (do not generate) the @code{friz} instruction when the
4795 @option{-funsafe-math-optimizations} option is used to optimize
4796 rounding a floating-point value to 64-bit integer and back to floating
4797 point. The @code{friz} instruction does not return the same value if
4798 the floating-point number is too large to fit in an integer.
4800 @item avoid-indexed-addresses
4801 @itemx no-avoid-indexed-addresses
4802 @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
4803 Generate code that tries to avoid (not avoid) the use of indexed load
4804 or store instructions.
4808 @cindex @code{target("paired")} function attribute, PowerPC
4809 Generate code that uses (does not use) the generation of PAIRED simd
4814 @cindex @code{target("longcall")} function attribute, PowerPC
4815 Generate code that assumes (does not assume) that all calls are far
4816 away so that a longer more expensive calling sequence is required.
4819 @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
4820 Specify the architecture to generate code for when compiling the
4821 function. If you select the @code{target("cpu=power7")} attribute when
4822 generating 32-bit code, VSX and AltiVec instructions are not generated
4823 unless you use the @option{-mabi=altivec} option on the command line.
4825 @item tune=@var{TUNE}
4826 @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
4827 Specify the architecture to tune for when compiling the function. If
4828 you do not specify the @code{target("tune=@var{TUNE}")} attribute and
4829 you do specify the @code{target("cpu=@var{CPU}")} attribute,
4830 compilation tunes for the @var{CPU} architecture, and not the
4831 default tuning specified on the command line.
4834 On the PowerPC, the inliner does not inline a
4835 function that has different target options than the caller, unless the
4836 callee has a subset of the target options of the caller.
4839 @node RL78 Function Attributes
4840 @subsection RL78 Function Attributes
4842 These function attributes are supported by the RL78 back end:
4846 @itemx brk_interrupt
4847 @cindex @code{interrupt} function attribute, RL78
4848 @cindex @code{brk_interrupt} function attribute, RL78
4849 These attributes indicate
4850 that the specified function is an interrupt handler. The compiler generates
4851 function entry and exit sequences suitable for use in an interrupt handler
4852 when this attribute is present.
4854 Use @code{brk_interrupt} instead of @code{interrupt} for
4855 handlers intended to be used with the @code{BRK} opcode (i.e.@: those
4856 that must end with @code{RETB} instead of @code{RETI}).
4859 @cindex @code{naked} function attribute, RL78
4860 This attribute allows the compiler to construct the
4861 requisite function declaration, while allowing the body of the
4862 function to be assembly code. The specified function will not have
4863 prologue/epilogue sequences generated by the compiler. Only basic
4864 @code{asm} statements can safely be included in naked functions
4865 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4866 basic @code{asm} and C code may appear to work, they cannot be
4867 depended upon to work reliably and are not supported.
4870 @node RX Function Attributes
4871 @subsection RX Function Attributes
4873 These function attributes are supported by the RX back end:
4876 @item fast_interrupt
4877 @cindex @code{fast_interrupt} function attribute, RX
4878 Use this attribute on the RX port to indicate that the specified
4879 function is a fast interrupt handler. This is just like the
4880 @code{interrupt} attribute, except that @code{freit} is used to return
4881 instead of @code{reit}.
4884 @cindex @code{interrupt} function attribute, RX
4885 Use this attribute to indicate
4886 that the specified function is an interrupt handler. The compiler generates
4887 function entry and exit sequences suitable for use in an interrupt handler
4888 when this attribute is present.
4890 On RX targets, you may specify one or more vector numbers as arguments
4891 to the attribute, as well as naming an alternate table name.
4892 Parameters are handled sequentially, so one handler can be assigned to
4893 multiple entries in multiple tables. One may also pass the magic
4894 string @code{"$default"} which causes the function to be used for any
4895 unfilled slots in the current table.
4897 This example shows a simple assignment of a function to one vector in
4898 the default table (note that preprocessor macros may be used for
4899 chip-specific symbolic vector names):
4901 void __attribute__ ((interrupt (5))) txd1_handler ();
4904 This example assigns a function to two slots in the default table
4905 (using preprocessor macros defined elsewhere) and makes it the default
4906 for the @code{dct} table:
4908 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
4913 @cindex @code{naked} function attribute, RX
4914 This attribute allows the compiler to construct the
4915 requisite function declaration, while allowing the body of the
4916 function to be assembly code. The specified function will not have
4917 prologue/epilogue sequences generated by the compiler. Only basic
4918 @code{asm} statements can safely be included in naked functions
4919 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
4920 basic @code{asm} and C code may appear to work, they cannot be
4921 depended upon to work reliably and are not supported.
4924 @cindex @code{vector} function attribute, RX
4925 This RX attribute is similar to the @code{interrupt} attribute, including its
4926 parameters, but does not make the function an interrupt-handler type
4927 function (i.e. it retains the normal C function calling ABI). See the
4928 @code{interrupt} attribute for a description of its arguments.
4931 @node S/390 Function Attributes
4932 @subsection S/390 Function Attributes
4934 These function attributes are supported on the S/390:
4937 @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
4938 @cindex @code{hotpatch} function attribute, S/390
4940 On S/390 System z targets, you can use this function attribute to
4941 make GCC generate a ``hot-patching'' function prologue. If the
4942 @option{-mhotpatch=} command-line option is used at the same time,
4943 the @code{hotpatch} attribute takes precedence. The first of the
4944 two arguments specifies the number of halfwords to be added before
4945 the function label. A second argument can be used to specify the
4946 number of halfwords to be added after the function label. For
4947 both arguments the maximum allowed value is 1000000.
4949 If both arguments are zero, hotpatching is disabled.
4951 @item target (@var{options})
4952 @cindex @code{target} function attribute
4953 As discussed in @ref{Common Function Attributes}, this attribute
4954 allows specification of target-specific compilation options.
4956 On S/390, the following options are supported:
4964 @item warn-framesize=
4976 @itemx no-packed-stack
4978 @itemx no-small-exec
4981 @item warn-dynamicstack
4982 @itemx no-warn-dynamicstack
4985 The options work exactly like the S/390 specific command line
4986 options (without the prefix @option{-m}) except that they do not
4987 change any feature macros. For example,
4990 @code{target("no-vx")}
4993 does not undefine the @code{__VEC__} macro.
4996 @node SH Function Attributes
4997 @subsection SH Function Attributes
4999 These function attributes are supported on the SH family of processors:
5002 @item function_vector
5003 @cindex @code{function_vector} function attribute, SH
5004 @cindex calling functions through the function vector on SH2A
5005 On SH2A targets, this attribute declares a function to be called using the
5006 TBR relative addressing mode. The argument to this attribute is the entry
5007 number of the same function in a vector table containing all the TBR
5008 relative addressable functions. For correct operation the TBR must be setup
5009 accordingly to point to the start of the vector table before any functions with
5010 this attribute are invoked. Usually a good place to do the initialization is
5011 the startup routine. The TBR relative vector table can have at max 256 function
5012 entries. The jumps to these functions are generated using a SH2A specific,
5013 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
5014 from GNU binutils version 2.7 or later for this attribute to work correctly.
5016 In an application, for a function being called once, this attribute
5017 saves at least 8 bytes of code; and if other successive calls are being
5018 made to the same function, it saves 2 bytes of code per each of these
5021 @item interrupt_handler
5022 @cindex @code{interrupt_handler} function attribute, SH
5023 Use this attribute to
5024 indicate that the specified function is an interrupt handler. The compiler
5025 generates function entry and exit sequences suitable for use in an
5026 interrupt handler when this attribute is present.
5028 @item nosave_low_regs
5029 @cindex @code{nosave_low_regs} function attribute, SH
5030 Use this attribute on SH targets to indicate that an @code{interrupt_handler}
5031 function should not save and restore registers R0..R7. This can be used on SH3*
5032 and SH4* targets that have a second R0..R7 register bank for non-reentrant
5036 @cindex @code{renesas} function attribute, SH
5037 On SH targets this attribute specifies that the function or struct follows the
5041 @cindex @code{resbank} function attribute, SH
5042 On the SH2A target, this attribute enables the high-speed register
5043 saving and restoration using a register bank for @code{interrupt_handler}
5044 routines. Saving to the bank is performed automatically after the CPU
5045 accepts an interrupt that uses a register bank.
5047 The nineteen 32-bit registers comprising general register R0 to R14,
5048 control register GBR, and system registers MACH, MACL, and PR and the
5049 vector table address offset are saved into a register bank. Register
5050 banks are stacked in first-in last-out (FILO) sequence. Restoration
5051 from the bank is executed by issuing a RESBANK instruction.
5054 @cindex @code{sp_switch} function attribute, SH
5055 Use this attribute on the SH to indicate an @code{interrupt_handler}
5056 function should switch to an alternate stack. It expects a string
5057 argument that names a global variable holding the address of the
5062 void f () __attribute__ ((interrupt_handler,
5063 sp_switch ("alt_stack")));
5067 @cindex @code{trap_exit} function attribute, SH
5068 Use this attribute on the SH for an @code{interrupt_handler} to return using
5069 @code{trapa} instead of @code{rte}. This attribute expects an integer
5070 argument specifying the trap number to be used.
5073 @cindex @code{trapa_handler} function attribute, SH
5074 On SH targets this function attribute is similar to @code{interrupt_handler}
5075 but it does not save and restore all registers.
5078 @node SPU Function Attributes
5079 @subsection SPU Function Attributes
5081 These function attributes are supported by the SPU back end:
5085 @cindex @code{naked} function attribute, SPU
5086 This attribute allows the compiler to construct the
5087 requisite function declaration, while allowing the body of the
5088 function to be assembly code. The specified function will not have
5089 prologue/epilogue sequences generated by the compiler. Only basic
5090 @code{asm} statements can safely be included in naked functions
5091 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
5092 basic @code{asm} and C code may appear to work, they cannot be
5093 depended upon to work reliably and are not supported.
5096 @node Symbian OS Function Attributes
5097 @subsection Symbian OS Function Attributes
5099 @xref{Microsoft Windows Function Attributes}, for discussion of the
5100 @code{dllexport} and @code{dllimport} attributes.
5102 @node Visium Function Attributes
5103 @subsection Visium Function Attributes
5105 These function attributes are supported by the Visium back end:
5109 @cindex @code{interrupt} function attribute, Visium
5110 Use this attribute to indicate
5111 that the specified function is an interrupt handler. The compiler generates
5112 function entry and exit sequences suitable for use in an interrupt handler
5113 when this attribute is present.
5116 @node x86 Function Attributes
5117 @subsection x86 Function Attributes
5119 These function attributes are supported by the x86 back end:
5123 @cindex @code{cdecl} function attribute, x86-32
5124 @cindex functions that pop the argument stack on x86-32
5126 On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
5127 assume that the calling function pops off the stack space used to
5128 pass arguments. This is
5129 useful to override the effects of the @option{-mrtd} switch.
5132 @cindex @code{fastcall} function attribute, x86-32
5133 @cindex functions that pop the argument stack on x86-32
5134 On x86-32 targets, the @code{fastcall} attribute causes the compiler to
5135 pass the first argument (if of integral type) in the register ECX and
5136 the second argument (if of integral type) in the register EDX@. Subsequent
5137 and other typed arguments are passed on the stack. The called function
5138 pops the arguments off the stack. If the number of arguments is variable all
5139 arguments are pushed on the stack.
5142 @cindex @code{thiscall} function attribute, x86-32
5143 @cindex functions that pop the argument stack on x86-32
5144 On x86-32 targets, the @code{thiscall} attribute causes the compiler to
5145 pass the first argument (if of integral type) in the register ECX.
5146 Subsequent and other typed arguments are passed on the stack. The called
5147 function pops the arguments off the stack.
5148 If the number of arguments is variable all arguments are pushed on the
5150 The @code{thiscall} attribute is intended for C++ non-static member functions.
5151 As a GCC extension, this calling convention can be used for C functions
5152 and for static member methods.
5156 @cindex @code{ms_abi} function attribute, x86
5157 @cindex @code{sysv_abi} function attribute, x86
5159 On 32-bit and 64-bit x86 targets, you can use an ABI attribute
5160 to indicate which calling convention should be used for a function. The
5161 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
5162 while the @code{sysv_abi} attribute tells the compiler to use the ABI
5163 used on GNU/Linux and other systems. The default is to use the Microsoft ABI
5164 when targeting Windows. On all other systems, the default is the x86/AMD ABI.
5166 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
5167 requires the @option{-maccumulate-outgoing-args} option.
5169 @item callee_pop_aggregate_return (@var{number})
5170 @cindex @code{callee_pop_aggregate_return} function attribute, x86
5172 On x86-32 targets, you can use this attribute to control how
5173 aggregates are returned in memory. If the caller is responsible for
5174 popping the hidden pointer together with the rest of the arguments, specify
5175 @var{number} equal to zero. If callee is responsible for popping the
5176 hidden pointer, specify @var{number} equal to one.
5178 The default x86-32 ABI assumes that the callee pops the
5179 stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
5180 the compiler assumes that the
5181 caller pops the stack for hidden pointer.
5183 @item ms_hook_prologue
5184 @cindex @code{ms_hook_prologue} function attribute, x86
5186 On 32-bit and 64-bit x86 targets, you can use
5187 this function attribute to make GCC generate the ``hot-patching'' function
5188 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
5191 @item regparm (@var{number})
5192 @cindex @code{regparm} function attribute, x86
5193 @cindex functions that are passed arguments in registers on x86-32
5194 On x86-32 targets, the @code{regparm} attribute causes the compiler to
5195 pass arguments number one to @var{number} if they are of integral type
5196 in registers EAX, EDX, and ECX instead of on the stack. Functions that
5197 take a variable number of arguments continue to be passed all of their
5198 arguments on the stack.
5200 Beware that on some ELF systems this attribute is unsuitable for
5201 global functions in shared libraries with lazy binding (which is the
5202 default). Lazy binding sends the first call via resolving code in
5203 the loader, which might assume EAX, EDX and ECX can be clobbered, as
5204 per the standard calling conventions. Solaris 8 is affected by this.
5205 Systems with the GNU C Library version 2.1 or higher
5206 and FreeBSD are believed to be
5207 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
5208 disabled with the linker or the loader if desired, to avoid the
5212 @cindex @code{sseregparm} function attribute, x86
5213 On x86-32 targets with SSE support, the @code{sseregparm} attribute
5214 causes the compiler to pass up to 3 floating-point arguments in
5215 SSE registers instead of on the stack. Functions that take a
5216 variable number of arguments continue to pass all of their
5217 floating-point arguments on the stack.
5219 @item force_align_arg_pointer
5220 @cindex @code{force_align_arg_pointer} function attribute, x86
5221 On x86 targets, the @code{force_align_arg_pointer} attribute may be
5222 applied to individual function definitions, generating an alternate
5223 prologue and epilogue that realigns the run-time stack if necessary.
5224 This supports mixing legacy codes that run with a 4-byte aligned stack
5225 with modern codes that keep a 16-byte stack for SSE compatibility.
5228 @cindex @code{stdcall} function attribute, x86-32
5229 @cindex functions that pop the argument stack on x86-32
5230 On x86-32 targets, the @code{stdcall} attribute causes the compiler to
5231 assume that the called function pops off the stack space used to
5232 pass arguments, unless it takes a variable number of arguments.
5234 @item target (@var{options})
5235 @cindex @code{target} function attribute
5236 As discussed in @ref{Common Function Attributes}, this attribute
5237 allows specification of target-specific compilation options.
5239 On the x86, the following options are allowed:
5243 @cindex @code{target("abm")} function attribute, x86
5244 Enable/disable the generation of the advanced bit instructions.
5248 @cindex @code{target("aes")} function attribute, x86
5249 Enable/disable the generation of the AES instructions.
5252 @cindex @code{target("default")} function attribute, x86
5253 @xref{Function Multiversioning}, where it is used to specify the
5254 default function version.
5258 @cindex @code{target("mmx")} function attribute, x86
5259 Enable/disable the generation of the MMX instructions.
5263 @cindex @code{target("pclmul")} function attribute, x86
5264 Enable/disable the generation of the PCLMUL instructions.
5268 @cindex @code{target("popcnt")} function attribute, x86
5269 Enable/disable the generation of the POPCNT instruction.
5273 @cindex @code{target("sse")} function attribute, x86
5274 Enable/disable the generation of the SSE instructions.
5278 @cindex @code{target("sse2")} function attribute, x86
5279 Enable/disable the generation of the SSE2 instructions.
5283 @cindex @code{target("sse3")} function attribute, x86
5284 Enable/disable the generation of the SSE3 instructions.
5288 @cindex @code{target("sse4")} function attribute, x86
5289 Enable/disable the generation of the SSE4 instructions (both SSE4.1
5294 @cindex @code{target("sse4.1")} function attribute, x86
5295 Enable/disable the generation of the sse4.1 instructions.
5299 @cindex @code{target("sse4.2")} function attribute, x86
5300 Enable/disable the generation of the sse4.2 instructions.
5304 @cindex @code{target("sse4a")} function attribute, x86
5305 Enable/disable the generation of the SSE4A instructions.
5309 @cindex @code{target("fma4")} function attribute, x86
5310 Enable/disable the generation of the FMA4 instructions.
5314 @cindex @code{target("xop")} function attribute, x86
5315 Enable/disable the generation of the XOP instructions.
5319 @cindex @code{target("lwp")} function attribute, x86
5320 Enable/disable the generation of the LWP instructions.
5324 @cindex @code{target("ssse3")} function attribute, x86
5325 Enable/disable the generation of the SSSE3 instructions.
5329 @cindex @code{target("cld")} function attribute, x86
5330 Enable/disable the generation of the CLD before string moves.
5332 @item fancy-math-387
5333 @itemx no-fancy-math-387
5334 @cindex @code{target("fancy-math-387")} function attribute, x86
5335 Enable/disable the generation of the @code{sin}, @code{cos}, and
5336 @code{sqrt} instructions on the 387 floating-point unit.
5339 @itemx no-fused-madd
5340 @cindex @code{target("fused-madd")} function attribute, x86
5341 Enable/disable the generation of the fused multiply/add instructions.
5345 @cindex @code{target("ieee-fp")} function attribute, x86
5346 Enable/disable the generation of floating point that depends on IEEE arithmetic.
5348 @item inline-all-stringops
5349 @itemx no-inline-all-stringops
5350 @cindex @code{target("inline-all-stringops")} function attribute, x86
5351 Enable/disable inlining of string operations.
5353 @item inline-stringops-dynamically
5354 @itemx no-inline-stringops-dynamically
5355 @cindex @code{target("inline-stringops-dynamically")} function attribute, x86
5356 Enable/disable the generation of the inline code to do small string
5357 operations and calling the library routines for large operations.
5359 @item align-stringops
5360 @itemx no-align-stringops
5361 @cindex @code{target("align-stringops")} function attribute, x86
5362 Do/do not align destination of inlined string operations.
5366 @cindex @code{target("recip")} function attribute, x86
5367 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
5368 instructions followed an additional Newton-Raphson step instead of
5369 doing a floating-point division.
5371 @item arch=@var{ARCH}
5372 @cindex @code{target("arch=@var{ARCH}")} function attribute, x86
5373 Specify the architecture to generate code for in compiling the function.
5375 @item tune=@var{TUNE}
5376 @cindex @code{target("tune=@var{TUNE}")} function attribute, x86
5377 Specify the architecture to tune for in compiling the function.
5379 @item fpmath=@var{FPMATH}
5380 @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
5381 Specify which floating-point unit to use. You must specify the
5382 @code{target("fpmath=sse,387")} option as
5383 @code{target("fpmath=sse+387")} because the comma would separate
5387 On the x86, the inliner does not inline a
5388 function that has different target options than the caller, unless the
5389 callee has a subset of the target options of the caller. For example
5390 a function declared with @code{target("sse3")} can inline a function
5391 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
5394 @node Xstormy16 Function Attributes
5395 @subsection Xstormy16 Function Attributes
5397 These function attributes are supported by the Xstormy16 back end:
5401 @cindex @code{interrupt} function attribute, Xstormy16
5402 Use this attribute to indicate
5403 that the specified function is an interrupt handler. The compiler generates
5404 function entry and exit sequences suitable for use in an interrupt handler
5405 when this attribute is present.
5408 @node Variable Attributes
5409 @section Specifying Attributes of Variables
5410 @cindex attribute of variables
5411 @cindex variable attributes
5413 The keyword @code{__attribute__} allows you to specify special
5414 attributes of variables or structure fields. This keyword is followed
5415 by an attribute specification inside double parentheses. Some
5416 attributes are currently defined generically for variables.
5417 Other attributes are defined for variables on particular target
5418 systems. Other attributes are available for functions
5419 (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
5420 enumerators (@pxref{Enumerator Attributes}), and for types
5421 (@pxref{Type Attributes}).
5422 Other front ends might define more attributes
5423 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
5425 @xref{Attribute Syntax}, for details of the exact syntax for using
5429 * Common Variable Attributes::
5430 * AVR Variable Attributes::
5431 * Blackfin Variable Attributes::
5432 * H8/300 Variable Attributes::
5433 * IA-64 Variable Attributes::
5434 * M32R/D Variable Attributes::
5435 * MeP Variable Attributes::
5436 * Microsoft Windows Variable Attributes::
5437 * MSP430 Variable Attributes::
5438 * PowerPC Variable Attributes::
5439 * SPU Variable Attributes::
5440 * x86 Variable Attributes::
5441 * Xstormy16 Variable Attributes::
5444 @node Common Variable Attributes
5445 @subsection Common Variable Attributes
5447 The following attributes are supported on most targets.
5450 @cindex @code{aligned} variable attribute
5451 @item aligned (@var{alignment})
5452 This attribute specifies a minimum alignment for the variable or
5453 structure field, measured in bytes. For example, the declaration:
5456 int x __attribute__ ((aligned (16))) = 0;
5460 causes the compiler to allocate the global variable @code{x} on a
5461 16-byte boundary. On a 68040, this could be used in conjunction with
5462 an @code{asm} expression to access the @code{move16} instruction which
5463 requires 16-byte aligned operands.
5465 You can also specify the alignment of structure fields. For example, to
5466 create a double-word aligned @code{int} pair, you could write:
5469 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
5473 This is an alternative to creating a union with a @code{double} member,
5474 which forces the union to be double-word aligned.
5476 As in the preceding examples, you can explicitly specify the alignment
5477 (in bytes) that you wish the compiler to use for a given variable or
5478 structure field. Alternatively, you can leave out the alignment factor
5479 and just ask the compiler to align a variable or field to the
5480 default alignment for the target architecture you are compiling for.
5481 The default alignment is sufficient for all scalar types, but may not be
5482 enough for all vector types on a target that supports vector operations.
5483 The default alignment is fixed for a particular target ABI.
5485 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
5486 which is the largest alignment ever used for any data type on the
5487 target machine you are compiling for. For example, you could write:
5490 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
5493 The compiler automatically sets the alignment for the declared
5494 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
5495 often make copy operations more efficient, because the compiler can
5496 use whatever instructions copy the biggest chunks of memory when
5497 performing copies to or from the variables or fields that you have
5498 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
5499 may change depending on command-line options.
5501 When used on a struct, or struct member, the @code{aligned} attribute can
5502 only increase the alignment; in order to decrease it, the @code{packed}
5503 attribute must be specified as well. When used as part of a typedef, the
5504 @code{aligned} attribute can both increase and decrease alignment, and
5505 specifying the @code{packed} attribute generates a warning.
5507 Note that the effectiveness of @code{aligned} attributes may be limited
5508 by inherent limitations in your linker. On many systems, the linker is
5509 only able to arrange for variables to be aligned up to a certain maximum
5510 alignment. (For some linkers, the maximum supported alignment may
5511 be very very small.) If your linker is only able to align variables
5512 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
5513 in an @code{__attribute__} still only provides you with 8-byte
5514 alignment. See your linker documentation for further information.
5516 The @code{aligned} attribute can also be used for functions
5517 (@pxref{Common Function Attributes}.)
5519 @item cleanup (@var{cleanup_function})
5520 @cindex @code{cleanup} variable attribute
5521 The @code{cleanup} attribute runs a function when the variable goes
5522 out of scope. This attribute can only be applied to auto function
5523 scope variables; it may not be applied to parameters or variables
5524 with static storage duration. The function must take one parameter,
5525 a pointer to a type compatible with the variable. The return value
5526 of the function (if any) is ignored.
5528 If @option{-fexceptions} is enabled, then @var{cleanup_function}
5529 is run during the stack unwinding that happens during the
5530 processing of the exception. Note that the @code{cleanup} attribute
5531 does not allow the exception to be caught, only to perform an action.
5532 It is undefined what happens if @var{cleanup_function} does not
5537 @cindex @code{common} variable attribute
5538 @cindex @code{nocommon} variable attribute
5541 The @code{common} attribute requests GCC to place a variable in
5542 ``common'' storage. The @code{nocommon} attribute requests the
5543 opposite---to allocate space for it directly.
5545 These attributes override the default chosen by the
5546 @option{-fno-common} and @option{-fcommon} flags respectively.
5549 @itemx deprecated (@var{msg})
5550 @cindex @code{deprecated} variable attribute
5551 The @code{deprecated} attribute results in a warning if the variable
5552 is used anywhere in the source file. This is useful when identifying
5553 variables that are expected to be removed in a future version of a
5554 program. The warning also includes the location of the declaration
5555 of the deprecated variable, to enable users to easily find further
5556 information about why the variable is deprecated, or what they should
5557 do instead. Note that the warning only occurs for uses:
5560 extern int old_var __attribute__ ((deprecated));
5562 int new_fn () @{ return old_var; @}
5566 results in a warning on line 3 but not line 2. The optional @var{msg}
5567 argument, which must be a string, is printed in the warning if
5570 The @code{deprecated} attribute can also be used for functions and
5571 types (@pxref{Common Function Attributes},
5572 @pxref{Common Type Attributes}).
5574 @item mode (@var{mode})
5575 @cindex @code{mode} variable attribute
5576 This attribute specifies the data type for the declaration---whichever
5577 type corresponds to the mode @var{mode}. This in effect lets you
5578 request an integer or floating-point type according to its width.
5580 You may also specify a mode of @code{byte} or @code{__byte__} to
5581 indicate the mode corresponding to a one-byte integer, @code{word} or
5582 @code{__word__} for the mode of a one-word integer, and @code{pointer}
5583 or @code{__pointer__} for the mode used to represent pointers.
5586 @cindex @code{packed} variable attribute
5587 The @code{packed} attribute specifies that a variable or structure field
5588 should have the smallest possible alignment---one byte for a variable,
5589 and one bit for a field, unless you specify a larger value with the
5590 @code{aligned} attribute.
5592 Here is a structure in which the field @code{x} is packed, so that it
5593 immediately follows @code{a}:
5599 int x[2] __attribute__ ((packed));
5603 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
5604 @code{packed} attribute on bit-fields of type @code{char}. This has
5605 been fixed in GCC 4.4 but the change can lead to differences in the
5606 structure layout. See the documentation of
5607 @option{-Wpacked-bitfield-compat} for more information.
5609 @item section ("@var{section-name}")
5610 @cindex @code{section} variable attribute
5611 Normally, the compiler places the objects it generates in sections like
5612 @code{data} and @code{bss}. Sometimes, however, you need additional sections,
5613 or you need certain particular variables to appear in special sections,
5614 for example to map to special hardware. The @code{section}
5615 attribute specifies that a variable (or function) lives in a particular
5616 section. For example, this small program uses several specific section names:
5619 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
5620 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
5621 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
5622 int init_data __attribute__ ((section ("INITDATA")));
5626 /* @r{Initialize stack pointer} */
5627 init_sp (stack + sizeof (stack));
5629 /* @r{Initialize initialized data} */
5630 memcpy (&init_data, &data, &edata - &data);
5632 /* @r{Turn on the serial ports} */
5639 Use the @code{section} attribute with
5640 @emph{global} variables and not @emph{local} variables,
5641 as shown in the example.
5643 You may use the @code{section} attribute with initialized or
5644 uninitialized global variables but the linker requires
5645 each object be defined once, with the exception that uninitialized
5646 variables tentatively go in the @code{common} (or @code{bss}) section
5647 and can be multiply ``defined''. Using the @code{section} attribute
5648 changes what section the variable goes into and may cause the
5649 linker to issue an error if an uninitialized variable has multiple
5650 definitions. You can force a variable to be initialized with the
5651 @option{-fno-common} flag or the @code{nocommon} attribute.
5653 Some file formats do not support arbitrary sections so the @code{section}
5654 attribute is not available on all platforms.
5655 If you need to map the entire contents of a module to a particular
5656 section, consider using the facilities of the linker instead.
5658 @item tls_model ("@var{tls_model}")
5659 @cindex @code{tls_model} variable attribute
5660 The @code{tls_model} attribute sets thread-local storage model
5661 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
5662 overriding @option{-ftls-model=} command-line switch on a per-variable
5664 The @var{tls_model} argument should be one of @code{global-dynamic},
5665 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
5667 Not all targets support this attribute.
5670 @cindex @code{unused} variable attribute
5671 This attribute, attached to a variable, means that the variable is meant
5672 to be possibly unused. GCC does not produce a warning for this
5676 @cindex @code{used} variable attribute
5677 This attribute, attached to a variable with static storage, means that
5678 the variable must be emitted even if it appears that the variable is not
5681 When applied to a static data member of a C++ class template, the
5682 attribute also means that the member is instantiated if the
5683 class itself is instantiated.
5685 @item vector_size (@var{bytes})
5686 @cindex @code{vector_size} variable attribute
5687 This attribute specifies the vector size for the variable, measured in
5688 bytes. For example, the declaration:
5691 int foo __attribute__ ((vector_size (16)));
5695 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
5696 divided into @code{int} sized units. Assuming a 32-bit int (a vector of
5697 4 units of 4 bytes), the corresponding mode of @code{foo} is V4SI@.
5699 This attribute is only applicable to integral and float scalars,
5700 although arrays, pointers, and function return values are allowed in
5701 conjunction with this construct.
5703 Aggregates with this attribute are invalid, even if they are of the same
5704 size as a corresponding scalar. For example, the declaration:
5707 struct S @{ int a; @};
5708 struct S __attribute__ ((vector_size (16))) foo;
5712 is invalid even if the size of the structure is the same as the size of
5715 @item visibility ("@var{visibility_type}")
5716 @cindex @code{visibility} variable attribute
5717 This attribute affects the linkage of the declaration to which it is attached.
5718 The @code{visibility} attribute is described in
5719 @ref{Common Function Attributes}.
5722 @cindex @code{weak} variable attribute
5723 The @code{weak} attribute is described in
5724 @ref{Common Function Attributes}.
5728 @node AVR Variable Attributes
5729 @subsection AVR Variable Attributes
5733 @cindex @code{progmem} variable attribute, AVR
5734 The @code{progmem} attribute is used on the AVR to place read-only
5735 data in the non-volatile program memory (flash). The @code{progmem}
5736 attribute accomplishes this by putting respective variables into a
5737 section whose name starts with @code{.progmem}.
5739 This attribute works similar to the @code{section} attribute
5740 but adds additional checking. Notice that just like the
5741 @code{section} attribute, @code{progmem} affects the location
5742 of the data but not how this data is accessed.
5744 In order to read data located with the @code{progmem} attribute
5745 (inline) assembler must be used.
5747 /* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */
5748 #include <avr/pgmspace.h>
5750 /* Locate var in flash memory */
5751 const int var[2] PROGMEM = @{ 1, 2 @};
5753 int read_var (int i)
5755 /* Access var[] by accessor macro from avr/pgmspace.h */
5756 return (int) pgm_read_word (& var[i]);
5760 AVR is a Harvard architecture processor and data and read-only data
5761 normally resides in the data memory (RAM).
5763 See also the @ref{AVR Named Address Spaces} section for
5764 an alternate way to locate and access data in flash memory.
5767 @itemx io (@var{addr})
5768 @cindex @code{io} variable attribute, AVR
5769 Variables with the @code{io} attribute are used to address
5770 memory-mapped peripherals in the io address range.
5771 If an address is specified, the variable
5772 is assigned that address, and the value is interpreted as an
5773 address in the data address space.
5777 volatile int porta __attribute__((io (0x22)));
5780 The address specified in the address in the data address range.
5782 Otherwise, the variable it is not assigned an address, but the
5783 compiler will still use in/out instructions where applicable,
5784 assuming some other module assigns an address in the io address range.
5788 extern volatile int porta __attribute__((io));
5792 @itemx io_low (@var{addr})
5793 @cindex @code{io_low} variable attribute, AVR
5794 This is like the @code{io} attribute, but additionally it informs the
5795 compiler that the object lies in the lower half of the I/O area,
5796 allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
5800 @itemx address (@var{addr})
5801 @cindex @code{address} variable attribute, AVR
5802 Variables with the @code{address} attribute are used to address
5803 memory-mapped peripherals that may lie outside the io address range.
5806 volatile int porta __attribute__((address (0x600)));
5811 @node Blackfin Variable Attributes
5812 @subsection Blackfin Variable Attributes
5814 Three attributes are currently defined for the Blackfin.
5820 @cindex @code{l1_data} variable attribute, Blackfin
5821 @cindex @code{l1_data_A} variable attribute, Blackfin
5822 @cindex @code{l1_data_B} variable attribute, Blackfin
5823 Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
5824 Variables with @code{l1_data} attribute are put into the specific section
5825 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
5826 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
5827 attribute are put into the specific section named @code{.l1.data.B}.
5830 @cindex @code{l2} variable attribute, Blackfin
5831 Use this attribute on the Blackfin to place the variable into L2 SRAM.
5832 Variables with @code{l2} attribute are put into the specific section
5833 named @code{.l2.data}.
5836 @node H8/300 Variable Attributes
5837 @subsection H8/300 Variable Attributes
5839 These variable attributes are available for H8/300 targets:
5843 @cindex @code{eightbit_data} variable attribute, H8/300
5844 @cindex eight-bit data on the H8/300, H8/300H, and H8S
5845 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
5846 variable should be placed into the eight-bit data section.
5847 The compiler generates more efficient code for certain operations
5848 on data in the eight-bit data area. Note the eight-bit data area is limited to
5851 You must use GAS and GLD from GNU binutils version 2.7 or later for
5852 this attribute to work correctly.
5855 @cindex @code{tiny_data} variable attribute, H8/300
5856 @cindex tiny data section on the H8/300H and H8S
5857 Use this attribute on the H8/300H and H8S to indicate that the specified
5858 variable should be placed into the tiny data section.
5859 The compiler generates more efficient code for loads and stores
5860 on data in the tiny data section. Note the tiny data area is limited to
5861 slightly under 32KB of data.
5865 @node IA-64 Variable Attributes
5866 @subsection IA-64 Variable Attributes
5868 The IA-64 back end supports the following variable attribute:
5871 @item model (@var{model-name})
5872 @cindex @code{model} variable attribute, IA-64
5874 On IA-64, use this attribute to set the addressability of an object.
5875 At present, the only supported identifier for @var{model-name} is
5876 @code{small}, indicating addressability via ``small'' (22-bit)
5877 addresses (so that their addresses can be loaded with the @code{addl}
5878 instruction). Caveat: such addressing is by definition not position
5879 independent and hence this attribute must not be used for objects
5880 defined by shared libraries.
5884 @node M32R/D Variable Attributes
5885 @subsection M32R/D Variable Attributes
5887 One attribute is currently defined for the M32R/D@.
5890 @item model (@var{model-name})
5891 @cindex @code{model-name} variable attribute, M32R/D
5892 @cindex variable addressability on the M32R/D
5893 Use this attribute on the M32R/D to set the addressability of an object.
5894 The identifier @var{model-name} is one of @code{small}, @code{medium},
5895 or @code{large}, representing each of the code models.
5897 Small model objects live in the lower 16MB of memory (so that their
5898 addresses can be loaded with the @code{ld24} instruction).
5900 Medium and large model objects may live anywhere in the 32-bit address space
5901 (the compiler generates @code{seth/add3} instructions to load their
5905 @node MeP Variable Attributes
5906 @subsection MeP Variable Attributes
5908 The MeP target has a number of addressing modes and busses. The
5909 @code{near} space spans the standard memory space's first 16 megabytes
5910 (24 bits). The @code{far} space spans the entire 32-bit memory space.
5911 The @code{based} space is a 128-byte region in the memory space that
5912 is addressed relative to the @code{$tp} register. The @code{tiny}
5913 space is a 65536-byte region relative to the @code{$gp} register. In
5914 addition to these memory regions, the MeP target has a separate 16-bit
5915 control bus which is specified with @code{cb} attributes.
5920 @cindex @code{based} variable attribute, MeP
5921 Any variable with the @code{based} attribute is assigned to the
5922 @code{.based} section, and is accessed with relative to the
5923 @code{$tp} register.
5926 @cindex @code{tiny} variable attribute, MeP
5927 Likewise, the @code{tiny} attribute assigned variables to the
5928 @code{.tiny} section, relative to the @code{$gp} register.
5931 @cindex @code{near} variable attribute, MeP
5932 Variables with the @code{near} attribute are assumed to have addresses
5933 that fit in a 24-bit addressing mode. This is the default for large
5934 variables (@code{-mtiny=4} is the default) but this attribute can
5935 override @code{-mtiny=} for small variables, or override @code{-ml}.
5938 @cindex @code{far} variable attribute, MeP
5939 Variables with the @code{far} attribute are addressed using a full
5940 32-bit address. Since this covers the entire memory space, this
5941 allows modules to make no assumptions about where variables might be
5945 @cindex @code{io} variable attribute, MeP
5946 @itemx io (@var{addr})
5947 Variables with the @code{io} attribute are used to address
5948 memory-mapped peripherals. If an address is specified, the variable
5949 is assigned that address, else it is not assigned an address (it is
5950 assumed some other module assigns an address). Example:
5953 int timer_count __attribute__((io(0x123)));
5957 @itemx cb (@var{addr})
5958 @cindex @code{cb} variable attribute, MeP
5959 Variables with the @code{cb} attribute are used to access the control
5960 bus, using special instructions. @code{addr} indicates the control bus
5964 int cpu_clock __attribute__((cb(0x123)));
5969 @node Microsoft Windows Variable Attributes
5970 @subsection Microsoft Windows Variable Attributes
5972 You can use these attributes on Microsoft Windows targets.
5973 @ref{x86 Variable Attributes} for additional Windows compatibility
5974 attributes available on all x86 targets.
5979 @cindex @code{dllimport} variable attribute
5980 @cindex @code{dllexport} variable attribute
5981 The @code{dllimport} and @code{dllexport} attributes are described in
5982 @ref{Microsoft Windows Function Attributes}.
5985 @cindex @code{selectany} variable attribute
5986 The @code{selectany} attribute causes an initialized global variable to
5987 have link-once semantics. When multiple definitions of the variable are
5988 encountered by the linker, the first is selected and the remainder are
5989 discarded. Following usage by the Microsoft compiler, the linker is told
5990 @emph{not} to warn about size or content differences of the multiple
5993 Although the primary usage of this attribute is for POD types, the
5994 attribute can also be applied to global C++ objects that are initialized
5995 by a constructor. In this case, the static initialization and destruction
5996 code for the object is emitted in each translation defining the object,
5997 but the calls to the constructor and destructor are protected by a
5998 link-once guard variable.
6000 The @code{selectany} attribute is only available on Microsoft Windows
6001 targets. You can use @code{__declspec (selectany)} as a synonym for
6002 @code{__attribute__ ((selectany))} for compatibility with other
6006 @cindex @code{shared} variable attribute
6007 On Microsoft Windows, in addition to putting variable definitions in a named
6008 section, the section can also be shared among all running copies of an
6009 executable or DLL@. For example, this small program defines shared data
6010 by putting it in a named section @code{shared} and marking the section
6014 int foo __attribute__((section ("shared"), shared)) = 0;
6019 /* @r{Read and write foo. All running
6020 copies see the same value.} */
6026 You may only use the @code{shared} attribute along with @code{section}
6027 attribute with a fully-initialized global definition because of the way
6028 linkers work. See @code{section} attribute for more information.
6030 The @code{shared} attribute is only available on Microsoft Windows@.
6034 @node MSP430 Variable Attributes
6035 @subsection MSP430 Variable Attributes
6039 @cindex @code{noinit} variable attribute, MSP430
6040 Any data with the @code{noinit} attribute will not be initialised by
6041 the C runtime startup code, or the program loader. Not initialising
6042 data in this way can reduce program startup times.
6045 @cindex @code{persistent} variable attribute, MSP430
6046 Any variable with the @code{persistent} attribute will not be
6047 initialised by the C runtime startup code. Instead its value will be
6048 set once, when the application is loaded, and then never initialised
6049 again, even if the processor is reset or the program restarts.
6050 Persistent data is intended to be placed into FLASH RAM, where its
6051 value will be retained across resets. The linker script being used to
6052 create the application should ensure that persistent data is correctly
6058 @cindex @code{lower} variable attribute, MSP430
6059 @cindex @code{upper} variable attribute, MSP430
6060 @cindex @code{either} variable attribute, MSP430
6061 These attributes are the same as the MSP430 function attributes of the
6062 same name (@pxref{MSP430 Function Attributes}).
6063 These attributes can be applied to both functions and variables.
6066 @node PowerPC Variable Attributes
6067 @subsection PowerPC Variable Attributes
6069 Three attributes currently are defined for PowerPC configurations:
6070 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
6072 @cindex @code{ms_struct} variable attribute, PowerPC
6073 @cindex @code{gcc_struct} variable attribute, PowerPC
6074 For full documentation of the struct attributes please see the
6075 documentation in @ref{x86 Variable Attributes}.
6077 @cindex @code{altivec} variable attribute, PowerPC
6078 For documentation of @code{altivec} attribute please see the
6079 documentation in @ref{PowerPC Type Attributes}.
6081 @node SPU Variable Attributes
6082 @subsection SPU Variable Attributes
6084 @cindex @code{spu_vector} variable attribute, SPU
6085 The SPU supports the @code{spu_vector} attribute for variables. For
6086 documentation of this attribute please see the documentation in
6087 @ref{SPU Type Attributes}.
6089 @node x86 Variable Attributes
6090 @subsection x86 Variable Attributes
6092 Two attributes are currently defined for x86 configurations:
6093 @code{ms_struct} and @code{gcc_struct}.
6098 @cindex @code{ms_struct} variable attribute, x86
6099 @cindex @code{gcc_struct} variable attribute, x86
6101 If @code{packed} is used on a structure, or if bit-fields are used,
6102 it may be that the Microsoft ABI lays out the structure differently
6103 than the way GCC normally does. Particularly when moving packed
6104 data between functions compiled with GCC and the native Microsoft compiler
6105 (either via function call or as data in a file), it may be necessary to access
6108 The @code{ms_struct} and @code{gcc_struct} attributes correspond
6109 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
6110 command-line options, respectively;
6111 see @ref{x86 Options}, for details of how structure layout is affected.
6112 @xref{x86 Type Attributes}, for information about the corresponding
6113 attributes on types.
6117 @node Xstormy16 Variable Attributes
6118 @subsection Xstormy16 Variable Attributes
6120 One attribute is currently defined for xstormy16 configurations:
6125 @cindex @code{below100} variable attribute, Xstormy16
6127 If a variable has the @code{below100} attribute (@code{BELOW100} is
6128 allowed also), GCC places the variable in the first 0x100 bytes of
6129 memory and use special opcodes to access it. Such variables are
6130 placed in either the @code{.bss_below100} section or the
6131 @code{.data_below100} section.
6135 @node Type Attributes
6136 @section Specifying Attributes of Types
6137 @cindex attribute of types
6138 @cindex type attributes
6140 The keyword @code{__attribute__} allows you to specify special
6141 attributes of types. Some type attributes apply only to @code{struct}
6142 and @code{union} types, while others can apply to any type defined
6143 via a @code{typedef} declaration. Other attributes are defined for
6144 functions (@pxref{Function Attributes}), labels (@pxref{Label
6145 Attributes}), enumerators (@pxref{Enumerator Attributes}), and for
6146 variables (@pxref{Variable Attributes}).
6148 The @code{__attribute__} keyword is followed by an attribute specification
6149 inside double parentheses.
6151 You may specify type attributes in an enum, struct or union type
6152 declaration or definition by placing them immediately after the
6153 @code{struct}, @code{union} or @code{enum} keyword. A less preferred
6154 syntax is to place them just past the closing curly brace of the
6157 You can also include type attributes in a @code{typedef} declaration.
6158 @xref{Attribute Syntax}, for details of the exact syntax for using
6162 * Common Type Attributes::
6163 * ARM Type Attributes::
6164 * MeP Type Attributes::
6165 * PowerPC Type Attributes::
6166 * SPU Type Attributes::
6167 * x86 Type Attributes::
6170 @node Common Type Attributes
6171 @subsection Common Type Attributes
6173 The following type attributes are supported on most targets.
6176 @cindex @code{aligned} type attribute
6177 @item aligned (@var{alignment})
6178 This attribute specifies a minimum alignment (in bytes) for variables
6179 of the specified type. For example, the declarations:
6182 struct S @{ short f[3]; @} __attribute__ ((aligned (8)));
6183 typedef int more_aligned_int __attribute__ ((aligned (8)));
6187 force the compiler to ensure (as far as it can) that each variable whose
6188 type is @code{struct S} or @code{more_aligned_int} is allocated and
6189 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
6190 variables of type @code{struct S} aligned to 8-byte boundaries allows
6191 the compiler to use the @code{ldd} and @code{std} (doubleword load and
6192 store) instructions when copying one variable of type @code{struct S} to
6193 another, thus improving run-time efficiency.
6195 Note that the alignment of any given @code{struct} or @code{union} type
6196 is required by the ISO C standard to be at least a perfect multiple of
6197 the lowest common multiple of the alignments of all of the members of
6198 the @code{struct} or @code{union} in question. This means that you @emph{can}
6199 effectively adjust the alignment of a @code{struct} or @code{union}
6200 type by attaching an @code{aligned} attribute to any one of the members
6201 of such a type, but the notation illustrated in the example above is a
6202 more obvious, intuitive, and readable way to request the compiler to
6203 adjust the alignment of an entire @code{struct} or @code{union} type.
6205 As in the preceding example, you can explicitly specify the alignment
6206 (in bytes) that you wish the compiler to use for a given @code{struct}
6207 or @code{union} type. Alternatively, you can leave out the alignment factor
6208 and just ask the compiler to align a type to the maximum
6209 useful alignment for the target machine you are compiling for. For
6210 example, you could write:
6213 struct S @{ short f[3]; @} __attribute__ ((aligned));
6216 Whenever you leave out the alignment factor in an @code{aligned}
6217 attribute specification, the compiler automatically sets the alignment
6218 for the type to the largest alignment that is ever used for any data
6219 type on the target machine you are compiling for. Doing this can often
6220 make copy operations more efficient, because the compiler can use
6221 whatever instructions copy the biggest chunks of memory when performing
6222 copies to or from the variables that have types that you have aligned
6225 In the example above, if the size of each @code{short} is 2 bytes, then
6226 the size of the entire @code{struct S} type is 6 bytes. The smallest
6227 power of two that is greater than or equal to that is 8, so the
6228 compiler sets the alignment for the entire @code{struct S} type to 8
6231 Note that although you can ask the compiler to select a time-efficient
6232 alignment for a given type and then declare only individual stand-alone
6233 objects of that type, the compiler's ability to select a time-efficient
6234 alignment is primarily useful only when you plan to create arrays of
6235 variables having the relevant (efficiently aligned) type. If you
6236 declare or use arrays of variables of an efficiently-aligned type, then
6237 it is likely that your program also does pointer arithmetic (or
6238 subscripting, which amounts to the same thing) on pointers to the
6239 relevant type, and the code that the compiler generates for these
6240 pointer arithmetic operations is often more efficient for
6241 efficiently-aligned types than for other types.
6243 The @code{aligned} attribute can only increase the alignment; but you
6244 can decrease it by specifying @code{packed} as well. See below.
6246 Note that the effectiveness of @code{aligned} attributes may be limited
6247 by inherent limitations in your linker. On many systems, the linker is
6248 only able to arrange for variables to be aligned up to a certain maximum
6249 alignment. (For some linkers, the maximum supported alignment may
6250 be very very small.) If your linker is only able to align variables
6251 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
6252 in an @code{__attribute__} still only provides you with 8-byte
6253 alignment. See your linker documentation for further information.
6255 @opindex fshort-enums
6256 Specifying this attribute for @code{struct} and @code{union} types is
6257 equivalent to specifying the @code{packed} attribute on each of the
6258 structure or union members. Specifying the @option{-fshort-enums}
6259 flag on the line is equivalent to specifying the @code{packed}
6260 attribute on all @code{enum} definitions.
6262 In the following example @code{struct my_packed_struct}'s members are
6263 packed closely together, but the internal layout of its @code{s} member
6264 is not packed---to do that, @code{struct my_unpacked_struct} needs to
6268 struct my_unpacked_struct
6274 struct __attribute__ ((__packed__)) my_packed_struct
6278 struct my_unpacked_struct s;
6282 You may only specify this attribute on the definition of an @code{enum},
6283 @code{struct} or @code{union}, not on a @code{typedef} that does not
6284 also define the enumerated type, structure or union.
6286 @item bnd_variable_size
6287 @cindex @code{bnd_variable_size} type attribute
6288 @cindex Pointer Bounds Checker attributes
6289 When applied to a structure field, this attribute tells Pointer
6290 Bounds Checker that the size of this field should not be computed
6291 using static type information. It may be used to mark variably-sized
6292 static array fields placed at the end of a structure.
6300 S *p = (S *)malloc (sizeof(S) + 100);
6301 p->data[10] = 0; //Bounds violation
6305 By using an attribute for the field we may avoid unwanted bound
6312 char data[1] __attribute__((bnd_variable_size));
6314 S *p = (S *)malloc (sizeof(S) + 100);
6315 p->data[10] = 0; //OK
6319 @itemx deprecated (@var{msg})
6320 @cindex @code{deprecated} type attribute
6321 The @code{deprecated} attribute results in a warning if the type
6322 is used anywhere in the source file. This is useful when identifying
6323 types that are expected to be removed in a future version of a program.
6324 If possible, the warning also includes the location of the declaration
6325 of the deprecated type, to enable users to easily find further
6326 information about why the type is deprecated, or what they should do
6327 instead. Note that the warnings only occur for uses and then only
6328 if the type is being applied to an identifier that itself is not being
6329 declared as deprecated.
6332 typedef int T1 __attribute__ ((deprecated));
6336 typedef T1 T3 __attribute__ ((deprecated));
6337 T3 z __attribute__ ((deprecated));
6341 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
6342 warning is issued for line 4 because T2 is not explicitly
6343 deprecated. Line 5 has no warning because T3 is explicitly
6344 deprecated. Similarly for line 6. The optional @var{msg}
6345 argument, which must be a string, is printed in the warning if
6348 The @code{deprecated} attribute can also be used for functions and
6349 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
6351 @item designated_init
6352 @cindex @code{designated_init} type attribute
6353 This attribute may only be applied to structure types. It indicates
6354 that any initialization of an object of this type must use designated
6355 initializers rather than positional initializers. The intent of this
6356 attribute is to allow the programmer to indicate that a structure's
6357 layout may change, and that therefore relying on positional
6358 initialization will result in future breakage.
6360 GCC emits warnings based on this attribute by default; use
6361 @option{-Wno-designated-init} to suppress them.
6364 @cindex @code{may_alias} type attribute
6365 Accesses through pointers to types with this attribute are not subject
6366 to type-based alias analysis, but are instead assumed to be able to alias
6367 any other type of objects.
6368 In the context of section 6.5 paragraph 7 of the C99 standard,
6369 an lvalue expression
6370 dereferencing such a pointer is treated like having a character type.
6371 See @option{-fstrict-aliasing} for more information on aliasing issues.
6372 This extension exists to support some vector APIs, in which pointers to
6373 one vector type are permitted to alias pointers to a different vector type.
6375 Note that an object of a type with this attribute does not have any
6381 typedef short __attribute__((__may_alias__)) short_a;
6387 short_a *b = (short_a *) &a;
6391 if (a == 0x12345678)
6399 If you replaced @code{short_a} with @code{short} in the variable
6400 declaration, the above program would abort when compiled with
6401 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
6405 @cindex @code{packed} type attribute
6406 This attribute, attached to @code{struct} or @code{union} type
6407 definition, specifies that each member (other than zero-width bit-fields)
6408 of the structure or union is placed to minimize the memory required. When
6409 attached to an @code{enum} definition, it indicates that the smallest
6410 integral type should be used.
6412 @item scalar_storage_order ("@var{endianness}")
6413 @cindex @code{scalar_storage_order} type attribute
6414 When attached to a @code{union} or a @code{struct}, this attribute sets
6415 the storage order, aka endianness, of the scalar fields of the type, as
6416 well as the array fields whose component is scalar. The supported
6417 endianness are @code{big-endian} and @code{little-endian}. The attribute
6418 has no effects on fields which are themselves a @code{union}, a @code{struct}
6419 or an array whose component is a @code{union} or a @code{struct}, and it is
6420 possible to have fields with a different scalar storage order than the
6423 This attribute is supported only for targets that use a uniform default
6424 scalar storage order (fortunately, most of them), i.e. targets that store
6425 the scalars either all in big-endian or all in little-endian.
6427 Additional restrictions are enforced for types with the reverse scalar
6428 storage order with regard to the scalar storage order of the target:
6431 @item Taking the address of a scalar field of a @code{union} or a
6432 @code{struct} with reverse scalar storage order is not permitted and will
6434 @item Taking the address of an array field, whose component is scalar, of
6435 a @code{union} or a @code{struct} with reverse scalar storage order is
6436 permitted but will yield a warning, unless @option{-Wno-scalar-storage-order}
6438 @item Taking the address of a @code{union} or a @code{struct} with reverse
6439 scalar storage order is permitted.
6442 These restrictions exist because the storage order attribute is lost when
6443 the address of a scalar or the address of an array with scalar component
6444 is taken, so storing indirectly through this address will generally not work.
6445 The second case is nevertheless allowed to be able to perform a block copy
6446 from or to the array.
6448 @item transparent_union
6449 @cindex @code{transparent_union} type attribute
6451 This attribute, attached to a @code{union} type definition, indicates
6452 that any function parameter having that union type causes calls to that
6453 function to be treated in a special way.
6455 First, the argument corresponding to a transparent union type can be of
6456 any type in the union; no cast is required. Also, if the union contains
6457 a pointer type, the corresponding argument can be a null pointer
6458 constant or a void pointer expression; and if the union contains a void
6459 pointer type, the corresponding argument can be any pointer expression.
6460 If the union member type is a pointer, qualifiers like @code{const} on
6461 the referenced type must be respected, just as with normal pointer
6464 Second, the argument is passed to the function using the calling
6465 conventions of the first member of the transparent union, not the calling
6466 conventions of the union itself. All members of the union must have the
6467 same machine representation; this is necessary for this argument passing
6470 Transparent unions are designed for library functions that have multiple
6471 interfaces for compatibility reasons. For example, suppose the
6472 @code{wait} function must accept either a value of type @code{int *} to
6473 comply with POSIX, or a value of type @code{union wait *} to comply with
6474 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
6475 @code{wait} would accept both kinds of arguments, but it would also
6476 accept any other pointer type and this would make argument type checking
6477 less useful. Instead, @code{<sys/wait.h>} might define the interface
6481 typedef union __attribute__ ((__transparent_union__))
6485 @} wait_status_ptr_t;
6487 pid_t wait (wait_status_ptr_t);
6491 This interface allows either @code{int *} or @code{union wait *}
6492 arguments to be passed, using the @code{int *} calling convention.
6493 The program can call @code{wait} with arguments of either type:
6496 int w1 () @{ int w; return wait (&w); @}
6497 int w2 () @{ union wait w; return wait (&w); @}
6501 With this interface, @code{wait}'s implementation might look like this:
6504 pid_t wait (wait_status_ptr_t p)
6506 return waitpid (-1, p.__ip, 0);
6511 @cindex @code{unused} type attribute
6512 When attached to a type (including a @code{union} or a @code{struct}),
6513 this attribute means that variables of that type are meant to appear
6514 possibly unused. GCC does not produce a warning for any variables of
6515 that type, even if the variable appears to do nothing. This is often
6516 the case with lock or thread classes, which are usually defined and then
6517 not referenced, but contain constructors and destructors that have
6518 nontrivial bookkeeping functions.
6521 @cindex @code{visibility} type attribute
6522 In C++, attribute visibility (@pxref{Function Attributes}) can also be
6523 applied to class, struct, union and enum types. Unlike other type
6524 attributes, the attribute must appear between the initial keyword and
6525 the name of the type; it cannot appear after the body of the type.
6527 Note that the type visibility is applied to vague linkage entities
6528 associated with the class (vtable, typeinfo node, etc.). In
6529 particular, if a class is thrown as an exception in one shared object
6530 and caught in another, the class must have default visibility.
6531 Otherwise the two shared objects are unable to use the same
6532 typeinfo node and exception handling will break.
6536 To specify multiple attributes, separate them by commas within the
6537 double parentheses: for example, @samp{__attribute__ ((aligned (16),
6540 @node ARM Type Attributes
6541 @subsection ARM Type Attributes
6543 @cindex @code{notshared} type attribute, ARM
6544 On those ARM targets that support @code{dllimport} (such as Symbian
6545 OS), you can use the @code{notshared} attribute to indicate that the
6546 virtual table and other similar data for a class should not be
6547 exported from a DLL@. For example:
6550 class __declspec(notshared) C @{
6552 __declspec(dllimport) C();
6556 __declspec(dllexport)
6561 In this code, @code{C::C} is exported from the current DLL, but the
6562 virtual table for @code{C} is not exported. (You can use
6563 @code{__attribute__} instead of @code{__declspec} if you prefer, but
6564 most Symbian OS code uses @code{__declspec}.)
6566 @node MeP Type Attributes
6567 @subsection MeP Type Attributes
6569 @cindex @code{based} type attribute, MeP
6570 @cindex @code{tiny} type attribute, MeP
6571 @cindex @code{near} type attribute, MeP
6572 @cindex @code{far} type attribute, MeP
6573 Many of the MeP variable attributes may be applied to types as well.
6574 Specifically, the @code{based}, @code{tiny}, @code{near}, and
6575 @code{far} attributes may be applied to either. The @code{io} and
6576 @code{cb} attributes may not be applied to types.
6578 @node PowerPC Type Attributes
6579 @subsection PowerPC Type Attributes
6581 Three attributes currently are defined for PowerPC configurations:
6582 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
6584 @cindex @code{ms_struct} type attribute, PowerPC
6585 @cindex @code{gcc_struct} type attribute, PowerPC
6586 For full documentation of the @code{ms_struct} and @code{gcc_struct}
6587 attributes please see the documentation in @ref{x86 Type Attributes}.
6589 @cindex @code{altivec} type attribute, PowerPC
6590 The @code{altivec} attribute allows one to declare AltiVec vector data
6591 types supported by the AltiVec Programming Interface Manual. The
6592 attribute requires an argument to specify one of three vector types:
6593 @code{vector__}, @code{pixel__} (always followed by unsigned short),
6594 and @code{bool__} (always followed by unsigned).
6597 __attribute__((altivec(vector__)))
6598 __attribute__((altivec(pixel__))) unsigned short
6599 __attribute__((altivec(bool__))) unsigned
6602 These attributes mainly are intended to support the @code{__vector},
6603 @code{__pixel}, and @code{__bool} AltiVec keywords.
6605 @node SPU Type Attributes
6606 @subsection SPU Type Attributes
6608 @cindex @code{spu_vector} type attribute, SPU
6609 The SPU supports the @code{spu_vector} attribute for types. This attribute
6610 allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU
6611 Language Extensions Specification. It is intended to support the
6612 @code{__vector} keyword.
6614 @node x86 Type Attributes
6615 @subsection x86 Type Attributes
6617 Two attributes are currently defined for x86 configurations:
6618 @code{ms_struct} and @code{gcc_struct}.
6624 @cindex @code{ms_struct} type attribute, x86
6625 @cindex @code{gcc_struct} type attribute, x86
6627 If @code{packed} is used on a structure, or if bit-fields are used
6628 it may be that the Microsoft ABI packs them differently
6629 than GCC normally packs them. Particularly when moving packed
6630 data between functions compiled with GCC and the native Microsoft compiler
6631 (either via function call or as data in a file), it may be necessary to access
6634 The @code{ms_struct} and @code{gcc_struct} attributes correspond
6635 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
6636 command-line options, respectively;
6637 see @ref{x86 Options}, for details of how structure layout is affected.
6638 @xref{x86 Variable Attributes}, for information about the corresponding
6639 attributes on variables.
6643 @node Label Attributes
6644 @section Label Attributes
6645 @cindex Label Attributes
6647 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
6648 details of the exact syntax for using attributes. Other attributes are
6649 available for functions (@pxref{Function Attributes}), variables
6650 (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
6651 and for types (@pxref{Type Attributes}).
6653 This example uses the @code{cold} label attribute to indicate the
6654 @code{ErrorHandling} branch is unlikely to be taken and that the
6655 @code{ErrorHandling} label is unused:
6659 asm goto ("some asm" : : : : NoError);
6661 /* This branch (the fall-through from the asm) is less commonly used */
6663 __attribute__((cold, unused)); /* Semi-colon is required here */
6668 printf("no error\n");
6674 @cindex @code{unused} label attribute
6675 This feature is intended for program-generated code that may contain
6676 unused labels, but which is compiled with @option{-Wall}. It is
6677 not normally appropriate to use in it human-written code, though it
6678 could be useful in cases where the code that jumps to the label is
6679 contained within an @code{#ifdef} conditional.
6682 @cindex @code{hot} label attribute
6683 The @code{hot} attribute on a label is used to inform the compiler that
6684 the path following the label is more likely than paths that are not so
6685 annotated. This attribute is used in cases where @code{__builtin_expect}
6686 cannot be used, for instance with computed goto or @code{asm goto}.
6689 @cindex @code{cold} label attribute
6690 The @code{cold} attribute on labels is used to inform the compiler that
6691 the path following the label is unlikely to be executed. This attribute
6692 is used in cases where @code{__builtin_expect} cannot be used, for instance
6693 with computed goto or @code{asm goto}.
6697 @node Enumerator Attributes
6698 @section Enumerator Attributes
6699 @cindex Enumerator Attributes
6701 GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for
6702 details of the exact syntax for using attributes. Other attributes are
6703 available for functions (@pxref{Function Attributes}), variables
6704 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}),
6705 and for types (@pxref{Type Attributes}).
6707 This example uses the @code{deprecated} enumerator attribute to indicate the
6708 @code{oldval} enumerator is deprecated:
6712 oldval __attribute__((deprecated)),
6725 @cindex @code{deprecated} enumerator attribute
6726 The @code{deprecated} attribute results in a warning if the enumerator
6727 is used anywhere in the source file. This is useful when identifying
6728 enumerators that are expected to be removed in a future version of a
6729 program. The warning also includes the location of the declaration
6730 of the deprecated enumerator, to enable users to easily find further
6731 information about why the enumerator is deprecated, or what they should
6732 do instead. Note that the warnings only occurs for uses.
6736 @node Attribute Syntax
6737 @section Attribute Syntax
6738 @cindex attribute syntax
6740 This section describes the syntax with which @code{__attribute__} may be
6741 used, and the constructs to which attribute specifiers bind, for the C
6742 language. Some details may vary for C++ and Objective-C@. Because of
6743 infelicities in the grammar for attributes, some forms described here
6744 may not be successfully parsed in all cases.
6746 There are some problems with the semantics of attributes in C++. For
6747 example, there are no manglings for attributes, although they may affect
6748 code generation, so problems may arise when attributed types are used in
6749 conjunction with templates or overloading. Similarly, @code{typeid}
6750 does not distinguish between types with different attributes. Support
6751 for attributes in C++ may be restricted in future to attributes on
6752 declarations only, but not on nested declarators.
6754 @xref{Function Attributes}, for details of the semantics of attributes
6755 applying to functions. @xref{Variable Attributes}, for details of the
6756 semantics of attributes applying to variables. @xref{Type Attributes},
6757 for details of the semantics of attributes applying to structure, union
6758 and enumerated types.
6759 @xref{Label Attributes}, for details of the semantics of attributes
6761 @xref{Enumerator Attributes}, for details of the semantics of attributes
6762 applying to enumerators.
6764 An @dfn{attribute specifier} is of the form
6765 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
6766 is a possibly empty comma-separated sequence of @dfn{attributes}, where
6767 each attribute is one of the following:
6771 Empty. Empty attributes are ignored.
6775 (which may be an identifier such as @code{unused}, or a reserved
6776 word such as @code{const}).
6779 An attribute name followed by a parenthesized list of
6780 parameters for the attribute.
6781 These parameters take one of the following forms:
6785 An identifier. For example, @code{mode} attributes use this form.
6788 An identifier followed by a comma and a non-empty comma-separated list
6789 of expressions. For example, @code{format} attributes use this form.
6792 A possibly empty comma-separated list of expressions. For example,
6793 @code{format_arg} attributes use this form with the list being a single
6794 integer constant expression, and @code{alias} attributes use this form
6795 with the list being a single string constant.
6799 An @dfn{attribute specifier list} is a sequence of one or more attribute
6800 specifiers, not separated by any other tokens.
6802 You may optionally specify attribute names with @samp{__}
6803 preceding and following the name.
6804 This allows you to use them in header files without
6805 being concerned about a possible macro of the same name. For example,
6806 you may use the attribute name @code{__noreturn__} instead of @code{noreturn}.
6809 @subsubheading Label Attributes
6811 In GNU C, an attribute specifier list may appear after the colon following a
6812 label, other than a @code{case} or @code{default} label. GNU C++ only permits
6813 attributes on labels if the attribute specifier is immediately
6814 followed by a semicolon (i.e., the label applies to an empty
6815 statement). If the semicolon is missing, C++ label attributes are
6816 ambiguous, as it is permissible for a declaration, which could begin
6817 with an attribute list, to be labelled in C++. Declarations cannot be
6818 labelled in C90 or C99, so the ambiguity does not arise there.
6820 @subsubheading Enumerator Attributes
6822 In GNU C, an attribute specifier list may appear as part of an enumerator.
6823 The attribute goes after the enumeration constant, before @code{=}, if
6824 present. The optional attribute in the enumerator appertains to the
6825 enumeration constant. It is not possible to place the attribute after
6826 the constant expression, if present.
6828 @subsubheading Type Attributes
6830 An attribute specifier list may appear as part of a @code{struct},
6831 @code{union} or @code{enum} specifier. It may go either immediately
6832 after the @code{struct}, @code{union} or @code{enum} keyword, or after
6833 the closing brace. The former syntax is preferred.
6834 Where attribute specifiers follow the closing brace, they are considered
6835 to relate to the structure, union or enumerated type defined, not to any
6836 enclosing declaration the type specifier appears in, and the type
6837 defined is not complete until after the attribute specifiers.
6838 @c Otherwise, there would be the following problems: a shift/reduce
6839 @c conflict between attributes binding the struct/union/enum and
6840 @c binding to the list of specifiers/qualifiers; and "aligned"
6841 @c attributes could use sizeof for the structure, but the size could be
6842 @c changed later by "packed" attributes.
6845 @subsubheading All other attributes
6847 Otherwise, an attribute specifier appears as part of a declaration,
6848 counting declarations of unnamed parameters and type names, and relates
6849 to that declaration (which may be nested in another declaration, for
6850 example in the case of a parameter declaration), or to a particular declarator
6851 within a declaration. Where an
6852 attribute specifier is applied to a parameter declared as a function or
6853 an array, it should apply to the function or array rather than the
6854 pointer to which the parameter is implicitly converted, but this is not
6855 yet correctly implemented.
6857 Any list of specifiers and qualifiers at the start of a declaration may
6858 contain attribute specifiers, whether or not such a list may in that
6859 context contain storage class specifiers. (Some attributes, however,
6860 are essentially in the nature of storage class specifiers, and only make
6861 sense where storage class specifiers may be used; for example,
6862 @code{section}.) There is one necessary limitation to this syntax: the
6863 first old-style parameter declaration in a function definition cannot
6864 begin with an attribute specifier, because such an attribute applies to
6865 the function instead by syntax described below (which, however, is not
6866 yet implemented in this case). In some other cases, attribute
6867 specifiers are permitted by this grammar but not yet supported by the
6868 compiler. All attribute specifiers in this place relate to the
6869 declaration as a whole. In the obsolescent usage where a type of
6870 @code{int} is implied by the absence of type specifiers, such a list of
6871 specifiers and qualifiers may be an attribute specifier list with no
6872 other specifiers or qualifiers.
6874 At present, the first parameter in a function prototype must have some
6875 type specifier that is not an attribute specifier; this resolves an
6876 ambiguity in the interpretation of @code{void f(int
6877 (__attribute__((foo)) x))}, but is subject to change. At present, if
6878 the parentheses of a function declarator contain only attributes then
6879 those attributes are ignored, rather than yielding an error or warning
6880 or implying a single parameter of type int, but this is subject to
6883 An attribute specifier list may appear immediately before a declarator
6884 (other than the first) in a comma-separated list of declarators in a
6885 declaration of more than one identifier using a single list of
6886 specifiers and qualifiers. Such attribute specifiers apply
6887 only to the identifier before whose declarator they appear. For
6891 __attribute__((noreturn)) void d0 (void),
6892 __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
6897 the @code{noreturn} attribute applies to all the functions
6898 declared; the @code{format} attribute only applies to @code{d1}.
6900 An attribute specifier list may appear immediately before the comma,
6901 @code{=} or semicolon terminating the declaration of an identifier other
6902 than a function definition. Such attribute specifiers apply
6903 to the declared object or function. Where an
6904 assembler name for an object or function is specified (@pxref{Asm
6905 Labels}), the attribute must follow the @code{asm}
6908 An attribute specifier list may, in future, be permitted to appear after
6909 the declarator in a function definition (before any old-style parameter
6910 declarations or the function body).
6912 Attribute specifiers may be mixed with type qualifiers appearing inside
6913 the @code{[]} of a parameter array declarator, in the C99 construct by
6914 which such qualifiers are applied to the pointer to which the array is
6915 implicitly converted. Such attribute specifiers apply to the pointer,
6916 not to the array, but at present this is not implemented and they are
6919 An attribute specifier list may appear at the start of a nested
6920 declarator. At present, there are some limitations in this usage: the
6921 attributes correctly apply to the declarator, but for most individual
6922 attributes the semantics this implies are not implemented.
6923 When attribute specifiers follow the @code{*} of a pointer
6924 declarator, they may be mixed with any type qualifiers present.
6925 The following describes the formal semantics of this syntax. It makes the
6926 most sense if you are familiar with the formal specification of
6927 declarators in the ISO C standard.
6929 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
6930 D1}, where @code{T} contains declaration specifiers that specify a type
6931 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
6932 contains an identifier @var{ident}. The type specified for @var{ident}
6933 for derived declarators whose type does not include an attribute
6934 specifier is as in the ISO C standard.
6936 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
6937 and the declaration @code{T D} specifies the type
6938 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
6939 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
6940 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
6942 If @code{D1} has the form @code{*
6943 @var{type-qualifier-and-attribute-specifier-list} D}, and the
6944 declaration @code{T D} specifies the type
6945 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
6946 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
6947 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
6953 void (__attribute__((noreturn)) ****f) (void);
6957 specifies the type ``pointer to pointer to pointer to pointer to
6958 non-returning function returning @code{void}''. As another example,
6961 char *__attribute__((aligned(8))) *f;
6965 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
6966 Note again that this does not work with most attributes; for example,
6967 the usage of @samp{aligned} and @samp{noreturn} attributes given above
6968 is not yet supported.
6970 For compatibility with existing code written for compiler versions that
6971 did not implement attributes on nested declarators, some laxity is
6972 allowed in the placing of attributes. If an attribute that only applies
6973 to types is applied to a declaration, it is treated as applying to
6974 the type of that declaration. If an attribute that only applies to
6975 declarations is applied to the type of a declaration, it is treated
6976 as applying to that declaration; and, for compatibility with code
6977 placing the attributes immediately before the identifier declared, such
6978 an attribute applied to a function return type is treated as
6979 applying to the function type, and such an attribute applied to an array
6980 element type is treated as applying to the array type. If an
6981 attribute that only applies to function types is applied to a
6982 pointer-to-function type, it is treated as applying to the pointer
6983 target type; if such an attribute is applied to a function return type
6984 that is not a pointer-to-function type, it is treated as applying
6985 to the function type.
6987 @node Function Prototypes
6988 @section Prototypes and Old-Style Function Definitions
6989 @cindex function prototype declarations
6990 @cindex old-style function definitions
6991 @cindex promotion of formal parameters
6993 GNU C extends ISO C to allow a function prototype to override a later
6994 old-style non-prototype definition. Consider the following example:
6997 /* @r{Use prototypes unless the compiler is old-fashioned.} */
7004 /* @r{Prototype function declaration.} */
7005 int isroot P((uid_t));
7007 /* @r{Old-style function definition.} */
7009 isroot (x) /* @r{??? lossage here ???} */
7016 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
7017 not allow this example, because subword arguments in old-style
7018 non-prototype definitions are promoted. Therefore in this example the
7019 function definition's argument is really an @code{int}, which does not
7020 match the prototype argument type of @code{short}.
7022 This restriction of ISO C makes it hard to write code that is portable
7023 to traditional C compilers, because the programmer does not know
7024 whether the @code{uid_t} type is @code{short}, @code{int}, or
7025 @code{long}. Therefore, in cases like these GNU C allows a prototype
7026 to override a later old-style definition. More precisely, in GNU C, a
7027 function prototype argument type overrides the argument type specified
7028 by a later old-style definition if the former type is the same as the
7029 latter type before promotion. Thus in GNU C the above example is
7030 equivalent to the following:
7043 GNU C++ does not support old-style function definitions, so this
7044 extension is irrelevant.
7047 @section C++ Style Comments
7049 @cindex C++ comments
7050 @cindex comments, C++ style
7052 In GNU C, you may use C++ style comments, which start with @samp{//} and
7053 continue until the end of the line. Many other C implementations allow
7054 such comments, and they are included in the 1999 C standard. However,
7055 C++ style comments are not recognized if you specify an @option{-std}
7056 option specifying a version of ISO C before C99, or @option{-ansi}
7057 (equivalent to @option{-std=c90}).
7060 @section Dollar Signs in Identifier Names
7062 @cindex dollar signs in identifier names
7063 @cindex identifier names, dollar signs in
7065 In GNU C, you may normally use dollar signs in identifier names.
7066 This is because many traditional C implementations allow such identifiers.
7067 However, dollar signs in identifiers are not supported on a few target
7068 machines, typically because the target assembler does not allow them.
7070 @node Character Escapes
7071 @section The Character @key{ESC} in Constants
7073 You can use the sequence @samp{\e} in a string or character constant to
7074 stand for the ASCII character @key{ESC}.
7077 @section Inquiring on Alignment of Types or Variables
7079 @cindex type alignment
7080 @cindex variable alignment
7082 The keyword @code{__alignof__} allows you to inquire about how an object
7083 is aligned, or the minimum alignment usually required by a type. Its
7084 syntax is just like @code{sizeof}.
7086 For example, if the target machine requires a @code{double} value to be
7087 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
7088 This is true on many RISC machines. On more traditional machine
7089 designs, @code{__alignof__ (double)} is 4 or even 2.
7091 Some machines never actually require alignment; they allow reference to any
7092 data type even at an odd address. For these machines, @code{__alignof__}
7093 reports the smallest alignment that GCC gives the data type, usually as
7094 mandated by the target ABI.
7096 If the operand of @code{__alignof__} is an lvalue rather than a type,
7097 its value is the required alignment for its type, taking into account
7098 any minimum alignment specified with GCC's @code{__attribute__}
7099 extension (@pxref{Variable Attributes}). For example, after this
7103 struct foo @{ int x; char y; @} foo1;
7107 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
7108 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
7110 It is an error to ask for the alignment of an incomplete type.
7114 @section An Inline Function is As Fast As a Macro
7115 @cindex inline functions
7116 @cindex integrating function code
7118 @cindex macros, inline alternative
7120 By declaring a function inline, you can direct GCC to make
7121 calls to that function faster. One way GCC can achieve this is to
7122 integrate that function's code into the code for its callers. This
7123 makes execution faster by eliminating the function-call overhead; in
7124 addition, if any of the actual argument values are constant, their
7125 known values may permit simplifications at compile time so that not
7126 all of the inline function's code needs to be included. The effect on
7127 code size is less predictable; object code may be larger or smaller
7128 with function inlining, depending on the particular case. You can
7129 also direct GCC to try to integrate all ``simple enough'' functions
7130 into their callers with the option @option{-finline-functions}.
7132 GCC implements three different semantics of declaring a function
7133 inline. One is available with @option{-std=gnu89} or
7134 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
7135 on all inline declarations, another when
7136 @option{-std=c99}, @option{-std=c11},
7137 @option{-std=gnu99} or @option{-std=gnu11}
7138 (without @option{-fgnu89-inline}), and the third
7139 is used when compiling C++.
7141 To declare a function inline, use the @code{inline} keyword in its
7142 declaration, like this:
7152 If you are writing a header file to be included in ISO C90 programs, write
7153 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
7155 The three types of inlining behave similarly in two important cases:
7156 when the @code{inline} keyword is used on a @code{static} function,
7157 like the example above, and when a function is first declared without
7158 using the @code{inline} keyword and then is defined with
7159 @code{inline}, like this:
7162 extern int inc (int *a);
7170 In both of these common cases, the program behaves the same as if you
7171 had not used the @code{inline} keyword, except for its speed.
7173 @cindex inline functions, omission of
7174 @opindex fkeep-inline-functions
7175 When a function is both inline and @code{static}, if all calls to the
7176 function are integrated into the caller, and the function's address is
7177 never used, then the function's own assembler code is never referenced.
7178 In this case, GCC does not actually output assembler code for the
7179 function, unless you specify the option @option{-fkeep-inline-functions}.
7180 If there is a nonintegrated call, then the function is compiled to
7181 assembler code as usual. The function must also be compiled as usual if
7182 the program refers to its address, because that can't be inlined.
7185 Note that certain usages in a function definition can make it unsuitable
7186 for inline substitution. Among these usages are: variadic functions,
7187 use of @code{alloca}, use of computed goto (@pxref{Labels as Values}),
7188 use of nonlocal goto, use of nested functions, use of @code{setjmp}, use
7189 of @code{__builtin_longjmp} and use of @code{__builtin_return} or
7190 @code{__builtin_apply_args}. Using @option{-Winline} warns when a
7191 function marked @code{inline} could not be substituted, and gives the
7192 reason for the failure.
7194 @cindex automatic @code{inline} for C++ member fns
7195 @cindex @code{inline} automatic for C++ member fns
7196 @cindex member fns, automatically @code{inline}
7197 @cindex C++ member fns, automatically @code{inline}
7198 @opindex fno-default-inline
7199 As required by ISO C++, GCC considers member functions defined within
7200 the body of a class to be marked inline even if they are
7201 not explicitly declared with the @code{inline} keyword. You can
7202 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
7203 Options,,Options Controlling C++ Dialect}.
7205 GCC does not inline any functions when not optimizing unless you specify
7206 the @samp{always_inline} attribute for the function, like this:
7209 /* @r{Prototype.} */
7210 inline void foo (const char) __attribute__((always_inline));
7213 The remainder of this section is specific to GNU C90 inlining.
7215 @cindex non-static inline function
7216 When an inline function is not @code{static}, then the compiler must assume
7217 that there may be calls from other source files; since a global symbol can
7218 be defined only once in any program, the function must not be defined in
7219 the other source files, so the calls therein cannot be integrated.
7220 Therefore, a non-@code{static} inline function is always compiled on its
7221 own in the usual fashion.
7223 If you specify both @code{inline} and @code{extern} in the function
7224 definition, then the definition is used only for inlining. In no case
7225 is the function compiled on its own, not even if you refer to its
7226 address explicitly. Such an address becomes an external reference, as
7227 if you had only declared the function, and had not defined it.
7229 This combination of @code{inline} and @code{extern} has almost the
7230 effect of a macro. The way to use it is to put a function definition in
7231 a header file with these keywords, and put another copy of the
7232 definition (lacking @code{inline} and @code{extern}) in a library file.
7233 The definition in the header file causes most calls to the function
7234 to be inlined. If any uses of the function remain, they refer to
7235 the single copy in the library.
7238 @section When is a Volatile Object Accessed?
7239 @cindex accessing volatiles
7240 @cindex volatile read
7241 @cindex volatile write
7242 @cindex volatile access
7244 C has the concept of volatile objects. These are normally accessed by
7245 pointers and used for accessing hardware or inter-thread
7246 communication. The standard encourages compilers to refrain from
7247 optimizations concerning accesses to volatile objects, but leaves it
7248 implementation defined as to what constitutes a volatile access. The
7249 minimum requirement is that at a sequence point all previous accesses
7250 to volatile objects have stabilized and no subsequent accesses have
7251 occurred. Thus an implementation is free to reorder and combine
7252 volatile accesses that occur between sequence points, but cannot do
7253 so for accesses across a sequence point. The use of volatile does
7254 not allow you to violate the restriction on updating objects multiple
7255 times between two sequence points.
7257 Accesses to non-volatile objects are not ordered with respect to
7258 volatile accesses. You cannot use a volatile object as a memory
7259 barrier to order a sequence of writes to non-volatile memory. For
7263 int *ptr = @var{something};
7265 *ptr = @var{something};
7270 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
7271 that the write to @var{*ptr} occurs by the time the update
7272 of @var{vobj} happens. If you need this guarantee, you must use
7273 a stronger memory barrier such as:
7276 int *ptr = @var{something};
7278 *ptr = @var{something};
7279 asm volatile ("" : : : "memory");
7283 A scalar volatile object is read when it is accessed in a void context:
7286 volatile int *src = @var{somevalue};
7290 Such expressions are rvalues, and GCC implements this as a
7291 read of the volatile object being pointed to.
7293 Assignments are also expressions and have an rvalue. However when
7294 assigning to a scalar volatile, the volatile object is not reread,
7295 regardless of whether the assignment expression's rvalue is used or
7296 not. If the assignment's rvalue is used, the value is that assigned
7297 to the volatile object. For instance, there is no read of @var{vobj}
7298 in all the following cases:
7303 vobj = @var{something};
7304 obj = vobj = @var{something};
7305 obj ? vobj = @var{onething} : vobj = @var{anotherthing};
7306 obj = (@var{something}, vobj = @var{anotherthing});
7309 If you need to read the volatile object after an assignment has
7310 occurred, you must use a separate expression with an intervening
7313 As bit-fields are not individually addressable, volatile bit-fields may
7314 be implicitly read when written to, or when adjacent bit-fields are
7315 accessed. Bit-field operations may be optimized such that adjacent
7316 bit-fields are only partially accessed, if they straddle a storage unit
7317 boundary. For these reasons it is unwise to use volatile bit-fields to
7320 @node Using Assembly Language with C
7321 @section How to Use Inline Assembly Language in C Code
7322 @cindex @code{asm} keyword
7323 @cindex assembly language in C
7324 @cindex inline assembly language
7325 @cindex mixing assembly language and C
7327 The @code{asm} keyword allows you to embed assembler instructions
7328 within C code. GCC provides two forms of inline @code{asm}
7329 statements. A @dfn{basic @code{asm}} statement is one with no
7330 operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}}
7331 statement (@pxref{Extended Asm}) includes one or more operands.
7332 The extended form is preferred for mixing C and assembly language
7333 within a function, but to include assembly language at
7334 top level you must use basic @code{asm}.
7336 You can also use the @code{asm} keyword to override the assembler name
7337 for a C symbol, or to place a C variable in a specific register.
7340 * Basic Asm:: Inline assembler without operands.
7341 * Extended Asm:: Inline assembler with operands.
7342 * Constraints:: Constraints for @code{asm} operands
7343 * Asm Labels:: Specifying the assembler name to use for a C symbol.
7344 * Explicit Register Variables:: Defining variables residing in specified
7346 * Size of an asm:: How GCC calculates the size of an @code{asm} block.
7350 @subsection Basic Asm --- Assembler Instructions Without Operands
7351 @cindex basic @code{asm}
7352 @cindex assembly language in C, basic
7354 A basic @code{asm} statement has the following syntax:
7357 asm @r{[} volatile @r{]} ( @var{AssemblerInstructions} )
7360 The @code{asm} keyword is a GNU extension.
7361 When writing code that can be compiled with @option{-ansi} and the
7362 various @option{-std} options, use @code{__asm__} instead of
7363 @code{asm} (@pxref{Alternate Keywords}).
7365 @subsubheading Qualifiers
7368 The optional @code{volatile} qualifier has no effect.
7369 All basic @code{asm} blocks are implicitly volatile.
7372 @subsubheading Parameters
7375 @item AssemblerInstructions
7376 This is a literal string that specifies the assembler code. The string can
7377 contain any instructions recognized by the assembler, including directives.
7378 GCC does not parse the assembler instructions themselves and
7379 does not know what they mean or even whether they are valid assembler input.
7381 You may place multiple assembler instructions together in a single @code{asm}
7382 string, separated by the characters normally used in assembly code for the
7383 system. A combination that works in most places is a newline to break the
7384 line, plus a tab character (written as @samp{\n\t}).
7385 Some assemblers allow semicolons as a line separator. However,
7386 note that some assembler dialects use semicolons to start a comment.
7389 @subsubheading Remarks
7390 Using extended @code{asm} typically produces smaller, safer, and more
7391 efficient code, and in most cases it is a better solution than basic
7392 @code{asm}. However, there are two situations where only basic @code{asm}
7397 Extended @code{asm} statements have to be inside a C
7398 function, so to write inline assembly language at file scope (``top-level''),
7399 outside of C functions, you must use basic @code{asm}.
7400 You can use this technique to emit assembler directives,
7401 define assembly language macros that can be invoked elsewhere in the file,
7402 or write entire functions in assembly language.
7406 with the @code{naked} attribute also require basic @code{asm}
7407 (@pxref{Function Attributes}).
7410 Safely accessing C data and calling functions from basic @code{asm} is more
7411 complex than it may appear. To access C data, it is better to use extended
7414 Do not expect a sequence of @code{asm} statements to remain perfectly
7415 consecutive after compilation. If certain instructions need to remain
7416 consecutive in the output, put them in a single multi-instruction @code{asm}
7417 statement. Note that GCC's optimizers can move @code{asm} statements
7418 relative to other code, including across jumps.
7420 @code{asm} statements may not perform jumps into other @code{asm} statements.
7421 GCC does not know about these jumps, and therefore cannot take
7422 account of them when deciding how to optimize. Jumps from @code{asm} to C
7423 labels are only supported in extended @code{asm}.
7425 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
7426 assembly code when optimizing. This can lead to unexpected duplicate
7427 symbol errors during compilation if your assembly code defines symbols or
7430 Since GCC does not parse the @var{AssemblerInstructions}, it has no
7431 visibility of any symbols it references. This may result in GCC discarding
7432 those symbols as unreferenced.
7434 The compiler copies the assembler instructions in a basic @code{asm}
7435 verbatim to the assembly language output file, without
7436 processing dialects or any of the @samp{%} operators that are available with
7437 extended @code{asm}. This results in minor differences between basic
7438 @code{asm} strings and extended @code{asm} templates. For example, to refer to
7439 registers you might use @samp{%eax} in basic @code{asm} and
7440 @samp{%%eax} in extended @code{asm}.
7442 On targets such as x86 that support multiple assembler dialects,
7443 all basic @code{asm} blocks use the assembler dialect specified by the
7444 @option{-masm} command-line option (@pxref{x86 Options}).
7445 Basic @code{asm} provides no
7446 mechanism to provide different assembler strings for different dialects.
7448 Here is an example of basic @code{asm} for i386:
7451 /* Note that this code will not compile with -masm=intel */
7452 #define DebugBreak() asm("int $3")
7456 @subsection Extended Asm - Assembler Instructions with C Expression Operands
7457 @cindex extended @code{asm}
7458 @cindex assembly language in C, extended
7460 With extended @code{asm} you can read and write C variables from
7461 assembler and perform jumps from assembler code to C labels.
7462 Extended @code{asm} syntax uses colons (@samp{:}) to delimit
7463 the operand parameters after the assembler template:
7466 asm @r{[}volatile@r{]} ( @var{AssemblerTemplate}
7467 : @var{OutputOperands}
7468 @r{[} : @var{InputOperands}
7469 @r{[} : @var{Clobbers} @r{]} @r{]})
7471 asm @r{[}volatile@r{]} goto ( @var{AssemblerTemplate}
7473 : @var{InputOperands}
7478 The @code{asm} keyword is a GNU extension.
7479 When writing code that can be compiled with @option{-ansi} and the
7480 various @option{-std} options, use @code{__asm__} instead of
7481 @code{asm} (@pxref{Alternate Keywords}).
7483 @subsubheading Qualifiers
7487 The typical use of extended @code{asm} statements is to manipulate input
7488 values to produce output values. However, your @code{asm} statements may
7489 also produce side effects. If so, you may need to use the @code{volatile}
7490 qualifier to disable certain optimizations. @xref{Volatile}.
7493 This qualifier informs the compiler that the @code{asm} statement may
7494 perform a jump to one of the labels listed in the @var{GotoLabels}.
7498 @subsubheading Parameters
7500 @item AssemblerTemplate
7501 This is a literal string that is the template for the assembler code. It is a
7502 combination of fixed text and tokens that refer to the input, output,
7503 and goto parameters. @xref{AssemblerTemplate}.
7505 @item OutputOperands
7506 A comma-separated list of the C variables modified by the instructions in the
7507 @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
7510 A comma-separated list of C expressions read by the instructions in the
7511 @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
7514 A comma-separated list of registers or other values changed by the
7515 @var{AssemblerTemplate}, beyond those listed as outputs.
7516 An empty list is permitted. @xref{Clobbers}.
7519 When you are using the @code{goto} form of @code{asm}, this section contains
7520 the list of all C labels to which the code in the
7521 @var{AssemblerTemplate} may jump.
7524 @code{asm} statements may not perform jumps into other @code{asm} statements,
7525 only to the listed @var{GotoLabels}.
7526 GCC's optimizers do not know about other jumps; therefore they cannot take
7527 account of them when deciding how to optimize.
7530 The total number of input + output + goto operands is limited to 30.
7532 @subsubheading Remarks
7533 The @code{asm} statement allows you to include assembly instructions directly
7534 within C code. This may help you to maximize performance in time-sensitive
7535 code or to access assembly instructions that are not readily available to C
7538 Note that extended @code{asm} statements must be inside a function. Only
7539 basic @code{asm} may be outside functions (@pxref{Basic Asm}).
7540 Functions declared with the @code{naked} attribute also require basic
7541 @code{asm} (@pxref{Function Attributes}).
7543 While the uses of @code{asm} are many and varied, it may help to think of an
7544 @code{asm} statement as a series of low-level instructions that convert input
7545 parameters to output parameters. So a simple (if not particularly useful)
7546 example for i386 using @code{asm} might look like this:
7552 asm ("mov %1, %0\n\t"
7557 printf("%d\n", dst);
7560 This code copies @code{src} to @code{dst} and add 1 to @code{dst}.
7563 @subsubsection Volatile
7564 @cindex volatile @code{asm}
7565 @cindex @code{asm} volatile
7567 GCC's optimizers sometimes discard @code{asm} statements if they determine
7568 there is no need for the output variables. Also, the optimizers may move
7569 code out of loops if they believe that the code will always return the same
7570 result (i.e. none of its input values change between calls). Using the
7571 @code{volatile} qualifier disables these optimizations. @code{asm} statements
7572 that have no output operands, including @code{asm goto} statements,
7573 are implicitly volatile.
7575 This i386 code demonstrates a case that does not use (or require) the
7576 @code{volatile} qualifier. If it is performing assertion checking, this code
7577 uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is
7578 unreferenced by any code. As a result, the optimizers can discard the
7579 @code{asm} statement, which in turn removes the need for the entire
7580 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
7581 isn't needed you allow the optimizers to produce the most efficient code
7585 void DoCheck(uint32_t dwSomeValue)
7589 // Assumes dwSomeValue is not zero.
7599 The next example shows a case where the optimizers can recognize that the input
7600 (@code{dwSomeValue}) never changes during the execution of the function and can
7601 therefore move the @code{asm} outside the loop to produce more efficient code.
7602 Again, using @code{volatile} disables this type of optimization.
7605 void do_print(uint32_t dwSomeValue)
7609 for (uint32_t x=0; x < 5; x++)
7611 // Assumes dwSomeValue is not zero.
7617 printf("%u: %u %u\n", x, dwSomeValue, dwRes);
7622 The following example demonstrates a case where you need to use the
7623 @code{volatile} qualifier.
7624 It uses the x86 @code{rdtsc} instruction, which reads
7625 the computer's time-stamp counter. Without the @code{volatile} qualifier,
7626 the optimizers might assume that the @code{asm} block will always return the
7627 same value and therefore optimize away the second call.
7632 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
7633 "shl $32, %%rdx\n\t" // Shift the upper bits left.
7634 "or %%rdx, %0" // 'Or' in the lower bits.
7639 printf("msr: %llx\n", msr);
7643 // Reprint the timestamp
7644 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
7645 "shl $32, %%rdx\n\t" // Shift the upper bits left.
7646 "or %%rdx, %0" // 'Or' in the lower bits.
7651 printf("msr: %llx\n", msr);
7654 GCC's optimizers do not treat this code like the non-volatile code in the
7655 earlier examples. They do not move it out of loops or omit it on the
7656 assumption that the result from a previous call is still valid.
7658 Note that the compiler can move even volatile @code{asm} instructions relative
7659 to other code, including across jump instructions. For example, on many
7660 targets there is a system register that controls the rounding mode of
7661 floating-point operations. Setting it with a volatile @code{asm}, as in the
7662 following PowerPC example, does not work reliably.
7665 asm volatile("mtfsf 255, %0" : : "f" (fpenv));
7669 The compiler may move the addition back before the volatile @code{asm}. To
7670 make it work as expected, add an artificial dependency to the @code{asm} by
7671 referencing a variable in the subsequent code, for example:
7674 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
7678 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
7679 assembly code when optimizing. This can lead to unexpected duplicate symbol
7680 errors during compilation if your asm code defines symbols or labels.
7682 (@pxref{AssemblerTemplate}) may help resolve this problem.
7684 @anchor{AssemblerTemplate}
7685 @subsubsection Assembler Template
7686 @cindex @code{asm} assembler template
7688 An assembler template is a literal string containing assembler instructions.
7689 The compiler replaces tokens in the template that refer
7690 to inputs, outputs, and goto labels,
7691 and then outputs the resulting string to the assembler. The
7692 string can contain any instructions recognized by the assembler, including
7693 directives. GCC does not parse the assembler instructions
7694 themselves and does not know what they mean or even whether they are valid
7695 assembler input. However, it does count the statements
7696 (@pxref{Size of an asm}).
7698 You may place multiple assembler instructions together in a single @code{asm}
7699 string, separated by the characters normally used in assembly code for the
7700 system. A combination that works in most places is a newline to break the
7701 line, plus a tab character to move to the instruction field (written as
7703 Some assemblers allow semicolons as a line separator. However, note
7704 that some assembler dialects use semicolons to start a comment.
7706 Do not expect a sequence of @code{asm} statements to remain perfectly
7707 consecutive after compilation, even when you are using the @code{volatile}
7708 qualifier. If certain instructions need to remain consecutive in the output,
7709 put them in a single multi-instruction asm statement.
7711 Accessing data from C programs without using input/output operands (such as
7712 by using global symbols directly from the assembler template) may not work as
7713 expected. Similarly, calling functions directly from an assembler template
7714 requires a detailed understanding of the target assembler and ABI.
7716 Since GCC does not parse the assembler template,
7717 it has no visibility of any
7718 symbols it references. This may result in GCC discarding those symbols as
7719 unreferenced unless they are also listed as input, output, or goto operands.
7721 @subsubheading Special format strings
7723 In addition to the tokens described by the input, output, and goto operands,
7724 these tokens have special meanings in the assembler template:
7728 Outputs a single @samp{%} into the assembler code.
7731 Outputs a number that is unique to each instance of the @code{asm}
7732 statement in the entire compilation. This option is useful when creating local
7733 labels and referring to them multiple times in a single template that
7734 generates multiple assembler instructions.
7739 Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively)
7740 into the assembler code. When unescaped, these characters have special
7741 meaning to indicate multiple assembler dialects, as described below.
7744 @subsubheading Multiple assembler dialects in @code{asm} templates
7746 On targets such as x86, GCC supports multiple assembler dialects.
7747 The @option{-masm} option controls which dialect GCC uses as its
7748 default for inline assembler. The target-specific documentation for the
7749 @option{-masm} option contains the list of supported dialects, as well as the
7750 default dialect if the option is not specified. This information may be
7751 important to understand, since assembler code that works correctly when
7752 compiled using one dialect will likely fail if compiled using another.
7755 If your code needs to support multiple assembler dialects (for example, if
7756 you are writing public headers that need to support a variety of compilation
7757 options), use constructs of this form:
7760 @{ dialect0 | dialect1 | dialect2... @}
7763 This construct outputs @code{dialect0}
7764 when using dialect #0 to compile the code,
7765 @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the
7766 braces than the number of dialects the compiler supports, the construct
7769 For example, if an x86 compiler supports two dialects
7770 (@samp{att}, @samp{intel}), an
7771 assembler template such as this:
7774 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
7778 is equivalent to one of
7781 "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */}
7782 "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */}
7785 Using that same compiler, this code:
7788 "xchg@{l@}\t@{%%@}ebx, %1"
7792 corresponds to either
7795 "xchgl\t%%ebx, %1" @r{/* att dialect */}
7796 "xchg\tebx, %1" @r{/* intel dialect */}
7799 There is no support for nesting dialect alternatives.
7801 @anchor{OutputOperands}
7802 @subsubsection Output Operands
7803 @cindex @code{asm} output operands
7805 An @code{asm} statement has zero or more output operands indicating the names
7806 of C variables modified by the assembler code.
7808 In this i386 example, @code{old} (referred to in the template string as
7809 @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset}
7810 (@code{%2}) is an input:
7815 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
7816 "sbb %0,%0" // Use the CF to calculate old.
7817 : "=r" (old), "+rm" (*Base)
7824 Operands are separated by commas. Each operand has this format:
7827 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename})
7831 @item asmSymbolicName
7832 Specifies a symbolic name for the operand.
7833 Reference the name in the assembler template
7834 by enclosing it in square brackets
7835 (i.e. @samp{%[Value]}). The scope of the name is the @code{asm} statement
7836 that contains the definition. Any valid C variable name is acceptable,
7837 including names already defined in the surrounding code. No two operands
7838 within the same @code{asm} statement can use the same symbolic name.
7840 When not using an @var{asmSymbolicName}, use the (zero-based) position
7842 in the list of operands in the assembler template. For example if there are
7843 three output operands, use @samp{%0} in the template to refer to the first,
7844 @samp{%1} for the second, and @samp{%2} for the third.
7847 A string constant specifying constraints on the placement of the operand;
7848 @xref{Constraints}, for details.
7850 Output constraints must begin with either @samp{=} (a variable overwriting an
7851 existing value) or @samp{+} (when reading and writing). When using
7852 @samp{=}, do not assume the location contains the existing value
7853 on entry to the @code{asm}, except
7854 when the operand is tied to an input; @pxref{InputOperands,,Input Operands}.
7856 After the prefix, there must be one or more additional constraints
7857 (@pxref{Constraints}) that describe where the value resides. Common
7858 constraints include @samp{r} for register and @samp{m} for memory.
7859 When you list more than one possible location (for example, @code{"=rm"}),
7860 the compiler chooses the most efficient one based on the current context.
7861 If you list as many alternates as the @code{asm} statement allows, you permit
7862 the optimizers to produce the best possible code.
7863 If you must use a specific register, but your Machine Constraints do not
7864 provide sufficient control to select the specific register you want,
7865 local register variables may provide a solution (@pxref{Local Register
7869 Specifies a C lvalue expression to hold the output, typically a variable name.
7870 The enclosing parentheses are a required part of the syntax.
7874 When the compiler selects the registers to use to
7875 represent the output operands, it does not use any of the clobbered registers
7878 Output operand expressions must be lvalues. The compiler cannot check whether
7879 the operands have data types that are reasonable for the instruction being
7880 executed. For output expressions that are not directly addressable (for
7881 example a bit-field), the constraint must allow a register. In that case, GCC
7882 uses the register as the output of the @code{asm}, and then stores that
7883 register into the output.
7885 Operands using the @samp{+} constraint modifier count as two operands
7886 (that is, both as input and output) towards the total maximum of 30 operands
7887 per @code{asm} statement.
7889 Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output
7890 operands that must not overlap an input. Otherwise,
7891 GCC may allocate the output operand in the same register as an unrelated
7892 input operand, on the assumption that the assembler code consumes its
7893 inputs before producing outputs. This assumption may be false if the assembler
7894 code actually consists of more than one instruction.
7896 The same problem can occur if one output parameter (@var{a}) allows a register
7897 constraint and another output parameter (@var{b}) allows a memory constraint.
7898 The code generated by GCC to access the memory address in @var{b} can contain
7899 registers which @emph{might} be shared by @var{a}, and GCC considers those
7900 registers to be inputs to the asm. As above, GCC assumes that such input
7901 registers are consumed before any outputs are written. This assumption may
7902 result in incorrect behavior if the asm writes to @var{a} before using
7903 @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a}
7904 ensures that modifying @var{a} does not affect the address referenced by
7905 @var{b}. Otherwise, the location of @var{b}
7906 is undefined if @var{a} is modified before using @var{b}.
7908 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
7909 instead of simply @samp{%2}). Typically these qualifiers are hardware
7910 dependent. The list of supported modifiers for x86 is found at
7911 @ref{x86Operandmodifiers,x86 Operand modifiers}.
7913 If the C code that follows the @code{asm} makes no use of any of the output
7914 operands, use @code{volatile} for the @code{asm} statement to prevent the
7915 optimizers from discarding the @code{asm} statement as unneeded
7916 (see @ref{Volatile}).
7918 This code makes no use of the optional @var{asmSymbolicName}. Therefore it
7919 references the first output operand as @code{%0} (were there a second, it
7920 would be @code{%1}, etc). The number of the first input operand is one greater
7921 than that of the last output operand. In this i386 example, that makes
7922 @code{Mask} referenced as @code{%1}:
7925 uint32_t Mask = 1234;
7934 That code overwrites the variable @code{Index} (@samp{=}),
7935 placing the value in a register (@samp{r}).
7936 Using the generic @samp{r} constraint instead of a constraint for a specific
7937 register allows the compiler to pick the register to use, which can result
7938 in more efficient code. This may not be possible if an assembler instruction
7939 requires a specific register.
7941 The following i386 example uses the @var{asmSymbolicName} syntax.
7943 same result as the code above, but some may consider it more readable or more
7944 maintainable since reordering index numbers is not necessary when adding or
7945 removing operands. The names @code{aIndex} and @code{aMask}
7946 are only used in this example to emphasize which
7947 names get used where.
7948 It is acceptable to reuse the names @code{Index} and @code{Mask}.
7951 uint32_t Mask = 1234;
7954 asm ("bsfl %[aMask], %[aIndex]"
7955 : [aIndex] "=r" (Index)
7956 : [aMask] "r" (Mask)
7960 Here are some more examples of output operands.
7967 asm ("mov %[e], %[d]"
7972 Here, @code{d} may either be in a register or in memory. Since the compiler
7973 might already have the current value of the @code{uint32_t} location
7974 pointed to by @code{e}
7975 in a register, you can enable it to choose the best location
7976 for @code{d} by specifying both constraints.
7978 @anchor{FlagOutputOperands}
7979 @subsection Flag Output Operands
7980 @cindex @code{asm} flag output operands
7982 Some targets have a special register that holds the ``flags'' for the
7983 result of an operation or comparison. Normally, the contents of that
7984 register are either unmodifed by the asm, or the asm is considered to
7985 clobber the contents.
7987 On some targets, a special form of output operand exists by which
7988 conditions in the flags register may be outputs of the asm. The set of
7989 conditions supported are target specific, but the general rule is that
7990 the output variable must be a scalar integer, and the value will be boolean.
7991 When supported, the target will define the preprocessor symbol
7992 @code{__GCC_ASM_FLAG_OUTPUTS__}.
7994 Because of the special nature of the flag output operands, the constraint
7995 may not include alternatives.
7997 Most often, the target has only one flags register, and thus is an implied
7998 operand of many instructions. In this case, the operand should not be
7999 referenced within the assembler template via @code{%0} etc, as there's
8000 no corresponding text in the assembly language.
8004 The flag output constraints for the x86 family are of the form
8005 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard
8006 conditions defined in the ISA manual for @code{j@var{cc}} or
8011 ``above'' or unsigned greater than
8013 ``above or equal'' or unsigned greater than or equal
8015 ``below'' or unsigned less than
8017 ``below or equal'' or unsigned less than or equal
8022 ``equal'' or zero flag set
8026 signed greater than or equal
8030 signed less than or equal
8051 ``not'' @var{flag}, or inverted versions of those above
8056 @anchor{InputOperands}
8057 @subsubsection Input Operands
8058 @cindex @code{asm} input operands
8059 @cindex @code{asm} expressions
8061 Input operands make values from C variables and expressions available to the
8064 Operands are separated by commas. Each operand has this format:
8067 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression})
8071 @item asmSymbolicName
8072 Specifies a symbolic name for the operand.
8073 Reference the name in the assembler template
8074 by enclosing it in square brackets
8075 (i.e. @samp{%[Value]}). The scope of the name is the @code{asm} statement
8076 that contains the definition. Any valid C variable name is acceptable,
8077 including names already defined in the surrounding code. No two operands
8078 within the same @code{asm} statement can use the same symbolic name.
8080 When not using an @var{asmSymbolicName}, use the (zero-based) position
8082 in the list of operands in the assembler template. For example if there are
8083 two output operands and three inputs,
8084 use @samp{%2} in the template to refer to the first input operand,
8085 @samp{%3} for the second, and @samp{%4} for the third.
8088 A string constant specifying constraints on the placement of the operand;
8089 @xref{Constraints}, for details.
8091 Input constraint strings may not begin with either @samp{=} or @samp{+}.
8092 When you list more than one possible location (for example, @samp{"irm"}),
8093 the compiler chooses the most efficient one based on the current context.
8094 If you must use a specific register, but your Machine Constraints do not
8095 provide sufficient control to select the specific register you want,
8096 local register variables may provide a solution (@pxref{Local Register
8099 Input constraints can also be digits (for example, @code{"0"}). This indicates
8100 that the specified input must be in the same place as the output constraint
8101 at the (zero-based) index in the output constraint list.
8102 When using @var{asmSymbolicName} syntax for the output operands,
8103 you may use these names (enclosed in brackets @samp{[]}) instead of digits.
8106 This is the C variable or expression being passed to the @code{asm} statement
8107 as input. The enclosing parentheses are a required part of the syntax.
8111 When the compiler selects the registers to use to represent the input
8112 operands, it does not use any of the clobbered registers (@pxref{Clobbers}).
8114 If there are no output operands but there are input operands, place two
8115 consecutive colons where the output operands would go:
8118 __asm__ ("some instructions"
8120 : "r" (Offset / 8));
8123 @strong{Warning:} Do @emph{not} modify the contents of input-only operands
8124 (except for inputs tied to outputs). The compiler assumes that on exit from
8125 the @code{asm} statement these operands contain the same values as they
8126 had before executing the statement.
8127 It is @emph{not} possible to use clobbers
8128 to inform the compiler that the values in these inputs are changing. One
8129 common work-around is to tie the changing input variable to an output variable
8130 that never gets used. Note, however, that if the code that follows the
8131 @code{asm} statement makes no use of any of the output operands, the GCC
8132 optimizers may discard the @code{asm} statement as unneeded
8133 (see @ref{Volatile}).
8135 @code{asm} supports operand modifiers on operands (for example @samp{%k2}
8136 instead of simply @samp{%2}). Typically these qualifiers are hardware
8137 dependent. The list of supported modifiers for x86 is found at
8138 @ref{x86Operandmodifiers,x86 Operand modifiers}.
8140 In this example using the fictitious @code{combine} instruction, the
8141 constraint @code{"0"} for input operand 1 says that it must occupy the same
8142 location as output operand 0. Only input operands may use numbers in
8143 constraints, and they must each refer to an output operand. Only a number (or
8144 the symbolic assembler name) in the constraint can guarantee that one operand
8145 is in the same place as another. The mere fact that @code{foo} is the value of
8146 both operands is not enough to guarantee that they are in the same place in
8147 the generated assembler code.
8150 asm ("combine %2, %0"
8152 : "0" (foo), "g" (bar));
8155 Here is an example using symbolic names.
8158 asm ("cmoveq %1, %2, %[result]"
8159 : [result] "=r"(result)
8160 : "r" (test), "r" (new), "[result]" (old));
8164 @subsubsection Clobbers
8165 @cindex @code{asm} clobbers
8167 While the compiler is aware of changes to entries listed in the output
8168 operands, the inline @code{asm} code may modify more than just the outputs. For
8169 example, calculations may require additional registers, or the processor may
8170 overwrite a register as a side effect of a particular assembler instruction.
8171 In order to inform the compiler of these changes, list them in the clobber
8172 list. Clobber list items are either register names or the special clobbers
8173 (listed below). Each clobber list item is a string constant
8174 enclosed in double quotes and separated by commas.
8176 Clobber descriptions may not in any way overlap with an input or output
8177 operand. For example, you may not have an operand describing a register class
8178 with one member when listing that register in the clobber list. Variables
8179 declared to live in specific registers (@pxref{Explicit Register
8180 Variables}) and used
8181 as @code{asm} input or output operands must have no part mentioned in the
8182 clobber description. In particular, there is no way to specify that input
8183 operands get modified without also specifying them as output operands.
8185 When the compiler selects which registers to use to represent input and output
8186 operands, it does not use any of the clobbered registers. As a result,
8187 clobbered registers are available for any use in the assembler code.
8189 Here is a realistic example for the VAX showing the use of clobbered
8193 asm volatile ("movc3 %0, %1, %2"
8195 : "g" (from), "g" (to), "g" (count)
8196 : "r0", "r1", "r2", "r3", "r4", "r5");
8199 Also, there are two special clobber arguments:
8203 The @code{"cc"} clobber indicates that the assembler code modifies the flags
8204 register. On some machines, GCC represents the condition codes as a specific
8205 hardware register; @code{"cc"} serves to name this register.
8206 On other machines, condition code handling is different,
8207 and specifying @code{"cc"} has no effect. But
8208 it is valid no matter what the target.
8211 The @code{"memory"} clobber tells the compiler that the assembly code
8213 reads or writes to items other than those listed in the input and output
8214 operands (for example, accessing the memory pointed to by one of the input
8215 parameters). To ensure memory contains correct values, GCC may need to flush
8216 specific register values to memory before executing the @code{asm}. Further,
8217 the compiler does not assume that any values read from memory before an
8218 @code{asm} remain unchanged after that @code{asm}; it reloads them as
8220 Using the @code{"memory"} clobber effectively forms a read/write
8221 memory barrier for the compiler.
8223 Note that this clobber does not prevent the @emph{processor} from doing
8224 speculative reads past the @code{asm} statement. To prevent that, you need
8225 processor-specific fence instructions.
8227 Flushing registers to memory has performance implications and may be an issue
8228 for time-sensitive code. You can use a trick to avoid this if the size of
8229 the memory being accessed is known at compile time. For example, if accessing
8230 ten bytes of a string, use a memory input like:
8232 @code{@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}}.
8237 @subsubsection Goto Labels
8238 @cindex @code{asm} goto labels
8240 @code{asm goto} allows assembly code to jump to one or more C labels. The
8241 @var{GotoLabels} section in an @code{asm goto} statement contains
8243 list of all C labels to which the assembler code may jump. GCC assumes that
8244 @code{asm} execution falls through to the next statement (if this is not the
8245 case, consider using the @code{__builtin_unreachable} intrinsic after the
8246 @code{asm} statement). Optimization of @code{asm goto} may be improved by
8247 using the @code{hot} and @code{cold} label attributes (@pxref{Label
8250 An @code{asm goto} statement cannot have outputs.
8251 This is due to an internal restriction of
8252 the compiler: control transfer instructions cannot have outputs.
8253 If the assembler code does modify anything, use the @code{"memory"} clobber
8255 optimizers to flush all register values to memory and reload them if
8256 necessary after the @code{asm} statement.
8258 Also note that an @code{asm goto} statement is always implicitly
8259 considered volatile.
8261 To reference a label in the assembler template,
8262 prefix it with @samp{%l} (lowercase @samp{L}) followed
8263 by its (zero-based) position in @var{GotoLabels} plus the number of input
8264 operands. For example, if the @code{asm} has three inputs and references two
8265 labels, refer to the first label as @samp{%l3} and the second as @samp{%l4}).
8267 Alternately, you can reference labels using the actual C label name enclosed
8268 in brackets. For example, to reference a label named @code{carry}, you can
8269 use @samp{%l[carry]}. The label must still be listed in the @var{GotoLabels}
8270 section when using this approach.
8272 Here is an example of @code{asm goto} for i386:
8279 : "r" (p1), "r" (p2)
8289 The following example shows an @code{asm goto} that uses a memory clobber.
8295 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
8306 @anchor{x86Operandmodifiers}
8307 @subsubsection x86 Operand Modifiers
8309 References to input, output, and goto operands in the assembler template
8310 of extended @code{asm} statements can use
8311 modifiers to affect the way the operands are formatted in
8312 the code output to the assembler. For example, the
8313 following code uses the @samp{h} and @samp{b} modifiers for x86:
8317 asm volatile ("xchg %h0, %b0" : "+a" (num) );
8321 These modifiers generate this assembler code:
8327 The rest of this discussion uses the following code for illustrative purposes.
8336 asm volatile goto ("some assembler instructions here"
8338 : "q" (iInt), "X" (sizeof(unsigned char) + 1)
8339 : /* No clobbers. */
8344 With no modifiers, this is what the output from the operands would be for the
8345 @samp{att} and @samp{intel} dialects of assembler:
8347 @multitable {Operand} {masm=att} {OFFSET FLAT:.L2}
8348 @headitem Operand @tab masm=att @tab masm=intel
8357 @tab @code{OFFSET FLAT:.L2}
8360 The table below shows the list of supported modifiers and their effects.
8362 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {masm=att} {masm=intel}
8363 @headitem Modifier @tab Description @tab Operand @tab @option{masm=att} @tab @option{masm=intel}
8365 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
8370 @tab Print the QImode name of the register.
8375 @tab Print the QImode name for a ``high'' register.
8380 @tab Print the HImode name of the register.
8385 @tab Print the SImode name of the register.
8390 @tab Print the DImode name of the register.
8395 @tab Print the label name with no punctuation.
8400 @tab Require a constant operand and print the constant expression with no punctuation.
8406 @anchor{x86floatingpointasmoperands}
8407 @subsubsection x86 Floating-Point @code{asm} Operands
8409 On x86 targets, there are several rules on the usage of stack-like registers
8410 in the operands of an @code{asm}. These rules apply only to the operands
8411 that are stack-like registers:
8415 Given a set of input registers that die in an @code{asm}, it is
8416 necessary to know which are implicitly popped by the @code{asm}, and
8417 which must be explicitly popped by GCC@.
8419 An input register that is implicitly popped by the @code{asm} must be
8420 explicitly clobbered, unless it is constrained to match an
8424 For any input register that is implicitly popped by an @code{asm}, it is
8425 necessary to know how to adjust the stack to compensate for the pop.
8426 If any non-popped input is closer to the top of the reg-stack than
8427 the implicitly popped register, it would not be possible to know what the
8428 stack looked like---it's not clear how the rest of the stack ``slides
8431 All implicitly popped input registers must be closer to the top of
8432 the reg-stack than any input that is not implicitly popped.
8434 It is possible that if an input dies in an @code{asm}, the compiler might
8435 use the input register for an output reload. Consider this example:
8438 asm ("foo" : "=t" (a) : "f" (b));
8442 This code says that input @code{b} is not popped by the @code{asm}, and that
8443 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
8444 deeper after the @code{asm} than it was before. But, it is possible that
8445 reload may think that it can use the same register for both the input and
8448 To prevent this from happening,
8449 if any input operand uses the @samp{f} constraint, all output register
8450 constraints must use the @samp{&} early-clobber modifier.
8452 The example above is correctly written as:
8455 asm ("foo" : "=&t" (a) : "f" (b));
8459 Some operands need to be in particular places on the stack. All
8460 output operands fall in this category---GCC has no other way to
8461 know which registers the outputs appear in unless you indicate
8462 this in the constraints.
8464 Output operands must specifically indicate which register an output
8465 appears in after an @code{asm}. @samp{=f} is not allowed: the operand
8466 constraints must select a class with a single register.
8469 Output operands may not be ``inserted'' between existing stack registers.
8470 Since no 387 opcode uses a read/write operand, all output operands
8471 are dead before the @code{asm}, and are pushed by the @code{asm}.
8472 It makes no sense to push anywhere but the top of the reg-stack.
8474 Output operands must start at the top of the reg-stack: output
8475 operands may not ``skip'' a register.
8478 Some @code{asm} statements may need extra stack space for internal
8479 calculations. This can be guaranteed by clobbering stack registers
8480 unrelated to the inputs and outputs.
8485 takes one input, which is internally popped, and produces two outputs.
8488 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
8492 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
8493 and replaces them with one output. The @code{st(1)} clobber is necessary
8494 for the compiler to know that @code{fyl2xp1} pops both inputs.
8497 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
8505 @subsection Controlling Names Used in Assembler Code
8506 @cindex assembler names for identifiers
8507 @cindex names used in assembler code
8508 @cindex identifiers, names in assembler code
8510 You can specify the name to be used in the assembler code for a C
8511 function or variable by writing the @code{asm} (or @code{__asm__})
8512 keyword after the declarator.
8513 It is up to you to make sure that the assembler names you choose do not
8514 conflict with any other assembler symbols, or reference registers.
8516 @subsubheading Assembler names for data:
8518 This sample shows how to specify the assembler name for data:
8521 int foo asm ("myfoo") = 2;
8525 This specifies that the name to be used for the variable @code{foo} in
8526 the assembler code should be @samp{myfoo} rather than the usual
8529 On systems where an underscore is normally prepended to the name of a C
8530 variable, this feature allows you to define names for the
8531 linker that do not start with an underscore.
8533 GCC does not support using this feature with a non-static local variable
8534 since such variables do not have assembler names. If you are
8535 trying to put the variable in a particular register, see
8536 @ref{Explicit Register Variables}.
8538 @subsubheading Assembler names for functions:
8540 To specify the assembler name for functions, write a declaration for the
8541 function before its definition and put @code{asm} there, like this:
8544 int func (int x, int y) asm ("MYFUNC");
8546 int func (int x, int y)
8552 This specifies that the name to be used for the function @code{func} in
8553 the assembler code should be @code{MYFUNC}.
8555 @node Explicit Register Variables
8556 @subsection Variables in Specified Registers
8557 @anchor{Explicit Reg Vars}
8558 @cindex explicit register variables
8559 @cindex variables in specified registers
8560 @cindex specified registers
8562 GNU C allows you to associate specific hardware registers with C
8563 variables. In almost all cases, allowing the compiler to assign
8564 registers produces the best code. However under certain unusual
8565 circumstances, more precise control over the variable storage is
8568 Both global and local variables can be associated with a register. The
8569 consequences of performing this association are very different between
8570 the two, as explained in the sections below.
8573 * Global Register Variables:: Variables declared at global scope.
8574 * Local Register Variables:: Variables declared within a function.
8577 @node Global Register Variables
8578 @subsubsection Defining Global Register Variables
8579 @anchor{Global Reg Vars}
8580 @cindex global register variables
8581 @cindex registers, global variables in
8582 @cindex registers, global allocation
8584 You can define a global register variable and associate it with a specified
8588 register int *foo asm ("r12");
8592 Here @code{r12} is the name of the register that should be used. Note that
8593 this is the same syntax used for defining local register variables, but for
8594 a global variable the declaration appears outside a function. The
8595 @code{register} keyword is required, and cannot be combined with
8596 @code{static}. The register name must be a valid register name for the
8599 Registers are a scarce resource on most systems and allowing the
8600 compiler to manage their usage usually results in the best code. However,
8601 under special circumstances it can make sense to reserve some globally.
8602 For example this may be useful in programs such as programming language
8603 interpreters that have a couple of global variables that are accessed
8606 After defining a global register variable, for the current compilation
8610 @item The register is reserved entirely for this use, and will not be
8611 allocated for any other purpose.
8612 @item The register is not saved and restored by any functions.
8613 @item Stores into this register are never deleted even if they appear to be
8614 dead, but references may be deleted, moved or simplified.
8617 Note that these points @emph{only} apply to code that is compiled with the
8618 definition. The behavior of code that is merely linked in (for example
8619 code from libraries) is not affected.
8621 If you want to recompile source files that do not actually use your global
8622 register variable so they do not use the specified register for any other
8623 purpose, you need not actually add the global register declaration to
8624 their source code. It suffices to specify the compiler option
8625 @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the
8628 @subsubheading Declaring the variable
8630 Global register variables can not have initial values, because an
8631 executable file has no means to supply initial contents for a register.
8633 When selecting a register, choose one that is normally saved and
8634 restored by function calls on your machine. This ensures that code
8635 which is unaware of this reservation (such as library routines) will
8636 restore it before returning.
8638 On machines with register windows, be sure to choose a global
8639 register that is not affected magically by the function call mechanism.
8641 @subsubheading Using the variable
8643 @cindex @code{qsort}, and global register variables
8644 When calling routines that are not aware of the reservation, be
8645 cautious if those routines call back into code which uses them. As an
8646 example, if you call the system library version of @code{qsort}, it may
8647 clobber your registers during execution, but (if you have selected
8648 appropriate registers) it will restore them before returning. However
8649 it will @emph{not} restore them before calling @code{qsort}'s comparison
8650 function. As a result, global values will not reliably be available to
8651 the comparison function unless the @code{qsort} function itself is rebuilt.
8653 Similarly, it is not safe to access the global register variables from signal
8654 handlers or from more than one thread of control. Unless you recompile
8655 them specially for the task at hand, the system library routines may
8656 temporarily use the register for other things.
8658 @cindex register variable after @code{longjmp}
8659 @cindex global register after @code{longjmp}
8660 @cindex value after @code{longjmp}
8663 On most machines, @code{longjmp} restores to each global register
8664 variable the value it had at the time of the @code{setjmp}. On some
8665 machines, however, @code{longjmp} does not change the value of global
8666 register variables. To be portable, the function that called @code{setjmp}
8667 should make other arrangements to save the values of the global register
8668 variables, and to restore them in a @code{longjmp}. This way, the same
8669 thing happens regardless of what @code{longjmp} does.
8671 Eventually there may be a way of asking the compiler to choose a register
8672 automatically, but first we need to figure out how it should choose and
8673 how to enable you to guide the choice. No solution is evident.
8675 @node Local Register Variables
8676 @subsubsection Specifying Registers for Local Variables
8677 @anchor{Local Reg Vars}
8678 @cindex local variables, specifying registers
8679 @cindex specifying registers for local variables
8680 @cindex registers for local variables
8682 You can define a local register variable and associate it with a specified
8686 register int *foo asm ("r12");
8690 Here @code{r12} is the name of the register that should be used. Note
8691 that this is the same syntax used for defining global register variables,
8692 but for a local variable the declaration appears within a function. The
8693 @code{register} keyword is required, and cannot be combined with
8694 @code{static}. The register name must be a valid register name for the
8697 As with global register variables, it is recommended that you choose
8698 a register that is normally saved and restored by function calls on your
8699 machine, so that calls to library routines will not clobber it.
8701 The only supported use for this feature is to specify registers
8702 for input and output operands when calling Extended @code{asm}
8703 (@pxref{Extended Asm}). This may be necessary if the constraints for a
8704 particular machine don't provide sufficient control to select the desired
8705 register. To force an operand into a register, create a local variable
8706 and specify the register name after the variable's declaration. Then use
8707 the local variable for the @code{asm} operand and specify any constraint
8708 letter that matches the register:
8711 register int *p1 asm ("r0") = @dots{};
8712 register int *p2 asm ("r1") = @dots{};
8713 register int *result asm ("r0");
8714 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
8717 @emph{Warning:} In the above example, be aware that a register (for example
8718 @code{r0}) can be call-clobbered by subsequent code, including function
8719 calls and library calls for arithmetic operators on other variables (for
8720 example the initialization of @code{p2}). In this case, use temporary
8721 variables for expressions between the register assignments:
8725 register int *p1 asm ("r0") = @dots{};
8726 register int *p2 asm ("r1") = t1;
8727 register int *result asm ("r0");
8728 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
8731 Defining a register variable does not reserve the register. Other than
8732 when invoking the Extended @code{asm}, the contents of the specified
8733 register are not guaranteed. For this reason, the following uses
8734 are explicitly @emph{not} supported. If they appear to work, it is only
8735 happenstance, and may stop working as intended due to (seemingly)
8736 unrelated changes in surrounding code, or even minor changes in the
8737 optimization of a future version of gcc:
8740 @item Passing parameters to or from Basic @code{asm}
8741 @item Passing parameters to or from Extended @code{asm} without using input
8743 @item Passing parameters to or from routines written in assembler (or
8744 other languages) using non-standard calling conventions.
8747 Some developers use Local Register Variables in an attempt to improve
8748 gcc's allocation of registers, especially in large functions. In this
8749 case the register name is essentially a hint to the register allocator.
8750 While in some instances this can generate better code, improvements are
8751 subject to the whims of the allocator/optimizers. Since there are no
8752 guarantees that your improvements won't be lost, this usage of Local
8753 Register Variables is discouraged.
8755 On the MIPS platform, there is related use for local register variables
8756 with slightly different characteristics (@pxref{MIPS Coprocessors,,
8757 Defining coprocessor specifics for MIPS targets, gccint,
8758 GNU Compiler Collection (GCC) Internals}).
8760 @node Size of an asm
8761 @subsection Size of an @code{asm}
8763 Some targets require that GCC track the size of each instruction used
8764 in order to generate correct code. Because the final length of the
8765 code produced by an @code{asm} statement is only known by the
8766 assembler, GCC must make an estimate as to how big it will be. It
8767 does this by counting the number of instructions in the pattern of the
8768 @code{asm} and multiplying that by the length of the longest
8769 instruction supported by that processor. (When working out the number
8770 of instructions, it assumes that any occurrence of a newline or of
8771 whatever statement separator character is supported by the assembler --
8772 typically @samp{;} --- indicates the end of an instruction.)
8774 Normally, GCC's estimate is adequate to ensure that correct
8775 code is generated, but it is possible to confuse the compiler if you use
8776 pseudo instructions or assembler macros that expand into multiple real
8777 instructions, or if you use assembler directives that expand to more
8778 space in the object file than is needed for a single instruction.
8779 If this happens then the assembler may produce a diagnostic saying that
8780 a label is unreachable.
8782 @node Alternate Keywords
8783 @section Alternate Keywords
8784 @cindex alternate keywords
8785 @cindex keywords, alternate
8787 @option{-ansi} and the various @option{-std} options disable certain
8788 keywords. This causes trouble when you want to use GNU C extensions, or
8789 a general-purpose header file that should be usable by all programs,
8790 including ISO C programs. The keywords @code{asm}, @code{typeof} and
8791 @code{inline} are not available in programs compiled with
8792 @option{-ansi} or @option{-std} (although @code{inline} can be used in a
8793 program compiled with @option{-std=c99} or @option{-std=c11}). The
8795 @code{restrict} is only available when @option{-std=gnu99} (which will
8796 eventually be the default) or @option{-std=c99} (or the equivalent
8797 @option{-std=iso9899:1999}), or an option for a later standard
8800 The way to solve these problems is to put @samp{__} at the beginning and
8801 end of each problematical keyword. For example, use @code{__asm__}
8802 instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
8804 Other C compilers won't accept these alternative keywords; if you want to
8805 compile with another compiler, you can define the alternate keywords as
8806 macros to replace them with the customary keywords. It looks like this:
8814 @findex __extension__
8816 @option{-pedantic} and other options cause warnings for many GNU C extensions.
8818 prevent such warnings within one expression by writing
8819 @code{__extension__} before the expression. @code{__extension__} has no
8820 effect aside from this.
8822 @node Incomplete Enums
8823 @section Incomplete @code{enum} Types
8825 You can define an @code{enum} tag without specifying its possible values.
8826 This results in an incomplete type, much like what you get if you write
8827 @code{struct foo} without describing the elements. A later declaration
8828 that does specify the possible values completes the type.
8830 You can't allocate variables or storage using the type while it is
8831 incomplete. However, you can work with pointers to that type.
8833 This extension may not be very useful, but it makes the handling of
8834 @code{enum} more consistent with the way @code{struct} and @code{union}
8837 This extension is not supported by GNU C++.
8839 @node Function Names
8840 @section Function Names as Strings
8841 @cindex @code{__func__} identifier
8842 @cindex @code{__FUNCTION__} identifier
8843 @cindex @code{__PRETTY_FUNCTION__} identifier
8845 GCC provides three magic variables that hold the name of the current
8846 function, as a string. The first of these is @code{__func__}, which
8847 is part of the C99 standard:
8849 The identifier @code{__func__} is implicitly declared by the translator
8850 as if, immediately following the opening brace of each function
8851 definition, the declaration
8854 static const char __func__[] = "function-name";
8858 appeared, where function-name is the name of the lexically-enclosing
8859 function. This name is the unadorned name of the function.
8861 @code{__FUNCTION__} is another name for @code{__func__}, provided for
8862 backward compatibility with old versions of GCC.
8864 In C, @code{__PRETTY_FUNCTION__} is yet another name for
8865 @code{__func__}. However, in C++, @code{__PRETTY_FUNCTION__} contains
8866 the type signature of the function as well as its bare name. For
8867 example, this program:
8871 extern int printf (char *, ...);
8878 printf ("__FUNCTION__ = %s\n", __FUNCTION__);
8879 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
8897 __PRETTY_FUNCTION__ = void a::sub(int)
8900 These identifiers are variables, not preprocessor macros, and may not
8901 be used to initialize @code{char} arrays or be concatenated with other string
8904 @node Return Address
8905 @section Getting the Return or Frame Address of a Function
8907 These functions may be used to get information about the callers of a
8910 @deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
8911 This function returns the return address of the current function, or of
8912 one of its callers. The @var{level} argument is number of frames to
8913 scan up the call stack. A value of @code{0} yields the return address
8914 of the current function, a value of @code{1} yields the return address
8915 of the caller of the current function, and so forth. When inlining
8916 the expected behavior is that the function returns the address of
8917 the function that is returned to. To work around this behavior use
8918 the @code{noinline} function attribute.
8920 The @var{level} argument must be a constant integer.
8922 On some machines it may be impossible to determine the return address of
8923 any function other than the current one; in such cases, or when the top
8924 of the stack has been reached, this function returns @code{0} or a
8925 random value. In addition, @code{__builtin_frame_address} may be used
8926 to determine if the top of the stack has been reached.
8928 Additional post-processing of the returned value may be needed, see
8929 @code{__builtin_extract_return_addr}.
8931 Calling this function with a nonzero argument can have unpredictable
8932 effects, including crashing the calling program. As a result, calls
8933 that are considered unsafe are diagnosed when the @option{-Wframe-address}
8934 option is in effect. Such calls should only be made in debugging
8938 @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr})
8939 The address as returned by @code{__builtin_return_address} may have to be fed
8940 through this function to get the actual encoded address. For example, on the
8941 31-bit S/390 platform the highest bit has to be masked out, or on SPARC
8942 platforms an offset has to be added for the true next instruction to be
8945 If no fixup is needed, this function simply passes through @var{addr}.
8948 @deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr})
8949 This function does the reverse of @code{__builtin_extract_return_addr}.
8952 @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
8953 This function is similar to @code{__builtin_return_address}, but it
8954 returns the address of the function frame rather than the return address
8955 of the function. Calling @code{__builtin_frame_address} with a value of
8956 @code{0} yields the frame address of the current function, a value of
8957 @code{1} yields the frame address of the caller of the current function,
8960 The frame is the area on the stack that holds local variables and saved
8961 registers. The frame address is normally the address of the first word
8962 pushed on to the stack by the function. However, the exact definition
8963 depends upon the processor and the calling convention. If the processor
8964 has a dedicated frame pointer register, and the function has a frame,
8965 then @code{__builtin_frame_address} returns the value of the frame
8968 On some machines it may be impossible to determine the frame address of
8969 any function other than the current one; in such cases, or when the top
8970 of the stack has been reached, this function returns @code{0} if
8971 the first frame pointer is properly initialized by the startup code.
8973 Calling this function with a nonzero argument can have unpredictable
8974 effects, including crashing the calling program. As a result, calls
8975 that are considered unsafe are diagnosed when the @option{-Wframe-address}
8976 option is in effect. Such calls should only be made in debugging
8980 @node Vector Extensions
8981 @section Using Vector Instructions through Built-in Functions
8983 On some targets, the instruction set contains SIMD vector instructions which
8984 operate on multiple values contained in one large register at the same time.
8985 For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used
8988 The first step in using these extensions is to provide the necessary data
8989 types. This should be done using an appropriate @code{typedef}:
8992 typedef int v4si __attribute__ ((vector_size (16)));
8996 The @code{int} type specifies the base type, while the attribute specifies
8997 the vector size for the variable, measured in bytes. For example, the
8998 declaration above causes the compiler to set the mode for the @code{v4si}
8999 type to be 16 bytes wide and divided into @code{int} sized units. For
9000 a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
9001 corresponding mode of @code{foo} is @acronym{V4SI}.
9003 The @code{vector_size} attribute is only applicable to integral and
9004 float scalars, although arrays, pointers, and function return values
9005 are allowed in conjunction with this construct. Only sizes that are
9006 a power of two are currently allowed.
9008 All the basic integer types can be used as base types, both as signed
9009 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
9010 @code{long long}. In addition, @code{float} and @code{double} can be
9011 used to build floating-point vector types.
9013 Specifying a combination that is not valid for the current architecture
9014 causes GCC to synthesize the instructions using a narrower mode.
9015 For example, if you specify a variable of type @code{V4SI} and your
9016 architecture does not allow for this specific SIMD type, GCC
9017 produces code that uses 4 @code{SIs}.
9019 The types defined in this manner can be used with a subset of normal C
9020 operations. Currently, GCC allows using the following operators
9021 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
9023 The operations behave like C++ @code{valarrays}. Addition is defined as
9024 the addition of the corresponding elements of the operands. For
9025 example, in the code below, each of the 4 elements in @var{a} is
9026 added to the corresponding 4 elements in @var{b} and the resulting
9027 vector is stored in @var{c}.
9030 typedef int v4si __attribute__ ((vector_size (16)));
9037 Subtraction, multiplication, division, and the logical operations
9038 operate in a similar manner. Likewise, the result of using the unary
9039 minus or complement operators on a vector type is a vector whose
9040 elements are the negative or complemented values of the corresponding
9041 elements in the operand.
9043 It is possible to use shifting operators @code{<<}, @code{>>} on
9044 integer-type vectors. The operation is defined as following: @code{@{a0,
9045 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
9046 @dots{}, an >> bn@}}@. Vector operands must have the same number of
9049 For convenience, it is allowed to use a binary vector operation
9050 where one operand is a scalar. In that case the compiler transforms
9051 the scalar operand into a vector where each element is the scalar from
9052 the operation. The transformation happens only if the scalar could be
9053 safely converted to the vector-element type.
9054 Consider the following code.
9057 typedef int v4si __attribute__ ((vector_size (16)));
9062 a = b + 1; /* a = b + @{1,1,1,1@}; */
9063 a = 2 * b; /* a = @{2,2,2,2@} * b; */
9065 a = l + a; /* Error, cannot convert long to int. */
9068 Vectors can be subscripted as if the vector were an array with
9069 the same number of elements and base type. Out of bound accesses
9070 invoke undefined behavior at run time. Warnings for out of bound
9071 accesses for vector subscription can be enabled with
9072 @option{-Warray-bounds}.
9074 Vector comparison is supported with standard comparison
9075 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
9076 vector expressions of integer-type or real-type. Comparison between
9077 integer-type vectors and real-type vectors are not supported. The
9078 result of the comparison is a vector of the same width and number of
9079 elements as the comparison operands with a signed integral element
9082 Vectors are compared element-wise producing 0 when comparison is false
9083 and -1 (constant of the appropriate type where all bits are set)
9084 otherwise. Consider the following example.
9087 typedef int v4si __attribute__ ((vector_size (16)));
9089 v4si a = @{1,2,3,4@};
9090 v4si b = @{3,2,1,4@};
9093 c = a > b; /* The result would be @{0, 0,-1, 0@} */
9094 c = a == b; /* The result would be @{0,-1, 0,-1@} */
9097 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
9098 @code{b} and @code{c} are vectors of the same type and @code{a} is an
9099 integer vector with the same number of elements of the same size as @code{b}
9100 and @code{c}, computes all three arguments and creates a vector
9101 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
9102 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
9103 As in the case of binary operations, this syntax is also accepted when
9104 one of @code{b} or @code{c} is a scalar that is then transformed into a
9105 vector. If both @code{b} and @code{c} are scalars and the type of
9106 @code{true?b:c} has the same size as the element type of @code{a}, then
9107 @code{b} and @code{c} are converted to a vector type whose elements have
9108 this type and with the same number of elements as @code{a}.
9110 In C++, the logic operators @code{!, &&, ||} are available for vectors.
9111 @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
9112 @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
9113 For mixed operations between a scalar @code{s} and a vector @code{v},
9114 @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
9115 short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
9117 Vector shuffling is available using functions
9118 @code{__builtin_shuffle (vec, mask)} and
9119 @code{__builtin_shuffle (vec0, vec1, mask)}.
9120 Both functions construct a permutation of elements from one or two
9121 vectors and return a vector of the same type as the input vector(s).
9122 The @var{mask} is an integral vector with the same width (@var{W})
9123 and element count (@var{N}) as the output vector.
9125 The elements of the input vectors are numbered in memory ordering of
9126 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
9127 elements of @var{mask} are considered modulo @var{N} in the single-operand
9128 case and modulo @math{2*@var{N}} in the two-operand case.
9130 Consider the following example,
9133 typedef int v4si __attribute__ ((vector_size (16)));
9135 v4si a = @{1,2,3,4@};
9136 v4si b = @{5,6,7,8@};
9137 v4si mask1 = @{0,1,1,3@};
9138 v4si mask2 = @{0,4,2,5@};
9141 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
9142 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
9145 Note that @code{__builtin_shuffle} is intentionally semantically
9146 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
9148 You can declare variables and use them in function calls and returns, as
9149 well as in assignments and some casts. You can specify a vector type as
9150 a return type for a function. Vector types can also be used as function
9151 arguments. It is possible to cast from one vector type to another,
9152 provided they are of the same size (in fact, you can also cast vectors
9153 to and from other datatypes of the same size).
9155 You cannot operate between vectors of different lengths or different
9156 signedness without a cast.
9159 @section Support for @code{offsetof}
9160 @findex __builtin_offsetof
9162 GCC implements for both C and C++ a syntactic extension to implement
9163 the @code{offsetof} macro.
9167 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
9169 offsetof_member_designator:
9171 | offsetof_member_designator "." @code{identifier}
9172 | offsetof_member_designator "[" @code{expr} "]"
9175 This extension is sufficient such that
9178 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
9182 is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
9183 may be dependent. In either case, @var{member} may consist of a single
9184 identifier, or a sequence of member accesses and array references.
9186 @node __sync Builtins
9187 @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access
9189 The following built-in functions
9190 are intended to be compatible with those described
9191 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
9192 section 7.4. As such, they depart from normal GCC practice by not using
9193 the @samp{__builtin_} prefix and also by being overloaded so that they
9194 work on multiple types.
9196 The definition given in the Intel documentation allows only for the use of
9197 the types @code{int}, @code{long}, @code{long long} or their unsigned
9198 counterparts. GCC allows any integral scalar or pointer type that is
9199 1, 2, 4 or 8 bytes in length.
9201 These functions are implemented in terms of the @samp{__atomic}
9202 builtins (@pxref{__atomic Builtins}). They should not be used for new
9203 code which should use the @samp{__atomic} builtins instead.
9205 Not all operations are supported by all target processors. If a particular
9206 operation cannot be implemented on the target processor, a warning is
9207 generated and a call to an external function is generated. The external
9208 function carries the same name as the built-in version,
9209 with an additional suffix
9210 @samp{_@var{n}} where @var{n} is the size of the data type.
9212 @c ??? Should we have a mechanism to suppress this warning? This is almost
9213 @c useful for implementing the operation under the control of an external
9216 In most cases, these built-in functions are considered a @dfn{full barrier}.
9218 no memory operand is moved across the operation, either forward or
9219 backward. Further, instructions are issued as necessary to prevent the
9220 processor from speculating loads across the operation and from queuing stores
9221 after the operation.
9223 All of the routines are described in the Intel documentation to take
9224 ``an optional list of variables protected by the memory barrier''. It's
9225 not clear what is meant by that; it could mean that @emph{only} the
9226 listed variables are protected, or it could mean a list of additional
9227 variables to be protected. The list is ignored by GCC which treats it as
9228 empty. GCC interprets an empty list as meaning that all globally
9229 accessible variables should be protected.
9232 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
9233 @itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
9234 @itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
9235 @itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
9236 @itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
9237 @itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
9238 @findex __sync_fetch_and_add
9239 @findex __sync_fetch_and_sub
9240 @findex __sync_fetch_and_or
9241 @findex __sync_fetch_and_and
9242 @findex __sync_fetch_and_xor
9243 @findex __sync_fetch_and_nand
9244 These built-in functions perform the operation suggested by the name, and
9245 returns the value that had previously been in memory. That is,
9248 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
9249 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
9252 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
9253 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
9255 @item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
9256 @itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
9257 @itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
9258 @itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
9259 @itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
9260 @itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
9261 @findex __sync_add_and_fetch
9262 @findex __sync_sub_and_fetch
9263 @findex __sync_or_and_fetch
9264 @findex __sync_and_and_fetch
9265 @findex __sync_xor_and_fetch
9266 @findex __sync_nand_and_fetch
9267 These built-in functions perform the operation suggested by the name, and
9268 return the new value. That is,
9271 @{ *ptr @var{op}= value; return *ptr; @}
9272 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand
9275 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
9276 as @code{*ptr = ~(*ptr & value)} instead of
9277 @code{*ptr = ~*ptr & value}.
9279 @item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
9280 @itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
9281 @findex __sync_bool_compare_and_swap
9282 @findex __sync_val_compare_and_swap
9283 These built-in functions perform an atomic compare and swap.
9284 That is, if the current
9285 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
9288 The ``bool'' version returns true if the comparison is successful and
9289 @var{newval} is written. The ``val'' version returns the contents
9290 of @code{*@var{ptr}} before the operation.
9292 @item __sync_synchronize (...)
9293 @findex __sync_synchronize
9294 This built-in function issues a full memory barrier.
9296 @item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
9297 @findex __sync_lock_test_and_set
9298 This built-in function, as described by Intel, is not a traditional test-and-set
9299 operation, but rather an atomic exchange operation. It writes @var{value}
9300 into @code{*@var{ptr}}, and returns the previous contents of
9303 Many targets have only minimal support for such locks, and do not support
9304 a full exchange operation. In this case, a target may support reduced
9305 functionality here by which the @emph{only} valid value to store is the
9306 immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
9307 is implementation defined.
9309 This built-in function is not a full barrier,
9310 but rather an @dfn{acquire barrier}.
9311 This means that references after the operation cannot move to (or be
9312 speculated to) before the operation, but previous memory stores may not
9313 be globally visible yet, and previous memory loads may not yet be
9316 @item void __sync_lock_release (@var{type} *ptr, ...)
9317 @findex __sync_lock_release
9318 This built-in function releases the lock acquired by
9319 @code{__sync_lock_test_and_set}.
9320 Normally this means writing the constant 0 to @code{*@var{ptr}}.
9322 This built-in function is not a full barrier,
9323 but rather a @dfn{release barrier}.
9324 This means that all previous memory stores are globally visible, and all
9325 previous memory loads have been satisfied, but following memory reads
9326 are not prevented from being speculated to before the barrier.
9329 @node __atomic Builtins
9330 @section Built-in Functions for Memory Model Aware Atomic Operations
9332 The following built-in functions approximately match the requirements
9333 for the C++11 memory model. They are all
9334 identified by being prefixed with @samp{__atomic} and most are
9335 overloaded so that they work with multiple types.
9337 These functions are intended to replace the legacy @samp{__sync}
9338 builtins. The main difference is that the memory order that is requested
9339 is a parameter to the functions. New code should always use the
9340 @samp{__atomic} builtins rather than the @samp{__sync} builtins.
9342 Note that the @samp{__atomic} builtins assume that programs will
9343 conform to the C++11 memory model. In particular, they assume
9344 that programs are free of data races. See the C++11 standard for
9345 detailed requirements.
9347 The @samp{__atomic} builtins can be used with any integral scalar or
9348 pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral
9349 types are also allowed if @samp{__int128} (@pxref{__int128}) is
9350 supported by the architecture.
9352 The four non-arithmetic functions (load, store, exchange, and
9353 compare_exchange) all have a generic version as well. This generic
9354 version works on any data type. It uses the lock-free built-in function
9355 if the specific data type size makes that possible; otherwise, an
9356 external call is left to be resolved at run time. This external call is
9357 the same format with the addition of a @samp{size_t} parameter inserted
9358 as the first parameter indicating the size of the object being pointed to.
9359 All objects must be the same size.
9361 There are 6 different memory orders that can be specified. These map
9362 to the C++11 memory orders with the same names, see the C++11 standard
9363 or the @uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki
9364 on atomic synchronization} for detailed definitions. Individual
9365 targets may also support additional memory orders for use on specific
9366 architectures. Refer to the target documentation for details of
9369 An atomic operation can both constrain code motion and
9370 be mapped to hardware instructions for synchronization between threads
9371 (e.g., a fence). To which extent this happens is controlled by the
9372 memory orders, which are listed here in approximately ascending order of
9373 strength. The description of each memory order is only meant to roughly
9374 illustrate the effects and is not a specification; see the C++11
9375 memory model for precise semantics.
9378 @item __ATOMIC_RELAXED
9379 Implies no inter-thread ordering constraints.
9380 @item __ATOMIC_CONSUME
9381 This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE}
9382 memory order because of a deficiency in C++11's semantics for
9383 @code{memory_order_consume}.
9384 @item __ATOMIC_ACQUIRE
9385 Creates an inter-thread happens-before constraint from the release (or
9386 stronger) semantic store to this acquire load. Can prevent hoisting
9387 of code to before the operation.
9388 @item __ATOMIC_RELEASE
9389 Creates an inter-thread happens-before constraint to acquire (or stronger)
9390 semantic loads that read from this release store. Can prevent sinking
9391 of code to after the operation.
9392 @item __ATOMIC_ACQ_REL
9393 Combines the effects of both @code{__ATOMIC_ACQUIRE} and
9394 @code{__ATOMIC_RELEASE}.
9395 @item __ATOMIC_SEQ_CST
9396 Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations.
9399 Note that in the C++11 memory model, @emph{fences} (e.g.,
9400 @samp{__atomic_thread_fence}) take effect in combination with other
9401 atomic operations on specific memory locations (e.g., atomic loads);
9402 operations on specific memory locations do not necessarily affect other
9403 operations in the same way.
9405 Target architectures are encouraged to provide their own patterns for
9406 each of the atomic built-in functions. If no target is provided, the original
9407 non-memory model set of @samp{__sync} atomic built-in functions are
9408 used, along with any required synchronization fences surrounding it in
9409 order to achieve the proper behavior. Execution in this case is subject
9410 to the same restrictions as those built-in functions.
9412 If there is no pattern or mechanism to provide a lock-free instruction
9413 sequence, a call is made to an external routine with the same parameters
9414 to be resolved at run time.
9416 When implementing patterns for these built-in functions, the memory order
9417 parameter can be ignored as long as the pattern implements the most
9418 restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory
9419 orders execute correctly with this memory order but they may not execute as
9420 efficiently as they could with a more appropriate implementation of the
9421 relaxed requirements.
9423 Note that the C++11 standard allows for the memory order parameter to be
9424 determined at run time rather than at compile time. These built-in
9425 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
9426 than invoke a runtime library call or inline a switch statement. This is
9427 standard compliant, safe, and the simplest approach for now.
9429 The memory order parameter is a signed int, but only the lower 16 bits are
9430 reserved for the memory order. The remainder of the signed int is reserved
9431 for target use and should be 0. Use of the predefined atomic values
9432 ensures proper usage.
9434 @deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder)
9435 This built-in function implements an atomic load operation. It returns the
9436 contents of @code{*@var{ptr}}.
9438 The valid memory order variants are
9439 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
9440 and @code{__ATOMIC_CONSUME}.
9444 @deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder)
9445 This is the generic version of an atomic load. It returns the
9446 contents of @code{*@var{ptr}} in @code{*@var{ret}}.
9450 @deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder)
9451 This built-in function implements an atomic store operation. It writes
9452 @code{@var{val}} into @code{*@var{ptr}}.
9454 The valid memory order variants are
9455 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
9459 @deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder)
9460 This is the generic version of an atomic store. It stores the value
9461 of @code{*@var{val}} into @code{*@var{ptr}}.
9465 @deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder)
9466 This built-in function implements an atomic exchange operation. It writes
9467 @var{val} into @code{*@var{ptr}}, and returns the previous contents of
9470 The valid memory order variants are
9471 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
9472 @code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}.
9476 @deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder)
9477 This is the generic version of an atomic exchange. It stores the
9478 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
9479 of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
9483 @deftypefn {Built-in Function} bool __atomic_compare_exchange_n (@var{type} *ptr, @var{type} *expected, @var{type} desired, bool weak, int success_memorder, int failure_memorder)
9484 This built-in function implements an atomic compare and exchange operation.
9485 This compares the contents of @code{*@var{ptr}} with the contents of
9486 @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write}
9487 operation that writes @var{desired} into @code{*@var{ptr}}. If they are not
9488 equal, the operation is a @emph{read} and the current contents of
9489 @code{*@var{ptr}} is written into @code{*@var{expected}}. @var{weak} is true
9490 for weak compare_exchange, and false for the strong variation. Many targets
9491 only offer the strong variation and ignore the parameter. When in doubt, use
9492 the strong variation.
9494 True is returned if @var{desired} is written into
9495 @code{*@var{ptr}} and the operation is considered to conform to the
9496 memory order specified by @var{success_memorder}. There are no
9497 restrictions on what memory order can be used here.
9499 False is returned otherwise, and the operation is considered to conform
9500 to @var{failure_memorder}. This memory order cannot be
9501 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
9502 stronger order than that specified by @var{success_memorder}.
9506 @deftypefn {Built-in Function} bool __atomic_compare_exchange (@var{type} *ptr, @var{type} *expected, @var{type} *desired, bool weak, int success_memorder, int failure_memorder)
9507 This built-in function implements the generic version of
9508 @code{__atomic_compare_exchange}. The function is virtually identical to
9509 @code{__atomic_compare_exchange_n}, except the desired value is also a
9514 @deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder)
9515 @deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder)
9516 @deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder)
9517 @deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder)
9518 @deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder)
9519 @deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder)
9520 These built-in functions perform the operation suggested by the name, and
9521 return the result of the operation. That is,
9524 @{ *ptr @var{op}= val; return *ptr; @}
9527 All memory orders are valid.
9531 @deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder)
9532 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder)
9533 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder)
9534 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder)
9535 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder)
9536 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder)
9537 These built-in functions perform the operation suggested by the name, and
9538 return the value that had previously been in @code{*@var{ptr}}. That is,
9541 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
9544 All memory orders are valid.
9548 @deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder)
9550 This built-in function performs an atomic test-and-set operation on
9551 the byte at @code{*@var{ptr}}. The byte is set to some implementation
9552 defined nonzero ``set'' value and the return value is @code{true} if and only
9553 if the previous contents were ``set''.
9554 It should be only used for operands of type @code{bool} or @code{char}. For
9555 other types only part of the value may be set.
9557 All memory orders are valid.
9561 @deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder)
9563 This built-in function performs an atomic clear operation on
9564 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
9565 It should be only used for operands of type @code{bool} or @code{char} and
9566 in conjunction with @code{__atomic_test_and_set}.
9567 For other types it may only clear partially. If the type is not @code{bool}
9568 prefer using @code{__atomic_store}.
9570 The valid memory order variants are
9571 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
9572 @code{__ATOMIC_RELEASE}.
9576 @deftypefn {Built-in Function} void __atomic_thread_fence (int memorder)
9578 This built-in function acts as a synchronization fence between threads
9579 based on the specified memory order.
9581 All memory orders are valid.
9585 @deftypefn {Built-in Function} void __atomic_signal_fence (int memorder)
9587 This built-in function acts as a synchronization fence between a thread
9588 and signal handlers based in the same thread.
9590 All memory orders are valid.
9594 @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr)
9596 This built-in function returns true if objects of @var{size} bytes always
9597 generate lock-free atomic instructions for the target architecture.
9598 @var{size} must resolve to a compile-time constant and the result also
9599 resolves to a compile-time constant.
9601 @var{ptr} is an optional pointer to the object that may be used to determine
9602 alignment. A value of 0 indicates typical alignment should be used. The
9603 compiler may also ignore this parameter.
9606 if (_atomic_always_lock_free (sizeof (long long), 0))
9611 @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
9613 This built-in function returns true if objects of @var{size} bytes always
9614 generate lock-free atomic instructions for the target architecture. If
9615 the built-in function is not known to be lock-free, a call is made to a
9616 runtime routine named @code{__atomic_is_lock_free}.
9618 @var{ptr} is an optional pointer to the object that may be used to determine
9619 alignment. A value of 0 indicates typical alignment should be used. The
9620 compiler may also ignore this parameter.
9623 @node Integer Overflow Builtins
9624 @section Built-in Functions to Perform Arithmetic with Overflow Checking
9626 The following built-in functions allow performing simple arithmetic operations
9627 together with checking whether the operations overflowed.
9629 @deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
9630 @deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res)
9631 @deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res)
9632 @deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long int *res)
9633 @deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)
9634 @deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
9635 @deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res)
9637 These built-in functions promote the first two operands into infinite precision signed
9638 type and perform addition on those promoted operands. The result is then
9639 cast to the type the third pointer argument points to and stored there.
9640 If the stored result is equal to the infinite precision result, the built-in
9641 functions return false, otherwise they return true. As the addition is
9642 performed in infinite signed precision, these built-in functions have fully defined
9643 behavior for all argument values.
9645 The first built-in function allows arbitrary integral types for operands and
9646 the result type must be pointer to some integer type, the rest of the built-in
9647 functions have explicit integer types.
9649 The compiler will attempt to use hardware instructions to implement
9650 these built-in functions where possible, like conditional jump on overflow
9651 after addition, conditional jump on carry etc.
9655 @deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
9656 @deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res)
9657 @deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res)
9658 @deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long int *res)
9659 @deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)
9660 @deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
9661 @deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res)
9663 These built-in functions are similar to the add overflow checking built-in
9664 functions above, except they perform subtraction, subtract the second argument
9665 from the first one, instead of addition.
9669 @deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
9670 @deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res)
9671 @deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res)
9672 @deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long int *res)
9673 @deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)
9674 @deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
9675 @deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res)
9677 These built-in functions are similar to the add overflow checking built-in
9678 functions above, except they perform multiplication, instead of addition.
9682 @node x86 specific memory model extensions for transactional memory
9683 @section x86-Specific Memory Model Extensions for Transactional Memory
9685 The x86 architecture supports additional memory ordering flags
9686 to mark lock critical sections for hardware lock elision.
9687 These must be specified in addition to an existing memory order to
9691 @item __ATOMIC_HLE_ACQUIRE
9692 Start lock elision on a lock variable.
9693 Memory order must be @code{__ATOMIC_ACQUIRE} or stronger.
9694 @item __ATOMIC_HLE_RELEASE
9695 End lock elision on a lock variable.
9696 Memory order must be @code{__ATOMIC_RELEASE} or stronger.
9699 When a lock acquire fails, it is required for good performance to abort
9700 the transaction quickly. This can be done with a @code{_mm_pause}.
9703 #include <immintrin.h> // For _mm_pause
9707 /* Acquire lock with lock elision */
9708 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
9709 _mm_pause(); /* Abort failed transaction */
9711 /* Free lock with lock elision */
9712 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
9715 @node Object Size Checking
9716 @section Object Size Checking Built-in Functions
9717 @findex __builtin_object_size
9718 @findex __builtin___memcpy_chk
9719 @findex __builtin___mempcpy_chk
9720 @findex __builtin___memmove_chk
9721 @findex __builtin___memset_chk
9722 @findex __builtin___strcpy_chk
9723 @findex __builtin___stpcpy_chk
9724 @findex __builtin___strncpy_chk
9725 @findex __builtin___strcat_chk
9726 @findex __builtin___strncat_chk
9727 @findex __builtin___sprintf_chk
9728 @findex __builtin___snprintf_chk
9729 @findex __builtin___vsprintf_chk
9730 @findex __builtin___vsnprintf_chk
9731 @findex __builtin___printf_chk
9732 @findex __builtin___vprintf_chk
9733 @findex __builtin___fprintf_chk
9734 @findex __builtin___vfprintf_chk
9736 GCC implements a limited buffer overflow protection mechanism
9737 that can prevent some buffer overflow attacks.
9739 @deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type})
9740 is a built-in construct that returns a constant number of bytes from
9741 @var{ptr} to the end of the object @var{ptr} pointer points to
9742 (if known at compile time). @code{__builtin_object_size} never evaluates
9743 its arguments for side-effects. If there are any side-effects in them, it
9744 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
9745 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
9746 point to and all of them are known at compile time, the returned number
9747 is the maximum of remaining byte counts in those objects if @var{type} & 2 is
9748 0 and minimum if nonzero. If it is not possible to determine which objects
9749 @var{ptr} points to at compile time, @code{__builtin_object_size} should
9750 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
9751 for @var{type} 2 or 3.
9753 @var{type} is an integer constant from 0 to 3. If the least significant
9754 bit is clear, objects are whole variables, if it is set, a closest
9755 surrounding subobject is considered the object a pointer points to.
9756 The second bit determines if maximum or minimum of remaining bytes
9760 struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
9761 char *p = &var.buf1[1], *q = &var.b;
9763 /* Here the object p points to is var. */
9764 assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
9765 /* The subobject p points to is var.buf1. */
9766 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
9767 /* The object q points to is var. */
9768 assert (__builtin_object_size (q, 0)
9769 == (char *) (&var + 1) - (char *) &var.b);
9770 /* The subobject q points to is var.b. */
9771 assert (__builtin_object_size (q, 1) == sizeof (var.b));
9775 There are built-in functions added for many common string operation
9776 functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
9777 built-in is provided. This built-in has an additional last argument,
9778 which is the number of bytes remaining in object the @var{dest}
9779 argument points to or @code{(size_t) -1} if the size is not known.
9781 The built-in functions are optimized into the normal string functions
9782 like @code{memcpy} if the last argument is @code{(size_t) -1} or if
9783 it is known at compile time that the destination object will not
9784 be overflown. If the compiler can determine at compile time the
9785 object will be always overflown, it issues a warning.
9787 The intended use can be e.g.@:
9791 #define bos0(dest) __builtin_object_size (dest, 0)
9792 #define memcpy(dest, src, n) \
9793 __builtin___memcpy_chk (dest, src, n, bos0 (dest))
9797 /* It is unknown what object p points to, so this is optimized
9798 into plain memcpy - no checking is possible. */
9799 memcpy (p, "abcde", n);
9800 /* Destination is known and length too. It is known at compile
9801 time there will be no overflow. */
9802 memcpy (&buf[5], "abcde", 5);
9803 /* Destination is known, but the length is not known at compile time.
9804 This will result in __memcpy_chk call that can check for overflow
9806 memcpy (&buf[5], "abcde", n);
9807 /* Destination is known and it is known at compile time there will
9808 be overflow. There will be a warning and __memcpy_chk call that
9809 will abort the program at run time. */
9810 memcpy (&buf[6], "abcde", 5);
9813 Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
9814 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
9815 @code{strcat} and @code{strncat}.
9817 There are also checking built-in functions for formatted output functions.
9819 int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
9820 int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
9821 const char *fmt, ...);
9822 int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
9824 int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
9825 const char *fmt, va_list ap);
9828 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
9829 etc.@: functions and can contain implementation specific flags on what
9830 additional security measures the checking function might take, such as
9831 handling @code{%n} differently.
9833 The @var{os} argument is the object size @var{s} points to, like in the
9834 other built-in functions. There is a small difference in the behavior
9835 though, if @var{os} is @code{(size_t) -1}, the built-in functions are
9836 optimized into the non-checking functions only if @var{flag} is 0, otherwise
9837 the checking function is called with @var{os} argument set to
9840 In addition to this, there are checking built-in functions
9841 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
9842 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
9843 These have just one additional argument, @var{flag}, right before
9844 format string @var{fmt}. If the compiler is able to optimize them to
9845 @code{fputc} etc.@: functions, it does, otherwise the checking function
9846 is called and the @var{flag} argument passed to it.
9848 @node Pointer Bounds Checker builtins
9849 @section Pointer Bounds Checker Built-in Functions
9850 @cindex Pointer Bounds Checker builtins
9851 @findex __builtin___bnd_set_ptr_bounds
9852 @findex __builtin___bnd_narrow_ptr_bounds
9853 @findex __builtin___bnd_copy_ptr_bounds
9854 @findex __builtin___bnd_init_ptr_bounds
9855 @findex __builtin___bnd_null_ptr_bounds
9856 @findex __builtin___bnd_store_ptr_bounds
9857 @findex __builtin___bnd_chk_ptr_lbounds
9858 @findex __builtin___bnd_chk_ptr_ubounds
9859 @findex __builtin___bnd_chk_ptr_bounds
9860 @findex __builtin___bnd_get_ptr_lbound
9861 @findex __builtin___bnd_get_ptr_ubound
9863 GCC provides a set of built-in functions to control Pointer Bounds Checker
9864 instrumentation. Note that all Pointer Bounds Checker builtins can be used
9865 even if you compile with Pointer Bounds Checker off
9866 (@option{-fno-check-pointer-bounds}).
9867 The behavior may differ in such case as documented below.
9869 @deftypefn {Built-in Function} {void *} __builtin___bnd_set_ptr_bounds (const void *@var{q}, size_t @var{size})
9871 This built-in function returns a new pointer with the value of @var{q}, and
9872 associate it with the bounds [@var{q}, @var{q}+@var{size}-1]. With Pointer
9873 Bounds Checker off, the built-in function just returns the first argument.
9876 extern void *__wrap_malloc (size_t n)
9878 void *p = (void *)__real_malloc (n);
9879 if (!p) return __builtin___bnd_null_ptr_bounds (p);
9880 return __builtin___bnd_set_ptr_bounds (p, n);
9886 @deftypefn {Built-in Function} {void *} __builtin___bnd_narrow_ptr_bounds (const void *@var{p}, const void *@var{q}, size_t @var{size})
9888 This built-in function returns a new pointer with the value of @var{p}
9889 and associates it with the narrowed bounds formed by the intersection
9890 of bounds associated with @var{q} and the bounds
9891 [@var{p}, @var{p} + @var{size} - 1].
9892 With Pointer Bounds Checker off, the built-in function just returns the first
9896 void init_objects (object *objs, size_t size)
9899 /* Initialize objects one-by-one passing pointers with bounds of
9900 an object, not the full array of objects. */
9901 for (i = 0; i < size; i++)
9902 init_object (__builtin___bnd_narrow_ptr_bounds (objs + i, objs,
9909 @deftypefn {Built-in Function} {void *} __builtin___bnd_copy_ptr_bounds (const void *@var{q}, const void *@var{r})
9911 This built-in function returns a new pointer with the value of @var{q},
9912 and associates it with the bounds already associated with pointer @var{r}.
9913 With Pointer Bounds Checker off, the built-in function just returns the first
9917 /* Here is a way to get pointer to object's field but
9918 still with the full object's bounds. */
9919 int *field_ptr = __builtin___bnd_copy_ptr_bounds (&objptr->int_field,
9925 @deftypefn {Built-in Function} {void *} __builtin___bnd_init_ptr_bounds (const void *@var{q})
9927 This built-in function returns a new pointer with the value of @var{q}, and
9928 associates it with INIT (allowing full memory access) bounds. With Pointer
9929 Bounds Checker off, the built-in function just returns the first argument.
9933 @deftypefn {Built-in Function} {void *} __builtin___bnd_null_ptr_bounds (const void *@var{q})
9935 This built-in function returns a new pointer with the value of @var{q}, and
9936 associates it with NULL (allowing no memory access) bounds. With Pointer
9937 Bounds Checker off, the built-in function just returns the first argument.
9941 @deftypefn {Built-in Function} void __builtin___bnd_store_ptr_bounds (const void **@var{ptr_addr}, const void *@var{ptr_val})
9943 This built-in function stores the bounds associated with pointer @var{ptr_val}
9944 and location @var{ptr_addr} into Bounds Table. This can be useful to propagate
9945 bounds from legacy code without touching the associated pointer's memory when
9946 pointers are copied as integers. With Pointer Bounds Checker off, the built-in
9947 function call is ignored.
9951 @deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_lbounds (const void *@var{q})
9953 This built-in function checks if the pointer @var{q} is within the lower
9954 bound of its associated bounds. With Pointer Bounds Checker off, the built-in
9955 function call is ignored.
9958 extern void *__wrap_memset (void *dst, int c, size_t len)
9962 __builtin___bnd_chk_ptr_lbounds (dst);
9963 __builtin___bnd_chk_ptr_ubounds ((char *)dst + len - 1);
9964 __real_memset (dst, c, len);
9972 @deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_ubounds (const void *@var{q})
9974 This built-in function checks if the pointer @var{q} is within the upper
9975 bound of its associated bounds. With Pointer Bounds Checker off, the built-in
9976 function call is ignored.
9980 @deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_bounds (const void *@var{q}, size_t @var{size})
9982 This built-in function checks if [@var{q}, @var{q} + @var{size} - 1] is within
9983 the lower and upper bounds associated with @var{q}. With Pointer Bounds Checker
9984 off, the built-in function call is ignored.
9987 extern void *__wrap_memcpy (void *dst, const void *src, size_t n)
9991 __bnd_chk_ptr_bounds (dst, n);
9992 __bnd_chk_ptr_bounds (src, n);
9993 __real_memcpy (dst, src, n);
10001 @deftypefn {Built-in Function} {const void *} __builtin___bnd_get_ptr_lbound (const void *@var{q})
10003 This built-in function returns the lower bound associated
10004 with the pointer @var{q}, as a pointer value.
10005 This is useful for debugging using @code{printf}.
10006 With Pointer Bounds Checker off, the built-in function returns 0.
10009 void *lb = __builtin___bnd_get_ptr_lbound (q);
10010 void *ub = __builtin___bnd_get_ptr_ubound (q);
10011 printf ("q = %p lb(q) = %p ub(q) = %p", q, lb, ub);
10016 @deftypefn {Built-in Function} {const void *} __builtin___bnd_get_ptr_ubound (const void *@var{q})
10018 This built-in function returns the upper bound (which is a pointer) associated
10019 with the pointer @var{q}. With Pointer Bounds Checker off,
10020 the built-in function returns -1.
10024 @node Cilk Plus Builtins
10025 @section Cilk Plus C/C++ Language Extension Built-in Functions
10027 GCC provides support for the following built-in reduction functions if Cilk Plus
10028 is enabled. Cilk Plus can be enabled using the @option{-fcilkplus} flag.
10031 @item @code{__sec_implicit_index}
10032 @item @code{__sec_reduce}
10033 @item @code{__sec_reduce_add}
10034 @item @code{__sec_reduce_all_nonzero}
10035 @item @code{__sec_reduce_all_zero}
10036 @item @code{__sec_reduce_any_nonzero}
10037 @item @code{__sec_reduce_any_zero}
10038 @item @code{__sec_reduce_max}
10039 @item @code{__sec_reduce_min}
10040 @item @code{__sec_reduce_max_ind}
10041 @item @code{__sec_reduce_min_ind}
10042 @item @code{__sec_reduce_mul}
10043 @item @code{__sec_reduce_mutating}
10046 Further details and examples about these built-in functions are described
10047 in the Cilk Plus language manual which can be found at
10048 @uref{http://www.cilkplus.org}.
10050 @node Other Builtins
10051 @section Other Built-in Functions Provided by GCC
10052 @cindex built-in functions
10053 @findex __builtin_call_with_static_chain
10054 @findex __builtin_fpclassify
10055 @findex __builtin_isfinite
10056 @findex __builtin_isnormal
10057 @findex __builtin_isgreater
10058 @findex __builtin_isgreaterequal
10059 @findex __builtin_isinf_sign
10060 @findex __builtin_isless
10061 @findex __builtin_islessequal
10062 @findex __builtin_islessgreater
10063 @findex __builtin_isunordered
10064 @findex __builtin_powi
10065 @findex __builtin_powif
10066 @findex __builtin_powil
10224 @findex fprintf_unlocked
10226 @findex fputs_unlocked
10334 @findex nexttowardf
10335 @findex nexttowardl
10343 @findex printf_unlocked
10373 @findex signbitd128
10374 @findex significand
10375 @findex significandf
10376 @findex significandl
10404 @findex strncasecmp
10447 GCC provides a large number of built-in functions other than the ones
10448 mentioned above. Some of these are for internal use in the processing
10449 of exceptions or variable-length argument lists and are not
10450 documented here because they may change from time to time; we do not
10451 recommend general use of these functions.
10453 The remaining functions are provided for optimization purposes.
10455 With the exception of built-ins that have library equivalents such as
10456 the standard C library functions discussed below, or that expand to
10457 library calls, GCC built-in functions are always expanded inline and
10458 thus do not have corresponding entry points and their address cannot
10459 be obtained. Attempting to use them in an expression other than
10460 a function call results in a compile-time error.
10462 @opindex fno-builtin
10463 GCC includes built-in versions of many of the functions in the standard
10464 C library. These functions come in two forms: one whose names start with
10465 the @code{__builtin_} prefix, and the other without. Both forms have the
10466 same type (including prototype), the same address (when their address is
10467 taken), and the same meaning as the C library functions even if you specify
10468 the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these
10469 functions are only optimized in certain cases; if they are not optimized in
10470 a particular case, a call to the library function is emitted.
10474 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
10475 @option{-std=c99} or @option{-std=c11}), the functions
10476 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
10477 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
10478 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
10479 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
10480 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
10481 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
10482 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
10483 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
10484 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
10485 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
10486 @code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb},
10487 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
10488 @code{signbitd64}, @code{signbitd128}, @code{significandf},
10489 @code{significandl}, @code{significand}, @code{sincosf},
10490 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
10491 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
10492 @code{strndup}, @code{toascii}, @code{y0f}, @code{y0l}, @code{y0},
10493 @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
10495 may be handled as built-in functions.
10496 All these functions have corresponding versions
10497 prefixed with @code{__builtin_}, which may be used even in strict C90
10500 The ISO C99 functions
10501 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
10502 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
10503 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
10504 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
10505 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
10506 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
10507 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
10508 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
10509 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
10510 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
10511 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
10512 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
10513 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
10514 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
10515 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
10516 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
10517 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
10518 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
10519 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
10520 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
10521 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
10522 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
10523 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
10524 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
10525 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
10526 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
10527 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
10528 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
10529 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
10530 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
10531 @code{nextafterf}, @code{nextafterl}, @code{nextafter},
10532 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
10533 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
10534 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
10535 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
10536 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
10537 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
10538 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
10539 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
10540 are handled as built-in functions
10541 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
10543 There are also built-in versions of the ISO C99 functions
10544 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
10545 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
10546 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
10547 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
10548 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
10549 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
10550 @code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf},
10551 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
10552 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
10553 that are recognized in any mode since ISO C90 reserves these names for
10554 the purpose to which ISO C99 puts them. All these functions have
10555 corresponding versions prefixed with @code{__builtin_}.
10557 The ISO C94 functions
10558 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
10559 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
10560 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
10562 are handled as built-in functions
10563 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
10565 The ISO C90 functions
10566 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
10567 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
10568 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
10569 @code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf},
10570 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
10571 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
10572 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
10573 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
10574 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
10575 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
10576 @code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf},
10577 @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
10578 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
10579 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
10580 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
10581 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
10582 are all recognized as built-in functions unless
10583 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
10584 is specified for an individual function). All of these functions have
10585 corresponding versions prefixed with @code{__builtin_}.
10587 GCC provides built-in versions of the ISO C99 floating-point comparison
10588 macros that avoid raising exceptions for unordered operands. They have
10589 the same names as the standard macros ( @code{isgreater},
10590 @code{isgreaterequal}, @code{isless}, @code{islessequal},
10591 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
10592 prefixed. We intend for a library implementor to be able to simply
10593 @code{#define} each standard macro to its built-in equivalent.
10594 In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
10595 @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with
10596 @code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
10597 built-in functions appear both with and without the @code{__builtin_} prefix.
10599 @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
10601 You can use the built-in function @code{__builtin_types_compatible_p} to
10602 determine whether two types are the same.
10604 This built-in function returns 1 if the unqualified versions of the
10605 types @var{type1} and @var{type2} (which are types, not expressions) are
10606 compatible, 0 otherwise. The result of this built-in function can be
10607 used in integer constant expressions.
10609 This built-in function ignores top level qualifiers (e.g., @code{const},
10610 @code{volatile}). For example, @code{int} is equivalent to @code{const
10613 The type @code{int[]} and @code{int[5]} are compatible. On the other
10614 hand, @code{int} and @code{char *} are not compatible, even if the size
10615 of their types, on the particular architecture are the same. Also, the
10616 amount of pointer indirection is taken into account when determining
10617 similarity. Consequently, @code{short *} is not similar to
10618 @code{short **}. Furthermore, two types that are typedefed are
10619 considered compatible if their underlying types are compatible.
10621 An @code{enum} type is not considered to be compatible with another
10622 @code{enum} type even if both are compatible with the same integer
10623 type; this is what the C standard specifies.
10624 For example, @code{enum @{foo, bar@}} is not similar to
10625 @code{enum @{hot, dog@}}.
10627 You typically use this function in code whose execution varies
10628 depending on the arguments' types. For example:
10633 typeof (x) tmp = (x); \
10634 if (__builtin_types_compatible_p (typeof (x), long double)) \
10635 tmp = foo_long_double (tmp); \
10636 else if (__builtin_types_compatible_p (typeof (x), double)) \
10637 tmp = foo_double (tmp); \
10638 else if (__builtin_types_compatible_p (typeof (x), float)) \
10639 tmp = foo_float (tmp); \
10646 @emph{Note:} This construct is only available for C@.
10650 @deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})
10652 The @var{call_exp} expression must be a function call, and the
10653 @var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
10654 is passed to the function call in the target's static chain location.
10655 The result of builtin is the result of the function call.
10657 @emph{Note:} This builtin is only available for C@.
10658 This builtin can be used to call Go closures from C.
10662 @deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
10664 You can use the built-in function @code{__builtin_choose_expr} to
10665 evaluate code depending on the value of a constant expression. This
10666 built-in function returns @var{exp1} if @var{const_exp}, which is an
10667 integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
10669 This built-in function is analogous to the @samp{? :} operator in C,
10670 except that the expression returned has its type unaltered by promotion
10671 rules. Also, the built-in function does not evaluate the expression
10672 that is not chosen. For example, if @var{const_exp} evaluates to true,
10673 @var{exp2} is not evaluated even if it has side-effects.
10675 This built-in function can return an lvalue if the chosen argument is an
10678 If @var{exp1} is returned, the return type is the same as @var{exp1}'s
10679 type. Similarly, if @var{exp2} is returned, its return type is the same
10686 __builtin_choose_expr ( \
10687 __builtin_types_compatible_p (typeof (x), double), \
10689 __builtin_choose_expr ( \
10690 __builtin_types_compatible_p (typeof (x), float), \
10692 /* @r{The void expression results in a compile-time error} \
10693 @r{when assigning the result to something.} */ \
10697 @emph{Note:} This construct is only available for C@. Furthermore, the
10698 unused expression (@var{exp1} or @var{exp2} depending on the value of
10699 @var{const_exp}) may still generate syntax errors. This may change in
10704 @deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
10706 The built-in function @code{__builtin_complex} is provided for use in
10707 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
10708 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
10709 real binary floating-point type, and the result has the corresponding
10710 complex type with real and imaginary parts @var{real} and @var{imag}.
10711 Unlike @samp{@var{real} + I * @var{imag}}, this works even when
10712 infinities, NaNs and negative zeros are involved.
10716 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
10717 You can use the built-in function @code{__builtin_constant_p} to
10718 determine if a value is known to be constant at compile time and hence
10719 that GCC can perform constant-folding on expressions involving that
10720 value. The argument of the function is the value to test. The function
10721 returns the integer 1 if the argument is known to be a compile-time
10722 constant and 0 if it is not known to be a compile-time constant. A
10723 return of 0 does not indicate that the value is @emph{not} a constant,
10724 but merely that GCC cannot prove it is a constant with the specified
10725 value of the @option{-O} option.
10727 You typically use this function in an embedded application where
10728 memory is a critical resource. If you have some complex calculation,
10729 you may want it to be folded if it involves constants, but need to call
10730 a function if it does not. For example:
10733 #define Scale_Value(X) \
10734 (__builtin_constant_p (X) \
10735 ? ((X) * SCALE + OFFSET) : Scale (X))
10738 You may use this built-in function in either a macro or an inline
10739 function. However, if you use it in an inlined function and pass an
10740 argument of the function as the argument to the built-in, GCC
10741 never returns 1 when you call the inline function with a string constant
10742 or compound literal (@pxref{Compound Literals}) and does not return 1
10743 when you pass a constant numeric value to the inline function unless you
10744 specify the @option{-O} option.
10746 You may also use @code{__builtin_constant_p} in initializers for static
10747 data. For instance, you can write
10750 static const int table[] = @{
10751 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
10757 This is an acceptable initializer even if @var{EXPRESSION} is not a
10758 constant expression, including the case where
10759 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
10760 folded to a constant but @var{EXPRESSION} contains operands that are
10761 not otherwise permitted in a static initializer (for example,
10762 @code{0 && foo ()}). GCC must be more conservative about evaluating the
10763 built-in in this case, because it has no opportunity to perform
10767 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
10768 @opindex fprofile-arcs
10769 You may use @code{__builtin_expect} to provide the compiler with
10770 branch prediction information. In general, you should prefer to
10771 use actual profile feedback for this (@option{-fprofile-arcs}), as
10772 programmers are notoriously bad at predicting how their programs
10773 actually perform. However, there are applications in which this
10774 data is hard to collect.
10776 The return value is the value of @var{exp}, which should be an integral
10777 expression. The semantics of the built-in are that it is expected that
10778 @var{exp} == @var{c}. For example:
10781 if (__builtin_expect (x, 0))
10786 indicates that we do not expect to call @code{foo}, since
10787 we expect @code{x} to be zero. Since you are limited to integral
10788 expressions for @var{exp}, you should use constructions such as
10791 if (__builtin_expect (ptr != NULL, 1))
10796 when testing pointer or floating-point values.
10799 @deftypefn {Built-in Function} void __builtin_trap (void)
10800 This function causes the program to exit abnormally. GCC implements
10801 this function by using a target-dependent mechanism (such as
10802 intentionally executing an illegal instruction) or by calling
10803 @code{abort}. The mechanism used may vary from release to release so
10804 you should not rely on any particular implementation.
10807 @deftypefn {Built-in Function} void __builtin_unreachable (void)
10808 If control flow reaches the point of the @code{__builtin_unreachable},
10809 the program is undefined. It is useful in situations where the
10810 compiler cannot deduce the unreachability of the code.
10812 One such case is immediately following an @code{asm} statement that
10813 either never terminates, or one that transfers control elsewhere
10814 and never returns. In this example, without the
10815 @code{__builtin_unreachable}, GCC issues a warning that control
10816 reaches the end of a non-void function. It also generates code
10817 to return after the @code{asm}.
10820 int f (int c, int v)
10828 asm("jmp error_handler");
10829 __builtin_unreachable ();
10835 Because the @code{asm} statement unconditionally transfers control out
10836 of the function, control never reaches the end of the function
10837 body. The @code{__builtin_unreachable} is in fact unreachable and
10838 communicates this fact to the compiler.
10840 Another use for @code{__builtin_unreachable} is following a call a
10841 function that never returns but that is not declared
10842 @code{__attribute__((noreturn))}, as in this example:
10845 void function_that_never_returns (void);
10855 function_that_never_returns ();
10856 __builtin_unreachable ();
10863 @deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)
10864 This function returns its first argument, and allows the compiler
10865 to assume that the returned pointer is at least @var{align} bytes
10866 aligned. This built-in can have either two or three arguments,
10867 if it has three, the third argument should have integer type, and
10868 if it is nonzero means misalignment offset. For example:
10871 void *x = __builtin_assume_aligned (arg, 16);
10875 means that the compiler can assume @code{x}, set to @code{arg}, is at least
10876 16-byte aligned, while:
10879 void *x = __builtin_assume_aligned (arg, 32, 8);
10883 means that the compiler can assume for @code{x}, set to @code{arg}, that
10884 @code{(char *) x - 8} is 32-byte aligned.
10887 @deftypefn {Built-in Function} int __builtin_LINE ()
10888 This function is the equivalent to the preprocessor @code{__LINE__}
10889 macro and returns the line number of the invocation of the built-in.
10890 In a C++ default argument for a function @var{F}, it gets the line number of
10891 the call to @var{F}.
10894 @deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
10895 This function is the equivalent to the preprocessor @code{__FUNCTION__}
10896 macro and returns the function name the invocation of the built-in is in.
10899 @deftypefn {Built-in Function} {const char *} __builtin_FILE ()
10900 This function is the equivalent to the preprocessor @code{__FILE__}
10901 macro and returns the file name the invocation of the built-in is in.
10902 In a C++ default argument for a function @var{F}, it gets the file name of
10903 the call to @var{F}.
10906 @deftypefn {Built-in Function} void __builtin___clear_cache (char *@var{begin}, char *@var{end})
10907 This function is used to flush the processor's instruction cache for
10908 the region of memory between @var{begin} inclusive and @var{end}
10909 exclusive. Some targets require that the instruction cache be
10910 flushed, after modifying memory containing code, in order to obtain
10911 deterministic behavior.
10913 If the target does not require instruction cache flushes,
10914 @code{__builtin___clear_cache} has no effect. Otherwise either
10915 instructions are emitted in-line to clear the instruction cache or a
10916 call to the @code{__clear_cache} function in libgcc is made.
10919 @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
10920 This function is used to minimize cache-miss latency by moving data into
10921 a cache before it is accessed.
10922 You can insert calls to @code{__builtin_prefetch} into code for which
10923 you know addresses of data in memory that is likely to be accessed soon.
10924 If the target supports them, data prefetch instructions are generated.
10925 If the prefetch is done early enough before the access then the data will
10926 be in the cache by the time it is accessed.
10928 The value of @var{addr} is the address of the memory to prefetch.
10929 There are two optional arguments, @var{rw} and @var{locality}.
10930 The value of @var{rw} is a compile-time constant one or zero; one
10931 means that the prefetch is preparing for a write to the memory address
10932 and zero, the default, means that the prefetch is preparing for a read.
10933 The value @var{locality} must be a compile-time constant integer between
10934 zero and three. A value of zero means that the data has no temporal
10935 locality, so it need not be left in the cache after the access. A value
10936 of three means that the data has a high degree of temporal locality and
10937 should be left in all levels of cache possible. Values of one and two
10938 mean, respectively, a low or moderate degree of temporal locality. The
10942 for (i = 0; i < n; i++)
10944 a[i] = a[i] + b[i];
10945 __builtin_prefetch (&a[i+j], 1, 1);
10946 __builtin_prefetch (&b[i+j], 0, 1);
10951 Data prefetch does not generate faults if @var{addr} is invalid, but
10952 the address expression itself must be valid. For example, a prefetch
10953 of @code{p->next} does not fault if @code{p->next} is not a valid
10954 address, but evaluation faults if @code{p} is not a valid address.
10956 If the target does not support data prefetch, the address expression
10957 is evaluated if it includes side effects but no other code is generated
10958 and GCC does not issue a warning.
10961 @deftypefn {Built-in Function} double __builtin_huge_val (void)
10962 Returns a positive infinity, if supported by the floating-point format,
10963 else @code{DBL_MAX}. This function is suitable for implementing the
10964 ISO C macro @code{HUGE_VAL}.
10967 @deftypefn {Built-in Function} float __builtin_huge_valf (void)
10968 Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
10971 @deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
10972 Similar to @code{__builtin_huge_val}, except the return
10973 type is @code{long double}.
10976 @deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
10977 This built-in implements the C99 fpclassify functionality. The first
10978 five int arguments should be the target library's notion of the
10979 possible FP classes and are used for return values. They must be
10980 constant values and they must appear in this order: @code{FP_NAN},
10981 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
10982 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value
10983 to classify. GCC treats the last argument as type-generic, which
10984 means it does not do default promotion from float to double.
10987 @deftypefn {Built-in Function} double __builtin_inf (void)
10988 Similar to @code{__builtin_huge_val}, except a warning is generated
10989 if the target floating-point format does not support infinities.
10992 @deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
10993 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
10996 @deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
10997 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
11000 @deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
11001 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
11004 @deftypefn {Built-in Function} float __builtin_inff (void)
11005 Similar to @code{__builtin_inf}, except the return type is @code{float}.
11006 This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
11009 @deftypefn {Built-in Function} {long double} __builtin_infl (void)
11010 Similar to @code{__builtin_inf}, except the return
11011 type is @code{long double}.
11014 @deftypefn {Built-in Function} int __builtin_isinf_sign (...)
11015 Similar to @code{isinf}, except the return value is -1 for
11016 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
11017 Note while the parameter list is an
11018 ellipsis, this function only accepts exactly one floating-point
11019 argument. GCC treats this parameter as type-generic, which means it
11020 does not do default promotion from float to double.
11023 @deftypefn {Built-in Function} double __builtin_nan (const char *str)
11024 This is an implementation of the ISO C99 function @code{nan}.
11026 Since ISO C99 defines this function in terms of @code{strtod}, which we
11027 do not implement, a description of the parsing is in order. The string
11028 is parsed as by @code{strtol}; that is, the base is recognized by
11029 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
11030 in the significand such that the least significant bit of the number
11031 is at the least significant bit of the significand. The number is
11032 truncated to fit the significand field provided. The significand is
11033 forced to be a quiet NaN@.
11035 This function, if given a string literal all of which would have been
11036 consumed by @code{strtol}, is evaluated early enough that it is considered a
11037 compile-time constant.
11040 @deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
11041 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
11044 @deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
11045 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
11048 @deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
11049 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
11052 @deftypefn {Built-in Function} float __builtin_nanf (const char *str)
11053 Similar to @code{__builtin_nan}, except the return type is @code{float}.
11056 @deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
11057 Similar to @code{__builtin_nan}, except the return type is @code{long double}.
11060 @deftypefn {Built-in Function} double __builtin_nans (const char *str)
11061 Similar to @code{__builtin_nan}, except the significand is forced
11062 to be a signaling NaN@. The @code{nans} function is proposed by
11063 @uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
11066 @deftypefn {Built-in Function} float __builtin_nansf (const char *str)
11067 Similar to @code{__builtin_nans}, except the return type is @code{float}.
11070 @deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
11071 Similar to @code{__builtin_nans}, except the return type is @code{long double}.
11074 @deftypefn {Built-in Function} int __builtin_ffs (int x)
11075 Returns one plus the index of the least significant 1-bit of @var{x}, or
11076 if @var{x} is zero, returns zero.
11079 @deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
11080 Returns the number of leading 0-bits in @var{x}, starting at the most
11081 significant bit position. If @var{x} is 0, the result is undefined.
11084 @deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
11085 Returns the number of trailing 0-bits in @var{x}, starting at the least
11086 significant bit position. If @var{x} is 0, the result is undefined.
11089 @deftypefn {Built-in Function} int __builtin_clrsb (int x)
11090 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
11091 number of bits following the most significant bit that are identical
11092 to it. There are no special cases for 0 or other values.
11095 @deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
11096 Returns the number of 1-bits in @var{x}.
11099 @deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
11100 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
11104 @deftypefn {Built-in Function} int __builtin_ffsl (long)
11105 Similar to @code{__builtin_ffs}, except the argument type is
11109 @deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
11110 Similar to @code{__builtin_clz}, except the argument type is
11111 @code{unsigned long}.
11114 @deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
11115 Similar to @code{__builtin_ctz}, except the argument type is
11116 @code{unsigned long}.
11119 @deftypefn {Built-in Function} int __builtin_clrsbl (long)
11120 Similar to @code{__builtin_clrsb}, except the argument type is
11124 @deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
11125 Similar to @code{__builtin_popcount}, except the argument type is
11126 @code{unsigned long}.
11129 @deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
11130 Similar to @code{__builtin_parity}, except the argument type is
11131 @code{unsigned long}.
11134 @deftypefn {Built-in Function} int __builtin_ffsll (long long)
11135 Similar to @code{__builtin_ffs}, except the argument type is
11139 @deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
11140 Similar to @code{__builtin_clz}, except the argument type is
11141 @code{unsigned long long}.
11144 @deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
11145 Similar to @code{__builtin_ctz}, except the argument type is
11146 @code{unsigned long long}.
11149 @deftypefn {Built-in Function} int __builtin_clrsbll (long long)
11150 Similar to @code{__builtin_clrsb}, except the argument type is
11154 @deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
11155 Similar to @code{__builtin_popcount}, except the argument type is
11156 @code{unsigned long long}.
11159 @deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
11160 Similar to @code{__builtin_parity}, except the argument type is
11161 @code{unsigned long long}.
11164 @deftypefn {Built-in Function} double __builtin_powi (double, int)
11165 Returns the first argument raised to the power of the second. Unlike the
11166 @code{pow} function no guarantees about precision and rounding are made.
11169 @deftypefn {Built-in Function} float __builtin_powif (float, int)
11170 Similar to @code{__builtin_powi}, except the argument and return types
11174 @deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
11175 Similar to @code{__builtin_powi}, except the argument and return types
11176 are @code{long double}.
11179 @deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x)
11180 Returns @var{x} with the order of the bytes reversed; for example,
11181 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means
11185 @deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x)
11186 Similar to @code{__builtin_bswap16}, except the argument and return types
11190 @deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x)
11191 Similar to @code{__builtin_bswap32}, except the argument and return types
11195 @node Target Builtins
11196 @section Built-in Functions Specific to Particular Target Machines
11198 On some target machines, GCC supports many built-in functions specific
11199 to those machines. Generally these generate calls to specific machine
11200 instructions, but allow the compiler to schedule those calls.
11203 * AArch64 Built-in Functions::
11204 * Alpha Built-in Functions::
11205 * Altera Nios II Built-in Functions::
11206 * ARC Built-in Functions::
11207 * ARC SIMD Built-in Functions::
11208 * ARM iWMMXt Built-in Functions::
11209 * ARM C Language Extensions (ACLE)::
11210 * ARM Floating Point Status and Control Intrinsics::
11211 * AVR Built-in Functions::
11212 * Blackfin Built-in Functions::
11213 * FR-V Built-in Functions::
11214 * MIPS DSP Built-in Functions::
11215 * MIPS Paired-Single Support::
11216 * MIPS Loongson Built-in Functions::
11217 * Other MIPS Built-in Functions::
11218 * MSP430 Built-in Functions::
11219 * NDS32 Built-in Functions::
11220 * picoChip Built-in Functions::
11221 * PowerPC Built-in Functions::
11222 * PowerPC AltiVec/VSX Built-in Functions::
11223 * PowerPC Hardware Transactional Memory Built-in Functions::
11224 * RX Built-in Functions::
11225 * S/390 System z Built-in Functions::
11226 * SH Built-in Functions::
11227 * SPARC VIS Built-in Functions::
11228 * SPU Built-in Functions::
11229 * TI C6X Built-in Functions::
11230 * TILE-Gx Built-in Functions::
11231 * TILEPro Built-in Functions::
11232 * x86 Built-in Functions::
11233 * x86 transactional memory intrinsics::
11236 @node AArch64 Built-in Functions
11237 @subsection AArch64 Built-in Functions
11239 These built-in functions are available for the AArch64 family of
11242 unsigned int __builtin_aarch64_get_fpcr ()
11243 void __builtin_aarch64_set_fpcr (unsigned int)
11244 unsigned int __builtin_aarch64_get_fpsr ()
11245 void __builtin_aarch64_set_fpsr (unsigned int)
11248 @node Alpha Built-in Functions
11249 @subsection Alpha Built-in Functions
11251 These built-in functions are available for the Alpha family of
11252 processors, depending on the command-line switches used.
11254 The following built-in functions are always available. They
11255 all generate the machine instruction that is part of the name.
11258 long __builtin_alpha_implver (void)
11259 long __builtin_alpha_rpcc (void)
11260 long __builtin_alpha_amask (long)
11261 long __builtin_alpha_cmpbge (long, long)
11262 long __builtin_alpha_extbl (long, long)
11263 long __builtin_alpha_extwl (long, long)
11264 long __builtin_alpha_extll (long, long)
11265 long __builtin_alpha_extql (long, long)
11266 long __builtin_alpha_extwh (long, long)
11267 long __builtin_alpha_extlh (long, long)
11268 long __builtin_alpha_extqh (long, long)
11269 long __builtin_alpha_insbl (long, long)
11270 long __builtin_alpha_inswl (long, long)
11271 long __builtin_alpha_insll (long, long)
11272 long __builtin_alpha_insql (long, long)
11273 long __builtin_alpha_inswh (long, long)
11274 long __builtin_alpha_inslh (long, long)
11275 long __builtin_alpha_insqh (long, long)
11276 long __builtin_alpha_mskbl (long, long)
11277 long __builtin_alpha_mskwl (long, long)
11278 long __builtin_alpha_mskll (long, long)
11279 long __builtin_alpha_mskql (long, long)
11280 long __builtin_alpha_mskwh (long, long)
11281 long __builtin_alpha_msklh (long, long)
11282 long __builtin_alpha_mskqh (long, long)
11283 long __builtin_alpha_umulh (long, long)
11284 long __builtin_alpha_zap (long, long)
11285 long __builtin_alpha_zapnot (long, long)
11288 The following built-in functions are always with @option{-mmax}
11289 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
11290 later. They all generate the machine instruction that is part
11294 long __builtin_alpha_pklb (long)
11295 long __builtin_alpha_pkwb (long)
11296 long __builtin_alpha_unpkbl (long)
11297 long __builtin_alpha_unpkbw (long)
11298 long __builtin_alpha_minub8 (long, long)
11299 long __builtin_alpha_minsb8 (long, long)
11300 long __builtin_alpha_minuw4 (long, long)
11301 long __builtin_alpha_minsw4 (long, long)
11302 long __builtin_alpha_maxub8 (long, long)
11303 long __builtin_alpha_maxsb8 (long, long)
11304 long __builtin_alpha_maxuw4 (long, long)
11305 long __builtin_alpha_maxsw4 (long, long)
11306 long __builtin_alpha_perr (long, long)
11309 The following built-in functions are always with @option{-mcix}
11310 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
11311 later. They all generate the machine instruction that is part
11315 long __builtin_alpha_cttz (long)
11316 long __builtin_alpha_ctlz (long)
11317 long __builtin_alpha_ctpop (long)
11320 The following built-in functions are available on systems that use the OSF/1
11321 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
11322 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
11323 @code{rdval} and @code{wrval}.
11326 void *__builtin_thread_pointer (void)
11327 void __builtin_set_thread_pointer (void *)
11330 @node Altera Nios II Built-in Functions
11331 @subsection Altera Nios II Built-in Functions
11333 These built-in functions are available for the Altera Nios II
11334 family of processors.
11336 The following built-in functions are always available. They
11337 all generate the machine instruction that is part of the name.
11340 int __builtin_ldbio (volatile const void *)
11341 int __builtin_ldbuio (volatile const void *)
11342 int __builtin_ldhio (volatile const void *)
11343 int __builtin_ldhuio (volatile const void *)
11344 int __builtin_ldwio (volatile const void *)
11345 void __builtin_stbio (volatile void *, int)
11346 void __builtin_sthio (volatile void *, int)
11347 void __builtin_stwio (volatile void *, int)
11348 void __builtin_sync (void)
11349 int __builtin_rdctl (int)
11350 int __builtin_rdprs (int, int)
11351 void __builtin_wrctl (int, int)
11352 void __builtin_flushd (volatile void *)
11353 void __builtin_flushda (volatile void *)
11354 int __builtin_wrpie (int);
11355 void __builtin_eni (int);
11356 int __builtin_ldex (volatile const void *)
11357 int __builtin_stex (volatile void *, int)
11358 int __builtin_ldsex (volatile const void *)
11359 int __builtin_stsex (volatile void *, int)
11362 The following built-in functions are always available. They
11363 all generate a Nios II Custom Instruction. The name of the
11364 function represents the types that the function takes and
11365 returns. The letter before the @code{n} is the return type
11366 or void if absent. The @code{n} represents the first parameter
11367 to all the custom instructions, the custom instruction number.
11368 The two letters after the @code{n} represent the up to two
11369 parameters to the function.
11371 The letters represent the following data types:
11374 @code{void} for return type and no parameter for parameter types.
11377 @code{int} for return type and parameter type
11380 @code{float} for return type and parameter type
11383 @code{void *} for return type and parameter type
11387 And the function names are:
11389 void __builtin_custom_n (void)
11390 void __builtin_custom_ni (int)
11391 void __builtin_custom_nf (float)
11392 void __builtin_custom_np (void *)
11393 void __builtin_custom_nii (int, int)
11394 void __builtin_custom_nif (int, float)
11395 void __builtin_custom_nip (int, void *)
11396 void __builtin_custom_nfi (float, int)
11397 void __builtin_custom_nff (float, float)
11398 void __builtin_custom_nfp (float, void *)
11399 void __builtin_custom_npi (void *, int)
11400 void __builtin_custom_npf (void *, float)
11401 void __builtin_custom_npp (void *, void *)
11402 int __builtin_custom_in (void)
11403 int __builtin_custom_ini (int)
11404 int __builtin_custom_inf (float)
11405 int __builtin_custom_inp (void *)
11406 int __builtin_custom_inii (int, int)
11407 int __builtin_custom_inif (int, float)
11408 int __builtin_custom_inip (int, void *)
11409 int __builtin_custom_infi (float, int)
11410 int __builtin_custom_inff (float, float)
11411 int __builtin_custom_infp (float, void *)
11412 int __builtin_custom_inpi (void *, int)
11413 int __builtin_custom_inpf (void *, float)
11414 int __builtin_custom_inpp (void *, void *)
11415 float __builtin_custom_fn (void)
11416 float __builtin_custom_fni (int)
11417 float __builtin_custom_fnf (float)
11418 float __builtin_custom_fnp (void *)
11419 float __builtin_custom_fnii (int, int)
11420 float __builtin_custom_fnif (int, float)
11421 float __builtin_custom_fnip (int, void *)
11422 float __builtin_custom_fnfi (float, int)
11423 float __builtin_custom_fnff (float, float)
11424 float __builtin_custom_fnfp (float, void *)
11425 float __builtin_custom_fnpi (void *, int)
11426 float __builtin_custom_fnpf (void *, float)
11427 float __builtin_custom_fnpp (void *, void *)
11428 void * __builtin_custom_pn (void)
11429 void * __builtin_custom_pni (int)
11430 void * __builtin_custom_pnf (float)
11431 void * __builtin_custom_pnp (void *)
11432 void * __builtin_custom_pnii (int, int)
11433 void * __builtin_custom_pnif (int, float)
11434 void * __builtin_custom_pnip (int, void *)
11435 void * __builtin_custom_pnfi (float, int)
11436 void * __builtin_custom_pnff (float, float)
11437 void * __builtin_custom_pnfp (float, void *)
11438 void * __builtin_custom_pnpi (void *, int)
11439 void * __builtin_custom_pnpf (void *, float)
11440 void * __builtin_custom_pnpp (void *, void *)
11443 @node ARC Built-in Functions
11444 @subsection ARC Built-in Functions
11446 The following built-in functions are provided for ARC targets. The
11447 built-ins generate the corresponding assembly instructions. In the
11448 examples given below, the generated code often requires an operand or
11449 result to be in a register. Where necessary further code will be
11450 generated to ensure this is true, but for brevity this is not
11451 described in each case.
11453 @emph{Note:} Using a built-in to generate an instruction not supported
11454 by a target may cause problems. At present the compiler is not
11455 guaranteed to detect such misuse, and as a result an internal compiler
11456 error may be generated.
11458 @deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval})
11459 Return 1 if @var{val} is known to have the byte alignment given
11460 by @var{alignval}, otherwise return 0.
11461 Note that this is different from
11463 __alignof__(*(char *)@var{val}) >= alignval
11465 because __alignof__ sees only the type of the dereference, whereas
11466 __builtin_arc_align uses alignment information from the pointer
11467 as well as from the pointed-to type.
11468 The information available will depend on optimization level.
11471 @deftypefn {Built-in Function} void __builtin_arc_brk (void)
11478 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno})
11479 The operand is the number of a register to be read. Generates:
11481 mov @var{dest}, r@var{regno}
11483 where the value in @var{dest} will be the result returned from the
11487 @deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})
11488 The first operand is the number of a register to be written, the
11489 second operand is a compile time constant to write into that
11490 register. Generates:
11492 mov r@var{regno}, @var{val}
11496 @deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b})
11497 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
11500 divaw @var{dest}, @var{a}, @var{b}
11502 where the value in @var{dest} will be the result returned from the
11506 @deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a})
11513 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr})
11514 The operand, @var{auxv}, is the address of an auxiliary register and
11515 must be a compile time constant. Generates:
11517 lr @var{dest}, [@var{auxr}]
11519 Where the value in @var{dest} will be the result returned from the
11523 @deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b})
11524 Only available with @option{-mmul64}. Generates:
11526 mul64 @var{a}, @var{b}
11530 @deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})
11531 Only available with @option{-mmul64}. Generates:
11533 mulu64 @var{a}, @var{b}
11537 @deftypefn {Built-in Function} void __builtin_arc_nop (void)
11544 @deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src})
11545 Only valid if the @samp{norm} instruction is available through the
11546 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
11549 norm @var{dest}, @var{src}
11551 Where the value in @var{dest} will be the result returned from the
11555 @deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src})
11556 Only valid if the @samp{normw} instruction is available through the
11557 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
11560 normw @var{dest}, @var{src}
11562 Where the value in @var{dest} will be the result returned from the
11566 @deftypefn {Built-in Function} void __builtin_arc_rtie (void)
11573 @deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a}
11580 @deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{auxr}, unsigned int @var{val})
11581 The first argument, @var{auxv}, is the address of an auxiliary
11582 register, the second argument, @var{val}, is a compile time constant
11583 to be written to the register. Generates:
11585 sr @var{auxr}, [@var{val}]
11589 @deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src})
11590 Only valid with @option{-mswap}. Generates:
11592 swap @var{dest}, @var{src}
11594 Where the value in @var{dest} will be the result returned from the
11598 @deftypefn {Built-in Function} void __builtin_arc_swi (void)
11605 @deftypefn {Built-in Function} void __builtin_arc_sync (void)
11606 Only available with @option{-mcpu=ARC700}. Generates:
11612 @deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c})
11613 Only available with @option{-mcpu=ARC700}. Generates:
11619 @deftypefn {Built-in Function} void __builtin_arc_unimp_s (void)
11620 Only available with @option{-mcpu=ARC700}. Generates:
11626 The instructions generated by the following builtins are not
11627 considered as candidates for scheduling. They are not moved around by
11628 the compiler during scheduling, and thus can be expected to appear
11629 where they are put in the C code:
11631 __builtin_arc_brk()
11632 __builtin_arc_core_read()
11633 __builtin_arc_core_write()
11634 __builtin_arc_flag()
11636 __builtin_arc_sleep()
11638 __builtin_arc_swi()
11641 @node ARC SIMD Built-in Functions
11642 @subsection ARC SIMD Built-in Functions
11644 SIMD builtins provided by the compiler can be used to generate the
11645 vector instructions. This section describes the available builtins
11646 and their usage in programs. With the @option{-msimd} option, the
11647 compiler provides 128-bit vector types, which can be specified using
11648 the @code{vector_size} attribute. The header file @file{arc-simd.h}
11649 can be included to use the following predefined types:
11651 typedef int __v4si __attribute__((vector_size(16)));
11652 typedef short __v8hi __attribute__((vector_size(16)));
11655 These types can be used to define 128-bit variables. The built-in
11656 functions listed in the following section can be used on these
11657 variables to generate the vector operations.
11659 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
11660 @file{arc-simd.h} also provides equivalent macros called
11661 @code{_@var{someinsn}} that can be used for programming ease and
11662 improved readability. The following macros for DMA control are also
11665 #define _setup_dma_in_channel_reg _vdiwr
11666 #define _setup_dma_out_channel_reg _vdowr
11669 The following is a complete list of all the SIMD built-ins provided
11670 for ARC, grouped by calling signature.
11672 The following take two @code{__v8hi} arguments and return a
11673 @code{__v8hi} result:
11675 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi)
11676 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi)
11677 __v8hi __builtin_arc_vand (__v8hi, __v8hi)
11678 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi)
11679 __v8hi __builtin_arc_vavb (__v8hi, __v8hi)
11680 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi)
11681 __v8hi __builtin_arc_vbic (__v8hi, __v8hi)
11682 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi)
11683 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi)
11684 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi)
11685 __v8hi __builtin_arc_veqw (__v8hi, __v8hi)
11686 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi)
11687 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi)
11688 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi)
11689 __v8hi __builtin_arc_vlew (__v8hi, __v8hi)
11690 __v8hi __builtin_arc_vltw (__v8hi, __v8hi)
11691 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi)
11692 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi)
11693 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi)
11694 __v8hi __builtin_arc_vminw (__v8hi, __v8hi)
11695 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi)
11696 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi)
11697 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi)
11698 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi)
11699 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi)
11700 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi)
11701 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi)
11702 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi)
11703 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi)
11704 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi)
11705 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi)
11706 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi)
11707 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi)
11708 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi)
11709 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi)
11710 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi)
11711 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi)
11712 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi)
11713 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi)
11714 __v8hi __builtin_arc_vnew (__v8hi, __v8hi)
11715 __v8hi __builtin_arc_vor (__v8hi, __v8hi)
11716 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi)
11717 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi)
11718 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi)
11719 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi)
11720 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi)
11721 __v8hi __builtin_arc_vxor (__v8hi, __v8hi)
11722 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi)
11725 The following take one @code{__v8hi} and one @code{int} argument and return a
11726 @code{__v8hi} result:
11729 __v8hi __builtin_arc_vbaddw (__v8hi, int)
11730 __v8hi __builtin_arc_vbmaxw (__v8hi, int)
11731 __v8hi __builtin_arc_vbminw (__v8hi, int)
11732 __v8hi __builtin_arc_vbmulaw (__v8hi, int)
11733 __v8hi __builtin_arc_vbmulfw (__v8hi, int)
11734 __v8hi __builtin_arc_vbmulw (__v8hi, int)
11735 __v8hi __builtin_arc_vbrsubw (__v8hi, int)
11736 __v8hi __builtin_arc_vbsubw (__v8hi, int)
11739 The following take one @code{__v8hi} argument and one @code{int} argument which
11740 must be a 3-bit compile time constant indicating a register number
11741 I0-I7. They return a @code{__v8hi} result.
11743 __v8hi __builtin_arc_vasrw (__v8hi, const int)
11744 __v8hi __builtin_arc_vsr8 (__v8hi, const int)
11745 __v8hi __builtin_arc_vsr8aw (__v8hi, const int)
11748 The following take one @code{__v8hi} argument and one @code{int}
11749 argument which must be a 6-bit compile time constant. They return a
11750 @code{__v8hi} result.
11752 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int)
11753 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int)
11754 __v8hi __builtin_arc_vasrrwi (__v8hi, const int)
11755 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int)
11756 __v8hi __builtin_arc_vasrwi (__v8hi, const int)
11757 __v8hi __builtin_arc_vsr8awi (__v8hi, const int)
11758 __v8hi __builtin_arc_vsr8i (__v8hi, const int)
11761 The following take one @code{__v8hi} argument and one @code{int} argument which
11762 must be a 8-bit compile time constant. They return a @code{__v8hi}
11765 __v8hi __builtin_arc_vd6tapf (__v8hi, const int)
11766 __v8hi __builtin_arc_vmvaw (__v8hi, const int)
11767 __v8hi __builtin_arc_vmvw (__v8hi, const int)
11768 __v8hi __builtin_arc_vmvzw (__v8hi, const int)
11771 The following take two @code{int} arguments, the second of which which
11772 must be a 8-bit compile time constant. They return a @code{__v8hi}
11775 __v8hi __builtin_arc_vmovaw (int, const int)
11776 __v8hi __builtin_arc_vmovw (int, const int)
11777 __v8hi __builtin_arc_vmovzw (int, const int)
11780 The following take a single @code{__v8hi} argument and return a
11781 @code{__v8hi} result:
11783 __v8hi __builtin_arc_vabsaw (__v8hi)
11784 __v8hi __builtin_arc_vabsw (__v8hi)
11785 __v8hi __builtin_arc_vaddsuw (__v8hi)
11786 __v8hi __builtin_arc_vexch1 (__v8hi)
11787 __v8hi __builtin_arc_vexch2 (__v8hi)
11788 __v8hi __builtin_arc_vexch4 (__v8hi)
11789 __v8hi __builtin_arc_vsignw (__v8hi)
11790 __v8hi __builtin_arc_vupbaw (__v8hi)
11791 __v8hi __builtin_arc_vupbw (__v8hi)
11792 __v8hi __builtin_arc_vupsbaw (__v8hi)
11793 __v8hi __builtin_arc_vupsbw (__v8hi)
11796 The following take two @code{int} arguments and return no result:
11798 void __builtin_arc_vdirun (int, int)
11799 void __builtin_arc_vdorun (int, int)
11802 The following take two @code{int} arguments and return no result. The
11803 first argument must a 3-bit compile time constant indicating one of
11804 the DR0-DR7 DMA setup channels:
11806 void __builtin_arc_vdiwr (const int, int)
11807 void __builtin_arc_vdowr (const int, int)
11810 The following take an @code{int} argument and return no result:
11812 void __builtin_arc_vendrec (int)
11813 void __builtin_arc_vrec (int)
11814 void __builtin_arc_vrecrun (int)
11815 void __builtin_arc_vrun (int)
11818 The following take a @code{__v8hi} argument and two @code{int}
11819 arguments and return a @code{__v8hi} result. The second argument must
11820 be a 3-bit compile time constants, indicating one the registers I0-I7,
11821 and the third argument must be an 8-bit compile time constant.
11823 @emph{Note:} Although the equivalent hardware instructions do not take
11824 an SIMD register as an operand, these builtins overwrite the relevant
11825 bits of the @code{__v8hi} register provided as the first argument with
11826 the value loaded from the @code{[Ib, u8]} location in the SDM.
11829 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int)
11830 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int)
11831 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int)
11832 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int)
11835 The following take two @code{int} arguments and return a @code{__v8hi}
11836 result. The first argument must be a 3-bit compile time constants,
11837 indicating one the registers I0-I7, and the second argument must be an
11838 8-bit compile time constant.
11841 __v8hi __builtin_arc_vld128 (const int, const int)
11842 __v8hi __builtin_arc_vld64w (const int, const int)
11845 The following take a @code{__v8hi} argument and two @code{int}
11846 arguments and return no result. The second argument must be a 3-bit
11847 compile time constants, indicating one the registers I0-I7, and the
11848 third argument must be an 8-bit compile time constant.
11851 void __builtin_arc_vst128 (__v8hi, const int, const int)
11852 void __builtin_arc_vst64 (__v8hi, const int, const int)
11855 The following take a @code{__v8hi} argument and three @code{int}
11856 arguments and return no result. The second argument must be a 3-bit
11857 compile-time constant, identifying the 16-bit sub-register to be
11858 stored, the third argument must be a 3-bit compile time constants,
11859 indicating one the registers I0-I7, and the fourth argument must be an
11860 8-bit compile time constant.
11863 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int)
11864 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int)
11867 @node ARM iWMMXt Built-in Functions
11868 @subsection ARM iWMMXt Built-in Functions
11870 These built-in functions are available for the ARM family of
11871 processors when the @option{-mcpu=iwmmxt} switch is used:
11874 typedef int v2si __attribute__ ((vector_size (8)));
11875 typedef short v4hi __attribute__ ((vector_size (8)));
11876 typedef char v8qi __attribute__ ((vector_size (8)));
11878 int __builtin_arm_getwcgr0 (void)
11879 void __builtin_arm_setwcgr0 (int)
11880 int __builtin_arm_getwcgr1 (void)
11881 void __builtin_arm_setwcgr1 (int)
11882 int __builtin_arm_getwcgr2 (void)
11883 void __builtin_arm_setwcgr2 (int)
11884 int __builtin_arm_getwcgr3 (void)
11885 void __builtin_arm_setwcgr3 (int)
11886 int __builtin_arm_textrmsb (v8qi, int)
11887 int __builtin_arm_textrmsh (v4hi, int)
11888 int __builtin_arm_textrmsw (v2si, int)
11889 int __builtin_arm_textrmub (v8qi, int)
11890 int __builtin_arm_textrmuh (v4hi, int)
11891 int __builtin_arm_textrmuw (v2si, int)
11892 v8qi __builtin_arm_tinsrb (v8qi, int, int)
11893 v4hi __builtin_arm_tinsrh (v4hi, int, int)
11894 v2si __builtin_arm_tinsrw (v2si, int, int)
11895 long long __builtin_arm_tmia (long long, int, int)
11896 long long __builtin_arm_tmiabb (long long, int, int)
11897 long long __builtin_arm_tmiabt (long long, int, int)
11898 long long __builtin_arm_tmiaph (long long, int, int)
11899 long long __builtin_arm_tmiatb (long long, int, int)
11900 long long __builtin_arm_tmiatt (long long, int, int)
11901 int __builtin_arm_tmovmskb (v8qi)
11902 int __builtin_arm_tmovmskh (v4hi)
11903 int __builtin_arm_tmovmskw (v2si)
11904 long long __builtin_arm_waccb (v8qi)
11905 long long __builtin_arm_wacch (v4hi)
11906 long long __builtin_arm_waccw (v2si)
11907 v8qi __builtin_arm_waddb (v8qi, v8qi)
11908 v8qi __builtin_arm_waddbss (v8qi, v8qi)
11909 v8qi __builtin_arm_waddbus (v8qi, v8qi)
11910 v4hi __builtin_arm_waddh (v4hi, v4hi)
11911 v4hi __builtin_arm_waddhss (v4hi, v4hi)
11912 v4hi __builtin_arm_waddhus (v4hi, v4hi)
11913 v2si __builtin_arm_waddw (v2si, v2si)
11914 v2si __builtin_arm_waddwss (v2si, v2si)
11915 v2si __builtin_arm_waddwus (v2si, v2si)
11916 v8qi __builtin_arm_walign (v8qi, v8qi, int)
11917 long long __builtin_arm_wand(long long, long long)
11918 long long __builtin_arm_wandn (long long, long long)
11919 v8qi __builtin_arm_wavg2b (v8qi, v8qi)
11920 v8qi __builtin_arm_wavg2br (v8qi, v8qi)
11921 v4hi __builtin_arm_wavg2h (v4hi, v4hi)
11922 v4hi __builtin_arm_wavg2hr (v4hi, v4hi)
11923 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi)
11924 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi)
11925 v2si __builtin_arm_wcmpeqw (v2si, v2si)
11926 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi)
11927 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi)
11928 v2si __builtin_arm_wcmpgtsw (v2si, v2si)
11929 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi)
11930 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi)
11931 v2si __builtin_arm_wcmpgtuw (v2si, v2si)
11932 long long __builtin_arm_wmacs (long long, v4hi, v4hi)
11933 long long __builtin_arm_wmacsz (v4hi, v4hi)
11934 long long __builtin_arm_wmacu (long long, v4hi, v4hi)
11935 long long __builtin_arm_wmacuz (v4hi, v4hi)
11936 v4hi __builtin_arm_wmadds (v4hi, v4hi)
11937 v4hi __builtin_arm_wmaddu (v4hi, v4hi)
11938 v8qi __builtin_arm_wmaxsb (v8qi, v8qi)
11939 v4hi __builtin_arm_wmaxsh (v4hi, v4hi)
11940 v2si __builtin_arm_wmaxsw (v2si, v2si)
11941 v8qi __builtin_arm_wmaxub (v8qi, v8qi)
11942 v4hi __builtin_arm_wmaxuh (v4hi, v4hi)
11943 v2si __builtin_arm_wmaxuw (v2si, v2si)
11944 v8qi __builtin_arm_wminsb (v8qi, v8qi)
11945 v4hi __builtin_arm_wminsh (v4hi, v4hi)
11946 v2si __builtin_arm_wminsw (v2si, v2si)
11947 v8qi __builtin_arm_wminub (v8qi, v8qi)
11948 v4hi __builtin_arm_wminuh (v4hi, v4hi)
11949 v2si __builtin_arm_wminuw (v2si, v2si)
11950 v4hi __builtin_arm_wmulsm (v4hi, v4hi)
11951 v4hi __builtin_arm_wmulul (v4hi, v4hi)
11952 v4hi __builtin_arm_wmulum (v4hi, v4hi)
11953 long long __builtin_arm_wor (long long, long long)
11954 v2si __builtin_arm_wpackdss (long long, long long)
11955 v2si __builtin_arm_wpackdus (long long, long long)
11956 v8qi __builtin_arm_wpackhss (v4hi, v4hi)
11957 v8qi __builtin_arm_wpackhus (v4hi, v4hi)
11958 v4hi __builtin_arm_wpackwss (v2si, v2si)
11959 v4hi __builtin_arm_wpackwus (v2si, v2si)
11960 long long __builtin_arm_wrord (long long, long long)
11961 long long __builtin_arm_wrordi (long long, int)
11962 v4hi __builtin_arm_wrorh (v4hi, long long)
11963 v4hi __builtin_arm_wrorhi (v4hi, int)
11964 v2si __builtin_arm_wrorw (v2si, long long)
11965 v2si __builtin_arm_wrorwi (v2si, int)
11966 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi)
11967 v2si __builtin_arm_wsadbz (v8qi, v8qi)
11968 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi)
11969 v2si __builtin_arm_wsadhz (v4hi, v4hi)
11970 v4hi __builtin_arm_wshufh (v4hi, int)
11971 long long __builtin_arm_wslld (long long, long long)
11972 long long __builtin_arm_wslldi (long long, int)
11973 v4hi __builtin_arm_wsllh (v4hi, long long)
11974 v4hi __builtin_arm_wsllhi (v4hi, int)
11975 v2si __builtin_arm_wsllw (v2si, long long)
11976 v2si __builtin_arm_wsllwi (v2si, int)
11977 long long __builtin_arm_wsrad (long long, long long)
11978 long long __builtin_arm_wsradi (long long, int)
11979 v4hi __builtin_arm_wsrah (v4hi, long long)
11980 v4hi __builtin_arm_wsrahi (v4hi, int)
11981 v2si __builtin_arm_wsraw (v2si, long long)
11982 v2si __builtin_arm_wsrawi (v2si, int)
11983 long long __builtin_arm_wsrld (long long, long long)
11984 long long __builtin_arm_wsrldi (long long, int)
11985 v4hi __builtin_arm_wsrlh (v4hi, long long)
11986 v4hi __builtin_arm_wsrlhi (v4hi, int)
11987 v2si __builtin_arm_wsrlw (v2si, long long)
11988 v2si __builtin_arm_wsrlwi (v2si, int)
11989 v8qi __builtin_arm_wsubb (v8qi, v8qi)
11990 v8qi __builtin_arm_wsubbss (v8qi, v8qi)
11991 v8qi __builtin_arm_wsubbus (v8qi, v8qi)
11992 v4hi __builtin_arm_wsubh (v4hi, v4hi)
11993 v4hi __builtin_arm_wsubhss (v4hi, v4hi)
11994 v4hi __builtin_arm_wsubhus (v4hi, v4hi)
11995 v2si __builtin_arm_wsubw (v2si, v2si)
11996 v2si __builtin_arm_wsubwss (v2si, v2si)
11997 v2si __builtin_arm_wsubwus (v2si, v2si)
11998 v4hi __builtin_arm_wunpckehsb (v8qi)
11999 v2si __builtin_arm_wunpckehsh (v4hi)
12000 long long __builtin_arm_wunpckehsw (v2si)
12001 v4hi __builtin_arm_wunpckehub (v8qi)
12002 v2si __builtin_arm_wunpckehuh (v4hi)
12003 long long __builtin_arm_wunpckehuw (v2si)
12004 v4hi __builtin_arm_wunpckelsb (v8qi)
12005 v2si __builtin_arm_wunpckelsh (v4hi)
12006 long long __builtin_arm_wunpckelsw (v2si)
12007 v4hi __builtin_arm_wunpckelub (v8qi)
12008 v2si __builtin_arm_wunpckeluh (v4hi)
12009 long long __builtin_arm_wunpckeluw (v2si)
12010 v8qi __builtin_arm_wunpckihb (v8qi, v8qi)
12011 v4hi __builtin_arm_wunpckihh (v4hi, v4hi)
12012 v2si __builtin_arm_wunpckihw (v2si, v2si)
12013 v8qi __builtin_arm_wunpckilb (v8qi, v8qi)
12014 v4hi __builtin_arm_wunpckilh (v4hi, v4hi)
12015 v2si __builtin_arm_wunpckilw (v2si, v2si)
12016 long long __builtin_arm_wxor (long long, long long)
12017 long long __builtin_arm_wzero ()
12021 @node ARM C Language Extensions (ACLE)
12022 @subsection ARM C Language Extensions (ACLE)
12024 GCC implements extensions for C as described in the ARM C Language
12025 Extensions (ACLE) specification, which can be found at
12026 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf}.
12028 As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
12029 the ARM C Language Extensions Specification. The complete list of Advanced SIMD
12030 intrinsics can be found at
12031 @uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073a/IHI0073A_arm_neon_intrinsics_ref.pdf}.
12032 The built-in intrinsics for the Advanced SIMD extension are available when
12035 Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both
12036 back ends support CRC32 intrinsics from @file{arm_acle.h}. The ARM back end's
12037 16-bit floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1.
12038 AArch64's back end does not have support for 16-bit floating point Advanced SIMD
12041 See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
12042 availability of extensions.
12044 @node ARM Floating Point Status and Control Intrinsics
12045 @subsection ARM Floating Point Status and Control Intrinsics
12047 These built-in functions are available for the ARM family of
12048 processors with floating-point unit.
12051 unsigned int __builtin_arm_get_fpscr ()
12052 void __builtin_arm_set_fpscr (unsigned int)
12055 @node AVR Built-in Functions
12056 @subsection AVR Built-in Functions
12058 For each built-in function for AVR, there is an equally named,
12059 uppercase built-in macro defined. That way users can easily query if
12060 or if not a specific built-in is implemented or not. For example, if
12061 @code{__builtin_avr_nop} is available the macro
12062 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
12064 The following built-in functions map to the respective machine
12065 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
12066 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
12067 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
12068 as library call if no hardware multiplier is available.
12071 void __builtin_avr_nop (void)
12072 void __builtin_avr_sei (void)
12073 void __builtin_avr_cli (void)
12074 void __builtin_avr_sleep (void)
12075 void __builtin_avr_wdr (void)
12076 unsigned char __builtin_avr_swap (unsigned char)
12077 unsigned int __builtin_avr_fmul (unsigned char, unsigned char)
12078 int __builtin_avr_fmuls (char, char)
12079 int __builtin_avr_fmulsu (char, unsigned char)
12082 In order to delay execution for a specific number of cycles, GCC
12085 void __builtin_avr_delay_cycles (unsigned long ticks)
12089 @code{ticks} is the number of ticks to delay execution. Note that this
12090 built-in does not take into account the effect of interrupts that
12091 might increase delay time. @code{ticks} must be a compile-time
12092 integer constant; delays with a variable number of cycles are not supported.
12095 char __builtin_avr_flash_segment (const __memx void*)
12099 This built-in takes a byte address to the 24-bit
12100 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns
12101 the number of the flash segment (the 64 KiB chunk) where the address
12102 points to. Counting starts at @code{0}.
12103 If the address does not point to flash memory, return @code{-1}.
12106 unsigned char __builtin_avr_insert_bits (unsigned long map, unsigned char bits, unsigned char val)
12110 Insert bits from @var{bits} into @var{val} and return the resulting
12111 value. The nibbles of @var{map} determine how the insertion is
12112 performed: Let @var{X} be the @var{n}-th nibble of @var{map}
12114 @item If @var{X} is @code{0xf},
12115 then the @var{n}-th bit of @var{val} is returned unaltered.
12117 @item If X is in the range 0@dots{}7,
12118 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
12120 @item If X is in the range 8@dots{}@code{0xe},
12121 then the @var{n}-th result bit is undefined.
12125 One typical use case for this built-in is adjusting input and
12126 output values to non-contiguous port layouts. Some examples:
12129 // same as val, bits is unused
12130 __builtin_avr_insert_bits (0xffffffff, bits, val)
12134 // same as bits, val is unused
12135 __builtin_avr_insert_bits (0x76543210, bits, val)
12139 // same as rotating bits by 4
12140 __builtin_avr_insert_bits (0x32107654, bits, 0)
12144 // high nibble of result is the high nibble of val
12145 // low nibble of result is the low nibble of bits
12146 __builtin_avr_insert_bits (0xffff3210, bits, val)
12150 // reverse the bit order of bits
12151 __builtin_avr_insert_bits (0x01234567, bits, 0)
12154 @node Blackfin Built-in Functions
12155 @subsection Blackfin Built-in Functions
12157 Currently, there are two Blackfin-specific built-in functions. These are
12158 used for generating @code{CSYNC} and @code{SSYNC} machine insns without
12159 using inline assembly; by using these built-in functions the compiler can
12160 automatically add workarounds for hardware errata involving these
12161 instructions. These functions are named as follows:
12164 void __builtin_bfin_csync (void)
12165 void __builtin_bfin_ssync (void)
12168 @node FR-V Built-in Functions
12169 @subsection FR-V Built-in Functions
12171 GCC provides many FR-V-specific built-in functions. In general,
12172 these functions are intended to be compatible with those described
12173 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
12174 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
12175 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by
12176 pointer rather than by value.
12178 Most of the functions are named after specific FR-V instructions.
12179 Such functions are said to be ``directly mapped'' and are summarized
12180 here in tabular form.
12184 * Directly-mapped Integer Functions::
12185 * Directly-mapped Media Functions::
12186 * Raw read/write Functions::
12187 * Other Built-in Functions::
12190 @node Argument Types
12191 @subsubsection Argument Types
12193 The arguments to the built-in functions can be divided into three groups:
12194 register numbers, compile-time constants and run-time values. In order
12195 to make this classification clear at a glance, the arguments and return
12196 values are given the following pseudo types:
12198 @multitable @columnfractions .20 .30 .15 .35
12199 @item Pseudo type @tab Real C type @tab Constant? @tab Description
12200 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
12201 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
12202 @item @code{sw1} @tab @code{int} @tab No @tab a signed word
12203 @item @code{uw2} @tab @code{unsigned long long} @tab No
12204 @tab an unsigned doubleword
12205 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
12206 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant
12207 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
12208 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
12211 These pseudo types are not defined by GCC, they are simply a notational
12212 convenience used in this manual.
12214 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
12215 and @code{sw2} are evaluated at run time. They correspond to
12216 register operands in the underlying FR-V instructions.
12218 @code{const} arguments represent immediate operands in the underlying
12219 FR-V instructions. They must be compile-time constants.
12221 @code{acc} arguments are evaluated at compile time and specify the number
12222 of an accumulator register. For example, an @code{acc} argument of 2
12223 selects the ACC2 register.
12225 @code{iacc} arguments are similar to @code{acc} arguments but specify the
12226 number of an IACC register. See @pxref{Other Built-in Functions}
12229 @node Directly-mapped Integer Functions
12230 @subsubsection Directly-Mapped Integer Functions
12232 The functions listed below map directly to FR-V I-type instructions.
12234 @multitable @columnfractions .45 .32 .23
12235 @item Function prototype @tab Example usage @tab Assembly output
12236 @item @code{sw1 __ADDSS (sw1, sw1)}
12237 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
12238 @tab @code{ADDSS @var{a},@var{b},@var{c}}
12239 @item @code{sw1 __SCAN (sw1, sw1)}
12240 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
12241 @tab @code{SCAN @var{a},@var{b},@var{c}}
12242 @item @code{sw1 __SCUTSS (sw1)}
12243 @tab @code{@var{b} = __SCUTSS (@var{a})}
12244 @tab @code{SCUTSS @var{a},@var{b}}
12245 @item @code{sw1 __SLASS (sw1, sw1)}
12246 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
12247 @tab @code{SLASS @var{a},@var{b},@var{c}}
12248 @item @code{void __SMASS (sw1, sw1)}
12249 @tab @code{__SMASS (@var{a}, @var{b})}
12250 @tab @code{SMASS @var{a},@var{b}}
12251 @item @code{void __SMSSS (sw1, sw1)}
12252 @tab @code{__SMSSS (@var{a}, @var{b})}
12253 @tab @code{SMSSS @var{a},@var{b}}
12254 @item @code{void __SMU (sw1, sw1)}
12255 @tab @code{__SMU (@var{a}, @var{b})}
12256 @tab @code{SMU @var{a},@var{b}}
12257 @item @code{sw2 __SMUL (sw1, sw1)}
12258 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
12259 @tab @code{SMUL @var{a},@var{b},@var{c}}
12260 @item @code{sw1 __SUBSS (sw1, sw1)}
12261 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
12262 @tab @code{SUBSS @var{a},@var{b},@var{c}}
12263 @item @code{uw2 __UMUL (uw1, uw1)}
12264 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
12265 @tab @code{UMUL @var{a},@var{b},@var{c}}
12268 @node Directly-mapped Media Functions
12269 @subsubsection Directly-Mapped Media Functions
12271 The functions listed below map directly to FR-V M-type instructions.
12273 @multitable @columnfractions .45 .32 .23
12274 @item Function prototype @tab Example usage @tab Assembly output
12275 @item @code{uw1 __MABSHS (sw1)}
12276 @tab @code{@var{b} = __MABSHS (@var{a})}
12277 @tab @code{MABSHS @var{a},@var{b}}
12278 @item @code{void __MADDACCS (acc, acc)}
12279 @tab @code{__MADDACCS (@var{b}, @var{a})}
12280 @tab @code{MADDACCS @var{a},@var{b}}
12281 @item @code{sw1 __MADDHSS (sw1, sw1)}
12282 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
12283 @tab @code{MADDHSS @var{a},@var{b},@var{c}}
12284 @item @code{uw1 __MADDHUS (uw1, uw1)}
12285 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
12286 @tab @code{MADDHUS @var{a},@var{b},@var{c}}
12287 @item @code{uw1 __MAND (uw1, uw1)}
12288 @tab @code{@var{c} = __MAND (@var{a}, @var{b})}
12289 @tab @code{MAND @var{a},@var{b},@var{c}}
12290 @item @code{void __MASACCS (acc, acc)}
12291 @tab @code{__MASACCS (@var{b}, @var{a})}
12292 @tab @code{MASACCS @var{a},@var{b}}
12293 @item @code{uw1 __MAVEH (uw1, uw1)}
12294 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
12295 @tab @code{MAVEH @var{a},@var{b},@var{c}}
12296 @item @code{uw2 __MBTOH (uw1)}
12297 @tab @code{@var{b} = __MBTOH (@var{a})}
12298 @tab @code{MBTOH @var{a},@var{b}}
12299 @item @code{void __MBTOHE (uw1 *, uw1)}
12300 @tab @code{__MBTOHE (&@var{b}, @var{a})}
12301 @tab @code{MBTOHE @var{a},@var{b}}
12302 @item @code{void __MCLRACC (acc)}
12303 @tab @code{__MCLRACC (@var{a})}
12304 @tab @code{MCLRACC @var{a}}
12305 @item @code{void __MCLRACCA (void)}
12306 @tab @code{__MCLRACCA ()}
12307 @tab @code{MCLRACCA}
12308 @item @code{uw1 __Mcop1 (uw1, uw1)}
12309 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
12310 @tab @code{Mcop1 @var{a},@var{b},@var{c}}
12311 @item @code{uw1 __Mcop2 (uw1, uw1)}
12312 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
12313 @tab @code{Mcop2 @var{a},@var{b},@var{c}}
12314 @item @code{uw1 __MCPLHI (uw2, const)}
12315 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
12316 @tab @code{MCPLHI @var{a},#@var{b},@var{c}}
12317 @item @code{uw1 __MCPLI (uw2, const)}
12318 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
12319 @tab @code{MCPLI @var{a},#@var{b},@var{c}}
12320 @item @code{void __MCPXIS (acc, sw1, sw1)}
12321 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
12322 @tab @code{MCPXIS @var{a},@var{b},@var{c}}
12323 @item @code{void __MCPXIU (acc, uw1, uw1)}
12324 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
12325 @tab @code{MCPXIU @var{a},@var{b},@var{c}}
12326 @item @code{void __MCPXRS (acc, sw1, sw1)}
12327 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
12328 @tab @code{MCPXRS @var{a},@var{b},@var{c}}
12329 @item @code{void __MCPXRU (acc, uw1, uw1)}
12330 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
12331 @tab @code{MCPXRU @var{a},@var{b},@var{c}}
12332 @item @code{uw1 __MCUT (acc, uw1)}
12333 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
12334 @tab @code{MCUT @var{a},@var{b},@var{c}}
12335 @item @code{uw1 __MCUTSS (acc, sw1)}
12336 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
12337 @tab @code{MCUTSS @var{a},@var{b},@var{c}}
12338 @item @code{void __MDADDACCS (acc, acc)}
12339 @tab @code{__MDADDACCS (@var{b}, @var{a})}
12340 @tab @code{MDADDACCS @var{a},@var{b}}
12341 @item @code{void __MDASACCS (acc, acc)}
12342 @tab @code{__MDASACCS (@var{b}, @var{a})}
12343 @tab @code{MDASACCS @var{a},@var{b}}
12344 @item @code{uw2 __MDCUTSSI (acc, const)}
12345 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
12346 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
12347 @item @code{uw2 __MDPACKH (uw2, uw2)}
12348 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
12349 @tab @code{MDPACKH @var{a},@var{b},@var{c}}
12350 @item @code{uw2 __MDROTLI (uw2, const)}
12351 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
12352 @tab @code{MDROTLI @var{a},#@var{b},@var{c}}
12353 @item @code{void __MDSUBACCS (acc, acc)}
12354 @tab @code{__MDSUBACCS (@var{b}, @var{a})}
12355 @tab @code{MDSUBACCS @var{a},@var{b}}
12356 @item @code{void __MDUNPACKH (uw1 *, uw2)}
12357 @tab @code{__MDUNPACKH (&@var{b}, @var{a})}
12358 @tab @code{MDUNPACKH @var{a},@var{b}}
12359 @item @code{uw2 __MEXPDHD (uw1, const)}
12360 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
12361 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
12362 @item @code{uw1 __MEXPDHW (uw1, const)}
12363 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
12364 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
12365 @item @code{uw1 __MHDSETH (uw1, const)}
12366 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
12367 @tab @code{MHDSETH @var{a},#@var{b},@var{c}}
12368 @item @code{sw1 __MHDSETS (const)}
12369 @tab @code{@var{b} = __MHDSETS (@var{a})}
12370 @tab @code{MHDSETS #@var{a},@var{b}}
12371 @item @code{uw1 __MHSETHIH (uw1, const)}
12372 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
12373 @tab @code{MHSETHIH #@var{a},@var{b}}
12374 @item @code{sw1 __MHSETHIS (sw1, const)}
12375 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
12376 @tab @code{MHSETHIS #@var{a},@var{b}}
12377 @item @code{uw1 __MHSETLOH (uw1, const)}
12378 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
12379 @tab @code{MHSETLOH #@var{a},@var{b}}
12380 @item @code{sw1 __MHSETLOS (sw1, const)}
12381 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
12382 @tab @code{MHSETLOS #@var{a},@var{b}}
12383 @item @code{uw1 __MHTOB (uw2)}
12384 @tab @code{@var{b} = __MHTOB (@var{a})}
12385 @tab @code{MHTOB @var{a},@var{b}}
12386 @item @code{void __MMACHS (acc, sw1, sw1)}
12387 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
12388 @tab @code{MMACHS @var{a},@var{b},@var{c}}
12389 @item @code{void __MMACHU (acc, uw1, uw1)}
12390 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
12391 @tab @code{MMACHU @var{a},@var{b},@var{c}}
12392 @item @code{void __MMRDHS (acc, sw1, sw1)}
12393 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
12394 @tab @code{MMRDHS @var{a},@var{b},@var{c}}
12395 @item @code{void __MMRDHU (acc, uw1, uw1)}
12396 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
12397 @tab @code{MMRDHU @var{a},@var{b},@var{c}}
12398 @item @code{void __MMULHS (acc, sw1, sw1)}
12399 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
12400 @tab @code{MMULHS @var{a},@var{b},@var{c}}
12401 @item @code{void __MMULHU (acc, uw1, uw1)}
12402 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
12403 @tab @code{MMULHU @var{a},@var{b},@var{c}}
12404 @item @code{void __MMULXHS (acc, sw1, sw1)}
12405 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
12406 @tab @code{MMULXHS @var{a},@var{b},@var{c}}
12407 @item @code{void __MMULXHU (acc, uw1, uw1)}
12408 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
12409 @tab @code{MMULXHU @var{a},@var{b},@var{c}}
12410 @item @code{uw1 __MNOT (uw1)}
12411 @tab @code{@var{b} = __MNOT (@var{a})}
12412 @tab @code{MNOT @var{a},@var{b}}
12413 @item @code{uw1 __MOR (uw1, uw1)}
12414 @tab @code{@var{c} = __MOR (@var{a}, @var{b})}
12415 @tab @code{MOR @var{a},@var{b},@var{c}}
12416 @item @code{uw1 __MPACKH (uh, uh)}
12417 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
12418 @tab @code{MPACKH @var{a},@var{b},@var{c}}
12419 @item @code{sw2 __MQADDHSS (sw2, sw2)}
12420 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
12421 @tab @code{MQADDHSS @var{a},@var{b},@var{c}}
12422 @item @code{uw2 __MQADDHUS (uw2, uw2)}
12423 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
12424 @tab @code{MQADDHUS @var{a},@var{b},@var{c}}
12425 @item @code{void __MQCPXIS (acc, sw2, sw2)}
12426 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
12427 @tab @code{MQCPXIS @var{a},@var{b},@var{c}}
12428 @item @code{void __MQCPXIU (acc, uw2, uw2)}
12429 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
12430 @tab @code{MQCPXIU @var{a},@var{b},@var{c}}
12431 @item @code{void __MQCPXRS (acc, sw2, sw2)}
12432 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
12433 @tab @code{MQCPXRS @var{a},@var{b},@var{c}}
12434 @item @code{void __MQCPXRU (acc, uw2, uw2)}
12435 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
12436 @tab @code{MQCPXRU @var{a},@var{b},@var{c}}
12437 @item @code{sw2 __MQLCLRHS (sw2, sw2)}
12438 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
12439 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
12440 @item @code{sw2 __MQLMTHS (sw2, sw2)}
12441 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
12442 @tab @code{MQLMTHS @var{a},@var{b},@var{c}}
12443 @item @code{void __MQMACHS (acc, sw2, sw2)}
12444 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
12445 @tab @code{MQMACHS @var{a},@var{b},@var{c}}
12446 @item @code{void __MQMACHU (acc, uw2, uw2)}
12447 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
12448 @tab @code{MQMACHU @var{a},@var{b},@var{c}}
12449 @item @code{void __MQMACXHS (acc, sw2, sw2)}
12450 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
12451 @tab @code{MQMACXHS @var{a},@var{b},@var{c}}
12452 @item @code{void __MQMULHS (acc, sw2, sw2)}
12453 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
12454 @tab @code{MQMULHS @var{a},@var{b},@var{c}}
12455 @item @code{void __MQMULHU (acc, uw2, uw2)}
12456 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
12457 @tab @code{MQMULHU @var{a},@var{b},@var{c}}
12458 @item @code{void __MQMULXHS (acc, sw2, sw2)}
12459 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
12460 @tab @code{MQMULXHS @var{a},@var{b},@var{c}}
12461 @item @code{void __MQMULXHU (acc, uw2, uw2)}
12462 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
12463 @tab @code{MQMULXHU @var{a},@var{b},@var{c}}
12464 @item @code{sw2 __MQSATHS (sw2, sw2)}
12465 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
12466 @tab @code{MQSATHS @var{a},@var{b},@var{c}}
12467 @item @code{uw2 __MQSLLHI (uw2, int)}
12468 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
12469 @tab @code{MQSLLHI @var{a},@var{b},@var{c}}
12470 @item @code{sw2 __MQSRAHI (sw2, int)}
12471 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
12472 @tab @code{MQSRAHI @var{a},@var{b},@var{c}}
12473 @item @code{sw2 __MQSUBHSS (sw2, sw2)}
12474 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
12475 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
12476 @item @code{uw2 __MQSUBHUS (uw2, uw2)}
12477 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
12478 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
12479 @item @code{void __MQXMACHS (acc, sw2, sw2)}
12480 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
12481 @tab @code{MQXMACHS @var{a},@var{b},@var{c}}
12482 @item @code{void __MQXMACXHS (acc, sw2, sw2)}
12483 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
12484 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
12485 @item @code{uw1 __MRDACC (acc)}
12486 @tab @code{@var{b} = __MRDACC (@var{a})}
12487 @tab @code{MRDACC @var{a},@var{b}}
12488 @item @code{uw1 __MRDACCG (acc)}
12489 @tab @code{@var{b} = __MRDACCG (@var{a})}
12490 @tab @code{MRDACCG @var{a},@var{b}}
12491 @item @code{uw1 __MROTLI (uw1, const)}
12492 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
12493 @tab @code{MROTLI @var{a},#@var{b},@var{c}}
12494 @item @code{uw1 __MROTRI (uw1, const)}
12495 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
12496 @tab @code{MROTRI @var{a},#@var{b},@var{c}}
12497 @item @code{sw1 __MSATHS (sw1, sw1)}
12498 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
12499 @tab @code{MSATHS @var{a},@var{b},@var{c}}
12500 @item @code{uw1 __MSATHU (uw1, uw1)}
12501 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
12502 @tab @code{MSATHU @var{a},@var{b},@var{c}}
12503 @item @code{uw1 __MSLLHI (uw1, const)}
12504 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
12505 @tab @code{MSLLHI @var{a},#@var{b},@var{c}}
12506 @item @code{sw1 __MSRAHI (sw1, const)}
12507 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
12508 @tab @code{MSRAHI @var{a},#@var{b},@var{c}}
12509 @item @code{uw1 __MSRLHI (uw1, const)}
12510 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
12511 @tab @code{MSRLHI @var{a},#@var{b},@var{c}}
12512 @item @code{void __MSUBACCS (acc, acc)}
12513 @tab @code{__MSUBACCS (@var{b}, @var{a})}
12514 @tab @code{MSUBACCS @var{a},@var{b}}
12515 @item @code{sw1 __MSUBHSS (sw1, sw1)}
12516 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
12517 @tab @code{MSUBHSS @var{a},@var{b},@var{c}}
12518 @item @code{uw1 __MSUBHUS (uw1, uw1)}
12519 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
12520 @tab @code{MSUBHUS @var{a},@var{b},@var{c}}
12521 @item @code{void __MTRAP (void)}
12522 @tab @code{__MTRAP ()}
12524 @item @code{uw2 __MUNPACKH (uw1)}
12525 @tab @code{@var{b} = __MUNPACKH (@var{a})}
12526 @tab @code{MUNPACKH @var{a},@var{b}}
12527 @item @code{uw1 __MWCUT (uw2, uw1)}
12528 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
12529 @tab @code{MWCUT @var{a},@var{b},@var{c}}
12530 @item @code{void __MWTACC (acc, uw1)}
12531 @tab @code{__MWTACC (@var{b}, @var{a})}
12532 @tab @code{MWTACC @var{a},@var{b}}
12533 @item @code{void __MWTACCG (acc, uw1)}
12534 @tab @code{__MWTACCG (@var{b}, @var{a})}
12535 @tab @code{MWTACCG @var{a},@var{b}}
12536 @item @code{uw1 __MXOR (uw1, uw1)}
12537 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
12538 @tab @code{MXOR @var{a},@var{b},@var{c}}
12541 @node Raw read/write Functions
12542 @subsubsection Raw Read/Write Functions
12544 This sections describes built-in functions related to read and write
12545 instructions to access memory. These functions generate
12546 @code{membar} instructions to flush the I/O load and stores where
12547 appropriate, as described in Fujitsu's manual described above.
12551 @item unsigned char __builtin_read8 (void *@var{data})
12552 @item unsigned short __builtin_read16 (void *@var{data})
12553 @item unsigned long __builtin_read32 (void *@var{data})
12554 @item unsigned long long __builtin_read64 (void *@var{data})
12556 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
12557 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
12558 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
12559 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
12562 @node Other Built-in Functions
12563 @subsubsection Other Built-in Functions
12565 This section describes built-in functions that are not named after
12566 a specific FR-V instruction.
12569 @item sw2 __IACCreadll (iacc @var{reg})
12570 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
12571 for future expansion and must be 0.
12573 @item sw1 __IACCreadl (iacc @var{reg})
12574 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
12575 Other values of @var{reg} are rejected as invalid.
12577 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
12578 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
12579 is reserved for future expansion and must be 0.
12581 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
12582 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
12583 is 1. Other values of @var{reg} are rejected as invalid.
12585 @item void __data_prefetch0 (const void *@var{x})
12586 Use the @code{dcpl} instruction to load the contents of address @var{x}
12587 into the data cache.
12589 @item void __data_prefetch (const void *@var{x})
12590 Use the @code{nldub} instruction to load the contents of address @var{x}
12591 into the data cache. The instruction is issued in slot I1@.
12594 @node MIPS DSP Built-in Functions
12595 @subsection MIPS DSP Built-in Functions
12597 The MIPS DSP Application-Specific Extension (ASE) includes new
12598 instructions that are designed to improve the performance of DSP and
12599 media applications. It provides instructions that operate on packed
12600 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
12602 GCC supports MIPS DSP operations using both the generic
12603 vector extensions (@pxref{Vector Extensions}) and a collection of
12604 MIPS-specific built-in functions. Both kinds of support are
12605 enabled by the @option{-mdsp} command-line option.
12607 Revision 2 of the ASE was introduced in the second half of 2006.
12608 This revision adds extra instructions to the original ASE, but is
12609 otherwise backwards-compatible with it. You can select revision 2
12610 using the command-line option @option{-mdspr2}; this option implies
12613 The SCOUNT and POS bits of the DSP control register are global. The
12614 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
12615 POS bits. During optimization, the compiler does not delete these
12616 instructions and it does not delete calls to functions containing
12617 these instructions.
12619 At present, GCC only provides support for operations on 32-bit
12620 vectors. The vector type associated with 8-bit integer data is
12621 usually called @code{v4i8}, the vector type associated with Q7
12622 is usually called @code{v4q7}, the vector type associated with 16-bit
12623 integer data is usually called @code{v2i16}, and the vector type
12624 associated with Q15 is usually called @code{v2q15}. They can be
12625 defined in C as follows:
12628 typedef signed char v4i8 __attribute__ ((vector_size(4)));
12629 typedef signed char v4q7 __attribute__ ((vector_size(4)));
12630 typedef short v2i16 __attribute__ ((vector_size(4)));
12631 typedef short v2q15 __attribute__ ((vector_size(4)));
12634 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
12635 initialized in the same way as aggregates. For example:
12638 v4i8 a = @{1, 2, 3, 4@};
12640 b = (v4i8) @{5, 6, 7, 8@};
12642 v2q15 c = @{0x0fcb, 0x3a75@};
12644 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
12647 @emph{Note:} The CPU's endianness determines the order in which values
12648 are packed. On little-endian targets, the first value is the least
12649 significant and the last value is the most significant. The opposite
12650 order applies to big-endian targets. For example, the code above
12651 sets the lowest byte of @code{a} to @code{1} on little-endian targets
12652 and @code{4} on big-endian targets.
12654 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
12655 representation. As shown in this example, the integer representation
12656 of a Q7 value can be obtained by multiplying the fractional value by
12657 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by
12658 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by
12661 The table below lists the @code{v4i8} and @code{v2q15} operations for which
12662 hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
12663 and @code{c} and @code{d} are @code{v2q15} values.
12665 @multitable @columnfractions .50 .50
12666 @item C code @tab MIPS instruction
12667 @item @code{a + b} @tab @code{addu.qb}
12668 @item @code{c + d} @tab @code{addq.ph}
12669 @item @code{a - b} @tab @code{subu.qb}
12670 @item @code{c - d} @tab @code{subq.ph}
12673 The table below lists the @code{v2i16} operation for which
12674 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
12675 @code{v2i16} values.
12677 @multitable @columnfractions .50 .50
12678 @item C code @tab MIPS instruction
12679 @item @code{e * f} @tab @code{mul.ph}
12682 It is easier to describe the DSP built-in functions if we first define
12683 the following types:
12688 typedef unsigned int ui32;
12689 typedef long long a64;
12692 @code{q31} and @code{i32} are actually the same as @code{int}, but we
12693 use @code{q31} to indicate a Q31 fractional value and @code{i32} to
12694 indicate a 32-bit integer value. Similarly, @code{a64} is the same as
12695 @code{long long}, but we use @code{a64} to indicate values that are
12696 placed in one of the four DSP accumulators (@code{$ac0},
12697 @code{$ac1}, @code{$ac2} or @code{$ac3}).
12699 Also, some built-in functions prefer or require immediate numbers as
12700 parameters, because the corresponding DSP instructions accept both immediate
12701 numbers and register operands, or accept immediate numbers only. The
12702 immediate parameters are listed as follows.
12710 imm0_255: 0 to 255.
12711 imm_n32_31: -32 to 31.
12712 imm_n512_511: -512 to 511.
12715 The following built-in functions map directly to a particular MIPS DSP
12716 instruction. Please refer to the architecture specification
12717 for details on what each instruction does.
12720 v2q15 __builtin_mips_addq_ph (v2q15, v2q15)
12721 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15)
12722 q31 __builtin_mips_addq_s_w (q31, q31)
12723 v4i8 __builtin_mips_addu_qb (v4i8, v4i8)
12724 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8)
12725 v2q15 __builtin_mips_subq_ph (v2q15, v2q15)
12726 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15)
12727 q31 __builtin_mips_subq_s_w (q31, q31)
12728 v4i8 __builtin_mips_subu_qb (v4i8, v4i8)
12729 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8)
12730 i32 __builtin_mips_addsc (i32, i32)
12731 i32 __builtin_mips_addwc (i32, i32)
12732 i32 __builtin_mips_modsub (i32, i32)
12733 i32 __builtin_mips_raddu_w_qb (v4i8)
12734 v2q15 __builtin_mips_absq_s_ph (v2q15)
12735 q31 __builtin_mips_absq_s_w (q31)
12736 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15)
12737 v2q15 __builtin_mips_precrq_ph_w (q31, q31)
12738 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31)
12739 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15)
12740 q31 __builtin_mips_preceq_w_phl (v2q15)
12741 q31 __builtin_mips_preceq_w_phr (v2q15)
12742 v2q15 __builtin_mips_precequ_ph_qbl (v4i8)
12743 v2q15 __builtin_mips_precequ_ph_qbr (v4i8)
12744 v2q15 __builtin_mips_precequ_ph_qbla (v4i8)
12745 v2q15 __builtin_mips_precequ_ph_qbra (v4i8)
12746 v2q15 __builtin_mips_preceu_ph_qbl (v4i8)
12747 v2q15 __builtin_mips_preceu_ph_qbr (v4i8)
12748 v2q15 __builtin_mips_preceu_ph_qbla (v4i8)
12749 v2q15 __builtin_mips_preceu_ph_qbra (v4i8)
12750 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7)
12751 v4i8 __builtin_mips_shll_qb (v4i8, i32)
12752 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15)
12753 v2q15 __builtin_mips_shll_ph (v2q15, i32)
12754 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15)
12755 v2q15 __builtin_mips_shll_s_ph (v2q15, i32)
12756 q31 __builtin_mips_shll_s_w (q31, imm0_31)
12757 q31 __builtin_mips_shll_s_w (q31, i32)
12758 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7)
12759 v4i8 __builtin_mips_shrl_qb (v4i8, i32)
12760 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15)
12761 v2q15 __builtin_mips_shra_ph (v2q15, i32)
12762 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15)
12763 v2q15 __builtin_mips_shra_r_ph (v2q15, i32)
12764 q31 __builtin_mips_shra_r_w (q31, imm0_31)
12765 q31 __builtin_mips_shra_r_w (q31, i32)
12766 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15)
12767 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15)
12768 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15)
12769 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15)
12770 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15)
12771 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8)
12772 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8)
12773 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8)
12774 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8)
12775 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15)
12776 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31)
12777 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15)
12778 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31)
12779 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15)
12780 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15)
12781 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15)
12782 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15)
12783 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15)
12784 i32 __builtin_mips_bitrev (i32)
12785 i32 __builtin_mips_insv (i32, i32)
12786 v4i8 __builtin_mips_repl_qb (imm0_255)
12787 v4i8 __builtin_mips_repl_qb (i32)
12788 v2q15 __builtin_mips_repl_ph (imm_n512_511)
12789 v2q15 __builtin_mips_repl_ph (i32)
12790 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8)
12791 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8)
12792 void __builtin_mips_cmpu_le_qb (v4i8, v4i8)
12793 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8)
12794 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8)
12795 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8)
12796 void __builtin_mips_cmp_eq_ph (v2q15, v2q15)
12797 void __builtin_mips_cmp_lt_ph (v2q15, v2q15)
12798 void __builtin_mips_cmp_le_ph (v2q15, v2q15)
12799 v4i8 __builtin_mips_pick_qb (v4i8, v4i8)
12800 v2q15 __builtin_mips_pick_ph (v2q15, v2q15)
12801 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15)
12802 i32 __builtin_mips_extr_w (a64, imm0_31)
12803 i32 __builtin_mips_extr_w (a64, i32)
12804 i32 __builtin_mips_extr_r_w (a64, imm0_31)
12805 i32 __builtin_mips_extr_s_h (a64, i32)
12806 i32 __builtin_mips_extr_rs_w (a64, imm0_31)
12807 i32 __builtin_mips_extr_rs_w (a64, i32)
12808 i32 __builtin_mips_extr_s_h (a64, imm0_31)
12809 i32 __builtin_mips_extr_r_w (a64, i32)
12810 i32 __builtin_mips_extp (a64, imm0_31)
12811 i32 __builtin_mips_extp (a64, i32)
12812 i32 __builtin_mips_extpdp (a64, imm0_31)
12813 i32 __builtin_mips_extpdp (a64, i32)
12814 a64 __builtin_mips_shilo (a64, imm_n32_31)
12815 a64 __builtin_mips_shilo (a64, i32)
12816 a64 __builtin_mips_mthlip (a64, i32)
12817 void __builtin_mips_wrdsp (i32, imm0_63)
12818 i32 __builtin_mips_rddsp (imm0_63)
12819 i32 __builtin_mips_lbux (void *, i32)
12820 i32 __builtin_mips_lhx (void *, i32)
12821 i32 __builtin_mips_lwx (void *, i32)
12822 a64 __builtin_mips_ldx (void *, i32) [MIPS64 only]
12823 i32 __builtin_mips_bposge32 (void)
12824 a64 __builtin_mips_madd (a64, i32, i32);
12825 a64 __builtin_mips_maddu (a64, ui32, ui32);
12826 a64 __builtin_mips_msub (a64, i32, i32);
12827 a64 __builtin_mips_msubu (a64, ui32, ui32);
12828 a64 __builtin_mips_mult (i32, i32);
12829 a64 __builtin_mips_multu (ui32, ui32);
12832 The following built-in functions map directly to a particular MIPS DSP REV 2
12833 instruction. Please refer to the architecture specification
12834 for details on what each instruction does.
12837 v4q7 __builtin_mips_absq_s_qb (v4q7);
12838 v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
12839 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
12840 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
12841 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
12842 i32 __builtin_mips_append (i32, i32, imm0_31);
12843 i32 __builtin_mips_balign (i32, i32, imm0_3);
12844 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
12845 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
12846 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
12847 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
12848 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
12849 v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
12850 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
12851 q31 __builtin_mips_mulq_rs_w (q31, q31);
12852 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
12853 q31 __builtin_mips_mulq_s_w (q31, q31);
12854 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
12855 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
12856 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
12857 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
12858 i32 __builtin_mips_prepend (i32, i32, imm0_31);
12859 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
12860 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
12861 v4i8 __builtin_mips_shra_qb (v4i8, i32);
12862 v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
12863 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
12864 v2i16 __builtin_mips_shrl_ph (v2i16, i32);
12865 v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
12866 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
12867 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
12868 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
12869 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
12870 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
12871 q31 __builtin_mips_addqh_w (q31, q31);
12872 q31 __builtin_mips_addqh_r_w (q31, q31);
12873 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
12874 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
12875 q31 __builtin_mips_subqh_w (q31, q31);
12876 q31 __builtin_mips_subqh_r_w (q31, q31);
12877 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
12878 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
12879 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
12880 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
12881 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
12882 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
12886 @node MIPS Paired-Single Support
12887 @subsection MIPS Paired-Single Support
12889 The MIPS64 architecture includes a number of instructions that
12890 operate on pairs of single-precision floating-point values.
12891 Each pair is packed into a 64-bit floating-point register,
12892 with one element being designated the ``upper half'' and
12893 the other being designated the ``lower half''.
12895 GCC supports paired-single operations using both the generic
12896 vector extensions (@pxref{Vector Extensions}) and a collection of
12897 MIPS-specific built-in functions. Both kinds of support are
12898 enabled by the @option{-mpaired-single} command-line option.
12900 The vector type associated with paired-single values is usually
12901 called @code{v2sf}. It can be defined in C as follows:
12904 typedef float v2sf __attribute__ ((vector_size (8)));
12907 @code{v2sf} values are initialized in the same way as aggregates.
12911 v2sf a = @{1.5, 9.1@};
12914 b = (v2sf) @{e, f@};
12917 @emph{Note:} The CPU's endianness determines which value is stored in
12918 the upper half of a register and which value is stored in the lower half.
12919 On little-endian targets, the first value is the lower one and the second
12920 value is the upper one. The opposite order applies to big-endian targets.
12921 For example, the code above sets the lower half of @code{a} to
12922 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
12924 @node MIPS Loongson Built-in Functions
12925 @subsection MIPS Loongson Built-in Functions
12927 GCC provides intrinsics to access the SIMD instructions provided by the
12928 ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
12929 available after inclusion of the @code{loongson.h} header file,
12930 operate on the following 64-bit vector types:
12933 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
12934 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
12935 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
12936 @item @code{int8x8_t}, a vector of eight signed 8-bit integers;
12937 @item @code{int16x4_t}, a vector of four signed 16-bit integers;
12938 @item @code{int32x2_t}, a vector of two signed 32-bit integers.
12941 The intrinsics provided are listed below; each is named after the
12942 machine instruction to which it corresponds, with suffixes added as
12943 appropriate to distinguish intrinsics that expand to the same machine
12944 instruction yet have different argument types. Refer to the architecture
12945 documentation for a description of the functionality of each
12949 int16x4_t packsswh (int32x2_t s, int32x2_t t);
12950 int8x8_t packsshb (int16x4_t s, int16x4_t t);
12951 uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
12952 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
12953 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
12954 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
12955 int32x2_t paddw_s (int32x2_t s, int32x2_t t);
12956 int16x4_t paddh_s (int16x4_t s, int16x4_t t);
12957 int8x8_t paddb_s (int8x8_t s, int8x8_t t);
12958 uint64_t paddd_u (uint64_t s, uint64_t t);
12959 int64_t paddd_s (int64_t s, int64_t t);
12960 int16x4_t paddsh (int16x4_t s, int16x4_t t);
12961 int8x8_t paddsb (int8x8_t s, int8x8_t t);
12962 uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
12963 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
12964 uint64_t pandn_ud (uint64_t s, uint64_t t);
12965 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
12966 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
12967 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
12968 int64_t pandn_sd (int64_t s, int64_t t);
12969 int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
12970 int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
12971 int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
12972 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
12973 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
12974 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
12975 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
12976 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
12977 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
12978 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
12979 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
12980 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
12981 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
12982 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
12983 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
12984 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
12985 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
12986 uint16x4_t pextrh_u (uint16x4_t s, int field);
12987 int16x4_t pextrh_s (int16x4_t s, int field);
12988 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
12989 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
12990 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
12991 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
12992 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
12993 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
12994 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
12995 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
12996 int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
12997 int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
12998 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
12999 int16x4_t pminsh (int16x4_t s, int16x4_t t);
13000 uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
13001 uint8x8_t pmovmskb_u (uint8x8_t s);
13002 int8x8_t pmovmskb_s (int8x8_t s);
13003 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
13004 int16x4_t pmulhh (int16x4_t s, int16x4_t t);
13005 int16x4_t pmullh (int16x4_t s, int16x4_t t);
13006 int64_t pmuluw (uint32x2_t s, uint32x2_t t);
13007 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
13008 uint16x4_t biadd (uint8x8_t s);
13009 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
13010 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
13011 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
13012 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
13013 int16x4_t psllh_s (int16x4_t s, uint8_t amount);
13014 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
13015 int32x2_t psllw_s (int32x2_t s, uint8_t amount);
13016 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
13017 int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
13018 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
13019 int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
13020 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
13021 int16x4_t psrah_s (int16x4_t s, uint8_t amount);
13022 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
13023 int32x2_t psraw_s (int32x2_t s, uint8_t amount);
13024 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
13025 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
13026 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
13027 int32x2_t psubw_s (int32x2_t s, int32x2_t t);
13028 int16x4_t psubh_s (int16x4_t s, int16x4_t t);
13029 int8x8_t psubb_s (int8x8_t s, int8x8_t t);
13030 uint64_t psubd_u (uint64_t s, uint64_t t);
13031 int64_t psubd_s (int64_t s, int64_t t);
13032 int16x4_t psubsh (int16x4_t s, int16x4_t t);
13033 int8x8_t psubsb (int8x8_t s, int8x8_t t);
13034 uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
13035 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
13036 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
13037 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
13038 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
13039 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
13040 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
13041 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
13042 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
13043 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
13044 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
13045 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
13046 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
13047 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
13051 * Paired-Single Arithmetic::
13052 * Paired-Single Built-in Functions::
13053 * MIPS-3D Built-in Functions::
13056 @node Paired-Single Arithmetic
13057 @subsubsection Paired-Single Arithmetic
13059 The table below lists the @code{v2sf} operations for which hardware
13060 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
13061 values and @code{x} is an integral value.
13063 @multitable @columnfractions .50 .50
13064 @item C code @tab MIPS instruction
13065 @item @code{a + b} @tab @code{add.ps}
13066 @item @code{a - b} @tab @code{sub.ps}
13067 @item @code{-a} @tab @code{neg.ps}
13068 @item @code{a * b} @tab @code{mul.ps}
13069 @item @code{a * b + c} @tab @code{madd.ps}
13070 @item @code{a * b - c} @tab @code{msub.ps}
13071 @item @code{-(a * b + c)} @tab @code{nmadd.ps}
13072 @item @code{-(a * b - c)} @tab @code{nmsub.ps}
13073 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
13076 Note that the multiply-accumulate instructions can be disabled
13077 using the command-line option @code{-mno-fused-madd}.
13079 @node Paired-Single Built-in Functions
13080 @subsubsection Paired-Single Built-in Functions
13082 The following paired-single functions map directly to a particular
13083 MIPS instruction. Please refer to the architecture specification
13084 for details on what each instruction does.
13087 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
13088 Pair lower lower (@code{pll.ps}).
13090 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
13091 Pair upper lower (@code{pul.ps}).
13093 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
13094 Pair lower upper (@code{plu.ps}).
13096 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
13097 Pair upper upper (@code{puu.ps}).
13099 @item v2sf __builtin_mips_cvt_ps_s (float, float)
13100 Convert pair to paired single (@code{cvt.ps.s}).
13102 @item float __builtin_mips_cvt_s_pl (v2sf)
13103 Convert pair lower to single (@code{cvt.s.pl}).
13105 @item float __builtin_mips_cvt_s_pu (v2sf)
13106 Convert pair upper to single (@code{cvt.s.pu}).
13108 @item v2sf __builtin_mips_abs_ps (v2sf)
13109 Absolute value (@code{abs.ps}).
13111 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
13112 Align variable (@code{alnv.ps}).
13114 @emph{Note:} The value of the third parameter must be 0 or 4
13115 modulo 8, otherwise the result is unpredictable. Please read the
13116 instruction description for details.
13119 The following multi-instruction functions are also available.
13120 In each case, @var{cond} can be any of the 16 floating-point conditions:
13121 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
13122 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
13123 @code{lt}, @code{nge}, @code{le} or @code{ngt}.
13126 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13127 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13128 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
13129 @code{movt.ps}/@code{movf.ps}).
13131 The @code{movt} functions return the value @var{x} computed by:
13134 c.@var{cond}.ps @var{cc},@var{a},@var{b}
13135 mov.ps @var{x},@var{c}
13136 movt.ps @var{x},@var{d},@var{cc}
13139 The @code{movf} functions are similar but use @code{movf.ps} instead
13142 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13143 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13144 Comparison of two paired-single values (@code{c.@var{cond}.ps},
13145 @code{bc1t}/@code{bc1f}).
13147 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
13148 and return either the upper or lower half of the result. For example:
13152 if (__builtin_mips_upper_c_eq_ps (a, b))
13153 upper_halves_are_equal ();
13155 upper_halves_are_unequal ();
13157 if (__builtin_mips_lower_c_eq_ps (a, b))
13158 lower_halves_are_equal ();
13160 lower_halves_are_unequal ();
13164 @node MIPS-3D Built-in Functions
13165 @subsubsection MIPS-3D Built-in Functions
13167 The MIPS-3D Application-Specific Extension (ASE) includes additional
13168 paired-single instructions that are designed to improve the performance
13169 of 3D graphics operations. Support for these instructions is controlled
13170 by the @option{-mips3d} command-line option.
13172 The functions listed below map directly to a particular MIPS-3D
13173 instruction. Please refer to the architecture specification for
13174 more details on what each instruction does.
13177 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
13178 Reduction add (@code{addr.ps}).
13180 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
13181 Reduction multiply (@code{mulr.ps}).
13183 @item v2sf __builtin_mips_cvt_pw_ps (v2sf)
13184 Convert paired single to paired word (@code{cvt.pw.ps}).
13186 @item v2sf __builtin_mips_cvt_ps_pw (v2sf)
13187 Convert paired word to paired single (@code{cvt.ps.pw}).
13189 @item float __builtin_mips_recip1_s (float)
13190 @itemx double __builtin_mips_recip1_d (double)
13191 @itemx v2sf __builtin_mips_recip1_ps (v2sf)
13192 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
13194 @item float __builtin_mips_recip2_s (float, float)
13195 @itemx double __builtin_mips_recip2_d (double, double)
13196 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
13197 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
13199 @item float __builtin_mips_rsqrt1_s (float)
13200 @itemx double __builtin_mips_rsqrt1_d (double)
13201 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
13202 Reduced-precision reciprocal square root (sequence step 1)
13203 (@code{rsqrt1.@var{fmt}}).
13205 @item float __builtin_mips_rsqrt2_s (float, float)
13206 @itemx double __builtin_mips_rsqrt2_d (double, double)
13207 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
13208 Reduced-precision reciprocal square root (sequence step 2)
13209 (@code{rsqrt2.@var{fmt}}).
13212 The following multi-instruction functions are also available.
13213 In each case, @var{cond} can be any of the 16 floating-point conditions:
13214 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
13215 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
13216 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
13219 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
13220 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
13221 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
13222 @code{bc1t}/@code{bc1f}).
13224 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
13225 or @code{cabs.@var{cond}.d} and return the result as a boolean value.
13230 if (__builtin_mips_cabs_eq_s (a, b))
13236 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13237 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13238 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
13239 @code{bc1t}/@code{bc1f}).
13241 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
13242 and return either the upper or lower half of the result. For example:
13246 if (__builtin_mips_upper_cabs_eq_ps (a, b))
13247 upper_halves_are_equal ();
13249 upper_halves_are_unequal ();
13251 if (__builtin_mips_lower_cabs_eq_ps (a, b))
13252 lower_halves_are_equal ();
13254 lower_halves_are_unequal ();
13257 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13258 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13259 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
13260 @code{movt.ps}/@code{movf.ps}).
13262 The @code{movt} functions return the value @var{x} computed by:
13265 cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
13266 mov.ps @var{x},@var{c}
13267 movt.ps @var{x},@var{d},@var{cc}
13270 The @code{movf} functions are similar but use @code{movf.ps} instead
13273 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13274 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13275 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13276 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13277 Comparison of two paired-single values
13278 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
13279 @code{bc1any2t}/@code{bc1any2f}).
13281 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
13282 or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either
13283 result is true and the @code{all} forms return true if both results are true.
13288 if (__builtin_mips_any_c_eq_ps (a, b))
13293 if (__builtin_mips_all_c_eq_ps (a, b))
13299 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13300 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13301 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13302 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13303 Comparison of four paired-single values
13304 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
13305 @code{bc1any4t}/@code{bc1any4f}).
13307 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
13308 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
13309 The @code{any} forms return true if any of the four results are true
13310 and the @code{all} forms return true if all four results are true.
13315 if (__builtin_mips_any_c_eq_4s (a, b, c, d))
13320 if (__builtin_mips_all_c_eq_4s (a, b, c, d))
13327 @node Other MIPS Built-in Functions
13328 @subsection Other MIPS Built-in Functions
13330 GCC provides other MIPS-specific built-in functions:
13333 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
13334 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
13335 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
13336 when this function is available.
13338 @item unsigned int __builtin_mips_get_fcsr (void)
13339 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
13340 Get and set the contents of the floating-point control and status register
13341 (FPU control register 31). These functions are only available in hard-float
13342 code but can be called in both MIPS16 and non-MIPS16 contexts.
13344 @code{__builtin_mips_set_fcsr} can be used to change any bit of the
13345 register except the condition codes, which GCC assumes are preserved.
13348 @node MSP430 Built-in Functions
13349 @subsection MSP430 Built-in Functions
13351 GCC provides a couple of special builtin functions to aid in the
13352 writing of interrupt handlers in C.
13355 @item __bic_SR_register_on_exit (int @var{mask})
13356 This clears the indicated bits in the saved copy of the status register
13357 currently residing on the stack. This only works inside interrupt
13358 handlers and the changes to the status register will only take affect
13359 once the handler returns.
13361 @item __bis_SR_register_on_exit (int @var{mask})
13362 This sets the indicated bits in the saved copy of the status register
13363 currently residing on the stack. This only works inside interrupt
13364 handlers and the changes to the status register will only take affect
13365 once the handler returns.
13367 @item __delay_cycles (long long @var{cycles})
13368 This inserts an instruction sequence that takes exactly @var{cycles}
13369 cycles (between 0 and about 17E9) to complete. The inserted sequence
13370 may use jumps, loops, or no-ops, and does not interfere with any other
13371 instructions. Note that @var{cycles} must be a compile-time constant
13372 integer - that is, you must pass a number, not a variable that may be
13373 optimized to a constant later. The number of cycles delayed by this
13377 @node NDS32 Built-in Functions
13378 @subsection NDS32 Built-in Functions
13380 These built-in functions are available for the NDS32 target:
13382 @deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr})
13383 Insert an ISYNC instruction into the instruction stream where
13384 @var{addr} is an instruction address for serialization.
13387 @deftypefn {Built-in Function} void __builtin_nds32_isb (void)
13388 Insert an ISB instruction into the instruction stream.
13391 @deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr})
13392 Return the content of a system register which is mapped by @var{sr}.
13395 @deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr})
13396 Return the content of a user space register which is mapped by @var{usr}.
13399 @deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr})
13400 Move the @var{value} to a system register which is mapped by @var{sr}.
13403 @deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr})
13404 Move the @var{value} to a user space register which is mapped by @var{usr}.
13407 @deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void)
13408 Enable global interrupt.
13411 @deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void)
13412 Disable global interrupt.
13415 @node picoChip Built-in Functions
13416 @subsection picoChip Built-in Functions
13418 GCC provides an interface to selected machine instructions from the
13419 picoChip instruction set.
13422 @item int __builtin_sbc (int @var{value})
13423 Sign bit count. Return the number of consecutive bits in @var{value}
13424 that have the same value as the sign bit. The result is the number of
13425 leading sign bits minus one, giving the number of redundant sign bits in
13428 @item int __builtin_byteswap (int @var{value})
13429 Byte swap. Return the result of swapping the upper and lower bytes of
13432 @item int __builtin_brev (int @var{value})
13433 Bit reversal. Return the result of reversing the bits in
13434 @var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
13437 @item int __builtin_adds (int @var{x}, int @var{y})
13438 Saturating addition. Return the result of adding @var{x} and @var{y},
13439 storing the value 32767 if the result overflows.
13441 @item int __builtin_subs (int @var{x}, int @var{y})
13442 Saturating subtraction. Return the result of subtracting @var{y} from
13443 @var{x}, storing the value @minus{}32768 if the result overflows.
13445 @item void __builtin_halt (void)
13446 Halt. The processor stops execution. This built-in is useful for
13447 implementing assertions.
13451 @node PowerPC Built-in Functions
13452 @subsection PowerPC Built-in Functions
13454 These built-in functions are available for the PowerPC family of
13457 float __builtin_recipdivf (float, float);
13458 float __builtin_rsqrtf (float);
13459 double __builtin_recipdiv (double, double);
13460 double __builtin_rsqrt (double);
13461 uint64_t __builtin_ppc_get_timebase ();
13462 unsigned long __builtin_ppc_mftb ();
13463 double __builtin_unpack_longdouble (long double, int);
13464 long double __builtin_pack_longdouble (double, double);
13467 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
13468 @code{__builtin_rsqrtf} functions generate multiple instructions to
13469 implement the reciprocal sqrt functionality using reciprocal sqrt
13470 estimate instructions.
13472 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
13473 functions generate multiple instructions to implement division using
13474 the reciprocal estimate instructions.
13476 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
13477 functions generate instructions to read the Time Base Register. The
13478 @code{__builtin_ppc_get_timebase} function may generate multiple
13479 instructions and always returns the 64 bits of the Time Base Register.
13480 The @code{__builtin_ppc_mftb} function always generates one instruction and
13481 returns the Time Base Register value as an unsigned long, throwing away
13482 the most significant word on 32-bit environments.
13484 The following built-in functions are available for the PowerPC family
13485 of processors, starting with ISA 2.06 or later (@option{-mcpu=power7}
13486 or @option{-mpopcntd}):
13488 long __builtin_bpermd (long, long);
13489 int __builtin_divwe (int, int);
13490 int __builtin_divweo (int, int);
13491 unsigned int __builtin_divweu (unsigned int, unsigned int);
13492 unsigned int __builtin_divweuo (unsigned int, unsigned int);
13493 long __builtin_divde (long, long);
13494 long __builtin_divdeo (long, long);
13495 unsigned long __builtin_divdeu (unsigned long, unsigned long);
13496 unsigned long __builtin_divdeuo (unsigned long, unsigned long);
13497 unsigned int cdtbcd (unsigned int);
13498 unsigned int cbcdtd (unsigned int);
13499 unsigned int addg6s (unsigned int, unsigned int);
13502 The @code{__builtin_divde}, @code{__builtin_divdeo},
13503 @code{__builtin_divdeu}, @code{__builtin_divdeou} functions require a
13504 64-bit environment support ISA 2.06 or later.
13506 The following built-in functions are available for the PowerPC family
13507 of processors when hardware decimal floating point
13508 (@option{-mhard-dfp}) is available:
13510 _Decimal64 __builtin_dxex (_Decimal64);
13511 _Decimal128 __builtin_dxexq (_Decimal128);
13512 _Decimal64 __builtin_ddedpd (int, _Decimal64);
13513 _Decimal128 __builtin_ddedpdq (int, _Decimal128);
13514 _Decimal64 __builtin_denbcd (int, _Decimal64);
13515 _Decimal128 __builtin_denbcdq (int, _Decimal128);
13516 _Decimal64 __builtin_diex (_Decimal64, _Decimal64);
13517 _Decimal128 _builtin_diexq (_Decimal128, _Decimal128);
13518 _Decimal64 __builtin_dscli (_Decimal64, int);
13519 _Decimal128 __builtin_dscliq (_Decimal128, int);
13520 _Decimal64 __builtin_dscri (_Decimal64, int);
13521 _Decimal128 __builtin_dscriq (_Decimal128, int);
13522 unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
13523 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
13526 The following built-in functions are available for the PowerPC family
13527 of processors when the Vector Scalar (vsx) instruction set is
13530 unsigned long long __builtin_unpack_vector_int128 (vector __int128_t, int);
13531 vector __int128_t __builtin_pack_vector_int128 (unsigned long long,
13532 unsigned long long);
13535 @node PowerPC AltiVec/VSX Built-in Functions
13536 @subsection PowerPC AltiVec Built-in Functions
13538 GCC provides an interface for the PowerPC family of processors to access
13539 the AltiVec operations described in Motorola's AltiVec Programming
13540 Interface Manual. The interface is made available by including
13541 @code{<altivec.h>} and using @option{-maltivec} and
13542 @option{-mabi=altivec}. The interface supports the following vector
13546 vector unsigned char
13550 vector unsigned short
13551 vector signed short
13555 vector unsigned int
13561 If @option{-mvsx} is used the following additional vector types are
13565 vector unsigned long
13570 The long types are only implemented for 64-bit code generation, and
13571 the long type is only used in the floating point/integer conversion
13574 GCC's implementation of the high-level language interface available from
13575 C and C++ code differs from Motorola's documentation in several ways.
13580 A vector constant is a list of constant expressions within curly braces.
13583 A vector initializer requires no cast if the vector constant is of the
13584 same type as the variable it is initializing.
13587 If @code{signed} or @code{unsigned} is omitted, the signedness of the
13588 vector type is the default signedness of the base type. The default
13589 varies depending on the operating system, so a portable program should
13590 always specify the signedness.
13593 Compiling with @option{-maltivec} adds keywords @code{__vector},
13594 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
13595 @code{bool}. When compiling ISO C, the context-sensitive substitution
13596 of the keywords @code{vector}, @code{pixel} and @code{bool} is
13597 disabled. To use them, you must include @code{<altivec.h>} instead.
13600 GCC allows using a @code{typedef} name as the type specifier for a
13604 For C, overloaded functions are implemented with macros so the following
13608 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
13612 Since @code{vec_add} is a macro, the vector constant in the example
13613 is treated as four separate arguments. Wrap the entire argument in
13614 parentheses for this to work.
13617 @emph{Note:} Only the @code{<altivec.h>} interface is supported.
13618 Internally, GCC uses built-in functions to achieve the functionality in
13619 the aforementioned header file, but they are not supported and are
13620 subject to change without notice.
13622 The following interfaces are supported for the generic and specific
13623 AltiVec operations and the AltiVec predicates. In cases where there
13624 is a direct mapping between generic and specific operations, only the
13625 generic names are shown here, although the specific operations can also
13628 Arguments that are documented as @code{const int} require literal
13629 integral values within the range required for that operation.
13632 vector signed char vec_abs (vector signed char);
13633 vector signed short vec_abs (vector signed short);
13634 vector signed int vec_abs (vector signed int);
13635 vector float vec_abs (vector float);
13637 vector signed char vec_abss (vector signed char);
13638 vector signed short vec_abss (vector signed short);
13639 vector signed int vec_abss (vector signed int);
13641 vector signed char vec_add (vector bool char, vector signed char);
13642 vector signed char vec_add (vector signed char, vector bool char);
13643 vector signed char vec_add (vector signed char, vector signed char);
13644 vector unsigned char vec_add (vector bool char, vector unsigned char);
13645 vector unsigned char vec_add (vector unsigned char, vector bool char);
13646 vector unsigned char vec_add (vector unsigned char,
13647 vector unsigned char);
13648 vector signed short vec_add (vector bool short, vector signed short);
13649 vector signed short vec_add (vector signed short, vector bool short);
13650 vector signed short vec_add (vector signed short, vector signed short);
13651 vector unsigned short vec_add (vector bool short,
13652 vector unsigned short);
13653 vector unsigned short vec_add (vector unsigned short,
13654 vector bool short);
13655 vector unsigned short vec_add (vector unsigned short,
13656 vector unsigned short);
13657 vector signed int vec_add (vector bool int, vector signed int);
13658 vector signed int vec_add (vector signed int, vector bool int);
13659 vector signed int vec_add (vector signed int, vector signed int);
13660 vector unsigned int vec_add (vector bool int, vector unsigned int);
13661 vector unsigned int vec_add (vector unsigned int, vector bool int);
13662 vector unsigned int vec_add (vector unsigned int, vector unsigned int);
13663 vector float vec_add (vector float, vector float);
13665 vector float vec_vaddfp (vector float, vector float);
13667 vector signed int vec_vadduwm (vector bool int, vector signed int);
13668 vector signed int vec_vadduwm (vector signed int, vector bool int);
13669 vector signed int vec_vadduwm (vector signed int, vector signed int);
13670 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
13671 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
13672 vector unsigned int vec_vadduwm (vector unsigned int,
13673 vector unsigned int);
13675 vector signed short vec_vadduhm (vector bool short,
13676 vector signed short);
13677 vector signed short vec_vadduhm (vector signed short,
13678 vector bool short);
13679 vector signed short vec_vadduhm (vector signed short,
13680 vector signed short);
13681 vector unsigned short vec_vadduhm (vector bool short,
13682 vector unsigned short);
13683 vector unsigned short vec_vadduhm (vector unsigned short,
13684 vector bool short);
13685 vector unsigned short vec_vadduhm (vector unsigned short,
13686 vector unsigned short);
13688 vector signed char vec_vaddubm (vector bool char, vector signed char);
13689 vector signed char vec_vaddubm (vector signed char, vector bool char);
13690 vector signed char vec_vaddubm (vector signed char, vector signed char);
13691 vector unsigned char vec_vaddubm (vector bool char,
13692 vector unsigned char);
13693 vector unsigned char vec_vaddubm (vector unsigned char,
13695 vector unsigned char vec_vaddubm (vector unsigned char,
13696 vector unsigned char);
13698 vector unsigned int vec_addc (vector unsigned int, vector unsigned int);
13700 vector unsigned char vec_adds (vector bool char, vector unsigned char);
13701 vector unsigned char vec_adds (vector unsigned char, vector bool char);
13702 vector unsigned char vec_adds (vector unsigned char,
13703 vector unsigned char);
13704 vector signed char vec_adds (vector bool char, vector signed char);
13705 vector signed char vec_adds (vector signed char, vector bool char);
13706 vector signed char vec_adds (vector signed char, vector signed char);
13707 vector unsigned short vec_adds (vector bool short,
13708 vector unsigned short);
13709 vector unsigned short vec_adds (vector unsigned short,
13710 vector bool short);
13711 vector unsigned short vec_adds (vector unsigned short,
13712 vector unsigned short);
13713 vector signed short vec_adds (vector bool short, vector signed short);
13714 vector signed short vec_adds (vector signed short, vector bool short);
13715 vector signed short vec_adds (vector signed short, vector signed short);
13716 vector unsigned int vec_adds (vector bool int, vector unsigned int);
13717 vector unsigned int vec_adds (vector unsigned int, vector bool int);
13718 vector unsigned int vec_adds (vector unsigned int, vector unsigned int);
13719 vector signed int vec_adds (vector bool int, vector signed int);
13720 vector signed int vec_adds (vector signed int, vector bool int);
13721 vector signed int vec_adds (vector signed int, vector signed int);
13723 vector signed int vec_vaddsws (vector bool int, vector signed int);
13724 vector signed int vec_vaddsws (vector signed int, vector bool int);
13725 vector signed int vec_vaddsws (vector signed int, vector signed int);
13727 vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
13728 vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
13729 vector unsigned int vec_vadduws (vector unsigned int,
13730 vector unsigned int);
13732 vector signed short vec_vaddshs (vector bool short,
13733 vector signed short);
13734 vector signed short vec_vaddshs (vector signed short,
13735 vector bool short);
13736 vector signed short vec_vaddshs (vector signed short,
13737 vector signed short);
13739 vector unsigned short vec_vadduhs (vector bool short,
13740 vector unsigned short);
13741 vector unsigned short vec_vadduhs (vector unsigned short,
13742 vector bool short);
13743 vector unsigned short vec_vadduhs (vector unsigned short,
13744 vector unsigned short);
13746 vector signed char vec_vaddsbs (vector bool char, vector signed char);
13747 vector signed char vec_vaddsbs (vector signed char, vector bool char);
13748 vector signed char vec_vaddsbs (vector signed char, vector signed char);
13750 vector unsigned char vec_vaddubs (vector bool char,
13751 vector unsigned char);
13752 vector unsigned char vec_vaddubs (vector unsigned char,
13754 vector unsigned char vec_vaddubs (vector unsigned char,
13755 vector unsigned char);
13757 vector float vec_and (vector float, vector float);
13758 vector float vec_and (vector float, vector bool int);
13759 vector float vec_and (vector bool int, vector float);
13760 vector bool int vec_and (vector bool int, vector bool int);
13761 vector signed int vec_and (vector bool int, vector signed int);
13762 vector signed int vec_and (vector signed int, vector bool int);
13763 vector signed int vec_and (vector signed int, vector signed int);
13764 vector unsigned int vec_and (vector bool int, vector unsigned int);
13765 vector unsigned int vec_and (vector unsigned int, vector bool int);
13766 vector unsigned int vec_and (vector unsigned int, vector unsigned int);
13767 vector bool short vec_and (vector bool short, vector bool short);
13768 vector signed short vec_and (vector bool short, vector signed short);
13769 vector signed short vec_and (vector signed short, vector bool short);
13770 vector signed short vec_and (vector signed short, vector signed short);
13771 vector unsigned short vec_and (vector bool short,
13772 vector unsigned short);
13773 vector unsigned short vec_and (vector unsigned short,
13774 vector bool short);
13775 vector unsigned short vec_and (vector unsigned short,
13776 vector unsigned short);
13777 vector signed char vec_and (vector bool char, vector signed char);
13778 vector bool char vec_and (vector bool char, vector bool char);
13779 vector signed char vec_and (vector signed char, vector bool char);
13780 vector signed char vec_and (vector signed char, vector signed char);
13781 vector unsigned char vec_and (vector bool char, vector unsigned char);
13782 vector unsigned char vec_and (vector unsigned char, vector bool char);
13783 vector unsigned char vec_and (vector unsigned char,
13784 vector unsigned char);
13786 vector float vec_andc (vector float, vector float);
13787 vector float vec_andc (vector float, vector bool int);
13788 vector float vec_andc (vector bool int, vector float);
13789 vector bool int vec_andc (vector bool int, vector bool int);
13790 vector signed int vec_andc (vector bool int, vector signed int);
13791 vector signed int vec_andc (vector signed int, vector bool int);
13792 vector signed int vec_andc (vector signed int, vector signed int);
13793 vector unsigned int vec_andc (vector bool int, vector unsigned int);
13794 vector unsigned int vec_andc (vector unsigned int, vector bool int);
13795 vector unsigned int vec_andc (vector unsigned int, vector unsigned int);
13796 vector bool short vec_andc (vector bool short, vector bool short);
13797 vector signed short vec_andc (vector bool short, vector signed short);
13798 vector signed short vec_andc (vector signed short, vector bool short);
13799 vector signed short vec_andc (vector signed short, vector signed short);
13800 vector unsigned short vec_andc (vector bool short,
13801 vector unsigned short);
13802 vector unsigned short vec_andc (vector unsigned short,
13803 vector bool short);
13804 vector unsigned short vec_andc (vector unsigned short,
13805 vector unsigned short);
13806 vector signed char vec_andc (vector bool char, vector signed char);
13807 vector bool char vec_andc (vector bool char, vector bool char);
13808 vector signed char vec_andc (vector signed char, vector bool char);
13809 vector signed char vec_andc (vector signed char, vector signed char);
13810 vector unsigned char vec_andc (vector bool char, vector unsigned char);
13811 vector unsigned char vec_andc (vector unsigned char, vector bool char);
13812 vector unsigned char vec_andc (vector unsigned char,
13813 vector unsigned char);
13815 vector unsigned char vec_avg (vector unsigned char,
13816 vector unsigned char);
13817 vector signed char vec_avg (vector signed char, vector signed char);
13818 vector unsigned short vec_avg (vector unsigned short,
13819 vector unsigned short);
13820 vector signed short vec_avg (vector signed short, vector signed short);
13821 vector unsigned int vec_avg (vector unsigned int, vector unsigned int);
13822 vector signed int vec_avg (vector signed int, vector signed int);
13824 vector signed int vec_vavgsw (vector signed int, vector signed int);
13826 vector unsigned int vec_vavguw (vector unsigned int,
13827 vector unsigned int);
13829 vector signed short vec_vavgsh (vector signed short,
13830 vector signed short);
13832 vector unsigned short vec_vavguh (vector unsigned short,
13833 vector unsigned short);
13835 vector signed char vec_vavgsb (vector signed char, vector signed char);
13837 vector unsigned char vec_vavgub (vector unsigned char,
13838 vector unsigned char);
13840 vector float vec_copysign (vector float);
13842 vector float vec_ceil (vector float);
13844 vector signed int vec_cmpb (vector float, vector float);
13846 vector bool char vec_cmpeq (vector signed char, vector signed char);
13847 vector bool char vec_cmpeq (vector unsigned char, vector unsigned char);
13848 vector bool short vec_cmpeq (vector signed short, vector signed short);
13849 vector bool short vec_cmpeq (vector unsigned short,
13850 vector unsigned short);
13851 vector bool int vec_cmpeq (vector signed int, vector signed int);
13852 vector bool int vec_cmpeq (vector unsigned int, vector unsigned int);
13853 vector bool int vec_cmpeq (vector float, vector float);
13855 vector bool int vec_vcmpeqfp (vector float, vector float);
13857 vector bool int vec_vcmpequw (vector signed int, vector signed int);
13858 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
13860 vector bool short vec_vcmpequh (vector signed short,
13861 vector signed short);
13862 vector bool short vec_vcmpequh (vector unsigned short,
13863 vector unsigned short);
13865 vector bool char vec_vcmpequb (vector signed char, vector signed char);
13866 vector bool char vec_vcmpequb (vector unsigned char,
13867 vector unsigned char);
13869 vector bool int vec_cmpge (vector float, vector float);
13871 vector bool char vec_cmpgt (vector unsigned char, vector unsigned char);
13872 vector bool char vec_cmpgt (vector signed char, vector signed char);
13873 vector bool short vec_cmpgt (vector unsigned short,
13874 vector unsigned short);
13875 vector bool short vec_cmpgt (vector signed short, vector signed short);
13876 vector bool int vec_cmpgt (vector unsigned int, vector unsigned int);
13877 vector bool int vec_cmpgt (vector signed int, vector signed int);
13878 vector bool int vec_cmpgt (vector float, vector float);
13880 vector bool int vec_vcmpgtfp (vector float, vector float);
13882 vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
13884 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
13886 vector bool short vec_vcmpgtsh (vector signed short,
13887 vector signed short);
13889 vector bool short vec_vcmpgtuh (vector unsigned short,
13890 vector unsigned short);
13892 vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
13894 vector bool char vec_vcmpgtub (vector unsigned char,
13895 vector unsigned char);
13897 vector bool int vec_cmple (vector float, vector float);
13899 vector bool char vec_cmplt (vector unsigned char, vector unsigned char);
13900 vector bool char vec_cmplt (vector signed char, vector signed char);
13901 vector bool short vec_cmplt (vector unsigned short,
13902 vector unsigned short);
13903 vector bool short vec_cmplt (vector signed short, vector signed short);
13904 vector bool int vec_cmplt (vector unsigned int, vector unsigned int);
13905 vector bool int vec_cmplt (vector signed int, vector signed int);
13906 vector bool int vec_cmplt (vector float, vector float);
13908 vector float vec_cpsgn (vector float, vector float);
13910 vector float vec_ctf (vector unsigned int, const int);
13911 vector float vec_ctf (vector signed int, const int);
13912 vector double vec_ctf (vector unsigned long, const int);
13913 vector double vec_ctf (vector signed long, const int);
13915 vector float vec_vcfsx (vector signed int, const int);
13917 vector float vec_vcfux (vector unsigned int, const int);
13919 vector signed int vec_cts (vector float, const int);
13920 vector signed long vec_cts (vector double, const int);
13922 vector unsigned int vec_ctu (vector float, const int);
13923 vector unsigned long vec_ctu (vector double, const int);
13925 void vec_dss (const int);
13927 void vec_dssall (void);
13929 void vec_dst (const vector unsigned char *, int, const int);
13930 void vec_dst (const vector signed char *, int, const int);
13931 void vec_dst (const vector bool char *, int, const int);
13932 void vec_dst (const vector unsigned short *, int, const int);
13933 void vec_dst (const vector signed short *, int, const int);
13934 void vec_dst (const vector bool short *, int, const int);
13935 void vec_dst (const vector pixel *, int, const int);
13936 void vec_dst (const vector unsigned int *, int, const int);
13937 void vec_dst (const vector signed int *, int, const int);
13938 void vec_dst (const vector bool int *, int, const int);
13939 void vec_dst (const vector float *, int, const int);
13940 void vec_dst (const unsigned char *, int, const int);
13941 void vec_dst (const signed char *, int, const int);
13942 void vec_dst (const unsigned short *, int, const int);
13943 void vec_dst (const short *, int, const int);
13944 void vec_dst (const unsigned int *, int, const int);
13945 void vec_dst (const int *, int, const int);
13946 void vec_dst (const unsigned long *, int, const int);
13947 void vec_dst (const long *, int, const int);
13948 void vec_dst (const float *, int, const int);
13950 void vec_dstst (const vector unsigned char *, int, const int);
13951 void vec_dstst (const vector signed char *, int, const int);
13952 void vec_dstst (const vector bool char *, int, const int);
13953 void vec_dstst (const vector unsigned short *, int, const int);
13954 void vec_dstst (const vector signed short *, int, const int);
13955 void vec_dstst (const vector bool short *, int, const int);
13956 void vec_dstst (const vector pixel *, int, const int);
13957 void vec_dstst (const vector unsigned int *, int, const int);
13958 void vec_dstst (const vector signed int *, int, const int);
13959 void vec_dstst (const vector bool int *, int, const int);
13960 void vec_dstst (const vector float *, int, const int);
13961 void vec_dstst (const unsigned char *, int, const int);
13962 void vec_dstst (const signed char *, int, const int);
13963 void vec_dstst (const unsigned short *, int, const int);
13964 void vec_dstst (const short *, int, const int);
13965 void vec_dstst (const unsigned int *, int, const int);
13966 void vec_dstst (const int *, int, const int);
13967 void vec_dstst (const unsigned long *, int, const int);
13968 void vec_dstst (const long *, int, const int);
13969 void vec_dstst (const float *, int, const int);
13971 void vec_dststt (const vector unsigned char *, int, const int);
13972 void vec_dststt (const vector signed char *, int, const int);
13973 void vec_dststt (const vector bool char *, int, const int);
13974 void vec_dststt (const vector unsigned short *, int, const int);
13975 void vec_dststt (const vector signed short *, int, const int);
13976 void vec_dststt (const vector bool short *, int, const int);
13977 void vec_dststt (const vector pixel *, int, const int);
13978 void vec_dststt (const vector unsigned int *, int, const int);
13979 void vec_dststt (const vector signed int *, int, const int);
13980 void vec_dststt (const vector bool int *, int, const int);
13981 void vec_dststt (const vector float *, int, const int);
13982 void vec_dststt (const unsigned char *, int, const int);
13983 void vec_dststt (const signed char *, int, const int);
13984 void vec_dststt (const unsigned short *, int, const int);
13985 void vec_dststt (const short *, int, const int);
13986 void vec_dststt (const unsigned int *, int, const int);
13987 void vec_dststt (const int *, int, const int);
13988 void vec_dststt (const unsigned long *, int, const int);
13989 void vec_dststt (const long *, int, const int);
13990 void vec_dststt (const float *, int, const int);
13992 void vec_dstt (const vector unsigned char *, int, const int);
13993 void vec_dstt (const vector signed char *, int, const int);
13994 void vec_dstt (const vector bool char *, int, const int);
13995 void vec_dstt (const vector unsigned short *, int, const int);
13996 void vec_dstt (const vector signed short *, int, const int);
13997 void vec_dstt (const vector bool short *, int, const int);
13998 void vec_dstt (const vector pixel *, int, const int);
13999 void vec_dstt (const vector unsigned int *, int, const int);
14000 void vec_dstt (const vector signed int *, int, const int);
14001 void vec_dstt (const vector bool int *, int, const int);
14002 void vec_dstt (const vector float *, int, const int);
14003 void vec_dstt (const unsigned char *, int, const int);
14004 void vec_dstt (const signed char *, int, const int);
14005 void vec_dstt (const unsigned short *, int, const int);
14006 void vec_dstt (const short *, int, const int);
14007 void vec_dstt (const unsigned int *, int, const int);
14008 void vec_dstt (const int *, int, const int);
14009 void vec_dstt (const unsigned long *, int, const int);
14010 void vec_dstt (const long *, int, const int);
14011 void vec_dstt (const float *, int, const int);
14013 vector float vec_expte (vector float);
14015 vector float vec_floor (vector float);
14017 vector float vec_ld (int, const vector float *);
14018 vector float vec_ld (int, const float *);
14019 vector bool int vec_ld (int, const vector bool int *);
14020 vector signed int vec_ld (int, const vector signed int *);
14021 vector signed int vec_ld (int, const int *);
14022 vector signed int vec_ld (int, const long *);
14023 vector unsigned int vec_ld (int, const vector unsigned int *);
14024 vector unsigned int vec_ld (int, const unsigned int *);
14025 vector unsigned int vec_ld (int, const unsigned long *);
14026 vector bool short vec_ld (int, const vector bool short *);
14027 vector pixel vec_ld (int, const vector pixel *);
14028 vector signed short vec_ld (int, const vector signed short *);
14029 vector signed short vec_ld (int, const short *);
14030 vector unsigned short vec_ld (int, const vector unsigned short *);
14031 vector unsigned short vec_ld (int, const unsigned short *);
14032 vector bool char vec_ld (int, const vector bool char *);
14033 vector signed char vec_ld (int, const vector signed char *);
14034 vector signed char vec_ld (int, const signed char *);
14035 vector unsigned char vec_ld (int, const vector unsigned char *);
14036 vector unsigned char vec_ld (int, const unsigned char *);
14038 vector signed char vec_lde (int, const signed char *);
14039 vector unsigned char vec_lde (int, const unsigned char *);
14040 vector signed short vec_lde (int, const short *);
14041 vector unsigned short vec_lde (int, const unsigned short *);
14042 vector float vec_lde (int, const float *);
14043 vector signed int vec_lde (int, const int *);
14044 vector unsigned int vec_lde (int, const unsigned int *);
14045 vector signed int vec_lde (int, const long *);
14046 vector unsigned int vec_lde (int, const unsigned long *);
14048 vector float vec_lvewx (int, float *);
14049 vector signed int vec_lvewx (int, int *);
14050 vector unsigned int vec_lvewx (int, unsigned int *);
14051 vector signed int vec_lvewx (int, long *);
14052 vector unsigned int vec_lvewx (int, unsigned long *);
14054 vector signed short vec_lvehx (int, short *);
14055 vector unsigned short vec_lvehx (int, unsigned short *);
14057 vector signed char vec_lvebx (int, char *);
14058 vector unsigned char vec_lvebx (int, unsigned char *);
14060 vector float vec_ldl (int, const vector float *);
14061 vector float vec_ldl (int, const float *);
14062 vector bool int vec_ldl (int, const vector bool int *);
14063 vector signed int vec_ldl (int, const vector signed int *);
14064 vector signed int vec_ldl (int, const int *);
14065 vector signed int vec_ldl (int, const long *);
14066 vector unsigned int vec_ldl (int, const vector unsigned int *);
14067 vector unsigned int vec_ldl (int, const unsigned int *);
14068 vector unsigned int vec_ldl (int, const unsigned long *);
14069 vector bool short vec_ldl (int, const vector bool short *);
14070 vector pixel vec_ldl (int, const vector pixel *);
14071 vector signed short vec_ldl (int, const vector signed short *);
14072 vector signed short vec_ldl (int, const short *);
14073 vector unsigned short vec_ldl (int, const vector unsigned short *);
14074 vector unsigned short vec_ldl (int, const unsigned short *);
14075 vector bool char vec_ldl (int, const vector bool char *);
14076 vector signed char vec_ldl (int, const vector signed char *);
14077 vector signed char vec_ldl (int, const signed char *);
14078 vector unsigned char vec_ldl (int, const vector unsigned char *);
14079 vector unsigned char vec_ldl (int, const unsigned char *);
14081 vector float vec_loge (vector float);
14083 vector unsigned char vec_lvsl (int, const volatile unsigned char *);
14084 vector unsigned char vec_lvsl (int, const volatile signed char *);
14085 vector unsigned char vec_lvsl (int, const volatile unsigned short *);
14086 vector unsigned char vec_lvsl (int, const volatile short *);
14087 vector unsigned char vec_lvsl (int, const volatile unsigned int *);
14088 vector unsigned char vec_lvsl (int, const volatile int *);
14089 vector unsigned char vec_lvsl (int, const volatile unsigned long *);
14090 vector unsigned char vec_lvsl (int, const volatile long *);
14091 vector unsigned char vec_lvsl (int, const volatile float *);
14093 vector unsigned char vec_lvsr (int, const volatile unsigned char *);
14094 vector unsigned char vec_lvsr (int, const volatile signed char *);
14095 vector unsigned char vec_lvsr (int, const volatile unsigned short *);
14096 vector unsigned char vec_lvsr (int, const volatile short *);
14097 vector unsigned char vec_lvsr (int, const volatile unsigned int *);
14098 vector unsigned char vec_lvsr (int, const volatile int *);
14099 vector unsigned char vec_lvsr (int, const volatile unsigned long *);
14100 vector unsigned char vec_lvsr (int, const volatile long *);
14101 vector unsigned char vec_lvsr (int, const volatile float *);
14103 vector float vec_madd (vector float, vector float, vector float);
14105 vector signed short vec_madds (vector signed short,
14106 vector signed short,
14107 vector signed short);
14109 vector unsigned char vec_max (vector bool char, vector unsigned char);
14110 vector unsigned char vec_max (vector unsigned char, vector bool char);
14111 vector unsigned char vec_max (vector unsigned char,
14112 vector unsigned char);
14113 vector signed char vec_max (vector bool char, vector signed char);
14114 vector signed char vec_max (vector signed char, vector bool char);
14115 vector signed char vec_max (vector signed char, vector signed char);
14116 vector unsigned short vec_max (vector bool short,
14117 vector unsigned short);
14118 vector unsigned short vec_max (vector unsigned short,
14119 vector bool short);
14120 vector unsigned short vec_max (vector unsigned short,
14121 vector unsigned short);
14122 vector signed short vec_max (vector bool short, vector signed short);
14123 vector signed short vec_max (vector signed short, vector bool short);
14124 vector signed short vec_max (vector signed short, vector signed short);
14125 vector unsigned int vec_max (vector bool int, vector unsigned int);
14126 vector unsigned int vec_max (vector unsigned int, vector bool int);
14127 vector unsigned int vec_max (vector unsigned int, vector unsigned int);
14128 vector signed int vec_max (vector bool int, vector signed int);
14129 vector signed int vec_max (vector signed int, vector bool int);
14130 vector signed int vec_max (vector signed int, vector signed int);
14131 vector float vec_max (vector float, vector float);
14133 vector float vec_vmaxfp (vector float, vector float);
14135 vector signed int vec_vmaxsw (vector bool int, vector signed int);
14136 vector signed int vec_vmaxsw (vector signed int, vector bool int);
14137 vector signed int vec_vmaxsw (vector signed int, vector signed int);
14139 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
14140 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
14141 vector unsigned int vec_vmaxuw (vector unsigned int,
14142 vector unsigned int);
14144 vector signed short vec_vmaxsh (vector bool short, vector signed short);
14145 vector signed short vec_vmaxsh (vector signed short, vector bool short);
14146 vector signed short vec_vmaxsh (vector signed short,
14147 vector signed short);
14149 vector unsigned short vec_vmaxuh (vector bool short,
14150 vector unsigned short);
14151 vector unsigned short vec_vmaxuh (vector unsigned short,
14152 vector bool short);
14153 vector unsigned short vec_vmaxuh (vector unsigned short,
14154 vector unsigned short);
14156 vector signed char vec_vmaxsb (vector bool char, vector signed char);
14157 vector signed char vec_vmaxsb (vector signed char, vector bool char);
14158 vector signed char vec_vmaxsb (vector signed char, vector signed char);
14160 vector unsigned char vec_vmaxub (vector bool char,
14161 vector unsigned char);
14162 vector unsigned char vec_vmaxub (vector unsigned char,
14164 vector unsigned char vec_vmaxub (vector unsigned char,
14165 vector unsigned char);
14167 vector bool char vec_mergeh (vector bool char, vector bool char);
14168 vector signed char vec_mergeh (vector signed char, vector signed char);
14169 vector unsigned char vec_mergeh (vector unsigned char,
14170 vector unsigned char);
14171 vector bool short vec_mergeh (vector bool short, vector bool short);
14172 vector pixel vec_mergeh (vector pixel, vector pixel);
14173 vector signed short vec_mergeh (vector signed short,
14174 vector signed short);
14175 vector unsigned short vec_mergeh (vector unsigned short,
14176 vector unsigned short);
14177 vector float vec_mergeh (vector float, vector float);
14178 vector bool int vec_mergeh (vector bool int, vector bool int);
14179 vector signed int vec_mergeh (vector signed int, vector signed int);
14180 vector unsigned int vec_mergeh (vector unsigned int,
14181 vector unsigned int);
14183 vector float vec_vmrghw (vector float, vector float);
14184 vector bool int vec_vmrghw (vector bool int, vector bool int);
14185 vector signed int vec_vmrghw (vector signed int, vector signed int);
14186 vector unsigned int vec_vmrghw (vector unsigned int,
14187 vector unsigned int);
14189 vector bool short vec_vmrghh (vector bool short, vector bool short);
14190 vector signed short vec_vmrghh (vector signed short,
14191 vector signed short);
14192 vector unsigned short vec_vmrghh (vector unsigned short,
14193 vector unsigned short);
14194 vector pixel vec_vmrghh (vector pixel, vector pixel);
14196 vector bool char vec_vmrghb (vector bool char, vector bool char);
14197 vector signed char vec_vmrghb (vector signed char, vector signed char);
14198 vector unsigned char vec_vmrghb (vector unsigned char,
14199 vector unsigned char);
14201 vector bool char vec_mergel (vector bool char, vector bool char);
14202 vector signed char vec_mergel (vector signed char, vector signed char);
14203 vector unsigned char vec_mergel (vector unsigned char,
14204 vector unsigned char);
14205 vector bool short vec_mergel (vector bool short, vector bool short);
14206 vector pixel vec_mergel (vector pixel, vector pixel);
14207 vector signed short vec_mergel (vector signed short,
14208 vector signed short);
14209 vector unsigned short vec_mergel (vector unsigned short,
14210 vector unsigned short);
14211 vector float vec_mergel (vector float, vector float);
14212 vector bool int vec_mergel (vector bool int, vector bool int);
14213 vector signed int vec_mergel (vector signed int, vector signed int);
14214 vector unsigned int vec_mergel (vector unsigned int,
14215 vector unsigned int);
14217 vector float vec_vmrglw (vector float, vector float);
14218 vector signed int vec_vmrglw (vector signed int, vector signed int);
14219 vector unsigned int vec_vmrglw (vector unsigned int,
14220 vector unsigned int);
14221 vector bool int vec_vmrglw (vector bool int, vector bool int);
14223 vector bool short vec_vmrglh (vector bool short, vector bool short);
14224 vector signed short vec_vmrglh (vector signed short,
14225 vector signed short);
14226 vector unsigned short vec_vmrglh (vector unsigned short,
14227 vector unsigned short);
14228 vector pixel vec_vmrglh (vector pixel, vector pixel);
14230 vector bool char vec_vmrglb (vector bool char, vector bool char);
14231 vector signed char vec_vmrglb (vector signed char, vector signed char);
14232 vector unsigned char vec_vmrglb (vector unsigned char,
14233 vector unsigned char);
14235 vector unsigned short vec_mfvscr (void);
14237 vector unsigned char vec_min (vector bool char, vector unsigned char);
14238 vector unsigned char vec_min (vector unsigned char, vector bool char);
14239 vector unsigned char vec_min (vector unsigned char,
14240 vector unsigned char);
14241 vector signed char vec_min (vector bool char, vector signed char);
14242 vector signed char vec_min (vector signed char, vector bool char);
14243 vector signed char vec_min (vector signed char, vector signed char);
14244 vector unsigned short vec_min (vector bool short,
14245 vector unsigned short);
14246 vector unsigned short vec_min (vector unsigned short,
14247 vector bool short);
14248 vector unsigned short vec_min (vector unsigned short,
14249 vector unsigned short);
14250 vector signed short vec_min (vector bool short, vector signed short);
14251 vector signed short vec_min (vector signed short, vector bool short);
14252 vector signed short vec_min (vector signed short, vector signed short);
14253 vector unsigned int vec_min (vector bool int, vector unsigned int);
14254 vector unsigned int vec_min (vector unsigned int, vector bool int);
14255 vector unsigned int vec_min (vector unsigned int, vector unsigned int);
14256 vector signed int vec_min (vector bool int, vector signed int);
14257 vector signed int vec_min (vector signed int, vector bool int);
14258 vector signed int vec_min (vector signed int, vector signed int);
14259 vector float vec_min (vector float, vector float);
14261 vector float vec_vminfp (vector float, vector float);
14263 vector signed int vec_vminsw (vector bool int, vector signed int);
14264 vector signed int vec_vminsw (vector signed int, vector bool int);
14265 vector signed int vec_vminsw (vector signed int, vector signed int);
14267 vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
14268 vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
14269 vector unsigned int vec_vminuw (vector unsigned int,
14270 vector unsigned int);
14272 vector signed short vec_vminsh (vector bool short, vector signed short);
14273 vector signed short vec_vminsh (vector signed short, vector bool short);
14274 vector signed short vec_vminsh (vector signed short,
14275 vector signed short);
14277 vector unsigned short vec_vminuh (vector bool short,
14278 vector unsigned short);
14279 vector unsigned short vec_vminuh (vector unsigned short,
14280 vector bool short);
14281 vector unsigned short vec_vminuh (vector unsigned short,
14282 vector unsigned short);
14284 vector signed char vec_vminsb (vector bool char, vector signed char);
14285 vector signed char vec_vminsb (vector signed char, vector bool char);
14286 vector signed char vec_vminsb (vector signed char, vector signed char);
14288 vector unsigned char vec_vminub (vector bool char,
14289 vector unsigned char);
14290 vector unsigned char vec_vminub (vector unsigned char,
14292 vector unsigned char vec_vminub (vector unsigned char,
14293 vector unsigned char);
14295 vector signed short vec_mladd (vector signed short,
14296 vector signed short,
14297 vector signed short);
14298 vector signed short vec_mladd (vector signed short,
14299 vector unsigned short,
14300 vector unsigned short);
14301 vector signed short vec_mladd (vector unsigned short,
14302 vector signed short,
14303 vector signed short);
14304 vector unsigned short vec_mladd (vector unsigned short,
14305 vector unsigned short,
14306 vector unsigned short);
14308 vector signed short vec_mradds (vector signed short,
14309 vector signed short,
14310 vector signed short);
14312 vector unsigned int vec_msum (vector unsigned char,
14313 vector unsigned char,
14314 vector unsigned int);
14315 vector signed int vec_msum (vector signed char,
14316 vector unsigned char,
14317 vector signed int);
14318 vector unsigned int vec_msum (vector unsigned short,
14319 vector unsigned short,
14320 vector unsigned int);
14321 vector signed int vec_msum (vector signed short,
14322 vector signed short,
14323 vector signed int);
14325 vector signed int vec_vmsumshm (vector signed short,
14326 vector signed short,
14327 vector signed int);
14329 vector unsigned int vec_vmsumuhm (vector unsigned short,
14330 vector unsigned short,
14331 vector unsigned int);
14333 vector signed int vec_vmsummbm (vector signed char,
14334 vector unsigned char,
14335 vector signed int);
14337 vector unsigned int vec_vmsumubm (vector unsigned char,
14338 vector unsigned char,
14339 vector unsigned int);
14341 vector unsigned int vec_msums (vector unsigned short,
14342 vector unsigned short,
14343 vector unsigned int);
14344 vector signed int vec_msums (vector signed short,
14345 vector signed short,
14346 vector signed int);
14348 vector signed int vec_vmsumshs (vector signed short,
14349 vector signed short,
14350 vector signed int);
14352 vector unsigned int vec_vmsumuhs (vector unsigned short,
14353 vector unsigned short,
14354 vector unsigned int);
14356 void vec_mtvscr (vector signed int);
14357 void vec_mtvscr (vector unsigned int);
14358 void vec_mtvscr (vector bool int);
14359 void vec_mtvscr (vector signed short);
14360 void vec_mtvscr (vector unsigned short);
14361 void vec_mtvscr (vector bool short);
14362 void vec_mtvscr (vector pixel);
14363 void vec_mtvscr (vector signed char);
14364 void vec_mtvscr (vector unsigned char);
14365 void vec_mtvscr (vector bool char);
14367 vector unsigned short vec_mule (vector unsigned char,
14368 vector unsigned char);
14369 vector signed short vec_mule (vector signed char,
14370 vector signed char);
14371 vector unsigned int vec_mule (vector unsigned short,
14372 vector unsigned short);
14373 vector signed int vec_mule (vector signed short, vector signed short);
14375 vector signed int vec_vmulesh (vector signed short,
14376 vector signed short);
14378 vector unsigned int vec_vmuleuh (vector unsigned short,
14379 vector unsigned short);
14381 vector signed short vec_vmulesb (vector signed char,
14382 vector signed char);
14384 vector unsigned short vec_vmuleub (vector unsigned char,
14385 vector unsigned char);
14387 vector unsigned short vec_mulo (vector unsigned char,
14388 vector unsigned char);
14389 vector signed short vec_mulo (vector signed char, vector signed char);
14390 vector unsigned int vec_mulo (vector unsigned short,
14391 vector unsigned short);
14392 vector signed int vec_mulo (vector signed short, vector signed short);
14394 vector signed int vec_vmulosh (vector signed short,
14395 vector signed short);
14397 vector unsigned int vec_vmulouh (vector unsigned short,
14398 vector unsigned short);
14400 vector signed short vec_vmulosb (vector signed char,
14401 vector signed char);
14403 vector unsigned short vec_vmuloub (vector unsigned char,
14404 vector unsigned char);
14406 vector float vec_nmsub (vector float, vector float, vector float);
14408 vector float vec_nor (vector float, vector float);
14409 vector signed int vec_nor (vector signed int, vector signed int);
14410 vector unsigned int vec_nor (vector unsigned int, vector unsigned int);
14411 vector bool int vec_nor (vector bool int, vector bool int);
14412 vector signed short vec_nor (vector signed short, vector signed short);
14413 vector unsigned short vec_nor (vector unsigned short,
14414 vector unsigned short);
14415 vector bool short vec_nor (vector bool short, vector bool short);
14416 vector signed char vec_nor (vector signed char, vector signed char);
14417 vector unsigned char vec_nor (vector unsigned char,
14418 vector unsigned char);
14419 vector bool char vec_nor (vector bool char, vector bool char);
14421 vector float vec_or (vector float, vector float);
14422 vector float vec_or (vector float, vector bool int);
14423 vector float vec_or (vector bool int, vector float);
14424 vector bool int vec_or (vector bool int, vector bool int);
14425 vector signed int vec_or (vector bool int, vector signed int);
14426 vector signed int vec_or (vector signed int, vector bool int);
14427 vector signed int vec_or (vector signed int, vector signed int);
14428 vector unsigned int vec_or (vector bool int, vector unsigned int);
14429 vector unsigned int vec_or (vector unsigned int, vector bool int);
14430 vector unsigned int vec_or (vector unsigned int, vector unsigned int);
14431 vector bool short vec_or (vector bool short, vector bool short);
14432 vector signed short vec_or (vector bool short, vector signed short);
14433 vector signed short vec_or (vector signed short, vector bool short);
14434 vector signed short vec_or (vector signed short, vector signed short);
14435 vector unsigned short vec_or (vector bool short, vector unsigned short);
14436 vector unsigned short vec_or (vector unsigned short, vector bool short);
14437 vector unsigned short vec_or (vector unsigned short,
14438 vector unsigned short);
14439 vector signed char vec_or (vector bool char, vector signed char);
14440 vector bool char vec_or (vector bool char, vector bool char);
14441 vector signed char vec_or (vector signed char, vector bool char);
14442 vector signed char vec_or (vector signed char, vector signed char);
14443 vector unsigned char vec_or (vector bool char, vector unsigned char);
14444 vector unsigned char vec_or (vector unsigned char, vector bool char);
14445 vector unsigned char vec_or (vector unsigned char,
14446 vector unsigned char);
14448 vector signed char vec_pack (vector signed short, vector signed short);
14449 vector unsigned char vec_pack (vector unsigned short,
14450 vector unsigned short);
14451 vector bool char vec_pack (vector bool short, vector bool short);
14452 vector signed short vec_pack (vector signed int, vector signed int);
14453 vector unsigned short vec_pack (vector unsigned int,
14454 vector unsigned int);
14455 vector bool short vec_pack (vector bool int, vector bool int);
14457 vector bool short vec_vpkuwum (vector bool int, vector bool int);
14458 vector signed short vec_vpkuwum (vector signed int, vector signed int);
14459 vector unsigned short vec_vpkuwum (vector unsigned int,
14460 vector unsigned int);
14462 vector bool char vec_vpkuhum (vector bool short, vector bool short);
14463 vector signed char vec_vpkuhum (vector signed short,
14464 vector signed short);
14465 vector unsigned char vec_vpkuhum (vector unsigned short,
14466 vector unsigned short);
14468 vector pixel vec_packpx (vector unsigned int, vector unsigned int);
14470 vector unsigned char vec_packs (vector unsigned short,
14471 vector unsigned short);
14472 vector signed char vec_packs (vector signed short, vector signed short);
14473 vector unsigned short vec_packs (vector unsigned int,
14474 vector unsigned int);
14475 vector signed short vec_packs (vector signed int, vector signed int);
14477 vector signed short vec_vpkswss (vector signed int, vector signed int);
14479 vector unsigned short vec_vpkuwus (vector unsigned int,
14480 vector unsigned int);
14482 vector signed char vec_vpkshss (vector signed short,
14483 vector signed short);
14485 vector unsigned char vec_vpkuhus (vector unsigned short,
14486 vector unsigned short);
14488 vector unsigned char vec_packsu (vector unsigned short,
14489 vector unsigned short);
14490 vector unsigned char vec_packsu (vector signed short,
14491 vector signed short);
14492 vector unsigned short vec_packsu (vector unsigned int,
14493 vector unsigned int);
14494 vector unsigned short vec_packsu (vector signed int, vector signed int);
14496 vector unsigned short vec_vpkswus (vector signed int,
14497 vector signed int);
14499 vector unsigned char vec_vpkshus (vector signed short,
14500 vector signed short);
14502 vector float vec_perm (vector float,
14504 vector unsigned char);
14505 vector signed int vec_perm (vector signed int,
14507 vector unsigned char);
14508 vector unsigned int vec_perm (vector unsigned int,
14509 vector unsigned int,
14510 vector unsigned char);
14511 vector bool int vec_perm (vector bool int,
14513 vector unsigned char);
14514 vector signed short vec_perm (vector signed short,
14515 vector signed short,
14516 vector unsigned char);
14517 vector unsigned short vec_perm (vector unsigned short,
14518 vector unsigned short,
14519 vector unsigned char);
14520 vector bool short vec_perm (vector bool short,
14522 vector unsigned char);
14523 vector pixel vec_perm (vector pixel,
14525 vector unsigned char);
14526 vector signed char vec_perm (vector signed char,
14527 vector signed char,
14528 vector unsigned char);
14529 vector unsigned char vec_perm (vector unsigned char,
14530 vector unsigned char,
14531 vector unsigned char);
14532 vector bool char vec_perm (vector bool char,
14534 vector unsigned char);
14536 vector float vec_re (vector float);
14538 vector signed char vec_rl (vector signed char,
14539 vector unsigned char);
14540 vector unsigned char vec_rl (vector unsigned char,
14541 vector unsigned char);
14542 vector signed short vec_rl (vector signed short, vector unsigned short);
14543 vector unsigned short vec_rl (vector unsigned short,
14544 vector unsigned short);
14545 vector signed int vec_rl (vector signed int, vector unsigned int);
14546 vector unsigned int vec_rl (vector unsigned int, vector unsigned int);
14548 vector signed int vec_vrlw (vector signed int, vector unsigned int);
14549 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
14551 vector signed short vec_vrlh (vector signed short,
14552 vector unsigned short);
14553 vector unsigned short vec_vrlh (vector unsigned short,
14554 vector unsigned short);
14556 vector signed char vec_vrlb (vector signed char, vector unsigned char);
14557 vector unsigned char vec_vrlb (vector unsigned char,
14558 vector unsigned char);
14560 vector float vec_round (vector float);
14562 vector float vec_recip (vector float, vector float);
14564 vector float vec_rsqrt (vector float);
14566 vector float vec_rsqrte (vector float);
14568 vector float vec_sel (vector float, vector float, vector bool int);
14569 vector float vec_sel (vector float, vector float, vector unsigned int);
14570 vector signed int vec_sel (vector signed int,
14573 vector signed int vec_sel (vector signed int,
14575 vector unsigned int);
14576 vector unsigned int vec_sel (vector unsigned int,
14577 vector unsigned int,
14579 vector unsigned int vec_sel (vector unsigned int,
14580 vector unsigned int,
14581 vector unsigned int);
14582 vector bool int vec_sel (vector bool int,
14585 vector bool int vec_sel (vector bool int,
14587 vector unsigned int);
14588 vector signed short vec_sel (vector signed short,
14589 vector signed short,
14590 vector bool short);
14591 vector signed short vec_sel (vector signed short,
14592 vector signed short,
14593 vector unsigned short);
14594 vector unsigned short vec_sel (vector unsigned short,
14595 vector unsigned short,
14596 vector bool short);
14597 vector unsigned short vec_sel (vector unsigned short,
14598 vector unsigned short,
14599 vector unsigned short);
14600 vector bool short vec_sel (vector bool short,
14602 vector bool short);
14603 vector bool short vec_sel (vector bool short,
14605 vector unsigned short);
14606 vector signed char vec_sel (vector signed char,
14607 vector signed char,
14609 vector signed char vec_sel (vector signed char,
14610 vector signed char,
14611 vector unsigned char);
14612 vector unsigned char vec_sel (vector unsigned char,
14613 vector unsigned char,
14615 vector unsigned char vec_sel (vector unsigned char,
14616 vector unsigned char,
14617 vector unsigned char);
14618 vector bool char vec_sel (vector bool char,
14621 vector bool char vec_sel (vector bool char,
14623 vector unsigned char);
14625 vector signed char vec_sl (vector signed char,
14626 vector unsigned char);
14627 vector unsigned char vec_sl (vector unsigned char,
14628 vector unsigned char);
14629 vector signed short vec_sl (vector signed short, vector unsigned short);
14630 vector unsigned short vec_sl (vector unsigned short,
14631 vector unsigned short);
14632 vector signed int vec_sl (vector signed int, vector unsigned int);
14633 vector unsigned int vec_sl (vector unsigned int, vector unsigned int);
14635 vector signed int vec_vslw (vector signed int, vector unsigned int);
14636 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
14638 vector signed short vec_vslh (vector signed short,
14639 vector unsigned short);
14640 vector unsigned short vec_vslh (vector unsigned short,
14641 vector unsigned short);
14643 vector signed char vec_vslb (vector signed char, vector unsigned char);
14644 vector unsigned char vec_vslb (vector unsigned char,
14645 vector unsigned char);
14647 vector float vec_sld (vector float, vector float, const int);
14648 vector signed int vec_sld (vector signed int,
14651 vector unsigned int vec_sld (vector unsigned int,
14652 vector unsigned int,
14654 vector bool int vec_sld (vector bool int,
14657 vector signed short vec_sld (vector signed short,
14658 vector signed short,
14660 vector unsigned short vec_sld (vector unsigned short,
14661 vector unsigned short,
14663 vector bool short vec_sld (vector bool short,
14666 vector pixel vec_sld (vector pixel,
14669 vector signed char vec_sld (vector signed char,
14670 vector signed char,
14672 vector unsigned char vec_sld (vector unsigned char,
14673 vector unsigned char,
14675 vector bool char vec_sld (vector bool char,
14679 vector signed int vec_sll (vector signed int,
14680 vector unsigned int);
14681 vector signed int vec_sll (vector signed int,
14682 vector unsigned short);
14683 vector signed int vec_sll (vector signed int,
14684 vector unsigned char);
14685 vector unsigned int vec_sll (vector unsigned int,
14686 vector unsigned int);
14687 vector unsigned int vec_sll (vector unsigned int,
14688 vector unsigned short);
14689 vector unsigned int vec_sll (vector unsigned int,
14690 vector unsigned char);
14691 vector bool int vec_sll (vector bool int,
14692 vector unsigned int);
14693 vector bool int vec_sll (vector bool int,
14694 vector unsigned short);
14695 vector bool int vec_sll (vector bool int,
14696 vector unsigned char);
14697 vector signed short vec_sll (vector signed short,
14698 vector unsigned int);
14699 vector signed short vec_sll (vector signed short,
14700 vector unsigned short);
14701 vector signed short vec_sll (vector signed short,
14702 vector unsigned char);
14703 vector unsigned short vec_sll (vector unsigned short,
14704 vector unsigned int);
14705 vector unsigned short vec_sll (vector unsigned short,
14706 vector unsigned short);
14707 vector unsigned short vec_sll (vector unsigned short,
14708 vector unsigned char);
14709 vector bool short vec_sll (vector bool short, vector unsigned int);
14710 vector bool short vec_sll (vector bool short, vector unsigned short);
14711 vector bool short vec_sll (vector bool short, vector unsigned char);
14712 vector pixel vec_sll (vector pixel, vector unsigned int);
14713 vector pixel vec_sll (vector pixel, vector unsigned short);
14714 vector pixel vec_sll (vector pixel, vector unsigned char);
14715 vector signed char vec_sll (vector signed char, vector unsigned int);
14716 vector signed char vec_sll (vector signed char, vector unsigned short);
14717 vector signed char vec_sll (vector signed char, vector unsigned char);
14718 vector unsigned char vec_sll (vector unsigned char,
14719 vector unsigned int);
14720 vector unsigned char vec_sll (vector unsigned char,
14721 vector unsigned short);
14722 vector unsigned char vec_sll (vector unsigned char,
14723 vector unsigned char);
14724 vector bool char vec_sll (vector bool char, vector unsigned int);
14725 vector bool char vec_sll (vector bool char, vector unsigned short);
14726 vector bool char vec_sll (vector bool char, vector unsigned char);
14728 vector float vec_slo (vector float, vector signed char);
14729 vector float vec_slo (vector float, vector unsigned char);
14730 vector signed int vec_slo (vector signed int, vector signed char);
14731 vector signed int vec_slo (vector signed int, vector unsigned char);
14732 vector unsigned int vec_slo (vector unsigned int, vector signed char);
14733 vector unsigned int vec_slo (vector unsigned int, vector unsigned char);
14734 vector signed short vec_slo (vector signed short, vector signed char);
14735 vector signed short vec_slo (vector signed short, vector unsigned char);
14736 vector unsigned short vec_slo (vector unsigned short,
14737 vector signed char);
14738 vector unsigned short vec_slo (vector unsigned short,
14739 vector unsigned char);
14740 vector pixel vec_slo (vector pixel, vector signed char);
14741 vector pixel vec_slo (vector pixel, vector unsigned char);
14742 vector signed char vec_slo (vector signed char, vector signed char);
14743 vector signed char vec_slo (vector signed char, vector unsigned char);
14744 vector unsigned char vec_slo (vector unsigned char, vector signed char);
14745 vector unsigned char vec_slo (vector unsigned char,
14746 vector unsigned char);
14748 vector signed char vec_splat (vector signed char, const int);
14749 vector unsigned char vec_splat (vector unsigned char, const int);
14750 vector bool char vec_splat (vector bool char, const int);
14751 vector signed short vec_splat (vector signed short, const int);
14752 vector unsigned short vec_splat (vector unsigned short, const int);
14753 vector bool short vec_splat (vector bool short, const int);
14754 vector pixel vec_splat (vector pixel, const int);
14755 vector float vec_splat (vector float, const int);
14756 vector signed int vec_splat (vector signed int, const int);
14757 vector unsigned int vec_splat (vector unsigned int, const int);
14758 vector bool int vec_splat (vector bool int, const int);
14759 vector signed long vec_splat (vector signed long, const int);
14760 vector unsigned long vec_splat (vector unsigned long, const int);
14762 vector signed char vec_splats (signed char);
14763 vector unsigned char vec_splats (unsigned char);
14764 vector signed short vec_splats (signed short);
14765 vector unsigned short vec_splats (unsigned short);
14766 vector signed int vec_splats (signed int);
14767 vector unsigned int vec_splats (unsigned int);
14768 vector float vec_splats (float);
14770 vector float vec_vspltw (vector float, const int);
14771 vector signed int vec_vspltw (vector signed int, const int);
14772 vector unsigned int vec_vspltw (vector unsigned int, const int);
14773 vector bool int vec_vspltw (vector bool int, const int);
14775 vector bool short vec_vsplth (vector bool short, const int);
14776 vector signed short vec_vsplth (vector signed short, const int);
14777 vector unsigned short vec_vsplth (vector unsigned short, const int);
14778 vector pixel vec_vsplth (vector pixel, const int);
14780 vector signed char vec_vspltb (vector signed char, const int);
14781 vector unsigned char vec_vspltb (vector unsigned char, const int);
14782 vector bool char vec_vspltb (vector bool char, const int);
14784 vector signed char vec_splat_s8 (const int);
14786 vector signed short vec_splat_s16 (const int);
14788 vector signed int vec_splat_s32 (const int);
14790 vector unsigned char vec_splat_u8 (const int);
14792 vector unsigned short vec_splat_u16 (const int);
14794 vector unsigned int vec_splat_u32 (const int);
14796 vector signed char vec_sr (vector signed char, vector unsigned char);
14797 vector unsigned char vec_sr (vector unsigned char,
14798 vector unsigned char);
14799 vector signed short vec_sr (vector signed short,
14800 vector unsigned short);
14801 vector unsigned short vec_sr (vector unsigned short,
14802 vector unsigned short);
14803 vector signed int vec_sr (vector signed int, vector unsigned int);
14804 vector unsigned int vec_sr (vector unsigned int, vector unsigned int);
14806 vector signed int vec_vsrw (vector signed int, vector unsigned int);
14807 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
14809 vector signed short vec_vsrh (vector signed short,
14810 vector unsigned short);
14811 vector unsigned short vec_vsrh (vector unsigned short,
14812 vector unsigned short);
14814 vector signed char vec_vsrb (vector signed char, vector unsigned char);
14815 vector unsigned char vec_vsrb (vector unsigned char,
14816 vector unsigned char);
14818 vector signed char vec_sra (vector signed char, vector unsigned char);
14819 vector unsigned char vec_sra (vector unsigned char,
14820 vector unsigned char);
14821 vector signed short vec_sra (vector signed short,
14822 vector unsigned short);
14823 vector unsigned short vec_sra (vector unsigned short,
14824 vector unsigned short);
14825 vector signed int vec_sra (vector signed int, vector unsigned int);
14826 vector unsigned int vec_sra (vector unsigned int, vector unsigned int);
14828 vector signed int vec_vsraw (vector signed int, vector unsigned int);
14829 vector unsigned int vec_vsraw (vector unsigned int,
14830 vector unsigned int);
14832 vector signed short vec_vsrah (vector signed short,
14833 vector unsigned short);
14834 vector unsigned short vec_vsrah (vector unsigned short,
14835 vector unsigned short);
14837 vector signed char vec_vsrab (vector signed char, vector unsigned char);
14838 vector unsigned char vec_vsrab (vector unsigned char,
14839 vector unsigned char);
14841 vector signed int vec_srl (vector signed int, vector unsigned int);
14842 vector signed int vec_srl (vector signed int, vector unsigned short);
14843 vector signed int vec_srl (vector signed int, vector unsigned char);
14844 vector unsigned int vec_srl (vector unsigned int, vector unsigned int);
14845 vector unsigned int vec_srl (vector unsigned int,
14846 vector unsigned short);
14847 vector unsigned int vec_srl (vector unsigned int, vector unsigned char);
14848 vector bool int vec_srl (vector bool int, vector unsigned int);
14849 vector bool int vec_srl (vector bool int, vector unsigned short);
14850 vector bool int vec_srl (vector bool int, vector unsigned char);
14851 vector signed short vec_srl (vector signed short, vector unsigned int);
14852 vector signed short vec_srl (vector signed short,
14853 vector unsigned short);
14854 vector signed short vec_srl (vector signed short, vector unsigned char);
14855 vector unsigned short vec_srl (vector unsigned short,
14856 vector unsigned int);
14857 vector unsigned short vec_srl (vector unsigned short,
14858 vector unsigned short);
14859 vector unsigned short vec_srl (vector unsigned short,
14860 vector unsigned char);
14861 vector bool short vec_srl (vector bool short, vector unsigned int);
14862 vector bool short vec_srl (vector bool short, vector unsigned short);
14863 vector bool short vec_srl (vector bool short, vector unsigned char);
14864 vector pixel vec_srl (vector pixel, vector unsigned int);
14865 vector pixel vec_srl (vector pixel, vector unsigned short);
14866 vector pixel vec_srl (vector pixel, vector unsigned char);
14867 vector signed char vec_srl (vector signed char, vector unsigned int);
14868 vector signed char vec_srl (vector signed char, vector unsigned short);
14869 vector signed char vec_srl (vector signed char, vector unsigned char);
14870 vector unsigned char vec_srl (vector unsigned char,
14871 vector unsigned int);
14872 vector unsigned char vec_srl (vector unsigned char,
14873 vector unsigned short);
14874 vector unsigned char vec_srl (vector unsigned char,
14875 vector unsigned char);
14876 vector bool char vec_srl (vector bool char, vector unsigned int);
14877 vector bool char vec_srl (vector bool char, vector unsigned short);
14878 vector bool char vec_srl (vector bool char, vector unsigned char);
14880 vector float vec_sro (vector float, vector signed char);
14881 vector float vec_sro (vector float, vector unsigned char);
14882 vector signed int vec_sro (vector signed int, vector signed char);
14883 vector signed int vec_sro (vector signed int, vector unsigned char);
14884 vector unsigned int vec_sro (vector unsigned int, vector signed char);
14885 vector unsigned int vec_sro (vector unsigned int, vector unsigned char);
14886 vector signed short vec_sro (vector signed short, vector signed char);
14887 vector signed short vec_sro (vector signed short, vector unsigned char);
14888 vector unsigned short vec_sro (vector unsigned short,
14889 vector signed char);
14890 vector unsigned short vec_sro (vector unsigned short,
14891 vector unsigned char);
14892 vector pixel vec_sro (vector pixel, vector signed char);
14893 vector pixel vec_sro (vector pixel, vector unsigned char);
14894 vector signed char vec_sro (vector signed char, vector signed char);
14895 vector signed char vec_sro (vector signed char, vector unsigned char);
14896 vector unsigned char vec_sro (vector unsigned char, vector signed char);
14897 vector unsigned char vec_sro (vector unsigned char,
14898 vector unsigned char);
14900 void vec_st (vector float, int, vector float *);
14901 void vec_st (vector float, int, float *);
14902 void vec_st (vector signed int, int, vector signed int *);
14903 void vec_st (vector signed int, int, int *);
14904 void vec_st (vector unsigned int, int, vector unsigned int *);
14905 void vec_st (vector unsigned int, int, unsigned int *);
14906 void vec_st (vector bool int, int, vector bool int *);
14907 void vec_st (vector bool int, int, unsigned int *);
14908 void vec_st (vector bool int, int, int *);
14909 void vec_st (vector signed short, int, vector signed short *);
14910 void vec_st (vector signed short, int, short *);
14911 void vec_st (vector unsigned short, int, vector unsigned short *);
14912 void vec_st (vector unsigned short, int, unsigned short *);
14913 void vec_st (vector bool short, int, vector bool short *);
14914 void vec_st (vector bool short, int, unsigned short *);
14915 void vec_st (vector pixel, int, vector pixel *);
14916 void vec_st (vector pixel, int, unsigned short *);
14917 void vec_st (vector pixel, int, short *);
14918 void vec_st (vector bool short, int, short *);
14919 void vec_st (vector signed char, int, vector signed char *);
14920 void vec_st (vector signed char, int, signed char *);
14921 void vec_st (vector unsigned char, int, vector unsigned char *);
14922 void vec_st (vector unsigned char, int, unsigned char *);
14923 void vec_st (vector bool char, int, vector bool char *);
14924 void vec_st (vector bool char, int, unsigned char *);
14925 void vec_st (vector bool char, int, signed char *);
14927 void vec_ste (vector signed char, int, signed char *);
14928 void vec_ste (vector unsigned char, int, unsigned char *);
14929 void vec_ste (vector bool char, int, signed char *);
14930 void vec_ste (vector bool char, int, unsigned char *);
14931 void vec_ste (vector signed short, int, short *);
14932 void vec_ste (vector unsigned short, int, unsigned short *);
14933 void vec_ste (vector bool short, int, short *);
14934 void vec_ste (vector bool short, int, unsigned short *);
14935 void vec_ste (vector pixel, int, short *);
14936 void vec_ste (vector pixel, int, unsigned short *);
14937 void vec_ste (vector float, int, float *);
14938 void vec_ste (vector signed int, int, int *);
14939 void vec_ste (vector unsigned int, int, unsigned int *);
14940 void vec_ste (vector bool int, int, int *);
14941 void vec_ste (vector bool int, int, unsigned int *);
14943 void vec_stvewx (vector float, int, float *);
14944 void vec_stvewx (vector signed int, int, int *);
14945 void vec_stvewx (vector unsigned int, int, unsigned int *);
14946 void vec_stvewx (vector bool int, int, int *);
14947 void vec_stvewx (vector bool int, int, unsigned int *);
14949 void vec_stvehx (vector signed short, int, short *);
14950 void vec_stvehx (vector unsigned short, int, unsigned short *);
14951 void vec_stvehx (vector bool short, int, short *);
14952 void vec_stvehx (vector bool short, int, unsigned short *);
14953 void vec_stvehx (vector pixel, int, short *);
14954 void vec_stvehx (vector pixel, int, unsigned short *);
14956 void vec_stvebx (vector signed char, int, signed char *);
14957 void vec_stvebx (vector unsigned char, int, unsigned char *);
14958 void vec_stvebx (vector bool char, int, signed char *);
14959 void vec_stvebx (vector bool char, int, unsigned char *);
14961 void vec_stl (vector float, int, vector float *);
14962 void vec_stl (vector float, int, float *);
14963 void vec_stl (vector signed int, int, vector signed int *);
14964 void vec_stl (vector signed int, int, int *);
14965 void vec_stl (vector unsigned int, int, vector unsigned int *);
14966 void vec_stl (vector unsigned int, int, unsigned int *);
14967 void vec_stl (vector bool int, int, vector bool int *);
14968 void vec_stl (vector bool int, int, unsigned int *);
14969 void vec_stl (vector bool int, int, int *);
14970 void vec_stl (vector signed short, int, vector signed short *);
14971 void vec_stl (vector signed short, int, short *);
14972 void vec_stl (vector unsigned short, int, vector unsigned short *);
14973 void vec_stl (vector unsigned short, int, unsigned short *);
14974 void vec_stl (vector bool short, int, vector bool short *);
14975 void vec_stl (vector bool short, int, unsigned short *);
14976 void vec_stl (vector bool short, int, short *);
14977 void vec_stl (vector pixel, int, vector pixel *);
14978 void vec_stl (vector pixel, int, unsigned short *);
14979 void vec_stl (vector pixel, int, short *);
14980 void vec_stl (vector signed char, int, vector signed char *);
14981 void vec_stl (vector signed char, int, signed char *);
14982 void vec_stl (vector unsigned char, int, vector unsigned char *);
14983 void vec_stl (vector unsigned char, int, unsigned char *);
14984 void vec_stl (vector bool char, int, vector bool char *);
14985 void vec_stl (vector bool char, int, unsigned char *);
14986 void vec_stl (vector bool char, int, signed char *);
14988 vector signed char vec_sub (vector bool char, vector signed char);
14989 vector signed char vec_sub (vector signed char, vector bool char);
14990 vector signed char vec_sub (vector signed char, vector signed char);
14991 vector unsigned char vec_sub (vector bool char, vector unsigned char);
14992 vector unsigned char vec_sub (vector unsigned char, vector bool char);
14993 vector unsigned char vec_sub (vector unsigned char,
14994 vector unsigned char);
14995 vector signed short vec_sub (vector bool short, vector signed short);
14996 vector signed short vec_sub (vector signed short, vector bool short);
14997 vector signed short vec_sub (vector signed short, vector signed short);
14998 vector unsigned short vec_sub (vector bool short,
14999 vector unsigned short);
15000 vector unsigned short vec_sub (vector unsigned short,
15001 vector bool short);
15002 vector unsigned short vec_sub (vector unsigned short,
15003 vector unsigned short);
15004 vector signed int vec_sub (vector bool int, vector signed int);
15005 vector signed int vec_sub (vector signed int, vector bool int);
15006 vector signed int vec_sub (vector signed int, vector signed int);
15007 vector unsigned int vec_sub (vector bool int, vector unsigned int);
15008 vector unsigned int vec_sub (vector unsigned int, vector bool int);
15009 vector unsigned int vec_sub (vector unsigned int, vector unsigned int);
15010 vector float vec_sub (vector float, vector float);
15012 vector float vec_vsubfp (vector float, vector float);
15014 vector signed int vec_vsubuwm (vector bool int, vector signed int);
15015 vector signed int vec_vsubuwm (vector signed int, vector bool int);
15016 vector signed int vec_vsubuwm (vector signed int, vector signed int);
15017 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
15018 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
15019 vector unsigned int vec_vsubuwm (vector unsigned int,
15020 vector unsigned int);
15022 vector signed short vec_vsubuhm (vector bool short,
15023 vector signed short);
15024 vector signed short vec_vsubuhm (vector signed short,
15025 vector bool short);
15026 vector signed short vec_vsubuhm (vector signed short,
15027 vector signed short);
15028 vector unsigned short vec_vsubuhm (vector bool short,
15029 vector unsigned short);
15030 vector unsigned short vec_vsubuhm (vector unsigned short,
15031 vector bool short);
15032 vector unsigned short vec_vsubuhm (vector unsigned short,
15033 vector unsigned short);
15035 vector signed char vec_vsububm (vector bool char, vector signed char);
15036 vector signed char vec_vsububm (vector signed char, vector bool char);
15037 vector signed char vec_vsububm (vector signed char, vector signed char);
15038 vector unsigned char vec_vsububm (vector bool char,
15039 vector unsigned char);
15040 vector unsigned char vec_vsububm (vector unsigned char,
15042 vector unsigned char vec_vsububm (vector unsigned char,
15043 vector unsigned char);
15045 vector unsigned int vec_subc (vector unsigned int, vector unsigned int);
15047 vector unsigned char vec_subs (vector bool char, vector unsigned char);
15048 vector unsigned char vec_subs (vector unsigned char, vector bool char);
15049 vector unsigned char vec_subs (vector unsigned char,
15050 vector unsigned char);
15051 vector signed char vec_subs (vector bool char, vector signed char);
15052 vector signed char vec_subs (vector signed char, vector bool char);
15053 vector signed char vec_subs (vector signed char, vector signed char);
15054 vector unsigned short vec_subs (vector bool short,
15055 vector unsigned short);
15056 vector unsigned short vec_subs (vector unsigned short,
15057 vector bool short);
15058 vector unsigned short vec_subs (vector unsigned short,
15059 vector unsigned short);
15060 vector signed short vec_subs (vector bool short, vector signed short);
15061 vector signed short vec_subs (vector signed short, vector bool short);
15062 vector signed short vec_subs (vector signed short, vector signed short);
15063 vector unsigned int vec_subs (vector bool int, vector unsigned int);
15064 vector unsigned int vec_subs (vector unsigned int, vector bool int);
15065 vector unsigned int vec_subs (vector unsigned int, vector unsigned int);
15066 vector signed int vec_subs (vector bool int, vector signed int);
15067 vector signed int vec_subs (vector signed int, vector bool int);
15068 vector signed int vec_subs (vector signed int, vector signed int);
15070 vector signed int vec_vsubsws (vector bool int, vector signed int);
15071 vector signed int vec_vsubsws (vector signed int, vector bool int);
15072 vector signed int vec_vsubsws (vector signed int, vector signed int);
15074 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
15075 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
15076 vector unsigned int vec_vsubuws (vector unsigned int,
15077 vector unsigned int);
15079 vector signed short vec_vsubshs (vector bool short,
15080 vector signed short);
15081 vector signed short vec_vsubshs (vector signed short,
15082 vector bool short);
15083 vector signed short vec_vsubshs (vector signed short,
15084 vector signed short);
15086 vector unsigned short vec_vsubuhs (vector bool short,
15087 vector unsigned short);
15088 vector unsigned short vec_vsubuhs (vector unsigned short,
15089 vector bool short);
15090 vector unsigned short vec_vsubuhs (vector unsigned short,
15091 vector unsigned short);
15093 vector signed char vec_vsubsbs (vector bool char, vector signed char);
15094 vector signed char vec_vsubsbs (vector signed char, vector bool char);
15095 vector signed char vec_vsubsbs (vector signed char, vector signed char);
15097 vector unsigned char vec_vsububs (vector bool char,
15098 vector unsigned char);
15099 vector unsigned char vec_vsububs (vector unsigned char,
15101 vector unsigned char vec_vsububs (vector unsigned char,
15102 vector unsigned char);
15104 vector unsigned int vec_sum4s (vector unsigned char,
15105 vector unsigned int);
15106 vector signed int vec_sum4s (vector signed char, vector signed int);
15107 vector signed int vec_sum4s (vector signed short, vector signed int);
15109 vector signed int vec_vsum4shs (vector signed short, vector signed int);
15111 vector signed int vec_vsum4sbs (vector signed char, vector signed int);
15113 vector unsigned int vec_vsum4ubs (vector unsigned char,
15114 vector unsigned int);
15116 vector signed int vec_sum2s (vector signed int, vector signed int);
15118 vector signed int vec_sums (vector signed int, vector signed int);
15120 vector float vec_trunc (vector float);
15122 vector signed short vec_unpackh (vector signed char);
15123 vector bool short vec_unpackh (vector bool char);
15124 vector signed int vec_unpackh (vector signed short);
15125 vector bool int vec_unpackh (vector bool short);
15126 vector unsigned int vec_unpackh (vector pixel);
15128 vector bool int vec_vupkhsh (vector bool short);
15129 vector signed int vec_vupkhsh (vector signed short);
15131 vector unsigned int vec_vupkhpx (vector pixel);
15133 vector bool short vec_vupkhsb (vector bool char);
15134 vector signed short vec_vupkhsb (vector signed char);
15136 vector signed short vec_unpackl (vector signed char);
15137 vector bool short vec_unpackl (vector bool char);
15138 vector unsigned int vec_unpackl (vector pixel);
15139 vector signed int vec_unpackl (vector signed short);
15140 vector bool int vec_unpackl (vector bool short);
15142 vector unsigned int vec_vupklpx (vector pixel);
15144 vector bool int vec_vupklsh (vector bool short);
15145 vector signed int vec_vupklsh (vector signed short);
15147 vector bool short vec_vupklsb (vector bool char);
15148 vector signed short vec_vupklsb (vector signed char);
15150 vector float vec_xor (vector float, vector float);
15151 vector float vec_xor (vector float, vector bool int);
15152 vector float vec_xor (vector bool int, vector float);
15153 vector bool int vec_xor (vector bool int, vector bool int);
15154 vector signed int vec_xor (vector bool int, vector signed int);
15155 vector signed int vec_xor (vector signed int, vector bool int);
15156 vector signed int vec_xor (vector signed int, vector signed int);
15157 vector unsigned int vec_xor (vector bool int, vector unsigned int);
15158 vector unsigned int vec_xor (vector unsigned int, vector bool int);
15159 vector unsigned int vec_xor (vector unsigned int, vector unsigned int);
15160 vector bool short vec_xor (vector bool short, vector bool short);
15161 vector signed short vec_xor (vector bool short, vector signed short);
15162 vector signed short vec_xor (vector signed short, vector bool short);
15163 vector signed short vec_xor (vector signed short, vector signed short);
15164 vector unsigned short vec_xor (vector bool short,
15165 vector unsigned short);
15166 vector unsigned short vec_xor (vector unsigned short,
15167 vector bool short);
15168 vector unsigned short vec_xor (vector unsigned short,
15169 vector unsigned short);
15170 vector signed char vec_xor (vector bool char, vector signed char);
15171 vector bool char vec_xor (vector bool char, vector bool char);
15172 vector signed char vec_xor (vector signed char, vector bool char);
15173 vector signed char vec_xor (vector signed char, vector signed char);
15174 vector unsigned char vec_xor (vector bool char, vector unsigned char);
15175 vector unsigned char vec_xor (vector unsigned char, vector bool char);
15176 vector unsigned char vec_xor (vector unsigned char,
15177 vector unsigned char);
15179 int vec_all_eq (vector signed char, vector bool char);
15180 int vec_all_eq (vector signed char, vector signed char);
15181 int vec_all_eq (vector unsigned char, vector bool char);
15182 int vec_all_eq (vector unsigned char, vector unsigned char);
15183 int vec_all_eq (vector bool char, vector bool char);
15184 int vec_all_eq (vector bool char, vector unsigned char);
15185 int vec_all_eq (vector bool char, vector signed char);
15186 int vec_all_eq (vector signed short, vector bool short);
15187 int vec_all_eq (vector signed short, vector signed short);
15188 int vec_all_eq (vector unsigned short, vector bool short);
15189 int vec_all_eq (vector unsigned short, vector unsigned short);
15190 int vec_all_eq (vector bool short, vector bool short);
15191 int vec_all_eq (vector bool short, vector unsigned short);
15192 int vec_all_eq (vector bool short, vector signed short);
15193 int vec_all_eq (vector pixel, vector pixel);
15194 int vec_all_eq (vector signed int, vector bool int);
15195 int vec_all_eq (vector signed int, vector signed int);
15196 int vec_all_eq (vector unsigned int, vector bool int);
15197 int vec_all_eq (vector unsigned int, vector unsigned int);
15198 int vec_all_eq (vector bool int, vector bool int);
15199 int vec_all_eq (vector bool int, vector unsigned int);
15200 int vec_all_eq (vector bool int, vector signed int);
15201 int vec_all_eq (vector float, vector float);
15203 int vec_all_ge (vector bool char, vector unsigned char);
15204 int vec_all_ge (vector unsigned char, vector bool char);
15205 int vec_all_ge (vector unsigned char, vector unsigned char);
15206 int vec_all_ge (vector bool char, vector signed char);
15207 int vec_all_ge (vector signed char, vector bool char);
15208 int vec_all_ge (vector signed char, vector signed char);
15209 int vec_all_ge (vector bool short, vector unsigned short);
15210 int vec_all_ge (vector unsigned short, vector bool short);
15211 int vec_all_ge (vector unsigned short, vector unsigned short);
15212 int vec_all_ge (vector signed short, vector signed short);
15213 int vec_all_ge (vector bool short, vector signed short);
15214 int vec_all_ge (vector signed short, vector bool short);
15215 int vec_all_ge (vector bool int, vector unsigned int);
15216 int vec_all_ge (vector unsigned int, vector bool int);
15217 int vec_all_ge (vector unsigned int, vector unsigned int);
15218 int vec_all_ge (vector bool int, vector signed int);
15219 int vec_all_ge (vector signed int, vector bool int);
15220 int vec_all_ge (vector signed int, vector signed int);
15221 int vec_all_ge (vector float, vector float);
15223 int vec_all_gt (vector bool char, vector unsigned char);
15224 int vec_all_gt (vector unsigned char, vector bool char);
15225 int vec_all_gt (vector unsigned char, vector unsigned char);
15226 int vec_all_gt (vector bool char, vector signed char);
15227 int vec_all_gt (vector signed char, vector bool char);
15228 int vec_all_gt (vector signed char, vector signed char);
15229 int vec_all_gt (vector bool short, vector unsigned short);
15230 int vec_all_gt (vector unsigned short, vector bool short);
15231 int vec_all_gt (vector unsigned short, vector unsigned short);
15232 int vec_all_gt (vector bool short, vector signed short);
15233 int vec_all_gt (vector signed short, vector bool short);
15234 int vec_all_gt (vector signed short, vector signed short);
15235 int vec_all_gt (vector bool int, vector unsigned int);
15236 int vec_all_gt (vector unsigned int, vector bool int);
15237 int vec_all_gt (vector unsigned int, vector unsigned int);
15238 int vec_all_gt (vector bool int, vector signed int);
15239 int vec_all_gt (vector signed int, vector bool int);
15240 int vec_all_gt (vector signed int, vector signed int);
15241 int vec_all_gt (vector float, vector float);
15243 int vec_all_in (vector float, vector float);
15245 int vec_all_le (vector bool char, vector unsigned char);
15246 int vec_all_le (vector unsigned char, vector bool char);
15247 int vec_all_le (vector unsigned char, vector unsigned char);
15248 int vec_all_le (vector bool char, vector signed char);
15249 int vec_all_le (vector signed char, vector bool char);
15250 int vec_all_le (vector signed char, vector signed char);
15251 int vec_all_le (vector bool short, vector unsigned short);
15252 int vec_all_le (vector unsigned short, vector bool short);
15253 int vec_all_le (vector unsigned short, vector unsigned short);
15254 int vec_all_le (vector bool short, vector signed short);
15255 int vec_all_le (vector signed short, vector bool short);
15256 int vec_all_le (vector signed short, vector signed short);
15257 int vec_all_le (vector bool int, vector unsigned int);
15258 int vec_all_le (vector unsigned int, vector bool int);
15259 int vec_all_le (vector unsigned int, vector unsigned int);
15260 int vec_all_le (vector bool int, vector signed int);
15261 int vec_all_le (vector signed int, vector bool int);
15262 int vec_all_le (vector signed int, vector signed int);
15263 int vec_all_le (vector float, vector float);
15265 int vec_all_lt (vector bool char, vector unsigned char);
15266 int vec_all_lt (vector unsigned char, vector bool char);
15267 int vec_all_lt (vector unsigned char, vector unsigned char);
15268 int vec_all_lt (vector bool char, vector signed char);
15269 int vec_all_lt (vector signed char, vector bool char);
15270 int vec_all_lt (vector signed char, vector signed char);
15271 int vec_all_lt (vector bool short, vector unsigned short);
15272 int vec_all_lt (vector unsigned short, vector bool short);
15273 int vec_all_lt (vector unsigned short, vector unsigned short);
15274 int vec_all_lt (vector bool short, vector signed short);
15275 int vec_all_lt (vector signed short, vector bool short);
15276 int vec_all_lt (vector signed short, vector signed short);
15277 int vec_all_lt (vector bool int, vector unsigned int);
15278 int vec_all_lt (vector unsigned int, vector bool int);
15279 int vec_all_lt (vector unsigned int, vector unsigned int);
15280 int vec_all_lt (vector bool int, vector signed int);
15281 int vec_all_lt (vector signed int, vector bool int);
15282 int vec_all_lt (vector signed int, vector signed int);
15283 int vec_all_lt (vector float, vector float);
15285 int vec_all_nan (vector float);
15287 int vec_all_ne (vector signed char, vector bool char);
15288 int vec_all_ne (vector signed char, vector signed char);
15289 int vec_all_ne (vector unsigned char, vector bool char);
15290 int vec_all_ne (vector unsigned char, vector unsigned char);
15291 int vec_all_ne (vector bool char, vector bool char);
15292 int vec_all_ne (vector bool char, vector unsigned char);
15293 int vec_all_ne (vector bool char, vector signed char);
15294 int vec_all_ne (vector signed short, vector bool short);
15295 int vec_all_ne (vector signed short, vector signed short);
15296 int vec_all_ne (vector unsigned short, vector bool short);
15297 int vec_all_ne (vector unsigned short, vector unsigned short);
15298 int vec_all_ne (vector bool short, vector bool short);
15299 int vec_all_ne (vector bool short, vector unsigned short);
15300 int vec_all_ne (vector bool short, vector signed short);
15301 int vec_all_ne (vector pixel, vector pixel);
15302 int vec_all_ne (vector signed int, vector bool int);
15303 int vec_all_ne (vector signed int, vector signed int);
15304 int vec_all_ne (vector unsigned int, vector bool int);
15305 int vec_all_ne (vector unsigned int, vector unsigned int);
15306 int vec_all_ne (vector bool int, vector bool int);
15307 int vec_all_ne (vector bool int, vector unsigned int);
15308 int vec_all_ne (vector bool int, vector signed int);
15309 int vec_all_ne (vector float, vector float);
15311 int vec_all_nge (vector float, vector float);
15313 int vec_all_ngt (vector float, vector float);
15315 int vec_all_nle (vector float, vector float);
15317 int vec_all_nlt (vector float, vector float);
15319 int vec_all_numeric (vector float);
15321 int vec_any_eq (vector signed char, vector bool char);
15322 int vec_any_eq (vector signed char, vector signed char);
15323 int vec_any_eq (vector unsigned char, vector bool char);
15324 int vec_any_eq (vector unsigned char, vector unsigned char);
15325 int vec_any_eq (vector bool char, vector bool char);
15326 int vec_any_eq (vector bool char, vector unsigned char);
15327 int vec_any_eq (vector bool char, vector signed char);
15328 int vec_any_eq (vector signed short, vector bool short);
15329 int vec_any_eq (vector signed short, vector signed short);
15330 int vec_any_eq (vector unsigned short, vector bool short);
15331 int vec_any_eq (vector unsigned short, vector unsigned short);
15332 int vec_any_eq (vector bool short, vector bool short);
15333 int vec_any_eq (vector bool short, vector unsigned short);
15334 int vec_any_eq (vector bool short, vector signed short);
15335 int vec_any_eq (vector pixel, vector pixel);
15336 int vec_any_eq (vector signed int, vector bool int);
15337 int vec_any_eq (vector signed int, vector signed int);
15338 int vec_any_eq (vector unsigned int, vector bool int);
15339 int vec_any_eq (vector unsigned int, vector unsigned int);
15340 int vec_any_eq (vector bool int, vector bool int);
15341 int vec_any_eq (vector bool int, vector unsigned int);
15342 int vec_any_eq (vector bool int, vector signed int);
15343 int vec_any_eq (vector float, vector float);
15345 int vec_any_ge (vector signed char, vector bool char);
15346 int vec_any_ge (vector unsigned char, vector bool char);
15347 int vec_any_ge (vector unsigned char, vector unsigned char);
15348 int vec_any_ge (vector signed char, vector signed char);
15349 int vec_any_ge (vector bool char, vector unsigned char);
15350 int vec_any_ge (vector bool char, vector signed char);
15351 int vec_any_ge (vector unsigned short, vector bool short);
15352 int vec_any_ge (vector unsigned short, vector unsigned short);
15353 int vec_any_ge (vector signed short, vector signed short);
15354 int vec_any_ge (vector signed short, vector bool short);
15355 int vec_any_ge (vector bool short, vector unsigned short);
15356 int vec_any_ge (vector bool short, vector signed short);
15357 int vec_any_ge (vector signed int, vector bool int);
15358 int vec_any_ge (vector unsigned int, vector bool int);
15359 int vec_any_ge (vector unsigned int, vector unsigned int);
15360 int vec_any_ge (vector signed int, vector signed int);
15361 int vec_any_ge (vector bool int, vector unsigned int);
15362 int vec_any_ge (vector bool int, vector signed int);
15363 int vec_any_ge (vector float, vector float);
15365 int vec_any_gt (vector bool char, vector unsigned char);
15366 int vec_any_gt (vector unsigned char, vector bool char);
15367 int vec_any_gt (vector unsigned char, vector unsigned char);
15368 int vec_any_gt (vector bool char, vector signed char);
15369 int vec_any_gt (vector signed char, vector bool char);
15370 int vec_any_gt (vector signed char, vector signed char);
15371 int vec_any_gt (vector bool short, vector unsigned short);
15372 int vec_any_gt (vector unsigned short, vector bool short);
15373 int vec_any_gt (vector unsigned short, vector unsigned short);
15374 int vec_any_gt (vector bool short, vector signed short);
15375 int vec_any_gt (vector signed short, vector bool short);
15376 int vec_any_gt (vector signed short, vector signed short);
15377 int vec_any_gt (vector bool int, vector unsigned int);
15378 int vec_any_gt (vector unsigned int, vector bool int);
15379 int vec_any_gt (vector unsigned int, vector unsigned int);
15380 int vec_any_gt (vector bool int, vector signed int);
15381 int vec_any_gt (vector signed int, vector bool int);
15382 int vec_any_gt (vector signed int, vector signed int);
15383 int vec_any_gt (vector float, vector float);
15385 int vec_any_le (vector bool char, vector unsigned char);
15386 int vec_any_le (vector unsigned char, vector bool char);
15387 int vec_any_le (vector unsigned char, vector unsigned char);
15388 int vec_any_le (vector bool char, vector signed char);
15389 int vec_any_le (vector signed char, vector bool char);
15390 int vec_any_le (vector signed char, vector signed char);
15391 int vec_any_le (vector bool short, vector unsigned short);
15392 int vec_any_le (vector unsigned short, vector bool short);
15393 int vec_any_le (vector unsigned short, vector unsigned short);
15394 int vec_any_le (vector bool short, vector signed short);
15395 int vec_any_le (vector signed short, vector bool short);
15396 int vec_any_le (vector signed short, vector signed short);
15397 int vec_any_le (vector bool int, vector unsigned int);
15398 int vec_any_le (vector unsigned int, vector bool int);
15399 int vec_any_le (vector unsigned int, vector unsigned int);
15400 int vec_any_le (vector bool int, vector signed int);
15401 int vec_any_le (vector signed int, vector bool int);
15402 int vec_any_le (vector signed int, vector signed int);
15403 int vec_any_le (vector float, vector float);
15405 int vec_any_lt (vector bool char, vector unsigned char);
15406 int vec_any_lt (vector unsigned char, vector bool char);
15407 int vec_any_lt (vector unsigned char, vector unsigned char);
15408 int vec_any_lt (vector bool char, vector signed char);
15409 int vec_any_lt (vector signed char, vector bool char);
15410 int vec_any_lt (vector signed char, vector signed char);
15411 int vec_any_lt (vector bool short, vector unsigned short);
15412 int vec_any_lt (vector unsigned short, vector bool short);
15413 int vec_any_lt (vector unsigned short, vector unsigned short);
15414 int vec_any_lt (vector bool short, vector signed short);
15415 int vec_any_lt (vector signed short, vector bool short);
15416 int vec_any_lt (vector signed short, vector signed short);
15417 int vec_any_lt (vector bool int, vector unsigned int);
15418 int vec_any_lt (vector unsigned int, vector bool int);
15419 int vec_any_lt (vector unsigned int, vector unsigned int);
15420 int vec_any_lt (vector bool int, vector signed int);
15421 int vec_any_lt (vector signed int, vector bool int);
15422 int vec_any_lt (vector signed int, vector signed int);
15423 int vec_any_lt (vector float, vector float);
15425 int vec_any_nan (vector float);
15427 int vec_any_ne (vector signed char, vector bool char);
15428 int vec_any_ne (vector signed char, vector signed char);
15429 int vec_any_ne (vector unsigned char, vector bool char);
15430 int vec_any_ne (vector unsigned char, vector unsigned char);
15431 int vec_any_ne (vector bool char, vector bool char);
15432 int vec_any_ne (vector bool char, vector unsigned char);
15433 int vec_any_ne (vector bool char, vector signed char);
15434 int vec_any_ne (vector signed short, vector bool short);
15435 int vec_any_ne (vector signed short, vector signed short);
15436 int vec_any_ne (vector unsigned short, vector bool short);
15437 int vec_any_ne (vector unsigned short, vector unsigned short);
15438 int vec_any_ne (vector bool short, vector bool short);
15439 int vec_any_ne (vector bool short, vector unsigned short);
15440 int vec_any_ne (vector bool short, vector signed short);
15441 int vec_any_ne (vector pixel, vector pixel);
15442 int vec_any_ne (vector signed int, vector bool int);
15443 int vec_any_ne (vector signed int, vector signed int);
15444 int vec_any_ne (vector unsigned int, vector bool int);
15445 int vec_any_ne (vector unsigned int, vector unsigned int);
15446 int vec_any_ne (vector bool int, vector bool int);
15447 int vec_any_ne (vector bool int, vector unsigned int);
15448 int vec_any_ne (vector bool int, vector signed int);
15449 int vec_any_ne (vector float, vector float);
15451 int vec_any_nge (vector float, vector float);
15453 int vec_any_ngt (vector float, vector float);
15455 int vec_any_nle (vector float, vector float);
15457 int vec_any_nlt (vector float, vector float);
15459 int vec_any_numeric (vector float);
15461 int vec_any_out (vector float, vector float);
15464 If the vector/scalar (VSX) instruction set is available, the following
15465 additional functions are available:
15468 vector double vec_abs (vector double);
15469 vector double vec_add (vector double, vector double);
15470 vector double vec_and (vector double, vector double);
15471 vector double vec_and (vector double, vector bool long);
15472 vector double vec_and (vector bool long, vector double);
15473 vector long vec_and (vector long, vector long);
15474 vector long vec_and (vector long, vector bool long);
15475 vector long vec_and (vector bool long, vector long);
15476 vector unsigned long vec_and (vector unsigned long, vector unsigned long);
15477 vector unsigned long vec_and (vector unsigned long, vector bool long);
15478 vector unsigned long vec_and (vector bool long, vector unsigned long);
15479 vector double vec_andc (vector double, vector double);
15480 vector double vec_andc (vector double, vector bool long);
15481 vector double vec_andc (vector bool long, vector double);
15482 vector long vec_andc (vector long, vector long);
15483 vector long vec_andc (vector long, vector bool long);
15484 vector long vec_andc (vector bool long, vector long);
15485 vector unsigned long vec_andc (vector unsigned long, vector unsigned long);
15486 vector unsigned long vec_andc (vector unsigned long, vector bool long);
15487 vector unsigned long vec_andc (vector bool long, vector unsigned long);
15488 vector double vec_ceil (vector double);
15489 vector bool long vec_cmpeq (vector double, vector double);
15490 vector bool long vec_cmpge (vector double, vector double);
15491 vector bool long vec_cmpgt (vector double, vector double);
15492 vector bool long vec_cmple (vector double, vector double);
15493 vector bool long vec_cmplt (vector double, vector double);
15494 vector double vec_cpsgn (vector double, vector double);
15495 vector float vec_div (vector float, vector float);
15496 vector double vec_div (vector double, vector double);
15497 vector long vec_div (vector long, vector long);
15498 vector unsigned long vec_div (vector unsigned long, vector unsigned long);
15499 vector double vec_floor (vector double);
15500 vector double vec_ld (int, const vector double *);
15501 vector double vec_ld (int, const double *);
15502 vector double vec_ldl (int, const vector double *);
15503 vector double vec_ldl (int, const double *);
15504 vector unsigned char vec_lvsl (int, const volatile double *);
15505 vector unsigned char vec_lvsr (int, const volatile double *);
15506 vector double vec_madd (vector double, vector double, vector double);
15507 vector double vec_max (vector double, vector double);
15508 vector signed long vec_mergeh (vector signed long, vector signed long);
15509 vector signed long vec_mergeh (vector signed long, vector bool long);
15510 vector signed long vec_mergeh (vector bool long, vector signed long);
15511 vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long);
15512 vector unsigned long vec_mergeh (vector unsigned long, vector bool long);
15513 vector unsigned long vec_mergeh (vector bool long, vector unsigned long);
15514 vector signed long vec_mergel (vector signed long, vector signed long);
15515 vector signed long vec_mergel (vector signed long, vector bool long);
15516 vector signed long vec_mergel (vector bool long, vector signed long);
15517 vector unsigned long vec_mergel (vector unsigned long, vector unsigned long);
15518 vector unsigned long vec_mergel (vector unsigned long, vector bool long);
15519 vector unsigned long vec_mergel (vector bool long, vector unsigned long);
15520 vector double vec_min (vector double, vector double);
15521 vector float vec_msub (vector float, vector float, vector float);
15522 vector double vec_msub (vector double, vector double, vector double);
15523 vector float vec_mul (vector float, vector float);
15524 vector double vec_mul (vector double, vector double);
15525 vector long vec_mul (vector long, vector long);
15526 vector unsigned long vec_mul (vector unsigned long, vector unsigned long);
15527 vector float vec_nearbyint (vector float);
15528 vector double vec_nearbyint (vector double);
15529 vector float vec_nmadd (vector float, vector float, vector float);
15530 vector double vec_nmadd (vector double, vector double, vector double);
15531 vector double vec_nmsub (vector double, vector double, vector double);
15532 vector double vec_nor (vector double, vector double);
15533 vector long vec_nor (vector long, vector long);
15534 vector long vec_nor (vector long, vector bool long);
15535 vector long vec_nor (vector bool long, vector long);
15536 vector unsigned long vec_nor (vector unsigned long, vector unsigned long);
15537 vector unsigned long vec_nor (vector unsigned long, vector bool long);
15538 vector unsigned long vec_nor (vector bool long, vector unsigned long);
15539 vector double vec_or (vector double, vector double);
15540 vector double vec_or (vector double, vector bool long);
15541 vector double vec_or (vector bool long, vector double);
15542 vector long vec_or (vector long, vector long);
15543 vector long vec_or (vector long, vector bool long);
15544 vector long vec_or (vector bool long, vector long);
15545 vector unsigned long vec_or (vector unsigned long, vector unsigned long);
15546 vector unsigned long vec_or (vector unsigned long, vector bool long);
15547 vector unsigned long vec_or (vector bool long, vector unsigned long);
15548 vector double vec_perm (vector double, vector double, vector unsigned char);
15549 vector long vec_perm (vector long, vector long, vector unsigned char);
15550 vector unsigned long vec_perm (vector unsigned long, vector unsigned long,
15551 vector unsigned char);
15552 vector double vec_rint (vector double);
15553 vector double vec_recip (vector double, vector double);
15554 vector double vec_rsqrt (vector double);
15555 vector double vec_rsqrte (vector double);
15556 vector double vec_sel (vector double, vector double, vector bool long);
15557 vector double vec_sel (vector double, vector double, vector unsigned long);
15558 vector long vec_sel (vector long, vector long, vector long);
15559 vector long vec_sel (vector long, vector long, vector unsigned long);
15560 vector long vec_sel (vector long, vector long, vector bool long);
15561 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
15563 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
15564 vector unsigned long);
15565 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
15567 vector double vec_splats (double);
15568 vector signed long vec_splats (signed long);
15569 vector unsigned long vec_splats (unsigned long);
15570 vector float vec_sqrt (vector float);
15571 vector double vec_sqrt (vector double);
15572 void vec_st (vector double, int, vector double *);
15573 void vec_st (vector double, int, double *);
15574 vector double vec_sub (vector double, vector double);
15575 vector double vec_trunc (vector double);
15576 vector double vec_xor (vector double, vector double);
15577 vector double vec_xor (vector double, vector bool long);
15578 vector double vec_xor (vector bool long, vector double);
15579 vector long vec_xor (vector long, vector long);
15580 vector long vec_xor (vector long, vector bool long);
15581 vector long vec_xor (vector bool long, vector long);
15582 vector unsigned long vec_xor (vector unsigned long, vector unsigned long);
15583 vector unsigned long vec_xor (vector unsigned long, vector bool long);
15584 vector unsigned long vec_xor (vector bool long, vector unsigned long);
15585 int vec_all_eq (vector double, vector double);
15586 int vec_all_ge (vector double, vector double);
15587 int vec_all_gt (vector double, vector double);
15588 int vec_all_le (vector double, vector double);
15589 int vec_all_lt (vector double, vector double);
15590 int vec_all_nan (vector double);
15591 int vec_all_ne (vector double, vector double);
15592 int vec_all_nge (vector double, vector double);
15593 int vec_all_ngt (vector double, vector double);
15594 int vec_all_nle (vector double, vector double);
15595 int vec_all_nlt (vector double, vector double);
15596 int vec_all_numeric (vector double);
15597 int vec_any_eq (vector double, vector double);
15598 int vec_any_ge (vector double, vector double);
15599 int vec_any_gt (vector double, vector double);
15600 int vec_any_le (vector double, vector double);
15601 int vec_any_lt (vector double, vector double);
15602 int vec_any_nan (vector double);
15603 int vec_any_ne (vector double, vector double);
15604 int vec_any_nge (vector double, vector double);
15605 int vec_any_ngt (vector double, vector double);
15606 int vec_any_nle (vector double, vector double);
15607 int vec_any_nlt (vector double, vector double);
15608 int vec_any_numeric (vector double);
15610 vector double vec_vsx_ld (int, const vector double *);
15611 vector double vec_vsx_ld (int, const double *);
15612 vector float vec_vsx_ld (int, const vector float *);
15613 vector float vec_vsx_ld (int, const float *);
15614 vector bool int vec_vsx_ld (int, const vector bool int *);
15615 vector signed int vec_vsx_ld (int, const vector signed int *);
15616 vector signed int vec_vsx_ld (int, const int *);
15617 vector signed int vec_vsx_ld (int, const long *);
15618 vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
15619 vector unsigned int vec_vsx_ld (int, const unsigned int *);
15620 vector unsigned int vec_vsx_ld (int, const unsigned long *);
15621 vector bool short vec_vsx_ld (int, const vector bool short *);
15622 vector pixel vec_vsx_ld (int, const vector pixel *);
15623 vector signed short vec_vsx_ld (int, const vector signed short *);
15624 vector signed short vec_vsx_ld (int, const short *);
15625 vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
15626 vector unsigned short vec_vsx_ld (int, const unsigned short *);
15627 vector bool char vec_vsx_ld (int, const vector bool char *);
15628 vector signed char vec_vsx_ld (int, const vector signed char *);
15629 vector signed char vec_vsx_ld (int, const signed char *);
15630 vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
15631 vector unsigned char vec_vsx_ld (int, const unsigned char *);
15633 void vec_vsx_st (vector double, int, vector double *);
15634 void vec_vsx_st (vector double, int, double *);
15635 void vec_vsx_st (vector float, int, vector float *);
15636 void vec_vsx_st (vector float, int, float *);
15637 void vec_vsx_st (vector signed int, int, vector signed int *);
15638 void vec_vsx_st (vector signed int, int, int *);
15639 void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
15640 void vec_vsx_st (vector unsigned int, int, unsigned int *);
15641 void vec_vsx_st (vector bool int, int, vector bool int *);
15642 void vec_vsx_st (vector bool int, int, unsigned int *);
15643 void vec_vsx_st (vector bool int, int, int *);
15644 void vec_vsx_st (vector signed short, int, vector signed short *);
15645 void vec_vsx_st (vector signed short, int, short *);
15646 void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
15647 void vec_vsx_st (vector unsigned short, int, unsigned short *);
15648 void vec_vsx_st (vector bool short, int, vector bool short *);
15649 void vec_vsx_st (vector bool short, int, unsigned short *);
15650 void vec_vsx_st (vector pixel, int, vector pixel *);
15651 void vec_vsx_st (vector pixel, int, unsigned short *);
15652 void vec_vsx_st (vector pixel, int, short *);
15653 void vec_vsx_st (vector bool short, int, short *);
15654 void vec_vsx_st (vector signed char, int, vector signed char *);
15655 void vec_vsx_st (vector signed char, int, signed char *);
15656 void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
15657 void vec_vsx_st (vector unsigned char, int, unsigned char *);
15658 void vec_vsx_st (vector bool char, int, vector bool char *);
15659 void vec_vsx_st (vector bool char, int, unsigned char *);
15660 void vec_vsx_st (vector bool char, int, signed char *);
15662 vector double vec_xxpermdi (vector double, vector double, int);
15663 vector float vec_xxpermdi (vector float, vector float, int);
15664 vector long long vec_xxpermdi (vector long long, vector long long, int);
15665 vector unsigned long long vec_xxpermdi (vector unsigned long long,
15666 vector unsigned long long, int);
15667 vector int vec_xxpermdi (vector int, vector int, int);
15668 vector unsigned int vec_xxpermdi (vector unsigned int,
15669 vector unsigned int, int);
15670 vector short vec_xxpermdi (vector short, vector short, int);
15671 vector unsigned short vec_xxpermdi (vector unsigned short,
15672 vector unsigned short, int);
15673 vector signed char vec_xxpermdi (vector signed char, vector signed char, int);
15674 vector unsigned char vec_xxpermdi (vector unsigned char,
15675 vector unsigned char, int);
15677 vector double vec_xxsldi (vector double, vector double, int);
15678 vector float vec_xxsldi (vector float, vector float, int);
15679 vector long long vec_xxsldi (vector long long, vector long long, int);
15680 vector unsigned long long vec_xxsldi (vector unsigned long long,
15681 vector unsigned long long, int);
15682 vector int vec_xxsldi (vector int, vector int, int);
15683 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
15684 vector short vec_xxsldi (vector short, vector short, int);
15685 vector unsigned short vec_xxsldi (vector unsigned short,
15686 vector unsigned short, int);
15687 vector signed char vec_xxsldi (vector signed char, vector signed char, int);
15688 vector unsigned char vec_xxsldi (vector unsigned char,
15689 vector unsigned char, int);
15692 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
15693 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
15694 if the VSX instruction set is available. The @samp{vec_vsx_ld} and
15695 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
15696 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
15698 If the ISA 2.07 additions to the vector/scalar (power8-vector)
15699 instruction set is available, the following additional functions are
15700 available for both 32-bit and 64-bit targets. For 64-bit targets, you
15701 can use @var{vector long} instead of @var{vector long long},
15702 @var{vector bool long} instead of @var{vector bool long long}, and
15703 @var{vector unsigned long} instead of @var{vector unsigned long long}.
15706 vector long long vec_abs (vector long long);
15708 vector long long vec_add (vector long long, vector long long);
15709 vector unsigned long long vec_add (vector unsigned long long,
15710 vector unsigned long long);
15712 int vec_all_eq (vector long long, vector long long);
15713 int vec_all_eq (vector unsigned long long, vector unsigned long long);
15714 int vec_all_ge (vector long long, vector long long);
15715 int vec_all_ge (vector unsigned long long, vector unsigned long long);
15716 int vec_all_gt (vector long long, vector long long);
15717 int vec_all_gt (vector unsigned long long, vector unsigned long long);
15718 int vec_all_le (vector long long, vector long long);
15719 int vec_all_le (vector unsigned long long, vector unsigned long long);
15720 int vec_all_lt (vector long long, vector long long);
15721 int vec_all_lt (vector unsigned long long, vector unsigned long long);
15722 int vec_all_ne (vector long long, vector long long);
15723 int vec_all_ne (vector unsigned long long, vector unsigned long long);
15725 int vec_any_eq (vector long long, vector long long);
15726 int vec_any_eq (vector unsigned long long, vector unsigned long long);
15727 int vec_any_ge (vector long long, vector long long);
15728 int vec_any_ge (vector unsigned long long, vector unsigned long long);
15729 int vec_any_gt (vector long long, vector long long);
15730 int vec_any_gt (vector unsigned long long, vector unsigned long long);
15731 int vec_any_le (vector long long, vector long long);
15732 int vec_any_le (vector unsigned long long, vector unsigned long long);
15733 int vec_any_lt (vector long long, vector long long);
15734 int vec_any_lt (vector unsigned long long, vector unsigned long long);
15735 int vec_any_ne (vector long long, vector long long);
15736 int vec_any_ne (vector unsigned long long, vector unsigned long long);
15738 vector long long vec_eqv (vector long long, vector long long);
15739 vector long long vec_eqv (vector bool long long, vector long long);
15740 vector long long vec_eqv (vector long long, vector bool long long);
15741 vector unsigned long long vec_eqv (vector unsigned long long,
15742 vector unsigned long long);
15743 vector unsigned long long vec_eqv (vector bool long long,
15744 vector unsigned long long);
15745 vector unsigned long long vec_eqv (vector unsigned long long,
15746 vector bool long long);
15747 vector int vec_eqv (vector int, vector int);
15748 vector int vec_eqv (vector bool int, vector int);
15749 vector int vec_eqv (vector int, vector bool int);
15750 vector unsigned int vec_eqv (vector unsigned int, vector unsigned int);
15751 vector unsigned int vec_eqv (vector bool unsigned int,
15752 vector unsigned int);
15753 vector unsigned int vec_eqv (vector unsigned int,
15754 vector bool unsigned int);
15755 vector short vec_eqv (vector short, vector short);
15756 vector short vec_eqv (vector bool short, vector short);
15757 vector short vec_eqv (vector short, vector bool short);
15758 vector unsigned short vec_eqv (vector unsigned short, vector unsigned short);
15759 vector unsigned short vec_eqv (vector bool unsigned short,
15760 vector unsigned short);
15761 vector unsigned short vec_eqv (vector unsigned short,
15762 vector bool unsigned short);
15763 vector signed char vec_eqv (vector signed char, vector signed char);
15764 vector signed char vec_eqv (vector bool signed char, vector signed char);
15765 vector signed char vec_eqv (vector signed char, vector bool signed char);
15766 vector unsigned char vec_eqv (vector unsigned char, vector unsigned char);
15767 vector unsigned char vec_eqv (vector bool unsigned char, vector unsigned char);
15768 vector unsigned char vec_eqv (vector unsigned char, vector bool unsigned char);
15770 vector long long vec_max (vector long long, vector long long);
15771 vector unsigned long long vec_max (vector unsigned long long,
15772 vector unsigned long long);
15774 vector signed int vec_mergee (vector signed int, vector signed int);
15775 vector unsigned int vec_mergee (vector unsigned int, vector unsigned int);
15776 vector bool int vec_mergee (vector bool int, vector bool int);
15778 vector signed int vec_mergeo (vector signed int, vector signed int);
15779 vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int);
15780 vector bool int vec_mergeo (vector bool int, vector bool int);
15782 vector long long vec_min (vector long long, vector long long);
15783 vector unsigned long long vec_min (vector unsigned long long,
15784 vector unsigned long long);
15786 vector long long vec_nand (vector long long, vector long long);
15787 vector long long vec_nand (vector bool long long, vector long long);
15788 vector long long vec_nand (vector long long, vector bool long long);
15789 vector unsigned long long vec_nand (vector unsigned long long,
15790 vector unsigned long long);
15791 vector unsigned long long vec_nand (vector bool long long,
15792 vector unsigned long long);
15793 vector unsigned long long vec_nand (vector unsigned long long,
15794 vector bool long long);
15795 vector int vec_nand (vector int, vector int);
15796 vector int vec_nand (vector bool int, vector int);
15797 vector int vec_nand (vector int, vector bool int);
15798 vector unsigned int vec_nand (vector unsigned int, vector unsigned int);
15799 vector unsigned int vec_nand (vector bool unsigned int,
15800 vector unsigned int);
15801 vector unsigned int vec_nand (vector unsigned int,
15802 vector bool unsigned int);
15803 vector short vec_nand (vector short, vector short);
15804 vector short vec_nand (vector bool short, vector short);
15805 vector short vec_nand (vector short, vector bool short);
15806 vector unsigned short vec_nand (vector unsigned short, vector unsigned short);
15807 vector unsigned short vec_nand (vector bool unsigned short,
15808 vector unsigned short);
15809 vector unsigned short vec_nand (vector unsigned short,
15810 vector bool unsigned short);
15811 vector signed char vec_nand (vector signed char, vector signed char);
15812 vector signed char vec_nand (vector bool signed char, vector signed char);
15813 vector signed char vec_nand (vector signed char, vector bool signed char);
15814 vector unsigned char vec_nand (vector unsigned char, vector unsigned char);
15815 vector unsigned char vec_nand (vector bool unsigned char, vector unsigned char);
15816 vector unsigned char vec_nand (vector unsigned char, vector bool unsigned char);
15818 vector long long vec_orc (vector long long, vector long long);
15819 vector long long vec_orc (vector bool long long, vector long long);
15820 vector long long vec_orc (vector long long, vector bool long long);
15821 vector unsigned long long vec_orc (vector unsigned long long,
15822 vector unsigned long long);
15823 vector unsigned long long vec_orc (vector bool long long,
15824 vector unsigned long long);
15825 vector unsigned long long vec_orc (vector unsigned long long,
15826 vector bool long long);
15827 vector int vec_orc (vector int, vector int);
15828 vector int vec_orc (vector bool int, vector int);
15829 vector int vec_orc (vector int, vector bool int);
15830 vector unsigned int vec_orc (vector unsigned int, vector unsigned int);
15831 vector unsigned int vec_orc (vector bool unsigned int,
15832 vector unsigned int);
15833 vector unsigned int vec_orc (vector unsigned int,
15834 vector bool unsigned int);
15835 vector short vec_orc (vector short, vector short);
15836 vector short vec_orc (vector bool short, vector short);
15837 vector short vec_orc (vector short, vector bool short);
15838 vector unsigned short vec_orc (vector unsigned short, vector unsigned short);
15839 vector unsigned short vec_orc (vector bool unsigned short,
15840 vector unsigned short);
15841 vector unsigned short vec_orc (vector unsigned short,
15842 vector bool unsigned short);
15843 vector signed char vec_orc (vector signed char, vector signed char);
15844 vector signed char vec_orc (vector bool signed char, vector signed char);
15845 vector signed char vec_orc (vector signed char, vector bool signed char);
15846 vector unsigned char vec_orc (vector unsigned char, vector unsigned char);
15847 vector unsigned char vec_orc (vector bool unsigned char, vector unsigned char);
15848 vector unsigned char vec_orc (vector unsigned char, vector bool unsigned char);
15850 vector int vec_pack (vector long long, vector long long);
15851 vector unsigned int vec_pack (vector unsigned long long,
15852 vector unsigned long long);
15853 vector bool int vec_pack (vector bool long long, vector bool long long);
15855 vector int vec_packs (vector long long, vector long long);
15856 vector unsigned int vec_packs (vector unsigned long long,
15857 vector unsigned long long);
15859 vector unsigned int vec_packsu (vector long long, vector long long);
15860 vector unsigned int vec_packsu (vector unsigned long long,
15861 vector unsigned long long);
15863 vector long long vec_rl (vector long long,
15864 vector unsigned long long);
15865 vector long long vec_rl (vector unsigned long long,
15866 vector unsigned long long);
15868 vector long long vec_sl (vector long long, vector unsigned long long);
15869 vector long long vec_sl (vector unsigned long long,
15870 vector unsigned long long);
15872 vector long long vec_sr (vector long long, vector unsigned long long);
15873 vector unsigned long long char vec_sr (vector unsigned long long,
15874 vector unsigned long long);
15876 vector long long vec_sra (vector long long, vector unsigned long long);
15877 vector unsigned long long vec_sra (vector unsigned long long,
15878 vector unsigned long long);
15880 vector long long vec_sub (vector long long, vector long long);
15881 vector unsigned long long vec_sub (vector unsigned long long,
15882 vector unsigned long long);
15884 vector long long vec_unpackh (vector int);
15885 vector unsigned long long vec_unpackh (vector unsigned int);
15887 vector long long vec_unpackl (vector int);
15888 vector unsigned long long vec_unpackl (vector unsigned int);
15890 vector long long vec_vaddudm (vector long long, vector long long);
15891 vector long long vec_vaddudm (vector bool long long, vector long long);
15892 vector long long vec_vaddudm (vector long long, vector bool long long);
15893 vector unsigned long long vec_vaddudm (vector unsigned long long,
15894 vector unsigned long long);
15895 vector unsigned long long vec_vaddudm (vector bool unsigned long long,
15896 vector unsigned long long);
15897 vector unsigned long long vec_vaddudm (vector unsigned long long,
15898 vector bool unsigned long long);
15900 vector long long vec_vbpermq (vector signed char, vector signed char);
15901 vector long long vec_vbpermq (vector unsigned char, vector unsigned char);
15903 vector long long vec_cntlz (vector long long);
15904 vector unsigned long long vec_cntlz (vector unsigned long long);
15905 vector int vec_cntlz (vector int);
15906 vector unsigned int vec_cntlz (vector int);
15907 vector short vec_cntlz (vector short);
15908 vector unsigned short vec_cntlz (vector unsigned short);
15909 vector signed char vec_cntlz (vector signed char);
15910 vector unsigned char vec_cntlz (vector unsigned char);
15912 vector long long vec_vclz (vector long long);
15913 vector unsigned long long vec_vclz (vector unsigned long long);
15914 vector int vec_vclz (vector int);
15915 vector unsigned int vec_vclz (vector int);
15916 vector short vec_vclz (vector short);
15917 vector unsigned short vec_vclz (vector unsigned short);
15918 vector signed char vec_vclz (vector signed char);
15919 vector unsigned char vec_vclz (vector unsigned char);
15921 vector signed char vec_vclzb (vector signed char);
15922 vector unsigned char vec_vclzb (vector unsigned char);
15924 vector long long vec_vclzd (vector long long);
15925 vector unsigned long long vec_vclzd (vector unsigned long long);
15927 vector short vec_vclzh (vector short);
15928 vector unsigned short vec_vclzh (vector unsigned short);
15930 vector int vec_vclzw (vector int);
15931 vector unsigned int vec_vclzw (vector int);
15933 vector signed char vec_vgbbd (vector signed char);
15934 vector unsigned char vec_vgbbd (vector unsigned char);
15936 vector long long vec_vmaxsd (vector long long, vector long long);
15938 vector unsigned long long vec_vmaxud (vector unsigned long long,
15939 unsigned vector long long);
15941 vector long long vec_vminsd (vector long long, vector long long);
15943 vector unsigned long long vec_vminud (vector long long,
15946 vector int vec_vpksdss (vector long long, vector long long);
15947 vector unsigned int vec_vpksdss (vector long long, vector long long);
15949 vector unsigned int vec_vpkudus (vector unsigned long long,
15950 vector unsigned long long);
15952 vector int vec_vpkudum (vector long long, vector long long);
15953 vector unsigned int vec_vpkudum (vector unsigned long long,
15954 vector unsigned long long);
15955 vector bool int vec_vpkudum (vector bool long long, vector bool long long);
15957 vector long long vec_vpopcnt (vector long long);
15958 vector unsigned long long vec_vpopcnt (vector unsigned long long);
15959 vector int vec_vpopcnt (vector int);
15960 vector unsigned int vec_vpopcnt (vector int);
15961 vector short vec_vpopcnt (vector short);
15962 vector unsigned short vec_vpopcnt (vector unsigned short);
15963 vector signed char vec_vpopcnt (vector signed char);
15964 vector unsigned char vec_vpopcnt (vector unsigned char);
15966 vector signed char vec_vpopcntb (vector signed char);
15967 vector unsigned char vec_vpopcntb (vector unsigned char);
15969 vector long long vec_vpopcntd (vector long long);
15970 vector unsigned long long vec_vpopcntd (vector unsigned long long);
15972 vector short vec_vpopcnth (vector short);
15973 vector unsigned short vec_vpopcnth (vector unsigned short);
15975 vector int vec_vpopcntw (vector int);
15976 vector unsigned int vec_vpopcntw (vector int);
15978 vector long long vec_vrld (vector long long, vector unsigned long long);
15979 vector unsigned long long vec_vrld (vector unsigned long long,
15980 vector unsigned long long);
15982 vector long long vec_vsld (vector long long, vector unsigned long long);
15983 vector long long vec_vsld (vector unsigned long long,
15984 vector unsigned long long);
15986 vector long long vec_vsrad (vector long long, vector unsigned long long);
15987 vector unsigned long long vec_vsrad (vector unsigned long long,
15988 vector unsigned long long);
15990 vector long long vec_vsrd (vector long long, vector unsigned long long);
15991 vector unsigned long long char vec_vsrd (vector unsigned long long,
15992 vector unsigned long long);
15994 vector long long vec_vsubudm (vector long long, vector long long);
15995 vector long long vec_vsubudm (vector bool long long, vector long long);
15996 vector long long vec_vsubudm (vector long long, vector bool long long);
15997 vector unsigned long long vec_vsubudm (vector unsigned long long,
15998 vector unsigned long long);
15999 vector unsigned long long vec_vsubudm (vector bool long long,
16000 vector unsigned long long);
16001 vector unsigned long long vec_vsubudm (vector unsigned long long,
16002 vector bool long long);
16004 vector long long vec_vupkhsw (vector int);
16005 vector unsigned long long vec_vupkhsw (vector unsigned int);
16007 vector long long vec_vupklsw (vector int);
16008 vector unsigned long long vec_vupklsw (vector int);
16011 If the ISA 2.07 additions to the vector/scalar (power8-vector)
16012 instruction set is available, the following additional functions are
16013 available for 64-bit targets. New vector types
16014 (@var{vector __int128_t} and @var{vector __uint128_t}) are available
16015 to hold the @var{__int128_t} and @var{__uint128_t} types to use these
16018 The normal vector extract, and set operations work on
16019 @var{vector __int128_t} and @var{vector __uint128_t} types,
16020 but the index value must be 0.
16023 vector __int128_t vec_vaddcuq (vector __int128_t, vector __int128_t);
16024 vector __uint128_t vec_vaddcuq (vector __uint128_t, vector __uint128_t);
16026 vector __int128_t vec_vadduqm (vector __int128_t, vector __int128_t);
16027 vector __uint128_t vec_vadduqm (vector __uint128_t, vector __uint128_t);
16029 vector __int128_t vec_vaddecuq (vector __int128_t, vector __int128_t,
16030 vector __int128_t);
16031 vector __uint128_t vec_vaddecuq (vector __uint128_t, vector __uint128_t,
16032 vector __uint128_t);
16034 vector __int128_t vec_vaddeuqm (vector __int128_t, vector __int128_t,
16035 vector __int128_t);
16036 vector __uint128_t vec_vaddeuqm (vector __uint128_t, vector __uint128_t,
16037 vector __uint128_t);
16039 vector __int128_t vec_vsubecuq (vector __int128_t, vector __int128_t,
16040 vector __int128_t);
16041 vector __uint128_t vec_vsubecuq (vector __uint128_t, vector __uint128_t,
16042 vector __uint128_t);
16044 vector __int128_t vec_vsubeuqm (vector __int128_t, vector __int128_t,
16045 vector __int128_t);
16046 vector __uint128_t vec_vsubeuqm (vector __uint128_t, vector __uint128_t,
16047 vector __uint128_t);
16049 vector __int128_t vec_vsubcuq (vector __int128_t, vector __int128_t);
16050 vector __uint128_t vec_vsubcuq (vector __uint128_t, vector __uint128_t);
16052 __int128_t vec_vsubuqm (__int128_t, __int128_t);
16053 __uint128_t vec_vsubuqm (__uint128_t, __uint128_t);
16055 vector __int128_t __builtin_bcdadd (vector __int128_t, vector__int128_t);
16056 int __builtin_bcdadd_lt (vector __int128_t, vector__int128_t);
16057 int __builtin_bcdadd_eq (vector __int128_t, vector__int128_t);
16058 int __builtin_bcdadd_gt (vector __int128_t, vector__int128_t);
16059 int __builtin_bcdadd_ov (vector __int128_t, vector__int128_t);
16060 vector __int128_t bcdsub (vector __int128_t, vector__int128_t);
16061 int __builtin_bcdsub_lt (vector __int128_t, vector__int128_t);
16062 int __builtin_bcdsub_eq (vector __int128_t, vector__int128_t);
16063 int __builtin_bcdsub_gt (vector __int128_t, vector__int128_t);
16064 int __builtin_bcdsub_ov (vector __int128_t, vector__int128_t);
16067 If the cryptographic instructions are enabled (@option{-mcrypto} or
16068 @option{-mcpu=power8}), the following builtins are enabled.
16071 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
16073 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
16074 vector unsigned long long);
16076 vector unsigned long long __builtin_crypto_vcipherlast
16077 (vector unsigned long long,
16078 vector unsigned long long);
16080 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
16081 vector unsigned long long);
16083 vector unsigned long long __builtin_crypto_vncipherlast
16084 (vector unsigned long long,
16085 vector unsigned long long);
16087 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
16088 vector unsigned char,
16089 vector unsigned char);
16091 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
16092 vector unsigned short,
16093 vector unsigned short);
16095 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
16096 vector unsigned int,
16097 vector unsigned int);
16099 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
16100 vector unsigned long long,
16101 vector unsigned long long);
16103 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
16104 vector unsigned char);
16106 vector unsigned short __builtin_crypto_vpmsumb (vector unsigned short,
16107 vector unsigned short);
16109 vector unsigned int __builtin_crypto_vpmsumb (vector unsigned int,
16110 vector unsigned int);
16112 vector unsigned long long __builtin_crypto_vpmsumb (vector unsigned long long,
16113 vector unsigned long long);
16115 vector unsigned long long __builtin_crypto_vshasigmad
16116 (vector unsigned long long, int, int);
16118 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int,
16122 The second argument to the @var{__builtin_crypto_vshasigmad} and
16123 @var{__builtin_crypto_vshasigmaw} builtin functions must be a constant
16124 integer that is 0 or 1. The third argument to these builtin functions
16125 must be a constant integer in the range of 0 to 15.
16127 @node PowerPC Hardware Transactional Memory Built-in Functions
16128 @subsection PowerPC Hardware Transactional Memory Built-in Functions
16129 GCC provides two interfaces for accessing the Hardware Transactional
16130 Memory (HTM) instructions available on some of the PowerPC family
16131 of processors (eg, POWER8). The two interfaces come in a low level
16132 interface, consisting of built-in functions specific to PowerPC and a
16133 higher level interface consisting of inline functions that are common
16134 between PowerPC and S/390.
16136 @subsubsection PowerPC HTM Low Level Built-in Functions
16138 The following low level built-in functions are available with
16139 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
16140 They all generate the machine instruction that is part of the name.
16142 The HTM builtins (with the exception of @code{__builtin_tbegin}) return
16143 the full 4-bit condition register value set by their associated hardware
16144 instruction. The header file @code{htmintrin.h} defines some macros that can
16145 be used to decipher the return value. The @code{__builtin_tbegin} builtin
16146 returns a simple true or false value depending on whether a transaction was
16147 successfully started or not. The arguments of the builtins match exactly the
16148 type and order of the associated hardware instruction's operands, except for
16149 the @code{__builtin_tcheck} builtin, which does not take any input arguments.
16150 Refer to the ISA manual for a description of each instruction's operands.
16153 unsigned int __builtin_tbegin (unsigned int)
16154 unsigned int __builtin_tend (unsigned int)
16156 unsigned int __builtin_tabort (unsigned int)
16157 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int)
16158 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int)
16159 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int)
16160 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int)
16162 unsigned int __builtin_tcheck (void)
16163 unsigned int __builtin_treclaim (unsigned int)
16164 unsigned int __builtin_trechkpt (void)
16165 unsigned int __builtin_tsr (unsigned int)
16168 In addition to the above HTM built-ins, we have added built-ins for
16169 some common extended mnemonics of the HTM instructions:
16172 unsigned int __builtin_tendall (void)
16173 unsigned int __builtin_tresume (void)
16174 unsigned int __builtin_tsuspend (void)
16177 Note that the semantics of the above HTM builtins are required to mimic
16178 the locking semantics used for critical sections. Builtins that are used
16179 to create a new transaction or restart a suspended transaction must have
16180 lock acquisition like semantics while those builtins that end or suspend a
16181 transaction must have lock release like semantics. Specifically, this must
16182 mimic lock semantics as specified by C++11, for example: Lock acquisition is
16183 as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE)
16184 that returns 0, and lock release is as-if an execution of
16185 __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an
16186 implicit implementation-defined lock used for all transactions. The HTM
16187 instructions associated with with the builtins inherently provide the
16188 correct acquisition and release hardware barriers required. However,
16189 the compiler must also be prohibited from moving loads and stores across
16190 the builtins in a way that would violate their semantics. This has been
16191 accomplished by adding memory barriers to the associated HTM instructions
16192 (which is a conservative approach to provide acquire and release semantics).
16193 Earlier versions of the compiler did not treat the HTM instructions as
16194 memory barriers. A @code{__TM_FENCE__} macro has been added, which can
16195 be used to determine whether the current compiler treats HTM instructions
16196 as memory barriers or not. This allows the user to explicitly add memory
16197 barriers to their code when using an older version of the compiler.
16199 The following set of built-in functions are available to gain access
16200 to the HTM specific special purpose registers.
16203 unsigned long __builtin_get_texasr (void)
16204 unsigned long __builtin_get_texasru (void)
16205 unsigned long __builtin_get_tfhar (void)
16206 unsigned long __builtin_get_tfiar (void)
16208 void __builtin_set_texasr (unsigned long);
16209 void __builtin_set_texasru (unsigned long);
16210 void __builtin_set_tfhar (unsigned long);
16211 void __builtin_set_tfiar (unsigned long);
16214 Example usage of these low level built-in functions may look like:
16217 #include <htmintrin.h>
16219 int num_retries = 10;
16223 if (__builtin_tbegin (0))
16225 /* Transaction State Initiated. */
16226 if (is_locked (lock))
16227 __builtin_tabort (0);
16228 ... transaction code...
16229 __builtin_tend (0);
16234 /* Transaction State Failed. Use locks if the transaction
16235 failure is "persistent" or we've tried too many times. */
16236 if (num_retries-- <= 0
16237 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
16239 acquire_lock (lock);
16240 ... non transactional fallback path...
16241 release_lock (lock);
16248 One final built-in function has been added that returns the value of
16249 the 2-bit Transaction State field of the Machine Status Register (MSR)
16250 as stored in @code{CR0}.
16253 unsigned long __builtin_ttest (void)
16256 This built-in can be used to determine the current transaction state
16257 using the following code example:
16260 #include <htmintrin.h>
16262 unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
16264 if (tx_state == _HTM_TRANSACTIONAL)
16266 /* Code to use in transactional state. */
16268 else if (tx_state == _HTM_NONTRANSACTIONAL)
16270 /* Code to use in non-transactional state. */
16272 else if (tx_state == _HTM_SUSPENDED)
16274 /* Code to use in transaction suspended state. */
16278 @subsubsection PowerPC HTM High Level Inline Functions
16280 The following high level HTM interface is made available by including
16281 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
16282 where CPU is `power8' or later. This interface is common between PowerPC
16283 and S/390, allowing users to write one HTM source implementation that
16284 can be compiled and executed on either system.
16287 long __TM_simple_begin (void)
16288 long __TM_begin (void* const TM_buff)
16289 long __TM_end (void)
16290 void __TM_abort (void)
16291 void __TM_named_abort (unsigned char const code)
16292 void __TM_resume (void)
16293 void __TM_suspend (void)
16295 long __TM_is_user_abort (void* const TM_buff)
16296 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code)
16297 long __TM_is_illegal (void* const TM_buff)
16298 long __TM_is_footprint_exceeded (void* const TM_buff)
16299 long __TM_nesting_depth (void* const TM_buff)
16300 long __TM_is_nested_too_deep(void* const TM_buff)
16301 long __TM_is_conflict(void* const TM_buff)
16302 long __TM_is_failure_persistent(void* const TM_buff)
16303 long __TM_failure_address(void* const TM_buff)
16304 long long __TM_failure_code(void* const TM_buff)
16307 Using these common set of HTM inline functions, we can create
16308 a more portable version of the HTM example in the previous
16309 section that will work on either PowerPC or S/390:
16312 #include <htmxlintrin.h>
16314 int num_retries = 10;
16315 TM_buff_type TM_buff;
16319 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED)
16321 /* Transaction State Initiated. */
16322 if (is_locked (lock))
16324 ... transaction code...
16330 /* Transaction State Failed. Use locks if the transaction
16331 failure is "persistent" or we've tried too many times. */
16332 if (num_retries-- <= 0
16333 || __TM_is_failure_persistent (TM_buff))
16335 acquire_lock (lock);
16336 ... non transactional fallback path...
16337 release_lock (lock);
16344 @node RX Built-in Functions
16345 @subsection RX Built-in Functions
16346 GCC supports some of the RX instructions which cannot be expressed in
16347 the C programming language via the use of built-in functions. The
16348 following functions are supported:
16350 @deftypefn {Built-in Function} void __builtin_rx_brk (void)
16351 Generates the @code{brk} machine instruction.
16354 @deftypefn {Built-in Function} void __builtin_rx_clrpsw (int)
16355 Generates the @code{clrpsw} machine instruction to clear the specified
16356 bit in the processor status word.
16359 @deftypefn {Built-in Function} void __builtin_rx_int (int)
16360 Generates the @code{int} machine instruction to generate an interrupt
16361 with the specified value.
16364 @deftypefn {Built-in Function} void __builtin_rx_machi (int, int)
16365 Generates the @code{machi} machine instruction to add the result of
16366 multiplying the top 16 bits of the two arguments into the
16370 @deftypefn {Built-in Function} void __builtin_rx_maclo (int, int)
16371 Generates the @code{maclo} machine instruction to add the result of
16372 multiplying the bottom 16 bits of the two arguments into the
16376 @deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int)
16377 Generates the @code{mulhi} machine instruction to place the result of
16378 multiplying the top 16 bits of the two arguments into the
16382 @deftypefn {Built-in Function} void __builtin_rx_mullo (int, int)
16383 Generates the @code{mullo} machine instruction to place the result of
16384 multiplying the bottom 16 bits of the two arguments into the
16388 @deftypefn {Built-in Function} int __builtin_rx_mvfachi (void)
16389 Generates the @code{mvfachi} machine instruction to read the top
16390 32 bits of the accumulator.
16393 @deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void)
16394 Generates the @code{mvfacmi} machine instruction to read the middle
16395 32 bits of the accumulator.
16398 @deftypefn {Built-in Function} int __builtin_rx_mvfc (int)
16399 Generates the @code{mvfc} machine instruction which reads the control
16400 register specified in its argument and returns its value.
16403 @deftypefn {Built-in Function} void __builtin_rx_mvtachi (int)
16404 Generates the @code{mvtachi} machine instruction to set the top
16405 32 bits of the accumulator.
16408 @deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int)
16409 Generates the @code{mvtaclo} machine instruction to set the bottom
16410 32 bits of the accumulator.
16413 @deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val)
16414 Generates the @code{mvtc} machine instruction which sets control
16415 register number @code{reg} to @code{val}.
16418 @deftypefn {Built-in Function} void __builtin_rx_mvtipl (int)
16419 Generates the @code{mvtipl} machine instruction set the interrupt
16423 @deftypefn {Built-in Function} void __builtin_rx_racw (int)
16424 Generates the @code{racw} machine instruction to round the accumulator
16425 according to the specified mode.
16428 @deftypefn {Built-in Function} int __builtin_rx_revw (int)
16429 Generates the @code{revw} machine instruction which swaps the bytes in
16430 the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
16431 and also bits 16--23 occupy bits 24--31 and vice versa.
16434 @deftypefn {Built-in Function} void __builtin_rx_rmpa (void)
16435 Generates the @code{rmpa} machine instruction which initiates a
16436 repeated multiply and accumulate sequence.
16439 @deftypefn {Built-in Function} void __builtin_rx_round (float)
16440 Generates the @code{round} machine instruction which returns the
16441 floating-point argument rounded according to the current rounding mode
16442 set in the floating-point status word register.
16445 @deftypefn {Built-in Function} int __builtin_rx_sat (int)
16446 Generates the @code{sat} machine instruction which returns the
16447 saturated value of the argument.
16450 @deftypefn {Built-in Function} void __builtin_rx_setpsw (int)
16451 Generates the @code{setpsw} machine instruction to set the specified
16452 bit in the processor status word.
16455 @deftypefn {Built-in Function} void __builtin_rx_wait (void)
16456 Generates the @code{wait} machine instruction.
16459 @node S/390 System z Built-in Functions
16460 @subsection S/390 System z Built-in Functions
16461 @deftypefn {Built-in Function} int __builtin_tbegin (void*)
16462 Generates the @code{tbegin} machine instruction starting a
16463 non-constraint hardware transaction. If the parameter is non-NULL the
16464 memory area is used to store the transaction diagnostic buffer and
16465 will be passed as first operand to @code{tbegin}. This buffer can be
16466 defined using the @code{struct __htm_tdb} C struct defined in
16467 @code{htmintrin.h} and must reside on a double-word boundary. The
16468 second tbegin operand is set to @code{0xff0c}. This enables
16469 save/restore of all GPRs and disables aborts for FPR and AR
16470 manipulations inside the transaction body. The condition code set by
16471 the tbegin instruction is returned as integer value. The tbegin
16472 instruction by definition overwrites the content of all FPRs. The
16473 compiler will generate code which saves and restores the FPRs. For
16474 soft-float code it is recommended to used the @code{*_nofloat}
16475 variant. In order to prevent a TDB from being written it is required
16476 to pass an constant zero value as parameter. Passing the zero value
16477 through a variable is not sufficient. Although modifications of
16478 access registers inside the transaction will not trigger an
16479 transaction abort it is not supported to actually modify them. Access
16480 registers do not get saved when entering a transaction. They will have
16481 undefined state when reaching the abort code.
16484 Macros for the possible return codes of tbegin are defined in the
16485 @code{htmintrin.h} header file:
16488 @item _HTM_TBEGIN_STARTED
16489 @code{tbegin} has been executed as part of normal processing. The
16490 transaction body is supposed to be executed.
16491 @item _HTM_TBEGIN_INDETERMINATE
16492 The transaction was aborted due to an indeterminate condition which
16493 might be persistent.
16494 @item _HTM_TBEGIN_TRANSIENT
16495 The transaction aborted due to a transient failure. The transaction
16496 should be re-executed in that case.
16497 @item _HTM_TBEGIN_PERSISTENT
16498 The transaction aborted due to a persistent failure. Re-execution
16499 under same circumstances will not be productive.
16502 @defmac _HTM_FIRST_USER_ABORT_CODE
16503 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
16504 specifies the first abort code which can be used for
16505 @code{__builtin_tabort}. Values below this threshold are reserved for
16509 @deftp {Data type} {struct __htm_tdb}
16510 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
16511 the structure of the transaction diagnostic block as specified in the
16512 Principles of Operation manual chapter 5-91.
16515 @deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*)
16516 Same as @code{__builtin_tbegin} but without FPR saves and restores.
16517 Using this variant in code making use of FPRs will leave the FPRs in
16518 undefined state when entering the transaction abort handler code.
16521 @deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int)
16522 In addition to @code{__builtin_tbegin} a loop for transient failures
16523 is generated. If tbegin returns a condition code of 2 the transaction
16524 will be retried as often as specified in the second argument. The
16525 perform processor assist instruction is used to tell the CPU about the
16526 number of fails so far.
16529 @deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int)
16530 Same as @code{__builtin_tbegin_retry} but without FPR saves and
16531 restores. Using this variant in code making use of FPRs will leave
16532 the FPRs in undefined state when entering the transaction abort
16536 @deftypefn {Built-in Function} void __builtin_tbeginc (void)
16537 Generates the @code{tbeginc} machine instruction starting a constraint
16538 hardware transaction. The second operand is set to @code{0xff08}.
16541 @deftypefn {Built-in Function} int __builtin_tend (void)
16542 Generates the @code{tend} machine instruction finishing a transaction
16543 and making the changes visible to other threads. The condition code
16544 generated by tend is returned as integer value.
16547 @deftypefn {Built-in Function} void __builtin_tabort (int)
16548 Generates the @code{tabort} machine instruction with the specified
16549 abort code. Abort codes from 0 through 255 are reserved and will
16550 result in an error message.
16553 @deftypefn {Built-in Function} void __builtin_tx_assist (int)
16554 Generates the @code{ppa rX,rY,1} machine instruction. Where the
16555 integer parameter is loaded into rX and a value of zero is loaded into
16556 rY. The integer parameter specifies the number of times the
16557 transaction repeatedly aborted.
16560 @deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void)
16561 Generates the @code{etnd} machine instruction. The current nesting
16562 depth is returned as integer value. For a nesting depth of 0 the code
16563 is not executed as part of an transaction.
16566 @deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t)
16568 Generates the @code{ntstg} machine instruction. The second argument
16569 is written to the first arguments location. The store operation will
16570 not be rolled-back in case of an transaction abort.
16573 @node SH Built-in Functions
16574 @subsection SH Built-in Functions
16575 The following built-in functions are supported on the SH1, SH2, SH3 and SH4
16576 families of processors:
16578 @deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr})
16579 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
16580 used by system code that manages threads and execution contexts. The compiler
16581 normally does not generate code that modifies the contents of @samp{GBR} and
16582 thus the value is preserved across function calls. Changing the @samp{GBR}
16583 value in user code must be done with caution, since the compiler might use
16584 @samp{GBR} in order to access thread local variables.
16588 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
16589 Returns the value that is currently set in the @samp{GBR} register.
16590 Memory loads and stores that use the thread pointer as a base address are
16591 turned into @samp{GBR} based displacement loads and stores, if possible.
16599 int get_tcb_value (void)
16601 // Generate @samp{mov.l @@(8,gbr),r0} instruction
16602 return ((my_tcb*)__builtin_thread_pointer ())->c;
16608 @deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void)
16609 Returns the value that is currently set in the @samp{FPSCR} register.
16612 @deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val})
16613 Sets the @samp{FPSCR} register to the specified value @var{val}, while
16614 preserving the current values of the FR, SZ and PR bits.
16617 @node SPARC VIS Built-in Functions
16618 @subsection SPARC VIS Built-in Functions
16620 GCC supports SIMD operations on the SPARC using both the generic vector
16621 extensions (@pxref{Vector Extensions}) as well as built-in functions for
16622 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
16623 switch, the VIS extension is exposed as the following built-in functions:
16626 typedef int v1si __attribute__ ((vector_size (4)));
16627 typedef int v2si __attribute__ ((vector_size (8)));
16628 typedef short v4hi __attribute__ ((vector_size (8)));
16629 typedef short v2hi __attribute__ ((vector_size (4)));
16630 typedef unsigned char v8qi __attribute__ ((vector_size (8)));
16631 typedef unsigned char v4qi __attribute__ ((vector_size (4)));
16633 void __builtin_vis_write_gsr (int64_t);
16634 int64_t __builtin_vis_read_gsr (void);
16636 void * __builtin_vis_alignaddr (void *, long);
16637 void * __builtin_vis_alignaddrl (void *, long);
16638 int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
16639 v2si __builtin_vis_faligndatav2si (v2si, v2si);
16640 v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
16641 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
16643 v4hi __builtin_vis_fexpand (v4qi);
16645 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
16646 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
16647 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
16648 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
16649 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
16650 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
16651 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
16653 v4qi __builtin_vis_fpack16 (v4hi);
16654 v8qi __builtin_vis_fpack32 (v2si, v8qi);
16655 v2hi __builtin_vis_fpackfix (v2si);
16656 v8qi __builtin_vis_fpmerge (v4qi, v4qi);
16658 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
16660 long __builtin_vis_edge8 (void *, void *);
16661 long __builtin_vis_edge8l (void *, void *);
16662 long __builtin_vis_edge16 (void *, void *);
16663 long __builtin_vis_edge16l (void *, void *);
16664 long __builtin_vis_edge32 (void *, void *);
16665 long __builtin_vis_edge32l (void *, void *);
16667 long __builtin_vis_fcmple16 (v4hi, v4hi);
16668 long __builtin_vis_fcmple32 (v2si, v2si);
16669 long __builtin_vis_fcmpne16 (v4hi, v4hi);
16670 long __builtin_vis_fcmpne32 (v2si, v2si);
16671 long __builtin_vis_fcmpgt16 (v4hi, v4hi);
16672 long __builtin_vis_fcmpgt32 (v2si, v2si);
16673 long __builtin_vis_fcmpeq16 (v4hi, v4hi);
16674 long __builtin_vis_fcmpeq32 (v2si, v2si);
16676 v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
16677 v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
16678 v2si __builtin_vis_fpadd32 (v2si, v2si);
16679 v1si __builtin_vis_fpadd32s (v1si, v1si);
16680 v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
16681 v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
16682 v2si __builtin_vis_fpsub32 (v2si, v2si);
16683 v1si __builtin_vis_fpsub32s (v1si, v1si);
16685 long __builtin_vis_array8 (long, long);
16686 long __builtin_vis_array16 (long, long);
16687 long __builtin_vis_array32 (long, long);
16690 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
16691 functions also become available:
16694 long __builtin_vis_bmask (long, long);
16695 int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
16696 v2si __builtin_vis_bshufflev2si (v2si, v2si);
16697 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
16698 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
16700 long __builtin_vis_edge8n (void *, void *);
16701 long __builtin_vis_edge8ln (void *, void *);
16702 long __builtin_vis_edge16n (void *, void *);
16703 long __builtin_vis_edge16ln (void *, void *);
16704 long __builtin_vis_edge32n (void *, void *);
16705 long __builtin_vis_edge32ln (void *, void *);
16708 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
16709 functions also become available:
16712 void __builtin_vis_cmask8 (long);
16713 void __builtin_vis_cmask16 (long);
16714 void __builtin_vis_cmask32 (long);
16716 v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
16718 v4hi __builtin_vis_fsll16 (v4hi, v4hi);
16719 v4hi __builtin_vis_fslas16 (v4hi, v4hi);
16720 v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
16721 v4hi __builtin_vis_fsra16 (v4hi, v4hi);
16722 v2si __builtin_vis_fsll16 (v2si, v2si);
16723 v2si __builtin_vis_fslas16 (v2si, v2si);
16724 v2si __builtin_vis_fsrl16 (v2si, v2si);
16725 v2si __builtin_vis_fsra16 (v2si, v2si);
16727 long __builtin_vis_pdistn (v8qi, v8qi);
16729 v4hi __builtin_vis_fmean16 (v4hi, v4hi);
16731 int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
16732 int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
16734 v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
16735 v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
16736 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
16737 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
16738 v2si __builtin_vis_fpadds32 (v2si, v2si);
16739 v1si __builtin_vis_fpadds32s (v1si, v1si);
16740 v2si __builtin_vis_fpsubs32 (v2si, v2si);
16741 v1si __builtin_vis_fpsubs32s (v1si, v1si);
16743 long __builtin_vis_fucmple8 (v8qi, v8qi);
16744 long __builtin_vis_fucmpne8 (v8qi, v8qi);
16745 long __builtin_vis_fucmpgt8 (v8qi, v8qi);
16746 long __builtin_vis_fucmpeq8 (v8qi, v8qi);
16748 float __builtin_vis_fhadds (float, float);
16749 double __builtin_vis_fhaddd (double, double);
16750 float __builtin_vis_fhsubs (float, float);
16751 double __builtin_vis_fhsubd (double, double);
16752 float __builtin_vis_fnhadds (float, float);
16753 double __builtin_vis_fnhaddd (double, double);
16755 int64_t __builtin_vis_umulxhi (int64_t, int64_t);
16756 int64_t __builtin_vis_xmulx (int64_t, int64_t);
16757 int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
16760 @node SPU Built-in Functions
16761 @subsection SPU Built-in Functions
16763 GCC provides extensions for the SPU processor as described in the
16764 Sony/Toshiba/IBM SPU Language Extensions Specification, which can be
16765 found at @uref{http://cell.scei.co.jp/} or
16766 @uref{http://www.ibm.com/developerworks/power/cell/}. GCC's
16767 implementation differs in several ways.
16772 The optional extension of specifying vector constants in parentheses is
16776 A vector initializer requires no cast if the vector constant is of the
16777 same type as the variable it is initializing.
16780 If @code{signed} or @code{unsigned} is omitted, the signedness of the
16781 vector type is the default signedness of the base type. The default
16782 varies depending on the operating system, so a portable program should
16783 always specify the signedness.
16786 By default, the keyword @code{__vector} is added. The macro
16787 @code{vector} is defined in @code{<spu_intrinsics.h>} and can be
16791 GCC allows using a @code{typedef} name as the type specifier for a
16795 For C, overloaded functions are implemented with macros so the following
16799 spu_add ((vector signed int)@{1, 2, 3, 4@}, foo);
16803 Since @code{spu_add} is a macro, the vector constant in the example
16804 is treated as four separate arguments. Wrap the entire argument in
16805 parentheses for this to work.
16808 The extended version of @code{__builtin_expect} is not supported.
16812 @emph{Note:} Only the interface described in the aforementioned
16813 specification is supported. Internally, GCC uses built-in functions to
16814 implement the required functionality, but these are not supported and
16815 are subject to change without notice.
16817 @node TI C6X Built-in Functions
16818 @subsection TI C6X Built-in Functions
16820 GCC provides intrinsics to access certain instructions of the TI C6X
16821 processors. These intrinsics, listed below, are available after
16822 inclusion of the @code{c6x_intrinsics.h} header file. They map directly
16823 to C6X instructions.
16827 int _sadd (int, int)
16828 int _ssub (int, int)
16829 int _sadd2 (int, int)
16830 int _ssub2 (int, int)
16831 long long _mpy2 (int, int)
16832 long long _smpy2 (int, int)
16833 int _add4 (int, int)
16834 int _sub4 (int, int)
16835 int _saddu4 (int, int)
16837 int _smpy (int, int)
16838 int _smpyh (int, int)
16839 int _smpyhl (int, int)
16840 int _smpylh (int, int)
16842 int _sshl (int, int)
16843 int _subc (int, int)
16845 int _avg2 (int, int)
16846 int _avgu4 (int, int)
16848 int _clrr (int, int)
16849 int _extr (int, int)
16850 int _extru (int, int)
16856 @node TILE-Gx Built-in Functions
16857 @subsection TILE-Gx Built-in Functions
16859 GCC provides intrinsics to access every instruction of the TILE-Gx
16860 processor. The intrinsics are of the form:
16864 unsigned long long __insn_@var{op} (...)
16868 Where @var{op} is the name of the instruction. Refer to the ISA manual
16869 for the complete list of instructions.
16871 GCC also provides intrinsics to directly access the network registers.
16872 The intrinsics are:
16876 unsigned long long __tile_idn0_receive (void)
16877 unsigned long long __tile_idn1_receive (void)
16878 unsigned long long __tile_udn0_receive (void)
16879 unsigned long long __tile_udn1_receive (void)
16880 unsigned long long __tile_udn2_receive (void)
16881 unsigned long long __tile_udn3_receive (void)
16882 void __tile_idn_send (unsigned long long)
16883 void __tile_udn_send (unsigned long long)
16887 The intrinsic @code{void __tile_network_barrier (void)} is used to
16888 guarantee that no network operations before it are reordered with
16891 @node TILEPro Built-in Functions
16892 @subsection TILEPro Built-in Functions
16894 GCC provides intrinsics to access every instruction of the TILEPro
16895 processor. The intrinsics are of the form:
16899 unsigned __insn_@var{op} (...)
16904 where @var{op} is the name of the instruction. Refer to the ISA manual
16905 for the complete list of instructions.
16907 GCC also provides intrinsics to directly access the network registers.
16908 The intrinsics are:
16912 unsigned __tile_idn0_receive (void)
16913 unsigned __tile_idn1_receive (void)
16914 unsigned __tile_sn_receive (void)
16915 unsigned __tile_udn0_receive (void)
16916 unsigned __tile_udn1_receive (void)
16917 unsigned __tile_udn2_receive (void)
16918 unsigned __tile_udn3_receive (void)
16919 void __tile_idn_send (unsigned)
16920 void __tile_sn_send (unsigned)
16921 void __tile_udn_send (unsigned)
16925 The intrinsic @code{void __tile_network_barrier (void)} is used to
16926 guarantee that no network operations before it are reordered with
16929 @node x86 Built-in Functions
16930 @subsection x86 Built-in Functions
16932 These built-in functions are available for the x86-32 and x86-64 family
16933 of computers, depending on the command-line switches used.
16935 If you specify command-line switches such as @option{-msse},
16936 the compiler could use the extended instruction sets even if the built-ins
16937 are not used explicitly in the program. For this reason, applications
16938 that perform run-time CPU detection must compile separate files for each
16939 supported architecture, using the appropriate flags. In particular,
16940 the file containing the CPU detection code should be compiled without
16943 The following machine modes are available for use with MMX built-in functions
16944 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
16945 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
16946 vector of eight 8-bit integers. Some of the built-in functions operate on
16947 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
16949 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
16950 of two 32-bit floating-point values.
16952 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
16953 floating-point values. Some instructions use a vector of four 32-bit
16954 integers, these use @code{V4SI}. Finally, some instructions operate on an
16955 entire vector register, interpreting it as a 128-bit integer, these use mode
16958 In 64-bit mode, the x86-64 family of processors uses additional built-in
16959 functions for efficient use of @code{TF} (@code{__float128}) 128-bit
16960 floating point and @code{TC} 128-bit complex floating-point values.
16962 The following floating-point built-in functions are available in 64-bit
16963 mode. All of them implement the function that is part of the name.
16966 __float128 __builtin_fabsq (__float128)
16967 __float128 __builtin_copysignq (__float128, __float128)
16970 The following built-in function is always available.
16973 @item void __builtin_ia32_pause (void)
16974 Generates the @code{pause} machine instruction with a compiler memory
16978 The following floating-point built-in functions are made available in the
16982 @item __float128 __builtin_infq (void)
16983 Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
16984 @findex __builtin_infq
16986 @item __float128 __builtin_huge_valq (void)
16987 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
16988 @findex __builtin_huge_valq
16991 The following built-in functions are always available and can be used to
16992 check the target platform type.
16994 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
16995 This function runs the CPU detection code to check the type of CPU and the
16996 features supported. This built-in function needs to be invoked along with the built-in functions
16997 to check CPU type and features, @code{__builtin_cpu_is} and
16998 @code{__builtin_cpu_supports}, only when used in a function that is
16999 executed before any constructors are called. The CPU detection code is
17000 automatically executed in a very high priority constructor.
17002 For example, this function has to be used in @code{ifunc} resolvers that
17003 check for CPU type using the built-in functions @code{__builtin_cpu_is}
17004 and @code{__builtin_cpu_supports}, or in constructors on targets that
17005 don't support constructor priority.
17008 static void (*resolve_memcpy (void)) (void)
17010 // ifunc resolvers fire before constructors, explicitly call the init
17012 __builtin_cpu_init ();
17013 if (__builtin_cpu_supports ("ssse3"))
17014 return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
17016 return default_memcpy;
17019 void *memcpy (void *, const void *, size_t)
17020 __attribute__ ((ifunc ("resolve_memcpy")));
17025 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
17026 This function returns a positive integer if the run-time CPU
17027 is of type @var{cpuname}
17028 and returns @code{0} otherwise. The following CPU names can be detected:
17044 Intel Core i7 Nehalem CPU.
17047 Intel Core i7 Westmere CPU.
17050 Intel Core i7 Sandy Bridge CPU.
17056 AMD Family 10h CPU.
17059 AMD Family 10h Barcelona CPU.
17062 AMD Family 10h Shanghai CPU.
17065 AMD Family 10h Istanbul CPU.
17068 AMD Family 14h CPU.
17071 AMD Family 15h CPU.
17074 AMD Family 15h Bulldozer version 1.
17077 AMD Family 15h Bulldozer version 2.
17080 AMD Family 15h Bulldozer version 3.
17083 AMD Family 15h Bulldozer version 4.
17086 AMD Family 16h CPU.
17089 AMD Family 17h CPU.
17092 Here is an example:
17094 if (__builtin_cpu_is ("corei7"))
17096 do_corei7 (); // Core i7 specific implementation.
17100 do_generic (); // Generic implementation.
17105 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
17106 This function returns a positive integer if the run-time CPU
17107 supports @var{feature}
17108 and returns @code{0} otherwise. The following features can be detected:
17116 POPCNT instruction.
17124 SSSE3 instructions.
17126 SSE4.1 instructions.
17128 SSE4.2 instructions.
17134 AVX512F instructions.
17137 Here is an example:
17139 if (__builtin_cpu_supports ("popcnt"))
17141 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
17145 count = generic_countbits (n); //generic implementation.
17151 The following built-in functions are made available by @option{-mmmx}.
17152 All of them generate the machine instruction that is part of the name.
17155 v8qi __builtin_ia32_paddb (v8qi, v8qi)
17156 v4hi __builtin_ia32_paddw (v4hi, v4hi)
17157 v2si __builtin_ia32_paddd (v2si, v2si)
17158 v8qi __builtin_ia32_psubb (v8qi, v8qi)
17159 v4hi __builtin_ia32_psubw (v4hi, v4hi)
17160 v2si __builtin_ia32_psubd (v2si, v2si)
17161 v8qi __builtin_ia32_paddsb (v8qi, v8qi)
17162 v4hi __builtin_ia32_paddsw (v4hi, v4hi)
17163 v8qi __builtin_ia32_psubsb (v8qi, v8qi)
17164 v4hi __builtin_ia32_psubsw (v4hi, v4hi)
17165 v8qi __builtin_ia32_paddusb (v8qi, v8qi)
17166 v4hi __builtin_ia32_paddusw (v4hi, v4hi)
17167 v8qi __builtin_ia32_psubusb (v8qi, v8qi)
17168 v4hi __builtin_ia32_psubusw (v4hi, v4hi)
17169 v4hi __builtin_ia32_pmullw (v4hi, v4hi)
17170 v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
17171 di __builtin_ia32_pand (di, di)
17172 di __builtin_ia32_pandn (di,di)
17173 di __builtin_ia32_por (di, di)
17174 di __builtin_ia32_pxor (di, di)
17175 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
17176 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
17177 v2si __builtin_ia32_pcmpeqd (v2si, v2si)
17178 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
17179 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
17180 v2si __builtin_ia32_pcmpgtd (v2si, v2si)
17181 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
17182 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
17183 v2si __builtin_ia32_punpckhdq (v2si, v2si)
17184 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
17185 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
17186 v2si __builtin_ia32_punpckldq (v2si, v2si)
17187 v8qi __builtin_ia32_packsswb (v4hi, v4hi)
17188 v4hi __builtin_ia32_packssdw (v2si, v2si)
17189 v8qi __builtin_ia32_packuswb (v4hi, v4hi)
17191 v4hi __builtin_ia32_psllw (v4hi, v4hi)
17192 v2si __builtin_ia32_pslld (v2si, v2si)
17193 v1di __builtin_ia32_psllq (v1di, v1di)
17194 v4hi __builtin_ia32_psrlw (v4hi, v4hi)
17195 v2si __builtin_ia32_psrld (v2si, v2si)
17196 v1di __builtin_ia32_psrlq (v1di, v1di)
17197 v4hi __builtin_ia32_psraw (v4hi, v4hi)
17198 v2si __builtin_ia32_psrad (v2si, v2si)
17199 v4hi __builtin_ia32_psllwi (v4hi, int)
17200 v2si __builtin_ia32_pslldi (v2si, int)
17201 v1di __builtin_ia32_psllqi (v1di, int)
17202 v4hi __builtin_ia32_psrlwi (v4hi, int)
17203 v2si __builtin_ia32_psrldi (v2si, int)
17204 v1di __builtin_ia32_psrlqi (v1di, int)
17205 v4hi __builtin_ia32_psrawi (v4hi, int)
17206 v2si __builtin_ia32_psradi (v2si, int)
17210 The following built-in functions are made available either with
17211 @option{-msse}, or with a combination of @option{-m3dnow} and
17212 @option{-march=athlon}. All of them generate the machine
17213 instruction that is part of the name.
17216 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
17217 v8qi __builtin_ia32_pavgb (v8qi, v8qi)
17218 v4hi __builtin_ia32_pavgw (v4hi, v4hi)
17219 v1di __builtin_ia32_psadbw (v8qi, v8qi)
17220 v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
17221 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
17222 v8qi __builtin_ia32_pminub (v8qi, v8qi)
17223 v4hi __builtin_ia32_pminsw (v4hi, v4hi)
17224 int __builtin_ia32_pmovmskb (v8qi)
17225 void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
17226 void __builtin_ia32_movntq (di *, di)
17227 void __builtin_ia32_sfence (void)
17230 The following built-in functions are available when @option{-msse} is used.
17231 All of them generate the machine instruction that is part of the name.
17234 int __builtin_ia32_comieq (v4sf, v4sf)
17235 int __builtin_ia32_comineq (v4sf, v4sf)
17236 int __builtin_ia32_comilt (v4sf, v4sf)
17237 int __builtin_ia32_comile (v4sf, v4sf)
17238 int __builtin_ia32_comigt (v4sf, v4sf)
17239 int __builtin_ia32_comige (v4sf, v4sf)
17240 int __builtin_ia32_ucomieq (v4sf, v4sf)
17241 int __builtin_ia32_ucomineq (v4sf, v4sf)
17242 int __builtin_ia32_ucomilt (v4sf, v4sf)
17243 int __builtin_ia32_ucomile (v4sf, v4sf)
17244 int __builtin_ia32_ucomigt (v4sf, v4sf)
17245 int __builtin_ia32_ucomige (v4sf, v4sf)
17246 v4sf __builtin_ia32_addps (v4sf, v4sf)
17247 v4sf __builtin_ia32_subps (v4sf, v4sf)
17248 v4sf __builtin_ia32_mulps (v4sf, v4sf)
17249 v4sf __builtin_ia32_divps (v4sf, v4sf)
17250 v4sf __builtin_ia32_addss (v4sf, v4sf)
17251 v4sf __builtin_ia32_subss (v4sf, v4sf)
17252 v4sf __builtin_ia32_mulss (v4sf, v4sf)
17253 v4sf __builtin_ia32_divss (v4sf, v4sf)
17254 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf)
17255 v4sf __builtin_ia32_cmpltps (v4sf, v4sf)
17256 v4sf __builtin_ia32_cmpleps (v4sf, v4sf)
17257 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf)
17258 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf)
17259 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf)
17260 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf)
17261 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf)
17262 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf)
17263 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf)
17264 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf)
17265 v4sf __builtin_ia32_cmpordps (v4sf, v4sf)
17266 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf)
17267 v4sf __builtin_ia32_cmpltss (v4sf, v4sf)
17268 v4sf __builtin_ia32_cmpless (v4sf, v4sf)
17269 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf)
17270 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf)
17271 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf)
17272 v4sf __builtin_ia32_cmpnless (v4sf, v4sf)
17273 v4sf __builtin_ia32_cmpordss (v4sf, v4sf)
17274 v4sf __builtin_ia32_maxps (v4sf, v4sf)
17275 v4sf __builtin_ia32_maxss (v4sf, v4sf)
17276 v4sf __builtin_ia32_minps (v4sf, v4sf)
17277 v4sf __builtin_ia32_minss (v4sf, v4sf)
17278 v4sf __builtin_ia32_andps (v4sf, v4sf)
17279 v4sf __builtin_ia32_andnps (v4sf, v4sf)
17280 v4sf __builtin_ia32_orps (v4sf, v4sf)
17281 v4sf __builtin_ia32_xorps (v4sf, v4sf)
17282 v4sf __builtin_ia32_movss (v4sf, v4sf)
17283 v4sf __builtin_ia32_movhlps (v4sf, v4sf)
17284 v4sf __builtin_ia32_movlhps (v4sf, v4sf)
17285 v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
17286 v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
17287 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
17288 v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
17289 v2si __builtin_ia32_cvtps2pi (v4sf)
17290 int __builtin_ia32_cvtss2si (v4sf)
17291 v2si __builtin_ia32_cvttps2pi (v4sf)
17292 int __builtin_ia32_cvttss2si (v4sf)
17293 v4sf __builtin_ia32_rcpps (v4sf)
17294 v4sf __builtin_ia32_rsqrtps (v4sf)
17295 v4sf __builtin_ia32_sqrtps (v4sf)
17296 v4sf __builtin_ia32_rcpss (v4sf)
17297 v4sf __builtin_ia32_rsqrtss (v4sf)
17298 v4sf __builtin_ia32_sqrtss (v4sf)
17299 v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
17300 void __builtin_ia32_movntps (float *, v4sf)
17301 int __builtin_ia32_movmskps (v4sf)
17304 The following built-in functions are available when @option{-msse} is used.
17307 @item v4sf __builtin_ia32_loadups (float *)
17308 Generates the @code{movups} machine instruction as a load from memory.
17309 @item void __builtin_ia32_storeups (float *, v4sf)
17310 Generates the @code{movups} machine instruction as a store to memory.
17311 @item v4sf __builtin_ia32_loadss (float *)
17312 Generates the @code{movss} machine instruction as a load from memory.
17313 @item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
17314 Generates the @code{movhps} machine instruction as a load from memory.
17315 @item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
17316 Generates the @code{movlps} machine instruction as a load from memory
17317 @item void __builtin_ia32_storehps (v2sf *, v4sf)
17318 Generates the @code{movhps} machine instruction as a store to memory.
17319 @item void __builtin_ia32_storelps (v2sf *, v4sf)
17320 Generates the @code{movlps} machine instruction as a store to memory.
17323 The following built-in functions are available when @option{-msse2} is used.
17324 All of them generate the machine instruction that is part of the name.
17327 int __builtin_ia32_comisdeq (v2df, v2df)
17328 int __builtin_ia32_comisdlt (v2df, v2df)
17329 int __builtin_ia32_comisdle (v2df, v2df)
17330 int __builtin_ia32_comisdgt (v2df, v2df)
17331 int __builtin_ia32_comisdge (v2df, v2df)
17332 int __builtin_ia32_comisdneq (v2df, v2df)
17333 int __builtin_ia32_ucomisdeq (v2df, v2df)
17334 int __builtin_ia32_ucomisdlt (v2df, v2df)
17335 int __builtin_ia32_ucomisdle (v2df, v2df)
17336 int __builtin_ia32_ucomisdgt (v2df, v2df)
17337 int __builtin_ia32_ucomisdge (v2df, v2df)
17338 int __builtin_ia32_ucomisdneq (v2df, v2df)
17339 v2df __builtin_ia32_cmpeqpd (v2df, v2df)
17340 v2df __builtin_ia32_cmpltpd (v2df, v2df)
17341 v2df __builtin_ia32_cmplepd (v2df, v2df)
17342 v2df __builtin_ia32_cmpgtpd (v2df, v2df)
17343 v2df __builtin_ia32_cmpgepd (v2df, v2df)
17344 v2df __builtin_ia32_cmpunordpd (v2df, v2df)
17345 v2df __builtin_ia32_cmpneqpd (v2df, v2df)
17346 v2df __builtin_ia32_cmpnltpd (v2df, v2df)
17347 v2df __builtin_ia32_cmpnlepd (v2df, v2df)
17348 v2df __builtin_ia32_cmpngtpd (v2df, v2df)
17349 v2df __builtin_ia32_cmpngepd (v2df, v2df)
17350 v2df __builtin_ia32_cmpordpd (v2df, v2df)
17351 v2df __builtin_ia32_cmpeqsd (v2df, v2df)
17352 v2df __builtin_ia32_cmpltsd (v2df, v2df)
17353 v2df __builtin_ia32_cmplesd (v2df, v2df)
17354 v2df __builtin_ia32_cmpunordsd (v2df, v2df)
17355 v2df __builtin_ia32_cmpneqsd (v2df, v2df)
17356 v2df __builtin_ia32_cmpnltsd (v2df, v2df)
17357 v2df __builtin_ia32_cmpnlesd (v2df, v2df)
17358 v2df __builtin_ia32_cmpordsd (v2df, v2df)
17359 v2di __builtin_ia32_paddq (v2di, v2di)
17360 v2di __builtin_ia32_psubq (v2di, v2di)
17361 v2df __builtin_ia32_addpd (v2df, v2df)
17362 v2df __builtin_ia32_subpd (v2df, v2df)
17363 v2df __builtin_ia32_mulpd (v2df, v2df)
17364 v2df __builtin_ia32_divpd (v2df, v2df)
17365 v2df __builtin_ia32_addsd (v2df, v2df)
17366 v2df __builtin_ia32_subsd (v2df, v2df)
17367 v2df __builtin_ia32_mulsd (v2df, v2df)
17368 v2df __builtin_ia32_divsd (v2df, v2df)
17369 v2df __builtin_ia32_minpd (v2df, v2df)
17370 v2df __builtin_ia32_maxpd (v2df, v2df)
17371 v2df __builtin_ia32_minsd (v2df, v2df)
17372 v2df __builtin_ia32_maxsd (v2df, v2df)
17373 v2df __builtin_ia32_andpd (v2df, v2df)
17374 v2df __builtin_ia32_andnpd (v2df, v2df)
17375 v2df __builtin_ia32_orpd (v2df, v2df)
17376 v2df __builtin_ia32_xorpd (v2df, v2df)
17377 v2df __builtin_ia32_movsd (v2df, v2df)
17378 v2df __builtin_ia32_unpckhpd (v2df, v2df)
17379 v2df __builtin_ia32_unpcklpd (v2df, v2df)
17380 v16qi __builtin_ia32_paddb128 (v16qi, v16qi)
17381 v8hi __builtin_ia32_paddw128 (v8hi, v8hi)
17382 v4si __builtin_ia32_paddd128 (v4si, v4si)
17383 v2di __builtin_ia32_paddq128 (v2di, v2di)
17384 v16qi __builtin_ia32_psubb128 (v16qi, v16qi)
17385 v8hi __builtin_ia32_psubw128 (v8hi, v8hi)
17386 v4si __builtin_ia32_psubd128 (v4si, v4si)
17387 v2di __builtin_ia32_psubq128 (v2di, v2di)
17388 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi)
17389 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi)
17390 v2di __builtin_ia32_pand128 (v2di, v2di)
17391 v2di __builtin_ia32_pandn128 (v2di, v2di)
17392 v2di __builtin_ia32_por128 (v2di, v2di)
17393 v2di __builtin_ia32_pxor128 (v2di, v2di)
17394 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi)
17395 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi)
17396 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi)
17397 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi)
17398 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si)
17399 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi)
17400 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi)
17401 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si)
17402 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi)
17403 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi)
17404 v16qi __builtin_ia32_pminub128 (v16qi, v16qi)
17405 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi)
17406 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi)
17407 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi)
17408 v4si __builtin_ia32_punpckhdq128 (v4si, v4si)
17409 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di)
17410 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi)
17411 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi)
17412 v4si __builtin_ia32_punpckldq128 (v4si, v4si)
17413 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di)
17414 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi)
17415 v8hi __builtin_ia32_packssdw128 (v4si, v4si)
17416 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi)
17417 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi)
17418 void __builtin_ia32_maskmovdqu (v16qi, v16qi)
17419 v2df __builtin_ia32_loadupd (double *)
17420 void __builtin_ia32_storeupd (double *, v2df)
17421 v2df __builtin_ia32_loadhpd (v2df, double const *)
17422 v2df __builtin_ia32_loadlpd (v2df, double const *)
17423 int __builtin_ia32_movmskpd (v2df)
17424 int __builtin_ia32_pmovmskb128 (v16qi)
17425 void __builtin_ia32_movnti (int *, int)
17426 void __builtin_ia32_movnti64 (long long int *, long long int)
17427 void __builtin_ia32_movntpd (double *, v2df)
17428 void __builtin_ia32_movntdq (v2df *, v2df)
17429 v4si __builtin_ia32_pshufd (v4si, int)
17430 v8hi __builtin_ia32_pshuflw (v8hi, int)
17431 v8hi __builtin_ia32_pshufhw (v8hi, int)
17432 v2di __builtin_ia32_psadbw128 (v16qi, v16qi)
17433 v2df __builtin_ia32_sqrtpd (v2df)
17434 v2df __builtin_ia32_sqrtsd (v2df)
17435 v2df __builtin_ia32_shufpd (v2df, v2df, int)
17436 v2df __builtin_ia32_cvtdq2pd (v4si)
17437 v4sf __builtin_ia32_cvtdq2ps (v4si)
17438 v4si __builtin_ia32_cvtpd2dq (v2df)
17439 v2si __builtin_ia32_cvtpd2pi (v2df)
17440 v4sf __builtin_ia32_cvtpd2ps (v2df)
17441 v4si __builtin_ia32_cvttpd2dq (v2df)
17442 v2si __builtin_ia32_cvttpd2pi (v2df)
17443 v2df __builtin_ia32_cvtpi2pd (v2si)
17444 int __builtin_ia32_cvtsd2si (v2df)
17445 int __builtin_ia32_cvttsd2si (v2df)
17446 long long __builtin_ia32_cvtsd2si64 (v2df)
17447 long long __builtin_ia32_cvttsd2si64 (v2df)
17448 v4si __builtin_ia32_cvtps2dq (v4sf)
17449 v2df __builtin_ia32_cvtps2pd (v4sf)
17450 v4si __builtin_ia32_cvttps2dq (v4sf)
17451 v2df __builtin_ia32_cvtsi2sd (v2df, int)
17452 v2df __builtin_ia32_cvtsi642sd (v2df, long long)
17453 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df)
17454 v2df __builtin_ia32_cvtss2sd (v2df, v4sf)
17455 void __builtin_ia32_clflush (const void *)
17456 void __builtin_ia32_lfence (void)
17457 void __builtin_ia32_mfence (void)
17458 v16qi __builtin_ia32_loaddqu (const char *)
17459 void __builtin_ia32_storedqu (char *, v16qi)
17460 v1di __builtin_ia32_pmuludq (v2si, v2si)
17461 v2di __builtin_ia32_pmuludq128 (v4si, v4si)
17462 v8hi __builtin_ia32_psllw128 (v8hi, v8hi)
17463 v4si __builtin_ia32_pslld128 (v4si, v4si)
17464 v2di __builtin_ia32_psllq128 (v2di, v2di)
17465 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi)
17466 v4si __builtin_ia32_psrld128 (v4si, v4si)
17467 v2di __builtin_ia32_psrlq128 (v2di, v2di)
17468 v8hi __builtin_ia32_psraw128 (v8hi, v8hi)
17469 v4si __builtin_ia32_psrad128 (v4si, v4si)
17470 v2di __builtin_ia32_pslldqi128 (v2di, int)
17471 v8hi __builtin_ia32_psllwi128 (v8hi, int)
17472 v4si __builtin_ia32_pslldi128 (v4si, int)
17473 v2di __builtin_ia32_psllqi128 (v2di, int)
17474 v2di __builtin_ia32_psrldqi128 (v2di, int)
17475 v8hi __builtin_ia32_psrlwi128 (v8hi, int)
17476 v4si __builtin_ia32_psrldi128 (v4si, int)
17477 v2di __builtin_ia32_psrlqi128 (v2di, int)
17478 v8hi __builtin_ia32_psrawi128 (v8hi, int)
17479 v4si __builtin_ia32_psradi128 (v4si, int)
17480 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi)
17481 v2di __builtin_ia32_movq128 (v2di)
17484 The following built-in functions are available when @option{-msse3} is used.
17485 All of them generate the machine instruction that is part of the name.
17488 v2df __builtin_ia32_addsubpd (v2df, v2df)
17489 v4sf __builtin_ia32_addsubps (v4sf, v4sf)
17490 v2df __builtin_ia32_haddpd (v2df, v2df)
17491 v4sf __builtin_ia32_haddps (v4sf, v4sf)
17492 v2df __builtin_ia32_hsubpd (v2df, v2df)
17493 v4sf __builtin_ia32_hsubps (v4sf, v4sf)
17494 v16qi __builtin_ia32_lddqu (char const *)
17495 void __builtin_ia32_monitor (void *, unsigned int, unsigned int)
17496 v4sf __builtin_ia32_movshdup (v4sf)
17497 v4sf __builtin_ia32_movsldup (v4sf)
17498 void __builtin_ia32_mwait (unsigned int, unsigned int)
17501 The following built-in functions are available when @option{-mssse3} is used.
17502 All of them generate the machine instruction that is part of the name.
17505 v2si __builtin_ia32_phaddd (v2si, v2si)
17506 v4hi __builtin_ia32_phaddw (v4hi, v4hi)
17507 v4hi __builtin_ia32_phaddsw (v4hi, v4hi)
17508 v2si __builtin_ia32_phsubd (v2si, v2si)
17509 v4hi __builtin_ia32_phsubw (v4hi, v4hi)
17510 v4hi __builtin_ia32_phsubsw (v4hi, v4hi)
17511 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi)
17512 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi)
17513 v8qi __builtin_ia32_pshufb (v8qi, v8qi)
17514 v8qi __builtin_ia32_psignb (v8qi, v8qi)
17515 v2si __builtin_ia32_psignd (v2si, v2si)
17516 v4hi __builtin_ia32_psignw (v4hi, v4hi)
17517 v1di __builtin_ia32_palignr (v1di, v1di, int)
17518 v8qi __builtin_ia32_pabsb (v8qi)
17519 v2si __builtin_ia32_pabsd (v2si)
17520 v4hi __builtin_ia32_pabsw (v4hi)
17523 The following built-in functions are available when @option{-mssse3} is used.
17524 All of them generate the machine instruction that is part of the name.
17527 v4si __builtin_ia32_phaddd128 (v4si, v4si)
17528 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi)
17529 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi)
17530 v4si __builtin_ia32_phsubd128 (v4si, v4si)
17531 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi)
17532 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi)
17533 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi)
17534 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi)
17535 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi)
17536 v16qi __builtin_ia32_psignb128 (v16qi, v16qi)
17537 v4si __builtin_ia32_psignd128 (v4si, v4si)
17538 v8hi __builtin_ia32_psignw128 (v8hi, v8hi)
17539 v2di __builtin_ia32_palignr128 (v2di, v2di, int)
17540 v16qi __builtin_ia32_pabsb128 (v16qi)
17541 v4si __builtin_ia32_pabsd128 (v4si)
17542 v8hi __builtin_ia32_pabsw128 (v8hi)
17545 The following built-in functions are available when @option{-msse4.1} is
17546 used. All of them generate the machine instruction that is part of the
17550 v2df __builtin_ia32_blendpd (v2df, v2df, const int)
17551 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int)
17552 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df)
17553 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf)
17554 v2df __builtin_ia32_dppd (v2df, v2df, const int)
17555 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int)
17556 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int)
17557 v2di __builtin_ia32_movntdqa (v2di *);
17558 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int)
17559 v8hi __builtin_ia32_packusdw128 (v4si, v4si)
17560 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi)
17561 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int)
17562 v2di __builtin_ia32_pcmpeqq (v2di, v2di)
17563 v8hi __builtin_ia32_phminposuw128 (v8hi)
17564 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi)
17565 v4si __builtin_ia32_pmaxsd128 (v4si, v4si)
17566 v4si __builtin_ia32_pmaxud128 (v4si, v4si)
17567 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi)
17568 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi)
17569 v4si __builtin_ia32_pminsd128 (v4si, v4si)
17570 v4si __builtin_ia32_pminud128 (v4si, v4si)
17571 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi)
17572 v4si __builtin_ia32_pmovsxbd128 (v16qi)
17573 v2di __builtin_ia32_pmovsxbq128 (v16qi)
17574 v8hi __builtin_ia32_pmovsxbw128 (v16qi)
17575 v2di __builtin_ia32_pmovsxdq128 (v4si)
17576 v4si __builtin_ia32_pmovsxwd128 (v8hi)
17577 v2di __builtin_ia32_pmovsxwq128 (v8hi)
17578 v4si __builtin_ia32_pmovzxbd128 (v16qi)
17579 v2di __builtin_ia32_pmovzxbq128 (v16qi)
17580 v8hi __builtin_ia32_pmovzxbw128 (v16qi)
17581 v2di __builtin_ia32_pmovzxdq128 (v4si)
17582 v4si __builtin_ia32_pmovzxwd128 (v8hi)
17583 v2di __builtin_ia32_pmovzxwq128 (v8hi)
17584 v2di __builtin_ia32_pmuldq128 (v4si, v4si)
17585 v4si __builtin_ia32_pmulld128 (v4si, v4si)
17586 int __builtin_ia32_ptestc128 (v2di, v2di)
17587 int __builtin_ia32_ptestnzc128 (v2di, v2di)
17588 int __builtin_ia32_ptestz128 (v2di, v2di)
17589 v2df __builtin_ia32_roundpd (v2df, const int)
17590 v4sf __builtin_ia32_roundps (v4sf, const int)
17591 v2df __builtin_ia32_roundsd (v2df, v2df, const int)
17592 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int)
17595 The following built-in functions are available when @option{-msse4.1} is
17599 @item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
17600 Generates the @code{insertps} machine instruction.
17601 @item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
17602 Generates the @code{pextrb} machine instruction.
17603 @item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
17604 Generates the @code{pinsrb} machine instruction.
17605 @item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
17606 Generates the @code{pinsrd} machine instruction.
17607 @item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
17608 Generates the @code{pinsrq} machine instruction in 64bit mode.
17611 The following built-in functions are changed to generate new SSE4.1
17612 instructions when @option{-msse4.1} is used.
17615 @item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
17616 Generates the @code{extractps} machine instruction.
17617 @item int __builtin_ia32_vec_ext_v4si (v4si, const int)
17618 Generates the @code{pextrd} machine instruction.
17619 @item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
17620 Generates the @code{pextrq} machine instruction in 64bit mode.
17623 The following built-in functions are available when @option{-msse4.2} is
17624 used. All of them generate the machine instruction that is part of the
17628 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int)
17629 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int)
17630 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int)
17631 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int)
17632 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int)
17633 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int)
17634 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int)
17635 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int)
17636 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int)
17637 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int)
17638 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int)
17639 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int)
17640 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int)
17641 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int)
17642 v2di __builtin_ia32_pcmpgtq (v2di, v2di)
17645 The following built-in functions are available when @option{-msse4.2} is
17649 @item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
17650 Generates the @code{crc32b} machine instruction.
17651 @item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
17652 Generates the @code{crc32w} machine instruction.
17653 @item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
17654 Generates the @code{crc32l} machine instruction.
17655 @item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
17656 Generates the @code{crc32q} machine instruction.
17659 The following built-in functions are changed to generate new SSE4.2
17660 instructions when @option{-msse4.2} is used.
17663 @item int __builtin_popcount (unsigned int)
17664 Generates the @code{popcntl} machine instruction.
17665 @item int __builtin_popcountl (unsigned long)
17666 Generates the @code{popcntl} or @code{popcntq} machine instruction,
17667 depending on the size of @code{unsigned long}.
17668 @item int __builtin_popcountll (unsigned long long)
17669 Generates the @code{popcntq} machine instruction.
17672 The following built-in functions are available when @option{-mavx} is
17673 used. All of them generate the machine instruction that is part of the
17677 v4df __builtin_ia32_addpd256 (v4df,v4df)
17678 v8sf __builtin_ia32_addps256 (v8sf,v8sf)
17679 v4df __builtin_ia32_addsubpd256 (v4df,v4df)
17680 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf)
17681 v4df __builtin_ia32_andnpd256 (v4df,v4df)
17682 v8sf __builtin_ia32_andnps256 (v8sf,v8sf)
17683 v4df __builtin_ia32_andpd256 (v4df,v4df)
17684 v8sf __builtin_ia32_andps256 (v8sf,v8sf)
17685 v4df __builtin_ia32_blendpd256 (v4df,v4df,int)
17686 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int)
17687 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df)
17688 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf)
17689 v2df __builtin_ia32_cmppd (v2df,v2df,int)
17690 v4df __builtin_ia32_cmppd256 (v4df,v4df,int)
17691 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int)
17692 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int)
17693 v2df __builtin_ia32_cmpsd (v2df,v2df,int)
17694 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int)
17695 v4df __builtin_ia32_cvtdq2pd256 (v4si)
17696 v8sf __builtin_ia32_cvtdq2ps256 (v8si)
17697 v4si __builtin_ia32_cvtpd2dq256 (v4df)
17698 v4sf __builtin_ia32_cvtpd2ps256 (v4df)
17699 v8si __builtin_ia32_cvtps2dq256 (v8sf)
17700 v4df __builtin_ia32_cvtps2pd256 (v4sf)
17701 v4si __builtin_ia32_cvttpd2dq256 (v4df)
17702 v8si __builtin_ia32_cvttps2dq256 (v8sf)
17703 v4df __builtin_ia32_divpd256 (v4df,v4df)
17704 v8sf __builtin_ia32_divps256 (v8sf,v8sf)
17705 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int)
17706 v4df __builtin_ia32_haddpd256 (v4df,v4df)
17707 v8sf __builtin_ia32_haddps256 (v8sf,v8sf)
17708 v4df __builtin_ia32_hsubpd256 (v4df,v4df)
17709 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf)
17710 v32qi __builtin_ia32_lddqu256 (pcchar)
17711 v32qi __builtin_ia32_loaddqu256 (pcchar)
17712 v4df __builtin_ia32_loadupd256 (pcdouble)
17713 v8sf __builtin_ia32_loadups256 (pcfloat)
17714 v2df __builtin_ia32_maskloadpd (pcv2df,v2df)
17715 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df)
17716 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf)
17717 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf)
17718 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df)
17719 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df)
17720 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf)
17721 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf)
17722 v4df __builtin_ia32_maxpd256 (v4df,v4df)
17723 v8sf __builtin_ia32_maxps256 (v8sf,v8sf)
17724 v4df __builtin_ia32_minpd256 (v4df,v4df)
17725 v8sf __builtin_ia32_minps256 (v8sf,v8sf)
17726 v4df __builtin_ia32_movddup256 (v4df)
17727 int __builtin_ia32_movmskpd256 (v4df)
17728 int __builtin_ia32_movmskps256 (v8sf)
17729 v8sf __builtin_ia32_movshdup256 (v8sf)
17730 v8sf __builtin_ia32_movsldup256 (v8sf)
17731 v4df __builtin_ia32_mulpd256 (v4df,v4df)
17732 v8sf __builtin_ia32_mulps256 (v8sf,v8sf)
17733 v4df __builtin_ia32_orpd256 (v4df,v4df)
17734 v8sf __builtin_ia32_orps256 (v8sf,v8sf)
17735 v2df __builtin_ia32_pd_pd256 (v4df)
17736 v4df __builtin_ia32_pd256_pd (v2df)
17737 v4sf __builtin_ia32_ps_ps256 (v8sf)
17738 v8sf __builtin_ia32_ps256_ps (v4sf)
17739 int __builtin_ia32_ptestc256 (v4di,v4di,ptest)
17740 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest)
17741 int __builtin_ia32_ptestz256 (v4di,v4di,ptest)
17742 v8sf __builtin_ia32_rcpps256 (v8sf)
17743 v4df __builtin_ia32_roundpd256 (v4df,int)
17744 v8sf __builtin_ia32_roundps256 (v8sf,int)
17745 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf)
17746 v8sf __builtin_ia32_rsqrtps256 (v8sf)
17747 v4df __builtin_ia32_shufpd256 (v4df,v4df,int)
17748 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int)
17749 v4si __builtin_ia32_si_si256 (v8si)
17750 v8si __builtin_ia32_si256_si (v4si)
17751 v4df __builtin_ia32_sqrtpd256 (v4df)
17752 v8sf __builtin_ia32_sqrtps_nr256 (v8sf)
17753 v8sf __builtin_ia32_sqrtps256 (v8sf)
17754 void __builtin_ia32_storedqu256 (pchar,v32qi)
17755 void __builtin_ia32_storeupd256 (pdouble,v4df)
17756 void __builtin_ia32_storeups256 (pfloat,v8sf)
17757 v4df __builtin_ia32_subpd256 (v4df,v4df)
17758 v8sf __builtin_ia32_subps256 (v8sf,v8sf)
17759 v4df __builtin_ia32_unpckhpd256 (v4df,v4df)
17760 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf)
17761 v4df __builtin_ia32_unpcklpd256 (v4df,v4df)
17762 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf)
17763 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df)
17764 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf)
17765 v4df __builtin_ia32_vbroadcastsd256 (pcdouble)
17766 v4sf __builtin_ia32_vbroadcastss (pcfloat)
17767 v8sf __builtin_ia32_vbroadcastss256 (pcfloat)
17768 v2df __builtin_ia32_vextractf128_pd256 (v4df,int)
17769 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int)
17770 v4si __builtin_ia32_vextractf128_si256 (v8si,int)
17771 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int)
17772 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int)
17773 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int)
17774 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int)
17775 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int)
17776 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int)
17777 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int)
17778 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int)
17779 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int)
17780 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int)
17781 v2df __builtin_ia32_vpermilpd (v2df,int)
17782 v4df __builtin_ia32_vpermilpd256 (v4df,int)
17783 v4sf __builtin_ia32_vpermilps (v4sf,int)
17784 v8sf __builtin_ia32_vpermilps256 (v8sf,int)
17785 v2df __builtin_ia32_vpermilvarpd (v2df,v2di)
17786 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di)
17787 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si)
17788 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si)
17789 int __builtin_ia32_vtestcpd (v2df,v2df,ptest)
17790 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest)
17791 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest)
17792 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest)
17793 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest)
17794 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest)
17795 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest)
17796 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest)
17797 int __builtin_ia32_vtestzpd (v2df,v2df,ptest)
17798 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest)
17799 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest)
17800 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest)
17801 void __builtin_ia32_vzeroall (void)
17802 void __builtin_ia32_vzeroupper (void)
17803 v4df __builtin_ia32_xorpd256 (v4df,v4df)
17804 v8sf __builtin_ia32_xorps256 (v8sf,v8sf)
17807 The following built-in functions are available when @option{-mavx2} is
17808 used. All of them generate the machine instruction that is part of the
17812 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int)
17813 v32qi __builtin_ia32_pabsb256 (v32qi)
17814 v16hi __builtin_ia32_pabsw256 (v16hi)
17815 v8si __builtin_ia32_pabsd256 (v8si)
17816 v16hi __builtin_ia32_packssdw256 (v8si,v8si)
17817 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi)
17818 v16hi __builtin_ia32_packusdw256 (v8si,v8si)
17819 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi)
17820 v32qi __builtin_ia32_paddb256 (v32qi,v32qi)
17821 v16hi __builtin_ia32_paddw256 (v16hi,v16hi)
17822 v8si __builtin_ia32_paddd256 (v8si,v8si)
17823 v4di __builtin_ia32_paddq256 (v4di,v4di)
17824 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi)
17825 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi)
17826 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi)
17827 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi)
17828 v4di __builtin_ia32_palignr256 (v4di,v4di,int)
17829 v4di __builtin_ia32_andsi256 (v4di,v4di)
17830 v4di __builtin_ia32_andnotsi256 (v4di,v4di)
17831 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi)
17832 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi)
17833 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi)
17834 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int)
17835 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi)
17836 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi)
17837 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si)
17838 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di)
17839 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi)
17840 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi)
17841 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si)
17842 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di)
17843 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi)
17844 v8si __builtin_ia32_phaddd256 (v8si,v8si)
17845 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi)
17846 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi)
17847 v8si __builtin_ia32_phsubd256 (v8si,v8si)
17848 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi)
17849 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi)
17850 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi)
17851 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi)
17852 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi)
17853 v8si __builtin_ia32_pmaxsd256 (v8si,v8si)
17854 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi)
17855 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi)
17856 v8si __builtin_ia32_pmaxud256 (v8si,v8si)
17857 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi)
17858 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi)
17859 v8si __builtin_ia32_pminsd256 (v8si,v8si)
17860 v32qi __builtin_ia32_pminub256 (v32qi,v32qi)
17861 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi)
17862 v8si __builtin_ia32_pminud256 (v8si,v8si)
17863 int __builtin_ia32_pmovmskb256 (v32qi)
17864 v16hi __builtin_ia32_pmovsxbw256 (v16qi)
17865 v8si __builtin_ia32_pmovsxbd256 (v16qi)
17866 v4di __builtin_ia32_pmovsxbq256 (v16qi)
17867 v8si __builtin_ia32_pmovsxwd256 (v8hi)
17868 v4di __builtin_ia32_pmovsxwq256 (v8hi)
17869 v4di __builtin_ia32_pmovsxdq256 (v4si)
17870 v16hi __builtin_ia32_pmovzxbw256 (v16qi)
17871 v8si __builtin_ia32_pmovzxbd256 (v16qi)
17872 v4di __builtin_ia32_pmovzxbq256 (v16qi)
17873 v8si __builtin_ia32_pmovzxwd256 (v8hi)
17874 v4di __builtin_ia32_pmovzxwq256 (v8hi)
17875 v4di __builtin_ia32_pmovzxdq256 (v4si)
17876 v4di __builtin_ia32_pmuldq256 (v8si,v8si)
17877 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi)
17878 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi)
17879 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi)
17880 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi)
17881 v8si __builtin_ia32_pmulld256 (v8si,v8si)
17882 v4di __builtin_ia32_pmuludq256 (v8si,v8si)
17883 v4di __builtin_ia32_por256 (v4di,v4di)
17884 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi)
17885 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi)
17886 v8si __builtin_ia32_pshufd256 (v8si,int)
17887 v16hi __builtin_ia32_pshufhw256 (v16hi,int)
17888 v16hi __builtin_ia32_pshuflw256 (v16hi,int)
17889 v32qi __builtin_ia32_psignb256 (v32qi,v32qi)
17890 v16hi __builtin_ia32_psignw256 (v16hi,v16hi)
17891 v8si __builtin_ia32_psignd256 (v8si,v8si)
17892 v4di __builtin_ia32_pslldqi256 (v4di,int)
17893 v16hi __builtin_ia32_psllwi256 (16hi,int)
17894 v16hi __builtin_ia32_psllw256(v16hi,v8hi)
17895 v8si __builtin_ia32_pslldi256 (v8si,int)
17896 v8si __builtin_ia32_pslld256(v8si,v4si)
17897 v4di __builtin_ia32_psllqi256 (v4di,int)
17898 v4di __builtin_ia32_psllq256(v4di,v2di)
17899 v16hi __builtin_ia32_psrawi256 (v16hi,int)
17900 v16hi __builtin_ia32_psraw256 (v16hi,v8hi)
17901 v8si __builtin_ia32_psradi256 (v8si,int)
17902 v8si __builtin_ia32_psrad256 (v8si,v4si)
17903 v4di __builtin_ia32_psrldqi256 (v4di, int)
17904 v16hi __builtin_ia32_psrlwi256 (v16hi,int)
17905 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi)
17906 v8si __builtin_ia32_psrldi256 (v8si,int)
17907 v8si __builtin_ia32_psrld256 (v8si,v4si)
17908 v4di __builtin_ia32_psrlqi256 (v4di,int)
17909 v4di __builtin_ia32_psrlq256(v4di,v2di)
17910 v32qi __builtin_ia32_psubb256 (v32qi,v32qi)
17911 v32hi __builtin_ia32_psubw256 (v16hi,v16hi)
17912 v8si __builtin_ia32_psubd256 (v8si,v8si)
17913 v4di __builtin_ia32_psubq256 (v4di,v4di)
17914 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi)
17915 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi)
17916 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi)
17917 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi)
17918 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi)
17919 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi)
17920 v8si __builtin_ia32_punpckhdq256 (v8si,v8si)
17921 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di)
17922 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi)
17923 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi)
17924 v8si __builtin_ia32_punpckldq256 (v8si,v8si)
17925 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di)
17926 v4di __builtin_ia32_pxor256 (v4di,v4di)
17927 v4di __builtin_ia32_movntdqa256 (pv4di)
17928 v4sf __builtin_ia32_vbroadcastss_ps (v4sf)
17929 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf)
17930 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df)
17931 v4di __builtin_ia32_vbroadcastsi256 (v2di)
17932 v4si __builtin_ia32_pblendd128 (v4si,v4si)
17933 v8si __builtin_ia32_pblendd256 (v8si,v8si)
17934 v32qi __builtin_ia32_pbroadcastb256 (v16qi)
17935 v16hi __builtin_ia32_pbroadcastw256 (v8hi)
17936 v8si __builtin_ia32_pbroadcastd256 (v4si)
17937 v4di __builtin_ia32_pbroadcastq256 (v2di)
17938 v16qi __builtin_ia32_pbroadcastb128 (v16qi)
17939 v8hi __builtin_ia32_pbroadcastw128 (v8hi)
17940 v4si __builtin_ia32_pbroadcastd128 (v4si)
17941 v2di __builtin_ia32_pbroadcastq128 (v2di)
17942 v8si __builtin_ia32_permvarsi256 (v8si,v8si)
17943 v4df __builtin_ia32_permdf256 (v4df,int)
17944 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf)
17945 v4di __builtin_ia32_permdi256 (v4di,int)
17946 v4di __builtin_ia32_permti256 (v4di,v4di,int)
17947 v4di __builtin_ia32_extract128i256 (v4di,int)
17948 v4di __builtin_ia32_insert128i256 (v4di,v2di,int)
17949 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si)
17950 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di)
17951 v4si __builtin_ia32_maskloadd (pcv4si,v4si)
17952 v2di __builtin_ia32_maskloadq (pcv2di,v2di)
17953 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si)
17954 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di)
17955 void __builtin_ia32_maskstored (pv4si,v4si,v4si)
17956 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di)
17957 v8si __builtin_ia32_psllv8si (v8si,v8si)
17958 v4si __builtin_ia32_psllv4si (v4si,v4si)
17959 v4di __builtin_ia32_psllv4di (v4di,v4di)
17960 v2di __builtin_ia32_psllv2di (v2di,v2di)
17961 v8si __builtin_ia32_psrav8si (v8si,v8si)
17962 v4si __builtin_ia32_psrav4si (v4si,v4si)
17963 v8si __builtin_ia32_psrlv8si (v8si,v8si)
17964 v4si __builtin_ia32_psrlv4si (v4si,v4si)
17965 v4di __builtin_ia32_psrlv4di (v4di,v4di)
17966 v2di __builtin_ia32_psrlv2di (v2di,v2di)
17967 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int)
17968 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int)
17969 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int)
17970 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int)
17971 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int)
17972 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int)
17973 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int)
17974 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int)
17975 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int)
17976 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int)
17977 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int)
17978 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int)
17979 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int)
17980 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int)
17981 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int)
17982 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int)
17985 The following built-in functions are available when @option{-maes} is
17986 used. All of them generate the machine instruction that is part of the
17990 v2di __builtin_ia32_aesenc128 (v2di, v2di)
17991 v2di __builtin_ia32_aesenclast128 (v2di, v2di)
17992 v2di __builtin_ia32_aesdec128 (v2di, v2di)
17993 v2di __builtin_ia32_aesdeclast128 (v2di, v2di)
17994 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int)
17995 v2di __builtin_ia32_aesimc128 (v2di)
17998 The following built-in function is available when @option{-mpclmul} is
18002 @item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
18003 Generates the @code{pclmulqdq} machine instruction.
18006 The following built-in function is available when @option{-mfsgsbase} is
18007 used. All of them generate the machine instruction that is part of the
18011 unsigned int __builtin_ia32_rdfsbase32 (void)
18012 unsigned long long __builtin_ia32_rdfsbase64 (void)
18013 unsigned int __builtin_ia32_rdgsbase32 (void)
18014 unsigned long long __builtin_ia32_rdgsbase64 (void)
18015 void _writefsbase_u32 (unsigned int)
18016 void _writefsbase_u64 (unsigned long long)
18017 void _writegsbase_u32 (unsigned int)
18018 void _writegsbase_u64 (unsigned long long)
18021 The following built-in function is available when @option{-mrdrnd} is
18022 used. All of them generate the machine instruction that is part of the
18026 unsigned int __builtin_ia32_rdrand16_step (unsigned short *)
18027 unsigned int __builtin_ia32_rdrand32_step (unsigned int *)
18028 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *)
18031 The following built-in functions are available when @option{-msse4a} is used.
18032 All of them generate the machine instruction that is part of the name.
18035 void __builtin_ia32_movntsd (double *, v2df)
18036 void __builtin_ia32_movntss (float *, v4sf)
18037 v2di __builtin_ia32_extrq (v2di, v16qi)
18038 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int)
18039 v2di __builtin_ia32_insertq (v2di, v2di)
18040 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int)
18043 The following built-in functions are available when @option{-mxop} is used.
18045 v2df __builtin_ia32_vfrczpd (v2df)
18046 v4sf __builtin_ia32_vfrczps (v4sf)
18047 v2df __builtin_ia32_vfrczsd (v2df)
18048 v4sf __builtin_ia32_vfrczss (v4sf)
18049 v4df __builtin_ia32_vfrczpd256 (v4df)
18050 v8sf __builtin_ia32_vfrczps256 (v8sf)
18051 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di)
18052 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di)
18053 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si)
18054 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi)
18055 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi)
18056 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df)
18057 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf)
18058 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di)
18059 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si)
18060 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi)
18061 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi)
18062 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df)
18063 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf)
18064 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi)
18065 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
18066 v4si __builtin_ia32_vpcomeqd (v4si, v4si)
18067 v2di __builtin_ia32_vpcomeqq (v2di, v2di)
18068 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi)
18069 v4si __builtin_ia32_vpcomequd (v4si, v4si)
18070 v2di __builtin_ia32_vpcomequq (v2di, v2di)
18071 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi)
18072 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
18073 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi)
18074 v4si __builtin_ia32_vpcomfalsed (v4si, v4si)
18075 v2di __builtin_ia32_vpcomfalseq (v2di, v2di)
18076 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi)
18077 v4si __builtin_ia32_vpcomfalseud (v4si, v4si)
18078 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di)
18079 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi)
18080 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi)
18081 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi)
18082 v4si __builtin_ia32_vpcomged (v4si, v4si)
18083 v2di __builtin_ia32_vpcomgeq (v2di, v2di)
18084 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi)
18085 v4si __builtin_ia32_vpcomgeud (v4si, v4si)
18086 v2di __builtin_ia32_vpcomgeuq (v2di, v2di)
18087 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi)
18088 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi)
18089 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi)
18090 v4si __builtin_ia32_vpcomgtd (v4si, v4si)
18091 v2di __builtin_ia32_vpcomgtq (v2di, v2di)
18092 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi)
18093 v4si __builtin_ia32_vpcomgtud (v4si, v4si)
18094 v2di __builtin_ia32_vpcomgtuq (v2di, v2di)
18095 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi)
18096 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi)
18097 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi)
18098 v4si __builtin_ia32_vpcomled (v4si, v4si)
18099 v2di __builtin_ia32_vpcomleq (v2di, v2di)
18100 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi)
18101 v4si __builtin_ia32_vpcomleud (v4si, v4si)
18102 v2di __builtin_ia32_vpcomleuq (v2di, v2di)
18103 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi)
18104 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi)
18105 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi)
18106 v4si __builtin_ia32_vpcomltd (v4si, v4si)
18107 v2di __builtin_ia32_vpcomltq (v2di, v2di)
18108 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi)
18109 v4si __builtin_ia32_vpcomltud (v4si, v4si)
18110 v2di __builtin_ia32_vpcomltuq (v2di, v2di)
18111 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi)
18112 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi)
18113 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi)
18114 v4si __builtin_ia32_vpcomned (v4si, v4si)
18115 v2di __builtin_ia32_vpcomneq (v2di, v2di)
18116 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi)
18117 v4si __builtin_ia32_vpcomneud (v4si, v4si)
18118 v2di __builtin_ia32_vpcomneuq (v2di, v2di)
18119 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi)
18120 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi)
18121 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi)
18122 v4si __builtin_ia32_vpcomtrued (v4si, v4si)
18123 v2di __builtin_ia32_vpcomtrueq (v2di, v2di)
18124 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi)
18125 v4si __builtin_ia32_vpcomtrueud (v4si, v4si)
18126 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di)
18127 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi)
18128 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi)
18129 v4si __builtin_ia32_vphaddbd (v16qi)
18130 v2di __builtin_ia32_vphaddbq (v16qi)
18131 v8hi __builtin_ia32_vphaddbw (v16qi)
18132 v2di __builtin_ia32_vphadddq (v4si)
18133 v4si __builtin_ia32_vphaddubd (v16qi)
18134 v2di __builtin_ia32_vphaddubq (v16qi)
18135 v8hi __builtin_ia32_vphaddubw (v16qi)
18136 v2di __builtin_ia32_vphaddudq (v4si)
18137 v4si __builtin_ia32_vphadduwd (v8hi)
18138 v2di __builtin_ia32_vphadduwq (v8hi)
18139 v4si __builtin_ia32_vphaddwd (v8hi)
18140 v2di __builtin_ia32_vphaddwq (v8hi)
18141 v8hi __builtin_ia32_vphsubbw (v16qi)
18142 v2di __builtin_ia32_vphsubdq (v4si)
18143 v4si __builtin_ia32_vphsubwd (v8hi)
18144 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si)
18145 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di)
18146 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di)
18147 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si)
18148 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di)
18149 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di)
18150 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si)
18151 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi)
18152 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si)
18153 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi)
18154 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si)
18155 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si)
18156 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi)
18157 v16qi __builtin_ia32_vprotb (v16qi, v16qi)
18158 v4si __builtin_ia32_vprotd (v4si, v4si)
18159 v2di __builtin_ia32_vprotq (v2di, v2di)
18160 v8hi __builtin_ia32_vprotw (v8hi, v8hi)
18161 v16qi __builtin_ia32_vpshab (v16qi, v16qi)
18162 v4si __builtin_ia32_vpshad (v4si, v4si)
18163 v2di __builtin_ia32_vpshaq (v2di, v2di)
18164 v8hi __builtin_ia32_vpshaw (v8hi, v8hi)
18165 v16qi __builtin_ia32_vpshlb (v16qi, v16qi)
18166 v4si __builtin_ia32_vpshld (v4si, v4si)
18167 v2di __builtin_ia32_vpshlq (v2di, v2di)
18168 v8hi __builtin_ia32_vpshlw (v8hi, v8hi)
18171 The following built-in functions are available when @option{-mfma4} is used.
18172 All of them generate the machine instruction that is part of the name.
18175 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df)
18176 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf)
18177 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df)
18178 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf)
18179 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df)
18180 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf)
18181 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df)
18182 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf)
18183 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df)
18184 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf)
18185 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df)
18186 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf)
18187 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df)
18188 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf)
18189 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df)
18190 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf)
18191 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df)
18192 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf)
18193 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df)
18194 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf)
18195 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df)
18196 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf)
18197 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df)
18198 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf)
18199 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df)
18200 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf)
18201 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df)
18202 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf)
18203 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df)
18204 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf)
18205 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df)
18206 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf)
18210 The following built-in functions are available when @option{-mlwp} is used.
18213 void __builtin_ia32_llwpcb16 (void *);
18214 void __builtin_ia32_llwpcb32 (void *);
18215 void __builtin_ia32_llwpcb64 (void *);
18216 void * __builtin_ia32_llwpcb16 (void);
18217 void * __builtin_ia32_llwpcb32 (void);
18218 void * __builtin_ia32_llwpcb64 (void);
18219 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short)
18220 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int)
18221 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int)
18222 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short)
18223 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int)
18224 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int)
18227 The following built-in functions are available when @option{-mbmi} is used.
18228 All of them generate the machine instruction that is part of the name.
18230 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
18231 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
18234 The following built-in functions are available when @option{-mbmi2} is used.
18235 All of them generate the machine instruction that is part of the name.
18237 unsigned int _bzhi_u32 (unsigned int, unsigned int)
18238 unsigned int _pdep_u32 (unsigned int, unsigned int)
18239 unsigned int _pext_u32 (unsigned int, unsigned int)
18240 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long)
18241 unsigned long long _pdep_u64 (unsigned long long, unsigned long long)
18242 unsigned long long _pext_u64 (unsigned long long, unsigned long long)
18245 The following built-in functions are available when @option{-mlzcnt} is used.
18246 All of them generate the machine instruction that is part of the name.
18248 unsigned short __builtin_ia32_lzcnt_16(unsigned short);
18249 unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
18250 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
18253 The following built-in functions are available when @option{-mfxsr} is used.
18254 All of them generate the machine instruction that is part of the name.
18256 void __builtin_ia32_fxsave (void *)
18257 void __builtin_ia32_fxrstor (void *)
18258 void __builtin_ia32_fxsave64 (void *)
18259 void __builtin_ia32_fxrstor64 (void *)
18262 The following built-in functions are available when @option{-mxsave} is used.
18263 All of them generate the machine instruction that is part of the name.
18265 void __builtin_ia32_xsave (void *, long long)
18266 void __builtin_ia32_xrstor (void *, long long)
18267 void __builtin_ia32_xsave64 (void *, long long)
18268 void __builtin_ia32_xrstor64 (void *, long long)
18271 The following built-in functions are available when @option{-mxsaveopt} is used.
18272 All of them generate the machine instruction that is part of the name.
18274 void __builtin_ia32_xsaveopt (void *, long long)
18275 void __builtin_ia32_xsaveopt64 (void *, long long)
18278 The following built-in functions are available when @option{-mtbm} is used.
18279 Both of them generate the immediate form of the bextr machine instruction.
18281 unsigned int __builtin_ia32_bextri_u32 (unsigned int, const unsigned int);
18282 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, const unsigned long long);
18286 The following built-in functions are available when @option{-m3dnow} is used.
18287 All of them generate the machine instruction that is part of the name.
18290 void __builtin_ia32_femms (void)
18291 v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
18292 v2si __builtin_ia32_pf2id (v2sf)
18293 v2sf __builtin_ia32_pfacc (v2sf, v2sf)
18294 v2sf __builtin_ia32_pfadd (v2sf, v2sf)
18295 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
18296 v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
18297 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
18298 v2sf __builtin_ia32_pfmax (v2sf, v2sf)
18299 v2sf __builtin_ia32_pfmin (v2sf, v2sf)
18300 v2sf __builtin_ia32_pfmul (v2sf, v2sf)
18301 v2sf __builtin_ia32_pfrcp (v2sf)
18302 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
18303 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
18304 v2sf __builtin_ia32_pfrsqrt (v2sf)
18305 v2sf __builtin_ia32_pfsub (v2sf, v2sf)
18306 v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
18307 v2sf __builtin_ia32_pi2fd (v2si)
18308 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)
18311 The following built-in functions are available when both @option{-m3dnow}
18312 and @option{-march=athlon} are used. All of them generate the machine
18313 instruction that is part of the name.
18316 v2si __builtin_ia32_pf2iw (v2sf)
18317 v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
18318 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
18319 v2sf __builtin_ia32_pi2fw (v2si)
18320 v2sf __builtin_ia32_pswapdsf (v2sf)
18321 v2si __builtin_ia32_pswapdsi (v2si)
18324 The following built-in functions are available when @option{-mrtm} is used
18325 They are used for restricted transactional memory. These are the internal
18326 low level functions. Normally the functions in
18327 @ref{x86 transactional memory intrinsics} should be used instead.
18330 int __builtin_ia32_xbegin ()
18331 void __builtin_ia32_xend ()
18332 void __builtin_ia32_xabort (status)
18333 int __builtin_ia32_xtest ()
18336 The following built-in functions are available when @option{-mmwaitx} is used.
18337 All of them generate the machine instruction that is part of the name.
18339 void __builtin_ia32_monitorx (void *, unsigned int, unsigned int)
18340 void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int)
18343 The following built-in functions are available when @option{-mclzero} is used.
18344 All of them generate the machine instruction that is part of the name.
18346 void __builtin_i32_clzero (void *)
18349 The following built-in functions are available when @option{-mpku} is used.
18350 They generate reads and writes to PKRU.
18352 void __builtin_ia32_wrpkru (unsigned int)
18353 unsigned int __builtin_ia32_rdpkru ()
18356 @node x86 transactional memory intrinsics
18357 @subsection x86 Transactional Memory Intrinsics
18359 These hardware transactional memory intrinsics for x86 allow you to use
18360 memory transactions with RTM (Restricted Transactional Memory).
18361 This support is enabled with the @option{-mrtm} option.
18362 For using HLE (Hardware Lock Elision) see
18363 @ref{x86 specific memory model extensions for transactional memory} instead.
18365 A memory transaction commits all changes to memory in an atomic way,
18366 as visible to other threads. If the transaction fails it is rolled back
18367 and all side effects discarded.
18369 Generally there is no guarantee that a memory transaction ever succeeds
18370 and suitable fallback code always needs to be supplied.
18372 @deftypefn {RTM Function} {unsigned} _xbegin ()
18373 Start a RTM (Restricted Transactional Memory) transaction.
18374 Returns @code{_XBEGIN_STARTED} when the transaction
18375 started successfully (note this is not 0, so the constant has to be
18376 explicitly tested).
18378 If the transaction aborts, all side-effects
18379 are undone and an abort code encoded as a bit mask is returned.
18380 The following macros are defined:
18383 @item _XABORT_EXPLICIT
18384 Transaction was explicitly aborted with @code{_xabort}. The parameter passed
18385 to @code{_xabort} is available with @code{_XABORT_CODE(status)}.
18386 @item _XABORT_RETRY
18387 Transaction retry is possible.
18388 @item _XABORT_CONFLICT
18389 Transaction abort due to a memory conflict with another thread.
18390 @item _XABORT_CAPACITY
18391 Transaction abort due to the transaction using too much memory.
18392 @item _XABORT_DEBUG
18393 Transaction abort due to a debug trap.
18394 @item _XABORT_NESTED
18395 Transaction abort in an inner nested transaction.
18398 There is no guarantee
18399 any transaction ever succeeds, so there always needs to be a valid
18403 @deftypefn {RTM Function} {void} _xend ()
18404 Commit the current transaction. When no transaction is active this faults.
18405 All memory side-effects of the transaction become visible
18406 to other threads in an atomic manner.
18409 @deftypefn {RTM Function} {int} _xtest ()
18410 Return a nonzero value if a transaction is currently active, otherwise 0.
18413 @deftypefn {RTM Function} {void} _xabort (status)
18414 Abort the current transaction. When no transaction is active this is a no-op.
18415 The @var{status} is an 8-bit constant; its value is encoded in the return
18416 value from @code{_xbegin}.
18419 Here is an example showing handling for @code{_XABORT_RETRY}
18420 and a fallback path for other failures:
18423 #include <immintrin.h>
18425 int n_tries, max_tries;
18426 unsigned status = _XABORT_EXPLICIT;
18429 for (n_tries = 0; n_tries < max_tries; n_tries++)
18431 status = _xbegin ();
18432 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY))
18435 if (status == _XBEGIN_STARTED)
18437 ... transaction code...
18442 ... non-transactional fallback path...
18447 Note that, in most cases, the transactional and non-transactional code
18448 must synchronize together to ensure consistency.
18450 @node Target Format Checks
18451 @section Format Checks Specific to Particular Target Machines
18453 For some target machines, GCC supports additional options to the
18455 (@pxref{Function Attributes,,Declaring Attributes of Functions}).
18458 * Solaris Format Checks::
18459 * Darwin Format Checks::
18462 @node Solaris Format Checks
18463 @subsection Solaris Format Checks
18465 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
18466 check. @code{cmn_err} accepts a subset of the standard @code{printf}
18467 conversions, and the two-argument @code{%b} conversion for displaying
18468 bit-fields. See the Solaris man page for @code{cmn_err} for more information.
18470 @node Darwin Format Checks
18471 @subsection Darwin Format Checks
18473 Darwin targets support the @code{CFString} (or @code{__CFString__}) in the format
18474 attribute context. Declarations made with such attribution are parsed for correct syntax
18475 and format argument types. However, parsing of the format string itself is currently undefined
18476 and is not carried out by this version of the compiler.
18478 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
18479 also be used as format arguments. Note that the relevant headers are only likely to be
18480 available on Darwin (OSX) installations. On such installations, the XCode and system
18481 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
18482 associated functions.
18485 @section Pragmas Accepted by GCC
18487 @cindex @code{#pragma}
18489 GCC supports several types of pragmas, primarily in order to compile
18490 code originally written for other compilers. Note that in general
18491 we do not recommend the use of pragmas; @xref{Function Attributes},
18492 for further explanation.
18495 * AArch64 Pragmas::
18499 * RS/6000 and PowerPC Pragmas::
18502 * Solaris Pragmas::
18503 * Symbol-Renaming Pragmas::
18504 * Structure-Layout Pragmas::
18506 * Diagnostic Pragmas::
18507 * Visibility Pragmas::
18508 * Push/Pop Macro Pragmas::
18509 * Function Specific Option Pragmas::
18510 * Loop-Specific Pragmas::
18513 @node AArch64 Pragmas
18514 @subsection AArch64 Pragmas
18516 The pragmas defined by the AArch64 target correspond to the AArch64
18517 target function attributes. They can be specified as below:
18519 #pragma GCC target("string")
18522 where @code{@var{string}} can be any string accepted as an AArch64 target
18523 attribute. @xref{AArch64 Function Attributes}, for more details
18524 on the permissible values of @code{string}.
18527 @subsection ARM Pragmas
18529 The ARM target defines pragmas for controlling the default addition of
18530 @code{long_call} and @code{short_call} attributes to functions.
18531 @xref{Function Attributes}, for information about the effects of these
18536 @cindex pragma, long_calls
18537 Set all subsequent functions to have the @code{long_call} attribute.
18539 @item no_long_calls
18540 @cindex pragma, no_long_calls
18541 Set all subsequent functions to have the @code{short_call} attribute.
18543 @item long_calls_off
18544 @cindex pragma, long_calls_off
18545 Do not affect the @code{long_call} or @code{short_call} attributes of
18546 subsequent functions.
18550 @subsection M32C Pragmas
18553 @item GCC memregs @var{number}
18554 @cindex pragma, memregs
18555 Overrides the command-line option @code{-memregs=} for the current
18556 file. Use with care! This pragma must be before any function in the
18557 file, and mixing different memregs values in different objects may
18558 make them incompatible. This pragma is useful when a
18559 performance-critical function uses a memreg for temporary values,
18560 as it may allow you to reduce the number of memregs used.
18562 @item ADDRESS @var{name} @var{address}
18563 @cindex pragma, address
18564 For any declared symbols matching @var{name}, this does three things
18565 to that symbol: it forces the symbol to be located at the given
18566 address (a number), it forces the symbol to be volatile, and it
18567 changes the symbol's scope to be static. This pragma exists for
18568 compatibility with other compilers, but note that the common
18569 @code{1234H} numeric syntax is not supported (use @code{0x1234}
18573 #pragma ADDRESS port3 0x103
18580 @subsection MeP Pragmas
18584 @item custom io_volatile (on|off)
18585 @cindex pragma, custom io_volatile
18586 Overrides the command-line option @code{-mio-volatile} for the current
18587 file. Note that for compatibility with future GCC releases, this
18588 option should only be used once before any @code{io} variables in each
18591 @item GCC coprocessor available @var{registers}
18592 @cindex pragma, coprocessor available
18593 Specifies which coprocessor registers are available to the register
18594 allocator. @var{registers} may be a single register, register range
18595 separated by ellipses, or comma-separated list of those. Example:
18598 #pragma GCC coprocessor available $c0...$c10, $c28
18601 @item GCC coprocessor call_saved @var{registers}
18602 @cindex pragma, coprocessor call_saved
18603 Specifies which coprocessor registers are to be saved and restored by
18604 any function using them. @var{registers} may be a single register,
18605 register range separated by ellipses, or comma-separated list of
18609 #pragma GCC coprocessor call_saved $c4...$c6, $c31
18612 @item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
18613 @cindex pragma, coprocessor subclass
18614 Creates and defines a register class. These register classes can be
18615 used by inline @code{asm} constructs. @var{registers} may be a single
18616 register, register range separated by ellipses, or comma-separated
18617 list of those. Example:
18620 #pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
18622 asm ("cpfoo %0" : "=B" (x));
18625 @item GCC disinterrupt @var{name} , @var{name} @dots{}
18626 @cindex pragma, disinterrupt
18627 For the named functions, the compiler adds code to disable interrupts
18628 for the duration of those functions. If any functions so named
18629 are not encountered in the source, a warning is emitted that the pragma is
18630 not used. Examples:
18633 #pragma disinterrupt foo
18634 #pragma disinterrupt bar, grill
18635 int foo () @{ @dots{} @}
18638 @item GCC call @var{name} , @var{name} @dots{}
18639 @cindex pragma, call
18640 For the named functions, the compiler always uses a register-indirect
18641 call model when calling the named functions. Examples:
18650 @node RS/6000 and PowerPC Pragmas
18651 @subsection RS/6000 and PowerPC Pragmas
18653 The RS/6000 and PowerPC targets define one pragma for controlling
18654 whether or not the @code{longcall} attribute is added to function
18655 declarations by default. This pragma overrides the @option{-mlongcall}
18656 option, but not the @code{longcall} and @code{shortcall} attributes.
18657 @xref{RS/6000 and PowerPC Options}, for more information about when long
18658 calls are and are not necessary.
18662 @cindex pragma, longcall
18663 Apply the @code{longcall} attribute to all subsequent function
18667 Do not apply the @code{longcall} attribute to subsequent function
18671 @c Describe h8300 pragmas here.
18672 @c Describe sh pragmas here.
18673 @c Describe v850 pragmas here.
18675 @node S/390 Pragmas
18676 @subsection S/390 Pragmas
18678 The pragmas defined by the S/390 target correspond to the S/390
18679 target function attributes and some the additional options:
18686 Note that options of the pragma, unlike options of the target
18687 attribute, do change the value of preprocessor macros like
18688 @code{__VEC__}. They can be specified as below:
18691 #pragma GCC target("string[,string]...")
18692 #pragma GCC target("string"[,"string"]...)
18695 @node Darwin Pragmas
18696 @subsection Darwin Pragmas
18698 The following pragmas are available for all architectures running the
18699 Darwin operating system. These are useful for compatibility with other
18703 @item mark @var{tokens}@dots{}
18704 @cindex pragma, mark
18705 This pragma is accepted, but has no effect.
18707 @item options align=@var{alignment}
18708 @cindex pragma, options align
18709 This pragma sets the alignment of fields in structures. The values of
18710 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
18711 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest
18712 properly; to restore the previous setting, use @code{reset} for the
18715 @item segment @var{tokens}@dots{}
18716 @cindex pragma, segment
18717 This pragma is accepted, but has no effect.
18719 @item unused (@var{var} [, @var{var}]@dots{})
18720 @cindex pragma, unused
18721 This pragma declares variables to be possibly unused. GCC does not
18722 produce warnings for the listed variables. The effect is similar to
18723 that of the @code{unused} attribute, except that this pragma may appear
18724 anywhere within the variables' scopes.
18727 @node Solaris Pragmas
18728 @subsection Solaris Pragmas
18730 The Solaris target supports @code{#pragma redefine_extname}
18731 (@pxref{Symbol-Renaming Pragmas}). It also supports additional
18732 @code{#pragma} directives for compatibility with the system compiler.
18735 @item align @var{alignment} (@var{variable} [, @var{variable}]...)
18736 @cindex pragma, align
18738 Increase the minimum alignment of each @var{variable} to @var{alignment}.
18739 This is the same as GCC's @code{aligned} attribute @pxref{Variable
18740 Attributes}). Macro expansion occurs on the arguments to this pragma
18741 when compiling C and Objective-C@. It does not currently occur when
18742 compiling C++, but this is a bug which may be fixed in a future
18745 @item fini (@var{function} [, @var{function}]...)
18746 @cindex pragma, fini
18748 This pragma causes each listed @var{function} to be called after
18749 main, or during shared module unloading, by adding a call to the
18750 @code{.fini} section.
18752 @item init (@var{function} [, @var{function}]...)
18753 @cindex pragma, init
18755 This pragma causes each listed @var{function} to be called during
18756 initialization (before @code{main}) or during shared module loading, by
18757 adding a call to the @code{.init} section.
18761 @node Symbol-Renaming Pragmas
18762 @subsection Symbol-Renaming Pragmas
18764 GCC supports a @code{#pragma} directive that changes the name used in
18765 assembly for a given declaration. While this pragma is supported on all
18766 platforms, it is intended primarily to provide compatibility with the
18767 Solaris system headers. This effect can also be achieved using the asm
18768 labels extension (@pxref{Asm Labels}).
18771 @item redefine_extname @var{oldname} @var{newname}
18772 @cindex pragma, redefine_extname
18774 This pragma gives the C function @var{oldname} the assembly symbol
18775 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
18776 is defined if this pragma is available (currently on all platforms).
18779 This pragma and the asm labels extension interact in a complicated
18780 manner. Here are some corner cases you may want to be aware of:
18783 @item This pragma silently applies only to declarations with external
18784 linkage. Asm labels do not have this restriction.
18786 @item In C++, this pragma silently applies only to declarations with
18787 ``C'' linkage. Again, asm labels do not have this restriction.
18789 @item If either of the ways of changing the assembly name of a
18790 declaration are applied to a declaration whose assembly name has
18791 already been determined (either by a previous use of one of these
18792 features, or because the compiler needed the assembly name in order to
18793 generate code), and the new name is different, a warning issues and
18794 the name does not change.
18796 @item The @var{oldname} used by @code{#pragma redefine_extname} is
18797 always the C-language name.
18800 @node Structure-Layout Pragmas
18801 @subsection Structure-Layout Pragmas
18803 For compatibility with Microsoft Windows compilers, GCC supports a
18804 set of @code{#pragma} directives that change the maximum alignment of
18805 members of structures (other than zero-width bit-fields), unions, and
18806 classes subsequently defined. The @var{n} value below always is required
18807 to be a small power of two and specifies the new alignment in bytes.
18810 @item @code{#pragma pack(@var{n})} simply sets the new alignment.
18811 @item @code{#pragma pack()} sets the alignment to the one that was in
18812 effect when compilation started (see also command-line option
18813 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
18814 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
18815 setting on an internal stack and then optionally sets the new alignment.
18816 @item @code{#pragma pack(pop)} restores the alignment setting to the one
18817 saved at the top of the internal stack (and removes that stack entry).
18818 Note that @code{#pragma pack([@var{n}])} does not influence this internal
18819 stack; thus it is possible to have @code{#pragma pack(push)} followed by
18820 multiple @code{#pragma pack(@var{n})} instances and finalized by a single
18821 @code{#pragma pack(pop)}.
18824 Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
18825 directive which lays out structures and unions subsequently defined as the
18826 documented @code{__attribute__ ((ms_struct))}.
18829 @item @code{#pragma ms_struct on} turns on the Microsoft layout.
18830 @item @code{#pragma ms_struct off} turns off the Microsoft layout.
18831 @item @code{#pragma ms_struct reset} goes back to the default layout.
18834 Most targets also support the @code{#pragma scalar_storage_order} directive
18835 which lays out structures and unions subsequently defined as the documented
18836 @code{__attribute__ ((scalar_storage_order))}.
18839 @item @code{#pragma scalar_storage_order big-endian} sets the storage order
18840 of the scalar fields to big-endian.
18841 @item @code{#pragma scalar_storage_order little-endian} sets the storage order
18842 of the scalar fields to little-endian.
18843 @item @code{#pragma scalar_storage_order default} goes back to the endianness
18844 that was in effect when compilation started (see also command-line option
18845 @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}).
18849 @subsection Weak Pragmas
18851 For compatibility with SVR4, GCC supports a set of @code{#pragma}
18852 directives for declaring symbols to be weak, and defining weak
18856 @item #pragma weak @var{symbol}
18857 @cindex pragma, weak
18858 This pragma declares @var{symbol} to be weak, as if the declaration
18859 had the attribute of the same name. The pragma may appear before
18860 or after the declaration of @var{symbol}. It is not an error for
18861 @var{symbol} to never be defined at all.
18863 @item #pragma weak @var{symbol1} = @var{symbol2}
18864 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
18865 It is an error if @var{symbol2} is not defined in the current
18869 @node Diagnostic Pragmas
18870 @subsection Diagnostic Pragmas
18872 GCC allows the user to selectively enable or disable certain types of
18873 diagnostics, and change the kind of the diagnostic. For example, a
18874 project's policy might require that all sources compile with
18875 @option{-Werror} but certain files might have exceptions allowing
18876 specific types of warnings. Or, a project might selectively enable
18877 diagnostics and treat them as errors depending on which preprocessor
18878 macros are defined.
18881 @item #pragma GCC diagnostic @var{kind} @var{option}
18882 @cindex pragma, diagnostic
18884 Modifies the disposition of a diagnostic. Note that not all
18885 diagnostics are modifiable; at the moment only warnings (normally
18886 controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
18887 Use @option{-fdiagnostics-show-option} to determine which diagnostics
18888 are controllable and which option controls them.
18890 @var{kind} is @samp{error} to treat this diagnostic as an error,
18891 @samp{warning} to treat it like a warning (even if @option{-Werror} is
18892 in effect), or @samp{ignored} if the diagnostic is to be ignored.
18893 @var{option} is a double quoted string that matches the command-line
18897 #pragma GCC diagnostic warning "-Wformat"
18898 #pragma GCC diagnostic error "-Wformat"
18899 #pragma GCC diagnostic ignored "-Wformat"
18902 Note that these pragmas override any command-line options. GCC keeps
18903 track of the location of each pragma, and issues diagnostics according
18904 to the state as of that point in the source file. Thus, pragmas occurring
18905 after a line do not affect diagnostics caused by that line.
18907 @item #pragma GCC diagnostic push
18908 @itemx #pragma GCC diagnostic pop
18910 Causes GCC to remember the state of the diagnostics as of each
18911 @code{push}, and restore to that point at each @code{pop}. If a
18912 @code{pop} has no matching @code{push}, the command-line options are
18916 #pragma GCC diagnostic error "-Wuninitialized"
18917 foo(a); /* error is given for this one */
18918 #pragma GCC diagnostic push
18919 #pragma GCC diagnostic ignored "-Wuninitialized"
18920 foo(b); /* no diagnostic for this one */
18921 #pragma GCC diagnostic pop
18922 foo(c); /* error is given for this one */
18923 #pragma GCC diagnostic pop
18924 foo(d); /* depends on command-line options */
18929 GCC also offers a simple mechanism for printing messages during
18933 @item #pragma message @var{string}
18934 @cindex pragma, diagnostic
18936 Prints @var{string} as a compiler message on compilation. The message
18937 is informational only, and is neither a compilation warning nor an error.
18940 #pragma message "Compiling " __FILE__ "..."
18943 @var{string} may be parenthesized, and is printed with location
18944 information. For example,
18947 #define DO_PRAGMA(x) _Pragma (#x)
18948 #define TODO(x) DO_PRAGMA(message ("TODO - " #x))
18950 TODO(Remember to fix this)
18954 prints @samp{/tmp/file.c:4: note: #pragma message:
18955 TODO - Remember to fix this}.
18959 @node Visibility Pragmas
18960 @subsection Visibility Pragmas
18963 @item #pragma GCC visibility push(@var{visibility})
18964 @itemx #pragma GCC visibility pop
18965 @cindex pragma, visibility
18967 This pragma allows the user to set the visibility for multiple
18968 declarations without having to give each a visibility attribute
18969 (@pxref{Function Attributes}).
18971 In C++, @samp{#pragma GCC visibility} affects only namespace-scope
18972 declarations. Class members and template specializations are not
18973 affected; if you want to override the visibility for a particular
18974 member or instantiation, you must use an attribute.
18979 @node Push/Pop Macro Pragmas
18980 @subsection Push/Pop Macro Pragmas
18982 For compatibility with Microsoft Windows compilers, GCC supports
18983 @samp{#pragma push_macro(@var{"macro_name"})}
18984 and @samp{#pragma pop_macro(@var{"macro_name"})}.
18987 @item #pragma push_macro(@var{"macro_name"})
18988 @cindex pragma, push_macro
18989 This pragma saves the value of the macro named as @var{macro_name} to
18990 the top of the stack for this macro.
18992 @item #pragma pop_macro(@var{"macro_name"})
18993 @cindex pragma, pop_macro
18994 This pragma sets the value of the macro named as @var{macro_name} to
18995 the value on top of the stack for this macro. If the stack for
18996 @var{macro_name} is empty, the value of the macro remains unchanged.
19003 #pragma push_macro("X")
19006 #pragma pop_macro("X")
19011 In this example, the definition of X as 1 is saved by @code{#pragma
19012 push_macro} and restored by @code{#pragma pop_macro}.
19014 @node Function Specific Option Pragmas
19015 @subsection Function Specific Option Pragmas
19018 @item #pragma GCC target (@var{"string"}...)
19019 @cindex pragma GCC target
19021 This pragma allows you to set target specific options for functions
19022 defined later in the source file. One or more strings can be
19023 specified. Each function that is defined after this point is as
19024 if @code{attribute((target("STRING")))} was specified for that
19025 function. The parenthesis around the options is optional.
19026 @xref{Function Attributes}, for more information about the
19027 @code{target} attribute and the attribute syntax.
19029 The @code{#pragma GCC target} pragma is presently implemented for
19030 x86, PowerPC, and Nios II targets only.
19034 @item #pragma GCC optimize (@var{"string"}...)
19035 @cindex pragma GCC optimize
19037 This pragma allows you to set global optimization options for functions
19038 defined later in the source file. One or more strings can be
19039 specified. Each function that is defined after this point is as
19040 if @code{attribute((optimize("STRING")))} was specified for that
19041 function. The parenthesis around the options is optional.
19042 @xref{Function Attributes}, for more information about the
19043 @code{optimize} attribute and the attribute syntax.
19047 @item #pragma GCC push_options
19048 @itemx #pragma GCC pop_options
19049 @cindex pragma GCC push_options
19050 @cindex pragma GCC pop_options
19052 These pragmas maintain a stack of the current target and optimization
19053 options. It is intended for include files where you temporarily want
19054 to switch to using a different @samp{#pragma GCC target} or
19055 @samp{#pragma GCC optimize} and then to pop back to the previous
19060 @item #pragma GCC reset_options
19061 @cindex pragma GCC reset_options
19063 This pragma clears the current @code{#pragma GCC target} and
19064 @code{#pragma GCC optimize} to use the default switches as specified
19065 on the command line.
19068 @node Loop-Specific Pragmas
19069 @subsection Loop-Specific Pragmas
19072 @item #pragma GCC ivdep
19073 @cindex pragma GCC ivdep
19076 With this pragma, the programmer asserts that there are no loop-carried
19077 dependencies which would prevent consecutive iterations of
19078 the following loop from executing concurrently with SIMD
19079 (single instruction multiple data) instructions.
19081 For example, the compiler can only unconditionally vectorize the following
19082 loop with the pragma:
19085 void foo (int n, int *a, int *b, int *c)
19089 for (i = 0; i < n; ++i)
19090 a[i] = b[i] + c[i];
19095 In this example, using the @code{restrict} qualifier had the same
19096 effect. In the following example, that would not be possible. Assume
19097 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
19098 that it can unconditionally vectorize the following loop:
19101 void ignore_vec_dep (int *a, int k, int c, int m)
19104 for (int i = 0; i < m; i++)
19105 a[i] = a[i + k] * c;
19110 @node Unnamed Fields
19111 @section Unnamed Structure and Union Fields
19112 @cindex @code{struct}
19113 @cindex @code{union}
19115 As permitted by ISO C11 and for compatibility with other compilers,
19116 GCC allows you to define
19117 a structure or union that contains, as fields, structures and unions
19118 without names. For example:
19132 In this example, you are able to access members of the unnamed
19133 union with code like @samp{foo.b}. Note that only unnamed structs and
19134 unions are allowed, you may not have, for example, an unnamed
19137 You must never create such structures that cause ambiguous field definitions.
19138 For example, in this structure:
19150 it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
19151 The compiler gives errors for such constructs.
19153 @opindex fms-extensions
19154 Unless @option{-fms-extensions} is used, the unnamed field must be a
19155 structure or union definition without a tag (for example, @samp{struct
19156 @{ int a; @};}). If @option{-fms-extensions} is used, the field may
19157 also be a definition with a tag such as @samp{struct foo @{ int a;
19158 @};}, a reference to a previously defined structure or union such as
19159 @samp{struct foo;}, or a reference to a @code{typedef} name for a
19160 previously defined structure or union type.
19162 @opindex fplan9-extensions
19163 The option @option{-fplan9-extensions} enables
19164 @option{-fms-extensions} as well as two other extensions. First, a
19165 pointer to a structure is automatically converted to a pointer to an
19166 anonymous field for assignments and function calls. For example:
19169 struct s1 @{ int a; @};
19170 struct s2 @{ struct s1; @};
19171 extern void f1 (struct s1 *);
19172 void f2 (struct s2 *p) @{ f1 (p); @}
19176 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
19177 converted into a pointer to the anonymous field.
19179 Second, when the type of an anonymous field is a @code{typedef} for a
19180 @code{struct} or @code{union}, code may refer to the field using the
19181 name of the @code{typedef}.
19184 typedef struct @{ int a; @} s1;
19185 struct s2 @{ s1; @};
19186 s1 f1 (struct s2 *p) @{ return p->s1; @}
19189 These usages are only permitted when they are not ambiguous.
19192 @section Thread-Local Storage
19193 @cindex Thread-Local Storage
19194 @cindex @acronym{TLS}
19195 @cindex @code{__thread}
19197 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
19198 are allocated such that there is one instance of the variable per extant
19199 thread. The runtime model GCC uses to implement this originates
19200 in the IA-64 processor-specific ABI, but has since been migrated
19201 to other processors as well. It requires significant support from
19202 the linker (@command{ld}), dynamic linker (@command{ld.so}), and
19203 system libraries (@file{libc.so} and @file{libpthread.so}), so it
19204 is not available everywhere.
19206 At the user level, the extension is visible with a new storage
19207 class keyword: @code{__thread}. For example:
19211 extern __thread struct state s;
19212 static __thread char *p;
19215 The @code{__thread} specifier may be used alone, with the @code{extern}
19216 or @code{static} specifiers, but with no other storage class specifier.
19217 When used with @code{extern} or @code{static}, @code{__thread} must appear
19218 immediately after the other storage class specifier.
19220 The @code{__thread} specifier may be applied to any global, file-scoped
19221 static, function-scoped static, or static data member of a class. It may
19222 not be applied to block-scoped automatic or non-static data member.
19224 When the address-of operator is applied to a thread-local variable, it is
19225 evaluated at run time and returns the address of the current thread's
19226 instance of that variable. An address so obtained may be used by any
19227 thread. When a thread terminates, any pointers to thread-local variables
19228 in that thread become invalid.
19230 No static initialization may refer to the address of a thread-local variable.
19232 In C++, if an initializer is present for a thread-local variable, it must
19233 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
19236 See @uref{http://www.akkadia.org/drepper/tls.pdf,
19237 ELF Handling For Thread-Local Storage} for a detailed explanation of
19238 the four thread-local storage addressing models, and how the runtime
19239 is expected to function.
19242 * C99 Thread-Local Edits::
19243 * C++98 Thread-Local Edits::
19246 @node C99 Thread-Local Edits
19247 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
19249 The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
19250 that document the exact semantics of the language extension.
19254 @cite{5.1.2 Execution environments}
19256 Add new text after paragraph 1
19259 Within either execution environment, a @dfn{thread} is a flow of
19260 control within a program. It is implementation defined whether
19261 or not there may be more than one thread associated with a program.
19262 It is implementation defined how threads beyond the first are
19263 created, the name and type of the function called at thread
19264 startup, and how threads may be terminated. However, objects
19265 with thread storage duration shall be initialized before thread
19270 @cite{6.2.4 Storage durations of objects}
19272 Add new text before paragraph 3
19275 An object whose identifier is declared with the storage-class
19276 specifier @w{@code{__thread}} has @dfn{thread storage duration}.
19277 Its lifetime is the entire execution of the thread, and its
19278 stored value is initialized only once, prior to thread startup.
19282 @cite{6.4.1 Keywords}
19284 Add @code{__thread}.
19287 @cite{6.7.1 Storage-class specifiers}
19289 Add @code{__thread} to the list of storage class specifiers in
19292 Change paragraph 2 to
19295 With the exception of @code{__thread}, at most one storage-class
19296 specifier may be given [@dots{}]. The @code{__thread} specifier may
19297 be used alone, or immediately following @code{extern} or
19301 Add new text after paragraph 6
19304 The declaration of an identifier for a variable that has
19305 block scope that specifies @code{__thread} shall also
19306 specify either @code{extern} or @code{static}.
19308 The @code{__thread} specifier shall be used only with
19313 @node C++98 Thread-Local Edits
19314 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
19316 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
19317 that document the exact semantics of the language extension.
19321 @b{[intro.execution]}
19323 New text after paragraph 4
19326 A @dfn{thread} is a flow of control within the abstract machine.
19327 It is implementation defined whether or not there may be more than
19331 New text after paragraph 7
19334 It is unspecified whether additional action must be taken to
19335 ensure when and whether side effects are visible to other threads.
19341 Add @code{__thread}.
19344 @b{[basic.start.main]}
19346 Add after paragraph 5
19349 The thread that begins execution at the @code{main} function is called
19350 the @dfn{main thread}. It is implementation defined how functions
19351 beginning threads other than the main thread are designated or typed.
19352 A function so designated, as well as the @code{main} function, is called
19353 a @dfn{thread startup function}. It is implementation defined what
19354 happens if a thread startup function returns. It is implementation
19355 defined what happens to other threads when any thread calls @code{exit}.
19359 @b{[basic.start.init]}
19361 Add after paragraph 4
19364 The storage for an object of thread storage duration shall be
19365 statically initialized before the first statement of the thread startup
19366 function. An object of thread storage duration shall not require
19367 dynamic initialization.
19371 @b{[basic.start.term]}
19373 Add after paragraph 3
19376 The type of an object with thread storage duration shall not have a
19377 non-trivial destructor, nor shall it be an array type whose elements
19378 (directly or indirectly) have non-trivial destructors.
19384 Add ``thread storage duration'' to the list in paragraph 1.
19389 Thread, static, and automatic storage durations are associated with
19390 objects introduced by declarations [@dots{}].
19393 Add @code{__thread} to the list of specifiers in paragraph 3.
19396 @b{[basic.stc.thread]}
19398 New section before @b{[basic.stc.static]}
19401 The keyword @code{__thread} applied to a non-local object gives the
19402 object thread storage duration.
19404 A local variable or class data member declared both @code{static}
19405 and @code{__thread} gives the variable or member thread storage
19410 @b{[basic.stc.static]}
19415 All objects that have neither thread storage duration, dynamic
19416 storage duration nor are local [@dots{}].
19422 Add @code{__thread} to the list in paragraph 1.
19427 With the exception of @code{__thread}, at most one
19428 @var{storage-class-specifier} shall appear in a given
19429 @var{decl-specifier-seq}. The @code{__thread} specifier may
19430 be used alone, or immediately following the @code{extern} or
19431 @code{static} specifiers. [@dots{}]
19434 Add after paragraph 5
19437 The @code{__thread} specifier can be applied only to the names of objects
19438 and to anonymous unions.
19444 Add after paragraph 6
19447 Non-@code{static} members shall not be @code{__thread}.
19451 @node Binary constants
19452 @section Binary Constants using the @samp{0b} Prefix
19453 @cindex Binary constants using the @samp{0b} prefix
19455 Integer constants can be written as binary constants, consisting of a
19456 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
19457 @samp{0B}. This is particularly useful in environments that operate a
19458 lot on the bit level (like microcontrollers).
19460 The following statements are identical:
19469 The type of these constants follows the same rules as for octal or
19470 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
19473 @node C++ Extensions
19474 @chapter Extensions to the C++ Language
19475 @cindex extensions, C++ language
19476 @cindex C++ language extensions
19478 The GNU compiler provides these extensions to the C++ language (and you
19479 can also use most of the C language extensions in your C++ programs). If you
19480 want to write code that checks whether these features are available, you can
19481 test for the GNU compiler the same way as for C programs: check for a
19482 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
19483 test specifically for GNU C++ (@pxref{Common Predefined Macros,,
19484 Predefined Macros,cpp,The GNU C Preprocessor}).
19487 * C++ Volatiles:: What constitutes an access to a volatile object.
19488 * Restricted Pointers:: C99 restricted pointers and references.
19489 * Vague Linkage:: Where G++ puts inlines, vtables and such.
19490 * C++ Interface:: You can use a single C++ header file for both
19491 declarations and definitions.
19492 * Template Instantiation:: Methods for ensuring that exactly one copy of
19493 each needed template instantiation is emitted.
19494 * Bound member functions:: You can extract a function pointer to the
19495 method denoted by a @samp{->*} or @samp{.*} expression.
19496 * C++ Attributes:: Variable, function, and type attributes for C++ only.
19497 * Function Multiversioning:: Declaring multiple function versions.
19498 * Namespace Association:: Strong using-directives for namespace association.
19499 * Type Traits:: Compiler support for type traits.
19500 * C++ Concepts:: Improved support for generic programming.
19501 * Java Exceptions:: Tweaking exception handling to work with Java.
19502 * Deprecated Features:: Things will disappear from G++.
19503 * Backwards Compatibility:: Compatibilities with earlier definitions of C++.
19506 @node C++ Volatiles
19507 @section When is a Volatile C++ Object Accessed?
19508 @cindex accessing volatiles
19509 @cindex volatile read
19510 @cindex volatile write
19511 @cindex volatile access
19513 The C++ standard differs from the C standard in its treatment of
19514 volatile objects. It fails to specify what constitutes a volatile
19515 access, except to say that C++ should behave in a similar manner to C
19516 with respect to volatiles, where possible. However, the different
19517 lvalueness of expressions between C and C++ complicate the behavior.
19518 G++ behaves the same as GCC for volatile access, @xref{C
19519 Extensions,,Volatiles}, for a description of GCC's behavior.
19521 The C and C++ language specifications differ when an object is
19522 accessed in a void context:
19525 volatile int *src = @var{somevalue};
19529 The C++ standard specifies that such expressions do not undergo lvalue
19530 to rvalue conversion, and that the type of the dereferenced object may
19531 be incomplete. The C++ standard does not specify explicitly that it
19532 is lvalue to rvalue conversion that is responsible for causing an
19533 access. There is reason to believe that it is, because otherwise
19534 certain simple expressions become undefined. However, because it
19535 would surprise most programmers, G++ treats dereferencing a pointer to
19536 volatile object of complete type as GCC would do for an equivalent
19537 type in C@. When the object has incomplete type, G++ issues a
19538 warning; if you wish to force an error, you must force a conversion to
19539 rvalue with, for instance, a static cast.
19541 When using a reference to volatile, G++ does not treat equivalent
19542 expressions as accesses to volatiles, but instead issues a warning that
19543 no volatile is accessed. The rationale for this is that otherwise it
19544 becomes difficult to determine where volatile access occur, and not
19545 possible to ignore the return value from functions returning volatile
19546 references. Again, if you wish to force a read, cast the reference to
19549 G++ implements the same behavior as GCC does when assigning to a
19550 volatile object---there is no reread of the assigned-to object, the
19551 assigned rvalue is reused. Note that in C++ assignment expressions
19552 are lvalues, and if used as an lvalue, the volatile object is
19553 referred to. For instance, @var{vref} refers to @var{vobj}, as
19554 expected, in the following example:
19558 volatile int &vref = vobj = @var{something};
19561 @node Restricted Pointers
19562 @section Restricting Pointer Aliasing
19563 @cindex restricted pointers
19564 @cindex restricted references
19565 @cindex restricted this pointer
19567 As with the C front end, G++ understands the C99 feature of restricted pointers,
19568 specified with the @code{__restrict__}, or @code{__restrict} type
19569 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
19570 language flag, @code{restrict} is not a keyword in C++.
19572 In addition to allowing restricted pointers, you can specify restricted
19573 references, which indicate that the reference is not aliased in the local
19577 void fn (int *__restrict__ rptr, int &__restrict__ rref)
19584 In the body of @code{fn}, @var{rptr} points to an unaliased integer and
19585 @var{rref} refers to a (different) unaliased integer.
19587 You may also specify whether a member function's @var{this} pointer is
19588 unaliased by using @code{__restrict__} as a member function qualifier.
19591 void T::fn () __restrict__
19598 Within the body of @code{T::fn}, @var{this} has the effective
19599 definition @code{T *__restrict__ const this}. Notice that the
19600 interpretation of a @code{__restrict__} member function qualifier is
19601 different to that of @code{const} or @code{volatile} qualifier, in that it
19602 is applied to the pointer rather than the object. This is consistent with
19603 other compilers that implement restricted pointers.
19605 As with all outermost parameter qualifiers, @code{__restrict__} is
19606 ignored in function definition matching. This means you only need to
19607 specify @code{__restrict__} in a function definition, rather than
19608 in a function prototype as well.
19610 @node Vague Linkage
19611 @section Vague Linkage
19612 @cindex vague linkage
19614 There are several constructs in C++ that require space in the object
19615 file but are not clearly tied to a single translation unit. We say that
19616 these constructs have ``vague linkage''. Typically such constructs are
19617 emitted wherever they are needed, though sometimes we can be more
19621 @item Inline Functions
19622 Inline functions are typically defined in a header file which can be
19623 included in many different compilations. Hopefully they can usually be
19624 inlined, but sometimes an out-of-line copy is necessary, if the address
19625 of the function is taken or if inlining fails. In general, we emit an
19626 out-of-line copy in all translation units where one is needed. As an
19627 exception, we only emit inline virtual functions with the vtable, since
19628 it always requires a copy.
19630 Local static variables and string constants used in an inline function
19631 are also considered to have vague linkage, since they must be shared
19632 between all inlined and out-of-line instances of the function.
19636 C++ virtual functions are implemented in most compilers using a lookup
19637 table, known as a vtable. The vtable contains pointers to the virtual
19638 functions provided by a class, and each object of the class contains a
19639 pointer to its vtable (or vtables, in some multiple-inheritance
19640 situations). If the class declares any non-inline, non-pure virtual
19641 functions, the first one is chosen as the ``key method'' for the class,
19642 and the vtable is only emitted in the translation unit where the key
19645 @emph{Note:} If the chosen key method is later defined as inline, the
19646 vtable is still emitted in every translation unit that defines it.
19647 Make sure that any inline virtuals are declared inline in the class
19648 body, even if they are not defined there.
19650 @item @code{type_info} objects
19651 @cindex @code{type_info}
19653 C++ requires information about types to be written out in order to
19654 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
19655 For polymorphic classes (classes with virtual functions), the @samp{type_info}
19656 object is written out along with the vtable so that @samp{dynamic_cast}
19657 can determine the dynamic type of a class object at run time. For all
19658 other types, we write out the @samp{type_info} object when it is used: when
19659 applying @samp{typeid} to an expression, throwing an object, or
19660 referring to a type in a catch clause or exception specification.
19662 @item Template Instantiations
19663 Most everything in this section also applies to template instantiations,
19664 but there are other options as well.
19665 @xref{Template Instantiation,,Where's the Template?}.
19669 When used with GNU ld version 2.8 or later on an ELF system such as
19670 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
19671 these constructs will be discarded at link time. This is known as
19674 On targets that don't support COMDAT, but do support weak symbols, GCC
19675 uses them. This way one copy overrides all the others, but
19676 the unused copies still take up space in the executable.
19678 For targets that do not support either COMDAT or weak symbols,
19679 most entities with vague linkage are emitted as local symbols to
19680 avoid duplicate definition errors from the linker. This does not happen
19681 for local statics in inlines, however, as having multiple copies
19682 almost certainly breaks things.
19684 @xref{C++ Interface,,Declarations and Definitions in One Header}, for
19685 another way to control placement of these constructs.
19687 @node C++ Interface
19688 @section C++ Interface and Implementation Pragmas
19690 @cindex interface and implementation headers, C++
19691 @cindex C++ interface and implementation headers
19692 @cindex pragmas, interface and implementation
19694 @code{#pragma interface} and @code{#pragma implementation} provide the
19695 user with a way of explicitly directing the compiler to emit entities
19696 with vague linkage (and debugging information) in a particular
19699 @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2
19700 by COMDAT support and the ``key method'' heuristic
19701 mentioned in @ref{Vague Linkage}. Using them can actually cause your
19702 program to grow due to unnecessary out-of-line copies of inline
19706 @item #pragma interface
19707 @itemx #pragma interface "@var{subdir}/@var{objects}.h"
19708 @kindex #pragma interface
19709 Use this directive in @emph{header files} that define object classes, to save
19710 space in most of the object files that use those classes. Normally,
19711 local copies of certain information (backup copies of inline member
19712 functions, debugging information, and the internal tables that implement
19713 virtual functions) must be kept in each object file that includes class
19714 definitions. You can use this pragma to avoid such duplication. When a
19715 header file containing @samp{#pragma interface} is included in a
19716 compilation, this auxiliary information is not generated (unless
19717 the main input source file itself uses @samp{#pragma implementation}).
19718 Instead, the object files contain references to be resolved at link
19721 The second form of this directive is useful for the case where you have
19722 multiple headers with the same name in different directories. If you
19723 use this form, you must specify the same string to @samp{#pragma
19726 @item #pragma implementation
19727 @itemx #pragma implementation "@var{objects}.h"
19728 @kindex #pragma implementation
19729 Use this pragma in a @emph{main input file}, when you want full output from
19730 included header files to be generated (and made globally visible). The
19731 included header file, in turn, should use @samp{#pragma interface}.
19732 Backup copies of inline member functions, debugging information, and the
19733 internal tables used to implement virtual functions are all generated in
19734 implementation files.
19736 @cindex implied @code{#pragma implementation}
19737 @cindex @code{#pragma implementation}, implied
19738 @cindex naming convention, implementation headers
19739 If you use @samp{#pragma implementation} with no argument, it applies to
19740 an include file with the same basename@footnote{A file's @dfn{basename}
19741 is the name stripped of all leading path information and of trailing
19742 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
19743 file. For example, in @file{allclass.cc}, giving just
19744 @samp{#pragma implementation}
19745 by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
19747 Use the string argument if you want a single implementation file to
19748 include code from multiple header files. (You must also use
19749 @samp{#include} to include the header file; @samp{#pragma
19750 implementation} only specifies how to use the file---it doesn't actually
19753 There is no way to split up the contents of a single header file into
19754 multiple implementation files.
19757 @cindex inlining and C++ pragmas
19758 @cindex C++ pragmas, effect on inlining
19759 @cindex pragmas in C++, effect on inlining
19760 @samp{#pragma implementation} and @samp{#pragma interface} also have an
19761 effect on function inlining.
19763 If you define a class in a header file marked with @samp{#pragma
19764 interface}, the effect on an inline function defined in that class is
19765 similar to an explicit @code{extern} declaration---the compiler emits
19766 no code at all to define an independent version of the function. Its
19767 definition is used only for inlining with its callers.
19769 @opindex fno-implement-inlines
19770 Conversely, when you include the same header file in a main source file
19771 that declares it as @samp{#pragma implementation}, the compiler emits
19772 code for the function itself; this defines a version of the function
19773 that can be found via pointers (or by callers compiled without
19774 inlining). If all calls to the function can be inlined, you can avoid
19775 emitting the function by compiling with @option{-fno-implement-inlines}.
19776 If any calls are not inlined, you will get linker errors.
19778 @node Template Instantiation
19779 @section Where's the Template?
19780 @cindex template instantiation
19782 C++ templates were the first language feature to require more
19783 intelligence from the environment than was traditionally found on a UNIX
19784 system. Somehow the compiler and linker have to make sure that each
19785 template instance occurs exactly once in the executable if it is needed,
19786 and not at all otherwise. There are two basic approaches to this
19787 problem, which are referred to as the Borland model and the Cfront model.
19790 @item Borland model
19791 Borland C++ solved the template instantiation problem by adding the code
19792 equivalent of common blocks to their linker; the compiler emits template
19793 instances in each translation unit that uses them, and the linker
19794 collapses them together. The advantage of this model is that the linker
19795 only has to consider the object files themselves; there is no external
19796 complexity to worry about. The disadvantage is that compilation time
19797 is increased because the template code is being compiled repeatedly.
19798 Code written for this model tends to include definitions of all
19799 templates in the header file, since they must be seen to be
19803 The AT&T C++ translator, Cfront, solved the template instantiation
19804 problem by creating the notion of a template repository, an
19805 automatically maintained place where template instances are stored. A
19806 more modern version of the repository works as follows: As individual
19807 object files are built, the compiler places any template definitions and
19808 instantiations encountered in the repository. At link time, the link
19809 wrapper adds in the objects in the repository and compiles any needed
19810 instances that were not previously emitted. The advantages of this
19811 model are more optimal compilation speed and the ability to use the
19812 system linker; to implement the Borland model a compiler vendor also
19813 needs to replace the linker. The disadvantages are vastly increased
19814 complexity, and thus potential for error; for some code this can be
19815 just as transparent, but in practice it can been very difficult to build
19816 multiple programs in one directory and one program in multiple
19817 directories. Code written for this model tends to separate definitions
19818 of non-inline member templates into a separate file, which should be
19819 compiled separately.
19822 G++ implements the Borland model on targets where the linker supports it,
19823 including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows.
19824 Otherwise G++ implements neither automatic model.
19826 You have the following options for dealing with template instantiations:
19830 Do nothing. Code written for the Borland model works fine, but
19831 each translation unit contains instances of each of the templates it
19832 uses. The duplicate instances will be discarded by the linker, but in
19833 a large program, this can lead to an unacceptable amount of code
19834 duplication in object files or shared libraries.
19836 Duplicate instances of a template can be avoided by defining an explicit
19837 instantiation in one object file, and preventing the compiler from doing
19838 implicit instantiations in any other object files by using an explicit
19839 instantiation declaration, using the @code{extern template} syntax:
19842 extern template int max (int, int);
19845 This syntax is defined in the C++ 2011 standard, but has been supported by
19846 G++ and other compilers since well before 2011.
19848 Explicit instantiations can be used for the largest or most frequently
19849 duplicated instances, without having to know exactly which other instances
19850 are used in the rest of the program. You can scatter the explicit
19851 instantiations throughout your program, perhaps putting them in the
19852 translation units where the instances are used or the translation units
19853 that define the templates themselves; you can put all of the explicit
19854 instantiations you need into one big file; or you can create small files
19861 template class Foo<int>;
19862 template ostream& operator <<
19863 (ostream&, const Foo<int>&);
19867 for each of the instances you need, and create a template instantiation
19868 library from those.
19870 This is the simplest option, but also offers flexibility and
19871 fine-grained control when necessary. It is also the most portable
19872 alternative and programs using this approach will work with most modern
19877 Compile your template-using code with @option{-frepo}. The compiler
19878 generates files with the extension @samp{.rpo} listing all of the
19879 template instantiations used in the corresponding object files that
19880 could be instantiated there; the link wrapper, @samp{collect2},
19881 then updates the @samp{.rpo} files to tell the compiler where to place
19882 those instantiations and rebuild any affected object files. The
19883 link-time overhead is negligible after the first pass, as the compiler
19884 continues to place the instantiations in the same files.
19886 This can be a suitable option for application code written for the Borland
19887 model, as it usually just works. Code written for the Cfront model
19888 needs to be modified so that the template definitions are available at
19889 one or more points of instantiation; usually this is as simple as adding
19890 @code{#include <tmethods.cc>} to the end of each template header.
19892 For library code, if you want the library to provide all of the template
19893 instantiations it needs, just try to link all of its object files
19894 together; the link will fail, but cause the instantiations to be
19895 generated as a side effect. Be warned, however, that this may cause
19896 conflicts if multiple libraries try to provide the same instantiations.
19897 For greater control, use explicit instantiation as described in the next
19901 @opindex fno-implicit-templates
19902 Compile your code with @option{-fno-implicit-templates} to disable the
19903 implicit generation of template instances, and explicitly instantiate
19904 all the ones you use. This approach requires more knowledge of exactly
19905 which instances you need than do the others, but it's less
19906 mysterious and allows greater control if you want to ensure that only
19907 the intended instances are used.
19909 If you are using Cfront-model code, you can probably get away with not
19910 using @option{-fno-implicit-templates} when compiling files that don't
19911 @samp{#include} the member template definitions.
19913 If you use one big file to do the instantiations, you may want to
19914 compile it without @option{-fno-implicit-templates} so you get all of the
19915 instances required by your explicit instantiations (but not by any
19916 other files) without having to specify them as well.
19918 In addition to forward declaration of explicit instantiations
19919 (with @code{extern}), G++ has extended the template instantiation
19920 syntax to support instantiation of the compiler support data for a
19921 template class (i.e.@: the vtable) without instantiating any of its
19922 members (with @code{inline}), and instantiation of only the static data
19923 members of a template class, without the support data or member
19924 functions (with @code{static}):
19927 inline template class Foo<int>;
19928 static template class Foo<int>;
19932 @node Bound member functions
19933 @section Extracting the Function Pointer from a Bound Pointer to Member Function
19935 @cindex pointer to member function
19936 @cindex bound pointer to member function
19938 In C++, pointer to member functions (PMFs) are implemented using a wide
19939 pointer of sorts to handle all the possible call mechanisms; the PMF
19940 needs to store information about how to adjust the @samp{this} pointer,
19941 and if the function pointed to is virtual, where to find the vtable, and
19942 where in the vtable to look for the member function. If you are using
19943 PMFs in an inner loop, you should really reconsider that decision. If
19944 that is not an option, you can extract the pointer to the function that
19945 would be called for a given object/PMF pair and call it directly inside
19946 the inner loop, to save a bit of time.
19948 Note that you still pay the penalty for the call through a
19949 function pointer; on most modern architectures, such a call defeats the
19950 branch prediction features of the CPU@. This is also true of normal
19951 virtual function calls.
19953 The syntax for this extension is
19957 extern int (A::*fp)();
19958 typedef int (*fptr)(A *);
19960 fptr p = (fptr)(a.*fp);
19963 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
19964 no object is needed to obtain the address of the function. They can be
19965 converted to function pointers directly:
19968 fptr p1 = (fptr)(&A::foo);
19971 @opindex Wno-pmf-conversions
19972 You must specify @option{-Wno-pmf-conversions} to use this extension.
19974 @node C++ Attributes
19975 @section C++-Specific Variable, Function, and Type Attributes
19977 Some attributes only make sense for C++ programs.
19980 @item abi_tag ("@var{tag}", ...)
19981 @cindex @code{abi_tag} function attribute
19982 @cindex @code{abi_tag} variable attribute
19983 @cindex @code{abi_tag} type attribute
19984 The @code{abi_tag} attribute can be applied to a function, variable, or class
19985 declaration. It modifies the mangled name of the entity to
19986 incorporate the tag name, in order to distinguish the function or
19987 class from an earlier version with a different ABI; perhaps the class
19988 has changed size, or the function has a different return type that is
19989 not encoded in the mangled name.
19991 The attribute can also be applied to an inline namespace, but does not
19992 affect the mangled name of the namespace; in this case it is only used
19993 for @option{-Wabi-tag} warnings and automatic tagging of functions and
19994 variables. Tagging inline namespaces is generally preferable to
19995 tagging individual declarations, but the latter is sometimes
19996 necessary, such as when only certain members of a class need to be
19999 The argument can be a list of strings of arbitrary length. The
20000 strings are sorted on output, so the order of the list is
20003 A redeclaration of an entity must not add new ABI tags,
20004 since doing so would change the mangled name.
20006 The ABI tags apply to a name, so all instantiations and
20007 specializations of a template have the same tags. The attribute will
20008 be ignored if applied to an explicit specialization or instantiation.
20010 The @option{-Wabi-tag} flag enables a warning about a class which does
20011 not have all the ABI tags used by its subobjects and virtual functions; for users with code
20012 that needs to coexist with an earlier ABI, using this option can help
20013 to find all affected types that need to be tagged.
20015 When a type involving an ABI tag is used as the type of a variable or
20016 return type of a function where that tag is not already present in the
20017 signature of the function, the tag is automatically applied to the
20018 variable or function. @option{-Wabi-tag} also warns about this
20019 situation; this warning can be avoided by explicitly tagging the
20020 variable or function or moving it into a tagged inline namespace.
20022 @item init_priority (@var{priority})
20023 @cindex @code{init_priority} variable attribute
20025 In Standard C++, objects defined at namespace scope are guaranteed to be
20026 initialized in an order in strict accordance with that of their definitions
20027 @emph{in a given translation unit}. No guarantee is made for initializations
20028 across translation units. However, GNU C++ allows users to control the
20029 order of initialization of objects defined at namespace scope with the
20030 @code{init_priority} attribute by specifying a relative @var{priority},
20031 a constant integral expression currently bounded between 101 and 65535
20032 inclusive. Lower numbers indicate a higher priority.
20034 In the following example, @code{A} would normally be created before
20035 @code{B}, but the @code{init_priority} attribute reverses that order:
20038 Some_Class A __attribute__ ((init_priority (2000)));
20039 Some_Class B __attribute__ ((init_priority (543)));
20043 Note that the particular values of @var{priority} do not matter; only their
20046 @item java_interface
20047 @cindex @code{java_interface} type attribute
20049 This type attribute informs C++ that the class is a Java interface. It may
20050 only be applied to classes declared within an @code{extern "Java"} block.
20051 Calls to methods declared in this interface are dispatched using GCJ's
20052 interface table mechanism, instead of regular virtual table dispatch.
20055 @cindex @code{warn_unused} type attribute
20057 For C++ types with non-trivial constructors and/or destructors it is
20058 impossible for the compiler to determine whether a variable of this
20059 type is truly unused if it is not referenced. This type attribute
20060 informs the compiler that variables of this type should be warned
20061 about if they appear to be unused, just like variables of fundamental
20064 This attribute is appropriate for types which just represent a value,
20065 such as @code{std::string}; it is not appropriate for types which
20066 control a resource, such as @code{std::mutex}.
20068 This attribute is also accepted in C, but it is unnecessary because C
20069 does not have constructors or destructors.
20073 See also @ref{Namespace Association}.
20075 @node Function Multiversioning
20076 @section Function Multiversioning
20077 @cindex function versions
20079 With the GNU C++ front end, for x86 targets, you may specify multiple
20080 versions of a function, where each function is specialized for a
20081 specific target feature. At runtime, the appropriate version of the
20082 function is automatically executed depending on the characteristics of
20083 the execution platform. Here is an example.
20086 __attribute__ ((target ("default")))
20089 // The default version of foo.
20093 __attribute__ ((target ("sse4.2")))
20096 // foo version for SSE4.2
20100 __attribute__ ((target ("arch=atom")))
20103 // foo version for the Intel ATOM processor
20107 __attribute__ ((target ("arch=amdfam10")))
20110 // foo version for the AMD Family 0x10 processors.
20117 assert ((*p) () == foo ());
20122 In the above example, four versions of function foo are created. The
20123 first version of foo with the target attribute "default" is the default
20124 version. This version gets executed when no other target specific
20125 version qualifies for execution on a particular platform. A new version
20126 of foo is created by using the same function signature but with a
20127 different target string. Function foo is called or a pointer to it is
20128 taken just like a regular function. GCC takes care of doing the
20129 dispatching to call the right version at runtime. Refer to the
20130 @uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
20131 Function Multiversioning} for more details.
20133 @node Namespace Association
20134 @section Namespace Association
20136 @strong{Caution:} The semantics of this extension are equivalent
20137 to C++ 2011 inline namespaces. Users should use inline namespaces
20138 instead as this extension will be removed in future versions of G++.
20140 A using-directive with @code{__attribute ((strong))} is stronger
20141 than a normal using-directive in two ways:
20145 Templates from the used namespace can be specialized and explicitly
20146 instantiated as though they were members of the using namespace.
20149 The using namespace is considered an associated namespace of all
20150 templates in the used namespace for purposes of argument-dependent
20154 The used namespace must be nested within the using namespace so that
20155 normal unqualified lookup works properly.
20157 This is useful for composing a namespace transparently from
20158 implementation namespaces. For example:
20163 template <class T> struct A @{ @};
20165 using namespace debug __attribute ((__strong__));
20166 template <> struct A<int> @{ @}; // @r{OK to specialize}
20168 template <class T> void f (A<T>);
20173 f (std::A<float>()); // @r{lookup finds} std::f
20179 @section Type Traits
20181 The C++ front end implements syntactic extensions that allow
20182 compile-time determination of
20183 various characteristics of a type (or of a
20187 @item __has_nothrow_assign (type)
20188 If @code{type} is const qualified or is a reference type then the trait is
20189 false. Otherwise if @code{__has_trivial_assign (type)} is true then the trait
20190 is true, else if @code{type} is a cv class or union type with copy assignment
20191 operators that are known not to throw an exception then the trait is true,
20192 else it is false. Requires: @code{type} shall be a complete type,
20193 (possibly cv-qualified) @code{void}, or an array of unknown bound.
20195 @item __has_nothrow_copy (type)
20196 If @code{__has_trivial_copy (type)} is true then the trait is true, else if
20197 @code{type} is a cv class or union type with copy constructors that
20198 are known not to throw an exception then the trait is true, else it is false.
20199 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
20200 @code{void}, or an array of unknown bound.
20202 @item __has_nothrow_constructor (type)
20203 If @code{__has_trivial_constructor (type)} is true then the trait is
20204 true, else if @code{type} is a cv class or union type (or array
20205 thereof) with a default constructor that is known not to throw an
20206 exception then the trait is true, else it is false. Requires:
20207 @code{type} shall be a complete type, (possibly cv-qualified)
20208 @code{void}, or an array of unknown bound.
20210 @item __has_trivial_assign (type)
20211 If @code{type} is const qualified or is a reference type then the trait is
20212 false. Otherwise if @code{__is_pod (type)} is true then the trait is
20213 true, else if @code{type} is a cv class or union type with a trivial
20214 copy assignment ([class.copy]) then the trait is true, else it is
20215 false. Requires: @code{type} shall be a complete type, (possibly
20216 cv-qualified) @code{void}, or an array of unknown bound.
20218 @item __has_trivial_copy (type)
20219 If @code{__is_pod (type)} is true or @code{type} is a reference type
20220 then the trait is true, else if @code{type} is a cv class or union type
20221 with a trivial copy constructor ([class.copy]) then the trait
20222 is true, else it is false. Requires: @code{type} shall be a complete
20223 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
20225 @item __has_trivial_constructor (type)
20226 If @code{__is_pod (type)} is true then the trait is true, else if
20227 @code{type} is a cv class or union type (or array thereof) with a
20228 trivial default constructor ([class.ctor]) then the trait is true,
20229 else it is false. Requires: @code{type} shall be a complete
20230 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
20232 @item __has_trivial_destructor (type)
20233 If @code{__is_pod (type)} is true or @code{type} is a reference type then
20234 the trait is true, else if @code{type} is a cv class or union type (or
20235 array thereof) with a trivial destructor ([class.dtor]) then the trait
20236 is true, else it is false. Requires: @code{type} shall be a complete
20237 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
20239 @item __has_virtual_destructor (type)
20240 If @code{type} is a class type with a virtual destructor
20241 ([class.dtor]) then the trait is true, else it is false. Requires:
20242 @code{type} shall be a complete type, (possibly cv-qualified)
20243 @code{void}, or an array of unknown bound.
20245 @item __is_abstract (type)
20246 If @code{type} is an abstract class ([class.abstract]) then the trait
20247 is true, else it is false. Requires: @code{type} shall be a complete
20248 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
20250 @item __is_base_of (base_type, derived_type)
20251 If @code{base_type} is a base class of @code{derived_type}
20252 ([class.derived]) then the trait is true, otherwise it is false.
20253 Top-level cv qualifications of @code{base_type} and
20254 @code{derived_type} are ignored. For the purposes of this trait, a
20255 class type is considered is own base. Requires: if @code{__is_class
20256 (base_type)} and @code{__is_class (derived_type)} are true and
20257 @code{base_type} and @code{derived_type} are not the same type
20258 (disregarding cv-qualifiers), @code{derived_type} shall be a complete
20259 type. Diagnostic is produced if this requirement is not met.
20261 @item __is_class (type)
20262 If @code{type} is a cv class type, and not a union type
20263 ([basic.compound]) the trait is true, else it is false.
20265 @item __is_empty (type)
20266 If @code{__is_class (type)} is false then the trait is false.
20267 Otherwise @code{type} is considered empty if and only if: @code{type}
20268 has no non-static data members, or all non-static data members, if
20269 any, are bit-fields of length 0, and @code{type} has no virtual
20270 members, and @code{type} has no virtual base classes, and @code{type}
20271 has no base classes @code{base_type} for which
20272 @code{__is_empty (base_type)} is false. Requires: @code{type} shall
20273 be a complete type, (possibly cv-qualified) @code{void}, or an array
20276 @item __is_enum (type)
20277 If @code{type} is a cv enumeration type ([basic.compound]) the trait is
20278 true, else it is false.
20280 @item __is_literal_type (type)
20281 If @code{type} is a literal type ([basic.types]) the trait is
20282 true, else it is false. Requires: @code{type} shall be a complete type,
20283 (possibly cv-qualified) @code{void}, or an array of unknown bound.
20285 @item __is_pod (type)
20286 If @code{type} is a cv POD type ([basic.types]) then the trait is true,
20287 else it is false. Requires: @code{type} shall be a complete type,
20288 (possibly cv-qualified) @code{void}, or an array of unknown bound.
20290 @item __is_polymorphic (type)
20291 If @code{type} is a polymorphic class ([class.virtual]) then the trait
20292 is true, else it is false. Requires: @code{type} shall be a complete
20293 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
20295 @item __is_standard_layout (type)
20296 If @code{type} is a standard-layout type ([basic.types]) the trait is
20297 true, else it is false. Requires: @code{type} shall be a complete
20298 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
20300 @item __is_trivial (type)
20301 If @code{type} is a trivial type ([basic.types]) the trait is
20302 true, else it is false. Requires: @code{type} shall be a complete
20303 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
20305 @item __is_union (type)
20306 If @code{type} is a cv union type ([basic.compound]) the trait is
20307 true, else it is false.
20309 @item __underlying_type (type)
20310 The underlying type of @code{type}. Requires: @code{type} shall be
20311 an enumeration type ([dcl.enum]).
20317 @section C++ Concepts
20319 C++ concepts provide much-improved support for generic programming. In
20320 particular, they allow the specification of constraints on template arguments.
20321 The constraints are used to extend the usual overloading and partial
20322 specialization capabilities of the language, allowing generic data structures
20323 and algorithms to be ``refined'' based on their properties rather than their
20326 The following keywords are reserved for concepts.
20330 States an expression as an assumption, and if possible, verifies that the
20331 assumption is valid. For example, @code{assume(n > 0)}.
20334 Introduces an axiom definition. Axioms introduce requirements on values.
20337 Introduces a universally quantified object in an axiom. For example,
20338 @code{forall (int n) n + 0 == n}).
20341 Introduces a concept definition. Concepts are sets of syntactic and semantic
20342 requirements on types and their values.
20345 Introduces constraints on template arguments or requirements for a member
20346 function of a class template.
20350 The front end also exposes a number of internal mechanism that can be used
20351 to simplify the writing of type traits. Note that some of these traits are
20352 likely to be removed in the future.
20355 @item __is_same (type1, type2)
20356 A binary type trait: true whenever the type arguments are the same.
20361 @node Java Exceptions
20362 @section Java Exceptions
20364 The Java language uses a slightly different exception handling model
20365 from C++. Normally, GNU C++ automatically detects when you are
20366 writing C++ code that uses Java exceptions, and handle them
20367 appropriately. However, if C++ code only needs to execute destructors
20368 when Java exceptions are thrown through it, GCC guesses incorrectly.
20369 Sample problematic code is:
20372 struct S @{ ~S(); @};
20373 extern void bar(); // @r{is written in Java, and may throw exceptions}
20382 The usual effect of an incorrect guess is a link failure, complaining of
20383 a missing routine called @samp{__gxx_personality_v0}.
20385 You can inform the compiler that Java exceptions are to be used in a
20386 translation unit, irrespective of what it might think, by writing
20387 @samp{@w{#pragma GCC java_exceptions}} at the head of the file. This
20388 @samp{#pragma} must appear before any functions that throw or catch
20389 exceptions, or run destructors when exceptions are thrown through them.
20391 You cannot mix Java and C++ exceptions in the same translation unit. It
20392 is believed to be safe to throw a C++ exception from one file through
20393 another file compiled for the Java exception model, or vice versa, but
20394 there may be bugs in this area.
20396 @node Deprecated Features
20397 @section Deprecated Features
20399 In the past, the GNU C++ compiler was extended to experiment with new
20400 features, at a time when the C++ language was still evolving. Now that
20401 the C++ standard is complete, some of those features are superseded by
20402 superior alternatives. Using the old features might cause a warning in
20403 some cases that the feature will be dropped in the future. In other
20404 cases, the feature might be gone already.
20406 While the list below is not exhaustive, it documents some of the options
20407 that are now deprecated:
20410 @item -fexternal-templates
20411 @itemx -falt-external-templates
20412 These are two of the many ways for G++ to implement template
20413 instantiation. @xref{Template Instantiation}. The C++ standard clearly
20414 defines how template definitions have to be organized across
20415 implementation units. G++ has an implicit instantiation mechanism that
20416 should work just fine for standard-conforming code.
20418 @item -fstrict-prototype
20419 @itemx -fno-strict-prototype
20420 Previously it was possible to use an empty prototype parameter list to
20421 indicate an unspecified number of parameters (like C), rather than no
20422 parameters, as C++ demands. This feature has been removed, except where
20423 it is required for backwards compatibility. @xref{Backwards Compatibility}.
20426 G++ allows a virtual function returning @samp{void *} to be overridden
20427 by one returning a different pointer type. This extension to the
20428 covariant return type rules is now deprecated and will be removed from a
20431 The G++ minimum and maximum operators (@samp{<?} and @samp{>?}) and
20432 their compound forms (@samp{<?=}) and @samp{>?=}) have been deprecated
20433 and are now removed from G++. Code using these operators should be
20434 modified to use @code{std::min} and @code{std::max} instead.
20436 The named return value extension has been deprecated, and is now
20439 The use of initializer lists with new expressions has been deprecated,
20440 and is now removed from G++.
20442 Floating and complex non-type template parameters have been deprecated,
20443 and are now removed from G++.
20445 The implicit typename extension has been deprecated and is now
20448 The use of default arguments in function pointers, function typedefs
20449 and other places where they are not permitted by the standard is
20450 deprecated and will be removed from a future version of G++.
20452 G++ allows floating-point literals to appear in integral constant expressions,
20453 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
20454 This extension is deprecated and will be removed from a future version.
20456 G++ allows static data members of const floating-point type to be declared
20457 with an initializer in a class definition. The standard only allows
20458 initializers for static members of const integral types and const
20459 enumeration types so this extension has been deprecated and will be removed
20460 from a future version.
20462 @node Backwards Compatibility
20463 @section Backwards Compatibility
20464 @cindex Backwards Compatibility
20465 @cindex ARM [Annotated C++ Reference Manual]
20467 Now that there is a definitive ISO standard C++, G++ has a specification
20468 to adhere to. The C++ language evolved over time, and features that
20469 used to be acceptable in previous drafts of the standard, such as the ARM
20470 [Annotated C++ Reference Manual], are no longer accepted. In order to allow
20471 compilation of C++ written to such drafts, G++ contains some backwards
20472 compatibilities. @emph{All such backwards compatibility features are
20473 liable to disappear in future versions of G++.} They should be considered
20474 deprecated. @xref{Deprecated Features}.
20478 If a variable is declared at for scope, it used to remain in scope until
20479 the end of the scope that contained the for statement (rather than just
20480 within the for scope). G++ retains this, but issues a warning, if such a
20481 variable is accessed outside the for scope.
20483 @item Implicit C language
20484 Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
20485 scope to set the language. On such systems, all header files are
20486 implicitly scoped inside a C language scope. Also, an empty prototype
20487 @code{()} is treated as an unspecified number of arguments, rather
20488 than no arguments, as C++ demands.
20491 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
20492 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr