1@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001, 2@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 3@c Free Software Foundation, Inc. 4 5@c This is part of the GCC manual. 6@c For copying conditions, see the file gcc.texi. 7 8@node C Extensions 9@chapter Extensions to the C Language Family 10@cindex extensions, C language 11@cindex C language extensions 12 13@opindex pedantic 14GNU C provides several language features not found in ISO standard C@. 15(The @option{-pedantic} option directs GCC to print a warning message if 16any of these features is used.) To test for the availability of these 17features in conditional compilation, check for a predefined macro 18@code{__GNUC__}, which is always defined under GCC@. 19 20These extensions are available in C and Objective-C@. Most of them are 21also available in C++. @xref{C++ Extensions,,Extensions to the 22C++ Language}, for extensions that apply @emph{only} to C++. 23 24Some features that are in ISO C99 but not C90 or C++ are also, as 25extensions, accepted by GCC in C90 mode and in C++. 26 27@menu 28* Statement Exprs:: Putting statements and declarations inside expressions. 29* Local Labels:: Labels local to a block. 30* Labels as Values:: Getting pointers to labels, and computed gotos. 31* Nested Functions:: As in Algol and Pascal, lexical scoping of functions. 32* Constructing Calls:: Dispatching a call to another function. 33* Typeof:: @code{typeof}: referring to the type of an expression. 34* Conditionals:: Omitting the middle operand of a @samp{?:} expression. 35* Long Long:: Double-word integers---@code{long long int}. 36* __int128:: 128-bit integers---@code{__int128}. 37* Complex:: Data types for complex numbers. 38* Floating Types:: Additional Floating Types. 39* Half-Precision:: Half-Precision Floating Point. 40* Decimal Float:: Decimal Floating Types. 41* Hex Floats:: Hexadecimal floating-point constants. 42* Fixed-Point:: Fixed-Point Types. 43* Named Address Spaces::Named address spaces. 44* Zero Length:: Zero-length arrays. 45* Variable Length:: Arrays whose length is computed at run time. 46* Empty Structures:: Structures with no members. 47* Variadic Macros:: Macros with a variable number of arguments. 48* Escaped Newlines:: Slightly looser rules for escaped newlines. 49* Subscripting:: Any array can be subscripted, even if not an lvalue. 50* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. 51* Initializers:: Non-constant initializers. 52* Compound Literals:: Compound literals give structures, unions 53 or arrays as values. 54* Designated Inits:: Labeling elements of initializers. 55* Cast to Union:: Casting to union type from any member of the union. 56* Case Ranges:: `case 1 ... 9' and such. 57* Mixed Declarations:: Mixing declarations and code. 58* Function Attributes:: Declaring that functions have no side effects, 59 or that they can never return. 60* Attribute Syntax:: Formal syntax for attributes. 61* Function Prototypes:: Prototype declarations and old-style definitions. 62* C++ Comments:: C++ comments are recognized. 63* Dollar Signs:: Dollar sign is allowed in identifiers. 64* Character Escapes:: @samp{\e} stands for the character @key{ESC}. 65* Variable Attributes:: Specifying attributes of variables. 66* Type Attributes:: Specifying attributes of types. 67* Alignment:: Inquiring about the alignment of a type or variable. 68* Inline:: Defining inline functions (as fast as macros). 69* Volatiles:: What constitutes an access to a volatile object. 70* Extended Asm:: Assembler instructions with C expressions as operands. 71 (With them you can define ``built-in'' functions.) 72* Constraints:: Constraints for asm operands 73* Asm Labels:: Specifying the assembler name to use for a C symbol. 74* Explicit Reg Vars:: Defining variables residing in specified registers. 75* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. 76* Incomplete Enums:: @code{enum foo;}, with details to follow. 77* Function Names:: Printable strings which are the name of the current 78 function. 79* Return Address:: Getting the return or frame address of a function. 80* Vector Extensions:: Using vector instructions through built-in functions. 81* Offsetof:: Special syntax for implementing @code{offsetof}. 82* __sync Builtins:: Legacy built-in functions for atomic memory access. 83* __atomic Builtins:: Atomic built-in functions with memory model. 84* Object Size Checking:: Built-in functions for limited buffer overflow 85 checking. 86* Other Builtins:: Other built-in functions. 87* Target Builtins:: Built-in functions specific to particular targets. 88* Target Format Checks:: Format checks specific to particular targets. 89* Pragmas:: Pragmas accepted by GCC. 90* Unnamed Fields:: Unnamed struct/union fields within structs/unions. 91* Thread-Local:: Per-thread variables. 92* Binary constants:: Binary constants using the @samp{0b} prefix. 93@end menu 94 95@node Statement Exprs 96@section Statements and Declarations in Expressions 97@cindex statements inside expressions 98@cindex declarations inside expressions 99@cindex expressions containing statements 100@cindex macros, statements in expressions 101 102@c the above section title wrapped and causes an underfull hbox.. i 103@c changed it from "within" to "in". --mew 4feb93 104A compound statement enclosed in parentheses may appear as an expression 105in GNU C@. This allows you to use loops, switches, and local variables 106within an expression. 107 108Recall that a compound statement is a sequence of statements surrounded 109by braces; in this construct, parentheses go around the braces. For 110example: 111 112@smallexample 113(@{ int y = foo (); int z; 114 if (y > 0) z = y; 115 else z = - y; 116 z; @}) 117@end smallexample 118 119@noindent 120is a valid (though slightly more complex than necessary) expression 121for the absolute value of @code{foo ()}. 122 123The last thing in the compound statement should be an expression 124followed by a semicolon; the value of this subexpression serves as the 125value of the entire construct. (If you use some other kind of statement 126last within the braces, the construct has type @code{void}, and thus 127effectively no value.) 128 129This feature is especially useful in making macro definitions ``safe'' (so 130that they evaluate each operand exactly once). For example, the 131``maximum'' function is commonly defined as a macro in standard C as 132follows: 133 134@smallexample 135#define max(a,b) ((a) > (b) ? (a) : (b)) 136@end smallexample 137 138@noindent 139@cindex side effects, macro argument 140But this definition computes either @var{a} or @var{b} twice, with bad 141results if the operand has side effects. In GNU C, if you know the 142type of the operands (here taken as @code{int}), you can define 143the macro safely as follows: 144 145@smallexample 146#define maxint(a,b) \ 147 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) 148@end smallexample 149 150Embedded statements are not allowed in constant expressions, such as 151the value of an enumeration constant, the width of a bit-field, or 152the initial value of a static variable. 153 154If you don't know the type of the operand, you can still do this, but you 155must use @code{typeof} (@pxref{Typeof}). 156 157In G++, the result value of a statement expression undergoes array and 158function pointer decay, and is returned by value to the enclosing 159expression. For instance, if @code{A} is a class, then 160 161@smallexample 162 A a; 163 164 (@{a;@}).Foo () 165@end smallexample 166 167@noindent 168will construct a temporary @code{A} object to hold the result of the 169statement expression, and that will be used to invoke @code{Foo}. 170Therefore the @code{this} pointer observed by @code{Foo} will not be the 171address of @code{a}. 172 173Any temporaries created within a statement within a statement expression 174will be destroyed at the statement's end. This makes statement 175expressions inside macros slightly different from function calls. In 176the latter case temporaries introduced during argument evaluation will 177be destroyed at the end of the statement that includes the function 178call. In the statement expression case they will be destroyed during 179the statement expression. For instance, 180 181@smallexample 182#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) 183template<typename T> T function(T a) @{ T b = a; return b + 3; @} 184 185void foo () 186@{ 187 macro (X ()); 188 function (X ()); 189@} 190@end smallexample 191 192@noindent 193will have different places where temporaries are destroyed. For the 194@code{macro} case, the temporary @code{X} will be destroyed just after 195the initialization of @code{b}. In the @code{function} case that 196temporary will be destroyed when the function returns. 197 198These considerations mean that it is probably a bad idea to use 199statement-expressions of this form in header files that are designed to 200work with C++. (Note that some versions of the GNU C Library contained 201header files using statement-expression that lead to precisely this 202bug.) 203 204Jumping into a statement expression with @code{goto} or using a 205@code{switch} statement outside the statement expression with a 206@code{case} or @code{default} label inside the statement expression is 207not permitted. Jumping into a statement expression with a computed 208@code{goto} (@pxref{Labels as Values}) yields undefined behavior. 209Jumping out of a statement expression is permitted, but if the 210statement expression is part of a larger expression then it is 211unspecified which other subexpressions of that expression have been 212evaluated except where the language definition requires certain 213subexpressions to be evaluated before or after the statement 214expression. In any case, as with a function call the evaluation of a 215statement expression is not interleaved with the evaluation of other 216parts of the containing expression. For example, 217 218@smallexample 219 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); 220@end smallexample 221 222@noindent 223will call @code{foo} and @code{bar1} and will not call @code{baz} but 224may or may not call @code{bar2}. If @code{bar2} is called, it will be 225called after @code{foo} and before @code{bar1} 226 227@node Local Labels 228@section Locally Declared Labels 229@cindex local labels 230@cindex macros, local labels 231 232GCC allows you to declare @dfn{local labels} in any nested block 233scope. A local label is just like an ordinary label, but you can 234only reference it (with a @code{goto} statement, or by taking its 235address) within the block in which it was declared. 236 237A local label declaration looks like this: 238 239@smallexample 240__label__ @var{label}; 241@end smallexample 242 243@noindent 244or 245 246@smallexample 247__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; 248@end smallexample 249 250Local label declarations must come at the beginning of the block, 251before any ordinary declarations or statements. 252 253The label declaration defines the label @emph{name}, but does not define 254the label itself. You must do this in the usual way, with 255@code{@var{label}:}, within the statements of the statement expression. 256 257The local label feature is useful for complex macros. If a macro 258contains nested loops, a @code{goto} can be useful for breaking out of 259them. However, an ordinary label whose scope is the whole function 260cannot be used: if the macro can be expanded several times in one 261function, the label will be multiply defined in that function. A 262local label avoids this problem. For example: 263 264@smallexample 265#define SEARCH(value, array, target) \ 266do @{ \ 267 __label__ found; \ 268 typeof (target) _SEARCH_target = (target); \ 269 typeof (*(array)) *_SEARCH_array = (array); \ 270 int i, j; \ 271 int value; \ 272 for (i = 0; i < max; i++) \ 273 for (j = 0; j < max; j++) \ 274 if (_SEARCH_array[i][j] == _SEARCH_target) \ 275 @{ (value) = i; goto found; @} \ 276 (value) = -1; \ 277 found:; \ 278@} while (0) 279@end smallexample 280 281This could also be written using a statement-expression: 282 283@smallexample 284#define SEARCH(array, target) \ 285(@{ \ 286 __label__ found; \ 287 typeof (target) _SEARCH_target = (target); \ 288 typeof (*(array)) *_SEARCH_array = (array); \ 289 int i, j; \ 290 int value; \ 291 for (i = 0; i < max; i++) \ 292 for (j = 0; j < max; j++) \ 293 if (_SEARCH_array[i][j] == _SEARCH_target) \ 294 @{ value = i; goto found; @} \ 295 value = -1; \ 296 found: \ 297 value; \ 298@}) 299@end smallexample 300 301Local label declarations also make the labels they declare visible to 302nested functions, if there are any. @xref{Nested Functions}, for details. 303 304@node Labels as Values 305@section Labels as Values 306@cindex labels as values 307@cindex computed gotos 308@cindex goto with computed label 309@cindex address of a label 310 311You can get the address of a label defined in the current function 312(or a containing function) with the unary operator @samp{&&}. The 313value has type @code{void *}. This value is a constant and can be used 314wherever a constant of that type is valid. For example: 315 316@smallexample 317void *ptr; 318/* @r{@dots{}} */ 319ptr = &&foo; 320@end smallexample 321 322To use these values, you need to be able to jump to one. This is done 323with the computed goto statement@footnote{The analogous feature in 324Fortran is called an assigned goto, but that name seems inappropriate in 325C, where one can do more than simply store label addresses in label 326variables.}, @code{goto *@var{exp};}. For example, 327 328@smallexample 329goto *ptr; 330@end smallexample 331 332@noindent 333Any expression of type @code{void *} is allowed. 334 335One way of using these constants is in initializing a static array that 336will serve as a jump table: 337 338@smallexample 339static void *array[] = @{ &&foo, &&bar, &&hack @}; 340@end smallexample 341 342Then you can select a label with indexing, like this: 343 344@smallexample 345goto *array[i]; 346@end smallexample 347 348@noindent 349Note that this does not check whether the subscript is in bounds---array 350indexing in C never does that. 351 352Such an array of label values serves a purpose much like that of the 353@code{switch} statement. The @code{switch} statement is cleaner, so 354use that rather than an array unless the problem does not fit a 355@code{switch} statement very well. 356 357Another use of label values is in an interpreter for threaded code. 358The labels within the interpreter function can be stored in the 359threaded code for super-fast dispatching. 360 361You may not use this mechanism to jump to code in a different function. 362If you do that, totally unpredictable things will happen. The best way to 363avoid this is to store the label address only in automatic variables and 364never pass it as an argument. 365 366An alternate way to write the above example is 367 368@smallexample 369static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, 370 &&hack - &&foo @}; 371goto *(&&foo + array[i]); 372@end smallexample 373 374@noindent 375This is more friendly to code living in shared libraries, as it reduces 376the number of dynamic relocations that are needed, and by consequence, 377allows the data to be read-only. 378 379The @code{&&foo} expressions for the same label might have different 380values if the containing function is inlined or cloned. If a program 381relies on them being always the same, 382@code{__attribute__((__noinline__,__noclone__))} should be used to 383prevent inlining and cloning. If @code{&&foo} is used in a static 384variable initializer, inlining and cloning is forbidden. 385 386@node Nested Functions 387@section Nested Functions 388@cindex nested functions 389@cindex downward funargs 390@cindex thunks 391 392A @dfn{nested function} is a function defined inside another function. 393(Nested functions are not supported for GNU C++.) The nested function's 394name is local to the block where it is defined. For example, here we 395define a nested function named @code{square}, and call it twice: 396 397@smallexample 398@group 399foo (double a, double b) 400@{ 401 double square (double z) @{ return z * z; @} 402 403 return square (a) + square (b); 404@} 405@end group 406@end smallexample 407 408The nested function can access all the variables of the containing 409function that are visible at the point of its definition. This is 410called @dfn{lexical scoping}. For example, here we show a nested 411function which uses an inherited variable named @code{offset}: 412 413@smallexample 414@group 415bar (int *array, int offset, int size) 416@{ 417 int access (int *array, int index) 418 @{ return array[index + offset]; @} 419 int i; 420 /* @r{@dots{}} */ 421 for (i = 0; i < size; i++) 422 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 423@} 424@end group 425@end smallexample 426 427Nested function definitions are permitted within functions in the places 428where variable definitions are allowed; that is, in any block, mixed 429with the other declarations and statements in the block. 430 431It is possible to call the nested function from outside the scope of its 432name by storing its address or passing the address to another function: 433 434@smallexample 435hack (int *array, int size) 436@{ 437 void store (int index, int value) 438 @{ array[index] = value; @} 439 440 intermediate (store, size); 441@} 442@end smallexample 443 444Here, the function @code{intermediate} receives the address of 445@code{store} as an argument. If @code{intermediate} calls @code{store}, 446the arguments given to @code{store} are used to store into @code{array}. 447But this technique works only so long as the containing function 448(@code{hack}, in this example) does not exit. 449 450If you try to call the nested function through its address after the 451containing function has exited, all hell will break loose. If you try 452to call it after a containing scope level has exited, and if it refers 453to some of the variables that are no longer in scope, you may be lucky, 454but it's not wise to take the risk. If, however, the nested function 455does not refer to anything that has gone out of scope, you should be 456safe. 457 458GCC implements taking the address of a nested function using a technique 459called @dfn{trampolines}. This technique was described in 460@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX 461C++ Conference Proceedings, October 17-21, 1988). 462 463A nested function can jump to a label inherited from a containing 464function, provided the label was explicitly declared in the containing 465function (@pxref{Local Labels}). Such a jump returns instantly to the 466containing function, exiting the nested function which did the 467@code{goto} and any intermediate functions as well. Here is an example: 468 469@smallexample 470@group 471bar (int *array, int offset, int size) 472@{ 473 __label__ failure; 474 int access (int *array, int index) 475 @{ 476 if (index > size) 477 goto failure; 478 return array[index + offset]; 479 @} 480 int i; 481 /* @r{@dots{}} */ 482 for (i = 0; i < size; i++) 483 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 484 /* @r{@dots{}} */ 485 return 0; 486 487 /* @r{Control comes here from @code{access} 488 if it detects an error.} */ 489 failure: 490 return -1; 491@} 492@end group 493@end smallexample 494 495A nested function always has no linkage. Declaring one with 496@code{extern} or @code{static} is erroneous. If you need to declare the nested function 497before its definition, use @code{auto} (which is otherwise meaningless 498for function declarations). 499 500@smallexample 501bar (int *array, int offset, int size) 502@{ 503 __label__ failure; 504 auto int access (int *, int); 505 /* @r{@dots{}} */ 506 int access (int *array, int index) 507 @{ 508 if (index > size) 509 goto failure; 510 return array[index + offset]; 511 @} 512 /* @r{@dots{}} */ 513@} 514@end smallexample 515 516@node Constructing Calls 517@section Constructing Function Calls 518@cindex constructing calls 519@cindex forwarding calls 520 521Using the built-in functions described below, you can record 522the arguments a function received, and call another function 523with the same arguments, without knowing the number or types 524of the arguments. 525 526You can also record the return value of that function call, 527and later return that value, without knowing what data type 528the function tried to return (as long as your caller expects 529that data type). 530 531However, these built-in functions may interact badly with some 532sophisticated features or other extensions of the language. It 533is, therefore, not recommended to use them outside very simple 534functions acting as mere forwarders for their arguments. 535 536@deftypefn {Built-in Function} {void *} __builtin_apply_args () 537This built-in function returns a pointer to data 538describing how to perform a call with the same arguments as were passed 539to the current function. 540 541The function saves the arg pointer register, structure value address, 542and all registers that might be used to pass arguments to a function 543into a block of memory allocated on the stack. Then it returns the 544address of that block. 545@end deftypefn 546 547@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) 548This built-in function invokes @var{function} 549with a copy of the parameters described by @var{arguments} 550and @var{size}. 551 552The value of @var{arguments} should be the value returned by 553@code{__builtin_apply_args}. The argument @var{size} specifies the size 554of the stack argument data, in bytes. 555 556This function returns a pointer to data describing 557how to return whatever value was returned by @var{function}. The data 558is saved in a block of memory allocated on the stack. 559 560It is not always simple to compute the proper value for @var{size}. The 561value is used by @code{__builtin_apply} to compute the amount of data 562that should be pushed on the stack and copied from the incoming argument 563area. 564@end deftypefn 565 566@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) 567This built-in function returns the value described by @var{result} from 568the containing function. You should specify, for @var{result}, a value 569returned by @code{__builtin_apply}. 570@end deftypefn 571 572@deftypefn {Built-in Function} {} __builtin_va_arg_pack () 573This built-in function represents all anonymous arguments of an inline 574function. It can be used only in inline functions which will be always 575inlined, never compiled as a separate function, such as those using 576@code{__attribute__ ((__always_inline__))} or 577@code{__attribute__ ((__gnu_inline__))} extern inline functions. 578It must be only passed as last argument to some other function 579with variable arguments. This is useful for writing small wrapper 580inlines for variable argument functions, when using preprocessor 581macros is undesirable. For example: 582@smallexample 583extern int myprintf (FILE *f, const char *format, ...); 584extern inline __attribute__ ((__gnu_inline__)) int 585myprintf (FILE *f, const char *format, ...) 586@{ 587 int r = fprintf (f, "myprintf: "); 588 if (r < 0) 589 return r; 590 int s = fprintf (f, format, __builtin_va_arg_pack ()); 591 if (s < 0) 592 return s; 593 return r + s; 594@} 595@end smallexample 596@end deftypefn 597 598@deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len () 599This built-in function returns the number of anonymous arguments of 600an inline function. It can be used only in inline functions which 601will be always inlined, never compiled as a separate function, such 602as those using @code{__attribute__ ((__always_inline__))} or 603@code{__attribute__ ((__gnu_inline__))} extern inline functions. 604For example following will do link or runtime checking of open 605arguments for optimized code: 606@smallexample 607#ifdef __OPTIMIZE__ 608extern inline __attribute__((__gnu_inline__)) int 609myopen (const char *path, int oflag, ...) 610@{ 611 if (__builtin_va_arg_pack_len () > 1) 612 warn_open_too_many_arguments (); 613 614 if (__builtin_constant_p (oflag)) 615 @{ 616 if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1) 617 @{ 618 warn_open_missing_mode (); 619 return __open_2 (path, oflag); 620 @} 621 return open (path, oflag, __builtin_va_arg_pack ()); 622 @} 623 624 if (__builtin_va_arg_pack_len () < 1) 625 return __open_2 (path, oflag); 626 627 return open (path, oflag, __builtin_va_arg_pack ()); 628@} 629#endif 630@end smallexample 631@end deftypefn 632 633@node Typeof 634@section Referring to a Type with @code{typeof} 635@findex typeof 636@findex sizeof 637@cindex macros, types of arguments 638 639Another way to refer to the type of an expression is with @code{typeof}. 640The syntax of using of this keyword looks like @code{sizeof}, but the 641construct acts semantically like a type name defined with @code{typedef}. 642 643There are two ways of writing the argument to @code{typeof}: with an 644expression or with a type. Here is an example with an expression: 645 646@smallexample 647typeof (x[0](1)) 648@end smallexample 649 650@noindent 651This assumes that @code{x} is an array of pointers to functions; 652the type described is that of the values of the functions. 653 654Here is an example with a typename as the argument: 655 656@smallexample 657typeof (int *) 658@end smallexample 659 660@noindent 661Here the type described is that of pointers to @code{int}. 662 663If you are writing a header file that must work when included in ISO C 664programs, write @code{__typeof__} instead of @code{typeof}. 665@xref{Alternate Keywords}. 666 667A @code{typeof}-construct can be used anywhere a typedef name could be 668used. For example, you can use it in a declaration, in a cast, or inside 669of @code{sizeof} or @code{typeof}. 670 671The operand of @code{typeof} is evaluated for its side effects if and 672only if it is an expression of variably modified type or the name of 673such a type. 674 675@code{typeof} is often useful in conjunction with the 676statements-within-expressions feature. Here is how the two together can 677be used to define a safe ``maximum'' macro that operates on any 678arithmetic type and evaluates each of its arguments exactly once: 679 680@smallexample 681#define max(a,b) \ 682 (@{ typeof (a) _a = (a); \ 683 typeof (b) _b = (b); \ 684 _a > _b ? _a : _b; @}) 685@end smallexample 686 687@cindex underscores in variables in macros 688@cindex @samp{_} in variables in macros 689@cindex local variables in macros 690@cindex variables, local, in macros 691@cindex macros, local variables in 692 693The reason for using names that start with underscores for the local 694variables is to avoid conflicts with variable names that occur within the 695expressions that are substituted for @code{a} and @code{b}. Eventually we 696hope to design a new form of declaration syntax that allows you to declare 697variables whose scopes start only after their initializers; this will be a 698more reliable way to prevent such conflicts. 699 700@noindent 701Some more examples of the use of @code{typeof}: 702 703@itemize @bullet 704@item 705This declares @code{y} with the type of what @code{x} points to. 706 707@smallexample 708typeof (*x) y; 709@end smallexample 710 711@item 712This declares @code{y} as an array of such values. 713 714@smallexample 715typeof (*x) y[4]; 716@end smallexample 717 718@item 719This declares @code{y} as an array of pointers to characters: 720 721@smallexample 722typeof (typeof (char *)[4]) y; 723@end smallexample 724 725@noindent 726It is equivalent to the following traditional C declaration: 727 728@smallexample 729char *y[4]; 730@end smallexample 731 732To see the meaning of the declaration using @code{typeof}, and why it 733might be a useful way to write, rewrite it with these macros: 734 735@smallexample 736#define pointer(T) typeof(T *) 737#define array(T, N) typeof(T [N]) 738@end smallexample 739 740@noindent 741Now the declaration can be rewritten this way: 742 743@smallexample 744array (pointer (char), 4) y; 745@end smallexample 746 747@noindent 748Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 749pointers to @code{char}. 750@end itemize 751 752@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported 753a more limited extension which permitted one to write 754 755@smallexample 756typedef @var{T} = @var{expr}; 757@end smallexample 758 759@noindent 760with the effect of declaring @var{T} to have the type of the expression 761@var{expr}. This extension does not work with GCC 3 (versions between 7623.0 and 3.2 will crash; 3.2.1 and later give an error). Code which 763relies on it should be rewritten to use @code{typeof}: 764 765@smallexample 766typedef typeof(@var{expr}) @var{T}; 767@end smallexample 768 769@noindent 770This will work with all versions of GCC@. 771 772@node Conditionals 773@section Conditionals with Omitted Operands 774@cindex conditional expressions, extensions 775@cindex omitted middle-operands 776@cindex middle-operands, omitted 777@cindex extensions, @code{?:} 778@cindex @code{?:} extensions 779 780The middle operand in a conditional expression may be omitted. Then 781if the first operand is nonzero, its value is the value of the conditional 782expression. 783 784Therefore, the expression 785 786@smallexample 787x ? : y 788@end smallexample 789 790@noindent 791has the value of @code{x} if that is nonzero; otherwise, the value of 792@code{y}. 793 794This example is perfectly equivalent to 795 796@smallexample 797x ? x : y 798@end smallexample 799 800@cindex side effect in @code{?:} 801@cindex @code{?:} side effect 802@noindent 803In this simple case, the ability to omit the middle operand is not 804especially useful. When it becomes useful is when the first operand does, 805or may (if it is a macro argument), contain a side effect. Then repeating 806the operand in the middle would perform the side effect twice. Omitting 807the middle operand uses the value already computed without the undesirable 808effects of recomputing it. 809 810@node __int128 811@section 128-bits integers 812@cindex @code{__int128} data types 813 814As an extension the integer scalar type @code{__int128} is supported for 815targets having an integer mode wide enough to hold 128-bit. 816Simply write @code{__int128} for a signed 128-bit integer, or 817@code{unsigned __int128} for an unsigned 128-bit integer. There is no 818support in GCC to express an integer constant of type @code{__int128} 819for targets having @code{long long} integer with less then 128 bit width. 820 821@node Long Long 822@section Double-Word Integers 823@cindex @code{long long} data types 824@cindex double-word arithmetic 825@cindex multiprecision arithmetic 826@cindex @code{LL} integer suffix 827@cindex @code{ULL} integer suffix 828 829ISO C99 supports data types for integers that are at least 64 bits wide, 830and as an extension GCC supports them in C90 mode and in C++. 831Simply write @code{long long int} for a signed integer, or 832@code{unsigned long long int} for an unsigned integer. To make an 833integer constant of type @code{long long int}, add the suffix @samp{LL} 834to the integer. To make an integer constant of type @code{unsigned long 835long int}, add the suffix @samp{ULL} to the integer. 836 837You can use these types in arithmetic like any other integer types. 838Addition, subtraction, and bitwise boolean operations on these types 839are open-coded on all types of machines. Multiplication is open-coded 840if the machine supports fullword-to-doubleword a widening multiply 841instruction. Division and shifts are open-coded only on machines that 842provide special support. The operations that are not open-coded use 843special library routines that come with GCC@. 844 845There may be pitfalls when you use @code{long long} types for function 846arguments, unless you declare function prototypes. If a function 847expects type @code{int} for its argument, and you pass a value of type 848@code{long long int}, confusion will result because the caller and the 849subroutine will disagree about the number of bytes for the argument. 850Likewise, if the function expects @code{long long int} and you pass 851@code{int}. The best way to avoid such problems is to use prototypes. 852 853@node Complex 854@section Complex Numbers 855@cindex complex numbers 856@cindex @code{_Complex} keyword 857@cindex @code{__complex__} keyword 858 859ISO C99 supports complex floating data types, and as an extension GCC 860supports them in C90 mode and in C++, and supports complex integer data 861types which are not part of ISO C99. You can declare complex types 862using the keyword @code{_Complex}. As an extension, the older GNU 863keyword @code{__complex__} is also supported. 864 865For example, @samp{_Complex double x;} declares @code{x} as a 866variable whose real part and imaginary part are both of type 867@code{double}. @samp{_Complex short int y;} declares @code{y} to 868have real and imaginary parts of type @code{short int}; this is not 869likely to be useful, but it shows that the set of complex types is 870complete. 871 872To write a constant with a complex data type, use the suffix @samp{i} or 873@samp{j} (either one; they are equivalent). For example, @code{2.5fi} 874has type @code{_Complex float} and @code{3i} has type 875@code{_Complex int}. Such a constant always has a pure imaginary 876value, but you can form any complex value you like by adding one to a 877real constant. This is a GNU extension; if you have an ISO C99 878conforming C library (such as GNU libc), and want to construct complex 879constants of floating type, you should include @code{<complex.h>} and 880use the macros @code{I} or @code{_Complex_I} instead. 881 882@cindex @code{__real__} keyword 883@cindex @code{__imag__} keyword 884To extract the real part of a complex-valued expression @var{exp}, write 885@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to 886extract the imaginary part. This is a GNU extension; for values of 887floating type, you should use the ISO C99 functions @code{crealf}, 888@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and 889@code{cimagl}, declared in @code{<complex.h>} and also provided as 890built-in functions by GCC@. 891 892@cindex complex conjugation 893The operator @samp{~} performs complex conjugation when used on a value 894with a complex type. This is a GNU extension; for values of 895floating type, you should use the ISO C99 functions @code{conjf}, 896@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also 897provided as built-in functions by GCC@. 898 899GCC can allocate complex automatic variables in a noncontiguous 900fashion; it's even possible for the real part to be in a register while 901the imaginary part is on the stack (or vice-versa). Only the DWARF2 902debug info format can represent this, so use of DWARF2 is recommended. 903If you are using the stabs debug info format, GCC describes a noncontiguous 904complex variable as if it were two separate variables of noncomplex type. 905If the variable's actual name is @code{foo}, the two fictitious 906variables are named @code{foo$real} and @code{foo$imag}. You can 907examine and set these two fictitious variables with your debugger. 908 909@node Floating Types 910@section Additional Floating Types 911@cindex additional floating types 912@cindex @code{__float80} data type 913@cindex @code{__float128} data type 914@cindex @code{w} floating point suffix 915@cindex @code{q} floating point suffix 916@cindex @code{W} floating point suffix 917@cindex @code{Q} floating point suffix 918 919As an extension, the GNU C compiler supports additional floating 920types, @code{__float80} and @code{__float128} to support 80bit 921(@code{XFmode}) and 128 bit (@code{TFmode}) floating types. 922Support for additional types includes the arithmetic operators: 923add, subtract, multiply, divide; unary arithmetic operators; 924relational operators; equality operators; and conversions to and from 925integer and other floating types. Use a suffix @samp{w} or @samp{W} 926in a literal constant of type @code{__float80} and @samp{q} or @samp{Q} 927for @code{_float128}. You can declare complex types using the 928corresponding internal complex type, @code{XCmode} for @code{__float80} 929type and @code{TCmode} for @code{__float128} type: 930 931@smallexample 932typedef _Complex float __attribute__((mode(TC))) _Complex128; 933typedef _Complex float __attribute__((mode(XC))) _Complex80; 934@end smallexample 935 936Not all targets support additional floating point types. @code{__float80} 937and @code{__float128} types are supported on i386, x86_64 and ia64 targets. 938The @code{__float128} type is supported on hppa HP-UX targets. 939 940@node Half-Precision 941@section Half-Precision Floating Point 942@cindex half-precision floating point 943@cindex @code{__fp16} data type 944 945On ARM targets, GCC supports half-precision (16-bit) floating point via 946the @code{__fp16} type. You must enable this type explicitly 947with the @option{-mfp16-format} command-line option in order to use it. 948 949ARM supports two incompatible representations for half-precision 950floating-point values. You must choose one of the representations and 951use it consistently in your program. 952 953Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format. 954This format can represent normalized values in the range of @math{2^{-14}} to 65504. 955There are 11 bits of significand precision, approximately 3 956decimal digits. 957 958Specifying @option{-mfp16-format=alternative} selects the ARM 959alternative format. This representation is similar to the IEEE 960format, but does not support infinities or NaNs. Instead, the range 961of exponents is extended, so that this format can represent normalized 962values in the range of @math{2^{-14}} to 131008. 963 964The @code{__fp16} type is a storage format only. For purposes 965of arithmetic and other operations, @code{__fp16} values in C or C++ 966expressions are automatically promoted to @code{float}. In addition, 967you cannot declare a function with a return value or parameters 968of type @code{__fp16}. 969 970Note that conversions from @code{double} to @code{__fp16} 971involve an intermediate conversion to @code{float}. Because 972of rounding, this can sometimes produce a different result than a 973direct conversion. 974 975ARM provides hardware support for conversions between 976@code{__fp16} and @code{float} values 977as an extension to VFP and NEON (Advanced SIMD). GCC generates 978code using these hardware instructions if you compile with 979options to select an FPU that provides them; 980for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp}, 981in addition to the @option{-mfp16-format} option to select 982a half-precision format. 983 984Language-level support for the @code{__fp16} data type is 985independent of whether GCC generates code using hardware floating-point 986instructions. In cases where hardware support is not specified, GCC 987implements conversions between @code{__fp16} and @code{float} values 988as library calls. 989 990@node Decimal Float 991@section Decimal Floating Types 992@cindex decimal floating types 993@cindex @code{_Decimal32} data type 994@cindex @code{_Decimal64} data type 995@cindex @code{_Decimal128} data type 996@cindex @code{df} integer suffix 997@cindex @code{dd} integer suffix 998@cindex @code{dl} integer suffix 999@cindex @code{DF} integer suffix 1000@cindex @code{DD} integer suffix 1001@cindex @code{DL} integer suffix 1002 1003As an extension, the GNU C compiler supports decimal floating types as 1004defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal 1005floating types in GCC will evolve as the draft technical report changes. 1006Calling conventions for any target might also change. Not all targets 1007support decimal floating types. 1008 1009The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and 1010@code{_Decimal128}. They use a radix of ten, unlike the floating types 1011@code{float}, @code{double}, and @code{long double} whose radix is not 1012specified by the C standard but is usually two. 1013 1014Support for decimal floating types includes the arithmetic operators 1015add, subtract, multiply, divide; unary arithmetic operators; 1016relational operators; equality operators; and conversions to and from 1017integer and other floating types. Use a suffix @samp{df} or 1018@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} 1019or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for 1020@code{_Decimal128}. 1021 1022GCC support of decimal float as specified by the draft technical report 1023is incomplete: 1024 1025@itemize @bullet 1026@item 1027When the value of a decimal floating type cannot be represented in the 1028integer type to which it is being converted, the result is undefined 1029rather than the result value specified by the draft technical report. 1030 1031@item 1032GCC does not provide the C library functionality associated with 1033@file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and 1034@file{wchar.h}, which must come from a separate C library implementation. 1035Because of this the GNU C compiler does not define macro 1036@code{__STDC_DEC_FP__} to indicate that the implementation conforms to 1037the technical report. 1038@end itemize 1039 1040Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} 1041are supported by the DWARF2 debug information format. 1042 1043@node Hex Floats 1044@section Hex Floats 1045@cindex hex floats 1046 1047ISO C99 supports floating-point numbers written not only in the usual 1048decimal notation, such as @code{1.55e1}, but also numbers such as 1049@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC 1050supports this in C90 mode (except in some cases when strictly 1051conforming) and in C++. In that format the 1052@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are 1053mandatory. The exponent is a decimal number that indicates the power of 10542 by which the significant part will be multiplied. Thus @samp{0x1.f} is 1055@tex 1056$1 {15\over16}$, 1057@end tex 1058@ifnottex 10591 15/16, 1060@end ifnottex 1061@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} 1062is the same as @code{1.55e1}. 1063 1064Unlike for floating-point numbers in the decimal notation the exponent 1065is always required in the hexadecimal notation. Otherwise the compiler 1066would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This 1067could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the 1068extension for floating-point constants of type @code{float}. 1069 1070@node Fixed-Point 1071@section Fixed-Point Types 1072@cindex fixed-point types 1073@cindex @code{_Fract} data type 1074@cindex @code{_Accum} data type 1075@cindex @code{_Sat} data type 1076@cindex @code{hr} fixed-suffix 1077@cindex @code{r} fixed-suffix 1078@cindex @code{lr} fixed-suffix 1079@cindex @code{llr} fixed-suffix 1080@cindex @code{uhr} fixed-suffix 1081@cindex @code{ur} fixed-suffix 1082@cindex @code{ulr} fixed-suffix 1083@cindex @code{ullr} fixed-suffix 1084@cindex @code{hk} fixed-suffix 1085@cindex @code{k} fixed-suffix 1086@cindex @code{lk} fixed-suffix 1087@cindex @code{llk} fixed-suffix 1088@cindex @code{uhk} fixed-suffix 1089@cindex @code{uk} fixed-suffix 1090@cindex @code{ulk} fixed-suffix 1091@cindex @code{ullk} fixed-suffix 1092@cindex @code{HR} fixed-suffix 1093@cindex @code{R} fixed-suffix 1094@cindex @code{LR} fixed-suffix 1095@cindex @code{LLR} fixed-suffix 1096@cindex @code{UHR} fixed-suffix 1097@cindex @code{UR} fixed-suffix 1098@cindex @code{ULR} fixed-suffix 1099@cindex @code{ULLR} fixed-suffix 1100@cindex @code{HK} fixed-suffix 1101@cindex @code{K} fixed-suffix 1102@cindex @code{LK} fixed-suffix 1103@cindex @code{LLK} fixed-suffix 1104@cindex @code{UHK} fixed-suffix 1105@cindex @code{UK} fixed-suffix 1106@cindex @code{ULK} fixed-suffix 1107@cindex @code{ULLK} fixed-suffix 1108 1109As an extension, the GNU C compiler supports fixed-point types as 1110defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point 1111types in GCC will evolve as the draft technical report changes. 1112Calling conventions for any target might also change. Not all targets 1113support fixed-point types. 1114 1115The fixed-point types are 1116@code{short _Fract}, 1117@code{_Fract}, 1118@code{long _Fract}, 1119@code{long long _Fract}, 1120@code{unsigned short _Fract}, 1121@code{unsigned _Fract}, 1122@code{unsigned long _Fract}, 1123@code{unsigned long long _Fract}, 1124@code{_Sat short _Fract}, 1125@code{_Sat _Fract}, 1126@code{_Sat long _Fract}, 1127@code{_Sat long long _Fract}, 1128@code{_Sat unsigned short _Fract}, 1129@code{_Sat unsigned _Fract}, 1130@code{_Sat unsigned long _Fract}, 1131@code{_Sat unsigned long long _Fract}, 1132@code{short _Accum}, 1133@code{_Accum}, 1134@code{long _Accum}, 1135@code{long long _Accum}, 1136@code{unsigned short _Accum}, 1137@code{unsigned _Accum}, 1138@code{unsigned long _Accum}, 1139@code{unsigned long long _Accum}, 1140@code{_Sat short _Accum}, 1141@code{_Sat _Accum}, 1142@code{_Sat long _Accum}, 1143@code{_Sat long long _Accum}, 1144@code{_Sat unsigned short _Accum}, 1145@code{_Sat unsigned _Accum}, 1146@code{_Sat unsigned long _Accum}, 1147@code{_Sat unsigned long long _Accum}. 1148 1149Fixed-point data values contain fractional and optional integral parts. 1150The format of fixed-point data varies and depends on the target machine. 1151 1152Support for fixed-point types includes: 1153@itemize @bullet 1154@item 1155prefix and postfix increment and decrement operators (@code{++}, @code{--}) 1156@item 1157unary arithmetic operators (@code{+}, @code{-}, @code{!}) 1158@item 1159binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/}) 1160@item 1161binary shift operators (@code{<<}, @code{>>}) 1162@item 1163relational operators (@code{<}, @code{<=}, @code{>=}, @code{>}) 1164@item 1165equality operators (@code{==}, @code{!=}) 1166@item 1167assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=}, 1168@code{<<=}, @code{>>=}) 1169@item 1170conversions to and from integer, floating-point, or fixed-point types 1171@end itemize 1172 1173Use a suffix in a fixed-point literal constant: 1174@itemize 1175@item @samp{hr} or @samp{HR} for @code{short _Fract} and 1176@code{_Sat short _Fract} 1177@item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract} 1178@item @samp{lr} or @samp{LR} for @code{long _Fract} and 1179@code{_Sat long _Fract} 1180@item @samp{llr} or @samp{LLR} for @code{long long _Fract} and 1181@code{_Sat long long _Fract} 1182@item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and 1183@code{_Sat unsigned short _Fract} 1184@item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and 1185@code{_Sat unsigned _Fract} 1186@item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and 1187@code{_Sat unsigned long _Fract} 1188@item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract} 1189and @code{_Sat unsigned long long _Fract} 1190@item @samp{hk} or @samp{HK} for @code{short _Accum} and 1191@code{_Sat short _Accum} 1192@item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum} 1193@item @samp{lk} or @samp{LK} for @code{long _Accum} and 1194@code{_Sat long _Accum} 1195@item @samp{llk} or @samp{LLK} for @code{long long _Accum} and 1196@code{_Sat long long _Accum} 1197@item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and 1198@code{_Sat unsigned short _Accum} 1199@item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and 1200@code{_Sat unsigned _Accum} 1201@item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and 1202@code{_Sat unsigned long _Accum} 1203@item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum} 1204and @code{_Sat unsigned long long _Accum} 1205@end itemize 1206 1207GCC support of fixed-point types as specified by the draft technical report 1208is incomplete: 1209 1210@itemize @bullet 1211@item 1212Pragmas to control overflow and rounding behaviors are not implemented. 1213@end itemize 1214 1215Fixed-point types are supported by the DWARF2 debug information format. 1216 1217@node Named Address Spaces 1218@section Named Address Spaces 1219@cindex Named Address Spaces 1220 1221As an extension, the GNU C compiler supports named address spaces as 1222defined in the N1275 draft of ISO/IEC DTR 18037. Support for named 1223address spaces in GCC will evolve as the draft technical report 1224changes. Calling conventions for any target might also change. At 1225present, only the AVR, SPU, M32C, and RL78 targets support address 1226spaces other than the generic address space. 1227 1228Address space identifiers may be used exactly like any other C type 1229qualifier (e.g., @code{const} or @code{volatile}). See the N1275 1230document for more details. 1231 1232@anchor{AVR Named Address Spaces} 1233@subsection AVR Named Address Spaces 1234 1235On the AVR target, there are several address spaces that can be used 1236in order to put read-only data into the flash memory and access that 1237data by means of the special instructions @code{LPM} or @code{ELPM} 1238needed to read from flash. 1239 1240Per default, any data including read-only data is located in RAM 1241(the generic address space) so that non-generic address spaces are 1242needed to locate read-only data in flash memory 1243@emph{and} to generate the right instructions to access this data 1244without using (inline) assembler code. 1245 1246@table @code 1247@item __flash 1248@cindex @code{__flash} AVR Named Address Spaces 1249The @code{__flash} qualifier will locate data in the 1250@code{.progmem.data} section. Data will be read using the @code{LPM} 1251instruction. Pointers to this address space are 16 bits wide. 1252 1253@item __flash1 1254@item __flash2 1255@item __flash3 1256@item __flash4 1257@item __flash5 1258@cindex @code{__flash1} AVR Named Address Spaces 1259@cindex @code{__flash2} AVR Named Address Spaces 1260@cindex @code{__flash3} AVR Named Address Spaces 1261@cindex @code{__flash4} AVR Named Address Spaces 1262@cindex @code{__flash5} AVR Named Address Spaces 1263These are 16-bit address spaces locating data in section 1264@code{.progmem@var{N}.data} where @var{N} refers to 1265address space @code{__flash@var{N}}. 1266The compiler will set the @code{RAMPZ} segment register approptiately 1267before reading data by means of the @code{ELPM} instruction. 1268 1269@item __memx 1270@cindex @code{__memx} AVR Named Address Spaces 1271This is a 24-bit address space that linearizes flash and RAM: 1272If the high bit of the address is set, data is read from 1273RAM using the lower two bytes as RAM address. 1274If the high bit of the address is clear, data is read from flash 1275with @code{RAMPZ} set according to the high byte of the address. 1276 1277Objects in this address space will be located in @code{.progmem.data}. 1278@end table 1279 1280@b{Example} 1281 1282@example 1283char my_read (const __flash char ** p) 1284@{ 1285 /* p is a pointer to RAM that points to a pointer to flash. 1286 The first indirection of p will read that flash pointer 1287 from RAM and the second indirection reads a char from this 1288 flash address. */ 1289 1290 return **p; 1291@} 1292 1293/* Locate array[] in flash memory */ 1294const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; 1295 1296int i = 1; 1297 1298int main (void) 1299@{ 1300 /* Return 17 by reading from flash memory */ 1301 return array[array[i]]; 1302@} 1303@end example 1304 1305For each named address space supported by avr-gcc there is an equally 1306named but uppercase built-in macro defined. 1307The purpose is to facilitate testing if respective address space 1308support is available or not: 1309 1310@example 1311#ifdef __FLASH 1312const __flash int var = 1; 1313 1314int read_var (void) 1315@{ 1316 return var; 1317@} 1318#else 1319#include <avr/pgmspace.h> /* From AVR-LibC */ 1320 1321const int var PROGMEM = 1; 1322 1323int read_var (void) 1324@{ 1325 return (int) pgm_read_word (&var); 1326@} 1327#endif /* __FLASH */ 1328@end example 1329 1330Notice that attribute @ref{AVR Variable Attributes,@code{progmem}} 1331locates data in flash but 1332accesses to these data will read from generic address space, i.e.@: 1333from RAM, 1334so that you need special accessors like @code{pgm_read_byte} 1335from @w{@uref{http://nongnu.org/avr-libc/user-manual,AVR-LibC}} 1336together with attribute @code{progmem}. 1337 1338@b{Limitations and caveats} 1339 1340@itemize 1341@item 1342Reading across the 64@tie{}KiB section boundary of 1343the @code{__flash} or @code{__flash@var{N}} address spaces 1344will show undefined behaviour. The only address space that 1345supports reading across the 64@tie{}KiB flash segment boundaries is 1346@code{__memx}. 1347 1348@item 1349If you use one of the @code{__flash@var{N}} address spaces 1350you will have to arrange your linker skript to locate the 1351@code{.progmem@var{N}.data} sections according to your needs. 1352 1353@item 1354Any data or pointers to the non-generic address spaces must 1355be qualified as @code{const}, i.e.@: as read-only data. 1356This still applies if the data in one of these address 1357spaces like software version number or calibration lookup table are intended to 1358be changed after load time by, say, a boot loader. In this case 1359the right qualification is @code{const} @code{volatile} so that the compiler 1360must not optimize away known values or insert them 1361as immediates into operands of instructions. 1362 1363@item 1364Code like the following is not yet supported because of missing 1365support in avr-binutils, 1366see @w{@uref{http://sourceware.org/PR13503,PR13503}}. 1367@example 1368extern const __memx char foo; 1369const __memx void *pfoo = &foo; 1370@end example 1371The code will throw an assembler warning and the high byte of 1372@code{pfoo} will be initialized with@tie{}@code{0}, i.e.@: the 1373initialization will be as if @code{foo} was located in the first 137464@tie{}KiB chunk of flash. 1375 1376@end itemize 1377 1378@subsection M32C Named Address Spaces 1379@cindex @code{__far} M32C Named Address Spaces 1380 1381On the M32C target, with the R8C and M16C cpu variants, variables 1382qualified with @code{__far} are accessed using 32-bit addresses in 1383order to access memory beyond the first 64@tie{}Ki bytes. If 1384@code{__far} is used with the M32CM or M32C cpu variants, it has no 1385effect. 1386 1387@subsection RL78 Named Address Spaces 1388@cindex @code{__far} RL78 Named Address Spaces 1389 1390On the RL78 target, variables qualified with @code{__far} are accessed 1391with 32-bit pointers (20-bit addresses) rather than the default 16-bit 1392addresses. Non-far variables are assumed to appear in the topmost 139364@tie{}KiB of the address space. 1394 1395@subsection SPU Named Address Spaces 1396@cindex @code{__ea} SPU Named Address Spaces 1397 1398On the SPU target variables may be declared as 1399belonging to another address space by qualifying the type with the 1400@code{__ea} address space identifier: 1401 1402@smallexample 1403extern int __ea i; 1404@end smallexample 1405 1406When the variable @code{i} is accessed, the compiler will generate 1407special code to access this variable. It may use runtime library 1408support, or generate special machine instructions to access that address 1409space. 1410 1411@node Zero Length 1412@section Arrays of Length Zero 1413@cindex arrays of length zero 1414@cindex zero-length arrays 1415@cindex length-zero arrays 1416@cindex flexible array members 1417 1418Zero-length arrays are allowed in GNU C@. They are very useful as the 1419last element of a structure which is really a header for a variable-length 1420object: 1421 1422@smallexample 1423struct line @{ 1424 int length; 1425 char contents[0]; 1426@}; 1427 1428struct line *thisline = (struct line *) 1429 malloc (sizeof (struct line) + this_length); 1430thisline->length = this_length; 1431@end smallexample 1432 1433In ISO C90, you would have to give @code{contents} a length of 1, which 1434means either you waste space or complicate the argument to @code{malloc}. 1435 1436In ISO C99, you would use a @dfn{flexible array member}, which is 1437slightly different in syntax and semantics: 1438 1439@itemize @bullet 1440@item 1441Flexible array members are written as @code{contents[]} without 1442the @code{0}. 1443 1444@item 1445Flexible array members have incomplete type, and so the @code{sizeof} 1446operator may not be applied. As a quirk of the original implementation 1447of zero-length arrays, @code{sizeof} evaluates to zero. 1448 1449@item 1450Flexible array members may only appear as the last member of a 1451@code{struct} that is otherwise non-empty. 1452 1453@item 1454A structure containing a flexible array member, or a union containing 1455such a structure (possibly recursively), may not be a member of a 1456structure or an element of an array. (However, these uses are 1457permitted by GCC as extensions.) 1458@end itemize 1459 1460GCC versions before 3.0 allowed zero-length arrays to be statically 1461initialized, as if they were flexible arrays. In addition to those 1462cases that were useful, it also allowed initializations in situations 1463that would corrupt later data. Non-empty initialization of zero-length 1464arrays is now treated like any case where there are more initializer 1465elements than the array holds, in that a suitable warning about "excess 1466elements in array" is given, and the excess elements (all of them, in 1467this case) are ignored. 1468 1469Instead GCC allows static initialization of flexible array members. 1470This is equivalent to defining a new structure containing the original 1471structure followed by an array of sufficient size to contain the data. 1472I.e.@: in the following, @code{f1} is constructed as if it were declared 1473like @code{f2}. 1474 1475@smallexample 1476struct f1 @{ 1477 int x; int y[]; 1478@} f1 = @{ 1, @{ 2, 3, 4 @} @}; 1479 1480struct f2 @{ 1481 struct f1 f1; int data[3]; 1482@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; 1483@end smallexample 1484 1485@noindent 1486The convenience of this extension is that @code{f1} has the desired 1487type, eliminating the need to consistently refer to @code{f2.f1}. 1488 1489This has symmetry with normal static arrays, in that an array of 1490unknown size is also written with @code{[]}. 1491 1492Of course, this extension only makes sense if the extra data comes at 1493the end of a top-level object, as otherwise we would be overwriting 1494data at subsequent offsets. To avoid undue complication and confusion 1495with initialization of deeply nested arrays, we simply disallow any 1496non-empty initialization except when the structure is the top-level 1497object. For example: 1498 1499@smallexample 1500struct foo @{ int x; int y[]; @}; 1501struct bar @{ struct foo z; @}; 1502 1503struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} 1504struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1505struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} 1506struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1507@end smallexample 1508 1509@node Empty Structures 1510@section Structures With No Members 1511@cindex empty structures 1512@cindex zero-size structures 1513 1514GCC permits a C structure to have no members: 1515 1516@smallexample 1517struct empty @{ 1518@}; 1519@end smallexample 1520 1521The structure will have size zero. In C++, empty structures are part 1522of the language. G++ treats empty structures as if they had a single 1523member of type @code{char}. 1524 1525@node Variable Length 1526@section Arrays of Variable Length 1527@cindex variable-length arrays 1528@cindex arrays of variable length 1529@cindex VLAs 1530 1531Variable-length automatic arrays are allowed in ISO C99, and as an 1532extension GCC accepts them in C90 mode and in C++. These arrays are 1533declared like any other automatic arrays, but with a length that is not 1534a constant expression. The storage is allocated at the point of 1535declaration and deallocated when the brace-level is exited. For 1536example: 1537 1538@smallexample 1539FILE * 1540concat_fopen (char *s1, char *s2, char *mode) 1541@{ 1542 char str[strlen (s1) + strlen (s2) + 1]; 1543 strcpy (str, s1); 1544 strcat (str, s2); 1545 return fopen (str, mode); 1546@} 1547@end smallexample 1548 1549@cindex scope of a variable length array 1550@cindex variable-length array scope 1551@cindex deallocating variable length arrays 1552Jumping or breaking out of the scope of the array name deallocates the 1553storage. Jumping into the scope is not allowed; you get an error 1554message for it. 1555 1556@cindex @code{alloca} vs variable-length arrays 1557You can use the function @code{alloca} to get an effect much like 1558variable-length arrays. The function @code{alloca} is available in 1559many other C implementations (but not in all). On the other hand, 1560variable-length arrays are more elegant. 1561 1562There are other differences between these two methods. Space allocated 1563with @code{alloca} exists until the containing @emph{function} returns. 1564The space for a variable-length array is deallocated as soon as the array 1565name's scope ends. (If you use both variable-length arrays and 1566@code{alloca} in the same function, deallocation of a variable-length array 1567will also deallocate anything more recently allocated with @code{alloca}.) 1568 1569You can also use variable-length arrays as arguments to functions: 1570 1571@smallexample 1572struct entry 1573tester (int len, char data[len][len]) 1574@{ 1575 /* @r{@dots{}} */ 1576@} 1577@end smallexample 1578 1579The length of an array is computed once when the storage is allocated 1580and is remembered for the scope of the array in case you access it with 1581@code{sizeof}. 1582 1583If you want to pass the array first and the length afterward, you can 1584use a forward declaration in the parameter list---another GNU extension. 1585 1586@smallexample 1587struct entry 1588tester (int len; char data[len][len], int len) 1589@{ 1590 /* @r{@dots{}} */ 1591@} 1592@end smallexample 1593 1594@cindex parameter forward declaration 1595The @samp{int len} before the semicolon is a @dfn{parameter forward 1596declaration}, and it serves the purpose of making the name @code{len} 1597known when the declaration of @code{data} is parsed. 1598 1599You can write any number of such parameter forward declarations in the 1600parameter list. They can be separated by commas or semicolons, but the 1601last one must end with a semicolon, which is followed by the ``real'' 1602parameter declarations. Each forward declaration must match a ``real'' 1603declaration in parameter name and data type. ISO C99 does not support 1604parameter forward declarations. 1605 1606@node Variadic Macros 1607@section Macros with a Variable Number of Arguments. 1608@cindex variable number of arguments 1609@cindex macro with variable arguments 1610@cindex rest argument (in macro) 1611@cindex variadic macros 1612 1613In the ISO C standard of 1999, a macro can be declared to accept a 1614variable number of arguments much as a function can. The syntax for 1615defining the macro is similar to that of a function. Here is an 1616example: 1617 1618@smallexample 1619#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) 1620@end smallexample 1621 1622Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of 1623such a macro, it represents the zero or more tokens until the closing 1624parenthesis that ends the invocation, including any commas. This set of 1625tokens replaces the identifier @code{__VA_ARGS__} in the macro body 1626wherever it appears. See the CPP manual for more information. 1627 1628GCC has long supported variadic macros, and used a different syntax that 1629allowed you to give a name to the variable arguments just like any other 1630argument. Here is an example: 1631 1632@smallexample 1633#define debug(format, args...) fprintf (stderr, format, args) 1634@end smallexample 1635 1636This is in all ways equivalent to the ISO C example above, but arguably 1637more readable and descriptive. 1638 1639GNU CPP has two further variadic macro extensions, and permits them to 1640be used with either of the above forms of macro definition. 1641 1642In standard C, you are not allowed to leave the variable argument out 1643entirely; but you are allowed to pass an empty argument. For example, 1644this invocation is invalid in ISO C, because there is no comma after 1645the string: 1646 1647@smallexample 1648debug ("A message") 1649@end smallexample 1650 1651GNU CPP permits you to completely omit the variable arguments in this 1652way. In the above examples, the compiler would complain, though since 1653the expansion of the macro still has the extra comma after the format 1654string. 1655 1656To help solve this problem, CPP behaves specially for variable arguments 1657used with the token paste operator, @samp{##}. If instead you write 1658 1659@smallexample 1660#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) 1661@end smallexample 1662 1663and if the variable arguments are omitted or empty, the @samp{##} 1664operator causes the preprocessor to remove the comma before it. If you 1665do provide some variable arguments in your macro invocation, GNU CPP 1666does not complain about the paste operation and instead places the 1667variable arguments after the comma. Just like any other pasted macro 1668argument, these arguments are not macro expanded. 1669 1670@node Escaped Newlines 1671@section Slightly Looser Rules for Escaped Newlines 1672@cindex escaped newlines 1673@cindex newlines (escaped) 1674 1675Recently, the preprocessor has relaxed its treatment of escaped 1676newlines. Previously, the newline had to immediately follow a 1677backslash. The current implementation allows whitespace in the form 1678of spaces, horizontal and vertical tabs, and form feeds between the 1679backslash and the subsequent newline. The preprocessor issues a 1680warning, but treats it as a valid escaped newline and combines the two 1681lines to form a single logical line. This works within comments and 1682tokens, as well as between tokens. Comments are @emph{not} treated as 1683whitespace for the purposes of this relaxation, since they have not 1684yet been replaced with spaces. 1685 1686@node Subscripting 1687@section Non-Lvalue Arrays May Have Subscripts 1688@cindex subscripting 1689@cindex arrays, non-lvalue 1690 1691@cindex subscripting and function values 1692In ISO C99, arrays that are not lvalues still decay to pointers, and 1693may be subscripted, although they may not be modified or used after 1694the next sequence point and the unary @samp{&} operator may not be 1695applied to them. As an extension, GCC allows such arrays to be 1696subscripted in C90 mode, though otherwise they do not decay to 1697pointers outside C99 mode. For example, 1698this is valid in GNU C though not valid in C90: 1699 1700@smallexample 1701@group 1702struct foo @{int a[4];@}; 1703 1704struct foo f(); 1705 1706bar (int index) 1707@{ 1708 return f().a[index]; 1709@} 1710@end group 1711@end smallexample 1712 1713@node Pointer Arith 1714@section Arithmetic on @code{void}- and Function-Pointers 1715@cindex void pointers, arithmetic 1716@cindex void, size of pointer to 1717@cindex function pointers, arithmetic 1718@cindex function, size of pointer to 1719 1720In GNU C, addition and subtraction operations are supported on pointers to 1721@code{void} and on pointers to functions. This is done by treating the 1722size of a @code{void} or of a function as 1. 1723 1724A consequence of this is that @code{sizeof} is also allowed on @code{void} 1725and on function types, and returns 1. 1726 1727@opindex Wpointer-arith 1728The option @option{-Wpointer-arith} requests a warning if these extensions 1729are used. 1730 1731@node Initializers 1732@section Non-Constant Initializers 1733@cindex initializers, non-constant 1734@cindex non-constant initializers 1735 1736As in standard C++ and ISO C99, the elements of an aggregate initializer for an 1737automatic variable are not required to be constant expressions in GNU C@. 1738Here is an example of an initializer with run-time varying elements: 1739 1740@smallexample 1741foo (float f, float g) 1742@{ 1743 float beat_freqs[2] = @{ f-g, f+g @}; 1744 /* @r{@dots{}} */ 1745@} 1746@end smallexample 1747 1748@node Compound Literals 1749@section Compound Literals 1750@cindex constructor expressions 1751@cindex initializations in expressions 1752@cindex structures, constructor expression 1753@cindex expressions, constructor 1754@cindex compound literals 1755@c The GNU C name for what C99 calls compound literals was "constructor expressions". 1756 1757ISO C99 supports compound literals. A compound literal looks like 1758a cast containing an initializer. Its value is an object of the 1759type specified in the cast, containing the elements specified in 1760the initializer; it is an lvalue. As an extension, GCC supports 1761compound literals in C90 mode and in C++, though the semantics are 1762somewhat different in C++. 1763 1764Usually, the specified type is a structure. Assume that 1765@code{struct foo} and @code{structure} are declared as shown: 1766 1767@smallexample 1768struct foo @{int a; char b[2];@} structure; 1769@end smallexample 1770 1771@noindent 1772Here is an example of constructing a @code{struct foo} with a compound literal: 1773 1774@smallexample 1775structure = ((struct foo) @{x + y, 'a', 0@}); 1776@end smallexample 1777 1778@noindent 1779This is equivalent to writing the following: 1780 1781@smallexample 1782@{ 1783 struct foo temp = @{x + y, 'a', 0@}; 1784 structure = temp; 1785@} 1786@end smallexample 1787 1788You can also construct an array, though this is dangerous in C++, as 1789explained below. If all the elements of the compound literal are 1790(made up of) simple constant expressions, suitable for use in 1791initializers of objects of static storage duration, then the compound 1792literal can be coerced to a pointer to its first element and used in 1793such an initializer, as shown here: 1794 1795@smallexample 1796char **foo = (char *[]) @{ "x", "y", "z" @}; 1797@end smallexample 1798 1799Compound literals for scalar types and union types are 1800also allowed, but then the compound literal is equivalent 1801to a cast. 1802 1803As a GNU extension, GCC allows initialization of objects with static storage 1804duration by compound literals (which is not possible in ISO C99, because 1805the initializer is not a constant). 1806It is handled as if the object was initialized only with the bracket 1807enclosed list if the types of the compound literal and the object match. 1808The initializer list of the compound literal must be constant. 1809If the object being initialized has array type of unknown size, the size is 1810determined by compound literal size. 1811 1812@smallexample 1813static struct foo x = (struct foo) @{1, 'a', 'b'@}; 1814static int y[] = (int []) @{1, 2, 3@}; 1815static int z[] = (int [3]) @{1@}; 1816@end smallexample 1817 1818@noindent 1819The above lines are equivalent to the following: 1820@smallexample 1821static struct foo x = @{1, 'a', 'b'@}; 1822static int y[] = @{1, 2, 3@}; 1823static int z[] = @{1, 0, 0@}; 1824@end smallexample 1825 1826In C, a compound literal designates an unnamed object with static or 1827automatic storage duration. In C++, a compound literal designates a 1828temporary object, which only lives until the end of its 1829full-expression. As a result, well-defined C code that takes the 1830address of a subobject of a compound literal can be undefined in C++. 1831For instance, if the array compound literal example above appeared 1832inside a function, any subsequent use of @samp{foo} in C++ has 1833undefined behavior because the lifetime of the array ends after the 1834declaration of @samp{foo}. As a result, the C++ compiler now rejects 1835the conversion of a temporary array to a pointer. 1836 1837As an optimization, the C++ compiler sometimes gives array compound 1838literals longer lifetimes: when the array either appears outside a 1839function or has const-qualified type. If @samp{foo} and its 1840initializer had elements of @samp{char *const} type rather than 1841@samp{char *}, or if @samp{foo} were a global variable, the array 1842would have static storage duration. But it is probably safest just to 1843avoid the use of array compound literals in code compiled as C++. 1844 1845@node Designated Inits 1846@section Designated Initializers 1847@cindex initializers with labeled elements 1848@cindex labeled elements in initializers 1849@cindex case labels in initializers 1850@cindex designated initializers 1851 1852Standard C90 requires the elements of an initializer to appear in a fixed 1853order, the same as the order of the elements in the array or structure 1854being initialized. 1855 1856In ISO C99 you can give the elements in any order, specifying the array 1857indices or structure field names they apply to, and GNU C allows this as 1858an extension in C90 mode as well. This extension is not 1859implemented in GNU C++. 1860 1861To specify an array index, write 1862@samp{[@var{index}] =} before the element value. For example, 1863 1864@smallexample 1865int a[6] = @{ [4] = 29, [2] = 15 @}; 1866@end smallexample 1867 1868@noindent 1869is equivalent to 1870 1871@smallexample 1872int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; 1873@end smallexample 1874 1875@noindent 1876The index values must be constant expressions, even if the array being 1877initialized is automatic. 1878 1879An alternative syntax for this which has been obsolete since GCC 2.5 but 1880GCC still accepts is to write @samp{[@var{index}]} before the element 1881value, with no @samp{=}. 1882 1883To initialize a range of elements to the same value, write 1884@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU 1885extension. For example, 1886 1887@smallexample 1888int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; 1889@end smallexample 1890 1891@noindent 1892If the value in it has side-effects, the side-effects will happen only once, 1893not for each initialized field by the range initializer. 1894 1895@noindent 1896Note that the length of the array is the highest value specified 1897plus one. 1898 1899In a structure initializer, specify the name of a field to initialize 1900with @samp{.@var{fieldname} =} before the element value. For example, 1901given the following structure, 1902 1903@smallexample 1904struct point @{ int x, y; @}; 1905@end smallexample 1906 1907@noindent 1908the following initialization 1909 1910@smallexample 1911struct point p = @{ .y = yvalue, .x = xvalue @}; 1912@end smallexample 1913 1914@noindent 1915is equivalent to 1916 1917@smallexample 1918struct point p = @{ xvalue, yvalue @}; 1919@end smallexample 1920 1921Another syntax which has the same meaning, obsolete since GCC 2.5, is 1922@samp{@var{fieldname}:}, as shown here: 1923 1924@smallexample 1925struct point p = @{ y: yvalue, x: xvalue @}; 1926@end smallexample 1927 1928@cindex designators 1929The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a 1930@dfn{designator}. You can also use a designator (or the obsolete colon 1931syntax) when initializing a union, to specify which element of the union 1932should be used. For example, 1933 1934@smallexample 1935union foo @{ int i; double d; @}; 1936 1937union foo f = @{ .d = 4 @}; 1938@end smallexample 1939 1940@noindent 1941will convert 4 to a @code{double} to store it in the union using 1942the second element. By contrast, casting 4 to type @code{union foo} 1943would store it into the union as the integer @code{i}, since it is 1944an integer. (@xref{Cast to Union}.) 1945 1946You can combine this technique of naming elements with ordinary C 1947initialization of successive elements. Each initializer element that 1948does not have a designator applies to the next consecutive element of the 1949array or structure. For example, 1950 1951@smallexample 1952int a[6] = @{ [1] = v1, v2, [4] = v4 @}; 1953@end smallexample 1954 1955@noindent 1956is equivalent to 1957 1958@smallexample 1959int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; 1960@end smallexample 1961 1962Labeling the elements of an array initializer is especially useful 1963when the indices are characters or belong to an @code{enum} type. 1964For example: 1965 1966@smallexample 1967int whitespace[256] 1968 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, 1969 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; 1970@end smallexample 1971 1972@cindex designator lists 1973You can also write a series of @samp{.@var{fieldname}} and 1974@samp{[@var{index}]} designators before an @samp{=} to specify a 1975nested subobject to initialize; the list is taken relative to the 1976subobject corresponding to the closest surrounding brace pair. For 1977example, with the @samp{struct point} declaration above: 1978 1979@smallexample 1980struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; 1981@end smallexample 1982 1983@noindent 1984If the same field is initialized multiple times, it will have value from 1985the last initialization. If any such overridden initialization has 1986side-effect, it is unspecified whether the side-effect happens or not. 1987Currently, GCC will discard them and issue a warning. 1988 1989@node Case Ranges 1990@section Case Ranges 1991@cindex case ranges 1992@cindex ranges in case statements 1993 1994You can specify a range of consecutive values in a single @code{case} label, 1995like this: 1996 1997@smallexample 1998case @var{low} ... @var{high}: 1999@end smallexample 2000 2001@noindent 2002This has the same effect as the proper number of individual @code{case} 2003labels, one for each integer value from @var{low} to @var{high}, inclusive. 2004 2005This feature is especially useful for ranges of ASCII character codes: 2006 2007@smallexample 2008case 'A' ... 'Z': 2009@end smallexample 2010 2011@strong{Be careful:} Write spaces around the @code{...}, for otherwise 2012it may be parsed wrong when you use it with integer values. For example, 2013write this: 2014 2015@smallexample 2016case 1 ... 5: 2017@end smallexample 2018 2019@noindent 2020rather than this: 2021 2022@smallexample 2023case 1...5: 2024@end smallexample 2025 2026@node Cast to Union 2027@section Cast to a Union Type 2028@cindex cast to a union 2029@cindex union, casting to a 2030 2031A cast to union type is similar to other casts, except that the type 2032specified is a union type. You can specify the type either with 2033@code{union @var{tag}} or with a typedef name. A cast to union is actually 2034a constructor though, not a cast, and hence does not yield an lvalue like 2035normal casts. (@xref{Compound Literals}.) 2036 2037The types that may be cast to the union type are those of the members 2038of the union. Thus, given the following union and variables: 2039 2040@smallexample 2041union foo @{ int i; double d; @}; 2042int x; 2043double y; 2044@end smallexample 2045 2046@noindent 2047both @code{x} and @code{y} can be cast to type @code{union foo}. 2048 2049Using the cast as the right-hand side of an assignment to a variable of 2050union type is equivalent to storing in a member of the union: 2051 2052@smallexample 2053union foo u; 2054/* @r{@dots{}} */ 2055u = (union foo) x @equiv{} u.i = x 2056u = (union foo) y @equiv{} u.d = y 2057@end smallexample 2058 2059You can also use the union cast as a function argument: 2060 2061@smallexample 2062void hack (union foo); 2063/* @r{@dots{}} */ 2064hack ((union foo) x); 2065@end smallexample 2066 2067@node Mixed Declarations 2068@section Mixed Declarations and Code 2069@cindex mixed declarations and code 2070@cindex declarations, mixed with code 2071@cindex code, mixed with declarations 2072 2073ISO C99 and ISO C++ allow declarations and code to be freely mixed 2074within compound statements. As an extension, GCC also allows this in 2075C90 mode. For example, you could do: 2076 2077@smallexample 2078int i; 2079/* @r{@dots{}} */ 2080i++; 2081int j = i + 2; 2082@end smallexample 2083 2084Each identifier is visible from where it is declared until the end of 2085the enclosing block. 2086 2087@node Function Attributes 2088@section Declaring Attributes of Functions 2089@cindex function attributes 2090@cindex declaring attributes of functions 2091@cindex functions that never return 2092@cindex functions that return more than once 2093@cindex functions that have no side effects 2094@cindex functions in arbitrary sections 2095@cindex functions that behave like malloc 2096@cindex @code{volatile} applied to function 2097@cindex @code{const} applied to function 2098@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments 2099@cindex functions with non-null pointer arguments 2100@cindex functions that are passed arguments in registers on the 386 2101@cindex functions that pop the argument stack on the 386 2102@cindex functions that do not pop the argument stack on the 386 2103@cindex functions that have different compilation options on the 386 2104@cindex functions that have different optimization options 2105@cindex functions that are dynamically resolved 2106 2107In GNU C, you declare certain things about functions called in your program 2108which help the compiler optimize function calls and check your code more 2109carefully. 2110 2111The keyword @code{__attribute__} allows you to specify special 2112attributes when making a declaration. This keyword is followed by an 2113attribute specification inside double parentheses. The following 2114attributes are currently defined for functions on all targets: 2115@code{aligned}, @code{alloc_size}, @code{noreturn}, 2116@code{returns_twice}, @code{noinline}, @code{noclone}, 2117@code{always_inline}, @code{flatten}, @code{pure}, @code{const}, 2118@code{nothrow}, @code{sentinel}, @code{format}, @code{format_arg}, 2119@code{no_instrument_function}, @code{no_split_stack}, 2120@code{section}, @code{constructor}, 2121@code{destructor}, @code{used}, @code{unused}, @code{deprecated}, 2122@code{weak}, @code{malloc}, @code{alias}, @code{ifunc}, 2123@code{warn_unused_result}, @code{nonnull}, @code{gnu_inline}, 2124@code{externally_visible}, @code{hot}, @code{cold}, @code{artificial}, 2125@code{error} and @code{warning}. Several other attributes are defined 2126for functions on particular target systems. Other attributes, 2127including @code{section} are supported for variables declarations 2128(@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}). 2129 2130GCC plugins may provide their own attributes. 2131 2132You may also specify attributes with @samp{__} preceding and following 2133each keyword. This allows you to use them in header files without 2134being concerned about a possible macro of the same name. For example, 2135you may use @code{__noreturn__} instead of @code{noreturn}. 2136 2137@xref{Attribute Syntax}, for details of the exact syntax for using 2138attributes. 2139 2140@table @code 2141@c Keep this table alphabetized by attribute name. Treat _ as space. 2142 2143@item alias ("@var{target}") 2144@cindex @code{alias} attribute 2145The @code{alias} attribute causes the declaration to be emitted as an 2146alias for another symbol, which must be specified. For instance, 2147 2148@smallexample 2149void __f () @{ /* @r{Do something.} */; @} 2150void f () __attribute__ ((weak, alias ("__f"))); 2151@end smallexample 2152 2153defines @samp{f} to be a weak alias for @samp{__f}. In C++, the 2154mangled name for the target must be used. It is an error if @samp{__f} 2155is not defined in the same translation unit. 2156 2157Not all target machines support this attribute. 2158 2159@item aligned (@var{alignment}) 2160@cindex @code{aligned} attribute 2161This attribute specifies a minimum alignment for the function, 2162measured in bytes. 2163 2164You cannot use this attribute to decrease the alignment of a function, 2165only to increase it. However, when you explicitly specify a function 2166alignment this will override the effect of the 2167@option{-falign-functions} (@pxref{Optimize Options}) option for this 2168function. 2169 2170Note that the effectiveness of @code{aligned} attributes may be 2171limited by inherent limitations in your linker. On many systems, the 2172linker is only able to arrange for functions to be aligned up to a 2173certain maximum alignment. (For some linkers, the maximum supported 2174alignment may be very very small.) See your linker documentation for 2175further information. 2176 2177The @code{aligned} attribute can also be used for variables and fields 2178(@pxref{Variable Attributes}.) 2179 2180@item alloc_size 2181@cindex @code{alloc_size} attribute 2182The @code{alloc_size} attribute is used to tell the compiler that the 2183function return value points to memory, where the size is given by 2184one or two of the functions parameters. GCC uses this 2185information to improve the correctness of @code{__builtin_object_size}. 2186 2187The function parameter(s) denoting the allocated size are specified by 2188one or two integer arguments supplied to the attribute. The allocated size 2189is either the value of the single function argument specified or the product 2190of the two function arguments specified. Argument numbering starts at 2191one. 2192 2193For instance, 2194 2195@smallexample 2196void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2))) 2197void my_realloc(void*, size_t) __attribute__((alloc_size(2))) 2198@end smallexample 2199 2200declares that my_calloc will return memory of the size given by 2201the product of parameter 1 and 2 and that my_realloc will return memory 2202of the size given by parameter 2. 2203 2204@item always_inline 2205@cindex @code{always_inline} function attribute 2206Generally, functions are not inlined unless optimization is specified. 2207For functions declared inline, this attribute inlines the function even 2208if no optimization level was specified. 2209 2210@item gnu_inline 2211@cindex @code{gnu_inline} function attribute 2212This attribute should be used with a function which is also declared 2213with the @code{inline} keyword. It directs GCC to treat the function 2214as if it were defined in gnu90 mode even when compiling in C99 or 2215gnu99 mode. 2216 2217If the function is declared @code{extern}, then this definition of the 2218function is used only for inlining. In no case is the function 2219compiled as a standalone function, not even if you take its address 2220explicitly. Such an address becomes an external reference, as if you 2221had only declared the function, and had not defined it. This has 2222almost the effect of a macro. The way to use this is to put a 2223function definition in a header file with this attribute, and put 2224another copy of the function, without @code{extern}, in a library 2225file. The definition in the header file will cause most calls to the 2226function to be inlined. If any uses of the function remain, they will 2227refer to the single copy in the library. Note that the two 2228definitions of the functions need not be precisely the same, although 2229if they do not have the same effect your program may behave oddly. 2230 2231In C, if the function is neither @code{extern} nor @code{static}, then 2232the function is compiled as a standalone function, as well as being 2233inlined where possible. 2234 2235This is how GCC traditionally handled functions declared 2236@code{inline}. Since ISO C99 specifies a different semantics for 2237@code{inline}, this function attribute is provided as a transition 2238measure and as a useful feature in its own right. This attribute is 2239available in GCC 4.1.3 and later. It is available if either of the 2240preprocessor macros @code{__GNUC_GNU_INLINE__} or 2241@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline 2242Function is As Fast As a Macro}. 2243 2244In C++, this attribute does not depend on @code{extern} in any way, 2245but it still requires the @code{inline} keyword to enable its special 2246behavior. 2247 2248@item artificial 2249@cindex @code{artificial} function attribute 2250This attribute is useful for small inline wrappers which if possible 2251should appear during debugging as a unit, depending on the debug 2252info format it will either mean marking the function as artificial 2253or using the caller location for all instructions within the inlined 2254body. 2255 2256@item bank_switch 2257@cindex interrupt handler functions 2258When added to an interrupt handler with the M32C port, causes the 2259prologue and epilogue to use bank switching to preserve the registers 2260rather than saving them on the stack. 2261 2262@item flatten 2263@cindex @code{flatten} function attribute 2264Generally, inlining into a function is limited. For a function marked with 2265this attribute, every call inside this function will be inlined, if possible. 2266Whether the function itself is considered for inlining depends on its size and 2267the current inlining parameters. 2268 2269@item error ("@var{message}") 2270@cindex @code{error} function attribute 2271If this attribute is used on a function declaration and a call to such a function 2272is not eliminated through dead code elimination or other optimizations, an error 2273which will include @var{message} will be diagnosed. This is useful 2274for compile time checking, especially together with @code{__builtin_constant_p} 2275and inline functions where checking the inline function arguments is not 2276possible through @code{extern char [(condition) ? 1 : -1];} tricks. 2277While it is possible to leave the function undefined and thus invoke 2278a link failure, when using this attribute the problem will be diagnosed 2279earlier and with exact location of the call even in presence of inline 2280functions or when not emitting debugging information. 2281 2282@item warning ("@var{message}") 2283@cindex @code{warning} function attribute 2284If this attribute is used on a function declaration and a call to such a function 2285is not eliminated through dead code elimination or other optimizations, a warning 2286which will include @var{message} will be diagnosed. This is useful 2287for compile time checking, especially together with @code{__builtin_constant_p} 2288and inline functions. While it is possible to define the function with 2289a message in @code{.gnu.warning*} section, when using this attribute the problem 2290will be diagnosed earlier and with exact location of the call even in presence 2291of inline functions or when not emitting debugging information. 2292 2293@item cdecl 2294@cindex functions that do pop the argument stack on the 386 2295@opindex mrtd 2296On the Intel 386, the @code{cdecl} attribute causes the compiler to 2297assume that the calling function will pop off the stack space used to 2298pass arguments. This is 2299useful to override the effects of the @option{-mrtd} switch. 2300 2301@item const 2302@cindex @code{const} function attribute 2303Many functions do not examine any values except their arguments, and 2304have no effects except the return value. Basically this is just slightly 2305more strict class than the @code{pure} attribute below, since function is not 2306allowed to read global memory. 2307 2308@cindex pointer arguments 2309Note that a function that has pointer arguments and examines the data 2310pointed to must @emph{not} be declared @code{const}. Likewise, a 2311function that calls a non-@code{const} function usually must not be 2312@code{const}. It does not make sense for a @code{const} function to 2313return @code{void}. 2314 2315The attribute @code{const} is not implemented in GCC versions earlier 2316than 2.5. An alternative way to declare that a function has no side 2317effects, which works in the current version and in some older versions, 2318is as follows: 2319 2320@smallexample 2321typedef int intfn (); 2322 2323extern const intfn square; 2324@end smallexample 2325 2326This approach does not work in GNU C++ from 2.6.0 on, since the language 2327specifies that the @samp{const} must be attached to the return value. 2328 2329@item constructor 2330@itemx destructor 2331@itemx constructor (@var{priority}) 2332@itemx destructor (@var{priority}) 2333@cindex @code{constructor} function attribute 2334@cindex @code{destructor} function attribute 2335The @code{constructor} attribute causes the function to be called 2336automatically before execution enters @code{main ()}. Similarly, the 2337@code{destructor} attribute causes the function to be called 2338automatically after @code{main ()} has completed or @code{exit ()} has 2339been called. Functions with these attributes are useful for 2340initializing data that will be used implicitly during the execution of 2341the program. 2342 2343You may provide an optional integer priority to control the order in 2344which constructor and destructor functions are run. A constructor 2345with a smaller priority number runs before a constructor with a larger 2346priority number; the opposite relationship holds for destructors. So, 2347if you have a constructor that allocates a resource and a destructor 2348that deallocates the same resource, both functions typically have the 2349same priority. The priorities for constructor and destructor 2350functions are the same as those specified for namespace-scope C++ 2351objects (@pxref{C++ Attributes}). 2352 2353These attributes are not currently implemented for Objective-C@. 2354 2355@item deprecated 2356@itemx deprecated (@var{msg}) 2357@cindex @code{deprecated} attribute. 2358The @code{deprecated} attribute results in a warning if the function 2359is used anywhere in the source file. This is useful when identifying 2360functions that are expected to be removed in a future version of a 2361program. The warning also includes the location of the declaration 2362of the deprecated function, to enable users to easily find further 2363information about why the function is deprecated, or what they should 2364do instead. Note that the warnings only occurs for uses: 2365 2366@smallexample 2367int old_fn () __attribute__ ((deprecated)); 2368int old_fn (); 2369int (*fn_ptr)() = old_fn; 2370@end smallexample 2371 2372results in a warning on line 3 but not line 2. The optional msg 2373argument, which must be a string, will be printed in the warning if 2374present. 2375 2376The @code{deprecated} attribute can also be used for variables and 2377types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) 2378 2379@item disinterrupt 2380@cindex @code{disinterrupt} attribute 2381On Epiphany and MeP targets, this attribute causes the compiler to emit 2382instructions to disable interrupts for the duration of the given 2383function. 2384 2385@item dllexport 2386@cindex @code{__declspec(dllexport)} 2387On Microsoft Windows targets and Symbian OS targets the 2388@code{dllexport} attribute causes the compiler to provide a global 2389pointer to a pointer in a DLL, so that it can be referenced with the 2390@code{dllimport} attribute. On Microsoft Windows targets, the pointer 2391name is formed by combining @code{_imp__} and the function or variable 2392name. 2393 2394You can use @code{__declspec(dllexport)} as a synonym for 2395@code{__attribute__ ((dllexport))} for compatibility with other 2396compilers. 2397 2398On systems that support the @code{visibility} attribute, this 2399attribute also implies ``default'' visibility. It is an error to 2400explicitly specify any other visibility. 2401 2402In previous versions of GCC, the @code{dllexport} attribute was ignored 2403for inlined functions, unless the @option{-fkeep-inline-functions} flag 2404had been used. The default behaviour now is to emit all dllexported 2405inline functions; however, this can cause object file-size bloat, in 2406which case the old behaviour can be restored by using 2407@option{-fno-keep-inline-dllexport}. 2408 2409The attribute is also ignored for undefined symbols. 2410 2411When applied to C++ classes, the attribute marks defined non-inlined 2412member functions and static data members as exports. Static consts 2413initialized in-class are not marked unless they are also defined 2414out-of-class. 2415 2416For Microsoft Windows targets there are alternative methods for 2417including the symbol in the DLL's export table such as using a 2418@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using 2419the @option{--export-all} linker flag. 2420 2421@item dllimport 2422@cindex @code{__declspec(dllimport)} 2423On Microsoft Windows and Symbian OS targets, the @code{dllimport} 2424attribute causes the compiler to reference a function or variable via 2425a global pointer to a pointer that is set up by the DLL exporting the 2426symbol. The attribute implies @code{extern}. On Microsoft Windows 2427targets, the pointer name is formed by combining @code{_imp__} and the 2428function or variable name. 2429 2430You can use @code{__declspec(dllimport)} as a synonym for 2431@code{__attribute__ ((dllimport))} for compatibility with other 2432compilers. 2433 2434On systems that support the @code{visibility} attribute, this 2435attribute also implies ``default'' visibility. It is an error to 2436explicitly specify any other visibility. 2437 2438Currently, the attribute is ignored for inlined functions. If the 2439attribute is applied to a symbol @emph{definition}, an error is reported. 2440If a symbol previously declared @code{dllimport} is later defined, the 2441attribute is ignored in subsequent references, and a warning is emitted. 2442The attribute is also overridden by a subsequent declaration as 2443@code{dllexport}. 2444 2445When applied to C++ classes, the attribute marks non-inlined 2446member functions and static data members as imports. However, the 2447attribute is ignored for virtual methods to allow creation of vtables 2448using thunks. 2449 2450On the SH Symbian OS target the @code{dllimport} attribute also has 2451another affect---it can cause the vtable and run-time type information 2452for a class to be exported. This happens when the class has a 2453dllimport'ed constructor or a non-inline, non-pure virtual function 2454and, for either of those two conditions, the class also has an inline 2455constructor or destructor and has a key function that is defined in 2456the current translation unit. 2457 2458For Microsoft Windows based targets the use of the @code{dllimport} 2459attribute on functions is not necessary, but provides a small 2460performance benefit by eliminating a thunk in the DLL@. The use of the 2461@code{dllimport} attribute on imported variables was required on older 2462versions of the GNU linker, but can now be avoided by passing the 2463@option{--enable-auto-import} switch to the GNU linker. As with 2464functions, using the attribute for a variable eliminates a thunk in 2465the DLL@. 2466 2467One drawback to using this attribute is that a pointer to a 2468@emph{variable} marked as @code{dllimport} cannot be used as a constant 2469address. However, a pointer to a @emph{function} with the 2470@code{dllimport} attribute can be used as a constant initializer; in 2471this case, the address of a stub function in the import lib is 2472referenced. On Microsoft Windows targets, the attribute can be disabled 2473for functions by setting the @option{-mnop-fun-dllimport} flag. 2474 2475@item eightbit_data 2476@cindex eight bit data on the H8/300, H8/300H, and H8S 2477Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 2478variable should be placed into the eight bit data section. 2479The compiler will generate more efficient code for certain operations 2480on data in the eight bit data area. Note the eight bit data area is limited to 2481256 bytes of data. 2482 2483You must use GAS and GLD from GNU binutils version 2.7 or later for 2484this attribute to work correctly. 2485 2486@item exception_handler 2487@cindex exception handler functions on the Blackfin processor 2488Use this attribute on the Blackfin to indicate that the specified function 2489is an exception handler. The compiler will generate function entry and 2490exit sequences suitable for use in an exception handler when this 2491attribute is present. 2492 2493@item externally_visible 2494@cindex @code{externally_visible} attribute. 2495This attribute, attached to a global variable or function, nullifies 2496the effect of the @option{-fwhole-program} command-line option, so the 2497object remains visible outside the current compilation unit. If @option{-fwhole-program} is used together with @option{-flto} and @command{gold} is used as the linker plugin, @code{externally_visible} attributes are automatically added to functions (not variable yet due to a current @command{gold} issue) that are accessed outside of LTO objects according to resolution file produced by @command{gold}. For other linkers that cannot generate resolution file, explicit @code{externally_visible} attributes are still necessary. 2498 2499@item far 2500@cindex functions which handle memory bank switching 2501On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to 2502use a calling convention that takes care of switching memory banks when 2503entering and leaving a function. This calling convention is also the 2504default when using the @option{-mlong-calls} option. 2505 2506On 68HC12 the compiler will use the @code{call} and @code{rtc} instructions 2507to call and return from a function. 2508 2509On 68HC11 the compiler will generate a sequence of instructions 2510to invoke a board-specific routine to switch the memory bank and call the 2511real function. The board-specific routine simulates a @code{call}. 2512At the end of a function, it will jump to a board-specific routine 2513instead of using @code{rts}. The board-specific return routine simulates 2514the @code{rtc}. 2515 2516On MeP targets this causes the compiler to use a calling convention 2517which assumes the called function is too far away for the built-in 2518addressing modes. 2519 2520@item fast_interrupt 2521@cindex interrupt handler functions 2522Use this attribute on the M32C and RX ports to indicate that the specified 2523function is a fast interrupt handler. This is just like the 2524@code{interrupt} attribute, except that @code{freit} is used to return 2525instead of @code{reit}. 2526 2527@item fastcall 2528@cindex functions that pop the argument stack on the 386 2529On the Intel 386, the @code{fastcall} attribute causes the compiler to 2530pass the first argument (if of integral type) in the register ECX and 2531the second argument (if of integral type) in the register EDX@. Subsequent 2532and other typed arguments are passed on the stack. The called function will 2533pop the arguments off the stack. If the number of arguments is variable all 2534arguments are pushed on the stack. 2535 2536@item thiscall 2537@cindex functions that pop the argument stack on the 386 2538On the Intel 386, the @code{thiscall} attribute causes the compiler to 2539pass the first argument (if of integral type) in the register ECX. 2540Subsequent and other typed arguments are passed on the stack. The called 2541function will pop the arguments off the stack. 2542If the number of arguments is variable all arguments are pushed on the 2543stack. 2544The @code{thiscall} attribute is intended for C++ non-static member functions. 2545As gcc extension this calling convention can be used for C-functions 2546and for static member methods. 2547 2548@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) 2549@cindex @code{format} function attribute 2550@opindex Wformat 2551The @code{format} attribute specifies that a function takes @code{printf}, 2552@code{scanf}, @code{strftime} or @code{strfmon} style arguments which 2553should be type-checked against a format string. For example, the 2554declaration: 2555 2556@smallexample 2557extern int 2558my_printf (void *my_object, const char *my_format, ...) 2559 __attribute__ ((format (printf, 2, 3))); 2560@end smallexample 2561 2562@noindent 2563causes the compiler to check the arguments in calls to @code{my_printf} 2564for consistency with the @code{printf} style format string argument 2565@code{my_format}. 2566 2567The parameter @var{archetype} determines how the format string is 2568interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}, 2569@code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or 2570@code{strfmon}. (You can also use @code{__printf__}, 2571@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On 2572MinGW targets, @code{ms_printf}, @code{ms_scanf}, and 2573@code{ms_strftime} are also present. 2574@var{archtype} values such as @code{printf} refer to the formats accepted 2575by the system's C run-time library, while @code{gnu_} values always refer 2576to the formats accepted by the GNU C Library. On Microsoft Windows 2577targets, @code{ms_} values refer to the formats accepted by the 2578@file{msvcrt.dll} library. 2579The parameter @var{string-index} 2580specifies which argument is the format string argument (starting 2581from 1), while @var{first-to-check} is the number of the first 2582argument to check against the format string. For functions 2583where the arguments are not available to be checked (such as 2584@code{vprintf}), specify the third parameter as zero. In this case the 2585compiler only checks the format string for consistency. For 2586@code{strftime} formats, the third parameter is required to be zero. 2587Since non-static C++ methods have an implicit @code{this} argument, the 2588arguments of such methods should be counted from two, not one, when 2589giving values for @var{string-index} and @var{first-to-check}. 2590 2591In the example above, the format string (@code{my_format}) is the second 2592argument of the function @code{my_print}, and the arguments to check 2593start with the third argument, so the correct parameters for the format 2594attribute are 2 and 3. 2595 2596@opindex ffreestanding 2597@opindex fno-builtin 2598The @code{format} attribute allows you to identify your own functions 2599which take format strings as arguments, so that GCC can check the 2600calls to these functions for errors. The compiler always (unless 2601@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats 2602for the standard library functions @code{printf}, @code{fprintf}, 2603@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, 2604@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such 2605warnings are requested (using @option{-Wformat}), so there is no need to 2606modify the header file @file{stdio.h}. In C99 mode, the functions 2607@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and 2608@code{vsscanf} are also checked. Except in strictly conforming C 2609standard modes, the X/Open function @code{strfmon} is also checked as 2610are @code{printf_unlocked} and @code{fprintf_unlocked}. 2611@xref{C Dialect Options,,Options Controlling C Dialect}. 2612 2613For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is 2614recognized in the same context. Declarations including these format attributes 2615will be parsed for correct syntax, however the result of checking of such format 2616strings is not yet defined, and will not be carried out by this version of the 2617compiler. 2618 2619The target may also provide additional types of format checks. 2620@xref{Target Format Checks,,Format Checks Specific to Particular 2621Target Machines}. 2622 2623@item format_arg (@var{string-index}) 2624@cindex @code{format_arg} function attribute 2625@opindex Wformat-nonliteral 2626The @code{format_arg} attribute specifies that a function takes a format 2627string for a @code{printf}, @code{scanf}, @code{strftime} or 2628@code{strfmon} style function and modifies it (for example, to translate 2629it into another language), so the result can be passed to a 2630@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style 2631function (with the remaining arguments to the format function the same 2632as they would have been for the unmodified string). For example, the 2633declaration: 2634 2635@smallexample 2636extern char * 2637my_dgettext (char *my_domain, const char *my_format) 2638 __attribute__ ((format_arg (2))); 2639@end smallexample 2640 2641@noindent 2642causes the compiler to check the arguments in calls to a @code{printf}, 2643@code{scanf}, @code{strftime} or @code{strfmon} type function, whose 2644format string argument is a call to the @code{my_dgettext} function, for 2645consistency with the format string argument @code{my_format}. If the 2646@code{format_arg} attribute had not been specified, all the compiler 2647could tell in such calls to format functions would be that the format 2648string argument is not constant; this would generate a warning when 2649@option{-Wformat-nonliteral} is used, but the calls could not be checked 2650without the attribute. 2651 2652The parameter @var{string-index} specifies which argument is the format 2653string argument (starting from one). Since non-static C++ methods have 2654an implicit @code{this} argument, the arguments of such methods should 2655be counted from two. 2656 2657The @code{format-arg} attribute allows you to identify your own 2658functions which modify format strings, so that GCC can check the 2659calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} 2660type function whose operands are a call to one of your own function. 2661The compiler always treats @code{gettext}, @code{dgettext}, and 2662@code{dcgettext} in this manner except when strict ISO C support is 2663requested by @option{-ansi} or an appropriate @option{-std} option, or 2664@option{-ffreestanding} or @option{-fno-builtin} 2665is used. @xref{C Dialect Options,,Options 2666Controlling C Dialect}. 2667 2668For Objective-C dialects, the @code{format-arg} attribute may refer to an 2669@code{NSString} reference for compatibility with the @code{format} attribute 2670above. 2671 2672The target may also allow additional types in @code{format-arg} attributes. 2673@xref{Target Format Checks,,Format Checks Specific to Particular 2674Target Machines}. 2675 2676@item function_vector 2677@cindex calling functions through the function vector on H8/300, M16C, M32C and SH2A processors 2678Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 2679function should be called through the function vector. Calling a 2680function through the function vector will reduce code size, however; 2681the function vector has a limited size (maximum 128 entries on the H8/300 2682and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector. 2683 2684In SH2A target, this attribute declares a function to be called using the 2685TBR relative addressing mode. The argument to this attribute is the entry 2686number of the same function in a vector table containing all the TBR 2687relative addressable functions. For the successful jump, register TBR 2688should contain the start address of this TBR relative vector table. 2689In the startup routine of the user application, user needs to care of this 2690TBR register initialization. The TBR relative vector table can have at 2691max 256 function entries. The jumps to these functions will be generated 2692using a SH2A specific, non delayed branch instruction JSR/N @@(disp8,TBR). 2693You must use GAS and GLD from GNU binutils version 2.7 or later for 2694this attribute to work correctly. 2695 2696Please refer the example of M16C target, to see the use of this 2697attribute while declaring a function, 2698 2699In an application, for a function being called once, this attribute will 2700save at least 8 bytes of code; and if other successive calls are being 2701made to the same function, it will save 2 bytes of code per each of these 2702calls. 2703 2704On M16C/M32C targets, the @code{function_vector} attribute declares a 2705special page subroutine call function. Use of this attribute reduces 2706the code size by 2 bytes for each call generated to the 2707subroutine. The argument to the attribute is the vector number entry 2708from the special page vector table which contains the 16 low-order 2709bits of the subroutine's entry address. Each vector table has special 2710page number (18 to 255) which are used in @code{jsrs} instruction. 2711Jump addresses of the routines are generated by adding 0x0F0000 (in 2712case of M16C targets) or 0xFF0000 (in case of M32C targets), to the 2 2713byte addresses set in the vector table. Therefore you need to ensure 2714that all the special page vector routines should get mapped within the 2715address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF 2716(for M32C). 2717 2718In the following example 2 bytes will be saved for each call to 2719function @code{foo}. 2720 2721@smallexample 2722void foo (void) __attribute__((function_vector(0x18))); 2723void foo (void) 2724@{ 2725@} 2726 2727void bar (void) 2728@{ 2729 foo(); 2730@} 2731@end smallexample 2732 2733If functions are defined in one file and are called in another file, 2734then be sure to write this declaration in both files. 2735 2736This attribute is ignored for R8C target. 2737 2738@item ifunc ("@var{resolver}") 2739@cindex @code{ifunc} attribute 2740The @code{ifunc} attribute is used to mark a function as an indirect 2741function using the STT_GNU_IFUNC symbol type extension to the ELF 2742standard. This allows the resolution of the symbol value to be 2743determined dynamically at load time, and an optimized version of the 2744routine can be selected for the particular processor or other system 2745characteristics determined then. To use this attribute, first define 2746the implementation functions available, and a resolver function that 2747returns a pointer to the selected implementation function. The 2748implementation functions' declarations must match the API of the 2749function being implemented, the resolver's declaration is be a 2750function returning pointer to void function returning void: 2751 2752@smallexample 2753void *my_memcpy (void *dst, const void *src, size_t len) 2754@{ 2755 @dots{} 2756@} 2757 2758static void (*resolve_memcpy (void)) (void) 2759@{ 2760 return my_memcpy; // we'll just always select this routine 2761@} 2762@end smallexample 2763 2764The exported header file declaring the function the user calls would 2765contain: 2766 2767@smallexample 2768extern void *memcpy (void *, const void *, size_t); 2769@end smallexample 2770 2771allowing the user to call this as a regular function, unaware of the 2772implementation. Finally, the indirect function needs to be defined in 2773the same translation unit as the resolver function: 2774 2775@smallexample 2776void *memcpy (void *, const void *, size_t) 2777 __attribute__ ((ifunc ("resolve_memcpy"))); 2778@end smallexample 2779 2780Indirect functions cannot be weak, and require a recent binutils (at 2781least version 2.20.1), and GNU C library (at least version 2.11.1). 2782 2783@item interrupt 2784@cindex interrupt handler functions 2785Use this attribute on the ARM, AVR, CR16, Epiphany, M32C, M32R/D, m68k, MeP, MIPS, 2786RL78, RX and Xstormy16 ports to indicate that the specified function is an 2787interrupt handler. The compiler will generate function entry and exit 2788sequences suitable for use in an interrupt handler when this attribute 2789is present. With Epiphany targets it may also generate a special section with 2790code to initialize the interrupt vector table. 2791 2792Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, MicroBlaze, 2793and SH processors can be specified via the @code{interrupt_handler} attribute. 2794 2795Note, on the AVR, the hardware globally disables interrupts when an 2796interrupt is executed. The first instruction of an interrupt handler 2797declared with this attribute will be a @code{SEI} instruction to 2798re-enable interrupts. See also the @code{signal} function attribute 2799that does not insert a @code{SEI} instuction. If both @code{signal} and 2800@code{interrupt} are specified for the same function, @code{signal} 2801will be silently ignored. 2802 2803Note, for the ARM, you can specify the kind of interrupt to be handled by 2804adding an optional parameter to the interrupt attribute like this: 2805 2806@smallexample 2807void f () __attribute__ ((interrupt ("IRQ"))); 2808@end smallexample 2809 2810Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@. 2811 2812On ARMv7-M the interrupt type is ignored, and the attribute means the function 2813may be called with a word aligned stack pointer. 2814 2815On Epiphany targets one or more optional parameters can be added like this: 2816 2817@smallexample 2818void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); 2819@end smallexample 2820 2821Permissible values for these parameters are: @w{@code{reset}}, 2822@w{@code{software_exception}}, @w{@code{page_miss}}, 2823@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}}, 2824@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}. 2825Multiple parameters indicate that multiple entries in the interrupt 2826vector table should be initialized for this function, i.e. for each 2827parameter @w{@var{name}}, a jump to the function will be emitted in 2828the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted 2829entirely, in which case no interrupt vector table entry will be provided. 2830 2831Note, on Epiphany targets, interrupts are enabled inside the function 2832unless the @code{disinterrupt} attribute is also specified. 2833 2834On Epiphany targets, you can also use the following attribute to 2835modify the behavior of an interrupt handler: 2836@table @code 2837@item forwarder_section 2838@cindex @code{forwarder_section} attribute 2839The interrupt handler may be in external memory which cannot be 2840reached by a branch instruction, so generate a local memory trampoline 2841to transfer control. The single parameter identifies the section where 2842the trampoline will be placed. 2843@end table 2844 2845The following examples are all valid uses of these attributes on 2846Epiphany targets: 2847@smallexample 2848void __attribute__ ((interrupt)) universal_handler (); 2849void __attribute__ ((interrupt ("dma1"))) dma1_handler (); 2850void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); 2851void __attribute__ ((interrupt ("timer0"), disinterrupt)) 2852 fast_timer_handler (); 2853void __attribute__ ((interrupt ("dma0, dma1"), forwarder_section ("tramp"))) 2854 external_dma_handler (); 2855@end smallexample 2856 2857On MIPS targets, you can use the following attributes to modify the behavior 2858of an interrupt handler: 2859@table @code 2860@item use_shadow_register_set 2861@cindex @code{use_shadow_register_set} attribute 2862Assume that the handler uses a shadow register set, instead of 2863the main general-purpose registers. 2864 2865@item keep_interrupts_masked 2866@cindex @code{keep_interrupts_masked} attribute 2867Keep interrupts masked for the whole function. Without this attribute, 2868GCC tries to reenable interrupts for as much of the function as it can. 2869 2870@item use_debug_exception_return 2871@cindex @code{use_debug_exception_return} attribute 2872Return using the @code{deret} instruction. Interrupt handlers that don't 2873have this attribute return using @code{eret} instead. 2874@end table 2875 2876You can use any combination of these attributes, as shown below: 2877@smallexample 2878void __attribute__ ((interrupt)) v0 (); 2879void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); 2880void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); 2881void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); 2882void __attribute__ ((interrupt, use_shadow_register_set, 2883 keep_interrupts_masked)) v4 (); 2884void __attribute__ ((interrupt, use_shadow_register_set, 2885 use_debug_exception_return)) v5 (); 2886void __attribute__ ((interrupt, keep_interrupts_masked, 2887 use_debug_exception_return)) v6 (); 2888void __attribute__ ((interrupt, use_shadow_register_set, 2889 keep_interrupts_masked, 2890 use_debug_exception_return)) v7 (); 2891@end smallexample 2892 2893On RL78, use @code{brk_interrupt} instead of @code{interrupt} for 2894handlers intended to be used with the @code{BRK} opcode (i.e. those 2895that must end with @code{RETB} instead of @code{RETI}). 2896 2897@item interrupt_handler 2898@cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors 2899Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to 2900indicate that the specified function is an interrupt handler. The compiler 2901will generate function entry and exit sequences suitable for use in an 2902interrupt handler when this attribute is present. 2903 2904@item interrupt_thread 2905@cindex interrupt thread functions on fido 2906Use this attribute on fido, a subarchitecture of the m68k, to indicate 2907that the specified function is an interrupt handler that is designed 2908to run as a thread. The compiler omits generate prologue/epilogue 2909sequences and replaces the return instruction with a @code{sleep} 2910instruction. This attribute is available only on fido. 2911 2912@item isr 2913@cindex interrupt service routines on ARM 2914Use this attribute on ARM to write Interrupt Service Routines. This is an 2915alias to the @code{interrupt} attribute above. 2916 2917@item kspisusp 2918@cindex User stack pointer in interrupts on the Blackfin 2919When used together with @code{interrupt_handler}, @code{exception_handler} 2920or @code{nmi_handler}, code will be generated to load the stack pointer 2921from the USP register in the function prologue. 2922 2923@item l1_text 2924@cindex @code{l1_text} function attribute 2925This attribute specifies a function to be placed into L1 Instruction 2926SRAM@. The function will be put into a specific section named @code{.l1.text}. 2927With @option{-mfdpic}, function calls with a such function as the callee 2928or caller will use inlined PLT. 2929 2930@item l2 2931@cindex @code{l2} function attribute 2932On the Blackfin, this attribute specifies a function to be placed into L2 2933SRAM. The function will be put into a specific section named 2934@code{.l1.text}. With @option{-mfdpic}, callers of such functions will use 2935an inlined PLT. 2936 2937@item leaf 2938@cindex @code{leaf} function attribute 2939Calls to external functions with this attribute must return to the current 2940compilation unit only by return or by exception handling. In particular, leaf 2941functions are not allowed to call callback function passed to it from the current 2942compilation unit or directly call functions exported by the unit or longjmp 2943into the unit. Leaf function might still call functions from other compilation 2944units and thus they are not necessarily leaf in the sense that they contain no 2945function calls at all. 2946 2947The attribute is intended for library functions to improve dataflow analysis. 2948The compiler takes the hint that any data not escaping the current compilation unit can 2949not be used or modified by the leaf function. For example, the @code{sin} function 2950is a leaf function, but @code{qsort} is not. 2951 2952Note that leaf functions might invoke signals and signal handlers might be 2953defined in the current compilation unit and use static variables. The only 2954compliant way to write such a signal handler is to declare such variables 2955@code{volatile}. 2956 2957The attribute has no effect on functions defined within the current compilation 2958unit. This is to allow easy merging of multiple compilation units into one, 2959for example, by using the link time optimization. For this reason the 2960attribute is not allowed on types to annotate indirect calls. 2961 2962@item long_call/short_call 2963@cindex indirect calls on ARM 2964This attribute specifies how a particular function is called on 2965ARM and Epiphany. Both attributes override the 2966@option{-mlong-calls} (@pxref{ARM Options}) 2967command-line switch and @code{#pragma long_calls} settings. The 2968@code{long_call} attribute indicates that the function might be far 2969away from the call site and require a different (more expensive) 2970calling sequence. The @code{short_call} attribute always places 2971the offset to the function from the call site into the @samp{BL} 2972instruction directly. 2973 2974@item longcall/shortcall 2975@cindex functions called via pointer on the RS/6000 and PowerPC 2976On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute 2977indicates that the function might be far away from the call site and 2978require a different (more expensive) calling sequence. The 2979@code{shortcall} attribute indicates that the function is always close 2980enough for the shorter calling sequence to be used. These attributes 2981override both the @option{-mlongcall} switch and, on the RS/6000 and 2982PowerPC, the @code{#pragma longcall} setting. 2983 2984@xref{RS/6000 and PowerPC Options}, for more information on whether long 2985calls are necessary. 2986 2987@item long_call/near/far 2988@cindex indirect calls on MIPS 2989These attributes specify how a particular function is called on MIPS@. 2990The attributes override the @option{-mlong-calls} (@pxref{MIPS Options}) 2991command-line switch. The @code{long_call} and @code{far} attributes are 2992synonyms, and cause the compiler to always call 2993the function by first loading its address into a register, and then using 2994the contents of that register. The @code{near} attribute has the opposite 2995effect; it specifies that non-PIC calls should be made using the more 2996efficient @code{jal} instruction. 2997 2998@item malloc 2999@cindex @code{malloc} attribute 3000The @code{malloc} attribute is used to tell the compiler that a function 3001may be treated as if any non-@code{NULL} pointer it returns cannot 3002alias any other pointer valid when the function returns and that the memory 3003has undefined content. 3004This will often improve optimization. 3005Standard functions with this property include @code{malloc} and 3006@code{calloc}. @code{realloc}-like functions do not have this 3007property as the memory pointed to does not have undefined content. 3008 3009@item mips16/nomips16 3010@cindex @code{mips16} attribute 3011@cindex @code{nomips16} attribute 3012 3013On MIPS targets, you can use the @code{mips16} and @code{nomips16} 3014function attributes to locally select or turn off MIPS16 code generation. 3015A function with the @code{mips16} attribute is emitted as MIPS16 code, 3016while MIPS16 code generation is disabled for functions with the 3017@code{nomips16} attribute. These attributes override the 3018@option{-mips16} and @option{-mno-mips16} options on the command line 3019(@pxref{MIPS Options}). 3020 3021When compiling files containing mixed MIPS16 and non-MIPS16 code, the 3022preprocessor symbol @code{__mips16} reflects the setting on the command line, 3023not that within individual functions. Mixed MIPS16 and non-MIPS16 code 3024may interact badly with some GCC extensions such as @code{__builtin_apply} 3025(@pxref{Constructing Calls}). 3026 3027@item model (@var{model-name}) 3028@cindex function addressability on the M32R/D 3029@cindex variable addressability on the IA-64 3030 3031On the M32R/D, use this attribute to set the addressability of an 3032object, and of the code generated for a function. The identifier 3033@var{model-name} is one of @code{small}, @code{medium}, or 3034@code{large}, representing each of the code models. 3035 3036Small model objects live in the lower 16MB of memory (so that their 3037addresses can be loaded with the @code{ld24} instruction), and are 3038callable with the @code{bl} instruction. 3039 3040Medium model objects may live anywhere in the 32-bit address space (the 3041compiler will generate @code{seth/add3} instructions to load their addresses), 3042and are callable with the @code{bl} instruction. 3043 3044Large model objects may live anywhere in the 32-bit address space (the 3045compiler will generate @code{seth/add3} instructions to load their addresses), 3046and may not be reachable with the @code{bl} instruction (the compiler will 3047generate the much slower @code{seth/add3/jl} instruction sequence). 3048 3049On IA-64, use this attribute to set the addressability of an object. 3050At present, the only supported identifier for @var{model-name} is 3051@code{small}, indicating addressability via ``small'' (22-bit) 3052addresses (so that their addresses can be loaded with the @code{addl} 3053instruction). Caveat: such addressing is by definition not position 3054independent and hence this attribute must not be used for objects 3055defined by shared libraries. 3056 3057@item ms_abi/sysv_abi 3058@cindex @code{ms_abi} attribute 3059@cindex @code{sysv_abi} attribute 3060 3061On 32-bit and 64-bit (i?86|x86_64)-*-* targets, you can use an ABI attribute 3062to indicate which calling convention should be used for a function. The 3063@code{ms_abi} attribute tells the compiler to use the Microsoft ABI, 3064while the @code{sysv_abi} attribute tells the compiler to use the ABI 3065used on GNU/Linux and other systems. The default is to use the Microsoft ABI 3066when targeting Windows. On all other systems, the default is the x86/AMD ABI. 3067 3068Note, the @code{ms_abi} attribute for Windows 64-bit targets currently 3069requires the @option{-maccumulate-outgoing-args} option. 3070 3071@item callee_pop_aggregate_return (@var{number}) 3072@cindex @code{callee_pop_aggregate_return} attribute 3073 3074On 32-bit i?86-*-* targets, you can control by those attribute for 3075aggregate return in memory, if the caller is responsible to pop the hidden 3076pointer together with the rest of the arguments - @var{number} equal to 3077zero -, or if the callee is responsible to pop hidden pointer - @var{number} 3078equal to one. The default i386 ABI assumes that the callee pops the 3079stack for hidden pointer. 3080 3081Note, that on 32-bit i386 Windows targets the compiler assumes that the 3082caller pops the stack for hidden pointer. 3083 3084@item ms_hook_prologue 3085@cindex @code{ms_hook_prologue} attribute 3086 3087On 32 bit i[34567]86-*-* targets and 64 bit x86_64-*-* targets, you can use 3088this function attribute to make gcc generate the "hot-patching" function 3089prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 3090and newer. 3091 3092@item naked 3093@cindex function without a prologue/epilogue code 3094Use this attribute on the ARM, AVR, MCORE, RX and SPU ports to indicate that 3095the specified function does not need prologue/epilogue sequences generated by 3096the compiler. It is up to the programmer to provide these sequences. The 3097only statements that can be safely included in naked functions are 3098@code{asm} statements that do not have operands. All other statements, 3099including declarations of local variables, @code{if} statements, and so 3100forth, should be avoided. Naked functions should be used to implement the 3101body of an assembly function, while allowing the compiler to construct 3102the requisite function declaration for the assembler. 3103 3104@item near 3105@cindex functions which do not handle memory bank switching on 68HC11/68HC12 3106On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to 3107use the normal calling convention based on @code{jsr} and @code{rts}. 3108This attribute can be used to cancel the effect of the @option{-mlong-calls} 3109option. 3110 3111On MeP targets this attribute causes the compiler to assume the called 3112function is close enough to use the normal calling convention, 3113overriding the @code{-mtf} command line option. 3114 3115@item nesting 3116@cindex Allow nesting in an interrupt handler on the Blackfin processor. 3117Use this attribute together with @code{interrupt_handler}, 3118@code{exception_handler} or @code{nmi_handler} to indicate that the function 3119entry code should enable nested interrupts or exceptions. 3120 3121@item nmi_handler 3122@cindex NMI handler functions on the Blackfin processor 3123Use this attribute on the Blackfin to indicate that the specified function 3124is an NMI handler. The compiler will generate function entry and 3125exit sequences suitable for use in an NMI handler when this 3126attribute is present. 3127 3128@item no_instrument_function 3129@cindex @code{no_instrument_function} function attribute 3130@opindex finstrument-functions 3131If @option{-finstrument-functions} is given, profiling function calls will 3132be generated at entry and exit of most user-compiled functions. 3133Functions with this attribute will not be so instrumented. 3134 3135@item no_split_stack 3136@cindex @code{no_split_stack} function attribute 3137@opindex fsplit-stack 3138If @option{-fsplit-stack} is given, functions will have a small 3139prologue which decides whether to split the stack. Functions with the 3140@code{no_split_stack} attribute will not have that prologue, and thus 3141may run with only a small amount of stack space available. 3142 3143@item noinline 3144@cindex @code{noinline} function attribute 3145This function attribute prevents a function from being considered for 3146inlining. 3147@c Don't enumerate the optimizations by name here; we try to be 3148@c future-compatible with this mechanism. 3149If the function does not have side-effects, there are optimizations 3150other than inlining that causes function calls to be optimized away, 3151although the function call is live. To keep such calls from being 3152optimized away, put 3153@smallexample 3154asm (""); 3155@end smallexample 3156(@pxref{Extended Asm}) in the called function, to serve as a special 3157side-effect. 3158 3159@item noclone 3160@cindex @code{noclone} function attribute 3161This function attribute prevents a function from being considered for 3162cloning - a mechanism which produces specialized copies of functions 3163and which is (currently) performed by interprocedural constant 3164propagation. 3165 3166@item nonnull (@var{arg-index}, @dots{}) 3167@cindex @code{nonnull} function attribute 3168The @code{nonnull} attribute specifies that some function parameters should 3169be non-null pointers. For instance, the declaration: 3170 3171@smallexample 3172extern void * 3173my_memcpy (void *dest, const void *src, size_t len) 3174 __attribute__((nonnull (1, 2))); 3175@end smallexample 3176 3177@noindent 3178causes the compiler to check that, in calls to @code{my_memcpy}, 3179arguments @var{dest} and @var{src} are non-null. If the compiler 3180determines that a null pointer is passed in an argument slot marked 3181as non-null, and the @option{-Wnonnull} option is enabled, a warning 3182is issued. The compiler may also choose to make optimizations based 3183on the knowledge that certain function arguments will not be null. 3184 3185If no argument index list is given to the @code{nonnull} attribute, 3186all pointer arguments are marked as non-null. To illustrate, the 3187following declaration is equivalent to the previous example: 3188 3189@smallexample 3190extern void * 3191my_memcpy (void *dest, const void *src, size_t len) 3192 __attribute__((nonnull)); 3193@end smallexample 3194 3195@item noreturn 3196@cindex @code{noreturn} function attribute 3197A few standard library functions, such as @code{abort} and @code{exit}, 3198cannot return. GCC knows this automatically. Some programs define 3199their own functions that never return. You can declare them 3200@code{noreturn} to tell the compiler this fact. For example, 3201 3202@smallexample 3203@group 3204void fatal () __attribute__ ((noreturn)); 3205 3206void 3207fatal (/* @r{@dots{}} */) 3208@{ 3209 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ 3210 exit (1); 3211@} 3212@end group 3213@end smallexample 3214 3215The @code{noreturn} keyword tells the compiler to assume that 3216@code{fatal} cannot return. It can then optimize without regard to what 3217would happen if @code{fatal} ever did return. This makes slightly 3218better code. More importantly, it helps avoid spurious warnings of 3219uninitialized variables. 3220 3221The @code{noreturn} keyword does not affect the exceptional path when that 3222applies: a @code{noreturn}-marked function may still return to the caller 3223by throwing an exception or calling @code{longjmp}. 3224 3225Do not assume that registers saved by the calling function are 3226restored before calling the @code{noreturn} function. 3227 3228It does not make sense for a @code{noreturn} function to have a return 3229type other than @code{void}. 3230 3231The attribute @code{noreturn} is not implemented in GCC versions 3232earlier than 2.5. An alternative way to declare that a function does 3233not return, which works in the current version and in some older 3234versions, is as follows: 3235 3236@smallexample 3237typedef void voidfn (); 3238 3239volatile voidfn fatal; 3240@end smallexample 3241 3242This approach does not work in GNU C++. 3243 3244@item nothrow 3245@cindex @code{nothrow} function attribute 3246The @code{nothrow} attribute is used to inform the compiler that a 3247function cannot throw an exception. For example, most functions in 3248the standard C library can be guaranteed not to throw an exception 3249with the notable exceptions of @code{qsort} and @code{bsearch} that 3250take function pointer arguments. The @code{nothrow} attribute is not 3251implemented in GCC versions earlier than 3.3. 3252 3253@item optimize 3254@cindex @code{optimize} function attribute 3255The @code{optimize} attribute is used to specify that a function is to 3256be compiled with different optimization options than specified on the 3257command line. Arguments can either be numbers or strings. Numbers 3258are assumed to be an optimization level. Strings that begin with 3259@code{O} are assumed to be an optimization option, while other options 3260are assumed to be used with a @code{-f} prefix. You can also use the 3261@samp{#pragma GCC optimize} pragma to set the optimization options 3262that affect more than one function. 3263@xref{Function Specific Option Pragmas}, for details about the 3264@samp{#pragma GCC optimize} pragma. 3265 3266This can be used for instance to have frequently executed functions 3267compiled with more aggressive optimization options that produce faster 3268and larger code, while other functions can be called with less 3269aggressive options. 3270 3271@item OS_main/OS_task 3272@cindex @code{OS_main} AVR function attribute 3273@cindex @code{OS_task} AVR function attribute 3274On AVR, functions with the @code{OS_main} or @code{OS_task} attribute 3275do not save/restore any call-saved register in their prologue/epilogue. 3276 3277The @code{OS_main} attribute can be used when there @emph{is 3278guarantee} that interrupts are disabled at the time when the function 3279is entered. This will save resources when the stack pointer has to be 3280changed to set up a frame for local variables. 3281 3282The @code{OS_task} attribute can be used when there is @emph{no 3283guarantee} that interrupts are disabled at that time when the function 3284is entered like for, e@.g@. task functions in a multi-threading operating 3285system. In that case, changing the stack pointer register will be 3286guarded by save/clear/restore of the global interrupt enable flag. 3287 3288The differences to the @code{naked} function attribute are: 3289@itemize @bullet 3290@item @code{naked} functions do not have a return instruction whereas 3291@code{OS_main} and @code{OS_task} functions will have a @code{RET} or 3292@code{RETI} return instruction. 3293@item @code{naked} functions do not set up a frame for local variables 3294or a frame pointer whereas @code{OS_main} and @code{OS_task} do this 3295as needed. 3296@end itemize 3297 3298@item pcs 3299@cindex @code{pcs} function attribute 3300 3301The @code{pcs} attribute can be used to control the calling convention 3302used for a function on ARM. The attribute takes an argument that specifies 3303the calling convention to use. 3304 3305When compiling using the AAPCS ABI (or a variant of that) then valid 3306values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In 3307order to use a variant other than @code{"aapcs"} then the compiler must 3308be permitted to use the appropriate co-processor registers (i.e., the 3309VFP registers must be available in order to use @code{"aapcs-vfp"}). 3310For example, 3311 3312@smallexample 3313/* Argument passed in r0, and result returned in r0+r1. */ 3314double f2d (float) __attribute__((pcs("aapcs"))); 3315@end smallexample 3316 3317Variadic functions always use the @code{"aapcs"} calling convention and 3318the compiler will reject attempts to specify an alternative. 3319 3320@item pure 3321@cindex @code{pure} function attribute 3322Many functions have no effects except the return value and their 3323return value depends only on the parameters and/or global variables. 3324Such a function can be subject 3325to common subexpression elimination and loop optimization just as an 3326arithmetic operator would be. These functions should be declared 3327with the attribute @code{pure}. For example, 3328 3329@smallexample 3330int square (int) __attribute__ ((pure)); 3331@end smallexample 3332 3333@noindent 3334says that the hypothetical function @code{square} is safe to call 3335fewer times than the program says. 3336 3337Some of common examples of pure functions are @code{strlen} or @code{memcmp}. 3338Interesting non-pure functions are functions with infinite loops or those 3339depending on volatile memory or other system resource, that may change between 3340two consecutive calls (such as @code{feof} in a multithreading environment). 3341 3342The attribute @code{pure} is not implemented in GCC versions earlier 3343than 2.96. 3344 3345@item hot 3346@cindex @code{hot} function attribute 3347The @code{hot} attribute is used to inform the compiler that a function is a 3348hot spot of the compiled program. The function is optimized more aggressively 3349and on many target it is placed into special subsection of the text section so 3350all hot functions appears close together improving locality. 3351 3352When profile feedback is available, via @option{-fprofile-use}, hot functions 3353are automatically detected and this attribute is ignored. 3354 3355The @code{hot} attribute is not implemented in GCC versions earlier 3356than 4.3. 3357 3358@item cold 3359@cindex @code{cold} function attribute 3360The @code{cold} attribute is used to inform the compiler that a function is 3361unlikely executed. The function is optimized for size rather than speed and on 3362many targets it is placed into special subsection of the text section so all 3363cold functions appears close together improving code locality of non-cold parts 3364of program. The paths leading to call of cold functions within code are marked 3365as unlikely by the branch prediction mechanism. It is thus useful to mark 3366functions used to handle unlikely conditions, such as @code{perror}, as cold to 3367improve optimization of hot functions that do call marked functions in rare 3368occasions. 3369 3370When profile feedback is available, via @option{-fprofile-use}, hot functions 3371are automatically detected and this attribute is ignored. 3372 3373The @code{cold} attribute is not implemented in GCC versions earlier than 4.3. 3374 3375@item regparm (@var{number}) 3376@cindex @code{regparm} attribute 3377@cindex functions that are passed arguments in registers on the 386 3378On the Intel 386, the @code{regparm} attribute causes the compiler to 3379pass arguments number one to @var{number} if they are of integral type 3380in registers EAX, EDX, and ECX instead of on the stack. Functions that 3381take a variable number of arguments will continue to be passed all of their 3382arguments on the stack. 3383 3384Beware that on some ELF systems this attribute is unsuitable for 3385global functions in shared libraries with lazy binding (which is the 3386default). Lazy binding will send the first call via resolving code in 3387the loader, which might assume EAX, EDX and ECX can be clobbered, as 3388per the standard calling conventions. Solaris 8 is affected by this. 3389GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be 3390safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be 3391disabled with the linker or the loader if desired, to avoid the 3392problem.) 3393 3394@item sseregparm 3395@cindex @code{sseregparm} attribute 3396On the Intel 386 with SSE support, the @code{sseregparm} attribute 3397causes the compiler to pass up to 3 floating point arguments in 3398SSE registers instead of on the stack. Functions that take a 3399variable number of arguments will continue to pass all of their 3400floating point arguments on the stack. 3401 3402@item force_align_arg_pointer 3403@cindex @code{force_align_arg_pointer} attribute 3404On the Intel x86, the @code{force_align_arg_pointer} attribute may be 3405applied to individual function definitions, generating an alternate 3406prologue and epilogue that realigns the runtime stack if necessary. 3407This supports mixing legacy codes that run with a 4-byte aligned stack 3408with modern codes that keep a 16-byte stack for SSE compatibility. 3409 3410@item resbank 3411@cindex @code{resbank} attribute 3412On the SH2A target, this attribute enables the high-speed register 3413saving and restoration using a register bank for @code{interrupt_handler} 3414routines. Saving to the bank is performed automatically after the CPU 3415accepts an interrupt that uses a register bank. 3416 3417The nineteen 32-bit registers comprising general register R0 to R14, 3418control register GBR, and system registers MACH, MACL, and PR and the 3419vector table address offset are saved into a register bank. Register 3420banks are stacked in first-in last-out (FILO) sequence. Restoration 3421from the bank is executed by issuing a RESBANK instruction. 3422 3423@item returns_twice 3424@cindex @code{returns_twice} attribute 3425The @code{returns_twice} attribute tells the compiler that a function may 3426return more than one time. The compiler will ensure that all registers 3427are dead before calling such a function and will emit a warning about 3428the variables that may be clobbered after the second return from the 3429function. Examples of such functions are @code{setjmp} and @code{vfork}. 3430The @code{longjmp}-like counterpart of such function, if any, might need 3431to be marked with the @code{noreturn} attribute. 3432 3433@item saveall 3434@cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S 3435Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that 3436all registers except the stack pointer should be saved in the prologue 3437regardless of whether they are used or not. 3438 3439@item save_volatiles 3440@cindex save volatile registers on the MicroBlaze 3441Use this attribute on the MicroBlaze to indicate that the function is 3442an interrupt handler. All volatile registers (in addition to non-volatile 3443registers) will be saved in the function prologue. If the function is a leaf 3444function, only volatiles used by the function are saved. A normal function 3445return is generated instead of a return from interrupt. 3446 3447@item section ("@var{section-name}") 3448@cindex @code{section} function attribute 3449Normally, the compiler places the code it generates in the @code{text} section. 3450Sometimes, however, you need additional sections, or you need certain 3451particular functions to appear in special sections. The @code{section} 3452attribute specifies that a function lives in a particular section. 3453For example, the declaration: 3454 3455@smallexample 3456extern void foobar (void) __attribute__ ((section ("bar"))); 3457@end smallexample 3458 3459@noindent 3460puts the function @code{foobar} in the @code{bar} section. 3461 3462Some file formats do not support arbitrary sections so the @code{section} 3463attribute is not available on all platforms. 3464If you need to map the entire contents of a module to a particular 3465section, consider using the facilities of the linker instead. 3466 3467@item sentinel 3468@cindex @code{sentinel} function attribute 3469This function attribute ensures that a parameter in a function call is 3470an explicit @code{NULL}. The attribute is only valid on variadic 3471functions. By default, the sentinel is located at position zero, the 3472last parameter of the function call. If an optional integer position 3473argument P is supplied to the attribute, the sentinel must be located at 3474position P counting backwards from the end of the argument list. 3475 3476@smallexample 3477__attribute__ ((sentinel)) 3478is equivalent to 3479__attribute__ ((sentinel(0))) 3480@end smallexample 3481 3482The attribute is automatically set with a position of 0 for the built-in 3483functions @code{execl} and @code{execlp}. The built-in function 3484@code{execle} has the attribute set with a position of 1. 3485 3486A valid @code{NULL} in this context is defined as zero with any pointer 3487type. If your system defines the @code{NULL} macro with an integer type 3488then you need to add an explicit cast. GCC replaces @code{stddef.h} 3489with a copy that redefines NULL appropriately. 3490 3491The warnings for missing or incorrect sentinels are enabled with 3492@option{-Wformat}. 3493 3494@item short_call 3495See long_call/short_call. 3496 3497@item shortcall 3498See longcall/shortcall. 3499 3500@item signal 3501@cindex interrupt handler functions on the AVR processors 3502Use this attribute on the AVR to indicate that the specified 3503function is an interrupt handler. The compiler will generate function 3504entry and exit sequences suitable for use in an interrupt handler when this 3505attribute is present. 3506 3507See also the @code{interrupt} function attribute. 3508 3509The AVR hardware globally disables interrupts when an interrupt is executed. 3510Interrupt handler functions defined with the @code{signal} attribute 3511do not re-enable interrupts. It is save to enable interrupts in a 3512@code{signal} handler. This ``save'' only applies to the code 3513generated by the compiler and not to the IRQ-layout of the 3514application which is responsibility of the application. 3515 3516If both @code{signal} and @code{interrupt} are specified for the same 3517function, @code{signal} will be silently ignored. 3518 3519@item sp_switch 3520Use this attribute on the SH to indicate an @code{interrupt_handler} 3521function should switch to an alternate stack. It expects a string 3522argument that names a global variable holding the address of the 3523alternate stack. 3524 3525@smallexample 3526void *alt_stack; 3527void f () __attribute__ ((interrupt_handler, 3528 sp_switch ("alt_stack"))); 3529@end smallexample 3530 3531@item stdcall 3532@cindex functions that pop the argument stack on the 386 3533On the Intel 386, the @code{stdcall} attribute causes the compiler to 3534assume that the called function will pop off the stack space used to 3535pass arguments, unless it takes a variable number of arguments. 3536 3537@item syscall_linkage 3538@cindex @code{syscall_linkage} attribute 3539This attribute is used to modify the IA64 calling convention by marking 3540all input registers as live at all function exits. This makes it possible 3541to restart a system call after an interrupt without having to save/restore 3542the input registers. This also prevents kernel data from leaking into 3543application code. 3544 3545@item target 3546@cindex @code{target} function attribute 3547The @code{target} attribute is used to specify that a function is to 3548be compiled with different target options than specified on the 3549command line. This can be used for instance to have functions 3550compiled with a different ISA (instruction set architecture) than the 3551default. You can also use the @samp{#pragma GCC target} pragma to set 3552more than one function to be compiled with specific target options. 3553@xref{Function Specific Option Pragmas}, for details about the 3554@samp{#pragma GCC target} pragma. 3555 3556For instance on a 386, you could compile one function with 3557@code{target("sse4.1,arch=core2")} and another with 3558@code{target("sse4a,arch=amdfam10")} that would be equivalent to 3559compiling the first function with @option{-msse4.1} and 3560@option{-march=core2} options, and the second function with 3561@option{-msse4a} and @option{-march=amdfam10} options. It is up to the 3562user to make sure that a function is only invoked on a machine that 3563supports the particular ISA it was compiled for (for example by using 3564@code{cpuid} on 386 to determine what feature bits and architecture 3565family are used). 3566 3567@smallexample 3568int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); 3569int sse3_func (void) __attribute__ ((__target__ ("sse3"))); 3570@end smallexample 3571 3572On the 386, the following options are allowed: 3573 3574@table @samp 3575@item abm 3576@itemx no-abm 3577@cindex @code{target("abm")} attribute 3578Enable/disable the generation of the advanced bit instructions. 3579 3580@item aes 3581@itemx no-aes 3582@cindex @code{target("aes")} attribute 3583Enable/disable the generation of the AES instructions. 3584 3585@item mmx 3586@itemx no-mmx 3587@cindex @code{target("mmx")} attribute 3588Enable/disable the generation of the MMX instructions. 3589 3590@item pclmul 3591@itemx no-pclmul 3592@cindex @code{target("pclmul")} attribute 3593Enable/disable the generation of the PCLMUL instructions. 3594 3595@item popcnt 3596@itemx no-popcnt 3597@cindex @code{target("popcnt")} attribute 3598Enable/disable the generation of the POPCNT instruction. 3599 3600@item sse 3601@itemx no-sse 3602@cindex @code{target("sse")} attribute 3603Enable/disable the generation of the SSE instructions. 3604 3605@item sse2 3606@itemx no-sse2 3607@cindex @code{target("sse2")} attribute 3608Enable/disable the generation of the SSE2 instructions. 3609 3610@item sse3 3611@itemx no-sse3 3612@cindex @code{target("sse3")} attribute 3613Enable/disable the generation of the SSE3 instructions. 3614 3615@item sse4 3616@itemx no-sse4 3617@cindex @code{target("sse4")} attribute 3618Enable/disable the generation of the SSE4 instructions (both SSE4.1 3619and SSE4.2). 3620 3621@item sse4.1 3622@itemx no-sse4.1 3623@cindex @code{target("sse4.1")} attribute 3624Enable/disable the generation of the sse4.1 instructions. 3625 3626@item sse4.2 3627@itemx no-sse4.2 3628@cindex @code{target("sse4.2")} attribute 3629Enable/disable the generation of the sse4.2 instructions. 3630 3631@item sse4a 3632@itemx no-sse4a 3633@cindex @code{target("sse4a")} attribute 3634Enable/disable the generation of the SSE4A instructions. 3635 3636@item fma4 3637@itemx no-fma4 3638@cindex @code{target("fma4")} attribute 3639Enable/disable the generation of the FMA4 instructions. 3640 3641@item xop 3642@itemx no-xop 3643@cindex @code{target("xop")} attribute 3644Enable/disable the generation of the XOP instructions. 3645 3646@item lwp 3647@itemx no-lwp 3648@cindex @code{target("lwp")} attribute 3649Enable/disable the generation of the LWP instructions. 3650 3651@item ssse3 3652@itemx no-ssse3 3653@cindex @code{target("ssse3")} attribute 3654Enable/disable the generation of the SSSE3 instructions. 3655 3656@item cld 3657@itemx no-cld 3658@cindex @code{target("cld")} attribute 3659Enable/disable the generation of the CLD before string moves. 3660 3661@item fancy-math-387 3662@itemx no-fancy-math-387 3663@cindex @code{target("fancy-math-387")} attribute 3664Enable/disable the generation of the @code{sin}, @code{cos}, and 3665@code{sqrt} instructions on the 387 floating point unit. 3666 3667@item fused-madd 3668@itemx no-fused-madd 3669@cindex @code{target("fused-madd")} attribute 3670Enable/disable the generation of the fused multiply/add instructions. 3671 3672@item ieee-fp 3673@itemx no-ieee-fp 3674@cindex @code{target("ieee-fp")} attribute 3675Enable/disable the generation of floating point that depends on IEEE arithmetic. 3676 3677@item inline-all-stringops 3678@itemx no-inline-all-stringops 3679@cindex @code{target("inline-all-stringops")} attribute 3680Enable/disable inlining of string operations. 3681 3682@item inline-stringops-dynamically 3683@itemx no-inline-stringops-dynamically 3684@cindex @code{target("inline-stringops-dynamically")} attribute 3685Enable/disable the generation of the inline code to do small string 3686operations and calling the library routines for large operations. 3687 3688@item align-stringops 3689@itemx no-align-stringops 3690@cindex @code{target("align-stringops")} attribute 3691Do/do not align destination of inlined string operations. 3692 3693@item recip 3694@itemx no-recip 3695@cindex @code{target("recip")} attribute 3696Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS 3697instructions followed an additional Newton-Raphson step instead of 3698doing a floating point division. 3699 3700@item arch=@var{ARCH} 3701@cindex @code{target("arch=@var{ARCH}")} attribute 3702Specify the architecture to generate code for in compiling the function. 3703 3704@item tune=@var{TUNE} 3705@cindex @code{target("tune=@var{TUNE}")} attribute 3706Specify the architecture to tune for in compiling the function. 3707 3708@item fpmath=@var{FPMATH} 3709@cindex @code{target("fpmath=@var{FPMATH}")} attribute 3710Specify which floating point unit to use. The 3711@code{target("fpmath=sse,387")} option must be specified as 3712@code{target("fpmath=sse+387")} because the comma would separate 3713different options. 3714@end table 3715 3716On the PowerPC, the following options are allowed: 3717 3718@table @samp 3719@item altivec 3720@itemx no-altivec 3721@cindex @code{target("altivec")} attribute 3722Generate code that uses (does not use) AltiVec instructions. In 372332-bit code, you cannot enable Altivec instructions unless 3724@option{-mabi=altivec} was used on the command line. 3725 3726@item cmpb 3727@itemx no-cmpb 3728@cindex @code{target("cmpb")} attribute 3729Generate code that uses (does not use) the compare bytes instruction 3730implemented on the POWER6 processor and other processors that support 3731the PowerPC V2.05 architecture. 3732 3733@item dlmzb 3734@itemx no-dlmzb 3735@cindex @code{target("dlmzb")} attribute 3736Generate code that uses (does not use) the string-search @samp{dlmzb} 3737instruction on the IBM 405, 440, 464 and 476 processors. This instruction is 3738generated by default when targetting those processors. 3739 3740@item fprnd 3741@itemx no-fprnd 3742@cindex @code{target("fprnd")} attribute 3743Generate code that uses (does not use) the FP round to integer 3744instructions implemented on the POWER5+ processor and other processors 3745that support the PowerPC V2.03 architecture. 3746 3747@item hard-dfp 3748@itemx no-hard-dfp 3749@cindex @code{target("hard-dfp")} attribute 3750Generate code that uses (does not use) the decimal floating point 3751instructions implemented on some POWER processors. 3752 3753@item isel 3754@itemx no-isel 3755@cindex @code{target("isel")} attribute 3756Generate code that uses (does not use) ISEL instruction. 3757 3758@item mfcrf 3759@itemx no-mfcrf 3760@cindex @code{target("mfcrf")} attribute 3761Generate code that uses (does not use) the move from condition 3762register field instruction implemented on the POWER4 processor and 3763other processors that support the PowerPC V2.01 architecture. 3764 3765@item mfpgpr 3766@itemx no-mfpgpr 3767@cindex @code{target("mfpgpr")} attribute 3768Generate code that uses (does not use) the FP move to/from general 3769purpose register instructions implemented on the POWER6X processor and 3770other processors that support the extended PowerPC V2.05 architecture. 3771 3772@item mulhw 3773@itemx no-mulhw 3774@cindex @code{target("mulhw")} attribute 3775Generate code that uses (does not use) the half-word multiply and 3776multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. 3777These instructions are generated by default when targetting those 3778processors. 3779 3780@item multiple 3781@itemx no-multiple 3782@cindex @code{target("multiple")} attribute 3783Generate code that uses (does not use) the load multiple word 3784instructions and the store multiple word instructions. 3785 3786@item update 3787@itemx no-update 3788@cindex @code{target("update")} attribute 3789Generate code that uses (does not use) the load or store instructions 3790that update the base register to the address of the calculated memory 3791location. 3792 3793@item popcntb 3794@itemx no-popcntb 3795@cindex @code{target("popcntb")} attribute 3796Generate code that uses (does not use) the popcount and double 3797precision FP reciprocal estimate instruction implemented on the POWER5 3798processor and other processors that support the PowerPC V2.02 3799architecture. 3800 3801@item popcntd 3802@itemx no-popcntd 3803@cindex @code{target("popcntd")} attribute 3804Generate code that uses (does not use) the popcount instruction 3805implemented on the POWER7 processor and other processors that support 3806the PowerPC V2.06 architecture. 3807 3808@item powerpc-gfxopt 3809@itemx no-powerpc-gfxopt 3810@cindex @code{target("powerpc-gfxopt")} attribute 3811Generate code that uses (does not use) the optional PowerPC 3812architecture instructions in the Graphics group, including 3813floating-point select. 3814 3815@item powerpc-gpopt 3816@itemx no-powerpc-gpopt 3817@cindex @code{target("powerpc-gpopt")} attribute 3818Generate code that uses (does not use) the optional PowerPC 3819architecture instructions in the General Purpose group, including 3820floating-point square root. 3821 3822@item recip-precision 3823@itemx no-recip-precision 3824@cindex @code{target("recip-precision")} attribute 3825Assume (do not assume) that the reciprocal estimate instructions 3826provide higher precision estimates than is mandated by the powerpc 3827ABI. 3828 3829@item string 3830@itemx no-string 3831@cindex @code{target("string")} attribute 3832Generate code that uses (does not use) the load string instructions 3833and the store string word instructions to save multiple registers and 3834do small block moves. 3835 3836@item vsx 3837@itemx no-vsx 3838@cindex @code{target("vsx")} attribute 3839Generate code that uses (does not use) vector/scalar (VSX) 3840instructions, and also enable the use of built-in functions that allow 3841more direct access to the VSX instruction set. In 32-bit code, you 3842cannot enable VSX or Altivec instructions unless 3843@option{-mabi=altivec} was used on the command line. 3844 3845@item friz 3846@itemx no-friz 3847@cindex @code{target("friz")} attribute 3848Generate (do not generate) the @code{friz} instruction when the 3849@option{-funsafe-math-optimizations} option is used to optimize 3850rounding a floating point value to 64-bit integer and back to floating 3851point. The @code{friz} instruction does not return the same value if 3852the floating point number is too large to fit in an integer. 3853 3854@item avoid-indexed-addresses 3855@itemx no-avoid-indexed-addresses 3856@cindex @code{target("avoid-indexed-addresses")} attribute 3857Generate code that tries to avoid (not avoid) the use of indexed load 3858or store instructions. 3859 3860@item paired 3861@itemx no-paired 3862@cindex @code{target("paired")} attribute 3863Generate code that uses (does not use) the generation of PAIRED simd 3864instructions. 3865 3866@item longcall 3867@itemx no-longcall 3868@cindex @code{target("longcall")} attribute 3869Generate code that assumes (does not assume) that all calls are far 3870away so that a longer more expensive calling sequence is required. 3871 3872@item cpu=@var{CPU} 3873@cindex @code{target("cpu=@var{CPU}")} attribute 3874Specify the architecture to generate code for when compiling the 3875function. If you select the @code{target("cpu=power7")} attribute when 3876generating 32-bit code, VSX and Altivec instructions are not generated 3877unless you use the @option{-mabi=altivec} option on the command line. 3878 3879@item tune=@var{TUNE} 3880@cindex @code{target("tune=@var{TUNE}")} attribute 3881Specify the architecture to tune for when compiling the function. If 3882you do not specify the @code{target("tune=@var{TUNE}")} attribute and 3883you do specify the @code{target("cpu=@var{CPU}")} attribute, 3884compilation will tune for the @var{CPU} architecture, and not the 3885default tuning specified on the command line. 3886@end table 3887 3888On the 386/x86_64 and PowerPC backends, you can use either multiple 3889strings to specify multiple options, or you can separate the option 3890with a comma (@code{,}). 3891 3892On the 386/x86_64 and PowerPC backends, the inliner will not inline a 3893function that has different target options than the caller, unless the 3894callee has a subset of the target options of the caller. For example 3895a function declared with @code{target("sse3")} can inline a function 3896with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}. 3897 3898The @code{target} attribute is not implemented in GCC versions earlier 3899than 4.4 for the i386/x86_64 and 4.6 for the PowerPC backends. It is 3900not currently implemented for other backends. 3901 3902@item tiny_data 3903@cindex tiny data section on the H8/300H and H8S 3904Use this attribute on the H8/300H and H8S to indicate that the specified 3905variable should be placed into the tiny data section. 3906The compiler will generate more efficient code for loads and stores 3907on data in the tiny data section. Note the tiny data area is limited to 3908slightly under 32kbytes of data. 3909 3910@item trap_exit 3911Use this attribute on the SH for an @code{interrupt_handler} to return using 3912@code{trapa} instead of @code{rte}. This attribute expects an integer 3913argument specifying the trap number to be used. 3914 3915@item unused 3916@cindex @code{unused} attribute. 3917This attribute, attached to a function, means that the function is meant 3918to be possibly unused. GCC will not produce a warning for this 3919function. 3920 3921@item used 3922@cindex @code{used} attribute. 3923This attribute, attached to a function, means that code must be emitted 3924for the function even if it appears that the function is not referenced. 3925This is useful, for example, when the function is referenced only in 3926inline assembly. 3927 3928When applied to a member function of a C++ class template, the 3929attribute also means that the function will be instantiated if the 3930class itself is instantiated. 3931 3932@item version_id 3933@cindex @code{version_id} attribute 3934This IA64 HP-UX attribute, attached to a global variable or function, renames a 3935symbol to contain a version string, thus allowing for function level 3936versioning. HP-UX system header files may use version level functioning 3937for some system calls. 3938 3939@smallexample 3940extern int foo () __attribute__((version_id ("20040821"))); 3941@end smallexample 3942 3943Calls to @var{foo} will be mapped to calls to @var{foo@{20040821@}}. 3944 3945@item visibility ("@var{visibility_type}") 3946@cindex @code{visibility} attribute 3947This attribute affects the linkage of the declaration to which it is attached. 3948There are four supported @var{visibility_type} values: default, 3949hidden, protected or internal visibility. 3950 3951@smallexample 3952void __attribute__ ((visibility ("protected"))) 3953f () @{ /* @r{Do something.} */; @} 3954int i __attribute__ ((visibility ("hidden"))); 3955@end smallexample 3956 3957The possible values of @var{visibility_type} correspond to the 3958visibility settings in the ELF gABI. 3959 3960@table @dfn 3961@c keep this list of visibilities in alphabetical order. 3962 3963@item default 3964Default visibility is the normal case for the object file format. 3965This value is available for the visibility attribute to override other 3966options that may change the assumed visibility of entities. 3967 3968On ELF, default visibility means that the declaration is visible to other 3969modules and, in shared libraries, means that the declared entity may be 3970overridden. 3971 3972On Darwin, default visibility means that the declaration is visible to 3973other modules. 3974 3975Default visibility corresponds to ``external linkage'' in the language. 3976 3977@item hidden 3978Hidden visibility indicates that the entity declared will have a new 3979form of linkage, which we'll call ``hidden linkage''. Two 3980declarations of an object with hidden linkage refer to the same object 3981if they are in the same shared object. 3982 3983@item internal 3984Internal visibility is like hidden visibility, but with additional 3985processor specific semantics. Unless otherwise specified by the 3986psABI, GCC defines internal visibility to mean that a function is 3987@emph{never} called from another module. Compare this with hidden 3988functions which, while they cannot be referenced directly by other 3989modules, can be referenced indirectly via function pointers. By 3990indicating that a function cannot be called from outside the module, 3991GCC may for instance omit the load of a PIC register since it is known 3992that the calling function loaded the correct value. 3993 3994@item protected 3995Protected visibility is like default visibility except that it 3996indicates that references within the defining module will bind to the 3997definition in that module. That is, the declared entity cannot be 3998overridden by another module. 3999 4000@end table 4001 4002All visibilities are supported on many, but not all, ELF targets 4003(supported when the assembler supports the @samp{.visibility} 4004pseudo-op). Default visibility is supported everywhere. Hidden 4005visibility is supported on Darwin targets. 4006 4007The visibility attribute should be applied only to declarations which 4008would otherwise have external linkage. The attribute should be applied 4009consistently, so that the same entity should not be declared with 4010different settings of the attribute. 4011 4012In C++, the visibility attribute applies to types as well as functions 4013and objects, because in C++ types have linkage. A class must not have 4014greater visibility than its non-static data member types and bases, 4015and class members default to the visibility of their class. Also, a 4016declaration without explicit visibility is limited to the visibility 4017of its type. 4018 4019In C++, you can mark member functions and static member variables of a 4020class with the visibility attribute. This is useful if you know a 4021particular method or static member variable should only be used from 4022one shared object; then you can mark it hidden while the rest of the 4023class has default visibility. Care must be taken to avoid breaking 4024the One Definition Rule; for example, it is usually not useful to mark 4025an inline method as hidden without marking the whole class as hidden. 4026 4027A C++ namespace declaration can also have the visibility attribute. 4028This attribute applies only to the particular namespace body, not to 4029other definitions of the same namespace; it is equivalent to using 4030@samp{#pragma GCC visibility} before and after the namespace 4031definition (@pxref{Visibility Pragmas}). 4032 4033In C++, if a template argument has limited visibility, this 4034restriction is implicitly propagated to the template instantiation. 4035Otherwise, template instantiations and specializations default to the 4036visibility of their template. 4037 4038If both the template and enclosing class have explicit visibility, the 4039visibility from the template is used. 4040 4041@item vliw 4042@cindex @code{vliw} attribute 4043On MeP, the @code{vliw} attribute tells the compiler to emit 4044instructions in VLIW mode instead of core mode. Note that this 4045attribute is not allowed unless a VLIW coprocessor has been configured 4046and enabled through command line options. 4047 4048@item warn_unused_result 4049@cindex @code{warn_unused_result} attribute 4050The @code{warn_unused_result} attribute causes a warning to be emitted 4051if a caller of the function with this attribute does not use its 4052return value. This is useful for functions where not checking 4053the result is either a security problem or always a bug, such as 4054@code{realloc}. 4055 4056@smallexample 4057int fn () __attribute__ ((warn_unused_result)); 4058int foo () 4059@{ 4060 if (fn () < 0) return -1; 4061 fn (); 4062 return 0; 4063@} 4064@end smallexample 4065 4066results in warning on line 5. 4067 4068@item weak 4069@cindex @code{weak} attribute 4070The @code{weak} attribute causes the declaration to be emitted as a weak 4071symbol rather than a global. This is primarily useful in defining 4072library functions which can be overridden in user code, though it can 4073also be used with non-function declarations. Weak symbols are supported 4074for ELF targets, and also for a.out targets when using the GNU assembler 4075and linker. 4076 4077@item weakref 4078@itemx weakref ("@var{target}") 4079@cindex @code{weakref} attribute 4080The @code{weakref} attribute marks a declaration as a weak reference. 4081Without arguments, it should be accompanied by an @code{alias} attribute 4082naming the target symbol. Optionally, the @var{target} may be given as 4083an argument to @code{weakref} itself. In either case, @code{weakref} 4084implicitly marks the declaration as @code{weak}. Without a 4085@var{target}, given as an argument to @code{weakref} or to @code{alias}, 4086@code{weakref} is equivalent to @code{weak}. 4087 4088@smallexample 4089static int x() __attribute__ ((weakref ("y"))); 4090/* is equivalent to... */ 4091static int x() __attribute__ ((weak, weakref, alias ("y"))); 4092/* and to... */ 4093static int x() __attribute__ ((weakref)); 4094static int x() __attribute__ ((alias ("y"))); 4095@end smallexample 4096 4097A weak reference is an alias that does not by itself require a 4098definition to be given for the target symbol. If the target symbol is 4099only referenced through weak references, then it becomes a @code{weak} 4100undefined symbol. If it is directly referenced, however, then such 4101strong references prevail, and a definition will be required for the 4102symbol, not necessarily in the same translation unit. 4103 4104The effect is equivalent to moving all references to the alias to a 4105separate translation unit, renaming the alias to the aliased symbol, 4106declaring it as weak, compiling the two separate translation units and 4107performing a reloadable link on them. 4108 4109At present, a declaration to which @code{weakref} is attached can 4110only be @code{static}. 4111 4112@end table 4113 4114You can specify multiple attributes in a declaration by separating them 4115by commas within the double parentheses or by immediately following an 4116attribute declaration with another attribute declaration. 4117 4118@cindex @code{#pragma}, reason for not using 4119@cindex pragma, reason for not using 4120Some people object to the @code{__attribute__} feature, suggesting that 4121ISO C's @code{#pragma} should be used instead. At the time 4122@code{__attribute__} was designed, there were two reasons for not doing 4123this. 4124 4125@enumerate 4126@item 4127It is impossible to generate @code{#pragma} commands from a macro. 4128 4129@item 4130There is no telling what the same @code{#pragma} might mean in another 4131compiler. 4132@end enumerate 4133 4134These two reasons applied to almost any application that might have been 4135proposed for @code{#pragma}. It was basically a mistake to use 4136@code{#pragma} for @emph{anything}. 4137 4138The ISO C99 standard includes @code{_Pragma}, which now allows pragmas 4139to be generated from macros. In addition, a @code{#pragma GCC} 4140namespace is now in use for GCC-specific pragmas. However, it has been 4141found convenient to use @code{__attribute__} to achieve a natural 4142attachment of attributes to their corresponding declarations, whereas 4143@code{#pragma GCC} is of use for constructs that do not naturally form 4144part of the grammar. @xref{Other Directives,,Miscellaneous 4145Preprocessing Directives, cpp, The GNU C Preprocessor}. 4146 4147@node Attribute Syntax 4148@section Attribute Syntax 4149@cindex attribute syntax 4150 4151This section describes the syntax with which @code{__attribute__} may be 4152used, and the constructs to which attribute specifiers bind, for the C 4153language. Some details may vary for C++ and Objective-C@. Because of 4154infelicities in the grammar for attributes, some forms described here 4155may not be successfully parsed in all cases. 4156 4157There are some problems with the semantics of attributes in C++. For 4158example, there are no manglings for attributes, although they may affect 4159code generation, so problems may arise when attributed types are used in 4160conjunction with templates or overloading. Similarly, @code{typeid} 4161does not distinguish between types with different attributes. Support 4162for attributes in C++ may be restricted in future to attributes on 4163declarations only, but not on nested declarators. 4164 4165@xref{Function Attributes}, for details of the semantics of attributes 4166applying to functions. @xref{Variable Attributes}, for details of the 4167semantics of attributes applying to variables. @xref{Type Attributes}, 4168for details of the semantics of attributes applying to structure, union 4169and enumerated types. 4170 4171An @dfn{attribute specifier} is of the form 4172@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} 4173is a possibly empty comma-separated sequence of @dfn{attributes}, where 4174each attribute is one of the following: 4175 4176@itemize @bullet 4177@item 4178Empty. Empty attributes are ignored. 4179 4180@item 4181A word (which may be an identifier such as @code{unused}, or a reserved 4182word such as @code{const}). 4183 4184@item 4185A word, followed by, in parentheses, parameters for the attribute. 4186These parameters take one of the following forms: 4187 4188@itemize @bullet 4189@item 4190An identifier. For example, @code{mode} attributes use this form. 4191 4192@item 4193An identifier followed by a comma and a non-empty comma-separated list 4194of expressions. For example, @code{format} attributes use this form. 4195 4196@item 4197A possibly empty comma-separated list of expressions. For example, 4198@code{format_arg} attributes use this form with the list being a single 4199integer constant expression, and @code{alias} attributes use this form 4200with the list being a single string constant. 4201@end itemize 4202@end itemize 4203 4204An @dfn{attribute specifier list} is a sequence of one or more attribute 4205specifiers, not separated by any other tokens. 4206 4207In GNU C, an attribute specifier list may appear after the colon following a 4208label, other than a @code{case} or @code{default} label. The only 4209attribute it makes sense to use after a label is @code{unused}. This 4210feature is intended for code generated by programs which contains labels 4211that may be unused but which is compiled with @option{-Wall}. It would 4212not normally be appropriate to use in it human-written code, though it 4213could be useful in cases where the code that jumps to the label is 4214contained within an @code{#ifdef} conditional. GNU C++ only permits 4215attributes on labels if the attribute specifier is immediately 4216followed by a semicolon (i.e., the label applies to an empty 4217statement). If the semicolon is missing, C++ label attributes are 4218ambiguous, as it is permissible for a declaration, which could begin 4219with an attribute list, to be labelled in C++. Declarations cannot be 4220labelled in C90 or C99, so the ambiguity does not arise there. 4221 4222An attribute specifier list may appear as part of a @code{struct}, 4223@code{union} or @code{enum} specifier. It may go either immediately 4224after the @code{struct}, @code{union} or @code{enum} keyword, or after 4225the closing brace. The former syntax is preferred. 4226Where attribute specifiers follow the closing brace, they are considered 4227to relate to the structure, union or enumerated type defined, not to any 4228enclosing declaration the type specifier appears in, and the type 4229defined is not complete until after the attribute specifiers. 4230@c Otherwise, there would be the following problems: a shift/reduce 4231@c conflict between attributes binding the struct/union/enum and 4232@c binding to the list of specifiers/qualifiers; and "aligned" 4233@c attributes could use sizeof for the structure, but the size could be 4234@c changed later by "packed" attributes. 4235 4236Otherwise, an attribute specifier appears as part of a declaration, 4237counting declarations of unnamed parameters and type names, and relates 4238to that declaration (which may be nested in another declaration, for 4239example in the case of a parameter declaration), or to a particular declarator 4240within a declaration. Where an 4241attribute specifier is applied to a parameter declared as a function or 4242an array, it should apply to the function or array rather than the 4243pointer to which the parameter is implicitly converted, but this is not 4244yet correctly implemented. 4245 4246Any list of specifiers and qualifiers at the start of a declaration may 4247contain attribute specifiers, whether or not such a list may in that 4248context contain storage class specifiers. (Some attributes, however, 4249are essentially in the nature of storage class specifiers, and only make 4250sense where storage class specifiers may be used; for example, 4251@code{section}.) There is one necessary limitation to this syntax: the 4252first old-style parameter declaration in a function definition cannot 4253begin with an attribute specifier, because such an attribute applies to 4254the function instead by syntax described below (which, however, is not 4255yet implemented in this case). In some other cases, attribute 4256specifiers are permitted by this grammar but not yet supported by the 4257compiler. All attribute specifiers in this place relate to the 4258declaration as a whole. In the obsolescent usage where a type of 4259@code{int} is implied by the absence of type specifiers, such a list of 4260specifiers and qualifiers may be an attribute specifier list with no 4261other specifiers or qualifiers. 4262 4263At present, the first parameter in a function prototype must have some 4264type specifier which is not an attribute specifier; this resolves an 4265ambiguity in the interpretation of @code{void f(int 4266(__attribute__((foo)) x))}, but is subject to change. At present, if 4267the parentheses of a function declarator contain only attributes then 4268those attributes are ignored, rather than yielding an error or warning 4269or implying a single parameter of type int, but this is subject to 4270change. 4271 4272An attribute specifier list may appear immediately before a declarator 4273(other than the first) in a comma-separated list of declarators in a 4274declaration of more than one identifier using a single list of 4275specifiers and qualifiers. Such attribute specifiers apply 4276only to the identifier before whose declarator they appear. For 4277example, in 4278 4279@smallexample 4280__attribute__((noreturn)) void d0 (void), 4281 __attribute__((format(printf, 1, 2))) d1 (const char *, ...), 4282 d2 (void) 4283@end smallexample 4284 4285@noindent 4286the @code{noreturn} attribute applies to all the functions 4287declared; the @code{format} attribute only applies to @code{d1}. 4288 4289An attribute specifier list may appear immediately before the comma, 4290@code{=} or semicolon terminating the declaration of an identifier other 4291than a function definition. Such attribute specifiers apply 4292to the declared object or function. Where an 4293assembler name for an object or function is specified (@pxref{Asm 4294Labels}), the attribute must follow the @code{asm} 4295specification. 4296 4297An attribute specifier list may, in future, be permitted to appear after 4298the declarator in a function definition (before any old-style parameter 4299declarations or the function body). 4300 4301Attribute specifiers may be mixed with type qualifiers appearing inside 4302the @code{[]} of a parameter array declarator, in the C99 construct by 4303which such qualifiers are applied to the pointer to which the array is 4304implicitly converted. Such attribute specifiers apply to the pointer, 4305not to the array, but at present this is not implemented and they are 4306ignored. 4307 4308An attribute specifier list may appear at the start of a nested 4309declarator. At present, there are some limitations in this usage: the 4310attributes correctly apply to the declarator, but for most individual 4311attributes the semantics this implies are not implemented. 4312When attribute specifiers follow the @code{*} of a pointer 4313declarator, they may be mixed with any type qualifiers present. 4314The following describes the formal semantics of this syntax. It will make the 4315most sense if you are familiar with the formal specification of 4316declarators in the ISO C standard. 4317 4318Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T 4319D1}, where @code{T} contains declaration specifiers that specify a type 4320@var{Type} (such as @code{int}) and @code{D1} is a declarator that 4321contains an identifier @var{ident}. The type specified for @var{ident} 4322for derived declarators whose type does not include an attribute 4323specifier is as in the ISO C standard. 4324 4325If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, 4326and the declaration @code{T D} specifies the type 4327``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 4328@code{T D1} specifies the type ``@var{derived-declarator-type-list} 4329@var{attribute-specifier-list} @var{Type}'' for @var{ident}. 4330 4331If @code{D1} has the form @code{* 4332@var{type-qualifier-and-attribute-specifier-list} D}, and the 4333declaration @code{T D} specifies the type 4334``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 4335@code{T D1} specifies the type ``@var{derived-declarator-type-list} 4336@var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for 4337@var{ident}. 4338 4339For example, 4340 4341@smallexample 4342void (__attribute__((noreturn)) ****f) (void); 4343@end smallexample 4344 4345@noindent 4346specifies the type ``pointer to pointer to pointer to pointer to 4347non-returning function returning @code{void}''. As another example, 4348 4349@smallexample 4350char *__attribute__((aligned(8))) *f; 4351@end smallexample 4352 4353@noindent 4354specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. 4355Note again that this does not work with most attributes; for example, 4356the usage of @samp{aligned} and @samp{noreturn} attributes given above 4357is not yet supported. 4358 4359For compatibility with existing code written for compiler versions that 4360did not implement attributes on nested declarators, some laxity is 4361allowed in the placing of attributes. If an attribute that only applies 4362to types is applied to a declaration, it will be treated as applying to 4363the type of that declaration. If an attribute that only applies to 4364declarations is applied to the type of a declaration, it will be treated 4365as applying to that declaration; and, for compatibility with code 4366placing the attributes immediately before the identifier declared, such 4367an attribute applied to a function return type will be treated as 4368applying to the function type, and such an attribute applied to an array 4369element type will be treated as applying to the array type. If an 4370attribute that only applies to function types is applied to a 4371pointer-to-function type, it will be treated as applying to the pointer 4372target type; if such an attribute is applied to a function return type 4373that is not a pointer-to-function type, it will be treated as applying 4374to the function type. 4375 4376@node Function Prototypes 4377@section Prototypes and Old-Style Function Definitions 4378@cindex function prototype declarations 4379@cindex old-style function definitions 4380@cindex promotion of formal parameters 4381 4382GNU C extends ISO C to allow a function prototype to override a later 4383old-style non-prototype definition. Consider the following example: 4384 4385@smallexample 4386/* @r{Use prototypes unless the compiler is old-fashioned.} */ 4387#ifdef __STDC__ 4388#define P(x) x 4389#else 4390#define P(x) () 4391#endif 4392 4393/* @r{Prototype function declaration.} */ 4394int isroot P((uid_t)); 4395 4396/* @r{Old-style function definition.} */ 4397int 4398isroot (x) /* @r{??? lossage here ???} */ 4399 uid_t x; 4400@{ 4401 return x == 0; 4402@} 4403@end smallexample 4404 4405Suppose the type @code{uid_t} happens to be @code{short}. ISO C does 4406not allow this example, because subword arguments in old-style 4407non-prototype definitions are promoted. Therefore in this example the 4408function definition's argument is really an @code{int}, which does not 4409match the prototype argument type of @code{short}. 4410 4411This restriction of ISO C makes it hard to write code that is portable 4412to traditional C compilers, because the programmer does not know 4413whether the @code{uid_t} type is @code{short}, @code{int}, or 4414@code{long}. Therefore, in cases like these GNU C allows a prototype 4415to override a later old-style definition. More precisely, in GNU C, a 4416function prototype argument type overrides the argument type specified 4417by a later old-style definition if the former type is the same as the 4418latter type before promotion. Thus in GNU C the above example is 4419equivalent to the following: 4420 4421@smallexample 4422int isroot (uid_t); 4423 4424int 4425isroot (uid_t x) 4426@{ 4427 return x == 0; 4428@} 4429@end smallexample 4430 4431@noindent 4432GNU C++ does not support old-style function definitions, so this 4433extension is irrelevant. 4434 4435@node C++ Comments 4436@section C++ Style Comments 4437@cindex @code{//} 4438@cindex C++ comments 4439@cindex comments, C++ style 4440 4441In GNU C, you may use C++ style comments, which start with @samp{//} and 4442continue until the end of the line. Many other C implementations allow 4443such comments, and they are included in the 1999 C standard. However, 4444C++ style comments are not recognized if you specify an @option{-std} 4445option specifying a version of ISO C before C99, or @option{-ansi} 4446(equivalent to @option{-std=c90}). 4447 4448@node Dollar Signs 4449@section Dollar Signs in Identifier Names 4450@cindex $ 4451@cindex dollar signs in identifier names 4452@cindex identifier names, dollar signs in 4453 4454In GNU C, you may normally use dollar signs in identifier names. 4455This is because many traditional C implementations allow such identifiers. 4456However, dollar signs in identifiers are not supported on a few target 4457machines, typically because the target assembler does not allow them. 4458 4459@node Character Escapes 4460@section The Character @key{ESC} in Constants 4461 4462You can use the sequence @samp{\e} in a string or character constant to 4463stand for the ASCII character @key{ESC}. 4464 4465@node Variable Attributes 4466@section Specifying Attributes of Variables 4467@cindex attribute of variables 4468@cindex variable attributes 4469 4470The keyword @code{__attribute__} allows you to specify special 4471attributes of variables or structure fields. This keyword is followed 4472by an attribute specification inside double parentheses. Some 4473attributes are currently defined generically for variables. 4474Other attributes are defined for variables on particular target 4475systems. Other attributes are available for functions 4476(@pxref{Function Attributes}) and for types (@pxref{Type Attributes}). 4477Other front ends might define more attributes 4478(@pxref{C++ Extensions,,Extensions to the C++ Language}). 4479 4480You may also specify attributes with @samp{__} preceding and following 4481each keyword. This allows you to use them in header files without 4482being concerned about a possible macro of the same name. For example, 4483you may use @code{__aligned__} instead of @code{aligned}. 4484 4485@xref{Attribute Syntax}, for details of the exact syntax for using 4486attributes. 4487 4488@table @code 4489@cindex @code{aligned} attribute 4490@item aligned (@var{alignment}) 4491This attribute specifies a minimum alignment for the variable or 4492structure field, measured in bytes. For example, the declaration: 4493 4494@smallexample 4495int x __attribute__ ((aligned (16))) = 0; 4496@end smallexample 4497 4498@noindent 4499causes the compiler to allocate the global variable @code{x} on a 450016-byte boundary. On a 68040, this could be used in conjunction with 4501an @code{asm} expression to access the @code{move16} instruction which 4502requires 16-byte aligned operands. 4503 4504You can also specify the alignment of structure fields. For example, to 4505create a double-word aligned @code{int} pair, you could write: 4506 4507@smallexample 4508struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; 4509@end smallexample 4510 4511@noindent 4512This is an alternative to creating a union with a @code{double} member 4513that forces the union to be double-word aligned. 4514 4515As in the preceding examples, you can explicitly specify the alignment 4516(in bytes) that you wish the compiler to use for a given variable or 4517structure field. Alternatively, you can leave out the alignment factor 4518and just ask the compiler to align a variable or field to the 4519default alignment for the target architecture you are compiling for. 4520The default alignment is sufficient for all scalar types, but may not be 4521enough for all vector types on a target which supports vector operations. 4522The default alignment is fixed for a particular target ABI. 4523 4524Gcc also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, 4525which is the largest alignment ever used for any data type on the 4526target machine you are compiling for. For example, you could write: 4527 4528@smallexample 4529short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); 4530@end smallexample 4531 4532The compiler automatically sets the alignment for the declared 4533variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can 4534often make copy operations more efficient, because the compiler can 4535use whatever instructions copy the biggest chunks of memory when 4536performing copies to or from the variables or fields that you have 4537aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__} 4538may change depending on command line options. 4539 4540When used on a struct, or struct member, the @code{aligned} attribute can 4541only increase the alignment; in order to decrease it, the @code{packed} 4542attribute must be specified as well. When used as part of a typedef, the 4543@code{aligned} attribute can both increase and decrease alignment, and 4544specifying the @code{packed} attribute will generate a warning. 4545 4546Note that the effectiveness of @code{aligned} attributes may be limited 4547by inherent limitations in your linker. On many systems, the linker is 4548only able to arrange for variables to be aligned up to a certain maximum 4549alignment. (For some linkers, the maximum supported alignment may 4550be very very small.) If your linker is only able to align variables 4551up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} 4552in an @code{__attribute__} will still only provide you with 8 byte 4553alignment. See your linker documentation for further information. 4554 4555The @code{aligned} attribute can also be used for functions 4556(@pxref{Function Attributes}.) 4557 4558@item cleanup (@var{cleanup_function}) 4559@cindex @code{cleanup} attribute 4560The @code{cleanup} attribute runs a function when the variable goes 4561out of scope. This attribute can only be applied to auto function 4562scope variables; it may not be applied to parameters or variables 4563with static storage duration. The function must take one parameter, 4564a pointer to a type compatible with the variable. The return value 4565of the function (if any) is ignored. 4566 4567If @option{-fexceptions} is enabled, then @var{cleanup_function} 4568will be run during the stack unwinding that happens during the 4569processing of the exception. Note that the @code{cleanup} attribute 4570does not allow the exception to be caught, only to perform an action. 4571It is undefined what happens if @var{cleanup_function} does not 4572return normally. 4573 4574@item common 4575@itemx nocommon 4576@cindex @code{common} attribute 4577@cindex @code{nocommon} attribute 4578@opindex fcommon 4579@opindex fno-common 4580The @code{common} attribute requests GCC to place a variable in 4581``common'' storage. The @code{nocommon} attribute requests the 4582opposite---to allocate space for it directly. 4583 4584These attributes override the default chosen by the 4585@option{-fno-common} and @option{-fcommon} flags respectively. 4586 4587@item deprecated 4588@itemx deprecated (@var{msg}) 4589@cindex @code{deprecated} attribute 4590The @code{deprecated} attribute results in a warning if the variable 4591is used anywhere in the source file. This is useful when identifying 4592variables that are expected to be removed in a future version of a 4593program. The warning also includes the location of the declaration 4594of the deprecated variable, to enable users to easily find further 4595information about why the variable is deprecated, or what they should 4596do instead. Note that the warning only occurs for uses: 4597 4598@smallexample 4599extern int old_var __attribute__ ((deprecated)); 4600extern int old_var; 4601int new_fn () @{ return old_var; @} 4602@end smallexample 4603 4604results in a warning on line 3 but not line 2. The optional msg 4605argument, which must be a string, will be printed in the warning if 4606present. 4607 4608The @code{deprecated} attribute can also be used for functions and 4609types (@pxref{Function Attributes}, @pxref{Type Attributes}.) 4610 4611@item mode (@var{mode}) 4612@cindex @code{mode} attribute 4613This attribute specifies the data type for the declaration---whichever 4614type corresponds to the mode @var{mode}. This in effect lets you 4615request an integer or floating point type according to its width. 4616 4617You may also specify a mode of @samp{byte} or @samp{__byte__} to 4618indicate the mode corresponding to a one-byte integer, @samp{word} or 4619@samp{__word__} for the mode of a one-word integer, and @samp{pointer} 4620or @samp{__pointer__} for the mode used to represent pointers. 4621 4622@item packed 4623@cindex @code{packed} attribute 4624The @code{packed} attribute specifies that a variable or structure field 4625should have the smallest possible alignment---one byte for a variable, 4626and one bit for a field, unless you specify a larger value with the 4627@code{aligned} attribute. 4628 4629Here is a structure in which the field @code{x} is packed, so that it 4630immediately follows @code{a}: 4631 4632@smallexample 4633struct foo 4634@{ 4635 char a; 4636 int x[2] __attribute__ ((packed)); 4637@}; 4638@end smallexample 4639 4640@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the 4641@code{packed} attribute on bit-fields of type @code{char}. This has 4642been fixed in GCC 4.4 but the change can lead to differences in the 4643structure layout. See the documentation of 4644@option{-Wpacked-bitfield-compat} for more information. 4645 4646@item section ("@var{section-name}") 4647@cindex @code{section} variable attribute 4648Normally, the compiler places the objects it generates in sections like 4649@code{data} and @code{bss}. Sometimes, however, you need additional sections, 4650or you need certain particular variables to appear in special sections, 4651for example to map to special hardware. The @code{section} 4652attribute specifies that a variable (or function) lives in a particular 4653section. For example, this small program uses several specific section names: 4654 4655@smallexample 4656struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; 4657struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; 4658char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; 4659int init_data __attribute__ ((section ("INITDATA"))); 4660 4661main() 4662@{ 4663 /* @r{Initialize stack pointer} */ 4664 init_sp (stack + sizeof (stack)); 4665 4666 /* @r{Initialize initialized data} */ 4667 memcpy (&init_data, &data, &edata - &data); 4668 4669 /* @r{Turn on the serial ports} */ 4670 init_duart (&a); 4671 init_duart (&b); 4672@} 4673@end smallexample 4674 4675@noindent 4676Use the @code{section} attribute with 4677@emph{global} variables and not @emph{local} variables, 4678as shown in the example. 4679 4680You may use the @code{section} attribute with initialized or 4681uninitialized global variables but the linker requires 4682each object be defined once, with the exception that uninitialized 4683variables tentatively go in the @code{common} (or @code{bss}) section 4684and can be multiply ``defined''. Using the @code{section} attribute 4685will change what section the variable goes into and may cause the 4686linker to issue an error if an uninitialized variable has multiple 4687definitions. You can force a variable to be initialized with the 4688@option{-fno-common} flag or the @code{nocommon} attribute. 4689 4690Some file formats do not support arbitrary sections so the @code{section} 4691attribute is not available on all platforms. 4692If you need to map the entire contents of a module to a particular 4693section, consider using the facilities of the linker instead. 4694 4695@item shared 4696@cindex @code{shared} variable attribute 4697On Microsoft Windows, in addition to putting variable definitions in a named 4698section, the section can also be shared among all running copies of an 4699executable or DLL@. For example, this small program defines shared data 4700by putting it in a named section @code{shared} and marking the section 4701shareable: 4702 4703@smallexample 4704int foo __attribute__((section ("shared"), shared)) = 0; 4705 4706int 4707main() 4708@{ 4709 /* @r{Read and write foo. All running 4710 copies see the same value.} */ 4711 return 0; 4712@} 4713@end smallexample 4714 4715@noindent 4716You may only use the @code{shared} attribute along with @code{section} 4717attribute with a fully initialized global definition because of the way 4718linkers work. See @code{section} attribute for more information. 4719 4720The @code{shared} attribute is only available on Microsoft Windows@. 4721 4722@item tls_model ("@var{tls_model}") 4723@cindex @code{tls_model} attribute 4724The @code{tls_model} attribute sets thread-local storage model 4725(@pxref{Thread-Local}) of a particular @code{__thread} variable, 4726overriding @option{-ftls-model=} command-line switch on a per-variable 4727basis. 4728The @var{tls_model} argument should be one of @code{global-dynamic}, 4729@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. 4730 4731Not all targets support this attribute. 4732 4733@item unused 4734This attribute, attached to a variable, means that the variable is meant 4735to be possibly unused. GCC will not produce a warning for this 4736variable. 4737 4738@item used 4739This attribute, attached to a variable, means that the variable must be 4740emitted even if it appears that the variable is not referenced. 4741 4742When applied to a static data member of a C++ class template, the 4743attribute also means that the member will be instantiated if the 4744class itself is instantiated. 4745 4746@item vector_size (@var{bytes}) 4747This attribute specifies the vector size for the variable, measured in 4748bytes. For example, the declaration: 4749 4750@smallexample 4751int foo __attribute__ ((vector_size (16))); 4752@end smallexample 4753 4754@noindent 4755causes the compiler to set the mode for @code{foo}, to be 16 bytes, 4756divided into @code{int} sized units. Assuming a 32-bit int (a vector of 47574 units of 4 bytes), the corresponding mode of @code{foo} will be V4SI@. 4758 4759This attribute is only applicable to integral and float scalars, 4760although arrays, pointers, and function return values are allowed in 4761conjunction with this construct. 4762 4763Aggregates with this attribute are invalid, even if they are of the same 4764size as a corresponding scalar. For example, the declaration: 4765 4766@smallexample 4767struct S @{ int a; @}; 4768struct S __attribute__ ((vector_size (16))) foo; 4769@end smallexample 4770 4771@noindent 4772is invalid even if the size of the structure is the same as the size of 4773the @code{int}. 4774 4775@item selectany 4776The @code{selectany} attribute causes an initialized global variable to 4777have link-once semantics. When multiple definitions of the variable are 4778encountered by the linker, the first is selected and the remainder are 4779discarded. Following usage by the Microsoft compiler, the linker is told 4780@emph{not} to warn about size or content differences of the multiple 4781definitions. 4782 4783Although the primary usage of this attribute is for POD types, the 4784attribute can also be applied to global C++ objects that are initialized 4785by a constructor. In this case, the static initialization and destruction 4786code for the object is emitted in each translation defining the object, 4787but the calls to the constructor and destructor are protected by a 4788link-once guard variable. 4789 4790The @code{selectany} attribute is only available on Microsoft Windows 4791targets. You can use @code{__declspec (selectany)} as a synonym for 4792@code{__attribute__ ((selectany))} for compatibility with other 4793compilers. 4794 4795@item weak 4796The @code{weak} attribute is described in @ref{Function Attributes}. 4797 4798@item dllimport 4799The @code{dllimport} attribute is described in @ref{Function Attributes}. 4800 4801@item dllexport 4802The @code{dllexport} attribute is described in @ref{Function Attributes}. 4803 4804@end table 4805 4806@anchor{AVR Variable Attributes} 4807@subsection AVR Variable Attributes 4808 4809@table @code 4810@item progmem 4811@cindex @code{progmem} AVR variable attribute 4812The @code{progmem} attribute is used on the AVR to place read-only 4813data in the non-volatile program memory (flash). The @code{progmem} 4814attribute accomplishes this by putting respective variables into a 4815section whose name starts with @code{.progmem}. 4816 4817This attribute works similar to the @code{section} attribute 4818but adds additional checking. Notice that just like the 4819@code{section} attribute, @code{progmem} affects the location 4820of the data but not how this data is accessed. 4821 4822In order to read data located with the @code{progmem} attribute 4823(inline) assembler must be used. 4824@example 4825/* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual,AVR-LibC}} */ 4826#include <avr/pgmspace.h> 4827 4828/* Locate var in flash memory */ 4829const int var[2] PROGMEM = @{ 1, 2 @}; 4830 4831int read_var (int i) 4832@{ 4833 /* Access var[] by accessor macro from avr/pgmspace.h */ 4834 return (int) pgm_read_word (& var[i]); 4835@} 4836@end example 4837 4838AVR is a Harvard architecture processor and data and read-only data 4839normally resides in the data memory (RAM). 4840 4841See also the @ref{AVR Named Address Spaces} section for 4842an alternate way to locate and access data in flash memory. 4843@end table 4844 4845@subsection Blackfin Variable Attributes 4846 4847Three attributes are currently defined for the Blackfin. 4848 4849@table @code 4850@item l1_data 4851@itemx l1_data_A 4852@itemx l1_data_B 4853@cindex @code{l1_data} variable attribute 4854@cindex @code{l1_data_A} variable attribute 4855@cindex @code{l1_data_B} variable attribute 4856Use these attributes on the Blackfin to place the variable into L1 Data SRAM. 4857Variables with @code{l1_data} attribute will be put into the specific section 4858named @code{.l1.data}. Those with @code{l1_data_A} attribute will be put into 4859the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} 4860attribute will be put into the specific section named @code{.l1.data.B}. 4861 4862@item l2 4863@cindex @code{l2} variable attribute 4864Use this attribute on the Blackfin to place the variable into L2 SRAM. 4865Variables with @code{l2} attribute will be put into the specific section 4866named @code{.l2.data}. 4867@end table 4868 4869@subsection M32R/D Variable Attributes 4870 4871One attribute is currently defined for the M32R/D@. 4872 4873@table @code 4874@item model (@var{model-name}) 4875@cindex variable addressability on the M32R/D 4876Use this attribute on the M32R/D to set the addressability of an object. 4877The identifier @var{model-name} is one of @code{small}, @code{medium}, 4878or @code{large}, representing each of the code models. 4879 4880Small model objects live in the lower 16MB of memory (so that their 4881addresses can be loaded with the @code{ld24} instruction). 4882 4883Medium and large model objects may live anywhere in the 32-bit address space 4884(the compiler will generate @code{seth/add3} instructions to load their 4885addresses). 4886@end table 4887 4888@anchor{MeP Variable Attributes} 4889@subsection MeP Variable Attributes 4890 4891The MeP target has a number of addressing modes and busses. The 4892@code{near} space spans the standard memory space's first 16 megabytes 4893(24 bits). The @code{far} space spans the entire 32-bit memory space. 4894The @code{based} space is a 128 byte region in the memory space which 4895is addressed relative to the @code{$tp} register. The @code{tiny} 4896space is a 65536 byte region relative to the @code{$gp} register. In 4897addition to these memory regions, the MeP target has a separate 16-bit 4898control bus which is specified with @code{cb} attributes. 4899 4900@table @code 4901 4902@item based 4903Any variable with the @code{based} attribute will be assigned to the 4904@code{.based} section, and will be accessed with relative to the 4905@code{$tp} register. 4906 4907@item tiny 4908Likewise, the @code{tiny} attribute assigned variables to the 4909@code{.tiny} section, relative to the @code{$gp} register. 4910 4911@item near 4912Variables with the @code{near} attribute are assumed to have addresses 4913that fit in a 24-bit addressing mode. This is the default for large 4914variables (@code{-mtiny=4} is the default) but this attribute can 4915override @code{-mtiny=} for small variables, or override @code{-ml}. 4916 4917@item far 4918Variables with the @code{far} attribute are addressed using a full 491932-bit address. Since this covers the entire memory space, this 4920allows modules to make no assumptions about where variables might be 4921stored. 4922 4923@item io 4924@itemx io (@var{addr}) 4925Variables with the @code{io} attribute are used to address 4926memory-mapped peripherals. If an address is specified, the variable 4927is assigned that address, else it is not assigned an address (it is 4928assumed some other module will assign an address). Example: 4929 4930@example 4931int timer_count __attribute__((io(0x123))); 4932@end example 4933 4934@item cb 4935@itemx cb (@var{addr}) 4936Variables with the @code{cb} attribute are used to access the control 4937bus, using special instructions. @code{addr} indicates the control bus 4938address. Example: 4939 4940@example 4941int cpu_clock __attribute__((cb(0x123))); 4942@end example 4943 4944@end table 4945 4946@anchor{i386 Variable Attributes} 4947@subsection i386 Variable Attributes 4948 4949Two attributes are currently defined for i386 configurations: 4950@code{ms_struct} and @code{gcc_struct} 4951 4952@table @code 4953@item ms_struct 4954@itemx gcc_struct 4955@cindex @code{ms_struct} attribute 4956@cindex @code{gcc_struct} attribute 4957 4958If @code{packed} is used on a structure, or if bit-fields are used 4959it may be that the Microsoft ABI packs them differently 4960than GCC would normally pack them. Particularly when moving packed 4961data between functions compiled with GCC and the native Microsoft compiler 4962(either via function call or as data in a file), it may be necessary to access 4963either format. 4964 4965Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 4966compilers to match the native Microsoft compiler. 4967 4968The Microsoft structure layout algorithm is fairly simple with the exception 4969of the bitfield packing: 4970 4971The padding and alignment of members of structures and whether a bit field 4972can straddle a storage-unit boundary 4973 4974@enumerate 4975@item Structure members are stored sequentially in the order in which they are 4976declared: the first member has the lowest memory address and the last member 4977the highest. 4978 4979@item Every data object has an alignment-requirement. The alignment-requirement 4980for all data except structures, unions, and arrays is either the size of the 4981object or the current packing size (specified with either the aligned attribute 4982or the pack pragma), whichever is less. For structures, unions, and arrays, 4983the alignment-requirement is the largest alignment-requirement of its members. 4984Every object is allocated an offset so that: 4985 4986offset % alignment-requirement == 0 4987 4988@item Adjacent bit fields are packed into the same 1-, 2-, or 4-byte allocation 4989unit if the integral types are the same size and if the next bit field fits 4990into the current allocation unit without crossing the boundary imposed by the 4991common alignment requirements of the bit fields. 4992@end enumerate 4993 4994Handling of zero-length bitfields: 4995 4996MSVC interprets zero-length bitfields in the following ways: 4997 4998@enumerate 4999@item If a zero-length bitfield is inserted between two bitfields that would 5000normally be coalesced, the bitfields will not be coalesced. 5001 5002For example: 5003 5004@smallexample 5005struct 5006 @{ 5007 unsigned long bf_1 : 12; 5008 unsigned long : 0; 5009 unsigned long bf_2 : 12; 5010 @} t1; 5011@end smallexample 5012 5013The size of @code{t1} would be 8 bytes with the zero-length bitfield. If the 5014zero-length bitfield were removed, @code{t1}'s size would be 4 bytes. 5015 5016@item If a zero-length bitfield is inserted after a bitfield, @code{foo}, and the 5017alignment of the zero-length bitfield is greater than the member that follows it, 5018@code{bar}, @code{bar} will be aligned as the type of the zero-length bitfield. 5019 5020For example: 5021 5022@smallexample 5023struct 5024 @{ 5025 char foo : 4; 5026 short : 0; 5027 char bar; 5028 @} t2; 5029 5030struct 5031 @{ 5032 char foo : 4; 5033 short : 0; 5034 double bar; 5035 @} t3; 5036@end smallexample 5037 5038For @code{t2}, @code{bar} will be placed at offset 2, rather than offset 1. 5039Accordingly, the size of @code{t2} will be 4. For @code{t3}, the zero-length 5040bitfield will not affect the alignment of @code{bar} or, as a result, the size 5041of the structure. 5042 5043Taking this into account, it is important to note the following: 5044 5045@enumerate 5046@item If a zero-length bitfield follows a normal bitfield, the type of the 5047zero-length bitfield may affect the alignment of the structure as whole. For 5048example, @code{t2} has a size of 4 bytes, since the zero-length bitfield follows a 5049normal bitfield, and is of type short. 5050 5051@item Even if a zero-length bitfield is not followed by a normal bitfield, it may 5052still affect the alignment of the structure: 5053 5054@smallexample 5055struct 5056 @{ 5057 char foo : 6; 5058 long : 0; 5059 @} t4; 5060@end smallexample 5061 5062Here, @code{t4} will take up 4 bytes. 5063@end enumerate 5064 5065@item Zero-length bitfields following non-bitfield members are ignored: 5066 5067@smallexample 5068struct 5069 @{ 5070 char foo; 5071 long : 0; 5072 char bar; 5073 @} t5; 5074@end smallexample 5075 5076Here, @code{t5} will take up 2 bytes. 5077@end enumerate 5078@end table 5079 5080@subsection PowerPC Variable Attributes 5081 5082Three attributes currently are defined for PowerPC configurations: 5083@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 5084 5085For full documentation of the struct attributes please see the 5086documentation in @ref{i386 Variable Attributes}. 5087 5088For documentation of @code{altivec} attribute please see the 5089documentation in @ref{PowerPC Type Attributes}. 5090 5091@subsection SPU Variable Attributes 5092 5093The SPU supports the @code{spu_vector} attribute for variables. For 5094documentation of this attribute please see the documentation in 5095@ref{SPU Type Attributes}. 5096 5097@subsection Xstormy16 Variable Attributes 5098 5099One attribute is currently defined for xstormy16 configurations: 5100@code{below100}. 5101 5102@table @code 5103@item below100 5104@cindex @code{below100} attribute 5105 5106If a variable has the @code{below100} attribute (@code{BELOW100} is 5107allowed also), GCC will place the variable in the first 0x100 bytes of 5108memory and use special opcodes to access it. Such variables will be 5109placed in either the @code{.bss_below100} section or the 5110@code{.data_below100} section. 5111 5112@end table 5113 5114@node Type Attributes 5115@section Specifying Attributes of Types 5116@cindex attribute of types 5117@cindex type attributes 5118 5119The keyword @code{__attribute__} allows you to specify special 5120attributes of @code{struct} and @code{union} types when you define 5121such types. This keyword is followed by an attribute specification 5122inside double parentheses. Seven attributes are currently defined for 5123types: @code{aligned}, @code{packed}, @code{transparent_union}, 5124@code{unused}, @code{deprecated}, @code{visibility}, and 5125@code{may_alias}. Other attributes are defined for functions 5126(@pxref{Function Attributes}) and for variables (@pxref{Variable 5127Attributes}). 5128 5129You may also specify any one of these attributes with @samp{__} 5130preceding and following its keyword. This allows you to use these 5131attributes in header files without being concerned about a possible 5132macro of the same name. For example, you may use @code{__aligned__} 5133instead of @code{aligned}. 5134 5135You may specify type attributes in an enum, struct or union type 5136declaration or definition, or for other types in a @code{typedef} 5137declaration. 5138 5139For an enum, struct or union type, you may specify attributes either 5140between the enum, struct or union tag and the name of the type, or 5141just past the closing curly brace of the @emph{definition}. The 5142former syntax is preferred. 5143 5144@xref{Attribute Syntax}, for details of the exact syntax for using 5145attributes. 5146 5147@table @code 5148@cindex @code{aligned} attribute 5149@item aligned (@var{alignment}) 5150This attribute specifies a minimum alignment (in bytes) for variables 5151of the specified type. For example, the declarations: 5152 5153@smallexample 5154struct S @{ short f[3]; @} __attribute__ ((aligned (8))); 5155typedef int more_aligned_int __attribute__ ((aligned (8))); 5156@end smallexample 5157 5158@noindent 5159force the compiler to insure (as far as it can) that each variable whose 5160type is @code{struct S} or @code{more_aligned_int} will be allocated and 5161aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all 5162variables of type @code{struct S} aligned to 8-byte boundaries allows 5163the compiler to use the @code{ldd} and @code{std} (doubleword load and 5164store) instructions when copying one variable of type @code{struct S} to 5165another, thus improving run-time efficiency. 5166 5167Note that the alignment of any given @code{struct} or @code{union} type 5168is required by the ISO C standard to be at least a perfect multiple of 5169the lowest common multiple of the alignments of all of the members of 5170the @code{struct} or @code{union} in question. This means that you @emph{can} 5171effectively adjust the alignment of a @code{struct} or @code{union} 5172type by attaching an @code{aligned} attribute to any one of the members 5173of such a type, but the notation illustrated in the example above is a 5174more obvious, intuitive, and readable way to request the compiler to 5175adjust the alignment of an entire @code{struct} or @code{union} type. 5176 5177As in the preceding example, you can explicitly specify the alignment 5178(in bytes) that you wish the compiler to use for a given @code{struct} 5179or @code{union} type. Alternatively, you can leave out the alignment factor 5180and just ask the compiler to align a type to the maximum 5181useful alignment for the target machine you are compiling for. For 5182example, you could write: 5183 5184@smallexample 5185struct S @{ short f[3]; @} __attribute__ ((aligned)); 5186@end smallexample 5187 5188Whenever you leave out the alignment factor in an @code{aligned} 5189attribute specification, the compiler automatically sets the alignment 5190for the type to the largest alignment which is ever used for any data 5191type on the target machine you are compiling for. Doing this can often 5192make copy operations more efficient, because the compiler can use 5193whatever instructions copy the biggest chunks of memory when performing 5194copies to or from the variables which have types that you have aligned 5195this way. 5196 5197In the example above, if the size of each @code{short} is 2 bytes, then 5198the size of the entire @code{struct S} type is 6 bytes. The smallest 5199power of two which is greater than or equal to that is 8, so the 5200compiler sets the alignment for the entire @code{struct S} type to 8 5201bytes. 5202 5203Note that although you can ask the compiler to select a time-efficient 5204alignment for a given type and then declare only individual stand-alone 5205objects of that type, the compiler's ability to select a time-efficient 5206alignment is primarily useful only when you plan to create arrays of 5207variables having the relevant (efficiently aligned) type. If you 5208declare or use arrays of variables of an efficiently-aligned type, then 5209it is likely that your program will also be doing pointer arithmetic (or 5210subscripting, which amounts to the same thing) on pointers to the 5211relevant type, and the code that the compiler generates for these 5212pointer arithmetic operations will often be more efficient for 5213efficiently-aligned types than for other types. 5214 5215The @code{aligned} attribute can only increase the alignment; but you 5216can decrease it by specifying @code{packed} as well. See below. 5217 5218Note that the effectiveness of @code{aligned} attributes may be limited 5219by inherent limitations in your linker. On many systems, the linker is 5220only able to arrange for variables to be aligned up to a certain maximum 5221alignment. (For some linkers, the maximum supported alignment may 5222be very very small.) If your linker is only able to align variables 5223up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} 5224in an @code{__attribute__} will still only provide you with 8 byte 5225alignment. See your linker documentation for further information. 5226 5227@item packed 5228This attribute, attached to @code{struct} or @code{union} type 5229definition, specifies that each member (other than zero-width bitfields) 5230of the structure or union is placed to minimize the memory required. When 5231attached to an @code{enum} definition, it indicates that the smallest 5232integral type should be used. 5233 5234@opindex fshort-enums 5235Specifying this attribute for @code{struct} and @code{union} types is 5236equivalent to specifying the @code{packed} attribute on each of the 5237structure or union members. Specifying the @option{-fshort-enums} 5238flag on the line is equivalent to specifying the @code{packed} 5239attribute on all @code{enum} definitions. 5240 5241In the following example @code{struct my_packed_struct}'s members are 5242packed closely together, but the internal layout of its @code{s} member 5243is not packed---to do that, @code{struct my_unpacked_struct} would need to 5244be packed too. 5245 5246@smallexample 5247struct my_unpacked_struct 5248 @{ 5249 char c; 5250 int i; 5251 @}; 5252 5253struct __attribute__ ((__packed__)) my_packed_struct 5254 @{ 5255 char c; 5256 int i; 5257 struct my_unpacked_struct s; 5258 @}; 5259@end smallexample 5260 5261You may only specify this attribute on the definition of an @code{enum}, 5262@code{struct} or @code{union}, not on a @code{typedef} which does not 5263also define the enumerated type, structure or union. 5264 5265@item transparent_union 5266This attribute, attached to a @code{union} type definition, indicates 5267that any function parameter having that union type causes calls to that 5268function to be treated in a special way. 5269 5270First, the argument corresponding to a transparent union type can be of 5271any type in the union; no cast is required. Also, if the union contains 5272a pointer type, the corresponding argument can be a null pointer 5273constant or a void pointer expression; and if the union contains a void 5274pointer type, the corresponding argument can be any pointer expression. 5275If the union member type is a pointer, qualifiers like @code{const} on 5276the referenced type must be respected, just as with normal pointer 5277conversions. 5278 5279Second, the argument is passed to the function using the calling 5280conventions of the first member of the transparent union, not the calling 5281conventions of the union itself. All members of the union must have the 5282same machine representation; this is necessary for this argument passing 5283to work properly. 5284 5285Transparent unions are designed for library functions that have multiple 5286interfaces for compatibility reasons. For example, suppose the 5287@code{wait} function must accept either a value of type @code{int *} to 5288comply with Posix, or a value of type @code{union wait *} to comply with 5289the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, 5290@code{wait} would accept both kinds of arguments, but it would also 5291accept any other pointer type and this would make argument type checking 5292less useful. Instead, @code{<sys/wait.h>} might define the interface 5293as follows: 5294 5295@smallexample 5296typedef union __attribute__ ((__transparent_union__)) 5297 @{ 5298 int *__ip; 5299 union wait *__up; 5300 @} wait_status_ptr_t; 5301 5302pid_t wait (wait_status_ptr_t); 5303@end smallexample 5304 5305This interface allows either @code{int *} or @code{union wait *} 5306arguments to be passed, using the @code{int *} calling convention. 5307The program can call @code{wait} with arguments of either type: 5308 5309@smallexample 5310int w1 () @{ int w; return wait (&w); @} 5311int w2 () @{ union wait w; return wait (&w); @} 5312@end smallexample 5313 5314With this interface, @code{wait}'s implementation might look like this: 5315 5316@smallexample 5317pid_t wait (wait_status_ptr_t p) 5318@{ 5319 return waitpid (-1, p.__ip, 0); 5320@} 5321@end smallexample 5322 5323@item unused 5324When attached to a type (including a @code{union} or a @code{struct}), 5325this attribute means that variables of that type are meant to appear 5326possibly unused. GCC will not produce a warning for any variables of 5327that type, even if the variable appears to do nothing. This is often 5328the case with lock or thread classes, which are usually defined and then 5329not referenced, but contain constructors and destructors that have 5330nontrivial bookkeeping functions. 5331 5332@item deprecated 5333@itemx deprecated (@var{msg}) 5334The @code{deprecated} attribute results in a warning if the type 5335is used anywhere in the source file. This is useful when identifying 5336types that are expected to be removed in a future version of a program. 5337If possible, the warning also includes the location of the declaration 5338of the deprecated type, to enable users to easily find further 5339information about why the type is deprecated, or what they should do 5340instead. Note that the warnings only occur for uses and then only 5341if the type is being applied to an identifier that itself is not being 5342declared as deprecated. 5343 5344@smallexample 5345typedef int T1 __attribute__ ((deprecated)); 5346T1 x; 5347typedef T1 T2; 5348T2 y; 5349typedef T1 T3 __attribute__ ((deprecated)); 5350T3 z __attribute__ ((deprecated)); 5351@end smallexample 5352 5353results in a warning on line 2 and 3 but not lines 4, 5, or 6. No 5354warning is issued for line 4 because T2 is not explicitly 5355deprecated. Line 5 has no warning because T3 is explicitly 5356deprecated. Similarly for line 6. The optional msg 5357argument, which must be a string, will be printed in the warning if 5358present. 5359 5360The @code{deprecated} attribute can also be used for functions and 5361variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) 5362 5363@item may_alias 5364Accesses through pointers to types with this attribute are not subject 5365to type-based alias analysis, but are instead assumed to be able to alias 5366any other type of objects. In the context of 6.5/7 an lvalue expression 5367dereferencing such a pointer is treated like having a character type. 5368See @option{-fstrict-aliasing} for more information on aliasing issues. 5369This extension exists to support some vector APIs, in which pointers to 5370one vector type are permitted to alias pointers to a different vector type. 5371 5372Note that an object of a type with this attribute does not have any 5373special semantics. 5374 5375Example of use: 5376 5377@smallexample 5378typedef short __attribute__((__may_alias__)) short_a; 5379 5380int 5381main (void) 5382@{ 5383 int a = 0x12345678; 5384 short_a *b = (short_a *) &a; 5385 5386 b[1] = 0; 5387 5388 if (a == 0x12345678) 5389 abort(); 5390 5391 exit(0); 5392@} 5393@end smallexample 5394 5395If you replaced @code{short_a} with @code{short} in the variable 5396declaration, the above program would abort when compiled with 5397@option{-fstrict-aliasing}, which is on by default at @option{-O2} or 5398above in recent GCC versions. 5399 5400@item visibility 5401In C++, attribute visibility (@pxref{Function Attributes}) can also be 5402applied to class, struct, union and enum types. Unlike other type 5403attributes, the attribute must appear between the initial keyword and 5404the name of the type; it cannot appear after the body of the type. 5405 5406Note that the type visibility is applied to vague linkage entities 5407associated with the class (vtable, typeinfo node, etc.). In 5408particular, if a class is thrown as an exception in one shared object 5409and caught in another, the class must have default visibility. 5410Otherwise the two shared objects will be unable to use the same 5411typeinfo node and exception handling will break. 5412 5413@end table 5414 5415@subsection ARM Type Attributes 5416 5417On those ARM targets that support @code{dllimport} (such as Symbian 5418OS), you can use the @code{notshared} attribute to indicate that the 5419virtual table and other similar data for a class should not be 5420exported from a DLL@. For example: 5421 5422@smallexample 5423class __declspec(notshared) C @{ 5424public: 5425 __declspec(dllimport) C(); 5426 virtual void f(); 5427@} 5428 5429__declspec(dllexport) 5430C::C() @{@} 5431@end smallexample 5432 5433In this code, @code{C::C} is exported from the current DLL, but the 5434virtual table for @code{C} is not exported. (You can use 5435@code{__attribute__} instead of @code{__declspec} if you prefer, but 5436most Symbian OS code uses @code{__declspec}.) 5437 5438@anchor{MeP Type Attributes} 5439@subsection MeP Type Attributes 5440 5441Many of the MeP variable attributes may be applied to types as well. 5442Specifically, the @code{based}, @code{tiny}, @code{near}, and 5443@code{far} attributes may be applied to either. The @code{io} and 5444@code{cb} attributes may not be applied to types. 5445 5446@anchor{i386 Type Attributes} 5447@subsection i386 Type Attributes 5448 5449Two attributes are currently defined for i386 configurations: 5450@code{ms_struct} and @code{gcc_struct}. 5451 5452@table @code 5453 5454@item ms_struct 5455@itemx gcc_struct 5456@cindex @code{ms_struct} 5457@cindex @code{gcc_struct} 5458 5459If @code{packed} is used on a structure, or if bit-fields are used 5460it may be that the Microsoft ABI packs them differently 5461than GCC would normally pack them. Particularly when moving packed 5462data between functions compiled with GCC and the native Microsoft compiler 5463(either via function call or as data in a file), it may be necessary to access 5464either format. 5465 5466Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 5467compilers to match the native Microsoft compiler. 5468@end table 5469 5470To specify multiple attributes, separate them by commas within the 5471double parentheses: for example, @samp{__attribute__ ((aligned (16), 5472packed))}. 5473 5474@anchor{PowerPC Type Attributes} 5475@subsection PowerPC Type Attributes 5476 5477Three attributes currently are defined for PowerPC configurations: 5478@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 5479 5480For full documentation of the @code{ms_struct} and @code{gcc_struct} 5481attributes please see the documentation in @ref{i386 Type Attributes}. 5482 5483The @code{altivec} attribute allows one to declare AltiVec vector data 5484types supported by the AltiVec Programming Interface Manual. The 5485attribute requires an argument to specify one of three vector types: 5486@code{vector__}, @code{pixel__} (always followed by unsigned short), 5487and @code{bool__} (always followed by unsigned). 5488 5489@smallexample 5490__attribute__((altivec(vector__))) 5491__attribute__((altivec(pixel__))) unsigned short 5492__attribute__((altivec(bool__))) unsigned 5493@end smallexample 5494 5495These attributes mainly are intended to support the @code{__vector}, 5496@code{__pixel}, and @code{__bool} AltiVec keywords. 5497 5498@anchor{SPU Type Attributes} 5499@subsection SPU Type Attributes 5500 5501The SPU supports the @code{spu_vector} attribute for types. This attribute 5502allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU 5503Language Extensions Specification. It is intended to support the 5504@code{__vector} keyword. 5505 5506@node Alignment 5507@section Inquiring on Alignment of Types or Variables 5508@cindex alignment 5509@cindex type alignment 5510@cindex variable alignment 5511 5512The keyword @code{__alignof__} allows you to inquire about how an object 5513is aligned, or the minimum alignment usually required by a type. Its 5514syntax is just like @code{sizeof}. 5515 5516For example, if the target machine requires a @code{double} value to be 5517aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. 5518This is true on many RISC machines. On more traditional machine 5519designs, @code{__alignof__ (double)} is 4 or even 2. 5520 5521Some machines never actually require alignment; they allow reference to any 5522data type even at an odd address. For these machines, @code{__alignof__} 5523reports the smallest alignment that GCC will give the data type, usually as 5524mandated by the target ABI. 5525 5526If the operand of @code{__alignof__} is an lvalue rather than a type, 5527its value is the required alignment for its type, taking into account 5528any minimum alignment specified with GCC's @code{__attribute__} 5529extension (@pxref{Variable Attributes}). For example, after this 5530declaration: 5531 5532@smallexample 5533struct foo @{ int x; char y; @} foo1; 5534@end smallexample 5535 5536@noindent 5537the value of @code{__alignof__ (foo1.y)} is 1, even though its actual 5538alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. 5539 5540It is an error to ask for the alignment of an incomplete type. 5541 5542 5543@node Inline 5544@section An Inline Function is As Fast As a Macro 5545@cindex inline functions 5546@cindex integrating function code 5547@cindex open coding 5548@cindex macros, inline alternative 5549 5550By declaring a function inline, you can direct GCC to make 5551calls to that function faster. One way GCC can achieve this is to 5552integrate that function's code into the code for its callers. This 5553makes execution faster by eliminating the function-call overhead; in 5554addition, if any of the actual argument values are constant, their 5555known values may permit simplifications at compile time so that not 5556all of the inline function's code needs to be included. The effect on 5557code size is less predictable; object code may be larger or smaller 5558with function inlining, depending on the particular case. You can 5559also direct GCC to try to integrate all ``simple enough'' functions 5560into their callers with the option @option{-finline-functions}. 5561 5562GCC implements three different semantics of declaring a function 5563inline. One is available with @option{-std=gnu89} or 5564@option{-fgnu89-inline} or when @code{gnu_inline} attribute is present 5565on all inline declarations, another when 5566@option{-std=c99}, @option{-std=c11}, 5567@option{-std=gnu99} or @option{-std=gnu11} 5568(without @option{-fgnu89-inline}), and the third 5569is used when compiling C++. 5570 5571To declare a function inline, use the @code{inline} keyword in its 5572declaration, like this: 5573 5574@smallexample 5575static inline int 5576inc (int *a) 5577@{ 5578 return (*a)++; 5579@} 5580@end smallexample 5581 5582If you are writing a header file to be included in ISO C90 programs, write 5583@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. 5584 5585The three types of inlining behave similarly in two important cases: 5586when the @code{inline} keyword is used on a @code{static} function, 5587like the example above, and when a function is first declared without 5588using the @code{inline} keyword and then is defined with 5589@code{inline}, like this: 5590 5591@smallexample 5592extern int inc (int *a); 5593inline int 5594inc (int *a) 5595@{ 5596 return (*a)++; 5597@} 5598@end smallexample 5599 5600In both of these common cases, the program behaves the same as if you 5601had not used the @code{inline} keyword, except for its speed. 5602 5603@cindex inline functions, omission of 5604@opindex fkeep-inline-functions 5605When a function is both inline and @code{static}, if all calls to the 5606function are integrated into the caller, and the function's address is 5607never used, then the function's own assembler code is never referenced. 5608In this case, GCC does not actually output assembler code for the 5609function, unless you specify the option @option{-fkeep-inline-functions}. 5610Some calls cannot be integrated for various reasons (in particular, 5611calls that precede the function's definition cannot be integrated, and 5612neither can recursive calls within the definition). If there is a 5613nonintegrated call, then the function is compiled to assembler code as 5614usual. The function must also be compiled as usual if the program 5615refers to its address, because that can't be inlined. 5616 5617@opindex Winline 5618Note that certain usages in a function definition can make it unsuitable 5619for inline substitution. Among these usages are: use of varargs, use of 5620alloca, use of variable sized data types (@pxref{Variable Length}), 5621use of computed goto (@pxref{Labels as Values}), use of nonlocal goto, 5622and nested functions (@pxref{Nested Functions}). Using @option{-Winline} 5623will warn when a function marked @code{inline} could not be substituted, 5624and will give the reason for the failure. 5625 5626@cindex automatic @code{inline} for C++ member fns 5627@cindex @code{inline} automatic for C++ member fns 5628@cindex member fns, automatically @code{inline} 5629@cindex C++ member fns, automatically @code{inline} 5630@opindex fno-default-inline 5631As required by ISO C++, GCC considers member functions defined within 5632the body of a class to be marked inline even if they are 5633not explicitly declared with the @code{inline} keyword. You can 5634override this with @option{-fno-default-inline}; @pxref{C++ Dialect 5635Options,,Options Controlling C++ Dialect}. 5636 5637GCC does not inline any functions when not optimizing unless you specify 5638the @samp{always_inline} attribute for the function, like this: 5639 5640@smallexample 5641/* @r{Prototype.} */ 5642inline void foo (const char) __attribute__((always_inline)); 5643@end smallexample 5644 5645The remainder of this section is specific to GNU C90 inlining. 5646 5647@cindex non-static inline function 5648When an inline function is not @code{static}, then the compiler must assume 5649that there may be calls from other source files; since a global symbol can 5650be defined only once in any program, the function must not be defined in 5651the other source files, so the calls therein cannot be integrated. 5652Therefore, a non-@code{static} inline function is always compiled on its 5653own in the usual fashion. 5654 5655If you specify both @code{inline} and @code{extern} in the function 5656definition, then the definition is used only for inlining. In no case 5657is the function compiled on its own, not even if you refer to its 5658address explicitly. Such an address becomes an external reference, as 5659if you had only declared the function, and had not defined it. 5660 5661This combination of @code{inline} and @code{extern} has almost the 5662effect of a macro. The way to use it is to put a function definition in 5663a header file with these keywords, and put another copy of the 5664definition (lacking @code{inline} and @code{extern}) in a library file. 5665The definition in the header file will cause most calls to the function 5666to be inlined. If any uses of the function remain, they will refer to 5667the single copy in the library. 5668 5669@node Volatiles 5670@section When is a Volatile Object Accessed? 5671@cindex accessing volatiles 5672@cindex volatile read 5673@cindex volatile write 5674@cindex volatile access 5675 5676C has the concept of volatile objects. These are normally accessed by 5677pointers and used for accessing hardware or inter-thread 5678communication. The standard encourages compilers to refrain from 5679optimizations concerning accesses to volatile objects, but leaves it 5680implementation defined as to what constitutes a volatile access. The 5681minimum requirement is that at a sequence point all previous accesses 5682to volatile objects have stabilized and no subsequent accesses have 5683occurred. Thus an implementation is free to reorder and combine 5684volatile accesses which occur between sequence points, but cannot do 5685so for accesses across a sequence point. The use of volatile does 5686not allow you to violate the restriction on updating objects multiple 5687times between two sequence points. 5688 5689Accesses to non-volatile objects are not ordered with respect to 5690volatile accesses. You cannot use a volatile object as a memory 5691barrier to order a sequence of writes to non-volatile memory. For 5692instance: 5693 5694@smallexample 5695int *ptr = @var{something}; 5696volatile int vobj; 5697*ptr = @var{something}; 5698vobj = 1; 5699@end smallexample 5700 5701Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed 5702that the write to @var{*ptr} will have occurred by the time the update 5703of @var{vobj} has happened. If you need this guarantee, you must use 5704a stronger memory barrier such as: 5705 5706@smallexample 5707int *ptr = @var{something}; 5708volatile int vobj; 5709*ptr = @var{something}; 5710asm volatile ("" : : : "memory"); 5711vobj = 1; 5712@end smallexample 5713 5714A scalar volatile object is read when it is accessed in a void context: 5715 5716@smallexample 5717volatile int *src = @var{somevalue}; 5718*src; 5719@end smallexample 5720 5721Such expressions are rvalues, and GCC implements this as a 5722read of the volatile object being pointed to. 5723 5724Assignments are also expressions and have an rvalue. However when 5725assigning to a scalar volatile, the volatile object is not reread, 5726regardless of whether the assignment expression's rvalue is used or 5727not. If the assignment's rvalue is used, the value is that assigned 5728to the volatile object. For instance, there is no read of @var{vobj} 5729in all the following cases: 5730 5731@smallexample 5732int obj; 5733volatile int vobj; 5734vobj = @var{something}; 5735obj = vobj = @var{something}; 5736obj ? vobj = @var{onething} : vobj = @var{anotherthing}; 5737obj = (@var{something}, vobj = @var{anotherthing}); 5738@end smallexample 5739 5740If you need to read the volatile object after an assignment has 5741occurred, you must use a separate expression with an intervening 5742sequence point. 5743 5744As bitfields are not individually addressable, volatile bitfields may 5745be implicitly read when written to, or when adjacent bitfields are 5746accessed. Bitfield operations may be optimized such that adjacent 5747bitfields are only partially accessed, if they straddle a storage unit 5748boundary. For these reasons it is unwise to use volatile bitfields to 5749access hardware. 5750 5751@node Extended Asm 5752@section Assembler Instructions with C Expression Operands 5753@cindex extended @code{asm} 5754@cindex @code{asm} expressions 5755@cindex assembler instructions 5756@cindex registers 5757 5758In an assembler instruction using @code{asm}, you can specify the 5759operands of the instruction using C expressions. This means you need not 5760guess which registers or memory locations will contain the data you want 5761to use. 5762 5763You must specify an assembler instruction template much like what 5764appears in a machine description, plus an operand constraint string for 5765each operand. 5766 5767For example, here is how to use the 68881's @code{fsinx} instruction: 5768 5769@smallexample 5770asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); 5771@end smallexample 5772 5773@noindent 5774Here @code{angle} is the C expression for the input operand while 5775@code{result} is that of the output operand. Each has @samp{"f"} as its 5776operand constraint, saying that a floating point register is required. 5777The @samp{=} in @samp{=f} indicates that the operand is an output; all 5778output operands' constraints must use @samp{=}. The constraints use the 5779same language used in the machine description (@pxref{Constraints}). 5780 5781Each operand is described by an operand-constraint string followed by 5782the C expression in parentheses. A colon separates the assembler 5783template from the first output operand and another separates the last 5784output operand from the first input, if any. Commas separate the 5785operands within each group. The total number of operands is currently 5786limited to 30; this limitation may be lifted in some future version of 5787GCC@. 5788 5789If there are no output operands but there are input operands, you must 5790place two consecutive colons surrounding the place where the output 5791operands would go. 5792 5793As of GCC version 3.1, it is also possible to specify input and output 5794operands using symbolic names which can be referenced within the 5795assembler code. These names are specified inside square brackets 5796preceding the constraint string, and can be referenced inside the 5797assembler code using @code{%[@var{name}]} instead of a percentage sign 5798followed by the operand number. Using named operands the above example 5799could look like: 5800 5801@smallexample 5802asm ("fsinx %[angle],%[output]" 5803 : [output] "=f" (result) 5804 : [angle] "f" (angle)); 5805@end smallexample 5806 5807@noindent 5808Note that the symbolic operand names have no relation whatsoever to 5809other C identifiers. You may use any name you like, even those of 5810existing C symbols, but you must ensure that no two operands within the same 5811assembler construct use the same symbolic name. 5812 5813Output operand expressions must be lvalues; the compiler can check this. 5814The input operands need not be lvalues. The compiler cannot check 5815whether the operands have data types that are reasonable for the 5816instruction being executed. It does not parse the assembler instruction 5817template and does not know what it means or even whether it is valid 5818assembler input. The extended @code{asm} feature is most often used for 5819machine instructions the compiler itself does not know exist. If 5820the output expression cannot be directly addressed (for example, it is a 5821bit-field), your constraint must allow a register. In that case, GCC 5822will use the register as the output of the @code{asm}, and then store 5823that register into the output. 5824 5825The ordinary output operands must be write-only; GCC will assume that 5826the values in these operands before the instruction are dead and need 5827not be generated. Extended asm supports input-output or read-write 5828operands. Use the constraint character @samp{+} to indicate such an 5829operand and list it with the output operands. You should only use 5830read-write operands when the constraints for the operand (or the 5831operand in which only some of the bits are to be changed) allow a 5832register. 5833 5834You may, as an alternative, logically split its function into two 5835separate operands, one input operand and one write-only output 5836operand. The connection between them is expressed by constraints 5837which say they need to be in the same location when the instruction 5838executes. You can use the same C expression for both operands, or 5839different expressions. For example, here we write the (fictitious) 5840@samp{combine} instruction with @code{bar} as its read-only source 5841operand and @code{foo} as its read-write destination: 5842 5843@smallexample 5844asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); 5845@end smallexample 5846 5847@noindent 5848The constraint @samp{"0"} for operand 1 says that it must occupy the 5849same location as operand 0. A number in constraint is allowed only in 5850an input operand and it must refer to an output operand. 5851 5852Only a number in the constraint can guarantee that one operand will be in 5853the same place as another. The mere fact that @code{foo} is the value 5854of both operands is not enough to guarantee that they will be in the 5855same place in the generated assembler code. The following would not 5856work reliably: 5857 5858@smallexample 5859asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); 5860@end smallexample 5861 5862Various optimizations or reloading could cause operands 0 and 1 to be in 5863different registers; GCC knows no reason not to do so. For example, the 5864compiler might find a copy of the value of @code{foo} in one register and 5865use it for operand 1, but generate the output operand 0 in a different 5866register (copying it afterward to @code{foo}'s own address). Of course, 5867since the register for operand 1 is not even mentioned in the assembler 5868code, the result will not work, but GCC can't tell that. 5869 5870As of GCC version 3.1, one may write @code{[@var{name}]} instead of 5871the operand number for a matching constraint. For example: 5872 5873@smallexample 5874asm ("cmoveq %1,%2,%[result]" 5875 : [result] "=r"(result) 5876 : "r" (test), "r"(new), "[result]"(old)); 5877@end smallexample 5878 5879Sometimes you need to make an @code{asm} operand be a specific register, 5880but there's no matching constraint letter for that register @emph{by 5881itself}. To force the operand into that register, use a local variable 5882for the operand and specify the register in the variable declaration. 5883@xref{Explicit Reg Vars}. Then for the @code{asm} operand, use any 5884register constraint letter that matches the register: 5885 5886@smallexample 5887register int *p1 asm ("r0") = @dots{}; 5888register int *p2 asm ("r1") = @dots{}; 5889register int *result asm ("r0"); 5890asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 5891@end smallexample 5892 5893@anchor{Example of asm with clobbered asm reg} 5894In the above example, beware that a register that is call-clobbered by 5895the target ABI will be overwritten by any function call in the 5896assignment, including library calls for arithmetic operators. 5897Also a register may be clobbered when generating some operations, 5898like variable shift, memory copy or memory move on x86. 5899Assuming it is a call-clobbered register, this may happen to @code{r0} 5900above by the assignment to @code{p2}. If you have to use such a 5901register, use temporary variables for expressions between the register 5902assignment and use: 5903 5904@smallexample 5905int t1 = @dots{}; 5906register int *p1 asm ("r0") = @dots{}; 5907register int *p2 asm ("r1") = t1; 5908register int *result asm ("r0"); 5909asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 5910@end smallexample 5911 5912Some instructions clobber specific hard registers. To describe this, 5913write a third colon after the input operands, followed by the names of 5914the clobbered hard registers (given as strings). Here is a realistic 5915example for the VAX: 5916 5917@smallexample 5918asm volatile ("movc3 %0,%1,%2" 5919 : /* @r{no outputs} */ 5920 : "g" (from), "g" (to), "g" (count) 5921 : "r0", "r1", "r2", "r3", "r4", "r5"); 5922@end smallexample 5923 5924You may not write a clobber description in a way that overlaps with an 5925input or output operand. For example, you may not have an operand 5926describing a register class with one member if you mention that register 5927in the clobber list. Variables declared to live in specific registers 5928(@pxref{Explicit Reg Vars}), and used as asm input or output operands must 5929have no part mentioned in the clobber description. 5930There is no way for you to specify that an input 5931operand is modified without also specifying it as an output 5932operand. Note that if all the output operands you specify are for this 5933purpose (and hence unused), you will then also need to specify 5934@code{volatile} for the @code{asm} construct, as described below, to 5935prevent GCC from deleting the @code{asm} statement as unused. 5936 5937If you refer to a particular hardware register from the assembler code, 5938you will probably have to list the register after the third colon to 5939tell the compiler the register's value is modified. In some assemblers, 5940the register names begin with @samp{%}; to produce one @samp{%} in the 5941assembler code, you must write @samp{%%} in the input. 5942 5943If your assembler instruction can alter the condition code register, add 5944@samp{cc} to the list of clobbered registers. GCC on some machines 5945represents the condition codes as a specific hardware register; 5946@samp{cc} serves to name this register. On other machines, the 5947condition code is handled differently, and specifying @samp{cc} has no 5948effect. But it is valid no matter what the machine. 5949 5950If your assembler instructions access memory in an unpredictable 5951fashion, add @samp{memory} to the list of clobbered registers. This 5952will cause GCC to not keep memory values cached in registers across the 5953assembler instruction and not optimize stores or loads to that memory. 5954You will also want to add the @code{volatile} keyword if the memory 5955affected is not listed in the inputs or outputs of the @code{asm}, as 5956the @samp{memory} clobber does not count as a side-effect of the 5957@code{asm}. If you know how large the accessed memory is, you can add 5958it as input or output but if this is not known, you should add 5959@samp{memory}. As an example, if you access ten bytes of a string, you 5960can use a memory input like: 5961 5962@smallexample 5963@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}. 5964@end smallexample 5965 5966Note that in the following example the memory input is necessary, 5967otherwise GCC might optimize the store to @code{x} away: 5968@smallexample 5969int foo () 5970@{ 5971 int x = 42; 5972 int *y = &x; 5973 int result; 5974 asm ("magic stuff accessing an 'int' pointed to by '%1'" 5975 "=&d" (r) : "a" (y), "m" (*y)); 5976 return result; 5977@} 5978@end smallexample 5979 5980You can put multiple assembler instructions together in a single 5981@code{asm} template, separated by the characters normally used in assembly 5982code for the system. A combination that works in most places is a newline 5983to break the line, plus a tab character to move to the instruction field 5984(written as @samp{\n\t}). Sometimes semicolons can be used, if the 5985assembler allows semicolons as a line-breaking character. Note that some 5986assembler dialects use semicolons to start a comment. 5987The input operands are guaranteed not to use any of the clobbered 5988registers, and neither will the output operands' addresses, so you can 5989read and write the clobbered registers as many times as you like. Here 5990is an example of multiple instructions in a template; it assumes the 5991subroutine @code{_foo} accepts arguments in registers 9 and 10: 5992 5993@smallexample 5994asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo" 5995 : /* no outputs */ 5996 : "g" (from), "g" (to) 5997 : "r9", "r10"); 5998@end smallexample 5999 6000Unless an output operand has the @samp{&} constraint modifier, GCC 6001may allocate it in the same register as an unrelated input operand, on 6002the assumption the inputs are consumed before the outputs are produced. 6003This assumption may be false if the assembler code actually consists of 6004more than one instruction. In such a case, use @samp{&} for each output 6005operand that may not overlap an input. @xref{Modifiers}. 6006 6007If you want to test the condition code produced by an assembler 6008instruction, you must include a branch and a label in the @code{asm} 6009construct, as follows: 6010 6011@smallexample 6012asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:" 6013 : "g" (result) 6014 : "g" (input)); 6015@end smallexample 6016 6017@noindent 6018This assumes your assembler supports local labels, as the GNU assembler 6019and most Unix assemblers do. 6020 6021Speaking of labels, jumps from one @code{asm} to another are not 6022supported. The compiler's optimizers do not know about these jumps, and 6023therefore they cannot take account of them when deciding how to 6024optimize. @xref{Extended asm with goto}. 6025 6026@cindex macros containing @code{asm} 6027Usually the most convenient way to use these @code{asm} instructions is to 6028encapsulate them in macros that look like functions. For example, 6029 6030@smallexample 6031#define sin(x) \ 6032(@{ double __value, __arg = (x); \ 6033 asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ 6034 __value; @}) 6035@end smallexample 6036 6037@noindent 6038Here the variable @code{__arg} is used to make sure that the instruction 6039operates on a proper @code{double} value, and to accept only those 6040arguments @code{x} which can convert automatically to a @code{double}. 6041 6042Another way to make sure the instruction operates on the correct data 6043type is to use a cast in the @code{asm}. This is different from using a 6044variable @code{__arg} in that it converts more different types. For 6045example, if the desired type were @code{int}, casting the argument to 6046@code{int} would accept a pointer with no complaint, while assigning the 6047argument to an @code{int} variable named @code{__arg} would warn about 6048using a pointer unless the caller explicitly casts it. 6049 6050If an @code{asm} has output operands, GCC assumes for optimization 6051purposes the instruction has no side effects except to change the output 6052operands. This does not mean instructions with a side effect cannot be 6053used, but you must be careful, because the compiler may eliminate them 6054if the output operands aren't used, or move them out of loops, or 6055replace two with one if they constitute a common subexpression. Also, 6056if your instruction does have a side effect on a variable that otherwise 6057appears not to change, the old value of the variable may be reused later 6058if it happens to be found in a register. 6059 6060You can prevent an @code{asm} instruction from being deleted 6061by writing the keyword @code{volatile} after 6062the @code{asm}. For example: 6063 6064@smallexample 6065#define get_and_set_priority(new) \ 6066(@{ int __old; \ 6067 asm volatile ("get_and_set_priority %0, %1" \ 6068 : "=g" (__old) : "g" (new)); \ 6069 __old; @}) 6070@end smallexample 6071 6072@noindent 6073The @code{volatile} keyword indicates that the instruction has 6074important side-effects. GCC will not delete a volatile @code{asm} if 6075it is reachable. (The instruction can still be deleted if GCC can 6076prove that control-flow will never reach the location of the 6077instruction.) Note that even a volatile @code{asm} instruction 6078can be moved relative to other code, including across jump 6079instructions. For example, on many targets there is a system 6080register which can be set to control the rounding mode of 6081floating point operations. You might try 6082setting it with a volatile @code{asm}, like this PowerPC example: 6083 6084@smallexample 6085 asm volatile("mtfsf 255,%0" : : "f" (fpenv)); 6086 sum = x + y; 6087@end smallexample 6088 6089@noindent 6090This will not work reliably, as the compiler may move the addition back 6091before the volatile @code{asm}. To make it work you need to add an 6092artificial dependency to the @code{asm} referencing a variable in the code 6093you don't want moved, for example: 6094 6095@smallexample 6096 asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv)); 6097 sum = x + y; 6098@end smallexample 6099 6100Similarly, you can't expect a 6101sequence of volatile @code{asm} instructions to remain perfectly 6102consecutive. If you want consecutive output, use a single @code{asm}. 6103Also, GCC will perform some optimizations across a volatile @code{asm} 6104instruction; GCC does not ``forget everything'' when it encounters 6105a volatile @code{asm} instruction the way some other compilers do. 6106 6107An @code{asm} instruction without any output operands will be treated 6108identically to a volatile @code{asm} instruction. 6109 6110It is a natural idea to look for a way to give access to the condition 6111code left by the assembler instruction. However, when we attempted to 6112implement this, we found no way to make it work reliably. The problem 6113is that output operands might need reloading, which would result in 6114additional following ``store'' instructions. On most machines, these 6115instructions would alter the condition code before there was time to 6116test it. This problem doesn't arise for ordinary ``test'' and 6117``compare'' instructions because they don't have any output operands. 6118 6119For reasons similar to those described above, it is not possible to give 6120an assembler instruction access to the condition code left by previous 6121instructions. 6122 6123@anchor{Extended asm with goto} 6124As of GCC version 4.5, @code{asm goto} may be used to have the assembly 6125jump to one or more C labels. In this form, a fifth section after the 6126clobber list contains a list of all C labels to which the assembly may jump. 6127Each label operand is implicitly self-named. The @code{asm} is also assumed 6128to fall through to the next statement. 6129 6130This form of @code{asm} is restricted to not have outputs. This is due 6131to a internal restriction in the compiler that control transfer instructions 6132cannot have outputs. This restriction on @code{asm goto} may be lifted 6133in some future version of the compiler. In the mean time, @code{asm goto} 6134may include a memory clobber, and so leave outputs in memory. 6135 6136@smallexample 6137int frob(int x) 6138@{ 6139 int y; 6140 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5" 6141 : : "r"(x), "r"(&y) : "r5", "memory" : error); 6142 return y; 6143 error: 6144 return -1; 6145@} 6146@end smallexample 6147 6148In this (inefficient) example, the @code{frob} instruction sets the 6149carry bit to indicate an error. The @code{jc} instruction detects 6150this and branches to the @code{error} label. Finally, the output 6151of the @code{frob} instruction (@code{%r5}) is stored into the memory 6152for variable @code{y}, which is later read by the @code{return} statement. 6153 6154@smallexample 6155void doit(void) 6156@{ 6157 int i = 0; 6158 asm goto ("mfsr %%r1, 123; jmp %%r1;" 6159 ".pushsection doit_table;" 6160 ".long %l0, %l1, %l2, %l3;" 6161 ".popsection" 6162 : : : "r1" : label1, label2, label3, label4); 6163 __builtin_unreachable (); 6164 6165 label1: 6166 f1(); 6167 return; 6168 label2: 6169 f2(); 6170 return; 6171 label3: 6172 i = 1; 6173 label4: 6174 f3(i); 6175@} 6176@end smallexample 6177 6178In this (also inefficient) example, the @code{mfsr} instruction reads 6179an address from some out-of-band machine register, and the following 6180@code{jmp} instruction branches to that address. The address read by 6181the @code{mfsr} instruction is assumed to have been previously set via 6182some application-specific mechanism to be one of the four values stored 6183in the @code{doit_table} section. Finally, the @code{asm} is followed 6184by a call to @code{__builtin_unreachable} to indicate that the @code{asm} 6185does not in fact fall through. 6186 6187@smallexample 6188#define TRACE1(NUM) \ 6189 do @{ \ 6190 asm goto ("0: nop;" \ 6191 ".pushsection trace_table;" \ 6192 ".long 0b, %l0;" \ 6193 ".popsection" \ 6194 : : : : trace#NUM); \ 6195 if (0) @{ trace#NUM: trace(); @} \ 6196 @} while (0) 6197#define TRACE TRACE1(__COUNTER__) 6198@end smallexample 6199 6200In this example (which in fact inspired the @code{asm goto} feature) 6201we want on rare occasions to call the @code{trace} function; on other 6202occasions we'd like to keep the overhead to the absolute minimum. 6203The normal code path consists of a single @code{nop} instruction. 6204However, we record the address of this @code{nop} together with the 6205address of a label that calls the @code{trace} function. This allows 6206the @code{nop} instruction to be patched at runtime to be an 6207unconditional branch to the stored label. It is assumed that an 6208optimizing compiler will move the labeled block out of line, to 6209optimize the fall through path from the @code{asm}. 6210 6211If you are writing a header file that should be includable in ISO C 6212programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate 6213Keywords}. 6214 6215@subsection Size of an @code{asm} 6216 6217Some targets require that GCC track the size of each instruction used in 6218order to generate correct code. Because the final length of an 6219@code{asm} is only known by the assembler, GCC must make an estimate as 6220to how big it will be. The estimate is formed by counting the number of 6221statements in the pattern of the @code{asm} and multiplying that by the 6222length of the longest instruction on that processor. Statements in the 6223@code{asm} are identified by newline characters and whatever statement 6224separator characters are supported by the assembler; on most processors 6225this is the `@code{;}' character. 6226 6227Normally, GCC's estimate is perfectly adequate to ensure that correct 6228code is generated, but it is possible to confuse the compiler if you use 6229pseudo instructions or assembler macros that expand into multiple real 6230instructions or if you use assembler directives that expand to more 6231space in the object file than would be needed for a single instruction. 6232If this happens then the assembler will produce a diagnostic saying that 6233a label is unreachable. 6234 6235@subsection i386 floating point asm operands 6236 6237There are several rules on the usage of stack-like regs in 6238asm_operands insns. These rules apply only to the operands that are 6239stack-like regs: 6240 6241@enumerate 6242@item 6243Given a set of input regs that die in an asm_operands, it is 6244necessary to know which are implicitly popped by the asm, and 6245which must be explicitly popped by gcc. 6246 6247An input reg that is implicitly popped by the asm must be 6248explicitly clobbered, unless it is constrained to match an 6249output operand. 6250 6251@item 6252For any input reg that is implicitly popped by an asm, it is 6253necessary to know how to adjust the stack to compensate for the pop. 6254If any non-popped input is closer to the top of the reg-stack than 6255the implicitly popped reg, it would not be possible to know what the 6256stack looked like---it's not clear how the rest of the stack ``slides 6257up''. 6258 6259All implicitly popped input regs must be closer to the top of 6260the reg-stack than any input that is not implicitly popped. 6261 6262It is possible that if an input dies in an insn, reload might 6263use the input reg for an output reload. Consider this example: 6264 6265@smallexample 6266asm ("foo" : "=t" (a) : "f" (b)); 6267@end smallexample 6268 6269This asm says that input B is not popped by the asm, and that 6270the asm pushes a result onto the reg-stack, i.e., the stack is one 6271deeper after the asm than it was before. But, it is possible that 6272reload will think that it can use the same reg for both the input and 6273the output, if input B dies in this insn. 6274 6275If any input operand uses the @code{f} constraint, all output reg 6276constraints must use the @code{&} earlyclobber. 6277 6278The asm above would be written as 6279 6280@smallexample 6281asm ("foo" : "=&t" (a) : "f" (b)); 6282@end smallexample 6283 6284@item 6285Some operands need to be in particular places on the stack. All 6286output operands fall in this category---there is no other way to 6287know which regs the outputs appear in unless the user indicates 6288this in the constraints. 6289 6290Output operands must specifically indicate which reg an output 6291appears in after an asm. @code{=f} is not allowed: the operand 6292constraints must select a class with a single reg. 6293 6294@item 6295Output operands may not be ``inserted'' between existing stack regs. 6296Since no 387 opcode uses a read/write operand, all output operands 6297are dead before the asm_operands, and are pushed by the asm_operands. 6298It makes no sense to push anywhere but the top of the reg-stack. 6299 6300Output operands must start at the top of the reg-stack: output 6301operands may not ``skip'' a reg. 6302 6303@item 6304Some asm statements may need extra stack space for internal 6305calculations. This can be guaranteed by clobbering stack registers 6306unrelated to the inputs and outputs. 6307 6308@end enumerate 6309 6310Here are a couple of reasonable asms to want to write. This asm 6311takes one input, which is internally popped, and produces two outputs. 6312 6313@smallexample 6314asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); 6315@end smallexample 6316 6317This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode, 6318and replaces them with one output. The user must code the @code{st(1)} 6319clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs. 6320 6321@smallexample 6322asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); 6323@end smallexample 6324 6325@include md.texi 6326 6327@node Asm Labels 6328@section Controlling Names Used in Assembler Code 6329@cindex assembler names for identifiers 6330@cindex names used in assembler code 6331@cindex identifiers, names in assembler code 6332 6333You can specify the name to be used in the assembler code for a C 6334function or variable by writing the @code{asm} (or @code{__asm__}) 6335keyword after the declarator as follows: 6336 6337@smallexample 6338int foo asm ("myfoo") = 2; 6339@end smallexample 6340 6341@noindent 6342This specifies that the name to be used for the variable @code{foo} in 6343the assembler code should be @samp{myfoo} rather than the usual 6344@samp{_foo}. 6345 6346On systems where an underscore is normally prepended to the name of a C 6347function or variable, this feature allows you to define names for the 6348linker that do not start with an underscore. 6349 6350It does not make sense to use this feature with a non-static local 6351variable since such variables do not have assembler names. If you are 6352trying to put the variable in a particular register, see @ref{Explicit 6353Reg Vars}. GCC presently accepts such code with a warning, but will 6354probably be changed to issue an error, rather than a warning, in the 6355future. 6356 6357You cannot use @code{asm} in this way in a function @emph{definition}; but 6358you can get the same effect by writing a declaration for the function 6359before its definition and putting @code{asm} there, like this: 6360 6361@smallexample 6362extern func () asm ("FUNC"); 6363 6364func (x, y) 6365 int x, y; 6366/* @r{@dots{}} */ 6367@end smallexample 6368 6369It is up to you to make sure that the assembler names you choose do not 6370conflict with any other assembler symbols. Also, you must not use a 6371register name; that would produce completely invalid assembler code. GCC 6372does not as yet have the ability to store static variables in registers. 6373Perhaps that will be added. 6374 6375@node Explicit Reg Vars 6376@section Variables in Specified Registers 6377@cindex explicit register variables 6378@cindex variables in specified registers 6379@cindex specified registers 6380@cindex registers, global allocation 6381 6382GNU C allows you to put a few global variables into specified hardware 6383registers. You can also specify the register in which an ordinary 6384register variable should be allocated. 6385 6386@itemize @bullet 6387@item 6388Global register variables reserve registers throughout the program. 6389This may be useful in programs such as programming language 6390interpreters which have a couple of global variables that are accessed 6391very often. 6392 6393@item 6394Local register variables in specific registers do not reserve the 6395registers, except at the point where they are used as input or output 6396operands in an @code{asm} statement and the @code{asm} statement itself is 6397not deleted. The compiler's data flow analysis is capable of determining 6398where the specified registers contain live values, and where they are 6399available for other uses. Stores into local register variables may be deleted 6400when they appear to be dead according to dataflow analysis. References 6401to local register variables may be deleted or moved or simplified. 6402 6403These local variables are sometimes convenient for use with the extended 6404@code{asm} feature (@pxref{Extended Asm}), if you want to write one 6405output of the assembler instruction directly into a particular register. 6406(This will work provided the register you specify fits the constraints 6407specified for that operand in the @code{asm}.) 6408@end itemize 6409 6410@menu 6411* Global Reg Vars:: 6412* Local Reg Vars:: 6413@end menu 6414 6415@node Global Reg Vars 6416@subsection Defining Global Register Variables 6417@cindex global register variables 6418@cindex registers, global variables in 6419 6420You can define a global register variable in GNU C like this: 6421 6422@smallexample 6423register int *foo asm ("a5"); 6424@end smallexample 6425 6426@noindent 6427Here @code{a5} is the name of the register which should be used. Choose a 6428register which is normally saved and restored by function calls on your 6429machine, so that library routines will not clobber it. 6430 6431Naturally the register name is cpu-dependent, so you would need to 6432conditionalize your program according to cpu type. The register 6433@code{a5} would be a good choice on a 68000 for a variable of pointer 6434type. On machines with register windows, be sure to choose a ``global'' 6435register that is not affected magically by the function call mechanism. 6436 6437In addition, operating systems on one type of cpu may differ in how they 6438name the registers; then you would need additional conditionals. For 6439example, some 68000 operating systems call this register @code{%a5}. 6440 6441Eventually there may be a way of asking the compiler to choose a register 6442automatically, but first we need to figure out how it should choose and 6443how to enable you to guide the choice. No solution is evident. 6444 6445Defining a global register variable in a certain register reserves that 6446register entirely for this use, at least within the current compilation. 6447The register will not be allocated for any other purpose in the functions 6448in the current compilation. The register will not be saved and restored by 6449these functions. Stores into this register are never deleted even if they 6450would appear to be dead, but references may be deleted or moved or 6451simplified. 6452 6453It is not safe to access the global register variables from signal 6454handlers, or from more than one thread of control, because the system 6455library routines may temporarily use the register for other things (unless 6456you recompile them specially for the task at hand). 6457 6458@cindex @code{qsort}, and global register variables 6459It is not safe for one function that uses a global register variable to 6460call another such function @code{foo} by way of a third function 6461@code{lose} that was compiled without knowledge of this variable (i.e.@: in a 6462different source file in which the variable wasn't declared). This is 6463because @code{lose} might save the register and put some other value there. 6464For example, you can't expect a global register variable to be available in 6465the comparison-function that you pass to @code{qsort}, since @code{qsort} 6466might have put something else in that register. (If you are prepared to 6467recompile @code{qsort} with the same global register variable, you can 6468solve this problem.) 6469 6470If you want to recompile @code{qsort} or other source files which do not 6471actually use your global register variable, so that they will not use that 6472register for any other purpose, then it suffices to specify the compiler 6473option @option{-ffixed-@var{reg}}. You need not actually add a global 6474register declaration to their source code. 6475 6476A function which can alter the value of a global register variable cannot 6477safely be called from a function compiled without this variable, because it 6478could clobber the value the caller expects to find there on return. 6479Therefore, the function which is the entry point into the part of the 6480program that uses the global register variable must explicitly save and 6481restore the value which belongs to its caller. 6482 6483@cindex register variable after @code{longjmp} 6484@cindex global register after @code{longjmp} 6485@cindex value after @code{longjmp} 6486@findex longjmp 6487@findex setjmp 6488On most machines, @code{longjmp} will restore to each global register 6489variable the value it had at the time of the @code{setjmp}. On some 6490machines, however, @code{longjmp} will not change the value of global 6491register variables. To be portable, the function that called @code{setjmp} 6492should make other arrangements to save the values of the global register 6493variables, and to restore them in a @code{longjmp}. This way, the same 6494thing will happen regardless of what @code{longjmp} does. 6495 6496All global register variable declarations must precede all function 6497definitions. If such a declaration could appear after function 6498definitions, the declaration would be too late to prevent the register from 6499being used for other purposes in the preceding functions. 6500 6501Global register variables may not have initial values, because an 6502executable file has no means to supply initial contents for a register. 6503 6504On the SPARC, there are reports that g3 @dots{} g7 are suitable 6505registers, but certain library functions, such as @code{getwd}, as well 6506as the subroutines for division and remainder, modify g3 and g4. g1 and 6507g2 are local temporaries. 6508 6509On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7. 6510Of course, it will not do to use more than a few of those. 6511 6512@node Local Reg Vars 6513@subsection Specifying Registers for Local Variables 6514@cindex local variables, specifying registers 6515@cindex specifying registers for local variables 6516@cindex registers for local variables 6517 6518You can define a local register variable with a specified register 6519like this: 6520 6521@smallexample 6522register int *foo asm ("a5"); 6523@end smallexample 6524 6525@noindent 6526Here @code{a5} is the name of the register which should be used. Note 6527that this is the same syntax used for defining global register 6528variables, but for a local variable it would appear within a function. 6529 6530Naturally the register name is cpu-dependent, but this is not a 6531problem, since specific registers are most often useful with explicit 6532assembler instructions (@pxref{Extended Asm}). Both of these things 6533generally require that you conditionalize your program according to 6534cpu type. 6535 6536In addition, operating systems on one type of cpu may differ in how they 6537name the registers; then you would need additional conditionals. For 6538example, some 68000 operating systems call this register @code{%a5}. 6539 6540Defining such a register variable does not reserve the register; it 6541remains available for other uses in places where flow control determines 6542the variable's value is not live. 6543 6544This option does not guarantee that GCC will generate code that has 6545this variable in the register you specify at all times. You may not 6546code an explicit reference to this register in the @emph{assembler 6547instruction template} part of an @code{asm} statement and assume it will 6548always refer to this variable. However, using the variable as an 6549@code{asm} @emph{operand} guarantees that the specified register is used 6550for the operand. 6551 6552Stores into local register variables may be deleted when they appear to be dead 6553according to dataflow analysis. References to local register variables may 6554be deleted or moved or simplified. 6555 6556As for global register variables, it's recommended that you choose a 6557register which is normally saved and restored by function calls on 6558your machine, so that library routines will not clobber it. A common 6559pitfall is to initialize multiple call-clobbered registers with 6560arbitrary expressions, where a function call or library call for an 6561arithmetic operator will overwrite a register value from a previous 6562assignment, for example @code{r0} below: 6563@smallexample 6564register int *p1 asm ("r0") = @dots{}; 6565register int *p2 asm ("r1") = @dots{}; 6566@end smallexample 6567In those cases, a solution is to use a temporary variable for 6568each arbitrary expression. @xref{Example of asm with clobbered asm reg}. 6569 6570@node Alternate Keywords 6571@section Alternate Keywords 6572@cindex alternate keywords 6573@cindex keywords, alternate 6574 6575@option{-ansi} and the various @option{-std} options disable certain 6576keywords. This causes trouble when you want to use GNU C extensions, or 6577a general-purpose header file that should be usable by all programs, 6578including ISO C programs. The keywords @code{asm}, @code{typeof} and 6579@code{inline} are not available in programs compiled with 6580@option{-ansi} or @option{-std} (although @code{inline} can be used in a 6581program compiled with @option{-std=c99} or @option{-std=c11}). The 6582ISO C99 keyword 6583@code{restrict} is only available when @option{-std=gnu99} (which will 6584eventually be the default) or @option{-std=c99} (or the equivalent 6585@option{-std=iso9899:1999}), or an option for a later standard 6586version, is used. 6587 6588The way to solve these problems is to put @samp{__} at the beginning and 6589end of each problematical keyword. For example, use @code{__asm__} 6590instead of @code{asm}, and @code{__inline__} instead of @code{inline}. 6591 6592Other C compilers won't accept these alternative keywords; if you want to 6593compile with another compiler, you can define the alternate keywords as 6594macros to replace them with the customary keywords. It looks like this: 6595 6596@smallexample 6597#ifndef __GNUC__ 6598#define __asm__ asm 6599#endif 6600@end smallexample 6601 6602@findex __extension__ 6603@opindex pedantic 6604@option{-pedantic} and other options cause warnings for many GNU C extensions. 6605You can 6606prevent such warnings within one expression by writing 6607@code{__extension__} before the expression. @code{__extension__} has no 6608effect aside from this. 6609 6610@node Incomplete Enums 6611@section Incomplete @code{enum} Types 6612 6613You can define an @code{enum} tag without specifying its possible values. 6614This results in an incomplete type, much like what you get if you write 6615@code{struct foo} without describing the elements. A later declaration 6616which does specify the possible values completes the type. 6617 6618You can't allocate variables or storage using the type while it is 6619incomplete. However, you can work with pointers to that type. 6620 6621This extension may not be very useful, but it makes the handling of 6622@code{enum} more consistent with the way @code{struct} and @code{union} 6623are handled. 6624 6625This extension is not supported by GNU C++. 6626 6627@node Function Names 6628@section Function Names as Strings 6629@cindex @code{__func__} identifier 6630@cindex @code{__FUNCTION__} identifier 6631@cindex @code{__PRETTY_FUNCTION__} identifier 6632 6633GCC provides three magic variables which hold the name of the current 6634function, as a string. The first of these is @code{__func__}, which 6635is part of the C99 standard: 6636 6637The identifier @code{__func__} is implicitly declared by the translator 6638as if, immediately following the opening brace of each function 6639definition, the declaration 6640 6641@smallexample 6642static const char __func__[] = "function-name"; 6643@end smallexample 6644 6645@noindent 6646appeared, where function-name is the name of the lexically-enclosing 6647function. This name is the unadorned name of the function. 6648 6649@code{__FUNCTION__} is another name for @code{__func__}. Older 6650versions of GCC recognize only this name. However, it is not 6651standardized. For maximum portability, we recommend you use 6652@code{__func__}, but provide a fallback definition with the 6653preprocessor: 6654 6655@smallexample 6656#if __STDC_VERSION__ < 199901L 6657# if __GNUC__ >= 2 6658# define __func__ __FUNCTION__ 6659# else 6660# define __func__ "<unknown>" 6661# endif 6662#endif 6663@end smallexample 6664 6665In C, @code{__PRETTY_FUNCTION__} is yet another name for 6666@code{__func__}. However, in C++, @code{__PRETTY_FUNCTION__} contains 6667the type signature of the function as well as its bare name. For 6668example, this program: 6669 6670@smallexample 6671extern "C" @{ 6672extern int printf (char *, ...); 6673@} 6674 6675class a @{ 6676 public: 6677 void sub (int i) 6678 @{ 6679 printf ("__FUNCTION__ = %s\n", __FUNCTION__); 6680 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); 6681 @} 6682@}; 6683 6684int 6685main (void) 6686@{ 6687 a ax; 6688 ax.sub (0); 6689 return 0; 6690@} 6691@end smallexample 6692 6693@noindent 6694gives this output: 6695 6696@smallexample 6697__FUNCTION__ = sub 6698__PRETTY_FUNCTION__ = void a::sub(int) 6699@end smallexample 6700 6701These identifiers are not preprocessor macros. In GCC 3.3 and 6702earlier, in C only, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} 6703were treated as string literals; they could be used to initialize 6704@code{char} arrays, and they could be concatenated with other string 6705literals. GCC 3.4 and later treat them as variables, like 6706@code{__func__}. In C++, @code{__FUNCTION__} and 6707@code{__PRETTY_FUNCTION__} have always been variables. 6708 6709@node Return Address 6710@section Getting the Return or Frame Address of a Function 6711 6712These functions may be used to get information about the callers of a 6713function. 6714 6715@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) 6716This function returns the return address of the current function, or of 6717one of its callers. The @var{level} argument is number of frames to 6718scan up the call stack. A value of @code{0} yields the return address 6719of the current function, a value of @code{1} yields the return address 6720of the caller of the current function, and so forth. When inlining 6721the expected behavior is that the function will return the address of 6722the function that will be returned to. To work around this behavior use 6723the @code{noinline} function attribute. 6724 6725The @var{level} argument must be a constant integer. 6726 6727On some machines it may be impossible to determine the return address of 6728any function other than the current one; in such cases, or when the top 6729of the stack has been reached, this function will return @code{0} or a 6730random value. In addition, @code{__builtin_frame_address} may be used 6731to determine if the top of the stack has been reached. 6732 6733Additional post-processing of the returned value may be needed, see 6734@code{__builtin_extract_return_address}. 6735 6736This function should only be used with a nonzero argument for debugging 6737purposes. 6738@end deftypefn 6739 6740@deftypefn {Built-in Function} {void *} __builtin_extract_return_address (void *@var{addr}) 6741The address as returned by @code{__builtin_return_address} may have to be fed 6742through this function to get the actual encoded address. For example, on the 674331-bit S/390 platform the highest bit has to be masked out, or on SPARC 6744platforms an offset has to be added for the true next instruction to be 6745executed. 6746 6747If no fixup is needed, this function simply passes through @var{addr}. 6748@end deftypefn 6749 6750@deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr}) 6751This function does the reverse of @code{__builtin_extract_return_address}. 6752@end deftypefn 6753 6754@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) 6755This function is similar to @code{__builtin_return_address}, but it 6756returns the address of the function frame rather than the return address 6757of the function. Calling @code{__builtin_frame_address} with a value of 6758@code{0} yields the frame address of the current function, a value of 6759@code{1} yields the frame address of the caller of the current function, 6760and so forth. 6761 6762The frame is the area on the stack which holds local variables and saved 6763registers. The frame address is normally the address of the first word 6764pushed on to the stack by the function. However, the exact definition 6765depends upon the processor and the calling convention. If the processor 6766has a dedicated frame pointer register, and the function has a frame, 6767then @code{__builtin_frame_address} will return the value of the frame 6768pointer register. 6769 6770On some machines it may be impossible to determine the frame address of 6771any function other than the current one; in such cases, or when the top 6772of the stack has been reached, this function will return @code{0} if 6773the first frame pointer is properly initialized by the startup code. 6774 6775This function should only be used with a nonzero argument for debugging 6776purposes. 6777@end deftypefn 6778 6779@node Vector Extensions 6780@section Using vector instructions through built-in functions 6781 6782On some targets, the instruction set contains SIMD vector instructions that 6783operate on multiple values contained in one large register at the same time. 6784For example, on the i386 the MMX, 3DNow!@: and SSE extensions can be used 6785this way. 6786 6787The first step in using these extensions is to provide the necessary data 6788types. This should be done using an appropriate @code{typedef}: 6789 6790@smallexample 6791typedef int v4si __attribute__ ((vector_size (16))); 6792@end smallexample 6793 6794The @code{int} type specifies the base type, while the attribute specifies 6795the vector size for the variable, measured in bytes. For example, the 6796declaration above causes the compiler to set the mode for the @code{v4si} 6797type to be 16 bytes wide and divided into @code{int} sized units. For 6798a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the 6799corresponding mode of @code{foo} will be @acronym{V4SI}. 6800 6801The @code{vector_size} attribute is only applicable to integral and 6802float scalars, although arrays, pointers, and function return values 6803are allowed in conjunction with this construct. 6804 6805All the basic integer types can be used as base types, both as signed 6806and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, 6807@code{long long}. In addition, @code{float} and @code{double} can be 6808used to build floating-point vector types. 6809 6810Specifying a combination that is not valid for the current architecture 6811will cause GCC to synthesize the instructions using a narrower mode. 6812For example, if you specify a variable of type @code{V4SI} and your 6813architecture does not allow for this specific SIMD type, GCC will 6814produce code that uses 4 @code{SIs}. 6815 6816The types defined in this manner can be used with a subset of normal C 6817operations. Currently, GCC will allow using the following operators 6818on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. 6819 6820The operations behave like C++ @code{valarrays}. Addition is defined as 6821the addition of the corresponding elements of the operands. For 6822example, in the code below, each of the 4 elements in @var{a} will be 6823added to the corresponding 4 elements in @var{b} and the resulting 6824vector will be stored in @var{c}. 6825 6826@smallexample 6827typedef int v4si __attribute__ ((vector_size (16))); 6828 6829v4si a, b, c; 6830 6831c = a + b; 6832@end smallexample 6833 6834Subtraction, multiplication, division, and the logical operations 6835operate in a similar manner. Likewise, the result of using the unary 6836minus or complement operators on a vector type is a vector whose 6837elements are the negative or complemented values of the corresponding 6838elements in the operand. 6839 6840In C it is possible to use shifting operators @code{<<}, @code{>>} on 6841integer-type vectors. The operation is defined as following: @code{@{a0, 6842a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, 6843@dots{}, an >> bn@}}@. Vector operands must have the same number of 6844elements. 6845 6846For the convenience in C it is allowed to use a binary vector operation 6847where one operand is a scalar. In that case the compiler will transform 6848the scalar operand into a vector where each element is the scalar from 6849the operation. The transformation will happen only if the scalar could be 6850safely converted to the vector-element type. 6851Consider the following code. 6852 6853@smallexample 6854typedef int v4si __attribute__ ((vector_size (16))); 6855 6856v4si a, b, c; 6857long l; 6858 6859a = b + 1; /* a = b + @{1,1,1,1@}; */ 6860a = 2 * b; /* a = @{2,2,2,2@} * b; */ 6861 6862a = l + a; /* Error, cannot convert long to int. */ 6863@end smallexample 6864 6865In C vectors can be subscripted as if the vector were an array with 6866the same number of elements and base type. Out of bound accesses 6867invoke undefined behavior at runtime. Warnings for out of bound 6868accesses for vector subscription can be enabled with 6869@option{-Warray-bounds}. 6870 6871In GNU C vector comparison is supported within standard comparison 6872operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be 6873vector expressions of integer-type or real-type. Comparison between 6874integer-type vectors and real-type vectors are not supported. The 6875result of the comparison is a vector of the same width and number of 6876elements as the comparison operands with a signed integral element 6877type. 6878 6879Vectors are compared element-wise producing 0 when comparison is false 6880and -1 (constant of the appropriate type where all bits are set) 6881otherwise. Consider the following example. 6882 6883@smallexample 6884typedef int v4si __attribute__ ((vector_size (16))); 6885 6886v4si a = @{1,2,3,4@}; 6887v4si b = @{3,2,1,4@}; 6888v4si c; 6889 6890c = a > b; /* The result would be @{0, 0,-1, 0@} */ 6891c = a == b; /* The result would be @{0,-1, 0,-1@} */ 6892@end smallexample 6893 6894Vector shuffling is available using functions 6895@code{__builtin_shuffle (vec, mask)} and 6896@code{__builtin_shuffle (vec0, vec1, mask)}. 6897Both functions construct a permutation of elements from one or two 6898vectors and return a vector of the same type as the input vector(s). 6899The @var{mask} is an integral vector with the same width (@var{W}) 6900and element count (@var{N}) as the output vector. 6901 6902The elements of the input vectors are numbered in memory ordering of 6903@var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The 6904elements of @var{mask} are considered modulo @var{N} in the single-operand 6905case and modulo @math{2*@var{N}} in the two-operand case. 6906 6907Consider the following example, 6908 6909@smallexample 6910typedef int v4si __attribute__ ((vector_size (16))); 6911 6912v4si a = @{1,2,3,4@}; 6913v4si b = @{5,6,7,8@}; 6914v4si mask1 = @{0,1,1,3@}; 6915v4si mask2 = @{0,4,2,5@}; 6916v4si res; 6917 6918res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */ 6919res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */ 6920@end smallexample 6921 6922Note that @code{__builtin_shuffle} is intentionally semantically 6923compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions. 6924 6925You can declare variables and use them in function calls and returns, as 6926well as in assignments and some casts. You can specify a vector type as 6927a return type for a function. Vector types can also be used as function 6928arguments. It is possible to cast from one vector type to another, 6929provided they are of the same size (in fact, you can also cast vectors 6930to and from other datatypes of the same size). 6931 6932You cannot operate between vectors of different lengths or different 6933signedness without a cast. 6934 6935@node Offsetof 6936@section Offsetof 6937@findex __builtin_offsetof 6938 6939GCC implements for both C and C++ a syntactic extension to implement 6940the @code{offsetof} macro. 6941 6942@smallexample 6943primary: 6944 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" 6945 6946offsetof_member_designator: 6947 @code{identifier} 6948 | offsetof_member_designator "." @code{identifier} 6949 | offsetof_member_designator "[" @code{expr} "]" 6950@end smallexample 6951 6952This extension is sufficient such that 6953 6954@smallexample 6955#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) 6956@end smallexample 6957 6958is a suitable definition of the @code{offsetof} macro. In C++, @var{type} 6959may be dependent. In either case, @var{member} may consist of a single 6960identifier, or a sequence of member accesses and array references. 6961 6962@node __sync Builtins 6963@section Legacy __sync built-in functions for atomic memory access 6964 6965The following builtins are intended to be compatible with those described 6966in the @cite{Intel Itanium Processor-specific Application Binary Interface}, 6967section 7.4. As such, they depart from the normal GCC practice of using 6968the ``__builtin_'' prefix, and further that they are overloaded such that 6969they work on multiple types. 6970 6971The definition given in the Intel documentation allows only for the use of 6972the types @code{int}, @code{long}, @code{long long} as well as their unsigned 6973counterparts. GCC will allow any integral scalar or pointer type that is 69741, 2, 4 or 8 bytes in length. 6975 6976Not all operations are supported by all target processors. If a particular 6977operation cannot be implemented on the target processor, a warning will be 6978generated and a call an external function will be generated. The external 6979function will carry the same name as the builtin, with an additional suffix 6980@samp{_@var{n}} where @var{n} is the size of the data type. 6981 6982@c ??? Should we have a mechanism to suppress this warning? This is almost 6983@c useful for implementing the operation under the control of an external 6984@c mutex. 6985 6986In most cases, these builtins are considered a @dfn{full barrier}. That is, 6987no memory operand will be moved across the operation, either forward or 6988backward. Further, instructions will be issued as necessary to prevent the 6989processor from speculating loads across the operation and from queuing stores 6990after the operation. 6991 6992All of the routines are described in the Intel documentation to take 6993``an optional list of variables protected by the memory barrier''. It's 6994not clear what is meant by that; it could mean that @emph{only} the 6995following variables are protected, or it could mean that these variables 6996should in addition be protected. At present GCC ignores this list and 6997protects all variables which are globally accessible. If in the future 6998we make some use of this list, an empty list will continue to mean all 6999globally accessible variables. 7000 7001@table @code 7002@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) 7003@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) 7004@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) 7005@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) 7006@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) 7007@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) 7008@findex __sync_fetch_and_add 7009@findex __sync_fetch_and_sub 7010@findex __sync_fetch_and_or 7011@findex __sync_fetch_and_and 7012@findex __sync_fetch_and_xor 7013@findex __sync_fetch_and_nand 7014These builtins perform the operation suggested by the name, and 7015returns the value that had previously been in memory. That is, 7016 7017@smallexample 7018@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} 7019@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand 7020@end smallexample 7021 7022@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} 7023builtin as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. 7024 7025@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) 7026@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) 7027@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) 7028@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) 7029@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) 7030@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) 7031@findex __sync_add_and_fetch 7032@findex __sync_sub_and_fetch 7033@findex __sync_or_and_fetch 7034@findex __sync_and_and_fetch 7035@findex __sync_xor_and_fetch 7036@findex __sync_nand_and_fetch 7037These builtins perform the operation suggested by the name, and 7038return the new value. That is, 7039 7040@smallexample 7041@{ *ptr @var{op}= value; return *ptr; @} 7042@{ *ptr = ~(*ptr & value); return *ptr; @} // nand 7043@end smallexample 7044 7045@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} 7046builtin as @code{*ptr = ~(*ptr & value)} instead of 7047@code{*ptr = ~*ptr & value}. 7048 7049@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 7050@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 7051@findex __sync_bool_compare_and_swap 7052@findex __sync_val_compare_and_swap 7053These builtins perform an atomic compare and swap. That is, if the current 7054value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into 7055@code{*@var{ptr}}. 7056 7057The ``bool'' version returns true if the comparison is successful and 7058@var{newval} was written. The ``val'' version returns the contents 7059of @code{*@var{ptr}} before the operation. 7060 7061@item __sync_synchronize (...) 7062@findex __sync_synchronize 7063This builtin issues a full memory barrier. 7064 7065@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) 7066@findex __sync_lock_test_and_set 7067This builtin, as described by Intel, is not a traditional test-and-set 7068operation, but rather an atomic exchange operation. It writes @var{value} 7069into @code{*@var{ptr}}, and returns the previous contents of 7070@code{*@var{ptr}}. 7071 7072Many targets have only minimal support for such locks, and do not support 7073a full exchange operation. In this case, a target may support reduced 7074functionality here by which the @emph{only} valid value to store is the 7075immediate constant 1. The exact value actually stored in @code{*@var{ptr}} 7076is implementation defined. 7077 7078This builtin is not a full barrier, but rather an @dfn{acquire barrier}. 7079This means that references after the builtin cannot move to (or be 7080speculated to) before the builtin, but previous memory stores may not 7081be globally visible yet, and previous memory loads may not yet be 7082satisfied. 7083 7084@item void __sync_lock_release (@var{type} *ptr, ...) 7085@findex __sync_lock_release 7086This builtin releases the lock acquired by @code{__sync_lock_test_and_set}. 7087Normally this means writing the constant 0 to @code{*@var{ptr}}. 7088 7089This builtin is not a full barrier, but rather a @dfn{release barrier}. 7090This means that all previous memory stores are globally visible, and all 7091previous memory loads have been satisfied, but following memory reads 7092are not prevented from being speculated to before the barrier. 7093@end table 7094 7095@node __atomic Builtins 7096@section Built-in functions for memory model aware atomic operations 7097 7098The following built-in functions approximately match the requirements for 7099C++11 memory model. Many are similar to the @samp{__sync} prefixed built-in 7100functions, but all also have a memory model parameter. These are all 7101identified by being prefixed with @samp{__atomic}, and most are overloaded 7102such that they work with multiple types. 7103 7104GCC will allow any integral scalar or pointer type that is 1, 2, 4, or 8 7105bytes in length. 16-byte integral types are also allowed if 7106@samp{__int128} (@pxref{__int128}) is supported by the architecture. 7107 7108Target architectures are encouraged to provide their own patterns for 7109each of these built-in functions. If no target is provided, the original 7110non-memory model set of @samp{__sync} atomic built-in functions will be 7111utilized, along with any required synchronization fences surrounding it in 7112order to achieve the proper behaviour. Execution in this case is subject 7113to the same restrictions as those built-in functions. 7114 7115If there is no pattern or mechanism to provide a lock free instruction 7116sequence, a call is made to an external routine with the same parameters 7117to be resolved at runtime. 7118 7119The four non-arithmetic functions (load, store, exchange, and 7120compare_exchange) all have a generic version as well. This generic 7121version will work on any data type. If the data type size maps to one 7122of the integral sizes which may have lock free support, the generic 7123version will utilize the lock free built-in function. Otherwise an 7124external call is left to be resolved at runtime. This external call will 7125be the same format with the addition of a @samp{size_t} parameter inserted 7126as the first parameter indicating the size of the object being pointed to. 7127All objects must be the same size. 7128 7129There are 6 different memory models which can be specified. These map 7130to the same names in the C++11 standard. Refer there or to the 7131@uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki on 7132atomic synchronization} for more detailed definitions. These memory 7133models integrate both barriers to code motion as well as synchronization 7134requirements with other threads. These are listed in approximately 7135ascending order of strength. 7136 7137@table @code 7138@item __ATOMIC_RELAXED 7139No barriers or synchronization. 7140@item __ATOMIC_CONSUME 7141Data dependency only for both barrier and synchronization with another 7142thread. 7143@item __ATOMIC_ACQUIRE 7144Barrier to hoisting of code and synchronizes with release (or stronger) 7145semantic stores from another thread. 7146@item __ATOMIC_RELEASE 7147Barrier to sinking of code and synchronizes with acquire (or stronger) 7148semantic loads from another thread. 7149@item __ATOMIC_ACQ_REL 7150Full barrier in both directions and synchronizes with acquire loads and 7151release stores in another thread. 7152@item __ATOMIC_SEQ_CST 7153Full barrier in both directions and synchronizes with acquire loads and 7154release stores in all threads. 7155@end table 7156 7157When implementing patterns for these built-in functions , the memory model 7158parameter can be ignored as long as the pattern implements the most 7159restrictive @code{__ATOMIC_SEQ_CST} model. Any of the other memory models 7160will execute correctly with this memory model but they may not execute as 7161efficiently as they could with a more appropriate implemention of the 7162relaxed requirements. 7163 7164Note that the C++11 standard allows for the memory model parameter to be 7165determined at runtime rather than at compile time. These built-in 7166functions will map any runtime value to @code{__ATOMIC_SEQ_CST} rather 7167than invoke a runtime library call or inline a switch statement. This is 7168standard compliant, safe, and the simplest approach for now. 7169 7170The memory model parameter is a signed int, but only the lower 8 bits are 7171reserved for the memory model. The remainder of the signed int is reserved 7172for future use and should be 0. Use of the predefined atomic values will 7173ensure proper usage. 7174 7175@deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memmodel) 7176This built-in function implements an atomic load operation. It returns the 7177contents of @code{*@var{ptr}}. 7178 7179The valid memory model variants are 7180@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, 7181and @code{__ATOMIC_CONSUME}. 7182 7183@end deftypefn 7184 7185@deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memmodel) 7186This is the generic version of an atomic load. It will return the 7187contents of @code{*@var{ptr}} in @code{*@var{ret}}. 7188 7189@end deftypefn 7190 7191@deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memmodel) 7192This built-in function implements an atomic store operation. It writes 7193@code{@var{val}} into @code{*@var{ptr}}. 7194 7195The valid memory model variants are 7196@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}. 7197 7198@end deftypefn 7199 7200@deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memmodel) 7201This is the generic version of an atomic store. It will store the value 7202of @code{*@var{val}} into @code{*@var{ptr}}. 7203 7204@end deftypefn 7205 7206@deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memmodel) 7207This built-in function implements an atomic exchange operation. It writes 7208@var{val} into @code{*@var{ptr}}, and returns the previous contents of 7209@code{*@var{ptr}}. 7210 7211The valid memory model variants are 7212@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, 7213@code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}. 7214 7215@end deftypefn 7216 7217@deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memmodel) 7218This is the generic version of an atomic exchange. It will store the 7219contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value 7220of @code{*@var{ptr}} will be copied into @code{*@var{ret}}. 7221 7222@end deftypefn 7223 7224@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) 7225This built-in function implements an atomic compare and exchange operation. 7226This compares the contents of @code{*@var{ptr}} with the contents of 7227@code{*@var{expected}} and if equal, writes @var{desired} into 7228@code{*@var{ptr}}. If they are not equal, the current contents of 7229@code{*@var{ptr}} is written into @code{*@var{expected}}. @var{weak} is true 7230for weak compare_exchange, and false for the strong variation. Many targets 7231only offer the strong variation and ignore the parameter. When in doubt, use 7232the strong variation. 7233 7234True is returned if @var{desired} is written into 7235@code{*@var{ptr}} and the execution is considered to conform to the 7236memory model specified by @var{success_memmodel}. There are no 7237restrictions on what memory model can be used here. 7238 7239False is returned otherwise, and the execution is considered to conform 7240to @var{failure_memmodel}. This memory model cannot be 7241@code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a 7242stronger model than that specified by @var{success_memmodel}. 7243 7244@end deftypefn 7245 7246@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) 7247This built-in function implements the generic version of 7248@code{__atomic_compare_exchange}. The function is virtually identical to 7249@code{__atomic_compare_exchange_n}, except the desired value is also a 7250pointer. 7251 7252@end deftypefn 7253 7254@deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memmodel) 7255@deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memmodel) 7256@deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memmodel) 7257@deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memmodel) 7258@deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memmodel) 7259@deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memmodel) 7260These built-in functions perform the operation suggested by the name, and 7261return the result of the operation. That is, 7262 7263@smallexample 7264@{ *ptr @var{op}= val; return *ptr; @} 7265@end smallexample 7266 7267All memory models are valid. 7268 7269@end deftypefn 7270 7271@deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memmodel) 7272@deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memmodel) 7273@deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memmodel) 7274@deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memmodel) 7275@deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memmodel) 7276@deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memmodel) 7277These built-in functions perform the operation suggested by the name, and 7278return the value that had previously been in @code{*@var{ptr}}. That is, 7279 7280@smallexample 7281@{ tmp = *ptr; *ptr @var{op}= val; return tmp; @} 7282@end smallexample 7283 7284All memory models are valid. 7285 7286@end deftypefn 7287 7288@deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memmodel) 7289 7290This built-in function performs an atomic test-and-set operation on 7291the byte at @code{*@var{ptr}}. The byte is set to some implementation 7292defined non-zero "set" value and the return value is @code{true} if and only 7293if the previous contents were "set". 7294 7295All memory models are valid. 7296 7297@end deftypefn 7298 7299@deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memmodel) 7300 7301This built-in function performs an atomic clear operation on 7302@code{*@var{ptr}}. After the operation, @code{*@var{ptr}} will contain 0. 7303 7304The valid memory model variants are 7305@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and 7306@code{__ATOMIC_RELEASE}. 7307 7308@end deftypefn 7309 7310@deftypefn {Built-in Function} void __atomic_thread_fence (int memmodel) 7311 7312This built-in function acts as a synchronization fence between threads 7313based on the specified memory model. 7314 7315All memory orders are valid. 7316 7317@end deftypefn 7318 7319@deftypefn {Built-in Function} void __atomic_signal_fence (int memmodel) 7320 7321This built-in function acts as a synchronization fence between a thread 7322and signal handlers based in the same thread. 7323 7324All memory orders are valid. 7325 7326@end deftypefn 7327 7328@deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr) 7329 7330This built-in function returns true if objects of @var{size} bytes will always 7331generate lock free atomic instructions for the target architecture. 7332@var{size} must resolve to a compile time constant and the result also resolves to compile time constant. 7333 7334@var{ptr} is an optional pointer to the object which may be used to determine 7335alignment. A value of 0 indicates typical alignment should be used. The 7336compiler may also ignore this parameter. 7337 7338@smallexample 7339if (_atomic_always_lock_free (sizeof (long long), 0)) 7340@end smallexample 7341 7342@end deftypefn 7343 7344@deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr) 7345 7346This built-in function returns true if objects of @var{size} bytes will always 7347generate lock free atomic instructions for the target architecture. If 7348it is not known to be lock free a call is made to a runtime routine named 7349@code{__atomic_is_lock_free}. 7350 7351@var{ptr} is an optional pointer to the object which may be used to determine 7352alignment. A value of 0 indicates typical alignment should be used. The 7353compiler may also ignore this parameter. 7354@end deftypefn 7355 7356@node Object Size Checking 7357@section Object Size Checking Builtins 7358@findex __builtin_object_size 7359@findex __builtin___memcpy_chk 7360@findex __builtin___mempcpy_chk 7361@findex __builtin___memmove_chk 7362@findex __builtin___memset_chk 7363@findex __builtin___strcpy_chk 7364@findex __builtin___stpcpy_chk 7365@findex __builtin___strncpy_chk 7366@findex __builtin___strcat_chk 7367@findex __builtin___strncat_chk 7368@findex __builtin___sprintf_chk 7369@findex __builtin___snprintf_chk 7370@findex __builtin___vsprintf_chk 7371@findex __builtin___vsnprintf_chk 7372@findex __builtin___printf_chk 7373@findex __builtin___vprintf_chk 7374@findex __builtin___fprintf_chk 7375@findex __builtin___vfprintf_chk 7376 7377GCC implements a limited buffer overflow protection mechanism 7378that can prevent some buffer overflow attacks. 7379 7380@deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type}) 7381is a built-in construct that returns a constant number of bytes from 7382@var{ptr} to the end of the object @var{ptr} pointer points to 7383(if known at compile time). @code{__builtin_object_size} never evaluates 7384its arguments for side-effects. If there are any side-effects in them, it 7385returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 7386for @var{type} 2 or 3. If there are multiple objects @var{ptr} can 7387point to and all of them are known at compile time, the returned number 7388is the maximum of remaining byte counts in those objects if @var{type} & 2 is 73890 and minimum if nonzero. If it is not possible to determine which objects 7390@var{ptr} points to at compile time, @code{__builtin_object_size} should 7391return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 7392for @var{type} 2 or 3. 7393 7394@var{type} is an integer constant from 0 to 3. If the least significant 7395bit is clear, objects are whole variables, if it is set, a closest 7396surrounding subobject is considered the object a pointer points to. 7397The second bit determines if maximum or minimum of remaining bytes 7398is computed. 7399 7400@smallexample 7401struct V @{ char buf1[10]; int b; char buf2[10]; @} var; 7402char *p = &var.buf1[1], *q = &var.b; 7403 7404/* Here the object p points to is var. */ 7405assert (__builtin_object_size (p, 0) == sizeof (var) - 1); 7406/* The subobject p points to is var.buf1. */ 7407assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); 7408/* The object q points to is var. */ 7409assert (__builtin_object_size (q, 0) 7410 == (char *) (&var + 1) - (char *) &var.b); 7411/* The subobject q points to is var.b. */ 7412assert (__builtin_object_size (q, 1) == sizeof (var.b)); 7413@end smallexample 7414@end deftypefn 7415 7416There are built-in functions added for many common string operation 7417functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk} 7418built-in is provided. This built-in has an additional last argument, 7419which is the number of bytes remaining in object the @var{dest} 7420argument points to or @code{(size_t) -1} if the size is not known. 7421 7422The built-in functions are optimized into the normal string functions 7423like @code{memcpy} if the last argument is @code{(size_t) -1} or if 7424it is known at compile time that the destination object will not 7425be overflown. If the compiler can determine at compile time the 7426object will be always overflown, it issues a warning. 7427 7428The intended use can be e.g. 7429 7430@smallexample 7431#undef memcpy 7432#define bos0(dest) __builtin_object_size (dest, 0) 7433#define memcpy(dest, src, n) \ 7434 __builtin___memcpy_chk (dest, src, n, bos0 (dest)) 7435 7436char *volatile p; 7437char buf[10]; 7438/* It is unknown what object p points to, so this is optimized 7439 into plain memcpy - no checking is possible. */ 7440memcpy (p, "abcde", n); 7441/* Destination is known and length too. It is known at compile 7442 time there will be no overflow. */ 7443memcpy (&buf[5], "abcde", 5); 7444/* Destination is known, but the length is not known at compile time. 7445 This will result in __memcpy_chk call that can check for overflow 7446 at runtime. */ 7447memcpy (&buf[5], "abcde", n); 7448/* Destination is known and it is known at compile time there will 7449 be overflow. There will be a warning and __memcpy_chk call that 7450 will abort the program at runtime. */ 7451memcpy (&buf[6], "abcde", 5); 7452@end smallexample 7453 7454Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, 7455@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, 7456@code{strcat} and @code{strncat}. 7457 7458There are also checking built-in functions for formatted output functions. 7459@smallexample 7460int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); 7461int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, 7462 const char *fmt, ...); 7463int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, 7464 va_list ap); 7465int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, 7466 const char *fmt, va_list ap); 7467@end smallexample 7468 7469The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} 7470etc.@: functions and can contain implementation specific flags on what 7471additional security measures the checking function might take, such as 7472handling @code{%n} differently. 7473 7474The @var{os} argument is the object size @var{s} points to, like in the 7475other built-in functions. There is a small difference in the behavior 7476though, if @var{os} is @code{(size_t) -1}, the built-in functions are 7477optimized into the non-checking functions only if @var{flag} is 0, otherwise 7478the checking function is called with @var{os} argument set to 7479@code{(size_t) -1}. 7480 7481In addition to this, there are checking built-in functions 7482@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, 7483@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. 7484These have just one additional argument, @var{flag}, right before 7485format string @var{fmt}. If the compiler is able to optimize them to 7486@code{fputc} etc.@: functions, it will, otherwise the checking function 7487should be called and the @var{flag} argument passed to it. 7488 7489@node Other Builtins 7490@section Other built-in functions provided by GCC 7491@cindex built-in functions 7492@findex __builtin_fpclassify 7493@findex __builtin_isfinite 7494@findex __builtin_isnormal 7495@findex __builtin_isgreater 7496@findex __builtin_isgreaterequal 7497@findex __builtin_isinf_sign 7498@findex __builtin_isless 7499@findex __builtin_islessequal 7500@findex __builtin_islessgreater 7501@findex __builtin_isunordered 7502@findex __builtin_powi 7503@findex __builtin_powif 7504@findex __builtin_powil 7505@findex _Exit 7506@findex _exit 7507@findex abort 7508@findex abs 7509@findex acos 7510@findex acosf 7511@findex acosh 7512@findex acoshf 7513@findex acoshl 7514@findex acosl 7515@findex alloca 7516@findex asin 7517@findex asinf 7518@findex asinh 7519@findex asinhf 7520@findex asinhl 7521@findex asinl 7522@findex atan 7523@findex atan2 7524@findex atan2f 7525@findex atan2l 7526@findex atanf 7527@findex atanh 7528@findex atanhf 7529@findex atanhl 7530@findex atanl 7531@findex bcmp 7532@findex bzero 7533@findex cabs 7534@findex cabsf 7535@findex cabsl 7536@findex cacos 7537@findex cacosf 7538@findex cacosh 7539@findex cacoshf 7540@findex cacoshl 7541@findex cacosl 7542@findex calloc 7543@findex carg 7544@findex cargf 7545@findex cargl 7546@findex casin 7547@findex casinf 7548@findex casinh 7549@findex casinhf 7550@findex casinhl 7551@findex casinl 7552@findex catan 7553@findex catanf 7554@findex catanh 7555@findex catanhf 7556@findex catanhl 7557@findex catanl 7558@findex cbrt 7559@findex cbrtf 7560@findex cbrtl 7561@findex ccos 7562@findex ccosf 7563@findex ccosh 7564@findex ccoshf 7565@findex ccoshl 7566@findex ccosl 7567@findex ceil 7568@findex ceilf 7569@findex ceill 7570@findex cexp 7571@findex cexpf 7572@findex cexpl 7573@findex cimag 7574@findex cimagf 7575@findex cimagl 7576@findex clog 7577@findex clogf 7578@findex clogl 7579@findex conj 7580@findex conjf 7581@findex conjl 7582@findex copysign 7583@findex copysignf 7584@findex copysignl 7585@findex cos 7586@findex cosf 7587@findex cosh 7588@findex coshf 7589@findex coshl 7590@findex cosl 7591@findex cpow 7592@findex cpowf 7593@findex cpowl 7594@findex cproj 7595@findex cprojf 7596@findex cprojl 7597@findex creal 7598@findex crealf 7599@findex creall 7600@findex csin 7601@findex csinf 7602@findex csinh 7603@findex csinhf 7604@findex csinhl 7605@findex csinl 7606@findex csqrt 7607@findex csqrtf 7608@findex csqrtl 7609@findex ctan 7610@findex ctanf 7611@findex ctanh 7612@findex ctanhf 7613@findex ctanhl 7614@findex ctanl 7615@findex dcgettext 7616@findex dgettext 7617@findex drem 7618@findex dremf 7619@findex dreml 7620@findex erf 7621@findex erfc 7622@findex erfcf 7623@findex erfcl 7624@findex erff 7625@findex erfl 7626@findex exit 7627@findex exp 7628@findex exp10 7629@findex exp10f 7630@findex exp10l 7631@findex exp2 7632@findex exp2f 7633@findex exp2l 7634@findex expf 7635@findex expl 7636@findex expm1 7637@findex expm1f 7638@findex expm1l 7639@findex fabs 7640@findex fabsf 7641@findex fabsl 7642@findex fdim 7643@findex fdimf 7644@findex fdiml 7645@findex ffs 7646@findex floor 7647@findex floorf 7648@findex floorl 7649@findex fma 7650@findex fmaf 7651@findex fmal 7652@findex fmax 7653@findex fmaxf 7654@findex fmaxl 7655@findex fmin 7656@findex fminf 7657@findex fminl 7658@findex fmod 7659@findex fmodf 7660@findex fmodl 7661@findex fprintf 7662@findex fprintf_unlocked 7663@findex fputs 7664@findex fputs_unlocked 7665@findex frexp 7666@findex frexpf 7667@findex frexpl 7668@findex fscanf 7669@findex gamma 7670@findex gammaf 7671@findex gammal 7672@findex gamma_r 7673@findex gammaf_r 7674@findex gammal_r 7675@findex gettext 7676@findex hypot 7677@findex hypotf 7678@findex hypotl 7679@findex ilogb 7680@findex ilogbf 7681@findex ilogbl 7682@findex imaxabs 7683@findex index 7684@findex isalnum 7685@findex isalpha 7686@findex isascii 7687@findex isblank 7688@findex iscntrl 7689@findex isdigit 7690@findex isgraph 7691@findex islower 7692@findex isprint 7693@findex ispunct 7694@findex isspace 7695@findex isupper 7696@findex iswalnum 7697@findex iswalpha 7698@findex iswblank 7699@findex iswcntrl 7700@findex iswdigit 7701@findex iswgraph 7702@findex iswlower 7703@findex iswprint 7704@findex iswpunct 7705@findex iswspace 7706@findex iswupper 7707@findex iswxdigit 7708@findex isxdigit 7709@findex j0 7710@findex j0f 7711@findex j0l 7712@findex j1 7713@findex j1f 7714@findex j1l 7715@findex jn 7716@findex jnf 7717@findex jnl 7718@findex labs 7719@findex ldexp 7720@findex ldexpf 7721@findex ldexpl 7722@findex lgamma 7723@findex lgammaf 7724@findex lgammal 7725@findex lgamma_r 7726@findex lgammaf_r 7727@findex lgammal_r 7728@findex llabs 7729@findex llrint 7730@findex llrintf 7731@findex llrintl 7732@findex llround 7733@findex llroundf 7734@findex llroundl 7735@findex log 7736@findex log10 7737@findex log10f 7738@findex log10l 7739@findex log1p 7740@findex log1pf 7741@findex log1pl 7742@findex log2 7743@findex log2f 7744@findex log2l 7745@findex logb 7746@findex logbf 7747@findex logbl 7748@findex logf 7749@findex logl 7750@findex lrint 7751@findex lrintf 7752@findex lrintl 7753@findex lround 7754@findex lroundf 7755@findex lroundl 7756@findex malloc 7757@findex memchr 7758@findex memcmp 7759@findex memcpy 7760@findex mempcpy 7761@findex memset 7762@findex modf 7763@findex modff 7764@findex modfl 7765@findex nearbyint 7766@findex nearbyintf 7767@findex nearbyintl 7768@findex nextafter 7769@findex nextafterf 7770@findex nextafterl 7771@findex nexttoward 7772@findex nexttowardf 7773@findex nexttowardl 7774@findex pow 7775@findex pow10 7776@findex pow10f 7777@findex pow10l 7778@findex powf 7779@findex powl 7780@findex printf 7781@findex printf_unlocked 7782@findex putchar 7783@findex puts 7784@findex remainder 7785@findex remainderf 7786@findex remainderl 7787@findex remquo 7788@findex remquof 7789@findex remquol 7790@findex rindex 7791@findex rint 7792@findex rintf 7793@findex rintl 7794@findex round 7795@findex roundf 7796@findex roundl 7797@findex scalb 7798@findex scalbf 7799@findex scalbl 7800@findex scalbln 7801@findex scalblnf 7802@findex scalblnf 7803@findex scalbn 7804@findex scalbnf 7805@findex scanfnl 7806@findex signbit 7807@findex signbitf 7808@findex signbitl 7809@findex signbitd32 7810@findex signbitd64 7811@findex signbitd128 7812@findex significand 7813@findex significandf 7814@findex significandl 7815@findex sin 7816@findex sincos 7817@findex sincosf 7818@findex sincosl 7819@findex sinf 7820@findex sinh 7821@findex sinhf 7822@findex sinhl 7823@findex sinl 7824@findex snprintf 7825@findex sprintf 7826@findex sqrt 7827@findex sqrtf 7828@findex sqrtl 7829@findex sscanf 7830@findex stpcpy 7831@findex stpncpy 7832@findex strcasecmp 7833@findex strcat 7834@findex strchr 7835@findex strcmp 7836@findex strcpy 7837@findex strcspn 7838@findex strdup 7839@findex strfmon 7840@findex strftime 7841@findex strlen 7842@findex strncasecmp 7843@findex strncat 7844@findex strncmp 7845@findex strncpy 7846@findex strndup 7847@findex strpbrk 7848@findex strrchr 7849@findex strspn 7850@findex strstr 7851@findex tan 7852@findex tanf 7853@findex tanh 7854@findex tanhf 7855@findex tanhl 7856@findex tanl 7857@findex tgamma 7858@findex tgammaf 7859@findex tgammal 7860@findex toascii 7861@findex tolower 7862@findex toupper 7863@findex towlower 7864@findex towupper 7865@findex trunc 7866@findex truncf 7867@findex truncl 7868@findex vfprintf 7869@findex vfscanf 7870@findex vprintf 7871@findex vscanf 7872@findex vsnprintf 7873@findex vsprintf 7874@findex vsscanf 7875@findex y0 7876@findex y0f 7877@findex y0l 7878@findex y1 7879@findex y1f 7880@findex y1l 7881@findex yn 7882@findex ynf 7883@findex ynl 7884 7885GCC provides a large number of built-in functions other than the ones 7886mentioned above. Some of these are for internal use in the processing 7887of exceptions or variable-length argument lists and will not be 7888documented here because they may change from time to time; we do not 7889recommend general use of these functions. 7890 7891The remaining functions are provided for optimization purposes. 7892 7893@opindex fno-builtin 7894GCC includes built-in versions of many of the functions in the standard 7895C library. The versions prefixed with @code{__builtin_} will always be 7896treated as having the same meaning as the C library function even if you 7897specify the @option{-fno-builtin} option. (@pxref{C Dialect Options}) 7898Many of these functions are only optimized in certain cases; if they are 7899not optimized in a particular case, a call to the library function will 7900be emitted. 7901 7902@opindex ansi 7903@opindex std 7904Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, 7905@option{-std=c99} or @option{-std=c11}), the functions 7906@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, 7907@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, 7908@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, 7909@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, 7910@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, 7911@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, 7912@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, 7913@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, 7914@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, 7915@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, 7916@code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb}, 7917@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, 7918@code{signbitd64}, @code{signbitd128}, @code{significandf}, 7919@code{significandl}, @code{significand}, @code{sincosf}, 7920@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, 7921@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, 7922@code{strndup}, @code{toascii}, @code{y0f}, @code{y0l}, @code{y0}, 7923@code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and 7924@code{yn} 7925may be handled as built-in functions. 7926All these functions have corresponding versions 7927prefixed with @code{__builtin_}, which may be used even in strict C90 7928mode. 7929 7930The ISO C99 functions 7931@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, 7932@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, 7933@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, 7934@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, 7935@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, 7936@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, 7937@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, 7938@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, 7939@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, 7940@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, 7941@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, 7942@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, 7943@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, 7944@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, 7945@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, 7946@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, 7947@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, 7948@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, 7949@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, 7950@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, 7951@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, 7952@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, 7953@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, 7954@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, 7955@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, 7956@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, 7957@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, 7958@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, 7959@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, 7960@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, 7961@code{nextafterf}, @code{nextafterl}, @code{nextafter}, 7962@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, 7963@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, 7964@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, 7965@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, 7966@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, 7967@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, 7968@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, 7969@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} 7970are handled as built-in functions 7971except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 7972 7973There are also built-in versions of the ISO C99 functions 7974@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, 7975@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, 7976@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, 7977@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, 7978@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, 7979@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, 7980@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, 7981@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, 7982@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} 7983that are recognized in any mode since ISO C90 reserves these names for 7984the purpose to which ISO C99 puts them. All these functions have 7985corresponding versions prefixed with @code{__builtin_}. 7986 7987The ISO C94 functions 7988@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, 7989@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, 7990@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and 7991@code{towupper} 7992are handled as built-in functions 7993except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 7994 7995The ISO C90 functions 7996@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, 7997@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, 7998@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, 7999@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf}, 8000@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, 8001@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, 8002@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, 8003@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, 8004@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, 8005@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, 8006@code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf}, 8007@code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, 8008@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, 8009@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, 8010@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, 8011@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} 8012are all recognized as built-in functions unless 8013@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} 8014is specified for an individual function). All of these functions have 8015corresponding versions prefixed with @code{__builtin_}. 8016 8017GCC provides built-in versions of the ISO C99 floating point comparison 8018macros that avoid raising exceptions for unordered operands. They have 8019the same names as the standard macros ( @code{isgreater}, 8020@code{isgreaterequal}, @code{isless}, @code{islessequal}, 8021@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} 8022prefixed. We intend for a library implementor to be able to simply 8023@code{#define} each standard macro to its built-in equivalent. 8024In the same fashion, GCC provides @code{fpclassify}, @code{isfinite}, 8025@code{isinf_sign} and @code{isnormal} built-ins used with 8026@code{__builtin_} prefixed. The @code{isinf} and @code{isnan} 8027builtins appear both with and without the @code{__builtin_} prefix. 8028 8029@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) 8030 8031You can use the built-in function @code{__builtin_types_compatible_p} to 8032determine whether two types are the same. 8033 8034This built-in function returns 1 if the unqualified versions of the 8035types @var{type1} and @var{type2} (which are types, not expressions) are 8036compatible, 0 otherwise. The result of this built-in function can be 8037used in integer constant expressions. 8038 8039This built-in function ignores top level qualifiers (e.g., @code{const}, 8040@code{volatile}). For example, @code{int} is equivalent to @code{const 8041int}. 8042 8043The type @code{int[]} and @code{int[5]} are compatible. On the other 8044hand, @code{int} and @code{char *} are not compatible, even if the size 8045of their types, on the particular architecture are the same. Also, the 8046amount of pointer indirection is taken into account when determining 8047similarity. Consequently, @code{short *} is not similar to 8048@code{short **}. Furthermore, two types that are typedefed are 8049considered compatible if their underlying types are compatible. 8050 8051An @code{enum} type is not considered to be compatible with another 8052@code{enum} type even if both are compatible with the same integer 8053type; this is what the C standard specifies. 8054For example, @code{enum @{foo, bar@}} is not similar to 8055@code{enum @{hot, dog@}}. 8056 8057You would typically use this function in code whose execution varies 8058depending on the arguments' types. For example: 8059 8060@smallexample 8061#define foo(x) \ 8062 (@{ \ 8063 typeof (x) tmp = (x); \ 8064 if (__builtin_types_compatible_p (typeof (x), long double)) \ 8065 tmp = foo_long_double (tmp); \ 8066 else if (__builtin_types_compatible_p (typeof (x), double)) \ 8067 tmp = foo_double (tmp); \ 8068 else if (__builtin_types_compatible_p (typeof (x), float)) \ 8069 tmp = foo_float (tmp); \ 8070 else \ 8071 abort (); \ 8072 tmp; \ 8073 @}) 8074@end smallexample 8075 8076@emph{Note:} This construct is only available for C@. 8077 8078@end deftypefn 8079 8080@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) 8081 8082You can use the built-in function @code{__builtin_choose_expr} to 8083evaluate code depending on the value of a constant expression. This 8084built-in function returns @var{exp1} if @var{const_exp}, which is an 8085integer constant expression, is nonzero. Otherwise it returns @var{exp2}. 8086 8087This built-in function is analogous to the @samp{? :} operator in C, 8088except that the expression returned has its type unaltered by promotion 8089rules. Also, the built-in function does not evaluate the expression 8090that was not chosen. For example, if @var{const_exp} evaluates to true, 8091@var{exp2} is not evaluated even if it has side-effects. 8092 8093This built-in function can return an lvalue if the chosen argument is an 8094lvalue. 8095 8096If @var{exp1} is returned, the return type is the same as @var{exp1}'s 8097type. Similarly, if @var{exp2} is returned, its return type is the same 8098as @var{exp2}. 8099 8100Example: 8101 8102@smallexample 8103#define foo(x) \ 8104 __builtin_choose_expr ( \ 8105 __builtin_types_compatible_p (typeof (x), double), \ 8106 foo_double (x), \ 8107 __builtin_choose_expr ( \ 8108 __builtin_types_compatible_p (typeof (x), float), \ 8109 foo_float (x), \ 8110 /* @r{The void expression results in a compile-time error} \ 8111 @r{when assigning the result to something.} */ \ 8112 (void)0)) 8113@end smallexample 8114 8115@emph{Note:} This construct is only available for C@. Furthermore, the 8116unused expression (@var{exp1} or @var{exp2} depending on the value of 8117@var{const_exp}) may still generate syntax errors. This may change in 8118future revisions. 8119 8120@end deftypefn 8121 8122@deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag}) 8123 8124The built-in function @code{__builtin_complex} is provided for use in 8125implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and 8126@code{CMPLXL}. @var{real} and @var{imag} must have the same type, a 8127real binary floating-point type, and the result has the corresponding 8128complex type with real and imaginary parts @var{real} and @var{imag}. 8129Unlike @samp{@var{real} + I * @var{imag}}, this works even when 8130infinities, NaNs and negative zeros are involved. 8131 8132@end deftypefn 8133 8134@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) 8135You can use the built-in function @code{__builtin_constant_p} to 8136determine if a value is known to be constant at compile-time and hence 8137that GCC can perform constant-folding on expressions involving that 8138value. The argument of the function is the value to test. The function 8139returns the integer 1 if the argument is known to be a compile-time 8140constant and 0 if it is not known to be a compile-time constant. A 8141return of 0 does not indicate that the value is @emph{not} a constant, 8142but merely that GCC cannot prove it is a constant with the specified 8143value of the @option{-O} option. 8144 8145You would typically use this function in an embedded application where 8146memory was a critical resource. If you have some complex calculation, 8147you may want it to be folded if it involves constants, but need to call 8148a function if it does not. For example: 8149 8150@smallexample 8151#define Scale_Value(X) \ 8152 (__builtin_constant_p (X) \ 8153 ? ((X) * SCALE + OFFSET) : Scale (X)) 8154@end smallexample 8155 8156You may use this built-in function in either a macro or an inline 8157function. However, if you use it in an inlined function and pass an 8158argument of the function as the argument to the built-in, GCC will 8159never return 1 when you call the inline function with a string constant 8160or compound literal (@pxref{Compound Literals}) and will not return 1 8161when you pass a constant numeric value to the inline function unless you 8162specify the @option{-O} option. 8163 8164You may also use @code{__builtin_constant_p} in initializers for static 8165data. For instance, you can write 8166 8167@smallexample 8168static const int table[] = @{ 8169 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, 8170 /* @r{@dots{}} */ 8171@}; 8172@end smallexample 8173 8174@noindent 8175This is an acceptable initializer even if @var{EXPRESSION} is not a 8176constant expression, including the case where 8177@code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be 8178folded to a constant but @var{EXPRESSION} contains operands that would 8179not otherwise be permitted in a static initializer (for example, 8180@code{0 && foo ()}). GCC must be more conservative about evaluating the 8181built-in in this case, because it has no opportunity to perform 8182optimization. 8183 8184Previous versions of GCC did not accept this built-in in data 8185initializers. The earliest version where it is completely safe is 81863.0.1. 8187@end deftypefn 8188 8189@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) 8190@opindex fprofile-arcs 8191You may use @code{__builtin_expect} to provide the compiler with 8192branch prediction information. In general, you should prefer to 8193use actual profile feedback for this (@option{-fprofile-arcs}), as 8194programmers are notoriously bad at predicting how their programs 8195actually perform. However, there are applications in which this 8196data is hard to collect. 8197 8198The return value is the value of @var{exp}, which should be an integral 8199expression. The semantics of the built-in are that it is expected that 8200@var{exp} == @var{c}. For example: 8201 8202@smallexample 8203if (__builtin_expect (x, 0)) 8204 foo (); 8205@end smallexample 8206 8207@noindent 8208would indicate that we do not expect to call @code{foo}, since 8209we expect @code{x} to be zero. Since you are limited to integral 8210expressions for @var{exp}, you should use constructions such as 8211 8212@smallexample 8213if (__builtin_expect (ptr != NULL, 1)) 8214 foo (*ptr); 8215@end smallexample 8216 8217@noindent 8218when testing pointer or floating-point values. 8219@end deftypefn 8220 8221@deftypefn {Built-in Function} void __builtin_trap (void) 8222This function causes the program to exit abnormally. GCC implements 8223this function by using a target-dependent mechanism (such as 8224intentionally executing an illegal instruction) or by calling 8225@code{abort}. The mechanism used may vary from release to release so 8226you should not rely on any particular implementation. 8227@end deftypefn 8228 8229@deftypefn {Built-in Function} void __builtin_unreachable (void) 8230If control flow reaches the point of the @code{__builtin_unreachable}, 8231the program is undefined. It is useful in situations where the 8232compiler cannot deduce the unreachability of the code. 8233 8234One such case is immediately following an @code{asm} statement that 8235will either never terminate, or one that transfers control elsewhere 8236and never returns. In this example, without the 8237@code{__builtin_unreachable}, GCC would issue a warning that control 8238reaches the end of a non-void function. It would also generate code 8239to return after the @code{asm}. 8240 8241@smallexample 8242int f (int c, int v) 8243@{ 8244 if (c) 8245 @{ 8246 return v; 8247 @} 8248 else 8249 @{ 8250 asm("jmp error_handler"); 8251 __builtin_unreachable (); 8252 @} 8253@} 8254@end smallexample 8255 8256Because the @code{asm} statement unconditionally transfers control out 8257of the function, control will never reach the end of the function 8258body. The @code{__builtin_unreachable} is in fact unreachable and 8259communicates this fact to the compiler. 8260 8261Another use for @code{__builtin_unreachable} is following a call a 8262function that never returns but that is not declared 8263@code{__attribute__((noreturn))}, as in this example: 8264 8265@smallexample 8266void function_that_never_returns (void); 8267 8268int g (int c) 8269@{ 8270 if (c) 8271 @{ 8272 return 1; 8273 @} 8274 else 8275 @{ 8276 function_that_never_returns (); 8277 __builtin_unreachable (); 8278 @} 8279@} 8280@end smallexample 8281 8282@end deftypefn 8283 8284@deftypefn {Built-in Function} void *__builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...) 8285This function returns its first argument, and allows the compiler 8286to assume that the returned pointer is at least @var{align} bytes 8287aligned. This built-in can have either two or three arguments, 8288if it has three, the third argument should have integer type, and 8289if it is non-zero means misalignment offset. For example: 8290 8291@smallexample 8292void *x = __builtin_assume_aligned (arg, 16); 8293@end smallexample 8294 8295means that the compiler can assume x, set to arg, is at least 829616 byte aligned, while: 8297 8298@smallexample 8299void *x = __builtin_assume_aligned (arg, 32, 8); 8300@end smallexample 8301 8302means that the compiler can assume for x, set to arg, that 8303(char *) x - 8 is 32 byte aligned. 8304@end deftypefn 8305 8306@deftypefn {Built-in Function} void __builtin___clear_cache (char *@var{begin}, char *@var{end}) 8307This function is used to flush the processor's instruction cache for 8308the region of memory between @var{begin} inclusive and @var{end} 8309exclusive. Some targets require that the instruction cache be 8310flushed, after modifying memory containing code, in order to obtain 8311deterministic behavior. 8312 8313If the target does not require instruction cache flushes, 8314@code{__builtin___clear_cache} has no effect. Otherwise either 8315instructions are emitted in-line to clear the instruction cache or a 8316call to the @code{__clear_cache} function in libgcc is made. 8317@end deftypefn 8318 8319@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) 8320This function is used to minimize cache-miss latency by moving data into 8321a cache before it is accessed. 8322You can insert calls to @code{__builtin_prefetch} into code for which 8323you know addresses of data in memory that is likely to be accessed soon. 8324If the target supports them, data prefetch instructions will be generated. 8325If the prefetch is done early enough before the access then the data will 8326be in the cache by the time it is accessed. 8327 8328The value of @var{addr} is the address of the memory to prefetch. 8329There are two optional arguments, @var{rw} and @var{locality}. 8330The value of @var{rw} is a compile-time constant one or zero; one 8331means that the prefetch is preparing for a write to the memory address 8332and zero, the default, means that the prefetch is preparing for a read. 8333The value @var{locality} must be a compile-time constant integer between 8334zero and three. A value of zero means that the data has no temporal 8335locality, so it need not be left in the cache after the access. A value 8336of three means that the data has a high degree of temporal locality and 8337should be left in all levels of cache possible. Values of one and two 8338mean, respectively, a low or moderate degree of temporal locality. The 8339default is three. 8340 8341@smallexample 8342for (i = 0; i < n; i++) 8343 @{ 8344 a[i] = a[i] + b[i]; 8345 __builtin_prefetch (&a[i+j], 1, 1); 8346 __builtin_prefetch (&b[i+j], 0, 1); 8347 /* @r{@dots{}} */ 8348 @} 8349@end smallexample 8350 8351Data prefetch does not generate faults if @var{addr} is invalid, but 8352the address expression itself must be valid. For example, a prefetch 8353of @code{p->next} will not fault if @code{p->next} is not a valid 8354address, but evaluation will fault if @code{p} is not a valid address. 8355 8356If the target does not support data prefetch, the address expression 8357is evaluated if it includes side effects but no other code is generated 8358and GCC does not issue a warning. 8359@end deftypefn 8360 8361@deftypefn {Built-in Function} double __builtin_huge_val (void) 8362Returns a positive infinity, if supported by the floating-point format, 8363else @code{DBL_MAX}. This function is suitable for implementing the 8364ISO C macro @code{HUGE_VAL}. 8365@end deftypefn 8366 8367@deftypefn {Built-in Function} float __builtin_huge_valf (void) 8368Similar to @code{__builtin_huge_val}, except the return type is @code{float}. 8369@end deftypefn 8370 8371@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) 8372Similar to @code{__builtin_huge_val}, except the return 8373type is @code{long double}. 8374@end deftypefn 8375 8376@deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...) 8377This built-in implements the C99 fpclassify functionality. The first 8378five int arguments should be the target library's notion of the 8379possible FP classes and are used for return values. They must be 8380constant values and they must appear in this order: @code{FP_NAN}, 8381@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and 8382@code{FP_ZERO}. The ellipsis is for exactly one floating point value 8383to classify. GCC treats the last argument as type-generic, which 8384means it does not do default promotion from float to double. 8385@end deftypefn 8386 8387@deftypefn {Built-in Function} double __builtin_inf (void) 8388Similar to @code{__builtin_huge_val}, except a warning is generated 8389if the target floating-point format does not support infinities. 8390@end deftypefn 8391 8392@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) 8393Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. 8394@end deftypefn 8395 8396@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) 8397Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. 8398@end deftypefn 8399 8400@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) 8401Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. 8402@end deftypefn 8403 8404@deftypefn {Built-in Function} float __builtin_inff (void) 8405Similar to @code{__builtin_inf}, except the return type is @code{float}. 8406This function is suitable for implementing the ISO C99 macro @code{INFINITY}. 8407@end deftypefn 8408 8409@deftypefn {Built-in Function} {long double} __builtin_infl (void) 8410Similar to @code{__builtin_inf}, except the return 8411type is @code{long double}. 8412@end deftypefn 8413 8414@deftypefn {Built-in Function} int __builtin_isinf_sign (...) 8415Similar to @code{isinf}, except the return value will be negative for 8416an argument of @code{-Inf}. Note while the parameter list is an 8417ellipsis, this function only accepts exactly one floating point 8418argument. GCC treats this parameter as type-generic, which means it 8419does not do default promotion from float to double. 8420@end deftypefn 8421 8422@deftypefn {Built-in Function} double __builtin_nan (const char *str) 8423This is an implementation of the ISO C99 function @code{nan}. 8424 8425Since ISO C99 defines this function in terms of @code{strtod}, which we 8426do not implement, a description of the parsing is in order. The string 8427is parsed as by @code{strtol}; that is, the base is recognized by 8428leading @samp{0} or @samp{0x} prefixes. The number parsed is placed 8429in the significand such that the least significant bit of the number 8430is at the least significant bit of the significand. The number is 8431truncated to fit the significand field provided. The significand is 8432forced to be a quiet NaN@. 8433 8434This function, if given a string literal all of which would have been 8435consumed by strtol, is evaluated early enough that it is considered a 8436compile-time constant. 8437@end deftypefn 8438 8439@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) 8440Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. 8441@end deftypefn 8442 8443@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) 8444Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. 8445@end deftypefn 8446 8447@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) 8448Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. 8449@end deftypefn 8450 8451@deftypefn {Built-in Function} float __builtin_nanf (const char *str) 8452Similar to @code{__builtin_nan}, except the return type is @code{float}. 8453@end deftypefn 8454 8455@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) 8456Similar to @code{__builtin_nan}, except the return type is @code{long double}. 8457@end deftypefn 8458 8459@deftypefn {Built-in Function} double __builtin_nans (const char *str) 8460Similar to @code{__builtin_nan}, except the significand is forced 8461to be a signaling NaN@. The @code{nans} function is proposed by 8462@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. 8463@end deftypefn 8464 8465@deftypefn {Built-in Function} float __builtin_nansf (const char *str) 8466Similar to @code{__builtin_nans}, except the return type is @code{float}. 8467@end deftypefn 8468 8469@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) 8470Similar to @code{__builtin_nans}, except the return type is @code{long double}. 8471@end deftypefn 8472 8473@deftypefn {Built-in Function} int __builtin_ffs (unsigned int x) 8474Returns one plus the index of the least significant 1-bit of @var{x}, or 8475if @var{x} is zero, returns zero. 8476@end deftypefn 8477 8478@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) 8479Returns the number of leading 0-bits in @var{x}, starting at the most 8480significant bit position. If @var{x} is 0, the result is undefined. 8481@end deftypefn 8482 8483@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) 8484Returns the number of trailing 0-bits in @var{x}, starting at the least 8485significant bit position. If @var{x} is 0, the result is undefined. 8486@end deftypefn 8487 8488@deftypefn {Built-in Function} int __builtin_clrsb (int x) 8489Returns the number of leading redundant sign bits in @var{x}, i.e. the 8490number of bits following the most significant bit which are identical 8491to it. There are no special cases for 0 or other values. 8492@end deftypefn 8493 8494@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) 8495Returns the number of 1-bits in @var{x}. 8496@end deftypefn 8497 8498@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) 8499Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} 8500modulo 2. 8501@end deftypefn 8502 8503@deftypefn {Built-in Function} int __builtin_ffsl (unsigned long) 8504Similar to @code{__builtin_ffs}, except the argument type is 8505@code{unsigned long}. 8506@end deftypefn 8507 8508@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) 8509Similar to @code{__builtin_clz}, except the argument type is 8510@code{unsigned long}. 8511@end deftypefn 8512 8513@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) 8514Similar to @code{__builtin_ctz}, except the argument type is 8515@code{unsigned long}. 8516@end deftypefn 8517 8518@deftypefn {Built-in Function} int __builtin_clrsbl (long) 8519Similar to @code{__builtin_clrsb}, except the argument type is 8520@code{long}. 8521@end deftypefn 8522 8523@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) 8524Similar to @code{__builtin_popcount}, except the argument type is 8525@code{unsigned long}. 8526@end deftypefn 8527 8528@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) 8529Similar to @code{__builtin_parity}, except the argument type is 8530@code{unsigned long}. 8531@end deftypefn 8532 8533@deftypefn {Built-in Function} int __builtin_ffsll (unsigned long long) 8534Similar to @code{__builtin_ffs}, except the argument type is 8535@code{unsigned long long}. 8536@end deftypefn 8537 8538@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) 8539Similar to @code{__builtin_clz}, except the argument type is 8540@code{unsigned long long}. 8541@end deftypefn 8542 8543@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) 8544Similar to @code{__builtin_ctz}, except the argument type is 8545@code{unsigned long long}. 8546@end deftypefn 8547 8548@deftypefn {Built-in Function} int __builtin_clrsbll (long long) 8549Similar to @code{__builtin_clrsb}, except the argument type is 8550@code{long long}. 8551@end deftypefn 8552 8553@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) 8554Similar to @code{__builtin_popcount}, except the argument type is 8555@code{unsigned long long}. 8556@end deftypefn 8557 8558@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) 8559Similar to @code{__builtin_parity}, except the argument type is 8560@code{unsigned long long}. 8561@end deftypefn 8562 8563@deftypefn {Built-in Function} double __builtin_powi (double, int) 8564Returns the first argument raised to the power of the second. Unlike the 8565@code{pow} function no guarantees about precision and rounding are made. 8566@end deftypefn 8567 8568@deftypefn {Built-in Function} float __builtin_powif (float, int) 8569Similar to @code{__builtin_powi}, except the argument and return types 8570are @code{float}. 8571@end deftypefn 8572 8573@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) 8574Similar to @code{__builtin_powi}, except the argument and return types 8575are @code{long double}. 8576@end deftypefn 8577 8578@deftypefn {Built-in Function} int32_t __builtin_bswap32 (int32_t x) 8579Returns @var{x} with the order of the bytes reversed; for example, 8580@code{0xaabbccdd} becomes @code{0xddccbbaa}. Byte here always means 8581exactly 8 bits. 8582@end deftypefn 8583 8584@deftypefn {Built-in Function} int64_t __builtin_bswap64 (int64_t x) 8585Similar to @code{__builtin_bswap32}, except the argument and return types 8586are 64-bit. 8587@end deftypefn 8588 8589@node Target Builtins 8590@section Built-in Functions Specific to Particular Target Machines 8591 8592On some target machines, GCC supports many built-in functions specific 8593to those machines. Generally these generate calls to specific machine 8594instructions, but allow the compiler to schedule those calls. 8595 8596@menu 8597* Alpha Built-in Functions:: 8598* ARM iWMMXt Built-in Functions:: 8599* ARM NEON Intrinsics:: 8600* AVR Built-in Functions:: 8601* Blackfin Built-in Functions:: 8602* FR-V Built-in Functions:: 8603* X86 Built-in Functions:: 8604* MIPS DSP Built-in Functions:: 8605* MIPS Paired-Single Support:: 8606* MIPS Loongson Built-in Functions:: 8607* Other MIPS Built-in Functions:: 8608* picoChip Built-in Functions:: 8609* PowerPC AltiVec/VSX Built-in Functions:: 8610* RX Built-in Functions:: 8611* SPARC VIS Built-in Functions:: 8612* SPU Built-in Functions:: 8613* TI C6X Built-in Functions:: 8614* TILE-Gx Built-in Functions:: 8615* TILEPro Built-in Functions:: 8616@end menu 8617 8618@node Alpha Built-in Functions 8619@subsection Alpha Built-in Functions 8620 8621These built-in functions are available for the Alpha family of 8622processors, depending on the command-line switches used. 8623 8624The following built-in functions are always available. They 8625all generate the machine instruction that is part of the name. 8626 8627@smallexample 8628long __builtin_alpha_implver (void) 8629long __builtin_alpha_rpcc (void) 8630long __builtin_alpha_amask (long) 8631long __builtin_alpha_cmpbge (long, long) 8632long __builtin_alpha_extbl (long, long) 8633long __builtin_alpha_extwl (long, long) 8634long __builtin_alpha_extll (long, long) 8635long __builtin_alpha_extql (long, long) 8636long __builtin_alpha_extwh (long, long) 8637long __builtin_alpha_extlh (long, long) 8638long __builtin_alpha_extqh (long, long) 8639long __builtin_alpha_insbl (long, long) 8640long __builtin_alpha_inswl (long, long) 8641long __builtin_alpha_insll (long, long) 8642long __builtin_alpha_insql (long, long) 8643long __builtin_alpha_inswh (long, long) 8644long __builtin_alpha_inslh (long, long) 8645long __builtin_alpha_insqh (long, long) 8646long __builtin_alpha_mskbl (long, long) 8647long __builtin_alpha_mskwl (long, long) 8648long __builtin_alpha_mskll (long, long) 8649long __builtin_alpha_mskql (long, long) 8650long __builtin_alpha_mskwh (long, long) 8651long __builtin_alpha_msklh (long, long) 8652long __builtin_alpha_mskqh (long, long) 8653long __builtin_alpha_umulh (long, long) 8654long __builtin_alpha_zap (long, long) 8655long __builtin_alpha_zapnot (long, long) 8656@end smallexample 8657 8658The following built-in functions are always with @option{-mmax} 8659or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or 8660later. They all generate the machine instruction that is part 8661of the name. 8662 8663@smallexample 8664long __builtin_alpha_pklb (long) 8665long __builtin_alpha_pkwb (long) 8666long __builtin_alpha_unpkbl (long) 8667long __builtin_alpha_unpkbw (long) 8668long __builtin_alpha_minub8 (long, long) 8669long __builtin_alpha_minsb8 (long, long) 8670long __builtin_alpha_minuw4 (long, long) 8671long __builtin_alpha_minsw4 (long, long) 8672long __builtin_alpha_maxub8 (long, long) 8673long __builtin_alpha_maxsb8 (long, long) 8674long __builtin_alpha_maxuw4 (long, long) 8675long __builtin_alpha_maxsw4 (long, long) 8676long __builtin_alpha_perr (long, long) 8677@end smallexample 8678 8679The following built-in functions are always with @option{-mcix} 8680or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or 8681later. They all generate the machine instruction that is part 8682of the name. 8683 8684@smallexample 8685long __builtin_alpha_cttz (long) 8686long __builtin_alpha_ctlz (long) 8687long __builtin_alpha_ctpop (long) 8688@end smallexample 8689 8690The following builtins are available on systems that use the OSF/1 8691PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} 8692PAL calls, but when invoked with @option{-mtls-kernel}, they invoke 8693@code{rdval} and @code{wrval}. 8694 8695@smallexample 8696void *__builtin_thread_pointer (void) 8697void __builtin_set_thread_pointer (void *) 8698@end smallexample 8699 8700@node ARM iWMMXt Built-in Functions 8701@subsection ARM iWMMXt Built-in Functions 8702 8703These built-in functions are available for the ARM family of 8704processors when the @option{-mcpu=iwmmxt} switch is used: 8705 8706@smallexample 8707typedef int v2si __attribute__ ((vector_size (8))); 8708typedef short v4hi __attribute__ ((vector_size (8))); 8709typedef char v8qi __attribute__ ((vector_size (8))); 8710 8711int __builtin_arm_getwcx (int) 8712void __builtin_arm_setwcx (int, int) 8713int __builtin_arm_textrmsb (v8qi, int) 8714int __builtin_arm_textrmsh (v4hi, int) 8715int __builtin_arm_textrmsw (v2si, int) 8716int __builtin_arm_textrmub (v8qi, int) 8717int __builtin_arm_textrmuh (v4hi, int) 8718int __builtin_arm_textrmuw (v2si, int) 8719v8qi __builtin_arm_tinsrb (v8qi, int) 8720v4hi __builtin_arm_tinsrh (v4hi, int) 8721v2si __builtin_arm_tinsrw (v2si, int) 8722long long __builtin_arm_tmia (long long, int, int) 8723long long __builtin_arm_tmiabb (long long, int, int) 8724long long __builtin_arm_tmiabt (long long, int, int) 8725long long __builtin_arm_tmiaph (long long, int, int) 8726long long __builtin_arm_tmiatb (long long, int, int) 8727long long __builtin_arm_tmiatt (long long, int, int) 8728int __builtin_arm_tmovmskb (v8qi) 8729int __builtin_arm_tmovmskh (v4hi) 8730int __builtin_arm_tmovmskw (v2si) 8731long long __builtin_arm_waccb (v8qi) 8732long long __builtin_arm_wacch (v4hi) 8733long long __builtin_arm_waccw (v2si) 8734v8qi __builtin_arm_waddb (v8qi, v8qi) 8735v8qi __builtin_arm_waddbss (v8qi, v8qi) 8736v8qi __builtin_arm_waddbus (v8qi, v8qi) 8737v4hi __builtin_arm_waddh (v4hi, v4hi) 8738v4hi __builtin_arm_waddhss (v4hi, v4hi) 8739v4hi __builtin_arm_waddhus (v4hi, v4hi) 8740v2si __builtin_arm_waddw (v2si, v2si) 8741v2si __builtin_arm_waddwss (v2si, v2si) 8742v2si __builtin_arm_waddwus (v2si, v2si) 8743v8qi __builtin_arm_walign (v8qi, v8qi, int) 8744long long __builtin_arm_wand(long long, long long) 8745long long __builtin_arm_wandn (long long, long long) 8746v8qi __builtin_arm_wavg2b (v8qi, v8qi) 8747v8qi __builtin_arm_wavg2br (v8qi, v8qi) 8748v4hi __builtin_arm_wavg2h (v4hi, v4hi) 8749v4hi __builtin_arm_wavg2hr (v4hi, v4hi) 8750v8qi __builtin_arm_wcmpeqb (v8qi, v8qi) 8751v4hi __builtin_arm_wcmpeqh (v4hi, v4hi) 8752v2si __builtin_arm_wcmpeqw (v2si, v2si) 8753v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) 8754v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) 8755v2si __builtin_arm_wcmpgtsw (v2si, v2si) 8756v8qi __builtin_arm_wcmpgtub (v8qi, v8qi) 8757v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) 8758v2si __builtin_arm_wcmpgtuw (v2si, v2si) 8759long long __builtin_arm_wmacs (long long, v4hi, v4hi) 8760long long __builtin_arm_wmacsz (v4hi, v4hi) 8761long long __builtin_arm_wmacu (long long, v4hi, v4hi) 8762long long __builtin_arm_wmacuz (v4hi, v4hi) 8763v4hi __builtin_arm_wmadds (v4hi, v4hi) 8764v4hi __builtin_arm_wmaddu (v4hi, v4hi) 8765v8qi __builtin_arm_wmaxsb (v8qi, v8qi) 8766v4hi __builtin_arm_wmaxsh (v4hi, v4hi) 8767v2si __builtin_arm_wmaxsw (v2si, v2si) 8768v8qi __builtin_arm_wmaxub (v8qi, v8qi) 8769v4hi __builtin_arm_wmaxuh (v4hi, v4hi) 8770v2si __builtin_arm_wmaxuw (v2si, v2si) 8771v8qi __builtin_arm_wminsb (v8qi, v8qi) 8772v4hi __builtin_arm_wminsh (v4hi, v4hi) 8773v2si __builtin_arm_wminsw (v2si, v2si) 8774v8qi __builtin_arm_wminub (v8qi, v8qi) 8775v4hi __builtin_arm_wminuh (v4hi, v4hi) 8776v2si __builtin_arm_wminuw (v2si, v2si) 8777v4hi __builtin_arm_wmulsm (v4hi, v4hi) 8778v4hi __builtin_arm_wmulul (v4hi, v4hi) 8779v4hi __builtin_arm_wmulum (v4hi, v4hi) 8780long long __builtin_arm_wor (long long, long long) 8781v2si __builtin_arm_wpackdss (long long, long long) 8782v2si __builtin_arm_wpackdus (long long, long long) 8783v8qi __builtin_arm_wpackhss (v4hi, v4hi) 8784v8qi __builtin_arm_wpackhus (v4hi, v4hi) 8785v4hi __builtin_arm_wpackwss (v2si, v2si) 8786v4hi __builtin_arm_wpackwus (v2si, v2si) 8787long long __builtin_arm_wrord (long long, long long) 8788long long __builtin_arm_wrordi (long long, int) 8789v4hi __builtin_arm_wrorh (v4hi, long long) 8790v4hi __builtin_arm_wrorhi (v4hi, int) 8791v2si __builtin_arm_wrorw (v2si, long long) 8792v2si __builtin_arm_wrorwi (v2si, int) 8793v2si __builtin_arm_wsadb (v8qi, v8qi) 8794v2si __builtin_arm_wsadbz (v8qi, v8qi) 8795v2si __builtin_arm_wsadh (v4hi, v4hi) 8796v2si __builtin_arm_wsadhz (v4hi, v4hi) 8797v4hi __builtin_arm_wshufh (v4hi, int) 8798long long __builtin_arm_wslld (long long, long long) 8799long long __builtin_arm_wslldi (long long, int) 8800v4hi __builtin_arm_wsllh (v4hi, long long) 8801v4hi __builtin_arm_wsllhi (v4hi, int) 8802v2si __builtin_arm_wsllw (v2si, long long) 8803v2si __builtin_arm_wsllwi (v2si, int) 8804long long __builtin_arm_wsrad (long long, long long) 8805long long __builtin_arm_wsradi (long long, int) 8806v4hi __builtin_arm_wsrah (v4hi, long long) 8807v4hi __builtin_arm_wsrahi (v4hi, int) 8808v2si __builtin_arm_wsraw (v2si, long long) 8809v2si __builtin_arm_wsrawi (v2si, int) 8810long long __builtin_arm_wsrld (long long, long long) 8811long long __builtin_arm_wsrldi (long long, int) 8812v4hi __builtin_arm_wsrlh (v4hi, long long) 8813v4hi __builtin_arm_wsrlhi (v4hi, int) 8814v2si __builtin_arm_wsrlw (v2si, long long) 8815v2si __builtin_arm_wsrlwi (v2si, int) 8816v8qi __builtin_arm_wsubb (v8qi, v8qi) 8817v8qi __builtin_arm_wsubbss (v8qi, v8qi) 8818v8qi __builtin_arm_wsubbus (v8qi, v8qi) 8819v4hi __builtin_arm_wsubh (v4hi, v4hi) 8820v4hi __builtin_arm_wsubhss (v4hi, v4hi) 8821v4hi __builtin_arm_wsubhus (v4hi, v4hi) 8822v2si __builtin_arm_wsubw (v2si, v2si) 8823v2si __builtin_arm_wsubwss (v2si, v2si) 8824v2si __builtin_arm_wsubwus (v2si, v2si) 8825v4hi __builtin_arm_wunpckehsb (v8qi) 8826v2si __builtin_arm_wunpckehsh (v4hi) 8827long long __builtin_arm_wunpckehsw (v2si) 8828v4hi __builtin_arm_wunpckehub (v8qi) 8829v2si __builtin_arm_wunpckehuh (v4hi) 8830long long __builtin_arm_wunpckehuw (v2si) 8831v4hi __builtin_arm_wunpckelsb (v8qi) 8832v2si __builtin_arm_wunpckelsh (v4hi) 8833long long __builtin_arm_wunpckelsw (v2si) 8834v4hi __builtin_arm_wunpckelub (v8qi) 8835v2si __builtin_arm_wunpckeluh (v4hi) 8836long long __builtin_arm_wunpckeluw (v2si) 8837v8qi __builtin_arm_wunpckihb (v8qi, v8qi) 8838v4hi __builtin_arm_wunpckihh (v4hi, v4hi) 8839v2si __builtin_arm_wunpckihw (v2si, v2si) 8840v8qi __builtin_arm_wunpckilb (v8qi, v8qi) 8841v4hi __builtin_arm_wunpckilh (v4hi, v4hi) 8842v2si __builtin_arm_wunpckilw (v2si, v2si) 8843long long __builtin_arm_wxor (long long, long long) 8844long long __builtin_arm_wzero () 8845@end smallexample 8846 8847@node ARM NEON Intrinsics 8848@subsection ARM NEON Intrinsics 8849 8850These built-in intrinsics for the ARM Advanced SIMD extension are available 8851when the @option{-mfpu=neon} switch is used: 8852 8853@include arm-neon-intrinsics.texi 8854 8855@node AVR Built-in Functions 8856@subsection AVR Built-in Functions 8857 8858For each built-in function for AVR, there is an equally named, 8859uppercase built-in macro defined. That way users can easily query if 8860or if not a specific built-in is implemented or not. For example, if 8861@code{__builtin_avr_nop} is available the macro 8862@code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise. 8863 8864The following built-in functions map to the respective machine 8865instruction, i.e. @code{nop}, @code{sei}, @code{cli}, @code{sleep}, 8866@code{wdr}, @code{swap}, @code{fmul}, @code{fmuls} 8867resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented 8868as library call if no hardware multiplier is available. 8869 8870@smallexample 8871void __builtin_avr_nop (void) 8872void __builtin_avr_sei (void) 8873void __builtin_avr_cli (void) 8874void __builtin_avr_sleep (void) 8875void __builtin_avr_wdr (void) 8876unsigned char __builtin_avr_swap (unsigned char) 8877unsigned int __builtin_avr_fmul (unsigned char, unsigned char) 8878int __builtin_avr_fmuls (char, char) 8879int __builtin_avr_fmulsu (char, unsigned char) 8880@end smallexample 8881 8882In order to delay execution for a specific number of cycles, GCC 8883implements 8884@smallexample 8885void __builtin_avr_delay_cycles (unsigned long ticks) 8886@end smallexample 8887 8888@noindent 8889@code{ticks} is the number of ticks to delay execution. Note that this 8890built-in does not take into account the effect of interrupts which 8891might increase delay time. @code{ticks} must be a compile time 8892integer constant; delays with a variable number of cycles are not supported. 8893 8894@smallexample 8895char __builtin_avr_flash_segment (const __memx void*) 8896@end smallexample 8897 8898@noindent 8899This built-in takes a byte address to the 24-bit 8900@ref{AVR Named Address Spaces,address space} @code{__memx} and returns 8901the number of the flash segment (the 64 KiB chunk) where the address 8902points to. Counting starts at @code{0}. 8903If the address does not point to flash memory, return @code{-1}. 8904 8905@smallexample 8906unsigned char __builtin_avr_insert_bits (unsigned long map, unsigned char bits, unsigned char val) 8907@end smallexample 8908 8909@noindent 8910Insert bits from @var{bits} into @var{val} and return the resulting 8911value. The nibbles of @var{map} determine how the insertion is 8912performed: Let @var{X} be the @var{n}-th nibble of @var{map} 8913@enumerate 8914@item If @var{X} is @code{0xf}, 8915then the @var{n}-th bit of @var{val} is returned unaltered. 8916 8917@item If X is in the range 0@dots{}7, 8918then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits} 8919 8920@item If X is in the range 8@dots{}@code{0xe}, 8921then the @var{n}-th result bit is undefined. 8922@end enumerate 8923 8924@noindent 8925One typical use case for this built-in is adjusting input and 8926output values to non-contiguous port layouts. Some examples: 8927 8928@smallexample 8929// same as val, bits is unused 8930__builtin_avr_insert_bits (0xffffffff, bits, val) 8931@end smallexample 8932 8933@smallexample 8934// same as bits, val is unused 8935__builtin_avr_insert_bits (0x76543210, bits, val) 8936@end smallexample 8937 8938@smallexample 8939// same as rotating bits by 4 8940__builtin_avr_insert_bits (0x32107654, bits, 0) 8941@end smallexample 8942 8943@smallexample 8944// high-nibble of result is the high-nibble of val 8945// low-nibble of result is the low-nibble of bits 8946__builtin_avr_insert_bits (0xffff3210, bits, val) 8947@end smallexample 8948 8949@smallexample 8950// reverse the bit order of bits 8951__builtin_avr_insert_bits (0x01234567, bits, 0) 8952@end smallexample 8953 8954@node Blackfin Built-in Functions 8955@subsection Blackfin Built-in Functions 8956 8957Currently, there are two Blackfin-specific built-in functions. These are 8958used for generating @code{CSYNC} and @code{SSYNC} machine insns without 8959using inline assembly; by using these built-in functions the compiler can 8960automatically add workarounds for hardware errata involving these 8961instructions. These functions are named as follows: 8962 8963@smallexample 8964void __builtin_bfin_csync (void) 8965void __builtin_bfin_ssync (void) 8966@end smallexample 8967 8968@node FR-V Built-in Functions 8969@subsection FR-V Built-in Functions 8970 8971GCC provides many FR-V-specific built-in functions. In general, 8972these functions are intended to be compatible with those described 8973by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu 8974Semiconductor}. The two exceptions are @code{__MDUNPACKH} and 8975@code{__MBTOHE}, the gcc forms of which pass 128-bit values by 8976pointer rather than by value. 8977 8978Most of the functions are named after specific FR-V instructions. 8979Such functions are said to be ``directly mapped'' and are summarized 8980here in tabular form. 8981 8982@menu 8983* Argument Types:: 8984* Directly-mapped Integer Functions:: 8985* Directly-mapped Media Functions:: 8986* Raw read/write Functions:: 8987* Other Built-in Functions:: 8988@end menu 8989 8990@node Argument Types 8991@subsubsection Argument Types 8992 8993The arguments to the built-in functions can be divided into three groups: 8994register numbers, compile-time constants and run-time values. In order 8995to make this classification clear at a glance, the arguments and return 8996values are given the following pseudo types: 8997 8998@multitable @columnfractions .20 .30 .15 .35 8999@item Pseudo type @tab Real C type @tab Constant? @tab Description 9000@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword 9001@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word 9002@item @code{sw1} @tab @code{int} @tab No @tab a signed word 9003@item @code{uw2} @tab @code{unsigned long long} @tab No 9004@tab an unsigned doubleword 9005@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword 9006@item @code{const} @tab @code{int} @tab Yes @tab an integer constant 9007@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number 9008@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number 9009@end multitable 9010 9011These pseudo types are not defined by GCC, they are simply a notational 9012convenience used in this manual. 9013 9014Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} 9015and @code{sw2} are evaluated at run time. They correspond to 9016register operands in the underlying FR-V instructions. 9017 9018@code{const} arguments represent immediate operands in the underlying 9019FR-V instructions. They must be compile-time constants. 9020 9021@code{acc} arguments are evaluated at compile time and specify the number 9022of an accumulator register. For example, an @code{acc} argument of 2 9023will select the ACC2 register. 9024 9025@code{iacc} arguments are similar to @code{acc} arguments but specify the 9026number of an IACC register. See @pxref{Other Built-in Functions} 9027for more details. 9028 9029@node Directly-mapped Integer Functions 9030@subsubsection Directly-mapped Integer Functions 9031 9032The functions listed below map directly to FR-V I-type instructions. 9033 9034@multitable @columnfractions .45 .32 .23 9035@item Function prototype @tab Example usage @tab Assembly output 9036@item @code{sw1 __ADDSS (sw1, sw1)} 9037@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} 9038@tab @code{ADDSS @var{a},@var{b},@var{c}} 9039@item @code{sw1 __SCAN (sw1, sw1)} 9040@tab @code{@var{c} = __SCAN (@var{a}, @var{b})} 9041@tab @code{SCAN @var{a},@var{b},@var{c}} 9042@item @code{sw1 __SCUTSS (sw1)} 9043@tab @code{@var{b} = __SCUTSS (@var{a})} 9044@tab @code{SCUTSS @var{a},@var{b}} 9045@item @code{sw1 __SLASS (sw1, sw1)} 9046@tab @code{@var{c} = __SLASS (@var{a}, @var{b})} 9047@tab @code{SLASS @var{a},@var{b},@var{c}} 9048@item @code{void __SMASS (sw1, sw1)} 9049@tab @code{__SMASS (@var{a}, @var{b})} 9050@tab @code{SMASS @var{a},@var{b}} 9051@item @code{void __SMSSS (sw1, sw1)} 9052@tab @code{__SMSSS (@var{a}, @var{b})} 9053@tab @code{SMSSS @var{a},@var{b}} 9054@item @code{void __SMU (sw1, sw1)} 9055@tab @code{__SMU (@var{a}, @var{b})} 9056@tab @code{SMU @var{a},@var{b}} 9057@item @code{sw2 __SMUL (sw1, sw1)} 9058@tab @code{@var{c} = __SMUL (@var{a}, @var{b})} 9059@tab @code{SMUL @var{a},@var{b},@var{c}} 9060@item @code{sw1 __SUBSS (sw1, sw1)} 9061@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} 9062@tab @code{SUBSS @var{a},@var{b},@var{c}} 9063@item @code{uw2 __UMUL (uw1, uw1)} 9064@tab @code{@var{c} = __UMUL (@var{a}, @var{b})} 9065@tab @code{UMUL @var{a},@var{b},@var{c}} 9066@end multitable 9067 9068@node Directly-mapped Media Functions 9069@subsubsection Directly-mapped Media Functions 9070 9071The functions listed below map directly to FR-V M-type instructions. 9072 9073@multitable @columnfractions .45 .32 .23 9074@item Function prototype @tab Example usage @tab Assembly output 9075@item @code{uw1 __MABSHS (sw1)} 9076@tab @code{@var{b} = __MABSHS (@var{a})} 9077@tab @code{MABSHS @var{a},@var{b}} 9078@item @code{void __MADDACCS (acc, acc)} 9079@tab @code{__MADDACCS (@var{b}, @var{a})} 9080@tab @code{MADDACCS @var{a},@var{b}} 9081@item @code{sw1 __MADDHSS (sw1, sw1)} 9082@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} 9083@tab @code{MADDHSS @var{a},@var{b},@var{c}} 9084@item @code{uw1 __MADDHUS (uw1, uw1)} 9085@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} 9086@tab @code{MADDHUS @var{a},@var{b},@var{c}} 9087@item @code{uw1 __MAND (uw1, uw1)} 9088@tab @code{@var{c} = __MAND (@var{a}, @var{b})} 9089@tab @code{MAND @var{a},@var{b},@var{c}} 9090@item @code{void __MASACCS (acc, acc)} 9091@tab @code{__MASACCS (@var{b}, @var{a})} 9092@tab @code{MASACCS @var{a},@var{b}} 9093@item @code{uw1 __MAVEH (uw1, uw1)} 9094@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} 9095@tab @code{MAVEH @var{a},@var{b},@var{c}} 9096@item @code{uw2 __MBTOH (uw1)} 9097@tab @code{@var{b} = __MBTOH (@var{a})} 9098@tab @code{MBTOH @var{a},@var{b}} 9099@item @code{void __MBTOHE (uw1 *, uw1)} 9100@tab @code{__MBTOHE (&@var{b}, @var{a})} 9101@tab @code{MBTOHE @var{a},@var{b}} 9102@item @code{void __MCLRACC (acc)} 9103@tab @code{__MCLRACC (@var{a})} 9104@tab @code{MCLRACC @var{a}} 9105@item @code{void __MCLRACCA (void)} 9106@tab @code{__MCLRACCA ()} 9107@tab @code{MCLRACCA} 9108@item @code{uw1 __Mcop1 (uw1, uw1)} 9109@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} 9110@tab @code{Mcop1 @var{a},@var{b},@var{c}} 9111@item @code{uw1 __Mcop2 (uw1, uw1)} 9112@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} 9113@tab @code{Mcop2 @var{a},@var{b},@var{c}} 9114@item @code{uw1 __MCPLHI (uw2, const)} 9115@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} 9116@tab @code{MCPLHI @var{a},#@var{b},@var{c}} 9117@item @code{uw1 __MCPLI (uw2, const)} 9118@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} 9119@tab @code{MCPLI @var{a},#@var{b},@var{c}} 9120@item @code{void __MCPXIS (acc, sw1, sw1)} 9121@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} 9122@tab @code{MCPXIS @var{a},@var{b},@var{c}} 9123@item @code{void __MCPXIU (acc, uw1, uw1)} 9124@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} 9125@tab @code{MCPXIU @var{a},@var{b},@var{c}} 9126@item @code{void __MCPXRS (acc, sw1, sw1)} 9127@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} 9128@tab @code{MCPXRS @var{a},@var{b},@var{c}} 9129@item @code{void __MCPXRU (acc, uw1, uw1)} 9130@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} 9131@tab @code{MCPXRU @var{a},@var{b},@var{c}} 9132@item @code{uw1 __MCUT (acc, uw1)} 9133@tab @code{@var{c} = __MCUT (@var{a}, @var{b})} 9134@tab @code{MCUT @var{a},@var{b},@var{c}} 9135@item @code{uw1 __MCUTSS (acc, sw1)} 9136@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} 9137@tab @code{MCUTSS @var{a},@var{b},@var{c}} 9138@item @code{void __MDADDACCS (acc, acc)} 9139@tab @code{__MDADDACCS (@var{b}, @var{a})} 9140@tab @code{MDADDACCS @var{a},@var{b}} 9141@item @code{void __MDASACCS (acc, acc)} 9142@tab @code{__MDASACCS (@var{b}, @var{a})} 9143@tab @code{MDASACCS @var{a},@var{b}} 9144@item @code{uw2 __MDCUTSSI (acc, const)} 9145@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} 9146@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} 9147@item @code{uw2 __MDPACKH (uw2, uw2)} 9148@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} 9149@tab @code{MDPACKH @var{a},@var{b},@var{c}} 9150@item @code{uw2 __MDROTLI (uw2, const)} 9151@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} 9152@tab @code{MDROTLI @var{a},#@var{b},@var{c}} 9153@item @code{void __MDSUBACCS (acc, acc)} 9154@tab @code{__MDSUBACCS (@var{b}, @var{a})} 9155@tab @code{MDSUBACCS @var{a},@var{b}} 9156@item @code{void __MDUNPACKH (uw1 *, uw2)} 9157@tab @code{__MDUNPACKH (&@var{b}, @var{a})} 9158@tab @code{MDUNPACKH @var{a},@var{b}} 9159@item @code{uw2 __MEXPDHD (uw1, const)} 9160@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} 9161@tab @code{MEXPDHD @var{a},#@var{b},@var{c}} 9162@item @code{uw1 __MEXPDHW (uw1, const)} 9163@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} 9164@tab @code{MEXPDHW @var{a},#@var{b},@var{c}} 9165@item @code{uw1 __MHDSETH (uw1, const)} 9166@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} 9167@tab @code{MHDSETH @var{a},#@var{b},@var{c}} 9168@item @code{sw1 __MHDSETS (const)} 9169@tab @code{@var{b} = __MHDSETS (@var{a})} 9170@tab @code{MHDSETS #@var{a},@var{b}} 9171@item @code{uw1 __MHSETHIH (uw1, const)} 9172@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} 9173@tab @code{MHSETHIH #@var{a},@var{b}} 9174@item @code{sw1 __MHSETHIS (sw1, const)} 9175@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} 9176@tab @code{MHSETHIS #@var{a},@var{b}} 9177@item @code{uw1 __MHSETLOH (uw1, const)} 9178@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} 9179@tab @code{MHSETLOH #@var{a},@var{b}} 9180@item @code{sw1 __MHSETLOS (sw1, const)} 9181@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} 9182@tab @code{MHSETLOS #@var{a},@var{b}} 9183@item @code{uw1 __MHTOB (uw2)} 9184@tab @code{@var{b} = __MHTOB (@var{a})} 9185@tab @code{MHTOB @var{a},@var{b}} 9186@item @code{void __MMACHS (acc, sw1, sw1)} 9187@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} 9188@tab @code{MMACHS @var{a},@var{b},@var{c}} 9189@item @code{void __MMACHU (acc, uw1, uw1)} 9190@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} 9191@tab @code{MMACHU @var{a},@var{b},@var{c}} 9192@item @code{void __MMRDHS (acc, sw1, sw1)} 9193@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} 9194@tab @code{MMRDHS @var{a},@var{b},@var{c}} 9195@item @code{void __MMRDHU (acc, uw1, uw1)} 9196@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} 9197@tab @code{MMRDHU @var{a},@var{b},@var{c}} 9198@item @code{void __MMULHS (acc, sw1, sw1)} 9199@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} 9200@tab @code{MMULHS @var{a},@var{b},@var{c}} 9201@item @code{void __MMULHU (acc, uw1, uw1)} 9202@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} 9203@tab @code{MMULHU @var{a},@var{b},@var{c}} 9204@item @code{void __MMULXHS (acc, sw1, sw1)} 9205@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} 9206@tab @code{MMULXHS @var{a},@var{b},@var{c}} 9207@item @code{void __MMULXHU (acc, uw1, uw1)} 9208@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} 9209@tab @code{MMULXHU @var{a},@var{b},@var{c}} 9210@item @code{uw1 __MNOT (uw1)} 9211@tab @code{@var{b} = __MNOT (@var{a})} 9212@tab @code{MNOT @var{a},@var{b}} 9213@item @code{uw1 __MOR (uw1, uw1)} 9214@tab @code{@var{c} = __MOR (@var{a}, @var{b})} 9215@tab @code{MOR @var{a},@var{b},@var{c}} 9216@item @code{uw1 __MPACKH (uh, uh)} 9217@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} 9218@tab @code{MPACKH @var{a},@var{b},@var{c}} 9219@item @code{sw2 __MQADDHSS (sw2, sw2)} 9220@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} 9221@tab @code{MQADDHSS @var{a},@var{b},@var{c}} 9222@item @code{uw2 __MQADDHUS (uw2, uw2)} 9223@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} 9224@tab @code{MQADDHUS @var{a},@var{b},@var{c}} 9225@item @code{void __MQCPXIS (acc, sw2, sw2)} 9226@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} 9227@tab @code{MQCPXIS @var{a},@var{b},@var{c}} 9228@item @code{void __MQCPXIU (acc, uw2, uw2)} 9229@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} 9230@tab @code{MQCPXIU @var{a},@var{b},@var{c}} 9231@item @code{void __MQCPXRS (acc, sw2, sw2)} 9232@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} 9233@tab @code{MQCPXRS @var{a},@var{b},@var{c}} 9234@item @code{void __MQCPXRU (acc, uw2, uw2)} 9235@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} 9236@tab @code{MQCPXRU @var{a},@var{b},@var{c}} 9237@item @code{sw2 __MQLCLRHS (sw2, sw2)} 9238@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} 9239@tab @code{MQLCLRHS @var{a},@var{b},@var{c}} 9240@item @code{sw2 __MQLMTHS (sw2, sw2)} 9241@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} 9242@tab @code{MQLMTHS @var{a},@var{b},@var{c}} 9243@item @code{void __MQMACHS (acc, sw2, sw2)} 9244@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} 9245@tab @code{MQMACHS @var{a},@var{b},@var{c}} 9246@item @code{void __MQMACHU (acc, uw2, uw2)} 9247@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} 9248@tab @code{MQMACHU @var{a},@var{b},@var{c}} 9249@item @code{void __MQMACXHS (acc, sw2, sw2)} 9250@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} 9251@tab @code{MQMACXHS @var{a},@var{b},@var{c}} 9252@item @code{void __MQMULHS (acc, sw2, sw2)} 9253@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} 9254@tab @code{MQMULHS @var{a},@var{b},@var{c}} 9255@item @code{void __MQMULHU (acc, uw2, uw2)} 9256@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} 9257@tab @code{MQMULHU @var{a},@var{b},@var{c}} 9258@item @code{void __MQMULXHS (acc, sw2, sw2)} 9259@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} 9260@tab @code{MQMULXHS @var{a},@var{b},@var{c}} 9261@item @code{void __MQMULXHU (acc, uw2, uw2)} 9262@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} 9263@tab @code{MQMULXHU @var{a},@var{b},@var{c}} 9264@item @code{sw2 __MQSATHS (sw2, sw2)} 9265@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} 9266@tab @code{MQSATHS @var{a},@var{b},@var{c}} 9267@item @code{uw2 __MQSLLHI (uw2, int)} 9268@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} 9269@tab @code{MQSLLHI @var{a},@var{b},@var{c}} 9270@item @code{sw2 __MQSRAHI (sw2, int)} 9271@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} 9272@tab @code{MQSRAHI @var{a},@var{b},@var{c}} 9273@item @code{sw2 __MQSUBHSS (sw2, sw2)} 9274@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} 9275@tab @code{MQSUBHSS @var{a},@var{b},@var{c}} 9276@item @code{uw2 __MQSUBHUS (uw2, uw2)} 9277@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} 9278@tab @code{MQSUBHUS @var{a},@var{b},@var{c}} 9279@item @code{void __MQXMACHS (acc, sw2, sw2)} 9280@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} 9281@tab @code{MQXMACHS @var{a},@var{b},@var{c}} 9282@item @code{void __MQXMACXHS (acc, sw2, sw2)} 9283@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} 9284@tab @code{MQXMACXHS @var{a},@var{b},@var{c}} 9285@item @code{uw1 __MRDACC (acc)} 9286@tab @code{@var{b} = __MRDACC (@var{a})} 9287@tab @code{MRDACC @var{a},@var{b}} 9288@item @code{uw1 __MRDACCG (acc)} 9289@tab @code{@var{b} = __MRDACCG (@var{a})} 9290@tab @code{MRDACCG @var{a},@var{b}} 9291@item @code{uw1 __MROTLI (uw1, const)} 9292@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} 9293@tab @code{MROTLI @var{a},#@var{b},@var{c}} 9294@item @code{uw1 __MROTRI (uw1, const)} 9295@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} 9296@tab @code{MROTRI @var{a},#@var{b},@var{c}} 9297@item @code{sw1 __MSATHS (sw1, sw1)} 9298@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} 9299@tab @code{MSATHS @var{a},@var{b},@var{c}} 9300@item @code{uw1 __MSATHU (uw1, uw1)} 9301@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} 9302@tab @code{MSATHU @var{a},@var{b},@var{c}} 9303@item @code{uw1 __MSLLHI (uw1, const)} 9304@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} 9305@tab @code{MSLLHI @var{a},#@var{b},@var{c}} 9306@item @code{sw1 __MSRAHI (sw1, const)} 9307@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} 9308@tab @code{MSRAHI @var{a},#@var{b},@var{c}} 9309@item @code{uw1 __MSRLHI (uw1, const)} 9310@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} 9311@tab @code{MSRLHI @var{a},#@var{b},@var{c}} 9312@item @code{void __MSUBACCS (acc, acc)} 9313@tab @code{__MSUBACCS (@var{b}, @var{a})} 9314@tab @code{MSUBACCS @var{a},@var{b}} 9315@item @code{sw1 __MSUBHSS (sw1, sw1)} 9316@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} 9317@tab @code{MSUBHSS @var{a},@var{b},@var{c}} 9318@item @code{uw1 __MSUBHUS (uw1, uw1)} 9319@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} 9320@tab @code{MSUBHUS @var{a},@var{b},@var{c}} 9321@item @code{void __MTRAP (void)} 9322@tab @code{__MTRAP ()} 9323@tab @code{MTRAP} 9324@item @code{uw2 __MUNPACKH (uw1)} 9325@tab @code{@var{b} = __MUNPACKH (@var{a})} 9326@tab @code{MUNPACKH @var{a},@var{b}} 9327@item @code{uw1 __MWCUT (uw2, uw1)} 9328@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} 9329@tab @code{MWCUT @var{a},@var{b},@var{c}} 9330@item @code{void __MWTACC (acc, uw1)} 9331@tab @code{__MWTACC (@var{b}, @var{a})} 9332@tab @code{MWTACC @var{a},@var{b}} 9333@item @code{void __MWTACCG (acc, uw1)} 9334@tab @code{__MWTACCG (@var{b}, @var{a})} 9335@tab @code{MWTACCG @var{a},@var{b}} 9336@item @code{uw1 __MXOR (uw1, uw1)} 9337@tab @code{@var{c} = __MXOR (@var{a}, @var{b})} 9338@tab @code{MXOR @var{a},@var{b},@var{c}} 9339@end multitable 9340 9341@node Raw read/write Functions 9342@subsubsection Raw read/write Functions 9343 9344This sections describes built-in functions related to read and write 9345instructions to access memory. These functions generate 9346@code{membar} instructions to flush the I/O load and stores where 9347appropriate, as described in Fujitsu's manual described above. 9348 9349@table @code 9350 9351@item unsigned char __builtin_read8 (void *@var{data}) 9352@item unsigned short __builtin_read16 (void *@var{data}) 9353@item unsigned long __builtin_read32 (void *@var{data}) 9354@item unsigned long long __builtin_read64 (void *@var{data}) 9355 9356@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) 9357@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) 9358@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) 9359@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) 9360@end table 9361 9362@node Other Built-in Functions 9363@subsubsection Other Built-in Functions 9364 9365This section describes built-in functions that are not named after 9366a specific FR-V instruction. 9367 9368@table @code 9369@item sw2 __IACCreadll (iacc @var{reg}) 9370Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved 9371for future expansion and must be 0. 9372 9373@item sw1 __IACCreadl (iacc @var{reg}) 9374Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. 9375Other values of @var{reg} are rejected as invalid. 9376 9377@item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) 9378Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument 9379is reserved for future expansion and must be 0. 9380 9381@item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) 9382Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} 9383is 1. Other values of @var{reg} are rejected as invalid. 9384 9385@item void __data_prefetch0 (const void *@var{x}) 9386Use the @code{dcpl} instruction to load the contents of address @var{x} 9387into the data cache. 9388 9389@item void __data_prefetch (const void *@var{x}) 9390Use the @code{nldub} instruction to load the contents of address @var{x} 9391into the data cache. The instruction will be issued in slot I1@. 9392@end table 9393 9394@node X86 Built-in Functions 9395@subsection X86 Built-in Functions 9396 9397These built-in functions are available for the i386 and x86-64 family 9398of computers, depending on the command-line switches used. 9399 9400Note that, if you specify command-line switches such as @option{-msse}, 9401the compiler could use the extended instruction sets even if the built-ins 9402are not used explicitly in the program. For this reason, applications 9403which perform runtime CPU detection must compile separate files for each 9404supported architecture, using the appropriate flags. In particular, 9405the file containing the CPU detection code should be compiled without 9406these options. 9407 9408The following machine modes are available for use with MMX built-in functions 9409(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, 9410@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a 9411vector of eight 8-bit integers. Some of the built-in functions operate on 9412MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode. 9413 9414If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector 9415of two 32-bit floating point values. 9416 9417If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit 9418floating point values. Some instructions use a vector of four 32-bit 9419integers, these use @code{V4SI}. Finally, some instructions operate on an 9420entire vector register, interpreting it as a 128-bit integer, these use mode 9421@code{TI}. 9422 9423In 64-bit mode, the x86-64 family of processors uses additional built-in 9424functions for efficient use of @code{TF} (@code{__float128}) 128-bit 9425floating point and @code{TC} 128-bit complex floating point values. 9426 9427The following floating point built-in functions are available in 64-bit 9428mode. All of them implement the function that is part of the name. 9429 9430@smallexample 9431__float128 __builtin_fabsq (__float128) 9432__float128 __builtin_copysignq (__float128, __float128) 9433@end smallexample 9434 9435The following built-in function is always available. 9436 9437@table @code 9438@item void __builtin_ia32_pause (void) 9439Generates the @code{pause} machine instruction with a compiler memory 9440barrier. 9441@end table 9442 9443The following floating point built-in functions are made available in the 944464-bit mode. 9445 9446@table @code 9447@item __float128 __builtin_infq (void) 9448Similar to @code{__builtin_inf}, except the return type is @code{__float128}. 9449@findex __builtin_infq 9450 9451@item __float128 __builtin_huge_valq (void) 9452Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}. 9453@findex __builtin_huge_valq 9454@end table 9455 9456The following built-in functions are made available by @option{-mmmx}. 9457All of them generate the machine instruction that is part of the name. 9458 9459@smallexample 9460v8qi __builtin_ia32_paddb (v8qi, v8qi) 9461v4hi __builtin_ia32_paddw (v4hi, v4hi) 9462v2si __builtin_ia32_paddd (v2si, v2si) 9463v8qi __builtin_ia32_psubb (v8qi, v8qi) 9464v4hi __builtin_ia32_psubw (v4hi, v4hi) 9465v2si __builtin_ia32_psubd (v2si, v2si) 9466v8qi __builtin_ia32_paddsb (v8qi, v8qi) 9467v4hi __builtin_ia32_paddsw (v4hi, v4hi) 9468v8qi __builtin_ia32_psubsb (v8qi, v8qi) 9469v4hi __builtin_ia32_psubsw (v4hi, v4hi) 9470v8qi __builtin_ia32_paddusb (v8qi, v8qi) 9471v4hi __builtin_ia32_paddusw (v4hi, v4hi) 9472v8qi __builtin_ia32_psubusb (v8qi, v8qi) 9473v4hi __builtin_ia32_psubusw (v4hi, v4hi) 9474v4hi __builtin_ia32_pmullw (v4hi, v4hi) 9475v4hi __builtin_ia32_pmulhw (v4hi, v4hi) 9476di __builtin_ia32_pand (di, di) 9477di __builtin_ia32_pandn (di,di) 9478di __builtin_ia32_por (di, di) 9479di __builtin_ia32_pxor (di, di) 9480v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) 9481v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) 9482v2si __builtin_ia32_pcmpeqd (v2si, v2si) 9483v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) 9484v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) 9485v2si __builtin_ia32_pcmpgtd (v2si, v2si) 9486v8qi __builtin_ia32_punpckhbw (v8qi, v8qi) 9487v4hi __builtin_ia32_punpckhwd (v4hi, v4hi) 9488v2si __builtin_ia32_punpckhdq (v2si, v2si) 9489v8qi __builtin_ia32_punpcklbw (v8qi, v8qi) 9490v4hi __builtin_ia32_punpcklwd (v4hi, v4hi) 9491v2si __builtin_ia32_punpckldq (v2si, v2si) 9492v8qi __builtin_ia32_packsswb (v4hi, v4hi) 9493v4hi __builtin_ia32_packssdw (v2si, v2si) 9494v8qi __builtin_ia32_packuswb (v4hi, v4hi) 9495 9496v4hi __builtin_ia32_psllw (v4hi, v4hi) 9497v2si __builtin_ia32_pslld (v2si, v2si) 9498v1di __builtin_ia32_psllq (v1di, v1di) 9499v4hi __builtin_ia32_psrlw (v4hi, v4hi) 9500v2si __builtin_ia32_psrld (v2si, v2si) 9501v1di __builtin_ia32_psrlq (v1di, v1di) 9502v4hi __builtin_ia32_psraw (v4hi, v4hi) 9503v2si __builtin_ia32_psrad (v2si, v2si) 9504v4hi __builtin_ia32_psllwi (v4hi, int) 9505v2si __builtin_ia32_pslldi (v2si, int) 9506v1di __builtin_ia32_psllqi (v1di, int) 9507v4hi __builtin_ia32_psrlwi (v4hi, int) 9508v2si __builtin_ia32_psrldi (v2si, int) 9509v1di __builtin_ia32_psrlqi (v1di, int) 9510v4hi __builtin_ia32_psrawi (v4hi, int) 9511v2si __builtin_ia32_psradi (v2si, int) 9512 9513@end smallexample 9514 9515The following built-in functions are made available either with 9516@option{-msse}, or with a combination of @option{-m3dnow} and 9517@option{-march=athlon}. All of them generate the machine 9518instruction that is part of the name. 9519 9520@smallexample 9521v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) 9522v8qi __builtin_ia32_pavgb (v8qi, v8qi) 9523v4hi __builtin_ia32_pavgw (v4hi, v4hi) 9524v1di __builtin_ia32_psadbw (v8qi, v8qi) 9525v8qi __builtin_ia32_pmaxub (v8qi, v8qi) 9526v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) 9527v8qi __builtin_ia32_pminub (v8qi, v8qi) 9528v4hi __builtin_ia32_pminsw (v4hi, v4hi) 9529int __builtin_ia32_pextrw (v4hi, int) 9530v4hi __builtin_ia32_pinsrw (v4hi, int, int) 9531int __builtin_ia32_pmovmskb (v8qi) 9532void __builtin_ia32_maskmovq (v8qi, v8qi, char *) 9533void __builtin_ia32_movntq (di *, di) 9534void __builtin_ia32_sfence (void) 9535@end smallexample 9536 9537The following built-in functions are available when @option{-msse} is used. 9538All of them generate the machine instruction that is part of the name. 9539 9540@smallexample 9541int __builtin_ia32_comieq (v4sf, v4sf) 9542int __builtin_ia32_comineq (v4sf, v4sf) 9543int __builtin_ia32_comilt (v4sf, v4sf) 9544int __builtin_ia32_comile (v4sf, v4sf) 9545int __builtin_ia32_comigt (v4sf, v4sf) 9546int __builtin_ia32_comige (v4sf, v4sf) 9547int __builtin_ia32_ucomieq (v4sf, v4sf) 9548int __builtin_ia32_ucomineq (v4sf, v4sf) 9549int __builtin_ia32_ucomilt (v4sf, v4sf) 9550int __builtin_ia32_ucomile (v4sf, v4sf) 9551int __builtin_ia32_ucomigt (v4sf, v4sf) 9552int __builtin_ia32_ucomige (v4sf, v4sf) 9553v4sf __builtin_ia32_addps (v4sf, v4sf) 9554v4sf __builtin_ia32_subps (v4sf, v4sf) 9555v4sf __builtin_ia32_mulps (v4sf, v4sf) 9556v4sf __builtin_ia32_divps (v4sf, v4sf) 9557v4sf __builtin_ia32_addss (v4sf, v4sf) 9558v4sf __builtin_ia32_subss (v4sf, v4sf) 9559v4sf __builtin_ia32_mulss (v4sf, v4sf) 9560v4sf __builtin_ia32_divss (v4sf, v4sf) 9561v4si __builtin_ia32_cmpeqps (v4sf, v4sf) 9562v4si __builtin_ia32_cmpltps (v4sf, v4sf) 9563v4si __builtin_ia32_cmpleps (v4sf, v4sf) 9564v4si __builtin_ia32_cmpgtps (v4sf, v4sf) 9565v4si __builtin_ia32_cmpgeps (v4sf, v4sf) 9566v4si __builtin_ia32_cmpunordps (v4sf, v4sf) 9567v4si __builtin_ia32_cmpneqps (v4sf, v4sf) 9568v4si __builtin_ia32_cmpnltps (v4sf, v4sf) 9569v4si __builtin_ia32_cmpnleps (v4sf, v4sf) 9570v4si __builtin_ia32_cmpngtps (v4sf, v4sf) 9571v4si __builtin_ia32_cmpngeps (v4sf, v4sf) 9572v4si __builtin_ia32_cmpordps (v4sf, v4sf) 9573v4si __builtin_ia32_cmpeqss (v4sf, v4sf) 9574v4si __builtin_ia32_cmpltss (v4sf, v4sf) 9575v4si __builtin_ia32_cmpless (v4sf, v4sf) 9576v4si __builtin_ia32_cmpunordss (v4sf, v4sf) 9577v4si __builtin_ia32_cmpneqss (v4sf, v4sf) 9578v4si __builtin_ia32_cmpnlts (v4sf, v4sf) 9579v4si __builtin_ia32_cmpnless (v4sf, v4sf) 9580v4si __builtin_ia32_cmpordss (v4sf, v4sf) 9581v4sf __builtin_ia32_maxps (v4sf, v4sf) 9582v4sf __builtin_ia32_maxss (v4sf, v4sf) 9583v4sf __builtin_ia32_minps (v4sf, v4sf) 9584v4sf __builtin_ia32_minss (v4sf, v4sf) 9585v4sf __builtin_ia32_andps (v4sf, v4sf) 9586v4sf __builtin_ia32_andnps (v4sf, v4sf) 9587v4sf __builtin_ia32_orps (v4sf, v4sf) 9588v4sf __builtin_ia32_xorps (v4sf, v4sf) 9589v4sf __builtin_ia32_movss (v4sf, v4sf) 9590v4sf __builtin_ia32_movhlps (v4sf, v4sf) 9591v4sf __builtin_ia32_movlhps (v4sf, v4sf) 9592v4sf __builtin_ia32_unpckhps (v4sf, v4sf) 9593v4sf __builtin_ia32_unpcklps (v4sf, v4sf) 9594v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) 9595v4sf __builtin_ia32_cvtsi2ss (v4sf, int) 9596v2si __builtin_ia32_cvtps2pi (v4sf) 9597int __builtin_ia32_cvtss2si (v4sf) 9598v2si __builtin_ia32_cvttps2pi (v4sf) 9599int __builtin_ia32_cvttss2si (v4sf) 9600v4sf __builtin_ia32_rcpps (v4sf) 9601v4sf __builtin_ia32_rsqrtps (v4sf) 9602v4sf __builtin_ia32_sqrtps (v4sf) 9603v4sf __builtin_ia32_rcpss (v4sf) 9604v4sf __builtin_ia32_rsqrtss (v4sf) 9605v4sf __builtin_ia32_sqrtss (v4sf) 9606v4sf __builtin_ia32_shufps (v4sf, v4sf, int) 9607void __builtin_ia32_movntps (float *, v4sf) 9608int __builtin_ia32_movmskps (v4sf) 9609@end smallexample 9610 9611The following built-in functions are available when @option{-msse} is used. 9612 9613@table @code 9614@item v4sf __builtin_ia32_loadaps (float *) 9615Generates the @code{movaps} machine instruction as a load from memory. 9616@item void __builtin_ia32_storeaps (float *, v4sf) 9617Generates the @code{movaps} machine instruction as a store to memory. 9618@item v4sf __builtin_ia32_loadups (float *) 9619Generates the @code{movups} machine instruction as a load from memory. 9620@item void __builtin_ia32_storeups (float *, v4sf) 9621Generates the @code{movups} machine instruction as a store to memory. 9622@item v4sf __builtin_ia32_loadsss (float *) 9623Generates the @code{movss} machine instruction as a load from memory. 9624@item void __builtin_ia32_storess (float *, v4sf) 9625Generates the @code{movss} machine instruction as a store to memory. 9626@item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *) 9627Generates the @code{movhps} machine instruction as a load from memory. 9628@item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *) 9629Generates the @code{movlps} machine instruction as a load from memory 9630@item void __builtin_ia32_storehps (v2sf *, v4sf) 9631Generates the @code{movhps} machine instruction as a store to memory. 9632@item void __builtin_ia32_storelps (v2sf *, v4sf) 9633Generates the @code{movlps} machine instruction as a store to memory. 9634@end table 9635 9636The following built-in functions are available when @option{-msse2} is used. 9637All of them generate the machine instruction that is part of the name. 9638 9639@smallexample 9640int __builtin_ia32_comisdeq (v2df, v2df) 9641int __builtin_ia32_comisdlt (v2df, v2df) 9642int __builtin_ia32_comisdle (v2df, v2df) 9643int __builtin_ia32_comisdgt (v2df, v2df) 9644int __builtin_ia32_comisdge (v2df, v2df) 9645int __builtin_ia32_comisdneq (v2df, v2df) 9646int __builtin_ia32_ucomisdeq (v2df, v2df) 9647int __builtin_ia32_ucomisdlt (v2df, v2df) 9648int __builtin_ia32_ucomisdle (v2df, v2df) 9649int __builtin_ia32_ucomisdgt (v2df, v2df) 9650int __builtin_ia32_ucomisdge (v2df, v2df) 9651int __builtin_ia32_ucomisdneq (v2df, v2df) 9652v2df __builtin_ia32_cmpeqpd (v2df, v2df) 9653v2df __builtin_ia32_cmpltpd (v2df, v2df) 9654v2df __builtin_ia32_cmplepd (v2df, v2df) 9655v2df __builtin_ia32_cmpgtpd (v2df, v2df) 9656v2df __builtin_ia32_cmpgepd (v2df, v2df) 9657v2df __builtin_ia32_cmpunordpd (v2df, v2df) 9658v2df __builtin_ia32_cmpneqpd (v2df, v2df) 9659v2df __builtin_ia32_cmpnltpd (v2df, v2df) 9660v2df __builtin_ia32_cmpnlepd (v2df, v2df) 9661v2df __builtin_ia32_cmpngtpd (v2df, v2df) 9662v2df __builtin_ia32_cmpngepd (v2df, v2df) 9663v2df __builtin_ia32_cmpordpd (v2df, v2df) 9664v2df __builtin_ia32_cmpeqsd (v2df, v2df) 9665v2df __builtin_ia32_cmpltsd (v2df, v2df) 9666v2df __builtin_ia32_cmplesd (v2df, v2df) 9667v2df __builtin_ia32_cmpunordsd (v2df, v2df) 9668v2df __builtin_ia32_cmpneqsd (v2df, v2df) 9669v2df __builtin_ia32_cmpnltsd (v2df, v2df) 9670v2df __builtin_ia32_cmpnlesd (v2df, v2df) 9671v2df __builtin_ia32_cmpordsd (v2df, v2df) 9672v2di __builtin_ia32_paddq (v2di, v2di) 9673v2di __builtin_ia32_psubq (v2di, v2di) 9674v2df __builtin_ia32_addpd (v2df, v2df) 9675v2df __builtin_ia32_subpd (v2df, v2df) 9676v2df __builtin_ia32_mulpd (v2df, v2df) 9677v2df __builtin_ia32_divpd (v2df, v2df) 9678v2df __builtin_ia32_addsd (v2df, v2df) 9679v2df __builtin_ia32_subsd (v2df, v2df) 9680v2df __builtin_ia32_mulsd (v2df, v2df) 9681v2df __builtin_ia32_divsd (v2df, v2df) 9682v2df __builtin_ia32_minpd (v2df, v2df) 9683v2df __builtin_ia32_maxpd (v2df, v2df) 9684v2df __builtin_ia32_minsd (v2df, v2df) 9685v2df __builtin_ia32_maxsd (v2df, v2df) 9686v2df __builtin_ia32_andpd (v2df, v2df) 9687v2df __builtin_ia32_andnpd (v2df, v2df) 9688v2df __builtin_ia32_orpd (v2df, v2df) 9689v2df __builtin_ia32_xorpd (v2df, v2df) 9690v2df __builtin_ia32_movsd (v2df, v2df) 9691v2df __builtin_ia32_unpckhpd (v2df, v2df) 9692v2df __builtin_ia32_unpcklpd (v2df, v2df) 9693v16qi __builtin_ia32_paddb128 (v16qi, v16qi) 9694v8hi __builtin_ia32_paddw128 (v8hi, v8hi) 9695v4si __builtin_ia32_paddd128 (v4si, v4si) 9696v2di __builtin_ia32_paddq128 (v2di, v2di) 9697v16qi __builtin_ia32_psubb128 (v16qi, v16qi) 9698v8hi __builtin_ia32_psubw128 (v8hi, v8hi) 9699v4si __builtin_ia32_psubd128 (v4si, v4si) 9700v2di __builtin_ia32_psubq128 (v2di, v2di) 9701v8hi __builtin_ia32_pmullw128 (v8hi, v8hi) 9702v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi) 9703v2di __builtin_ia32_pand128 (v2di, v2di) 9704v2di __builtin_ia32_pandn128 (v2di, v2di) 9705v2di __builtin_ia32_por128 (v2di, v2di) 9706v2di __builtin_ia32_pxor128 (v2di, v2di) 9707v16qi __builtin_ia32_pavgb128 (v16qi, v16qi) 9708v8hi __builtin_ia32_pavgw128 (v8hi, v8hi) 9709v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi) 9710v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi) 9711v4si __builtin_ia32_pcmpeqd128 (v4si, v4si) 9712v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi) 9713v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi) 9714v4si __builtin_ia32_pcmpgtd128 (v4si, v4si) 9715v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi) 9716v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi) 9717v16qi __builtin_ia32_pminub128 (v16qi, v16qi) 9718v8hi __builtin_ia32_pminsw128 (v8hi, v8hi) 9719v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi) 9720v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi) 9721v4si __builtin_ia32_punpckhdq128 (v4si, v4si) 9722v2di __builtin_ia32_punpckhqdq128 (v2di, v2di) 9723v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi) 9724v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi) 9725v4si __builtin_ia32_punpckldq128 (v4si, v4si) 9726v2di __builtin_ia32_punpcklqdq128 (v2di, v2di) 9727v16qi __builtin_ia32_packsswb128 (v8hi, v8hi) 9728v8hi __builtin_ia32_packssdw128 (v4si, v4si) 9729v16qi __builtin_ia32_packuswb128 (v8hi, v8hi) 9730v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi) 9731void __builtin_ia32_maskmovdqu (v16qi, v16qi) 9732v2df __builtin_ia32_loadupd (double *) 9733void __builtin_ia32_storeupd (double *, v2df) 9734v2df __builtin_ia32_loadhpd (v2df, double const *) 9735v2df __builtin_ia32_loadlpd (v2df, double const *) 9736int __builtin_ia32_movmskpd (v2df) 9737int __builtin_ia32_pmovmskb128 (v16qi) 9738void __builtin_ia32_movnti (int *, int) 9739void __builtin_ia32_movnti64 (long long int *, long long int) 9740void __builtin_ia32_movntpd (double *, v2df) 9741void __builtin_ia32_movntdq (v2df *, v2df) 9742v4si __builtin_ia32_pshufd (v4si, int) 9743v8hi __builtin_ia32_pshuflw (v8hi, int) 9744v8hi __builtin_ia32_pshufhw (v8hi, int) 9745v2di __builtin_ia32_psadbw128 (v16qi, v16qi) 9746v2df __builtin_ia32_sqrtpd (v2df) 9747v2df __builtin_ia32_sqrtsd (v2df) 9748v2df __builtin_ia32_shufpd (v2df, v2df, int) 9749v2df __builtin_ia32_cvtdq2pd (v4si) 9750v4sf __builtin_ia32_cvtdq2ps (v4si) 9751v4si __builtin_ia32_cvtpd2dq (v2df) 9752v2si __builtin_ia32_cvtpd2pi (v2df) 9753v4sf __builtin_ia32_cvtpd2ps (v2df) 9754v4si __builtin_ia32_cvttpd2dq (v2df) 9755v2si __builtin_ia32_cvttpd2pi (v2df) 9756v2df __builtin_ia32_cvtpi2pd (v2si) 9757int __builtin_ia32_cvtsd2si (v2df) 9758int __builtin_ia32_cvttsd2si (v2df) 9759long long __builtin_ia32_cvtsd2si64 (v2df) 9760long long __builtin_ia32_cvttsd2si64 (v2df) 9761v4si __builtin_ia32_cvtps2dq (v4sf) 9762v2df __builtin_ia32_cvtps2pd (v4sf) 9763v4si __builtin_ia32_cvttps2dq (v4sf) 9764v2df __builtin_ia32_cvtsi2sd (v2df, int) 9765v2df __builtin_ia32_cvtsi642sd (v2df, long long) 9766v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df) 9767v2df __builtin_ia32_cvtss2sd (v2df, v4sf) 9768void __builtin_ia32_clflush (const void *) 9769void __builtin_ia32_lfence (void) 9770void __builtin_ia32_mfence (void) 9771v16qi __builtin_ia32_loaddqu (const char *) 9772void __builtin_ia32_storedqu (char *, v16qi) 9773v1di __builtin_ia32_pmuludq (v2si, v2si) 9774v2di __builtin_ia32_pmuludq128 (v4si, v4si) 9775v8hi __builtin_ia32_psllw128 (v8hi, v8hi) 9776v4si __builtin_ia32_pslld128 (v4si, v4si) 9777v2di __builtin_ia32_psllq128 (v2di, v2di) 9778v8hi __builtin_ia32_psrlw128 (v8hi, v8hi) 9779v4si __builtin_ia32_psrld128 (v4si, v4si) 9780v2di __builtin_ia32_psrlq128 (v2di, v2di) 9781v8hi __builtin_ia32_psraw128 (v8hi, v8hi) 9782v4si __builtin_ia32_psrad128 (v4si, v4si) 9783v2di __builtin_ia32_pslldqi128 (v2di, int) 9784v8hi __builtin_ia32_psllwi128 (v8hi, int) 9785v4si __builtin_ia32_pslldi128 (v4si, int) 9786v2di __builtin_ia32_psllqi128 (v2di, int) 9787v2di __builtin_ia32_psrldqi128 (v2di, int) 9788v8hi __builtin_ia32_psrlwi128 (v8hi, int) 9789v4si __builtin_ia32_psrldi128 (v4si, int) 9790v2di __builtin_ia32_psrlqi128 (v2di, int) 9791v8hi __builtin_ia32_psrawi128 (v8hi, int) 9792v4si __builtin_ia32_psradi128 (v4si, int) 9793v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi) 9794v2di __builtin_ia32_movq128 (v2di) 9795@end smallexample 9796 9797The following built-in functions are available when @option{-msse3} is used. 9798All of them generate the machine instruction that is part of the name. 9799 9800@smallexample 9801v2df __builtin_ia32_addsubpd (v2df, v2df) 9802v4sf __builtin_ia32_addsubps (v4sf, v4sf) 9803v2df __builtin_ia32_haddpd (v2df, v2df) 9804v4sf __builtin_ia32_haddps (v4sf, v4sf) 9805v2df __builtin_ia32_hsubpd (v2df, v2df) 9806v4sf __builtin_ia32_hsubps (v4sf, v4sf) 9807v16qi __builtin_ia32_lddqu (char const *) 9808void __builtin_ia32_monitor (void *, unsigned int, unsigned int) 9809v2df __builtin_ia32_movddup (v2df) 9810v4sf __builtin_ia32_movshdup (v4sf) 9811v4sf __builtin_ia32_movsldup (v4sf) 9812void __builtin_ia32_mwait (unsigned int, unsigned int) 9813@end smallexample 9814 9815The following built-in functions are available when @option{-msse3} is used. 9816 9817@table @code 9818@item v2df __builtin_ia32_loadddup (double const *) 9819Generates the @code{movddup} machine instruction as a load from memory. 9820@end table 9821 9822The following built-in functions are available when @option{-mssse3} is used. 9823All of them generate the machine instruction that is part of the name 9824with MMX registers. 9825 9826@smallexample 9827v2si __builtin_ia32_phaddd (v2si, v2si) 9828v4hi __builtin_ia32_phaddw (v4hi, v4hi) 9829v4hi __builtin_ia32_phaddsw (v4hi, v4hi) 9830v2si __builtin_ia32_phsubd (v2si, v2si) 9831v4hi __builtin_ia32_phsubw (v4hi, v4hi) 9832v4hi __builtin_ia32_phsubsw (v4hi, v4hi) 9833v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi) 9834v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi) 9835v8qi __builtin_ia32_pshufb (v8qi, v8qi) 9836v8qi __builtin_ia32_psignb (v8qi, v8qi) 9837v2si __builtin_ia32_psignd (v2si, v2si) 9838v4hi __builtin_ia32_psignw (v4hi, v4hi) 9839v1di __builtin_ia32_palignr (v1di, v1di, int) 9840v8qi __builtin_ia32_pabsb (v8qi) 9841v2si __builtin_ia32_pabsd (v2si) 9842v4hi __builtin_ia32_pabsw (v4hi) 9843@end smallexample 9844 9845The following built-in functions are available when @option{-mssse3} is used. 9846All of them generate the machine instruction that is part of the name 9847with SSE registers. 9848 9849@smallexample 9850v4si __builtin_ia32_phaddd128 (v4si, v4si) 9851v8hi __builtin_ia32_phaddw128 (v8hi, v8hi) 9852v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi) 9853v4si __builtin_ia32_phsubd128 (v4si, v4si) 9854v8hi __builtin_ia32_phsubw128 (v8hi, v8hi) 9855v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi) 9856v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi) 9857v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi) 9858v16qi __builtin_ia32_pshufb128 (v16qi, v16qi) 9859v16qi __builtin_ia32_psignb128 (v16qi, v16qi) 9860v4si __builtin_ia32_psignd128 (v4si, v4si) 9861v8hi __builtin_ia32_psignw128 (v8hi, v8hi) 9862v2di __builtin_ia32_palignr128 (v2di, v2di, int) 9863v16qi __builtin_ia32_pabsb128 (v16qi) 9864v4si __builtin_ia32_pabsd128 (v4si) 9865v8hi __builtin_ia32_pabsw128 (v8hi) 9866@end smallexample 9867 9868The following built-in functions are available when @option{-msse4.1} is 9869used. All of them generate the machine instruction that is part of the 9870name. 9871 9872@smallexample 9873v2df __builtin_ia32_blendpd (v2df, v2df, const int) 9874v4sf __builtin_ia32_blendps (v4sf, v4sf, const int) 9875v2df __builtin_ia32_blendvpd (v2df, v2df, v2df) 9876v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf) 9877v2df __builtin_ia32_dppd (v2df, v2df, const int) 9878v4sf __builtin_ia32_dpps (v4sf, v4sf, const int) 9879v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int) 9880v2di __builtin_ia32_movntdqa (v2di *); 9881v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int) 9882v8hi __builtin_ia32_packusdw128 (v4si, v4si) 9883v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi) 9884v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int) 9885v2di __builtin_ia32_pcmpeqq (v2di, v2di) 9886v8hi __builtin_ia32_phminposuw128 (v8hi) 9887v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi) 9888v4si __builtin_ia32_pmaxsd128 (v4si, v4si) 9889v4si __builtin_ia32_pmaxud128 (v4si, v4si) 9890v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi) 9891v16qi __builtin_ia32_pminsb128 (v16qi, v16qi) 9892v4si __builtin_ia32_pminsd128 (v4si, v4si) 9893v4si __builtin_ia32_pminud128 (v4si, v4si) 9894v8hi __builtin_ia32_pminuw128 (v8hi, v8hi) 9895v4si __builtin_ia32_pmovsxbd128 (v16qi) 9896v2di __builtin_ia32_pmovsxbq128 (v16qi) 9897v8hi __builtin_ia32_pmovsxbw128 (v16qi) 9898v2di __builtin_ia32_pmovsxdq128 (v4si) 9899v4si __builtin_ia32_pmovsxwd128 (v8hi) 9900v2di __builtin_ia32_pmovsxwq128 (v8hi) 9901v4si __builtin_ia32_pmovzxbd128 (v16qi) 9902v2di __builtin_ia32_pmovzxbq128 (v16qi) 9903v8hi __builtin_ia32_pmovzxbw128 (v16qi) 9904v2di __builtin_ia32_pmovzxdq128 (v4si) 9905v4si __builtin_ia32_pmovzxwd128 (v8hi) 9906v2di __builtin_ia32_pmovzxwq128 (v8hi) 9907v2di __builtin_ia32_pmuldq128 (v4si, v4si) 9908v4si __builtin_ia32_pmulld128 (v4si, v4si) 9909int __builtin_ia32_ptestc128 (v2di, v2di) 9910int __builtin_ia32_ptestnzc128 (v2di, v2di) 9911int __builtin_ia32_ptestz128 (v2di, v2di) 9912v2df __builtin_ia32_roundpd (v2df, const int) 9913v4sf __builtin_ia32_roundps (v4sf, const int) 9914v2df __builtin_ia32_roundsd (v2df, v2df, const int) 9915v4sf __builtin_ia32_roundss (v4sf, v4sf, const int) 9916@end smallexample 9917 9918The following built-in functions are available when @option{-msse4.1} is 9919used. 9920 9921@table @code 9922@item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int) 9923Generates the @code{insertps} machine instruction. 9924@item int __builtin_ia32_vec_ext_v16qi (v16qi, const int) 9925Generates the @code{pextrb} machine instruction. 9926@item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int) 9927Generates the @code{pinsrb} machine instruction. 9928@item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int) 9929Generates the @code{pinsrd} machine instruction. 9930@item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int) 9931Generates the @code{pinsrq} machine instruction in 64bit mode. 9932@end table 9933 9934The following built-in functions are changed to generate new SSE4.1 9935instructions when @option{-msse4.1} is used. 9936 9937@table @code 9938@item float __builtin_ia32_vec_ext_v4sf (v4sf, const int) 9939Generates the @code{extractps} machine instruction. 9940@item int __builtin_ia32_vec_ext_v4si (v4si, const int) 9941Generates the @code{pextrd} machine instruction. 9942@item long long __builtin_ia32_vec_ext_v2di (v2di, const int) 9943Generates the @code{pextrq} machine instruction in 64bit mode. 9944@end table 9945 9946The following built-in functions are available when @option{-msse4.2} is 9947used. All of them generate the machine instruction that is part of the 9948name. 9949 9950@smallexample 9951v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int) 9952int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int) 9953int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int) 9954int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int) 9955int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int) 9956int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int) 9957int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int) 9958v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int) 9959int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int) 9960int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int) 9961int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int) 9962int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int) 9963int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int) 9964int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int) 9965v2di __builtin_ia32_pcmpgtq (v2di, v2di) 9966@end smallexample 9967 9968The following built-in functions are available when @option{-msse4.2} is 9969used. 9970 9971@table @code 9972@item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char) 9973Generates the @code{crc32b} machine instruction. 9974@item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short) 9975Generates the @code{crc32w} machine instruction. 9976@item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int) 9977Generates the @code{crc32l} machine instruction. 9978@item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long) 9979Generates the @code{crc32q} machine instruction. 9980@end table 9981 9982The following built-in functions are changed to generate new SSE4.2 9983instructions when @option{-msse4.2} is used. 9984 9985@table @code 9986@item int __builtin_popcount (unsigned int) 9987Generates the @code{popcntl} machine instruction. 9988@item int __builtin_popcountl (unsigned long) 9989Generates the @code{popcntl} or @code{popcntq} machine instruction, 9990depending on the size of @code{unsigned long}. 9991@item int __builtin_popcountll (unsigned long long) 9992Generates the @code{popcntq} machine instruction. 9993@end table 9994 9995The following built-in functions are available when @option{-mavx} is 9996used. All of them generate the machine instruction that is part of the 9997name. 9998 9999@smallexample 10000v4df __builtin_ia32_addpd256 (v4df,v4df) 10001v8sf __builtin_ia32_addps256 (v8sf,v8sf) 10002v4df __builtin_ia32_addsubpd256 (v4df,v4df) 10003v8sf __builtin_ia32_addsubps256 (v8sf,v8sf) 10004v4df __builtin_ia32_andnpd256 (v4df,v4df) 10005v8sf __builtin_ia32_andnps256 (v8sf,v8sf) 10006v4df __builtin_ia32_andpd256 (v4df,v4df) 10007v8sf __builtin_ia32_andps256 (v8sf,v8sf) 10008v4df __builtin_ia32_blendpd256 (v4df,v4df,int) 10009v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int) 10010v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df) 10011v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf) 10012v2df __builtin_ia32_cmppd (v2df,v2df,int) 10013v4df __builtin_ia32_cmppd256 (v4df,v4df,int) 10014v4sf __builtin_ia32_cmpps (v4sf,v4sf,int) 10015v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int) 10016v2df __builtin_ia32_cmpsd (v2df,v2df,int) 10017v4sf __builtin_ia32_cmpss (v4sf,v4sf,int) 10018v4df __builtin_ia32_cvtdq2pd256 (v4si) 10019v8sf __builtin_ia32_cvtdq2ps256 (v8si) 10020v4si __builtin_ia32_cvtpd2dq256 (v4df) 10021v4sf __builtin_ia32_cvtpd2ps256 (v4df) 10022v8si __builtin_ia32_cvtps2dq256 (v8sf) 10023v4df __builtin_ia32_cvtps2pd256 (v4sf) 10024v4si __builtin_ia32_cvttpd2dq256 (v4df) 10025v8si __builtin_ia32_cvttps2dq256 (v8sf) 10026v4df __builtin_ia32_divpd256 (v4df,v4df) 10027v8sf __builtin_ia32_divps256 (v8sf,v8sf) 10028v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int) 10029v4df __builtin_ia32_haddpd256 (v4df,v4df) 10030v8sf __builtin_ia32_haddps256 (v8sf,v8sf) 10031v4df __builtin_ia32_hsubpd256 (v4df,v4df) 10032v8sf __builtin_ia32_hsubps256 (v8sf,v8sf) 10033v32qi __builtin_ia32_lddqu256 (pcchar) 10034v32qi __builtin_ia32_loaddqu256 (pcchar) 10035v4df __builtin_ia32_loadupd256 (pcdouble) 10036v8sf __builtin_ia32_loadups256 (pcfloat) 10037v2df __builtin_ia32_maskloadpd (pcv2df,v2df) 10038v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df) 10039v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf) 10040v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf) 10041void __builtin_ia32_maskstorepd (pv2df,v2df,v2df) 10042void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df) 10043void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf) 10044void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf) 10045v4df __builtin_ia32_maxpd256 (v4df,v4df) 10046v8sf __builtin_ia32_maxps256 (v8sf,v8sf) 10047v4df __builtin_ia32_minpd256 (v4df,v4df) 10048v8sf __builtin_ia32_minps256 (v8sf,v8sf) 10049v4df __builtin_ia32_movddup256 (v4df) 10050int __builtin_ia32_movmskpd256 (v4df) 10051int __builtin_ia32_movmskps256 (v8sf) 10052v8sf __builtin_ia32_movshdup256 (v8sf) 10053v8sf __builtin_ia32_movsldup256 (v8sf) 10054v4df __builtin_ia32_mulpd256 (v4df,v4df) 10055v8sf __builtin_ia32_mulps256 (v8sf,v8sf) 10056v4df __builtin_ia32_orpd256 (v4df,v4df) 10057v8sf __builtin_ia32_orps256 (v8sf,v8sf) 10058v2df __builtin_ia32_pd_pd256 (v4df) 10059v4df __builtin_ia32_pd256_pd (v2df) 10060v4sf __builtin_ia32_ps_ps256 (v8sf) 10061v8sf __builtin_ia32_ps256_ps (v4sf) 10062int __builtin_ia32_ptestc256 (v4di,v4di,ptest) 10063int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest) 10064int __builtin_ia32_ptestz256 (v4di,v4di,ptest) 10065v8sf __builtin_ia32_rcpps256 (v8sf) 10066v4df __builtin_ia32_roundpd256 (v4df,int) 10067v8sf __builtin_ia32_roundps256 (v8sf,int) 10068v8sf __builtin_ia32_rsqrtps_nr256 (v8sf) 10069v8sf __builtin_ia32_rsqrtps256 (v8sf) 10070v4df __builtin_ia32_shufpd256 (v4df,v4df,int) 10071v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int) 10072v4si __builtin_ia32_si_si256 (v8si) 10073v8si __builtin_ia32_si256_si (v4si) 10074v4df __builtin_ia32_sqrtpd256 (v4df) 10075v8sf __builtin_ia32_sqrtps_nr256 (v8sf) 10076v8sf __builtin_ia32_sqrtps256 (v8sf) 10077void __builtin_ia32_storedqu256 (pchar,v32qi) 10078void __builtin_ia32_storeupd256 (pdouble,v4df) 10079void __builtin_ia32_storeups256 (pfloat,v8sf) 10080v4df __builtin_ia32_subpd256 (v4df,v4df) 10081v8sf __builtin_ia32_subps256 (v8sf,v8sf) 10082v4df __builtin_ia32_unpckhpd256 (v4df,v4df) 10083v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf) 10084v4df __builtin_ia32_unpcklpd256 (v4df,v4df) 10085v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf) 10086v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df) 10087v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf) 10088v4df __builtin_ia32_vbroadcastsd256 (pcdouble) 10089v4sf __builtin_ia32_vbroadcastss (pcfloat) 10090v8sf __builtin_ia32_vbroadcastss256 (pcfloat) 10091v2df __builtin_ia32_vextractf128_pd256 (v4df,int) 10092v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int) 10093v4si __builtin_ia32_vextractf128_si256 (v8si,int) 10094v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int) 10095v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int) 10096v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int) 10097v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int) 10098v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int) 10099v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int) 10100v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int) 10101v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int) 10102v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int) 10103v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int) 10104v2df __builtin_ia32_vpermilpd (v2df,int) 10105v4df __builtin_ia32_vpermilpd256 (v4df,int) 10106v4sf __builtin_ia32_vpermilps (v4sf,int) 10107v8sf __builtin_ia32_vpermilps256 (v8sf,int) 10108v2df __builtin_ia32_vpermilvarpd (v2df,v2di) 10109v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di) 10110v4sf __builtin_ia32_vpermilvarps (v4sf,v4si) 10111v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si) 10112int __builtin_ia32_vtestcpd (v2df,v2df,ptest) 10113int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest) 10114int __builtin_ia32_vtestcps (v4sf,v4sf,ptest) 10115int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest) 10116int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest) 10117int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest) 10118int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest) 10119int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest) 10120int __builtin_ia32_vtestzpd (v2df,v2df,ptest) 10121int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest) 10122int __builtin_ia32_vtestzps (v4sf,v4sf,ptest) 10123int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest) 10124void __builtin_ia32_vzeroall (void) 10125void __builtin_ia32_vzeroupper (void) 10126v4df __builtin_ia32_xorpd256 (v4df,v4df) 10127v8sf __builtin_ia32_xorps256 (v8sf,v8sf) 10128@end smallexample 10129 10130The following built-in functions are available when @option{-mavx2} is 10131used. All of them generate the machine instruction that is part of the 10132name. 10133 10134@smallexample 10135v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,v32qi,int) 10136v32qi __builtin_ia32_pabsb256 (v32qi) 10137v16hi __builtin_ia32_pabsw256 (v16hi) 10138v8si __builtin_ia32_pabsd256 (v8si) 10139v16hi builtin_ia32_packssdw256 (v8si,v8si) 10140v32qi __builtin_ia32_packsswb256 (v16hi,v16hi) 10141v16hi __builtin_ia32_packusdw256 (v8si,v8si) 10142v32qi __builtin_ia32_packuswb256 (v16hi,v16hi) 10143v32qi__builtin_ia32_paddb256 (v32qi,v32qi) 10144v16hi __builtin_ia32_paddw256 (v16hi,v16hi) 10145v8si __builtin_ia32_paddd256 (v8si,v8si) 10146v4di __builtin_ia32_paddq256 (v4di,v4di) 10147v32qi __builtin_ia32_paddsb256 (v32qi,v32qi) 10148v16hi __builtin_ia32_paddsw256 (v16hi,v16hi) 10149v32qi __builtin_ia32_paddusb256 (v32qi,v32qi) 10150v16hi __builtin_ia32_paddusw256 (v16hi,v16hi) 10151v4di __builtin_ia32_palignr256 (v4di,v4di,int) 10152v4di __builtin_ia32_andsi256 (v4di,v4di) 10153v4di __builtin_ia32_andnotsi256 (v4di,v4di) 10154v32qi__builtin_ia32_pavgb256 (v32qi,v32qi) 10155v16hi __builtin_ia32_pavgw256 (v16hi,v16hi) 10156v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi) 10157v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int) 10158v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi) 10159v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi) 10160v8si __builtin_ia32_pcmpeqd256 (c8si,v8si) 10161v4di __builtin_ia32_pcmpeqq256 (v4di,v4di) 10162v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi) 10163v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi) 10164v8si __builtin_ia32_pcmpgtd256 (v8si,v8si) 10165v4di __builtin_ia32_pcmpgtq256 (v4di,v4di) 10166v16hi __builtin_ia32_phaddw256 (v16hi,v16hi) 10167v8si __builtin_ia32_phaddd256 (v8si,v8si) 10168v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi) 10169v16hi __builtin_ia32_phsubw256 (v16hi,v16hi) 10170v8si __builtin_ia32_phsubd256 (v8si,v8si) 10171v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi) 10172v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi) 10173v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi) 10174v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi) 10175v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi) 10176v8si __builtin_ia32_pmaxsd256 (v8si,v8si) 10177v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi) 10178v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi) 10179v8si __builtin_ia32_pmaxud256 (v8si,v8si) 10180v32qi __builtin_ia32_pminsb256 (v32qi,v32qi) 10181v16hi __builtin_ia32_pminsw256 (v16hi,v16hi) 10182v8si __builtin_ia32_pminsd256 (v8si,v8si) 10183v32qi __builtin_ia32_pminub256 (v32qi,v32qi) 10184v16hi __builtin_ia32_pminuw256 (v16hi,v16hi) 10185v8si __builtin_ia32_pminud256 (v8si,v8si) 10186int __builtin_ia32_pmovmskb256 (v32qi) 10187v16hi __builtin_ia32_pmovsxbw256 (v16qi) 10188v8si __builtin_ia32_pmovsxbd256 (v16qi) 10189v4di __builtin_ia32_pmovsxbq256 (v16qi) 10190v8si __builtin_ia32_pmovsxwd256 (v8hi) 10191v4di __builtin_ia32_pmovsxwq256 (v8hi) 10192v4di __builtin_ia32_pmovsxdq256 (v4si) 10193v16hi __builtin_ia32_pmovzxbw256 (v16qi) 10194v8si __builtin_ia32_pmovzxbd256 (v16qi) 10195v4di __builtin_ia32_pmovzxbq256 (v16qi) 10196v8si __builtin_ia32_pmovzxwd256 (v8hi) 10197v4di __builtin_ia32_pmovzxwq256 (v8hi) 10198v4di __builtin_ia32_pmovzxdq256 (v4si) 10199v4di __builtin_ia32_pmuldq256 (v8si,v8si) 10200v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi) 10201v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi) 10202v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi) 10203v16hi __builtin_ia32_pmullw256 (v16hi,v16hi) 10204v8si __builtin_ia32_pmulld256 (v8si,v8si) 10205v4di __builtin_ia32_pmuludq256 (v8si,v8si) 10206v4di __builtin_ia32_por256 (v4di,v4di) 10207v16hi __builtin_ia32_psadbw256 (v32qi,v32qi) 10208v32qi __builtin_ia32_pshufb256 (v32qi,v32qi) 10209v8si __builtin_ia32_pshufd256 (v8si,int) 10210v16hi __builtin_ia32_pshufhw256 (v16hi,int) 10211v16hi __builtin_ia32_pshuflw256 (v16hi,int) 10212v32qi __builtin_ia32_psignb256 (v32qi,v32qi) 10213v16hi __builtin_ia32_psignw256 (v16hi,v16hi) 10214v8si __builtin_ia32_psignd256 (v8si,v8si) 10215v4di __builtin_ia32_pslldqi256 (v4di,int) 10216v16hi __builtin_ia32_psllwi256 (16hi,int) 10217v16hi __builtin_ia32_psllw256(v16hi,v8hi) 10218v8si __builtin_ia32_pslldi256 (v8si,int) 10219v8si __builtin_ia32_pslld256(v8si,v4si) 10220v4di __builtin_ia32_psllqi256 (v4di,int) 10221v4di __builtin_ia32_psllq256(v4di,v2di) 10222v16hi __builtin_ia32_psrawi256 (v16hi,int) 10223v16hi __builtin_ia32_psraw256 (v16hi,v8hi) 10224v8si __builtin_ia32_psradi256 (v8si,int) 10225v8si __builtin_ia32_psrad256 (v8si,v4si) 10226v4di __builtin_ia32_psrldqi256 (v4di, int) 10227v16hi __builtin_ia32_psrlwi256 (v16hi,int) 10228v16hi __builtin_ia32_psrlw256 (v16hi,v8hi) 10229v8si __builtin_ia32_psrldi256 (v8si,int) 10230v8si __builtin_ia32_psrld256 (v8si,v4si) 10231v4di __builtin_ia32_psrlqi256 (v4di,int) 10232v4di __builtin_ia32_psrlq256(v4di,v2di) 10233v32qi __builtin_ia32_psubb256 (v32qi,v32qi) 10234v32hi __builtin_ia32_psubw256 (v16hi,v16hi) 10235v8si __builtin_ia32_psubd256 (v8si,v8si) 10236v4di __builtin_ia32_psubq256 (v4di,v4di) 10237v32qi __builtin_ia32_psubsb256 (v32qi,v32qi) 10238v16hi __builtin_ia32_psubsw256 (v16hi,v16hi) 10239v32qi __builtin_ia32_psubusb256 (v32qi,v32qi) 10240v16hi __builtin_ia32_psubusw256 (v16hi,v16hi) 10241v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi) 10242v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi) 10243v8si __builtin_ia32_punpckhdq256 (v8si,v8si) 10244v4di __builtin_ia32_punpckhqdq256 (v4di,v4di) 10245v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi) 10246v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi) 10247v8si __builtin_ia32_punpckldq256 (v8si,v8si) 10248v4di __builtin_ia32_punpcklqdq256 (v4di,v4di) 10249v4di __builtin_ia32_pxor256 (v4di,v4di) 10250v4di __builtin_ia32_movntdqa256 (pv4di) 10251v4sf __builtin_ia32_vbroadcastss_ps (v4sf) 10252v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf) 10253v4df __builtin_ia32_vbroadcastsd_pd256 (v2df) 10254v4di __builtin_ia32_vbroadcastsi256 (v2di) 10255v4si __builtin_ia32_pblendd128 (v4si,v4si) 10256v8si __builtin_ia32_pblendd256 (v8si,v8si) 10257v32qi __builtin_ia32_pbroadcastb256 (v16qi) 10258v16hi __builtin_ia32_pbroadcastw256 (v8hi) 10259v8si __builtin_ia32_pbroadcastd256 (v4si) 10260v4di __builtin_ia32_pbroadcastq256 (v2di) 10261v16qi __builtin_ia32_pbroadcastb128 (v16qi) 10262v8hi __builtin_ia32_pbroadcastw128 (v8hi) 10263v4si __builtin_ia32_pbroadcastd128 (v4si) 10264v2di __builtin_ia32_pbroadcastq128 (v2di) 10265v8si __builtin_ia32_permvarsi256 (v8si,v8si) 10266v4df __builtin_ia32_permdf256 (v4df,int) 10267v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf) 10268v4di __builtin_ia32_permdi256 (v4di,int) 10269v4di __builtin_ia32_permti256 (v4di,v4di,int) 10270v4di __builtin_ia32_extract128i256 (v4di,int) 10271v4di __builtin_ia32_insert128i256 (v4di,v2di,int) 10272v8si __builtin_ia32_maskloadd256 (pcv8si,v8si) 10273v4di __builtin_ia32_maskloadq256 (pcv4di,v4di) 10274v4si __builtin_ia32_maskloadd (pcv4si,v4si) 10275v2di __builtin_ia32_maskloadq (pcv2di,v2di) 10276void __builtin_ia32_maskstored256 (pv8si,v8si,v8si) 10277void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di) 10278void __builtin_ia32_maskstored (pv4si,v4si,v4si) 10279void __builtin_ia32_maskstoreq (pv2di,v2di,v2di) 10280v8si __builtin_ia32_psllv8si (v8si,v8si) 10281v4si __builtin_ia32_psllv4si (v4si,v4si) 10282v4di __builtin_ia32_psllv4di (v4di,v4di) 10283v2di __builtin_ia32_psllv2di (v2di,v2di) 10284v8si __builtin_ia32_psrav8si (v8si,v8si) 10285v4si __builtin_ia32_psrav4si (v4si,v4si) 10286v8si __builtin_ia32_psrlv8si (v8si,v8si) 10287v4si __builtin_ia32_psrlv4si (v4si,v4si) 10288v4di __builtin_ia32_psrlv4di (v4di,v4di) 10289v2di __builtin_ia32_psrlv2di (v2di,v2di) 10290v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int) 10291v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int) 10292v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int) 10293v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int) 10294v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int) 10295v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int) 10296v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int) 10297v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int) 10298v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int) 10299v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int) 10300v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int) 10301v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int) 10302v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int) 10303v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int) 10304v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int) 10305v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int) 10306@end smallexample 10307 10308The following built-in functions are available when @option{-maes} is 10309used. All of them generate the machine instruction that is part of the 10310name. 10311 10312@smallexample 10313v2di __builtin_ia32_aesenc128 (v2di, v2di) 10314v2di __builtin_ia32_aesenclast128 (v2di, v2di) 10315v2di __builtin_ia32_aesdec128 (v2di, v2di) 10316v2di __builtin_ia32_aesdeclast128 (v2di, v2di) 10317v2di __builtin_ia32_aeskeygenassist128 (v2di, const int) 10318v2di __builtin_ia32_aesimc128 (v2di) 10319@end smallexample 10320 10321The following built-in function is available when @option{-mpclmul} is 10322used. 10323 10324@table @code 10325@item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int) 10326Generates the @code{pclmulqdq} machine instruction. 10327@end table 10328 10329The following built-in function is available when @option{-mfsgsbase} is 10330used. All of them generate the machine instruction that is part of the 10331name. 10332 10333@smallexample 10334unsigned int __builtin_ia32_rdfsbase32 (void) 10335unsigned long long __builtin_ia32_rdfsbase64 (void) 10336unsigned int __builtin_ia32_rdgsbase32 (void) 10337unsigned long long __builtin_ia32_rdgsbase64 (void) 10338void _writefsbase_u32 (unsigned int) 10339void _writefsbase_u64 (unsigned long long) 10340void _writegsbase_u32 (unsigned int) 10341void _writegsbase_u64 (unsigned long long) 10342@end smallexample 10343 10344The following built-in function is available when @option{-mrdrnd} is 10345used. All of them generate the machine instruction that is part of the 10346name. 10347 10348@smallexample 10349unsigned int __builtin_ia32_rdrand16_step (unsigned short *) 10350unsigned int __builtin_ia32_rdrand32_step (unsigned int *) 10351unsigned int __builtin_ia32_rdrand64_step (unsigned long long *) 10352@end smallexample 10353 10354The following built-in functions are available when @option{-msse4a} is used. 10355All of them generate the machine instruction that is part of the name. 10356 10357@smallexample 10358void __builtin_ia32_movntsd (double *, v2df) 10359void __builtin_ia32_movntss (float *, v4sf) 10360v2di __builtin_ia32_extrq (v2di, v16qi) 10361v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int) 10362v2di __builtin_ia32_insertq (v2di, v2di) 10363v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int) 10364@end smallexample 10365 10366The following built-in functions are available when @option{-mxop} is used. 10367@smallexample 10368v2df __builtin_ia32_vfrczpd (v2df) 10369v4sf __builtin_ia32_vfrczps (v4sf) 10370v2df __builtin_ia32_vfrczsd (v2df, v2df) 10371v4sf __builtin_ia32_vfrczss (v4sf, v4sf) 10372v4df __builtin_ia32_vfrczpd256 (v4df) 10373v8sf __builtin_ia32_vfrczps256 (v8sf) 10374v2di __builtin_ia32_vpcmov (v2di, v2di, v2di) 10375v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di) 10376v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si) 10377v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi) 10378v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi) 10379v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df) 10380v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf) 10381v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di) 10382v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si) 10383v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi) 10384v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi) 10385v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df) 10386v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf) 10387v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi) 10388v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) 10389v4si __builtin_ia32_vpcomeqd (v4si, v4si) 10390v2di __builtin_ia32_vpcomeqq (v2di, v2di) 10391v16qi __builtin_ia32_vpcomequb (v16qi, v16qi) 10392v4si __builtin_ia32_vpcomequd (v4si, v4si) 10393v2di __builtin_ia32_vpcomequq (v2di, v2di) 10394v8hi __builtin_ia32_vpcomequw (v8hi, v8hi) 10395v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) 10396v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi) 10397v4si __builtin_ia32_vpcomfalsed (v4si, v4si) 10398v2di __builtin_ia32_vpcomfalseq (v2di, v2di) 10399v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi) 10400v4si __builtin_ia32_vpcomfalseud (v4si, v4si) 10401v2di __builtin_ia32_vpcomfalseuq (v2di, v2di) 10402v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi) 10403v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi) 10404v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi) 10405v4si __builtin_ia32_vpcomged (v4si, v4si) 10406v2di __builtin_ia32_vpcomgeq (v2di, v2di) 10407v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi) 10408v4si __builtin_ia32_vpcomgeud (v4si, v4si) 10409v2di __builtin_ia32_vpcomgeuq (v2di, v2di) 10410v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi) 10411v8hi __builtin_ia32_vpcomgew (v8hi, v8hi) 10412v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi) 10413v4si __builtin_ia32_vpcomgtd (v4si, v4si) 10414v2di __builtin_ia32_vpcomgtq (v2di, v2di) 10415v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi) 10416v4si __builtin_ia32_vpcomgtud (v4si, v4si) 10417v2di __builtin_ia32_vpcomgtuq (v2di, v2di) 10418v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi) 10419v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi) 10420v16qi __builtin_ia32_vpcomleb (v16qi, v16qi) 10421v4si __builtin_ia32_vpcomled (v4si, v4si) 10422v2di __builtin_ia32_vpcomleq (v2di, v2di) 10423v16qi __builtin_ia32_vpcomleub (v16qi, v16qi) 10424v4si __builtin_ia32_vpcomleud (v4si, v4si) 10425v2di __builtin_ia32_vpcomleuq (v2di, v2di) 10426v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi) 10427v8hi __builtin_ia32_vpcomlew (v8hi, v8hi) 10428v16qi __builtin_ia32_vpcomltb (v16qi, v16qi) 10429v4si __builtin_ia32_vpcomltd (v4si, v4si) 10430v2di __builtin_ia32_vpcomltq (v2di, v2di) 10431v16qi __builtin_ia32_vpcomltub (v16qi, v16qi) 10432v4si __builtin_ia32_vpcomltud (v4si, v4si) 10433v2di __builtin_ia32_vpcomltuq (v2di, v2di) 10434v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi) 10435v8hi __builtin_ia32_vpcomltw (v8hi, v8hi) 10436v16qi __builtin_ia32_vpcomneb (v16qi, v16qi) 10437v4si __builtin_ia32_vpcomned (v4si, v4si) 10438v2di __builtin_ia32_vpcomneq (v2di, v2di) 10439v16qi __builtin_ia32_vpcomneub (v16qi, v16qi) 10440v4si __builtin_ia32_vpcomneud (v4si, v4si) 10441v2di __builtin_ia32_vpcomneuq (v2di, v2di) 10442v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi) 10443v8hi __builtin_ia32_vpcomnew (v8hi, v8hi) 10444v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi) 10445v4si __builtin_ia32_vpcomtrued (v4si, v4si) 10446v2di __builtin_ia32_vpcomtrueq (v2di, v2di) 10447v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi) 10448v4si __builtin_ia32_vpcomtrueud (v4si, v4si) 10449v2di __builtin_ia32_vpcomtrueuq (v2di, v2di) 10450v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi) 10451v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi) 10452v4si __builtin_ia32_vphaddbd (v16qi) 10453v2di __builtin_ia32_vphaddbq (v16qi) 10454v8hi __builtin_ia32_vphaddbw (v16qi) 10455v2di __builtin_ia32_vphadddq (v4si) 10456v4si __builtin_ia32_vphaddubd (v16qi) 10457v2di __builtin_ia32_vphaddubq (v16qi) 10458v8hi __builtin_ia32_vphaddubw (v16qi) 10459v2di __builtin_ia32_vphaddudq (v4si) 10460v4si __builtin_ia32_vphadduwd (v8hi) 10461v2di __builtin_ia32_vphadduwq (v8hi) 10462v4si __builtin_ia32_vphaddwd (v8hi) 10463v2di __builtin_ia32_vphaddwq (v8hi) 10464v8hi __builtin_ia32_vphsubbw (v16qi) 10465v2di __builtin_ia32_vphsubdq (v4si) 10466v4si __builtin_ia32_vphsubwd (v8hi) 10467v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si) 10468v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di) 10469v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di) 10470v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si) 10471v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di) 10472v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di) 10473v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si) 10474v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi) 10475v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si) 10476v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi) 10477v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si) 10478v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si) 10479v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi) 10480v16qi __builtin_ia32_vprotb (v16qi, v16qi) 10481v4si __builtin_ia32_vprotd (v4si, v4si) 10482v2di __builtin_ia32_vprotq (v2di, v2di) 10483v8hi __builtin_ia32_vprotw (v8hi, v8hi) 10484v16qi __builtin_ia32_vpshab (v16qi, v16qi) 10485v4si __builtin_ia32_vpshad (v4si, v4si) 10486v2di __builtin_ia32_vpshaq (v2di, v2di) 10487v8hi __builtin_ia32_vpshaw (v8hi, v8hi) 10488v16qi __builtin_ia32_vpshlb (v16qi, v16qi) 10489v4si __builtin_ia32_vpshld (v4si, v4si) 10490v2di __builtin_ia32_vpshlq (v2di, v2di) 10491v8hi __builtin_ia32_vpshlw (v8hi, v8hi) 10492@end smallexample 10493 10494The following built-in functions are available when @option{-mfma4} is used. 10495All of them generate the machine instruction that is part of the name 10496with MMX registers. 10497 10498@smallexample 10499v2df __builtin_ia32_fmaddpd (v2df, v2df, v2df) 10500v4sf __builtin_ia32_fmaddps (v4sf, v4sf, v4sf) 10501v2df __builtin_ia32_fmaddsd (v2df, v2df, v2df) 10502v4sf __builtin_ia32_fmaddss (v4sf, v4sf, v4sf) 10503v2df __builtin_ia32_fmsubpd (v2df, v2df, v2df) 10504v4sf __builtin_ia32_fmsubps (v4sf, v4sf, v4sf) 10505v2df __builtin_ia32_fmsubsd (v2df, v2df, v2df) 10506v4sf __builtin_ia32_fmsubss (v4sf, v4sf, v4sf) 10507v2df __builtin_ia32_fnmaddpd (v2df, v2df, v2df) 10508v4sf __builtin_ia32_fnmaddps (v4sf, v4sf, v4sf) 10509v2df __builtin_ia32_fnmaddsd (v2df, v2df, v2df) 10510v4sf __builtin_ia32_fnmaddss (v4sf, v4sf, v4sf) 10511v2df __builtin_ia32_fnmsubpd (v2df, v2df, v2df) 10512v4sf __builtin_ia32_fnmsubps (v4sf, v4sf, v4sf) 10513v2df __builtin_ia32_fnmsubsd (v2df, v2df, v2df) 10514v4sf __builtin_ia32_fnmsubss (v4sf, v4sf, v4sf) 10515v2df __builtin_ia32_fmaddsubpd (v2df, v2df, v2df) 10516v4sf __builtin_ia32_fmaddsubps (v4sf, v4sf, v4sf) 10517v2df __builtin_ia32_fmsubaddpd (v2df, v2df, v2df) 10518v4sf __builtin_ia32_fmsubaddps (v4sf, v4sf, v4sf) 10519v4df __builtin_ia32_fmaddpd256 (v4df, v4df, v4df) 10520v8sf __builtin_ia32_fmaddps256 (v8sf, v8sf, v8sf) 10521v4df __builtin_ia32_fmsubpd256 (v4df, v4df, v4df) 10522v8sf __builtin_ia32_fmsubps256 (v8sf, v8sf, v8sf) 10523v4df __builtin_ia32_fnmaddpd256 (v4df, v4df, v4df) 10524v8sf __builtin_ia32_fnmaddps256 (v8sf, v8sf, v8sf) 10525v4df __builtin_ia32_fnmsubpd256 (v4df, v4df, v4df) 10526v8sf __builtin_ia32_fnmsubps256 (v8sf, v8sf, v8sf) 10527v4df __builtin_ia32_fmaddsubpd256 (v4df, v4df, v4df) 10528v8sf __builtin_ia32_fmaddsubps256 (v8sf, v8sf, v8sf) 10529v4df __builtin_ia32_fmsubaddpd256 (v4df, v4df, v4df) 10530v8sf __builtin_ia32_fmsubaddps256 (v8sf, v8sf, v8sf) 10531 10532@end smallexample 10533 10534The following built-in functions are available when @option{-mlwp} is used. 10535 10536@smallexample 10537void __builtin_ia32_llwpcb16 (void *); 10538void __builtin_ia32_llwpcb32 (void *); 10539void __builtin_ia32_llwpcb64 (void *); 10540void * __builtin_ia32_llwpcb16 (void); 10541void * __builtin_ia32_llwpcb32 (void); 10542void * __builtin_ia32_llwpcb64 (void); 10543void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short) 10544void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int) 10545void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int) 10546unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short) 10547unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int) 10548unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int) 10549@end smallexample 10550 10551The following built-in functions are available when @option{-mbmi} is used. 10552All of them generate the machine instruction that is part of the name. 10553@smallexample 10554unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int); 10555unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long); 10556@end smallexample 10557 10558The following built-in functions are available when @option{-mbmi2} is used. 10559All of them generate the machine instruction that is part of the name. 10560@smallexample 10561unsigned int _bzhi_u32 (unsigned int, unsigned int) 10562unsigned int _pdep_u32 (unsigned int, unsigned int) 10563unsigned int _pext_u32 (unsigned int, unsigned int) 10564unsigned long long _bzhi_u64 (unsigned long long, unsigned long long) 10565unsigned long long _pdep_u64 (unsigned long long, unsigned long long) 10566unsigned long long _pext_u64 (unsigned long long, unsigned long long) 10567@end smallexample 10568 10569The following built-in functions are available when @option{-mlzcnt} is used. 10570All of them generate the machine instruction that is part of the name. 10571@smallexample 10572unsigned short __builtin_ia32_lzcnt_16(unsigned short); 10573unsigned int __builtin_ia32_lzcnt_u32(unsigned int); 10574unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long); 10575@end smallexample 10576 10577The following built-in functions are available when @option{-mtbm} is used. 10578Both of them generate the immediate form of the bextr machine instruction. 10579@smallexample 10580unsigned int __builtin_ia32_bextri_u32 (unsigned int, const unsigned int); 10581unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, const unsigned long long); 10582@end smallexample 10583 10584 10585The following built-in functions are available when @option{-m3dnow} is used. 10586All of them generate the machine instruction that is part of the name. 10587 10588@smallexample 10589void __builtin_ia32_femms (void) 10590v8qi __builtin_ia32_pavgusb (v8qi, v8qi) 10591v2si __builtin_ia32_pf2id (v2sf) 10592v2sf __builtin_ia32_pfacc (v2sf, v2sf) 10593v2sf __builtin_ia32_pfadd (v2sf, v2sf) 10594v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) 10595v2si __builtin_ia32_pfcmpge (v2sf, v2sf) 10596v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) 10597v2sf __builtin_ia32_pfmax (v2sf, v2sf) 10598v2sf __builtin_ia32_pfmin (v2sf, v2sf) 10599v2sf __builtin_ia32_pfmul (v2sf, v2sf) 10600v2sf __builtin_ia32_pfrcp (v2sf) 10601v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) 10602v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) 10603v2sf __builtin_ia32_pfrsqrt (v2sf) 10604v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf) 10605v2sf __builtin_ia32_pfsub (v2sf, v2sf) 10606v2sf __builtin_ia32_pfsubr (v2sf, v2sf) 10607v2sf __builtin_ia32_pi2fd (v2si) 10608v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) 10609@end smallexample 10610 10611The following built-in functions are available when both @option{-m3dnow} 10612and @option{-march=athlon} are used. All of them generate the machine 10613instruction that is part of the name. 10614 10615@smallexample 10616v2si __builtin_ia32_pf2iw (v2sf) 10617v2sf __builtin_ia32_pfnacc (v2sf, v2sf) 10618v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) 10619v2sf __builtin_ia32_pi2fw (v2si) 10620v2sf __builtin_ia32_pswapdsf (v2sf) 10621v2si __builtin_ia32_pswapdsi (v2si) 10622@end smallexample 10623 10624@node MIPS DSP Built-in Functions 10625@subsection MIPS DSP Built-in Functions 10626 10627The MIPS DSP Application-Specific Extension (ASE) includes new 10628instructions that are designed to improve the performance of DSP and 10629media applications. It provides instructions that operate on packed 106308-bit/16-bit integer data, Q7, Q15 and Q31 fractional data. 10631 10632GCC supports MIPS DSP operations using both the generic 10633vector extensions (@pxref{Vector Extensions}) and a collection of 10634MIPS-specific built-in functions. Both kinds of support are 10635enabled by the @option{-mdsp} command-line option. 10636 10637Revision 2 of the ASE was introduced in the second half of 2006. 10638This revision adds extra instructions to the original ASE, but is 10639otherwise backwards-compatible with it. You can select revision 2 10640using the command-line option @option{-mdspr2}; this option implies 10641@option{-mdsp}. 10642 10643The SCOUNT and POS bits of the DSP control register are global. The 10644WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and 10645POS bits. During optimization, the compiler will not delete these 10646instructions and it will not delete calls to functions containing 10647these instructions. 10648 10649At present, GCC only provides support for operations on 32-bit 10650vectors. The vector type associated with 8-bit integer data is 10651usually called @code{v4i8}, the vector type associated with Q7 10652is usually called @code{v4q7}, the vector type associated with 16-bit 10653integer data is usually called @code{v2i16}, and the vector type 10654associated with Q15 is usually called @code{v2q15}. They can be 10655defined in C as follows: 10656 10657@smallexample 10658typedef signed char v4i8 __attribute__ ((vector_size(4))); 10659typedef signed char v4q7 __attribute__ ((vector_size(4))); 10660typedef short v2i16 __attribute__ ((vector_size(4))); 10661typedef short v2q15 __attribute__ ((vector_size(4))); 10662@end smallexample 10663 10664@code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are 10665initialized in the same way as aggregates. For example: 10666 10667@smallexample 10668v4i8 a = @{1, 2, 3, 4@}; 10669v4i8 b; 10670b = (v4i8) @{5, 6, 7, 8@}; 10671 10672v2q15 c = @{0x0fcb, 0x3a75@}; 10673v2q15 d; 10674d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; 10675@end smallexample 10676 10677@emph{Note:} The CPU's endianness determines the order in which values 10678are packed. On little-endian targets, the first value is the least 10679significant and the last value is the most significant. The opposite 10680order applies to big-endian targets. For example, the code above will 10681set the lowest byte of @code{a} to @code{1} on little-endian targets 10682and @code{4} on big-endian targets. 10683 10684@emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer 10685representation. As shown in this example, the integer representation 10686of a Q7 value can be obtained by multiplying the fractional value by 10687@code{0x1.0p7}. The equivalent for Q15 values is to multiply by 10688@code{0x1.0p15}. The equivalent for Q31 values is to multiply by 10689@code{0x1.0p31}. 10690 10691The table below lists the @code{v4i8} and @code{v2q15} operations for which 10692hardware support exists. @code{a} and @code{b} are @code{v4i8} values, 10693and @code{c} and @code{d} are @code{v2q15} values. 10694 10695@multitable @columnfractions .50 .50 10696@item C code @tab MIPS instruction 10697@item @code{a + b} @tab @code{addu.qb} 10698@item @code{c + d} @tab @code{addq.ph} 10699@item @code{a - b} @tab @code{subu.qb} 10700@item @code{c - d} @tab @code{subq.ph} 10701@end multitable 10702 10703The table below lists the @code{v2i16} operation for which 10704hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are 10705@code{v2i16} values. 10706 10707@multitable @columnfractions .50 .50 10708@item C code @tab MIPS instruction 10709@item @code{e * f} @tab @code{mul.ph} 10710@end multitable 10711 10712It is easier to describe the DSP built-in functions if we first define 10713the following types: 10714 10715@smallexample 10716typedef int q31; 10717typedef int i32; 10718typedef unsigned int ui32; 10719typedef long long a64; 10720@end smallexample 10721 10722@code{q31} and @code{i32} are actually the same as @code{int}, but we 10723use @code{q31} to indicate a Q31 fractional value and @code{i32} to 10724indicate a 32-bit integer value. Similarly, @code{a64} is the same as 10725@code{long long}, but we use @code{a64} to indicate values that will 10726be placed in one of the four DSP accumulators (@code{$ac0}, 10727@code{$ac1}, @code{$ac2} or @code{$ac3}). 10728 10729Also, some built-in functions prefer or require immediate numbers as 10730parameters, because the corresponding DSP instructions accept both immediate 10731numbers and register operands, or accept immediate numbers only. The 10732immediate parameters are listed as follows. 10733 10734@smallexample 10735imm0_3: 0 to 3. 10736imm0_7: 0 to 7. 10737imm0_15: 0 to 15. 10738imm0_31: 0 to 31. 10739imm0_63: 0 to 63. 10740imm0_255: 0 to 255. 10741imm_n32_31: -32 to 31. 10742imm_n512_511: -512 to 511. 10743@end smallexample 10744 10745The following built-in functions map directly to a particular MIPS DSP 10746instruction. Please refer to the architecture specification 10747for details on what each instruction does. 10748 10749@smallexample 10750v2q15 __builtin_mips_addq_ph (v2q15, v2q15) 10751v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) 10752q31 __builtin_mips_addq_s_w (q31, q31) 10753v4i8 __builtin_mips_addu_qb (v4i8, v4i8) 10754v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) 10755v2q15 __builtin_mips_subq_ph (v2q15, v2q15) 10756v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) 10757q31 __builtin_mips_subq_s_w (q31, q31) 10758v4i8 __builtin_mips_subu_qb (v4i8, v4i8) 10759v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) 10760i32 __builtin_mips_addsc (i32, i32) 10761i32 __builtin_mips_addwc (i32, i32) 10762i32 __builtin_mips_modsub (i32, i32) 10763i32 __builtin_mips_raddu_w_qb (v4i8) 10764v2q15 __builtin_mips_absq_s_ph (v2q15) 10765q31 __builtin_mips_absq_s_w (q31) 10766v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) 10767v2q15 __builtin_mips_precrq_ph_w (q31, q31) 10768v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) 10769v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) 10770q31 __builtin_mips_preceq_w_phl (v2q15) 10771q31 __builtin_mips_preceq_w_phr (v2q15) 10772v2q15 __builtin_mips_precequ_ph_qbl (v4i8) 10773v2q15 __builtin_mips_precequ_ph_qbr (v4i8) 10774v2q15 __builtin_mips_precequ_ph_qbla (v4i8) 10775v2q15 __builtin_mips_precequ_ph_qbra (v4i8) 10776v2q15 __builtin_mips_preceu_ph_qbl (v4i8) 10777v2q15 __builtin_mips_preceu_ph_qbr (v4i8) 10778v2q15 __builtin_mips_preceu_ph_qbla (v4i8) 10779v2q15 __builtin_mips_preceu_ph_qbra (v4i8) 10780v4i8 __builtin_mips_shll_qb (v4i8, imm0_7) 10781v4i8 __builtin_mips_shll_qb (v4i8, i32) 10782v2q15 __builtin_mips_shll_ph (v2q15, imm0_15) 10783v2q15 __builtin_mips_shll_ph (v2q15, i32) 10784v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) 10785v2q15 __builtin_mips_shll_s_ph (v2q15, i32) 10786q31 __builtin_mips_shll_s_w (q31, imm0_31) 10787q31 __builtin_mips_shll_s_w (q31, i32) 10788v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) 10789v4i8 __builtin_mips_shrl_qb (v4i8, i32) 10790v2q15 __builtin_mips_shra_ph (v2q15, imm0_15) 10791v2q15 __builtin_mips_shra_ph (v2q15, i32) 10792v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) 10793v2q15 __builtin_mips_shra_r_ph (v2q15, i32) 10794q31 __builtin_mips_shra_r_w (q31, imm0_31) 10795q31 __builtin_mips_shra_r_w (q31, i32) 10796v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) 10797v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) 10798v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) 10799q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) 10800q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) 10801a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) 10802a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) 10803a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) 10804a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) 10805a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) 10806a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) 10807a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) 10808a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) 10809a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) 10810a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) 10811a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) 10812a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) 10813a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) 10814i32 __builtin_mips_bitrev (i32) 10815i32 __builtin_mips_insv (i32, i32) 10816v4i8 __builtin_mips_repl_qb (imm0_255) 10817v4i8 __builtin_mips_repl_qb (i32) 10818v2q15 __builtin_mips_repl_ph (imm_n512_511) 10819v2q15 __builtin_mips_repl_ph (i32) 10820void __builtin_mips_cmpu_eq_qb (v4i8, v4i8) 10821void __builtin_mips_cmpu_lt_qb (v4i8, v4i8) 10822void __builtin_mips_cmpu_le_qb (v4i8, v4i8) 10823i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) 10824i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) 10825i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) 10826void __builtin_mips_cmp_eq_ph (v2q15, v2q15) 10827void __builtin_mips_cmp_lt_ph (v2q15, v2q15) 10828void __builtin_mips_cmp_le_ph (v2q15, v2q15) 10829v4i8 __builtin_mips_pick_qb (v4i8, v4i8) 10830v2q15 __builtin_mips_pick_ph (v2q15, v2q15) 10831v2q15 __builtin_mips_packrl_ph (v2q15, v2q15) 10832i32 __builtin_mips_extr_w (a64, imm0_31) 10833i32 __builtin_mips_extr_w (a64, i32) 10834i32 __builtin_mips_extr_r_w (a64, imm0_31) 10835i32 __builtin_mips_extr_s_h (a64, i32) 10836i32 __builtin_mips_extr_rs_w (a64, imm0_31) 10837i32 __builtin_mips_extr_rs_w (a64, i32) 10838i32 __builtin_mips_extr_s_h (a64, imm0_31) 10839i32 __builtin_mips_extr_r_w (a64, i32) 10840i32 __builtin_mips_extp (a64, imm0_31) 10841i32 __builtin_mips_extp (a64, i32) 10842i32 __builtin_mips_extpdp (a64, imm0_31) 10843i32 __builtin_mips_extpdp (a64, i32) 10844a64 __builtin_mips_shilo (a64, imm_n32_31) 10845a64 __builtin_mips_shilo (a64, i32) 10846a64 __builtin_mips_mthlip (a64, i32) 10847void __builtin_mips_wrdsp (i32, imm0_63) 10848i32 __builtin_mips_rddsp (imm0_63) 10849i32 __builtin_mips_lbux (void *, i32) 10850i32 __builtin_mips_lhx (void *, i32) 10851i32 __builtin_mips_lwx (void *, i32) 10852a64 __builtin_mips_ldx (void *, i32) [MIPS64 only] 10853i32 __builtin_mips_bposge32 (void) 10854a64 __builtin_mips_madd (a64, i32, i32); 10855a64 __builtin_mips_maddu (a64, ui32, ui32); 10856a64 __builtin_mips_msub (a64, i32, i32); 10857a64 __builtin_mips_msubu (a64, ui32, ui32); 10858a64 __builtin_mips_mult (i32, i32); 10859a64 __builtin_mips_multu (ui32, ui32); 10860@end smallexample 10861 10862The following built-in functions map directly to a particular MIPS DSP REV 2 10863instruction. Please refer to the architecture specification 10864for details on what each instruction does. 10865 10866@smallexample 10867v4q7 __builtin_mips_absq_s_qb (v4q7); 10868v2i16 __builtin_mips_addu_ph (v2i16, v2i16); 10869v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16); 10870v4i8 __builtin_mips_adduh_qb (v4i8, v4i8); 10871v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8); 10872i32 __builtin_mips_append (i32, i32, imm0_31); 10873i32 __builtin_mips_balign (i32, i32, imm0_3); 10874i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8); 10875i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8); 10876i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8); 10877a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16); 10878a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16); 10879v2i16 __builtin_mips_mul_ph (v2i16, v2i16); 10880v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16); 10881q31 __builtin_mips_mulq_rs_w (q31, q31); 10882v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15); 10883q31 __builtin_mips_mulq_s_w (q31, q31); 10884a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16); 10885v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16); 10886v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31); 10887v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31); 10888i32 __builtin_mips_prepend (i32, i32, imm0_31); 10889v4i8 __builtin_mips_shra_qb (v4i8, imm0_7); 10890v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7); 10891v4i8 __builtin_mips_shra_qb (v4i8, i32); 10892v4i8 __builtin_mips_shra_r_qb (v4i8, i32); 10893v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15); 10894v2i16 __builtin_mips_shrl_ph (v2i16, i32); 10895v2i16 __builtin_mips_subu_ph (v2i16, v2i16); 10896v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16); 10897v4i8 __builtin_mips_subuh_qb (v4i8, v4i8); 10898v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8); 10899v2q15 __builtin_mips_addqh_ph (v2q15, v2q15); 10900v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15); 10901q31 __builtin_mips_addqh_w (q31, q31); 10902q31 __builtin_mips_addqh_r_w (q31, q31); 10903v2q15 __builtin_mips_subqh_ph (v2q15, v2q15); 10904v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15); 10905q31 __builtin_mips_subqh_w (q31, q31); 10906q31 __builtin_mips_subqh_r_w (q31, q31); 10907a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16); 10908a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16); 10909a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15); 10910a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15); 10911a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15); 10912a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15); 10913@end smallexample 10914 10915 10916@node MIPS Paired-Single Support 10917@subsection MIPS Paired-Single Support 10918 10919The MIPS64 architecture includes a number of instructions that 10920operate on pairs of single-precision floating-point values. 10921Each pair is packed into a 64-bit floating-point register, 10922with one element being designated the ``upper half'' and 10923the other being designated the ``lower half''. 10924 10925GCC supports paired-single operations using both the generic 10926vector extensions (@pxref{Vector Extensions}) and a collection of 10927MIPS-specific built-in functions. Both kinds of support are 10928enabled by the @option{-mpaired-single} command-line option. 10929 10930The vector type associated with paired-single values is usually 10931called @code{v2sf}. It can be defined in C as follows: 10932 10933@smallexample 10934typedef float v2sf __attribute__ ((vector_size (8))); 10935@end smallexample 10936 10937@code{v2sf} values are initialized in the same way as aggregates. 10938For example: 10939 10940@smallexample 10941v2sf a = @{1.5, 9.1@}; 10942v2sf b; 10943float e, f; 10944b = (v2sf) @{e, f@}; 10945@end smallexample 10946 10947@emph{Note:} The CPU's endianness determines which value is stored in 10948the upper half of a register and which value is stored in the lower half. 10949On little-endian targets, the first value is the lower one and the second 10950value is the upper one. The opposite order applies to big-endian targets. 10951For example, the code above will set the lower half of @code{a} to 10952@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. 10953 10954@node MIPS Loongson Built-in Functions 10955@subsection MIPS Loongson Built-in Functions 10956 10957GCC provides intrinsics to access the SIMD instructions provided by the 10958ST Microelectronics Loongson-2E and -2F processors. These intrinsics, 10959available after inclusion of the @code{loongson.h} header file, 10960operate on the following 64-bit vector types: 10961 10962@itemize 10963@item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers; 10964@item @code{uint16x4_t}, a vector of four unsigned 16-bit integers; 10965@item @code{uint32x2_t}, a vector of two unsigned 32-bit integers; 10966@item @code{int8x8_t}, a vector of eight signed 8-bit integers; 10967@item @code{int16x4_t}, a vector of four signed 16-bit integers; 10968@item @code{int32x2_t}, a vector of two signed 32-bit integers. 10969@end itemize 10970 10971The intrinsics provided are listed below; each is named after the 10972machine instruction to which it corresponds, with suffixes added as 10973appropriate to distinguish intrinsics that expand to the same machine 10974instruction yet have different argument types. Refer to the architecture 10975documentation for a description of the functionality of each 10976instruction. 10977 10978@smallexample 10979int16x4_t packsswh (int32x2_t s, int32x2_t t); 10980int8x8_t packsshb (int16x4_t s, int16x4_t t); 10981uint8x8_t packushb (uint16x4_t s, uint16x4_t t); 10982uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t); 10983uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t); 10984uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t); 10985int32x2_t paddw_s (int32x2_t s, int32x2_t t); 10986int16x4_t paddh_s (int16x4_t s, int16x4_t t); 10987int8x8_t paddb_s (int8x8_t s, int8x8_t t); 10988uint64_t paddd_u (uint64_t s, uint64_t t); 10989int64_t paddd_s (int64_t s, int64_t t); 10990int16x4_t paddsh (int16x4_t s, int16x4_t t); 10991int8x8_t paddsb (int8x8_t s, int8x8_t t); 10992uint16x4_t paddush (uint16x4_t s, uint16x4_t t); 10993uint8x8_t paddusb (uint8x8_t s, uint8x8_t t); 10994uint64_t pandn_ud (uint64_t s, uint64_t t); 10995uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t); 10996uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t); 10997uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t); 10998int64_t pandn_sd (int64_t s, int64_t t); 10999int32x2_t pandn_sw (int32x2_t s, int32x2_t t); 11000int16x4_t pandn_sh (int16x4_t s, int16x4_t t); 11001int8x8_t pandn_sb (int8x8_t s, int8x8_t t); 11002uint16x4_t pavgh (uint16x4_t s, uint16x4_t t); 11003uint8x8_t pavgb (uint8x8_t s, uint8x8_t t); 11004uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t); 11005uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t); 11006uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t); 11007int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t); 11008int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t); 11009int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t); 11010uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t); 11011uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t); 11012uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t); 11013int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t); 11014int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t); 11015int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t); 11016uint16x4_t pextrh_u (uint16x4_t s, int field); 11017int16x4_t pextrh_s (int16x4_t s, int field); 11018uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t); 11019uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t); 11020uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t); 11021uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t); 11022int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t); 11023int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t); 11024int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t); 11025int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t); 11026int32x2_t pmaddhw (int16x4_t s, int16x4_t t); 11027int16x4_t pmaxsh (int16x4_t s, int16x4_t t); 11028uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t); 11029int16x4_t pminsh (int16x4_t s, int16x4_t t); 11030uint8x8_t pminub (uint8x8_t s, uint8x8_t t); 11031uint8x8_t pmovmskb_u (uint8x8_t s); 11032int8x8_t pmovmskb_s (int8x8_t s); 11033uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t); 11034int16x4_t pmulhh (int16x4_t s, int16x4_t t); 11035int16x4_t pmullh (int16x4_t s, int16x4_t t); 11036int64_t pmuluw (uint32x2_t s, uint32x2_t t); 11037uint8x8_t pasubub (uint8x8_t s, uint8x8_t t); 11038uint16x4_t biadd (uint8x8_t s); 11039uint16x4_t psadbh (uint8x8_t s, uint8x8_t t); 11040uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order); 11041int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order); 11042uint16x4_t psllh_u (uint16x4_t s, uint8_t amount); 11043int16x4_t psllh_s (int16x4_t s, uint8_t amount); 11044uint32x2_t psllw_u (uint32x2_t s, uint8_t amount); 11045int32x2_t psllw_s (int32x2_t s, uint8_t amount); 11046uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount); 11047int16x4_t psrlh_s (int16x4_t s, uint8_t amount); 11048uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount); 11049int32x2_t psrlw_s (int32x2_t s, uint8_t amount); 11050uint16x4_t psrah_u (uint16x4_t s, uint8_t amount); 11051int16x4_t psrah_s (int16x4_t s, uint8_t amount); 11052uint32x2_t psraw_u (uint32x2_t s, uint8_t amount); 11053int32x2_t psraw_s (int32x2_t s, uint8_t amount); 11054uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t); 11055uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t); 11056uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t); 11057int32x2_t psubw_s (int32x2_t s, int32x2_t t); 11058int16x4_t psubh_s (int16x4_t s, int16x4_t t); 11059int8x8_t psubb_s (int8x8_t s, int8x8_t t); 11060uint64_t psubd_u (uint64_t s, uint64_t t); 11061int64_t psubd_s (int64_t s, int64_t t); 11062int16x4_t psubsh (int16x4_t s, int16x4_t t); 11063int8x8_t psubsb (int8x8_t s, int8x8_t t); 11064uint16x4_t psubush (uint16x4_t s, uint16x4_t t); 11065uint8x8_t psubusb (uint8x8_t s, uint8x8_t t); 11066uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t); 11067uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t); 11068uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t); 11069int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t); 11070int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t); 11071int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t); 11072uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t); 11073uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t); 11074uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t); 11075int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t); 11076int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t); 11077int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t); 11078@end smallexample 11079 11080@menu 11081* Paired-Single Arithmetic:: 11082* Paired-Single Built-in Functions:: 11083* MIPS-3D Built-in Functions:: 11084@end menu 11085 11086@node Paired-Single Arithmetic 11087@subsubsection Paired-Single Arithmetic 11088 11089The table below lists the @code{v2sf} operations for which hardware 11090support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} 11091values and @code{x} is an integral value. 11092 11093@multitable @columnfractions .50 .50 11094@item C code @tab MIPS instruction 11095@item @code{a + b} @tab @code{add.ps} 11096@item @code{a - b} @tab @code{sub.ps} 11097@item @code{-a} @tab @code{neg.ps} 11098@item @code{a * b} @tab @code{mul.ps} 11099@item @code{a * b + c} @tab @code{madd.ps} 11100@item @code{a * b - c} @tab @code{msub.ps} 11101@item @code{-(a * b + c)} @tab @code{nmadd.ps} 11102@item @code{-(a * b - c)} @tab @code{nmsub.ps} 11103@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} 11104@end multitable 11105 11106Note that the multiply-accumulate instructions can be disabled 11107using the command-line option @code{-mno-fused-madd}. 11108 11109@node Paired-Single Built-in Functions 11110@subsubsection Paired-Single Built-in Functions 11111 11112The following paired-single functions map directly to a particular 11113MIPS instruction. Please refer to the architecture specification 11114for details on what each instruction does. 11115 11116@table @code 11117@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) 11118Pair lower lower (@code{pll.ps}). 11119 11120@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) 11121Pair upper lower (@code{pul.ps}). 11122 11123@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) 11124Pair lower upper (@code{plu.ps}). 11125 11126@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) 11127Pair upper upper (@code{puu.ps}). 11128 11129@item v2sf __builtin_mips_cvt_ps_s (float, float) 11130Convert pair to paired single (@code{cvt.ps.s}). 11131 11132@item float __builtin_mips_cvt_s_pl (v2sf) 11133Convert pair lower to single (@code{cvt.s.pl}). 11134 11135@item float __builtin_mips_cvt_s_pu (v2sf) 11136Convert pair upper to single (@code{cvt.s.pu}). 11137 11138@item v2sf __builtin_mips_abs_ps (v2sf) 11139Absolute value (@code{abs.ps}). 11140 11141@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) 11142Align variable (@code{alnv.ps}). 11143 11144@emph{Note:} The value of the third parameter must be 0 or 4 11145modulo 8, otherwise the result will be unpredictable. Please read the 11146instruction description for details. 11147@end table 11148 11149The following multi-instruction functions are also available. 11150In each case, @var{cond} can be any of the 16 floating-point conditions: 11151@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 11152@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, 11153@code{lt}, @code{nge}, @code{le} or @code{ngt}. 11154 11155@table @code 11156@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 11157@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 11158Conditional move based on floating point comparison (@code{c.@var{cond}.ps}, 11159@code{movt.ps}/@code{movf.ps}). 11160 11161The @code{movt} functions return the value @var{x} computed by: 11162 11163@smallexample 11164c.@var{cond}.ps @var{cc},@var{a},@var{b} 11165mov.ps @var{x},@var{c} 11166movt.ps @var{x},@var{d},@var{cc} 11167@end smallexample 11168 11169The @code{movf} functions are similar but use @code{movf.ps} instead 11170of @code{movt.ps}. 11171 11172@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 11173@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 11174Comparison of two paired-single values (@code{c.@var{cond}.ps}, 11175@code{bc1t}/@code{bc1f}). 11176 11177These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 11178and return either the upper or lower half of the result. For example: 11179 11180@smallexample 11181v2sf a, b; 11182if (__builtin_mips_upper_c_eq_ps (a, b)) 11183 upper_halves_are_equal (); 11184else 11185 upper_halves_are_unequal (); 11186 11187if (__builtin_mips_lower_c_eq_ps (a, b)) 11188 lower_halves_are_equal (); 11189else 11190 lower_halves_are_unequal (); 11191@end smallexample 11192@end table 11193 11194@node MIPS-3D Built-in Functions 11195@subsubsection MIPS-3D Built-in Functions 11196 11197The MIPS-3D Application-Specific Extension (ASE) includes additional 11198paired-single instructions that are designed to improve the performance 11199of 3D graphics operations. Support for these instructions is controlled 11200by the @option{-mips3d} command-line option. 11201 11202The functions listed below map directly to a particular MIPS-3D 11203instruction. Please refer to the architecture specification for 11204more details on what each instruction does. 11205 11206@table @code 11207@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) 11208Reduction add (@code{addr.ps}). 11209 11210@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) 11211Reduction multiply (@code{mulr.ps}). 11212 11213@item v2sf __builtin_mips_cvt_pw_ps (v2sf) 11214Convert paired single to paired word (@code{cvt.pw.ps}). 11215 11216@item v2sf __builtin_mips_cvt_ps_pw (v2sf) 11217Convert paired word to paired single (@code{cvt.ps.pw}). 11218 11219@item float __builtin_mips_recip1_s (float) 11220@itemx double __builtin_mips_recip1_d (double) 11221@itemx v2sf __builtin_mips_recip1_ps (v2sf) 11222Reduced precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). 11223 11224@item float __builtin_mips_recip2_s (float, float) 11225@itemx double __builtin_mips_recip2_d (double, double) 11226@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) 11227Reduced precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). 11228 11229@item float __builtin_mips_rsqrt1_s (float) 11230@itemx double __builtin_mips_rsqrt1_d (double) 11231@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) 11232Reduced precision reciprocal square root (sequence step 1) 11233(@code{rsqrt1.@var{fmt}}). 11234 11235@item float __builtin_mips_rsqrt2_s (float, float) 11236@itemx double __builtin_mips_rsqrt2_d (double, double) 11237@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) 11238Reduced precision reciprocal square root (sequence step 2) 11239(@code{rsqrt2.@var{fmt}}). 11240@end table 11241 11242The following multi-instruction functions are also available. 11243In each case, @var{cond} can be any of the 16 floating-point conditions: 11244@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 11245@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 11246@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. 11247 11248@table @code 11249@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) 11250@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) 11251Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, 11252@code{bc1t}/@code{bc1f}). 11253 11254These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} 11255or @code{cabs.@var{cond}.d} and return the result as a boolean value. 11256For example: 11257 11258@smallexample 11259float a, b; 11260if (__builtin_mips_cabs_eq_s (a, b)) 11261 true (); 11262else 11263 false (); 11264@end smallexample 11265 11266@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 11267@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 11268Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, 11269@code{bc1t}/@code{bc1f}). 11270 11271These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} 11272and return either the upper or lower half of the result. For example: 11273 11274@smallexample 11275v2sf a, b; 11276if (__builtin_mips_upper_cabs_eq_ps (a, b)) 11277 upper_halves_are_equal (); 11278else 11279 upper_halves_are_unequal (); 11280 11281if (__builtin_mips_lower_cabs_eq_ps (a, b)) 11282 lower_halves_are_equal (); 11283else 11284 lower_halves_are_unequal (); 11285@end smallexample 11286 11287@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 11288@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 11289Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, 11290@code{movt.ps}/@code{movf.ps}). 11291 11292The @code{movt} functions return the value @var{x} computed by: 11293 11294@smallexample 11295cabs.@var{cond}.ps @var{cc},@var{a},@var{b} 11296mov.ps @var{x},@var{c} 11297movt.ps @var{x},@var{d},@var{cc} 11298@end smallexample 11299 11300The @code{movf} functions are similar but use @code{movf.ps} instead 11301of @code{movt.ps}. 11302 11303@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 11304@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 11305@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 11306@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 11307Comparison of two paired-single values 11308(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 11309@code{bc1any2t}/@code{bc1any2f}). 11310 11311These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 11312or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either 11313result is true and the @code{all} forms return true if both results are true. 11314For example: 11315 11316@smallexample 11317v2sf a, b; 11318if (__builtin_mips_any_c_eq_ps (a, b)) 11319 one_is_true (); 11320else 11321 both_are_false (); 11322 11323if (__builtin_mips_all_c_eq_ps (a, b)) 11324 both_are_true (); 11325else 11326 one_is_false (); 11327@end smallexample 11328 11329@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 11330@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 11331@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 11332@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 11333Comparison of four paired-single values 11334(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 11335@code{bc1any4t}/@code{bc1any4f}). 11336 11337These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} 11338to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. 11339The @code{any} forms return true if any of the four results are true 11340and the @code{all} forms return true if all four results are true. 11341For example: 11342 11343@smallexample 11344v2sf a, b, c, d; 11345if (__builtin_mips_any_c_eq_4s (a, b, c, d)) 11346 some_are_true (); 11347else 11348 all_are_false (); 11349 11350if (__builtin_mips_all_c_eq_4s (a, b, c, d)) 11351 all_are_true (); 11352else 11353 some_are_false (); 11354@end smallexample 11355@end table 11356 11357@node picoChip Built-in Functions 11358@subsection picoChip Built-in Functions 11359 11360GCC provides an interface to selected machine instructions from the 11361picoChip instruction set. 11362 11363@table @code 11364@item int __builtin_sbc (int @var{value}) 11365Sign bit count. Return the number of consecutive bits in @var{value} 11366which have the same value as the sign-bit. The result is the number of 11367leading sign bits minus one, giving the number of redundant sign bits in 11368@var{value}. 11369 11370@item int __builtin_byteswap (int @var{value}) 11371Byte swap. Return the result of swapping the upper and lower bytes of 11372@var{value}. 11373 11374@item int __builtin_brev (int @var{value}) 11375Bit reversal. Return the result of reversing the bits in 11376@var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1, 11377and so on. 11378 11379@item int __builtin_adds (int @var{x}, int @var{y}) 11380Saturating addition. Return the result of adding @var{x} and @var{y}, 11381storing the value 32767 if the result overflows. 11382 11383@item int __builtin_subs (int @var{x}, int @var{y}) 11384Saturating subtraction. Return the result of subtracting @var{y} from 11385@var{x}, storing the value @minus{}32768 if the result overflows. 11386 11387@item void __builtin_halt (void) 11388Halt. The processor will stop execution. This built-in is useful for 11389implementing assertions. 11390 11391@end table 11392 11393@node Other MIPS Built-in Functions 11394@subsection Other MIPS Built-in Functions 11395 11396GCC provides other MIPS-specific built-in functions: 11397 11398@table @code 11399@item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr}) 11400Insert a @samp{cache} instruction with operands @var{op} and @var{addr}. 11401GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE} 11402when this function is available. 11403@end table 11404 11405@node PowerPC AltiVec/VSX Built-in Functions 11406@subsection PowerPC AltiVec Built-in Functions 11407 11408GCC provides an interface for the PowerPC family of processors to access 11409the AltiVec operations described in Motorola's AltiVec Programming 11410Interface Manual. The interface is made available by including 11411@code{<altivec.h>} and using @option{-maltivec} and 11412@option{-mabi=altivec}. The interface supports the following vector 11413types. 11414 11415@smallexample 11416vector unsigned char 11417vector signed char 11418vector bool char 11419 11420vector unsigned short 11421vector signed short 11422vector bool short 11423vector pixel 11424 11425vector unsigned int 11426vector signed int 11427vector bool int 11428vector float 11429@end smallexample 11430 11431If @option{-mvsx} is used the following additional vector types are 11432implemented. 11433 11434@smallexample 11435vector unsigned long 11436vector signed long 11437vector double 11438@end smallexample 11439 11440The long types are only implemented for 64-bit code generation, and 11441the long type is only used in the floating point/integer conversion 11442instructions. 11443 11444GCC's implementation of the high-level language interface available from 11445C and C++ code differs from Motorola's documentation in several ways. 11446 11447@itemize @bullet 11448 11449@item 11450A vector constant is a list of constant expressions within curly braces. 11451 11452@item 11453A vector initializer requires no cast if the vector constant is of the 11454same type as the variable it is initializing. 11455 11456@item 11457If @code{signed} or @code{unsigned} is omitted, the signedness of the 11458vector type is the default signedness of the base type. The default 11459varies depending on the operating system, so a portable program should 11460always specify the signedness. 11461 11462@item 11463Compiling with @option{-maltivec} adds keywords @code{__vector}, 11464@code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and 11465@code{bool}. When compiling ISO C, the context-sensitive substitution 11466of the keywords @code{vector}, @code{pixel} and @code{bool} is 11467disabled. To use them, you must include @code{<altivec.h>} instead. 11468 11469@item 11470GCC allows using a @code{typedef} name as the type specifier for a 11471vector type. 11472 11473@item 11474For C, overloaded functions are implemented with macros so the following 11475does not work: 11476 11477@smallexample 11478 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); 11479@end smallexample 11480 11481Since @code{vec_add} is a macro, the vector constant in the example 11482is treated as four separate arguments. Wrap the entire argument in 11483parentheses for this to work. 11484@end itemize 11485 11486@emph{Note:} Only the @code{<altivec.h>} interface is supported. 11487Internally, GCC uses built-in functions to achieve the functionality in 11488the aforementioned header file, but they are not supported and are 11489subject to change without notice. 11490 11491The following interfaces are supported for the generic and specific 11492AltiVec operations and the AltiVec predicates. In cases where there 11493is a direct mapping between generic and specific operations, only the 11494generic names are shown here, although the specific operations can also 11495be used. 11496 11497Arguments that are documented as @code{const int} require literal 11498integral values within the range required for that operation. 11499 11500@smallexample 11501vector signed char vec_abs (vector signed char); 11502vector signed short vec_abs (vector signed short); 11503vector signed int vec_abs (vector signed int); 11504vector float vec_abs (vector float); 11505 11506vector signed char vec_abss (vector signed char); 11507vector signed short vec_abss (vector signed short); 11508vector signed int vec_abss (vector signed int); 11509 11510vector signed char vec_add (vector bool char, vector signed char); 11511vector signed char vec_add (vector signed char, vector bool char); 11512vector signed char vec_add (vector signed char, vector signed char); 11513vector unsigned char vec_add (vector bool char, vector unsigned char); 11514vector unsigned char vec_add (vector unsigned char, vector bool char); 11515vector unsigned char vec_add (vector unsigned char, 11516 vector unsigned char); 11517vector signed short vec_add (vector bool short, vector signed short); 11518vector signed short vec_add (vector signed short, vector bool short); 11519vector signed short vec_add (vector signed short, vector signed short); 11520vector unsigned short vec_add (vector bool short, 11521 vector unsigned short); 11522vector unsigned short vec_add (vector unsigned short, 11523 vector bool short); 11524vector unsigned short vec_add (vector unsigned short, 11525 vector unsigned short); 11526vector signed int vec_add (vector bool int, vector signed int); 11527vector signed int vec_add (vector signed int, vector bool int); 11528vector signed int vec_add (vector signed int, vector signed int); 11529vector unsigned int vec_add (vector bool int, vector unsigned int); 11530vector unsigned int vec_add (vector unsigned int, vector bool int); 11531vector unsigned int vec_add (vector unsigned int, vector unsigned int); 11532vector float vec_add (vector float, vector float); 11533 11534vector float vec_vaddfp (vector float, vector float); 11535 11536vector signed int vec_vadduwm (vector bool int, vector signed int); 11537vector signed int vec_vadduwm (vector signed int, vector bool int); 11538vector signed int vec_vadduwm (vector signed int, vector signed int); 11539vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); 11540vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); 11541vector unsigned int vec_vadduwm (vector unsigned int, 11542 vector unsigned int); 11543 11544vector signed short vec_vadduhm (vector bool short, 11545 vector signed short); 11546vector signed short vec_vadduhm (vector signed short, 11547 vector bool short); 11548vector signed short vec_vadduhm (vector signed short, 11549 vector signed short); 11550vector unsigned short vec_vadduhm (vector bool short, 11551 vector unsigned short); 11552vector unsigned short vec_vadduhm (vector unsigned short, 11553 vector bool short); 11554vector unsigned short vec_vadduhm (vector unsigned short, 11555 vector unsigned short); 11556 11557vector signed char vec_vaddubm (vector bool char, vector signed char); 11558vector signed char vec_vaddubm (vector signed char, vector bool char); 11559vector signed char vec_vaddubm (vector signed char, vector signed char); 11560vector unsigned char vec_vaddubm (vector bool char, 11561 vector unsigned char); 11562vector unsigned char vec_vaddubm (vector unsigned char, 11563 vector bool char); 11564vector unsigned char vec_vaddubm (vector unsigned char, 11565 vector unsigned char); 11566 11567vector unsigned int vec_addc (vector unsigned int, vector unsigned int); 11568 11569vector unsigned char vec_adds (vector bool char, vector unsigned char); 11570vector unsigned char vec_adds (vector unsigned char, vector bool char); 11571vector unsigned char vec_adds (vector unsigned char, 11572 vector unsigned char); 11573vector signed char vec_adds (vector bool char, vector signed char); 11574vector signed char vec_adds (vector signed char, vector bool char); 11575vector signed char vec_adds (vector signed char, vector signed char); 11576vector unsigned short vec_adds (vector bool short, 11577 vector unsigned short); 11578vector unsigned short vec_adds (vector unsigned short, 11579 vector bool short); 11580vector unsigned short vec_adds (vector unsigned short, 11581 vector unsigned short); 11582vector signed short vec_adds (vector bool short, vector signed short); 11583vector signed short vec_adds (vector signed short, vector bool short); 11584vector signed short vec_adds (vector signed short, vector signed short); 11585vector unsigned int vec_adds (vector bool int, vector unsigned int); 11586vector unsigned int vec_adds (vector unsigned int, vector bool int); 11587vector unsigned int vec_adds (vector unsigned int, vector unsigned int); 11588vector signed int vec_adds (vector bool int, vector signed int); 11589vector signed int vec_adds (vector signed int, vector bool int); 11590vector signed int vec_adds (vector signed int, vector signed int); 11591 11592vector signed int vec_vaddsws (vector bool int, vector signed int); 11593vector signed int vec_vaddsws (vector signed int, vector bool int); 11594vector signed int vec_vaddsws (vector signed int, vector signed int); 11595 11596vector unsigned int vec_vadduws (vector bool int, vector unsigned int); 11597vector unsigned int vec_vadduws (vector unsigned int, vector bool int); 11598vector unsigned int vec_vadduws (vector unsigned int, 11599 vector unsigned int); 11600 11601vector signed short vec_vaddshs (vector bool short, 11602 vector signed short); 11603vector signed short vec_vaddshs (vector signed short, 11604 vector bool short); 11605vector signed short vec_vaddshs (vector signed short, 11606 vector signed short); 11607 11608vector unsigned short vec_vadduhs (vector bool short, 11609 vector unsigned short); 11610vector unsigned short vec_vadduhs (vector unsigned short, 11611 vector bool short); 11612vector unsigned short vec_vadduhs (vector unsigned short, 11613 vector unsigned short); 11614 11615vector signed char vec_vaddsbs (vector bool char, vector signed char); 11616vector signed char vec_vaddsbs (vector signed char, vector bool char); 11617vector signed char vec_vaddsbs (vector signed char, vector signed char); 11618 11619vector unsigned char vec_vaddubs (vector bool char, 11620 vector unsigned char); 11621vector unsigned char vec_vaddubs (vector unsigned char, 11622 vector bool char); 11623vector unsigned char vec_vaddubs (vector unsigned char, 11624 vector unsigned char); 11625 11626vector float vec_and (vector float, vector float); 11627vector float vec_and (vector float, vector bool int); 11628vector float vec_and (vector bool int, vector float); 11629vector bool int vec_and (vector bool int, vector bool int); 11630vector signed int vec_and (vector bool int, vector signed int); 11631vector signed int vec_and (vector signed int, vector bool int); 11632vector signed int vec_and (vector signed int, vector signed int); 11633vector unsigned int vec_and (vector bool int, vector unsigned int); 11634vector unsigned int vec_and (vector unsigned int, vector bool int); 11635vector unsigned int vec_and (vector unsigned int, vector unsigned int); 11636vector bool short vec_and (vector bool short, vector bool short); 11637vector signed short vec_and (vector bool short, vector signed short); 11638vector signed short vec_and (vector signed short, vector bool short); 11639vector signed short vec_and (vector signed short, vector signed short); 11640vector unsigned short vec_and (vector bool short, 11641 vector unsigned short); 11642vector unsigned short vec_and (vector unsigned short, 11643 vector bool short); 11644vector unsigned short vec_and (vector unsigned short, 11645 vector unsigned short); 11646vector signed char vec_and (vector bool char, vector signed char); 11647vector bool char vec_and (vector bool char, vector bool char); 11648vector signed char vec_and (vector signed char, vector bool char); 11649vector signed char vec_and (vector signed char, vector signed char); 11650vector unsigned char vec_and (vector bool char, vector unsigned char); 11651vector unsigned char vec_and (vector unsigned char, vector bool char); 11652vector unsigned char vec_and (vector unsigned char, 11653 vector unsigned char); 11654 11655vector float vec_andc (vector float, vector float); 11656vector float vec_andc (vector float, vector bool int); 11657vector float vec_andc (vector bool int, vector float); 11658vector bool int vec_andc (vector bool int, vector bool int); 11659vector signed int vec_andc (vector bool int, vector signed int); 11660vector signed int vec_andc (vector signed int, vector bool int); 11661vector signed int vec_andc (vector signed int, vector signed int); 11662vector unsigned int vec_andc (vector bool int, vector unsigned int); 11663vector unsigned int vec_andc (vector unsigned int, vector bool int); 11664vector unsigned int vec_andc (vector unsigned int, vector unsigned int); 11665vector bool short vec_andc (vector bool short, vector bool short); 11666vector signed short vec_andc (vector bool short, vector signed short); 11667vector signed short vec_andc (vector signed short, vector bool short); 11668vector signed short vec_andc (vector signed short, vector signed short); 11669vector unsigned short vec_andc (vector bool short, 11670 vector unsigned short); 11671vector unsigned short vec_andc (vector unsigned short, 11672 vector bool short); 11673vector unsigned short vec_andc (vector unsigned short, 11674 vector unsigned short); 11675vector signed char vec_andc (vector bool char, vector signed char); 11676vector bool char vec_andc (vector bool char, vector bool char); 11677vector signed char vec_andc (vector signed char, vector bool char); 11678vector signed char vec_andc (vector signed char, vector signed char); 11679vector unsigned char vec_andc (vector bool char, vector unsigned char); 11680vector unsigned char vec_andc (vector unsigned char, vector bool char); 11681vector unsigned char vec_andc (vector unsigned char, 11682 vector unsigned char); 11683 11684vector unsigned char vec_avg (vector unsigned char, 11685 vector unsigned char); 11686vector signed char vec_avg (vector signed char, vector signed char); 11687vector unsigned short vec_avg (vector unsigned short, 11688 vector unsigned short); 11689vector signed short vec_avg (vector signed short, vector signed short); 11690vector unsigned int vec_avg (vector unsigned int, vector unsigned int); 11691vector signed int vec_avg (vector signed int, vector signed int); 11692 11693vector signed int vec_vavgsw (vector signed int, vector signed int); 11694 11695vector unsigned int vec_vavguw (vector unsigned int, 11696 vector unsigned int); 11697 11698vector signed short vec_vavgsh (vector signed short, 11699 vector signed short); 11700 11701vector unsigned short vec_vavguh (vector unsigned short, 11702 vector unsigned short); 11703 11704vector signed char vec_vavgsb (vector signed char, vector signed char); 11705 11706vector unsigned char vec_vavgub (vector unsigned char, 11707 vector unsigned char); 11708 11709vector float vec_copysign (vector float); 11710 11711vector float vec_ceil (vector float); 11712 11713vector signed int vec_cmpb (vector float, vector float); 11714 11715vector bool char vec_cmpeq (vector signed char, vector signed char); 11716vector bool char vec_cmpeq (vector unsigned char, vector unsigned char); 11717vector bool short vec_cmpeq (vector signed short, vector signed short); 11718vector bool short vec_cmpeq (vector unsigned short, 11719 vector unsigned short); 11720vector bool int vec_cmpeq (vector signed int, vector signed int); 11721vector bool int vec_cmpeq (vector unsigned int, vector unsigned int); 11722vector bool int vec_cmpeq (vector float, vector float); 11723 11724vector bool int vec_vcmpeqfp (vector float, vector float); 11725 11726vector bool int vec_vcmpequw (vector signed int, vector signed int); 11727vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); 11728 11729vector bool short vec_vcmpequh (vector signed short, 11730 vector signed short); 11731vector bool short vec_vcmpequh (vector unsigned short, 11732 vector unsigned short); 11733 11734vector bool char vec_vcmpequb (vector signed char, vector signed char); 11735vector bool char vec_vcmpequb (vector unsigned char, 11736 vector unsigned char); 11737 11738vector bool int vec_cmpge (vector float, vector float); 11739 11740vector bool char vec_cmpgt (vector unsigned char, vector unsigned char); 11741vector bool char vec_cmpgt (vector signed char, vector signed char); 11742vector bool short vec_cmpgt (vector unsigned short, 11743 vector unsigned short); 11744vector bool short vec_cmpgt (vector signed short, vector signed short); 11745vector bool int vec_cmpgt (vector unsigned int, vector unsigned int); 11746vector bool int vec_cmpgt (vector signed int, vector signed int); 11747vector bool int vec_cmpgt (vector float, vector float); 11748 11749vector bool int vec_vcmpgtfp (vector float, vector float); 11750 11751vector bool int vec_vcmpgtsw (vector signed int, vector signed int); 11752 11753vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); 11754 11755vector bool short vec_vcmpgtsh (vector signed short, 11756 vector signed short); 11757 11758vector bool short vec_vcmpgtuh (vector unsigned short, 11759 vector unsigned short); 11760 11761vector bool char vec_vcmpgtsb (vector signed char, vector signed char); 11762 11763vector bool char vec_vcmpgtub (vector unsigned char, 11764 vector unsigned char); 11765 11766vector bool int vec_cmple (vector float, vector float); 11767 11768vector bool char vec_cmplt (vector unsigned char, vector unsigned char); 11769vector bool char vec_cmplt (vector signed char, vector signed char); 11770vector bool short vec_cmplt (vector unsigned short, 11771 vector unsigned short); 11772vector bool short vec_cmplt (vector signed short, vector signed short); 11773vector bool int vec_cmplt (vector unsigned int, vector unsigned int); 11774vector bool int vec_cmplt (vector signed int, vector signed int); 11775vector bool int vec_cmplt (vector float, vector float); 11776 11777vector float vec_ctf (vector unsigned int, const int); 11778vector float vec_ctf (vector signed int, const int); 11779 11780vector float vec_vcfsx (vector signed int, const int); 11781 11782vector float vec_vcfux (vector unsigned int, const int); 11783 11784vector signed int vec_cts (vector float, const int); 11785 11786vector unsigned int vec_ctu (vector float, const int); 11787 11788void vec_dss (const int); 11789 11790void vec_dssall (void); 11791 11792void vec_dst (const vector unsigned char *, int, const int); 11793void vec_dst (const vector signed char *, int, const int); 11794void vec_dst (const vector bool char *, int, const int); 11795void vec_dst (const vector unsigned short *, int, const int); 11796void vec_dst (const vector signed short *, int, const int); 11797void vec_dst (const vector bool short *, int, const int); 11798void vec_dst (const vector pixel *, int, const int); 11799void vec_dst (const vector unsigned int *, int, const int); 11800void vec_dst (const vector signed int *, int, const int); 11801void vec_dst (const vector bool int *, int, const int); 11802void vec_dst (const vector float *, int, const int); 11803void vec_dst (const unsigned char *, int, const int); 11804void vec_dst (const signed char *, int, const int); 11805void vec_dst (const unsigned short *, int, const int); 11806void vec_dst (const short *, int, const int); 11807void vec_dst (const unsigned int *, int, const int); 11808void vec_dst (const int *, int, const int); 11809void vec_dst (const unsigned long *, int, const int); 11810void vec_dst (const long *, int, const int); 11811void vec_dst (const float *, int, const int); 11812 11813void vec_dstst (const vector unsigned char *, int, const int); 11814void vec_dstst (const vector signed char *, int, const int); 11815void vec_dstst (const vector bool char *, int, const int); 11816void vec_dstst (const vector unsigned short *, int, const int); 11817void vec_dstst (const vector signed short *, int, const int); 11818void vec_dstst (const vector bool short *, int, const int); 11819void vec_dstst (const vector pixel *, int, const int); 11820void vec_dstst (const vector unsigned int *, int, const int); 11821void vec_dstst (const vector signed int *, int, const int); 11822void vec_dstst (const vector bool int *, int, const int); 11823void vec_dstst (const vector float *, int, const int); 11824void vec_dstst (const unsigned char *, int, const int); 11825void vec_dstst (const signed char *, int, const int); 11826void vec_dstst (const unsigned short *, int, const int); 11827void vec_dstst (const short *, int, const int); 11828void vec_dstst (const unsigned int *, int, const int); 11829void vec_dstst (const int *, int, const int); 11830void vec_dstst (const unsigned long *, int, const int); 11831void vec_dstst (const long *, int, const int); 11832void vec_dstst (const float *, int, const int); 11833 11834void vec_dststt (const vector unsigned char *, int, const int); 11835void vec_dststt (const vector signed char *, int, const int); 11836void vec_dststt (const vector bool char *, int, const int); 11837void vec_dststt (const vector unsigned short *, int, const int); 11838void vec_dststt (const vector signed short *, int, const int); 11839void vec_dststt (const vector bool short *, int, const int); 11840void vec_dststt (const vector pixel *, int, const int); 11841void vec_dststt (const vector unsigned int *, int, const int); 11842void vec_dststt (const vector signed int *, int, const int); 11843void vec_dststt (const vector bool int *, int, const int); 11844void vec_dststt (const vector float *, int, const int); 11845void vec_dststt (const unsigned char *, int, const int); 11846void vec_dststt (const signed char *, int, const int); 11847void vec_dststt (const unsigned short *, int, const int); 11848void vec_dststt (const short *, int, const int); 11849void vec_dststt (const unsigned int *, int, const int); 11850void vec_dststt (const int *, int, const int); 11851void vec_dststt (const unsigned long *, int, const int); 11852void vec_dststt (const long *, int, const int); 11853void vec_dststt (const float *, int, const int); 11854 11855void vec_dstt (const vector unsigned char *, int, const int); 11856void vec_dstt (const vector signed char *, int, const int); 11857void vec_dstt (const vector bool char *, int, const int); 11858void vec_dstt (const vector unsigned short *, int, const int); 11859void vec_dstt (const vector signed short *, int, const int); 11860void vec_dstt (const vector bool short *, int, const int); 11861void vec_dstt (const vector pixel *, int, const int); 11862void vec_dstt (const vector unsigned int *, int, const int); 11863void vec_dstt (const vector signed int *, int, const int); 11864void vec_dstt (const vector bool int *, int, const int); 11865void vec_dstt (const vector float *, int, const int); 11866void vec_dstt (const unsigned char *, int, const int); 11867void vec_dstt (const signed char *, int, const int); 11868void vec_dstt (const unsigned short *, int, const int); 11869void vec_dstt (const short *, int, const int); 11870void vec_dstt (const unsigned int *, int, const int); 11871void vec_dstt (const int *, int, const int); 11872void vec_dstt (const unsigned long *, int, const int); 11873void vec_dstt (const long *, int, const int); 11874void vec_dstt (const float *, int, const int); 11875 11876vector float vec_expte (vector float); 11877 11878vector float vec_floor (vector float); 11879 11880vector float vec_ld (int, const vector float *); 11881vector float vec_ld (int, const float *); 11882vector bool int vec_ld (int, const vector bool int *); 11883vector signed int vec_ld (int, const vector signed int *); 11884vector signed int vec_ld (int, const int *); 11885vector signed int vec_ld (int, const long *); 11886vector unsigned int vec_ld (int, const vector unsigned int *); 11887vector unsigned int vec_ld (int, const unsigned int *); 11888vector unsigned int vec_ld (int, const unsigned long *); 11889vector bool short vec_ld (int, const vector bool short *); 11890vector pixel vec_ld (int, const vector pixel *); 11891vector signed short vec_ld (int, const vector signed short *); 11892vector signed short vec_ld (int, const short *); 11893vector unsigned short vec_ld (int, const vector unsigned short *); 11894vector unsigned short vec_ld (int, const unsigned short *); 11895vector bool char vec_ld (int, const vector bool char *); 11896vector signed char vec_ld (int, const vector signed char *); 11897vector signed char vec_ld (int, const signed char *); 11898vector unsigned char vec_ld (int, const vector unsigned char *); 11899vector unsigned char vec_ld (int, const unsigned char *); 11900 11901vector signed char vec_lde (int, const signed char *); 11902vector unsigned char vec_lde (int, const unsigned char *); 11903vector signed short vec_lde (int, const short *); 11904vector unsigned short vec_lde (int, const unsigned short *); 11905vector float vec_lde (int, const float *); 11906vector signed int vec_lde (int, const int *); 11907vector unsigned int vec_lde (int, const unsigned int *); 11908vector signed int vec_lde (int, const long *); 11909vector unsigned int vec_lde (int, const unsigned long *); 11910 11911vector float vec_lvewx (int, float *); 11912vector signed int vec_lvewx (int, int *); 11913vector unsigned int vec_lvewx (int, unsigned int *); 11914vector signed int vec_lvewx (int, long *); 11915vector unsigned int vec_lvewx (int, unsigned long *); 11916 11917vector signed short vec_lvehx (int, short *); 11918vector unsigned short vec_lvehx (int, unsigned short *); 11919 11920vector signed char vec_lvebx (int, char *); 11921vector unsigned char vec_lvebx (int, unsigned char *); 11922 11923vector float vec_ldl (int, const vector float *); 11924vector float vec_ldl (int, const float *); 11925vector bool int vec_ldl (int, const vector bool int *); 11926vector signed int vec_ldl (int, const vector signed int *); 11927vector signed int vec_ldl (int, const int *); 11928vector signed int vec_ldl (int, const long *); 11929vector unsigned int vec_ldl (int, const vector unsigned int *); 11930vector unsigned int vec_ldl (int, const unsigned int *); 11931vector unsigned int vec_ldl (int, const unsigned long *); 11932vector bool short vec_ldl (int, const vector bool short *); 11933vector pixel vec_ldl (int, const vector pixel *); 11934vector signed short vec_ldl (int, const vector signed short *); 11935vector signed short vec_ldl (int, const short *); 11936vector unsigned short vec_ldl (int, const vector unsigned short *); 11937vector unsigned short vec_ldl (int, const unsigned short *); 11938vector bool char vec_ldl (int, const vector bool char *); 11939vector signed char vec_ldl (int, const vector signed char *); 11940vector signed char vec_ldl (int, const signed char *); 11941vector unsigned char vec_ldl (int, const vector unsigned char *); 11942vector unsigned char vec_ldl (int, const unsigned char *); 11943 11944vector float vec_loge (vector float); 11945 11946vector unsigned char vec_lvsl (int, const volatile unsigned char *); 11947vector unsigned char vec_lvsl (int, const volatile signed char *); 11948vector unsigned char vec_lvsl (int, const volatile unsigned short *); 11949vector unsigned char vec_lvsl (int, const volatile short *); 11950vector unsigned char vec_lvsl (int, const volatile unsigned int *); 11951vector unsigned char vec_lvsl (int, const volatile int *); 11952vector unsigned char vec_lvsl (int, const volatile unsigned long *); 11953vector unsigned char vec_lvsl (int, const volatile long *); 11954vector unsigned char vec_lvsl (int, const volatile float *); 11955 11956vector unsigned char vec_lvsr (int, const volatile unsigned char *); 11957vector unsigned char vec_lvsr (int, const volatile signed char *); 11958vector unsigned char vec_lvsr (int, const volatile unsigned short *); 11959vector unsigned char vec_lvsr (int, const volatile short *); 11960vector unsigned char vec_lvsr (int, const volatile unsigned int *); 11961vector unsigned char vec_lvsr (int, const volatile int *); 11962vector unsigned char vec_lvsr (int, const volatile unsigned long *); 11963vector unsigned char vec_lvsr (int, const volatile long *); 11964vector unsigned char vec_lvsr (int, const volatile float *); 11965 11966vector float vec_madd (vector float, vector float, vector float); 11967 11968vector signed short vec_madds (vector signed short, 11969 vector signed short, 11970 vector signed short); 11971 11972vector unsigned char vec_max (vector bool char, vector unsigned char); 11973vector unsigned char vec_max (vector unsigned char, vector bool char); 11974vector unsigned char vec_max (vector unsigned char, 11975 vector unsigned char); 11976vector signed char vec_max (vector bool char, vector signed char); 11977vector signed char vec_max (vector signed char, vector bool char); 11978vector signed char vec_max (vector signed char, vector signed char); 11979vector unsigned short vec_max (vector bool short, 11980 vector unsigned short); 11981vector unsigned short vec_max (vector unsigned short, 11982 vector bool short); 11983vector unsigned short vec_max (vector unsigned short, 11984 vector unsigned short); 11985vector signed short vec_max (vector bool short, vector signed short); 11986vector signed short vec_max (vector signed short, vector bool short); 11987vector signed short vec_max (vector signed short, vector signed short); 11988vector unsigned int vec_max (vector bool int, vector unsigned int); 11989vector unsigned int vec_max (vector unsigned int, vector bool int); 11990vector unsigned int vec_max (vector unsigned int, vector unsigned int); 11991vector signed int vec_max (vector bool int, vector signed int); 11992vector signed int vec_max (vector signed int, vector bool int); 11993vector signed int vec_max (vector signed int, vector signed int); 11994vector float vec_max (vector float, vector float); 11995 11996vector float vec_vmaxfp (vector float, vector float); 11997 11998vector signed int vec_vmaxsw (vector bool int, vector signed int); 11999vector signed int vec_vmaxsw (vector signed int, vector bool int); 12000vector signed int vec_vmaxsw (vector signed int, vector signed int); 12001 12002vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); 12003vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); 12004vector unsigned int vec_vmaxuw (vector unsigned int, 12005 vector unsigned int); 12006 12007vector signed short vec_vmaxsh (vector bool short, vector signed short); 12008vector signed short vec_vmaxsh (vector signed short, vector bool short); 12009vector signed short vec_vmaxsh (vector signed short, 12010 vector signed short); 12011 12012vector unsigned short vec_vmaxuh (vector bool short, 12013 vector unsigned short); 12014vector unsigned short vec_vmaxuh (vector unsigned short, 12015 vector bool short); 12016vector unsigned short vec_vmaxuh (vector unsigned short, 12017 vector unsigned short); 12018 12019vector signed char vec_vmaxsb (vector bool char, vector signed char); 12020vector signed char vec_vmaxsb (vector signed char, vector bool char); 12021vector signed char vec_vmaxsb (vector signed char, vector signed char); 12022 12023vector unsigned char vec_vmaxub (vector bool char, 12024 vector unsigned char); 12025vector unsigned char vec_vmaxub (vector unsigned char, 12026 vector bool char); 12027vector unsigned char vec_vmaxub (vector unsigned char, 12028 vector unsigned char); 12029 12030vector bool char vec_mergeh (vector bool char, vector bool char); 12031vector signed char vec_mergeh (vector signed char, vector signed char); 12032vector unsigned char vec_mergeh (vector unsigned char, 12033 vector unsigned char); 12034vector bool short vec_mergeh (vector bool short, vector bool short); 12035vector pixel vec_mergeh (vector pixel, vector pixel); 12036vector signed short vec_mergeh (vector signed short, 12037 vector signed short); 12038vector unsigned short vec_mergeh (vector unsigned short, 12039 vector unsigned short); 12040vector float vec_mergeh (vector float, vector float); 12041vector bool int vec_mergeh (vector bool int, vector bool int); 12042vector signed int vec_mergeh (vector signed int, vector signed int); 12043vector unsigned int vec_mergeh (vector unsigned int, 12044 vector unsigned int); 12045 12046vector float vec_vmrghw (vector float, vector float); 12047vector bool int vec_vmrghw (vector bool int, vector bool int); 12048vector signed int vec_vmrghw (vector signed int, vector signed int); 12049vector unsigned int vec_vmrghw (vector unsigned int, 12050 vector unsigned int); 12051 12052vector bool short vec_vmrghh (vector bool short, vector bool short); 12053vector signed short vec_vmrghh (vector signed short, 12054 vector signed short); 12055vector unsigned short vec_vmrghh (vector unsigned short, 12056 vector unsigned short); 12057vector pixel vec_vmrghh (vector pixel, vector pixel); 12058 12059vector bool char vec_vmrghb (vector bool char, vector bool char); 12060vector signed char vec_vmrghb (vector signed char, vector signed char); 12061vector unsigned char vec_vmrghb (vector unsigned char, 12062 vector unsigned char); 12063 12064vector bool char vec_mergel (vector bool char, vector bool char); 12065vector signed char vec_mergel (vector signed char, vector signed char); 12066vector unsigned char vec_mergel (vector unsigned char, 12067 vector unsigned char); 12068vector bool short vec_mergel (vector bool short, vector bool short); 12069vector pixel vec_mergel (vector pixel, vector pixel); 12070vector signed short vec_mergel (vector signed short, 12071 vector signed short); 12072vector unsigned short vec_mergel (vector unsigned short, 12073 vector unsigned short); 12074vector float vec_mergel (vector float, vector float); 12075vector bool int vec_mergel (vector bool int, vector bool int); 12076vector signed int vec_mergel (vector signed int, vector signed int); 12077vector unsigned int vec_mergel (vector unsigned int, 12078 vector unsigned int); 12079 12080vector float vec_vmrglw (vector float, vector float); 12081vector signed int vec_vmrglw (vector signed int, vector signed int); 12082vector unsigned int vec_vmrglw (vector unsigned int, 12083 vector unsigned int); 12084vector bool int vec_vmrglw (vector bool int, vector bool int); 12085 12086vector bool short vec_vmrglh (vector bool short, vector bool short); 12087vector signed short vec_vmrglh (vector signed short, 12088 vector signed short); 12089vector unsigned short vec_vmrglh (vector unsigned short, 12090 vector unsigned short); 12091vector pixel vec_vmrglh (vector pixel, vector pixel); 12092 12093vector bool char vec_vmrglb (vector bool char, vector bool char); 12094vector signed char vec_vmrglb (vector signed char, vector signed char); 12095vector unsigned char vec_vmrglb (vector unsigned char, 12096 vector unsigned char); 12097 12098vector unsigned short vec_mfvscr (void); 12099 12100vector unsigned char vec_min (vector bool char, vector unsigned char); 12101vector unsigned char vec_min (vector unsigned char, vector bool char); 12102vector unsigned char vec_min (vector unsigned char, 12103 vector unsigned char); 12104vector signed char vec_min (vector bool char, vector signed char); 12105vector signed char vec_min (vector signed char, vector bool char); 12106vector signed char vec_min (vector signed char, vector signed char); 12107vector unsigned short vec_min (vector bool short, 12108 vector unsigned short); 12109vector unsigned short vec_min (vector unsigned short, 12110 vector bool short); 12111vector unsigned short vec_min (vector unsigned short, 12112 vector unsigned short); 12113vector signed short vec_min (vector bool short, vector signed short); 12114vector signed short vec_min (vector signed short, vector bool short); 12115vector signed short vec_min (vector signed short, vector signed short); 12116vector unsigned int vec_min (vector bool int, vector unsigned int); 12117vector unsigned int vec_min (vector unsigned int, vector bool int); 12118vector unsigned int vec_min (vector unsigned int, vector unsigned int); 12119vector signed int vec_min (vector bool int, vector signed int); 12120vector signed int vec_min (vector signed int, vector bool int); 12121vector signed int vec_min (vector signed int, vector signed int); 12122vector float vec_min (vector float, vector float); 12123 12124vector float vec_vminfp (vector float, vector float); 12125 12126vector signed int vec_vminsw (vector bool int, vector signed int); 12127vector signed int vec_vminsw (vector signed int, vector bool int); 12128vector signed int vec_vminsw (vector signed int, vector signed int); 12129 12130vector unsigned int vec_vminuw (vector bool int, vector unsigned int); 12131vector unsigned int vec_vminuw (vector unsigned int, vector bool int); 12132vector unsigned int vec_vminuw (vector unsigned int, 12133 vector unsigned int); 12134 12135vector signed short vec_vminsh (vector bool short, vector signed short); 12136vector signed short vec_vminsh (vector signed short, vector bool short); 12137vector signed short vec_vminsh (vector signed short, 12138 vector signed short); 12139 12140vector unsigned short vec_vminuh (vector bool short, 12141 vector unsigned short); 12142vector unsigned short vec_vminuh (vector unsigned short, 12143 vector bool short); 12144vector unsigned short vec_vminuh (vector unsigned short, 12145 vector unsigned short); 12146 12147vector signed char vec_vminsb (vector bool char, vector signed char); 12148vector signed char vec_vminsb (vector signed char, vector bool char); 12149vector signed char vec_vminsb (vector signed char, vector signed char); 12150 12151vector unsigned char vec_vminub (vector bool char, 12152 vector unsigned char); 12153vector unsigned char vec_vminub (vector unsigned char, 12154 vector bool char); 12155vector unsigned char vec_vminub (vector unsigned char, 12156 vector unsigned char); 12157 12158vector signed short vec_mladd (vector signed short, 12159 vector signed short, 12160 vector signed short); 12161vector signed short vec_mladd (vector signed short, 12162 vector unsigned short, 12163 vector unsigned short); 12164vector signed short vec_mladd (vector unsigned short, 12165 vector signed short, 12166 vector signed short); 12167vector unsigned short vec_mladd (vector unsigned short, 12168 vector unsigned short, 12169 vector unsigned short); 12170 12171vector signed short vec_mradds (vector signed short, 12172 vector signed short, 12173 vector signed short); 12174 12175vector unsigned int vec_msum (vector unsigned char, 12176 vector unsigned char, 12177 vector unsigned int); 12178vector signed int vec_msum (vector signed char, 12179 vector unsigned char, 12180 vector signed int); 12181vector unsigned int vec_msum (vector unsigned short, 12182 vector unsigned short, 12183 vector unsigned int); 12184vector signed int vec_msum (vector signed short, 12185 vector signed short, 12186 vector signed int); 12187 12188vector signed int vec_vmsumshm (vector signed short, 12189 vector signed short, 12190 vector signed int); 12191 12192vector unsigned int vec_vmsumuhm (vector unsigned short, 12193 vector unsigned short, 12194 vector unsigned int); 12195 12196vector signed int vec_vmsummbm (vector signed char, 12197 vector unsigned char, 12198 vector signed int); 12199 12200vector unsigned int vec_vmsumubm (vector unsigned char, 12201 vector unsigned char, 12202 vector unsigned int); 12203 12204vector unsigned int vec_msums (vector unsigned short, 12205 vector unsigned short, 12206 vector unsigned int); 12207vector signed int vec_msums (vector signed short, 12208 vector signed short, 12209 vector signed int); 12210 12211vector signed int vec_vmsumshs (vector signed short, 12212 vector signed short, 12213 vector signed int); 12214 12215vector unsigned int vec_vmsumuhs (vector unsigned short, 12216 vector unsigned short, 12217 vector unsigned int); 12218 12219void vec_mtvscr (vector signed int); 12220void vec_mtvscr (vector unsigned int); 12221void vec_mtvscr (vector bool int); 12222void vec_mtvscr (vector signed short); 12223void vec_mtvscr (vector unsigned short); 12224void vec_mtvscr (vector bool short); 12225void vec_mtvscr (vector pixel); 12226void vec_mtvscr (vector signed char); 12227void vec_mtvscr (vector unsigned char); 12228void vec_mtvscr (vector bool char); 12229 12230vector unsigned short vec_mule (vector unsigned char, 12231 vector unsigned char); 12232vector signed short vec_mule (vector signed char, 12233 vector signed char); 12234vector unsigned int vec_mule (vector unsigned short, 12235 vector unsigned short); 12236vector signed int vec_mule (vector signed short, vector signed short); 12237 12238vector signed int vec_vmulesh (vector signed short, 12239 vector signed short); 12240 12241vector unsigned int vec_vmuleuh (vector unsigned short, 12242 vector unsigned short); 12243 12244vector signed short vec_vmulesb (vector signed char, 12245 vector signed char); 12246 12247vector unsigned short vec_vmuleub (vector unsigned char, 12248 vector unsigned char); 12249 12250vector unsigned short vec_mulo (vector unsigned char, 12251 vector unsigned char); 12252vector signed short vec_mulo (vector signed char, vector signed char); 12253vector unsigned int vec_mulo (vector unsigned short, 12254 vector unsigned short); 12255vector signed int vec_mulo (vector signed short, vector signed short); 12256 12257vector signed int vec_vmulosh (vector signed short, 12258 vector signed short); 12259 12260vector unsigned int vec_vmulouh (vector unsigned short, 12261 vector unsigned short); 12262 12263vector signed short vec_vmulosb (vector signed char, 12264 vector signed char); 12265 12266vector unsigned short vec_vmuloub (vector unsigned char, 12267 vector unsigned char); 12268 12269vector float vec_nmsub (vector float, vector float, vector float); 12270 12271vector float vec_nor (vector float, vector float); 12272vector signed int vec_nor (vector signed int, vector signed int); 12273vector unsigned int vec_nor (vector unsigned int, vector unsigned int); 12274vector bool int vec_nor (vector bool int, vector bool int); 12275vector signed short vec_nor (vector signed short, vector signed short); 12276vector unsigned short vec_nor (vector unsigned short, 12277 vector unsigned short); 12278vector bool short vec_nor (vector bool short, vector bool short); 12279vector signed char vec_nor (vector signed char, vector signed char); 12280vector unsigned char vec_nor (vector unsigned char, 12281 vector unsigned char); 12282vector bool char vec_nor (vector bool char, vector bool char); 12283 12284vector float vec_or (vector float, vector float); 12285vector float vec_or (vector float, vector bool int); 12286vector float vec_or (vector bool int, vector float); 12287vector bool int vec_or (vector bool int, vector bool int); 12288vector signed int vec_or (vector bool int, vector signed int); 12289vector signed int vec_or (vector signed int, vector bool int); 12290vector signed int vec_or (vector signed int, vector signed int); 12291vector unsigned int vec_or (vector bool int, vector unsigned int); 12292vector unsigned int vec_or (vector unsigned int, vector bool int); 12293vector unsigned int vec_or (vector unsigned int, vector unsigned int); 12294vector bool short vec_or (vector bool short, vector bool short); 12295vector signed short vec_or (vector bool short, vector signed short); 12296vector signed short vec_or (vector signed short, vector bool short); 12297vector signed short vec_or (vector signed short, vector signed short); 12298vector unsigned short vec_or (vector bool short, vector unsigned short); 12299vector unsigned short vec_or (vector unsigned short, vector bool short); 12300vector unsigned short vec_or (vector unsigned short, 12301 vector unsigned short); 12302vector signed char vec_or (vector bool char, vector signed char); 12303vector bool char vec_or (vector bool char, vector bool char); 12304vector signed char vec_or (vector signed char, vector bool char); 12305vector signed char vec_or (vector signed char, vector signed char); 12306vector unsigned char vec_or (vector bool char, vector unsigned char); 12307vector unsigned char vec_or (vector unsigned char, vector bool char); 12308vector unsigned char vec_or (vector unsigned char, 12309 vector unsigned char); 12310 12311vector signed char vec_pack (vector signed short, vector signed short); 12312vector unsigned char vec_pack (vector unsigned short, 12313 vector unsigned short); 12314vector bool char vec_pack (vector bool short, vector bool short); 12315vector signed short vec_pack (vector signed int, vector signed int); 12316vector unsigned short vec_pack (vector unsigned int, 12317 vector unsigned int); 12318vector bool short vec_pack (vector bool int, vector bool int); 12319 12320vector bool short vec_vpkuwum (vector bool int, vector bool int); 12321vector signed short vec_vpkuwum (vector signed int, vector signed int); 12322vector unsigned short vec_vpkuwum (vector unsigned int, 12323 vector unsigned int); 12324 12325vector bool char vec_vpkuhum (vector bool short, vector bool short); 12326vector signed char vec_vpkuhum (vector signed short, 12327 vector signed short); 12328vector unsigned char vec_vpkuhum (vector unsigned short, 12329 vector unsigned short); 12330 12331vector pixel vec_packpx (vector unsigned int, vector unsigned int); 12332 12333vector unsigned char vec_packs (vector unsigned short, 12334 vector unsigned short); 12335vector signed char vec_packs (vector signed short, vector signed short); 12336vector unsigned short vec_packs (vector unsigned int, 12337 vector unsigned int); 12338vector signed short vec_packs (vector signed int, vector signed int); 12339 12340vector signed short vec_vpkswss (vector signed int, vector signed int); 12341 12342vector unsigned short vec_vpkuwus (vector unsigned int, 12343 vector unsigned int); 12344 12345vector signed char vec_vpkshss (vector signed short, 12346 vector signed short); 12347 12348vector unsigned char vec_vpkuhus (vector unsigned short, 12349 vector unsigned short); 12350 12351vector unsigned char vec_packsu (vector unsigned short, 12352 vector unsigned short); 12353vector unsigned char vec_packsu (vector signed short, 12354 vector signed short); 12355vector unsigned short vec_packsu (vector unsigned int, 12356 vector unsigned int); 12357vector unsigned short vec_packsu (vector signed int, vector signed int); 12358 12359vector unsigned short vec_vpkswus (vector signed int, 12360 vector signed int); 12361 12362vector unsigned char vec_vpkshus (vector signed short, 12363 vector signed short); 12364 12365vector float vec_perm (vector float, 12366 vector float, 12367 vector unsigned char); 12368vector signed int vec_perm (vector signed int, 12369 vector signed int, 12370 vector unsigned char); 12371vector unsigned int vec_perm (vector unsigned int, 12372 vector unsigned int, 12373 vector unsigned char); 12374vector bool int vec_perm (vector bool int, 12375 vector bool int, 12376 vector unsigned char); 12377vector signed short vec_perm (vector signed short, 12378 vector signed short, 12379 vector unsigned char); 12380vector unsigned short vec_perm (vector unsigned short, 12381 vector unsigned short, 12382 vector unsigned char); 12383vector bool short vec_perm (vector bool short, 12384 vector bool short, 12385 vector unsigned char); 12386vector pixel vec_perm (vector pixel, 12387 vector pixel, 12388 vector unsigned char); 12389vector signed char vec_perm (vector signed char, 12390 vector signed char, 12391 vector unsigned char); 12392vector unsigned char vec_perm (vector unsigned char, 12393 vector unsigned char, 12394 vector unsigned char); 12395vector bool char vec_perm (vector bool char, 12396 vector bool char, 12397 vector unsigned char); 12398 12399vector float vec_re (vector float); 12400 12401vector signed char vec_rl (vector signed char, 12402 vector unsigned char); 12403vector unsigned char vec_rl (vector unsigned char, 12404 vector unsigned char); 12405vector signed short vec_rl (vector signed short, vector unsigned short); 12406vector unsigned short vec_rl (vector unsigned short, 12407 vector unsigned short); 12408vector signed int vec_rl (vector signed int, vector unsigned int); 12409vector unsigned int vec_rl (vector unsigned int, vector unsigned int); 12410 12411vector signed int vec_vrlw (vector signed int, vector unsigned int); 12412vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); 12413 12414vector signed short vec_vrlh (vector signed short, 12415 vector unsigned short); 12416vector unsigned short vec_vrlh (vector unsigned short, 12417 vector unsigned short); 12418 12419vector signed char vec_vrlb (vector signed char, vector unsigned char); 12420vector unsigned char vec_vrlb (vector unsigned char, 12421 vector unsigned char); 12422 12423vector float vec_round (vector float); 12424 12425vector float vec_recip (vector float, vector float); 12426 12427vector float vec_rsqrt (vector float); 12428 12429vector float vec_rsqrte (vector float); 12430 12431vector float vec_sel (vector float, vector float, vector bool int); 12432vector float vec_sel (vector float, vector float, vector unsigned int); 12433vector signed int vec_sel (vector signed int, 12434 vector signed int, 12435 vector bool int); 12436vector signed int vec_sel (vector signed int, 12437 vector signed int, 12438 vector unsigned int); 12439vector unsigned int vec_sel (vector unsigned int, 12440 vector unsigned int, 12441 vector bool int); 12442vector unsigned int vec_sel (vector unsigned int, 12443 vector unsigned int, 12444 vector unsigned int); 12445vector bool int vec_sel (vector bool int, 12446 vector bool int, 12447 vector bool int); 12448vector bool int vec_sel (vector bool int, 12449 vector bool int, 12450 vector unsigned int); 12451vector signed short vec_sel (vector signed short, 12452 vector signed short, 12453 vector bool short); 12454vector signed short vec_sel (vector signed short, 12455 vector signed short, 12456 vector unsigned short); 12457vector unsigned short vec_sel (vector unsigned short, 12458 vector unsigned short, 12459 vector bool short); 12460vector unsigned short vec_sel (vector unsigned short, 12461 vector unsigned short, 12462 vector unsigned short); 12463vector bool short vec_sel (vector bool short, 12464 vector bool short, 12465 vector bool short); 12466vector bool short vec_sel (vector bool short, 12467 vector bool short, 12468 vector unsigned short); 12469vector signed char vec_sel (vector signed char, 12470 vector signed char, 12471 vector bool char); 12472vector signed char vec_sel (vector signed char, 12473 vector signed char, 12474 vector unsigned char); 12475vector unsigned char vec_sel (vector unsigned char, 12476 vector unsigned char, 12477 vector bool char); 12478vector unsigned char vec_sel (vector unsigned char, 12479 vector unsigned char, 12480 vector unsigned char); 12481vector bool char vec_sel (vector bool char, 12482 vector bool char, 12483 vector bool char); 12484vector bool char vec_sel (vector bool char, 12485 vector bool char, 12486 vector unsigned char); 12487 12488vector signed char vec_sl (vector signed char, 12489 vector unsigned char); 12490vector unsigned char vec_sl (vector unsigned char, 12491 vector unsigned char); 12492vector signed short vec_sl (vector signed short, vector unsigned short); 12493vector unsigned short vec_sl (vector unsigned short, 12494 vector unsigned short); 12495vector signed int vec_sl (vector signed int, vector unsigned int); 12496vector unsigned int vec_sl (vector unsigned int, vector unsigned int); 12497 12498vector signed int vec_vslw (vector signed int, vector unsigned int); 12499vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); 12500 12501vector signed short vec_vslh (vector signed short, 12502 vector unsigned short); 12503vector unsigned short vec_vslh (vector unsigned short, 12504 vector unsigned short); 12505 12506vector signed char vec_vslb (vector signed char, vector unsigned char); 12507vector unsigned char vec_vslb (vector unsigned char, 12508 vector unsigned char); 12509 12510vector float vec_sld (vector float, vector float, const int); 12511vector signed int vec_sld (vector signed int, 12512 vector signed int, 12513 const int); 12514vector unsigned int vec_sld (vector unsigned int, 12515 vector unsigned int, 12516 const int); 12517vector bool int vec_sld (vector bool int, 12518 vector bool int, 12519 const int); 12520vector signed short vec_sld (vector signed short, 12521 vector signed short, 12522 const int); 12523vector unsigned short vec_sld (vector unsigned short, 12524 vector unsigned short, 12525 const int); 12526vector bool short vec_sld (vector bool short, 12527 vector bool short, 12528 const int); 12529vector pixel vec_sld (vector pixel, 12530 vector pixel, 12531 const int); 12532vector signed char vec_sld (vector signed char, 12533 vector signed char, 12534 const int); 12535vector unsigned char vec_sld (vector unsigned char, 12536 vector unsigned char, 12537 const int); 12538vector bool char vec_sld (vector bool char, 12539 vector bool char, 12540 const int); 12541 12542vector signed int vec_sll (vector signed int, 12543 vector unsigned int); 12544vector signed int vec_sll (vector signed int, 12545 vector unsigned short); 12546vector signed int vec_sll (vector signed int, 12547 vector unsigned char); 12548vector unsigned int vec_sll (vector unsigned int, 12549 vector unsigned int); 12550vector unsigned int vec_sll (vector unsigned int, 12551 vector unsigned short); 12552vector unsigned int vec_sll (vector unsigned int, 12553 vector unsigned char); 12554vector bool int vec_sll (vector bool int, 12555 vector unsigned int); 12556vector bool int vec_sll (vector bool int, 12557 vector unsigned short); 12558vector bool int vec_sll (vector bool int, 12559 vector unsigned char); 12560vector signed short vec_sll (vector signed short, 12561 vector unsigned int); 12562vector signed short vec_sll (vector signed short, 12563 vector unsigned short); 12564vector signed short vec_sll (vector signed short, 12565 vector unsigned char); 12566vector unsigned short vec_sll (vector unsigned short, 12567 vector unsigned int); 12568vector unsigned short vec_sll (vector unsigned short, 12569 vector unsigned short); 12570vector unsigned short vec_sll (vector unsigned short, 12571 vector unsigned char); 12572vector bool short vec_sll (vector bool short, vector unsigned int); 12573vector bool short vec_sll (vector bool short, vector unsigned short); 12574vector bool short vec_sll (vector bool short, vector unsigned char); 12575vector pixel vec_sll (vector pixel, vector unsigned int); 12576vector pixel vec_sll (vector pixel, vector unsigned short); 12577vector pixel vec_sll (vector pixel, vector unsigned char); 12578vector signed char vec_sll (vector signed char, vector unsigned int); 12579vector signed char vec_sll (vector signed char, vector unsigned short); 12580vector signed char vec_sll (vector signed char, vector unsigned char); 12581vector unsigned char vec_sll (vector unsigned char, 12582 vector unsigned int); 12583vector unsigned char vec_sll (vector unsigned char, 12584 vector unsigned short); 12585vector unsigned char vec_sll (vector unsigned char, 12586 vector unsigned char); 12587vector bool char vec_sll (vector bool char, vector unsigned int); 12588vector bool char vec_sll (vector bool char, vector unsigned short); 12589vector bool char vec_sll (vector bool char, vector unsigned char); 12590 12591vector float vec_slo (vector float, vector signed char); 12592vector float vec_slo (vector float, vector unsigned char); 12593vector signed int vec_slo (vector signed int, vector signed char); 12594vector signed int vec_slo (vector signed int, vector unsigned char); 12595vector unsigned int vec_slo (vector unsigned int, vector signed char); 12596vector unsigned int vec_slo (vector unsigned int, vector unsigned char); 12597vector signed short vec_slo (vector signed short, vector signed char); 12598vector signed short vec_slo (vector signed short, vector unsigned char); 12599vector unsigned short vec_slo (vector unsigned short, 12600 vector signed char); 12601vector unsigned short vec_slo (vector unsigned short, 12602 vector unsigned char); 12603vector pixel vec_slo (vector pixel, vector signed char); 12604vector pixel vec_slo (vector pixel, vector unsigned char); 12605vector signed char vec_slo (vector signed char, vector signed char); 12606vector signed char vec_slo (vector signed char, vector unsigned char); 12607vector unsigned char vec_slo (vector unsigned char, vector signed char); 12608vector unsigned char vec_slo (vector unsigned char, 12609 vector unsigned char); 12610 12611vector signed char vec_splat (vector signed char, const int); 12612vector unsigned char vec_splat (vector unsigned char, const int); 12613vector bool char vec_splat (vector bool char, const int); 12614vector signed short vec_splat (vector signed short, const int); 12615vector unsigned short vec_splat (vector unsigned short, const int); 12616vector bool short vec_splat (vector bool short, const int); 12617vector pixel vec_splat (vector pixel, const int); 12618vector float vec_splat (vector float, const int); 12619vector signed int vec_splat (vector signed int, const int); 12620vector unsigned int vec_splat (vector unsigned int, const int); 12621vector bool int vec_splat (vector bool int, const int); 12622 12623vector float vec_vspltw (vector float, const int); 12624vector signed int vec_vspltw (vector signed int, const int); 12625vector unsigned int vec_vspltw (vector unsigned int, const int); 12626vector bool int vec_vspltw (vector bool int, const int); 12627 12628vector bool short vec_vsplth (vector bool short, const int); 12629vector signed short vec_vsplth (vector signed short, const int); 12630vector unsigned short vec_vsplth (vector unsigned short, const int); 12631vector pixel vec_vsplth (vector pixel, const int); 12632 12633vector signed char vec_vspltb (vector signed char, const int); 12634vector unsigned char vec_vspltb (vector unsigned char, const int); 12635vector bool char vec_vspltb (vector bool char, const int); 12636 12637vector signed char vec_splat_s8 (const int); 12638 12639vector signed short vec_splat_s16 (const int); 12640 12641vector signed int vec_splat_s32 (const int); 12642 12643vector unsigned char vec_splat_u8 (const int); 12644 12645vector unsigned short vec_splat_u16 (const int); 12646 12647vector unsigned int vec_splat_u32 (const int); 12648 12649vector signed char vec_sr (vector signed char, vector unsigned char); 12650vector unsigned char vec_sr (vector unsigned char, 12651 vector unsigned char); 12652vector signed short vec_sr (vector signed short, 12653 vector unsigned short); 12654vector unsigned short vec_sr (vector unsigned short, 12655 vector unsigned short); 12656vector signed int vec_sr (vector signed int, vector unsigned int); 12657vector unsigned int vec_sr (vector unsigned int, vector unsigned int); 12658 12659vector signed int vec_vsrw (vector signed int, vector unsigned int); 12660vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); 12661 12662vector signed short vec_vsrh (vector signed short, 12663 vector unsigned short); 12664vector unsigned short vec_vsrh (vector unsigned short, 12665 vector unsigned short); 12666 12667vector signed char vec_vsrb (vector signed char, vector unsigned char); 12668vector unsigned char vec_vsrb (vector unsigned char, 12669 vector unsigned char); 12670 12671vector signed char vec_sra (vector signed char, vector unsigned char); 12672vector unsigned char vec_sra (vector unsigned char, 12673 vector unsigned char); 12674vector signed short vec_sra (vector signed short, 12675 vector unsigned short); 12676vector unsigned short vec_sra (vector unsigned short, 12677 vector unsigned short); 12678vector signed int vec_sra (vector signed int, vector unsigned int); 12679vector unsigned int vec_sra (vector unsigned int, vector unsigned int); 12680 12681vector signed int vec_vsraw (vector signed int, vector unsigned int); 12682vector unsigned int vec_vsraw (vector unsigned int, 12683 vector unsigned int); 12684 12685vector signed short vec_vsrah (vector signed short, 12686 vector unsigned short); 12687vector unsigned short vec_vsrah (vector unsigned short, 12688 vector unsigned short); 12689 12690vector signed char vec_vsrab (vector signed char, vector unsigned char); 12691vector unsigned char vec_vsrab (vector unsigned char, 12692 vector unsigned char); 12693 12694vector signed int vec_srl (vector signed int, vector unsigned int); 12695vector signed int vec_srl (vector signed int, vector unsigned short); 12696vector signed int vec_srl (vector signed int, vector unsigned char); 12697vector unsigned int vec_srl (vector unsigned int, vector unsigned int); 12698vector unsigned int vec_srl (vector unsigned int, 12699 vector unsigned short); 12700vector unsigned int vec_srl (vector unsigned int, vector unsigned char); 12701vector bool int vec_srl (vector bool int, vector unsigned int); 12702vector bool int vec_srl (vector bool int, vector unsigned short); 12703vector bool int vec_srl (vector bool int, vector unsigned char); 12704vector signed short vec_srl (vector signed short, vector unsigned int); 12705vector signed short vec_srl (vector signed short, 12706 vector unsigned short); 12707vector signed short vec_srl (vector signed short, vector unsigned char); 12708vector unsigned short vec_srl (vector unsigned short, 12709 vector unsigned int); 12710vector unsigned short vec_srl (vector unsigned short, 12711 vector unsigned short); 12712vector unsigned short vec_srl (vector unsigned short, 12713 vector unsigned char); 12714vector bool short vec_srl (vector bool short, vector unsigned int); 12715vector bool short vec_srl (vector bool short, vector unsigned short); 12716vector bool short vec_srl (vector bool short, vector unsigned char); 12717vector pixel vec_srl (vector pixel, vector unsigned int); 12718vector pixel vec_srl (vector pixel, vector unsigned short); 12719vector pixel vec_srl (vector pixel, vector unsigned char); 12720vector signed char vec_srl (vector signed char, vector unsigned int); 12721vector signed char vec_srl (vector signed char, vector unsigned short); 12722vector signed char vec_srl (vector signed char, vector unsigned char); 12723vector unsigned char vec_srl (vector unsigned char, 12724 vector unsigned int); 12725vector unsigned char vec_srl (vector unsigned char, 12726 vector unsigned short); 12727vector unsigned char vec_srl (vector unsigned char, 12728 vector unsigned char); 12729vector bool char vec_srl (vector bool char, vector unsigned int); 12730vector bool char vec_srl (vector bool char, vector unsigned short); 12731vector bool char vec_srl (vector bool char, vector unsigned char); 12732 12733vector float vec_sro (vector float, vector signed char); 12734vector float vec_sro (vector float, vector unsigned char); 12735vector signed int vec_sro (vector signed int, vector signed char); 12736vector signed int vec_sro (vector signed int, vector unsigned char); 12737vector unsigned int vec_sro (vector unsigned int, vector signed char); 12738vector unsigned int vec_sro (vector unsigned int, vector unsigned char); 12739vector signed short vec_sro (vector signed short, vector signed char); 12740vector signed short vec_sro (vector signed short, vector unsigned char); 12741vector unsigned short vec_sro (vector unsigned short, 12742 vector signed char); 12743vector unsigned short vec_sro (vector unsigned short, 12744 vector unsigned char); 12745vector pixel vec_sro (vector pixel, vector signed char); 12746vector pixel vec_sro (vector pixel, vector unsigned char); 12747vector signed char vec_sro (vector signed char, vector signed char); 12748vector signed char vec_sro (vector signed char, vector unsigned char); 12749vector unsigned char vec_sro (vector unsigned char, vector signed char); 12750vector unsigned char vec_sro (vector unsigned char, 12751 vector unsigned char); 12752 12753void vec_st (vector float, int, vector float *); 12754void vec_st (vector float, int, float *); 12755void vec_st (vector signed int, int, vector signed int *); 12756void vec_st (vector signed int, int, int *); 12757void vec_st (vector unsigned int, int, vector unsigned int *); 12758void vec_st (vector unsigned int, int, unsigned int *); 12759void vec_st (vector bool int, int, vector bool int *); 12760void vec_st (vector bool int, int, unsigned int *); 12761void vec_st (vector bool int, int, int *); 12762void vec_st (vector signed short, int, vector signed short *); 12763void vec_st (vector signed short, int, short *); 12764void vec_st (vector unsigned short, int, vector unsigned short *); 12765void vec_st (vector unsigned short, int, unsigned short *); 12766void vec_st (vector bool short, int, vector bool short *); 12767void vec_st (vector bool short, int, unsigned short *); 12768void vec_st (vector pixel, int, vector pixel *); 12769void vec_st (vector pixel, int, unsigned short *); 12770void vec_st (vector pixel, int, short *); 12771void vec_st (vector bool short, int, short *); 12772void vec_st (vector signed char, int, vector signed char *); 12773void vec_st (vector signed char, int, signed char *); 12774void vec_st (vector unsigned char, int, vector unsigned char *); 12775void vec_st (vector unsigned char, int, unsigned char *); 12776void vec_st (vector bool char, int, vector bool char *); 12777void vec_st (vector bool char, int, unsigned char *); 12778void vec_st (vector bool char, int, signed char *); 12779 12780void vec_ste (vector signed char, int, signed char *); 12781void vec_ste (vector unsigned char, int, unsigned char *); 12782void vec_ste (vector bool char, int, signed char *); 12783void vec_ste (vector bool char, int, unsigned char *); 12784void vec_ste (vector signed short, int, short *); 12785void vec_ste (vector unsigned short, int, unsigned short *); 12786void vec_ste (vector bool short, int, short *); 12787void vec_ste (vector bool short, int, unsigned short *); 12788void vec_ste (vector pixel, int, short *); 12789void vec_ste (vector pixel, int, unsigned short *); 12790void vec_ste (vector float, int, float *); 12791void vec_ste (vector signed int, int, int *); 12792void vec_ste (vector unsigned int, int, unsigned int *); 12793void vec_ste (vector bool int, int, int *); 12794void vec_ste (vector bool int, int, unsigned int *); 12795 12796void vec_stvewx (vector float, int, float *); 12797void vec_stvewx (vector signed int, int, int *); 12798void vec_stvewx (vector unsigned int, int, unsigned int *); 12799void vec_stvewx (vector bool int, int, int *); 12800void vec_stvewx (vector bool int, int, unsigned int *); 12801 12802void vec_stvehx (vector signed short, int, short *); 12803void vec_stvehx (vector unsigned short, int, unsigned short *); 12804void vec_stvehx (vector bool short, int, short *); 12805void vec_stvehx (vector bool short, int, unsigned short *); 12806void vec_stvehx (vector pixel, int, short *); 12807void vec_stvehx (vector pixel, int, unsigned short *); 12808 12809void vec_stvebx (vector signed char, int, signed char *); 12810void vec_stvebx (vector unsigned char, int, unsigned char *); 12811void vec_stvebx (vector bool char, int, signed char *); 12812void vec_stvebx (vector bool char, int, unsigned char *); 12813 12814void vec_stl (vector float, int, vector float *); 12815void vec_stl (vector float, int, float *); 12816void vec_stl (vector signed int, int, vector signed int *); 12817void vec_stl (vector signed int, int, int *); 12818void vec_stl (vector unsigned int, int, vector unsigned int *); 12819void vec_stl (vector unsigned int, int, unsigned int *); 12820void vec_stl (vector bool int, int, vector bool int *); 12821void vec_stl (vector bool int, int, unsigned int *); 12822void vec_stl (vector bool int, int, int *); 12823void vec_stl (vector signed short, int, vector signed short *); 12824void vec_stl (vector signed short, int, short *); 12825void vec_stl (vector unsigned short, int, vector unsigned short *); 12826void vec_stl (vector unsigned short, int, unsigned short *); 12827void vec_stl (vector bool short, int, vector bool short *); 12828void vec_stl (vector bool short, int, unsigned short *); 12829void vec_stl (vector bool short, int, short *); 12830void vec_stl (vector pixel, int, vector pixel *); 12831void vec_stl (vector pixel, int, unsigned short *); 12832void vec_stl (vector pixel, int, short *); 12833void vec_stl (vector signed char, int, vector signed char *); 12834void vec_stl (vector signed char, int, signed char *); 12835void vec_stl (vector unsigned char, int, vector unsigned char *); 12836void vec_stl (vector unsigned char, int, unsigned char *); 12837void vec_stl (vector bool char, int, vector bool char *); 12838void vec_stl (vector bool char, int, unsigned char *); 12839void vec_stl (vector bool char, int, signed char *); 12840 12841vector signed char vec_sub (vector bool char, vector signed char); 12842vector signed char vec_sub (vector signed char, vector bool char); 12843vector signed char vec_sub (vector signed char, vector signed char); 12844vector unsigned char vec_sub (vector bool char, vector unsigned char); 12845vector unsigned char vec_sub (vector unsigned char, vector bool char); 12846vector unsigned char vec_sub (vector unsigned char, 12847 vector unsigned char); 12848vector signed short vec_sub (vector bool short, vector signed short); 12849vector signed short vec_sub (vector signed short, vector bool short); 12850vector signed short vec_sub (vector signed short, vector signed short); 12851vector unsigned short vec_sub (vector bool short, 12852 vector unsigned short); 12853vector unsigned short vec_sub (vector unsigned short, 12854 vector bool short); 12855vector unsigned short vec_sub (vector unsigned short, 12856 vector unsigned short); 12857vector signed int vec_sub (vector bool int, vector signed int); 12858vector signed int vec_sub (vector signed int, vector bool int); 12859vector signed int vec_sub (vector signed int, vector signed int); 12860vector unsigned int vec_sub (vector bool int, vector unsigned int); 12861vector unsigned int vec_sub (vector unsigned int, vector bool int); 12862vector unsigned int vec_sub (vector unsigned int, vector unsigned int); 12863vector float vec_sub (vector float, vector float); 12864 12865vector float vec_vsubfp (vector float, vector float); 12866 12867vector signed int vec_vsubuwm (vector bool int, vector signed int); 12868vector signed int vec_vsubuwm (vector signed int, vector bool int); 12869vector signed int vec_vsubuwm (vector signed int, vector signed int); 12870vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); 12871vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); 12872vector unsigned int vec_vsubuwm (vector unsigned int, 12873 vector unsigned int); 12874 12875vector signed short vec_vsubuhm (vector bool short, 12876 vector signed short); 12877vector signed short vec_vsubuhm (vector signed short, 12878 vector bool short); 12879vector signed short vec_vsubuhm (vector signed short, 12880 vector signed short); 12881vector unsigned short vec_vsubuhm (vector bool short, 12882 vector unsigned short); 12883vector unsigned short vec_vsubuhm (vector unsigned short, 12884 vector bool short); 12885vector unsigned short vec_vsubuhm (vector unsigned short, 12886 vector unsigned short); 12887 12888vector signed char vec_vsububm (vector bool char, vector signed char); 12889vector signed char vec_vsububm (vector signed char, vector bool char); 12890vector signed char vec_vsububm (vector signed char, vector signed char); 12891vector unsigned char vec_vsububm (vector bool char, 12892 vector unsigned char); 12893vector unsigned char vec_vsububm (vector unsigned char, 12894 vector bool char); 12895vector unsigned char vec_vsububm (vector unsigned char, 12896 vector unsigned char); 12897 12898vector unsigned int vec_subc (vector unsigned int, vector unsigned int); 12899 12900vector unsigned char vec_subs (vector bool char, vector unsigned char); 12901vector unsigned char vec_subs (vector unsigned char, vector bool char); 12902vector unsigned char vec_subs (vector unsigned char, 12903 vector unsigned char); 12904vector signed char vec_subs (vector bool char, vector signed char); 12905vector signed char vec_subs (vector signed char, vector bool char); 12906vector signed char vec_subs (vector signed char, vector signed char); 12907vector unsigned short vec_subs (vector bool short, 12908 vector unsigned short); 12909vector unsigned short vec_subs (vector unsigned short, 12910 vector bool short); 12911vector unsigned short vec_subs (vector unsigned short, 12912 vector unsigned short); 12913vector signed short vec_subs (vector bool short, vector signed short); 12914vector signed short vec_subs (vector signed short, vector bool short); 12915vector signed short vec_subs (vector signed short, vector signed short); 12916vector unsigned int vec_subs (vector bool int, vector unsigned int); 12917vector unsigned int vec_subs (vector unsigned int, vector bool int); 12918vector unsigned int vec_subs (vector unsigned int, vector unsigned int); 12919vector signed int vec_subs (vector bool int, vector signed int); 12920vector signed int vec_subs (vector signed int, vector bool int); 12921vector signed int vec_subs (vector signed int, vector signed int); 12922 12923vector signed int vec_vsubsws (vector bool int, vector signed int); 12924vector signed int vec_vsubsws (vector signed int, vector bool int); 12925vector signed int vec_vsubsws (vector signed int, vector signed int); 12926 12927vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); 12928vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); 12929vector unsigned int vec_vsubuws (vector unsigned int, 12930 vector unsigned int); 12931 12932vector signed short vec_vsubshs (vector bool short, 12933 vector signed short); 12934vector signed short vec_vsubshs (vector signed short, 12935 vector bool short); 12936vector signed short vec_vsubshs (vector signed short, 12937 vector signed short); 12938 12939vector unsigned short vec_vsubuhs (vector bool short, 12940 vector unsigned short); 12941vector unsigned short vec_vsubuhs (vector unsigned short, 12942 vector bool short); 12943vector unsigned short vec_vsubuhs (vector unsigned short, 12944 vector unsigned short); 12945 12946vector signed char vec_vsubsbs (vector bool char, vector signed char); 12947vector signed char vec_vsubsbs (vector signed char, vector bool char); 12948vector signed char vec_vsubsbs (vector signed char, vector signed char); 12949 12950vector unsigned char vec_vsububs (vector bool char, 12951 vector unsigned char); 12952vector unsigned char vec_vsububs (vector unsigned char, 12953 vector bool char); 12954vector unsigned char vec_vsububs (vector unsigned char, 12955 vector unsigned char); 12956 12957vector unsigned int vec_sum4s (vector unsigned char, 12958 vector unsigned int); 12959vector signed int vec_sum4s (vector signed char, vector signed int); 12960vector signed int vec_sum4s (vector signed short, vector signed int); 12961 12962vector signed int vec_vsum4shs (vector signed short, vector signed int); 12963 12964vector signed int vec_vsum4sbs (vector signed char, vector signed int); 12965 12966vector unsigned int vec_vsum4ubs (vector unsigned char, 12967 vector unsigned int); 12968 12969vector signed int vec_sum2s (vector signed int, vector signed int); 12970 12971vector signed int vec_sums (vector signed int, vector signed int); 12972 12973vector float vec_trunc (vector float); 12974 12975vector signed short vec_unpackh (vector signed char); 12976vector bool short vec_unpackh (vector bool char); 12977vector signed int vec_unpackh (vector signed short); 12978vector bool int vec_unpackh (vector bool short); 12979vector unsigned int vec_unpackh (vector pixel); 12980 12981vector bool int vec_vupkhsh (vector bool short); 12982vector signed int vec_vupkhsh (vector signed short); 12983 12984vector unsigned int vec_vupkhpx (vector pixel); 12985 12986vector bool short vec_vupkhsb (vector bool char); 12987vector signed short vec_vupkhsb (vector signed char); 12988 12989vector signed short vec_unpackl (vector signed char); 12990vector bool short vec_unpackl (vector bool char); 12991vector unsigned int vec_unpackl (vector pixel); 12992vector signed int vec_unpackl (vector signed short); 12993vector bool int vec_unpackl (vector bool short); 12994 12995vector unsigned int vec_vupklpx (vector pixel); 12996 12997vector bool int vec_vupklsh (vector bool short); 12998vector signed int vec_vupklsh (vector signed short); 12999 13000vector bool short vec_vupklsb (vector bool char); 13001vector signed short vec_vupklsb (vector signed char); 13002 13003vector float vec_xor (vector float, vector float); 13004vector float vec_xor (vector float, vector bool int); 13005vector float vec_xor (vector bool int, vector float); 13006vector bool int vec_xor (vector bool int, vector bool int); 13007vector signed int vec_xor (vector bool int, vector signed int); 13008vector signed int vec_xor (vector signed int, vector bool int); 13009vector signed int vec_xor (vector signed int, vector signed int); 13010vector unsigned int vec_xor (vector bool int, vector unsigned int); 13011vector unsigned int vec_xor (vector unsigned int, vector bool int); 13012vector unsigned int vec_xor (vector unsigned int, vector unsigned int); 13013vector bool short vec_xor (vector bool short, vector bool short); 13014vector signed short vec_xor (vector bool short, vector signed short); 13015vector signed short vec_xor (vector signed short, vector bool short); 13016vector signed short vec_xor (vector signed short, vector signed short); 13017vector unsigned short vec_xor (vector bool short, 13018 vector unsigned short); 13019vector unsigned short vec_xor (vector unsigned short, 13020 vector bool short); 13021vector unsigned short vec_xor (vector unsigned short, 13022 vector unsigned short); 13023vector signed char vec_xor (vector bool char, vector signed char); 13024vector bool char vec_xor (vector bool char, vector bool char); 13025vector signed char vec_xor (vector signed char, vector bool char); 13026vector signed char vec_xor (vector signed char, vector signed char); 13027vector unsigned char vec_xor (vector bool char, vector unsigned char); 13028vector unsigned char vec_xor (vector unsigned char, vector bool char); 13029vector unsigned char vec_xor (vector unsigned char, 13030 vector unsigned char); 13031 13032int vec_all_eq (vector signed char, vector bool char); 13033int vec_all_eq (vector signed char, vector signed char); 13034int vec_all_eq (vector unsigned char, vector bool char); 13035int vec_all_eq (vector unsigned char, vector unsigned char); 13036int vec_all_eq (vector bool char, vector bool char); 13037int vec_all_eq (vector bool char, vector unsigned char); 13038int vec_all_eq (vector bool char, vector signed char); 13039int vec_all_eq (vector signed short, vector bool short); 13040int vec_all_eq (vector signed short, vector signed short); 13041int vec_all_eq (vector unsigned short, vector bool short); 13042int vec_all_eq (vector unsigned short, vector unsigned short); 13043int vec_all_eq (vector bool short, vector bool short); 13044int vec_all_eq (vector bool short, vector unsigned short); 13045int vec_all_eq (vector bool short, vector signed short); 13046int vec_all_eq (vector pixel, vector pixel); 13047int vec_all_eq (vector signed int, vector bool int); 13048int vec_all_eq (vector signed int, vector signed int); 13049int vec_all_eq (vector unsigned int, vector bool int); 13050int vec_all_eq (vector unsigned int, vector unsigned int); 13051int vec_all_eq (vector bool int, vector bool int); 13052int vec_all_eq (vector bool int, vector unsigned int); 13053int vec_all_eq (vector bool int, vector signed int); 13054int vec_all_eq (vector float, vector float); 13055 13056int vec_all_ge (vector bool char, vector unsigned char); 13057int vec_all_ge (vector unsigned char, vector bool char); 13058int vec_all_ge (vector unsigned char, vector unsigned char); 13059int vec_all_ge (vector bool char, vector signed char); 13060int vec_all_ge (vector signed char, vector bool char); 13061int vec_all_ge (vector signed char, vector signed char); 13062int vec_all_ge (vector bool short, vector unsigned short); 13063int vec_all_ge (vector unsigned short, vector bool short); 13064int vec_all_ge (vector unsigned short, vector unsigned short); 13065int vec_all_ge (vector signed short, vector signed short); 13066int vec_all_ge (vector bool short, vector signed short); 13067int vec_all_ge (vector signed short, vector bool short); 13068int vec_all_ge (vector bool int, vector unsigned int); 13069int vec_all_ge (vector unsigned int, vector bool int); 13070int vec_all_ge (vector unsigned int, vector unsigned int); 13071int vec_all_ge (vector bool int, vector signed int); 13072int vec_all_ge (vector signed int, vector bool int); 13073int vec_all_ge (vector signed int, vector signed int); 13074int vec_all_ge (vector float, vector float); 13075 13076int vec_all_gt (vector bool char, vector unsigned char); 13077int vec_all_gt (vector unsigned char, vector bool char); 13078int vec_all_gt (vector unsigned char, vector unsigned char); 13079int vec_all_gt (vector bool char, vector signed char); 13080int vec_all_gt (vector signed char, vector bool char); 13081int vec_all_gt (vector signed char, vector signed char); 13082int vec_all_gt (vector bool short, vector unsigned short); 13083int vec_all_gt (vector unsigned short, vector bool short); 13084int vec_all_gt (vector unsigned short, vector unsigned short); 13085int vec_all_gt (vector bool short, vector signed short); 13086int vec_all_gt (vector signed short, vector bool short); 13087int vec_all_gt (vector signed short, vector signed short); 13088int vec_all_gt (vector bool int, vector unsigned int); 13089int vec_all_gt (vector unsigned int, vector bool int); 13090int vec_all_gt (vector unsigned int, vector unsigned int); 13091int vec_all_gt (vector bool int, vector signed int); 13092int vec_all_gt (vector signed int, vector bool int); 13093int vec_all_gt (vector signed int, vector signed int); 13094int vec_all_gt (vector float, vector float); 13095 13096int vec_all_in (vector float, vector float); 13097 13098int vec_all_le (vector bool char, vector unsigned char); 13099int vec_all_le (vector unsigned char, vector bool char); 13100int vec_all_le (vector unsigned char, vector unsigned char); 13101int vec_all_le (vector bool char, vector signed char); 13102int vec_all_le (vector signed char, vector bool char); 13103int vec_all_le (vector signed char, vector signed char); 13104int vec_all_le (vector bool short, vector unsigned short); 13105int vec_all_le (vector unsigned short, vector bool short); 13106int vec_all_le (vector unsigned short, vector unsigned short); 13107int vec_all_le (vector bool short, vector signed short); 13108int vec_all_le (vector signed short, vector bool short); 13109int vec_all_le (vector signed short, vector signed short); 13110int vec_all_le (vector bool int, vector unsigned int); 13111int vec_all_le (vector unsigned int, vector bool int); 13112int vec_all_le (vector unsigned int, vector unsigned int); 13113int vec_all_le (vector bool int, vector signed int); 13114int vec_all_le (vector signed int, vector bool int); 13115int vec_all_le (vector signed int, vector signed int); 13116int vec_all_le (vector float, vector float); 13117 13118int vec_all_lt (vector bool char, vector unsigned char); 13119int vec_all_lt (vector unsigned char, vector bool char); 13120int vec_all_lt (vector unsigned char, vector unsigned char); 13121int vec_all_lt (vector bool char, vector signed char); 13122int vec_all_lt (vector signed char, vector bool char); 13123int vec_all_lt (vector signed char, vector signed char); 13124int vec_all_lt (vector bool short, vector unsigned short); 13125int vec_all_lt (vector unsigned short, vector bool short); 13126int vec_all_lt (vector unsigned short, vector unsigned short); 13127int vec_all_lt (vector bool short, vector signed short); 13128int vec_all_lt (vector signed short, vector bool short); 13129int vec_all_lt (vector signed short, vector signed short); 13130int vec_all_lt (vector bool int, vector unsigned int); 13131int vec_all_lt (vector unsigned int, vector bool int); 13132int vec_all_lt (vector unsigned int, vector unsigned int); 13133int vec_all_lt (vector bool int, vector signed int); 13134int vec_all_lt (vector signed int, vector bool int); 13135int vec_all_lt (vector signed int, vector signed int); 13136int vec_all_lt (vector float, vector float); 13137 13138int vec_all_nan (vector float); 13139 13140int vec_all_ne (vector signed char, vector bool char); 13141int vec_all_ne (vector signed char, vector signed char); 13142int vec_all_ne (vector unsigned char, vector bool char); 13143int vec_all_ne (vector unsigned char, vector unsigned char); 13144int vec_all_ne (vector bool char, vector bool char); 13145int vec_all_ne (vector bool char, vector unsigned char); 13146int vec_all_ne (vector bool char, vector signed char); 13147int vec_all_ne (vector signed short, vector bool short); 13148int vec_all_ne (vector signed short, vector signed short); 13149int vec_all_ne (vector unsigned short, vector bool short); 13150int vec_all_ne (vector unsigned short, vector unsigned short); 13151int vec_all_ne (vector bool short, vector bool short); 13152int vec_all_ne (vector bool short, vector unsigned short); 13153int vec_all_ne (vector bool short, vector signed short); 13154int vec_all_ne (vector pixel, vector pixel); 13155int vec_all_ne (vector signed int, vector bool int); 13156int vec_all_ne (vector signed int, vector signed int); 13157int vec_all_ne (vector unsigned int, vector bool int); 13158int vec_all_ne (vector unsigned int, vector unsigned int); 13159int vec_all_ne (vector bool int, vector bool int); 13160int vec_all_ne (vector bool int, vector unsigned int); 13161int vec_all_ne (vector bool int, vector signed int); 13162int vec_all_ne (vector float, vector float); 13163 13164int vec_all_nge (vector float, vector float); 13165 13166int vec_all_ngt (vector float, vector float); 13167 13168int vec_all_nle (vector float, vector float); 13169 13170int vec_all_nlt (vector float, vector float); 13171 13172int vec_all_numeric (vector float); 13173 13174int vec_any_eq (vector signed char, vector bool char); 13175int vec_any_eq (vector signed char, vector signed char); 13176int vec_any_eq (vector unsigned char, vector bool char); 13177int vec_any_eq (vector unsigned char, vector unsigned char); 13178int vec_any_eq (vector bool char, vector bool char); 13179int vec_any_eq (vector bool char, vector unsigned char); 13180int vec_any_eq (vector bool char, vector signed char); 13181int vec_any_eq (vector signed short, vector bool short); 13182int vec_any_eq (vector signed short, vector signed short); 13183int vec_any_eq (vector unsigned short, vector bool short); 13184int vec_any_eq (vector unsigned short, vector unsigned short); 13185int vec_any_eq (vector bool short, vector bool short); 13186int vec_any_eq (vector bool short, vector unsigned short); 13187int vec_any_eq (vector bool short, vector signed short); 13188int vec_any_eq (vector pixel, vector pixel); 13189int vec_any_eq (vector signed int, vector bool int); 13190int vec_any_eq (vector signed int, vector signed int); 13191int vec_any_eq (vector unsigned int, vector bool int); 13192int vec_any_eq (vector unsigned int, vector unsigned int); 13193int vec_any_eq (vector bool int, vector bool int); 13194int vec_any_eq (vector bool int, vector unsigned int); 13195int vec_any_eq (vector bool int, vector signed int); 13196int vec_any_eq (vector float, vector float); 13197 13198int vec_any_ge (vector signed char, vector bool char); 13199int vec_any_ge (vector unsigned char, vector bool char); 13200int vec_any_ge (vector unsigned char, vector unsigned char); 13201int vec_any_ge (vector signed char, vector signed char); 13202int vec_any_ge (vector bool char, vector unsigned char); 13203int vec_any_ge (vector bool char, vector signed char); 13204int vec_any_ge (vector unsigned short, vector bool short); 13205int vec_any_ge (vector unsigned short, vector unsigned short); 13206int vec_any_ge (vector signed short, vector signed short); 13207int vec_any_ge (vector signed short, vector bool short); 13208int vec_any_ge (vector bool short, vector unsigned short); 13209int vec_any_ge (vector bool short, vector signed short); 13210int vec_any_ge (vector signed int, vector bool int); 13211int vec_any_ge (vector unsigned int, vector bool int); 13212int vec_any_ge (vector unsigned int, vector unsigned int); 13213int vec_any_ge (vector signed int, vector signed int); 13214int vec_any_ge (vector bool int, vector unsigned int); 13215int vec_any_ge (vector bool int, vector signed int); 13216int vec_any_ge (vector float, vector float); 13217 13218int vec_any_gt (vector bool char, vector unsigned char); 13219int vec_any_gt (vector unsigned char, vector bool char); 13220int vec_any_gt (vector unsigned char, vector unsigned char); 13221int vec_any_gt (vector bool char, vector signed char); 13222int vec_any_gt (vector signed char, vector bool char); 13223int vec_any_gt (vector signed char, vector signed char); 13224int vec_any_gt (vector bool short, vector unsigned short); 13225int vec_any_gt (vector unsigned short, vector bool short); 13226int vec_any_gt (vector unsigned short, vector unsigned short); 13227int vec_any_gt (vector bool short, vector signed short); 13228int vec_any_gt (vector signed short, vector bool short); 13229int vec_any_gt (vector signed short, vector signed short); 13230int vec_any_gt (vector bool int, vector unsigned int); 13231int vec_any_gt (vector unsigned int, vector bool int); 13232int vec_any_gt (vector unsigned int, vector unsigned int); 13233int vec_any_gt (vector bool int, vector signed int); 13234int vec_any_gt (vector signed int, vector bool int); 13235int vec_any_gt (vector signed int, vector signed int); 13236int vec_any_gt (vector float, vector float); 13237 13238int vec_any_le (vector bool char, vector unsigned char); 13239int vec_any_le (vector unsigned char, vector bool char); 13240int vec_any_le (vector unsigned char, vector unsigned char); 13241int vec_any_le (vector bool char, vector signed char); 13242int vec_any_le (vector signed char, vector bool char); 13243int vec_any_le (vector signed char, vector signed char); 13244int vec_any_le (vector bool short, vector unsigned short); 13245int vec_any_le (vector unsigned short, vector bool short); 13246int vec_any_le (vector unsigned short, vector unsigned short); 13247int vec_any_le (vector bool short, vector signed short); 13248int vec_any_le (vector signed short, vector bool short); 13249int vec_any_le (vector signed short, vector signed short); 13250int vec_any_le (vector bool int, vector unsigned int); 13251int vec_any_le (vector unsigned int, vector bool int); 13252int vec_any_le (vector unsigned int, vector unsigned int); 13253int vec_any_le (vector bool int, vector signed int); 13254int vec_any_le (vector signed int, vector bool int); 13255int vec_any_le (vector signed int, vector signed int); 13256int vec_any_le (vector float, vector float); 13257 13258int vec_any_lt (vector bool char, vector unsigned char); 13259int vec_any_lt (vector unsigned char, vector bool char); 13260int vec_any_lt (vector unsigned char, vector unsigned char); 13261int vec_any_lt (vector bool char, vector signed char); 13262int vec_any_lt (vector signed char, vector bool char); 13263int vec_any_lt (vector signed char, vector signed char); 13264int vec_any_lt (vector bool short, vector unsigned short); 13265int vec_any_lt (vector unsigned short, vector bool short); 13266int vec_any_lt (vector unsigned short, vector unsigned short); 13267int vec_any_lt (vector bool short, vector signed short); 13268int vec_any_lt (vector signed short, vector bool short); 13269int vec_any_lt (vector signed short, vector signed short); 13270int vec_any_lt (vector bool int, vector unsigned int); 13271int vec_any_lt (vector unsigned int, vector bool int); 13272int vec_any_lt (vector unsigned int, vector unsigned int); 13273int vec_any_lt (vector bool int, vector signed int); 13274int vec_any_lt (vector signed int, vector bool int); 13275int vec_any_lt (vector signed int, vector signed int); 13276int vec_any_lt (vector float, vector float); 13277 13278int vec_any_nan (vector float); 13279 13280int vec_any_ne (vector signed char, vector bool char); 13281int vec_any_ne (vector signed char, vector signed char); 13282int vec_any_ne (vector unsigned char, vector bool char); 13283int vec_any_ne (vector unsigned char, vector unsigned char); 13284int vec_any_ne (vector bool char, vector bool char); 13285int vec_any_ne (vector bool char, vector unsigned char); 13286int vec_any_ne (vector bool char, vector signed char); 13287int vec_any_ne (vector signed short, vector bool short); 13288int vec_any_ne (vector signed short, vector signed short); 13289int vec_any_ne (vector unsigned short, vector bool short); 13290int vec_any_ne (vector unsigned short, vector unsigned short); 13291int vec_any_ne (vector bool short, vector bool short); 13292int vec_any_ne (vector bool short, vector unsigned short); 13293int vec_any_ne (vector bool short, vector signed short); 13294int vec_any_ne (vector pixel, vector pixel); 13295int vec_any_ne (vector signed int, vector bool int); 13296int vec_any_ne (vector signed int, vector signed int); 13297int vec_any_ne (vector unsigned int, vector bool int); 13298int vec_any_ne (vector unsigned int, vector unsigned int); 13299int vec_any_ne (vector bool int, vector bool int); 13300int vec_any_ne (vector bool int, vector unsigned int); 13301int vec_any_ne (vector bool int, vector signed int); 13302int vec_any_ne (vector float, vector float); 13303 13304int vec_any_nge (vector float, vector float); 13305 13306int vec_any_ngt (vector float, vector float); 13307 13308int vec_any_nle (vector float, vector float); 13309 13310int vec_any_nlt (vector float, vector float); 13311 13312int vec_any_numeric (vector float); 13313 13314int vec_any_out (vector float, vector float); 13315@end smallexample 13316 13317If the vector/scalar (VSX) instruction set is available, the following 13318additional functions are available: 13319 13320@smallexample 13321vector double vec_abs (vector double); 13322vector double vec_add (vector double, vector double); 13323vector double vec_and (vector double, vector double); 13324vector double vec_and (vector double, vector bool long); 13325vector double vec_and (vector bool long, vector double); 13326vector double vec_andc (vector double, vector double); 13327vector double vec_andc (vector double, vector bool long); 13328vector double vec_andc (vector bool long, vector double); 13329vector double vec_ceil (vector double); 13330vector bool long vec_cmpeq (vector double, vector double); 13331vector bool long vec_cmpge (vector double, vector double); 13332vector bool long vec_cmpgt (vector double, vector double); 13333vector bool long vec_cmple (vector double, vector double); 13334vector bool long vec_cmplt (vector double, vector double); 13335vector float vec_div (vector float, vector float); 13336vector double vec_div (vector double, vector double); 13337vector double vec_floor (vector double); 13338vector double vec_ld (int, const vector double *); 13339vector double vec_ld (int, const double *); 13340vector double vec_ldl (int, const vector double *); 13341vector double vec_ldl (int, const double *); 13342vector unsigned char vec_lvsl (int, const volatile double *); 13343vector unsigned char vec_lvsr (int, const volatile double *); 13344vector double vec_madd (vector double, vector double, vector double); 13345vector double vec_max (vector double, vector double); 13346vector double vec_min (vector double, vector double); 13347vector float vec_msub (vector float, vector float, vector float); 13348vector double vec_msub (vector double, vector double, vector double); 13349vector float vec_mul (vector float, vector float); 13350vector double vec_mul (vector double, vector double); 13351vector float vec_nearbyint (vector float); 13352vector double vec_nearbyint (vector double); 13353vector float vec_nmadd (vector float, vector float, vector float); 13354vector double vec_nmadd (vector double, vector double, vector double); 13355vector double vec_nmsub (vector double, vector double, vector double); 13356vector double vec_nor (vector double, vector double); 13357vector double vec_or (vector double, vector double); 13358vector double vec_or (vector double, vector bool long); 13359vector double vec_or (vector bool long, vector double); 13360vector double vec_perm (vector double, 13361 vector double, 13362 vector unsigned char); 13363vector double vec_rint (vector double); 13364vector double vec_recip (vector double, vector double); 13365vector double vec_rsqrt (vector double); 13366vector double vec_rsqrte (vector double); 13367vector double vec_sel (vector double, vector double, vector bool long); 13368vector double vec_sel (vector double, vector double, vector unsigned long); 13369vector double vec_sub (vector double, vector double); 13370vector float vec_sqrt (vector float); 13371vector double vec_sqrt (vector double); 13372void vec_st (vector double, int, vector double *); 13373void vec_st (vector double, int, double *); 13374vector double vec_trunc (vector double); 13375vector double vec_xor (vector double, vector double); 13376vector double vec_xor (vector double, vector bool long); 13377vector double vec_xor (vector bool long, vector double); 13378int vec_all_eq (vector double, vector double); 13379int vec_all_ge (vector double, vector double); 13380int vec_all_gt (vector double, vector double); 13381int vec_all_le (vector double, vector double); 13382int vec_all_lt (vector double, vector double); 13383int vec_all_nan (vector double); 13384int vec_all_ne (vector double, vector double); 13385int vec_all_nge (vector double, vector double); 13386int vec_all_ngt (vector double, vector double); 13387int vec_all_nle (vector double, vector double); 13388int vec_all_nlt (vector double, vector double); 13389int vec_all_numeric (vector double); 13390int vec_any_eq (vector double, vector double); 13391int vec_any_ge (vector double, vector double); 13392int vec_any_gt (vector double, vector double); 13393int vec_any_le (vector double, vector double); 13394int vec_any_lt (vector double, vector double); 13395int vec_any_nan (vector double); 13396int vec_any_ne (vector double, vector double); 13397int vec_any_nge (vector double, vector double); 13398int vec_any_ngt (vector double, vector double); 13399int vec_any_nle (vector double, vector double); 13400int vec_any_nlt (vector double, vector double); 13401int vec_any_numeric (vector double); 13402 13403vector double vec_vsx_ld (int, const vector double *); 13404vector double vec_vsx_ld (int, const double *); 13405vector float vec_vsx_ld (int, const vector float *); 13406vector float vec_vsx_ld (int, const float *); 13407vector bool int vec_vsx_ld (int, const vector bool int *); 13408vector signed int vec_vsx_ld (int, const vector signed int *); 13409vector signed int vec_vsx_ld (int, const int *); 13410vector signed int vec_vsx_ld (int, const long *); 13411vector unsigned int vec_vsx_ld (int, const vector unsigned int *); 13412vector unsigned int vec_vsx_ld (int, const unsigned int *); 13413vector unsigned int vec_vsx_ld (int, const unsigned long *); 13414vector bool short vec_vsx_ld (int, const vector bool short *); 13415vector pixel vec_vsx_ld (int, const vector pixel *); 13416vector signed short vec_vsx_ld (int, const vector signed short *); 13417vector signed short vec_vsx_ld (int, const short *); 13418vector unsigned short vec_vsx_ld (int, const vector unsigned short *); 13419vector unsigned short vec_vsx_ld (int, const unsigned short *); 13420vector bool char vec_vsx_ld (int, const vector bool char *); 13421vector signed char vec_vsx_ld (int, const vector signed char *); 13422vector signed char vec_vsx_ld (int, const signed char *); 13423vector unsigned char vec_vsx_ld (int, const vector unsigned char *); 13424vector unsigned char vec_vsx_ld (int, const unsigned char *); 13425 13426void vec_vsx_st (vector double, int, vector double *); 13427void vec_vsx_st (vector double, int, double *); 13428void vec_vsx_st (vector float, int, vector float *); 13429void vec_vsx_st (vector float, int, float *); 13430void vec_vsx_st (vector signed int, int, vector signed int *); 13431void vec_vsx_st (vector signed int, int, int *); 13432void vec_vsx_st (vector unsigned int, int, vector unsigned int *); 13433void vec_vsx_st (vector unsigned int, int, unsigned int *); 13434void vec_vsx_st (vector bool int, int, vector bool int *); 13435void vec_vsx_st (vector bool int, int, unsigned int *); 13436void vec_vsx_st (vector bool int, int, int *); 13437void vec_vsx_st (vector signed short, int, vector signed short *); 13438void vec_vsx_st (vector signed short, int, short *); 13439void vec_vsx_st (vector unsigned short, int, vector unsigned short *); 13440void vec_vsx_st (vector unsigned short, int, unsigned short *); 13441void vec_vsx_st (vector bool short, int, vector bool short *); 13442void vec_vsx_st (vector bool short, int, unsigned short *); 13443void vec_vsx_st (vector pixel, int, vector pixel *); 13444void vec_vsx_st (vector pixel, int, unsigned short *); 13445void vec_vsx_st (vector pixel, int, short *); 13446void vec_vsx_st (vector bool short, int, short *); 13447void vec_vsx_st (vector signed char, int, vector signed char *); 13448void vec_vsx_st (vector signed char, int, signed char *); 13449void vec_vsx_st (vector unsigned char, int, vector unsigned char *); 13450void vec_vsx_st (vector unsigned char, int, unsigned char *); 13451void vec_vsx_st (vector bool char, int, vector bool char *); 13452void vec_vsx_st (vector bool char, int, unsigned char *); 13453void vec_vsx_st (vector bool char, int, signed char *); 13454@end smallexample 13455 13456Note that the @samp{vec_ld} and @samp{vec_st} builtins will always 13457generate the Altivec @samp{LVX} and @samp{STVX} instructions even 13458if the VSX instruction set is available. The @samp{vec_vsx_ld} and 13459@samp{vec_vsx_st} builtins will always generate the VSX @samp{LXVD2X}, 13460@samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions. 13461 13462GCC provides a few other builtins on Powerpc to access certain instructions: 13463@smallexample 13464float __builtin_recipdivf (float, float); 13465float __builtin_rsqrtf (float); 13466double __builtin_recipdiv (double, double); 13467double __builtin_rsqrt (double); 13468long __builtin_bpermd (long, long); 13469int __builtin_bswap16 (int); 13470@end smallexample 13471 13472The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and 13473@code{__builtin_rsqrtf} functions generate multiple instructions to 13474implement the reciprocal sqrt functionality using reciprocal sqrt 13475estimate instructions. 13476 13477The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf} 13478functions generate multiple instructions to implement division using 13479the reciprocal estimate instructions. 13480 13481@node RX Built-in Functions 13482@subsection RX Built-in Functions 13483GCC supports some of the RX instructions which cannot be expressed in 13484the C programming language via the use of built-in functions. The 13485following functions are supported: 13486 13487@deftypefn {Built-in Function} void __builtin_rx_brk (void) 13488Generates the @code{brk} machine instruction. 13489@end deftypefn 13490 13491@deftypefn {Built-in Function} void __builtin_rx_clrpsw (int) 13492Generates the @code{clrpsw} machine instruction to clear the specified 13493bit in the processor status word. 13494@end deftypefn 13495 13496@deftypefn {Built-in Function} void __builtin_rx_int (int) 13497Generates the @code{int} machine instruction to generate an interrupt 13498with the specified value. 13499@end deftypefn 13500 13501@deftypefn {Built-in Function} void __builtin_rx_machi (int, int) 13502Generates the @code{machi} machine instruction to add the result of 13503multiplying the top 16-bits of the two arguments into the 13504accumulator. 13505@end deftypefn 13506 13507@deftypefn {Built-in Function} void __builtin_rx_maclo (int, int) 13508Generates the @code{maclo} machine instruction to add the result of 13509multiplying the bottom 16-bits of the two arguments into the 13510accumulator. 13511@end deftypefn 13512 13513@deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int) 13514Generates the @code{mulhi} machine instruction to place the result of 13515multiplying the top 16-bits of the two arguments into the 13516accumulator. 13517@end deftypefn 13518 13519@deftypefn {Built-in Function} void __builtin_rx_mullo (int, int) 13520Generates the @code{mullo} machine instruction to place the result of 13521multiplying the bottom 16-bits of the two arguments into the 13522accumulator. 13523@end deftypefn 13524 13525@deftypefn {Built-in Function} int __builtin_rx_mvfachi (void) 13526Generates the @code{mvfachi} machine instruction to read the top 1352732-bits of the accumulator. 13528@end deftypefn 13529 13530@deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void) 13531Generates the @code{mvfacmi} machine instruction to read the middle 1353232-bits of the accumulator. 13533@end deftypefn 13534 13535@deftypefn {Built-in Function} int __builtin_rx_mvfc (int) 13536Generates the @code{mvfc} machine instruction which reads the control 13537register specified in its argument and returns its value. 13538@end deftypefn 13539 13540@deftypefn {Built-in Function} void __builtin_rx_mvtachi (int) 13541Generates the @code{mvtachi} machine instruction to set the top 1354232-bits of the accumulator. 13543@end deftypefn 13544 13545@deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int) 13546Generates the @code{mvtaclo} machine instruction to set the bottom 1354732-bits of the accumulator. 13548@end deftypefn 13549 13550@deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val) 13551Generates the @code{mvtc} machine instruction which sets control 13552register number @code{reg} to @code{val}. 13553@end deftypefn 13554 13555@deftypefn {Built-in Function} void __builtin_rx_mvtipl (int) 13556Generates the @code{mvtipl} machine instruction set the interrupt 13557priority level. 13558@end deftypefn 13559 13560@deftypefn {Built-in Function} void __builtin_rx_racw (int) 13561Generates the @code{racw} machine instruction to round the accumulator 13562according to the specified mode. 13563@end deftypefn 13564 13565@deftypefn {Built-in Function} int __builtin_rx_revw (int) 13566Generates the @code{revw} machine instruction which swaps the bytes in 13567the argument so that bits 0--7 now occupy bits 8--15 and vice versa, 13568and also bits 16--23 occupy bits 24--31 and vice versa. 13569@end deftypefn 13570 13571@deftypefn {Built-in Function} void __builtin_rx_rmpa (void) 13572Generates the @code{rmpa} machine instruction which initiates a 13573repeated multiply and accumulate sequence. 13574@end deftypefn 13575 13576@deftypefn {Built-in Function} void __builtin_rx_round (float) 13577Generates the @code{round} machine instruction which returns the 13578floating point argument rounded according to the current rounding mode 13579set in the floating point status word register. 13580@end deftypefn 13581 13582@deftypefn {Built-in Function} int __builtin_rx_sat (int) 13583Generates the @code{sat} machine instruction which returns the 13584saturated value of the argument. 13585@end deftypefn 13586 13587@deftypefn {Built-in Function} void __builtin_rx_setpsw (int) 13588Generates the @code{setpsw} machine instruction to set the specified 13589bit in the processor status word. 13590@end deftypefn 13591 13592@deftypefn {Built-in Function} void __builtin_rx_wait (void) 13593Generates the @code{wait} machine instruction. 13594@end deftypefn 13595 13596@node SPARC VIS Built-in Functions 13597@subsection SPARC VIS Built-in Functions 13598 13599GCC supports SIMD operations on the SPARC using both the generic vector 13600extensions (@pxref{Vector Extensions}) as well as built-in functions for 13601the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} 13602switch, the VIS extension is exposed as the following built-in functions: 13603 13604@smallexample 13605typedef int v1si __attribute__ ((vector_size (4))); 13606typedef int v2si __attribute__ ((vector_size (8))); 13607typedef short v4hi __attribute__ ((vector_size (8))); 13608typedef short v2hi __attribute__ ((vector_size (4))); 13609typedef unsigned char v8qi __attribute__ ((vector_size (8))); 13610typedef unsigned char v4qi __attribute__ ((vector_size (4))); 13611 13612void __builtin_vis_write_gsr (int64_t); 13613int64_t __builtin_vis_read_gsr (void); 13614 13615void * __builtin_vis_alignaddr (void *, long); 13616void * __builtin_vis_alignaddrl (void *, long); 13617int64_t __builtin_vis_faligndatadi (int64_t, int64_t); 13618v2si __builtin_vis_faligndatav2si (v2si, v2si); 13619v4hi __builtin_vis_faligndatav4hi (v4si, v4si); 13620v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); 13621 13622v4hi __builtin_vis_fexpand (v4qi); 13623 13624v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); 13625v4hi __builtin_vis_fmul8x16au (v4qi, v2hi); 13626v4hi __builtin_vis_fmul8x16al (v4qi, v2hi); 13627v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); 13628v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); 13629v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); 13630v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); 13631 13632v4qi __builtin_vis_fpack16 (v4hi); 13633v8qi __builtin_vis_fpack32 (v2si, v8qi); 13634v2hi __builtin_vis_fpackfix (v2si); 13635v8qi __builtin_vis_fpmerge (v4qi, v4qi); 13636 13637int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); 13638 13639long __builtin_vis_edge8 (void *, void *); 13640long __builtin_vis_edge8l (void *, void *); 13641long __builtin_vis_edge16 (void *, void *); 13642long __builtin_vis_edge16l (void *, void *); 13643long __builtin_vis_edge32 (void *, void *); 13644long __builtin_vis_edge32l (void *, void *); 13645 13646long __builtin_vis_fcmple16 (v4hi, v4hi); 13647long __builtin_vis_fcmple32 (v2si, v2si); 13648long __builtin_vis_fcmpne16 (v4hi, v4hi); 13649long __builtin_vis_fcmpne32 (v2si, v2si); 13650long __builtin_vis_fcmpgt16 (v4hi, v4hi); 13651long __builtin_vis_fcmpgt32 (v2si, v2si); 13652long __builtin_vis_fcmpeq16 (v4hi, v4hi); 13653long __builtin_vis_fcmpeq32 (v2si, v2si); 13654 13655v4hi __builtin_vis_fpadd16 (v4hi, v4hi); 13656v2hi __builtin_vis_fpadd16s (v2hi, v2hi); 13657v2si __builtin_vis_fpadd32 (v2si, v2si); 13658v1si __builtin_vis_fpadd32s (v1si, v1si); 13659v4hi __builtin_vis_fpsub16 (v4hi, v4hi); 13660v2hi __builtin_vis_fpsub16s (v2hi, v2hi); 13661v2si __builtin_vis_fpsub32 (v2si, v2si); 13662v1si __builtin_vis_fpsub32s (v1si, v1si); 13663 13664long __builtin_vis_array8 (long, long); 13665long __builtin_vis_array16 (long, long); 13666long __builtin_vis_array32 (long, long); 13667@end smallexample 13668 13669When you use the @option{-mvis2} switch, the VIS version 2.0 built-in 13670functions also become available: 13671 13672@smallexample 13673long __builtin_vis_bmask (long, long); 13674int64_t __builtin_vis_bshuffledi (int64_t, int64_t); 13675v2si __builtin_vis_bshufflev2si (v2si, v2si); 13676v4hi __builtin_vis_bshufflev2si (v4hi, v4hi); 13677v8qi __builtin_vis_bshufflev2si (v8qi, v8qi); 13678 13679long __builtin_vis_edge8n (void *, void *); 13680long __builtin_vis_edge8ln (void *, void *); 13681long __builtin_vis_edge16n (void *, void *); 13682long __builtin_vis_edge16ln (void *, void *); 13683long __builtin_vis_edge32n (void *, void *); 13684long __builtin_vis_edge32ln (void *, void *); 13685@end smallexample 13686 13687When you use the @option{-mvis3} switch, the VIS version 3.0 built-in 13688functions also become available: 13689 13690@smallexample 13691void __builtin_vis_cmask8 (long); 13692void __builtin_vis_cmask16 (long); 13693void __builtin_vis_cmask32 (long); 13694 13695v4hi __builtin_vis_fchksm16 (v4hi, v4hi); 13696 13697v4hi __builtin_vis_fsll16 (v4hi, v4hi); 13698v4hi __builtin_vis_fslas16 (v4hi, v4hi); 13699v4hi __builtin_vis_fsrl16 (v4hi, v4hi); 13700v4hi __builtin_vis_fsra16 (v4hi, v4hi); 13701v2si __builtin_vis_fsll16 (v2si, v2si); 13702v2si __builtin_vis_fslas16 (v2si, v2si); 13703v2si __builtin_vis_fsrl16 (v2si, v2si); 13704v2si __builtin_vis_fsra16 (v2si, v2si); 13705 13706long __builtin_vis_pdistn (v8qi, v8qi); 13707 13708v4hi __builtin_vis_fmean16 (v4hi, v4hi); 13709 13710int64_t __builtin_vis_fpadd64 (int64_t, int64_t); 13711int64_t __builtin_vis_fpsub64 (int64_t, int64_t); 13712 13713v4hi __builtin_vis_fpadds16 (v4hi, v4hi); 13714v2hi __builtin_vis_fpadds16s (v2hi, v2hi); 13715v4hi __builtin_vis_fpsubs16 (v4hi, v4hi); 13716v2hi __builtin_vis_fpsubs16s (v2hi, v2hi); 13717v2si __builtin_vis_fpadds32 (v2si, v2si); 13718v1si __builtin_vis_fpadds32s (v1si, v1si); 13719v2si __builtin_vis_fpsubs32 (v2si, v2si); 13720v1si __builtin_vis_fpsubs32s (v1si, v1si); 13721 13722long __builtin_vis_fucmple8 (v8qi, v8qi); 13723long __builtin_vis_fucmpne8 (v8qi, v8qi); 13724long __builtin_vis_fucmpgt8 (v8qi, v8qi); 13725long __builtin_vis_fucmpeq8 (v8qi, v8qi); 13726 13727float __builtin_vis_fhadds (float, float); 13728double __builtin_vis_fhaddd (double, double); 13729float __builtin_vis_fhsubs (float, float); 13730double __builtin_vis_fhsubd (double, double); 13731float __builtin_vis_fnhadds (float, float); 13732double __builtin_vis_fnhaddd (double, double); 13733 13734int64_t __builtin_vis_umulxhi (int64_t, int64_t); 13735int64_t __builtin_vis_xmulx (int64_t, int64_t); 13736int64_t __builtin_vis_xmulxhi (int64_t, int64_t); 13737@end smallexample 13738 13739@node SPU Built-in Functions 13740@subsection SPU Built-in Functions 13741 13742GCC provides extensions for the SPU processor as described in the 13743Sony/Toshiba/IBM SPU Language Extensions Specification, which can be 13744found at @uref{http://cell.scei.co.jp/} or 13745@uref{http://www.ibm.com/developerworks/power/cell/}. GCC's 13746implementation differs in several ways. 13747 13748@itemize @bullet 13749 13750@item 13751The optional extension of specifying vector constants in parentheses is 13752not supported. 13753 13754@item 13755A vector initializer requires no cast if the vector constant is of the 13756same type as the variable it is initializing. 13757 13758@item 13759If @code{signed} or @code{unsigned} is omitted, the signedness of the 13760vector type is the default signedness of the base type. The default 13761varies depending on the operating system, so a portable program should 13762always specify the signedness. 13763 13764@item 13765By default, the keyword @code{__vector} is added. The macro 13766@code{vector} is defined in @code{<spu_intrinsics.h>} and can be 13767undefined. 13768 13769@item 13770GCC allows using a @code{typedef} name as the type specifier for a 13771vector type. 13772 13773@item 13774For C, overloaded functions are implemented with macros so the following 13775does not work: 13776 13777@smallexample 13778 spu_add ((vector signed int)@{1, 2, 3, 4@}, foo); 13779@end smallexample 13780 13781Since @code{spu_add} is a macro, the vector constant in the example 13782is treated as four separate arguments. Wrap the entire argument in 13783parentheses for this to work. 13784 13785@item 13786The extended version of @code{__builtin_expect} is not supported. 13787 13788@end itemize 13789 13790@emph{Note:} Only the interface described in the aforementioned 13791specification is supported. Internally, GCC uses built-in functions to 13792implement the required functionality, but these are not supported and 13793are subject to change without notice. 13794 13795@node TI C6X Built-in Functions 13796@subsection TI C6X Built-in Functions 13797 13798GCC provides intrinsics to access certain instructions of the TI C6X 13799processors. These intrinsics, listed below, are available after 13800inclusion of the @code{c6x_intrinsics.h} header file. They map directly 13801to C6X instructions. 13802 13803@smallexample 13804 13805int _sadd (int, int) 13806int _ssub (int, int) 13807int _sadd2 (int, int) 13808int _ssub2 (int, int) 13809long long _mpy2 (int, int) 13810long long _smpy2 (int, int) 13811int _add4 (int, int) 13812int _sub4 (int, int) 13813int _saddu4 (int, int) 13814 13815int _smpy (int, int) 13816int _smpyh (int, int) 13817int _smpyhl (int, int) 13818int _smpylh (int, int) 13819 13820int _sshl (int, int) 13821int _subc (int, int) 13822 13823int _avg2 (int, int) 13824int _avgu4 (int, int) 13825 13826int _clrr (int, int) 13827int _extr (int, int) 13828int _extru (int, int) 13829int _abs (int) 13830int _abs2 (int) 13831 13832@end smallexample 13833 13834@node TILE-Gx Built-in Functions 13835@subsection TILE-Gx Built-in Functions 13836 13837GCC provides intrinsics to access every instruction of the TILE-Gx 13838processor. The intrinsics are of the form: 13839 13840@smallexample 13841 13842unsigned long long __insn_@var{op} (...) 13843 13844@end smallexample 13845 13846Where @var{op} is the name of the instruction. Refer to the ISA manual 13847for the complete list of instructions. 13848 13849GCC also provides intrinsics to directly access the network registers. 13850The intrinsics are: 13851 13852@smallexample 13853 13854unsigned long long __tile_idn0_receive (void) 13855unsigned long long __tile_idn1_receive (void) 13856unsigned long long __tile_udn0_receive (void) 13857unsigned long long __tile_udn1_receive (void) 13858unsigned long long __tile_udn2_receive (void) 13859unsigned long long __tile_udn3_receive (void) 13860void __tile_idn_send (unsigned long long) 13861void __tile_udn_send (unsigned long long) 13862 13863@end smallexample 13864 13865The intrinsic @code{void __tile_network_barrier (void)} is used to 13866guarantee that no network operatons before it will be reordered with 13867those after it. 13868 13869@node TILEPro Built-in Functions 13870@subsection TILEPro Built-in Functions 13871 13872GCC provides intrinsics to access every instruction of the TILEPro 13873processor. The intrinsics are of the form: 13874 13875@smallexample 13876 13877unsigned __insn_@var{op} (...) 13878 13879@end smallexample 13880 13881Where @var{op} is the name of the instruction. Refer to the ISA manual 13882for the complete list of instructions. 13883 13884GCC also provides intrinsics to directly access the network registers. 13885The intrinsics are: 13886 13887@smallexample 13888 13889unsigned __tile_idn0_receive (void) 13890unsigned __tile_idn1_receive (void) 13891unsigned __tile_sn_receive (void) 13892unsigned __tile_udn0_receive (void) 13893unsigned __tile_udn1_receive (void) 13894unsigned __tile_udn2_receive (void) 13895unsigned __tile_udn3_receive (void) 13896void __tile_idn_send (unsigned) 13897void __tile_sn_send (unsigned) 13898void __tile_udn_send (unsigned) 13899 13900@end smallexample 13901 13902The intrinsic @code{void __tile_network_barrier (void)} is used to 13903guarantee that no network operatons before it will be reordered with 13904those after it. 13905 13906@node Target Format Checks 13907@section Format Checks Specific to Particular Target Machines 13908 13909For some target machines, GCC supports additional options to the 13910format attribute 13911(@pxref{Function Attributes,,Declaring Attributes of Functions}). 13912 13913@menu 13914* Solaris Format Checks:: 13915* Darwin Format Checks:: 13916@end menu 13917 13918@node Solaris Format Checks 13919@subsection Solaris Format Checks 13920 13921Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format 13922check. @code{cmn_err} accepts a subset of the standard @code{printf} 13923conversions, and the two-argument @code{%b} conversion for displaying 13924bit-fields. See the Solaris man page for @code{cmn_err} for more information. 13925 13926@node Darwin Format Checks 13927@subsection Darwin Format Checks 13928 13929Darwin targets support the @code{CFString} (or @code{__CFString__}) in the format 13930attribute context. Declarations made with such attribution will be parsed for correct syntax 13931and format argument types. However, parsing of the format string itself is currently undefined 13932and will not be carried out by this version of the compiler. 13933 13934Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may 13935also be used as format arguments. Note that the relevant headers are only likely to be 13936available on Darwin (OSX) installations. On such installations, the XCode and system 13937documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and 13938associated functions. 13939 13940@node Pragmas 13941@section Pragmas Accepted by GCC 13942@cindex pragmas 13943@cindex @code{#pragma} 13944 13945GCC supports several types of pragmas, primarily in order to compile 13946code originally written for other compilers. Note that in general 13947we do not recommend the use of pragmas; @xref{Function Attributes}, 13948for further explanation. 13949 13950@menu 13951* ARM Pragmas:: 13952* M32C Pragmas:: 13953* MeP Pragmas:: 13954* RS/6000 and PowerPC Pragmas:: 13955* Darwin Pragmas:: 13956* Solaris Pragmas:: 13957* Symbol-Renaming Pragmas:: 13958* Structure-Packing Pragmas:: 13959* Weak Pragmas:: 13960* Diagnostic Pragmas:: 13961* Visibility Pragmas:: 13962* Push/Pop Macro Pragmas:: 13963* Function Specific Option Pragmas:: 13964@end menu 13965 13966@node ARM Pragmas 13967@subsection ARM Pragmas 13968 13969The ARM target defines pragmas for controlling the default addition of 13970@code{long_call} and @code{short_call} attributes to functions. 13971@xref{Function Attributes}, for information about the effects of these 13972attributes. 13973 13974@table @code 13975@item long_calls 13976@cindex pragma, long_calls 13977Set all subsequent functions to have the @code{long_call} attribute. 13978 13979@item no_long_calls 13980@cindex pragma, no_long_calls 13981Set all subsequent functions to have the @code{short_call} attribute. 13982 13983@item long_calls_off 13984@cindex pragma, long_calls_off 13985Do not affect the @code{long_call} or @code{short_call} attributes of 13986subsequent functions. 13987@end table 13988 13989@node M32C Pragmas 13990@subsection M32C Pragmas 13991 13992@table @code 13993@item GCC memregs @var{number} 13994@cindex pragma, memregs 13995Overrides the command-line option @code{-memregs=} for the current 13996file. Use with care! This pragma must be before any function in the 13997file, and mixing different memregs values in different objects may 13998make them incompatible. This pragma is useful when a 13999performance-critical function uses a memreg for temporary values, 14000as it may allow you to reduce the number of memregs used. 14001 14002@item ADDRESS @var{name} @var{address} 14003@cindex pragma, address 14004For any declared symbols matching @var{name}, this does three things 14005to that symbol: it forces the symbol to be located at the given 14006address (a number), it forces the symbol to be volatile, and it 14007changes the symbol's scope to be static. This pragma exists for 14008compatibility with other compilers, but note that the common 14009@code{1234H} numeric syntax is not supported (use @code{0x1234} 14010instead). Example: 14011 14012@example 14013#pragma ADDRESS port3 0x103 14014char port3; 14015@end example 14016 14017@end table 14018 14019@node MeP Pragmas 14020@subsection MeP Pragmas 14021 14022@table @code 14023 14024@item custom io_volatile (on|off) 14025@cindex pragma, custom io_volatile 14026Overrides the command line option @code{-mio-volatile} for the current 14027file. Note that for compatibility with future GCC releases, this 14028option should only be used once before any @code{io} variables in each 14029file. 14030 14031@item GCC coprocessor available @var{registers} 14032@cindex pragma, coprocessor available 14033Specifies which coprocessor registers are available to the register 14034allocator. @var{registers} may be a single register, register range 14035separated by ellipses, or comma-separated list of those. Example: 14036 14037@example 14038#pragma GCC coprocessor available $c0...$c10, $c28 14039@end example 14040 14041@item GCC coprocessor call_saved @var{registers} 14042@cindex pragma, coprocessor call_saved 14043Specifies which coprocessor registers are to be saved and restored by 14044any function using them. @var{registers} may be a single register, 14045register range separated by ellipses, or comma-separated list of 14046those. Example: 14047 14048@example 14049#pragma GCC coprocessor call_saved $c4...$c6, $c31 14050@end example 14051 14052@item GCC coprocessor subclass '(A|B|C|D)' = @var{registers} 14053@cindex pragma, coprocessor subclass 14054Creates and defines a register class. These register classes can be 14055used by inline @code{asm} constructs. @var{registers} may be a single 14056register, register range separated by ellipses, or comma-separated 14057list of those. Example: 14058 14059@example 14060#pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6 14061 14062asm ("cpfoo %0" : "=B" (x)); 14063@end example 14064 14065@item GCC disinterrupt @var{name} , @var{name} @dots{} 14066@cindex pragma, disinterrupt 14067For the named functions, the compiler adds code to disable interrupts 14068for the duration of those functions. Any functions so named, which 14069are not encountered in the source, cause a warning that the pragma was 14070not used. Examples: 14071 14072@example 14073#pragma disinterrupt foo 14074#pragma disinterrupt bar, grill 14075int foo () @{ @dots{} @} 14076@end example 14077 14078@item GCC call @var{name} , @var{name} @dots{} 14079@cindex pragma, call 14080For the named functions, the compiler always uses a register-indirect 14081call model when calling the named functions. Examples: 14082 14083@example 14084extern int foo (); 14085#pragma call foo 14086@end example 14087 14088@end table 14089 14090@node RS/6000 and PowerPC Pragmas 14091@subsection RS/6000 and PowerPC Pragmas 14092 14093The RS/6000 and PowerPC targets define one pragma for controlling 14094whether or not the @code{longcall} attribute is added to function 14095declarations by default. This pragma overrides the @option{-mlongcall} 14096option, but not the @code{longcall} and @code{shortcall} attributes. 14097@xref{RS/6000 and PowerPC Options}, for more information about when long 14098calls are and are not necessary. 14099 14100@table @code 14101@item longcall (1) 14102@cindex pragma, longcall 14103Apply the @code{longcall} attribute to all subsequent function 14104declarations. 14105 14106@item longcall (0) 14107Do not apply the @code{longcall} attribute to subsequent function 14108declarations. 14109@end table 14110 14111@c Describe h8300 pragmas here. 14112@c Describe sh pragmas here. 14113@c Describe v850 pragmas here. 14114 14115@node Darwin Pragmas 14116@subsection Darwin Pragmas 14117 14118The following pragmas are available for all architectures running the 14119Darwin operating system. These are useful for compatibility with other 14120Mac OS compilers. 14121 14122@table @code 14123@item mark @var{tokens}@dots{} 14124@cindex pragma, mark 14125This pragma is accepted, but has no effect. 14126 14127@item options align=@var{alignment} 14128@cindex pragma, options align 14129This pragma sets the alignment of fields in structures. The values of 14130@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or 14131@code{power}, to emulate PowerPC alignment. Uses of this pragma nest 14132properly; to restore the previous setting, use @code{reset} for the 14133@var{alignment}. 14134 14135@item segment @var{tokens}@dots{} 14136@cindex pragma, segment 14137This pragma is accepted, but has no effect. 14138 14139@item unused (@var{var} [, @var{var}]@dots{}) 14140@cindex pragma, unused 14141This pragma declares variables to be possibly unused. GCC will not 14142produce warnings for the listed variables. The effect is similar to 14143that of the @code{unused} attribute, except that this pragma may appear 14144anywhere within the variables' scopes. 14145@end table 14146 14147@node Solaris Pragmas 14148@subsection Solaris Pragmas 14149 14150The Solaris target supports @code{#pragma redefine_extname} 14151(@pxref{Symbol-Renaming Pragmas}). It also supports additional 14152@code{#pragma} directives for compatibility with the system compiler. 14153 14154@table @code 14155@item align @var{alignment} (@var{variable} [, @var{variable}]...) 14156@cindex pragma, align 14157 14158Increase the minimum alignment of each @var{variable} to @var{alignment}. 14159This is the same as GCC's @code{aligned} attribute @pxref{Variable 14160Attributes}). Macro expansion occurs on the arguments to this pragma 14161when compiling C and Objective-C@. It does not currently occur when 14162compiling C++, but this is a bug which may be fixed in a future 14163release. 14164 14165@item fini (@var{function} [, @var{function}]...) 14166@cindex pragma, fini 14167 14168This pragma causes each listed @var{function} to be called after 14169main, or during shared module unloading, by adding a call to the 14170@code{.fini} section. 14171 14172@item init (@var{function} [, @var{function}]...) 14173@cindex pragma, init 14174 14175This pragma causes each listed @var{function} to be called during 14176initialization (before @code{main}) or during shared module loading, by 14177adding a call to the @code{.init} section. 14178 14179@end table 14180 14181@node Symbol-Renaming Pragmas 14182@subsection Symbol-Renaming Pragmas 14183 14184For compatibility with the Solaris and Tru64 UNIX system headers, GCC 14185supports two @code{#pragma} directives which change the name used in 14186assembly for a given declaration. @code{#pragma extern_prefix} is only 14187available on platforms whose system headers need it. To get this effect 14188on all platforms supported by GCC, use the asm labels extension (@pxref{Asm 14189Labels}). 14190 14191@table @code 14192@item redefine_extname @var{oldname} @var{newname} 14193@cindex pragma, redefine_extname 14194 14195This pragma gives the C function @var{oldname} the assembly symbol 14196@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} 14197will be defined if this pragma is available (currently on all platforms). 14198 14199@item extern_prefix @var{string} 14200@cindex pragma, extern_prefix 14201 14202This pragma causes all subsequent external function and variable 14203declarations to have @var{string} prepended to their assembly symbols. 14204This effect may be terminated with another @code{extern_prefix} pragma 14205whose argument is an empty string. The preprocessor macro 14206@code{__PRAGMA_EXTERN_PREFIX} will be defined if this pragma is 14207available (currently only on Tru64 UNIX)@. 14208@end table 14209 14210These pragmas and the asm labels extension interact in a complicated 14211manner. Here are some corner cases you may want to be aware of. 14212 14213@enumerate 14214@item Both pragmas silently apply only to declarations with external 14215linkage. Asm labels do not have this restriction. 14216 14217@item In C++, both pragmas silently apply only to declarations with 14218``C'' linkage. Again, asm labels do not have this restriction. 14219 14220@item If any of the three ways of changing the assembly name of a 14221declaration is applied to a declaration whose assembly name has 14222already been determined (either by a previous use of one of these 14223features, or because the compiler needed the assembly name in order to 14224generate code), and the new name is different, a warning issues and 14225the name does not change. 14226 14227@item The @var{oldname} used by @code{#pragma redefine_extname} is 14228always the C-language name. 14229 14230@item If @code{#pragma extern_prefix} is in effect, and a declaration 14231occurs with an asm label attached, the prefix is silently ignored for 14232that declaration. 14233 14234@item If @code{#pragma extern_prefix} and @code{#pragma redefine_extname} 14235apply to the same declaration, whichever triggered first wins, and a 14236warning issues if they contradict each other. (We would like to have 14237@code{#pragma redefine_extname} always win, for consistency with asm 14238labels, but if @code{#pragma extern_prefix} triggers first we have no 14239way of knowing that that happened.) 14240@end enumerate 14241 14242@node Structure-Packing Pragmas 14243@subsection Structure-Packing Pragmas 14244 14245For compatibility with Microsoft Windows compilers, GCC supports a 14246set of @code{#pragma} directives which change the maximum alignment of 14247members of structures (other than zero-width bitfields), unions, and 14248classes subsequently defined. The @var{n} value below always is required 14249to be a small power of two and specifies the new alignment in bytes. 14250 14251@enumerate 14252@item @code{#pragma pack(@var{n})} simply sets the new alignment. 14253@item @code{#pragma pack()} sets the alignment to the one that was in 14254effect when compilation started (see also command-line option 14255@option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). 14256@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment 14257setting on an internal stack and then optionally sets the new alignment. 14258@item @code{#pragma pack(pop)} restores the alignment setting to the one 14259saved at the top of the internal stack (and removes that stack entry). 14260Note that @code{#pragma pack([@var{n}])} does not influence this internal 14261stack; thus it is possible to have @code{#pragma pack(push)} followed by 14262multiple @code{#pragma pack(@var{n})} instances and finalized by a single 14263@code{#pragma pack(pop)}. 14264@end enumerate 14265 14266Some targets, e.g.@: i386 and powerpc, support the @code{ms_struct} 14267@code{#pragma} which lays out a structure as the documented 14268@code{__attribute__ ((ms_struct))}. 14269@enumerate 14270@item @code{#pragma ms_struct on} turns on the layout for structures 14271declared. 14272@item @code{#pragma ms_struct off} turns off the layout for structures 14273declared. 14274@item @code{#pragma ms_struct reset} goes back to the default layout. 14275@end enumerate 14276 14277@node Weak Pragmas 14278@subsection Weak Pragmas 14279 14280For compatibility with SVR4, GCC supports a set of @code{#pragma} 14281directives for declaring symbols to be weak, and defining weak 14282aliases. 14283 14284@table @code 14285@item #pragma weak @var{symbol} 14286@cindex pragma, weak 14287This pragma declares @var{symbol} to be weak, as if the declaration 14288had the attribute of the same name. The pragma may appear before 14289or after the declaration of @var{symbol}. It is not an error for 14290@var{symbol} to never be defined at all. 14291 14292@item #pragma weak @var{symbol1} = @var{symbol2} 14293This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. 14294It is an error if @var{symbol2} is not defined in the current 14295translation unit. 14296@end table 14297 14298@node Diagnostic Pragmas 14299@subsection Diagnostic Pragmas 14300 14301GCC allows the user to selectively enable or disable certain types of 14302diagnostics, and change the kind of the diagnostic. For example, a 14303project's policy might require that all sources compile with 14304@option{-Werror} but certain files might have exceptions allowing 14305specific types of warnings. Or, a project might selectively enable 14306diagnostics and treat them as errors depending on which preprocessor 14307macros are defined. 14308 14309@table @code 14310@item #pragma GCC diagnostic @var{kind} @var{option} 14311@cindex pragma, diagnostic 14312 14313Modifies the disposition of a diagnostic. Note that not all 14314diagnostics are modifiable; at the moment only warnings (normally 14315controlled by @samp{-W@dots{}}) can be controlled, and not all of them. 14316Use @option{-fdiagnostics-show-option} to determine which diagnostics 14317are controllable and which option controls them. 14318 14319@var{kind} is @samp{error} to treat this diagnostic as an error, 14320@samp{warning} to treat it like a warning (even if @option{-Werror} is 14321in effect), or @samp{ignored} if the diagnostic is to be ignored. 14322@var{option} is a double quoted string which matches the command-line 14323option. 14324 14325@example 14326#pragma GCC diagnostic warning "-Wformat" 14327#pragma GCC diagnostic error "-Wformat" 14328#pragma GCC diagnostic ignored "-Wformat" 14329@end example 14330 14331Note that these pragmas override any command-line options. GCC keeps 14332track of the location of each pragma, and issues diagnostics according 14333to the state as of that point in the source file. Thus, pragmas occurring 14334after a line do not affect diagnostics caused by that line. 14335 14336@item #pragma GCC diagnostic push 14337@itemx #pragma GCC diagnostic pop 14338 14339Causes GCC to remember the state of the diagnostics as of each 14340@code{push}, and restore to that point at each @code{pop}. If a 14341@code{pop} has no matching @code{push}, the command line options are 14342restored. 14343 14344@example 14345#pragma GCC diagnostic error "-Wuninitialized" 14346 foo(a); /* error is given for this one */ 14347#pragma GCC diagnostic push 14348#pragma GCC diagnostic ignored "-Wuninitialized" 14349 foo(b); /* no diagnostic for this one */ 14350#pragma GCC diagnostic pop 14351 foo(c); /* error is given for this one */ 14352#pragma GCC diagnostic pop 14353 foo(d); /* depends on command line options */ 14354@end example 14355 14356@end table 14357 14358GCC also offers a simple mechanism for printing messages during 14359compilation. 14360 14361@table @code 14362@item #pragma message @var{string} 14363@cindex pragma, diagnostic 14364 14365Prints @var{string} as a compiler message on compilation. The message 14366is informational only, and is neither a compilation warning nor an error. 14367 14368@smallexample 14369#pragma message "Compiling " __FILE__ "..." 14370@end smallexample 14371 14372@var{string} may be parenthesized, and is printed with location 14373information. For example, 14374 14375@smallexample 14376#define DO_PRAGMA(x) _Pragma (#x) 14377#define TODO(x) DO_PRAGMA(message ("TODO - " #x)) 14378 14379TODO(Remember to fix this) 14380@end smallexample 14381 14382prints @samp{/tmp/file.c:4: note: #pragma message: 14383TODO - Remember to fix this}. 14384 14385@end table 14386 14387@node Visibility Pragmas 14388@subsection Visibility Pragmas 14389 14390@table @code 14391@item #pragma GCC visibility push(@var{visibility}) 14392@itemx #pragma GCC visibility pop 14393@cindex pragma, visibility 14394 14395This pragma allows the user to set the visibility for multiple 14396declarations without having to give each a visibility attribute 14397@xref{Function Attributes}, for more information about visibility and 14398the attribute syntax. 14399 14400In C++, @samp{#pragma GCC visibility} affects only namespace-scope 14401declarations. Class members and template specializations are not 14402affected; if you want to override the visibility for a particular 14403member or instantiation, you must use an attribute. 14404 14405@end table 14406 14407 14408@node Push/Pop Macro Pragmas 14409@subsection Push/Pop Macro Pragmas 14410 14411For compatibility with Microsoft Windows compilers, GCC supports 14412@samp{#pragma push_macro(@var{"macro_name"})} 14413and @samp{#pragma pop_macro(@var{"macro_name"})}. 14414 14415@table @code 14416@item #pragma push_macro(@var{"macro_name"}) 14417@cindex pragma, push_macro 14418This pragma saves the value of the macro named as @var{macro_name} to 14419the top of the stack for this macro. 14420 14421@item #pragma pop_macro(@var{"macro_name"}) 14422@cindex pragma, pop_macro 14423This pragma sets the value of the macro named as @var{macro_name} to 14424the value on top of the stack for this macro. If the stack for 14425@var{macro_name} is empty, the value of the macro remains unchanged. 14426@end table 14427 14428For example: 14429 14430@smallexample 14431#define X 1 14432#pragma push_macro("X") 14433#undef X 14434#define X -1 14435#pragma pop_macro("X") 14436int x [X]; 14437@end smallexample 14438 14439In this example, the definition of X as 1 is saved by @code{#pragma 14440push_macro} and restored by @code{#pragma pop_macro}. 14441 14442@node Function Specific Option Pragmas 14443@subsection Function Specific Option Pragmas 14444 14445@table @code 14446@item #pragma GCC target (@var{"string"}...) 14447@cindex pragma GCC target 14448 14449This pragma allows you to set target specific options for functions 14450defined later in the source file. One or more strings can be 14451specified. Each function that is defined after this point will be as 14452if @code{attribute((target("STRING")))} was specified for that 14453function. The parenthesis around the options is optional. 14454@xref{Function Attributes}, for more information about the 14455@code{target} attribute and the attribute syntax. 14456 14457The @code{#pragma GCC target} attribute is not implemented in GCC versions earlier 14458than 4.4 for the i386/x86_64 and 4.6 for the PowerPC backends. At 14459present, it is not implemented for other backends. 14460@end table 14461 14462@table @code 14463@item #pragma GCC optimize (@var{"string"}...) 14464@cindex pragma GCC optimize 14465 14466This pragma allows you to set global optimization options for functions 14467defined later in the source file. One or more strings can be 14468specified. Each function that is defined after this point will be as 14469if @code{attribute((optimize("STRING")))} was specified for that 14470function. The parenthesis around the options is optional. 14471@xref{Function Attributes}, for more information about the 14472@code{optimize} attribute and the attribute syntax. 14473 14474The @samp{#pragma GCC optimize} pragma is not implemented in GCC 14475versions earlier than 4.4. 14476@end table 14477 14478@table @code 14479@item #pragma GCC push_options 14480@itemx #pragma GCC pop_options 14481@cindex pragma GCC push_options 14482@cindex pragma GCC pop_options 14483 14484These pragmas maintain a stack of the current target and optimization 14485options. It is intended for include files where you temporarily want 14486to switch to using a different @samp{#pragma GCC target} or 14487@samp{#pragma GCC optimize} and then to pop back to the previous 14488options. 14489 14490The @samp{#pragma GCC push_options} and @samp{#pragma GCC pop_options} 14491pragmas are not implemented in GCC versions earlier than 4.4. 14492@end table 14493 14494@table @code 14495@item #pragma GCC reset_options 14496@cindex pragma GCC reset_options 14497 14498This pragma clears the current @code{#pragma GCC target} and 14499@code{#pragma GCC optimize} to use the default switches as specified 14500on the command line. 14501 14502The @samp{#pragma GCC reset_options} pragma is not implemented in GCC 14503versions earlier than 4.4. 14504@end table 14505 14506@node Unnamed Fields 14507@section Unnamed struct/union fields within structs/unions 14508@cindex @code{struct} 14509@cindex @code{union} 14510 14511As permitted by ISO C11 and for compatibility with other compilers, 14512GCC allows you to define 14513a structure or union that contains, as fields, structures and unions 14514without names. For example: 14515 14516@smallexample 14517struct @{ 14518 int a; 14519 union @{ 14520 int b; 14521 float c; 14522 @}; 14523 int d; 14524@} foo; 14525@end smallexample 14526 14527In this example, the user would be able to access members of the unnamed 14528union with code like @samp{foo.b}. Note that only unnamed structs and 14529unions are allowed, you may not have, for example, an unnamed 14530@code{int}. 14531 14532You must never create such structures that cause ambiguous field definitions. 14533For example, this structure: 14534 14535@smallexample 14536struct @{ 14537 int a; 14538 struct @{ 14539 int a; 14540 @}; 14541@} foo; 14542@end smallexample 14543 14544It is ambiguous which @code{a} is being referred to with @samp{foo.a}. 14545The compiler gives errors for such constructs. 14546 14547@opindex fms-extensions 14548Unless @option{-fms-extensions} is used, the unnamed field must be a 14549structure or union definition without a tag (for example, @samp{struct 14550@{ int a; @};}). If @option{-fms-extensions} is used, the field may 14551also be a definition with a tag such as @samp{struct foo @{ int a; 14552@};}, a reference to a previously defined structure or union such as 14553@samp{struct foo;}, or a reference to a @code{typedef} name for a 14554previously defined structure or union type. 14555 14556@opindex fplan9-extensions 14557The option @option{-fplan9-extensions} enables 14558@option{-fms-extensions} as well as two other extensions. First, a 14559pointer to a structure is automatically converted to a pointer to an 14560anonymous field for assignments and function calls. For example: 14561 14562@smallexample 14563struct s1 @{ int a; @}; 14564struct s2 @{ struct s1; @}; 14565extern void f1 (struct s1 *); 14566void f2 (struct s2 *p) @{ f1 (p); @} 14567@end smallexample 14568 14569In the call to @code{f1} inside @code{f2}, the pointer @code{p} is 14570converted into a pointer to the anonymous field. 14571 14572Second, when the type of an anonymous field is a @code{typedef} for a 14573@code{struct} or @code{union}, code may refer to the field using the 14574name of the @code{typedef}. 14575 14576@smallexample 14577typedef struct @{ int a; @} s1; 14578struct s2 @{ s1; @}; 14579s1 f1 (struct s2 *p) @{ return p->s1; @} 14580@end smallexample 14581 14582These usages are only permitted when they are not ambiguous. 14583 14584@node Thread-Local 14585@section Thread-Local Storage 14586@cindex Thread-Local Storage 14587@cindex @acronym{TLS} 14588@cindex @code{__thread} 14589 14590Thread-local storage (@acronym{TLS}) is a mechanism by which variables 14591are allocated such that there is one instance of the variable per extant 14592thread. The run-time model GCC uses to implement this originates 14593in the IA-64 processor-specific ABI, but has since been migrated 14594to other processors as well. It requires significant support from 14595the linker (@command{ld}), dynamic linker (@command{ld.so}), and 14596system libraries (@file{libc.so} and @file{libpthread.so}), so it 14597is not available everywhere. 14598 14599At the user level, the extension is visible with a new storage 14600class keyword: @code{__thread}. For example: 14601 14602@smallexample 14603__thread int i; 14604extern __thread struct state s; 14605static __thread char *p; 14606@end smallexample 14607 14608The @code{__thread} specifier may be used alone, with the @code{extern} 14609or @code{static} specifiers, but with no other storage class specifier. 14610When used with @code{extern} or @code{static}, @code{__thread} must appear 14611immediately after the other storage class specifier. 14612 14613The @code{__thread} specifier may be applied to any global, file-scoped 14614static, function-scoped static, or static data member of a class. It may 14615not be applied to block-scoped automatic or non-static data member. 14616 14617When the address-of operator is applied to a thread-local variable, it is 14618evaluated at run-time and returns the address of the current thread's 14619instance of that variable. An address so obtained may be used by any 14620thread. When a thread terminates, any pointers to thread-local variables 14621in that thread become invalid. 14622 14623No static initialization may refer to the address of a thread-local variable. 14624 14625In C++, if an initializer is present for a thread-local variable, it must 14626be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ 14627standard. 14628 14629See @uref{http://www.akkadia.org/drepper/tls.pdf, 14630ELF Handling For Thread-Local Storage} for a detailed explanation of 14631the four thread-local storage addressing models, and how the run-time 14632is expected to function. 14633 14634@menu 14635* C99 Thread-Local Edits:: 14636* C++98 Thread-Local Edits:: 14637@end menu 14638 14639@node C99 Thread-Local Edits 14640@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage 14641 14642The following are a set of changes to ISO/IEC 9899:1999 (aka C99) 14643that document the exact semantics of the language extension. 14644 14645@itemize @bullet 14646@item 14647@cite{5.1.2 Execution environments} 14648 14649Add new text after paragraph 1 14650 14651@quotation 14652Within either execution environment, a @dfn{thread} is a flow of 14653control within a program. It is implementation defined whether 14654or not there may be more than one thread associated with a program. 14655It is implementation defined how threads beyond the first are 14656created, the name and type of the function called at thread 14657startup, and how threads may be terminated. However, objects 14658with thread storage duration shall be initialized before thread 14659startup. 14660@end quotation 14661 14662@item 14663@cite{6.2.4 Storage durations of objects} 14664 14665Add new text before paragraph 3 14666 14667@quotation 14668An object whose identifier is declared with the storage-class 14669specifier @w{@code{__thread}} has @dfn{thread storage duration}. 14670Its lifetime is the entire execution of the thread, and its 14671stored value is initialized only once, prior to thread startup. 14672@end quotation 14673 14674@item 14675@cite{6.4.1 Keywords} 14676 14677Add @code{__thread}. 14678 14679@item 14680@cite{6.7.1 Storage-class specifiers} 14681 14682Add @code{__thread} to the list of storage class specifiers in 14683paragraph 1. 14684 14685Change paragraph 2 to 14686 14687@quotation 14688With the exception of @code{__thread}, at most one storage-class 14689specifier may be given [@dots{}]. The @code{__thread} specifier may 14690be used alone, or immediately following @code{extern} or 14691@code{static}. 14692@end quotation 14693 14694Add new text after paragraph 6 14695 14696@quotation 14697The declaration of an identifier for a variable that has 14698block scope that specifies @code{__thread} shall also 14699specify either @code{extern} or @code{static}. 14700 14701The @code{__thread} specifier shall be used only with 14702variables. 14703@end quotation 14704@end itemize 14705 14706@node C++98 Thread-Local Edits 14707@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage 14708 14709The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) 14710that document the exact semantics of the language extension. 14711 14712@itemize @bullet 14713@item 14714@b{[intro.execution]} 14715 14716New text after paragraph 4 14717 14718@quotation 14719A @dfn{thread} is a flow of control within the abstract machine. 14720It is implementation defined whether or not there may be more than 14721one thread. 14722@end quotation 14723 14724New text after paragraph 7 14725 14726@quotation 14727It is unspecified whether additional action must be taken to 14728ensure when and whether side effects are visible to other threads. 14729@end quotation 14730 14731@item 14732@b{[lex.key]} 14733 14734Add @code{__thread}. 14735 14736@item 14737@b{[basic.start.main]} 14738 14739Add after paragraph 5 14740 14741@quotation 14742The thread that begins execution at the @code{main} function is called 14743the @dfn{main thread}. It is implementation defined how functions 14744beginning threads other than the main thread are designated or typed. 14745A function so designated, as well as the @code{main} function, is called 14746a @dfn{thread startup function}. It is implementation defined what 14747happens if a thread startup function returns. It is implementation 14748defined what happens to other threads when any thread calls @code{exit}. 14749@end quotation 14750 14751@item 14752@b{[basic.start.init]} 14753 14754Add after paragraph 4 14755 14756@quotation 14757The storage for an object of thread storage duration shall be 14758statically initialized before the first statement of the thread startup 14759function. An object of thread storage duration shall not require 14760dynamic initialization. 14761@end quotation 14762 14763@item 14764@b{[basic.start.term]} 14765 14766Add after paragraph 3 14767 14768@quotation 14769The type of an object with thread storage duration shall not have a 14770non-trivial destructor, nor shall it be an array type whose elements 14771(directly or indirectly) have non-trivial destructors. 14772@end quotation 14773 14774@item 14775@b{[basic.stc]} 14776 14777Add ``thread storage duration'' to the list in paragraph 1. 14778 14779Change paragraph 2 14780 14781@quotation 14782Thread, static, and automatic storage durations are associated with 14783objects introduced by declarations [@dots{}]. 14784@end quotation 14785 14786Add @code{__thread} to the list of specifiers in paragraph 3. 14787 14788@item 14789@b{[basic.stc.thread]} 14790 14791New section before @b{[basic.stc.static]} 14792 14793@quotation 14794The keyword @code{__thread} applied to a non-local object gives the 14795object thread storage duration. 14796 14797A local variable or class data member declared both @code{static} 14798and @code{__thread} gives the variable or member thread storage 14799duration. 14800@end quotation 14801 14802@item 14803@b{[basic.stc.static]} 14804 14805Change paragraph 1 14806 14807@quotation 14808All objects which have neither thread storage duration, dynamic 14809storage duration nor are local [@dots{}]. 14810@end quotation 14811 14812@item 14813@b{[dcl.stc]} 14814 14815Add @code{__thread} to the list in paragraph 1. 14816 14817Change paragraph 1 14818 14819@quotation 14820With the exception of @code{__thread}, at most one 14821@var{storage-class-specifier} shall appear in a given 14822@var{decl-specifier-seq}. The @code{__thread} specifier may 14823be used alone, or immediately following the @code{extern} or 14824@code{static} specifiers. [@dots{}] 14825@end quotation 14826 14827Add after paragraph 5 14828 14829@quotation 14830The @code{__thread} specifier can be applied only to the names of objects 14831and to anonymous unions. 14832@end quotation 14833 14834@item 14835@b{[class.mem]} 14836 14837Add after paragraph 6 14838 14839@quotation 14840Non-@code{static} members shall not be @code{__thread}. 14841@end quotation 14842@end itemize 14843 14844@node Binary constants 14845@section Binary constants using the @samp{0b} prefix 14846@cindex Binary constants using the @samp{0b} prefix 14847 14848Integer constants can be written as binary constants, consisting of a 14849sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or 14850@samp{0B}. This is particularly useful in environments that operate a 14851lot on the bit-level (like microcontrollers). 14852 14853The following statements are identical: 14854 14855@smallexample 14856i = 42; 14857i = 0x2a; 14858i = 052; 14859i = 0b101010; 14860@end smallexample 14861 14862The type of these constants follows the same rules as for octal or 14863hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} 14864can be applied. 14865 14866@node C++ Extensions 14867@chapter Extensions to the C++ Language 14868@cindex extensions, C++ language 14869@cindex C++ language extensions 14870 14871The GNU compiler provides these extensions to the C++ language (and you 14872can also use most of the C language extensions in your C++ programs). If you 14873want to write code that checks whether these features are available, you can 14874test for the GNU compiler the same way as for C programs: check for a 14875predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to 14876test specifically for GNU C++ (@pxref{Common Predefined Macros,, 14877Predefined Macros,cpp,The GNU C Preprocessor}). 14878 14879@menu 14880* C++ Volatiles:: What constitutes an access to a volatile object. 14881* Restricted Pointers:: C99 restricted pointers and references. 14882* Vague Linkage:: Where G++ puts inlines, vtables and such. 14883* C++ Interface:: You can use a single C++ header file for both 14884 declarations and definitions. 14885* Template Instantiation:: Methods for ensuring that exactly one copy of 14886 each needed template instantiation is emitted. 14887* Bound member functions:: You can extract a function pointer to the 14888 method denoted by a @samp{->*} or @samp{.*} expression. 14889* C++ Attributes:: Variable, function, and type attributes for C++ only. 14890* Namespace Association:: Strong using-directives for namespace association. 14891* Type Traits:: Compiler support for type traits 14892* Java Exceptions:: Tweaking exception handling to work with Java. 14893* Deprecated Features:: Things will disappear from g++. 14894* Backwards Compatibility:: Compatibilities with earlier definitions of C++. 14895@end menu 14896 14897@node C++ Volatiles 14898@section When is a Volatile C++ Object Accessed? 14899@cindex accessing volatiles 14900@cindex volatile read 14901@cindex volatile write 14902@cindex volatile access 14903 14904The C++ standard differs from the C standard in its treatment of 14905volatile objects. It fails to specify what constitutes a volatile 14906access, except to say that C++ should behave in a similar manner to C 14907with respect to volatiles, where possible. However, the different 14908lvalueness of expressions between C and C++ complicate the behavior. 14909G++ behaves the same as GCC for volatile access, @xref{C 14910Extensions,,Volatiles}, for a description of GCC's behavior. 14911 14912The C and C++ language specifications differ when an object is 14913accessed in a void context: 14914 14915@smallexample 14916volatile int *src = @var{somevalue}; 14917*src; 14918@end smallexample 14919 14920The C++ standard specifies that such expressions do not undergo lvalue 14921to rvalue conversion, and that the type of the dereferenced object may 14922be incomplete. The C++ standard does not specify explicitly that it 14923is lvalue to rvalue conversion which is responsible for causing an 14924access. There is reason to believe that it is, because otherwise 14925certain simple expressions become undefined. However, because it 14926would surprise most programmers, G++ treats dereferencing a pointer to 14927volatile object of complete type as GCC would do for an equivalent 14928type in C@. When the object has incomplete type, G++ issues a 14929warning; if you wish to force an error, you must force a conversion to 14930rvalue with, for instance, a static cast. 14931 14932When using a reference to volatile, G++ does not treat equivalent 14933expressions as accesses to volatiles, but instead issues a warning that 14934no volatile is accessed. The rationale for this is that otherwise it 14935becomes difficult to determine where volatile access occur, and not 14936possible to ignore the return value from functions returning volatile 14937references. Again, if you wish to force a read, cast the reference to 14938an rvalue. 14939 14940G++ implements the same behavior as GCC does when assigning to a 14941volatile object -- there is no reread of the assigned-to object, the 14942assigned rvalue is reused. Note that in C++ assignment expressions 14943are lvalues, and if used as an lvalue, the volatile object will be 14944referred to. For instance, @var{vref} will refer to @var{vobj}, as 14945expected, in the following example: 14946 14947@smallexample 14948volatile int vobj; 14949volatile int &vref = vobj = @var{something}; 14950@end smallexample 14951 14952@node Restricted Pointers 14953@section Restricting Pointer Aliasing 14954@cindex restricted pointers 14955@cindex restricted references 14956@cindex restricted this pointer 14957 14958As with the C front end, G++ understands the C99 feature of restricted pointers, 14959specified with the @code{__restrict__}, or @code{__restrict} type 14960qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} 14961language flag, @code{restrict} is not a keyword in C++. 14962 14963In addition to allowing restricted pointers, you can specify restricted 14964references, which indicate that the reference is not aliased in the local 14965context. 14966 14967@smallexample 14968void fn (int *__restrict__ rptr, int &__restrict__ rref) 14969@{ 14970 /* @r{@dots{}} */ 14971@} 14972@end smallexample 14973 14974@noindent 14975In the body of @code{fn}, @var{rptr} points to an unaliased integer and 14976@var{rref} refers to a (different) unaliased integer. 14977 14978You may also specify whether a member function's @var{this} pointer is 14979unaliased by using @code{__restrict__} as a member function qualifier. 14980 14981@smallexample 14982void T::fn () __restrict__ 14983@{ 14984 /* @r{@dots{}} */ 14985@} 14986@end smallexample 14987 14988@noindent 14989Within the body of @code{T::fn}, @var{this} will have the effective 14990definition @code{T *__restrict__ const this}. Notice that the 14991interpretation of a @code{__restrict__} member function qualifier is 14992different to that of @code{const} or @code{volatile} qualifier, in that it 14993is applied to the pointer rather than the object. This is consistent with 14994other compilers which implement restricted pointers. 14995 14996As with all outermost parameter qualifiers, @code{__restrict__} is 14997ignored in function definition matching. This means you only need to 14998specify @code{__restrict__} in a function definition, rather than 14999in a function prototype as well. 15000 15001@node Vague Linkage 15002@section Vague Linkage 15003@cindex vague linkage 15004 15005There are several constructs in C++ which require space in the object 15006file but are not clearly tied to a single translation unit. We say that 15007these constructs have ``vague linkage''. Typically such constructs are 15008emitted wherever they are needed, though sometimes we can be more 15009clever. 15010 15011@table @asis 15012@item Inline Functions 15013Inline functions are typically defined in a header file which can be 15014included in many different compilations. Hopefully they can usually be 15015inlined, but sometimes an out-of-line copy is necessary, if the address 15016of the function is taken or if inlining fails. In general, we emit an 15017out-of-line copy in all translation units where one is needed. As an 15018exception, we only emit inline virtual functions with the vtable, since 15019it will always require a copy. 15020 15021Local static variables and string constants used in an inline function 15022are also considered to have vague linkage, since they must be shared 15023between all inlined and out-of-line instances of the function. 15024 15025@item VTables 15026@cindex vtable 15027C++ virtual functions are implemented in most compilers using a lookup 15028table, known as a vtable. The vtable contains pointers to the virtual 15029functions provided by a class, and each object of the class contains a 15030pointer to its vtable (or vtables, in some multiple-inheritance 15031situations). If the class declares any non-inline, non-pure virtual 15032functions, the first one is chosen as the ``key method'' for the class, 15033and the vtable is only emitted in the translation unit where the key 15034method is defined. 15035 15036@emph{Note:} If the chosen key method is later defined as inline, the 15037vtable will still be emitted in every translation unit which defines it. 15038Make sure that any inline virtuals are declared inline in the class 15039body, even if they are not defined there. 15040 15041@item @code{type_info} objects 15042@cindex @code{type_info} 15043@cindex RTTI 15044C++ requires information about types to be written out in order to 15045implement @samp{dynamic_cast}, @samp{typeid} and exception handling. 15046For polymorphic classes (classes with virtual functions), the @samp{type_info} 15047object is written out along with the vtable so that @samp{dynamic_cast} 15048can determine the dynamic type of a class object at runtime. For all 15049other types, we write out the @samp{type_info} object when it is used: when 15050applying @samp{typeid} to an expression, throwing an object, or 15051referring to a type in a catch clause or exception specification. 15052 15053@item Template Instantiations 15054Most everything in this section also applies to template instantiations, 15055but there are other options as well. 15056@xref{Template Instantiation,,Where's the Template?}. 15057 15058@end table 15059 15060When used with GNU ld version 2.8 or later on an ELF system such as 15061GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of 15062these constructs will be discarded at link time. This is known as 15063COMDAT support. 15064 15065On targets that don't support COMDAT, but do support weak symbols, GCC 15066will use them. This way one copy will override all the others, but 15067the unused copies will still take up space in the executable. 15068 15069For targets which do not support either COMDAT or weak symbols, 15070most entities with vague linkage will be emitted as local symbols to 15071avoid duplicate definition errors from the linker. This will not happen 15072for local statics in inlines, however, as having multiple copies will 15073almost certainly break things. 15074 15075@xref{C++ Interface,,Declarations and Definitions in One Header}, for 15076another way to control placement of these constructs. 15077 15078@node C++ Interface 15079@section #pragma interface and implementation 15080 15081@cindex interface and implementation headers, C++ 15082@cindex C++ interface and implementation headers 15083@cindex pragmas, interface and implementation 15084 15085@code{#pragma interface} and @code{#pragma implementation} provide the 15086user with a way of explicitly directing the compiler to emit entities 15087with vague linkage (and debugging information) in a particular 15088translation unit. 15089 15090@emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in 15091most cases, because of COMDAT support and the ``key method'' heuristic 15092mentioned in @ref{Vague Linkage}. Using them can actually cause your 15093program to grow due to unnecessary out-of-line copies of inline 15094functions. Currently (3.4) the only benefit of these 15095@code{#pragma}s is reduced duplication of debugging information, and 15096that should be addressed soon on DWARF 2 targets with the use of 15097COMDAT groups. 15098 15099@table @code 15100@item #pragma interface 15101@itemx #pragma interface "@var{subdir}/@var{objects}.h" 15102@kindex #pragma interface 15103Use this directive in @emph{header files} that define object classes, to save 15104space in most of the object files that use those classes. Normally, 15105local copies of certain information (backup copies of inline member 15106functions, debugging information, and the internal tables that implement 15107virtual functions) must be kept in each object file that includes class 15108definitions. You can use this pragma to avoid such duplication. When a 15109header file containing @samp{#pragma interface} is included in a 15110compilation, this auxiliary information will not be generated (unless 15111the main input source file itself uses @samp{#pragma implementation}). 15112Instead, the object files will contain references to be resolved at link 15113time. 15114 15115The second form of this directive is useful for the case where you have 15116multiple headers with the same name in different directories. If you 15117use this form, you must specify the same string to @samp{#pragma 15118implementation}. 15119 15120@item #pragma implementation 15121@itemx #pragma implementation "@var{objects}.h" 15122@kindex #pragma implementation 15123Use this pragma in a @emph{main input file}, when you want full output from 15124included header files to be generated (and made globally visible). The 15125included header file, in turn, should use @samp{#pragma interface}. 15126Backup copies of inline member functions, debugging information, and the 15127internal tables used to implement virtual functions are all generated in 15128implementation files. 15129 15130@cindex implied @code{#pragma implementation} 15131@cindex @code{#pragma implementation}, implied 15132@cindex naming convention, implementation headers 15133If you use @samp{#pragma implementation} with no argument, it applies to 15134an include file with the same basename@footnote{A file's @dfn{basename} 15135was the name stripped of all leading path information and of trailing 15136suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source 15137file. For example, in @file{allclass.cc}, giving just 15138@samp{#pragma implementation} 15139by itself is equivalent to @samp{#pragma implementation "allclass.h"}. 15140 15141In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as 15142an implementation file whenever you would include it from 15143@file{allclass.cc} even if you never specified @samp{#pragma 15144implementation}. This was deemed to be more trouble than it was worth, 15145however, and disabled. 15146 15147Use the string argument if you want a single implementation file to 15148include code from multiple header files. (You must also use 15149@samp{#include} to include the header file; @samp{#pragma 15150implementation} only specifies how to use the file---it doesn't actually 15151include it.) 15152 15153There is no way to split up the contents of a single header file into 15154multiple implementation files. 15155@end table 15156 15157@cindex inlining and C++ pragmas 15158@cindex C++ pragmas, effect on inlining 15159@cindex pragmas in C++, effect on inlining 15160@samp{#pragma implementation} and @samp{#pragma interface} also have an 15161effect on function inlining. 15162 15163If you define a class in a header file marked with @samp{#pragma 15164interface}, the effect on an inline function defined in that class is 15165similar to an explicit @code{extern} declaration---the compiler emits 15166no code at all to define an independent version of the function. Its 15167definition is used only for inlining with its callers. 15168 15169@opindex fno-implement-inlines 15170Conversely, when you include the same header file in a main source file 15171that declares it as @samp{#pragma implementation}, the compiler emits 15172code for the function itself; this defines a version of the function 15173that can be found via pointers (or by callers compiled without 15174inlining). If all calls to the function can be inlined, you can avoid 15175emitting the function by compiling with @option{-fno-implement-inlines}. 15176If any calls were not inlined, you will get linker errors. 15177 15178@node Template Instantiation 15179@section Where's the Template? 15180@cindex template instantiation 15181 15182C++ templates are the first language feature to require more 15183intelligence from the environment than one usually finds on a UNIX 15184system. Somehow the compiler and linker have to make sure that each 15185template instance occurs exactly once in the executable if it is needed, 15186and not at all otherwise. There are two basic approaches to this 15187problem, which are referred to as the Borland model and the Cfront model. 15188 15189@table @asis 15190@item Borland model 15191Borland C++ solved the template instantiation problem by adding the code 15192equivalent of common blocks to their linker; the compiler emits template 15193instances in each translation unit that uses them, and the linker 15194collapses them together. The advantage of this model is that the linker 15195only has to consider the object files themselves; there is no external 15196complexity to worry about. This disadvantage is that compilation time 15197is increased because the template code is being compiled repeatedly. 15198Code written for this model tends to include definitions of all 15199templates in the header file, since they must be seen to be 15200instantiated. 15201 15202@item Cfront model 15203The AT&T C++ translator, Cfront, solved the template instantiation 15204problem by creating the notion of a template repository, an 15205automatically maintained place where template instances are stored. A 15206more modern version of the repository works as follows: As individual 15207object files are built, the compiler places any template definitions and 15208instantiations encountered in the repository. At link time, the link 15209wrapper adds in the objects in the repository and compiles any needed 15210instances that were not previously emitted. The advantages of this 15211model are more optimal compilation speed and the ability to use the 15212system linker; to implement the Borland model a compiler vendor also 15213needs to replace the linker. The disadvantages are vastly increased 15214complexity, and thus potential for error; for some code this can be 15215just as transparent, but in practice it can been very difficult to build 15216multiple programs in one directory and one program in multiple 15217directories. Code written for this model tends to separate definitions 15218of non-inline member templates into a separate file, which should be 15219compiled separately. 15220@end table 15221 15222When used with GNU ld version 2.8 or later on an ELF system such as 15223GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the 15224Borland model. On other systems, G++ implements neither automatic 15225model. 15226 15227A future version of G++ will support a hybrid model whereby the compiler 15228will emit any instantiations for which the template definition is 15229included in the compile, and store template definitions and 15230instantiation context information into the object file for the rest. 15231The link wrapper will extract that information as necessary and invoke 15232the compiler to produce the remaining instantiations. The linker will 15233then combine duplicate instantiations. 15234 15235In the mean time, you have the following options for dealing with 15236template instantiations: 15237 15238@enumerate 15239@item 15240@opindex frepo 15241Compile your template-using code with @option{-frepo}. The compiler will 15242generate files with the extension @samp{.rpo} listing all of the 15243template instantiations used in the corresponding object files which 15244could be instantiated there; the link wrapper, @samp{collect2}, will 15245then update the @samp{.rpo} files to tell the compiler where to place 15246those instantiations and rebuild any affected object files. The 15247link-time overhead is negligible after the first pass, as the compiler 15248will continue to place the instantiations in the same files. 15249 15250This is your best option for application code written for the Borland 15251model, as it will just work. Code written for the Cfront model will 15252need to be modified so that the template definitions are available at 15253one or more points of instantiation; usually this is as simple as adding 15254@code{#include <tmethods.cc>} to the end of each template header. 15255 15256For library code, if you want the library to provide all of the template 15257instantiations it needs, just try to link all of its object files 15258together; the link will fail, but cause the instantiations to be 15259generated as a side effect. Be warned, however, that this may cause 15260conflicts if multiple libraries try to provide the same instantiations. 15261For greater control, use explicit instantiation as described in the next 15262option. 15263 15264@item 15265@opindex fno-implicit-templates 15266Compile your code with @option{-fno-implicit-templates} to disable the 15267implicit generation of template instances, and explicitly instantiate 15268all the ones you use. This approach requires more knowledge of exactly 15269which instances you need than do the others, but it's less 15270mysterious and allows greater control. You can scatter the explicit 15271instantiations throughout your program, perhaps putting them in the 15272translation units where the instances are used or the translation units 15273that define the templates themselves; you can put all of the explicit 15274instantiations you need into one big file; or you can create small files 15275like 15276 15277@smallexample 15278#include "Foo.h" 15279#include "Foo.cc" 15280 15281template class Foo<int>; 15282template ostream& operator << 15283 (ostream&, const Foo<int>&); 15284@end smallexample 15285 15286for each of the instances you need, and create a template instantiation 15287library from those. 15288 15289If you are using Cfront-model code, you can probably get away with not 15290using @option{-fno-implicit-templates} when compiling files that don't 15291@samp{#include} the member template definitions. 15292 15293If you use one big file to do the instantiations, you may want to 15294compile it without @option{-fno-implicit-templates} so you get all of the 15295instances required by your explicit instantiations (but not by any 15296other files) without having to specify them as well. 15297 15298G++ has extended the template instantiation syntax given in the ISO 15299standard to allow forward declaration of explicit instantiations 15300(with @code{extern}), instantiation of the compiler support data for a 15301template class (i.e.@: the vtable) without instantiating any of its 15302members (with @code{inline}), and instantiation of only the static data 15303members of a template class, without the support data or member 15304functions (with (@code{static}): 15305 15306@smallexample 15307extern template int max (int, int); 15308inline template class Foo<int>; 15309static template class Foo<int>; 15310@end smallexample 15311 15312@item 15313Do nothing. Pretend G++ does implement automatic instantiation 15314management. Code written for the Borland model will work fine, but 15315each translation unit will contain instances of each of the templates it 15316uses. In a large program, this can lead to an unacceptable amount of code 15317duplication. 15318@end enumerate 15319 15320@node Bound member functions 15321@section Extracting the function pointer from a bound pointer to member function 15322@cindex pmf 15323@cindex pointer to member function 15324@cindex bound pointer to member function 15325 15326In C++, pointer to member functions (PMFs) are implemented using a wide 15327pointer of sorts to handle all the possible call mechanisms; the PMF 15328needs to store information about how to adjust the @samp{this} pointer, 15329and if the function pointed to is virtual, where to find the vtable, and 15330where in the vtable to look for the member function. If you are using 15331PMFs in an inner loop, you should really reconsider that decision. If 15332that is not an option, you can extract the pointer to the function that 15333would be called for a given object/PMF pair and call it directly inside 15334the inner loop, to save a bit of time. 15335 15336Note that you will still be paying the penalty for the call through a 15337function pointer; on most modern architectures, such a call defeats the 15338branch prediction features of the CPU@. This is also true of normal 15339virtual function calls. 15340 15341The syntax for this extension is 15342 15343@smallexample 15344extern A a; 15345extern int (A::*fp)(); 15346typedef int (*fptr)(A *); 15347 15348fptr p = (fptr)(a.*fp); 15349@end smallexample 15350 15351For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), 15352no object is needed to obtain the address of the function. They can be 15353converted to function pointers directly: 15354 15355@smallexample 15356fptr p1 = (fptr)(&A::foo); 15357@end smallexample 15358 15359@opindex Wno-pmf-conversions 15360You must specify @option{-Wno-pmf-conversions} to use this extension. 15361 15362@node C++ Attributes 15363@section C++-Specific Variable, Function, and Type Attributes 15364 15365Some attributes only make sense for C++ programs. 15366 15367@table @code 15368@item init_priority (@var{priority}) 15369@cindex @code{init_priority} attribute 15370 15371 15372In Standard C++, objects defined at namespace scope are guaranteed to be 15373initialized in an order in strict accordance with that of their definitions 15374@emph{in a given translation unit}. No guarantee is made for initializations 15375across translation units. However, GNU C++ allows users to control the 15376order of initialization of objects defined at namespace scope with the 15377@code{init_priority} attribute by specifying a relative @var{priority}, 15378a constant integral expression currently bounded between 101 and 65535 15379inclusive. Lower numbers indicate a higher priority. 15380 15381In the following example, @code{A} would normally be created before 15382@code{B}, but the @code{init_priority} attribute has reversed that order: 15383 15384@smallexample 15385Some_Class A __attribute__ ((init_priority (2000))); 15386Some_Class B __attribute__ ((init_priority (543))); 15387@end smallexample 15388 15389@noindent 15390Note that the particular values of @var{priority} do not matter; only their 15391relative ordering. 15392 15393@item java_interface 15394@cindex @code{java_interface} attribute 15395 15396This type attribute informs C++ that the class is a Java interface. It may 15397only be applied to classes declared within an @code{extern "Java"} block. 15398Calls to methods declared in this interface will be dispatched using GCJ's 15399interface table mechanism, instead of regular virtual table dispatch. 15400 15401@end table 15402 15403See also @ref{Namespace Association}. 15404 15405@node Namespace Association 15406@section Namespace Association 15407 15408@strong{Caution:} The semantics of this extension are not fully 15409defined. Users should refrain from using this extension as its 15410semantics may change subtly over time. It is possible that this 15411extension will be removed in future versions of G++. 15412 15413A using-directive with @code{__attribute ((strong))} is stronger 15414than a normal using-directive in two ways: 15415 15416@itemize @bullet 15417@item 15418Templates from the used namespace can be specialized and explicitly 15419instantiated as though they were members of the using namespace. 15420 15421@item 15422The using namespace is considered an associated namespace of all 15423templates in the used namespace for purposes of argument-dependent 15424name lookup. 15425@end itemize 15426 15427The used namespace must be nested within the using namespace so that 15428normal unqualified lookup works properly. 15429 15430This is useful for composing a namespace transparently from 15431implementation namespaces. For example: 15432 15433@smallexample 15434namespace std @{ 15435 namespace debug @{ 15436 template <class T> struct A @{ @}; 15437 @} 15438 using namespace debug __attribute ((__strong__)); 15439 template <> struct A<int> @{ @}; // @r{ok to specialize} 15440 15441 template <class T> void f (A<T>); 15442@} 15443 15444int main() 15445@{ 15446 f (std::A<float>()); // @r{lookup finds} std::f 15447 f (std::A<int>()); 15448@} 15449@end smallexample 15450 15451@node Type Traits 15452@section Type Traits 15453 15454The C++ front-end implements syntactic extensions that allow to 15455determine at compile time various characteristics of a type (or of a 15456pair of types). 15457 15458@table @code 15459@item __has_nothrow_assign (type) 15460If @code{type} is const qualified or is a reference type then the trait is 15461false. Otherwise if @code{__has_trivial_assign (type)} is true then the trait 15462is true, else if @code{type} is a cv class or union type with copy assignment 15463operators that are known not to throw an exception then the trait is true, 15464else it is false. Requires: @code{type} shall be a complete type, 15465(possibly cv-qualified) @code{void}, or an array of unknown bound. 15466 15467@item __has_nothrow_copy (type) 15468If @code{__has_trivial_copy (type)} is true then the trait is true, else if 15469@code{type} is a cv class or union type with copy constructors that 15470are known not to throw an exception then the trait is true, else it is false. 15471Requires: @code{type} shall be a complete type, (possibly cv-qualified) 15472@code{void}, or an array of unknown bound. 15473 15474@item __has_nothrow_constructor (type) 15475If @code{__has_trivial_constructor (type)} is true then the trait is 15476true, else if @code{type} is a cv class or union type (or array 15477thereof) with a default constructor that is known not to throw an 15478exception then the trait is true, else it is false. Requires: 15479@code{type} shall be a complete type, (possibly cv-qualified) 15480@code{void}, or an array of unknown bound. 15481 15482@item __has_trivial_assign (type) 15483If @code{type} is const qualified or is a reference type then the trait is 15484false. Otherwise if @code{__is_pod (type)} is true then the trait is 15485true, else if @code{type} is a cv class or union type with a trivial 15486copy assignment ([class.copy]) then the trait is true, else it is 15487false. Requires: @code{type} shall be a complete type, (possibly 15488cv-qualified) @code{void}, or an array of unknown bound. 15489 15490@item __has_trivial_copy (type) 15491If @code{__is_pod (type)} is true or @code{type} is a reference type 15492then the trait is true, else if @code{type} is a cv class or union type 15493with a trivial copy constructor ([class.copy]) then the trait 15494is true, else it is false. Requires: @code{type} shall be a complete 15495type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 15496 15497@item __has_trivial_constructor (type) 15498If @code{__is_pod (type)} is true then the trait is true, else if 15499@code{type} is a cv class or union type (or array thereof) with a 15500trivial default constructor ([class.ctor]) then the trait is true, 15501else it is false. Requires: @code{type} shall be a complete 15502type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 15503 15504@item __has_trivial_destructor (type) 15505If @code{__is_pod (type)} is true or @code{type} is a reference type then 15506the trait is true, else if @code{type} is a cv class or union type (or 15507array thereof) with a trivial destructor ([class.dtor]) then the trait 15508is true, else it is false. Requires: @code{type} shall be a complete 15509type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 15510 15511@item __has_virtual_destructor (type) 15512If @code{type} is a class type with a virtual destructor 15513([class.dtor]) then the trait is true, else it is false. Requires: 15514@code{type} shall be a complete type, (possibly cv-qualified) 15515@code{void}, or an array of unknown bound. 15516 15517@item __is_abstract (type) 15518If @code{type} is an abstract class ([class.abstract]) then the trait 15519is true, else it is false. Requires: @code{type} shall be a complete 15520type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 15521 15522@item __is_base_of (base_type, derived_type) 15523If @code{base_type} is a base class of @code{derived_type} 15524([class.derived]) then the trait is true, otherwise it is false. 15525Top-level cv qualifications of @code{base_type} and 15526@code{derived_type} are ignored. For the purposes of this trait, a 15527class type is considered is own base. Requires: if @code{__is_class 15528(base_type)} and @code{__is_class (derived_type)} are true and 15529@code{base_type} and @code{derived_type} are not the same type 15530(disregarding cv-qualifiers), @code{derived_type} shall be a complete 15531type. Diagnostic is produced if this requirement is not met. 15532 15533@item __is_class (type) 15534If @code{type} is a cv class type, and not a union type 15535([basic.compound]) the trait is true, else it is false. 15536 15537@item __is_empty (type) 15538If @code{__is_class (type)} is false then the trait is false. 15539Otherwise @code{type} is considered empty if and only if: @code{type} 15540has no non-static data members, or all non-static data members, if 15541any, are bit-fields of length 0, and @code{type} has no virtual 15542members, and @code{type} has no virtual base classes, and @code{type} 15543has no base classes @code{base_type} for which 15544@code{__is_empty (base_type)} is false. Requires: @code{type} shall 15545be a complete type, (possibly cv-qualified) @code{void}, or an array 15546of unknown bound. 15547 15548@item __is_enum (type) 15549If @code{type} is a cv enumeration type ([basic.compound]) the trait is 15550true, else it is false. 15551 15552@item __is_literal_type (type) 15553If @code{type} is a literal type ([basic.types]) the trait is 15554true, else it is false. Requires: @code{type} shall be a complete type, 15555(possibly cv-qualified) @code{void}, or an array of unknown bound. 15556 15557@item __is_pod (type) 15558If @code{type} is a cv POD type ([basic.types]) then the trait is true, 15559else it is false. Requires: @code{type} shall be a complete type, 15560(possibly cv-qualified) @code{void}, or an array of unknown bound. 15561 15562@item __is_polymorphic (type) 15563If @code{type} is a polymorphic class ([class.virtual]) then the trait 15564is true, else it is false. Requires: @code{type} shall be a complete 15565type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 15566 15567@item __is_standard_layout (type) 15568If @code{type} is a standard-layout type ([basic.types]) the trait is 15569true, else it is false. Requires: @code{type} shall be a complete 15570type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 15571 15572@item __is_trivial (type) 15573If @code{type} is a trivial type ([basic.types]) the trait is 15574true, else it is false. Requires: @code{type} shall be a complete 15575type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 15576 15577@item __is_union (type) 15578If @code{type} is a cv union type ([basic.compound]) the trait is 15579true, else it is false. 15580 15581@item __underlying_type (type) 15582The underlying type of @code{type}. Requires: @code{type} shall be 15583an enumeration type ([dcl.enum]). 15584 15585@end table 15586 15587@node Java Exceptions 15588@section Java Exceptions 15589 15590The Java language uses a slightly different exception handling model 15591from C++. Normally, GNU C++ will automatically detect when you are 15592writing C++ code that uses Java exceptions, and handle them 15593appropriately. However, if C++ code only needs to execute destructors 15594when Java exceptions are thrown through it, GCC will guess incorrectly. 15595Sample problematic code is: 15596 15597@smallexample 15598 struct S @{ ~S(); @}; 15599 extern void bar(); // @r{is written in Java, and may throw exceptions} 15600 void foo() 15601 @{ 15602 S s; 15603 bar(); 15604 @} 15605@end smallexample 15606 15607@noindent 15608The usual effect of an incorrect guess is a link failure, complaining of 15609a missing routine called @samp{__gxx_personality_v0}. 15610 15611You can inform the compiler that Java exceptions are to be used in a 15612translation unit, irrespective of what it might think, by writing 15613@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This 15614@samp{#pragma} must appear before any functions that throw or catch 15615exceptions, or run destructors when exceptions are thrown through them. 15616 15617You cannot mix Java and C++ exceptions in the same translation unit. It 15618is believed to be safe to throw a C++ exception from one file through 15619another file compiled for the Java exception model, or vice versa, but 15620there may be bugs in this area. 15621 15622@node Deprecated Features 15623@section Deprecated Features 15624 15625In the past, the GNU C++ compiler was extended to experiment with new 15626features, at a time when the C++ language was still evolving. Now that 15627the C++ standard is complete, some of those features are superseded by 15628superior alternatives. Using the old features might cause a warning in 15629some cases that the feature will be dropped in the future. In other 15630cases, the feature might be gone already. 15631 15632While the list below is not exhaustive, it documents some of the options 15633that are now deprecated: 15634 15635@table @code 15636@item -fexternal-templates 15637@itemx -falt-external-templates 15638These are two of the many ways for G++ to implement template 15639instantiation. @xref{Template Instantiation}. The C++ standard clearly 15640defines how template definitions have to be organized across 15641implementation units. G++ has an implicit instantiation mechanism that 15642should work just fine for standard-conforming code. 15643 15644@item -fstrict-prototype 15645@itemx -fno-strict-prototype 15646Previously it was possible to use an empty prototype parameter list to 15647indicate an unspecified number of parameters (like C), rather than no 15648parameters, as C++ demands. This feature has been removed, except where 15649it is required for backwards compatibility. @xref{Backwards Compatibility}. 15650@end table 15651 15652G++ allows a virtual function returning @samp{void *} to be overridden 15653by one returning a different pointer type. This extension to the 15654covariant return type rules is now deprecated and will be removed from a 15655future version. 15656 15657The G++ minimum and maximum operators (@samp{<?} and @samp{>?}) and 15658their compound forms (@samp{<?=}) and @samp{>?=}) have been deprecated 15659and are now removed from G++. Code using these operators should be 15660modified to use @code{std::min} and @code{std::max} instead. 15661 15662The named return value extension has been deprecated, and is now 15663removed from G++. 15664 15665The use of initializer lists with new expressions has been deprecated, 15666and is now removed from G++. 15667 15668Floating and complex non-type template parameters have been deprecated, 15669and are now removed from G++. 15670 15671The implicit typename extension has been deprecated and is now 15672removed from G++. 15673 15674The use of default arguments in function pointers, function typedefs 15675and other places where they are not permitted by the standard is 15676deprecated and will be removed from a future version of G++. 15677 15678G++ allows floating-point literals to appear in integral constant expressions, 15679e.g. @samp{ enum E @{ e = int(2.2 * 3.7) @} } 15680This extension is deprecated and will be removed from a future version. 15681 15682G++ allows static data members of const floating-point type to be declared 15683with an initializer in a class definition. The standard only allows 15684initializers for static members of const integral types and const 15685enumeration types so this extension has been deprecated and will be removed 15686from a future version. 15687 15688@node Backwards Compatibility 15689@section Backwards Compatibility 15690@cindex Backwards Compatibility 15691@cindex ARM [Annotated C++ Reference Manual] 15692 15693Now that there is a definitive ISO standard C++, G++ has a specification 15694to adhere to. The C++ language evolved over time, and features that 15695used to be acceptable in previous drafts of the standard, such as the ARM 15696[Annotated C++ Reference Manual], are no longer accepted. In order to allow 15697compilation of C++ written to such drafts, G++ contains some backwards 15698compatibilities. @emph{All such backwards compatibility features are 15699liable to disappear in future versions of G++.} They should be considered 15700deprecated. @xref{Deprecated Features}. 15701 15702@table @code 15703@item For scope 15704If a variable is declared at for scope, it used to remain in scope until 15705the end of the scope which contained the for statement (rather than just 15706within the for scope). G++ retains this, but issues a warning, if such a 15707variable is accessed outside the for scope. 15708 15709@item Implicit C language 15710Old C system header files did not contain an @code{extern "C" @{@dots{}@}} 15711scope to set the language. On such systems, all header files are 15712implicitly scoped inside a C language scope. Also, an empty prototype 15713@code{()} will be treated as an unspecified number of arguments, rather 15714than no arguments, as C++ demands. 15715@end table 15716