extend.texi revision 236962
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{-msse4a} is used. 7259 7260@smallexample 7261void _mm_stream_sd (double*,__m128d); 7262Generates the @code{movntsd} machine instruction. 7263void _mm_stream_ss (float*,__m128); 7264Generates the @code{movntss} machine instruction. 7265__m128i _mm_extract_si64 (__m128i, __m128i); 7266Generates the @code{extrq} machine instruction with only SSE register operands. 7267__m128i _mm_extracti_si64 (__m128i, int, int); 7268Generates the @code{extrq} machine instruction with SSE register and immediate operands. 7269__m128i _mm_insert_si64 (__m128i, __m128i); 7270Generates the @code{insertq} machine instruction with only SSE register operands. 7271__m128i _mm_inserti_si64 (__m128i, __m128i, int, int); 7272Generates the @code{insertq} machine instruction with SSE register and immediate operands. 7273@end smallexample 7274 7275The following built-in functions are available when @option{-m3dnow} is used. 7276All of them generate the machine instruction that is part of the name. 7277 7278@smallexample 7279void __builtin_ia32_femms (void) 7280v8qi __builtin_ia32_pavgusb (v8qi, v8qi) 7281v2si __builtin_ia32_pf2id (v2sf) 7282v2sf __builtin_ia32_pfacc (v2sf, v2sf) 7283v2sf __builtin_ia32_pfadd (v2sf, v2sf) 7284v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) 7285v2si __builtin_ia32_pfcmpge (v2sf, v2sf) 7286v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) 7287v2sf __builtin_ia32_pfmax (v2sf, v2sf) 7288v2sf __builtin_ia32_pfmin (v2sf, v2sf) 7289v2sf __builtin_ia32_pfmul (v2sf, v2sf) 7290v2sf __builtin_ia32_pfrcp (v2sf) 7291v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) 7292v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) 7293v2sf __builtin_ia32_pfrsqrt (v2sf) 7294v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf) 7295v2sf __builtin_ia32_pfsub (v2sf, v2sf) 7296v2sf __builtin_ia32_pfsubr (v2sf, v2sf) 7297v2sf __builtin_ia32_pi2fd (v2si) 7298v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) 7299@end smallexample 7300 7301The following built-in functions are available when both @option{-m3dnow} 7302and @option{-march=athlon} are used. All of them generate the machine 7303instruction that is part of the name. 7304 7305@smallexample 7306v2si __builtin_ia32_pf2iw (v2sf) 7307v2sf __builtin_ia32_pfnacc (v2sf, v2sf) 7308v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) 7309v2sf __builtin_ia32_pi2fw (v2si) 7310v2sf __builtin_ia32_pswapdsf (v2sf) 7311v2si __builtin_ia32_pswapdsi (v2si) 7312@end smallexample 7313 7314@node MIPS DSP Built-in Functions 7315@subsection MIPS DSP Built-in Functions 7316 7317The MIPS DSP Application-Specific Extension (ASE) includes new 7318instructions that are designed to improve the performance of DSP and 7319media applications. It provides instructions that operate on packed 73208-bit integer data, Q15 fractional data and Q31 fractional data. 7321 7322GCC supports MIPS DSP operations using both the generic 7323vector extensions (@pxref{Vector Extensions}) and a collection of 7324MIPS-specific built-in functions. Both kinds of support are 7325enabled by the @option{-mdsp} command-line option. 7326 7327At present, GCC only provides support for operations on 32-bit 7328vectors. The vector type associated with 8-bit integer data is 7329usually called @code{v4i8} and the vector type associated with Q15 is 7330usually called @code{v2q15}. They can be defined in C as follows: 7331 7332@smallexample 7333typedef char v4i8 __attribute__ ((vector_size(4))); 7334typedef short v2q15 __attribute__ ((vector_size(4))); 7335@end smallexample 7336 7337@code{v4i8} and @code{v2q15} values are initialized in the same way as 7338aggregates. For example: 7339 7340@smallexample 7341v4i8 a = @{1, 2, 3, 4@}; 7342v4i8 b; 7343b = (v4i8) @{5, 6, 7, 8@}; 7344 7345v2q15 c = @{0x0fcb, 0x3a75@}; 7346v2q15 d; 7347d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; 7348@end smallexample 7349 7350@emph{Note:} The CPU's endianness determines the order in which values 7351are packed. On little-endian targets, the first value is the least 7352significant and the last value is the most significant. The opposite 7353order applies to big-endian targets. For example, the code above will 7354set the lowest byte of @code{a} to @code{1} on little-endian targets 7355and @code{4} on big-endian targets. 7356 7357@emph{Note:} Q15 and Q31 values must be initialized with their integer 7358representation. As shown in this example, the integer representation 7359of a Q15 value can be obtained by multiplying the fractional value by 7360@code{0x1.0p15}. The equivalent for Q31 values is to multiply by 7361@code{0x1.0p31}. 7362 7363The table below lists the @code{v4i8} and @code{v2q15} operations for which 7364hardware support exists. @code{a} and @code{b} are @code{v4i8} values, 7365and @code{c} and @code{d} are @code{v2q15} values. 7366 7367@multitable @columnfractions .50 .50 7368@item C code @tab MIPS instruction 7369@item @code{a + b} @tab @code{addu.qb} 7370@item @code{c + d} @tab @code{addq.ph} 7371@item @code{a - b} @tab @code{subu.qb} 7372@item @code{c - d} @tab @code{subq.ph} 7373@end multitable 7374 7375It is easier to describe the DSP built-in functions if we first define 7376the following types: 7377 7378@smallexample 7379typedef int q31; 7380typedef int i32; 7381typedef long long a64; 7382@end smallexample 7383 7384@code{q31} and @code{i32} are actually the same as @code{int}, but we 7385use @code{q31} to indicate a Q31 fractional value and @code{i32} to 7386indicate a 32-bit integer value. Similarly, @code{a64} is the same as 7387@code{long long}, but we use @code{a64} to indicate values that will 7388be placed in one of the four DSP accumulators (@code{$ac0}, 7389@code{$ac1}, @code{$ac2} or @code{$ac3}). 7390 7391Also, some built-in functions prefer or require immediate numbers as 7392parameters, because the corresponding DSP instructions accept both immediate 7393numbers and register operands, or accept immediate numbers only. The 7394immediate parameters are listed as follows. 7395 7396@smallexample 7397imm0_7: 0 to 7. 7398imm0_15: 0 to 15. 7399imm0_31: 0 to 31. 7400imm0_63: 0 to 63. 7401imm0_255: 0 to 255. 7402imm_n32_31: -32 to 31. 7403imm_n512_511: -512 to 511. 7404@end smallexample 7405 7406The following built-in functions map directly to a particular MIPS DSP 7407instruction. Please refer to the architecture specification 7408for details on what each instruction does. 7409 7410@smallexample 7411v2q15 __builtin_mips_addq_ph (v2q15, v2q15) 7412v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) 7413q31 __builtin_mips_addq_s_w (q31, q31) 7414v4i8 __builtin_mips_addu_qb (v4i8, v4i8) 7415v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) 7416v2q15 __builtin_mips_subq_ph (v2q15, v2q15) 7417v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) 7418q31 __builtin_mips_subq_s_w (q31, q31) 7419v4i8 __builtin_mips_subu_qb (v4i8, v4i8) 7420v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) 7421i32 __builtin_mips_addsc (i32, i32) 7422i32 __builtin_mips_addwc (i32, i32) 7423i32 __builtin_mips_modsub (i32, i32) 7424i32 __builtin_mips_raddu_w_qb (v4i8) 7425v2q15 __builtin_mips_absq_s_ph (v2q15) 7426q31 __builtin_mips_absq_s_w (q31) 7427v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) 7428v2q15 __builtin_mips_precrq_ph_w (q31, q31) 7429v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) 7430v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) 7431q31 __builtin_mips_preceq_w_phl (v2q15) 7432q31 __builtin_mips_preceq_w_phr (v2q15) 7433v2q15 __builtin_mips_precequ_ph_qbl (v4i8) 7434v2q15 __builtin_mips_precequ_ph_qbr (v4i8) 7435v2q15 __builtin_mips_precequ_ph_qbla (v4i8) 7436v2q15 __builtin_mips_precequ_ph_qbra (v4i8) 7437v2q15 __builtin_mips_preceu_ph_qbl (v4i8) 7438v2q15 __builtin_mips_preceu_ph_qbr (v4i8) 7439v2q15 __builtin_mips_preceu_ph_qbla (v4i8) 7440v2q15 __builtin_mips_preceu_ph_qbra (v4i8) 7441v4i8 __builtin_mips_shll_qb (v4i8, imm0_7) 7442v4i8 __builtin_mips_shll_qb (v4i8, i32) 7443v2q15 __builtin_mips_shll_ph (v2q15, imm0_15) 7444v2q15 __builtin_mips_shll_ph (v2q15, i32) 7445v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) 7446v2q15 __builtin_mips_shll_s_ph (v2q15, i32) 7447q31 __builtin_mips_shll_s_w (q31, imm0_31) 7448q31 __builtin_mips_shll_s_w (q31, i32) 7449v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) 7450v4i8 __builtin_mips_shrl_qb (v4i8, i32) 7451v2q15 __builtin_mips_shra_ph (v2q15, imm0_15) 7452v2q15 __builtin_mips_shra_ph (v2q15, i32) 7453v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) 7454v2q15 __builtin_mips_shra_r_ph (v2q15, i32) 7455q31 __builtin_mips_shra_r_w (q31, imm0_31) 7456q31 __builtin_mips_shra_r_w (q31, i32) 7457v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) 7458v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) 7459v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) 7460q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) 7461q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) 7462a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) 7463a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) 7464a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) 7465a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) 7466a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) 7467a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) 7468a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) 7469a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) 7470a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) 7471a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) 7472a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) 7473a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) 7474a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) 7475i32 __builtin_mips_bitrev (i32) 7476i32 __builtin_mips_insv (i32, i32) 7477v4i8 __builtin_mips_repl_qb (imm0_255) 7478v4i8 __builtin_mips_repl_qb (i32) 7479v2q15 __builtin_mips_repl_ph (imm_n512_511) 7480v2q15 __builtin_mips_repl_ph (i32) 7481void __builtin_mips_cmpu_eq_qb (v4i8, v4i8) 7482void __builtin_mips_cmpu_lt_qb (v4i8, v4i8) 7483void __builtin_mips_cmpu_le_qb (v4i8, v4i8) 7484i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) 7485i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) 7486i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) 7487void __builtin_mips_cmp_eq_ph (v2q15, v2q15) 7488void __builtin_mips_cmp_lt_ph (v2q15, v2q15) 7489void __builtin_mips_cmp_le_ph (v2q15, v2q15) 7490v4i8 __builtin_mips_pick_qb (v4i8, v4i8) 7491v2q15 __builtin_mips_pick_ph (v2q15, v2q15) 7492v2q15 __builtin_mips_packrl_ph (v2q15, v2q15) 7493i32 __builtin_mips_extr_w (a64, imm0_31) 7494i32 __builtin_mips_extr_w (a64, i32) 7495i32 __builtin_mips_extr_r_w (a64, imm0_31) 7496i32 __builtin_mips_extr_s_h (a64, i32) 7497i32 __builtin_mips_extr_rs_w (a64, imm0_31) 7498i32 __builtin_mips_extr_rs_w (a64, i32) 7499i32 __builtin_mips_extr_s_h (a64, imm0_31) 7500i32 __builtin_mips_extr_r_w (a64, i32) 7501i32 __builtin_mips_extp (a64, imm0_31) 7502i32 __builtin_mips_extp (a64, i32) 7503i32 __builtin_mips_extpdp (a64, imm0_31) 7504i32 __builtin_mips_extpdp (a64, i32) 7505a64 __builtin_mips_shilo (a64, imm_n32_31) 7506a64 __builtin_mips_shilo (a64, i32) 7507a64 __builtin_mips_mthlip (a64, i32) 7508void __builtin_mips_wrdsp (i32, imm0_63) 7509i32 __builtin_mips_rddsp (imm0_63) 7510i32 __builtin_mips_lbux (void *, i32) 7511i32 __builtin_mips_lhx (void *, i32) 7512i32 __builtin_mips_lwx (void *, i32) 7513i32 __builtin_mips_bposge32 (void) 7514@end smallexample 7515 7516@node MIPS Paired-Single Support 7517@subsection MIPS Paired-Single Support 7518 7519The MIPS64 architecture includes a number of instructions that 7520operate on pairs of single-precision floating-point values. 7521Each pair is packed into a 64-bit floating-point register, 7522with one element being designated the ``upper half'' and 7523the other being designated the ``lower half''. 7524 7525GCC supports paired-single operations using both the generic 7526vector extensions (@pxref{Vector Extensions}) and a collection of 7527MIPS-specific built-in functions. Both kinds of support are 7528enabled by the @option{-mpaired-single} command-line option. 7529 7530The vector type associated with paired-single values is usually 7531called @code{v2sf}. It can be defined in C as follows: 7532 7533@smallexample 7534typedef float v2sf __attribute__ ((vector_size (8))); 7535@end smallexample 7536 7537@code{v2sf} values are initialized in the same way as aggregates. 7538For example: 7539 7540@smallexample 7541v2sf a = @{1.5, 9.1@}; 7542v2sf b; 7543float e, f; 7544b = (v2sf) @{e, f@}; 7545@end smallexample 7546 7547@emph{Note:} The CPU's endianness determines which value is stored in 7548the upper half of a register and which value is stored in the lower half. 7549On little-endian targets, the first value is the lower one and the second 7550value is the upper one. The opposite order applies to big-endian targets. 7551For example, the code above will set the lower half of @code{a} to 7552@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. 7553 7554@menu 7555* Paired-Single Arithmetic:: 7556* Paired-Single Built-in Functions:: 7557* MIPS-3D Built-in Functions:: 7558@end menu 7559 7560@node Paired-Single Arithmetic 7561@subsubsection Paired-Single Arithmetic 7562 7563The table below lists the @code{v2sf} operations for which hardware 7564support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} 7565values and @code{x} is an integral value. 7566 7567@multitable @columnfractions .50 .50 7568@item C code @tab MIPS instruction 7569@item @code{a + b} @tab @code{add.ps} 7570@item @code{a - b} @tab @code{sub.ps} 7571@item @code{-a} @tab @code{neg.ps} 7572@item @code{a * b} @tab @code{mul.ps} 7573@item @code{a * b + c} @tab @code{madd.ps} 7574@item @code{a * b - c} @tab @code{msub.ps} 7575@item @code{-(a * b + c)} @tab @code{nmadd.ps} 7576@item @code{-(a * b - c)} @tab @code{nmsub.ps} 7577@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} 7578@end multitable 7579 7580Note that the multiply-accumulate instructions can be disabled 7581using the command-line option @code{-mno-fused-madd}. 7582 7583@node Paired-Single Built-in Functions 7584@subsubsection Paired-Single Built-in Functions 7585 7586The following paired-single functions map directly to a particular 7587MIPS instruction. Please refer to the architecture specification 7588for details on what each instruction does. 7589 7590@table @code 7591@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) 7592Pair lower lower (@code{pll.ps}). 7593 7594@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) 7595Pair upper lower (@code{pul.ps}). 7596 7597@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) 7598Pair lower upper (@code{plu.ps}). 7599 7600@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) 7601Pair upper upper (@code{puu.ps}). 7602 7603@item v2sf __builtin_mips_cvt_ps_s (float, float) 7604Convert pair to paired single (@code{cvt.ps.s}). 7605 7606@item float __builtin_mips_cvt_s_pl (v2sf) 7607Convert pair lower to single (@code{cvt.s.pl}). 7608 7609@item float __builtin_mips_cvt_s_pu (v2sf) 7610Convert pair upper to single (@code{cvt.s.pu}). 7611 7612@item v2sf __builtin_mips_abs_ps (v2sf) 7613Absolute value (@code{abs.ps}). 7614 7615@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) 7616Align variable (@code{alnv.ps}). 7617 7618@emph{Note:} The value of the third parameter must be 0 or 4 7619modulo 8, otherwise the result will be unpredictable. Please read the 7620instruction description for details. 7621@end table 7622 7623The following multi-instruction functions are also available. 7624In each case, @var{cond} can be any of the 16 floating-point conditions: 7625@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 7626@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, 7627@code{lt}, @code{nge}, @code{le} or @code{ngt}. 7628 7629@table @code 7630@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7631@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7632Conditional move based on floating point comparison (@code{c.@var{cond}.ps}, 7633@code{movt.ps}/@code{movf.ps}). 7634 7635The @code{movt} functions return the value @var{x} computed by: 7636 7637@smallexample 7638c.@var{cond}.ps @var{cc},@var{a},@var{b} 7639mov.ps @var{x},@var{c} 7640movt.ps @var{x},@var{d},@var{cc} 7641@end smallexample 7642 7643The @code{movf} functions are similar but use @code{movf.ps} instead 7644of @code{movt.ps}. 7645 7646@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7647@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7648Comparison of two paired-single values (@code{c.@var{cond}.ps}, 7649@code{bc1t}/@code{bc1f}). 7650 7651These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 7652and return either the upper or lower half of the result. For example: 7653 7654@smallexample 7655v2sf a, b; 7656if (__builtin_mips_upper_c_eq_ps (a, b)) 7657 upper_halves_are_equal (); 7658else 7659 upper_halves_are_unequal (); 7660 7661if (__builtin_mips_lower_c_eq_ps (a, b)) 7662 lower_halves_are_equal (); 7663else 7664 lower_halves_are_unequal (); 7665@end smallexample 7666@end table 7667 7668@node MIPS-3D Built-in Functions 7669@subsubsection MIPS-3D Built-in Functions 7670 7671The MIPS-3D Application-Specific Extension (ASE) includes additional 7672paired-single instructions that are designed to improve the performance 7673of 3D graphics operations. Support for these instructions is controlled 7674by the @option{-mips3d} command-line option. 7675 7676The functions listed below map directly to a particular MIPS-3D 7677instruction. Please refer to the architecture specification for 7678more details on what each instruction does. 7679 7680@table @code 7681@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) 7682Reduction add (@code{addr.ps}). 7683 7684@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) 7685Reduction multiply (@code{mulr.ps}). 7686 7687@item v2sf __builtin_mips_cvt_pw_ps (v2sf) 7688Convert paired single to paired word (@code{cvt.pw.ps}). 7689 7690@item v2sf __builtin_mips_cvt_ps_pw (v2sf) 7691Convert paired word to paired single (@code{cvt.ps.pw}). 7692 7693@item float __builtin_mips_recip1_s (float) 7694@itemx double __builtin_mips_recip1_d (double) 7695@itemx v2sf __builtin_mips_recip1_ps (v2sf) 7696Reduced precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). 7697 7698@item float __builtin_mips_recip2_s (float, float) 7699@itemx double __builtin_mips_recip2_d (double, double) 7700@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) 7701Reduced precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). 7702 7703@item float __builtin_mips_rsqrt1_s (float) 7704@itemx double __builtin_mips_rsqrt1_d (double) 7705@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) 7706Reduced precision reciprocal square root (sequence step 1) 7707(@code{rsqrt1.@var{fmt}}). 7708 7709@item float __builtin_mips_rsqrt2_s (float, float) 7710@itemx double __builtin_mips_rsqrt2_d (double, double) 7711@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) 7712Reduced precision reciprocal square root (sequence step 2) 7713(@code{rsqrt2.@var{fmt}}). 7714@end table 7715 7716The following multi-instruction functions are also available. 7717In each case, @var{cond} can be any of the 16 floating-point conditions: 7718@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 7719@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 7720@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. 7721 7722@table @code 7723@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) 7724@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) 7725Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, 7726@code{bc1t}/@code{bc1f}). 7727 7728These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} 7729or @code{cabs.@var{cond}.d} and return the result as a boolean value. 7730For example: 7731 7732@smallexample 7733float a, b; 7734if (__builtin_mips_cabs_eq_s (a, b)) 7735 true (); 7736else 7737 false (); 7738@end smallexample 7739 7740@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7741@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7742Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, 7743@code{bc1t}/@code{bc1f}). 7744 7745These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} 7746and return either the upper or lower half of the result. For example: 7747 7748@smallexample 7749v2sf a, b; 7750if (__builtin_mips_upper_cabs_eq_ps (a, b)) 7751 upper_halves_are_equal (); 7752else 7753 upper_halves_are_unequal (); 7754 7755if (__builtin_mips_lower_cabs_eq_ps (a, b)) 7756 lower_halves_are_equal (); 7757else 7758 lower_halves_are_unequal (); 7759@end smallexample 7760 7761@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7762@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7763Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, 7764@code{movt.ps}/@code{movf.ps}). 7765 7766The @code{movt} functions return the value @var{x} computed by: 7767 7768@smallexample 7769cabs.@var{cond}.ps @var{cc},@var{a},@var{b} 7770mov.ps @var{x},@var{c} 7771movt.ps @var{x},@var{d},@var{cc} 7772@end smallexample 7773 7774The @code{movf} functions are similar but use @code{movf.ps} instead 7775of @code{movt.ps}. 7776 7777@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7778@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7779@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7780@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7781Comparison of two paired-single values 7782(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 7783@code{bc1any2t}/@code{bc1any2f}). 7784 7785These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 7786or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either 7787result is true and the @code{all} forms return true if both results are true. 7788For example: 7789 7790@smallexample 7791v2sf a, b; 7792if (__builtin_mips_any_c_eq_ps (a, b)) 7793 one_is_true (); 7794else 7795 both_are_false (); 7796 7797if (__builtin_mips_all_c_eq_ps (a, b)) 7798 both_are_true (); 7799else 7800 one_is_false (); 7801@end smallexample 7802 7803@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7804@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7805@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7806@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7807Comparison of four paired-single values 7808(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 7809@code{bc1any4t}/@code{bc1any4f}). 7810 7811These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} 7812to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. 7813The @code{any} forms return true if any of the four results are true 7814and the @code{all} forms return true if all four results are true. 7815For example: 7816 7817@smallexample 7818v2sf a, b, c, d; 7819if (__builtin_mips_any_c_eq_4s (a, b, c, d)) 7820 some_are_true (); 7821else 7822 all_are_false (); 7823 7824if (__builtin_mips_all_c_eq_4s (a, b, c, d)) 7825 all_are_true (); 7826else 7827 some_are_false (); 7828@end smallexample 7829@end table 7830 7831@node PowerPC AltiVec Built-in Functions 7832@subsection PowerPC AltiVec Built-in Functions 7833 7834GCC provides an interface for the PowerPC family of processors to access 7835the AltiVec operations described in Motorola's AltiVec Programming 7836Interface Manual. The interface is made available by including 7837@code{<altivec.h>} and using @option{-maltivec} and 7838@option{-mabi=altivec}. The interface supports the following vector 7839types. 7840 7841@smallexample 7842vector unsigned char 7843vector signed char 7844vector bool char 7845 7846vector unsigned short 7847vector signed short 7848vector bool short 7849vector pixel 7850 7851vector unsigned int 7852vector signed int 7853vector bool int 7854vector float 7855@end smallexample 7856 7857GCC's implementation of the high-level language interface available from 7858C and C++ code differs from Motorola's documentation in several ways. 7859 7860@itemize @bullet 7861 7862@item 7863A vector constant is a list of constant expressions within curly braces. 7864 7865@item 7866A vector initializer requires no cast if the vector constant is of the 7867same type as the variable it is initializing. 7868 7869@item 7870If @code{signed} or @code{unsigned} is omitted, the signedness of the 7871vector type is the default signedness of the base type. The default 7872varies depending on the operating system, so a portable program should 7873always specify the signedness. 7874 7875@item 7876Compiling with @option{-maltivec} adds keywords @code{__vector}, 7877@code{__pixel}, and @code{__bool}. Macros @option{vector}, 7878@code{pixel}, and @code{bool} are defined in @code{<altivec.h>} and can 7879be undefined. 7880 7881@item 7882GCC allows using a @code{typedef} name as the type specifier for a 7883vector type. 7884 7885@item 7886For C, overloaded functions are implemented with macros so the following 7887does not work: 7888 7889@smallexample 7890 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); 7891@end smallexample 7892 7893Since @code{vec_add} is a macro, the vector constant in the example 7894is treated as four separate arguments. Wrap the entire argument in 7895parentheses for this to work. 7896@end itemize 7897 7898@emph{Note:} Only the @code{<altivec.h>} interface is supported. 7899Internally, GCC uses built-in functions to achieve the functionality in 7900the aforementioned header file, but they are not supported and are 7901subject to change without notice. 7902 7903The following interfaces are supported for the generic and specific 7904AltiVec operations and the AltiVec predicates. In cases where there 7905is a direct mapping between generic and specific operations, only the 7906generic names are shown here, although the specific operations can also 7907be used. 7908 7909Arguments that are documented as @code{const int} require literal 7910integral values within the range required for that operation. 7911 7912@smallexample 7913vector signed char vec_abs (vector signed char); 7914vector signed short vec_abs (vector signed short); 7915vector signed int vec_abs (vector signed int); 7916vector float vec_abs (vector float); 7917 7918vector signed char vec_abss (vector signed char); 7919vector signed short vec_abss (vector signed short); 7920vector signed int vec_abss (vector signed int); 7921 7922vector signed char vec_add (vector bool char, vector signed char); 7923vector signed char vec_add (vector signed char, vector bool char); 7924vector signed char vec_add (vector signed char, vector signed char); 7925vector unsigned char vec_add (vector bool char, vector unsigned char); 7926vector unsigned char vec_add (vector unsigned char, vector bool char); 7927vector unsigned char vec_add (vector unsigned char, 7928 vector unsigned char); 7929vector signed short vec_add (vector bool short, vector signed short); 7930vector signed short vec_add (vector signed short, vector bool short); 7931vector signed short vec_add (vector signed short, vector signed short); 7932vector unsigned short vec_add (vector bool short, 7933 vector unsigned short); 7934vector unsigned short vec_add (vector unsigned short, 7935 vector bool short); 7936vector unsigned short vec_add (vector unsigned short, 7937 vector unsigned short); 7938vector signed int vec_add (vector bool int, vector signed int); 7939vector signed int vec_add (vector signed int, vector bool int); 7940vector signed int vec_add (vector signed int, vector signed int); 7941vector unsigned int vec_add (vector bool int, vector unsigned int); 7942vector unsigned int vec_add (vector unsigned int, vector bool int); 7943vector unsigned int vec_add (vector unsigned int, vector unsigned int); 7944vector float vec_add (vector float, vector float); 7945 7946vector float vec_vaddfp (vector float, vector float); 7947 7948vector signed int vec_vadduwm (vector bool int, vector signed int); 7949vector signed int vec_vadduwm (vector signed int, vector bool int); 7950vector signed int vec_vadduwm (vector signed int, vector signed int); 7951vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); 7952vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); 7953vector unsigned int vec_vadduwm (vector unsigned int, 7954 vector unsigned int); 7955 7956vector signed short vec_vadduhm (vector bool short, 7957 vector signed short); 7958vector signed short vec_vadduhm (vector signed short, 7959 vector bool short); 7960vector signed short vec_vadduhm (vector signed short, 7961 vector signed short); 7962vector unsigned short vec_vadduhm (vector bool short, 7963 vector unsigned short); 7964vector unsigned short vec_vadduhm (vector unsigned short, 7965 vector bool short); 7966vector unsigned short vec_vadduhm (vector unsigned short, 7967 vector unsigned short); 7968 7969vector signed char vec_vaddubm (vector bool char, vector signed char); 7970vector signed char vec_vaddubm (vector signed char, vector bool char); 7971vector signed char vec_vaddubm (vector signed char, vector signed char); 7972vector unsigned char vec_vaddubm (vector bool char, 7973 vector unsigned char); 7974vector unsigned char vec_vaddubm (vector unsigned char, 7975 vector bool char); 7976vector unsigned char vec_vaddubm (vector unsigned char, 7977 vector unsigned char); 7978 7979vector unsigned int vec_addc (vector unsigned int, vector unsigned int); 7980 7981vector unsigned char vec_adds (vector bool char, vector unsigned char); 7982vector unsigned char vec_adds (vector unsigned char, vector bool char); 7983vector unsigned char vec_adds (vector unsigned char, 7984 vector unsigned char); 7985vector signed char vec_adds (vector bool char, vector signed char); 7986vector signed char vec_adds (vector signed char, vector bool char); 7987vector signed char vec_adds (vector signed char, vector signed char); 7988vector unsigned short vec_adds (vector bool short, 7989 vector unsigned short); 7990vector unsigned short vec_adds (vector unsigned short, 7991 vector bool short); 7992vector unsigned short vec_adds (vector unsigned short, 7993 vector unsigned short); 7994vector signed short vec_adds (vector bool short, vector signed short); 7995vector signed short vec_adds (vector signed short, vector bool short); 7996vector signed short vec_adds (vector signed short, vector signed short); 7997vector unsigned int vec_adds (vector bool int, vector unsigned int); 7998vector unsigned int vec_adds (vector unsigned int, vector bool int); 7999vector unsigned int vec_adds (vector unsigned int, vector unsigned int); 8000vector signed int vec_adds (vector bool int, vector signed int); 8001vector signed int vec_adds (vector signed int, vector bool int); 8002vector signed int vec_adds (vector signed int, vector signed int); 8003 8004vector signed int vec_vaddsws (vector bool int, vector signed int); 8005vector signed int vec_vaddsws (vector signed int, vector bool int); 8006vector signed int vec_vaddsws (vector signed int, vector signed int); 8007 8008vector unsigned int vec_vadduws (vector bool int, vector unsigned int); 8009vector unsigned int vec_vadduws (vector unsigned int, vector bool int); 8010vector unsigned int vec_vadduws (vector unsigned int, 8011 vector unsigned int); 8012 8013vector signed short vec_vaddshs (vector bool short, 8014 vector signed short); 8015vector signed short vec_vaddshs (vector signed short, 8016 vector bool short); 8017vector signed short vec_vaddshs (vector signed short, 8018 vector signed short); 8019 8020vector unsigned short vec_vadduhs (vector bool short, 8021 vector unsigned short); 8022vector unsigned short vec_vadduhs (vector unsigned short, 8023 vector bool short); 8024vector unsigned short vec_vadduhs (vector unsigned short, 8025 vector unsigned short); 8026 8027vector signed char vec_vaddsbs (vector bool char, vector signed char); 8028vector signed char vec_vaddsbs (vector signed char, vector bool char); 8029vector signed char vec_vaddsbs (vector signed char, vector signed char); 8030 8031vector unsigned char vec_vaddubs (vector bool char, 8032 vector unsigned char); 8033vector unsigned char vec_vaddubs (vector unsigned char, 8034 vector bool char); 8035vector unsigned char vec_vaddubs (vector unsigned char, 8036 vector unsigned char); 8037 8038vector float vec_and (vector float, vector float); 8039vector float vec_and (vector float, vector bool int); 8040vector float vec_and (vector bool int, vector float); 8041vector bool int vec_and (vector bool int, vector bool int); 8042vector signed int vec_and (vector bool int, vector signed int); 8043vector signed int vec_and (vector signed int, vector bool int); 8044vector signed int vec_and (vector signed int, vector signed int); 8045vector unsigned int vec_and (vector bool int, vector unsigned int); 8046vector unsigned int vec_and (vector unsigned int, vector bool int); 8047vector unsigned int vec_and (vector unsigned int, vector unsigned int); 8048vector bool short vec_and (vector bool short, vector bool short); 8049vector signed short vec_and (vector bool short, vector signed short); 8050vector signed short vec_and (vector signed short, vector bool short); 8051vector signed short vec_and (vector signed short, vector signed short); 8052vector unsigned short vec_and (vector bool short, 8053 vector unsigned short); 8054vector unsigned short vec_and (vector unsigned short, 8055 vector bool short); 8056vector unsigned short vec_and (vector unsigned short, 8057 vector unsigned short); 8058vector signed char vec_and (vector bool char, vector signed char); 8059vector bool char vec_and (vector bool char, vector bool char); 8060vector signed char vec_and (vector signed char, vector bool char); 8061vector signed char vec_and (vector signed char, vector signed char); 8062vector unsigned char vec_and (vector bool char, vector unsigned char); 8063vector unsigned char vec_and (vector unsigned char, vector bool char); 8064vector unsigned char vec_and (vector unsigned char, 8065 vector unsigned char); 8066 8067vector float vec_andc (vector float, vector float); 8068vector float vec_andc (vector float, vector bool int); 8069vector float vec_andc (vector bool int, vector float); 8070vector bool int vec_andc (vector bool int, vector bool int); 8071vector signed int vec_andc (vector bool int, vector signed int); 8072vector signed int vec_andc (vector signed int, vector bool int); 8073vector signed int vec_andc (vector signed int, vector signed int); 8074vector unsigned int vec_andc (vector bool int, vector unsigned int); 8075vector unsigned int vec_andc (vector unsigned int, vector bool int); 8076vector unsigned int vec_andc (vector unsigned int, vector unsigned int); 8077vector bool short vec_andc (vector bool short, vector bool short); 8078vector signed short vec_andc (vector bool short, vector signed short); 8079vector signed short vec_andc (vector signed short, vector bool short); 8080vector signed short vec_andc (vector signed short, vector signed short); 8081vector unsigned short vec_andc (vector bool short, 8082 vector unsigned short); 8083vector unsigned short vec_andc (vector unsigned short, 8084 vector bool short); 8085vector unsigned short vec_andc (vector unsigned short, 8086 vector unsigned short); 8087vector signed char vec_andc (vector bool char, vector signed char); 8088vector bool char vec_andc (vector bool char, vector bool char); 8089vector signed char vec_andc (vector signed char, vector bool char); 8090vector signed char vec_andc (vector signed char, vector signed char); 8091vector unsigned char vec_andc (vector bool char, vector unsigned char); 8092vector unsigned char vec_andc (vector unsigned char, vector bool char); 8093vector unsigned char vec_andc (vector unsigned char, 8094 vector unsigned char); 8095 8096vector unsigned char vec_avg (vector unsigned char, 8097 vector unsigned char); 8098vector signed char vec_avg (vector signed char, vector signed char); 8099vector unsigned short vec_avg (vector unsigned short, 8100 vector unsigned short); 8101vector signed short vec_avg (vector signed short, vector signed short); 8102vector unsigned int vec_avg (vector unsigned int, vector unsigned int); 8103vector signed int vec_avg (vector signed int, vector signed int); 8104 8105vector signed int vec_vavgsw (vector signed int, vector signed int); 8106 8107vector unsigned int vec_vavguw (vector unsigned int, 8108 vector unsigned int); 8109 8110vector signed short vec_vavgsh (vector signed short, 8111 vector signed short); 8112 8113vector unsigned short vec_vavguh (vector unsigned short, 8114 vector unsigned short); 8115 8116vector signed char vec_vavgsb (vector signed char, vector signed char); 8117 8118vector unsigned char vec_vavgub (vector unsigned char, 8119 vector unsigned char); 8120 8121vector float vec_ceil (vector float); 8122 8123vector signed int vec_cmpb (vector float, vector float); 8124 8125vector bool char vec_cmpeq (vector signed char, vector signed char); 8126vector bool char vec_cmpeq (vector unsigned char, vector unsigned char); 8127vector bool short vec_cmpeq (vector signed short, vector signed short); 8128vector bool short vec_cmpeq (vector unsigned short, 8129 vector unsigned short); 8130vector bool int vec_cmpeq (vector signed int, vector signed int); 8131vector bool int vec_cmpeq (vector unsigned int, vector unsigned int); 8132vector bool int vec_cmpeq (vector float, vector float); 8133 8134vector bool int vec_vcmpeqfp (vector float, vector float); 8135 8136vector bool int vec_vcmpequw (vector signed int, vector signed int); 8137vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); 8138 8139vector bool short vec_vcmpequh (vector signed short, 8140 vector signed short); 8141vector bool short vec_vcmpequh (vector unsigned short, 8142 vector unsigned short); 8143 8144vector bool char vec_vcmpequb (vector signed char, vector signed char); 8145vector bool char vec_vcmpequb (vector unsigned char, 8146 vector unsigned char); 8147 8148vector bool int vec_cmpge (vector float, vector float); 8149 8150vector bool char vec_cmpgt (vector unsigned char, vector unsigned char); 8151vector bool char vec_cmpgt (vector signed char, vector signed char); 8152vector bool short vec_cmpgt (vector unsigned short, 8153 vector unsigned short); 8154vector bool short vec_cmpgt (vector signed short, vector signed short); 8155vector bool int vec_cmpgt (vector unsigned int, vector unsigned int); 8156vector bool int vec_cmpgt (vector signed int, vector signed int); 8157vector bool int vec_cmpgt (vector float, vector float); 8158 8159vector bool int vec_vcmpgtfp (vector float, vector float); 8160 8161vector bool int vec_vcmpgtsw (vector signed int, vector signed int); 8162 8163vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); 8164 8165vector bool short vec_vcmpgtsh (vector signed short, 8166 vector signed short); 8167 8168vector bool short vec_vcmpgtuh (vector unsigned short, 8169 vector unsigned short); 8170 8171vector bool char vec_vcmpgtsb (vector signed char, vector signed char); 8172 8173vector bool char vec_vcmpgtub (vector unsigned char, 8174 vector unsigned char); 8175 8176vector bool int vec_cmple (vector float, vector float); 8177 8178vector bool char vec_cmplt (vector unsigned char, vector unsigned char); 8179vector bool char vec_cmplt (vector signed char, vector signed char); 8180vector bool short vec_cmplt (vector unsigned short, 8181 vector unsigned short); 8182vector bool short vec_cmplt (vector signed short, vector signed short); 8183vector bool int vec_cmplt (vector unsigned int, vector unsigned int); 8184vector bool int vec_cmplt (vector signed int, vector signed int); 8185vector bool int vec_cmplt (vector float, vector float); 8186 8187vector float vec_ctf (vector unsigned int, const int); 8188vector float vec_ctf (vector signed int, const int); 8189 8190vector float vec_vcfsx (vector signed int, const int); 8191 8192vector float vec_vcfux (vector unsigned int, const int); 8193 8194vector signed int vec_cts (vector float, const int); 8195 8196vector unsigned int vec_ctu (vector float, const int); 8197 8198void vec_dss (const int); 8199 8200void vec_dssall (void); 8201 8202void vec_dst (const vector unsigned char *, int, const int); 8203void vec_dst (const vector signed char *, int, const int); 8204void vec_dst (const vector bool char *, int, const int); 8205void vec_dst (const vector unsigned short *, int, const int); 8206void vec_dst (const vector signed short *, int, const int); 8207void vec_dst (const vector bool short *, int, const int); 8208void vec_dst (const vector pixel *, int, const int); 8209void vec_dst (const vector unsigned int *, int, const int); 8210void vec_dst (const vector signed int *, int, const int); 8211void vec_dst (const vector bool int *, int, const int); 8212void vec_dst (const vector float *, int, const int); 8213void vec_dst (const unsigned char *, int, const int); 8214void vec_dst (const signed char *, int, const int); 8215void vec_dst (const unsigned short *, int, const int); 8216void vec_dst (const short *, int, const int); 8217void vec_dst (const unsigned int *, int, const int); 8218void vec_dst (const int *, int, const int); 8219void vec_dst (const unsigned long *, int, const int); 8220void vec_dst (const long *, int, const int); 8221void vec_dst (const float *, int, const int); 8222 8223void vec_dstst (const vector unsigned char *, int, const int); 8224void vec_dstst (const vector signed char *, int, const int); 8225void vec_dstst (const vector bool char *, int, const int); 8226void vec_dstst (const vector unsigned short *, int, const int); 8227void vec_dstst (const vector signed short *, int, const int); 8228void vec_dstst (const vector bool short *, int, const int); 8229void vec_dstst (const vector pixel *, int, const int); 8230void vec_dstst (const vector unsigned int *, int, const int); 8231void vec_dstst (const vector signed int *, int, const int); 8232void vec_dstst (const vector bool int *, int, const int); 8233void vec_dstst (const vector float *, int, const int); 8234void vec_dstst (const unsigned char *, int, const int); 8235void vec_dstst (const signed char *, int, const int); 8236void vec_dstst (const unsigned short *, int, const int); 8237void vec_dstst (const short *, int, const int); 8238void vec_dstst (const unsigned int *, int, const int); 8239void vec_dstst (const int *, int, const int); 8240void vec_dstst (const unsigned long *, int, const int); 8241void vec_dstst (const long *, int, const int); 8242void vec_dstst (const float *, int, const int); 8243 8244void vec_dststt (const vector unsigned char *, int, const int); 8245void vec_dststt (const vector signed char *, int, const int); 8246void vec_dststt (const vector bool char *, int, const int); 8247void vec_dststt (const vector unsigned short *, int, const int); 8248void vec_dststt (const vector signed short *, int, const int); 8249void vec_dststt (const vector bool short *, int, const int); 8250void vec_dststt (const vector pixel *, int, const int); 8251void vec_dststt (const vector unsigned int *, int, const int); 8252void vec_dststt (const vector signed int *, int, const int); 8253void vec_dststt (const vector bool int *, int, const int); 8254void vec_dststt (const vector float *, int, const int); 8255void vec_dststt (const unsigned char *, int, const int); 8256void vec_dststt (const signed char *, int, const int); 8257void vec_dststt (const unsigned short *, int, const int); 8258void vec_dststt (const short *, int, const int); 8259void vec_dststt (const unsigned int *, int, const int); 8260void vec_dststt (const int *, int, const int); 8261void vec_dststt (const unsigned long *, int, const int); 8262void vec_dststt (const long *, int, const int); 8263void vec_dststt (const float *, int, const int); 8264 8265void vec_dstt (const vector unsigned char *, int, const int); 8266void vec_dstt (const vector signed char *, int, const int); 8267void vec_dstt (const vector bool char *, int, const int); 8268void vec_dstt (const vector unsigned short *, int, const int); 8269void vec_dstt (const vector signed short *, int, const int); 8270void vec_dstt (const vector bool short *, int, const int); 8271void vec_dstt (const vector pixel *, int, const int); 8272void vec_dstt (const vector unsigned int *, int, const int); 8273void vec_dstt (const vector signed int *, int, const int); 8274void vec_dstt (const vector bool int *, int, const int); 8275void vec_dstt (const vector float *, int, const int); 8276void vec_dstt (const unsigned char *, int, const int); 8277void vec_dstt (const signed char *, int, const int); 8278void vec_dstt (const unsigned short *, int, const int); 8279void vec_dstt (const short *, int, const int); 8280void vec_dstt (const unsigned int *, int, const int); 8281void vec_dstt (const int *, int, const int); 8282void vec_dstt (const unsigned long *, int, const int); 8283void vec_dstt (const long *, int, const int); 8284void vec_dstt (const float *, int, const int); 8285 8286vector float vec_expte (vector float); 8287 8288vector float vec_floor (vector float); 8289 8290vector float vec_ld (int, const vector float *); 8291vector float vec_ld (int, const float *); 8292vector bool int vec_ld (int, const vector bool int *); 8293vector signed int vec_ld (int, const vector signed int *); 8294vector signed int vec_ld (int, const int *); 8295vector signed int vec_ld (int, const long *); 8296vector unsigned int vec_ld (int, const vector unsigned int *); 8297vector unsigned int vec_ld (int, const unsigned int *); 8298vector unsigned int vec_ld (int, const unsigned long *); 8299vector bool short vec_ld (int, const vector bool short *); 8300vector pixel vec_ld (int, const vector pixel *); 8301vector signed short vec_ld (int, const vector signed short *); 8302vector signed short vec_ld (int, const short *); 8303vector unsigned short vec_ld (int, const vector unsigned short *); 8304vector unsigned short vec_ld (int, const unsigned short *); 8305vector bool char vec_ld (int, const vector bool char *); 8306vector signed char vec_ld (int, const vector signed char *); 8307vector signed char vec_ld (int, const signed char *); 8308vector unsigned char vec_ld (int, const vector unsigned char *); 8309vector unsigned char vec_ld (int, const unsigned char *); 8310 8311vector signed char vec_lde (int, const signed char *); 8312vector unsigned char vec_lde (int, const unsigned char *); 8313vector signed short vec_lde (int, const short *); 8314vector unsigned short vec_lde (int, const unsigned short *); 8315vector float vec_lde (int, const float *); 8316vector signed int vec_lde (int, const int *); 8317vector unsigned int vec_lde (int, const unsigned int *); 8318vector signed int vec_lde (int, const long *); 8319vector unsigned int vec_lde (int, const unsigned long *); 8320 8321vector float vec_lvewx (int, float *); 8322vector signed int vec_lvewx (int, int *); 8323vector unsigned int vec_lvewx (int, unsigned int *); 8324vector signed int vec_lvewx (int, long *); 8325vector unsigned int vec_lvewx (int, unsigned long *); 8326 8327vector signed short vec_lvehx (int, short *); 8328vector unsigned short vec_lvehx (int, unsigned short *); 8329 8330vector signed char vec_lvebx (int, char *); 8331vector unsigned char vec_lvebx (int, unsigned char *); 8332 8333vector float vec_ldl (int, const vector float *); 8334vector float vec_ldl (int, const float *); 8335vector bool int vec_ldl (int, const vector bool int *); 8336vector signed int vec_ldl (int, const vector signed int *); 8337vector signed int vec_ldl (int, const int *); 8338vector signed int vec_ldl (int, const long *); 8339vector unsigned int vec_ldl (int, const vector unsigned int *); 8340vector unsigned int vec_ldl (int, const unsigned int *); 8341vector unsigned int vec_ldl (int, const unsigned long *); 8342vector bool short vec_ldl (int, const vector bool short *); 8343vector pixel vec_ldl (int, const vector pixel *); 8344vector signed short vec_ldl (int, const vector signed short *); 8345vector signed short vec_ldl (int, const short *); 8346vector unsigned short vec_ldl (int, const vector unsigned short *); 8347vector unsigned short vec_ldl (int, const unsigned short *); 8348vector bool char vec_ldl (int, const vector bool char *); 8349vector signed char vec_ldl (int, const vector signed char *); 8350vector signed char vec_ldl (int, const signed char *); 8351vector unsigned char vec_ldl (int, const vector unsigned char *); 8352vector unsigned char vec_ldl (int, const unsigned char *); 8353 8354vector float vec_loge (vector float); 8355 8356vector unsigned char vec_lvsl (int, const volatile unsigned char *); 8357vector unsigned char vec_lvsl (int, const volatile signed char *); 8358vector unsigned char vec_lvsl (int, const volatile unsigned short *); 8359vector unsigned char vec_lvsl (int, const volatile short *); 8360vector unsigned char vec_lvsl (int, const volatile unsigned int *); 8361vector unsigned char vec_lvsl (int, const volatile int *); 8362vector unsigned char vec_lvsl (int, const volatile unsigned long *); 8363vector unsigned char vec_lvsl (int, const volatile long *); 8364vector unsigned char vec_lvsl (int, const volatile float *); 8365 8366vector unsigned char vec_lvsr (int, const volatile unsigned char *); 8367vector unsigned char vec_lvsr (int, const volatile signed char *); 8368vector unsigned char vec_lvsr (int, const volatile unsigned short *); 8369vector unsigned char vec_lvsr (int, const volatile short *); 8370vector unsigned char vec_lvsr (int, const volatile unsigned int *); 8371vector unsigned char vec_lvsr (int, const volatile int *); 8372vector unsigned char vec_lvsr (int, const volatile unsigned long *); 8373vector unsigned char vec_lvsr (int, const volatile long *); 8374vector unsigned char vec_lvsr (int, const volatile float *); 8375 8376vector float vec_madd (vector float, vector float, vector float); 8377 8378vector signed short vec_madds (vector signed short, 8379 vector signed short, 8380 vector signed short); 8381 8382vector unsigned char vec_max (vector bool char, vector unsigned char); 8383vector unsigned char vec_max (vector unsigned char, vector bool char); 8384vector unsigned char vec_max (vector unsigned char, 8385 vector unsigned char); 8386vector signed char vec_max (vector bool char, vector signed char); 8387vector signed char vec_max (vector signed char, vector bool char); 8388vector signed char vec_max (vector signed char, vector signed char); 8389vector unsigned short vec_max (vector bool short, 8390 vector unsigned short); 8391vector unsigned short vec_max (vector unsigned short, 8392 vector bool short); 8393vector unsigned short vec_max (vector unsigned short, 8394 vector unsigned short); 8395vector signed short vec_max (vector bool short, vector signed short); 8396vector signed short vec_max (vector signed short, vector bool short); 8397vector signed short vec_max (vector signed short, vector signed short); 8398vector unsigned int vec_max (vector bool int, vector unsigned int); 8399vector unsigned int vec_max (vector unsigned int, vector bool int); 8400vector unsigned int vec_max (vector unsigned int, vector unsigned int); 8401vector signed int vec_max (vector bool int, vector signed int); 8402vector signed int vec_max (vector signed int, vector bool int); 8403vector signed int vec_max (vector signed int, vector signed int); 8404vector float vec_max (vector float, vector float); 8405 8406vector float vec_vmaxfp (vector float, vector float); 8407 8408vector signed int vec_vmaxsw (vector bool int, vector signed int); 8409vector signed int vec_vmaxsw (vector signed int, vector bool int); 8410vector signed int vec_vmaxsw (vector signed int, vector signed int); 8411 8412vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); 8413vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); 8414vector unsigned int vec_vmaxuw (vector unsigned int, 8415 vector unsigned int); 8416 8417vector signed short vec_vmaxsh (vector bool short, vector signed short); 8418vector signed short vec_vmaxsh (vector signed short, vector bool short); 8419vector signed short vec_vmaxsh (vector signed short, 8420 vector signed short); 8421 8422vector unsigned short vec_vmaxuh (vector bool short, 8423 vector unsigned short); 8424vector unsigned short vec_vmaxuh (vector unsigned short, 8425 vector bool short); 8426vector unsigned short vec_vmaxuh (vector unsigned short, 8427 vector unsigned short); 8428 8429vector signed char vec_vmaxsb (vector bool char, vector signed char); 8430vector signed char vec_vmaxsb (vector signed char, vector bool char); 8431vector signed char vec_vmaxsb (vector signed char, vector signed char); 8432 8433vector unsigned char vec_vmaxub (vector bool char, 8434 vector unsigned char); 8435vector unsigned char vec_vmaxub (vector unsigned char, 8436 vector bool char); 8437vector unsigned char vec_vmaxub (vector unsigned char, 8438 vector unsigned char); 8439 8440vector bool char vec_mergeh (vector bool char, vector bool char); 8441vector signed char vec_mergeh (vector signed char, vector signed char); 8442vector unsigned char vec_mergeh (vector unsigned char, 8443 vector unsigned char); 8444vector bool short vec_mergeh (vector bool short, vector bool short); 8445vector pixel vec_mergeh (vector pixel, vector pixel); 8446vector signed short vec_mergeh (vector signed short, 8447 vector signed short); 8448vector unsigned short vec_mergeh (vector unsigned short, 8449 vector unsigned short); 8450vector float vec_mergeh (vector float, vector float); 8451vector bool int vec_mergeh (vector bool int, vector bool int); 8452vector signed int vec_mergeh (vector signed int, vector signed int); 8453vector unsigned int vec_mergeh (vector unsigned int, 8454 vector unsigned int); 8455 8456vector float vec_vmrghw (vector float, vector float); 8457vector bool int vec_vmrghw (vector bool int, vector bool int); 8458vector signed int vec_vmrghw (vector signed int, vector signed int); 8459vector unsigned int vec_vmrghw (vector unsigned int, 8460 vector unsigned int); 8461 8462vector bool short vec_vmrghh (vector bool short, vector bool short); 8463vector signed short vec_vmrghh (vector signed short, 8464 vector signed short); 8465vector unsigned short vec_vmrghh (vector unsigned short, 8466 vector unsigned short); 8467vector pixel vec_vmrghh (vector pixel, vector pixel); 8468 8469vector bool char vec_vmrghb (vector bool char, vector bool char); 8470vector signed char vec_vmrghb (vector signed char, vector signed char); 8471vector unsigned char vec_vmrghb (vector unsigned char, 8472 vector unsigned char); 8473 8474vector bool char vec_mergel (vector bool char, vector bool char); 8475vector signed char vec_mergel (vector signed char, vector signed char); 8476vector unsigned char vec_mergel (vector unsigned char, 8477 vector unsigned char); 8478vector bool short vec_mergel (vector bool short, vector bool short); 8479vector pixel vec_mergel (vector pixel, vector pixel); 8480vector signed short vec_mergel (vector signed short, 8481 vector signed short); 8482vector unsigned short vec_mergel (vector unsigned short, 8483 vector unsigned short); 8484vector float vec_mergel (vector float, vector float); 8485vector bool int vec_mergel (vector bool int, vector bool int); 8486vector signed int vec_mergel (vector signed int, vector signed int); 8487vector unsigned int vec_mergel (vector unsigned int, 8488 vector unsigned int); 8489 8490vector float vec_vmrglw (vector float, vector float); 8491vector signed int vec_vmrglw (vector signed int, vector signed int); 8492vector unsigned int vec_vmrglw (vector unsigned int, 8493 vector unsigned int); 8494vector bool int vec_vmrglw (vector bool int, vector bool int); 8495 8496vector bool short vec_vmrglh (vector bool short, vector bool short); 8497vector signed short vec_vmrglh (vector signed short, 8498 vector signed short); 8499vector unsigned short vec_vmrglh (vector unsigned short, 8500 vector unsigned short); 8501vector pixel vec_vmrglh (vector pixel, vector pixel); 8502 8503vector bool char vec_vmrglb (vector bool char, vector bool char); 8504vector signed char vec_vmrglb (vector signed char, vector signed char); 8505vector unsigned char vec_vmrglb (vector unsigned char, 8506 vector unsigned char); 8507 8508vector unsigned short vec_mfvscr (void); 8509 8510vector unsigned char vec_min (vector bool char, vector unsigned char); 8511vector unsigned char vec_min (vector unsigned char, vector bool char); 8512vector unsigned char vec_min (vector unsigned char, 8513 vector unsigned char); 8514vector signed char vec_min (vector bool char, vector signed char); 8515vector signed char vec_min (vector signed char, vector bool char); 8516vector signed char vec_min (vector signed char, vector signed char); 8517vector unsigned short vec_min (vector bool short, 8518 vector unsigned short); 8519vector unsigned short vec_min (vector unsigned short, 8520 vector bool short); 8521vector unsigned short vec_min (vector unsigned short, 8522 vector unsigned short); 8523vector signed short vec_min (vector bool short, vector signed short); 8524vector signed short vec_min (vector signed short, vector bool short); 8525vector signed short vec_min (vector signed short, vector signed short); 8526vector unsigned int vec_min (vector bool int, vector unsigned int); 8527vector unsigned int vec_min (vector unsigned int, vector bool int); 8528vector unsigned int vec_min (vector unsigned int, vector unsigned int); 8529vector signed int vec_min (vector bool int, vector signed int); 8530vector signed int vec_min (vector signed int, vector bool int); 8531vector signed int vec_min (vector signed int, vector signed int); 8532vector float vec_min (vector float, vector float); 8533 8534vector float vec_vminfp (vector float, vector float); 8535 8536vector signed int vec_vminsw (vector bool int, vector signed int); 8537vector signed int vec_vminsw (vector signed int, vector bool int); 8538vector signed int vec_vminsw (vector signed int, vector signed int); 8539 8540vector unsigned int vec_vminuw (vector bool int, vector unsigned int); 8541vector unsigned int vec_vminuw (vector unsigned int, vector bool int); 8542vector unsigned int vec_vminuw (vector unsigned int, 8543 vector unsigned int); 8544 8545vector signed short vec_vminsh (vector bool short, vector signed short); 8546vector signed short vec_vminsh (vector signed short, vector bool short); 8547vector signed short vec_vminsh (vector signed short, 8548 vector signed short); 8549 8550vector unsigned short vec_vminuh (vector bool short, 8551 vector unsigned short); 8552vector unsigned short vec_vminuh (vector unsigned short, 8553 vector bool short); 8554vector unsigned short vec_vminuh (vector unsigned short, 8555 vector unsigned short); 8556 8557vector signed char vec_vminsb (vector bool char, vector signed char); 8558vector signed char vec_vminsb (vector signed char, vector bool char); 8559vector signed char vec_vminsb (vector signed char, vector signed char); 8560 8561vector unsigned char vec_vminub (vector bool char, 8562 vector unsigned char); 8563vector unsigned char vec_vminub (vector unsigned char, 8564 vector bool char); 8565vector unsigned char vec_vminub (vector unsigned char, 8566 vector unsigned char); 8567 8568vector signed short vec_mladd (vector signed short, 8569 vector signed short, 8570 vector signed short); 8571vector signed short vec_mladd (vector signed short, 8572 vector unsigned short, 8573 vector unsigned short); 8574vector signed short vec_mladd (vector unsigned short, 8575 vector signed short, 8576 vector signed short); 8577vector unsigned short vec_mladd (vector unsigned short, 8578 vector unsigned short, 8579 vector unsigned short); 8580 8581vector signed short vec_mradds (vector signed short, 8582 vector signed short, 8583 vector signed short); 8584 8585vector unsigned int vec_msum (vector unsigned char, 8586 vector unsigned char, 8587 vector unsigned int); 8588vector signed int vec_msum (vector signed char, 8589 vector unsigned char, 8590 vector signed int); 8591vector unsigned int vec_msum (vector unsigned short, 8592 vector unsigned short, 8593 vector unsigned int); 8594vector signed int vec_msum (vector signed short, 8595 vector signed short, 8596 vector signed int); 8597 8598vector signed int vec_vmsumshm (vector signed short, 8599 vector signed short, 8600 vector signed int); 8601 8602vector unsigned int vec_vmsumuhm (vector unsigned short, 8603 vector unsigned short, 8604 vector unsigned int); 8605 8606vector signed int vec_vmsummbm (vector signed char, 8607 vector unsigned char, 8608 vector signed int); 8609 8610vector unsigned int vec_vmsumubm (vector unsigned char, 8611 vector unsigned char, 8612 vector unsigned int); 8613 8614vector unsigned int vec_msums (vector unsigned short, 8615 vector unsigned short, 8616 vector unsigned int); 8617vector signed int vec_msums (vector signed short, 8618 vector signed short, 8619 vector signed int); 8620 8621vector signed int vec_vmsumshs (vector signed short, 8622 vector signed short, 8623 vector signed int); 8624 8625vector unsigned int vec_vmsumuhs (vector unsigned short, 8626 vector unsigned short, 8627 vector unsigned int); 8628 8629void vec_mtvscr (vector signed int); 8630void vec_mtvscr (vector unsigned int); 8631void vec_mtvscr (vector bool int); 8632void vec_mtvscr (vector signed short); 8633void vec_mtvscr (vector unsigned short); 8634void vec_mtvscr (vector bool short); 8635void vec_mtvscr (vector pixel); 8636void vec_mtvscr (vector signed char); 8637void vec_mtvscr (vector unsigned char); 8638void vec_mtvscr (vector bool char); 8639 8640vector unsigned short vec_mule (vector unsigned char, 8641 vector unsigned char); 8642vector signed short vec_mule (vector signed char, 8643 vector signed char); 8644vector unsigned int vec_mule (vector unsigned short, 8645 vector unsigned short); 8646vector signed int vec_mule (vector signed short, vector signed short); 8647 8648vector signed int vec_vmulesh (vector signed short, 8649 vector signed short); 8650 8651vector unsigned int vec_vmuleuh (vector unsigned short, 8652 vector unsigned short); 8653 8654vector signed short vec_vmulesb (vector signed char, 8655 vector signed char); 8656 8657vector unsigned short vec_vmuleub (vector unsigned char, 8658 vector unsigned char); 8659 8660vector unsigned short vec_mulo (vector unsigned char, 8661 vector unsigned char); 8662vector signed short vec_mulo (vector signed char, vector signed char); 8663vector unsigned int vec_mulo (vector unsigned short, 8664 vector unsigned short); 8665vector signed int vec_mulo (vector signed short, vector signed short); 8666 8667vector signed int vec_vmulosh (vector signed short, 8668 vector signed short); 8669 8670vector unsigned int vec_vmulouh (vector unsigned short, 8671 vector unsigned short); 8672 8673vector signed short vec_vmulosb (vector signed char, 8674 vector signed char); 8675 8676vector unsigned short vec_vmuloub (vector unsigned char, 8677 vector unsigned char); 8678 8679vector float vec_nmsub (vector float, vector float, vector float); 8680 8681vector float vec_nor (vector float, vector float); 8682vector signed int vec_nor (vector signed int, vector signed int); 8683vector unsigned int vec_nor (vector unsigned int, vector unsigned int); 8684vector bool int vec_nor (vector bool int, vector bool int); 8685vector signed short vec_nor (vector signed short, vector signed short); 8686vector unsigned short vec_nor (vector unsigned short, 8687 vector unsigned short); 8688vector bool short vec_nor (vector bool short, vector bool short); 8689vector signed char vec_nor (vector signed char, vector signed char); 8690vector unsigned char vec_nor (vector unsigned char, 8691 vector unsigned char); 8692vector bool char vec_nor (vector bool char, vector bool char); 8693 8694vector float vec_or (vector float, vector float); 8695vector float vec_or (vector float, vector bool int); 8696vector float vec_or (vector bool int, vector float); 8697vector bool int vec_or (vector bool int, vector bool int); 8698vector signed int vec_or (vector bool int, vector signed int); 8699vector signed int vec_or (vector signed int, vector bool int); 8700vector signed int vec_or (vector signed int, vector signed int); 8701vector unsigned int vec_or (vector bool int, vector unsigned int); 8702vector unsigned int vec_or (vector unsigned int, vector bool int); 8703vector unsigned int vec_or (vector unsigned int, vector unsigned int); 8704vector bool short vec_or (vector bool short, vector bool short); 8705vector signed short vec_or (vector bool short, vector signed short); 8706vector signed short vec_or (vector signed short, vector bool short); 8707vector signed short vec_or (vector signed short, vector signed short); 8708vector unsigned short vec_or (vector bool short, vector unsigned short); 8709vector unsigned short vec_or (vector unsigned short, vector bool short); 8710vector unsigned short vec_or (vector unsigned short, 8711 vector unsigned short); 8712vector signed char vec_or (vector bool char, vector signed char); 8713vector bool char vec_or (vector bool char, vector bool char); 8714vector signed char vec_or (vector signed char, vector bool char); 8715vector signed char vec_or (vector signed char, vector signed char); 8716vector unsigned char vec_or (vector bool char, vector unsigned char); 8717vector unsigned char vec_or (vector unsigned char, vector bool char); 8718vector unsigned char vec_or (vector unsigned char, 8719 vector unsigned char); 8720 8721vector signed char vec_pack (vector signed short, vector signed short); 8722vector unsigned char vec_pack (vector unsigned short, 8723 vector unsigned short); 8724vector bool char vec_pack (vector bool short, vector bool short); 8725vector signed short vec_pack (vector signed int, vector signed int); 8726vector unsigned short vec_pack (vector unsigned int, 8727 vector unsigned int); 8728vector bool short vec_pack (vector bool int, vector bool int); 8729 8730vector bool short vec_vpkuwum (vector bool int, vector bool int); 8731vector signed short vec_vpkuwum (vector signed int, vector signed int); 8732vector unsigned short vec_vpkuwum (vector unsigned int, 8733 vector unsigned int); 8734 8735vector bool char vec_vpkuhum (vector bool short, vector bool short); 8736vector signed char vec_vpkuhum (vector signed short, 8737 vector signed short); 8738vector unsigned char vec_vpkuhum (vector unsigned short, 8739 vector unsigned short); 8740 8741vector pixel vec_packpx (vector unsigned int, vector unsigned int); 8742 8743vector unsigned char vec_packs (vector unsigned short, 8744 vector unsigned short); 8745vector signed char vec_packs (vector signed short, vector signed short); 8746vector unsigned short vec_packs (vector unsigned int, 8747 vector unsigned int); 8748vector signed short vec_packs (vector signed int, vector signed int); 8749 8750vector signed short vec_vpkswss (vector signed int, vector signed int); 8751 8752vector unsigned short vec_vpkuwus (vector unsigned int, 8753 vector unsigned int); 8754 8755vector signed char vec_vpkshss (vector signed short, 8756 vector signed short); 8757 8758vector unsigned char vec_vpkuhus (vector unsigned short, 8759 vector unsigned short); 8760 8761vector unsigned char vec_packsu (vector unsigned short, 8762 vector unsigned short); 8763vector unsigned char vec_packsu (vector signed short, 8764 vector signed short); 8765vector unsigned short vec_packsu (vector unsigned int, 8766 vector unsigned int); 8767vector unsigned short vec_packsu (vector signed int, vector signed int); 8768 8769vector unsigned short vec_vpkswus (vector signed int, 8770 vector signed int); 8771 8772vector unsigned char vec_vpkshus (vector signed short, 8773 vector signed short); 8774 8775vector float vec_perm (vector float, 8776 vector float, 8777 vector unsigned char); 8778vector signed int vec_perm (vector signed int, 8779 vector signed int, 8780 vector unsigned char); 8781vector unsigned int vec_perm (vector unsigned int, 8782 vector unsigned int, 8783 vector unsigned char); 8784vector bool int vec_perm (vector bool int, 8785 vector bool int, 8786 vector unsigned char); 8787vector signed short vec_perm (vector signed short, 8788 vector signed short, 8789 vector unsigned char); 8790vector unsigned short vec_perm (vector unsigned short, 8791 vector unsigned short, 8792 vector unsigned char); 8793vector bool short vec_perm (vector bool short, 8794 vector bool short, 8795 vector unsigned char); 8796vector pixel vec_perm (vector pixel, 8797 vector pixel, 8798 vector unsigned char); 8799vector signed char vec_perm (vector signed char, 8800 vector signed char, 8801 vector unsigned char); 8802vector unsigned char vec_perm (vector unsigned char, 8803 vector unsigned char, 8804 vector unsigned char); 8805vector bool char vec_perm (vector bool char, 8806 vector bool char, 8807 vector unsigned char); 8808 8809vector float vec_re (vector float); 8810 8811vector signed char vec_rl (vector signed char, 8812 vector unsigned char); 8813vector unsigned char vec_rl (vector unsigned char, 8814 vector unsigned char); 8815vector signed short vec_rl (vector signed short, vector unsigned short); 8816vector unsigned short vec_rl (vector unsigned short, 8817 vector unsigned short); 8818vector signed int vec_rl (vector signed int, vector unsigned int); 8819vector unsigned int vec_rl (vector unsigned int, vector unsigned int); 8820 8821vector signed int vec_vrlw (vector signed int, vector unsigned int); 8822vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); 8823 8824vector signed short vec_vrlh (vector signed short, 8825 vector unsigned short); 8826vector unsigned short vec_vrlh (vector unsigned short, 8827 vector unsigned short); 8828 8829vector signed char vec_vrlb (vector signed char, vector unsigned char); 8830vector unsigned char vec_vrlb (vector unsigned char, 8831 vector unsigned char); 8832 8833vector float vec_round (vector float); 8834 8835vector float vec_rsqrte (vector float); 8836 8837vector float vec_sel (vector float, vector float, vector bool int); 8838vector float vec_sel (vector float, vector float, vector unsigned int); 8839vector signed int vec_sel (vector signed int, 8840 vector signed int, 8841 vector bool int); 8842vector signed int vec_sel (vector signed int, 8843 vector signed int, 8844 vector unsigned int); 8845vector unsigned int vec_sel (vector unsigned int, 8846 vector unsigned int, 8847 vector bool int); 8848vector unsigned int vec_sel (vector unsigned int, 8849 vector unsigned int, 8850 vector unsigned int); 8851vector bool int vec_sel (vector bool int, 8852 vector bool int, 8853 vector bool int); 8854vector bool int vec_sel (vector bool int, 8855 vector bool int, 8856 vector unsigned int); 8857vector signed short vec_sel (vector signed short, 8858 vector signed short, 8859 vector bool short); 8860vector signed short vec_sel (vector signed short, 8861 vector signed short, 8862 vector unsigned short); 8863vector unsigned short vec_sel (vector unsigned short, 8864 vector unsigned short, 8865 vector bool short); 8866vector unsigned short vec_sel (vector unsigned short, 8867 vector unsigned short, 8868 vector unsigned short); 8869vector bool short vec_sel (vector bool short, 8870 vector bool short, 8871 vector bool short); 8872vector bool short vec_sel (vector bool short, 8873 vector bool short, 8874 vector unsigned short); 8875vector signed char vec_sel (vector signed char, 8876 vector signed char, 8877 vector bool char); 8878vector signed char vec_sel (vector signed char, 8879 vector signed char, 8880 vector unsigned char); 8881vector unsigned char vec_sel (vector unsigned char, 8882 vector unsigned char, 8883 vector bool char); 8884vector unsigned char vec_sel (vector unsigned char, 8885 vector unsigned char, 8886 vector unsigned char); 8887vector bool char vec_sel (vector bool char, 8888 vector bool char, 8889 vector bool char); 8890vector bool char vec_sel (vector bool char, 8891 vector bool char, 8892 vector unsigned char); 8893 8894vector signed char vec_sl (vector signed char, 8895 vector unsigned char); 8896vector unsigned char vec_sl (vector unsigned char, 8897 vector unsigned char); 8898vector signed short vec_sl (vector signed short, vector unsigned short); 8899vector unsigned short vec_sl (vector unsigned short, 8900 vector unsigned short); 8901vector signed int vec_sl (vector signed int, vector unsigned int); 8902vector unsigned int vec_sl (vector unsigned int, vector unsigned int); 8903 8904vector signed int vec_vslw (vector signed int, vector unsigned int); 8905vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); 8906 8907vector signed short vec_vslh (vector signed short, 8908 vector unsigned short); 8909vector unsigned short vec_vslh (vector unsigned short, 8910 vector unsigned short); 8911 8912vector signed char vec_vslb (vector signed char, vector unsigned char); 8913vector unsigned char vec_vslb (vector unsigned char, 8914 vector unsigned char); 8915 8916vector float vec_sld (vector float, vector float, const int); 8917vector signed int vec_sld (vector signed int, 8918 vector signed int, 8919 const int); 8920vector unsigned int vec_sld (vector unsigned int, 8921 vector unsigned int, 8922 const int); 8923vector bool int vec_sld (vector bool int, 8924 vector bool int, 8925 const int); 8926vector signed short vec_sld (vector signed short, 8927 vector signed short, 8928 const int); 8929vector unsigned short vec_sld (vector unsigned short, 8930 vector unsigned short, 8931 const int); 8932vector bool short vec_sld (vector bool short, 8933 vector bool short, 8934 const int); 8935vector pixel vec_sld (vector pixel, 8936 vector pixel, 8937 const int); 8938vector signed char vec_sld (vector signed char, 8939 vector signed char, 8940 const int); 8941vector unsigned char vec_sld (vector unsigned char, 8942 vector unsigned char, 8943 const int); 8944vector bool char vec_sld (vector bool char, 8945 vector bool char, 8946 const int); 8947 8948vector signed int vec_sll (vector signed int, 8949 vector unsigned int); 8950vector signed int vec_sll (vector signed int, 8951 vector unsigned short); 8952vector signed int vec_sll (vector signed int, 8953 vector unsigned char); 8954vector unsigned int vec_sll (vector unsigned int, 8955 vector unsigned int); 8956vector unsigned int vec_sll (vector unsigned int, 8957 vector unsigned short); 8958vector unsigned int vec_sll (vector unsigned int, 8959 vector unsigned char); 8960vector bool int vec_sll (vector bool int, 8961 vector unsigned int); 8962vector bool int vec_sll (vector bool int, 8963 vector unsigned short); 8964vector bool int vec_sll (vector bool int, 8965 vector unsigned char); 8966vector signed short vec_sll (vector signed short, 8967 vector unsigned int); 8968vector signed short vec_sll (vector signed short, 8969 vector unsigned short); 8970vector signed short vec_sll (vector signed short, 8971 vector unsigned char); 8972vector unsigned short vec_sll (vector unsigned short, 8973 vector unsigned int); 8974vector unsigned short vec_sll (vector unsigned short, 8975 vector unsigned short); 8976vector unsigned short vec_sll (vector unsigned short, 8977 vector unsigned char); 8978vector bool short vec_sll (vector bool short, vector unsigned int); 8979vector bool short vec_sll (vector bool short, vector unsigned short); 8980vector bool short vec_sll (vector bool short, vector unsigned char); 8981vector pixel vec_sll (vector pixel, vector unsigned int); 8982vector pixel vec_sll (vector pixel, vector unsigned short); 8983vector pixel vec_sll (vector pixel, vector unsigned char); 8984vector signed char vec_sll (vector signed char, vector unsigned int); 8985vector signed char vec_sll (vector signed char, vector unsigned short); 8986vector signed char vec_sll (vector signed char, vector unsigned char); 8987vector unsigned char vec_sll (vector unsigned char, 8988 vector unsigned int); 8989vector unsigned char vec_sll (vector unsigned char, 8990 vector unsigned short); 8991vector unsigned char vec_sll (vector unsigned char, 8992 vector unsigned char); 8993vector bool char vec_sll (vector bool char, vector unsigned int); 8994vector bool char vec_sll (vector bool char, vector unsigned short); 8995vector bool char vec_sll (vector bool char, vector unsigned char); 8996 8997vector float vec_slo (vector float, vector signed char); 8998vector float vec_slo (vector float, vector unsigned char); 8999vector signed int vec_slo (vector signed int, vector signed char); 9000vector signed int vec_slo (vector signed int, vector unsigned char); 9001vector unsigned int vec_slo (vector unsigned int, vector signed char); 9002vector unsigned int vec_slo (vector unsigned int, vector unsigned char); 9003vector signed short vec_slo (vector signed short, vector signed char); 9004vector signed short vec_slo (vector signed short, vector unsigned char); 9005vector unsigned short vec_slo (vector unsigned short, 9006 vector signed char); 9007vector unsigned short vec_slo (vector unsigned short, 9008 vector unsigned char); 9009vector pixel vec_slo (vector pixel, vector signed char); 9010vector pixel vec_slo (vector pixel, vector unsigned char); 9011vector signed char vec_slo (vector signed char, vector signed char); 9012vector signed char vec_slo (vector signed char, vector unsigned char); 9013vector unsigned char vec_slo (vector unsigned char, vector signed char); 9014vector unsigned char vec_slo (vector unsigned char, 9015 vector unsigned char); 9016 9017vector signed char vec_splat (vector signed char, const int); 9018vector unsigned char vec_splat (vector unsigned char, const int); 9019vector bool char vec_splat (vector bool char, const int); 9020vector signed short vec_splat (vector signed short, const int); 9021vector unsigned short vec_splat (vector unsigned short, const int); 9022vector bool short vec_splat (vector bool short, const int); 9023vector pixel vec_splat (vector pixel, const int); 9024vector float vec_splat (vector float, const int); 9025vector signed int vec_splat (vector signed int, const int); 9026vector unsigned int vec_splat (vector unsigned int, const int); 9027vector bool int vec_splat (vector bool int, const int); 9028 9029vector float vec_vspltw (vector float, const int); 9030vector signed int vec_vspltw (vector signed int, const int); 9031vector unsigned int vec_vspltw (vector unsigned int, const int); 9032vector bool int vec_vspltw (vector bool int, const int); 9033 9034vector bool short vec_vsplth (vector bool short, const int); 9035vector signed short vec_vsplth (vector signed short, const int); 9036vector unsigned short vec_vsplth (vector unsigned short, const int); 9037vector pixel vec_vsplth (vector pixel, const int); 9038 9039vector signed char vec_vspltb (vector signed char, const int); 9040vector unsigned char vec_vspltb (vector unsigned char, const int); 9041vector bool char vec_vspltb (vector bool char, const int); 9042 9043vector signed char vec_splat_s8 (const int); 9044 9045vector signed short vec_splat_s16 (const int); 9046 9047vector signed int vec_splat_s32 (const int); 9048 9049vector unsigned char vec_splat_u8 (const int); 9050 9051vector unsigned short vec_splat_u16 (const int); 9052 9053vector unsigned int vec_splat_u32 (const int); 9054 9055vector signed char vec_sr (vector signed char, vector unsigned char); 9056vector unsigned char vec_sr (vector unsigned char, 9057 vector unsigned char); 9058vector signed short vec_sr (vector signed short, 9059 vector unsigned short); 9060vector unsigned short vec_sr (vector unsigned short, 9061 vector unsigned short); 9062vector signed int vec_sr (vector signed int, vector unsigned int); 9063vector unsigned int vec_sr (vector unsigned int, vector unsigned int); 9064 9065vector signed int vec_vsrw (vector signed int, vector unsigned int); 9066vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); 9067 9068vector signed short vec_vsrh (vector signed short, 9069 vector unsigned short); 9070vector unsigned short vec_vsrh (vector unsigned short, 9071 vector unsigned short); 9072 9073vector signed char vec_vsrb (vector signed char, vector unsigned char); 9074vector unsigned char vec_vsrb (vector unsigned char, 9075 vector unsigned char); 9076 9077vector signed char vec_sra (vector signed char, vector unsigned char); 9078vector unsigned char vec_sra (vector unsigned char, 9079 vector unsigned char); 9080vector signed short vec_sra (vector signed short, 9081 vector unsigned short); 9082vector unsigned short vec_sra (vector unsigned short, 9083 vector unsigned short); 9084vector signed int vec_sra (vector signed int, vector unsigned int); 9085vector unsigned int vec_sra (vector unsigned int, vector unsigned int); 9086 9087vector signed int vec_vsraw (vector signed int, vector unsigned int); 9088vector unsigned int vec_vsraw (vector unsigned int, 9089 vector unsigned int); 9090 9091vector signed short vec_vsrah (vector signed short, 9092 vector unsigned short); 9093vector unsigned short vec_vsrah (vector unsigned short, 9094 vector unsigned short); 9095 9096vector signed char vec_vsrab (vector signed char, vector unsigned char); 9097vector unsigned char vec_vsrab (vector unsigned char, 9098 vector unsigned char); 9099 9100vector signed int vec_srl (vector signed int, vector unsigned int); 9101vector signed int vec_srl (vector signed int, vector unsigned short); 9102vector signed int vec_srl (vector signed int, vector unsigned char); 9103vector unsigned int vec_srl (vector unsigned int, vector unsigned int); 9104vector unsigned int vec_srl (vector unsigned int, 9105 vector unsigned short); 9106vector unsigned int vec_srl (vector unsigned int, vector unsigned char); 9107vector bool int vec_srl (vector bool int, vector unsigned int); 9108vector bool int vec_srl (vector bool int, vector unsigned short); 9109vector bool int vec_srl (vector bool int, vector unsigned char); 9110vector signed short vec_srl (vector signed short, vector unsigned int); 9111vector signed short vec_srl (vector signed short, 9112 vector unsigned short); 9113vector signed short vec_srl (vector signed short, vector unsigned char); 9114vector unsigned short vec_srl (vector unsigned short, 9115 vector unsigned int); 9116vector unsigned short vec_srl (vector unsigned short, 9117 vector unsigned short); 9118vector unsigned short vec_srl (vector unsigned short, 9119 vector unsigned char); 9120vector bool short vec_srl (vector bool short, vector unsigned int); 9121vector bool short vec_srl (vector bool short, vector unsigned short); 9122vector bool short vec_srl (vector bool short, vector unsigned char); 9123vector pixel vec_srl (vector pixel, vector unsigned int); 9124vector pixel vec_srl (vector pixel, vector unsigned short); 9125vector pixel vec_srl (vector pixel, vector unsigned char); 9126vector signed char vec_srl (vector signed char, vector unsigned int); 9127vector signed char vec_srl (vector signed char, vector unsigned short); 9128vector signed char vec_srl (vector signed char, vector unsigned char); 9129vector unsigned char vec_srl (vector unsigned char, 9130 vector unsigned int); 9131vector unsigned char vec_srl (vector unsigned char, 9132 vector unsigned short); 9133vector unsigned char vec_srl (vector unsigned char, 9134 vector unsigned char); 9135vector bool char vec_srl (vector bool char, vector unsigned int); 9136vector bool char vec_srl (vector bool char, vector unsigned short); 9137vector bool char vec_srl (vector bool char, vector unsigned char); 9138 9139vector float vec_sro (vector float, vector signed char); 9140vector float vec_sro (vector float, vector unsigned char); 9141vector signed int vec_sro (vector signed int, vector signed char); 9142vector signed int vec_sro (vector signed int, vector unsigned char); 9143vector unsigned int vec_sro (vector unsigned int, vector signed char); 9144vector unsigned int vec_sro (vector unsigned int, vector unsigned char); 9145vector signed short vec_sro (vector signed short, vector signed char); 9146vector signed short vec_sro (vector signed short, vector unsigned char); 9147vector unsigned short vec_sro (vector unsigned short, 9148 vector signed char); 9149vector unsigned short vec_sro (vector unsigned short, 9150 vector unsigned char); 9151vector pixel vec_sro (vector pixel, vector signed char); 9152vector pixel vec_sro (vector pixel, vector unsigned char); 9153vector signed char vec_sro (vector signed char, vector signed char); 9154vector signed char vec_sro (vector signed char, vector unsigned char); 9155vector unsigned char vec_sro (vector unsigned char, vector signed char); 9156vector unsigned char vec_sro (vector unsigned char, 9157 vector unsigned char); 9158 9159void vec_st (vector float, int, vector float *); 9160void vec_st (vector float, int, float *); 9161void vec_st (vector signed int, int, vector signed int *); 9162void vec_st (vector signed int, int, int *); 9163void vec_st (vector unsigned int, int, vector unsigned int *); 9164void vec_st (vector unsigned int, int, unsigned int *); 9165void vec_st (vector bool int, int, vector bool int *); 9166void vec_st (vector bool int, int, unsigned int *); 9167void vec_st (vector bool int, int, int *); 9168void vec_st (vector signed short, int, vector signed short *); 9169void vec_st (vector signed short, int, short *); 9170void vec_st (vector unsigned short, int, vector unsigned short *); 9171void vec_st (vector unsigned short, int, unsigned short *); 9172void vec_st (vector bool short, int, vector bool short *); 9173void vec_st (vector bool short, int, unsigned short *); 9174void vec_st (vector pixel, int, vector pixel *); 9175void vec_st (vector pixel, int, unsigned short *); 9176void vec_st (vector pixel, int, short *); 9177void vec_st (vector bool short, int, short *); 9178void vec_st (vector signed char, int, vector signed char *); 9179void vec_st (vector signed char, int, signed char *); 9180void vec_st (vector unsigned char, int, vector unsigned char *); 9181void vec_st (vector unsigned char, int, unsigned char *); 9182void vec_st (vector bool char, int, vector bool char *); 9183void vec_st (vector bool char, int, unsigned char *); 9184void vec_st (vector bool char, int, signed char *); 9185 9186void vec_ste (vector signed char, int, signed char *); 9187void vec_ste (vector unsigned char, int, unsigned char *); 9188void vec_ste (vector bool char, int, signed char *); 9189void vec_ste (vector bool char, int, unsigned char *); 9190void vec_ste (vector signed short, int, short *); 9191void vec_ste (vector unsigned short, int, unsigned short *); 9192void vec_ste (vector bool short, int, short *); 9193void vec_ste (vector bool short, int, unsigned short *); 9194void vec_ste (vector pixel, int, short *); 9195void vec_ste (vector pixel, int, unsigned short *); 9196void vec_ste (vector float, int, float *); 9197void vec_ste (vector signed int, int, int *); 9198void vec_ste (vector unsigned int, int, unsigned int *); 9199void vec_ste (vector bool int, int, int *); 9200void vec_ste (vector bool int, int, unsigned int *); 9201 9202void vec_stvewx (vector float, int, float *); 9203void vec_stvewx (vector signed int, int, int *); 9204void vec_stvewx (vector unsigned int, int, unsigned int *); 9205void vec_stvewx (vector bool int, int, int *); 9206void vec_stvewx (vector bool int, int, unsigned int *); 9207 9208void vec_stvehx (vector signed short, int, short *); 9209void vec_stvehx (vector unsigned short, int, unsigned short *); 9210void vec_stvehx (vector bool short, int, short *); 9211void vec_stvehx (vector bool short, int, unsigned short *); 9212void vec_stvehx (vector pixel, int, short *); 9213void vec_stvehx (vector pixel, int, unsigned short *); 9214 9215void vec_stvebx (vector signed char, int, signed char *); 9216void vec_stvebx (vector unsigned char, int, unsigned char *); 9217void vec_stvebx (vector bool char, int, signed char *); 9218void vec_stvebx (vector bool char, int, unsigned char *); 9219 9220void vec_stl (vector float, int, vector float *); 9221void vec_stl (vector float, int, float *); 9222void vec_stl (vector signed int, int, vector signed int *); 9223void vec_stl (vector signed int, int, int *); 9224void vec_stl (vector unsigned int, int, vector unsigned int *); 9225void vec_stl (vector unsigned int, int, unsigned int *); 9226void vec_stl (vector bool int, int, vector bool int *); 9227void vec_stl (vector bool int, int, unsigned int *); 9228void vec_stl (vector bool int, int, int *); 9229void vec_stl (vector signed short, int, vector signed short *); 9230void vec_stl (vector signed short, int, short *); 9231void vec_stl (vector unsigned short, int, vector unsigned short *); 9232void vec_stl (vector unsigned short, int, unsigned short *); 9233void vec_stl (vector bool short, int, vector bool short *); 9234void vec_stl (vector bool short, int, unsigned short *); 9235void vec_stl (vector bool short, int, short *); 9236void vec_stl (vector pixel, int, vector pixel *); 9237void vec_stl (vector pixel, int, unsigned short *); 9238void vec_stl (vector pixel, int, short *); 9239void vec_stl (vector signed char, int, vector signed char *); 9240void vec_stl (vector signed char, int, signed char *); 9241void vec_stl (vector unsigned char, int, vector unsigned char *); 9242void vec_stl (vector unsigned char, int, unsigned char *); 9243void vec_stl (vector bool char, int, vector bool char *); 9244void vec_stl (vector bool char, int, unsigned char *); 9245void vec_stl (vector bool char, int, signed char *); 9246 9247vector signed char vec_sub (vector bool char, vector signed char); 9248vector signed char vec_sub (vector signed char, vector bool char); 9249vector signed char vec_sub (vector signed char, vector signed char); 9250vector unsigned char vec_sub (vector bool char, vector unsigned char); 9251vector unsigned char vec_sub (vector unsigned char, vector bool char); 9252vector unsigned char vec_sub (vector unsigned char, 9253 vector unsigned char); 9254vector signed short vec_sub (vector bool short, vector signed short); 9255vector signed short vec_sub (vector signed short, vector bool short); 9256vector signed short vec_sub (vector signed short, vector signed short); 9257vector unsigned short vec_sub (vector bool short, 9258 vector unsigned short); 9259vector unsigned short vec_sub (vector unsigned short, 9260 vector bool short); 9261vector unsigned short vec_sub (vector unsigned short, 9262 vector unsigned short); 9263vector signed int vec_sub (vector bool int, vector signed int); 9264vector signed int vec_sub (vector signed int, vector bool int); 9265vector signed int vec_sub (vector signed int, vector signed int); 9266vector unsigned int vec_sub (vector bool int, vector unsigned int); 9267vector unsigned int vec_sub (vector unsigned int, vector bool int); 9268vector unsigned int vec_sub (vector unsigned int, vector unsigned int); 9269vector float vec_sub (vector float, vector float); 9270 9271vector float vec_vsubfp (vector float, vector float); 9272 9273vector signed int vec_vsubuwm (vector bool int, vector signed int); 9274vector signed int vec_vsubuwm (vector signed int, vector bool int); 9275vector signed int vec_vsubuwm (vector signed int, vector signed int); 9276vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); 9277vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); 9278vector unsigned int vec_vsubuwm (vector unsigned int, 9279 vector unsigned int); 9280 9281vector signed short vec_vsubuhm (vector bool short, 9282 vector signed short); 9283vector signed short vec_vsubuhm (vector signed short, 9284 vector bool short); 9285vector signed short vec_vsubuhm (vector signed short, 9286 vector signed short); 9287vector unsigned short vec_vsubuhm (vector bool short, 9288 vector unsigned short); 9289vector unsigned short vec_vsubuhm (vector unsigned short, 9290 vector bool short); 9291vector unsigned short vec_vsubuhm (vector unsigned short, 9292 vector unsigned short); 9293 9294vector signed char vec_vsububm (vector bool char, vector signed char); 9295vector signed char vec_vsububm (vector signed char, vector bool char); 9296vector signed char vec_vsububm (vector signed char, vector signed char); 9297vector unsigned char vec_vsububm (vector bool char, 9298 vector unsigned char); 9299vector unsigned char vec_vsububm (vector unsigned char, 9300 vector bool char); 9301vector unsigned char vec_vsububm (vector unsigned char, 9302 vector unsigned char); 9303 9304vector unsigned int vec_subc (vector unsigned int, vector unsigned int); 9305 9306vector unsigned char vec_subs (vector bool char, vector unsigned char); 9307vector unsigned char vec_subs (vector unsigned char, vector bool char); 9308vector unsigned char vec_subs (vector unsigned char, 9309 vector unsigned char); 9310vector signed char vec_subs (vector bool char, vector signed char); 9311vector signed char vec_subs (vector signed char, vector bool char); 9312vector signed char vec_subs (vector signed char, vector signed char); 9313vector unsigned short vec_subs (vector bool short, 9314 vector unsigned short); 9315vector unsigned short vec_subs (vector unsigned short, 9316 vector bool short); 9317vector unsigned short vec_subs (vector unsigned short, 9318 vector unsigned short); 9319vector signed short vec_subs (vector bool short, vector signed short); 9320vector signed short vec_subs (vector signed short, vector bool short); 9321vector signed short vec_subs (vector signed short, vector signed short); 9322vector unsigned int vec_subs (vector bool int, vector unsigned int); 9323vector unsigned int vec_subs (vector unsigned int, vector bool int); 9324vector unsigned int vec_subs (vector unsigned int, vector unsigned int); 9325vector signed int vec_subs (vector bool int, vector signed int); 9326vector signed int vec_subs (vector signed int, vector bool int); 9327vector signed int vec_subs (vector signed int, vector signed int); 9328 9329vector signed int vec_vsubsws (vector bool int, vector signed int); 9330vector signed int vec_vsubsws (vector signed int, vector bool int); 9331vector signed int vec_vsubsws (vector signed int, vector signed int); 9332 9333vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); 9334vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); 9335vector unsigned int vec_vsubuws (vector unsigned int, 9336 vector unsigned int); 9337 9338vector signed short vec_vsubshs (vector bool short, 9339 vector signed short); 9340vector signed short vec_vsubshs (vector signed short, 9341 vector bool short); 9342vector signed short vec_vsubshs (vector signed short, 9343 vector signed short); 9344 9345vector unsigned short vec_vsubuhs (vector bool short, 9346 vector unsigned short); 9347vector unsigned short vec_vsubuhs (vector unsigned short, 9348 vector bool short); 9349vector unsigned short vec_vsubuhs (vector unsigned short, 9350 vector unsigned short); 9351 9352vector signed char vec_vsubsbs (vector bool char, vector signed char); 9353vector signed char vec_vsubsbs (vector signed char, vector bool char); 9354vector signed char vec_vsubsbs (vector signed char, vector signed char); 9355 9356vector unsigned char vec_vsububs (vector bool char, 9357 vector unsigned char); 9358vector unsigned char vec_vsububs (vector unsigned char, 9359 vector bool char); 9360vector unsigned char vec_vsububs (vector unsigned char, 9361 vector unsigned char); 9362 9363vector unsigned int vec_sum4s (vector unsigned char, 9364 vector unsigned int); 9365vector signed int vec_sum4s (vector signed char, vector signed int); 9366vector signed int vec_sum4s (vector signed short, vector signed int); 9367 9368vector signed int vec_vsum4shs (vector signed short, vector signed int); 9369 9370vector signed int vec_vsum4sbs (vector signed char, vector signed int); 9371 9372vector unsigned int vec_vsum4ubs (vector unsigned char, 9373 vector unsigned int); 9374 9375vector signed int vec_sum2s (vector signed int, vector signed int); 9376 9377vector signed int vec_sums (vector signed int, vector signed int); 9378 9379vector float vec_trunc (vector float); 9380 9381vector signed short vec_unpackh (vector signed char); 9382vector bool short vec_unpackh (vector bool char); 9383vector signed int vec_unpackh (vector signed short); 9384vector bool int vec_unpackh (vector bool short); 9385vector unsigned int vec_unpackh (vector pixel); 9386 9387vector bool int vec_vupkhsh (vector bool short); 9388vector signed int vec_vupkhsh (vector signed short); 9389 9390vector unsigned int vec_vupkhpx (vector pixel); 9391 9392vector bool short vec_vupkhsb (vector bool char); 9393vector signed short vec_vupkhsb (vector signed char); 9394 9395vector signed short vec_unpackl (vector signed char); 9396vector bool short vec_unpackl (vector bool char); 9397vector unsigned int vec_unpackl (vector pixel); 9398vector signed int vec_unpackl (vector signed short); 9399vector bool int vec_unpackl (vector bool short); 9400 9401vector unsigned int vec_vupklpx (vector pixel); 9402 9403vector bool int vec_vupklsh (vector bool short); 9404vector signed int vec_vupklsh (vector signed short); 9405 9406vector bool short vec_vupklsb (vector bool char); 9407vector signed short vec_vupklsb (vector signed char); 9408 9409vector float vec_xor (vector float, vector float); 9410vector float vec_xor (vector float, vector bool int); 9411vector float vec_xor (vector bool int, vector float); 9412vector bool int vec_xor (vector bool int, vector bool int); 9413vector signed int vec_xor (vector bool int, vector signed int); 9414vector signed int vec_xor (vector signed int, vector bool int); 9415vector signed int vec_xor (vector signed int, vector signed int); 9416vector unsigned int vec_xor (vector bool int, vector unsigned int); 9417vector unsigned int vec_xor (vector unsigned int, vector bool int); 9418vector unsigned int vec_xor (vector unsigned int, vector unsigned int); 9419vector bool short vec_xor (vector bool short, vector bool short); 9420vector signed short vec_xor (vector bool short, vector signed short); 9421vector signed short vec_xor (vector signed short, vector bool short); 9422vector signed short vec_xor (vector signed short, vector signed short); 9423vector unsigned short vec_xor (vector bool short, 9424 vector unsigned short); 9425vector unsigned short vec_xor (vector unsigned short, 9426 vector bool short); 9427vector unsigned short vec_xor (vector unsigned short, 9428 vector unsigned short); 9429vector signed char vec_xor (vector bool char, vector signed char); 9430vector bool char vec_xor (vector bool char, vector bool char); 9431vector signed char vec_xor (vector signed char, vector bool char); 9432vector signed char vec_xor (vector signed char, vector signed char); 9433vector unsigned char vec_xor (vector bool char, vector unsigned char); 9434vector unsigned char vec_xor (vector unsigned char, vector bool char); 9435vector unsigned char vec_xor (vector unsigned char, 9436 vector unsigned char); 9437 9438int vec_all_eq (vector signed char, vector bool char); 9439int vec_all_eq (vector signed char, vector signed char); 9440int vec_all_eq (vector unsigned char, vector bool char); 9441int vec_all_eq (vector unsigned char, vector unsigned char); 9442int vec_all_eq (vector bool char, vector bool char); 9443int vec_all_eq (vector bool char, vector unsigned char); 9444int vec_all_eq (vector bool char, vector signed char); 9445int vec_all_eq (vector signed short, vector bool short); 9446int vec_all_eq (vector signed short, vector signed short); 9447int vec_all_eq (vector unsigned short, vector bool short); 9448int vec_all_eq (vector unsigned short, vector unsigned short); 9449int vec_all_eq (vector bool short, vector bool short); 9450int vec_all_eq (vector bool short, vector unsigned short); 9451int vec_all_eq (vector bool short, vector signed short); 9452int vec_all_eq (vector pixel, vector pixel); 9453int vec_all_eq (vector signed int, vector bool int); 9454int vec_all_eq (vector signed int, vector signed int); 9455int vec_all_eq (vector unsigned int, vector bool int); 9456int vec_all_eq (vector unsigned int, vector unsigned int); 9457int vec_all_eq (vector bool int, vector bool int); 9458int vec_all_eq (vector bool int, vector unsigned int); 9459int vec_all_eq (vector bool int, vector signed int); 9460int vec_all_eq (vector float, vector float); 9461 9462int vec_all_ge (vector bool char, vector unsigned char); 9463int vec_all_ge (vector unsigned char, vector bool char); 9464int vec_all_ge (vector unsigned char, vector unsigned char); 9465int vec_all_ge (vector bool char, vector signed char); 9466int vec_all_ge (vector signed char, vector bool char); 9467int vec_all_ge (vector signed char, vector signed char); 9468int vec_all_ge (vector bool short, vector unsigned short); 9469int vec_all_ge (vector unsigned short, vector bool short); 9470int vec_all_ge (vector unsigned short, vector unsigned short); 9471int vec_all_ge (vector signed short, vector signed short); 9472int vec_all_ge (vector bool short, vector signed short); 9473int vec_all_ge (vector signed short, vector bool short); 9474int vec_all_ge (vector bool int, vector unsigned int); 9475int vec_all_ge (vector unsigned int, vector bool int); 9476int vec_all_ge (vector unsigned int, vector unsigned int); 9477int vec_all_ge (vector bool int, vector signed int); 9478int vec_all_ge (vector signed int, vector bool int); 9479int vec_all_ge (vector signed int, vector signed int); 9480int vec_all_ge (vector float, vector float); 9481 9482int vec_all_gt (vector bool char, vector unsigned char); 9483int vec_all_gt (vector unsigned char, vector bool char); 9484int vec_all_gt (vector unsigned char, vector unsigned char); 9485int vec_all_gt (vector bool char, vector signed char); 9486int vec_all_gt (vector signed char, vector bool char); 9487int vec_all_gt (vector signed char, vector signed char); 9488int vec_all_gt (vector bool short, vector unsigned short); 9489int vec_all_gt (vector unsigned short, vector bool short); 9490int vec_all_gt (vector unsigned short, vector unsigned short); 9491int vec_all_gt (vector bool short, vector signed short); 9492int vec_all_gt (vector signed short, vector bool short); 9493int vec_all_gt (vector signed short, vector signed short); 9494int vec_all_gt (vector bool int, vector unsigned int); 9495int vec_all_gt (vector unsigned int, vector bool int); 9496int vec_all_gt (vector unsigned int, vector unsigned int); 9497int vec_all_gt (vector bool int, vector signed int); 9498int vec_all_gt (vector signed int, vector bool int); 9499int vec_all_gt (vector signed int, vector signed int); 9500int vec_all_gt (vector float, vector float); 9501 9502int vec_all_in (vector float, vector float); 9503 9504int vec_all_le (vector bool char, vector unsigned char); 9505int vec_all_le (vector unsigned char, vector bool char); 9506int vec_all_le (vector unsigned char, vector unsigned char); 9507int vec_all_le (vector bool char, vector signed char); 9508int vec_all_le (vector signed char, vector bool char); 9509int vec_all_le (vector signed char, vector signed char); 9510int vec_all_le (vector bool short, vector unsigned short); 9511int vec_all_le (vector unsigned short, vector bool short); 9512int vec_all_le (vector unsigned short, vector unsigned short); 9513int vec_all_le (vector bool short, vector signed short); 9514int vec_all_le (vector signed short, vector bool short); 9515int vec_all_le (vector signed short, vector signed short); 9516int vec_all_le (vector bool int, vector unsigned int); 9517int vec_all_le (vector unsigned int, vector bool int); 9518int vec_all_le (vector unsigned int, vector unsigned int); 9519int vec_all_le (vector bool int, vector signed int); 9520int vec_all_le (vector signed int, vector bool int); 9521int vec_all_le (vector signed int, vector signed int); 9522int vec_all_le (vector float, vector float); 9523 9524int vec_all_lt (vector bool char, vector unsigned char); 9525int vec_all_lt (vector unsigned char, vector bool char); 9526int vec_all_lt (vector unsigned char, vector unsigned char); 9527int vec_all_lt (vector bool char, vector signed char); 9528int vec_all_lt (vector signed char, vector bool char); 9529int vec_all_lt (vector signed char, vector signed char); 9530int vec_all_lt (vector bool short, vector unsigned short); 9531int vec_all_lt (vector unsigned short, vector bool short); 9532int vec_all_lt (vector unsigned short, vector unsigned short); 9533int vec_all_lt (vector bool short, vector signed short); 9534int vec_all_lt (vector signed short, vector bool short); 9535int vec_all_lt (vector signed short, vector signed short); 9536int vec_all_lt (vector bool int, vector unsigned int); 9537int vec_all_lt (vector unsigned int, vector bool int); 9538int vec_all_lt (vector unsigned int, vector unsigned int); 9539int vec_all_lt (vector bool int, vector signed int); 9540int vec_all_lt (vector signed int, vector bool int); 9541int vec_all_lt (vector signed int, vector signed int); 9542int vec_all_lt (vector float, vector float); 9543 9544int vec_all_nan (vector float); 9545 9546int vec_all_ne (vector signed char, vector bool char); 9547int vec_all_ne (vector signed char, vector signed char); 9548int vec_all_ne (vector unsigned char, vector bool char); 9549int vec_all_ne (vector unsigned char, vector unsigned char); 9550int vec_all_ne (vector bool char, vector bool char); 9551int vec_all_ne (vector bool char, vector unsigned char); 9552int vec_all_ne (vector bool char, vector signed char); 9553int vec_all_ne (vector signed short, vector bool short); 9554int vec_all_ne (vector signed short, vector signed short); 9555int vec_all_ne (vector unsigned short, vector bool short); 9556int vec_all_ne (vector unsigned short, vector unsigned short); 9557int vec_all_ne (vector bool short, vector bool short); 9558int vec_all_ne (vector bool short, vector unsigned short); 9559int vec_all_ne (vector bool short, vector signed short); 9560int vec_all_ne (vector pixel, vector pixel); 9561int vec_all_ne (vector signed int, vector bool int); 9562int vec_all_ne (vector signed int, vector signed int); 9563int vec_all_ne (vector unsigned int, vector bool int); 9564int vec_all_ne (vector unsigned int, vector unsigned int); 9565int vec_all_ne (vector bool int, vector bool int); 9566int vec_all_ne (vector bool int, vector unsigned int); 9567int vec_all_ne (vector bool int, vector signed int); 9568int vec_all_ne (vector float, vector float); 9569 9570int vec_all_nge (vector float, vector float); 9571 9572int vec_all_ngt (vector float, vector float); 9573 9574int vec_all_nle (vector float, vector float); 9575 9576int vec_all_nlt (vector float, vector float); 9577 9578int vec_all_numeric (vector float); 9579 9580int vec_any_eq (vector signed char, vector bool char); 9581int vec_any_eq (vector signed char, vector signed char); 9582int vec_any_eq (vector unsigned char, vector bool char); 9583int vec_any_eq (vector unsigned char, vector unsigned char); 9584int vec_any_eq (vector bool char, vector bool char); 9585int vec_any_eq (vector bool char, vector unsigned char); 9586int vec_any_eq (vector bool char, vector signed char); 9587int vec_any_eq (vector signed short, vector bool short); 9588int vec_any_eq (vector signed short, vector signed short); 9589int vec_any_eq (vector unsigned short, vector bool short); 9590int vec_any_eq (vector unsigned short, vector unsigned short); 9591int vec_any_eq (vector bool short, vector bool short); 9592int vec_any_eq (vector bool short, vector unsigned short); 9593int vec_any_eq (vector bool short, vector signed short); 9594int vec_any_eq (vector pixel, vector pixel); 9595int vec_any_eq (vector signed int, vector bool int); 9596int vec_any_eq (vector signed int, vector signed int); 9597int vec_any_eq (vector unsigned int, vector bool int); 9598int vec_any_eq (vector unsigned int, vector unsigned int); 9599int vec_any_eq (vector bool int, vector bool int); 9600int vec_any_eq (vector bool int, vector unsigned int); 9601int vec_any_eq (vector bool int, vector signed int); 9602int vec_any_eq (vector float, vector float); 9603 9604int vec_any_ge (vector signed char, vector bool char); 9605int vec_any_ge (vector unsigned char, vector bool char); 9606int vec_any_ge (vector unsigned char, vector unsigned char); 9607int vec_any_ge (vector signed char, vector signed char); 9608int vec_any_ge (vector bool char, vector unsigned char); 9609int vec_any_ge (vector bool char, vector signed char); 9610int vec_any_ge (vector unsigned short, vector bool short); 9611int vec_any_ge (vector unsigned short, vector unsigned short); 9612int vec_any_ge (vector signed short, vector signed short); 9613int vec_any_ge (vector signed short, vector bool short); 9614int vec_any_ge (vector bool short, vector unsigned short); 9615int vec_any_ge (vector bool short, vector signed short); 9616int vec_any_ge (vector signed int, vector bool int); 9617int vec_any_ge (vector unsigned int, vector bool int); 9618int vec_any_ge (vector unsigned int, vector unsigned int); 9619int vec_any_ge (vector signed int, vector signed int); 9620int vec_any_ge (vector bool int, vector unsigned int); 9621int vec_any_ge (vector bool int, vector signed int); 9622int vec_any_ge (vector float, vector float); 9623 9624int vec_any_gt (vector bool char, vector unsigned char); 9625int vec_any_gt (vector unsigned char, vector bool char); 9626int vec_any_gt (vector unsigned char, vector unsigned char); 9627int vec_any_gt (vector bool char, vector signed char); 9628int vec_any_gt (vector signed char, vector bool char); 9629int vec_any_gt (vector signed char, vector signed char); 9630int vec_any_gt (vector bool short, vector unsigned short); 9631int vec_any_gt (vector unsigned short, vector bool short); 9632int vec_any_gt (vector unsigned short, vector unsigned short); 9633int vec_any_gt (vector bool short, vector signed short); 9634int vec_any_gt (vector signed short, vector bool short); 9635int vec_any_gt (vector signed short, vector signed short); 9636int vec_any_gt (vector bool int, vector unsigned int); 9637int vec_any_gt (vector unsigned int, vector bool int); 9638int vec_any_gt (vector unsigned int, vector unsigned int); 9639int vec_any_gt (vector bool int, vector signed int); 9640int vec_any_gt (vector signed int, vector bool int); 9641int vec_any_gt (vector signed int, vector signed int); 9642int vec_any_gt (vector float, vector float); 9643 9644int vec_any_le (vector bool char, vector unsigned char); 9645int vec_any_le (vector unsigned char, vector bool char); 9646int vec_any_le (vector unsigned char, vector unsigned char); 9647int vec_any_le (vector bool char, vector signed char); 9648int vec_any_le (vector signed char, vector bool char); 9649int vec_any_le (vector signed char, vector signed char); 9650int vec_any_le (vector bool short, vector unsigned short); 9651int vec_any_le (vector unsigned short, vector bool short); 9652int vec_any_le (vector unsigned short, vector unsigned short); 9653int vec_any_le (vector bool short, vector signed short); 9654int vec_any_le (vector signed short, vector bool short); 9655int vec_any_le (vector signed short, vector signed short); 9656int vec_any_le (vector bool int, vector unsigned int); 9657int vec_any_le (vector unsigned int, vector bool int); 9658int vec_any_le (vector unsigned int, vector unsigned int); 9659int vec_any_le (vector bool int, vector signed int); 9660int vec_any_le (vector signed int, vector bool int); 9661int vec_any_le (vector signed int, vector signed int); 9662int vec_any_le (vector float, vector float); 9663 9664int vec_any_lt (vector bool char, vector unsigned char); 9665int vec_any_lt (vector unsigned char, vector bool char); 9666int vec_any_lt (vector unsigned char, vector unsigned char); 9667int vec_any_lt (vector bool char, vector signed char); 9668int vec_any_lt (vector signed char, vector bool char); 9669int vec_any_lt (vector signed char, vector signed char); 9670int vec_any_lt (vector bool short, vector unsigned short); 9671int vec_any_lt (vector unsigned short, vector bool short); 9672int vec_any_lt (vector unsigned short, vector unsigned short); 9673int vec_any_lt (vector bool short, vector signed short); 9674int vec_any_lt (vector signed short, vector bool short); 9675int vec_any_lt (vector signed short, vector signed short); 9676int vec_any_lt (vector bool int, vector unsigned int); 9677int vec_any_lt (vector unsigned int, vector bool int); 9678int vec_any_lt (vector unsigned int, vector unsigned int); 9679int vec_any_lt (vector bool int, vector signed int); 9680int vec_any_lt (vector signed int, vector bool int); 9681int vec_any_lt (vector signed int, vector signed int); 9682int vec_any_lt (vector float, vector float); 9683 9684int vec_any_nan (vector float); 9685 9686int vec_any_ne (vector signed char, vector bool char); 9687int vec_any_ne (vector signed char, vector signed char); 9688int vec_any_ne (vector unsigned char, vector bool char); 9689int vec_any_ne (vector unsigned char, vector unsigned char); 9690int vec_any_ne (vector bool char, vector bool char); 9691int vec_any_ne (vector bool char, vector unsigned char); 9692int vec_any_ne (vector bool char, vector signed char); 9693int vec_any_ne (vector signed short, vector bool short); 9694int vec_any_ne (vector signed short, vector signed short); 9695int vec_any_ne (vector unsigned short, vector bool short); 9696int vec_any_ne (vector unsigned short, vector unsigned short); 9697int vec_any_ne (vector bool short, vector bool short); 9698int vec_any_ne (vector bool short, vector unsigned short); 9699int vec_any_ne (vector bool short, vector signed short); 9700int vec_any_ne (vector pixel, vector pixel); 9701int vec_any_ne (vector signed int, vector bool int); 9702int vec_any_ne (vector signed int, vector signed int); 9703int vec_any_ne (vector unsigned int, vector bool int); 9704int vec_any_ne (vector unsigned int, vector unsigned int); 9705int vec_any_ne (vector bool int, vector bool int); 9706int vec_any_ne (vector bool int, vector unsigned int); 9707int vec_any_ne (vector bool int, vector signed int); 9708int vec_any_ne (vector float, vector float); 9709 9710int vec_any_nge (vector float, vector float); 9711 9712int vec_any_ngt (vector float, vector float); 9713 9714int vec_any_nle (vector float, vector float); 9715 9716int vec_any_nlt (vector float, vector float); 9717 9718int vec_any_numeric (vector float); 9719 9720int vec_any_out (vector float, vector float); 9721@end smallexample 9722 9723@node SPARC VIS Built-in Functions 9724@subsection SPARC VIS Built-in Functions 9725 9726GCC supports SIMD operations on the SPARC using both the generic vector 9727extensions (@pxref{Vector Extensions}) as well as built-in functions for 9728the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} 9729switch, the VIS extension is exposed as the following built-in functions: 9730 9731@smallexample 9732typedef int v2si __attribute__ ((vector_size (8))); 9733typedef short v4hi __attribute__ ((vector_size (8))); 9734typedef short v2hi __attribute__ ((vector_size (4))); 9735typedef char v8qi __attribute__ ((vector_size (8))); 9736typedef char v4qi __attribute__ ((vector_size (4))); 9737 9738void * __builtin_vis_alignaddr (void *, long); 9739int64_t __builtin_vis_faligndatadi (int64_t, int64_t); 9740v2si __builtin_vis_faligndatav2si (v2si, v2si); 9741v4hi __builtin_vis_faligndatav4hi (v4si, v4si); 9742v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); 9743 9744v4hi __builtin_vis_fexpand (v4qi); 9745 9746v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); 9747v4hi __builtin_vis_fmul8x16au (v4qi, v4hi); 9748v4hi __builtin_vis_fmul8x16al (v4qi, v4hi); 9749v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); 9750v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); 9751v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); 9752v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); 9753 9754v4qi __builtin_vis_fpack16 (v4hi); 9755v8qi __builtin_vis_fpack32 (v2si, v2si); 9756v2hi __builtin_vis_fpackfix (v2si); 9757v8qi __builtin_vis_fpmerge (v4qi, v4qi); 9758 9759int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); 9760@end smallexample 9761 9762@node Target Format Checks 9763@section Format Checks Specific to Particular Target Machines 9764 9765For some target machines, GCC supports additional options to the 9766format attribute 9767(@pxref{Function Attributes,,Declaring Attributes of Functions}). 9768 9769@menu 9770* Solaris Format Checks:: 9771@end menu 9772 9773@node Solaris Format Checks 9774@subsection Solaris Format Checks 9775 9776Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format 9777check. @code{cmn_err} accepts a subset of the standard @code{printf} 9778conversions, and the two-argument @code{%b} conversion for displaying 9779bit-fields. See the Solaris man page for @code{cmn_err} for more information. 9780 9781@node Pragmas 9782@section Pragmas Accepted by GCC 9783@cindex pragmas 9784@cindex #pragma 9785 9786GCC supports several types of pragmas, primarily in order to compile 9787code originally written for other compilers. Note that in general 9788we do not recommend the use of pragmas; @xref{Function Attributes}, 9789for further explanation. 9790 9791@menu 9792* ARM Pragmas:: 9793* M32C Pragmas:: 9794* RS/6000 and PowerPC Pragmas:: 9795* Darwin Pragmas:: 9796* Solaris Pragmas:: 9797* Symbol-Renaming Pragmas:: 9798* Structure-Packing Pragmas:: 9799* Weak Pragmas:: 9800* Diagnostic Pragmas:: 9801* Visibility Pragmas:: 9802@end menu 9803 9804@node ARM Pragmas 9805@subsection ARM Pragmas 9806 9807The ARM target defines pragmas for controlling the default addition of 9808@code{long_call} and @code{short_call} attributes to functions. 9809@xref{Function Attributes}, for information about the effects of these 9810attributes. 9811 9812@table @code 9813@item long_calls 9814@cindex pragma, long_calls 9815Set all subsequent functions to have the @code{long_call} attribute. 9816 9817@item no_long_calls 9818@cindex pragma, no_long_calls 9819Set all subsequent functions to have the @code{short_call} attribute. 9820 9821@item long_calls_off 9822@cindex pragma, long_calls_off 9823Do not affect the @code{long_call} or @code{short_call} attributes of 9824subsequent functions. 9825@end table 9826 9827@node M32C Pragmas 9828@subsection M32C Pragmas 9829 9830@table @code 9831@item memregs @var{number} 9832@cindex pragma, memregs 9833Overrides the command line option @code{-memregs=} for the current 9834file. Use with care! This pragma must be before any function in the 9835file, and mixing different memregs values in different objects may 9836make them incompatible. This pragma is useful when a 9837performance-critical function uses a memreg for temporary values, 9838as it may allow you to reduce the number of memregs used. 9839 9840@end table 9841 9842@node RS/6000 and PowerPC Pragmas 9843@subsection RS/6000 and PowerPC Pragmas 9844 9845The RS/6000 and PowerPC targets define one pragma for controlling 9846whether or not the @code{longcall} attribute is added to function 9847declarations by default. This pragma overrides the @option{-mlongcall} 9848option, but not the @code{longcall} and @code{shortcall} attributes. 9849@xref{RS/6000 and PowerPC Options}, for more information about when long 9850calls are and are not necessary. 9851 9852@table @code 9853@item longcall (1) 9854@cindex pragma, longcall 9855Apply the @code{longcall} attribute to all subsequent function 9856declarations. 9857 9858@item longcall (0) 9859Do not apply the @code{longcall} attribute to subsequent function 9860declarations. 9861@end table 9862 9863@c Describe c4x pragmas here. 9864@c Describe h8300 pragmas here. 9865@c Describe sh pragmas here. 9866@c Describe v850 pragmas here. 9867 9868@node Darwin Pragmas 9869@subsection Darwin Pragmas 9870 9871The following pragmas are available for all architectures running the 9872Darwin operating system. These are useful for compatibility with other 9873Mac OS compilers. 9874 9875@table @code 9876@item mark @var{tokens}@dots{} 9877@cindex pragma, mark 9878This pragma is accepted, but has no effect. 9879 9880@item options align=@var{alignment} 9881@cindex pragma, options align 9882This pragma sets the alignment of fields in structures. The values of 9883@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or 9884@code{power}, to emulate PowerPC alignment. Uses of this pragma nest 9885properly; to restore the previous setting, use @code{reset} for the 9886@var{alignment}. 9887 9888@item segment @var{tokens}@dots{} 9889@cindex pragma, segment 9890This pragma is accepted, but has no effect. 9891 9892@item unused (@var{var} [, @var{var}]@dots{}) 9893@cindex pragma, unused 9894This pragma declares variables to be possibly unused. GCC will not 9895produce warnings for the listed variables. The effect is similar to 9896that of the @code{unused} attribute, except that this pragma may appear 9897anywhere within the variables' scopes. 9898@end table 9899 9900@node Solaris Pragmas 9901@subsection Solaris Pragmas 9902 9903The Solaris target supports @code{#pragma redefine_extname} 9904(@pxref{Symbol-Renaming Pragmas}). It also supports additional 9905@code{#pragma} directives for compatibility with the system compiler. 9906 9907@table @code 9908@item align @var{alignment} (@var{variable} [, @var{variable}]...) 9909@cindex pragma, align 9910 9911Increase the minimum alignment of each @var{variable} to @var{alignment}. 9912This is the same as GCC's @code{aligned} attribute @pxref{Variable 9913Attributes}). Macro expansion occurs on the arguments to this pragma 9914when compiling C. It does not currently occur when compiling C++, but 9915this is a bug which may be fixed in a future release. 9916 9917@item fini (@var{function} [, @var{function}]...) 9918@cindex pragma, fini 9919 9920This pragma causes each listed @var{function} to be called after 9921main, or during shared module unloading, by adding a call to the 9922@code{.fini} section. 9923 9924@item init (@var{function} [, @var{function}]...) 9925@cindex pragma, init 9926 9927This pragma causes each listed @var{function} to be called during 9928initialization (before @code{main}) or during shared module loading, by 9929adding a call to the @code{.init} section. 9930 9931@end table 9932 9933@node Symbol-Renaming Pragmas 9934@subsection Symbol-Renaming Pragmas 9935 9936For compatibility with the Solaris and Tru64 UNIX system headers, GCC 9937supports two @code{#pragma} directives which change the name used in 9938assembly for a given declaration. These pragmas are only available on 9939platforms whose system headers need them. To get this effect on all 9940platforms supported by GCC, use the asm labels extension (@pxref{Asm 9941Labels}). 9942 9943@table @code 9944@item redefine_extname @var{oldname} @var{newname} 9945@cindex pragma, redefine_extname 9946 9947This pragma gives the C function @var{oldname} the assembly symbol 9948@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} 9949will be defined if this pragma is available (currently only on 9950Solaris). 9951 9952@item extern_prefix @var{string} 9953@cindex pragma, extern_prefix 9954 9955This pragma causes all subsequent external function and variable 9956declarations to have @var{string} prepended to their assembly symbols. 9957This effect may be terminated with another @code{extern_prefix} pragma 9958whose argument is an empty string. The preprocessor macro 9959@code{__PRAGMA_EXTERN_PREFIX} will be defined if this pragma is 9960available (currently only on Tru64 UNIX)@. 9961@end table 9962 9963These pragmas and the asm labels extension interact in a complicated 9964manner. Here are some corner cases you may want to be aware of. 9965 9966@enumerate 9967@item Both pragmas silently apply only to declarations with external 9968linkage. Asm labels do not have this restriction. 9969 9970@item In C++, both pragmas silently apply only to declarations with 9971``C'' linkage. Again, asm labels do not have this restriction. 9972 9973@item If any of the three ways of changing the assembly name of a 9974declaration is applied to a declaration whose assembly name has 9975already been determined (either by a previous use of one of these 9976features, or because the compiler needed the assembly name in order to 9977generate code), and the new name is different, a warning issues and 9978the name does not change. 9979 9980@item The @var{oldname} used by @code{#pragma redefine_extname} is 9981always the C-language name. 9982 9983@item If @code{#pragma extern_prefix} is in effect, and a declaration 9984occurs with an asm label attached, the prefix is silently ignored for 9985that declaration. 9986 9987@item If @code{#pragma extern_prefix} and @code{#pragma redefine_extname} 9988apply to the same declaration, whichever triggered first wins, and a 9989warning issues if they contradict each other. (We would like to have 9990@code{#pragma redefine_extname} always win, for consistency with asm 9991labels, but if @code{#pragma extern_prefix} triggers first we have no 9992way of knowing that that happened.) 9993@end enumerate 9994 9995@node Structure-Packing Pragmas 9996@subsection Structure-Packing Pragmas 9997 9998For compatibility with Win32, GCC supports a set of @code{#pragma} 9999directives which change the maximum alignment of members of structures 10000(other than zero-width bitfields), unions, and classes subsequently 10001defined. The @var{n} value below always is required to be a small power 10002of two and specifies the new alignment in bytes. 10003 10004@enumerate 10005@item @code{#pragma pack(@var{n})} simply sets the new alignment. 10006@item @code{#pragma pack()} sets the alignment to the one that was in 10007effect when compilation started (see also command line option 10008@option{-fpack-struct[=<n>]} @pxref{Code Gen Options}). 10009@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment 10010setting on an internal stack and then optionally sets the new alignment. 10011@item @code{#pragma pack(pop)} restores the alignment setting to the one 10012saved at the top of the internal stack (and removes that stack entry). 10013Note that @code{#pragma pack([@var{n}])} does not influence this internal 10014stack; thus it is possible to have @code{#pragma pack(push)} followed by 10015multiple @code{#pragma pack(@var{n})} instances and finalized by a single 10016@code{#pragma pack(pop)}. 10017@end enumerate 10018 10019Some targets, e.g. i386 and powerpc, support the @code{ms_struct} 10020@code{#pragma} which lays out a structure as the documented 10021@code{__attribute__ ((ms_struct))}. 10022@enumerate 10023@item @code{#pragma ms_struct on} turns on the layout for structures 10024declared. 10025@item @code{#pragma ms_struct off} turns off the layout for structures 10026declared. 10027@item @code{#pragma ms_struct reset} goes back to the default layout. 10028@end enumerate 10029 10030@node Weak Pragmas 10031@subsection Weak Pragmas 10032 10033For compatibility with SVR4, GCC supports a set of @code{#pragma} 10034directives for declaring symbols to be weak, and defining weak 10035aliases. 10036 10037@table @code 10038@item #pragma weak @var{symbol} 10039@cindex pragma, weak 10040This pragma declares @var{symbol} to be weak, as if the declaration 10041had the attribute of the same name. The pragma may appear before 10042or after the declaration of @var{symbol}, but must appear before 10043either its first use or its definition. It is not an error for 10044@var{symbol} to never be defined at all. 10045 10046@item #pragma weak @var{symbol1} = @var{symbol2} 10047This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. 10048It is an error if @var{symbol2} is not defined in the current 10049translation unit. 10050@end table 10051 10052@node Diagnostic Pragmas 10053@subsection Diagnostic Pragmas 10054 10055GCC allows the user to selectively enable or disable certain types of 10056diagnostics, and change the kind of the diagnostic. For example, a 10057project's policy might require that all sources compile with 10058@option{-Werror} but certain files might have exceptions allowing 10059specific types of warnings. Or, a project might selectively enable 10060diagnostics and treat them as errors depending on which preprocessor 10061macros are defined. 10062 10063@table @code 10064@item #pragma GCC diagnostic @var{kind} @var{option} 10065@cindex pragma, diagnostic 10066 10067Modifies the disposition of a diagnostic. Note that not all 10068diagnostics are modifiable; at the moment only warnings (normally 10069controlled by @samp{-W...}) can be controlled, and not all of them. 10070Use @option{-fdiagnostics-show-option} to determine which diagnostics 10071are controllable and which option controls them. 10072 10073@var{kind} is @samp{error} to treat this diagnostic as an error, 10074@samp{warning} to treat it like a warning (even if @option{-Werror} is 10075in effect), or @samp{ignored} if the diagnostic is to be ignored. 10076@var{option} is a double quoted string which matches the command line 10077option. 10078 10079@example 10080#pragma GCC diagnostic warning "-Wformat" 10081#pragma GCC diagnostic error "-Wformat" 10082#pragma GCC diagnostic ignored "-Wformat" 10083@end example 10084 10085Note that these pragmas override any command line options. Also, 10086while it is syntactically valid to put these pragmas anywhere in your 10087sources, the only supported location for them is before any data or 10088functions are defined. Doing otherwise may result in unpredictable 10089results depending on how the optimizer manages your sources. If the 10090same option is listed multiple times, the last one specified is the 10091one that is in effect. This pragma is not intended to be a general 10092purpose replacement for command line options, but for implementing 10093strict control over project policies. 10094 10095@end table 10096 10097@node Visibility Pragmas 10098@subsection Visibility Pragmas 10099 10100@table @code 10101@item #pragma GCC visibility push(@var{visibility}) 10102@itemx #pragma GCC visibility pop 10103@cindex pragma, visibility 10104 10105This pragma allows the user to set the visibility for multiple 10106declarations without having to give each a visibility attribute 10107@xref{Function Attributes}, for more information about visibility and 10108the attribute syntax. 10109 10110In C++, @samp{#pragma GCC visibility} affects only namespace-scope 10111declarations. Class members and template specializations are not 10112affected; if you want to override the visibility for a particular 10113member or instantiation, you must use an attribute. 10114 10115@end table 10116 10117@node Unnamed Fields 10118@section Unnamed struct/union fields within structs/unions 10119@cindex struct 10120@cindex union 10121 10122For compatibility with other compilers, GCC allows you to define 10123a structure or union that contains, as fields, structures and unions 10124without names. For example: 10125 10126@smallexample 10127struct @{ 10128 int a; 10129 union @{ 10130 int b; 10131 float c; 10132 @}; 10133 int d; 10134@} foo; 10135@end smallexample 10136 10137In this example, the user would be able to access members of the unnamed 10138union with code like @samp{foo.b}. Note that only unnamed structs and 10139unions are allowed, you may not have, for example, an unnamed 10140@code{int}. 10141 10142You must never create such structures that cause ambiguous field definitions. 10143For example, this structure: 10144 10145@smallexample 10146struct @{ 10147 int a; 10148 struct @{ 10149 int a; 10150 @}; 10151@} foo; 10152@end smallexample 10153 10154It is ambiguous which @code{a} is being referred to with @samp{foo.a}. 10155Such constructs are not supported and must be avoided. In the future, 10156such constructs may be detected and treated as compilation errors. 10157 10158@opindex fms-extensions 10159Unless @option{-fms-extensions} is used, the unnamed field must be a 10160structure or union definition without a tag (for example, @samp{struct 10161@{ int a; @};}). If @option{-fms-extensions} is used, the field may 10162also be a definition with a tag such as @samp{struct foo @{ int a; 10163@};}, a reference to a previously defined structure or union such as 10164@samp{struct foo;}, or a reference to a @code{typedef} name for a 10165previously defined structure or union type. 10166 10167@node Thread-Local 10168@section Thread-Local Storage 10169@cindex Thread-Local Storage 10170@cindex @acronym{TLS} 10171@cindex __thread 10172 10173Thread-local storage (@acronym{TLS}) is a mechanism by which variables 10174are allocated such that there is one instance of the variable per extant 10175thread. The run-time model GCC uses to implement this originates 10176in the IA-64 processor-specific ABI, but has since been migrated 10177to other processors as well. It requires significant support from 10178the linker (@command{ld}), dynamic linker (@command{ld.so}), and 10179system libraries (@file{libc.so} and @file{libpthread.so}), so it 10180is not available everywhere. 10181 10182At the user level, the extension is visible with a new storage 10183class keyword: @code{__thread}. For example: 10184 10185@smallexample 10186__thread int i; 10187extern __thread struct state s; 10188static __thread char *p; 10189@end smallexample 10190 10191The @code{__thread} specifier may be used alone, with the @code{extern} 10192or @code{static} specifiers, but with no other storage class specifier. 10193When used with @code{extern} or @code{static}, @code{__thread} must appear 10194immediately after the other storage class specifier. 10195 10196The @code{__thread} specifier may be applied to any global, file-scoped 10197static, function-scoped static, or static data member of a class. It may 10198not be applied to block-scoped automatic or non-static data member. 10199 10200When the address-of operator is applied to a thread-local variable, it is 10201evaluated at run-time and returns the address of the current thread's 10202instance of that variable. An address so obtained may be used by any 10203thread. When a thread terminates, any pointers to thread-local variables 10204in that thread become invalid. 10205 10206No static initialization may refer to the address of a thread-local variable. 10207 10208In C++, if an initializer is present for a thread-local variable, it must 10209be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ 10210standard. 10211 10212See @uref{http://people.redhat.com/drepper/tls.pdf, 10213ELF Handling For Thread-Local Storage} for a detailed explanation of 10214the four thread-local storage addressing models, and how the run-time 10215is expected to function. 10216 10217@menu 10218* C99 Thread-Local Edits:: 10219* C++98 Thread-Local Edits:: 10220@end menu 10221 10222@node C99 Thread-Local Edits 10223@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage 10224 10225The following are a set of changes to ISO/IEC 9899:1999 (aka C99) 10226that document the exact semantics of the language extension. 10227 10228@itemize @bullet 10229@item 10230@cite{5.1.2 Execution environments} 10231 10232Add new text after paragraph 1 10233 10234@quotation 10235Within either execution environment, a @dfn{thread} is a flow of 10236control within a program. It is implementation defined whether 10237or not there may be more than one thread associated with a program. 10238It is implementation defined how threads beyond the first are 10239created, the name and type of the function called at thread 10240startup, and how threads may be terminated. However, objects 10241with thread storage duration shall be initialized before thread 10242startup. 10243@end quotation 10244 10245@item 10246@cite{6.2.4 Storage durations of objects} 10247 10248Add new text before paragraph 3 10249 10250@quotation 10251An object whose identifier is declared with the storage-class 10252specifier @w{@code{__thread}} has @dfn{thread storage duration}. 10253Its lifetime is the entire execution of the thread, and its 10254stored value is initialized only once, prior to thread startup. 10255@end quotation 10256 10257@item 10258@cite{6.4.1 Keywords} 10259 10260Add @code{__thread}. 10261 10262@item 10263@cite{6.7.1 Storage-class specifiers} 10264 10265Add @code{__thread} to the list of storage class specifiers in 10266paragraph 1. 10267 10268Change paragraph 2 to 10269 10270@quotation 10271With the exception of @code{__thread}, at most one storage-class 10272specifier may be given [@dots{}]. The @code{__thread} specifier may 10273be used alone, or immediately following @code{extern} or 10274@code{static}. 10275@end quotation 10276 10277Add new text after paragraph 6 10278 10279@quotation 10280The declaration of an identifier for a variable that has 10281block scope that specifies @code{__thread} shall also 10282specify either @code{extern} or @code{static}. 10283 10284The @code{__thread} specifier shall be used only with 10285variables. 10286@end quotation 10287@end itemize 10288 10289@node C++98 Thread-Local Edits 10290@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage 10291 10292The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) 10293that document the exact semantics of the language extension. 10294 10295@itemize @bullet 10296@item 10297@b{[intro.execution]} 10298 10299New text after paragraph 4 10300 10301@quotation 10302A @dfn{thread} is a flow of control within the abstract machine. 10303It is implementation defined whether or not there may be more than 10304one thread. 10305@end quotation 10306 10307New text after paragraph 7 10308 10309@quotation 10310It is unspecified whether additional action must be taken to 10311ensure when and whether side effects are visible to other threads. 10312@end quotation 10313 10314@item 10315@b{[lex.key]} 10316 10317Add @code{__thread}. 10318 10319@item 10320@b{[basic.start.main]} 10321 10322Add after paragraph 5 10323 10324@quotation 10325The thread that begins execution at the @code{main} function is called 10326the @dfn{main thread}. It is implementation defined how functions 10327beginning threads other than the main thread are designated or typed. 10328A function so designated, as well as the @code{main} function, is called 10329a @dfn{thread startup function}. It is implementation defined what 10330happens if a thread startup function returns. It is implementation 10331defined what happens to other threads when any thread calls @code{exit}. 10332@end quotation 10333 10334@item 10335@b{[basic.start.init]} 10336 10337Add after paragraph 4 10338 10339@quotation 10340The storage for an object of thread storage duration shall be 10341statically initialized before the first statement of the thread startup 10342function. An object of thread storage duration shall not require 10343dynamic initialization. 10344@end quotation 10345 10346@item 10347@b{[basic.start.term]} 10348 10349Add after paragraph 3 10350 10351@quotation 10352The type of an object with thread storage duration shall not have a 10353non-trivial destructor, nor shall it be an array type whose elements 10354(directly or indirectly) have non-trivial destructors. 10355@end quotation 10356 10357@item 10358@b{[basic.stc]} 10359 10360Add ``thread storage duration'' to the list in paragraph 1. 10361 10362Change paragraph 2 10363 10364@quotation 10365Thread, static, and automatic storage durations are associated with 10366objects introduced by declarations [@dots{}]. 10367@end quotation 10368 10369Add @code{__thread} to the list of specifiers in paragraph 3. 10370 10371@item 10372@b{[basic.stc.thread]} 10373 10374New section before @b{[basic.stc.static]} 10375 10376@quotation 10377The keyword @code{__thread} applied to a non-local object gives the 10378object thread storage duration. 10379 10380A local variable or class data member declared both @code{static} 10381and @code{__thread} gives the variable or member thread storage 10382duration. 10383@end quotation 10384 10385@item 10386@b{[basic.stc.static]} 10387 10388Change paragraph 1 10389 10390@quotation 10391All objects which have neither thread storage duration, dynamic 10392storage duration nor are local [@dots{}]. 10393@end quotation 10394 10395@item 10396@b{[dcl.stc]} 10397 10398Add @code{__thread} to the list in paragraph 1. 10399 10400Change paragraph 1 10401 10402@quotation 10403With the exception of @code{__thread}, at most one 10404@var{storage-class-specifier} shall appear in a given 10405@var{decl-specifier-seq}. The @code{__thread} specifier may 10406be used alone, or immediately following the @code{extern} or 10407@code{static} specifiers. [@dots{}] 10408@end quotation 10409 10410Add after paragraph 5 10411 10412@quotation 10413The @code{__thread} specifier can be applied only to the names of objects 10414and to anonymous unions. 10415@end quotation 10416 10417@item 10418@b{[class.mem]} 10419 10420Add after paragraph 6 10421 10422@quotation 10423Non-@code{static} members shall not be @code{__thread}. 10424@end quotation 10425@end itemize 10426 10427@node C++ Extensions 10428@chapter Extensions to the C++ Language 10429@cindex extensions, C++ language 10430@cindex C++ language extensions 10431 10432The GNU compiler provides these extensions to the C++ language (and you 10433can also use most of the C language extensions in your C++ programs). If you 10434want to write code that checks whether these features are available, you can 10435test for the GNU compiler the same way as for C programs: check for a 10436predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to 10437test specifically for GNU C++ (@pxref{Common Predefined Macros,, 10438Predefined Macros,cpp,The GNU C Preprocessor}). 10439 10440@menu 10441* Volatiles:: What constitutes an access to a volatile object. 10442* Restricted Pointers:: C99 restricted pointers and references. 10443* Vague Linkage:: Where G++ puts inlines, vtables and such. 10444* C++ Interface:: You can use a single C++ header file for both 10445 declarations and definitions. 10446* Template Instantiation:: Methods for ensuring that exactly one copy of 10447 each needed template instantiation is emitted. 10448* Bound member functions:: You can extract a function pointer to the 10449 method denoted by a @samp{->*} or @samp{.*} expression. 10450* C++ Attributes:: Variable, function, and type attributes for C++ only. 10451* Namespace Association:: Strong using-directives for namespace association. 10452* Java Exceptions:: Tweaking exception handling to work with Java. 10453* Deprecated Features:: Things will disappear from g++. 10454* Backwards Compatibility:: Compatibilities with earlier definitions of C++. 10455@end menu 10456 10457@node Volatiles 10458@section When is a Volatile Object Accessed? 10459@cindex accessing volatiles 10460@cindex volatile read 10461@cindex volatile write 10462@cindex volatile access 10463 10464Both the C and C++ standard have the concept of volatile objects. These 10465are normally accessed by pointers and used for accessing hardware. The 10466standards encourage compilers to refrain from optimizations concerning 10467accesses to volatile objects. The C standard leaves it implementation 10468defined as to what constitutes a volatile access. The C++ standard omits 10469to specify this, except to say that C++ should behave in a similar manner 10470to C with respect to volatiles, where possible. The minimum either 10471standard specifies is that at a sequence point all previous accesses to 10472volatile objects have stabilized and no subsequent accesses have 10473occurred. Thus an implementation is free to reorder and combine 10474volatile accesses which occur between sequence points, but cannot do so 10475for accesses across a sequence point. The use of volatiles does not 10476allow you to violate the restriction on updating objects multiple times 10477within a sequence point. 10478 10479@xref{Qualifiers implementation, , Volatile qualifier and the C compiler}. 10480 10481The behavior differs slightly between C and C++ in the non-obvious cases: 10482 10483@smallexample 10484volatile int *src = @var{somevalue}; 10485*src; 10486@end smallexample 10487 10488With C, such expressions are rvalues, and GCC interprets this either as a 10489read of the volatile object being pointed to or only as request to evaluate 10490the side-effects. The C++ standard specifies that such expressions do not 10491undergo lvalue to rvalue conversion, and that the type of the dereferenced 10492object may be incomplete. The C++ standard does not specify explicitly 10493that it is this lvalue to rvalue conversion which may be responsible for 10494causing an access. However, there is reason to believe that it is, 10495because otherwise certain simple expressions become undefined. However, 10496because it would surprise most programmers, G++ treats dereferencing a 10497pointer to volatile object of complete type when the value is unused as 10498GCC would do for an equivalent type in C. When the object has incomplete 10499type, G++ issues a warning; if you wish to force an error, you must 10500force a conversion to rvalue with, for instance, a static cast. 10501 10502When using a reference to volatile, G++ does not treat equivalent 10503expressions as accesses to volatiles, but instead issues a warning that 10504no volatile is accessed. The rationale for this is that otherwise it 10505becomes difficult to determine where volatile access occur, and not 10506possible to ignore the return value from functions returning volatile 10507references. Again, if you wish to force a read, cast the reference to 10508an rvalue. 10509 10510@node Restricted Pointers 10511@section Restricting Pointer Aliasing 10512@cindex restricted pointers 10513@cindex restricted references 10514@cindex restricted this pointer 10515 10516As with the C front end, G++ understands the C99 feature of restricted pointers, 10517specified with the @code{__restrict__}, or @code{__restrict} type 10518qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} 10519language flag, @code{restrict} is not a keyword in C++. 10520 10521In addition to allowing restricted pointers, you can specify restricted 10522references, which indicate that the reference is not aliased in the local 10523context. 10524 10525@smallexample 10526void fn (int *__restrict__ rptr, int &__restrict__ rref) 10527@{ 10528 /* @r{@dots{}} */ 10529@} 10530@end smallexample 10531 10532@noindent 10533In the body of @code{fn}, @var{rptr} points to an unaliased integer and 10534@var{rref} refers to a (different) unaliased integer. 10535 10536You may also specify whether a member function's @var{this} pointer is 10537unaliased by using @code{__restrict__} as a member function qualifier. 10538 10539@smallexample 10540void T::fn () __restrict__ 10541@{ 10542 /* @r{@dots{}} */ 10543@} 10544@end smallexample 10545 10546@noindent 10547Within the body of @code{T::fn}, @var{this} will have the effective 10548definition @code{T *__restrict__ const this}. Notice that the 10549interpretation of a @code{__restrict__} member function qualifier is 10550different to that of @code{const} or @code{volatile} qualifier, in that it 10551is applied to the pointer rather than the object. This is consistent with 10552other compilers which implement restricted pointers. 10553 10554As with all outermost parameter qualifiers, @code{__restrict__} is 10555ignored in function definition matching. This means you only need to 10556specify @code{__restrict__} in a function definition, rather than 10557in a function prototype as well. 10558 10559@node Vague Linkage 10560@section Vague Linkage 10561@cindex vague linkage 10562 10563There are several constructs in C++ which require space in the object 10564file but are not clearly tied to a single translation unit. We say that 10565these constructs have ``vague linkage''. Typically such constructs are 10566emitted wherever they are needed, though sometimes we can be more 10567clever. 10568 10569@table @asis 10570@item Inline Functions 10571Inline functions are typically defined in a header file which can be 10572included in many different compilations. Hopefully they can usually be 10573inlined, but sometimes an out-of-line copy is necessary, if the address 10574of the function is taken or if inlining fails. In general, we emit an 10575out-of-line copy in all translation units where one is needed. As an 10576exception, we only emit inline virtual functions with the vtable, since 10577it will always require a copy. 10578 10579Local static variables and string constants used in an inline function 10580are also considered to have vague linkage, since they must be shared 10581between all inlined and out-of-line instances of the function. 10582 10583@item VTables 10584@cindex vtable 10585C++ virtual functions are implemented in most compilers using a lookup 10586table, known as a vtable. The vtable contains pointers to the virtual 10587functions provided by a class, and each object of the class contains a 10588pointer to its vtable (or vtables, in some multiple-inheritance 10589situations). If the class declares any non-inline, non-pure virtual 10590functions, the first one is chosen as the ``key method'' for the class, 10591and the vtable is only emitted in the translation unit where the key 10592method is defined. 10593 10594@emph{Note:} If the chosen key method is later defined as inline, the 10595vtable will still be emitted in every translation unit which defines it. 10596Make sure that any inline virtuals are declared inline in the class 10597body, even if they are not defined there. 10598 10599@item type_info objects 10600@cindex type_info 10601@cindex RTTI 10602C++ requires information about types to be written out in order to 10603implement @samp{dynamic_cast}, @samp{typeid} and exception handling. 10604For polymorphic classes (classes with virtual functions), the type_info 10605object is written out along with the vtable so that @samp{dynamic_cast} 10606can determine the dynamic type of a class object at runtime. For all 10607other types, we write out the type_info object when it is used: when 10608applying @samp{typeid} to an expression, throwing an object, or 10609referring to a type in a catch clause or exception specification. 10610 10611@item Template Instantiations 10612Most everything in this section also applies to template instantiations, 10613but there are other options as well. 10614@xref{Template Instantiation,,Where's the Template?}. 10615 10616@end table 10617 10618When used with GNU ld version 2.8 or later on an ELF system such as 10619GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of 10620these constructs will be discarded at link time. This is known as 10621COMDAT support. 10622 10623On targets that don't support COMDAT, but do support weak symbols, GCC 10624will use them. This way one copy will override all the others, but 10625the unused copies will still take up space in the executable. 10626 10627For targets which do not support either COMDAT or weak symbols, 10628most entities with vague linkage will be emitted as local symbols to 10629avoid duplicate definition errors from the linker. This will not happen 10630for local statics in inlines, however, as having multiple copies will 10631almost certainly break things. 10632 10633@xref{C++ Interface,,Declarations and Definitions in One Header}, for 10634another way to control placement of these constructs. 10635 10636@node C++ Interface 10637@section #pragma interface and implementation 10638 10639@cindex interface and implementation headers, C++ 10640@cindex C++ interface and implementation headers 10641@cindex pragmas, interface and implementation 10642 10643@code{#pragma interface} and @code{#pragma implementation} provide the 10644user with a way of explicitly directing the compiler to emit entities 10645with vague linkage (and debugging information) in a particular 10646translation unit. 10647 10648@emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in 10649most cases, because of COMDAT support and the ``key method'' heuristic 10650mentioned in @ref{Vague Linkage}. Using them can actually cause your 10651program to grow due to unnecessary out-of-line copies of inline 10652functions. Currently (3.4) the only benefit of these 10653@code{#pragma}s is reduced duplication of debugging information, and 10654that should be addressed soon on DWARF 2 targets with the use of 10655COMDAT groups. 10656 10657@table @code 10658@item #pragma interface 10659@itemx #pragma interface "@var{subdir}/@var{objects}.h" 10660@kindex #pragma interface 10661Use this directive in @emph{header files} that define object classes, to save 10662space in most of the object files that use those classes. Normally, 10663local copies of certain information (backup copies of inline member 10664functions, debugging information, and the internal tables that implement 10665virtual functions) must be kept in each object file that includes class 10666definitions. You can use this pragma to avoid such duplication. When a 10667header file containing @samp{#pragma interface} is included in a 10668compilation, this auxiliary information will not be generated (unless 10669the main input source file itself uses @samp{#pragma implementation}). 10670Instead, the object files will contain references to be resolved at link 10671time. 10672 10673The second form of this directive is useful for the case where you have 10674multiple headers with the same name in different directories. If you 10675use this form, you must specify the same string to @samp{#pragma 10676implementation}. 10677 10678@item #pragma implementation 10679@itemx #pragma implementation "@var{objects}.h" 10680@kindex #pragma implementation 10681Use this pragma in a @emph{main input file}, when you want full output from 10682included header files to be generated (and made globally visible). The 10683included header file, in turn, should use @samp{#pragma interface}. 10684Backup copies of inline member functions, debugging information, and the 10685internal tables used to implement virtual functions are all generated in 10686implementation files. 10687 10688@cindex implied @code{#pragma implementation} 10689@cindex @code{#pragma implementation}, implied 10690@cindex naming convention, implementation headers 10691If you use @samp{#pragma implementation} with no argument, it applies to 10692an include file with the same basename@footnote{A file's @dfn{basename} 10693was the name stripped of all leading path information and of trailing 10694suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source 10695file. For example, in @file{allclass.cc}, giving just 10696@samp{#pragma implementation} 10697by itself is equivalent to @samp{#pragma implementation "allclass.h"}. 10698 10699In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as 10700an implementation file whenever you would include it from 10701@file{allclass.cc} even if you never specified @samp{#pragma 10702implementation}. This was deemed to be more trouble than it was worth, 10703however, and disabled. 10704 10705Use the string argument if you want a single implementation file to 10706include code from multiple header files. (You must also use 10707@samp{#include} to include the header file; @samp{#pragma 10708implementation} only specifies how to use the file---it doesn't actually 10709include it.) 10710 10711There is no way to split up the contents of a single header file into 10712multiple implementation files. 10713@end table 10714 10715@cindex inlining and C++ pragmas 10716@cindex C++ pragmas, effect on inlining 10717@cindex pragmas in C++, effect on inlining 10718@samp{#pragma implementation} and @samp{#pragma interface} also have an 10719effect on function inlining. 10720 10721If you define a class in a header file marked with @samp{#pragma 10722interface}, the effect on an inline function defined in that class is 10723similar to an explicit @code{extern} declaration---the compiler emits 10724no code at all to define an independent version of the function. Its 10725definition is used only for inlining with its callers. 10726 10727@opindex fno-implement-inlines 10728Conversely, when you include the same header file in a main source file 10729that declares it as @samp{#pragma implementation}, the compiler emits 10730code for the function itself; this defines a version of the function 10731that can be found via pointers (or by callers compiled without 10732inlining). If all calls to the function can be inlined, you can avoid 10733emitting the function by compiling with @option{-fno-implement-inlines}. 10734If any calls were not inlined, you will get linker errors. 10735 10736@node Template Instantiation 10737@section Where's the Template? 10738@cindex template instantiation 10739 10740C++ templates are the first language feature to require more 10741intelligence from the environment than one usually finds on a UNIX 10742system. Somehow the compiler and linker have to make sure that each 10743template instance occurs exactly once in the executable if it is needed, 10744and not at all otherwise. There are two basic approaches to this 10745problem, which are referred to as the Borland model and the Cfront model. 10746 10747@table @asis 10748@item Borland model 10749Borland C++ solved the template instantiation problem by adding the code 10750equivalent of common blocks to their linker; the compiler emits template 10751instances in each translation unit that uses them, and the linker 10752collapses them together. The advantage of this model is that the linker 10753only has to consider the object files themselves; there is no external 10754complexity to worry about. This disadvantage is that compilation time 10755is increased because the template code is being compiled repeatedly. 10756Code written for this model tends to include definitions of all 10757templates in the header file, since they must be seen to be 10758instantiated. 10759 10760@item Cfront model 10761The AT&T C++ translator, Cfront, solved the template instantiation 10762problem by creating the notion of a template repository, an 10763automatically maintained place where template instances are stored. A 10764more modern version of the repository works as follows: As individual 10765object files are built, the compiler places any template definitions and 10766instantiations encountered in the repository. At link time, the link 10767wrapper adds in the objects in the repository and compiles any needed 10768instances that were not previously emitted. The advantages of this 10769model are more optimal compilation speed and the ability to use the 10770system linker; to implement the Borland model a compiler vendor also 10771needs to replace the linker. The disadvantages are vastly increased 10772complexity, and thus potential for error; for some code this can be 10773just as transparent, but in practice it can been very difficult to build 10774multiple programs in one directory and one program in multiple 10775directories. Code written for this model tends to separate definitions 10776of non-inline member templates into a separate file, which should be 10777compiled separately. 10778@end table 10779 10780When used with GNU ld version 2.8 or later on an ELF system such as 10781GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the 10782Borland model. On other systems, G++ implements neither automatic 10783model. 10784 10785A future version of G++ will support a hybrid model whereby the compiler 10786will emit any instantiations for which the template definition is 10787included in the compile, and store template definitions and 10788instantiation context information into the object file for the rest. 10789The link wrapper will extract that information as necessary and invoke 10790the compiler to produce the remaining instantiations. The linker will 10791then combine duplicate instantiations. 10792 10793In the mean time, you have the following options for dealing with 10794template instantiations: 10795 10796@enumerate 10797@item 10798@opindex frepo 10799Compile your template-using code with @option{-frepo}. The compiler will 10800generate files with the extension @samp{.rpo} listing all of the 10801template instantiations used in the corresponding object files which 10802could be instantiated there; the link wrapper, @samp{collect2}, will 10803then update the @samp{.rpo} files to tell the compiler where to place 10804those instantiations and rebuild any affected object files. The 10805link-time overhead is negligible after the first pass, as the compiler 10806will continue to place the instantiations in the same files. 10807 10808This is your best option for application code written for the Borland 10809model, as it will just work. Code written for the Cfront model will 10810need to be modified so that the template definitions are available at 10811one or more points of instantiation; usually this is as simple as adding 10812@code{#include <tmethods.cc>} to the end of each template header. 10813 10814For library code, if you want the library to provide all of the template 10815instantiations it needs, just try to link all of its object files 10816together; the link will fail, but cause the instantiations to be 10817generated as a side effect. Be warned, however, that this may cause 10818conflicts if multiple libraries try to provide the same instantiations. 10819For greater control, use explicit instantiation as described in the next 10820option. 10821 10822@item 10823@opindex fno-implicit-templates 10824Compile your code with @option{-fno-implicit-templates} to disable the 10825implicit generation of template instances, and explicitly instantiate 10826all the ones you use. This approach requires more knowledge of exactly 10827which instances you need than do the others, but it's less 10828mysterious and allows greater control. You can scatter the explicit 10829instantiations throughout your program, perhaps putting them in the 10830translation units where the instances are used or the translation units 10831that define the templates themselves; you can put all of the explicit 10832instantiations you need into one big file; or you can create small files 10833like 10834 10835@smallexample 10836#include "Foo.h" 10837#include "Foo.cc" 10838 10839template class Foo<int>; 10840template ostream& operator << 10841 (ostream&, const Foo<int>&); 10842@end smallexample 10843 10844for each of the instances you need, and create a template instantiation 10845library from those. 10846 10847If you are using Cfront-model code, you can probably get away with not 10848using @option{-fno-implicit-templates} when compiling files that don't 10849@samp{#include} the member template definitions. 10850 10851If you use one big file to do the instantiations, you may want to 10852compile it without @option{-fno-implicit-templates} so you get all of the 10853instances required by your explicit instantiations (but not by any 10854other files) without having to specify them as well. 10855 10856G++ has extended the template instantiation syntax given in the ISO 10857standard to allow forward declaration of explicit instantiations 10858(with @code{extern}), instantiation of the compiler support data for a 10859template class (i.e.@: the vtable) without instantiating any of its 10860members (with @code{inline}), and instantiation of only the static data 10861members of a template class, without the support data or member 10862functions (with (@code{static}): 10863 10864@smallexample 10865extern template int max (int, int); 10866inline template class Foo<int>; 10867static template class Foo<int>; 10868@end smallexample 10869 10870@item 10871Do nothing. Pretend G++ does implement automatic instantiation 10872management. Code written for the Borland model will work fine, but 10873each translation unit will contain instances of each of the templates it 10874uses. In a large program, this can lead to an unacceptable amount of code 10875duplication. 10876@end enumerate 10877 10878@node Bound member functions 10879@section Extracting the function pointer from a bound pointer to member function 10880@cindex pmf 10881@cindex pointer to member function 10882@cindex bound pointer to member function 10883 10884In C++, pointer to member functions (PMFs) are implemented using a wide 10885pointer of sorts to handle all the possible call mechanisms; the PMF 10886needs to store information about how to adjust the @samp{this} pointer, 10887and if the function pointed to is virtual, where to find the vtable, and 10888where in the vtable to look for the member function. If you are using 10889PMFs in an inner loop, you should really reconsider that decision. If 10890that is not an option, you can extract the pointer to the function that 10891would be called for a given object/PMF pair and call it directly inside 10892the inner loop, to save a bit of time. 10893 10894Note that you will still be paying the penalty for the call through a 10895function pointer; on most modern architectures, such a call defeats the 10896branch prediction features of the CPU@. This is also true of normal 10897virtual function calls. 10898 10899The syntax for this extension is 10900 10901@smallexample 10902extern A a; 10903extern int (A::*fp)(); 10904typedef int (*fptr)(A *); 10905 10906fptr p = (fptr)(a.*fp); 10907@end smallexample 10908 10909For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), 10910no object is needed to obtain the address of the function. They can be 10911converted to function pointers directly: 10912 10913@smallexample 10914fptr p1 = (fptr)(&A::foo); 10915@end smallexample 10916 10917@opindex Wno-pmf-conversions 10918You must specify @option{-Wno-pmf-conversions} to use this extension. 10919 10920@node C++ Attributes 10921@section C++-Specific Variable, Function, and Type Attributes 10922 10923Some attributes only make sense for C++ programs. 10924 10925@table @code 10926@item init_priority (@var{priority}) 10927@cindex init_priority attribute 10928 10929 10930In Standard C++, objects defined at namespace scope are guaranteed to be 10931initialized in an order in strict accordance with that of their definitions 10932@emph{in a given translation unit}. No guarantee is made for initializations 10933across translation units. However, GNU C++ allows users to control the 10934order of initialization of objects defined at namespace scope with the 10935@code{init_priority} attribute by specifying a relative @var{priority}, 10936a constant integral expression currently bounded between 101 and 65535 10937inclusive. Lower numbers indicate a higher priority. 10938 10939In the following example, @code{A} would normally be created before 10940@code{B}, but the @code{init_priority} attribute has reversed that order: 10941 10942@smallexample 10943Some_Class A __attribute__ ((init_priority (2000))); 10944Some_Class B __attribute__ ((init_priority (543))); 10945@end smallexample 10946 10947@noindent 10948Note that the particular values of @var{priority} do not matter; only their 10949relative ordering. 10950 10951@item java_interface 10952@cindex java_interface attribute 10953 10954This type attribute informs C++ that the class is a Java interface. It may 10955only be applied to classes declared within an @code{extern "Java"} block. 10956Calls to methods declared in this interface will be dispatched using GCJ's 10957interface table mechanism, instead of regular virtual table dispatch. 10958 10959@end table 10960 10961See also @xref{Namespace Association}. 10962 10963@node Namespace Association 10964@section Namespace Association 10965 10966@strong{Caution:} The semantics of this extension are not fully 10967defined. Users should refrain from using this extension as its 10968semantics may change subtly over time. It is possible that this 10969extension will be removed in future versions of G++. 10970 10971A using-directive with @code{__attribute ((strong))} is stronger 10972than a normal using-directive in two ways: 10973 10974@itemize @bullet 10975@item 10976Templates from the used namespace can be specialized and explicitly 10977instantiated as though they were members of the using namespace. 10978 10979@item 10980The using namespace is considered an associated namespace of all 10981templates in the used namespace for purposes of argument-dependent 10982name lookup. 10983@end itemize 10984 10985The used namespace must be nested within the using namespace so that 10986normal unqualified lookup works properly. 10987 10988This is useful for composing a namespace transparently from 10989implementation namespaces. For example: 10990 10991@smallexample 10992namespace std @{ 10993 namespace debug @{ 10994 template <class T> struct A @{ @}; 10995 @} 10996 using namespace debug __attribute ((__strong__)); 10997 template <> struct A<int> @{ @}; // @r{ok to specialize} 10998 10999 template <class T> void f (A<T>); 11000@} 11001 11002int main() 11003@{ 11004 f (std::A<float>()); // @r{lookup finds} std::f 11005 f (std::A<int>()); 11006@} 11007@end smallexample 11008 11009@node Java Exceptions 11010@section Java Exceptions 11011 11012The Java language uses a slightly different exception handling model 11013from C++. Normally, GNU C++ will automatically detect when you are 11014writing C++ code that uses Java exceptions, and handle them 11015appropriately. However, if C++ code only needs to execute destructors 11016when Java exceptions are thrown through it, GCC will guess incorrectly. 11017Sample problematic code is: 11018 11019@smallexample 11020 struct S @{ ~S(); @}; 11021 extern void bar(); // @r{is written in Java, and may throw exceptions} 11022 void foo() 11023 @{ 11024 S s; 11025 bar(); 11026 @} 11027@end smallexample 11028 11029@noindent 11030The usual effect of an incorrect guess is a link failure, complaining of 11031a missing routine called @samp{__gxx_personality_v0}. 11032 11033You can inform the compiler that Java exceptions are to be used in a 11034translation unit, irrespective of what it might think, by writing 11035@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This 11036@samp{#pragma} must appear before any functions that throw or catch 11037exceptions, or run destructors when exceptions are thrown through them. 11038 11039You cannot mix Java and C++ exceptions in the same translation unit. It 11040is believed to be safe to throw a C++ exception from one file through 11041another file compiled for the Java exception model, or vice versa, but 11042there may be bugs in this area. 11043 11044@node Deprecated Features 11045@section Deprecated Features 11046 11047In the past, the GNU C++ compiler was extended to experiment with new 11048features, at a time when the C++ language was still evolving. Now that 11049the C++ standard is complete, some of those features are superseded by 11050superior alternatives. Using the old features might cause a warning in 11051some cases that the feature will be dropped in the future. In other 11052cases, the feature might be gone already. 11053 11054While the list below is not exhaustive, it documents some of the options 11055that are now deprecated: 11056 11057@table @code 11058@item -fexternal-templates 11059@itemx -falt-external-templates 11060These are two of the many ways for G++ to implement template 11061instantiation. @xref{Template Instantiation}. The C++ standard clearly 11062defines how template definitions have to be organized across 11063implementation units. G++ has an implicit instantiation mechanism that 11064should work just fine for standard-conforming code. 11065 11066@item -fstrict-prototype 11067@itemx -fno-strict-prototype 11068Previously it was possible to use an empty prototype parameter list to 11069indicate an unspecified number of parameters (like C), rather than no 11070parameters, as C++ demands. This feature has been removed, except where 11071it is required for backwards compatibility @xref{Backwards Compatibility}. 11072@end table 11073 11074G++ allows a virtual function returning @samp{void *} to be overridden 11075by one returning a different pointer type. This extension to the 11076covariant return type rules is now deprecated and will be removed from a 11077future version. 11078 11079The G++ minimum and maximum operators (@samp{<?} and @samp{>?}) and 11080their compound forms (@samp{<?=}) and @samp{>?=}) have been deprecated 11081and will be removed in a future version. Code using these operators 11082should be modified to use @code{std::min} and @code{std::max} instead. 11083 11084The named return value extension has been deprecated, and is now 11085removed from G++. 11086 11087The use of initializer lists with new expressions has been deprecated, 11088and is now removed from G++. 11089 11090Floating and complex non-type template parameters have been deprecated, 11091and are now removed from G++. 11092 11093The implicit typename extension has been deprecated and is now 11094removed from G++. 11095 11096The use of default arguments in function pointers, function typedefs 11097and other places where they are not permitted by the standard is 11098deprecated and will be removed from a future version of G++. 11099 11100G++ allows floating-point literals to appear in integral constant expressions, 11101e.g. @samp{ enum E @{ e = int(2.2 * 3.7) @} } 11102This extension is deprecated and will be removed from a future version. 11103 11104G++ allows static data members of const floating-point type to be declared 11105with an initializer in a class definition. The standard only allows 11106initializers for static members of const integral types and const 11107enumeration types so this extension has been deprecated and will be removed 11108from a future version. 11109 11110@node Backwards Compatibility 11111@section Backwards Compatibility 11112@cindex Backwards Compatibility 11113@cindex ARM [Annotated C++ Reference Manual] 11114 11115Now that there is a definitive ISO standard C++, G++ has a specification 11116to adhere to. The C++ language evolved over time, and features that 11117used to be acceptable in previous drafts of the standard, such as the ARM 11118[Annotated C++ Reference Manual], are no longer accepted. In order to allow 11119compilation of C++ written to such drafts, G++ contains some backwards 11120compatibilities. @emph{All such backwards compatibility features are 11121liable to disappear in future versions of G++.} They should be considered 11122deprecated @xref{Deprecated Features}. 11123 11124@table @code 11125@item For scope 11126If a variable is declared at for scope, it used to remain in scope until 11127the end of the scope which contained the for statement (rather than just 11128within the for scope). G++ retains this, but issues a warning, if such a 11129variable is accessed outside the for scope. 11130 11131@item Implicit C language 11132Old C system header files did not contain an @code{extern "C" @{@dots{}@}} 11133scope to set the language. On such systems, all header files are 11134implicitly scoped inside a C language scope. Also, an empty prototype 11135@code{()} will be treated as an unspecified number of arguments, rather 11136than no arguments, as C++ demands. 11137@end table 11138