extend.texi revision 259694
1@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2@c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. 3 4@c This is part of the GCC manual. 5@c For copying conditions, see the file gcc.texi. 6 7@node C Extensions 8@chapter Extensions to the C Language Family 9@cindex extensions, C language 10@cindex C language extensions 11 12@opindex pedantic 13GNU C provides several language features not found in ISO standard C@. 14(The @option{-pedantic} option directs GCC to print a warning message if 15any of these features is used.) To test for the availability of these 16features in conditional compilation, check for a predefined macro 17@code{__GNUC__}, which is always defined under GCC@. 18 19These extensions are available in C. Most of them are also available 20in C++. @xref{C++ Extensions,,Extensions to the C++ Language}, for 21extensions that apply @emph{only} to C++. 22 23Some features that are in ISO C99 but not C89 or C++ are also, as 24extensions, accepted by GCC in C89 mode and in C++. 25 26@menu 27* Statement Exprs:: Putting statements and declarations inside expressions. 28* Local Labels:: Labels local to a block. 29* Labels as Values:: Getting pointers to labels, and computed gotos. 30* Nested Functions:: As in Algol and Pascal, lexical scoping of functions. 31* Constructing Calls:: Dispatching a call to another function. 32* Typeof:: @code{typeof}: referring to the type of an expression. 33* Conditionals:: Omitting the middle operand of a @samp{?:} expression. 34* Long Long:: Double-word integers---@code{long long int}. 35* Complex:: Data types for complex numbers. 36* Decimal Float:: Decimal Floating Types. 37* Hex Floats:: Hexadecimal floating-point constants. 38* Zero Length:: Zero-length arrays. 39* Variable Length:: Arrays whose length is computed at run time. 40* Empty Structures:: Structures with no members. 41* Variadic Macros:: Macros with a variable number of arguments. 42* Escaped Newlines:: Slightly looser rules for escaped newlines. 43* Subscripting:: Any array can be subscripted, even if not an lvalue. 44* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. 45* Initializers:: Non-constant initializers. 46* Compound Literals:: Compound literals give structures, unions 47 or arrays as values. 48* Designated Inits:: Labeling elements of initializers. 49* Cast to Union:: Casting to union type from any member of the union. 50* Case Ranges:: `case 1 ... 9' and such. 51* Mixed Declarations:: Mixing declarations and code. 52* Function Attributes:: Declaring that functions have no side effects, 53 or that they can never return. 54* Attribute Syntax:: Formal syntax for attributes. 55* Function Prototypes:: Prototype declarations and old-style definitions. 56* C++ Comments:: C++ comments are recognized. 57* Dollar Signs:: Dollar sign is allowed in identifiers. 58* Character Escapes:: @samp{\e} stands for the character @key{ESC}. 59* Variable Attributes:: Specifying attributes of variables. 60* Type Attributes:: Specifying attributes of types. 61* Alignment:: Inquiring about the alignment of a type or variable. 62* Inline:: Defining inline functions (as fast as macros). 63* Extended Asm:: Assembler instructions with C expressions as operands. 64 (With them you can define ``built-in'' functions.) 65* Constraints:: Constraints for asm operands 66* Asm Labels:: Specifying the assembler name to use for a C symbol. 67* Explicit Reg Vars:: Defining variables residing in specified registers. 68* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. 69* Incomplete Enums:: @code{enum foo;}, with details to follow. 70* Function Names:: Printable strings which are the name of the current 71 function. 72* Return Address:: Getting the return or frame address of a function. 73* Vector Extensions:: Using vector instructions through built-in functions. 74* Offsetof:: Special syntax for implementing @code{offsetof}. 75* Atomic Builtins:: Built-in functions for atomic memory access. 76* Object Size Checking:: Built-in functions for limited buffer overflow 77 checking. 78* Other Builtins:: Other built-in functions. 79* Target Builtins:: Built-in functions specific to particular targets. 80* Target Format Checks:: Format checks specific to particular targets. 81* Pragmas:: Pragmas accepted by GCC. 82* Unnamed Fields:: Unnamed struct/union fields within structs/unions. 83* Thread-Local:: Per-thread variables. 84* Binary constants:: Binary constants using the @samp{0b} prefix. 85@end menu 86 87@node Statement Exprs 88@section Statements and Declarations in Expressions 89@cindex statements inside expressions 90@cindex declarations inside expressions 91@cindex expressions containing statements 92@cindex macros, statements in expressions 93 94@c the above section title wrapped and causes an underfull hbox.. i 95@c changed it from "within" to "in". --mew 4feb93 96A compound statement enclosed in parentheses may appear as an expression 97in GNU C@. This allows you to use loops, switches, and local variables 98within an expression. 99 100Recall that a compound statement is a sequence of statements surrounded 101by braces; in this construct, parentheses go around the braces. For 102example: 103 104@smallexample 105(@{ int y = foo (); int z; 106 if (y > 0) z = y; 107 else z = - y; 108 z; @}) 109@end smallexample 110 111@noindent 112is a valid (though slightly more complex than necessary) expression 113for the absolute value of @code{foo ()}. 114 115The last thing in the compound statement should be an expression 116followed by a semicolon; the value of this subexpression serves as the 117value of the entire construct. (If you use some other kind of statement 118last within the braces, the construct has type @code{void}, and thus 119effectively no value.) 120 121This feature is especially useful in making macro definitions ``safe'' (so 122that they evaluate each operand exactly once). For example, the 123``maximum'' function is commonly defined as a macro in standard C as 124follows: 125 126@smallexample 127#define max(a,b) ((a) > (b) ? (a) : (b)) 128@end smallexample 129 130@noindent 131@cindex side effects, macro argument 132But this definition computes either @var{a} or @var{b} twice, with bad 133results if the operand has side effects. In GNU C, if you know the 134type of the operands (here taken as @code{int}), you can define 135the macro safely as follows: 136 137@smallexample 138#define maxint(a,b) \ 139 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) 140@end smallexample 141 142Embedded statements are not allowed in constant expressions, such as 143the value of an enumeration constant, the width of a bit-field, or 144the initial value of a static variable. 145 146If you don't know the type of the operand, you can still do this, but you 147must use @code{typeof} (@pxref{Typeof}). 148 149In G++, the result value of a statement expression undergoes array and 150function pointer decay, and is returned by value to the enclosing 151expression. For instance, if @code{A} is a class, then 152 153@smallexample 154 A a; 155 156 (@{a;@}).Foo () 157@end smallexample 158 159@noindent 160will construct a temporary @code{A} object to hold the result of the 161statement expression, and that will be used to invoke @code{Foo}. 162Therefore the @code{this} pointer observed by @code{Foo} will not be the 163address of @code{a}. 164 165Any temporaries created within a statement within a statement expression 166will be destroyed at the statement's end. This makes statement 167expressions inside macros slightly different from function calls. In 168the latter case temporaries introduced during argument evaluation will 169be destroyed at the end of the statement that includes the function 170call. In the statement expression case they will be destroyed during 171the statement expression. For instance, 172 173@smallexample 174#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) 175template<typename T> T function(T a) @{ T b = a; return b + 3; @} 176 177void foo () 178@{ 179 macro (X ()); 180 function (X ()); 181@} 182@end smallexample 183 184@noindent 185will have different places where temporaries are destroyed. For the 186@code{macro} case, the temporary @code{X} will be destroyed just after 187the initialization of @code{b}. In the @code{function} case that 188temporary will be destroyed when the function returns. 189 190These considerations mean that it is probably a bad idea to use 191statement-expressions of this form in header files that are designed to 192work with C++. (Note that some versions of the GNU C Library contained 193header files using statement-expression that lead to precisely this 194bug.) 195 196Jumping into a statement expression with @code{goto} or using a 197@code{switch} statement outside the statement expression with a 198@code{case} or @code{default} label inside the statement expression is 199not permitted. Jumping into a statement expression with a computed 200@code{goto} (@pxref{Labels as Values}) yields undefined behavior. 201Jumping out of a statement expression is permitted, but if the 202statement expression is part of a larger expression then it is 203unspecified which other subexpressions of that expression have been 204evaluated except where the language definition requires certain 205subexpressions to be evaluated before or after the statement 206expression. In any case, as with a function call the evaluation of a 207statement expression is not interleaved with the evaluation of other 208parts of the containing expression. For example, 209 210@smallexample 211 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); 212@end smallexample 213 214@noindent 215will call @code{foo} and @code{bar1} and will not call @code{baz} but 216may or may not call @code{bar2}. If @code{bar2} is called, it will be 217called after @code{foo} and before @code{bar1} 218 219@node Local Labels 220@section Locally Declared Labels 221@cindex local labels 222@cindex macros, local labels 223 224GCC allows you to declare @dfn{local labels} in any nested block 225scope. A local label is just like an ordinary label, but you can 226only reference it (with a @code{goto} statement, or by taking its 227address) within the block in which it was declared. 228 229A local label declaration looks like this: 230 231@smallexample 232__label__ @var{label}; 233@end smallexample 234 235@noindent 236or 237 238@smallexample 239__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; 240@end smallexample 241 242Local label declarations must come at the beginning of the block, 243before any ordinary declarations or statements. 244 245The label declaration defines the label @emph{name}, but does not define 246the label itself. You must do this in the usual way, with 247@code{@var{label}:}, within the statements of the statement expression. 248 249The local label feature is useful for complex macros. If a macro 250contains nested loops, a @code{goto} can be useful for breaking out of 251them. However, an ordinary label whose scope is the whole function 252cannot be used: if the macro can be expanded several times in one 253function, the label will be multiply defined in that function. A 254local label avoids this problem. For example: 255 256@smallexample 257#define SEARCH(value, array, target) \ 258do @{ \ 259 __label__ found; \ 260 typeof (target) _SEARCH_target = (target); \ 261 typeof (*(array)) *_SEARCH_array = (array); \ 262 int i, j; \ 263 int value; \ 264 for (i = 0; i < max; i++) \ 265 for (j = 0; j < max; j++) \ 266 if (_SEARCH_array[i][j] == _SEARCH_target) \ 267 @{ (value) = i; goto found; @} \ 268 (value) = -1; \ 269 found:; \ 270@} while (0) 271@end smallexample 272 273This could also be written using a statement-expression: 274 275@smallexample 276#define SEARCH(array, target) \ 277(@{ \ 278 __label__ found; \ 279 typeof (target) _SEARCH_target = (target); \ 280 typeof (*(array)) *_SEARCH_array = (array); \ 281 int i, j; \ 282 int value; \ 283 for (i = 0; i < max; i++) \ 284 for (j = 0; j < max; j++) \ 285 if (_SEARCH_array[i][j] == _SEARCH_target) \ 286 @{ value = i; goto found; @} \ 287 value = -1; \ 288 found: \ 289 value; \ 290@}) 291@end smallexample 292 293Local label declarations also make the labels they declare visible to 294nested functions, if there are any. @xref{Nested Functions}, for details. 295 296@node Labels as Values 297@section Labels as Values 298@cindex labels as values 299@cindex computed gotos 300@cindex goto with computed label 301@cindex address of a label 302 303You can get the address of a label defined in the current function 304(or a containing function) with the unary operator @samp{&&}. The 305value has type @code{void *}. This value is a constant and can be used 306wherever a constant of that type is valid. For example: 307 308@smallexample 309void *ptr; 310/* @r{@dots{}} */ 311ptr = &&foo; 312@end smallexample 313 314To use these values, you need to be able to jump to one. This is done 315with the computed goto statement@footnote{The analogous feature in 316Fortran is called an assigned goto, but that name seems inappropriate in 317C, where one can do more than simply store label addresses in label 318variables.}, @code{goto *@var{exp};}. For example, 319 320@smallexample 321goto *ptr; 322@end smallexample 323 324@noindent 325Any expression of type @code{void *} is allowed. 326 327One way of using these constants is in initializing a static array that 328will serve as a jump table: 329 330@smallexample 331static void *array[] = @{ &&foo, &&bar, &&hack @}; 332@end smallexample 333 334Then you can select a label with indexing, like this: 335 336@smallexample 337goto *array[i]; 338@end smallexample 339 340@noindent 341Note that this does not check whether the subscript is in bounds---array 342indexing in C never does that. 343 344Such an array of label values serves a purpose much like that of the 345@code{switch} statement. The @code{switch} statement is cleaner, so 346use that rather than an array unless the problem does not fit a 347@code{switch} statement very well. 348 349Another use of label values is in an interpreter for threaded code. 350The labels within the interpreter function can be stored in the 351threaded code for super-fast dispatching. 352 353You may not use this mechanism to jump to code in a different function. 354If you do that, totally unpredictable things will happen. The best way to 355avoid this is to store the label address only in automatic variables and 356never pass it as an argument. 357 358An alternate way to write the above example is 359 360@smallexample 361static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, 362 &&hack - &&foo @}; 363goto *(&&foo + array[i]); 364@end smallexample 365 366@noindent 367This is more friendly to code living in shared libraries, as it reduces 368the number of dynamic relocations that are needed, and by consequence, 369allows the data to be read-only. 370 371@node Nested Functions 372@section Nested Functions 373@cindex nested functions 374@cindex downward funargs 375@cindex thunks 376 377A @dfn{nested function} is a function defined inside another function. 378(Nested functions are not supported for GNU C++.) The nested function's 379name is local to the block where it is defined. For example, here we 380define a nested function named @code{square}, and call it twice: 381 382@smallexample 383@group 384foo (double a, double b) 385@{ 386 double square (double z) @{ return z * z; @} 387 388 return square (a) + square (b); 389@} 390@end group 391@end smallexample 392 393The nested function can access all the variables of the containing 394function that are visible at the point of its definition. This is 395called @dfn{lexical scoping}. For example, here we show a nested 396function which uses an inherited variable named @code{offset}: 397 398@smallexample 399@group 400bar (int *array, int offset, int size) 401@{ 402 int access (int *array, int index) 403 @{ return array[index + offset]; @} 404 int i; 405 /* @r{@dots{}} */ 406 for (i = 0; i < size; i++) 407 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 408@} 409@end group 410@end smallexample 411 412Nested function definitions are permitted within functions in the places 413where variable definitions are allowed; that is, in any block, mixed 414with the other declarations and statements in the block. 415 416It is possible to call the nested function from outside the scope of its 417name by storing its address or passing the address to another function: 418 419@smallexample 420hack (int *array, int size) 421@{ 422 void store (int index, int value) 423 @{ array[index] = value; @} 424 425 intermediate (store, size); 426@} 427@end smallexample 428 429Here, the function @code{intermediate} receives the address of 430@code{store} as an argument. If @code{intermediate} calls @code{store}, 431the arguments given to @code{store} are used to store into @code{array}. 432But this technique works only so long as the containing function 433(@code{hack}, in this example) does not exit. 434 435If you try to call the nested function through its address after the 436containing function has exited, all hell will break loose. If you try 437to call it after a containing scope level has exited, and if it refers 438to some of the variables that are no longer in scope, you may be lucky, 439but it's not wise to take the risk. If, however, the nested function 440does not refer to anything that has gone out of scope, you should be 441safe. 442 443GCC implements taking the address of a nested function using a technique 444called @dfn{trampolines}. A paper describing them is available as 445 446@noindent 447@uref{http://people.debian.org/~aaronl/Usenix88-lexic.pdf}. 448 449A nested function can jump to a label inherited from a containing 450function, provided the label was explicitly declared in the containing 451function (@pxref{Local Labels}). Such a jump returns instantly to the 452containing function, exiting the nested function which did the 453@code{goto} and any intermediate functions as well. Here is an example: 454 455@smallexample 456@group 457bar (int *array, int offset, int size) 458@{ 459 __label__ failure; 460 int access (int *array, int index) 461 @{ 462 if (index > size) 463 goto failure; 464 return array[index + offset]; 465 @} 466 int i; 467 /* @r{@dots{}} */ 468 for (i = 0; i < size; i++) 469 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 470 /* @r{@dots{}} */ 471 return 0; 472 473 /* @r{Control comes here from @code{access} 474 if it detects an error.} */ 475 failure: 476 return -1; 477@} 478@end group 479@end smallexample 480 481A nested function always has no linkage. Declaring one with 482@code{extern} or @code{static} is erroneous. If you need to declare the nested function 483before its definition, use @code{auto} (which is otherwise meaningless 484for function declarations). 485 486@smallexample 487bar (int *array, int offset, int size) 488@{ 489 __label__ failure; 490 auto int access (int *, int); 491 /* @r{@dots{}} */ 492 int access (int *array, int index) 493 @{ 494 if (index > size) 495 goto failure; 496 return array[index + offset]; 497 @} 498 /* @r{@dots{}} */ 499@} 500@end smallexample 501 502@node Constructing Calls 503@section Constructing Function Calls 504@cindex constructing calls 505@cindex forwarding calls 506 507Using the built-in functions described below, you can record 508the arguments a function received, and call another function 509with the same arguments, without knowing the number or types 510of the arguments. 511 512You can also record the return value of that function call, 513and later return that value, without knowing what data type 514the function tried to return (as long as your caller expects 515that data type). 516 517However, these built-in functions may interact badly with some 518sophisticated features or other extensions of the language. It 519is, therefore, not recommended to use them outside very simple 520functions acting as mere forwarders for their arguments. 521 522@deftypefn {Built-in Function} {void *} __builtin_apply_args () 523This built-in function returns a pointer to data 524describing how to perform a call with the same arguments as were passed 525to the current function. 526 527The function saves the arg pointer register, structure value address, 528and all registers that might be used to pass arguments to a function 529into a block of memory allocated on the stack. Then it returns the 530address of that block. 531@end deftypefn 532 533@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) 534This built-in function invokes @var{function} 535with a copy of the parameters described by @var{arguments} 536and @var{size}. 537 538The value of @var{arguments} should be the value returned by 539@code{__builtin_apply_args}. The argument @var{size} specifies the size 540of the stack argument data, in bytes. 541 542This function returns a pointer to data describing 543how to return whatever value was returned by @var{function}. The data 544is saved in a block of memory allocated on the stack. 545 546It is not always simple to compute the proper value for @var{size}. The 547value is used by @code{__builtin_apply} to compute the amount of data 548that should be pushed on the stack and copied from the incoming argument 549area. 550@end deftypefn 551 552@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) 553This built-in function returns the value described by @var{result} from 554the containing function. You should specify, for @var{result}, a value 555returned by @code{__builtin_apply}. 556@end deftypefn 557 558@node Typeof 559@section Referring to a Type with @code{typeof} 560@findex typeof 561@findex sizeof 562@cindex macros, types of arguments 563 564Another way to refer to the type of an expression is with @code{typeof}. 565The syntax of using of this keyword looks like @code{sizeof}, but the 566construct acts semantically like a type name defined with @code{typedef}. 567 568There are two ways of writing the argument to @code{typeof}: with an 569expression or with a type. Here is an example with an expression: 570 571@smallexample 572typeof (x[0](1)) 573@end smallexample 574 575@noindent 576This assumes that @code{x} is an array of pointers to functions; 577the type described is that of the values of the functions. 578 579Here is an example with a typename as the argument: 580 581@smallexample 582typeof (int *) 583@end smallexample 584 585@noindent 586Here the type described is that of pointers to @code{int}. 587 588If you are writing a header file that must work when included in ISO C 589programs, write @code{__typeof__} instead of @code{typeof}. 590@xref{Alternate Keywords}. 591 592A @code{typeof}-construct can be used anywhere a typedef name could be 593used. For example, you can use it in a declaration, in a cast, or inside 594of @code{sizeof} or @code{typeof}. 595 596@code{typeof} is often useful in conjunction with the 597statements-within-expressions feature. Here is how the two together can 598be used to define a safe ``maximum'' macro that operates on any 599arithmetic type and evaluates each of its arguments exactly once: 600 601@smallexample 602#define max(a,b) \ 603 (@{ typeof (a) _a = (a); \ 604 typeof (b) _b = (b); \ 605 _a > _b ? _a : _b; @}) 606@end smallexample 607 608@cindex underscores in variables in macros 609@cindex @samp{_} in variables in macros 610@cindex local variables in macros 611@cindex variables, local, in macros 612@cindex macros, local variables in 613 614The reason for using names that start with underscores for the local 615variables is to avoid conflicts with variable names that occur within the 616expressions that are substituted for @code{a} and @code{b}. Eventually we 617hope to design a new form of declaration syntax that allows you to declare 618variables whose scopes start only after their initializers; this will be a 619more reliable way to prevent such conflicts. 620 621@noindent 622Some more examples of the use of @code{typeof}: 623 624@itemize @bullet 625@item 626This declares @code{y} with the type of what @code{x} points to. 627 628@smallexample 629typeof (*x) y; 630@end smallexample 631 632@item 633This declares @code{y} as an array of such values. 634 635@smallexample 636typeof (*x) y[4]; 637@end smallexample 638 639@item 640This declares @code{y} as an array of pointers to characters: 641 642@smallexample 643typeof (typeof (char *)[4]) y; 644@end smallexample 645 646@noindent 647It is equivalent to the following traditional C declaration: 648 649@smallexample 650char *y[4]; 651@end smallexample 652 653To see the meaning of the declaration using @code{typeof}, and why it 654might be a useful way to write, rewrite it with these macros: 655 656@smallexample 657#define pointer(T) typeof(T *) 658#define array(T, N) typeof(T [N]) 659@end smallexample 660 661@noindent 662Now the declaration can be rewritten this way: 663 664@smallexample 665array (pointer (char), 4) y; 666@end smallexample 667 668@noindent 669Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 670pointers to @code{char}. 671@end itemize 672 673@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported 674a more limited extension which permitted one to write 675 676@smallexample 677typedef @var{T} = @var{expr}; 678@end smallexample 679 680@noindent 681with the effect of declaring @var{T} to have the type of the expression 682@var{expr}. This extension does not work with GCC 3 (versions between 6833.0 and 3.2 will crash; 3.2.1 and later give an error). Code which 684relies on it should be rewritten to use @code{typeof}: 685 686@smallexample 687typedef typeof(@var{expr}) @var{T}; 688@end smallexample 689 690@noindent 691This will work with all versions of GCC@. 692 693@node Conditionals 694@section Conditionals with Omitted Operands 695@cindex conditional expressions, extensions 696@cindex omitted middle-operands 697@cindex middle-operands, omitted 698@cindex extensions, @code{?:} 699@cindex @code{?:} extensions 700 701The middle operand in a conditional expression may be omitted. Then 702if the first operand is nonzero, its value is the value of the conditional 703expression. 704 705Therefore, the expression 706 707@smallexample 708x ? : y 709@end smallexample 710 711@noindent 712has the value of @code{x} if that is nonzero; otherwise, the value of 713@code{y}. 714 715This example is perfectly equivalent to 716 717@smallexample 718x ? x : y 719@end smallexample 720 721@cindex side effect in ?: 722@cindex ?: side effect 723@noindent 724In this simple case, the ability to omit the middle operand is not 725especially useful. When it becomes useful is when the first operand does, 726or may (if it is a macro argument), contain a side effect. Then repeating 727the operand in the middle would perform the side effect twice. Omitting 728the middle operand uses the value already computed without the undesirable 729effects of recomputing it. 730 731@node Long Long 732@section Double-Word Integers 733@cindex @code{long long} data types 734@cindex double-word arithmetic 735@cindex multiprecision arithmetic 736@cindex @code{LL} integer suffix 737@cindex @code{ULL} integer suffix 738 739ISO C99 supports data types for integers that are at least 64 bits wide, 740and as an extension GCC supports them in C89 mode and in C++. 741Simply write @code{long long int} for a signed integer, or 742@code{unsigned long long int} for an unsigned integer. To make an 743integer constant of type @code{long long int}, add the suffix @samp{LL} 744to the integer. To make an integer constant of type @code{unsigned long 745long int}, add the suffix @samp{ULL} to the integer. 746 747You can use these types in arithmetic like any other integer types. 748Addition, subtraction, and bitwise boolean operations on these types 749are open-coded on all types of machines. Multiplication is open-coded 750if the machine supports fullword-to-doubleword a widening multiply 751instruction. Division and shifts are open-coded only on machines that 752provide special support. The operations that are not open-coded use 753special library routines that come with GCC@. 754 755There may be pitfalls when you use @code{long long} types for function 756arguments, unless you declare function prototypes. If a function 757expects type @code{int} for its argument, and you pass a value of type 758@code{long long int}, confusion will result because the caller and the 759subroutine will disagree about the number of bytes for the argument. 760Likewise, if the function expects @code{long long int} and you pass 761@code{int}. The best way to avoid such problems is to use prototypes. 762 763@node Complex 764@section Complex Numbers 765@cindex complex numbers 766@cindex @code{_Complex} keyword 767@cindex @code{__complex__} keyword 768 769ISO C99 supports complex floating data types, and as an extension GCC 770supports them in C89 mode and in C++, and supports complex integer data 771types which are not part of ISO C99. You can declare complex types 772using the keyword @code{_Complex}. As an extension, the older GNU 773keyword @code{__complex__} is also supported. 774 775For example, @samp{_Complex double x;} declares @code{x} as a 776variable whose real part and imaginary part are both of type 777@code{double}. @samp{_Complex short int y;} declares @code{y} to 778have real and imaginary parts of type @code{short int}; this is not 779likely to be useful, but it shows that the set of complex types is 780complete. 781 782To write a constant with a complex data type, use the suffix @samp{i} or 783@samp{j} (either one; they are equivalent). For example, @code{2.5fi} 784has type @code{_Complex float} and @code{3i} has type 785@code{_Complex int}. Such a constant always has a pure imaginary 786value, but you can form any complex value you like by adding one to a 787real constant. This is a GNU extension; if you have an ISO C99 788conforming C library (such as GNU libc), and want to construct complex 789constants of floating type, you should include @code{<complex.h>} and 790use the macros @code{I} or @code{_Complex_I} instead. 791 792@cindex @code{__real__} keyword 793@cindex @code{__imag__} keyword 794To extract the real part of a complex-valued expression @var{exp}, write 795@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to 796extract the imaginary part. This is a GNU extension; for values of 797floating type, you should use the ISO C99 functions @code{crealf}, 798@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and 799@code{cimagl}, declared in @code{<complex.h>} and also provided as 800built-in functions by GCC@. 801 802@cindex complex conjugation 803The operator @samp{~} performs complex conjugation when used on a value 804with a complex type. This is a GNU extension; for values of 805floating type, you should use the ISO C99 functions @code{conjf}, 806@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also 807provided as built-in functions by GCC@. 808 809GCC can allocate complex automatic variables in a noncontiguous 810fashion; it's even possible for the real part to be in a register while 811the imaginary part is on the stack (or vice-versa). Only the DWARF2 812debug info format can represent this, so use of DWARF2 is recommended. 813If you are using the stabs debug info format, GCC describes a noncontiguous 814complex variable as if it were two separate variables of noncomplex type. 815If the variable's actual name is @code{foo}, the two fictitious 816variables are named @code{foo$real} and @code{foo$imag}. You can 817examine and set these two fictitious variables with your debugger. 818 819@node Decimal Float 820@section Decimal Floating Types 821@cindex decimal floating types 822@cindex @code{_Decimal32} data type 823@cindex @code{_Decimal64} data type 824@cindex @code{_Decimal128} data type 825@cindex @code{df} integer suffix 826@cindex @code{dd} integer suffix 827@cindex @code{dl} integer suffix 828@cindex @code{DF} integer suffix 829@cindex @code{DD} integer suffix 830@cindex @code{DL} integer suffix 831 832As an extension, the GNU C compiler supports decimal floating types as 833defined in the N1176 draft of ISO/IEC WDTR24732. Support for decimal 834floating types in GCC will evolve as the draft technical report changes. 835Calling conventions for any target might also change. Not all targets 836support decimal floating types. 837 838The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and 839@code{_Decimal128}. They use a radix of ten, unlike the floating types 840@code{float}, @code{double}, and @code{long double} whose radix is not 841specified by the C standard but is usually two. 842 843Support for decimal floating types includes the arithmetic operators 844add, subtract, multiply, divide; unary arithmetic operators; 845relational operators; equality operators; and conversions to and from 846integer and other floating types. Use a suffix @samp{df} or 847@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} 848or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for 849@code{_Decimal128}. 850 851GCC support of decimal float as specified by the draft technical report 852is incomplete: 853 854@itemize @bullet 855@item 856Translation time data type (TTDT) is not supported. 857 858@item 859Characteristics of decimal floating types are defined in header file 860@file{decfloat.h} rather than @file{float.h}. 861 862@item 863When the value of a decimal floating type cannot be represented in the 864integer type to which it is being converted, the result is undefined 865rather than the result value specified by the draft technical report. 866@end itemize 867 868Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} 869are supported by the DWARF2 debug information format. 870 871@node Hex Floats 872@section Hex Floats 873@cindex hex floats 874 875ISO C99 supports floating-point numbers written not only in the usual 876decimal notation, such as @code{1.55e1}, but also numbers such as 877@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC 878supports this in C89 mode (except in some cases when strictly 879conforming) and in C++. In that format the 880@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are 881mandatory. The exponent is a decimal number that indicates the power of 8822 by which the significant part will be multiplied. Thus @samp{0x1.f} is 883@tex 884$1 {15\over16}$, 885@end tex 886@ifnottex 8871 15/16, 888@end ifnottex 889@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} 890is the same as @code{1.55e1}. 891 892Unlike for floating-point numbers in the decimal notation the exponent 893is always required in the hexadecimal notation. Otherwise the compiler 894would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This 895could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the 896extension for floating-point constants of type @code{float}. 897 898@node Zero Length 899@section Arrays of Length Zero 900@cindex arrays of length zero 901@cindex zero-length arrays 902@cindex length-zero arrays 903@cindex flexible array members 904 905Zero-length arrays are allowed in GNU C@. They are very useful as the 906last element of a structure which is really a header for a variable-length 907object: 908 909@smallexample 910struct line @{ 911 int length; 912 char contents[0]; 913@}; 914 915struct line *thisline = (struct line *) 916 malloc (sizeof (struct line) + this_length); 917thisline->length = this_length; 918@end smallexample 919 920In ISO C90, you would have to give @code{contents} a length of 1, which 921means either you waste space or complicate the argument to @code{malloc}. 922 923In ISO C99, you would use a @dfn{flexible array member}, which is 924slightly different in syntax and semantics: 925 926@itemize @bullet 927@item 928Flexible array members are written as @code{contents[]} without 929the @code{0}. 930 931@item 932Flexible array members have incomplete type, and so the @code{sizeof} 933operator may not be applied. As a quirk of the original implementation 934of zero-length arrays, @code{sizeof} evaluates to zero. 935 936@item 937Flexible array members may only appear as the last member of a 938@code{struct} that is otherwise non-empty. 939 940@item 941A structure containing a flexible array member, or a union containing 942such a structure (possibly recursively), may not be a member of a 943structure or an element of an array. (However, these uses are 944permitted by GCC as extensions.) 945@end itemize 946 947GCC versions before 3.0 allowed zero-length arrays to be statically 948initialized, as if they were flexible arrays. In addition to those 949cases that were useful, it also allowed initializations in situations 950that would corrupt later data. Non-empty initialization of zero-length 951arrays is now treated like any case where there are more initializer 952elements than the array holds, in that a suitable warning about "excess 953elements in array" is given, and the excess elements (all of them, in 954this case) are ignored. 955 956Instead GCC allows static initialization of flexible array members. 957This is equivalent to defining a new structure containing the original 958structure followed by an array of sufficient size to contain the data. 959I.e.@: in the following, @code{f1} is constructed as if it were declared 960like @code{f2}. 961 962@smallexample 963struct f1 @{ 964 int x; int y[]; 965@} f1 = @{ 1, @{ 2, 3, 4 @} @}; 966 967struct f2 @{ 968 struct f1 f1; int data[3]; 969@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; 970@end smallexample 971 972@noindent 973The convenience of this extension is that @code{f1} has the desired 974type, eliminating the need to consistently refer to @code{f2.f1}. 975 976This has symmetry with normal static arrays, in that an array of 977unknown size is also written with @code{[]}. 978 979Of course, this extension only makes sense if the extra data comes at 980the end of a top-level object, as otherwise we would be overwriting 981data at subsequent offsets. To avoid undue complication and confusion 982with initialization of deeply nested arrays, we simply disallow any 983non-empty initialization except when the structure is the top-level 984object. For example: 985 986@smallexample 987struct foo @{ int x; int y[]; @}; 988struct bar @{ struct foo z; @}; 989 990struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} 991struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 992struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} 993struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 994@end smallexample 995 996@node Empty Structures 997@section Structures With No Members 998@cindex empty structures 999@cindex zero-size structures 1000 1001GCC permits a C structure to have no members: 1002 1003@smallexample 1004struct empty @{ 1005@}; 1006@end smallexample 1007 1008The structure will have size zero. In C++, empty structures are part 1009of the language. G++ treats empty structures as if they had a single 1010member of type @code{char}. 1011 1012@node Variable Length 1013@section Arrays of Variable Length 1014@cindex variable-length arrays 1015@cindex arrays of variable length 1016@cindex VLAs 1017 1018Variable-length automatic arrays are allowed in ISO C99, and as an 1019extension GCC accepts them in C89 mode and in C++. (However, GCC's 1020implementation of variable-length arrays does not yet conform in detail 1021to the ISO C99 standard.) These arrays are 1022declared like any other automatic arrays, but with a length that is not 1023a constant expression. The storage is allocated at the point of 1024declaration and deallocated when the brace-level is exited. For 1025example: 1026 1027@smallexample 1028FILE * 1029concat_fopen (char *s1, char *s2, char *mode) 1030@{ 1031 char str[strlen (s1) + strlen (s2) + 1]; 1032 strcpy (str, s1); 1033 strcat (str, s2); 1034 return fopen (str, mode); 1035@} 1036@end smallexample 1037 1038@cindex scope of a variable length array 1039@cindex variable-length array scope 1040@cindex deallocating variable length arrays 1041Jumping or breaking out of the scope of the array name deallocates the 1042storage. Jumping into the scope is not allowed; you get an error 1043message for it. 1044 1045@cindex @code{alloca} vs variable-length arrays 1046You can use the function @code{alloca} to get an effect much like 1047variable-length arrays. The function @code{alloca} is available in 1048many other C implementations (but not in all). On the other hand, 1049variable-length arrays are more elegant. 1050 1051There are other differences between these two methods. Space allocated 1052with @code{alloca} exists until the containing @emph{function} returns. 1053The space for a variable-length array is deallocated as soon as the array 1054name's scope ends. (If you use both variable-length arrays and 1055@code{alloca} in the same function, deallocation of a variable-length array 1056will also deallocate anything more recently allocated with @code{alloca}.) 1057 1058You can also use variable-length arrays as arguments to functions: 1059 1060@smallexample 1061struct entry 1062tester (int len, char data[len][len]) 1063@{ 1064 /* @r{@dots{}} */ 1065@} 1066@end smallexample 1067 1068The length of an array is computed once when the storage is allocated 1069and is remembered for the scope of the array in case you access it with 1070@code{sizeof}. 1071 1072If you want to pass the array first and the length afterward, you can 1073use a forward declaration in the parameter list---another GNU extension. 1074 1075@smallexample 1076struct entry 1077tester (int len; char data[len][len], int len) 1078@{ 1079 /* @r{@dots{}} */ 1080@} 1081@end smallexample 1082 1083@cindex parameter forward declaration 1084The @samp{int len} before the semicolon is a @dfn{parameter forward 1085declaration}, and it serves the purpose of making the name @code{len} 1086known when the declaration of @code{data} is parsed. 1087 1088You can write any number of such parameter forward declarations in the 1089parameter list. They can be separated by commas or semicolons, but the 1090last one must end with a semicolon, which is followed by the ``real'' 1091parameter declarations. Each forward declaration must match a ``real'' 1092declaration in parameter name and data type. ISO C99 does not support 1093parameter forward declarations. 1094 1095@node Variadic Macros 1096@section Macros with a Variable Number of Arguments. 1097@cindex variable number of arguments 1098@cindex macro with variable arguments 1099@cindex rest argument (in macro) 1100@cindex variadic macros 1101 1102In the ISO C standard of 1999, a macro can be declared to accept a 1103variable number of arguments much as a function can. The syntax for 1104defining the macro is similar to that of a function. Here is an 1105example: 1106 1107@smallexample 1108#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) 1109@end smallexample 1110 1111Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of 1112such a macro, it represents the zero or more tokens until the closing 1113parenthesis that ends the invocation, including any commas. This set of 1114tokens replaces the identifier @code{__VA_ARGS__} in the macro body 1115wherever it appears. See the CPP manual for more information. 1116 1117GCC has long supported variadic macros, and used a different syntax that 1118allowed you to give a name to the variable arguments just like any other 1119argument. Here is an example: 1120 1121@smallexample 1122#define debug(format, args...) fprintf (stderr, format, args) 1123@end smallexample 1124 1125This is in all ways equivalent to the ISO C example above, but arguably 1126more readable and descriptive. 1127 1128GNU CPP has two further variadic macro extensions, and permits them to 1129be used with either of the above forms of macro definition. 1130 1131In standard C, you are not allowed to leave the variable argument out 1132entirely; but you are allowed to pass an empty argument. For example, 1133this invocation is invalid in ISO C, because there is no comma after 1134the string: 1135 1136@smallexample 1137debug ("A message") 1138@end smallexample 1139 1140GNU CPP permits you to completely omit the variable arguments in this 1141way. In the above examples, the compiler would complain, though since 1142the expansion of the macro still has the extra comma after the format 1143string. 1144 1145To help solve this problem, CPP behaves specially for variable arguments 1146used with the token paste operator, @samp{##}. If instead you write 1147 1148@smallexample 1149#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) 1150@end smallexample 1151 1152and if the variable arguments are omitted or empty, the @samp{##} 1153operator causes the preprocessor to remove the comma before it. If you 1154do provide some variable arguments in your macro invocation, GNU CPP 1155does not complain about the paste operation and instead places the 1156variable arguments after the comma. Just like any other pasted macro 1157argument, these arguments are not macro expanded. 1158 1159@node Escaped Newlines 1160@section Slightly Looser Rules for Escaped Newlines 1161@cindex escaped newlines 1162@cindex newlines (escaped) 1163 1164Recently, the preprocessor has relaxed its treatment of escaped 1165newlines. Previously, the newline had to immediately follow a 1166backslash. The current implementation allows whitespace in the form 1167of spaces, horizontal and vertical tabs, and form feeds between the 1168backslash and the subsequent newline. The preprocessor issues a 1169warning, but treats it as a valid escaped newline and combines the two 1170lines to form a single logical line. This works within comments and 1171tokens, as well as between tokens. Comments are @emph{not} treated as 1172whitespace for the purposes of this relaxation, since they have not 1173yet been replaced with spaces. 1174 1175@node Subscripting 1176@section Non-Lvalue Arrays May Have Subscripts 1177@cindex subscripting 1178@cindex arrays, non-lvalue 1179 1180@cindex subscripting and function values 1181In ISO C99, arrays that are not lvalues still decay to pointers, and 1182may be subscripted, although they may not be modified or used after 1183the next sequence point and the unary @samp{&} operator may not be 1184applied to them. As an extension, GCC allows such arrays to be 1185subscripted in C89 mode, though otherwise they do not decay to 1186pointers outside C99 mode. For example, 1187this is valid in GNU C though not valid in C89: 1188 1189@smallexample 1190@group 1191struct foo @{int a[4];@}; 1192 1193struct foo f(); 1194 1195bar (int index) 1196@{ 1197 return f().a[index]; 1198@} 1199@end group 1200@end smallexample 1201 1202@node Pointer Arith 1203@section Arithmetic on @code{void}- and Function-Pointers 1204@cindex void pointers, arithmetic 1205@cindex void, size of pointer to 1206@cindex function pointers, arithmetic 1207@cindex function, size of pointer to 1208 1209In GNU C, addition and subtraction operations are supported on pointers to 1210@code{void} and on pointers to functions. This is done by treating the 1211size of a @code{void} or of a function as 1. 1212 1213A consequence of this is that @code{sizeof} is also allowed on @code{void} 1214and on function types, and returns 1. 1215 1216@opindex Wpointer-arith 1217The option @option{-Wpointer-arith} requests a warning if these extensions 1218are used. 1219 1220@node Initializers 1221@section Non-Constant Initializers 1222@cindex initializers, non-constant 1223@cindex non-constant initializers 1224 1225As in standard C++ and ISO C99, the elements of an aggregate initializer for an 1226automatic variable are not required to be constant expressions in GNU C@. 1227Here is an example of an initializer with run-time varying elements: 1228 1229@smallexample 1230foo (float f, float g) 1231@{ 1232 float beat_freqs[2] = @{ f-g, f+g @}; 1233 /* @r{@dots{}} */ 1234@} 1235@end smallexample 1236 1237@node Compound Literals 1238@section Compound Literals 1239@cindex constructor expressions 1240@cindex initializations in expressions 1241@cindex structures, constructor expression 1242@cindex expressions, constructor 1243@cindex compound literals 1244@c The GNU C name for what C99 calls compound literals was "constructor expressions". 1245 1246ISO C99 supports compound literals. A compound literal looks like 1247a cast containing an initializer. Its value is an object of the 1248type specified in the cast, containing the elements specified in 1249the initializer; it is an lvalue. As an extension, GCC supports 1250compound literals in C89 mode and in C++. 1251 1252Usually, the specified type is a structure. Assume that 1253@code{struct foo} and @code{structure} are declared as shown: 1254 1255@smallexample 1256struct foo @{int a; char b[2];@} structure; 1257@end smallexample 1258 1259@noindent 1260Here is an example of constructing a @code{struct foo} with a compound literal: 1261 1262@smallexample 1263structure = ((struct foo) @{x + y, 'a', 0@}); 1264@end smallexample 1265 1266@noindent 1267This is equivalent to writing the following: 1268 1269@smallexample 1270@{ 1271 struct foo temp = @{x + y, 'a', 0@}; 1272 structure = temp; 1273@} 1274@end smallexample 1275 1276You can also construct an array. If all the elements of the compound literal 1277are (made up of) simple constant expressions, suitable for use in 1278initializers of objects of static storage duration, then the compound 1279literal can be coerced to a pointer to its first element and used in 1280such an initializer, as shown here: 1281 1282@smallexample 1283char **foo = (char *[]) @{ "x", "y", "z" @}; 1284@end smallexample 1285 1286Compound literals for scalar types and union types are is 1287also allowed, but then the compound literal is equivalent 1288to a cast. 1289 1290As a GNU extension, GCC allows initialization of objects with static storage 1291duration by compound literals (which is not possible in ISO C99, because 1292the initializer is not a constant). 1293It is handled as if the object was initialized only with the bracket 1294enclosed list if the types of the compound literal and the object match. 1295The initializer list of the compound literal must be constant. 1296If the object being initialized has array type of unknown size, the size is 1297determined by compound literal size. 1298 1299@smallexample 1300static struct foo x = (struct foo) @{1, 'a', 'b'@}; 1301static int y[] = (int []) @{1, 2, 3@}; 1302static int z[] = (int [3]) @{1@}; 1303@end smallexample 1304 1305@noindent 1306The above lines are equivalent to the following: 1307@smallexample 1308static struct foo x = @{1, 'a', 'b'@}; 1309static int y[] = @{1, 2, 3@}; 1310static int z[] = @{1, 0, 0@}; 1311@end smallexample 1312 1313@node Designated Inits 1314@section Designated Initializers 1315@cindex initializers with labeled elements 1316@cindex labeled elements in initializers 1317@cindex case labels in initializers 1318@cindex designated initializers 1319 1320Standard C89 requires the elements of an initializer to appear in a fixed 1321order, the same as the order of the elements in the array or structure 1322being initialized. 1323 1324In ISO C99 you can give the elements in any order, specifying the array 1325indices or structure field names they apply to, and GNU C allows this as 1326an extension in C89 mode as well. This extension is not 1327implemented in GNU C++. 1328 1329To specify an array index, write 1330@samp{[@var{index}] =} before the element value. For example, 1331 1332@smallexample 1333int a[6] = @{ [4] = 29, [2] = 15 @}; 1334@end smallexample 1335 1336@noindent 1337is equivalent to 1338 1339@smallexample 1340int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; 1341@end smallexample 1342 1343@noindent 1344The index values must be constant expressions, even if the array being 1345initialized is automatic. 1346 1347An alternative syntax for this which has been obsolete since GCC 2.5 but 1348GCC still accepts is to write @samp{[@var{index}]} before the element 1349value, with no @samp{=}. 1350 1351To initialize a range of elements to the same value, write 1352@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU 1353extension. For example, 1354 1355@smallexample 1356int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; 1357@end smallexample 1358 1359@noindent 1360If the value in it has side-effects, the side-effects will happen only once, 1361not for each initialized field by the range initializer. 1362 1363@noindent 1364Note that the length of the array is the highest value specified 1365plus one. 1366 1367In a structure initializer, specify the name of a field to initialize 1368with @samp{.@var{fieldname} =} before the element value. For example, 1369given the following structure, 1370 1371@smallexample 1372struct point @{ int x, y; @}; 1373@end smallexample 1374 1375@noindent 1376the following initialization 1377 1378@smallexample 1379struct point p = @{ .y = yvalue, .x = xvalue @}; 1380@end smallexample 1381 1382@noindent 1383is equivalent to 1384 1385@smallexample 1386struct point p = @{ xvalue, yvalue @}; 1387@end smallexample 1388 1389Another syntax which has the same meaning, obsolete since GCC 2.5, is 1390@samp{@var{fieldname}:}, as shown here: 1391 1392@smallexample 1393struct point p = @{ y: yvalue, x: xvalue @}; 1394@end smallexample 1395 1396@cindex designators 1397The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a 1398@dfn{designator}. You can also use a designator (or the obsolete colon 1399syntax) when initializing a union, to specify which element of the union 1400should be used. For example, 1401 1402@smallexample 1403union foo @{ int i; double d; @}; 1404 1405union foo f = @{ .d = 4 @}; 1406@end smallexample 1407 1408@noindent 1409will convert 4 to a @code{double} to store it in the union using 1410the second element. By contrast, casting 4 to type @code{union foo} 1411would store it into the union as the integer @code{i}, since it is 1412an integer. (@xref{Cast to Union}.) 1413 1414You can combine this technique of naming elements with ordinary C 1415initialization of successive elements. Each initializer element that 1416does not have a designator applies to the next consecutive element of the 1417array or structure. For example, 1418 1419@smallexample 1420int a[6] = @{ [1] = v1, v2, [4] = v4 @}; 1421@end smallexample 1422 1423@noindent 1424is equivalent to 1425 1426@smallexample 1427int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; 1428@end smallexample 1429 1430Labeling the elements of an array initializer is especially useful 1431when the indices are characters or belong to an @code{enum} type. 1432For example: 1433 1434@smallexample 1435int whitespace[256] 1436 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, 1437 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; 1438@end smallexample 1439 1440@cindex designator lists 1441You can also write a series of @samp{.@var{fieldname}} and 1442@samp{[@var{index}]} designators before an @samp{=} to specify a 1443nested subobject to initialize; the list is taken relative to the 1444subobject corresponding to the closest surrounding brace pair. For 1445example, with the @samp{struct point} declaration above: 1446 1447@smallexample 1448struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; 1449@end smallexample 1450 1451@noindent 1452If the same field is initialized multiple times, it will have value from 1453the last initialization. If any such overridden initialization has 1454side-effect, it is unspecified whether the side-effect happens or not. 1455Currently, GCC will discard them and issue a warning. 1456 1457@node Case Ranges 1458@section Case Ranges 1459@cindex case ranges 1460@cindex ranges in case statements 1461 1462You can specify a range of consecutive values in a single @code{case} label, 1463like this: 1464 1465@smallexample 1466case @var{low} ... @var{high}: 1467@end smallexample 1468 1469@noindent 1470This has the same effect as the proper number of individual @code{case} 1471labels, one for each integer value from @var{low} to @var{high}, inclusive. 1472 1473This feature is especially useful for ranges of ASCII character codes: 1474 1475@smallexample 1476case 'A' ... 'Z': 1477@end smallexample 1478 1479@strong{Be careful:} Write spaces around the @code{...}, for otherwise 1480it may be parsed wrong when you use it with integer values. For example, 1481write this: 1482 1483@smallexample 1484case 1 ... 5: 1485@end smallexample 1486 1487@noindent 1488rather than this: 1489 1490@smallexample 1491case 1...5: 1492@end smallexample 1493 1494@node Cast to Union 1495@section Cast to a Union Type 1496@cindex cast to a union 1497@cindex union, casting to a 1498 1499A cast to union type is similar to other casts, except that the type 1500specified is a union type. You can specify the type either with 1501@code{union @var{tag}} or with a typedef name. A cast to union is actually 1502a constructor though, not a cast, and hence does not yield an lvalue like 1503normal casts. (@xref{Compound Literals}.) 1504 1505The types that may be cast to the union type are those of the members 1506of the union. Thus, given the following union and variables: 1507 1508@smallexample 1509union foo @{ int i; double d; @}; 1510int x; 1511double y; 1512@end smallexample 1513 1514@noindent 1515both @code{x} and @code{y} can be cast to type @code{union foo}. 1516 1517Using the cast as the right-hand side of an assignment to a variable of 1518union type is equivalent to storing in a member of the union: 1519 1520@smallexample 1521union foo u; 1522/* @r{@dots{}} */ 1523u = (union foo) x @equiv{} u.i = x 1524u = (union foo) y @equiv{} u.d = y 1525@end smallexample 1526 1527You can also use the union cast as a function argument: 1528 1529@smallexample 1530void hack (union foo); 1531/* @r{@dots{}} */ 1532hack ((union foo) x); 1533@end smallexample 1534 1535@node Mixed Declarations 1536@section Mixed Declarations and Code 1537@cindex mixed declarations and code 1538@cindex declarations, mixed with code 1539@cindex code, mixed with declarations 1540 1541ISO C99 and ISO C++ allow declarations and code to be freely mixed 1542within compound statements. As an extension, GCC also allows this in 1543C89 mode. For example, you could do: 1544 1545@smallexample 1546int i; 1547/* @r{@dots{}} */ 1548i++; 1549int j = i + 2; 1550@end smallexample 1551 1552Each identifier is visible from where it is declared until the end of 1553the enclosing block. 1554 1555@node Function Attributes 1556@section Declaring Attributes of Functions 1557@cindex function attributes 1558@cindex declaring attributes of functions 1559@cindex functions that never return 1560@cindex functions that return more than once 1561@cindex functions that have no side effects 1562@cindex functions in arbitrary sections 1563@cindex functions that behave like malloc 1564@cindex @code{volatile} applied to function 1565@cindex @code{const} applied to function 1566@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments 1567@cindex functions with non-null pointer arguments 1568@cindex functions that are passed arguments in registers on the 386 1569@cindex functions that pop the argument stack on the 386 1570@cindex functions that do not pop the argument stack on the 386 1571 1572In GNU C, you declare certain things about functions called in your program 1573which help the compiler optimize function calls and check your code more 1574carefully. 1575 1576The keyword @code{__attribute__} allows you to specify special 1577attributes when making a declaration. This keyword is followed by an 1578attribute specification inside double parentheses. The following 1579attributes are currently defined for functions on all targets: 1580@code{aligned}, 1581@code{noreturn}, @code{returns_twice}, @code{noinline}, @code{always_inline}, 1582@code{flatten}, @code{pure}, @code{const}, @code{nothrow}, @code{sentinel}, 1583@code{format}, @code{format_arg}, @code{no_instrument_function}, 1584@code{section}, @code{constructor}, @code{destructor}, @code{used}, 1585@code{unused}, @code{deprecated}, @code{weak}, @code{malloc}, 1586@code{alias}, @code{warn_unused_result}, @code{nonnull}, 1587@code{gnu_inline} and @code{externally_visible}. Several other 1588attributes are defined for functions on particular target systems. Other 1589attributes, including @code{section} are supported for variables declarations 1590(@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}). 1591 1592You may also specify attributes with @samp{__} preceding and following 1593each keyword. This allows you to use them in header files without 1594being concerned about a possible macro of the same name. For example, 1595you may use @code{__noreturn__} instead of @code{noreturn}. 1596 1597@xref{Attribute Syntax}, for details of the exact syntax for using 1598attributes. 1599 1600@table @code 1601@c Keep this table alphabetized by attribute name. Treat _ as space. 1602 1603@item alias ("@var{target}") 1604@cindex @code{alias} attribute 1605The @code{alias} attribute causes the declaration to be emitted as an 1606alias for another symbol, which must be specified. For instance, 1607 1608@smallexample 1609void __f () @{ /* @r{Do something.} */; @} 1610void f () __attribute__ ((weak, alias ("__f"))); 1611@end smallexample 1612 1613defines @samp{f} to be a weak alias for @samp{__f}. In C++, the 1614mangled name for the target must be used. It is an error if @samp{__f} 1615is not defined in the same translation unit. 1616 1617Not all target machines support this attribute. 1618 1619@item aligned (@var{alignment}) 1620@cindex @code{aligned} attribute 1621This attribute specifies a minimum alignment for the function, 1622measured in bytes. 1623 1624You cannot use this attribute to decrease the alignment of a function, 1625only to increase it. However, when you explicitly specify a function 1626alignment this will override the effect of the 1627@option{-falign-functions} (@pxref{Optimize Options}) option for this 1628function. 1629 1630Note that the effectiveness of @code{aligned} attributes may be 1631limited by inherent limitations in your linker. On many systems, the 1632linker is only able to arrange for functions to be aligned up to a 1633certain maximum alignment. (For some linkers, the maximum supported 1634alignment may be very very small.) See your linker documentation for 1635further information. 1636 1637The @code{aligned} attribute can also be used for variables and fields 1638(@pxref{Variable Attributes}.) 1639 1640@item always_inline 1641@cindex @code{always_inline} function attribute 1642Generally, functions are not inlined unless optimization is specified. 1643For functions declared inline, this attribute inlines the function even 1644if no optimization level was specified. 1645 1646@item gnu_inline 1647@cindex @code{gnu_inline} function attribute 1648This attribute should be used with a function which is also declared 1649with the @code{inline} keyword. It directs GCC to treat the function 1650as if it were defined in gnu89 mode even when compiling in C99 or 1651gnu99 mode. 1652 1653If the function is declared @code{extern}, then this definition of the 1654function is used only for inlining. In no case is the function 1655compiled as a standalone function, not even if you take its address 1656explicitly. Such an address becomes an external reference, as if you 1657had only declared the function, and had not defined it. This has 1658almost the effect of a macro. The way to use this is to put a 1659function definition in a header file with this attribute, and put 1660another copy of the function, without @code{extern}, in a library 1661file. The definition in the header file will cause most calls to the 1662function to be inlined. If any uses of the function remain, they will 1663refer to the single copy in the library. Note that the two 1664definitions of the functions need not be precisely the same, although 1665if they do not have the same effect your program may behave oddly. 1666 1667If the function is neither @code{extern} nor @code{static}, then the 1668function is compiled as a standalone function, as well as being 1669inlined where possible. 1670 1671This is how GCC traditionally handled functions declared 1672@code{inline}. Since ISO C99 specifies a different semantics for 1673@code{inline}, this function attribute is provided as a transition 1674measure and as a useful feature in its own right. This attribute is 1675available in GCC 4.1.3 and later. It is available if either of the 1676preprocessor macros @code{__GNUC_GNU_INLINE__} or 1677@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline 1678Function is As Fast As a Macro}. 1679 1680Note that since the first version of GCC to support C99 inline semantics 1681is 4.3, earlier versions of GCC which accept this attribute effectively 1682assume that it is always present, whether or not it is given explicitly. 1683In versions prior to 4.3, the only effect of explicitly including it is 1684to disable warnings about using inline functions in C99 mode. 1685 1686@cindex @code{flatten} function attribute 1687@item flatten 1688Generally, inlining into a function is limited. For a function marked with 1689this attribute, every call inside this function will be inlined, if possible. 1690Whether the function itself is considered for inlining depends on its size and 1691the current inlining parameters. The @code{flatten} attribute only works 1692reliably in unit-at-a-time mode. 1693 1694@item cdecl 1695@cindex functions that do pop the argument stack on the 386 1696@opindex mrtd 1697On the Intel 386, the @code{cdecl} attribute causes the compiler to 1698assume that the calling function will pop off the stack space used to 1699pass arguments. This is 1700useful to override the effects of the @option{-mrtd} switch. 1701 1702@item const 1703@cindex @code{const} function attribute 1704Many functions do not examine any values except their arguments, and 1705have no effects except the return value. Basically this is just slightly 1706more strict class than the @code{pure} attribute below, since function is not 1707allowed to read global memory. 1708 1709@cindex pointer arguments 1710Note that a function that has pointer arguments and examines the data 1711pointed to must @emph{not} be declared @code{const}. Likewise, a 1712function that calls a non-@code{const} function usually must not be 1713@code{const}. It does not make sense for a @code{const} function to 1714return @code{void}. 1715 1716The attribute @code{const} is not implemented in GCC versions earlier 1717than 2.5. An alternative way to declare that a function has no side 1718effects, which works in the current version and in some older versions, 1719is as follows: 1720 1721@smallexample 1722typedef int intfn (); 1723 1724extern const intfn square; 1725@end smallexample 1726 1727This approach does not work in GNU C++ from 2.6.0 on, since the language 1728specifies that the @samp{const} must be attached to the return value. 1729 1730@item constructor 1731@itemx destructor 1732@cindex @code{constructor} function attribute 1733@cindex @code{destructor} function attribute 1734The @code{constructor} attribute causes the function to be called 1735automatically before execution enters @code{main ()}. Similarly, the 1736@code{destructor} attribute causes the function to be called 1737automatically after @code{main ()} has completed or @code{exit ()} has 1738been called. Functions with these attributes are useful for 1739initializing data that will be used implicitly during the execution of 1740the program. 1741 1742@item deprecated 1743@cindex @code{deprecated} attribute. 1744The @code{deprecated} attribute results in a warning if the function 1745is used anywhere in the source file. This is useful when identifying 1746functions that are expected to be removed in a future version of a 1747program. The warning also includes the location of the declaration 1748of the deprecated function, to enable users to easily find further 1749information about why the function is deprecated, or what they should 1750do instead. Note that the warnings only occurs for uses: 1751 1752@smallexample 1753int old_fn () __attribute__ ((deprecated)); 1754int old_fn (); 1755int (*fn_ptr)() = old_fn; 1756@end smallexample 1757 1758results in a warning on line 3 but not line 2. 1759 1760The @code{deprecated} attribute can also be used for variables and 1761types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) 1762 1763@item dllexport 1764@cindex @code{__declspec(dllexport)} 1765On Microsoft Windows targets and Symbian OS targets the 1766@code{dllexport} attribute causes the compiler to provide a global 1767pointer to a pointer in a DLL, so that it can be referenced with the 1768@code{dllimport} attribute. On Microsoft Windows targets, the pointer 1769name is formed by combining @code{_imp__} and the function or variable 1770name. 1771 1772You can use @code{__declspec(dllexport)} as a synonym for 1773@code{__attribute__ ((dllexport))} for compatibility with other 1774compilers. 1775 1776On systems that support the @code{visibility} attribute, this 1777attribute also implies ``default'' visibility, unless a 1778@code{visibility} attribute is explicitly specified. You should avoid 1779the use of @code{dllexport} with ``hidden'' or ``internal'' 1780visibility; in the future GCC may issue an error for those cases. 1781 1782Currently, the @code{dllexport} attribute is ignored for inlined 1783functions, unless the @option{-fkeep-inline-functions} flag has been 1784used. The attribute is also ignored for undefined symbols. 1785 1786When applied to C++ classes, the attribute marks defined non-inlined 1787member functions and static data members as exports. Static consts 1788initialized in-class are not marked unless they are also defined 1789out-of-class. 1790 1791For Microsoft Windows targets there are alternative methods for 1792including the symbol in the DLL's export table such as using a 1793@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using 1794the @option{--export-all} linker flag. 1795 1796@item dllimport 1797@cindex @code{__declspec(dllimport)} 1798On Microsoft Windows and Symbian OS targets, the @code{dllimport} 1799attribute causes the compiler to reference a function or variable via 1800a global pointer to a pointer that is set up by the DLL exporting the 1801symbol. The attribute implies @code{extern} storage. On Microsoft 1802Windows targets, the pointer name is formed by combining @code{_imp__} 1803and the function or variable name. 1804 1805You can use @code{__declspec(dllimport)} as a synonym for 1806@code{__attribute__ ((dllimport))} for compatibility with other 1807compilers. 1808 1809Currently, the attribute is ignored for inlined functions. If the 1810attribute is applied to a symbol @emph{definition}, an error is reported. 1811If a symbol previously declared @code{dllimport} is later defined, the 1812attribute is ignored in subsequent references, and a warning is emitted. 1813The attribute is also overridden by a subsequent declaration as 1814@code{dllexport}. 1815 1816When applied to C++ classes, the attribute marks non-inlined 1817member functions and static data members as imports. However, the 1818attribute is ignored for virtual methods to allow creation of vtables 1819using thunks. 1820 1821On the SH Symbian OS target the @code{dllimport} attribute also has 1822another affect---it can cause the vtable and run-time type information 1823for a class to be exported. This happens when the class has a 1824dllimport'ed constructor or a non-inline, non-pure virtual function 1825and, for either of those two conditions, the class also has a inline 1826constructor or destructor and has a key function that is defined in 1827the current translation unit. 1828 1829For Microsoft Windows based targets the use of the @code{dllimport} 1830attribute on functions is not necessary, but provides a small 1831performance benefit by eliminating a thunk in the DLL@. The use of the 1832@code{dllimport} attribute on imported variables was required on older 1833versions of the GNU linker, but can now be avoided by passing the 1834@option{--enable-auto-import} switch to the GNU linker. As with 1835functions, using the attribute for a variable eliminates a thunk in 1836the DLL@. 1837 1838One drawback to using this attribute is that a pointer to a function 1839or variable marked as @code{dllimport} cannot be used as a constant 1840address. On Microsoft Windows targets, the attribute can be disabled 1841for functions by setting the @option{-mnop-fun-dllimport} flag. 1842 1843@item eightbit_data 1844@cindex eight bit data on the H8/300, H8/300H, and H8S 1845Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 1846variable should be placed into the eight bit data section. 1847The compiler will generate more efficient code for certain operations 1848on data in the eight bit data area. Note the eight bit data area is limited to 1849256 bytes of data. 1850 1851You must use GAS and GLD from GNU binutils version 2.7 or later for 1852this attribute to work correctly. 1853 1854@item exception_handler 1855@cindex exception handler functions on the Blackfin processor 1856Use this attribute on the Blackfin to indicate that the specified function 1857is an exception handler. The compiler will generate function entry and 1858exit sequences suitable for use in an exception handler when this 1859attribute is present. 1860 1861@item far 1862@cindex functions which handle memory bank switching 1863On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to 1864use a calling convention that takes care of switching memory banks when 1865entering and leaving a function. This calling convention is also the 1866default when using the @option{-mlong-calls} option. 1867 1868On 68HC12 the compiler will use the @code{call} and @code{rtc} instructions 1869to call and return from a function. 1870 1871On 68HC11 the compiler will generate a sequence of instructions 1872to invoke a board-specific routine to switch the memory bank and call the 1873real function. The board-specific routine simulates a @code{call}. 1874At the end of a function, it will jump to a board-specific routine 1875instead of using @code{rts}. The board-specific return routine simulates 1876the @code{rtc}. 1877 1878@item fastcall 1879@cindex functions that pop the argument stack on the 386 1880On the Intel 386, the @code{fastcall} attribute causes the compiler to 1881pass the first argument (if of integral type) in the register ECX and 1882the second argument (if of integral type) in the register EDX@. Subsequent 1883and other typed arguments are passed on the stack. The called function will 1884pop the arguments off the stack. If the number of arguments is variable all 1885arguments are pushed on the stack. 1886 1887@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) 1888@cindex @code{format} function attribute 1889@opindex Wformat 1890The @code{format} attribute specifies that a function takes @code{printf}, 1891@code{scanf}, @code{strftime} or @code{strfmon} style arguments which 1892should be type-checked against a format string. For example, the 1893declaration: 1894 1895@smallexample 1896extern int 1897my_printf (void *my_object, const char *my_format, ...) 1898 __attribute__ ((format (printf, 2, 3))); 1899@end smallexample 1900 1901@noindent 1902causes the compiler to check the arguments in calls to @code{my_printf} 1903for consistency with the @code{printf} style format string argument 1904@code{my_format}. 1905 1906The parameter @var{archetype} determines how the format string is 1907interpreted, and should be @code{printf}, @code{scanf}, @code{strftime} 1908or @code{strfmon}. (You can also use @code{__printf__}, 1909@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) The 1910parameter @var{string-index} specifies which argument is the format 1911string argument (starting from 1), while @var{first-to-check} is the 1912number of the first argument to check against the format string. For 1913functions where the arguments are not available to be checked (such as 1914@code{vprintf}), specify the third parameter as zero. In this case the 1915compiler only checks the format string for consistency. For 1916@code{strftime} formats, the third parameter is required to be zero. 1917Since non-static C++ methods have an implicit @code{this} argument, the 1918arguments of such methods should be counted from two, not one, when 1919giving values for @var{string-index} and @var{first-to-check}. 1920 1921In the example above, the format string (@code{my_format}) is the second 1922argument of the function @code{my_print}, and the arguments to check 1923start with the third argument, so the correct parameters for the format 1924attribute are 2 and 3. 1925 1926@opindex ffreestanding 1927@opindex fno-builtin 1928The @code{format} attribute allows you to identify your own functions 1929which take format strings as arguments, so that GCC can check the 1930calls to these functions for errors. The compiler always (unless 1931@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats 1932for the standard library functions @code{printf}, @code{fprintf}, 1933@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, 1934@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such 1935warnings are requested (using @option{-Wformat}), so there is no need to 1936modify the header file @file{stdio.h}. In C99 mode, the functions 1937@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and 1938@code{vsscanf} are also checked. Except in strictly conforming C 1939standard modes, the X/Open function @code{strfmon} is also checked as 1940are @code{printf_unlocked} and @code{fprintf_unlocked}. 1941@xref{C Dialect Options,,Options Controlling C Dialect}. 1942 1943The target may provide additional types of format checks. 1944@xref{Target Format Checks,,Format Checks Specific to Particular 1945Target Machines}. 1946 1947@item format_arg (@var{string-index}) 1948@cindex @code{format_arg} function attribute 1949@opindex Wformat-nonliteral 1950The @code{format_arg} attribute specifies that a function takes a format 1951string for a @code{printf}, @code{scanf}, @code{strftime} or 1952@code{strfmon} style function and modifies it (for example, to translate 1953it into another language), so the result can be passed to a 1954@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style 1955function (with the remaining arguments to the format function the same 1956as they would have been for the unmodified string). For example, the 1957declaration: 1958 1959@smallexample 1960extern char * 1961my_dgettext (char *my_domain, const char *my_format) 1962 __attribute__ ((format_arg (2))); 1963@end smallexample 1964 1965@noindent 1966causes the compiler to check the arguments in calls to a @code{printf}, 1967@code{scanf}, @code{strftime} or @code{strfmon} type function, whose 1968format string argument is a call to the @code{my_dgettext} function, for 1969consistency with the format string argument @code{my_format}. If the 1970@code{format_arg} attribute had not been specified, all the compiler 1971could tell in such calls to format functions would be that the format 1972string argument is not constant; this would generate a warning when 1973@option{-Wformat-nonliteral} is used, but the calls could not be checked 1974without the attribute. 1975 1976The parameter @var{string-index} specifies which argument is the format 1977string argument (starting from one). Since non-static C++ methods have 1978an implicit @code{this} argument, the arguments of such methods should 1979be counted from two. 1980 1981The @code{format-arg} attribute allows you to identify your own 1982functions which modify format strings, so that GCC can check the 1983calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} 1984type function whose operands are a call to one of your own function. 1985The compiler always treats @code{gettext}, @code{dgettext}, and 1986@code{dcgettext} in this manner except when strict ISO C support is 1987requested by @option{-ansi} or an appropriate @option{-std} option, or 1988@option{-ffreestanding} or @option{-fno-builtin} 1989is used. @xref{C Dialect Options,,Options 1990Controlling C Dialect}. 1991 1992@item function_vector 1993@cindex calling functions through the function vector on the H8/300 processors 1994Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 1995function should be called through the function vector. Calling a 1996function through the function vector will reduce code size, however; 1997the function vector has a limited size (maximum 128 entries on the H8/300 1998and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector. 1999 2000You must use GAS and GLD from GNU binutils version 2.7 or later for 2001this attribute to work correctly. 2002 2003@item interrupt 2004@cindex interrupt handler functions 2005Use this attribute on the ARM, AVR, C4x, CRX, M32C, M32R/D, MS1, and Xstormy16 2006ports to indicate that the specified function is an interrupt handler. 2007The compiler will generate function entry and exit sequences suitable 2008for use in an interrupt handler when this attribute is present. 2009 2010Note, interrupt handlers for the Blackfin, m68k, H8/300, H8/300H, H8S, and 2011SH processors can be specified via the @code{interrupt_handler} attribute. 2012 2013Note, on the AVR, interrupts will be enabled inside the function. 2014 2015Note, for the ARM, you can specify the kind of interrupt to be handled by 2016adding an optional parameter to the interrupt attribute like this: 2017 2018@smallexample 2019void f () __attribute__ ((interrupt ("IRQ"))); 2020@end smallexample 2021 2022Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@. 2023 2024@item interrupt_handler 2025@cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors 2026Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to 2027indicate that the specified function is an interrupt handler. The compiler 2028will generate function entry and exit sequences suitable for use in an 2029interrupt handler when this attribute is present. 2030 2031@item kspisusp 2032@cindex User stack pointer in interrupts on the Blackfin 2033When used together with @code{interrupt_handler}, @code{exception_handler} 2034or @code{nmi_handler}, code will be generated to load the stack pointer 2035from the USP register in the function prologue. 2036 2037@item long_call/short_call 2038@cindex indirect calls on ARM 2039This attribute specifies how a particular function is called on 2040ARM@. Both attributes override the @option{-mlong-calls} (@pxref{ARM Options}) 2041command line switch and @code{#pragma long_calls} settings. The 2042@code{long_call} attribute indicates that the function might be far 2043away from the call site and require a different (more expensive) 2044calling sequence. The @code{short_call} attribute always places 2045the offset to the function from the call site into the @samp{BL} 2046instruction directly. 2047 2048@item longcall/shortcall 2049@cindex functions called via pointer on the RS/6000 and PowerPC 2050On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute 2051indicates that the function might be far away from the call site and 2052require a different (more expensive) calling sequence. The 2053@code{shortcall} attribute indicates that the function is always close 2054enough for the shorter calling sequence to be used. These attributes 2055override both the @option{-mlongcall} switch and, on the RS/6000 and 2056PowerPC, the @code{#pragma longcall} setting. 2057 2058@xref{RS/6000 and PowerPC Options}, for more information on whether long 2059calls are necessary. 2060 2061@item long_call 2062@cindex indirect calls on MIPS 2063This attribute specifies how a particular function is called on MIPS@. 2064The attribute overrides the @option{-mlong-calls} (@pxref{MIPS Options}) 2065command line switch. This attribute causes the compiler to always call 2066the function by first loading its address into a register, and then using 2067the contents of that register. 2068 2069@item malloc 2070@cindex @code{malloc} attribute 2071The @code{malloc} attribute is used to tell the compiler that a function 2072may be treated as if any non-@code{NULL} pointer it returns cannot 2073alias any other pointer valid when the function returns. 2074This will often improve optimization. 2075Standard functions with this property include @code{malloc} and 2076@code{calloc}. @code{realloc}-like functions have this property as 2077long as the old pointer is never referred to (including comparing it 2078to the new pointer) after the function returns a non-@code{NULL} 2079value. 2080 2081@item model (@var{model-name}) 2082@cindex function addressability on the M32R/D 2083@cindex variable addressability on the IA-64 2084 2085On the M32R/D, use this attribute to set the addressability of an 2086object, and of the code generated for a function. The identifier 2087@var{model-name} is one of @code{small}, @code{medium}, or 2088@code{large}, representing each of the code models. 2089 2090Small model objects live in the lower 16MB of memory (so that their 2091addresses can be loaded with the @code{ld24} instruction), and are 2092callable with the @code{bl} instruction. 2093 2094Medium model objects may live anywhere in the 32-bit address space (the 2095compiler will generate @code{seth/add3} instructions to load their addresses), 2096and are callable with the @code{bl} instruction. 2097 2098Large model objects may live anywhere in the 32-bit address space (the 2099compiler will generate @code{seth/add3} instructions to load their addresses), 2100and may not be reachable with the @code{bl} instruction (the compiler will 2101generate the much slower @code{seth/add3/jl} instruction sequence). 2102 2103On IA-64, use this attribute to set the addressability of an object. 2104At present, the only supported identifier for @var{model-name} is 2105@code{small}, indicating addressability via ``small'' (22-bit) 2106addresses (so that their addresses can be loaded with the @code{addl} 2107instruction). Caveat: such addressing is by definition not position 2108independent and hence this attribute must not be used for objects 2109defined by shared libraries. 2110 2111@item naked 2112@cindex function without a prologue/epilogue code 2113Use this attribute on the ARM, AVR, C4x and IP2K ports to indicate that the 2114specified function does not need prologue/epilogue sequences generated by 2115the compiler. It is up to the programmer to provide these sequences. 2116 2117@item near 2118@cindex functions which do not handle memory bank switching on 68HC11/68HC12 2119On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to 2120use the normal calling convention based on @code{jsr} and @code{rts}. 2121This attribute can be used to cancel the effect of the @option{-mlong-calls} 2122option. 2123 2124@item nesting 2125@cindex Allow nesting in an interrupt handler on the Blackfin processor. 2126Use this attribute together with @code{interrupt_handler}, 2127@code{exception_handler} or @code{nmi_handler} to indicate that the function 2128entry code should enable nested interrupts or exceptions. 2129 2130@item nmi_handler 2131@cindex NMI handler functions on the Blackfin processor 2132Use this attribute on the Blackfin to indicate that the specified function 2133is an NMI handler. The compiler will generate function entry and 2134exit sequences suitable for use in an NMI handler when this 2135attribute is present. 2136 2137@item no_instrument_function 2138@cindex @code{no_instrument_function} function attribute 2139@opindex finstrument-functions 2140If @option{-finstrument-functions} is given, profiling function calls will 2141be generated at entry and exit of most user-compiled functions. 2142Functions with this attribute will not be so instrumented. 2143 2144@item noinline 2145@cindex @code{noinline} function attribute 2146This function attribute prevents a function from being considered for 2147inlining. 2148 2149@item nonnull (@var{arg-index}, @dots{}) 2150@cindex @code{nonnull} function attribute 2151The @code{nonnull} attribute specifies that some function parameters should 2152be non-null pointers. For instance, the declaration: 2153 2154@smallexample 2155extern void * 2156my_memcpy (void *dest, const void *src, size_t len) 2157 __attribute__((nonnull (1, 2))); 2158@end smallexample 2159 2160@noindent 2161causes the compiler to check that, in calls to @code{my_memcpy}, 2162arguments @var{dest} and @var{src} are non-null. If the compiler 2163determines that a null pointer is passed in an argument slot marked 2164as non-null, and the @option{-Wnonnull} option is enabled, a warning 2165is issued. The compiler may also choose to make optimizations based 2166on the knowledge that certain function arguments will not be null. 2167 2168If no argument index list is given to the @code{nonnull} attribute, 2169all pointer arguments are marked as non-null. To illustrate, the 2170following declaration is equivalent to the previous example: 2171 2172@smallexample 2173extern void * 2174my_memcpy (void *dest, const void *src, size_t len) 2175 __attribute__((nonnull)); 2176@end smallexample 2177 2178@item noreturn 2179@cindex @code{noreturn} function attribute 2180A few standard library functions, such as @code{abort} and @code{exit}, 2181cannot return. GCC knows this automatically. Some programs define 2182their own functions that never return. You can declare them 2183@code{noreturn} to tell the compiler this fact. For example, 2184 2185@smallexample 2186@group 2187void fatal () __attribute__ ((noreturn)); 2188 2189void 2190fatal (/* @r{@dots{}} */) 2191@{ 2192 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ 2193 exit (1); 2194@} 2195@end group 2196@end smallexample 2197 2198The @code{noreturn} keyword tells the compiler to assume that 2199@code{fatal} cannot return. It can then optimize without regard to what 2200would happen if @code{fatal} ever did return. This makes slightly 2201better code. More importantly, it helps avoid spurious warnings of 2202uninitialized variables. 2203 2204The @code{noreturn} keyword does not affect the exceptional path when that 2205applies: a @code{noreturn}-marked function may still return to the caller 2206by throwing an exception or calling @code{longjmp}. 2207 2208Do not assume that registers saved by the calling function are 2209restored before calling the @code{noreturn} function. 2210 2211It does not make sense for a @code{noreturn} function to have a return 2212type other than @code{void}. 2213 2214The attribute @code{noreturn} is not implemented in GCC versions 2215earlier than 2.5. An alternative way to declare that a function does 2216not return, which works in the current version and in some older 2217versions, is as follows: 2218 2219@smallexample 2220typedef void voidfn (); 2221 2222volatile voidfn fatal; 2223@end smallexample 2224 2225This approach does not work in GNU C++. 2226 2227@item nothrow 2228@cindex @code{nothrow} function attribute 2229The @code{nothrow} attribute is used to inform the compiler that a 2230function cannot throw an exception. For example, most functions in 2231the standard C library can be guaranteed not to throw an exception 2232with the notable exceptions of @code{qsort} and @code{bsearch} that 2233take function pointer arguments. The @code{nothrow} attribute is not 2234implemented in GCC versions earlier than 3.3. 2235 2236@item pure 2237@cindex @code{pure} function attribute 2238Many functions have no effects except the return value and their 2239return value depends only on the parameters and/or global variables. 2240Such a function can be subject 2241to common subexpression elimination and loop optimization just as an 2242arithmetic operator would be. These functions should be declared 2243with the attribute @code{pure}. For example, 2244 2245@smallexample 2246int square (int) __attribute__ ((pure)); 2247@end smallexample 2248 2249@noindent 2250says that the hypothetical function @code{square} is safe to call 2251fewer times than the program says. 2252 2253Some of common examples of pure functions are @code{strlen} or @code{memcmp}. 2254Interesting non-pure functions are functions with infinite loops or those 2255depending on volatile memory or other system resource, that may change between 2256two consecutive calls (such as @code{feof} in a multithreading environment). 2257 2258The attribute @code{pure} is not implemented in GCC versions earlier 2259than 2.96. 2260 2261@item regparm (@var{number}) 2262@cindex @code{regparm} attribute 2263@cindex functions that are passed arguments in registers on the 386 2264On the Intel 386, the @code{regparm} attribute causes the compiler to 2265pass arguments number one to @var{number} if they are of integral type 2266in registers EAX, EDX, and ECX instead of on the stack. Functions that 2267take a variable number of arguments will continue to be passed all of their 2268arguments on the stack. 2269 2270Beware that on some ELF systems this attribute is unsuitable for 2271global functions in shared libraries with lazy binding (which is the 2272default). Lazy binding will send the first call via resolving code in 2273the loader, which might assume EAX, EDX and ECX can be clobbered, as 2274per the standard calling conventions. Solaris 8 is affected by this. 2275GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be 2276safe since the loaders there save all registers. (Lazy binding can be 2277disabled with the linker or the loader if desired, to avoid the 2278problem.) 2279 2280@item sseregparm 2281@cindex @code{sseregparm} attribute 2282On the Intel 386 with SSE support, the @code{sseregparm} attribute 2283causes the compiler to pass up to 3 floating point arguments in 2284SSE registers instead of on the stack. Functions that take a 2285variable number of arguments will continue to pass all of their 2286floating point arguments on the stack. 2287 2288@item force_align_arg_pointer 2289@cindex @code{force_align_arg_pointer} attribute 2290On the Intel x86, the @code{force_align_arg_pointer} attribute may be 2291applied to individual function definitions, generating an alternate 2292prologue and epilogue that realigns the runtime stack. This supports 2293mixing legacy codes that run with a 4-byte aligned stack with modern 2294codes that keep a 16-byte stack for SSE compatibility. The alternate 2295prologue and epilogue are slower and bigger than the regular ones, and 2296the alternate prologue requires a scratch register; this lowers the 2297number of registers available if used in conjunction with the 2298@code{regparm} attribute. The @code{force_align_arg_pointer} 2299attribute is incompatible with nested functions; this is considered a 2300hard error. 2301 2302@item returns_twice 2303@cindex @code{returns_twice} attribute 2304The @code{returns_twice} attribute tells the compiler that a function may 2305return more than one time. The compiler will ensure that all registers 2306are dead before calling such a function and will emit a warning about 2307the variables that may be clobbered after the second return from the 2308function. Examples of such functions are @code{setjmp} and @code{vfork}. 2309The @code{longjmp}-like counterpart of such function, if any, might need 2310to be marked with the @code{noreturn} attribute. 2311 2312@item saveall 2313@cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S 2314Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that 2315all registers except the stack pointer should be saved in the prologue 2316regardless of whether they are used or not. 2317 2318@item section ("@var{section-name}") 2319@cindex @code{section} function attribute 2320Normally, the compiler places the code it generates in the @code{text} section. 2321Sometimes, however, you need additional sections, or you need certain 2322particular functions to appear in special sections. The @code{section} 2323attribute specifies that a function lives in a particular section. 2324For example, the declaration: 2325 2326@smallexample 2327extern void foobar (void) __attribute__ ((section ("bar"))); 2328@end smallexample 2329 2330@noindent 2331puts the function @code{foobar} in the @code{bar} section. 2332 2333Some file formats do not support arbitrary sections so the @code{section} 2334attribute is not available on all platforms. 2335If you need to map the entire contents of a module to a particular 2336section, consider using the facilities of the linker instead. 2337 2338@item sentinel 2339@cindex @code{sentinel} function attribute 2340This function attribute ensures that a parameter in a function call is 2341an explicit @code{NULL}. The attribute is only valid on variadic 2342functions. By default, the sentinel is located at position zero, the 2343last parameter of the function call. If an optional integer position 2344argument P is supplied to the attribute, the sentinel must be located at 2345position P counting backwards from the end of the argument list. 2346 2347@smallexample 2348__attribute__ ((sentinel)) 2349is equivalent to 2350__attribute__ ((sentinel(0))) 2351@end smallexample 2352 2353The attribute is automatically set with a position of 0 for the built-in 2354functions @code{execl} and @code{execlp}. The built-in function 2355@code{execle} has the attribute set with a position of 1. 2356 2357A valid @code{NULL} in this context is defined as zero with any pointer 2358type. If your system defines the @code{NULL} macro with an integer type 2359then you need to add an explicit cast. GCC replaces @code{stddef.h} 2360with a copy that redefines NULL appropriately. 2361 2362The warnings for missing or incorrect sentinels are enabled with 2363@option{-Wformat}. 2364 2365@item short_call 2366See long_call/short_call. 2367 2368@item shortcall 2369See longcall/shortcall. 2370 2371@item signal 2372@cindex signal handler functions on the AVR processors 2373Use this attribute on the AVR to indicate that the specified 2374function is a signal handler. The compiler will generate function 2375entry and exit sequences suitable for use in a signal handler when this 2376attribute is present. Interrupts will be disabled inside the function. 2377 2378@item sp_switch 2379Use this attribute on the SH to indicate an @code{interrupt_handler} 2380function should switch to an alternate stack. It expects a string 2381argument that names a global variable holding the address of the 2382alternate stack. 2383 2384@smallexample 2385void *alt_stack; 2386void f () __attribute__ ((interrupt_handler, 2387 sp_switch ("alt_stack"))); 2388@end smallexample 2389 2390@item stdcall 2391@cindex functions that pop the argument stack on the 386 2392On the Intel 386, the @code{stdcall} attribute causes the compiler to 2393assume that the called function will pop off the stack space used to 2394pass arguments, unless it takes a variable number of arguments. 2395 2396@item tiny_data 2397@cindex tiny data section on the H8/300H and H8S 2398Use this attribute on the H8/300H and H8S to indicate that the specified 2399variable should be placed into the tiny data section. 2400The compiler will generate more efficient code for loads and stores 2401on data in the tiny data section. Note the tiny data area is limited to 2402slightly under 32kbytes of data. 2403 2404@item trap_exit 2405Use this attribute on the SH for an @code{interrupt_handler} to return using 2406@code{trapa} instead of @code{rte}. This attribute expects an integer 2407argument specifying the trap number to be used. 2408 2409@item unused 2410@cindex @code{unused} attribute. 2411This attribute, attached to a function, means that the function is meant 2412to be possibly unused. GCC will not produce a warning for this 2413function. 2414 2415@item used 2416@cindex @code{used} attribute. 2417This attribute, attached to a function, means that code must be emitted 2418for the function even if it appears that the function is not referenced. 2419This is useful, for example, when the function is referenced only in 2420inline assembly. 2421 2422@item visibility ("@var{visibility_type}") 2423@cindex @code{visibility} attribute 2424This attribute affects the linkage of the declaration to which it is attached. 2425There are four supported @var{visibility_type} values: default, 2426hidden, protected or internal visibility. 2427 2428@smallexample 2429void __attribute__ ((visibility ("protected"))) 2430f () @{ /* @r{Do something.} */; @} 2431int i __attribute__ ((visibility ("hidden"))); 2432@end smallexample 2433 2434The possible values of @var{visibility_type} correspond to the 2435visibility settings in the ELF gABI. 2436 2437@table @dfn 2438@c keep this list of visibilities in alphabetical order. 2439 2440@item default 2441Default visibility is the normal case for the object file format. 2442This value is available for the visibility attribute to override other 2443options that may change the assumed visibility of entities. 2444 2445On ELF, default visibility means that the declaration is visible to other 2446modules and, in shared libraries, means that the declared entity may be 2447overridden. 2448 2449On Darwin, default visibility means that the declaration is visible to 2450other modules. 2451 2452Default visibility corresponds to ``external linkage'' in the language. 2453 2454@item hidden 2455Hidden visibility indicates that the entity declared will have a new 2456form of linkage, which we'll call ``hidden linkage''. Two 2457declarations of an object with hidden linkage refer to the same object 2458if they are in the same shared object. 2459 2460@item internal 2461Internal visibility is like hidden visibility, but with additional 2462processor specific semantics. Unless otherwise specified by the 2463psABI, GCC defines internal visibility to mean that a function is 2464@emph{never} called from another module. Compare this with hidden 2465functions which, while they cannot be referenced directly by other 2466modules, can be referenced indirectly via function pointers. By 2467indicating that a function cannot be called from outside the module, 2468GCC may for instance omit the load of a PIC register since it is known 2469that the calling function loaded the correct value. 2470 2471@item protected 2472Protected visibility is like default visibility except that it 2473indicates that references within the defining module will bind to the 2474definition in that module. That is, the declared entity cannot be 2475overridden by another module. 2476 2477@end table 2478 2479All visibilities are supported on many, but not all, ELF targets 2480(supported when the assembler supports the @samp{.visibility} 2481pseudo-op). Default visibility is supported everywhere. Hidden 2482visibility is supported on Darwin targets. 2483 2484The visibility attribute should be applied only to declarations which 2485would otherwise have external linkage. The attribute should be applied 2486consistently, so that the same entity should not be declared with 2487different settings of the attribute. 2488 2489In C++, the visibility attribute applies to types as well as functions 2490and objects, because in C++ types have linkage. A class must not have 2491greater visibility than its non-static data member types and bases, 2492and class members default to the visibility of their class. Also, a 2493declaration without explicit visibility is limited to the visibility 2494of its type. 2495 2496In C++, you can mark member functions and static member variables of a 2497class with the visibility attribute. This is useful if if you know a 2498particular method or static member variable should only be used from 2499one shared object; then you can mark it hidden while the rest of the 2500class has default visibility. Care must be taken to avoid breaking 2501the One Definition Rule; for example, it is usually not useful to mark 2502an inline method as hidden without marking the whole class as hidden. 2503 2504A C++ namespace declaration can also have the visibility attribute. 2505This attribute applies only to the particular namespace body, not to 2506other definitions of the same namespace; it is equivalent to using 2507@samp{#pragma GCC visibility} before and after the namespace 2508definition (@pxref{Visibility Pragmas}). 2509 2510In C++, if a template argument has limited visibility, this 2511restriction is implicitly propagated to the template instantiation. 2512Otherwise, template instantiations and specializations default to the 2513visibility of their template. 2514 2515If both the template and enclosing class have explicit visibility, the 2516visibility from the template is used. 2517 2518@item warn_unused_result 2519@cindex @code{warn_unused_result} attribute 2520The @code{warn_unused_result} attribute causes a warning to be emitted 2521if a caller of the function with this attribute does not use its 2522return value. This is useful for functions where not checking 2523the result is either a security problem or always a bug, such as 2524@code{realloc}. 2525 2526@smallexample 2527int fn () __attribute__ ((warn_unused_result)); 2528int foo () 2529@{ 2530 if (fn () < 0) return -1; 2531 fn (); 2532 return 0; 2533@} 2534@end smallexample 2535 2536results in warning on line 5. 2537 2538@item weak 2539@cindex @code{weak} attribute 2540The @code{weak} attribute causes the declaration to be emitted as a weak 2541symbol rather than a global. This is primarily useful in defining 2542library functions which can be overridden in user code, though it can 2543also be used with non-function declarations. Weak symbols are supported 2544for ELF targets, and also for a.out targets when using the GNU assembler 2545and linker. 2546 2547@item weakref 2548@itemx weakref ("@var{target}") 2549@cindex @code{weakref} attribute 2550The @code{weakref} attribute marks a declaration as a weak reference. 2551Without arguments, it should be accompanied by an @code{alias} attribute 2552naming the target symbol. Optionally, the @var{target} may be given as 2553an argument to @code{weakref} itself. In either case, @code{weakref} 2554implicitly marks the declaration as @code{weak}. Without a 2555@var{target}, given as an argument to @code{weakref} or to @code{alias}, 2556@code{weakref} is equivalent to @code{weak}. 2557 2558@smallexample 2559static int x() __attribute__ ((weakref ("y"))); 2560/* is equivalent to... */ 2561static int x() __attribute__ ((weak, weakref, alias ("y"))); 2562/* and to... */ 2563static int x() __attribute__ ((weakref)); 2564static int x() __attribute__ ((alias ("y"))); 2565@end smallexample 2566 2567A weak reference is an alias that does not by itself require a 2568definition to be given for the target symbol. If the target symbol is 2569only referenced through weak references, then the becomes a @code{weak} 2570undefined symbol. If it is directly referenced, however, then such 2571strong references prevail, and a definition will be required for the 2572symbol, not necessarily in the same translation unit. 2573 2574The effect is equivalent to moving all references to the alias to a 2575separate translation unit, renaming the alias to the aliased symbol, 2576declaring it as weak, compiling the two separate translation units and 2577performing a reloadable link on them. 2578 2579At present, a declaration to which @code{weakref} is attached can 2580only be @code{static}. 2581 2582@item externally_visible 2583@cindex @code{externally_visible} attribute. 2584This attribute, attached to a global variable or function nullify 2585effect of @option{-fwhole-program} command line option, so the object 2586remain visible outside the current compilation unit 2587 2588@end table 2589 2590You can specify multiple attributes in a declaration by separating them 2591by commas within the double parentheses or by immediately following an 2592attribute declaration with another attribute declaration. 2593 2594@cindex @code{#pragma}, reason for not using 2595@cindex pragma, reason for not using 2596Some people object to the @code{__attribute__} feature, suggesting that 2597ISO C's @code{#pragma} should be used instead. At the time 2598@code{__attribute__} was designed, there were two reasons for not doing 2599this. 2600 2601@enumerate 2602@item 2603It is impossible to generate @code{#pragma} commands from a macro. 2604 2605@item 2606There is no telling what the same @code{#pragma} might mean in another 2607compiler. 2608@end enumerate 2609 2610These two reasons applied to almost any application that might have been 2611proposed for @code{#pragma}. It was basically a mistake to use 2612@code{#pragma} for @emph{anything}. 2613 2614The ISO C99 standard includes @code{_Pragma}, which now allows pragmas 2615to be generated from macros. In addition, a @code{#pragma GCC} 2616namespace is now in use for GCC-specific pragmas. However, it has been 2617found convenient to use @code{__attribute__} to achieve a natural 2618attachment of attributes to their corresponding declarations, whereas 2619@code{#pragma GCC} is of use for constructs that do not naturally form 2620part of the grammar. @xref{Other Directives,,Miscellaneous 2621Preprocessing Directives, cpp, The GNU C Preprocessor}. 2622 2623@node Attribute Syntax 2624@section Attribute Syntax 2625@cindex attribute syntax 2626 2627This section describes the syntax with which @code{__attribute__} may be 2628used, and the constructs to which attribute specifiers bind, for the C 2629language. Some details may vary for C++. Because of infelicities in 2630the grammar for attributes, some forms described here may not be 2631successfully parsed in all cases. 2632 2633There are some problems with the semantics of attributes in C++. For 2634example, there are no manglings for attributes, although they may affect 2635code generation, so problems may arise when attributed types are used in 2636conjunction with templates or overloading. Similarly, @code{typeid} 2637does not distinguish between types with different attributes. Support 2638for attributes in C++ may be restricted in future to attributes on 2639declarations only, but not on nested declarators. 2640 2641@xref{Function Attributes}, for details of the semantics of attributes 2642applying to functions. @xref{Variable Attributes}, for details of the 2643semantics of attributes applying to variables. @xref{Type Attributes}, 2644for details of the semantics of attributes applying to structure, union 2645and enumerated types. 2646 2647An @dfn{attribute specifier} is of the form 2648@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} 2649is a possibly empty comma-separated sequence of @dfn{attributes}, where 2650each attribute is one of the following: 2651 2652@itemize @bullet 2653@item 2654Empty. Empty attributes are ignored. 2655 2656@item 2657A word (which may be an identifier such as @code{unused}, or a reserved 2658word such as @code{const}). 2659 2660@item 2661A word, followed by, in parentheses, parameters for the attribute. 2662These parameters take one of the following forms: 2663 2664@itemize @bullet 2665@item 2666An identifier. For example, @code{mode} attributes use this form. 2667 2668@item 2669An identifier followed by a comma and a non-empty comma-separated list 2670of expressions. For example, @code{format} attributes use this form. 2671 2672@item 2673A possibly empty comma-separated list of expressions. For example, 2674@code{format_arg} attributes use this form with the list being a single 2675integer constant expression, and @code{alias} attributes use this form 2676with the list being a single string constant. 2677@end itemize 2678@end itemize 2679 2680An @dfn{attribute specifier list} is a sequence of one or more attribute 2681specifiers, not separated by any other tokens. 2682 2683In GNU C, an attribute specifier list may appear after the colon following a 2684label, other than a @code{case} or @code{default} label. The only 2685attribute it makes sense to use after a label is @code{unused}. This 2686feature is intended for code generated by programs which contains labels 2687that may be unused but which is compiled with @option{-Wall}. It would 2688not normally be appropriate to use in it human-written code, though it 2689could be useful in cases where the code that jumps to the label is 2690contained within an @code{#ifdef} conditional. GNU C++ does not permit 2691such placement of attribute lists, as it is permissible for a 2692declaration, which could begin with an attribute list, to be labelled in 2693C++. Declarations cannot be labelled in C90 or C99, so the ambiguity 2694does not arise there. 2695 2696An attribute specifier list may appear as part of a @code{struct}, 2697@code{union} or @code{enum} specifier. It may go either immediately 2698after the @code{struct}, @code{union} or @code{enum} keyword, or after 2699the closing brace. The former syntax is preferred. 2700Where attribute specifiers follow the closing brace, they are considered 2701to relate to the structure, union or enumerated type defined, not to any 2702enclosing declaration the type specifier appears in, and the type 2703defined is not complete until after the attribute specifiers. 2704@c Otherwise, there would be the following problems: a shift/reduce 2705@c conflict between attributes binding the struct/union/enum and 2706@c binding to the list of specifiers/qualifiers; and "aligned" 2707@c attributes could use sizeof for the structure, but the size could be 2708@c changed later by "packed" attributes. 2709 2710Otherwise, an attribute specifier appears as part of a declaration, 2711counting declarations of unnamed parameters and type names, and relates 2712to that declaration (which may be nested in another declaration, for 2713example in the case of a parameter declaration), or to a particular declarator 2714within a declaration. Where an 2715attribute specifier is applied to a parameter declared as a function or 2716an array, it should apply to the function or array rather than the 2717pointer to which the parameter is implicitly converted, but this is not 2718yet correctly implemented. 2719 2720Any list of specifiers and qualifiers at the start of a declaration may 2721contain attribute specifiers, whether or not such a list may in that 2722context contain storage class specifiers. (Some attributes, however, 2723are essentially in the nature of storage class specifiers, and only make 2724sense where storage class specifiers may be used; for example, 2725@code{section}.) There is one necessary limitation to this syntax: the 2726first old-style parameter declaration in a function definition cannot 2727begin with an attribute specifier, because such an attribute applies to 2728the function instead by syntax described below (which, however, is not 2729yet implemented in this case). In some other cases, attribute 2730specifiers are permitted by this grammar but not yet supported by the 2731compiler. All attribute specifiers in this place relate to the 2732declaration as a whole. In the obsolescent usage where a type of 2733@code{int} is implied by the absence of type specifiers, such a list of 2734specifiers and qualifiers may be an attribute specifier list with no 2735other specifiers or qualifiers. 2736 2737At present, the first parameter in a function prototype must have some 2738type specifier which is not an attribute specifier; this resolves an 2739ambiguity in the interpretation of @code{void f(int 2740(__attribute__((foo)) x))}, but is subject to change. At present, if 2741the parentheses of a function declarator contain only attributes then 2742those attributes are ignored, rather than yielding an error or warning 2743or implying a single parameter of type int, but this is subject to 2744change. 2745 2746An attribute specifier list may appear immediately before a declarator 2747(other than the first) in a comma-separated list of declarators in a 2748declaration of more than one identifier using a single list of 2749specifiers and qualifiers. Such attribute specifiers apply 2750only to the identifier before whose declarator they appear. For 2751example, in 2752 2753@smallexample 2754__attribute__((noreturn)) void d0 (void), 2755 __attribute__((format(printf, 1, 2))) d1 (const char *, ...), 2756 d2 (void) 2757@end smallexample 2758 2759@noindent 2760the @code{noreturn} attribute applies to all the functions 2761declared; the @code{format} attribute only applies to @code{d1}. 2762 2763An attribute specifier list may appear immediately before the comma, 2764@code{=} or semicolon terminating the declaration of an identifier other 2765than a function definition. At present, such attribute specifiers apply 2766to the declared object or function, but in future they may attach to the 2767outermost adjacent declarator. In simple cases there is no difference, 2768but, for example, in 2769 2770@smallexample 2771void (****f)(void) __attribute__((noreturn)); 2772@end smallexample 2773 2774@noindent 2775at present the @code{noreturn} attribute applies to @code{f}, which 2776causes a warning since @code{f} is not a function, but in future it may 2777apply to the function @code{****f}. The precise semantics of what 2778attributes in such cases will apply to are not yet specified. Where an 2779assembler name for an object or function is specified (@pxref{Asm 2780Labels}), at present the attribute must follow the @code{asm} 2781specification; in future, attributes before the @code{asm} specification 2782may apply to the adjacent declarator, and those after it to the declared 2783object or function. 2784 2785An attribute specifier list may, in future, be permitted to appear after 2786the declarator in a function definition (before any old-style parameter 2787declarations or the function body). 2788 2789Attribute specifiers may be mixed with type qualifiers appearing inside 2790the @code{[]} of a parameter array declarator, in the C99 construct by 2791which such qualifiers are applied to the pointer to which the array is 2792implicitly converted. Such attribute specifiers apply to the pointer, 2793not to the array, but at present this is not implemented and they are 2794ignored. 2795 2796An attribute specifier list may appear at the start of a nested 2797declarator. At present, there are some limitations in this usage: the 2798attributes correctly apply to the declarator, but for most individual 2799attributes the semantics this implies are not implemented. 2800When attribute specifiers follow the @code{*} of a pointer 2801declarator, they may be mixed with any type qualifiers present. 2802The following describes the formal semantics of this syntax. It will make the 2803most sense if you are familiar with the formal specification of 2804declarators in the ISO C standard. 2805 2806Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T 2807D1}, where @code{T} contains declaration specifiers that specify a type 2808@var{Type} (such as @code{int}) and @code{D1} is a declarator that 2809contains an identifier @var{ident}. The type specified for @var{ident} 2810for derived declarators whose type does not include an attribute 2811specifier is as in the ISO C standard. 2812 2813If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, 2814and the declaration @code{T D} specifies the type 2815``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 2816@code{T D1} specifies the type ``@var{derived-declarator-type-list} 2817@var{attribute-specifier-list} @var{Type}'' for @var{ident}. 2818 2819If @code{D1} has the form @code{* 2820@var{type-qualifier-and-attribute-specifier-list} D}, and the 2821declaration @code{T D} specifies the type 2822``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 2823@code{T D1} specifies the type ``@var{derived-declarator-type-list} 2824@var{type-qualifier-and-attribute-specifier-list} @var{Type}'' for 2825@var{ident}. 2826 2827For example, 2828 2829@smallexample 2830void (__attribute__((noreturn)) ****f) (void); 2831@end smallexample 2832 2833@noindent 2834specifies the type ``pointer to pointer to pointer to pointer to 2835non-returning function returning @code{void}''. As another example, 2836 2837@smallexample 2838char *__attribute__((aligned(8))) *f; 2839@end smallexample 2840 2841@noindent 2842specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. 2843Note again that this does not work with most attributes; for example, 2844the usage of @samp{aligned} and @samp{noreturn} attributes given above 2845is not yet supported. 2846 2847For compatibility with existing code written for compiler versions that 2848did not implement attributes on nested declarators, some laxity is 2849allowed in the placing of attributes. If an attribute that only applies 2850to types is applied to a declaration, it will be treated as applying to 2851the type of that declaration. If an attribute that only applies to 2852declarations is applied to the type of a declaration, it will be treated 2853as applying to that declaration; and, for compatibility with code 2854placing the attributes immediately before the identifier declared, such 2855an attribute applied to a function return type will be treated as 2856applying to the function type, and such an attribute applied to an array 2857element type will be treated as applying to the array type. If an 2858attribute that only applies to function types is applied to a 2859pointer-to-function type, it will be treated as applying to the pointer 2860target type; if such an attribute is applied to a function return type 2861that is not a pointer-to-function type, it will be treated as applying 2862to the function type. 2863 2864@node Function Prototypes 2865@section Prototypes and Old-Style Function Definitions 2866@cindex function prototype declarations 2867@cindex old-style function definitions 2868@cindex promotion of formal parameters 2869 2870GNU C extends ISO C to allow a function prototype to override a later 2871old-style non-prototype definition. Consider the following example: 2872 2873@smallexample 2874/* @r{Use prototypes unless the compiler is old-fashioned.} */ 2875#ifdef __STDC__ 2876#define P(x) x 2877#else 2878#define P(x) () 2879#endif 2880 2881/* @r{Prototype function declaration.} */ 2882int isroot P((uid_t)); 2883 2884/* @r{Old-style function definition.} */ 2885int 2886isroot (x) /* @r{??? lossage here ???} */ 2887 uid_t x; 2888@{ 2889 return x == 0; 2890@} 2891@end smallexample 2892 2893Suppose the type @code{uid_t} happens to be @code{short}. ISO C does 2894not allow this example, because subword arguments in old-style 2895non-prototype definitions are promoted. Therefore in this example the 2896function definition's argument is really an @code{int}, which does not 2897match the prototype argument type of @code{short}. 2898 2899This restriction of ISO C makes it hard to write code that is portable 2900to traditional C compilers, because the programmer does not know 2901whether the @code{uid_t} type is @code{short}, @code{int}, or 2902@code{long}. Therefore, in cases like these GNU C allows a prototype 2903to override a later old-style definition. More precisely, in GNU C, a 2904function prototype argument type overrides the argument type specified 2905by a later old-style definition if the former type is the same as the 2906latter type before promotion. Thus in GNU C the above example is 2907equivalent to the following: 2908 2909@smallexample 2910int isroot (uid_t); 2911 2912int 2913isroot (uid_t x) 2914@{ 2915 return x == 0; 2916@} 2917@end smallexample 2918 2919@noindent 2920GNU C++ does not support old-style function definitions, so this 2921extension is irrelevant. 2922 2923@node C++ Comments 2924@section C++ Style Comments 2925@cindex // 2926@cindex C++ comments 2927@cindex comments, C++ style 2928 2929In GNU C, you may use C++ style comments, which start with @samp{//} and 2930continue until the end of the line. Many other C implementations allow 2931such comments, and they are included in the 1999 C standard. However, 2932C++ style comments are not recognized if you specify an @option{-std} 2933option specifying a version of ISO C before C99, or @option{-ansi} 2934(equivalent to @option{-std=c89}). 2935 2936@node Dollar Signs 2937@section Dollar Signs in Identifier Names 2938@cindex $ 2939@cindex dollar signs in identifier names 2940@cindex identifier names, dollar signs in 2941 2942In GNU C, you may normally use dollar signs in identifier names. 2943This is because many traditional C implementations allow such identifiers. 2944However, dollar signs in identifiers are not supported on a few target 2945machines, typically because the target assembler does not allow them. 2946 2947@node Character Escapes 2948@section The Character @key{ESC} in Constants 2949 2950You can use the sequence @samp{\e} in a string or character constant to 2951stand for the ASCII character @key{ESC}. 2952 2953@node Alignment 2954@section Inquiring on Alignment of Types or Variables 2955@cindex alignment 2956@cindex type alignment 2957@cindex variable alignment 2958 2959The keyword @code{__alignof__} allows you to inquire about how an object 2960is aligned, or the minimum alignment usually required by a type. Its 2961syntax is just like @code{sizeof}. 2962 2963For example, if the target machine requires a @code{double} value to be 2964aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. 2965This is true on many RISC machines. On more traditional machine 2966designs, @code{__alignof__ (double)} is 4 or even 2. 2967 2968Some machines never actually require alignment; they allow reference to any 2969data type even at an odd address. For these machines, @code{__alignof__} 2970reports the @emph{recommended} alignment of a type. 2971 2972If the operand of @code{__alignof__} is an lvalue rather than a type, 2973its value is the required alignment for its type, taking into account 2974any minimum alignment specified with GCC's @code{__attribute__} 2975extension (@pxref{Variable Attributes}). For example, after this 2976declaration: 2977 2978@smallexample 2979struct foo @{ int x; char y; @} foo1; 2980@end smallexample 2981 2982@noindent 2983the value of @code{__alignof__ (foo1.y)} is 1, even though its actual 2984alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. 2985 2986It is an error to ask for the alignment of an incomplete type. 2987 2988@node Variable Attributes 2989@section Specifying Attributes of Variables 2990@cindex attribute of variables 2991@cindex variable attributes 2992 2993The keyword @code{__attribute__} allows you to specify special 2994attributes of variables or structure fields. This keyword is followed 2995by an attribute specification inside double parentheses. Some 2996attributes are currently defined generically for variables. 2997Other attributes are defined for variables on particular target 2998systems. Other attributes are available for functions 2999(@pxref{Function Attributes}) and for types (@pxref{Type Attributes}). 3000Other front ends might define more attributes 3001(@pxref{C++ Extensions,,Extensions to the C++ Language}). 3002 3003You may also specify attributes with @samp{__} preceding and following 3004each keyword. This allows you to use them in header files without 3005being concerned about a possible macro of the same name. For example, 3006you may use @code{__aligned__} instead of @code{aligned}. 3007 3008@xref{Attribute Syntax}, for details of the exact syntax for using 3009attributes. 3010 3011@table @code 3012@cindex @code{aligned} attribute 3013@item aligned (@var{alignment}) 3014This attribute specifies a minimum alignment for the variable or 3015structure field, measured in bytes. For example, the declaration: 3016 3017@smallexample 3018int x __attribute__ ((aligned (16))) = 0; 3019@end smallexample 3020 3021@noindent 3022causes the compiler to allocate the global variable @code{x} on a 302316-byte boundary. On a 68040, this could be used in conjunction with 3024an @code{asm} expression to access the @code{move16} instruction which 3025requires 16-byte aligned operands. 3026 3027You can also specify the alignment of structure fields. For example, to 3028create a double-word aligned @code{int} pair, you could write: 3029 3030@smallexample 3031struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; 3032@end smallexample 3033 3034@noindent 3035This is an alternative to creating a union with a @code{double} member 3036that forces the union to be double-word aligned. 3037 3038As in the preceding examples, you can explicitly specify the alignment 3039(in bytes) that you wish the compiler to use for a given variable or 3040structure field. Alternatively, you can leave out the alignment factor 3041and just ask the compiler to align a variable or field to the maximum 3042useful alignment for the target machine you are compiling for. For 3043example, you could write: 3044 3045@smallexample 3046short array[3] __attribute__ ((aligned)); 3047@end smallexample 3048 3049Whenever you leave out the alignment factor in an @code{aligned} attribute 3050specification, the compiler automatically sets the alignment for the declared 3051variable or field to the largest alignment which is ever used for any data 3052type on the target machine you are compiling for. Doing this can often make 3053copy operations more efficient, because the compiler can use whatever 3054instructions copy the biggest chunks of memory when performing copies to 3055or from the variables or fields that you have aligned this way. 3056 3057The @code{aligned} attribute can only increase the alignment; but you 3058can decrease it by specifying @code{packed} as well. See below. 3059 3060Note that the effectiveness of @code{aligned} attributes may be limited 3061by inherent limitations in your linker. On many systems, the linker is 3062only able to arrange for variables to be aligned up to a certain maximum 3063alignment. (For some linkers, the maximum supported alignment may 3064be very very small.) If your linker is only able to align variables 3065up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} 3066in an @code{__attribute__} will still only provide you with 8 byte 3067alignment. See your linker documentation for further information. 3068 3069The @code{aligned} attribute can also be used for functions 3070(@pxref{Function Attributes}.) 3071 3072@item cleanup (@var{cleanup_function}) 3073@cindex @code{cleanup} attribute 3074The @code{cleanup} attribute runs a function when the variable goes 3075out of scope. This attribute can only be applied to auto function 3076scope variables; it may not be applied to parameters or variables 3077with static storage duration. The function must take one parameter, 3078a pointer to a type compatible with the variable. The return value 3079of the function (if any) is ignored. 3080 3081If @option{-fexceptions} is enabled, then @var{cleanup_function} 3082will be run during the stack unwinding that happens during the 3083processing of the exception. Note that the @code{cleanup} attribute 3084does not allow the exception to be caught, only to perform an action. 3085It is undefined what happens if @var{cleanup_function} does not 3086return normally. 3087 3088@item common 3089@itemx nocommon 3090@cindex @code{common} attribute 3091@cindex @code{nocommon} attribute 3092@opindex fcommon 3093@opindex fno-common 3094The @code{common} attribute requests GCC to place a variable in 3095``common'' storage. The @code{nocommon} attribute requests the 3096opposite---to allocate space for it directly. 3097 3098These attributes override the default chosen by the 3099@option{-fno-common} and @option{-fcommon} flags respectively. 3100 3101@item deprecated 3102@cindex @code{deprecated} attribute 3103The @code{deprecated} attribute results in a warning if the variable 3104is used anywhere in the source file. This is useful when identifying 3105variables that are expected to be removed in a future version of a 3106program. The warning also includes the location of the declaration 3107of the deprecated variable, to enable users to easily find further 3108information about why the variable is deprecated, or what they should 3109do instead. Note that the warning only occurs for uses: 3110 3111@smallexample 3112extern int old_var __attribute__ ((deprecated)); 3113extern int old_var; 3114int new_fn () @{ return old_var; @} 3115@end smallexample 3116 3117results in a warning on line 3 but not line 2. 3118 3119The @code{deprecated} attribute can also be used for functions and 3120types (@pxref{Function Attributes}, @pxref{Type Attributes}.) 3121 3122@item mode (@var{mode}) 3123@cindex @code{mode} attribute 3124This attribute specifies the data type for the declaration---whichever 3125type corresponds to the mode @var{mode}. This in effect lets you 3126request an integer or floating point type according to its width. 3127 3128You may also specify a mode of @samp{byte} or @samp{__byte__} to 3129indicate the mode corresponding to a one-byte integer, @samp{word} or 3130@samp{__word__} for the mode of a one-word integer, and @samp{pointer} 3131or @samp{__pointer__} for the mode used to represent pointers. 3132 3133@item packed 3134@cindex @code{packed} attribute 3135The @code{packed} attribute specifies that a variable or structure field 3136should have the smallest possible alignment---one byte for a variable, 3137and one bit for a field, unless you specify a larger value with the 3138@code{aligned} attribute. 3139 3140Here is a structure in which the field @code{x} is packed, so that it 3141immediately follows @code{a}: 3142 3143@smallexample 3144struct foo 3145@{ 3146 char a; 3147 int x[2] __attribute__ ((packed)); 3148@}; 3149@end smallexample 3150 3151@item section ("@var{section-name}") 3152@cindex @code{section} variable attribute 3153Normally, the compiler places the objects it generates in sections like 3154@code{data} and @code{bss}. Sometimes, however, you need additional sections, 3155or you need certain particular variables to appear in special sections, 3156for example to map to special hardware. The @code{section} 3157attribute specifies that a variable (or function) lives in a particular 3158section. For example, this small program uses several specific section names: 3159 3160@smallexample 3161struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; 3162struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; 3163char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; 3164int init_data __attribute__ ((section ("INITDATA"))) = 0; 3165 3166main() 3167@{ 3168 /* @r{Initialize stack pointer} */ 3169 init_sp (stack + sizeof (stack)); 3170 3171 /* @r{Initialize initialized data} */ 3172 memcpy (&init_data, &data, &edata - &data); 3173 3174 /* @r{Turn on the serial ports} */ 3175 init_duart (&a); 3176 init_duart (&b); 3177@} 3178@end smallexample 3179 3180@noindent 3181Use the @code{section} attribute with an @emph{initialized} definition 3182of a @emph{global} variable, as shown in the example. GCC issues 3183a warning and otherwise ignores the @code{section} attribute in 3184uninitialized variable declarations. 3185 3186You may only use the @code{section} attribute with a fully initialized 3187global definition because of the way linkers work. The linker requires 3188each object be defined once, with the exception that uninitialized 3189variables tentatively go in the @code{common} (or @code{bss}) section 3190and can be multiply ``defined''. You can force a variable to be 3191initialized with the @option{-fno-common} flag or the @code{nocommon} 3192attribute. 3193 3194Some file formats do not support arbitrary sections so the @code{section} 3195attribute is not available on all platforms. 3196If you need to map the entire contents of a module to a particular 3197section, consider using the facilities of the linker instead. 3198 3199@item shared 3200@cindex @code{shared} variable attribute 3201On Microsoft Windows, in addition to putting variable definitions in a named 3202section, the section can also be shared among all running copies of an 3203executable or DLL@. For example, this small program defines shared data 3204by putting it in a named section @code{shared} and marking the section 3205shareable: 3206 3207@smallexample 3208int foo __attribute__((section ("shared"), shared)) = 0; 3209 3210int 3211main() 3212@{ 3213 /* @r{Read and write foo. All running 3214 copies see the same value.} */ 3215 return 0; 3216@} 3217@end smallexample 3218 3219@noindent 3220You may only use the @code{shared} attribute along with @code{section} 3221attribute with a fully initialized global definition because of the way 3222linkers work. See @code{section} attribute for more information. 3223 3224The @code{shared} attribute is only available on Microsoft Windows@. 3225 3226@item tls_model ("@var{tls_model}") 3227@cindex @code{tls_model} attribute 3228The @code{tls_model} attribute sets thread-local storage model 3229(@pxref{Thread-Local}) of a particular @code{__thread} variable, 3230overriding @option{-ftls-model=} command line switch on a per-variable 3231basis. 3232The @var{tls_model} argument should be one of @code{global-dynamic}, 3233@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. 3234 3235Not all targets support this attribute. 3236 3237@item unused 3238This attribute, attached to a variable, means that the variable is meant 3239to be possibly unused. GCC will not produce a warning for this 3240variable. 3241 3242@item used 3243This attribute, attached to a variable, means that the variable must be 3244emitted even if it appears that the variable is not referenced. 3245 3246@item vector_size (@var{bytes}) 3247This attribute specifies the vector size for the variable, measured in 3248bytes. For example, the declaration: 3249 3250@smallexample 3251int foo __attribute__ ((vector_size (16))); 3252@end smallexample 3253 3254@noindent 3255causes the compiler to set the mode for @code{foo}, to be 16 bytes, 3256divided into @code{int} sized units. Assuming a 32-bit int (a vector of 32574 units of 4 bytes), the corresponding mode of @code{foo} will be V4SI@. 3258 3259This attribute is only applicable to integral and float scalars, 3260although arrays, pointers, and function return values are allowed in 3261conjunction with this construct. 3262 3263Aggregates with this attribute are invalid, even if they are of the same 3264size as a corresponding scalar. For example, the declaration: 3265 3266@smallexample 3267struct S @{ int a; @}; 3268struct S __attribute__ ((vector_size (16))) foo; 3269@end smallexample 3270 3271@noindent 3272is invalid even if the size of the structure is the same as the size of 3273the @code{int}. 3274 3275@item selectany 3276The @code{selectany} attribute causes an initialized global variable to 3277have link-once semantics. When multiple definitions of the variable are 3278encountered by the linker, the first is selected and the remainder are 3279discarded. Following usage by the Microsoft compiler, the linker is told 3280@emph{not} to warn about size or content differences of the multiple 3281definitions. 3282 3283Although the primary usage of this attribute is for POD types, the 3284attribute can also be applied to global C++ objects that are initialized 3285by a constructor. In this case, the static initialization and destruction 3286code for the object is emitted in each translation defining the object, 3287but the calls to the constructor and destructor are protected by a 3288link-once guard variable. 3289 3290The @code{selectany} attribute is only available on Microsoft Windows 3291targets. You can use @code{__declspec (selectany)} as a synonym for 3292@code{__attribute__ ((selectany))} for compatibility with other 3293compilers. 3294 3295@item weak 3296The @code{weak} attribute is described in @xref{Function Attributes}. 3297 3298@item dllimport 3299The @code{dllimport} attribute is described in @xref{Function Attributes}. 3300 3301@item dllexport 3302The @code{dllexport} attribute is described in @xref{Function Attributes}. 3303 3304@end table 3305 3306@subsection M32R/D Variable Attributes 3307 3308One attribute is currently defined for the M32R/D@. 3309 3310@table @code 3311@item model (@var{model-name}) 3312@cindex variable addressability on the M32R/D 3313Use this attribute on the M32R/D to set the addressability of an object. 3314The identifier @var{model-name} is one of @code{small}, @code{medium}, 3315or @code{large}, representing each of the code models. 3316 3317Small model objects live in the lower 16MB of memory (so that their 3318addresses can be loaded with the @code{ld24} instruction). 3319 3320Medium and large model objects may live anywhere in the 32-bit address space 3321(the compiler will generate @code{seth/add3} instructions to load their 3322addresses). 3323@end table 3324 3325@anchor{i386 Variable Attributes} 3326@subsection i386 Variable Attributes 3327 3328Two attributes are currently defined for i386 configurations: 3329@code{ms_struct} and @code{gcc_struct} 3330 3331@table @code 3332@item ms_struct 3333@itemx gcc_struct 3334@cindex @code{ms_struct} attribute 3335@cindex @code{gcc_struct} attribute 3336 3337If @code{packed} is used on a structure, or if bit-fields are used 3338it may be that the Microsoft ABI packs them differently 3339than GCC would normally pack them. Particularly when moving packed 3340data between functions compiled with GCC and the native Microsoft compiler 3341(either via function call or as data in a file), it may be necessary to access 3342either format. 3343 3344Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 3345compilers to match the native Microsoft compiler. 3346 3347The Microsoft structure layout algorithm is fairly simple with the exception 3348of the bitfield packing: 3349 3350The padding and alignment of members of structures and whether a bit field 3351can straddle a storage-unit boundary 3352 3353@enumerate 3354@item Structure members are stored sequentially in the order in which they are 3355declared: the first member has the lowest memory address and the last member 3356the highest. 3357 3358@item Every data object has an alignment-requirement. The alignment-requirement 3359for all data except structures, unions, and arrays is either the size of the 3360object or the current packing size (specified with either the aligned attribute 3361or the pack pragma), whichever is less. For structures, unions, and arrays, 3362the alignment-requirement is the largest alignment-requirement of its members. 3363Every object is allocated an offset so that: 3364 3365offset % alignment-requirement == 0 3366 3367@item Adjacent bit fields are packed into the same 1-, 2-, or 4-byte allocation 3368unit if the integral types are the same size and if the next bit field fits 3369into the current allocation unit without crossing the boundary imposed by the 3370common alignment requirements of the bit fields. 3371@end enumerate 3372 3373Handling of zero-length bitfields: 3374 3375MSVC interprets zero-length bitfields in the following ways: 3376 3377@enumerate 3378@item If a zero-length bitfield is inserted between two bitfields that would 3379normally be coalesced, the bitfields will not be coalesced. 3380 3381For example: 3382 3383@smallexample 3384struct 3385 @{ 3386 unsigned long bf_1 : 12; 3387 unsigned long : 0; 3388 unsigned long bf_2 : 12; 3389 @} t1; 3390@end smallexample 3391 3392The size of @code{t1} would be 8 bytes with the zero-length bitfield. If the 3393zero-length bitfield were removed, @code{t1}'s size would be 4 bytes. 3394 3395@item If a zero-length bitfield is inserted after a bitfield, @code{foo}, and the 3396alignment of the zero-length bitfield is greater than the member that follows it, 3397@code{bar}, @code{bar} will be aligned as the type of the zero-length bitfield. 3398 3399For example: 3400 3401@smallexample 3402struct 3403 @{ 3404 char foo : 4; 3405 short : 0; 3406 char bar; 3407 @} t2; 3408 3409struct 3410 @{ 3411 char foo : 4; 3412 short : 0; 3413 double bar; 3414 @} t3; 3415@end smallexample 3416 3417For @code{t2}, @code{bar} will be placed at offset 2, rather than offset 1. 3418Accordingly, the size of @code{t2} will be 4. For @code{t3}, the zero-length 3419bitfield will not affect the alignment of @code{bar} or, as a result, the size 3420of the structure. 3421 3422Taking this into account, it is important to note the following: 3423 3424@enumerate 3425@item If a zero-length bitfield follows a normal bitfield, the type of the 3426zero-length bitfield may affect the alignment of the structure as whole. For 3427example, @code{t2} has a size of 4 bytes, since the zero-length bitfield follows a 3428normal bitfield, and is of type short. 3429 3430@item Even if a zero-length bitfield is not followed by a normal bitfield, it may 3431still affect the alignment of the structure: 3432 3433@smallexample 3434struct 3435 @{ 3436 char foo : 6; 3437 long : 0; 3438 @} t4; 3439@end smallexample 3440 3441Here, @code{t4} will take up 4 bytes. 3442@end enumerate 3443 3444@item Zero-length bitfields following non-bitfield members are ignored: 3445 3446@smallexample 3447struct 3448 @{ 3449 char foo; 3450 long : 0; 3451 char bar; 3452 @} t5; 3453@end smallexample 3454 3455Here, @code{t5} will take up 2 bytes. 3456@end enumerate 3457@end table 3458 3459@subsection PowerPC Variable Attributes 3460 3461Three attributes currently are defined for PowerPC configurations: 3462@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 3463 3464For full documentation of the struct attributes please see the 3465documentation in the @xref{i386 Variable Attributes}, section. 3466 3467For documentation of @code{altivec} attribute please see the 3468documentation in the @xref{PowerPC Type Attributes}, section. 3469 3470@subsection Xstormy16 Variable Attributes 3471 3472One attribute is currently defined for xstormy16 configurations: 3473@code{below100} 3474 3475@table @code 3476@item below100 3477@cindex @code{below100} attribute 3478 3479If a variable has the @code{below100} attribute (@code{BELOW100} is 3480allowed also), GCC will place the variable in the first 0x100 bytes of 3481memory and use special opcodes to access it. Such variables will be 3482placed in either the @code{.bss_below100} section or the 3483@code{.data_below100} section. 3484 3485@end table 3486 3487@node Type Attributes 3488@section Specifying Attributes of Types 3489@cindex attribute of types 3490@cindex type attributes 3491 3492The keyword @code{__attribute__} allows you to specify special 3493attributes of @code{struct} and @code{union} types when you define 3494such types. This keyword is followed by an attribute specification 3495inside double parentheses. Seven attributes are currently defined for 3496types: @code{aligned}, @code{packed}, @code{transparent_union}, 3497@code{unused}, @code{deprecated}, @code{visibility}, and 3498@code{may_alias}. Other attributes are defined for functions 3499(@pxref{Function Attributes}) and for variables (@pxref{Variable 3500Attributes}). 3501 3502You may also specify any one of these attributes with @samp{__} 3503preceding and following its keyword. This allows you to use these 3504attributes in header files without being concerned about a possible 3505macro of the same name. For example, you may use @code{__aligned__} 3506instead of @code{aligned}. 3507 3508You may specify type attributes either in a @code{typedef} declaration 3509or in an enum, struct or union type declaration or definition. 3510 3511For an enum, struct or union type, you may specify attributes either 3512between the enum, struct or union tag and the name of the type, or 3513just past the closing curly brace of the @emph{definition}. The 3514former syntax is preferred. 3515 3516@xref{Attribute Syntax}, for details of the exact syntax for using 3517attributes. 3518 3519@table @code 3520@cindex @code{aligned} attribute 3521@item aligned (@var{alignment}) 3522This attribute specifies a minimum alignment (in bytes) for variables 3523of the specified type. For example, the declarations: 3524 3525@smallexample 3526struct S @{ short f[3]; @} __attribute__ ((aligned (8))); 3527typedef int more_aligned_int __attribute__ ((aligned (8))); 3528@end smallexample 3529 3530@noindent 3531force the compiler to insure (as far as it can) that each variable whose 3532type is @code{struct S} or @code{more_aligned_int} will be allocated and 3533aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all 3534variables of type @code{struct S} aligned to 8-byte boundaries allows 3535the compiler to use the @code{ldd} and @code{std} (doubleword load and 3536store) instructions when copying one variable of type @code{struct S} to 3537another, thus improving run-time efficiency. 3538 3539Note that the alignment of any given @code{struct} or @code{union} type 3540is required by the ISO C standard to be at least a perfect multiple of 3541the lowest common multiple of the alignments of all of the members of 3542the @code{struct} or @code{union} in question. This means that you @emph{can} 3543effectively adjust the alignment of a @code{struct} or @code{union} 3544type by attaching an @code{aligned} attribute to any one of the members 3545of such a type, but the notation illustrated in the example above is a 3546more obvious, intuitive, and readable way to request the compiler to 3547adjust the alignment of an entire @code{struct} or @code{union} type. 3548 3549As in the preceding example, you can explicitly specify the alignment 3550(in bytes) that you wish the compiler to use for a given @code{struct} 3551or @code{union} type. Alternatively, you can leave out the alignment factor 3552and just ask the compiler to align a type to the maximum 3553useful alignment for the target machine you are compiling for. For 3554example, you could write: 3555 3556@smallexample 3557struct S @{ short f[3]; @} __attribute__ ((aligned)); 3558@end smallexample 3559 3560Whenever you leave out the alignment factor in an @code{aligned} 3561attribute specification, the compiler automatically sets the alignment 3562for the type to the largest alignment which is ever used for any data 3563type on the target machine you are compiling for. Doing this can often 3564make copy operations more efficient, because the compiler can use 3565whatever instructions copy the biggest chunks of memory when performing 3566copies to or from the variables which have types that you have aligned 3567this way. 3568 3569In the example above, if the size of each @code{short} is 2 bytes, then 3570the size of the entire @code{struct S} type is 6 bytes. The smallest 3571power of two which is greater than or equal to that is 8, so the 3572compiler sets the alignment for the entire @code{struct S} type to 8 3573bytes. 3574 3575Note that although you can ask the compiler to select a time-efficient 3576alignment for a given type and then declare only individual stand-alone 3577objects of that type, the compiler's ability to select a time-efficient 3578alignment is primarily useful only when you plan to create arrays of 3579variables having the relevant (efficiently aligned) type. If you 3580declare or use arrays of variables of an efficiently-aligned type, then 3581it is likely that your program will also be doing pointer arithmetic (or 3582subscripting, which amounts to the same thing) on pointers to the 3583relevant type, and the code that the compiler generates for these 3584pointer arithmetic operations will often be more efficient for 3585efficiently-aligned types than for other types. 3586 3587The @code{aligned} attribute can only increase the alignment; but you 3588can decrease it by specifying @code{packed} as well. See below. 3589 3590Note that the effectiveness of @code{aligned} attributes may be limited 3591by inherent limitations in your linker. On many systems, the linker is 3592only able to arrange for variables to be aligned up to a certain maximum 3593alignment. (For some linkers, the maximum supported alignment may 3594be very very small.) If your linker is only able to align variables 3595up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} 3596in an @code{__attribute__} will still only provide you with 8 byte 3597alignment. See your linker documentation for further information. 3598 3599@item packed 3600This attribute, attached to @code{struct} or @code{union} type 3601definition, specifies that each member (other than zero-width bitfields) 3602of the structure or union is placed to minimize the memory required. When 3603attached to an @code{enum} definition, it indicates that the smallest 3604integral type should be used. 3605 3606@opindex fshort-enums 3607Specifying this attribute for @code{struct} and @code{union} types is 3608equivalent to specifying the @code{packed} attribute on each of the 3609structure or union members. Specifying the @option{-fshort-enums} 3610flag on the line is equivalent to specifying the @code{packed} 3611attribute on all @code{enum} definitions. 3612 3613In the following example @code{struct my_packed_struct}'s members are 3614packed closely together, but the internal layout of its @code{s} member 3615is not packed---to do that, @code{struct my_unpacked_struct} would need to 3616be packed too. 3617 3618@smallexample 3619struct my_unpacked_struct 3620 @{ 3621 char c; 3622 int i; 3623 @}; 3624 3625struct __attribute__ ((__packed__)) my_packed_struct 3626 @{ 3627 char c; 3628 int i; 3629 struct my_unpacked_struct s; 3630 @}; 3631@end smallexample 3632 3633You may only specify this attribute on the definition of a @code{enum}, 3634@code{struct} or @code{union}, not on a @code{typedef} which does not 3635also define the enumerated type, structure or union. 3636 3637@item transparent_union 3638This attribute, attached to a @code{union} type definition, indicates 3639that any function parameter having that union type causes calls to that 3640function to be treated in a special way. 3641 3642First, the argument corresponding to a transparent union type can be of 3643any type in the union; no cast is required. Also, if the union contains 3644a pointer type, the corresponding argument can be a null pointer 3645constant or a void pointer expression; and if the union contains a void 3646pointer type, the corresponding argument can be any pointer expression. 3647If the union member type is a pointer, qualifiers like @code{const} on 3648the referenced type must be respected, just as with normal pointer 3649conversions. 3650 3651Second, the argument is passed to the function using the calling 3652conventions of the first member of the transparent union, not the calling 3653conventions of the union itself. All members of the union must have the 3654same machine representation; this is necessary for this argument passing 3655to work properly. 3656 3657Transparent unions are designed for library functions that have multiple 3658interfaces for compatibility reasons. For example, suppose the 3659@code{wait} function must accept either a value of type @code{int *} to 3660comply with Posix, or a value of type @code{union wait *} to comply with 3661the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, 3662@code{wait} would accept both kinds of arguments, but it would also 3663accept any other pointer type and this would make argument type checking 3664less useful. Instead, @code{<sys/wait.h>} might define the interface 3665as follows: 3666 3667@smallexample 3668typedef union 3669 @{ 3670 int *__ip; 3671 union wait *__up; 3672 @} wait_status_ptr_t __attribute__ ((__transparent_union__)); 3673 3674pid_t wait (wait_status_ptr_t); 3675@end smallexample 3676 3677This interface allows either @code{int *} or @code{union wait *} 3678arguments to be passed, using the @code{int *} calling convention. 3679The program can call @code{wait} with arguments of either type: 3680 3681@smallexample 3682int w1 () @{ int w; return wait (&w); @} 3683int w2 () @{ union wait w; return wait (&w); @} 3684@end smallexample 3685 3686With this interface, @code{wait}'s implementation might look like this: 3687 3688@smallexample 3689pid_t wait (wait_status_ptr_t p) 3690@{ 3691 return waitpid (-1, p.__ip, 0); 3692@} 3693@end smallexample 3694 3695@item unused 3696When attached to a type (including a @code{union} or a @code{struct}), 3697this attribute means that variables of that type are meant to appear 3698possibly unused. GCC will not produce a warning for any variables of 3699that type, even if the variable appears to do nothing. This is often 3700the case with lock or thread classes, which are usually defined and then 3701not referenced, but contain constructors and destructors that have 3702nontrivial bookkeeping functions. 3703 3704@item deprecated 3705The @code{deprecated} attribute results in a warning if the type 3706is used anywhere in the source file. This is useful when identifying 3707types that are expected to be removed in a future version of a program. 3708If possible, the warning also includes the location of the declaration 3709of the deprecated type, to enable users to easily find further 3710information about why the type is deprecated, or what they should do 3711instead. Note that the warnings only occur for uses and then only 3712if the type is being applied to an identifier that itself is not being 3713declared as deprecated. 3714 3715@smallexample 3716typedef int T1 __attribute__ ((deprecated)); 3717T1 x; 3718typedef T1 T2; 3719T2 y; 3720typedef T1 T3 __attribute__ ((deprecated)); 3721T3 z __attribute__ ((deprecated)); 3722@end smallexample 3723 3724results in a warning on line 2 and 3 but not lines 4, 5, or 6. No 3725warning is issued for line 4 because T2 is not explicitly 3726deprecated. Line 5 has no warning because T3 is explicitly 3727deprecated. Similarly for line 6. 3728 3729The @code{deprecated} attribute can also be used for functions and 3730variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) 3731 3732@item may_alias 3733Accesses to objects with types with this attribute are not subjected to 3734type-based alias analysis, but are instead assumed to be able to alias 3735any other type of objects, just like the @code{char} type. See 3736@option{-fstrict-aliasing} for more information on aliasing issues. 3737 3738Example of use: 3739 3740@smallexample 3741typedef short __attribute__((__may_alias__)) short_a; 3742 3743int 3744main (void) 3745@{ 3746 int a = 0x12345678; 3747 short_a *b = (short_a *) &a; 3748 3749 b[1] = 0; 3750 3751 if (a == 0x12345678) 3752 abort(); 3753 3754 exit(0); 3755@} 3756@end smallexample 3757 3758If you replaced @code{short_a} with @code{short} in the variable 3759declaration, the above program would abort when compiled with 3760@option{-fstrict-aliasing}, which is on by default at @option{-O2} or 3761above in recent GCC versions. 3762 3763@item visibility 3764In C++, attribute visibility (@pxref{Function Attributes}) can also be 3765applied to class, struct, union and enum types. Unlike other type 3766attributes, the attribute must appear between the initial keyword and 3767the name of the type; it cannot appear after the body of the type. 3768 3769Note that the type visibility is applied to vague linkage entities 3770associated with the class (vtable, typeinfo node, etc.). In 3771particular, if a class is thrown as an exception in one shared object 3772and caught in another, the class must have default visibility. 3773Otherwise the two shared objects will be unable to use the same 3774typeinfo node and exception handling will break. 3775 3776@subsection ARM Type Attributes 3777 3778On those ARM targets that support @code{dllimport} (such as Symbian 3779OS), you can use the @code{notshared} attribute to indicate that the 3780virtual table and other similar data for a class should not be 3781exported from a DLL@. For example: 3782 3783@smallexample 3784class __declspec(notshared) C @{ 3785public: 3786 __declspec(dllimport) C(); 3787 virtual void f(); 3788@} 3789 3790__declspec(dllexport) 3791C::C() @{@} 3792@end smallexample 3793 3794In this code, @code{C::C} is exported from the current DLL, but the 3795virtual table for @code{C} is not exported. (You can use 3796@code{__attribute__} instead of @code{__declspec} if you prefer, but 3797most Symbian OS code uses @code{__declspec}.) 3798 3799@anchor{i386 Type Attributes} 3800@subsection i386 Type Attributes 3801 3802Two attributes are currently defined for i386 configurations: 3803@code{ms_struct} and @code{gcc_struct} 3804 3805@item ms_struct 3806@itemx gcc_struct 3807@cindex @code{ms_struct} 3808@cindex @code{gcc_struct} 3809 3810If @code{packed} is used on a structure, or if bit-fields are used 3811it may be that the Microsoft ABI packs them differently 3812than GCC would normally pack them. Particularly when moving packed 3813data between functions compiled with GCC and the native Microsoft compiler 3814(either via function call or as data in a file), it may be necessary to access 3815either format. 3816 3817Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 3818compilers to match the native Microsoft compiler. 3819@end table 3820 3821To specify multiple attributes, separate them by commas within the 3822double parentheses: for example, @samp{__attribute__ ((aligned (16), 3823packed))}. 3824 3825@anchor{PowerPC Type Attributes} 3826@subsection PowerPC Type Attributes 3827 3828Three attributes currently are defined for PowerPC configurations: 3829@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 3830 3831For full documentation of the struct attributes please see the 3832documentation in the @xref{i386 Type Attributes}, section. 3833 3834The @code{altivec} attribute allows one to declare AltiVec vector data 3835types supported by the AltiVec Programming Interface Manual. The 3836attribute requires an argument to specify one of three vector types: 3837@code{vector__}, @code{pixel__} (always followed by unsigned short), 3838and @code{bool__} (always followed by unsigned). 3839 3840@smallexample 3841__attribute__((altivec(vector__))) 3842__attribute__((altivec(pixel__))) unsigned short 3843__attribute__((altivec(bool__))) unsigned 3844@end smallexample 3845 3846These attributes mainly are intended to support the @code{__vector}, 3847@code{__pixel}, and @code{__bool} AltiVec keywords. 3848 3849@node Inline 3850@section An Inline Function is As Fast As a Macro 3851@cindex inline functions 3852@cindex integrating function code 3853@cindex open coding 3854@cindex macros, inline alternative 3855 3856By declaring a function inline, you can direct GCC to make 3857calls to that function faster. One way GCC can achieve this is to 3858integrate that function's code into the code for its callers. This 3859makes execution faster by eliminating the function-call overhead; in 3860addition, if any of the actual argument values are constant, their 3861known values may permit simplifications at compile time so that not 3862all of the inline function's code needs to be included. The effect on 3863code size is less predictable; object code may be larger or smaller 3864with function inlining, depending on the particular case. You can 3865also direct GCC to try to integrate all ``simple enough'' functions 3866into their callers with the option @option{-finline-functions}. 3867 3868GCC implements three different semantics of declaring a function 3869inline. One is available with @option{-std=gnu89}, another when 3870@option{-std=c99} or @option{-std=gnu99}, and the third is used when 3871compiling C++. 3872 3873To declare a function inline, use the @code{inline} keyword in its 3874declaration, like this: 3875 3876@smallexample 3877static inline int 3878inc (int *a) 3879@{ 3880 (*a)++; 3881@} 3882@end smallexample 3883 3884If you are writing a header file to be included in ISO C89 programs, write 3885@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. 3886 3887The three types of inlining behave similarly in two important cases: 3888when the @code{inline} keyword is used on a @code{static} function, 3889like the example above, and when a function is first declared without 3890using the @code{inline} keyword and then is defined with 3891@code{inline}, like this: 3892 3893@smallexample 3894extern int inc (int *a); 3895inline int 3896inc (int *a) 3897@{ 3898 (*a)++; 3899@} 3900@end smallexample 3901 3902In both of these common cases, the program behaves the same as if you 3903had not used the @code{inline} keyword, except for its speed. 3904 3905@cindex inline functions, omission of 3906@opindex fkeep-inline-functions 3907When a function is both inline and @code{static}, if all calls to the 3908function are integrated into the caller, and the function's address is 3909never used, then the function's own assembler code is never referenced. 3910In this case, GCC does not actually output assembler code for the 3911function, unless you specify the option @option{-fkeep-inline-functions}. 3912Some calls cannot be integrated for various reasons (in particular, 3913calls that precede the function's definition cannot be integrated, and 3914neither can recursive calls within the definition). If there is a 3915nonintegrated call, then the function is compiled to assembler code as 3916usual. The function must also be compiled as usual if the program 3917refers to its address, because that can't be inlined. 3918 3919@cindex automatic @code{inline} for C++ member fns 3920@cindex @code{inline} automatic for C++ member fns 3921@cindex member fns, automatically @code{inline} 3922@cindex C++ member fns, automatically @code{inline} 3923@opindex fno-default-inline 3924As required by ISO C++, GCC considers member functions defined within 3925the body of a class to be marked inline even if they are 3926not explicitly declared with the @code{inline} keyword. You can 3927override this with @option{-fno-default-inline}; @pxref{C++ Dialect 3928Options,,Options Controlling C++ Dialect}. 3929 3930GCC does not inline any functions when not optimizing unless you specify 3931the @samp{always_inline} attribute for the function, like this: 3932 3933@smallexample 3934/* @r{Prototype.} */ 3935inline void foo (const char) __attribute__((always_inline)); 3936@end smallexample 3937 3938The remainder of this section is specific to GNU C89 inlining. 3939 3940@cindex non-static inline function 3941When an inline function is not @code{static}, then the compiler must assume 3942that there may be calls from other source files; since a global symbol can 3943be defined only once in any program, the function must not be defined in 3944the other source files, so the calls therein cannot be integrated. 3945Therefore, a non-@code{static} inline function is always compiled on its 3946own in the usual fashion. 3947 3948If you specify both @code{inline} and @code{extern} in the function 3949definition, then the definition is used only for inlining. In no case 3950is the function compiled on its own, not even if you refer to its 3951address explicitly. Such an address becomes an external reference, as 3952if you had only declared the function, and had not defined it. 3953 3954This combination of @code{inline} and @code{extern} has almost the 3955effect of a macro. The way to use it is to put a function definition in 3956a header file with these keywords, and put another copy of the 3957definition (lacking @code{inline} and @code{extern}) in a library file. 3958The definition in the header file will cause most calls to the function 3959to be inlined. If any uses of the function remain, they will refer to 3960the single copy in the library. 3961 3962@node Extended Asm 3963@section Assembler Instructions with C Expression Operands 3964@cindex extended @code{asm} 3965@cindex @code{asm} expressions 3966@cindex assembler instructions 3967@cindex registers 3968 3969In an assembler instruction using @code{asm}, you can specify the 3970operands of the instruction using C expressions. This means you need not 3971guess which registers or memory locations will contain the data you want 3972to use. 3973 3974You must specify an assembler instruction template much like what 3975appears in a machine description, plus an operand constraint string for 3976each operand. 3977 3978For example, here is how to use the 68881's @code{fsinx} instruction: 3979 3980@smallexample 3981asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); 3982@end smallexample 3983 3984@noindent 3985Here @code{angle} is the C expression for the input operand while 3986@code{result} is that of the output operand. Each has @samp{"f"} as its 3987operand constraint, saying that a floating point register is required. 3988The @samp{=} in @samp{=f} indicates that the operand is an output; all 3989output operands' constraints must use @samp{=}. The constraints use the 3990same language used in the machine description (@pxref{Constraints}). 3991 3992Each operand is described by an operand-constraint string followed by 3993the C expression in parentheses. A colon separates the assembler 3994template from the first output operand and another separates the last 3995output operand from the first input, if any. Commas separate the 3996operands within each group. The total number of operands is currently 3997limited to 30; this limitation may be lifted in some future version of 3998GCC@. 3999 4000If there are no output operands but there are input operands, you must 4001place two consecutive colons surrounding the place where the output 4002operands would go. 4003 4004As of GCC version 3.1, it is also possible to specify input and output 4005operands using symbolic names which can be referenced within the 4006assembler code. These names are specified inside square brackets 4007preceding the constraint string, and can be referenced inside the 4008assembler code using @code{%[@var{name}]} instead of a percentage sign 4009followed by the operand number. Using named operands the above example 4010could look like: 4011 4012@smallexample 4013asm ("fsinx %[angle],%[output]" 4014 : [output] "=f" (result) 4015 : [angle] "f" (angle)); 4016@end smallexample 4017 4018@noindent 4019Note that the symbolic operand names have no relation whatsoever to 4020other C identifiers. You may use any name you like, even those of 4021existing C symbols, but you must ensure that no two operands within the same 4022assembler construct use the same symbolic name. 4023 4024Output operand expressions must be lvalues; the compiler can check this. 4025The input operands need not be lvalues. The compiler cannot check 4026whether the operands have data types that are reasonable for the 4027instruction being executed. It does not parse the assembler instruction 4028template and does not know what it means or even whether it is valid 4029assembler input. The extended @code{asm} feature is most often used for 4030machine instructions the compiler itself does not know exist. If 4031the output expression cannot be directly addressed (for example, it is a 4032bit-field), your constraint must allow a register. In that case, GCC 4033will use the register as the output of the @code{asm}, and then store 4034that register into the output. 4035 4036The ordinary output operands must be write-only; GCC will assume that 4037the values in these operands before the instruction are dead and need 4038not be generated. Extended asm supports input-output or read-write 4039operands. Use the constraint character @samp{+} to indicate such an 4040operand and list it with the output operands. You should only use 4041read-write operands when the constraints for the operand (or the 4042operand in which only some of the bits are to be changed) allow a 4043register. 4044 4045You may, as an alternative, logically split its function into two 4046separate operands, one input operand and one write-only output 4047operand. The connection between them is expressed by constraints 4048which say they need to be in the same location when the instruction 4049executes. You can use the same C expression for both operands, or 4050different expressions. For example, here we write the (fictitious) 4051@samp{combine} instruction with @code{bar} as its read-only source 4052operand and @code{foo} as its read-write destination: 4053 4054@smallexample 4055asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); 4056@end smallexample 4057 4058@noindent 4059The constraint @samp{"0"} for operand 1 says that it must occupy the 4060same location as operand 0. A number in constraint is allowed only in 4061an input operand and it must refer to an output operand. 4062 4063Only a number in the constraint can guarantee that one operand will be in 4064the same place as another. The mere fact that @code{foo} is the value 4065of both operands is not enough to guarantee that they will be in the 4066same place in the generated assembler code. The following would not 4067work reliably: 4068 4069@smallexample 4070asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); 4071@end smallexample 4072 4073Various optimizations or reloading could cause operands 0 and 1 to be in 4074different registers; GCC knows no reason not to do so. For example, the 4075compiler might find a copy of the value of @code{foo} in one register and 4076use it for operand 1, but generate the output operand 0 in a different 4077register (copying it afterward to @code{foo}'s own address). Of course, 4078since the register for operand 1 is not even mentioned in the assembler 4079code, the result will not work, but GCC can't tell that. 4080 4081As of GCC version 3.1, one may write @code{[@var{name}]} instead of 4082the operand number for a matching constraint. For example: 4083 4084@smallexample 4085asm ("cmoveq %1,%2,%[result]" 4086 : [result] "=r"(result) 4087 : "r" (test), "r"(new), "[result]"(old)); 4088@end smallexample 4089 4090Sometimes you need to make an @code{asm} operand be a specific register, 4091but there's no matching constraint letter for that register @emph{by 4092itself}. To force the operand into that register, use a local variable 4093for the operand and specify the register in the variable declaration. 4094@xref{Explicit Reg Vars}. Then for the @code{asm} operand, use any 4095register constraint letter that matches the register: 4096 4097@smallexample 4098register int *p1 asm ("r0") = @dots{}; 4099register int *p2 asm ("r1") = @dots{}; 4100register int *result asm ("r0"); 4101asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 4102@end smallexample 4103 4104@anchor{Example of asm with clobbered asm reg} 4105In the above example, beware that a register that is call-clobbered by 4106the target ABI will be overwritten by any function call in the 4107assignment, including library calls for arithmetic operators. 4108Assuming it is a call-clobbered register, this may happen to @code{r0} 4109above by the assignment to @code{p2}. If you have to use such a 4110register, use temporary variables for expressions between the register 4111assignment and use: 4112 4113@smallexample 4114int t1 = @dots{}; 4115register int *p1 asm ("r0") = @dots{}; 4116register int *p2 asm ("r1") = t1; 4117register int *result asm ("r0"); 4118asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 4119@end smallexample 4120 4121Some instructions clobber specific hard registers. To describe this, 4122write a third colon after the input operands, followed by the names of 4123the clobbered hard registers (given as strings). Here is a realistic 4124example for the VAX: 4125 4126@smallexample 4127asm volatile ("movc3 %0,%1,%2" 4128 : /* @r{no outputs} */ 4129 : "g" (from), "g" (to), "g" (count) 4130 : "r0", "r1", "r2", "r3", "r4", "r5"); 4131@end smallexample 4132 4133You may not write a clobber description in a way that overlaps with an 4134input or output operand. For example, you may not have an operand 4135describing a register class with one member if you mention that register 4136in the clobber list. Variables declared to live in specific registers 4137(@pxref{Explicit Reg Vars}), and used as asm input or output operands must 4138have no part mentioned in the clobber description. 4139There is no way for you to specify that an input 4140operand is modified without also specifying it as an output 4141operand. Note that if all the output operands you specify are for this 4142purpose (and hence unused), you will then also need to specify 4143@code{volatile} for the @code{asm} construct, as described below, to 4144prevent GCC from deleting the @code{asm} statement as unused. 4145 4146If you refer to a particular hardware register from the assembler code, 4147you will probably have to list the register after the third colon to 4148tell the compiler the register's value is modified. In some assemblers, 4149the register names begin with @samp{%}; to produce one @samp{%} in the 4150assembler code, you must write @samp{%%} in the input. 4151 4152If your assembler instruction can alter the condition code register, add 4153@samp{cc} to the list of clobbered registers. GCC on some machines 4154represents the condition codes as a specific hardware register; 4155@samp{cc} serves to name this register. On other machines, the 4156condition code is handled differently, and specifying @samp{cc} has no 4157effect. But it is valid no matter what the machine. 4158 4159If your assembler instructions access memory in an unpredictable 4160fashion, add @samp{memory} to the list of clobbered registers. This 4161will cause GCC to not keep memory values cached in registers across the 4162assembler instruction and not optimize stores or loads to that memory. 4163You will also want to add the @code{volatile} keyword if the memory 4164affected is not listed in the inputs or outputs of the @code{asm}, as 4165the @samp{memory} clobber does not count as a side-effect of the 4166@code{asm}. If you know how large the accessed memory is, you can add 4167it as input or output but if this is not known, you should add 4168@samp{memory}. As an example, if you access ten bytes of a string, you 4169can use a memory input like: 4170 4171@smallexample 4172@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}. 4173@end smallexample 4174 4175Note that in the following example the memory input is necessary, 4176otherwise GCC might optimize the store to @code{x} away: 4177@smallexample 4178int foo () 4179@{ 4180 int x = 42; 4181 int *y = &x; 4182 int result; 4183 asm ("magic stuff accessing an 'int' pointed to by '%1'" 4184 "=&d" (r) : "a" (y), "m" (*y)); 4185 return result; 4186@} 4187@end smallexample 4188 4189You can put multiple assembler instructions together in a single 4190@code{asm} template, separated by the characters normally used in assembly 4191code for the system. A combination that works in most places is a newline 4192to break the line, plus a tab character to move to the instruction field 4193(written as @samp{\n\t}). Sometimes semicolons can be used, if the 4194assembler allows semicolons as a line-breaking character. Note that some 4195assembler dialects use semicolons to start a comment. 4196The input operands are guaranteed not to use any of the clobbered 4197registers, and neither will the output operands' addresses, so you can 4198read and write the clobbered registers as many times as you like. Here 4199is an example of multiple instructions in a template; it assumes the 4200subroutine @code{_foo} accepts arguments in registers 9 and 10: 4201 4202@smallexample 4203asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo" 4204 : /* no outputs */ 4205 : "g" (from), "g" (to) 4206 : "r9", "r10"); 4207@end smallexample 4208 4209Unless an output operand has the @samp{&} constraint modifier, GCC 4210may allocate it in the same register as an unrelated input operand, on 4211the assumption the inputs are consumed before the outputs are produced. 4212This assumption may be false if the assembler code actually consists of 4213more than one instruction. In such a case, use @samp{&} for each output 4214operand that may not overlap an input. @xref{Modifiers}. 4215 4216If you want to test the condition code produced by an assembler 4217instruction, you must include a branch and a label in the @code{asm} 4218construct, as follows: 4219 4220@smallexample 4221asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:" 4222 : "g" (result) 4223 : "g" (input)); 4224@end smallexample 4225 4226@noindent 4227This assumes your assembler supports local labels, as the GNU assembler 4228and most Unix assemblers do. 4229 4230Speaking of labels, jumps from one @code{asm} to another are not 4231supported. The compiler's optimizers do not know about these jumps, and 4232therefore they cannot take account of them when deciding how to 4233optimize. 4234 4235@cindex macros containing @code{asm} 4236Usually the most convenient way to use these @code{asm} instructions is to 4237encapsulate them in macros that look like functions. For example, 4238 4239@smallexample 4240#define sin(x) \ 4241(@{ double __value, __arg = (x); \ 4242 asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ 4243 __value; @}) 4244@end smallexample 4245 4246@noindent 4247Here the variable @code{__arg} is used to make sure that the instruction 4248operates on a proper @code{double} value, and to accept only those 4249arguments @code{x} which can convert automatically to a @code{double}. 4250 4251Another way to make sure the instruction operates on the correct data 4252type is to use a cast in the @code{asm}. This is different from using a 4253variable @code{__arg} in that it converts more different types. For 4254example, if the desired type were @code{int}, casting the argument to 4255@code{int} would accept a pointer with no complaint, while assigning the 4256argument to an @code{int} variable named @code{__arg} would warn about 4257using a pointer unless the caller explicitly casts it. 4258 4259If an @code{asm} has output operands, GCC assumes for optimization 4260purposes the instruction has no side effects except to change the output 4261operands. This does not mean instructions with a side effect cannot be 4262used, but you must be careful, because the compiler may eliminate them 4263if the output operands aren't used, or move them out of loops, or 4264replace two with one if they constitute a common subexpression. Also, 4265if your instruction does have a side effect on a variable that otherwise 4266appears not to change, the old value of the variable may be reused later 4267if it happens to be found in a register. 4268 4269You can prevent an @code{asm} instruction from being deleted 4270by writing the keyword @code{volatile} after 4271the @code{asm}. For example: 4272 4273@smallexample 4274#define get_and_set_priority(new) \ 4275(@{ int __old; \ 4276 asm volatile ("get_and_set_priority %0, %1" \ 4277 : "=g" (__old) : "g" (new)); \ 4278 __old; @}) 4279@end smallexample 4280 4281@noindent 4282The @code{volatile} keyword indicates that the instruction has 4283important side-effects. GCC will not delete a volatile @code{asm} if 4284it is reachable. (The instruction can still be deleted if GCC can 4285prove that control-flow will never reach the location of the 4286instruction.) Note that even a volatile @code{asm} instruction 4287can be moved relative to other code, including across jump 4288instructions. For example, on many targets there is a system 4289register which can be set to control the rounding mode of 4290floating point operations. You might try 4291setting it with a volatile @code{asm}, like this PowerPC example: 4292 4293@smallexample 4294 asm volatile("mtfsf 255,%0" : : "f" (fpenv)); 4295 sum = x + y; 4296@end smallexample 4297 4298@noindent 4299This will not work reliably, as the compiler may move the addition back 4300before the volatile @code{asm}. To make it work you need to add an 4301artificial dependency to the @code{asm} referencing a variable in the code 4302you don't want moved, for example: 4303 4304@smallexample 4305 asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv)); 4306 sum = x + y; 4307@end smallexample 4308 4309Similarly, you can't expect a 4310sequence of volatile @code{asm} instructions to remain perfectly 4311consecutive. If you want consecutive output, use a single @code{asm}. 4312Also, GCC will perform some optimizations across a volatile @code{asm} 4313instruction; GCC does not ``forget everything'' when it encounters 4314a volatile @code{asm} instruction the way some other compilers do. 4315 4316An @code{asm} instruction without any output operands will be treated 4317identically to a volatile @code{asm} instruction. 4318 4319It is a natural idea to look for a way to give access to the condition 4320code left by the assembler instruction. However, when we attempted to 4321implement this, we found no way to make it work reliably. The problem 4322is that output operands might need reloading, which would result in 4323additional following ``store'' instructions. On most machines, these 4324instructions would alter the condition code before there was time to 4325test it. This problem doesn't arise for ordinary ``test'' and 4326``compare'' instructions because they don't have any output operands. 4327 4328For reasons similar to those described above, it is not possible to give 4329an assembler instruction access to the condition code left by previous 4330instructions. 4331 4332If you are writing a header file that should be includable in ISO C 4333programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate 4334Keywords}. 4335 4336@subsection Size of an @code{asm} 4337 4338Some targets require that GCC track the size of each instruction used in 4339order to generate correct code. Because the final length of an 4340@code{asm} is only known by the assembler, GCC must make an estimate as 4341to how big it will be. The estimate is formed by counting the number of 4342statements in the pattern of the @code{asm} and multiplying that by the 4343length of the longest instruction on that processor. Statements in the 4344@code{asm} are identified by newline characters and whatever statement 4345separator characters are supported by the assembler; on most processors 4346this is the `@code{;}' character. 4347 4348Normally, GCC's estimate is perfectly adequate to ensure that correct 4349code is generated, but it is possible to confuse the compiler if you use 4350pseudo instructions or assembler macros that expand into multiple real 4351instructions or if you use assembler directives that expand to more 4352space in the object file than would be needed for a single instruction. 4353If this happens then the assembler will produce a diagnostic saying that 4354a label is unreachable. 4355 4356@subsection i386 floating point asm operands 4357 4358There are several rules on the usage of stack-like regs in 4359asm_operands insns. These rules apply only to the operands that are 4360stack-like regs: 4361 4362@enumerate 4363@item 4364Given a set of input regs that die in an asm_operands, it is 4365necessary to know which are implicitly popped by the asm, and 4366which must be explicitly popped by gcc. 4367 4368An input reg that is implicitly popped by the asm must be 4369explicitly clobbered, unless it is constrained to match an 4370output operand. 4371 4372@item 4373For any input reg that is implicitly popped by an asm, it is 4374necessary to know how to adjust the stack to compensate for the pop. 4375If any non-popped input is closer to the top of the reg-stack than 4376the implicitly popped reg, it would not be possible to know what the 4377stack looked like---it's not clear how the rest of the stack ``slides 4378up''. 4379 4380All implicitly popped input regs must be closer to the top of 4381the reg-stack than any input that is not implicitly popped. 4382 4383It is possible that if an input dies in an insn, reload might 4384use the input reg for an output reload. Consider this example: 4385 4386@smallexample 4387asm ("foo" : "=t" (a) : "f" (b)); 4388@end smallexample 4389 4390This asm says that input B is not popped by the asm, and that 4391the asm pushes a result onto the reg-stack, i.e., the stack is one 4392deeper after the asm than it was before. But, it is possible that 4393reload will think that it can use the same reg for both the input and 4394the output, if input B dies in this insn. 4395 4396If any input operand uses the @code{f} constraint, all output reg 4397constraints must use the @code{&} earlyclobber. 4398 4399The asm above would be written as 4400 4401@smallexample 4402asm ("foo" : "=&t" (a) : "f" (b)); 4403@end smallexample 4404 4405@item 4406Some operands need to be in particular places on the stack. All 4407output operands fall in this category---there is no other way to 4408know which regs the outputs appear in unless the user indicates 4409this in the constraints. 4410 4411Output operands must specifically indicate which reg an output 4412appears in after an asm. @code{=f} is not allowed: the operand 4413constraints must select a class with a single reg. 4414 4415@item 4416Output operands may not be ``inserted'' between existing stack regs. 4417Since no 387 opcode uses a read/write operand, all output operands 4418are dead before the asm_operands, and are pushed by the asm_operands. 4419It makes no sense to push anywhere but the top of the reg-stack. 4420 4421Output operands must start at the top of the reg-stack: output 4422operands may not ``skip'' a reg. 4423 4424@item 4425Some asm statements may need extra stack space for internal 4426calculations. This can be guaranteed by clobbering stack registers 4427unrelated to the inputs and outputs. 4428 4429@end enumerate 4430 4431Here are a couple of reasonable asms to want to write. This asm 4432takes one input, which is internally popped, and produces two outputs. 4433 4434@smallexample 4435asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); 4436@end smallexample 4437 4438This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode, 4439and replaces them with one output. The user must code the @code{st(1)} 4440clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs. 4441 4442@smallexample 4443asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); 4444@end smallexample 4445 4446@include md.texi 4447 4448@node Asm Labels 4449@section Controlling Names Used in Assembler Code 4450@cindex assembler names for identifiers 4451@cindex names used in assembler code 4452@cindex identifiers, names in assembler code 4453 4454You can specify the name to be used in the assembler code for a C 4455function or variable by writing the @code{asm} (or @code{__asm__}) 4456keyword after the declarator as follows: 4457 4458@smallexample 4459int foo asm ("myfoo") = 2; 4460@end smallexample 4461 4462@noindent 4463This specifies that the name to be used for the variable @code{foo} in 4464the assembler code should be @samp{myfoo} rather than the usual 4465@samp{_foo}. 4466 4467On systems where an underscore is normally prepended to the name of a C 4468function or variable, this feature allows you to define names for the 4469linker that do not start with an underscore. 4470 4471It does not make sense to use this feature with a non-static local 4472variable since such variables do not have assembler names. If you are 4473trying to put the variable in a particular register, see @ref{Explicit 4474Reg Vars}. GCC presently accepts such code with a warning, but will 4475probably be changed to issue an error, rather than a warning, in the 4476future. 4477 4478You cannot use @code{asm} in this way in a function @emph{definition}; but 4479you can get the same effect by writing a declaration for the function 4480before its definition and putting @code{asm} there, like this: 4481 4482@smallexample 4483extern func () asm ("FUNC"); 4484 4485func (x, y) 4486 int x, y; 4487/* @r{@dots{}} */ 4488@end smallexample 4489 4490It is up to you to make sure that the assembler names you choose do not 4491conflict with any other assembler symbols. Also, you must not use a 4492register name; that would produce completely invalid assembler code. GCC 4493does not as yet have the ability to store static variables in registers. 4494Perhaps that will be added. 4495 4496@node Explicit Reg Vars 4497@section Variables in Specified Registers 4498@cindex explicit register variables 4499@cindex variables in specified registers 4500@cindex specified registers 4501@cindex registers, global allocation 4502 4503GNU C allows you to put a few global variables into specified hardware 4504registers. You can also specify the register in which an ordinary 4505register variable should be allocated. 4506 4507@itemize @bullet 4508@item 4509Global register variables reserve registers throughout the program. 4510This may be useful in programs such as programming language 4511interpreters which have a couple of global variables that are accessed 4512very often. 4513 4514@item 4515Local register variables in specific registers do not reserve the 4516registers, except at the point where they are used as input or output 4517operands in an @code{asm} statement and the @code{asm} statement itself is 4518not deleted. The compiler's data flow analysis is capable of determining 4519where the specified registers contain live values, and where they are 4520available for other uses. Stores into local register variables may be deleted 4521when they appear to be dead according to dataflow analysis. References 4522to local register variables may be deleted or moved or simplified. 4523 4524These local variables are sometimes convenient for use with the extended 4525@code{asm} feature (@pxref{Extended Asm}), if you want to write one 4526output of the assembler instruction directly into a particular register. 4527(This will work provided the register you specify fits the constraints 4528specified for that operand in the @code{asm}.) 4529@end itemize 4530 4531@menu 4532* Global Reg Vars:: 4533* Local Reg Vars:: 4534@end menu 4535 4536@node Global Reg Vars 4537@subsection Defining Global Register Variables 4538@cindex global register variables 4539@cindex registers, global variables in 4540 4541You can define a global register variable in GNU C like this: 4542 4543@smallexample 4544register int *foo asm ("a5"); 4545@end smallexample 4546 4547@noindent 4548Here @code{a5} is the name of the register which should be used. Choose a 4549register which is normally saved and restored by function calls on your 4550machine, so that library routines will not clobber it. 4551 4552Naturally the register name is cpu-dependent, so you would need to 4553conditionalize your program according to cpu type. The register 4554@code{a5} would be a good choice on a 68000 for a variable of pointer 4555type. On machines with register windows, be sure to choose a ``global'' 4556register that is not affected magically by the function call mechanism. 4557 4558In addition, operating systems on one type of cpu may differ in how they 4559name the registers; then you would need additional conditionals. For 4560example, some 68000 operating systems call this register @code{%a5}. 4561 4562Eventually there may be a way of asking the compiler to choose a register 4563automatically, but first we need to figure out how it should choose and 4564how to enable you to guide the choice. No solution is evident. 4565 4566Defining a global register variable in a certain register reserves that 4567register entirely for this use, at least within the current compilation. 4568The register will not be allocated for any other purpose in the functions 4569in the current compilation. The register will not be saved and restored by 4570these functions. Stores into this register are never deleted even if they 4571would appear to be dead, but references may be deleted or moved or 4572simplified. 4573 4574It is not safe to access the global register variables from signal 4575handlers, or from more than one thread of control, because the system 4576library routines may temporarily use the register for other things (unless 4577you recompile them specially for the task at hand). 4578 4579@cindex @code{qsort}, and global register variables 4580It is not safe for one function that uses a global register variable to 4581call another such function @code{foo} by way of a third function 4582@code{lose} that was compiled without knowledge of this variable (i.e.@: in a 4583different source file in which the variable wasn't declared). This is 4584because @code{lose} might save the register and put some other value there. 4585For example, you can't expect a global register variable to be available in 4586the comparison-function that you pass to @code{qsort}, since @code{qsort} 4587might have put something else in that register. (If you are prepared to 4588recompile @code{qsort} with the same global register variable, you can 4589solve this problem.) 4590 4591If you want to recompile @code{qsort} or other source files which do not 4592actually use your global register variable, so that they will not use that 4593register for any other purpose, then it suffices to specify the compiler 4594option @option{-ffixed-@var{reg}}. You need not actually add a global 4595register declaration to their source code. 4596 4597A function which can alter the value of a global register variable cannot 4598safely be called from a function compiled without this variable, because it 4599could clobber the value the caller expects to find there on return. 4600Therefore, the function which is the entry point into the part of the 4601program that uses the global register variable must explicitly save and 4602restore the value which belongs to its caller. 4603 4604@cindex register variable after @code{longjmp} 4605@cindex global register after @code{longjmp} 4606@cindex value after @code{longjmp} 4607@findex longjmp 4608@findex setjmp 4609On most machines, @code{longjmp} will restore to each global register 4610variable the value it had at the time of the @code{setjmp}. On some 4611machines, however, @code{longjmp} will not change the value of global 4612register variables. To be portable, the function that called @code{setjmp} 4613should make other arrangements to save the values of the global register 4614variables, and to restore them in a @code{longjmp}. This way, the same 4615thing will happen regardless of what @code{longjmp} does. 4616 4617All global register variable declarations must precede all function 4618definitions. If such a declaration could appear after function 4619definitions, the declaration would be too late to prevent the register from 4620being used for other purposes in the preceding functions. 4621 4622Global register variables may not have initial values, because an 4623executable file has no means to supply initial contents for a register. 4624 4625On the SPARC, there are reports that g3 @dots{} g7 are suitable 4626registers, but certain library functions, such as @code{getwd}, as well 4627as the subroutines for division and remainder, modify g3 and g4. g1 and 4628g2 are local temporaries. 4629 4630On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7. 4631Of course, it will not do to use more than a few of those. 4632 4633@node Local Reg Vars 4634@subsection Specifying Registers for Local Variables 4635@cindex local variables, specifying registers 4636@cindex specifying registers for local variables 4637@cindex registers for local variables 4638 4639You can define a local register variable with a specified register 4640like this: 4641 4642@smallexample 4643register int *foo asm ("a5"); 4644@end smallexample 4645 4646@noindent 4647Here @code{a5} is the name of the register which should be used. Note 4648that this is the same syntax used for defining global register 4649variables, but for a local variable it would appear within a function. 4650 4651Naturally the register name is cpu-dependent, but this is not a 4652problem, since specific registers are most often useful with explicit 4653assembler instructions (@pxref{Extended Asm}). Both of these things 4654generally require that you conditionalize your program according to 4655cpu type. 4656 4657In addition, operating systems on one type of cpu may differ in how they 4658name the registers; then you would need additional conditionals. For 4659example, some 68000 operating systems call this register @code{%a5}. 4660 4661Defining such a register variable does not reserve the register; it 4662remains available for other uses in places where flow control determines 4663the variable's value is not live. 4664 4665This option does not guarantee that GCC will generate code that has 4666this variable in the register you specify at all times. You may not 4667code an explicit reference to this register in the @emph{assembler 4668instruction template} part of an @code{asm} statement and assume it will 4669always refer to this variable. However, using the variable as an 4670@code{asm} @emph{operand} guarantees that the specified register is used 4671for the operand. 4672 4673Stores into local register variables may be deleted when they appear to be dead 4674according to dataflow analysis. References to local register variables may 4675be deleted or moved or simplified. 4676 4677As for global register variables, it's recommended that you choose a 4678register which is normally saved and restored by function calls on 4679your machine, so that library routines will not clobber it. A common 4680pitfall is to initialize multiple call-clobbered registers with 4681arbitrary expressions, where a function call or library call for an 4682arithmetic operator will overwrite a register value from a previous 4683assignment, for example @code{r0} below: 4684@smallexample 4685register int *p1 asm ("r0") = @dots{}; 4686register int *p2 asm ("r1") = @dots{}; 4687@end smallexample 4688In those cases, a solution is to use a temporary variable for 4689each arbitrary expression. @xref{Example of asm with clobbered asm reg}. 4690 4691@node Alternate Keywords 4692@section Alternate Keywords 4693@cindex alternate keywords 4694@cindex keywords, alternate 4695 4696@option{-ansi} and the various @option{-std} options disable certain 4697keywords. This causes trouble when you want to use GNU C extensions, or 4698a general-purpose header file that should be usable by all programs, 4699including ISO C programs. The keywords @code{asm}, @code{typeof} and 4700@code{inline} are not available in programs compiled with 4701@option{-ansi} or @option{-std} (although @code{inline} can be used in a 4702program compiled with @option{-std=c99}). The ISO C99 keyword 4703@code{restrict} is only available when @option{-std=gnu99} (which will 4704eventually be the default) or @option{-std=c99} (or the equivalent 4705@option{-std=iso9899:1999}) is used. 4706 4707The way to solve these problems is to put @samp{__} at the beginning and 4708end of each problematical keyword. For example, use @code{__asm__} 4709instead of @code{asm}, and @code{__inline__} instead of @code{inline}. 4710 4711Other C compilers won't accept these alternative keywords; if you want to 4712compile with another compiler, you can define the alternate keywords as 4713macros to replace them with the customary keywords. It looks like this: 4714 4715@smallexample 4716#ifndef __GNUC__ 4717#define __asm__ asm 4718#endif 4719@end smallexample 4720 4721@findex __extension__ 4722@opindex pedantic 4723@option{-pedantic} and other options cause warnings for many GNU C extensions. 4724You can 4725prevent such warnings within one expression by writing 4726@code{__extension__} before the expression. @code{__extension__} has no 4727effect aside from this. 4728 4729@node Incomplete Enums 4730@section Incomplete @code{enum} Types 4731 4732You can define an @code{enum} tag without specifying its possible values. 4733This results in an incomplete type, much like what you get if you write 4734@code{struct foo} without describing the elements. A later declaration 4735which does specify the possible values completes the type. 4736 4737You can't allocate variables or storage using the type while it is 4738incomplete. However, you can work with pointers to that type. 4739 4740This extension may not be very useful, but it makes the handling of 4741@code{enum} more consistent with the way @code{struct} and @code{union} 4742are handled. 4743 4744This extension is not supported by GNU C++. 4745 4746@node Function Names 4747@section Function Names as Strings 4748@cindex @code{__func__} identifier 4749@cindex @code{__FUNCTION__} identifier 4750@cindex @code{__PRETTY_FUNCTION__} identifier 4751 4752GCC provides three magic variables which hold the name of the current 4753function, as a string. The first of these is @code{__func__}, which 4754is part of the C99 standard: 4755 4756@display 4757The identifier @code{__func__} is implicitly declared by the translator 4758as if, immediately following the opening brace of each function 4759definition, the declaration 4760 4761@smallexample 4762static const char __func__[] = "function-name"; 4763@end smallexample 4764 4765appeared, where function-name is the name of the lexically-enclosing 4766function. This name is the unadorned name of the function. 4767@end display 4768 4769@code{__FUNCTION__} is another name for @code{__func__}. Older 4770versions of GCC recognize only this name. However, it is not 4771standardized. For maximum portability, we recommend you use 4772@code{__func__}, but provide a fallback definition with the 4773preprocessor: 4774 4775@smallexample 4776#if __STDC_VERSION__ < 199901L 4777# if __GNUC__ >= 2 4778# define __func__ __FUNCTION__ 4779# else 4780# define __func__ "<unknown>" 4781# endif 4782#endif 4783@end smallexample 4784 4785In C, @code{__PRETTY_FUNCTION__} is yet another name for 4786@code{__func__}. However, in C++, @code{__PRETTY_FUNCTION__} contains 4787the type signature of the function as well as its bare name. For 4788example, this program: 4789 4790@smallexample 4791extern "C" @{ 4792extern int printf (char *, ...); 4793@} 4794 4795class a @{ 4796 public: 4797 void sub (int i) 4798 @{ 4799 printf ("__FUNCTION__ = %s\n", __FUNCTION__); 4800 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); 4801 @} 4802@}; 4803 4804int 4805main (void) 4806@{ 4807 a ax; 4808 ax.sub (0); 4809 return 0; 4810@} 4811@end smallexample 4812 4813@noindent 4814gives this output: 4815 4816@smallexample 4817__FUNCTION__ = sub 4818__PRETTY_FUNCTION__ = void a::sub(int) 4819@end smallexample 4820 4821These identifiers are not preprocessor macros. In GCC 3.3 and 4822earlier, in C only, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} 4823were treated as string literals; they could be used to initialize 4824@code{char} arrays, and they could be concatenated with other string 4825literals. GCC 3.4 and later treat them as variables, like 4826@code{__func__}. In C++, @code{__FUNCTION__} and 4827@code{__PRETTY_FUNCTION__} have always been variables. 4828 4829@node Return Address 4830@section Getting the Return or Frame Address of a Function 4831 4832These functions may be used to get information about the callers of a 4833function. 4834 4835@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) 4836This function returns the return address of the current function, or of 4837one of its callers. The @var{level} argument is number of frames to 4838scan up the call stack. A value of @code{0} yields the return address 4839of the current function, a value of @code{1} yields the return address 4840of the caller of the current function, and so forth. When inlining 4841the expected behavior is that the function will return the address of 4842the function that will be returned to. To work around this behavior use 4843the @code{noinline} function attribute. 4844 4845The @var{level} argument must be a constant integer. 4846 4847On some machines it may be impossible to determine the return address of 4848any function other than the current one; in such cases, or when the top 4849of the stack has been reached, this function will return @code{0} or a 4850random value. In addition, @code{__builtin_frame_address} may be used 4851to determine if the top of the stack has been reached. 4852 4853This function should only be used with a nonzero argument for debugging 4854purposes. 4855@end deftypefn 4856 4857@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) 4858This function is similar to @code{__builtin_return_address}, but it 4859returns the address of the function frame rather than the return address 4860of the function. Calling @code{__builtin_frame_address} with a value of 4861@code{0} yields the frame address of the current function, a value of 4862@code{1} yields the frame address of the caller of the current function, 4863and so forth. 4864 4865The frame is the area on the stack which holds local variables and saved 4866registers. The frame address is normally the address of the first word 4867pushed on to the stack by the function. However, the exact definition 4868depends upon the processor and the calling convention. If the processor 4869has a dedicated frame pointer register, and the function has a frame, 4870then @code{__builtin_frame_address} will return the value of the frame 4871pointer register. 4872 4873On some machines it may be impossible to determine the frame address of 4874any function other than the current one; in such cases, or when the top 4875of the stack has been reached, this function will return @code{0} if 4876the first frame pointer is properly initialized by the startup code. 4877 4878This function should only be used with a nonzero argument for debugging 4879purposes. 4880@end deftypefn 4881 4882@node Vector Extensions 4883@section Using vector instructions through built-in functions 4884 4885On some targets, the instruction set contains SIMD vector instructions that 4886operate on multiple values contained in one large register at the same time. 4887For example, on the i386 the MMX, 3Dnow! and SSE extensions can be used 4888this way. 4889 4890The first step in using these extensions is to provide the necessary data 4891types. This should be done using an appropriate @code{typedef}: 4892 4893@smallexample 4894typedef int v4si __attribute__ ((vector_size (16))); 4895@end smallexample 4896 4897The @code{int} type specifies the base type, while the attribute specifies 4898the vector size for the variable, measured in bytes. For example, the 4899declaration above causes the compiler to set the mode for the @code{v4si} 4900type to be 16 bytes wide and divided into @code{int} sized units. For 4901a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the 4902corresponding mode of @code{foo} will be @acronym{V4SI}. 4903 4904The @code{vector_size} attribute is only applicable to integral and 4905float scalars, although arrays, pointers, and function return values 4906are allowed in conjunction with this construct. 4907 4908All the basic integer types can be used as base types, both as signed 4909and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, 4910@code{long long}. In addition, @code{float} and @code{double} can be 4911used to build floating-point vector types. 4912 4913Specifying a combination that is not valid for the current architecture 4914will cause GCC to synthesize the instructions using a narrower mode. 4915For example, if you specify a variable of type @code{V4SI} and your 4916architecture does not allow for this specific SIMD type, GCC will 4917produce code that uses 4 @code{SIs}. 4918 4919The types defined in this manner can be used with a subset of normal C 4920operations. Currently, GCC will allow using the following operators 4921on these types: @code{+, -, *, /, unary minus, ^, |, &, ~}@. 4922 4923The operations behave like C++ @code{valarrays}. Addition is defined as 4924the addition of the corresponding elements of the operands. For 4925example, in the code below, each of the 4 elements in @var{a} will be 4926added to the corresponding 4 elements in @var{b} and the resulting 4927vector will be stored in @var{c}. 4928 4929@smallexample 4930typedef int v4si __attribute__ ((vector_size (16))); 4931 4932v4si a, b, c; 4933 4934c = a + b; 4935@end smallexample 4936 4937Subtraction, multiplication, division, and the logical operations 4938operate in a similar manner. Likewise, the result of using the unary 4939minus or complement operators on a vector type is a vector whose 4940elements are the negative or complemented values of the corresponding 4941elements in the operand. 4942 4943You can declare variables and use them in function calls and returns, as 4944well as in assignments and some casts. You can specify a vector type as 4945a return type for a function. Vector types can also be used as function 4946arguments. It is possible to cast from one vector type to another, 4947provided they are of the same size (in fact, you can also cast vectors 4948to and from other datatypes of the same size). 4949 4950You cannot operate between vectors of different lengths or different 4951signedness without a cast. 4952 4953A port that supports hardware vector operations, usually provides a set 4954of built-in functions that can be used to operate on vectors. For 4955example, a function to add two vectors and multiply the result by a 4956third could look like this: 4957 4958@smallexample 4959v4si f (v4si a, v4si b, v4si c) 4960@{ 4961 v4si tmp = __builtin_addv4si (a, b); 4962 return __builtin_mulv4si (tmp, c); 4963@} 4964 4965@end smallexample 4966 4967@node Offsetof 4968@section Offsetof 4969@findex __builtin_offsetof 4970 4971GCC implements for both C and C++ a syntactic extension to implement 4972the @code{offsetof} macro. 4973 4974@smallexample 4975primary: 4976 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" 4977 4978offsetof_member_designator: 4979 @code{identifier} 4980 | offsetof_member_designator "." @code{identifier} 4981 | offsetof_member_designator "[" @code{expr} "]" 4982@end smallexample 4983 4984This extension is sufficient such that 4985 4986@smallexample 4987#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) 4988@end smallexample 4989 4990is a suitable definition of the @code{offsetof} macro. In C++, @var{type} 4991may be dependent. In either case, @var{member} may consist of a single 4992identifier, or a sequence of member accesses and array references. 4993 4994@node Atomic Builtins 4995@section Built-in functions for atomic memory access 4996 4997The following builtins are intended to be compatible with those described 4998in the @cite{Intel Itanium Processor-specific Application Binary Interface}, 4999section 7.4. As such, they depart from the normal GCC practice of using 5000the ``__builtin_'' prefix, and further that they are overloaded such that 5001they work on multiple types. 5002 5003The definition given in the Intel documentation allows only for the use of 5004the types @code{int}, @code{long}, @code{long long} as well as their unsigned 5005counterparts. GCC will allow any integral scalar or pointer type that is 50061, 2, 4 or 8 bytes in length. 5007 5008Not all operations are supported by all target processors. If a particular 5009operation cannot be implemented on the target processor, a warning will be 5010generated and a call an external function will be generated. The external 5011function will carry the same name as the builtin, with an additional suffix 5012@samp{_@var{n}} where @var{n} is the size of the data type. 5013 5014@c ??? Should we have a mechanism to suppress this warning? This is almost 5015@c useful for implementing the operation under the control of an external 5016@c mutex. 5017 5018In most cases, these builtins are considered a @dfn{full barrier}. That is, 5019no memory operand will be moved across the operation, either forward or 5020backward. Further, instructions will be issued as necessary to prevent the 5021processor from speculating loads across the operation and from queuing stores 5022after the operation. 5023 5024All of the routines are are described in the Intel documentation to take 5025``an optional list of variables protected by the memory barrier''. It's 5026not clear what is meant by that; it could mean that @emph{only} the 5027following variables are protected, or it could mean that these variables 5028should in addition be protected. At present GCC ignores this list and 5029protects all variables which are globally accessible. If in the future 5030we make some use of this list, an empty list will continue to mean all 5031globally accessible variables. 5032 5033@table @code 5034@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) 5035@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) 5036@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) 5037@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) 5038@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) 5039@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) 5040@findex __sync_fetch_and_add 5041@findex __sync_fetch_and_sub 5042@findex __sync_fetch_and_or 5043@findex __sync_fetch_and_and 5044@findex __sync_fetch_and_xor 5045@findex __sync_fetch_and_nand 5046These builtins perform the operation suggested by the name, and 5047returns the value that had previously been in memory. That is, 5048 5049@smallexample 5050@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} 5051@{ tmp = *ptr; *ptr = ~tmp & value; return tmp; @} // nand 5052@end smallexample 5053 5054@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) 5055@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) 5056@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) 5057@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) 5058@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) 5059@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) 5060@findex __sync_add_and_fetch 5061@findex __sync_sub_and_fetch 5062@findex __sync_or_and_fetch 5063@findex __sync_and_and_fetch 5064@findex __sync_xor_and_fetch 5065@findex __sync_nand_and_fetch 5066These builtins perform the operation suggested by the name, and 5067return the new value. That is, 5068 5069@smallexample 5070@{ *ptr @var{op}= value; return *ptr; @} 5071@{ *ptr = ~*ptr & value; return *ptr; @} // nand 5072@end smallexample 5073 5074@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...) 5075@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...) 5076@findex __sync_bool_compare_and_swap 5077@findex __sync_val_compare_and_swap 5078These builtins perform an atomic compare and swap. That is, if the current 5079value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into 5080@code{*@var{ptr}}. 5081 5082The ``bool'' version returns true if the comparison is successful and 5083@var{newval} was written. The ``val'' version returns the contents 5084of @code{*@var{ptr}} before the operation. 5085 5086@item __sync_synchronize (...) 5087@findex __sync_synchronize 5088This builtin issues a full memory barrier. 5089 5090@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) 5091@findex __sync_lock_test_and_set 5092This builtin, as described by Intel, is not a traditional test-and-set 5093operation, but rather an atomic exchange operation. It writes @var{value} 5094into @code{*@var{ptr}}, and returns the previous contents of 5095@code{*@var{ptr}}. 5096 5097Many targets have only minimal support for such locks, and do not support 5098a full exchange operation. In this case, a target may support reduced 5099functionality here by which the @emph{only} valid value to store is the 5100immediate constant 1. The exact value actually stored in @code{*@var{ptr}} 5101is implementation defined. 5102 5103This builtin is not a full barrier, but rather an @dfn{acquire barrier}. 5104This means that references after the builtin cannot move to (or be 5105speculated to) before the builtin, but previous memory stores may not 5106be globally visible yet, and previous memory loads may not yet be 5107satisfied. 5108 5109@item void __sync_lock_release (@var{type} *ptr, ...) 5110@findex __sync_lock_release 5111This builtin releases the lock acquired by @code{__sync_lock_test_and_set}. 5112Normally this means writing the constant 0 to @code{*@var{ptr}}. 5113 5114This builtin is not a full barrier, but rather a @dfn{release barrier}. 5115This means that all previous memory stores are globally visible, and all 5116previous memory loads have been satisfied, but following memory reads 5117are not prevented from being speculated to before the barrier. 5118@end table 5119 5120@node Object Size Checking 5121@section Object Size Checking Builtins 5122@findex __builtin_object_size 5123@findex __builtin___memcpy_chk 5124@findex __builtin___mempcpy_chk 5125@findex __builtin___memmove_chk 5126@findex __builtin___memset_chk 5127@findex __builtin___strcpy_chk 5128@findex __builtin___stpcpy_chk 5129@findex __builtin___strncpy_chk 5130@findex __builtin___strcat_chk 5131@findex __builtin___strncat_chk 5132@findex __builtin___sprintf_chk 5133@findex __builtin___snprintf_chk 5134@findex __builtin___vsprintf_chk 5135@findex __builtin___vsnprintf_chk 5136@findex __builtin___printf_chk 5137@findex __builtin___vprintf_chk 5138@findex __builtin___fprintf_chk 5139@findex __builtin___vfprintf_chk 5140 5141GCC implements a limited buffer overflow protection mechanism 5142that can prevent some buffer overflow attacks. 5143 5144@deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type}) 5145is a built-in construct that returns a constant number of bytes from 5146@var{ptr} to the end of the object @var{ptr} pointer points to 5147(if known at compile time). @code{__builtin_object_size} never evaluates 5148its arguments for side-effects. If there are any side-effects in them, it 5149returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 5150for @var{type} 2 or 3. If there are multiple objects @var{ptr} can 5151point to and all of them are known at compile time, the returned number 5152is the maximum of remaining byte counts in those objects if @var{type} & 2 is 51530 and minimum if nonzero. If it is not possible to determine which objects 5154@var{ptr} points to at compile time, @code{__builtin_object_size} should 5155return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 5156for @var{type} 2 or 3. 5157 5158@var{type} is an integer constant from 0 to 3. If the least significant 5159bit is clear, objects are whole variables, if it is set, a closest 5160surrounding subobject is considered the object a pointer points to. 5161The second bit determines if maximum or minimum of remaining bytes 5162is computed. 5163 5164@smallexample 5165struct V @{ char buf1[10]; int b; char buf2[10]; @} var; 5166char *p = &var.buf1[1], *q = &var.b; 5167 5168/* Here the object p points to is var. */ 5169assert (__builtin_object_size (p, 0) == sizeof (var) - 1); 5170/* The subobject p points to is var.buf1. */ 5171assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); 5172/* The object q points to is var. */ 5173assert (__builtin_object_size (q, 0) 5174 == (char *) (&var + 1) - (char *) &var.b); 5175/* The subobject q points to is var.b. */ 5176assert (__builtin_object_size (q, 1) == sizeof (var.b)); 5177@end smallexample 5178@end deftypefn 5179 5180There are built-in functions added for many common string operation 5181functions, e.g. for @code{memcpy} @code{__builtin___memcpy_chk} 5182built-in is provided. This built-in has an additional last argument, 5183which is the number of bytes remaining in object the @var{dest} 5184argument points to or @code{(size_t) -1} if the size is not known. 5185 5186The built-in functions are optimized into the normal string functions 5187like @code{memcpy} if the last argument is @code{(size_t) -1} or if 5188it is known at compile time that the destination object will not 5189be overflown. If the compiler can determine at compile time the 5190object will be always overflown, it issues a warning. 5191 5192The intended use can be e.g. 5193 5194@smallexample 5195#undef memcpy 5196#define bos0(dest) __builtin_object_size (dest, 0) 5197#define memcpy(dest, src, n) \ 5198 __builtin___memcpy_chk (dest, src, n, bos0 (dest)) 5199 5200char *volatile p; 5201char buf[10]; 5202/* It is unknown what object p points to, so this is optimized 5203 into plain memcpy - no checking is possible. */ 5204memcpy (p, "abcde", n); 5205/* Destination is known and length too. It is known at compile 5206 time there will be no overflow. */ 5207memcpy (&buf[5], "abcde", 5); 5208/* Destination is known, but the length is not known at compile time. 5209 This will result in __memcpy_chk call that can check for overflow 5210 at runtime. */ 5211memcpy (&buf[5], "abcde", n); 5212/* Destination is known and it is known at compile time there will 5213 be overflow. There will be a warning and __memcpy_chk call that 5214 will abort the program at runtime. */ 5215memcpy (&buf[6], "abcde", 5); 5216@end smallexample 5217 5218Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, 5219@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, 5220@code{strcat} and @code{strncat}. 5221 5222There are also checking built-in functions for formatted output functions. 5223@smallexample 5224int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); 5225int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, 5226 const char *fmt, ...); 5227int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, 5228 va_list ap); 5229int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, 5230 const char *fmt, va_list ap); 5231@end smallexample 5232 5233The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} 5234etc. functions and can contain implementation specific flags on what 5235additional security measures the checking function might take, such as 5236handling @code{%n} differently. 5237 5238The @var{os} argument is the object size @var{s} points to, like in the 5239other built-in functions. There is a small difference in the behavior 5240though, if @var{os} is @code{(size_t) -1}, the built-in functions are 5241optimized into the non-checking functions only if @var{flag} is 0, otherwise 5242the checking function is called with @var{os} argument set to 5243@code{(size_t) -1}. 5244 5245In addition to this, there are checking built-in functions 5246@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, 5247@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. 5248These have just one additional argument, @var{flag}, right before 5249format string @var{fmt}. If the compiler is able to optimize them to 5250@code{fputc} etc. functions, it will, otherwise the checking function 5251should be called and the @var{flag} argument passed to it. 5252 5253@node Other Builtins 5254@section Other built-in functions provided by GCC 5255@cindex built-in functions 5256@findex __builtin_isgreater 5257@findex __builtin_isgreaterequal 5258@findex __builtin_isless 5259@findex __builtin_islessequal 5260@findex __builtin_islessgreater 5261@findex __builtin_isunordered 5262@findex __builtin_powi 5263@findex __builtin_powif 5264@findex __builtin_powil 5265@findex _Exit 5266@findex _exit 5267@findex abort 5268@findex abs 5269@findex acos 5270@findex acosf 5271@findex acosh 5272@findex acoshf 5273@findex acoshl 5274@findex acosl 5275@findex alloca 5276@findex asin 5277@findex asinf 5278@findex asinh 5279@findex asinhf 5280@findex asinhl 5281@findex asinl 5282@findex atan 5283@findex atan2 5284@findex atan2f 5285@findex atan2l 5286@findex atanf 5287@findex atanh 5288@findex atanhf 5289@findex atanhl 5290@findex atanl 5291@findex bcmp 5292@findex bzero 5293@findex cabs 5294@findex cabsf 5295@findex cabsl 5296@findex cacos 5297@findex cacosf 5298@findex cacosh 5299@findex cacoshf 5300@findex cacoshl 5301@findex cacosl 5302@findex calloc 5303@findex carg 5304@findex cargf 5305@findex cargl 5306@findex casin 5307@findex casinf 5308@findex casinh 5309@findex casinhf 5310@findex casinhl 5311@findex casinl 5312@findex catan 5313@findex catanf 5314@findex catanh 5315@findex catanhf 5316@findex catanhl 5317@findex catanl 5318@findex cbrt 5319@findex cbrtf 5320@findex cbrtl 5321@findex ccos 5322@findex ccosf 5323@findex ccosh 5324@findex ccoshf 5325@findex ccoshl 5326@findex ccosl 5327@findex ceil 5328@findex ceilf 5329@findex ceill 5330@findex cexp 5331@findex cexpf 5332@findex cexpl 5333@findex cimag 5334@findex cimagf 5335@findex cimagl 5336@findex clog 5337@findex clogf 5338@findex clogl 5339@findex conj 5340@findex conjf 5341@findex conjl 5342@findex copysign 5343@findex copysignf 5344@findex copysignl 5345@findex cos 5346@findex cosf 5347@findex cosh 5348@findex coshf 5349@findex coshl 5350@findex cosl 5351@findex cpow 5352@findex cpowf 5353@findex cpowl 5354@findex cproj 5355@findex cprojf 5356@findex cprojl 5357@findex creal 5358@findex crealf 5359@findex creall 5360@findex csin 5361@findex csinf 5362@findex csinh 5363@findex csinhf 5364@findex csinhl 5365@findex csinl 5366@findex csqrt 5367@findex csqrtf 5368@findex csqrtl 5369@findex ctan 5370@findex ctanf 5371@findex ctanh 5372@findex ctanhf 5373@findex ctanhl 5374@findex ctanl 5375@findex dcgettext 5376@findex dgettext 5377@findex drem 5378@findex dremf 5379@findex dreml 5380@findex erf 5381@findex erfc 5382@findex erfcf 5383@findex erfcl 5384@findex erff 5385@findex erfl 5386@findex exit 5387@findex exp 5388@findex exp10 5389@findex exp10f 5390@findex exp10l 5391@findex exp2 5392@findex exp2f 5393@findex exp2l 5394@findex expf 5395@findex expl 5396@findex expm1 5397@findex expm1f 5398@findex expm1l 5399@findex fabs 5400@findex fabsf 5401@findex fabsl 5402@findex fdim 5403@findex fdimf 5404@findex fdiml 5405@findex ffs 5406@findex floor 5407@findex floorf 5408@findex floorl 5409@findex fma 5410@findex fmaf 5411@findex fmal 5412@findex fmax 5413@findex fmaxf 5414@findex fmaxl 5415@findex fmin 5416@findex fminf 5417@findex fminl 5418@findex fmod 5419@findex fmodf 5420@findex fmodl 5421@findex fprintf 5422@findex fprintf_unlocked 5423@findex fputs 5424@findex fputs_unlocked 5425@findex frexp 5426@findex frexpf 5427@findex frexpl 5428@findex fscanf 5429@findex gamma 5430@findex gammaf 5431@findex gammal 5432@findex gettext 5433@findex hypot 5434@findex hypotf 5435@findex hypotl 5436@findex ilogb 5437@findex ilogbf 5438@findex ilogbl 5439@findex imaxabs 5440@findex index 5441@findex isalnum 5442@findex isalpha 5443@findex isascii 5444@findex isblank 5445@findex iscntrl 5446@findex isdigit 5447@findex isgraph 5448@findex islower 5449@findex isprint 5450@findex ispunct 5451@findex isspace 5452@findex isupper 5453@findex iswalnum 5454@findex iswalpha 5455@findex iswblank 5456@findex iswcntrl 5457@findex iswdigit 5458@findex iswgraph 5459@findex iswlower 5460@findex iswprint 5461@findex iswpunct 5462@findex iswspace 5463@findex iswupper 5464@findex iswxdigit 5465@findex isxdigit 5466@findex j0 5467@findex j0f 5468@findex j0l 5469@findex j1 5470@findex j1f 5471@findex j1l 5472@findex jn 5473@findex jnf 5474@findex jnl 5475@findex labs 5476@findex ldexp 5477@findex ldexpf 5478@findex ldexpl 5479@findex lgamma 5480@findex lgammaf 5481@findex lgammal 5482@findex llabs 5483@findex llrint 5484@findex llrintf 5485@findex llrintl 5486@findex llround 5487@findex llroundf 5488@findex llroundl 5489@findex log 5490@findex log10 5491@findex log10f 5492@findex log10l 5493@findex log1p 5494@findex log1pf 5495@findex log1pl 5496@findex log2 5497@findex log2f 5498@findex log2l 5499@findex logb 5500@findex logbf 5501@findex logbl 5502@findex logf 5503@findex logl 5504@findex lrint 5505@findex lrintf 5506@findex lrintl 5507@findex lround 5508@findex lroundf 5509@findex lroundl 5510@findex malloc 5511@findex memcmp 5512@findex memcpy 5513@findex mempcpy 5514@findex memset 5515@findex modf 5516@findex modff 5517@findex modfl 5518@findex nearbyint 5519@findex nearbyintf 5520@findex nearbyintl 5521@findex nextafter 5522@findex nextafterf 5523@findex nextafterl 5524@findex nexttoward 5525@findex nexttowardf 5526@findex nexttowardl 5527@findex pow 5528@findex pow10 5529@findex pow10f 5530@findex pow10l 5531@findex powf 5532@findex powl 5533@findex printf 5534@findex printf_unlocked 5535@findex putchar 5536@findex puts 5537@findex remainder 5538@findex remainderf 5539@findex remainderl 5540@findex remquo 5541@findex remquof 5542@findex remquol 5543@findex rindex 5544@findex rint 5545@findex rintf 5546@findex rintl 5547@findex round 5548@findex roundf 5549@findex roundl 5550@findex scalb 5551@findex scalbf 5552@findex scalbl 5553@findex scalbln 5554@findex scalblnf 5555@findex scalblnf 5556@findex scalbn 5557@findex scalbnf 5558@findex scanfnl 5559@findex signbit 5560@findex signbitf 5561@findex signbitl 5562@findex significand 5563@findex significandf 5564@findex significandl 5565@findex sin 5566@findex sincos 5567@findex sincosf 5568@findex sincosl 5569@findex sinf 5570@findex sinh 5571@findex sinhf 5572@findex sinhl 5573@findex sinl 5574@findex snprintf 5575@findex sprintf 5576@findex sqrt 5577@findex sqrtf 5578@findex sqrtl 5579@findex sscanf 5580@findex stpcpy 5581@findex stpncpy 5582@findex strcasecmp 5583@findex strcat 5584@findex strchr 5585@findex strcmp 5586@findex strcpy 5587@findex strcspn 5588@findex strdup 5589@findex strfmon 5590@findex strftime 5591@findex strlen 5592@findex strncasecmp 5593@findex strncat 5594@findex strncmp 5595@findex strncpy 5596@findex strndup 5597@findex strpbrk 5598@findex strrchr 5599@findex strspn 5600@findex strstr 5601@findex tan 5602@findex tanf 5603@findex tanh 5604@findex tanhf 5605@findex tanhl 5606@findex tanl 5607@findex tgamma 5608@findex tgammaf 5609@findex tgammal 5610@findex toascii 5611@findex tolower 5612@findex toupper 5613@findex towlower 5614@findex towupper 5615@findex trunc 5616@findex truncf 5617@findex truncl 5618@findex vfprintf 5619@findex vfscanf 5620@findex vprintf 5621@findex vscanf 5622@findex vsnprintf 5623@findex vsprintf 5624@findex vsscanf 5625@findex y0 5626@findex y0f 5627@findex y0l 5628@findex y1 5629@findex y1f 5630@findex y1l 5631@findex yn 5632@findex ynf 5633@findex ynl 5634 5635GCC provides a large number of built-in functions other than the ones 5636mentioned above. Some of these are for internal use in the processing 5637of exceptions or variable-length argument lists and will not be 5638documented here because they may change from time to time; we do not 5639recommend general use of these functions. 5640 5641The remaining functions are provided for optimization purposes. 5642 5643@opindex fno-builtin 5644GCC includes built-in versions of many of the functions in the standard 5645C library. The versions prefixed with @code{__builtin_} will always be 5646treated as having the same meaning as the C library function even if you 5647specify the @option{-fno-builtin} option. (@pxref{C Dialect Options}) 5648Many of these functions are only optimized in certain cases; if they are 5649not optimized in a particular case, a call to the library function will 5650be emitted. 5651 5652@opindex ansi 5653@opindex std 5654Outside strict ISO C mode (@option{-ansi}, @option{-std=c89} or 5655@option{-std=c99}), the functions 5656@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, 5657@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, 5658@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, 5659@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, @code{fputs_unlocked}, 5660@code{gammaf}, @code{gammal}, @code{gamma}, @code{gettext}, 5661@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, 5662@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, 5663@code{mempcpy}, @code{pow10f}, @code{pow10l}, @code{pow10}, 5664@code{printf_unlocked}, @code{rindex}, @code{scalbf}, @code{scalbl}, 5665@code{scalb}, @code{signbit}, @code{signbitf}, @code{signbitl}, 5666@code{significandf}, @code{significandl}, @code{significand}, 5667@code{sincosf}, @code{sincosl}, @code{sincos}, @code{stpcpy}, 5668@code{stpncpy}, @code{strcasecmp}, @code{strdup}, @code{strfmon}, 5669@code{strncasecmp}, @code{strndup}, @code{toascii}, @code{y0f}, 5670@code{y0l}, @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, 5671@code{ynl} and @code{yn} 5672may be handled as built-in functions. 5673All these functions have corresponding versions 5674prefixed with @code{__builtin_}, which may be used even in strict C89 5675mode. 5676 5677The ISO C99 functions 5678@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, 5679@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, 5680@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, 5681@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, 5682@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, 5683@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, 5684@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, 5685@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, 5686@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, 5687@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, 5688@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, 5689@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, 5690@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, 5691@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, 5692@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, 5693@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, 5694@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, 5695@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, 5696@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, 5697@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, 5698@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, 5699@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, 5700@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, 5701@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, 5702@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, 5703@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, 5704@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, 5705@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, 5706@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, 5707@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, 5708@code{nextafterf}, @code{nextafterl}, @code{nextafter}, 5709@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, 5710@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, 5711@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, 5712@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, 5713@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, 5714@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, 5715@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, 5716@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} 5717are handled as built-in functions 5718except in strict ISO C90 mode (@option{-ansi} or @option{-std=c89}). 5719 5720There are also built-in versions of the ISO C99 functions 5721@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, 5722@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, 5723@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, 5724@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, 5725@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, 5726@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, 5727@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, 5728@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, 5729@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} 5730that are recognized in any mode since ISO C90 reserves these names for 5731the purpose to which ISO C99 puts them. All these functions have 5732corresponding versions prefixed with @code{__builtin_}. 5733 5734The ISO C94 functions 5735@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, 5736@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, 5737@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and 5738@code{towupper} 5739are handled as built-in functions 5740except in strict ISO C90 mode (@option{-ansi} or @option{-std=c89}). 5741 5742The ISO C90 functions 5743@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, 5744@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, 5745@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, 5746@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf}, 5747@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, 5748@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, 5749@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, 5750@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, 5751@code{malloc}, @code{memcmp}, @code{memcpy}, @code{memset}, @code{modf}, 5752@code{pow}, @code{printf}, @code{putchar}, @code{puts}, @code{scanf}, 5753@code{sinh}, @code{sin}, @code{snprintf}, @code{sprintf}, @code{sqrt}, 5754@code{sscanf}, @code{strcat}, @code{strchr}, @code{strcmp}, 5755@code{strcpy}, @code{strcspn}, @code{strlen}, @code{strncat}, 5756@code{strncmp}, @code{strncpy}, @code{strpbrk}, @code{strrchr}, 5757@code{strspn}, @code{strstr}, @code{tanh}, @code{tan}, @code{vfprintf}, 5758@code{vprintf} and @code{vsprintf} 5759are all recognized as built-in functions unless 5760@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} 5761is specified for an individual function). All of these functions have 5762corresponding versions prefixed with @code{__builtin_}. 5763 5764GCC provides built-in versions of the ISO C99 floating point comparison 5765macros that avoid raising exceptions for unordered operands. They have 5766the same names as the standard macros ( @code{isgreater}, 5767@code{isgreaterequal}, @code{isless}, @code{islessequal}, 5768@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} 5769prefixed. We intend for a library implementor to be able to simply 5770@code{#define} each standard macro to its built-in equivalent. 5771 5772@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) 5773 5774You can use the built-in function @code{__builtin_types_compatible_p} to 5775determine whether two types are the same. 5776 5777This built-in function returns 1 if the unqualified versions of the 5778types @var{type1} and @var{type2} (which are types, not expressions) are 5779compatible, 0 otherwise. The result of this built-in function can be 5780used in integer constant expressions. 5781 5782This built-in function ignores top level qualifiers (e.g., @code{const}, 5783@code{volatile}). For example, @code{int} is equivalent to @code{const 5784int}. 5785 5786The type @code{int[]} and @code{int[5]} are compatible. On the other 5787hand, @code{int} and @code{char *} are not compatible, even if the size 5788of their types, on the particular architecture are the same. Also, the 5789amount of pointer indirection is taken into account when determining 5790similarity. Consequently, @code{short *} is not similar to 5791@code{short **}. Furthermore, two types that are typedefed are 5792considered compatible if their underlying types are compatible. 5793 5794An @code{enum} type is not considered to be compatible with another 5795@code{enum} type even if both are compatible with the same integer 5796type; this is what the C standard specifies. 5797For example, @code{enum @{foo, bar@}} is not similar to 5798@code{enum @{hot, dog@}}. 5799 5800You would typically use this function in code whose execution varies 5801depending on the arguments' types. For example: 5802 5803@smallexample 5804#define foo(x) \ 5805 (@{ \ 5806 typeof (x) tmp = (x); \ 5807 if (__builtin_types_compatible_p (typeof (x), long double)) \ 5808 tmp = foo_long_double (tmp); \ 5809 else if (__builtin_types_compatible_p (typeof (x), double)) \ 5810 tmp = foo_double (tmp); \ 5811 else if (__builtin_types_compatible_p (typeof (x), float)) \ 5812 tmp = foo_float (tmp); \ 5813 else \ 5814 abort (); \ 5815 tmp; \ 5816 @}) 5817@end smallexample 5818 5819@emph{Note:} This construct is only available for C@. 5820 5821@end deftypefn 5822 5823@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) 5824 5825You can use the built-in function @code{__builtin_choose_expr} to 5826evaluate code depending on the value of a constant expression. This 5827built-in function returns @var{exp1} if @var{const_exp}, which is a 5828constant expression that must be able to be determined at compile time, 5829is nonzero. Otherwise it returns 0. 5830 5831This built-in function is analogous to the @samp{? :} operator in C, 5832except that the expression returned has its type unaltered by promotion 5833rules. Also, the built-in function does not evaluate the expression 5834that was not chosen. For example, if @var{const_exp} evaluates to true, 5835@var{exp2} is not evaluated even if it has side-effects. 5836 5837This built-in function can return an lvalue if the chosen argument is an 5838lvalue. 5839 5840If @var{exp1} is returned, the return type is the same as @var{exp1}'s 5841type. Similarly, if @var{exp2} is returned, its return type is the same 5842as @var{exp2}. 5843 5844Example: 5845 5846@smallexample 5847#define foo(x) \ 5848 __builtin_choose_expr ( \ 5849 __builtin_types_compatible_p (typeof (x), double), \ 5850 foo_double (x), \ 5851 __builtin_choose_expr ( \ 5852 __builtin_types_compatible_p (typeof (x), float), \ 5853 foo_float (x), \ 5854 /* @r{The void expression results in a compile-time error} \ 5855 @r{when assigning the result to something.} */ \ 5856 (void)0)) 5857@end smallexample 5858 5859@emph{Note:} This construct is only available for C@. Furthermore, the 5860unused expression (@var{exp1} or @var{exp2} depending on the value of 5861@var{const_exp}) may still generate syntax errors. This may change in 5862future revisions. 5863 5864@end deftypefn 5865 5866@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) 5867You can use the built-in function @code{__builtin_constant_p} to 5868determine if a value is known to be constant at compile-time and hence 5869that GCC can perform constant-folding on expressions involving that 5870value. The argument of the function is the value to test. The function 5871returns the integer 1 if the argument is known to be a compile-time 5872constant and 0 if it is not known to be a compile-time constant. A 5873return of 0 does not indicate that the value is @emph{not} a constant, 5874but merely that GCC cannot prove it is a constant with the specified 5875value of the @option{-O} option. 5876 5877You would typically use this function in an embedded application where 5878memory was a critical resource. If you have some complex calculation, 5879you may want it to be folded if it involves constants, but need to call 5880a function if it does not. For example: 5881 5882@smallexample 5883#define Scale_Value(X) \ 5884 (__builtin_constant_p (X) \ 5885 ? ((X) * SCALE + OFFSET) : Scale (X)) 5886@end smallexample 5887 5888You may use this built-in function in either a macro or an inline 5889function. However, if you use it in an inlined function and pass an 5890argument of the function as the argument to the built-in, GCC will 5891never return 1 when you call the inline function with a string constant 5892or compound literal (@pxref{Compound Literals}) and will not return 1 5893when you pass a constant numeric value to the inline function unless you 5894specify the @option{-O} option. 5895 5896You may also use @code{__builtin_constant_p} in initializers for static 5897data. For instance, you can write 5898 5899@smallexample 5900static const int table[] = @{ 5901 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, 5902 /* @r{@dots{}} */ 5903@}; 5904@end smallexample 5905 5906@noindent 5907This is an acceptable initializer even if @var{EXPRESSION} is not a 5908constant expression. GCC must be more conservative about evaluating the 5909built-in in this case, because it has no opportunity to perform 5910optimization. 5911 5912Previous versions of GCC did not accept this built-in in data 5913initializers. The earliest version where it is completely safe is 59143.0.1. 5915@end deftypefn 5916 5917@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) 5918@opindex fprofile-arcs 5919You may use @code{__builtin_expect} to provide the compiler with 5920branch prediction information. In general, you should prefer to 5921use actual profile feedback for this (@option{-fprofile-arcs}), as 5922programmers are notoriously bad at predicting how their programs 5923actually perform. However, there are applications in which this 5924data is hard to collect. 5925 5926The return value is the value of @var{exp}, which should be an 5927integral expression. The value of @var{c} must be a compile-time 5928constant. The semantics of the built-in are that it is expected 5929that @var{exp} == @var{c}. For example: 5930 5931@smallexample 5932if (__builtin_expect (x, 0)) 5933 foo (); 5934@end smallexample 5935 5936@noindent 5937would indicate that we do not expect to call @code{foo}, since 5938we expect @code{x} to be zero. Since you are limited to integral 5939expressions for @var{exp}, you should use constructions such as 5940 5941@smallexample 5942if (__builtin_expect (ptr != NULL, 1)) 5943 error (); 5944@end smallexample 5945 5946@noindent 5947when testing pointer or floating-point values. 5948@end deftypefn 5949 5950@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) 5951This function is used to minimize cache-miss latency by moving data into 5952a cache before it is accessed. 5953You can insert calls to @code{__builtin_prefetch} into code for which 5954you know addresses of data in memory that is likely to be accessed soon. 5955If the target supports them, data prefetch instructions will be generated. 5956If the prefetch is done early enough before the access then the data will 5957be in the cache by the time it is accessed. 5958 5959The value of @var{addr} is the address of the memory to prefetch. 5960There are two optional arguments, @var{rw} and @var{locality}. 5961The value of @var{rw} is a compile-time constant one or zero; one 5962means that the prefetch is preparing for a write to the memory address 5963and zero, the default, means that the prefetch is preparing for a read. 5964The value @var{locality} must be a compile-time constant integer between 5965zero and three. A value of zero means that the data has no temporal 5966locality, so it need not be left in the cache after the access. A value 5967of three means that the data has a high degree of temporal locality and 5968should be left in all levels of cache possible. Values of one and two 5969mean, respectively, a low or moderate degree of temporal locality. The 5970default is three. 5971 5972@smallexample 5973for (i = 0; i < n; i++) 5974 @{ 5975 a[i] = a[i] + b[i]; 5976 __builtin_prefetch (&a[i+j], 1, 1); 5977 __builtin_prefetch (&b[i+j], 0, 1); 5978 /* @r{@dots{}} */ 5979 @} 5980@end smallexample 5981 5982Data prefetch does not generate faults if @var{addr} is invalid, but 5983the address expression itself must be valid. For example, a prefetch 5984of @code{p->next} will not fault if @code{p->next} is not a valid 5985address, but evaluation will fault if @code{p} is not a valid address. 5986 5987If the target does not support data prefetch, the address expression 5988is evaluated if it includes side effects but no other code is generated 5989and GCC does not issue a warning. 5990@end deftypefn 5991 5992@deftypefn {Built-in Function} double __builtin_huge_val (void) 5993Returns a positive infinity, if supported by the floating-point format, 5994else @code{DBL_MAX}. This function is suitable for implementing the 5995ISO C macro @code{HUGE_VAL}. 5996@end deftypefn 5997 5998@deftypefn {Built-in Function} float __builtin_huge_valf (void) 5999Similar to @code{__builtin_huge_val}, except the return type is @code{float}. 6000@end deftypefn 6001 6002@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) 6003Similar to @code{__builtin_huge_val}, except the return 6004type is @code{long double}. 6005@end deftypefn 6006 6007@deftypefn {Built-in Function} double __builtin_inf (void) 6008Similar to @code{__builtin_huge_val}, except a warning is generated 6009if the target floating-point format does not support infinities. 6010@end deftypefn 6011 6012@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) 6013Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. 6014@end deftypefn 6015 6016@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) 6017Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. 6018@end deftypefn 6019 6020@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) 6021Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. 6022@end deftypefn 6023 6024@deftypefn {Built-in Function} float __builtin_inff (void) 6025Similar to @code{__builtin_inf}, except the return type is @code{float}. 6026This function is suitable for implementing the ISO C99 macro @code{INFINITY}. 6027@end deftypefn 6028 6029@deftypefn {Built-in Function} {long double} __builtin_infl (void) 6030Similar to @code{__builtin_inf}, except the return 6031type is @code{long double}. 6032@end deftypefn 6033 6034@deftypefn {Built-in Function} double __builtin_nan (const char *str) 6035This is an implementation of the ISO C99 function @code{nan}. 6036 6037Since ISO C99 defines this function in terms of @code{strtod}, which we 6038do not implement, a description of the parsing is in order. The string 6039is parsed as by @code{strtol}; that is, the base is recognized by 6040leading @samp{0} or @samp{0x} prefixes. The number parsed is placed 6041in the significand such that the least significant bit of the number 6042is at the least significant bit of the significand. The number is 6043truncated to fit the significand field provided. The significand is 6044forced to be a quiet NaN@. 6045 6046This function, if given a string literal all of which would have been 6047consumed by strtol, is evaluated early enough that it is considered a 6048compile-time constant. 6049@end deftypefn 6050 6051@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) 6052Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. 6053@end deftypefn 6054 6055@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) 6056Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. 6057@end deftypefn 6058 6059@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) 6060Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. 6061@end deftypefn 6062 6063@deftypefn {Built-in Function} float __builtin_nanf (const char *str) 6064Similar to @code{__builtin_nan}, except the return type is @code{float}. 6065@end deftypefn 6066 6067@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) 6068Similar to @code{__builtin_nan}, except the return type is @code{long double}. 6069@end deftypefn 6070 6071@deftypefn {Built-in Function} double __builtin_nans (const char *str) 6072Similar to @code{__builtin_nan}, except the significand is forced 6073to be a signaling NaN@. The @code{nans} function is proposed by 6074@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. 6075@end deftypefn 6076 6077@deftypefn {Built-in Function} float __builtin_nansf (const char *str) 6078Similar to @code{__builtin_nans}, except the return type is @code{float}. 6079@end deftypefn 6080 6081@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) 6082Similar to @code{__builtin_nans}, except the return type is @code{long double}. 6083@end deftypefn 6084 6085@deftypefn {Built-in Function} int __builtin_ffs (unsigned int x) 6086Returns one plus the index of the least significant 1-bit of @var{x}, or 6087if @var{x} is zero, returns zero. 6088@end deftypefn 6089 6090@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) 6091Returns the number of leading 0-bits in @var{x}, starting at the most 6092significant bit position. If @var{x} is 0, the result is undefined. 6093@end deftypefn 6094 6095@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) 6096Returns the number of trailing 0-bits in @var{x}, starting at the least 6097significant bit position. If @var{x} is 0, the result is undefined. 6098@end deftypefn 6099 6100@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) 6101Returns the number of 1-bits in @var{x}. 6102@end deftypefn 6103 6104@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) 6105Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} 6106modulo 2. 6107@end deftypefn 6108 6109@deftypefn {Built-in Function} int __builtin_ffsl (unsigned long) 6110Similar to @code{__builtin_ffs}, except the argument type is 6111@code{unsigned long}. 6112@end deftypefn 6113 6114@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) 6115Similar to @code{__builtin_clz}, except the argument type is 6116@code{unsigned long}. 6117@end deftypefn 6118 6119@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) 6120Similar to @code{__builtin_ctz}, except the argument type is 6121@code{unsigned long}. 6122@end deftypefn 6123 6124@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) 6125Similar to @code{__builtin_popcount}, except the argument type is 6126@code{unsigned long}. 6127@end deftypefn 6128 6129@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) 6130Similar to @code{__builtin_parity}, except the argument type is 6131@code{unsigned long}. 6132@end deftypefn 6133 6134@deftypefn {Built-in Function} int __builtin_ffsll (unsigned long long) 6135Similar to @code{__builtin_ffs}, except the argument type is 6136@code{unsigned long long}. 6137@end deftypefn 6138 6139@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) 6140Similar to @code{__builtin_clz}, except the argument type is 6141@code{unsigned long long}. 6142@end deftypefn 6143 6144@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) 6145Similar to @code{__builtin_ctz}, except the argument type is 6146@code{unsigned long long}. 6147@end deftypefn 6148 6149@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) 6150Similar to @code{__builtin_popcount}, except the argument type is 6151@code{unsigned long long}. 6152@end deftypefn 6153 6154@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) 6155Similar to @code{__builtin_parity}, except the argument type is 6156@code{unsigned long long}. 6157@end deftypefn 6158 6159@deftypefn {Built-in Function} double __builtin_powi (double, int) 6160Returns the first argument raised to the power of the second. Unlike the 6161@code{pow} function no guarantees about precision and rounding are made. 6162@end deftypefn 6163 6164@deftypefn {Built-in Function} float __builtin_powif (float, int) 6165Similar to @code{__builtin_powi}, except the argument and return types 6166are @code{float}. 6167@end deftypefn 6168 6169@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) 6170Similar to @code{__builtin_powi}, except the argument and return types 6171are @code{long double}. 6172@end deftypefn 6173 6174@deftypefn {Built-in Function} int32_t __builtin_bswap32 (int32_t x) 6175Returns @var{x} with the order of the bytes reversed; for example, 6176@code{0xaabbccdd} becomes @code{0xddccbbaa}. Byte here always means 6177exactly 8 bits. 6178@end deftypefn 6179 6180@deftypefn {Built-in Function} int64_t __builtin_bswap64 (int64_t x) 6181Similar to @code{__builtin_bswap32}, except the argument and return types 6182are 64-bit. 6183@end deftypefn 6184 6185@node Target Builtins 6186@section Built-in Functions Specific to Particular Target Machines 6187 6188On some target machines, GCC supports many built-in functions specific 6189to those machines. Generally these generate calls to specific machine 6190instructions, but allow the compiler to schedule those calls. 6191 6192@menu 6193* Alpha Built-in Functions:: 6194* ARM Built-in Functions:: 6195* Blackfin Built-in Functions:: 6196* FR-V Built-in Functions:: 6197* X86 Built-in Functions:: 6198* MIPS DSP Built-in Functions:: 6199* MIPS Paired-Single Support:: 6200* PowerPC AltiVec Built-in Functions:: 6201* SPARC VIS Built-in Functions:: 6202@end menu 6203 6204@node Alpha Built-in Functions 6205@subsection Alpha Built-in Functions 6206 6207These built-in functions are available for the Alpha family of 6208processors, depending on the command-line switches used. 6209 6210The following built-in functions are always available. They 6211all generate the machine instruction that is part of the name. 6212 6213@smallexample 6214long __builtin_alpha_implver (void) 6215long __builtin_alpha_rpcc (void) 6216long __builtin_alpha_amask (long) 6217long __builtin_alpha_cmpbge (long, long) 6218long __builtin_alpha_extbl (long, long) 6219long __builtin_alpha_extwl (long, long) 6220long __builtin_alpha_extll (long, long) 6221long __builtin_alpha_extql (long, long) 6222long __builtin_alpha_extwh (long, long) 6223long __builtin_alpha_extlh (long, long) 6224long __builtin_alpha_extqh (long, long) 6225long __builtin_alpha_insbl (long, long) 6226long __builtin_alpha_inswl (long, long) 6227long __builtin_alpha_insll (long, long) 6228long __builtin_alpha_insql (long, long) 6229long __builtin_alpha_inswh (long, long) 6230long __builtin_alpha_inslh (long, long) 6231long __builtin_alpha_insqh (long, long) 6232long __builtin_alpha_mskbl (long, long) 6233long __builtin_alpha_mskwl (long, long) 6234long __builtin_alpha_mskll (long, long) 6235long __builtin_alpha_mskql (long, long) 6236long __builtin_alpha_mskwh (long, long) 6237long __builtin_alpha_msklh (long, long) 6238long __builtin_alpha_mskqh (long, long) 6239long __builtin_alpha_umulh (long, long) 6240long __builtin_alpha_zap (long, long) 6241long __builtin_alpha_zapnot (long, long) 6242@end smallexample 6243 6244The following built-in functions are always with @option{-mmax} 6245or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or 6246later. They all generate the machine instruction that is part 6247of the name. 6248 6249@smallexample 6250long __builtin_alpha_pklb (long) 6251long __builtin_alpha_pkwb (long) 6252long __builtin_alpha_unpkbl (long) 6253long __builtin_alpha_unpkbw (long) 6254long __builtin_alpha_minub8 (long, long) 6255long __builtin_alpha_minsb8 (long, long) 6256long __builtin_alpha_minuw4 (long, long) 6257long __builtin_alpha_minsw4 (long, long) 6258long __builtin_alpha_maxub8 (long, long) 6259long __builtin_alpha_maxsb8 (long, long) 6260long __builtin_alpha_maxuw4 (long, long) 6261long __builtin_alpha_maxsw4 (long, long) 6262long __builtin_alpha_perr (long, long) 6263@end smallexample 6264 6265The following built-in functions are always with @option{-mcix} 6266or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or 6267later. They all generate the machine instruction that is part 6268of the name. 6269 6270@smallexample 6271long __builtin_alpha_cttz (long) 6272long __builtin_alpha_ctlz (long) 6273long __builtin_alpha_ctpop (long) 6274@end smallexample 6275 6276The following builtins are available on systems that use the OSF/1 6277PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} 6278PAL calls, but when invoked with @option{-mtls-kernel}, they invoke 6279@code{rdval} and @code{wrval}. 6280 6281@smallexample 6282void *__builtin_thread_pointer (void) 6283void __builtin_set_thread_pointer (void *) 6284@end smallexample 6285 6286@node ARM Built-in Functions 6287@subsection ARM Built-in Functions 6288 6289These built-in functions are available for the ARM family of 6290processors, when the @option{-mcpu=iwmmxt} switch is used: 6291 6292@smallexample 6293typedef int v2si __attribute__ ((vector_size (8))); 6294typedef short v4hi __attribute__ ((vector_size (8))); 6295typedef char v8qi __attribute__ ((vector_size (8))); 6296 6297int __builtin_arm_getwcx (int) 6298void __builtin_arm_setwcx (int, int) 6299int __builtin_arm_textrmsb (v8qi, int) 6300int __builtin_arm_textrmsh (v4hi, int) 6301int __builtin_arm_textrmsw (v2si, int) 6302int __builtin_arm_textrmub (v8qi, int) 6303int __builtin_arm_textrmuh (v4hi, int) 6304int __builtin_arm_textrmuw (v2si, int) 6305v8qi __builtin_arm_tinsrb (v8qi, int) 6306v4hi __builtin_arm_tinsrh (v4hi, int) 6307v2si __builtin_arm_tinsrw (v2si, int) 6308long long __builtin_arm_tmia (long long, int, int) 6309long long __builtin_arm_tmiabb (long long, int, int) 6310long long __builtin_arm_tmiabt (long long, int, int) 6311long long __builtin_arm_tmiaph (long long, int, int) 6312long long __builtin_arm_tmiatb (long long, int, int) 6313long long __builtin_arm_tmiatt (long long, int, int) 6314int __builtin_arm_tmovmskb (v8qi) 6315int __builtin_arm_tmovmskh (v4hi) 6316int __builtin_arm_tmovmskw (v2si) 6317long long __builtin_arm_waccb (v8qi) 6318long long __builtin_arm_wacch (v4hi) 6319long long __builtin_arm_waccw (v2si) 6320v8qi __builtin_arm_waddb (v8qi, v8qi) 6321v8qi __builtin_arm_waddbss (v8qi, v8qi) 6322v8qi __builtin_arm_waddbus (v8qi, v8qi) 6323v4hi __builtin_arm_waddh (v4hi, v4hi) 6324v4hi __builtin_arm_waddhss (v4hi, v4hi) 6325v4hi __builtin_arm_waddhus (v4hi, v4hi) 6326v2si __builtin_arm_waddw (v2si, v2si) 6327v2si __builtin_arm_waddwss (v2si, v2si) 6328v2si __builtin_arm_waddwus (v2si, v2si) 6329v8qi __builtin_arm_walign (v8qi, v8qi, int) 6330long long __builtin_arm_wand(long long, long long) 6331long long __builtin_arm_wandn (long long, long long) 6332v8qi __builtin_arm_wavg2b (v8qi, v8qi) 6333v8qi __builtin_arm_wavg2br (v8qi, v8qi) 6334v4hi __builtin_arm_wavg2h (v4hi, v4hi) 6335v4hi __builtin_arm_wavg2hr (v4hi, v4hi) 6336v8qi __builtin_arm_wcmpeqb (v8qi, v8qi) 6337v4hi __builtin_arm_wcmpeqh (v4hi, v4hi) 6338v2si __builtin_arm_wcmpeqw (v2si, v2si) 6339v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) 6340v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) 6341v2si __builtin_arm_wcmpgtsw (v2si, v2si) 6342v8qi __builtin_arm_wcmpgtub (v8qi, v8qi) 6343v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) 6344v2si __builtin_arm_wcmpgtuw (v2si, v2si) 6345long long __builtin_arm_wmacs (long long, v4hi, v4hi) 6346long long __builtin_arm_wmacsz (v4hi, v4hi) 6347long long __builtin_arm_wmacu (long long, v4hi, v4hi) 6348long long __builtin_arm_wmacuz (v4hi, v4hi) 6349v4hi __builtin_arm_wmadds (v4hi, v4hi) 6350v4hi __builtin_arm_wmaddu (v4hi, v4hi) 6351v8qi __builtin_arm_wmaxsb (v8qi, v8qi) 6352v4hi __builtin_arm_wmaxsh (v4hi, v4hi) 6353v2si __builtin_arm_wmaxsw (v2si, v2si) 6354v8qi __builtin_arm_wmaxub (v8qi, v8qi) 6355v4hi __builtin_arm_wmaxuh (v4hi, v4hi) 6356v2si __builtin_arm_wmaxuw (v2si, v2si) 6357v8qi __builtin_arm_wminsb (v8qi, v8qi) 6358v4hi __builtin_arm_wminsh (v4hi, v4hi) 6359v2si __builtin_arm_wminsw (v2si, v2si) 6360v8qi __builtin_arm_wminub (v8qi, v8qi) 6361v4hi __builtin_arm_wminuh (v4hi, v4hi) 6362v2si __builtin_arm_wminuw (v2si, v2si) 6363v4hi __builtin_arm_wmulsm (v4hi, v4hi) 6364v4hi __builtin_arm_wmulul (v4hi, v4hi) 6365v4hi __builtin_arm_wmulum (v4hi, v4hi) 6366long long __builtin_arm_wor (long long, long long) 6367v2si __builtin_arm_wpackdss (long long, long long) 6368v2si __builtin_arm_wpackdus (long long, long long) 6369v8qi __builtin_arm_wpackhss (v4hi, v4hi) 6370v8qi __builtin_arm_wpackhus (v4hi, v4hi) 6371v4hi __builtin_arm_wpackwss (v2si, v2si) 6372v4hi __builtin_arm_wpackwus (v2si, v2si) 6373long long __builtin_arm_wrord (long long, long long) 6374long long __builtin_arm_wrordi (long long, int) 6375v4hi __builtin_arm_wrorh (v4hi, long long) 6376v4hi __builtin_arm_wrorhi (v4hi, int) 6377v2si __builtin_arm_wrorw (v2si, long long) 6378v2si __builtin_arm_wrorwi (v2si, int) 6379v2si __builtin_arm_wsadb (v8qi, v8qi) 6380v2si __builtin_arm_wsadbz (v8qi, v8qi) 6381v2si __builtin_arm_wsadh (v4hi, v4hi) 6382v2si __builtin_arm_wsadhz (v4hi, v4hi) 6383v4hi __builtin_arm_wshufh (v4hi, int) 6384long long __builtin_arm_wslld (long long, long long) 6385long long __builtin_arm_wslldi (long long, int) 6386v4hi __builtin_arm_wsllh (v4hi, long long) 6387v4hi __builtin_arm_wsllhi (v4hi, int) 6388v2si __builtin_arm_wsllw (v2si, long long) 6389v2si __builtin_arm_wsllwi (v2si, int) 6390long long __builtin_arm_wsrad (long long, long long) 6391long long __builtin_arm_wsradi (long long, int) 6392v4hi __builtin_arm_wsrah (v4hi, long long) 6393v4hi __builtin_arm_wsrahi (v4hi, int) 6394v2si __builtin_arm_wsraw (v2si, long long) 6395v2si __builtin_arm_wsrawi (v2si, int) 6396long long __builtin_arm_wsrld (long long, long long) 6397long long __builtin_arm_wsrldi (long long, int) 6398v4hi __builtin_arm_wsrlh (v4hi, long long) 6399v4hi __builtin_arm_wsrlhi (v4hi, int) 6400v2si __builtin_arm_wsrlw (v2si, long long) 6401v2si __builtin_arm_wsrlwi (v2si, int) 6402v8qi __builtin_arm_wsubb (v8qi, v8qi) 6403v8qi __builtin_arm_wsubbss (v8qi, v8qi) 6404v8qi __builtin_arm_wsubbus (v8qi, v8qi) 6405v4hi __builtin_arm_wsubh (v4hi, v4hi) 6406v4hi __builtin_arm_wsubhss (v4hi, v4hi) 6407v4hi __builtin_arm_wsubhus (v4hi, v4hi) 6408v2si __builtin_arm_wsubw (v2si, v2si) 6409v2si __builtin_arm_wsubwss (v2si, v2si) 6410v2si __builtin_arm_wsubwus (v2si, v2si) 6411v4hi __builtin_arm_wunpckehsb (v8qi) 6412v2si __builtin_arm_wunpckehsh (v4hi) 6413long long __builtin_arm_wunpckehsw (v2si) 6414v4hi __builtin_arm_wunpckehub (v8qi) 6415v2si __builtin_arm_wunpckehuh (v4hi) 6416long long __builtin_arm_wunpckehuw (v2si) 6417v4hi __builtin_arm_wunpckelsb (v8qi) 6418v2si __builtin_arm_wunpckelsh (v4hi) 6419long long __builtin_arm_wunpckelsw (v2si) 6420v4hi __builtin_arm_wunpckelub (v8qi) 6421v2si __builtin_arm_wunpckeluh (v4hi) 6422long long __builtin_arm_wunpckeluw (v2si) 6423v8qi __builtin_arm_wunpckihb (v8qi, v8qi) 6424v4hi __builtin_arm_wunpckihh (v4hi, v4hi) 6425v2si __builtin_arm_wunpckihw (v2si, v2si) 6426v8qi __builtin_arm_wunpckilb (v8qi, v8qi) 6427v4hi __builtin_arm_wunpckilh (v4hi, v4hi) 6428v2si __builtin_arm_wunpckilw (v2si, v2si) 6429long long __builtin_arm_wxor (long long, long long) 6430long long __builtin_arm_wzero () 6431@end smallexample 6432 6433@node Blackfin Built-in Functions 6434@subsection Blackfin Built-in Functions 6435 6436Currently, there are two Blackfin-specific built-in functions. These are 6437used for generating @code{CSYNC} and @code{SSYNC} machine insns without 6438using inline assembly; by using these built-in functions the compiler can 6439automatically add workarounds for hardware errata involving these 6440instructions. These functions are named as follows: 6441 6442@smallexample 6443void __builtin_bfin_csync (void) 6444void __builtin_bfin_ssync (void) 6445@end smallexample 6446 6447@node FR-V Built-in Functions 6448@subsection FR-V Built-in Functions 6449 6450GCC provides many FR-V-specific built-in functions. In general, 6451these functions are intended to be compatible with those described 6452by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu 6453Semiconductor}. The two exceptions are @code{__MDUNPACKH} and 6454@code{__MBTOHE}, the gcc forms of which pass 128-bit values by 6455pointer rather than by value. 6456 6457Most of the functions are named after specific FR-V instructions. 6458Such functions are said to be ``directly mapped'' and are summarized 6459here in tabular form. 6460 6461@menu 6462* Argument Types:: 6463* Directly-mapped Integer Functions:: 6464* Directly-mapped Media Functions:: 6465* Raw read/write Functions:: 6466* Other Built-in Functions:: 6467@end menu 6468 6469@node Argument Types 6470@subsubsection Argument Types 6471 6472The arguments to the built-in functions can be divided into three groups: 6473register numbers, compile-time constants and run-time values. In order 6474to make this classification clear at a glance, the arguments and return 6475values are given the following pseudo types: 6476 6477@multitable @columnfractions .20 .30 .15 .35 6478@item Pseudo type @tab Real C type @tab Constant? @tab Description 6479@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword 6480@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word 6481@item @code{sw1} @tab @code{int} @tab No @tab a signed word 6482@item @code{uw2} @tab @code{unsigned long long} @tab No 6483@tab an unsigned doubleword 6484@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword 6485@item @code{const} @tab @code{int} @tab Yes @tab an integer constant 6486@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number 6487@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number 6488@end multitable 6489 6490These pseudo types are not defined by GCC, they are simply a notational 6491convenience used in this manual. 6492 6493Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} 6494and @code{sw2} are evaluated at run time. They correspond to 6495register operands in the underlying FR-V instructions. 6496 6497@code{const} arguments represent immediate operands in the underlying 6498FR-V instructions. They must be compile-time constants. 6499 6500@code{acc} arguments are evaluated at compile time and specify the number 6501of an accumulator register. For example, an @code{acc} argument of 2 6502will select the ACC2 register. 6503 6504@code{iacc} arguments are similar to @code{acc} arguments but specify the 6505number of an IACC register. See @pxref{Other Built-in Functions} 6506for more details. 6507 6508@node Directly-mapped Integer Functions 6509@subsubsection Directly-mapped Integer Functions 6510 6511The functions listed below map directly to FR-V I-type instructions. 6512 6513@multitable @columnfractions .45 .32 .23 6514@item Function prototype @tab Example usage @tab Assembly output 6515@item @code{sw1 __ADDSS (sw1, sw1)} 6516@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} 6517@tab @code{ADDSS @var{a},@var{b},@var{c}} 6518@item @code{sw1 __SCAN (sw1, sw1)} 6519@tab @code{@var{c} = __SCAN (@var{a}, @var{b})} 6520@tab @code{SCAN @var{a},@var{b},@var{c}} 6521@item @code{sw1 __SCUTSS (sw1)} 6522@tab @code{@var{b} = __SCUTSS (@var{a})} 6523@tab @code{SCUTSS @var{a},@var{b}} 6524@item @code{sw1 __SLASS (sw1, sw1)} 6525@tab @code{@var{c} = __SLASS (@var{a}, @var{b})} 6526@tab @code{SLASS @var{a},@var{b},@var{c}} 6527@item @code{void __SMASS (sw1, sw1)} 6528@tab @code{__SMASS (@var{a}, @var{b})} 6529@tab @code{SMASS @var{a},@var{b}} 6530@item @code{void __SMSSS (sw1, sw1)} 6531@tab @code{__SMSSS (@var{a}, @var{b})} 6532@tab @code{SMSSS @var{a},@var{b}} 6533@item @code{void __SMU (sw1, sw1)} 6534@tab @code{__SMU (@var{a}, @var{b})} 6535@tab @code{SMU @var{a},@var{b}} 6536@item @code{sw2 __SMUL (sw1, sw1)} 6537@tab @code{@var{c} = __SMUL (@var{a}, @var{b})} 6538@tab @code{SMUL @var{a},@var{b},@var{c}} 6539@item @code{sw1 __SUBSS (sw1, sw1)} 6540@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} 6541@tab @code{SUBSS @var{a},@var{b},@var{c}} 6542@item @code{uw2 __UMUL (uw1, uw1)} 6543@tab @code{@var{c} = __UMUL (@var{a}, @var{b})} 6544@tab @code{UMUL @var{a},@var{b},@var{c}} 6545@end multitable 6546 6547@node Directly-mapped Media Functions 6548@subsubsection Directly-mapped Media Functions 6549 6550The functions listed below map directly to FR-V M-type instructions. 6551 6552@multitable @columnfractions .45 .32 .23 6553@item Function prototype @tab Example usage @tab Assembly output 6554@item @code{uw1 __MABSHS (sw1)} 6555@tab @code{@var{b} = __MABSHS (@var{a})} 6556@tab @code{MABSHS @var{a},@var{b}} 6557@item @code{void __MADDACCS (acc, acc)} 6558@tab @code{__MADDACCS (@var{b}, @var{a})} 6559@tab @code{MADDACCS @var{a},@var{b}} 6560@item @code{sw1 __MADDHSS (sw1, sw1)} 6561@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} 6562@tab @code{MADDHSS @var{a},@var{b},@var{c}} 6563@item @code{uw1 __MADDHUS (uw1, uw1)} 6564@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} 6565@tab @code{MADDHUS @var{a},@var{b},@var{c}} 6566@item @code{uw1 __MAND (uw1, uw1)} 6567@tab @code{@var{c} = __MAND (@var{a}, @var{b})} 6568@tab @code{MAND @var{a},@var{b},@var{c}} 6569@item @code{void __MASACCS (acc, acc)} 6570@tab @code{__MASACCS (@var{b}, @var{a})} 6571@tab @code{MASACCS @var{a},@var{b}} 6572@item @code{uw1 __MAVEH (uw1, uw1)} 6573@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} 6574@tab @code{MAVEH @var{a},@var{b},@var{c}} 6575@item @code{uw2 __MBTOH (uw1)} 6576@tab @code{@var{b} = __MBTOH (@var{a})} 6577@tab @code{MBTOH @var{a},@var{b}} 6578@item @code{void __MBTOHE (uw1 *, uw1)} 6579@tab @code{__MBTOHE (&@var{b}, @var{a})} 6580@tab @code{MBTOHE @var{a},@var{b}} 6581@item @code{void __MCLRACC (acc)} 6582@tab @code{__MCLRACC (@var{a})} 6583@tab @code{MCLRACC @var{a}} 6584@item @code{void __MCLRACCA (void)} 6585@tab @code{__MCLRACCA ()} 6586@tab @code{MCLRACCA} 6587@item @code{uw1 __Mcop1 (uw1, uw1)} 6588@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} 6589@tab @code{Mcop1 @var{a},@var{b},@var{c}} 6590@item @code{uw1 __Mcop2 (uw1, uw1)} 6591@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} 6592@tab @code{Mcop2 @var{a},@var{b},@var{c}} 6593@item @code{uw1 __MCPLHI (uw2, const)} 6594@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} 6595@tab @code{MCPLHI @var{a},#@var{b},@var{c}} 6596@item @code{uw1 __MCPLI (uw2, const)} 6597@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} 6598@tab @code{MCPLI @var{a},#@var{b},@var{c}} 6599@item @code{void __MCPXIS (acc, sw1, sw1)} 6600@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} 6601@tab @code{MCPXIS @var{a},@var{b},@var{c}} 6602@item @code{void __MCPXIU (acc, uw1, uw1)} 6603@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} 6604@tab @code{MCPXIU @var{a},@var{b},@var{c}} 6605@item @code{void __MCPXRS (acc, sw1, sw1)} 6606@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} 6607@tab @code{MCPXRS @var{a},@var{b},@var{c}} 6608@item @code{void __MCPXRU (acc, uw1, uw1)} 6609@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} 6610@tab @code{MCPXRU @var{a},@var{b},@var{c}} 6611@item @code{uw1 __MCUT (acc, uw1)} 6612@tab @code{@var{c} = __MCUT (@var{a}, @var{b})} 6613@tab @code{MCUT @var{a},@var{b},@var{c}} 6614@item @code{uw1 __MCUTSS (acc, sw1)} 6615@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} 6616@tab @code{MCUTSS @var{a},@var{b},@var{c}} 6617@item @code{void __MDADDACCS (acc, acc)} 6618@tab @code{__MDADDACCS (@var{b}, @var{a})} 6619@tab @code{MDADDACCS @var{a},@var{b}} 6620@item @code{void __MDASACCS (acc, acc)} 6621@tab @code{__MDASACCS (@var{b}, @var{a})} 6622@tab @code{MDASACCS @var{a},@var{b}} 6623@item @code{uw2 __MDCUTSSI (acc, const)} 6624@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} 6625@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} 6626@item @code{uw2 __MDPACKH (uw2, uw2)} 6627@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} 6628@tab @code{MDPACKH @var{a},@var{b},@var{c}} 6629@item @code{uw2 __MDROTLI (uw2, const)} 6630@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} 6631@tab @code{MDROTLI @var{a},#@var{b},@var{c}} 6632@item @code{void __MDSUBACCS (acc, acc)} 6633@tab @code{__MDSUBACCS (@var{b}, @var{a})} 6634@tab @code{MDSUBACCS @var{a},@var{b}} 6635@item @code{void __MDUNPACKH (uw1 *, uw2)} 6636@tab @code{__MDUNPACKH (&@var{b}, @var{a})} 6637@tab @code{MDUNPACKH @var{a},@var{b}} 6638@item @code{uw2 __MEXPDHD (uw1, const)} 6639@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} 6640@tab @code{MEXPDHD @var{a},#@var{b},@var{c}} 6641@item @code{uw1 __MEXPDHW (uw1, const)} 6642@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} 6643@tab @code{MEXPDHW @var{a},#@var{b},@var{c}} 6644@item @code{uw1 __MHDSETH (uw1, const)} 6645@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} 6646@tab @code{MHDSETH @var{a},#@var{b},@var{c}} 6647@item @code{sw1 __MHDSETS (const)} 6648@tab @code{@var{b} = __MHDSETS (@var{a})} 6649@tab @code{MHDSETS #@var{a},@var{b}} 6650@item @code{uw1 __MHSETHIH (uw1, const)} 6651@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} 6652@tab @code{MHSETHIH #@var{a},@var{b}} 6653@item @code{sw1 __MHSETHIS (sw1, const)} 6654@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} 6655@tab @code{MHSETHIS #@var{a},@var{b}} 6656@item @code{uw1 __MHSETLOH (uw1, const)} 6657@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} 6658@tab @code{MHSETLOH #@var{a},@var{b}} 6659@item @code{sw1 __MHSETLOS (sw1, const)} 6660@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} 6661@tab @code{MHSETLOS #@var{a},@var{b}} 6662@item @code{uw1 __MHTOB (uw2)} 6663@tab @code{@var{b} = __MHTOB (@var{a})} 6664@tab @code{MHTOB @var{a},@var{b}} 6665@item @code{void __MMACHS (acc, sw1, sw1)} 6666@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} 6667@tab @code{MMACHS @var{a},@var{b},@var{c}} 6668@item @code{void __MMACHU (acc, uw1, uw1)} 6669@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} 6670@tab @code{MMACHU @var{a},@var{b},@var{c}} 6671@item @code{void __MMRDHS (acc, sw1, sw1)} 6672@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} 6673@tab @code{MMRDHS @var{a},@var{b},@var{c}} 6674@item @code{void __MMRDHU (acc, uw1, uw1)} 6675@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} 6676@tab @code{MMRDHU @var{a},@var{b},@var{c}} 6677@item @code{void __MMULHS (acc, sw1, sw1)} 6678@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} 6679@tab @code{MMULHS @var{a},@var{b},@var{c}} 6680@item @code{void __MMULHU (acc, uw1, uw1)} 6681@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} 6682@tab @code{MMULHU @var{a},@var{b},@var{c}} 6683@item @code{void __MMULXHS (acc, sw1, sw1)} 6684@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} 6685@tab @code{MMULXHS @var{a},@var{b},@var{c}} 6686@item @code{void __MMULXHU (acc, uw1, uw1)} 6687@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} 6688@tab @code{MMULXHU @var{a},@var{b},@var{c}} 6689@item @code{uw1 __MNOT (uw1)} 6690@tab @code{@var{b} = __MNOT (@var{a})} 6691@tab @code{MNOT @var{a},@var{b}} 6692@item @code{uw1 __MOR (uw1, uw1)} 6693@tab @code{@var{c} = __MOR (@var{a}, @var{b})} 6694@tab @code{MOR @var{a},@var{b},@var{c}} 6695@item @code{uw1 __MPACKH (uh, uh)} 6696@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} 6697@tab @code{MPACKH @var{a},@var{b},@var{c}} 6698@item @code{sw2 __MQADDHSS (sw2, sw2)} 6699@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} 6700@tab @code{MQADDHSS @var{a},@var{b},@var{c}} 6701@item @code{uw2 __MQADDHUS (uw2, uw2)} 6702@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} 6703@tab @code{MQADDHUS @var{a},@var{b},@var{c}} 6704@item @code{void __MQCPXIS (acc, sw2, sw2)} 6705@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} 6706@tab @code{MQCPXIS @var{a},@var{b},@var{c}} 6707@item @code{void __MQCPXIU (acc, uw2, uw2)} 6708@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} 6709@tab @code{MQCPXIU @var{a},@var{b},@var{c}} 6710@item @code{void __MQCPXRS (acc, sw2, sw2)} 6711@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} 6712@tab @code{MQCPXRS @var{a},@var{b},@var{c}} 6713@item @code{void __MQCPXRU (acc, uw2, uw2)} 6714@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} 6715@tab @code{MQCPXRU @var{a},@var{b},@var{c}} 6716@item @code{sw2 __MQLCLRHS (sw2, sw2)} 6717@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} 6718@tab @code{MQLCLRHS @var{a},@var{b},@var{c}} 6719@item @code{sw2 __MQLMTHS (sw2, sw2)} 6720@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} 6721@tab @code{MQLMTHS @var{a},@var{b},@var{c}} 6722@item @code{void __MQMACHS (acc, sw2, sw2)} 6723@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} 6724@tab @code{MQMACHS @var{a},@var{b},@var{c}} 6725@item @code{void __MQMACHU (acc, uw2, uw2)} 6726@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} 6727@tab @code{MQMACHU @var{a},@var{b},@var{c}} 6728@item @code{void __MQMACXHS (acc, sw2, sw2)} 6729@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} 6730@tab @code{MQMACXHS @var{a},@var{b},@var{c}} 6731@item @code{void __MQMULHS (acc, sw2, sw2)} 6732@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} 6733@tab @code{MQMULHS @var{a},@var{b},@var{c}} 6734@item @code{void __MQMULHU (acc, uw2, uw2)} 6735@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} 6736@tab @code{MQMULHU @var{a},@var{b},@var{c}} 6737@item @code{void __MQMULXHS (acc, sw2, sw2)} 6738@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} 6739@tab @code{MQMULXHS @var{a},@var{b},@var{c}} 6740@item @code{void __MQMULXHU (acc, uw2, uw2)} 6741@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} 6742@tab @code{MQMULXHU @var{a},@var{b},@var{c}} 6743@item @code{sw2 __MQSATHS (sw2, sw2)} 6744@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} 6745@tab @code{MQSATHS @var{a},@var{b},@var{c}} 6746@item @code{uw2 __MQSLLHI (uw2, int)} 6747@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} 6748@tab @code{MQSLLHI @var{a},@var{b},@var{c}} 6749@item @code{sw2 __MQSRAHI (sw2, int)} 6750@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} 6751@tab @code{MQSRAHI @var{a},@var{b},@var{c}} 6752@item @code{sw2 __MQSUBHSS (sw2, sw2)} 6753@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} 6754@tab @code{MQSUBHSS @var{a},@var{b},@var{c}} 6755@item @code{uw2 __MQSUBHUS (uw2, uw2)} 6756@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} 6757@tab @code{MQSUBHUS @var{a},@var{b},@var{c}} 6758@item @code{void __MQXMACHS (acc, sw2, sw2)} 6759@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} 6760@tab @code{MQXMACHS @var{a},@var{b},@var{c}} 6761@item @code{void __MQXMACXHS (acc, sw2, sw2)} 6762@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} 6763@tab @code{MQXMACXHS @var{a},@var{b},@var{c}} 6764@item @code{uw1 __MRDACC (acc)} 6765@tab @code{@var{b} = __MRDACC (@var{a})} 6766@tab @code{MRDACC @var{a},@var{b}} 6767@item @code{uw1 __MRDACCG (acc)} 6768@tab @code{@var{b} = __MRDACCG (@var{a})} 6769@tab @code{MRDACCG @var{a},@var{b}} 6770@item @code{uw1 __MROTLI (uw1, const)} 6771@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} 6772@tab @code{MROTLI @var{a},#@var{b},@var{c}} 6773@item @code{uw1 __MROTRI (uw1, const)} 6774@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} 6775@tab @code{MROTRI @var{a},#@var{b},@var{c}} 6776@item @code{sw1 __MSATHS (sw1, sw1)} 6777@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} 6778@tab @code{MSATHS @var{a},@var{b},@var{c}} 6779@item @code{uw1 __MSATHU (uw1, uw1)} 6780@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} 6781@tab @code{MSATHU @var{a},@var{b},@var{c}} 6782@item @code{uw1 __MSLLHI (uw1, const)} 6783@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} 6784@tab @code{MSLLHI @var{a},#@var{b},@var{c}} 6785@item @code{sw1 __MSRAHI (sw1, const)} 6786@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} 6787@tab @code{MSRAHI @var{a},#@var{b},@var{c}} 6788@item @code{uw1 __MSRLHI (uw1, const)} 6789@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} 6790@tab @code{MSRLHI @var{a},#@var{b},@var{c}} 6791@item @code{void __MSUBACCS (acc, acc)} 6792@tab @code{__MSUBACCS (@var{b}, @var{a})} 6793@tab @code{MSUBACCS @var{a},@var{b}} 6794@item @code{sw1 __MSUBHSS (sw1, sw1)} 6795@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} 6796@tab @code{MSUBHSS @var{a},@var{b},@var{c}} 6797@item @code{uw1 __MSUBHUS (uw1, uw1)} 6798@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} 6799@tab @code{MSUBHUS @var{a},@var{b},@var{c}} 6800@item @code{void __MTRAP (void)} 6801@tab @code{__MTRAP ()} 6802@tab @code{MTRAP} 6803@item @code{uw2 __MUNPACKH (uw1)} 6804@tab @code{@var{b} = __MUNPACKH (@var{a})} 6805@tab @code{MUNPACKH @var{a},@var{b}} 6806@item @code{uw1 __MWCUT (uw2, uw1)} 6807@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} 6808@tab @code{MWCUT @var{a},@var{b},@var{c}} 6809@item @code{void __MWTACC (acc, uw1)} 6810@tab @code{__MWTACC (@var{b}, @var{a})} 6811@tab @code{MWTACC @var{a},@var{b}} 6812@item @code{void __MWTACCG (acc, uw1)} 6813@tab @code{__MWTACCG (@var{b}, @var{a})} 6814@tab @code{MWTACCG @var{a},@var{b}} 6815@item @code{uw1 __MXOR (uw1, uw1)} 6816@tab @code{@var{c} = __MXOR (@var{a}, @var{b})} 6817@tab @code{MXOR @var{a},@var{b},@var{c}} 6818@end multitable 6819 6820@node Raw read/write Functions 6821@subsubsection Raw read/write Functions 6822 6823This sections describes built-in functions related to read and write 6824instructions to access memory. These functions generate 6825@code{membar} instructions to flush the I/O load and stores where 6826appropriate, as described in Fujitsu's manual described above. 6827 6828@table @code 6829 6830@item unsigned char __builtin_read8 (void *@var{data}) 6831@item unsigned short __builtin_read16 (void *@var{data}) 6832@item unsigned long __builtin_read32 (void *@var{data}) 6833@item unsigned long long __builtin_read64 (void *@var{data}) 6834 6835@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) 6836@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) 6837@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) 6838@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) 6839@end table 6840 6841@node Other Built-in Functions 6842@subsubsection Other Built-in Functions 6843 6844This section describes built-in functions that are not named after 6845a specific FR-V instruction. 6846 6847@table @code 6848@item sw2 __IACCreadll (iacc @var{reg}) 6849Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved 6850for future expansion and must be 0. 6851 6852@item sw1 __IACCreadl (iacc @var{reg}) 6853Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. 6854Other values of @var{reg} are rejected as invalid. 6855 6856@item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) 6857Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument 6858is reserved for future expansion and must be 0. 6859 6860@item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) 6861Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} 6862is 1. Other values of @var{reg} are rejected as invalid. 6863 6864@item void __data_prefetch0 (const void *@var{x}) 6865Use the @code{dcpl} instruction to load the contents of address @var{x} 6866into the data cache. 6867 6868@item void __data_prefetch (const void *@var{x}) 6869Use the @code{nldub} instruction to load the contents of address @var{x} 6870into the data cache. The instruction will be issued in slot I1@. 6871@end table 6872 6873@node X86 Built-in Functions 6874@subsection X86 Built-in Functions 6875 6876These built-in functions are available for the i386 and x86-64 family 6877of computers, depending on the command-line switches used. 6878 6879Note that, if you specify command-line switches such as @option{-msse}, 6880the compiler could use the extended instruction sets even if the built-ins 6881are not used explicitly in the program. For this reason, applications 6882which perform runtime CPU detection must compile separate files for each 6883supported architecture, using the appropriate flags. In particular, 6884the file containing the CPU detection code should be compiled without 6885these options. 6886 6887The following machine modes are available for use with MMX built-in functions 6888(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, 6889@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a 6890vector of eight 8-bit integers. Some of the built-in functions operate on 6891MMX registers as a whole 64-bit entity, these use @code{DI} as their mode. 6892 6893If 3Dnow extensions are enabled, @code{V2SF} is used as a mode for a vector 6894of two 32-bit floating point values. 6895 6896If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit 6897floating point values. Some instructions use a vector of four 32-bit 6898integers, these use @code{V4SI}. Finally, some instructions operate on an 6899entire vector register, interpreting it as a 128-bit integer, these use mode 6900@code{TI}. 6901 6902The following built-in functions are made available by @option{-mmmx}. 6903All of them generate the machine instruction that is part of the name. 6904 6905@smallexample 6906v8qi __builtin_ia32_paddb (v8qi, v8qi) 6907v4hi __builtin_ia32_paddw (v4hi, v4hi) 6908v2si __builtin_ia32_paddd (v2si, v2si) 6909v8qi __builtin_ia32_psubb (v8qi, v8qi) 6910v4hi __builtin_ia32_psubw (v4hi, v4hi) 6911v2si __builtin_ia32_psubd (v2si, v2si) 6912v8qi __builtin_ia32_paddsb (v8qi, v8qi) 6913v4hi __builtin_ia32_paddsw (v4hi, v4hi) 6914v8qi __builtin_ia32_psubsb (v8qi, v8qi) 6915v4hi __builtin_ia32_psubsw (v4hi, v4hi) 6916v8qi __builtin_ia32_paddusb (v8qi, v8qi) 6917v4hi __builtin_ia32_paddusw (v4hi, v4hi) 6918v8qi __builtin_ia32_psubusb (v8qi, v8qi) 6919v4hi __builtin_ia32_psubusw (v4hi, v4hi) 6920v4hi __builtin_ia32_pmullw (v4hi, v4hi) 6921v4hi __builtin_ia32_pmulhw (v4hi, v4hi) 6922di __builtin_ia32_pand (di, di) 6923di __builtin_ia32_pandn (di,di) 6924di __builtin_ia32_por (di, di) 6925di __builtin_ia32_pxor (di, di) 6926v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) 6927v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) 6928v2si __builtin_ia32_pcmpeqd (v2si, v2si) 6929v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) 6930v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) 6931v2si __builtin_ia32_pcmpgtd (v2si, v2si) 6932v8qi __builtin_ia32_punpckhbw (v8qi, v8qi) 6933v4hi __builtin_ia32_punpckhwd (v4hi, v4hi) 6934v2si __builtin_ia32_punpckhdq (v2si, v2si) 6935v8qi __builtin_ia32_punpcklbw (v8qi, v8qi) 6936v4hi __builtin_ia32_punpcklwd (v4hi, v4hi) 6937v2si __builtin_ia32_punpckldq (v2si, v2si) 6938v8qi __builtin_ia32_packsswb (v4hi, v4hi) 6939v4hi __builtin_ia32_packssdw (v2si, v2si) 6940v8qi __builtin_ia32_packuswb (v4hi, v4hi) 6941@end smallexample 6942 6943The following built-in functions are made available either with 6944@option{-msse}, or with a combination of @option{-m3dnow} and 6945@option{-march=athlon}. All of them generate the machine 6946instruction that is part of the name. 6947 6948@smallexample 6949v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) 6950v8qi __builtin_ia32_pavgb (v8qi, v8qi) 6951v4hi __builtin_ia32_pavgw (v4hi, v4hi) 6952v4hi __builtin_ia32_psadbw (v8qi, v8qi) 6953v8qi __builtin_ia32_pmaxub (v8qi, v8qi) 6954v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) 6955v8qi __builtin_ia32_pminub (v8qi, v8qi) 6956v4hi __builtin_ia32_pminsw (v4hi, v4hi) 6957int __builtin_ia32_pextrw (v4hi, int) 6958v4hi __builtin_ia32_pinsrw (v4hi, int, int) 6959int __builtin_ia32_pmovmskb (v8qi) 6960void __builtin_ia32_maskmovq (v8qi, v8qi, char *) 6961void __builtin_ia32_movntq (di *, di) 6962void __builtin_ia32_sfence (void) 6963@end smallexample 6964 6965The following built-in functions are available when @option{-msse} is used. 6966All of them generate the machine instruction that is part of the name. 6967 6968@smallexample 6969int __builtin_ia32_comieq (v4sf, v4sf) 6970int __builtin_ia32_comineq (v4sf, v4sf) 6971int __builtin_ia32_comilt (v4sf, v4sf) 6972int __builtin_ia32_comile (v4sf, v4sf) 6973int __builtin_ia32_comigt (v4sf, v4sf) 6974int __builtin_ia32_comige (v4sf, v4sf) 6975int __builtin_ia32_ucomieq (v4sf, v4sf) 6976int __builtin_ia32_ucomineq (v4sf, v4sf) 6977int __builtin_ia32_ucomilt (v4sf, v4sf) 6978int __builtin_ia32_ucomile (v4sf, v4sf) 6979int __builtin_ia32_ucomigt (v4sf, v4sf) 6980int __builtin_ia32_ucomige (v4sf, v4sf) 6981v4sf __builtin_ia32_addps (v4sf, v4sf) 6982v4sf __builtin_ia32_subps (v4sf, v4sf) 6983v4sf __builtin_ia32_mulps (v4sf, v4sf) 6984v4sf __builtin_ia32_divps (v4sf, v4sf) 6985v4sf __builtin_ia32_addss (v4sf, v4sf) 6986v4sf __builtin_ia32_subss (v4sf, v4sf) 6987v4sf __builtin_ia32_mulss (v4sf, v4sf) 6988v4sf __builtin_ia32_divss (v4sf, v4sf) 6989v4si __builtin_ia32_cmpeqps (v4sf, v4sf) 6990v4si __builtin_ia32_cmpltps (v4sf, v4sf) 6991v4si __builtin_ia32_cmpleps (v4sf, v4sf) 6992v4si __builtin_ia32_cmpgtps (v4sf, v4sf) 6993v4si __builtin_ia32_cmpgeps (v4sf, v4sf) 6994v4si __builtin_ia32_cmpunordps (v4sf, v4sf) 6995v4si __builtin_ia32_cmpneqps (v4sf, v4sf) 6996v4si __builtin_ia32_cmpnltps (v4sf, v4sf) 6997v4si __builtin_ia32_cmpnleps (v4sf, v4sf) 6998v4si __builtin_ia32_cmpngtps (v4sf, v4sf) 6999v4si __builtin_ia32_cmpngeps (v4sf, v4sf) 7000v4si __builtin_ia32_cmpordps (v4sf, v4sf) 7001v4si __builtin_ia32_cmpeqss (v4sf, v4sf) 7002v4si __builtin_ia32_cmpltss (v4sf, v4sf) 7003v4si __builtin_ia32_cmpless (v4sf, v4sf) 7004v4si __builtin_ia32_cmpunordss (v4sf, v4sf) 7005v4si __builtin_ia32_cmpneqss (v4sf, v4sf) 7006v4si __builtin_ia32_cmpnlts (v4sf, v4sf) 7007v4si __builtin_ia32_cmpnless (v4sf, v4sf) 7008v4si __builtin_ia32_cmpordss (v4sf, v4sf) 7009v4sf __builtin_ia32_maxps (v4sf, v4sf) 7010v4sf __builtin_ia32_maxss (v4sf, v4sf) 7011v4sf __builtin_ia32_minps (v4sf, v4sf) 7012v4sf __builtin_ia32_minss (v4sf, v4sf) 7013v4sf __builtin_ia32_andps (v4sf, v4sf) 7014v4sf __builtin_ia32_andnps (v4sf, v4sf) 7015v4sf __builtin_ia32_orps (v4sf, v4sf) 7016v4sf __builtin_ia32_xorps (v4sf, v4sf) 7017v4sf __builtin_ia32_movss (v4sf, v4sf) 7018v4sf __builtin_ia32_movhlps (v4sf, v4sf) 7019v4sf __builtin_ia32_movlhps (v4sf, v4sf) 7020v4sf __builtin_ia32_unpckhps (v4sf, v4sf) 7021v4sf __builtin_ia32_unpcklps (v4sf, v4sf) 7022v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) 7023v4sf __builtin_ia32_cvtsi2ss (v4sf, int) 7024v2si __builtin_ia32_cvtps2pi (v4sf) 7025int __builtin_ia32_cvtss2si (v4sf) 7026v2si __builtin_ia32_cvttps2pi (v4sf) 7027int __builtin_ia32_cvttss2si (v4sf) 7028v4sf __builtin_ia32_rcpps (v4sf) 7029v4sf __builtin_ia32_rsqrtps (v4sf) 7030v4sf __builtin_ia32_sqrtps (v4sf) 7031v4sf __builtin_ia32_rcpss (v4sf) 7032v4sf __builtin_ia32_rsqrtss (v4sf) 7033v4sf __builtin_ia32_sqrtss (v4sf) 7034v4sf __builtin_ia32_shufps (v4sf, v4sf, int) 7035void __builtin_ia32_movntps (float *, v4sf) 7036int __builtin_ia32_movmskps (v4sf) 7037@end smallexample 7038 7039The following built-in functions are available when @option{-msse} is used. 7040 7041@table @code 7042@item v4sf __builtin_ia32_loadaps (float *) 7043Generates the @code{movaps} machine instruction as a load from memory. 7044@item void __builtin_ia32_storeaps (float *, v4sf) 7045Generates the @code{movaps} machine instruction as a store to memory. 7046@item v4sf __builtin_ia32_loadups (float *) 7047Generates the @code{movups} machine instruction as a load from memory. 7048@item void __builtin_ia32_storeups (float *, v4sf) 7049Generates the @code{movups} machine instruction as a store to memory. 7050@item v4sf __builtin_ia32_loadsss (float *) 7051Generates the @code{movss} machine instruction as a load from memory. 7052@item void __builtin_ia32_storess (float *, v4sf) 7053Generates the @code{movss} machine instruction as a store to memory. 7054@item v4sf __builtin_ia32_loadhps (v4sf, v2si *) 7055Generates the @code{movhps} machine instruction as a load from memory. 7056@item v4sf __builtin_ia32_loadlps (v4sf, v2si *) 7057Generates the @code{movlps} machine instruction as a load from memory 7058@item void __builtin_ia32_storehps (v4sf, v2si *) 7059Generates the @code{movhps} machine instruction as a store to memory. 7060@item void __builtin_ia32_storelps (v4sf, v2si *) 7061Generates the @code{movlps} machine instruction as a store to memory. 7062@end table 7063 7064The following built-in functions are available when @option{-msse2} is used. 7065All of them generate the machine instruction that is part of the name. 7066 7067@smallexample 7068int __builtin_ia32_comisdeq (v2df, v2df) 7069int __builtin_ia32_comisdlt (v2df, v2df) 7070int __builtin_ia32_comisdle (v2df, v2df) 7071int __builtin_ia32_comisdgt (v2df, v2df) 7072int __builtin_ia32_comisdge (v2df, v2df) 7073int __builtin_ia32_comisdneq (v2df, v2df) 7074int __builtin_ia32_ucomisdeq (v2df, v2df) 7075int __builtin_ia32_ucomisdlt (v2df, v2df) 7076int __builtin_ia32_ucomisdle (v2df, v2df) 7077int __builtin_ia32_ucomisdgt (v2df, v2df) 7078int __builtin_ia32_ucomisdge (v2df, v2df) 7079int __builtin_ia32_ucomisdneq (v2df, v2df) 7080v2df __builtin_ia32_cmpeqpd (v2df, v2df) 7081v2df __builtin_ia32_cmpltpd (v2df, v2df) 7082v2df __builtin_ia32_cmplepd (v2df, v2df) 7083v2df __builtin_ia32_cmpgtpd (v2df, v2df) 7084v2df __builtin_ia32_cmpgepd (v2df, v2df) 7085v2df __builtin_ia32_cmpunordpd (v2df, v2df) 7086v2df __builtin_ia32_cmpneqpd (v2df, v2df) 7087v2df __builtin_ia32_cmpnltpd (v2df, v2df) 7088v2df __builtin_ia32_cmpnlepd (v2df, v2df) 7089v2df __builtin_ia32_cmpngtpd (v2df, v2df) 7090v2df __builtin_ia32_cmpngepd (v2df, v2df) 7091v2df __builtin_ia32_cmpordpd (v2df, v2df) 7092v2df __builtin_ia32_cmpeqsd (v2df, v2df) 7093v2df __builtin_ia32_cmpltsd (v2df, v2df) 7094v2df __builtin_ia32_cmplesd (v2df, v2df) 7095v2df __builtin_ia32_cmpunordsd (v2df, v2df) 7096v2df __builtin_ia32_cmpneqsd (v2df, v2df) 7097v2df __builtin_ia32_cmpnltsd (v2df, v2df) 7098v2df __builtin_ia32_cmpnlesd (v2df, v2df) 7099v2df __builtin_ia32_cmpordsd (v2df, v2df) 7100v2di __builtin_ia32_paddq (v2di, v2di) 7101v2di __builtin_ia32_psubq (v2di, v2di) 7102v2df __builtin_ia32_addpd (v2df, v2df) 7103v2df __builtin_ia32_subpd (v2df, v2df) 7104v2df __builtin_ia32_mulpd (v2df, v2df) 7105v2df __builtin_ia32_divpd (v2df, v2df) 7106v2df __builtin_ia32_addsd (v2df, v2df) 7107v2df __builtin_ia32_subsd (v2df, v2df) 7108v2df __builtin_ia32_mulsd (v2df, v2df) 7109v2df __builtin_ia32_divsd (v2df, v2df) 7110v2df __builtin_ia32_minpd (v2df, v2df) 7111v2df __builtin_ia32_maxpd (v2df, v2df) 7112v2df __builtin_ia32_minsd (v2df, v2df) 7113v2df __builtin_ia32_maxsd (v2df, v2df) 7114v2df __builtin_ia32_andpd (v2df, v2df) 7115v2df __builtin_ia32_andnpd (v2df, v2df) 7116v2df __builtin_ia32_orpd (v2df, v2df) 7117v2df __builtin_ia32_xorpd (v2df, v2df) 7118v2df __builtin_ia32_movsd (v2df, v2df) 7119v2df __builtin_ia32_unpckhpd (v2df, v2df) 7120v2df __builtin_ia32_unpcklpd (v2df, v2df) 7121v16qi __builtin_ia32_paddb128 (v16qi, v16qi) 7122v8hi __builtin_ia32_paddw128 (v8hi, v8hi) 7123v4si __builtin_ia32_paddd128 (v4si, v4si) 7124v2di __builtin_ia32_paddq128 (v2di, v2di) 7125v16qi __builtin_ia32_psubb128 (v16qi, v16qi) 7126v8hi __builtin_ia32_psubw128 (v8hi, v8hi) 7127v4si __builtin_ia32_psubd128 (v4si, v4si) 7128v2di __builtin_ia32_psubq128 (v2di, v2di) 7129v8hi __builtin_ia32_pmullw128 (v8hi, v8hi) 7130v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi) 7131v2di __builtin_ia32_pand128 (v2di, v2di) 7132v2di __builtin_ia32_pandn128 (v2di, v2di) 7133v2di __builtin_ia32_por128 (v2di, v2di) 7134v2di __builtin_ia32_pxor128 (v2di, v2di) 7135v16qi __builtin_ia32_pavgb128 (v16qi, v16qi) 7136v8hi __builtin_ia32_pavgw128 (v8hi, v8hi) 7137v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi) 7138v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi) 7139v4si __builtin_ia32_pcmpeqd128 (v4si, v4si) 7140v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi) 7141v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi) 7142v4si __builtin_ia32_pcmpgtd128 (v4si, v4si) 7143v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi) 7144v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi) 7145v16qi __builtin_ia32_pminub128 (v16qi, v16qi) 7146v8hi __builtin_ia32_pminsw128 (v8hi, v8hi) 7147v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi) 7148v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi) 7149v4si __builtin_ia32_punpckhdq128 (v4si, v4si) 7150v2di __builtin_ia32_punpckhqdq128 (v2di, v2di) 7151v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi) 7152v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi) 7153v4si __builtin_ia32_punpckldq128 (v4si, v4si) 7154v2di __builtin_ia32_punpcklqdq128 (v2di, v2di) 7155v16qi __builtin_ia32_packsswb128 (v16qi, v16qi) 7156v8hi __builtin_ia32_packssdw128 (v8hi, v8hi) 7157v16qi __builtin_ia32_packuswb128 (v16qi, v16qi) 7158v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi) 7159void __builtin_ia32_maskmovdqu (v16qi, v16qi) 7160v2df __builtin_ia32_loadupd (double *) 7161void __builtin_ia32_storeupd (double *, v2df) 7162v2df __builtin_ia32_loadhpd (v2df, double *) 7163v2df __builtin_ia32_loadlpd (v2df, double *) 7164int __builtin_ia32_movmskpd (v2df) 7165int __builtin_ia32_pmovmskb128 (v16qi) 7166void __builtin_ia32_movnti (int *, int) 7167void __builtin_ia32_movntpd (double *, v2df) 7168void __builtin_ia32_movntdq (v2df *, v2df) 7169v4si __builtin_ia32_pshufd (v4si, int) 7170v8hi __builtin_ia32_pshuflw (v8hi, int) 7171v8hi __builtin_ia32_pshufhw (v8hi, int) 7172v2di __builtin_ia32_psadbw128 (v16qi, v16qi) 7173v2df __builtin_ia32_sqrtpd (v2df) 7174v2df __builtin_ia32_sqrtsd (v2df) 7175v2df __builtin_ia32_shufpd (v2df, v2df, int) 7176v2df __builtin_ia32_cvtdq2pd (v4si) 7177v4sf __builtin_ia32_cvtdq2ps (v4si) 7178v4si __builtin_ia32_cvtpd2dq (v2df) 7179v2si __builtin_ia32_cvtpd2pi (v2df) 7180v4sf __builtin_ia32_cvtpd2ps (v2df) 7181v4si __builtin_ia32_cvttpd2dq (v2df) 7182v2si __builtin_ia32_cvttpd2pi (v2df) 7183v2df __builtin_ia32_cvtpi2pd (v2si) 7184int __builtin_ia32_cvtsd2si (v2df) 7185int __builtin_ia32_cvttsd2si (v2df) 7186long long __builtin_ia32_cvtsd2si64 (v2df) 7187long long __builtin_ia32_cvttsd2si64 (v2df) 7188v4si __builtin_ia32_cvtps2dq (v4sf) 7189v2df __builtin_ia32_cvtps2pd (v4sf) 7190v4si __builtin_ia32_cvttps2dq (v4sf) 7191v2df __builtin_ia32_cvtsi2sd (v2df, int) 7192v2df __builtin_ia32_cvtsi642sd (v2df, long long) 7193v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df) 7194v2df __builtin_ia32_cvtss2sd (v2df, v4sf) 7195void __builtin_ia32_clflush (const void *) 7196void __builtin_ia32_lfence (void) 7197void __builtin_ia32_mfence (void) 7198v16qi __builtin_ia32_loaddqu (const char *) 7199void __builtin_ia32_storedqu (char *, v16qi) 7200unsigned long long __builtin_ia32_pmuludq (v2si, v2si) 7201v2di __builtin_ia32_pmuludq128 (v4si, v4si) 7202v8hi __builtin_ia32_psllw128 (v8hi, v2di) 7203v4si __builtin_ia32_pslld128 (v4si, v2di) 7204v2di __builtin_ia32_psllq128 (v4si, v2di) 7205v8hi __builtin_ia32_psrlw128 (v8hi, v2di) 7206v4si __builtin_ia32_psrld128 (v4si, v2di) 7207v2di __builtin_ia32_psrlq128 (v2di, v2di) 7208v8hi __builtin_ia32_psraw128 (v8hi, v2di) 7209v4si __builtin_ia32_psrad128 (v4si, v2di) 7210v2di __builtin_ia32_pslldqi128 (v2di, int) 7211v8hi __builtin_ia32_psllwi128 (v8hi, int) 7212v4si __builtin_ia32_pslldi128 (v4si, int) 7213v2di __builtin_ia32_psllqi128 (v2di, int) 7214v2di __builtin_ia32_psrldqi128 (v2di, int) 7215v8hi __builtin_ia32_psrlwi128 (v8hi, int) 7216v4si __builtin_ia32_psrldi128 (v4si, int) 7217v2di __builtin_ia32_psrlqi128 (v2di, int) 7218v8hi __builtin_ia32_psrawi128 (v8hi, int) 7219v4si __builtin_ia32_psradi128 (v4si, int) 7220v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi) 7221@end smallexample 7222 7223The following built-in functions are available when @option{-msse3} is used. 7224All of them generate the machine instruction that is part of the name. 7225 7226@smallexample 7227v2df __builtin_ia32_addsubpd (v2df, v2df) 7228v4sf __builtin_ia32_addsubps (v4sf, v4sf) 7229v2df __builtin_ia32_haddpd (v2df, v2df) 7230v4sf __builtin_ia32_haddps (v4sf, v4sf) 7231v2df __builtin_ia32_hsubpd (v2df, v2df) 7232v4sf __builtin_ia32_hsubps (v4sf, v4sf) 7233v16qi __builtin_ia32_lddqu (char const *) 7234void __builtin_ia32_monitor (void *, unsigned int, unsigned int) 7235v2df __builtin_ia32_movddup (v2df) 7236v4sf __builtin_ia32_movshdup (v4sf) 7237v4sf __builtin_ia32_movsldup (v4sf) 7238void __builtin_ia32_mwait (unsigned int, unsigned int) 7239@end smallexample 7240 7241The following built-in functions are available when @option{-msse3} is used. 7242 7243@table @code 7244@item v2df __builtin_ia32_loadddup (double const *) 7245Generates the @code{movddup} machine instruction as a load from memory. 7246@end table 7247 7248The following built-in functions are available when @option{-mssse3} is used. 7249All of them generate the machine instruction that is part of the name 7250with MMX registers. 7251 7252@smallexample 7253v2si __builtin_ia32_phaddd (v2si, v2si) 7254v4hi __builtin_ia32_phaddw (v4hi, v4hi) 7255v4hi __builtin_ia32_phaddsw (v4hi, v4hi) 7256v2si __builtin_ia32_phsubd (v2si, v2si) 7257v4hi __builtin_ia32_phsubw (v4hi, v4hi) 7258v4hi __builtin_ia32_phsubsw (v4hi, v4hi) 7259v8qi __builtin_ia32_pmaddubsw (v8qi, v8qi) 7260v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi) 7261v8qi __builtin_ia32_pshufb (v8qi, v8qi) 7262v8qi __builtin_ia32_psignb (v8qi, v8qi) 7263v2si __builtin_ia32_psignd (v2si, v2si) 7264v4hi __builtin_ia32_psignw (v4hi, v4hi) 7265long long __builtin_ia32_palignr (long long, long long, int) 7266v8qi __builtin_ia32_pabsb (v8qi) 7267v2si __builtin_ia32_pabsd (v2si) 7268v4hi __builtin_ia32_pabsw (v4hi) 7269@end smallexample 7270 7271The following built-in functions are available when @option{-mssse3} is used. 7272All of them generate the machine instruction that is part of the name 7273with SSE registers. 7274 7275@smallexample 7276v4si __builtin_ia32_phaddd128 (v4si, v4si) 7277v8hi __builtin_ia32_phaddw128 (v8hi, v8hi) 7278v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi) 7279v4si __builtin_ia32_phsubd128 (v4si, v4si) 7280v8hi __builtin_ia32_phsubw128 (v8hi, v8hi) 7281v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi) 7282v16qi __builtin_ia32_pmaddubsw128 (v16qi, v16qi) 7283v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi) 7284v16qi __builtin_ia32_pshufb128 (v16qi, v16qi) 7285v16qi __builtin_ia32_psignb128 (v16qi, v16qi) 7286v4si __builtin_ia32_psignd128 (v4si, v4si) 7287v8hi __builtin_ia32_psignw128 (v8hi, v8hi) 7288v2di __builtin_ia32_palignr (v2di, v2di, int) 7289v16qi __builtin_ia32_pabsb128 (v16qi) 7290v4si __builtin_ia32_pabsd128 (v4si) 7291v8hi __builtin_ia32_pabsw128 (v8hi) 7292@end smallexample 7293 7294The following built-in functions are available when @option{-msse4a} is used. 7295 7296@smallexample 7297void _mm_stream_sd (double*,__m128d); 7298Generates the @code{movntsd} machine instruction. 7299void _mm_stream_ss (float*,__m128); 7300Generates the @code{movntss} machine instruction. 7301__m128i _mm_extract_si64 (__m128i, __m128i); 7302Generates the @code{extrq} machine instruction with only SSE register operands. 7303__m128i _mm_extracti_si64 (__m128i, int, int); 7304Generates the @code{extrq} machine instruction with SSE register and immediate operands. 7305__m128i _mm_insert_si64 (__m128i, __m128i); 7306Generates the @code{insertq} machine instruction with only SSE register operands. 7307__m128i _mm_inserti_si64 (__m128i, __m128i, int, int); 7308Generates the @code{insertq} machine instruction with SSE register and immediate operands. 7309@end smallexample 7310 7311The following built-in functions are available when @option{-m3dnow} is used. 7312All of them generate the machine instruction that is part of the name. 7313 7314@smallexample 7315void __builtin_ia32_femms (void) 7316v8qi __builtin_ia32_pavgusb (v8qi, v8qi) 7317v2si __builtin_ia32_pf2id (v2sf) 7318v2sf __builtin_ia32_pfacc (v2sf, v2sf) 7319v2sf __builtin_ia32_pfadd (v2sf, v2sf) 7320v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) 7321v2si __builtin_ia32_pfcmpge (v2sf, v2sf) 7322v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) 7323v2sf __builtin_ia32_pfmax (v2sf, v2sf) 7324v2sf __builtin_ia32_pfmin (v2sf, v2sf) 7325v2sf __builtin_ia32_pfmul (v2sf, v2sf) 7326v2sf __builtin_ia32_pfrcp (v2sf) 7327v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) 7328v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) 7329v2sf __builtin_ia32_pfrsqrt (v2sf) 7330v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf) 7331v2sf __builtin_ia32_pfsub (v2sf, v2sf) 7332v2sf __builtin_ia32_pfsubr (v2sf, v2sf) 7333v2sf __builtin_ia32_pi2fd (v2si) 7334v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) 7335@end smallexample 7336 7337The following built-in functions are available when both @option{-m3dnow} 7338and @option{-march=athlon} are used. All of them generate the machine 7339instruction that is part of the name. 7340 7341@smallexample 7342v2si __builtin_ia32_pf2iw (v2sf) 7343v2sf __builtin_ia32_pfnacc (v2sf, v2sf) 7344v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) 7345v2sf __builtin_ia32_pi2fw (v2si) 7346v2sf __builtin_ia32_pswapdsf (v2sf) 7347v2si __builtin_ia32_pswapdsi (v2si) 7348@end smallexample 7349 7350@node MIPS DSP Built-in Functions 7351@subsection MIPS DSP Built-in Functions 7352 7353The MIPS DSP Application-Specific Extension (ASE) includes new 7354instructions that are designed to improve the performance of DSP and 7355media applications. It provides instructions that operate on packed 73568-bit integer data, Q15 fractional data and Q31 fractional data. 7357 7358GCC supports MIPS DSP operations using both the generic 7359vector extensions (@pxref{Vector Extensions}) and a collection of 7360MIPS-specific built-in functions. Both kinds of support are 7361enabled by the @option{-mdsp} command-line option. 7362 7363At present, GCC only provides support for operations on 32-bit 7364vectors. The vector type associated with 8-bit integer data is 7365usually called @code{v4i8} and the vector type associated with Q15 is 7366usually called @code{v2q15}. They can be defined in C as follows: 7367 7368@smallexample 7369typedef char v4i8 __attribute__ ((vector_size(4))); 7370typedef short v2q15 __attribute__ ((vector_size(4))); 7371@end smallexample 7372 7373@code{v4i8} and @code{v2q15} values are initialized in the same way as 7374aggregates. For example: 7375 7376@smallexample 7377v4i8 a = @{1, 2, 3, 4@}; 7378v4i8 b; 7379b = (v4i8) @{5, 6, 7, 8@}; 7380 7381v2q15 c = @{0x0fcb, 0x3a75@}; 7382v2q15 d; 7383d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; 7384@end smallexample 7385 7386@emph{Note:} The CPU's endianness determines the order in which values 7387are packed. On little-endian targets, the first value is the least 7388significant and the last value is the most significant. The opposite 7389order applies to big-endian targets. For example, the code above will 7390set the lowest byte of @code{a} to @code{1} on little-endian targets 7391and @code{4} on big-endian targets. 7392 7393@emph{Note:} Q15 and Q31 values must be initialized with their integer 7394representation. As shown in this example, the integer representation 7395of a Q15 value can be obtained by multiplying the fractional value by 7396@code{0x1.0p15}. The equivalent for Q31 values is to multiply by 7397@code{0x1.0p31}. 7398 7399The table below lists the @code{v4i8} and @code{v2q15} operations for which 7400hardware support exists. @code{a} and @code{b} are @code{v4i8} values, 7401and @code{c} and @code{d} are @code{v2q15} values. 7402 7403@multitable @columnfractions .50 .50 7404@item C code @tab MIPS instruction 7405@item @code{a + b} @tab @code{addu.qb} 7406@item @code{c + d} @tab @code{addq.ph} 7407@item @code{a - b} @tab @code{subu.qb} 7408@item @code{c - d} @tab @code{subq.ph} 7409@end multitable 7410 7411It is easier to describe the DSP built-in functions if we first define 7412the following types: 7413 7414@smallexample 7415typedef int q31; 7416typedef int i32; 7417typedef long long a64; 7418@end smallexample 7419 7420@code{q31} and @code{i32} are actually the same as @code{int}, but we 7421use @code{q31} to indicate a Q31 fractional value and @code{i32} to 7422indicate a 32-bit integer value. Similarly, @code{a64} is the same as 7423@code{long long}, but we use @code{a64} to indicate values that will 7424be placed in one of the four DSP accumulators (@code{$ac0}, 7425@code{$ac1}, @code{$ac2} or @code{$ac3}). 7426 7427Also, some built-in functions prefer or require immediate numbers as 7428parameters, because the corresponding DSP instructions accept both immediate 7429numbers and register operands, or accept immediate numbers only. The 7430immediate parameters are listed as follows. 7431 7432@smallexample 7433imm0_7: 0 to 7. 7434imm0_15: 0 to 15. 7435imm0_31: 0 to 31. 7436imm0_63: 0 to 63. 7437imm0_255: 0 to 255. 7438imm_n32_31: -32 to 31. 7439imm_n512_511: -512 to 511. 7440@end smallexample 7441 7442The following built-in functions map directly to a particular MIPS DSP 7443instruction. Please refer to the architecture specification 7444for details on what each instruction does. 7445 7446@smallexample 7447v2q15 __builtin_mips_addq_ph (v2q15, v2q15) 7448v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) 7449q31 __builtin_mips_addq_s_w (q31, q31) 7450v4i8 __builtin_mips_addu_qb (v4i8, v4i8) 7451v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) 7452v2q15 __builtin_mips_subq_ph (v2q15, v2q15) 7453v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) 7454q31 __builtin_mips_subq_s_w (q31, q31) 7455v4i8 __builtin_mips_subu_qb (v4i8, v4i8) 7456v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) 7457i32 __builtin_mips_addsc (i32, i32) 7458i32 __builtin_mips_addwc (i32, i32) 7459i32 __builtin_mips_modsub (i32, i32) 7460i32 __builtin_mips_raddu_w_qb (v4i8) 7461v2q15 __builtin_mips_absq_s_ph (v2q15) 7462q31 __builtin_mips_absq_s_w (q31) 7463v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) 7464v2q15 __builtin_mips_precrq_ph_w (q31, q31) 7465v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) 7466v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) 7467q31 __builtin_mips_preceq_w_phl (v2q15) 7468q31 __builtin_mips_preceq_w_phr (v2q15) 7469v2q15 __builtin_mips_precequ_ph_qbl (v4i8) 7470v2q15 __builtin_mips_precequ_ph_qbr (v4i8) 7471v2q15 __builtin_mips_precequ_ph_qbla (v4i8) 7472v2q15 __builtin_mips_precequ_ph_qbra (v4i8) 7473v2q15 __builtin_mips_preceu_ph_qbl (v4i8) 7474v2q15 __builtin_mips_preceu_ph_qbr (v4i8) 7475v2q15 __builtin_mips_preceu_ph_qbla (v4i8) 7476v2q15 __builtin_mips_preceu_ph_qbra (v4i8) 7477v4i8 __builtin_mips_shll_qb (v4i8, imm0_7) 7478v4i8 __builtin_mips_shll_qb (v4i8, i32) 7479v2q15 __builtin_mips_shll_ph (v2q15, imm0_15) 7480v2q15 __builtin_mips_shll_ph (v2q15, i32) 7481v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) 7482v2q15 __builtin_mips_shll_s_ph (v2q15, i32) 7483q31 __builtin_mips_shll_s_w (q31, imm0_31) 7484q31 __builtin_mips_shll_s_w (q31, i32) 7485v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) 7486v4i8 __builtin_mips_shrl_qb (v4i8, i32) 7487v2q15 __builtin_mips_shra_ph (v2q15, imm0_15) 7488v2q15 __builtin_mips_shra_ph (v2q15, i32) 7489v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) 7490v2q15 __builtin_mips_shra_r_ph (v2q15, i32) 7491q31 __builtin_mips_shra_r_w (q31, imm0_31) 7492q31 __builtin_mips_shra_r_w (q31, i32) 7493v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) 7494v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) 7495v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) 7496q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) 7497q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) 7498a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) 7499a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) 7500a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) 7501a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) 7502a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) 7503a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) 7504a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) 7505a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) 7506a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) 7507a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) 7508a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) 7509a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) 7510a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) 7511i32 __builtin_mips_bitrev (i32) 7512i32 __builtin_mips_insv (i32, i32) 7513v4i8 __builtin_mips_repl_qb (imm0_255) 7514v4i8 __builtin_mips_repl_qb (i32) 7515v2q15 __builtin_mips_repl_ph (imm_n512_511) 7516v2q15 __builtin_mips_repl_ph (i32) 7517void __builtin_mips_cmpu_eq_qb (v4i8, v4i8) 7518void __builtin_mips_cmpu_lt_qb (v4i8, v4i8) 7519void __builtin_mips_cmpu_le_qb (v4i8, v4i8) 7520i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) 7521i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) 7522i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) 7523void __builtin_mips_cmp_eq_ph (v2q15, v2q15) 7524void __builtin_mips_cmp_lt_ph (v2q15, v2q15) 7525void __builtin_mips_cmp_le_ph (v2q15, v2q15) 7526v4i8 __builtin_mips_pick_qb (v4i8, v4i8) 7527v2q15 __builtin_mips_pick_ph (v2q15, v2q15) 7528v2q15 __builtin_mips_packrl_ph (v2q15, v2q15) 7529i32 __builtin_mips_extr_w (a64, imm0_31) 7530i32 __builtin_mips_extr_w (a64, i32) 7531i32 __builtin_mips_extr_r_w (a64, imm0_31) 7532i32 __builtin_mips_extr_s_h (a64, i32) 7533i32 __builtin_mips_extr_rs_w (a64, imm0_31) 7534i32 __builtin_mips_extr_rs_w (a64, i32) 7535i32 __builtin_mips_extr_s_h (a64, imm0_31) 7536i32 __builtin_mips_extr_r_w (a64, i32) 7537i32 __builtin_mips_extp (a64, imm0_31) 7538i32 __builtin_mips_extp (a64, i32) 7539i32 __builtin_mips_extpdp (a64, imm0_31) 7540i32 __builtin_mips_extpdp (a64, i32) 7541a64 __builtin_mips_shilo (a64, imm_n32_31) 7542a64 __builtin_mips_shilo (a64, i32) 7543a64 __builtin_mips_mthlip (a64, i32) 7544void __builtin_mips_wrdsp (i32, imm0_63) 7545i32 __builtin_mips_rddsp (imm0_63) 7546i32 __builtin_mips_lbux (void *, i32) 7547i32 __builtin_mips_lhx (void *, i32) 7548i32 __builtin_mips_lwx (void *, i32) 7549i32 __builtin_mips_bposge32 (void) 7550@end smallexample 7551 7552@node MIPS Paired-Single Support 7553@subsection MIPS Paired-Single Support 7554 7555The MIPS64 architecture includes a number of instructions that 7556operate on pairs of single-precision floating-point values. 7557Each pair is packed into a 64-bit floating-point register, 7558with one element being designated the ``upper half'' and 7559the other being designated the ``lower half''. 7560 7561GCC supports paired-single operations using both the generic 7562vector extensions (@pxref{Vector Extensions}) and a collection of 7563MIPS-specific built-in functions. Both kinds of support are 7564enabled by the @option{-mpaired-single} command-line option. 7565 7566The vector type associated with paired-single values is usually 7567called @code{v2sf}. It can be defined in C as follows: 7568 7569@smallexample 7570typedef float v2sf __attribute__ ((vector_size (8))); 7571@end smallexample 7572 7573@code{v2sf} values are initialized in the same way as aggregates. 7574For example: 7575 7576@smallexample 7577v2sf a = @{1.5, 9.1@}; 7578v2sf b; 7579float e, f; 7580b = (v2sf) @{e, f@}; 7581@end smallexample 7582 7583@emph{Note:} The CPU's endianness determines which value is stored in 7584the upper half of a register and which value is stored in the lower half. 7585On little-endian targets, the first value is the lower one and the second 7586value is the upper one. The opposite order applies to big-endian targets. 7587For example, the code above will set the lower half of @code{a} to 7588@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. 7589 7590@menu 7591* Paired-Single Arithmetic:: 7592* Paired-Single Built-in Functions:: 7593* MIPS-3D Built-in Functions:: 7594@end menu 7595 7596@node Paired-Single Arithmetic 7597@subsubsection Paired-Single Arithmetic 7598 7599The table below lists the @code{v2sf} operations for which hardware 7600support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} 7601values and @code{x} is an integral value. 7602 7603@multitable @columnfractions .50 .50 7604@item C code @tab MIPS instruction 7605@item @code{a + b} @tab @code{add.ps} 7606@item @code{a - b} @tab @code{sub.ps} 7607@item @code{-a} @tab @code{neg.ps} 7608@item @code{a * b} @tab @code{mul.ps} 7609@item @code{a * b + c} @tab @code{madd.ps} 7610@item @code{a * b - c} @tab @code{msub.ps} 7611@item @code{-(a * b + c)} @tab @code{nmadd.ps} 7612@item @code{-(a * b - c)} @tab @code{nmsub.ps} 7613@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} 7614@end multitable 7615 7616Note that the multiply-accumulate instructions can be disabled 7617using the command-line option @code{-mno-fused-madd}. 7618 7619@node Paired-Single Built-in Functions 7620@subsubsection Paired-Single Built-in Functions 7621 7622The following paired-single functions map directly to a particular 7623MIPS instruction. Please refer to the architecture specification 7624for details on what each instruction does. 7625 7626@table @code 7627@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) 7628Pair lower lower (@code{pll.ps}). 7629 7630@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) 7631Pair upper lower (@code{pul.ps}). 7632 7633@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) 7634Pair lower upper (@code{plu.ps}). 7635 7636@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) 7637Pair upper upper (@code{puu.ps}). 7638 7639@item v2sf __builtin_mips_cvt_ps_s (float, float) 7640Convert pair to paired single (@code{cvt.ps.s}). 7641 7642@item float __builtin_mips_cvt_s_pl (v2sf) 7643Convert pair lower to single (@code{cvt.s.pl}). 7644 7645@item float __builtin_mips_cvt_s_pu (v2sf) 7646Convert pair upper to single (@code{cvt.s.pu}). 7647 7648@item v2sf __builtin_mips_abs_ps (v2sf) 7649Absolute value (@code{abs.ps}). 7650 7651@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) 7652Align variable (@code{alnv.ps}). 7653 7654@emph{Note:} The value of the third parameter must be 0 or 4 7655modulo 8, otherwise the result will be unpredictable. Please read the 7656instruction description for details. 7657@end table 7658 7659The following multi-instruction functions are also available. 7660In each case, @var{cond} can be any of the 16 floating-point conditions: 7661@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 7662@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, 7663@code{lt}, @code{nge}, @code{le} or @code{ngt}. 7664 7665@table @code 7666@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7667@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7668Conditional move based on floating point comparison (@code{c.@var{cond}.ps}, 7669@code{movt.ps}/@code{movf.ps}). 7670 7671The @code{movt} functions return the value @var{x} computed by: 7672 7673@smallexample 7674c.@var{cond}.ps @var{cc},@var{a},@var{b} 7675mov.ps @var{x},@var{c} 7676movt.ps @var{x},@var{d},@var{cc} 7677@end smallexample 7678 7679The @code{movf} functions are similar but use @code{movf.ps} instead 7680of @code{movt.ps}. 7681 7682@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7683@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7684Comparison of two paired-single values (@code{c.@var{cond}.ps}, 7685@code{bc1t}/@code{bc1f}). 7686 7687These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 7688and return either the upper or lower half of the result. For example: 7689 7690@smallexample 7691v2sf a, b; 7692if (__builtin_mips_upper_c_eq_ps (a, b)) 7693 upper_halves_are_equal (); 7694else 7695 upper_halves_are_unequal (); 7696 7697if (__builtin_mips_lower_c_eq_ps (a, b)) 7698 lower_halves_are_equal (); 7699else 7700 lower_halves_are_unequal (); 7701@end smallexample 7702@end table 7703 7704@node MIPS-3D Built-in Functions 7705@subsubsection MIPS-3D Built-in Functions 7706 7707The MIPS-3D Application-Specific Extension (ASE) includes additional 7708paired-single instructions that are designed to improve the performance 7709of 3D graphics operations. Support for these instructions is controlled 7710by the @option{-mips3d} command-line option. 7711 7712The functions listed below map directly to a particular MIPS-3D 7713instruction. Please refer to the architecture specification for 7714more details on what each instruction does. 7715 7716@table @code 7717@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) 7718Reduction add (@code{addr.ps}). 7719 7720@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) 7721Reduction multiply (@code{mulr.ps}). 7722 7723@item v2sf __builtin_mips_cvt_pw_ps (v2sf) 7724Convert paired single to paired word (@code{cvt.pw.ps}). 7725 7726@item v2sf __builtin_mips_cvt_ps_pw (v2sf) 7727Convert paired word to paired single (@code{cvt.ps.pw}). 7728 7729@item float __builtin_mips_recip1_s (float) 7730@itemx double __builtin_mips_recip1_d (double) 7731@itemx v2sf __builtin_mips_recip1_ps (v2sf) 7732Reduced precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). 7733 7734@item float __builtin_mips_recip2_s (float, float) 7735@itemx double __builtin_mips_recip2_d (double, double) 7736@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) 7737Reduced precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). 7738 7739@item float __builtin_mips_rsqrt1_s (float) 7740@itemx double __builtin_mips_rsqrt1_d (double) 7741@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) 7742Reduced precision reciprocal square root (sequence step 1) 7743(@code{rsqrt1.@var{fmt}}). 7744 7745@item float __builtin_mips_rsqrt2_s (float, float) 7746@itemx double __builtin_mips_rsqrt2_d (double, double) 7747@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) 7748Reduced precision reciprocal square root (sequence step 2) 7749(@code{rsqrt2.@var{fmt}}). 7750@end table 7751 7752The following multi-instruction functions are also available. 7753In each case, @var{cond} can be any of the 16 floating-point conditions: 7754@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 7755@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 7756@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. 7757 7758@table @code 7759@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) 7760@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) 7761Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, 7762@code{bc1t}/@code{bc1f}). 7763 7764These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} 7765or @code{cabs.@var{cond}.d} and return the result as a boolean value. 7766For example: 7767 7768@smallexample 7769float a, b; 7770if (__builtin_mips_cabs_eq_s (a, b)) 7771 true (); 7772else 7773 false (); 7774@end smallexample 7775 7776@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7777@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7778Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, 7779@code{bc1t}/@code{bc1f}). 7780 7781These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} 7782and return either the upper or lower half of the result. For example: 7783 7784@smallexample 7785v2sf a, b; 7786if (__builtin_mips_upper_cabs_eq_ps (a, b)) 7787 upper_halves_are_equal (); 7788else 7789 upper_halves_are_unequal (); 7790 7791if (__builtin_mips_lower_cabs_eq_ps (a, b)) 7792 lower_halves_are_equal (); 7793else 7794 lower_halves_are_unequal (); 7795@end smallexample 7796 7797@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7798@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7799Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, 7800@code{movt.ps}/@code{movf.ps}). 7801 7802The @code{movt} functions return the value @var{x} computed by: 7803 7804@smallexample 7805cabs.@var{cond}.ps @var{cc},@var{a},@var{b} 7806mov.ps @var{x},@var{c} 7807movt.ps @var{x},@var{d},@var{cc} 7808@end smallexample 7809 7810The @code{movf} functions are similar but use @code{movf.ps} instead 7811of @code{movt.ps}. 7812 7813@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7814@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7815@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7816@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7817Comparison of two paired-single values 7818(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 7819@code{bc1any2t}/@code{bc1any2f}). 7820 7821These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 7822or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either 7823result is true and the @code{all} forms return true if both results are true. 7824For example: 7825 7826@smallexample 7827v2sf a, b; 7828if (__builtin_mips_any_c_eq_ps (a, b)) 7829 one_is_true (); 7830else 7831 both_are_false (); 7832 7833if (__builtin_mips_all_c_eq_ps (a, b)) 7834 both_are_true (); 7835else 7836 one_is_false (); 7837@end smallexample 7838 7839@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7840@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7841@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7842@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7843Comparison of four paired-single values 7844(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 7845@code{bc1any4t}/@code{bc1any4f}). 7846 7847These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} 7848to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. 7849The @code{any} forms return true if any of the four results are true 7850and the @code{all} forms return true if all four results are true. 7851For example: 7852 7853@smallexample 7854v2sf a, b, c, d; 7855if (__builtin_mips_any_c_eq_4s (a, b, c, d)) 7856 some_are_true (); 7857else 7858 all_are_false (); 7859 7860if (__builtin_mips_all_c_eq_4s (a, b, c, d)) 7861 all_are_true (); 7862else 7863 some_are_false (); 7864@end smallexample 7865@end table 7866 7867@node PowerPC AltiVec Built-in Functions 7868@subsection PowerPC AltiVec Built-in Functions 7869 7870GCC provides an interface for the PowerPC family of processors to access 7871the AltiVec operations described in Motorola's AltiVec Programming 7872Interface Manual. The interface is made available by including 7873@code{<altivec.h>} and using @option{-maltivec} and 7874@option{-mabi=altivec}. The interface supports the following vector 7875types. 7876 7877@smallexample 7878vector unsigned char 7879vector signed char 7880vector bool char 7881 7882vector unsigned short 7883vector signed short 7884vector bool short 7885vector pixel 7886 7887vector unsigned int 7888vector signed int 7889vector bool int 7890vector float 7891@end smallexample 7892 7893GCC's implementation of the high-level language interface available from 7894C and C++ code differs from Motorola's documentation in several ways. 7895 7896@itemize @bullet 7897 7898@item 7899A vector constant is a list of constant expressions within curly braces. 7900 7901@item 7902A vector initializer requires no cast if the vector constant is of the 7903same type as the variable it is initializing. 7904 7905@item 7906If @code{signed} or @code{unsigned} is omitted, the signedness of the 7907vector type is the default signedness of the base type. The default 7908varies depending on the operating system, so a portable program should 7909always specify the signedness. 7910 7911@item 7912Compiling with @option{-maltivec} adds keywords @code{__vector}, 7913@code{__pixel}, and @code{__bool}. Macros @option{vector}, 7914@code{pixel}, and @code{bool} are defined in @code{<altivec.h>} and can 7915be undefined. 7916 7917@item 7918GCC allows using a @code{typedef} name as the type specifier for a 7919vector type. 7920 7921@item 7922For C, overloaded functions are implemented with macros so the following 7923does not work: 7924 7925@smallexample 7926 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); 7927@end smallexample 7928 7929Since @code{vec_add} is a macro, the vector constant in the example 7930is treated as four separate arguments. Wrap the entire argument in 7931parentheses for this to work. 7932@end itemize 7933 7934@emph{Note:} Only the @code{<altivec.h>} interface is supported. 7935Internally, GCC uses built-in functions to achieve the functionality in 7936the aforementioned header file, but they are not supported and are 7937subject to change without notice. 7938 7939The following interfaces are supported for the generic and specific 7940AltiVec operations and the AltiVec predicates. In cases where there 7941is a direct mapping between generic and specific operations, only the 7942generic names are shown here, although the specific operations can also 7943be used. 7944 7945Arguments that are documented as @code{const int} require literal 7946integral values within the range required for that operation. 7947 7948@smallexample 7949vector signed char vec_abs (vector signed char); 7950vector signed short vec_abs (vector signed short); 7951vector signed int vec_abs (vector signed int); 7952vector float vec_abs (vector float); 7953 7954vector signed char vec_abss (vector signed char); 7955vector signed short vec_abss (vector signed short); 7956vector signed int vec_abss (vector signed int); 7957 7958vector signed char vec_add (vector bool char, vector signed char); 7959vector signed char vec_add (vector signed char, vector bool char); 7960vector signed char vec_add (vector signed char, vector signed char); 7961vector unsigned char vec_add (vector bool char, vector unsigned char); 7962vector unsigned char vec_add (vector unsigned char, vector bool char); 7963vector unsigned char vec_add (vector unsigned char, 7964 vector unsigned char); 7965vector signed short vec_add (vector bool short, vector signed short); 7966vector signed short vec_add (vector signed short, vector bool short); 7967vector signed short vec_add (vector signed short, vector signed short); 7968vector unsigned short vec_add (vector bool short, 7969 vector unsigned short); 7970vector unsigned short vec_add (vector unsigned short, 7971 vector bool short); 7972vector unsigned short vec_add (vector unsigned short, 7973 vector unsigned short); 7974vector signed int vec_add (vector bool int, vector signed int); 7975vector signed int vec_add (vector signed int, vector bool int); 7976vector signed int vec_add (vector signed int, vector signed int); 7977vector unsigned int vec_add (vector bool int, vector unsigned int); 7978vector unsigned int vec_add (vector unsigned int, vector bool int); 7979vector unsigned int vec_add (vector unsigned int, vector unsigned int); 7980vector float vec_add (vector float, vector float); 7981 7982vector float vec_vaddfp (vector float, vector float); 7983 7984vector signed int vec_vadduwm (vector bool int, vector signed int); 7985vector signed int vec_vadduwm (vector signed int, vector bool int); 7986vector signed int vec_vadduwm (vector signed int, vector signed int); 7987vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); 7988vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); 7989vector unsigned int vec_vadduwm (vector unsigned int, 7990 vector unsigned int); 7991 7992vector signed short vec_vadduhm (vector bool short, 7993 vector signed short); 7994vector signed short vec_vadduhm (vector signed short, 7995 vector bool short); 7996vector signed short vec_vadduhm (vector signed short, 7997 vector signed short); 7998vector unsigned short vec_vadduhm (vector bool short, 7999 vector unsigned short); 8000vector unsigned short vec_vadduhm (vector unsigned short, 8001 vector bool short); 8002vector unsigned short vec_vadduhm (vector unsigned short, 8003 vector unsigned short); 8004 8005vector signed char vec_vaddubm (vector bool char, vector signed char); 8006vector signed char vec_vaddubm (vector signed char, vector bool char); 8007vector signed char vec_vaddubm (vector signed char, vector signed char); 8008vector unsigned char vec_vaddubm (vector bool char, 8009 vector unsigned char); 8010vector unsigned char vec_vaddubm (vector unsigned char, 8011 vector bool char); 8012vector unsigned char vec_vaddubm (vector unsigned char, 8013 vector unsigned char); 8014 8015vector unsigned int vec_addc (vector unsigned int, vector unsigned int); 8016 8017vector unsigned char vec_adds (vector bool char, vector unsigned char); 8018vector unsigned char vec_adds (vector unsigned char, vector bool char); 8019vector unsigned char vec_adds (vector unsigned char, 8020 vector unsigned char); 8021vector signed char vec_adds (vector bool char, vector signed char); 8022vector signed char vec_adds (vector signed char, vector bool char); 8023vector signed char vec_adds (vector signed char, vector signed char); 8024vector unsigned short vec_adds (vector bool short, 8025 vector unsigned short); 8026vector unsigned short vec_adds (vector unsigned short, 8027 vector bool short); 8028vector unsigned short vec_adds (vector unsigned short, 8029 vector unsigned short); 8030vector signed short vec_adds (vector bool short, vector signed short); 8031vector signed short vec_adds (vector signed short, vector bool short); 8032vector signed short vec_adds (vector signed short, vector signed short); 8033vector unsigned int vec_adds (vector bool int, vector unsigned int); 8034vector unsigned int vec_adds (vector unsigned int, vector bool int); 8035vector unsigned int vec_adds (vector unsigned int, vector unsigned int); 8036vector signed int vec_adds (vector bool int, vector signed int); 8037vector signed int vec_adds (vector signed int, vector bool int); 8038vector signed int vec_adds (vector signed int, vector signed int); 8039 8040vector signed int vec_vaddsws (vector bool int, vector signed int); 8041vector signed int vec_vaddsws (vector signed int, vector bool int); 8042vector signed int vec_vaddsws (vector signed int, vector signed int); 8043 8044vector unsigned int vec_vadduws (vector bool int, vector unsigned int); 8045vector unsigned int vec_vadduws (vector unsigned int, vector bool int); 8046vector unsigned int vec_vadduws (vector unsigned int, 8047 vector unsigned int); 8048 8049vector signed short vec_vaddshs (vector bool short, 8050 vector signed short); 8051vector signed short vec_vaddshs (vector signed short, 8052 vector bool short); 8053vector signed short vec_vaddshs (vector signed short, 8054 vector signed short); 8055 8056vector unsigned short vec_vadduhs (vector bool short, 8057 vector unsigned short); 8058vector unsigned short vec_vadduhs (vector unsigned short, 8059 vector bool short); 8060vector unsigned short vec_vadduhs (vector unsigned short, 8061 vector unsigned short); 8062 8063vector signed char vec_vaddsbs (vector bool char, vector signed char); 8064vector signed char vec_vaddsbs (vector signed char, vector bool char); 8065vector signed char vec_vaddsbs (vector signed char, vector signed char); 8066 8067vector unsigned char vec_vaddubs (vector bool char, 8068 vector unsigned char); 8069vector unsigned char vec_vaddubs (vector unsigned char, 8070 vector bool char); 8071vector unsigned char vec_vaddubs (vector unsigned char, 8072 vector unsigned char); 8073 8074vector float vec_and (vector float, vector float); 8075vector float vec_and (vector float, vector bool int); 8076vector float vec_and (vector bool int, vector float); 8077vector bool int vec_and (vector bool int, vector bool int); 8078vector signed int vec_and (vector bool int, vector signed int); 8079vector signed int vec_and (vector signed int, vector bool int); 8080vector signed int vec_and (vector signed int, vector signed int); 8081vector unsigned int vec_and (vector bool int, vector unsigned int); 8082vector unsigned int vec_and (vector unsigned int, vector bool int); 8083vector unsigned int vec_and (vector unsigned int, vector unsigned int); 8084vector bool short vec_and (vector bool short, vector bool short); 8085vector signed short vec_and (vector bool short, vector signed short); 8086vector signed short vec_and (vector signed short, vector bool short); 8087vector signed short vec_and (vector signed short, vector signed short); 8088vector unsigned short vec_and (vector bool short, 8089 vector unsigned short); 8090vector unsigned short vec_and (vector unsigned short, 8091 vector bool short); 8092vector unsigned short vec_and (vector unsigned short, 8093 vector unsigned short); 8094vector signed char vec_and (vector bool char, vector signed char); 8095vector bool char vec_and (vector bool char, vector bool char); 8096vector signed char vec_and (vector signed char, vector bool char); 8097vector signed char vec_and (vector signed char, vector signed char); 8098vector unsigned char vec_and (vector bool char, vector unsigned char); 8099vector unsigned char vec_and (vector unsigned char, vector bool char); 8100vector unsigned char vec_and (vector unsigned char, 8101 vector unsigned char); 8102 8103vector float vec_andc (vector float, vector float); 8104vector float vec_andc (vector float, vector bool int); 8105vector float vec_andc (vector bool int, vector float); 8106vector bool int vec_andc (vector bool int, vector bool int); 8107vector signed int vec_andc (vector bool int, vector signed int); 8108vector signed int vec_andc (vector signed int, vector bool int); 8109vector signed int vec_andc (vector signed int, vector signed int); 8110vector unsigned int vec_andc (vector bool int, vector unsigned int); 8111vector unsigned int vec_andc (vector unsigned int, vector bool int); 8112vector unsigned int vec_andc (vector unsigned int, vector unsigned int); 8113vector bool short vec_andc (vector bool short, vector bool short); 8114vector signed short vec_andc (vector bool short, vector signed short); 8115vector signed short vec_andc (vector signed short, vector bool short); 8116vector signed short vec_andc (vector signed short, vector signed short); 8117vector unsigned short vec_andc (vector bool short, 8118 vector unsigned short); 8119vector unsigned short vec_andc (vector unsigned short, 8120 vector bool short); 8121vector unsigned short vec_andc (vector unsigned short, 8122 vector unsigned short); 8123vector signed char vec_andc (vector bool char, vector signed char); 8124vector bool char vec_andc (vector bool char, vector bool char); 8125vector signed char vec_andc (vector signed char, vector bool char); 8126vector signed char vec_andc (vector signed char, vector signed char); 8127vector unsigned char vec_andc (vector bool char, vector unsigned char); 8128vector unsigned char vec_andc (vector unsigned char, vector bool char); 8129vector unsigned char vec_andc (vector unsigned char, 8130 vector unsigned char); 8131 8132vector unsigned char vec_avg (vector unsigned char, 8133 vector unsigned char); 8134vector signed char vec_avg (vector signed char, vector signed char); 8135vector unsigned short vec_avg (vector unsigned short, 8136 vector unsigned short); 8137vector signed short vec_avg (vector signed short, vector signed short); 8138vector unsigned int vec_avg (vector unsigned int, vector unsigned int); 8139vector signed int vec_avg (vector signed int, vector signed int); 8140 8141vector signed int vec_vavgsw (vector signed int, vector signed int); 8142 8143vector unsigned int vec_vavguw (vector unsigned int, 8144 vector unsigned int); 8145 8146vector signed short vec_vavgsh (vector signed short, 8147 vector signed short); 8148 8149vector unsigned short vec_vavguh (vector unsigned short, 8150 vector unsigned short); 8151 8152vector signed char vec_vavgsb (vector signed char, vector signed char); 8153 8154vector unsigned char vec_vavgub (vector unsigned char, 8155 vector unsigned char); 8156 8157vector float vec_ceil (vector float); 8158 8159vector signed int vec_cmpb (vector float, vector float); 8160 8161vector bool char vec_cmpeq (vector signed char, vector signed char); 8162vector bool char vec_cmpeq (vector unsigned char, vector unsigned char); 8163vector bool short vec_cmpeq (vector signed short, vector signed short); 8164vector bool short vec_cmpeq (vector unsigned short, 8165 vector unsigned short); 8166vector bool int vec_cmpeq (vector signed int, vector signed int); 8167vector bool int vec_cmpeq (vector unsigned int, vector unsigned int); 8168vector bool int vec_cmpeq (vector float, vector float); 8169 8170vector bool int vec_vcmpeqfp (vector float, vector float); 8171 8172vector bool int vec_vcmpequw (vector signed int, vector signed int); 8173vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); 8174 8175vector bool short vec_vcmpequh (vector signed short, 8176 vector signed short); 8177vector bool short vec_vcmpequh (vector unsigned short, 8178 vector unsigned short); 8179 8180vector bool char vec_vcmpequb (vector signed char, vector signed char); 8181vector bool char vec_vcmpequb (vector unsigned char, 8182 vector unsigned char); 8183 8184vector bool int vec_cmpge (vector float, vector float); 8185 8186vector bool char vec_cmpgt (vector unsigned char, vector unsigned char); 8187vector bool char vec_cmpgt (vector signed char, vector signed char); 8188vector bool short vec_cmpgt (vector unsigned short, 8189 vector unsigned short); 8190vector bool short vec_cmpgt (vector signed short, vector signed short); 8191vector bool int vec_cmpgt (vector unsigned int, vector unsigned int); 8192vector bool int vec_cmpgt (vector signed int, vector signed int); 8193vector bool int vec_cmpgt (vector float, vector float); 8194 8195vector bool int vec_vcmpgtfp (vector float, vector float); 8196 8197vector bool int vec_vcmpgtsw (vector signed int, vector signed int); 8198 8199vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); 8200 8201vector bool short vec_vcmpgtsh (vector signed short, 8202 vector signed short); 8203 8204vector bool short vec_vcmpgtuh (vector unsigned short, 8205 vector unsigned short); 8206 8207vector bool char vec_vcmpgtsb (vector signed char, vector signed char); 8208 8209vector bool char vec_vcmpgtub (vector unsigned char, 8210 vector unsigned char); 8211 8212vector bool int vec_cmple (vector float, vector float); 8213 8214vector bool char vec_cmplt (vector unsigned char, vector unsigned char); 8215vector bool char vec_cmplt (vector signed char, vector signed char); 8216vector bool short vec_cmplt (vector unsigned short, 8217 vector unsigned short); 8218vector bool short vec_cmplt (vector signed short, vector signed short); 8219vector bool int vec_cmplt (vector unsigned int, vector unsigned int); 8220vector bool int vec_cmplt (vector signed int, vector signed int); 8221vector bool int vec_cmplt (vector float, vector float); 8222 8223vector float vec_ctf (vector unsigned int, const int); 8224vector float vec_ctf (vector signed int, const int); 8225 8226vector float vec_vcfsx (vector signed int, const int); 8227 8228vector float vec_vcfux (vector unsigned int, const int); 8229 8230vector signed int vec_cts (vector float, const int); 8231 8232vector unsigned int vec_ctu (vector float, const int); 8233 8234void vec_dss (const int); 8235 8236void vec_dssall (void); 8237 8238void vec_dst (const vector unsigned char *, int, const int); 8239void vec_dst (const vector signed char *, int, const int); 8240void vec_dst (const vector bool char *, int, const int); 8241void vec_dst (const vector unsigned short *, int, const int); 8242void vec_dst (const vector signed short *, int, const int); 8243void vec_dst (const vector bool short *, int, const int); 8244void vec_dst (const vector pixel *, int, const int); 8245void vec_dst (const vector unsigned int *, int, const int); 8246void vec_dst (const vector signed int *, int, const int); 8247void vec_dst (const vector bool int *, int, const int); 8248void vec_dst (const vector float *, int, const int); 8249void vec_dst (const unsigned char *, int, const int); 8250void vec_dst (const signed char *, int, const int); 8251void vec_dst (const unsigned short *, int, const int); 8252void vec_dst (const short *, int, const int); 8253void vec_dst (const unsigned int *, int, const int); 8254void vec_dst (const int *, int, const int); 8255void vec_dst (const unsigned long *, int, const int); 8256void vec_dst (const long *, int, const int); 8257void vec_dst (const float *, int, const int); 8258 8259void vec_dstst (const vector unsigned char *, int, const int); 8260void vec_dstst (const vector signed char *, int, const int); 8261void vec_dstst (const vector bool char *, int, const int); 8262void vec_dstst (const vector unsigned short *, int, const int); 8263void vec_dstst (const vector signed short *, int, const int); 8264void vec_dstst (const vector bool short *, int, const int); 8265void vec_dstst (const vector pixel *, int, const int); 8266void vec_dstst (const vector unsigned int *, int, const int); 8267void vec_dstst (const vector signed int *, int, const int); 8268void vec_dstst (const vector bool int *, int, const int); 8269void vec_dstst (const vector float *, int, const int); 8270void vec_dstst (const unsigned char *, int, const int); 8271void vec_dstst (const signed char *, int, const int); 8272void vec_dstst (const unsigned short *, int, const int); 8273void vec_dstst (const short *, int, const int); 8274void vec_dstst (const unsigned int *, int, const int); 8275void vec_dstst (const int *, int, const int); 8276void vec_dstst (const unsigned long *, int, const int); 8277void vec_dstst (const long *, int, const int); 8278void vec_dstst (const float *, int, const int); 8279 8280void vec_dststt (const vector unsigned char *, int, const int); 8281void vec_dststt (const vector signed char *, int, const int); 8282void vec_dststt (const vector bool char *, int, const int); 8283void vec_dststt (const vector unsigned short *, int, const int); 8284void vec_dststt (const vector signed short *, int, const int); 8285void vec_dststt (const vector bool short *, int, const int); 8286void vec_dststt (const vector pixel *, int, const int); 8287void vec_dststt (const vector unsigned int *, int, const int); 8288void vec_dststt (const vector signed int *, int, const int); 8289void vec_dststt (const vector bool int *, int, const int); 8290void vec_dststt (const vector float *, int, const int); 8291void vec_dststt (const unsigned char *, int, const int); 8292void vec_dststt (const signed char *, int, const int); 8293void vec_dststt (const unsigned short *, int, const int); 8294void vec_dststt (const short *, int, const int); 8295void vec_dststt (const unsigned int *, int, const int); 8296void vec_dststt (const int *, int, const int); 8297void vec_dststt (const unsigned long *, int, const int); 8298void vec_dststt (const long *, int, const int); 8299void vec_dststt (const float *, int, const int); 8300 8301void vec_dstt (const vector unsigned char *, int, const int); 8302void vec_dstt (const vector signed char *, int, const int); 8303void vec_dstt (const vector bool char *, int, const int); 8304void vec_dstt (const vector unsigned short *, int, const int); 8305void vec_dstt (const vector signed short *, int, const int); 8306void vec_dstt (const vector bool short *, int, const int); 8307void vec_dstt (const vector pixel *, int, const int); 8308void vec_dstt (const vector unsigned int *, int, const int); 8309void vec_dstt (const vector signed int *, int, const int); 8310void vec_dstt (const vector bool int *, int, const int); 8311void vec_dstt (const vector float *, int, const int); 8312void vec_dstt (const unsigned char *, int, const int); 8313void vec_dstt (const signed char *, int, const int); 8314void vec_dstt (const unsigned short *, int, const int); 8315void vec_dstt (const short *, int, const int); 8316void vec_dstt (const unsigned int *, int, const int); 8317void vec_dstt (const int *, int, const int); 8318void vec_dstt (const unsigned long *, int, const int); 8319void vec_dstt (const long *, int, const int); 8320void vec_dstt (const float *, int, const int); 8321 8322vector float vec_expte (vector float); 8323 8324vector float vec_floor (vector float); 8325 8326vector float vec_ld (int, const vector float *); 8327vector float vec_ld (int, const float *); 8328vector bool int vec_ld (int, const vector bool int *); 8329vector signed int vec_ld (int, const vector signed int *); 8330vector signed int vec_ld (int, const int *); 8331vector signed int vec_ld (int, const long *); 8332vector unsigned int vec_ld (int, const vector unsigned int *); 8333vector unsigned int vec_ld (int, const unsigned int *); 8334vector unsigned int vec_ld (int, const unsigned long *); 8335vector bool short vec_ld (int, const vector bool short *); 8336vector pixel vec_ld (int, const vector pixel *); 8337vector signed short vec_ld (int, const vector signed short *); 8338vector signed short vec_ld (int, const short *); 8339vector unsigned short vec_ld (int, const vector unsigned short *); 8340vector unsigned short vec_ld (int, const unsigned short *); 8341vector bool char vec_ld (int, const vector bool char *); 8342vector signed char vec_ld (int, const vector signed char *); 8343vector signed char vec_ld (int, const signed char *); 8344vector unsigned char vec_ld (int, const vector unsigned char *); 8345vector unsigned char vec_ld (int, const unsigned char *); 8346 8347vector signed char vec_lde (int, const signed char *); 8348vector unsigned char vec_lde (int, const unsigned char *); 8349vector signed short vec_lde (int, const short *); 8350vector unsigned short vec_lde (int, const unsigned short *); 8351vector float vec_lde (int, const float *); 8352vector signed int vec_lde (int, const int *); 8353vector unsigned int vec_lde (int, const unsigned int *); 8354vector signed int vec_lde (int, const long *); 8355vector unsigned int vec_lde (int, const unsigned long *); 8356 8357vector float vec_lvewx (int, float *); 8358vector signed int vec_lvewx (int, int *); 8359vector unsigned int vec_lvewx (int, unsigned int *); 8360vector signed int vec_lvewx (int, long *); 8361vector unsigned int vec_lvewx (int, unsigned long *); 8362 8363vector signed short vec_lvehx (int, short *); 8364vector unsigned short vec_lvehx (int, unsigned short *); 8365 8366vector signed char vec_lvebx (int, char *); 8367vector unsigned char vec_lvebx (int, unsigned char *); 8368 8369vector float vec_ldl (int, const vector float *); 8370vector float vec_ldl (int, const float *); 8371vector bool int vec_ldl (int, const vector bool int *); 8372vector signed int vec_ldl (int, const vector signed int *); 8373vector signed int vec_ldl (int, const int *); 8374vector signed int vec_ldl (int, const long *); 8375vector unsigned int vec_ldl (int, const vector unsigned int *); 8376vector unsigned int vec_ldl (int, const unsigned int *); 8377vector unsigned int vec_ldl (int, const unsigned long *); 8378vector bool short vec_ldl (int, const vector bool short *); 8379vector pixel vec_ldl (int, const vector pixel *); 8380vector signed short vec_ldl (int, const vector signed short *); 8381vector signed short vec_ldl (int, const short *); 8382vector unsigned short vec_ldl (int, const vector unsigned short *); 8383vector unsigned short vec_ldl (int, const unsigned short *); 8384vector bool char vec_ldl (int, const vector bool char *); 8385vector signed char vec_ldl (int, const vector signed char *); 8386vector signed char vec_ldl (int, const signed char *); 8387vector unsigned char vec_ldl (int, const vector unsigned char *); 8388vector unsigned char vec_ldl (int, const unsigned char *); 8389 8390vector float vec_loge (vector float); 8391 8392vector unsigned char vec_lvsl (int, const volatile unsigned char *); 8393vector unsigned char vec_lvsl (int, const volatile signed char *); 8394vector unsigned char vec_lvsl (int, const volatile unsigned short *); 8395vector unsigned char vec_lvsl (int, const volatile short *); 8396vector unsigned char vec_lvsl (int, const volatile unsigned int *); 8397vector unsigned char vec_lvsl (int, const volatile int *); 8398vector unsigned char vec_lvsl (int, const volatile unsigned long *); 8399vector unsigned char vec_lvsl (int, const volatile long *); 8400vector unsigned char vec_lvsl (int, const volatile float *); 8401 8402vector unsigned char vec_lvsr (int, const volatile unsigned char *); 8403vector unsigned char vec_lvsr (int, const volatile signed char *); 8404vector unsigned char vec_lvsr (int, const volatile unsigned short *); 8405vector unsigned char vec_lvsr (int, const volatile short *); 8406vector unsigned char vec_lvsr (int, const volatile unsigned int *); 8407vector unsigned char vec_lvsr (int, const volatile int *); 8408vector unsigned char vec_lvsr (int, const volatile unsigned long *); 8409vector unsigned char vec_lvsr (int, const volatile long *); 8410vector unsigned char vec_lvsr (int, const volatile float *); 8411 8412vector float vec_madd (vector float, vector float, vector float); 8413 8414vector signed short vec_madds (vector signed short, 8415 vector signed short, 8416 vector signed short); 8417 8418vector unsigned char vec_max (vector bool char, vector unsigned char); 8419vector unsigned char vec_max (vector unsigned char, vector bool char); 8420vector unsigned char vec_max (vector unsigned char, 8421 vector unsigned char); 8422vector signed char vec_max (vector bool char, vector signed char); 8423vector signed char vec_max (vector signed char, vector bool char); 8424vector signed char vec_max (vector signed char, vector signed char); 8425vector unsigned short vec_max (vector bool short, 8426 vector unsigned short); 8427vector unsigned short vec_max (vector unsigned short, 8428 vector bool short); 8429vector unsigned short vec_max (vector unsigned short, 8430 vector unsigned short); 8431vector signed short vec_max (vector bool short, vector signed short); 8432vector signed short vec_max (vector signed short, vector bool short); 8433vector signed short vec_max (vector signed short, vector signed short); 8434vector unsigned int vec_max (vector bool int, vector unsigned int); 8435vector unsigned int vec_max (vector unsigned int, vector bool int); 8436vector unsigned int vec_max (vector unsigned int, vector unsigned int); 8437vector signed int vec_max (vector bool int, vector signed int); 8438vector signed int vec_max (vector signed int, vector bool int); 8439vector signed int vec_max (vector signed int, vector signed int); 8440vector float vec_max (vector float, vector float); 8441 8442vector float vec_vmaxfp (vector float, vector float); 8443 8444vector signed int vec_vmaxsw (vector bool int, vector signed int); 8445vector signed int vec_vmaxsw (vector signed int, vector bool int); 8446vector signed int vec_vmaxsw (vector signed int, vector signed int); 8447 8448vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); 8449vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); 8450vector unsigned int vec_vmaxuw (vector unsigned int, 8451 vector unsigned int); 8452 8453vector signed short vec_vmaxsh (vector bool short, vector signed short); 8454vector signed short vec_vmaxsh (vector signed short, vector bool short); 8455vector signed short vec_vmaxsh (vector signed short, 8456 vector signed short); 8457 8458vector unsigned short vec_vmaxuh (vector bool short, 8459 vector unsigned short); 8460vector unsigned short vec_vmaxuh (vector unsigned short, 8461 vector bool short); 8462vector unsigned short vec_vmaxuh (vector unsigned short, 8463 vector unsigned short); 8464 8465vector signed char vec_vmaxsb (vector bool char, vector signed char); 8466vector signed char vec_vmaxsb (vector signed char, vector bool char); 8467vector signed char vec_vmaxsb (vector signed char, vector signed char); 8468 8469vector unsigned char vec_vmaxub (vector bool char, 8470 vector unsigned char); 8471vector unsigned char vec_vmaxub (vector unsigned char, 8472 vector bool char); 8473vector unsigned char vec_vmaxub (vector unsigned char, 8474 vector unsigned char); 8475 8476vector bool char vec_mergeh (vector bool char, vector bool char); 8477vector signed char vec_mergeh (vector signed char, vector signed char); 8478vector unsigned char vec_mergeh (vector unsigned char, 8479 vector unsigned char); 8480vector bool short vec_mergeh (vector bool short, vector bool short); 8481vector pixel vec_mergeh (vector pixel, vector pixel); 8482vector signed short vec_mergeh (vector signed short, 8483 vector signed short); 8484vector unsigned short vec_mergeh (vector unsigned short, 8485 vector unsigned short); 8486vector float vec_mergeh (vector float, vector float); 8487vector bool int vec_mergeh (vector bool int, vector bool int); 8488vector signed int vec_mergeh (vector signed int, vector signed int); 8489vector unsigned int vec_mergeh (vector unsigned int, 8490 vector unsigned int); 8491 8492vector float vec_vmrghw (vector float, vector float); 8493vector bool int vec_vmrghw (vector bool int, vector bool int); 8494vector signed int vec_vmrghw (vector signed int, vector signed int); 8495vector unsigned int vec_vmrghw (vector unsigned int, 8496 vector unsigned int); 8497 8498vector bool short vec_vmrghh (vector bool short, vector bool short); 8499vector signed short vec_vmrghh (vector signed short, 8500 vector signed short); 8501vector unsigned short vec_vmrghh (vector unsigned short, 8502 vector unsigned short); 8503vector pixel vec_vmrghh (vector pixel, vector pixel); 8504 8505vector bool char vec_vmrghb (vector bool char, vector bool char); 8506vector signed char vec_vmrghb (vector signed char, vector signed char); 8507vector unsigned char vec_vmrghb (vector unsigned char, 8508 vector unsigned char); 8509 8510vector bool char vec_mergel (vector bool char, vector bool char); 8511vector signed char vec_mergel (vector signed char, vector signed char); 8512vector unsigned char vec_mergel (vector unsigned char, 8513 vector unsigned char); 8514vector bool short vec_mergel (vector bool short, vector bool short); 8515vector pixel vec_mergel (vector pixel, vector pixel); 8516vector signed short vec_mergel (vector signed short, 8517 vector signed short); 8518vector unsigned short vec_mergel (vector unsigned short, 8519 vector unsigned short); 8520vector float vec_mergel (vector float, vector float); 8521vector bool int vec_mergel (vector bool int, vector bool int); 8522vector signed int vec_mergel (vector signed int, vector signed int); 8523vector unsigned int vec_mergel (vector unsigned int, 8524 vector unsigned int); 8525 8526vector float vec_vmrglw (vector float, vector float); 8527vector signed int vec_vmrglw (vector signed int, vector signed int); 8528vector unsigned int vec_vmrglw (vector unsigned int, 8529 vector unsigned int); 8530vector bool int vec_vmrglw (vector bool int, vector bool int); 8531 8532vector bool short vec_vmrglh (vector bool short, vector bool short); 8533vector signed short vec_vmrglh (vector signed short, 8534 vector signed short); 8535vector unsigned short vec_vmrglh (vector unsigned short, 8536 vector unsigned short); 8537vector pixel vec_vmrglh (vector pixel, vector pixel); 8538 8539vector bool char vec_vmrglb (vector bool char, vector bool char); 8540vector signed char vec_vmrglb (vector signed char, vector signed char); 8541vector unsigned char vec_vmrglb (vector unsigned char, 8542 vector unsigned char); 8543 8544vector unsigned short vec_mfvscr (void); 8545 8546vector unsigned char vec_min (vector bool char, vector unsigned char); 8547vector unsigned char vec_min (vector unsigned char, vector bool char); 8548vector unsigned char vec_min (vector unsigned char, 8549 vector unsigned char); 8550vector signed char vec_min (vector bool char, vector signed char); 8551vector signed char vec_min (vector signed char, vector bool char); 8552vector signed char vec_min (vector signed char, vector signed char); 8553vector unsigned short vec_min (vector bool short, 8554 vector unsigned short); 8555vector unsigned short vec_min (vector unsigned short, 8556 vector bool short); 8557vector unsigned short vec_min (vector unsigned short, 8558 vector unsigned short); 8559vector signed short vec_min (vector bool short, vector signed short); 8560vector signed short vec_min (vector signed short, vector bool short); 8561vector signed short vec_min (vector signed short, vector signed short); 8562vector unsigned int vec_min (vector bool int, vector unsigned int); 8563vector unsigned int vec_min (vector unsigned int, vector bool int); 8564vector unsigned int vec_min (vector unsigned int, vector unsigned int); 8565vector signed int vec_min (vector bool int, vector signed int); 8566vector signed int vec_min (vector signed int, vector bool int); 8567vector signed int vec_min (vector signed int, vector signed int); 8568vector float vec_min (vector float, vector float); 8569 8570vector float vec_vminfp (vector float, vector float); 8571 8572vector signed int vec_vminsw (vector bool int, vector signed int); 8573vector signed int vec_vminsw (vector signed int, vector bool int); 8574vector signed int vec_vminsw (vector signed int, vector signed int); 8575 8576vector unsigned int vec_vminuw (vector bool int, vector unsigned int); 8577vector unsigned int vec_vminuw (vector unsigned int, vector bool int); 8578vector unsigned int vec_vminuw (vector unsigned int, 8579 vector unsigned int); 8580 8581vector signed short vec_vminsh (vector bool short, vector signed short); 8582vector signed short vec_vminsh (vector signed short, vector bool short); 8583vector signed short vec_vminsh (vector signed short, 8584 vector signed short); 8585 8586vector unsigned short vec_vminuh (vector bool short, 8587 vector unsigned short); 8588vector unsigned short vec_vminuh (vector unsigned short, 8589 vector bool short); 8590vector unsigned short vec_vminuh (vector unsigned short, 8591 vector unsigned short); 8592 8593vector signed char vec_vminsb (vector bool char, vector signed char); 8594vector signed char vec_vminsb (vector signed char, vector bool char); 8595vector signed char vec_vminsb (vector signed char, vector signed char); 8596 8597vector unsigned char vec_vminub (vector bool char, 8598 vector unsigned char); 8599vector unsigned char vec_vminub (vector unsigned char, 8600 vector bool char); 8601vector unsigned char vec_vminub (vector unsigned char, 8602 vector unsigned char); 8603 8604vector signed short vec_mladd (vector signed short, 8605 vector signed short, 8606 vector signed short); 8607vector signed short vec_mladd (vector signed short, 8608 vector unsigned short, 8609 vector unsigned short); 8610vector signed short vec_mladd (vector unsigned short, 8611 vector signed short, 8612 vector signed short); 8613vector unsigned short vec_mladd (vector unsigned short, 8614 vector unsigned short, 8615 vector unsigned short); 8616 8617vector signed short vec_mradds (vector signed short, 8618 vector signed short, 8619 vector signed short); 8620 8621vector unsigned int vec_msum (vector unsigned char, 8622 vector unsigned char, 8623 vector unsigned int); 8624vector signed int vec_msum (vector signed char, 8625 vector unsigned char, 8626 vector signed int); 8627vector unsigned int vec_msum (vector unsigned short, 8628 vector unsigned short, 8629 vector unsigned int); 8630vector signed int vec_msum (vector signed short, 8631 vector signed short, 8632 vector signed int); 8633 8634vector signed int vec_vmsumshm (vector signed short, 8635 vector signed short, 8636 vector signed int); 8637 8638vector unsigned int vec_vmsumuhm (vector unsigned short, 8639 vector unsigned short, 8640 vector unsigned int); 8641 8642vector signed int vec_vmsummbm (vector signed char, 8643 vector unsigned char, 8644 vector signed int); 8645 8646vector unsigned int vec_vmsumubm (vector unsigned char, 8647 vector unsigned char, 8648 vector unsigned int); 8649 8650vector unsigned int vec_msums (vector unsigned short, 8651 vector unsigned short, 8652 vector unsigned int); 8653vector signed int vec_msums (vector signed short, 8654 vector signed short, 8655 vector signed int); 8656 8657vector signed int vec_vmsumshs (vector signed short, 8658 vector signed short, 8659 vector signed int); 8660 8661vector unsigned int vec_vmsumuhs (vector unsigned short, 8662 vector unsigned short, 8663 vector unsigned int); 8664 8665void vec_mtvscr (vector signed int); 8666void vec_mtvscr (vector unsigned int); 8667void vec_mtvscr (vector bool int); 8668void vec_mtvscr (vector signed short); 8669void vec_mtvscr (vector unsigned short); 8670void vec_mtvscr (vector bool short); 8671void vec_mtvscr (vector pixel); 8672void vec_mtvscr (vector signed char); 8673void vec_mtvscr (vector unsigned char); 8674void vec_mtvscr (vector bool char); 8675 8676vector unsigned short vec_mule (vector unsigned char, 8677 vector unsigned char); 8678vector signed short vec_mule (vector signed char, 8679 vector signed char); 8680vector unsigned int vec_mule (vector unsigned short, 8681 vector unsigned short); 8682vector signed int vec_mule (vector signed short, vector signed short); 8683 8684vector signed int vec_vmulesh (vector signed short, 8685 vector signed short); 8686 8687vector unsigned int vec_vmuleuh (vector unsigned short, 8688 vector unsigned short); 8689 8690vector signed short vec_vmulesb (vector signed char, 8691 vector signed char); 8692 8693vector unsigned short vec_vmuleub (vector unsigned char, 8694 vector unsigned char); 8695 8696vector unsigned short vec_mulo (vector unsigned char, 8697 vector unsigned char); 8698vector signed short vec_mulo (vector signed char, vector signed char); 8699vector unsigned int vec_mulo (vector unsigned short, 8700 vector unsigned short); 8701vector signed int vec_mulo (vector signed short, vector signed short); 8702 8703vector signed int vec_vmulosh (vector signed short, 8704 vector signed short); 8705 8706vector unsigned int vec_vmulouh (vector unsigned short, 8707 vector unsigned short); 8708 8709vector signed short vec_vmulosb (vector signed char, 8710 vector signed char); 8711 8712vector unsigned short vec_vmuloub (vector unsigned char, 8713 vector unsigned char); 8714 8715vector float vec_nmsub (vector float, vector float, vector float); 8716 8717vector float vec_nor (vector float, vector float); 8718vector signed int vec_nor (vector signed int, vector signed int); 8719vector unsigned int vec_nor (vector unsigned int, vector unsigned int); 8720vector bool int vec_nor (vector bool int, vector bool int); 8721vector signed short vec_nor (vector signed short, vector signed short); 8722vector unsigned short vec_nor (vector unsigned short, 8723 vector unsigned short); 8724vector bool short vec_nor (vector bool short, vector bool short); 8725vector signed char vec_nor (vector signed char, vector signed char); 8726vector unsigned char vec_nor (vector unsigned char, 8727 vector unsigned char); 8728vector bool char vec_nor (vector bool char, vector bool char); 8729 8730vector float vec_or (vector float, vector float); 8731vector float vec_or (vector float, vector bool int); 8732vector float vec_or (vector bool int, vector float); 8733vector bool int vec_or (vector bool int, vector bool int); 8734vector signed int vec_or (vector bool int, vector signed int); 8735vector signed int vec_or (vector signed int, vector bool int); 8736vector signed int vec_or (vector signed int, vector signed int); 8737vector unsigned int vec_or (vector bool int, vector unsigned int); 8738vector unsigned int vec_or (vector unsigned int, vector bool int); 8739vector unsigned int vec_or (vector unsigned int, vector unsigned int); 8740vector bool short vec_or (vector bool short, vector bool short); 8741vector signed short vec_or (vector bool short, vector signed short); 8742vector signed short vec_or (vector signed short, vector bool short); 8743vector signed short vec_or (vector signed short, vector signed short); 8744vector unsigned short vec_or (vector bool short, vector unsigned short); 8745vector unsigned short vec_or (vector unsigned short, vector bool short); 8746vector unsigned short vec_or (vector unsigned short, 8747 vector unsigned short); 8748vector signed char vec_or (vector bool char, vector signed char); 8749vector bool char vec_or (vector bool char, vector bool char); 8750vector signed char vec_or (vector signed char, vector bool char); 8751vector signed char vec_or (vector signed char, vector signed char); 8752vector unsigned char vec_or (vector bool char, vector unsigned char); 8753vector unsigned char vec_or (vector unsigned char, vector bool char); 8754vector unsigned char vec_or (vector unsigned char, 8755 vector unsigned char); 8756 8757vector signed char vec_pack (vector signed short, vector signed short); 8758vector unsigned char vec_pack (vector unsigned short, 8759 vector unsigned short); 8760vector bool char vec_pack (vector bool short, vector bool short); 8761vector signed short vec_pack (vector signed int, vector signed int); 8762vector unsigned short vec_pack (vector unsigned int, 8763 vector unsigned int); 8764vector bool short vec_pack (vector bool int, vector bool int); 8765 8766vector bool short vec_vpkuwum (vector bool int, vector bool int); 8767vector signed short vec_vpkuwum (vector signed int, vector signed int); 8768vector unsigned short vec_vpkuwum (vector unsigned int, 8769 vector unsigned int); 8770 8771vector bool char vec_vpkuhum (vector bool short, vector bool short); 8772vector signed char vec_vpkuhum (vector signed short, 8773 vector signed short); 8774vector unsigned char vec_vpkuhum (vector unsigned short, 8775 vector unsigned short); 8776 8777vector pixel vec_packpx (vector unsigned int, vector unsigned int); 8778 8779vector unsigned char vec_packs (vector unsigned short, 8780 vector unsigned short); 8781vector signed char vec_packs (vector signed short, vector signed short); 8782vector unsigned short vec_packs (vector unsigned int, 8783 vector unsigned int); 8784vector signed short vec_packs (vector signed int, vector signed int); 8785 8786vector signed short vec_vpkswss (vector signed int, vector signed int); 8787 8788vector unsigned short vec_vpkuwus (vector unsigned int, 8789 vector unsigned int); 8790 8791vector signed char vec_vpkshss (vector signed short, 8792 vector signed short); 8793 8794vector unsigned char vec_vpkuhus (vector unsigned short, 8795 vector unsigned short); 8796 8797vector unsigned char vec_packsu (vector unsigned short, 8798 vector unsigned short); 8799vector unsigned char vec_packsu (vector signed short, 8800 vector signed short); 8801vector unsigned short vec_packsu (vector unsigned int, 8802 vector unsigned int); 8803vector unsigned short vec_packsu (vector signed int, vector signed int); 8804 8805vector unsigned short vec_vpkswus (vector signed int, 8806 vector signed int); 8807 8808vector unsigned char vec_vpkshus (vector signed short, 8809 vector signed short); 8810 8811vector float vec_perm (vector float, 8812 vector float, 8813 vector unsigned char); 8814vector signed int vec_perm (vector signed int, 8815 vector signed int, 8816 vector unsigned char); 8817vector unsigned int vec_perm (vector unsigned int, 8818 vector unsigned int, 8819 vector unsigned char); 8820vector bool int vec_perm (vector bool int, 8821 vector bool int, 8822 vector unsigned char); 8823vector signed short vec_perm (vector signed short, 8824 vector signed short, 8825 vector unsigned char); 8826vector unsigned short vec_perm (vector unsigned short, 8827 vector unsigned short, 8828 vector unsigned char); 8829vector bool short vec_perm (vector bool short, 8830 vector bool short, 8831 vector unsigned char); 8832vector pixel vec_perm (vector pixel, 8833 vector pixel, 8834 vector unsigned char); 8835vector signed char vec_perm (vector signed char, 8836 vector signed char, 8837 vector unsigned char); 8838vector unsigned char vec_perm (vector unsigned char, 8839 vector unsigned char, 8840 vector unsigned char); 8841vector bool char vec_perm (vector bool char, 8842 vector bool char, 8843 vector unsigned char); 8844 8845vector float vec_re (vector float); 8846 8847vector signed char vec_rl (vector signed char, 8848 vector unsigned char); 8849vector unsigned char vec_rl (vector unsigned char, 8850 vector unsigned char); 8851vector signed short vec_rl (vector signed short, vector unsigned short); 8852vector unsigned short vec_rl (vector unsigned short, 8853 vector unsigned short); 8854vector signed int vec_rl (vector signed int, vector unsigned int); 8855vector unsigned int vec_rl (vector unsigned int, vector unsigned int); 8856 8857vector signed int vec_vrlw (vector signed int, vector unsigned int); 8858vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); 8859 8860vector signed short vec_vrlh (vector signed short, 8861 vector unsigned short); 8862vector unsigned short vec_vrlh (vector unsigned short, 8863 vector unsigned short); 8864 8865vector signed char vec_vrlb (vector signed char, vector unsigned char); 8866vector unsigned char vec_vrlb (vector unsigned char, 8867 vector unsigned char); 8868 8869vector float vec_round (vector float); 8870 8871vector float vec_rsqrte (vector float); 8872 8873vector float vec_sel (vector float, vector float, vector bool int); 8874vector float vec_sel (vector float, vector float, vector unsigned int); 8875vector signed int vec_sel (vector signed int, 8876 vector signed int, 8877 vector bool int); 8878vector signed int vec_sel (vector signed int, 8879 vector signed int, 8880 vector unsigned int); 8881vector unsigned int vec_sel (vector unsigned int, 8882 vector unsigned int, 8883 vector bool int); 8884vector unsigned int vec_sel (vector unsigned int, 8885 vector unsigned int, 8886 vector unsigned int); 8887vector bool int vec_sel (vector bool int, 8888 vector bool int, 8889 vector bool int); 8890vector bool int vec_sel (vector bool int, 8891 vector bool int, 8892 vector unsigned int); 8893vector signed short vec_sel (vector signed short, 8894 vector signed short, 8895 vector bool short); 8896vector signed short vec_sel (vector signed short, 8897 vector signed short, 8898 vector unsigned short); 8899vector unsigned short vec_sel (vector unsigned short, 8900 vector unsigned short, 8901 vector bool short); 8902vector unsigned short vec_sel (vector unsigned short, 8903 vector unsigned short, 8904 vector unsigned short); 8905vector bool short vec_sel (vector bool short, 8906 vector bool short, 8907 vector bool short); 8908vector bool short vec_sel (vector bool short, 8909 vector bool short, 8910 vector unsigned short); 8911vector signed char vec_sel (vector signed char, 8912 vector signed char, 8913 vector bool char); 8914vector signed char vec_sel (vector signed char, 8915 vector signed char, 8916 vector unsigned char); 8917vector unsigned char vec_sel (vector unsigned char, 8918 vector unsigned char, 8919 vector bool char); 8920vector unsigned char vec_sel (vector unsigned char, 8921 vector unsigned char, 8922 vector unsigned char); 8923vector bool char vec_sel (vector bool char, 8924 vector bool char, 8925 vector bool char); 8926vector bool char vec_sel (vector bool char, 8927 vector bool char, 8928 vector unsigned char); 8929 8930vector signed char vec_sl (vector signed char, 8931 vector unsigned char); 8932vector unsigned char vec_sl (vector unsigned char, 8933 vector unsigned char); 8934vector signed short vec_sl (vector signed short, vector unsigned short); 8935vector unsigned short vec_sl (vector unsigned short, 8936 vector unsigned short); 8937vector signed int vec_sl (vector signed int, vector unsigned int); 8938vector unsigned int vec_sl (vector unsigned int, vector unsigned int); 8939 8940vector signed int vec_vslw (vector signed int, vector unsigned int); 8941vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); 8942 8943vector signed short vec_vslh (vector signed short, 8944 vector unsigned short); 8945vector unsigned short vec_vslh (vector unsigned short, 8946 vector unsigned short); 8947 8948vector signed char vec_vslb (vector signed char, vector unsigned char); 8949vector unsigned char vec_vslb (vector unsigned char, 8950 vector unsigned char); 8951 8952vector float vec_sld (vector float, vector float, const int); 8953vector signed int vec_sld (vector signed int, 8954 vector signed int, 8955 const int); 8956vector unsigned int vec_sld (vector unsigned int, 8957 vector unsigned int, 8958 const int); 8959vector bool int vec_sld (vector bool int, 8960 vector bool int, 8961 const int); 8962vector signed short vec_sld (vector signed short, 8963 vector signed short, 8964 const int); 8965vector unsigned short vec_sld (vector unsigned short, 8966 vector unsigned short, 8967 const int); 8968vector bool short vec_sld (vector bool short, 8969 vector bool short, 8970 const int); 8971vector pixel vec_sld (vector pixel, 8972 vector pixel, 8973 const int); 8974vector signed char vec_sld (vector signed char, 8975 vector signed char, 8976 const int); 8977vector unsigned char vec_sld (vector unsigned char, 8978 vector unsigned char, 8979 const int); 8980vector bool char vec_sld (vector bool char, 8981 vector bool char, 8982 const int); 8983 8984vector signed int vec_sll (vector signed int, 8985 vector unsigned int); 8986vector signed int vec_sll (vector signed int, 8987 vector unsigned short); 8988vector signed int vec_sll (vector signed int, 8989 vector unsigned char); 8990vector unsigned int vec_sll (vector unsigned int, 8991 vector unsigned int); 8992vector unsigned int vec_sll (vector unsigned int, 8993 vector unsigned short); 8994vector unsigned int vec_sll (vector unsigned int, 8995 vector unsigned char); 8996vector bool int vec_sll (vector bool int, 8997 vector unsigned int); 8998vector bool int vec_sll (vector bool int, 8999 vector unsigned short); 9000vector bool int vec_sll (vector bool int, 9001 vector unsigned char); 9002vector signed short vec_sll (vector signed short, 9003 vector unsigned int); 9004vector signed short vec_sll (vector signed short, 9005 vector unsigned short); 9006vector signed short vec_sll (vector signed short, 9007 vector unsigned char); 9008vector unsigned short vec_sll (vector unsigned short, 9009 vector unsigned int); 9010vector unsigned short vec_sll (vector unsigned short, 9011 vector unsigned short); 9012vector unsigned short vec_sll (vector unsigned short, 9013 vector unsigned char); 9014vector bool short vec_sll (vector bool short, vector unsigned int); 9015vector bool short vec_sll (vector bool short, vector unsigned short); 9016vector bool short vec_sll (vector bool short, vector unsigned char); 9017vector pixel vec_sll (vector pixel, vector unsigned int); 9018vector pixel vec_sll (vector pixel, vector unsigned short); 9019vector pixel vec_sll (vector pixel, vector unsigned char); 9020vector signed char vec_sll (vector signed char, vector unsigned int); 9021vector signed char vec_sll (vector signed char, vector unsigned short); 9022vector signed char vec_sll (vector signed char, vector unsigned char); 9023vector unsigned char vec_sll (vector unsigned char, 9024 vector unsigned int); 9025vector unsigned char vec_sll (vector unsigned char, 9026 vector unsigned short); 9027vector unsigned char vec_sll (vector unsigned char, 9028 vector unsigned char); 9029vector bool char vec_sll (vector bool char, vector unsigned int); 9030vector bool char vec_sll (vector bool char, vector unsigned short); 9031vector bool char vec_sll (vector bool char, vector unsigned char); 9032 9033vector float vec_slo (vector float, vector signed char); 9034vector float vec_slo (vector float, vector unsigned char); 9035vector signed int vec_slo (vector signed int, vector signed char); 9036vector signed int vec_slo (vector signed int, vector unsigned char); 9037vector unsigned int vec_slo (vector unsigned int, vector signed char); 9038vector unsigned int vec_slo (vector unsigned int, vector unsigned char); 9039vector signed short vec_slo (vector signed short, vector signed char); 9040vector signed short vec_slo (vector signed short, vector unsigned char); 9041vector unsigned short vec_slo (vector unsigned short, 9042 vector signed char); 9043vector unsigned short vec_slo (vector unsigned short, 9044 vector unsigned char); 9045vector pixel vec_slo (vector pixel, vector signed char); 9046vector pixel vec_slo (vector pixel, vector unsigned char); 9047vector signed char vec_slo (vector signed char, vector signed char); 9048vector signed char vec_slo (vector signed char, vector unsigned char); 9049vector unsigned char vec_slo (vector unsigned char, vector signed char); 9050vector unsigned char vec_slo (vector unsigned char, 9051 vector unsigned char); 9052 9053vector signed char vec_splat (vector signed char, const int); 9054vector unsigned char vec_splat (vector unsigned char, const int); 9055vector bool char vec_splat (vector bool char, const int); 9056vector signed short vec_splat (vector signed short, const int); 9057vector unsigned short vec_splat (vector unsigned short, const int); 9058vector bool short vec_splat (vector bool short, const int); 9059vector pixel vec_splat (vector pixel, const int); 9060vector float vec_splat (vector float, const int); 9061vector signed int vec_splat (vector signed int, const int); 9062vector unsigned int vec_splat (vector unsigned int, const int); 9063vector bool int vec_splat (vector bool int, const int); 9064 9065vector float vec_vspltw (vector float, const int); 9066vector signed int vec_vspltw (vector signed int, const int); 9067vector unsigned int vec_vspltw (vector unsigned int, const int); 9068vector bool int vec_vspltw (vector bool int, const int); 9069 9070vector bool short vec_vsplth (vector bool short, const int); 9071vector signed short vec_vsplth (vector signed short, const int); 9072vector unsigned short vec_vsplth (vector unsigned short, const int); 9073vector pixel vec_vsplth (vector pixel, const int); 9074 9075vector signed char vec_vspltb (vector signed char, const int); 9076vector unsigned char vec_vspltb (vector unsigned char, const int); 9077vector bool char vec_vspltb (vector bool char, const int); 9078 9079vector signed char vec_splat_s8 (const int); 9080 9081vector signed short vec_splat_s16 (const int); 9082 9083vector signed int vec_splat_s32 (const int); 9084 9085vector unsigned char vec_splat_u8 (const int); 9086 9087vector unsigned short vec_splat_u16 (const int); 9088 9089vector unsigned int vec_splat_u32 (const int); 9090 9091vector signed char vec_sr (vector signed char, vector unsigned char); 9092vector unsigned char vec_sr (vector unsigned char, 9093 vector unsigned char); 9094vector signed short vec_sr (vector signed short, 9095 vector unsigned short); 9096vector unsigned short vec_sr (vector unsigned short, 9097 vector unsigned short); 9098vector signed int vec_sr (vector signed int, vector unsigned int); 9099vector unsigned int vec_sr (vector unsigned int, vector unsigned int); 9100 9101vector signed int vec_vsrw (vector signed int, vector unsigned int); 9102vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); 9103 9104vector signed short vec_vsrh (vector signed short, 9105 vector unsigned short); 9106vector unsigned short vec_vsrh (vector unsigned short, 9107 vector unsigned short); 9108 9109vector signed char vec_vsrb (vector signed char, vector unsigned char); 9110vector unsigned char vec_vsrb (vector unsigned char, 9111 vector unsigned char); 9112 9113vector signed char vec_sra (vector signed char, vector unsigned char); 9114vector unsigned char vec_sra (vector unsigned char, 9115 vector unsigned char); 9116vector signed short vec_sra (vector signed short, 9117 vector unsigned short); 9118vector unsigned short vec_sra (vector unsigned short, 9119 vector unsigned short); 9120vector signed int vec_sra (vector signed int, vector unsigned int); 9121vector unsigned int vec_sra (vector unsigned int, vector unsigned int); 9122 9123vector signed int vec_vsraw (vector signed int, vector unsigned int); 9124vector unsigned int vec_vsraw (vector unsigned int, 9125 vector unsigned int); 9126 9127vector signed short vec_vsrah (vector signed short, 9128 vector unsigned short); 9129vector unsigned short vec_vsrah (vector unsigned short, 9130 vector unsigned short); 9131 9132vector signed char vec_vsrab (vector signed char, vector unsigned char); 9133vector unsigned char vec_vsrab (vector unsigned char, 9134 vector unsigned char); 9135 9136vector signed int vec_srl (vector signed int, vector unsigned int); 9137vector signed int vec_srl (vector signed int, vector unsigned short); 9138vector signed int vec_srl (vector signed int, vector unsigned char); 9139vector unsigned int vec_srl (vector unsigned int, vector unsigned int); 9140vector unsigned int vec_srl (vector unsigned int, 9141 vector unsigned short); 9142vector unsigned int vec_srl (vector unsigned int, vector unsigned char); 9143vector bool int vec_srl (vector bool int, vector unsigned int); 9144vector bool int vec_srl (vector bool int, vector unsigned short); 9145vector bool int vec_srl (vector bool int, vector unsigned char); 9146vector signed short vec_srl (vector signed short, vector unsigned int); 9147vector signed short vec_srl (vector signed short, 9148 vector unsigned short); 9149vector signed short vec_srl (vector signed short, vector unsigned char); 9150vector unsigned short vec_srl (vector unsigned short, 9151 vector unsigned int); 9152vector unsigned short vec_srl (vector unsigned short, 9153 vector unsigned short); 9154vector unsigned short vec_srl (vector unsigned short, 9155 vector unsigned char); 9156vector bool short vec_srl (vector bool short, vector unsigned int); 9157vector bool short vec_srl (vector bool short, vector unsigned short); 9158vector bool short vec_srl (vector bool short, vector unsigned char); 9159vector pixel vec_srl (vector pixel, vector unsigned int); 9160vector pixel vec_srl (vector pixel, vector unsigned short); 9161vector pixel vec_srl (vector pixel, vector unsigned char); 9162vector signed char vec_srl (vector signed char, vector unsigned int); 9163vector signed char vec_srl (vector signed char, vector unsigned short); 9164vector signed char vec_srl (vector signed char, vector unsigned char); 9165vector unsigned char vec_srl (vector unsigned char, 9166 vector unsigned int); 9167vector unsigned char vec_srl (vector unsigned char, 9168 vector unsigned short); 9169vector unsigned char vec_srl (vector unsigned char, 9170 vector unsigned char); 9171vector bool char vec_srl (vector bool char, vector unsigned int); 9172vector bool char vec_srl (vector bool char, vector unsigned short); 9173vector bool char vec_srl (vector bool char, vector unsigned char); 9174 9175vector float vec_sro (vector float, vector signed char); 9176vector float vec_sro (vector float, vector unsigned char); 9177vector signed int vec_sro (vector signed int, vector signed char); 9178vector signed int vec_sro (vector signed int, vector unsigned char); 9179vector unsigned int vec_sro (vector unsigned int, vector signed char); 9180vector unsigned int vec_sro (vector unsigned int, vector unsigned char); 9181vector signed short vec_sro (vector signed short, vector signed char); 9182vector signed short vec_sro (vector signed short, vector unsigned char); 9183vector unsigned short vec_sro (vector unsigned short, 9184 vector signed char); 9185vector unsigned short vec_sro (vector unsigned short, 9186 vector unsigned char); 9187vector pixel vec_sro (vector pixel, vector signed char); 9188vector pixel vec_sro (vector pixel, vector unsigned char); 9189vector signed char vec_sro (vector signed char, vector signed char); 9190vector signed char vec_sro (vector signed char, vector unsigned char); 9191vector unsigned char vec_sro (vector unsigned char, vector signed char); 9192vector unsigned char vec_sro (vector unsigned char, 9193 vector unsigned char); 9194 9195void vec_st (vector float, int, vector float *); 9196void vec_st (vector float, int, float *); 9197void vec_st (vector signed int, int, vector signed int *); 9198void vec_st (vector signed int, int, int *); 9199void vec_st (vector unsigned int, int, vector unsigned int *); 9200void vec_st (vector unsigned int, int, unsigned int *); 9201void vec_st (vector bool int, int, vector bool int *); 9202void vec_st (vector bool int, int, unsigned int *); 9203void vec_st (vector bool int, int, int *); 9204void vec_st (vector signed short, int, vector signed short *); 9205void vec_st (vector signed short, int, short *); 9206void vec_st (vector unsigned short, int, vector unsigned short *); 9207void vec_st (vector unsigned short, int, unsigned short *); 9208void vec_st (vector bool short, int, vector bool short *); 9209void vec_st (vector bool short, int, unsigned short *); 9210void vec_st (vector pixel, int, vector pixel *); 9211void vec_st (vector pixel, int, unsigned short *); 9212void vec_st (vector pixel, int, short *); 9213void vec_st (vector bool short, int, short *); 9214void vec_st (vector signed char, int, vector signed char *); 9215void vec_st (vector signed char, int, signed char *); 9216void vec_st (vector unsigned char, int, vector unsigned char *); 9217void vec_st (vector unsigned char, int, unsigned char *); 9218void vec_st (vector bool char, int, vector bool char *); 9219void vec_st (vector bool char, int, unsigned char *); 9220void vec_st (vector bool char, int, signed char *); 9221 9222void vec_ste (vector signed char, int, signed char *); 9223void vec_ste (vector unsigned char, int, unsigned char *); 9224void vec_ste (vector bool char, int, signed char *); 9225void vec_ste (vector bool char, int, unsigned char *); 9226void vec_ste (vector signed short, int, short *); 9227void vec_ste (vector unsigned short, int, unsigned short *); 9228void vec_ste (vector bool short, int, short *); 9229void vec_ste (vector bool short, int, unsigned short *); 9230void vec_ste (vector pixel, int, short *); 9231void vec_ste (vector pixel, int, unsigned short *); 9232void vec_ste (vector float, int, float *); 9233void vec_ste (vector signed int, int, int *); 9234void vec_ste (vector unsigned int, int, unsigned int *); 9235void vec_ste (vector bool int, int, int *); 9236void vec_ste (vector bool int, int, unsigned int *); 9237 9238void vec_stvewx (vector float, int, float *); 9239void vec_stvewx (vector signed int, int, int *); 9240void vec_stvewx (vector unsigned int, int, unsigned int *); 9241void vec_stvewx (vector bool int, int, int *); 9242void vec_stvewx (vector bool int, int, unsigned int *); 9243 9244void vec_stvehx (vector signed short, int, short *); 9245void vec_stvehx (vector unsigned short, int, unsigned short *); 9246void vec_stvehx (vector bool short, int, short *); 9247void vec_stvehx (vector bool short, int, unsigned short *); 9248void vec_stvehx (vector pixel, int, short *); 9249void vec_stvehx (vector pixel, int, unsigned short *); 9250 9251void vec_stvebx (vector signed char, int, signed char *); 9252void vec_stvebx (vector unsigned char, int, unsigned char *); 9253void vec_stvebx (vector bool char, int, signed char *); 9254void vec_stvebx (vector bool char, int, unsigned char *); 9255 9256void vec_stl (vector float, int, vector float *); 9257void vec_stl (vector float, int, float *); 9258void vec_stl (vector signed int, int, vector signed int *); 9259void vec_stl (vector signed int, int, int *); 9260void vec_stl (vector unsigned int, int, vector unsigned int *); 9261void vec_stl (vector unsigned int, int, unsigned int *); 9262void vec_stl (vector bool int, int, vector bool int *); 9263void vec_stl (vector bool int, int, unsigned int *); 9264void vec_stl (vector bool int, int, int *); 9265void vec_stl (vector signed short, int, vector signed short *); 9266void vec_stl (vector signed short, int, short *); 9267void vec_stl (vector unsigned short, int, vector unsigned short *); 9268void vec_stl (vector unsigned short, int, unsigned short *); 9269void vec_stl (vector bool short, int, vector bool short *); 9270void vec_stl (vector bool short, int, unsigned short *); 9271void vec_stl (vector bool short, int, short *); 9272void vec_stl (vector pixel, int, vector pixel *); 9273void vec_stl (vector pixel, int, unsigned short *); 9274void vec_stl (vector pixel, int, short *); 9275void vec_stl (vector signed char, int, vector signed char *); 9276void vec_stl (vector signed char, int, signed char *); 9277void vec_stl (vector unsigned char, int, vector unsigned char *); 9278void vec_stl (vector unsigned char, int, unsigned char *); 9279void vec_stl (vector bool char, int, vector bool char *); 9280void vec_stl (vector bool char, int, unsigned char *); 9281void vec_stl (vector bool char, int, signed char *); 9282 9283vector signed char vec_sub (vector bool char, vector signed char); 9284vector signed char vec_sub (vector signed char, vector bool char); 9285vector signed char vec_sub (vector signed char, vector signed char); 9286vector unsigned char vec_sub (vector bool char, vector unsigned char); 9287vector unsigned char vec_sub (vector unsigned char, vector bool char); 9288vector unsigned char vec_sub (vector unsigned char, 9289 vector unsigned char); 9290vector signed short vec_sub (vector bool short, vector signed short); 9291vector signed short vec_sub (vector signed short, vector bool short); 9292vector signed short vec_sub (vector signed short, vector signed short); 9293vector unsigned short vec_sub (vector bool short, 9294 vector unsigned short); 9295vector unsigned short vec_sub (vector unsigned short, 9296 vector bool short); 9297vector unsigned short vec_sub (vector unsigned short, 9298 vector unsigned short); 9299vector signed int vec_sub (vector bool int, vector signed int); 9300vector signed int vec_sub (vector signed int, vector bool int); 9301vector signed int vec_sub (vector signed int, vector signed int); 9302vector unsigned int vec_sub (vector bool int, vector unsigned int); 9303vector unsigned int vec_sub (vector unsigned int, vector bool int); 9304vector unsigned int vec_sub (vector unsigned int, vector unsigned int); 9305vector float vec_sub (vector float, vector float); 9306 9307vector float vec_vsubfp (vector float, vector float); 9308 9309vector signed int vec_vsubuwm (vector bool int, vector signed int); 9310vector signed int vec_vsubuwm (vector signed int, vector bool int); 9311vector signed int vec_vsubuwm (vector signed int, vector signed int); 9312vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); 9313vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); 9314vector unsigned int vec_vsubuwm (vector unsigned int, 9315 vector unsigned int); 9316 9317vector signed short vec_vsubuhm (vector bool short, 9318 vector signed short); 9319vector signed short vec_vsubuhm (vector signed short, 9320 vector bool short); 9321vector signed short vec_vsubuhm (vector signed short, 9322 vector signed short); 9323vector unsigned short vec_vsubuhm (vector bool short, 9324 vector unsigned short); 9325vector unsigned short vec_vsubuhm (vector unsigned short, 9326 vector bool short); 9327vector unsigned short vec_vsubuhm (vector unsigned short, 9328 vector unsigned short); 9329 9330vector signed char vec_vsububm (vector bool char, vector signed char); 9331vector signed char vec_vsububm (vector signed char, vector bool char); 9332vector signed char vec_vsububm (vector signed char, vector signed char); 9333vector unsigned char vec_vsububm (vector bool char, 9334 vector unsigned char); 9335vector unsigned char vec_vsububm (vector unsigned char, 9336 vector bool char); 9337vector unsigned char vec_vsububm (vector unsigned char, 9338 vector unsigned char); 9339 9340vector unsigned int vec_subc (vector unsigned int, vector unsigned int); 9341 9342vector unsigned char vec_subs (vector bool char, vector unsigned char); 9343vector unsigned char vec_subs (vector unsigned char, vector bool char); 9344vector unsigned char vec_subs (vector unsigned char, 9345 vector unsigned char); 9346vector signed char vec_subs (vector bool char, vector signed char); 9347vector signed char vec_subs (vector signed char, vector bool char); 9348vector signed char vec_subs (vector signed char, vector signed char); 9349vector unsigned short vec_subs (vector bool short, 9350 vector unsigned short); 9351vector unsigned short vec_subs (vector unsigned short, 9352 vector bool short); 9353vector unsigned short vec_subs (vector unsigned short, 9354 vector unsigned short); 9355vector signed short vec_subs (vector bool short, vector signed short); 9356vector signed short vec_subs (vector signed short, vector bool short); 9357vector signed short vec_subs (vector signed short, vector signed short); 9358vector unsigned int vec_subs (vector bool int, vector unsigned int); 9359vector unsigned int vec_subs (vector unsigned int, vector bool int); 9360vector unsigned int vec_subs (vector unsigned int, vector unsigned int); 9361vector signed int vec_subs (vector bool int, vector signed int); 9362vector signed int vec_subs (vector signed int, vector bool int); 9363vector signed int vec_subs (vector signed int, vector signed int); 9364 9365vector signed int vec_vsubsws (vector bool int, vector signed int); 9366vector signed int vec_vsubsws (vector signed int, vector bool int); 9367vector signed int vec_vsubsws (vector signed int, vector signed int); 9368 9369vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); 9370vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); 9371vector unsigned int vec_vsubuws (vector unsigned int, 9372 vector unsigned int); 9373 9374vector signed short vec_vsubshs (vector bool short, 9375 vector signed short); 9376vector signed short vec_vsubshs (vector signed short, 9377 vector bool short); 9378vector signed short vec_vsubshs (vector signed short, 9379 vector signed short); 9380 9381vector unsigned short vec_vsubuhs (vector bool short, 9382 vector unsigned short); 9383vector unsigned short vec_vsubuhs (vector unsigned short, 9384 vector bool short); 9385vector unsigned short vec_vsubuhs (vector unsigned short, 9386 vector unsigned short); 9387 9388vector signed char vec_vsubsbs (vector bool char, vector signed char); 9389vector signed char vec_vsubsbs (vector signed char, vector bool char); 9390vector signed char vec_vsubsbs (vector signed char, vector signed char); 9391 9392vector unsigned char vec_vsububs (vector bool char, 9393 vector unsigned char); 9394vector unsigned char vec_vsububs (vector unsigned char, 9395 vector bool char); 9396vector unsigned char vec_vsububs (vector unsigned char, 9397 vector unsigned char); 9398 9399vector unsigned int vec_sum4s (vector unsigned char, 9400 vector unsigned int); 9401vector signed int vec_sum4s (vector signed char, vector signed int); 9402vector signed int vec_sum4s (vector signed short, vector signed int); 9403 9404vector signed int vec_vsum4shs (vector signed short, vector signed int); 9405 9406vector signed int vec_vsum4sbs (vector signed char, vector signed int); 9407 9408vector unsigned int vec_vsum4ubs (vector unsigned char, 9409 vector unsigned int); 9410 9411vector signed int vec_sum2s (vector signed int, vector signed int); 9412 9413vector signed int vec_sums (vector signed int, vector signed int); 9414 9415vector float vec_trunc (vector float); 9416 9417vector signed short vec_unpackh (vector signed char); 9418vector bool short vec_unpackh (vector bool char); 9419vector signed int vec_unpackh (vector signed short); 9420vector bool int vec_unpackh (vector bool short); 9421vector unsigned int vec_unpackh (vector pixel); 9422 9423vector bool int vec_vupkhsh (vector bool short); 9424vector signed int vec_vupkhsh (vector signed short); 9425 9426vector unsigned int vec_vupkhpx (vector pixel); 9427 9428vector bool short vec_vupkhsb (vector bool char); 9429vector signed short vec_vupkhsb (vector signed char); 9430 9431vector signed short vec_unpackl (vector signed char); 9432vector bool short vec_unpackl (vector bool char); 9433vector unsigned int vec_unpackl (vector pixel); 9434vector signed int vec_unpackl (vector signed short); 9435vector bool int vec_unpackl (vector bool short); 9436 9437vector unsigned int vec_vupklpx (vector pixel); 9438 9439vector bool int vec_vupklsh (vector bool short); 9440vector signed int vec_vupklsh (vector signed short); 9441 9442vector bool short vec_vupklsb (vector bool char); 9443vector signed short vec_vupklsb (vector signed char); 9444 9445vector float vec_xor (vector float, vector float); 9446vector float vec_xor (vector float, vector bool int); 9447vector float vec_xor (vector bool int, vector float); 9448vector bool int vec_xor (vector bool int, vector bool int); 9449vector signed int vec_xor (vector bool int, vector signed int); 9450vector signed int vec_xor (vector signed int, vector bool int); 9451vector signed int vec_xor (vector signed int, vector signed int); 9452vector unsigned int vec_xor (vector bool int, vector unsigned int); 9453vector unsigned int vec_xor (vector unsigned int, vector bool int); 9454vector unsigned int vec_xor (vector unsigned int, vector unsigned int); 9455vector bool short vec_xor (vector bool short, vector bool short); 9456vector signed short vec_xor (vector bool short, vector signed short); 9457vector signed short vec_xor (vector signed short, vector bool short); 9458vector signed short vec_xor (vector signed short, vector signed short); 9459vector unsigned short vec_xor (vector bool short, 9460 vector unsigned short); 9461vector unsigned short vec_xor (vector unsigned short, 9462 vector bool short); 9463vector unsigned short vec_xor (vector unsigned short, 9464 vector unsigned short); 9465vector signed char vec_xor (vector bool char, vector signed char); 9466vector bool char vec_xor (vector bool char, vector bool char); 9467vector signed char vec_xor (vector signed char, vector bool char); 9468vector signed char vec_xor (vector signed char, vector signed char); 9469vector unsigned char vec_xor (vector bool char, vector unsigned char); 9470vector unsigned char vec_xor (vector unsigned char, vector bool char); 9471vector unsigned char vec_xor (vector unsigned char, 9472 vector unsigned char); 9473 9474int vec_all_eq (vector signed char, vector bool char); 9475int vec_all_eq (vector signed char, vector signed char); 9476int vec_all_eq (vector unsigned char, vector bool char); 9477int vec_all_eq (vector unsigned char, vector unsigned char); 9478int vec_all_eq (vector bool char, vector bool char); 9479int vec_all_eq (vector bool char, vector unsigned char); 9480int vec_all_eq (vector bool char, vector signed char); 9481int vec_all_eq (vector signed short, vector bool short); 9482int vec_all_eq (vector signed short, vector signed short); 9483int vec_all_eq (vector unsigned short, vector bool short); 9484int vec_all_eq (vector unsigned short, vector unsigned short); 9485int vec_all_eq (vector bool short, vector bool short); 9486int vec_all_eq (vector bool short, vector unsigned short); 9487int vec_all_eq (vector bool short, vector signed short); 9488int vec_all_eq (vector pixel, vector pixel); 9489int vec_all_eq (vector signed int, vector bool int); 9490int vec_all_eq (vector signed int, vector signed int); 9491int vec_all_eq (vector unsigned int, vector bool int); 9492int vec_all_eq (vector unsigned int, vector unsigned int); 9493int vec_all_eq (vector bool int, vector bool int); 9494int vec_all_eq (vector bool int, vector unsigned int); 9495int vec_all_eq (vector bool int, vector signed int); 9496int vec_all_eq (vector float, vector float); 9497 9498int vec_all_ge (vector bool char, vector unsigned char); 9499int vec_all_ge (vector unsigned char, vector bool char); 9500int vec_all_ge (vector unsigned char, vector unsigned char); 9501int vec_all_ge (vector bool char, vector signed char); 9502int vec_all_ge (vector signed char, vector bool char); 9503int vec_all_ge (vector signed char, vector signed char); 9504int vec_all_ge (vector bool short, vector unsigned short); 9505int vec_all_ge (vector unsigned short, vector bool short); 9506int vec_all_ge (vector unsigned short, vector unsigned short); 9507int vec_all_ge (vector signed short, vector signed short); 9508int vec_all_ge (vector bool short, vector signed short); 9509int vec_all_ge (vector signed short, vector bool short); 9510int vec_all_ge (vector bool int, vector unsigned int); 9511int vec_all_ge (vector unsigned int, vector bool int); 9512int vec_all_ge (vector unsigned int, vector unsigned int); 9513int vec_all_ge (vector bool int, vector signed int); 9514int vec_all_ge (vector signed int, vector bool int); 9515int vec_all_ge (vector signed int, vector signed int); 9516int vec_all_ge (vector float, vector float); 9517 9518int vec_all_gt (vector bool char, vector unsigned char); 9519int vec_all_gt (vector unsigned char, vector bool char); 9520int vec_all_gt (vector unsigned char, vector unsigned char); 9521int vec_all_gt (vector bool char, vector signed char); 9522int vec_all_gt (vector signed char, vector bool char); 9523int vec_all_gt (vector signed char, vector signed char); 9524int vec_all_gt (vector bool short, vector unsigned short); 9525int vec_all_gt (vector unsigned short, vector bool short); 9526int vec_all_gt (vector unsigned short, vector unsigned short); 9527int vec_all_gt (vector bool short, vector signed short); 9528int vec_all_gt (vector signed short, vector bool short); 9529int vec_all_gt (vector signed short, vector signed short); 9530int vec_all_gt (vector bool int, vector unsigned int); 9531int vec_all_gt (vector unsigned int, vector bool int); 9532int vec_all_gt (vector unsigned int, vector unsigned int); 9533int vec_all_gt (vector bool int, vector signed int); 9534int vec_all_gt (vector signed int, vector bool int); 9535int vec_all_gt (vector signed int, vector signed int); 9536int vec_all_gt (vector float, vector float); 9537 9538int vec_all_in (vector float, vector float); 9539 9540int vec_all_le (vector bool char, vector unsigned char); 9541int vec_all_le (vector unsigned char, vector bool char); 9542int vec_all_le (vector unsigned char, vector unsigned char); 9543int vec_all_le (vector bool char, vector signed char); 9544int vec_all_le (vector signed char, vector bool char); 9545int vec_all_le (vector signed char, vector signed char); 9546int vec_all_le (vector bool short, vector unsigned short); 9547int vec_all_le (vector unsigned short, vector bool short); 9548int vec_all_le (vector unsigned short, vector unsigned short); 9549int vec_all_le (vector bool short, vector signed short); 9550int vec_all_le (vector signed short, vector bool short); 9551int vec_all_le (vector signed short, vector signed short); 9552int vec_all_le (vector bool int, vector unsigned int); 9553int vec_all_le (vector unsigned int, vector bool int); 9554int vec_all_le (vector unsigned int, vector unsigned int); 9555int vec_all_le (vector bool int, vector signed int); 9556int vec_all_le (vector signed int, vector bool int); 9557int vec_all_le (vector signed int, vector signed int); 9558int vec_all_le (vector float, vector float); 9559 9560int vec_all_lt (vector bool char, vector unsigned char); 9561int vec_all_lt (vector unsigned char, vector bool char); 9562int vec_all_lt (vector unsigned char, vector unsigned char); 9563int vec_all_lt (vector bool char, vector signed char); 9564int vec_all_lt (vector signed char, vector bool char); 9565int vec_all_lt (vector signed char, vector signed char); 9566int vec_all_lt (vector bool short, vector unsigned short); 9567int vec_all_lt (vector unsigned short, vector bool short); 9568int vec_all_lt (vector unsigned short, vector unsigned short); 9569int vec_all_lt (vector bool short, vector signed short); 9570int vec_all_lt (vector signed short, vector bool short); 9571int vec_all_lt (vector signed short, vector signed short); 9572int vec_all_lt (vector bool int, vector unsigned int); 9573int vec_all_lt (vector unsigned int, vector bool int); 9574int vec_all_lt (vector unsigned int, vector unsigned int); 9575int vec_all_lt (vector bool int, vector signed int); 9576int vec_all_lt (vector signed int, vector bool int); 9577int vec_all_lt (vector signed int, vector signed int); 9578int vec_all_lt (vector float, vector float); 9579 9580int vec_all_nan (vector float); 9581 9582int vec_all_ne (vector signed char, vector bool char); 9583int vec_all_ne (vector signed char, vector signed char); 9584int vec_all_ne (vector unsigned char, vector bool char); 9585int vec_all_ne (vector unsigned char, vector unsigned char); 9586int vec_all_ne (vector bool char, vector bool char); 9587int vec_all_ne (vector bool char, vector unsigned char); 9588int vec_all_ne (vector bool char, vector signed char); 9589int vec_all_ne (vector signed short, vector bool short); 9590int vec_all_ne (vector signed short, vector signed short); 9591int vec_all_ne (vector unsigned short, vector bool short); 9592int vec_all_ne (vector unsigned short, vector unsigned short); 9593int vec_all_ne (vector bool short, vector bool short); 9594int vec_all_ne (vector bool short, vector unsigned short); 9595int vec_all_ne (vector bool short, vector signed short); 9596int vec_all_ne (vector pixel, vector pixel); 9597int vec_all_ne (vector signed int, vector bool int); 9598int vec_all_ne (vector signed int, vector signed int); 9599int vec_all_ne (vector unsigned int, vector bool int); 9600int vec_all_ne (vector unsigned int, vector unsigned int); 9601int vec_all_ne (vector bool int, vector bool int); 9602int vec_all_ne (vector bool int, vector unsigned int); 9603int vec_all_ne (vector bool int, vector signed int); 9604int vec_all_ne (vector float, vector float); 9605 9606int vec_all_nge (vector float, vector float); 9607 9608int vec_all_ngt (vector float, vector float); 9609 9610int vec_all_nle (vector float, vector float); 9611 9612int vec_all_nlt (vector float, vector float); 9613 9614int vec_all_numeric (vector float); 9615 9616int vec_any_eq (vector signed char, vector bool char); 9617int vec_any_eq (vector signed char, vector signed char); 9618int vec_any_eq (vector unsigned char, vector bool char); 9619int vec_any_eq (vector unsigned char, vector unsigned char); 9620int vec_any_eq (vector bool char, vector bool char); 9621int vec_any_eq (vector bool char, vector unsigned char); 9622int vec_any_eq (vector bool char, vector signed char); 9623int vec_any_eq (vector signed short, vector bool short); 9624int vec_any_eq (vector signed short, vector signed short); 9625int vec_any_eq (vector unsigned short, vector bool short); 9626int vec_any_eq (vector unsigned short, vector unsigned short); 9627int vec_any_eq (vector bool short, vector bool short); 9628int vec_any_eq (vector bool short, vector unsigned short); 9629int vec_any_eq (vector bool short, vector signed short); 9630int vec_any_eq (vector pixel, vector pixel); 9631int vec_any_eq (vector signed int, vector bool int); 9632int vec_any_eq (vector signed int, vector signed int); 9633int vec_any_eq (vector unsigned int, vector bool int); 9634int vec_any_eq (vector unsigned int, vector unsigned int); 9635int vec_any_eq (vector bool int, vector bool int); 9636int vec_any_eq (vector bool int, vector unsigned int); 9637int vec_any_eq (vector bool int, vector signed int); 9638int vec_any_eq (vector float, vector float); 9639 9640int vec_any_ge (vector signed char, vector bool char); 9641int vec_any_ge (vector unsigned char, vector bool char); 9642int vec_any_ge (vector unsigned char, vector unsigned char); 9643int vec_any_ge (vector signed char, vector signed char); 9644int vec_any_ge (vector bool char, vector unsigned char); 9645int vec_any_ge (vector bool char, vector signed char); 9646int vec_any_ge (vector unsigned short, vector bool short); 9647int vec_any_ge (vector unsigned short, vector unsigned short); 9648int vec_any_ge (vector signed short, vector signed short); 9649int vec_any_ge (vector signed short, vector bool short); 9650int vec_any_ge (vector bool short, vector unsigned short); 9651int vec_any_ge (vector bool short, vector signed short); 9652int vec_any_ge (vector signed int, vector bool int); 9653int vec_any_ge (vector unsigned int, vector bool int); 9654int vec_any_ge (vector unsigned int, vector unsigned int); 9655int vec_any_ge (vector signed int, vector signed int); 9656int vec_any_ge (vector bool int, vector unsigned int); 9657int vec_any_ge (vector bool int, vector signed int); 9658int vec_any_ge (vector float, vector float); 9659 9660int vec_any_gt (vector bool char, vector unsigned char); 9661int vec_any_gt (vector unsigned char, vector bool char); 9662int vec_any_gt (vector unsigned char, vector unsigned char); 9663int vec_any_gt (vector bool char, vector signed char); 9664int vec_any_gt (vector signed char, vector bool char); 9665int vec_any_gt (vector signed char, vector signed char); 9666int vec_any_gt (vector bool short, vector unsigned short); 9667int vec_any_gt (vector unsigned short, vector bool short); 9668int vec_any_gt (vector unsigned short, vector unsigned short); 9669int vec_any_gt (vector bool short, vector signed short); 9670int vec_any_gt (vector signed short, vector bool short); 9671int vec_any_gt (vector signed short, vector signed short); 9672int vec_any_gt (vector bool int, vector unsigned int); 9673int vec_any_gt (vector unsigned int, vector bool int); 9674int vec_any_gt (vector unsigned int, vector unsigned int); 9675int vec_any_gt (vector bool int, vector signed int); 9676int vec_any_gt (vector signed int, vector bool int); 9677int vec_any_gt (vector signed int, vector signed int); 9678int vec_any_gt (vector float, vector float); 9679 9680int vec_any_le (vector bool char, vector unsigned char); 9681int vec_any_le (vector unsigned char, vector bool char); 9682int vec_any_le (vector unsigned char, vector unsigned char); 9683int vec_any_le (vector bool char, vector signed char); 9684int vec_any_le (vector signed char, vector bool char); 9685int vec_any_le (vector signed char, vector signed char); 9686int vec_any_le (vector bool short, vector unsigned short); 9687int vec_any_le (vector unsigned short, vector bool short); 9688int vec_any_le (vector unsigned short, vector unsigned short); 9689int vec_any_le (vector bool short, vector signed short); 9690int vec_any_le (vector signed short, vector bool short); 9691int vec_any_le (vector signed short, vector signed short); 9692int vec_any_le (vector bool int, vector unsigned int); 9693int vec_any_le (vector unsigned int, vector bool int); 9694int vec_any_le (vector unsigned int, vector unsigned int); 9695int vec_any_le (vector bool int, vector signed int); 9696int vec_any_le (vector signed int, vector bool int); 9697int vec_any_le (vector signed int, vector signed int); 9698int vec_any_le (vector float, vector float); 9699 9700int vec_any_lt (vector bool char, vector unsigned char); 9701int vec_any_lt (vector unsigned char, vector bool char); 9702int vec_any_lt (vector unsigned char, vector unsigned char); 9703int vec_any_lt (vector bool char, vector signed char); 9704int vec_any_lt (vector signed char, vector bool char); 9705int vec_any_lt (vector signed char, vector signed char); 9706int vec_any_lt (vector bool short, vector unsigned short); 9707int vec_any_lt (vector unsigned short, vector bool short); 9708int vec_any_lt (vector unsigned short, vector unsigned short); 9709int vec_any_lt (vector bool short, vector signed short); 9710int vec_any_lt (vector signed short, vector bool short); 9711int vec_any_lt (vector signed short, vector signed short); 9712int vec_any_lt (vector bool int, vector unsigned int); 9713int vec_any_lt (vector unsigned int, vector bool int); 9714int vec_any_lt (vector unsigned int, vector unsigned int); 9715int vec_any_lt (vector bool int, vector signed int); 9716int vec_any_lt (vector signed int, vector bool int); 9717int vec_any_lt (vector signed int, vector signed int); 9718int vec_any_lt (vector float, vector float); 9719 9720int vec_any_nan (vector float); 9721 9722int vec_any_ne (vector signed char, vector bool char); 9723int vec_any_ne (vector signed char, vector signed char); 9724int vec_any_ne (vector unsigned char, vector bool char); 9725int vec_any_ne (vector unsigned char, vector unsigned char); 9726int vec_any_ne (vector bool char, vector bool char); 9727int vec_any_ne (vector bool char, vector unsigned char); 9728int vec_any_ne (vector bool char, vector signed char); 9729int vec_any_ne (vector signed short, vector bool short); 9730int vec_any_ne (vector signed short, vector signed short); 9731int vec_any_ne (vector unsigned short, vector bool short); 9732int vec_any_ne (vector unsigned short, vector unsigned short); 9733int vec_any_ne (vector bool short, vector bool short); 9734int vec_any_ne (vector bool short, vector unsigned short); 9735int vec_any_ne (vector bool short, vector signed short); 9736int vec_any_ne (vector pixel, vector pixel); 9737int vec_any_ne (vector signed int, vector bool int); 9738int vec_any_ne (vector signed int, vector signed int); 9739int vec_any_ne (vector unsigned int, vector bool int); 9740int vec_any_ne (vector unsigned int, vector unsigned int); 9741int vec_any_ne (vector bool int, vector bool int); 9742int vec_any_ne (vector bool int, vector unsigned int); 9743int vec_any_ne (vector bool int, vector signed int); 9744int vec_any_ne (vector float, vector float); 9745 9746int vec_any_nge (vector float, vector float); 9747 9748int vec_any_ngt (vector float, vector float); 9749 9750int vec_any_nle (vector float, vector float); 9751 9752int vec_any_nlt (vector float, vector float); 9753 9754int vec_any_numeric (vector float); 9755 9756int vec_any_out (vector float, vector float); 9757@end smallexample 9758 9759@node SPARC VIS Built-in Functions 9760@subsection SPARC VIS Built-in Functions 9761 9762GCC supports SIMD operations on the SPARC using both the generic vector 9763extensions (@pxref{Vector Extensions}) as well as built-in functions for 9764the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} 9765switch, the VIS extension is exposed as the following built-in functions: 9766 9767@smallexample 9768typedef int v2si __attribute__ ((vector_size (8))); 9769typedef short v4hi __attribute__ ((vector_size (8))); 9770typedef short v2hi __attribute__ ((vector_size (4))); 9771typedef char v8qi __attribute__ ((vector_size (8))); 9772typedef char v4qi __attribute__ ((vector_size (4))); 9773 9774void * __builtin_vis_alignaddr (void *, long); 9775int64_t __builtin_vis_faligndatadi (int64_t, int64_t); 9776v2si __builtin_vis_faligndatav2si (v2si, v2si); 9777v4hi __builtin_vis_faligndatav4hi (v4si, v4si); 9778v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); 9779 9780v4hi __builtin_vis_fexpand (v4qi); 9781 9782v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); 9783v4hi __builtin_vis_fmul8x16au (v4qi, v4hi); 9784v4hi __builtin_vis_fmul8x16al (v4qi, v4hi); 9785v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); 9786v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); 9787v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); 9788v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); 9789 9790v4qi __builtin_vis_fpack16 (v4hi); 9791v8qi __builtin_vis_fpack32 (v2si, v2si); 9792v2hi __builtin_vis_fpackfix (v2si); 9793v8qi __builtin_vis_fpmerge (v4qi, v4qi); 9794 9795int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); 9796@end smallexample 9797 9798@node Target Format Checks 9799@section Format Checks Specific to Particular Target Machines 9800 9801For some target machines, GCC supports additional options to the 9802format attribute 9803(@pxref{Function Attributes,,Declaring Attributes of Functions}). 9804 9805@menu 9806* Solaris Format Checks:: 9807@end menu 9808 9809@node Solaris Format Checks 9810@subsection Solaris Format Checks 9811 9812Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format 9813check. @code{cmn_err} accepts a subset of the standard @code{printf} 9814conversions, and the two-argument @code{%b} conversion for displaying 9815bit-fields. See the Solaris man page for @code{cmn_err} for more information. 9816 9817@node Pragmas 9818@section Pragmas Accepted by GCC 9819@cindex pragmas 9820@cindex #pragma 9821 9822GCC supports several types of pragmas, primarily in order to compile 9823code originally written for other compilers. Note that in general 9824we do not recommend the use of pragmas; @xref{Function Attributes}, 9825for further explanation. 9826 9827@menu 9828* ARM Pragmas:: 9829* M32C Pragmas:: 9830* RS/6000 and PowerPC Pragmas:: 9831* Darwin Pragmas:: 9832* Solaris Pragmas:: 9833* Symbol-Renaming Pragmas:: 9834* Structure-Packing Pragmas:: 9835* Weak Pragmas:: 9836* Diagnostic Pragmas:: 9837* Visibility Pragmas:: 9838@end menu 9839 9840@node ARM Pragmas 9841@subsection ARM Pragmas 9842 9843The ARM target defines pragmas for controlling the default addition of 9844@code{long_call} and @code{short_call} attributes to functions. 9845@xref{Function Attributes}, for information about the effects of these 9846attributes. 9847 9848@table @code 9849@item long_calls 9850@cindex pragma, long_calls 9851Set all subsequent functions to have the @code{long_call} attribute. 9852 9853@item no_long_calls 9854@cindex pragma, no_long_calls 9855Set all subsequent functions to have the @code{short_call} attribute. 9856 9857@item long_calls_off 9858@cindex pragma, long_calls_off 9859Do not affect the @code{long_call} or @code{short_call} attributes of 9860subsequent functions. 9861@end table 9862 9863@node M32C Pragmas 9864@subsection M32C Pragmas 9865 9866@table @code 9867@item memregs @var{number} 9868@cindex pragma, memregs 9869Overrides the command line option @code{-memregs=} for the current 9870file. Use with care! This pragma must be before any function in the 9871file, and mixing different memregs values in different objects may 9872make them incompatible. This pragma is useful when a 9873performance-critical function uses a memreg for temporary values, 9874as it may allow you to reduce the number of memregs used. 9875 9876@end table 9877 9878@node RS/6000 and PowerPC Pragmas 9879@subsection RS/6000 and PowerPC Pragmas 9880 9881The RS/6000 and PowerPC targets define one pragma for controlling 9882whether or not the @code{longcall} attribute is added to function 9883declarations by default. This pragma overrides the @option{-mlongcall} 9884option, but not the @code{longcall} and @code{shortcall} attributes. 9885@xref{RS/6000 and PowerPC Options}, for more information about when long 9886calls are and are not necessary. 9887 9888@table @code 9889@item longcall (1) 9890@cindex pragma, longcall 9891Apply the @code{longcall} attribute to all subsequent function 9892declarations. 9893 9894@item longcall (0) 9895Do not apply the @code{longcall} attribute to subsequent function 9896declarations. 9897@end table 9898 9899@c Describe c4x pragmas here. 9900@c Describe h8300 pragmas here. 9901@c Describe sh pragmas here. 9902@c Describe v850 pragmas here. 9903 9904@node Darwin Pragmas 9905@subsection Darwin Pragmas 9906 9907The following pragmas are available for all architectures running the 9908Darwin operating system. These are useful for compatibility with other 9909Mac OS compilers. 9910 9911@table @code 9912@item mark @var{tokens}@dots{} 9913@cindex pragma, mark 9914This pragma is accepted, but has no effect. 9915 9916@item options align=@var{alignment} 9917@cindex pragma, options align 9918This pragma sets the alignment of fields in structures. The values of 9919@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or 9920@code{power}, to emulate PowerPC alignment. Uses of this pragma nest 9921properly; to restore the previous setting, use @code{reset} for the 9922@var{alignment}. 9923 9924@item segment @var{tokens}@dots{} 9925@cindex pragma, segment 9926This pragma is accepted, but has no effect. 9927 9928@item unused (@var{var} [, @var{var}]@dots{}) 9929@cindex pragma, unused 9930This pragma declares variables to be possibly unused. GCC will not 9931produce warnings for the listed variables. The effect is similar to 9932that of the @code{unused} attribute, except that this pragma may appear 9933anywhere within the variables' scopes. 9934@end table 9935 9936@node Solaris Pragmas 9937@subsection Solaris Pragmas 9938 9939The Solaris target supports @code{#pragma redefine_extname} 9940(@pxref{Symbol-Renaming Pragmas}). It also supports additional 9941@code{#pragma} directives for compatibility with the system compiler. 9942 9943@table @code 9944@item align @var{alignment} (@var{variable} [, @var{variable}]...) 9945@cindex pragma, align 9946 9947Increase the minimum alignment of each @var{variable} to @var{alignment}. 9948This is the same as GCC's @code{aligned} attribute @pxref{Variable 9949Attributes}). Macro expansion occurs on the arguments to this pragma 9950when compiling C. It does not currently occur when compiling C++, but 9951this is a bug which may be fixed in a future release. 9952 9953@item fini (@var{function} [, @var{function}]...) 9954@cindex pragma, fini 9955 9956This pragma causes each listed @var{function} to be called after 9957main, or during shared module unloading, by adding a call to the 9958@code{.fini} section. 9959 9960@item init (@var{function} [, @var{function}]...) 9961@cindex pragma, init 9962 9963This pragma causes each listed @var{function} to be called during 9964initialization (before @code{main}) or during shared module loading, by 9965adding a call to the @code{.init} section. 9966 9967@end table 9968 9969@node Symbol-Renaming Pragmas 9970@subsection Symbol-Renaming Pragmas 9971 9972For compatibility with the Solaris and Tru64 UNIX system headers, GCC 9973supports two @code{#pragma} directives which change the name used in 9974assembly for a given declaration. These pragmas are only available on 9975platforms whose system headers need them. To get this effect on all 9976platforms supported by GCC, use the asm labels extension (@pxref{Asm 9977Labels}). 9978 9979@table @code 9980@item redefine_extname @var{oldname} @var{newname} 9981@cindex pragma, redefine_extname 9982 9983This pragma gives the C function @var{oldname} the assembly symbol 9984@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} 9985will be defined if this pragma is available (currently only on 9986Solaris). 9987 9988@item extern_prefix @var{string} 9989@cindex pragma, extern_prefix 9990 9991This pragma causes all subsequent external function and variable 9992declarations to have @var{string} prepended to their assembly symbols. 9993This effect may be terminated with another @code{extern_prefix} pragma 9994whose argument is an empty string. The preprocessor macro 9995@code{__PRAGMA_EXTERN_PREFIX} will be defined if this pragma is 9996available (currently only on Tru64 UNIX)@. 9997@end table 9998 9999These pragmas and the asm labels extension interact in a complicated 10000manner. Here are some corner cases you may want to be aware of. 10001 10002@enumerate 10003@item Both pragmas silently apply only to declarations with external 10004linkage. Asm labels do not have this restriction. 10005 10006@item In C++, both pragmas silently apply only to declarations with 10007``C'' linkage. Again, asm labels do not have this restriction. 10008 10009@item If any of the three ways of changing the assembly name of a 10010declaration is applied to a declaration whose assembly name has 10011already been determined (either by a previous use of one of these 10012features, or because the compiler needed the assembly name in order to 10013generate code), and the new name is different, a warning issues and 10014the name does not change. 10015 10016@item The @var{oldname} used by @code{#pragma redefine_extname} is 10017always the C-language name. 10018 10019@item If @code{#pragma extern_prefix} is in effect, and a declaration 10020occurs with an asm label attached, the prefix is silently ignored for 10021that declaration. 10022 10023@item If @code{#pragma extern_prefix} and @code{#pragma redefine_extname} 10024apply to the same declaration, whichever triggered first wins, and a 10025warning issues if they contradict each other. (We would like to have 10026@code{#pragma redefine_extname} always win, for consistency with asm 10027labels, but if @code{#pragma extern_prefix} triggers first we have no 10028way of knowing that that happened.) 10029@end enumerate 10030 10031@node Structure-Packing Pragmas 10032@subsection Structure-Packing Pragmas 10033 10034For compatibility with Win32, GCC supports a set of @code{#pragma} 10035directives which change the maximum alignment of members of structures 10036(other than zero-width bitfields), unions, and classes subsequently 10037defined. The @var{n} value below always is required to be a small power 10038of two and specifies the new alignment in bytes. 10039 10040@enumerate 10041@item @code{#pragma pack(@var{n})} simply sets the new alignment. 10042@item @code{#pragma pack()} sets the alignment to the one that was in 10043effect when compilation started (see also command line option 10044@option{-fpack-struct[=<n>]} @pxref{Code Gen Options}). 10045@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment 10046setting on an internal stack and then optionally sets the new alignment. 10047@item @code{#pragma pack(pop)} restores the alignment setting to the one 10048saved at the top of the internal stack (and removes that stack entry). 10049Note that @code{#pragma pack([@var{n}])} does not influence this internal 10050stack; thus it is possible to have @code{#pragma pack(push)} followed by 10051multiple @code{#pragma pack(@var{n})} instances and finalized by a single 10052@code{#pragma pack(pop)}. 10053@end enumerate 10054 10055Some targets, e.g. i386 and powerpc, support the @code{ms_struct} 10056@code{#pragma} which lays out a structure as the documented 10057@code{__attribute__ ((ms_struct))}. 10058@enumerate 10059@item @code{#pragma ms_struct on} turns on the layout for structures 10060declared. 10061@item @code{#pragma ms_struct off} turns off the layout for structures 10062declared. 10063@item @code{#pragma ms_struct reset} goes back to the default layout. 10064@end enumerate 10065 10066@node Weak Pragmas 10067@subsection Weak Pragmas 10068 10069For compatibility with SVR4, GCC supports a set of @code{#pragma} 10070directives for declaring symbols to be weak, and defining weak 10071aliases. 10072 10073@table @code 10074@item #pragma weak @var{symbol} 10075@cindex pragma, weak 10076This pragma declares @var{symbol} to be weak, as if the declaration 10077had the attribute of the same name. The pragma may appear before 10078or after the declaration of @var{symbol}, but must appear before 10079either its first use or its definition. It is not an error for 10080@var{symbol} to never be defined at all. 10081 10082@item #pragma weak @var{symbol1} = @var{symbol2} 10083This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. 10084It is an error if @var{symbol2} is not defined in the current 10085translation unit. 10086@end table 10087 10088@node Diagnostic Pragmas 10089@subsection Diagnostic Pragmas 10090 10091GCC allows the user to selectively enable or disable certain types of 10092diagnostics, and change the kind of the diagnostic. For example, a 10093project's policy might require that all sources compile with 10094@option{-Werror} but certain files might have exceptions allowing 10095specific types of warnings. Or, a project might selectively enable 10096diagnostics and treat them as errors depending on which preprocessor 10097macros are defined. 10098 10099@table @code 10100@item #pragma GCC diagnostic @var{kind} @var{option} 10101@cindex pragma, diagnostic 10102 10103Modifies the disposition of a diagnostic. Note that not all 10104diagnostics are modifiable; at the moment only warnings (normally 10105controlled by @samp{-W...}) can be controlled, and not all of them. 10106Use @option{-fdiagnostics-show-option} to determine which diagnostics 10107are controllable and which option controls them. 10108 10109@var{kind} is @samp{error} to treat this diagnostic as an error, 10110@samp{warning} to treat it like a warning (even if @option{-Werror} is 10111in effect), or @samp{ignored} if the diagnostic is to be ignored. 10112@var{option} is a double quoted string which matches the command line 10113option. 10114 10115@example 10116#pragma GCC diagnostic warning "-Wformat" 10117#pragma GCC diagnostic error "-Wformat" 10118#pragma GCC diagnostic ignored "-Wformat" 10119@end example 10120 10121Note that these pragmas override any command line options. Also, 10122while it is syntactically valid to put these pragmas anywhere in your 10123sources, the only supported location for them is before any data or 10124functions are defined. Doing otherwise may result in unpredictable 10125results depending on how the optimizer manages your sources. If the 10126same option is listed multiple times, the last one specified is the 10127one that is in effect. This pragma is not intended to be a general 10128purpose replacement for command line options, but for implementing 10129strict control over project policies. 10130 10131@end table 10132 10133@node Visibility Pragmas 10134@subsection Visibility Pragmas 10135 10136@table @code 10137@item #pragma GCC visibility push(@var{visibility}) 10138@itemx #pragma GCC visibility pop 10139@cindex pragma, visibility 10140 10141This pragma allows the user to set the visibility for multiple 10142declarations without having to give each a visibility attribute 10143@xref{Function Attributes}, for more information about visibility and 10144the attribute syntax. 10145 10146In C++, @samp{#pragma GCC visibility} affects only namespace-scope 10147declarations. Class members and template specializations are not 10148affected; if you want to override the visibility for a particular 10149member or instantiation, you must use an attribute. 10150 10151@end table 10152 10153@node Unnamed Fields 10154@section Unnamed struct/union fields within structs/unions 10155@cindex struct 10156@cindex union 10157 10158For compatibility with other compilers, GCC allows you to define 10159a structure or union that contains, as fields, structures and unions 10160without names. For example: 10161 10162@smallexample 10163struct @{ 10164 int a; 10165 union @{ 10166 int b; 10167 float c; 10168 @}; 10169 int d; 10170@} foo; 10171@end smallexample 10172 10173In this example, the user would be able to access members of the unnamed 10174union with code like @samp{foo.b}. Note that only unnamed structs and 10175unions are allowed, you may not have, for example, an unnamed 10176@code{int}. 10177 10178You must never create such structures that cause ambiguous field definitions. 10179For example, this structure: 10180 10181@smallexample 10182struct @{ 10183 int a; 10184 struct @{ 10185 int a; 10186 @}; 10187@} foo; 10188@end smallexample 10189 10190It is ambiguous which @code{a} is being referred to with @samp{foo.a}. 10191Such constructs are not supported and must be avoided. In the future, 10192such constructs may be detected and treated as compilation errors. 10193 10194@opindex fms-extensions 10195Unless @option{-fms-extensions} is used, the unnamed field must be a 10196structure or union definition without a tag (for example, @samp{struct 10197@{ int a; @};}). If @option{-fms-extensions} is used, the field may 10198also be a definition with a tag such as @samp{struct foo @{ int a; 10199@};}, a reference to a previously defined structure or union such as 10200@samp{struct foo;}, or a reference to a @code{typedef} name for a 10201previously defined structure or union type. 10202 10203@node Thread-Local 10204@section Thread-Local Storage 10205@cindex Thread-Local Storage 10206@cindex @acronym{TLS} 10207@cindex __thread 10208 10209Thread-local storage (@acronym{TLS}) is a mechanism by which variables 10210are allocated such that there is one instance of the variable per extant 10211thread. The run-time model GCC uses to implement this originates 10212in the IA-64 processor-specific ABI, but has since been migrated 10213to other processors as well. It requires significant support from 10214the linker (@command{ld}), dynamic linker (@command{ld.so}), and 10215system libraries (@file{libc.so} and @file{libpthread.so}), so it 10216is not available everywhere. 10217 10218At the user level, the extension is visible with a new storage 10219class keyword: @code{__thread}. For example: 10220 10221@smallexample 10222__thread int i; 10223extern __thread struct state s; 10224static __thread char *p; 10225@end smallexample 10226 10227The @code{__thread} specifier may be used alone, with the @code{extern} 10228or @code{static} specifiers, but with no other storage class specifier. 10229When used with @code{extern} or @code{static}, @code{__thread} must appear 10230immediately after the other storage class specifier. 10231 10232The @code{__thread} specifier may be applied to any global, file-scoped 10233static, function-scoped static, or static data member of a class. It may 10234not be applied to block-scoped automatic or non-static data member. 10235 10236When the address-of operator is applied to a thread-local variable, it is 10237evaluated at run-time and returns the address of the current thread's 10238instance of that variable. An address so obtained may be used by any 10239thread. When a thread terminates, any pointers to thread-local variables 10240in that thread become invalid. 10241 10242No static initialization may refer to the address of a thread-local variable. 10243 10244In C++, if an initializer is present for a thread-local variable, it must 10245be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ 10246standard. 10247 10248See @uref{http://people.redhat.com/drepper/tls.pdf, 10249ELF Handling For Thread-Local Storage} for a detailed explanation of 10250the four thread-local storage addressing models, and how the run-time 10251is expected to function. 10252 10253@menu 10254* C99 Thread-Local Edits:: 10255* C++98 Thread-Local Edits:: 10256@end menu 10257 10258@node C99 Thread-Local Edits 10259@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage 10260 10261The following are a set of changes to ISO/IEC 9899:1999 (aka C99) 10262that document the exact semantics of the language extension. 10263 10264@itemize @bullet 10265@item 10266@cite{5.1.2 Execution environments} 10267 10268Add new text after paragraph 1 10269 10270@quotation 10271Within either execution environment, a @dfn{thread} is a flow of 10272control within a program. It is implementation defined whether 10273or not there may be more than one thread associated with a program. 10274It is implementation defined how threads beyond the first are 10275created, the name and type of the function called at thread 10276startup, and how threads may be terminated. However, objects 10277with thread storage duration shall be initialized before thread 10278startup. 10279@end quotation 10280 10281@item 10282@cite{6.2.4 Storage durations of objects} 10283 10284Add new text before paragraph 3 10285 10286@quotation 10287An object whose identifier is declared with the storage-class 10288specifier @w{@code{__thread}} has @dfn{thread storage duration}. 10289Its lifetime is the entire execution of the thread, and its 10290stored value is initialized only once, prior to thread startup. 10291@end quotation 10292 10293@item 10294@cite{6.4.1 Keywords} 10295 10296Add @code{__thread}. 10297 10298@item 10299@cite{6.7.1 Storage-class specifiers} 10300 10301Add @code{__thread} to the list of storage class specifiers in 10302paragraph 1. 10303 10304Change paragraph 2 to 10305 10306@quotation 10307With the exception of @code{__thread}, at most one storage-class 10308specifier may be given [@dots{}]. The @code{__thread} specifier may 10309be used alone, or immediately following @code{extern} or 10310@code{static}. 10311@end quotation 10312 10313Add new text after paragraph 6 10314 10315@quotation 10316The declaration of an identifier for a variable that has 10317block scope that specifies @code{__thread} shall also 10318specify either @code{extern} or @code{static}. 10319 10320The @code{__thread} specifier shall be used only with 10321variables. 10322@end quotation 10323@end itemize 10324 10325@node C++98 Thread-Local Edits 10326@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage 10327 10328The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) 10329that document the exact semantics of the language extension. 10330 10331@itemize @bullet 10332@item 10333@b{[intro.execution]} 10334 10335New text after paragraph 4 10336 10337@quotation 10338A @dfn{thread} is a flow of control within the abstract machine. 10339It is implementation defined whether or not there may be more than 10340one thread. 10341@end quotation 10342 10343New text after paragraph 7 10344 10345@quotation 10346It is unspecified whether additional action must be taken to 10347ensure when and whether side effects are visible to other threads. 10348@end quotation 10349 10350@item 10351@b{[lex.key]} 10352 10353Add @code{__thread}. 10354 10355@item 10356@b{[basic.start.main]} 10357 10358Add after paragraph 5 10359 10360@quotation 10361The thread that begins execution at the @code{main} function is called 10362the @dfn{main thread}. It is implementation defined how functions 10363beginning threads other than the main thread are designated or typed. 10364A function so designated, as well as the @code{main} function, is called 10365a @dfn{thread startup function}. It is implementation defined what 10366happens if a thread startup function returns. It is implementation 10367defined what happens to other threads when any thread calls @code{exit}. 10368@end quotation 10369 10370@item 10371@b{[basic.start.init]} 10372 10373Add after paragraph 4 10374 10375@quotation 10376The storage for an object of thread storage duration shall be 10377statically initialized before the first statement of the thread startup 10378function. An object of thread storage duration shall not require 10379dynamic initialization. 10380@end quotation 10381 10382@item 10383@b{[basic.start.term]} 10384 10385Add after paragraph 3 10386 10387@quotation 10388The type of an object with thread storage duration shall not have a 10389non-trivial destructor, nor shall it be an array type whose elements 10390(directly or indirectly) have non-trivial destructors. 10391@end quotation 10392 10393@item 10394@b{[basic.stc]} 10395 10396Add ``thread storage duration'' to the list in paragraph 1. 10397 10398Change paragraph 2 10399 10400@quotation 10401Thread, static, and automatic storage durations are associated with 10402objects introduced by declarations [@dots{}]. 10403@end quotation 10404 10405Add @code{__thread} to the list of specifiers in paragraph 3. 10406 10407@item 10408@b{[basic.stc.thread]} 10409 10410New section before @b{[basic.stc.static]} 10411 10412@quotation 10413The keyword @code{__thread} applied to a non-local object gives the 10414object thread storage duration. 10415 10416A local variable or class data member declared both @code{static} 10417and @code{__thread} gives the variable or member thread storage 10418duration. 10419@end quotation 10420 10421@item 10422@b{[basic.stc.static]} 10423 10424Change paragraph 1 10425 10426@quotation 10427All objects which have neither thread storage duration, dynamic 10428storage duration nor are local [@dots{}]. 10429@end quotation 10430 10431@item 10432@b{[dcl.stc]} 10433 10434Add @code{__thread} to the list in paragraph 1. 10435 10436Change paragraph 1 10437 10438@quotation 10439With the exception of @code{__thread}, at most one 10440@var{storage-class-specifier} shall appear in a given 10441@var{decl-specifier-seq}. The @code{__thread} specifier may 10442be used alone, or immediately following the @code{extern} or 10443@code{static} specifiers. [@dots{}] 10444@end quotation 10445 10446Add after paragraph 5 10447 10448@quotation 10449The @code{__thread} specifier can be applied only to the names of objects 10450and to anonymous unions. 10451@end quotation 10452 10453@item 10454@b{[class.mem]} 10455 10456Add after paragraph 6 10457 10458@quotation 10459Non-@code{static} members shall not be @code{__thread}. 10460@end quotation 10461@end itemize 10462 10463@node Binary constants 10464@section Binary constants using the @samp{0b} prefix 10465@cindex Binary constants using the @samp{0b} prefix 10466 10467Integer constants can be written as binary constants, consisting of a 10468sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or 10469@samp{0B}. This is particularly useful in environments that operate a 10470lot on the bit-level (like microcontrollers). 10471 10472The following statements are identical: 10473 10474@smallexample 10475i = 42; 10476i = 0x2a; 10477i = 052; 10478i = 0b101010; 10479@end smallexample 10480 10481The type of these constants follows the same rules as for octal or 10482hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} 10483can be applied. 10484 10485@node C++ Extensions 10486@chapter Extensions to the C++ Language 10487@cindex extensions, C++ language 10488@cindex C++ language extensions 10489 10490The GNU compiler provides these extensions to the C++ language (and you 10491can also use most of the C language extensions in your C++ programs). If you 10492want to write code that checks whether these features are available, you can 10493test for the GNU compiler the same way as for C programs: check for a 10494predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to 10495test specifically for GNU C++ (@pxref{Common Predefined Macros,, 10496Predefined Macros,cpp,The GNU C Preprocessor}). 10497 10498@menu 10499* Volatiles:: What constitutes an access to a volatile object. 10500* Restricted Pointers:: C99 restricted pointers and references. 10501* Vague Linkage:: Where G++ puts inlines, vtables and such. 10502* C++ Interface:: You can use a single C++ header file for both 10503 declarations and definitions. 10504* Template Instantiation:: Methods for ensuring that exactly one copy of 10505 each needed template instantiation is emitted. 10506* Bound member functions:: You can extract a function pointer to the 10507 method denoted by a @samp{->*} or @samp{.*} expression. 10508* C++ Attributes:: Variable, function, and type attributes for C++ only. 10509* Namespace Association:: Strong using-directives for namespace association. 10510* Java Exceptions:: Tweaking exception handling to work with Java. 10511* Deprecated Features:: Things will disappear from g++. 10512* Backwards Compatibility:: Compatibilities with earlier definitions of C++. 10513@end menu 10514 10515@node Volatiles 10516@section When is a Volatile Object Accessed? 10517@cindex accessing volatiles 10518@cindex volatile read 10519@cindex volatile write 10520@cindex volatile access 10521 10522Both the C and C++ standard have the concept of volatile objects. These 10523are normally accessed by pointers and used for accessing hardware. The 10524standards encourage compilers to refrain from optimizations concerning 10525accesses to volatile objects. The C standard leaves it implementation 10526defined as to what constitutes a volatile access. The C++ standard omits 10527to specify this, except to say that C++ should behave in a similar manner 10528to C with respect to volatiles, where possible. The minimum either 10529standard specifies is that at a sequence point all previous accesses to 10530volatile objects have stabilized and no subsequent accesses have 10531occurred. Thus an implementation is free to reorder and combine 10532volatile accesses which occur between sequence points, but cannot do so 10533for accesses across a sequence point. The use of volatiles does not 10534allow you to violate the restriction on updating objects multiple times 10535within a sequence point. 10536 10537@xref{Qualifiers implementation, , Volatile qualifier and the C compiler}. 10538 10539The behavior differs slightly between C and C++ in the non-obvious cases: 10540 10541@smallexample 10542volatile int *src = @var{somevalue}; 10543*src; 10544@end smallexample 10545 10546With C, such expressions are rvalues, and GCC interprets this either as a 10547read of the volatile object being pointed to or only as request to evaluate 10548the side-effects. The C++ standard specifies that such expressions do not 10549undergo lvalue to rvalue conversion, and that the type of the dereferenced 10550object may be incomplete. The C++ standard does not specify explicitly 10551that it is this lvalue to rvalue conversion which may be responsible for 10552causing an access. However, there is reason to believe that it is, 10553because otherwise certain simple expressions become undefined. However, 10554because it would surprise most programmers, G++ treats dereferencing a 10555pointer to volatile object of complete type when the value is unused as 10556GCC would do for an equivalent type in C. When the object has incomplete 10557type, G++ issues a warning; if you wish to force an error, you must 10558force a conversion to rvalue with, for instance, a static cast. 10559 10560When using a reference to volatile, G++ does not treat equivalent 10561expressions as accesses to volatiles, but instead issues a warning that 10562no volatile is accessed. The rationale for this is that otherwise it 10563becomes difficult to determine where volatile access occur, and not 10564possible to ignore the return value from functions returning volatile 10565references. Again, if you wish to force a read, cast the reference to 10566an rvalue. 10567 10568@node Restricted Pointers 10569@section Restricting Pointer Aliasing 10570@cindex restricted pointers 10571@cindex restricted references 10572@cindex restricted this pointer 10573 10574As with the C front end, G++ understands the C99 feature of restricted pointers, 10575specified with the @code{__restrict__}, or @code{__restrict} type 10576qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} 10577language flag, @code{restrict} is not a keyword in C++. 10578 10579In addition to allowing restricted pointers, you can specify restricted 10580references, which indicate that the reference is not aliased in the local 10581context. 10582 10583@smallexample 10584void fn (int *__restrict__ rptr, int &__restrict__ rref) 10585@{ 10586 /* @r{@dots{}} */ 10587@} 10588@end smallexample 10589 10590@noindent 10591In the body of @code{fn}, @var{rptr} points to an unaliased integer and 10592@var{rref} refers to a (different) unaliased integer. 10593 10594You may also specify whether a member function's @var{this} pointer is 10595unaliased by using @code{__restrict__} as a member function qualifier. 10596 10597@smallexample 10598void T::fn () __restrict__ 10599@{ 10600 /* @r{@dots{}} */ 10601@} 10602@end smallexample 10603 10604@noindent 10605Within the body of @code{T::fn}, @var{this} will have the effective 10606definition @code{T *__restrict__ const this}. Notice that the 10607interpretation of a @code{__restrict__} member function qualifier is 10608different to that of @code{const} or @code{volatile} qualifier, in that it 10609is applied to the pointer rather than the object. This is consistent with 10610other compilers which implement restricted pointers. 10611 10612As with all outermost parameter qualifiers, @code{__restrict__} is 10613ignored in function definition matching. This means you only need to 10614specify @code{__restrict__} in a function definition, rather than 10615in a function prototype as well. 10616 10617@node Vague Linkage 10618@section Vague Linkage 10619@cindex vague linkage 10620 10621There are several constructs in C++ which require space in the object 10622file but are not clearly tied to a single translation unit. We say that 10623these constructs have ``vague linkage''. Typically such constructs are 10624emitted wherever they are needed, though sometimes we can be more 10625clever. 10626 10627@table @asis 10628@item Inline Functions 10629Inline functions are typically defined in a header file which can be 10630included in many different compilations. Hopefully they can usually be 10631inlined, but sometimes an out-of-line copy is necessary, if the address 10632of the function is taken or if inlining fails. In general, we emit an 10633out-of-line copy in all translation units where one is needed. As an 10634exception, we only emit inline virtual functions with the vtable, since 10635it will always require a copy. 10636 10637Local static variables and string constants used in an inline function 10638are also considered to have vague linkage, since they must be shared 10639between all inlined and out-of-line instances of the function. 10640 10641@item VTables 10642@cindex vtable 10643C++ virtual functions are implemented in most compilers using a lookup 10644table, known as a vtable. The vtable contains pointers to the virtual 10645functions provided by a class, and each object of the class contains a 10646pointer to its vtable (or vtables, in some multiple-inheritance 10647situations). If the class declares any non-inline, non-pure virtual 10648functions, the first one is chosen as the ``key method'' for the class, 10649and the vtable is only emitted in the translation unit where the key 10650method is defined. 10651 10652@emph{Note:} If the chosen key method is later defined as inline, the 10653vtable will still be emitted in every translation unit which defines it. 10654Make sure that any inline virtuals are declared inline in the class 10655body, even if they are not defined there. 10656 10657@item type_info objects 10658@cindex type_info 10659@cindex RTTI 10660C++ requires information about types to be written out in order to 10661implement @samp{dynamic_cast}, @samp{typeid} and exception handling. 10662For polymorphic classes (classes with virtual functions), the type_info 10663object is written out along with the vtable so that @samp{dynamic_cast} 10664can determine the dynamic type of a class object at runtime. For all 10665other types, we write out the type_info object when it is used: when 10666applying @samp{typeid} to an expression, throwing an object, or 10667referring to a type in a catch clause or exception specification. 10668 10669@item Template Instantiations 10670Most everything in this section also applies to template instantiations, 10671but there are other options as well. 10672@xref{Template Instantiation,,Where's the Template?}. 10673 10674@end table 10675 10676When used with GNU ld version 2.8 or later on an ELF system such as 10677GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of 10678these constructs will be discarded at link time. This is known as 10679COMDAT support. 10680 10681On targets that don't support COMDAT, but do support weak symbols, GCC 10682will use them. This way one copy will override all the others, but 10683the unused copies will still take up space in the executable. 10684 10685For targets which do not support either COMDAT or weak symbols, 10686most entities with vague linkage will be emitted as local symbols to 10687avoid duplicate definition errors from the linker. This will not happen 10688for local statics in inlines, however, as having multiple copies will 10689almost certainly break things. 10690 10691@xref{C++ Interface,,Declarations and Definitions in One Header}, for 10692another way to control placement of these constructs. 10693 10694@node C++ Interface 10695@section #pragma interface and implementation 10696 10697@cindex interface and implementation headers, C++ 10698@cindex C++ interface and implementation headers 10699@cindex pragmas, interface and implementation 10700 10701@code{#pragma interface} and @code{#pragma implementation} provide the 10702user with a way of explicitly directing the compiler to emit entities 10703with vague linkage (and debugging information) in a particular 10704translation unit. 10705 10706@emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in 10707most cases, because of COMDAT support and the ``key method'' heuristic 10708mentioned in @ref{Vague Linkage}. Using them can actually cause your 10709program to grow due to unnecessary out-of-line copies of inline 10710functions. Currently (3.4) the only benefit of these 10711@code{#pragma}s is reduced duplication of debugging information, and 10712that should be addressed soon on DWARF 2 targets with the use of 10713COMDAT groups. 10714 10715@table @code 10716@item #pragma interface 10717@itemx #pragma interface "@var{subdir}/@var{objects}.h" 10718@kindex #pragma interface 10719Use this directive in @emph{header files} that define object classes, to save 10720space in most of the object files that use those classes. Normally, 10721local copies of certain information (backup copies of inline member 10722functions, debugging information, and the internal tables that implement 10723virtual functions) must be kept in each object file that includes class 10724definitions. You can use this pragma to avoid such duplication. When a 10725header file containing @samp{#pragma interface} is included in a 10726compilation, this auxiliary information will not be generated (unless 10727the main input source file itself uses @samp{#pragma implementation}). 10728Instead, the object files will contain references to be resolved at link 10729time. 10730 10731The second form of this directive is useful for the case where you have 10732multiple headers with the same name in different directories. If you 10733use this form, you must specify the same string to @samp{#pragma 10734implementation}. 10735 10736@item #pragma implementation 10737@itemx #pragma implementation "@var{objects}.h" 10738@kindex #pragma implementation 10739Use this pragma in a @emph{main input file}, when you want full output from 10740included header files to be generated (and made globally visible). The 10741included header file, in turn, should use @samp{#pragma interface}. 10742Backup copies of inline member functions, debugging information, and the 10743internal tables used to implement virtual functions are all generated in 10744implementation files. 10745 10746@cindex implied @code{#pragma implementation} 10747@cindex @code{#pragma implementation}, implied 10748@cindex naming convention, implementation headers 10749If you use @samp{#pragma implementation} with no argument, it applies to 10750an include file with the same basename@footnote{A file's @dfn{basename} 10751was the name stripped of all leading path information and of trailing 10752suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source 10753file. For example, in @file{allclass.cc}, giving just 10754@samp{#pragma implementation} 10755by itself is equivalent to @samp{#pragma implementation "allclass.h"}. 10756 10757In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as 10758an implementation file whenever you would include it from 10759@file{allclass.cc} even if you never specified @samp{#pragma 10760implementation}. This was deemed to be more trouble than it was worth, 10761however, and disabled. 10762 10763Use the string argument if you want a single implementation file to 10764include code from multiple header files. (You must also use 10765@samp{#include} to include the header file; @samp{#pragma 10766implementation} only specifies how to use the file---it doesn't actually 10767include it.) 10768 10769There is no way to split up the contents of a single header file into 10770multiple implementation files. 10771@end table 10772 10773@cindex inlining and C++ pragmas 10774@cindex C++ pragmas, effect on inlining 10775@cindex pragmas in C++, effect on inlining 10776@samp{#pragma implementation} and @samp{#pragma interface} also have an 10777effect on function inlining. 10778 10779If you define a class in a header file marked with @samp{#pragma 10780interface}, the effect on an inline function defined in that class is 10781similar to an explicit @code{extern} declaration---the compiler emits 10782no code at all to define an independent version of the function. Its 10783definition is used only for inlining with its callers. 10784 10785@opindex fno-implement-inlines 10786Conversely, when you include the same header file in a main source file 10787that declares it as @samp{#pragma implementation}, the compiler emits 10788code for the function itself; this defines a version of the function 10789that can be found via pointers (or by callers compiled without 10790inlining). If all calls to the function can be inlined, you can avoid 10791emitting the function by compiling with @option{-fno-implement-inlines}. 10792If any calls were not inlined, you will get linker errors. 10793 10794@node Template Instantiation 10795@section Where's the Template? 10796@cindex template instantiation 10797 10798C++ templates are the first language feature to require more 10799intelligence from the environment than one usually finds on a UNIX 10800system. Somehow the compiler and linker have to make sure that each 10801template instance occurs exactly once in the executable if it is needed, 10802and not at all otherwise. There are two basic approaches to this 10803problem, which are referred to as the Borland model and the Cfront model. 10804 10805@table @asis 10806@item Borland model 10807Borland C++ solved the template instantiation problem by adding the code 10808equivalent of common blocks to their linker; the compiler emits template 10809instances in each translation unit that uses them, and the linker 10810collapses them together. The advantage of this model is that the linker 10811only has to consider the object files themselves; there is no external 10812complexity to worry about. This disadvantage is that compilation time 10813is increased because the template code is being compiled repeatedly. 10814Code written for this model tends to include definitions of all 10815templates in the header file, since they must be seen to be 10816instantiated. 10817 10818@item Cfront model 10819The AT&T C++ translator, Cfront, solved the template instantiation 10820problem by creating the notion of a template repository, an 10821automatically maintained place where template instances are stored. A 10822more modern version of the repository works as follows: As individual 10823object files are built, the compiler places any template definitions and 10824instantiations encountered in the repository. At link time, the link 10825wrapper adds in the objects in the repository and compiles any needed 10826instances that were not previously emitted. The advantages of this 10827model are more optimal compilation speed and the ability to use the 10828system linker; to implement the Borland model a compiler vendor also 10829needs to replace the linker. The disadvantages are vastly increased 10830complexity, and thus potential for error; for some code this can be 10831just as transparent, but in practice it can been very difficult to build 10832multiple programs in one directory and one program in multiple 10833directories. Code written for this model tends to separate definitions 10834of non-inline member templates into a separate file, which should be 10835compiled separately. 10836@end table 10837 10838When used with GNU ld version 2.8 or later on an ELF system such as 10839GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the 10840Borland model. On other systems, G++ implements neither automatic 10841model. 10842 10843A future version of G++ will support a hybrid model whereby the compiler 10844will emit any instantiations for which the template definition is 10845included in the compile, and store template definitions and 10846instantiation context information into the object file for the rest. 10847The link wrapper will extract that information as necessary and invoke 10848the compiler to produce the remaining instantiations. The linker will 10849then combine duplicate instantiations. 10850 10851In the mean time, you have the following options for dealing with 10852template instantiations: 10853 10854@enumerate 10855@item 10856@opindex frepo 10857Compile your template-using code with @option{-frepo}. The compiler will 10858generate files with the extension @samp{.rpo} listing all of the 10859template instantiations used in the corresponding object files which 10860could be instantiated there; the link wrapper, @samp{collect2}, will 10861then update the @samp{.rpo} files to tell the compiler where to place 10862those instantiations and rebuild any affected object files. The 10863link-time overhead is negligible after the first pass, as the compiler 10864will continue to place the instantiations in the same files. 10865 10866This is your best option for application code written for the Borland 10867model, as it will just work. Code written for the Cfront model will 10868need to be modified so that the template definitions are available at 10869one or more points of instantiation; usually this is as simple as adding 10870@code{#include <tmethods.cc>} to the end of each template header. 10871 10872For library code, if you want the library to provide all of the template 10873instantiations it needs, just try to link all of its object files 10874together; the link will fail, but cause the instantiations to be 10875generated as a side effect. Be warned, however, that this may cause 10876conflicts if multiple libraries try to provide the same instantiations. 10877For greater control, use explicit instantiation as described in the next 10878option. 10879 10880@item 10881@opindex fno-implicit-templates 10882Compile your code with @option{-fno-implicit-templates} to disable the 10883implicit generation of template instances, and explicitly instantiate 10884all the ones you use. This approach requires more knowledge of exactly 10885which instances you need than do the others, but it's less 10886mysterious and allows greater control. You can scatter the explicit 10887instantiations throughout your program, perhaps putting them in the 10888translation units where the instances are used or the translation units 10889that define the templates themselves; you can put all of the explicit 10890instantiations you need into one big file; or you can create small files 10891like 10892 10893@smallexample 10894#include "Foo.h" 10895#include "Foo.cc" 10896 10897template class Foo<int>; 10898template ostream& operator << 10899 (ostream&, const Foo<int>&); 10900@end smallexample 10901 10902for each of the instances you need, and create a template instantiation 10903library from those. 10904 10905If you are using Cfront-model code, you can probably get away with not 10906using @option{-fno-implicit-templates} when compiling files that don't 10907@samp{#include} the member template definitions. 10908 10909If you use one big file to do the instantiations, you may want to 10910compile it without @option{-fno-implicit-templates} so you get all of the 10911instances required by your explicit instantiations (but not by any 10912other files) without having to specify them as well. 10913 10914G++ has extended the template instantiation syntax given in the ISO 10915standard to allow forward declaration of explicit instantiations 10916(with @code{extern}), instantiation of the compiler support data for a 10917template class (i.e.@: the vtable) without instantiating any of its 10918members (with @code{inline}), and instantiation of only the static data 10919members of a template class, without the support data or member 10920functions (with (@code{static}): 10921 10922@smallexample 10923extern template int max (int, int); 10924inline template class Foo<int>; 10925static template class Foo<int>; 10926@end smallexample 10927 10928@item 10929Do nothing. Pretend G++ does implement automatic instantiation 10930management. Code written for the Borland model will work fine, but 10931each translation unit will contain instances of each of the templates it 10932uses. In a large program, this can lead to an unacceptable amount of code 10933duplication. 10934@end enumerate 10935 10936@node Bound member functions 10937@section Extracting the function pointer from a bound pointer to member function 10938@cindex pmf 10939@cindex pointer to member function 10940@cindex bound pointer to member function 10941 10942In C++, pointer to member functions (PMFs) are implemented using a wide 10943pointer of sorts to handle all the possible call mechanisms; the PMF 10944needs to store information about how to adjust the @samp{this} pointer, 10945and if the function pointed to is virtual, where to find the vtable, and 10946where in the vtable to look for the member function. If you are using 10947PMFs in an inner loop, you should really reconsider that decision. If 10948that is not an option, you can extract the pointer to the function that 10949would be called for a given object/PMF pair and call it directly inside 10950the inner loop, to save a bit of time. 10951 10952Note that you will still be paying the penalty for the call through a 10953function pointer; on most modern architectures, such a call defeats the 10954branch prediction features of the CPU@. This is also true of normal 10955virtual function calls. 10956 10957The syntax for this extension is 10958 10959@smallexample 10960extern A a; 10961extern int (A::*fp)(); 10962typedef int (*fptr)(A *); 10963 10964fptr p = (fptr)(a.*fp); 10965@end smallexample 10966 10967For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), 10968no object is needed to obtain the address of the function. They can be 10969converted to function pointers directly: 10970 10971@smallexample 10972fptr p1 = (fptr)(&A::foo); 10973@end smallexample 10974 10975@opindex Wno-pmf-conversions 10976You must specify @option{-Wno-pmf-conversions} to use this extension. 10977 10978@node C++ Attributes 10979@section C++-Specific Variable, Function, and Type Attributes 10980 10981Some attributes only make sense for C++ programs. 10982 10983@table @code 10984@item init_priority (@var{priority}) 10985@cindex init_priority attribute 10986 10987 10988In Standard C++, objects defined at namespace scope are guaranteed to be 10989initialized in an order in strict accordance with that of their definitions 10990@emph{in a given translation unit}. No guarantee is made for initializations 10991across translation units. However, GNU C++ allows users to control the 10992order of initialization of objects defined at namespace scope with the 10993@code{init_priority} attribute by specifying a relative @var{priority}, 10994a constant integral expression currently bounded between 101 and 65535 10995inclusive. Lower numbers indicate a higher priority. 10996 10997In the following example, @code{A} would normally be created before 10998@code{B}, but the @code{init_priority} attribute has reversed that order: 10999 11000@smallexample 11001Some_Class A __attribute__ ((init_priority (2000))); 11002Some_Class B __attribute__ ((init_priority (543))); 11003@end smallexample 11004 11005@noindent 11006Note that the particular values of @var{priority} do not matter; only their 11007relative ordering. 11008 11009@item java_interface 11010@cindex java_interface attribute 11011 11012This type attribute informs C++ that the class is a Java interface. It may 11013only be applied to classes declared within an @code{extern "Java"} block. 11014Calls to methods declared in this interface will be dispatched using GCJ's 11015interface table mechanism, instead of regular virtual table dispatch. 11016 11017@end table 11018 11019See also @xref{Namespace Association}. 11020 11021@node Namespace Association 11022@section Namespace Association 11023 11024@strong{Caution:} The semantics of this extension are not fully 11025defined. Users should refrain from using this extension as its 11026semantics may change subtly over time. It is possible that this 11027extension will be removed in future versions of G++. 11028 11029A using-directive with @code{__attribute ((strong))} is stronger 11030than a normal using-directive in two ways: 11031 11032@itemize @bullet 11033@item 11034Templates from the used namespace can be specialized and explicitly 11035instantiated as though they were members of the using namespace. 11036 11037@item 11038The using namespace is considered an associated namespace of all 11039templates in the used namespace for purposes of argument-dependent 11040name lookup. 11041@end itemize 11042 11043The used namespace must be nested within the using namespace so that 11044normal unqualified lookup works properly. 11045 11046This is useful for composing a namespace transparently from 11047implementation namespaces. For example: 11048 11049@smallexample 11050namespace std @{ 11051 namespace debug @{ 11052 template <class T> struct A @{ @}; 11053 @} 11054 using namespace debug __attribute ((__strong__)); 11055 template <> struct A<int> @{ @}; // @r{ok to specialize} 11056 11057 template <class T> void f (A<T>); 11058@} 11059 11060int main() 11061@{ 11062 f (std::A<float>()); // @r{lookup finds} std::f 11063 f (std::A<int>()); 11064@} 11065@end smallexample 11066 11067@node Java Exceptions 11068@section Java Exceptions 11069 11070The Java language uses a slightly different exception handling model 11071from C++. Normally, GNU C++ will automatically detect when you are 11072writing C++ code that uses Java exceptions, and handle them 11073appropriately. However, if C++ code only needs to execute destructors 11074when Java exceptions are thrown through it, GCC will guess incorrectly. 11075Sample problematic code is: 11076 11077@smallexample 11078 struct S @{ ~S(); @}; 11079 extern void bar(); // @r{is written in Java, and may throw exceptions} 11080 void foo() 11081 @{ 11082 S s; 11083 bar(); 11084 @} 11085@end smallexample 11086 11087@noindent 11088The usual effect of an incorrect guess is a link failure, complaining of 11089a missing routine called @samp{__gxx_personality_v0}. 11090 11091You can inform the compiler that Java exceptions are to be used in a 11092translation unit, irrespective of what it might think, by writing 11093@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This 11094@samp{#pragma} must appear before any functions that throw or catch 11095exceptions, or run destructors when exceptions are thrown through them. 11096 11097You cannot mix Java and C++ exceptions in the same translation unit. It 11098is believed to be safe to throw a C++ exception from one file through 11099another file compiled for the Java exception model, or vice versa, but 11100there may be bugs in this area. 11101 11102@node Deprecated Features 11103@section Deprecated Features 11104 11105In the past, the GNU C++ compiler was extended to experiment with new 11106features, at a time when the C++ language was still evolving. Now that 11107the C++ standard is complete, some of those features are superseded by 11108superior alternatives. Using the old features might cause a warning in 11109some cases that the feature will be dropped in the future. In other 11110cases, the feature might be gone already. 11111 11112While the list below is not exhaustive, it documents some of the options 11113that are now deprecated: 11114 11115@table @code 11116@item -fexternal-templates 11117@itemx -falt-external-templates 11118These are two of the many ways for G++ to implement template 11119instantiation. @xref{Template Instantiation}. The C++ standard clearly 11120defines how template definitions have to be organized across 11121implementation units. G++ has an implicit instantiation mechanism that 11122should work just fine for standard-conforming code. 11123 11124@item -fstrict-prototype 11125@itemx -fno-strict-prototype 11126Previously it was possible to use an empty prototype parameter list to 11127indicate an unspecified number of parameters (like C), rather than no 11128parameters, as C++ demands. This feature has been removed, except where 11129it is required for backwards compatibility @xref{Backwards Compatibility}. 11130@end table 11131 11132G++ allows a virtual function returning @samp{void *} to be overridden 11133by one returning a different pointer type. This extension to the 11134covariant return type rules is now deprecated and will be removed from a 11135future version. 11136 11137The G++ minimum and maximum operators (@samp{<?} and @samp{>?}) and 11138their compound forms (@samp{<?=}) and @samp{>?=}) have been deprecated 11139and will be removed in a future version. Code using these operators 11140should be modified to use @code{std::min} and @code{std::max} instead. 11141 11142The named return value extension has been deprecated, and is now 11143removed from G++. 11144 11145The use of initializer lists with new expressions has been deprecated, 11146and is now removed from G++. 11147 11148Floating and complex non-type template parameters have been deprecated, 11149and are now removed from G++. 11150 11151The implicit typename extension has been deprecated and is now 11152removed from G++. 11153 11154The use of default arguments in function pointers, function typedefs 11155and other places where they are not permitted by the standard is 11156deprecated and will be removed from a future version of G++. 11157 11158G++ allows floating-point literals to appear in integral constant expressions, 11159e.g. @samp{ enum E @{ e = int(2.2 * 3.7) @} } 11160This extension is deprecated and will be removed from a future version. 11161 11162G++ allows static data members of const floating-point type to be declared 11163with an initializer in a class definition. The standard only allows 11164initializers for static members of const integral types and const 11165enumeration types so this extension has been deprecated and will be removed 11166from a future version. 11167 11168@node Backwards Compatibility 11169@section Backwards Compatibility 11170@cindex Backwards Compatibility 11171@cindex ARM [Annotated C++ Reference Manual] 11172 11173Now that there is a definitive ISO standard C++, G++ has a specification 11174to adhere to. The C++ language evolved over time, and features that 11175used to be acceptable in previous drafts of the standard, such as the ARM 11176[Annotated C++ Reference Manual], are no longer accepted. In order to allow 11177compilation of C++ written to such drafts, G++ contains some backwards 11178compatibilities. @emph{All such backwards compatibility features are 11179liable to disappear in future versions of G++.} They should be considered 11180deprecated @xref{Deprecated Features}. 11181 11182@table @code 11183@item For scope 11184If a variable is declared at for scope, it used to remain in scope until 11185the end of the scope which contained the for statement (rather than just 11186within the for scope). G++ retains this, but issues a warning, if such a 11187variable is accessed outside the for scope. 11188 11189@item Implicit C language 11190Old C system header files did not contain an @code{extern "C" @{@dots{}@}} 11191scope to set the language. On such systems, all header files are 11192implicitly scoped inside a C language scope. Also, an empty prototype 11193@code{()} will be treated as an unspecified number of arguments, rather 11194than no arguments, as C++ demands. 11195@end table 11196