1 @c Copyright (C) 1988-2014 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 * Initializers:: Non-constant initializers.
50 * Compound Literals:: Compound literals give structures, unions
52 * Designated Inits:: Labeling elements of initializers.
53 * Case Ranges:: `case 1 ... 9' and such.
54 * Cast to Union:: Casting to union type from any member of the union.
55 * Mixed Declarations:: Mixing declarations and code.
56 * Function Attributes:: Declaring that functions have no side effects,
57 or that they can never return.
58 * Label Attributes:: Specifying attributes on labels.
59 * Attribute Syntax:: Formal syntax for attributes.
60 * Function Prototypes:: Prototype declarations and old-style definitions.
61 * C++ Comments:: C++ comments are recognized.
62 * Dollar Signs:: Dollar sign is allowed in identifiers.
63 * Character Escapes:: @samp{\e} stands for the character @key{ESC}.
64 * Variable Attributes:: Specifying attributes of variables.
65 * Type Attributes:: Specifying attributes of types.
66 * Alignment:: Inquiring about the alignment of a type or variable.
67 * Inline:: Defining inline functions (as fast as macros).
68 * Volatiles:: What constitutes an access to a volatile object.
69 * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
70 * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
71 * Incomplete Enums:: @code{enum foo;}, with details to follow.
72 * Function Names:: Printable strings which are the name of the current
74 * Return Address:: Getting the return or frame address of a function.
75 * Vector Extensions:: Using vector instructions through built-in functions.
76 * Offsetof:: Special syntax for implementing @code{offsetof}.
77 * __sync Builtins:: Legacy built-in functions for atomic memory access.
78 * __atomic Builtins:: Atomic built-in functions with memory model.
79 * x86 specific memory model extensions for transactional memory:: x86 memory models.
80 * Object Size Checking:: Built-in functions for limited buffer overflow
82 * Cilk Plus Builtins:: Built-in functions for the Cilk Plus language extension.
83 * Other Builtins:: Other built-in functions.
84 * Target Builtins:: Built-in functions specific to particular targets.
85 * Target Format Checks:: Format checks specific to particular targets.
86 * Pragmas:: Pragmas accepted by GCC.
87 * Unnamed Fields:: Unnamed struct/union fields within structs/unions.
88 * Thread-Local:: Per-thread variables.
89 * Binary constants:: Binary constants using the @samp{0b} prefix.
93 @section Statements and Declarations in Expressions
94 @cindex statements inside expressions
95 @cindex declarations inside expressions
96 @cindex expressions containing statements
97 @cindex macros, statements in expressions
99 @c the above section title wrapped and causes an underfull hbox.. i
100 @c changed it from "within" to "in". --mew 4feb93
101 A compound statement enclosed in parentheses may appear as an expression
102 in GNU C@. This allows you to use loops, switches, and local variables
103 within an expression.
105 Recall that a compound statement is a sequence of statements surrounded
106 by braces; in this construct, parentheses go around the braces. For
110 (@{ int y = foo (); int z;
117 is a valid (though slightly more complex than necessary) expression
118 for the absolute value of @code{foo ()}.
120 The last thing in the compound statement should be an expression
121 followed by a semicolon; the value of this subexpression serves as the
122 value of the entire construct. (If you use some other kind of statement
123 last within the braces, the construct has type @code{void}, and thus
124 effectively no value.)
126 This feature is especially useful in making macro definitions ``safe'' (so
127 that they evaluate each operand exactly once). For example, the
128 ``maximum'' function is commonly defined as a macro in standard C as
132 #define max(a,b) ((a) > (b) ? (a) : (b))
136 @cindex side effects, macro argument
137 But this definition computes either @var{a} or @var{b} twice, with bad
138 results if the operand has side effects. In GNU C, if you know the
139 type of the operands (here taken as @code{int}), you can define
140 the macro safely as follows:
143 #define maxint(a,b) \
144 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
147 Embedded statements are not allowed in constant expressions, such as
148 the value of an enumeration constant, the width of a bit-field, or
149 the initial value of a static variable.
151 If you don't know the type of the operand, you can still do this, but you
152 must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}).
154 In G++, the result value of a statement expression undergoes array and
155 function pointer decay, and is returned by value to the enclosing
156 expression. For instance, if @code{A} is a class, then
165 constructs a temporary @code{A} object to hold the result of the
166 statement expression, and that is used to invoke @code{Foo}.
167 Therefore the @code{this} pointer observed by @code{Foo} is not the
170 In a statement expression, any temporaries created within a statement
171 are destroyed at that statement's end. This makes statement
172 expressions inside macros slightly different from function calls. In
173 the latter case temporaries introduced during argument evaluation are
174 destroyed at the end of the statement that includes the function
175 call. In the statement expression case they are destroyed during
176 the statement expression. For instance,
179 #define macro(a) (@{__typeof__(a) b = (a); b + 3; @})
180 template<typename T> T function(T a) @{ T b = a; return b + 3; @}
190 has different places where temporaries are destroyed. For the
191 @code{macro} case, the temporary @code{X} is destroyed just after
192 the initialization of @code{b}. In the @code{function} case that
193 temporary is destroyed when the function returns.
195 These considerations mean that it is probably a bad idea to use
196 statement expressions of this form in header files that are designed to
197 work with C++. (Note that some versions of the GNU C Library contained
198 header files using statement expressions that lead to precisely this
201 Jumping into a statement expression with @code{goto} or using a
202 @code{switch} statement outside the statement expression with a
203 @code{case} or @code{default} label inside the statement expression is
204 not permitted. Jumping into a statement expression with a computed
205 @code{goto} (@pxref{Labels as Values}) has undefined behavior.
206 Jumping out of a statement expression is permitted, but if the
207 statement expression is part of a larger expression then it is
208 unspecified which other subexpressions of that expression have been
209 evaluated except where the language definition requires certain
210 subexpressions to be evaluated before or after the statement
211 expression. In any case, as with a function call, the evaluation of a
212 statement expression is not interleaved with the evaluation of other
213 parts of the containing expression. For example,
216 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz();
220 calls @code{foo} and @code{bar1} and does not call @code{baz} but
221 may or may not call @code{bar2}. If @code{bar2} is called, it is
222 called after @code{foo} and before @code{bar1}.
225 @section Locally Declared Labels
227 @cindex macros, local labels
229 GCC allows you to declare @dfn{local labels} in any nested block
230 scope. A local label is just like an ordinary label, but you can
231 only reference it (with a @code{goto} statement, or by taking its
232 address) within the block in which it is declared.
234 A local label declaration looks like this:
237 __label__ @var{label};
244 __label__ @var{label1}, @var{label2}, /* @r{@dots{}} */;
247 Local label declarations must come at the beginning of the block,
248 before any ordinary declarations or statements.
250 The label declaration defines the label @emph{name}, but does not define
251 the label itself. You must do this in the usual way, with
252 @code{@var{label}:}, within the statements of the statement expression.
254 The local label feature is useful for complex macros. If a macro
255 contains nested loops, a @code{goto} can be useful for breaking out of
256 them. However, an ordinary label whose scope is the whole function
257 cannot be used: if the macro can be expanded several times in one
258 function, the label is multiply defined in that function. A
259 local label avoids this problem. For example:
262 #define SEARCH(value, array, target) \
265 typeof (target) _SEARCH_target = (target); \
266 typeof (*(array)) *_SEARCH_array = (array); \
269 for (i = 0; i < max; i++) \
270 for (j = 0; j < max; j++) \
271 if (_SEARCH_array[i][j] == _SEARCH_target) \
272 @{ (value) = i; goto found; @} \
278 This could also be written using a statement expression:
281 #define SEARCH(array, target) \
284 typeof (target) _SEARCH_target = (target); \
285 typeof (*(array)) *_SEARCH_array = (array); \
288 for (i = 0; i < max; i++) \
289 for (j = 0; j < max; j++) \
290 if (_SEARCH_array[i][j] == _SEARCH_target) \
291 @{ value = i; goto found; @} \
298 Local label declarations also make the labels they declare visible to
299 nested functions, if there are any. @xref{Nested Functions}, for details.
301 @node Labels as Values
302 @section Labels as Values
303 @cindex labels as values
304 @cindex computed gotos
305 @cindex goto with computed label
306 @cindex address of a label
308 You can get the address of a label defined in the current function
309 (or a containing function) with the unary operator @samp{&&}. The
310 value has type @code{void *}. This value is a constant and can be used
311 wherever a constant of that type is valid. For example:
319 To use these values, you need to be able to jump to one. This is done
320 with the computed goto statement@footnote{The analogous feature in
321 Fortran is called an assigned goto, but that name seems inappropriate in
322 C, where one can do more than simply store label addresses in label
323 variables.}, @code{goto *@var{exp};}. For example,
330 Any expression of type @code{void *} is allowed.
332 One way of using these constants is in initializing a static array that
333 serves as a jump table:
336 static void *array[] = @{ &&foo, &&bar, &&hack @};
340 Then you can select a label with indexing, like this:
347 Note that this does not check whether the subscript is in bounds---array
348 indexing in C never does that.
350 Such an array of label values serves a purpose much like that of the
351 @code{switch} statement. The @code{switch} statement is cleaner, so
352 use that rather than an array unless the problem does not fit a
353 @code{switch} statement very well.
355 Another use of label values is in an interpreter for threaded code.
356 The labels within the interpreter function can be stored in the
357 threaded code for super-fast dispatching.
359 You may not use this mechanism to jump to code in a different function.
360 If you do that, totally unpredictable things happen. The best way to
361 avoid this is to store the label address only in automatic variables and
362 never pass it as an argument.
364 An alternate way to write the above example is
367 static const int array[] = @{ &&foo - &&foo, &&bar - &&foo,
369 goto *(&&foo + array[i]);
373 This is more friendly to code living in shared libraries, as it reduces
374 the number of dynamic relocations that are needed, and by consequence,
375 allows the data to be read-only.
376 This alternative with label differences is not supported for the AVR target,
377 please use the first approach for AVR programs.
379 The @code{&&foo} expressions for the same label might have different
380 values if the containing function is inlined or cloned. If a program
381 relies on them being always the same,
382 @code{__attribute__((__noinline__,__noclone__))} should be used to
383 prevent inlining and cloning. If @code{&&foo} is used in a static
384 variable initializer, inlining and cloning is forbidden.
386 @node Nested Functions
387 @section Nested Functions
388 @cindex nested functions
389 @cindex downward funargs
392 A @dfn{nested function} is a function defined inside another function.
393 Nested functions are supported as an extension in GNU C, but are not
394 supported by GNU C++.
396 The nested function's name is local to the block where it is defined.
397 For example, here we define a nested function named @code{square}, and
402 foo (double a, double b)
404 double square (double z) @{ return z * z; @}
406 return square (a) + square (b);
411 The nested function can access all the variables of the containing
412 function that are visible at the point of its definition. This is
413 called @dfn{lexical scoping}. For example, here we show a nested
414 function which uses an inherited variable named @code{offset}:
418 bar (int *array, int offset, int size)
420 int access (int *array, int index)
421 @{ return array[index + offset]; @}
424 for (i = 0; i < size; i++)
425 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
430 Nested function definitions are permitted within functions in the places
431 where variable definitions are allowed; that is, in any block, mixed
432 with the other declarations and statements in the block.
434 It is possible to call the nested function from outside the scope of its
435 name by storing its address or passing the address to another function:
438 hack (int *array, int size)
440 void store (int index, int value)
441 @{ array[index] = value; @}
443 intermediate (store, size);
447 Here, the function @code{intermediate} receives the address of
448 @code{store} as an argument. If @code{intermediate} calls @code{store},
449 the arguments given to @code{store} are used to store into @code{array}.
450 But this technique works only so long as the containing function
451 (@code{hack}, in this example) does not exit.
453 If you try to call the nested function through its address after the
454 containing function exits, all hell breaks loose. If you try
455 to call it after a containing scope level exits, and if it refers
456 to some of the variables that are no longer in scope, you may be lucky,
457 but it's not wise to take the risk. If, however, the nested function
458 does not refer to anything that has gone out of scope, you should be
461 GCC implements taking the address of a nested function using a technique
462 called @dfn{trampolines}. This technique was described in
463 @cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX
464 C++ Conference Proceedings, October 17-21, 1988).
466 A nested function can jump to a label inherited from a containing
467 function, provided the label is explicitly declared in the containing
468 function (@pxref{Local Labels}). Such a jump returns instantly to the
469 containing function, exiting the nested function that did the
470 @code{goto} and any intermediate functions as well. Here is an example:
474 bar (int *array, int offset, int size)
477 int access (int *array, int index)
481 return array[index + offset];
485 for (i = 0; i < size; i++)
486 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */
490 /* @r{Control comes here from @code{access}
491 if it detects an error.} */
498 A nested function always has no linkage. Declaring one with
499 @code{extern} or @code{static} is erroneous. If you need to declare the nested function
500 before its definition, use @code{auto} (which is otherwise meaningless
501 for function declarations).
504 bar (int *array, int offset, int size)
507 auto int access (int *, int);
509 int access (int *array, int index)
513 return array[index + offset];
519 @node Constructing Calls
520 @section Constructing Function Calls
521 @cindex constructing calls
522 @cindex forwarding calls
524 Using the built-in functions described below, you can record
525 the arguments a function received, and call another function
526 with the same arguments, without knowing the number or types
529 You can also record the return value of that function call,
530 and later return that value, without knowing what data type
531 the function tried to return (as long as your caller expects
534 However, these built-in functions may interact badly with some
535 sophisticated features or other extensions of the language. It
536 is, therefore, not recommended to use them outside very simple
537 functions acting as mere forwarders for their arguments.
539 @deftypefn {Built-in Function} {void *} __builtin_apply_args ()
540 This built-in function returns a pointer to data
541 describing how to perform a call with the same arguments as are passed
542 to the current function.
544 The function saves the arg pointer register, structure value address,
545 and all registers that might be used to pass arguments to a function
546 into a block of memory allocated on the stack. Then it returns the
547 address of that block.
550 @deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})
551 This built-in function invokes @var{function}
552 with a copy of the parameters described by @var{arguments}
555 The value of @var{arguments} should be the value returned by
556 @code{__builtin_apply_args}. The argument @var{size} specifies the size
557 of the stack argument data, in bytes.
559 This function returns a pointer to data describing
560 how to return whatever value is returned by @var{function}. The data
561 is saved in a block of memory allocated on the stack.
563 It is not always simple to compute the proper value for @var{size}. The
564 value is used by @code{__builtin_apply} to compute the amount of data
565 that should be pushed on the stack and copied from the incoming argument
569 @deftypefn {Built-in Function} {void} __builtin_return (void *@var{result})
570 This built-in function returns the value described by @var{result} from
571 the containing function. You should specify, for @var{result}, a value
572 returned by @code{__builtin_apply}.
575 @deftypefn {Built-in Function} {} __builtin_va_arg_pack ()
576 This built-in function represents all anonymous arguments of an inline
577 function. It can be used only in inline functions that are always
578 inlined, never compiled as a separate function, such as those using
579 @code{__attribute__ ((__always_inline__))} or
580 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
581 It must be only passed as last argument to some other function
582 with variable arguments. This is useful for writing small wrapper
583 inlines for variable argument functions, when using preprocessor
584 macros is undesirable. For example:
586 extern int myprintf (FILE *f, const char *format, ...);
587 extern inline __attribute__ ((__gnu_inline__)) int
588 myprintf (FILE *f, const char *format, ...)
590 int r = fprintf (f, "myprintf: ");
593 int s = fprintf (f, format, __builtin_va_arg_pack ());
601 @deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len ()
602 This built-in function returns the number of anonymous arguments of
603 an inline function. It can be used only in inline functions that
604 are always inlined, never compiled as a separate function, such
605 as those using @code{__attribute__ ((__always_inline__))} or
606 @code{__attribute__ ((__gnu_inline__))} extern inline functions.
607 For example following does link- or run-time checking of open
608 arguments for optimized code:
611 extern inline __attribute__((__gnu_inline__)) int
612 myopen (const char *path, int oflag, ...)
614 if (__builtin_va_arg_pack_len () > 1)
615 warn_open_too_many_arguments ();
617 if (__builtin_constant_p (oflag))
619 if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
621 warn_open_missing_mode ();
622 return __open_2 (path, oflag);
624 return open (path, oflag, __builtin_va_arg_pack ());
627 if (__builtin_va_arg_pack_len () < 1)
628 return __open_2 (path, oflag);
630 return open (path, oflag, __builtin_va_arg_pack ());
637 @section Referring to a Type with @code{typeof}
640 @cindex macros, types of arguments
642 Another way to refer to the type of an expression is with @code{typeof}.
643 The syntax of using of this keyword looks like @code{sizeof}, but the
644 construct acts semantically like a type name defined with @code{typedef}.
646 There are two ways of writing the argument to @code{typeof}: with an
647 expression or with a type. Here is an example with an expression:
654 This assumes that @code{x} is an array of pointers to functions;
655 the type described is that of the values of the functions.
657 Here is an example with a typename as the argument:
664 Here the type described is that of pointers to @code{int}.
666 If you are writing a header file that must work when included in ISO C
667 programs, write @code{__typeof__} instead of @code{typeof}.
668 @xref{Alternate Keywords}.
670 A @code{typeof} construct can be used anywhere a typedef name can be
671 used. For example, you can use it in a declaration, in a cast, or inside
672 of @code{sizeof} or @code{typeof}.
674 The operand of @code{typeof} is evaluated for its side effects if and
675 only if it is an expression of variably modified type or the name of
678 @code{typeof} is often useful in conjunction with
679 statement expressions (@pxref{Statement Exprs}).
680 Here is how the two together can
681 be used to define a safe ``maximum'' macro which operates on any
682 arithmetic type and evaluates each of its arguments exactly once:
686 (@{ typeof (a) _a = (a); \
687 typeof (b) _b = (b); \
688 _a > _b ? _a : _b; @})
691 @cindex underscores in variables in macros
692 @cindex @samp{_} in variables in macros
693 @cindex local variables in macros
694 @cindex variables, local, in macros
695 @cindex macros, local variables in
697 The reason for using names that start with underscores for the local
698 variables is to avoid conflicts with variable names that occur within the
699 expressions that are substituted for @code{a} and @code{b}. Eventually we
700 hope to design a new form of declaration syntax that allows you to declare
701 variables whose scopes start only after their initializers; this will be a
702 more reliable way to prevent such conflicts.
705 Some more examples of the use of @code{typeof}:
709 This declares @code{y} with the type of what @code{x} points to.
716 This declares @code{y} as an array of such values.
723 This declares @code{y} as an array of pointers to characters:
726 typeof (typeof (char *)[4]) y;
730 It is equivalent to the following traditional C declaration:
736 To see the meaning of the declaration using @code{typeof}, and why it
737 might be a useful way to write, rewrite it with these macros:
740 #define pointer(T) typeof(T *)
741 #define array(T, N) typeof(T [N])
745 Now the declaration can be rewritten this way:
748 array (pointer (char), 4) y;
752 Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
753 pointers to @code{char}.
756 In GNU C, but not GNU C++, you may also declare the type of a variable
757 as @code{__auto_type}. In that case, the declaration must declare
758 only one variable, whose declarator must just be an identifier, the
759 declaration must be initialized, and the type of the variable is
760 determined by the initializer; the name of the variable is not in
761 scope until after the initializer. (In C++, you should use C++11
762 @code{auto} for this purpose.) Using @code{__auto_type}, the
763 ``maximum'' macro above could be written as:
767 (@{ __auto_type _a = (a); \
768 __auto_type _b = (b); \
769 _a > _b ? _a : _b; @})
772 Using @code{__auto_type} instead of @code{typeof} has two advantages:
775 @item Each argument to the macro appears only once in the expansion of
776 the macro. This prevents the size of the macro expansion growing
777 exponentially when calls to such macros are nested inside arguments of
780 @item If the argument to the macro has variably modified type, it is
781 evaluated only once when using @code{__auto_type}, but twice if
782 @code{typeof} is used.
785 @emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported
786 a more limited extension that permitted one to write
789 typedef @var{T} = @var{expr};
793 with the effect of declaring @var{T} to have the type of the expression
794 @var{expr}. This extension does not work with GCC 3 (versions between
795 3.0 and 3.2 crash; 3.2.1 and later give an error). Code that
796 relies on it should be rewritten to use @code{typeof}:
799 typedef typeof(@var{expr}) @var{T};
803 This works with all versions of GCC@.
806 @section Conditionals with Omitted Operands
807 @cindex conditional expressions, extensions
808 @cindex omitted middle-operands
809 @cindex middle-operands, omitted
810 @cindex extensions, @code{?:}
811 @cindex @code{?:} extensions
813 The middle operand in a conditional expression may be omitted. Then
814 if the first operand is nonzero, its value is the value of the conditional
817 Therefore, the expression
824 has the value of @code{x} if that is nonzero; otherwise, the value of
827 This example is perfectly equivalent to
833 @cindex side effect in @code{?:}
834 @cindex @code{?:} side effect
836 In this simple case, the ability to omit the middle operand is not
837 especially useful. When it becomes useful is when the first operand does,
838 or may (if it is a macro argument), contain a side effect. Then repeating
839 the operand in the middle would perform the side effect twice. Omitting
840 the middle operand uses the value already computed without the undesirable
841 effects of recomputing it.
844 @section 128-bit integers
845 @cindex @code{__int128} data types
847 As an extension the integer scalar type @code{__int128} is supported for
848 targets which have an integer mode wide enough to hold 128 bits.
849 Simply write @code{__int128} for a signed 128-bit integer, or
850 @code{unsigned __int128} for an unsigned 128-bit integer. There is no
851 support in GCC for expressing an integer constant of type @code{__int128}
852 for targets with @code{long long} integer less than 128 bits wide.
855 @section Double-Word Integers
856 @cindex @code{long long} data types
857 @cindex double-word arithmetic
858 @cindex multiprecision arithmetic
859 @cindex @code{LL} integer suffix
860 @cindex @code{ULL} integer suffix
862 ISO C99 supports data types for integers that are at least 64 bits wide,
863 and as an extension GCC supports them in C90 mode and in C++.
864 Simply write @code{long long int} for a signed integer, or
865 @code{unsigned long long int} for an unsigned integer. To make an
866 integer constant of type @code{long long int}, add the suffix @samp{LL}
867 to the integer. To make an integer constant of type @code{unsigned long
868 long int}, add the suffix @samp{ULL} to the integer.
870 You can use these types in arithmetic like any other integer types.
871 Addition, subtraction, and bitwise boolean operations on these types
872 are open-coded on all types of machines. Multiplication is open-coded
873 if the machine supports a fullword-to-doubleword widening multiply
874 instruction. Division and shifts are open-coded only on machines that
875 provide special support. The operations that are not open-coded use
876 special library routines that come with GCC@.
878 There may be pitfalls when you use @code{long long} types for function
879 arguments without function prototypes. If a function
880 expects type @code{int} for its argument, and you pass a value of type
881 @code{long long int}, confusion results because the caller and the
882 subroutine disagree about the number of bytes for the argument.
883 Likewise, if the function expects @code{long long int} and you pass
884 @code{int}. The best way to avoid such problems is to use prototypes.
887 @section Complex Numbers
888 @cindex complex numbers
889 @cindex @code{_Complex} keyword
890 @cindex @code{__complex__} keyword
892 ISO C99 supports complex floating data types, and as an extension GCC
893 supports them in C90 mode and in C++. GCC also supports complex integer data
894 types which are not part of ISO C99. You can declare complex types
895 using the keyword @code{_Complex}. As an extension, the older GNU
896 keyword @code{__complex__} is also supported.
898 For example, @samp{_Complex double x;} declares @code{x} as a
899 variable whose real part and imaginary part are both of type
900 @code{double}. @samp{_Complex short int y;} declares @code{y} to
901 have real and imaginary parts of type @code{short int}; this is not
902 likely to be useful, but it shows that the set of complex types is
905 To write a constant with a complex data type, use the suffix @samp{i} or
906 @samp{j} (either one; they are equivalent). For example, @code{2.5fi}
907 has type @code{_Complex float} and @code{3i} has type
908 @code{_Complex int}. Such a constant always has a pure imaginary
909 value, but you can form any complex value you like by adding one to a
910 real constant. This is a GNU extension; if you have an ISO C99
911 conforming C library (such as the GNU C Library), and want to construct complex
912 constants of floating type, you should include @code{<complex.h>} and
913 use the macros @code{I} or @code{_Complex_I} instead.
915 @cindex @code{__real__} keyword
916 @cindex @code{__imag__} keyword
917 To extract the real part of a complex-valued expression @var{exp}, write
918 @code{__real__ @var{exp}}. Likewise, use @code{__imag__} to
919 extract the imaginary part. This is a GNU extension; for values of
920 floating type, you should use the ISO C99 functions @code{crealf},
921 @code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and
922 @code{cimagl}, declared in @code{<complex.h>} and also provided as
923 built-in functions by GCC@.
925 @cindex complex conjugation
926 The operator @samp{~} performs complex conjugation when used on a value
927 with a complex type. This is a GNU extension; for values of
928 floating type, you should use the ISO C99 functions @code{conjf},
929 @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also
930 provided as built-in functions by GCC@.
932 GCC can allocate complex automatic variables in a noncontiguous
933 fashion; it's even possible for the real part to be in a register while
934 the imaginary part is on the stack (or vice versa). Only the DWARF 2
935 debug info format can represent this, so use of DWARF 2 is recommended.
936 If you are using the stabs debug info format, GCC describes a noncontiguous
937 complex variable as if it were two separate variables of noncomplex type.
938 If the variable's actual name is @code{foo}, the two fictitious
939 variables are named @code{foo$real} and @code{foo$imag}. You can
940 examine and set these two fictitious variables with your debugger.
943 @section Additional Floating Types
944 @cindex additional floating types
945 @cindex @code{__float80} data type
946 @cindex @code{__float128} data type
947 @cindex @code{w} floating point suffix
948 @cindex @code{q} floating point suffix
949 @cindex @code{W} floating point suffix
950 @cindex @code{Q} floating point suffix
952 As an extension, GNU C supports additional floating
953 types, @code{__float80} and @code{__float128} to support 80-bit
954 (@code{XFmode}) and 128-bit (@code{TFmode}) floating types.
955 Support for additional types includes the arithmetic operators:
956 add, subtract, multiply, divide; unary arithmetic operators;
957 relational operators; equality operators; and conversions to and from
958 integer and other floating types. Use a suffix @samp{w} or @samp{W}
959 in a literal constant of type @code{__float80} and @samp{q} or @samp{Q}
960 for @code{_float128}. You can declare complex types using the
961 corresponding internal complex type, @code{XCmode} for @code{__float80}
962 type and @code{TCmode} for @code{__float128} type:
965 typedef _Complex float __attribute__((mode(TC))) _Complex128;
966 typedef _Complex float __attribute__((mode(XC))) _Complex80;
969 Not all targets support additional floating-point types. @code{__float80}
970 and @code{__float128} types are supported on i386, x86_64 and IA-64 targets.
971 The @code{__float128} type is supported on hppa HP-UX targets.
974 @section Half-Precision Floating Point
975 @cindex half-precision floating point
976 @cindex @code{__fp16} data type
978 On ARM targets, GCC supports half-precision (16-bit) floating point via
979 the @code{__fp16} type. You must enable this type explicitly
980 with the @option{-mfp16-format} command-line option in order to use it.
982 ARM supports two incompatible representations for half-precision
983 floating-point values. You must choose one of the representations and
984 use it consistently in your program.
986 Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format.
987 This format can represent normalized values in the range of @math{2^{-14}} to 65504.
988 There are 11 bits of significand precision, approximately 3
991 Specifying @option{-mfp16-format=alternative} selects the ARM
992 alternative format. This representation is similar to the IEEE
993 format, but does not support infinities or NaNs. Instead, the range
994 of exponents is extended, so that this format can represent normalized
995 values in the range of @math{2^{-14}} to 131008.
997 The @code{__fp16} type is a storage format only. For purposes
998 of arithmetic and other operations, @code{__fp16} values in C or C++
999 expressions are automatically promoted to @code{float}. In addition,
1000 you cannot declare a function with a return value or parameters
1001 of type @code{__fp16}.
1003 Note that conversions from @code{double} to @code{__fp16}
1004 involve an intermediate conversion to @code{float}. Because
1005 of rounding, this can sometimes produce a different result than a
1008 ARM provides hardware support for conversions between
1009 @code{__fp16} and @code{float} values
1010 as an extension to VFP and NEON (Advanced SIMD). GCC generates
1011 code using these hardware instructions if you compile with
1012 options to select an FPU that provides them;
1013 for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
1014 in addition to the @option{-mfp16-format} option to select
1015 a half-precision format.
1017 Language-level support for the @code{__fp16} data type is
1018 independent of whether GCC generates code using hardware floating-point
1019 instructions. In cases where hardware support is not specified, GCC
1020 implements conversions between @code{__fp16} and @code{float} values
1024 @section Decimal Floating Types
1025 @cindex decimal floating types
1026 @cindex @code{_Decimal32} data type
1027 @cindex @code{_Decimal64} data type
1028 @cindex @code{_Decimal128} data type
1029 @cindex @code{df} integer suffix
1030 @cindex @code{dd} integer suffix
1031 @cindex @code{dl} integer suffix
1032 @cindex @code{DF} integer suffix
1033 @cindex @code{DD} integer suffix
1034 @cindex @code{DL} integer suffix
1036 As an extension, GNU C supports decimal floating types as
1037 defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal
1038 floating types in GCC will evolve as the draft technical report changes.
1039 Calling conventions for any target might also change. Not all targets
1040 support decimal floating types.
1042 The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and
1043 @code{_Decimal128}. They use a radix of ten, unlike the floating types
1044 @code{float}, @code{double}, and @code{long double} whose radix is not
1045 specified by the C standard but is usually two.
1047 Support for decimal floating types includes the arithmetic operators
1048 add, subtract, multiply, divide; unary arithmetic operators;
1049 relational operators; equality operators; and conversions to and from
1050 integer and other floating types. Use a suffix @samp{df} or
1051 @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd}
1052 or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for
1055 GCC support of decimal float as specified by the draft technical report
1060 When the value of a decimal floating type cannot be represented in the
1061 integer type to which it is being converted, the result is undefined
1062 rather than the result value specified by the draft technical report.
1065 GCC does not provide the C library functionality associated with
1066 @file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and
1067 @file{wchar.h}, which must come from a separate C library implementation.
1068 Because of this the GNU C compiler does not define macro
1069 @code{__STDC_DEC_FP__} to indicate that the implementation conforms to
1070 the technical report.
1073 Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128}
1074 are supported by the DWARF 2 debug information format.
1080 ISO C99 supports floating-point numbers written not only in the usual
1081 decimal notation, such as @code{1.55e1}, but also numbers such as
1082 @code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC
1083 supports this in C90 mode (except in some cases when strictly
1084 conforming) and in C++. In that format the
1085 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
1086 mandatory. The exponent is a decimal number that indicates the power of
1087 2 by which the significant part is multiplied. Thus @samp{0x1.f} is
1094 @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
1095 is the same as @code{1.55e1}.
1097 Unlike for floating-point numbers in the decimal notation the exponent
1098 is always required in the hexadecimal notation. Otherwise the compiler
1099 would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This
1100 could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the
1101 extension for floating-point constants of type @code{float}.
1104 @section Fixed-Point Types
1105 @cindex fixed-point types
1106 @cindex @code{_Fract} data type
1107 @cindex @code{_Accum} data type
1108 @cindex @code{_Sat} data type
1109 @cindex @code{hr} fixed-suffix
1110 @cindex @code{r} fixed-suffix
1111 @cindex @code{lr} fixed-suffix
1112 @cindex @code{llr} fixed-suffix
1113 @cindex @code{uhr} fixed-suffix
1114 @cindex @code{ur} fixed-suffix
1115 @cindex @code{ulr} fixed-suffix
1116 @cindex @code{ullr} fixed-suffix
1117 @cindex @code{hk} fixed-suffix
1118 @cindex @code{k} fixed-suffix
1119 @cindex @code{lk} fixed-suffix
1120 @cindex @code{llk} fixed-suffix
1121 @cindex @code{uhk} fixed-suffix
1122 @cindex @code{uk} fixed-suffix
1123 @cindex @code{ulk} fixed-suffix
1124 @cindex @code{ullk} fixed-suffix
1125 @cindex @code{HR} fixed-suffix
1126 @cindex @code{R} fixed-suffix
1127 @cindex @code{LR} fixed-suffix
1128 @cindex @code{LLR} fixed-suffix
1129 @cindex @code{UHR} fixed-suffix
1130 @cindex @code{UR} fixed-suffix
1131 @cindex @code{ULR} fixed-suffix
1132 @cindex @code{ULLR} fixed-suffix
1133 @cindex @code{HK} fixed-suffix
1134 @cindex @code{K} fixed-suffix
1135 @cindex @code{LK} fixed-suffix
1136 @cindex @code{LLK} fixed-suffix
1137 @cindex @code{UHK} fixed-suffix
1138 @cindex @code{UK} fixed-suffix
1139 @cindex @code{ULK} fixed-suffix
1140 @cindex @code{ULLK} fixed-suffix
1142 As an extension, GNU C supports fixed-point types as
1143 defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point
1144 types in GCC will evolve as the draft technical report changes.
1145 Calling conventions for any target might also change. Not all targets
1146 support fixed-point types.
1148 The fixed-point types are
1149 @code{short _Fract},
1152 @code{long long _Fract},
1153 @code{unsigned short _Fract},
1154 @code{unsigned _Fract},
1155 @code{unsigned long _Fract},
1156 @code{unsigned long long _Fract},
1157 @code{_Sat short _Fract},
1159 @code{_Sat long _Fract},
1160 @code{_Sat long long _Fract},
1161 @code{_Sat unsigned short _Fract},
1162 @code{_Sat unsigned _Fract},
1163 @code{_Sat unsigned long _Fract},
1164 @code{_Sat unsigned long long _Fract},
1165 @code{short _Accum},
1168 @code{long long _Accum},
1169 @code{unsigned short _Accum},
1170 @code{unsigned _Accum},
1171 @code{unsigned long _Accum},
1172 @code{unsigned long long _Accum},
1173 @code{_Sat short _Accum},
1175 @code{_Sat long _Accum},
1176 @code{_Sat long long _Accum},
1177 @code{_Sat unsigned short _Accum},
1178 @code{_Sat unsigned _Accum},
1179 @code{_Sat unsigned long _Accum},
1180 @code{_Sat unsigned long long _Accum}.
1182 Fixed-point data values contain fractional and optional integral parts.
1183 The format of fixed-point data varies and depends on the target machine.
1185 Support for fixed-point types includes:
1188 prefix and postfix increment and decrement operators (@code{++}, @code{--})
1190 unary arithmetic operators (@code{+}, @code{-}, @code{!})
1192 binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/})
1194 binary shift operators (@code{<<}, @code{>>})
1196 relational operators (@code{<}, @code{<=}, @code{>=}, @code{>})
1198 equality operators (@code{==}, @code{!=})
1200 assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=},
1201 @code{<<=}, @code{>>=})
1203 conversions to and from integer, floating-point, or fixed-point types
1206 Use a suffix in a fixed-point literal constant:
1208 @item @samp{hr} or @samp{HR} for @code{short _Fract} and
1209 @code{_Sat short _Fract}
1210 @item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract}
1211 @item @samp{lr} or @samp{LR} for @code{long _Fract} and
1212 @code{_Sat long _Fract}
1213 @item @samp{llr} or @samp{LLR} for @code{long long _Fract} and
1214 @code{_Sat long long _Fract}
1215 @item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and
1216 @code{_Sat unsigned short _Fract}
1217 @item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and
1218 @code{_Sat unsigned _Fract}
1219 @item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and
1220 @code{_Sat unsigned long _Fract}
1221 @item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract}
1222 and @code{_Sat unsigned long long _Fract}
1223 @item @samp{hk} or @samp{HK} for @code{short _Accum} and
1224 @code{_Sat short _Accum}
1225 @item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum}
1226 @item @samp{lk} or @samp{LK} for @code{long _Accum} and
1227 @code{_Sat long _Accum}
1228 @item @samp{llk} or @samp{LLK} for @code{long long _Accum} and
1229 @code{_Sat long long _Accum}
1230 @item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and
1231 @code{_Sat unsigned short _Accum}
1232 @item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and
1233 @code{_Sat unsigned _Accum}
1234 @item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and
1235 @code{_Sat unsigned long _Accum}
1236 @item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum}
1237 and @code{_Sat unsigned long long _Accum}
1240 GCC support of fixed-point types as specified by the draft technical report
1245 Pragmas to control overflow and rounding behaviors are not implemented.
1248 Fixed-point types are supported by the DWARF 2 debug information format.
1250 @node Named Address Spaces
1251 @section Named Address Spaces
1252 @cindex Named Address Spaces
1254 As an extension, GNU C supports named address spaces as
1255 defined in the N1275 draft of ISO/IEC DTR 18037. Support for named
1256 address spaces in GCC will evolve as the draft technical report
1257 changes. Calling conventions for any target might also change. At
1258 present, only the AVR, SPU, M32C, and RL78 targets support address
1259 spaces other than the generic address space.
1261 Address space identifiers may be used exactly like any other C type
1262 qualifier (e.g., @code{const} or @code{volatile}). See the N1275
1263 document for more details.
1265 @anchor{AVR Named Address Spaces}
1266 @subsection AVR Named Address Spaces
1268 On the AVR target, there are several address spaces that can be used
1269 in order to put read-only data into the flash memory and access that
1270 data by means of the special instructions @code{LPM} or @code{ELPM}
1271 needed to read from flash.
1273 Per default, any data including read-only data is located in RAM
1274 (the generic address space) so that non-generic address spaces are
1275 needed to locate read-only data in flash memory
1276 @emph{and} to generate the right instructions to access this data
1277 without using (inline) assembler code.
1281 @cindex @code{__flash} AVR Named Address Spaces
1282 The @code{__flash} qualifier locates data in the
1283 @code{.progmem.data} section. Data is read using the @code{LPM}
1284 instruction. Pointers to this address space are 16 bits wide.
1291 @cindex @code{__flash1} AVR Named Address Spaces
1292 @cindex @code{__flash2} AVR Named Address Spaces
1293 @cindex @code{__flash3} AVR Named Address Spaces
1294 @cindex @code{__flash4} AVR Named Address Spaces
1295 @cindex @code{__flash5} AVR Named Address Spaces
1296 These are 16-bit address spaces locating data in section
1297 @code{.progmem@var{N}.data} where @var{N} refers to
1298 address space @code{__flash@var{N}}.
1299 The compiler sets the @code{RAMPZ} segment register appropriately
1300 before reading data by means of the @code{ELPM} instruction.
1303 @cindex @code{__memx} AVR Named Address Spaces
1304 This is a 24-bit address space that linearizes flash and RAM:
1305 If the high bit of the address is set, data is read from
1306 RAM using the lower two bytes as RAM address.
1307 If the high bit of the address is clear, data is read from flash
1308 with @code{RAMPZ} set according to the high byte of the address.
1309 @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}.
1311 Objects in this address space are located in @code{.progmemx.data}.
1317 char my_read (const __flash char ** p)
1319 /* p is a pointer to RAM that points to a pointer to flash.
1320 The first indirection of p reads that flash pointer
1321 from RAM and the second indirection reads a char from this
1327 /* Locate array[] in flash memory */
1328 const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @};
1334 /* Return 17 by reading from flash memory */
1335 return array[array[i]];
1340 For each named address space supported by avr-gcc there is an equally
1341 named but uppercase built-in macro defined.
1342 The purpose is to facilitate testing if respective address space
1343 support is available or not:
1347 const __flash int var = 1;
1354 #include <avr/pgmspace.h> /* From AVR-LibC */
1356 const int var PROGMEM = 1;
1360 return (int) pgm_read_word (&var);
1362 #endif /* __FLASH */
1366 Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
1367 locates data in flash but
1368 accesses to these data read from generic address space, i.e.@:
1370 so that you need special accessors like @code{pgm_read_byte}
1371 from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}}
1372 together with attribute @code{progmem}.
1375 @b{Limitations and caveats}
1379 Reading across the 64@tie{}KiB section boundary of
1380 the @code{__flash} or @code{__flash@var{N}} address spaces
1381 shows undefined behavior. The only address space that
1382 supports reading across the 64@tie{}KiB flash segment boundaries is
1386 If you use one of the @code{__flash@var{N}} address spaces
1387 you must arrange your linker script to locate the
1388 @code{.progmem@var{N}.data} sections according to your needs.
1391 Any data or pointers to the non-generic address spaces must
1392 be qualified as @code{const}, i.e.@: as read-only data.
1393 This still applies if the data in one of these address
1394 spaces like software version number or calibration lookup table are intended to
1395 be changed after load time by, say, a boot loader. In this case
1396 the right qualification is @code{const} @code{volatile} so that the compiler
1397 must not optimize away known values or insert them
1398 as immediates into operands of instructions.
1401 The following code initializes a variable @code{pfoo}
1402 located in static storage with a 24-bit address:
1404 extern const __memx char foo;
1405 const __memx void *pfoo = &foo;
1409 Such code requires at least binutils 2.23, see
1410 @w{@uref{http://sourceware.org/PR13503,PR13503}}.
1414 @subsection M32C Named Address Spaces
1415 @cindex @code{__far} M32C Named Address Spaces
1417 On the M32C target, with the R8C and M16C CPU variants, variables
1418 qualified with @code{__far} are accessed using 32-bit addresses in
1419 order to access memory beyond the first 64@tie{}Ki bytes. If
1420 @code{__far} is used with the M32CM or M32C CPU variants, it has no
1423 @subsection RL78 Named Address Spaces
1424 @cindex @code{__far} RL78 Named Address Spaces
1426 On the RL78 target, variables qualified with @code{__far} are accessed
1427 with 32-bit pointers (20-bit addresses) rather than the default 16-bit
1428 addresses. Non-far variables are assumed to appear in the topmost
1429 64@tie{}KiB of the address space.
1431 @subsection SPU Named Address Spaces
1432 @cindex @code{__ea} SPU Named Address Spaces
1434 On the SPU target variables may be declared as
1435 belonging to another address space by qualifying the type with the
1436 @code{__ea} address space identifier:
1443 The compiler generates special code to access the variable @code{i}.
1444 It may use runtime library
1445 support, or generate special machine instructions to access that address
1449 @section Arrays of Length Zero
1450 @cindex arrays of length zero
1451 @cindex zero-length arrays
1452 @cindex length-zero arrays
1453 @cindex flexible array members
1455 Zero-length arrays are allowed in GNU C@. They are very useful as the
1456 last element of a structure that is really a header for a variable-length
1465 struct line *thisline = (struct line *)
1466 malloc (sizeof (struct line) + this_length);
1467 thisline->length = this_length;
1470 In ISO C90, you would have to give @code{contents} a length of 1, which
1471 means either you waste space or complicate the argument to @code{malloc}.
1473 In ISO C99, you would use a @dfn{flexible array member}, which is
1474 slightly different in syntax and semantics:
1478 Flexible array members are written as @code{contents[]} without
1482 Flexible array members have incomplete type, and so the @code{sizeof}
1483 operator may not be applied. As a quirk of the original implementation
1484 of zero-length arrays, @code{sizeof} evaluates to zero.
1487 Flexible array members may only appear as the last member of a
1488 @code{struct} that is otherwise non-empty.
1491 A structure containing a flexible array member, or a union containing
1492 such a structure (possibly recursively), may not be a member of a
1493 structure or an element of an array. (However, these uses are
1494 permitted by GCC as extensions.)
1497 GCC versions before 3.0 allowed zero-length arrays to be statically
1498 initialized, as if they were flexible arrays. In addition to those
1499 cases that were useful, it also allowed initializations in situations
1500 that would corrupt later data. Non-empty initialization of zero-length
1501 arrays is now treated like any case where there are more initializer
1502 elements than the array holds, in that a suitable warning about ``excess
1503 elements in array'' is given, and the excess elements (all of them, in
1504 this case) are ignored.
1506 Instead GCC allows static initialization of flexible array members.
1507 This is equivalent to defining a new structure containing the original
1508 structure followed by an array of sufficient size to contain the data.
1509 E.g.@: in the following, @code{f1} is constructed as if it were declared
1515 @} f1 = @{ 1, @{ 2, 3, 4 @} @};
1518 struct f1 f1; int data[3];
1519 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @};
1523 The convenience of this extension is that @code{f1} has the desired
1524 type, eliminating the need to consistently refer to @code{f2.f1}.
1526 This has symmetry with normal static arrays, in that an array of
1527 unknown size is also written with @code{[]}.
1529 Of course, this extension only makes sense if the extra data comes at
1530 the end of a top-level object, as otherwise we would be overwriting
1531 data at subsequent offsets. To avoid undue complication and confusion
1532 with initialization of deeply nested arrays, we simply disallow any
1533 non-empty initialization except when the structure is the top-level
1534 object. For example:
1537 struct foo @{ int x; int y[]; @};
1538 struct bar @{ struct foo z; @};
1540 struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
1541 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1542 struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
1543 struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
1546 @node Empty Structures
1547 @section Structures With No Members
1548 @cindex empty structures
1549 @cindex zero-size structures
1551 GCC permits a C structure to have no members:
1558 The structure has size zero. In C++, empty structures are part
1559 of the language. G++ treats empty structures as if they had a single
1560 member of type @code{char}.
1562 @node Variable Length
1563 @section Arrays of Variable Length
1564 @cindex variable-length arrays
1565 @cindex arrays of variable length
1568 Variable-length automatic arrays are allowed in ISO C99, and as an
1569 extension GCC accepts them in C90 mode and in C++. These arrays are
1570 declared like any other automatic arrays, but with a length that is not
1571 a constant expression. The storage is allocated at the point of
1572 declaration and deallocated when the block scope containing the declaration
1578 concat_fopen (char *s1, char *s2, char *mode)
1580 char str[strlen (s1) + strlen (s2) + 1];
1583 return fopen (str, mode);
1587 @cindex scope of a variable length array
1588 @cindex variable-length array scope
1589 @cindex deallocating variable length arrays
1590 Jumping or breaking out of the scope of the array name deallocates the
1591 storage. Jumping into the scope is not allowed; you get an error
1594 @cindex variable-length array in a structure
1595 As an extension, GCC accepts variable-length arrays as a member of
1596 a structure or a union. For example:
1602 struct S @{ int x[n]; @};
1606 @cindex @code{alloca} vs variable-length arrays
1607 You can use the function @code{alloca} to get an effect much like
1608 variable-length arrays. The function @code{alloca} is available in
1609 many other C implementations (but not in all). On the other hand,
1610 variable-length arrays are more elegant.
1612 There are other differences between these two methods. Space allocated
1613 with @code{alloca} exists until the containing @emph{function} returns.
1614 The space for a variable-length array is deallocated as soon as the array
1615 name's scope ends. (If you use both variable-length arrays and
1616 @code{alloca} in the same function, deallocation of a variable-length array
1617 also deallocates anything more recently allocated with @code{alloca}.)
1619 You can also use variable-length arrays as arguments to functions:
1623 tester (int len, char data[len][len])
1629 The length of an array is computed once when the storage is allocated
1630 and is remembered for the scope of the array in case you access it with
1633 If you want to pass the array first and the length afterward, you can
1634 use a forward declaration in the parameter list---another GNU extension.
1638 tester (int len; char data[len][len], int len)
1644 @cindex parameter forward declaration
1645 The @samp{int len} before the semicolon is a @dfn{parameter forward
1646 declaration}, and it serves the purpose of making the name @code{len}
1647 known when the declaration of @code{data} is parsed.
1649 You can write any number of such parameter forward declarations in the
1650 parameter list. They can be separated by commas or semicolons, but the
1651 last one must end with a semicolon, which is followed by the ``real''
1652 parameter declarations. Each forward declaration must match a ``real''
1653 declaration in parameter name and data type. ISO C99 does not support
1654 parameter forward declarations.
1656 @node Variadic Macros
1657 @section Macros with a Variable Number of Arguments.
1658 @cindex variable number of arguments
1659 @cindex macro with variable arguments
1660 @cindex rest argument (in macro)
1661 @cindex variadic macros
1663 In the ISO C standard of 1999, a macro can be declared to accept a
1664 variable number of arguments much as a function can. The syntax for
1665 defining the macro is similar to that of a function. Here is an
1669 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__)
1673 Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of
1674 such a macro, it represents the zero or more tokens until the closing
1675 parenthesis that ends the invocation, including any commas. This set of
1676 tokens replaces the identifier @code{__VA_ARGS__} in the macro body
1677 wherever it appears. See the CPP manual for more information.
1679 GCC has long supported variadic macros, and used a different syntax that
1680 allowed you to give a name to the variable arguments just like any other
1681 argument. Here is an example:
1684 #define debug(format, args...) fprintf (stderr, format, args)
1688 This is in all ways equivalent to the ISO C example above, but arguably
1689 more readable and descriptive.
1691 GNU CPP has two further variadic macro extensions, and permits them to
1692 be used with either of the above forms of macro definition.
1694 In standard C, you are not allowed to leave the variable argument out
1695 entirely; but you are allowed to pass an empty argument. For example,
1696 this invocation is invalid in ISO C, because there is no comma after
1703 GNU CPP permits you to completely omit the variable arguments in this
1704 way. In the above examples, the compiler would complain, though since
1705 the expansion of the macro still has the extra comma after the format
1708 To help solve this problem, CPP behaves specially for variable arguments
1709 used with the token paste operator, @samp{##}. If instead you write
1712 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__)
1716 and if the variable arguments are omitted or empty, the @samp{##}
1717 operator causes the preprocessor to remove the comma before it. If you
1718 do provide some variable arguments in your macro invocation, GNU CPP
1719 does not complain about the paste operation and instead places the
1720 variable arguments after the comma. Just like any other pasted macro
1721 argument, these arguments are not macro expanded.
1723 @node Escaped Newlines
1724 @section Slightly Looser Rules for Escaped Newlines
1725 @cindex escaped newlines
1726 @cindex newlines (escaped)
1728 Recently, the preprocessor has relaxed its treatment of escaped
1729 newlines. Previously, the newline had to immediately follow a
1730 backslash. The current implementation allows whitespace in the form
1731 of spaces, horizontal and vertical tabs, and form feeds between the
1732 backslash and the subsequent newline. The preprocessor issues a
1733 warning, but treats it as a valid escaped newline and combines the two
1734 lines to form a single logical line. This works within comments and
1735 tokens, as well as between tokens. Comments are @emph{not} treated as
1736 whitespace for the purposes of this relaxation, since they have not
1737 yet been replaced with spaces.
1740 @section Non-Lvalue Arrays May Have Subscripts
1741 @cindex subscripting
1742 @cindex arrays, non-lvalue
1744 @cindex subscripting and function values
1745 In ISO C99, arrays that are not lvalues still decay to pointers, and
1746 may be subscripted, although they may not be modified or used after
1747 the next sequence point and the unary @samp{&} operator may not be
1748 applied to them. As an extension, GNU C allows such arrays to be
1749 subscripted in C90 mode, though otherwise they do not decay to
1750 pointers outside C99 mode. For example,
1751 this is valid in GNU C though not valid in C90:
1755 struct foo @{int a[4];@};
1761 return f().a[index];
1767 @section Arithmetic on @code{void}- and Function-Pointers
1768 @cindex void pointers, arithmetic
1769 @cindex void, size of pointer to
1770 @cindex function pointers, arithmetic
1771 @cindex function, size of pointer to
1773 In GNU C, addition and subtraction operations are supported on pointers to
1774 @code{void} and on pointers to functions. This is done by treating the
1775 size of a @code{void} or of a function as 1.
1777 A consequence of this is that @code{sizeof} is also allowed on @code{void}
1778 and on function types, and returns 1.
1780 @opindex Wpointer-arith
1781 The option @option{-Wpointer-arith} requests a warning if these extensions
1785 @section Non-Constant Initializers
1786 @cindex initializers, non-constant
1787 @cindex non-constant initializers
1789 As in standard C++ and ISO C99, the elements of an aggregate initializer for an
1790 automatic variable are not required to be constant expressions in GNU C@.
1791 Here is an example of an initializer with run-time varying elements:
1794 foo (float f, float g)
1796 float beat_freqs[2] = @{ f-g, f+g @};
1801 @node Compound Literals
1802 @section Compound Literals
1803 @cindex constructor expressions
1804 @cindex initializations in expressions
1805 @cindex structures, constructor expression
1806 @cindex expressions, constructor
1807 @cindex compound literals
1808 @c The GNU C name for what C99 calls compound literals was "constructor expressions".
1810 ISO C99 supports compound literals. A compound literal looks like
1811 a cast containing an initializer. Its value is an object of the
1812 type specified in the cast, containing the elements specified in
1813 the initializer; it is an lvalue. As an extension, GCC supports
1814 compound literals in C90 mode and in C++, though the semantics are
1815 somewhat different in C++.
1817 Usually, the specified type is a structure. Assume that
1818 @code{struct foo} and @code{structure} are declared as shown:
1821 struct foo @{int a; char b[2];@} structure;
1825 Here is an example of constructing a @code{struct foo} with a compound literal:
1828 structure = ((struct foo) @{x + y, 'a', 0@});
1832 This is equivalent to writing the following:
1836 struct foo temp = @{x + y, 'a', 0@};
1841 You can also construct an array, though this is dangerous in C++, as
1842 explained below. If all the elements of the compound literal are
1843 (made up of) simple constant expressions, suitable for use in
1844 initializers of objects of static storage duration, then the compound
1845 literal can be coerced to a pointer to its first element and used in
1846 such an initializer, as shown here:
1849 char **foo = (char *[]) @{ "x", "y", "z" @};
1852 Compound literals for scalar types and union types are
1853 also allowed, but then the compound literal is equivalent
1856 As a GNU extension, GCC allows initialization of objects with static storage
1857 duration by compound literals (which is not possible in ISO C99, because
1858 the initializer is not a constant).
1859 It is handled as if the object is initialized only with the bracket
1860 enclosed list if the types of the compound literal and the object match.
1861 The initializer list of the compound literal must be constant.
1862 If the object being initialized has array type of unknown size, the size is
1863 determined by compound literal size.
1866 static struct foo x = (struct foo) @{1, 'a', 'b'@};
1867 static int y[] = (int []) @{1, 2, 3@};
1868 static int z[] = (int [3]) @{1@};
1872 The above lines are equivalent to the following:
1874 static struct foo x = @{1, 'a', 'b'@};
1875 static int y[] = @{1, 2, 3@};
1876 static int z[] = @{1, 0, 0@};
1879 In C, a compound literal designates an unnamed object with static or
1880 automatic storage duration. In C++, a compound literal designates a
1881 temporary object, which only lives until the end of its
1882 full-expression. As a result, well-defined C code that takes the
1883 address of a subobject of a compound literal can be undefined in C++.
1884 For instance, if the array compound literal example above appeared
1885 inside a function, any subsequent use of @samp{foo} in C++ has
1886 undefined behavior because the lifetime of the array ends after the
1887 declaration of @samp{foo}. As a result, the C++ compiler now rejects
1888 the conversion of a temporary array to a pointer.
1890 As an optimization, the C++ compiler sometimes gives array compound
1891 literals longer lifetimes: when the array either appears outside a
1892 function or has const-qualified type. If @samp{foo} and its
1893 initializer had elements of @samp{char *const} type rather than
1894 @samp{char *}, or if @samp{foo} were a global variable, the array
1895 would have static storage duration. But it is probably safest just to
1896 avoid the use of array compound literals in code compiled as C++.
1898 @node Designated Inits
1899 @section Designated Initializers
1900 @cindex initializers with labeled elements
1901 @cindex labeled elements in initializers
1902 @cindex case labels in initializers
1903 @cindex designated initializers
1905 Standard C90 requires the elements of an initializer to appear in a fixed
1906 order, the same as the order of the elements in the array or structure
1909 In ISO C99 you can give the elements in any order, specifying the array
1910 indices or structure field names they apply to, and GNU C allows this as
1911 an extension in C90 mode as well. This extension is not
1912 implemented in GNU C++.
1914 To specify an array index, write
1915 @samp{[@var{index}] =} before the element value. For example,
1918 int a[6] = @{ [4] = 29, [2] = 15 @};
1925 int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
1929 The index values must be constant expressions, even if the array being
1930 initialized is automatic.
1932 An alternative syntax for this that has been obsolete since GCC 2.5 but
1933 GCC still accepts is to write @samp{[@var{index}]} before the element
1934 value, with no @samp{=}.
1936 To initialize a range of elements to the same value, write
1937 @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU
1938 extension. For example,
1941 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @};
1945 If the value in it has side-effects, the side-effects happen only once,
1946 not for each initialized field by the range initializer.
1949 Note that the length of the array is the highest value specified
1952 In a structure initializer, specify the name of a field to initialize
1953 with @samp{.@var{fieldname} =} before the element value. For example,
1954 given the following structure,
1957 struct point @{ int x, y; @};
1961 the following initialization
1964 struct point p = @{ .y = yvalue, .x = xvalue @};
1971 struct point p = @{ xvalue, yvalue @};
1974 Another syntax that has the same meaning, obsolete since GCC 2.5, is
1975 @samp{@var{fieldname}:}, as shown here:
1978 struct point p = @{ y: yvalue, x: xvalue @};
1981 Omitted field members are implicitly initialized the same as objects
1982 that have static storage duration.
1985 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
1986 @dfn{designator}. You can also use a designator (or the obsolete colon
1987 syntax) when initializing a union, to specify which element of the union
1988 should be used. For example,
1991 union foo @{ int i; double d; @};
1993 union foo f = @{ .d = 4 @};
1997 converts 4 to a @code{double} to store it in the union using
1998 the second element. By contrast, casting 4 to type @code{union foo}
1999 stores it into the union as the integer @code{i}, since it is
2000 an integer. (@xref{Cast to Union}.)
2002 You can combine this technique of naming elements with ordinary C
2003 initialization of successive elements. Each initializer element that
2004 does not have a designator applies to the next consecutive element of the
2005 array or structure. For example,
2008 int a[6] = @{ [1] = v1, v2, [4] = v4 @};
2015 int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
2018 Labeling the elements of an array initializer is especially useful
2019 when the indices are characters or belong to an @code{enum} type.
2024 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
2025 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
2028 @cindex designator lists
2029 You can also write a series of @samp{.@var{fieldname}} and
2030 @samp{[@var{index}]} designators before an @samp{=} to specify a
2031 nested subobject to initialize; the list is taken relative to the
2032 subobject corresponding to the closest surrounding brace pair. For
2033 example, with the @samp{struct point} declaration above:
2036 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @};
2040 If the same field is initialized multiple times, it has the value from
2041 the last initialization. If any such overridden initialization has
2042 side-effect, it is unspecified whether the side-effect happens or not.
2043 Currently, GCC discards them and issues a warning.
2046 @section Case Ranges
2048 @cindex ranges in case statements
2050 You can specify a range of consecutive values in a single @code{case} label,
2054 case @var{low} ... @var{high}:
2058 This has the same effect as the proper number of individual @code{case}
2059 labels, one for each integer value from @var{low} to @var{high}, inclusive.
2061 This feature is especially useful for ranges of ASCII character codes:
2067 @strong{Be careful:} Write spaces around the @code{...}, for otherwise
2068 it may be parsed wrong when you use it with integer values. For example,
2083 @section Cast to a Union Type
2084 @cindex cast to a union
2085 @cindex union, casting to a
2087 A cast to union type is similar to other casts, except that the type
2088 specified is a union type. You can specify the type either with
2089 @code{union @var{tag}} or with a typedef name. A cast to union is actually
2090 a constructor, not a cast, and hence does not yield an lvalue like
2091 normal casts. (@xref{Compound Literals}.)
2093 The types that may be cast to the union type are those of the members
2094 of the union. Thus, given the following union and variables:
2097 union foo @{ int i; double d; @};
2103 both @code{x} and @code{y} can be cast to type @code{union foo}.
2105 Using the cast as the right-hand side of an assignment to a variable of
2106 union type is equivalent to storing in a member of the union:
2111 u = (union foo) x @equiv{} u.i = x
2112 u = (union foo) y @equiv{} u.d = y
2115 You can also use the union cast as a function argument:
2118 void hack (union foo);
2120 hack ((union foo) x);
2123 @node Mixed Declarations
2124 @section Mixed Declarations and Code
2125 @cindex mixed declarations and code
2126 @cindex declarations, mixed with code
2127 @cindex code, mixed with declarations
2129 ISO C99 and ISO C++ allow declarations and code to be freely mixed
2130 within compound statements. As an extension, GNU C also allows this in
2131 C90 mode. For example, you could do:
2140 Each identifier is visible from where it is declared until the end of
2141 the enclosing block.
2143 @node Function Attributes
2144 @section Declaring Attributes of Functions
2145 @cindex function attributes
2146 @cindex declaring attributes of functions
2147 @cindex functions that never return
2148 @cindex functions that return more than once
2149 @cindex functions that have no side effects
2150 @cindex functions in arbitrary sections
2151 @cindex functions that behave like malloc
2152 @cindex @code{volatile} applied to function
2153 @cindex @code{const} applied to function
2154 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments
2155 @cindex functions with non-null pointer arguments
2156 @cindex functions that are passed arguments in registers on the 386
2157 @cindex functions that pop the argument stack on the 386
2158 @cindex functions that do not pop the argument stack on the 386
2159 @cindex functions that have different compilation options on the 386
2160 @cindex functions that have different optimization options
2161 @cindex functions that are dynamically resolved
2163 In GNU C, you declare certain things about functions called in your program
2164 which help the compiler optimize function calls and check your code more
2167 The keyword @code{__attribute__} allows you to specify special
2168 attributes when making a declaration. This keyword is followed by an
2169 attribute specification inside double parentheses. The following
2170 attributes are currently defined for functions on all targets:
2171 @code{aligned}, @code{alloc_size}, @code{alloc_align}, @code{assume_aligned},
2172 @code{noreturn}, @code{returns_twice}, @code{noinline}, @code{noclone},
2173 @code{always_inline}, @code{flatten}, @code{pure}, @code{const},
2174 @code{nothrow}, @code{sentinel}, @code{format}, @code{format_arg},
2175 @code{no_instrument_function}, @code{no_split_stack},
2176 @code{section}, @code{constructor},
2177 @code{destructor}, @code{used}, @code{unused}, @code{deprecated},
2178 @code{weak}, @code{malloc}, @code{alias}, @code{ifunc},
2179 @code{warn_unused_result}, @code{nonnull},
2180 @code{returns_nonnull}, @code{gnu_inline},
2181 @code{externally_visible}, @code{hot}, @code{cold}, @code{artificial},
2182 @code{no_sanitize_address}, @code{no_address_safety_analysis},
2183 @code{no_sanitize_undefined}, @code{no_reorder},
2184 @code{error} and @code{warning}.
2185 Several other attributes are defined for functions on particular
2186 target systems. Other attributes, including @code{section} are
2187 supported for variables declarations (@pxref{Variable Attributes}),
2188 labels (@pxref{Label Attributes})
2189 and for types (@pxref{Type Attributes}).
2191 GCC plugins may provide their own attributes.
2193 You may also specify attributes with @samp{__} preceding and following
2194 each keyword. This allows you to use them in header files without
2195 being concerned about a possible macro of the same name. For example,
2196 you may use @code{__noreturn__} instead of @code{noreturn}.
2198 @xref{Attribute Syntax}, for details of the exact syntax for using
2202 @c Keep this table alphabetized by attribute name. Treat _ as space.
2204 @item alias ("@var{target}")
2205 @cindex @code{alias} attribute
2206 The @code{alias} attribute causes the declaration to be emitted as an
2207 alias for another symbol, which must be specified. For instance,
2210 void __f () @{ /* @r{Do something.} */; @}
2211 void f () __attribute__ ((weak, alias ("__f")));
2215 defines @samp{f} to be a weak alias for @samp{__f}. In C++, the
2216 mangled name for the target must be used. It is an error if @samp{__f}
2217 is not defined in the same translation unit.
2219 Not all target machines support this attribute.
2221 @item aligned (@var{alignment})
2222 @cindex @code{aligned} attribute
2223 This attribute specifies a minimum alignment for the function,
2226 You cannot use this attribute to decrease the alignment of a function,
2227 only to increase it. However, when you explicitly specify a function
2228 alignment this overrides the effect of the
2229 @option{-falign-functions} (@pxref{Optimize Options}) option for this
2232 Note that the effectiveness of @code{aligned} attributes may be
2233 limited by inherent limitations in your linker. On many systems, the
2234 linker is only able to arrange for functions to be aligned up to a
2235 certain maximum alignment. (For some linkers, the maximum supported
2236 alignment may be very very small.) See your linker documentation for
2237 further information.
2239 The @code{aligned} attribute can also be used for variables and fields
2240 (@pxref{Variable Attributes}.)
2243 @cindex @code{alloc_size} attribute
2244 The @code{alloc_size} attribute is used to tell the compiler that the
2245 function return value points to memory, where the size is given by
2246 one or two of the functions parameters. GCC uses this
2247 information to improve the correctness of @code{__builtin_object_size}.
2249 The function parameter(s) denoting the allocated size are specified by
2250 one or two integer arguments supplied to the attribute. The allocated size
2251 is either the value of the single function argument specified or the product
2252 of the two function arguments specified. Argument numbering starts at
2258 void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2)))
2259 void* my_realloc(void*, size_t) __attribute__((alloc_size(2)))
2263 declares that @code{my_calloc} returns memory of the size given by
2264 the product of parameter 1 and 2 and that @code{my_realloc} returns memory
2265 of the size given by parameter 2.
2268 @cindex @code{alloc_align} attribute
2269 The @code{alloc_align} attribute is used to tell the compiler that the
2270 function return value points to memory, where the returned pointer minimum
2271 alignment is given by one of the functions parameters. GCC uses this
2272 information to improve pointer alignment analysis.
2274 The function parameter denoting the allocated alignment is specified by
2275 one integer argument, whose number is the argument of the attribute.
2276 Argument numbering starts at one.
2281 void* my_memalign(size_t, size_t) __attribute__((alloc_align(1)))
2285 declares that @code{my_memalign} returns memory with minimum alignment
2286 given by parameter 1.
2288 @item assume_aligned
2289 @cindex @code{assume_aligned} attribute
2290 The @code{assume_aligned} attribute is used to tell the compiler that the
2291 function return value points to memory, where the returned pointer minimum
2292 alignment is given by the first argument.
2293 If the attribute has two arguments, the second argument is misalignment offset.
2298 void* my_alloc1(size_t) __attribute__((assume_aligned(16)))
2299 void* my_alloc2(size_t) __attribute__((assume_aligned(32, 8)))
2303 declares that @code{my_alloc1} returns 16-byte aligned pointer and
2304 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
2308 @cindex @code{always_inline} function attribute
2309 Generally, functions are not inlined unless optimization is specified.
2310 For functions declared inline, this attribute inlines the function
2311 independent of any restrictions that otherwise apply to inlining.
2312 Failure to inline such a function is diagnosed as an error.
2313 Note that if such a function is called indirectly the compiler may
2314 or may not inline it depending on optimization level and a failure
2315 to inline an indirect call may or may not be diagnosed.
2318 @cindex @code{gnu_inline} function attribute
2319 This attribute should be used with a function that is also declared
2320 with the @code{inline} keyword. It directs GCC to treat the function
2321 as if it were defined in gnu90 mode even when compiling in C99 or
2324 If the function is declared @code{extern}, then this definition of the
2325 function is used only for inlining. In no case is the function
2326 compiled as a standalone function, not even if you take its address
2327 explicitly. Such an address becomes an external reference, as if you
2328 had only declared the function, and had not defined it. This has
2329 almost the effect of a macro. The way to use this is to put a
2330 function definition in a header file with this attribute, and put
2331 another copy of the function, without @code{extern}, in a library
2332 file. The definition in the header file causes most calls to the
2333 function to be inlined. If any uses of the function remain, they
2334 refer to the single copy in the library. Note that the two
2335 definitions of the functions need not be precisely the same, although
2336 if they do not have the same effect your program may behave oddly.
2338 In C, if the function is neither @code{extern} nor @code{static}, then
2339 the function is compiled as a standalone function, as well as being
2340 inlined where possible.
2342 This is how GCC traditionally handled functions declared
2343 @code{inline}. Since ISO C99 specifies a different semantics for
2344 @code{inline}, this function attribute is provided as a transition
2345 measure and as a useful feature in its own right. This attribute is
2346 available in GCC 4.1.3 and later. It is available if either of the
2347 preprocessor macros @code{__GNUC_GNU_INLINE__} or
2348 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline
2349 Function is As Fast As a Macro}.
2351 In C++, this attribute does not depend on @code{extern} in any way,
2352 but it still requires the @code{inline} keyword to enable its special
2356 @cindex @code{artificial} function attribute
2357 This attribute is useful for small inline wrappers that if possible
2358 should appear during debugging as a unit. Depending on the debug
2359 info format it either means marking the function as artificial
2360 or using the caller location for all instructions within the inlined
2364 @cindex interrupt handler functions
2365 When added to an interrupt handler with the M32C port, causes the
2366 prologue and epilogue to use bank switching to preserve the registers
2367 rather than saving them on the stack.
2370 @cindex @code{flatten} function attribute
2371 Generally, inlining into a function is limited. For a function marked with
2372 this attribute, every call inside this function is inlined, if possible.
2373 Whether the function itself is considered for inlining depends on its size and
2374 the current inlining parameters.
2376 @item error ("@var{message}")
2377 @cindex @code{error} function attribute
2378 If this attribute is used on a function declaration and a call to such a function
2379 is not eliminated through dead code elimination or other optimizations, an error
2380 that includes @var{message} is diagnosed. This is useful
2381 for compile-time checking, especially together with @code{__builtin_constant_p}
2382 and inline functions where checking the inline function arguments is not
2383 possible through @code{extern char [(condition) ? 1 : -1];} tricks.
2384 While it is possible to leave the function undefined and thus invoke
2385 a link failure, when using this attribute the problem is diagnosed
2386 earlier and with exact location of the call even in presence of inline
2387 functions or when not emitting debugging information.
2389 @item warning ("@var{message}")
2390 @cindex @code{warning} function attribute
2391 If this attribute is used on a function declaration and a call to such a function
2392 is not eliminated through dead code elimination or other optimizations, a warning
2393 that includes @var{message} is diagnosed. This is useful
2394 for compile-time checking, especially together with @code{__builtin_constant_p}
2395 and inline functions. While it is possible to define the function with
2396 a message in @code{.gnu.warning*} section, when using this attribute the problem
2397 is diagnosed earlier and with exact location of the call even in presence
2398 of inline functions or when not emitting debugging information.
2401 @cindex functions that do pop the argument stack on the 386
2403 On the Intel 386, the @code{cdecl} attribute causes the compiler to
2404 assume that the calling function pops off the stack space used to
2405 pass arguments. This is
2406 useful to override the effects of the @option{-mrtd} switch.
2409 @cindex @code{const} function attribute
2410 Many functions do not examine any values except their arguments, and
2411 have no effects except the return value. Basically this is just slightly
2412 more strict class than the @code{pure} attribute below, since function is not
2413 allowed to read global memory.
2415 @cindex pointer arguments
2416 Note that a function that has pointer arguments and examines the data
2417 pointed to must @emph{not} be declared @code{const}. Likewise, a
2418 function that calls a non-@code{const} function usually must not be
2419 @code{const}. It does not make sense for a @code{const} function to
2422 The attribute @code{const} is not implemented in GCC versions earlier
2423 than 2.5. An alternative way to declare that a function has no side
2424 effects, which works in the current version and in some older versions,
2428 typedef int intfn ();
2430 extern const intfn square;
2434 This approach does not work in GNU C++ from 2.6.0 on, since the language
2435 specifies that the @samp{const} must be attached to the return value.
2439 @itemx constructor (@var{priority})
2440 @itemx destructor (@var{priority})
2441 @cindex @code{constructor} function attribute
2442 @cindex @code{destructor} function attribute
2443 The @code{constructor} attribute causes the function to be called
2444 automatically before execution enters @code{main ()}. Similarly, the
2445 @code{destructor} attribute causes the function to be called
2446 automatically after @code{main ()} completes or @code{exit ()} is
2447 called. Functions with these attributes are useful for
2448 initializing data that is used implicitly during the execution of
2451 You may provide an optional integer priority to control the order in
2452 which constructor and destructor functions are run. A constructor
2453 with a smaller priority number runs before a constructor with a larger
2454 priority number; the opposite relationship holds for destructors. So,
2455 if you have a constructor that allocates a resource and a destructor
2456 that deallocates the same resource, both functions typically have the
2457 same priority. The priorities for constructor and destructor
2458 functions are the same as those specified for namespace-scope C++
2459 objects (@pxref{C++ Attributes}).
2461 These attributes are not currently implemented for Objective-C@.
2464 @itemx deprecated (@var{msg})
2465 @cindex @code{deprecated} attribute.
2466 The @code{deprecated} attribute results in a warning if the function
2467 is used anywhere in the source file. This is useful when identifying
2468 functions that are expected to be removed in a future version of a
2469 program. The warning also includes the location of the declaration
2470 of the deprecated function, to enable users to easily find further
2471 information about why the function is deprecated, or what they should
2472 do instead. Note that the warnings only occurs for uses:
2475 int old_fn () __attribute__ ((deprecated));
2477 int (*fn_ptr)() = old_fn;
2481 results in a warning on line 3 but not line 2. The optional @var{msg}
2482 argument, which must be a string, is printed in the warning if
2485 The @code{deprecated} attribute can also be used for variables and
2486 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
2489 @cindex @code{disinterrupt} attribute
2490 On Epiphany and MeP targets, this attribute causes the compiler to emit
2491 instructions to disable interrupts for the duration of the given
2495 @cindex @code{__declspec(dllexport)}
2496 On Microsoft Windows targets and Symbian OS targets the
2497 @code{dllexport} attribute causes the compiler to provide a global
2498 pointer to a pointer in a DLL, so that it can be referenced with the
2499 @code{dllimport} attribute. On Microsoft Windows targets, the pointer
2500 name is formed by combining @code{_imp__} and the function or variable
2503 You can use @code{__declspec(dllexport)} as a synonym for
2504 @code{__attribute__ ((dllexport))} for compatibility with other
2507 On systems that support the @code{visibility} attribute, this
2508 attribute also implies ``default'' visibility. It is an error to
2509 explicitly specify any other visibility.
2511 In previous versions of GCC, the @code{dllexport} attribute was ignored
2512 for inlined functions, unless the @option{-fkeep-inline-functions} flag
2513 had been used. The default behavior now is to emit all dllexported
2514 inline functions; however, this can cause object file-size bloat, in
2515 which case the old behavior can be restored by using
2516 @option{-fno-keep-inline-dllexport}.
2518 The attribute is also ignored for undefined symbols.
2520 When applied to C++ classes, the attribute marks defined non-inlined
2521 member functions and static data members as exports. Static consts
2522 initialized in-class are not marked unless they are also defined
2525 For Microsoft Windows targets there are alternative methods for
2526 including the symbol in the DLL's export table such as using a
2527 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
2528 the @option{--export-all} linker flag.
2531 @cindex @code{__declspec(dllimport)}
2532 On Microsoft Windows and Symbian OS targets, the @code{dllimport}
2533 attribute causes the compiler to reference a function or variable via
2534 a global pointer to a pointer that is set up by the DLL exporting the
2535 symbol. The attribute implies @code{extern}. On Microsoft Windows
2536 targets, the pointer name is formed by combining @code{_imp__} and the
2537 function or variable name.
2539 You can use @code{__declspec(dllimport)} as a synonym for
2540 @code{__attribute__ ((dllimport))} for compatibility with other
2543 On systems that support the @code{visibility} attribute, this
2544 attribute also implies ``default'' visibility. It is an error to
2545 explicitly specify any other visibility.
2547 Currently, the attribute is ignored for inlined functions. If the
2548 attribute is applied to a symbol @emph{definition}, an error is reported.
2549 If a symbol previously declared @code{dllimport} is later defined, the
2550 attribute is ignored in subsequent references, and a warning is emitted.
2551 The attribute is also overridden by a subsequent declaration as
2554 When applied to C++ classes, the attribute marks non-inlined
2555 member functions and static data members as imports. However, the
2556 attribute is ignored for virtual methods to allow creation of vtables
2559 On the SH Symbian OS target the @code{dllimport} attribute also has
2560 another affect---it can cause the vtable and run-time type information
2561 for a class to be exported. This happens when the class has a
2562 dllimported constructor or a non-inline, non-pure virtual function
2563 and, for either of those two conditions, the class also has an inline
2564 constructor or destructor and has a key function that is defined in
2565 the current translation unit.
2567 For Microsoft Windows targets the use of the @code{dllimport}
2568 attribute on functions is not necessary, but provides a small
2569 performance benefit by eliminating a thunk in the DLL@. The use of the
2570 @code{dllimport} attribute on imported variables was required on older
2571 versions of the GNU linker, but can now be avoided by passing the
2572 @option{--enable-auto-import} switch to the GNU linker. As with
2573 functions, using the attribute for a variable eliminates a thunk in
2576 One drawback to using this attribute is that a pointer to a
2577 @emph{variable} marked as @code{dllimport} cannot be used as a constant
2578 address. However, a pointer to a @emph{function} with the
2579 @code{dllimport} attribute can be used as a constant initializer; in
2580 this case, the address of a stub function in the import lib is
2581 referenced. On Microsoft Windows targets, the attribute can be disabled
2582 for functions by setting the @option{-mnop-fun-dllimport} flag.
2585 @cindex eight-bit data on the H8/300, H8/300H, and H8S
2586 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
2587 variable should be placed into the eight-bit data section.
2588 The compiler generates more efficient code for certain operations
2589 on data in the eight-bit data area. Note the eight-bit data area is limited to
2592 You must use GAS and GLD from GNU binutils version 2.7 or later for
2593 this attribute to work correctly.
2596 @cindex exception handler functions
2597 Use this attribute on the NDS32 target to indicate that the specified function
2598 is an exception handler. The compiler will generate corresponding sections
2599 for use in an exception handler.
2601 @item exception_handler
2602 @cindex exception handler functions on the Blackfin processor
2603 Use this attribute on the Blackfin to indicate that the specified function
2604 is an exception handler. The compiler generates function entry and
2605 exit sequences suitable for use in an exception handler when this
2606 attribute is present.
2608 @item externally_visible
2609 @cindex @code{externally_visible} attribute.
2610 This attribute, attached to a global variable or function, nullifies
2611 the effect of the @option{-fwhole-program} command-line option, so the
2612 object remains visible outside the current compilation unit.
2614 If @option{-fwhole-program} is used together with @option{-flto} and
2615 @command{gold} is used as the linker plugin,
2616 @code{externally_visible} attributes are automatically added to functions
2617 (not variable yet due to a current @command{gold} issue)
2618 that are accessed outside of LTO objects according to resolution file
2619 produced by @command{gold}.
2620 For other linkers that cannot generate resolution file,
2621 explicit @code{externally_visible} attributes are still necessary.
2624 @cindex functions that handle memory bank switching
2625 On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to
2626 use a calling convention that takes care of switching memory banks when
2627 entering and leaving a function. This calling convention is also the
2628 default when using the @option{-mlong-calls} option.
2630 On 68HC12 the compiler uses the @code{call} and @code{rtc} instructions
2631 to call and return from a function.
2633 On 68HC11 the compiler generates a sequence of instructions
2634 to invoke a board-specific routine to switch the memory bank and call the
2635 real function. The board-specific routine simulates a @code{call}.
2636 At the end of a function, it jumps to a board-specific routine
2637 instead of using @code{rts}. The board-specific return routine simulates
2640 On MeP targets this causes the compiler to use a calling convention
2641 that assumes the called function is too far away for the built-in
2644 @item fast_interrupt
2645 @cindex interrupt handler functions
2646 Use this attribute on the M32C and RX ports to indicate that the specified
2647 function is a fast interrupt handler. This is just like the
2648 @code{interrupt} attribute, except that @code{freit} is used to return
2649 instead of @code{reit}.
2652 @cindex functions that pop the argument stack on the 386
2653 On the Intel 386, the @code{fastcall} attribute causes the compiler to
2654 pass the first argument (if of integral type) in the register ECX and
2655 the second argument (if of integral type) in the register EDX@. Subsequent
2656 and other typed arguments are passed on the stack. The called function
2657 pops the arguments off the stack. If the number of arguments is variable all
2658 arguments are pushed on the stack.
2661 @cindex functions that pop the argument stack on the 386
2662 On the Intel 386, the @code{thiscall} attribute causes the compiler to
2663 pass the first argument (if of integral type) in the register ECX.
2664 Subsequent and other typed arguments are passed on the stack. The called
2665 function pops the arguments off the stack.
2666 If the number of arguments is variable all arguments are pushed on the
2668 The @code{thiscall} attribute is intended for C++ non-static member functions.
2669 As a GCC extension, this calling convention can be used for C functions
2670 and for static member methods.
2672 @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
2673 @cindex @code{format} function attribute
2675 The @code{format} attribute specifies that a function takes @code{printf},
2676 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that
2677 should be type-checked against a format string. For example, the
2682 my_printf (void *my_object, const char *my_format, ...)
2683 __attribute__ ((format (printf, 2, 3)));
2687 causes the compiler to check the arguments in calls to @code{my_printf}
2688 for consistency with the @code{printf} style format string argument
2691 The parameter @var{archetype} determines how the format string is
2692 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime},
2693 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or
2694 @code{strfmon}. (You can also use @code{__printf__},
2695 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On
2696 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and
2697 @code{ms_strftime} are also present.
2698 @var{archetype} values such as @code{printf} refer to the formats accepted
2699 by the system's C runtime library,
2700 while values prefixed with @samp{gnu_} always refer
2701 to the formats accepted by the GNU C Library. On Microsoft Windows
2702 targets, values prefixed with @samp{ms_} refer to the formats accepted by the
2703 @file{msvcrt.dll} library.
2704 The parameter @var{string-index}
2705 specifies which argument is the format string argument (starting
2706 from 1), while @var{first-to-check} is the number of the first
2707 argument to check against the format string. For functions
2708 where the arguments are not available to be checked (such as
2709 @code{vprintf}), specify the third parameter as zero. In this case the
2710 compiler only checks the format string for consistency. For
2711 @code{strftime} formats, the third parameter is required to be zero.
2712 Since non-static C++ methods have an implicit @code{this} argument, the
2713 arguments of such methods should be counted from two, not one, when
2714 giving values for @var{string-index} and @var{first-to-check}.
2716 In the example above, the format string (@code{my_format}) is the second
2717 argument of the function @code{my_print}, and the arguments to check
2718 start with the third argument, so the correct parameters for the format
2719 attribute are 2 and 3.
2721 @opindex ffreestanding
2722 @opindex fno-builtin
2723 The @code{format} attribute allows you to identify your own functions
2724 that take format strings as arguments, so that GCC can check the
2725 calls to these functions for errors. The compiler always (unless
2726 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats
2727 for the standard library functions @code{printf}, @code{fprintf},
2728 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime},
2729 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
2730 warnings are requested (using @option{-Wformat}), so there is no need to
2731 modify the header file @file{stdio.h}. In C99 mode, the functions
2732 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and
2733 @code{vsscanf} are also checked. Except in strictly conforming C
2734 standard modes, the X/Open function @code{strfmon} is also checked as
2735 are @code{printf_unlocked} and @code{fprintf_unlocked}.
2736 @xref{C Dialect Options,,Options Controlling C Dialect}.
2738 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is
2739 recognized in the same context. Declarations including these format attributes
2740 are parsed for correct syntax, however the result of checking of such format
2741 strings is not yet defined, and is not carried out by this version of the
2744 The target may also provide additional types of format checks.
2745 @xref{Target Format Checks,,Format Checks Specific to Particular
2748 @item format_arg (@var{string-index})
2749 @cindex @code{format_arg} function attribute
2750 @opindex Wformat-nonliteral
2751 The @code{format_arg} attribute specifies that a function takes a format
2752 string for a @code{printf}, @code{scanf}, @code{strftime} or
2753 @code{strfmon} style function and modifies it (for example, to translate
2754 it into another language), so the result can be passed to a
2755 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style
2756 function (with the remaining arguments to the format function the same
2757 as they would have been for the unmodified string). For example, the
2762 my_dgettext (char *my_domain, const char *my_format)
2763 __attribute__ ((format_arg (2)));
2767 causes the compiler to check the arguments in calls to a @code{printf},
2768 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose
2769 format string argument is a call to the @code{my_dgettext} function, for
2770 consistency with the format string argument @code{my_format}. If the
2771 @code{format_arg} attribute had not been specified, all the compiler
2772 could tell in such calls to format functions would be that the format
2773 string argument is not constant; this would generate a warning when
2774 @option{-Wformat-nonliteral} is used, but the calls could not be checked
2775 without the attribute.
2777 The parameter @var{string-index} specifies which argument is the format
2778 string argument (starting from one). Since non-static C++ methods have
2779 an implicit @code{this} argument, the arguments of such methods should
2780 be counted from two.
2782 The @code{format_arg} attribute allows you to identify your own
2783 functions that modify format strings, so that GCC can check the
2784 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon}
2785 type function whose operands are a call to one of your own function.
2786 The compiler always treats @code{gettext}, @code{dgettext}, and
2787 @code{dcgettext} in this manner except when strict ISO C support is
2788 requested by @option{-ansi} or an appropriate @option{-std} option, or
2789 @option{-ffreestanding} or @option{-fno-builtin}
2790 is used. @xref{C Dialect Options,,Options
2791 Controlling C Dialect}.
2793 For Objective-C dialects, the @code{format-arg} attribute may refer to an
2794 @code{NSString} reference for compatibility with the @code{format} attribute
2797 The target may also allow additional types in @code{format-arg} attributes.
2798 @xref{Target Format Checks,,Format Checks Specific to Particular
2801 @item function_vector
2802 @cindex calling functions through the function vector on H8/300, M16C, M32C and SH2A processors
2803 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
2804 function should be called through the function vector. Calling a
2805 function through the function vector reduces code size, however;
2806 the function vector has a limited size (maximum 128 entries on the H8/300
2807 and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector.
2809 On SH2A targets, this attribute declares a function to be called using the
2810 TBR relative addressing mode. The argument to this attribute is the entry
2811 number of the same function in a vector table containing all the TBR
2812 relative addressable functions. For correct operation the TBR must be setup
2813 accordingly to point to the start of the vector table before any functions with
2814 this attribute are invoked. Usually a good place to do the initialization is
2815 the startup routine. The TBR relative vector table can have at max 256 function
2816 entries. The jumps to these functions are generated using a SH2A specific,
2817 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD
2818 from GNU binutils version 2.7 or later for this attribute to work correctly.
2820 Please refer the example of M16C target, to see the use of this
2821 attribute while declaring a function,
2823 In an application, for a function being called once, this attribute
2824 saves at least 8 bytes of code; and if other successive calls are being
2825 made to the same function, it saves 2 bytes of code per each of these
2828 On M16C/M32C targets, the @code{function_vector} attribute declares a
2829 special page subroutine call function. Use of this attribute reduces
2830 the code size by 2 bytes for each call generated to the
2831 subroutine. The argument to the attribute is the vector number entry
2832 from the special page vector table which contains the 16 low-order
2833 bits of the subroutine's entry address. Each vector table has special
2834 page number (18 to 255) that is used in @code{jsrs} instructions.
2835 Jump addresses of the routines are generated by adding 0x0F0000 (in
2836 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
2837 2-byte addresses set in the vector table. Therefore you need to ensure
2838 that all the special page vector routines should get mapped within the
2839 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
2842 In the following example 2 bytes are saved for each call to
2843 function @code{foo}.
2846 void foo (void) __attribute__((function_vector(0x18)));
2857 If functions are defined in one file and are called in another file,
2858 then be sure to write this declaration in both files.
2860 This attribute is ignored for R8C target.
2862 @item ifunc ("@var{resolver}")
2863 @cindex @code{ifunc} attribute
2864 The @code{ifunc} attribute is used to mark a function as an indirect
2865 function using the STT_GNU_IFUNC symbol type extension to the ELF
2866 standard. This allows the resolution of the symbol value to be
2867 determined dynamically at load time, and an optimized version of the
2868 routine can be selected for the particular processor or other system
2869 characteristics determined then. To use this attribute, first define
2870 the implementation functions available, and a resolver function that
2871 returns a pointer to the selected implementation function. The
2872 implementation functions' declarations must match the API of the
2873 function being implemented, the resolver's declaration is be a
2874 function returning pointer to void function returning void:
2877 void *my_memcpy (void *dst, const void *src, size_t len)
2882 static void (*resolve_memcpy (void)) (void)
2884 return my_memcpy; // we'll just always select this routine
2889 The exported header file declaring the function the user calls would
2893 extern void *memcpy (void *, const void *, size_t);
2897 allowing the user to call this as a regular function, unaware of the
2898 implementation. Finally, the indirect function needs to be defined in
2899 the same translation unit as the resolver function:
2902 void *memcpy (void *, const void *, size_t)
2903 __attribute__ ((ifunc ("resolve_memcpy")));
2906 Indirect functions cannot be weak, and require a recent binutils (at
2907 least version 2.20.1), and GNU C library (at least version 2.11.1).
2910 @cindex interrupt handler functions
2911 Use this attribute on the ARC, ARM, AVR, CR16, Epiphany, M32C, M32R/D,
2912 m68k, MeP, MIPS, MSP430, RL78, RX and Xstormy16 ports to indicate that
2913 the specified function is an
2914 interrupt handler. The compiler generates function entry and exit
2915 sequences suitable for use in an interrupt handler when this attribute
2916 is present. With Epiphany targets it may also generate a special section with
2917 code to initialize the interrupt vector table.
2919 Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, MicroBlaze,
2920 and SH processors can be specified via the @code{interrupt_handler} attribute.
2922 Note, on the ARC, you must specify the kind of interrupt to be handled
2923 in a parameter to the interrupt attribute like this:
2926 void f () __attribute__ ((interrupt ("ilink1")));
2929 Permissible values for this parameter are: @w{@code{ilink1}} and
2932 Note, on the AVR, the hardware globally disables interrupts when an
2933 interrupt is executed. The first instruction of an interrupt handler
2934 declared with this attribute is a @code{SEI} instruction to
2935 re-enable interrupts. See also the @code{signal} function attribute
2936 that does not insert a @code{SEI} instruction. If both @code{signal} and
2937 @code{interrupt} are specified for the same function, @code{signal}
2938 is silently ignored.
2940 Note, for the ARM, you can specify the kind of interrupt to be handled by
2941 adding an optional parameter to the interrupt attribute like this:
2944 void f () __attribute__ ((interrupt ("IRQ")));
2948 Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
2949 @code{SWI}, @code{ABORT} and @code{UNDEF}.
2951 On ARMv7-M the interrupt type is ignored, and the attribute means the function
2952 may be called with a word-aligned stack pointer.
2954 Note, for the MSP430 you can provide an argument to the interrupt
2955 attribute which specifies a name or number. If the argument is a
2956 number it indicates the slot in the interrupt vector table (0 - 31) to
2957 which this handler should be assigned. If the argument is a name it
2958 is treated as a symbolic name for the vector slot. These names should
2959 match up with appropriate entries in the linker script. By default
2960 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
2961 @code{reset} for vector 31 are recognised.
2963 You can also use the following function attributes to modify how
2964 normal functions interact with interrupt functions:
2968 @cindex @code{critical} attribute
2969 Critical functions disable interrupts upon entry and restore the
2970 previous interrupt state upon exit. Critical functions cannot also
2971 have the @code{naked} or @code{reentrant} attributes. They can have
2972 the @code{interrupt} attribute.
2975 @cindex @code{reentrant} attribute
2976 Reentrant functions disable interrupts upon entry and enable them
2977 upon exit. Reentrant functions cannot also have the @code{naked}
2978 or @code{critical} attributes. They can have the @code{interrupt}
2982 @cindex @code{wakeup} attribute
2983 This attribute only applies to interrupt functions. It is silently
2984 ignored if applied to a non-interrupt function. A wakeup interrupt
2985 function will rouse the processor from any low-power state that it
2986 might be in when the function exits.
2990 On Epiphany targets one or more optional parameters can be added like this:
2993 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
2996 Permissible values for these parameters are: @w{@code{reset}},
2997 @w{@code{software_exception}}, @w{@code{page_miss}},
2998 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
2999 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
3000 Multiple parameters indicate that multiple entries in the interrupt
3001 vector table should be initialized for this function, i.e.@: for each
3002 parameter @w{@var{name}}, a jump to the function is emitted in
3003 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
3004 entirely, in which case no interrupt vector table entry is provided.
3006 Note, on Epiphany targets, interrupts are enabled inside the function
3007 unless the @code{disinterrupt} attribute is also specified.
3009 On Epiphany targets, you can also use the following attribute to
3010 modify the behavior of an interrupt handler:
3012 @item forwarder_section
3013 @cindex @code{forwarder_section} attribute
3014 The interrupt handler may be in external memory which cannot be
3015 reached by a branch instruction, so generate a local memory trampoline
3016 to transfer control. The single parameter identifies the section where
3017 the trampoline is placed.
3020 The following examples are all valid uses of these attributes on
3023 void __attribute__ ((interrupt)) universal_handler ();
3024 void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
3025 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
3026 void __attribute__ ((interrupt ("timer0"), disinterrupt))
3027 fast_timer_handler ();
3028 void __attribute__ ((interrupt ("dma0, dma1"), forwarder_section ("tramp")))
3029 external_dma_handler ();
3032 On MIPS targets, you can use the following attributes to modify the behavior
3033 of an interrupt handler:
3035 @item use_shadow_register_set
3036 @cindex @code{use_shadow_register_set} attribute
3037 Assume that the handler uses a shadow register set, instead of
3038 the main general-purpose registers.
3040 @item keep_interrupts_masked
3041 @cindex @code{keep_interrupts_masked} attribute
3042 Keep interrupts masked for the whole function. Without this attribute,
3043 GCC tries to reenable interrupts for as much of the function as it can.
3045 @item use_debug_exception_return
3046 @cindex @code{use_debug_exception_return} attribute
3047 Return using the @code{deret} instruction. Interrupt handlers that don't
3048 have this attribute return using @code{eret} instead.
3051 You can use any combination of these attributes, as shown below:
3053 void __attribute__ ((interrupt)) v0 ();
3054 void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
3055 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
3056 void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
3057 void __attribute__ ((interrupt, use_shadow_register_set,
3058 keep_interrupts_masked)) v4 ();
3059 void __attribute__ ((interrupt, use_shadow_register_set,
3060 use_debug_exception_return)) v5 ();
3061 void __attribute__ ((interrupt, keep_interrupts_masked,
3062 use_debug_exception_return)) v6 ();
3063 void __attribute__ ((interrupt, use_shadow_register_set,
3064 keep_interrupts_masked,
3065 use_debug_exception_return)) v7 ();
3068 On NDS32 target, this attribute is to indicate that the specified function
3069 is an interrupt handler. The compiler will generate corresponding sections
3070 for use in an interrupt handler. You can use the following attributes
3071 to modify the behavior:
3074 @cindex @code{nested} attribute
3075 This interrupt service routine is interruptible.
3077 @cindex @code{not_nested} attribute
3078 This interrupt service routine is not interruptible.
3080 @cindex @code{nested_ready} attribute
3081 This interrupt service routine is interruptible after @code{PSW.GIE}
3082 (global interrupt enable) is set. This allows interrupt service routine to
3083 finish some short critical code before enabling interrupts.
3085 @cindex @code{save_all} attribute
3086 The system will help save all registers into stack before entering
3089 @cindex @code{partial_save} attribute
3090 The system will help save caller registers into stack before entering
3094 On RL78, use @code{brk_interrupt} instead of @code{interrupt} for
3095 handlers intended to be used with the @code{BRK} opcode (i.e.@: those
3096 that must end with @code{RETB} instead of @code{RETI}).
3098 On RX targets, you may specify one or more vector numbers as arguments
3099 to the attribute, as well as naming an alternate table name.
3100 Parameters are handled sequentially, so one handler can be assigned to
3101 multiple entries in multiple tables. One may also pass the magic
3102 string @code{"$default"} which causes the function to be used for any
3103 unfilled slots in the current table.
3105 This example shows a simple assignment of a function to one vector in
3106 the default table (note that preprocessor macros may be used for
3107 chip-specific symbolic vector names):
3109 void __attribute__ ((interrupt (5))) txd1_handler ();
3112 This example assigns a function to two slots in the default table
3113 (using preprocessor macros defined elsewhere) and makes it the default
3114 for the @code{dct} table:
3116 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
3120 @item interrupt_handler
3121 @cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors
3122 Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to
3123 indicate that the specified function is an interrupt handler. The compiler
3124 generates function entry and exit sequences suitable for use in an
3125 interrupt handler when this attribute is present.
3127 @item interrupt_thread
3128 @cindex interrupt thread functions on fido
3129 Use this attribute on fido, a subarchitecture of the m68k, to indicate
3130 that the specified function is an interrupt handler that is designed
3131 to run as a thread. The compiler omits generate prologue/epilogue
3132 sequences and replaces the return instruction with a @code{sleep}
3133 instruction. This attribute is available only on fido.
3136 @cindex interrupt service routines on ARM
3137 Use this attribute on ARM to write Interrupt Service Routines. This is an
3138 alias to the @code{interrupt} attribute above.
3141 @cindex User stack pointer in interrupts on the Blackfin
3142 When used together with @code{interrupt_handler}, @code{exception_handler}
3143 or @code{nmi_handler}, code is generated to load the stack pointer
3144 from the USP register in the function prologue.
3147 @cindex @code{l1_text} function attribute
3148 This attribute specifies a function to be placed into L1 Instruction
3149 SRAM@. The function is put into a specific section named @code{.l1.text}.
3150 With @option{-mfdpic}, function calls with a such function as the callee
3151 or caller uses inlined PLT.
3154 @cindex @code{l2} function attribute
3155 On the Blackfin, this attribute specifies a function to be placed into L2
3156 SRAM. The function is put into a specific section named
3157 @code{.l1.text}. With @option{-mfdpic}, callers of such functions use
3161 @cindex @code{leaf} function attribute
3162 Calls to external functions with this attribute must return to the current
3163 compilation unit only by return or by exception handling. In particular, leaf
3164 functions are not allowed to call callback function passed to it from the current
3165 compilation unit or directly call functions exported by the unit or longjmp
3166 into the unit. Leaf function might still call functions from other compilation
3167 units and thus they are not necessarily leaf in the sense that they contain no
3168 function calls at all.
3170 The attribute is intended for library functions to improve dataflow analysis.
3171 The compiler takes the hint that any data not escaping the current compilation unit can
3172 not be used or modified by the leaf function. For example, the @code{sin} function
3173 is a leaf function, but @code{qsort} is not.
3175 Note that leaf functions might invoke signals and signal handlers might be
3176 defined in the current compilation unit and use static variables. The only
3177 compliant way to write such a signal handler is to declare such variables
3180 The attribute has no effect on functions defined within the current compilation
3181 unit. This is to allow easy merging of multiple compilation units into one,
3182 for example, by using the link-time optimization. For this reason the
3183 attribute is not allowed on types to annotate indirect calls.
3185 @item long_call/medium_call/short_call
3186 @cindex indirect calls on ARC
3187 @cindex indirect calls on ARM
3188 @cindex indirect calls on Epiphany
3189 These attributes specify how a particular function is called on
3190 ARC, ARM and Epiphany - with @code{medium_call} being specific to ARC.
3191 These attributes override the
3192 @option{-mlong-calls} (@pxref{ARM Options} and @ref{ARC Options})
3193 and @option{-mmedium-calls} (@pxref{ARC Options})
3194 command-line switches and @code{#pragma long_calls} settings. For ARM, the
3195 @code{long_call} attribute indicates that the function might be far
3196 away from the call site and require a different (more expensive)
3197 calling sequence. The @code{short_call} attribute always places
3198 the offset to the function from the call site into the @samp{BL}
3199 instruction directly.
3201 For ARC, a function marked with the @code{long_call} attribute is
3202 always called using register-indirect jump-and-link instructions,
3203 thereby enabling the called function to be placed anywhere within the
3204 32-bit address space. A function marked with the @code{medium_call}
3205 attribute will always be close enough to be called with an unconditional
3206 branch-and-link instruction, which has a 25-bit offset from
3207 the call site. A function marked with the @code{short_call}
3208 attribute will always be close enough to be called with a conditional
3209 branch-and-link instruction, which has a 21-bit offset from
3212 @item longcall/shortcall
3213 @cindex functions called via pointer on the RS/6000 and PowerPC
3214 On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute
3215 indicates that the function might be far away from the call site and
3216 require a different (more expensive) calling sequence. The
3217 @code{shortcall} attribute indicates that the function is always close
3218 enough for the shorter calling sequence to be used. These attributes
3219 override both the @option{-mlongcall} switch and, on the RS/6000 and
3220 PowerPC, the @code{#pragma longcall} setting.
3222 @xref{RS/6000 and PowerPC Options}, for more information on whether long
3223 calls are necessary.
3225 @item long_call/near/far
3226 @cindex indirect calls on MIPS
3227 These attributes specify how a particular function is called on MIPS@.
3228 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
3229 command-line switch. The @code{long_call} and @code{far} attributes are
3230 synonyms, and cause the compiler to always call
3231 the function by first loading its address into a register, and then using
3232 the contents of that register. The @code{near} attribute has the opposite
3233 effect; it specifies that non-PIC calls should be made using the more
3234 efficient @code{jal} instruction.
3237 @cindex @code{malloc} attribute
3238 This tells the compiler that a function is @code{malloc}-like, i.e.,
3239 that the pointer @var{P} returned by the function cannot alias any
3240 other pointer valid when the function returns, and moreover no
3241 pointers to valid objects occur in any storage addressed by @var{P}.
3243 Using this attribute can improve optimization. Functions like
3244 @code{malloc} and @code{calloc} have this property because they return
3245 a pointer to uninitialized or zeroed-out storage. However, functions
3246 like @code{realloc} do not have this property, as they can return a
3247 pointer to storage containing pointers.
3249 @item mips16/nomips16
3250 @cindex @code{mips16} attribute
3251 @cindex @code{nomips16} attribute
3253 On MIPS targets, you can use the @code{mips16} and @code{nomips16}
3254 function attributes to locally select or turn off MIPS16 code generation.
3255 A function with the @code{mips16} attribute is emitted as MIPS16 code,
3256 while MIPS16 code generation is disabled for functions with the
3257 @code{nomips16} attribute. These attributes override the
3258 @option{-mips16} and @option{-mno-mips16} options on the command line
3259 (@pxref{MIPS Options}).
3261 When compiling files containing mixed MIPS16 and non-MIPS16 code, the
3262 preprocessor symbol @code{__mips16} reflects the setting on the command line,
3263 not that within individual functions. Mixed MIPS16 and non-MIPS16 code
3264 may interact badly with some GCC extensions such as @code{__builtin_apply}
3265 (@pxref{Constructing Calls}).
3267 @item micromips/nomicromips
3268 @cindex @code{micromips} attribute
3269 @cindex @code{nomicromips} attribute
3271 On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
3272 function attributes to locally select or turn off microMIPS code generation.
3273 A function with the @code{micromips} attribute is emitted as microMIPS code,
3274 while microMIPS code generation is disabled for functions with the
3275 @code{nomicromips} attribute. These attributes override the
3276 @option{-mmicromips} and @option{-mno-micromips} options on the command line
3277 (@pxref{MIPS Options}).
3279 When compiling files containing mixed microMIPS and non-microMIPS code, the
3280 preprocessor symbol @code{__mips_micromips} reflects the setting on the
3282 not that within individual functions. Mixed microMIPS and non-microMIPS code
3283 may interact badly with some GCC extensions such as @code{__builtin_apply}
3284 (@pxref{Constructing Calls}).
3286 @item model (@var{model-name})
3287 @cindex function addressability on the M32R/D
3288 @cindex variable addressability on the IA-64
3290 On the M32R/D, use this attribute to set the addressability of an
3291 object, and of the code generated for a function. The identifier
3292 @var{model-name} is one of @code{small}, @code{medium}, or
3293 @code{large}, representing each of the code models.
3295 Small model objects live in the lower 16MB of memory (so that their
3296 addresses can be loaded with the @code{ld24} instruction), and are
3297 callable with the @code{bl} instruction.
3299 Medium model objects may live anywhere in the 32-bit address space (the
3300 compiler generates @code{seth/add3} instructions to load their addresses),
3301 and are callable with the @code{bl} instruction.
3303 Large model objects may live anywhere in the 32-bit address space (the
3304 compiler generates @code{seth/add3} instructions to load their addresses),
3305 and may not be reachable with the @code{bl} instruction (the compiler
3306 generates the much slower @code{seth/add3/jl} instruction sequence).
3308 On IA-64, use this attribute to set the addressability of an object.
3309 At present, the only supported identifier for @var{model-name} is
3310 @code{small}, indicating addressability via ``small'' (22-bit)
3311 addresses (so that their addresses can be loaded with the @code{addl}
3312 instruction). Caveat: such addressing is by definition not position
3313 independent and hence this attribute must not be used for objects
3314 defined by shared libraries.
3316 @item ms_abi/sysv_abi
3317 @cindex @code{ms_abi} attribute
3318 @cindex @code{sysv_abi} attribute
3320 On 32-bit and 64-bit (i?86|x86_64)-*-* targets, you can use an ABI attribute
3321 to indicate which calling convention should be used for a function. The
3322 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
3323 while the @code{sysv_abi} attribute tells the compiler to use the ABI
3324 used on GNU/Linux and other systems. The default is to use the Microsoft ABI
3325 when targeting Windows. On all other systems, the default is the x86/AMD ABI.
3327 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
3328 requires the @option{-maccumulate-outgoing-args} option.
3330 @item callee_pop_aggregate_return (@var{number})
3331 @cindex @code{callee_pop_aggregate_return} attribute
3333 On 32-bit i?86-*-* targets, you can use this attribute to control how
3334 aggregates are returned in memory. If the caller is responsible for
3335 popping the hidden pointer together with the rest of the arguments, specify
3336 @var{number} equal to zero. If callee is responsible for popping the
3337 hidden pointer, specify @var{number} equal to one.
3339 The default i386 ABI assumes that the callee pops the
3340 stack for hidden pointer. However, on 32-bit i386 Microsoft Windows targets,
3341 the compiler assumes that the
3342 caller pops the stack for hidden pointer.
3344 @item ms_hook_prologue
3345 @cindex @code{ms_hook_prologue} attribute
3347 On 32-bit i[34567]86-*-* targets and 64-bit x86_64-*-* targets, you can use
3348 this function attribute to make GCC generate the ``hot-patching'' function
3349 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
3352 @item hotpatch [(@var{prologue-halfwords})]
3353 @cindex @code{hotpatch} attribute
3355 On S/390 System z targets, you can use this function attribute to
3356 make GCC generate a ``hot-patching'' function prologue. The
3357 @code{hotpatch} has no effect on funtions that are explicitly
3358 inline. If the @option{-mhotpatch} or @option{-mno-hotpatch}
3359 command-line option is used at the same time, the @code{hotpatch}
3360 attribute takes precedence. If an argument is given, the maximum
3361 allowed value is 1000000.
3364 @cindex function without a prologue/epilogue code
3365 This attribute is available on the ARM, AVR, MCORE, MSP430, NDS32,
3366 RL78, RX and SPU ports. It allows the compiler to construct the
3367 requisite function declaration, while allowing the body of the
3368 function to be assembly code. The specified function will not have
3369 prologue/epilogue sequences generated by the compiler. Only Basic
3370 @code{asm} statements can safely be included in naked functions
3371 (@pxref{Basic Asm}). While using Extended @code{asm} or a mixture of
3372 Basic @code{asm} and ``C'' code may appear to work, they cannot be
3373 depended upon to work reliably and are not supported.
3376 @cindex functions that do not handle memory bank switching on 68HC11/68HC12
3377 On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to
3378 use the normal calling convention based on @code{jsr} and @code{rts}.
3379 This attribute can be used to cancel the effect of the @option{-mlong-calls}
3382 On MeP targets this attribute causes the compiler to assume the called
3383 function is close enough to use the normal calling convention,
3384 overriding the @option{-mtf} command-line option.
3387 @cindex Allow nesting in an interrupt handler on the Blackfin processor.
3388 Use this attribute together with @code{interrupt_handler},
3389 @code{exception_handler} or @code{nmi_handler} to indicate that the function
3390 entry code should enable nested interrupts or exceptions.
3393 @cindex NMI handler functions on the Blackfin processor
3394 Use this attribute on the Blackfin to indicate that the specified function
3395 is an NMI handler. The compiler generates function entry and
3396 exit sequences suitable for use in an NMI handler when this
3397 attribute is present.
3400 @cindex @code{nocompression} attribute
3401 On MIPS targets, you can use the @code{nocompression} function attribute
3402 to locally turn off MIPS16 and microMIPS code generation. This attribute
3403 overrides the @option{-mips16} and @option{-mmicromips} options on the
3404 command line (@pxref{MIPS Options}).
3406 @item no_instrument_function
3407 @cindex @code{no_instrument_function} function attribute
3408 @opindex finstrument-functions
3409 If @option{-finstrument-functions} is given, profiling function calls are
3410 generated at entry and exit of most user-compiled functions.
3411 Functions with this attribute are not so instrumented.
3413 @item no_split_stack
3414 @cindex @code{no_split_stack} function attribute
3415 @opindex fsplit-stack
3416 If @option{-fsplit-stack} is given, functions have a small
3417 prologue which decides whether to split the stack. Functions with the
3418 @code{no_split_stack} attribute do not have that prologue, and thus
3419 may run with only a small amount of stack space available.
3422 @cindex @code{noinline} function attribute
3423 This function attribute prevents a function from being considered for
3425 @c Don't enumerate the optimizations by name here; we try to be
3426 @c future-compatible with this mechanism.
3427 If the function does not have side-effects, there are optimizations
3428 other than inlining that cause function calls to be optimized away,
3429 although the function call is live. To keep such calls from being
3436 (@pxref{Extended Asm}) in the called function, to serve as a special
3440 @cindex @code{noclone} function attribute
3441 This function attribute prevents a function from being considered for
3442 cloning---a mechanism that produces specialized copies of functions
3443 and which is (currently) performed by interprocedural constant
3446 @item nonnull (@var{arg-index}, @dots{})
3447 @cindex @code{nonnull} function attribute
3448 The @code{nonnull} attribute specifies that some function parameters should
3449 be non-null pointers. For instance, the declaration:
3453 my_memcpy (void *dest, const void *src, size_t len)
3454 __attribute__((nonnull (1, 2)));
3458 causes the compiler to check that, in calls to @code{my_memcpy},
3459 arguments @var{dest} and @var{src} are non-null. If the compiler
3460 determines that a null pointer is passed in an argument slot marked
3461 as non-null, and the @option{-Wnonnull} option is enabled, a warning
3462 is issued. The compiler may also choose to make optimizations based
3463 on the knowledge that certain function arguments will never be null.
3465 If no argument index list is given to the @code{nonnull} attribute,
3466 all pointer arguments are marked as non-null. To illustrate, the
3467 following declaration is equivalent to the previous example:
3471 my_memcpy (void *dest, const void *src, size_t len)
3472 __attribute__((nonnull));
3476 @cindex @code{no_reorder} function or variable attribute
3477 Do not reorder functions or variables marked @code{no_reorder}
3478 against each other or top level assembler statements the executable.
3479 The actual order in the program will depend on the linker command
3480 line. Static variables marked like this are also not removed.
3481 This has a similar effect
3482 as the @option{-fno-toplevel-reorder} option, but only applies to the
3485 @item returns_nonnull
3486 @cindex @code{returns_nonnull} function attribute
3487 The @code{returns_nonnull} attribute specifies that the function
3488 return value should be a non-null pointer. For instance, the declaration:
3492 mymalloc (size_t len) __attribute__((returns_nonnull));
3496 lets the compiler optimize callers based on the knowledge
3497 that the return value will never be null.
3500 @cindex @code{noreturn} function attribute
3501 A few standard library functions, such as @code{abort} and @code{exit},
3502 cannot return. GCC knows this automatically. Some programs define
3503 their own functions that never return. You can declare them
3504 @code{noreturn} to tell the compiler this fact. For example,
3508 void fatal () __attribute__ ((noreturn));
3511 fatal (/* @r{@dots{}} */)
3513 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */
3519 The @code{noreturn} keyword tells the compiler to assume that
3520 @code{fatal} cannot return. It can then optimize without regard to what
3521 would happen if @code{fatal} ever did return. This makes slightly
3522 better code. More importantly, it helps avoid spurious warnings of
3523 uninitialized variables.
3525 The @code{noreturn} keyword does not affect the exceptional path when that
3526 applies: a @code{noreturn}-marked function may still return to the caller
3527 by throwing an exception or calling @code{longjmp}.
3529 Do not assume that registers saved by the calling function are
3530 restored before calling the @code{noreturn} function.
3532 It does not make sense for a @code{noreturn} function to have a return
3533 type other than @code{void}.
3535 The attribute @code{noreturn} is not implemented in GCC versions
3536 earlier than 2.5. An alternative way to declare that a function does
3537 not return, which works in the current version and in some older
3538 versions, is as follows:
3541 typedef void voidfn ();
3543 volatile voidfn fatal;
3547 This approach does not work in GNU C++.
3550 @cindex @code{nothrow} function attribute
3551 The @code{nothrow} attribute is used to inform the compiler that a
3552 function cannot throw an exception. For example, most functions in
3553 the standard C library can be guaranteed not to throw an exception
3554 with the notable exceptions of @code{qsort} and @code{bsearch} that
3555 take function pointer arguments. The @code{nothrow} attribute is not
3556 implemented in GCC versions earlier than 3.3.
3558 @item nosave_low_regs
3559 @cindex @code{nosave_low_regs} attribute
3560 Use this attribute on SH targets to indicate that an @code{interrupt_handler}
3561 function should not save and restore registers R0..R7. This can be used on SH3*
3562 and SH4* targets that have a second R0..R7 register bank for non-reentrant
3566 @cindex @code{optimize} function attribute
3567 The @code{optimize} attribute is used to specify that a function is to
3568 be compiled with different optimization options than specified on the
3569 command line. Arguments can either be numbers or strings. Numbers
3570 are assumed to be an optimization level. Strings that begin with
3571 @code{O} are assumed to be an optimization option, while other options
3572 are assumed to be used with a @code{-f} prefix. You can also use the
3573 @samp{#pragma GCC optimize} pragma to set the optimization options
3574 that affect more than one function.
3575 @xref{Function Specific Option Pragmas}, for details about the
3576 @samp{#pragma GCC optimize} pragma.
3578 This can be used for instance to have frequently-executed functions
3579 compiled with more aggressive optimization options that produce faster
3580 and larger code, while other functions can be compiled with less
3583 @item OS_main/OS_task
3584 @cindex @code{OS_main} AVR function attribute
3585 @cindex @code{OS_task} AVR function attribute
3586 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
3587 do not save/restore any call-saved register in their prologue/epilogue.
3589 The @code{OS_main} attribute can be used when there @emph{is
3590 guarantee} that interrupts are disabled at the time when the function
3591 is entered. This saves resources when the stack pointer has to be
3592 changed to set up a frame for local variables.
3594 The @code{OS_task} attribute can be used when there is @emph{no
3595 guarantee} that interrupts are disabled at that time when the function
3596 is entered like for, e@.g@. task functions in a multi-threading operating
3597 system. In that case, changing the stack pointer register is
3598 guarded by save/clear/restore of the global interrupt enable flag.
3600 The differences to the @code{naked} function attribute are:
3602 @item @code{naked} functions do not have a return instruction whereas
3603 @code{OS_main} and @code{OS_task} functions have a @code{RET} or
3604 @code{RETI} return instruction.
3605 @item @code{naked} functions do not set up a frame for local variables
3606 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
3611 @cindex @code{pcs} function attribute
3613 The @code{pcs} attribute can be used to control the calling convention
3614 used for a function on ARM. The attribute takes an argument that specifies
3615 the calling convention to use.
3617 When compiling using the AAPCS ABI (or a variant of it) then valid
3618 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
3619 order to use a variant other than @code{"aapcs"} then the compiler must
3620 be permitted to use the appropriate co-processor registers (i.e., the
3621 VFP registers must be available in order to use @code{"aapcs-vfp"}).
3625 /* Argument passed in r0, and result returned in r0+r1. */
3626 double f2d (float) __attribute__((pcs("aapcs")));
3629 Variadic functions always use the @code{"aapcs"} calling convention and
3630 the compiler rejects attempts to specify an alternative.
3633 @cindex @code{pure} function attribute
3634 Many functions have no effects except the return value and their
3635 return value depends only on the parameters and/or global variables.
3636 Such a function can be subject
3637 to common subexpression elimination and loop optimization just as an
3638 arithmetic operator would be. These functions should be declared
3639 with the attribute @code{pure}. For example,
3642 int square (int) __attribute__ ((pure));
3646 says that the hypothetical function @code{square} is safe to call
3647 fewer times than the program says.
3649 Some of common examples of pure functions are @code{strlen} or @code{memcmp}.
3650 Interesting non-pure functions are functions with infinite loops or those
3651 depending on volatile memory or other system resource, that may change between
3652 two consecutive calls (such as @code{feof} in a multithreading environment).
3654 The attribute @code{pure} is not implemented in GCC versions earlier
3658 @cindex @code{hot} function attribute
3659 The @code{hot} attribute on a function is used to inform the compiler that
3660 the function is a hot spot of the compiled program. The function is
3661 optimized more aggressively and on many targets it is placed into a special
3662 subsection of the text section so all hot functions appear close together,
3665 When profile feedback is available, via @option{-fprofile-use}, hot functions
3666 are automatically detected and this attribute is ignored.
3668 The @code{hot} attribute on functions is not implemented in GCC versions
3672 @cindex @code{cold} function attribute
3673 The @code{cold} attribute on functions is used to inform the compiler that
3674 the function is unlikely to be executed. The function is optimized for
3675 size rather than speed and on many targets it is placed into a special
3676 subsection of the text section so all cold functions appear close together,
3677 improving code locality of non-cold parts of program. The paths leading
3678 to calls of cold functions within code are marked as unlikely by the branch
3679 prediction mechanism. It is thus useful to mark functions used to handle
3680 unlikely conditions, such as @code{perror}, as cold to improve optimization
3681 of hot functions that do call marked functions in rare occasions.
3683 When profile feedback is available, via @option{-fprofile-use}, cold functions
3684 are automatically detected and this attribute is ignored.
3686 The @code{cold} attribute on functions is not implemented in GCC versions
3689 @item no_sanitize_address
3690 @itemx no_address_safety_analysis
3691 @cindex @code{no_sanitize_address} function attribute
3692 The @code{no_sanitize_address} attribute on functions is used
3693 to inform the compiler that it should not instrument memory accesses
3694 in the function when compiling with the @option{-fsanitize=address} option.
3695 The @code{no_address_safety_analysis} is a deprecated alias of the
3696 @code{no_sanitize_address} attribute, new code should use
3697 @code{no_sanitize_address}.
3699 @item no_sanitize_undefined
3700 @cindex @code{no_sanitize_undefined} function attribute
3701 The @code{no_sanitize_undefined} attribute on functions is used
3702 to inform the compiler that it should not check for undefined behavior
3703 in the function when compiling with the @option{-fsanitize=undefined} option.
3705 @item regparm (@var{number})
3706 @cindex @code{regparm} attribute
3707 @cindex functions that are passed arguments in registers on the 386
3708 On the Intel 386, the @code{regparm} attribute causes the compiler to
3709 pass arguments number one to @var{number} if they are of integral type
3710 in registers EAX, EDX, and ECX instead of on the stack. Functions that
3711 take a variable number of arguments continue to be passed all of their
3712 arguments on the stack.
3714 Beware that on some ELF systems this attribute is unsuitable for
3715 global functions in shared libraries with lazy binding (which is the
3716 default). Lazy binding sends the first call via resolving code in
3717 the loader, which might assume EAX, EDX and ECX can be clobbered, as
3718 per the standard calling conventions. Solaris 8 is affected by this.
3719 Systems with the GNU C Library version 2.1 or higher
3720 and FreeBSD are believed to be
3721 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
3722 disabled with the linker or the loader if desired, to avoid the
3726 @cindex reset handler functions
3727 Use this attribute on the NDS32 target to indicate that the specified function
3728 is a reset handler. The compiler will generate corresponding sections
3729 for use in a reset handler. You can use the following attributes
3730 to provide extra exception handling:
3733 @cindex @code{nmi} attribute
3734 Provide a user-defined function to handle NMI exception.
3736 @cindex @code{warm} attribute
3737 Provide a user-defined function to handle warm reset exception.
3741 @cindex @code{sseregparm} attribute
3742 On the Intel 386 with SSE support, the @code{sseregparm} attribute
3743 causes the compiler to pass up to 3 floating-point arguments in
3744 SSE registers instead of on the stack. Functions that take a
3745 variable number of arguments continue to pass all of their
3746 floating-point arguments on the stack.
3748 @item force_align_arg_pointer
3749 @cindex @code{force_align_arg_pointer} attribute
3750 On the Intel x86, the @code{force_align_arg_pointer} attribute may be
3751 applied to individual function definitions, generating an alternate
3752 prologue and epilogue that realigns the run-time stack if necessary.
3753 This supports mixing legacy codes that run with a 4-byte aligned stack
3754 with modern codes that keep a 16-byte stack for SSE compatibility.
3757 @cindex @code{renesas} attribute
3758 On SH targets this attribute specifies that the function or struct follows the
3762 @cindex @code{resbank} attribute
3763 On the SH2A target, this attribute enables the high-speed register
3764 saving and restoration using a register bank for @code{interrupt_handler}
3765 routines. Saving to the bank is performed automatically after the CPU
3766 accepts an interrupt that uses a register bank.
3768 The nineteen 32-bit registers comprising general register R0 to R14,
3769 control register GBR, and system registers MACH, MACL, and PR and the
3770 vector table address offset are saved into a register bank. Register
3771 banks are stacked in first-in last-out (FILO) sequence. Restoration
3772 from the bank is executed by issuing a RESBANK instruction.
3775 @cindex @code{returns_twice} attribute
3776 The @code{returns_twice} attribute tells the compiler that a function may
3777 return more than one time. The compiler ensures that all registers
3778 are dead before calling such a function and emits a warning about
3779 the variables that may be clobbered after the second return from the
3780 function. Examples of such functions are @code{setjmp} and @code{vfork}.
3781 The @code{longjmp}-like counterpart of such function, if any, might need
3782 to be marked with the @code{noreturn} attribute.
3785 @cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S
3786 Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that
3787 all registers except the stack pointer should be saved in the prologue
3788 regardless of whether they are used or not.
3790 @item save_volatiles
3791 @cindex save volatile registers on the MicroBlaze
3792 Use this attribute on the MicroBlaze to indicate that the function is
3793 an interrupt handler. All volatile registers (in addition to non-volatile
3794 registers) are saved in the function prologue. If the function is a leaf
3795 function, only volatiles used by the function are saved. A normal function
3796 return is generated instead of a return from interrupt.
3799 @cindex break handler functions
3800 Use this attribute on the MicroBlaze ports to indicate that
3801 the specified function is an break handler. The compiler generates function
3802 entry and exit sequences suitable for use in an break handler when this
3803 attribute is present. The return from @code{break_handler} is done through
3804 the @code{rtbd} instead of @code{rtsd}.
3807 void f () __attribute__ ((break_handler));
3810 @item section ("@var{section-name}")
3811 @cindex @code{section} function attribute
3812 Normally, the compiler places the code it generates in the @code{text} section.
3813 Sometimes, however, you need additional sections, or you need certain
3814 particular functions to appear in special sections. The @code{section}
3815 attribute specifies that a function lives in a particular section.
3816 For example, the declaration:
3819 extern void foobar (void) __attribute__ ((section ("bar")));
3823 puts the function @code{foobar} in the @code{bar} section.
3825 Some file formats do not support arbitrary sections so the @code{section}
3826 attribute is not available on all platforms.
3827 If you need to map the entire contents of a module to a particular
3828 section, consider using the facilities of the linker instead.
3831 @cindex @code{sentinel} function attribute
3832 This function attribute ensures that a parameter in a function call is
3833 an explicit @code{NULL}. The attribute is only valid on variadic
3834 functions. By default, the sentinel is located at position zero, the
3835 last parameter of the function call. If an optional integer position
3836 argument P is supplied to the attribute, the sentinel must be located at
3837 position P counting backwards from the end of the argument list.
3840 __attribute__ ((sentinel))
3842 __attribute__ ((sentinel(0)))
3845 The attribute is automatically set with a position of 0 for the built-in
3846 functions @code{execl} and @code{execlp}. The built-in function
3847 @code{execle} has the attribute set with a position of 1.
3849 A valid @code{NULL} in this context is defined as zero with any pointer
3850 type. If your system defines the @code{NULL} macro with an integer type
3851 then you need to add an explicit cast. GCC replaces @code{stddef.h}
3852 with a copy that redefines NULL appropriately.
3854 The warnings for missing or incorrect sentinels are enabled with
3858 See @code{long_call/short_call}.
3861 See @code{longcall/shortcall}.
3864 @cindex interrupt handler functions on the AVR processors
3865 Use this attribute on the AVR to indicate that the specified
3866 function is an interrupt handler. The compiler generates function
3867 entry and exit sequences suitable for use in an interrupt handler when this
3868 attribute is present.
3870 See also the @code{interrupt} function attribute.
3872 The AVR hardware globally disables interrupts when an interrupt is executed.
3873 Interrupt handler functions defined with the @code{signal} attribute
3874 do not re-enable interrupts. It is save to enable interrupts in a
3875 @code{signal} handler. This ``save'' only applies to the code
3876 generated by the compiler and not to the IRQ layout of the
3877 application which is responsibility of the application.
3879 If both @code{signal} and @code{interrupt} are specified for the same
3880 function, @code{signal} is silently ignored.
3883 @cindex @code{sp_switch} attribute
3884 Use this attribute on the SH to indicate an @code{interrupt_handler}
3885 function should switch to an alternate stack. It expects a string
3886 argument that names a global variable holding the address of the
3891 void f () __attribute__ ((interrupt_handler,
3892 sp_switch ("alt_stack")));
3896 @cindex functions that pop the argument stack on the 386
3897 On the Intel 386, the @code{stdcall} attribute causes the compiler to
3898 assume that the called function pops off the stack space used to
3899 pass arguments, unless it takes a variable number of arguments.
3901 @item syscall_linkage
3902 @cindex @code{syscall_linkage} attribute
3903 This attribute is used to modify the IA-64 calling convention by marking
3904 all input registers as live at all function exits. This makes it possible
3905 to restart a system call after an interrupt without having to save/restore
3906 the input registers. This also prevents kernel data from leaking into
3910 @cindex @code{target} function attribute
3911 The @code{target} attribute is used to specify that a function is to
3912 be compiled with different target options than specified on the
3913 command line. This can be used for instance to have functions
3914 compiled with a different ISA (instruction set architecture) than the
3915 default. You can also use the @samp{#pragma GCC target} pragma to set
3916 more than one function to be compiled with specific target options.
3917 @xref{Function Specific Option Pragmas}, for details about the
3918 @samp{#pragma GCC target} pragma.
3920 For instance on a 386, you could compile one function with
3921 @code{target("sse4.1,arch=core2")} and another with
3922 @code{target("sse4a,arch=amdfam10")}. This is equivalent to
3923 compiling the first function with @option{-msse4.1} and
3924 @option{-march=core2} options, and the second function with
3925 @option{-msse4a} and @option{-march=amdfam10} options. It is up to the
3926 user to make sure that a function is only invoked on a machine that
3927 supports the particular ISA it is compiled for (for example by using
3928 @code{cpuid} on 386 to determine what feature bits and architecture
3932 int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
3933 int sse3_func (void) __attribute__ ((__target__ ("sse3")));
3936 You can either use multiple
3937 strings to specify multiple options, or separate the options
3938 with a comma (@samp{,}).
3940 The @code{target} attribute is presently implemented for
3941 i386/x86_64, PowerPC, and Nios II targets only.
3942 The options supported are specific to each target.
3944 On the 386, the following options are allowed:
3949 @cindex @code{target("abm")} attribute
3950 Enable/disable the generation of the advanced bit instructions.
3954 @cindex @code{target("aes")} attribute
3955 Enable/disable the generation of the AES instructions.
3958 @cindex @code{target("default")} attribute
3959 @xref{Function Multiversioning}, where it is used to specify the
3960 default function version.
3964 @cindex @code{target("mmx")} attribute
3965 Enable/disable the generation of the MMX instructions.
3969 @cindex @code{target("pclmul")} attribute
3970 Enable/disable the generation of the PCLMUL instructions.
3974 @cindex @code{target("popcnt")} attribute
3975 Enable/disable the generation of the POPCNT instruction.
3979 @cindex @code{target("sse")} attribute
3980 Enable/disable the generation of the SSE instructions.
3984 @cindex @code{target("sse2")} attribute
3985 Enable/disable the generation of the SSE2 instructions.
3989 @cindex @code{target("sse3")} attribute
3990 Enable/disable the generation of the SSE3 instructions.
3994 @cindex @code{target("sse4")} attribute
3995 Enable/disable the generation of the SSE4 instructions (both SSE4.1
4000 @cindex @code{target("sse4.1")} attribute
4001 Enable/disable the generation of the sse4.1 instructions.
4005 @cindex @code{target("sse4.2")} attribute
4006 Enable/disable the generation of the sse4.2 instructions.
4010 @cindex @code{target("sse4a")} attribute
4011 Enable/disable the generation of the SSE4A instructions.
4015 @cindex @code{target("fma4")} attribute
4016 Enable/disable the generation of the FMA4 instructions.
4020 @cindex @code{target("xop")} attribute
4021 Enable/disable the generation of the XOP instructions.
4025 @cindex @code{target("lwp")} attribute
4026 Enable/disable the generation of the LWP instructions.
4030 @cindex @code{target("ssse3")} attribute
4031 Enable/disable the generation of the SSSE3 instructions.
4035 @cindex @code{target("cld")} attribute
4036 Enable/disable the generation of the CLD before string moves.
4038 @item fancy-math-387
4039 @itemx no-fancy-math-387
4040 @cindex @code{target("fancy-math-387")} attribute
4041 Enable/disable the generation of the @code{sin}, @code{cos}, and
4042 @code{sqrt} instructions on the 387 floating-point unit.
4045 @itemx no-fused-madd
4046 @cindex @code{target("fused-madd")} attribute
4047 Enable/disable the generation of the fused multiply/add instructions.
4051 @cindex @code{target("ieee-fp")} attribute
4052 Enable/disable the generation of floating point that depends on IEEE arithmetic.
4054 @item inline-all-stringops
4055 @itemx no-inline-all-stringops
4056 @cindex @code{target("inline-all-stringops")} attribute
4057 Enable/disable inlining of string operations.
4059 @item inline-stringops-dynamically
4060 @itemx no-inline-stringops-dynamically
4061 @cindex @code{target("inline-stringops-dynamically")} attribute
4062 Enable/disable the generation of the inline code to do small string
4063 operations and calling the library routines for large operations.
4065 @item align-stringops
4066 @itemx no-align-stringops
4067 @cindex @code{target("align-stringops")} attribute
4068 Do/do not align destination of inlined string operations.
4072 @cindex @code{target("recip")} attribute
4073 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
4074 instructions followed an additional Newton-Raphson step instead of
4075 doing a floating-point division.
4077 @item arch=@var{ARCH}
4078 @cindex @code{target("arch=@var{ARCH}")} attribute
4079 Specify the architecture to generate code for in compiling the function.
4081 @item tune=@var{TUNE}
4082 @cindex @code{target("tune=@var{TUNE}")} attribute
4083 Specify the architecture to tune for in compiling the function.
4085 @item fpmath=@var{FPMATH}
4086 @cindex @code{target("fpmath=@var{FPMATH}")} attribute
4087 Specify which floating-point unit to use. The
4088 @code{target("fpmath=sse,387")} option must be specified as
4089 @code{target("fpmath=sse+387")} because the comma would separate
4093 On the PowerPC, the following options are allowed:
4098 @cindex @code{target("altivec")} attribute
4099 Generate code that uses (does not use) AltiVec instructions. In
4100 32-bit code, you cannot enable AltiVec instructions unless
4101 @option{-mabi=altivec} is used on the command line.
4105 @cindex @code{target("cmpb")} attribute
4106 Generate code that uses (does not use) the compare bytes instruction
4107 implemented on the POWER6 processor and other processors that support
4108 the PowerPC V2.05 architecture.
4112 @cindex @code{target("dlmzb")} attribute
4113 Generate code that uses (does not use) the string-search @samp{dlmzb}
4114 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
4115 generated by default when targeting those processors.
4119 @cindex @code{target("fprnd")} attribute
4120 Generate code that uses (does not use) the FP round to integer
4121 instructions implemented on the POWER5+ processor and other processors
4122 that support the PowerPC V2.03 architecture.
4126 @cindex @code{target("hard-dfp")} attribute
4127 Generate code that uses (does not use) the decimal floating-point
4128 instructions implemented on some POWER processors.
4132 @cindex @code{target("isel")} attribute
4133 Generate code that uses (does not use) ISEL instruction.
4137 @cindex @code{target("mfcrf")} attribute
4138 Generate code that uses (does not use) the move from condition
4139 register field instruction implemented on the POWER4 processor and
4140 other processors that support the PowerPC V2.01 architecture.
4144 @cindex @code{target("mfpgpr")} attribute
4145 Generate code that uses (does not use) the FP move to/from general
4146 purpose register instructions implemented on the POWER6X processor and
4147 other processors that support the extended PowerPC V2.05 architecture.
4151 @cindex @code{target("mulhw")} attribute
4152 Generate code that uses (does not use) the half-word multiply and
4153 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
4154 These instructions are generated by default when targeting those
4159 @cindex @code{target("multiple")} attribute
4160 Generate code that uses (does not use) the load multiple word
4161 instructions and the store multiple word instructions.
4165 @cindex @code{target("update")} attribute
4166 Generate code that uses (does not use) the load or store instructions
4167 that update the base register to the address of the calculated memory
4172 @cindex @code{target("popcntb")} attribute
4173 Generate code that uses (does not use) the popcount and double-precision
4174 FP reciprocal estimate instruction implemented on the POWER5
4175 processor and other processors that support the PowerPC V2.02
4180 @cindex @code{target("popcntd")} attribute
4181 Generate code that uses (does not use) the popcount instruction
4182 implemented on the POWER7 processor and other processors that support
4183 the PowerPC V2.06 architecture.
4185 @item powerpc-gfxopt
4186 @itemx no-powerpc-gfxopt
4187 @cindex @code{target("powerpc-gfxopt")} attribute
4188 Generate code that uses (does not use) the optional PowerPC
4189 architecture instructions in the Graphics group, including
4190 floating-point select.
4193 @itemx no-powerpc-gpopt
4194 @cindex @code{target("powerpc-gpopt")} attribute
4195 Generate code that uses (does not use) the optional PowerPC
4196 architecture instructions in the General Purpose group, including
4197 floating-point square root.
4199 @item recip-precision
4200 @itemx no-recip-precision
4201 @cindex @code{target("recip-precision")} attribute
4202 Assume (do not assume) that the reciprocal estimate instructions
4203 provide higher-precision estimates than is mandated by the powerpc
4208 @cindex @code{target("string")} attribute
4209 Generate code that uses (does not use) the load string instructions
4210 and the store string word instructions to save multiple registers and
4211 do small block moves.
4215 @cindex @code{target("vsx")} attribute
4216 Generate code that uses (does not use) vector/scalar (VSX)
4217 instructions, and also enable the use of built-in functions that allow
4218 more direct access to the VSX instruction set. In 32-bit code, you
4219 cannot enable VSX or AltiVec instructions unless
4220 @option{-mabi=altivec} is used on the command line.
4224 @cindex @code{target("friz")} attribute
4225 Generate (do not generate) the @code{friz} instruction when the
4226 @option{-funsafe-math-optimizations} option is used to optimize
4227 rounding a floating-point value to 64-bit integer and back to floating
4228 point. The @code{friz} instruction does not return the same value if
4229 the floating-point number is too large to fit in an integer.
4231 @item avoid-indexed-addresses
4232 @itemx no-avoid-indexed-addresses
4233 @cindex @code{target("avoid-indexed-addresses")} attribute
4234 Generate code that tries to avoid (not avoid) the use of indexed load
4235 or store instructions.
4239 @cindex @code{target("paired")} attribute
4240 Generate code that uses (does not use) the generation of PAIRED simd
4245 @cindex @code{target("longcall")} attribute
4246 Generate code that assumes (does not assume) that all calls are far
4247 away so that a longer more expensive calling sequence is required.
4250 @cindex @code{target("cpu=@var{CPU}")} attribute
4251 Specify the architecture to generate code for when compiling the
4252 function. If you select the @code{target("cpu=power7")} attribute when
4253 generating 32-bit code, VSX and AltiVec instructions are not generated
4254 unless you use the @option{-mabi=altivec} option on the command line.
4256 @item tune=@var{TUNE}
4257 @cindex @code{target("tune=@var{TUNE}")} attribute
4258 Specify the architecture to tune for when compiling the function. If
4259 you do not specify the @code{target("tune=@var{TUNE}")} attribute and
4260 you do specify the @code{target("cpu=@var{CPU}")} attribute,
4261 compilation tunes for the @var{CPU} architecture, and not the
4262 default tuning specified on the command line.
4265 When compiling for Nios II, the following options are allowed:
4268 @item custom-@var{insn}=@var{N}
4269 @itemx no-custom-@var{insn}
4270 @cindex @code{target("custom-@var{insn}=@var{N}")} attribute
4271 @cindex @code{target("no-custom-@var{insn}")} attribute
4272 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
4273 custom instruction with encoding @var{N} when generating code that uses
4274 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
4275 the custom instruction @var{insn}.
4276 These target attributes correspond to the
4277 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
4278 command-line options, and support the same set of @var{insn} keywords.
4279 @xref{Nios II Options}, for more information.
4281 @item custom-fpu-cfg=@var{name}
4282 @cindex @code{target("custom-fpu-cfg=@var{name}")} attribute
4283 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
4284 command-line option, to select a predefined set of custom instructions
4286 @xref{Nios II Options}, for more information.
4289 On the 386/x86_64 and PowerPC back ends, the inliner does not inline a
4290 function that has different target options than the caller, unless the
4291 callee has a subset of the target options of the caller. For example
4292 a function declared with @code{target("sse3")} can inline a function
4293 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
4296 @cindex tiny data section on the H8/300H and H8S
4297 Use this attribute on the H8/300H and H8S to indicate that the specified
4298 variable should be placed into the tiny data section.
4299 The compiler generates more efficient code for loads and stores
4300 on data in the tiny data section. Note the tiny data area is limited to
4301 slightly under 32KB of data.
4304 @cindex @code{trap_exit} attribute
4305 Use this attribute on the SH for an @code{interrupt_handler} to return using
4306 @code{trapa} instead of @code{rte}. This attribute expects an integer
4307 argument specifying the trap number to be used.
4310 @cindex @code{trapa_handler} attribute
4311 On SH targets this function attribute is similar to @code{interrupt_handler}
4312 but it does not save and restore all registers.
4315 @cindex @code{unused} attribute.
4316 This attribute, attached to a function, means that the function is meant
4317 to be possibly unused. GCC does not produce a warning for this
4321 @cindex @code{used} attribute.
4322 This attribute, attached to a function, means that code must be emitted
4323 for the function even if it appears that the function is not referenced.
4324 This is useful, for example, when the function is referenced only in
4327 When applied to a member function of a C++ class template, the
4328 attribute also means that the function is instantiated if the
4329 class itself is instantiated.
4332 @cindex @code{vector} attribute
4333 This RX attribute is similar to the @code{interrupt} attribute, including its
4334 parameters, but does not make the function an interrupt-handler type
4335 function (i.e. it retains the normal C function calling ABI). See the
4336 @code{interrupt} attribute for a description of its arguments.
4339 @cindex @code{version_id} attribute
4340 This IA-64 HP-UX attribute, attached to a global variable or function, renames a
4341 symbol to contain a version string, thus allowing for function level
4342 versioning. HP-UX system header files may use function level versioning
4343 for some system calls.
4346 extern int foo () __attribute__((version_id ("20040821")));
4350 Calls to @var{foo} are mapped to calls to @var{foo@{20040821@}}.
4352 @item visibility ("@var{visibility_type}")
4353 @cindex @code{visibility} attribute
4354 This attribute affects the linkage of the declaration to which it is attached.
4355 There are four supported @var{visibility_type} values: default,
4356 hidden, protected or internal visibility.
4359 void __attribute__ ((visibility ("protected")))
4360 f () @{ /* @r{Do something.} */; @}
4361 int i __attribute__ ((visibility ("hidden")));
4364 The possible values of @var{visibility_type} correspond to the
4365 visibility settings in the ELF gABI.
4368 @c keep this list of visibilities in alphabetical order.
4371 Default visibility is the normal case for the object file format.
4372 This value is available for the visibility attribute to override other
4373 options that may change the assumed visibility of entities.
4375 On ELF, default visibility means that the declaration is visible to other
4376 modules and, in shared libraries, means that the declared entity may be
4379 On Darwin, default visibility means that the declaration is visible to
4382 Default visibility corresponds to ``external linkage'' in the language.
4385 Hidden visibility indicates that the entity declared has a new
4386 form of linkage, which we call ``hidden linkage''. Two
4387 declarations of an object with hidden linkage refer to the same object
4388 if they are in the same shared object.
4391 Internal visibility is like hidden visibility, but with additional
4392 processor specific semantics. Unless otherwise specified by the
4393 psABI, GCC defines internal visibility to mean that a function is
4394 @emph{never} called from another module. Compare this with hidden
4395 functions which, while they cannot be referenced directly by other
4396 modules, can be referenced indirectly via function pointers. By
4397 indicating that a function cannot be called from outside the module,
4398 GCC may for instance omit the load of a PIC register since it is known
4399 that the calling function loaded the correct value.
4402 Protected visibility is like default visibility except that it
4403 indicates that references within the defining module bind to the
4404 definition in that module. That is, the declared entity cannot be
4405 overridden by another module.
4409 All visibilities are supported on many, but not all, ELF targets
4410 (supported when the assembler supports the @samp{.visibility}
4411 pseudo-op). Default visibility is supported everywhere. Hidden
4412 visibility is supported on Darwin targets.
4414 The visibility attribute should be applied only to declarations that
4415 would otherwise have external linkage. The attribute should be applied
4416 consistently, so that the same entity should not be declared with
4417 different settings of the attribute.
4419 In C++, the visibility attribute applies to types as well as functions
4420 and objects, because in C++ types have linkage. A class must not have
4421 greater visibility than its non-static data member types and bases,
4422 and class members default to the visibility of their class. Also, a
4423 declaration without explicit visibility is limited to the visibility
4426 In C++, you can mark member functions and static member variables of a
4427 class with the visibility attribute. This is useful if you know a
4428 particular method or static member variable should only be used from
4429 one shared object; then you can mark it hidden while the rest of the
4430 class has default visibility. Care must be taken to avoid breaking
4431 the One Definition Rule; for example, it is usually not useful to mark
4432 an inline method as hidden without marking the whole class as hidden.
4434 A C++ namespace declaration can also have the visibility attribute.
4437 namespace nspace1 __attribute__ ((visibility ("protected")))
4438 @{ /* @r{Do something.} */; @}
4441 This attribute applies only to the particular namespace body, not to
4442 other definitions of the same namespace; it is equivalent to using
4443 @samp{#pragma GCC visibility} before and after the namespace
4444 definition (@pxref{Visibility Pragmas}).
4446 In C++, if a template argument has limited visibility, this
4447 restriction is implicitly propagated to the template instantiation.
4448 Otherwise, template instantiations and specializations default to the
4449 visibility of their template.
4451 If both the template and enclosing class have explicit visibility, the
4452 visibility from the template is used.
4455 @cindex @code{vliw} attribute
4456 On MeP, the @code{vliw} attribute tells the compiler to emit
4457 instructions in VLIW mode instead of core mode. Note that this
4458 attribute is not allowed unless a VLIW coprocessor has been configured
4459 and enabled through command-line options.
4461 @item warn_unused_result
4462 @cindex @code{warn_unused_result} attribute
4463 The @code{warn_unused_result} attribute causes a warning to be emitted
4464 if a caller of the function with this attribute does not use its
4465 return value. This is useful for functions where not checking
4466 the result is either a security problem or always a bug, such as
4470 int fn () __attribute__ ((warn_unused_result));
4473 if (fn () < 0) return -1;
4480 results in warning on line 5.
4483 @cindex @code{weak} attribute
4484 The @code{weak} attribute causes the declaration to be emitted as a weak
4485 symbol rather than a global. This is primarily useful in defining
4486 library functions that can be overridden in user code, though it can
4487 also be used with non-function declarations. Weak symbols are supported
4488 for ELF targets, and also for a.out targets when using the GNU assembler
4492 @itemx weakref ("@var{target}")
4493 @cindex @code{weakref} attribute
4494 The @code{weakref} attribute marks a declaration as a weak reference.
4495 Without arguments, it should be accompanied by an @code{alias} attribute
4496 naming the target symbol. Optionally, the @var{target} may be given as
4497 an argument to @code{weakref} itself. In either case, @code{weakref}
4498 implicitly marks the declaration as @code{weak}. Without a
4499 @var{target}, given as an argument to @code{weakref} or to @code{alias},
4500 @code{weakref} is equivalent to @code{weak}.
4503 static int x() __attribute__ ((weakref ("y")));
4504 /* is equivalent to... */
4505 static int x() __attribute__ ((weak, weakref, alias ("y")));
4507 static int x() __attribute__ ((weakref));
4508 static int x() __attribute__ ((alias ("y")));
4511 A weak reference is an alias that does not by itself require a
4512 definition to be given for the target symbol. If the target symbol is
4513 only referenced through weak references, then it becomes a @code{weak}
4514 undefined symbol. If it is directly referenced, however, then such
4515 strong references prevail, and a definition is required for the
4516 symbol, not necessarily in the same translation unit.
4518 The effect is equivalent to moving all references to the alias to a
4519 separate translation unit, renaming the alias to the aliased symbol,
4520 declaring it as weak, compiling the two separate translation units and
4521 performing a reloadable link on them.
4523 At present, a declaration to which @code{weakref} is attached can
4524 only be @code{static}.
4528 You can specify multiple attributes in a declaration by separating them
4529 by commas within the double parentheses or by immediately following an
4530 attribute declaration with another attribute declaration.
4532 @cindex @code{#pragma}, reason for not using
4533 @cindex pragma, reason for not using
4534 Some people object to the @code{__attribute__} feature, suggesting that
4535 ISO C's @code{#pragma} should be used instead. At the time
4536 @code{__attribute__} was designed, there were two reasons for not doing
4541 It is impossible to generate @code{#pragma} commands from a macro.
4544 There is no telling what the same @code{#pragma} might mean in another
4548 These two reasons applied to almost any application that might have been
4549 proposed for @code{#pragma}. It was basically a mistake to use
4550 @code{#pragma} for @emph{anything}.
4552 The ISO C99 standard includes @code{_Pragma}, which now allows pragmas
4553 to be generated from macros. In addition, a @code{#pragma GCC}
4554 namespace is now in use for GCC-specific pragmas. However, it has been
4555 found convenient to use @code{__attribute__} to achieve a natural
4556 attachment of attributes to their corresponding declarations, whereas
4557 @code{#pragma GCC} is of use for constructs that do not naturally form
4558 part of the grammar. @xref{Pragmas,,Pragmas Accepted by GCC}.
4560 @node Label Attributes
4561 @section Label Attributes
4562 @cindex Label Attributes
4564 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
4565 details of the exact syntax for using attributes. Other attributes are
4566 available for functions (@pxref{Function Attributes}), variables
4567 (@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}).
4569 This example uses the @code{cold} label attribute to indicate the
4570 @code{ErrorHandling} branch is unlikely to be taken and that the
4571 @code{ErrorHandling} label is unused:
4575 asm goto ("some asm" : : : : NoError);
4577 /* This branch (the fallthru from the asm) is less commonly used */
4579 __attribute__((cold, unused)); /* Semi-colon is required here */
4584 printf("no error\n");
4590 @cindex @code{unused} label attribute
4591 This feature is intended for program-generated code that may contain
4592 unused labels, but which is compiled with @option{-Wall}. It is
4593 not normally appropriate to use in it human-written code, though it
4594 could be useful in cases where the code that jumps to the label is
4595 contained within an @code{#ifdef} conditional.
4598 @cindex @code{hot} label attribute
4599 The @code{hot} attribute on a label is used to inform the compiler that
4600 the path following the label is more likely than paths that are not so
4601 annotated. This attribute is used in cases where @code{__builtin_expect}
4602 cannot be used, for instance with computed goto or @code{asm goto}.
4604 The @code{hot} attribute on labels is not implemented in GCC versions
4608 @cindex @code{cold} label attribute
4609 The @code{cold} attribute on labels is used to inform the compiler that
4610 the path following the label is unlikely to be executed. This attribute
4611 is used in cases where @code{__builtin_expect} cannot be used, for instance
4612 with computed goto or @code{asm goto}.
4614 The @code{cold} attribute on labels is not implemented in GCC versions
4619 @node Attribute Syntax
4620 @section Attribute Syntax
4621 @cindex attribute syntax
4623 This section describes the syntax with which @code{__attribute__} may be
4624 used, and the constructs to which attribute specifiers bind, for the C
4625 language. Some details may vary for C++ and Objective-C@. Because of
4626 infelicities in the grammar for attributes, some forms described here
4627 may not be successfully parsed in all cases.
4629 There are some problems with the semantics of attributes in C++. For
4630 example, there are no manglings for attributes, although they may affect
4631 code generation, so problems may arise when attributed types are used in
4632 conjunction with templates or overloading. Similarly, @code{typeid}
4633 does not distinguish between types with different attributes. Support
4634 for attributes in C++ may be restricted in future to attributes on
4635 declarations only, but not on nested declarators.
4637 @xref{Function Attributes}, for details of the semantics of attributes
4638 applying to functions. @xref{Variable Attributes}, for details of the
4639 semantics of attributes applying to variables. @xref{Type Attributes},
4640 for details of the semantics of attributes applying to structure, union
4641 and enumerated types.
4642 @xref{Label Attributes}, for details of the semantics of attributes
4645 An @dfn{attribute specifier} is of the form
4646 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
4647 is a possibly empty comma-separated sequence of @dfn{attributes}, where
4648 each attribute is one of the following:
4652 Empty. Empty attributes are ignored.
4655 A word (which may be an identifier such as @code{unused}, or a reserved
4656 word such as @code{const}).
4659 A word, followed by, in parentheses, parameters for the attribute.
4660 These parameters take one of the following forms:
4664 An identifier. For example, @code{mode} attributes use this form.
4667 An identifier followed by a comma and a non-empty comma-separated list
4668 of expressions. For example, @code{format} attributes use this form.
4671 A possibly empty comma-separated list of expressions. For example,
4672 @code{format_arg} attributes use this form with the list being a single
4673 integer constant expression, and @code{alias} attributes use this form
4674 with the list being a single string constant.
4678 An @dfn{attribute specifier list} is a sequence of one or more attribute
4679 specifiers, not separated by any other tokens.
4681 @subsubheading Label Attributes
4683 In GNU C, an attribute specifier list may appear after the colon following a
4684 label, other than a @code{case} or @code{default} label. GNU C++ only permits
4685 attributes on labels if the attribute specifier is immediately
4686 followed by a semicolon (i.e., the label applies to an empty
4687 statement). If the semicolon is missing, C++ label attributes are
4688 ambiguous, as it is permissible for a declaration, which could begin
4689 with an attribute list, to be labelled in C++. Declarations cannot be
4690 labelled in C90 or C99, so the ambiguity does not arise there.
4692 @subsubheading Type Attributes
4694 An attribute specifier list may appear as part of a @code{struct},
4695 @code{union} or @code{enum} specifier. It may go either immediately
4696 after the @code{struct}, @code{union} or @code{enum} keyword, or after
4697 the closing brace. The former syntax is preferred.
4698 Where attribute specifiers follow the closing brace, they are considered
4699 to relate to the structure, union or enumerated type defined, not to any
4700 enclosing declaration the type specifier appears in, and the type
4701 defined is not complete until after the attribute specifiers.
4702 @c Otherwise, there would be the following problems: a shift/reduce
4703 @c conflict between attributes binding the struct/union/enum and
4704 @c binding to the list of specifiers/qualifiers; and "aligned"
4705 @c attributes could use sizeof for the structure, but the size could be
4706 @c changed later by "packed" attributes.
4709 @subsubheading All other attributes
4711 Otherwise, an attribute specifier appears as part of a declaration,
4712 counting declarations of unnamed parameters and type names, and relates
4713 to that declaration (which may be nested in another declaration, for
4714 example in the case of a parameter declaration), or to a particular declarator
4715 within a declaration. Where an
4716 attribute specifier is applied to a parameter declared as a function or
4717 an array, it should apply to the function or array rather than the
4718 pointer to which the parameter is implicitly converted, but this is not
4719 yet correctly implemented.
4721 Any list of specifiers and qualifiers at the start of a declaration may
4722 contain attribute specifiers, whether or not such a list may in that
4723 context contain storage class specifiers. (Some attributes, however,
4724 are essentially in the nature of storage class specifiers, and only make
4725 sense where storage class specifiers may be used; for example,
4726 @code{section}.) There is one necessary limitation to this syntax: the
4727 first old-style parameter declaration in a function definition cannot
4728 begin with an attribute specifier, because such an attribute applies to
4729 the function instead by syntax described below (which, however, is not
4730 yet implemented in this case). In some other cases, attribute
4731 specifiers are permitted by this grammar but not yet supported by the
4732 compiler. All attribute specifiers in this place relate to the
4733 declaration as a whole. In the obsolescent usage where a type of
4734 @code{int} is implied by the absence of type specifiers, such a list of
4735 specifiers and qualifiers may be an attribute specifier list with no
4736 other specifiers or qualifiers.
4738 At present, the first parameter in a function prototype must have some
4739 type specifier that is not an attribute specifier; this resolves an
4740 ambiguity in the interpretation of @code{void f(int
4741 (__attribute__((foo)) x))}, but is subject to change. At present, if
4742 the parentheses of a function declarator contain only attributes then
4743 those attributes are ignored, rather than yielding an error or warning
4744 or implying a single parameter of type int, but this is subject to
4747 An attribute specifier list may appear immediately before a declarator
4748 (other than the first) in a comma-separated list of declarators in a
4749 declaration of more than one identifier using a single list of
4750 specifiers and qualifiers. Such attribute specifiers apply
4751 only to the identifier before whose declarator they appear. For
4755 __attribute__((noreturn)) void d0 (void),
4756 __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
4761 the @code{noreturn} attribute applies to all the functions
4762 declared; the @code{format} attribute only applies to @code{d1}.
4764 An attribute specifier list may appear immediately before the comma,
4765 @code{=} or semicolon terminating the declaration of an identifier other
4766 than a function definition. Such attribute specifiers apply
4767 to the declared object or function. Where an
4768 assembler name for an object or function is specified (@pxref{Asm
4769 Labels}), the attribute must follow the @code{asm}
4772 An attribute specifier list may, in future, be permitted to appear after
4773 the declarator in a function definition (before any old-style parameter
4774 declarations or the function body).
4776 Attribute specifiers may be mixed with type qualifiers appearing inside
4777 the @code{[]} of a parameter array declarator, in the C99 construct by
4778 which such qualifiers are applied to the pointer to which the array is
4779 implicitly converted. Such attribute specifiers apply to the pointer,
4780 not to the array, but at present this is not implemented and they are
4783 An attribute specifier list may appear at the start of a nested
4784 declarator. At present, there are some limitations in this usage: the
4785 attributes correctly apply to the declarator, but for most individual
4786 attributes the semantics this implies are not implemented.
4787 When attribute specifiers follow the @code{*} of a pointer
4788 declarator, they may be mixed with any type qualifiers present.
4789 The following describes the formal semantics of this syntax. It makes the
4790 most sense if you are familiar with the formal specification of
4791 declarators in the ISO C standard.
4793 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T
4794 D1}, where @code{T} contains declaration specifiers that specify a type
4795 @var{Type} (such as @code{int}) and @code{D1} is a declarator that
4796 contains an identifier @var{ident}. The type specified for @var{ident}
4797 for derived declarators whose type does not include an attribute
4798 specifier is as in the ISO C standard.
4800 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )},
4801 and the declaration @code{T D} specifies the type
4802 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
4803 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
4804 @var{attribute-specifier-list} @var{Type}'' for @var{ident}.
4806 If @code{D1} has the form @code{*
4807 @var{type-qualifier-and-attribute-specifier-list} D}, and the
4808 declaration @code{T D} specifies the type
4809 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then
4810 @code{T D1} specifies the type ``@var{derived-declarator-type-list}
4811 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for
4817 void (__attribute__((noreturn)) ****f) (void);
4821 specifies the type ``pointer to pointer to pointer to pointer to
4822 non-returning function returning @code{void}''. As another example,
4825 char *__attribute__((aligned(8))) *f;
4829 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''.
4830 Note again that this does not work with most attributes; for example,
4831 the usage of @samp{aligned} and @samp{noreturn} attributes given above
4832 is not yet supported.
4834 For compatibility with existing code written for compiler versions that
4835 did not implement attributes on nested declarators, some laxity is
4836 allowed in the placing of attributes. If an attribute that only applies
4837 to types is applied to a declaration, it is treated as applying to
4838 the type of that declaration. If an attribute that only applies to
4839 declarations is applied to the type of a declaration, it is treated
4840 as applying to that declaration; and, for compatibility with code
4841 placing the attributes immediately before the identifier declared, such
4842 an attribute applied to a function return type is treated as
4843 applying to the function type, and such an attribute applied to an array
4844 element type is treated as applying to the array type. If an
4845 attribute that only applies to function types is applied to a
4846 pointer-to-function type, it is treated as applying to the pointer
4847 target type; if such an attribute is applied to a function return type
4848 that is not a pointer-to-function type, it is treated as applying
4849 to the function type.
4851 @node Function Prototypes
4852 @section Prototypes and Old-Style Function Definitions
4853 @cindex function prototype declarations
4854 @cindex old-style function definitions
4855 @cindex promotion of formal parameters
4857 GNU C extends ISO C to allow a function prototype to override a later
4858 old-style non-prototype definition. Consider the following example:
4861 /* @r{Use prototypes unless the compiler is old-fashioned.} */
4868 /* @r{Prototype function declaration.} */
4869 int isroot P((uid_t));
4871 /* @r{Old-style function definition.} */
4873 isroot (x) /* @r{??? lossage here ???} */
4880 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does
4881 not allow this example, because subword arguments in old-style
4882 non-prototype definitions are promoted. Therefore in this example the
4883 function definition's argument is really an @code{int}, which does not
4884 match the prototype argument type of @code{short}.
4886 This restriction of ISO C makes it hard to write code that is portable
4887 to traditional C compilers, because the programmer does not know
4888 whether the @code{uid_t} type is @code{short}, @code{int}, or
4889 @code{long}. Therefore, in cases like these GNU C allows a prototype
4890 to override a later old-style definition. More precisely, in GNU C, a
4891 function prototype argument type overrides the argument type specified
4892 by a later old-style definition if the former type is the same as the
4893 latter type before promotion. Thus in GNU C the above example is
4894 equivalent to the following:
4907 GNU C++ does not support old-style function definitions, so this
4908 extension is irrelevant.
4911 @section C++ Style Comments
4913 @cindex C++ comments
4914 @cindex comments, C++ style
4916 In GNU C, you may use C++ style comments, which start with @samp{//} and
4917 continue until the end of the line. Many other C implementations allow
4918 such comments, and they are included in the 1999 C standard. However,
4919 C++ style comments are not recognized if you specify an @option{-std}
4920 option specifying a version of ISO C before C99, or @option{-ansi}
4921 (equivalent to @option{-std=c90}).
4924 @section Dollar Signs in Identifier Names
4926 @cindex dollar signs in identifier names
4927 @cindex identifier names, dollar signs in
4929 In GNU C, you may normally use dollar signs in identifier names.
4930 This is because many traditional C implementations allow such identifiers.
4931 However, dollar signs in identifiers are not supported on a few target
4932 machines, typically because the target assembler does not allow them.
4934 @node Character Escapes
4935 @section The Character @key{ESC} in Constants
4937 You can use the sequence @samp{\e} in a string or character constant to
4938 stand for the ASCII character @key{ESC}.
4940 @node Variable Attributes
4941 @section Specifying Attributes of Variables
4942 @cindex attribute of variables
4943 @cindex variable attributes
4945 The keyword @code{__attribute__} allows you to specify special
4946 attributes of variables or structure fields. This keyword is followed
4947 by an attribute specification inside double parentheses. Some
4948 attributes are currently defined generically for variables.
4949 Other attributes are defined for variables on particular target
4950 systems. Other attributes are available for functions
4951 (@pxref{Function Attributes}), labels (@pxref{Label Attributes}) and for
4952 types (@pxref{Type Attributes}).
4953 Other front ends might define more attributes
4954 (@pxref{C++ Extensions,,Extensions to the C++ Language}).
4956 You may also specify attributes with @samp{__} preceding and following
4957 each keyword. This allows you to use them in header files without
4958 being concerned about a possible macro of the same name. For example,
4959 you may use @code{__aligned__} instead of @code{aligned}.
4961 @xref{Attribute Syntax}, for details of the exact syntax for using
4965 @cindex @code{aligned} attribute
4966 @item aligned (@var{alignment})
4967 This attribute specifies a minimum alignment for the variable or
4968 structure field, measured in bytes. For example, the declaration:
4971 int x __attribute__ ((aligned (16))) = 0;
4975 causes the compiler to allocate the global variable @code{x} on a
4976 16-byte boundary. On a 68040, this could be used in conjunction with
4977 an @code{asm} expression to access the @code{move16} instruction which
4978 requires 16-byte aligned operands.
4980 You can also specify the alignment of structure fields. For example, to
4981 create a double-word aligned @code{int} pair, you could write:
4984 struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
4988 This is an alternative to creating a union with a @code{double} member,
4989 which forces the union to be double-word aligned.
4991 As in the preceding examples, you can explicitly specify the alignment
4992 (in bytes) that you wish the compiler to use for a given variable or
4993 structure field. Alternatively, you can leave out the alignment factor
4994 and just ask the compiler to align a variable or field to the
4995 default alignment for the target architecture you are compiling for.
4996 The default alignment is sufficient for all scalar types, but may not be
4997 enough for all vector types on a target that supports vector operations.
4998 The default alignment is fixed for a particular target ABI.
5000 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
5001 which is the largest alignment ever used for any data type on the
5002 target machine you are compiling for. For example, you could write:
5005 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
5008 The compiler automatically sets the alignment for the declared
5009 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
5010 often make copy operations more efficient, because the compiler can
5011 use whatever instructions copy the biggest chunks of memory when
5012 performing copies to or from the variables or fields that you have
5013 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
5014 may change depending on command-line options.
5016 When used on a struct, or struct member, the @code{aligned} attribute can
5017 only increase the alignment; in order to decrease it, the @code{packed}
5018 attribute must be specified as well. When used as part of a typedef, the
5019 @code{aligned} attribute can both increase and decrease alignment, and
5020 specifying the @code{packed} attribute generates a warning.
5022 Note that the effectiveness of @code{aligned} attributes may be limited
5023 by inherent limitations in your linker. On many systems, the linker is
5024 only able to arrange for variables to be aligned up to a certain maximum
5025 alignment. (For some linkers, the maximum supported alignment may
5026 be very very small.) If your linker is only able to align variables
5027 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
5028 in an @code{__attribute__} still only provides you with 8-byte
5029 alignment. See your linker documentation for further information.
5031 The @code{aligned} attribute can also be used for functions
5032 (@pxref{Function Attributes}.)
5034 @item cleanup (@var{cleanup_function})
5035 @cindex @code{cleanup} attribute
5036 The @code{cleanup} attribute runs a function when the variable goes
5037 out of scope. This attribute can only be applied to auto function
5038 scope variables; it may not be applied to parameters or variables
5039 with static storage duration. The function must take one parameter,
5040 a pointer to a type compatible with the variable. The return value
5041 of the function (if any) is ignored.
5043 If @option{-fexceptions} is enabled, then @var{cleanup_function}
5044 is run during the stack unwinding that happens during the
5045 processing of the exception. Note that the @code{cleanup} attribute
5046 does not allow the exception to be caught, only to perform an action.
5047 It is undefined what happens if @var{cleanup_function} does not
5052 @cindex @code{common} attribute
5053 @cindex @code{nocommon} attribute
5056 The @code{common} attribute requests GCC to place a variable in
5057 ``common'' storage. The @code{nocommon} attribute requests the
5058 opposite---to allocate space for it directly.
5060 These attributes override the default chosen by the
5061 @option{-fno-common} and @option{-fcommon} flags respectively.
5064 @itemx deprecated (@var{msg})
5065 @cindex @code{deprecated} attribute
5066 The @code{deprecated} attribute results in a warning if the variable
5067 is used anywhere in the source file. This is useful when identifying
5068 variables that are expected to be removed in a future version of a
5069 program. The warning also includes the location of the declaration
5070 of the deprecated variable, to enable users to easily find further
5071 information about why the variable is deprecated, or what they should
5072 do instead. Note that the warning only occurs for uses:
5075 extern int old_var __attribute__ ((deprecated));
5077 int new_fn () @{ return old_var; @}
5081 results in a warning on line 3 but not line 2. The optional @var{msg}
5082 argument, which must be a string, is printed in the warning if
5085 The @code{deprecated} attribute can also be used for functions and
5086 types (@pxref{Function Attributes}, @pxref{Type Attributes}.)
5088 @item mode (@var{mode})
5089 @cindex @code{mode} attribute
5090 This attribute specifies the data type for the declaration---whichever
5091 type corresponds to the mode @var{mode}. This in effect lets you
5092 request an integer or floating-point type according to its width.
5094 You may also specify a mode of @code{byte} or @code{__byte__} to
5095 indicate the mode corresponding to a one-byte integer, @code{word} or
5096 @code{__word__} for the mode of a one-word integer, and @code{pointer}
5097 or @code{__pointer__} for the mode used to represent pointers.
5100 @cindex @code{packed} attribute
5101 The @code{packed} attribute specifies that a variable or structure field
5102 should have the smallest possible alignment---one byte for a variable,
5103 and one bit for a field, unless you specify a larger value with the
5104 @code{aligned} attribute.
5106 Here is a structure in which the field @code{x} is packed, so that it
5107 immediately follows @code{a}:
5113 int x[2] __attribute__ ((packed));
5117 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
5118 @code{packed} attribute on bit-fields of type @code{char}. This has
5119 been fixed in GCC 4.4 but the change can lead to differences in the
5120 structure layout. See the documentation of
5121 @option{-Wpacked-bitfield-compat} for more information.
5123 @item section ("@var{section-name}")
5124 @cindex @code{section} variable attribute
5125 Normally, the compiler places the objects it generates in sections like
5126 @code{data} and @code{bss}. Sometimes, however, you need additional sections,
5127 or you need certain particular variables to appear in special sections,
5128 for example to map to special hardware. The @code{section}
5129 attribute specifies that a variable (or function) lives in a particular
5130 section. For example, this small program uses several specific section names:
5133 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
5134 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
5135 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
5136 int init_data __attribute__ ((section ("INITDATA")));
5140 /* @r{Initialize stack pointer} */
5141 init_sp (stack + sizeof (stack));
5143 /* @r{Initialize initialized data} */
5144 memcpy (&init_data, &data, &edata - &data);
5146 /* @r{Turn on the serial ports} */
5153 Use the @code{section} attribute with
5154 @emph{global} variables and not @emph{local} variables,
5155 as shown in the example.
5157 You may use the @code{section} attribute with initialized or
5158 uninitialized global variables but the linker requires
5159 each object be defined once, with the exception that uninitialized
5160 variables tentatively go in the @code{common} (or @code{bss}) section
5161 and can be multiply ``defined''. Using the @code{section} attribute
5162 changes what section the variable goes into and may cause the
5163 linker to issue an error if an uninitialized variable has multiple
5164 definitions. You can force a variable to be initialized with the
5165 @option{-fno-common} flag or the @code{nocommon} attribute.
5167 Some file formats do not support arbitrary sections so the @code{section}
5168 attribute is not available on all platforms.
5169 If you need to map the entire contents of a module to a particular
5170 section, consider using the facilities of the linker instead.
5173 @cindex @code{shared} variable attribute
5174 On Microsoft Windows, in addition to putting variable definitions in a named
5175 section, the section can also be shared among all running copies of an
5176 executable or DLL@. For example, this small program defines shared data
5177 by putting it in a named section @code{shared} and marking the section
5181 int foo __attribute__((section ("shared"), shared)) = 0;
5186 /* @r{Read and write foo. All running
5187 copies see the same value.} */
5193 You may only use the @code{shared} attribute along with @code{section}
5194 attribute with a fully-initialized global definition because of the way
5195 linkers work. See @code{section} attribute for more information.
5197 The @code{shared} attribute is only available on Microsoft Windows@.
5199 @item tls_model ("@var{tls_model}")
5200 @cindex @code{tls_model} attribute
5201 The @code{tls_model} attribute sets thread-local storage model
5202 (@pxref{Thread-Local}) of a particular @code{__thread} variable,
5203 overriding @option{-ftls-model=} command-line switch on a per-variable
5205 The @var{tls_model} argument should be one of @code{global-dynamic},
5206 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
5208 Not all targets support this attribute.
5211 This attribute, attached to a variable, means that the variable is meant
5212 to be possibly unused. GCC does not produce a warning for this
5216 This attribute, attached to a variable with the static storage, means that
5217 the variable must be emitted even if it appears that the variable is not
5220 When applied to a static data member of a C++ class template, the
5221 attribute also means that the member is instantiated if the
5222 class itself is instantiated.
5224 @item vector_size (@var{bytes})
5225 This attribute specifies the vector size for the variable, measured in
5226 bytes. For example, the declaration:
5229 int foo __attribute__ ((vector_size (16)));
5233 causes the compiler to set the mode for @code{foo}, to be 16 bytes,
5234 divided into @code{int} sized units. Assuming a 32-bit int (a vector of
5235 4 units of 4 bytes), the corresponding mode of @code{foo} is V4SI@.
5237 This attribute is only applicable to integral and float scalars,
5238 although arrays, pointers, and function return values are allowed in
5239 conjunction with this construct.
5241 Aggregates with this attribute are invalid, even if they are of the same
5242 size as a corresponding scalar. For example, the declaration:
5245 struct S @{ int a; @};
5246 struct S __attribute__ ((vector_size (16))) foo;
5250 is invalid even if the size of the structure is the same as the size of
5254 The @code{selectany} attribute causes an initialized global variable to
5255 have link-once semantics. When multiple definitions of the variable are
5256 encountered by the linker, the first is selected and the remainder are
5257 discarded. Following usage by the Microsoft compiler, the linker is told
5258 @emph{not} to warn about size or content differences of the multiple
5261 Although the primary usage of this attribute is for POD types, the
5262 attribute can also be applied to global C++ objects that are initialized
5263 by a constructor. In this case, the static initialization and destruction
5264 code for the object is emitted in each translation defining the object,
5265 but the calls to the constructor and destructor are protected by a
5266 link-once guard variable.
5268 The @code{selectany} attribute is only available on Microsoft Windows
5269 targets. You can use @code{__declspec (selectany)} as a synonym for
5270 @code{__attribute__ ((selectany))} for compatibility with other
5274 The @code{weak} attribute is described in @ref{Function Attributes}.
5277 The @code{dllimport} attribute is described in @ref{Function Attributes}.
5280 The @code{dllexport} attribute is described in @ref{Function Attributes}.
5284 @anchor{AVR Variable Attributes}
5285 @subsection AVR Variable Attributes
5289 @cindex @code{progmem} AVR variable attribute
5290 The @code{progmem} attribute is used on the AVR to place read-only
5291 data in the non-volatile program memory (flash). The @code{progmem}
5292 attribute accomplishes this by putting respective variables into a
5293 section whose name starts with @code{.progmem}.
5295 This attribute works similar to the @code{section} attribute
5296 but adds additional checking. Notice that just like the
5297 @code{section} attribute, @code{progmem} affects the location
5298 of the data but not how this data is accessed.
5300 In order to read data located with the @code{progmem} attribute
5301 (inline) assembler must be used.
5303 /* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */
5304 #include <avr/pgmspace.h>
5306 /* Locate var in flash memory */
5307 const int var[2] PROGMEM = @{ 1, 2 @};
5309 int read_var (int i)
5311 /* Access var[] by accessor macro from avr/pgmspace.h */
5312 return (int) pgm_read_word (& var[i]);
5316 AVR is a Harvard architecture processor and data and read-only data
5317 normally resides in the data memory (RAM).
5319 See also the @ref{AVR Named Address Spaces} section for
5320 an alternate way to locate and access data in flash memory.
5323 @subsection Blackfin Variable Attributes
5325 Three attributes are currently defined for the Blackfin.
5331 @cindex @code{l1_data} variable attribute
5332 @cindex @code{l1_data_A} variable attribute
5333 @cindex @code{l1_data_B} variable attribute
5334 Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
5335 Variables with @code{l1_data} attribute are put into the specific section
5336 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
5337 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
5338 attribute are put into the specific section named @code{.l1.data.B}.
5341 @cindex @code{l2} variable attribute
5342 Use this attribute on the Blackfin to place the variable into L2 SRAM.
5343 Variables with @code{l2} attribute are put into the specific section
5344 named @code{.l2.data}.
5347 @subsection M32R/D Variable Attributes
5349 One attribute is currently defined for the M32R/D@.
5352 @item model (@var{model-name})
5353 @cindex variable addressability on the M32R/D
5354 Use this attribute on the M32R/D to set the addressability of an object.
5355 The identifier @var{model-name} is one of @code{small}, @code{medium},
5356 or @code{large}, representing each of the code models.
5358 Small model objects live in the lower 16MB of memory (so that their
5359 addresses can be loaded with the @code{ld24} instruction).
5361 Medium and large model objects may live anywhere in the 32-bit address space
5362 (the compiler generates @code{seth/add3} instructions to load their
5366 @anchor{MeP Variable Attributes}
5367 @subsection MeP Variable Attributes
5369 The MeP target has a number of addressing modes and busses. The
5370 @code{near} space spans the standard memory space's first 16 megabytes
5371 (24 bits). The @code{far} space spans the entire 32-bit memory space.
5372 The @code{based} space is a 128-byte region in the memory space that
5373 is addressed relative to the @code{$tp} register. The @code{tiny}
5374 space is a 65536-byte region relative to the @code{$gp} register. In
5375 addition to these memory regions, the MeP target has a separate 16-bit
5376 control bus which is specified with @code{cb} attributes.
5381 Any variable with the @code{based} attribute is assigned to the
5382 @code{.based} section, and is accessed with relative to the
5383 @code{$tp} register.
5386 Likewise, the @code{tiny} attribute assigned variables to the
5387 @code{.tiny} section, relative to the @code{$gp} register.
5390 Variables with the @code{near} attribute are assumed to have addresses
5391 that fit in a 24-bit addressing mode. This is the default for large
5392 variables (@code{-mtiny=4} is the default) but this attribute can
5393 override @code{-mtiny=} for small variables, or override @code{-ml}.
5396 Variables with the @code{far} attribute are addressed using a full
5397 32-bit address. Since this covers the entire memory space, this
5398 allows modules to make no assumptions about where variables might be
5402 @itemx io (@var{addr})
5403 Variables with the @code{io} attribute are used to address
5404 memory-mapped peripherals. If an address is specified, the variable
5405 is assigned that address, else it is not assigned an address (it is
5406 assumed some other module assigns an address). Example:
5409 int timer_count __attribute__((io(0x123)));
5413 @itemx cb (@var{addr})
5414 Variables with the @code{cb} attribute are used to access the control
5415 bus, using special instructions. @code{addr} indicates the control bus
5419 int cpu_clock __attribute__((cb(0x123)));
5424 @anchor{i386 Variable Attributes}
5425 @subsection i386 Variable Attributes
5427 Two attributes are currently defined for i386 configurations:
5428 @code{ms_struct} and @code{gcc_struct}
5433 @cindex @code{ms_struct} attribute
5434 @cindex @code{gcc_struct} attribute
5436 If @code{packed} is used on a structure, or if bit-fields are used,
5437 it may be that the Microsoft ABI lays out the structure differently
5438 than the way GCC normally does. Particularly when moving packed
5439 data between functions compiled with GCC and the native Microsoft compiler
5440 (either via function call or as data in a file), it may be necessary to access
5443 Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86
5444 compilers to match the native Microsoft compiler.
5446 The Microsoft structure layout algorithm is fairly simple with the exception
5447 of the bit-field packing.
5448 The padding and alignment of members of structures and whether a bit-field
5449 can straddle a storage-unit boundary are determine by these rules:
5452 @item Structure members are stored sequentially in the order in which they are
5453 declared: the first member has the lowest memory address and the last member
5456 @item Every data object has an alignment requirement. The alignment requirement
5457 for all data except structures, unions, and arrays is either the size of the
5458 object or the current packing size (specified with either the
5459 @code{aligned} attribute or the @code{pack} pragma),
5460 whichever is less. For structures, unions, and arrays,
5461 the alignment requirement is the largest alignment requirement of its members.
5462 Every object is allocated an offset so that:
5465 offset % alignment_requirement == 0
5468 @item Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation
5469 unit if the integral types are the same size and if the next bit-field fits
5470 into the current allocation unit without crossing the boundary imposed by the
5471 common alignment requirements of the bit-fields.
5474 MSVC interprets zero-length bit-fields in the following ways:
5477 @item If a zero-length bit-field is inserted between two bit-fields that
5478 are normally coalesced, the bit-fields are not coalesced.
5485 unsigned long bf_1 : 12;
5487 unsigned long bf_2 : 12;
5492 The size of @code{t1} is 8 bytes with the zero-length bit-field. If the
5493 zero-length bit-field were removed, @code{t1}'s size would be 4 bytes.
5495 @item If a zero-length bit-field is inserted after a bit-field, @code{foo}, and the
5496 alignment of the zero-length bit-field is greater than the member that follows it,
5497 @code{bar}, @code{bar} is aligned as the type of the zero-length bit-field.
5518 For @code{t2}, @code{bar} is placed at offset 2, rather than offset 1.
5519 Accordingly, the size of @code{t2} is 4. For @code{t3}, the zero-length
5520 bit-field does not affect the alignment of @code{bar} or, as a result, the size
5523 Taking this into account, it is important to note the following:
5526 @item If a zero-length bit-field follows a normal bit-field, the type of the
5527 zero-length bit-field may affect the alignment of the structure as whole. For
5528 example, @code{t2} has a size of 4 bytes, since the zero-length bit-field follows a
5529 normal bit-field, and is of type short.
5531 @item Even if a zero-length bit-field is not followed by a normal bit-field, it may
5532 still affect the alignment of the structure:
5543 Here, @code{t4} takes up 4 bytes.
5546 @item Zero-length bit-fields following non-bit-field members are ignored:
5558 Here, @code{t5} takes up 2 bytes.
5562 @subsection PowerPC Variable Attributes
5564 Three attributes currently are defined for PowerPC configurations:
5565 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
5567 For full documentation of the struct attributes please see the
5568 documentation in @ref{i386 Variable Attributes}.
5570 For documentation of @code{altivec} attribute please see the
5571 documentation in @ref{PowerPC Type Attributes}.
5573 @subsection SPU Variable Attributes
5575 The SPU supports the @code{spu_vector} attribute for variables. For
5576 documentation of this attribute please see the documentation in
5577 @ref{SPU Type Attributes}.
5579 @subsection Xstormy16 Variable Attributes
5581 One attribute is currently defined for xstormy16 configurations:
5586 @cindex @code{below100} attribute
5588 If a variable has the @code{below100} attribute (@code{BELOW100} is
5589 allowed also), GCC places the variable in the first 0x100 bytes of
5590 memory and use special opcodes to access it. Such variables are
5591 placed in either the @code{.bss_below100} section or the
5592 @code{.data_below100} section.
5596 @node Type Attributes
5597 @section Specifying Attributes of Types
5598 @cindex attribute of types
5599 @cindex type attributes
5601 The keyword @code{__attribute__} allows you to specify special
5602 attributes of @code{struct} and @code{union} types when you define
5603 such types. This keyword is followed by an attribute specification
5604 inside double parentheses. Seven attributes are currently defined for
5605 types: @code{aligned}, @code{packed}, @code{transparent_union},
5606 @code{unused}, @code{deprecated}, @code{visibility}, and
5607 @code{may_alias}. Other attributes are defined for functions
5608 (@pxref{Function Attributes}), labels (@pxref{Label
5609 Attributes}) and for variables (@pxref{Variable Attributes}).
5611 You may also specify any one of these attributes with @samp{__}
5612 preceding and following its keyword. This allows you to use these
5613 attributes in header files without being concerned about a possible
5614 macro of the same name. For example, you may use @code{__aligned__}
5615 instead of @code{aligned}.
5617 You may specify type attributes in an enum, struct or union type
5618 declaration or definition, or for other types in a @code{typedef}
5621 For an enum, struct or union type, you may specify attributes either
5622 between the enum, struct or union tag and the name of the type, or
5623 just past the closing curly brace of the @emph{definition}. The
5624 former syntax is preferred.
5626 @xref{Attribute Syntax}, for details of the exact syntax for using
5630 @cindex @code{aligned} attribute
5631 @item aligned (@var{alignment})
5632 This attribute specifies a minimum alignment (in bytes) for variables
5633 of the specified type. For example, the declarations:
5636 struct S @{ short f[3]; @} __attribute__ ((aligned (8)));
5637 typedef int more_aligned_int __attribute__ ((aligned (8)));
5641 force the compiler to ensure (as far as it can) that each variable whose
5642 type is @code{struct S} or @code{more_aligned_int} is allocated and
5643 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
5644 variables of type @code{struct S} aligned to 8-byte boundaries allows
5645 the compiler to use the @code{ldd} and @code{std} (doubleword load and
5646 store) instructions when copying one variable of type @code{struct S} to
5647 another, thus improving run-time efficiency.
5649 Note that the alignment of any given @code{struct} or @code{union} type
5650 is required by the ISO C standard to be at least a perfect multiple of
5651 the lowest common multiple of the alignments of all of the members of
5652 the @code{struct} or @code{union} in question. This means that you @emph{can}
5653 effectively adjust the alignment of a @code{struct} or @code{union}
5654 type by attaching an @code{aligned} attribute to any one of the members
5655 of such a type, but the notation illustrated in the example above is a
5656 more obvious, intuitive, and readable way to request the compiler to
5657 adjust the alignment of an entire @code{struct} or @code{union} type.
5659 As in the preceding example, you can explicitly specify the alignment
5660 (in bytes) that you wish the compiler to use for a given @code{struct}
5661 or @code{union} type. Alternatively, you can leave out the alignment factor
5662 and just ask the compiler to align a type to the maximum
5663 useful alignment for the target machine you are compiling for. For
5664 example, you could write:
5667 struct S @{ short f[3]; @} __attribute__ ((aligned));
5670 Whenever you leave out the alignment factor in an @code{aligned}
5671 attribute specification, the compiler automatically sets the alignment
5672 for the type to the largest alignment that is ever used for any data
5673 type on the target machine you are compiling for. Doing this can often
5674 make copy operations more efficient, because the compiler can use
5675 whatever instructions copy the biggest chunks of memory when performing
5676 copies to or from the variables that have types that you have aligned
5679 In the example above, if the size of each @code{short} is 2 bytes, then
5680 the size of the entire @code{struct S} type is 6 bytes. The smallest
5681 power of two that is greater than or equal to that is 8, so the
5682 compiler sets the alignment for the entire @code{struct S} type to 8
5685 Note that although you can ask the compiler to select a time-efficient
5686 alignment for a given type and then declare only individual stand-alone
5687 objects of that type, the compiler's ability to select a time-efficient
5688 alignment is primarily useful only when you plan to create arrays of
5689 variables having the relevant (efficiently aligned) type. If you
5690 declare or use arrays of variables of an efficiently-aligned type, then
5691 it is likely that your program also does pointer arithmetic (or
5692 subscripting, which amounts to the same thing) on pointers to the
5693 relevant type, and the code that the compiler generates for these
5694 pointer arithmetic operations is often more efficient for
5695 efficiently-aligned types than for other types.
5697 The @code{aligned} attribute can only increase the alignment; but you
5698 can decrease it by specifying @code{packed} as well. See below.
5700 Note that the effectiveness of @code{aligned} attributes may be limited
5701 by inherent limitations in your linker. On many systems, the linker is
5702 only able to arrange for variables to be aligned up to a certain maximum
5703 alignment. (For some linkers, the maximum supported alignment may
5704 be very very small.) If your linker is only able to align variables
5705 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
5706 in an @code{__attribute__} still only provides you with 8-byte
5707 alignment. See your linker documentation for further information.
5710 This attribute, attached to @code{struct} or @code{union} type
5711 definition, specifies that each member (other than zero-width bit-fields)
5712 of the structure or union is placed to minimize the memory required. When
5713 attached to an @code{enum} definition, it indicates that the smallest
5714 integral type should be used.
5716 @opindex fshort-enums
5717 Specifying this attribute for @code{struct} and @code{union} types is
5718 equivalent to specifying the @code{packed} attribute on each of the
5719 structure or union members. Specifying the @option{-fshort-enums}
5720 flag on the line is equivalent to specifying the @code{packed}
5721 attribute on all @code{enum} definitions.
5723 In the following example @code{struct my_packed_struct}'s members are
5724 packed closely together, but the internal layout of its @code{s} member
5725 is not packed---to do that, @code{struct my_unpacked_struct} needs to
5729 struct my_unpacked_struct
5735 struct __attribute__ ((__packed__)) my_packed_struct
5739 struct my_unpacked_struct s;
5743 You may only specify this attribute on the definition of an @code{enum},
5744 @code{struct} or @code{union}, not on a @code{typedef} that does not
5745 also define the enumerated type, structure or union.
5747 @item transparent_union
5748 @cindex @code{transparent_union} attribute
5750 This attribute, attached to a @code{union} type definition, indicates
5751 that any function parameter having that union type causes calls to that
5752 function to be treated in a special way.
5754 First, the argument corresponding to a transparent union type can be of
5755 any type in the union; no cast is required. Also, if the union contains
5756 a pointer type, the corresponding argument can be a null pointer
5757 constant or a void pointer expression; and if the union contains a void
5758 pointer type, the corresponding argument can be any pointer expression.
5759 If the union member type is a pointer, qualifiers like @code{const} on
5760 the referenced type must be respected, just as with normal pointer
5763 Second, the argument is passed to the function using the calling
5764 conventions of the first member of the transparent union, not the calling
5765 conventions of the union itself. All members of the union must have the
5766 same machine representation; this is necessary for this argument passing
5769 Transparent unions are designed for library functions that have multiple
5770 interfaces for compatibility reasons. For example, suppose the
5771 @code{wait} function must accept either a value of type @code{int *} to
5772 comply with POSIX, or a value of type @code{union wait *} to comply with
5773 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
5774 @code{wait} would accept both kinds of arguments, but it would also
5775 accept any other pointer type and this would make argument type checking
5776 less useful. Instead, @code{<sys/wait.h>} might define the interface
5780 typedef union __attribute__ ((__transparent_union__))
5784 @} wait_status_ptr_t;
5786 pid_t wait (wait_status_ptr_t);
5790 This interface allows either @code{int *} or @code{union wait *}
5791 arguments to be passed, using the @code{int *} calling convention.
5792 The program can call @code{wait} with arguments of either type:
5795 int w1 () @{ int w; return wait (&w); @}
5796 int w2 () @{ union wait w; return wait (&w); @}
5800 With this interface, @code{wait}'s implementation might look like this:
5803 pid_t wait (wait_status_ptr_t p)
5805 return waitpid (-1, p.__ip, 0);
5810 When attached to a type (including a @code{union} or a @code{struct}),
5811 this attribute means that variables of that type are meant to appear
5812 possibly unused. GCC does not produce a warning for any variables of
5813 that type, even if the variable appears to do nothing. This is often
5814 the case with lock or thread classes, which are usually defined and then
5815 not referenced, but contain constructors and destructors that have
5816 nontrivial bookkeeping functions.
5819 @itemx deprecated (@var{msg})
5820 The @code{deprecated} attribute results in a warning if the type
5821 is used anywhere in the source file. This is useful when identifying
5822 types that are expected to be removed in a future version of a program.
5823 If possible, the warning also includes the location of the declaration
5824 of the deprecated type, to enable users to easily find further
5825 information about why the type is deprecated, or what they should do
5826 instead. Note that the warnings only occur for uses and then only
5827 if the type is being applied to an identifier that itself is not being
5828 declared as deprecated.
5831 typedef int T1 __attribute__ ((deprecated));
5835 typedef T1 T3 __attribute__ ((deprecated));
5836 T3 z __attribute__ ((deprecated));
5840 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
5841 warning is issued for line 4 because T2 is not explicitly
5842 deprecated. Line 5 has no warning because T3 is explicitly
5843 deprecated. Similarly for line 6. The optional @var{msg}
5844 argument, which must be a string, is printed in the warning if
5847 The @code{deprecated} attribute can also be used for functions and
5848 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
5851 Accesses through pointers to types with this attribute are not subject
5852 to type-based alias analysis, but are instead assumed to be able to alias
5853 any other type of objects.
5854 In the context of section 6.5 paragraph 7 of the C99 standard,
5855 an lvalue expression
5856 dereferencing such a pointer is treated like having a character type.
5857 See @option{-fstrict-aliasing} for more information on aliasing issues.
5858 This extension exists to support some vector APIs, in which pointers to
5859 one vector type are permitted to alias pointers to a different vector type.
5861 Note that an object of a type with this attribute does not have any
5867 typedef short __attribute__((__may_alias__)) short_a;
5873 short_a *b = (short_a *) &a;
5877 if (a == 0x12345678)
5885 If you replaced @code{short_a} with @code{short} in the variable
5886 declaration, the above program would abort when compiled with
5887 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or
5888 above in recent GCC versions.
5891 In C++, attribute visibility (@pxref{Function Attributes}) can also be
5892 applied to class, struct, union and enum types. Unlike other type
5893 attributes, the attribute must appear between the initial keyword and
5894 the name of the type; it cannot appear after the body of the type.
5896 Note that the type visibility is applied to vague linkage entities
5897 associated with the class (vtable, typeinfo node, etc.). In
5898 particular, if a class is thrown as an exception in one shared object
5899 and caught in another, the class must have default visibility.
5900 Otherwise the two shared objects are unable to use the same
5901 typeinfo node and exception handling will break.
5903 @item designated_init
5904 This attribute may only be applied to structure types. It indicates
5905 that any initialization of an object of this type must use designated
5906 initializers rather than positional initializers. The intent of this
5907 attribute is to allow the programmer to indicate that a structure's
5908 layout may change, and that therefore relying on positional
5909 initialization will result in future breakage.
5911 GCC emits warnings based on this attribute by default; use
5912 @option{-Wno-designated-init} to suppress them.
5916 To specify multiple attributes, separate them by commas within the
5917 double parentheses: for example, @samp{__attribute__ ((aligned (16),
5920 @subsection ARM Type Attributes
5922 On those ARM targets that support @code{dllimport} (such as Symbian
5923 OS), you can use the @code{notshared} attribute to indicate that the
5924 virtual table and other similar data for a class should not be
5925 exported from a DLL@. For example:
5928 class __declspec(notshared) C @{
5930 __declspec(dllimport) C();
5934 __declspec(dllexport)
5939 In this code, @code{C::C} is exported from the current DLL, but the
5940 virtual table for @code{C} is not exported. (You can use
5941 @code{__attribute__} instead of @code{__declspec} if you prefer, but
5942 most Symbian OS code uses @code{__declspec}.)
5944 @anchor{MeP Type Attributes}
5945 @subsection MeP Type Attributes
5947 Many of the MeP variable attributes may be applied to types as well.
5948 Specifically, the @code{based}, @code{tiny}, @code{near}, and
5949 @code{far} attributes may be applied to either. The @code{io} and
5950 @code{cb} attributes may not be applied to types.
5952 @anchor{i386 Type Attributes}
5953 @subsection i386 Type Attributes
5955 Two attributes are currently defined for i386 configurations:
5956 @code{ms_struct} and @code{gcc_struct}.
5962 @cindex @code{ms_struct}
5963 @cindex @code{gcc_struct}
5965 If @code{packed} is used on a structure, or if bit-fields are used
5966 it may be that the Microsoft ABI packs them differently
5967 than GCC normally packs them. Particularly when moving packed
5968 data between functions compiled with GCC and the native Microsoft compiler
5969 (either via function call or as data in a file), it may be necessary to access
5972 Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86
5973 compilers to match the native Microsoft compiler.
5976 @anchor{PowerPC Type Attributes}
5977 @subsection PowerPC Type Attributes
5979 Three attributes currently are defined for PowerPC configurations:
5980 @code{altivec}, @code{ms_struct} and @code{gcc_struct}.
5982 For full documentation of the @code{ms_struct} and @code{gcc_struct}
5983 attributes please see the documentation in @ref{i386 Type Attributes}.
5985 The @code{altivec} attribute allows one to declare AltiVec vector data
5986 types supported by the AltiVec Programming Interface Manual. The
5987 attribute requires an argument to specify one of three vector types:
5988 @code{vector__}, @code{pixel__} (always followed by unsigned short),
5989 and @code{bool__} (always followed by unsigned).
5992 __attribute__((altivec(vector__)))
5993 __attribute__((altivec(pixel__))) unsigned short
5994 __attribute__((altivec(bool__))) unsigned
5997 These attributes mainly are intended to support the @code{__vector},
5998 @code{__pixel}, and @code{__bool} AltiVec keywords.
6000 @anchor{SPU Type Attributes}
6001 @subsection SPU Type Attributes
6003 The SPU supports the @code{spu_vector} attribute for types. This attribute
6004 allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU
6005 Language Extensions Specification. It is intended to support the
6006 @code{__vector} keyword.
6009 @section Inquiring on Alignment of Types or Variables
6011 @cindex type alignment
6012 @cindex variable alignment
6014 The keyword @code{__alignof__} allows you to inquire about how an object
6015 is aligned, or the minimum alignment usually required by a type. Its
6016 syntax is just like @code{sizeof}.
6018 For example, if the target machine requires a @code{double} value to be
6019 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
6020 This is true on many RISC machines. On more traditional machine
6021 designs, @code{__alignof__ (double)} is 4 or even 2.
6023 Some machines never actually require alignment; they allow reference to any
6024 data type even at an odd address. For these machines, @code{__alignof__}
6025 reports the smallest alignment that GCC gives the data type, usually as
6026 mandated by the target ABI.
6028 If the operand of @code{__alignof__} is an lvalue rather than a type,
6029 its value is the required alignment for its type, taking into account
6030 any minimum alignment specified with GCC's @code{__attribute__}
6031 extension (@pxref{Variable Attributes}). For example, after this
6035 struct foo @{ int x; char y; @} foo1;
6039 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual
6040 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}.
6042 It is an error to ask for the alignment of an incomplete type.
6046 @section An Inline Function is As Fast As a Macro
6047 @cindex inline functions
6048 @cindex integrating function code
6050 @cindex macros, inline alternative
6052 By declaring a function inline, you can direct GCC to make
6053 calls to that function faster. One way GCC can achieve this is to
6054 integrate that function's code into the code for its callers. This
6055 makes execution faster by eliminating the function-call overhead; in
6056 addition, if any of the actual argument values are constant, their
6057 known values may permit simplifications at compile time so that not
6058 all of the inline function's code needs to be included. The effect on
6059 code size is less predictable; object code may be larger or smaller
6060 with function inlining, depending on the particular case. You can
6061 also direct GCC to try to integrate all ``simple enough'' functions
6062 into their callers with the option @option{-finline-functions}.
6064 GCC implements three different semantics of declaring a function
6065 inline. One is available with @option{-std=gnu89} or
6066 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present
6067 on all inline declarations, another when
6068 @option{-std=c99}, @option{-std=c11},
6069 @option{-std=gnu99} or @option{-std=gnu11}
6070 (without @option{-fgnu89-inline}), and the third
6071 is used when compiling C++.
6073 To declare a function inline, use the @code{inline} keyword in its
6074 declaration, like this:
6084 If you are writing a header file to be included in ISO C90 programs, write
6085 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.
6087 The three types of inlining behave similarly in two important cases:
6088 when the @code{inline} keyword is used on a @code{static} function,
6089 like the example above, and when a function is first declared without
6090 using the @code{inline} keyword and then is defined with
6091 @code{inline}, like this:
6094 extern int inc (int *a);
6102 In both of these common cases, the program behaves the same as if you
6103 had not used the @code{inline} keyword, except for its speed.
6105 @cindex inline functions, omission of
6106 @opindex fkeep-inline-functions
6107 When a function is both inline and @code{static}, if all calls to the
6108 function are integrated into the caller, and the function's address is
6109 never used, then the function's own assembler code is never referenced.
6110 In this case, GCC does not actually output assembler code for the
6111 function, unless you specify the option @option{-fkeep-inline-functions}.
6112 Some calls cannot be integrated for various reasons (in particular,
6113 calls that precede the function's definition cannot be integrated, and
6114 neither can recursive calls within the definition). If there is a
6115 nonintegrated call, then the function is compiled to assembler code as
6116 usual. The function must also be compiled as usual if the program
6117 refers to its address, because that can't be inlined.
6120 Note that certain usages in a function definition can make it unsuitable
6121 for inline substitution. Among these usages are: variadic functions, use of
6122 @code{alloca}, use of variable-length data types (@pxref{Variable Length}),
6123 use of computed goto (@pxref{Labels as Values}), use of nonlocal goto,
6124 and nested functions (@pxref{Nested Functions}). Using @option{-Winline}
6125 warns when a function marked @code{inline} could not be substituted,
6126 and gives the reason for the failure.
6128 @cindex automatic @code{inline} for C++ member fns
6129 @cindex @code{inline} automatic for C++ member fns
6130 @cindex member fns, automatically @code{inline}
6131 @cindex C++ member fns, automatically @code{inline}
6132 @opindex fno-default-inline
6133 As required by ISO C++, GCC considers member functions defined within
6134 the body of a class to be marked inline even if they are
6135 not explicitly declared with the @code{inline} keyword. You can
6136 override this with @option{-fno-default-inline}; @pxref{C++ Dialect
6137 Options,,Options Controlling C++ Dialect}.
6139 GCC does not inline any functions when not optimizing unless you specify
6140 the @samp{always_inline} attribute for the function, like this:
6143 /* @r{Prototype.} */
6144 inline void foo (const char) __attribute__((always_inline));
6147 The remainder of this section is specific to GNU C90 inlining.
6149 @cindex non-static inline function
6150 When an inline function is not @code{static}, then the compiler must assume
6151 that there may be calls from other source files; since a global symbol can
6152 be defined only once in any program, the function must not be defined in
6153 the other source files, so the calls therein cannot be integrated.
6154 Therefore, a non-@code{static} inline function is always compiled on its
6155 own in the usual fashion.
6157 If you specify both @code{inline} and @code{extern} in the function
6158 definition, then the definition is used only for inlining. In no case
6159 is the function compiled on its own, not even if you refer to its
6160 address explicitly. Such an address becomes an external reference, as
6161 if you had only declared the function, and had not defined it.
6163 This combination of @code{inline} and @code{extern} has almost the
6164 effect of a macro. The way to use it is to put a function definition in
6165 a header file with these keywords, and put another copy of the
6166 definition (lacking @code{inline} and @code{extern}) in a library file.
6167 The definition in the header file causes most calls to the function
6168 to be inlined. If any uses of the function remain, they refer to
6169 the single copy in the library.
6172 @section When is a Volatile Object Accessed?
6173 @cindex accessing volatiles
6174 @cindex volatile read
6175 @cindex volatile write
6176 @cindex volatile access
6178 C has the concept of volatile objects. These are normally accessed by
6179 pointers and used for accessing hardware or inter-thread
6180 communication. The standard encourages compilers to refrain from
6181 optimizations concerning accesses to volatile objects, but leaves it
6182 implementation defined as to what constitutes a volatile access. The
6183 minimum requirement is that at a sequence point all previous accesses
6184 to volatile objects have stabilized and no subsequent accesses have
6185 occurred. Thus an implementation is free to reorder and combine
6186 volatile accesses that occur between sequence points, but cannot do
6187 so for accesses across a sequence point. The use of volatile does
6188 not allow you to violate the restriction on updating objects multiple
6189 times between two sequence points.
6191 Accesses to non-volatile objects are not ordered with respect to
6192 volatile accesses. You cannot use a volatile object as a memory
6193 barrier to order a sequence of writes to non-volatile memory. For
6197 int *ptr = @var{something};
6199 *ptr = @var{something};
6204 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed
6205 that the write to @var{*ptr} occurs by the time the update
6206 of @var{vobj} happens. If you need this guarantee, you must use
6207 a stronger memory barrier such as:
6210 int *ptr = @var{something};
6212 *ptr = @var{something};
6213 asm volatile ("" : : : "memory");
6217 A scalar volatile object is read when it is accessed in a void context:
6220 volatile int *src = @var{somevalue};
6224 Such expressions are rvalues, and GCC implements this as a
6225 read of the volatile object being pointed to.
6227 Assignments are also expressions and have an rvalue. However when
6228 assigning to a scalar volatile, the volatile object is not reread,
6229 regardless of whether the assignment expression's rvalue is used or
6230 not. If the assignment's rvalue is used, the value is that assigned
6231 to the volatile object. For instance, there is no read of @var{vobj}
6232 in all the following cases:
6237 vobj = @var{something};
6238 obj = vobj = @var{something};
6239 obj ? vobj = @var{onething} : vobj = @var{anotherthing};
6240 obj = (@var{something}, vobj = @var{anotherthing});
6243 If you need to read the volatile object after an assignment has
6244 occurred, you must use a separate expression with an intervening
6247 As bit-fields are not individually addressable, volatile bit-fields may
6248 be implicitly read when written to, or when adjacent bit-fields are
6249 accessed. Bit-field operations may be optimized such that adjacent
6250 bit-fields are only partially accessed, if they straddle a storage unit
6251 boundary. For these reasons it is unwise to use volatile bit-fields to
6254 @node Using Assembly Language with C
6255 @section How to Use Inline Assembly Language in C Code
6257 GCC provides various extensions that allow you to embed assembler within
6261 * Basic Asm:: Inline assembler with no operands.
6262 * Extended Asm:: Inline assembler with operands.
6263 * Constraints:: Constraints for @code{asm} operands
6264 * Asm Labels:: Specifying the assembler name to use for a C symbol.
6265 * Explicit Reg Vars:: Defining variables residing in specified registers.
6266 * Size of an asm:: How GCC calculates the size of an @code{asm} block.
6270 @subsection Basic Asm --- Assembler Instructions with No Operands
6271 @cindex basic @code{asm}
6273 The @code{asm} keyword allows you to embed assembler instructions within
6277 asm [ volatile ] ( AssemblerInstructions )
6280 To create headers compatible with ISO C, write @code{__asm__} instead of
6281 @code{asm} (@pxref{Alternate Keywords}).
6283 By definition, a Basic @code{asm} statement is one with no operands.
6284 @code{asm} statements that contain one or more colons (used to delineate
6285 operands) are considered to be Extended (for example, @code{asm("int $3")}
6286 is Basic, and @code{asm("int $3" : )} is Extended). @xref{Extended Asm}.
6288 @subsubheading Qualifiers
6291 This optional qualifier has no effect. All Basic @code{asm} blocks are
6292 implicitly volatile.
6294 @subsubheading Parameters
6295 @emph{AssemblerInstructions}
6297 This is a literal string that specifies the assembler code. The string can
6298 contain any instructions recognized by the assembler, including directives.
6299 GCC does not parse the assembler instructions themselves and
6300 does not know what they mean or even whether they are valid assembler input.
6301 The compiler copies it verbatim to the assembly language output file, without
6302 processing dialects or any of the "%" operators that are available with
6303 Extended @code{asm}. This results in minor differences between Basic
6304 @code{asm} strings and Extended @code{asm} templates. For example, to refer to
6305 registers you might use %%eax in Extended @code{asm} and %eax in Basic
6308 You may place multiple assembler instructions together in a single @code{asm}
6309 string, separated by the characters normally used in assembly code for the
6310 system. A combination that works in most places is a newline to break the
6311 line, plus a tab character (written as "\n\t").
6312 Some assemblers allow semicolons as a line separator. However,
6313 note that some assembler dialects use semicolons to start a comment.
6315 Do not expect a sequence of @code{asm} statements to remain perfectly
6316 consecutive after compilation. If certain instructions need to remain
6317 consecutive in the output, put them in a single multi-instruction asm
6318 statement. Note that GCC's optimizers can move @code{asm} statements
6319 relative to other code, including across jumps.
6321 @code{asm} statements may not perform jumps into other @code{asm} statements.
6322 GCC does not know about these jumps, and therefore cannot take
6323 account of them when deciding how to optimize. Jumps from @code{asm} to C
6324 labels are only supported in Extended @code{asm}.
6326 @subsubheading Remarks
6327 Using Extended @code{asm} will typically produce smaller, safer, and more
6328 efficient code, and in most cases it is a better solution. When writing
6329 inline assembly language outside of C functions, however, you must use Basic
6330 @code{asm}. Extended @code{asm} statements have to be inside a C function.
6331 Functions declared with the @code{naked} attribute also require Basic
6332 @code{asm} (@pxref{Function Attributes}).
6334 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
6335 assembly code when optimizing. This can lead to unexpected duplicate
6336 symbol errors during compilation if your assembly code defines symbols or
6339 Safely accessing C data and calling functions from Basic @code{asm} is more
6340 complex than it may appear. To access C data, it is better to use Extended
6343 Since GCC does not parse the AssemblerInstructions, it has no
6344 visibility of any symbols it references. This may result in GCC discarding
6345 those symbols as unreferenced.
6347 Unlike Extended @code{asm}, all Basic @code{asm} blocks are implicitly
6348 volatile. @xref{Volatile}. Similarly, Basic @code{asm} blocks are not treated
6349 as though they used a "memory" clobber (@pxref{Clobbers}).
6351 All Basic @code{asm} blocks use the assembler dialect specified by the
6352 @option{-masm} command-line option. Basic @code{asm} provides no
6353 mechanism to provide different assembler strings for different dialects.
6355 Here is an example of Basic @code{asm} for i386:
6358 /* Note that this code will not compile with -masm=intel */
6359 #define DebugBreak() asm("int $3")
6363 @subsection Extended Asm - Assembler Instructions with C Expression Operands
6364 @cindex @code{asm} keyword
6365 @cindex extended @code{asm}
6366 @cindex assembler instructions
6368 The @code{asm} keyword allows you to embed assembler instructions within C
6369 code. With Extended @code{asm} you can read and write C variables from
6370 assembler and perform jumps from assembler code to C labels.
6374 asm [volatile] ( AssemblerTemplate : [OutputOperands] [ : [InputOperands] [ : [Clobbers] ] ] )
6376 asm [volatile] goto ( AssemblerTemplate : : [InputOperands] : [Clobbers] : GotoLabels )
6379 asm [volatile] ( AssemblerTemplate
6384 asm [volatile] goto ( AssemblerTemplate
6392 To create headers compatible with ISO C, write @code{__asm__} instead of
6393 @code{asm} and @code{__volatile__} instead of @code{volatile}
6394 (@pxref{Alternate Keywords}). There is no alternate for @code{goto}.
6396 By definition, Extended @code{asm} is an @code{asm} statement that contains
6397 operands. To separate the classes of operands, you use colons. Basic
6398 @code{asm} statements contain no colons. (So, for example,
6399 @code{asm("int $3")} is Basic @code{asm}, and @code{asm("int $3" : )} is
6400 Extended @code{asm}. @pxref{Basic Asm}.)
6402 @subsubheading Qualifiers
6405 The typical use of Extended @code{asm} statements is to manipulate input
6406 values to produce output values. However, your @code{asm} statements may
6407 also produce side effects. If so, you may need to use the @code{volatile}
6408 qualifier to disable certain optimizations. @xref{Volatile}.
6412 This qualifier informs the compiler that the @code{asm} statement may
6413 perform a jump to one of the labels listed in the GotoLabels section.
6416 @subsubheading Parameters
6417 @emph{AssemblerTemplate}
6419 This is a literal string that contains the assembler code. It is a
6420 combination of fixed text and tokens that refer to the input, output,
6421 and goto parameters. @xref{AssemblerTemplate}.
6423 @emph{OutputOperands}
6425 A comma-separated list of the C variables modified by the instructions in the
6426 AssemblerTemplate. @xref{OutputOperands}.
6428 @emph{InputOperands}
6430 A comma-separated list of C expressions read by the instructions in the
6431 AssemblerTemplate. @xref{InputOperands}.
6435 A comma-separated list of registers or other values changed by the
6436 AssemblerTemplate, beyond those listed as outputs. @xref{Clobbers}.
6440 When you are using the @code{goto} form of @code{asm}, this section contains
6441 the list of all C labels to which the AssemblerTemplate may jump.
6444 @subsubheading Remarks
6445 The @code{asm} statement allows you to include assembly instructions directly
6446 within C code. This may help you to maximize performance in time-sensitive
6447 code or to access assembly instructions that are not readily available to C
6450 Note that Extended @code{asm} statements must be inside a function. Only
6451 Basic @code{asm} may be outside functions (@pxref{Basic Asm}).
6452 Functions declared with the @code{naked} attribute also require Basic
6453 @code{asm} (@pxref{Function Attributes}).
6455 While the uses of @code{asm} are many and varied, it may help to think of an
6456 @code{asm} statement as a series of low-level instructions that convert input
6457 parameters to output parameters. So a simple (if not particularly useful)
6458 example for i386 using @code{asm} might look like this:
6464 asm ("mov %1, %0\n\t"
6469 printf("%d\n", dst);
6472 This code will copy @var{src} to @var{dst} and add 1 to @var{dst}.
6475 @subsubsection Volatile
6476 @cindex volatile @code{asm}
6477 @cindex @code{asm} volatile
6479 GCC's optimizers sometimes discard @code{asm} statements if they determine
6480 there is no need for the output variables. Also, the optimizers may move
6481 code out of loops if they believe that the code will always return the same
6482 result (i.e. none of its input values change between calls). Using the
6483 @code{volatile} qualifier disables these optimizations. @code{asm} statements
6484 that have no output operands are implicitly volatile.
6488 This i386 code demonstrates a case that does not use (or require) the
6489 @code{volatile} qualifier. If it is performing assertion checking, this code
6490 uses @code{asm} to perform the validation. Otherwise, @var{dwRes} is
6491 unreferenced by any code. As a result, the optimizers can discard the
6492 @code{asm} statement, which in turn removes the need for the entire
6493 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
6494 isn't needed you allow the optimizers to produce the most efficient code
6498 void DoCheck(uint32_t dwSomeValue)
6502 // Assumes dwSomeValue is not zero.
6512 The next example shows a case where the optimizers can recognize that the input
6513 (@var{dwSomeValue}) never changes during the execution of the function and can
6514 therefore move the @code{asm} outside the loop to produce more efficient code.
6515 Again, using @code{volatile} disables this type of optimization.
6518 void do_print(uint32_t dwSomeValue)
6522 for (uint32_t x=0; x < 5; x++)
6524 // Assumes dwSomeValue is not zero.
6530 printf("%u: %u %u\n", x, dwSomeValue, dwRes);
6535 The following example demonstrates a case where you need to use the
6536 @code{volatile} qualifier. It uses the i386 RDTSC instruction, which reads
6537 the computer's time-stamp counter. Without the @code{volatile} qualifier,
6538 the optimizers might assume that the @code{asm} block will always return the
6539 same value and therefore optimize away the second call.
6544 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
6545 "shl $32, %%rdx\n\t" // Shift the upper bits left.
6546 "or %%rdx, %0" // 'Or' in the lower bits.
6551 printf("msr: %llx\n", msr);
6555 // Reprint the timestamp
6556 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
6557 "shl $32, %%rdx\n\t" // Shift the upper bits left.
6558 "or %%rdx, %0" // 'Or' in the lower bits.
6563 printf("msr: %llx\n", msr);
6566 GCC's optimizers will not treat this code like the non-volatile code in the
6567 earlier examples. They do not move it out of loops or omit it on the
6568 assumption that the result from a previous call is still valid.
6570 Note that the compiler can move even volatile @code{asm} instructions relative
6571 to other code, including across jump instructions. For example, on many
6572 targets there is a system register that controls the rounding mode of
6573 floating-point operations. Setting it with a volatile @code{asm}, as in the
6574 following PowerPC example, will not work reliably.
6577 asm volatile("mtfsf 255, %0" : : "f" (fpenv));
6581 The compiler may move the addition back before the volatile @code{asm}. To
6582 make it work as expected, add an artificial dependency to the @code{asm} by
6583 referencing a variable in the subsequent code, for example:
6586 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
6590 Under certain circumstances, GCC may duplicate (or remove duplicates of) your
6591 assembly code when optimizing. This can lead to unexpected duplicate symbol
6592 errors during compilation if your asm code defines symbols or labels. Using %=
6593 (@pxref{AssemblerTemplate}) may help resolve this problem.
6595 @anchor{AssemblerTemplate}
6596 @subsubsection Assembler Template
6597 @cindex @code{asm} assembler template
6599 An assembler template is a literal string containing assembler instructions.
6600 The compiler will replace any references to inputs, outputs, and goto labels
6601 in the template, and then output the resulting string to the assembler. The
6602 string can contain any instructions recognized by the assembler, including
6603 directives. GCC does not parse the assembler instructions
6604 themselves and does not know what they mean or even whether they are valid
6605 assembler input. However, it does count the statements
6606 (@pxref{Size of an asm}).
6608 You may place multiple assembler instructions together in a single @code{asm}
6609 string, separated by the characters normally used in assembly code for the
6610 system. A combination that works in most places is a newline to break the
6611 line, plus a tab character to move to the instruction field (written as
6612 "\n\t"). Some assemblers allow semicolons as a line separator. However, note
6613 that some assembler dialects use semicolons to start a comment.
6615 Do not expect a sequence of @code{asm} statements to remain perfectly
6616 consecutive after compilation, even when you are using the @code{volatile}
6617 qualifier. If certain instructions need to remain consecutive in the output,
6618 put them in a single multi-instruction asm statement.
6620 Accessing data from C programs without using input/output operands (such as
6621 by using global symbols directly from the assembler template) may not work as
6622 expected. Similarly, calling functions directly from an assembler template
6623 requires a detailed understanding of the target assembler and ABI.
6625 Since GCC does not parse the AssemblerTemplate, it has no visibility of any
6626 symbols it references. This may result in GCC discarding those symbols as
6627 unreferenced unless they are also listed as input, output, or goto operands.
6629 GCC can support multiple assembler dialects (for example, GCC for i386
6630 supports "att" and "intel" dialects) for inline assembler. In builds that
6631 support this capability, the @option{-masm} option controls which dialect
6632 GCC uses as its default. The hardware-specific documentation for the
6633 @option{-masm} option contains the list of supported dialects, as well as the
6634 default dialect if the option is not specified. This information may be
6635 important to understand, since assembler code that works correctly when
6636 compiled using one dialect will likely fail if compiled using another.
6638 @subsubheading Using braces in @code{asm} templates
6640 If your code needs to support multiple assembler dialects (for example, if
6641 you are writing public headers that need to support a variety of compilation
6642 options), use constructs of this form:
6645 @{ dialect0 | dialect1 | dialect2... @}
6648 This construct outputs 'dialect0' when using dialect #0 to compile the code,
6649 'dialect1' for dialect #1, etc. If there are fewer alternatives within the
6650 braces than the number of dialects the compiler supports, the construct
6653 For example, if an i386 compiler supports two dialects (att, intel), an
6654 assembler template such as this:
6657 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
6660 would produce the output:
6663 For att: "btl %[Offset],%[Base] ; jc %l2"
6664 For intel: "bt %[Base],%[Offset]; jc %l2"
6667 Using that same compiler, this code:
6670 "xchg@{l@}\t@{%%@}ebx, %1"
6676 For att: "xchgl\t%%ebx, %1"
6677 For intel: "xchg\tebx, %1"
6680 There is no support for nesting dialect alternatives. Also, there is no
6681 ``escape'' for an open brace (@{), so do not use open braces in an Extended
6682 @code{asm} template other than as a dialect indicator.
6684 @subsubheading Other format strings
6686 In addition to the tokens described by the input, output, and goto operands,
6687 there are a few special cases:
6691 "%%" outputs a single "%" into the assembler code.
6694 "%=" outputs a number that is unique to each instance of the @code{asm}
6695 statement in the entire compilation. This option is useful when creating local
6696 labels and referring to them multiple times in a single template that
6697 generates multiple assembler instructions.
6701 @anchor{OutputOperands}
6702 @subsubsection Output Operands
6703 @cindex @code{asm} output operands
6705 An @code{asm} statement has zero or more output operands indicating the names
6706 of C variables modified by the assembler code.
6708 In this i386 example, @var{old} (referred to in the template string as
6709 @code{%0}) and @var{*Base} (as @code{%1}) are outputs and @var{Offset}
6710 (@code{%2}) is an input:
6715 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
6716 "sbb %0,%0" // Use the CF to calculate old.
6717 : "=r" (old), "+rm" (*Base)
6724 Operands use this format:
6727 [ [asmSymbolicName] ] "constraint" (cvariablename)
6730 @emph{asmSymbolicName}
6733 When not using asmSymbolicNames, use the (zero-based) position of the operand
6734 in the list of operands in the assembler template. For example if there are
6735 three output operands, use @code{%0} in the template to refer to the first,
6736 @code{%1} for the second, and @code{%2} for the third. When using an
6737 asmSymbolicName, reference it by enclosing the name in square brackets
6738 (i.e. @code{%[Value]}). The scope of the name is the @code{asm} statement
6739 that contains the definition. Any valid C variable name is acceptable,
6740 including names already defined in the surrounding code. No two operands
6741 within the same @code{asm} statement can use the same symbolic name.
6745 Output constraints must begin with either @code{"="} (a variable overwriting an
6746 existing value) or @code{"+"} (when reading and writing). When using
6747 @code{"="}, do not assume the location will contain the existing value (except
6748 when tying the variable to an input; @pxref{InputOperands,,Input Operands}).
6750 After the prefix, there must be one or more additional constraints
6751 (@pxref{Constraints}) that describe where the value resides. Common
6752 constraints include @code{"r"} for register and @code{"m"} for memory.
6753 When you list more than one possible location (for example @code{"=rm"}), the
6754 compiler chooses the most efficient one based on the current context. If you
6755 list as many alternates as the @code{asm} statement allows, you will permit
6756 the optimizers to produce the best possible code. If you must use a specific
6757 register, but your Machine Constraints do not provide sufficient
6758 control to select the specific register you want, Local Reg Vars may provide
6759 a solution (@pxref{Local Reg Vars}).
6761 @emph{cvariablename}
6763 Specifies the C variable name of the output (enclosed by parentheses). Accepts
6764 any (non-constant) variable within scope.
6768 The total number of input + output + goto operands has a limit of 30. Commas
6769 separate the operands. When the compiler selects the registers to use to
6770 represent the output operands, it will not use any of the clobbered registers
6773 Output operand expressions must be lvalues. The compiler cannot check whether
6774 the operands have data types that are reasonable for the instruction being
6775 executed. For output expressions that are not directly addressable (for
6776 example a bit-field), the constraint must allow a register. In that case, GCC
6777 uses the register as the output of the @code{asm}, and then stores that
6778 register into the output.
6780 Unless an output operand has the '@code{&}' constraint modifier
6781 (@pxref{Modifiers}), GCC may allocate it in the same register as an unrelated
6782 input operand, on the assumption that the assembler code will consume its
6783 inputs before producing outputs. This assumption may be false if the assembler
6784 code actually consists of more than one instruction. In this case, use
6785 '@code{&}' on each output operand that must not overlap an input.
6787 The same problem can occur if one output parameter (@var{a}) allows a register
6788 constraint and another output parameter (@var{b}) allows a memory constraint.
6789 The code generated by GCC to access the memory address in @var{b} can contain
6790 registers which @emph{might} be shared by @var{a}, and GCC considers those
6791 registers to be inputs to the asm. As above, GCC assumes that such input
6792 registers are consumed before any outputs are written. This assumption may
6793 result in incorrect behavior if the asm writes to @var{a} before using
6794 @var{b}. Combining the `@code{&}' constraint with the register constraint
6795 ensures that modifying @var{a} will not affect what address is referenced by
6796 @var{b}. Omitting the `@code{&}' constraint means that the location of @var{b}
6797 will be undefined if @var{a} is modified before using @var{b}.
6799 @code{asm} supports operand modifiers on operands (for example @code{%k2}
6800 instead of simply @code{%2}). Typically these qualifiers are hardware
6801 dependent. The list of supported modifiers for i386 is found at
6802 @ref{i386Operandmodifiers,i386 Operand modifiers}.
6804 If the C code that follows the @code{asm} makes no use of any of the output
6805 operands, use @code{volatile} for the @code{asm} statement to prevent the
6806 optimizers from discarding the @code{asm} statement as unneeded
6807 (see @ref{Volatile}).
6811 This code makes no use of the optional asmSymbolicName. Therefore it
6812 references the first output operand as @code{%0} (were there a second, it
6813 would be @code{%1}, etc). The number of the first input operand is one greater
6814 than that of the last output operand. In this i386 example, that makes
6815 @var{Mask} @code{%1}:
6818 uint32_t Mask = 1234;
6827 That code overwrites the variable Index ("="), placing the value in a register
6828 ("r"). The generic "r" constraint instead of a constraint for a specific
6829 register allows the compiler to pick the register to use, which can result
6830 in more efficient code. This may not be possible if an assembler instruction
6831 requires a specific register.
6833 The following i386 example uses the asmSymbolicName operand. It produces the
6834 same result as the code above, but some may consider it more readable or more
6835 maintainable since reordering index numbers is not necessary when adding or
6836 removing operands. The names aIndex and aMask are only used to emphasize which
6837 names get used where. It is acceptable to reuse the names Index and Mask.
6840 uint32_t Mask = 1234;
6843 asm ("bsfl %[aMask], %[aIndex]"
6844 : [aIndex] "=r" (Index)
6845 : [aMask] "r" (Mask)
6849 Here are some more examples of output operands.
6856 asm ("mov %[e], %[d]"
6861 Here, @var{d} may either be in a register or in memory. Since the compiler
6862 might already have the current value of the uint32_t pointed to by @var{e}
6863 in a register, you can enable it to choose the best location
6864 for @var{d} by specifying both constraints.
6866 @anchor{InputOperands}
6867 @subsubsection Input Operands
6868 @cindex @code{asm} input operands
6869 @cindex @code{asm} expressions
6871 Input operands make inputs from C variables and expressions available to the
6874 Specify input operands by using the format:
6877 [ [asmSymbolicName] ] "constraint" (cexpression)
6880 @emph{asmSymbolicName}
6882 When not using asmSymbolicNames, use the (zero-based) position of the operand
6883 in the list of operands, including outputs, in the assembler template. For
6884 example, if there are two output parameters and three inputs, @code{%2} refers
6885 to the first input, @code{%3} to the second, and @code{%4} to the third.
6886 When using an asmSymbolicName, reference it by enclosing the name in square
6887 brackets (e.g. @code{%[Value]}). The scope of the name is the @code{asm}
6888 statement that contains the definition. Any valid C variable name is
6889 acceptable, including names already defined in the surrounding code. No two
6890 operands within the same @code{asm} statement can use the same symbolic name.
6894 Input constraints must be a string containing one or more constraints
6895 (@pxref{Constraints}). When you give more than one possible constraint
6896 (for example, @code{"irm"}), the compiler will choose the most efficient
6897 method based on the current context. Input constraints may not begin with
6898 either "=" or "+". If you must use a specific register, but your Machine
6899 Constraints do not provide sufficient control to select the specific
6900 register you want, Local Reg Vars may provide a solution
6901 (@pxref{Local Reg Vars}).
6903 Input constraints can also be digits (for example, @code{"0"}). This indicates
6904 that the specified input will be in the same place as the output constraint
6905 at the (zero-based) index in the output constraint list. When using
6906 asmSymbolicNames for the output operands, you may use these names (enclosed
6907 in brackets []) instead of digits.
6911 This is the C variable or expression being passed to the @code{asm} statement
6914 When the compiler selects the registers to use to represent the input
6915 operands, it will not use any of the clobbered registers (@pxref{Clobbers}).
6917 If there are no output operands but there are input operands, place two
6918 consecutive colons where the output operands would go:
6921 __asm__ ("some instructions"
6926 @strong{Warning:} Do @emph{not} modify the contents of input-only operands
6927 (except for inputs tied to outputs). The compiler assumes that on exit from
6928 the @code{asm} statement these operands will contain the same values as they
6929 had before executing the assembler. It is @emph{not} possible to use Clobbers
6930 to inform the compiler that the values in these inputs are changing. One
6931 common work-around is to tie the changing input variable to an output variable
6932 that never gets used. Note, however, that if the code that follows the
6933 @code{asm} statement makes no use of any of the output operands, the GCC
6934 optimizers may discard the @code{asm} statement as unneeded
6935 (see @ref{Volatile}).
6939 The total number of input + output + goto operands has a limit of 30.
6941 @code{asm} supports operand modifiers on operands (for example @code{%k2}
6942 instead of simply @code{%2}). Typically these qualifiers are hardware
6943 dependent. The list of supported modifiers for i386 is found at
6944 @ref{i386Operandmodifiers,i386 Operand modifiers}.
6948 In this example using the fictitious @code{combine} instruction, the
6949 constraint @code{"0"} for input operand 1 says that it must occupy the same
6950 location as output operand 0. Only input operands may use numbers in
6951 constraints, and they must each refer to an output operand. Only a number (or
6952 the symbolic assembler name) in the constraint can guarantee that one operand
6953 is in the same place as another. The mere fact that @var{foo} is the value of
6954 both operands is not enough to guarantee that they are in the same place in
6955 the generated assembler code.
6958 asm ("combine %2, %0"
6960 : "0" (foo), "g" (bar));
6963 Here is an example using symbolic names.
6966 asm ("cmoveq %1, %2, %[result]"
6967 : [result] "=r"(result)
6968 : "r" (test), "r" (new), "[result]" (old));
6972 @subsubsection Clobbers
6973 @cindex @code{asm} clobbers
6975 While the compiler is aware of changes to entries listed in the output
6976 operands, the assembler code may modify more than just the outputs. For
6977 example, calculations may require additional registers, or the processor may
6978 overwrite a register as a side effect of a particular assembler instruction.
6979 In order to inform the compiler of these changes, list them in the clobber
6980 list. Clobber list items are either register names or the special clobbers
6981 (listed below). Each clobber list item is enclosed in double quotes and
6982 separated by commas.
6984 Clobber descriptions may not in any way overlap with an input or output
6985 operand. For example, you may not have an operand describing a register class
6986 with one member when listing that register in the clobber list. Variables
6987 declared to live in specific registers (@pxref{Explicit Reg Vars}), and used
6988 as @code{asm} input or output operands, must have no part mentioned in the
6989 clobber description. In particular, there is no way to specify that input
6990 operands get modified without also specifying them as output operands.
6992 When the compiler selects which registers to use to represent input and output
6993 operands, it will not use any of the clobbered registers. As a result,
6994 clobbered registers are available for any use in the assembler code.
6996 Here is a realistic example for the VAX showing the use of clobbered
7000 asm volatile ("movc3 %0, %1, %2"
7002 : "g" (from), "g" (to), "g" (count)
7003 : "r0", "r1", "r2", "r3", "r4", "r5");
7006 Also, there are two special clobber arguments:
7010 The @code{"cc"} clobber indicates that the assembler code modifies the flags
7011 register. On some machines, GCC represents the condition codes as a specific
7012 hardware register; "cc" serves to name this register. On other machines,
7013 condition code handling is different, and specifying "cc" has no effect. But
7014 it is valid no matter what the machine.
7017 The "memory" clobber tells the compiler that the assembly code performs memory
7018 reads or writes to items other than those listed in the input and output
7019 operands (for example accessing the memory pointed to by one of the input
7020 parameters). To ensure memory contains correct values, GCC may need to flush
7021 specific register values to memory before executing the @code{asm}. Further,
7022 the compiler will not assume that any values read from memory before an
7023 @code{asm} will remain unchanged after that @code{asm}; it will reload them as
7024 needed. This effectively forms a read/write memory barrier for the compiler.
7026 Note that this clobber does not prevent the @emph{processor} from doing
7027 speculative reads past the @code{asm} statement. To prevent that, you need
7028 processor-specific fence instructions.
7030 Flushing registers to memory has performance implications and may be an issue
7031 for time-sensitive code. One trick to avoid this is available if the size of
7032 the memory being accessed is known at compile time. For example, if accessing
7033 ten bytes of a string, use a memory input like:
7035 @code{@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}}.
7040 @subsubsection Goto Labels
7041 @cindex @code{asm} goto labels
7043 @code{asm goto} allows assembly code to jump to one or more C labels. The
7044 GotoLabels section in an @code{asm goto} statement contains a comma-separated
7045 list of all C labels to which the assembler code may jump. GCC assumes that
7046 @code{asm} execution falls through to the next statement (if this is not the
7047 case, consider using the @code{__builtin_unreachable} intrinsic after the
7048 @code{asm} statement). Optimization of @code{asm goto} may be improved by
7049 using the @code{hot} and @code{cold} label attributes (@pxref{Label
7050 Attributes}). The total number of input + output + goto operands has
7053 An @code{asm goto} statement can not have outputs (which means that the
7054 statement is implicitly volatile). This is due to an internal restriction of
7055 the compiler: control transfer instructions cannot have outputs. If the
7056 assembler code does modify anything, use the "memory" clobber to force the
7057 optimizers to flush all register values to memory, and reload them if
7058 necessary, after the @code{asm} statement.
7060 To reference a label, prefix it with @code{%l} (that's a lowercase L) followed
7061 by its (zero-based) position in GotoLabels plus the number of input
7062 arguments. For example, if the @code{asm} has three inputs and references two
7063 labels, refer to the first label as @code{%l3} and the second as @code{%l4}).
7065 @code{asm} statements may not perform jumps into other @code{asm} statements.
7066 GCC's optimizers do not know about these jumps; therefore they cannot take
7067 account of them when deciding how to optimize.
7069 Example code for i386 might look like:
7076 : "r" (p1), "r" (p2)
7086 The following example shows an @code{asm goto} that uses the memory clobber.
7092 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
7103 @anchor{i386Operandmodifiers}
7104 @subsubsection i386 Operand modifiers
7106 Input, output, and goto operands for extended @code{asm} statements can use
7107 modifiers to affect the code output to the assembler. For example, the
7108 following code uses the "h" and "b" modifiers for i386:
7112 asm volatile ("xchg %h0, %b0" : "+a" (num) );
7115 These modifiers generate this assembler code:
7121 The rest of this discussion uses the following code for illustrative purposes.
7130 asm volatile goto ("some assembler instructions here"
7132 : "q" (iInt), "X" (sizeof(unsigned char) + 1)
7133 : /* No clobbers. */
7138 With no modifiers, this is what the output from the operands would be for the
7139 att and intel dialects of assembler:
7141 @multitable {Operand} {masm=att} {OFFSET FLAT:.L2}
7142 @headitem Operand @tab masm=att @tab masm=intel
7151 @tab @code{OFFSET FLAT:.L2}
7154 The table below shows the list of supported modifiers and their effects.
7156 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {masm=att} {masm=intel}
7157 @headitem Modifier @tab Description @tab Operand @tab @option{masm=att} @tab @option{masm=intel}
7159 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
7164 @tab Print the QImode name of the register.
7169 @tab Print the QImode name for a ``high'' register.
7174 @tab Print the HImode name of the register.
7179 @tab Print the SImode name of the register.
7184 @tab Print the DImode name of the register.
7189 @tab Print the label name with no punctuation.
7194 @tab Require a constant operand and print the constant expression with no punctuation.
7200 @anchor{i386floatingpointasmoperands}
7201 @subsubsection i386 floating-point asm operands
7203 On i386 targets, there are several rules on the usage of stack-like registers
7204 in the operands of an @code{asm}. These rules apply only to the operands
7205 that are stack-like registers:
7209 Given a set of input registers that die in an @code{asm}, it is
7210 necessary to know which are implicitly popped by the @code{asm}, and
7211 which must be explicitly popped by GCC@.
7213 An input register that is implicitly popped by the @code{asm} must be
7214 explicitly clobbered, unless it is constrained to match an
7218 For any input register that is implicitly popped by an @code{asm}, it is
7219 necessary to know how to adjust the stack to compensate for the pop.
7220 If any non-popped input is closer to the top of the reg-stack than
7221 the implicitly popped register, it would not be possible to know what the
7222 stack looked like---it's not clear how the rest of the stack ``slides
7225 All implicitly popped input registers must be closer to the top of
7226 the reg-stack than any input that is not implicitly popped.
7228 It is possible that if an input dies in an @code{asm}, the compiler might
7229 use the input register for an output reload. Consider this example:
7232 asm ("foo" : "=t" (a) : "f" (b));
7236 This code says that input @code{b} is not popped by the @code{asm}, and that
7237 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one
7238 deeper after the @code{asm} than it was before. But, it is possible that
7239 reload may think that it can use the same register for both the input and
7242 To prevent this from happening,
7243 if any input operand uses the @code{f} constraint, all output register
7244 constraints must use the @code{&} early-clobber modifier.
7246 The example above would be correctly written as:
7249 asm ("foo" : "=&t" (a) : "f" (b));
7253 Some operands need to be in particular places on the stack. All
7254 output operands fall in this category---GCC has no other way to
7255 know which registers the outputs appear in unless you indicate
7256 this in the constraints.
7258 Output operands must specifically indicate which register an output
7259 appears in after an @code{asm}. @code{=f} is not allowed: the operand
7260 constraints must select a class with a single register.
7263 Output operands may not be ``inserted'' between existing stack registers.
7264 Since no 387 opcode uses a read/write operand, all output operands
7265 are dead before the @code{asm}, and are pushed by the @code{asm}.
7266 It makes no sense to push anywhere but the top of the reg-stack.
7268 Output operands must start at the top of the reg-stack: output
7269 operands may not ``skip'' a register.
7272 Some @code{asm} statements may need extra stack space for internal
7273 calculations. This can be guaranteed by clobbering stack registers
7274 unrelated to the inputs and outputs.
7278 Here are a couple of reasonable @code{asm}s to want to write. This
7280 takes one input, which is internally popped, and produces two outputs.
7283 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
7287 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode,
7288 and replaces them with one output. The @code{st(1)} clobber is necessary
7289 for the compiler to know that @code{fyl2xp1} pops both inputs.
7292 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
7300 @subsection Controlling Names Used in Assembler Code
7301 @cindex assembler names for identifiers
7302 @cindex names used in assembler code
7303 @cindex identifiers, names in assembler code
7305 You can specify the name to be used in the assembler code for a C
7306 function or variable by writing the @code{asm} (or @code{__asm__})
7307 keyword after the declarator as follows:
7310 int foo asm ("myfoo") = 2;
7314 This specifies that the name to be used for the variable @code{foo} in
7315 the assembler code should be @samp{myfoo} rather than the usual
7318 On systems where an underscore is normally prepended to the name of a C
7319 function or variable, this feature allows you to define names for the
7320 linker that do not start with an underscore.
7322 It does not make sense to use this feature with a non-static local
7323 variable since such variables do not have assembler names. If you are
7324 trying to put the variable in a particular register, see @ref{Explicit
7325 Reg Vars}. GCC presently accepts such code with a warning, but will
7326 probably be changed to issue an error, rather than a warning, in the
7329 You cannot use @code{asm} in this way in a function @emph{definition}; but
7330 you can get the same effect by writing a declaration for the function
7331 before its definition and putting @code{asm} there, like this:
7334 extern func () asm ("FUNC");
7341 It is up to you to make sure that the assembler names you choose do not
7342 conflict with any other assembler symbols. Also, you must not use a
7343 register name; that would produce completely invalid assembler code. GCC
7344 does not as yet have the ability to store static variables in registers.
7345 Perhaps that will be added.
7347 @node Explicit Reg Vars
7348 @subsection Variables in Specified Registers
7349 @cindex explicit register variables
7350 @cindex variables in specified registers
7351 @cindex specified registers
7352 @cindex registers, global allocation
7354 GNU C allows you to put a few global variables into specified hardware
7355 registers. You can also specify the register in which an ordinary
7356 register variable should be allocated.
7360 Global register variables reserve registers throughout the program.
7361 This may be useful in programs such as programming language
7362 interpreters that have a couple of global variables that are accessed
7366 Local register variables in specific registers do not reserve the
7367 registers, except at the point where they are used as input or output
7368 operands in an @code{asm} statement and the @code{asm} statement itself is
7369 not deleted. The compiler's data flow analysis is capable of determining
7370 where the specified registers contain live values, and where they are
7371 available for other uses. Stores into local register variables may be deleted
7372 when they appear to be dead according to dataflow analysis. References
7373 to local register variables may be deleted or moved or simplified.
7375 These local variables are sometimes convenient for use with the extended
7376 @code{asm} feature (@pxref{Extended Asm}), if you want to write one
7377 output of the assembler instruction directly into a particular register.
7378 (This works provided the register you specify fits the constraints
7379 specified for that operand in the @code{asm}.)
7387 @node Global Reg Vars
7388 @subsubsection Defining Global Register Variables
7389 @cindex global register variables
7390 @cindex registers, global variables in
7392 You can define a global register variable in GNU C like this:
7395 register int *foo asm ("a5");
7399 Here @code{a5} is the name of the register that should be used. Choose a
7400 register that is normally saved and restored by function calls on your
7401 machine, so that library routines will not clobber it.
7403 Naturally the register name is cpu-dependent, so you need to
7404 conditionalize your program according to cpu type. The register
7405 @code{a5} is a good choice on a 68000 for a variable of pointer
7406 type. On machines with register windows, be sure to choose a ``global''
7407 register that is not affected magically by the function call mechanism.
7409 In addition, different operating systems on the same CPU may differ in how they
7410 name the registers; then you need additional conditionals. For
7411 example, some 68000 operating systems call this register @code{%a5}.
7413 Eventually there may be a way of asking the compiler to choose a register
7414 automatically, but first we need to figure out how it should choose and
7415 how to enable you to guide the choice. No solution is evident.
7417 Defining a global register variable in a certain register reserves that
7418 register entirely for this use, at least within the current compilation.
7419 The register is not allocated for any other purpose in the functions
7420 in the current compilation, and is not saved and restored by
7421 these functions. Stores into this register are never deleted even if they
7422 appear to be dead, but references may be deleted or moved or
7425 It is not safe to access the global register variables from signal
7426 handlers, or from more than one thread of control, because the system
7427 library routines may temporarily use the register for other things (unless
7428 you recompile them specially for the task at hand).
7430 @cindex @code{qsort}, and global register variables
7431 It is not safe for one function that uses a global register variable to
7432 call another such function @code{foo} by way of a third function
7433 @code{lose} that is compiled without knowledge of this variable (i.e.@: in a
7434 different source file in which the variable isn't declared). This is
7435 because @code{lose} might save the register and put some other value there.
7436 For example, you can't expect a global register variable to be available in
7437 the comparison-function that you pass to @code{qsort}, since @code{qsort}
7438 might have put something else in that register. (If you are prepared to
7439 recompile @code{qsort} with the same global register variable, you can
7440 solve this problem.)
7442 If you want to recompile @code{qsort} or other source files that do not
7443 actually use your global register variable, so that they do not use that
7444 register for any other purpose, then it suffices to specify the compiler
7445 option @option{-ffixed-@var{reg}}. You need not actually add a global
7446 register declaration to their source code.
7448 A function that can alter the value of a global register variable cannot
7449 safely be called from a function compiled without this variable, because it
7450 could clobber the value the caller expects to find there on return.
7451 Therefore, the function that is the entry point into the part of the
7452 program that uses the global register variable must explicitly save and
7453 restore the value that belongs to its caller.
7455 @cindex register variable after @code{longjmp}
7456 @cindex global register after @code{longjmp}
7457 @cindex value after @code{longjmp}
7460 On most machines, @code{longjmp} restores to each global register
7461 variable the value it had at the time of the @code{setjmp}. On some
7462 machines, however, @code{longjmp} does not change the value of global
7463 register variables. To be portable, the function that called @code{setjmp}
7464 should make other arrangements to save the values of the global register
7465 variables, and to restore them in a @code{longjmp}. This way, the same
7466 thing happens regardless of what @code{longjmp} does.
7468 All global register variable declarations must precede all function
7469 definitions. If such a declaration could appear after function
7470 definitions, the declaration would be too late to prevent the register from
7471 being used for other purposes in the preceding functions.
7473 Global register variables may not have initial values, because an
7474 executable file has no means to supply initial contents for a register.
7476 On the SPARC, there are reports that g3 @dots{} g7 are suitable
7477 registers, but certain library functions, such as @code{getwd}, as well
7478 as the subroutines for division and remainder, modify g3 and g4. g1 and
7479 g2 are local temporaries.
7481 On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7.
7482 Of course, it does not do to use more than a few of those.
7484 @node Local Reg Vars
7485 @subsubsection Specifying Registers for Local Variables
7486 @cindex local variables, specifying registers
7487 @cindex specifying registers for local variables
7488 @cindex registers for local variables
7490 You can define a local register variable with a specified register
7494 register int *foo asm ("a5");
7498 Here @code{a5} is the name of the register that should be used. Note
7499 that this is the same syntax used for defining global register
7500 variables, but for a local variable it appears within a function.
7502 Naturally the register name is cpu-dependent, but this is not a
7503 problem, since specific registers are most often useful with explicit
7504 assembler instructions (@pxref{Extended Asm}). Both of these things
7505 generally require that you conditionalize your program according to
7508 In addition, operating systems on one type of cpu may differ in how they
7509 name the registers; then you need additional conditionals. For
7510 example, some 68000 operating systems call this register @code{%a5}.
7512 Defining such a register variable does not reserve the register; it
7513 remains available for other uses in places where flow control determines
7514 the variable's value is not live.
7516 This option does not guarantee that GCC generates code that has
7517 this variable in the register you specify at all times. You may not
7518 code an explicit reference to this register in the @emph{assembler
7519 instruction template} part of an @code{asm} statement and assume it
7520 always refers to this variable. However, using the variable as an
7521 @code{asm} @emph{operand} guarantees that the specified register is used
7524 Stores into local register variables may be deleted when they appear to be dead
7525 according to dataflow analysis. References to local register variables may
7526 be deleted or moved or simplified.
7528 As with global register variables, it is recommended that you choose a
7529 register that is normally saved and restored by function calls on
7530 your machine, so that library routines will not clobber it.
7532 Sometimes when writing inline @code{asm} code, you need to make an operand be a
7533 specific register, but there's no matching constraint letter for that
7534 register. To force the operand into that register, create a local variable
7535 and specify the register in the variable's declaration. Then use the local
7536 variable for the asm operand and specify any constraint letter that matches
7540 register int *p1 asm ("r0") = @dots{};
7541 register int *p2 asm ("r1") = @dots{};
7542 register int *result asm ("r0");
7543 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
7546 @emph{Warning:} In the above example, be aware that a register (for example r0) can be
7547 call-clobbered by subsequent code, including function calls and library calls
7548 for arithmetic operators on other variables (for example the initialization
7549 of p2). In this case, use temporary variables for expressions between the
7550 register assignments:
7554 register int *p1 asm ("r0") = @dots{};
7555 register int *p2 asm ("r1") = t1;
7556 register int *result asm ("r0");
7557 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
7560 @node Size of an asm
7561 @subsection Size of an @code{asm}
7563 Some targets require that GCC track the size of each instruction used
7564 in order to generate correct code. Because the final length of the
7565 code produced by an @code{asm} statement is only known by the
7566 assembler, GCC must make an estimate as to how big it will be. It
7567 does this by counting the number of instructions in the pattern of the
7568 @code{asm} and multiplying that by the length of the longest
7569 instruction supported by that processor. (When working out the number
7570 of instructions, it assumes that any occurrence of a newline or of
7571 whatever statement separator character is supported by the assembler --
7572 typically @samp{;} --- indicates the end of an instruction.)
7574 Normally, GCC's estimate is adequate to ensure that correct
7575 code is generated, but it is possible to confuse the compiler if you use
7576 pseudo instructions or assembler macros that expand into multiple real
7577 instructions, or if you use assembler directives that expand to more
7578 space in the object file than is needed for a single instruction.
7579 If this happens then the assembler may produce a diagnostic saying that
7580 a label is unreachable.
7582 @node Alternate Keywords
7583 @section Alternate Keywords
7584 @cindex alternate keywords
7585 @cindex keywords, alternate
7587 @option{-ansi} and the various @option{-std} options disable certain
7588 keywords. This causes trouble when you want to use GNU C extensions, or
7589 a general-purpose header file that should be usable by all programs,
7590 including ISO C programs. The keywords @code{asm}, @code{typeof} and
7591 @code{inline} are not available in programs compiled with
7592 @option{-ansi} or @option{-std} (although @code{inline} can be used in a
7593 program compiled with @option{-std=c99} or @option{-std=c11}). The
7595 @code{restrict} is only available when @option{-std=gnu99} (which will
7596 eventually be the default) or @option{-std=c99} (or the equivalent
7597 @option{-std=iso9899:1999}), or an option for a later standard
7600 The way to solve these problems is to put @samp{__} at the beginning and
7601 end of each problematical keyword. For example, use @code{__asm__}
7602 instead of @code{asm}, and @code{__inline__} instead of @code{inline}.
7604 Other C compilers won't accept these alternative keywords; if you want to
7605 compile with another compiler, you can define the alternate keywords as
7606 macros to replace them with the customary keywords. It looks like this:
7614 @findex __extension__
7616 @option{-pedantic} and other options cause warnings for many GNU C extensions.
7618 prevent such warnings within one expression by writing
7619 @code{__extension__} before the expression. @code{__extension__} has no
7620 effect aside from this.
7622 @node Incomplete Enums
7623 @section Incomplete @code{enum} Types
7625 You can define an @code{enum} tag without specifying its possible values.
7626 This results in an incomplete type, much like what you get if you write
7627 @code{struct foo} without describing the elements. A later declaration
7628 that does specify the possible values completes the type.
7630 You can't allocate variables or storage using the type while it is
7631 incomplete. However, you can work with pointers to that type.
7633 This extension may not be very useful, but it makes the handling of
7634 @code{enum} more consistent with the way @code{struct} and @code{union}
7637 This extension is not supported by GNU C++.
7639 @node Function Names
7640 @section Function Names as Strings
7641 @cindex @code{__func__} identifier
7642 @cindex @code{__FUNCTION__} identifier
7643 @cindex @code{__PRETTY_FUNCTION__} identifier
7645 GCC provides three magic variables that hold the name of the current
7646 function, as a string. The first of these is @code{__func__}, which
7647 is part of the C99 standard:
7649 The identifier @code{__func__} is implicitly declared by the translator
7650 as if, immediately following the opening brace of each function
7651 definition, the declaration
7654 static const char __func__[] = "function-name";
7658 appeared, where function-name is the name of the lexically-enclosing
7659 function. This name is the unadorned name of the function.
7661 @code{__FUNCTION__} is another name for @code{__func__}. Older
7662 versions of GCC recognize only this name. However, it is not
7663 standardized. For maximum portability, we recommend you use
7664 @code{__func__}, but provide a fallback definition with the
7668 #if __STDC_VERSION__ < 199901L
7670 # define __func__ __FUNCTION__
7672 # define __func__ "<unknown>"
7677 In C, @code{__PRETTY_FUNCTION__} is yet another name for
7678 @code{__func__}. However, in C++, @code{__PRETTY_FUNCTION__} contains
7679 the type signature of the function as well as its bare name. For
7680 example, this program:
7684 extern int printf (char *, ...);
7691 printf ("__FUNCTION__ = %s\n", __FUNCTION__);
7692 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
7710 __PRETTY_FUNCTION__ = void a::sub(int)
7713 These identifiers are not preprocessor macros. In GCC 3.3 and
7714 earlier, in C only, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__}
7715 were treated as string literals; they could be used to initialize
7716 @code{char} arrays, and they could be concatenated with other string
7717 literals. GCC 3.4 and later treat them as variables, like
7718 @code{__func__}. In C++, @code{__FUNCTION__} and
7719 @code{__PRETTY_FUNCTION__} have always been variables.
7721 @node Return Address
7722 @section Getting the Return or Frame Address of a Function
7724 These functions may be used to get information about the callers of a
7727 @deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level})
7728 This function returns the return address of the current function, or of
7729 one of its callers. The @var{level} argument is number of frames to
7730 scan up the call stack. A value of @code{0} yields the return address
7731 of the current function, a value of @code{1} yields the return address
7732 of the caller of the current function, and so forth. When inlining
7733 the expected behavior is that the function returns the address of
7734 the function that is returned to. To work around this behavior use
7735 the @code{noinline} function attribute.
7737 The @var{level} argument must be a constant integer.
7739 On some machines it may be impossible to determine the return address of
7740 any function other than the current one; in such cases, or when the top
7741 of the stack has been reached, this function returns @code{0} or a
7742 random value. In addition, @code{__builtin_frame_address} may be used
7743 to determine if the top of the stack has been reached.
7745 Additional post-processing of the returned value may be needed, see
7746 @code{__builtin_extract_return_addr}.
7748 This function should only be used with a nonzero argument for debugging
7752 @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr})
7753 The address as returned by @code{__builtin_return_address} may have to be fed
7754 through this function to get the actual encoded address. For example, on the
7755 31-bit S/390 platform the highest bit has to be masked out, or on SPARC
7756 platforms an offset has to be added for the true next instruction to be
7759 If no fixup is needed, this function simply passes through @var{addr}.
7762 @deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr})
7763 This function does the reverse of @code{__builtin_extract_return_addr}.
7766 @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level})
7767 This function is similar to @code{__builtin_return_address}, but it
7768 returns the address of the function frame rather than the return address
7769 of the function. Calling @code{__builtin_frame_address} with a value of
7770 @code{0} yields the frame address of the current function, a value of
7771 @code{1} yields the frame address of the caller of the current function,
7774 The frame is the area on the stack that holds local variables and saved
7775 registers. The frame address is normally the address of the first word
7776 pushed on to the stack by the function. However, the exact definition
7777 depends upon the processor and the calling convention. If the processor
7778 has a dedicated frame pointer register, and the function has a frame,
7779 then @code{__builtin_frame_address} returns the value of the frame
7782 On some machines it may be impossible to determine the frame address of
7783 any function other than the current one; in such cases, or when the top
7784 of the stack has been reached, this function returns @code{0} if
7785 the first frame pointer is properly initialized by the startup code.
7787 This function should only be used with a nonzero argument for debugging
7791 @node Vector Extensions
7792 @section Using Vector Instructions through Built-in Functions
7794 On some targets, the instruction set contains SIMD vector instructions which
7795 operate on multiple values contained in one large register at the same time.
7796 For example, on the i386 the MMX, 3DNow!@: and SSE extensions can be used
7799 The first step in using these extensions is to provide the necessary data
7800 types. This should be done using an appropriate @code{typedef}:
7803 typedef int v4si __attribute__ ((vector_size (16)));
7807 The @code{int} type specifies the base type, while the attribute specifies
7808 the vector size for the variable, measured in bytes. For example, the
7809 declaration above causes the compiler to set the mode for the @code{v4si}
7810 type to be 16 bytes wide and divided into @code{int} sized units. For
7811 a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the
7812 corresponding mode of @code{foo} is @acronym{V4SI}.
7814 The @code{vector_size} attribute is only applicable to integral and
7815 float scalars, although arrays, pointers, and function return values
7816 are allowed in conjunction with this construct. Only sizes that are
7817 a power of two are currently allowed.
7819 All the basic integer types can be used as base types, both as signed
7820 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long},
7821 @code{long long}. In addition, @code{float} and @code{double} can be
7822 used to build floating-point vector types.
7824 Specifying a combination that is not valid for the current architecture
7825 causes GCC to synthesize the instructions using a narrower mode.
7826 For example, if you specify a variable of type @code{V4SI} and your
7827 architecture does not allow for this specific SIMD type, GCC
7828 produces code that uses 4 @code{SIs}.
7830 The types defined in this manner can be used with a subset of normal C
7831 operations. Currently, GCC allows using the following operators
7832 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@.
7834 The operations behave like C++ @code{valarrays}. Addition is defined as
7835 the addition of the corresponding elements of the operands. For
7836 example, in the code below, each of the 4 elements in @var{a} is
7837 added to the corresponding 4 elements in @var{b} and the resulting
7838 vector is stored in @var{c}.
7841 typedef int v4si __attribute__ ((vector_size (16)));
7848 Subtraction, multiplication, division, and the logical operations
7849 operate in a similar manner. Likewise, the result of using the unary
7850 minus or complement operators on a vector type is a vector whose
7851 elements are the negative or complemented values of the corresponding
7852 elements in the operand.
7854 It is possible to use shifting operators @code{<<}, @code{>>} on
7855 integer-type vectors. The operation is defined as following: @code{@{a0,
7856 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1,
7857 @dots{}, an >> bn@}}@. Vector operands must have the same number of
7860 For convenience, it is allowed to use a binary vector operation
7861 where one operand is a scalar. In that case the compiler transforms
7862 the scalar operand into a vector where each element is the scalar from
7863 the operation. The transformation happens only if the scalar could be
7864 safely converted to the vector-element type.
7865 Consider the following code.
7868 typedef int v4si __attribute__ ((vector_size (16)));
7873 a = b + 1; /* a = b + @{1,1,1,1@}; */
7874 a = 2 * b; /* a = @{2,2,2,2@} * b; */
7876 a = l + a; /* Error, cannot convert long to int. */
7879 Vectors can be subscripted as if the vector were an array with
7880 the same number of elements and base type. Out of bound accesses
7881 invoke undefined behavior at run time. Warnings for out of bound
7882 accesses for vector subscription can be enabled with
7883 @option{-Warray-bounds}.
7885 Vector comparison is supported with standard comparison
7886 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be
7887 vector expressions of integer-type or real-type. Comparison between
7888 integer-type vectors and real-type vectors are not supported. The
7889 result of the comparison is a vector of the same width and number of
7890 elements as the comparison operands with a signed integral element
7893 Vectors are compared element-wise producing 0 when comparison is false
7894 and -1 (constant of the appropriate type where all bits are set)
7895 otherwise. Consider the following example.
7898 typedef int v4si __attribute__ ((vector_size (16)));
7900 v4si a = @{1,2,3,4@};
7901 v4si b = @{3,2,1,4@};
7904 c = a > b; /* The result would be @{0, 0,-1, 0@} */
7905 c = a == b; /* The result would be @{0,-1, 0,-1@} */
7908 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
7909 @code{b} and @code{c} are vectors of the same type and @code{a} is an
7910 integer vector with the same number of elements of the same size as @code{b}
7911 and @code{c}, computes all three arguments and creates a vector
7912 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
7913 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
7914 As in the case of binary operations, this syntax is also accepted when
7915 one of @code{b} or @code{c} is a scalar that is then transformed into a
7916 vector. If both @code{b} and @code{c} are scalars and the type of
7917 @code{true?b:c} has the same size as the element type of @code{a}, then
7918 @code{b} and @code{c} are converted to a vector type whose elements have
7919 this type and with the same number of elements as @code{a}.
7921 Vector shuffling is available using functions
7922 @code{__builtin_shuffle (vec, mask)} and
7923 @code{__builtin_shuffle (vec0, vec1, mask)}.
7924 Both functions construct a permutation of elements from one or two
7925 vectors and return a vector of the same type as the input vector(s).
7926 The @var{mask} is an integral vector with the same width (@var{W})
7927 and element count (@var{N}) as the output vector.
7929 The elements of the input vectors are numbered in memory ordering of
7930 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The
7931 elements of @var{mask} are considered modulo @var{N} in the single-operand
7932 case and modulo @math{2*@var{N}} in the two-operand case.
7934 Consider the following example,
7937 typedef int v4si __attribute__ ((vector_size (16)));
7939 v4si a = @{1,2,3,4@};
7940 v4si b = @{5,6,7,8@};
7941 v4si mask1 = @{0,1,1,3@};
7942 v4si mask2 = @{0,4,2,5@};
7945 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */
7946 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */
7949 Note that @code{__builtin_shuffle} is intentionally semantically
7950 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions.
7952 You can declare variables and use them in function calls and returns, as
7953 well as in assignments and some casts. You can specify a vector type as
7954 a return type for a function. Vector types can also be used as function
7955 arguments. It is possible to cast from one vector type to another,
7956 provided they are of the same size (in fact, you can also cast vectors
7957 to and from other datatypes of the same size).
7959 You cannot operate between vectors of different lengths or different
7960 signedness without a cast.
7964 @findex __builtin_offsetof
7966 GCC implements for both C and C++ a syntactic extension to implement
7967 the @code{offsetof} macro.
7971 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")"
7973 offsetof_member_designator:
7975 | offsetof_member_designator "." @code{identifier}
7976 | offsetof_member_designator "[" @code{expr} "]"
7979 This extension is sufficient such that
7982 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member})
7986 is a suitable definition of the @code{offsetof} macro. In C++, @var{type}
7987 may be dependent. In either case, @var{member} may consist of a single
7988 identifier, or a sequence of member accesses and array references.
7990 @node __sync Builtins
7991 @section Legacy __sync Built-in Functions for Atomic Memory Access
7993 The following built-in functions
7994 are intended to be compatible with those described
7995 in the @cite{Intel Itanium Processor-specific Application Binary Interface},
7996 section 7.4. As such, they depart from the normal GCC practice of using
7997 the @samp{__builtin_} prefix, and further that they are overloaded such that
7998 they work on multiple types.
8000 The definition given in the Intel documentation allows only for the use of
8001 the types @code{int}, @code{long}, @code{long long} as well as their unsigned
8002 counterparts. GCC allows any integral scalar or pointer type that is
8003 1, 2, 4 or 8 bytes in length.
8005 Not all operations are supported by all target processors. If a particular
8006 operation cannot be implemented on the target processor, a warning is
8007 generated and a call an external function is generated. The external
8008 function carries the same name as the built-in version,
8009 with an additional suffix
8010 @samp{_@var{n}} where @var{n} is the size of the data type.
8012 @c ??? Should we have a mechanism to suppress this warning? This is almost
8013 @c useful for implementing the operation under the control of an external
8016 In most cases, these built-in functions are considered a @dfn{full barrier}.
8018 no memory operand is moved across the operation, either forward or
8019 backward. Further, instructions are issued as necessary to prevent the
8020 processor from speculating loads across the operation and from queuing stores
8021 after the operation.
8023 All of the routines are described in the Intel documentation to take
8024 ``an optional list of variables protected by the memory barrier''. It's
8025 not clear what is meant by that; it could mean that @emph{only} the
8026 following variables are protected, or it could mean that these variables
8027 should in addition be protected. At present GCC ignores this list and
8028 protects all variables that are globally accessible. If in the future
8029 we make some use of this list, an empty list will continue to mean all
8030 globally accessible variables.
8033 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...)
8034 @itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...)
8035 @itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...)
8036 @itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...)
8037 @itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...)
8038 @itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...)
8039 @findex __sync_fetch_and_add
8040 @findex __sync_fetch_and_sub
8041 @findex __sync_fetch_and_or
8042 @findex __sync_fetch_and_and
8043 @findex __sync_fetch_and_xor
8044 @findex __sync_fetch_and_nand
8045 These built-in functions perform the operation suggested by the name, and
8046 returns the value that had previously been in memory. That is,
8049 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @}
8050 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand
8053 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand}
8054 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}.
8056 @item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...)
8057 @itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...)
8058 @itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...)
8059 @itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...)
8060 @itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...)
8061 @itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...)
8062 @findex __sync_add_and_fetch
8063 @findex __sync_sub_and_fetch
8064 @findex __sync_or_and_fetch
8065 @findex __sync_and_and_fetch
8066 @findex __sync_xor_and_fetch
8067 @findex __sync_nand_and_fetch
8068 These built-in functions perform the operation suggested by the name, and
8069 return the new value. That is,
8072 @{ *ptr @var{op}= value; return *ptr; @}
8073 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand
8076 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch}
8077 as @code{*ptr = ~(*ptr & value)} instead of
8078 @code{*ptr = ~*ptr & value}.
8080 @item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
8081 @itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...)
8082 @findex __sync_bool_compare_and_swap
8083 @findex __sync_val_compare_and_swap
8084 These built-in functions perform an atomic compare and swap.
8085 That is, if the current
8086 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into
8089 The ``bool'' version returns true if the comparison is successful and
8090 @var{newval} is written. The ``val'' version returns the contents
8091 of @code{*@var{ptr}} before the operation.
8093 @item __sync_synchronize (...)
8094 @findex __sync_synchronize
8095 This built-in function issues a full memory barrier.
8097 @item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...)
8098 @findex __sync_lock_test_and_set
8099 This built-in function, as described by Intel, is not a traditional test-and-set
8100 operation, but rather an atomic exchange operation. It writes @var{value}
8101 into @code{*@var{ptr}}, and returns the previous contents of
8104 Many targets have only minimal support for such locks, and do not support
8105 a full exchange operation. In this case, a target may support reduced
8106 functionality here by which the @emph{only} valid value to store is the
8107 immediate constant 1. The exact value actually stored in @code{*@var{ptr}}
8108 is implementation defined.
8110 This built-in function is not a full barrier,
8111 but rather an @dfn{acquire barrier}.
8112 This means that references after the operation cannot move to (or be
8113 speculated to) before the operation, but previous memory stores may not
8114 be globally visible yet, and previous memory loads may not yet be
8117 @item void __sync_lock_release (@var{type} *ptr, ...)
8118 @findex __sync_lock_release
8119 This built-in function releases the lock acquired by
8120 @code{__sync_lock_test_and_set}.
8121 Normally this means writing the constant 0 to @code{*@var{ptr}}.
8123 This built-in function is not a full barrier,
8124 but rather a @dfn{release barrier}.
8125 This means that all previous memory stores are globally visible, and all
8126 previous memory loads have been satisfied, but following memory reads
8127 are not prevented from being speculated to before the barrier.
8130 @node __atomic Builtins
8131 @section Built-in functions for memory model aware atomic operations
8133 The following built-in functions approximately match the requirements for
8134 C++11 memory model. Many are similar to the @samp{__sync} prefixed built-in
8135 functions, but all also have a memory model parameter. These are all
8136 identified by being prefixed with @samp{__atomic}, and most are overloaded
8137 such that they work with multiple types.
8139 GCC allows any integral scalar or pointer type that is 1, 2, 4, or 8
8140 bytes in length. 16-byte integral types are also allowed if
8141 @samp{__int128} (@pxref{__int128}) is supported by the architecture.
8143 Target architectures are encouraged to provide their own patterns for
8144 each of these built-in functions. If no target is provided, the original
8145 non-memory model set of @samp{__sync} atomic built-in functions are
8146 utilized, along with any required synchronization fences surrounding it in
8147 order to achieve the proper behavior. Execution in this case is subject
8148 to the same restrictions as those built-in functions.
8150 If there is no pattern or mechanism to provide a lock free instruction
8151 sequence, a call is made to an external routine with the same parameters
8152 to be resolved at run time.
8154 The four non-arithmetic functions (load, store, exchange, and
8155 compare_exchange) all have a generic version as well. This generic
8156 version works on any data type. If the data type size maps to one
8157 of the integral sizes that may have lock free support, the generic
8158 version utilizes the lock free built-in function. Otherwise an
8159 external call is left to be resolved at run time. This external call is
8160 the same format with the addition of a @samp{size_t} parameter inserted
8161 as the first parameter indicating the size of the object being pointed to.
8162 All objects must be the same size.
8164 There are 6 different memory models that can be specified. These map
8165 to the same names in the C++11 standard. Refer there or to the
8166 @uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki on
8167 atomic synchronization} for more detailed definitions. These memory
8168 models integrate both barriers to code motion as well as synchronization
8169 requirements with other threads. These are listed in approximately
8170 ascending order of strength. It is also possible to use target specific
8171 flags for memory model flags, like Hardware Lock Elision.
8174 @item __ATOMIC_RELAXED
8175 No barriers or synchronization.
8176 @item __ATOMIC_CONSUME
8177 Data dependency only for both barrier and synchronization with another
8179 @item __ATOMIC_ACQUIRE
8180 Barrier to hoisting of code and synchronizes with release (or stronger)
8181 semantic stores from another thread.
8182 @item __ATOMIC_RELEASE
8183 Barrier to sinking of code and synchronizes with acquire (or stronger)
8184 semantic loads from another thread.
8185 @item __ATOMIC_ACQ_REL
8186 Full barrier in both directions and synchronizes with acquire loads and
8187 release stores in another thread.
8188 @item __ATOMIC_SEQ_CST
8189 Full barrier in both directions and synchronizes with acquire loads and
8190 release stores in all threads.
8193 When implementing patterns for these built-in functions, the memory model
8194 parameter can be ignored as long as the pattern implements the most
8195 restrictive @code{__ATOMIC_SEQ_CST} model. Any of the other memory models
8196 execute correctly with this memory model but they may not execute as
8197 efficiently as they could with a more appropriate implementation of the
8198 relaxed requirements.
8200 Note that the C++11 standard allows for the memory model parameter to be
8201 determined at run time rather than at compile time. These built-in
8202 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather
8203 than invoke a runtime library call or inline a switch statement. This is
8204 standard compliant, safe, and the simplest approach for now.
8206 The memory model parameter is a signed int, but only the lower 8 bits are
8207 reserved for the memory model. The remainder of the signed int is reserved
8208 for future use and should be 0. Use of the predefined atomic values
8209 ensures proper usage.
8211 @deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memmodel)
8212 This built-in function implements an atomic load operation. It returns the
8213 contents of @code{*@var{ptr}}.
8215 The valid memory model variants are
8216 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
8217 and @code{__ATOMIC_CONSUME}.
8221 @deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memmodel)
8222 This is the generic version of an atomic load. It returns the
8223 contents of @code{*@var{ptr}} in @code{*@var{ret}}.
8227 @deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memmodel)
8228 This built-in function implements an atomic store operation. It writes
8229 @code{@var{val}} into @code{*@var{ptr}}.
8231 The valid memory model variants are
8232 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}.
8236 @deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memmodel)
8237 This is the generic version of an atomic store. It stores the value
8238 of @code{*@var{val}} into @code{*@var{ptr}}.
8242 @deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memmodel)
8243 This built-in function implements an atomic exchange operation. It writes
8244 @var{val} into @code{*@var{ptr}}, and returns the previous contents of
8247 The valid memory model variants are
8248 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE},
8249 @code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}.
8253 @deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memmodel)
8254 This is the generic version of an atomic exchange. It stores the
8255 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value
8256 of @code{*@var{ptr}} is copied into @code{*@var{ret}}.
8260 @deftypefn {Built-in Function} bool __atomic_compare_exchange_n (@var{type} *ptr, @var{type} *expected, @var{type} desired, bool weak, int success_memmodel, int failure_memmodel)
8261 This built-in function implements an atomic compare and exchange operation.
8262 This compares the contents of @code{*@var{ptr}} with the contents of
8263 @code{*@var{expected}} and if equal, writes @var{desired} into
8264 @code{*@var{ptr}}. If they are not equal, the current contents of
8265 @code{*@var{ptr}} is written into @code{*@var{expected}}. @var{weak} is true
8266 for weak compare_exchange, and false for the strong variation. Many targets
8267 only offer the strong variation and ignore the parameter. When in doubt, use
8268 the strong variation.
8270 True is returned if @var{desired} is written into
8271 @code{*@var{ptr}} and the execution is considered to conform to the
8272 memory model specified by @var{success_memmodel}. There are no
8273 restrictions on what memory model can be used here.
8275 False is returned otherwise, and the execution is considered to conform
8276 to @var{failure_memmodel}. This memory model cannot be
8277 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a
8278 stronger model than that specified by @var{success_memmodel}.
8282 @deftypefn {Built-in Function} bool __atomic_compare_exchange (@var{type} *ptr, @var{type} *expected, @var{type} *desired, bool weak, int success_memmodel, int failure_memmodel)
8283 This built-in function implements the generic version of
8284 @code{__atomic_compare_exchange}. The function is virtually identical to
8285 @code{__atomic_compare_exchange_n}, except the desired value is also a
8290 @deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memmodel)
8291 @deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memmodel)
8292 @deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memmodel)
8293 @deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memmodel)
8294 @deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memmodel)
8295 @deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memmodel)
8296 These built-in functions perform the operation suggested by the name, and
8297 return the result of the operation. That is,
8300 @{ *ptr @var{op}= val; return *ptr; @}
8303 All memory models are valid.
8307 @deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memmodel)
8308 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memmodel)
8309 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memmodel)
8310 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memmodel)
8311 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memmodel)
8312 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memmodel)
8313 These built-in functions perform the operation suggested by the name, and
8314 return the value that had previously been in @code{*@var{ptr}}. That is,
8317 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @}
8320 All memory models are valid.
8324 @deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memmodel)
8326 This built-in function performs an atomic test-and-set operation on
8327 the byte at @code{*@var{ptr}}. The byte is set to some implementation
8328 defined nonzero ``set'' value and the return value is @code{true} if and only
8329 if the previous contents were ``set''.
8330 It should be only used for operands of type @code{bool} or @code{char}. For
8331 other types only part of the value may be set.
8333 All memory models are valid.
8337 @deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memmodel)
8339 This built-in function performs an atomic clear operation on
8340 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0.
8341 It should be only used for operands of type @code{bool} or @code{char} and
8342 in conjunction with @code{__atomic_test_and_set}.
8343 For other types it may only clear partially. If the type is not @code{bool}
8344 prefer using @code{__atomic_store}.
8346 The valid memory model variants are
8347 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and
8348 @code{__ATOMIC_RELEASE}.
8352 @deftypefn {Built-in Function} void __atomic_thread_fence (int memmodel)
8354 This built-in function acts as a synchronization fence between threads
8355 based on the specified memory model.
8357 All memory orders are valid.
8361 @deftypefn {Built-in Function} void __atomic_signal_fence (int memmodel)
8363 This built-in function acts as a synchronization fence between a thread
8364 and signal handlers based in the same thread.
8366 All memory orders are valid.
8370 @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr)
8372 This built-in function returns true if objects of @var{size} bytes always
8373 generate lock free atomic instructions for the target architecture.
8374 @var{size} must resolve to a compile-time constant and the result also
8375 resolves to a compile-time constant.
8377 @var{ptr} is an optional pointer to the object that may be used to determine
8378 alignment. A value of 0 indicates typical alignment should be used. The
8379 compiler may also ignore this parameter.
8382 if (_atomic_always_lock_free (sizeof (long long), 0))
8387 @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr)
8389 This built-in function returns true if objects of @var{size} bytes always
8390 generate lock free atomic instructions for the target architecture. If
8391 it is not known to be lock free a call is made to a runtime routine named
8392 @code{__atomic_is_lock_free}.
8394 @var{ptr} is an optional pointer to the object that may be used to determine
8395 alignment. A value of 0 indicates typical alignment should be used. The
8396 compiler may also ignore this parameter.
8399 @node x86 specific memory model extensions for transactional memory
8400 @section x86 specific memory model extensions for transactional memory
8402 The i386 architecture supports additional memory ordering flags
8403 to mark lock critical sections for hardware lock elision.
8404 These must be specified in addition to an existing memory model to
8408 @item __ATOMIC_HLE_ACQUIRE
8409 Start lock elision on a lock variable.
8410 Memory model must be @code{__ATOMIC_ACQUIRE} or stronger.
8411 @item __ATOMIC_HLE_RELEASE
8412 End lock elision on a lock variable.
8413 Memory model must be @code{__ATOMIC_RELEASE} or stronger.
8416 When a lock acquire fails it is required for good performance to abort
8417 the transaction quickly. This can be done with a @code{_mm_pause}
8420 #include <immintrin.h> // For _mm_pause
8424 /* Acquire lock with lock elision */
8425 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
8426 _mm_pause(); /* Abort failed transaction */
8428 /* Free lock with lock elision */
8429 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
8432 @node Object Size Checking
8433 @section Object Size Checking Built-in Functions
8434 @findex __builtin_object_size
8435 @findex __builtin___memcpy_chk
8436 @findex __builtin___mempcpy_chk
8437 @findex __builtin___memmove_chk
8438 @findex __builtin___memset_chk
8439 @findex __builtin___strcpy_chk
8440 @findex __builtin___stpcpy_chk
8441 @findex __builtin___strncpy_chk
8442 @findex __builtin___strcat_chk
8443 @findex __builtin___strncat_chk
8444 @findex __builtin___sprintf_chk
8445 @findex __builtin___snprintf_chk
8446 @findex __builtin___vsprintf_chk
8447 @findex __builtin___vsnprintf_chk
8448 @findex __builtin___printf_chk
8449 @findex __builtin___vprintf_chk
8450 @findex __builtin___fprintf_chk
8451 @findex __builtin___vfprintf_chk
8453 GCC implements a limited buffer overflow protection mechanism
8454 that can prevent some buffer overflow attacks.
8456 @deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type})
8457 is a built-in construct that returns a constant number of bytes from
8458 @var{ptr} to the end of the object @var{ptr} pointer points to
8459 (if known at compile time). @code{__builtin_object_size} never evaluates
8460 its arguments for side-effects. If there are any side-effects in them, it
8461 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
8462 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
8463 point to and all of them are known at compile time, the returned number
8464 is the maximum of remaining byte counts in those objects if @var{type} & 2 is
8465 0 and minimum if nonzero. If it is not possible to determine which objects
8466 @var{ptr} points to at compile time, @code{__builtin_object_size} should
8467 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
8468 for @var{type} 2 or 3.
8470 @var{type} is an integer constant from 0 to 3. If the least significant
8471 bit is clear, objects are whole variables, if it is set, a closest
8472 surrounding subobject is considered the object a pointer points to.
8473 The second bit determines if maximum or minimum of remaining bytes
8477 struct V @{ char buf1[10]; int b; char buf2[10]; @} var;
8478 char *p = &var.buf1[1], *q = &var.b;
8480 /* Here the object p points to is var. */
8481 assert (__builtin_object_size (p, 0) == sizeof (var) - 1);
8482 /* The subobject p points to is var.buf1. */
8483 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1);
8484 /* The object q points to is var. */
8485 assert (__builtin_object_size (q, 0)
8486 == (char *) (&var + 1) - (char *) &var.b);
8487 /* The subobject q points to is var.b. */
8488 assert (__builtin_object_size (q, 1) == sizeof (var.b));
8492 There are built-in functions added for many common string operation
8493 functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk}
8494 built-in is provided. This built-in has an additional last argument,
8495 which is the number of bytes remaining in object the @var{dest}
8496 argument points to or @code{(size_t) -1} if the size is not known.
8498 The built-in functions are optimized into the normal string functions
8499 like @code{memcpy} if the last argument is @code{(size_t) -1} or if
8500 it is known at compile time that the destination object will not
8501 be overflown. If the compiler can determine at compile time the
8502 object will be always overflown, it issues a warning.
8504 The intended use can be e.g.@:
8508 #define bos0(dest) __builtin_object_size (dest, 0)
8509 #define memcpy(dest, src, n) \
8510 __builtin___memcpy_chk (dest, src, n, bos0 (dest))
8514 /* It is unknown what object p points to, so this is optimized
8515 into plain memcpy - no checking is possible. */
8516 memcpy (p, "abcde", n);
8517 /* Destination is known and length too. It is known at compile
8518 time there will be no overflow. */
8519 memcpy (&buf[5], "abcde", 5);
8520 /* Destination is known, but the length is not known at compile time.
8521 This will result in __memcpy_chk call that can check for overflow
8523 memcpy (&buf[5], "abcde", n);
8524 /* Destination is known and it is known at compile time there will
8525 be overflow. There will be a warning and __memcpy_chk call that
8526 will abort the program at run time. */
8527 memcpy (&buf[6], "abcde", 5);
8530 Such built-in functions are provided for @code{memcpy}, @code{mempcpy},
8531 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy},
8532 @code{strcat} and @code{strncat}.
8534 There are also checking built-in functions for formatted output functions.
8536 int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...);
8537 int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os,
8538 const char *fmt, ...);
8539 int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt,
8541 int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os,
8542 const char *fmt, va_list ap);
8545 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk}
8546 etc.@: functions and can contain implementation specific flags on what
8547 additional security measures the checking function might take, such as
8548 handling @code{%n} differently.
8550 The @var{os} argument is the object size @var{s} points to, like in the
8551 other built-in functions. There is a small difference in the behavior
8552 though, if @var{os} is @code{(size_t) -1}, the built-in functions are
8553 optimized into the non-checking functions only if @var{flag} is 0, otherwise
8554 the checking function is called with @var{os} argument set to
8557 In addition to this, there are checking built-in functions
8558 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk},
8559 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}.
8560 These have just one additional argument, @var{flag}, right before
8561 format string @var{fmt}. If the compiler is able to optimize them to
8562 @code{fputc} etc.@: functions, it does, otherwise the checking function
8563 is called and the @var{flag} argument passed to it.
8565 @node Cilk Plus Builtins
8566 @section Cilk Plus C/C++ language extension Built-in Functions.
8568 GCC provides support for the following built-in reduction funtions if Cilk Plus
8569 is enabled. Cilk Plus can be enabled using the @option{-fcilkplus} flag.
8572 @item __sec_implicit_index
8574 @item __sec_reduce_add
8575 @item __sec_reduce_all_nonzero
8576 @item __sec_reduce_all_zero
8577 @item __sec_reduce_any_nonzero
8578 @item __sec_reduce_any_zero
8579 @item __sec_reduce_max
8580 @item __sec_reduce_min
8581 @item __sec_reduce_max_ind
8582 @item __sec_reduce_min_ind
8583 @item __sec_reduce_mul
8584 @item __sec_reduce_mutating
8587 Further details and examples about these built-in functions are described
8588 in the Cilk Plus language manual which can be found at
8589 @uref{http://www.cilkplus.org}.
8591 @node Other Builtins
8592 @section Other Built-in Functions Provided by GCC
8593 @cindex built-in functions
8594 @findex __builtin_fpclassify
8595 @findex __builtin_isfinite
8596 @findex __builtin_isnormal
8597 @findex __builtin_isgreater
8598 @findex __builtin_isgreaterequal
8599 @findex __builtin_isinf_sign
8600 @findex __builtin_isless
8601 @findex __builtin_islessequal
8602 @findex __builtin_islessgreater
8603 @findex __builtin_isunordered
8604 @findex __builtin_powi
8605 @findex __builtin_powif
8606 @findex __builtin_powil
8764 @findex fprintf_unlocked
8766 @findex fputs_unlocked
8883 @findex printf_unlocked
8915 @findex significandf
8916 @findex significandl
8987 GCC provides a large number of built-in functions other than the ones
8988 mentioned above. Some of these are for internal use in the processing
8989 of exceptions or variable-length argument lists and are not
8990 documented here because they may change from time to time; we do not
8991 recommend general use of these functions.
8993 The remaining functions are provided for optimization purposes.
8995 @opindex fno-builtin
8996 GCC includes built-in versions of many of the functions in the standard
8997 C library. The versions prefixed with @code{__builtin_} are always
8998 treated as having the same meaning as the C library function even if you
8999 specify the @option{-fno-builtin} option. (@pxref{C Dialect Options})
9000 Many of these functions are only optimized in certain cases; if they are
9001 not optimized in a particular case, a call to the library function is
9006 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90},
9007 @option{-std=c99} or @option{-std=c11}), the functions
9008 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero},
9009 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml},
9010 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll},
9011 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked},
9012 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma},
9013 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext},
9014 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0},
9015 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn},
9016 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy},
9017 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked},
9018 @code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb},
9019 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32},
9020 @code{signbitd64}, @code{signbitd128}, @code{significandf},
9021 @code{significandl}, @code{significand}, @code{sincosf},
9022 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy},
9023 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp},
9024 @code{strndup}, @code{toascii}, @code{y0f}, @code{y0l}, @code{y0},
9025 @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and
9027 may be handled as built-in functions.
9028 All these functions have corresponding versions
9029 prefixed with @code{__builtin_}, which may be used even in strict C90
9032 The ISO C99 functions
9033 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf},
9034 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh},
9035 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf},
9036 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos},
9037 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf},
9038 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin},
9039 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh},
9040 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt},
9041 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl},
9042 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf},
9043 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog},
9044 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl},
9045 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf},
9046 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal},
9047 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl},
9048 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf},
9049 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan},
9050 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl},
9051 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f},
9052 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim},
9053 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax},
9054 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf},
9055 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb},
9056 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf},
9057 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl},
9058 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround},
9059 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l},
9060 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf},
9061 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl},
9062 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint},
9063 @code{nextafterf}, @code{nextafterl}, @code{nextafter},
9064 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward},
9065 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof},
9066 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint},
9067 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf},
9068 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl},
9069 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal},
9070 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc},
9071 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf}
9072 are handled as built-in functions
9073 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
9075 There are also built-in versions of the ISO C99 functions
9076 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f},
9077 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill},
9078 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf},
9079 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl},
9080 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf},
9081 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl},
9082 @code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf},
9083 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl},
9084 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl}
9085 that are recognized in any mode since ISO C90 reserves these names for
9086 the purpose to which ISO C99 puts them. All these functions have
9087 corresponding versions prefixed with @code{__builtin_}.
9089 The ISO C94 functions
9090 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit},
9091 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct},
9092 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and
9094 are handled as built-in functions
9095 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}).
9097 The ISO C90 functions
9098 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2},
9099 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos},
9100 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod},
9101 @code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf},
9102 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit},
9103 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct},
9104 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower},
9105 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log},
9106 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy},
9107 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar},
9108 @code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf},
9109 @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat},
9110 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn},
9111 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy},
9112 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr},
9113 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf}
9114 are all recognized as built-in functions unless
9115 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}}
9116 is specified for an individual function). All of these functions have
9117 corresponding versions prefixed with @code{__builtin_}.
9119 GCC provides built-in versions of the ISO C99 floating-point comparison
9120 macros that avoid raising exceptions for unordered operands. They have
9121 the same names as the standard macros ( @code{isgreater},
9122 @code{isgreaterequal}, @code{isless}, @code{islessequal},
9123 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_}
9124 prefixed. We intend for a library implementor to be able to simply
9125 @code{#define} each standard macro to its built-in equivalent.
9126 In the same fashion, GCC provides @code{fpclassify}, @code{isfinite},
9127 @code{isinf_sign} and @code{isnormal} built-ins used with
9128 @code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
9129 built-in functions appear both with and without the @code{__builtin_} prefix.
9131 @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
9133 You can use the built-in function @code{__builtin_types_compatible_p} to
9134 determine whether two types are the same.
9136 This built-in function returns 1 if the unqualified versions of the
9137 types @var{type1} and @var{type2} (which are types, not expressions) are
9138 compatible, 0 otherwise. The result of this built-in function can be
9139 used in integer constant expressions.
9141 This built-in function ignores top level qualifiers (e.g., @code{const},
9142 @code{volatile}). For example, @code{int} is equivalent to @code{const
9145 The type @code{int[]} and @code{int[5]} are compatible. On the other
9146 hand, @code{int} and @code{char *} are not compatible, even if the size
9147 of their types, on the particular architecture are the same. Also, the
9148 amount of pointer indirection is taken into account when determining
9149 similarity. Consequently, @code{short *} is not similar to
9150 @code{short **}. Furthermore, two types that are typedefed are
9151 considered compatible if their underlying types are compatible.
9153 An @code{enum} type is not considered to be compatible with another
9154 @code{enum} type even if both are compatible with the same integer
9155 type; this is what the C standard specifies.
9156 For example, @code{enum @{foo, bar@}} is not similar to
9157 @code{enum @{hot, dog@}}.
9159 You typically use this function in code whose execution varies
9160 depending on the arguments' types. For example:
9165 typeof (x) tmp = (x); \
9166 if (__builtin_types_compatible_p (typeof (x), long double)) \
9167 tmp = foo_long_double (tmp); \
9168 else if (__builtin_types_compatible_p (typeof (x), double)) \
9169 tmp = foo_double (tmp); \
9170 else if (__builtin_types_compatible_p (typeof (x), float)) \
9171 tmp = foo_float (tmp); \
9178 @emph{Note:} This construct is only available for C@.
9182 @deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
9184 You can use the built-in function @code{__builtin_choose_expr} to
9185 evaluate code depending on the value of a constant expression. This
9186 built-in function returns @var{exp1} if @var{const_exp}, which is an
9187 integer constant expression, is nonzero. Otherwise it returns @var{exp2}.
9189 This built-in function is analogous to the @samp{? :} operator in C,
9190 except that the expression returned has its type unaltered by promotion
9191 rules. Also, the built-in function does not evaluate the expression
9192 that is not chosen. For example, if @var{const_exp} evaluates to true,
9193 @var{exp2} is not evaluated even if it has side-effects.
9195 This built-in function can return an lvalue if the chosen argument is an
9198 If @var{exp1} is returned, the return type is the same as @var{exp1}'s
9199 type. Similarly, if @var{exp2} is returned, its return type is the same
9206 __builtin_choose_expr ( \
9207 __builtin_types_compatible_p (typeof (x), double), \
9209 __builtin_choose_expr ( \
9210 __builtin_types_compatible_p (typeof (x), float), \
9212 /* @r{The void expression results in a compile-time error} \
9213 @r{when assigning the result to something.} */ \
9217 @emph{Note:} This construct is only available for C@. Furthermore, the
9218 unused expression (@var{exp1} or @var{exp2} depending on the value of
9219 @var{const_exp}) may still generate syntax errors. This may change in
9224 @deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag})
9226 The built-in function @code{__builtin_complex} is provided for use in
9227 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and
9228 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a
9229 real binary floating-point type, and the result has the corresponding
9230 complex type with real and imaginary parts @var{real} and @var{imag}.
9231 Unlike @samp{@var{real} + I * @var{imag}}, this works even when
9232 infinities, NaNs and negative zeros are involved.
9236 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp})
9237 You can use the built-in function @code{__builtin_constant_p} to
9238 determine if a value is known to be constant at compile time and hence
9239 that GCC can perform constant-folding on expressions involving that
9240 value. The argument of the function is the value to test. The function
9241 returns the integer 1 if the argument is known to be a compile-time
9242 constant and 0 if it is not known to be a compile-time constant. A
9243 return of 0 does not indicate that the value is @emph{not} a constant,
9244 but merely that GCC cannot prove it is a constant with the specified
9245 value of the @option{-O} option.
9247 You typically use this function in an embedded application where
9248 memory is a critical resource. If you have some complex calculation,
9249 you may want it to be folded if it involves constants, but need to call
9250 a function if it does not. For example:
9253 #define Scale_Value(X) \
9254 (__builtin_constant_p (X) \
9255 ? ((X) * SCALE + OFFSET) : Scale (X))
9258 You may use this built-in function in either a macro or an inline
9259 function. However, if you use it in an inlined function and pass an
9260 argument of the function as the argument to the built-in, GCC
9261 never returns 1 when you call the inline function with a string constant
9262 or compound literal (@pxref{Compound Literals}) and does not return 1
9263 when you pass a constant numeric value to the inline function unless you
9264 specify the @option{-O} option.
9266 You may also use @code{__builtin_constant_p} in initializers for static
9267 data. For instance, you can write
9270 static const int table[] = @{
9271 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
9277 This is an acceptable initializer even if @var{EXPRESSION} is not a
9278 constant expression, including the case where
9279 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be
9280 folded to a constant but @var{EXPRESSION} contains operands that are
9281 not otherwise permitted in a static initializer (for example,
9282 @code{0 && foo ()}). GCC must be more conservative about evaluating the
9283 built-in in this case, because it has no opportunity to perform
9286 Previous versions of GCC did not accept this built-in in data
9287 initializers. The earliest version where it is completely safe is
9291 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c})
9292 @opindex fprofile-arcs
9293 You may use @code{__builtin_expect} to provide the compiler with
9294 branch prediction information. In general, you should prefer to
9295 use actual profile feedback for this (@option{-fprofile-arcs}), as
9296 programmers are notoriously bad at predicting how their programs
9297 actually perform. However, there are applications in which this
9298 data is hard to collect.
9300 The return value is the value of @var{exp}, which should be an integral
9301 expression. The semantics of the built-in are that it is expected that
9302 @var{exp} == @var{c}. For example:
9305 if (__builtin_expect (x, 0))
9310 indicates that we do not expect to call @code{foo}, since
9311 we expect @code{x} to be zero. Since you are limited to integral
9312 expressions for @var{exp}, you should use constructions such as
9315 if (__builtin_expect (ptr != NULL, 1))
9320 when testing pointer or floating-point values.
9323 @deftypefn {Built-in Function} void __builtin_trap (void)
9324 This function causes the program to exit abnormally. GCC implements
9325 this function by using a target-dependent mechanism (such as
9326 intentionally executing an illegal instruction) or by calling
9327 @code{abort}. The mechanism used may vary from release to release so
9328 you should not rely on any particular implementation.
9331 @deftypefn {Built-in Function} void __builtin_unreachable (void)
9332 If control flow reaches the point of the @code{__builtin_unreachable},
9333 the program is undefined. It is useful in situations where the
9334 compiler cannot deduce the unreachability of the code.
9336 One such case is immediately following an @code{asm} statement that
9337 either never terminates, or one that transfers control elsewhere
9338 and never returns. In this example, without the
9339 @code{__builtin_unreachable}, GCC issues a warning that control
9340 reaches the end of a non-void function. It also generates code
9341 to return after the @code{asm}.
9344 int f (int c, int v)
9352 asm("jmp error_handler");
9353 __builtin_unreachable ();
9359 Because the @code{asm} statement unconditionally transfers control out
9360 of the function, control never reaches the end of the function
9361 body. The @code{__builtin_unreachable} is in fact unreachable and
9362 communicates this fact to the compiler.
9364 Another use for @code{__builtin_unreachable} is following a call a
9365 function that never returns but that is not declared
9366 @code{__attribute__((noreturn))}, as in this example:
9369 void function_that_never_returns (void);
9379 function_that_never_returns ();
9380 __builtin_unreachable ();
9387 @deftypefn {Built-in Function} void *__builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)
9388 This function returns its first argument, and allows the compiler
9389 to assume that the returned pointer is at least @var{align} bytes
9390 aligned. This built-in can have either two or three arguments,
9391 if it has three, the third argument should have integer type, and
9392 if it is nonzero means misalignment offset. For example:
9395 void *x = __builtin_assume_aligned (arg, 16);
9399 means that the compiler can assume @code{x}, set to @code{arg}, is at least
9400 16-byte aligned, while:
9403 void *x = __builtin_assume_aligned (arg, 32, 8);
9407 means that the compiler can assume for @code{x}, set to @code{arg}, that
9408 @code{(char *) x - 8} is 32-byte aligned.
9411 @deftypefn {Built-in Function} int __builtin_LINE ()
9412 This function is the equivalent to the preprocessor @code{__LINE__}
9413 macro and returns the line number of the invocation of the built-in.
9414 In a C++ default argument for a function @var{F}, it gets the line number of
9415 the call to @var{F}.
9418 @deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
9419 This function is the equivalent to the preprocessor @code{__FUNCTION__}
9420 macro and returns the function name the invocation of the built-in is in.
9423 @deftypefn {Built-in Function} {const char *} __builtin_FILE ()
9424 This function is the equivalent to the preprocessor @code{__FILE__}
9425 macro and returns the file name the invocation of the built-in is in.
9426 In a C++ default argument for a function @var{F}, it gets the file name of
9427 the call to @var{F}.
9430 @deftypefn {Built-in Function} void __builtin___clear_cache (char *@var{begin}, char *@var{end})
9431 This function is used to flush the processor's instruction cache for
9432 the region of memory between @var{begin} inclusive and @var{end}
9433 exclusive. Some targets require that the instruction cache be
9434 flushed, after modifying memory containing code, in order to obtain
9435 deterministic behavior.
9437 If the target does not require instruction cache flushes,
9438 @code{__builtin___clear_cache} has no effect. Otherwise either
9439 instructions are emitted in-line to clear the instruction cache or a
9440 call to the @code{__clear_cache} function in libgcc is made.
9443 @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...)
9444 This function is used to minimize cache-miss latency by moving data into
9445 a cache before it is accessed.
9446 You can insert calls to @code{__builtin_prefetch} into code for which
9447 you know addresses of data in memory that is likely to be accessed soon.
9448 If the target supports them, data prefetch instructions are generated.
9449 If the prefetch is done early enough before the access then the data will
9450 be in the cache by the time it is accessed.
9452 The value of @var{addr} is the address of the memory to prefetch.
9453 There are two optional arguments, @var{rw} and @var{locality}.
9454 The value of @var{rw} is a compile-time constant one or zero; one
9455 means that the prefetch is preparing for a write to the memory address
9456 and zero, the default, means that the prefetch is preparing for a read.
9457 The value @var{locality} must be a compile-time constant integer between
9458 zero and three. A value of zero means that the data has no temporal
9459 locality, so it need not be left in the cache after the access. A value
9460 of three means that the data has a high degree of temporal locality and
9461 should be left in all levels of cache possible. Values of one and two
9462 mean, respectively, a low or moderate degree of temporal locality. The
9466 for (i = 0; i < n; i++)
9469 __builtin_prefetch (&a[i+j], 1, 1);
9470 __builtin_prefetch (&b[i+j], 0, 1);
9475 Data prefetch does not generate faults if @var{addr} is invalid, but
9476 the address expression itself must be valid. For example, a prefetch
9477 of @code{p->next} does not fault if @code{p->next} is not a valid
9478 address, but evaluation faults if @code{p} is not a valid address.
9480 If the target does not support data prefetch, the address expression
9481 is evaluated if it includes side effects but no other code is generated
9482 and GCC does not issue a warning.
9485 @deftypefn {Built-in Function} double __builtin_huge_val (void)
9486 Returns a positive infinity, if supported by the floating-point format,
9487 else @code{DBL_MAX}. This function is suitable for implementing the
9488 ISO C macro @code{HUGE_VAL}.
9491 @deftypefn {Built-in Function} float __builtin_huge_valf (void)
9492 Similar to @code{__builtin_huge_val}, except the return type is @code{float}.
9495 @deftypefn {Built-in Function} {long double} __builtin_huge_vall (void)
9496 Similar to @code{__builtin_huge_val}, except the return
9497 type is @code{long double}.
9500 @deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...)
9501 This built-in implements the C99 fpclassify functionality. The first
9502 five int arguments should be the target library's notion of the
9503 possible FP classes and are used for return values. They must be
9504 constant values and they must appear in this order: @code{FP_NAN},
9505 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and
9506 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value
9507 to classify. GCC treats the last argument as type-generic, which
9508 means it does not do default promotion from float to double.
9511 @deftypefn {Built-in Function} double __builtin_inf (void)
9512 Similar to @code{__builtin_huge_val}, except a warning is generated
9513 if the target floating-point format does not support infinities.
9516 @deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void)
9517 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}.
9520 @deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void)
9521 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}.
9524 @deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void)
9525 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}.
9528 @deftypefn {Built-in Function} float __builtin_inff (void)
9529 Similar to @code{__builtin_inf}, except the return type is @code{float}.
9530 This function is suitable for implementing the ISO C99 macro @code{INFINITY}.
9533 @deftypefn {Built-in Function} {long double} __builtin_infl (void)
9534 Similar to @code{__builtin_inf}, except the return
9535 type is @code{long double}.
9538 @deftypefn {Built-in Function} int __builtin_isinf_sign (...)
9539 Similar to @code{isinf}, except the return value is -1 for
9540 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}.
9541 Note while the parameter list is an
9542 ellipsis, this function only accepts exactly one floating-point
9543 argument. GCC treats this parameter as type-generic, which means it
9544 does not do default promotion from float to double.
9547 @deftypefn {Built-in Function} double __builtin_nan (const char *str)
9548 This is an implementation of the ISO C99 function @code{nan}.
9550 Since ISO C99 defines this function in terms of @code{strtod}, which we
9551 do not implement, a description of the parsing is in order. The string
9552 is parsed as by @code{strtol}; that is, the base is recognized by
9553 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed
9554 in the significand such that the least significant bit of the number
9555 is at the least significant bit of the significand. The number is
9556 truncated to fit the significand field provided. The significand is
9557 forced to be a quiet NaN@.
9559 This function, if given a string literal all of which would have been
9560 consumed by @code{strtol}, is evaluated early enough that it is considered a
9561 compile-time constant.
9564 @deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str)
9565 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}.
9568 @deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str)
9569 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}.
9572 @deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str)
9573 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}.
9576 @deftypefn {Built-in Function} float __builtin_nanf (const char *str)
9577 Similar to @code{__builtin_nan}, except the return type is @code{float}.
9580 @deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str)
9581 Similar to @code{__builtin_nan}, except the return type is @code{long double}.
9584 @deftypefn {Built-in Function} double __builtin_nans (const char *str)
9585 Similar to @code{__builtin_nan}, except the significand is forced
9586 to be a signaling NaN@. The @code{nans} function is proposed by
9587 @uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}.
9590 @deftypefn {Built-in Function} float __builtin_nansf (const char *str)
9591 Similar to @code{__builtin_nans}, except the return type is @code{float}.
9594 @deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str)
9595 Similar to @code{__builtin_nans}, except the return type is @code{long double}.
9598 @deftypefn {Built-in Function} int __builtin_ffs (int x)
9599 Returns one plus the index of the least significant 1-bit of @var{x}, or
9600 if @var{x} is zero, returns zero.
9603 @deftypefn {Built-in Function} int __builtin_clz (unsigned int x)
9604 Returns the number of leading 0-bits in @var{x}, starting at the most
9605 significant bit position. If @var{x} is 0, the result is undefined.
9608 @deftypefn {Built-in Function} int __builtin_ctz (unsigned int x)
9609 Returns the number of trailing 0-bits in @var{x}, starting at the least
9610 significant bit position. If @var{x} is 0, the result is undefined.
9613 @deftypefn {Built-in Function} int __builtin_clrsb (int x)
9614 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the
9615 number of bits following the most significant bit that are identical
9616 to it. There are no special cases for 0 or other values.
9619 @deftypefn {Built-in Function} int __builtin_popcount (unsigned int x)
9620 Returns the number of 1-bits in @var{x}.
9623 @deftypefn {Built-in Function} int __builtin_parity (unsigned int x)
9624 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x}
9628 @deftypefn {Built-in Function} int __builtin_ffsl (long)
9629 Similar to @code{__builtin_ffs}, except the argument type is
9633 @deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
9634 Similar to @code{__builtin_clz}, except the argument type is
9635 @code{unsigned long}.
9638 @deftypefn {Built-in Function} int __builtin_ctzl (unsigned long)
9639 Similar to @code{__builtin_ctz}, except the argument type is
9640 @code{unsigned long}.
9643 @deftypefn {Built-in Function} int __builtin_clrsbl (long)
9644 Similar to @code{__builtin_clrsb}, except the argument type is
9648 @deftypefn {Built-in Function} int __builtin_popcountl (unsigned long)
9649 Similar to @code{__builtin_popcount}, except the argument type is
9650 @code{unsigned long}.
9653 @deftypefn {Built-in Function} int __builtin_parityl (unsigned long)
9654 Similar to @code{__builtin_parity}, except the argument type is
9655 @code{unsigned long}.
9658 @deftypefn {Built-in Function} int __builtin_ffsll (long long)
9659 Similar to @code{__builtin_ffs}, except the argument type is
9663 @deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
9664 Similar to @code{__builtin_clz}, except the argument type is
9665 @code{unsigned long long}.
9668 @deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long)
9669 Similar to @code{__builtin_ctz}, except the argument type is
9670 @code{unsigned long long}.
9673 @deftypefn {Built-in Function} int __builtin_clrsbll (long long)
9674 Similar to @code{__builtin_clrsb}, except the argument type is
9678 @deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long)
9679 Similar to @code{__builtin_popcount}, except the argument type is
9680 @code{unsigned long long}.
9683 @deftypefn {Built-in Function} int __builtin_parityll (unsigned long long)
9684 Similar to @code{__builtin_parity}, except the argument type is
9685 @code{unsigned long long}.
9688 @deftypefn {Built-in Function} double __builtin_powi (double, int)
9689 Returns the first argument raised to the power of the second. Unlike the
9690 @code{pow} function no guarantees about precision and rounding are made.
9693 @deftypefn {Built-in Function} float __builtin_powif (float, int)
9694 Similar to @code{__builtin_powi}, except the argument and return types
9698 @deftypefn {Built-in Function} {long double} __builtin_powil (long double, int)
9699 Similar to @code{__builtin_powi}, except the argument and return types
9700 are @code{long double}.
9703 @deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x)
9704 Returns @var{x} with the order of the bytes reversed; for example,
9705 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means
9709 @deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x)
9710 Similar to @code{__builtin_bswap16}, except the argument and return types
9714 @deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x)
9715 Similar to @code{__builtin_bswap32}, except the argument and return types
9719 @node Target Builtins
9720 @section Built-in Functions Specific to Particular Target Machines
9722 On some target machines, GCC supports many built-in functions specific
9723 to those machines. Generally these generate calls to specific machine
9724 instructions, but allow the compiler to schedule those calls.
9727 * AArch64 Built-in Functions::
9728 * AArch64 intrinsics::
9729 * Alpha Built-in Functions::
9730 * Altera Nios II Built-in Functions::
9731 * ARC Built-in Functions::
9732 * ARC SIMD Built-in Functions::
9733 * ARM iWMMXt Built-in Functions::
9734 * ARM NEON Intrinsics::
9735 * ARM ACLE Intrinsics::
9736 * ARM Floating Point Status and Control Intrinsics::
9737 * AVR Built-in Functions::
9738 * Blackfin Built-in Functions::
9739 * FR-V Built-in Functions::
9740 * X86 Built-in Functions::
9741 * X86 transactional memory intrinsics::
9742 * MIPS DSP Built-in Functions::
9743 * MIPS Paired-Single Support::
9744 * MIPS Loongson Built-in Functions::
9745 * Other MIPS Built-in Functions::
9746 * MSP430 Built-in Functions::
9747 * NDS32 Built-in Functions::
9748 * picoChip Built-in Functions::
9749 * PowerPC Built-in Functions::
9750 * PowerPC AltiVec/VSX Built-in Functions::
9751 * PowerPC Hardware Transactional Memory Built-in Functions::
9752 * RX Built-in Functions::
9753 * S/390 System z Built-in Functions::
9754 * SH Built-in Functions::
9755 * SPARC VIS Built-in Functions::
9756 * SPU Built-in Functions::
9757 * TI C6X Built-in Functions::
9758 * TILE-Gx Built-in Functions::
9759 * TILEPro Built-in Functions::
9762 @node AArch64 Built-in Functions
9763 @subsection AArch64 Built-in Functions
9765 These built-in functions are available for the AArch64 family of
9768 unsigned int __builtin_aarch64_get_fpcr ()
9769 void __builtin_aarch64_set_fpcr (unsigned int)
9770 unsigned int __builtin_aarch64_get_fpsr ()
9771 void __builtin_aarch64_set_fpsr (unsigned int)
9774 @node AArch64 intrinsics
9775 @subsection ACLE Intrinsics for AArch64
9777 @include aarch64-acle-intrinsics.texi
9779 @node Alpha Built-in Functions
9780 @subsection Alpha Built-in Functions
9782 These built-in functions are available for the Alpha family of
9783 processors, depending on the command-line switches used.
9785 The following built-in functions are always available. They
9786 all generate the machine instruction that is part of the name.
9789 long __builtin_alpha_implver (void)
9790 long __builtin_alpha_rpcc (void)
9791 long __builtin_alpha_amask (long)
9792 long __builtin_alpha_cmpbge (long, long)
9793 long __builtin_alpha_extbl (long, long)
9794 long __builtin_alpha_extwl (long, long)
9795 long __builtin_alpha_extll (long, long)
9796 long __builtin_alpha_extql (long, long)
9797 long __builtin_alpha_extwh (long, long)
9798 long __builtin_alpha_extlh (long, long)
9799 long __builtin_alpha_extqh (long, long)
9800 long __builtin_alpha_insbl (long, long)
9801 long __builtin_alpha_inswl (long, long)
9802 long __builtin_alpha_insll (long, long)
9803 long __builtin_alpha_insql (long, long)
9804 long __builtin_alpha_inswh (long, long)
9805 long __builtin_alpha_inslh (long, long)
9806 long __builtin_alpha_insqh (long, long)
9807 long __builtin_alpha_mskbl (long, long)
9808 long __builtin_alpha_mskwl (long, long)
9809 long __builtin_alpha_mskll (long, long)
9810 long __builtin_alpha_mskql (long, long)
9811 long __builtin_alpha_mskwh (long, long)
9812 long __builtin_alpha_msklh (long, long)
9813 long __builtin_alpha_mskqh (long, long)
9814 long __builtin_alpha_umulh (long, long)
9815 long __builtin_alpha_zap (long, long)
9816 long __builtin_alpha_zapnot (long, long)
9819 The following built-in functions are always with @option{-mmax}
9820 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or
9821 later. They all generate the machine instruction that is part
9825 long __builtin_alpha_pklb (long)
9826 long __builtin_alpha_pkwb (long)
9827 long __builtin_alpha_unpkbl (long)
9828 long __builtin_alpha_unpkbw (long)
9829 long __builtin_alpha_minub8 (long, long)
9830 long __builtin_alpha_minsb8 (long, long)
9831 long __builtin_alpha_minuw4 (long, long)
9832 long __builtin_alpha_minsw4 (long, long)
9833 long __builtin_alpha_maxub8 (long, long)
9834 long __builtin_alpha_maxsb8 (long, long)
9835 long __builtin_alpha_maxuw4 (long, long)
9836 long __builtin_alpha_maxsw4 (long, long)
9837 long __builtin_alpha_perr (long, long)
9840 The following built-in functions are always with @option{-mcix}
9841 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or
9842 later. They all generate the machine instruction that is part
9846 long __builtin_alpha_cttz (long)
9847 long __builtin_alpha_ctlz (long)
9848 long __builtin_alpha_ctpop (long)
9851 The following built-in functions are available on systems that use the OSF/1
9852 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq}
9853 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke
9854 @code{rdval} and @code{wrval}.
9857 void *__builtin_thread_pointer (void)
9858 void __builtin_set_thread_pointer (void *)
9861 @node Altera Nios II Built-in Functions
9862 @subsection Altera Nios II Built-in Functions
9864 These built-in functions are available for the Altera Nios II
9865 family of processors.
9867 The following built-in functions are always available. They
9868 all generate the machine instruction that is part of the name.
9871 int __builtin_ldbio (volatile const void *)
9872 int __builtin_ldbuio (volatile const void *)
9873 int __builtin_ldhio (volatile const void *)
9874 int __builtin_ldhuio (volatile const void *)
9875 int __builtin_ldwio (volatile const void *)
9876 void __builtin_stbio (volatile void *, int)
9877 void __builtin_sthio (volatile void *, int)
9878 void __builtin_stwio (volatile void *, int)
9879 void __builtin_sync (void)
9880 int __builtin_rdctl (int)
9881 void __builtin_wrctl (int, int)
9884 The following built-in functions are always available. They
9885 all generate a Nios II Custom Instruction. The name of the
9886 function represents the types that the function takes and
9887 returns. The letter before the @code{n} is the return type
9888 or void if absent. The @code{n} represents the first parameter
9889 to all the custom instructions, the custom instruction number.
9890 The two letters after the @code{n} represent the up to two
9891 parameters to the function.
9893 The letters represent the following data types:
9896 @code{void} for return type and no parameter for parameter types.
9899 @code{int} for return type and parameter type
9902 @code{float} for return type and parameter type
9905 @code{void *} for return type and parameter type
9909 And the function names are:
9911 void __builtin_custom_n (void)
9912 void __builtin_custom_ni (int)
9913 void __builtin_custom_nf (float)
9914 void __builtin_custom_np (void *)
9915 void __builtin_custom_nii (int, int)
9916 void __builtin_custom_nif (int, float)
9917 void __builtin_custom_nip (int, void *)
9918 void __builtin_custom_nfi (float, int)
9919 void __builtin_custom_nff (float, float)
9920 void __builtin_custom_nfp (float, void *)
9921 void __builtin_custom_npi (void *, int)
9922 void __builtin_custom_npf (void *, float)
9923 void __builtin_custom_npp (void *, void *)
9924 int __builtin_custom_in (void)
9925 int __builtin_custom_ini (int)
9926 int __builtin_custom_inf (float)
9927 int __builtin_custom_inp (void *)
9928 int __builtin_custom_inii (int, int)
9929 int __builtin_custom_inif (int, float)
9930 int __builtin_custom_inip (int, void *)
9931 int __builtin_custom_infi (float, int)
9932 int __builtin_custom_inff (float, float)
9933 int __builtin_custom_infp (float, void *)
9934 int __builtin_custom_inpi (void *, int)
9935 int __builtin_custom_inpf (void *, float)
9936 int __builtin_custom_inpp (void *, void *)
9937 float __builtin_custom_fn (void)
9938 float __builtin_custom_fni (int)
9939 float __builtin_custom_fnf (float)
9940 float __builtin_custom_fnp (void *)
9941 float __builtin_custom_fnii (int, int)
9942 float __builtin_custom_fnif (int, float)
9943 float __builtin_custom_fnip (int, void *)
9944 float __builtin_custom_fnfi (float, int)
9945 float __builtin_custom_fnff (float, float)
9946 float __builtin_custom_fnfp (float, void *)
9947 float __builtin_custom_fnpi (void *, int)
9948 float __builtin_custom_fnpf (void *, float)
9949 float __builtin_custom_fnpp (void *, void *)
9950 void * __builtin_custom_pn (void)
9951 void * __builtin_custom_pni (int)
9952 void * __builtin_custom_pnf (float)
9953 void * __builtin_custom_pnp (void *)
9954 void * __builtin_custom_pnii (int, int)
9955 void * __builtin_custom_pnif (int, float)
9956 void * __builtin_custom_pnip (int, void *)
9957 void * __builtin_custom_pnfi (float, int)
9958 void * __builtin_custom_pnff (float, float)
9959 void * __builtin_custom_pnfp (float, void *)
9960 void * __builtin_custom_pnpi (void *, int)
9961 void * __builtin_custom_pnpf (void *, float)
9962 void * __builtin_custom_pnpp (void *, void *)
9965 @node ARC Built-in Functions
9966 @subsection ARC Built-in Functions
9968 The following built-in functions are provided for ARC targets. The
9969 built-ins generate the corresponding assembly instructions. In the
9970 examples given below, the generated code often requires an operand or
9971 result to be in a register. Where necessary further code will be
9972 generated to ensure this is true, but for brevity this is not
9973 described in each case.
9975 @emph{Note:} Using a built-in to generate an instruction not supported
9976 by a target may cause problems. At present the compiler is not
9977 guaranteed to detect such misuse, and as a result an internal compiler
9978 error may be generated.
9980 @deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval})
9981 Return 1 if @var{val} is known to have the byte alignment given
9982 by @var{alignval}, otherwise return 0.
9983 Note that this is different from
9985 __alignof__(*(char *)@var{val}) >= alignval
9987 because __alignof__ sees only the type of the dereference, whereas
9988 __builtin_arc_align uses alignment information from the pointer
9989 as well as from the pointed-to type.
9990 The information available will depend on optimization level.
9993 @deftypefn {Built-in Function} void __builtin_arc_brk (void)
10000 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno})
10001 The operand is the number of a register to be read. Generates:
10003 mov @var{dest}, r@var{regno}
10005 where the value in @var{dest} will be the result returned from the
10009 @deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val})
10010 The first operand is the number of a register to be written, the
10011 second operand is a compile time constant to write into that
10012 register. Generates:
10014 mov r@var{regno}, @var{val}
10018 @deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b})
10019 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set.
10022 divaw @var{dest}, @var{a}, @var{b}
10024 where the value in @var{dest} will be the result returned from the
10028 @deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a})
10035 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr})
10036 The operand, @var{auxv}, is the address of an auxiliary register and
10037 must be a compile time constant. Generates:
10039 lr @var{dest}, [@var{auxr}]
10041 Where the value in @var{dest} will be the result returned from the
10045 @deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b})
10046 Only available with @option{-mmul64}. Generates:
10048 mul64 @var{a}, @var{b}
10052 @deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b})
10053 Only available with @option{-mmul64}. Generates:
10055 mulu64 @var{a}, @var{b}
10059 @deftypefn {Built-in Function} void __builtin_arc_nop (void)
10066 @deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src})
10067 Only valid if the @samp{norm} instruction is available through the
10068 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
10071 norm @var{dest}, @var{src}
10073 Where the value in @var{dest} will be the result returned from the
10077 @deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src})
10078 Only valid if the @samp{normw} instruction is available through the
10079 @option{-mnorm} option or by default with @option{-mcpu=ARC700}.
10082 normw @var{dest}, @var{src}
10084 Where the value in @var{dest} will be the result returned from the
10088 @deftypefn {Built-in Function} void __builtin_arc_rtie (void)
10095 @deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a}
10102 @deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{auxr}, unsigned int @var{val})
10103 The first argument, @var{auxv}, is the address of an auxiliary
10104 register, the second argument, @var{val}, is a compile time constant
10105 to be written to the register. Generates:
10107 sr @var{auxr}, [@var{val}]
10111 @deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src})
10112 Only valid with @option{-mswap}. Generates:
10114 swap @var{dest}, @var{src}
10116 Where the value in @var{dest} will be the result returned from the
10120 @deftypefn {Built-in Function} void __builtin_arc_swi (void)
10127 @deftypefn {Built-in Function} void __builtin_arc_sync (void)
10128 Only available with @option{-mcpu=ARC700}. Generates:
10134 @deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c})
10135 Only available with @option{-mcpu=ARC700}. Generates:
10141 @deftypefn {Built-in Function} void __builtin_arc_unimp_s (void)
10142 Only available with @option{-mcpu=ARC700}. Generates:
10148 The instructions generated by the following builtins are not
10149 considered as candidates for scheduling. They are not moved around by
10150 the compiler during scheduling, and thus can be expected to appear
10151 where they are put in the C code:
10153 __builtin_arc_brk()
10154 __builtin_arc_core_read()
10155 __builtin_arc_core_write()
10156 __builtin_arc_flag()
10158 __builtin_arc_sleep()
10160 __builtin_arc_swi()
10163 @node ARC SIMD Built-in Functions
10164 @subsection ARC SIMD Built-in Functions
10166 SIMD builtins provided by the compiler can be used to generate the
10167 vector instructions. This section describes the available builtins
10168 and their usage in programs. With the @option{-msimd} option, the
10169 compiler provides 128-bit vector types, which can be specified using
10170 the @code{vector_size} attribute. The header file @file{arc-simd.h}
10171 can be included to use the following predefined types:
10173 typedef int __v4si __attribute__((vector_size(16)));
10174 typedef short __v8hi __attribute__((vector_size(16)));
10177 These types can be used to define 128-bit variables. The built-in
10178 functions listed in the following section can be used on these
10179 variables to generate the vector operations.
10181 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file
10182 @file{arc-simd.h} also provides equivalent macros called
10183 @code{_@var{someinsn}} that can be used for programming ease and
10184 improved readability. The following macros for DMA control are also
10187 #define _setup_dma_in_channel_reg _vdiwr
10188 #define _setup_dma_out_channel_reg _vdowr
10191 The following is a complete list of all the SIMD built-ins provided
10192 for ARC, grouped by calling signature.
10194 The following take two @code{__v8hi} arguments and return a
10195 @code{__v8hi} result:
10197 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi)
10198 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi)
10199 __v8hi __builtin_arc_vand (__v8hi, __v8hi)
10200 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi)
10201 __v8hi __builtin_arc_vavb (__v8hi, __v8hi)
10202 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi)
10203 __v8hi __builtin_arc_vbic (__v8hi, __v8hi)
10204 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi)
10205 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi)
10206 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi)
10207 __v8hi __builtin_arc_veqw (__v8hi, __v8hi)
10208 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi)
10209 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi)
10210 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi)
10211 __v8hi __builtin_arc_vlew (__v8hi, __v8hi)
10212 __v8hi __builtin_arc_vltw (__v8hi, __v8hi)
10213 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi)
10214 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi)
10215 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi)
10216 __v8hi __builtin_arc_vminw (__v8hi, __v8hi)
10217 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi)
10218 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi)
10219 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi)
10220 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi)
10221 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi)
10222 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi)
10223 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi)
10224 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi)
10225 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi)
10226 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi)
10227 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi)
10228 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi)
10229 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi)
10230 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi)
10231 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi)
10232 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi)
10233 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi)
10234 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi)
10235 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi)
10236 __v8hi __builtin_arc_vnew (__v8hi, __v8hi)
10237 __v8hi __builtin_arc_vor (__v8hi, __v8hi)
10238 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi)
10239 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi)
10240 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi)
10241 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi)
10242 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi)
10243 __v8hi __builtin_arc_vxor (__v8hi, __v8hi)
10244 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi)
10247 The following take one @code{__v8hi} and one @code{int} argument and return a
10248 @code{__v8hi} result:
10251 __v8hi __builtin_arc_vbaddw (__v8hi, int)
10252 __v8hi __builtin_arc_vbmaxw (__v8hi, int)
10253 __v8hi __builtin_arc_vbminw (__v8hi, int)
10254 __v8hi __builtin_arc_vbmulaw (__v8hi, int)
10255 __v8hi __builtin_arc_vbmulfw (__v8hi, int)
10256 __v8hi __builtin_arc_vbmulw (__v8hi, int)
10257 __v8hi __builtin_arc_vbrsubw (__v8hi, int)
10258 __v8hi __builtin_arc_vbsubw (__v8hi, int)
10261 The following take one @code{__v8hi} argument and one @code{int} argument which
10262 must be a 3-bit compile time constant indicating a register number
10263 I0-I7. They return a @code{__v8hi} result.
10265 __v8hi __builtin_arc_vasrw (__v8hi, const int)
10266 __v8hi __builtin_arc_vsr8 (__v8hi, const int)
10267 __v8hi __builtin_arc_vsr8aw (__v8hi, const int)
10270 The following take one @code{__v8hi} argument and one @code{int}
10271 argument which must be a 6-bit compile time constant. They return a
10272 @code{__v8hi} result.
10274 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int)
10275 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int)
10276 __v8hi __builtin_arc_vasrrwi (__v8hi, const int)
10277 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int)
10278 __v8hi __builtin_arc_vasrwi (__v8hi, const int)
10279 __v8hi __builtin_arc_vsr8awi (__v8hi, const int)
10280 __v8hi __builtin_arc_vsr8i (__v8hi, const int)
10283 The following take one @code{__v8hi} argument and one @code{int} argument which
10284 must be a 8-bit compile time constant. They return a @code{__v8hi}
10287 __v8hi __builtin_arc_vd6tapf (__v8hi, const int)
10288 __v8hi __builtin_arc_vmvaw (__v8hi, const int)
10289 __v8hi __builtin_arc_vmvw (__v8hi, const int)
10290 __v8hi __builtin_arc_vmvzw (__v8hi, const int)
10293 The following take two @code{int} arguments, the second of which which
10294 must be a 8-bit compile time constant. They return a @code{__v8hi}
10297 __v8hi __builtin_arc_vmovaw (int, const int)
10298 __v8hi __builtin_arc_vmovw (int, const int)
10299 __v8hi __builtin_arc_vmovzw (int, const int)
10302 The following take a single @code{__v8hi} argument and return a
10303 @code{__v8hi} result:
10305 __v8hi __builtin_arc_vabsaw (__v8hi)
10306 __v8hi __builtin_arc_vabsw (__v8hi)
10307 __v8hi __builtin_arc_vaddsuw (__v8hi)
10308 __v8hi __builtin_arc_vexch1 (__v8hi)
10309 __v8hi __builtin_arc_vexch2 (__v8hi)
10310 __v8hi __builtin_arc_vexch4 (__v8hi)
10311 __v8hi __builtin_arc_vsignw (__v8hi)
10312 __v8hi __builtin_arc_vupbaw (__v8hi)
10313 __v8hi __builtin_arc_vupbw (__v8hi)
10314 __v8hi __builtin_arc_vupsbaw (__v8hi)
10315 __v8hi __builtin_arc_vupsbw (__v8hi)
10318 The followign take two @code{int} arguments and return no result:
10320 void __builtin_arc_vdirun (int, int)
10321 void __builtin_arc_vdorun (int, int)
10324 The following take two @code{int} arguments and return no result. The
10325 first argument must a 3-bit compile time constant indicating one of
10326 the DR0-DR7 DMA setup channels:
10328 void __builtin_arc_vdiwr (const int, int)
10329 void __builtin_arc_vdowr (const int, int)
10332 The following take an @code{int} argument and return no result:
10334 void __builtin_arc_vendrec (int)
10335 void __builtin_arc_vrec (int)
10336 void __builtin_arc_vrecrun (int)
10337 void __builtin_arc_vrun (int)
10340 The following take a @code{__v8hi} argument and two @code{int}
10341 arguments and return a @code{__v8hi} result. The second argument must
10342 be a 3-bit compile time constants, indicating one the registers I0-I7,
10343 and the third argument must be an 8-bit compile time constant.
10345 @emph{Note:} Although the equivalent hardware instructions do not take
10346 an SIMD register as an operand, these builtins overwrite the relevant
10347 bits of the @code{__v8hi} register provided as the first argument with
10348 the value loaded from the @code{[Ib, u8]} location in the SDM.
10351 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int)
10352 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int)
10353 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int)
10354 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int)
10357 The following take two @code{int} arguments and return a @code{__v8hi}
10358 result. The first argument must be a 3-bit compile time constants,
10359 indicating one the registers I0-I7, and the second argument must be an
10360 8-bit compile time constant.
10363 __v8hi __builtin_arc_vld128 (const int, const int)
10364 __v8hi __builtin_arc_vld64w (const int, const int)
10367 The following take a @code{__v8hi} argument and two @code{int}
10368 arguments and return no result. The second argument must be a 3-bit
10369 compile time constants, indicating one the registers I0-I7, and the
10370 third argument must be an 8-bit compile time constant.
10373 void __builtin_arc_vst128 (__v8hi, const int, const int)
10374 void __builtin_arc_vst64 (__v8hi, const int, const int)
10377 The following take a @code{__v8hi} argument and three @code{int}
10378 arguments and return no result. The second argument must be a 3-bit
10379 compile-time constant, identifying the 16-bit sub-register to be
10380 stored, the third argument must be a 3-bit compile time constants,
10381 indicating one the registers I0-I7, and the fourth argument must be an
10382 8-bit compile time constant.
10385 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int)
10386 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int)
10389 @node ARM iWMMXt Built-in Functions
10390 @subsection ARM iWMMXt Built-in Functions
10392 These built-in functions are available for the ARM family of
10393 processors when the @option{-mcpu=iwmmxt} switch is used:
10396 typedef int v2si __attribute__ ((vector_size (8)));
10397 typedef short v4hi __attribute__ ((vector_size (8)));
10398 typedef char v8qi __attribute__ ((vector_size (8)));
10400 int __builtin_arm_getwcgr0 (void)
10401 void __builtin_arm_setwcgr0 (int)
10402 int __builtin_arm_getwcgr1 (void)
10403 void __builtin_arm_setwcgr1 (int)
10404 int __builtin_arm_getwcgr2 (void)
10405 void __builtin_arm_setwcgr2 (int)
10406 int __builtin_arm_getwcgr3 (void)
10407 void __builtin_arm_setwcgr3 (int)
10408 int __builtin_arm_textrmsb (v8qi, int)
10409 int __builtin_arm_textrmsh (v4hi, int)
10410 int __builtin_arm_textrmsw (v2si, int)
10411 int __builtin_arm_textrmub (v8qi, int)
10412 int __builtin_arm_textrmuh (v4hi, int)
10413 int __builtin_arm_textrmuw (v2si, int)
10414 v8qi __builtin_arm_tinsrb (v8qi, int, int)
10415 v4hi __builtin_arm_tinsrh (v4hi, int, int)
10416 v2si __builtin_arm_tinsrw (v2si, int, int)
10417 long long __builtin_arm_tmia (long long, int, int)
10418 long long __builtin_arm_tmiabb (long long, int, int)
10419 long long __builtin_arm_tmiabt (long long, int, int)
10420 long long __builtin_arm_tmiaph (long long, int, int)
10421 long long __builtin_arm_tmiatb (long long, int, int)
10422 long long __builtin_arm_tmiatt (long long, int, int)
10423 int __builtin_arm_tmovmskb (v8qi)
10424 int __builtin_arm_tmovmskh (v4hi)
10425 int __builtin_arm_tmovmskw (v2si)
10426 long long __builtin_arm_waccb (v8qi)
10427 long long __builtin_arm_wacch (v4hi)
10428 long long __builtin_arm_waccw (v2si)
10429 v8qi __builtin_arm_waddb (v8qi, v8qi)
10430 v8qi __builtin_arm_waddbss (v8qi, v8qi)
10431 v8qi __builtin_arm_waddbus (v8qi, v8qi)
10432 v4hi __builtin_arm_waddh (v4hi, v4hi)
10433 v4hi __builtin_arm_waddhss (v4hi, v4hi)
10434 v4hi __builtin_arm_waddhus (v4hi, v4hi)
10435 v2si __builtin_arm_waddw (v2si, v2si)
10436 v2si __builtin_arm_waddwss (v2si, v2si)
10437 v2si __builtin_arm_waddwus (v2si, v2si)
10438 v8qi __builtin_arm_walign (v8qi, v8qi, int)
10439 long long __builtin_arm_wand(long long, long long)
10440 long long __builtin_arm_wandn (long long, long long)
10441 v8qi __builtin_arm_wavg2b (v8qi, v8qi)
10442 v8qi __builtin_arm_wavg2br (v8qi, v8qi)
10443 v4hi __builtin_arm_wavg2h (v4hi, v4hi)
10444 v4hi __builtin_arm_wavg2hr (v4hi, v4hi)
10445 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi)
10446 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi)
10447 v2si __builtin_arm_wcmpeqw (v2si, v2si)
10448 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi)
10449 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi)
10450 v2si __builtin_arm_wcmpgtsw (v2si, v2si)
10451 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi)
10452 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi)
10453 v2si __builtin_arm_wcmpgtuw (v2si, v2si)
10454 long long __builtin_arm_wmacs (long long, v4hi, v4hi)
10455 long long __builtin_arm_wmacsz (v4hi, v4hi)
10456 long long __builtin_arm_wmacu (long long, v4hi, v4hi)
10457 long long __builtin_arm_wmacuz (v4hi, v4hi)
10458 v4hi __builtin_arm_wmadds (v4hi, v4hi)
10459 v4hi __builtin_arm_wmaddu (v4hi, v4hi)
10460 v8qi __builtin_arm_wmaxsb (v8qi, v8qi)
10461 v4hi __builtin_arm_wmaxsh (v4hi, v4hi)
10462 v2si __builtin_arm_wmaxsw (v2si, v2si)
10463 v8qi __builtin_arm_wmaxub (v8qi, v8qi)
10464 v4hi __builtin_arm_wmaxuh (v4hi, v4hi)
10465 v2si __builtin_arm_wmaxuw (v2si, v2si)
10466 v8qi __builtin_arm_wminsb (v8qi, v8qi)
10467 v4hi __builtin_arm_wminsh (v4hi, v4hi)
10468 v2si __builtin_arm_wminsw (v2si, v2si)
10469 v8qi __builtin_arm_wminub (v8qi, v8qi)
10470 v4hi __builtin_arm_wminuh (v4hi, v4hi)
10471 v2si __builtin_arm_wminuw (v2si, v2si)
10472 v4hi __builtin_arm_wmulsm (v4hi, v4hi)
10473 v4hi __builtin_arm_wmulul (v4hi, v4hi)
10474 v4hi __builtin_arm_wmulum (v4hi, v4hi)
10475 long long __builtin_arm_wor (long long, long long)
10476 v2si __builtin_arm_wpackdss (long long, long long)
10477 v2si __builtin_arm_wpackdus (long long, long long)
10478 v8qi __builtin_arm_wpackhss (v4hi, v4hi)
10479 v8qi __builtin_arm_wpackhus (v4hi, v4hi)
10480 v4hi __builtin_arm_wpackwss (v2si, v2si)
10481 v4hi __builtin_arm_wpackwus (v2si, v2si)
10482 long long __builtin_arm_wrord (long long, long long)
10483 long long __builtin_arm_wrordi (long long, int)
10484 v4hi __builtin_arm_wrorh (v4hi, long long)
10485 v4hi __builtin_arm_wrorhi (v4hi, int)
10486 v2si __builtin_arm_wrorw (v2si, long long)
10487 v2si __builtin_arm_wrorwi (v2si, int)
10488 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi)
10489 v2si __builtin_arm_wsadbz (v8qi, v8qi)
10490 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi)
10491 v2si __builtin_arm_wsadhz (v4hi, v4hi)
10492 v4hi __builtin_arm_wshufh (v4hi, int)
10493 long long __builtin_arm_wslld (long long, long long)
10494 long long __builtin_arm_wslldi (long long, int)
10495 v4hi __builtin_arm_wsllh (v4hi, long long)
10496 v4hi __builtin_arm_wsllhi (v4hi, int)
10497 v2si __builtin_arm_wsllw (v2si, long long)
10498 v2si __builtin_arm_wsllwi (v2si, int)
10499 long long __builtin_arm_wsrad (long long, long long)
10500 long long __builtin_arm_wsradi (long long, int)
10501 v4hi __builtin_arm_wsrah (v4hi, long long)
10502 v4hi __builtin_arm_wsrahi (v4hi, int)
10503 v2si __builtin_arm_wsraw (v2si, long long)
10504 v2si __builtin_arm_wsrawi (v2si, int)
10505 long long __builtin_arm_wsrld (long long, long long)
10506 long long __builtin_arm_wsrldi (long long, int)
10507 v4hi __builtin_arm_wsrlh (v4hi, long long)
10508 v4hi __builtin_arm_wsrlhi (v4hi, int)
10509 v2si __builtin_arm_wsrlw (v2si, long long)
10510 v2si __builtin_arm_wsrlwi (v2si, int)
10511 v8qi __builtin_arm_wsubb (v8qi, v8qi)
10512 v8qi __builtin_arm_wsubbss (v8qi, v8qi)
10513 v8qi __builtin_arm_wsubbus (v8qi, v8qi)
10514 v4hi __builtin_arm_wsubh (v4hi, v4hi)
10515 v4hi __builtin_arm_wsubhss (v4hi, v4hi)
10516 v4hi __builtin_arm_wsubhus (v4hi, v4hi)
10517 v2si __builtin_arm_wsubw (v2si, v2si)
10518 v2si __builtin_arm_wsubwss (v2si, v2si)
10519 v2si __builtin_arm_wsubwus (v2si, v2si)
10520 v4hi __builtin_arm_wunpckehsb (v8qi)
10521 v2si __builtin_arm_wunpckehsh (v4hi)
10522 long long __builtin_arm_wunpckehsw (v2si)
10523 v4hi __builtin_arm_wunpckehub (v8qi)
10524 v2si __builtin_arm_wunpckehuh (v4hi)
10525 long long __builtin_arm_wunpckehuw (v2si)
10526 v4hi __builtin_arm_wunpckelsb (v8qi)
10527 v2si __builtin_arm_wunpckelsh (v4hi)
10528 long long __builtin_arm_wunpckelsw (v2si)
10529 v4hi __builtin_arm_wunpckelub (v8qi)
10530 v2si __builtin_arm_wunpckeluh (v4hi)
10531 long long __builtin_arm_wunpckeluw (v2si)
10532 v8qi __builtin_arm_wunpckihb (v8qi, v8qi)
10533 v4hi __builtin_arm_wunpckihh (v4hi, v4hi)
10534 v2si __builtin_arm_wunpckihw (v2si, v2si)
10535 v8qi __builtin_arm_wunpckilb (v8qi, v8qi)
10536 v4hi __builtin_arm_wunpckilh (v4hi, v4hi)
10537 v2si __builtin_arm_wunpckilw (v2si, v2si)
10538 long long __builtin_arm_wxor (long long, long long)
10539 long long __builtin_arm_wzero ()
10542 @node ARM NEON Intrinsics
10543 @subsection ARM NEON Intrinsics
10545 These built-in intrinsics for the ARM Advanced SIMD extension are available
10546 when the @option{-mfpu=neon} switch is used:
10548 @include arm-neon-intrinsics.texi
10550 @node ARM ACLE Intrinsics
10551 @subsection ARM ACLE Intrinsics
10553 @include arm-acle-intrinsics.texi
10555 @node ARM Floating Point Status and Control Intrinsics
10556 @subsection ARM Floating Point Status and Control Intrinsics
10558 These built-in functions are available for the ARM family of
10559 processors with floating-point unit.
10562 unsigned int __builtin_arm_get_fpscr ()
10563 void __builtin_arm_set_fpscr (unsigned int)
10566 @node AVR Built-in Functions
10567 @subsection AVR Built-in Functions
10569 For each built-in function for AVR, there is an equally named,
10570 uppercase built-in macro defined. That way users can easily query if
10571 or if not a specific built-in is implemented or not. For example, if
10572 @code{__builtin_avr_nop} is available the macro
10573 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise.
10575 The following built-in functions map to the respective machine
10576 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep},
10577 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls}
10578 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented
10579 as library call if no hardware multiplier is available.
10582 void __builtin_avr_nop (void)
10583 void __builtin_avr_sei (void)
10584 void __builtin_avr_cli (void)
10585 void __builtin_avr_sleep (void)
10586 void __builtin_avr_wdr (void)
10587 unsigned char __builtin_avr_swap (unsigned char)
10588 unsigned int __builtin_avr_fmul (unsigned char, unsigned char)
10589 int __builtin_avr_fmuls (char, char)
10590 int __builtin_avr_fmulsu (char, unsigned char)
10593 In order to delay execution for a specific number of cycles, GCC
10596 void __builtin_avr_delay_cycles (unsigned long ticks)
10600 @code{ticks} is the number of ticks to delay execution. Note that this
10601 built-in does not take into account the effect of interrupts that
10602 might increase delay time. @code{ticks} must be a compile-time
10603 integer constant; delays with a variable number of cycles are not supported.
10606 char __builtin_avr_flash_segment (const __memx void*)
10610 This built-in takes a byte address to the 24-bit
10611 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns
10612 the number of the flash segment (the 64 KiB chunk) where the address
10613 points to. Counting starts at @code{0}.
10614 If the address does not point to flash memory, return @code{-1}.
10617 unsigned char __builtin_avr_insert_bits (unsigned long map, unsigned char bits, unsigned char val)
10621 Insert bits from @var{bits} into @var{val} and return the resulting
10622 value. The nibbles of @var{map} determine how the insertion is
10623 performed: Let @var{X} be the @var{n}-th nibble of @var{map}
10625 @item If @var{X} is @code{0xf},
10626 then the @var{n}-th bit of @var{val} is returned unaltered.
10628 @item If X is in the range 0@dots{}7,
10629 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits}
10631 @item If X is in the range 8@dots{}@code{0xe},
10632 then the @var{n}-th result bit is undefined.
10636 One typical use case for this built-in is adjusting input and
10637 output values to non-contiguous port layouts. Some examples:
10640 // same as val, bits is unused
10641 __builtin_avr_insert_bits (0xffffffff, bits, val)
10645 // same as bits, val is unused
10646 __builtin_avr_insert_bits (0x76543210, bits, val)
10650 // same as rotating bits by 4
10651 __builtin_avr_insert_bits (0x32107654, bits, 0)
10655 // high nibble of result is the high nibble of val
10656 // low nibble of result is the low nibble of bits
10657 __builtin_avr_insert_bits (0xffff3210, bits, val)
10661 // reverse the bit order of bits
10662 __builtin_avr_insert_bits (0x01234567, bits, 0)
10665 @node Blackfin Built-in Functions
10666 @subsection Blackfin Built-in Functions
10668 Currently, there are two Blackfin-specific built-in functions. These are
10669 used for generating @code{CSYNC} and @code{SSYNC} machine insns without
10670 using inline assembly; by using these built-in functions the compiler can
10671 automatically add workarounds for hardware errata involving these
10672 instructions. These functions are named as follows:
10675 void __builtin_bfin_csync (void)
10676 void __builtin_bfin_ssync (void)
10679 @node FR-V Built-in Functions
10680 @subsection FR-V Built-in Functions
10682 GCC provides many FR-V-specific built-in functions. In general,
10683 these functions are intended to be compatible with those described
10684 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu
10685 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and
10686 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by
10687 pointer rather than by value.
10689 Most of the functions are named after specific FR-V instructions.
10690 Such functions are said to be ``directly mapped'' and are summarized
10691 here in tabular form.
10695 * Directly-mapped Integer Functions::
10696 * Directly-mapped Media Functions::
10697 * Raw read/write Functions::
10698 * Other Built-in Functions::
10701 @node Argument Types
10702 @subsubsection Argument Types
10704 The arguments to the built-in functions can be divided into three groups:
10705 register numbers, compile-time constants and run-time values. In order
10706 to make this classification clear at a glance, the arguments and return
10707 values are given the following pseudo types:
10709 @multitable @columnfractions .20 .30 .15 .35
10710 @item Pseudo type @tab Real C type @tab Constant? @tab Description
10711 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword
10712 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word
10713 @item @code{sw1} @tab @code{int} @tab No @tab a signed word
10714 @item @code{uw2} @tab @code{unsigned long long} @tab No
10715 @tab an unsigned doubleword
10716 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword
10717 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant
10718 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number
10719 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number
10722 These pseudo types are not defined by GCC, they are simply a notational
10723 convenience used in this manual.
10725 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2}
10726 and @code{sw2} are evaluated at run time. They correspond to
10727 register operands in the underlying FR-V instructions.
10729 @code{const} arguments represent immediate operands in the underlying
10730 FR-V instructions. They must be compile-time constants.
10732 @code{acc} arguments are evaluated at compile time and specify the number
10733 of an accumulator register. For example, an @code{acc} argument of 2
10734 selects the ACC2 register.
10736 @code{iacc} arguments are similar to @code{acc} arguments but specify the
10737 number of an IACC register. See @pxref{Other Built-in Functions}
10740 @node Directly-mapped Integer Functions
10741 @subsubsection Directly-mapped Integer Functions
10743 The functions listed below map directly to FR-V I-type instructions.
10745 @multitable @columnfractions .45 .32 .23
10746 @item Function prototype @tab Example usage @tab Assembly output
10747 @item @code{sw1 __ADDSS (sw1, sw1)}
10748 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})}
10749 @tab @code{ADDSS @var{a},@var{b},@var{c}}
10750 @item @code{sw1 __SCAN (sw1, sw1)}
10751 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})}
10752 @tab @code{SCAN @var{a},@var{b},@var{c}}
10753 @item @code{sw1 __SCUTSS (sw1)}
10754 @tab @code{@var{b} = __SCUTSS (@var{a})}
10755 @tab @code{SCUTSS @var{a},@var{b}}
10756 @item @code{sw1 __SLASS (sw1, sw1)}
10757 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})}
10758 @tab @code{SLASS @var{a},@var{b},@var{c}}
10759 @item @code{void __SMASS (sw1, sw1)}
10760 @tab @code{__SMASS (@var{a}, @var{b})}
10761 @tab @code{SMASS @var{a},@var{b}}
10762 @item @code{void __SMSSS (sw1, sw1)}
10763 @tab @code{__SMSSS (@var{a}, @var{b})}
10764 @tab @code{SMSSS @var{a},@var{b}}
10765 @item @code{void __SMU (sw1, sw1)}
10766 @tab @code{__SMU (@var{a}, @var{b})}
10767 @tab @code{SMU @var{a},@var{b}}
10768 @item @code{sw2 __SMUL (sw1, sw1)}
10769 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})}
10770 @tab @code{SMUL @var{a},@var{b},@var{c}}
10771 @item @code{sw1 __SUBSS (sw1, sw1)}
10772 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})}
10773 @tab @code{SUBSS @var{a},@var{b},@var{c}}
10774 @item @code{uw2 __UMUL (uw1, uw1)}
10775 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})}
10776 @tab @code{UMUL @var{a},@var{b},@var{c}}
10779 @node Directly-mapped Media Functions
10780 @subsubsection Directly-mapped Media Functions
10782 The functions listed below map directly to FR-V M-type instructions.
10784 @multitable @columnfractions .45 .32 .23
10785 @item Function prototype @tab Example usage @tab Assembly output
10786 @item @code{uw1 __MABSHS (sw1)}
10787 @tab @code{@var{b} = __MABSHS (@var{a})}
10788 @tab @code{MABSHS @var{a},@var{b}}
10789 @item @code{void __MADDACCS (acc, acc)}
10790 @tab @code{__MADDACCS (@var{b}, @var{a})}
10791 @tab @code{MADDACCS @var{a},@var{b}}
10792 @item @code{sw1 __MADDHSS (sw1, sw1)}
10793 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})}
10794 @tab @code{MADDHSS @var{a},@var{b},@var{c}}
10795 @item @code{uw1 __MADDHUS (uw1, uw1)}
10796 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})}
10797 @tab @code{MADDHUS @var{a},@var{b},@var{c}}
10798 @item @code{uw1 __MAND (uw1, uw1)}
10799 @tab @code{@var{c} = __MAND (@var{a}, @var{b})}
10800 @tab @code{MAND @var{a},@var{b},@var{c}}
10801 @item @code{void __MASACCS (acc, acc)}
10802 @tab @code{__MASACCS (@var{b}, @var{a})}
10803 @tab @code{MASACCS @var{a},@var{b}}
10804 @item @code{uw1 __MAVEH (uw1, uw1)}
10805 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})}
10806 @tab @code{MAVEH @var{a},@var{b},@var{c}}
10807 @item @code{uw2 __MBTOH (uw1)}
10808 @tab @code{@var{b} = __MBTOH (@var{a})}
10809 @tab @code{MBTOH @var{a},@var{b}}
10810 @item @code{void __MBTOHE (uw1 *, uw1)}
10811 @tab @code{__MBTOHE (&@var{b}, @var{a})}
10812 @tab @code{MBTOHE @var{a},@var{b}}
10813 @item @code{void __MCLRACC (acc)}
10814 @tab @code{__MCLRACC (@var{a})}
10815 @tab @code{MCLRACC @var{a}}
10816 @item @code{void __MCLRACCA (void)}
10817 @tab @code{__MCLRACCA ()}
10818 @tab @code{MCLRACCA}
10819 @item @code{uw1 __Mcop1 (uw1, uw1)}
10820 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})}
10821 @tab @code{Mcop1 @var{a},@var{b},@var{c}}
10822 @item @code{uw1 __Mcop2 (uw1, uw1)}
10823 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})}
10824 @tab @code{Mcop2 @var{a},@var{b},@var{c}}
10825 @item @code{uw1 __MCPLHI (uw2, const)}
10826 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})}
10827 @tab @code{MCPLHI @var{a},#@var{b},@var{c}}
10828 @item @code{uw1 __MCPLI (uw2, const)}
10829 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})}
10830 @tab @code{MCPLI @var{a},#@var{b},@var{c}}
10831 @item @code{void __MCPXIS (acc, sw1, sw1)}
10832 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})}
10833 @tab @code{MCPXIS @var{a},@var{b},@var{c}}
10834 @item @code{void __MCPXIU (acc, uw1, uw1)}
10835 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})}
10836 @tab @code{MCPXIU @var{a},@var{b},@var{c}}
10837 @item @code{void __MCPXRS (acc, sw1, sw1)}
10838 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})}
10839 @tab @code{MCPXRS @var{a},@var{b},@var{c}}
10840 @item @code{void __MCPXRU (acc, uw1, uw1)}
10841 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})}
10842 @tab @code{MCPXRU @var{a},@var{b},@var{c}}
10843 @item @code{uw1 __MCUT (acc, uw1)}
10844 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})}
10845 @tab @code{MCUT @var{a},@var{b},@var{c}}
10846 @item @code{uw1 __MCUTSS (acc, sw1)}
10847 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})}
10848 @tab @code{MCUTSS @var{a},@var{b},@var{c}}
10849 @item @code{void __MDADDACCS (acc, acc)}
10850 @tab @code{__MDADDACCS (@var{b}, @var{a})}
10851 @tab @code{MDADDACCS @var{a},@var{b}}
10852 @item @code{void __MDASACCS (acc, acc)}
10853 @tab @code{__MDASACCS (@var{b}, @var{a})}
10854 @tab @code{MDASACCS @var{a},@var{b}}
10855 @item @code{uw2 __MDCUTSSI (acc, const)}
10856 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})}
10857 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}}
10858 @item @code{uw2 __MDPACKH (uw2, uw2)}
10859 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})}
10860 @tab @code{MDPACKH @var{a},@var{b},@var{c}}
10861 @item @code{uw2 __MDROTLI (uw2, const)}
10862 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})}
10863 @tab @code{MDROTLI @var{a},#@var{b},@var{c}}
10864 @item @code{void __MDSUBACCS (acc, acc)}
10865 @tab @code{__MDSUBACCS (@var{b}, @var{a})}
10866 @tab @code{MDSUBACCS @var{a},@var{b}}
10867 @item @code{void __MDUNPACKH (uw1 *, uw2)}
10868 @tab @code{__MDUNPACKH (&@var{b}, @var{a})}
10869 @tab @code{MDUNPACKH @var{a},@var{b}}
10870 @item @code{uw2 __MEXPDHD (uw1, const)}
10871 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})}
10872 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}}
10873 @item @code{uw1 __MEXPDHW (uw1, const)}
10874 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})}
10875 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}}
10876 @item @code{uw1 __MHDSETH (uw1, const)}
10877 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})}
10878 @tab @code{MHDSETH @var{a},#@var{b},@var{c}}
10879 @item @code{sw1 __MHDSETS (const)}
10880 @tab @code{@var{b} = __MHDSETS (@var{a})}
10881 @tab @code{MHDSETS #@var{a},@var{b}}
10882 @item @code{uw1 __MHSETHIH (uw1, const)}
10883 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})}
10884 @tab @code{MHSETHIH #@var{a},@var{b}}
10885 @item @code{sw1 __MHSETHIS (sw1, const)}
10886 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})}
10887 @tab @code{MHSETHIS #@var{a},@var{b}}
10888 @item @code{uw1 __MHSETLOH (uw1, const)}
10889 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})}
10890 @tab @code{MHSETLOH #@var{a},@var{b}}
10891 @item @code{sw1 __MHSETLOS (sw1, const)}
10892 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})}
10893 @tab @code{MHSETLOS #@var{a},@var{b}}
10894 @item @code{uw1 __MHTOB (uw2)}
10895 @tab @code{@var{b} = __MHTOB (@var{a})}
10896 @tab @code{MHTOB @var{a},@var{b}}
10897 @item @code{void __MMACHS (acc, sw1, sw1)}
10898 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})}
10899 @tab @code{MMACHS @var{a},@var{b},@var{c}}
10900 @item @code{void __MMACHU (acc, uw1, uw1)}
10901 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})}
10902 @tab @code{MMACHU @var{a},@var{b},@var{c}}
10903 @item @code{void __MMRDHS (acc, sw1, sw1)}
10904 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})}
10905 @tab @code{MMRDHS @var{a},@var{b},@var{c}}
10906 @item @code{void __MMRDHU (acc, uw1, uw1)}
10907 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})}
10908 @tab @code{MMRDHU @var{a},@var{b},@var{c}}
10909 @item @code{void __MMULHS (acc, sw1, sw1)}
10910 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})}
10911 @tab @code{MMULHS @var{a},@var{b},@var{c}}
10912 @item @code{void __MMULHU (acc, uw1, uw1)}
10913 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})}
10914 @tab @code{MMULHU @var{a},@var{b},@var{c}}
10915 @item @code{void __MMULXHS (acc, sw1, sw1)}
10916 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})}
10917 @tab @code{MMULXHS @var{a},@var{b},@var{c}}
10918 @item @code{void __MMULXHU (acc, uw1, uw1)}
10919 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})}
10920 @tab @code{MMULXHU @var{a},@var{b},@var{c}}
10921 @item @code{uw1 __MNOT (uw1)}
10922 @tab @code{@var{b} = __MNOT (@var{a})}
10923 @tab @code{MNOT @var{a},@var{b}}
10924 @item @code{uw1 __MOR (uw1, uw1)}
10925 @tab @code{@var{c} = __MOR (@var{a}, @var{b})}
10926 @tab @code{MOR @var{a},@var{b},@var{c}}
10927 @item @code{uw1 __MPACKH (uh, uh)}
10928 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})}
10929 @tab @code{MPACKH @var{a},@var{b},@var{c}}
10930 @item @code{sw2 __MQADDHSS (sw2, sw2)}
10931 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})}
10932 @tab @code{MQADDHSS @var{a},@var{b},@var{c}}
10933 @item @code{uw2 __MQADDHUS (uw2, uw2)}
10934 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})}
10935 @tab @code{MQADDHUS @var{a},@var{b},@var{c}}
10936 @item @code{void __MQCPXIS (acc, sw2, sw2)}
10937 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})}
10938 @tab @code{MQCPXIS @var{a},@var{b},@var{c}}
10939 @item @code{void __MQCPXIU (acc, uw2, uw2)}
10940 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})}
10941 @tab @code{MQCPXIU @var{a},@var{b},@var{c}}
10942 @item @code{void __MQCPXRS (acc, sw2, sw2)}
10943 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})}
10944 @tab @code{MQCPXRS @var{a},@var{b},@var{c}}
10945 @item @code{void __MQCPXRU (acc, uw2, uw2)}
10946 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})}
10947 @tab @code{MQCPXRU @var{a},@var{b},@var{c}}
10948 @item @code{sw2 __MQLCLRHS (sw2, sw2)}
10949 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})}
10950 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}}
10951 @item @code{sw2 __MQLMTHS (sw2, sw2)}
10952 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})}
10953 @tab @code{MQLMTHS @var{a},@var{b},@var{c}}
10954 @item @code{void __MQMACHS (acc, sw2, sw2)}
10955 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})}
10956 @tab @code{MQMACHS @var{a},@var{b},@var{c}}
10957 @item @code{void __MQMACHU (acc, uw2, uw2)}
10958 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})}
10959 @tab @code{MQMACHU @var{a},@var{b},@var{c}}
10960 @item @code{void __MQMACXHS (acc, sw2, sw2)}
10961 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})}
10962 @tab @code{MQMACXHS @var{a},@var{b},@var{c}}
10963 @item @code{void __MQMULHS (acc, sw2, sw2)}
10964 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})}
10965 @tab @code{MQMULHS @var{a},@var{b},@var{c}}
10966 @item @code{void __MQMULHU (acc, uw2, uw2)}
10967 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})}
10968 @tab @code{MQMULHU @var{a},@var{b},@var{c}}
10969 @item @code{void __MQMULXHS (acc, sw2, sw2)}
10970 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})}
10971 @tab @code{MQMULXHS @var{a},@var{b},@var{c}}
10972 @item @code{void __MQMULXHU (acc, uw2, uw2)}
10973 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})}
10974 @tab @code{MQMULXHU @var{a},@var{b},@var{c}}
10975 @item @code{sw2 __MQSATHS (sw2, sw2)}
10976 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})}
10977 @tab @code{MQSATHS @var{a},@var{b},@var{c}}
10978 @item @code{uw2 __MQSLLHI (uw2, int)}
10979 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})}
10980 @tab @code{MQSLLHI @var{a},@var{b},@var{c}}
10981 @item @code{sw2 __MQSRAHI (sw2, int)}
10982 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})}
10983 @tab @code{MQSRAHI @var{a},@var{b},@var{c}}
10984 @item @code{sw2 __MQSUBHSS (sw2, sw2)}
10985 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})}
10986 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}}
10987 @item @code{uw2 __MQSUBHUS (uw2, uw2)}
10988 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})}
10989 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}}
10990 @item @code{void __MQXMACHS (acc, sw2, sw2)}
10991 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})}
10992 @tab @code{MQXMACHS @var{a},@var{b},@var{c}}
10993 @item @code{void __MQXMACXHS (acc, sw2, sw2)}
10994 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})}
10995 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}}
10996 @item @code{uw1 __MRDACC (acc)}
10997 @tab @code{@var{b} = __MRDACC (@var{a})}
10998 @tab @code{MRDACC @var{a},@var{b}}
10999 @item @code{uw1 __MRDACCG (acc)}
11000 @tab @code{@var{b} = __MRDACCG (@var{a})}
11001 @tab @code{MRDACCG @var{a},@var{b}}
11002 @item @code{uw1 __MROTLI (uw1, const)}
11003 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})}
11004 @tab @code{MROTLI @var{a},#@var{b},@var{c}}
11005 @item @code{uw1 __MROTRI (uw1, const)}
11006 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})}
11007 @tab @code{MROTRI @var{a},#@var{b},@var{c}}
11008 @item @code{sw1 __MSATHS (sw1, sw1)}
11009 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})}
11010 @tab @code{MSATHS @var{a},@var{b},@var{c}}
11011 @item @code{uw1 __MSATHU (uw1, uw1)}
11012 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})}
11013 @tab @code{MSATHU @var{a},@var{b},@var{c}}
11014 @item @code{uw1 __MSLLHI (uw1, const)}
11015 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})}
11016 @tab @code{MSLLHI @var{a},#@var{b},@var{c}}
11017 @item @code{sw1 __MSRAHI (sw1, const)}
11018 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})}
11019 @tab @code{MSRAHI @var{a},#@var{b},@var{c}}
11020 @item @code{uw1 __MSRLHI (uw1, const)}
11021 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})}
11022 @tab @code{MSRLHI @var{a},#@var{b},@var{c}}
11023 @item @code{void __MSUBACCS (acc, acc)}
11024 @tab @code{__MSUBACCS (@var{b}, @var{a})}
11025 @tab @code{MSUBACCS @var{a},@var{b}}
11026 @item @code{sw1 __MSUBHSS (sw1, sw1)}
11027 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})}
11028 @tab @code{MSUBHSS @var{a},@var{b},@var{c}}
11029 @item @code{uw1 __MSUBHUS (uw1, uw1)}
11030 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})}
11031 @tab @code{MSUBHUS @var{a},@var{b},@var{c}}
11032 @item @code{void __MTRAP (void)}
11033 @tab @code{__MTRAP ()}
11035 @item @code{uw2 __MUNPACKH (uw1)}
11036 @tab @code{@var{b} = __MUNPACKH (@var{a})}
11037 @tab @code{MUNPACKH @var{a},@var{b}}
11038 @item @code{uw1 __MWCUT (uw2, uw1)}
11039 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})}
11040 @tab @code{MWCUT @var{a},@var{b},@var{c}}
11041 @item @code{void __MWTACC (acc, uw1)}
11042 @tab @code{__MWTACC (@var{b}, @var{a})}
11043 @tab @code{MWTACC @var{a},@var{b}}
11044 @item @code{void __MWTACCG (acc, uw1)}
11045 @tab @code{__MWTACCG (@var{b}, @var{a})}
11046 @tab @code{MWTACCG @var{a},@var{b}}
11047 @item @code{uw1 __MXOR (uw1, uw1)}
11048 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})}
11049 @tab @code{MXOR @var{a},@var{b},@var{c}}
11052 @node Raw read/write Functions
11053 @subsubsection Raw read/write Functions
11055 This sections describes built-in functions related to read and write
11056 instructions to access memory. These functions generate
11057 @code{membar} instructions to flush the I/O load and stores where
11058 appropriate, as described in Fujitsu's manual described above.
11062 @item unsigned char __builtin_read8 (void *@var{data})
11063 @item unsigned short __builtin_read16 (void *@var{data})
11064 @item unsigned long __builtin_read32 (void *@var{data})
11065 @item unsigned long long __builtin_read64 (void *@var{data})
11067 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum})
11068 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum})
11069 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum})
11070 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum})
11073 @node Other Built-in Functions
11074 @subsubsection Other Built-in Functions
11076 This section describes built-in functions that are not named after
11077 a specific FR-V instruction.
11080 @item sw2 __IACCreadll (iacc @var{reg})
11081 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved
11082 for future expansion and must be 0.
11084 @item sw1 __IACCreadl (iacc @var{reg})
11085 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1.
11086 Other values of @var{reg} are rejected as invalid.
11088 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x})
11089 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument
11090 is reserved for future expansion and must be 0.
11092 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x})
11093 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg}
11094 is 1. Other values of @var{reg} are rejected as invalid.
11096 @item void __data_prefetch0 (const void *@var{x})
11097 Use the @code{dcpl} instruction to load the contents of address @var{x}
11098 into the data cache.
11100 @item void __data_prefetch (const void *@var{x})
11101 Use the @code{nldub} instruction to load the contents of address @var{x}
11102 into the data cache. The instruction is issued in slot I1@.
11105 @node X86 Built-in Functions
11106 @subsection X86 Built-in Functions
11108 These built-in functions are available for the i386 and x86-64 family
11109 of computers, depending on the command-line switches used.
11111 If you specify command-line switches such as @option{-msse},
11112 the compiler could use the extended instruction sets even if the built-ins
11113 are not used explicitly in the program. For this reason, applications
11114 that perform run-time CPU detection must compile separate files for each
11115 supported architecture, using the appropriate flags. In particular,
11116 the file containing the CPU detection code should be compiled without
11119 The following machine modes are available for use with MMX built-in functions
11120 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers,
11121 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a
11122 vector of eight 8-bit integers. Some of the built-in functions operate on
11123 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode.
11125 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector
11126 of two 32-bit floating-point values.
11128 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit
11129 floating-point values. Some instructions use a vector of four 32-bit
11130 integers, these use @code{V4SI}. Finally, some instructions operate on an
11131 entire vector register, interpreting it as a 128-bit integer, these use mode
11134 In 64-bit mode, the x86-64 family of processors uses additional built-in
11135 functions for efficient use of @code{TF} (@code{__float128}) 128-bit
11136 floating point and @code{TC} 128-bit complex floating-point values.
11138 The following floating-point built-in functions are available in 64-bit
11139 mode. All of them implement the function that is part of the name.
11142 __float128 __builtin_fabsq (__float128)
11143 __float128 __builtin_copysignq (__float128, __float128)
11146 The following built-in function is always available.
11149 @item void __builtin_ia32_pause (void)
11150 Generates the @code{pause} machine instruction with a compiler memory
11154 The following floating-point built-in functions are made available in the
11158 @item __float128 __builtin_infq (void)
11159 Similar to @code{__builtin_inf}, except the return type is @code{__float128}.
11160 @findex __builtin_infq
11162 @item __float128 __builtin_huge_valq (void)
11163 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}.
11164 @findex __builtin_huge_valq
11167 The following built-in functions are always available and can be used to
11168 check the target platform type.
11170 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
11171 This function runs the CPU detection code to check the type of CPU and the
11172 features supported. This built-in function needs to be invoked along with the built-in functions
11173 to check CPU type and features, @code{__builtin_cpu_is} and
11174 @code{__builtin_cpu_supports}, only when used in a function that is
11175 executed before any constructors are called. The CPU detection code is
11176 automatically executed in a very high priority constructor.
11178 For example, this function has to be used in @code{ifunc} resolvers that
11179 check for CPU type using the built-in functions @code{__builtin_cpu_is}
11180 and @code{__builtin_cpu_supports}, or in constructors on targets that
11181 don't support constructor priority.
11184 static void (*resolve_memcpy (void)) (void)
11186 // ifunc resolvers fire before constructors, explicitly call the init
11188 __builtin_cpu_init ();
11189 if (__builtin_cpu_supports ("ssse3"))
11190 return ssse3_memcpy; // super fast memcpy with ssse3 instructions.
11192 return default_memcpy;
11195 void *memcpy (void *, const void *, size_t)
11196 __attribute__ ((ifunc ("resolve_memcpy")));
11201 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname})
11202 This function returns a positive integer if the run-time CPU
11203 is of type @var{cpuname}
11204 and returns @code{0} otherwise. The following CPU names can be detected:
11220 Intel Core i7 Nehalem CPU.
11223 Intel Core i7 Westmere CPU.
11226 Intel Core i7 Sandy Bridge CPU.
11232 AMD Family 10h CPU.
11235 AMD Family 10h Barcelona CPU.
11238 AMD Family 10h Shanghai CPU.
11241 AMD Family 10h Istanbul CPU.
11244 AMD Family 14h CPU.
11247 AMD Family 15h CPU.
11250 AMD Family 15h Bulldozer version 1.
11253 AMD Family 15h Bulldozer version 2.
11256 AMD Family 15h Bulldozer version 3.
11259 AMD Family 15h Bulldozer version 4.
11262 AMD Family 16h CPU.
11265 Here is an example:
11267 if (__builtin_cpu_is ("corei7"))
11269 do_corei7 (); // Core i7 specific implementation.
11273 do_generic (); // Generic implementation.
11278 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature})
11279 This function returns a positive integer if the run-time CPU
11280 supports @var{feature}
11281 and returns @code{0} otherwise. The following features can be detected:
11289 POPCNT instruction.
11297 SSSE3 instructions.
11299 SSE4.1 instructions.
11301 SSE4.2 instructions.
11308 Here is an example:
11310 if (__builtin_cpu_supports ("popcnt"))
11312 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc");
11316 count = generic_countbits (n); //generic implementation.
11322 The following built-in functions are made available by @option{-mmmx}.
11323 All of them generate the machine instruction that is part of the name.
11326 v8qi __builtin_ia32_paddb (v8qi, v8qi)
11327 v4hi __builtin_ia32_paddw (v4hi, v4hi)
11328 v2si __builtin_ia32_paddd (v2si, v2si)
11329 v8qi __builtin_ia32_psubb (v8qi, v8qi)
11330 v4hi __builtin_ia32_psubw (v4hi, v4hi)
11331 v2si __builtin_ia32_psubd (v2si, v2si)
11332 v8qi __builtin_ia32_paddsb (v8qi, v8qi)
11333 v4hi __builtin_ia32_paddsw (v4hi, v4hi)
11334 v8qi __builtin_ia32_psubsb (v8qi, v8qi)
11335 v4hi __builtin_ia32_psubsw (v4hi, v4hi)
11336 v8qi __builtin_ia32_paddusb (v8qi, v8qi)
11337 v4hi __builtin_ia32_paddusw (v4hi, v4hi)
11338 v8qi __builtin_ia32_psubusb (v8qi, v8qi)
11339 v4hi __builtin_ia32_psubusw (v4hi, v4hi)
11340 v4hi __builtin_ia32_pmullw (v4hi, v4hi)
11341 v4hi __builtin_ia32_pmulhw (v4hi, v4hi)
11342 di __builtin_ia32_pand (di, di)
11343 di __builtin_ia32_pandn (di,di)
11344 di __builtin_ia32_por (di, di)
11345 di __builtin_ia32_pxor (di, di)
11346 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi)
11347 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi)
11348 v2si __builtin_ia32_pcmpeqd (v2si, v2si)
11349 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi)
11350 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi)
11351 v2si __builtin_ia32_pcmpgtd (v2si, v2si)
11352 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi)
11353 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi)
11354 v2si __builtin_ia32_punpckhdq (v2si, v2si)
11355 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi)
11356 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi)
11357 v2si __builtin_ia32_punpckldq (v2si, v2si)
11358 v8qi __builtin_ia32_packsswb (v4hi, v4hi)
11359 v4hi __builtin_ia32_packssdw (v2si, v2si)
11360 v8qi __builtin_ia32_packuswb (v4hi, v4hi)
11362 v4hi __builtin_ia32_psllw (v4hi, v4hi)
11363 v2si __builtin_ia32_pslld (v2si, v2si)
11364 v1di __builtin_ia32_psllq (v1di, v1di)
11365 v4hi __builtin_ia32_psrlw (v4hi, v4hi)
11366 v2si __builtin_ia32_psrld (v2si, v2si)
11367 v1di __builtin_ia32_psrlq (v1di, v1di)
11368 v4hi __builtin_ia32_psraw (v4hi, v4hi)
11369 v2si __builtin_ia32_psrad (v2si, v2si)
11370 v4hi __builtin_ia32_psllwi (v4hi, int)
11371 v2si __builtin_ia32_pslldi (v2si, int)
11372 v1di __builtin_ia32_psllqi (v1di, int)
11373 v4hi __builtin_ia32_psrlwi (v4hi, int)
11374 v2si __builtin_ia32_psrldi (v2si, int)
11375 v1di __builtin_ia32_psrlqi (v1di, int)
11376 v4hi __builtin_ia32_psrawi (v4hi, int)
11377 v2si __builtin_ia32_psradi (v2si, int)
11381 The following built-in functions are made available either with
11382 @option{-msse}, or with a combination of @option{-m3dnow} and
11383 @option{-march=athlon}. All of them generate the machine
11384 instruction that is part of the name.
11387 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi)
11388 v8qi __builtin_ia32_pavgb (v8qi, v8qi)
11389 v4hi __builtin_ia32_pavgw (v4hi, v4hi)
11390 v1di __builtin_ia32_psadbw (v8qi, v8qi)
11391 v8qi __builtin_ia32_pmaxub (v8qi, v8qi)
11392 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi)
11393 v8qi __builtin_ia32_pminub (v8qi, v8qi)
11394 v4hi __builtin_ia32_pminsw (v4hi, v4hi)
11395 int __builtin_ia32_pmovmskb (v8qi)
11396 void __builtin_ia32_maskmovq (v8qi, v8qi, char *)
11397 void __builtin_ia32_movntq (di *, di)
11398 void __builtin_ia32_sfence (void)
11401 The following built-in functions are available when @option{-msse} is used.
11402 All of them generate the machine instruction that is part of the name.
11405 int __builtin_ia32_comieq (v4sf, v4sf)
11406 int __builtin_ia32_comineq (v4sf, v4sf)
11407 int __builtin_ia32_comilt (v4sf, v4sf)
11408 int __builtin_ia32_comile (v4sf, v4sf)
11409 int __builtin_ia32_comigt (v4sf, v4sf)
11410 int __builtin_ia32_comige (v4sf, v4sf)
11411 int __builtin_ia32_ucomieq (v4sf, v4sf)
11412 int __builtin_ia32_ucomineq (v4sf, v4sf)
11413 int __builtin_ia32_ucomilt (v4sf, v4sf)
11414 int __builtin_ia32_ucomile (v4sf, v4sf)
11415 int __builtin_ia32_ucomigt (v4sf, v4sf)
11416 int __builtin_ia32_ucomige (v4sf, v4sf)
11417 v4sf __builtin_ia32_addps (v4sf, v4sf)
11418 v4sf __builtin_ia32_subps (v4sf, v4sf)
11419 v4sf __builtin_ia32_mulps (v4sf, v4sf)
11420 v4sf __builtin_ia32_divps (v4sf, v4sf)
11421 v4sf __builtin_ia32_addss (v4sf, v4sf)
11422 v4sf __builtin_ia32_subss (v4sf, v4sf)
11423 v4sf __builtin_ia32_mulss (v4sf, v4sf)
11424 v4sf __builtin_ia32_divss (v4sf, v4sf)
11425 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf)
11426 v4sf __builtin_ia32_cmpltps (v4sf, v4sf)
11427 v4sf __builtin_ia32_cmpleps (v4sf, v4sf)
11428 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf)
11429 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf)
11430 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf)
11431 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf)
11432 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf)
11433 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf)
11434 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf)
11435 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf)
11436 v4sf __builtin_ia32_cmpordps (v4sf, v4sf)
11437 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf)
11438 v4sf __builtin_ia32_cmpltss (v4sf, v4sf)
11439 v4sf __builtin_ia32_cmpless (v4sf, v4sf)
11440 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf)
11441 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf)
11442 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf)
11443 v4sf __builtin_ia32_cmpnless (v4sf, v4sf)
11444 v4sf __builtin_ia32_cmpordss (v4sf, v4sf)
11445 v4sf __builtin_ia32_maxps (v4sf, v4sf)
11446 v4sf __builtin_ia32_maxss (v4sf, v4sf)
11447 v4sf __builtin_ia32_minps (v4sf, v4sf)
11448 v4sf __builtin_ia32_minss (v4sf, v4sf)
11449 v4sf __builtin_ia32_andps (v4sf, v4sf)
11450 v4sf __builtin_ia32_andnps (v4sf, v4sf)
11451 v4sf __builtin_ia32_orps (v4sf, v4sf)
11452 v4sf __builtin_ia32_xorps (v4sf, v4sf)
11453 v4sf __builtin_ia32_movss (v4sf, v4sf)
11454 v4sf __builtin_ia32_movhlps (v4sf, v4sf)
11455 v4sf __builtin_ia32_movlhps (v4sf, v4sf)
11456 v4sf __builtin_ia32_unpckhps (v4sf, v4sf)
11457 v4sf __builtin_ia32_unpcklps (v4sf, v4sf)
11458 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si)
11459 v4sf __builtin_ia32_cvtsi2ss (v4sf, int)
11460 v2si __builtin_ia32_cvtps2pi (v4sf)
11461 int __builtin_ia32_cvtss2si (v4sf)
11462 v2si __builtin_ia32_cvttps2pi (v4sf)
11463 int __builtin_ia32_cvttss2si (v4sf)
11464 v4sf __builtin_ia32_rcpps (v4sf)
11465 v4sf __builtin_ia32_rsqrtps (v4sf)
11466 v4sf __builtin_ia32_sqrtps (v4sf)
11467 v4sf __builtin_ia32_rcpss (v4sf)
11468 v4sf __builtin_ia32_rsqrtss (v4sf)
11469 v4sf __builtin_ia32_sqrtss (v4sf)
11470 v4sf __builtin_ia32_shufps (v4sf, v4sf, int)
11471 void __builtin_ia32_movntps (float *, v4sf)
11472 int __builtin_ia32_movmskps (v4sf)
11475 The following built-in functions are available when @option{-msse} is used.
11478 @item v4sf __builtin_ia32_loadups (float *)
11479 Generates the @code{movups} machine instruction as a load from memory.
11480 @item void __builtin_ia32_storeups (float *, v4sf)
11481 Generates the @code{movups} machine instruction as a store to memory.
11482 @item v4sf __builtin_ia32_loadss (float *)
11483 Generates the @code{movss} machine instruction as a load from memory.
11484 @item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *)
11485 Generates the @code{movhps} machine instruction as a load from memory.
11486 @item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *)
11487 Generates the @code{movlps} machine instruction as a load from memory
11488 @item void __builtin_ia32_storehps (v2sf *, v4sf)
11489 Generates the @code{movhps} machine instruction as a store to memory.
11490 @item void __builtin_ia32_storelps (v2sf *, v4sf)
11491 Generates the @code{movlps} machine instruction as a store to memory.
11494 The following built-in functions are available when @option{-msse2} is used.
11495 All of them generate the machine instruction that is part of the name.
11498 int __builtin_ia32_comisdeq (v2df, v2df)
11499 int __builtin_ia32_comisdlt (v2df, v2df)
11500 int __builtin_ia32_comisdle (v2df, v2df)
11501 int __builtin_ia32_comisdgt (v2df, v2df)
11502 int __builtin_ia32_comisdge (v2df, v2df)
11503 int __builtin_ia32_comisdneq (v2df, v2df)
11504 int __builtin_ia32_ucomisdeq (v2df, v2df)
11505 int __builtin_ia32_ucomisdlt (v2df, v2df)
11506 int __builtin_ia32_ucomisdle (v2df, v2df)
11507 int __builtin_ia32_ucomisdgt (v2df, v2df)
11508 int __builtin_ia32_ucomisdge (v2df, v2df)
11509 int __builtin_ia32_ucomisdneq (v2df, v2df)
11510 v2df __builtin_ia32_cmpeqpd (v2df, v2df)
11511 v2df __builtin_ia32_cmpltpd (v2df, v2df)
11512 v2df __builtin_ia32_cmplepd (v2df, v2df)
11513 v2df __builtin_ia32_cmpgtpd (v2df, v2df)
11514 v2df __builtin_ia32_cmpgepd (v2df, v2df)
11515 v2df __builtin_ia32_cmpunordpd (v2df, v2df)
11516 v2df __builtin_ia32_cmpneqpd (v2df, v2df)
11517 v2df __builtin_ia32_cmpnltpd (v2df, v2df)
11518 v2df __builtin_ia32_cmpnlepd (v2df, v2df)
11519 v2df __builtin_ia32_cmpngtpd (v2df, v2df)
11520 v2df __builtin_ia32_cmpngepd (v2df, v2df)
11521 v2df __builtin_ia32_cmpordpd (v2df, v2df)
11522 v2df __builtin_ia32_cmpeqsd (v2df, v2df)
11523 v2df __builtin_ia32_cmpltsd (v2df, v2df)
11524 v2df __builtin_ia32_cmplesd (v2df, v2df)
11525 v2df __builtin_ia32_cmpunordsd (v2df, v2df)
11526 v2df __builtin_ia32_cmpneqsd (v2df, v2df)
11527 v2df __builtin_ia32_cmpnltsd (v2df, v2df)
11528 v2df __builtin_ia32_cmpnlesd (v2df, v2df)
11529 v2df __builtin_ia32_cmpordsd (v2df, v2df)
11530 v2di __builtin_ia32_paddq (v2di, v2di)
11531 v2di __builtin_ia32_psubq (v2di, v2di)
11532 v2df __builtin_ia32_addpd (v2df, v2df)
11533 v2df __builtin_ia32_subpd (v2df, v2df)
11534 v2df __builtin_ia32_mulpd (v2df, v2df)
11535 v2df __builtin_ia32_divpd (v2df, v2df)
11536 v2df __builtin_ia32_addsd (v2df, v2df)
11537 v2df __builtin_ia32_subsd (v2df, v2df)
11538 v2df __builtin_ia32_mulsd (v2df, v2df)
11539 v2df __builtin_ia32_divsd (v2df, v2df)
11540 v2df __builtin_ia32_minpd (v2df, v2df)
11541 v2df __builtin_ia32_maxpd (v2df, v2df)
11542 v2df __builtin_ia32_minsd (v2df, v2df)
11543 v2df __builtin_ia32_maxsd (v2df, v2df)
11544 v2df __builtin_ia32_andpd (v2df, v2df)
11545 v2df __builtin_ia32_andnpd (v2df, v2df)
11546 v2df __builtin_ia32_orpd (v2df, v2df)
11547 v2df __builtin_ia32_xorpd (v2df, v2df)
11548 v2df __builtin_ia32_movsd (v2df, v2df)
11549 v2df __builtin_ia32_unpckhpd (v2df, v2df)
11550 v2df __builtin_ia32_unpcklpd (v2df, v2df)
11551 v16qi __builtin_ia32_paddb128 (v16qi, v16qi)
11552 v8hi __builtin_ia32_paddw128 (v8hi, v8hi)
11553 v4si __builtin_ia32_paddd128 (v4si, v4si)
11554 v2di __builtin_ia32_paddq128 (v2di, v2di)
11555 v16qi __builtin_ia32_psubb128 (v16qi, v16qi)
11556 v8hi __builtin_ia32_psubw128 (v8hi, v8hi)
11557 v4si __builtin_ia32_psubd128 (v4si, v4si)
11558 v2di __builtin_ia32_psubq128 (v2di, v2di)
11559 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi)
11560 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi)
11561 v2di __builtin_ia32_pand128 (v2di, v2di)
11562 v2di __builtin_ia32_pandn128 (v2di, v2di)
11563 v2di __builtin_ia32_por128 (v2di, v2di)
11564 v2di __builtin_ia32_pxor128 (v2di, v2di)
11565 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi)
11566 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi)
11567 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi)
11568 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi)
11569 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si)
11570 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi)
11571 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi)
11572 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si)
11573 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi)
11574 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi)
11575 v16qi __builtin_ia32_pminub128 (v16qi, v16qi)
11576 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi)
11577 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi)
11578 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi)
11579 v4si __builtin_ia32_punpckhdq128 (v4si, v4si)
11580 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di)
11581 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi)
11582 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi)
11583 v4si __builtin_ia32_punpckldq128 (v4si, v4si)
11584 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di)
11585 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi)
11586 v8hi __builtin_ia32_packssdw128 (v4si, v4si)
11587 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi)
11588 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi)
11589 void __builtin_ia32_maskmovdqu (v16qi, v16qi)
11590 v2df __builtin_ia32_loadupd (double *)
11591 void __builtin_ia32_storeupd (double *, v2df)
11592 v2df __builtin_ia32_loadhpd (v2df, double const *)
11593 v2df __builtin_ia32_loadlpd (v2df, double const *)
11594 int __builtin_ia32_movmskpd (v2df)
11595 int __builtin_ia32_pmovmskb128 (v16qi)
11596 void __builtin_ia32_movnti (int *, int)
11597 void __builtin_ia32_movnti64 (long long int *, long long int)
11598 void __builtin_ia32_movntpd (double *, v2df)
11599 void __builtin_ia32_movntdq (v2df *, v2df)
11600 v4si __builtin_ia32_pshufd (v4si, int)
11601 v8hi __builtin_ia32_pshuflw (v8hi, int)
11602 v8hi __builtin_ia32_pshufhw (v8hi, int)
11603 v2di __builtin_ia32_psadbw128 (v16qi, v16qi)
11604 v2df __builtin_ia32_sqrtpd (v2df)
11605 v2df __builtin_ia32_sqrtsd (v2df)
11606 v2df __builtin_ia32_shufpd (v2df, v2df, int)
11607 v2df __builtin_ia32_cvtdq2pd (v4si)
11608 v4sf __builtin_ia32_cvtdq2ps (v4si)
11609 v4si __builtin_ia32_cvtpd2dq (v2df)
11610 v2si __builtin_ia32_cvtpd2pi (v2df)
11611 v4sf __builtin_ia32_cvtpd2ps (v2df)
11612 v4si __builtin_ia32_cvttpd2dq (v2df)
11613 v2si __builtin_ia32_cvttpd2pi (v2df)
11614 v2df __builtin_ia32_cvtpi2pd (v2si)
11615 int __builtin_ia32_cvtsd2si (v2df)
11616 int __builtin_ia32_cvttsd2si (v2df)
11617 long long __builtin_ia32_cvtsd2si64 (v2df)
11618 long long __builtin_ia32_cvttsd2si64 (v2df)
11619 v4si __builtin_ia32_cvtps2dq (v4sf)
11620 v2df __builtin_ia32_cvtps2pd (v4sf)
11621 v4si __builtin_ia32_cvttps2dq (v4sf)
11622 v2df __builtin_ia32_cvtsi2sd (v2df, int)
11623 v2df __builtin_ia32_cvtsi642sd (v2df, long long)
11624 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df)
11625 v2df __builtin_ia32_cvtss2sd (v2df, v4sf)
11626 void __builtin_ia32_clflush (const void *)
11627 void __builtin_ia32_lfence (void)
11628 void __builtin_ia32_mfence (void)
11629 v16qi __builtin_ia32_loaddqu (const char *)
11630 void __builtin_ia32_storedqu (char *, v16qi)
11631 v1di __builtin_ia32_pmuludq (v2si, v2si)
11632 v2di __builtin_ia32_pmuludq128 (v4si, v4si)
11633 v8hi __builtin_ia32_psllw128 (v8hi, v8hi)
11634 v4si __builtin_ia32_pslld128 (v4si, v4si)
11635 v2di __builtin_ia32_psllq128 (v2di, v2di)
11636 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi)
11637 v4si __builtin_ia32_psrld128 (v4si, v4si)
11638 v2di __builtin_ia32_psrlq128 (v2di, v2di)
11639 v8hi __builtin_ia32_psraw128 (v8hi, v8hi)
11640 v4si __builtin_ia32_psrad128 (v4si, v4si)
11641 v2di __builtin_ia32_pslldqi128 (v2di, int)
11642 v8hi __builtin_ia32_psllwi128 (v8hi, int)
11643 v4si __builtin_ia32_pslldi128 (v4si, int)
11644 v2di __builtin_ia32_psllqi128 (v2di, int)
11645 v2di __builtin_ia32_psrldqi128 (v2di, int)
11646 v8hi __builtin_ia32_psrlwi128 (v8hi, int)
11647 v4si __builtin_ia32_psrldi128 (v4si, int)
11648 v2di __builtin_ia32_psrlqi128 (v2di, int)
11649 v8hi __builtin_ia32_psrawi128 (v8hi, int)
11650 v4si __builtin_ia32_psradi128 (v4si, int)
11651 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi)
11652 v2di __builtin_ia32_movq128 (v2di)
11655 The following built-in functions are available when @option{-msse3} is used.
11656 All of them generate the machine instruction that is part of the name.
11659 v2df __builtin_ia32_addsubpd (v2df, v2df)
11660 v4sf __builtin_ia32_addsubps (v4sf, v4sf)
11661 v2df __builtin_ia32_haddpd (v2df, v2df)
11662 v4sf __builtin_ia32_haddps (v4sf, v4sf)
11663 v2df __builtin_ia32_hsubpd (v2df, v2df)
11664 v4sf __builtin_ia32_hsubps (v4sf, v4sf)
11665 v16qi __builtin_ia32_lddqu (char const *)
11666 void __builtin_ia32_monitor (void *, unsigned int, unsigned int)
11667 v4sf __builtin_ia32_movshdup (v4sf)
11668 v4sf __builtin_ia32_movsldup (v4sf)
11669 void __builtin_ia32_mwait (unsigned int, unsigned int)
11672 The following built-in functions are available when @option{-mssse3} is used.
11673 All of them generate the machine instruction that is part of the name.
11676 v2si __builtin_ia32_phaddd (v2si, v2si)
11677 v4hi __builtin_ia32_phaddw (v4hi, v4hi)
11678 v4hi __builtin_ia32_phaddsw (v4hi, v4hi)
11679 v2si __builtin_ia32_phsubd (v2si, v2si)
11680 v4hi __builtin_ia32_phsubw (v4hi, v4hi)
11681 v4hi __builtin_ia32_phsubsw (v4hi, v4hi)
11682 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi)
11683 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi)
11684 v8qi __builtin_ia32_pshufb (v8qi, v8qi)
11685 v8qi __builtin_ia32_psignb (v8qi, v8qi)
11686 v2si __builtin_ia32_psignd (v2si, v2si)
11687 v4hi __builtin_ia32_psignw (v4hi, v4hi)
11688 v1di __builtin_ia32_palignr (v1di, v1di, int)
11689 v8qi __builtin_ia32_pabsb (v8qi)
11690 v2si __builtin_ia32_pabsd (v2si)
11691 v4hi __builtin_ia32_pabsw (v4hi)
11694 The following built-in functions are available when @option{-mssse3} is used.
11695 All of them generate the machine instruction that is part of the name.
11698 v4si __builtin_ia32_phaddd128 (v4si, v4si)
11699 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi)
11700 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi)
11701 v4si __builtin_ia32_phsubd128 (v4si, v4si)
11702 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi)
11703 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi)
11704 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi)
11705 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi)
11706 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi)
11707 v16qi __builtin_ia32_psignb128 (v16qi, v16qi)
11708 v4si __builtin_ia32_psignd128 (v4si, v4si)
11709 v8hi __builtin_ia32_psignw128 (v8hi, v8hi)
11710 v2di __builtin_ia32_palignr128 (v2di, v2di, int)
11711 v16qi __builtin_ia32_pabsb128 (v16qi)
11712 v4si __builtin_ia32_pabsd128 (v4si)
11713 v8hi __builtin_ia32_pabsw128 (v8hi)
11716 The following built-in functions are available when @option{-msse4.1} is
11717 used. All of them generate the machine instruction that is part of the
11721 v2df __builtin_ia32_blendpd (v2df, v2df, const int)
11722 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int)
11723 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df)
11724 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf)
11725 v2df __builtin_ia32_dppd (v2df, v2df, const int)
11726 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int)
11727 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int)
11728 v2di __builtin_ia32_movntdqa (v2di *);
11729 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int)
11730 v8hi __builtin_ia32_packusdw128 (v4si, v4si)
11731 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi)
11732 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int)
11733 v2di __builtin_ia32_pcmpeqq (v2di, v2di)
11734 v8hi __builtin_ia32_phminposuw128 (v8hi)
11735 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi)
11736 v4si __builtin_ia32_pmaxsd128 (v4si, v4si)
11737 v4si __builtin_ia32_pmaxud128 (v4si, v4si)
11738 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi)
11739 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi)
11740 v4si __builtin_ia32_pminsd128 (v4si, v4si)
11741 v4si __builtin_ia32_pminud128 (v4si, v4si)
11742 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi)
11743 v4si __builtin_ia32_pmovsxbd128 (v16qi)
11744 v2di __builtin_ia32_pmovsxbq128 (v16qi)
11745 v8hi __builtin_ia32_pmovsxbw128 (v16qi)
11746 v2di __builtin_ia32_pmovsxdq128 (v4si)
11747 v4si __builtin_ia32_pmovsxwd128 (v8hi)
11748 v2di __builtin_ia32_pmovsxwq128 (v8hi)
11749 v4si __builtin_ia32_pmovzxbd128 (v16qi)
11750 v2di __builtin_ia32_pmovzxbq128 (v16qi)
11751 v8hi __builtin_ia32_pmovzxbw128 (v16qi)
11752 v2di __builtin_ia32_pmovzxdq128 (v4si)
11753 v4si __builtin_ia32_pmovzxwd128 (v8hi)
11754 v2di __builtin_ia32_pmovzxwq128 (v8hi)
11755 v2di __builtin_ia32_pmuldq128 (v4si, v4si)
11756 v4si __builtin_ia32_pmulld128 (v4si, v4si)
11757 int __builtin_ia32_ptestc128 (v2di, v2di)
11758 int __builtin_ia32_ptestnzc128 (v2di, v2di)
11759 int __builtin_ia32_ptestz128 (v2di, v2di)
11760 v2df __builtin_ia32_roundpd (v2df, const int)
11761 v4sf __builtin_ia32_roundps (v4sf, const int)
11762 v2df __builtin_ia32_roundsd (v2df, v2df, const int)
11763 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int)
11766 The following built-in functions are available when @option{-msse4.1} is
11770 @item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int)
11771 Generates the @code{insertps} machine instruction.
11772 @item int __builtin_ia32_vec_ext_v16qi (v16qi, const int)
11773 Generates the @code{pextrb} machine instruction.
11774 @item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int)
11775 Generates the @code{pinsrb} machine instruction.
11776 @item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int)
11777 Generates the @code{pinsrd} machine instruction.
11778 @item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int)
11779 Generates the @code{pinsrq} machine instruction in 64bit mode.
11782 The following built-in functions are changed to generate new SSE4.1
11783 instructions when @option{-msse4.1} is used.
11786 @item float __builtin_ia32_vec_ext_v4sf (v4sf, const int)
11787 Generates the @code{extractps} machine instruction.
11788 @item int __builtin_ia32_vec_ext_v4si (v4si, const int)
11789 Generates the @code{pextrd} machine instruction.
11790 @item long long __builtin_ia32_vec_ext_v2di (v2di, const int)
11791 Generates the @code{pextrq} machine instruction in 64bit mode.
11794 The following built-in functions are available when @option{-msse4.2} is
11795 used. All of them generate the machine instruction that is part of the
11799 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int)
11800 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int)
11801 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int)
11802 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int)
11803 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int)
11804 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int)
11805 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int)
11806 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int)
11807 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int)
11808 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int)
11809 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int)
11810 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int)
11811 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int)
11812 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int)
11813 v2di __builtin_ia32_pcmpgtq (v2di, v2di)
11816 The following built-in functions are available when @option{-msse4.2} is
11820 @item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)
11821 Generates the @code{crc32b} machine instruction.
11822 @item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)
11823 Generates the @code{crc32w} machine instruction.
11824 @item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)
11825 Generates the @code{crc32l} machine instruction.
11826 @item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)
11827 Generates the @code{crc32q} machine instruction.
11830 The following built-in functions are changed to generate new SSE4.2
11831 instructions when @option{-msse4.2} is used.
11834 @item int __builtin_popcount (unsigned int)
11835 Generates the @code{popcntl} machine instruction.
11836 @item int __builtin_popcountl (unsigned long)
11837 Generates the @code{popcntl} or @code{popcntq} machine instruction,
11838 depending on the size of @code{unsigned long}.
11839 @item int __builtin_popcountll (unsigned long long)
11840 Generates the @code{popcntq} machine instruction.
11843 The following built-in functions are available when @option{-mavx} is
11844 used. All of them generate the machine instruction that is part of the
11848 v4df __builtin_ia32_addpd256 (v4df,v4df)
11849 v8sf __builtin_ia32_addps256 (v8sf,v8sf)
11850 v4df __builtin_ia32_addsubpd256 (v4df,v4df)
11851 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf)
11852 v4df __builtin_ia32_andnpd256 (v4df,v4df)
11853 v8sf __builtin_ia32_andnps256 (v8sf,v8sf)
11854 v4df __builtin_ia32_andpd256 (v4df,v4df)
11855 v8sf __builtin_ia32_andps256 (v8sf,v8sf)
11856 v4df __builtin_ia32_blendpd256 (v4df,v4df,int)
11857 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int)
11858 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df)
11859 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf)
11860 v2df __builtin_ia32_cmppd (v2df,v2df,int)
11861 v4df __builtin_ia32_cmppd256 (v4df,v4df,int)
11862 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int)
11863 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int)
11864 v2df __builtin_ia32_cmpsd (v2df,v2df,int)
11865 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int)
11866 v4df __builtin_ia32_cvtdq2pd256 (v4si)
11867 v8sf __builtin_ia32_cvtdq2ps256 (v8si)
11868 v4si __builtin_ia32_cvtpd2dq256 (v4df)
11869 v4sf __builtin_ia32_cvtpd2ps256 (v4df)
11870 v8si __builtin_ia32_cvtps2dq256 (v8sf)
11871 v4df __builtin_ia32_cvtps2pd256 (v4sf)
11872 v4si __builtin_ia32_cvttpd2dq256 (v4df)
11873 v8si __builtin_ia32_cvttps2dq256 (v8sf)
11874 v4df __builtin_ia32_divpd256 (v4df,v4df)
11875 v8sf __builtin_ia32_divps256 (v8sf,v8sf)
11876 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int)
11877 v4df __builtin_ia32_haddpd256 (v4df,v4df)
11878 v8sf __builtin_ia32_haddps256 (v8sf,v8sf)
11879 v4df __builtin_ia32_hsubpd256 (v4df,v4df)
11880 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf)
11881 v32qi __builtin_ia32_lddqu256 (pcchar)
11882 v32qi __builtin_ia32_loaddqu256 (pcchar)
11883 v4df __builtin_ia32_loadupd256 (pcdouble)
11884 v8sf __builtin_ia32_loadups256 (pcfloat)
11885 v2df __builtin_ia32_maskloadpd (pcv2df,v2df)
11886 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df)
11887 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf)
11888 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf)
11889 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df)
11890 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df)
11891 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf)
11892 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf)
11893 v4df __builtin_ia32_maxpd256 (v4df,v4df)
11894 v8sf __builtin_ia32_maxps256 (v8sf,v8sf)
11895 v4df __builtin_ia32_minpd256 (v4df,v4df)
11896 v8sf __builtin_ia32_minps256 (v8sf,v8sf)
11897 v4df __builtin_ia32_movddup256 (v4df)
11898 int __builtin_ia32_movmskpd256 (v4df)
11899 int __builtin_ia32_movmskps256 (v8sf)
11900 v8sf __builtin_ia32_movshdup256 (v8sf)
11901 v8sf __builtin_ia32_movsldup256 (v8sf)
11902 v4df __builtin_ia32_mulpd256 (v4df,v4df)
11903 v8sf __builtin_ia32_mulps256 (v8sf,v8sf)
11904 v4df __builtin_ia32_orpd256 (v4df,v4df)
11905 v8sf __builtin_ia32_orps256 (v8sf,v8sf)
11906 v2df __builtin_ia32_pd_pd256 (v4df)
11907 v4df __builtin_ia32_pd256_pd (v2df)
11908 v4sf __builtin_ia32_ps_ps256 (v8sf)
11909 v8sf __builtin_ia32_ps256_ps (v4sf)
11910 int __builtin_ia32_ptestc256 (v4di,v4di,ptest)
11911 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest)
11912 int __builtin_ia32_ptestz256 (v4di,v4di,ptest)
11913 v8sf __builtin_ia32_rcpps256 (v8sf)
11914 v4df __builtin_ia32_roundpd256 (v4df,int)
11915 v8sf __builtin_ia32_roundps256 (v8sf,int)
11916 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf)
11917 v8sf __builtin_ia32_rsqrtps256 (v8sf)
11918 v4df __builtin_ia32_shufpd256 (v4df,v4df,int)
11919 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int)
11920 v4si __builtin_ia32_si_si256 (v8si)
11921 v8si __builtin_ia32_si256_si (v4si)
11922 v4df __builtin_ia32_sqrtpd256 (v4df)
11923 v8sf __builtin_ia32_sqrtps_nr256 (v8sf)
11924 v8sf __builtin_ia32_sqrtps256 (v8sf)
11925 void __builtin_ia32_storedqu256 (pchar,v32qi)
11926 void __builtin_ia32_storeupd256 (pdouble,v4df)
11927 void __builtin_ia32_storeups256 (pfloat,v8sf)
11928 v4df __builtin_ia32_subpd256 (v4df,v4df)
11929 v8sf __builtin_ia32_subps256 (v8sf,v8sf)
11930 v4df __builtin_ia32_unpckhpd256 (v4df,v4df)
11931 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf)
11932 v4df __builtin_ia32_unpcklpd256 (v4df,v4df)
11933 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf)
11934 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df)
11935 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf)
11936 v4df __builtin_ia32_vbroadcastsd256 (pcdouble)
11937 v4sf __builtin_ia32_vbroadcastss (pcfloat)
11938 v8sf __builtin_ia32_vbroadcastss256 (pcfloat)
11939 v2df __builtin_ia32_vextractf128_pd256 (v4df,int)
11940 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int)
11941 v4si __builtin_ia32_vextractf128_si256 (v8si,int)
11942 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int)
11943 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int)
11944 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int)
11945 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int)
11946 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int)
11947 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int)
11948 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int)
11949 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int)
11950 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int)
11951 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int)
11952 v2df __builtin_ia32_vpermilpd (v2df,int)
11953 v4df __builtin_ia32_vpermilpd256 (v4df,int)
11954 v4sf __builtin_ia32_vpermilps (v4sf,int)
11955 v8sf __builtin_ia32_vpermilps256 (v8sf,int)
11956 v2df __builtin_ia32_vpermilvarpd (v2df,v2di)
11957 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di)
11958 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si)
11959 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si)
11960 int __builtin_ia32_vtestcpd (v2df,v2df,ptest)
11961 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest)
11962 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest)
11963 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest)
11964 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest)
11965 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest)
11966 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest)
11967 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest)
11968 int __builtin_ia32_vtestzpd (v2df,v2df,ptest)
11969 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest)
11970 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest)
11971 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest)
11972 void __builtin_ia32_vzeroall (void)
11973 void __builtin_ia32_vzeroupper (void)
11974 v4df __builtin_ia32_xorpd256 (v4df,v4df)
11975 v8sf __builtin_ia32_xorps256 (v8sf,v8sf)
11978 The following built-in functions are available when @option{-mavx2} is
11979 used. All of them generate the machine instruction that is part of the
11983 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int)
11984 v32qi __builtin_ia32_pabsb256 (v32qi)
11985 v16hi __builtin_ia32_pabsw256 (v16hi)
11986 v8si __builtin_ia32_pabsd256 (v8si)
11987 v16hi __builtin_ia32_packssdw256 (v8si,v8si)
11988 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi)
11989 v16hi __builtin_ia32_packusdw256 (v8si,v8si)
11990 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi)
11991 v32qi __builtin_ia32_paddb256 (v32qi,v32qi)
11992 v16hi __builtin_ia32_paddw256 (v16hi,v16hi)
11993 v8si __builtin_ia32_paddd256 (v8si,v8si)
11994 v4di __builtin_ia32_paddq256 (v4di,v4di)
11995 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi)
11996 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi)
11997 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi)
11998 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi)
11999 v4di __builtin_ia32_palignr256 (v4di,v4di,int)
12000 v4di __builtin_ia32_andsi256 (v4di,v4di)
12001 v4di __builtin_ia32_andnotsi256 (v4di,v4di)
12002 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi)
12003 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi)
12004 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi)
12005 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int)
12006 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi)
12007 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi)
12008 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si)
12009 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di)
12010 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi)
12011 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi)
12012 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si)
12013 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di)
12014 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi)
12015 v8si __builtin_ia32_phaddd256 (v8si,v8si)
12016 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi)
12017 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi)
12018 v8si __builtin_ia32_phsubd256 (v8si,v8si)
12019 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi)
12020 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi)
12021 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi)
12022 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi)
12023 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi)
12024 v8si __builtin_ia32_pmaxsd256 (v8si,v8si)
12025 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi)
12026 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi)
12027 v8si __builtin_ia32_pmaxud256 (v8si,v8si)
12028 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi)
12029 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi)
12030 v8si __builtin_ia32_pminsd256 (v8si,v8si)
12031 v32qi __builtin_ia32_pminub256 (v32qi,v32qi)
12032 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi)
12033 v8si __builtin_ia32_pminud256 (v8si,v8si)
12034 int __builtin_ia32_pmovmskb256 (v32qi)
12035 v16hi __builtin_ia32_pmovsxbw256 (v16qi)
12036 v8si __builtin_ia32_pmovsxbd256 (v16qi)
12037 v4di __builtin_ia32_pmovsxbq256 (v16qi)
12038 v8si __builtin_ia32_pmovsxwd256 (v8hi)
12039 v4di __builtin_ia32_pmovsxwq256 (v8hi)
12040 v4di __builtin_ia32_pmovsxdq256 (v4si)
12041 v16hi __builtin_ia32_pmovzxbw256 (v16qi)
12042 v8si __builtin_ia32_pmovzxbd256 (v16qi)
12043 v4di __builtin_ia32_pmovzxbq256 (v16qi)
12044 v8si __builtin_ia32_pmovzxwd256 (v8hi)
12045 v4di __builtin_ia32_pmovzxwq256 (v8hi)
12046 v4di __builtin_ia32_pmovzxdq256 (v4si)
12047 v4di __builtin_ia32_pmuldq256 (v8si,v8si)
12048 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi)
12049 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi)
12050 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi)
12051 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi)
12052 v8si __builtin_ia32_pmulld256 (v8si,v8si)
12053 v4di __builtin_ia32_pmuludq256 (v8si,v8si)
12054 v4di __builtin_ia32_por256 (v4di,v4di)
12055 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi)
12056 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi)
12057 v8si __builtin_ia32_pshufd256 (v8si,int)
12058 v16hi __builtin_ia32_pshufhw256 (v16hi,int)
12059 v16hi __builtin_ia32_pshuflw256 (v16hi,int)
12060 v32qi __builtin_ia32_psignb256 (v32qi,v32qi)
12061 v16hi __builtin_ia32_psignw256 (v16hi,v16hi)
12062 v8si __builtin_ia32_psignd256 (v8si,v8si)
12063 v4di __builtin_ia32_pslldqi256 (v4di,int)
12064 v16hi __builtin_ia32_psllwi256 (16hi,int)
12065 v16hi __builtin_ia32_psllw256(v16hi,v8hi)
12066 v8si __builtin_ia32_pslldi256 (v8si,int)
12067 v8si __builtin_ia32_pslld256(v8si,v4si)
12068 v4di __builtin_ia32_psllqi256 (v4di,int)
12069 v4di __builtin_ia32_psllq256(v4di,v2di)
12070 v16hi __builtin_ia32_psrawi256 (v16hi,int)
12071 v16hi __builtin_ia32_psraw256 (v16hi,v8hi)
12072 v8si __builtin_ia32_psradi256 (v8si,int)
12073 v8si __builtin_ia32_psrad256 (v8si,v4si)
12074 v4di __builtin_ia32_psrldqi256 (v4di, int)
12075 v16hi __builtin_ia32_psrlwi256 (v16hi,int)
12076 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi)
12077 v8si __builtin_ia32_psrldi256 (v8si,int)
12078 v8si __builtin_ia32_psrld256 (v8si,v4si)
12079 v4di __builtin_ia32_psrlqi256 (v4di,int)
12080 v4di __builtin_ia32_psrlq256(v4di,v2di)
12081 v32qi __builtin_ia32_psubb256 (v32qi,v32qi)
12082 v32hi __builtin_ia32_psubw256 (v16hi,v16hi)
12083 v8si __builtin_ia32_psubd256 (v8si,v8si)
12084 v4di __builtin_ia32_psubq256 (v4di,v4di)
12085 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi)
12086 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi)
12087 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi)
12088 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi)
12089 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi)
12090 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi)
12091 v8si __builtin_ia32_punpckhdq256 (v8si,v8si)
12092 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di)
12093 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi)
12094 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi)
12095 v8si __builtin_ia32_punpckldq256 (v8si,v8si)
12096 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di)
12097 v4di __builtin_ia32_pxor256 (v4di,v4di)
12098 v4di __builtin_ia32_movntdqa256 (pv4di)
12099 v4sf __builtin_ia32_vbroadcastss_ps (v4sf)
12100 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf)
12101 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df)
12102 v4di __builtin_ia32_vbroadcastsi256 (v2di)
12103 v4si __builtin_ia32_pblendd128 (v4si,v4si)
12104 v8si __builtin_ia32_pblendd256 (v8si,v8si)
12105 v32qi __builtin_ia32_pbroadcastb256 (v16qi)
12106 v16hi __builtin_ia32_pbroadcastw256 (v8hi)
12107 v8si __builtin_ia32_pbroadcastd256 (v4si)
12108 v4di __builtin_ia32_pbroadcastq256 (v2di)
12109 v16qi __builtin_ia32_pbroadcastb128 (v16qi)
12110 v8hi __builtin_ia32_pbroadcastw128 (v8hi)
12111 v4si __builtin_ia32_pbroadcastd128 (v4si)
12112 v2di __builtin_ia32_pbroadcastq128 (v2di)
12113 v8si __builtin_ia32_permvarsi256 (v8si,v8si)
12114 v4df __builtin_ia32_permdf256 (v4df,int)
12115 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf)
12116 v4di __builtin_ia32_permdi256 (v4di,int)
12117 v4di __builtin_ia32_permti256 (v4di,v4di,int)
12118 v4di __builtin_ia32_extract128i256 (v4di,int)
12119 v4di __builtin_ia32_insert128i256 (v4di,v2di,int)
12120 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si)
12121 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di)
12122 v4si __builtin_ia32_maskloadd (pcv4si,v4si)
12123 v2di __builtin_ia32_maskloadq (pcv2di,v2di)
12124 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si)
12125 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di)
12126 void __builtin_ia32_maskstored (pv4si,v4si,v4si)
12127 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di)
12128 v8si __builtin_ia32_psllv8si (v8si,v8si)
12129 v4si __builtin_ia32_psllv4si (v4si,v4si)
12130 v4di __builtin_ia32_psllv4di (v4di,v4di)
12131 v2di __builtin_ia32_psllv2di (v2di,v2di)
12132 v8si __builtin_ia32_psrav8si (v8si,v8si)
12133 v4si __builtin_ia32_psrav4si (v4si,v4si)
12134 v8si __builtin_ia32_psrlv8si (v8si,v8si)
12135 v4si __builtin_ia32_psrlv4si (v4si,v4si)
12136 v4di __builtin_ia32_psrlv4di (v4di,v4di)
12137 v2di __builtin_ia32_psrlv2di (v2di,v2di)
12138 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int)
12139 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int)
12140 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int)
12141 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int)
12142 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int)
12143 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int)
12144 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int)
12145 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int)
12146 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int)
12147 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int)
12148 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int)
12149 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int)
12150 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int)
12151 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int)
12152 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int)
12153 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int)
12156 The following built-in functions are available when @option{-maes} is
12157 used. All of them generate the machine instruction that is part of the
12161 v2di __builtin_ia32_aesenc128 (v2di, v2di)
12162 v2di __builtin_ia32_aesenclast128 (v2di, v2di)
12163 v2di __builtin_ia32_aesdec128 (v2di, v2di)
12164 v2di __builtin_ia32_aesdeclast128 (v2di, v2di)
12165 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int)
12166 v2di __builtin_ia32_aesimc128 (v2di)
12169 The following built-in function is available when @option{-mpclmul} is
12173 @item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int)
12174 Generates the @code{pclmulqdq} machine instruction.
12177 The following built-in function is available when @option{-mfsgsbase} is
12178 used. All of them generate the machine instruction that is part of the
12182 unsigned int __builtin_ia32_rdfsbase32 (void)
12183 unsigned long long __builtin_ia32_rdfsbase64 (void)
12184 unsigned int __builtin_ia32_rdgsbase32 (void)
12185 unsigned long long __builtin_ia32_rdgsbase64 (void)
12186 void _writefsbase_u32 (unsigned int)
12187 void _writefsbase_u64 (unsigned long long)
12188 void _writegsbase_u32 (unsigned int)
12189 void _writegsbase_u64 (unsigned long long)
12192 The following built-in function is available when @option{-mrdrnd} is
12193 used. All of them generate the machine instruction that is part of the
12197 unsigned int __builtin_ia32_rdrand16_step (unsigned short *)
12198 unsigned int __builtin_ia32_rdrand32_step (unsigned int *)
12199 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *)
12202 The following built-in functions are available when @option{-msse4a} is used.
12203 All of them generate the machine instruction that is part of the name.
12206 void __builtin_ia32_movntsd (double *, v2df)
12207 void __builtin_ia32_movntss (float *, v4sf)
12208 v2di __builtin_ia32_extrq (v2di, v16qi)
12209 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int)
12210 v2di __builtin_ia32_insertq (v2di, v2di)
12211 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int)
12214 The following built-in functions are available when @option{-mxop} is used.
12216 v2df __builtin_ia32_vfrczpd (v2df)
12217 v4sf __builtin_ia32_vfrczps (v4sf)
12218 v2df __builtin_ia32_vfrczsd (v2df)
12219 v4sf __builtin_ia32_vfrczss (v4sf)
12220 v4df __builtin_ia32_vfrczpd256 (v4df)
12221 v8sf __builtin_ia32_vfrczps256 (v8sf)
12222 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di)
12223 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di)
12224 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si)
12225 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi)
12226 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi)
12227 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df)
12228 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf)
12229 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di)
12230 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si)
12231 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi)
12232 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi)
12233 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df)
12234 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf)
12235 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi)
12236 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
12237 v4si __builtin_ia32_vpcomeqd (v4si, v4si)
12238 v2di __builtin_ia32_vpcomeqq (v2di, v2di)
12239 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi)
12240 v4si __builtin_ia32_vpcomequd (v4si, v4si)
12241 v2di __builtin_ia32_vpcomequq (v2di, v2di)
12242 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi)
12243 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi)
12244 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi)
12245 v4si __builtin_ia32_vpcomfalsed (v4si, v4si)
12246 v2di __builtin_ia32_vpcomfalseq (v2di, v2di)
12247 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi)
12248 v4si __builtin_ia32_vpcomfalseud (v4si, v4si)
12249 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di)
12250 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi)
12251 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi)
12252 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi)
12253 v4si __builtin_ia32_vpcomged (v4si, v4si)
12254 v2di __builtin_ia32_vpcomgeq (v2di, v2di)
12255 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi)
12256 v4si __builtin_ia32_vpcomgeud (v4si, v4si)
12257 v2di __builtin_ia32_vpcomgeuq (v2di, v2di)
12258 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi)
12259 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi)
12260 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi)
12261 v4si __builtin_ia32_vpcomgtd (v4si, v4si)
12262 v2di __builtin_ia32_vpcomgtq (v2di, v2di)
12263 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi)
12264 v4si __builtin_ia32_vpcomgtud (v4si, v4si)
12265 v2di __builtin_ia32_vpcomgtuq (v2di, v2di)
12266 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi)
12267 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi)
12268 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi)
12269 v4si __builtin_ia32_vpcomled (v4si, v4si)
12270 v2di __builtin_ia32_vpcomleq (v2di, v2di)
12271 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi)
12272 v4si __builtin_ia32_vpcomleud (v4si, v4si)
12273 v2di __builtin_ia32_vpcomleuq (v2di, v2di)
12274 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi)
12275 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi)
12276 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi)
12277 v4si __builtin_ia32_vpcomltd (v4si, v4si)
12278 v2di __builtin_ia32_vpcomltq (v2di, v2di)
12279 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi)
12280 v4si __builtin_ia32_vpcomltud (v4si, v4si)
12281 v2di __builtin_ia32_vpcomltuq (v2di, v2di)
12282 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi)
12283 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi)
12284 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi)
12285 v4si __builtin_ia32_vpcomned (v4si, v4si)
12286 v2di __builtin_ia32_vpcomneq (v2di, v2di)
12287 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi)
12288 v4si __builtin_ia32_vpcomneud (v4si, v4si)
12289 v2di __builtin_ia32_vpcomneuq (v2di, v2di)
12290 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi)
12291 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi)
12292 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi)
12293 v4si __builtin_ia32_vpcomtrued (v4si, v4si)
12294 v2di __builtin_ia32_vpcomtrueq (v2di, v2di)
12295 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi)
12296 v4si __builtin_ia32_vpcomtrueud (v4si, v4si)
12297 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di)
12298 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi)
12299 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi)
12300 v4si __builtin_ia32_vphaddbd (v16qi)
12301 v2di __builtin_ia32_vphaddbq (v16qi)
12302 v8hi __builtin_ia32_vphaddbw (v16qi)
12303 v2di __builtin_ia32_vphadddq (v4si)
12304 v4si __builtin_ia32_vphaddubd (v16qi)
12305 v2di __builtin_ia32_vphaddubq (v16qi)
12306 v8hi __builtin_ia32_vphaddubw (v16qi)
12307 v2di __builtin_ia32_vphaddudq (v4si)
12308 v4si __builtin_ia32_vphadduwd (v8hi)
12309 v2di __builtin_ia32_vphadduwq (v8hi)
12310 v4si __builtin_ia32_vphaddwd (v8hi)
12311 v2di __builtin_ia32_vphaddwq (v8hi)
12312 v8hi __builtin_ia32_vphsubbw (v16qi)
12313 v2di __builtin_ia32_vphsubdq (v4si)
12314 v4si __builtin_ia32_vphsubwd (v8hi)
12315 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si)
12316 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di)
12317 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di)
12318 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si)
12319 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di)
12320 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di)
12321 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si)
12322 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi)
12323 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si)
12324 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi)
12325 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si)
12326 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si)
12327 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi)
12328 v16qi __builtin_ia32_vprotb (v16qi, v16qi)
12329 v4si __builtin_ia32_vprotd (v4si, v4si)
12330 v2di __builtin_ia32_vprotq (v2di, v2di)
12331 v8hi __builtin_ia32_vprotw (v8hi, v8hi)
12332 v16qi __builtin_ia32_vpshab (v16qi, v16qi)
12333 v4si __builtin_ia32_vpshad (v4si, v4si)
12334 v2di __builtin_ia32_vpshaq (v2di, v2di)
12335 v8hi __builtin_ia32_vpshaw (v8hi, v8hi)
12336 v16qi __builtin_ia32_vpshlb (v16qi, v16qi)
12337 v4si __builtin_ia32_vpshld (v4si, v4si)
12338 v2di __builtin_ia32_vpshlq (v2di, v2di)
12339 v8hi __builtin_ia32_vpshlw (v8hi, v8hi)
12342 The following built-in functions are available when @option{-mfma4} is used.
12343 All of them generate the machine instruction that is part of the name.
12346 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df)
12347 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf)
12348 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df)
12349 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf)
12350 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df)
12351 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf)
12352 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df)
12353 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf)
12354 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df)
12355 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf)
12356 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df)
12357 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf)
12358 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df)
12359 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf)
12360 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df)
12361 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf)
12362 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df)
12363 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf)
12364 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df)
12365 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf)
12366 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df)
12367 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf)
12368 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df)
12369 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf)
12370 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df)
12371 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf)
12372 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df)
12373 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf)
12374 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df)
12375 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf)
12376 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df)
12377 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf)
12381 The following built-in functions are available when @option{-mlwp} is used.
12384 void __builtin_ia32_llwpcb16 (void *);
12385 void __builtin_ia32_llwpcb32 (void *);
12386 void __builtin_ia32_llwpcb64 (void *);
12387 void * __builtin_ia32_llwpcb16 (void);
12388 void * __builtin_ia32_llwpcb32 (void);
12389 void * __builtin_ia32_llwpcb64 (void);
12390 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short)
12391 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int)
12392 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int)
12393 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short)
12394 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int)
12395 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int)
12398 The following built-in functions are available when @option{-mbmi} is used.
12399 All of them generate the machine instruction that is part of the name.
12401 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int);
12402 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long);
12405 The following built-in functions are available when @option{-mbmi2} is used.
12406 All of them generate the machine instruction that is part of the name.
12408 unsigned int _bzhi_u32 (unsigned int, unsigned int)
12409 unsigned int _pdep_u32 (unsigned int, unsigned int)
12410 unsigned int _pext_u32 (unsigned int, unsigned int)
12411 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long)
12412 unsigned long long _pdep_u64 (unsigned long long, unsigned long long)
12413 unsigned long long _pext_u64 (unsigned long long, unsigned long long)
12416 The following built-in functions are available when @option{-mlzcnt} is used.
12417 All of them generate the machine instruction that is part of the name.
12419 unsigned short __builtin_ia32_lzcnt_16(unsigned short);
12420 unsigned int __builtin_ia32_lzcnt_u32(unsigned int);
12421 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long);
12424 The following built-in functions are available when @option{-mfxsr} is used.
12425 All of them generate the machine instruction that is part of the name.
12427 void __builtin_ia32_fxsave (void *)
12428 void __builtin_ia32_fxrstor (void *)
12429 void __builtin_ia32_fxsave64 (void *)
12430 void __builtin_ia32_fxrstor64 (void *)
12433 The following built-in functions are available when @option{-mxsave} is used.
12434 All of them generate the machine instruction that is part of the name.
12436 void __builtin_ia32_xsave (void *, long long)
12437 void __builtin_ia32_xrstor (void *, long long)
12438 void __builtin_ia32_xsave64 (void *, long long)
12439 void __builtin_ia32_xrstor64 (void *, long long)
12442 The following built-in functions are available when @option{-mxsaveopt} is used.
12443 All of them generate the machine instruction that is part of the name.
12445 void __builtin_ia32_xsaveopt (void *, long long)
12446 void __builtin_ia32_xsaveopt64 (void *, long long)
12449 The following built-in functions are available when @option{-mtbm} is used.
12450 Both of them generate the immediate form of the bextr machine instruction.
12452 unsigned int __builtin_ia32_bextri_u32 (unsigned int, const unsigned int);
12453 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, const unsigned long long);
12457 The following built-in functions are available when @option{-m3dnow} is used.
12458 All of them generate the machine instruction that is part of the name.
12461 void __builtin_ia32_femms (void)
12462 v8qi __builtin_ia32_pavgusb (v8qi, v8qi)
12463 v2si __builtin_ia32_pf2id (v2sf)
12464 v2sf __builtin_ia32_pfacc (v2sf, v2sf)
12465 v2sf __builtin_ia32_pfadd (v2sf, v2sf)
12466 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf)
12467 v2si __builtin_ia32_pfcmpge (v2sf, v2sf)
12468 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf)
12469 v2sf __builtin_ia32_pfmax (v2sf, v2sf)
12470 v2sf __builtin_ia32_pfmin (v2sf, v2sf)
12471 v2sf __builtin_ia32_pfmul (v2sf, v2sf)
12472 v2sf __builtin_ia32_pfrcp (v2sf)
12473 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf)
12474 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf)
12475 v2sf __builtin_ia32_pfrsqrt (v2sf)
12476 v2sf __builtin_ia32_pfsub (v2sf, v2sf)
12477 v2sf __builtin_ia32_pfsubr (v2sf, v2sf)
12478 v2sf __builtin_ia32_pi2fd (v2si)
12479 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi)
12482 The following built-in functions are available when both @option{-m3dnow}
12483 and @option{-march=athlon} are used. All of them generate the machine
12484 instruction that is part of the name.
12487 v2si __builtin_ia32_pf2iw (v2sf)
12488 v2sf __builtin_ia32_pfnacc (v2sf, v2sf)
12489 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf)
12490 v2sf __builtin_ia32_pi2fw (v2si)
12491 v2sf __builtin_ia32_pswapdsf (v2sf)
12492 v2si __builtin_ia32_pswapdsi (v2si)
12495 The following built-in functions are available when @option{-mrtm} is used
12496 They are used for restricted transactional memory. These are the internal
12497 low level functions. Normally the functions in
12498 @ref{X86 transactional memory intrinsics} should be used instead.
12501 int __builtin_ia32_xbegin ()
12502 void __builtin_ia32_xend ()
12503 void __builtin_ia32_xabort (status)
12504 int __builtin_ia32_xtest ()
12507 @node X86 transactional memory intrinsics
12508 @subsection X86 transaction memory intrinsics
12510 Hardware transactional memory intrinsics for i386. These allow to use
12511 memory transactions with RTM (Restricted Transactional Memory).
12512 For using HLE (Hardware Lock Elision) see @ref{x86 specific memory model extensions for transactional memory} instead.
12513 This support is enabled with the @option{-mrtm} option.
12515 A memory transaction commits all changes to memory in an atomic way,
12516 as visible to other threads. If the transaction fails it is rolled back
12517 and all side effects discarded.
12519 Generally there is no guarantee that a memory transaction ever succeeds
12520 and suitable fallback code always needs to be supplied.
12522 @deftypefn {RTM Function} {unsigned} _xbegin ()
12523 Start a RTM (Restricted Transactional Memory) transaction.
12524 Returns _XBEGIN_STARTED when the transaction
12525 started successfully (note this is not 0, so the constant has to be
12526 explicitely tested). When the transaction aborts all side effects
12527 are undone and an abort code is returned. There is no guarantee
12528 any transaction ever succeeds, so there always needs to be a valid
12529 tested fallback path.
12533 #include <immintrin.h>
12535 if ((status = _xbegin ()) == _XBEGIN_STARTED) @{
12536 ... transaction code...
12539 ... non transactional fallback path...
12543 Valid abort status bits (when the value is not @code{_XBEGIN_STARTED}) are:
12546 @item _XABORT_EXPLICIT
12547 Transaction explicitely aborted with @code{_xabort}. The parameter passed
12548 to @code{_xabort} is available with @code{_XABORT_CODE(status)}
12549 @item _XABORT_RETRY
12550 Transaction retry is possible.
12551 @item _XABORT_CONFLICT
12552 Transaction abort due to a memory conflict with another thread
12553 @item _XABORT_CAPACITY
12554 Transaction abort due to the transaction using too much memory
12555 @item _XABORT_DEBUG
12556 Transaction abort due to a debug trap
12557 @item _XABORT_NESTED
12558 Transaction abort in a inner nested transaction
12561 @deftypefn {RTM Function} {void} _xend ()
12562 Commit the current transaction. When no transaction is active this will
12563 fault. All memory side effects of the transactions will become visible
12564 to other threads in an atomic matter.
12567 @deftypefn {RTM Function} {int} _xtest ()
12568 Return a value not zero when a transaction is currently active, otherwise 0.
12571 @deftypefn {RTM Function} {void} _xabort (status)
12572 Abort the current transaction. When no transaction is active this is a no-op.
12573 status must be a 8bit constant, that is included in the status code returned
12577 @node MIPS DSP Built-in Functions
12578 @subsection MIPS DSP Built-in Functions
12580 The MIPS DSP Application-Specific Extension (ASE) includes new
12581 instructions that are designed to improve the performance of DSP and
12582 media applications. It provides instructions that operate on packed
12583 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data.
12585 GCC supports MIPS DSP operations using both the generic
12586 vector extensions (@pxref{Vector Extensions}) and a collection of
12587 MIPS-specific built-in functions. Both kinds of support are
12588 enabled by the @option{-mdsp} command-line option.
12590 Revision 2 of the ASE was introduced in the second half of 2006.
12591 This revision adds extra instructions to the original ASE, but is
12592 otherwise backwards-compatible with it. You can select revision 2
12593 using the command-line option @option{-mdspr2}; this option implies
12596 The SCOUNT and POS bits of the DSP control register are global. The
12597 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and
12598 POS bits. During optimization, the compiler does not delete these
12599 instructions and it does not delete calls to functions containing
12600 these instructions.
12602 At present, GCC only provides support for operations on 32-bit
12603 vectors. The vector type associated with 8-bit integer data is
12604 usually called @code{v4i8}, the vector type associated with Q7
12605 is usually called @code{v4q7}, the vector type associated with 16-bit
12606 integer data is usually called @code{v2i16}, and the vector type
12607 associated with Q15 is usually called @code{v2q15}. They can be
12608 defined in C as follows:
12611 typedef signed char v4i8 __attribute__ ((vector_size(4)));
12612 typedef signed char v4q7 __attribute__ ((vector_size(4)));
12613 typedef short v2i16 __attribute__ ((vector_size(4)));
12614 typedef short v2q15 __attribute__ ((vector_size(4)));
12617 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are
12618 initialized in the same way as aggregates. For example:
12621 v4i8 a = @{1, 2, 3, 4@};
12623 b = (v4i8) @{5, 6, 7, 8@};
12625 v2q15 c = @{0x0fcb, 0x3a75@};
12627 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@};
12630 @emph{Note:} The CPU's endianness determines the order in which values
12631 are packed. On little-endian targets, the first value is the least
12632 significant and the last value is the most significant. The opposite
12633 order applies to big-endian targets. For example, the code above
12634 sets the lowest byte of @code{a} to @code{1} on little-endian targets
12635 and @code{4} on big-endian targets.
12637 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer
12638 representation. As shown in this example, the integer representation
12639 of a Q7 value can be obtained by multiplying the fractional value by
12640 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by
12641 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by
12644 The table below lists the @code{v4i8} and @code{v2q15} operations for which
12645 hardware support exists. @code{a} and @code{b} are @code{v4i8} values,
12646 and @code{c} and @code{d} are @code{v2q15} values.
12648 @multitable @columnfractions .50 .50
12649 @item C code @tab MIPS instruction
12650 @item @code{a + b} @tab @code{addu.qb}
12651 @item @code{c + d} @tab @code{addq.ph}
12652 @item @code{a - b} @tab @code{subu.qb}
12653 @item @code{c - d} @tab @code{subq.ph}
12656 The table below lists the @code{v2i16} operation for which
12657 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are
12658 @code{v2i16} values.
12660 @multitable @columnfractions .50 .50
12661 @item C code @tab MIPS instruction
12662 @item @code{e * f} @tab @code{mul.ph}
12665 It is easier to describe the DSP built-in functions if we first define
12666 the following types:
12671 typedef unsigned int ui32;
12672 typedef long long a64;
12675 @code{q31} and @code{i32} are actually the same as @code{int}, but we
12676 use @code{q31} to indicate a Q31 fractional value and @code{i32} to
12677 indicate a 32-bit integer value. Similarly, @code{a64} is the same as
12678 @code{long long}, but we use @code{a64} to indicate values that are
12679 placed in one of the four DSP accumulators (@code{$ac0},
12680 @code{$ac1}, @code{$ac2} or @code{$ac3}).
12682 Also, some built-in functions prefer or require immediate numbers as
12683 parameters, because the corresponding DSP instructions accept both immediate
12684 numbers and register operands, or accept immediate numbers only. The
12685 immediate parameters are listed as follows.
12693 imm0_255: 0 to 255.
12694 imm_n32_31: -32 to 31.
12695 imm_n512_511: -512 to 511.
12698 The following built-in functions map directly to a particular MIPS DSP
12699 instruction. Please refer to the architecture specification
12700 for details on what each instruction does.
12703 v2q15 __builtin_mips_addq_ph (v2q15, v2q15)
12704 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15)
12705 q31 __builtin_mips_addq_s_w (q31, q31)
12706 v4i8 __builtin_mips_addu_qb (v4i8, v4i8)
12707 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8)
12708 v2q15 __builtin_mips_subq_ph (v2q15, v2q15)
12709 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15)
12710 q31 __builtin_mips_subq_s_w (q31, q31)
12711 v4i8 __builtin_mips_subu_qb (v4i8, v4i8)
12712 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8)
12713 i32 __builtin_mips_addsc (i32, i32)
12714 i32 __builtin_mips_addwc (i32, i32)
12715 i32 __builtin_mips_modsub (i32, i32)
12716 i32 __builtin_mips_raddu_w_qb (v4i8)
12717 v2q15 __builtin_mips_absq_s_ph (v2q15)
12718 q31 __builtin_mips_absq_s_w (q31)
12719 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15)
12720 v2q15 __builtin_mips_precrq_ph_w (q31, q31)
12721 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31)
12722 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15)
12723 q31 __builtin_mips_preceq_w_phl (v2q15)
12724 q31 __builtin_mips_preceq_w_phr (v2q15)
12725 v2q15 __builtin_mips_precequ_ph_qbl (v4i8)
12726 v2q15 __builtin_mips_precequ_ph_qbr (v4i8)
12727 v2q15 __builtin_mips_precequ_ph_qbla (v4i8)
12728 v2q15 __builtin_mips_precequ_ph_qbra (v4i8)
12729 v2q15 __builtin_mips_preceu_ph_qbl (v4i8)
12730 v2q15 __builtin_mips_preceu_ph_qbr (v4i8)
12731 v2q15 __builtin_mips_preceu_ph_qbla (v4i8)
12732 v2q15 __builtin_mips_preceu_ph_qbra (v4i8)
12733 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7)
12734 v4i8 __builtin_mips_shll_qb (v4i8, i32)
12735 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15)
12736 v2q15 __builtin_mips_shll_ph (v2q15, i32)
12737 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15)
12738 v2q15 __builtin_mips_shll_s_ph (v2q15, i32)
12739 q31 __builtin_mips_shll_s_w (q31, imm0_31)
12740 q31 __builtin_mips_shll_s_w (q31, i32)
12741 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7)
12742 v4i8 __builtin_mips_shrl_qb (v4i8, i32)
12743 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15)
12744 v2q15 __builtin_mips_shra_ph (v2q15, i32)
12745 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15)
12746 v2q15 __builtin_mips_shra_r_ph (v2q15, i32)
12747 q31 __builtin_mips_shra_r_w (q31, imm0_31)
12748 q31 __builtin_mips_shra_r_w (q31, i32)
12749 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15)
12750 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15)
12751 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15)
12752 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15)
12753 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15)
12754 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8)
12755 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8)
12756 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8)
12757 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8)
12758 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15)
12759 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31)
12760 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15)
12761 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31)
12762 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15)
12763 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15)
12764 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15)
12765 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15)
12766 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15)
12767 i32 __builtin_mips_bitrev (i32)
12768 i32 __builtin_mips_insv (i32, i32)
12769 v4i8 __builtin_mips_repl_qb (imm0_255)
12770 v4i8 __builtin_mips_repl_qb (i32)
12771 v2q15 __builtin_mips_repl_ph (imm_n512_511)
12772 v2q15 __builtin_mips_repl_ph (i32)
12773 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8)
12774 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8)
12775 void __builtin_mips_cmpu_le_qb (v4i8, v4i8)
12776 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8)
12777 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8)
12778 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8)
12779 void __builtin_mips_cmp_eq_ph (v2q15, v2q15)
12780 void __builtin_mips_cmp_lt_ph (v2q15, v2q15)
12781 void __builtin_mips_cmp_le_ph (v2q15, v2q15)
12782 v4i8 __builtin_mips_pick_qb (v4i8, v4i8)
12783 v2q15 __builtin_mips_pick_ph (v2q15, v2q15)
12784 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15)
12785 i32 __builtin_mips_extr_w (a64, imm0_31)
12786 i32 __builtin_mips_extr_w (a64, i32)
12787 i32 __builtin_mips_extr_r_w (a64, imm0_31)
12788 i32 __builtin_mips_extr_s_h (a64, i32)
12789 i32 __builtin_mips_extr_rs_w (a64, imm0_31)
12790 i32 __builtin_mips_extr_rs_w (a64, i32)
12791 i32 __builtin_mips_extr_s_h (a64, imm0_31)
12792 i32 __builtin_mips_extr_r_w (a64, i32)
12793 i32 __builtin_mips_extp (a64, imm0_31)
12794 i32 __builtin_mips_extp (a64, i32)
12795 i32 __builtin_mips_extpdp (a64, imm0_31)
12796 i32 __builtin_mips_extpdp (a64, i32)
12797 a64 __builtin_mips_shilo (a64, imm_n32_31)
12798 a64 __builtin_mips_shilo (a64, i32)
12799 a64 __builtin_mips_mthlip (a64, i32)
12800 void __builtin_mips_wrdsp (i32, imm0_63)
12801 i32 __builtin_mips_rddsp (imm0_63)
12802 i32 __builtin_mips_lbux (void *, i32)
12803 i32 __builtin_mips_lhx (void *, i32)
12804 i32 __builtin_mips_lwx (void *, i32)
12805 a64 __builtin_mips_ldx (void *, i32) [MIPS64 only]
12806 i32 __builtin_mips_bposge32 (void)
12807 a64 __builtin_mips_madd (a64, i32, i32);
12808 a64 __builtin_mips_maddu (a64, ui32, ui32);
12809 a64 __builtin_mips_msub (a64, i32, i32);
12810 a64 __builtin_mips_msubu (a64, ui32, ui32);
12811 a64 __builtin_mips_mult (i32, i32);
12812 a64 __builtin_mips_multu (ui32, ui32);
12815 The following built-in functions map directly to a particular MIPS DSP REV 2
12816 instruction. Please refer to the architecture specification
12817 for details on what each instruction does.
12820 v4q7 __builtin_mips_absq_s_qb (v4q7);
12821 v2i16 __builtin_mips_addu_ph (v2i16, v2i16);
12822 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16);
12823 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8);
12824 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8);
12825 i32 __builtin_mips_append (i32, i32, imm0_31);
12826 i32 __builtin_mips_balign (i32, i32, imm0_3);
12827 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8);
12828 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8);
12829 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8);
12830 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16);
12831 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16);
12832 v2i16 __builtin_mips_mul_ph (v2i16, v2i16);
12833 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16);
12834 q31 __builtin_mips_mulq_rs_w (q31, q31);
12835 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15);
12836 q31 __builtin_mips_mulq_s_w (q31, q31);
12837 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16);
12838 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16);
12839 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31);
12840 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31);
12841 i32 __builtin_mips_prepend (i32, i32, imm0_31);
12842 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7);
12843 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7);
12844 v4i8 __builtin_mips_shra_qb (v4i8, i32);
12845 v4i8 __builtin_mips_shra_r_qb (v4i8, i32);
12846 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15);
12847 v2i16 __builtin_mips_shrl_ph (v2i16, i32);
12848 v2i16 __builtin_mips_subu_ph (v2i16, v2i16);
12849 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16);
12850 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8);
12851 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8);
12852 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15);
12853 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15);
12854 q31 __builtin_mips_addqh_w (q31, q31);
12855 q31 __builtin_mips_addqh_r_w (q31, q31);
12856 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15);
12857 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15);
12858 q31 __builtin_mips_subqh_w (q31, q31);
12859 q31 __builtin_mips_subqh_r_w (q31, q31);
12860 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16);
12861 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16);
12862 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15);
12863 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15);
12864 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15);
12865 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15);
12869 @node MIPS Paired-Single Support
12870 @subsection MIPS Paired-Single Support
12872 The MIPS64 architecture includes a number of instructions that
12873 operate on pairs of single-precision floating-point values.
12874 Each pair is packed into a 64-bit floating-point register,
12875 with one element being designated the ``upper half'' and
12876 the other being designated the ``lower half''.
12878 GCC supports paired-single operations using both the generic
12879 vector extensions (@pxref{Vector Extensions}) and a collection of
12880 MIPS-specific built-in functions. Both kinds of support are
12881 enabled by the @option{-mpaired-single} command-line option.
12883 The vector type associated with paired-single values is usually
12884 called @code{v2sf}. It can be defined in C as follows:
12887 typedef float v2sf __attribute__ ((vector_size (8)));
12890 @code{v2sf} values are initialized in the same way as aggregates.
12894 v2sf a = @{1.5, 9.1@};
12897 b = (v2sf) @{e, f@};
12900 @emph{Note:} The CPU's endianness determines which value is stored in
12901 the upper half of a register and which value is stored in the lower half.
12902 On little-endian targets, the first value is the lower one and the second
12903 value is the upper one. The opposite order applies to big-endian targets.
12904 For example, the code above sets the lower half of @code{a} to
12905 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets.
12907 @node MIPS Loongson Built-in Functions
12908 @subsection MIPS Loongson Built-in Functions
12910 GCC provides intrinsics to access the SIMD instructions provided by the
12911 ST Microelectronics Loongson-2E and -2F processors. These intrinsics,
12912 available after inclusion of the @code{loongson.h} header file,
12913 operate on the following 64-bit vector types:
12916 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers;
12917 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers;
12918 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers;
12919 @item @code{int8x8_t}, a vector of eight signed 8-bit integers;
12920 @item @code{int16x4_t}, a vector of four signed 16-bit integers;
12921 @item @code{int32x2_t}, a vector of two signed 32-bit integers.
12924 The intrinsics provided are listed below; each is named after the
12925 machine instruction to which it corresponds, with suffixes added as
12926 appropriate to distinguish intrinsics that expand to the same machine
12927 instruction yet have different argument types. Refer to the architecture
12928 documentation for a description of the functionality of each
12932 int16x4_t packsswh (int32x2_t s, int32x2_t t);
12933 int8x8_t packsshb (int16x4_t s, int16x4_t t);
12934 uint8x8_t packushb (uint16x4_t s, uint16x4_t t);
12935 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t);
12936 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t);
12937 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t);
12938 int32x2_t paddw_s (int32x2_t s, int32x2_t t);
12939 int16x4_t paddh_s (int16x4_t s, int16x4_t t);
12940 int8x8_t paddb_s (int8x8_t s, int8x8_t t);
12941 uint64_t paddd_u (uint64_t s, uint64_t t);
12942 int64_t paddd_s (int64_t s, int64_t t);
12943 int16x4_t paddsh (int16x4_t s, int16x4_t t);
12944 int8x8_t paddsb (int8x8_t s, int8x8_t t);
12945 uint16x4_t paddush (uint16x4_t s, uint16x4_t t);
12946 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t);
12947 uint64_t pandn_ud (uint64_t s, uint64_t t);
12948 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t);
12949 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t);
12950 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t);
12951 int64_t pandn_sd (int64_t s, int64_t t);
12952 int32x2_t pandn_sw (int32x2_t s, int32x2_t t);
12953 int16x4_t pandn_sh (int16x4_t s, int16x4_t t);
12954 int8x8_t pandn_sb (int8x8_t s, int8x8_t t);
12955 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t);
12956 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t);
12957 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t);
12958 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t);
12959 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t);
12960 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t);
12961 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t);
12962 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t);
12963 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t);
12964 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t);
12965 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t);
12966 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t);
12967 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t);
12968 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t);
12969 uint16x4_t pextrh_u (uint16x4_t s, int field);
12970 int16x4_t pextrh_s (int16x4_t s, int field);
12971 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t);
12972 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t);
12973 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t);
12974 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t);
12975 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t);
12976 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t);
12977 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t);
12978 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t);
12979 int32x2_t pmaddhw (int16x4_t s, int16x4_t t);
12980 int16x4_t pmaxsh (int16x4_t s, int16x4_t t);
12981 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t);
12982 int16x4_t pminsh (int16x4_t s, int16x4_t t);
12983 uint8x8_t pminub (uint8x8_t s, uint8x8_t t);
12984 uint8x8_t pmovmskb_u (uint8x8_t s);
12985 int8x8_t pmovmskb_s (int8x8_t s);
12986 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t);
12987 int16x4_t pmulhh (int16x4_t s, int16x4_t t);
12988 int16x4_t pmullh (int16x4_t s, int16x4_t t);
12989 int64_t pmuluw (uint32x2_t s, uint32x2_t t);
12990 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t);
12991 uint16x4_t biadd (uint8x8_t s);
12992 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t);
12993 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order);
12994 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order);
12995 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount);
12996 int16x4_t psllh_s (int16x4_t s, uint8_t amount);
12997 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount);
12998 int32x2_t psllw_s (int32x2_t s, uint8_t amount);
12999 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount);
13000 int16x4_t psrlh_s (int16x4_t s, uint8_t amount);
13001 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount);
13002 int32x2_t psrlw_s (int32x2_t s, uint8_t amount);
13003 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount);
13004 int16x4_t psrah_s (int16x4_t s, uint8_t amount);
13005 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount);
13006 int32x2_t psraw_s (int32x2_t s, uint8_t amount);
13007 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t);
13008 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t);
13009 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t);
13010 int32x2_t psubw_s (int32x2_t s, int32x2_t t);
13011 int16x4_t psubh_s (int16x4_t s, int16x4_t t);
13012 int8x8_t psubb_s (int8x8_t s, int8x8_t t);
13013 uint64_t psubd_u (uint64_t s, uint64_t t);
13014 int64_t psubd_s (int64_t s, int64_t t);
13015 int16x4_t psubsh (int16x4_t s, int16x4_t t);
13016 int8x8_t psubsb (int8x8_t s, int8x8_t t);
13017 uint16x4_t psubush (uint16x4_t s, uint16x4_t t);
13018 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t);
13019 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t);
13020 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t);
13021 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t);
13022 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t);
13023 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t);
13024 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t);
13025 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t);
13026 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t);
13027 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t);
13028 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t);
13029 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t);
13030 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t);
13034 * Paired-Single Arithmetic::
13035 * Paired-Single Built-in Functions::
13036 * MIPS-3D Built-in Functions::
13039 @node Paired-Single Arithmetic
13040 @subsubsection Paired-Single Arithmetic
13042 The table below lists the @code{v2sf} operations for which hardware
13043 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf}
13044 values and @code{x} is an integral value.
13046 @multitable @columnfractions .50 .50
13047 @item C code @tab MIPS instruction
13048 @item @code{a + b} @tab @code{add.ps}
13049 @item @code{a - b} @tab @code{sub.ps}
13050 @item @code{-a} @tab @code{neg.ps}
13051 @item @code{a * b} @tab @code{mul.ps}
13052 @item @code{a * b + c} @tab @code{madd.ps}
13053 @item @code{a * b - c} @tab @code{msub.ps}
13054 @item @code{-(a * b + c)} @tab @code{nmadd.ps}
13055 @item @code{-(a * b - c)} @tab @code{nmsub.ps}
13056 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps}
13059 Note that the multiply-accumulate instructions can be disabled
13060 using the command-line option @code{-mno-fused-madd}.
13062 @node Paired-Single Built-in Functions
13063 @subsubsection Paired-Single Built-in Functions
13065 The following paired-single functions map directly to a particular
13066 MIPS instruction. Please refer to the architecture specification
13067 for details on what each instruction does.
13070 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf)
13071 Pair lower lower (@code{pll.ps}).
13073 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf)
13074 Pair upper lower (@code{pul.ps}).
13076 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf)
13077 Pair lower upper (@code{plu.ps}).
13079 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf)
13080 Pair upper upper (@code{puu.ps}).
13082 @item v2sf __builtin_mips_cvt_ps_s (float, float)
13083 Convert pair to paired single (@code{cvt.ps.s}).
13085 @item float __builtin_mips_cvt_s_pl (v2sf)
13086 Convert pair lower to single (@code{cvt.s.pl}).
13088 @item float __builtin_mips_cvt_s_pu (v2sf)
13089 Convert pair upper to single (@code{cvt.s.pu}).
13091 @item v2sf __builtin_mips_abs_ps (v2sf)
13092 Absolute value (@code{abs.ps}).
13094 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int)
13095 Align variable (@code{alnv.ps}).
13097 @emph{Note:} The value of the third parameter must be 0 or 4
13098 modulo 8, otherwise the result is unpredictable. Please read the
13099 instruction description for details.
13102 The following multi-instruction functions are also available.
13103 In each case, @var{cond} can be any of the 16 floating-point conditions:
13104 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
13105 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl},
13106 @code{lt}, @code{nge}, @code{le} or @code{ngt}.
13109 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13110 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13111 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps},
13112 @code{movt.ps}/@code{movf.ps}).
13114 The @code{movt} functions return the value @var{x} computed by:
13117 c.@var{cond}.ps @var{cc},@var{a},@var{b}
13118 mov.ps @var{x},@var{c}
13119 movt.ps @var{x},@var{d},@var{cc}
13122 The @code{movf} functions are similar but use @code{movf.ps} instead
13125 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13126 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13127 Comparison of two paired-single values (@code{c.@var{cond}.ps},
13128 @code{bc1t}/@code{bc1f}).
13130 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
13131 and return either the upper or lower half of the result. For example:
13135 if (__builtin_mips_upper_c_eq_ps (a, b))
13136 upper_halves_are_equal ();
13138 upper_halves_are_unequal ();
13140 if (__builtin_mips_lower_c_eq_ps (a, b))
13141 lower_halves_are_equal ();
13143 lower_halves_are_unequal ();
13147 @node MIPS-3D Built-in Functions
13148 @subsubsection MIPS-3D Built-in Functions
13150 The MIPS-3D Application-Specific Extension (ASE) includes additional
13151 paired-single instructions that are designed to improve the performance
13152 of 3D graphics operations. Support for these instructions is controlled
13153 by the @option{-mips3d} command-line option.
13155 The functions listed below map directly to a particular MIPS-3D
13156 instruction. Please refer to the architecture specification for
13157 more details on what each instruction does.
13160 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf)
13161 Reduction add (@code{addr.ps}).
13163 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf)
13164 Reduction multiply (@code{mulr.ps}).
13166 @item v2sf __builtin_mips_cvt_pw_ps (v2sf)
13167 Convert paired single to paired word (@code{cvt.pw.ps}).
13169 @item v2sf __builtin_mips_cvt_ps_pw (v2sf)
13170 Convert paired word to paired single (@code{cvt.ps.pw}).
13172 @item float __builtin_mips_recip1_s (float)
13173 @itemx double __builtin_mips_recip1_d (double)
13174 @itemx v2sf __builtin_mips_recip1_ps (v2sf)
13175 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}).
13177 @item float __builtin_mips_recip2_s (float, float)
13178 @itemx double __builtin_mips_recip2_d (double, double)
13179 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf)
13180 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}).
13182 @item float __builtin_mips_rsqrt1_s (float)
13183 @itemx double __builtin_mips_rsqrt1_d (double)
13184 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf)
13185 Reduced-precision reciprocal square root (sequence step 1)
13186 (@code{rsqrt1.@var{fmt}}).
13188 @item float __builtin_mips_rsqrt2_s (float, float)
13189 @itemx double __builtin_mips_rsqrt2_d (double, double)
13190 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf)
13191 Reduced-precision reciprocal square root (sequence step 2)
13192 (@code{rsqrt2.@var{fmt}}).
13195 The following multi-instruction functions are also available.
13196 In each case, @var{cond} can be any of the 16 floating-point conditions:
13197 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult},
13198 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq},
13199 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}.
13202 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b})
13203 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b})
13204 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}},
13205 @code{bc1t}/@code{bc1f}).
13207 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s}
13208 or @code{cabs.@var{cond}.d} and return the result as a boolean value.
13213 if (__builtin_mips_cabs_eq_s (a, b))
13219 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13220 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13221 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps},
13222 @code{bc1t}/@code{bc1f}).
13224 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps}
13225 and return either the upper or lower half of the result. For example:
13229 if (__builtin_mips_upper_cabs_eq_ps (a, b))
13230 upper_halves_are_equal ();
13232 upper_halves_are_unequal ();
13234 if (__builtin_mips_lower_cabs_eq_ps (a, b))
13235 lower_halves_are_equal ();
13237 lower_halves_are_unequal ();
13240 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13241 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13242 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps},
13243 @code{movt.ps}/@code{movf.ps}).
13245 The @code{movt} functions return the value @var{x} computed by:
13248 cabs.@var{cond}.ps @var{cc},@var{a},@var{b}
13249 mov.ps @var{x},@var{c}
13250 movt.ps @var{x},@var{d},@var{cc}
13253 The @code{movf} functions are similar but use @code{movf.ps} instead
13256 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13257 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13258 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13259 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b})
13260 Comparison of two paired-single values
13261 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
13262 @code{bc1any2t}/@code{bc1any2f}).
13264 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps}
13265 or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either
13266 result is true and the @code{all} forms return true if both results are true.
13271 if (__builtin_mips_any_c_eq_ps (a, b))
13276 if (__builtin_mips_all_c_eq_ps (a, b))
13282 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13283 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13284 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13285 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d})
13286 Comparison of four paired-single values
13287 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps},
13288 @code{bc1any4t}/@code{bc1any4f}).
13290 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps}
13291 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}.
13292 The @code{any} forms return true if any of the four results are true
13293 and the @code{all} forms return true if all four results are true.
13298 if (__builtin_mips_any_c_eq_4s (a, b, c, d))
13303 if (__builtin_mips_all_c_eq_4s (a, b, c, d))
13310 @node Other MIPS Built-in Functions
13311 @subsection Other MIPS Built-in Functions
13313 GCC provides other MIPS-specific built-in functions:
13316 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr})
13317 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
13318 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
13319 when this function is available.
13321 @item unsigned int __builtin_mips_get_fcsr (void)
13322 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
13323 Get and set the contents of the floating-point control and status register
13324 (FPU control register 31). These functions are only available in hard-float
13325 code but can be called in both MIPS16 and non-MIPS16 contexts.
13327 @code{__builtin_mips_set_fcsr} can be used to change any bit of the
13328 register except the condition codes, which GCC assumes are preserved.
13331 @node MSP430 Built-in Functions
13332 @subsection MSP430 Built-in Functions
13334 GCC provides a couple of special builtin functions to aid in the
13335 writing of interrupt handlers in C.
13338 @item __bic_SR_register_on_exit (int @var{mask})
13339 This clears the indicated bits in the saved copy of the status register
13340 currently residing on the stack. This only works inside interrupt
13341 handlers and the changes to the status register will only take affect
13342 once the handler returns.
13344 @item __bis_SR_register_on_exit (int @var{mask})
13345 This sets the indicated bits in the saved copy of the status register
13346 currently residing on the stack. This only works inside interrupt
13347 handlers and the changes to the status register will only take affect
13348 once the handler returns.
13350 @item __delay_cycles (long long @var{cycles})
13351 This inserts an instruction sequence that takes exactly @var{cycles}
13352 cycles (between 0 and about 17E9) to complete. The inserted sequence
13353 may use jumps, loops, or no-ops, and does not interfere with any other
13354 instructions. Note that @var{cycles} must be a compile-time constant
13355 integer - that is, you must pass a number, not a variable that may be
13356 optimized to a constant later. The number of cycles delayed by this
13360 @node NDS32 Built-in Functions
13361 @subsection NDS32 Built-in Functions
13363 These built-in functions are available for the NDS32 target:
13365 @deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr})
13366 Insert an ISYNC instruction into the instruction stream where
13367 @var{addr} is an instruction address for serialization.
13370 @deftypefn {Built-in Function} void __builtin_nds32_isb (void)
13371 Insert an ISB instruction into the instruction stream.
13374 @deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr})
13375 Return the content of a system register which is mapped by @var{sr}.
13378 @deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr})
13379 Return the content of a user space register which is mapped by @var{usr}.
13382 @deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr})
13383 Move the @var{value} to a system register which is mapped by @var{sr}.
13386 @deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr})
13387 Move the @var{value} to a user space register which is mapped by @var{usr}.
13390 @deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void)
13391 Enable global interrupt.
13394 @deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void)
13395 Disable global interrupt.
13398 @node picoChip Built-in Functions
13399 @subsection picoChip Built-in Functions
13401 GCC provides an interface to selected machine instructions from the
13402 picoChip instruction set.
13405 @item int __builtin_sbc (int @var{value})
13406 Sign bit count. Return the number of consecutive bits in @var{value}
13407 that have the same value as the sign bit. The result is the number of
13408 leading sign bits minus one, giving the number of redundant sign bits in
13411 @item int __builtin_byteswap (int @var{value})
13412 Byte swap. Return the result of swapping the upper and lower bytes of
13415 @item int __builtin_brev (int @var{value})
13416 Bit reversal. Return the result of reversing the bits in
13417 @var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1,
13420 @item int __builtin_adds (int @var{x}, int @var{y})
13421 Saturating addition. Return the result of adding @var{x} and @var{y},
13422 storing the value 32767 if the result overflows.
13424 @item int __builtin_subs (int @var{x}, int @var{y})
13425 Saturating subtraction. Return the result of subtracting @var{y} from
13426 @var{x}, storing the value @minus{}32768 if the result overflows.
13428 @item void __builtin_halt (void)
13429 Halt. The processor stops execution. This built-in is useful for
13430 implementing assertions.
13434 @node PowerPC Built-in Functions
13435 @subsection PowerPC Built-in Functions
13437 These built-in functions are available for the PowerPC family of
13440 float __builtin_recipdivf (float, float);
13441 float __builtin_rsqrtf (float);
13442 double __builtin_recipdiv (double, double);
13443 double __builtin_rsqrt (double);
13444 uint64_t __builtin_ppc_get_timebase ();
13445 unsigned long __builtin_ppc_mftb ();
13446 double __builtin_unpack_longdouble (long double, int);
13447 long double __builtin_pack_longdouble (double, double);
13450 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
13451 @code{__builtin_rsqrtf} functions generate multiple instructions to
13452 implement the reciprocal sqrt functionality using reciprocal sqrt
13453 estimate instructions.
13455 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf}
13456 functions generate multiple instructions to implement division using
13457 the reciprocal estimate instructions.
13459 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
13460 functions generate instructions to read the Time Base Register. The
13461 @code{__builtin_ppc_get_timebase} function may generate multiple
13462 instructions and always returns the 64 bits of the Time Base Register.
13463 The @code{__builtin_ppc_mftb} function always generates one instruction and
13464 returns the Time Base Register value as an unsigned long, throwing away
13465 the most significant word on 32-bit environments.
13467 The following built-in functions are available for the PowerPC family
13468 of processors, starting with ISA 2.06 or later (@option{-mcpu=power7}
13469 or @option{-mpopcntd}):
13471 long __builtin_bpermd (long, long);
13472 int __builtin_divwe (int, int);
13473 int __builtin_divweo (int, int);
13474 unsigned int __builtin_divweu (unsigned int, unsigned int);
13475 unsigned int __builtin_divweuo (unsigned int, unsigned int);
13476 long __builtin_divde (long, long);
13477 long __builtin_divdeo (long, long);
13478 unsigned long __builtin_divdeu (unsigned long, unsigned long);
13479 unsigned long __builtin_divdeuo (unsigned long, unsigned long);
13480 unsigned int cdtbcd (unsigned int);
13481 unsigned int cbcdtd (unsigned int);
13482 unsigned int addg6s (unsigned int, unsigned int);
13485 The @code{__builtin_divde}, @code{__builtin_divdeo},
13486 @code{__builitin_divdeu}, @code{__builtin_divdeou} functions require a
13487 64-bit environment support ISA 2.06 or later.
13489 The following built-in functions are available for the PowerPC family
13490 of processors when hardware decimal floating point
13491 (@option{-mhard-dfp}) is available:
13493 _Decimal64 __builtin_dxex (_Decimal64);
13494 _Decimal128 __builtin_dxexq (_Decimal128);
13495 _Decimal64 __builtin_ddedpd (int, _Decimal64);
13496 _Decimal128 __builtin_ddedpdq (int, _Decimal128);
13497 _Decimal64 __builtin_denbcd (int, _Decimal64);
13498 _Decimal128 __builtin_denbcdq (int, _Decimal128);
13499 _Decimal64 __builtin_diex (_Decimal64, _Decimal64);
13500 _Decimal128 _builtin_diexq (_Decimal128, _Decimal128);
13501 _Decimal64 __builtin_dscli (_Decimal64, int);
13502 _Decimal128 __builitn_dscliq (_Decimal128, int);
13503 _Decimal64 __builtin_dscri (_Decimal64, int);
13504 _Decimal128 __builitn_dscriq (_Decimal128, int);
13505 unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
13506 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
13509 The following built-in functions are available for the PowerPC family
13510 of processors when the Vector Scalar (vsx) instruction set is
13513 unsigned long long __builtin_unpack_vector_int128 (vector __int128_t, int);
13514 vector __int128_t __builtin_pack_vector_int128 (unsigned long long,
13515 unsigned long long);
13518 @node PowerPC AltiVec/VSX Built-in Functions
13519 @subsection PowerPC AltiVec Built-in Functions
13521 GCC provides an interface for the PowerPC family of processors to access
13522 the AltiVec operations described in Motorola's AltiVec Programming
13523 Interface Manual. The interface is made available by including
13524 @code{<altivec.h>} and using @option{-maltivec} and
13525 @option{-mabi=altivec}. The interface supports the following vector
13529 vector unsigned char
13533 vector unsigned short
13534 vector signed short
13538 vector unsigned int
13544 If @option{-mvsx} is used the following additional vector types are
13548 vector unsigned long
13553 The long types are only implemented for 64-bit code generation, and
13554 the long type is only used in the floating point/integer conversion
13557 GCC's implementation of the high-level language interface available from
13558 C and C++ code differs from Motorola's documentation in several ways.
13563 A vector constant is a list of constant expressions within curly braces.
13566 A vector initializer requires no cast if the vector constant is of the
13567 same type as the variable it is initializing.
13570 If @code{signed} or @code{unsigned} is omitted, the signedness of the
13571 vector type is the default signedness of the base type. The default
13572 varies depending on the operating system, so a portable program should
13573 always specify the signedness.
13576 Compiling with @option{-maltivec} adds keywords @code{__vector},
13577 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and
13578 @code{bool}. When compiling ISO C, the context-sensitive substitution
13579 of the keywords @code{vector}, @code{pixel} and @code{bool} is
13580 disabled. To use them, you must include @code{<altivec.h>} instead.
13583 GCC allows using a @code{typedef} name as the type specifier for a
13587 For C, overloaded functions are implemented with macros so the following
13591 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo);
13595 Since @code{vec_add} is a macro, the vector constant in the example
13596 is treated as four separate arguments. Wrap the entire argument in
13597 parentheses for this to work.
13600 @emph{Note:} Only the @code{<altivec.h>} interface is supported.
13601 Internally, GCC uses built-in functions to achieve the functionality in
13602 the aforementioned header file, but they are not supported and are
13603 subject to change without notice.
13605 The following interfaces are supported for the generic and specific
13606 AltiVec operations and the AltiVec predicates. In cases where there
13607 is a direct mapping between generic and specific operations, only the
13608 generic names are shown here, although the specific operations can also
13611 Arguments that are documented as @code{const int} require literal
13612 integral values within the range required for that operation.
13615 vector signed char vec_abs (vector signed char);
13616 vector signed short vec_abs (vector signed short);
13617 vector signed int vec_abs (vector signed int);
13618 vector float vec_abs (vector float);
13620 vector signed char vec_abss (vector signed char);
13621 vector signed short vec_abss (vector signed short);
13622 vector signed int vec_abss (vector signed int);
13624 vector signed char vec_add (vector bool char, vector signed char);
13625 vector signed char vec_add (vector signed char, vector bool char);
13626 vector signed char vec_add (vector signed char, vector signed char);
13627 vector unsigned char vec_add (vector bool char, vector unsigned char);
13628 vector unsigned char vec_add (vector unsigned char, vector bool char);
13629 vector unsigned char vec_add (vector unsigned char,
13630 vector unsigned char);
13631 vector signed short vec_add (vector bool short, vector signed short);
13632 vector signed short vec_add (vector signed short, vector bool short);
13633 vector signed short vec_add (vector signed short, vector signed short);
13634 vector unsigned short vec_add (vector bool short,
13635 vector unsigned short);
13636 vector unsigned short vec_add (vector unsigned short,
13637 vector bool short);
13638 vector unsigned short vec_add (vector unsigned short,
13639 vector unsigned short);
13640 vector signed int vec_add (vector bool int, vector signed int);
13641 vector signed int vec_add (vector signed int, vector bool int);
13642 vector signed int vec_add (vector signed int, vector signed int);
13643 vector unsigned int vec_add (vector bool int, vector unsigned int);
13644 vector unsigned int vec_add (vector unsigned int, vector bool int);
13645 vector unsigned int vec_add (vector unsigned int, vector unsigned int);
13646 vector float vec_add (vector float, vector float);
13648 vector float vec_vaddfp (vector float, vector float);
13650 vector signed int vec_vadduwm (vector bool int, vector signed int);
13651 vector signed int vec_vadduwm (vector signed int, vector bool int);
13652 vector signed int vec_vadduwm (vector signed int, vector signed int);
13653 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int);
13654 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int);
13655 vector unsigned int vec_vadduwm (vector unsigned int,
13656 vector unsigned int);
13658 vector signed short vec_vadduhm (vector bool short,
13659 vector signed short);
13660 vector signed short vec_vadduhm (vector signed short,
13661 vector bool short);
13662 vector signed short vec_vadduhm (vector signed short,
13663 vector signed short);
13664 vector unsigned short vec_vadduhm (vector bool short,
13665 vector unsigned short);
13666 vector unsigned short vec_vadduhm (vector unsigned short,
13667 vector bool short);
13668 vector unsigned short vec_vadduhm (vector unsigned short,
13669 vector unsigned short);
13671 vector signed char vec_vaddubm (vector bool char, vector signed char);
13672 vector signed char vec_vaddubm (vector signed char, vector bool char);
13673 vector signed char vec_vaddubm (vector signed char, vector signed char);
13674 vector unsigned char vec_vaddubm (vector bool char,
13675 vector unsigned char);
13676 vector unsigned char vec_vaddubm (vector unsigned char,
13678 vector unsigned char vec_vaddubm (vector unsigned char,
13679 vector unsigned char);
13681 vector unsigned int vec_addc (vector unsigned int, vector unsigned int);
13683 vector unsigned char vec_adds (vector bool char, vector unsigned char);
13684 vector unsigned char vec_adds (vector unsigned char, vector bool char);
13685 vector unsigned char vec_adds (vector unsigned char,
13686 vector unsigned char);
13687 vector signed char vec_adds (vector bool char, vector signed char);
13688 vector signed char vec_adds (vector signed char, vector bool char);
13689 vector signed char vec_adds (vector signed char, vector signed char);
13690 vector unsigned short vec_adds (vector bool short,
13691 vector unsigned short);
13692 vector unsigned short vec_adds (vector unsigned short,
13693 vector bool short);
13694 vector unsigned short vec_adds (vector unsigned short,
13695 vector unsigned short);
13696 vector signed short vec_adds (vector bool short, vector signed short);
13697 vector signed short vec_adds (vector signed short, vector bool short);
13698 vector signed short vec_adds (vector signed short, vector signed short);
13699 vector unsigned int vec_adds (vector bool int, vector unsigned int);
13700 vector unsigned int vec_adds (vector unsigned int, vector bool int);
13701 vector unsigned int vec_adds (vector unsigned int, vector unsigned int);
13702 vector signed int vec_adds (vector bool int, vector signed int);
13703 vector signed int vec_adds (vector signed int, vector bool int);
13704 vector signed int vec_adds (vector signed int, vector signed int);
13706 vector signed int vec_vaddsws (vector bool int, vector signed int);
13707 vector signed int vec_vaddsws (vector signed int, vector bool int);
13708 vector signed int vec_vaddsws (vector signed int, vector signed int);
13710 vector unsigned int vec_vadduws (vector bool int, vector unsigned int);
13711 vector unsigned int vec_vadduws (vector unsigned int, vector bool int);
13712 vector unsigned int vec_vadduws (vector unsigned int,
13713 vector unsigned int);
13715 vector signed short vec_vaddshs (vector bool short,
13716 vector signed short);
13717 vector signed short vec_vaddshs (vector signed short,
13718 vector bool short);
13719 vector signed short vec_vaddshs (vector signed short,
13720 vector signed short);
13722 vector unsigned short vec_vadduhs (vector bool short,
13723 vector unsigned short);
13724 vector unsigned short vec_vadduhs (vector unsigned short,
13725 vector bool short);
13726 vector unsigned short vec_vadduhs (vector unsigned short,
13727 vector unsigned short);
13729 vector signed char vec_vaddsbs (vector bool char, vector signed char);
13730 vector signed char vec_vaddsbs (vector signed char, vector bool char);
13731 vector signed char vec_vaddsbs (vector signed char, vector signed char);
13733 vector unsigned char vec_vaddubs (vector bool char,
13734 vector unsigned char);
13735 vector unsigned char vec_vaddubs (vector unsigned char,
13737 vector unsigned char vec_vaddubs (vector unsigned char,
13738 vector unsigned char);
13740 vector float vec_and (vector float, vector float);
13741 vector float vec_and (vector float, vector bool int);
13742 vector float vec_and (vector bool int, vector float);
13743 vector bool int vec_and (vector bool int, vector bool int);
13744 vector signed int vec_and (vector bool int, vector signed int);
13745 vector signed int vec_and (vector signed int, vector bool int);
13746 vector signed int vec_and (vector signed int, vector signed int);
13747 vector unsigned int vec_and (vector bool int, vector unsigned int);
13748 vector unsigned int vec_and (vector unsigned int, vector bool int);
13749 vector unsigned int vec_and (vector unsigned int, vector unsigned int);
13750 vector bool short vec_and (vector bool short, vector bool short);
13751 vector signed short vec_and (vector bool short, vector signed short);
13752 vector signed short vec_and (vector signed short, vector bool short);
13753 vector signed short vec_and (vector signed short, vector signed short);
13754 vector unsigned short vec_and (vector bool short,
13755 vector unsigned short);
13756 vector unsigned short vec_and (vector unsigned short,
13757 vector bool short);
13758 vector unsigned short vec_and (vector unsigned short,
13759 vector unsigned short);
13760 vector signed char vec_and (vector bool char, vector signed char);
13761 vector bool char vec_and (vector bool char, vector bool char);
13762 vector signed char vec_and (vector signed char, vector bool char);
13763 vector signed char vec_and (vector signed char, vector signed char);
13764 vector unsigned char vec_and (vector bool char, vector unsigned char);
13765 vector unsigned char vec_and (vector unsigned char, vector bool char);
13766 vector unsigned char vec_and (vector unsigned char,
13767 vector unsigned char);
13769 vector float vec_andc (vector float, vector float);
13770 vector float vec_andc (vector float, vector bool int);
13771 vector float vec_andc (vector bool int, vector float);
13772 vector bool int vec_andc (vector bool int, vector bool int);
13773 vector signed int vec_andc (vector bool int, vector signed int);
13774 vector signed int vec_andc (vector signed int, vector bool int);
13775 vector signed int vec_andc (vector signed int, vector signed int);
13776 vector unsigned int vec_andc (vector bool int, vector unsigned int);
13777 vector unsigned int vec_andc (vector unsigned int, vector bool int);
13778 vector unsigned int vec_andc (vector unsigned int, vector unsigned int);
13779 vector bool short vec_andc (vector bool short, vector bool short);
13780 vector signed short vec_andc (vector bool short, vector signed short);
13781 vector signed short vec_andc (vector signed short, vector bool short);
13782 vector signed short vec_andc (vector signed short, vector signed short);
13783 vector unsigned short vec_andc (vector bool short,
13784 vector unsigned short);
13785 vector unsigned short vec_andc (vector unsigned short,
13786 vector bool short);
13787 vector unsigned short vec_andc (vector unsigned short,
13788 vector unsigned short);
13789 vector signed char vec_andc (vector bool char, vector signed char);
13790 vector bool char vec_andc (vector bool char, vector bool char);
13791 vector signed char vec_andc (vector signed char, vector bool char);
13792 vector signed char vec_andc (vector signed char, vector signed char);
13793 vector unsigned char vec_andc (vector bool char, vector unsigned char);
13794 vector unsigned char vec_andc (vector unsigned char, vector bool char);
13795 vector unsigned char vec_andc (vector unsigned char,
13796 vector unsigned char);
13798 vector unsigned char vec_avg (vector unsigned char,
13799 vector unsigned char);
13800 vector signed char vec_avg (vector signed char, vector signed char);
13801 vector unsigned short vec_avg (vector unsigned short,
13802 vector unsigned short);
13803 vector signed short vec_avg (vector signed short, vector signed short);
13804 vector unsigned int vec_avg (vector unsigned int, vector unsigned int);
13805 vector signed int vec_avg (vector signed int, vector signed int);
13807 vector signed int vec_vavgsw (vector signed int, vector signed int);
13809 vector unsigned int vec_vavguw (vector unsigned int,
13810 vector unsigned int);
13812 vector signed short vec_vavgsh (vector signed short,
13813 vector signed short);
13815 vector unsigned short vec_vavguh (vector unsigned short,
13816 vector unsigned short);
13818 vector signed char vec_vavgsb (vector signed char, vector signed char);
13820 vector unsigned char vec_vavgub (vector unsigned char,
13821 vector unsigned char);
13823 vector float vec_copysign (vector float);
13825 vector float vec_ceil (vector float);
13827 vector signed int vec_cmpb (vector float, vector float);
13829 vector bool char vec_cmpeq (vector signed char, vector signed char);
13830 vector bool char vec_cmpeq (vector unsigned char, vector unsigned char);
13831 vector bool short vec_cmpeq (vector signed short, vector signed short);
13832 vector bool short vec_cmpeq (vector unsigned short,
13833 vector unsigned short);
13834 vector bool int vec_cmpeq (vector signed int, vector signed int);
13835 vector bool int vec_cmpeq (vector unsigned int, vector unsigned int);
13836 vector bool int vec_cmpeq (vector float, vector float);
13838 vector bool int vec_vcmpeqfp (vector float, vector float);
13840 vector bool int vec_vcmpequw (vector signed int, vector signed int);
13841 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int);
13843 vector bool short vec_vcmpequh (vector signed short,
13844 vector signed short);
13845 vector bool short vec_vcmpequh (vector unsigned short,
13846 vector unsigned short);
13848 vector bool char vec_vcmpequb (vector signed char, vector signed char);
13849 vector bool char vec_vcmpequb (vector unsigned char,
13850 vector unsigned char);
13852 vector bool int vec_cmpge (vector float, vector float);
13854 vector bool char vec_cmpgt (vector unsigned char, vector unsigned char);
13855 vector bool char vec_cmpgt (vector signed char, vector signed char);
13856 vector bool short vec_cmpgt (vector unsigned short,
13857 vector unsigned short);
13858 vector bool short vec_cmpgt (vector signed short, vector signed short);
13859 vector bool int vec_cmpgt (vector unsigned int, vector unsigned int);
13860 vector bool int vec_cmpgt (vector signed int, vector signed int);
13861 vector bool int vec_cmpgt (vector float, vector float);
13863 vector bool int vec_vcmpgtfp (vector float, vector float);
13865 vector bool int vec_vcmpgtsw (vector signed int, vector signed int);
13867 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int);
13869 vector bool short vec_vcmpgtsh (vector signed short,
13870 vector signed short);
13872 vector bool short vec_vcmpgtuh (vector unsigned short,
13873 vector unsigned short);
13875 vector bool char vec_vcmpgtsb (vector signed char, vector signed char);
13877 vector bool char vec_vcmpgtub (vector unsigned char,
13878 vector unsigned char);
13880 vector bool int vec_cmple (vector float, vector float);
13882 vector bool char vec_cmplt (vector unsigned char, vector unsigned char);
13883 vector bool char vec_cmplt (vector signed char, vector signed char);
13884 vector bool short vec_cmplt (vector unsigned short,
13885 vector unsigned short);
13886 vector bool short vec_cmplt (vector signed short, vector signed short);
13887 vector bool int vec_cmplt (vector unsigned int, vector unsigned int);
13888 vector bool int vec_cmplt (vector signed int, vector signed int);
13889 vector bool int vec_cmplt (vector float, vector float);
13891 vector float vec_cpsgn (vector float, vector float);
13893 vector float vec_ctf (vector unsigned int, const int);
13894 vector float vec_ctf (vector signed int, const int);
13895 vector double vec_ctf (vector unsigned long, const int);
13896 vector double vec_ctf (vector signed long, const int);
13898 vector float vec_vcfsx (vector signed int, const int);
13900 vector float vec_vcfux (vector unsigned int, const int);
13902 vector signed int vec_cts (vector float, const int);
13903 vector signed long vec_cts (vector double, const int);
13905 vector unsigned int vec_ctu (vector float, const int);
13906 vector unsigned long vec_ctu (vector double, const int);
13908 void vec_dss (const int);
13910 void vec_dssall (void);
13912 void vec_dst (const vector unsigned char *, int, const int);
13913 void vec_dst (const vector signed char *, int, const int);
13914 void vec_dst (const vector bool char *, int, const int);
13915 void vec_dst (const vector unsigned short *, int, const int);
13916 void vec_dst (const vector signed short *, int, const int);
13917 void vec_dst (const vector bool short *, int, const int);
13918 void vec_dst (const vector pixel *, int, const int);
13919 void vec_dst (const vector unsigned int *, int, const int);
13920 void vec_dst (const vector signed int *, int, const int);
13921 void vec_dst (const vector bool int *, int, const int);
13922 void vec_dst (const vector float *, int, const int);
13923 void vec_dst (const unsigned char *, int, const int);
13924 void vec_dst (const signed char *, int, const int);
13925 void vec_dst (const unsigned short *, int, const int);
13926 void vec_dst (const short *, int, const int);
13927 void vec_dst (const unsigned int *, int, const int);
13928 void vec_dst (const int *, int, const int);
13929 void vec_dst (const unsigned long *, int, const int);
13930 void vec_dst (const long *, int, const int);
13931 void vec_dst (const float *, int, const int);
13933 void vec_dstst (const vector unsigned char *, int, const int);
13934 void vec_dstst (const vector signed char *, int, const int);
13935 void vec_dstst (const vector bool char *, int, const int);
13936 void vec_dstst (const vector unsigned short *, int, const int);
13937 void vec_dstst (const vector signed short *, int, const int);
13938 void vec_dstst (const vector bool short *, int, const int);
13939 void vec_dstst (const vector pixel *, int, const int);
13940 void vec_dstst (const vector unsigned int *, int, const int);
13941 void vec_dstst (const vector signed int *, int, const int);
13942 void vec_dstst (const vector bool int *, int, const int);
13943 void vec_dstst (const vector float *, int, const int);
13944 void vec_dstst (const unsigned char *, int, const int);
13945 void vec_dstst (const signed char *, int, const int);
13946 void vec_dstst (const unsigned short *, int, const int);
13947 void vec_dstst (const short *, int, const int);
13948 void vec_dstst (const unsigned int *, int, const int);
13949 void vec_dstst (const int *, int, const int);
13950 void vec_dstst (const unsigned long *, int, const int);
13951 void vec_dstst (const long *, int, const int);
13952 void vec_dstst (const float *, int, const int);
13954 void vec_dststt (const vector unsigned char *, int, const int);
13955 void vec_dststt (const vector signed char *, int, const int);
13956 void vec_dststt (const vector bool char *, int, const int);
13957 void vec_dststt (const vector unsigned short *, int, const int);
13958 void vec_dststt (const vector signed short *, int, const int);
13959 void vec_dststt (const vector bool short *, int, const int);
13960 void vec_dststt (const vector pixel *, int, const int);
13961 void vec_dststt (const vector unsigned int *, int, const int);
13962 void vec_dststt (const vector signed int *, int, const int);
13963 void vec_dststt (const vector bool int *, int, const int);
13964 void vec_dststt (const vector float *, int, const int);
13965 void vec_dststt (const unsigned char *, int, const int);
13966 void vec_dststt (const signed char *, int, const int);
13967 void vec_dststt (const unsigned short *, int, const int);
13968 void vec_dststt (const short *, int, const int);
13969 void vec_dststt (const unsigned int *, int, const int);
13970 void vec_dststt (const int *, int, const int);
13971 void vec_dststt (const unsigned long *, int, const int);
13972 void vec_dststt (const long *, int, const int);
13973 void vec_dststt (const float *, int, const int);
13975 void vec_dstt (const vector unsigned char *, int, const int);
13976 void vec_dstt (const vector signed char *, int, const int);
13977 void vec_dstt (const vector bool char *, int, const int);
13978 void vec_dstt (const vector unsigned short *, int, const int);
13979 void vec_dstt (const vector signed short *, int, const int);
13980 void vec_dstt (const vector bool short *, int, const int);
13981 void vec_dstt (const vector pixel *, int, const int);
13982 void vec_dstt (const vector unsigned int *, int, const int);
13983 void vec_dstt (const vector signed int *, int, const int);
13984 void vec_dstt (const vector bool int *, int, const int);
13985 void vec_dstt (const vector float *, int, const int);
13986 void vec_dstt (const unsigned char *, int, const int);
13987 void vec_dstt (const signed char *, int, const int);
13988 void vec_dstt (const unsigned short *, int, const int);
13989 void vec_dstt (const short *, int, const int);
13990 void vec_dstt (const unsigned int *, int, const int);
13991 void vec_dstt (const int *, int, const int);
13992 void vec_dstt (const unsigned long *, int, const int);
13993 void vec_dstt (const long *, int, const int);
13994 void vec_dstt (const float *, int, const int);
13996 vector float vec_expte (vector float);
13998 vector float vec_floor (vector float);
14000 vector float vec_ld (int, const vector float *);
14001 vector float vec_ld (int, const float *);
14002 vector bool int vec_ld (int, const vector bool int *);
14003 vector signed int vec_ld (int, const vector signed int *);
14004 vector signed int vec_ld (int, const int *);
14005 vector signed int vec_ld (int, const long *);
14006 vector unsigned int vec_ld (int, const vector unsigned int *);
14007 vector unsigned int vec_ld (int, const unsigned int *);
14008 vector unsigned int vec_ld (int, const unsigned long *);
14009 vector bool short vec_ld (int, const vector bool short *);
14010 vector pixel vec_ld (int, const vector pixel *);
14011 vector signed short vec_ld (int, const vector signed short *);
14012 vector signed short vec_ld (int, const short *);
14013 vector unsigned short vec_ld (int, const vector unsigned short *);
14014 vector unsigned short vec_ld (int, const unsigned short *);
14015 vector bool char vec_ld (int, const vector bool char *);
14016 vector signed char vec_ld (int, const vector signed char *);
14017 vector signed char vec_ld (int, const signed char *);
14018 vector unsigned char vec_ld (int, const vector unsigned char *);
14019 vector unsigned char vec_ld (int, const unsigned char *);
14021 vector signed char vec_lde (int, const signed char *);
14022 vector unsigned char vec_lde (int, const unsigned char *);
14023 vector signed short vec_lde (int, const short *);
14024 vector unsigned short vec_lde (int, const unsigned short *);
14025 vector float vec_lde (int, const float *);
14026 vector signed int vec_lde (int, const int *);
14027 vector unsigned int vec_lde (int, const unsigned int *);
14028 vector signed int vec_lde (int, const long *);
14029 vector unsigned int vec_lde (int, const unsigned long *);
14031 vector float vec_lvewx (int, float *);
14032 vector signed int vec_lvewx (int, int *);
14033 vector unsigned int vec_lvewx (int, unsigned int *);
14034 vector signed int vec_lvewx (int, long *);
14035 vector unsigned int vec_lvewx (int, unsigned long *);
14037 vector signed short vec_lvehx (int, short *);
14038 vector unsigned short vec_lvehx (int, unsigned short *);
14040 vector signed char vec_lvebx (int, char *);
14041 vector unsigned char vec_lvebx (int, unsigned char *);
14043 vector float vec_ldl (int, const vector float *);
14044 vector float vec_ldl (int, const float *);
14045 vector bool int vec_ldl (int, const vector bool int *);
14046 vector signed int vec_ldl (int, const vector signed int *);
14047 vector signed int vec_ldl (int, const int *);
14048 vector signed int vec_ldl (int, const long *);
14049 vector unsigned int vec_ldl (int, const vector unsigned int *);
14050 vector unsigned int vec_ldl (int, const unsigned int *);
14051 vector unsigned int vec_ldl (int, const unsigned long *);
14052 vector bool short vec_ldl (int, const vector bool short *);
14053 vector pixel vec_ldl (int, const vector pixel *);
14054 vector signed short vec_ldl (int, const vector signed short *);
14055 vector signed short vec_ldl (int, const short *);
14056 vector unsigned short vec_ldl (int, const vector unsigned short *);
14057 vector unsigned short vec_ldl (int, const unsigned short *);
14058 vector bool char vec_ldl (int, const vector bool char *);
14059 vector signed char vec_ldl (int, const vector signed char *);
14060 vector signed char vec_ldl (int, const signed char *);
14061 vector unsigned char vec_ldl (int, const vector unsigned char *);
14062 vector unsigned char vec_ldl (int, const unsigned char *);
14064 vector float vec_loge (vector float);
14066 vector unsigned char vec_lvsl (int, const volatile unsigned char *);
14067 vector unsigned char vec_lvsl (int, const volatile signed char *);
14068 vector unsigned char vec_lvsl (int, const volatile unsigned short *);
14069 vector unsigned char vec_lvsl (int, const volatile short *);
14070 vector unsigned char vec_lvsl (int, const volatile unsigned int *);
14071 vector unsigned char vec_lvsl (int, const volatile int *);
14072 vector unsigned char vec_lvsl (int, const volatile unsigned long *);
14073 vector unsigned char vec_lvsl (int, const volatile long *);
14074 vector unsigned char vec_lvsl (int, const volatile float *);
14076 vector unsigned char vec_lvsr (int, const volatile unsigned char *);
14077 vector unsigned char vec_lvsr (int, const volatile signed char *);
14078 vector unsigned char vec_lvsr (int, const volatile unsigned short *);
14079 vector unsigned char vec_lvsr (int, const volatile short *);
14080 vector unsigned char vec_lvsr (int, const volatile unsigned int *);
14081 vector unsigned char vec_lvsr (int, const volatile int *);
14082 vector unsigned char vec_lvsr (int, const volatile unsigned long *);
14083 vector unsigned char vec_lvsr (int, const volatile long *);
14084 vector unsigned char vec_lvsr (int, const volatile float *);
14086 vector float vec_madd (vector float, vector float, vector float);
14088 vector signed short vec_madds (vector signed short,
14089 vector signed short,
14090 vector signed short);
14092 vector unsigned char vec_max (vector bool char, vector unsigned char);
14093 vector unsigned char vec_max (vector unsigned char, vector bool char);
14094 vector unsigned char vec_max (vector unsigned char,
14095 vector unsigned char);
14096 vector signed char vec_max (vector bool char, vector signed char);
14097 vector signed char vec_max (vector signed char, vector bool char);
14098 vector signed char vec_max (vector signed char, vector signed char);
14099 vector unsigned short vec_max (vector bool short,
14100 vector unsigned short);
14101 vector unsigned short vec_max (vector unsigned short,
14102 vector bool short);
14103 vector unsigned short vec_max (vector unsigned short,
14104 vector unsigned short);
14105 vector signed short vec_max (vector bool short, vector signed short);
14106 vector signed short vec_max (vector signed short, vector bool short);
14107 vector signed short vec_max (vector signed short, vector signed short);
14108 vector unsigned int vec_max (vector bool int, vector unsigned int);
14109 vector unsigned int vec_max (vector unsigned int, vector bool int);
14110 vector unsigned int vec_max (vector unsigned int, vector unsigned int);
14111 vector signed int vec_max (vector bool int, vector signed int);
14112 vector signed int vec_max (vector signed int, vector bool int);
14113 vector signed int vec_max (vector signed int, vector signed int);
14114 vector float vec_max (vector float, vector float);
14116 vector float vec_vmaxfp (vector float, vector float);
14118 vector signed int vec_vmaxsw (vector bool int, vector signed int);
14119 vector signed int vec_vmaxsw (vector signed int, vector bool int);
14120 vector signed int vec_vmaxsw (vector signed int, vector signed int);
14122 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int);
14123 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int);
14124 vector unsigned int vec_vmaxuw (vector unsigned int,
14125 vector unsigned int);
14127 vector signed short vec_vmaxsh (vector bool short, vector signed short);
14128 vector signed short vec_vmaxsh (vector signed short, vector bool short);
14129 vector signed short vec_vmaxsh (vector signed short,
14130 vector signed short);
14132 vector unsigned short vec_vmaxuh (vector bool short,
14133 vector unsigned short);
14134 vector unsigned short vec_vmaxuh (vector unsigned short,
14135 vector bool short);
14136 vector unsigned short vec_vmaxuh (vector unsigned short,
14137 vector unsigned short);
14139 vector signed char vec_vmaxsb (vector bool char, vector signed char);
14140 vector signed char vec_vmaxsb (vector signed char, vector bool char);
14141 vector signed char vec_vmaxsb (vector signed char, vector signed char);
14143 vector unsigned char vec_vmaxub (vector bool char,
14144 vector unsigned char);
14145 vector unsigned char vec_vmaxub (vector unsigned char,
14147 vector unsigned char vec_vmaxub (vector unsigned char,
14148 vector unsigned char);
14150 vector bool char vec_mergeh (vector bool char, vector bool char);
14151 vector signed char vec_mergeh (vector signed char, vector signed char);
14152 vector unsigned char vec_mergeh (vector unsigned char,
14153 vector unsigned char);
14154 vector bool short vec_mergeh (vector bool short, vector bool short);
14155 vector pixel vec_mergeh (vector pixel, vector pixel);
14156 vector signed short vec_mergeh (vector signed short,
14157 vector signed short);
14158 vector unsigned short vec_mergeh (vector unsigned short,
14159 vector unsigned short);
14160 vector float vec_mergeh (vector float, vector float);
14161 vector bool int vec_mergeh (vector bool int, vector bool int);
14162 vector signed int vec_mergeh (vector signed int, vector signed int);
14163 vector unsigned int vec_mergeh (vector unsigned int,
14164 vector unsigned int);
14166 vector float vec_vmrghw (vector float, vector float);
14167 vector bool int vec_vmrghw (vector bool int, vector bool int);
14168 vector signed int vec_vmrghw (vector signed int, vector signed int);
14169 vector unsigned int vec_vmrghw (vector unsigned int,
14170 vector unsigned int);
14172 vector bool short vec_vmrghh (vector bool short, vector bool short);
14173 vector signed short vec_vmrghh (vector signed short,
14174 vector signed short);
14175 vector unsigned short vec_vmrghh (vector unsigned short,
14176 vector unsigned short);
14177 vector pixel vec_vmrghh (vector pixel, vector pixel);
14179 vector bool char vec_vmrghb (vector bool char, vector bool char);
14180 vector signed char vec_vmrghb (vector signed char, vector signed char);
14181 vector unsigned char vec_vmrghb (vector unsigned char,
14182 vector unsigned char);
14184 vector bool char vec_mergel (vector bool char, vector bool char);
14185 vector signed char vec_mergel (vector signed char, vector signed char);
14186 vector unsigned char vec_mergel (vector unsigned char,
14187 vector unsigned char);
14188 vector bool short vec_mergel (vector bool short, vector bool short);
14189 vector pixel vec_mergel (vector pixel, vector pixel);
14190 vector signed short vec_mergel (vector signed short,
14191 vector signed short);
14192 vector unsigned short vec_mergel (vector unsigned short,
14193 vector unsigned short);
14194 vector float vec_mergel (vector float, vector float);
14195 vector bool int vec_mergel (vector bool int, vector bool int);
14196 vector signed int vec_mergel (vector signed int, vector signed int);
14197 vector unsigned int vec_mergel (vector unsigned int,
14198 vector unsigned int);
14200 vector float vec_vmrglw (vector float, vector float);
14201 vector signed int vec_vmrglw (vector signed int, vector signed int);
14202 vector unsigned int vec_vmrglw (vector unsigned int,
14203 vector unsigned int);
14204 vector bool int vec_vmrglw (vector bool int, vector bool int);
14206 vector bool short vec_vmrglh (vector bool short, vector bool short);
14207 vector signed short vec_vmrglh (vector signed short,
14208 vector signed short);
14209 vector unsigned short vec_vmrglh (vector unsigned short,
14210 vector unsigned short);
14211 vector pixel vec_vmrglh (vector pixel, vector pixel);
14213 vector bool char vec_vmrglb (vector bool char, vector bool char);
14214 vector signed char vec_vmrglb (vector signed char, vector signed char);
14215 vector unsigned char vec_vmrglb (vector unsigned char,
14216 vector unsigned char);
14218 vector unsigned short vec_mfvscr (void);
14220 vector unsigned char vec_min (vector bool char, vector unsigned char);
14221 vector unsigned char vec_min (vector unsigned char, vector bool char);
14222 vector unsigned char vec_min (vector unsigned char,
14223 vector unsigned char);
14224 vector signed char vec_min (vector bool char, vector signed char);
14225 vector signed char vec_min (vector signed char, vector bool char);
14226 vector signed char vec_min (vector signed char, vector signed char);
14227 vector unsigned short vec_min (vector bool short,
14228 vector unsigned short);
14229 vector unsigned short vec_min (vector unsigned short,
14230 vector bool short);
14231 vector unsigned short vec_min (vector unsigned short,
14232 vector unsigned short);
14233 vector signed short vec_min (vector bool short, vector signed short);
14234 vector signed short vec_min (vector signed short, vector bool short);
14235 vector signed short vec_min (vector signed short, vector signed short);
14236 vector unsigned int vec_min (vector bool int, vector unsigned int);
14237 vector unsigned int vec_min (vector unsigned int, vector bool int);
14238 vector unsigned int vec_min (vector unsigned int, vector unsigned int);
14239 vector signed int vec_min (vector bool int, vector signed int);
14240 vector signed int vec_min (vector signed int, vector bool int);
14241 vector signed int vec_min (vector signed int, vector signed int);
14242 vector float vec_min (vector float, vector float);
14244 vector float vec_vminfp (vector float, vector float);
14246 vector signed int vec_vminsw (vector bool int, vector signed int);
14247 vector signed int vec_vminsw (vector signed int, vector bool int);
14248 vector signed int vec_vminsw (vector signed int, vector signed int);
14250 vector unsigned int vec_vminuw (vector bool int, vector unsigned int);
14251 vector unsigned int vec_vminuw (vector unsigned int, vector bool int);
14252 vector unsigned int vec_vminuw (vector unsigned int,
14253 vector unsigned int);
14255 vector signed short vec_vminsh (vector bool short, vector signed short);
14256 vector signed short vec_vminsh (vector signed short, vector bool short);
14257 vector signed short vec_vminsh (vector signed short,
14258 vector signed short);
14260 vector unsigned short vec_vminuh (vector bool short,
14261 vector unsigned short);
14262 vector unsigned short vec_vminuh (vector unsigned short,
14263 vector bool short);
14264 vector unsigned short vec_vminuh (vector unsigned short,
14265 vector unsigned short);
14267 vector signed char vec_vminsb (vector bool char, vector signed char);
14268 vector signed char vec_vminsb (vector signed char, vector bool char);
14269 vector signed char vec_vminsb (vector signed char, vector signed char);
14271 vector unsigned char vec_vminub (vector bool char,
14272 vector unsigned char);
14273 vector unsigned char vec_vminub (vector unsigned char,
14275 vector unsigned char vec_vminub (vector unsigned char,
14276 vector unsigned char);
14278 vector signed short vec_mladd (vector signed short,
14279 vector signed short,
14280 vector signed short);
14281 vector signed short vec_mladd (vector signed short,
14282 vector unsigned short,
14283 vector unsigned short);
14284 vector signed short vec_mladd (vector unsigned short,
14285 vector signed short,
14286 vector signed short);
14287 vector unsigned short vec_mladd (vector unsigned short,
14288 vector unsigned short,
14289 vector unsigned short);
14291 vector signed short vec_mradds (vector signed short,
14292 vector signed short,
14293 vector signed short);
14295 vector unsigned int vec_msum (vector unsigned char,
14296 vector unsigned char,
14297 vector unsigned int);
14298 vector signed int vec_msum (vector signed char,
14299 vector unsigned char,
14300 vector signed int);
14301 vector unsigned int vec_msum (vector unsigned short,
14302 vector unsigned short,
14303 vector unsigned int);
14304 vector signed int vec_msum (vector signed short,
14305 vector signed short,
14306 vector signed int);
14308 vector signed int vec_vmsumshm (vector signed short,
14309 vector signed short,
14310 vector signed int);
14312 vector unsigned int vec_vmsumuhm (vector unsigned short,
14313 vector unsigned short,
14314 vector unsigned int);
14316 vector signed int vec_vmsummbm (vector signed char,
14317 vector unsigned char,
14318 vector signed int);
14320 vector unsigned int vec_vmsumubm (vector unsigned char,
14321 vector unsigned char,
14322 vector unsigned int);
14324 vector unsigned int vec_msums (vector unsigned short,
14325 vector unsigned short,
14326 vector unsigned int);
14327 vector signed int vec_msums (vector signed short,
14328 vector signed short,
14329 vector signed int);
14331 vector signed int vec_vmsumshs (vector signed short,
14332 vector signed short,
14333 vector signed int);
14335 vector unsigned int vec_vmsumuhs (vector unsigned short,
14336 vector unsigned short,
14337 vector unsigned int);
14339 void vec_mtvscr (vector signed int);
14340 void vec_mtvscr (vector unsigned int);
14341 void vec_mtvscr (vector bool int);
14342 void vec_mtvscr (vector signed short);
14343 void vec_mtvscr (vector unsigned short);
14344 void vec_mtvscr (vector bool short);
14345 void vec_mtvscr (vector pixel);
14346 void vec_mtvscr (vector signed char);
14347 void vec_mtvscr (vector unsigned char);
14348 void vec_mtvscr (vector bool char);
14350 vector unsigned short vec_mule (vector unsigned char,
14351 vector unsigned char);
14352 vector signed short vec_mule (vector signed char,
14353 vector signed char);
14354 vector unsigned int vec_mule (vector unsigned short,
14355 vector unsigned short);
14356 vector signed int vec_mule (vector signed short, vector signed short);
14358 vector signed int vec_vmulesh (vector signed short,
14359 vector signed short);
14361 vector unsigned int vec_vmuleuh (vector unsigned short,
14362 vector unsigned short);
14364 vector signed short vec_vmulesb (vector signed char,
14365 vector signed char);
14367 vector unsigned short vec_vmuleub (vector unsigned char,
14368 vector unsigned char);
14370 vector unsigned short vec_mulo (vector unsigned char,
14371 vector unsigned char);
14372 vector signed short vec_mulo (vector signed char, vector signed char);
14373 vector unsigned int vec_mulo (vector unsigned short,
14374 vector unsigned short);
14375 vector signed int vec_mulo (vector signed short, vector signed short);
14377 vector signed int vec_vmulosh (vector signed short,
14378 vector signed short);
14380 vector unsigned int vec_vmulouh (vector unsigned short,
14381 vector unsigned short);
14383 vector signed short vec_vmulosb (vector signed char,
14384 vector signed char);
14386 vector unsigned short vec_vmuloub (vector unsigned char,
14387 vector unsigned char);
14389 vector float vec_nmsub (vector float, vector float, vector float);
14391 vector float vec_nor (vector float, vector float);
14392 vector signed int vec_nor (vector signed int, vector signed int);
14393 vector unsigned int vec_nor (vector unsigned int, vector unsigned int);
14394 vector bool int vec_nor (vector bool int, vector bool int);
14395 vector signed short vec_nor (vector signed short, vector signed short);
14396 vector unsigned short vec_nor (vector unsigned short,
14397 vector unsigned short);
14398 vector bool short vec_nor (vector bool short, vector bool short);
14399 vector signed char vec_nor (vector signed char, vector signed char);
14400 vector unsigned char vec_nor (vector unsigned char,
14401 vector unsigned char);
14402 vector bool char vec_nor (vector bool char, vector bool char);
14404 vector float vec_or (vector float, vector float);
14405 vector float vec_or (vector float, vector bool int);
14406 vector float vec_or (vector bool int, vector float);
14407 vector bool int vec_or (vector bool int, vector bool int);
14408 vector signed int vec_or (vector bool int, vector signed int);
14409 vector signed int vec_or (vector signed int, vector bool int);
14410 vector signed int vec_or (vector signed int, vector signed int);
14411 vector unsigned int vec_or (vector bool int, vector unsigned int);
14412 vector unsigned int vec_or (vector unsigned int, vector bool int);
14413 vector unsigned int vec_or (vector unsigned int, vector unsigned int);
14414 vector bool short vec_or (vector bool short, vector bool short);
14415 vector signed short vec_or (vector bool short, vector signed short);
14416 vector signed short vec_or (vector signed short, vector bool short);
14417 vector signed short vec_or (vector signed short, vector signed short);
14418 vector unsigned short vec_or (vector bool short, vector unsigned short);
14419 vector unsigned short vec_or (vector unsigned short, vector bool short);
14420 vector unsigned short vec_or (vector unsigned short,
14421 vector unsigned short);
14422 vector signed char vec_or (vector bool char, vector signed char);
14423 vector bool char vec_or (vector bool char, vector bool char);
14424 vector signed char vec_or (vector signed char, vector bool char);
14425 vector signed char vec_or (vector signed char, vector signed char);
14426 vector unsigned char vec_or (vector bool char, vector unsigned char);
14427 vector unsigned char vec_or (vector unsigned char, vector bool char);
14428 vector unsigned char vec_or (vector unsigned char,
14429 vector unsigned char);
14431 vector signed char vec_pack (vector signed short, vector signed short);
14432 vector unsigned char vec_pack (vector unsigned short,
14433 vector unsigned short);
14434 vector bool char vec_pack (vector bool short, vector bool short);
14435 vector signed short vec_pack (vector signed int, vector signed int);
14436 vector unsigned short vec_pack (vector unsigned int,
14437 vector unsigned int);
14438 vector bool short vec_pack (vector bool int, vector bool int);
14440 vector bool short vec_vpkuwum (vector bool int, vector bool int);
14441 vector signed short vec_vpkuwum (vector signed int, vector signed int);
14442 vector unsigned short vec_vpkuwum (vector unsigned int,
14443 vector unsigned int);
14445 vector bool char vec_vpkuhum (vector bool short, vector bool short);
14446 vector signed char vec_vpkuhum (vector signed short,
14447 vector signed short);
14448 vector unsigned char vec_vpkuhum (vector unsigned short,
14449 vector unsigned short);
14451 vector pixel vec_packpx (vector unsigned int, vector unsigned int);
14453 vector unsigned char vec_packs (vector unsigned short,
14454 vector unsigned short);
14455 vector signed char vec_packs (vector signed short, vector signed short);
14456 vector unsigned short vec_packs (vector unsigned int,
14457 vector unsigned int);
14458 vector signed short vec_packs (vector signed int, vector signed int);
14460 vector signed short vec_vpkswss (vector signed int, vector signed int);
14462 vector unsigned short vec_vpkuwus (vector unsigned int,
14463 vector unsigned int);
14465 vector signed char vec_vpkshss (vector signed short,
14466 vector signed short);
14468 vector unsigned char vec_vpkuhus (vector unsigned short,
14469 vector unsigned short);
14471 vector unsigned char vec_packsu (vector unsigned short,
14472 vector unsigned short);
14473 vector unsigned char vec_packsu (vector signed short,
14474 vector signed short);
14475 vector unsigned short vec_packsu (vector unsigned int,
14476 vector unsigned int);
14477 vector unsigned short vec_packsu (vector signed int, vector signed int);
14479 vector unsigned short vec_vpkswus (vector signed int,
14480 vector signed int);
14482 vector unsigned char vec_vpkshus (vector signed short,
14483 vector signed short);
14485 vector float vec_perm (vector float,
14487 vector unsigned char);
14488 vector signed int vec_perm (vector signed int,
14490 vector unsigned char);
14491 vector unsigned int vec_perm (vector unsigned int,
14492 vector unsigned int,
14493 vector unsigned char);
14494 vector bool int vec_perm (vector bool int,
14496 vector unsigned char);
14497 vector signed short vec_perm (vector signed short,
14498 vector signed short,
14499 vector unsigned char);
14500 vector unsigned short vec_perm (vector unsigned short,
14501 vector unsigned short,
14502 vector unsigned char);
14503 vector bool short vec_perm (vector bool short,
14505 vector unsigned char);
14506 vector pixel vec_perm (vector pixel,
14508 vector unsigned char);
14509 vector signed char vec_perm (vector signed char,
14510 vector signed char,
14511 vector unsigned char);
14512 vector unsigned char vec_perm (vector unsigned char,
14513 vector unsigned char,
14514 vector unsigned char);
14515 vector bool char vec_perm (vector bool char,
14517 vector unsigned char);
14519 vector float vec_re (vector float);
14521 vector signed char vec_rl (vector signed char,
14522 vector unsigned char);
14523 vector unsigned char vec_rl (vector unsigned char,
14524 vector unsigned char);
14525 vector signed short vec_rl (vector signed short, vector unsigned short);
14526 vector unsigned short vec_rl (vector unsigned short,
14527 vector unsigned short);
14528 vector signed int vec_rl (vector signed int, vector unsigned int);
14529 vector unsigned int vec_rl (vector unsigned int, vector unsigned int);
14531 vector signed int vec_vrlw (vector signed int, vector unsigned int);
14532 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int);
14534 vector signed short vec_vrlh (vector signed short,
14535 vector unsigned short);
14536 vector unsigned short vec_vrlh (vector unsigned short,
14537 vector unsigned short);
14539 vector signed char vec_vrlb (vector signed char, vector unsigned char);
14540 vector unsigned char vec_vrlb (vector unsigned char,
14541 vector unsigned char);
14543 vector float vec_round (vector float);
14545 vector float vec_recip (vector float, vector float);
14547 vector float vec_rsqrt (vector float);
14549 vector float vec_rsqrte (vector float);
14551 vector float vec_sel (vector float, vector float, vector bool int);
14552 vector float vec_sel (vector float, vector float, vector unsigned int);
14553 vector signed int vec_sel (vector signed int,
14556 vector signed int vec_sel (vector signed int,
14558 vector unsigned int);
14559 vector unsigned int vec_sel (vector unsigned int,
14560 vector unsigned int,
14562 vector unsigned int vec_sel (vector unsigned int,
14563 vector unsigned int,
14564 vector unsigned int);
14565 vector bool int vec_sel (vector bool int,
14568 vector bool int vec_sel (vector bool int,
14570 vector unsigned int);
14571 vector signed short vec_sel (vector signed short,
14572 vector signed short,
14573 vector bool short);
14574 vector signed short vec_sel (vector signed short,
14575 vector signed short,
14576 vector unsigned short);
14577 vector unsigned short vec_sel (vector unsigned short,
14578 vector unsigned short,
14579 vector bool short);
14580 vector unsigned short vec_sel (vector unsigned short,
14581 vector unsigned short,
14582 vector unsigned short);
14583 vector bool short vec_sel (vector bool short,
14585 vector bool short);
14586 vector bool short vec_sel (vector bool short,
14588 vector unsigned short);
14589 vector signed char vec_sel (vector signed char,
14590 vector signed char,
14592 vector signed char vec_sel (vector signed char,
14593 vector signed char,
14594 vector unsigned char);
14595 vector unsigned char vec_sel (vector unsigned char,
14596 vector unsigned char,
14598 vector unsigned char vec_sel (vector unsigned char,
14599 vector unsigned char,
14600 vector unsigned char);
14601 vector bool char vec_sel (vector bool char,
14604 vector bool char vec_sel (vector bool char,
14606 vector unsigned char);
14608 vector signed char vec_sl (vector signed char,
14609 vector unsigned char);
14610 vector unsigned char vec_sl (vector unsigned char,
14611 vector unsigned char);
14612 vector signed short vec_sl (vector signed short, vector unsigned short);
14613 vector unsigned short vec_sl (vector unsigned short,
14614 vector unsigned short);
14615 vector signed int vec_sl (vector signed int, vector unsigned int);
14616 vector unsigned int vec_sl (vector unsigned int, vector unsigned int);
14618 vector signed int vec_vslw (vector signed int, vector unsigned int);
14619 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int);
14621 vector signed short vec_vslh (vector signed short,
14622 vector unsigned short);
14623 vector unsigned short vec_vslh (vector unsigned short,
14624 vector unsigned short);
14626 vector signed char vec_vslb (vector signed char, vector unsigned char);
14627 vector unsigned char vec_vslb (vector unsigned char,
14628 vector unsigned char);
14630 vector float vec_sld (vector float, vector float, const int);
14631 vector signed int vec_sld (vector signed int,
14634 vector unsigned int vec_sld (vector unsigned int,
14635 vector unsigned int,
14637 vector bool int vec_sld (vector bool int,
14640 vector signed short vec_sld (vector signed short,
14641 vector signed short,
14643 vector unsigned short vec_sld (vector unsigned short,
14644 vector unsigned short,
14646 vector bool short vec_sld (vector bool short,
14649 vector pixel vec_sld (vector pixel,
14652 vector signed char vec_sld (vector signed char,
14653 vector signed char,
14655 vector unsigned char vec_sld (vector unsigned char,
14656 vector unsigned char,
14658 vector bool char vec_sld (vector bool char,
14662 vector signed int vec_sll (vector signed int,
14663 vector unsigned int);
14664 vector signed int vec_sll (vector signed int,
14665 vector unsigned short);
14666 vector signed int vec_sll (vector signed int,
14667 vector unsigned char);
14668 vector unsigned int vec_sll (vector unsigned int,
14669 vector unsigned int);
14670 vector unsigned int vec_sll (vector unsigned int,
14671 vector unsigned short);
14672 vector unsigned int vec_sll (vector unsigned int,
14673 vector unsigned char);
14674 vector bool int vec_sll (vector bool int,
14675 vector unsigned int);
14676 vector bool int vec_sll (vector bool int,
14677 vector unsigned short);
14678 vector bool int vec_sll (vector bool int,
14679 vector unsigned char);
14680 vector signed short vec_sll (vector signed short,
14681 vector unsigned int);
14682 vector signed short vec_sll (vector signed short,
14683 vector unsigned short);
14684 vector signed short vec_sll (vector signed short,
14685 vector unsigned char);
14686 vector unsigned short vec_sll (vector unsigned short,
14687 vector unsigned int);
14688 vector unsigned short vec_sll (vector unsigned short,
14689 vector unsigned short);
14690 vector unsigned short vec_sll (vector unsigned short,
14691 vector unsigned char);
14692 vector bool short vec_sll (vector bool short, vector unsigned int);
14693 vector bool short vec_sll (vector bool short, vector unsigned short);
14694 vector bool short vec_sll (vector bool short, vector unsigned char);
14695 vector pixel vec_sll (vector pixel, vector unsigned int);
14696 vector pixel vec_sll (vector pixel, vector unsigned short);
14697 vector pixel vec_sll (vector pixel, vector unsigned char);
14698 vector signed char vec_sll (vector signed char, vector unsigned int);
14699 vector signed char vec_sll (vector signed char, vector unsigned short);
14700 vector signed char vec_sll (vector signed char, vector unsigned char);
14701 vector unsigned char vec_sll (vector unsigned char,
14702 vector unsigned int);
14703 vector unsigned char vec_sll (vector unsigned char,
14704 vector unsigned short);
14705 vector unsigned char vec_sll (vector unsigned char,
14706 vector unsigned char);
14707 vector bool char vec_sll (vector bool char, vector unsigned int);
14708 vector bool char vec_sll (vector bool char, vector unsigned short);
14709 vector bool char vec_sll (vector bool char, vector unsigned char);
14711 vector float vec_slo (vector float, vector signed char);
14712 vector float vec_slo (vector float, vector unsigned char);
14713 vector signed int vec_slo (vector signed int, vector signed char);
14714 vector signed int vec_slo (vector signed int, vector unsigned char);
14715 vector unsigned int vec_slo (vector unsigned int, vector signed char);
14716 vector unsigned int vec_slo (vector unsigned int, vector unsigned char);
14717 vector signed short vec_slo (vector signed short, vector signed char);
14718 vector signed short vec_slo (vector signed short, vector unsigned char);
14719 vector unsigned short vec_slo (vector unsigned short,
14720 vector signed char);
14721 vector unsigned short vec_slo (vector unsigned short,
14722 vector unsigned char);
14723 vector pixel vec_slo (vector pixel, vector signed char);
14724 vector pixel vec_slo (vector pixel, vector unsigned char);
14725 vector signed char vec_slo (vector signed char, vector signed char);
14726 vector signed char vec_slo (vector signed char, vector unsigned char);
14727 vector unsigned char vec_slo (vector unsigned char, vector signed char);
14728 vector unsigned char vec_slo (vector unsigned char,
14729 vector unsigned char);
14731 vector signed char vec_splat (vector signed char, const int);
14732 vector unsigned char vec_splat (vector unsigned char, const int);
14733 vector bool char vec_splat (vector bool char, const int);
14734 vector signed short vec_splat (vector signed short, const int);
14735 vector unsigned short vec_splat (vector unsigned short, const int);
14736 vector bool short vec_splat (vector bool short, const int);
14737 vector pixel vec_splat (vector pixel, const int);
14738 vector float vec_splat (vector float, const int);
14739 vector signed int vec_splat (vector signed int, const int);
14740 vector unsigned int vec_splat (vector unsigned int, const int);
14741 vector bool int vec_splat (vector bool int, const int);
14742 vector signed long vec_splat (vector signed long, const int);
14743 vector unsigned long vec_splat (vector unsigned long, const int);
14745 vector signed char vec_splats (signed char);
14746 vector unsigned char vec_splats (unsigned char);
14747 vector signed short vec_splats (signed short);
14748 vector unsigned short vec_splats (unsigned short);
14749 vector signed int vec_splats (signed int);
14750 vector unsigned int vec_splats (unsigned int);
14751 vector float vec_splats (float);
14753 vector float vec_vspltw (vector float, const int);
14754 vector signed int vec_vspltw (vector signed int, const int);
14755 vector unsigned int vec_vspltw (vector unsigned int, const int);
14756 vector bool int vec_vspltw (vector bool int, const int);
14758 vector bool short vec_vsplth (vector bool short, const int);
14759 vector signed short vec_vsplth (vector signed short, const int);
14760 vector unsigned short vec_vsplth (vector unsigned short, const int);
14761 vector pixel vec_vsplth (vector pixel, const int);
14763 vector signed char vec_vspltb (vector signed char, const int);
14764 vector unsigned char vec_vspltb (vector unsigned char, const int);
14765 vector bool char vec_vspltb (vector bool char, const int);
14767 vector signed char vec_splat_s8 (const int);
14769 vector signed short vec_splat_s16 (const int);
14771 vector signed int vec_splat_s32 (const int);
14773 vector unsigned char vec_splat_u8 (const int);
14775 vector unsigned short vec_splat_u16 (const int);
14777 vector unsigned int vec_splat_u32 (const int);
14779 vector signed char vec_sr (vector signed char, vector unsigned char);
14780 vector unsigned char vec_sr (vector unsigned char,
14781 vector unsigned char);
14782 vector signed short vec_sr (vector signed short,
14783 vector unsigned short);
14784 vector unsigned short vec_sr (vector unsigned short,
14785 vector unsigned short);
14786 vector signed int vec_sr (vector signed int, vector unsigned int);
14787 vector unsigned int vec_sr (vector unsigned int, vector unsigned int);
14789 vector signed int vec_vsrw (vector signed int, vector unsigned int);
14790 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int);
14792 vector signed short vec_vsrh (vector signed short,
14793 vector unsigned short);
14794 vector unsigned short vec_vsrh (vector unsigned short,
14795 vector unsigned short);
14797 vector signed char vec_vsrb (vector signed char, vector unsigned char);
14798 vector unsigned char vec_vsrb (vector unsigned char,
14799 vector unsigned char);
14801 vector signed char vec_sra (vector signed char, vector unsigned char);
14802 vector unsigned char vec_sra (vector unsigned char,
14803 vector unsigned char);
14804 vector signed short vec_sra (vector signed short,
14805 vector unsigned short);
14806 vector unsigned short vec_sra (vector unsigned short,
14807 vector unsigned short);
14808 vector signed int vec_sra (vector signed int, vector unsigned int);
14809 vector unsigned int vec_sra (vector unsigned int, vector unsigned int);
14811 vector signed int vec_vsraw (vector signed int, vector unsigned int);
14812 vector unsigned int vec_vsraw (vector unsigned int,
14813 vector unsigned int);
14815 vector signed short vec_vsrah (vector signed short,
14816 vector unsigned short);
14817 vector unsigned short vec_vsrah (vector unsigned short,
14818 vector unsigned short);
14820 vector signed char vec_vsrab (vector signed char, vector unsigned char);
14821 vector unsigned char vec_vsrab (vector unsigned char,
14822 vector unsigned char);
14824 vector signed int vec_srl (vector signed int, vector unsigned int);
14825 vector signed int vec_srl (vector signed int, vector unsigned short);
14826 vector signed int vec_srl (vector signed int, vector unsigned char);
14827 vector unsigned int vec_srl (vector unsigned int, vector unsigned int);
14828 vector unsigned int vec_srl (vector unsigned int,
14829 vector unsigned short);
14830 vector unsigned int vec_srl (vector unsigned int, vector unsigned char);
14831 vector bool int vec_srl (vector bool int, vector unsigned int);
14832 vector bool int vec_srl (vector bool int, vector unsigned short);
14833 vector bool int vec_srl (vector bool int, vector unsigned char);
14834 vector signed short vec_srl (vector signed short, vector unsigned int);
14835 vector signed short vec_srl (vector signed short,
14836 vector unsigned short);
14837 vector signed short vec_srl (vector signed short, vector unsigned char);
14838 vector unsigned short vec_srl (vector unsigned short,
14839 vector unsigned int);
14840 vector unsigned short vec_srl (vector unsigned short,
14841 vector unsigned short);
14842 vector unsigned short vec_srl (vector unsigned short,
14843 vector unsigned char);
14844 vector bool short vec_srl (vector bool short, vector unsigned int);
14845 vector bool short vec_srl (vector bool short, vector unsigned short);
14846 vector bool short vec_srl (vector bool short, vector unsigned char);
14847 vector pixel vec_srl (vector pixel, vector unsigned int);
14848 vector pixel vec_srl (vector pixel, vector unsigned short);
14849 vector pixel vec_srl (vector pixel, vector unsigned char);
14850 vector signed char vec_srl (vector signed char, vector unsigned int);
14851 vector signed char vec_srl (vector signed char, vector unsigned short);
14852 vector signed char vec_srl (vector signed char, vector unsigned char);
14853 vector unsigned char vec_srl (vector unsigned char,
14854 vector unsigned int);
14855 vector unsigned char vec_srl (vector unsigned char,
14856 vector unsigned short);
14857 vector unsigned char vec_srl (vector unsigned char,
14858 vector unsigned char);
14859 vector bool char vec_srl (vector bool char, vector unsigned int);
14860 vector bool char vec_srl (vector bool char, vector unsigned short);
14861 vector bool char vec_srl (vector bool char, vector unsigned char);
14863 vector float vec_sro (vector float, vector signed char);
14864 vector float vec_sro (vector float, vector unsigned char);
14865 vector signed int vec_sro (vector signed int, vector signed char);
14866 vector signed int vec_sro (vector signed int, vector unsigned char);
14867 vector unsigned int vec_sro (vector unsigned int, vector signed char);
14868 vector unsigned int vec_sro (vector unsigned int, vector unsigned char);
14869 vector signed short vec_sro (vector signed short, vector signed char);
14870 vector signed short vec_sro (vector signed short, vector unsigned char);
14871 vector unsigned short vec_sro (vector unsigned short,
14872 vector signed char);
14873 vector unsigned short vec_sro (vector unsigned short,
14874 vector unsigned char);
14875 vector pixel vec_sro (vector pixel, vector signed char);
14876 vector pixel vec_sro (vector pixel, vector unsigned char);
14877 vector signed char vec_sro (vector signed char, vector signed char);
14878 vector signed char vec_sro (vector signed char, vector unsigned char);
14879 vector unsigned char vec_sro (vector unsigned char, vector signed char);
14880 vector unsigned char vec_sro (vector unsigned char,
14881 vector unsigned char);
14883 void vec_st (vector float, int, vector float *);
14884 void vec_st (vector float, int, float *);
14885 void vec_st (vector signed int, int, vector signed int *);
14886 void vec_st (vector signed int, int, int *);
14887 void vec_st (vector unsigned int, int, vector unsigned int *);
14888 void vec_st (vector unsigned int, int, unsigned int *);
14889 void vec_st (vector bool int, int, vector bool int *);
14890 void vec_st (vector bool int, int, unsigned int *);
14891 void vec_st (vector bool int, int, int *);
14892 void vec_st (vector signed short, int, vector signed short *);
14893 void vec_st (vector signed short, int, short *);
14894 void vec_st (vector unsigned short, int, vector unsigned short *);
14895 void vec_st (vector unsigned short, int, unsigned short *);
14896 void vec_st (vector bool short, int, vector bool short *);
14897 void vec_st (vector bool short, int, unsigned short *);
14898 void vec_st (vector pixel, int, vector pixel *);
14899 void vec_st (vector pixel, int, unsigned short *);
14900 void vec_st (vector pixel, int, short *);
14901 void vec_st (vector bool short, int, short *);
14902 void vec_st (vector signed char, int, vector signed char *);
14903 void vec_st (vector signed char, int, signed char *);
14904 void vec_st (vector unsigned char, int, vector unsigned char *);
14905 void vec_st (vector unsigned char, int, unsigned char *);
14906 void vec_st (vector bool char, int, vector bool char *);
14907 void vec_st (vector bool char, int, unsigned char *);
14908 void vec_st (vector bool char, int, signed char *);
14910 void vec_ste (vector signed char, int, signed char *);
14911 void vec_ste (vector unsigned char, int, unsigned char *);
14912 void vec_ste (vector bool char, int, signed char *);
14913 void vec_ste (vector bool char, int, unsigned char *);
14914 void vec_ste (vector signed short, int, short *);
14915 void vec_ste (vector unsigned short, int, unsigned short *);
14916 void vec_ste (vector bool short, int, short *);
14917 void vec_ste (vector bool short, int, unsigned short *);
14918 void vec_ste (vector pixel, int, short *);
14919 void vec_ste (vector pixel, int, unsigned short *);
14920 void vec_ste (vector float, int, float *);
14921 void vec_ste (vector signed int, int, int *);
14922 void vec_ste (vector unsigned int, int, unsigned int *);
14923 void vec_ste (vector bool int, int, int *);
14924 void vec_ste (vector bool int, int, unsigned int *);
14926 void vec_stvewx (vector float, int, float *);
14927 void vec_stvewx (vector signed int, int, int *);
14928 void vec_stvewx (vector unsigned int, int, unsigned int *);
14929 void vec_stvewx (vector bool int, int, int *);
14930 void vec_stvewx (vector bool int, int, unsigned int *);
14932 void vec_stvehx (vector signed short, int, short *);
14933 void vec_stvehx (vector unsigned short, int, unsigned short *);
14934 void vec_stvehx (vector bool short, int, short *);
14935 void vec_stvehx (vector bool short, int, unsigned short *);
14936 void vec_stvehx (vector pixel, int, short *);
14937 void vec_stvehx (vector pixel, int, unsigned short *);
14939 void vec_stvebx (vector signed char, int, signed char *);
14940 void vec_stvebx (vector unsigned char, int, unsigned char *);
14941 void vec_stvebx (vector bool char, int, signed char *);
14942 void vec_stvebx (vector bool char, int, unsigned char *);
14944 void vec_stl (vector float, int, vector float *);
14945 void vec_stl (vector float, int, float *);
14946 void vec_stl (vector signed int, int, vector signed int *);
14947 void vec_stl (vector signed int, int, int *);
14948 void vec_stl (vector unsigned int, int, vector unsigned int *);
14949 void vec_stl (vector unsigned int, int, unsigned int *);
14950 void vec_stl (vector bool int, int, vector bool int *);
14951 void vec_stl (vector bool int, int, unsigned int *);
14952 void vec_stl (vector bool int, int, int *);
14953 void vec_stl (vector signed short, int, vector signed short *);
14954 void vec_stl (vector signed short, int, short *);
14955 void vec_stl (vector unsigned short, int, vector unsigned short *);
14956 void vec_stl (vector unsigned short, int, unsigned short *);
14957 void vec_stl (vector bool short, int, vector bool short *);
14958 void vec_stl (vector bool short, int, unsigned short *);
14959 void vec_stl (vector bool short, int, short *);
14960 void vec_stl (vector pixel, int, vector pixel *);
14961 void vec_stl (vector pixel, int, unsigned short *);
14962 void vec_stl (vector pixel, int, short *);
14963 void vec_stl (vector signed char, int, vector signed char *);
14964 void vec_stl (vector signed char, int, signed char *);
14965 void vec_stl (vector unsigned char, int, vector unsigned char *);
14966 void vec_stl (vector unsigned char, int, unsigned char *);
14967 void vec_stl (vector bool char, int, vector bool char *);
14968 void vec_stl (vector bool char, int, unsigned char *);
14969 void vec_stl (vector bool char, int, signed char *);
14971 vector signed char vec_sub (vector bool char, vector signed char);
14972 vector signed char vec_sub (vector signed char, vector bool char);
14973 vector signed char vec_sub (vector signed char, vector signed char);
14974 vector unsigned char vec_sub (vector bool char, vector unsigned char);
14975 vector unsigned char vec_sub (vector unsigned char, vector bool char);
14976 vector unsigned char vec_sub (vector unsigned char,
14977 vector unsigned char);
14978 vector signed short vec_sub (vector bool short, vector signed short);
14979 vector signed short vec_sub (vector signed short, vector bool short);
14980 vector signed short vec_sub (vector signed short, vector signed short);
14981 vector unsigned short vec_sub (vector bool short,
14982 vector unsigned short);
14983 vector unsigned short vec_sub (vector unsigned short,
14984 vector bool short);
14985 vector unsigned short vec_sub (vector unsigned short,
14986 vector unsigned short);
14987 vector signed int vec_sub (vector bool int, vector signed int);
14988 vector signed int vec_sub (vector signed int, vector bool int);
14989 vector signed int vec_sub (vector signed int, vector signed int);
14990 vector unsigned int vec_sub (vector bool int, vector unsigned int);
14991 vector unsigned int vec_sub (vector unsigned int, vector bool int);
14992 vector unsigned int vec_sub (vector unsigned int, vector unsigned int);
14993 vector float vec_sub (vector float, vector float);
14995 vector float vec_vsubfp (vector float, vector float);
14997 vector signed int vec_vsubuwm (vector bool int, vector signed int);
14998 vector signed int vec_vsubuwm (vector signed int, vector bool int);
14999 vector signed int vec_vsubuwm (vector signed int, vector signed int);
15000 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int);
15001 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int);
15002 vector unsigned int vec_vsubuwm (vector unsigned int,
15003 vector unsigned int);
15005 vector signed short vec_vsubuhm (vector bool short,
15006 vector signed short);
15007 vector signed short vec_vsubuhm (vector signed short,
15008 vector bool short);
15009 vector signed short vec_vsubuhm (vector signed short,
15010 vector signed short);
15011 vector unsigned short vec_vsubuhm (vector bool short,
15012 vector unsigned short);
15013 vector unsigned short vec_vsubuhm (vector unsigned short,
15014 vector bool short);
15015 vector unsigned short vec_vsubuhm (vector unsigned short,
15016 vector unsigned short);
15018 vector signed char vec_vsububm (vector bool char, vector signed char);
15019 vector signed char vec_vsububm (vector signed char, vector bool char);
15020 vector signed char vec_vsububm (vector signed char, vector signed char);
15021 vector unsigned char vec_vsububm (vector bool char,
15022 vector unsigned char);
15023 vector unsigned char vec_vsububm (vector unsigned char,
15025 vector unsigned char vec_vsububm (vector unsigned char,
15026 vector unsigned char);
15028 vector unsigned int vec_subc (vector unsigned int, vector unsigned int);
15030 vector unsigned char vec_subs (vector bool char, vector unsigned char);
15031 vector unsigned char vec_subs (vector unsigned char, vector bool char);
15032 vector unsigned char vec_subs (vector unsigned char,
15033 vector unsigned char);
15034 vector signed char vec_subs (vector bool char, vector signed char);
15035 vector signed char vec_subs (vector signed char, vector bool char);
15036 vector signed char vec_subs (vector signed char, vector signed char);
15037 vector unsigned short vec_subs (vector bool short,
15038 vector unsigned short);
15039 vector unsigned short vec_subs (vector unsigned short,
15040 vector bool short);
15041 vector unsigned short vec_subs (vector unsigned short,
15042 vector unsigned short);
15043 vector signed short vec_subs (vector bool short, vector signed short);
15044 vector signed short vec_subs (vector signed short, vector bool short);
15045 vector signed short vec_subs (vector signed short, vector signed short);
15046 vector unsigned int vec_subs (vector bool int, vector unsigned int);
15047 vector unsigned int vec_subs (vector unsigned int, vector bool int);
15048 vector unsigned int vec_subs (vector unsigned int, vector unsigned int);
15049 vector signed int vec_subs (vector bool int, vector signed int);
15050 vector signed int vec_subs (vector signed int, vector bool int);
15051 vector signed int vec_subs (vector signed int, vector signed int);
15053 vector signed int vec_vsubsws (vector bool int, vector signed int);
15054 vector signed int vec_vsubsws (vector signed int, vector bool int);
15055 vector signed int vec_vsubsws (vector signed int, vector signed int);
15057 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int);
15058 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int);
15059 vector unsigned int vec_vsubuws (vector unsigned int,
15060 vector unsigned int);
15062 vector signed short vec_vsubshs (vector bool short,
15063 vector signed short);
15064 vector signed short vec_vsubshs (vector signed short,
15065 vector bool short);
15066 vector signed short vec_vsubshs (vector signed short,
15067 vector signed short);
15069 vector unsigned short vec_vsubuhs (vector bool short,
15070 vector unsigned short);
15071 vector unsigned short vec_vsubuhs (vector unsigned short,
15072 vector bool short);
15073 vector unsigned short vec_vsubuhs (vector unsigned short,
15074 vector unsigned short);
15076 vector signed char vec_vsubsbs (vector bool char, vector signed char);
15077 vector signed char vec_vsubsbs (vector signed char, vector bool char);
15078 vector signed char vec_vsubsbs (vector signed char, vector signed char);
15080 vector unsigned char vec_vsububs (vector bool char,
15081 vector unsigned char);
15082 vector unsigned char vec_vsububs (vector unsigned char,
15084 vector unsigned char vec_vsububs (vector unsigned char,
15085 vector unsigned char);
15087 vector unsigned int vec_sum4s (vector unsigned char,
15088 vector unsigned int);
15089 vector signed int vec_sum4s (vector signed char, vector signed int);
15090 vector signed int vec_sum4s (vector signed short, vector signed int);
15092 vector signed int vec_vsum4shs (vector signed short, vector signed int);
15094 vector signed int vec_vsum4sbs (vector signed char, vector signed int);
15096 vector unsigned int vec_vsum4ubs (vector unsigned char,
15097 vector unsigned int);
15099 vector signed int vec_sum2s (vector signed int, vector signed int);
15101 vector signed int vec_sums (vector signed int, vector signed int);
15103 vector float vec_trunc (vector float);
15105 vector signed short vec_unpackh (vector signed char);
15106 vector bool short vec_unpackh (vector bool char);
15107 vector signed int vec_unpackh (vector signed short);
15108 vector bool int vec_unpackh (vector bool short);
15109 vector unsigned int vec_unpackh (vector pixel);
15111 vector bool int vec_vupkhsh (vector bool short);
15112 vector signed int vec_vupkhsh (vector signed short);
15114 vector unsigned int vec_vupkhpx (vector pixel);
15116 vector bool short vec_vupkhsb (vector bool char);
15117 vector signed short vec_vupkhsb (vector signed char);
15119 vector signed short vec_unpackl (vector signed char);
15120 vector bool short vec_unpackl (vector bool char);
15121 vector unsigned int vec_unpackl (vector pixel);
15122 vector signed int vec_unpackl (vector signed short);
15123 vector bool int vec_unpackl (vector bool short);
15125 vector unsigned int vec_vupklpx (vector pixel);
15127 vector bool int vec_vupklsh (vector bool short);
15128 vector signed int vec_vupklsh (vector signed short);
15130 vector bool short vec_vupklsb (vector bool char);
15131 vector signed short vec_vupklsb (vector signed char);
15133 vector float vec_xor (vector float, vector float);
15134 vector float vec_xor (vector float, vector bool int);
15135 vector float vec_xor (vector bool int, vector float);
15136 vector bool int vec_xor (vector bool int, vector bool int);
15137 vector signed int vec_xor (vector bool int, vector signed int);
15138 vector signed int vec_xor (vector signed int, vector bool int);
15139 vector signed int vec_xor (vector signed int, vector signed int);
15140 vector unsigned int vec_xor (vector bool int, vector unsigned int);
15141 vector unsigned int vec_xor (vector unsigned int, vector bool int);
15142 vector unsigned int vec_xor (vector unsigned int, vector unsigned int);
15143 vector bool short vec_xor (vector bool short, vector bool short);
15144 vector signed short vec_xor (vector bool short, vector signed short);
15145 vector signed short vec_xor (vector signed short, vector bool short);
15146 vector signed short vec_xor (vector signed short, vector signed short);
15147 vector unsigned short vec_xor (vector bool short,
15148 vector unsigned short);
15149 vector unsigned short vec_xor (vector unsigned short,
15150 vector bool short);
15151 vector unsigned short vec_xor (vector unsigned short,
15152 vector unsigned short);
15153 vector signed char vec_xor (vector bool char, vector signed char);
15154 vector bool char vec_xor (vector bool char, vector bool char);
15155 vector signed char vec_xor (vector signed char, vector bool char);
15156 vector signed char vec_xor (vector signed char, vector signed char);
15157 vector unsigned char vec_xor (vector bool char, vector unsigned char);
15158 vector unsigned char vec_xor (vector unsigned char, vector bool char);
15159 vector unsigned char vec_xor (vector unsigned char,
15160 vector unsigned char);
15162 int vec_all_eq (vector signed char, vector bool char);
15163 int vec_all_eq (vector signed char, vector signed char);
15164 int vec_all_eq (vector unsigned char, vector bool char);
15165 int vec_all_eq (vector unsigned char, vector unsigned char);
15166 int vec_all_eq (vector bool char, vector bool char);
15167 int vec_all_eq (vector bool char, vector unsigned char);
15168 int vec_all_eq (vector bool char, vector signed char);
15169 int vec_all_eq (vector signed short, vector bool short);
15170 int vec_all_eq (vector signed short, vector signed short);
15171 int vec_all_eq (vector unsigned short, vector bool short);
15172 int vec_all_eq (vector unsigned short, vector unsigned short);
15173 int vec_all_eq (vector bool short, vector bool short);
15174 int vec_all_eq (vector bool short, vector unsigned short);
15175 int vec_all_eq (vector bool short, vector signed short);
15176 int vec_all_eq (vector pixel, vector pixel);
15177 int vec_all_eq (vector signed int, vector bool int);
15178 int vec_all_eq (vector signed int, vector signed int);
15179 int vec_all_eq (vector unsigned int, vector bool int);
15180 int vec_all_eq (vector unsigned int, vector unsigned int);
15181 int vec_all_eq (vector bool int, vector bool int);
15182 int vec_all_eq (vector bool int, vector unsigned int);
15183 int vec_all_eq (vector bool int, vector signed int);
15184 int vec_all_eq (vector float, vector float);
15186 int vec_all_ge (vector bool char, vector unsigned char);
15187 int vec_all_ge (vector unsigned char, vector bool char);
15188 int vec_all_ge (vector unsigned char, vector unsigned char);
15189 int vec_all_ge (vector bool char, vector signed char);
15190 int vec_all_ge (vector signed char, vector bool char);
15191 int vec_all_ge (vector signed char, vector signed char);
15192 int vec_all_ge (vector bool short, vector unsigned short);
15193 int vec_all_ge (vector unsigned short, vector bool short);
15194 int vec_all_ge (vector unsigned short, vector unsigned short);
15195 int vec_all_ge (vector signed short, vector signed short);
15196 int vec_all_ge (vector bool short, vector signed short);
15197 int vec_all_ge (vector signed short, vector bool short);
15198 int vec_all_ge (vector bool int, vector unsigned int);
15199 int vec_all_ge (vector unsigned int, vector bool int);
15200 int vec_all_ge (vector unsigned int, vector unsigned int);
15201 int vec_all_ge (vector bool int, vector signed int);
15202 int vec_all_ge (vector signed int, vector bool int);
15203 int vec_all_ge (vector signed int, vector signed int);
15204 int vec_all_ge (vector float, vector float);
15206 int vec_all_gt (vector bool char, vector unsigned char);
15207 int vec_all_gt (vector unsigned char, vector bool char);
15208 int vec_all_gt (vector unsigned char, vector unsigned char);
15209 int vec_all_gt (vector bool char, vector signed char);
15210 int vec_all_gt (vector signed char, vector bool char);
15211 int vec_all_gt (vector signed char, vector signed char);
15212 int vec_all_gt (vector bool short, vector unsigned short);
15213 int vec_all_gt (vector unsigned short, vector bool short);
15214 int vec_all_gt (vector unsigned short, vector unsigned short);
15215 int vec_all_gt (vector bool short, vector signed short);
15216 int vec_all_gt (vector signed short, vector bool short);
15217 int vec_all_gt (vector signed short, vector signed short);
15218 int vec_all_gt (vector bool int, vector unsigned int);
15219 int vec_all_gt (vector unsigned int, vector bool int);
15220 int vec_all_gt (vector unsigned int, vector unsigned int);
15221 int vec_all_gt (vector bool int, vector signed int);
15222 int vec_all_gt (vector signed int, vector bool int);
15223 int vec_all_gt (vector signed int, vector signed int);
15224 int vec_all_gt (vector float, vector float);
15226 int vec_all_in (vector float, vector float);
15228 int vec_all_le (vector bool char, vector unsigned char);
15229 int vec_all_le (vector unsigned char, vector bool char);
15230 int vec_all_le (vector unsigned char, vector unsigned char);
15231 int vec_all_le (vector bool char, vector signed char);
15232 int vec_all_le (vector signed char, vector bool char);
15233 int vec_all_le (vector signed char, vector signed char);
15234 int vec_all_le (vector bool short, vector unsigned short);
15235 int vec_all_le (vector unsigned short, vector bool short);
15236 int vec_all_le (vector unsigned short, vector unsigned short);
15237 int vec_all_le (vector bool short, vector signed short);
15238 int vec_all_le (vector signed short, vector bool short);
15239 int vec_all_le (vector signed short, vector signed short);
15240 int vec_all_le (vector bool int, vector unsigned int);
15241 int vec_all_le (vector unsigned int, vector bool int);
15242 int vec_all_le (vector unsigned int, vector unsigned int);
15243 int vec_all_le (vector bool int, vector signed int);
15244 int vec_all_le (vector signed int, vector bool int);
15245 int vec_all_le (vector signed int, vector signed int);
15246 int vec_all_le (vector float, vector float);
15248 int vec_all_lt (vector bool char, vector unsigned char);
15249 int vec_all_lt (vector unsigned char, vector bool char);
15250 int vec_all_lt (vector unsigned char, vector unsigned char);
15251 int vec_all_lt (vector bool char, vector signed char);
15252 int vec_all_lt (vector signed char, vector bool char);
15253 int vec_all_lt (vector signed char, vector signed char);
15254 int vec_all_lt (vector bool short, vector unsigned short);
15255 int vec_all_lt (vector unsigned short, vector bool short);
15256 int vec_all_lt (vector unsigned short, vector unsigned short);
15257 int vec_all_lt (vector bool short, vector signed short);
15258 int vec_all_lt (vector signed short, vector bool short);
15259 int vec_all_lt (vector signed short, vector signed short);
15260 int vec_all_lt (vector bool int, vector unsigned int);
15261 int vec_all_lt (vector unsigned int, vector bool int);
15262 int vec_all_lt (vector unsigned int, vector unsigned int);
15263 int vec_all_lt (vector bool int, vector signed int);
15264 int vec_all_lt (vector signed int, vector bool int);
15265 int vec_all_lt (vector signed int, vector signed int);
15266 int vec_all_lt (vector float, vector float);
15268 int vec_all_nan (vector float);
15270 int vec_all_ne (vector signed char, vector bool char);
15271 int vec_all_ne (vector signed char, vector signed char);
15272 int vec_all_ne (vector unsigned char, vector bool char);
15273 int vec_all_ne (vector unsigned char, vector unsigned char);
15274 int vec_all_ne (vector bool char, vector bool char);
15275 int vec_all_ne (vector bool char, vector unsigned char);
15276 int vec_all_ne (vector bool char, vector signed char);
15277 int vec_all_ne (vector signed short, vector bool short);
15278 int vec_all_ne (vector signed short, vector signed short);
15279 int vec_all_ne (vector unsigned short, vector bool short);
15280 int vec_all_ne (vector unsigned short, vector unsigned short);
15281 int vec_all_ne (vector bool short, vector bool short);
15282 int vec_all_ne (vector bool short, vector unsigned short);
15283 int vec_all_ne (vector bool short, vector signed short);
15284 int vec_all_ne (vector pixel, vector pixel);
15285 int vec_all_ne (vector signed int, vector bool int);
15286 int vec_all_ne (vector signed int, vector signed int);
15287 int vec_all_ne (vector unsigned int, vector bool int);
15288 int vec_all_ne (vector unsigned int, vector unsigned int);
15289 int vec_all_ne (vector bool int, vector bool int);
15290 int vec_all_ne (vector bool int, vector unsigned int);
15291 int vec_all_ne (vector bool int, vector signed int);
15292 int vec_all_ne (vector float, vector float);
15294 int vec_all_nge (vector float, vector float);
15296 int vec_all_ngt (vector float, vector float);
15298 int vec_all_nle (vector float, vector float);
15300 int vec_all_nlt (vector float, vector float);
15302 int vec_all_numeric (vector float);
15304 int vec_any_eq (vector signed char, vector bool char);
15305 int vec_any_eq (vector signed char, vector signed char);
15306 int vec_any_eq (vector unsigned char, vector bool char);
15307 int vec_any_eq (vector unsigned char, vector unsigned char);
15308 int vec_any_eq (vector bool char, vector bool char);
15309 int vec_any_eq (vector bool char, vector unsigned char);
15310 int vec_any_eq (vector bool char, vector signed char);
15311 int vec_any_eq (vector signed short, vector bool short);
15312 int vec_any_eq (vector signed short, vector signed short);
15313 int vec_any_eq (vector unsigned short, vector bool short);
15314 int vec_any_eq (vector unsigned short, vector unsigned short);
15315 int vec_any_eq (vector bool short, vector bool short);
15316 int vec_any_eq (vector bool short, vector unsigned short);
15317 int vec_any_eq (vector bool short, vector signed short);
15318 int vec_any_eq (vector pixel, vector pixel);
15319 int vec_any_eq (vector signed int, vector bool int);
15320 int vec_any_eq (vector signed int, vector signed int);
15321 int vec_any_eq (vector unsigned int, vector bool int);
15322 int vec_any_eq (vector unsigned int, vector unsigned int);
15323 int vec_any_eq (vector bool int, vector bool int);
15324 int vec_any_eq (vector bool int, vector unsigned int);
15325 int vec_any_eq (vector bool int, vector signed int);
15326 int vec_any_eq (vector float, vector float);
15328 int vec_any_ge (vector signed char, vector bool char);
15329 int vec_any_ge (vector unsigned char, vector bool char);
15330 int vec_any_ge (vector unsigned char, vector unsigned char);
15331 int vec_any_ge (vector signed char, vector signed char);
15332 int vec_any_ge (vector bool char, vector unsigned char);
15333 int vec_any_ge (vector bool char, vector signed char);
15334 int vec_any_ge (vector unsigned short, vector bool short);
15335 int vec_any_ge (vector unsigned short, vector unsigned short);
15336 int vec_any_ge (vector signed short, vector signed short);
15337 int vec_any_ge (vector signed short, vector bool short);
15338 int vec_any_ge (vector bool short, vector unsigned short);
15339 int vec_any_ge (vector bool short, vector signed short);
15340 int vec_any_ge (vector signed int, vector bool int);
15341 int vec_any_ge (vector unsigned int, vector bool int);
15342 int vec_any_ge (vector unsigned int, vector unsigned int);
15343 int vec_any_ge (vector signed int, vector signed int);
15344 int vec_any_ge (vector bool int, vector unsigned int);
15345 int vec_any_ge (vector bool int, vector signed int);
15346 int vec_any_ge (vector float, vector float);
15348 int vec_any_gt (vector bool char, vector unsigned char);
15349 int vec_any_gt (vector unsigned char, vector bool char);
15350 int vec_any_gt (vector unsigned char, vector unsigned char);
15351 int vec_any_gt (vector bool char, vector signed char);
15352 int vec_any_gt (vector signed char, vector bool char);
15353 int vec_any_gt (vector signed char, vector signed char);
15354 int vec_any_gt (vector bool short, vector unsigned short);
15355 int vec_any_gt (vector unsigned short, vector bool short);
15356 int vec_any_gt (vector unsigned short, vector unsigned short);
15357 int vec_any_gt (vector bool short, vector signed short);
15358 int vec_any_gt (vector signed short, vector bool short);
15359 int vec_any_gt (vector signed short, vector signed short);
15360 int vec_any_gt (vector bool int, vector unsigned int);
15361 int vec_any_gt (vector unsigned int, vector bool int);
15362 int vec_any_gt (vector unsigned int, vector unsigned int);
15363 int vec_any_gt (vector bool int, vector signed int);
15364 int vec_any_gt (vector signed int, vector bool int);
15365 int vec_any_gt (vector signed int, vector signed int);
15366 int vec_any_gt (vector float, vector float);
15368 int vec_any_le (vector bool char, vector unsigned char);
15369 int vec_any_le (vector unsigned char, vector bool char);
15370 int vec_any_le (vector unsigned char, vector unsigned char);
15371 int vec_any_le (vector bool char, vector signed char);
15372 int vec_any_le (vector signed char, vector bool char);
15373 int vec_any_le (vector signed char, vector signed char);
15374 int vec_any_le (vector bool short, vector unsigned short);
15375 int vec_any_le (vector unsigned short, vector bool short);
15376 int vec_any_le (vector unsigned short, vector unsigned short);
15377 int vec_any_le (vector bool short, vector signed short);
15378 int vec_any_le (vector signed short, vector bool short);
15379 int vec_any_le (vector signed short, vector signed short);
15380 int vec_any_le (vector bool int, vector unsigned int);
15381 int vec_any_le (vector unsigned int, vector bool int);
15382 int vec_any_le (vector unsigned int, vector unsigned int);
15383 int vec_any_le (vector bool int, vector signed int);
15384 int vec_any_le (vector signed int, vector bool int);
15385 int vec_any_le (vector signed int, vector signed int);
15386 int vec_any_le (vector float, vector float);
15388 int vec_any_lt (vector bool char, vector unsigned char);
15389 int vec_any_lt (vector unsigned char, vector bool char);
15390 int vec_any_lt (vector unsigned char, vector unsigned char);
15391 int vec_any_lt (vector bool char, vector signed char);
15392 int vec_any_lt (vector signed char, vector bool char);
15393 int vec_any_lt (vector signed char, vector signed char);
15394 int vec_any_lt (vector bool short, vector unsigned short);
15395 int vec_any_lt (vector unsigned short, vector bool short);
15396 int vec_any_lt (vector unsigned short, vector unsigned short);
15397 int vec_any_lt (vector bool short, vector signed short);
15398 int vec_any_lt (vector signed short, vector bool short);
15399 int vec_any_lt (vector signed short, vector signed short);
15400 int vec_any_lt (vector bool int, vector unsigned int);
15401 int vec_any_lt (vector unsigned int, vector bool int);
15402 int vec_any_lt (vector unsigned int, vector unsigned int);
15403 int vec_any_lt (vector bool int, vector signed int);
15404 int vec_any_lt (vector signed int, vector bool int);
15405 int vec_any_lt (vector signed int, vector signed int);
15406 int vec_any_lt (vector float, vector float);
15408 int vec_any_nan (vector float);
15410 int vec_any_ne (vector signed char, vector bool char);
15411 int vec_any_ne (vector signed char, vector signed char);
15412 int vec_any_ne (vector unsigned char, vector bool char);
15413 int vec_any_ne (vector unsigned char, vector unsigned char);
15414 int vec_any_ne (vector bool char, vector bool char);
15415 int vec_any_ne (vector bool char, vector unsigned char);
15416 int vec_any_ne (vector bool char, vector signed char);
15417 int vec_any_ne (vector signed short, vector bool short);
15418 int vec_any_ne (vector signed short, vector signed short);
15419 int vec_any_ne (vector unsigned short, vector bool short);
15420 int vec_any_ne (vector unsigned short, vector unsigned short);
15421 int vec_any_ne (vector bool short, vector bool short);
15422 int vec_any_ne (vector bool short, vector unsigned short);
15423 int vec_any_ne (vector bool short, vector signed short);
15424 int vec_any_ne (vector pixel, vector pixel);
15425 int vec_any_ne (vector signed int, vector bool int);
15426 int vec_any_ne (vector signed int, vector signed int);
15427 int vec_any_ne (vector unsigned int, vector bool int);
15428 int vec_any_ne (vector unsigned int, vector unsigned int);
15429 int vec_any_ne (vector bool int, vector bool int);
15430 int vec_any_ne (vector bool int, vector unsigned int);
15431 int vec_any_ne (vector bool int, vector signed int);
15432 int vec_any_ne (vector float, vector float);
15434 int vec_any_nge (vector float, vector float);
15436 int vec_any_ngt (vector float, vector float);
15438 int vec_any_nle (vector float, vector float);
15440 int vec_any_nlt (vector float, vector float);
15442 int vec_any_numeric (vector float);
15444 int vec_any_out (vector float, vector float);
15447 If the vector/scalar (VSX) instruction set is available, the following
15448 additional functions are available:
15451 vector double vec_abs (vector double);
15452 vector double vec_add (vector double, vector double);
15453 vector double vec_and (vector double, vector double);
15454 vector double vec_and (vector double, vector bool long);
15455 vector double vec_and (vector bool long, vector double);
15456 vector long vec_and (vector long, vector long);
15457 vector long vec_and (vector long, vector bool long);
15458 vector long vec_and (vector bool long, vector long);
15459 vector unsigned long vec_and (vector unsigned long, vector unsigned long);
15460 vector unsigned long vec_and (vector unsigned long, vector bool long);
15461 vector unsigned long vec_and (vector bool long, vector unsigned long);
15462 vector double vec_andc (vector double, vector double);
15463 vector double vec_andc (vector double, vector bool long);
15464 vector double vec_andc (vector bool long, vector double);
15465 vector long vec_andc (vector long, vector long);
15466 vector long vec_andc (vector long, vector bool long);
15467 vector long vec_andc (vector bool long, vector long);
15468 vector unsigned long vec_andc (vector unsigned long, vector unsigned long);
15469 vector unsigned long vec_andc (vector unsigned long, vector bool long);
15470 vector unsigned long vec_andc (vector bool long, vector unsigned long);
15471 vector double vec_ceil (vector double);
15472 vector bool long vec_cmpeq (vector double, vector double);
15473 vector bool long vec_cmpge (vector double, vector double);
15474 vector bool long vec_cmpgt (vector double, vector double);
15475 vector bool long vec_cmple (vector double, vector double);
15476 vector bool long vec_cmplt (vector double, vector double);
15477 vector double vec_cpsgn (vector double, vector double);
15478 vector float vec_div (vector float, vector float);
15479 vector double vec_div (vector double, vector double);
15480 vector long vec_div (vector long, vector long);
15481 vector unsigned long vec_div (vector unsigned long, vector unsigned long);
15482 vector double vec_floor (vector double);
15483 vector double vec_ld (int, const vector double *);
15484 vector double vec_ld (int, const double *);
15485 vector double vec_ldl (int, const vector double *);
15486 vector double vec_ldl (int, const double *);
15487 vector unsigned char vec_lvsl (int, const volatile double *);
15488 vector unsigned char vec_lvsr (int, const volatile double *);
15489 vector double vec_madd (vector double, vector double, vector double);
15490 vector double vec_max (vector double, vector double);
15491 vector signed long vec_mergeh (vector signed long, vector signed long);
15492 vector signed long vec_mergeh (vector signed long, vector bool long);
15493 vector signed long vec_mergeh (vector bool long, vector signed long);
15494 vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long);
15495 vector unsigned long vec_mergeh (vector unsigned long, vector bool long);
15496 vector unsigned long vec_mergeh (vector bool long, vector unsigned long);
15497 vector signed long vec_mergel (vector signed long, vector signed long);
15498 vector signed long vec_mergel (vector signed long, vector bool long);
15499 vector signed long vec_mergel (vector bool long, vector signed long);
15500 vector unsigned long vec_mergel (vector unsigned long, vector unsigned long);
15501 vector unsigned long vec_mergel (vector unsigned long, vector bool long);
15502 vector unsigned long vec_mergel (vector bool long, vector unsigned long);
15503 vector double vec_min (vector double, vector double);
15504 vector float vec_msub (vector float, vector float, vector float);
15505 vector double vec_msub (vector double, vector double, vector double);
15506 vector float vec_mul (vector float, vector float);
15507 vector double vec_mul (vector double, vector double);
15508 vector long vec_mul (vector long, vector long);
15509 vector unsigned long vec_mul (vector unsigned long, vector unsigned long);
15510 vector float vec_nearbyint (vector float);
15511 vector double vec_nearbyint (vector double);
15512 vector float vec_nmadd (vector float, vector float, vector float);
15513 vector double vec_nmadd (vector double, vector double, vector double);
15514 vector double vec_nmsub (vector double, vector double, vector double);
15515 vector double vec_nor (vector double, vector double);
15516 vector long vec_nor (vector long, vector long);
15517 vector long vec_nor (vector long, vector bool long);
15518 vector long vec_nor (vector bool long, vector long);
15519 vector unsigned long vec_nor (vector unsigned long, vector unsigned long);
15520 vector unsigned long vec_nor (vector unsigned long, vector bool long);
15521 vector unsigned long vec_nor (vector bool long, vector unsigned long);
15522 vector double vec_or (vector double, vector double);
15523 vector double vec_or (vector double, vector bool long);
15524 vector double vec_or (vector bool long, vector double);
15525 vector long vec_or (vector long, vector long);
15526 vector long vec_or (vector long, vector bool long);
15527 vector long vec_or (vector bool long, vector long);
15528 vector unsigned long vec_or (vector unsigned long, vector unsigned long);
15529 vector unsigned long vec_or (vector unsigned long, vector bool long);
15530 vector unsigned long vec_or (vector bool long, vector unsigned long);
15531 vector double vec_perm (vector double, vector double, vector unsigned char);
15532 vector long vec_perm (vector long, vector long, vector unsigned char);
15533 vector unsigned long vec_perm (vector unsigned long, vector unsigned long,
15534 vector unsigned char);
15535 vector double vec_rint (vector double);
15536 vector double vec_recip (vector double, vector double);
15537 vector double vec_rsqrt (vector double);
15538 vector double vec_rsqrte (vector double);
15539 vector double vec_sel (vector double, vector double, vector bool long);
15540 vector double vec_sel (vector double, vector double, vector unsigned long);
15541 vector long vec_sel (vector long, vector long, vector long);
15542 vector long vec_sel (vector long, vector long, vector unsigned long);
15543 vector long vec_sel (vector long, vector long, vector bool long);
15544 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
15546 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
15547 vector unsigned long);
15548 vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
15550 vector double vec_splats (double);
15551 vector signed long vec_splats (signed long);
15552 vector unsigned long vec_splats (unsigned long);
15553 vector float vec_sqrt (vector float);
15554 vector double vec_sqrt (vector double);
15555 void vec_st (vector double, int, vector double *);
15556 void vec_st (vector double, int, double *);
15557 vector double vec_sub (vector double, vector double);
15558 vector double vec_trunc (vector double);
15559 vector double vec_xor (vector double, vector double);
15560 vector double vec_xor (vector double, vector bool long);
15561 vector double vec_xor (vector bool long, vector double);
15562 vector long vec_xor (vector long, vector long);
15563 vector long vec_xor (vector long, vector bool long);
15564 vector long vec_xor (vector bool long, vector long);
15565 vector unsigned long vec_xor (vector unsigned long, vector unsigned long);
15566 vector unsigned long vec_xor (vector unsigned long, vector bool long);
15567 vector unsigned long vec_xor (vector bool long, vector unsigned long);
15568 int vec_all_eq (vector double, vector double);
15569 int vec_all_ge (vector double, vector double);
15570 int vec_all_gt (vector double, vector double);
15571 int vec_all_le (vector double, vector double);
15572 int vec_all_lt (vector double, vector double);
15573 int vec_all_nan (vector double);
15574 int vec_all_ne (vector double, vector double);
15575 int vec_all_nge (vector double, vector double);
15576 int vec_all_ngt (vector double, vector double);
15577 int vec_all_nle (vector double, vector double);
15578 int vec_all_nlt (vector double, vector double);
15579 int vec_all_numeric (vector double);
15580 int vec_any_eq (vector double, vector double);
15581 int vec_any_ge (vector double, vector double);
15582 int vec_any_gt (vector double, vector double);
15583 int vec_any_le (vector double, vector double);
15584 int vec_any_lt (vector double, vector double);
15585 int vec_any_nan (vector double);
15586 int vec_any_ne (vector double, vector double);
15587 int vec_any_nge (vector double, vector double);
15588 int vec_any_ngt (vector double, vector double);
15589 int vec_any_nle (vector double, vector double);
15590 int vec_any_nlt (vector double, vector double);
15591 int vec_any_numeric (vector double);
15593 vector double vec_vsx_ld (int, const vector double *);
15594 vector double vec_vsx_ld (int, const double *);
15595 vector float vec_vsx_ld (int, const vector float *);
15596 vector float vec_vsx_ld (int, const float *);
15597 vector bool int vec_vsx_ld (int, const vector bool int *);
15598 vector signed int vec_vsx_ld (int, const vector signed int *);
15599 vector signed int vec_vsx_ld (int, const int *);
15600 vector signed int vec_vsx_ld (int, const long *);
15601 vector unsigned int vec_vsx_ld (int, const vector unsigned int *);
15602 vector unsigned int vec_vsx_ld (int, const unsigned int *);
15603 vector unsigned int vec_vsx_ld (int, const unsigned long *);
15604 vector bool short vec_vsx_ld (int, const vector bool short *);
15605 vector pixel vec_vsx_ld (int, const vector pixel *);
15606 vector signed short vec_vsx_ld (int, const vector signed short *);
15607 vector signed short vec_vsx_ld (int, const short *);
15608 vector unsigned short vec_vsx_ld (int, const vector unsigned short *);
15609 vector unsigned short vec_vsx_ld (int, const unsigned short *);
15610 vector bool char vec_vsx_ld (int, const vector bool char *);
15611 vector signed char vec_vsx_ld (int, const vector signed char *);
15612 vector signed char vec_vsx_ld (int, const signed char *);
15613 vector unsigned char vec_vsx_ld (int, const vector unsigned char *);
15614 vector unsigned char vec_vsx_ld (int, const unsigned char *);
15616 void vec_vsx_st (vector double, int, vector double *);
15617 void vec_vsx_st (vector double, int, double *);
15618 void vec_vsx_st (vector float, int, vector float *);
15619 void vec_vsx_st (vector float, int, float *);
15620 void vec_vsx_st (vector signed int, int, vector signed int *);
15621 void vec_vsx_st (vector signed int, int, int *);
15622 void vec_vsx_st (vector unsigned int, int, vector unsigned int *);
15623 void vec_vsx_st (vector unsigned int, int, unsigned int *);
15624 void vec_vsx_st (vector bool int, int, vector bool int *);
15625 void vec_vsx_st (vector bool int, int, unsigned int *);
15626 void vec_vsx_st (vector bool int, int, int *);
15627 void vec_vsx_st (vector signed short, int, vector signed short *);
15628 void vec_vsx_st (vector signed short, int, short *);
15629 void vec_vsx_st (vector unsigned short, int, vector unsigned short *);
15630 void vec_vsx_st (vector unsigned short, int, unsigned short *);
15631 void vec_vsx_st (vector bool short, int, vector bool short *);
15632 void vec_vsx_st (vector bool short, int, unsigned short *);
15633 void vec_vsx_st (vector pixel, int, vector pixel *);
15634 void vec_vsx_st (vector pixel, int, unsigned short *);
15635 void vec_vsx_st (vector pixel, int, short *);
15636 void vec_vsx_st (vector bool short, int, short *);
15637 void vec_vsx_st (vector signed char, int, vector signed char *);
15638 void vec_vsx_st (vector signed char, int, signed char *);
15639 void vec_vsx_st (vector unsigned char, int, vector unsigned char *);
15640 void vec_vsx_st (vector unsigned char, int, unsigned char *);
15641 void vec_vsx_st (vector bool char, int, vector bool char *);
15642 void vec_vsx_st (vector bool char, int, unsigned char *);
15643 void vec_vsx_st (vector bool char, int, signed char *);
15645 vector double vec_xxpermdi (vector double, vector double, int);
15646 vector float vec_xxpermdi (vector float, vector float, int);
15647 vector long long vec_xxpermdi (vector long long, vector long long, int);
15648 vector unsigned long long vec_xxpermdi (vector unsigned long long,
15649 vector unsigned long long, int);
15650 vector int vec_xxpermdi (vector int, vector int, int);
15651 vector unsigned int vec_xxpermdi (vector unsigned int,
15652 vector unsigned int, int);
15653 vector short vec_xxpermdi (vector short, vector short, int);
15654 vector unsigned short vec_xxpermdi (vector unsigned short,
15655 vector unsigned short, int);
15656 vector signed char vec_xxpermdi (vector signed char, vector signed char, int);
15657 vector unsigned char vec_xxpermdi (vector unsigned char,
15658 vector unsigned char, int);
15660 vector double vec_xxsldi (vector double, vector double, int);
15661 vector float vec_xxsldi (vector float, vector float, int);
15662 vector long long vec_xxsldi (vector long long, vector long long, int);
15663 vector unsigned long long vec_xxsldi (vector unsigned long long,
15664 vector unsigned long long, int);
15665 vector int vec_xxsldi (vector int, vector int, int);
15666 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
15667 vector short vec_xxsldi (vector short, vector short, int);
15668 vector unsigned short vec_xxsldi (vector unsigned short,
15669 vector unsigned short, int);
15670 vector signed char vec_xxsldi (vector signed char, vector signed char, int);
15671 vector unsigned char vec_xxsldi (vector unsigned char,
15672 vector unsigned char, int);
15675 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
15676 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even
15677 if the VSX instruction set is available. The @samp{vec_vsx_ld} and
15678 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X},
15679 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions.
15681 If the ISA 2.07 additions to the vector/scalar (power8-vector)
15682 instruction set is available, the following additional functions are
15683 available for both 32-bit and 64-bit targets. For 64-bit targets, you
15684 can use @var{vector long} instead of @var{vector long long},
15685 @var{vector bool long} instead of @var{vector bool long long}, and
15686 @var{vector unsigned long} instead of @var{vector unsigned long long}.
15689 vector long long vec_abs (vector long long);
15691 vector long long vec_add (vector long long, vector long long);
15692 vector unsigned long long vec_add (vector unsigned long long,
15693 vector unsigned long long);
15695 int vec_all_eq (vector long long, vector long long);
15696 int vec_all_eq (vector unsigned long long, vector unsigned long long);
15697 int vec_all_ge (vector long long, vector long long);
15698 int vec_all_ge (vector unsigned long long, vector unsigned long long);
15699 int vec_all_gt (vector long long, vector long long);
15700 int vec_all_gt (vector unsigned long long, vector unsigned long long);
15701 int vec_all_le (vector long long, vector long long);
15702 int vec_all_le (vector unsigned long long, vector unsigned long long);
15703 int vec_all_lt (vector long long, vector long long);
15704 int vec_all_lt (vector unsigned long long, vector unsigned long long);
15705 int vec_all_ne (vector long long, vector long long);
15706 int vec_all_ne (vector unsigned long long, vector unsigned long long);
15708 int vec_any_eq (vector long long, vector long long);
15709 int vec_any_eq (vector unsigned long long, vector unsigned long long);
15710 int vec_any_ge (vector long long, vector long long);
15711 int vec_any_ge (vector unsigned long long, vector unsigned long long);
15712 int vec_any_gt (vector long long, vector long long);
15713 int vec_any_gt (vector unsigned long long, vector unsigned long long);
15714 int vec_any_le (vector long long, vector long long);
15715 int vec_any_le (vector unsigned long long, vector unsigned long long);
15716 int vec_any_lt (vector long long, vector long long);
15717 int vec_any_lt (vector unsigned long long, vector unsigned long long);
15718 int vec_any_ne (vector long long, vector long long);
15719 int vec_any_ne (vector unsigned long long, vector unsigned long long);
15721 vector long long vec_eqv (vector long long, vector long long);
15722 vector long long vec_eqv (vector bool long long, vector long long);
15723 vector long long vec_eqv (vector long long, vector bool long long);
15724 vector unsigned long long vec_eqv (vector unsigned long long,
15725 vector unsigned long long);
15726 vector unsigned long long vec_eqv (vector bool long long,
15727 vector unsigned long long);
15728 vector unsigned long long vec_eqv (vector unsigned long long,
15729 vector bool long long);
15730 vector int vec_eqv (vector int, vector int);
15731 vector int vec_eqv (vector bool int, vector int);
15732 vector int vec_eqv (vector int, vector bool int);
15733 vector unsigned int vec_eqv (vector unsigned int, vector unsigned int);
15734 vector unsigned int vec_eqv (vector bool unsigned int,
15735 vector unsigned int);
15736 vector unsigned int vec_eqv (vector unsigned int,
15737 vector bool unsigned int);
15738 vector short vec_eqv (vector short, vector short);
15739 vector short vec_eqv (vector bool short, vector short);
15740 vector short vec_eqv (vector short, vector bool short);
15741 vector unsigned short vec_eqv (vector unsigned short, vector unsigned short);
15742 vector unsigned short vec_eqv (vector bool unsigned short,
15743 vector unsigned short);
15744 vector unsigned short vec_eqv (vector unsigned short,
15745 vector bool unsigned short);
15746 vector signed char vec_eqv (vector signed char, vector signed char);
15747 vector signed char vec_eqv (vector bool signed char, vector signed char);
15748 vector signed char vec_eqv (vector signed char, vector bool signed char);
15749 vector unsigned char vec_eqv (vector unsigned char, vector unsigned char);
15750 vector unsigned char vec_eqv (vector bool unsigned char, vector unsigned char);
15751 vector unsigned char vec_eqv (vector unsigned char, vector bool unsigned char);
15753 vector long long vec_max (vector long long, vector long long);
15754 vector unsigned long long vec_max (vector unsigned long long,
15755 vector unsigned long long);
15757 vector signed int vec_mergee (vector signed int, vector signed int);
15758 vector unsigned int vec_mergee (vector unsigned int, vector unsigned int);
15759 vector bool int vec_mergee (vector bool int, vector bool int);
15761 vector signed int vec_mergeo (vector signed int, vector signed int);
15762 vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int);
15763 vector bool int vec_mergeo (vector bool int, vector bool int);
15765 vector long long vec_min (vector long long, vector long long);
15766 vector unsigned long long vec_min (vector unsigned long long,
15767 vector unsigned long long);
15769 vector long long vec_nand (vector long long, vector long long);
15770 vector long long vec_nand (vector bool long long, vector long long);
15771 vector long long vec_nand (vector long long, vector bool long long);
15772 vector unsigned long long vec_nand (vector unsigned long long,
15773 vector unsigned long long);
15774 vector unsigned long long vec_nand (vector bool long long,
15775 vector unsigned long long);
15776 vector unsigned long long vec_nand (vector unsigned long long,
15777 vector bool long long);
15778 vector int vec_nand (vector int, vector int);
15779 vector int vec_nand (vector bool int, vector int);
15780 vector int vec_nand (vector int, vector bool int);
15781 vector unsigned int vec_nand (vector unsigned int, vector unsigned int);
15782 vector unsigned int vec_nand (vector bool unsigned int,
15783 vector unsigned int);
15784 vector unsigned int vec_nand (vector unsigned int,
15785 vector bool unsigned int);
15786 vector short vec_nand (vector short, vector short);
15787 vector short vec_nand (vector bool short, vector short);
15788 vector short vec_nand (vector short, vector bool short);
15789 vector unsigned short vec_nand (vector unsigned short, vector unsigned short);
15790 vector unsigned short vec_nand (vector bool unsigned short,
15791 vector unsigned short);
15792 vector unsigned short vec_nand (vector unsigned short,
15793 vector bool unsigned short);
15794 vector signed char vec_nand (vector signed char, vector signed char);
15795 vector signed char vec_nand (vector bool signed char, vector signed char);
15796 vector signed char vec_nand (vector signed char, vector bool signed char);
15797 vector unsigned char vec_nand (vector unsigned char, vector unsigned char);
15798 vector unsigned char vec_nand (vector bool unsigned char, vector unsigned char);
15799 vector unsigned char vec_nand (vector unsigned char, vector bool unsigned char);
15801 vector long long vec_orc (vector long long, vector long long);
15802 vector long long vec_orc (vector bool long long, vector long long);
15803 vector long long vec_orc (vector long long, vector bool long long);
15804 vector unsigned long long vec_orc (vector unsigned long long,
15805 vector unsigned long long);
15806 vector unsigned long long vec_orc (vector bool long long,
15807 vector unsigned long long);
15808 vector unsigned long long vec_orc (vector unsigned long long,
15809 vector bool long long);
15810 vector int vec_orc (vector int, vector int);
15811 vector int vec_orc (vector bool int, vector int);
15812 vector int vec_orc (vector int, vector bool int);
15813 vector unsigned int vec_orc (vector unsigned int, vector unsigned int);
15814 vector unsigned int vec_orc (vector bool unsigned int,
15815 vector unsigned int);
15816 vector unsigned int vec_orc (vector unsigned int,
15817 vector bool unsigned int);
15818 vector short vec_orc (vector short, vector short);
15819 vector short vec_orc (vector bool short, vector short);
15820 vector short vec_orc (vector short, vector bool short);
15821 vector unsigned short vec_orc (vector unsigned short, vector unsigned short);
15822 vector unsigned short vec_orc (vector bool unsigned short,
15823 vector unsigned short);
15824 vector unsigned short vec_orc (vector unsigned short,
15825 vector bool unsigned short);
15826 vector signed char vec_orc (vector signed char, vector signed char);
15827 vector signed char vec_orc (vector bool signed char, vector signed char);
15828 vector signed char vec_orc (vector signed char, vector bool signed char);
15829 vector unsigned char vec_orc (vector unsigned char, vector unsigned char);
15830 vector unsigned char vec_orc (vector bool unsigned char, vector unsigned char);
15831 vector unsigned char vec_orc (vector unsigned char, vector bool unsigned char);
15833 vector int vec_pack (vector long long, vector long long);
15834 vector unsigned int vec_pack (vector unsigned long long,
15835 vector unsigned long long);
15836 vector bool int vec_pack (vector bool long long, vector bool long long);
15838 vector int vec_packs (vector long long, vector long long);
15839 vector unsigned int vec_packs (vector unsigned long long,
15840 vector unsigned long long);
15842 vector unsigned int vec_packsu (vector long long, vector long long);
15843 vector unsigned int vec_packsu (vector unsigned long long,
15844 vector unsigned long long);
15846 vector long long vec_rl (vector long long,
15847 vector unsigned long long);
15848 vector long long vec_rl (vector unsigned long long,
15849 vector unsigned long long);
15851 vector long long vec_sl (vector long long, vector unsigned long long);
15852 vector long long vec_sl (vector unsigned long long,
15853 vector unsigned long long);
15855 vector long long vec_sr (vector long long, vector unsigned long long);
15856 vector unsigned long long char vec_sr (vector unsigned long long,
15857 vector unsigned long long);
15859 vector long long vec_sra (vector long long, vector unsigned long long);
15860 vector unsigned long long vec_sra (vector unsigned long long,
15861 vector unsigned long long);
15863 vector long long vec_sub (vector long long, vector long long);
15864 vector unsigned long long vec_sub (vector unsigned long long,
15865 vector unsigned long long);
15867 vector long long vec_unpackh (vector int);
15868 vector unsigned long long vec_unpackh (vector unsigned int);
15870 vector long long vec_unpackl (vector int);
15871 vector unsigned long long vec_unpackl (vector unsigned int);
15873 vector long long vec_vaddudm (vector long long, vector long long);
15874 vector long long vec_vaddudm (vector bool long long, vector long long);
15875 vector long long vec_vaddudm (vector long long, vector bool long long);
15876 vector unsigned long long vec_vaddudm (vector unsigned long long,
15877 vector unsigned long long);
15878 vector unsigned long long vec_vaddudm (vector bool unsigned long long,
15879 vector unsigned long long);
15880 vector unsigned long long vec_vaddudm (vector unsigned long long,
15881 vector bool unsigned long long);
15883 vector long long vec_vbpermq (vector signed char, vector signed char);
15884 vector long long vec_vbpermq (vector unsigned char, vector unsigned char);
15886 vector long long vec_cntlz (vector long long);
15887 vector unsigned long long vec_cntlz (vector unsigned long long);
15888 vector int vec_cntlz (vector int);
15889 vector unsigned int vec_cntlz (vector int);
15890 vector short vec_cntlz (vector short);
15891 vector unsigned short vec_cntlz (vector unsigned short);
15892 vector signed char vec_cntlz (vector signed char);
15893 vector unsigned char vec_cntlz (vector unsigned char);
15895 vector long long vec_vclz (vector long long);
15896 vector unsigned long long vec_vclz (vector unsigned long long);
15897 vector int vec_vclz (vector int);
15898 vector unsigned int vec_vclz (vector int);
15899 vector short vec_vclz (vector short);
15900 vector unsigned short vec_vclz (vector unsigned short);
15901 vector signed char vec_vclz (vector signed char);
15902 vector unsigned char vec_vclz (vector unsigned char);
15904 vector signed char vec_vclzb (vector signed char);
15905 vector unsigned char vec_vclzb (vector unsigned char);
15907 vector long long vec_vclzd (vector long long);
15908 vector unsigned long long vec_vclzd (vector unsigned long long);
15910 vector short vec_vclzh (vector short);
15911 vector unsigned short vec_vclzh (vector unsigned short);
15913 vector int vec_vclzw (vector int);
15914 vector unsigned int vec_vclzw (vector int);
15916 vector signed char vec_vgbbd (vector signed char);
15917 vector unsigned char vec_vgbbd (vector unsigned char);
15919 vector long long vec_vmaxsd (vector long long, vector long long);
15921 vector unsigned long long vec_vmaxud (vector unsigned long long,
15922 unsigned vector long long);
15924 vector long long vec_vminsd (vector long long, vector long long);
15926 vector unsigned long long vec_vminud (vector long long,
15929 vector int vec_vpksdss (vector long long, vector long long);
15930 vector unsigned int vec_vpksdss (vector long long, vector long long);
15932 vector unsigned int vec_vpkudus (vector unsigned long long,
15933 vector unsigned long long);
15935 vector int vec_vpkudum (vector long long, vector long long);
15936 vector unsigned int vec_vpkudum (vector unsigned long long,
15937 vector unsigned long long);
15938 vector bool int vec_vpkudum (vector bool long long, vector bool long long);
15940 vector long long vec_vpopcnt (vector long long);
15941 vector unsigned long long vec_vpopcnt (vector unsigned long long);
15942 vector int vec_vpopcnt (vector int);
15943 vector unsigned int vec_vpopcnt (vector int);
15944 vector short vec_vpopcnt (vector short);
15945 vector unsigned short vec_vpopcnt (vector unsigned short);
15946 vector signed char vec_vpopcnt (vector signed char);
15947 vector unsigned char vec_vpopcnt (vector unsigned char);
15949 vector signed char vec_vpopcntb (vector signed char);
15950 vector unsigned char vec_vpopcntb (vector unsigned char);
15952 vector long long vec_vpopcntd (vector long long);
15953 vector unsigned long long vec_vpopcntd (vector unsigned long long);
15955 vector short vec_vpopcnth (vector short);
15956 vector unsigned short vec_vpopcnth (vector unsigned short);
15958 vector int vec_vpopcntw (vector int);
15959 vector unsigned int vec_vpopcntw (vector int);
15961 vector long long vec_vrld (vector long long, vector unsigned long long);
15962 vector unsigned long long vec_vrld (vector unsigned long long,
15963 vector unsigned long long);
15965 vector long long vec_vsld (vector long long, vector unsigned long long);
15966 vector long long vec_vsld (vector unsigned long long,
15967 vector unsigned long long);
15969 vector long long vec_vsrad (vector long long, vector unsigned long long);
15970 vector unsigned long long vec_vsrad (vector unsigned long long,
15971 vector unsigned long long);
15973 vector long long vec_vsrd (vector long long, vector unsigned long long);
15974 vector unsigned long long char vec_vsrd (vector unsigned long long,
15975 vector unsigned long long);
15977 vector long long vec_vsubudm (vector long long, vector long long);
15978 vector long long vec_vsubudm (vector bool long long, vector long long);
15979 vector long long vec_vsubudm (vector long long, vector bool long long);
15980 vector unsigned long long vec_vsubudm (vector unsigned long long,
15981 vector unsigned long long);
15982 vector unsigned long long vec_vsubudm (vector bool long long,
15983 vector unsigned long long);
15984 vector unsigned long long vec_vsubudm (vector unsigned long long,
15985 vector bool long long);
15987 vector long long vec_vupkhsw (vector int);
15988 vector unsigned long long vec_vupkhsw (vector unsigned int);
15990 vector long long vec_vupklsw (vector int);
15991 vector unsigned long long vec_vupklsw (vector int);
15994 If the ISA 2.07 additions to the vector/scalar (power8-vector)
15995 instruction set is available, the following additional functions are
15996 available for 64-bit targets. New vector types
15997 (@var{vector __int128_t} and @var{vector __uint128_t}) are available
15998 to hold the @var{__int128_t} and @var{__uint128_t} types to use these
16001 The normal vector extract, and set operations work on
16002 @var{vector __int128_t} and @var{vector __uint128_t} types,
16003 but the index value must be 0.
16006 vector __int128_t vec_vaddcuq (vector __int128_t, vector __int128_t);
16007 vector __uint128_t vec_vaddcuq (vector __uint128_t, vector __uint128_t);
16009 vector __int128_t vec_vadduqm (vector __int128_t, vector __int128_t);
16010 vector __uint128_t vec_vadduqm (vector __uint128_t, vector __uint128_t);
16012 vector __int128_t vec_vaddecuq (vector __int128_t, vector __int128_t,
16013 vector __int128_t);
16014 vector __uint128_t vec_vaddecuq (vector __uint128_t, vector __uint128_t,
16015 vector __uint128_t);
16017 vector __int128_t vec_vaddeuqm (vector __int128_t, vector __int128_t,
16018 vector __int128_t);
16019 vector __uint128_t vec_vaddeuqm (vector __uint128_t, vector __uint128_t,
16020 vector __uint128_t);
16022 vector __int128_t vec_vsubecuq (vector __int128_t, vector __int128_t,
16023 vector __int128_t);
16024 vector __uint128_t vec_vsubecuq (vector __uint128_t, vector __uint128_t,
16025 vector __uint128_t);
16027 vector __int128_t vec_vsubeuqm (vector __int128_t, vector __int128_t,
16028 vector __int128_t);
16029 vector __uint128_t vec_vsubeuqm (vector __uint128_t, vector __uint128_t,
16030 vector __uint128_t);
16032 vector __int128_t vec_vsubcuq (vector __int128_t, vector __int128_t);
16033 vector __uint128_t vec_vsubcuq (vector __uint128_t, vector __uint128_t);
16035 __int128_t vec_vsubuqm (__int128_t, __int128_t);
16036 __uint128_t vec_vsubuqm (__uint128_t, __uint128_t);
16038 vector __int128_t __builtin_bcdadd (vector __int128_t, vector__int128_t);
16039 int __builtin_bcdadd_lt (vector __int128_t, vector__int128_t);
16040 int __builtin_bcdadd_eq (vector __int128_t, vector__int128_t);
16041 int __builtin_bcdadd_gt (vector __int128_t, vector__int128_t);
16042 int __builtin_bcdadd_ov (vector __int128_t, vector__int128_t);
16043 vector __int128_t bcdsub (vector __int128_t, vector__int128_t);
16044 int __builtin_bcdsub_lt (vector __int128_t, vector__int128_t);
16045 int __builtin_bcdsub_eq (vector __int128_t, vector__int128_t);
16046 int __builtin_bcdsub_gt (vector __int128_t, vector__int128_t);
16047 int __builtin_bcdsub_ov (vector __int128_t, vector__int128_t);
16050 If the cryptographic instructions are enabled (@option{-mcrypto} or
16051 @option{-mcpu=power8}), the following builtins are enabled.
16054 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long);
16056 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long,
16057 vector unsigned long long);
16059 vector unsigned long long __builtin_crypto_vcipherlast
16060 (vector unsigned long long,
16061 vector unsigned long long);
16063 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long,
16064 vector unsigned long long);
16066 vector unsigned long long __builtin_crypto_vncipherlast
16067 (vector unsigned long long,
16068 vector unsigned long long);
16070 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char,
16071 vector unsigned char,
16072 vector unsigned char);
16074 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short,
16075 vector unsigned short,
16076 vector unsigned short);
16078 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int,
16079 vector unsigned int,
16080 vector unsigned int);
16082 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long,
16083 vector unsigned long long,
16084 vector unsigned long long);
16086 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char,
16087 vector unsigned char);
16089 vector unsigned short __builtin_crypto_vpmsumb (vector unsigned short,
16090 vector unsigned short);
16092 vector unsigned int __builtin_crypto_vpmsumb (vector unsigned int,
16093 vector unsigned int);
16095 vector unsigned long long __builtin_crypto_vpmsumb (vector unsigned long long,
16096 vector unsigned long long);
16098 vector unsigned long long __builtin_crypto_vshasigmad
16099 (vector unsigned long long, int, int);
16101 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int,
16105 The second argument to the @var{__builtin_crypto_vshasigmad} and
16106 @var{__builtin_crypto_vshasigmaw} builtin functions must be a constant
16107 integer that is 0 or 1. The third argument to these builtin functions
16108 must be a constant integer in the range of 0 to 15.
16110 @node PowerPC Hardware Transactional Memory Built-in Functions
16111 @subsection PowerPC Hardware Transactional Memory Built-in Functions
16112 GCC provides two interfaces for accessing the Hardware Transactional
16113 Memory (HTM) instructions available on some of the PowerPC family
16114 of prcoessors (eg, POWER8). The two interfaces come in a low level
16115 interface, consisting of built-in functions specific to PowerPC and a
16116 higher level interface consisting of inline functions that are common
16117 between PowerPC and S/390.
16119 @subsubsection PowerPC HTM Low Level Built-in Functions
16121 The following low level built-in functions are available with
16122 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
16123 They all generate the machine instruction that is part of the name.
16125 The HTM built-ins return true or false depending on their success and
16126 their arguments match exactly the type and order of the associated
16127 hardware instruction's operands. Refer to the ISA manual for a
16128 description of each instruction's operands.
16131 unsigned int __builtin_tbegin (unsigned int)
16132 unsigned int __builtin_tend (unsigned int)
16134 unsigned int __builtin_tabort (unsigned int)
16135 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int)
16136 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int)
16137 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int)
16138 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int)
16140 unsigned int __builtin_tcheck (unsigned int)
16141 unsigned int __builtin_treclaim (unsigned int)
16142 unsigned int __builtin_trechkpt (void)
16143 unsigned int __builtin_tsr (unsigned int)
16146 In addition to the above HTM built-ins, we have added built-ins for
16147 some common extended mnemonics of the HTM instructions:
16150 unsigned int __builtin_tendall (void)
16151 unsigned int __builtin_tresume (void)
16152 unsigned int __builtin_tsuspend (void)
16155 The following set of built-in functions are available to gain access
16156 to the HTM specific special purpose registers.
16159 unsigned long __builtin_get_texasr (void)
16160 unsigned long __builtin_get_texasru (void)
16161 unsigned long __builtin_get_tfhar (void)
16162 unsigned long __builtin_get_tfiar (void)
16164 void __builtin_set_texasr (unsigned long);
16165 void __builtin_set_texasru (unsigned long);
16166 void __builtin_set_tfhar (unsigned long);
16167 void __builtin_set_tfiar (unsigned long);
16170 Example usage of these low level built-in functions may look like:
16173 #include <htmintrin.h>
16175 int num_retries = 10;
16179 if (__builtin_tbegin (0))
16181 /* Transaction State Initiated. */
16182 if (is_locked (lock))
16183 __builtin_tabort (0);
16184 ... transaction code...
16185 __builtin_tend (0);
16190 /* Transaction State Failed. Use locks if the transaction
16191 failure is "persistent" or we've tried too many times. */
16192 if (num_retries-- <= 0
16193 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ()))
16195 acquire_lock (lock);
16196 ... non transactional fallback path...
16197 release_lock (lock);
16204 One final built-in function has been added that returns the value of
16205 the 2-bit Transaction State field of the Machine Status Register (MSR)
16206 as stored in @code{CR0}.
16209 unsigned long __builtin_ttest (void)
16212 This built-in can be used to determine the current transaction state
16213 using the following code example:
16216 #include <htmintrin.h>
16218 unsigned char tx_state = _HTM_STATE (__builtin_ttest ());
16220 if (tx_state == _HTM_TRANSACTIONAL)
16222 /* Code to use in transactional state. */
16224 else if (tx_state == _HTM_NONTRANSACTIONAL)
16226 /* Code to use in non-transactional state. */
16228 else if (tx_state == _HTM_SUSPENDED)
16230 /* Code to use in transaction suspended state. */
16234 @subsubsection PowerPC HTM High Level Inline Functions
16236 The following high level HTM interface is made available by including
16237 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU}
16238 where CPU is `power8' or later. This interface is common between PowerPC
16239 and S/390, allowing users to write one HTM source implementation that
16240 can be compiled and executed on either system.
16243 long __TM_simple_begin (void)
16244 long __TM_begin (void* const TM_buff)
16245 long __TM_end (void)
16246 void __TM_abort (void)
16247 void __TM_named_abort (unsigned char const code)
16248 void __TM_resume (void)
16249 void __TM_suspend (void)
16251 long __TM_is_user_abort (void* const TM_buff)
16252 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code)
16253 long __TM_is_illegal (void* const TM_buff)
16254 long __TM_is_footprint_exceeded (void* const TM_buff)
16255 long __TM_nesting_depth (void* const TM_buff)
16256 long __TM_is_nested_too_deep(void* const TM_buff)
16257 long __TM_is_conflict(void* const TM_buff)
16258 long __TM_is_failure_persistent(void* const TM_buff)
16259 long __TM_failure_address(void* const TM_buff)
16260 long long __TM_failure_code(void* const TM_buff)
16263 Using these common set of HTM inline functions, we can create
16264 a more portable version of the HTM example in the previous
16265 section that will work on either PowerPC or S/390:
16268 #include <htmxlintrin.h>
16270 int num_retries = 10;
16271 TM_buff_type TM_buff;
16275 if (__TM_begin (TM_buff))
16277 /* Transaction State Initiated. */
16278 if (is_locked (lock))
16280 ... transaction code...
16286 /* Transaction State Failed. Use locks if the transaction
16287 failure is "persistent" or we've tried too many times. */
16288 if (num_retries-- <= 0
16289 || __TM_is_failure_persistent (TM_buff))
16291 acquire_lock (lock);
16292 ... non transactional fallback path...
16293 release_lock (lock);
16300 @node RX Built-in Functions
16301 @subsection RX Built-in Functions
16302 GCC supports some of the RX instructions which cannot be expressed in
16303 the C programming language via the use of built-in functions. The
16304 following functions are supported:
16306 @deftypefn {Built-in Function} void __builtin_rx_brk (void)
16307 Generates the @code{brk} machine instruction.
16310 @deftypefn {Built-in Function} void __builtin_rx_clrpsw (int)
16311 Generates the @code{clrpsw} machine instruction to clear the specified
16312 bit in the processor status word.
16315 @deftypefn {Built-in Function} void __builtin_rx_int (int)
16316 Generates the @code{int} machine instruction to generate an interrupt
16317 with the specified value.
16320 @deftypefn {Built-in Function} void __builtin_rx_machi (int, int)
16321 Generates the @code{machi} machine instruction to add the result of
16322 multiplying the top 16 bits of the two arguments into the
16326 @deftypefn {Built-in Function} void __builtin_rx_maclo (int, int)
16327 Generates the @code{maclo} machine instruction to add the result of
16328 multiplying the bottom 16 bits of the two arguments into the
16332 @deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int)
16333 Generates the @code{mulhi} machine instruction to place the result of
16334 multiplying the top 16 bits of the two arguments into the
16338 @deftypefn {Built-in Function} void __builtin_rx_mullo (int, int)
16339 Generates the @code{mullo} machine instruction to place the result of
16340 multiplying the bottom 16 bits of the two arguments into the
16344 @deftypefn {Built-in Function} int __builtin_rx_mvfachi (void)
16345 Generates the @code{mvfachi} machine instruction to read the top
16346 32 bits of the accumulator.
16349 @deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void)
16350 Generates the @code{mvfacmi} machine instruction to read the middle
16351 32 bits of the accumulator.
16354 @deftypefn {Built-in Function} int __builtin_rx_mvfc (int)
16355 Generates the @code{mvfc} machine instruction which reads the control
16356 register specified in its argument and returns its value.
16359 @deftypefn {Built-in Function} void __builtin_rx_mvtachi (int)
16360 Generates the @code{mvtachi} machine instruction to set the top
16361 32 bits of the accumulator.
16364 @deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int)
16365 Generates the @code{mvtaclo} machine instruction to set the bottom
16366 32 bits of the accumulator.
16369 @deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val)
16370 Generates the @code{mvtc} machine instruction which sets control
16371 register number @code{reg} to @code{val}.
16374 @deftypefn {Built-in Function} void __builtin_rx_mvtipl (int)
16375 Generates the @code{mvtipl} machine instruction set the interrupt
16379 @deftypefn {Built-in Function} void __builtin_rx_racw (int)
16380 Generates the @code{racw} machine instruction to round the accumulator
16381 according to the specified mode.
16384 @deftypefn {Built-in Function} int __builtin_rx_revw (int)
16385 Generates the @code{revw} machine instruction which swaps the bytes in
16386 the argument so that bits 0--7 now occupy bits 8--15 and vice versa,
16387 and also bits 16--23 occupy bits 24--31 and vice versa.
16390 @deftypefn {Built-in Function} void __builtin_rx_rmpa (void)
16391 Generates the @code{rmpa} machine instruction which initiates a
16392 repeated multiply and accumulate sequence.
16395 @deftypefn {Built-in Function} void __builtin_rx_round (float)
16396 Generates the @code{round} machine instruction which returns the
16397 floating-point argument rounded according to the current rounding mode
16398 set in the floating-point status word register.
16401 @deftypefn {Built-in Function} int __builtin_rx_sat (int)
16402 Generates the @code{sat} machine instruction which returns the
16403 saturated value of the argument.
16406 @deftypefn {Built-in Function} void __builtin_rx_setpsw (int)
16407 Generates the @code{setpsw} machine instruction to set the specified
16408 bit in the processor status word.
16411 @deftypefn {Built-in Function} void __builtin_rx_wait (void)
16412 Generates the @code{wait} machine instruction.
16415 @node S/390 System z Built-in Functions
16416 @subsection S/390 System z Built-in Functions
16417 @deftypefn {Built-in Function} int __builtin_tbegin (void*)
16418 Generates the @code{tbegin} machine instruction starting a
16419 non-constraint hardware transaction. If the parameter is non-NULL the
16420 memory area is used to store the transaction diagnostic buffer and
16421 will be passed as first operand to @code{tbegin}. This buffer can be
16422 defined using the @code{struct __htm_tdb} C struct defined in
16423 @code{htmintrin.h} and must reside on a double-word boundary. The
16424 second tbegin operand is set to @code{0xff0c}. This enables
16425 save/restore of all GPRs and disables aborts for FPR and AR
16426 manipulations inside the transaction body. The condition code set by
16427 the tbegin instruction is returned as integer value. The tbegin
16428 instruction by definition overwrites the content of all FPRs. The
16429 compiler will generate code which saves and restores the FPRs. For
16430 soft-float code it is recommended to used the @code{*_nofloat}
16431 variant. In order to prevent a TDB from being written it is required
16432 to pass an constant zero value as parameter. Passing the zero value
16433 through a variable is not sufficient. Although modifications of
16434 access registers inside the transaction will not trigger an
16435 transaction abort it is not supported to actually modify them. Access
16436 registers do not get saved when entering a transaction. They will have
16437 undefined state when reaching the abort code.
16440 Macros for the possible return codes of tbegin are defined in the
16441 @code{htmintrin.h} header file:
16444 @item _HTM_TBEGIN_STARTED
16445 @code{tbegin} has been executed as part of normal processing. The
16446 transaction body is supposed to be executed.
16447 @item _HTM_TBEGIN_INDETERMINATE
16448 The transaction was aborted due to an indeterminate condition which
16449 might be persistent.
16450 @item _HTM_TBEGIN_TRANSIENT
16451 The transaction aborted due to a transient failure. The transaction
16452 should be re-executed in that case.
16453 @item _HTM_TBEGIN_PERSISTENT
16454 The transaction aborted due to a persistent failure. Re-execution
16455 under same circumstances will not be productive.
16458 @defmac _HTM_FIRST_USER_ABORT_CODE
16459 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h}
16460 specifies the first abort code which can be used for
16461 @code{__builtin_tabort}. Values below this threshold are reserved for
16465 @deftp {Data type} {struct __htm_tdb}
16466 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes
16467 the structure of the transaction diagnostic block as specified in the
16468 Principles of Operation manual chapter 5-91.
16471 @deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*)
16472 Same as @code{__builtin_tbegin} but without FPR saves and restores.
16473 Using this variant in code making use of FPRs will leave the FPRs in
16474 undefined state when entering the transaction abort handler code.
16477 @deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int)
16478 In addition to @code{__builtin_tbegin} a loop for transient failures
16479 is generated. If tbegin returns a condition code of 2 the transaction
16480 will be retried as often as specified in the second argument. The
16481 perform processor assist instruction is used to tell the CPU about the
16482 number of fails so far.
16485 @deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int)
16486 Same as @code{__builtin_tbegin_retry} but without FPR saves and
16487 restores. Using this variant in code making use of FPRs will leave
16488 the FPRs in undefined state when entering the transaction abort
16492 @deftypefn {Built-in Function} void __builtin_tbeginc (void)
16493 Generates the @code{tbeginc} machine instruction starting a constraint
16494 hardware transaction. The second operand is set to @code{0xff08}.
16497 @deftypefn {Built-in Function} int __builtin_tend (void)
16498 Generates the @code{tend} machine instruction finishing a transaction
16499 and making the changes visible to other threads. The condition code
16500 generated by tend is returned as integer value.
16503 @deftypefn {Built-in Function} void __builtin_tabort (int)
16504 Generates the @code{tabort} machine instruction with the specified
16505 abort code. Abort codes from 0 through 255 are reserved and will
16506 result in an error message.
16509 @deftypefn {Built-in Function} void __builtin_tx_assist (int)
16510 Generates the @code{ppa rX,rY,1} machine instruction. Where the
16511 integer parameter is loaded into rX and a value of zero is loaded into
16512 rY. The integer parameter specifies the number of times the
16513 transaction repeatedly aborted.
16516 @deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void)
16517 Generates the @code{etnd} machine instruction. The current nesting
16518 depth is returned as integer value. For a nesting depth of 0 the code
16519 is not executed as part of an transaction.
16522 @deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t)
16524 Generates the @code{ntstg} machine instruction. The second argument
16525 is written to the first arguments location. The store operation will
16526 not be rolled-back in case of an transaction abort.
16529 @node SH Built-in Functions
16530 @subsection SH Built-in Functions
16531 The following built-in functions are supported on the SH1, SH2, SH3 and SH4
16532 families of processors:
16534 @deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr})
16535 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually
16536 used by system code that manages threads and execution contexts. The compiler
16537 normally does not generate code that modifies the contents of @samp{GBR} and
16538 thus the value is preserved across function calls. Changing the @samp{GBR}
16539 value in user code must be done with caution, since the compiler might use
16540 @samp{GBR} in order to access thread local variables.
16544 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void)
16545 Returns the value that is currently set in the @samp{GBR} register.
16546 Memory loads and stores that use the thread pointer as a base address are
16547 turned into @samp{GBR} based displacement loads and stores, if possible.
16555 int get_tcb_value (void)
16557 // Generate @samp{mov.l @@(8,gbr),r0} instruction
16558 return ((my_tcb*)__builtin_thread_pointer ())->c;
16564 @node SPARC VIS Built-in Functions
16565 @subsection SPARC VIS Built-in Functions
16567 GCC supports SIMD operations on the SPARC using both the generic vector
16568 extensions (@pxref{Vector Extensions}) as well as built-in functions for
16569 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis}
16570 switch, the VIS extension is exposed as the following built-in functions:
16573 typedef int v1si __attribute__ ((vector_size (4)));
16574 typedef int v2si __attribute__ ((vector_size (8)));
16575 typedef short v4hi __attribute__ ((vector_size (8)));
16576 typedef short v2hi __attribute__ ((vector_size (4)));
16577 typedef unsigned char v8qi __attribute__ ((vector_size (8)));
16578 typedef unsigned char v4qi __attribute__ ((vector_size (4)));
16580 void __builtin_vis_write_gsr (int64_t);
16581 int64_t __builtin_vis_read_gsr (void);
16583 void * __builtin_vis_alignaddr (void *, long);
16584 void * __builtin_vis_alignaddrl (void *, long);
16585 int64_t __builtin_vis_faligndatadi (int64_t, int64_t);
16586 v2si __builtin_vis_faligndatav2si (v2si, v2si);
16587 v4hi __builtin_vis_faligndatav4hi (v4si, v4si);
16588 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi);
16590 v4hi __builtin_vis_fexpand (v4qi);
16592 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi);
16593 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi);
16594 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi);
16595 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi);
16596 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi);
16597 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi);
16598 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi);
16600 v4qi __builtin_vis_fpack16 (v4hi);
16601 v8qi __builtin_vis_fpack32 (v2si, v8qi);
16602 v2hi __builtin_vis_fpackfix (v2si);
16603 v8qi __builtin_vis_fpmerge (v4qi, v4qi);
16605 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t);
16607 long __builtin_vis_edge8 (void *, void *);
16608 long __builtin_vis_edge8l (void *, void *);
16609 long __builtin_vis_edge16 (void *, void *);
16610 long __builtin_vis_edge16l (void *, void *);
16611 long __builtin_vis_edge32 (void *, void *);
16612 long __builtin_vis_edge32l (void *, void *);
16614 long __builtin_vis_fcmple16 (v4hi, v4hi);
16615 long __builtin_vis_fcmple32 (v2si, v2si);
16616 long __builtin_vis_fcmpne16 (v4hi, v4hi);
16617 long __builtin_vis_fcmpne32 (v2si, v2si);
16618 long __builtin_vis_fcmpgt16 (v4hi, v4hi);
16619 long __builtin_vis_fcmpgt32 (v2si, v2si);
16620 long __builtin_vis_fcmpeq16 (v4hi, v4hi);
16621 long __builtin_vis_fcmpeq32 (v2si, v2si);
16623 v4hi __builtin_vis_fpadd16 (v4hi, v4hi);
16624 v2hi __builtin_vis_fpadd16s (v2hi, v2hi);
16625 v2si __builtin_vis_fpadd32 (v2si, v2si);
16626 v1si __builtin_vis_fpadd32s (v1si, v1si);
16627 v4hi __builtin_vis_fpsub16 (v4hi, v4hi);
16628 v2hi __builtin_vis_fpsub16s (v2hi, v2hi);
16629 v2si __builtin_vis_fpsub32 (v2si, v2si);
16630 v1si __builtin_vis_fpsub32s (v1si, v1si);
16632 long __builtin_vis_array8 (long, long);
16633 long __builtin_vis_array16 (long, long);
16634 long __builtin_vis_array32 (long, long);
16637 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in
16638 functions also become available:
16641 long __builtin_vis_bmask (long, long);
16642 int64_t __builtin_vis_bshuffledi (int64_t, int64_t);
16643 v2si __builtin_vis_bshufflev2si (v2si, v2si);
16644 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi);
16645 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi);
16647 long __builtin_vis_edge8n (void *, void *);
16648 long __builtin_vis_edge8ln (void *, void *);
16649 long __builtin_vis_edge16n (void *, void *);
16650 long __builtin_vis_edge16ln (void *, void *);
16651 long __builtin_vis_edge32n (void *, void *);
16652 long __builtin_vis_edge32ln (void *, void *);
16655 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in
16656 functions also become available:
16659 void __builtin_vis_cmask8 (long);
16660 void __builtin_vis_cmask16 (long);
16661 void __builtin_vis_cmask32 (long);
16663 v4hi __builtin_vis_fchksm16 (v4hi, v4hi);
16665 v4hi __builtin_vis_fsll16 (v4hi, v4hi);
16666 v4hi __builtin_vis_fslas16 (v4hi, v4hi);
16667 v4hi __builtin_vis_fsrl16 (v4hi, v4hi);
16668 v4hi __builtin_vis_fsra16 (v4hi, v4hi);
16669 v2si __builtin_vis_fsll16 (v2si, v2si);
16670 v2si __builtin_vis_fslas16 (v2si, v2si);
16671 v2si __builtin_vis_fsrl16 (v2si, v2si);
16672 v2si __builtin_vis_fsra16 (v2si, v2si);
16674 long __builtin_vis_pdistn (v8qi, v8qi);
16676 v4hi __builtin_vis_fmean16 (v4hi, v4hi);
16678 int64_t __builtin_vis_fpadd64 (int64_t, int64_t);
16679 int64_t __builtin_vis_fpsub64 (int64_t, int64_t);
16681 v4hi __builtin_vis_fpadds16 (v4hi, v4hi);
16682 v2hi __builtin_vis_fpadds16s (v2hi, v2hi);
16683 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi);
16684 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi);
16685 v2si __builtin_vis_fpadds32 (v2si, v2si);
16686 v1si __builtin_vis_fpadds32s (v1si, v1si);
16687 v2si __builtin_vis_fpsubs32 (v2si, v2si);
16688 v1si __builtin_vis_fpsubs32s (v1si, v1si);
16690 long __builtin_vis_fucmple8 (v8qi, v8qi);
16691 long __builtin_vis_fucmpne8 (v8qi, v8qi);
16692 long __builtin_vis_fucmpgt8 (v8qi, v8qi);
16693 long __builtin_vis_fucmpeq8 (v8qi, v8qi);
16695 float __builtin_vis_fhadds (float, float);
16696 double __builtin_vis_fhaddd (double, double);
16697 float __builtin_vis_fhsubs (float, float);
16698 double __builtin_vis_fhsubd (double, double);
16699 float __builtin_vis_fnhadds (float, float);
16700 double __builtin_vis_fnhaddd (double, double);
16702 int64_t __builtin_vis_umulxhi (int64_t, int64_t);
16703 int64_t __builtin_vis_xmulx (int64_t, int64_t);
16704 int64_t __builtin_vis_xmulxhi (int64_t, int64_t);
16707 @node SPU Built-in Functions
16708 @subsection SPU Built-in Functions
16710 GCC provides extensions for the SPU processor as described in the
16711 Sony/Toshiba/IBM SPU Language Extensions Specification, which can be
16712 found at @uref{http://cell.scei.co.jp/} or
16713 @uref{http://www.ibm.com/developerworks/power/cell/}. GCC's
16714 implementation differs in several ways.
16719 The optional extension of specifying vector constants in parentheses is
16723 A vector initializer requires no cast if the vector constant is of the
16724 same type as the variable it is initializing.
16727 If @code{signed} or @code{unsigned} is omitted, the signedness of the
16728 vector type is the default signedness of the base type. The default
16729 varies depending on the operating system, so a portable program should
16730 always specify the signedness.
16733 By default, the keyword @code{__vector} is added. The macro
16734 @code{vector} is defined in @code{<spu_intrinsics.h>} and can be
16738 GCC allows using a @code{typedef} name as the type specifier for a
16742 For C, overloaded functions are implemented with macros so the following
16746 spu_add ((vector signed int)@{1, 2, 3, 4@}, foo);
16750 Since @code{spu_add} is a macro, the vector constant in the example
16751 is treated as four separate arguments. Wrap the entire argument in
16752 parentheses for this to work.
16755 The extended version of @code{__builtin_expect} is not supported.
16759 @emph{Note:} Only the interface described in the aforementioned
16760 specification is supported. Internally, GCC uses built-in functions to
16761 implement the required functionality, but these are not supported and
16762 are subject to change without notice.
16764 @node TI C6X Built-in Functions
16765 @subsection TI C6X Built-in Functions
16767 GCC provides intrinsics to access certain instructions of the TI C6X
16768 processors. These intrinsics, listed below, are available after
16769 inclusion of the @code{c6x_intrinsics.h} header file. They map directly
16770 to C6X instructions.
16774 int _sadd (int, int)
16775 int _ssub (int, int)
16776 int _sadd2 (int, int)
16777 int _ssub2 (int, int)
16778 long long _mpy2 (int, int)
16779 long long _smpy2 (int, int)
16780 int _add4 (int, int)
16781 int _sub4 (int, int)
16782 int _saddu4 (int, int)
16784 int _smpy (int, int)
16785 int _smpyh (int, int)
16786 int _smpyhl (int, int)
16787 int _smpylh (int, int)
16789 int _sshl (int, int)
16790 int _subc (int, int)
16792 int _avg2 (int, int)
16793 int _avgu4 (int, int)
16795 int _clrr (int, int)
16796 int _extr (int, int)
16797 int _extru (int, int)
16803 @node TILE-Gx Built-in Functions
16804 @subsection TILE-Gx Built-in Functions
16806 GCC provides intrinsics to access every instruction of the TILE-Gx
16807 processor. The intrinsics are of the form:
16811 unsigned long long __insn_@var{op} (...)
16815 Where @var{op} is the name of the instruction. Refer to the ISA manual
16816 for the complete list of instructions.
16818 GCC also provides intrinsics to directly access the network registers.
16819 The intrinsics are:
16823 unsigned long long __tile_idn0_receive (void)
16824 unsigned long long __tile_idn1_receive (void)
16825 unsigned long long __tile_udn0_receive (void)
16826 unsigned long long __tile_udn1_receive (void)
16827 unsigned long long __tile_udn2_receive (void)
16828 unsigned long long __tile_udn3_receive (void)
16829 void __tile_idn_send (unsigned long long)
16830 void __tile_udn_send (unsigned long long)
16834 The intrinsic @code{void __tile_network_barrier (void)} is used to
16835 guarantee that no network operations before it are reordered with
16838 @node TILEPro Built-in Functions
16839 @subsection TILEPro Built-in Functions
16841 GCC provides intrinsics to access every instruction of the TILEPro
16842 processor. The intrinsics are of the form:
16846 unsigned __insn_@var{op} (...)
16851 where @var{op} is the name of the instruction. Refer to the ISA manual
16852 for the complete list of instructions.
16854 GCC also provides intrinsics to directly access the network registers.
16855 The intrinsics are:
16859 unsigned __tile_idn0_receive (void)
16860 unsigned __tile_idn1_receive (void)
16861 unsigned __tile_sn_receive (void)
16862 unsigned __tile_udn0_receive (void)
16863 unsigned __tile_udn1_receive (void)
16864 unsigned __tile_udn2_receive (void)
16865 unsigned __tile_udn3_receive (void)
16866 void __tile_idn_send (unsigned)
16867 void __tile_sn_send (unsigned)
16868 void __tile_udn_send (unsigned)
16872 The intrinsic @code{void __tile_network_barrier (void)} is used to
16873 guarantee that no network operations before it are reordered with
16876 @node Target Format Checks
16877 @section Format Checks Specific to Particular Target Machines
16879 For some target machines, GCC supports additional options to the
16881 (@pxref{Function Attributes,,Declaring Attributes of Functions}).
16884 * Solaris Format Checks::
16885 * Darwin Format Checks::
16888 @node Solaris Format Checks
16889 @subsection Solaris Format Checks
16891 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format
16892 check. @code{cmn_err} accepts a subset of the standard @code{printf}
16893 conversions, and the two-argument @code{%b} conversion for displaying
16894 bit-fields. See the Solaris man page for @code{cmn_err} for more information.
16896 @node Darwin Format Checks
16897 @subsection Darwin Format Checks
16899 Darwin targets support the @code{CFString} (or @code{__CFString__}) in the format
16900 attribute context. Declarations made with such attribution are parsed for correct syntax
16901 and format argument types. However, parsing of the format string itself is currently undefined
16902 and is not carried out by this version of the compiler.
16904 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may
16905 also be used as format arguments. Note that the relevant headers are only likely to be
16906 available on Darwin (OSX) installations. On such installations, the XCode and system
16907 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and
16908 associated functions.
16911 @section Pragmas Accepted by GCC
16913 @cindex @code{#pragma}
16915 GCC supports several types of pragmas, primarily in order to compile
16916 code originally written for other compilers. Note that in general
16917 we do not recommend the use of pragmas; @xref{Function Attributes},
16918 for further explanation.
16924 * RS/6000 and PowerPC Pragmas::
16926 * Solaris Pragmas::
16927 * Symbol-Renaming Pragmas::
16928 * Structure-Packing Pragmas::
16930 * Diagnostic Pragmas::
16931 * Visibility Pragmas::
16932 * Push/Pop Macro Pragmas::
16933 * Function Specific Option Pragmas::
16934 * Loop-Specific Pragmas::
16938 @subsection ARM Pragmas
16940 The ARM target defines pragmas for controlling the default addition of
16941 @code{long_call} and @code{short_call} attributes to functions.
16942 @xref{Function Attributes}, for information about the effects of these
16947 @cindex pragma, long_calls
16948 Set all subsequent functions to have the @code{long_call} attribute.
16950 @item no_long_calls
16951 @cindex pragma, no_long_calls
16952 Set all subsequent functions to have the @code{short_call} attribute.
16954 @item long_calls_off
16955 @cindex pragma, long_calls_off
16956 Do not affect the @code{long_call} or @code{short_call} attributes of
16957 subsequent functions.
16961 @subsection M32C Pragmas
16964 @item GCC memregs @var{number}
16965 @cindex pragma, memregs
16966 Overrides the command-line option @code{-memregs=} for the current
16967 file. Use with care! This pragma must be before any function in the
16968 file, and mixing different memregs values in different objects may
16969 make them incompatible. This pragma is useful when a
16970 performance-critical function uses a memreg for temporary values,
16971 as it may allow you to reduce the number of memregs used.
16973 @item ADDRESS @var{name} @var{address}
16974 @cindex pragma, address
16975 For any declared symbols matching @var{name}, this does three things
16976 to that symbol: it forces the symbol to be located at the given
16977 address (a number), it forces the symbol to be volatile, and it
16978 changes the symbol's scope to be static. This pragma exists for
16979 compatibility with other compilers, but note that the common
16980 @code{1234H} numeric syntax is not supported (use @code{0x1234}
16984 #pragma ADDRESS port3 0x103
16991 @subsection MeP Pragmas
16995 @item custom io_volatile (on|off)
16996 @cindex pragma, custom io_volatile
16997 Overrides the command-line option @code{-mio-volatile} for the current
16998 file. Note that for compatibility with future GCC releases, this
16999 option should only be used once before any @code{io} variables in each
17002 @item GCC coprocessor available @var{registers}
17003 @cindex pragma, coprocessor available
17004 Specifies which coprocessor registers are available to the register
17005 allocator. @var{registers} may be a single register, register range
17006 separated by ellipses, or comma-separated list of those. Example:
17009 #pragma GCC coprocessor available $c0...$c10, $c28
17012 @item GCC coprocessor call_saved @var{registers}
17013 @cindex pragma, coprocessor call_saved
17014 Specifies which coprocessor registers are to be saved and restored by
17015 any function using them. @var{registers} may be a single register,
17016 register range separated by ellipses, or comma-separated list of
17020 #pragma GCC coprocessor call_saved $c4...$c6, $c31
17023 @item GCC coprocessor subclass '(A|B|C|D)' = @var{registers}
17024 @cindex pragma, coprocessor subclass
17025 Creates and defines a register class. These register classes can be
17026 used by inline @code{asm} constructs. @var{registers} may be a single
17027 register, register range separated by ellipses, or comma-separated
17028 list of those. Example:
17031 #pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6
17033 asm ("cpfoo %0" : "=B" (x));
17036 @item GCC disinterrupt @var{name} , @var{name} @dots{}
17037 @cindex pragma, disinterrupt
17038 For the named functions, the compiler adds code to disable interrupts
17039 for the duration of those functions. If any functions so named
17040 are not encountered in the source, a warning is emitted that the pragma is
17041 not used. Examples:
17044 #pragma disinterrupt foo
17045 #pragma disinterrupt bar, grill
17046 int foo () @{ @dots{} @}
17049 @item GCC call @var{name} , @var{name} @dots{}
17050 @cindex pragma, call
17051 For the named functions, the compiler always uses a register-indirect
17052 call model when calling the named functions. Examples:
17061 @node RS/6000 and PowerPC Pragmas
17062 @subsection RS/6000 and PowerPC Pragmas
17064 The RS/6000 and PowerPC targets define one pragma for controlling
17065 whether or not the @code{longcall} attribute is added to function
17066 declarations by default. This pragma overrides the @option{-mlongcall}
17067 option, but not the @code{longcall} and @code{shortcall} attributes.
17068 @xref{RS/6000 and PowerPC Options}, for more information about when long
17069 calls are and are not necessary.
17073 @cindex pragma, longcall
17074 Apply the @code{longcall} attribute to all subsequent function
17078 Do not apply the @code{longcall} attribute to subsequent function
17082 @c Describe h8300 pragmas here.
17083 @c Describe sh pragmas here.
17084 @c Describe v850 pragmas here.
17086 @node Darwin Pragmas
17087 @subsection Darwin Pragmas
17089 The following pragmas are available for all architectures running the
17090 Darwin operating system. These are useful for compatibility with other
17094 @item mark @var{tokens}@dots{}
17095 @cindex pragma, mark
17096 This pragma is accepted, but has no effect.
17098 @item options align=@var{alignment}
17099 @cindex pragma, options align
17100 This pragma sets the alignment of fields in structures. The values of
17101 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or
17102 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest
17103 properly; to restore the previous setting, use @code{reset} for the
17106 @item segment @var{tokens}@dots{}
17107 @cindex pragma, segment
17108 This pragma is accepted, but has no effect.
17110 @item unused (@var{var} [, @var{var}]@dots{})
17111 @cindex pragma, unused
17112 This pragma declares variables to be possibly unused. GCC does not
17113 produce warnings for the listed variables. The effect is similar to
17114 that of the @code{unused} attribute, except that this pragma may appear
17115 anywhere within the variables' scopes.
17118 @node Solaris Pragmas
17119 @subsection Solaris Pragmas
17121 The Solaris target supports @code{#pragma redefine_extname}
17122 (@pxref{Symbol-Renaming Pragmas}). It also supports additional
17123 @code{#pragma} directives for compatibility with the system compiler.
17126 @item align @var{alignment} (@var{variable} [, @var{variable}]...)
17127 @cindex pragma, align
17129 Increase the minimum alignment of each @var{variable} to @var{alignment}.
17130 This is the same as GCC's @code{aligned} attribute @pxref{Variable
17131 Attributes}). Macro expansion occurs on the arguments to this pragma
17132 when compiling C and Objective-C@. It does not currently occur when
17133 compiling C++, but this is a bug which may be fixed in a future
17136 @item fini (@var{function} [, @var{function}]...)
17137 @cindex pragma, fini
17139 This pragma causes each listed @var{function} to be called after
17140 main, or during shared module unloading, by adding a call to the
17141 @code{.fini} section.
17143 @item init (@var{function} [, @var{function}]...)
17144 @cindex pragma, init
17146 This pragma causes each listed @var{function} to be called during
17147 initialization (before @code{main}) or during shared module loading, by
17148 adding a call to the @code{.init} section.
17152 @node Symbol-Renaming Pragmas
17153 @subsection Symbol-Renaming Pragmas
17155 GCC supports a @code{#pragma} directive that changes the name used in
17156 assembly for a given declaration. This effect can also be achieved
17157 using the asm labels extension (@pxref{Asm Labels}).
17160 @item redefine_extname @var{oldname} @var{newname}
17161 @cindex pragma, redefine_extname
17163 This pragma gives the C function @var{oldname} the assembly symbol
17164 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME}
17165 is defined if this pragma is available (currently on all platforms).
17168 This pragma and the asm labels extension interact in a complicated
17169 manner. Here are some corner cases you may want to be aware of:
17172 @item This pragma silently applies only to declarations with external
17173 linkage. Asm labels do not have this restriction.
17175 @item In C++, this pragma silently applies only to declarations with
17176 ``C'' linkage. Again, asm labels do not have this restriction.
17178 @item If either of the ways of changing the assembly name of a
17179 declaration are applied to a declaration whose assembly name has
17180 already been determined (either by a previous use of one of these
17181 features, or because the compiler needed the assembly name in order to
17182 generate code), and the new name is different, a warning issues and
17183 the name does not change.
17185 @item The @var{oldname} used by @code{#pragma redefine_extname} is
17186 always the C-language name.
17189 @node Structure-Packing Pragmas
17190 @subsection Structure-Packing Pragmas
17192 For compatibility with Microsoft Windows compilers, GCC supports a
17193 set of @code{#pragma} directives that change the maximum alignment of
17194 members of structures (other than zero-width bit-fields), unions, and
17195 classes subsequently defined. The @var{n} value below always is required
17196 to be a small power of two and specifies the new alignment in bytes.
17199 @item @code{#pragma pack(@var{n})} simply sets the new alignment.
17200 @item @code{#pragma pack()} sets the alignment to the one that was in
17201 effect when compilation started (see also command-line option
17202 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}).
17203 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment
17204 setting on an internal stack and then optionally sets the new alignment.
17205 @item @code{#pragma pack(pop)} restores the alignment setting to the one
17206 saved at the top of the internal stack (and removes that stack entry).
17207 Note that @code{#pragma pack([@var{n}])} does not influence this internal
17208 stack; thus it is possible to have @code{#pragma pack(push)} followed by
17209 multiple @code{#pragma pack(@var{n})} instances and finalized by a single
17210 @code{#pragma pack(pop)}.
17213 Some targets, e.g.@: i386 and PowerPC, support the @code{ms_struct}
17214 @code{#pragma} which lays out a structure as the documented
17215 @code{__attribute__ ((ms_struct))}.
17217 @item @code{#pragma ms_struct on} turns on the layout for structures
17219 @item @code{#pragma ms_struct off} turns off the layout for structures
17221 @item @code{#pragma ms_struct reset} goes back to the default layout.
17225 @subsection Weak Pragmas
17227 For compatibility with SVR4, GCC supports a set of @code{#pragma}
17228 directives for declaring symbols to be weak, and defining weak
17232 @item #pragma weak @var{symbol}
17233 @cindex pragma, weak
17234 This pragma declares @var{symbol} to be weak, as if the declaration
17235 had the attribute of the same name. The pragma may appear before
17236 or after the declaration of @var{symbol}. It is not an error for
17237 @var{symbol} to never be defined at all.
17239 @item #pragma weak @var{symbol1} = @var{symbol2}
17240 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}.
17241 It is an error if @var{symbol2} is not defined in the current
17245 @node Diagnostic Pragmas
17246 @subsection Diagnostic Pragmas
17248 GCC allows the user to selectively enable or disable certain types of
17249 diagnostics, and change the kind of the diagnostic. For example, a
17250 project's policy might require that all sources compile with
17251 @option{-Werror} but certain files might have exceptions allowing
17252 specific types of warnings. Or, a project might selectively enable
17253 diagnostics and treat them as errors depending on which preprocessor
17254 macros are defined.
17257 @item #pragma GCC diagnostic @var{kind} @var{option}
17258 @cindex pragma, diagnostic
17260 Modifies the disposition of a diagnostic. Note that not all
17261 diagnostics are modifiable; at the moment only warnings (normally
17262 controlled by @samp{-W@dots{}}) can be controlled, and not all of them.
17263 Use @option{-fdiagnostics-show-option} to determine which diagnostics
17264 are controllable and which option controls them.
17266 @var{kind} is @samp{error} to treat this diagnostic as an error,
17267 @samp{warning} to treat it like a warning (even if @option{-Werror} is
17268 in effect), or @samp{ignored} if the diagnostic is to be ignored.
17269 @var{option} is a double quoted string that matches the command-line
17273 #pragma GCC diagnostic warning "-Wformat"
17274 #pragma GCC diagnostic error "-Wformat"
17275 #pragma GCC diagnostic ignored "-Wformat"
17278 Note that these pragmas override any command-line options. GCC keeps
17279 track of the location of each pragma, and issues diagnostics according
17280 to the state as of that point in the source file. Thus, pragmas occurring
17281 after a line do not affect diagnostics caused by that line.
17283 @item #pragma GCC diagnostic push
17284 @itemx #pragma GCC diagnostic pop
17286 Causes GCC to remember the state of the diagnostics as of each
17287 @code{push}, and restore to that point at each @code{pop}. If a
17288 @code{pop} has no matching @code{push}, the command-line options are
17292 #pragma GCC diagnostic error "-Wuninitialized"
17293 foo(a); /* error is given for this one */
17294 #pragma GCC diagnostic push
17295 #pragma GCC diagnostic ignored "-Wuninitialized"
17296 foo(b); /* no diagnostic for this one */
17297 #pragma GCC diagnostic pop
17298 foo(c); /* error is given for this one */
17299 #pragma GCC diagnostic pop
17300 foo(d); /* depends on command-line options */
17305 GCC also offers a simple mechanism for printing messages during
17309 @item #pragma message @var{string}
17310 @cindex pragma, diagnostic
17312 Prints @var{string} as a compiler message on compilation. The message
17313 is informational only, and is neither a compilation warning nor an error.
17316 #pragma message "Compiling " __FILE__ "..."
17319 @var{string} may be parenthesized, and is printed with location
17320 information. For example,
17323 #define DO_PRAGMA(x) _Pragma (#x)
17324 #define TODO(x) DO_PRAGMA(message ("TODO - " #x))
17326 TODO(Remember to fix this)
17330 prints @samp{/tmp/file.c:4: note: #pragma message:
17331 TODO - Remember to fix this}.
17335 @node Visibility Pragmas
17336 @subsection Visibility Pragmas
17339 @item #pragma GCC visibility push(@var{visibility})
17340 @itemx #pragma GCC visibility pop
17341 @cindex pragma, visibility
17343 This pragma allows the user to set the visibility for multiple
17344 declarations without having to give each a visibility attribute
17345 (@pxref{Function Attributes}).
17347 In C++, @samp{#pragma GCC visibility} affects only namespace-scope
17348 declarations. Class members and template specializations are not
17349 affected; if you want to override the visibility for a particular
17350 member or instantiation, you must use an attribute.
17355 @node Push/Pop Macro Pragmas
17356 @subsection Push/Pop Macro Pragmas
17358 For compatibility with Microsoft Windows compilers, GCC supports
17359 @samp{#pragma push_macro(@var{"macro_name"})}
17360 and @samp{#pragma pop_macro(@var{"macro_name"})}.
17363 @item #pragma push_macro(@var{"macro_name"})
17364 @cindex pragma, push_macro
17365 This pragma saves the value of the macro named as @var{macro_name} to
17366 the top of the stack for this macro.
17368 @item #pragma pop_macro(@var{"macro_name"})
17369 @cindex pragma, pop_macro
17370 This pragma sets the value of the macro named as @var{macro_name} to
17371 the value on top of the stack for this macro. If the stack for
17372 @var{macro_name} is empty, the value of the macro remains unchanged.
17379 #pragma push_macro("X")
17382 #pragma pop_macro("X")
17387 In this example, the definition of X as 1 is saved by @code{#pragma
17388 push_macro} and restored by @code{#pragma pop_macro}.
17390 @node Function Specific Option Pragmas
17391 @subsection Function Specific Option Pragmas
17394 @item #pragma GCC target (@var{"string"}...)
17395 @cindex pragma GCC target
17397 This pragma allows you to set target specific options for functions
17398 defined later in the source file. One or more strings can be
17399 specified. Each function that is defined after this point is as
17400 if @code{attribute((target("STRING")))} was specified for that
17401 function. The parenthesis around the options is optional.
17402 @xref{Function Attributes}, for more information about the
17403 @code{target} attribute and the attribute syntax.
17405 The @code{#pragma GCC target} pragma is presently implemented for
17406 i386/x86_64, PowerPC, and Nios II targets only.
17410 @item #pragma GCC optimize (@var{"string"}...)
17411 @cindex pragma GCC optimize
17413 This pragma allows you to set global optimization options for functions
17414 defined later in the source file. One or more strings can be
17415 specified. Each function that is defined after this point is as
17416 if @code{attribute((optimize("STRING")))} was specified for that
17417 function. The parenthesis around the options is optional.
17418 @xref{Function Attributes}, for more information about the
17419 @code{optimize} attribute and the attribute syntax.
17421 The @samp{#pragma GCC optimize} pragma is not implemented in GCC
17422 versions earlier than 4.4.
17426 @item #pragma GCC push_options
17427 @itemx #pragma GCC pop_options
17428 @cindex pragma GCC push_options
17429 @cindex pragma GCC pop_options
17431 These pragmas maintain a stack of the current target and optimization
17432 options. It is intended for include files where you temporarily want
17433 to switch to using a different @samp{#pragma GCC target} or
17434 @samp{#pragma GCC optimize} and then to pop back to the previous
17437 The @samp{#pragma GCC push_options} and @samp{#pragma GCC pop_options}
17438 pragmas are not implemented in GCC versions earlier than 4.4.
17442 @item #pragma GCC reset_options
17443 @cindex pragma GCC reset_options
17445 This pragma clears the current @code{#pragma GCC target} and
17446 @code{#pragma GCC optimize} to use the default switches as specified
17447 on the command line.
17449 The @samp{#pragma GCC reset_options} pragma is not implemented in GCC
17450 versions earlier than 4.4.
17453 @node Loop-Specific Pragmas
17454 @subsection Loop-Specific Pragmas
17457 @item #pragma GCC ivdep
17458 @cindex pragma GCC ivdep
17461 With this pragma, the programmer asserts that there are no loop-carried
17462 dependencies which would prevent that consecutive iterations of
17463 the following loop can be executed concurrently with SIMD
17464 (single instruction multiple data) instructions.
17466 For example, the compiler can only unconditionally vectorize the following
17467 loop with the pragma:
17470 void foo (int n, int *a, int *b, int *c)
17474 for (i = 0; i < n; ++i)
17475 a[i] = b[i] + c[i];
17480 In this example, using the @code{restrict} qualifier had the same
17481 effect. In the following example, that would not be possible. Assume
17482 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows
17483 that it can unconditionally vectorize the following loop:
17486 void ignore_vec_dep (int *a, int k, int c, int m)
17489 for (int i = 0; i < m; i++)
17490 a[i] = a[i + k] * c;
17495 @node Unnamed Fields
17496 @section Unnamed struct/union fields within structs/unions
17497 @cindex @code{struct}
17498 @cindex @code{union}
17500 As permitted by ISO C11 and for compatibility with other compilers,
17501 GCC allows you to define
17502 a structure or union that contains, as fields, structures and unions
17503 without names. For example:
17517 In this example, you are able to access members of the unnamed
17518 union with code like @samp{foo.b}. Note that only unnamed structs and
17519 unions are allowed, you may not have, for example, an unnamed
17522 You must never create such structures that cause ambiguous field definitions.
17523 For example, in this structure:
17535 it is ambiguous which @code{a} is being referred to with @samp{foo.a}.
17536 The compiler gives errors for such constructs.
17538 @opindex fms-extensions
17539 Unless @option{-fms-extensions} is used, the unnamed field must be a
17540 structure or union definition without a tag (for example, @samp{struct
17541 @{ int a; @};}). If @option{-fms-extensions} is used, the field may
17542 also be a definition with a tag such as @samp{struct foo @{ int a;
17543 @};}, a reference to a previously defined structure or union such as
17544 @samp{struct foo;}, or a reference to a @code{typedef} name for a
17545 previously defined structure or union type.
17547 @opindex fplan9-extensions
17548 The option @option{-fplan9-extensions} enables
17549 @option{-fms-extensions} as well as two other extensions. First, a
17550 pointer to a structure is automatically converted to a pointer to an
17551 anonymous field for assignments and function calls. For example:
17554 struct s1 @{ int a; @};
17555 struct s2 @{ struct s1; @};
17556 extern void f1 (struct s1 *);
17557 void f2 (struct s2 *p) @{ f1 (p); @}
17561 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is
17562 converted into a pointer to the anonymous field.
17564 Second, when the type of an anonymous field is a @code{typedef} for a
17565 @code{struct} or @code{union}, code may refer to the field using the
17566 name of the @code{typedef}.
17569 typedef struct @{ int a; @} s1;
17570 struct s2 @{ s1; @};
17571 s1 f1 (struct s2 *p) @{ return p->s1; @}
17574 These usages are only permitted when they are not ambiguous.
17577 @section Thread-Local Storage
17578 @cindex Thread-Local Storage
17579 @cindex @acronym{TLS}
17580 @cindex @code{__thread}
17582 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
17583 are allocated such that there is one instance of the variable per extant
17584 thread. The runtime model GCC uses to implement this originates
17585 in the IA-64 processor-specific ABI, but has since been migrated
17586 to other processors as well. It requires significant support from
17587 the linker (@command{ld}), dynamic linker (@command{ld.so}), and
17588 system libraries (@file{libc.so} and @file{libpthread.so}), so it
17589 is not available everywhere.
17591 At the user level, the extension is visible with a new storage
17592 class keyword: @code{__thread}. For example:
17596 extern __thread struct state s;
17597 static __thread char *p;
17600 The @code{__thread} specifier may be used alone, with the @code{extern}
17601 or @code{static} specifiers, but with no other storage class specifier.
17602 When used with @code{extern} or @code{static}, @code{__thread} must appear
17603 immediately after the other storage class specifier.
17605 The @code{__thread} specifier may be applied to any global, file-scoped
17606 static, function-scoped static, or static data member of a class. It may
17607 not be applied to block-scoped automatic or non-static data member.
17609 When the address-of operator is applied to a thread-local variable, it is
17610 evaluated at run time and returns the address of the current thread's
17611 instance of that variable. An address so obtained may be used by any
17612 thread. When a thread terminates, any pointers to thread-local variables
17613 in that thread become invalid.
17615 No static initialization may refer to the address of a thread-local variable.
17617 In C++, if an initializer is present for a thread-local variable, it must
17618 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++
17621 See @uref{http://www.akkadia.org/drepper/tls.pdf,
17622 ELF Handling For Thread-Local Storage} for a detailed explanation of
17623 the four thread-local storage addressing models, and how the runtime
17624 is expected to function.
17627 * C99 Thread-Local Edits::
17628 * C++98 Thread-Local Edits::
17631 @node C99 Thread-Local Edits
17632 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage
17634 The following are a set of changes to ISO/IEC 9899:1999 (aka C99)
17635 that document the exact semantics of the language extension.
17639 @cite{5.1.2 Execution environments}
17641 Add new text after paragraph 1
17644 Within either execution environment, a @dfn{thread} is a flow of
17645 control within a program. It is implementation defined whether
17646 or not there may be more than one thread associated with a program.
17647 It is implementation defined how threads beyond the first are
17648 created, the name and type of the function called at thread
17649 startup, and how threads may be terminated. However, objects
17650 with thread storage duration shall be initialized before thread
17655 @cite{6.2.4 Storage durations of objects}
17657 Add new text before paragraph 3
17660 An object whose identifier is declared with the storage-class
17661 specifier @w{@code{__thread}} has @dfn{thread storage duration}.
17662 Its lifetime is the entire execution of the thread, and its
17663 stored value is initialized only once, prior to thread startup.
17667 @cite{6.4.1 Keywords}
17669 Add @code{__thread}.
17672 @cite{6.7.1 Storage-class specifiers}
17674 Add @code{__thread} to the list of storage class specifiers in
17677 Change paragraph 2 to
17680 With the exception of @code{__thread}, at most one storage-class
17681 specifier may be given [@dots{}]. The @code{__thread} specifier may
17682 be used alone, or immediately following @code{extern} or
17686 Add new text after paragraph 6
17689 The declaration of an identifier for a variable that has
17690 block scope that specifies @code{__thread} shall also
17691 specify either @code{extern} or @code{static}.
17693 The @code{__thread} specifier shall be used only with
17698 @node C++98 Thread-Local Edits
17699 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage
17701 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98)
17702 that document the exact semantics of the language extension.
17706 @b{[intro.execution]}
17708 New text after paragraph 4
17711 A @dfn{thread} is a flow of control within the abstract machine.
17712 It is implementation defined whether or not there may be more than
17716 New text after paragraph 7
17719 It is unspecified whether additional action must be taken to
17720 ensure when and whether side effects are visible to other threads.
17726 Add @code{__thread}.
17729 @b{[basic.start.main]}
17731 Add after paragraph 5
17734 The thread that begins execution at the @code{main} function is called
17735 the @dfn{main thread}. It is implementation defined how functions
17736 beginning threads other than the main thread are designated or typed.
17737 A function so designated, as well as the @code{main} function, is called
17738 a @dfn{thread startup function}. It is implementation defined what
17739 happens if a thread startup function returns. It is implementation
17740 defined what happens to other threads when any thread calls @code{exit}.
17744 @b{[basic.start.init]}
17746 Add after paragraph 4
17749 The storage for an object of thread storage duration shall be
17750 statically initialized before the first statement of the thread startup
17751 function. An object of thread storage duration shall not require
17752 dynamic initialization.
17756 @b{[basic.start.term]}
17758 Add after paragraph 3
17761 The type of an object with thread storage duration shall not have a
17762 non-trivial destructor, nor shall it be an array type whose elements
17763 (directly or indirectly) have non-trivial destructors.
17769 Add ``thread storage duration'' to the list in paragraph 1.
17774 Thread, static, and automatic storage durations are associated with
17775 objects introduced by declarations [@dots{}].
17778 Add @code{__thread} to the list of specifiers in paragraph 3.
17781 @b{[basic.stc.thread]}
17783 New section before @b{[basic.stc.static]}
17786 The keyword @code{__thread} applied to a non-local object gives the
17787 object thread storage duration.
17789 A local variable or class data member declared both @code{static}
17790 and @code{__thread} gives the variable or member thread storage
17795 @b{[basic.stc.static]}
17800 All objects that have neither thread storage duration, dynamic
17801 storage duration nor are local [@dots{}].
17807 Add @code{__thread} to the list in paragraph 1.
17812 With the exception of @code{__thread}, at most one
17813 @var{storage-class-specifier} shall appear in a given
17814 @var{decl-specifier-seq}. The @code{__thread} specifier may
17815 be used alone, or immediately following the @code{extern} or
17816 @code{static} specifiers. [@dots{}]
17819 Add after paragraph 5
17822 The @code{__thread} specifier can be applied only to the names of objects
17823 and to anonymous unions.
17829 Add after paragraph 6
17832 Non-@code{static} members shall not be @code{__thread}.
17836 @node Binary constants
17837 @section Binary constants using the @samp{0b} prefix
17838 @cindex Binary constants using the @samp{0b} prefix
17840 Integer constants can be written as binary constants, consisting of a
17841 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or
17842 @samp{0B}. This is particularly useful in environments that operate a
17843 lot on the bit level (like microcontrollers).
17845 The following statements are identical:
17854 The type of these constants follows the same rules as for octal or
17855 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL}
17858 @node C++ Extensions
17859 @chapter Extensions to the C++ Language
17860 @cindex extensions, C++ language
17861 @cindex C++ language extensions
17863 The GNU compiler provides these extensions to the C++ language (and you
17864 can also use most of the C language extensions in your C++ programs). If you
17865 want to write code that checks whether these features are available, you can
17866 test for the GNU compiler the same way as for C programs: check for a
17867 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
17868 test specifically for GNU C++ (@pxref{Common Predefined Macros,,
17869 Predefined Macros,cpp,The GNU C Preprocessor}).
17872 * C++ Volatiles:: What constitutes an access to a volatile object.
17873 * Restricted Pointers:: C99 restricted pointers and references.
17874 * Vague Linkage:: Where G++ puts inlines, vtables and such.
17875 * C++ Interface:: You can use a single C++ header file for both
17876 declarations and definitions.
17877 * Template Instantiation:: Methods for ensuring that exactly one copy of
17878 each needed template instantiation is emitted.
17879 * Bound member functions:: You can extract a function pointer to the
17880 method denoted by a @samp{->*} or @samp{.*} expression.
17881 * C++ Attributes:: Variable, function, and type attributes for C++ only.
17882 * Function Multiversioning:: Declaring multiple function versions.
17883 * Namespace Association:: Strong using-directives for namespace association.
17884 * Type Traits:: Compiler support for type traits
17885 * Java Exceptions:: Tweaking exception handling to work with Java.
17886 * Deprecated Features:: Things will disappear from G++.
17887 * Backwards Compatibility:: Compatibilities with earlier definitions of C++.
17890 @node C++ Volatiles
17891 @section When is a Volatile C++ Object Accessed?
17892 @cindex accessing volatiles
17893 @cindex volatile read
17894 @cindex volatile write
17895 @cindex volatile access
17897 The C++ standard differs from the C standard in its treatment of
17898 volatile objects. It fails to specify what constitutes a volatile
17899 access, except to say that C++ should behave in a similar manner to C
17900 with respect to volatiles, where possible. However, the different
17901 lvalueness of expressions between C and C++ complicate the behavior.
17902 G++ behaves the same as GCC for volatile access, @xref{C
17903 Extensions,,Volatiles}, for a description of GCC's behavior.
17905 The C and C++ language specifications differ when an object is
17906 accessed in a void context:
17909 volatile int *src = @var{somevalue};
17913 The C++ standard specifies that such expressions do not undergo lvalue
17914 to rvalue conversion, and that the type of the dereferenced object may
17915 be incomplete. The C++ standard does not specify explicitly that it
17916 is lvalue to rvalue conversion that is responsible for causing an
17917 access. There is reason to believe that it is, because otherwise
17918 certain simple expressions become undefined. However, because it
17919 would surprise most programmers, G++ treats dereferencing a pointer to
17920 volatile object of complete type as GCC would do for an equivalent
17921 type in C@. When the object has incomplete type, G++ issues a
17922 warning; if you wish to force an error, you must force a conversion to
17923 rvalue with, for instance, a static cast.
17925 When using a reference to volatile, G++ does not treat equivalent
17926 expressions as accesses to volatiles, but instead issues a warning that
17927 no volatile is accessed. The rationale for this is that otherwise it
17928 becomes difficult to determine where volatile access occur, and not
17929 possible to ignore the return value from functions returning volatile
17930 references. Again, if you wish to force a read, cast the reference to
17933 G++ implements the same behavior as GCC does when assigning to a
17934 volatile object---there is no reread of the assigned-to object, the
17935 assigned rvalue is reused. Note that in C++ assignment expressions
17936 are lvalues, and if used as an lvalue, the volatile object is
17937 referred to. For instance, @var{vref} refers to @var{vobj}, as
17938 expected, in the following example:
17942 volatile int &vref = vobj = @var{something};
17945 @node Restricted Pointers
17946 @section Restricting Pointer Aliasing
17947 @cindex restricted pointers
17948 @cindex restricted references
17949 @cindex restricted this pointer
17951 As with the C front end, G++ understands the C99 feature of restricted pointers,
17952 specified with the @code{__restrict__}, or @code{__restrict} type
17953 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99}
17954 language flag, @code{restrict} is not a keyword in C++.
17956 In addition to allowing restricted pointers, you can specify restricted
17957 references, which indicate that the reference is not aliased in the local
17961 void fn (int *__restrict__ rptr, int &__restrict__ rref)
17968 In the body of @code{fn}, @var{rptr} points to an unaliased integer and
17969 @var{rref} refers to a (different) unaliased integer.
17971 You may also specify whether a member function's @var{this} pointer is
17972 unaliased by using @code{__restrict__} as a member function qualifier.
17975 void T::fn () __restrict__
17982 Within the body of @code{T::fn}, @var{this} has the effective
17983 definition @code{T *__restrict__ const this}. Notice that the
17984 interpretation of a @code{__restrict__} member function qualifier is
17985 different to that of @code{const} or @code{volatile} qualifier, in that it
17986 is applied to the pointer rather than the object. This is consistent with
17987 other compilers that implement restricted pointers.
17989 As with all outermost parameter qualifiers, @code{__restrict__} is
17990 ignored in function definition matching. This means you only need to
17991 specify @code{__restrict__} in a function definition, rather than
17992 in a function prototype as well.
17994 @node Vague Linkage
17995 @section Vague Linkage
17996 @cindex vague linkage
17998 There are several constructs in C++ that require space in the object
17999 file but are not clearly tied to a single translation unit. We say that
18000 these constructs have ``vague linkage''. Typically such constructs are
18001 emitted wherever they are needed, though sometimes we can be more
18005 @item Inline Functions
18006 Inline functions are typically defined in a header file which can be
18007 included in many different compilations. Hopefully they can usually be
18008 inlined, but sometimes an out-of-line copy is necessary, if the address
18009 of the function is taken or if inlining fails. In general, we emit an
18010 out-of-line copy in all translation units where one is needed. As an
18011 exception, we only emit inline virtual functions with the vtable, since
18012 it always requires a copy.
18014 Local static variables and string constants used in an inline function
18015 are also considered to have vague linkage, since they must be shared
18016 between all inlined and out-of-line instances of the function.
18020 C++ virtual functions are implemented in most compilers using a lookup
18021 table, known as a vtable. The vtable contains pointers to the virtual
18022 functions provided by a class, and each object of the class contains a
18023 pointer to its vtable (or vtables, in some multiple-inheritance
18024 situations). If the class declares any non-inline, non-pure virtual
18025 functions, the first one is chosen as the ``key method'' for the class,
18026 and the vtable is only emitted in the translation unit where the key
18029 @emph{Note:} If the chosen key method is later defined as inline, the
18030 vtable is still emitted in every translation unit that defines it.
18031 Make sure that any inline virtuals are declared inline in the class
18032 body, even if they are not defined there.
18034 @item @code{type_info} objects
18035 @cindex @code{type_info}
18037 C++ requires information about types to be written out in order to
18038 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
18039 For polymorphic classes (classes with virtual functions), the @samp{type_info}
18040 object is written out along with the vtable so that @samp{dynamic_cast}
18041 can determine the dynamic type of a class object at run time. For all
18042 other types, we write out the @samp{type_info} object when it is used: when
18043 applying @samp{typeid} to an expression, throwing an object, or
18044 referring to a type in a catch clause or exception specification.
18046 @item Template Instantiations
18047 Most everything in this section also applies to template instantiations,
18048 but there are other options as well.
18049 @xref{Template Instantiation,,Where's the Template?}.
18053 When used with GNU ld version 2.8 or later on an ELF system such as
18054 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of
18055 these constructs will be discarded at link time. This is known as
18058 On targets that don't support COMDAT, but do support weak symbols, GCC
18059 uses them. This way one copy overrides all the others, but
18060 the unused copies still take up space in the executable.
18062 For targets that do not support either COMDAT or weak symbols,
18063 most entities with vague linkage are emitted as local symbols to
18064 avoid duplicate definition errors from the linker. This does not happen
18065 for local statics in inlines, however, as having multiple copies
18066 almost certainly breaks things.
18068 @xref{C++ Interface,,Declarations and Definitions in One Header}, for
18069 another way to control placement of these constructs.
18071 @node C++ Interface
18072 @section #pragma interface and implementation
18074 @cindex interface and implementation headers, C++
18075 @cindex C++ interface and implementation headers
18076 @cindex pragmas, interface and implementation
18078 @code{#pragma interface} and @code{#pragma implementation} provide the
18079 user with a way of explicitly directing the compiler to emit entities
18080 with vague linkage (and debugging information) in a particular
18083 @emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in
18084 most cases, because of COMDAT support and the ``key method'' heuristic
18085 mentioned in @ref{Vague Linkage}. Using them can actually cause your
18086 program to grow due to unnecessary out-of-line copies of inline
18087 functions. Currently (3.4) the only benefit of these
18088 @code{#pragma}s is reduced duplication of debugging information, and
18089 that should be addressed soon on DWARF 2 targets with the use of
18093 @item #pragma interface
18094 @itemx #pragma interface "@var{subdir}/@var{objects}.h"
18095 @kindex #pragma interface
18096 Use this directive in @emph{header files} that define object classes, to save
18097 space in most of the object files that use those classes. Normally,
18098 local copies of certain information (backup copies of inline member
18099 functions, debugging information, and the internal tables that implement
18100 virtual functions) must be kept in each object file that includes class
18101 definitions. You can use this pragma to avoid such duplication. When a
18102 header file containing @samp{#pragma interface} is included in a
18103 compilation, this auxiliary information is not generated (unless
18104 the main input source file itself uses @samp{#pragma implementation}).
18105 Instead, the object files contain references to be resolved at link
18108 The second form of this directive is useful for the case where you have
18109 multiple headers with the same name in different directories. If you
18110 use this form, you must specify the same string to @samp{#pragma
18113 @item #pragma implementation
18114 @itemx #pragma implementation "@var{objects}.h"
18115 @kindex #pragma implementation
18116 Use this pragma in a @emph{main input file}, when you want full output from
18117 included header files to be generated (and made globally visible). The
18118 included header file, in turn, should use @samp{#pragma interface}.
18119 Backup copies of inline member functions, debugging information, and the
18120 internal tables used to implement virtual functions are all generated in
18121 implementation files.
18123 @cindex implied @code{#pragma implementation}
18124 @cindex @code{#pragma implementation}, implied
18125 @cindex naming convention, implementation headers
18126 If you use @samp{#pragma implementation} with no argument, it applies to
18127 an include file with the same basename@footnote{A file's @dfn{basename}
18128 is the name stripped of all leading path information and of trailing
18129 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source
18130 file. For example, in @file{allclass.cc}, giving just
18131 @samp{#pragma implementation}
18132 by itself is equivalent to @samp{#pragma implementation "allclass.h"}.
18134 In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as
18135 an implementation file whenever you would include it from
18136 @file{allclass.cc} even if you never specified @samp{#pragma
18137 implementation}. This was deemed to be more trouble than it was worth,
18138 however, and disabled.
18140 Use the string argument if you want a single implementation file to
18141 include code from multiple header files. (You must also use
18142 @samp{#include} to include the header file; @samp{#pragma
18143 implementation} only specifies how to use the file---it doesn't actually
18146 There is no way to split up the contents of a single header file into
18147 multiple implementation files.
18150 @cindex inlining and C++ pragmas
18151 @cindex C++ pragmas, effect on inlining
18152 @cindex pragmas in C++, effect on inlining
18153 @samp{#pragma implementation} and @samp{#pragma interface} also have an
18154 effect on function inlining.
18156 If you define a class in a header file marked with @samp{#pragma
18157 interface}, the effect on an inline function defined in that class is
18158 similar to an explicit @code{extern} declaration---the compiler emits
18159 no code at all to define an independent version of the function. Its
18160 definition is used only for inlining with its callers.
18162 @opindex fno-implement-inlines
18163 Conversely, when you include the same header file in a main source file
18164 that declares it as @samp{#pragma implementation}, the compiler emits
18165 code for the function itself; this defines a version of the function
18166 that can be found via pointers (or by callers compiled without
18167 inlining). If all calls to the function can be inlined, you can avoid
18168 emitting the function by compiling with @option{-fno-implement-inlines}.
18169 If any calls are not inlined, you will get linker errors.
18171 @node Template Instantiation
18172 @section Where's the Template?
18173 @cindex template instantiation
18175 C++ templates are the first language feature to require more
18176 intelligence from the environment than one usually finds on a UNIX
18177 system. Somehow the compiler and linker have to make sure that each
18178 template instance occurs exactly once in the executable if it is needed,
18179 and not at all otherwise. There are two basic approaches to this
18180 problem, which are referred to as the Borland model and the Cfront model.
18183 @item Borland model
18184 Borland C++ solved the template instantiation problem by adding the code
18185 equivalent of common blocks to their linker; the compiler emits template
18186 instances in each translation unit that uses them, and the linker
18187 collapses them together. The advantage of this model is that the linker
18188 only has to consider the object files themselves; there is no external
18189 complexity to worry about. This disadvantage is that compilation time
18190 is increased because the template code is being compiled repeatedly.
18191 Code written for this model tends to include definitions of all
18192 templates in the header file, since they must be seen to be
18196 The AT&T C++ translator, Cfront, solved the template instantiation
18197 problem by creating the notion of a template repository, an
18198 automatically maintained place where template instances are stored. A
18199 more modern version of the repository works as follows: As individual
18200 object files are built, the compiler places any template definitions and
18201 instantiations encountered in the repository. At link time, the link
18202 wrapper adds in the objects in the repository and compiles any needed
18203 instances that were not previously emitted. The advantages of this
18204 model are more optimal compilation speed and the ability to use the
18205 system linker; to implement the Borland model a compiler vendor also
18206 needs to replace the linker. The disadvantages are vastly increased
18207 complexity, and thus potential for error; for some code this can be
18208 just as transparent, but in practice it can been very difficult to build
18209 multiple programs in one directory and one program in multiple
18210 directories. Code written for this model tends to separate definitions
18211 of non-inline member templates into a separate file, which should be
18212 compiled separately.
18215 When used with GNU ld version 2.8 or later on an ELF system such as
18216 GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the
18217 Borland model. On other systems, G++ implements neither automatic
18220 You have the following options for dealing with template instantiations:
18225 Compile your template-using code with @option{-frepo}. The compiler
18226 generates files with the extension @samp{.rpo} listing all of the
18227 template instantiations used in the corresponding object files that
18228 could be instantiated there; the link wrapper, @samp{collect2},
18229 then updates the @samp{.rpo} files to tell the compiler where to place
18230 those instantiations and rebuild any affected object files. The
18231 link-time overhead is negligible after the first pass, as the compiler
18232 continues to place the instantiations in the same files.
18234 This is your best option for application code written for the Borland
18235 model, as it just works. Code written for the Cfront model
18236 needs to be modified so that the template definitions are available at
18237 one or more points of instantiation; usually this is as simple as adding
18238 @code{#include <tmethods.cc>} to the end of each template header.
18240 For library code, if you want the library to provide all of the template
18241 instantiations it needs, just try to link all of its object files
18242 together; the link will fail, but cause the instantiations to be
18243 generated as a side effect. Be warned, however, that this may cause
18244 conflicts if multiple libraries try to provide the same instantiations.
18245 For greater control, use explicit instantiation as described in the next
18249 @opindex fno-implicit-templates
18250 Compile your code with @option{-fno-implicit-templates} to disable the
18251 implicit generation of template instances, and explicitly instantiate
18252 all the ones you use. This approach requires more knowledge of exactly
18253 which instances you need than do the others, but it's less
18254 mysterious and allows greater control. You can scatter the explicit
18255 instantiations throughout your program, perhaps putting them in the
18256 translation units where the instances are used or the translation units
18257 that define the templates themselves; you can put all of the explicit
18258 instantiations you need into one big file; or you can create small files
18265 template class Foo<int>;
18266 template ostream& operator <<
18267 (ostream&, const Foo<int>&);
18271 for each of the instances you need, and create a template instantiation
18272 library from those.
18274 If you are using Cfront-model code, you can probably get away with not
18275 using @option{-fno-implicit-templates} when compiling files that don't
18276 @samp{#include} the member template definitions.
18278 If you use one big file to do the instantiations, you may want to
18279 compile it without @option{-fno-implicit-templates} so you get all of the
18280 instances required by your explicit instantiations (but not by any
18281 other files) without having to specify them as well.
18283 The ISO C++ 2011 standard allows forward declaration of explicit
18284 instantiations (with @code{extern}). G++ supports explicit instantiation
18285 declarations in C++98 mode and has extended the template instantiation
18286 syntax to support instantiation of the compiler support data for a
18287 template class (i.e.@: the vtable) without instantiating any of its
18288 members (with @code{inline}), and instantiation of only the static data
18289 members of a template class, without the support data or member
18290 functions (with @code{static}):
18293 extern template int max (int, int);
18294 inline template class Foo<int>;
18295 static template class Foo<int>;
18299 Do nothing. Pretend G++ does implement automatic instantiation
18300 management. Code written for the Borland model works fine, but
18301 each translation unit contains instances of each of the templates it
18302 uses. In a large program, this can lead to an unacceptable amount of code
18306 @node Bound member functions
18307 @section Extracting the function pointer from a bound pointer to member function
18309 @cindex pointer to member function
18310 @cindex bound pointer to member function
18312 In C++, pointer to member functions (PMFs) are implemented using a wide
18313 pointer of sorts to handle all the possible call mechanisms; the PMF
18314 needs to store information about how to adjust the @samp{this} pointer,
18315 and if the function pointed to is virtual, where to find the vtable, and
18316 where in the vtable to look for the member function. If you are using
18317 PMFs in an inner loop, you should really reconsider that decision. If
18318 that is not an option, you can extract the pointer to the function that
18319 would be called for a given object/PMF pair and call it directly inside
18320 the inner loop, to save a bit of time.
18322 Note that you still pay the penalty for the call through a
18323 function pointer; on most modern architectures, such a call defeats the
18324 branch prediction features of the CPU@. This is also true of normal
18325 virtual function calls.
18327 The syntax for this extension is
18331 extern int (A::*fp)();
18332 typedef int (*fptr)(A *);
18334 fptr p = (fptr)(a.*fp);
18337 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}),
18338 no object is needed to obtain the address of the function. They can be
18339 converted to function pointers directly:
18342 fptr p1 = (fptr)(&A::foo);
18345 @opindex Wno-pmf-conversions
18346 You must specify @option{-Wno-pmf-conversions} to use this extension.
18348 @node C++ Attributes
18349 @section C++-Specific Variable, Function, and Type Attributes
18351 Some attributes only make sense for C++ programs.
18354 @item abi_tag ("@var{tag}", ...)
18355 @cindex @code{abi_tag} attribute
18356 The @code{abi_tag} attribute can be applied to a function or class
18357 declaration. It modifies the mangled name of the function or class to
18358 incorporate the tag name, in order to distinguish the function or
18359 class from an earlier version with a different ABI; perhaps the class
18360 has changed size, or the function has a different return type that is
18361 not encoded in the mangled name.
18363 The argument can be a list of strings of arbitrary length. The
18364 strings are sorted on output, so the order of the list is
18367 A redeclaration of a function or class must not add new ABI tags,
18368 since doing so would change the mangled name.
18370 The ABI tags apply to a name, so all instantiations and
18371 specializations of a template have the same tags. The attribute will
18372 be ignored if applied to an explicit specialization or instantiation.
18374 The @option{-Wabi-tag} flag enables a warning about a class which does
18375 not have all the ABI tags used by its subobjects and virtual functions; for users with code
18376 that needs to coexist with an earlier ABI, using this option can help
18377 to find all affected types that need to be tagged.
18379 @item init_priority (@var{priority})
18380 @cindex @code{init_priority} attribute
18383 In Standard C++, objects defined at namespace scope are guaranteed to be
18384 initialized in an order in strict accordance with that of their definitions
18385 @emph{in a given translation unit}. No guarantee is made for initializations
18386 across translation units. However, GNU C++ allows users to control the
18387 order of initialization of objects defined at namespace scope with the
18388 @code{init_priority} attribute by specifying a relative @var{priority},
18389 a constant integral expression currently bounded between 101 and 65535
18390 inclusive. Lower numbers indicate a higher priority.
18392 In the following example, @code{A} would normally be created before
18393 @code{B}, but the @code{init_priority} attribute reverses that order:
18396 Some_Class A __attribute__ ((init_priority (2000)));
18397 Some_Class B __attribute__ ((init_priority (543)));
18401 Note that the particular values of @var{priority} do not matter; only their
18404 @item java_interface
18405 @cindex @code{java_interface} attribute
18407 This type attribute informs C++ that the class is a Java interface. It may
18408 only be applied to classes declared within an @code{extern "Java"} block.
18409 Calls to methods declared in this interface are dispatched using GCJ's
18410 interface table mechanism, instead of regular virtual table dispatch.
18413 @cindex @code{warn_unused} attribute
18415 For C++ types with non-trivial constructors and/or destructors it is
18416 impossible for the compiler to determine whether a variable of this
18417 type is truly unused if it is not referenced. This type attribute
18418 informs the compiler that variables of this type should be warned
18419 about if they appear to be unused, just like variables of fundamental
18422 This attribute is appropriate for types which just represent a value,
18423 such as @code{std::string}; it is not appropriate for types which
18424 control a resource, such as @code{std::mutex}.
18426 This attribute is also accepted in C, but it is unnecessary because C
18427 does not have constructors or destructors.
18431 See also @ref{Namespace Association}.
18433 @node Function Multiversioning
18434 @section Function Multiversioning
18435 @cindex function versions
18437 With the GNU C++ front end, for target i386, you may specify multiple
18438 versions of a function, where each function is specialized for a
18439 specific target feature. At runtime, the appropriate version of the
18440 function is automatically executed depending on the characteristics of
18441 the execution platform. Here is an example.
18444 __attribute__ ((target ("default")))
18447 // The default version of foo.
18451 __attribute__ ((target ("sse4.2")))
18454 // foo version for SSE4.2
18458 __attribute__ ((target ("arch=atom")))
18461 // foo version for the Intel ATOM processor
18465 __attribute__ ((target ("arch=amdfam10")))
18468 // foo version for the AMD Family 0x10 processors.
18475 assert ((*p) () == foo ());
18480 In the above example, four versions of function foo are created. The
18481 first version of foo with the target attribute "default" is the default
18482 version. This version gets executed when no other target specific
18483 version qualifies for execution on a particular platform. A new version
18484 of foo is created by using the same function signature but with a
18485 different target string. Function foo is called or a pointer to it is
18486 taken just like a regular function. GCC takes care of doing the
18487 dispatching to call the right version at runtime. Refer to the
18488 @uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on
18489 Function Multiversioning} for more details.
18491 @node Namespace Association
18492 @section Namespace Association
18494 @strong{Caution:} The semantics of this extension are equivalent
18495 to C++ 2011 inline namespaces. Users should use inline namespaces
18496 instead as this extension will be removed in future versions of G++.
18498 A using-directive with @code{__attribute ((strong))} is stronger
18499 than a normal using-directive in two ways:
18503 Templates from the used namespace can be specialized and explicitly
18504 instantiated as though they were members of the using namespace.
18507 The using namespace is considered an associated namespace of all
18508 templates in the used namespace for purposes of argument-dependent
18512 The used namespace must be nested within the using namespace so that
18513 normal unqualified lookup works properly.
18515 This is useful for composing a namespace transparently from
18516 implementation namespaces. For example:
18521 template <class T> struct A @{ @};
18523 using namespace debug __attribute ((__strong__));
18524 template <> struct A<int> @{ @}; // @r{OK to specialize}
18526 template <class T> void f (A<T>);
18531 f (std::A<float>()); // @r{lookup finds} std::f
18537 @section Type Traits
18539 The C++ front end implements syntactic extensions that allow
18540 compile-time determination of
18541 various characteristics of a type (or of a
18545 @item __has_nothrow_assign (type)
18546 If @code{type} is const qualified or is a reference type then the trait is
18547 false. Otherwise if @code{__has_trivial_assign (type)} is true then the trait
18548 is true, else if @code{type} is a cv class or union type with copy assignment
18549 operators that are known not to throw an exception then the trait is true,
18550 else it is false. Requires: @code{type} shall be a complete type,
18551 (possibly cv-qualified) @code{void}, or an array of unknown bound.
18553 @item __has_nothrow_copy (type)
18554 If @code{__has_trivial_copy (type)} is true then the trait is true, else if
18555 @code{type} is a cv class or union type with copy constructors that
18556 are known not to throw an exception then the trait is true, else it is false.
18557 Requires: @code{type} shall be a complete type, (possibly cv-qualified)
18558 @code{void}, or an array of unknown bound.
18560 @item __has_nothrow_constructor (type)
18561 If @code{__has_trivial_constructor (type)} is true then the trait is
18562 true, else if @code{type} is a cv class or union type (or array
18563 thereof) with a default constructor that is known not to throw an
18564 exception then the trait is true, else it is false. Requires:
18565 @code{type} shall be a complete type, (possibly cv-qualified)
18566 @code{void}, or an array of unknown bound.
18568 @item __has_trivial_assign (type)
18569 If @code{type} is const qualified or is a reference type then the trait is
18570 false. Otherwise if @code{__is_pod (type)} is true then the trait is
18571 true, else if @code{type} is a cv class or union type with a trivial
18572 copy assignment ([class.copy]) then the trait is true, else it is
18573 false. Requires: @code{type} shall be a complete type, (possibly
18574 cv-qualified) @code{void}, or an array of unknown bound.
18576 @item __has_trivial_copy (type)
18577 If @code{__is_pod (type)} is true or @code{type} is a reference type
18578 then the trait is true, else if @code{type} is a cv class or union type
18579 with a trivial copy constructor ([class.copy]) then the trait
18580 is true, else it is false. Requires: @code{type} shall be a complete
18581 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
18583 @item __has_trivial_constructor (type)
18584 If @code{__is_pod (type)} is true then the trait is true, else if
18585 @code{type} is a cv class or union type (or array thereof) with a
18586 trivial default constructor ([class.ctor]) then the trait is true,
18587 else it is false. Requires: @code{type} shall be a complete
18588 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
18590 @item __has_trivial_destructor (type)
18591 If @code{__is_pod (type)} is true or @code{type} is a reference type then
18592 the trait is true, else if @code{type} is a cv class or union type (or
18593 array thereof) with a trivial destructor ([class.dtor]) then the trait
18594 is true, else it is false. Requires: @code{type} shall be a complete
18595 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
18597 @item __has_virtual_destructor (type)
18598 If @code{type} is a class type with a virtual destructor
18599 ([class.dtor]) then the trait is true, else it is false. Requires:
18600 @code{type} shall be a complete type, (possibly cv-qualified)
18601 @code{void}, or an array of unknown bound.
18603 @item __is_abstract (type)
18604 If @code{type} is an abstract class ([class.abstract]) then the trait
18605 is true, else it is false. Requires: @code{type} shall be a complete
18606 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
18608 @item __is_base_of (base_type, derived_type)
18609 If @code{base_type} is a base class of @code{derived_type}
18610 ([class.derived]) then the trait is true, otherwise it is false.
18611 Top-level cv qualifications of @code{base_type} and
18612 @code{derived_type} are ignored. For the purposes of this trait, a
18613 class type is considered is own base. Requires: if @code{__is_class
18614 (base_type)} and @code{__is_class (derived_type)} are true and
18615 @code{base_type} and @code{derived_type} are not the same type
18616 (disregarding cv-qualifiers), @code{derived_type} shall be a complete
18617 type. Diagnostic is produced if this requirement is not met.
18619 @item __is_class (type)
18620 If @code{type} is a cv class type, and not a union type
18621 ([basic.compound]) the trait is true, else it is false.
18623 @item __is_empty (type)
18624 If @code{__is_class (type)} is false then the trait is false.
18625 Otherwise @code{type} is considered empty if and only if: @code{type}
18626 has no non-static data members, or all non-static data members, if
18627 any, are bit-fields of length 0, and @code{type} has no virtual
18628 members, and @code{type} has no virtual base classes, and @code{type}
18629 has no base classes @code{base_type} for which
18630 @code{__is_empty (base_type)} is false. Requires: @code{type} shall
18631 be a complete type, (possibly cv-qualified) @code{void}, or an array
18634 @item __is_enum (type)
18635 If @code{type} is a cv enumeration type ([basic.compound]) the trait is
18636 true, else it is false.
18638 @item __is_literal_type (type)
18639 If @code{type} is a literal type ([basic.types]) the trait is
18640 true, else it is false. Requires: @code{type} shall be a complete type,
18641 (possibly cv-qualified) @code{void}, or an array of unknown bound.
18643 @item __is_pod (type)
18644 If @code{type} is a cv POD type ([basic.types]) then the trait is true,
18645 else it is false. Requires: @code{type} shall be a complete type,
18646 (possibly cv-qualified) @code{void}, or an array of unknown bound.
18648 @item __is_polymorphic (type)
18649 If @code{type} is a polymorphic class ([class.virtual]) then the trait
18650 is true, else it is false. Requires: @code{type} shall be a complete
18651 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
18653 @item __is_standard_layout (type)
18654 If @code{type} is a standard-layout type ([basic.types]) the trait is
18655 true, else it is false. Requires: @code{type} shall be a complete
18656 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
18658 @item __is_trivial (type)
18659 If @code{type} is a trivial type ([basic.types]) the trait is
18660 true, else it is false. Requires: @code{type} shall be a complete
18661 type, (possibly cv-qualified) @code{void}, or an array of unknown bound.
18663 @item __is_union (type)
18664 If @code{type} is a cv union type ([basic.compound]) the trait is
18665 true, else it is false.
18667 @item __underlying_type (type)
18668 The underlying type of @code{type}. Requires: @code{type} shall be
18669 an enumeration type ([dcl.enum]).
18673 @node Java Exceptions
18674 @section Java Exceptions
18676 The Java language uses a slightly different exception handling model
18677 from C++. Normally, GNU C++ automatically detects when you are
18678 writing C++ code that uses Java exceptions, and handle them
18679 appropriately. However, if C++ code only needs to execute destructors
18680 when Java exceptions are thrown through it, GCC guesses incorrectly.
18681 Sample problematic code is:
18684 struct S @{ ~S(); @};
18685 extern void bar(); // @r{is written in Java, and may throw exceptions}
18694 The usual effect of an incorrect guess is a link failure, complaining of
18695 a missing routine called @samp{__gxx_personality_v0}.
18697 You can inform the compiler that Java exceptions are to be used in a
18698 translation unit, irrespective of what it might think, by writing
18699 @samp{@w{#pragma GCC java_exceptions}} at the head of the file. This
18700 @samp{#pragma} must appear before any functions that throw or catch
18701 exceptions, or run destructors when exceptions are thrown through them.
18703 You cannot mix Java and C++ exceptions in the same translation unit. It
18704 is believed to be safe to throw a C++ exception from one file through
18705 another file compiled for the Java exception model, or vice versa, but
18706 there may be bugs in this area.
18708 @node Deprecated Features
18709 @section Deprecated Features
18711 In the past, the GNU C++ compiler was extended to experiment with new
18712 features, at a time when the C++ language was still evolving. Now that
18713 the C++ standard is complete, some of those features are superseded by
18714 superior alternatives. Using the old features might cause a warning in
18715 some cases that the feature will be dropped in the future. In other
18716 cases, the feature might be gone already.
18718 While the list below is not exhaustive, it documents some of the options
18719 that are now deprecated:
18722 @item -fexternal-templates
18723 @itemx -falt-external-templates
18724 These are two of the many ways for G++ to implement template
18725 instantiation. @xref{Template Instantiation}. The C++ standard clearly
18726 defines how template definitions have to be organized across
18727 implementation units. G++ has an implicit instantiation mechanism that
18728 should work just fine for standard-conforming code.
18730 @item -fstrict-prototype
18731 @itemx -fno-strict-prototype
18732 Previously it was possible to use an empty prototype parameter list to
18733 indicate an unspecified number of parameters (like C), rather than no
18734 parameters, as C++ demands. This feature has been removed, except where
18735 it is required for backwards compatibility. @xref{Backwards Compatibility}.
18738 G++ allows a virtual function returning @samp{void *} to be overridden
18739 by one returning a different pointer type. This extension to the
18740 covariant return type rules is now deprecated and will be removed from a
18743 The G++ minimum and maximum operators (@samp{<?} and @samp{>?}) and
18744 their compound forms (@samp{<?=}) and @samp{>?=}) have been deprecated
18745 and are now removed from G++. Code using these operators should be
18746 modified to use @code{std::min} and @code{std::max} instead.
18748 The named return value extension has been deprecated, and is now
18751 The use of initializer lists with new expressions has been deprecated,
18752 and is now removed from G++.
18754 Floating and complex non-type template parameters have been deprecated,
18755 and are now removed from G++.
18757 The implicit typename extension has been deprecated and is now
18760 The use of default arguments in function pointers, function typedefs
18761 and other places where they are not permitted by the standard is
18762 deprecated and will be removed from a future version of G++.
18764 G++ allows floating-point literals to appear in integral constant expressions,
18765 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} }
18766 This extension is deprecated and will be removed from a future version.
18768 G++ allows static data members of const floating-point type to be declared
18769 with an initializer in a class definition. The standard only allows
18770 initializers for static members of const integral types and const
18771 enumeration types so this extension has been deprecated and will be removed
18772 from a future version.
18774 @node Backwards Compatibility
18775 @section Backwards Compatibility
18776 @cindex Backwards Compatibility
18777 @cindex ARM [Annotated C++ Reference Manual]
18779 Now that there is a definitive ISO standard C++, G++ has a specification
18780 to adhere to. The C++ language evolved over time, and features that
18781 used to be acceptable in previous drafts of the standard, such as the ARM
18782 [Annotated C++ Reference Manual], are no longer accepted. In order to allow
18783 compilation of C++ written to such drafts, G++ contains some backwards
18784 compatibilities. @emph{All such backwards compatibility features are
18785 liable to disappear in future versions of G++.} They should be considered
18786 deprecated. @xref{Deprecated Features}.
18790 If a variable is declared at for scope, it used to remain in scope until
18791 the end of the scope that contained the for statement (rather than just
18792 within the for scope). G++ retains this, but issues a warning, if such a
18793 variable is accessed outside the for scope.
18795 @item Implicit C language
18796 Old C system header files did not contain an @code{extern "C" @{@dots{}@}}
18797 scope to set the language. On such systems, all header files are
18798 implicitly scoped inside a C language scope. Also, an empty prototype
18799 @code{()} is treated as an unspecified number of arguments, rather
18800 than no arguments, as C++ demands.
18803 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd
18804 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr followign