extend.texi revision 237021
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@end menu 85 86@node Statement Exprs 87@section Statements and Declarations in Expressions 88@cindex statements inside expressions 89@cindex declarations inside expressions 90@cindex expressions containing statements 91@cindex macros, statements in expressions 92 93@c the above section title wrapped and causes an underfull hbox.. i 94@c changed it from "within" to "in". --mew 4feb93 95A compound statement enclosed in parentheses may appear as an expression 96in GNU C@. This allows you to use loops, switches, and local variables 97within an expression. 98 99Recall that a compound statement is a sequence of statements surrounded 100by braces; in this construct, parentheses go around the braces. For 101example: 102 103@smallexample 104(@{ int y = foo (); int z; 105 if (y > 0) z = y; 106 else z = - y; 107 z; @}) 108@end smallexample 109 110@noindent 111is a valid (though slightly more complex than necessary) expression 112for the absolute value of @code{foo ()}. 113 114The last thing in the compound statement should be an expression 115followed by a semicolon; the value of this subexpression serves as the 116value of the entire construct. (If you use some other kind of statement 117last within the braces, the construct has type @code{void}, and thus 118effectively no value.) 119 120This feature is especially useful in making macro definitions ``safe'' (so 121that they evaluate each operand exactly once). For example, the 122``maximum'' function is commonly defined as a macro in standard C as 123follows: 124 125@smallexample 126#define max(a,b) ((a) > (b) ? (a) : (b)) 127@end smallexample 128 129@noindent 130@cindex side effects, macro argument 131But this definition computes either @var{a} or @var{b} twice, with bad 132results if the operand has side effects. In GNU C, if you know the 133type of the operands (here taken as @code{int}), you can define 134the macro safely as follows: 135 136@smallexample 137#define maxint(a,b) \ 138 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) 139@end smallexample 140 141Embedded statements are not allowed in constant expressions, such as 142the value of an enumeration constant, the width of a bit-field, or 143the initial value of a static variable. 144 145If you don't know the type of the operand, you can still do this, but you 146must use @code{typeof} (@pxref{Typeof}). 147 148In G++, the result value of a statement expression undergoes array and 149function pointer decay, and is returned by value to the enclosing 150expression. For instance, if @code{A} is a class, then 151 152@smallexample 153 A a; 154 155 (@{a;@}).Foo () 156@end smallexample 157 158@noindent 159will construct a temporary @code{A} object to hold the result of the 160statement expression, and that will be used to invoke @code{Foo}. 161Therefore the @code{this} pointer observed by @code{Foo} will not be the 162address of @code{a}. 163 164Any temporaries created within a statement within a statement expression 165will be destroyed at the statement's end. This makes statement 166expressions inside macros slightly different from function calls. In 167the latter case temporaries introduced during argument evaluation will 168be destroyed at the end of the statement that includes the function 169call. In the statement expression case they will be destroyed during 170the statement expression. For instance, 171 172@smallexample 173#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) 174template<typename T> T function(T a) @{ T b = a; return b + 3; @} 175 176void foo () 177@{ 178 macro (X ()); 179 function (X ()); 180@} 181@end smallexample 182 183@noindent 184will have different places where temporaries are destroyed. For the 185@code{macro} case, the temporary @code{X} will be destroyed just after 186the initialization of @code{b}. In the @code{function} case that 187temporary will be destroyed when the function returns. 188 189These considerations mean that it is probably a bad idea to use 190statement-expressions of this form in header files that are designed to 191work with C++. (Note that some versions of the GNU C Library contained 192header files using statement-expression that lead to precisely this 193bug.) 194 195Jumping into a statement expression with @code{goto} or using a 196@code{switch} statement outside the statement expression with a 197@code{case} or @code{default} label inside the statement expression is 198not permitted. Jumping into a statement expression with a computed 199@code{goto} (@pxref{Labels as Values}) yields undefined behavior. 200Jumping out of a statement expression is permitted, but if the 201statement expression is part of a larger expression then it is 202unspecified which other subexpressions of that expression have been 203evaluated except where the language definition requires certain 204subexpressions to be evaluated before or after the statement 205expression. In any case, as with a function call the evaluation of a 206statement expression is not interleaved with the evaluation of other 207parts of the containing expression. For example, 208 209@smallexample 210 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); 211@end smallexample 212 213@noindent 214will call @code{foo} and @code{bar1} and will not call @code{baz} but 215may or may not call @code{bar2}. If @code{bar2} is called, it will be 216called after @code{foo} and before @code{bar1} 217 218@node Local Labels 219@section Locally Declared Labels 220@cindex local labels 221@cindex macros, local labels 222 223GCC allows you to declare @dfn{local labels} in any nested block 224scope. A local label is just like an ordinary label, but you can 225only reference it (with a @code{goto} statement, or by taking its 226address) within the block in which it was declared. 227 228A local label declaration looks like this: 229 230@smallexample 231__label__ @var{label}; 232@end smallexample 233 234@noindent 235or 236 237@smallexample 238__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; 239@end smallexample 240 241Local label declarations must come at the beginning of the block, 242before any ordinary declarations or statements. 243 244The label declaration defines the label @emph{name}, but does not define 245the label itself. You must do this in the usual way, with 246@code{@var{label}:}, within the statements of the statement expression. 247 248The local label feature is useful for complex macros. If a macro 249contains nested loops, a @code{goto} can be useful for breaking out of 250them. However, an ordinary label whose scope is the whole function 251cannot be used: if the macro can be expanded several times in one 252function, the label will be multiply defined in that function. A 253local label avoids this problem. For example: 254 255@smallexample 256#define SEARCH(value, array, target) \ 257do @{ \ 258 __label__ found; \ 259 typeof (target) _SEARCH_target = (target); \ 260 typeof (*(array)) *_SEARCH_array = (array); \ 261 int i, j; \ 262 int value; \ 263 for (i = 0; i < max; i++) \ 264 for (j = 0; j < max; j++) \ 265 if (_SEARCH_array[i][j] == _SEARCH_target) \ 266 @{ (value) = i; goto found; @} \ 267 (value) = -1; \ 268 found:; \ 269@} while (0) 270@end smallexample 271 272This could also be written using a statement-expression: 273 274@smallexample 275#define SEARCH(array, target) \ 276(@{ \ 277 __label__ found; \ 278 typeof (target) _SEARCH_target = (target); \ 279 typeof (*(array)) *_SEARCH_array = (array); \ 280 int i, j; \ 281 int value; \ 282 for (i = 0; i < max; i++) \ 283 for (j = 0; j < max; j++) \ 284 if (_SEARCH_array[i][j] == _SEARCH_target) \ 285 @{ value = i; goto found; @} \ 286 value = -1; \ 287 found: \ 288 value; \ 289@}) 290@end smallexample 291 292Local label declarations also make the labels they declare visible to 293nested functions, if there are any. @xref{Nested Functions}, for details. 294 295@node Labels as Values 296@section Labels as Values 297@cindex labels as values 298@cindex computed gotos 299@cindex goto with computed label 300@cindex address of a label 301 302You can get the address of a label defined in the current function 303(or a containing function) with the unary operator @samp{&&}. The 304value has type @code{void *}. This value is a constant and can be used 305wherever a constant of that type is valid. For example: 306 307@smallexample 308void *ptr; 309/* @r{@dots{}} */ 310ptr = &&foo; 311@end smallexample 312 313To use these values, you need to be able to jump to one. This is done 314with the computed goto statement@footnote{The analogous feature in 315Fortran is called an assigned goto, but that name seems inappropriate in 316C, where one can do more than simply store label addresses in label 317variables.}, @code{goto *@var{exp};}. For example, 318 319@smallexample 320goto *ptr; 321@end smallexample 322 323@noindent 324Any expression of type @code{void *} is allowed. 325 326One way of using these constants is in initializing a static array that 327will serve as a jump table: 328 329@smallexample 330static void *array[] = @{ &&foo, &&bar, &&hack @}; 331@end smallexample 332 333Then you can select a label with indexing, like this: 334 335@smallexample 336goto *array[i]; 337@end smallexample 338 339@noindent 340Note that this does not check whether the subscript is in bounds---array 341indexing in C never does that. 342 343Such an array of label values serves a purpose much like that of the 344@code{switch} statement. The @code{switch} statement is cleaner, so 345use that rather than an array unless the problem does not fit a 346@code{switch} statement very well. 347 348Another use of label values is in an interpreter for threaded code. 349The labels within the interpreter function can be stored in the 350threaded code for super-fast dispatching. 351 352You may not use this mechanism to jump to code in a different function. 353If you do that, totally unpredictable things will happen. The best way to 354avoid this is to store the label address only in automatic variables and 355never pass it as an argument. 356 357An alternate way to write the above example is 358 359@smallexample 360static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, 361 &&hack - &&foo @}; 362goto *(&&foo + array[i]); 363@end smallexample 364 365@noindent 366This is more friendly to code living in shared libraries, as it reduces 367the number of dynamic relocations that are needed, and by consequence, 368allows the data to be read-only. 369 370@node Nested Functions 371@section Nested Functions 372@cindex nested functions 373@cindex downward funargs 374@cindex thunks 375 376A @dfn{nested function} is a function defined inside another function. 377(Nested functions are not supported for GNU C++.) The nested function's 378name is local to the block where it is defined. For example, here we 379define a nested function named @code{square}, and call it twice: 380 381@smallexample 382@group 383foo (double a, double b) 384@{ 385 double square (double z) @{ return z * z; @} 386 387 return square (a) + square (b); 388@} 389@end group 390@end smallexample 391 392The nested function can access all the variables of the containing 393function that are visible at the point of its definition. This is 394called @dfn{lexical scoping}. For example, here we show a nested 395function which uses an inherited variable named @code{offset}: 396 397@smallexample 398@group 399bar (int *array, int offset, int size) 400@{ 401 int access (int *array, int index) 402 @{ return array[index + offset]; @} 403 int i; 404 /* @r{@dots{}} */ 405 for (i = 0; i < size; i++) 406 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 407@} 408@end group 409@end smallexample 410 411Nested function definitions are permitted within functions in the places 412where variable definitions are allowed; that is, in any block, mixed 413with the other declarations and statements in the block. 414 415It is possible to call the nested function from outside the scope of its 416name by storing its address or passing the address to another function: 417 418@smallexample 419hack (int *array, int size) 420@{ 421 void store (int index, int value) 422 @{ array[index] = value; @} 423 424 intermediate (store, size); 425@} 426@end smallexample 427 428Here, the function @code{intermediate} receives the address of 429@code{store} as an argument. If @code{intermediate} calls @code{store}, 430the arguments given to @code{store} are used to store into @code{array}. 431But this technique works only so long as the containing function 432(@code{hack}, in this example) does not exit. 433 434If you try to call the nested function through its address after the 435containing function has exited, all hell will break loose. If you try 436to call it after a containing scope level has exited, and if it refers 437to some of the variables that are no longer in scope, you may be lucky, 438but it's not wise to take the risk. If, however, the nested function 439does not refer to anything that has gone out of scope, you should be 440safe. 441 442GCC implements taking the address of a nested function using a technique 443called @dfn{trampolines}. A paper describing them is available as 444 445@noindent 446@uref{http://people.debian.org/~aaronl/Usenix88-lexic.pdf}. 447 448A nested function can jump to a label inherited from a containing 449function, provided the label was explicitly declared in the containing 450function (@pxref{Local Labels}). Such a jump returns instantly to the 451containing function, exiting the nested function which did the 452@code{goto} and any intermediate functions as well. Here is an example: 453 454@smallexample 455@group 456bar (int *array, int offset, int size) 457@{ 458 __label__ failure; 459 int access (int *array, int index) 460 @{ 461 if (index > size) 462 goto failure; 463 return array[index + offset]; 464 @} 465 int i; 466 /* @r{@dots{}} */ 467 for (i = 0; i < size; i++) 468 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 469 /* @r{@dots{}} */ 470 return 0; 471 472 /* @r{Control comes here from @code{access} 473 if it detects an error.} */ 474 failure: 475 return -1; 476@} 477@end group 478@end smallexample 479 480A nested function always has no linkage. Declaring one with 481@code{extern} or @code{static} is erroneous. If you need to declare the nested function 482before its definition, use @code{auto} (which is otherwise meaningless 483for function declarations). 484 485@smallexample 486bar (int *array, int offset, int size) 487@{ 488 __label__ failure; 489 auto int access (int *, int); 490 /* @r{@dots{}} */ 491 int access (int *array, int index) 492 @{ 493 if (index > size) 494 goto failure; 495 return array[index + offset]; 496 @} 497 /* @r{@dots{}} */ 498@} 499@end smallexample 500 501@node Constructing Calls 502@section Constructing Function Calls 503@cindex constructing calls 504@cindex forwarding calls 505 506Using the built-in functions described below, you can record 507the arguments a function received, and call another function 508with the same arguments, without knowing the number or types 509of the arguments. 510 511You can also record the return value of that function call, 512and later return that value, without knowing what data type 513the function tried to return (as long as your caller expects 514that data type). 515 516However, these built-in functions may interact badly with some 517sophisticated features or other extensions of the language. It 518is, therefore, not recommended to use them outside very simple 519functions acting as mere forwarders for their arguments. 520 521@deftypefn {Built-in Function} {void *} __builtin_apply_args () 522This built-in function returns a pointer to data 523describing how to perform a call with the same arguments as were passed 524to the current function. 525 526The function saves the arg pointer register, structure value address, 527and all registers that might be used to pass arguments to a function 528into a block of memory allocated on the stack. Then it returns the 529address of that block. 530@end deftypefn 531 532@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) 533This built-in function invokes @var{function} 534with a copy of the parameters described by @var{arguments} 535and @var{size}. 536 537The value of @var{arguments} should be the value returned by 538@code{__builtin_apply_args}. The argument @var{size} specifies the size 539of the stack argument data, in bytes. 540 541This function returns a pointer to data describing 542how to return whatever value was returned by @var{function}. The data 543is saved in a block of memory allocated on the stack. 544 545It is not always simple to compute the proper value for @var{size}. The 546value is used by @code{__builtin_apply} to compute the amount of data 547that should be pushed on the stack and copied from the incoming argument 548area. 549@end deftypefn 550 551@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) 552This built-in function returns the value described by @var{result} from 553the containing function. You should specify, for @var{result}, a value 554returned by @code{__builtin_apply}. 555@end deftypefn 556 557@node Typeof 558@section Referring to a Type with @code{typeof} 559@findex typeof 560@findex sizeof 561@cindex macros, types of arguments 562 563Another way to refer to the type of an expression is with @code{typeof}. 564The syntax of using of this keyword looks like @code{sizeof}, but the 565construct acts semantically like a type name defined with @code{typedef}. 566 567There are two ways of writing the argument to @code{typeof}: with an 568expression or with a type. Here is an example with an expression: 569 570@smallexample 571typeof (x[0](1)) 572@end smallexample 573 574@noindent 575This assumes that @code{x} is an array of pointers to functions; 576the type described is that of the values of the functions. 577 578Here is an example with a typename as the argument: 579 580@smallexample 581typeof (int *) 582@end smallexample 583 584@noindent 585Here the type described is that of pointers to @code{int}. 586 587If you are writing a header file that must work when included in ISO C 588programs, write @code{__typeof__} instead of @code{typeof}. 589@xref{Alternate Keywords}. 590 591A @code{typeof}-construct can be used anywhere a typedef name could be 592used. For example, you can use it in a declaration, in a cast, or inside 593of @code{sizeof} or @code{typeof}. 594 595@code{typeof} is often useful in conjunction with the 596statements-within-expressions feature. Here is how the two together can 597be used to define a safe ``maximum'' macro that operates on any 598arithmetic type and evaluates each of its arguments exactly once: 599 600@smallexample 601#define max(a,b) \ 602 (@{ typeof (a) _a = (a); \ 603 typeof (b) _b = (b); \ 604 _a > _b ? _a : _b; @}) 605@end smallexample 606 607@cindex underscores in variables in macros 608@cindex @samp{_} in variables in macros 609@cindex local variables in macros 610@cindex variables, local, in macros 611@cindex macros, local variables in 612 613The reason for using names that start with underscores for the local 614variables is to avoid conflicts with variable names that occur within the 615expressions that are substituted for @code{a} and @code{b}. Eventually we 616hope to design a new form of declaration syntax that allows you to declare 617variables whose scopes start only after their initializers; this will be a 618more reliable way to prevent such conflicts. 619 620@noindent 621Some more examples of the use of @code{typeof}: 622 623@itemize @bullet 624@item 625This declares @code{y} with the type of what @code{x} points to. 626 627@smallexample 628typeof (*x) y; 629@end smallexample 630 631@item 632This declares @code{y} as an array of such values. 633 634@smallexample 635typeof (*x) y[4]; 636@end smallexample 637 638@item 639This declares @code{y} as an array of pointers to characters: 640 641@smallexample 642typeof (typeof (char *)[4]) y; 643@end smallexample 644 645@noindent 646It is equivalent to the following traditional C declaration: 647 648@smallexample 649char *y[4]; 650@end smallexample 651 652To see the meaning of the declaration using @code{typeof}, and why it 653might be a useful way to write, rewrite it with these macros: 654 655@smallexample 656#define pointer(T) typeof(T *) 657#define array(T, N) typeof(T [N]) 658@end smallexample 659 660@noindent 661Now the declaration can be rewritten this way: 662 663@smallexample 664array (pointer (char), 4) y; 665@end smallexample 666 667@noindent 668Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 669pointers to @code{char}. 670@end itemize 671 672@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported 673a more limited extension which permitted one to write 674 675@smallexample 676typedef @var{T} = @var{expr}; 677@end smallexample 678 679@noindent 680with the effect of declaring @var{T} to have the type of the expression 681@var{expr}. This extension does not work with GCC 3 (versions between 6823.0 and 3.2 will crash; 3.2.1 and later give an error). Code which 683relies on it should be rewritten to use @code{typeof}: 684 685@smallexample 686typedef typeof(@var{expr}) @var{T}; 687@end smallexample 688 689@noindent 690This will work with all versions of GCC@. 691 692@node Conditionals 693@section Conditionals with Omitted Operands 694@cindex conditional expressions, extensions 695@cindex omitted middle-operands 696@cindex middle-operands, omitted 697@cindex extensions, @code{?:} 698@cindex @code{?:} extensions 699 700The middle operand in a conditional expression may be omitted. Then 701if the first operand is nonzero, its value is the value of the conditional 702expression. 703 704Therefore, the expression 705 706@smallexample 707x ? : y 708@end smallexample 709 710@noindent 711has the value of @code{x} if that is nonzero; otherwise, the value of 712@code{y}. 713 714This example is perfectly equivalent to 715 716@smallexample 717x ? x : y 718@end smallexample 719 720@cindex side effect in ?: 721@cindex ?: side effect 722@noindent 723In this simple case, the ability to omit the middle operand is not 724especially useful. When it becomes useful is when the first operand does, 725or may (if it is a macro argument), contain a side effect. Then repeating 726the operand in the middle would perform the side effect twice. Omitting 727the middle operand uses the value already computed without the undesirable 728effects of recomputing it. 729 730@node Long Long 731@section Double-Word Integers 732@cindex @code{long long} data types 733@cindex double-word arithmetic 734@cindex multiprecision arithmetic 735@cindex @code{LL} integer suffix 736@cindex @code{ULL} integer suffix 737 738ISO C99 supports data types for integers that are at least 64 bits wide, 739and as an extension GCC supports them in C89 mode and in C++. 740Simply write @code{long long int} for a signed integer, or 741@code{unsigned long long int} for an unsigned integer. To make an 742integer constant of type @code{long long int}, add the suffix @samp{LL} 743to the integer. To make an integer constant of type @code{unsigned long 744long int}, add the suffix @samp{ULL} to the integer. 745 746You can use these types in arithmetic like any other integer types. 747Addition, subtraction, and bitwise boolean operations on these types 748are open-coded on all types of machines. Multiplication is open-coded 749if the machine supports fullword-to-doubleword a widening multiply 750instruction. Division and shifts are open-coded only on machines that 751provide special support. The operations that are not open-coded use 752special library routines that come with GCC@. 753 754There may be pitfalls when you use @code{long long} types for function 755arguments, unless you declare function prototypes. If a function 756expects type @code{int} for its argument, and you pass a value of type 757@code{long long int}, confusion will result because the caller and the 758subroutine will disagree about the number of bytes for the argument. 759Likewise, if the function expects @code{long long int} and you pass 760@code{int}. The best way to avoid such problems is to use prototypes. 761 762@node Complex 763@section Complex Numbers 764@cindex complex numbers 765@cindex @code{_Complex} keyword 766@cindex @code{__complex__} keyword 767 768ISO C99 supports complex floating data types, and as an extension GCC 769supports them in C89 mode and in C++, and supports complex integer data 770types which are not part of ISO C99. You can declare complex types 771using the keyword @code{_Complex}. As an extension, the older GNU 772keyword @code{__complex__} is also supported. 773 774For example, @samp{_Complex double x;} declares @code{x} as a 775variable whose real part and imaginary part are both of type 776@code{double}. @samp{_Complex short int y;} declares @code{y} to 777have real and imaginary parts of type @code{short int}; this is not 778likely to be useful, but it shows that the set of complex types is 779complete. 780 781To write a constant with a complex data type, use the suffix @samp{i} or 782@samp{j} (either one; they are equivalent). For example, @code{2.5fi} 783has type @code{_Complex float} and @code{3i} has type 784@code{_Complex int}. Such a constant always has a pure imaginary 785value, but you can form any complex value you like by adding one to a 786real constant. This is a GNU extension; if you have an ISO C99 787conforming C library (such as GNU libc), and want to construct complex 788constants of floating type, you should include @code{<complex.h>} and 789use the macros @code{I} or @code{_Complex_I} instead. 790 791@cindex @code{__real__} keyword 792@cindex @code{__imag__} keyword 793To extract the real part of a complex-valued expression @var{exp}, write 794@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to 795extract the imaginary part. This is a GNU extension; for values of 796floating type, you should use the ISO C99 functions @code{crealf}, 797@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and 798@code{cimagl}, declared in @code{<complex.h>} and also provided as 799built-in functions by GCC@. 800 801@cindex complex conjugation 802The operator @samp{~} performs complex conjugation when used on a value 803with a complex type. This is a GNU extension; for values of 804floating type, you should use the ISO C99 functions @code{conjf}, 805@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also 806provided as built-in functions by GCC@. 807 808GCC can allocate complex automatic variables in a noncontiguous 809fashion; it's even possible for the real part to be in a register while 810the imaginary part is on the stack (or vice-versa). Only the DWARF2 811debug info format can represent this, so use of DWARF2 is recommended. 812If you are using the stabs debug info format, GCC describes a noncontiguous 813complex variable as if it were two separate variables of noncomplex type. 814If the variable's actual name is @code{foo}, the two fictitious 815variables are named @code{foo$real} and @code{foo$imag}. You can 816examine and set these two fictitious variables with your debugger. 817 818@node Decimal Float 819@section Decimal Floating Types 820@cindex decimal floating types 821@cindex @code{_Decimal32} data type 822@cindex @code{_Decimal64} data type 823@cindex @code{_Decimal128} data type 824@cindex @code{df} integer suffix 825@cindex @code{dd} integer suffix 826@cindex @code{dl} integer suffix 827@cindex @code{DF} integer suffix 828@cindex @code{DD} integer suffix 829@cindex @code{DL} integer suffix 830 831As an extension, the GNU C compiler supports decimal floating types as 832defined in the N1176 draft of ISO/IEC WDTR24732. Support for decimal 833floating types in GCC will evolve as the draft technical report changes. 834Calling conventions for any target might also change. Not all targets 835support decimal floating types. 836 837The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and 838@code{_Decimal128}. They use a radix of ten, unlike the floating types 839@code{float}, @code{double}, and @code{long double} whose radix is not 840specified by the C standard but is usually two. 841 842Support for decimal floating types includes the arithmetic operators 843add, subtract, multiply, divide; unary arithmetic operators; 844relational operators; equality operators; and conversions to and from 845integer and other floating types. Use a suffix @samp{df} or 846@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} 847or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for 848@code{_Decimal128}. 849 850GCC support of decimal float as specified by the draft technical report 851is incomplete: 852 853@itemize @bullet 854@item 855Translation time data type (TTDT) is not supported. 856 857@item 858Characteristics of decimal floating types are defined in header file 859@file{decfloat.h} rather than @file{float.h}. 860 861@item 862When the value of a decimal floating type cannot be represented in the 863integer type to which it is being converted, the result is undefined 864rather than the result value specified by the draft technical report. 865@end itemize 866 867Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} 868are supported by the DWARF2 debug information format. 869 870@node Hex Floats 871@section Hex Floats 872@cindex hex floats 873 874ISO C99 supports floating-point numbers written not only in the usual 875decimal notation, such as @code{1.55e1}, but also numbers such as 876@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC 877supports this in C89 mode (except in some cases when strictly 878conforming) and in C++. In that format the 879@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are 880mandatory. The exponent is a decimal number that indicates the power of 8812 by which the significant part will be multiplied. Thus @samp{0x1.f} is 882@tex 883$1 {15\over16}$, 884@end tex 885@ifnottex 8861 15/16, 887@end ifnottex 888@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} 889is the same as @code{1.55e1}. 890 891Unlike for floating-point numbers in the decimal notation the exponent 892is always required in the hexadecimal notation. Otherwise the compiler 893would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This 894could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the 895extension for floating-point constants of type @code{float}. 896 897@node Zero Length 898@section Arrays of Length Zero 899@cindex arrays of length zero 900@cindex zero-length arrays 901@cindex length-zero arrays 902@cindex flexible array members 903 904Zero-length arrays are allowed in GNU C@. They are very useful as the 905last element of a structure which is really a header for a variable-length 906object: 907 908@smallexample 909struct line @{ 910 int length; 911 char contents[0]; 912@}; 913 914struct line *thisline = (struct line *) 915 malloc (sizeof (struct line) + this_length); 916thisline->length = this_length; 917@end smallexample 918 919In ISO C90, you would have to give @code{contents} a length of 1, which 920means either you waste space or complicate the argument to @code{malloc}. 921 922In ISO C99, you would use a @dfn{flexible array member}, which is 923slightly different in syntax and semantics: 924 925@itemize @bullet 926@item 927Flexible array members are written as @code{contents[]} without 928the @code{0}. 929 930@item 931Flexible array members have incomplete type, and so the @code{sizeof} 932operator may not be applied. As a quirk of the original implementation 933of zero-length arrays, @code{sizeof} evaluates to zero. 934 935@item 936Flexible array members may only appear as the last member of a 937@code{struct} that is otherwise non-empty. 938 939@item 940A structure containing a flexible array member, or a union containing 941such a structure (possibly recursively), may not be a member of a 942structure or an element of an array. (However, these uses are 943permitted by GCC as extensions.) 944@end itemize 945 946GCC versions before 3.0 allowed zero-length arrays to be statically 947initialized, as if they were flexible arrays. In addition to those 948cases that were useful, it also allowed initializations in situations 949that would corrupt later data. Non-empty initialization of zero-length 950arrays is now treated like any case where there are more initializer 951elements than the array holds, in that a suitable warning about "excess 952elements in array" is given, and the excess elements (all of them, in 953this case) are ignored. 954 955Instead GCC allows static initialization of flexible array members. 956This is equivalent to defining a new structure containing the original 957structure followed by an array of sufficient size to contain the data. 958I.e.@: in the following, @code{f1} is constructed as if it were declared 959like @code{f2}. 960 961@smallexample 962struct f1 @{ 963 int x; int y[]; 964@} f1 = @{ 1, @{ 2, 3, 4 @} @}; 965 966struct f2 @{ 967 struct f1 f1; int data[3]; 968@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; 969@end smallexample 970 971@noindent 972The convenience of this extension is that @code{f1} has the desired 973type, eliminating the need to consistently refer to @code{f2.f1}. 974 975This has symmetry with normal static arrays, in that an array of 976unknown size is also written with @code{[]}. 977 978Of course, this extension only makes sense if the extra data comes at 979the end of a top-level object, as otherwise we would be overwriting 980data at subsequent offsets. To avoid undue complication and confusion 981with initialization of deeply nested arrays, we simply disallow any 982non-empty initialization except when the structure is the top-level 983object. For example: 984 985@smallexample 986struct foo @{ int x; int y[]; @}; 987struct bar @{ struct foo z; @}; 988 989struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} 990struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 991struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} 992struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 993@end smallexample 994 995@node Empty Structures 996@section Structures With No Members 997@cindex empty structures 998@cindex zero-size structures 999 1000GCC permits a C structure to have no members: 1001 1002@smallexample 1003struct empty @{ 1004@}; 1005@end smallexample 1006 1007The structure will have size zero. In C++, empty structures are part 1008of the language. G++ treats empty structures as if they had a single 1009member of type @code{char}. 1010 1011@node Variable Length 1012@section Arrays of Variable Length 1013@cindex variable-length arrays 1014@cindex arrays of variable length 1015@cindex VLAs 1016 1017Variable-length automatic arrays are allowed in ISO C99, and as an 1018extension GCC accepts them in C89 mode and in C++. (However, GCC's 1019implementation of variable-length arrays does not yet conform in detail 1020to the ISO C99 standard.) These arrays are 1021declared like any other automatic arrays, but with a length that is not 1022a constant expression. The storage is allocated at the point of 1023declaration and deallocated when the brace-level is exited. For 1024example: 1025 1026@smallexample 1027FILE * 1028concat_fopen (char *s1, char *s2, char *mode) 1029@{ 1030 char str[strlen (s1) + strlen (s2) + 1]; 1031 strcpy (str, s1); 1032 strcat (str, s2); 1033 return fopen (str, mode); 1034@} 1035@end smallexample 1036 1037@cindex scope of a variable length array 1038@cindex variable-length array scope 1039@cindex deallocating variable length arrays 1040Jumping or breaking out of the scope of the array name deallocates the 1041storage. Jumping into the scope is not allowed; you get an error 1042message for it. 1043 1044@cindex @code{alloca} vs variable-length arrays 1045You can use the function @code{alloca} to get an effect much like 1046variable-length arrays. The function @code{alloca} is available in 1047many other C implementations (but not in all). On the other hand, 1048variable-length arrays are more elegant. 1049 1050There are other differences between these two methods. Space allocated 1051with @code{alloca} exists until the containing @emph{function} returns. 1052The space for a variable-length array is deallocated as soon as the array 1053name's scope ends. (If you use both variable-length arrays and 1054@code{alloca} in the same function, deallocation of a variable-length array 1055will also deallocate anything more recently allocated with @code{alloca}.) 1056 1057You can also use variable-length arrays as arguments to functions: 1058 1059@smallexample 1060struct entry 1061tester (int len, char data[len][len]) 1062@{ 1063 /* @r{@dots{}} */ 1064@} 1065@end smallexample 1066 1067The length of an array is computed once when the storage is allocated 1068and is remembered for the scope of the array in case you access it with 1069@code{sizeof}. 1070 1071If you want to pass the array first and the length afterward, you can 1072use a forward declaration in the parameter list---another GNU extension. 1073 1074@smallexample 1075struct entry 1076tester (int len; char data[len][len], int len) 1077@{ 1078 /* @r{@dots{}} */ 1079@} 1080@end smallexample 1081 1082@cindex parameter forward declaration 1083The @samp{int len} before the semicolon is a @dfn{parameter forward 1084declaration}, and it serves the purpose of making the name @code{len} 1085known when the declaration of @code{data} is parsed. 1086 1087You can write any number of such parameter forward declarations in the 1088parameter list. They can be separated by commas or semicolons, but the 1089last one must end with a semicolon, which is followed by the ``real'' 1090parameter declarations. Each forward declaration must match a ``real'' 1091declaration in parameter name and data type. ISO C99 does not support 1092parameter forward declarations. 1093 1094@node Variadic Macros 1095@section Macros with a Variable Number of Arguments. 1096@cindex variable number of arguments 1097@cindex macro with variable arguments 1098@cindex rest argument (in macro) 1099@cindex variadic macros 1100 1101In the ISO C standard of 1999, a macro can be declared to accept a 1102variable number of arguments much as a function can. The syntax for 1103defining the macro is similar to that of a function. Here is an 1104example: 1105 1106@smallexample 1107#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) 1108@end smallexample 1109 1110Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of 1111such a macro, it represents the zero or more tokens until the closing 1112parenthesis that ends the invocation, including any commas. This set of 1113tokens replaces the identifier @code{__VA_ARGS__} in the macro body 1114wherever it appears. See the CPP manual for more information. 1115 1116GCC has long supported variadic macros, and used a different syntax that 1117allowed you to give a name to the variable arguments just like any other 1118argument. Here is an example: 1119 1120@smallexample 1121#define debug(format, args...) fprintf (stderr, format, args) 1122@end smallexample 1123 1124This is in all ways equivalent to the ISO C example above, but arguably 1125more readable and descriptive. 1126 1127GNU CPP has two further variadic macro extensions, and permits them to 1128be used with either of the above forms of macro definition. 1129 1130In standard C, you are not allowed to leave the variable argument out 1131entirely; but you are allowed to pass an empty argument. For example, 1132this invocation is invalid in ISO C, because there is no comma after 1133the string: 1134 1135@smallexample 1136debug ("A message") 1137@end smallexample 1138 1139GNU CPP permits you to completely omit the variable arguments in this 1140way. In the above examples, the compiler would complain, though since 1141the expansion of the macro still has the extra comma after the format 1142string. 1143 1144To help solve this problem, CPP behaves specially for variable arguments 1145used with the token paste operator, @samp{##}. If instead you write 1146 1147@smallexample 1148#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) 1149@end smallexample 1150 1151and if the variable arguments are omitted or empty, the @samp{##} 1152operator causes the preprocessor to remove the comma before it. If you 1153do provide some variable arguments in your macro invocation, GNU CPP 1154does not complain about the paste operation and instead places the 1155variable arguments after the comma. Just like any other pasted macro 1156argument, these arguments are not macro expanded. 1157 1158@node Escaped Newlines 1159@section Slightly Looser Rules for Escaped Newlines 1160@cindex escaped newlines 1161@cindex newlines (escaped) 1162 1163Recently, the preprocessor has relaxed its treatment of escaped 1164newlines. Previously, the newline had to immediately follow a 1165backslash. The current implementation allows whitespace in the form 1166of spaces, horizontal and vertical tabs, and form feeds between the 1167backslash and the subsequent newline. The preprocessor issues a 1168warning, but treats it as a valid escaped newline and combines the two 1169lines to form a single logical line. This works within comments and 1170tokens, as well as between tokens. Comments are @emph{not} treated as 1171whitespace for the purposes of this relaxation, since they have not 1172yet been replaced with spaces. 1173 1174@node Subscripting 1175@section Non-Lvalue Arrays May Have Subscripts 1176@cindex subscripting 1177@cindex arrays, non-lvalue 1178 1179@cindex subscripting and function values 1180In ISO C99, arrays that are not lvalues still decay to pointers, and 1181may be subscripted, although they may not be modified or used after 1182the next sequence point and the unary @samp{&} operator may not be 1183applied to them. As an extension, GCC allows such arrays to be 1184subscripted in C89 mode, though otherwise they do not decay to 1185pointers outside C99 mode. For example, 1186this is valid in GNU C though not valid in C89: 1187 1188@smallexample 1189@group 1190struct foo @{int a[4];@}; 1191 1192struct foo f(); 1193 1194bar (int index) 1195@{ 1196 return f().a[index]; 1197@} 1198@end group 1199@end smallexample 1200 1201@node Pointer Arith 1202@section Arithmetic on @code{void}- and Function-Pointers 1203@cindex void pointers, arithmetic 1204@cindex void, size of pointer to 1205@cindex function pointers, arithmetic 1206@cindex function, size of pointer to 1207 1208In GNU C, addition and subtraction operations are supported on pointers to 1209@code{void} and on pointers to functions. This is done by treating the 1210size of a @code{void} or of a function as 1. 1211 1212A consequence of this is that @code{sizeof} is also allowed on @code{void} 1213and on function types, and returns 1. 1214 1215@opindex Wpointer-arith 1216The option @option{-Wpointer-arith} requests a warning if these extensions 1217are used. 1218 1219@node Initializers 1220@section Non-Constant Initializers 1221@cindex initializers, non-constant 1222@cindex non-constant initializers 1223 1224As in standard C++ and ISO C99, the elements of an aggregate initializer for an 1225automatic variable are not required to be constant expressions in GNU C@. 1226Here is an example of an initializer with run-time varying elements: 1227 1228@smallexample 1229foo (float f, float g) 1230@{ 1231 float beat_freqs[2] = @{ f-g, f+g @}; 1232 /* @r{@dots{}} */ 1233@} 1234@end smallexample 1235 1236@node Compound Literals 1237@section Compound Literals 1238@cindex constructor expressions 1239@cindex initializations in expressions 1240@cindex structures, constructor expression 1241@cindex expressions, constructor 1242@cindex compound literals 1243@c The GNU C name for what C99 calls compound literals was "constructor expressions". 1244 1245ISO C99 supports compound literals. A compound literal looks like 1246a cast containing an initializer. Its value is an object of the 1247type specified in the cast, containing the elements specified in 1248the initializer; it is an lvalue. As an extension, GCC supports 1249compound literals in C89 mode and in C++. 1250 1251Usually, the specified type is a structure. Assume that 1252@code{struct foo} and @code{structure} are declared as shown: 1253 1254@smallexample 1255struct foo @{int a; char b[2];@} structure; 1256@end smallexample 1257 1258@noindent 1259Here is an example of constructing a @code{struct foo} with a compound literal: 1260 1261@smallexample 1262structure = ((struct foo) @{x + y, 'a', 0@}); 1263@end smallexample 1264 1265@noindent 1266This is equivalent to writing the following: 1267 1268@smallexample 1269@{ 1270 struct foo temp = @{x + y, 'a', 0@}; 1271 structure = temp; 1272@} 1273@end smallexample 1274 1275You can also construct an array. If all the elements of the compound literal 1276are (made up of) simple constant expressions, suitable for use in 1277initializers of objects of static storage duration, then the compound 1278literal can be coerced to a pointer to its first element and used in 1279such an initializer, as shown here: 1280 1281@smallexample 1282char **foo = (char *[]) @{ "x", "y", "z" @}; 1283@end smallexample 1284 1285Compound literals for scalar types and union types are is 1286also allowed, but then the compound literal is equivalent 1287to a cast. 1288 1289As a GNU extension, GCC allows initialization of objects with static storage 1290duration by compound literals (which is not possible in ISO C99, because 1291the initializer is not a constant). 1292It is handled as if the object was initialized only with the bracket 1293enclosed list if the types of the compound literal and the object match. 1294The initializer list of the compound literal must be constant. 1295If the object being initialized has array type of unknown size, the size is 1296determined by compound literal size. 1297 1298@smallexample 1299static struct foo x = (struct foo) @{1, 'a', 'b'@}; 1300static int y[] = (int []) @{1, 2, 3@}; 1301static int z[] = (int [3]) @{1@}; 1302@end smallexample 1303 1304@noindent 1305The above lines are equivalent to the following: 1306@smallexample 1307static struct foo x = @{1, 'a', 'b'@}; 1308static int y[] = @{1, 2, 3@}; 1309static int z[] = @{1, 0, 0@}; 1310@end smallexample 1311 1312@node Designated Inits 1313@section Designated Initializers 1314@cindex initializers with labeled elements 1315@cindex labeled elements in initializers 1316@cindex case labels in initializers 1317@cindex designated initializers 1318 1319Standard C89 requires the elements of an initializer to appear in a fixed 1320order, the same as the order of the elements in the array or structure 1321being initialized. 1322 1323In ISO C99 you can give the elements in any order, specifying the array 1324indices or structure field names they apply to, and GNU C allows this as 1325an extension in C89 mode as well. This extension is not 1326implemented in GNU C++. 1327 1328To specify an array index, write 1329@samp{[@var{index}] =} before the element value. For example, 1330 1331@smallexample 1332int a[6] = @{ [4] = 29, [2] = 15 @}; 1333@end smallexample 1334 1335@noindent 1336is equivalent to 1337 1338@smallexample 1339int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; 1340@end smallexample 1341 1342@noindent 1343The index values must be constant expressions, even if the array being 1344initialized is automatic. 1345 1346An alternative syntax for this which has been obsolete since GCC 2.5 but 1347GCC still accepts is to write @samp{[@var{index}]} before the element 1348value, with no @samp{=}. 1349 1350To initialize a range of elements to the same value, write 1351@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU 1352extension. For example, 1353 1354@smallexample 1355int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; 1356@end smallexample 1357 1358@noindent 1359If the value in it has side-effects, the side-effects will happen only once, 1360not for each initialized field by the range initializer. 1361 1362@noindent 1363Note that the length of the array is the highest value specified 1364plus one. 1365 1366In a structure initializer, specify the name of a field to initialize 1367with @samp{.@var{fieldname} =} before the element value. For example, 1368given the following structure, 1369 1370@smallexample 1371struct point @{ int x, y; @}; 1372@end smallexample 1373 1374@noindent 1375the following initialization 1376 1377@smallexample 1378struct point p = @{ .y = yvalue, .x = xvalue @}; 1379@end smallexample 1380 1381@noindent 1382is equivalent to 1383 1384@smallexample 1385struct point p = @{ xvalue, yvalue @}; 1386@end smallexample 1387 1388Another syntax which has the same meaning, obsolete since GCC 2.5, is 1389@samp{@var{fieldname}:}, as shown here: 1390 1391@smallexample 1392struct point p = @{ y: yvalue, x: xvalue @}; 1393@end smallexample 1394 1395@cindex designators 1396The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a 1397@dfn{designator}. You can also use a designator (or the obsolete colon 1398syntax) when initializing a union, to specify which element of the union 1399should be used. For example, 1400 1401@smallexample 1402union foo @{ int i; double d; @}; 1403 1404union foo f = @{ .d = 4 @}; 1405@end smallexample 1406 1407@noindent 1408will convert 4 to a @code{double} to store it in the union using 1409the second element. By contrast, casting 4 to type @code{union foo} 1410would store it into the union as the integer @code{i}, since it is 1411an integer. (@xref{Cast to Union}.) 1412 1413You can combine this technique of naming elements with ordinary C 1414initialization of successive elements. Each initializer element that 1415does not have a designator applies to the next consecutive element of the 1416array or structure. For example, 1417 1418@smallexample 1419int a[6] = @{ [1] = v1, v2, [4] = v4 @}; 1420@end smallexample 1421 1422@noindent 1423is equivalent to 1424 1425@smallexample 1426int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; 1427@end smallexample 1428 1429Labeling the elements of an array initializer is especially useful 1430when the indices are characters or belong to an @code{enum} type. 1431For example: 1432 1433@smallexample 1434int whitespace[256] 1435 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, 1436 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; 1437@end smallexample 1438 1439@cindex designator lists 1440You can also write a series of @samp{.@var{fieldname}} and 1441@samp{[@var{index}]} designators before an @samp{=} to specify a 1442nested subobject to initialize; the list is taken relative to the 1443subobject corresponding to the closest surrounding brace pair. For 1444example, with the @samp{struct point} declaration above: 1445 1446@smallexample 1447struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; 1448@end smallexample 1449 1450@noindent 1451If the same field is initialized multiple times, it will have value from 1452the last initialization. If any such overridden initialization has 1453side-effect, it is unspecified whether the side-effect happens or not. 1454Currently, GCC will discard them and issue a warning. 1455 1456@node Case Ranges 1457@section Case Ranges 1458@cindex case ranges 1459@cindex ranges in case statements 1460 1461You can specify a range of consecutive values in a single @code{case} label, 1462like this: 1463 1464@smallexample 1465case @var{low} ... @var{high}: 1466@end smallexample 1467 1468@noindent 1469This has the same effect as the proper number of individual @code{case} 1470labels, one for each integer value from @var{low} to @var{high}, inclusive. 1471 1472This feature is especially useful for ranges of ASCII character codes: 1473 1474@smallexample 1475case 'A' ... 'Z': 1476@end smallexample 1477 1478@strong{Be careful:} Write spaces around the @code{...}, for otherwise 1479it may be parsed wrong when you use it with integer values. For example, 1480write this: 1481 1482@smallexample 1483case 1 ... 5: 1484@end smallexample 1485 1486@noindent 1487rather than this: 1488 1489@smallexample 1490case 1...5: 1491@end smallexample 1492 1493@node Cast to Union 1494@section Cast to a Union Type 1495@cindex cast to a union 1496@cindex union, casting to a 1497 1498A cast to union type is similar to other casts, except that the type 1499specified is a union type. You can specify the type either with 1500@code{union @var{tag}} or with a typedef name. A cast to union is actually 1501a constructor though, not a cast, and hence does not yield an lvalue like 1502normal casts. (@xref{Compound Literals}.) 1503 1504The types that may be cast to the union type are those of the members 1505of the union. Thus, given the following union and variables: 1506 1507@smallexample 1508union foo @{ int i; double d; @}; 1509int x; 1510double y; 1511@end smallexample 1512 1513@noindent 1514both @code{x} and @code{y} can be cast to type @code{union foo}. 1515 1516Using the cast as the right-hand side of an assignment to a variable of 1517union type is equivalent to storing in a member of the union: 1518 1519@smallexample 1520union foo u; 1521/* @r{@dots{}} */ 1522u = (union foo) x @equiv{} u.i = x 1523u = (union foo) y @equiv{} u.d = y 1524@end smallexample 1525 1526You can also use the union cast as a function argument: 1527 1528@smallexample 1529void hack (union foo); 1530/* @r{@dots{}} */ 1531hack ((union foo) x); 1532@end smallexample 1533 1534@node Mixed Declarations 1535@section Mixed Declarations and Code 1536@cindex mixed declarations and code 1537@cindex declarations, mixed with code 1538@cindex code, mixed with declarations 1539 1540ISO C99 and ISO C++ allow declarations and code to be freely mixed 1541within compound statements. As an extension, GCC also allows this in 1542C89 mode. For example, you could do: 1543 1544@smallexample 1545int i; 1546/* @r{@dots{}} */ 1547i++; 1548int j = i + 2; 1549@end smallexample 1550 1551Each identifier is visible from where it is declared until the end of 1552the enclosing block. 1553 1554@node Function Attributes 1555@section Declaring Attributes of Functions 1556@cindex function attributes 1557@cindex declaring attributes of functions 1558@cindex functions that never return 1559@cindex functions that return more than once 1560@cindex functions that have no side effects 1561@cindex functions in arbitrary sections 1562@cindex functions that behave like malloc 1563@cindex @code{volatile} applied to function 1564@cindex @code{const} applied to function 1565@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments 1566@cindex functions with non-null pointer arguments 1567@cindex functions that are passed arguments in registers on the 386 1568@cindex functions that pop the argument stack on the 386 1569@cindex functions that do not pop the argument stack on the 386 1570 1571In GNU C, you declare certain things about functions called in your program 1572which help the compiler optimize function calls and check your code more 1573carefully. 1574 1575The keyword @code{__attribute__} allows you to specify special 1576attributes when making a declaration. This keyword is followed by an 1577attribute specification inside double parentheses. The following 1578attributes are currently defined for functions on all targets: 1579@code{noreturn}, @code{returns_twice}, @code{noinline}, @code{always_inline}, 1580@code{flatten}, @code{pure}, @code{const}, @code{nothrow}, @code{sentinel}, 1581@code{format}, @code{format_arg}, @code{no_instrument_function}, 1582@code{section}, @code{constructor}, @code{destructor}, @code{used}, 1583@code{unused}, @code{deprecated}, @code{weak}, @code{malloc}, 1584@code{alias}, @code{warn_unused_result}, @code{nonnull}, 1585@code{gnu_inline} and @code{externally_visible}. Several other 1586attributes are defined for functions on particular target systems. Other 1587attributes, including @code{section} are supported for variables declarations 1588(@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}). 1589 1590You may also specify attributes with @samp{__} preceding and following 1591each keyword. This allows you to use them in header files without 1592being concerned about a possible macro of the same name. For example, 1593you may use @code{__noreturn__} instead of @code{noreturn}. 1594 1595@xref{Attribute Syntax}, for details of the exact syntax for using 1596attributes. 1597 1598@table @code 1599@c Keep this table alphabetized by attribute name. Treat _ as space. 1600 1601@item alias ("@var{target}") 1602@cindex @code{alias} attribute 1603The @code{alias} attribute causes the declaration to be emitted as an 1604alias for another symbol, which must be specified. For instance, 1605 1606@smallexample 1607void __f () @{ /* @r{Do something.} */; @} 1608void f () __attribute__ ((weak, alias ("__f"))); 1609@end smallexample 1610 1611defines @samp{f} to be a weak alias for @samp{__f}. In C++, the 1612mangled name for the target must be used. It is an error if @samp{__f} 1613is not defined in the same translation unit. 1614 1615Not all target machines support this attribute. 1616 1617@item always_inline 1618@cindex @code{always_inline} function attribute 1619Generally, functions are not inlined unless optimization is specified. 1620For functions declared inline, this attribute inlines the function even 1621if no optimization level was specified. 1622 1623@item gnu_inline 1624@cindex @code{gnu_inline} function attribute 1625This attribute should be used with a function which is also declared 1626with the @code{inline} keyword. It directs GCC to treat the function 1627as if it were defined in gnu89 mode even when compiling in C99 or 1628gnu99 mode. 1629 1630If the function is declared @code{extern}, then this definition of the 1631function is used only for inlining. In no case is the function 1632compiled as a standalone function, not even if you take its address 1633explicitly. Such an address becomes an external reference, as if you 1634had only declared the function, and had not defined it. This has 1635almost the effect of a macro. The way to use this is to put a 1636function definition in a header file with this attribute, and put 1637another copy of the function, without @code{extern}, in a library 1638file. The definition in the header file will cause most calls to the 1639function to be inlined. If any uses of the function remain, they will 1640refer to the single copy in the library. Note that the two 1641definitions of the functions need not be precisely the same, although 1642if they do not have the same effect your program may behave oddly. 1643 1644If the function is neither @code{extern} nor @code{static}, then the 1645function is compiled as a standalone function, as well as being 1646inlined where possible. 1647 1648This is how GCC traditionally handled functions declared 1649@code{inline}. Since ISO C99 specifies a different semantics for 1650@code{inline}, this function attribute is provided as a transition 1651measure and as a useful feature in its own right. This attribute is 1652available in GCC 4.1.3 and later. It is available if either of the 1653preprocessor macros @code{__GNUC_GNU_INLINE__} or 1654@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline 1655Function is As Fast As a Macro}. 1656 1657Note that since the first version of GCC to support C99 inline semantics 1658is 4.3, earlier versions of GCC which accept this attribute effectively 1659assume that it is always present, whether or not it is given explicitly. 1660In versions prior to 4.3, the only effect of explicitly including it is 1661to disable warnings about using inline functions in C99 mode. 1662 1663@cindex @code{flatten} function attribute 1664@item flatten 1665Generally, inlining into a function is limited. For a function marked with 1666this attribute, every call inside this function will be inlined, if possible. 1667Whether the function itself is considered for inlining depends on its size and 1668the current inlining parameters. The @code{flatten} attribute only works 1669reliably in unit-at-a-time mode. 1670 1671@item cdecl 1672@cindex functions that do pop the argument stack on the 386 1673@opindex mrtd 1674On the Intel 386, the @code{cdecl} attribute causes the compiler to 1675assume that the calling function will pop off the stack space used to 1676pass arguments. This is 1677useful to override the effects of the @option{-mrtd} switch. 1678 1679@item const 1680@cindex @code{const} function attribute 1681Many functions do not examine any values except their arguments, and 1682have no effects except the return value. Basically this is just slightly 1683more strict class than the @code{pure} attribute below, since function is not 1684allowed to read global memory. 1685 1686@cindex pointer arguments 1687Note that a function that has pointer arguments and examines the data 1688pointed to must @emph{not} be declared @code{const}. Likewise, a 1689function that calls a non-@code{const} function usually must not be 1690@code{const}. It does not make sense for a @code{const} function to 1691return @code{void}. 1692 1693The attribute @code{const} is not implemented in GCC versions earlier 1694than 2.5. An alternative way to declare that a function has no side 1695effects, which works in the current version and in some older versions, 1696is as follows: 1697 1698@smallexample 1699typedef int intfn (); 1700 1701extern const intfn square; 1702@end smallexample 1703 1704This approach does not work in GNU C++ from 2.6.0 on, since the language 1705specifies that the @samp{const} must be attached to the return value. 1706 1707@item constructor 1708@itemx destructor 1709@cindex @code{constructor} function attribute 1710@cindex @code{destructor} function attribute 1711The @code{constructor} attribute causes the function to be called 1712automatically before execution enters @code{main ()}. Similarly, the 1713@code{destructor} attribute causes the function to be called 1714automatically after @code{main ()} has completed or @code{exit ()} has 1715been called. Functions with these attributes are useful for 1716initializing data that will be used implicitly during the execution of 1717the program. 1718 1719@item deprecated 1720@cindex @code{deprecated} attribute. 1721The @code{deprecated} attribute results in a warning if the function 1722is used anywhere in the source file. This is useful when identifying 1723functions that are expected to be removed in a future version of a 1724program. The warning also includes the location of the declaration 1725of the deprecated function, to enable users to easily find further 1726information about why the function is deprecated, or what they should 1727do instead. Note that the warnings only occurs for uses: 1728 1729@smallexample 1730int old_fn () __attribute__ ((deprecated)); 1731int old_fn (); 1732int (*fn_ptr)() = old_fn; 1733@end smallexample 1734 1735results in a warning on line 3 but not line 2. 1736 1737The @code{deprecated} attribute can also be used for variables and 1738types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) 1739 1740@item dllexport 1741@cindex @code{__declspec(dllexport)} 1742On Microsoft Windows targets and Symbian OS targets the 1743@code{dllexport} attribute causes the compiler to provide a global 1744pointer to a pointer in a DLL, so that it can be referenced with the 1745@code{dllimport} attribute. On Microsoft Windows targets, the pointer 1746name is formed by combining @code{_imp__} and the function or variable 1747name. 1748 1749You can use @code{__declspec(dllexport)} as a synonym for 1750@code{__attribute__ ((dllexport))} for compatibility with other 1751compilers. 1752 1753On systems that support the @code{visibility} attribute, this 1754attribute also implies ``default'' visibility, unless a 1755@code{visibility} attribute is explicitly specified. You should avoid 1756the use of @code{dllexport} with ``hidden'' or ``internal'' 1757visibility; in the future GCC may issue an error for those cases. 1758 1759Currently, the @code{dllexport} attribute is ignored for inlined 1760functions, unless the @option{-fkeep-inline-functions} flag has been 1761used. The attribute is also ignored for undefined symbols. 1762 1763When applied to C++ classes, the attribute marks defined non-inlined 1764member functions and static data members as exports. Static consts 1765initialized in-class are not marked unless they are also defined 1766out-of-class. 1767 1768For Microsoft Windows targets there are alternative methods for 1769including the symbol in the DLL's export table such as using a 1770@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using 1771the @option{--export-all} linker flag. 1772 1773@item dllimport 1774@cindex @code{__declspec(dllimport)} 1775On Microsoft Windows and Symbian OS targets, the @code{dllimport} 1776attribute causes the compiler to reference a function or variable via 1777a global pointer to a pointer that is set up by the DLL exporting the 1778symbol. The attribute implies @code{extern} storage. On Microsoft 1779Windows targets, the pointer name is formed by combining @code{_imp__} 1780and the function or variable name. 1781 1782You can use @code{__declspec(dllimport)} as a synonym for 1783@code{__attribute__ ((dllimport))} for compatibility with other 1784compilers. 1785 1786Currently, the attribute is ignored for inlined functions. If the 1787attribute is applied to a symbol @emph{definition}, an error is reported. 1788If a symbol previously declared @code{dllimport} is later defined, the 1789attribute is ignored in subsequent references, and a warning is emitted. 1790The attribute is also overridden by a subsequent declaration as 1791@code{dllexport}. 1792 1793When applied to C++ classes, the attribute marks non-inlined 1794member functions and static data members as imports. However, the 1795attribute is ignored for virtual methods to allow creation of vtables 1796using thunks. 1797 1798On the SH Symbian OS target the @code{dllimport} attribute also has 1799another affect---it can cause the vtable and run-time type information 1800for a class to be exported. This happens when the class has a 1801dllimport'ed constructor or a non-inline, non-pure virtual function 1802and, for either of those two conditions, the class also has a inline 1803constructor or destructor and has a key function that is defined in 1804the current translation unit. 1805 1806For Microsoft Windows based targets the use of the @code{dllimport} 1807attribute on functions is not necessary, but provides a small 1808performance benefit by eliminating a thunk in the DLL@. The use of the 1809@code{dllimport} attribute on imported variables was required on older 1810versions of the GNU linker, but can now be avoided by passing the 1811@option{--enable-auto-import} switch to the GNU linker. As with 1812functions, using the attribute for a variable eliminates a thunk in 1813the DLL@. 1814 1815One drawback to using this attribute is that a pointer to a function 1816or variable marked as @code{dllimport} cannot be used as a constant 1817address. On Microsoft Windows targets, the attribute can be disabled 1818for functions by setting the @option{-mnop-fun-dllimport} flag. 1819 1820@item eightbit_data 1821@cindex eight bit data on the H8/300, H8/300H, and H8S 1822Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 1823variable should be placed into the eight bit data section. 1824The compiler will generate more efficient code for certain operations 1825on data in the eight bit data area. Note the eight bit data area is limited to 1826256 bytes of data. 1827 1828You must use GAS and GLD from GNU binutils version 2.7 or later for 1829this attribute to work correctly. 1830 1831@item exception_handler 1832@cindex exception handler functions on the Blackfin processor 1833Use this attribute on the Blackfin to indicate that the specified function 1834is an exception handler. The compiler will generate function entry and 1835exit sequences suitable for use in an exception handler when this 1836attribute is present. 1837 1838@item far 1839@cindex functions which handle memory bank switching 1840On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to 1841use a calling convention that takes care of switching memory banks when 1842entering and leaving a function. This calling convention is also the 1843default when using the @option{-mlong-calls} option. 1844 1845On 68HC12 the compiler will use the @code{call} and @code{rtc} instructions 1846to call and return from a function. 1847 1848On 68HC11 the compiler will generate a sequence of instructions 1849to invoke a board-specific routine to switch the memory bank and call the 1850real function. The board-specific routine simulates a @code{call}. 1851At the end of a function, it will jump to a board-specific routine 1852instead of using @code{rts}. The board-specific return routine simulates 1853the @code{rtc}. 1854 1855@item fastcall 1856@cindex functions that pop the argument stack on the 386 1857On the Intel 386, the @code{fastcall} attribute causes the compiler to 1858pass the first argument (if of integral type) in the register ECX and 1859the second argument (if of integral type) in the register EDX@. Subsequent 1860and other typed arguments are passed on the stack. The called function will 1861pop the arguments off the stack. If the number of arguments is variable all 1862arguments are pushed on the stack. 1863 1864@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) 1865@cindex @code{format} function attribute 1866@opindex Wformat 1867The @code{format} attribute specifies that a function takes @code{printf}, 1868@code{scanf}, @code{strftime} or @code{strfmon} style arguments which 1869should be type-checked against a format string. For example, the 1870declaration: 1871 1872@smallexample 1873extern int 1874my_printf (void *my_object, const char *my_format, ...) 1875 __attribute__ ((format (printf, 2, 3))); 1876@end smallexample 1877 1878@noindent 1879causes the compiler to check the arguments in calls to @code{my_printf} 1880for consistency with the @code{printf} style format string argument 1881@code{my_format}. 1882 1883The parameter @var{archetype} determines how the format string is 1884interpreted, and should be @code{printf}, @code{scanf}, @code{strftime} 1885or @code{strfmon}. (You can also use @code{__printf__}, 1886@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) The 1887parameter @var{string-index} specifies which argument is the format 1888string argument (starting from 1), while @var{first-to-check} is the 1889number of the first argument to check against the format string. For 1890functions where the arguments are not available to be checked (such as 1891@code{vprintf}), specify the third parameter as zero. In this case the 1892compiler only checks the format string for consistency. For 1893@code{strftime} formats, the third parameter is required to be zero. 1894Since non-static C++ methods have an implicit @code{this} argument, the 1895arguments of such methods should be counted from two, not one, when 1896giving values for @var{string-index} and @var{first-to-check}. 1897 1898In the example above, the format string (@code{my_format}) is the second 1899argument of the function @code{my_print}, and the arguments to check 1900start with the third argument, so the correct parameters for the format 1901attribute are 2 and 3. 1902 1903@opindex ffreestanding 1904@opindex fno-builtin 1905The @code{format} attribute allows you to identify your own functions 1906which take format strings as arguments, so that GCC can check the 1907calls to these functions for errors. The compiler always (unless 1908@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats 1909for the standard library functions @code{printf}, @code{fprintf}, 1910@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, 1911@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such 1912warnings are requested (using @option{-Wformat}), so there is no need to 1913modify the header file @file{stdio.h}. In C99 mode, the functions 1914@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and 1915@code{vsscanf} are also checked. Except in strictly conforming C 1916standard modes, the X/Open function @code{strfmon} is also checked as 1917are @code{printf_unlocked} and @code{fprintf_unlocked}. 1918@xref{C Dialect Options,,Options Controlling C Dialect}. 1919 1920The target may provide additional types of format checks. 1921@xref{Target Format Checks,,Format Checks Specific to Particular 1922Target Machines}. 1923 1924@item format_arg (@var{string-index}) 1925@cindex @code{format_arg} function attribute 1926@opindex Wformat-nonliteral 1927The @code{format_arg} attribute specifies that a function takes a format 1928string for a @code{printf}, @code{scanf}, @code{strftime} or 1929@code{strfmon} style function and modifies it (for example, to translate 1930it into another language), so the result can be passed to a 1931@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style 1932function (with the remaining arguments to the format function the same 1933as they would have been for the unmodified string). For example, the 1934declaration: 1935 1936@smallexample 1937extern char * 1938my_dgettext (char *my_domain, const char *my_format) 1939 __attribute__ ((format_arg (2))); 1940@end smallexample 1941 1942@noindent 1943causes the compiler to check the arguments in calls to a @code{printf}, 1944@code{scanf}, @code{strftime} or @code{strfmon} type function, whose 1945format string argument is a call to the @code{my_dgettext} function, for 1946consistency with the format string argument @code{my_format}. If the 1947@code{format_arg} attribute had not been specified, all the compiler 1948could tell in such calls to format functions would be that the format 1949string argument is not constant; this would generate a warning when 1950@option{-Wformat-nonliteral} is used, but the calls could not be checked 1951without the attribute. 1952 1953The parameter @var{string-index} specifies which argument is the format 1954string argument (starting from one). Since non-static C++ methods have 1955an implicit @code{this} argument, the arguments of such methods should 1956be counted from two. 1957 1958The @code{format-arg} attribute allows you to identify your own 1959functions which modify format strings, so that GCC can check the 1960calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} 1961type function whose operands are a call to one of your own function. 1962The compiler always treats @code{gettext}, @code{dgettext}, and 1963@code{dcgettext} in this manner except when strict ISO C support is 1964requested by @option{-ansi} or an appropriate @option{-std} option, or 1965@option{-ffreestanding} or @option{-fno-builtin} 1966is used. @xref{C Dialect Options,,Options 1967Controlling C Dialect}. 1968 1969@item function_vector 1970@cindex calling functions through the function vector on the H8/300 processors 1971Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 1972function should be called through the function vector. Calling a 1973function through the function vector will reduce code size, however; 1974the function vector has a limited size (maximum 128 entries on the H8/300 1975and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector. 1976 1977You must use GAS and GLD from GNU binutils version 2.7 or later for 1978this attribute to work correctly. 1979 1980@item interrupt 1981@cindex interrupt handler functions 1982Use this attribute on the ARM, AVR, C4x, CRX, M32C, M32R/D, MS1, and Xstormy16 1983ports to indicate that the specified function is an interrupt handler. 1984The compiler will generate function entry and exit sequences suitable 1985for use in an interrupt handler when this attribute is present. 1986 1987Note, interrupt handlers for the Blackfin, m68k, H8/300, H8/300H, H8S, and 1988SH processors can be specified via the @code{interrupt_handler} attribute. 1989 1990Note, on the AVR, interrupts will be enabled inside the function. 1991 1992Note, for the ARM, you can specify the kind of interrupt to be handled by 1993adding an optional parameter to the interrupt attribute like this: 1994 1995@smallexample 1996void f () __attribute__ ((interrupt ("IRQ"))); 1997@end smallexample 1998 1999Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@. 2000 2001@item interrupt_handler 2002@cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors 2003Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to 2004indicate that the specified function is an interrupt handler. The compiler 2005will generate function entry and exit sequences suitable for use in an 2006interrupt handler when this attribute is present. 2007 2008@item kspisusp 2009@cindex User stack pointer in interrupts on the Blackfin 2010When used together with @code{interrupt_handler}, @code{exception_handler} 2011or @code{nmi_handler}, code will be generated to load the stack pointer 2012from the USP register in the function prologue. 2013 2014@item long_call/short_call 2015@cindex indirect calls on ARM 2016This attribute specifies how a particular function is called on 2017ARM@. Both attributes override the @option{-mlong-calls} (@pxref{ARM Options}) 2018command line switch and @code{#pragma long_calls} settings. The 2019@code{long_call} attribute indicates that the function might be far 2020away from the call site and require a different (more expensive) 2021calling sequence. The @code{short_call} attribute always places 2022the offset to the function from the call site into the @samp{BL} 2023instruction directly. 2024 2025@item longcall/shortcall 2026@cindex functions called via pointer on the RS/6000 and PowerPC 2027On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute 2028indicates that the function might be far away from the call site and 2029require a different (more expensive) calling sequence. The 2030@code{shortcall} attribute indicates that the function is always close 2031enough for the shorter calling sequence to be used. These attributes 2032override both the @option{-mlongcall} switch and, on the RS/6000 and 2033PowerPC, the @code{#pragma longcall} setting. 2034 2035@xref{RS/6000 and PowerPC Options}, for more information on whether long 2036calls are necessary. 2037 2038@item long_call 2039@cindex indirect calls on MIPS 2040This attribute specifies how a particular function is called on MIPS@. 2041The attribute overrides the @option{-mlong-calls} (@pxref{MIPS Options}) 2042command line switch. This attribute causes the compiler to always call 2043the function by first loading its address into a register, and then using 2044the contents of that register. 2045 2046@item malloc 2047@cindex @code{malloc} attribute 2048The @code{malloc} attribute is used to tell the compiler that a function 2049may be treated as if any non-@code{NULL} pointer it returns cannot 2050alias any other pointer valid when the function returns. 2051This will often improve optimization. 2052Standard functions with this property include @code{malloc} and 2053@code{calloc}. @code{realloc}-like functions have this property as 2054long as the old pointer is never referred to (including comparing it 2055to the new pointer) after the function returns a non-@code{NULL} 2056value. 2057 2058@item model (@var{model-name}) 2059@cindex function addressability on the M32R/D 2060@cindex variable addressability on the IA-64 2061 2062On the M32R/D, use this attribute to set the addressability of an 2063object, and of the code generated for a function. The identifier 2064@var{model-name} is one of @code{small}, @code{medium}, or 2065@code{large}, representing each of the code models. 2066 2067Small model objects live in the lower 16MB of memory (so that their 2068addresses can be loaded with the @code{ld24} instruction), and are 2069callable with the @code{bl} instruction. 2070 2071Medium model objects may live anywhere in the 32-bit address space (the 2072compiler will generate @code{seth/add3} instructions to load their addresses), 2073and are callable with the @code{bl} instruction. 2074 2075Large model objects may live anywhere in the 32-bit address space (the 2076compiler will generate @code{seth/add3} instructions to load their addresses), 2077and may not be reachable with the @code{bl} instruction (the compiler will 2078generate the much slower @code{seth/add3/jl} instruction sequence). 2079 2080On IA-64, use this attribute to set the addressability of an object. 2081At present, the only supported identifier for @var{model-name} is 2082@code{small}, indicating addressability via ``small'' (22-bit) 2083addresses (so that their addresses can be loaded with the @code{addl} 2084instruction). Caveat: such addressing is by definition not position 2085independent and hence this attribute must not be used for objects 2086defined by shared libraries. 2087 2088@item naked 2089@cindex function without a prologue/epilogue code 2090Use this attribute on the ARM, AVR, C4x and IP2K ports to indicate that the 2091specified function does not need prologue/epilogue sequences generated by 2092the compiler. It is up to the programmer to provide these sequences. 2093 2094@item near 2095@cindex functions which do not handle memory bank switching on 68HC11/68HC12 2096On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to 2097use the normal calling convention based on @code{jsr} and @code{rts}. 2098This attribute can be used to cancel the effect of the @option{-mlong-calls} 2099option. 2100 2101@item nesting 2102@cindex Allow nesting in an interrupt handler on the Blackfin processor. 2103Use this attribute together with @code{interrupt_handler}, 2104@code{exception_handler} or @code{nmi_handler} to indicate that the function 2105entry code should enable nested interrupts or exceptions. 2106 2107@item nmi_handler 2108@cindex NMI handler functions on the Blackfin processor 2109Use this attribute on the Blackfin to indicate that the specified function 2110is an NMI handler. The compiler will generate function entry and 2111exit sequences suitable for use in an NMI handler when this 2112attribute is present. 2113 2114@item no_instrument_function 2115@cindex @code{no_instrument_function} function attribute 2116@opindex finstrument-functions 2117If @option{-finstrument-functions} is given, profiling function calls will 2118be generated at entry and exit of most user-compiled functions. 2119Functions with this attribute will not be so instrumented. 2120 2121@item noinline 2122@cindex @code{noinline} function attribute 2123This function attribute prevents a function from being considered for 2124inlining. 2125 2126@item nonnull (@var{arg-index}, @dots{}) 2127@cindex @code{nonnull} function attribute 2128The @code{nonnull} attribute specifies that some function parameters should 2129be non-null pointers. For instance, the declaration: 2130 2131@smallexample 2132extern void * 2133my_memcpy (void *dest, const void *src, size_t len) 2134 __attribute__((nonnull (1, 2))); 2135@end smallexample 2136 2137@noindent 2138causes the compiler to check that, in calls to @code{my_memcpy}, 2139arguments @var{dest} and @var{src} are non-null. If the compiler 2140determines that a null pointer is passed in an argument slot marked 2141as non-null, and the @option{-Wnonnull} option is enabled, a warning 2142is issued. The compiler may also choose to make optimizations based 2143on the knowledge that certain function arguments will not be null. 2144 2145If no argument index list is given to the @code{nonnull} attribute, 2146all pointer arguments are marked as non-null. To illustrate, the 2147following declaration is equivalent to the previous example: 2148 2149@smallexample 2150extern void * 2151my_memcpy (void *dest, const void *src, size_t len) 2152 __attribute__((nonnull)); 2153@end smallexample 2154 2155@item noreturn 2156@cindex @code{noreturn} function attribute 2157A few standard library functions, such as @code{abort} and @code{exit}, 2158cannot return. GCC knows this automatically. Some programs define 2159their own functions that never return. You can declare them 2160@code{noreturn} to tell the compiler this fact. For example, 2161 2162@smallexample 2163@group 2164void fatal () __attribute__ ((noreturn)); 2165 2166void 2167fatal (/* @r{@dots{}} */) 2168@{ 2169 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ 2170 exit (1); 2171@} 2172@end group 2173@end smallexample 2174 2175The @code{noreturn} keyword tells the compiler to assume that 2176@code{fatal} cannot return. It can then optimize without regard to what 2177would happen if @code{fatal} ever did return. This makes slightly 2178better code. More importantly, it helps avoid spurious warnings of 2179uninitialized variables. 2180 2181The @code{noreturn} keyword does not affect the exceptional path when that 2182applies: a @code{noreturn}-marked function may still return to the caller 2183by throwing an exception or calling @code{longjmp}. 2184 2185Do not assume that registers saved by the calling function are 2186restored before calling the @code{noreturn} function. 2187 2188It does not make sense for a @code{noreturn} function to have a return 2189type other than @code{void}. 2190 2191The attribute @code{noreturn} is not implemented in GCC versions 2192earlier than 2.5. An alternative way to declare that a function does 2193not return, which works in the current version and in some older 2194versions, is as follows: 2195 2196@smallexample 2197typedef void voidfn (); 2198 2199volatile voidfn fatal; 2200@end smallexample 2201 2202This approach does not work in GNU C++. 2203 2204@item nothrow 2205@cindex @code{nothrow} function attribute 2206The @code{nothrow} attribute is used to inform the compiler that a 2207function cannot throw an exception. For example, most functions in 2208the standard C library can be guaranteed not to throw an exception 2209with the notable exceptions of @code{qsort} and @code{bsearch} that 2210take function pointer arguments. The @code{nothrow} attribute is not 2211implemented in GCC versions earlier than 3.3. 2212 2213@item pure 2214@cindex @code{pure} function attribute 2215Many functions have no effects except the return value and their 2216return value depends only on the parameters and/or global variables. 2217Such a function can be subject 2218to common subexpression elimination and loop optimization just as an 2219arithmetic operator would be. These functions should be declared 2220with the attribute @code{pure}. For example, 2221 2222@smallexample 2223int square (int) __attribute__ ((pure)); 2224@end smallexample 2225 2226@noindent 2227says that the hypothetical function @code{square} is safe to call 2228fewer times than the program says. 2229 2230Some of common examples of pure functions are @code{strlen} or @code{memcmp}. 2231Interesting non-pure functions are functions with infinite loops or those 2232depending on volatile memory or other system resource, that may change between 2233two consecutive calls (such as @code{feof} in a multithreading environment). 2234 2235The attribute @code{pure} is not implemented in GCC versions earlier 2236than 2.96. 2237 2238@item regparm (@var{number}) 2239@cindex @code{regparm} attribute 2240@cindex functions that are passed arguments in registers on the 386 2241On the Intel 386, the @code{regparm} attribute causes the compiler to 2242pass arguments number one to @var{number} if they are of integral type 2243in registers EAX, EDX, and ECX instead of on the stack. Functions that 2244take a variable number of arguments will continue to be passed all of their 2245arguments on the stack. 2246 2247Beware that on some ELF systems this attribute is unsuitable for 2248global functions in shared libraries with lazy binding (which is the 2249default). Lazy binding will send the first call via resolving code in 2250the loader, which might assume EAX, EDX and ECX can be clobbered, as 2251per the standard calling conventions. Solaris 8 is affected by this. 2252GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be 2253safe since the loaders there save all registers. (Lazy binding can be 2254disabled with the linker or the loader if desired, to avoid the 2255problem.) 2256 2257@item sseregparm 2258@cindex @code{sseregparm} attribute 2259On the Intel 386 with SSE support, the @code{sseregparm} attribute 2260causes the compiler to pass up to 3 floating point arguments in 2261SSE registers instead of on the stack. Functions that take a 2262variable number of arguments will continue to pass all of their 2263floating point arguments on the stack. 2264 2265@item force_align_arg_pointer 2266@cindex @code{force_align_arg_pointer} attribute 2267On the Intel x86, the @code{force_align_arg_pointer} attribute may be 2268applied to individual function definitions, generating an alternate 2269prologue and epilogue that realigns the runtime stack. This supports 2270mixing legacy codes that run with a 4-byte aligned stack with modern 2271codes that keep a 16-byte stack for SSE compatibility. The alternate 2272prologue and epilogue are slower and bigger than the regular ones, and 2273the alternate prologue requires a scratch register; this lowers the 2274number of registers available if used in conjunction with the 2275@code{regparm} attribute. The @code{force_align_arg_pointer} 2276attribute is incompatible with nested functions; this is considered a 2277hard error. 2278 2279@item returns_twice 2280@cindex @code{returns_twice} attribute 2281The @code{returns_twice} attribute tells the compiler that a function may 2282return more than one time. The compiler will ensure that all registers 2283are dead before calling such a function and will emit a warning about 2284the variables that may be clobbered after the second return from the 2285function. Examples of such functions are @code{setjmp} and @code{vfork}. 2286The @code{longjmp}-like counterpart of such function, if any, might need 2287to be marked with the @code{noreturn} attribute. 2288 2289@item saveall 2290@cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S 2291Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that 2292all registers except the stack pointer should be saved in the prologue 2293regardless of whether they are used or not. 2294 2295@item section ("@var{section-name}") 2296@cindex @code{section} function attribute 2297Normally, the compiler places the code it generates in the @code{text} section. 2298Sometimes, however, you need additional sections, or you need certain 2299particular functions to appear in special sections. The @code{section} 2300attribute specifies that a function lives in a particular section. 2301For example, the declaration: 2302 2303@smallexample 2304extern void foobar (void) __attribute__ ((section ("bar"))); 2305@end smallexample 2306 2307@noindent 2308puts the function @code{foobar} in the @code{bar} section. 2309 2310Some file formats do not support arbitrary sections so the @code{section} 2311attribute is not available on all platforms. 2312If you need to map the entire contents of a module to a particular 2313section, consider using the facilities of the linker instead. 2314 2315@item sentinel 2316@cindex @code{sentinel} function attribute 2317This function attribute ensures that a parameter in a function call is 2318an explicit @code{NULL}. The attribute is only valid on variadic 2319functions. By default, the sentinel is located at position zero, the 2320last parameter of the function call. If an optional integer position 2321argument P is supplied to the attribute, the sentinel must be located at 2322position P counting backwards from the end of the argument list. 2323 2324@smallexample 2325__attribute__ ((sentinel)) 2326is equivalent to 2327__attribute__ ((sentinel(0))) 2328@end smallexample 2329 2330The attribute is automatically set with a position of 0 for the built-in 2331functions @code{execl} and @code{execlp}. The built-in function 2332@code{execle} has the attribute set with a position of 1. 2333 2334A valid @code{NULL} in this context is defined as zero with any pointer 2335type. If your system defines the @code{NULL} macro with an integer type 2336then you need to add an explicit cast. GCC replaces @code{stddef.h} 2337with a copy that redefines NULL appropriately. 2338 2339The warnings for missing or incorrect sentinels are enabled with 2340@option{-Wformat}. 2341 2342@item short_call 2343See long_call/short_call. 2344 2345@item shortcall 2346See longcall/shortcall. 2347 2348@item signal 2349@cindex signal handler functions on the AVR processors 2350Use this attribute on the AVR to indicate that the specified 2351function is a signal handler. The compiler will generate function 2352entry and exit sequences suitable for use in a signal handler when this 2353attribute is present. Interrupts will be disabled inside the function. 2354 2355@item sp_switch 2356Use this attribute on the SH to indicate an @code{interrupt_handler} 2357function should switch to an alternate stack. It expects a string 2358argument that names a global variable holding the address of the 2359alternate stack. 2360 2361@smallexample 2362void *alt_stack; 2363void f () __attribute__ ((interrupt_handler, 2364 sp_switch ("alt_stack"))); 2365@end smallexample 2366 2367@item stdcall 2368@cindex functions that pop the argument stack on the 386 2369On the Intel 386, the @code{stdcall} attribute causes the compiler to 2370assume that the called function will pop off the stack space used to 2371pass arguments, unless it takes a variable number of arguments. 2372 2373@item tiny_data 2374@cindex tiny data section on the H8/300H and H8S 2375Use this attribute on the H8/300H and H8S to indicate that the specified 2376variable should be placed into the tiny data section. 2377The compiler will generate more efficient code for loads and stores 2378on data in the tiny data section. Note the tiny data area is limited to 2379slightly under 32kbytes of data. 2380 2381@item trap_exit 2382Use this attribute on the SH for an @code{interrupt_handler} to return using 2383@code{trapa} instead of @code{rte}. This attribute expects an integer 2384argument specifying the trap number to be used. 2385 2386@item unused 2387@cindex @code{unused} attribute. 2388This attribute, attached to a function, means that the function is meant 2389to be possibly unused. GCC will not produce a warning for this 2390function. 2391 2392@item used 2393@cindex @code{used} attribute. 2394This attribute, attached to a function, means that code must be emitted 2395for the function even if it appears that the function is not referenced. 2396This is useful, for example, when the function is referenced only in 2397inline assembly. 2398 2399@item visibility ("@var{visibility_type}") 2400@cindex @code{visibility} attribute 2401This attribute affects the linkage of the declaration to which it is attached. 2402There are four supported @var{visibility_type} values: default, 2403hidden, protected or internal visibility. 2404 2405@smallexample 2406void __attribute__ ((visibility ("protected"))) 2407f () @{ /* @r{Do something.} */; @} 2408int i __attribute__ ((visibility ("hidden"))); 2409@end smallexample 2410 2411The possible values of @var{visibility_type} correspond to the 2412visibility settings in the ELF gABI. 2413 2414@table @dfn 2415@c keep this list of visibilities in alphabetical order. 2416 2417@item default 2418Default visibility is the normal case for the object file format. 2419This value is available for the visibility attribute to override other 2420options that may change the assumed visibility of entities. 2421 2422On ELF, default visibility means that the declaration is visible to other 2423modules and, in shared libraries, means that the declared entity may be 2424overridden. 2425 2426On Darwin, default visibility means that the declaration is visible to 2427other modules. 2428 2429Default visibility corresponds to ``external linkage'' in the language. 2430 2431@item hidden 2432Hidden visibility indicates that the entity declared will have a new 2433form of linkage, which we'll call ``hidden linkage''. Two 2434declarations of an object with hidden linkage refer to the same object 2435if they are in the same shared object. 2436 2437@item internal 2438Internal visibility is like hidden visibility, but with additional 2439processor specific semantics. Unless otherwise specified by the 2440psABI, GCC defines internal visibility to mean that a function is 2441@emph{never} called from another module. Compare this with hidden 2442functions which, while they cannot be referenced directly by other 2443modules, can be referenced indirectly via function pointers. By 2444indicating that a function cannot be called from outside the module, 2445GCC may for instance omit the load of a PIC register since it is known 2446that the calling function loaded the correct value. 2447 2448@item protected 2449Protected visibility is like default visibility except that it 2450indicates that references within the defining module will bind to the 2451definition in that module. That is, the declared entity cannot be 2452overridden by another module. 2453 2454@end table 2455 2456All visibilities are supported on many, but not all, ELF targets 2457(supported when the assembler supports the @samp{.visibility} 2458pseudo-op). Default visibility is supported everywhere. Hidden 2459visibility is supported on Darwin targets. 2460 2461The visibility attribute should be applied only to declarations which 2462would otherwise have external linkage. The attribute should be applied 2463consistently, so that the same entity should not be declared with 2464different settings of the attribute. 2465 2466In C++, the visibility attribute applies to types as well as functions 2467and objects, because in C++ types have linkage. A class must not have 2468greater visibility than its non-static data member types and bases, 2469and class members default to the visibility of their class. Also, a 2470declaration without explicit visibility is limited to the visibility 2471of its type. 2472 2473In C++, you can mark member functions and static member variables of a 2474class with the visibility attribute. This is useful if if you know a 2475particular method or static member variable should only be used from 2476one shared object; then you can mark it hidden while the rest of the 2477class has default visibility. Care must be taken to avoid breaking 2478the One Definition Rule; for example, it is usually not useful to mark 2479an inline method as hidden without marking the whole class as hidden. 2480 2481A C++ namespace declaration can also have the visibility attribute. 2482This attribute applies only to the particular namespace body, not to 2483other definitions of the same namespace; it is equivalent to using 2484@samp{#pragma GCC visibility} before and after the namespace 2485definition (@pxref{Visibility Pragmas}). 2486 2487In C++, if a template argument has limited visibility, this 2488restriction is implicitly propagated to the template instantiation. 2489Otherwise, template instantiations and specializations default to the 2490visibility of their template. 2491 2492If both the template and enclosing class have explicit visibility, the 2493visibility from the template is used. 2494 2495@item warn_unused_result 2496@cindex @code{warn_unused_result} attribute 2497The @code{warn_unused_result} attribute causes a warning to be emitted 2498if a caller of the function with this attribute does not use its 2499return value. This is useful for functions where not checking 2500the result is either a security problem or always a bug, such as 2501@code{realloc}. 2502 2503@smallexample 2504int fn () __attribute__ ((warn_unused_result)); 2505int foo () 2506@{ 2507 if (fn () < 0) return -1; 2508 fn (); 2509 return 0; 2510@} 2511@end smallexample 2512 2513results in warning on line 5. 2514 2515@item weak 2516@cindex @code{weak} attribute 2517The @code{weak} attribute causes the declaration to be emitted as a weak 2518symbol rather than a global. This is primarily useful in defining 2519library functions which can be overridden in user code, though it can 2520also be used with non-function declarations. Weak symbols are supported 2521for ELF targets, and also for a.out targets when using the GNU assembler 2522and linker. 2523 2524@item weakref 2525@itemx weakref ("@var{target}") 2526@cindex @code{weakref} attribute 2527The @code{weakref} attribute marks a declaration as a weak reference. 2528Without arguments, it should be accompanied by an @code{alias} attribute 2529naming the target symbol. Optionally, the @var{target} may be given as 2530an argument to @code{weakref} itself. In either case, @code{weakref} 2531implicitly marks the declaration as @code{weak}. Without a 2532@var{target}, given as an argument to @code{weakref} or to @code{alias}, 2533@code{weakref} is equivalent to @code{weak}. 2534 2535@smallexample 2536static int x() __attribute__ ((weakref ("y"))); 2537/* is equivalent to... */ 2538static int x() __attribute__ ((weak, weakref, alias ("y"))); 2539/* and to... */ 2540static int x() __attribute__ ((weakref)); 2541static int x() __attribute__ ((alias ("y"))); 2542@end smallexample 2543 2544A weak reference is an alias that does not by itself require a 2545definition to be given for the target symbol. If the target symbol is 2546only referenced through weak references, then the becomes a @code{weak} 2547undefined symbol. If it is directly referenced, however, then such 2548strong references prevail, and a definition will be required for the 2549symbol, not necessarily in the same translation unit. 2550 2551The effect is equivalent to moving all references to the alias to a 2552separate translation unit, renaming the alias to the aliased symbol, 2553declaring it as weak, compiling the two separate translation units and 2554performing a reloadable link on them. 2555 2556At present, a declaration to which @code{weakref} is attached can 2557only be @code{static}. 2558 2559@item externally_visible 2560@cindex @code{externally_visible} attribute. 2561This attribute, attached to a global variable or function nullify 2562effect of @option{-fwhole-program} command line option, so the object 2563remain visible outside the current compilation unit 2564 2565@end table 2566 2567You can specify multiple attributes in a declaration by separating them 2568by commas within the double parentheses or by immediately following an 2569attribute declaration with another attribute declaration. 2570 2571@cindex @code{#pragma}, reason for not using 2572@cindex pragma, reason for not using 2573Some people object to the @code{__attribute__} feature, suggesting that 2574ISO C's @code{#pragma} should be used instead. At the time 2575@code{__attribute__} was designed, there were two reasons for not doing 2576this. 2577 2578@enumerate 2579@item 2580It is impossible to generate @code{#pragma} commands from a macro. 2581 2582@item 2583There is no telling what the same @code{#pragma} might mean in another 2584compiler. 2585@end enumerate 2586 2587These two reasons applied to almost any application that might have been 2588proposed for @code{#pragma}. It was basically a mistake to use 2589@code{#pragma} for @emph{anything}. 2590 2591The ISO C99 standard includes @code{_Pragma}, which now allows pragmas 2592to be generated from macros. In addition, a @code{#pragma GCC} 2593namespace is now in use for GCC-specific pragmas. However, it has been 2594found convenient to use @code{__attribute__} to achieve a natural 2595attachment of attributes to their corresponding declarations, whereas 2596@code{#pragma GCC} is of use for constructs that do not naturally form 2597part of the grammar. @xref{Other Directives,,Miscellaneous 2598Preprocessing Directives, cpp, The GNU C Preprocessor}. 2599 2600@node Attribute Syntax 2601@section Attribute Syntax 2602@cindex attribute syntax 2603 2604This section describes the syntax with which @code{__attribute__} may be 2605used, and the constructs to which attribute specifiers bind, for the C 2606language. Some details may vary for C++. Because of infelicities in 2607the grammar for attributes, some forms described here may not be 2608successfully parsed in all cases. 2609 2610There are some problems with the semantics of attributes in C++. For 2611example, there are no manglings for attributes, although they may affect 2612code generation, so problems may arise when attributed types are used in 2613conjunction with templates or overloading. Similarly, @code{typeid} 2614does not distinguish between types with different attributes. Support 2615for attributes in C++ may be restricted in future to attributes on 2616declarations only, but not on nested declarators. 2617 2618@xref{Function Attributes}, for details of the semantics of attributes 2619applying to functions. @xref{Variable Attributes}, for details of the 2620semantics of attributes applying to variables. @xref{Type Attributes}, 2621for details of the semantics of attributes applying to structure, union 2622and enumerated types. 2623 2624An @dfn{attribute specifier} is of the form 2625@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} 2626is a possibly empty comma-separated sequence of @dfn{attributes}, where 2627each attribute is one of the following: 2628 2629@itemize @bullet 2630@item 2631Empty. Empty attributes are ignored. 2632 2633@item 2634A word (which may be an identifier such as @code{unused}, or a reserved 2635word such as @code{const}). 2636 2637@item 2638A word, followed by, in parentheses, parameters for the attribute. 2639These parameters take one of the following forms: 2640 2641@itemize @bullet 2642@item 2643An identifier. For example, @code{mode} attributes use this form. 2644 2645@item 2646An identifier followed by a comma and a non-empty comma-separated list 2647of expressions. For example, @code{format} attributes use this form. 2648 2649@item 2650A possibly empty comma-separated list of expressions. For example, 2651@code{format_arg} attributes use this form with the list being a single 2652integer constant expression, and @code{alias} attributes use this form 2653with the list being a single string constant. 2654@end itemize 2655@end itemize 2656 2657An @dfn{attribute specifier list} is a sequence of one or more attribute 2658specifiers, not separated by any other tokens. 2659 2660In GNU C, an attribute specifier list may appear after the colon following a 2661label, other than a @code{case} or @code{default} label. The only 2662attribute it makes sense to use after a label is @code{unused}. This 2663feature is intended for code generated by programs which contains labels 2664that may be unused but which is compiled with @option{-Wall}. It would 2665not normally be appropriate to use in it human-written code, though it 2666could be useful in cases where the code that jumps to the label is 2667contained within an @code{#ifdef} conditional. GNU C++ does not permit 2668such placement of attribute lists, as it is permissible for a 2669declaration, which could begin with an attribute list, to be labelled in 2670C++. Declarations cannot be labelled in C90 or C99, so the ambiguity 2671does not arise there. 2672 2673An attribute specifier list may appear as part of a @code{struct}, 2674@code{union} or @code{enum} specifier. It may go either immediately 2675after the @code{struct}, @code{union} or @code{enum} keyword, or after 2676the closing brace. The former syntax is preferred. 2677Where attribute specifiers follow the closing brace, they are considered 2678to relate to the structure, union or enumerated type defined, not to any 2679enclosing declaration the type specifier appears in, and the type 2680defined is not complete until after the attribute specifiers. 2681@c Otherwise, there would be the following problems: a shift/reduce 2682@c conflict between attributes binding the struct/union/enum and 2683@c binding to the list of specifiers/qualifiers; and "aligned" 2684@c attributes could use sizeof for the structure, but the size could be 2685@c changed later by "packed" attributes. 2686 2687Otherwise, an attribute specifier appears as part of a declaration, 2688counting declarations of unnamed parameters and type names, and relates 2689to that declaration (which may be nested in another declaration, for 2690example in the case of a parameter declaration), or to a particular declarator 2691within a declaration. Where an 2692attribute specifier is applied to a parameter declared as a function or 2693an array, it should apply to the function or array rather than the 2694pointer to which the parameter is implicitly converted, but this is not 2695yet correctly implemented. 2696 2697Any list of specifiers and qualifiers at the start of a declaration may 2698contain attribute specifiers, whether or not such a list may in that 2699context contain storage class specifiers. (Some attributes, however, 2700are essentially in the nature of storage class specifiers, and only make 2701sense where storage class specifiers may be used; for example, 2702@code{section}.) There is one necessary limitation to this syntax: the 2703first old-style parameter declaration in a function definition cannot 2704begin with an attribute specifier, because such an attribute applies to 2705the function instead by syntax described below (which, however, is not 2706yet implemented in this case). In some other cases, attribute 2707specifiers are permitted by this grammar but not yet supported by the 2708compiler. All attribute specifiers in this place relate to the 2709declaration as a whole. In the obsolescent usage where a type of 2710@code{int} is implied by the absence of type specifiers, such a list of 2711specifiers and qualifiers may be an attribute specifier list with no 2712other specifiers or qualifiers. 2713 2714At present, the first parameter in a function prototype must have some 2715type specifier which is not an attribute specifier; this resolves an 2716ambiguity in the interpretation of @code{void f(int 2717(__attribute__((foo)) x))}, but is subject to change. At present, if 2718the parentheses of a function declarator contain only attributes then 2719those attributes are ignored, rather than yielding an error or warning 2720or implying a single parameter of type int, but this is subject to 2721change. 2722 2723An attribute specifier list may appear immediately before a declarator 2724(other than the first) in a comma-separated list of declarators in a 2725declaration of more than one identifier using a single list of 2726specifiers and qualifiers. Such attribute specifiers apply 2727only to the identifier before whose declarator they appear. For 2728example, in 2729 2730@smallexample 2731__attribute__((noreturn)) void d0 (void), 2732 __attribute__((format(printf, 1, 2))) d1 (const char *, ...), 2733 d2 (void) 2734@end smallexample 2735 2736@noindent 2737the @code{noreturn} attribute applies to all the functions 2738declared; the @code{format} attribute only applies to @code{d1}. 2739 2740An attribute specifier list may appear immediately before the comma, 2741@code{=} or semicolon terminating the declaration of an identifier other 2742than a function definition. At present, such attribute specifiers apply 2743to the declared object or function, but in future they may attach to the 2744outermost adjacent declarator. In simple cases there is no difference, 2745but, for example, in 2746 2747@smallexample 2748void (****f)(void) __attribute__((noreturn)); 2749@end smallexample 2750 2751@noindent 2752at present the @code{noreturn} attribute applies to @code{f}, which 2753causes a warning since @code{f} is not a function, but in future it may 2754apply to the function @code{****f}. The precise semantics of what 2755attributes in such cases will apply to are not yet specified. Where an 2756assembler name for an object or function is specified (@pxref{Asm 2757Labels}), at present the attribute must follow the @code{asm} 2758specification; in future, attributes before the @code{asm} specification 2759may apply to the adjacent declarator, and those after it to the declared 2760object or function. 2761 2762An attribute specifier list may, in future, be permitted to appear after 2763the declarator in a function definition (before any old-style parameter 2764declarations or the function body). 2765 2766Attribute specifiers may be mixed with type qualifiers appearing inside 2767the @code{[]} of a parameter array declarator, in the C99 construct by 2768which such qualifiers are applied to the pointer to which the array is 2769implicitly converted. Such attribute specifiers apply to the pointer, 2770not to the array, but at present this is not implemented and they are 2771ignored. 2772 2773An attribute specifier list may appear at the start of a nested 2774declarator. At present, there are some limitations in this usage: the 2775attributes correctly apply to the declarator, but for most individual 2776attributes the semantics this implies are not implemented. 2777When attribute specifiers follow the @code{*} of a pointer 2778declarator, they may be mixed with any type qualifiers present. 2779The following describes the formal semantics of this syntax. It will make the 2780most sense if you are familiar with the formal specification of 2781declarators in the ISO C standard. 2782 2783Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T 2784D1}, where @code{T} contains declaration specifiers that specify a type 2785@var{Type} (such as @code{int}) and @code{D1} is a declarator that 2786contains an identifier @var{ident}. The type specified for @var{ident} 2787for derived declarators whose type does not include an attribute 2788specifier is as in the ISO C standard. 2789 2790If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, 2791and the declaration @code{T D} specifies the type 2792``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 2793@code{T D1} specifies the type ``@var{derived-declarator-type-list} 2794@var{attribute-specifier-list} @var{Type}'' for @var{ident}. 2795 2796If @code{D1} has the form @code{* 2797@var{type-qualifier-and-attribute-specifier-list} D}, and the 2798declaration @code{T D} specifies the type 2799``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 2800@code{T D1} specifies the type ``@var{derived-declarator-type-list} 2801@var{type-qualifier-and-attribute-specifier-list} @var{Type}'' for 2802@var{ident}. 2803 2804For example, 2805 2806@smallexample 2807void (__attribute__((noreturn)) ****f) (void); 2808@end smallexample 2809 2810@noindent 2811specifies the type ``pointer to pointer to pointer to pointer to 2812non-returning function returning @code{void}''. As another example, 2813 2814@smallexample 2815char *__attribute__((aligned(8))) *f; 2816@end smallexample 2817 2818@noindent 2819specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. 2820Note again that this does not work with most attributes; for example, 2821the usage of @samp{aligned} and @samp{noreturn} attributes given above 2822is not yet supported. 2823 2824For compatibility with existing code written for compiler versions that 2825did not implement attributes on nested declarators, some laxity is 2826allowed in the placing of attributes. If an attribute that only applies 2827to types is applied to a declaration, it will be treated as applying to 2828the type of that declaration. If an attribute that only applies to 2829declarations is applied to the type of a declaration, it will be treated 2830as applying to that declaration; and, for compatibility with code 2831placing the attributes immediately before the identifier declared, such 2832an attribute applied to a function return type will be treated as 2833applying to the function type, and such an attribute applied to an array 2834element type will be treated as applying to the array type. If an 2835attribute that only applies to function types is applied to a 2836pointer-to-function type, it will be treated as applying to the pointer 2837target type; if such an attribute is applied to a function return type 2838that is not a pointer-to-function type, it will be treated as applying 2839to the function type. 2840 2841@node Function Prototypes 2842@section Prototypes and Old-Style Function Definitions 2843@cindex function prototype declarations 2844@cindex old-style function definitions 2845@cindex promotion of formal parameters 2846 2847GNU C extends ISO C to allow a function prototype to override a later 2848old-style non-prototype definition. Consider the following example: 2849 2850@smallexample 2851/* @r{Use prototypes unless the compiler is old-fashioned.} */ 2852#ifdef __STDC__ 2853#define P(x) x 2854#else 2855#define P(x) () 2856#endif 2857 2858/* @r{Prototype function declaration.} */ 2859int isroot P((uid_t)); 2860 2861/* @r{Old-style function definition.} */ 2862int 2863isroot (x) /* @r{??? lossage here ???} */ 2864 uid_t x; 2865@{ 2866 return x == 0; 2867@} 2868@end smallexample 2869 2870Suppose the type @code{uid_t} happens to be @code{short}. ISO C does 2871not allow this example, because subword arguments in old-style 2872non-prototype definitions are promoted. Therefore in this example the 2873function definition's argument is really an @code{int}, which does not 2874match the prototype argument type of @code{short}. 2875 2876This restriction of ISO C makes it hard to write code that is portable 2877to traditional C compilers, because the programmer does not know 2878whether the @code{uid_t} type is @code{short}, @code{int}, or 2879@code{long}. Therefore, in cases like these GNU C allows a prototype 2880to override a later old-style definition. More precisely, in GNU C, a 2881function prototype argument type overrides the argument type specified 2882by a later old-style definition if the former type is the same as the 2883latter type before promotion. Thus in GNU C the above example is 2884equivalent to the following: 2885 2886@smallexample 2887int isroot (uid_t); 2888 2889int 2890isroot (uid_t x) 2891@{ 2892 return x == 0; 2893@} 2894@end smallexample 2895 2896@noindent 2897GNU C++ does not support old-style function definitions, so this 2898extension is irrelevant. 2899 2900@node C++ Comments 2901@section C++ Style Comments 2902@cindex // 2903@cindex C++ comments 2904@cindex comments, C++ style 2905 2906In GNU C, you may use C++ style comments, which start with @samp{//} and 2907continue until the end of the line. Many other C implementations allow 2908such comments, and they are included in the 1999 C standard. However, 2909C++ style comments are not recognized if you specify an @option{-std} 2910option specifying a version of ISO C before C99, or @option{-ansi} 2911(equivalent to @option{-std=c89}). 2912 2913@node Dollar Signs 2914@section Dollar Signs in Identifier Names 2915@cindex $ 2916@cindex dollar signs in identifier names 2917@cindex identifier names, dollar signs in 2918 2919In GNU C, you may normally use dollar signs in identifier names. 2920This is because many traditional C implementations allow such identifiers. 2921However, dollar signs in identifiers are not supported on a few target 2922machines, typically because the target assembler does not allow them. 2923 2924@node Character Escapes 2925@section The Character @key{ESC} in Constants 2926 2927You can use the sequence @samp{\e} in a string or character constant to 2928stand for the ASCII character @key{ESC}. 2929 2930@node Alignment 2931@section Inquiring on Alignment of Types or Variables 2932@cindex alignment 2933@cindex type alignment 2934@cindex variable alignment 2935 2936The keyword @code{__alignof__} allows you to inquire about how an object 2937is aligned, or the minimum alignment usually required by a type. Its 2938syntax is just like @code{sizeof}. 2939 2940For example, if the target machine requires a @code{double} value to be 2941aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. 2942This is true on many RISC machines. On more traditional machine 2943designs, @code{__alignof__ (double)} is 4 or even 2. 2944 2945Some machines never actually require alignment; they allow reference to any 2946data type even at an odd address. For these machines, @code{__alignof__} 2947reports the @emph{recommended} alignment of a type. 2948 2949If the operand of @code{__alignof__} is an lvalue rather than a type, 2950its value is the required alignment for its type, taking into account 2951any minimum alignment specified with GCC's @code{__attribute__} 2952extension (@pxref{Variable Attributes}). For example, after this 2953declaration: 2954 2955@smallexample 2956struct foo @{ int x; char y; @} foo1; 2957@end smallexample 2958 2959@noindent 2960the value of @code{__alignof__ (foo1.y)} is 1, even though its actual 2961alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. 2962 2963It is an error to ask for the alignment of an incomplete type. 2964 2965@node Variable Attributes 2966@section Specifying Attributes of Variables 2967@cindex attribute of variables 2968@cindex variable attributes 2969 2970The keyword @code{__attribute__} allows you to specify special 2971attributes of variables or structure fields. This keyword is followed 2972by an attribute specification inside double parentheses. Some 2973attributes are currently defined generically for variables. 2974Other attributes are defined for variables on particular target 2975systems. Other attributes are available for functions 2976(@pxref{Function Attributes}) and for types (@pxref{Type Attributes}). 2977Other front ends might define more attributes 2978(@pxref{C++ Extensions,,Extensions to the C++ Language}). 2979 2980You may also specify attributes with @samp{__} preceding and following 2981each keyword. This allows you to use them in header files without 2982being concerned about a possible macro of the same name. For example, 2983you may use @code{__aligned__} instead of @code{aligned}. 2984 2985@xref{Attribute Syntax}, for details of the exact syntax for using 2986attributes. 2987 2988@table @code 2989@cindex @code{aligned} attribute 2990@item aligned (@var{alignment}) 2991This attribute specifies a minimum alignment for the variable or 2992structure field, measured in bytes. For example, the declaration: 2993 2994@smallexample 2995int x __attribute__ ((aligned (16))) = 0; 2996@end smallexample 2997 2998@noindent 2999causes the compiler to allocate the global variable @code{x} on a 300016-byte boundary. On a 68040, this could be used in conjunction with 3001an @code{asm} expression to access the @code{move16} instruction which 3002requires 16-byte aligned operands. 3003 3004You can also specify the alignment of structure fields. For example, to 3005create a double-word aligned @code{int} pair, you could write: 3006 3007@smallexample 3008struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; 3009@end smallexample 3010 3011@noindent 3012This is an alternative to creating a union with a @code{double} member 3013that forces the union to be double-word aligned. 3014 3015As in the preceding examples, you can explicitly specify the alignment 3016(in bytes) that you wish the compiler to use for a given variable or 3017structure field. Alternatively, you can leave out the alignment factor 3018and just ask the compiler to align a variable or field to the maximum 3019useful alignment for the target machine you are compiling for. For 3020example, you could write: 3021 3022@smallexample 3023short array[3] __attribute__ ((aligned)); 3024@end smallexample 3025 3026Whenever you leave out the alignment factor in an @code{aligned} attribute 3027specification, the compiler automatically sets the alignment for the declared 3028variable or field to the largest alignment which is ever used for any data 3029type on the target machine you are compiling for. Doing this can often make 3030copy operations more efficient, because the compiler can use whatever 3031instructions copy the biggest chunks of memory when performing copies to 3032or from the variables or fields that you have aligned this way. 3033 3034The @code{aligned} attribute can only increase the alignment; but you 3035can decrease it by specifying @code{packed} as well. See below. 3036 3037Note that the effectiveness of @code{aligned} attributes may be limited 3038by inherent limitations in your linker. On many systems, the linker is 3039only able to arrange for variables to be aligned up to a certain maximum 3040alignment. (For some linkers, the maximum supported alignment may 3041be very very small.) If your linker is only able to align variables 3042up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} 3043in an @code{__attribute__} will still only provide you with 8 byte 3044alignment. See your linker documentation for further information. 3045 3046@item cleanup (@var{cleanup_function}) 3047@cindex @code{cleanup} attribute 3048The @code{cleanup} attribute runs a function when the variable goes 3049out of scope. This attribute can only be applied to auto function 3050scope variables; it may not be applied to parameters or variables 3051with static storage duration. The function must take one parameter, 3052a pointer to a type compatible with the variable. The return value 3053of the function (if any) is ignored. 3054 3055If @option{-fexceptions} is enabled, then @var{cleanup_function} 3056will be run during the stack unwinding that happens during the 3057processing of the exception. Note that the @code{cleanup} attribute 3058does not allow the exception to be caught, only to perform an action. 3059It is undefined what happens if @var{cleanup_function} does not 3060return normally. 3061 3062@item common 3063@itemx nocommon 3064@cindex @code{common} attribute 3065@cindex @code{nocommon} attribute 3066@opindex fcommon 3067@opindex fno-common 3068The @code{common} attribute requests GCC to place a variable in 3069``common'' storage. The @code{nocommon} attribute requests the 3070opposite---to allocate space for it directly. 3071 3072These attributes override the default chosen by the 3073@option{-fno-common} and @option{-fcommon} flags respectively. 3074 3075@item deprecated 3076@cindex @code{deprecated} attribute 3077The @code{deprecated} attribute results in a warning if the variable 3078is used anywhere in the source file. This is useful when identifying 3079variables that are expected to be removed in a future version of a 3080program. The warning also includes the location of the declaration 3081of the deprecated variable, to enable users to easily find further 3082information about why the variable is deprecated, or what they should 3083do instead. Note that the warning only occurs for uses: 3084 3085@smallexample 3086extern int old_var __attribute__ ((deprecated)); 3087extern int old_var; 3088int new_fn () @{ return old_var; @} 3089@end smallexample 3090 3091results in a warning on line 3 but not line 2. 3092 3093The @code{deprecated} attribute can also be used for functions and 3094types (@pxref{Function Attributes}, @pxref{Type Attributes}.) 3095 3096@item mode (@var{mode}) 3097@cindex @code{mode} attribute 3098This attribute specifies the data type for the declaration---whichever 3099type corresponds to the mode @var{mode}. This in effect lets you 3100request an integer or floating point type according to its width. 3101 3102You may also specify a mode of @samp{byte} or @samp{__byte__} to 3103indicate the mode corresponding to a one-byte integer, @samp{word} or 3104@samp{__word__} for the mode of a one-word integer, and @samp{pointer} 3105or @samp{__pointer__} for the mode used to represent pointers. 3106 3107@item packed 3108@cindex @code{packed} attribute 3109The @code{packed} attribute specifies that a variable or structure field 3110should have the smallest possible alignment---one byte for a variable, 3111and one bit for a field, unless you specify a larger value with the 3112@code{aligned} attribute. 3113 3114Here is a structure in which the field @code{x} is packed, so that it 3115immediately follows @code{a}: 3116 3117@smallexample 3118struct foo 3119@{ 3120 char a; 3121 int x[2] __attribute__ ((packed)); 3122@}; 3123@end smallexample 3124 3125@item section ("@var{section-name}") 3126@cindex @code{section} variable attribute 3127Normally, the compiler places the objects it generates in sections like 3128@code{data} and @code{bss}. Sometimes, however, you need additional sections, 3129or you need certain particular variables to appear in special sections, 3130for example to map to special hardware. The @code{section} 3131attribute specifies that a variable (or function) lives in a particular 3132section. For example, this small program uses several specific section names: 3133 3134@smallexample 3135struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; 3136struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; 3137char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; 3138int init_data __attribute__ ((section ("INITDATA"))) = 0; 3139 3140main() 3141@{ 3142 /* @r{Initialize stack pointer} */ 3143 init_sp (stack + sizeof (stack)); 3144 3145 /* @r{Initialize initialized data} */ 3146 memcpy (&init_data, &data, &edata - &data); 3147 3148 /* @r{Turn on the serial ports} */ 3149 init_duart (&a); 3150 init_duart (&b); 3151@} 3152@end smallexample 3153 3154@noindent 3155Use the @code{section} attribute with an @emph{initialized} definition 3156of a @emph{global} variable, as shown in the example. GCC issues 3157a warning and otherwise ignores the @code{section} attribute in 3158uninitialized variable declarations. 3159 3160You may only use the @code{section} attribute with a fully initialized 3161global definition because of the way linkers work. The linker requires 3162each object be defined once, with the exception that uninitialized 3163variables tentatively go in the @code{common} (or @code{bss}) section 3164and can be multiply ``defined''. You can force a variable to be 3165initialized with the @option{-fno-common} flag or the @code{nocommon} 3166attribute. 3167 3168Some file formats do not support arbitrary sections so the @code{section} 3169attribute is not available on all platforms. 3170If you need to map the entire contents of a module to a particular 3171section, consider using the facilities of the linker instead. 3172 3173@item shared 3174@cindex @code{shared} variable attribute 3175On Microsoft Windows, in addition to putting variable definitions in a named 3176section, the section can also be shared among all running copies of an 3177executable or DLL@. For example, this small program defines shared data 3178by putting it in a named section @code{shared} and marking the section 3179shareable: 3180 3181@smallexample 3182int foo __attribute__((section ("shared"), shared)) = 0; 3183 3184int 3185main() 3186@{ 3187 /* @r{Read and write foo. All running 3188 copies see the same value.} */ 3189 return 0; 3190@} 3191@end smallexample 3192 3193@noindent 3194You may only use the @code{shared} attribute along with @code{section} 3195attribute with a fully initialized global definition because of the way 3196linkers work. See @code{section} attribute for more information. 3197 3198The @code{shared} attribute is only available on Microsoft Windows@. 3199 3200@item tls_model ("@var{tls_model}") 3201@cindex @code{tls_model} attribute 3202The @code{tls_model} attribute sets thread-local storage model 3203(@pxref{Thread-Local}) of a particular @code{__thread} variable, 3204overriding @option{-ftls-model=} command line switch on a per-variable 3205basis. 3206The @var{tls_model} argument should be one of @code{global-dynamic}, 3207@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. 3208 3209Not all targets support this attribute. 3210 3211@item unused 3212This attribute, attached to a variable, means that the variable is meant 3213to be possibly unused. GCC will not produce a warning for this 3214variable. 3215 3216@item used 3217This attribute, attached to a variable, means that the variable must be 3218emitted even if it appears that the variable is not referenced. 3219 3220@item vector_size (@var{bytes}) 3221This attribute specifies the vector size for the variable, measured in 3222bytes. For example, the declaration: 3223 3224@smallexample 3225int foo __attribute__ ((vector_size (16))); 3226@end smallexample 3227 3228@noindent 3229causes the compiler to set the mode for @code{foo}, to be 16 bytes, 3230divided into @code{int} sized units. Assuming a 32-bit int (a vector of 32314 units of 4 bytes), the corresponding mode of @code{foo} will be V4SI@. 3232 3233This attribute is only applicable to integral and float scalars, 3234although arrays, pointers, and function return values are allowed in 3235conjunction with this construct. 3236 3237Aggregates with this attribute are invalid, even if they are of the same 3238size as a corresponding scalar. For example, the declaration: 3239 3240@smallexample 3241struct S @{ int a; @}; 3242struct S __attribute__ ((vector_size (16))) foo; 3243@end smallexample 3244 3245@noindent 3246is invalid even if the size of the structure is the same as the size of 3247the @code{int}. 3248 3249@item selectany 3250The @code{selectany} attribute causes an initialized global variable to 3251have link-once semantics. When multiple definitions of the variable are 3252encountered by the linker, the first is selected and the remainder are 3253discarded. Following usage by the Microsoft compiler, the linker is told 3254@emph{not} to warn about size or content differences of the multiple 3255definitions. 3256 3257Although the primary usage of this attribute is for POD types, the 3258attribute can also be applied to global C++ objects that are initialized 3259by a constructor. In this case, the static initialization and destruction 3260code for the object is emitted in each translation defining the object, 3261but the calls to the constructor and destructor are protected by a 3262link-once guard variable. 3263 3264The @code{selectany} attribute is only available on Microsoft Windows 3265targets. You can use @code{__declspec (selectany)} as a synonym for 3266@code{__attribute__ ((selectany))} for compatibility with other 3267compilers. 3268 3269@item weak 3270The @code{weak} attribute is described in @xref{Function Attributes}. 3271 3272@item dllimport 3273The @code{dllimport} attribute is described in @xref{Function Attributes}. 3274 3275@item dllexport 3276The @code{dllexport} attribute is described in @xref{Function Attributes}. 3277 3278@end table 3279 3280@subsection M32R/D Variable Attributes 3281 3282One attribute is currently defined for the M32R/D@. 3283 3284@table @code 3285@item model (@var{model-name}) 3286@cindex variable addressability on the M32R/D 3287Use this attribute on the M32R/D to set the addressability of an object. 3288The identifier @var{model-name} is one of @code{small}, @code{medium}, 3289or @code{large}, representing each of the code models. 3290 3291Small model objects live in the lower 16MB of memory (so that their 3292addresses can be loaded with the @code{ld24} instruction). 3293 3294Medium and large model objects may live anywhere in the 32-bit address space 3295(the compiler will generate @code{seth/add3} instructions to load their 3296addresses). 3297@end table 3298 3299@anchor{i386 Variable Attributes} 3300@subsection i386 Variable Attributes 3301 3302Two attributes are currently defined for i386 configurations: 3303@code{ms_struct} and @code{gcc_struct} 3304 3305@table @code 3306@item ms_struct 3307@itemx gcc_struct 3308@cindex @code{ms_struct} attribute 3309@cindex @code{gcc_struct} attribute 3310 3311If @code{packed} is used on a structure, or if bit-fields are used 3312it may be that the Microsoft ABI packs them differently 3313than GCC would normally pack them. Particularly when moving packed 3314data between functions compiled with GCC and the native Microsoft compiler 3315(either via function call or as data in a file), it may be necessary to access 3316either format. 3317 3318Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 3319compilers to match the native Microsoft compiler. 3320 3321The Microsoft structure layout algorithm is fairly simple with the exception 3322of the bitfield packing: 3323 3324The padding and alignment of members of structures and whether a bit field 3325can straddle a storage-unit boundary 3326 3327@enumerate 3328@item Structure members are stored sequentially in the order in which they are 3329declared: the first member has the lowest memory address and the last member 3330the highest. 3331 3332@item Every data object has an alignment-requirement. The alignment-requirement 3333for all data except structures, unions, and arrays is either the size of the 3334object or the current packing size (specified with either the aligned attribute 3335or the pack pragma), whichever is less. For structures, unions, and arrays, 3336the alignment-requirement is the largest alignment-requirement of its members. 3337Every object is allocated an offset so that: 3338 3339offset % alignment-requirement == 0 3340 3341@item Adjacent bit fields are packed into the same 1-, 2-, or 4-byte allocation 3342unit if the integral types are the same size and if the next bit field fits 3343into the current allocation unit without crossing the boundary imposed by the 3344common alignment requirements of the bit fields. 3345@end enumerate 3346 3347Handling of zero-length bitfields: 3348 3349MSVC interprets zero-length bitfields in the following ways: 3350 3351@enumerate 3352@item If a zero-length bitfield is inserted between two bitfields that would 3353normally be coalesced, the bitfields will not be coalesced. 3354 3355For example: 3356 3357@smallexample 3358struct 3359 @{ 3360 unsigned long bf_1 : 12; 3361 unsigned long : 0; 3362 unsigned long bf_2 : 12; 3363 @} t1; 3364@end smallexample 3365 3366The size of @code{t1} would be 8 bytes with the zero-length bitfield. If the 3367zero-length bitfield were removed, @code{t1}'s size would be 4 bytes. 3368 3369@item If a zero-length bitfield is inserted after a bitfield, @code{foo}, and the 3370alignment of the zero-length bitfield is greater than the member that follows it, 3371@code{bar}, @code{bar} will be aligned as the type of the zero-length bitfield. 3372 3373For example: 3374 3375@smallexample 3376struct 3377 @{ 3378 char foo : 4; 3379 short : 0; 3380 char bar; 3381 @} t2; 3382 3383struct 3384 @{ 3385 char foo : 4; 3386 short : 0; 3387 double bar; 3388 @} t3; 3389@end smallexample 3390 3391For @code{t2}, @code{bar} will be placed at offset 2, rather than offset 1. 3392Accordingly, the size of @code{t2} will be 4. For @code{t3}, the zero-length 3393bitfield will not affect the alignment of @code{bar} or, as a result, the size 3394of the structure. 3395 3396Taking this into account, it is important to note the following: 3397 3398@enumerate 3399@item If a zero-length bitfield follows a normal bitfield, the type of the 3400zero-length bitfield may affect the alignment of the structure as whole. For 3401example, @code{t2} has a size of 4 bytes, since the zero-length bitfield follows a 3402normal bitfield, and is of type short. 3403 3404@item Even if a zero-length bitfield is not followed by a normal bitfield, it may 3405still affect the alignment of the structure: 3406 3407@smallexample 3408struct 3409 @{ 3410 char foo : 6; 3411 long : 0; 3412 @} t4; 3413@end smallexample 3414 3415Here, @code{t4} will take up 4 bytes. 3416@end enumerate 3417 3418@item Zero-length bitfields following non-bitfield members are ignored: 3419 3420@smallexample 3421struct 3422 @{ 3423 char foo; 3424 long : 0; 3425 char bar; 3426 @} t5; 3427@end smallexample 3428 3429Here, @code{t5} will take up 2 bytes. 3430@end enumerate 3431@end table 3432 3433@subsection PowerPC Variable Attributes 3434 3435Three attributes currently are defined for PowerPC configurations: 3436@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 3437 3438For full documentation of the struct attributes please see the 3439documentation in the @xref{i386 Variable Attributes}, section. 3440 3441For documentation of @code{altivec} attribute please see the 3442documentation in the @xref{PowerPC Type Attributes}, section. 3443 3444@subsection Xstormy16 Variable Attributes 3445 3446One attribute is currently defined for xstormy16 configurations: 3447@code{below100} 3448 3449@table @code 3450@item below100 3451@cindex @code{below100} attribute 3452 3453If a variable has the @code{below100} attribute (@code{BELOW100} is 3454allowed also), GCC will place the variable in the first 0x100 bytes of 3455memory and use special opcodes to access it. Such variables will be 3456placed in either the @code{.bss_below100} section or the 3457@code{.data_below100} section. 3458 3459@end table 3460 3461@node Type Attributes 3462@section Specifying Attributes of Types 3463@cindex attribute of types 3464@cindex type attributes 3465 3466The keyword @code{__attribute__} allows you to specify special 3467attributes of @code{struct} and @code{union} types when you define 3468such types. This keyword is followed by an attribute specification 3469inside double parentheses. Seven attributes are currently defined for 3470types: @code{aligned}, @code{packed}, @code{transparent_union}, 3471@code{unused}, @code{deprecated}, @code{visibility}, and 3472@code{may_alias}. Other attributes are defined for functions 3473(@pxref{Function Attributes}) and for variables (@pxref{Variable 3474Attributes}). 3475 3476You may also specify any one of these attributes with @samp{__} 3477preceding and following its keyword. This allows you to use these 3478attributes in header files without being concerned about a possible 3479macro of the same name. For example, you may use @code{__aligned__} 3480instead of @code{aligned}. 3481 3482You may specify type attributes either in a @code{typedef} declaration 3483or in an enum, struct or union type declaration or definition. 3484 3485For an enum, struct or union type, you may specify attributes either 3486between the enum, struct or union tag and the name of the type, or 3487just past the closing curly brace of the @emph{definition}. The 3488former syntax is preferred. 3489 3490@xref{Attribute Syntax}, for details of the exact syntax for using 3491attributes. 3492 3493@table @code 3494@cindex @code{aligned} attribute 3495@item aligned (@var{alignment}) 3496This attribute specifies a minimum alignment (in bytes) for variables 3497of the specified type. For example, the declarations: 3498 3499@smallexample 3500struct S @{ short f[3]; @} __attribute__ ((aligned (8))); 3501typedef int more_aligned_int __attribute__ ((aligned (8))); 3502@end smallexample 3503 3504@noindent 3505force the compiler to insure (as far as it can) that each variable whose 3506type is @code{struct S} or @code{more_aligned_int} will be allocated and 3507aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all 3508variables of type @code{struct S} aligned to 8-byte boundaries allows 3509the compiler to use the @code{ldd} and @code{std} (doubleword load and 3510store) instructions when copying one variable of type @code{struct S} to 3511another, thus improving run-time efficiency. 3512 3513Note that the alignment of any given @code{struct} or @code{union} type 3514is required by the ISO C standard to be at least a perfect multiple of 3515the lowest common multiple of the alignments of all of the members of 3516the @code{struct} or @code{union} in question. This means that you @emph{can} 3517effectively adjust the alignment of a @code{struct} or @code{union} 3518type by attaching an @code{aligned} attribute to any one of the members 3519of such a type, but the notation illustrated in the example above is a 3520more obvious, intuitive, and readable way to request the compiler to 3521adjust the alignment of an entire @code{struct} or @code{union} type. 3522 3523As in the preceding example, you can explicitly specify the alignment 3524(in bytes) that you wish the compiler to use for a given @code{struct} 3525or @code{union} type. Alternatively, you can leave out the alignment factor 3526and just ask the compiler to align a type to the maximum 3527useful alignment for the target machine you are compiling for. For 3528example, you could write: 3529 3530@smallexample 3531struct S @{ short f[3]; @} __attribute__ ((aligned)); 3532@end smallexample 3533 3534Whenever you leave out the alignment factor in an @code{aligned} 3535attribute specification, the compiler automatically sets the alignment 3536for the type to the largest alignment which is ever used for any data 3537type on the target machine you are compiling for. Doing this can often 3538make copy operations more efficient, because the compiler can use 3539whatever instructions copy the biggest chunks of memory when performing 3540copies to or from the variables which have types that you have aligned 3541this way. 3542 3543In the example above, if the size of each @code{short} is 2 bytes, then 3544the size of the entire @code{struct S} type is 6 bytes. The smallest 3545power of two which is greater than or equal to that is 8, so the 3546compiler sets the alignment for the entire @code{struct S} type to 8 3547bytes. 3548 3549Note that although you can ask the compiler to select a time-efficient 3550alignment for a given type and then declare only individual stand-alone 3551objects of that type, the compiler's ability to select a time-efficient 3552alignment is primarily useful only when you plan to create arrays of 3553variables having the relevant (efficiently aligned) type. If you 3554declare or use arrays of variables of an efficiently-aligned type, then 3555it is likely that your program will also be doing pointer arithmetic (or 3556subscripting, which amounts to the same thing) on pointers to the 3557relevant type, and the code that the compiler generates for these 3558pointer arithmetic operations will often be more efficient for 3559efficiently-aligned types than for other types. 3560 3561The @code{aligned} attribute can only increase the alignment; but you 3562can decrease it by specifying @code{packed} as well. See below. 3563 3564Note that the effectiveness of @code{aligned} attributes may be limited 3565by inherent limitations in your linker. On many systems, the linker is 3566only able to arrange for variables to be aligned up to a certain maximum 3567alignment. (For some linkers, the maximum supported alignment may 3568be very very small.) If your linker is only able to align variables 3569up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} 3570in an @code{__attribute__} will still only provide you with 8 byte 3571alignment. See your linker documentation for further information. 3572 3573@item packed 3574This attribute, attached to @code{struct} or @code{union} type 3575definition, specifies that each member (other than zero-width bitfields) 3576of the structure or union is placed to minimize the memory required. When 3577attached to an @code{enum} definition, it indicates that the smallest 3578integral type should be used. 3579 3580@opindex fshort-enums 3581Specifying this attribute for @code{struct} and @code{union} types is 3582equivalent to specifying the @code{packed} attribute on each of the 3583structure or union members. Specifying the @option{-fshort-enums} 3584flag on the line is equivalent to specifying the @code{packed} 3585attribute on all @code{enum} definitions. 3586 3587In the following example @code{struct my_packed_struct}'s members are 3588packed closely together, but the internal layout of its @code{s} member 3589is not packed---to do that, @code{struct my_unpacked_struct} would need to 3590be packed too. 3591 3592@smallexample 3593struct my_unpacked_struct 3594 @{ 3595 char c; 3596 int i; 3597 @}; 3598 3599struct __attribute__ ((__packed__)) my_packed_struct 3600 @{ 3601 char c; 3602 int i; 3603 struct my_unpacked_struct s; 3604 @}; 3605@end smallexample 3606 3607You may only specify this attribute on the definition of a @code{enum}, 3608@code{struct} or @code{union}, not on a @code{typedef} which does not 3609also define the enumerated type, structure or union. 3610 3611@item transparent_union 3612This attribute, attached to a @code{union} type definition, indicates 3613that any function parameter having that union type causes calls to that 3614function to be treated in a special way. 3615 3616First, the argument corresponding to a transparent union type can be of 3617any type in the union; no cast is required. Also, if the union contains 3618a pointer type, the corresponding argument can be a null pointer 3619constant or a void pointer expression; and if the union contains a void 3620pointer type, the corresponding argument can be any pointer expression. 3621If the union member type is a pointer, qualifiers like @code{const} on 3622the referenced type must be respected, just as with normal pointer 3623conversions. 3624 3625Second, the argument is passed to the function using the calling 3626conventions of the first member of the transparent union, not the calling 3627conventions of the union itself. All members of the union must have the 3628same machine representation; this is necessary for this argument passing 3629to work properly. 3630 3631Transparent unions are designed for library functions that have multiple 3632interfaces for compatibility reasons. For example, suppose the 3633@code{wait} function must accept either a value of type @code{int *} to 3634comply with Posix, or a value of type @code{union wait *} to comply with 3635the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, 3636@code{wait} would accept both kinds of arguments, but it would also 3637accept any other pointer type and this would make argument type checking 3638less useful. Instead, @code{<sys/wait.h>} might define the interface 3639as follows: 3640 3641@smallexample 3642typedef union 3643 @{ 3644 int *__ip; 3645 union wait *__up; 3646 @} wait_status_ptr_t __attribute__ ((__transparent_union__)); 3647 3648pid_t wait (wait_status_ptr_t); 3649@end smallexample 3650 3651This interface allows either @code{int *} or @code{union wait *} 3652arguments to be passed, using the @code{int *} calling convention. 3653The program can call @code{wait} with arguments of either type: 3654 3655@smallexample 3656int w1 () @{ int w; return wait (&w); @} 3657int w2 () @{ union wait w; return wait (&w); @} 3658@end smallexample 3659 3660With this interface, @code{wait}'s implementation might look like this: 3661 3662@smallexample 3663pid_t wait (wait_status_ptr_t p) 3664@{ 3665 return waitpid (-1, p.__ip, 0); 3666@} 3667@end smallexample 3668 3669@item unused 3670When attached to a type (including a @code{union} or a @code{struct}), 3671this attribute means that variables of that type are meant to appear 3672possibly unused. GCC will not produce a warning for any variables of 3673that type, even if the variable appears to do nothing. This is often 3674the case with lock or thread classes, which are usually defined and then 3675not referenced, but contain constructors and destructors that have 3676nontrivial bookkeeping functions. 3677 3678@item deprecated 3679The @code{deprecated} attribute results in a warning if the type 3680is used anywhere in the source file. This is useful when identifying 3681types that are expected to be removed in a future version of a program. 3682If possible, the warning also includes the location of the declaration 3683of the deprecated type, to enable users to easily find further 3684information about why the type is deprecated, or what they should do 3685instead. Note that the warnings only occur for uses and then only 3686if the type is being applied to an identifier that itself is not being 3687declared as deprecated. 3688 3689@smallexample 3690typedef int T1 __attribute__ ((deprecated)); 3691T1 x; 3692typedef T1 T2; 3693T2 y; 3694typedef T1 T3 __attribute__ ((deprecated)); 3695T3 z __attribute__ ((deprecated)); 3696@end smallexample 3697 3698results in a warning on line 2 and 3 but not lines 4, 5, or 6. No 3699warning is issued for line 4 because T2 is not explicitly 3700deprecated. Line 5 has no warning because T3 is explicitly 3701deprecated. Similarly for line 6. 3702 3703The @code{deprecated} attribute can also be used for functions and 3704variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) 3705 3706@item may_alias 3707Accesses to objects with types with this attribute are not subjected to 3708type-based alias analysis, but are instead assumed to be able to alias 3709any other type of objects, just like the @code{char} type. See 3710@option{-fstrict-aliasing} for more information on aliasing issues. 3711 3712Example of use: 3713 3714@smallexample 3715typedef short __attribute__((__may_alias__)) short_a; 3716 3717int 3718main (void) 3719@{ 3720 int a = 0x12345678; 3721 short_a *b = (short_a *) &a; 3722 3723 b[1] = 0; 3724 3725 if (a == 0x12345678) 3726 abort(); 3727 3728 exit(0); 3729@} 3730@end smallexample 3731 3732If you replaced @code{short_a} with @code{short} in the variable 3733declaration, the above program would abort when compiled with 3734@option{-fstrict-aliasing}, which is on by default at @option{-O2} or 3735above in recent GCC versions. 3736 3737@item visibility 3738In C++, attribute visibility (@pxref{Function Attributes}) can also be 3739applied to class, struct, union and enum types. Unlike other type 3740attributes, the attribute must appear between the initial keyword and 3741the name of the type; it cannot appear after the body of the type. 3742 3743Note that the type visibility is applied to vague linkage entities 3744associated with the class (vtable, typeinfo node, etc.). In 3745particular, if a class is thrown as an exception in one shared object 3746and caught in another, the class must have default visibility. 3747Otherwise the two shared objects will be unable to use the same 3748typeinfo node and exception handling will break. 3749 3750@subsection ARM Type Attributes 3751 3752On those ARM targets that support @code{dllimport} (such as Symbian 3753OS), you can use the @code{notshared} attribute to indicate that the 3754virtual table and other similar data for a class should not be 3755exported from a DLL@. For example: 3756 3757@smallexample 3758class __declspec(notshared) C @{ 3759public: 3760 __declspec(dllimport) C(); 3761 virtual void f(); 3762@} 3763 3764__declspec(dllexport) 3765C::C() @{@} 3766@end smallexample 3767 3768In this code, @code{C::C} is exported from the current DLL, but the 3769virtual table for @code{C} is not exported. (You can use 3770@code{__attribute__} instead of @code{__declspec} if you prefer, but 3771most Symbian OS code uses @code{__declspec}.) 3772 3773@anchor{i386 Type Attributes} 3774@subsection i386 Type Attributes 3775 3776Two attributes are currently defined for i386 configurations: 3777@code{ms_struct} and @code{gcc_struct} 3778 3779@item ms_struct 3780@itemx gcc_struct 3781@cindex @code{ms_struct} 3782@cindex @code{gcc_struct} 3783 3784If @code{packed} is used on a structure, or if bit-fields are used 3785it may be that the Microsoft ABI packs them differently 3786than GCC would normally pack them. Particularly when moving packed 3787data between functions compiled with GCC and the native Microsoft compiler 3788(either via function call or as data in a file), it may be necessary to access 3789either format. 3790 3791Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 3792compilers to match the native Microsoft compiler. 3793@end table 3794 3795To specify multiple attributes, separate them by commas within the 3796double parentheses: for example, @samp{__attribute__ ((aligned (16), 3797packed))}. 3798 3799@anchor{PowerPC Type Attributes} 3800@subsection PowerPC Type Attributes 3801 3802Three attributes currently are defined for PowerPC configurations: 3803@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 3804 3805For full documentation of the struct attributes please see the 3806documentation in the @xref{i386 Type Attributes}, section. 3807 3808The @code{altivec} attribute allows one to declare AltiVec vector data 3809types supported by the AltiVec Programming Interface Manual. The 3810attribute requires an argument to specify one of three vector types: 3811@code{vector__}, @code{pixel__} (always followed by unsigned short), 3812and @code{bool__} (always followed by unsigned). 3813 3814@smallexample 3815__attribute__((altivec(vector__))) 3816__attribute__((altivec(pixel__))) unsigned short 3817__attribute__((altivec(bool__))) unsigned 3818@end smallexample 3819 3820These attributes mainly are intended to support the @code{__vector}, 3821@code{__pixel}, and @code{__bool} AltiVec keywords. 3822 3823@node Inline 3824@section An Inline Function is As Fast As a Macro 3825@cindex inline functions 3826@cindex integrating function code 3827@cindex open coding 3828@cindex macros, inline alternative 3829 3830By declaring a function inline, you can direct GCC to make 3831calls to that function faster. One way GCC can achieve this is to 3832integrate that function's code into the code for its callers. This 3833makes execution faster by eliminating the function-call overhead; in 3834addition, if any of the actual argument values are constant, their 3835known values may permit simplifications at compile time so that not 3836all of the inline function's code needs to be included. The effect on 3837code size is less predictable; object code may be larger or smaller 3838with function inlining, depending on the particular case. You can 3839also direct GCC to try to integrate all ``simple enough'' functions 3840into their callers with the option @option{-finline-functions}. 3841 3842GCC implements three different semantics of declaring a function 3843inline. One is available with @option{-std=gnu89}, another when 3844@option{-std=c99} or @option{-std=gnu99}, and the third is used when 3845compiling C++. 3846 3847To declare a function inline, use the @code{inline} keyword in its 3848declaration, like this: 3849 3850@smallexample 3851static inline int 3852inc (int *a) 3853@{ 3854 (*a)++; 3855@} 3856@end smallexample 3857 3858If you are writing a header file to be included in ISO C89 programs, write 3859@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. 3860 3861The three types of inlining behave similarly in two important cases: 3862when the @code{inline} keyword is used on a @code{static} function, 3863like the example above, and when a function is first declared without 3864using the @code{inline} keyword and then is defined with 3865@code{inline}, like this: 3866 3867@smallexample 3868extern int inc (int *a); 3869inline int 3870inc (int *a) 3871@{ 3872 (*a)++; 3873@} 3874@end smallexample 3875 3876In both of these common cases, the program behaves the same as if you 3877had not used the @code{inline} keyword, except for its speed. 3878 3879@cindex inline functions, omission of 3880@opindex fkeep-inline-functions 3881When a function is both inline and @code{static}, if all calls to the 3882function are integrated into the caller, and the function's address is 3883never used, then the function's own assembler code is never referenced. 3884In this case, GCC does not actually output assembler code for the 3885function, unless you specify the option @option{-fkeep-inline-functions}. 3886Some calls cannot be integrated for various reasons (in particular, 3887calls that precede the function's definition cannot be integrated, and 3888neither can recursive calls within the definition). If there is a 3889nonintegrated call, then the function is compiled to assembler code as 3890usual. The function must also be compiled as usual if the program 3891refers to its address, because that can't be inlined. 3892 3893@cindex automatic @code{inline} for C++ member fns 3894@cindex @code{inline} automatic for C++ member fns 3895@cindex member fns, automatically @code{inline} 3896@cindex C++ member fns, automatically @code{inline} 3897@opindex fno-default-inline 3898As required by ISO C++, GCC considers member functions defined within 3899the body of a class to be marked inline even if they are 3900not explicitly declared with the @code{inline} keyword. You can 3901override this with @option{-fno-default-inline}; @pxref{C++ Dialect 3902Options,,Options Controlling C++ Dialect}. 3903 3904GCC does not inline any functions when not optimizing unless you specify 3905the @samp{always_inline} attribute for the function, like this: 3906 3907@smallexample 3908/* @r{Prototype.} */ 3909inline void foo (const char) __attribute__((always_inline)); 3910@end smallexample 3911 3912The remainder of this section is specific to GNU C89 inlining. 3913 3914@cindex non-static inline function 3915When an inline function is not @code{static}, then the compiler must assume 3916that there may be calls from other source files; since a global symbol can 3917be defined only once in any program, the function must not be defined in 3918the other source files, so the calls therein cannot be integrated. 3919Therefore, a non-@code{static} inline function is always compiled on its 3920own in the usual fashion. 3921 3922If you specify both @code{inline} and @code{extern} in the function 3923definition, then the definition is used only for inlining. In no case 3924is the function compiled on its own, not even if you refer to its 3925address explicitly. Such an address becomes an external reference, as 3926if you had only declared the function, and had not defined it. 3927 3928This combination of @code{inline} and @code{extern} has almost the 3929effect of a macro. The way to use it is to put a function definition in 3930a header file with these keywords, and put another copy of the 3931definition (lacking @code{inline} and @code{extern}) in a library file. 3932The definition in the header file will cause most calls to the function 3933to be inlined. If any uses of the function remain, they will refer to 3934the single copy in the library. 3935 3936@node Extended Asm 3937@section Assembler Instructions with C Expression Operands 3938@cindex extended @code{asm} 3939@cindex @code{asm} expressions 3940@cindex assembler instructions 3941@cindex registers 3942 3943In an assembler instruction using @code{asm}, you can specify the 3944operands of the instruction using C expressions. This means you need not 3945guess which registers or memory locations will contain the data you want 3946to use. 3947 3948You must specify an assembler instruction template much like what 3949appears in a machine description, plus an operand constraint string for 3950each operand. 3951 3952For example, here is how to use the 68881's @code{fsinx} instruction: 3953 3954@smallexample 3955asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); 3956@end smallexample 3957 3958@noindent 3959Here @code{angle} is the C expression for the input operand while 3960@code{result} is that of the output operand. Each has @samp{"f"} as its 3961operand constraint, saying that a floating point register is required. 3962The @samp{=} in @samp{=f} indicates that the operand is an output; all 3963output operands' constraints must use @samp{=}. The constraints use the 3964same language used in the machine description (@pxref{Constraints}). 3965 3966Each operand is described by an operand-constraint string followed by 3967the C expression in parentheses. A colon separates the assembler 3968template from the first output operand and another separates the last 3969output operand from the first input, if any. Commas separate the 3970operands within each group. The total number of operands is currently 3971limited to 30; this limitation may be lifted in some future version of 3972GCC@. 3973 3974If there are no output operands but there are input operands, you must 3975place two consecutive colons surrounding the place where the output 3976operands would go. 3977 3978As of GCC version 3.1, it is also possible to specify input and output 3979operands using symbolic names which can be referenced within the 3980assembler code. These names are specified inside square brackets 3981preceding the constraint string, and can be referenced inside the 3982assembler code using @code{%[@var{name}]} instead of a percentage sign 3983followed by the operand number. Using named operands the above example 3984could look like: 3985 3986@smallexample 3987asm ("fsinx %[angle],%[output]" 3988 : [output] "=f" (result) 3989 : [angle] "f" (angle)); 3990@end smallexample 3991 3992@noindent 3993Note that the symbolic operand names have no relation whatsoever to 3994other C identifiers. You may use any name you like, even those of 3995existing C symbols, but you must ensure that no two operands within the same 3996assembler construct use the same symbolic name. 3997 3998Output operand expressions must be lvalues; the compiler can check this. 3999The input operands need not be lvalues. The compiler cannot check 4000whether the operands have data types that are reasonable for the 4001instruction being executed. It does not parse the assembler instruction 4002template and does not know what it means or even whether it is valid 4003assembler input. The extended @code{asm} feature is most often used for 4004machine instructions the compiler itself does not know exist. If 4005the output expression cannot be directly addressed (for example, it is a 4006bit-field), your constraint must allow a register. In that case, GCC 4007will use the register as the output of the @code{asm}, and then store 4008that register into the output. 4009 4010The ordinary output operands must be write-only; GCC will assume that 4011the values in these operands before the instruction are dead and need 4012not be generated. Extended asm supports input-output or read-write 4013operands. Use the constraint character @samp{+} to indicate such an 4014operand and list it with the output operands. You should only use 4015read-write operands when the constraints for the operand (or the 4016operand in which only some of the bits are to be changed) allow a 4017register. 4018 4019You may, as an alternative, logically split its function into two 4020separate operands, one input operand and one write-only output 4021operand. The connection between them is expressed by constraints 4022which say they need to be in the same location when the instruction 4023executes. You can use the same C expression for both operands, or 4024different expressions. For example, here we write the (fictitious) 4025@samp{combine} instruction with @code{bar} as its read-only source 4026operand and @code{foo} as its read-write destination: 4027 4028@smallexample 4029asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); 4030@end smallexample 4031 4032@noindent 4033The constraint @samp{"0"} for operand 1 says that it must occupy the 4034same location as operand 0. A number in constraint is allowed only in 4035an input operand and it must refer to an output operand. 4036 4037Only a number in the constraint can guarantee that one operand will be in 4038the same place as another. The mere fact that @code{foo} is the value 4039of both operands is not enough to guarantee that they will be in the 4040same place in the generated assembler code. The following would not 4041work reliably: 4042 4043@smallexample 4044asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); 4045@end smallexample 4046 4047Various optimizations or reloading could cause operands 0 and 1 to be in 4048different registers; GCC knows no reason not to do so. For example, the 4049compiler might find a copy of the value of @code{foo} in one register and 4050use it for operand 1, but generate the output operand 0 in a different 4051register (copying it afterward to @code{foo}'s own address). Of course, 4052since the register for operand 1 is not even mentioned in the assembler 4053code, the result will not work, but GCC can't tell that. 4054 4055As of GCC version 3.1, one may write @code{[@var{name}]} instead of 4056the operand number for a matching constraint. For example: 4057 4058@smallexample 4059asm ("cmoveq %1,%2,%[result]" 4060 : [result] "=r"(result) 4061 : "r" (test), "r"(new), "[result]"(old)); 4062@end smallexample 4063 4064Sometimes you need to make an @code{asm} operand be a specific register, 4065but there's no matching constraint letter for that register @emph{by 4066itself}. To force the operand into that register, use a local variable 4067for the operand and specify the register in the variable declaration. 4068@xref{Explicit Reg Vars}. Then for the @code{asm} operand, use any 4069register constraint letter that matches the register: 4070 4071@smallexample 4072register int *p1 asm ("r0") = @dots{}; 4073register int *p2 asm ("r1") = @dots{}; 4074register int *result asm ("r0"); 4075asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 4076@end smallexample 4077 4078@anchor{Example of asm with clobbered asm reg} 4079In the above example, beware that a register that is call-clobbered by 4080the target ABI will be overwritten by any function call in the 4081assignment, including library calls for arithmetic operators. 4082Assuming it is a call-clobbered register, this may happen to @code{r0} 4083above by the assignment to @code{p2}. If you have to use such a 4084register, use temporary variables for expressions between the register 4085assignment and use: 4086 4087@smallexample 4088int t1 = @dots{}; 4089register int *p1 asm ("r0") = @dots{}; 4090register int *p2 asm ("r1") = t1; 4091register int *result asm ("r0"); 4092asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 4093@end smallexample 4094 4095Some instructions clobber specific hard registers. To describe this, 4096write a third colon after the input operands, followed by the names of 4097the clobbered hard registers (given as strings). Here is a realistic 4098example for the VAX: 4099 4100@smallexample 4101asm volatile ("movc3 %0,%1,%2" 4102 : /* @r{no outputs} */ 4103 : "g" (from), "g" (to), "g" (count) 4104 : "r0", "r1", "r2", "r3", "r4", "r5"); 4105@end smallexample 4106 4107You may not write a clobber description in a way that overlaps with an 4108input or output operand. For example, you may not have an operand 4109describing a register class with one member if you mention that register 4110in the clobber list. Variables declared to live in specific registers 4111(@pxref{Explicit Reg Vars}), and used as asm input or output operands must 4112have no part mentioned in the clobber description. 4113There is no way for you to specify that an input 4114operand is modified without also specifying it as an output 4115operand. Note that if all the output operands you specify are for this 4116purpose (and hence unused), you will then also need to specify 4117@code{volatile} for the @code{asm} construct, as described below, to 4118prevent GCC from deleting the @code{asm} statement as unused. 4119 4120If you refer to a particular hardware register from the assembler code, 4121you will probably have to list the register after the third colon to 4122tell the compiler the register's value is modified. In some assemblers, 4123the register names begin with @samp{%}; to produce one @samp{%} in the 4124assembler code, you must write @samp{%%} in the input. 4125 4126If your assembler instruction can alter the condition code register, add 4127@samp{cc} to the list of clobbered registers. GCC on some machines 4128represents the condition codes as a specific hardware register; 4129@samp{cc} serves to name this register. On other machines, the 4130condition code is handled differently, and specifying @samp{cc} has no 4131effect. But it is valid no matter what the machine. 4132 4133If your assembler instructions access memory in an unpredictable 4134fashion, add @samp{memory} to the list of clobbered registers. This 4135will cause GCC to not keep memory values cached in registers across the 4136assembler instruction and not optimize stores or loads to that memory. 4137You will also want to add the @code{volatile} keyword if the memory 4138affected is not listed in the inputs or outputs of the @code{asm}, as 4139the @samp{memory} clobber does not count as a side-effect of the 4140@code{asm}. If you know how large the accessed memory is, you can add 4141it as input or output but if this is not known, you should add 4142@samp{memory}. As an example, if you access ten bytes of a string, you 4143can use a memory input like: 4144 4145@smallexample 4146@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}. 4147@end smallexample 4148 4149Note that in the following example the memory input is necessary, 4150otherwise GCC might optimize the store to @code{x} away: 4151@smallexample 4152int foo () 4153@{ 4154 int x = 42; 4155 int *y = &x; 4156 int result; 4157 asm ("magic stuff accessing an 'int' pointed to by '%1'" 4158 "=&d" (r) : "a" (y), "m" (*y)); 4159 return result; 4160@} 4161@end smallexample 4162 4163You can put multiple assembler instructions together in a single 4164@code{asm} template, separated by the characters normally used in assembly 4165code for the system. A combination that works in most places is a newline 4166to break the line, plus a tab character to move to the instruction field 4167(written as @samp{\n\t}). Sometimes semicolons can be used, if the 4168assembler allows semicolons as a line-breaking character. Note that some 4169assembler dialects use semicolons to start a comment. 4170The input operands are guaranteed not to use any of the clobbered 4171registers, and neither will the output operands' addresses, so you can 4172read and write the clobbered registers as many times as you like. Here 4173is an example of multiple instructions in a template; it assumes the 4174subroutine @code{_foo} accepts arguments in registers 9 and 10: 4175 4176@smallexample 4177asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo" 4178 : /* no outputs */ 4179 : "g" (from), "g" (to) 4180 : "r9", "r10"); 4181@end smallexample 4182 4183Unless an output operand has the @samp{&} constraint modifier, GCC 4184may allocate it in the same register as an unrelated input operand, on 4185the assumption the inputs are consumed before the outputs are produced. 4186This assumption may be false if the assembler code actually consists of 4187more than one instruction. In such a case, use @samp{&} for each output 4188operand that may not overlap an input. @xref{Modifiers}. 4189 4190If you want to test the condition code produced by an assembler 4191instruction, you must include a branch and a label in the @code{asm} 4192construct, as follows: 4193 4194@smallexample 4195asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:" 4196 : "g" (result) 4197 : "g" (input)); 4198@end smallexample 4199 4200@noindent 4201This assumes your assembler supports local labels, as the GNU assembler 4202and most Unix assemblers do. 4203 4204Speaking of labels, jumps from one @code{asm} to another are not 4205supported. The compiler's optimizers do not know about these jumps, and 4206therefore they cannot take account of them when deciding how to 4207optimize. 4208 4209@cindex macros containing @code{asm} 4210Usually the most convenient way to use these @code{asm} instructions is to 4211encapsulate them in macros that look like functions. For example, 4212 4213@smallexample 4214#define sin(x) \ 4215(@{ double __value, __arg = (x); \ 4216 asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ 4217 __value; @}) 4218@end smallexample 4219 4220@noindent 4221Here the variable @code{__arg} is used to make sure that the instruction 4222operates on a proper @code{double} value, and to accept only those 4223arguments @code{x} which can convert automatically to a @code{double}. 4224 4225Another way to make sure the instruction operates on the correct data 4226type is to use a cast in the @code{asm}. This is different from using a 4227variable @code{__arg} in that it converts more different types. For 4228example, if the desired type were @code{int}, casting the argument to 4229@code{int} would accept a pointer with no complaint, while assigning the 4230argument to an @code{int} variable named @code{__arg} would warn about 4231using a pointer unless the caller explicitly casts it. 4232 4233If an @code{asm} has output operands, GCC assumes for optimization 4234purposes the instruction has no side effects except to change the output 4235operands. This does not mean instructions with a side effect cannot be 4236used, but you must be careful, because the compiler may eliminate them 4237if the output operands aren't used, or move them out of loops, or 4238replace two with one if they constitute a common subexpression. Also, 4239if your instruction does have a side effect on a variable that otherwise 4240appears not to change, the old value of the variable may be reused later 4241if it happens to be found in a register. 4242 4243You can prevent an @code{asm} instruction from being deleted 4244by writing the keyword @code{volatile} after 4245the @code{asm}. For example: 4246 4247@smallexample 4248#define get_and_set_priority(new) \ 4249(@{ int __old; \ 4250 asm volatile ("get_and_set_priority %0, %1" \ 4251 : "=g" (__old) : "g" (new)); \ 4252 __old; @}) 4253@end smallexample 4254 4255@noindent 4256The @code{volatile} keyword indicates that the instruction has 4257important side-effects. GCC will not delete a volatile @code{asm} if 4258it is reachable. (The instruction can still be deleted if GCC can 4259prove that control-flow will never reach the location of the 4260instruction.) Note that even a volatile @code{asm} instruction 4261can be moved relative to other code, including across jump 4262instructions. For example, on many targets there is a system 4263register which can be set to control the rounding mode of 4264floating point operations. You might try 4265setting it with a volatile @code{asm}, like this PowerPC example: 4266 4267@smallexample 4268 asm volatile("mtfsf 255,%0" : : "f" (fpenv)); 4269 sum = x + y; 4270@end smallexample 4271 4272@noindent 4273This will not work reliably, as the compiler may move the addition back 4274before the volatile @code{asm}. To make it work you need to add an 4275artificial dependency to the @code{asm} referencing a variable in the code 4276you don't want moved, for example: 4277 4278@smallexample 4279 asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv)); 4280 sum = x + y; 4281@end smallexample 4282 4283Similarly, you can't expect a 4284sequence of volatile @code{asm} instructions to remain perfectly 4285consecutive. If you want consecutive output, use a single @code{asm}. 4286Also, GCC will perform some optimizations across a volatile @code{asm} 4287instruction; GCC does not ``forget everything'' when it encounters 4288a volatile @code{asm} instruction the way some other compilers do. 4289 4290An @code{asm} instruction without any output operands will be treated 4291identically to a volatile @code{asm} instruction. 4292 4293It is a natural idea to look for a way to give access to the condition 4294code left by the assembler instruction. However, when we attempted to 4295implement this, we found no way to make it work reliably. The problem 4296is that output operands might need reloading, which would result in 4297additional following ``store'' instructions. On most machines, these 4298instructions would alter the condition code before there was time to 4299test it. This problem doesn't arise for ordinary ``test'' and 4300``compare'' instructions because they don't have any output operands. 4301 4302For reasons similar to those described above, it is not possible to give 4303an assembler instruction access to the condition code left by previous 4304instructions. 4305 4306If you are writing a header file that should be includable in ISO C 4307programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate 4308Keywords}. 4309 4310@subsection Size of an @code{asm} 4311 4312Some targets require that GCC track the size of each instruction used in 4313order to generate correct code. Because the final length of an 4314@code{asm} is only known by the assembler, GCC must make an estimate as 4315to how big it will be. The estimate is formed by counting the number of 4316statements in the pattern of the @code{asm} and multiplying that by the 4317length of the longest instruction on that processor. Statements in the 4318@code{asm} are identified by newline characters and whatever statement 4319separator characters are supported by the assembler; on most processors 4320this is the `@code{;}' character. 4321 4322Normally, GCC's estimate is perfectly adequate to ensure that correct 4323code is generated, but it is possible to confuse the compiler if you use 4324pseudo instructions or assembler macros that expand into multiple real 4325instructions or if you use assembler directives that expand to more 4326space in the object file than would be needed for a single instruction. 4327If this happens then the assembler will produce a diagnostic saying that 4328a label is unreachable. 4329 4330@subsection i386 floating point asm operands 4331 4332There are several rules on the usage of stack-like regs in 4333asm_operands insns. These rules apply only to the operands that are 4334stack-like regs: 4335 4336@enumerate 4337@item 4338Given a set of input regs that die in an asm_operands, it is 4339necessary to know which are implicitly popped by the asm, and 4340which must be explicitly popped by gcc. 4341 4342An input reg that is implicitly popped by the asm must be 4343explicitly clobbered, unless it is constrained to match an 4344output operand. 4345 4346@item 4347For any input reg that is implicitly popped by an asm, it is 4348necessary to know how to adjust the stack to compensate for the pop. 4349If any non-popped input is closer to the top of the reg-stack than 4350the implicitly popped reg, it would not be possible to know what the 4351stack looked like---it's not clear how the rest of the stack ``slides 4352up''. 4353 4354All implicitly popped input regs must be closer to the top of 4355the reg-stack than any input that is not implicitly popped. 4356 4357It is possible that if an input dies in an insn, reload might 4358use the input reg for an output reload. Consider this example: 4359 4360@smallexample 4361asm ("foo" : "=t" (a) : "f" (b)); 4362@end smallexample 4363 4364This asm says that input B is not popped by the asm, and that 4365the asm pushes a result onto the reg-stack, i.e., the stack is one 4366deeper after the asm than it was before. But, it is possible that 4367reload will think that it can use the same reg for both the input and 4368the output, if input B dies in this insn. 4369 4370If any input operand uses the @code{f} constraint, all output reg 4371constraints must use the @code{&} earlyclobber. 4372 4373The asm above would be written as 4374 4375@smallexample 4376asm ("foo" : "=&t" (a) : "f" (b)); 4377@end smallexample 4378 4379@item 4380Some operands need to be in particular places on the stack. All 4381output operands fall in this category---there is no other way to 4382know which regs the outputs appear in unless the user indicates 4383this in the constraints. 4384 4385Output operands must specifically indicate which reg an output 4386appears in after an asm. @code{=f} is not allowed: the operand 4387constraints must select a class with a single reg. 4388 4389@item 4390Output operands may not be ``inserted'' between existing stack regs. 4391Since no 387 opcode uses a read/write operand, all output operands 4392are dead before the asm_operands, and are pushed by the asm_operands. 4393It makes no sense to push anywhere but the top of the reg-stack. 4394 4395Output operands must start at the top of the reg-stack: output 4396operands may not ``skip'' a reg. 4397 4398@item 4399Some asm statements may need extra stack space for internal 4400calculations. This can be guaranteed by clobbering stack registers 4401unrelated to the inputs and outputs. 4402 4403@end enumerate 4404 4405Here are a couple of reasonable asms to want to write. This asm 4406takes one input, which is internally popped, and produces two outputs. 4407 4408@smallexample 4409asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); 4410@end smallexample 4411 4412This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode, 4413and replaces them with one output. The user must code the @code{st(1)} 4414clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs. 4415 4416@smallexample 4417asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); 4418@end smallexample 4419 4420@include md.texi 4421 4422@node Asm Labels 4423@section Controlling Names Used in Assembler Code 4424@cindex assembler names for identifiers 4425@cindex names used in assembler code 4426@cindex identifiers, names in assembler code 4427 4428You can specify the name to be used in the assembler code for a C 4429function or variable by writing the @code{asm} (or @code{__asm__}) 4430keyword after the declarator as follows: 4431 4432@smallexample 4433int foo asm ("myfoo") = 2; 4434@end smallexample 4435 4436@noindent 4437This specifies that the name to be used for the variable @code{foo} in 4438the assembler code should be @samp{myfoo} rather than the usual 4439@samp{_foo}. 4440 4441On systems where an underscore is normally prepended to the name of a C 4442function or variable, this feature allows you to define names for the 4443linker that do not start with an underscore. 4444 4445It does not make sense to use this feature with a non-static local 4446variable since such variables do not have assembler names. If you are 4447trying to put the variable in a particular register, see @ref{Explicit 4448Reg Vars}. GCC presently accepts such code with a warning, but will 4449probably be changed to issue an error, rather than a warning, in the 4450future. 4451 4452You cannot use @code{asm} in this way in a function @emph{definition}; but 4453you can get the same effect by writing a declaration for the function 4454before its definition and putting @code{asm} there, like this: 4455 4456@smallexample 4457extern func () asm ("FUNC"); 4458 4459func (x, y) 4460 int x, y; 4461/* @r{@dots{}} */ 4462@end smallexample 4463 4464It is up to you to make sure that the assembler names you choose do not 4465conflict with any other assembler symbols. Also, you must not use a 4466register name; that would produce completely invalid assembler code. GCC 4467does not as yet have the ability to store static variables in registers. 4468Perhaps that will be added. 4469 4470@node Explicit Reg Vars 4471@section Variables in Specified Registers 4472@cindex explicit register variables 4473@cindex variables in specified registers 4474@cindex specified registers 4475@cindex registers, global allocation 4476 4477GNU C allows you to put a few global variables into specified hardware 4478registers. You can also specify the register in which an ordinary 4479register variable should be allocated. 4480 4481@itemize @bullet 4482@item 4483Global register variables reserve registers throughout the program. 4484This may be useful in programs such as programming language 4485interpreters which have a couple of global variables that are accessed 4486very often. 4487 4488@item 4489Local register variables in specific registers do not reserve the 4490registers, except at the point where they are used as input or output 4491operands in an @code{asm} statement and the @code{asm} statement itself is 4492not deleted. The compiler's data flow analysis is capable of determining 4493where the specified registers contain live values, and where they are 4494available for other uses. Stores into local register variables may be deleted 4495when they appear to be dead according to dataflow analysis. References 4496to local register variables may be deleted or moved or simplified. 4497 4498These local variables are sometimes convenient for use with the extended 4499@code{asm} feature (@pxref{Extended Asm}), if you want to write one 4500output of the assembler instruction directly into a particular register. 4501(This will work provided the register you specify fits the constraints 4502specified for that operand in the @code{asm}.) 4503@end itemize 4504 4505@menu 4506* Global Reg Vars:: 4507* Local Reg Vars:: 4508@end menu 4509 4510@node Global Reg Vars 4511@subsection Defining Global Register Variables 4512@cindex global register variables 4513@cindex registers, global variables in 4514 4515You can define a global register variable in GNU C like this: 4516 4517@smallexample 4518register int *foo asm ("a5"); 4519@end smallexample 4520 4521@noindent 4522Here @code{a5} is the name of the register which should be used. Choose a 4523register which is normally saved and restored by function calls on your 4524machine, so that library routines will not clobber it. 4525 4526Naturally the register name is cpu-dependent, so you would need to 4527conditionalize your program according to cpu type. The register 4528@code{a5} would be a good choice on a 68000 for a variable of pointer 4529type. On machines with register windows, be sure to choose a ``global'' 4530register that is not affected magically by the function call mechanism. 4531 4532In addition, operating systems on one type of cpu may differ in how they 4533name the registers; then you would need additional conditionals. For 4534example, some 68000 operating systems call this register @code{%a5}. 4535 4536Eventually there may be a way of asking the compiler to choose a register 4537automatically, but first we need to figure out how it should choose and 4538how to enable you to guide the choice. No solution is evident. 4539 4540Defining a global register variable in a certain register reserves that 4541register entirely for this use, at least within the current compilation. 4542The register will not be allocated for any other purpose in the functions 4543in the current compilation. The register will not be saved and restored by 4544these functions. Stores into this register are never deleted even if they 4545would appear to be dead, but references may be deleted or moved or 4546simplified. 4547 4548It is not safe to access the global register variables from signal 4549handlers, or from more than one thread of control, because the system 4550library routines may temporarily use the register for other things (unless 4551you recompile them specially for the task at hand). 4552 4553@cindex @code{qsort}, and global register variables 4554It is not safe for one function that uses a global register variable to 4555call another such function @code{foo} by way of a third function 4556@code{lose} that was compiled without knowledge of this variable (i.e.@: in a 4557different source file in which the variable wasn't declared). This is 4558because @code{lose} might save the register and put some other value there. 4559For example, you can't expect a global register variable to be available in 4560the comparison-function that you pass to @code{qsort}, since @code{qsort} 4561might have put something else in that register. (If you are prepared to 4562recompile @code{qsort} with the same global register variable, you can 4563solve this problem.) 4564 4565If you want to recompile @code{qsort} or other source files which do not 4566actually use your global register variable, so that they will not use that 4567register for any other purpose, then it suffices to specify the compiler 4568option @option{-ffixed-@var{reg}}. You need not actually add a global 4569register declaration to their source code. 4570 4571A function which can alter the value of a global register variable cannot 4572safely be called from a function compiled without this variable, because it 4573could clobber the value the caller expects to find there on return. 4574Therefore, the function which is the entry point into the part of the 4575program that uses the global register variable must explicitly save and 4576restore the value which belongs to its caller. 4577 4578@cindex register variable after @code{longjmp} 4579@cindex global register after @code{longjmp} 4580@cindex value after @code{longjmp} 4581@findex longjmp 4582@findex setjmp 4583On most machines, @code{longjmp} will restore to each global register 4584variable the value it had at the time of the @code{setjmp}. On some 4585machines, however, @code{longjmp} will not change the value of global 4586register variables. To be portable, the function that called @code{setjmp} 4587should make other arrangements to save the values of the global register 4588variables, and to restore them in a @code{longjmp}. This way, the same 4589thing will happen regardless of what @code{longjmp} does. 4590 4591All global register variable declarations must precede all function 4592definitions. If such a declaration could appear after function 4593definitions, the declaration would be too late to prevent the register from 4594being used for other purposes in the preceding functions. 4595 4596Global register variables may not have initial values, because an 4597executable file has no means to supply initial contents for a register. 4598 4599On the SPARC, there are reports that g3 @dots{} g7 are suitable 4600registers, but certain library functions, such as @code{getwd}, as well 4601as the subroutines for division and remainder, modify g3 and g4. g1 and 4602g2 are local temporaries. 4603 4604On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7. 4605Of course, it will not do to use more than a few of those. 4606 4607@node Local Reg Vars 4608@subsection Specifying Registers for Local Variables 4609@cindex local variables, specifying registers 4610@cindex specifying registers for local variables 4611@cindex registers for local variables 4612 4613You can define a local register variable with a specified register 4614like this: 4615 4616@smallexample 4617register int *foo asm ("a5"); 4618@end smallexample 4619 4620@noindent 4621Here @code{a5} is the name of the register which should be used. Note 4622that this is the same syntax used for defining global register 4623variables, but for a local variable it would appear within a function. 4624 4625Naturally the register name is cpu-dependent, but this is not a 4626problem, since specific registers are most often useful with explicit 4627assembler instructions (@pxref{Extended Asm}). Both of these things 4628generally require that you conditionalize your program according to 4629cpu type. 4630 4631In addition, operating systems on one type of cpu may differ in how they 4632name the registers; then you would need additional conditionals. For 4633example, some 68000 operating systems call this register @code{%a5}. 4634 4635Defining such a register variable does not reserve the register; it 4636remains available for other uses in places where flow control determines 4637the variable's value is not live. 4638 4639This option does not guarantee that GCC will generate code that has 4640this variable in the register you specify at all times. You may not 4641code an explicit reference to this register in the @emph{assembler 4642instruction template} part of an @code{asm} statement and assume it will 4643always refer to this variable. However, using the variable as an 4644@code{asm} @emph{operand} guarantees that the specified register is used 4645for the operand. 4646 4647Stores into local register variables may be deleted when they appear to be dead 4648according to dataflow analysis. References to local register variables may 4649be deleted or moved or simplified. 4650 4651As for global register variables, it's recommended that you choose a 4652register which is normally saved and restored by function calls on 4653your machine, so that library routines will not clobber it. A common 4654pitfall is to initialize multiple call-clobbered registers with 4655arbitrary expressions, where a function call or library call for an 4656arithmetic operator will overwrite a register value from a previous 4657assignment, for example @code{r0} below: 4658@smallexample 4659register int *p1 asm ("r0") = @dots{}; 4660register int *p2 asm ("r1") = @dots{}; 4661@end smallexample 4662In those cases, a solution is to use a temporary variable for 4663each arbitrary expression. @xref{Example of asm with clobbered asm reg}. 4664 4665@node Alternate Keywords 4666@section Alternate Keywords 4667@cindex alternate keywords 4668@cindex keywords, alternate 4669 4670@option{-ansi} and the various @option{-std} options disable certain 4671keywords. This causes trouble when you want to use GNU C extensions, or 4672a general-purpose header file that should be usable by all programs, 4673including ISO C programs. The keywords @code{asm}, @code{typeof} and 4674@code{inline} are not available in programs compiled with 4675@option{-ansi} or @option{-std} (although @code{inline} can be used in a 4676program compiled with @option{-std=c99}). The ISO C99 keyword 4677@code{restrict} is only available when @option{-std=gnu99} (which will 4678eventually be the default) or @option{-std=c99} (or the equivalent 4679@option{-std=iso9899:1999}) is used. 4680 4681The way to solve these problems is to put @samp{__} at the beginning and 4682end of each problematical keyword. For example, use @code{__asm__} 4683instead of @code{asm}, and @code{__inline__} instead of @code{inline}. 4684 4685Other C compilers won't accept these alternative keywords; if you want to 4686compile with another compiler, you can define the alternate keywords as 4687macros to replace them with the customary keywords. It looks like this: 4688 4689@smallexample 4690#ifndef __GNUC__ 4691#define __asm__ asm 4692#endif 4693@end smallexample 4694 4695@findex __extension__ 4696@opindex pedantic 4697@option{-pedantic} and other options cause warnings for many GNU C extensions. 4698You can 4699prevent such warnings within one expression by writing 4700@code{__extension__} before the expression. @code{__extension__} has no 4701effect aside from this. 4702 4703@node Incomplete Enums 4704@section Incomplete @code{enum} Types 4705 4706You can define an @code{enum} tag without specifying its possible values. 4707This results in an incomplete type, much like what you get if you write 4708@code{struct foo} without describing the elements. A later declaration 4709which does specify the possible values completes the type. 4710 4711You can't allocate variables or storage using the type while it is 4712incomplete. However, you can work with pointers to that type. 4713 4714This extension may not be very useful, but it makes the handling of 4715@code{enum} more consistent with the way @code{struct} and @code{union} 4716are handled. 4717 4718This extension is not supported by GNU C++. 4719 4720@node Function Names 4721@section Function Names as Strings 4722@cindex @code{__func__} identifier 4723@cindex @code{__FUNCTION__} identifier 4724@cindex @code{__PRETTY_FUNCTION__} identifier 4725 4726GCC provides three magic variables which hold the name of the current 4727function, as a string. The first of these is @code{__func__}, which 4728is part of the C99 standard: 4729 4730@display 4731The identifier @code{__func__} is implicitly declared by the translator 4732as if, immediately following the opening brace of each function 4733definition, the declaration 4734 4735@smallexample 4736static const char __func__[] = "function-name"; 4737@end smallexample 4738 4739appeared, where function-name is the name of the lexically-enclosing 4740function. This name is the unadorned name of the function. 4741@end display 4742 4743@code{__FUNCTION__} is another name for @code{__func__}. Older 4744versions of GCC recognize only this name. However, it is not 4745standardized. For maximum portability, we recommend you use 4746@code{__func__}, but provide a fallback definition with the 4747preprocessor: 4748 4749@smallexample 4750#if __STDC_VERSION__ < 199901L 4751# if __GNUC__ >= 2 4752# define __func__ __FUNCTION__ 4753# else 4754# define __func__ "<unknown>" 4755# endif 4756#endif 4757@end smallexample 4758 4759In C, @code{__PRETTY_FUNCTION__} is yet another name for 4760@code{__func__}. However, in C++, @code{__PRETTY_FUNCTION__} contains 4761the type signature of the function as well as its bare name. For 4762example, this program: 4763 4764@smallexample 4765extern "C" @{ 4766extern int printf (char *, ...); 4767@} 4768 4769class a @{ 4770 public: 4771 void sub (int i) 4772 @{ 4773 printf ("__FUNCTION__ = %s\n", __FUNCTION__); 4774 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); 4775 @} 4776@}; 4777 4778int 4779main (void) 4780@{ 4781 a ax; 4782 ax.sub (0); 4783 return 0; 4784@} 4785@end smallexample 4786 4787@noindent 4788gives this output: 4789 4790@smallexample 4791__FUNCTION__ = sub 4792__PRETTY_FUNCTION__ = void a::sub(int) 4793@end smallexample 4794 4795These identifiers are not preprocessor macros. In GCC 3.3 and 4796earlier, in C only, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} 4797were treated as string literals; they could be used to initialize 4798@code{char} arrays, and they could be concatenated with other string 4799literals. GCC 3.4 and later treat them as variables, like 4800@code{__func__}. In C++, @code{__FUNCTION__} and 4801@code{__PRETTY_FUNCTION__} have always been variables. 4802 4803@node Return Address 4804@section Getting the Return or Frame Address of a Function 4805 4806These functions may be used to get information about the callers of a 4807function. 4808 4809@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) 4810This function returns the return address of the current function, or of 4811one of its callers. The @var{level} argument is number of frames to 4812scan up the call stack. A value of @code{0} yields the return address 4813of the current function, a value of @code{1} yields the return address 4814of the caller of the current function, and so forth. When inlining 4815the expected behavior is that the function will return the address of 4816the function that will be returned to. To work around this behavior use 4817the @code{noinline} function attribute. 4818 4819The @var{level} argument must be a constant integer. 4820 4821On some machines it may be impossible to determine the return address of 4822any function other than the current one; in such cases, or when the top 4823of the stack has been reached, this function will return @code{0} or a 4824random value. In addition, @code{__builtin_frame_address} may be used 4825to determine if the top of the stack has been reached. 4826 4827This function should only be used with a nonzero argument for debugging 4828purposes. 4829@end deftypefn 4830 4831@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) 4832This function is similar to @code{__builtin_return_address}, but it 4833returns the address of the function frame rather than the return address 4834of the function. Calling @code{__builtin_frame_address} with a value of 4835@code{0} yields the frame address of the current function, a value of 4836@code{1} yields the frame address of the caller of the current function, 4837and so forth. 4838 4839The frame is the area on the stack which holds local variables and saved 4840registers. The frame address is normally the address of the first word 4841pushed on to the stack by the function. However, the exact definition 4842depends upon the processor and the calling convention. If the processor 4843has a dedicated frame pointer register, and the function has a frame, 4844then @code{__builtin_frame_address} will return the value of the frame 4845pointer register. 4846 4847On some machines it may be impossible to determine the frame 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} if 4850the first frame pointer is properly initialized by the startup code. 4851 4852This function should only be used with a nonzero argument for debugging 4853purposes. 4854@end deftypefn 4855 4856@node Vector Extensions 4857@section Using vector instructions through built-in functions 4858 4859On some targets, the instruction set contains SIMD vector instructions that 4860operate on multiple values contained in one large register at the same time. 4861For example, on the i386 the MMX, 3Dnow! and SSE extensions can be used 4862this way. 4863 4864The first step in using these extensions is to provide the necessary data 4865types. This should be done using an appropriate @code{typedef}: 4866 4867@smallexample 4868typedef int v4si __attribute__ ((vector_size (16))); 4869@end smallexample 4870 4871The @code{int} type specifies the base type, while the attribute specifies 4872the vector size for the variable, measured in bytes. For example, the 4873declaration above causes the compiler to set the mode for the @code{v4si} 4874type to be 16 bytes wide and divided into @code{int} sized units. For 4875a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the 4876corresponding mode of @code{foo} will be @acronym{V4SI}. 4877 4878The @code{vector_size} attribute is only applicable to integral and 4879float scalars, although arrays, pointers, and function return values 4880are allowed in conjunction with this construct. 4881 4882All the basic integer types can be used as base types, both as signed 4883and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, 4884@code{long long}. In addition, @code{float} and @code{double} can be 4885used to build floating-point vector types. 4886 4887Specifying a combination that is not valid for the current architecture 4888will cause GCC to synthesize the instructions using a narrower mode. 4889For example, if you specify a variable of type @code{V4SI} and your 4890architecture does not allow for this specific SIMD type, GCC will 4891produce code that uses 4 @code{SIs}. 4892 4893The types defined in this manner can be used with a subset of normal C 4894operations. Currently, GCC will allow using the following operators 4895on these types: @code{+, -, *, /, unary minus, ^, |, &, ~}@. 4896 4897The operations behave like C++ @code{valarrays}. Addition is defined as 4898the addition of the corresponding elements of the operands. For 4899example, in the code below, each of the 4 elements in @var{a} will be 4900added to the corresponding 4 elements in @var{b} and the resulting 4901vector will be stored in @var{c}. 4902 4903@smallexample 4904typedef int v4si __attribute__ ((vector_size (16))); 4905 4906v4si a, b, c; 4907 4908c = a + b; 4909@end smallexample 4910 4911Subtraction, multiplication, division, and the logical operations 4912operate in a similar manner. Likewise, the result of using the unary 4913minus or complement operators on a vector type is a vector whose 4914elements are the negative or complemented values of the corresponding 4915elements in the operand. 4916 4917You can declare variables and use them in function calls and returns, as 4918well as in assignments and some casts. You can specify a vector type as 4919a return type for a function. Vector types can also be used as function 4920arguments. It is possible to cast from one vector type to another, 4921provided they are of the same size (in fact, you can also cast vectors 4922to and from other datatypes of the same size). 4923 4924You cannot operate between vectors of different lengths or different 4925signedness without a cast. 4926 4927A port that supports hardware vector operations, usually provides a set 4928of built-in functions that can be used to operate on vectors. For 4929example, a function to add two vectors and multiply the result by a 4930third could look like this: 4931 4932@smallexample 4933v4si f (v4si a, v4si b, v4si c) 4934@{ 4935 v4si tmp = __builtin_addv4si (a, b); 4936 return __builtin_mulv4si (tmp, c); 4937@} 4938 4939@end smallexample 4940 4941@node Offsetof 4942@section Offsetof 4943@findex __builtin_offsetof 4944 4945GCC implements for both C and C++ a syntactic extension to implement 4946the @code{offsetof} macro. 4947 4948@smallexample 4949primary: 4950 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" 4951 4952offsetof_member_designator: 4953 @code{identifier} 4954 | offsetof_member_designator "." @code{identifier} 4955 | offsetof_member_designator "[" @code{expr} "]" 4956@end smallexample 4957 4958This extension is sufficient such that 4959 4960@smallexample 4961#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) 4962@end smallexample 4963 4964is a suitable definition of the @code{offsetof} macro. In C++, @var{type} 4965may be dependent. In either case, @var{member} may consist of a single 4966identifier, or a sequence of member accesses and array references. 4967 4968@node Atomic Builtins 4969@section Built-in functions for atomic memory access 4970 4971The following builtins are intended to be compatible with those described 4972in the @cite{Intel Itanium Processor-specific Application Binary Interface}, 4973section 7.4. As such, they depart from the normal GCC practice of using 4974the ``__builtin_'' prefix, and further that they are overloaded such that 4975they work on multiple types. 4976 4977The definition given in the Intel documentation allows only for the use of 4978the types @code{int}, @code{long}, @code{long long} as well as their unsigned 4979counterparts. GCC will allow any integral scalar or pointer type that is 49801, 2, 4 or 8 bytes in length. 4981 4982Not all operations are supported by all target processors. If a particular 4983operation cannot be implemented on the target processor, a warning will be 4984generated and a call an external function will be generated. The external 4985function will carry the same name as the builtin, with an additional suffix 4986@samp{_@var{n}} where @var{n} is the size of the data type. 4987 4988@c ??? Should we have a mechanism to suppress this warning? This is almost 4989@c useful for implementing the operation under the control of an external 4990@c mutex. 4991 4992In most cases, these builtins are considered a @dfn{full barrier}. That is, 4993no memory operand will be moved across the operation, either forward or 4994backward. Further, instructions will be issued as necessary to prevent the 4995processor from speculating loads across the operation and from queuing stores 4996after the operation. 4997 4998All of the routines are are described in the Intel documentation to take 4999``an optional list of variables protected by the memory barrier''. It's 5000not clear what is meant by that; it could mean that @emph{only} the 5001following variables are protected, or it could mean that these variables 5002should in addition be protected. At present GCC ignores this list and 5003protects all variables which are globally accessible. If in the future 5004we make some use of this list, an empty list will continue to mean all 5005globally accessible variables. 5006 5007@table @code 5008@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) 5009@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) 5010@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) 5011@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) 5012@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) 5013@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) 5014@findex __sync_fetch_and_add 5015@findex __sync_fetch_and_sub 5016@findex __sync_fetch_and_or 5017@findex __sync_fetch_and_and 5018@findex __sync_fetch_and_xor 5019@findex __sync_fetch_and_nand 5020These builtins perform the operation suggested by the name, and 5021returns the value that had previously been in memory. That is, 5022 5023@smallexample 5024@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} 5025@{ tmp = *ptr; *ptr = ~tmp & value; return tmp; @} // nand 5026@end smallexample 5027 5028@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) 5029@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) 5030@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) 5031@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) 5032@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) 5033@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) 5034@findex __sync_add_and_fetch 5035@findex __sync_sub_and_fetch 5036@findex __sync_or_and_fetch 5037@findex __sync_and_and_fetch 5038@findex __sync_xor_and_fetch 5039@findex __sync_nand_and_fetch 5040These builtins perform the operation suggested by the name, and 5041return the new value. That is, 5042 5043@smallexample 5044@{ *ptr @var{op}= value; return *ptr; @} 5045@{ *ptr = ~*ptr & value; return *ptr; @} // nand 5046@end smallexample 5047 5048@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...) 5049@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...) 5050@findex __sync_bool_compare_and_swap 5051@findex __sync_val_compare_and_swap 5052These builtins perform an atomic compare and swap. That is, if the current 5053value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into 5054@code{*@var{ptr}}. 5055 5056The ``bool'' version returns true if the comparison is successful and 5057@var{newval} was written. The ``val'' version returns the contents 5058of @code{*@var{ptr}} before the operation. 5059 5060@item __sync_synchronize (...) 5061@findex __sync_synchronize 5062This builtin issues a full memory barrier. 5063 5064@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) 5065@findex __sync_lock_test_and_set 5066This builtin, as described by Intel, is not a traditional test-and-set 5067operation, but rather an atomic exchange operation. It writes @var{value} 5068into @code{*@var{ptr}}, and returns the previous contents of 5069@code{*@var{ptr}}. 5070 5071Many targets have only minimal support for such locks, and do not support 5072a full exchange operation. In this case, a target may support reduced 5073functionality here by which the @emph{only} valid value to store is the 5074immediate constant 1. The exact value actually stored in @code{*@var{ptr}} 5075is implementation defined. 5076 5077This builtin is not a full barrier, but rather an @dfn{acquire barrier}. 5078This means that references after the builtin cannot move to (or be 5079speculated to) before the builtin, but previous memory stores may not 5080be globally visible yet, and previous memory loads may not yet be 5081satisfied. 5082 5083@item void __sync_lock_release (@var{type} *ptr, ...) 5084@findex __sync_lock_release 5085This builtin releases the lock acquired by @code{__sync_lock_test_and_set}. 5086Normally this means writing the constant 0 to @code{*@var{ptr}}. 5087 5088This builtin is not a full barrier, but rather a @dfn{release barrier}. 5089This means that all previous memory stores are globally visible, and all 5090previous memory loads have been satisfied, but following memory reads 5091are not prevented from being speculated to before the barrier. 5092@end table 5093 5094@node Object Size Checking 5095@section Object Size Checking Builtins 5096@findex __builtin_object_size 5097@findex __builtin___memcpy_chk 5098@findex __builtin___mempcpy_chk 5099@findex __builtin___memmove_chk 5100@findex __builtin___memset_chk 5101@findex __builtin___strcpy_chk 5102@findex __builtin___stpcpy_chk 5103@findex __builtin___strncpy_chk 5104@findex __builtin___strcat_chk 5105@findex __builtin___strncat_chk 5106@findex __builtin___sprintf_chk 5107@findex __builtin___snprintf_chk 5108@findex __builtin___vsprintf_chk 5109@findex __builtin___vsnprintf_chk 5110@findex __builtin___printf_chk 5111@findex __builtin___vprintf_chk 5112@findex __builtin___fprintf_chk 5113@findex __builtin___vfprintf_chk 5114 5115GCC implements a limited buffer overflow protection mechanism 5116that can prevent some buffer overflow attacks. 5117 5118@deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type}) 5119is a built-in construct that returns a constant number of bytes from 5120@var{ptr} to the end of the object @var{ptr} pointer points to 5121(if known at compile time). @code{__builtin_object_size} never evaluates 5122its arguments for side-effects. If there are any side-effects in them, it 5123returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 5124for @var{type} 2 or 3. If there are multiple objects @var{ptr} can 5125point to and all of them are known at compile time, the returned number 5126is the maximum of remaining byte counts in those objects if @var{type} & 2 is 51270 and minimum if nonzero. If it is not possible to determine which objects 5128@var{ptr} points to at compile time, @code{__builtin_object_size} should 5129return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 5130for @var{type} 2 or 3. 5131 5132@var{type} is an integer constant from 0 to 3. If the least significant 5133bit is clear, objects are whole variables, if it is set, a closest 5134surrounding subobject is considered the object a pointer points to. 5135The second bit determines if maximum or minimum of remaining bytes 5136is computed. 5137 5138@smallexample 5139struct V @{ char buf1[10]; int b; char buf2[10]; @} var; 5140char *p = &var.buf1[1], *q = &var.b; 5141 5142/* Here the object p points to is var. */ 5143assert (__builtin_object_size (p, 0) == sizeof (var) - 1); 5144/* The subobject p points to is var.buf1. */ 5145assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); 5146/* The object q points to is var. */ 5147assert (__builtin_object_size (q, 0) 5148 == (char *) (&var + 1) - (char *) &var.b); 5149/* The subobject q points to is var.b. */ 5150assert (__builtin_object_size (q, 1) == sizeof (var.b)); 5151@end smallexample 5152@end deftypefn 5153 5154There are built-in functions added for many common string operation 5155functions, e.g. for @code{memcpy} @code{__builtin___memcpy_chk} 5156built-in is provided. This built-in has an additional last argument, 5157which is the number of bytes remaining in object the @var{dest} 5158argument points to or @code{(size_t) -1} if the size is not known. 5159 5160The built-in functions are optimized into the normal string functions 5161like @code{memcpy} if the last argument is @code{(size_t) -1} or if 5162it is known at compile time that the destination object will not 5163be overflown. If the compiler can determine at compile time the 5164object will be always overflown, it issues a warning. 5165 5166The intended use can be e.g. 5167 5168@smallexample 5169#undef memcpy 5170#define bos0(dest) __builtin_object_size (dest, 0) 5171#define memcpy(dest, src, n) \ 5172 __builtin___memcpy_chk (dest, src, n, bos0 (dest)) 5173 5174char *volatile p; 5175char buf[10]; 5176/* It is unknown what object p points to, so this is optimized 5177 into plain memcpy - no checking is possible. */ 5178memcpy (p, "abcde", n); 5179/* Destination is known and length too. It is known at compile 5180 time there will be no overflow. */ 5181memcpy (&buf[5], "abcde", 5); 5182/* Destination is known, but the length is not known at compile time. 5183 This will result in __memcpy_chk call that can check for overflow 5184 at runtime. */ 5185memcpy (&buf[5], "abcde", n); 5186/* Destination is known and it is known at compile time there will 5187 be overflow. There will be a warning and __memcpy_chk call that 5188 will abort the program at runtime. */ 5189memcpy (&buf[6], "abcde", 5); 5190@end smallexample 5191 5192Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, 5193@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, 5194@code{strcat} and @code{strncat}. 5195 5196There are also checking built-in functions for formatted output functions. 5197@smallexample 5198int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); 5199int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, 5200 const char *fmt, ...); 5201int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, 5202 va_list ap); 5203int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, 5204 const char *fmt, va_list ap); 5205@end smallexample 5206 5207The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} 5208etc. functions and can contain implementation specific flags on what 5209additional security measures the checking function might take, such as 5210handling @code{%n} differently. 5211 5212The @var{os} argument is the object size @var{s} points to, like in the 5213other built-in functions. There is a small difference in the behavior 5214though, if @var{os} is @code{(size_t) -1}, the built-in functions are 5215optimized into the non-checking functions only if @var{flag} is 0, otherwise 5216the checking function is called with @var{os} argument set to 5217@code{(size_t) -1}. 5218 5219In addition to this, there are checking built-in functions 5220@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, 5221@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. 5222These have just one additional argument, @var{flag}, right before 5223format string @var{fmt}. If the compiler is able to optimize them to 5224@code{fputc} etc. functions, it will, otherwise the checking function 5225should be called and the @var{flag} argument passed to it. 5226 5227@node Other Builtins 5228@section Other built-in functions provided by GCC 5229@cindex built-in functions 5230@findex __builtin_isgreater 5231@findex __builtin_isgreaterequal 5232@findex __builtin_isless 5233@findex __builtin_islessequal 5234@findex __builtin_islessgreater 5235@findex __builtin_isunordered 5236@findex __builtin_powi 5237@findex __builtin_powif 5238@findex __builtin_powil 5239@findex _Exit 5240@findex _exit 5241@findex abort 5242@findex abs 5243@findex acos 5244@findex acosf 5245@findex acosh 5246@findex acoshf 5247@findex acoshl 5248@findex acosl 5249@findex alloca 5250@findex asin 5251@findex asinf 5252@findex asinh 5253@findex asinhf 5254@findex asinhl 5255@findex asinl 5256@findex atan 5257@findex atan2 5258@findex atan2f 5259@findex atan2l 5260@findex atanf 5261@findex atanh 5262@findex atanhf 5263@findex atanhl 5264@findex atanl 5265@findex bcmp 5266@findex bzero 5267@findex cabs 5268@findex cabsf 5269@findex cabsl 5270@findex cacos 5271@findex cacosf 5272@findex cacosh 5273@findex cacoshf 5274@findex cacoshl 5275@findex cacosl 5276@findex calloc 5277@findex carg 5278@findex cargf 5279@findex cargl 5280@findex casin 5281@findex casinf 5282@findex casinh 5283@findex casinhf 5284@findex casinhl 5285@findex casinl 5286@findex catan 5287@findex catanf 5288@findex catanh 5289@findex catanhf 5290@findex catanhl 5291@findex catanl 5292@findex cbrt 5293@findex cbrtf 5294@findex cbrtl 5295@findex ccos 5296@findex ccosf 5297@findex ccosh 5298@findex ccoshf 5299@findex ccoshl 5300@findex ccosl 5301@findex ceil 5302@findex ceilf 5303@findex ceill 5304@findex cexp 5305@findex cexpf 5306@findex cexpl 5307@findex cimag 5308@findex cimagf 5309@findex cimagl 5310@findex clog 5311@findex clogf 5312@findex clogl 5313@findex conj 5314@findex conjf 5315@findex conjl 5316@findex copysign 5317@findex copysignf 5318@findex copysignl 5319@findex cos 5320@findex cosf 5321@findex cosh 5322@findex coshf 5323@findex coshl 5324@findex cosl 5325@findex cpow 5326@findex cpowf 5327@findex cpowl 5328@findex cproj 5329@findex cprojf 5330@findex cprojl 5331@findex creal 5332@findex crealf 5333@findex creall 5334@findex csin 5335@findex csinf 5336@findex csinh 5337@findex csinhf 5338@findex csinhl 5339@findex csinl 5340@findex csqrt 5341@findex csqrtf 5342@findex csqrtl 5343@findex ctan 5344@findex ctanf 5345@findex ctanh 5346@findex ctanhf 5347@findex ctanhl 5348@findex ctanl 5349@findex dcgettext 5350@findex dgettext 5351@findex drem 5352@findex dremf 5353@findex dreml 5354@findex erf 5355@findex erfc 5356@findex erfcf 5357@findex erfcl 5358@findex erff 5359@findex erfl 5360@findex exit 5361@findex exp 5362@findex exp10 5363@findex exp10f 5364@findex exp10l 5365@findex exp2 5366@findex exp2f 5367@findex exp2l 5368@findex expf 5369@findex expl 5370@findex expm1 5371@findex expm1f 5372@findex expm1l 5373@findex fabs 5374@findex fabsf 5375@findex fabsl 5376@findex fdim 5377@findex fdimf 5378@findex fdiml 5379@findex ffs 5380@findex floor 5381@findex floorf 5382@findex floorl 5383@findex fma 5384@findex fmaf 5385@findex fmal 5386@findex fmax 5387@findex fmaxf 5388@findex fmaxl 5389@findex fmin 5390@findex fminf 5391@findex fminl 5392@findex fmod 5393@findex fmodf 5394@findex fmodl 5395@findex fprintf 5396@findex fprintf_unlocked 5397@findex fputs 5398@findex fputs_unlocked 5399@findex frexp 5400@findex frexpf 5401@findex frexpl 5402@findex fscanf 5403@findex gamma 5404@findex gammaf 5405@findex gammal 5406@findex gettext 5407@findex hypot 5408@findex hypotf 5409@findex hypotl 5410@findex ilogb 5411@findex ilogbf 5412@findex ilogbl 5413@findex imaxabs 5414@findex index 5415@findex isalnum 5416@findex isalpha 5417@findex isascii 5418@findex isblank 5419@findex iscntrl 5420@findex isdigit 5421@findex isgraph 5422@findex islower 5423@findex isprint 5424@findex ispunct 5425@findex isspace 5426@findex isupper 5427@findex iswalnum 5428@findex iswalpha 5429@findex iswblank 5430@findex iswcntrl 5431@findex iswdigit 5432@findex iswgraph 5433@findex iswlower 5434@findex iswprint 5435@findex iswpunct 5436@findex iswspace 5437@findex iswupper 5438@findex iswxdigit 5439@findex isxdigit 5440@findex j0 5441@findex j0f 5442@findex j0l 5443@findex j1 5444@findex j1f 5445@findex j1l 5446@findex jn 5447@findex jnf 5448@findex jnl 5449@findex labs 5450@findex ldexp 5451@findex ldexpf 5452@findex ldexpl 5453@findex lgamma 5454@findex lgammaf 5455@findex lgammal 5456@findex llabs 5457@findex llrint 5458@findex llrintf 5459@findex llrintl 5460@findex llround 5461@findex llroundf 5462@findex llroundl 5463@findex log 5464@findex log10 5465@findex log10f 5466@findex log10l 5467@findex log1p 5468@findex log1pf 5469@findex log1pl 5470@findex log2 5471@findex log2f 5472@findex log2l 5473@findex logb 5474@findex logbf 5475@findex logbl 5476@findex logf 5477@findex logl 5478@findex lrint 5479@findex lrintf 5480@findex lrintl 5481@findex lround 5482@findex lroundf 5483@findex lroundl 5484@findex malloc 5485@findex memcmp 5486@findex memcpy 5487@findex mempcpy 5488@findex memset 5489@findex modf 5490@findex modff 5491@findex modfl 5492@findex nearbyint 5493@findex nearbyintf 5494@findex nearbyintl 5495@findex nextafter 5496@findex nextafterf 5497@findex nextafterl 5498@findex nexttoward 5499@findex nexttowardf 5500@findex nexttowardl 5501@findex pow 5502@findex pow10 5503@findex pow10f 5504@findex pow10l 5505@findex powf 5506@findex powl 5507@findex printf 5508@findex printf_unlocked 5509@findex putchar 5510@findex puts 5511@findex remainder 5512@findex remainderf 5513@findex remainderl 5514@findex remquo 5515@findex remquof 5516@findex remquol 5517@findex rindex 5518@findex rint 5519@findex rintf 5520@findex rintl 5521@findex round 5522@findex roundf 5523@findex roundl 5524@findex scalb 5525@findex scalbf 5526@findex scalbl 5527@findex scalbln 5528@findex scalblnf 5529@findex scalblnf 5530@findex scalbn 5531@findex scalbnf 5532@findex scanfnl 5533@findex signbit 5534@findex signbitf 5535@findex signbitl 5536@findex significand 5537@findex significandf 5538@findex significandl 5539@findex sin 5540@findex sincos 5541@findex sincosf 5542@findex sincosl 5543@findex sinf 5544@findex sinh 5545@findex sinhf 5546@findex sinhl 5547@findex sinl 5548@findex snprintf 5549@findex sprintf 5550@findex sqrt 5551@findex sqrtf 5552@findex sqrtl 5553@findex sscanf 5554@findex stpcpy 5555@findex stpncpy 5556@findex strcasecmp 5557@findex strcat 5558@findex strchr 5559@findex strcmp 5560@findex strcpy 5561@findex strcspn 5562@findex strdup 5563@findex strfmon 5564@findex strftime 5565@findex strlen 5566@findex strncasecmp 5567@findex strncat 5568@findex strncmp 5569@findex strncpy 5570@findex strndup 5571@findex strpbrk 5572@findex strrchr 5573@findex strspn 5574@findex strstr 5575@findex tan 5576@findex tanf 5577@findex tanh 5578@findex tanhf 5579@findex tanhl 5580@findex tanl 5581@findex tgamma 5582@findex tgammaf 5583@findex tgammal 5584@findex toascii 5585@findex tolower 5586@findex toupper 5587@findex towlower 5588@findex towupper 5589@findex trunc 5590@findex truncf 5591@findex truncl 5592@findex vfprintf 5593@findex vfscanf 5594@findex vprintf 5595@findex vscanf 5596@findex vsnprintf 5597@findex vsprintf 5598@findex vsscanf 5599@findex y0 5600@findex y0f 5601@findex y0l 5602@findex y1 5603@findex y1f 5604@findex y1l 5605@findex yn 5606@findex ynf 5607@findex ynl 5608 5609GCC provides a large number of built-in functions other than the ones 5610mentioned above. Some of these are for internal use in the processing 5611of exceptions or variable-length argument lists and will not be 5612documented here because they may change from time to time; we do not 5613recommend general use of these functions. 5614 5615The remaining functions are provided for optimization purposes. 5616 5617@opindex fno-builtin 5618GCC includes built-in versions of many of the functions in the standard 5619C library. The versions prefixed with @code{__builtin_} will always be 5620treated as having the same meaning as the C library function even if you 5621specify the @option{-fno-builtin} option. (@pxref{C Dialect Options}) 5622Many of these functions are only optimized in certain cases; if they are 5623not optimized in a particular case, a call to the library function will 5624be emitted. 5625 5626@opindex ansi 5627@opindex std 5628Outside strict ISO C mode (@option{-ansi}, @option{-std=c89} or 5629@option{-std=c99}), the functions 5630@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, 5631@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, 5632@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, 5633@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, @code{fputs_unlocked}, 5634@code{gammaf}, @code{gammal}, @code{gamma}, @code{gettext}, 5635@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, 5636@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, 5637@code{mempcpy}, @code{pow10f}, @code{pow10l}, @code{pow10}, 5638@code{printf_unlocked}, @code{rindex}, @code{scalbf}, @code{scalbl}, 5639@code{scalb}, @code{signbit}, @code{signbitf}, @code{signbitl}, 5640@code{significandf}, @code{significandl}, @code{significand}, 5641@code{sincosf}, @code{sincosl}, @code{sincos}, @code{stpcpy}, 5642@code{stpncpy}, @code{strcasecmp}, @code{strdup}, @code{strfmon}, 5643@code{strncasecmp}, @code{strndup}, @code{toascii}, @code{y0f}, 5644@code{y0l}, @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, 5645@code{ynl} and @code{yn} 5646may be handled as built-in functions. 5647All these functions have corresponding versions 5648prefixed with @code{__builtin_}, which may be used even in strict C89 5649mode. 5650 5651The ISO C99 functions 5652@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, 5653@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, 5654@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, 5655@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, 5656@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, 5657@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, 5658@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, 5659@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, 5660@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, 5661@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, 5662@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, 5663@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, 5664@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, 5665@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, 5666@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, 5667@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, 5668@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, 5669@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, 5670@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, 5671@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, 5672@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, 5673@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, 5674@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, 5675@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, 5676@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, 5677@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, 5678@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, 5679@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, 5680@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, 5681@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, 5682@code{nextafterf}, @code{nextafterl}, @code{nextafter}, 5683@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, 5684@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, 5685@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, 5686@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, 5687@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, 5688@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, 5689@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, 5690@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} 5691are handled as built-in functions 5692except in strict ISO C90 mode (@option{-ansi} or @option{-std=c89}). 5693 5694There are also built-in versions of the ISO C99 functions 5695@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, 5696@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, 5697@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, 5698@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, 5699@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, 5700@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, 5701@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, 5702@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, 5703@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} 5704that are recognized in any mode since ISO C90 reserves these names for 5705the purpose to which ISO C99 puts them. All these functions have 5706corresponding versions prefixed with @code{__builtin_}. 5707 5708The ISO C94 functions 5709@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, 5710@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, 5711@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and 5712@code{towupper} 5713are handled as built-in functions 5714except in strict ISO C90 mode (@option{-ansi} or @option{-std=c89}). 5715 5716The ISO C90 functions 5717@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, 5718@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, 5719@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, 5720@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf}, 5721@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, 5722@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, 5723@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, 5724@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, 5725@code{malloc}, @code{memcmp}, @code{memcpy}, @code{memset}, @code{modf}, 5726@code{pow}, @code{printf}, @code{putchar}, @code{puts}, @code{scanf}, 5727@code{sinh}, @code{sin}, @code{snprintf}, @code{sprintf}, @code{sqrt}, 5728@code{sscanf}, @code{strcat}, @code{strchr}, @code{strcmp}, 5729@code{strcpy}, @code{strcspn}, @code{strlen}, @code{strncat}, 5730@code{strncmp}, @code{strncpy}, @code{strpbrk}, @code{strrchr}, 5731@code{strspn}, @code{strstr}, @code{tanh}, @code{tan}, @code{vfprintf}, 5732@code{vprintf} and @code{vsprintf} 5733are all recognized as built-in functions unless 5734@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} 5735is specified for an individual function). All of these functions have 5736corresponding versions prefixed with @code{__builtin_}. 5737 5738GCC provides built-in versions of the ISO C99 floating point comparison 5739macros that avoid raising exceptions for unordered operands. They have 5740the same names as the standard macros ( @code{isgreater}, 5741@code{isgreaterequal}, @code{isless}, @code{islessequal}, 5742@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} 5743prefixed. We intend for a library implementor to be able to simply 5744@code{#define} each standard macro to its built-in equivalent. 5745 5746@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) 5747 5748You can use the built-in function @code{__builtin_types_compatible_p} to 5749determine whether two types are the same. 5750 5751This built-in function returns 1 if the unqualified versions of the 5752types @var{type1} and @var{type2} (which are types, not expressions) are 5753compatible, 0 otherwise. The result of this built-in function can be 5754used in integer constant expressions. 5755 5756This built-in function ignores top level qualifiers (e.g., @code{const}, 5757@code{volatile}). For example, @code{int} is equivalent to @code{const 5758int}. 5759 5760The type @code{int[]} and @code{int[5]} are compatible. On the other 5761hand, @code{int} and @code{char *} are not compatible, even if the size 5762of their types, on the particular architecture are the same. Also, the 5763amount of pointer indirection is taken into account when determining 5764similarity. Consequently, @code{short *} is not similar to 5765@code{short **}. Furthermore, two types that are typedefed are 5766considered compatible if their underlying types are compatible. 5767 5768An @code{enum} type is not considered to be compatible with another 5769@code{enum} type even if both are compatible with the same integer 5770type; this is what the C standard specifies. 5771For example, @code{enum @{foo, bar@}} is not similar to 5772@code{enum @{hot, dog@}}. 5773 5774You would typically use this function in code whose execution varies 5775depending on the arguments' types. For example: 5776 5777@smallexample 5778#define foo(x) \ 5779 (@{ \ 5780 typeof (x) tmp = (x); \ 5781 if (__builtin_types_compatible_p (typeof (x), long double)) \ 5782 tmp = foo_long_double (tmp); \ 5783 else if (__builtin_types_compatible_p (typeof (x), double)) \ 5784 tmp = foo_double (tmp); \ 5785 else if (__builtin_types_compatible_p (typeof (x), float)) \ 5786 tmp = foo_float (tmp); \ 5787 else \ 5788 abort (); \ 5789 tmp; \ 5790 @}) 5791@end smallexample 5792 5793@emph{Note:} This construct is only available for C@. 5794 5795@end deftypefn 5796 5797@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) 5798 5799You can use the built-in function @code{__builtin_choose_expr} to 5800evaluate code depending on the value of a constant expression. This 5801built-in function returns @var{exp1} if @var{const_exp}, which is a 5802constant expression that must be able to be determined at compile time, 5803is nonzero. Otherwise it returns 0. 5804 5805This built-in function is analogous to the @samp{? :} operator in C, 5806except that the expression returned has its type unaltered by promotion 5807rules. Also, the built-in function does not evaluate the expression 5808that was not chosen. For example, if @var{const_exp} evaluates to true, 5809@var{exp2} is not evaluated even if it has side-effects. 5810 5811This built-in function can return an lvalue if the chosen argument is an 5812lvalue. 5813 5814If @var{exp1} is returned, the return type is the same as @var{exp1}'s 5815type. Similarly, if @var{exp2} is returned, its return type is the same 5816as @var{exp2}. 5817 5818Example: 5819 5820@smallexample 5821#define foo(x) \ 5822 __builtin_choose_expr ( \ 5823 __builtin_types_compatible_p (typeof (x), double), \ 5824 foo_double (x), \ 5825 __builtin_choose_expr ( \ 5826 __builtin_types_compatible_p (typeof (x), float), \ 5827 foo_float (x), \ 5828 /* @r{The void expression results in a compile-time error} \ 5829 @r{when assigning the result to something.} */ \ 5830 (void)0)) 5831@end smallexample 5832 5833@emph{Note:} This construct is only available for C@. Furthermore, the 5834unused expression (@var{exp1} or @var{exp2} depending on the value of 5835@var{const_exp}) may still generate syntax errors. This may change in 5836future revisions. 5837 5838@end deftypefn 5839 5840@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) 5841You can use the built-in function @code{__builtin_constant_p} to 5842determine if a value is known to be constant at compile-time and hence 5843that GCC can perform constant-folding on expressions involving that 5844value. The argument of the function is the value to test. The function 5845returns the integer 1 if the argument is known to be a compile-time 5846constant and 0 if it is not known to be a compile-time constant. A 5847return of 0 does not indicate that the value is @emph{not} a constant, 5848but merely that GCC cannot prove it is a constant with the specified 5849value of the @option{-O} option. 5850 5851You would typically use this function in an embedded application where 5852memory was a critical resource. If you have some complex calculation, 5853you may want it to be folded if it involves constants, but need to call 5854a function if it does not. For example: 5855 5856@smallexample 5857#define Scale_Value(X) \ 5858 (__builtin_constant_p (X) \ 5859 ? ((X) * SCALE + OFFSET) : Scale (X)) 5860@end smallexample 5861 5862You may use this built-in function in either a macro or an inline 5863function. However, if you use it in an inlined function and pass an 5864argument of the function as the argument to the built-in, GCC will 5865never return 1 when you call the inline function with a string constant 5866or compound literal (@pxref{Compound Literals}) and will not return 1 5867when you pass a constant numeric value to the inline function unless you 5868specify the @option{-O} option. 5869 5870You may also use @code{__builtin_constant_p} in initializers for static 5871data. For instance, you can write 5872 5873@smallexample 5874static const int table[] = @{ 5875 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, 5876 /* @r{@dots{}} */ 5877@}; 5878@end smallexample 5879 5880@noindent 5881This is an acceptable initializer even if @var{EXPRESSION} is not a 5882constant expression. GCC must be more conservative about evaluating the 5883built-in in this case, because it has no opportunity to perform 5884optimization. 5885 5886Previous versions of GCC did not accept this built-in in data 5887initializers. The earliest version where it is completely safe is 58883.0.1. 5889@end deftypefn 5890 5891@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) 5892@opindex fprofile-arcs 5893You may use @code{__builtin_expect} to provide the compiler with 5894branch prediction information. In general, you should prefer to 5895use actual profile feedback for this (@option{-fprofile-arcs}), as 5896programmers are notoriously bad at predicting how their programs 5897actually perform. However, there are applications in which this 5898data is hard to collect. 5899 5900The return value is the value of @var{exp}, which should be an 5901integral expression. The value of @var{c} must be a compile-time 5902constant. The semantics of the built-in are that it is expected 5903that @var{exp} == @var{c}. For example: 5904 5905@smallexample 5906if (__builtin_expect (x, 0)) 5907 foo (); 5908@end smallexample 5909 5910@noindent 5911would indicate that we do not expect to call @code{foo}, since 5912we expect @code{x} to be zero. Since you are limited to integral 5913expressions for @var{exp}, you should use constructions such as 5914 5915@smallexample 5916if (__builtin_expect (ptr != NULL, 1)) 5917 error (); 5918@end smallexample 5919 5920@noindent 5921when testing pointer or floating-point values. 5922@end deftypefn 5923 5924@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) 5925This function is used to minimize cache-miss latency by moving data into 5926a cache before it is accessed. 5927You can insert calls to @code{__builtin_prefetch} into code for which 5928you know addresses of data in memory that is likely to be accessed soon. 5929If the target supports them, data prefetch instructions will be generated. 5930If the prefetch is done early enough before the access then the data will 5931be in the cache by the time it is accessed. 5932 5933The value of @var{addr} is the address of the memory to prefetch. 5934There are two optional arguments, @var{rw} and @var{locality}. 5935The value of @var{rw} is a compile-time constant one or zero; one 5936means that the prefetch is preparing for a write to the memory address 5937and zero, the default, means that the prefetch is preparing for a read. 5938The value @var{locality} must be a compile-time constant integer between 5939zero and three. A value of zero means that the data has no temporal 5940locality, so it need not be left in the cache after the access. A value 5941of three means that the data has a high degree of temporal locality and 5942should be left in all levels of cache possible. Values of one and two 5943mean, respectively, a low or moderate degree of temporal locality. The 5944default is three. 5945 5946@smallexample 5947for (i = 0; i < n; i++) 5948 @{ 5949 a[i] = a[i] + b[i]; 5950 __builtin_prefetch (&a[i+j], 1, 1); 5951 __builtin_prefetch (&b[i+j], 0, 1); 5952 /* @r{@dots{}} */ 5953 @} 5954@end smallexample 5955 5956Data prefetch does not generate faults if @var{addr} is invalid, but 5957the address expression itself must be valid. For example, a prefetch 5958of @code{p->next} will not fault if @code{p->next} is not a valid 5959address, but evaluation will fault if @code{p} is not a valid address. 5960 5961If the target does not support data prefetch, the address expression 5962is evaluated if it includes side effects but no other code is generated 5963and GCC does not issue a warning. 5964@end deftypefn 5965 5966@deftypefn {Built-in Function} double __builtin_huge_val (void) 5967Returns a positive infinity, if supported by the floating-point format, 5968else @code{DBL_MAX}. This function is suitable for implementing the 5969ISO C macro @code{HUGE_VAL}. 5970@end deftypefn 5971 5972@deftypefn {Built-in Function} float __builtin_huge_valf (void) 5973Similar to @code{__builtin_huge_val}, except the return type is @code{float}. 5974@end deftypefn 5975 5976@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) 5977Similar to @code{__builtin_huge_val}, except the return 5978type is @code{long double}. 5979@end deftypefn 5980 5981@deftypefn {Built-in Function} double __builtin_inf (void) 5982Similar to @code{__builtin_huge_val}, except a warning is generated 5983if the target floating-point format does not support infinities. 5984@end deftypefn 5985 5986@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) 5987Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. 5988@end deftypefn 5989 5990@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) 5991Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. 5992@end deftypefn 5993 5994@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) 5995Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. 5996@end deftypefn 5997 5998@deftypefn {Built-in Function} float __builtin_inff (void) 5999Similar to @code{__builtin_inf}, except the return type is @code{float}. 6000This function is suitable for implementing the ISO C99 macro @code{INFINITY}. 6001@end deftypefn 6002 6003@deftypefn {Built-in Function} {long double} __builtin_infl (void) 6004Similar to @code{__builtin_inf}, except the return 6005type is @code{long double}. 6006@end deftypefn 6007 6008@deftypefn {Built-in Function} double __builtin_nan (const char *str) 6009This is an implementation of the ISO C99 function @code{nan}. 6010 6011Since ISO C99 defines this function in terms of @code{strtod}, which we 6012do not implement, a description of the parsing is in order. The string 6013is parsed as by @code{strtol}; that is, the base is recognized by 6014leading @samp{0} or @samp{0x} prefixes. The number parsed is placed 6015in the significand such that the least significant bit of the number 6016is at the least significant bit of the significand. The number is 6017truncated to fit the significand field provided. The significand is 6018forced to be a quiet NaN@. 6019 6020This function, if given a string literal all of which would have been 6021consumed by strtol, is evaluated early enough that it is considered a 6022compile-time constant. 6023@end deftypefn 6024 6025@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) 6026Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. 6027@end deftypefn 6028 6029@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) 6030Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. 6031@end deftypefn 6032 6033@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) 6034Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. 6035@end deftypefn 6036 6037@deftypefn {Built-in Function} float __builtin_nanf (const char *str) 6038Similar to @code{__builtin_nan}, except the return type is @code{float}. 6039@end deftypefn 6040 6041@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) 6042Similar to @code{__builtin_nan}, except the return type is @code{long double}. 6043@end deftypefn 6044 6045@deftypefn {Built-in Function} double __builtin_nans (const char *str) 6046Similar to @code{__builtin_nan}, except the significand is forced 6047to be a signaling NaN@. The @code{nans} function is proposed by 6048@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. 6049@end deftypefn 6050 6051@deftypefn {Built-in Function} float __builtin_nansf (const char *str) 6052Similar to @code{__builtin_nans}, except the return type is @code{float}. 6053@end deftypefn 6054 6055@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) 6056Similar to @code{__builtin_nans}, except the return type is @code{long double}. 6057@end deftypefn 6058 6059@deftypefn {Built-in Function} int __builtin_ffs (unsigned int x) 6060Returns one plus the index of the least significant 1-bit of @var{x}, or 6061if @var{x} is zero, returns zero. 6062@end deftypefn 6063 6064@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) 6065Returns the number of leading 0-bits in @var{x}, starting at the most 6066significant bit position. If @var{x} is 0, the result is undefined. 6067@end deftypefn 6068 6069@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) 6070Returns the number of trailing 0-bits in @var{x}, starting at the least 6071significant bit position. If @var{x} is 0, the result is undefined. 6072@end deftypefn 6073 6074@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) 6075Returns the number of 1-bits in @var{x}. 6076@end deftypefn 6077 6078@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) 6079Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} 6080modulo 2. 6081@end deftypefn 6082 6083@deftypefn {Built-in Function} int __builtin_ffsl (unsigned long) 6084Similar to @code{__builtin_ffs}, except the argument type is 6085@code{unsigned long}. 6086@end deftypefn 6087 6088@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) 6089Similar to @code{__builtin_clz}, except the argument type is 6090@code{unsigned long}. 6091@end deftypefn 6092 6093@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) 6094Similar to @code{__builtin_ctz}, except the argument type is 6095@code{unsigned long}. 6096@end deftypefn 6097 6098@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) 6099Similar to @code{__builtin_popcount}, except the argument type is 6100@code{unsigned long}. 6101@end deftypefn 6102 6103@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) 6104Similar to @code{__builtin_parity}, except the argument type is 6105@code{unsigned long}. 6106@end deftypefn 6107 6108@deftypefn {Built-in Function} int __builtin_ffsll (unsigned long long) 6109Similar to @code{__builtin_ffs}, except the argument type is 6110@code{unsigned long long}. 6111@end deftypefn 6112 6113@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) 6114Similar to @code{__builtin_clz}, except the argument type is 6115@code{unsigned long long}. 6116@end deftypefn 6117 6118@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) 6119Similar to @code{__builtin_ctz}, except the argument type is 6120@code{unsigned long long}. 6121@end deftypefn 6122 6123@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) 6124Similar to @code{__builtin_popcount}, except the argument type is 6125@code{unsigned long long}. 6126@end deftypefn 6127 6128@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) 6129Similar to @code{__builtin_parity}, except the argument type is 6130@code{unsigned long long}. 6131@end deftypefn 6132 6133@deftypefn {Built-in Function} double __builtin_powi (double, int) 6134Returns the first argument raised to the power of the second. Unlike the 6135@code{pow} function no guarantees about precision and rounding are made. 6136@end deftypefn 6137 6138@deftypefn {Built-in Function} float __builtin_powif (float, int) 6139Similar to @code{__builtin_powi}, except the argument and return types 6140are @code{float}. 6141@end deftypefn 6142 6143@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) 6144Similar to @code{__builtin_powi}, except the argument and return types 6145are @code{long double}. 6146@end deftypefn 6147 6148 6149@node Target Builtins 6150@section Built-in Functions Specific to Particular Target Machines 6151 6152On some target machines, GCC supports many built-in functions specific 6153to those machines. Generally these generate calls to specific machine 6154instructions, but allow the compiler to schedule those calls. 6155 6156@menu 6157* Alpha Built-in Functions:: 6158* ARM Built-in Functions:: 6159* Blackfin Built-in Functions:: 6160* FR-V Built-in Functions:: 6161* X86 Built-in Functions:: 6162* MIPS DSP Built-in Functions:: 6163* MIPS Paired-Single Support:: 6164* PowerPC AltiVec Built-in Functions:: 6165* SPARC VIS Built-in Functions:: 6166@end menu 6167 6168@node Alpha Built-in Functions 6169@subsection Alpha Built-in Functions 6170 6171These built-in functions are available for the Alpha family of 6172processors, depending on the command-line switches used. 6173 6174The following built-in functions are always available. They 6175all generate the machine instruction that is part of the name. 6176 6177@smallexample 6178long __builtin_alpha_implver (void) 6179long __builtin_alpha_rpcc (void) 6180long __builtin_alpha_amask (long) 6181long __builtin_alpha_cmpbge (long, long) 6182long __builtin_alpha_extbl (long, long) 6183long __builtin_alpha_extwl (long, long) 6184long __builtin_alpha_extll (long, long) 6185long __builtin_alpha_extql (long, long) 6186long __builtin_alpha_extwh (long, long) 6187long __builtin_alpha_extlh (long, long) 6188long __builtin_alpha_extqh (long, long) 6189long __builtin_alpha_insbl (long, long) 6190long __builtin_alpha_inswl (long, long) 6191long __builtin_alpha_insll (long, long) 6192long __builtin_alpha_insql (long, long) 6193long __builtin_alpha_inswh (long, long) 6194long __builtin_alpha_inslh (long, long) 6195long __builtin_alpha_insqh (long, long) 6196long __builtin_alpha_mskbl (long, long) 6197long __builtin_alpha_mskwl (long, long) 6198long __builtin_alpha_mskll (long, long) 6199long __builtin_alpha_mskql (long, long) 6200long __builtin_alpha_mskwh (long, long) 6201long __builtin_alpha_msklh (long, long) 6202long __builtin_alpha_mskqh (long, long) 6203long __builtin_alpha_umulh (long, long) 6204long __builtin_alpha_zap (long, long) 6205long __builtin_alpha_zapnot (long, long) 6206@end smallexample 6207 6208The following built-in functions are always with @option{-mmax} 6209or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or 6210later. They all generate the machine instruction that is part 6211of the name. 6212 6213@smallexample 6214long __builtin_alpha_pklb (long) 6215long __builtin_alpha_pkwb (long) 6216long __builtin_alpha_unpkbl (long) 6217long __builtin_alpha_unpkbw (long) 6218long __builtin_alpha_minub8 (long, long) 6219long __builtin_alpha_minsb8 (long, long) 6220long __builtin_alpha_minuw4 (long, long) 6221long __builtin_alpha_minsw4 (long, long) 6222long __builtin_alpha_maxub8 (long, long) 6223long __builtin_alpha_maxsb8 (long, long) 6224long __builtin_alpha_maxuw4 (long, long) 6225long __builtin_alpha_maxsw4 (long, long) 6226long __builtin_alpha_perr (long, long) 6227@end smallexample 6228 6229The following built-in functions are always with @option{-mcix} 6230or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or 6231later. They all generate the machine instruction that is part 6232of the name. 6233 6234@smallexample 6235long __builtin_alpha_cttz (long) 6236long __builtin_alpha_ctlz (long) 6237long __builtin_alpha_ctpop (long) 6238@end smallexample 6239 6240The following builtins are available on systems that use the OSF/1 6241PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} 6242PAL calls, but when invoked with @option{-mtls-kernel}, they invoke 6243@code{rdval} and @code{wrval}. 6244 6245@smallexample 6246void *__builtin_thread_pointer (void) 6247void __builtin_set_thread_pointer (void *) 6248@end smallexample 6249 6250@node ARM Built-in Functions 6251@subsection ARM Built-in Functions 6252 6253These built-in functions are available for the ARM family of 6254processors, when the @option{-mcpu=iwmmxt} switch is used: 6255 6256@smallexample 6257typedef int v2si __attribute__ ((vector_size (8))); 6258typedef short v4hi __attribute__ ((vector_size (8))); 6259typedef char v8qi __attribute__ ((vector_size (8))); 6260 6261int __builtin_arm_getwcx (int) 6262void __builtin_arm_setwcx (int, int) 6263int __builtin_arm_textrmsb (v8qi, int) 6264int __builtin_arm_textrmsh (v4hi, int) 6265int __builtin_arm_textrmsw (v2si, int) 6266int __builtin_arm_textrmub (v8qi, int) 6267int __builtin_arm_textrmuh (v4hi, int) 6268int __builtin_arm_textrmuw (v2si, int) 6269v8qi __builtin_arm_tinsrb (v8qi, int) 6270v4hi __builtin_arm_tinsrh (v4hi, int) 6271v2si __builtin_arm_tinsrw (v2si, int) 6272long long __builtin_arm_tmia (long long, int, int) 6273long long __builtin_arm_tmiabb (long long, int, int) 6274long long __builtin_arm_tmiabt (long long, int, int) 6275long long __builtin_arm_tmiaph (long long, int, int) 6276long long __builtin_arm_tmiatb (long long, int, int) 6277long long __builtin_arm_tmiatt (long long, int, int) 6278int __builtin_arm_tmovmskb (v8qi) 6279int __builtin_arm_tmovmskh (v4hi) 6280int __builtin_arm_tmovmskw (v2si) 6281long long __builtin_arm_waccb (v8qi) 6282long long __builtin_arm_wacch (v4hi) 6283long long __builtin_arm_waccw (v2si) 6284v8qi __builtin_arm_waddb (v8qi, v8qi) 6285v8qi __builtin_arm_waddbss (v8qi, v8qi) 6286v8qi __builtin_arm_waddbus (v8qi, v8qi) 6287v4hi __builtin_arm_waddh (v4hi, v4hi) 6288v4hi __builtin_arm_waddhss (v4hi, v4hi) 6289v4hi __builtin_arm_waddhus (v4hi, v4hi) 6290v2si __builtin_arm_waddw (v2si, v2si) 6291v2si __builtin_arm_waddwss (v2si, v2si) 6292v2si __builtin_arm_waddwus (v2si, v2si) 6293v8qi __builtin_arm_walign (v8qi, v8qi, int) 6294long long __builtin_arm_wand(long long, long long) 6295long long __builtin_arm_wandn (long long, long long) 6296v8qi __builtin_arm_wavg2b (v8qi, v8qi) 6297v8qi __builtin_arm_wavg2br (v8qi, v8qi) 6298v4hi __builtin_arm_wavg2h (v4hi, v4hi) 6299v4hi __builtin_arm_wavg2hr (v4hi, v4hi) 6300v8qi __builtin_arm_wcmpeqb (v8qi, v8qi) 6301v4hi __builtin_arm_wcmpeqh (v4hi, v4hi) 6302v2si __builtin_arm_wcmpeqw (v2si, v2si) 6303v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) 6304v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) 6305v2si __builtin_arm_wcmpgtsw (v2si, v2si) 6306v8qi __builtin_arm_wcmpgtub (v8qi, v8qi) 6307v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) 6308v2si __builtin_arm_wcmpgtuw (v2si, v2si) 6309long long __builtin_arm_wmacs (long long, v4hi, v4hi) 6310long long __builtin_arm_wmacsz (v4hi, v4hi) 6311long long __builtin_arm_wmacu (long long, v4hi, v4hi) 6312long long __builtin_arm_wmacuz (v4hi, v4hi) 6313v4hi __builtin_arm_wmadds (v4hi, v4hi) 6314v4hi __builtin_arm_wmaddu (v4hi, v4hi) 6315v8qi __builtin_arm_wmaxsb (v8qi, v8qi) 6316v4hi __builtin_arm_wmaxsh (v4hi, v4hi) 6317v2si __builtin_arm_wmaxsw (v2si, v2si) 6318v8qi __builtin_arm_wmaxub (v8qi, v8qi) 6319v4hi __builtin_arm_wmaxuh (v4hi, v4hi) 6320v2si __builtin_arm_wmaxuw (v2si, v2si) 6321v8qi __builtin_arm_wminsb (v8qi, v8qi) 6322v4hi __builtin_arm_wminsh (v4hi, v4hi) 6323v2si __builtin_arm_wminsw (v2si, v2si) 6324v8qi __builtin_arm_wminub (v8qi, v8qi) 6325v4hi __builtin_arm_wminuh (v4hi, v4hi) 6326v2si __builtin_arm_wminuw (v2si, v2si) 6327v4hi __builtin_arm_wmulsm (v4hi, v4hi) 6328v4hi __builtin_arm_wmulul (v4hi, v4hi) 6329v4hi __builtin_arm_wmulum (v4hi, v4hi) 6330long long __builtin_arm_wor (long long, long long) 6331v2si __builtin_arm_wpackdss (long long, long long) 6332v2si __builtin_arm_wpackdus (long long, long long) 6333v8qi __builtin_arm_wpackhss (v4hi, v4hi) 6334v8qi __builtin_arm_wpackhus (v4hi, v4hi) 6335v4hi __builtin_arm_wpackwss (v2si, v2si) 6336v4hi __builtin_arm_wpackwus (v2si, v2si) 6337long long __builtin_arm_wrord (long long, long long) 6338long long __builtin_arm_wrordi (long long, int) 6339v4hi __builtin_arm_wrorh (v4hi, long long) 6340v4hi __builtin_arm_wrorhi (v4hi, int) 6341v2si __builtin_arm_wrorw (v2si, long long) 6342v2si __builtin_arm_wrorwi (v2si, int) 6343v2si __builtin_arm_wsadb (v8qi, v8qi) 6344v2si __builtin_arm_wsadbz (v8qi, v8qi) 6345v2si __builtin_arm_wsadh (v4hi, v4hi) 6346v2si __builtin_arm_wsadhz (v4hi, v4hi) 6347v4hi __builtin_arm_wshufh (v4hi, int) 6348long long __builtin_arm_wslld (long long, long long) 6349long long __builtin_arm_wslldi (long long, int) 6350v4hi __builtin_arm_wsllh (v4hi, long long) 6351v4hi __builtin_arm_wsllhi (v4hi, int) 6352v2si __builtin_arm_wsllw (v2si, long long) 6353v2si __builtin_arm_wsllwi (v2si, int) 6354long long __builtin_arm_wsrad (long long, long long) 6355long long __builtin_arm_wsradi (long long, int) 6356v4hi __builtin_arm_wsrah (v4hi, long long) 6357v4hi __builtin_arm_wsrahi (v4hi, int) 6358v2si __builtin_arm_wsraw (v2si, long long) 6359v2si __builtin_arm_wsrawi (v2si, int) 6360long long __builtin_arm_wsrld (long long, long long) 6361long long __builtin_arm_wsrldi (long long, int) 6362v4hi __builtin_arm_wsrlh (v4hi, long long) 6363v4hi __builtin_arm_wsrlhi (v4hi, int) 6364v2si __builtin_arm_wsrlw (v2si, long long) 6365v2si __builtin_arm_wsrlwi (v2si, int) 6366v8qi __builtin_arm_wsubb (v8qi, v8qi) 6367v8qi __builtin_arm_wsubbss (v8qi, v8qi) 6368v8qi __builtin_arm_wsubbus (v8qi, v8qi) 6369v4hi __builtin_arm_wsubh (v4hi, v4hi) 6370v4hi __builtin_arm_wsubhss (v4hi, v4hi) 6371v4hi __builtin_arm_wsubhus (v4hi, v4hi) 6372v2si __builtin_arm_wsubw (v2si, v2si) 6373v2si __builtin_arm_wsubwss (v2si, v2si) 6374v2si __builtin_arm_wsubwus (v2si, v2si) 6375v4hi __builtin_arm_wunpckehsb (v8qi) 6376v2si __builtin_arm_wunpckehsh (v4hi) 6377long long __builtin_arm_wunpckehsw (v2si) 6378v4hi __builtin_arm_wunpckehub (v8qi) 6379v2si __builtin_arm_wunpckehuh (v4hi) 6380long long __builtin_arm_wunpckehuw (v2si) 6381v4hi __builtin_arm_wunpckelsb (v8qi) 6382v2si __builtin_arm_wunpckelsh (v4hi) 6383long long __builtin_arm_wunpckelsw (v2si) 6384v4hi __builtin_arm_wunpckelub (v8qi) 6385v2si __builtin_arm_wunpckeluh (v4hi) 6386long long __builtin_arm_wunpckeluw (v2si) 6387v8qi __builtin_arm_wunpckihb (v8qi, v8qi) 6388v4hi __builtin_arm_wunpckihh (v4hi, v4hi) 6389v2si __builtin_arm_wunpckihw (v2si, v2si) 6390v8qi __builtin_arm_wunpckilb (v8qi, v8qi) 6391v4hi __builtin_arm_wunpckilh (v4hi, v4hi) 6392v2si __builtin_arm_wunpckilw (v2si, v2si) 6393long long __builtin_arm_wxor (long long, long long) 6394long long __builtin_arm_wzero () 6395@end smallexample 6396 6397@node Blackfin Built-in Functions 6398@subsection Blackfin Built-in Functions 6399 6400Currently, there are two Blackfin-specific built-in functions. These are 6401used for generating @code{CSYNC} and @code{SSYNC} machine insns without 6402using inline assembly; by using these built-in functions the compiler can 6403automatically add workarounds for hardware errata involving these 6404instructions. These functions are named as follows: 6405 6406@smallexample 6407void __builtin_bfin_csync (void) 6408void __builtin_bfin_ssync (void) 6409@end smallexample 6410 6411@node FR-V Built-in Functions 6412@subsection FR-V Built-in Functions 6413 6414GCC provides many FR-V-specific built-in functions. In general, 6415these functions are intended to be compatible with those described 6416by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu 6417Semiconductor}. The two exceptions are @code{__MDUNPACKH} and 6418@code{__MBTOHE}, the gcc forms of which pass 128-bit values by 6419pointer rather than by value. 6420 6421Most of the functions are named after specific FR-V instructions. 6422Such functions are said to be ``directly mapped'' and are summarized 6423here in tabular form. 6424 6425@menu 6426* Argument Types:: 6427* Directly-mapped Integer Functions:: 6428* Directly-mapped Media Functions:: 6429* Raw read/write Functions:: 6430* Other Built-in Functions:: 6431@end menu 6432 6433@node Argument Types 6434@subsubsection Argument Types 6435 6436The arguments to the built-in functions can be divided into three groups: 6437register numbers, compile-time constants and run-time values. In order 6438to make this classification clear at a glance, the arguments and return 6439values are given the following pseudo types: 6440 6441@multitable @columnfractions .20 .30 .15 .35 6442@item Pseudo type @tab Real C type @tab Constant? @tab Description 6443@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword 6444@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word 6445@item @code{sw1} @tab @code{int} @tab No @tab a signed word 6446@item @code{uw2} @tab @code{unsigned long long} @tab No 6447@tab an unsigned doubleword 6448@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword 6449@item @code{const} @tab @code{int} @tab Yes @tab an integer constant 6450@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number 6451@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number 6452@end multitable 6453 6454These pseudo types are not defined by GCC, they are simply a notational 6455convenience used in this manual. 6456 6457Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} 6458and @code{sw2} are evaluated at run time. They correspond to 6459register operands in the underlying FR-V instructions. 6460 6461@code{const} arguments represent immediate operands in the underlying 6462FR-V instructions. They must be compile-time constants. 6463 6464@code{acc} arguments are evaluated at compile time and specify the number 6465of an accumulator register. For example, an @code{acc} argument of 2 6466will select the ACC2 register. 6467 6468@code{iacc} arguments are similar to @code{acc} arguments but specify the 6469number of an IACC register. See @pxref{Other Built-in Functions} 6470for more details. 6471 6472@node Directly-mapped Integer Functions 6473@subsubsection Directly-mapped Integer Functions 6474 6475The functions listed below map directly to FR-V I-type instructions. 6476 6477@multitable @columnfractions .45 .32 .23 6478@item Function prototype @tab Example usage @tab Assembly output 6479@item @code{sw1 __ADDSS (sw1, sw1)} 6480@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} 6481@tab @code{ADDSS @var{a},@var{b},@var{c}} 6482@item @code{sw1 __SCAN (sw1, sw1)} 6483@tab @code{@var{c} = __SCAN (@var{a}, @var{b})} 6484@tab @code{SCAN @var{a},@var{b},@var{c}} 6485@item @code{sw1 __SCUTSS (sw1)} 6486@tab @code{@var{b} = __SCUTSS (@var{a})} 6487@tab @code{SCUTSS @var{a},@var{b}} 6488@item @code{sw1 __SLASS (sw1, sw1)} 6489@tab @code{@var{c} = __SLASS (@var{a}, @var{b})} 6490@tab @code{SLASS @var{a},@var{b},@var{c}} 6491@item @code{void __SMASS (sw1, sw1)} 6492@tab @code{__SMASS (@var{a}, @var{b})} 6493@tab @code{SMASS @var{a},@var{b}} 6494@item @code{void __SMSSS (sw1, sw1)} 6495@tab @code{__SMSSS (@var{a}, @var{b})} 6496@tab @code{SMSSS @var{a},@var{b}} 6497@item @code{void __SMU (sw1, sw1)} 6498@tab @code{__SMU (@var{a}, @var{b})} 6499@tab @code{SMU @var{a},@var{b}} 6500@item @code{sw2 __SMUL (sw1, sw1)} 6501@tab @code{@var{c} = __SMUL (@var{a}, @var{b})} 6502@tab @code{SMUL @var{a},@var{b},@var{c}} 6503@item @code{sw1 __SUBSS (sw1, sw1)} 6504@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} 6505@tab @code{SUBSS @var{a},@var{b},@var{c}} 6506@item @code{uw2 __UMUL (uw1, uw1)} 6507@tab @code{@var{c} = __UMUL (@var{a}, @var{b})} 6508@tab @code{UMUL @var{a},@var{b},@var{c}} 6509@end multitable 6510 6511@node Directly-mapped Media Functions 6512@subsubsection Directly-mapped Media Functions 6513 6514The functions listed below map directly to FR-V M-type instructions. 6515 6516@multitable @columnfractions .45 .32 .23 6517@item Function prototype @tab Example usage @tab Assembly output 6518@item @code{uw1 __MABSHS (sw1)} 6519@tab @code{@var{b} = __MABSHS (@var{a})} 6520@tab @code{MABSHS @var{a},@var{b}} 6521@item @code{void __MADDACCS (acc, acc)} 6522@tab @code{__MADDACCS (@var{b}, @var{a})} 6523@tab @code{MADDACCS @var{a},@var{b}} 6524@item @code{sw1 __MADDHSS (sw1, sw1)} 6525@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} 6526@tab @code{MADDHSS @var{a},@var{b},@var{c}} 6527@item @code{uw1 __MADDHUS (uw1, uw1)} 6528@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} 6529@tab @code{MADDHUS @var{a},@var{b},@var{c}} 6530@item @code{uw1 __MAND (uw1, uw1)} 6531@tab @code{@var{c} = __MAND (@var{a}, @var{b})} 6532@tab @code{MAND @var{a},@var{b},@var{c}} 6533@item @code{void __MASACCS (acc, acc)} 6534@tab @code{__MASACCS (@var{b}, @var{a})} 6535@tab @code{MASACCS @var{a},@var{b}} 6536@item @code{uw1 __MAVEH (uw1, uw1)} 6537@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} 6538@tab @code{MAVEH @var{a},@var{b},@var{c}} 6539@item @code{uw2 __MBTOH (uw1)} 6540@tab @code{@var{b} = __MBTOH (@var{a})} 6541@tab @code{MBTOH @var{a},@var{b}} 6542@item @code{void __MBTOHE (uw1 *, uw1)} 6543@tab @code{__MBTOHE (&@var{b}, @var{a})} 6544@tab @code{MBTOHE @var{a},@var{b}} 6545@item @code{void __MCLRACC (acc)} 6546@tab @code{__MCLRACC (@var{a})} 6547@tab @code{MCLRACC @var{a}} 6548@item @code{void __MCLRACCA (void)} 6549@tab @code{__MCLRACCA ()} 6550@tab @code{MCLRACCA} 6551@item @code{uw1 __Mcop1 (uw1, uw1)} 6552@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} 6553@tab @code{Mcop1 @var{a},@var{b},@var{c}} 6554@item @code{uw1 __Mcop2 (uw1, uw1)} 6555@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} 6556@tab @code{Mcop2 @var{a},@var{b},@var{c}} 6557@item @code{uw1 __MCPLHI (uw2, const)} 6558@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} 6559@tab @code{MCPLHI @var{a},#@var{b},@var{c}} 6560@item @code{uw1 __MCPLI (uw2, const)} 6561@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} 6562@tab @code{MCPLI @var{a},#@var{b},@var{c}} 6563@item @code{void __MCPXIS (acc, sw1, sw1)} 6564@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} 6565@tab @code{MCPXIS @var{a},@var{b},@var{c}} 6566@item @code{void __MCPXIU (acc, uw1, uw1)} 6567@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} 6568@tab @code{MCPXIU @var{a},@var{b},@var{c}} 6569@item @code{void __MCPXRS (acc, sw1, sw1)} 6570@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} 6571@tab @code{MCPXRS @var{a},@var{b},@var{c}} 6572@item @code{void __MCPXRU (acc, uw1, uw1)} 6573@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} 6574@tab @code{MCPXRU @var{a},@var{b},@var{c}} 6575@item @code{uw1 __MCUT (acc, uw1)} 6576@tab @code{@var{c} = __MCUT (@var{a}, @var{b})} 6577@tab @code{MCUT @var{a},@var{b},@var{c}} 6578@item @code{uw1 __MCUTSS (acc, sw1)} 6579@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} 6580@tab @code{MCUTSS @var{a},@var{b},@var{c}} 6581@item @code{void __MDADDACCS (acc, acc)} 6582@tab @code{__MDADDACCS (@var{b}, @var{a})} 6583@tab @code{MDADDACCS @var{a},@var{b}} 6584@item @code{void __MDASACCS (acc, acc)} 6585@tab @code{__MDASACCS (@var{b}, @var{a})} 6586@tab @code{MDASACCS @var{a},@var{b}} 6587@item @code{uw2 __MDCUTSSI (acc, const)} 6588@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} 6589@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} 6590@item @code{uw2 __MDPACKH (uw2, uw2)} 6591@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} 6592@tab @code{MDPACKH @var{a},@var{b},@var{c}} 6593@item @code{uw2 __MDROTLI (uw2, const)} 6594@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} 6595@tab @code{MDROTLI @var{a},#@var{b},@var{c}} 6596@item @code{void __MDSUBACCS (acc, acc)} 6597@tab @code{__MDSUBACCS (@var{b}, @var{a})} 6598@tab @code{MDSUBACCS @var{a},@var{b}} 6599@item @code{void __MDUNPACKH (uw1 *, uw2)} 6600@tab @code{__MDUNPACKH (&@var{b}, @var{a})} 6601@tab @code{MDUNPACKH @var{a},@var{b}} 6602@item @code{uw2 __MEXPDHD (uw1, const)} 6603@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} 6604@tab @code{MEXPDHD @var{a},#@var{b},@var{c}} 6605@item @code{uw1 __MEXPDHW (uw1, const)} 6606@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} 6607@tab @code{MEXPDHW @var{a},#@var{b},@var{c}} 6608@item @code{uw1 __MHDSETH (uw1, const)} 6609@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} 6610@tab @code{MHDSETH @var{a},#@var{b},@var{c}} 6611@item @code{sw1 __MHDSETS (const)} 6612@tab @code{@var{b} = __MHDSETS (@var{a})} 6613@tab @code{MHDSETS #@var{a},@var{b}} 6614@item @code{uw1 __MHSETHIH (uw1, const)} 6615@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} 6616@tab @code{MHSETHIH #@var{a},@var{b}} 6617@item @code{sw1 __MHSETHIS (sw1, const)} 6618@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} 6619@tab @code{MHSETHIS #@var{a},@var{b}} 6620@item @code{uw1 __MHSETLOH (uw1, const)} 6621@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} 6622@tab @code{MHSETLOH #@var{a},@var{b}} 6623@item @code{sw1 __MHSETLOS (sw1, const)} 6624@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} 6625@tab @code{MHSETLOS #@var{a},@var{b}} 6626@item @code{uw1 __MHTOB (uw2)} 6627@tab @code{@var{b} = __MHTOB (@var{a})} 6628@tab @code{MHTOB @var{a},@var{b}} 6629@item @code{void __MMACHS (acc, sw1, sw1)} 6630@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} 6631@tab @code{MMACHS @var{a},@var{b},@var{c}} 6632@item @code{void __MMACHU (acc, uw1, uw1)} 6633@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} 6634@tab @code{MMACHU @var{a},@var{b},@var{c}} 6635@item @code{void __MMRDHS (acc, sw1, sw1)} 6636@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} 6637@tab @code{MMRDHS @var{a},@var{b},@var{c}} 6638@item @code{void __MMRDHU (acc, uw1, uw1)} 6639@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} 6640@tab @code{MMRDHU @var{a},@var{b},@var{c}} 6641@item @code{void __MMULHS (acc, sw1, sw1)} 6642@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} 6643@tab @code{MMULHS @var{a},@var{b},@var{c}} 6644@item @code{void __MMULHU (acc, uw1, uw1)} 6645@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} 6646@tab @code{MMULHU @var{a},@var{b},@var{c}} 6647@item @code{void __MMULXHS (acc, sw1, sw1)} 6648@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} 6649@tab @code{MMULXHS @var{a},@var{b},@var{c}} 6650@item @code{void __MMULXHU (acc, uw1, uw1)} 6651@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} 6652@tab @code{MMULXHU @var{a},@var{b},@var{c}} 6653@item @code{uw1 __MNOT (uw1)} 6654@tab @code{@var{b} = __MNOT (@var{a})} 6655@tab @code{MNOT @var{a},@var{b}} 6656@item @code{uw1 __MOR (uw1, uw1)} 6657@tab @code{@var{c} = __MOR (@var{a}, @var{b})} 6658@tab @code{MOR @var{a},@var{b},@var{c}} 6659@item @code{uw1 __MPACKH (uh, uh)} 6660@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} 6661@tab @code{MPACKH @var{a},@var{b},@var{c}} 6662@item @code{sw2 __MQADDHSS (sw2, sw2)} 6663@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} 6664@tab @code{MQADDHSS @var{a},@var{b},@var{c}} 6665@item @code{uw2 __MQADDHUS (uw2, uw2)} 6666@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} 6667@tab @code{MQADDHUS @var{a},@var{b},@var{c}} 6668@item @code{void __MQCPXIS (acc, sw2, sw2)} 6669@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} 6670@tab @code{MQCPXIS @var{a},@var{b},@var{c}} 6671@item @code{void __MQCPXIU (acc, uw2, uw2)} 6672@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} 6673@tab @code{MQCPXIU @var{a},@var{b},@var{c}} 6674@item @code{void __MQCPXRS (acc, sw2, sw2)} 6675@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} 6676@tab @code{MQCPXRS @var{a},@var{b},@var{c}} 6677@item @code{void __MQCPXRU (acc, uw2, uw2)} 6678@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} 6679@tab @code{MQCPXRU @var{a},@var{b},@var{c}} 6680@item @code{sw2 __MQLCLRHS (sw2, sw2)} 6681@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} 6682@tab @code{MQLCLRHS @var{a},@var{b},@var{c}} 6683@item @code{sw2 __MQLMTHS (sw2, sw2)} 6684@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} 6685@tab @code{MQLMTHS @var{a},@var{b},@var{c}} 6686@item @code{void __MQMACHS (acc, sw2, sw2)} 6687@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} 6688@tab @code{MQMACHS @var{a},@var{b},@var{c}} 6689@item @code{void __MQMACHU (acc, uw2, uw2)} 6690@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} 6691@tab @code{MQMACHU @var{a},@var{b},@var{c}} 6692@item @code{void __MQMACXHS (acc, sw2, sw2)} 6693@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} 6694@tab @code{MQMACXHS @var{a},@var{b},@var{c}} 6695@item @code{void __MQMULHS (acc, sw2, sw2)} 6696@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} 6697@tab @code{MQMULHS @var{a},@var{b},@var{c}} 6698@item @code{void __MQMULHU (acc, uw2, uw2)} 6699@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} 6700@tab @code{MQMULHU @var{a},@var{b},@var{c}} 6701@item @code{void __MQMULXHS (acc, sw2, sw2)} 6702@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} 6703@tab @code{MQMULXHS @var{a},@var{b},@var{c}} 6704@item @code{void __MQMULXHU (acc, uw2, uw2)} 6705@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} 6706@tab @code{MQMULXHU @var{a},@var{b},@var{c}} 6707@item @code{sw2 __MQSATHS (sw2, sw2)} 6708@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} 6709@tab @code{MQSATHS @var{a},@var{b},@var{c}} 6710@item @code{uw2 __MQSLLHI (uw2, int)} 6711@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} 6712@tab @code{MQSLLHI @var{a},@var{b},@var{c}} 6713@item @code{sw2 __MQSRAHI (sw2, int)} 6714@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} 6715@tab @code{MQSRAHI @var{a},@var{b},@var{c}} 6716@item @code{sw2 __MQSUBHSS (sw2, sw2)} 6717@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} 6718@tab @code{MQSUBHSS @var{a},@var{b},@var{c}} 6719@item @code{uw2 __MQSUBHUS (uw2, uw2)} 6720@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} 6721@tab @code{MQSUBHUS @var{a},@var{b},@var{c}} 6722@item @code{void __MQXMACHS (acc, sw2, sw2)} 6723@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} 6724@tab @code{MQXMACHS @var{a},@var{b},@var{c}} 6725@item @code{void __MQXMACXHS (acc, sw2, sw2)} 6726@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} 6727@tab @code{MQXMACXHS @var{a},@var{b},@var{c}} 6728@item @code{uw1 __MRDACC (acc)} 6729@tab @code{@var{b} = __MRDACC (@var{a})} 6730@tab @code{MRDACC @var{a},@var{b}} 6731@item @code{uw1 __MRDACCG (acc)} 6732@tab @code{@var{b} = __MRDACCG (@var{a})} 6733@tab @code{MRDACCG @var{a},@var{b}} 6734@item @code{uw1 __MROTLI (uw1, const)} 6735@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} 6736@tab @code{MROTLI @var{a},#@var{b},@var{c}} 6737@item @code{uw1 __MROTRI (uw1, const)} 6738@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} 6739@tab @code{MROTRI @var{a},#@var{b},@var{c}} 6740@item @code{sw1 __MSATHS (sw1, sw1)} 6741@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} 6742@tab @code{MSATHS @var{a},@var{b},@var{c}} 6743@item @code{uw1 __MSATHU (uw1, uw1)} 6744@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} 6745@tab @code{MSATHU @var{a},@var{b},@var{c}} 6746@item @code{uw1 __MSLLHI (uw1, const)} 6747@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} 6748@tab @code{MSLLHI @var{a},#@var{b},@var{c}} 6749@item @code{sw1 __MSRAHI (sw1, const)} 6750@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} 6751@tab @code{MSRAHI @var{a},#@var{b},@var{c}} 6752@item @code{uw1 __MSRLHI (uw1, const)} 6753@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} 6754@tab @code{MSRLHI @var{a},#@var{b},@var{c}} 6755@item @code{void __MSUBACCS (acc, acc)} 6756@tab @code{__MSUBACCS (@var{b}, @var{a})} 6757@tab @code{MSUBACCS @var{a},@var{b}} 6758@item @code{sw1 __MSUBHSS (sw1, sw1)} 6759@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} 6760@tab @code{MSUBHSS @var{a},@var{b},@var{c}} 6761@item @code{uw1 __MSUBHUS (uw1, uw1)} 6762@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} 6763@tab @code{MSUBHUS @var{a},@var{b},@var{c}} 6764@item @code{void __MTRAP (void)} 6765@tab @code{__MTRAP ()} 6766@tab @code{MTRAP} 6767@item @code{uw2 __MUNPACKH (uw1)} 6768@tab @code{@var{b} = __MUNPACKH (@var{a})} 6769@tab @code{MUNPACKH @var{a},@var{b}} 6770@item @code{uw1 __MWCUT (uw2, uw1)} 6771@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} 6772@tab @code{MWCUT @var{a},@var{b},@var{c}} 6773@item @code{void __MWTACC (acc, uw1)} 6774@tab @code{__MWTACC (@var{b}, @var{a})} 6775@tab @code{MWTACC @var{a},@var{b}} 6776@item @code{void __MWTACCG (acc, uw1)} 6777@tab @code{__MWTACCG (@var{b}, @var{a})} 6778@tab @code{MWTACCG @var{a},@var{b}} 6779@item @code{uw1 __MXOR (uw1, uw1)} 6780@tab @code{@var{c} = __MXOR (@var{a}, @var{b})} 6781@tab @code{MXOR @var{a},@var{b},@var{c}} 6782@end multitable 6783 6784@node Raw read/write Functions 6785@subsubsection Raw read/write Functions 6786 6787This sections describes built-in functions related to read and write 6788instructions to access memory. These functions generate 6789@code{membar} instructions to flush the I/O load and stores where 6790appropriate, as described in Fujitsu's manual described above. 6791 6792@table @code 6793 6794@item unsigned char __builtin_read8 (void *@var{data}) 6795@item unsigned short __builtin_read16 (void *@var{data}) 6796@item unsigned long __builtin_read32 (void *@var{data}) 6797@item unsigned long long __builtin_read64 (void *@var{data}) 6798 6799@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) 6800@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) 6801@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) 6802@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) 6803@end table 6804 6805@node Other Built-in Functions 6806@subsubsection Other Built-in Functions 6807 6808This section describes built-in functions that are not named after 6809a specific FR-V instruction. 6810 6811@table @code 6812@item sw2 __IACCreadll (iacc @var{reg}) 6813Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved 6814for future expansion and must be 0. 6815 6816@item sw1 __IACCreadl (iacc @var{reg}) 6817Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. 6818Other values of @var{reg} are rejected as invalid. 6819 6820@item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) 6821Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument 6822is reserved for future expansion and must be 0. 6823 6824@item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) 6825Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} 6826is 1. Other values of @var{reg} are rejected as invalid. 6827 6828@item void __data_prefetch0 (const void *@var{x}) 6829Use the @code{dcpl} instruction to load the contents of address @var{x} 6830into the data cache. 6831 6832@item void __data_prefetch (const void *@var{x}) 6833Use the @code{nldub} instruction to load the contents of address @var{x} 6834into the data cache. The instruction will be issued in slot I1@. 6835@end table 6836 6837@node X86 Built-in Functions 6838@subsection X86 Built-in Functions 6839 6840These built-in functions are available for the i386 and x86-64 family 6841of computers, depending on the command-line switches used. 6842 6843Note that, if you specify command-line switches such as @option{-msse}, 6844the compiler could use the extended instruction sets even if the built-ins 6845are not used explicitly in the program. For this reason, applications 6846which perform runtime CPU detection must compile separate files for each 6847supported architecture, using the appropriate flags. In particular, 6848the file containing the CPU detection code should be compiled without 6849these options. 6850 6851The following machine modes are available for use with MMX built-in functions 6852(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, 6853@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a 6854vector of eight 8-bit integers. Some of the built-in functions operate on 6855MMX registers as a whole 64-bit entity, these use @code{DI} as their mode. 6856 6857If 3Dnow extensions are enabled, @code{V2SF} is used as a mode for a vector 6858of two 32-bit floating point values. 6859 6860If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit 6861floating point values. Some instructions use a vector of four 32-bit 6862integers, these use @code{V4SI}. Finally, some instructions operate on an 6863entire vector register, interpreting it as a 128-bit integer, these use mode 6864@code{TI}. 6865 6866The following built-in functions are made available by @option{-mmmx}. 6867All of them generate the machine instruction that is part of the name. 6868 6869@smallexample 6870v8qi __builtin_ia32_paddb (v8qi, v8qi) 6871v4hi __builtin_ia32_paddw (v4hi, v4hi) 6872v2si __builtin_ia32_paddd (v2si, v2si) 6873v8qi __builtin_ia32_psubb (v8qi, v8qi) 6874v4hi __builtin_ia32_psubw (v4hi, v4hi) 6875v2si __builtin_ia32_psubd (v2si, v2si) 6876v8qi __builtin_ia32_paddsb (v8qi, v8qi) 6877v4hi __builtin_ia32_paddsw (v4hi, v4hi) 6878v8qi __builtin_ia32_psubsb (v8qi, v8qi) 6879v4hi __builtin_ia32_psubsw (v4hi, v4hi) 6880v8qi __builtin_ia32_paddusb (v8qi, v8qi) 6881v4hi __builtin_ia32_paddusw (v4hi, v4hi) 6882v8qi __builtin_ia32_psubusb (v8qi, v8qi) 6883v4hi __builtin_ia32_psubusw (v4hi, v4hi) 6884v4hi __builtin_ia32_pmullw (v4hi, v4hi) 6885v4hi __builtin_ia32_pmulhw (v4hi, v4hi) 6886di __builtin_ia32_pand (di, di) 6887di __builtin_ia32_pandn (di,di) 6888di __builtin_ia32_por (di, di) 6889di __builtin_ia32_pxor (di, di) 6890v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) 6891v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) 6892v2si __builtin_ia32_pcmpeqd (v2si, v2si) 6893v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) 6894v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) 6895v2si __builtin_ia32_pcmpgtd (v2si, v2si) 6896v8qi __builtin_ia32_punpckhbw (v8qi, v8qi) 6897v4hi __builtin_ia32_punpckhwd (v4hi, v4hi) 6898v2si __builtin_ia32_punpckhdq (v2si, v2si) 6899v8qi __builtin_ia32_punpcklbw (v8qi, v8qi) 6900v4hi __builtin_ia32_punpcklwd (v4hi, v4hi) 6901v2si __builtin_ia32_punpckldq (v2si, v2si) 6902v8qi __builtin_ia32_packsswb (v4hi, v4hi) 6903v4hi __builtin_ia32_packssdw (v2si, v2si) 6904v8qi __builtin_ia32_packuswb (v4hi, v4hi) 6905@end smallexample 6906 6907The following built-in functions are made available either with 6908@option{-msse}, or with a combination of @option{-m3dnow} and 6909@option{-march=athlon}. All of them generate the machine 6910instruction that is part of the name. 6911 6912@smallexample 6913v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) 6914v8qi __builtin_ia32_pavgb (v8qi, v8qi) 6915v4hi __builtin_ia32_pavgw (v4hi, v4hi) 6916v4hi __builtin_ia32_psadbw (v8qi, v8qi) 6917v8qi __builtin_ia32_pmaxub (v8qi, v8qi) 6918v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) 6919v8qi __builtin_ia32_pminub (v8qi, v8qi) 6920v4hi __builtin_ia32_pminsw (v4hi, v4hi) 6921int __builtin_ia32_pextrw (v4hi, int) 6922v4hi __builtin_ia32_pinsrw (v4hi, int, int) 6923int __builtin_ia32_pmovmskb (v8qi) 6924void __builtin_ia32_maskmovq (v8qi, v8qi, char *) 6925void __builtin_ia32_movntq (di *, di) 6926void __builtin_ia32_sfence (void) 6927@end smallexample 6928 6929The following built-in functions are available when @option{-msse} is used. 6930All of them generate the machine instruction that is part of the name. 6931 6932@smallexample 6933int __builtin_ia32_comieq (v4sf, v4sf) 6934int __builtin_ia32_comineq (v4sf, v4sf) 6935int __builtin_ia32_comilt (v4sf, v4sf) 6936int __builtin_ia32_comile (v4sf, v4sf) 6937int __builtin_ia32_comigt (v4sf, v4sf) 6938int __builtin_ia32_comige (v4sf, v4sf) 6939int __builtin_ia32_ucomieq (v4sf, v4sf) 6940int __builtin_ia32_ucomineq (v4sf, v4sf) 6941int __builtin_ia32_ucomilt (v4sf, v4sf) 6942int __builtin_ia32_ucomile (v4sf, v4sf) 6943int __builtin_ia32_ucomigt (v4sf, v4sf) 6944int __builtin_ia32_ucomige (v4sf, v4sf) 6945v4sf __builtin_ia32_addps (v4sf, v4sf) 6946v4sf __builtin_ia32_subps (v4sf, v4sf) 6947v4sf __builtin_ia32_mulps (v4sf, v4sf) 6948v4sf __builtin_ia32_divps (v4sf, v4sf) 6949v4sf __builtin_ia32_addss (v4sf, v4sf) 6950v4sf __builtin_ia32_subss (v4sf, v4sf) 6951v4sf __builtin_ia32_mulss (v4sf, v4sf) 6952v4sf __builtin_ia32_divss (v4sf, v4sf) 6953v4si __builtin_ia32_cmpeqps (v4sf, v4sf) 6954v4si __builtin_ia32_cmpltps (v4sf, v4sf) 6955v4si __builtin_ia32_cmpleps (v4sf, v4sf) 6956v4si __builtin_ia32_cmpgtps (v4sf, v4sf) 6957v4si __builtin_ia32_cmpgeps (v4sf, v4sf) 6958v4si __builtin_ia32_cmpunordps (v4sf, v4sf) 6959v4si __builtin_ia32_cmpneqps (v4sf, v4sf) 6960v4si __builtin_ia32_cmpnltps (v4sf, v4sf) 6961v4si __builtin_ia32_cmpnleps (v4sf, v4sf) 6962v4si __builtin_ia32_cmpngtps (v4sf, v4sf) 6963v4si __builtin_ia32_cmpngeps (v4sf, v4sf) 6964v4si __builtin_ia32_cmpordps (v4sf, v4sf) 6965v4si __builtin_ia32_cmpeqss (v4sf, v4sf) 6966v4si __builtin_ia32_cmpltss (v4sf, v4sf) 6967v4si __builtin_ia32_cmpless (v4sf, v4sf) 6968v4si __builtin_ia32_cmpunordss (v4sf, v4sf) 6969v4si __builtin_ia32_cmpneqss (v4sf, v4sf) 6970v4si __builtin_ia32_cmpnlts (v4sf, v4sf) 6971v4si __builtin_ia32_cmpnless (v4sf, v4sf) 6972v4si __builtin_ia32_cmpordss (v4sf, v4sf) 6973v4sf __builtin_ia32_maxps (v4sf, v4sf) 6974v4sf __builtin_ia32_maxss (v4sf, v4sf) 6975v4sf __builtin_ia32_minps (v4sf, v4sf) 6976v4sf __builtin_ia32_minss (v4sf, v4sf) 6977v4sf __builtin_ia32_andps (v4sf, v4sf) 6978v4sf __builtin_ia32_andnps (v4sf, v4sf) 6979v4sf __builtin_ia32_orps (v4sf, v4sf) 6980v4sf __builtin_ia32_xorps (v4sf, v4sf) 6981v4sf __builtin_ia32_movss (v4sf, v4sf) 6982v4sf __builtin_ia32_movhlps (v4sf, v4sf) 6983v4sf __builtin_ia32_movlhps (v4sf, v4sf) 6984v4sf __builtin_ia32_unpckhps (v4sf, v4sf) 6985v4sf __builtin_ia32_unpcklps (v4sf, v4sf) 6986v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) 6987v4sf __builtin_ia32_cvtsi2ss (v4sf, int) 6988v2si __builtin_ia32_cvtps2pi (v4sf) 6989int __builtin_ia32_cvtss2si (v4sf) 6990v2si __builtin_ia32_cvttps2pi (v4sf) 6991int __builtin_ia32_cvttss2si (v4sf) 6992v4sf __builtin_ia32_rcpps (v4sf) 6993v4sf __builtin_ia32_rsqrtps (v4sf) 6994v4sf __builtin_ia32_sqrtps (v4sf) 6995v4sf __builtin_ia32_rcpss (v4sf) 6996v4sf __builtin_ia32_rsqrtss (v4sf) 6997v4sf __builtin_ia32_sqrtss (v4sf) 6998v4sf __builtin_ia32_shufps (v4sf, v4sf, int) 6999void __builtin_ia32_movntps (float *, v4sf) 7000int __builtin_ia32_movmskps (v4sf) 7001@end smallexample 7002 7003The following built-in functions are available when @option{-msse} is used. 7004 7005@table @code 7006@item v4sf __builtin_ia32_loadaps (float *) 7007Generates the @code{movaps} machine instruction as a load from memory. 7008@item void __builtin_ia32_storeaps (float *, v4sf) 7009Generates the @code{movaps} machine instruction as a store to memory. 7010@item v4sf __builtin_ia32_loadups (float *) 7011Generates the @code{movups} machine instruction as a load from memory. 7012@item void __builtin_ia32_storeups (float *, v4sf) 7013Generates the @code{movups} machine instruction as a store to memory. 7014@item v4sf __builtin_ia32_loadsss (float *) 7015Generates the @code{movss} machine instruction as a load from memory. 7016@item void __builtin_ia32_storess (float *, v4sf) 7017Generates the @code{movss} machine instruction as a store to memory. 7018@item v4sf __builtin_ia32_loadhps (v4sf, v2si *) 7019Generates the @code{movhps} machine instruction as a load from memory. 7020@item v4sf __builtin_ia32_loadlps (v4sf, v2si *) 7021Generates the @code{movlps} machine instruction as a load from memory 7022@item void __builtin_ia32_storehps (v4sf, v2si *) 7023Generates the @code{movhps} machine instruction as a store to memory. 7024@item void __builtin_ia32_storelps (v4sf, v2si *) 7025Generates the @code{movlps} machine instruction as a store to memory. 7026@end table 7027 7028The following built-in functions are available when @option{-msse2} is used. 7029All of them generate the machine instruction that is part of the name. 7030 7031@smallexample 7032int __builtin_ia32_comisdeq (v2df, v2df) 7033int __builtin_ia32_comisdlt (v2df, v2df) 7034int __builtin_ia32_comisdle (v2df, v2df) 7035int __builtin_ia32_comisdgt (v2df, v2df) 7036int __builtin_ia32_comisdge (v2df, v2df) 7037int __builtin_ia32_comisdneq (v2df, v2df) 7038int __builtin_ia32_ucomisdeq (v2df, v2df) 7039int __builtin_ia32_ucomisdlt (v2df, v2df) 7040int __builtin_ia32_ucomisdle (v2df, v2df) 7041int __builtin_ia32_ucomisdgt (v2df, v2df) 7042int __builtin_ia32_ucomisdge (v2df, v2df) 7043int __builtin_ia32_ucomisdneq (v2df, v2df) 7044v2df __builtin_ia32_cmpeqpd (v2df, v2df) 7045v2df __builtin_ia32_cmpltpd (v2df, v2df) 7046v2df __builtin_ia32_cmplepd (v2df, v2df) 7047v2df __builtin_ia32_cmpgtpd (v2df, v2df) 7048v2df __builtin_ia32_cmpgepd (v2df, v2df) 7049v2df __builtin_ia32_cmpunordpd (v2df, v2df) 7050v2df __builtin_ia32_cmpneqpd (v2df, v2df) 7051v2df __builtin_ia32_cmpnltpd (v2df, v2df) 7052v2df __builtin_ia32_cmpnlepd (v2df, v2df) 7053v2df __builtin_ia32_cmpngtpd (v2df, v2df) 7054v2df __builtin_ia32_cmpngepd (v2df, v2df) 7055v2df __builtin_ia32_cmpordpd (v2df, v2df) 7056v2df __builtin_ia32_cmpeqsd (v2df, v2df) 7057v2df __builtin_ia32_cmpltsd (v2df, v2df) 7058v2df __builtin_ia32_cmplesd (v2df, v2df) 7059v2df __builtin_ia32_cmpunordsd (v2df, v2df) 7060v2df __builtin_ia32_cmpneqsd (v2df, v2df) 7061v2df __builtin_ia32_cmpnltsd (v2df, v2df) 7062v2df __builtin_ia32_cmpnlesd (v2df, v2df) 7063v2df __builtin_ia32_cmpordsd (v2df, v2df) 7064v2di __builtin_ia32_paddq (v2di, v2di) 7065v2di __builtin_ia32_psubq (v2di, v2di) 7066v2df __builtin_ia32_addpd (v2df, v2df) 7067v2df __builtin_ia32_subpd (v2df, v2df) 7068v2df __builtin_ia32_mulpd (v2df, v2df) 7069v2df __builtin_ia32_divpd (v2df, v2df) 7070v2df __builtin_ia32_addsd (v2df, v2df) 7071v2df __builtin_ia32_subsd (v2df, v2df) 7072v2df __builtin_ia32_mulsd (v2df, v2df) 7073v2df __builtin_ia32_divsd (v2df, v2df) 7074v2df __builtin_ia32_minpd (v2df, v2df) 7075v2df __builtin_ia32_maxpd (v2df, v2df) 7076v2df __builtin_ia32_minsd (v2df, v2df) 7077v2df __builtin_ia32_maxsd (v2df, v2df) 7078v2df __builtin_ia32_andpd (v2df, v2df) 7079v2df __builtin_ia32_andnpd (v2df, v2df) 7080v2df __builtin_ia32_orpd (v2df, v2df) 7081v2df __builtin_ia32_xorpd (v2df, v2df) 7082v2df __builtin_ia32_movsd (v2df, v2df) 7083v2df __builtin_ia32_unpckhpd (v2df, v2df) 7084v2df __builtin_ia32_unpcklpd (v2df, v2df) 7085v16qi __builtin_ia32_paddb128 (v16qi, v16qi) 7086v8hi __builtin_ia32_paddw128 (v8hi, v8hi) 7087v4si __builtin_ia32_paddd128 (v4si, v4si) 7088v2di __builtin_ia32_paddq128 (v2di, v2di) 7089v16qi __builtin_ia32_psubb128 (v16qi, v16qi) 7090v8hi __builtin_ia32_psubw128 (v8hi, v8hi) 7091v4si __builtin_ia32_psubd128 (v4si, v4si) 7092v2di __builtin_ia32_psubq128 (v2di, v2di) 7093v8hi __builtin_ia32_pmullw128 (v8hi, v8hi) 7094v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi) 7095v2di __builtin_ia32_pand128 (v2di, v2di) 7096v2di __builtin_ia32_pandn128 (v2di, v2di) 7097v2di __builtin_ia32_por128 (v2di, v2di) 7098v2di __builtin_ia32_pxor128 (v2di, v2di) 7099v16qi __builtin_ia32_pavgb128 (v16qi, v16qi) 7100v8hi __builtin_ia32_pavgw128 (v8hi, v8hi) 7101v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi) 7102v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi) 7103v4si __builtin_ia32_pcmpeqd128 (v4si, v4si) 7104v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi) 7105v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi) 7106v4si __builtin_ia32_pcmpgtd128 (v4si, v4si) 7107v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi) 7108v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi) 7109v16qi __builtin_ia32_pminub128 (v16qi, v16qi) 7110v8hi __builtin_ia32_pminsw128 (v8hi, v8hi) 7111v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi) 7112v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi) 7113v4si __builtin_ia32_punpckhdq128 (v4si, v4si) 7114v2di __builtin_ia32_punpckhqdq128 (v2di, v2di) 7115v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi) 7116v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi) 7117v4si __builtin_ia32_punpckldq128 (v4si, v4si) 7118v2di __builtin_ia32_punpcklqdq128 (v2di, v2di) 7119v16qi __builtin_ia32_packsswb128 (v16qi, v16qi) 7120v8hi __builtin_ia32_packssdw128 (v8hi, v8hi) 7121v16qi __builtin_ia32_packuswb128 (v16qi, v16qi) 7122v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi) 7123void __builtin_ia32_maskmovdqu (v16qi, v16qi) 7124v2df __builtin_ia32_loadupd (double *) 7125void __builtin_ia32_storeupd (double *, v2df) 7126v2df __builtin_ia32_loadhpd (v2df, double *) 7127v2df __builtin_ia32_loadlpd (v2df, double *) 7128int __builtin_ia32_movmskpd (v2df) 7129int __builtin_ia32_pmovmskb128 (v16qi) 7130void __builtin_ia32_movnti (int *, int) 7131void __builtin_ia32_movntpd (double *, v2df) 7132void __builtin_ia32_movntdq (v2df *, v2df) 7133v4si __builtin_ia32_pshufd (v4si, int) 7134v8hi __builtin_ia32_pshuflw (v8hi, int) 7135v8hi __builtin_ia32_pshufhw (v8hi, int) 7136v2di __builtin_ia32_psadbw128 (v16qi, v16qi) 7137v2df __builtin_ia32_sqrtpd (v2df) 7138v2df __builtin_ia32_sqrtsd (v2df) 7139v2df __builtin_ia32_shufpd (v2df, v2df, int) 7140v2df __builtin_ia32_cvtdq2pd (v4si) 7141v4sf __builtin_ia32_cvtdq2ps (v4si) 7142v4si __builtin_ia32_cvtpd2dq (v2df) 7143v2si __builtin_ia32_cvtpd2pi (v2df) 7144v4sf __builtin_ia32_cvtpd2ps (v2df) 7145v4si __builtin_ia32_cvttpd2dq (v2df) 7146v2si __builtin_ia32_cvttpd2pi (v2df) 7147v2df __builtin_ia32_cvtpi2pd (v2si) 7148int __builtin_ia32_cvtsd2si (v2df) 7149int __builtin_ia32_cvttsd2si (v2df) 7150long long __builtin_ia32_cvtsd2si64 (v2df) 7151long long __builtin_ia32_cvttsd2si64 (v2df) 7152v4si __builtin_ia32_cvtps2dq (v4sf) 7153v2df __builtin_ia32_cvtps2pd (v4sf) 7154v4si __builtin_ia32_cvttps2dq (v4sf) 7155v2df __builtin_ia32_cvtsi2sd (v2df, int) 7156v2df __builtin_ia32_cvtsi642sd (v2df, long long) 7157v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df) 7158v2df __builtin_ia32_cvtss2sd (v2df, v4sf) 7159void __builtin_ia32_clflush (const void *) 7160void __builtin_ia32_lfence (void) 7161void __builtin_ia32_mfence (void) 7162v16qi __builtin_ia32_loaddqu (const char *) 7163void __builtin_ia32_storedqu (char *, v16qi) 7164unsigned long long __builtin_ia32_pmuludq (v2si, v2si) 7165v2di __builtin_ia32_pmuludq128 (v4si, v4si) 7166v8hi __builtin_ia32_psllw128 (v8hi, v2di) 7167v4si __builtin_ia32_pslld128 (v4si, v2di) 7168v2di __builtin_ia32_psllq128 (v4si, v2di) 7169v8hi __builtin_ia32_psrlw128 (v8hi, v2di) 7170v4si __builtin_ia32_psrld128 (v4si, v2di) 7171v2di __builtin_ia32_psrlq128 (v2di, v2di) 7172v8hi __builtin_ia32_psraw128 (v8hi, v2di) 7173v4si __builtin_ia32_psrad128 (v4si, v2di) 7174v2di __builtin_ia32_pslldqi128 (v2di, int) 7175v8hi __builtin_ia32_psllwi128 (v8hi, int) 7176v4si __builtin_ia32_pslldi128 (v4si, int) 7177v2di __builtin_ia32_psllqi128 (v2di, int) 7178v2di __builtin_ia32_psrldqi128 (v2di, int) 7179v8hi __builtin_ia32_psrlwi128 (v8hi, int) 7180v4si __builtin_ia32_psrldi128 (v4si, int) 7181v2di __builtin_ia32_psrlqi128 (v2di, int) 7182v8hi __builtin_ia32_psrawi128 (v8hi, int) 7183v4si __builtin_ia32_psradi128 (v4si, int) 7184v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi) 7185@end smallexample 7186 7187The following built-in functions are available when @option{-msse3} is used. 7188All of them generate the machine instruction that is part of the name. 7189 7190@smallexample 7191v2df __builtin_ia32_addsubpd (v2df, v2df) 7192v4sf __builtin_ia32_addsubps (v4sf, v4sf) 7193v2df __builtin_ia32_haddpd (v2df, v2df) 7194v4sf __builtin_ia32_haddps (v4sf, v4sf) 7195v2df __builtin_ia32_hsubpd (v2df, v2df) 7196v4sf __builtin_ia32_hsubps (v4sf, v4sf) 7197v16qi __builtin_ia32_lddqu (char const *) 7198void __builtin_ia32_monitor (void *, unsigned int, unsigned int) 7199v2df __builtin_ia32_movddup (v2df) 7200v4sf __builtin_ia32_movshdup (v4sf) 7201v4sf __builtin_ia32_movsldup (v4sf) 7202void __builtin_ia32_mwait (unsigned int, unsigned int) 7203@end smallexample 7204 7205The following built-in functions are available when @option{-msse3} is used. 7206 7207@table @code 7208@item v2df __builtin_ia32_loadddup (double const *) 7209Generates the @code{movddup} machine instruction as a load from memory. 7210@end table 7211 7212The following built-in functions are available when @option{-mssse3} is used. 7213All of them generate the machine instruction that is part of the name 7214with MMX registers. 7215 7216@smallexample 7217v2si __builtin_ia32_phaddd (v2si, v2si) 7218v4hi __builtin_ia32_phaddw (v4hi, v4hi) 7219v4hi __builtin_ia32_phaddsw (v4hi, v4hi) 7220v2si __builtin_ia32_phsubd (v2si, v2si) 7221v4hi __builtin_ia32_phsubw (v4hi, v4hi) 7222v4hi __builtin_ia32_phsubsw (v4hi, v4hi) 7223v8qi __builtin_ia32_pmaddubsw (v8qi, v8qi) 7224v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi) 7225v8qi __builtin_ia32_pshufb (v8qi, v8qi) 7226v8qi __builtin_ia32_psignb (v8qi, v8qi) 7227v2si __builtin_ia32_psignd (v2si, v2si) 7228v4hi __builtin_ia32_psignw (v4hi, v4hi) 7229long long __builtin_ia32_palignr (long long, long long, int) 7230v8qi __builtin_ia32_pabsb (v8qi) 7231v2si __builtin_ia32_pabsd (v2si) 7232v4hi __builtin_ia32_pabsw (v4hi) 7233@end smallexample 7234 7235The following built-in functions are available when @option{-mssse3} is used. 7236All of them generate the machine instruction that is part of the name 7237with SSE registers. 7238 7239@smallexample 7240v4si __builtin_ia32_phaddd128 (v4si, v4si) 7241v8hi __builtin_ia32_phaddw128 (v8hi, v8hi) 7242v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi) 7243v4si __builtin_ia32_phsubd128 (v4si, v4si) 7244v8hi __builtin_ia32_phsubw128 (v8hi, v8hi) 7245v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi) 7246v16qi __builtin_ia32_pmaddubsw128 (v16qi, v16qi) 7247v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi) 7248v16qi __builtin_ia32_pshufb128 (v16qi, v16qi) 7249v16qi __builtin_ia32_psignb128 (v16qi, v16qi) 7250v4si __builtin_ia32_psignd128 (v4si, v4si) 7251v8hi __builtin_ia32_psignw128 (v8hi, v8hi) 7252v2di __builtin_ia32_palignr (v2di, v2di, int) 7253v16qi __builtin_ia32_pabsb128 (v16qi) 7254v4si __builtin_ia32_pabsd128 (v4si) 7255v8hi __builtin_ia32_pabsw128 (v8hi) 7256@end smallexample 7257 7258The following built-in functions are available when @option{-m3dnow} is used. 7259All of them generate the machine instruction that is part of the name. 7260 7261@smallexample 7262void __builtin_ia32_femms (void) 7263v8qi __builtin_ia32_pavgusb (v8qi, v8qi) 7264v2si __builtin_ia32_pf2id (v2sf) 7265v2sf __builtin_ia32_pfacc (v2sf, v2sf) 7266v2sf __builtin_ia32_pfadd (v2sf, v2sf) 7267v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) 7268v2si __builtin_ia32_pfcmpge (v2sf, v2sf) 7269v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) 7270v2sf __builtin_ia32_pfmax (v2sf, v2sf) 7271v2sf __builtin_ia32_pfmin (v2sf, v2sf) 7272v2sf __builtin_ia32_pfmul (v2sf, v2sf) 7273v2sf __builtin_ia32_pfrcp (v2sf) 7274v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) 7275v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) 7276v2sf __builtin_ia32_pfrsqrt (v2sf) 7277v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf) 7278v2sf __builtin_ia32_pfsub (v2sf, v2sf) 7279v2sf __builtin_ia32_pfsubr (v2sf, v2sf) 7280v2sf __builtin_ia32_pi2fd (v2si) 7281v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) 7282@end smallexample 7283 7284The following built-in functions are available when both @option{-m3dnow} 7285and @option{-march=athlon} are used. All of them generate the machine 7286instruction that is part of the name. 7287 7288@smallexample 7289v2si __builtin_ia32_pf2iw (v2sf) 7290v2sf __builtin_ia32_pfnacc (v2sf, v2sf) 7291v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) 7292v2sf __builtin_ia32_pi2fw (v2si) 7293v2sf __builtin_ia32_pswapdsf (v2sf) 7294v2si __builtin_ia32_pswapdsi (v2si) 7295@end smallexample 7296 7297@node MIPS DSP Built-in Functions 7298@subsection MIPS DSP Built-in Functions 7299 7300The MIPS DSP Application-Specific Extension (ASE) includes new 7301instructions that are designed to improve the performance of DSP and 7302media applications. It provides instructions that operate on packed 73038-bit integer data, Q15 fractional data and Q31 fractional data. 7304 7305GCC supports MIPS DSP operations using both the generic 7306vector extensions (@pxref{Vector Extensions}) and a collection of 7307MIPS-specific built-in functions. Both kinds of support are 7308enabled by the @option{-mdsp} command-line option. 7309 7310At present, GCC only provides support for operations on 32-bit 7311vectors. The vector type associated with 8-bit integer data is 7312usually called @code{v4i8} and the vector type associated with Q15 is 7313usually called @code{v2q15}. They can be defined in C as follows: 7314 7315@smallexample 7316typedef char v4i8 __attribute__ ((vector_size(4))); 7317typedef short v2q15 __attribute__ ((vector_size(4))); 7318@end smallexample 7319 7320@code{v4i8} and @code{v2q15} values are initialized in the same way as 7321aggregates. For example: 7322 7323@smallexample 7324v4i8 a = @{1, 2, 3, 4@}; 7325v4i8 b; 7326b = (v4i8) @{5, 6, 7, 8@}; 7327 7328v2q15 c = @{0x0fcb, 0x3a75@}; 7329v2q15 d; 7330d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; 7331@end smallexample 7332 7333@emph{Note:} The CPU's endianness determines the order in which values 7334are packed. On little-endian targets, the first value is the least 7335significant and the last value is the most significant. The opposite 7336order applies to big-endian targets. For example, the code above will 7337set the lowest byte of @code{a} to @code{1} on little-endian targets 7338and @code{4} on big-endian targets. 7339 7340@emph{Note:} Q15 and Q31 values must be initialized with their integer 7341representation. As shown in this example, the integer representation 7342of a Q15 value can be obtained by multiplying the fractional value by 7343@code{0x1.0p15}. The equivalent for Q31 values is to multiply by 7344@code{0x1.0p31}. 7345 7346The table below lists the @code{v4i8} and @code{v2q15} operations for which 7347hardware support exists. @code{a} and @code{b} are @code{v4i8} values, 7348and @code{c} and @code{d} are @code{v2q15} values. 7349 7350@multitable @columnfractions .50 .50 7351@item C code @tab MIPS instruction 7352@item @code{a + b} @tab @code{addu.qb} 7353@item @code{c + d} @tab @code{addq.ph} 7354@item @code{a - b} @tab @code{subu.qb} 7355@item @code{c - d} @tab @code{subq.ph} 7356@end multitable 7357 7358It is easier to describe the DSP built-in functions if we first define 7359the following types: 7360 7361@smallexample 7362typedef int q31; 7363typedef int i32; 7364typedef long long a64; 7365@end smallexample 7366 7367@code{q31} and @code{i32} are actually the same as @code{int}, but we 7368use @code{q31} to indicate a Q31 fractional value and @code{i32} to 7369indicate a 32-bit integer value. Similarly, @code{a64} is the same as 7370@code{long long}, but we use @code{a64} to indicate values that will 7371be placed in one of the four DSP accumulators (@code{$ac0}, 7372@code{$ac1}, @code{$ac2} or @code{$ac3}). 7373 7374Also, some built-in functions prefer or require immediate numbers as 7375parameters, because the corresponding DSP instructions accept both immediate 7376numbers and register operands, or accept immediate numbers only. The 7377immediate parameters are listed as follows. 7378 7379@smallexample 7380imm0_7: 0 to 7. 7381imm0_15: 0 to 15. 7382imm0_31: 0 to 31. 7383imm0_63: 0 to 63. 7384imm0_255: 0 to 255. 7385imm_n32_31: -32 to 31. 7386imm_n512_511: -512 to 511. 7387@end smallexample 7388 7389The following built-in functions map directly to a particular MIPS DSP 7390instruction. Please refer to the architecture specification 7391for details on what each instruction does. 7392 7393@smallexample 7394v2q15 __builtin_mips_addq_ph (v2q15, v2q15) 7395v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) 7396q31 __builtin_mips_addq_s_w (q31, q31) 7397v4i8 __builtin_mips_addu_qb (v4i8, v4i8) 7398v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) 7399v2q15 __builtin_mips_subq_ph (v2q15, v2q15) 7400v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) 7401q31 __builtin_mips_subq_s_w (q31, q31) 7402v4i8 __builtin_mips_subu_qb (v4i8, v4i8) 7403v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) 7404i32 __builtin_mips_addsc (i32, i32) 7405i32 __builtin_mips_addwc (i32, i32) 7406i32 __builtin_mips_modsub (i32, i32) 7407i32 __builtin_mips_raddu_w_qb (v4i8) 7408v2q15 __builtin_mips_absq_s_ph (v2q15) 7409q31 __builtin_mips_absq_s_w (q31) 7410v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) 7411v2q15 __builtin_mips_precrq_ph_w (q31, q31) 7412v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) 7413v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) 7414q31 __builtin_mips_preceq_w_phl (v2q15) 7415q31 __builtin_mips_preceq_w_phr (v2q15) 7416v2q15 __builtin_mips_precequ_ph_qbl (v4i8) 7417v2q15 __builtin_mips_precequ_ph_qbr (v4i8) 7418v2q15 __builtin_mips_precequ_ph_qbla (v4i8) 7419v2q15 __builtin_mips_precequ_ph_qbra (v4i8) 7420v2q15 __builtin_mips_preceu_ph_qbl (v4i8) 7421v2q15 __builtin_mips_preceu_ph_qbr (v4i8) 7422v2q15 __builtin_mips_preceu_ph_qbla (v4i8) 7423v2q15 __builtin_mips_preceu_ph_qbra (v4i8) 7424v4i8 __builtin_mips_shll_qb (v4i8, imm0_7) 7425v4i8 __builtin_mips_shll_qb (v4i8, i32) 7426v2q15 __builtin_mips_shll_ph (v2q15, imm0_15) 7427v2q15 __builtin_mips_shll_ph (v2q15, i32) 7428v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) 7429v2q15 __builtin_mips_shll_s_ph (v2q15, i32) 7430q31 __builtin_mips_shll_s_w (q31, imm0_31) 7431q31 __builtin_mips_shll_s_w (q31, i32) 7432v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) 7433v4i8 __builtin_mips_shrl_qb (v4i8, i32) 7434v2q15 __builtin_mips_shra_ph (v2q15, imm0_15) 7435v2q15 __builtin_mips_shra_ph (v2q15, i32) 7436v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) 7437v2q15 __builtin_mips_shra_r_ph (v2q15, i32) 7438q31 __builtin_mips_shra_r_w (q31, imm0_31) 7439q31 __builtin_mips_shra_r_w (q31, i32) 7440v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) 7441v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) 7442v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) 7443q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) 7444q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) 7445a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) 7446a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) 7447a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) 7448a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) 7449a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) 7450a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) 7451a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) 7452a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) 7453a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) 7454a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) 7455a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) 7456a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) 7457a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) 7458i32 __builtin_mips_bitrev (i32) 7459i32 __builtin_mips_insv (i32, i32) 7460v4i8 __builtin_mips_repl_qb (imm0_255) 7461v4i8 __builtin_mips_repl_qb (i32) 7462v2q15 __builtin_mips_repl_ph (imm_n512_511) 7463v2q15 __builtin_mips_repl_ph (i32) 7464void __builtin_mips_cmpu_eq_qb (v4i8, v4i8) 7465void __builtin_mips_cmpu_lt_qb (v4i8, v4i8) 7466void __builtin_mips_cmpu_le_qb (v4i8, v4i8) 7467i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) 7468i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) 7469i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) 7470void __builtin_mips_cmp_eq_ph (v2q15, v2q15) 7471void __builtin_mips_cmp_lt_ph (v2q15, v2q15) 7472void __builtin_mips_cmp_le_ph (v2q15, v2q15) 7473v4i8 __builtin_mips_pick_qb (v4i8, v4i8) 7474v2q15 __builtin_mips_pick_ph (v2q15, v2q15) 7475v2q15 __builtin_mips_packrl_ph (v2q15, v2q15) 7476i32 __builtin_mips_extr_w (a64, imm0_31) 7477i32 __builtin_mips_extr_w (a64, i32) 7478i32 __builtin_mips_extr_r_w (a64, imm0_31) 7479i32 __builtin_mips_extr_s_h (a64, i32) 7480i32 __builtin_mips_extr_rs_w (a64, imm0_31) 7481i32 __builtin_mips_extr_rs_w (a64, i32) 7482i32 __builtin_mips_extr_s_h (a64, imm0_31) 7483i32 __builtin_mips_extr_r_w (a64, i32) 7484i32 __builtin_mips_extp (a64, imm0_31) 7485i32 __builtin_mips_extp (a64, i32) 7486i32 __builtin_mips_extpdp (a64, imm0_31) 7487i32 __builtin_mips_extpdp (a64, i32) 7488a64 __builtin_mips_shilo (a64, imm_n32_31) 7489a64 __builtin_mips_shilo (a64, i32) 7490a64 __builtin_mips_mthlip (a64, i32) 7491void __builtin_mips_wrdsp (i32, imm0_63) 7492i32 __builtin_mips_rddsp (imm0_63) 7493i32 __builtin_mips_lbux (void *, i32) 7494i32 __builtin_mips_lhx (void *, i32) 7495i32 __builtin_mips_lwx (void *, i32) 7496i32 __builtin_mips_bposge32 (void) 7497@end smallexample 7498 7499@node MIPS Paired-Single Support 7500@subsection MIPS Paired-Single Support 7501 7502The MIPS64 architecture includes a number of instructions that 7503operate on pairs of single-precision floating-point values. 7504Each pair is packed into a 64-bit floating-point register, 7505with one element being designated the ``upper half'' and 7506the other being designated the ``lower half''. 7507 7508GCC supports paired-single operations using both the generic 7509vector extensions (@pxref{Vector Extensions}) and a collection of 7510MIPS-specific built-in functions. Both kinds of support are 7511enabled by the @option{-mpaired-single} command-line option. 7512 7513The vector type associated with paired-single values is usually 7514called @code{v2sf}. It can be defined in C as follows: 7515 7516@smallexample 7517typedef float v2sf __attribute__ ((vector_size (8))); 7518@end smallexample 7519 7520@code{v2sf} values are initialized in the same way as aggregates. 7521For example: 7522 7523@smallexample 7524v2sf a = @{1.5, 9.1@}; 7525v2sf b; 7526float e, f; 7527b = (v2sf) @{e, f@}; 7528@end smallexample 7529 7530@emph{Note:} The CPU's endianness determines which value is stored in 7531the upper half of a register and which value is stored in the lower half. 7532On little-endian targets, the first value is the lower one and the second 7533value is the upper one. The opposite order applies to big-endian targets. 7534For example, the code above will set the lower half of @code{a} to 7535@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. 7536 7537@menu 7538* Paired-Single Arithmetic:: 7539* Paired-Single Built-in Functions:: 7540* MIPS-3D Built-in Functions:: 7541@end menu 7542 7543@node Paired-Single Arithmetic 7544@subsubsection Paired-Single Arithmetic 7545 7546The table below lists the @code{v2sf} operations for which hardware 7547support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} 7548values and @code{x} is an integral value. 7549 7550@multitable @columnfractions .50 .50 7551@item C code @tab MIPS instruction 7552@item @code{a + b} @tab @code{add.ps} 7553@item @code{a - b} @tab @code{sub.ps} 7554@item @code{-a} @tab @code{neg.ps} 7555@item @code{a * b} @tab @code{mul.ps} 7556@item @code{a * b + c} @tab @code{madd.ps} 7557@item @code{a * b - c} @tab @code{msub.ps} 7558@item @code{-(a * b + c)} @tab @code{nmadd.ps} 7559@item @code{-(a * b - c)} @tab @code{nmsub.ps} 7560@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} 7561@end multitable 7562 7563Note that the multiply-accumulate instructions can be disabled 7564using the command-line option @code{-mno-fused-madd}. 7565 7566@node Paired-Single Built-in Functions 7567@subsubsection Paired-Single Built-in Functions 7568 7569The following paired-single functions map directly to a particular 7570MIPS instruction. Please refer to the architecture specification 7571for details on what each instruction does. 7572 7573@table @code 7574@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) 7575Pair lower lower (@code{pll.ps}). 7576 7577@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) 7578Pair upper lower (@code{pul.ps}). 7579 7580@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) 7581Pair lower upper (@code{plu.ps}). 7582 7583@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) 7584Pair upper upper (@code{puu.ps}). 7585 7586@item v2sf __builtin_mips_cvt_ps_s (float, float) 7587Convert pair to paired single (@code{cvt.ps.s}). 7588 7589@item float __builtin_mips_cvt_s_pl (v2sf) 7590Convert pair lower to single (@code{cvt.s.pl}). 7591 7592@item float __builtin_mips_cvt_s_pu (v2sf) 7593Convert pair upper to single (@code{cvt.s.pu}). 7594 7595@item v2sf __builtin_mips_abs_ps (v2sf) 7596Absolute value (@code{abs.ps}). 7597 7598@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) 7599Align variable (@code{alnv.ps}). 7600 7601@emph{Note:} The value of the third parameter must be 0 or 4 7602modulo 8, otherwise the result will be unpredictable. Please read the 7603instruction description for details. 7604@end table 7605 7606The following multi-instruction functions are also available. 7607In each case, @var{cond} can be any of the 16 floating-point conditions: 7608@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 7609@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, 7610@code{lt}, @code{nge}, @code{le} or @code{ngt}. 7611 7612@table @code 7613@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7614@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7615Conditional move based on floating point comparison (@code{c.@var{cond}.ps}, 7616@code{movt.ps}/@code{movf.ps}). 7617 7618The @code{movt} functions return the value @var{x} computed by: 7619 7620@smallexample 7621c.@var{cond}.ps @var{cc},@var{a},@var{b} 7622mov.ps @var{x},@var{c} 7623movt.ps @var{x},@var{d},@var{cc} 7624@end smallexample 7625 7626The @code{movf} functions are similar but use @code{movf.ps} instead 7627of @code{movt.ps}. 7628 7629@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7630@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7631Comparison of two paired-single values (@code{c.@var{cond}.ps}, 7632@code{bc1t}/@code{bc1f}). 7633 7634These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 7635and return either the upper or lower half of the result. For example: 7636 7637@smallexample 7638v2sf a, b; 7639if (__builtin_mips_upper_c_eq_ps (a, b)) 7640 upper_halves_are_equal (); 7641else 7642 upper_halves_are_unequal (); 7643 7644if (__builtin_mips_lower_c_eq_ps (a, b)) 7645 lower_halves_are_equal (); 7646else 7647 lower_halves_are_unequal (); 7648@end smallexample 7649@end table 7650 7651@node MIPS-3D Built-in Functions 7652@subsubsection MIPS-3D Built-in Functions 7653 7654The MIPS-3D Application-Specific Extension (ASE) includes additional 7655paired-single instructions that are designed to improve the performance 7656of 3D graphics operations. Support for these instructions is controlled 7657by the @option{-mips3d} command-line option. 7658 7659The functions listed below map directly to a particular MIPS-3D 7660instruction. Please refer to the architecture specification for 7661more details on what each instruction does. 7662 7663@table @code 7664@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) 7665Reduction add (@code{addr.ps}). 7666 7667@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) 7668Reduction multiply (@code{mulr.ps}). 7669 7670@item v2sf __builtin_mips_cvt_pw_ps (v2sf) 7671Convert paired single to paired word (@code{cvt.pw.ps}). 7672 7673@item v2sf __builtin_mips_cvt_ps_pw (v2sf) 7674Convert paired word to paired single (@code{cvt.ps.pw}). 7675 7676@item float __builtin_mips_recip1_s (float) 7677@itemx double __builtin_mips_recip1_d (double) 7678@itemx v2sf __builtin_mips_recip1_ps (v2sf) 7679Reduced precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). 7680 7681@item float __builtin_mips_recip2_s (float, float) 7682@itemx double __builtin_mips_recip2_d (double, double) 7683@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) 7684Reduced precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). 7685 7686@item float __builtin_mips_rsqrt1_s (float) 7687@itemx double __builtin_mips_rsqrt1_d (double) 7688@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) 7689Reduced precision reciprocal square root (sequence step 1) 7690(@code{rsqrt1.@var{fmt}}). 7691 7692@item float __builtin_mips_rsqrt2_s (float, float) 7693@itemx double __builtin_mips_rsqrt2_d (double, double) 7694@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) 7695Reduced precision reciprocal square root (sequence step 2) 7696(@code{rsqrt2.@var{fmt}}). 7697@end table 7698 7699The following multi-instruction functions are also available. 7700In each case, @var{cond} can be any of the 16 floating-point conditions: 7701@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 7702@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 7703@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. 7704 7705@table @code 7706@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) 7707@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) 7708Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, 7709@code{bc1t}/@code{bc1f}). 7710 7711These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} 7712or @code{cabs.@var{cond}.d} and return the result as a boolean value. 7713For example: 7714 7715@smallexample 7716float a, b; 7717if (__builtin_mips_cabs_eq_s (a, b)) 7718 true (); 7719else 7720 false (); 7721@end smallexample 7722 7723@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7724@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7725Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, 7726@code{bc1t}/@code{bc1f}). 7727 7728These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} 7729and return either the upper or lower half of the result. For example: 7730 7731@smallexample 7732v2sf a, b; 7733if (__builtin_mips_upper_cabs_eq_ps (a, b)) 7734 upper_halves_are_equal (); 7735else 7736 upper_halves_are_unequal (); 7737 7738if (__builtin_mips_lower_cabs_eq_ps (a, b)) 7739 lower_halves_are_equal (); 7740else 7741 lower_halves_are_unequal (); 7742@end smallexample 7743 7744@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7745@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7746Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, 7747@code{movt.ps}/@code{movf.ps}). 7748 7749The @code{movt} functions return the value @var{x} computed by: 7750 7751@smallexample 7752cabs.@var{cond}.ps @var{cc},@var{a},@var{b} 7753mov.ps @var{x},@var{c} 7754movt.ps @var{x},@var{d},@var{cc} 7755@end smallexample 7756 7757The @code{movf} functions are similar but use @code{movf.ps} instead 7758of @code{movt.ps}. 7759 7760@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7761@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7762@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7763@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7764Comparison of two paired-single values 7765(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 7766@code{bc1any2t}/@code{bc1any2f}). 7767 7768These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 7769or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either 7770result is true and the @code{all} forms return true if both results are true. 7771For example: 7772 7773@smallexample 7774v2sf a, b; 7775if (__builtin_mips_any_c_eq_ps (a, b)) 7776 one_is_true (); 7777else 7778 both_are_false (); 7779 7780if (__builtin_mips_all_c_eq_ps (a, b)) 7781 both_are_true (); 7782else 7783 one_is_false (); 7784@end smallexample 7785 7786@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7787@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7788@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7789@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7790Comparison of four paired-single values 7791(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 7792@code{bc1any4t}/@code{bc1any4f}). 7793 7794These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} 7795to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. 7796The @code{any} forms return true if any of the four results are true 7797and the @code{all} forms return true if all four results are true. 7798For example: 7799 7800@smallexample 7801v2sf a, b, c, d; 7802if (__builtin_mips_any_c_eq_4s (a, b, c, d)) 7803 some_are_true (); 7804else 7805 all_are_false (); 7806 7807if (__builtin_mips_all_c_eq_4s (a, b, c, d)) 7808 all_are_true (); 7809else 7810 some_are_false (); 7811@end smallexample 7812@end table 7813 7814@node PowerPC AltiVec Built-in Functions 7815@subsection PowerPC AltiVec Built-in Functions 7816 7817GCC provides an interface for the PowerPC family of processors to access 7818the AltiVec operations described in Motorola's AltiVec Programming 7819Interface Manual. The interface is made available by including 7820@code{<altivec.h>} and using @option{-maltivec} and 7821@option{-mabi=altivec}. The interface supports the following vector 7822types. 7823 7824@smallexample 7825vector unsigned char 7826vector signed char 7827vector bool char 7828 7829vector unsigned short 7830vector signed short 7831vector bool short 7832vector pixel 7833 7834vector unsigned int 7835vector signed int 7836vector bool int 7837vector float 7838@end smallexample 7839 7840GCC's implementation of the high-level language interface available from 7841C and C++ code differs from Motorola's documentation in several ways. 7842 7843@itemize @bullet 7844 7845@item 7846A vector constant is a list of constant expressions within curly braces. 7847 7848@item 7849A vector initializer requires no cast if the vector constant is of the 7850same type as the variable it is initializing. 7851 7852@item 7853If @code{signed} or @code{unsigned} is omitted, the signedness of the 7854vector type is the default signedness of the base type. The default 7855varies depending on the operating system, so a portable program should 7856always specify the signedness. 7857 7858@item 7859Compiling with @option{-maltivec} adds keywords @code{__vector}, 7860@code{__pixel}, and @code{__bool}. Macros @option{vector}, 7861@code{pixel}, and @code{bool} are defined in @code{<altivec.h>} and can 7862be undefined. 7863 7864@item 7865GCC allows using a @code{typedef} name as the type specifier for a 7866vector type. 7867 7868@item 7869For C, overloaded functions are implemented with macros so the following 7870does not work: 7871 7872@smallexample 7873 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); 7874@end smallexample 7875 7876Since @code{vec_add} is a macro, the vector constant in the example 7877is treated as four separate arguments. Wrap the entire argument in 7878parentheses for this to work. 7879@end itemize 7880 7881@emph{Note:} Only the @code{<altivec.h>} interface is supported. 7882Internally, GCC uses built-in functions to achieve the functionality in 7883the aforementioned header file, but they are not supported and are 7884subject to change without notice. 7885 7886The following interfaces are supported for the generic and specific 7887AltiVec operations and the AltiVec predicates. In cases where there 7888is a direct mapping between generic and specific operations, only the 7889generic names are shown here, although the specific operations can also 7890be used. 7891 7892Arguments that are documented as @code{const int} require literal 7893integral values within the range required for that operation. 7894 7895@smallexample 7896vector signed char vec_abs (vector signed char); 7897vector signed short vec_abs (vector signed short); 7898vector signed int vec_abs (vector signed int); 7899vector float vec_abs (vector float); 7900 7901vector signed char vec_abss (vector signed char); 7902vector signed short vec_abss (vector signed short); 7903vector signed int vec_abss (vector signed int); 7904 7905vector signed char vec_add (vector bool char, vector signed char); 7906vector signed char vec_add (vector signed char, vector bool char); 7907vector signed char vec_add (vector signed char, vector signed char); 7908vector unsigned char vec_add (vector bool char, vector unsigned char); 7909vector unsigned char vec_add (vector unsigned char, vector bool char); 7910vector unsigned char vec_add (vector unsigned char, 7911 vector unsigned char); 7912vector signed short vec_add (vector bool short, vector signed short); 7913vector signed short vec_add (vector signed short, vector bool short); 7914vector signed short vec_add (vector signed short, vector signed short); 7915vector unsigned short vec_add (vector bool short, 7916 vector unsigned short); 7917vector unsigned short vec_add (vector unsigned short, 7918 vector bool short); 7919vector unsigned short vec_add (vector unsigned short, 7920 vector unsigned short); 7921vector signed int vec_add (vector bool int, vector signed int); 7922vector signed int vec_add (vector signed int, vector bool int); 7923vector signed int vec_add (vector signed int, vector signed int); 7924vector unsigned int vec_add (vector bool int, vector unsigned int); 7925vector unsigned int vec_add (vector unsigned int, vector bool int); 7926vector unsigned int vec_add (vector unsigned int, vector unsigned int); 7927vector float vec_add (vector float, vector float); 7928 7929vector float vec_vaddfp (vector float, vector float); 7930 7931vector signed int vec_vadduwm (vector bool int, vector signed int); 7932vector signed int vec_vadduwm (vector signed int, vector bool int); 7933vector signed int vec_vadduwm (vector signed int, vector signed int); 7934vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); 7935vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); 7936vector unsigned int vec_vadduwm (vector unsigned int, 7937 vector unsigned int); 7938 7939vector signed short vec_vadduhm (vector bool short, 7940 vector signed short); 7941vector signed short vec_vadduhm (vector signed short, 7942 vector bool short); 7943vector signed short vec_vadduhm (vector signed short, 7944 vector signed short); 7945vector unsigned short vec_vadduhm (vector bool short, 7946 vector unsigned short); 7947vector unsigned short vec_vadduhm (vector unsigned short, 7948 vector bool short); 7949vector unsigned short vec_vadduhm (vector unsigned short, 7950 vector unsigned short); 7951 7952vector signed char vec_vaddubm (vector bool char, vector signed char); 7953vector signed char vec_vaddubm (vector signed char, vector bool char); 7954vector signed char vec_vaddubm (vector signed char, vector signed char); 7955vector unsigned char vec_vaddubm (vector bool char, 7956 vector unsigned char); 7957vector unsigned char vec_vaddubm (vector unsigned char, 7958 vector bool char); 7959vector unsigned char vec_vaddubm (vector unsigned char, 7960 vector unsigned char); 7961 7962vector unsigned int vec_addc (vector unsigned int, vector unsigned int); 7963 7964vector unsigned char vec_adds (vector bool char, vector unsigned char); 7965vector unsigned char vec_adds (vector unsigned char, vector bool char); 7966vector unsigned char vec_adds (vector unsigned char, 7967 vector unsigned char); 7968vector signed char vec_adds (vector bool char, vector signed char); 7969vector signed char vec_adds (vector signed char, vector bool char); 7970vector signed char vec_adds (vector signed char, vector signed char); 7971vector unsigned short vec_adds (vector bool short, 7972 vector unsigned short); 7973vector unsigned short vec_adds (vector unsigned short, 7974 vector bool short); 7975vector unsigned short vec_adds (vector unsigned short, 7976 vector unsigned short); 7977vector signed short vec_adds (vector bool short, vector signed short); 7978vector signed short vec_adds (vector signed short, vector bool short); 7979vector signed short vec_adds (vector signed short, vector signed short); 7980vector unsigned int vec_adds (vector bool int, vector unsigned int); 7981vector unsigned int vec_adds (vector unsigned int, vector bool int); 7982vector unsigned int vec_adds (vector unsigned int, vector unsigned int); 7983vector signed int vec_adds (vector bool int, vector signed int); 7984vector signed int vec_adds (vector signed int, vector bool int); 7985vector signed int vec_adds (vector signed int, vector signed int); 7986 7987vector signed int vec_vaddsws (vector bool int, vector signed int); 7988vector signed int vec_vaddsws (vector signed int, vector bool int); 7989vector signed int vec_vaddsws (vector signed int, vector signed int); 7990 7991vector unsigned int vec_vadduws (vector bool int, vector unsigned int); 7992vector unsigned int vec_vadduws (vector unsigned int, vector bool int); 7993vector unsigned int vec_vadduws (vector unsigned int, 7994 vector unsigned int); 7995 7996vector signed short vec_vaddshs (vector bool short, 7997 vector signed short); 7998vector signed short vec_vaddshs (vector signed short, 7999 vector bool short); 8000vector signed short vec_vaddshs (vector signed short, 8001 vector signed short); 8002 8003vector unsigned short vec_vadduhs (vector bool short, 8004 vector unsigned short); 8005vector unsigned short vec_vadduhs (vector unsigned short, 8006 vector bool short); 8007vector unsigned short vec_vadduhs (vector unsigned short, 8008 vector unsigned short); 8009 8010vector signed char vec_vaddsbs (vector bool char, vector signed char); 8011vector signed char vec_vaddsbs (vector signed char, vector bool char); 8012vector signed char vec_vaddsbs (vector signed char, vector signed char); 8013 8014vector unsigned char vec_vaddubs (vector bool char, 8015 vector unsigned char); 8016vector unsigned char vec_vaddubs (vector unsigned char, 8017 vector bool char); 8018vector unsigned char vec_vaddubs (vector unsigned char, 8019 vector unsigned char); 8020 8021vector float vec_and (vector float, vector float); 8022vector float vec_and (vector float, vector bool int); 8023vector float vec_and (vector bool int, vector float); 8024vector bool int vec_and (vector bool int, vector bool int); 8025vector signed int vec_and (vector bool int, vector signed int); 8026vector signed int vec_and (vector signed int, vector bool int); 8027vector signed int vec_and (vector signed int, vector signed int); 8028vector unsigned int vec_and (vector bool int, vector unsigned int); 8029vector unsigned int vec_and (vector unsigned int, vector bool int); 8030vector unsigned int vec_and (vector unsigned int, vector unsigned int); 8031vector bool short vec_and (vector bool short, vector bool short); 8032vector signed short vec_and (vector bool short, vector signed short); 8033vector signed short vec_and (vector signed short, vector bool short); 8034vector signed short vec_and (vector signed short, vector signed short); 8035vector unsigned short vec_and (vector bool short, 8036 vector unsigned short); 8037vector unsigned short vec_and (vector unsigned short, 8038 vector bool short); 8039vector unsigned short vec_and (vector unsigned short, 8040 vector unsigned short); 8041vector signed char vec_and (vector bool char, vector signed char); 8042vector bool char vec_and (vector bool char, vector bool char); 8043vector signed char vec_and (vector signed char, vector bool char); 8044vector signed char vec_and (vector signed char, vector signed char); 8045vector unsigned char vec_and (vector bool char, vector unsigned char); 8046vector unsigned char vec_and (vector unsigned char, vector bool char); 8047vector unsigned char vec_and (vector unsigned char, 8048 vector unsigned char); 8049 8050vector float vec_andc (vector float, vector float); 8051vector float vec_andc (vector float, vector bool int); 8052vector float vec_andc (vector bool int, vector float); 8053vector bool int vec_andc (vector bool int, vector bool int); 8054vector signed int vec_andc (vector bool int, vector signed int); 8055vector signed int vec_andc (vector signed int, vector bool int); 8056vector signed int vec_andc (vector signed int, vector signed int); 8057vector unsigned int vec_andc (vector bool int, vector unsigned int); 8058vector unsigned int vec_andc (vector unsigned int, vector bool int); 8059vector unsigned int vec_andc (vector unsigned int, vector unsigned int); 8060vector bool short vec_andc (vector bool short, vector bool short); 8061vector signed short vec_andc (vector bool short, vector signed short); 8062vector signed short vec_andc (vector signed short, vector bool short); 8063vector signed short vec_andc (vector signed short, vector signed short); 8064vector unsigned short vec_andc (vector bool short, 8065 vector unsigned short); 8066vector unsigned short vec_andc (vector unsigned short, 8067 vector bool short); 8068vector unsigned short vec_andc (vector unsigned short, 8069 vector unsigned short); 8070vector signed char vec_andc (vector bool char, vector signed char); 8071vector bool char vec_andc (vector bool char, vector bool char); 8072vector signed char vec_andc (vector signed char, vector bool char); 8073vector signed char vec_andc (vector signed char, vector signed char); 8074vector unsigned char vec_andc (vector bool char, vector unsigned char); 8075vector unsigned char vec_andc (vector unsigned char, vector bool char); 8076vector unsigned char vec_andc (vector unsigned char, 8077 vector unsigned char); 8078 8079vector unsigned char vec_avg (vector unsigned char, 8080 vector unsigned char); 8081vector signed char vec_avg (vector signed char, vector signed char); 8082vector unsigned short vec_avg (vector unsigned short, 8083 vector unsigned short); 8084vector signed short vec_avg (vector signed short, vector signed short); 8085vector unsigned int vec_avg (vector unsigned int, vector unsigned int); 8086vector signed int vec_avg (vector signed int, vector signed int); 8087 8088vector signed int vec_vavgsw (vector signed int, vector signed int); 8089 8090vector unsigned int vec_vavguw (vector unsigned int, 8091 vector unsigned int); 8092 8093vector signed short vec_vavgsh (vector signed short, 8094 vector signed short); 8095 8096vector unsigned short vec_vavguh (vector unsigned short, 8097 vector unsigned short); 8098 8099vector signed char vec_vavgsb (vector signed char, vector signed char); 8100 8101vector unsigned char vec_vavgub (vector unsigned char, 8102 vector unsigned char); 8103 8104vector float vec_ceil (vector float); 8105 8106vector signed int vec_cmpb (vector float, vector float); 8107 8108vector bool char vec_cmpeq (vector signed char, vector signed char); 8109vector bool char vec_cmpeq (vector unsigned char, vector unsigned char); 8110vector bool short vec_cmpeq (vector signed short, vector signed short); 8111vector bool short vec_cmpeq (vector unsigned short, 8112 vector unsigned short); 8113vector bool int vec_cmpeq (vector signed int, vector signed int); 8114vector bool int vec_cmpeq (vector unsigned int, vector unsigned int); 8115vector bool int vec_cmpeq (vector float, vector float); 8116 8117vector bool int vec_vcmpeqfp (vector float, vector float); 8118 8119vector bool int vec_vcmpequw (vector signed int, vector signed int); 8120vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); 8121 8122vector bool short vec_vcmpequh (vector signed short, 8123 vector signed short); 8124vector bool short vec_vcmpequh (vector unsigned short, 8125 vector unsigned short); 8126 8127vector bool char vec_vcmpequb (vector signed char, vector signed char); 8128vector bool char vec_vcmpequb (vector unsigned char, 8129 vector unsigned char); 8130 8131vector bool int vec_cmpge (vector float, vector float); 8132 8133vector bool char vec_cmpgt (vector unsigned char, vector unsigned char); 8134vector bool char vec_cmpgt (vector signed char, vector signed char); 8135vector bool short vec_cmpgt (vector unsigned short, 8136 vector unsigned short); 8137vector bool short vec_cmpgt (vector signed short, vector signed short); 8138vector bool int vec_cmpgt (vector unsigned int, vector unsigned int); 8139vector bool int vec_cmpgt (vector signed int, vector signed int); 8140vector bool int vec_cmpgt (vector float, vector float); 8141 8142vector bool int vec_vcmpgtfp (vector float, vector float); 8143 8144vector bool int vec_vcmpgtsw (vector signed int, vector signed int); 8145 8146vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); 8147 8148vector bool short vec_vcmpgtsh (vector signed short, 8149 vector signed short); 8150 8151vector bool short vec_vcmpgtuh (vector unsigned short, 8152 vector unsigned short); 8153 8154vector bool char vec_vcmpgtsb (vector signed char, vector signed char); 8155 8156vector bool char vec_vcmpgtub (vector unsigned char, 8157 vector unsigned char); 8158 8159vector bool int vec_cmple (vector float, vector float); 8160 8161vector bool char vec_cmplt (vector unsigned char, vector unsigned char); 8162vector bool char vec_cmplt (vector signed char, vector signed char); 8163vector bool short vec_cmplt (vector unsigned short, 8164 vector unsigned short); 8165vector bool short vec_cmplt (vector signed short, vector signed short); 8166vector bool int vec_cmplt (vector unsigned int, vector unsigned int); 8167vector bool int vec_cmplt (vector signed int, vector signed int); 8168vector bool int vec_cmplt (vector float, vector float); 8169 8170vector float vec_ctf (vector unsigned int, const int); 8171vector float vec_ctf (vector signed int, const int); 8172 8173vector float vec_vcfsx (vector signed int, const int); 8174 8175vector float vec_vcfux (vector unsigned int, const int); 8176 8177vector signed int vec_cts (vector float, const int); 8178 8179vector unsigned int vec_ctu (vector float, const int); 8180 8181void vec_dss (const int); 8182 8183void vec_dssall (void); 8184 8185void vec_dst (const vector unsigned char *, int, const int); 8186void vec_dst (const vector signed char *, int, const int); 8187void vec_dst (const vector bool char *, int, const int); 8188void vec_dst (const vector unsigned short *, int, const int); 8189void vec_dst (const vector signed short *, int, const int); 8190void vec_dst (const vector bool short *, int, const int); 8191void vec_dst (const vector pixel *, int, const int); 8192void vec_dst (const vector unsigned int *, int, const int); 8193void vec_dst (const vector signed int *, int, const int); 8194void vec_dst (const vector bool int *, int, const int); 8195void vec_dst (const vector float *, int, const int); 8196void vec_dst (const unsigned char *, int, const int); 8197void vec_dst (const signed char *, int, const int); 8198void vec_dst (const unsigned short *, int, const int); 8199void vec_dst (const short *, int, const int); 8200void vec_dst (const unsigned int *, int, const int); 8201void vec_dst (const int *, int, const int); 8202void vec_dst (const unsigned long *, int, const int); 8203void vec_dst (const long *, int, const int); 8204void vec_dst (const float *, int, const int); 8205 8206void vec_dstst (const vector unsigned char *, int, const int); 8207void vec_dstst (const vector signed char *, int, const int); 8208void vec_dstst (const vector bool char *, int, const int); 8209void vec_dstst (const vector unsigned short *, int, const int); 8210void vec_dstst (const vector signed short *, int, const int); 8211void vec_dstst (const vector bool short *, int, const int); 8212void vec_dstst (const vector pixel *, int, const int); 8213void vec_dstst (const vector unsigned int *, int, const int); 8214void vec_dstst (const vector signed int *, int, const int); 8215void vec_dstst (const vector bool int *, int, const int); 8216void vec_dstst (const vector float *, int, const int); 8217void vec_dstst (const unsigned char *, int, const int); 8218void vec_dstst (const signed char *, int, const int); 8219void vec_dstst (const unsigned short *, int, const int); 8220void vec_dstst (const short *, int, const int); 8221void vec_dstst (const unsigned int *, int, const int); 8222void vec_dstst (const int *, int, const int); 8223void vec_dstst (const unsigned long *, int, const int); 8224void vec_dstst (const long *, int, const int); 8225void vec_dstst (const float *, int, const int); 8226 8227void vec_dststt (const vector unsigned char *, int, const int); 8228void vec_dststt (const vector signed char *, int, const int); 8229void vec_dststt (const vector bool char *, int, const int); 8230void vec_dststt (const vector unsigned short *, int, const int); 8231void vec_dststt (const vector signed short *, int, const int); 8232void vec_dststt (const vector bool short *, int, const int); 8233void vec_dststt (const vector pixel *, int, const int); 8234void vec_dststt (const vector unsigned int *, int, const int); 8235void vec_dststt (const vector signed int *, int, const int); 8236void vec_dststt (const vector bool int *, int, const int); 8237void vec_dststt (const vector float *, int, const int); 8238void vec_dststt (const unsigned char *, int, const int); 8239void vec_dststt (const signed char *, int, const int); 8240void vec_dststt (const unsigned short *, int, const int); 8241void vec_dststt (const short *, int, const int); 8242void vec_dststt (const unsigned int *, int, const int); 8243void vec_dststt (const int *, int, const int); 8244void vec_dststt (const unsigned long *, int, const int); 8245void vec_dststt (const long *, int, const int); 8246void vec_dststt (const float *, int, const int); 8247 8248void vec_dstt (const vector unsigned char *, int, const int); 8249void vec_dstt (const vector signed char *, int, const int); 8250void vec_dstt (const vector bool char *, int, const int); 8251void vec_dstt (const vector unsigned short *, int, const int); 8252void vec_dstt (const vector signed short *, int, const int); 8253void vec_dstt (const vector bool short *, int, const int); 8254void vec_dstt (const vector pixel *, int, const int); 8255void vec_dstt (const vector unsigned int *, int, const int); 8256void vec_dstt (const vector signed int *, int, const int); 8257void vec_dstt (const vector bool int *, int, const int); 8258void vec_dstt (const vector float *, int, const int); 8259void vec_dstt (const unsigned char *, int, const int); 8260void vec_dstt (const signed char *, int, const int); 8261void vec_dstt (const unsigned short *, int, const int); 8262void vec_dstt (const short *, int, const int); 8263void vec_dstt (const unsigned int *, int, const int); 8264void vec_dstt (const int *, int, const int); 8265void vec_dstt (const unsigned long *, int, const int); 8266void vec_dstt (const long *, int, const int); 8267void vec_dstt (const float *, int, const int); 8268 8269vector float vec_expte (vector float); 8270 8271vector float vec_floor (vector float); 8272 8273vector float vec_ld (int, const vector float *); 8274vector float vec_ld (int, const float *); 8275vector bool int vec_ld (int, const vector bool int *); 8276vector signed int vec_ld (int, const vector signed int *); 8277vector signed int vec_ld (int, const int *); 8278vector signed int vec_ld (int, const long *); 8279vector unsigned int vec_ld (int, const vector unsigned int *); 8280vector unsigned int vec_ld (int, const unsigned int *); 8281vector unsigned int vec_ld (int, const unsigned long *); 8282vector bool short vec_ld (int, const vector bool short *); 8283vector pixel vec_ld (int, const vector pixel *); 8284vector signed short vec_ld (int, const vector signed short *); 8285vector signed short vec_ld (int, const short *); 8286vector unsigned short vec_ld (int, const vector unsigned short *); 8287vector unsigned short vec_ld (int, const unsigned short *); 8288vector bool char vec_ld (int, const vector bool char *); 8289vector signed char vec_ld (int, const vector signed char *); 8290vector signed char vec_ld (int, const signed char *); 8291vector unsigned char vec_ld (int, const vector unsigned char *); 8292vector unsigned char vec_ld (int, const unsigned char *); 8293 8294vector signed char vec_lde (int, const signed char *); 8295vector unsigned char vec_lde (int, const unsigned char *); 8296vector signed short vec_lde (int, const short *); 8297vector unsigned short vec_lde (int, const unsigned short *); 8298vector float vec_lde (int, const float *); 8299vector signed int vec_lde (int, const int *); 8300vector unsigned int vec_lde (int, const unsigned int *); 8301vector signed int vec_lde (int, const long *); 8302vector unsigned int vec_lde (int, const unsigned long *); 8303 8304vector float vec_lvewx (int, float *); 8305vector signed int vec_lvewx (int, int *); 8306vector unsigned int vec_lvewx (int, unsigned int *); 8307vector signed int vec_lvewx (int, long *); 8308vector unsigned int vec_lvewx (int, unsigned long *); 8309 8310vector signed short vec_lvehx (int, short *); 8311vector unsigned short vec_lvehx (int, unsigned short *); 8312 8313vector signed char vec_lvebx (int, char *); 8314vector unsigned char vec_lvebx (int, unsigned char *); 8315 8316vector float vec_ldl (int, const vector float *); 8317vector float vec_ldl (int, const float *); 8318vector bool int vec_ldl (int, const vector bool int *); 8319vector signed int vec_ldl (int, const vector signed int *); 8320vector signed int vec_ldl (int, const int *); 8321vector signed int vec_ldl (int, const long *); 8322vector unsigned int vec_ldl (int, const vector unsigned int *); 8323vector unsigned int vec_ldl (int, const unsigned int *); 8324vector unsigned int vec_ldl (int, const unsigned long *); 8325vector bool short vec_ldl (int, const vector bool short *); 8326vector pixel vec_ldl (int, const vector pixel *); 8327vector signed short vec_ldl (int, const vector signed short *); 8328vector signed short vec_ldl (int, const short *); 8329vector unsigned short vec_ldl (int, const vector unsigned short *); 8330vector unsigned short vec_ldl (int, const unsigned short *); 8331vector bool char vec_ldl (int, const vector bool char *); 8332vector signed char vec_ldl (int, const vector signed char *); 8333vector signed char vec_ldl (int, const signed char *); 8334vector unsigned char vec_ldl (int, const vector unsigned char *); 8335vector unsigned char vec_ldl (int, const unsigned char *); 8336 8337vector float vec_loge (vector float); 8338 8339vector unsigned char vec_lvsl (int, const volatile unsigned char *); 8340vector unsigned char vec_lvsl (int, const volatile signed char *); 8341vector unsigned char vec_lvsl (int, const volatile unsigned short *); 8342vector unsigned char vec_lvsl (int, const volatile short *); 8343vector unsigned char vec_lvsl (int, const volatile unsigned int *); 8344vector unsigned char vec_lvsl (int, const volatile int *); 8345vector unsigned char vec_lvsl (int, const volatile unsigned long *); 8346vector unsigned char vec_lvsl (int, const volatile long *); 8347vector unsigned char vec_lvsl (int, const volatile float *); 8348 8349vector unsigned char vec_lvsr (int, const volatile unsigned char *); 8350vector unsigned char vec_lvsr (int, const volatile signed char *); 8351vector unsigned char vec_lvsr (int, const volatile unsigned short *); 8352vector unsigned char vec_lvsr (int, const volatile short *); 8353vector unsigned char vec_lvsr (int, const volatile unsigned int *); 8354vector unsigned char vec_lvsr (int, const volatile int *); 8355vector unsigned char vec_lvsr (int, const volatile unsigned long *); 8356vector unsigned char vec_lvsr (int, const volatile long *); 8357vector unsigned char vec_lvsr (int, const volatile float *); 8358 8359vector float vec_madd (vector float, vector float, vector float); 8360 8361vector signed short vec_madds (vector signed short, 8362 vector signed short, 8363 vector signed short); 8364 8365vector unsigned char vec_max (vector bool char, vector unsigned char); 8366vector unsigned char vec_max (vector unsigned char, vector bool char); 8367vector unsigned char vec_max (vector unsigned char, 8368 vector unsigned char); 8369vector signed char vec_max (vector bool char, vector signed char); 8370vector signed char vec_max (vector signed char, vector bool char); 8371vector signed char vec_max (vector signed char, vector signed char); 8372vector unsigned short vec_max (vector bool short, 8373 vector unsigned short); 8374vector unsigned short vec_max (vector unsigned short, 8375 vector bool short); 8376vector unsigned short vec_max (vector unsigned short, 8377 vector unsigned short); 8378vector signed short vec_max (vector bool short, vector signed short); 8379vector signed short vec_max (vector signed short, vector bool short); 8380vector signed short vec_max (vector signed short, vector signed short); 8381vector unsigned int vec_max (vector bool int, vector unsigned int); 8382vector unsigned int vec_max (vector unsigned int, vector bool int); 8383vector unsigned int vec_max (vector unsigned int, vector unsigned int); 8384vector signed int vec_max (vector bool int, vector signed int); 8385vector signed int vec_max (vector signed int, vector bool int); 8386vector signed int vec_max (vector signed int, vector signed int); 8387vector float vec_max (vector float, vector float); 8388 8389vector float vec_vmaxfp (vector float, vector float); 8390 8391vector signed int vec_vmaxsw (vector bool int, vector signed int); 8392vector signed int vec_vmaxsw (vector signed int, vector bool int); 8393vector signed int vec_vmaxsw (vector signed int, vector signed int); 8394 8395vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); 8396vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); 8397vector unsigned int vec_vmaxuw (vector unsigned int, 8398 vector unsigned int); 8399 8400vector signed short vec_vmaxsh (vector bool short, vector signed short); 8401vector signed short vec_vmaxsh (vector signed short, vector bool short); 8402vector signed short vec_vmaxsh (vector signed short, 8403 vector signed short); 8404 8405vector unsigned short vec_vmaxuh (vector bool short, 8406 vector unsigned short); 8407vector unsigned short vec_vmaxuh (vector unsigned short, 8408 vector bool short); 8409vector unsigned short vec_vmaxuh (vector unsigned short, 8410 vector unsigned short); 8411 8412vector signed char vec_vmaxsb (vector bool char, vector signed char); 8413vector signed char vec_vmaxsb (vector signed char, vector bool char); 8414vector signed char vec_vmaxsb (vector signed char, vector signed char); 8415 8416vector unsigned char vec_vmaxub (vector bool char, 8417 vector unsigned char); 8418vector unsigned char vec_vmaxub (vector unsigned char, 8419 vector bool char); 8420vector unsigned char vec_vmaxub (vector unsigned char, 8421 vector unsigned char); 8422 8423vector bool char vec_mergeh (vector bool char, vector bool char); 8424vector signed char vec_mergeh (vector signed char, vector signed char); 8425vector unsigned char vec_mergeh (vector unsigned char, 8426 vector unsigned char); 8427vector bool short vec_mergeh (vector bool short, vector bool short); 8428vector pixel vec_mergeh (vector pixel, vector pixel); 8429vector signed short vec_mergeh (vector signed short, 8430 vector signed short); 8431vector unsigned short vec_mergeh (vector unsigned short, 8432 vector unsigned short); 8433vector float vec_mergeh (vector float, vector float); 8434vector bool int vec_mergeh (vector bool int, vector bool int); 8435vector signed int vec_mergeh (vector signed int, vector signed int); 8436vector unsigned int vec_mergeh (vector unsigned int, 8437 vector unsigned int); 8438 8439vector float vec_vmrghw (vector float, vector float); 8440vector bool int vec_vmrghw (vector bool int, vector bool int); 8441vector signed int vec_vmrghw (vector signed int, vector signed int); 8442vector unsigned int vec_vmrghw (vector unsigned int, 8443 vector unsigned int); 8444 8445vector bool short vec_vmrghh (vector bool short, vector bool short); 8446vector signed short vec_vmrghh (vector signed short, 8447 vector signed short); 8448vector unsigned short vec_vmrghh (vector unsigned short, 8449 vector unsigned short); 8450vector pixel vec_vmrghh (vector pixel, vector pixel); 8451 8452vector bool char vec_vmrghb (vector bool char, vector bool char); 8453vector signed char vec_vmrghb (vector signed char, vector signed char); 8454vector unsigned char vec_vmrghb (vector unsigned char, 8455 vector unsigned char); 8456 8457vector bool char vec_mergel (vector bool char, vector bool char); 8458vector signed char vec_mergel (vector signed char, vector signed char); 8459vector unsigned char vec_mergel (vector unsigned char, 8460 vector unsigned char); 8461vector bool short vec_mergel (vector bool short, vector bool short); 8462vector pixel vec_mergel (vector pixel, vector pixel); 8463vector signed short vec_mergel (vector signed short, 8464 vector signed short); 8465vector unsigned short vec_mergel (vector unsigned short, 8466 vector unsigned short); 8467vector float vec_mergel (vector float, vector float); 8468vector bool int vec_mergel (vector bool int, vector bool int); 8469vector signed int vec_mergel (vector signed int, vector signed int); 8470vector unsigned int vec_mergel (vector unsigned int, 8471 vector unsigned int); 8472 8473vector float vec_vmrglw (vector float, vector float); 8474vector signed int vec_vmrglw (vector signed int, vector signed int); 8475vector unsigned int vec_vmrglw (vector unsigned int, 8476 vector unsigned int); 8477vector bool int vec_vmrglw (vector bool int, vector bool int); 8478 8479vector bool short vec_vmrglh (vector bool short, vector bool short); 8480vector signed short vec_vmrglh (vector signed short, 8481 vector signed short); 8482vector unsigned short vec_vmrglh (vector unsigned short, 8483 vector unsigned short); 8484vector pixel vec_vmrglh (vector pixel, vector pixel); 8485 8486vector bool char vec_vmrglb (vector bool char, vector bool char); 8487vector signed char vec_vmrglb (vector signed char, vector signed char); 8488vector unsigned char vec_vmrglb (vector unsigned char, 8489 vector unsigned char); 8490 8491vector unsigned short vec_mfvscr (void); 8492 8493vector unsigned char vec_min (vector bool char, vector unsigned char); 8494vector unsigned char vec_min (vector unsigned char, vector bool char); 8495vector unsigned char vec_min (vector unsigned char, 8496 vector unsigned char); 8497vector signed char vec_min (vector bool char, vector signed char); 8498vector signed char vec_min (vector signed char, vector bool char); 8499vector signed char vec_min (vector signed char, vector signed char); 8500vector unsigned short vec_min (vector bool short, 8501 vector unsigned short); 8502vector unsigned short vec_min (vector unsigned short, 8503 vector bool short); 8504vector unsigned short vec_min (vector unsigned short, 8505 vector unsigned short); 8506vector signed short vec_min (vector bool short, vector signed short); 8507vector signed short vec_min (vector signed short, vector bool short); 8508vector signed short vec_min (vector signed short, vector signed short); 8509vector unsigned int vec_min (vector bool int, vector unsigned int); 8510vector unsigned int vec_min (vector unsigned int, vector bool int); 8511vector unsigned int vec_min (vector unsigned int, vector unsigned int); 8512vector signed int vec_min (vector bool int, vector signed int); 8513vector signed int vec_min (vector signed int, vector bool int); 8514vector signed int vec_min (vector signed int, vector signed int); 8515vector float vec_min (vector float, vector float); 8516 8517vector float vec_vminfp (vector float, vector float); 8518 8519vector signed int vec_vminsw (vector bool int, vector signed int); 8520vector signed int vec_vminsw (vector signed int, vector bool int); 8521vector signed int vec_vminsw (vector signed int, vector signed int); 8522 8523vector unsigned int vec_vminuw (vector bool int, vector unsigned int); 8524vector unsigned int vec_vminuw (vector unsigned int, vector bool int); 8525vector unsigned int vec_vminuw (vector unsigned int, 8526 vector unsigned int); 8527 8528vector signed short vec_vminsh (vector bool short, vector signed short); 8529vector signed short vec_vminsh (vector signed short, vector bool short); 8530vector signed short vec_vminsh (vector signed short, 8531 vector signed short); 8532 8533vector unsigned short vec_vminuh (vector bool short, 8534 vector unsigned short); 8535vector unsigned short vec_vminuh (vector unsigned short, 8536 vector bool short); 8537vector unsigned short vec_vminuh (vector unsigned short, 8538 vector unsigned short); 8539 8540vector signed char vec_vminsb (vector bool char, vector signed char); 8541vector signed char vec_vminsb (vector signed char, vector bool char); 8542vector signed char vec_vminsb (vector signed char, vector signed char); 8543 8544vector unsigned char vec_vminub (vector bool char, 8545 vector unsigned char); 8546vector unsigned char vec_vminub (vector unsigned char, 8547 vector bool char); 8548vector unsigned char vec_vminub (vector unsigned char, 8549 vector unsigned char); 8550 8551vector signed short vec_mladd (vector signed short, 8552 vector signed short, 8553 vector signed short); 8554vector signed short vec_mladd (vector signed short, 8555 vector unsigned short, 8556 vector unsigned short); 8557vector signed short vec_mladd (vector unsigned short, 8558 vector signed short, 8559 vector signed short); 8560vector unsigned short vec_mladd (vector unsigned short, 8561 vector unsigned short, 8562 vector unsigned short); 8563 8564vector signed short vec_mradds (vector signed short, 8565 vector signed short, 8566 vector signed short); 8567 8568vector unsigned int vec_msum (vector unsigned char, 8569 vector unsigned char, 8570 vector unsigned int); 8571vector signed int vec_msum (vector signed char, 8572 vector unsigned char, 8573 vector signed int); 8574vector unsigned int vec_msum (vector unsigned short, 8575 vector unsigned short, 8576 vector unsigned int); 8577vector signed int vec_msum (vector signed short, 8578 vector signed short, 8579 vector signed int); 8580 8581vector signed int vec_vmsumshm (vector signed short, 8582 vector signed short, 8583 vector signed int); 8584 8585vector unsigned int vec_vmsumuhm (vector unsigned short, 8586 vector unsigned short, 8587 vector unsigned int); 8588 8589vector signed int vec_vmsummbm (vector signed char, 8590 vector unsigned char, 8591 vector signed int); 8592 8593vector unsigned int vec_vmsumubm (vector unsigned char, 8594 vector unsigned char, 8595 vector unsigned int); 8596 8597vector unsigned int vec_msums (vector unsigned short, 8598 vector unsigned short, 8599 vector unsigned int); 8600vector signed int vec_msums (vector signed short, 8601 vector signed short, 8602 vector signed int); 8603 8604vector signed int vec_vmsumshs (vector signed short, 8605 vector signed short, 8606 vector signed int); 8607 8608vector unsigned int vec_vmsumuhs (vector unsigned short, 8609 vector unsigned short, 8610 vector unsigned int); 8611 8612void vec_mtvscr (vector signed int); 8613void vec_mtvscr (vector unsigned int); 8614void vec_mtvscr (vector bool int); 8615void vec_mtvscr (vector signed short); 8616void vec_mtvscr (vector unsigned short); 8617void vec_mtvscr (vector bool short); 8618void vec_mtvscr (vector pixel); 8619void vec_mtvscr (vector signed char); 8620void vec_mtvscr (vector unsigned char); 8621void vec_mtvscr (vector bool char); 8622 8623vector unsigned short vec_mule (vector unsigned char, 8624 vector unsigned char); 8625vector signed short vec_mule (vector signed char, 8626 vector signed char); 8627vector unsigned int vec_mule (vector unsigned short, 8628 vector unsigned short); 8629vector signed int vec_mule (vector signed short, vector signed short); 8630 8631vector signed int vec_vmulesh (vector signed short, 8632 vector signed short); 8633 8634vector unsigned int vec_vmuleuh (vector unsigned short, 8635 vector unsigned short); 8636 8637vector signed short vec_vmulesb (vector signed char, 8638 vector signed char); 8639 8640vector unsigned short vec_vmuleub (vector unsigned char, 8641 vector unsigned char); 8642 8643vector unsigned short vec_mulo (vector unsigned char, 8644 vector unsigned char); 8645vector signed short vec_mulo (vector signed char, vector signed char); 8646vector unsigned int vec_mulo (vector unsigned short, 8647 vector unsigned short); 8648vector signed int vec_mulo (vector signed short, vector signed short); 8649 8650vector signed int vec_vmulosh (vector signed short, 8651 vector signed short); 8652 8653vector unsigned int vec_vmulouh (vector unsigned short, 8654 vector unsigned short); 8655 8656vector signed short vec_vmulosb (vector signed char, 8657 vector signed char); 8658 8659vector unsigned short vec_vmuloub (vector unsigned char, 8660 vector unsigned char); 8661 8662vector float vec_nmsub (vector float, vector float, vector float); 8663 8664vector float vec_nor (vector float, vector float); 8665vector signed int vec_nor (vector signed int, vector signed int); 8666vector unsigned int vec_nor (vector unsigned int, vector unsigned int); 8667vector bool int vec_nor (vector bool int, vector bool int); 8668vector signed short vec_nor (vector signed short, vector signed short); 8669vector unsigned short vec_nor (vector unsigned short, 8670 vector unsigned short); 8671vector bool short vec_nor (vector bool short, vector bool short); 8672vector signed char vec_nor (vector signed char, vector signed char); 8673vector unsigned char vec_nor (vector unsigned char, 8674 vector unsigned char); 8675vector bool char vec_nor (vector bool char, vector bool char); 8676 8677vector float vec_or (vector float, vector float); 8678vector float vec_or (vector float, vector bool int); 8679vector float vec_or (vector bool int, vector float); 8680vector bool int vec_or (vector bool int, vector bool int); 8681vector signed int vec_or (vector bool int, vector signed int); 8682vector signed int vec_or (vector signed int, vector bool int); 8683vector signed int vec_or (vector signed int, vector signed int); 8684vector unsigned int vec_or (vector bool int, vector unsigned int); 8685vector unsigned int vec_or (vector unsigned int, vector bool int); 8686vector unsigned int vec_or (vector unsigned int, vector unsigned int); 8687vector bool short vec_or (vector bool short, vector bool short); 8688vector signed short vec_or (vector bool short, vector signed short); 8689vector signed short vec_or (vector signed short, vector bool short); 8690vector signed short vec_or (vector signed short, vector signed short); 8691vector unsigned short vec_or (vector bool short, vector unsigned short); 8692vector unsigned short vec_or (vector unsigned short, vector bool short); 8693vector unsigned short vec_or (vector unsigned short, 8694 vector unsigned short); 8695vector signed char vec_or (vector bool char, vector signed char); 8696vector bool char vec_or (vector bool char, vector bool char); 8697vector signed char vec_or (vector signed char, vector bool char); 8698vector signed char vec_or (vector signed char, vector signed char); 8699vector unsigned char vec_or (vector bool char, vector unsigned char); 8700vector unsigned char vec_or (vector unsigned char, vector bool char); 8701vector unsigned char vec_or (vector unsigned char, 8702 vector unsigned char); 8703 8704vector signed char vec_pack (vector signed short, vector signed short); 8705vector unsigned char vec_pack (vector unsigned short, 8706 vector unsigned short); 8707vector bool char vec_pack (vector bool short, vector bool short); 8708vector signed short vec_pack (vector signed int, vector signed int); 8709vector unsigned short vec_pack (vector unsigned int, 8710 vector unsigned int); 8711vector bool short vec_pack (vector bool int, vector bool int); 8712 8713vector bool short vec_vpkuwum (vector bool int, vector bool int); 8714vector signed short vec_vpkuwum (vector signed int, vector signed int); 8715vector unsigned short vec_vpkuwum (vector unsigned int, 8716 vector unsigned int); 8717 8718vector bool char vec_vpkuhum (vector bool short, vector bool short); 8719vector signed char vec_vpkuhum (vector signed short, 8720 vector signed short); 8721vector unsigned char vec_vpkuhum (vector unsigned short, 8722 vector unsigned short); 8723 8724vector pixel vec_packpx (vector unsigned int, vector unsigned int); 8725 8726vector unsigned char vec_packs (vector unsigned short, 8727 vector unsigned short); 8728vector signed char vec_packs (vector signed short, vector signed short); 8729vector unsigned short vec_packs (vector unsigned int, 8730 vector unsigned int); 8731vector signed short vec_packs (vector signed int, vector signed int); 8732 8733vector signed short vec_vpkswss (vector signed int, vector signed int); 8734 8735vector unsigned short vec_vpkuwus (vector unsigned int, 8736 vector unsigned int); 8737 8738vector signed char vec_vpkshss (vector signed short, 8739 vector signed short); 8740 8741vector unsigned char vec_vpkuhus (vector unsigned short, 8742 vector unsigned short); 8743 8744vector unsigned char vec_packsu (vector unsigned short, 8745 vector unsigned short); 8746vector unsigned char vec_packsu (vector signed short, 8747 vector signed short); 8748vector unsigned short vec_packsu (vector unsigned int, 8749 vector unsigned int); 8750vector unsigned short vec_packsu (vector signed int, vector signed int); 8751 8752vector unsigned short vec_vpkswus (vector signed int, 8753 vector signed int); 8754 8755vector unsigned char vec_vpkshus (vector signed short, 8756 vector signed short); 8757 8758vector float vec_perm (vector float, 8759 vector float, 8760 vector unsigned char); 8761vector signed int vec_perm (vector signed int, 8762 vector signed int, 8763 vector unsigned char); 8764vector unsigned int vec_perm (vector unsigned int, 8765 vector unsigned int, 8766 vector unsigned char); 8767vector bool int vec_perm (vector bool int, 8768 vector bool int, 8769 vector unsigned char); 8770vector signed short vec_perm (vector signed short, 8771 vector signed short, 8772 vector unsigned char); 8773vector unsigned short vec_perm (vector unsigned short, 8774 vector unsigned short, 8775 vector unsigned char); 8776vector bool short vec_perm (vector bool short, 8777 vector bool short, 8778 vector unsigned char); 8779vector pixel vec_perm (vector pixel, 8780 vector pixel, 8781 vector unsigned char); 8782vector signed char vec_perm (vector signed char, 8783 vector signed char, 8784 vector unsigned char); 8785vector unsigned char vec_perm (vector unsigned char, 8786 vector unsigned char, 8787 vector unsigned char); 8788vector bool char vec_perm (vector bool char, 8789 vector bool char, 8790 vector unsigned char); 8791 8792vector float vec_re (vector float); 8793 8794vector signed char vec_rl (vector signed char, 8795 vector unsigned char); 8796vector unsigned char vec_rl (vector unsigned char, 8797 vector unsigned char); 8798vector signed short vec_rl (vector signed short, vector unsigned short); 8799vector unsigned short vec_rl (vector unsigned short, 8800 vector unsigned short); 8801vector signed int vec_rl (vector signed int, vector unsigned int); 8802vector unsigned int vec_rl (vector unsigned int, vector unsigned int); 8803 8804vector signed int vec_vrlw (vector signed int, vector unsigned int); 8805vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); 8806 8807vector signed short vec_vrlh (vector signed short, 8808 vector unsigned short); 8809vector unsigned short vec_vrlh (vector unsigned short, 8810 vector unsigned short); 8811 8812vector signed char vec_vrlb (vector signed char, vector unsigned char); 8813vector unsigned char vec_vrlb (vector unsigned char, 8814 vector unsigned char); 8815 8816vector float vec_round (vector float); 8817 8818vector float vec_rsqrte (vector float); 8819 8820vector float vec_sel (vector float, vector float, vector bool int); 8821vector float vec_sel (vector float, vector float, vector unsigned int); 8822vector signed int vec_sel (vector signed int, 8823 vector signed int, 8824 vector bool int); 8825vector signed int vec_sel (vector signed int, 8826 vector signed int, 8827 vector unsigned int); 8828vector unsigned int vec_sel (vector unsigned int, 8829 vector unsigned int, 8830 vector bool int); 8831vector unsigned int vec_sel (vector unsigned int, 8832 vector unsigned int, 8833 vector unsigned int); 8834vector bool int vec_sel (vector bool int, 8835 vector bool int, 8836 vector bool int); 8837vector bool int vec_sel (vector bool int, 8838 vector bool int, 8839 vector unsigned int); 8840vector signed short vec_sel (vector signed short, 8841 vector signed short, 8842 vector bool short); 8843vector signed short vec_sel (vector signed short, 8844 vector signed short, 8845 vector unsigned short); 8846vector unsigned short vec_sel (vector unsigned short, 8847 vector unsigned short, 8848 vector bool short); 8849vector unsigned short vec_sel (vector unsigned short, 8850 vector unsigned short, 8851 vector unsigned short); 8852vector bool short vec_sel (vector bool short, 8853 vector bool short, 8854 vector bool short); 8855vector bool short vec_sel (vector bool short, 8856 vector bool short, 8857 vector unsigned short); 8858vector signed char vec_sel (vector signed char, 8859 vector signed char, 8860 vector bool char); 8861vector signed char vec_sel (vector signed char, 8862 vector signed char, 8863 vector unsigned char); 8864vector unsigned char vec_sel (vector unsigned char, 8865 vector unsigned char, 8866 vector bool char); 8867vector unsigned char vec_sel (vector unsigned char, 8868 vector unsigned char, 8869 vector unsigned char); 8870vector bool char vec_sel (vector bool char, 8871 vector bool char, 8872 vector bool char); 8873vector bool char vec_sel (vector bool char, 8874 vector bool char, 8875 vector unsigned char); 8876 8877vector signed char vec_sl (vector signed char, 8878 vector unsigned char); 8879vector unsigned char vec_sl (vector unsigned char, 8880 vector unsigned char); 8881vector signed short vec_sl (vector signed short, vector unsigned short); 8882vector unsigned short vec_sl (vector unsigned short, 8883 vector unsigned short); 8884vector signed int vec_sl (vector signed int, vector unsigned int); 8885vector unsigned int vec_sl (vector unsigned int, vector unsigned int); 8886 8887vector signed int vec_vslw (vector signed int, vector unsigned int); 8888vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); 8889 8890vector signed short vec_vslh (vector signed short, 8891 vector unsigned short); 8892vector unsigned short vec_vslh (vector unsigned short, 8893 vector unsigned short); 8894 8895vector signed char vec_vslb (vector signed char, vector unsigned char); 8896vector unsigned char vec_vslb (vector unsigned char, 8897 vector unsigned char); 8898 8899vector float vec_sld (vector float, vector float, const int); 8900vector signed int vec_sld (vector signed int, 8901 vector signed int, 8902 const int); 8903vector unsigned int vec_sld (vector unsigned int, 8904 vector unsigned int, 8905 const int); 8906vector bool int vec_sld (vector bool int, 8907 vector bool int, 8908 const int); 8909vector signed short vec_sld (vector signed short, 8910 vector signed short, 8911 const int); 8912vector unsigned short vec_sld (vector unsigned short, 8913 vector unsigned short, 8914 const int); 8915vector bool short vec_sld (vector bool short, 8916 vector bool short, 8917 const int); 8918vector pixel vec_sld (vector pixel, 8919 vector pixel, 8920 const int); 8921vector signed char vec_sld (vector signed char, 8922 vector signed char, 8923 const int); 8924vector unsigned char vec_sld (vector unsigned char, 8925 vector unsigned char, 8926 const int); 8927vector bool char vec_sld (vector bool char, 8928 vector bool char, 8929 const int); 8930 8931vector signed int vec_sll (vector signed int, 8932 vector unsigned int); 8933vector signed int vec_sll (vector signed int, 8934 vector unsigned short); 8935vector signed int vec_sll (vector signed int, 8936 vector unsigned char); 8937vector unsigned int vec_sll (vector unsigned int, 8938 vector unsigned int); 8939vector unsigned int vec_sll (vector unsigned int, 8940 vector unsigned short); 8941vector unsigned int vec_sll (vector unsigned int, 8942 vector unsigned char); 8943vector bool int vec_sll (vector bool int, 8944 vector unsigned int); 8945vector bool int vec_sll (vector bool int, 8946 vector unsigned short); 8947vector bool int vec_sll (vector bool int, 8948 vector unsigned char); 8949vector signed short vec_sll (vector signed short, 8950 vector unsigned int); 8951vector signed short vec_sll (vector signed short, 8952 vector unsigned short); 8953vector signed short vec_sll (vector signed short, 8954 vector unsigned char); 8955vector unsigned short vec_sll (vector unsigned short, 8956 vector unsigned int); 8957vector unsigned short vec_sll (vector unsigned short, 8958 vector unsigned short); 8959vector unsigned short vec_sll (vector unsigned short, 8960 vector unsigned char); 8961vector bool short vec_sll (vector bool short, vector unsigned int); 8962vector bool short vec_sll (vector bool short, vector unsigned short); 8963vector bool short vec_sll (vector bool short, vector unsigned char); 8964vector pixel vec_sll (vector pixel, vector unsigned int); 8965vector pixel vec_sll (vector pixel, vector unsigned short); 8966vector pixel vec_sll (vector pixel, vector unsigned char); 8967vector signed char vec_sll (vector signed char, vector unsigned int); 8968vector signed char vec_sll (vector signed char, vector unsigned short); 8969vector signed char vec_sll (vector signed char, vector unsigned char); 8970vector unsigned char vec_sll (vector unsigned char, 8971 vector unsigned int); 8972vector unsigned char vec_sll (vector unsigned char, 8973 vector unsigned short); 8974vector unsigned char vec_sll (vector unsigned char, 8975 vector unsigned char); 8976vector bool char vec_sll (vector bool char, vector unsigned int); 8977vector bool char vec_sll (vector bool char, vector unsigned short); 8978vector bool char vec_sll (vector bool char, vector unsigned char); 8979 8980vector float vec_slo (vector float, vector signed char); 8981vector float vec_slo (vector float, vector unsigned char); 8982vector signed int vec_slo (vector signed int, vector signed char); 8983vector signed int vec_slo (vector signed int, vector unsigned char); 8984vector unsigned int vec_slo (vector unsigned int, vector signed char); 8985vector unsigned int vec_slo (vector unsigned int, vector unsigned char); 8986vector signed short vec_slo (vector signed short, vector signed char); 8987vector signed short vec_slo (vector signed short, vector unsigned char); 8988vector unsigned short vec_slo (vector unsigned short, 8989 vector signed char); 8990vector unsigned short vec_slo (vector unsigned short, 8991 vector unsigned char); 8992vector pixel vec_slo (vector pixel, vector signed char); 8993vector pixel vec_slo (vector pixel, vector unsigned char); 8994vector signed char vec_slo (vector signed char, vector signed char); 8995vector signed char vec_slo (vector signed char, vector unsigned char); 8996vector unsigned char vec_slo (vector unsigned char, vector signed char); 8997vector unsigned char vec_slo (vector unsigned char, 8998 vector unsigned char); 8999 9000vector signed char vec_splat (vector signed char, const int); 9001vector unsigned char vec_splat (vector unsigned char, const int); 9002vector bool char vec_splat (vector bool char, const int); 9003vector signed short vec_splat (vector signed short, const int); 9004vector unsigned short vec_splat (vector unsigned short, const int); 9005vector bool short vec_splat (vector bool short, const int); 9006vector pixel vec_splat (vector pixel, const int); 9007vector float vec_splat (vector float, const int); 9008vector signed int vec_splat (vector signed int, const int); 9009vector unsigned int vec_splat (vector unsigned int, const int); 9010vector bool int vec_splat (vector bool int, const int); 9011 9012vector float vec_vspltw (vector float, const int); 9013vector signed int vec_vspltw (vector signed int, const int); 9014vector unsigned int vec_vspltw (vector unsigned int, const int); 9015vector bool int vec_vspltw (vector bool int, const int); 9016 9017vector bool short vec_vsplth (vector bool short, const int); 9018vector signed short vec_vsplth (vector signed short, const int); 9019vector unsigned short vec_vsplth (vector unsigned short, const int); 9020vector pixel vec_vsplth (vector pixel, const int); 9021 9022vector signed char vec_vspltb (vector signed char, const int); 9023vector unsigned char vec_vspltb (vector unsigned char, const int); 9024vector bool char vec_vspltb (vector bool char, const int); 9025 9026vector signed char vec_splat_s8 (const int); 9027 9028vector signed short vec_splat_s16 (const int); 9029 9030vector signed int vec_splat_s32 (const int); 9031 9032vector unsigned char vec_splat_u8 (const int); 9033 9034vector unsigned short vec_splat_u16 (const int); 9035 9036vector unsigned int vec_splat_u32 (const int); 9037 9038vector signed char vec_sr (vector signed char, vector unsigned char); 9039vector unsigned char vec_sr (vector unsigned char, 9040 vector unsigned char); 9041vector signed short vec_sr (vector signed short, 9042 vector unsigned short); 9043vector unsigned short vec_sr (vector unsigned short, 9044 vector unsigned short); 9045vector signed int vec_sr (vector signed int, vector unsigned int); 9046vector unsigned int vec_sr (vector unsigned int, vector unsigned int); 9047 9048vector signed int vec_vsrw (vector signed int, vector unsigned int); 9049vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); 9050 9051vector signed short vec_vsrh (vector signed short, 9052 vector unsigned short); 9053vector unsigned short vec_vsrh (vector unsigned short, 9054 vector unsigned short); 9055 9056vector signed char vec_vsrb (vector signed char, vector unsigned char); 9057vector unsigned char vec_vsrb (vector unsigned char, 9058 vector unsigned char); 9059 9060vector signed char vec_sra (vector signed char, vector unsigned char); 9061vector unsigned char vec_sra (vector unsigned char, 9062 vector unsigned char); 9063vector signed short vec_sra (vector signed short, 9064 vector unsigned short); 9065vector unsigned short vec_sra (vector unsigned short, 9066 vector unsigned short); 9067vector signed int vec_sra (vector signed int, vector unsigned int); 9068vector unsigned int vec_sra (vector unsigned int, vector unsigned int); 9069 9070vector signed int vec_vsraw (vector signed int, vector unsigned int); 9071vector unsigned int vec_vsraw (vector unsigned int, 9072 vector unsigned int); 9073 9074vector signed short vec_vsrah (vector signed short, 9075 vector unsigned short); 9076vector unsigned short vec_vsrah (vector unsigned short, 9077 vector unsigned short); 9078 9079vector signed char vec_vsrab (vector signed char, vector unsigned char); 9080vector unsigned char vec_vsrab (vector unsigned char, 9081 vector unsigned char); 9082 9083vector signed int vec_srl (vector signed int, vector unsigned int); 9084vector signed int vec_srl (vector signed int, vector unsigned short); 9085vector signed int vec_srl (vector signed int, vector unsigned char); 9086vector unsigned int vec_srl (vector unsigned int, vector unsigned int); 9087vector unsigned int vec_srl (vector unsigned int, 9088 vector unsigned short); 9089vector unsigned int vec_srl (vector unsigned int, vector unsigned char); 9090vector bool int vec_srl (vector bool int, vector unsigned int); 9091vector bool int vec_srl (vector bool int, vector unsigned short); 9092vector bool int vec_srl (vector bool int, vector unsigned char); 9093vector signed short vec_srl (vector signed short, vector unsigned int); 9094vector signed short vec_srl (vector signed short, 9095 vector unsigned short); 9096vector signed short vec_srl (vector signed short, vector unsigned char); 9097vector unsigned short vec_srl (vector unsigned short, 9098 vector unsigned int); 9099vector unsigned short vec_srl (vector unsigned short, 9100 vector unsigned short); 9101vector unsigned short vec_srl (vector unsigned short, 9102 vector unsigned char); 9103vector bool short vec_srl (vector bool short, vector unsigned int); 9104vector bool short vec_srl (vector bool short, vector unsigned short); 9105vector bool short vec_srl (vector bool short, vector unsigned char); 9106vector pixel vec_srl (vector pixel, vector unsigned int); 9107vector pixel vec_srl (vector pixel, vector unsigned short); 9108vector pixel vec_srl (vector pixel, vector unsigned char); 9109vector signed char vec_srl (vector signed char, vector unsigned int); 9110vector signed char vec_srl (vector signed char, vector unsigned short); 9111vector signed char vec_srl (vector signed char, vector unsigned char); 9112vector unsigned char vec_srl (vector unsigned char, 9113 vector unsigned int); 9114vector unsigned char vec_srl (vector unsigned char, 9115 vector unsigned short); 9116vector unsigned char vec_srl (vector unsigned char, 9117 vector unsigned char); 9118vector bool char vec_srl (vector bool char, vector unsigned int); 9119vector bool char vec_srl (vector bool char, vector unsigned short); 9120vector bool char vec_srl (vector bool char, vector unsigned char); 9121 9122vector float vec_sro (vector float, vector signed char); 9123vector float vec_sro (vector float, vector unsigned char); 9124vector signed int vec_sro (vector signed int, vector signed char); 9125vector signed int vec_sro (vector signed int, vector unsigned char); 9126vector unsigned int vec_sro (vector unsigned int, vector signed char); 9127vector unsigned int vec_sro (vector unsigned int, vector unsigned char); 9128vector signed short vec_sro (vector signed short, vector signed char); 9129vector signed short vec_sro (vector signed short, vector unsigned char); 9130vector unsigned short vec_sro (vector unsigned short, 9131 vector signed char); 9132vector unsigned short vec_sro (vector unsigned short, 9133 vector unsigned char); 9134vector pixel vec_sro (vector pixel, vector signed char); 9135vector pixel vec_sro (vector pixel, vector unsigned char); 9136vector signed char vec_sro (vector signed char, vector signed char); 9137vector signed char vec_sro (vector signed char, vector unsigned char); 9138vector unsigned char vec_sro (vector unsigned char, vector signed char); 9139vector unsigned char vec_sro (vector unsigned char, 9140 vector unsigned char); 9141 9142void vec_st (vector float, int, vector float *); 9143void vec_st (vector float, int, float *); 9144void vec_st (vector signed int, int, vector signed int *); 9145void vec_st (vector signed int, int, int *); 9146void vec_st (vector unsigned int, int, vector unsigned int *); 9147void vec_st (vector unsigned int, int, unsigned int *); 9148void vec_st (vector bool int, int, vector bool int *); 9149void vec_st (vector bool int, int, unsigned int *); 9150void vec_st (vector bool int, int, int *); 9151void vec_st (vector signed short, int, vector signed short *); 9152void vec_st (vector signed short, int, short *); 9153void vec_st (vector unsigned short, int, vector unsigned short *); 9154void vec_st (vector unsigned short, int, unsigned short *); 9155void vec_st (vector bool short, int, vector bool short *); 9156void vec_st (vector bool short, int, unsigned short *); 9157void vec_st (vector pixel, int, vector pixel *); 9158void vec_st (vector pixel, int, unsigned short *); 9159void vec_st (vector pixel, int, short *); 9160void vec_st (vector bool short, int, short *); 9161void vec_st (vector signed char, int, vector signed char *); 9162void vec_st (vector signed char, int, signed char *); 9163void vec_st (vector unsigned char, int, vector unsigned char *); 9164void vec_st (vector unsigned char, int, unsigned char *); 9165void vec_st (vector bool char, int, vector bool char *); 9166void vec_st (vector bool char, int, unsigned char *); 9167void vec_st (vector bool char, int, signed char *); 9168 9169void vec_ste (vector signed char, int, signed char *); 9170void vec_ste (vector unsigned char, int, unsigned char *); 9171void vec_ste (vector bool char, int, signed char *); 9172void vec_ste (vector bool char, int, unsigned char *); 9173void vec_ste (vector signed short, int, short *); 9174void vec_ste (vector unsigned short, int, unsigned short *); 9175void vec_ste (vector bool short, int, short *); 9176void vec_ste (vector bool short, int, unsigned short *); 9177void vec_ste (vector pixel, int, short *); 9178void vec_ste (vector pixel, int, unsigned short *); 9179void vec_ste (vector float, int, float *); 9180void vec_ste (vector signed int, int, int *); 9181void vec_ste (vector unsigned int, int, unsigned int *); 9182void vec_ste (vector bool int, int, int *); 9183void vec_ste (vector bool int, int, unsigned int *); 9184 9185void vec_stvewx (vector float, int, float *); 9186void vec_stvewx (vector signed int, int, int *); 9187void vec_stvewx (vector unsigned int, int, unsigned int *); 9188void vec_stvewx (vector bool int, int, int *); 9189void vec_stvewx (vector bool int, int, unsigned int *); 9190 9191void vec_stvehx (vector signed short, int, short *); 9192void vec_stvehx (vector unsigned short, int, unsigned short *); 9193void vec_stvehx (vector bool short, int, short *); 9194void vec_stvehx (vector bool short, int, unsigned short *); 9195void vec_stvehx (vector pixel, int, short *); 9196void vec_stvehx (vector pixel, int, unsigned short *); 9197 9198void vec_stvebx (vector signed char, int, signed char *); 9199void vec_stvebx (vector unsigned char, int, unsigned char *); 9200void vec_stvebx (vector bool char, int, signed char *); 9201void vec_stvebx (vector bool char, int, unsigned char *); 9202 9203void vec_stl (vector float, int, vector float *); 9204void vec_stl (vector float, int, float *); 9205void vec_stl (vector signed int, int, vector signed int *); 9206void vec_stl (vector signed int, int, int *); 9207void vec_stl (vector unsigned int, int, vector unsigned int *); 9208void vec_stl (vector unsigned int, int, unsigned int *); 9209void vec_stl (vector bool int, int, vector bool int *); 9210void vec_stl (vector bool int, int, unsigned int *); 9211void vec_stl (vector bool int, int, int *); 9212void vec_stl (vector signed short, int, vector signed short *); 9213void vec_stl (vector signed short, int, short *); 9214void vec_stl (vector unsigned short, int, vector unsigned short *); 9215void vec_stl (vector unsigned short, int, unsigned short *); 9216void vec_stl (vector bool short, int, vector bool short *); 9217void vec_stl (vector bool short, int, unsigned short *); 9218void vec_stl (vector bool short, int, short *); 9219void vec_stl (vector pixel, int, vector pixel *); 9220void vec_stl (vector pixel, int, unsigned short *); 9221void vec_stl (vector pixel, int, short *); 9222void vec_stl (vector signed char, int, vector signed char *); 9223void vec_stl (vector signed char, int, signed char *); 9224void vec_stl (vector unsigned char, int, vector unsigned char *); 9225void vec_stl (vector unsigned char, int, unsigned char *); 9226void vec_stl (vector bool char, int, vector bool char *); 9227void vec_stl (vector bool char, int, unsigned char *); 9228void vec_stl (vector bool char, int, signed char *); 9229 9230vector signed char vec_sub (vector bool char, vector signed char); 9231vector signed char vec_sub (vector signed char, vector bool char); 9232vector signed char vec_sub (vector signed char, vector signed char); 9233vector unsigned char vec_sub (vector bool char, vector unsigned char); 9234vector unsigned char vec_sub (vector unsigned char, vector bool char); 9235vector unsigned char vec_sub (vector unsigned char, 9236 vector unsigned char); 9237vector signed short vec_sub (vector bool short, vector signed short); 9238vector signed short vec_sub (vector signed short, vector bool short); 9239vector signed short vec_sub (vector signed short, vector signed short); 9240vector unsigned short vec_sub (vector bool short, 9241 vector unsigned short); 9242vector unsigned short vec_sub (vector unsigned short, 9243 vector bool short); 9244vector unsigned short vec_sub (vector unsigned short, 9245 vector unsigned short); 9246vector signed int vec_sub (vector bool int, vector signed int); 9247vector signed int vec_sub (vector signed int, vector bool int); 9248vector signed int vec_sub (vector signed int, vector signed int); 9249vector unsigned int vec_sub (vector bool int, vector unsigned int); 9250vector unsigned int vec_sub (vector unsigned int, vector bool int); 9251vector unsigned int vec_sub (vector unsigned int, vector unsigned int); 9252vector float vec_sub (vector float, vector float); 9253 9254vector float vec_vsubfp (vector float, vector float); 9255 9256vector signed int vec_vsubuwm (vector bool int, vector signed int); 9257vector signed int vec_vsubuwm (vector signed int, vector bool int); 9258vector signed int vec_vsubuwm (vector signed int, vector signed int); 9259vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); 9260vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); 9261vector unsigned int vec_vsubuwm (vector unsigned int, 9262 vector unsigned int); 9263 9264vector signed short vec_vsubuhm (vector bool short, 9265 vector signed short); 9266vector signed short vec_vsubuhm (vector signed short, 9267 vector bool short); 9268vector signed short vec_vsubuhm (vector signed short, 9269 vector signed short); 9270vector unsigned short vec_vsubuhm (vector bool short, 9271 vector unsigned short); 9272vector unsigned short vec_vsubuhm (vector unsigned short, 9273 vector bool short); 9274vector unsigned short vec_vsubuhm (vector unsigned short, 9275 vector unsigned short); 9276 9277vector signed char vec_vsububm (vector bool char, vector signed char); 9278vector signed char vec_vsububm (vector signed char, vector bool char); 9279vector signed char vec_vsububm (vector signed char, vector signed char); 9280vector unsigned char vec_vsububm (vector bool char, 9281 vector unsigned char); 9282vector unsigned char vec_vsububm (vector unsigned char, 9283 vector bool char); 9284vector unsigned char vec_vsububm (vector unsigned char, 9285 vector unsigned char); 9286 9287vector unsigned int vec_subc (vector unsigned int, vector unsigned int); 9288 9289vector unsigned char vec_subs (vector bool char, vector unsigned char); 9290vector unsigned char vec_subs (vector unsigned char, vector bool char); 9291vector unsigned char vec_subs (vector unsigned char, 9292 vector unsigned char); 9293vector signed char vec_subs (vector bool char, vector signed char); 9294vector signed char vec_subs (vector signed char, vector bool char); 9295vector signed char vec_subs (vector signed char, vector signed char); 9296vector unsigned short vec_subs (vector bool short, 9297 vector unsigned short); 9298vector unsigned short vec_subs (vector unsigned short, 9299 vector bool short); 9300vector unsigned short vec_subs (vector unsigned short, 9301 vector unsigned short); 9302vector signed short vec_subs (vector bool short, vector signed short); 9303vector signed short vec_subs (vector signed short, vector bool short); 9304vector signed short vec_subs (vector signed short, vector signed short); 9305vector unsigned int vec_subs (vector bool int, vector unsigned int); 9306vector unsigned int vec_subs (vector unsigned int, vector bool int); 9307vector unsigned int vec_subs (vector unsigned int, vector unsigned int); 9308vector signed int vec_subs (vector bool int, vector signed int); 9309vector signed int vec_subs (vector signed int, vector bool int); 9310vector signed int vec_subs (vector signed int, vector signed int); 9311 9312vector signed int vec_vsubsws (vector bool int, vector signed int); 9313vector signed int vec_vsubsws (vector signed int, vector bool int); 9314vector signed int vec_vsubsws (vector signed int, vector signed int); 9315 9316vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); 9317vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); 9318vector unsigned int vec_vsubuws (vector unsigned int, 9319 vector unsigned int); 9320 9321vector signed short vec_vsubshs (vector bool short, 9322 vector signed short); 9323vector signed short vec_vsubshs (vector signed short, 9324 vector bool short); 9325vector signed short vec_vsubshs (vector signed short, 9326 vector signed short); 9327 9328vector unsigned short vec_vsubuhs (vector bool short, 9329 vector unsigned short); 9330vector unsigned short vec_vsubuhs (vector unsigned short, 9331 vector bool short); 9332vector unsigned short vec_vsubuhs (vector unsigned short, 9333 vector unsigned short); 9334 9335vector signed char vec_vsubsbs (vector bool char, vector signed char); 9336vector signed char vec_vsubsbs (vector signed char, vector bool char); 9337vector signed char vec_vsubsbs (vector signed char, vector signed char); 9338 9339vector unsigned char vec_vsububs (vector bool char, 9340 vector unsigned char); 9341vector unsigned char vec_vsububs (vector unsigned char, 9342 vector bool char); 9343vector unsigned char vec_vsububs (vector unsigned char, 9344 vector unsigned char); 9345 9346vector unsigned int vec_sum4s (vector unsigned char, 9347 vector unsigned int); 9348vector signed int vec_sum4s (vector signed char, vector signed int); 9349vector signed int vec_sum4s (vector signed short, vector signed int); 9350 9351vector signed int vec_vsum4shs (vector signed short, vector signed int); 9352 9353vector signed int vec_vsum4sbs (vector signed char, vector signed int); 9354 9355vector unsigned int vec_vsum4ubs (vector unsigned char, 9356 vector unsigned int); 9357 9358vector signed int vec_sum2s (vector signed int, vector signed int); 9359 9360vector signed int vec_sums (vector signed int, vector signed int); 9361 9362vector float vec_trunc (vector float); 9363 9364vector signed short vec_unpackh (vector signed char); 9365vector bool short vec_unpackh (vector bool char); 9366vector signed int vec_unpackh (vector signed short); 9367vector bool int vec_unpackh (vector bool short); 9368vector unsigned int vec_unpackh (vector pixel); 9369 9370vector bool int vec_vupkhsh (vector bool short); 9371vector signed int vec_vupkhsh (vector signed short); 9372 9373vector unsigned int vec_vupkhpx (vector pixel); 9374 9375vector bool short vec_vupkhsb (vector bool char); 9376vector signed short vec_vupkhsb (vector signed char); 9377 9378vector signed short vec_unpackl (vector signed char); 9379vector bool short vec_unpackl (vector bool char); 9380vector unsigned int vec_unpackl (vector pixel); 9381vector signed int vec_unpackl (vector signed short); 9382vector bool int vec_unpackl (vector bool short); 9383 9384vector unsigned int vec_vupklpx (vector pixel); 9385 9386vector bool int vec_vupklsh (vector bool short); 9387vector signed int vec_vupklsh (vector signed short); 9388 9389vector bool short vec_vupklsb (vector bool char); 9390vector signed short vec_vupklsb (vector signed char); 9391 9392vector float vec_xor (vector float, vector float); 9393vector float vec_xor (vector float, vector bool int); 9394vector float vec_xor (vector bool int, vector float); 9395vector bool int vec_xor (vector bool int, vector bool int); 9396vector signed int vec_xor (vector bool int, vector signed int); 9397vector signed int vec_xor (vector signed int, vector bool int); 9398vector signed int vec_xor (vector signed int, vector signed int); 9399vector unsigned int vec_xor (vector bool int, vector unsigned int); 9400vector unsigned int vec_xor (vector unsigned int, vector bool int); 9401vector unsigned int vec_xor (vector unsigned int, vector unsigned int); 9402vector bool short vec_xor (vector bool short, vector bool short); 9403vector signed short vec_xor (vector bool short, vector signed short); 9404vector signed short vec_xor (vector signed short, vector bool short); 9405vector signed short vec_xor (vector signed short, vector signed short); 9406vector unsigned short vec_xor (vector bool short, 9407 vector unsigned short); 9408vector unsigned short vec_xor (vector unsigned short, 9409 vector bool short); 9410vector unsigned short vec_xor (vector unsigned short, 9411 vector unsigned short); 9412vector signed char vec_xor (vector bool char, vector signed char); 9413vector bool char vec_xor (vector bool char, vector bool char); 9414vector signed char vec_xor (vector signed char, vector bool char); 9415vector signed char vec_xor (vector signed char, vector signed char); 9416vector unsigned char vec_xor (vector bool char, vector unsigned char); 9417vector unsigned char vec_xor (vector unsigned char, vector bool char); 9418vector unsigned char vec_xor (vector unsigned char, 9419 vector unsigned char); 9420 9421int vec_all_eq (vector signed char, vector bool char); 9422int vec_all_eq (vector signed char, vector signed char); 9423int vec_all_eq (vector unsigned char, vector bool char); 9424int vec_all_eq (vector unsigned char, vector unsigned char); 9425int vec_all_eq (vector bool char, vector bool char); 9426int vec_all_eq (vector bool char, vector unsigned char); 9427int vec_all_eq (vector bool char, vector signed char); 9428int vec_all_eq (vector signed short, vector bool short); 9429int vec_all_eq (vector signed short, vector signed short); 9430int vec_all_eq (vector unsigned short, vector bool short); 9431int vec_all_eq (vector unsigned short, vector unsigned short); 9432int vec_all_eq (vector bool short, vector bool short); 9433int vec_all_eq (vector bool short, vector unsigned short); 9434int vec_all_eq (vector bool short, vector signed short); 9435int vec_all_eq (vector pixel, vector pixel); 9436int vec_all_eq (vector signed int, vector bool int); 9437int vec_all_eq (vector signed int, vector signed int); 9438int vec_all_eq (vector unsigned int, vector bool int); 9439int vec_all_eq (vector unsigned int, vector unsigned int); 9440int vec_all_eq (vector bool int, vector bool int); 9441int vec_all_eq (vector bool int, vector unsigned int); 9442int vec_all_eq (vector bool int, vector signed int); 9443int vec_all_eq (vector float, vector float); 9444 9445int vec_all_ge (vector bool char, vector unsigned char); 9446int vec_all_ge (vector unsigned char, vector bool char); 9447int vec_all_ge (vector unsigned char, vector unsigned char); 9448int vec_all_ge (vector bool char, vector signed char); 9449int vec_all_ge (vector signed char, vector bool char); 9450int vec_all_ge (vector signed char, vector signed char); 9451int vec_all_ge (vector bool short, vector unsigned short); 9452int vec_all_ge (vector unsigned short, vector bool short); 9453int vec_all_ge (vector unsigned short, vector unsigned short); 9454int vec_all_ge (vector signed short, vector signed short); 9455int vec_all_ge (vector bool short, vector signed short); 9456int vec_all_ge (vector signed short, vector bool short); 9457int vec_all_ge (vector bool int, vector unsigned int); 9458int vec_all_ge (vector unsigned int, vector bool int); 9459int vec_all_ge (vector unsigned int, vector unsigned int); 9460int vec_all_ge (vector bool int, vector signed int); 9461int vec_all_ge (vector signed int, vector bool int); 9462int vec_all_ge (vector signed int, vector signed int); 9463int vec_all_ge (vector float, vector float); 9464 9465int vec_all_gt (vector bool char, vector unsigned char); 9466int vec_all_gt (vector unsigned char, vector bool char); 9467int vec_all_gt (vector unsigned char, vector unsigned char); 9468int vec_all_gt (vector bool char, vector signed char); 9469int vec_all_gt (vector signed char, vector bool char); 9470int vec_all_gt (vector signed char, vector signed char); 9471int vec_all_gt (vector bool short, vector unsigned short); 9472int vec_all_gt (vector unsigned short, vector bool short); 9473int vec_all_gt (vector unsigned short, vector unsigned short); 9474int vec_all_gt (vector bool short, vector signed short); 9475int vec_all_gt (vector signed short, vector bool short); 9476int vec_all_gt (vector signed short, vector signed short); 9477int vec_all_gt (vector bool int, vector unsigned int); 9478int vec_all_gt (vector unsigned int, vector bool int); 9479int vec_all_gt (vector unsigned int, vector unsigned int); 9480int vec_all_gt (vector bool int, vector signed int); 9481int vec_all_gt (vector signed int, vector bool int); 9482int vec_all_gt (vector signed int, vector signed int); 9483int vec_all_gt (vector float, vector float); 9484 9485int vec_all_in (vector float, vector float); 9486 9487int vec_all_le (vector bool char, vector unsigned char); 9488int vec_all_le (vector unsigned char, vector bool char); 9489int vec_all_le (vector unsigned char, vector unsigned char); 9490int vec_all_le (vector bool char, vector signed char); 9491int vec_all_le (vector signed char, vector bool char); 9492int vec_all_le (vector signed char, vector signed char); 9493int vec_all_le (vector bool short, vector unsigned short); 9494int vec_all_le (vector unsigned short, vector bool short); 9495int vec_all_le (vector unsigned short, vector unsigned short); 9496int vec_all_le (vector bool short, vector signed short); 9497int vec_all_le (vector signed short, vector bool short); 9498int vec_all_le (vector signed short, vector signed short); 9499int vec_all_le (vector bool int, vector unsigned int); 9500int vec_all_le (vector unsigned int, vector bool int); 9501int vec_all_le (vector unsigned int, vector unsigned int); 9502int vec_all_le (vector bool int, vector signed int); 9503int vec_all_le (vector signed int, vector bool int); 9504int vec_all_le (vector signed int, vector signed int); 9505int vec_all_le (vector float, vector float); 9506 9507int vec_all_lt (vector bool char, vector unsigned char); 9508int vec_all_lt (vector unsigned char, vector bool char); 9509int vec_all_lt (vector unsigned char, vector unsigned char); 9510int vec_all_lt (vector bool char, vector signed char); 9511int vec_all_lt (vector signed char, vector bool char); 9512int vec_all_lt (vector signed char, vector signed char); 9513int vec_all_lt (vector bool short, vector unsigned short); 9514int vec_all_lt (vector unsigned short, vector bool short); 9515int vec_all_lt (vector unsigned short, vector unsigned short); 9516int vec_all_lt (vector bool short, vector signed short); 9517int vec_all_lt (vector signed short, vector bool short); 9518int vec_all_lt (vector signed short, vector signed short); 9519int vec_all_lt (vector bool int, vector unsigned int); 9520int vec_all_lt (vector unsigned int, vector bool int); 9521int vec_all_lt (vector unsigned int, vector unsigned int); 9522int vec_all_lt (vector bool int, vector signed int); 9523int vec_all_lt (vector signed int, vector bool int); 9524int vec_all_lt (vector signed int, vector signed int); 9525int vec_all_lt (vector float, vector float); 9526 9527int vec_all_nan (vector float); 9528 9529int vec_all_ne (vector signed char, vector bool char); 9530int vec_all_ne (vector signed char, vector signed char); 9531int vec_all_ne (vector unsigned char, vector bool char); 9532int vec_all_ne (vector unsigned char, vector unsigned char); 9533int vec_all_ne (vector bool char, vector bool char); 9534int vec_all_ne (vector bool char, vector unsigned char); 9535int vec_all_ne (vector bool char, vector signed char); 9536int vec_all_ne (vector signed short, vector bool short); 9537int vec_all_ne (vector signed short, vector signed short); 9538int vec_all_ne (vector unsigned short, vector bool short); 9539int vec_all_ne (vector unsigned short, vector unsigned short); 9540int vec_all_ne (vector bool short, vector bool short); 9541int vec_all_ne (vector bool short, vector unsigned short); 9542int vec_all_ne (vector bool short, vector signed short); 9543int vec_all_ne (vector pixel, vector pixel); 9544int vec_all_ne (vector signed int, vector bool int); 9545int vec_all_ne (vector signed int, vector signed int); 9546int vec_all_ne (vector unsigned int, vector bool int); 9547int vec_all_ne (vector unsigned int, vector unsigned int); 9548int vec_all_ne (vector bool int, vector bool int); 9549int vec_all_ne (vector bool int, vector unsigned int); 9550int vec_all_ne (vector bool int, vector signed int); 9551int vec_all_ne (vector float, vector float); 9552 9553int vec_all_nge (vector float, vector float); 9554 9555int vec_all_ngt (vector float, vector float); 9556 9557int vec_all_nle (vector float, vector float); 9558 9559int vec_all_nlt (vector float, vector float); 9560 9561int vec_all_numeric (vector float); 9562 9563int vec_any_eq (vector signed char, vector bool char); 9564int vec_any_eq (vector signed char, vector signed char); 9565int vec_any_eq (vector unsigned char, vector bool char); 9566int vec_any_eq (vector unsigned char, vector unsigned char); 9567int vec_any_eq (vector bool char, vector bool char); 9568int vec_any_eq (vector bool char, vector unsigned char); 9569int vec_any_eq (vector bool char, vector signed char); 9570int vec_any_eq (vector signed short, vector bool short); 9571int vec_any_eq (vector signed short, vector signed short); 9572int vec_any_eq (vector unsigned short, vector bool short); 9573int vec_any_eq (vector unsigned short, vector unsigned short); 9574int vec_any_eq (vector bool short, vector bool short); 9575int vec_any_eq (vector bool short, vector unsigned short); 9576int vec_any_eq (vector bool short, vector signed short); 9577int vec_any_eq (vector pixel, vector pixel); 9578int vec_any_eq (vector signed int, vector bool int); 9579int vec_any_eq (vector signed int, vector signed int); 9580int vec_any_eq (vector unsigned int, vector bool int); 9581int vec_any_eq (vector unsigned int, vector unsigned int); 9582int vec_any_eq (vector bool int, vector bool int); 9583int vec_any_eq (vector bool int, vector unsigned int); 9584int vec_any_eq (vector bool int, vector signed int); 9585int vec_any_eq (vector float, vector float); 9586 9587int vec_any_ge (vector signed char, vector bool char); 9588int vec_any_ge (vector unsigned char, vector bool char); 9589int vec_any_ge (vector unsigned char, vector unsigned char); 9590int vec_any_ge (vector signed char, vector signed char); 9591int vec_any_ge (vector bool char, vector unsigned char); 9592int vec_any_ge (vector bool char, vector signed char); 9593int vec_any_ge (vector unsigned short, vector bool short); 9594int vec_any_ge (vector unsigned short, vector unsigned short); 9595int vec_any_ge (vector signed short, vector signed short); 9596int vec_any_ge (vector signed short, vector bool short); 9597int vec_any_ge (vector bool short, vector unsigned short); 9598int vec_any_ge (vector bool short, vector signed short); 9599int vec_any_ge (vector signed int, vector bool int); 9600int vec_any_ge (vector unsigned int, vector bool int); 9601int vec_any_ge (vector unsigned int, vector unsigned int); 9602int vec_any_ge (vector signed int, vector signed int); 9603int vec_any_ge (vector bool int, vector unsigned int); 9604int vec_any_ge (vector bool int, vector signed int); 9605int vec_any_ge (vector float, vector float); 9606 9607int vec_any_gt (vector bool char, vector unsigned char); 9608int vec_any_gt (vector unsigned char, vector bool char); 9609int vec_any_gt (vector unsigned char, vector unsigned char); 9610int vec_any_gt (vector bool char, vector signed char); 9611int vec_any_gt (vector signed char, vector bool char); 9612int vec_any_gt (vector signed char, vector signed char); 9613int vec_any_gt (vector bool short, vector unsigned short); 9614int vec_any_gt (vector unsigned short, vector bool short); 9615int vec_any_gt (vector unsigned short, vector unsigned short); 9616int vec_any_gt (vector bool short, vector signed short); 9617int vec_any_gt (vector signed short, vector bool short); 9618int vec_any_gt (vector signed short, vector signed short); 9619int vec_any_gt (vector bool int, vector unsigned int); 9620int vec_any_gt (vector unsigned int, vector bool int); 9621int vec_any_gt (vector unsigned int, vector unsigned int); 9622int vec_any_gt (vector bool int, vector signed int); 9623int vec_any_gt (vector signed int, vector bool int); 9624int vec_any_gt (vector signed int, vector signed int); 9625int vec_any_gt (vector float, vector float); 9626 9627int vec_any_le (vector bool char, vector unsigned char); 9628int vec_any_le (vector unsigned char, vector bool char); 9629int vec_any_le (vector unsigned char, vector unsigned char); 9630int vec_any_le (vector bool char, vector signed char); 9631int vec_any_le (vector signed char, vector bool char); 9632int vec_any_le (vector signed char, vector signed char); 9633int vec_any_le (vector bool short, vector unsigned short); 9634int vec_any_le (vector unsigned short, vector bool short); 9635int vec_any_le (vector unsigned short, vector unsigned short); 9636int vec_any_le (vector bool short, vector signed short); 9637int vec_any_le (vector signed short, vector bool short); 9638int vec_any_le (vector signed short, vector signed short); 9639int vec_any_le (vector bool int, vector unsigned int); 9640int vec_any_le (vector unsigned int, vector bool int); 9641int vec_any_le (vector unsigned int, vector unsigned int); 9642int vec_any_le (vector bool int, vector signed int); 9643int vec_any_le (vector signed int, vector bool int); 9644int vec_any_le (vector signed int, vector signed int); 9645int vec_any_le (vector float, vector float); 9646 9647int vec_any_lt (vector bool char, vector unsigned char); 9648int vec_any_lt (vector unsigned char, vector bool char); 9649int vec_any_lt (vector unsigned char, vector unsigned char); 9650int vec_any_lt (vector bool char, vector signed char); 9651int vec_any_lt (vector signed char, vector bool char); 9652int vec_any_lt (vector signed char, vector signed char); 9653int vec_any_lt (vector bool short, vector unsigned short); 9654int vec_any_lt (vector unsigned short, vector bool short); 9655int vec_any_lt (vector unsigned short, vector unsigned short); 9656int vec_any_lt (vector bool short, vector signed short); 9657int vec_any_lt (vector signed short, vector bool short); 9658int vec_any_lt (vector signed short, vector signed short); 9659int vec_any_lt (vector bool int, vector unsigned int); 9660int vec_any_lt (vector unsigned int, vector bool int); 9661int vec_any_lt (vector unsigned int, vector unsigned int); 9662int vec_any_lt (vector bool int, vector signed int); 9663int vec_any_lt (vector signed int, vector bool int); 9664int vec_any_lt (vector signed int, vector signed int); 9665int vec_any_lt (vector float, vector float); 9666 9667int vec_any_nan (vector float); 9668 9669int vec_any_ne (vector signed char, vector bool char); 9670int vec_any_ne (vector signed char, vector signed char); 9671int vec_any_ne (vector unsigned char, vector bool char); 9672int vec_any_ne (vector unsigned char, vector unsigned char); 9673int vec_any_ne (vector bool char, vector bool char); 9674int vec_any_ne (vector bool char, vector unsigned char); 9675int vec_any_ne (vector bool char, vector signed char); 9676int vec_any_ne (vector signed short, vector bool short); 9677int vec_any_ne (vector signed short, vector signed short); 9678int vec_any_ne (vector unsigned short, vector bool short); 9679int vec_any_ne (vector unsigned short, vector unsigned short); 9680int vec_any_ne (vector bool short, vector bool short); 9681int vec_any_ne (vector bool short, vector unsigned short); 9682int vec_any_ne (vector bool short, vector signed short); 9683int vec_any_ne (vector pixel, vector pixel); 9684int vec_any_ne (vector signed int, vector bool int); 9685int vec_any_ne (vector signed int, vector signed int); 9686int vec_any_ne (vector unsigned int, vector bool int); 9687int vec_any_ne (vector unsigned int, vector unsigned int); 9688int vec_any_ne (vector bool int, vector bool int); 9689int vec_any_ne (vector bool int, vector unsigned int); 9690int vec_any_ne (vector bool int, vector signed int); 9691int vec_any_ne (vector float, vector float); 9692 9693int vec_any_nge (vector float, vector float); 9694 9695int vec_any_ngt (vector float, vector float); 9696 9697int vec_any_nle (vector float, vector float); 9698 9699int vec_any_nlt (vector float, vector float); 9700 9701int vec_any_numeric (vector float); 9702 9703int vec_any_out (vector float, vector float); 9704@end smallexample 9705 9706@node SPARC VIS Built-in Functions 9707@subsection SPARC VIS Built-in Functions 9708 9709GCC supports SIMD operations on the SPARC using both the generic vector 9710extensions (@pxref{Vector Extensions}) as well as built-in functions for 9711the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} 9712switch, the VIS extension is exposed as the following built-in functions: 9713 9714@smallexample 9715typedef int v2si __attribute__ ((vector_size (8))); 9716typedef short v4hi __attribute__ ((vector_size (8))); 9717typedef short v2hi __attribute__ ((vector_size (4))); 9718typedef char v8qi __attribute__ ((vector_size (8))); 9719typedef char v4qi __attribute__ ((vector_size (4))); 9720 9721void * __builtin_vis_alignaddr (void *, long); 9722int64_t __builtin_vis_faligndatadi (int64_t, int64_t); 9723v2si __builtin_vis_faligndatav2si (v2si, v2si); 9724v4hi __builtin_vis_faligndatav4hi (v4si, v4si); 9725v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); 9726 9727v4hi __builtin_vis_fexpand (v4qi); 9728 9729v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); 9730v4hi __builtin_vis_fmul8x16au (v4qi, v4hi); 9731v4hi __builtin_vis_fmul8x16al (v4qi, v4hi); 9732v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); 9733v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); 9734v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); 9735v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); 9736 9737v4qi __builtin_vis_fpack16 (v4hi); 9738v8qi __builtin_vis_fpack32 (v2si, v2si); 9739v2hi __builtin_vis_fpackfix (v2si); 9740v8qi __builtin_vis_fpmerge (v4qi, v4qi); 9741 9742int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); 9743@end smallexample 9744 9745@node Target Format Checks 9746@section Format Checks Specific to Particular Target Machines 9747 9748For some target machines, GCC supports additional options to the 9749format attribute 9750(@pxref{Function Attributes,,Declaring Attributes of Functions}). 9751 9752@menu 9753* Solaris Format Checks:: 9754@end menu 9755 9756@node Solaris Format Checks 9757@subsection Solaris Format Checks 9758 9759Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format 9760check. @code{cmn_err} accepts a subset of the standard @code{printf} 9761conversions, and the two-argument @code{%b} conversion for displaying 9762bit-fields. See the Solaris man page for @code{cmn_err} for more information. 9763 9764@node Pragmas 9765@section Pragmas Accepted by GCC 9766@cindex pragmas 9767@cindex #pragma 9768 9769GCC supports several types of pragmas, primarily in order to compile 9770code originally written for other compilers. Note that in general 9771we do not recommend the use of pragmas; @xref{Function Attributes}, 9772for further explanation. 9773 9774@menu 9775* ARM Pragmas:: 9776* M32C Pragmas:: 9777* RS/6000 and PowerPC Pragmas:: 9778* Darwin Pragmas:: 9779* Solaris Pragmas:: 9780* Symbol-Renaming Pragmas:: 9781* Structure-Packing Pragmas:: 9782* Weak Pragmas:: 9783* Diagnostic Pragmas:: 9784* Visibility Pragmas:: 9785@end menu 9786 9787@node ARM Pragmas 9788@subsection ARM Pragmas 9789 9790The ARM target defines pragmas for controlling the default addition of 9791@code{long_call} and @code{short_call} attributes to functions. 9792@xref{Function Attributes}, for information about the effects of these 9793attributes. 9794 9795@table @code 9796@item long_calls 9797@cindex pragma, long_calls 9798Set all subsequent functions to have the @code{long_call} attribute. 9799 9800@item no_long_calls 9801@cindex pragma, no_long_calls 9802Set all subsequent functions to have the @code{short_call} attribute. 9803 9804@item long_calls_off 9805@cindex pragma, long_calls_off 9806Do not affect the @code{long_call} or @code{short_call} attributes of 9807subsequent functions. 9808@end table 9809 9810@node M32C Pragmas 9811@subsection M32C Pragmas 9812 9813@table @code 9814@item memregs @var{number} 9815@cindex pragma, memregs 9816Overrides the command line option @code{-memregs=} for the current 9817file. Use with care! This pragma must be before any function in the 9818file, and mixing different memregs values in different objects may 9819make them incompatible. This pragma is useful when a 9820performance-critical function uses a memreg for temporary values, 9821as it may allow you to reduce the number of memregs used. 9822 9823@end table 9824 9825@node RS/6000 and PowerPC Pragmas 9826@subsection RS/6000 and PowerPC Pragmas 9827 9828The RS/6000 and PowerPC targets define one pragma for controlling 9829whether or not the @code{longcall} attribute is added to function 9830declarations by default. This pragma overrides the @option{-mlongcall} 9831option, but not the @code{longcall} and @code{shortcall} attributes. 9832@xref{RS/6000 and PowerPC Options}, for more information about when long 9833calls are and are not necessary. 9834 9835@table @code 9836@item longcall (1) 9837@cindex pragma, longcall 9838Apply the @code{longcall} attribute to all subsequent function 9839declarations. 9840 9841@item longcall (0) 9842Do not apply the @code{longcall} attribute to subsequent function 9843declarations. 9844@end table 9845 9846@c Describe c4x pragmas here. 9847@c Describe h8300 pragmas here. 9848@c Describe sh pragmas here. 9849@c Describe v850 pragmas here. 9850 9851@node Darwin Pragmas 9852@subsection Darwin Pragmas 9853 9854The following pragmas are available for all architectures running the 9855Darwin operating system. These are useful for compatibility with other 9856Mac OS compilers. 9857 9858@table @code 9859@item mark @var{tokens}@dots{} 9860@cindex pragma, mark 9861This pragma is accepted, but has no effect. 9862 9863@item options align=@var{alignment} 9864@cindex pragma, options align 9865This pragma sets the alignment of fields in structures. The values of 9866@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or 9867@code{power}, to emulate PowerPC alignment. Uses of this pragma nest 9868properly; to restore the previous setting, use @code{reset} for the 9869@var{alignment}. 9870 9871@item segment @var{tokens}@dots{} 9872@cindex pragma, segment 9873This pragma is accepted, but has no effect. 9874 9875@item unused (@var{var} [, @var{var}]@dots{}) 9876@cindex pragma, unused 9877This pragma declares variables to be possibly unused. GCC will not 9878produce warnings for the listed variables. The effect is similar to 9879that of the @code{unused} attribute, except that this pragma may appear 9880anywhere within the variables' scopes. 9881@end table 9882 9883@node Solaris Pragmas 9884@subsection Solaris Pragmas 9885 9886The Solaris target supports @code{#pragma redefine_extname} 9887(@pxref{Symbol-Renaming Pragmas}). It also supports additional 9888@code{#pragma} directives for compatibility with the system compiler. 9889 9890@table @code 9891@item align @var{alignment} (@var{variable} [, @var{variable}]...) 9892@cindex pragma, align 9893 9894Increase the minimum alignment of each @var{variable} to @var{alignment}. 9895This is the same as GCC's @code{aligned} attribute @pxref{Variable 9896Attributes}). Macro expansion occurs on the arguments to this pragma 9897when compiling C. It does not currently occur when compiling C++, but 9898this is a bug which may be fixed in a future release. 9899 9900@item fini (@var{function} [, @var{function}]...) 9901@cindex pragma, fini 9902 9903This pragma causes each listed @var{function} to be called after 9904main, or during shared module unloading, by adding a call to the 9905@code{.fini} section. 9906 9907@item init (@var{function} [, @var{function}]...) 9908@cindex pragma, init 9909 9910This pragma causes each listed @var{function} to be called during 9911initialization (before @code{main}) or during shared module loading, by 9912adding a call to the @code{.init} section. 9913 9914@end table 9915 9916@node Symbol-Renaming Pragmas 9917@subsection Symbol-Renaming Pragmas 9918 9919For compatibility with the Solaris and Tru64 UNIX system headers, GCC 9920supports two @code{#pragma} directives which change the name used in 9921assembly for a given declaration. These pragmas are only available on 9922platforms whose system headers need them. To get this effect on all 9923platforms supported by GCC, use the asm labels extension (@pxref{Asm 9924Labels}). 9925 9926@table @code 9927@item redefine_extname @var{oldname} @var{newname} 9928@cindex pragma, redefine_extname 9929 9930This pragma gives the C function @var{oldname} the assembly symbol 9931@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} 9932will be defined if this pragma is available (currently only on 9933Solaris). 9934 9935@item extern_prefix @var{string} 9936@cindex pragma, extern_prefix 9937 9938This pragma causes all subsequent external function and variable 9939declarations to have @var{string} prepended to their assembly symbols. 9940This effect may be terminated with another @code{extern_prefix} pragma 9941whose argument is an empty string. The preprocessor macro 9942@code{__PRAGMA_EXTERN_PREFIX} will be defined if this pragma is 9943available (currently only on Tru64 UNIX)@. 9944@end table 9945 9946These pragmas and the asm labels extension interact in a complicated 9947manner. Here are some corner cases you may want to be aware of. 9948 9949@enumerate 9950@item Both pragmas silently apply only to declarations with external 9951linkage. Asm labels do not have this restriction. 9952 9953@item In C++, both pragmas silently apply only to declarations with 9954``C'' linkage. Again, asm labels do not have this restriction. 9955 9956@item If any of the three ways of changing the assembly name of a 9957declaration is applied to a declaration whose assembly name has 9958already been determined (either by a previous use of one of these 9959features, or because the compiler needed the assembly name in order to 9960generate code), and the new name is different, a warning issues and 9961the name does not change. 9962 9963@item The @var{oldname} used by @code{#pragma redefine_extname} is 9964always the C-language name. 9965 9966@item If @code{#pragma extern_prefix} is in effect, and a declaration 9967occurs with an asm label attached, the prefix is silently ignored for 9968that declaration. 9969 9970@item If @code{#pragma extern_prefix} and @code{#pragma redefine_extname} 9971apply to the same declaration, whichever triggered first wins, and a 9972warning issues if they contradict each other. (We would like to have 9973@code{#pragma redefine_extname} always win, for consistency with asm 9974labels, but if @code{#pragma extern_prefix} triggers first we have no 9975way of knowing that that happened.) 9976@end enumerate 9977 9978@node Structure-Packing Pragmas 9979@subsection Structure-Packing Pragmas 9980 9981For compatibility with Win32, GCC supports a set of @code{#pragma} 9982directives which change the maximum alignment of members of structures 9983(other than zero-width bitfields), unions, and classes subsequently 9984defined. The @var{n} value below always is required to be a small power 9985of two and specifies the new alignment in bytes. 9986 9987@enumerate 9988@item @code{#pragma pack(@var{n})} simply sets the new alignment. 9989@item @code{#pragma pack()} sets the alignment to the one that was in 9990effect when compilation started (see also command line option 9991@option{-fpack-struct[=<n>]} @pxref{Code Gen Options}). 9992@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment 9993setting on an internal stack and then optionally sets the new alignment. 9994@item @code{#pragma pack(pop)} restores the alignment setting to the one 9995saved at the top of the internal stack (and removes that stack entry). 9996Note that @code{#pragma pack([@var{n}])} does not influence this internal 9997stack; thus it is possible to have @code{#pragma pack(push)} followed by 9998multiple @code{#pragma pack(@var{n})} instances and finalized by a single 9999@code{#pragma pack(pop)}. 10000@end enumerate 10001 10002Some targets, e.g. i386 and powerpc, support the @code{ms_struct} 10003@code{#pragma} which lays out a structure as the documented 10004@code{__attribute__ ((ms_struct))}. 10005@enumerate 10006@item @code{#pragma ms_struct on} turns on the layout for structures 10007declared. 10008@item @code{#pragma ms_struct off} turns off the layout for structures 10009declared. 10010@item @code{#pragma ms_struct reset} goes back to the default layout. 10011@end enumerate 10012 10013@node Weak Pragmas 10014@subsection Weak Pragmas 10015 10016For compatibility with SVR4, GCC supports a set of @code{#pragma} 10017directives for declaring symbols to be weak, and defining weak 10018aliases. 10019 10020@table @code 10021@item #pragma weak @var{symbol} 10022@cindex pragma, weak 10023This pragma declares @var{symbol} to be weak, as if the declaration 10024had the attribute of the same name. The pragma may appear before 10025or after the declaration of @var{symbol}, but must appear before 10026either its first use or its definition. It is not an error for 10027@var{symbol} to never be defined at all. 10028 10029@item #pragma weak @var{symbol1} = @var{symbol2} 10030This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. 10031It is an error if @var{symbol2} is not defined in the current 10032translation unit. 10033@end table 10034 10035@node Diagnostic Pragmas 10036@subsection Diagnostic Pragmas 10037 10038GCC allows the user to selectively enable or disable certain types of 10039diagnostics, and change the kind of the diagnostic. For example, a 10040project's policy might require that all sources compile with 10041@option{-Werror} but certain files might have exceptions allowing 10042specific types of warnings. Or, a project might selectively enable 10043diagnostics and treat them as errors depending on which preprocessor 10044macros are defined. 10045 10046@table @code 10047@item #pragma GCC diagnostic @var{kind} @var{option} 10048@cindex pragma, diagnostic 10049 10050Modifies the disposition of a diagnostic. Note that not all 10051diagnostics are modifiable; at the moment only warnings (normally 10052controlled by @samp{-W...}) can be controlled, and not all of them. 10053Use @option{-fdiagnostics-show-option} to determine which diagnostics 10054are controllable and which option controls them. 10055 10056@var{kind} is @samp{error} to treat this diagnostic as an error, 10057@samp{warning} to treat it like a warning (even if @option{-Werror} is 10058in effect), or @samp{ignored} if the diagnostic is to be ignored. 10059@var{option} is a double quoted string which matches the command line 10060option. 10061 10062@example 10063#pragma GCC diagnostic warning "-Wformat" 10064#pragma GCC diagnostic error "-Wformat" 10065#pragma GCC diagnostic ignored "-Wformat" 10066@end example 10067 10068Note that these pragmas override any command line options. Also, 10069while it is syntactically valid to put these pragmas anywhere in your 10070sources, the only supported location for them is before any data or 10071functions are defined. Doing otherwise may result in unpredictable 10072results depending on how the optimizer manages your sources. If the 10073same option is listed multiple times, the last one specified is the 10074one that is in effect. This pragma is not intended to be a general 10075purpose replacement for command line options, but for implementing 10076strict control over project policies. 10077 10078@end table 10079 10080@node Visibility Pragmas 10081@subsection Visibility Pragmas 10082 10083@table @code 10084@item #pragma GCC visibility push(@var{visibility}) 10085@itemx #pragma GCC visibility pop 10086@cindex pragma, visibility 10087 10088This pragma allows the user to set the visibility for multiple 10089declarations without having to give each a visibility attribute 10090@xref{Function Attributes}, for more information about visibility and 10091the attribute syntax. 10092 10093In C++, @samp{#pragma GCC visibility} affects only namespace-scope 10094declarations. Class members and template specializations are not 10095affected; if you want to override the visibility for a particular 10096member or instantiation, you must use an attribute. 10097 10098@end table 10099 10100@node Unnamed Fields 10101@section Unnamed struct/union fields within structs/unions 10102@cindex struct 10103@cindex union 10104 10105For compatibility with other compilers, GCC allows you to define 10106a structure or union that contains, as fields, structures and unions 10107without names. For example: 10108 10109@smallexample 10110struct @{ 10111 int a; 10112 union @{ 10113 int b; 10114 float c; 10115 @}; 10116 int d; 10117@} foo; 10118@end smallexample 10119 10120In this example, the user would be able to access members of the unnamed 10121union with code like @samp{foo.b}. Note that only unnamed structs and 10122unions are allowed, you may not have, for example, an unnamed 10123@code{int}. 10124 10125You must never create such structures that cause ambiguous field definitions. 10126For example, this structure: 10127 10128@smallexample 10129struct @{ 10130 int a; 10131 struct @{ 10132 int a; 10133 @}; 10134@} foo; 10135@end smallexample 10136 10137It is ambiguous which @code{a} is being referred to with @samp{foo.a}. 10138Such constructs are not supported and must be avoided. In the future, 10139such constructs may be detected and treated as compilation errors. 10140 10141@opindex fms-extensions 10142Unless @option{-fms-extensions} is used, the unnamed field must be a 10143structure or union definition without a tag (for example, @samp{struct 10144@{ int a; @};}). If @option{-fms-extensions} is used, the field may 10145also be a definition with a tag such as @samp{struct foo @{ int a; 10146@};}, a reference to a previously defined structure or union such as 10147@samp{struct foo;}, or a reference to a @code{typedef} name for a 10148previously defined structure or union type. 10149 10150@node Thread-Local 10151@section Thread-Local Storage 10152@cindex Thread-Local Storage 10153@cindex @acronym{TLS} 10154@cindex __thread 10155 10156Thread-local storage (@acronym{TLS}) is a mechanism by which variables 10157are allocated such that there is one instance of the variable per extant 10158thread. The run-time model GCC uses to implement this originates 10159in the IA-64 processor-specific ABI, but has since been migrated 10160to other processors as well. It requires significant support from 10161the linker (@command{ld}), dynamic linker (@command{ld.so}), and 10162system libraries (@file{libc.so} and @file{libpthread.so}), so it 10163is not available everywhere. 10164 10165At the user level, the extension is visible with a new storage 10166class keyword: @code{__thread}. For example: 10167 10168@smallexample 10169__thread int i; 10170extern __thread struct state s; 10171static __thread char *p; 10172@end smallexample 10173 10174The @code{__thread} specifier may be used alone, with the @code{extern} 10175or @code{static} specifiers, but with no other storage class specifier. 10176When used with @code{extern} or @code{static}, @code{__thread} must appear 10177immediately after the other storage class specifier. 10178 10179The @code{__thread} specifier may be applied to any global, file-scoped 10180static, function-scoped static, or static data member of a class. It may 10181not be applied to block-scoped automatic or non-static data member. 10182 10183When the address-of operator is applied to a thread-local variable, it is 10184evaluated at run-time and returns the address of the current thread's 10185instance of that variable. An address so obtained may be used by any 10186thread. When a thread terminates, any pointers to thread-local variables 10187in that thread become invalid. 10188 10189No static initialization may refer to the address of a thread-local variable. 10190 10191In C++, if an initializer is present for a thread-local variable, it must 10192be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ 10193standard. 10194 10195See @uref{http://people.redhat.com/drepper/tls.pdf, 10196ELF Handling For Thread-Local Storage} for a detailed explanation of 10197the four thread-local storage addressing models, and how the run-time 10198is expected to function. 10199 10200@menu 10201* C99 Thread-Local Edits:: 10202* C++98 Thread-Local Edits:: 10203@end menu 10204 10205@node C99 Thread-Local Edits 10206@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage 10207 10208The following are a set of changes to ISO/IEC 9899:1999 (aka C99) 10209that document the exact semantics of the language extension. 10210 10211@itemize @bullet 10212@item 10213@cite{5.1.2 Execution environments} 10214 10215Add new text after paragraph 1 10216 10217@quotation 10218Within either execution environment, a @dfn{thread} is a flow of 10219control within a program. It is implementation defined whether 10220or not there may be more than one thread associated with a program. 10221It is implementation defined how threads beyond the first are 10222created, the name and type of the function called at thread 10223startup, and how threads may be terminated. However, objects 10224with thread storage duration shall be initialized before thread 10225startup. 10226@end quotation 10227 10228@item 10229@cite{6.2.4 Storage durations of objects} 10230 10231Add new text before paragraph 3 10232 10233@quotation 10234An object whose identifier is declared with the storage-class 10235specifier @w{@code{__thread}} has @dfn{thread storage duration}. 10236Its lifetime is the entire execution of the thread, and its 10237stored value is initialized only once, prior to thread startup. 10238@end quotation 10239 10240@item 10241@cite{6.4.1 Keywords} 10242 10243Add @code{__thread}. 10244 10245@item 10246@cite{6.7.1 Storage-class specifiers} 10247 10248Add @code{__thread} to the list of storage class specifiers in 10249paragraph 1. 10250 10251Change paragraph 2 to 10252 10253@quotation 10254With the exception of @code{__thread}, at most one storage-class 10255specifier may be given [@dots{}]. The @code{__thread} specifier may 10256be used alone, or immediately following @code{extern} or 10257@code{static}. 10258@end quotation 10259 10260Add new text after paragraph 6 10261 10262@quotation 10263The declaration of an identifier for a variable that has 10264block scope that specifies @code{__thread} shall also 10265specify either @code{extern} or @code{static}. 10266 10267The @code{__thread} specifier shall be used only with 10268variables. 10269@end quotation 10270@end itemize 10271 10272@node C++98 Thread-Local Edits 10273@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage 10274 10275The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) 10276that document the exact semantics of the language extension. 10277 10278@itemize @bullet 10279@item 10280@b{[intro.execution]} 10281 10282New text after paragraph 4 10283 10284@quotation 10285A @dfn{thread} is a flow of control within the abstract machine. 10286It is implementation defined whether or not there may be more than 10287one thread. 10288@end quotation 10289 10290New text after paragraph 7 10291 10292@quotation 10293It is unspecified whether additional action must be taken to 10294ensure when and whether side effects are visible to other threads. 10295@end quotation 10296 10297@item 10298@b{[lex.key]} 10299 10300Add @code{__thread}. 10301 10302@item 10303@b{[basic.start.main]} 10304 10305Add after paragraph 5 10306 10307@quotation 10308The thread that begins execution at the @code{main} function is called 10309the @dfn{main thread}. It is implementation defined how functions 10310beginning threads other than the main thread are designated or typed. 10311A function so designated, as well as the @code{main} function, is called 10312a @dfn{thread startup function}. It is implementation defined what 10313happens if a thread startup function returns. It is implementation 10314defined what happens to other threads when any thread calls @code{exit}. 10315@end quotation 10316 10317@item 10318@b{[basic.start.init]} 10319 10320Add after paragraph 4 10321 10322@quotation 10323The storage for an object of thread storage duration shall be 10324statically initialized before the first statement of the thread startup 10325function. An object of thread storage duration shall not require 10326dynamic initialization. 10327@end quotation 10328 10329@item 10330@b{[basic.start.term]} 10331 10332Add after paragraph 3 10333 10334@quotation 10335The type of an object with thread storage duration shall not have a 10336non-trivial destructor, nor shall it be an array type whose elements 10337(directly or indirectly) have non-trivial destructors. 10338@end quotation 10339 10340@item 10341@b{[basic.stc]} 10342 10343Add ``thread storage duration'' to the list in paragraph 1. 10344 10345Change paragraph 2 10346 10347@quotation 10348Thread, static, and automatic storage durations are associated with 10349objects introduced by declarations [@dots{}]. 10350@end quotation 10351 10352Add @code{__thread} to the list of specifiers in paragraph 3. 10353 10354@item 10355@b{[basic.stc.thread]} 10356 10357New section before @b{[basic.stc.static]} 10358 10359@quotation 10360The keyword @code{__thread} applied to a non-local object gives the 10361object thread storage duration. 10362 10363A local variable or class data member declared both @code{static} 10364and @code{__thread} gives the variable or member thread storage 10365duration. 10366@end quotation 10367 10368@item 10369@b{[basic.stc.static]} 10370 10371Change paragraph 1 10372 10373@quotation 10374All objects which have neither thread storage duration, dynamic 10375storage duration nor are local [@dots{}]. 10376@end quotation 10377 10378@item 10379@b{[dcl.stc]} 10380 10381Add @code{__thread} to the list in paragraph 1. 10382 10383Change paragraph 1 10384 10385@quotation 10386With the exception of @code{__thread}, at most one 10387@var{storage-class-specifier} shall appear in a given 10388@var{decl-specifier-seq}. The @code{__thread} specifier may 10389be used alone, or immediately following the @code{extern} or 10390@code{static} specifiers. [@dots{}] 10391@end quotation 10392 10393Add after paragraph 5 10394 10395@quotation 10396The @code{__thread} specifier can be applied only to the names of objects 10397and to anonymous unions. 10398@end quotation 10399 10400@item 10401@b{[class.mem]} 10402 10403Add after paragraph 6 10404 10405@quotation 10406Non-@code{static} members shall not be @code{__thread}. 10407@end quotation 10408@end itemize 10409 10410@node C++ Extensions 10411@chapter Extensions to the C++ Language 10412@cindex extensions, C++ language 10413@cindex C++ language extensions 10414 10415The GNU compiler provides these extensions to the C++ language (and you 10416can also use most of the C language extensions in your C++ programs). If you 10417want to write code that checks whether these features are available, you can 10418test for the GNU compiler the same way as for C programs: check for a 10419predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to 10420test specifically for GNU C++ (@pxref{Common Predefined Macros,, 10421Predefined Macros,cpp,The GNU C Preprocessor}). 10422 10423@menu 10424* Volatiles:: What constitutes an access to a volatile object. 10425* Restricted Pointers:: C99 restricted pointers and references. 10426* Vague Linkage:: Where G++ puts inlines, vtables and such. 10427* C++ Interface:: You can use a single C++ header file for both 10428 declarations and definitions. 10429* Template Instantiation:: Methods for ensuring that exactly one copy of 10430 each needed template instantiation is emitted. 10431* Bound member functions:: You can extract a function pointer to the 10432 method denoted by a @samp{->*} or @samp{.*} expression. 10433* C++ Attributes:: Variable, function, and type attributes for C++ only. 10434* Namespace Association:: Strong using-directives for namespace association. 10435* Java Exceptions:: Tweaking exception handling to work with Java. 10436* Deprecated Features:: Things will disappear from g++. 10437* Backwards Compatibility:: Compatibilities with earlier definitions of C++. 10438@end menu 10439 10440@node Volatiles 10441@section When is a Volatile Object Accessed? 10442@cindex accessing volatiles 10443@cindex volatile read 10444@cindex volatile write 10445@cindex volatile access 10446 10447Both the C and C++ standard have the concept of volatile objects. These 10448are normally accessed by pointers and used for accessing hardware. The 10449standards encourage compilers to refrain from optimizations concerning 10450accesses to volatile objects. The C standard leaves it implementation 10451defined as to what constitutes a volatile access. The C++ standard omits 10452to specify this, except to say that C++ should behave in a similar manner 10453to C with respect to volatiles, where possible. The minimum either 10454standard specifies is that at a sequence point all previous accesses to 10455volatile objects have stabilized and no subsequent accesses have 10456occurred. Thus an implementation is free to reorder and combine 10457volatile accesses which occur between sequence points, but cannot do so 10458for accesses across a sequence point. The use of volatiles does not 10459allow you to violate the restriction on updating objects multiple times 10460within a sequence point. 10461 10462@xref{Qualifiers implementation, , Volatile qualifier and the C compiler}. 10463 10464The behavior differs slightly between C and C++ in the non-obvious cases: 10465 10466@smallexample 10467volatile int *src = @var{somevalue}; 10468*src; 10469@end smallexample 10470 10471With C, such expressions are rvalues, and GCC interprets this either as a 10472read of the volatile object being pointed to or only as request to evaluate 10473the side-effects. The C++ standard specifies that such expressions do not 10474undergo lvalue to rvalue conversion, and that the type of the dereferenced 10475object may be incomplete. The C++ standard does not specify explicitly 10476that it is this lvalue to rvalue conversion which may be responsible for 10477causing an access. However, there is reason to believe that it is, 10478because otherwise certain simple expressions become undefined. However, 10479because it would surprise most programmers, G++ treats dereferencing a 10480pointer to volatile object of complete type when the value is unused as 10481GCC would do for an equivalent type in C. When the object has incomplete 10482type, G++ issues a warning; if you wish to force an error, you must 10483force a conversion to rvalue with, for instance, a static cast. 10484 10485When using a reference to volatile, G++ does not treat equivalent 10486expressions as accesses to volatiles, but instead issues a warning that 10487no volatile is accessed. The rationale for this is that otherwise it 10488becomes difficult to determine where volatile access occur, and not 10489possible to ignore the return value from functions returning volatile 10490references. Again, if you wish to force a read, cast the reference to 10491an rvalue. 10492 10493@node Restricted Pointers 10494@section Restricting Pointer Aliasing 10495@cindex restricted pointers 10496@cindex restricted references 10497@cindex restricted this pointer 10498 10499As with the C front end, G++ understands the C99 feature of restricted pointers, 10500specified with the @code{__restrict__}, or @code{__restrict} type 10501qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} 10502language flag, @code{restrict} is not a keyword in C++. 10503 10504In addition to allowing restricted pointers, you can specify restricted 10505references, which indicate that the reference is not aliased in the local 10506context. 10507 10508@smallexample 10509void fn (int *__restrict__ rptr, int &__restrict__ rref) 10510@{ 10511 /* @r{@dots{}} */ 10512@} 10513@end smallexample 10514 10515@noindent 10516In the body of @code{fn}, @var{rptr} points to an unaliased integer and 10517@var{rref} refers to a (different) unaliased integer. 10518 10519You may also specify whether a member function's @var{this} pointer is 10520unaliased by using @code{__restrict__} as a member function qualifier. 10521 10522@smallexample 10523void T::fn () __restrict__ 10524@{ 10525 /* @r{@dots{}} */ 10526@} 10527@end smallexample 10528 10529@noindent 10530Within the body of @code{T::fn}, @var{this} will have the effective 10531definition @code{T *__restrict__ const this}. Notice that the 10532interpretation of a @code{__restrict__} member function qualifier is 10533different to that of @code{const} or @code{volatile} qualifier, in that it 10534is applied to the pointer rather than the object. This is consistent with 10535other compilers which implement restricted pointers. 10536 10537As with all outermost parameter qualifiers, @code{__restrict__} is 10538ignored in function definition matching. This means you only need to 10539specify @code{__restrict__} in a function definition, rather than 10540in a function prototype as well. 10541 10542@node Vague Linkage 10543@section Vague Linkage 10544@cindex vague linkage 10545 10546There are several constructs in C++ which require space in the object 10547file but are not clearly tied to a single translation unit. We say that 10548these constructs have ``vague linkage''. Typically such constructs are 10549emitted wherever they are needed, though sometimes we can be more 10550clever. 10551 10552@table @asis 10553@item Inline Functions 10554Inline functions are typically defined in a header file which can be 10555included in many different compilations. Hopefully they can usually be 10556inlined, but sometimes an out-of-line copy is necessary, if the address 10557of the function is taken or if inlining fails. In general, we emit an 10558out-of-line copy in all translation units where one is needed. As an 10559exception, we only emit inline virtual functions with the vtable, since 10560it will always require a copy. 10561 10562Local static variables and string constants used in an inline function 10563are also considered to have vague linkage, since they must be shared 10564between all inlined and out-of-line instances of the function. 10565 10566@item VTables 10567@cindex vtable 10568C++ virtual functions are implemented in most compilers using a lookup 10569table, known as a vtable. The vtable contains pointers to the virtual 10570functions provided by a class, and each object of the class contains a 10571pointer to its vtable (or vtables, in some multiple-inheritance 10572situations). If the class declares any non-inline, non-pure virtual 10573functions, the first one is chosen as the ``key method'' for the class, 10574and the vtable is only emitted in the translation unit where the key 10575method is defined. 10576 10577@emph{Note:} If the chosen key method is later defined as inline, the 10578vtable will still be emitted in every translation unit which defines it. 10579Make sure that any inline virtuals are declared inline in the class 10580body, even if they are not defined there. 10581 10582@item type_info objects 10583@cindex type_info 10584@cindex RTTI 10585C++ requires information about types to be written out in order to 10586implement @samp{dynamic_cast}, @samp{typeid} and exception handling. 10587For polymorphic classes (classes with virtual functions), the type_info 10588object is written out along with the vtable so that @samp{dynamic_cast} 10589can determine the dynamic type of a class object at runtime. For all 10590other types, we write out the type_info object when it is used: when 10591applying @samp{typeid} to an expression, throwing an object, or 10592referring to a type in a catch clause or exception specification. 10593 10594@item Template Instantiations 10595Most everything in this section also applies to template instantiations, 10596but there are other options as well. 10597@xref{Template Instantiation,,Where's the Template?}. 10598 10599@end table 10600 10601When used with GNU ld version 2.8 or later on an ELF system such as 10602GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of 10603these constructs will be discarded at link time. This is known as 10604COMDAT support. 10605 10606On targets that don't support COMDAT, but do support weak symbols, GCC 10607will use them. This way one copy will override all the others, but 10608the unused copies will still take up space in the executable. 10609 10610For targets which do not support either COMDAT or weak symbols, 10611most entities with vague linkage will be emitted as local symbols to 10612avoid duplicate definition errors from the linker. This will not happen 10613for local statics in inlines, however, as having multiple copies will 10614almost certainly break things. 10615 10616@xref{C++ Interface,,Declarations and Definitions in One Header}, for 10617another way to control placement of these constructs. 10618 10619@node C++ Interface 10620@section #pragma interface and implementation 10621 10622@cindex interface and implementation headers, C++ 10623@cindex C++ interface and implementation headers 10624@cindex pragmas, interface and implementation 10625 10626@code{#pragma interface} and @code{#pragma implementation} provide the 10627user with a way of explicitly directing the compiler to emit entities 10628with vague linkage (and debugging information) in a particular 10629translation unit. 10630 10631@emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in 10632most cases, because of COMDAT support and the ``key method'' heuristic 10633mentioned in @ref{Vague Linkage}. Using them can actually cause your 10634program to grow due to unnecessary out-of-line copies of inline 10635functions. Currently (3.4) the only benefit of these 10636@code{#pragma}s is reduced duplication of debugging information, and 10637that should be addressed soon on DWARF 2 targets with the use of 10638COMDAT groups. 10639 10640@table @code 10641@item #pragma interface 10642@itemx #pragma interface "@var{subdir}/@var{objects}.h" 10643@kindex #pragma interface 10644Use this directive in @emph{header files} that define object classes, to save 10645space in most of the object files that use those classes. Normally, 10646local copies of certain information (backup copies of inline member 10647functions, debugging information, and the internal tables that implement 10648virtual functions) must be kept in each object file that includes class 10649definitions. You can use this pragma to avoid such duplication. When a 10650header file containing @samp{#pragma interface} is included in a 10651compilation, this auxiliary information will not be generated (unless 10652the main input source file itself uses @samp{#pragma implementation}). 10653Instead, the object files will contain references to be resolved at link 10654time. 10655 10656The second form of this directive is useful for the case where you have 10657multiple headers with the same name in different directories. If you 10658use this form, you must specify the same string to @samp{#pragma 10659implementation}. 10660 10661@item #pragma implementation 10662@itemx #pragma implementation "@var{objects}.h" 10663@kindex #pragma implementation 10664Use this pragma in a @emph{main input file}, when you want full output from 10665included header files to be generated (and made globally visible). The 10666included header file, in turn, should use @samp{#pragma interface}. 10667Backup copies of inline member functions, debugging information, and the 10668internal tables used to implement virtual functions are all generated in 10669implementation files. 10670 10671@cindex implied @code{#pragma implementation} 10672@cindex @code{#pragma implementation}, implied 10673@cindex naming convention, implementation headers 10674If you use @samp{#pragma implementation} with no argument, it applies to 10675an include file with the same basename@footnote{A file's @dfn{basename} 10676was the name stripped of all leading path information and of trailing 10677suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source 10678file. For example, in @file{allclass.cc}, giving just 10679@samp{#pragma implementation} 10680by itself is equivalent to @samp{#pragma implementation "allclass.h"}. 10681 10682In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as 10683an implementation file whenever you would include it from 10684@file{allclass.cc} even if you never specified @samp{#pragma 10685implementation}. This was deemed to be more trouble than it was worth, 10686however, and disabled. 10687 10688Use the string argument if you want a single implementation file to 10689include code from multiple header files. (You must also use 10690@samp{#include} to include the header file; @samp{#pragma 10691implementation} only specifies how to use the file---it doesn't actually 10692include it.) 10693 10694There is no way to split up the contents of a single header file into 10695multiple implementation files. 10696@end table 10697 10698@cindex inlining and C++ pragmas 10699@cindex C++ pragmas, effect on inlining 10700@cindex pragmas in C++, effect on inlining 10701@samp{#pragma implementation} and @samp{#pragma interface} also have an 10702effect on function inlining. 10703 10704If you define a class in a header file marked with @samp{#pragma 10705interface}, the effect on an inline function defined in that class is 10706similar to an explicit @code{extern} declaration---the compiler emits 10707no code at all to define an independent version of the function. Its 10708definition is used only for inlining with its callers. 10709 10710@opindex fno-implement-inlines 10711Conversely, when you include the same header file in a main source file 10712that declares it as @samp{#pragma implementation}, the compiler emits 10713code for the function itself; this defines a version of the function 10714that can be found via pointers (or by callers compiled without 10715inlining). If all calls to the function can be inlined, you can avoid 10716emitting the function by compiling with @option{-fno-implement-inlines}. 10717If any calls were not inlined, you will get linker errors. 10718 10719@node Template Instantiation 10720@section Where's the Template? 10721@cindex template instantiation 10722 10723C++ templates are the first language feature to require more 10724intelligence from the environment than one usually finds on a UNIX 10725system. Somehow the compiler and linker have to make sure that each 10726template instance occurs exactly once in the executable if it is needed, 10727and not at all otherwise. There are two basic approaches to this 10728problem, which are referred to as the Borland model and the Cfront model. 10729 10730@table @asis 10731@item Borland model 10732Borland C++ solved the template instantiation problem by adding the code 10733equivalent of common blocks to their linker; the compiler emits template 10734instances in each translation unit that uses them, and the linker 10735collapses them together. The advantage of this model is that the linker 10736only has to consider the object files themselves; there is no external 10737complexity to worry about. This disadvantage is that compilation time 10738is increased because the template code is being compiled repeatedly. 10739Code written for this model tends to include definitions of all 10740templates in the header file, since they must be seen to be 10741instantiated. 10742 10743@item Cfront model 10744The AT&T C++ translator, Cfront, solved the template instantiation 10745problem by creating the notion of a template repository, an 10746automatically maintained place where template instances are stored. A 10747more modern version of the repository works as follows: As individual 10748object files are built, the compiler places any template definitions and 10749instantiations encountered in the repository. At link time, the link 10750wrapper adds in the objects in the repository and compiles any needed 10751instances that were not previously emitted. The advantages of this 10752model are more optimal compilation speed and the ability to use the 10753system linker; to implement the Borland model a compiler vendor also 10754needs to replace the linker. The disadvantages are vastly increased 10755complexity, and thus potential for error; for some code this can be 10756just as transparent, but in practice it can been very difficult to build 10757multiple programs in one directory and one program in multiple 10758directories. Code written for this model tends to separate definitions 10759of non-inline member templates into a separate file, which should be 10760compiled separately. 10761@end table 10762 10763When used with GNU ld version 2.8 or later on an ELF system such as 10764GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the 10765Borland model. On other systems, G++ implements neither automatic 10766model. 10767 10768A future version of G++ will support a hybrid model whereby the compiler 10769will emit any instantiations for which the template definition is 10770included in the compile, and store template definitions and 10771instantiation context information into the object file for the rest. 10772The link wrapper will extract that information as necessary and invoke 10773the compiler to produce the remaining instantiations. The linker will 10774then combine duplicate instantiations. 10775 10776In the mean time, you have the following options for dealing with 10777template instantiations: 10778 10779@enumerate 10780@item 10781@opindex frepo 10782Compile your template-using code with @option{-frepo}. The compiler will 10783generate files with the extension @samp{.rpo} listing all of the 10784template instantiations used in the corresponding object files which 10785could be instantiated there; the link wrapper, @samp{collect2}, will 10786then update the @samp{.rpo} files to tell the compiler where to place 10787those instantiations and rebuild any affected object files. The 10788link-time overhead is negligible after the first pass, as the compiler 10789will continue to place the instantiations in the same files. 10790 10791This is your best option for application code written for the Borland 10792model, as it will just work. Code written for the Cfront model will 10793need to be modified so that the template definitions are available at 10794one or more points of instantiation; usually this is as simple as adding 10795@code{#include <tmethods.cc>} to the end of each template header. 10796 10797For library code, if you want the library to provide all of the template 10798instantiations it needs, just try to link all of its object files 10799together; the link will fail, but cause the instantiations to be 10800generated as a side effect. Be warned, however, that this may cause 10801conflicts if multiple libraries try to provide the same instantiations. 10802For greater control, use explicit instantiation as described in the next 10803option. 10804 10805@item 10806@opindex fno-implicit-templates 10807Compile your code with @option{-fno-implicit-templates} to disable the 10808implicit generation of template instances, and explicitly instantiate 10809all the ones you use. This approach requires more knowledge of exactly 10810which instances you need than do the others, but it's less 10811mysterious and allows greater control. You can scatter the explicit 10812instantiations throughout your program, perhaps putting them in the 10813translation units where the instances are used or the translation units 10814that define the templates themselves; you can put all of the explicit 10815instantiations you need into one big file; or you can create small files 10816like 10817 10818@smallexample 10819#include "Foo.h" 10820#include "Foo.cc" 10821 10822template class Foo<int>; 10823template ostream& operator << 10824 (ostream&, const Foo<int>&); 10825@end smallexample 10826 10827for each of the instances you need, and create a template instantiation 10828library from those. 10829 10830If you are using Cfront-model code, you can probably get away with not 10831using @option{-fno-implicit-templates} when compiling files that don't 10832@samp{#include} the member template definitions. 10833 10834If you use one big file to do the instantiations, you may want to 10835compile it without @option{-fno-implicit-templates} so you get all of the 10836instances required by your explicit instantiations (but not by any 10837other files) without having to specify them as well. 10838 10839G++ has extended the template instantiation syntax given in the ISO 10840standard to allow forward declaration of explicit instantiations 10841(with @code{extern}), instantiation of the compiler support data for a 10842template class (i.e.@: the vtable) without instantiating any of its 10843members (with @code{inline}), and instantiation of only the static data 10844members of a template class, without the support data or member 10845functions (with (@code{static}): 10846 10847@smallexample 10848extern template int max (int, int); 10849inline template class Foo<int>; 10850static template class Foo<int>; 10851@end smallexample 10852 10853@item 10854Do nothing. Pretend G++ does implement automatic instantiation 10855management. Code written for the Borland model will work fine, but 10856each translation unit will contain instances of each of the templates it 10857uses. In a large program, this can lead to an unacceptable amount of code 10858duplication. 10859@end enumerate 10860 10861@node Bound member functions 10862@section Extracting the function pointer from a bound pointer to member function 10863@cindex pmf 10864@cindex pointer to member function 10865@cindex bound pointer to member function 10866 10867In C++, pointer to member functions (PMFs) are implemented using a wide 10868pointer of sorts to handle all the possible call mechanisms; the PMF 10869needs to store information about how to adjust the @samp{this} pointer, 10870and if the function pointed to is virtual, where to find the vtable, and 10871where in the vtable to look for the member function. If you are using 10872PMFs in an inner loop, you should really reconsider that decision. If 10873that is not an option, you can extract the pointer to the function that 10874would be called for a given object/PMF pair and call it directly inside 10875the inner loop, to save a bit of time. 10876 10877Note that you will still be paying the penalty for the call through a 10878function pointer; on most modern architectures, such a call defeats the 10879branch prediction features of the CPU@. This is also true of normal 10880virtual function calls. 10881 10882The syntax for this extension is 10883 10884@smallexample 10885extern A a; 10886extern int (A::*fp)(); 10887typedef int (*fptr)(A *); 10888 10889fptr p = (fptr)(a.*fp); 10890@end smallexample 10891 10892For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), 10893no object is needed to obtain the address of the function. They can be 10894converted to function pointers directly: 10895 10896@smallexample 10897fptr p1 = (fptr)(&A::foo); 10898@end smallexample 10899 10900@opindex Wno-pmf-conversions 10901You must specify @option{-Wno-pmf-conversions} to use this extension. 10902 10903@node C++ Attributes 10904@section C++-Specific Variable, Function, and Type Attributes 10905 10906Some attributes only make sense for C++ programs. 10907 10908@table @code 10909@item init_priority (@var{priority}) 10910@cindex init_priority attribute 10911 10912 10913In Standard C++, objects defined at namespace scope are guaranteed to be 10914initialized in an order in strict accordance with that of their definitions 10915@emph{in a given translation unit}. No guarantee is made for initializations 10916across translation units. However, GNU C++ allows users to control the 10917order of initialization of objects defined at namespace scope with the 10918@code{init_priority} attribute by specifying a relative @var{priority}, 10919a constant integral expression currently bounded between 101 and 65535 10920inclusive. Lower numbers indicate a higher priority. 10921 10922In the following example, @code{A} would normally be created before 10923@code{B}, but the @code{init_priority} attribute has reversed that order: 10924 10925@smallexample 10926Some_Class A __attribute__ ((init_priority (2000))); 10927Some_Class B __attribute__ ((init_priority (543))); 10928@end smallexample 10929 10930@noindent 10931Note that the particular values of @var{priority} do not matter; only their 10932relative ordering. 10933 10934@item java_interface 10935@cindex java_interface attribute 10936 10937This type attribute informs C++ that the class is a Java interface. It may 10938only be applied to classes declared within an @code{extern "Java"} block. 10939Calls to methods declared in this interface will be dispatched using GCJ's 10940interface table mechanism, instead of regular virtual table dispatch. 10941 10942@end table 10943 10944See also @xref{Namespace Association}. 10945 10946@node Namespace Association 10947@section Namespace Association 10948 10949@strong{Caution:} The semantics of this extension are not fully 10950defined. Users should refrain from using this extension as its 10951semantics may change subtly over time. It is possible that this 10952extension will be removed in future versions of G++. 10953 10954A using-directive with @code{__attribute ((strong))} is stronger 10955than a normal using-directive in two ways: 10956 10957@itemize @bullet 10958@item 10959Templates from the used namespace can be specialized and explicitly 10960instantiated as though they were members of the using namespace. 10961 10962@item 10963The using namespace is considered an associated namespace of all 10964templates in the used namespace for purposes of argument-dependent 10965name lookup. 10966@end itemize 10967 10968The used namespace must be nested within the using namespace so that 10969normal unqualified lookup works properly. 10970 10971This is useful for composing a namespace transparently from 10972implementation namespaces. For example: 10973 10974@smallexample 10975namespace std @{ 10976 namespace debug @{ 10977 template <class T> struct A @{ @}; 10978 @} 10979 using namespace debug __attribute ((__strong__)); 10980 template <> struct A<int> @{ @}; // @r{ok to specialize} 10981 10982 template <class T> void f (A<T>); 10983@} 10984 10985int main() 10986@{ 10987 f (std::A<float>()); // @r{lookup finds} std::f 10988 f (std::A<int>()); 10989@} 10990@end smallexample 10991 10992@node Java Exceptions 10993@section Java Exceptions 10994 10995The Java language uses a slightly different exception handling model 10996from C++. Normally, GNU C++ will automatically detect when you are 10997writing C++ code that uses Java exceptions, and handle them 10998appropriately. However, if C++ code only needs to execute destructors 10999when Java exceptions are thrown through it, GCC will guess incorrectly. 11000Sample problematic code is: 11001 11002@smallexample 11003 struct S @{ ~S(); @}; 11004 extern void bar(); // @r{is written in Java, and may throw exceptions} 11005 void foo() 11006 @{ 11007 S s; 11008 bar(); 11009 @} 11010@end smallexample 11011 11012@noindent 11013The usual effect of an incorrect guess is a link failure, complaining of 11014a missing routine called @samp{__gxx_personality_v0}. 11015 11016You can inform the compiler that Java exceptions are to be used in a 11017translation unit, irrespective of what it might think, by writing 11018@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This 11019@samp{#pragma} must appear before any functions that throw or catch 11020exceptions, or run destructors when exceptions are thrown through them. 11021 11022You cannot mix Java and C++ exceptions in the same translation unit. It 11023is believed to be safe to throw a C++ exception from one file through 11024another file compiled for the Java exception model, or vice versa, but 11025there may be bugs in this area. 11026 11027@node Deprecated Features 11028@section Deprecated Features 11029 11030In the past, the GNU C++ compiler was extended to experiment with new 11031features, at a time when the C++ language was still evolving. Now that 11032the C++ standard is complete, some of those features are superseded by 11033superior alternatives. Using the old features might cause a warning in 11034some cases that the feature will be dropped in the future. In other 11035cases, the feature might be gone already. 11036 11037While the list below is not exhaustive, it documents some of the options 11038that are now deprecated: 11039 11040@table @code 11041@item -fexternal-templates 11042@itemx -falt-external-templates 11043These are two of the many ways for G++ to implement template 11044instantiation. @xref{Template Instantiation}. The C++ standard clearly 11045defines how template definitions have to be organized across 11046implementation units. G++ has an implicit instantiation mechanism that 11047should work just fine for standard-conforming code. 11048 11049@item -fstrict-prototype 11050@itemx -fno-strict-prototype 11051Previously it was possible to use an empty prototype parameter list to 11052indicate an unspecified number of parameters (like C), rather than no 11053parameters, as C++ demands. This feature has been removed, except where 11054it is required for backwards compatibility @xref{Backwards Compatibility}. 11055@end table 11056 11057G++ allows a virtual function returning @samp{void *} to be overridden 11058by one returning a different pointer type. This extension to the 11059covariant return type rules is now deprecated and will be removed from a 11060future version. 11061 11062The G++ minimum and maximum operators (@samp{<?} and @samp{>?}) and 11063their compound forms (@samp{<?=}) and @samp{>?=}) have been deprecated 11064and will be removed in a future version. Code using these operators 11065should be modified to use @code{std::min} and @code{std::max} instead. 11066 11067The named return value extension has been deprecated, and is now 11068removed from G++. 11069 11070The use of initializer lists with new expressions has been deprecated, 11071and is now removed from G++. 11072 11073Floating and complex non-type template parameters have been deprecated, 11074and are now removed from G++. 11075 11076The implicit typename extension has been deprecated and is now 11077removed from G++. 11078 11079The use of default arguments in function pointers, function typedefs 11080and other places where they are not permitted by the standard is 11081deprecated and will be removed from a future version of G++. 11082 11083G++ allows floating-point literals to appear in integral constant expressions, 11084e.g. @samp{ enum E @{ e = int(2.2 * 3.7) @} } 11085This extension is deprecated and will be removed from a future version. 11086 11087G++ allows static data members of const floating-point type to be declared 11088with an initializer in a class definition. The standard only allows 11089initializers for static members of const integral types and const 11090enumeration types so this extension has been deprecated and will be removed 11091from a future version. 11092 11093@node Backwards Compatibility 11094@section Backwards Compatibility 11095@cindex Backwards Compatibility 11096@cindex ARM [Annotated C++ Reference Manual] 11097 11098Now that there is a definitive ISO standard C++, G++ has a specification 11099to adhere to. The C++ language evolved over time, and features that 11100used to be acceptable in previous drafts of the standard, such as the ARM 11101[Annotated C++ Reference Manual], are no longer accepted. In order to allow 11102compilation of C++ written to such drafts, G++ contains some backwards 11103compatibilities. @emph{All such backwards compatibility features are 11104liable to disappear in future versions of G++.} They should be considered 11105deprecated @xref{Deprecated Features}. 11106 11107@table @code 11108@item For scope 11109If a variable is declared at for scope, it used to remain in scope until 11110the end of the scope which contained the for statement (rather than just 11111within the for scope). G++ retains this, but issues a warning, if such a 11112variable is accessed outside the for scope. 11113 11114@item Implicit C language 11115Old C system header files did not contain an @code{extern "C" @{@dots{}@}} 11116scope to set the language. On such systems, all header files are 11117implicitly scoped inside a C language scope. Also, an empty prototype 11118@code{()} will be treated as an unspecified number of arguments, rather 11119than no arguments, as C++ demands. 11120@end table 11121