extend.texi revision 261188
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@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 62* Label Attributes:: Specifying attributes of labels and statements. 63@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 64* Alignment:: Inquiring about the alignment of a type or variable. 65* Inline:: Defining inline functions (as fast as macros). 66* Extended Asm:: Assembler instructions with C expressions as operands. 67 (With them you can define ``built-in'' functions.) 68* Constraints:: Constraints for asm operands 69* Asm Labels:: Specifying the assembler name to use for a C symbol. 70* Explicit Reg Vars:: Defining variables residing in specified registers. 71* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. 72* Incomplete Enums:: @code{enum foo;}, with details to follow. 73* Function Names:: Printable strings which are the name of the current 74 function. 75* Return Address:: Getting the return or frame address of a function. 76* Vector Extensions:: Using vector instructions through built-in functions. 77* Offsetof:: Special syntax for implementing @code{offsetof}. 78* Atomic Builtins:: Built-in functions for atomic memory access. 79* Object Size Checking:: Built-in functions for limited buffer overflow 80 checking. 81* Other Builtins:: Other built-in functions. 82* Target Builtins:: Built-in functions specific to particular targets. 83* Target Format Checks:: Format checks specific to particular targets. 84* Pragmas:: Pragmas accepted by GCC. 85* Unnamed Fields:: Unnamed struct/union fields within structs/unions. 86* Thread-Local:: Per-thread variables. 87* Binary constants:: Binary constants using the @samp{0b} prefix. 88@c APPLE LOCAL blocks 7205047 5811887 89* Blocks:: Anonymous functions (closures). 90@end menu 91 92@node Statement Exprs 93@section Statements and Declarations in Expressions 94@cindex statements inside expressions 95@cindex declarations inside expressions 96@cindex expressions containing statements 97@cindex macros, statements in expressions 98 99@c the above section title wrapped and causes an underfull hbox.. i 100@c changed it from "within" to "in". --mew 4feb93 101A compound statement enclosed in parentheses may appear as an expression 102in GNU C@. This allows you to use loops, switches, and local variables 103within an expression. 104 105Recall that a compound statement is a sequence of statements surrounded 106by braces; in this construct, parentheses go around the braces. For 107example: 108 109@smallexample 110(@{ int y = foo (); int z; 111 if (y > 0) z = y; 112 else z = - y; 113 z; @}) 114@end smallexample 115 116@noindent 117is a valid (though slightly more complex than necessary) expression 118for the absolute value of @code{foo ()}. 119 120The last thing in the compound statement should be an expression 121followed by a semicolon; the value of this subexpression serves as the 122value of the entire construct. (If you use some other kind of statement 123last within the braces, the construct has type @code{void}, and thus 124effectively no value.) 125 126This feature is especially useful in making macro definitions ``safe'' (so 127that they evaluate each operand exactly once). For example, the 128``maximum'' function is commonly defined as a macro in standard C as 129follows: 130 131@smallexample 132#define max(a,b) ((a) > (b) ? (a) : (b)) 133@end smallexample 134 135@noindent 136@cindex side effects, macro argument 137But this definition computes either @var{a} or @var{b} twice, with bad 138results if the operand has side effects. In GNU C, if you know the 139type of the operands (here taken as @code{int}), you can define 140the macro safely as follows: 141 142@smallexample 143#define maxint(a,b) \ 144 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) 145@end smallexample 146 147Embedded statements are not allowed in constant expressions, such as 148the value of an enumeration constant, the width of a bit-field, or 149the initial value of a static variable. 150 151If you don't know the type of the operand, you can still do this, but you 152must use @code{typeof} (@pxref{Typeof}). 153 154In G++, the result value of a statement expression undergoes array and 155function pointer decay, and is returned by value to the enclosing 156expression. For instance, if @code{A} is a class, then 157 158@smallexample 159 A a; 160 161 (@{a;@}).Foo () 162@end smallexample 163 164@noindent 165will construct a temporary @code{A} object to hold the result of the 166statement expression, and that will be used to invoke @code{Foo}. 167Therefore the @code{this} pointer observed by @code{Foo} will not be the 168address of @code{a}. 169 170Any temporaries created within a statement within a statement expression 171will be destroyed at the statement's end. This makes statement 172expressions inside macros slightly different from function calls. In 173the latter case temporaries introduced during argument evaluation will 174be destroyed at the end of the statement that includes the function 175call. In the statement expression case they will be destroyed during 176the statement expression. For instance, 177 178@smallexample 179#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) 180template<typename T> T function(T a) @{ T b = a; return b + 3; @} 181 182void foo () 183@{ 184 macro (X ()); 185 function (X ()); 186@} 187@end smallexample 188 189@noindent 190will have different places where temporaries are destroyed. For the 191@code{macro} case, the temporary @code{X} will be destroyed just after 192the initialization of @code{b}. In the @code{function} case that 193temporary will be destroyed when the function returns. 194 195These considerations mean that it is probably a bad idea to use 196statement-expressions of this form in header files that are designed to 197work with C++. (Note that some versions of the GNU C Library contained 198header files using statement-expression that lead to precisely this 199bug.) 200 201Jumping into a statement expression with @code{goto} or using a 202@code{switch} statement outside the statement expression with a 203@code{case} or @code{default} label inside the statement expression is 204not permitted. Jumping into a statement expression with a computed 205@code{goto} (@pxref{Labels as Values}) yields undefined behavior. 206Jumping out of a statement expression is permitted, but if the 207statement expression is part of a larger expression then it is 208unspecified which other subexpressions of that expression have been 209evaluated except where the language definition requires certain 210subexpressions to be evaluated before or after the statement 211expression. In any case, as with a function call the evaluation of a 212statement expression is not interleaved with the evaluation of other 213parts of the containing expression. For example, 214 215@smallexample 216 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); 217@end smallexample 218 219@noindent 220will call @code{foo} and @code{bar1} and will not call @code{baz} but 221may or may not call @code{bar2}. If @code{bar2} is called, it will be 222called after @code{foo} and before @code{bar1} 223 224@node Local Labels 225@section Locally Declared Labels 226@cindex local labels 227@cindex macros, local labels 228 229GCC allows you to declare @dfn{local labels} in any nested block 230scope. A local label is just like an ordinary label, but you can 231only reference it (with a @code{goto} statement, or by taking its 232address) within the block in which it was declared. 233 234A local label declaration looks like this: 235 236@smallexample 237__label__ @var{label}; 238@end smallexample 239 240@noindent 241or 242 243@smallexample 244__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; 245@end smallexample 246 247Local label declarations must come at the beginning of the block, 248before any ordinary declarations or statements. 249 250The label declaration defines the label @emph{name}, but does not define 251the label itself. You must do this in the usual way, with 252@code{@var{label}:}, within the statements of the statement expression. 253 254The local label feature is useful for complex macros. If a macro 255contains nested loops, a @code{goto} can be useful for breaking out of 256them. However, an ordinary label whose scope is the whole function 257cannot be used: if the macro can be expanded several times in one 258function, the label will be multiply defined in that function. A 259local label avoids this problem. For example: 260 261@smallexample 262#define SEARCH(value, array, target) \ 263do @{ \ 264 __label__ found; \ 265 typeof (target) _SEARCH_target = (target); \ 266 typeof (*(array)) *_SEARCH_array = (array); \ 267 int i, j; \ 268 int value; \ 269 for (i = 0; i < max; i++) \ 270 for (j = 0; j < max; j++) \ 271 if (_SEARCH_array[i][j] == _SEARCH_target) \ 272 @{ (value) = i; goto found; @} \ 273 (value) = -1; \ 274 found:; \ 275@} while (0) 276@end smallexample 277 278This could also be written using a statement-expression: 279 280@smallexample 281#define SEARCH(array, target) \ 282(@{ \ 283 __label__ found; \ 284 typeof (target) _SEARCH_target = (target); \ 285 typeof (*(array)) *_SEARCH_array = (array); \ 286 int i, j; \ 287 int value; \ 288 for (i = 0; i < max; i++) \ 289 for (j = 0; j < max; j++) \ 290 if (_SEARCH_array[i][j] == _SEARCH_target) \ 291 @{ value = i; goto found; @} \ 292 value = -1; \ 293 found: \ 294 value; \ 295@}) 296@end smallexample 297 298Local label declarations also make the labels they declare visible to 299nested functions, if there are any. @xref{Nested Functions}, for details. 300 301@node Labels as Values 302@section Labels as Values 303@cindex labels as values 304@cindex computed gotos 305@cindex goto with computed label 306@cindex address of a label 307 308You can get the address of a label defined in the current function 309(or a containing function) with the unary operator @samp{&&}. The 310value has type @code{void *}. This value is a constant and can be used 311wherever a constant of that type is valid. For example: 312 313@smallexample 314void *ptr; 315/* @r{@dots{}} */ 316ptr = &&foo; 317@end smallexample 318 319To use these values, you need to be able to jump to one. This is done 320with the computed goto statement@footnote{The analogous feature in 321Fortran is called an assigned goto, but that name seems inappropriate in 322C, where one can do more than simply store label addresses in label 323variables.}, @code{goto *@var{exp};}. For example, 324 325@smallexample 326goto *ptr; 327@end smallexample 328 329@noindent 330Any expression of type @code{void *} is allowed. 331 332One way of using these constants is in initializing a static array that 333will serve as a jump table: 334 335@smallexample 336static void *array[] = @{ &&foo, &&bar, &&hack @}; 337@end smallexample 338 339Then you can select a label with indexing, like this: 340 341@smallexample 342goto *array[i]; 343@end smallexample 344 345@noindent 346Note that this does not check whether the subscript is in bounds---array 347indexing in C never does that. 348 349Such an array of label values serves a purpose much like that of the 350@code{switch} statement. The @code{switch} statement is cleaner, so 351use that rather than an array unless the problem does not fit a 352@code{switch} statement very well. 353 354Another use of label values is in an interpreter for threaded code. 355The labels within the interpreter function can be stored in the 356threaded code for super-fast dispatching. 357 358You may not use this mechanism to jump to code in a different function. 359If you do that, totally unpredictable things will happen. The best way to 360avoid this is to store the label address only in automatic variables and 361never pass it as an argument. 362 363An alternate way to write the above example is 364 365@smallexample 366static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, 367 &&hack - &&foo @}; 368goto *(&&foo + array[i]); 369@end smallexample 370 371@noindent 372This is more friendly to code living in shared libraries, as it reduces 373the number of dynamic relocations that are needed, and by consequence, 374allows the data to be read-only. 375 376@node Nested Functions 377@section Nested Functions 378@cindex nested functions 379@cindex downward funargs 380@cindex thunks 381 382A @dfn{nested function} is a function defined inside another function. 383@c APPLE LOCAL begin nested functions 4357979 384Nested functions are not supported for GNU C++ and are disable by 385default on FreeBSD. The @option{-fnested-functions} and 386@option{-fno-nested-functions} options can be used to enable and 387disable nested function suppport. The nested function's name is local 388to the block where it is defined. For example, here we define a 389nested function named @code{square}, and call it twice: 390@c APPLE LOCAL end nested functions 4357979 391 392@smallexample 393@group 394foo (double a, double b) 395@{ 396 double square (double z) @{ return z * z; @} 397 398 return square (a) + square (b); 399@} 400@end group 401@end smallexample 402 403The nested function can access all the variables of the containing 404function that are visible at the point of its definition. This is 405called @dfn{lexical scoping}. For example, here we show a nested 406function which uses an inherited variable named @code{offset}: 407 408@smallexample 409@group 410bar (int *array, int offset, int size) 411@{ 412 int access (int *array, int index) 413 @{ return array[index + offset]; @} 414 int i; 415 /* @r{@dots{}} */ 416 for (i = 0; i < size; i++) 417 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 418@} 419@end group 420@end smallexample 421 422Nested function definitions are permitted within functions in the places 423where variable definitions are allowed; that is, in any block, mixed 424with the other declarations and statements in the block. 425 426It is possible to call the nested function from outside the scope of its 427name by storing its address or passing the address to another function: 428 429@smallexample 430hack (int *array, int size) 431@{ 432 void store (int index, int value) 433 @{ array[index] = value; @} 434 435 intermediate (store, size); 436@} 437@end smallexample 438 439Here, the function @code{intermediate} receives the address of 440@code{store} as an argument. If @code{intermediate} calls @code{store}, 441the arguments given to @code{store} are used to store into @code{array}. 442But this technique works only so long as the containing function 443(@code{hack}, in this example) does not exit. 444 445If you try to call the nested function through its address after the 446containing function has exited, all hell will break loose. If you try 447to call it after a containing scope level has exited, and if it refers 448to some of the variables that are no longer in scope, you may be lucky, 449but it's not wise to take the risk. If, however, the nested function 450does not refer to anything that has gone out of scope, you should be 451safe. 452 453GCC implements taking the address of a nested function using a technique 454called @dfn{trampolines}. A paper describing them is available as 455 456@noindent 457@uref{http://people.debian.org/~aaronl/Usenix88-lexic.pdf}. 458 459A nested function can jump to a label inherited from a containing 460function, provided the label was explicitly declared in the containing 461function (@pxref{Local Labels}). Such a jump returns instantly to the 462containing function, exiting the nested function which did the 463@code{goto} and any intermediate functions as well. Here is an example: 464 465@smallexample 466@group 467bar (int *array, int offset, int size) 468@{ 469 __label__ failure; 470 int access (int *array, int index) 471 @{ 472 if (index > size) 473 goto failure; 474 return array[index + offset]; 475 @} 476 int i; 477 /* @r{@dots{}} */ 478 for (i = 0; i < size; i++) 479 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 480 /* @r{@dots{}} */ 481 return 0; 482 483 /* @r{Control comes here from @code{access} 484 if it detects an error.} */ 485 failure: 486 return -1; 487@} 488@end group 489@end smallexample 490 491A nested function always has no linkage. Declaring one with 492@code{extern} or @code{static} is erroneous. If you need to declare the nested function 493before its definition, use @code{auto} (which is otherwise meaningless 494for function declarations). 495 496@smallexample 497bar (int *array, int offset, int size) 498@{ 499 __label__ failure; 500 auto int access (int *, int); 501 /* @r{@dots{}} */ 502 int access (int *array, int index) 503 @{ 504 if (index > size) 505 goto failure; 506 return array[index + offset]; 507 @} 508 /* @r{@dots{}} */ 509@} 510@end smallexample 511 512@node Constructing Calls 513@section Constructing Function Calls 514@cindex constructing calls 515@cindex forwarding calls 516 517Using the built-in functions described below, you can record 518the arguments a function received, and call another function 519with the same arguments, without knowing the number or types 520of the arguments. 521 522You can also record the return value of that function call, 523and later return that value, without knowing what data type 524the function tried to return (as long as your caller expects 525that data type). 526 527However, these built-in functions may interact badly with some 528sophisticated features or other extensions of the language. It 529is, therefore, not recommended to use them outside very simple 530functions acting as mere forwarders for their arguments. 531 532@deftypefn {Built-in Function} {void *} __builtin_apply_args () 533This built-in function returns a pointer to data 534describing how to perform a call with the same arguments as were passed 535to the current function. 536 537The function saves the arg pointer register, structure value address, 538and all registers that might be used to pass arguments to a function 539into a block of memory allocated on the stack. Then it returns the 540address of that block. 541@end deftypefn 542 543@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) 544This built-in function invokes @var{function} 545with a copy of the parameters described by @var{arguments} 546and @var{size}. 547 548The value of @var{arguments} should be the value returned by 549@code{__builtin_apply_args}. The argument @var{size} specifies the size 550of the stack argument data, in bytes. 551 552This function returns a pointer to data describing 553how to return whatever value was returned by @var{function}. The data 554is saved in a block of memory allocated on the stack. 555 556It is not always simple to compute the proper value for @var{size}. The 557value is used by @code{__builtin_apply} to compute the amount of data 558that should be pushed on the stack and copied from the incoming argument 559area. 560@end deftypefn 561 562@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) 563This built-in function returns the value described by @var{result} from 564the containing function. You should specify, for @var{result}, a value 565returned by @code{__builtin_apply}. 566@end deftypefn 567 568@node Typeof 569@section Referring to a Type with @code{typeof} 570@findex typeof 571@findex sizeof 572@cindex macros, types of arguments 573 574Another way to refer to the type of an expression is with @code{typeof}. 575The syntax of using of this keyword looks like @code{sizeof}, but the 576construct acts semantically like a type name defined with @code{typedef}. 577 578There are two ways of writing the argument to @code{typeof}: with an 579expression or with a type. Here is an example with an expression: 580 581@smallexample 582typeof (x[0](1)) 583@end smallexample 584 585@noindent 586This assumes that @code{x} is an array of pointers to functions; 587the type described is that of the values of the functions. 588 589Here is an example with a typename as the argument: 590 591@smallexample 592typeof (int *) 593@end smallexample 594 595@noindent 596Here the type described is that of pointers to @code{int}. 597 598If you are writing a header file that must work when included in ISO C 599programs, write @code{__typeof__} instead of @code{typeof}. 600@xref{Alternate Keywords}. 601 602A @code{typeof}-construct can be used anywhere a typedef name could be 603used. For example, you can use it in a declaration, in a cast, or inside 604of @code{sizeof} or @code{typeof}. 605 606@code{typeof} is often useful in conjunction with the 607statements-within-expressions feature. Here is how the two together can 608be used to define a safe ``maximum'' macro that operates on any 609arithmetic type and evaluates each of its arguments exactly once: 610 611@smallexample 612#define max(a,b) \ 613 (@{ typeof (a) _a = (a); \ 614 typeof (b) _b = (b); \ 615 _a > _b ? _a : _b; @}) 616@end smallexample 617 618@cindex underscores in variables in macros 619@cindex @samp{_} in variables in macros 620@cindex local variables in macros 621@cindex variables, local, in macros 622@cindex macros, local variables in 623 624The reason for using names that start with underscores for the local 625variables is to avoid conflicts with variable names that occur within the 626expressions that are substituted for @code{a} and @code{b}. Eventually we 627hope to design a new form of declaration syntax that allows you to declare 628variables whose scopes start only after their initializers; this will be a 629more reliable way to prevent such conflicts. 630 631@noindent 632Some more examples of the use of @code{typeof}: 633 634@itemize @bullet 635@item 636This declares @code{y} with the type of what @code{x} points to. 637 638@smallexample 639typeof (*x) y; 640@end smallexample 641 642@item 643This declares @code{y} as an array of such values. 644 645@smallexample 646typeof (*x) y[4]; 647@end smallexample 648 649@item 650This declares @code{y} as an array of pointers to characters: 651 652@smallexample 653typeof (typeof (char *)[4]) y; 654@end smallexample 655 656@noindent 657It is equivalent to the following traditional C declaration: 658 659@smallexample 660char *y[4]; 661@end smallexample 662 663To see the meaning of the declaration using @code{typeof}, and why it 664might be a useful way to write, rewrite it with these macros: 665 666@smallexample 667#define pointer(T) typeof(T *) 668#define array(T, N) typeof(T [N]) 669@end smallexample 670 671@noindent 672Now the declaration can be rewritten this way: 673 674@smallexample 675array (pointer (char), 4) y; 676@end smallexample 677 678@noindent 679Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 680pointers to @code{char}. 681@end itemize 682 683@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported 684a more limited extension which permitted one to write 685 686@smallexample 687typedef @var{T} = @var{expr}; 688@end smallexample 689 690@noindent 691with the effect of declaring @var{T} to have the type of the expression 692@var{expr}. This extension does not work with GCC 3 (versions between 6933.0 and 3.2 will crash; 3.2.1 and later give an error). Code which 694relies on it should be rewritten to use @code{typeof}: 695 696@smallexample 697typedef typeof(@var{expr}) @var{T}; 698@end smallexample 699 700@noindent 701This will work with all versions of GCC@. 702 703@node Conditionals 704@section Conditionals with Omitted Operands 705@cindex conditional expressions, extensions 706@cindex omitted middle-operands 707@cindex middle-operands, omitted 708@cindex extensions, @code{?:} 709@cindex @code{?:} extensions 710 711The middle operand in a conditional expression may be omitted. Then 712if the first operand is nonzero, its value is the value of the conditional 713expression. 714 715Therefore, the expression 716 717@smallexample 718x ? : y 719@end smallexample 720 721@noindent 722has the value of @code{x} if that is nonzero; otherwise, the value of 723@code{y}. 724 725This example is perfectly equivalent to 726 727@smallexample 728x ? x : y 729@end smallexample 730 731@cindex side effect in ?: 732@cindex ?: side effect 733@noindent 734In this simple case, the ability to omit the middle operand is not 735especially useful. When it becomes useful is when the first operand does, 736or may (if it is a macro argument), contain a side effect. Then repeating 737the operand in the middle would perform the side effect twice. Omitting 738the middle operand uses the value already computed without the undesirable 739effects of recomputing it. 740 741@node Long Long 742@section Double-Word Integers 743@cindex @code{long long} data types 744@cindex double-word arithmetic 745@cindex multiprecision arithmetic 746@cindex @code{LL} integer suffix 747@cindex @code{ULL} integer suffix 748 749ISO C99 supports data types for integers that are at least 64 bits wide, 750and as an extension GCC supports them in C89 mode and in C++. 751Simply write @code{long long int} for a signed integer, or 752@code{unsigned long long int} for an unsigned integer. To make an 753integer constant of type @code{long long int}, add the suffix @samp{LL} 754to the integer. To make an integer constant of type @code{unsigned long 755long int}, add the suffix @samp{ULL} to the integer. 756 757You can use these types in arithmetic like any other integer types. 758Addition, subtraction, and bitwise boolean operations on these types 759are open-coded on all types of machines. Multiplication is open-coded 760if the machine supports fullword-to-doubleword a widening multiply 761instruction. Division and shifts are open-coded only on machines that 762provide special support. The operations that are not open-coded use 763special library routines that come with GCC@. 764 765There may be pitfalls when you use @code{long long} types for function 766arguments, unless you declare function prototypes. If a function 767expects type @code{int} for its argument, and you pass a value of type 768@code{long long int}, confusion will result because the caller and the 769subroutine will disagree about the number of bytes for the argument. 770Likewise, if the function expects @code{long long int} and you pass 771@code{int}. The best way to avoid such problems is to use prototypes. 772 773@node Complex 774@section Complex Numbers 775@cindex complex numbers 776@cindex @code{_Complex} keyword 777@cindex @code{__complex__} keyword 778 779ISO C99 supports complex floating data types, and as an extension GCC 780supports them in C89 mode and in C++, and supports complex integer data 781types which are not part of ISO C99. You can declare complex types 782using the keyword @code{_Complex}. As an extension, the older GNU 783keyword @code{__complex__} is also supported. 784 785For example, @samp{_Complex double x;} declares @code{x} as a 786variable whose real part and imaginary part are both of type 787@code{double}. @samp{_Complex short int y;} declares @code{y} to 788have real and imaginary parts of type @code{short int}; this is not 789likely to be useful, but it shows that the set of complex types is 790complete. 791 792To write a constant with a complex data type, use the suffix @samp{i} or 793@samp{j} (either one; they are equivalent). For example, @code{2.5fi} 794has type @code{_Complex float} and @code{3i} has type 795@code{_Complex int}. Such a constant always has a pure imaginary 796value, but you can form any complex value you like by adding one to a 797real constant. This is a GNU extension; if you have an ISO C99 798conforming C library (such as GNU libc), and want to construct complex 799constants of floating type, you should include @code{<complex.h>} and 800use the macros @code{I} or @code{_Complex_I} instead. 801 802@cindex @code{__real__} keyword 803@cindex @code{__imag__} keyword 804To extract the real part of a complex-valued expression @var{exp}, write 805@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to 806extract the imaginary part. This is a GNU extension; for values of 807floating type, you should use the ISO C99 functions @code{crealf}, 808@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and 809@code{cimagl}, declared in @code{<complex.h>} and also provided as 810built-in functions by GCC@. 811 812@cindex complex conjugation 813The operator @samp{~} performs complex conjugation when used on a value 814with a complex type. This is a GNU extension; for values of 815floating type, you should use the ISO C99 functions @code{conjf}, 816@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also 817provided as built-in functions by GCC@. 818 819GCC can allocate complex automatic variables in a noncontiguous 820fashion; it's even possible for the real part to be in a register while 821the imaginary part is on the stack (or vice-versa). Only the DWARF2 822debug info format can represent this, so use of DWARF2 is recommended. 823If you are using the stabs debug info format, GCC describes a noncontiguous 824complex variable as if it were two separate variables of noncomplex type. 825If the variable's actual name is @code{foo}, the two fictitious 826variables are named @code{foo$real} and @code{foo$imag}. You can 827examine and set these two fictitious variables with your debugger. 828 829@node Decimal Float 830@section Decimal Floating Types 831@cindex decimal floating types 832@cindex @code{_Decimal32} data type 833@cindex @code{_Decimal64} data type 834@cindex @code{_Decimal128} data type 835@cindex @code{df} integer suffix 836@cindex @code{dd} integer suffix 837@cindex @code{dl} integer suffix 838@cindex @code{DF} integer suffix 839@cindex @code{DD} integer suffix 840@cindex @code{DL} integer suffix 841 842As an extension, the GNU C compiler supports decimal floating types as 843defined in the N1176 draft of ISO/IEC WDTR24732. Support for decimal 844floating types in GCC will evolve as the draft technical report changes. 845Calling conventions for any target might also change. Not all targets 846support decimal floating types. 847 848The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and 849@code{_Decimal128}. They use a radix of ten, unlike the floating types 850@code{float}, @code{double}, and @code{long double} whose radix is not 851specified by the C standard but is usually two. 852 853Support for decimal floating types includes the arithmetic operators 854add, subtract, multiply, divide; unary arithmetic operators; 855relational operators; equality operators; and conversions to and from 856integer and other floating types. Use a suffix @samp{df} or 857@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} 858or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for 859@code{_Decimal128}. 860 861GCC support of decimal float as specified by the draft technical report 862is incomplete: 863 864@itemize @bullet 865@item 866Translation time data type (TTDT) is not supported. 867 868@item 869Characteristics of decimal floating types are defined in header file 870@file{decfloat.h} rather than @file{float.h}. 871 872@item 873When the value of a decimal floating type cannot be represented in the 874integer type to which it is being converted, the result is undefined 875rather than the result value specified by the draft technical report. 876@end itemize 877 878Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} 879are supported by the DWARF2 debug information format. 880 881@node Hex Floats 882@section Hex Floats 883@cindex hex floats 884 885ISO C99 supports floating-point numbers written not only in the usual 886decimal notation, such as @code{1.55e1}, but also numbers such as 887@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC 888supports this in C89 mode (except in some cases when strictly 889conforming) and in C++. In that format the 890@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are 891mandatory. The exponent is a decimal number that indicates the power of 8922 by which the significant part will be multiplied. Thus @samp{0x1.f} is 893@tex 894$1 {15\over16}$, 895@end tex 896@ifnottex 8971 15/16, 898@end ifnottex 899@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} 900is the same as @code{1.55e1}. 901 902Unlike for floating-point numbers in the decimal notation the exponent 903is always required in the hexadecimal notation. Otherwise the compiler 904would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This 905could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the 906extension for floating-point constants of type @code{float}. 907 908@node Zero Length 909@section Arrays of Length Zero 910@cindex arrays of length zero 911@cindex zero-length arrays 912@cindex length-zero arrays 913@cindex flexible array members 914 915Zero-length arrays are allowed in GNU C@. They are very useful as the 916last element of a structure which is really a header for a variable-length 917object: 918 919@smallexample 920struct line @{ 921 int length; 922 char contents[0]; 923@}; 924 925struct line *thisline = (struct line *) 926 malloc (sizeof (struct line) + this_length); 927thisline->length = this_length; 928@end smallexample 929 930In ISO C90, you would have to give @code{contents} a length of 1, which 931means either you waste space or complicate the argument to @code{malloc}. 932 933In ISO C99, you would use a @dfn{flexible array member}, which is 934slightly different in syntax and semantics: 935 936@itemize @bullet 937@item 938Flexible array members are written as @code{contents[]} without 939the @code{0}. 940 941@item 942Flexible array members have incomplete type, and so the @code{sizeof} 943operator may not be applied. As a quirk of the original implementation 944of zero-length arrays, @code{sizeof} evaluates to zero. 945 946@item 947Flexible array members may only appear as the last member of a 948@code{struct} that is otherwise non-empty. 949 950@item 951A structure containing a flexible array member, or a union containing 952such a structure (possibly recursively), may not be a member of a 953structure or an element of an array. (However, these uses are 954permitted by GCC as extensions.) 955@end itemize 956 957GCC versions before 3.0 allowed zero-length arrays to be statically 958initialized, as if they were flexible arrays. In addition to those 959cases that were useful, it also allowed initializations in situations 960that would corrupt later data. Non-empty initialization of zero-length 961arrays is now treated like any case where there are more initializer 962elements than the array holds, in that a suitable warning about "excess 963elements in array" is given, and the excess elements (all of them, in 964this case) are ignored. 965 966Instead GCC allows static initialization of flexible array members. 967This is equivalent to defining a new structure containing the original 968structure followed by an array of sufficient size to contain the data. 969I.e.@: in the following, @code{f1} is constructed as if it were declared 970like @code{f2}. 971 972@smallexample 973struct f1 @{ 974 int x; int y[]; 975@} f1 = @{ 1, @{ 2, 3, 4 @} @}; 976 977struct f2 @{ 978 struct f1 f1; int data[3]; 979@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; 980@end smallexample 981 982@noindent 983The convenience of this extension is that @code{f1} has the desired 984type, eliminating the need to consistently refer to @code{f2.f1}. 985 986This has symmetry with normal static arrays, in that an array of 987unknown size is also written with @code{[]}. 988 989Of course, this extension only makes sense if the extra data comes at 990the end of a top-level object, as otherwise we would be overwriting 991data at subsequent offsets. To avoid undue complication and confusion 992with initialization of deeply nested arrays, we simply disallow any 993non-empty initialization except when the structure is the top-level 994object. For example: 995 996@smallexample 997struct foo @{ int x; int y[]; @}; 998struct bar @{ struct foo z; @}; 999 1000struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} 1001struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1002struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} 1003struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1004@end smallexample 1005 1006@node Empty Structures 1007@section Structures With No Members 1008@cindex empty structures 1009@cindex zero-size structures 1010 1011GCC permits a C structure to have no members: 1012 1013@smallexample 1014struct empty @{ 1015@}; 1016@end smallexample 1017 1018The structure will have size zero. In C++, empty structures are part 1019of the language. G++ treats empty structures as if they had a single 1020member of type @code{char}. 1021 1022@node Variable Length 1023@section Arrays of Variable Length 1024@cindex variable-length arrays 1025@cindex arrays of variable length 1026@cindex VLAs 1027 1028Variable-length automatic arrays are allowed in ISO C99, and as an 1029extension GCC accepts them in C89 mode and in C++. (However, GCC's 1030implementation of variable-length arrays does not yet conform in detail 1031to the ISO C99 standard.) These arrays are 1032declared like any other automatic arrays, but with a length that is not 1033a constant expression. The storage is allocated at the point of 1034declaration and deallocated when the brace-level is exited. For 1035example: 1036 1037@smallexample 1038FILE * 1039concat_fopen (char *s1, char *s2, char *mode) 1040@{ 1041 char str[strlen (s1) + strlen (s2) + 1]; 1042 strcpy (str, s1); 1043 strcat (str, s2); 1044 return fopen (str, mode); 1045@} 1046@end smallexample 1047 1048@cindex scope of a variable length array 1049@cindex variable-length array scope 1050@cindex deallocating variable length arrays 1051Jumping or breaking out of the scope of the array name deallocates the 1052storage. Jumping into the scope is not allowed; you get an error 1053message for it. 1054 1055@cindex @code{alloca} vs variable-length arrays 1056You can use the function @code{alloca} to get an effect much like 1057variable-length arrays. The function @code{alloca} is available in 1058many other C implementations (but not in all). On the other hand, 1059variable-length arrays are more elegant. 1060 1061There are other differences between these two methods. Space allocated 1062with @code{alloca} exists until the containing @emph{function} returns. 1063The space for a variable-length array is deallocated as soon as the array 1064name's scope ends. (If you use both variable-length arrays and 1065@code{alloca} in the same function, deallocation of a variable-length array 1066will also deallocate anything more recently allocated with @code{alloca}.) 1067 1068You can also use variable-length arrays as arguments to functions: 1069 1070@smallexample 1071struct entry 1072tester (int len, char data[len][len]) 1073@{ 1074 /* @r{@dots{}} */ 1075@} 1076@end smallexample 1077 1078The length of an array is computed once when the storage is allocated 1079and is remembered for the scope of the array in case you access it with 1080@code{sizeof}. 1081 1082If you want to pass the array first and the length afterward, you can 1083use a forward declaration in the parameter list---another GNU extension. 1084 1085@smallexample 1086struct entry 1087tester (int len; char data[len][len], int len) 1088@{ 1089 /* @r{@dots{}} */ 1090@} 1091@end smallexample 1092 1093@cindex parameter forward declaration 1094The @samp{int len} before the semicolon is a @dfn{parameter forward 1095declaration}, and it serves the purpose of making the name @code{len} 1096known when the declaration of @code{data} is parsed. 1097 1098You can write any number of such parameter forward declarations in the 1099parameter list. They can be separated by commas or semicolons, but the 1100last one must end with a semicolon, which is followed by the ``real'' 1101parameter declarations. Each forward declaration must match a ``real'' 1102declaration in parameter name and data type. ISO C99 does not support 1103parameter forward declarations. 1104 1105@node Variadic Macros 1106@section Macros with a Variable Number of Arguments. 1107@cindex variable number of arguments 1108@cindex macro with variable arguments 1109@cindex rest argument (in macro) 1110@cindex variadic macros 1111 1112In the ISO C standard of 1999, a macro can be declared to accept a 1113variable number of arguments much as a function can. The syntax for 1114defining the macro is similar to that of a function. Here is an 1115example: 1116 1117@smallexample 1118#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) 1119@end smallexample 1120 1121Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of 1122such a macro, it represents the zero or more tokens until the closing 1123parenthesis that ends the invocation, including any commas. This set of 1124tokens replaces the identifier @code{__VA_ARGS__} in the macro body 1125wherever it appears. See the CPP manual for more information. 1126 1127GCC has long supported variadic macros, and used a different syntax that 1128allowed you to give a name to the variable arguments just like any other 1129argument. Here is an example: 1130 1131@smallexample 1132#define debug(format, args...) fprintf (stderr, format, args) 1133@end smallexample 1134 1135This is in all ways equivalent to the ISO C example above, but arguably 1136more readable and descriptive. 1137 1138GNU CPP has two further variadic macro extensions, and permits them to 1139be used with either of the above forms of macro definition. 1140 1141In standard C, you are not allowed to leave the variable argument out 1142entirely; but you are allowed to pass an empty argument. For example, 1143this invocation is invalid in ISO C, because there is no comma after 1144the string: 1145 1146@smallexample 1147debug ("A message") 1148@end smallexample 1149 1150GNU CPP permits you to completely omit the variable arguments in this 1151way. In the above examples, the compiler would complain, though since 1152the expansion of the macro still has the extra comma after the format 1153string. 1154 1155To help solve this problem, CPP behaves specially for variable arguments 1156used with the token paste operator, @samp{##}. If instead you write 1157 1158@smallexample 1159#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) 1160@end smallexample 1161 1162and if the variable arguments are omitted or empty, the @samp{##} 1163operator causes the preprocessor to remove the comma before it. If you 1164do provide some variable arguments in your macro invocation, GNU CPP 1165does not complain about the paste operation and instead places the 1166variable arguments after the comma. Just like any other pasted macro 1167argument, these arguments are not macro expanded. 1168 1169@node Escaped Newlines 1170@section Slightly Looser Rules for Escaped Newlines 1171@cindex escaped newlines 1172@cindex newlines (escaped) 1173 1174Recently, the preprocessor has relaxed its treatment of escaped 1175newlines. Previously, the newline had to immediately follow a 1176backslash. The current implementation allows whitespace in the form 1177of spaces, horizontal and vertical tabs, and form feeds between the 1178backslash and the subsequent newline. The preprocessor issues a 1179warning, but treats it as a valid escaped newline and combines the two 1180lines to form a single logical line. This works within comments and 1181tokens, as well as between tokens. Comments are @emph{not} treated as 1182whitespace for the purposes of this relaxation, since they have not 1183yet been replaced with spaces. 1184 1185@node Subscripting 1186@section Non-Lvalue Arrays May Have Subscripts 1187@cindex subscripting 1188@cindex arrays, non-lvalue 1189 1190@cindex subscripting and function values 1191In ISO C99, arrays that are not lvalues still decay to pointers, and 1192may be subscripted, although they may not be modified or used after 1193the next sequence point and the unary @samp{&} operator may not be 1194applied to them. As an extension, GCC allows such arrays to be 1195subscripted in C89 mode, though otherwise they do not decay to 1196pointers outside C99 mode. For example, 1197this is valid in GNU C though not valid in C89: 1198 1199@smallexample 1200@group 1201struct foo @{int a[4];@}; 1202 1203struct foo f(); 1204 1205bar (int index) 1206@{ 1207 return f().a[index]; 1208@} 1209@end group 1210@end smallexample 1211 1212@node Pointer Arith 1213@section Arithmetic on @code{void}- and Function-Pointers 1214@cindex void pointers, arithmetic 1215@cindex void, size of pointer to 1216@cindex function pointers, arithmetic 1217@cindex function, size of pointer to 1218 1219In GNU C, addition and subtraction operations are supported on pointers to 1220@code{void} and on pointers to functions. This is done by treating the 1221size of a @code{void} or of a function as 1. 1222 1223A consequence of this is that @code{sizeof} is also allowed on @code{void} 1224and on function types, and returns 1. 1225 1226@opindex Wpointer-arith 1227The option @option{-Wpointer-arith} requests a warning if these extensions 1228are used. 1229 1230@node Initializers 1231@section Non-Constant Initializers 1232@cindex initializers, non-constant 1233@cindex non-constant initializers 1234 1235As in standard C++ and ISO C99, the elements of an aggregate initializer for an 1236automatic variable are not required to be constant expressions in GNU C@. 1237Here is an example of an initializer with run-time varying elements: 1238 1239@smallexample 1240foo (float f, float g) 1241@{ 1242 float beat_freqs[2] = @{ f-g, f+g @}; 1243 /* @r{@dots{}} */ 1244@} 1245@end smallexample 1246 1247@node Compound Literals 1248@section Compound Literals 1249@cindex constructor expressions 1250@cindex initializations in expressions 1251@cindex structures, constructor expression 1252@cindex expressions, constructor 1253@cindex compound literals 1254@c The GNU C name for what C99 calls compound literals was "constructor expressions". 1255 1256ISO C99 supports compound literals. A compound literal looks like 1257a cast containing an initializer. Its value is an object of the 1258type specified in the cast, containing the elements specified in 1259the initializer; it is an lvalue. As an extension, GCC supports 1260compound literals in C89 mode and in C++. 1261 1262Usually, the specified type is a structure. Assume that 1263@code{struct foo} and @code{structure} are declared as shown: 1264 1265@smallexample 1266struct foo @{int a; char b[2];@} structure; 1267@end smallexample 1268 1269@noindent 1270Here is an example of constructing a @code{struct foo} with a compound literal: 1271 1272@smallexample 1273structure = ((struct foo) @{x + y, 'a', 0@}); 1274@end smallexample 1275 1276@noindent 1277This is equivalent to writing the following: 1278 1279@smallexample 1280@{ 1281 struct foo temp = @{x + y, 'a', 0@}; 1282 structure = temp; 1283@} 1284@end smallexample 1285 1286You can also construct an array. If all the elements of the compound literal 1287are (made up of) simple constant expressions, suitable for use in 1288initializers of objects of static storage duration, then the compound 1289literal can be coerced to a pointer to its first element and used in 1290such an initializer, as shown here: 1291 1292@smallexample 1293char **foo = (char *[]) @{ "x", "y", "z" @}; 1294@end smallexample 1295 1296Compound literals for scalar types and union types are is 1297also allowed, but then the compound literal is equivalent 1298to a cast. 1299 1300As a GNU extension, GCC allows initialization of objects with static storage 1301duration by compound literals (which is not possible in ISO C99, because 1302the initializer is not a constant). 1303It is handled as if the object was initialized only with the bracket 1304enclosed list if the types of the compound literal and the object match. 1305The initializer list of the compound literal must be constant. 1306If the object being initialized has array type of unknown size, the size is 1307determined by compound literal size. 1308 1309@smallexample 1310static struct foo x = (struct foo) @{1, 'a', 'b'@}; 1311static int y[] = (int []) @{1, 2, 3@}; 1312static int z[] = (int [3]) @{1@}; 1313@end smallexample 1314 1315@noindent 1316The above lines are equivalent to the following: 1317@smallexample 1318static struct foo x = @{1, 'a', 'b'@}; 1319static int y[] = @{1, 2, 3@}; 1320static int z[] = @{1, 0, 0@}; 1321@end smallexample 1322 1323@node Designated Inits 1324@section Designated Initializers 1325@cindex initializers with labeled elements 1326@cindex labeled elements in initializers 1327@cindex case labels in initializers 1328@cindex designated initializers 1329 1330Standard C89 requires the elements of an initializer to appear in a fixed 1331order, the same as the order of the elements in the array or structure 1332being initialized. 1333 1334In ISO C99 you can give the elements in any order, specifying the array 1335indices or structure field names they apply to, and GNU C allows this as 1336an extension in C89 mode as well. This extension is not 1337implemented in GNU C++. 1338 1339To specify an array index, write 1340@samp{[@var{index}] =} before the element value. For example, 1341 1342@smallexample 1343int a[6] = @{ [4] = 29, [2] = 15 @}; 1344@end smallexample 1345 1346@noindent 1347is equivalent to 1348 1349@smallexample 1350int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; 1351@end smallexample 1352 1353@noindent 1354The index values must be constant expressions, even if the array being 1355initialized is automatic. 1356 1357An alternative syntax for this which has been obsolete since GCC 2.5 but 1358GCC still accepts is to write @samp{[@var{index}]} before the element 1359value, with no @samp{=}. 1360 1361To initialize a range of elements to the same value, write 1362@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU 1363extension. For example, 1364 1365@smallexample 1366int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; 1367@end smallexample 1368 1369@noindent 1370If the value in it has side-effects, the side-effects will happen only once, 1371not for each initialized field by the range initializer. 1372 1373@noindent 1374Note that the length of the array is the highest value specified 1375plus one. 1376 1377In a structure initializer, specify the name of a field to initialize 1378with @samp{.@var{fieldname} =} before the element value. For example, 1379given the following structure, 1380 1381@smallexample 1382struct point @{ int x, y; @}; 1383@end smallexample 1384 1385@noindent 1386the following initialization 1387 1388@smallexample 1389struct point p = @{ .y = yvalue, .x = xvalue @}; 1390@end smallexample 1391 1392@noindent 1393is equivalent to 1394 1395@smallexample 1396struct point p = @{ xvalue, yvalue @}; 1397@end smallexample 1398 1399Another syntax which has the same meaning, obsolete since GCC 2.5, is 1400@samp{@var{fieldname}:}, as shown here: 1401 1402@smallexample 1403struct point p = @{ y: yvalue, x: xvalue @}; 1404@end smallexample 1405 1406@cindex designators 1407The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a 1408@dfn{designator}. You can also use a designator (or the obsolete colon 1409syntax) when initializing a union, to specify which element of the union 1410should be used. For example, 1411 1412@smallexample 1413union foo @{ int i; double d; @}; 1414 1415union foo f = @{ .d = 4 @}; 1416@end smallexample 1417 1418@noindent 1419will convert 4 to a @code{double} to store it in the union using 1420the second element. By contrast, casting 4 to type @code{union foo} 1421would store it into the union as the integer @code{i}, since it is 1422an integer. (@xref{Cast to Union}.) 1423 1424You can combine this technique of naming elements with ordinary C 1425initialization of successive elements. Each initializer element that 1426does not have a designator applies to the next consecutive element of the 1427array or structure. For example, 1428 1429@smallexample 1430int a[6] = @{ [1] = v1, v2, [4] = v4 @}; 1431@end smallexample 1432 1433@noindent 1434is equivalent to 1435 1436@smallexample 1437int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; 1438@end smallexample 1439 1440Labeling the elements of an array initializer is especially useful 1441when the indices are characters or belong to an @code{enum} type. 1442For example: 1443 1444@smallexample 1445int whitespace[256] 1446 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, 1447 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; 1448@end smallexample 1449 1450@cindex designator lists 1451You can also write a series of @samp{.@var{fieldname}} and 1452@samp{[@var{index}]} designators before an @samp{=} to specify a 1453nested subobject to initialize; the list is taken relative to the 1454subobject corresponding to the closest surrounding brace pair. For 1455example, with the @samp{struct point} declaration above: 1456 1457@smallexample 1458struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; 1459@end smallexample 1460 1461@noindent 1462If the same field is initialized multiple times, it will have value from 1463the last initialization. If any such overridden initialization has 1464side-effect, it is unspecified whether the side-effect happens or not. 1465Currently, GCC will discard them and issue a warning. 1466 1467@node Case Ranges 1468@section Case Ranges 1469@cindex case ranges 1470@cindex ranges in case statements 1471 1472You can specify a range of consecutive values in a single @code{case} label, 1473like this: 1474 1475@smallexample 1476case @var{low} ... @var{high}: 1477@end smallexample 1478 1479@noindent 1480This has the same effect as the proper number of individual @code{case} 1481labels, one for each integer value from @var{low} to @var{high}, inclusive. 1482 1483This feature is especially useful for ranges of ASCII character codes: 1484 1485@smallexample 1486case 'A' ... 'Z': 1487@end smallexample 1488 1489@strong{Be careful:} Write spaces around the @code{...}, for otherwise 1490it may be parsed wrong when you use it with integer values. For example, 1491write this: 1492 1493@smallexample 1494case 1 ... 5: 1495@end smallexample 1496 1497@noindent 1498rather than this: 1499 1500@smallexample 1501case 1...5: 1502@end smallexample 1503 1504@node Cast to Union 1505@section Cast to a Union Type 1506@cindex cast to a union 1507@cindex union, casting to a 1508 1509A cast to union type is similar to other casts, except that the type 1510specified is a union type. You can specify the type either with 1511@code{union @var{tag}} or with a typedef name. A cast to union is actually 1512a constructor though, not a cast, and hence does not yield an lvalue like 1513normal casts. (@xref{Compound Literals}.) 1514 1515The types that may be cast to the union type are those of the members 1516of the union. Thus, given the following union and variables: 1517 1518@smallexample 1519union foo @{ int i; double d; @}; 1520int x; 1521double y; 1522@end smallexample 1523 1524@noindent 1525both @code{x} and @code{y} can be cast to type @code{union foo}. 1526 1527Using the cast as the right-hand side of an assignment to a variable of 1528union type is equivalent to storing in a member of the union: 1529 1530@smallexample 1531union foo u; 1532/* @r{@dots{}} */ 1533u = (union foo) x @equiv{} u.i = x 1534u = (union foo) y @equiv{} u.d = y 1535@end smallexample 1536 1537You can also use the union cast as a function argument: 1538 1539@smallexample 1540void hack (union foo); 1541/* @r{@dots{}} */ 1542hack ((union foo) x); 1543@end smallexample 1544 1545@node Mixed Declarations 1546@section Mixed Declarations and Code 1547@cindex mixed declarations and code 1548@cindex declarations, mixed with code 1549@cindex code, mixed with declarations 1550 1551ISO C99 and ISO C++ allow declarations and code to be freely mixed 1552within compound statements. As an extension, GCC also allows this in 1553C89 mode. For example, you could do: 1554 1555@smallexample 1556int i; 1557/* @r{@dots{}} */ 1558i++; 1559int j = i + 2; 1560@end smallexample 1561 1562Each identifier is visible from where it is declared until the end of 1563the enclosing block. 1564 1565@node Function Attributes 1566@section Declaring Attributes of Functions 1567@cindex function attributes 1568@cindex declaring attributes of functions 1569@cindex functions that never return 1570@cindex functions that return more than once 1571@cindex functions that have no side effects 1572@cindex functions in arbitrary sections 1573@cindex functions that behave like malloc 1574@cindex @code{volatile} applied to function 1575@cindex @code{const} applied to function 1576@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments 1577@cindex functions with non-null pointer arguments 1578@cindex functions that are passed arguments in registers on the 386 1579@cindex functions that pop the argument stack on the 386 1580@cindex functions that do not pop the argument stack on the 386 1581 1582In GNU C, you declare certain things about functions called in your program 1583which help the compiler optimize function calls and check your code more 1584carefully. 1585 1586The keyword @code{__attribute__} allows you to specify special 1587attributes when making a declaration. This keyword is followed by an 1588attribute specification inside double parentheses. The following 1589attributes are currently defined for functions on all targets: 1590@code{aligned}, 1591@code{noreturn}, @code{returns_twice}, @code{noinline}, @code{always_inline}, 1592@code{flatten}, @code{pure}, @code{const}, @code{nothrow}, @code{sentinel}, 1593@code{format}, @code{format_arg}, @code{no_instrument_function}, 1594@code{section}, @code{constructor}, @code{destructor}, @code{used}, 1595@code{unused}, @code{deprecated}, @code{weak}, @code{malloc}, 1596@code{alias}, @code{warn_unused_result}, @code{nonnull}, 1597@code{gnu_inline} and @code{externally_visible}. Several other 1598attributes are defined for functions on particular target systems. Other 1599attributes, including @code{section} are supported for variables declarations 1600@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 1601(@pxref{Variable Attributes}), for types (@pxref{Type Attributes}), 1602and labels (@pxref{Label Attributes}). 1603 1604@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 1605You may also specify attributes with @samp{__} preceding and following 1606each keyword. This allows you to use them in header files without 1607being concerned about a possible macro of the same name. For example, 1608you may use @code{__noreturn__} instead of @code{noreturn}. 1609 1610@xref{Attribute Syntax}, for details of the exact syntax for using 1611attributes. 1612 1613@table @code 1614@c Keep this table alphabetized by attribute name. Treat _ as space. 1615 1616@item alias ("@var{target}") 1617@cindex @code{alias} attribute 1618The @code{alias} attribute causes the declaration to be emitted as an 1619alias for another symbol, which must be specified. For instance, 1620 1621@smallexample 1622void __f () @{ /* @r{Do something.} */; @} 1623void f () __attribute__ ((weak, alias ("__f"))); 1624@end smallexample 1625 1626defines @samp{f} to be a weak alias for @samp{__f}. In C++, the 1627mangled name for the target must be used. It is an error if @samp{__f} 1628is not defined in the same translation unit. 1629 1630Not all target machines support this attribute. 1631 1632@item aligned (@var{alignment}) 1633@cindex @code{aligned} attribute 1634This attribute specifies a minimum alignment for the function, 1635measured in bytes. 1636 1637You cannot use this attribute to decrease the alignment of a function, 1638only to increase it. However, when you explicitly specify a function 1639alignment this will override the effect of the 1640@option{-falign-functions} (@pxref{Optimize Options}) option for this 1641function. 1642 1643Note that the effectiveness of @code{aligned} attributes may be 1644limited by inherent limitations in your linker. On many systems, the 1645linker is only able to arrange for functions to be aligned up to a 1646certain maximum alignment. (For some linkers, the maximum supported 1647alignment may be very very small.) See your linker documentation for 1648further information. 1649 1650The @code{aligned} attribute can also be used for variables and fields 1651(@pxref{Variable Attributes}.) 1652 1653@item always_inline 1654@cindex @code{always_inline} function attribute 1655Generally, functions are not inlined unless optimization is specified. 1656For functions declared inline, this attribute inlines the function even 1657if no optimization level was specified. 1658 1659@item gnu_inline 1660@cindex @code{gnu_inline} function attribute 1661This attribute should be used with a function which is also declared 1662with the @code{inline} keyword. It directs GCC to treat the function 1663as if it were defined in gnu89 mode even when compiling in C99 or 1664gnu99 mode. 1665 1666If the function is declared @code{extern}, then this definition of the 1667function is used only for inlining. In no case is the function 1668compiled as a standalone function, not even if you take its address 1669explicitly. Such an address becomes an external reference, as if you 1670had only declared the function, and had not defined it. This has 1671almost the effect of a macro. The way to use this is to put a 1672function definition in a header file with this attribute, and put 1673another copy of the function, without @code{extern}, in a library 1674file. The definition in the header file will cause most calls to the 1675function to be inlined. If any uses of the function remain, they will 1676refer to the single copy in the library. Note that the two 1677definitions of the functions need not be precisely the same, although 1678if they do not have the same effect your program may behave oddly. 1679 1680If the function is neither @code{extern} nor @code{static}, then the 1681function is compiled as a standalone function, as well as being 1682inlined where possible. 1683 1684This is how GCC traditionally handled functions declared 1685@code{inline}. Since ISO C99 specifies a different semantics for 1686@code{inline}, this function attribute is provided as a transition 1687measure and as a useful feature in its own right. This attribute is 1688available in GCC 4.1.3 and later. It is available if either of the 1689preprocessor macros @code{__GNUC_GNU_INLINE__} or 1690@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline 1691Function is As Fast As a Macro}. 1692 1693Note that since the first version of GCC to support C99 inline semantics 1694is 4.3, earlier versions of GCC which accept this attribute effectively 1695assume that it is always present, whether or not it is given explicitly. 1696In versions prior to 4.3, the only effect of explicitly including it is 1697to disable warnings about using inline functions in C99 mode. 1698 1699@cindex @code{flatten} function attribute 1700@item flatten 1701Generally, inlining into a function is limited. For a function marked with 1702this attribute, every call inside this function will be inlined, if possible. 1703Whether the function itself is considered for inlining depends on its size and 1704the current inlining parameters. The @code{flatten} attribute only works 1705reliably in unit-at-a-time mode. 1706 1707@item cdecl 1708@cindex functions that do pop the argument stack on the 386 1709@opindex mrtd 1710On the Intel 386, the @code{cdecl} attribute causes the compiler to 1711assume that the calling function will pop off the stack space used to 1712pass arguments. This is 1713useful to override the effects of the @option{-mrtd} switch. 1714 1715@item const 1716@cindex @code{const} function attribute 1717Many functions do not examine any values except their arguments, and 1718have no effects except the return value. Basically this is just slightly 1719more strict class than the @code{pure} attribute below, since function is not 1720allowed to read global memory. 1721 1722@cindex pointer arguments 1723Note that a function that has pointer arguments and examines the data 1724pointed to must @emph{not} be declared @code{const}. Likewise, a 1725function that calls a non-@code{const} function usually must not be 1726@code{const}. It does not make sense for a @code{const} function to 1727return @code{void}. 1728 1729The attribute @code{const} is not implemented in GCC versions earlier 1730than 2.5. An alternative way to declare that a function has no side 1731effects, which works in the current version and in some older versions, 1732is as follows: 1733 1734@smallexample 1735typedef int intfn (); 1736 1737extern const intfn square; 1738@end smallexample 1739 1740This approach does not work in GNU C++ from 2.6.0 on, since the language 1741specifies that the @samp{const} must be attached to the return value. 1742 1743@item constructor 1744@itemx destructor 1745@cindex @code{constructor} function attribute 1746@cindex @code{destructor} function attribute 1747The @code{constructor} attribute causes the function to be called 1748automatically before execution enters @code{main ()}. Similarly, the 1749@code{destructor} attribute causes the function to be called 1750automatically after @code{main ()} has completed or @code{exit ()} has 1751been called. Functions with these attributes are useful for 1752initializing data that will be used implicitly during the execution of 1753the program. 1754 1755@item deprecated 1756@cindex @code{deprecated} attribute. 1757The @code{deprecated} attribute results in a warning if the function 1758is used anywhere in the source file. This is useful when identifying 1759functions that are expected to be removed in a future version of a 1760program. The warning also includes the location of the declaration 1761of the deprecated function, to enable users to easily find further 1762information about why the function is deprecated, or what they should 1763do instead. Note that the warnings only occurs for uses: 1764 1765@smallexample 1766int old_fn () __attribute__ ((deprecated)); 1767int old_fn (); 1768int (*fn_ptr)() = old_fn; 1769@end smallexample 1770 1771results in a warning on line 3 but not line 2. 1772 1773The @code{deprecated} attribute can also be used for variables and 1774types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) 1775 1776@item dllexport 1777@cindex @code{__declspec(dllexport)} 1778On Microsoft Windows targets and Symbian OS targets the 1779@code{dllexport} attribute causes the compiler to provide a global 1780pointer to a pointer in a DLL, so that it can be referenced with the 1781@code{dllimport} attribute. On Microsoft Windows targets, the pointer 1782name is formed by combining @code{_imp__} and the function or variable 1783name. 1784 1785You can use @code{__declspec(dllexport)} as a synonym for 1786@code{__attribute__ ((dllexport))} for compatibility with other 1787compilers. 1788 1789On systems that support the @code{visibility} attribute, this 1790attribute also implies ``default'' visibility, unless a 1791@code{visibility} attribute is explicitly specified. You should avoid 1792the use of @code{dllexport} with ``hidden'' or ``internal'' 1793visibility; in the future GCC may issue an error for those cases. 1794 1795Currently, the @code{dllexport} attribute is ignored for inlined 1796functions, unless the @option{-fkeep-inline-functions} flag has been 1797used. The attribute is also ignored for undefined symbols. 1798 1799When applied to C++ classes, the attribute marks defined non-inlined 1800member functions and static data members as exports. Static consts 1801initialized in-class are not marked unless they are also defined 1802out-of-class. 1803 1804For Microsoft Windows targets there are alternative methods for 1805including the symbol in the DLL's export table such as using a 1806@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using 1807the @option{--export-all} linker flag. 1808 1809@item dllimport 1810@cindex @code{__declspec(dllimport)} 1811On Microsoft Windows and Symbian OS targets, the @code{dllimport} 1812attribute causes the compiler to reference a function or variable via 1813a global pointer to a pointer that is set up by the DLL exporting the 1814symbol. The attribute implies @code{extern} storage. On Microsoft 1815Windows targets, the pointer name is formed by combining @code{_imp__} 1816and the function or variable name. 1817 1818You can use @code{__declspec(dllimport)} as a synonym for 1819@code{__attribute__ ((dllimport))} for compatibility with other 1820compilers. 1821 1822Currently, the attribute is ignored for inlined functions. If the 1823attribute is applied to a symbol @emph{definition}, an error is reported. 1824If a symbol previously declared @code{dllimport} is later defined, the 1825attribute is ignored in subsequent references, and a warning is emitted. 1826The attribute is also overridden by a subsequent declaration as 1827@code{dllexport}. 1828 1829When applied to C++ classes, the attribute marks non-inlined 1830member functions and static data members as imports. However, the 1831attribute is ignored for virtual methods to allow creation of vtables 1832using thunks. 1833 1834On the SH Symbian OS target the @code{dllimport} attribute also has 1835another affect---it can cause the vtable and run-time type information 1836for a class to be exported. This happens when the class has a 1837dllimport'ed constructor or a non-inline, non-pure virtual function 1838and, for either of those two conditions, the class also has a inline 1839constructor or destructor and has a key function that is defined in 1840the current translation unit. 1841 1842For Microsoft Windows based targets the use of the @code{dllimport} 1843attribute on functions is not necessary, but provides a small 1844performance benefit by eliminating a thunk in the DLL@. The use of the 1845@code{dllimport} attribute on imported variables was required on older 1846versions of the GNU linker, but can now be avoided by passing the 1847@option{--enable-auto-import} switch to the GNU linker. As with 1848functions, using the attribute for a variable eliminates a thunk in 1849the DLL@. 1850 1851One drawback to using this attribute is that a pointer to a function 1852or variable marked as @code{dllimport} cannot be used as a constant 1853address. On Microsoft Windows targets, the attribute can be disabled 1854for functions by setting the @option{-mnop-fun-dllimport} flag. 1855 1856@item eightbit_data 1857@cindex eight bit data on the H8/300, H8/300H, and H8S 1858Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 1859variable should be placed into the eight bit data section. 1860The compiler will generate more efficient code for certain operations 1861on data in the eight bit data area. Note the eight bit data area is limited to 1862256 bytes of data. 1863 1864You must use GAS and GLD from GNU binutils version 2.7 or later for 1865this attribute to work correctly. 1866 1867@item exception_handler 1868@cindex exception handler functions on the Blackfin processor 1869Use this attribute on the Blackfin to indicate that the specified function 1870is an exception handler. The compiler will generate function entry and 1871exit sequences suitable for use in an exception handler when this 1872attribute is present. 1873 1874@item far 1875@cindex functions which handle memory bank switching 1876On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to 1877use a calling convention that takes care of switching memory banks when 1878entering and leaving a function. This calling convention is also the 1879default when using the @option{-mlong-calls} option. 1880 1881On 68HC12 the compiler will use the @code{call} and @code{rtc} instructions 1882to call and return from a function. 1883 1884On 68HC11 the compiler will generate a sequence of instructions 1885to invoke a board-specific routine to switch the memory bank and call the 1886real function. The board-specific routine simulates a @code{call}. 1887At the end of a function, it will jump to a board-specific routine 1888instead of using @code{rts}. The board-specific return routine simulates 1889the @code{rtc}. 1890 1891@item fastcall 1892@cindex functions that pop the argument stack on the 386 1893On the Intel 386, the @code{fastcall} attribute causes the compiler to 1894pass the first argument (if of integral type) in the register ECX and 1895the second argument (if of integral type) in the register EDX@. Subsequent 1896and other typed arguments are passed on the stack. The called function will 1897pop the arguments off the stack. If the number of arguments is variable all 1898arguments are pushed on the stack. 1899 1900@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) 1901@cindex @code{format} function attribute 1902@opindex Wformat 1903The @code{format} attribute specifies that a function takes @code{printf}, 1904@code{scanf}, @code{strftime} or @code{strfmon} style arguments which 1905should be type-checked against a format string. For example, the 1906declaration: 1907 1908@smallexample 1909extern int 1910my_printf (void *my_object, const char *my_format, ...) 1911 __attribute__ ((format (printf, 2, 3))); 1912@end smallexample 1913 1914@noindent 1915causes the compiler to check the arguments in calls to @code{my_printf} 1916for consistency with the @code{printf} style format string argument 1917@code{my_format}. 1918 1919The parameter @var{archetype} determines how the format string is 1920interpreted, and should be @code{printf}, @code{scanf}, @code{strftime} 1921or @code{strfmon}. (You can also use @code{__printf__}, 1922@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) The 1923parameter @var{string-index} specifies which argument is the format 1924string argument (starting from 1), while @var{first-to-check} is the 1925number of the first argument to check against the format string. For 1926functions where the arguments are not available to be checked (such as 1927@code{vprintf}), specify the third parameter as zero. In this case the 1928compiler only checks the format string for consistency. For 1929@code{strftime} formats, the third parameter is required to be zero. 1930Since non-static C++ methods have an implicit @code{this} argument, the 1931arguments of such methods should be counted from two, not one, when 1932giving values for @var{string-index} and @var{first-to-check}. 1933 1934In the example above, the format string (@code{my_format}) is the second 1935argument of the function @code{my_print}, and the arguments to check 1936start with the third argument, so the correct parameters for the format 1937attribute are 2 and 3. 1938 1939@opindex ffreestanding 1940@opindex fno-builtin 1941The @code{format} attribute allows you to identify your own functions 1942which take format strings as arguments, so that GCC can check the 1943calls to these functions for errors. The compiler always (unless 1944@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats 1945for the standard library functions @code{printf}, @code{fprintf}, 1946@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, 1947@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such 1948warnings are requested (using @option{-Wformat}), so there is no need to 1949modify the header file @file{stdio.h}. In C99 mode, the functions 1950@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and 1951@code{vsscanf} are also checked. Except in strictly conforming C 1952standard modes, the X/Open function @code{strfmon} is also checked as 1953are @code{printf_unlocked} and @code{fprintf_unlocked}. 1954@xref{C Dialect Options,,Options Controlling C Dialect}. 1955 1956The target may provide additional types of format checks. 1957@xref{Target Format Checks,,Format Checks Specific to Particular 1958Target Machines}. 1959 1960@item format_arg (@var{string-index}) 1961@cindex @code{format_arg} function attribute 1962@opindex Wformat-nonliteral 1963The @code{format_arg} attribute specifies that a function takes a format 1964string for a @code{printf}, @code{scanf}, @code{strftime} or 1965@code{strfmon} style function and modifies it (for example, to translate 1966it into another language), so the result can be passed to a 1967@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style 1968function (with the remaining arguments to the format function the same 1969as they would have been for the unmodified string). For example, the 1970declaration: 1971 1972@smallexample 1973extern char * 1974my_dgettext (char *my_domain, const char *my_format) 1975 __attribute__ ((format_arg (2))); 1976@end smallexample 1977 1978@noindent 1979causes the compiler to check the arguments in calls to a @code{printf}, 1980@code{scanf}, @code{strftime} or @code{strfmon} type function, whose 1981format string argument is a call to the @code{my_dgettext} function, for 1982consistency with the format string argument @code{my_format}. If the 1983@code{format_arg} attribute had not been specified, all the compiler 1984could tell in such calls to format functions would be that the format 1985string argument is not constant; this would generate a warning when 1986@option{-Wformat-nonliteral} is used, but the calls could not be checked 1987without the attribute. 1988 1989The parameter @var{string-index} specifies which argument is the format 1990string argument (starting from one). Since non-static C++ methods have 1991an implicit @code{this} argument, the arguments of such methods should 1992be counted from two. 1993 1994The @code{format-arg} attribute allows you to identify your own 1995functions which modify format strings, so that GCC can check the 1996calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} 1997type function whose operands are a call to one of your own function. 1998The compiler always treats @code{gettext}, @code{dgettext}, and 1999@code{dcgettext} in this manner except when strict ISO C support is 2000requested by @option{-ansi} or an appropriate @option{-std} option, or 2001@option{-ffreestanding} or @option{-fno-builtin} 2002is used. @xref{C Dialect Options,,Options 2003Controlling C Dialect}. 2004 2005@item function_vector 2006@cindex calling functions through the function vector on the H8/300 processors 2007Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 2008function should be called through the function vector. Calling a 2009function through the function vector will reduce code size, however; 2010the function vector has a limited size (maximum 128 entries on the H8/300 2011and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector. 2012 2013You must use GAS and GLD from GNU binutils version 2.7 or later for 2014this attribute to work correctly. 2015 2016@item interrupt 2017@cindex interrupt handler functions 2018Use this attribute on the ARM, AVR, C4x, CRX, M32C, M32R/D, MS1, and Xstormy16 2019ports to indicate that the specified function is an interrupt handler. 2020The compiler will generate function entry and exit sequences suitable 2021for use in an interrupt handler when this attribute is present. 2022 2023Note, interrupt handlers for the Blackfin, m68k, H8/300, H8/300H, H8S, and 2024SH processors can be specified via the @code{interrupt_handler} attribute. 2025 2026Note, on the AVR, interrupts will be enabled inside the function. 2027 2028Note, for the ARM, you can specify the kind of interrupt to be handled by 2029adding an optional parameter to the interrupt attribute like this: 2030 2031@smallexample 2032void f () __attribute__ ((interrupt ("IRQ"))); 2033@end smallexample 2034 2035Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@. 2036 2037@item interrupt_handler 2038@cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors 2039Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to 2040indicate that the specified function is an interrupt handler. The compiler 2041will generate function entry and exit sequences suitable for use in an 2042interrupt handler when this attribute is present. 2043 2044@item kspisusp 2045@cindex User stack pointer in interrupts on the Blackfin 2046When used together with @code{interrupt_handler}, @code{exception_handler} 2047or @code{nmi_handler}, code will be generated to load the stack pointer 2048from the USP register in the function prologue. 2049 2050@item long_call/short_call 2051@cindex indirect calls on ARM 2052This attribute specifies how a particular function is called on 2053ARM@. Both attributes override the @option{-mlong-calls} (@pxref{ARM Options}) 2054command line switch and @code{#pragma long_calls} settings. The 2055@code{long_call} attribute indicates that the function might be far 2056away from the call site and require a different (more expensive) 2057calling sequence. The @code{short_call} attribute always places 2058the offset to the function from the call site into the @samp{BL} 2059instruction directly. 2060 2061@item longcall/shortcall 2062@cindex functions called via pointer on the RS/6000 and PowerPC 2063On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute 2064indicates that the function might be far away from the call site and 2065require a different (more expensive) calling sequence. The 2066@code{shortcall} attribute indicates that the function is always close 2067enough for the shorter calling sequence to be used. These attributes 2068override both the @option{-mlongcall} switch and, on the RS/6000 and 2069PowerPC, the @code{#pragma longcall} setting. 2070 2071@xref{RS/6000 and PowerPC Options}, for more information on whether long 2072calls are necessary. 2073 2074@item long_call 2075@cindex indirect calls on MIPS 2076This attribute specifies how a particular function is called on MIPS@. 2077The attribute overrides the @option{-mlong-calls} (@pxref{MIPS Options}) 2078command line switch. This attribute causes the compiler to always call 2079the function by first loading its address into a register, and then using 2080the contents of that register. 2081 2082@item malloc 2083@cindex @code{malloc} attribute 2084The @code{malloc} attribute is used to tell the compiler that a function 2085may be treated as if any non-@code{NULL} pointer it returns cannot 2086alias any other pointer valid when the function returns. 2087This will often improve optimization. 2088Standard functions with this property include @code{malloc} and 2089@code{calloc}. @code{realloc}-like functions have this property as 2090long as the old pointer is never referred to (including comparing it 2091to the new pointer) after the function returns a non-@code{NULL} 2092value. 2093 2094@item model (@var{model-name}) 2095@cindex function addressability on the M32R/D 2096@cindex variable addressability on the IA-64 2097 2098On the M32R/D, use this attribute to set the addressability of an 2099object, and of the code generated for a function. The identifier 2100@var{model-name} is one of @code{small}, @code{medium}, or 2101@code{large}, representing each of the code models. 2102 2103Small model objects live in the lower 16MB of memory (so that their 2104addresses can be loaded with the @code{ld24} instruction), and are 2105callable with the @code{bl} instruction. 2106 2107Medium model objects may live anywhere in the 32-bit address space (the 2108compiler will generate @code{seth/add3} instructions to load their addresses), 2109and are callable with the @code{bl} instruction. 2110 2111Large model objects may live anywhere in the 32-bit address space (the 2112compiler will generate @code{seth/add3} instructions to load their addresses), 2113and may not be reachable with the @code{bl} instruction (the compiler will 2114generate the much slower @code{seth/add3/jl} instruction sequence). 2115 2116On IA-64, use this attribute to set the addressability of an object. 2117At present, the only supported identifier for @var{model-name} is 2118@code{small}, indicating addressability via ``small'' (22-bit) 2119addresses (so that their addresses can be loaded with the @code{addl} 2120instruction). Caveat: such addressing is by definition not position 2121independent and hence this attribute must not be used for objects 2122defined by shared libraries. 2123 2124@item naked 2125@cindex function without a prologue/epilogue code 2126Use this attribute on the ARM, AVR, C4x and IP2K ports to indicate that the 2127specified function does not need prologue/epilogue sequences generated by 2128the compiler. It is up to the programmer to provide these sequences. 2129 2130@item near 2131@cindex functions which do not handle memory bank switching on 68HC11/68HC12 2132On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to 2133use the normal calling convention based on @code{jsr} and @code{rts}. 2134This attribute can be used to cancel the effect of the @option{-mlong-calls} 2135option. 2136 2137@item nesting 2138@cindex Allow nesting in an interrupt handler on the Blackfin processor. 2139Use this attribute together with @code{interrupt_handler}, 2140@code{exception_handler} or @code{nmi_handler} to indicate that the function 2141entry code should enable nested interrupts or exceptions. 2142 2143@item nmi_handler 2144@cindex NMI handler functions on the Blackfin processor 2145Use this attribute on the Blackfin to indicate that the specified function 2146is an NMI handler. The compiler will generate function entry and 2147exit sequences suitable for use in an NMI handler when this 2148attribute is present. 2149 2150@item no_instrument_function 2151@cindex @code{no_instrument_function} function attribute 2152@opindex finstrument-functions 2153If @option{-finstrument-functions} is given, profiling function calls will 2154be generated at entry and exit of most user-compiled functions. 2155Functions with this attribute will not be so instrumented. 2156 2157@item noinline 2158@cindex @code{noinline} function attribute 2159This function attribute prevents a function from being considered for 2160inlining. 2161 2162@item nonnull (@var{arg-index}, @dots{}) 2163@cindex @code{nonnull} function attribute 2164The @code{nonnull} attribute specifies that some function parameters should 2165be non-null pointers. For instance, the declaration: 2166 2167@smallexample 2168extern void * 2169my_memcpy (void *dest, const void *src, size_t len) 2170 __attribute__((nonnull (1, 2))); 2171@end smallexample 2172 2173@noindent 2174causes the compiler to check that, in calls to @code{my_memcpy}, 2175arguments @var{dest} and @var{src} are non-null. If the compiler 2176determines that a null pointer is passed in an argument slot marked 2177as non-null, and the @option{-Wnonnull} option is enabled, a warning 2178is issued. The compiler may also choose to make optimizations based 2179on the knowledge that certain function arguments will not be null. 2180 2181If no argument index list is given to the @code{nonnull} attribute, 2182all pointer arguments are marked as non-null. To illustrate, the 2183following declaration is equivalent to the previous example: 2184 2185@smallexample 2186extern void * 2187my_memcpy (void *dest, const void *src, size_t len) 2188 __attribute__((nonnull)); 2189@end smallexample 2190 2191@item noreturn 2192@cindex @code{noreturn} function attribute 2193A few standard library functions, such as @code{abort} and @code{exit}, 2194cannot return. GCC knows this automatically. Some programs define 2195their own functions that never return. You can declare them 2196@code{noreturn} to tell the compiler this fact. For example, 2197 2198@smallexample 2199@group 2200void fatal () __attribute__ ((noreturn)); 2201 2202void 2203fatal (/* @r{@dots{}} */) 2204@{ 2205 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ 2206 exit (1); 2207@} 2208@end group 2209@end smallexample 2210 2211The @code{noreturn} keyword tells the compiler to assume that 2212@code{fatal} cannot return. It can then optimize without regard to what 2213would happen if @code{fatal} ever did return. This makes slightly 2214better code. More importantly, it helps avoid spurious warnings of 2215uninitialized variables. 2216 2217The @code{noreturn} keyword does not affect the exceptional path when that 2218applies: a @code{noreturn}-marked function may still return to the caller 2219by throwing an exception or calling @code{longjmp}. 2220 2221Do not assume that registers saved by the calling function are 2222restored before calling the @code{noreturn} function. 2223 2224It does not make sense for a @code{noreturn} function to have a return 2225type other than @code{void}. 2226 2227The attribute @code{noreturn} is not implemented in GCC versions 2228earlier than 2.5. An alternative way to declare that a function does 2229not return, which works in the current version and in some older 2230versions, is as follows: 2231 2232@smallexample 2233typedef void voidfn (); 2234 2235volatile voidfn fatal; 2236@end smallexample 2237 2238This approach does not work in GNU C++. 2239 2240@item nothrow 2241@cindex @code{nothrow} function attribute 2242The @code{nothrow} attribute is used to inform the compiler that a 2243function cannot throw an exception. For example, most functions in 2244the standard C library can be guaranteed not to throw an exception 2245with the notable exceptions of @code{qsort} and @code{bsearch} that 2246take function pointer arguments. The @code{nothrow} attribute is not 2247implemented in GCC versions earlier than 3.3. 2248 2249@item pure 2250@cindex @code{pure} function attribute 2251Many functions have no effects except the return value and their 2252return value depends only on the parameters and/or global variables. 2253Such a function can be subject 2254to common subexpression elimination and loop optimization just as an 2255arithmetic operator would be. These functions should be declared 2256with the attribute @code{pure}. For example, 2257 2258@smallexample 2259int square (int) __attribute__ ((pure)); 2260@end smallexample 2261 2262@noindent 2263says that the hypothetical function @code{square} is safe to call 2264fewer times than the program says. 2265 2266Some of common examples of pure functions are @code{strlen} or @code{memcmp}. 2267Interesting non-pure functions are functions with infinite loops or those 2268depending on volatile memory or other system resource, that may change between 2269two consecutive calls (such as @code{feof} in a multithreading environment). 2270 2271The attribute @code{pure} is not implemented in GCC versions earlier 2272than 2.96. 2273 2274@item regparm (@var{number}) 2275@cindex @code{regparm} attribute 2276@cindex functions that are passed arguments in registers on the 386 2277On the Intel 386, the @code{regparm} attribute causes the compiler to 2278pass arguments number one to @var{number} if they are of integral type 2279in registers EAX, EDX, and ECX instead of on the stack. Functions that 2280take a variable number of arguments will continue to be passed all of their 2281arguments on the stack. 2282 2283Beware that on some ELF systems this attribute is unsuitable for 2284global functions in shared libraries with lazy binding (which is the 2285default). Lazy binding will send the first call via resolving code in 2286the loader, which might assume EAX, EDX and ECX can be clobbered, as 2287per the standard calling conventions. Solaris 8 is affected by this. 2288GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be 2289safe since the loaders there save all registers. (Lazy binding can be 2290disabled with the linker or the loader if desired, to avoid the 2291problem.) 2292 2293@item sseregparm 2294@cindex @code{sseregparm} attribute 2295On the Intel 386 with SSE support, the @code{sseregparm} attribute 2296causes the compiler to pass up to 3 floating point arguments in 2297SSE registers instead of on the stack. Functions that take a 2298variable number of arguments will continue to pass all of their 2299floating point arguments on the stack. 2300 2301@item force_align_arg_pointer 2302@cindex @code{force_align_arg_pointer} attribute 2303On the Intel x86, the @code{force_align_arg_pointer} attribute may be 2304applied to individual function definitions, generating an alternate 2305prologue and epilogue that realigns the runtime stack. This supports 2306mixing legacy codes that run with a 4-byte aligned stack with modern 2307codes that keep a 16-byte stack for SSE compatibility. The alternate 2308prologue and epilogue are slower and bigger than the regular ones, and 2309the alternate prologue requires a scratch register; this lowers the 2310number of registers available if used in conjunction with the 2311@code{regparm} attribute. The @code{force_align_arg_pointer} 2312attribute is incompatible with nested functions; this is considered a 2313hard error. 2314 2315@item returns_twice 2316@cindex @code{returns_twice} attribute 2317The @code{returns_twice} attribute tells the compiler that a function may 2318return more than one time. The compiler will ensure that all registers 2319are dead before calling such a function and will emit a warning about 2320the variables that may be clobbered after the second return from the 2321function. Examples of such functions are @code{setjmp} and @code{vfork}. 2322The @code{longjmp}-like counterpart of such function, if any, might need 2323to be marked with the @code{noreturn} attribute. 2324 2325@item saveall 2326@cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S 2327Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that 2328all registers except the stack pointer should be saved in the prologue 2329regardless of whether they are used or not. 2330 2331@item section ("@var{section-name}") 2332@cindex @code{section} function attribute 2333Normally, the compiler places the code it generates in the @code{text} section. 2334Sometimes, however, you need additional sections, or you need certain 2335particular functions to appear in special sections. The @code{section} 2336attribute specifies that a function lives in a particular section. 2337For example, the declaration: 2338 2339@smallexample 2340extern void foobar (void) __attribute__ ((section ("bar"))); 2341@end smallexample 2342 2343@noindent 2344puts the function @code{foobar} in the @code{bar} section. 2345 2346Some file formats do not support arbitrary sections so the @code{section} 2347attribute is not available on all platforms. 2348If you need to map the entire contents of a module to a particular 2349section, consider using the facilities of the linker instead. 2350 2351@item sentinel 2352@cindex @code{sentinel} function attribute 2353This function attribute ensures that a parameter in a function call is 2354an explicit @code{NULL}. The attribute is only valid on variadic 2355functions. By default, the sentinel is located at position zero, the 2356last parameter of the function call. If an optional integer position 2357argument P is supplied to the attribute, the sentinel must be located at 2358position P counting backwards from the end of the argument list. 2359 2360@smallexample 2361__attribute__ ((sentinel)) 2362is equivalent to 2363__attribute__ ((sentinel(0))) 2364@end smallexample 2365 2366The attribute is automatically set with a position of 0 for the built-in 2367functions @code{execl} and @code{execlp}. The built-in function 2368@code{execle} has the attribute set with a position of 1. 2369 2370A valid @code{NULL} in this context is defined as zero with any pointer 2371type. If your system defines the @code{NULL} macro with an integer type 2372then you need to add an explicit cast. GCC replaces @code{stddef.h} 2373with a copy that redefines NULL appropriately. 2374 2375The warnings for missing or incorrect sentinels are enabled with 2376@option{-Wformat}. 2377 2378@item short_call 2379See long_call/short_call. 2380 2381@item shortcall 2382See longcall/shortcall. 2383 2384@item signal 2385@cindex signal handler functions on the AVR processors 2386Use this attribute on the AVR to indicate that the specified 2387function is a signal handler. The compiler will generate function 2388entry and exit sequences suitable for use in a signal handler when this 2389attribute is present. Interrupts will be disabled inside the function. 2390 2391@item sp_switch 2392Use this attribute on the SH to indicate an @code{interrupt_handler} 2393function should switch to an alternate stack. It expects a string 2394argument that names a global variable holding the address of the 2395alternate stack. 2396 2397@smallexample 2398void *alt_stack; 2399void f () __attribute__ ((interrupt_handler, 2400 sp_switch ("alt_stack"))); 2401@end smallexample 2402 2403@item stdcall 2404@cindex functions that pop the argument stack on the 386 2405On the Intel 386, the @code{stdcall} attribute causes the compiler to 2406assume that the called function will pop off the stack space used to 2407pass arguments, unless it takes a variable number of arguments. 2408 2409@item tiny_data 2410@cindex tiny data section on the H8/300H and H8S 2411Use this attribute on the H8/300H and H8S to indicate that the specified 2412variable should be placed into the tiny data section. 2413The compiler will generate more efficient code for loads and stores 2414on data in the tiny data section. Note the tiny data area is limited to 2415slightly under 32kbytes of data. 2416 2417@item trap_exit 2418Use this attribute on the SH for an @code{interrupt_handler} to return using 2419@code{trapa} instead of @code{rte}. This attribute expects an integer 2420argument specifying the trap number to be used. 2421 2422@item unused 2423@cindex @code{unused} attribute. 2424This attribute, attached to a function, means that the function is meant 2425to be possibly unused. GCC will not produce a warning for this 2426function. 2427 2428@item used 2429@cindex @code{used} attribute. 2430This attribute, attached to a function, means that code must be emitted 2431for the function even if it appears that the function is not referenced. 2432This is useful, for example, when the function is referenced only in 2433inline assembly. 2434 2435@item visibility ("@var{visibility_type}") 2436@cindex @code{visibility} attribute 2437This attribute affects the linkage of the declaration to which it is attached. 2438There are four supported @var{visibility_type} values: default, 2439hidden, protected or internal visibility. 2440 2441@smallexample 2442void __attribute__ ((visibility ("protected"))) 2443f () @{ /* @r{Do something.} */; @} 2444int i __attribute__ ((visibility ("hidden"))); 2445@end smallexample 2446 2447The possible values of @var{visibility_type} correspond to the 2448visibility settings in the ELF gABI. 2449 2450@table @dfn 2451@c keep this list of visibilities in alphabetical order. 2452 2453@item default 2454Default visibility is the normal case for the object file format. 2455This value is available for the visibility attribute to override other 2456options that may change the assumed visibility of entities. 2457 2458On ELF, default visibility means that the declaration is visible to other 2459modules and, in shared libraries, means that the declared entity may be 2460overridden. 2461 2462On Darwin, default visibility means that the declaration is visible to 2463other modules. 2464 2465Default visibility corresponds to ``external linkage'' in the language. 2466 2467@item hidden 2468Hidden visibility indicates that the entity declared will have a new 2469form of linkage, which we'll call ``hidden linkage''. Two 2470declarations of an object with hidden linkage refer to the same object 2471if they are in the same shared object. 2472 2473@item internal 2474Internal visibility is like hidden visibility, but with additional 2475processor specific semantics. Unless otherwise specified by the 2476psABI, GCC defines internal visibility to mean that a function is 2477@emph{never} called from another module. Compare this with hidden 2478functions which, while they cannot be referenced directly by other 2479modules, can be referenced indirectly via function pointers. By 2480indicating that a function cannot be called from outside the module, 2481GCC may for instance omit the load of a PIC register since it is known 2482that the calling function loaded the correct value. 2483 2484@item protected 2485Protected visibility is like default visibility except that it 2486indicates that references within the defining module will bind to the 2487definition in that module. That is, the declared entity cannot be 2488overridden by another module. 2489 2490@end table 2491 2492All visibilities are supported on many, but not all, ELF targets 2493(supported when the assembler supports the @samp{.visibility} 2494pseudo-op). Default visibility is supported everywhere. Hidden 2495visibility is supported on Darwin targets. 2496 2497The visibility attribute should be applied only to declarations which 2498would otherwise have external linkage. The attribute should be applied 2499consistently, so that the same entity should not be declared with 2500different settings of the attribute. 2501 2502In C++, the visibility attribute applies to types as well as functions 2503and objects, because in C++ types have linkage. A class must not have 2504greater visibility than its non-static data member types and bases, 2505and class members default to the visibility of their class. Also, a 2506declaration without explicit visibility is limited to the visibility 2507of its type. 2508 2509In C++, you can mark member functions and static member variables of a 2510class with the visibility attribute. This is useful if if you know a 2511particular method or static member variable should only be used from 2512one shared object; then you can mark it hidden while the rest of the 2513class has default visibility. Care must be taken to avoid breaking 2514the One Definition Rule; for example, it is usually not useful to mark 2515an inline method as hidden without marking the whole class as hidden. 2516 2517A C++ namespace declaration can also have the visibility attribute. 2518This attribute applies only to the particular namespace body, not to 2519other definitions of the same namespace; it is equivalent to using 2520@samp{#pragma GCC visibility} before and after the namespace 2521definition (@pxref{Visibility Pragmas}). 2522 2523In C++, if a template argument has limited visibility, this 2524restriction is implicitly propagated to the template instantiation. 2525Otherwise, template instantiations and specializations default to the 2526visibility of their template. 2527 2528If both the template and enclosing class have explicit visibility, the 2529visibility from the template is used. 2530 2531@item warn_unused_result 2532@cindex @code{warn_unused_result} attribute 2533The @code{warn_unused_result} attribute causes a warning to be emitted 2534if a caller of the function with this attribute does not use its 2535return value. This is useful for functions where not checking 2536the result is either a security problem or always a bug, such as 2537@code{realloc}. 2538 2539@smallexample 2540int fn () __attribute__ ((warn_unused_result)); 2541int foo () 2542@{ 2543 if (fn () < 0) return -1; 2544 fn (); 2545 return 0; 2546@} 2547@end smallexample 2548 2549results in warning on line 5. 2550 2551@item weak 2552@cindex @code{weak} attribute 2553The @code{weak} attribute causes the declaration to be emitted as a weak 2554symbol rather than a global. This is primarily useful in defining 2555library functions which can be overridden in user code, though it can 2556also be used with non-function declarations. Weak symbols are supported 2557for ELF targets, and also for a.out targets when using the GNU assembler 2558and linker. 2559 2560@item weakref 2561@itemx weakref ("@var{target}") 2562@cindex @code{weakref} attribute 2563The @code{weakref} attribute marks a declaration as a weak reference. 2564Without arguments, it should be accompanied by an @code{alias} attribute 2565naming the target symbol. Optionally, the @var{target} may be given as 2566an argument to @code{weakref} itself. In either case, @code{weakref} 2567implicitly marks the declaration as @code{weak}. Without a 2568@var{target}, given as an argument to @code{weakref} or to @code{alias}, 2569@code{weakref} is equivalent to @code{weak}. 2570 2571@smallexample 2572static int x() __attribute__ ((weakref ("y"))); 2573/* is equivalent to... */ 2574static int x() __attribute__ ((weak, weakref, alias ("y"))); 2575/* and to... */ 2576static int x() __attribute__ ((weakref)); 2577static int x() __attribute__ ((alias ("y"))); 2578@end smallexample 2579 2580A weak reference is an alias that does not by itself require a 2581definition to be given for the target symbol. If the target symbol is 2582only referenced through weak references, then the becomes a @code{weak} 2583undefined symbol. If it is directly referenced, however, then such 2584strong references prevail, and a definition will be required for the 2585symbol, not necessarily in the same translation unit. 2586 2587The effect is equivalent to moving all references to the alias to a 2588separate translation unit, renaming the alias to the aliased symbol, 2589declaring it as weak, compiling the two separate translation units and 2590performing a reloadable link on them. 2591 2592At present, a declaration to which @code{weakref} is attached can 2593only be @code{static}. 2594 2595@item externally_visible 2596@cindex @code{externally_visible} attribute. 2597This attribute, attached to a global variable or function nullify 2598effect of @option{-fwhole-program} command line option, so the object 2599remain visible outside the current compilation unit 2600 2601@end table 2602 2603You can specify multiple attributes in a declaration by separating them 2604by commas within the double parentheses or by immediately following an 2605attribute declaration with another attribute declaration. 2606 2607@cindex @code{#pragma}, reason for not using 2608@cindex pragma, reason for not using 2609Some people object to the @code{__attribute__} feature, suggesting that 2610ISO C's @code{#pragma} should be used instead. At the time 2611@code{__attribute__} was designed, there were two reasons for not doing 2612this. 2613 2614@enumerate 2615@item 2616It is impossible to generate @code{#pragma} commands from a macro. 2617 2618@item 2619There is no telling what the same @code{#pragma} might mean in another 2620compiler. 2621@end enumerate 2622 2623These two reasons applied to almost any application that might have been 2624proposed for @code{#pragma}. It was basically a mistake to use 2625@code{#pragma} for @emph{anything}. 2626 2627The ISO C99 standard includes @code{_Pragma}, which now allows pragmas 2628to be generated from macros. In addition, a @code{#pragma GCC} 2629namespace is now in use for GCC-specific pragmas. However, it has been 2630found convenient to use @code{__attribute__} to achieve a natural 2631attachment of attributes to their corresponding declarations, whereas 2632@code{#pragma GCC} is of use for constructs that do not naturally form 2633part of the grammar. @xref{Other Directives,,Miscellaneous 2634Preprocessing Directives, cpp, The GNU C Preprocessor}. 2635 2636@node Attribute Syntax 2637@section Attribute Syntax 2638@cindex attribute syntax 2639 2640This section describes the syntax with which @code{__attribute__} may be 2641used, and the constructs to which attribute specifiers bind, for the C 2642language. Some details may vary for C++. Because of infelicities in 2643the grammar for attributes, some forms described here may not be 2644successfully parsed in all cases. 2645 2646There are some problems with the semantics of attributes in C++. For 2647example, there are no manglings for attributes, although they may affect 2648code generation, so problems may arise when attributed types are used in 2649conjunction with templates or overloading. Similarly, @code{typeid} 2650does not distinguish between types with different attributes. Support 2651for attributes in C++ may be restricted in future to attributes on 2652declarations only, but not on nested declarators. 2653 2654@xref{Function Attributes}, for details of the semantics of attributes 2655applying to functions. @xref{Variable Attributes}, for details of the 2656@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 2657semantics of attributes applying to variables. @xref{Type 2658Attributes}, for details of the semantics of attributes applying to 2659structure, union and enumerated types. @xref{Label Attributes}, for 2660details of the semantics of attributes applying to labels and 2661statements. 2662 2663@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 2664An @dfn{attribute specifier} is of the form 2665@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} 2666is a possibly empty comma-separated sequence of @dfn{attributes}, where 2667each attribute is one of the following: 2668 2669@itemize @bullet 2670@item 2671Empty. Empty attributes are ignored. 2672 2673@item 2674A word (which may be an identifier such as @code{unused}, or a reserved 2675word such as @code{const}). 2676 2677@item 2678A word, followed by, in parentheses, parameters for the attribute. 2679These parameters take one of the following forms: 2680 2681@itemize @bullet 2682@item 2683An identifier. For example, @code{mode} attributes use this form. 2684 2685@item 2686An identifier followed by a comma and a non-empty comma-separated list 2687of expressions. For example, @code{format} attributes use this form. 2688 2689@item 2690A possibly empty comma-separated list of expressions. For example, 2691@code{format_arg} attributes use this form with the list being a single 2692integer constant expression, and @code{alias} attributes use this form 2693with the list being a single string constant. 2694@end itemize 2695@end itemize 2696 2697An @dfn{attribute specifier list} is a sequence of one or more attribute 2698specifiers, not separated by any other tokens. 2699 2700@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 2701In GNU C, an attribute specifier list may appear after the colon 2702following a label, other than a @code{case} or @code{default} label. 2703GNU C++ does not permit such placement of attribute lists, as it is 2704permissible for a declaration, which could begin with an attribute 2705list, to be labelled in C++. Declarations cannot be labelled in C90 2706or C99, so the ambiguity does not arise there. 2707 2708In GNU C an attribute specifier list may also appear after the keyword 2709@code{while} in a while loop, after @code{do} and after @code{for}. 2710 2711@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 2712An attribute specifier list may appear as part of a @code{struct}, 2713@code{union} or @code{enum} specifier. It may go either immediately 2714after the @code{struct}, @code{union} or @code{enum} keyword, or after 2715the closing brace. The former syntax is preferred. 2716Where attribute specifiers follow the closing brace, they are considered 2717to relate to the structure, union or enumerated type defined, not to any 2718enclosing declaration the type specifier appears in, and the type 2719defined is not complete until after the attribute specifiers. 2720@c Otherwise, there would be the following problems: a shift/reduce 2721@c conflict between attributes binding the struct/union/enum and 2722@c binding to the list of specifiers/qualifiers; and "aligned" 2723@c attributes could use sizeof for the structure, but the size could be 2724@c changed later by "packed" attributes. 2725 2726Otherwise, an attribute specifier appears as part of a declaration, 2727counting declarations of unnamed parameters and type names, and relates 2728to that declaration (which may be nested in another declaration, for 2729example in the case of a parameter declaration), or to a particular declarator 2730within a declaration. Where an 2731attribute specifier is applied to a parameter declared as a function or 2732an array, it should apply to the function or array rather than the 2733pointer to which the parameter is implicitly converted, but this is not 2734yet correctly implemented. 2735 2736Any list of specifiers and qualifiers at the start of a declaration may 2737contain attribute specifiers, whether or not such a list may in that 2738context contain storage class specifiers. (Some attributes, however, 2739are essentially in the nature of storage class specifiers, and only make 2740sense where storage class specifiers may be used; for example, 2741@code{section}.) There is one necessary limitation to this syntax: the 2742first old-style parameter declaration in a function definition cannot 2743begin with an attribute specifier, because such an attribute applies to 2744the function instead by syntax described below (which, however, is not 2745yet implemented in this case). In some other cases, attribute 2746specifiers are permitted by this grammar but not yet supported by the 2747compiler. All attribute specifiers in this place relate to the 2748declaration as a whole. In the obsolescent usage where a type of 2749@code{int} is implied by the absence of type specifiers, such a list of 2750specifiers and qualifiers may be an attribute specifier list with no 2751other specifiers or qualifiers. 2752 2753At present, the first parameter in a function prototype must have some 2754type specifier which is not an attribute specifier; this resolves an 2755ambiguity in the interpretation of @code{void f(int 2756(__attribute__((foo)) x))}, but is subject to change. At present, if 2757the parentheses of a function declarator contain only attributes then 2758those attributes are ignored, rather than yielding an error or warning 2759or implying a single parameter of type int, but this is subject to 2760change. 2761 2762An attribute specifier list may appear immediately before a declarator 2763(other than the first) in a comma-separated list of declarators in a 2764declaration of more than one identifier using a single list of 2765specifiers and qualifiers. Such attribute specifiers apply 2766only to the identifier before whose declarator they appear. For 2767example, in 2768 2769@smallexample 2770__attribute__((noreturn)) void d0 (void), 2771 __attribute__((format(printf, 1, 2))) d1 (const char *, ...), 2772 d2 (void) 2773@end smallexample 2774 2775@noindent 2776the @code{noreturn} attribute applies to all the functions 2777declared; the @code{format} attribute only applies to @code{d1}. 2778 2779An attribute specifier list may appear immediately before the comma, 2780@code{=} or semicolon terminating the declaration of an identifier other 2781than a function definition. At present, such attribute specifiers apply 2782to the declared object or function, but in future they may attach to the 2783outermost adjacent declarator. In simple cases there is no difference, 2784but, for example, in 2785 2786@smallexample 2787void (****f)(void) __attribute__((noreturn)); 2788@end smallexample 2789 2790@noindent 2791at present the @code{noreturn} attribute applies to @code{f}, which 2792causes a warning since @code{f} is not a function, but in future it may 2793apply to the function @code{****f}. The precise semantics of what 2794attributes in such cases will apply to are not yet specified. Where an 2795assembler name for an object or function is specified (@pxref{Asm 2796Labels}), at present the attribute must follow the @code{asm} 2797specification; in future, attributes before the @code{asm} specification 2798may apply to the adjacent declarator, and those after it to the declared 2799object or function. 2800 2801An attribute specifier list may, in future, be permitted to appear after 2802the declarator in a function definition (before any old-style parameter 2803declarations or the function body). 2804 2805Attribute specifiers may be mixed with type qualifiers appearing inside 2806the @code{[]} of a parameter array declarator, in the C99 construct by 2807which such qualifiers are applied to the pointer to which the array is 2808implicitly converted. Such attribute specifiers apply to the pointer, 2809not to the array, but at present this is not implemented and they are 2810ignored. 2811 2812An attribute specifier list may appear at the start of a nested 2813declarator. At present, there are some limitations in this usage: the 2814attributes correctly apply to the declarator, but for most individual 2815attributes the semantics this implies are not implemented. 2816When attribute specifiers follow the @code{*} of a pointer 2817declarator, they may be mixed with any type qualifiers present. 2818The following describes the formal semantics of this syntax. It will make the 2819most sense if you are familiar with the formal specification of 2820declarators in the ISO C standard. 2821 2822Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T 2823D1}, where @code{T} contains declaration specifiers that specify a type 2824@var{Type} (such as @code{int}) and @code{D1} is a declarator that 2825contains an identifier @var{ident}. The type specified for @var{ident} 2826for derived declarators whose type does not include an attribute 2827specifier is as in the ISO C standard. 2828 2829If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, 2830and the declaration @code{T D} specifies the type 2831``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 2832@code{T D1} specifies the type ``@var{derived-declarator-type-list} 2833@var{attribute-specifier-list} @var{Type}'' for @var{ident}. 2834 2835If @code{D1} has the form @code{* 2836@var{type-qualifier-and-attribute-specifier-list} D}, and the 2837declaration @code{T D} specifies the type 2838``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 2839@code{T D1} specifies the type ``@var{derived-declarator-type-list} 2840@var{type-qualifier-and-attribute-specifier-list} @var{Type}'' for 2841@var{ident}. 2842 2843For example, 2844 2845@smallexample 2846void (__attribute__((noreturn)) ****f) (void); 2847@end smallexample 2848 2849@noindent 2850specifies the type ``pointer to pointer to pointer to pointer to 2851non-returning function returning @code{void}''. As another example, 2852 2853@smallexample 2854char *__attribute__((aligned(8))) *f; 2855@end smallexample 2856 2857@noindent 2858specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. 2859Note again that this does not work with most attributes; for example, 2860the usage of @samp{aligned} and @samp{noreturn} attributes given above 2861is not yet supported. 2862 2863For compatibility with existing code written for compiler versions that 2864did not implement attributes on nested declarators, some laxity is 2865allowed in the placing of attributes. If an attribute that only applies 2866to types is applied to a declaration, it will be treated as applying to 2867the type of that declaration. If an attribute that only applies to 2868declarations is applied to the type of a declaration, it will be treated 2869as applying to that declaration; and, for compatibility with code 2870placing the attributes immediately before the identifier declared, such 2871an attribute applied to a function return type will be treated as 2872applying to the function type, and such an attribute applied to an array 2873element type will be treated as applying to the array type. If an 2874attribute that only applies to function types is applied to a 2875pointer-to-function type, it will be treated as applying to the pointer 2876target type; if such an attribute is applied to a function return type 2877that is not a pointer-to-function type, it will be treated as applying 2878to the function type. 2879 2880@node Function Prototypes 2881@section Prototypes and Old-Style Function Definitions 2882@cindex function prototype declarations 2883@cindex old-style function definitions 2884@cindex promotion of formal parameters 2885 2886GNU C extends ISO C to allow a function prototype to override a later 2887old-style non-prototype definition. Consider the following example: 2888 2889@smallexample 2890/* @r{Use prototypes unless the compiler is old-fashioned.} */ 2891#ifdef __STDC__ 2892#define P(x) x 2893#else 2894#define P(x) () 2895#endif 2896 2897/* @r{Prototype function declaration.} */ 2898int isroot P((uid_t)); 2899 2900/* @r{Old-style function definition.} */ 2901int 2902isroot (x) /* @r{??? lossage here ???} */ 2903 uid_t x; 2904@{ 2905 return x == 0; 2906@} 2907@end smallexample 2908 2909Suppose the type @code{uid_t} happens to be @code{short}. ISO C does 2910not allow this example, because subword arguments in old-style 2911non-prototype definitions are promoted. Therefore in this example the 2912function definition's argument is really an @code{int}, which does not 2913match the prototype argument type of @code{short}. 2914 2915This restriction of ISO C makes it hard to write code that is portable 2916to traditional C compilers, because the programmer does not know 2917whether the @code{uid_t} type is @code{short}, @code{int}, or 2918@code{long}. Therefore, in cases like these GNU C allows a prototype 2919to override a later old-style definition. More precisely, in GNU C, a 2920function prototype argument type overrides the argument type specified 2921by a later old-style definition if the former type is the same as the 2922latter type before promotion. Thus in GNU C the above example is 2923equivalent to the following: 2924 2925@smallexample 2926int isroot (uid_t); 2927 2928int 2929isroot (uid_t x) 2930@{ 2931 return x == 0; 2932@} 2933@end smallexample 2934 2935@noindent 2936GNU C++ does not support old-style function definitions, so this 2937extension is irrelevant. 2938 2939@node C++ Comments 2940@section C++ Style Comments 2941@cindex // 2942@cindex C++ comments 2943@cindex comments, C++ style 2944 2945In GNU C, you may use C++ style comments, which start with @samp{//} and 2946continue until the end of the line. Many other C implementations allow 2947such comments, and they are included in the 1999 C standard. However, 2948C++ style comments are not recognized if you specify an @option{-std} 2949option specifying a version of ISO C before C99, or @option{-ansi} 2950(equivalent to @option{-std=c89}). 2951 2952@node Dollar Signs 2953@section Dollar Signs in Identifier Names 2954@cindex $ 2955@cindex dollar signs in identifier names 2956@cindex identifier names, dollar signs in 2957 2958In GNU C, you may normally use dollar signs in identifier names. 2959This is because many traditional C implementations allow such identifiers. 2960However, dollar signs in identifiers are not supported on a few target 2961machines, typically because the target assembler does not allow them. 2962 2963@node Character Escapes 2964@section The Character @key{ESC} in Constants 2965 2966You can use the sequence @samp{\e} in a string or character constant to 2967stand for the ASCII character @key{ESC}. 2968 2969@node Alignment 2970@section Inquiring on Alignment of Types or Variables 2971@cindex alignment 2972@cindex type alignment 2973@cindex variable alignment 2974 2975The keyword @code{__alignof__} allows you to inquire about how an object 2976is aligned, or the minimum alignment usually required by a type. Its 2977syntax is just like @code{sizeof}. 2978 2979For example, if the target machine requires a @code{double} value to be 2980aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. 2981This is true on many RISC machines. On more traditional machine 2982designs, @code{__alignof__ (double)} is 4 or even 2. 2983 2984Some machines never actually require alignment; they allow reference to any 2985data type even at an odd address. For these machines, @code{__alignof__} 2986reports the @emph{recommended} alignment of a type. 2987 2988If the operand of @code{__alignof__} is an lvalue rather than a type, 2989its value is the required alignment for its type, taking into account 2990any minimum alignment specified with GCC's @code{__attribute__} 2991extension (@pxref{Variable Attributes}). For example, after this 2992declaration: 2993 2994@smallexample 2995struct foo @{ int x; char y; @} foo1; 2996@end smallexample 2997 2998@noindent 2999the value of @code{__alignof__ (foo1.y)} is 1, even though its actual 3000alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. 3001 3002It is an error to ask for the alignment of an incomplete type. 3003 3004@node Variable Attributes 3005@section Specifying Attributes of Variables 3006@cindex attribute of variables 3007@cindex variable attributes 3008 3009The keyword @code{__attribute__} allows you to specify special 3010attributes of variables or structure fields. This keyword is followed 3011by an attribute specification inside double parentheses. Some 3012attributes are currently defined generically for variables. 3013Other attributes are defined for variables on particular target 3014systems. Other attributes are available for functions 3015@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 3016(@pxref{Function Attributes}), types (@pxref{Type Attributes}) and 3017labels (@pxref{Label Attributes}). Other front ends might define 3018more attributes (@pxref{C++ Extensions,,Extensions to the C++ Language}). 3019 3020@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 3021You may also specify attributes with @samp{__} preceding and following 3022each keyword. This allows you to use them in header files without 3023being concerned about a possible macro of the same name. For example, 3024you may use @code{__aligned__} instead of @code{aligned}. 3025 3026@xref{Attribute Syntax}, for details of the exact syntax for using 3027attributes. 3028 3029@table @code 3030@cindex @code{aligned} attribute 3031@item aligned (@var{alignment}) 3032This attribute specifies a minimum alignment for the variable or 3033structure field, measured in bytes. For example, the declaration: 3034 3035@smallexample 3036int x __attribute__ ((aligned (16))) = 0; 3037@end smallexample 3038 3039@noindent 3040causes the compiler to allocate the global variable @code{x} on a 304116-byte boundary. On a 68040, this could be used in conjunction with 3042an @code{asm} expression to access the @code{move16} instruction which 3043requires 16-byte aligned operands. 3044 3045You can also specify the alignment of structure fields. For example, to 3046create a double-word aligned @code{int} pair, you could write: 3047 3048@smallexample 3049struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; 3050@end smallexample 3051 3052@noindent 3053This is an alternative to creating a union with a @code{double} member 3054that forces the union to be double-word aligned. 3055 3056As in the preceding examples, you can explicitly specify the alignment 3057(in bytes) that you wish the compiler to use for a given variable or 3058structure field. Alternatively, you can leave out the alignment factor 3059and just ask the compiler to align a variable or field to the maximum 3060useful alignment for the target machine you are compiling for. For 3061example, you could write: 3062 3063@smallexample 3064short array[3] __attribute__ ((aligned)); 3065@end smallexample 3066 3067Whenever you leave out the alignment factor in an @code{aligned} attribute 3068specification, the compiler automatically sets the alignment for the declared 3069variable or field to the largest alignment which is ever used for any data 3070type on the target machine you are compiling for. Doing this can often make 3071copy operations more efficient, because the compiler can use whatever 3072instructions copy the biggest chunks of memory when performing copies to 3073or from the variables or fields that you have aligned this way. 3074 3075The @code{aligned} attribute can only increase the alignment; but you 3076can decrease it by specifying @code{packed} as well. See below. 3077 3078Note that the effectiveness of @code{aligned} attributes may be limited 3079by inherent limitations in your linker. On many systems, the linker is 3080only able to arrange for variables to be aligned up to a certain maximum 3081alignment. (For some linkers, the maximum supported alignment may 3082be very very small.) If your linker is only able to align variables 3083up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} 3084in an @code{__attribute__} will still only provide you with 8 byte 3085alignment. See your linker documentation for further information. 3086 3087The @code{aligned} attribute can also be used for functions 3088(@pxref{Function Attributes}.) 3089 3090@item cleanup (@var{cleanup_function}) 3091@cindex @code{cleanup} attribute 3092The @code{cleanup} attribute runs a function when the variable goes 3093out of scope. This attribute can only be applied to auto function 3094scope variables; it may not be applied to parameters or variables 3095with static storage duration. The function must take one parameter, 3096a pointer to a type compatible with the variable. The return value 3097of the function (if any) is ignored. 3098 3099If @option{-fexceptions} is enabled, then @var{cleanup_function} 3100will be run during the stack unwinding that happens during the 3101processing of the exception. Note that the @code{cleanup} attribute 3102does not allow the exception to be caught, only to perform an action. 3103It is undefined what happens if @var{cleanup_function} does not 3104return normally. 3105 3106@item common 3107@itemx nocommon 3108@cindex @code{common} attribute 3109@cindex @code{nocommon} attribute 3110@opindex fcommon 3111@opindex fno-common 3112The @code{common} attribute requests GCC to place a variable in 3113``common'' storage. The @code{nocommon} attribute requests the 3114opposite---to allocate space for it directly. 3115 3116These attributes override the default chosen by the 3117@option{-fno-common} and @option{-fcommon} flags respectively. 3118 3119@item deprecated 3120@cindex @code{deprecated} attribute 3121The @code{deprecated} attribute results in a warning if the variable 3122is used anywhere in the source file. This is useful when identifying 3123variables that are expected to be removed in a future version of a 3124program. The warning also includes the location of the declaration 3125of the deprecated variable, to enable users to easily find further 3126information about why the variable is deprecated, or what they should 3127do instead. Note that the warning only occurs for uses: 3128 3129@smallexample 3130extern int old_var __attribute__ ((deprecated)); 3131extern int old_var; 3132int new_fn () @{ return old_var; @} 3133@end smallexample 3134 3135results in a warning on line 3 but not line 2. 3136 3137The @code{deprecated} attribute can also be used for functions and 3138types (@pxref{Function Attributes}, @pxref{Type Attributes}.) 3139 3140@item mode (@var{mode}) 3141@cindex @code{mode} attribute 3142This attribute specifies the data type for the declaration---whichever 3143type corresponds to the mode @var{mode}. This in effect lets you 3144request an integer or floating point type according to its width. 3145 3146You may also specify a mode of @samp{byte} or @samp{__byte__} to 3147indicate the mode corresponding to a one-byte integer, @samp{word} or 3148@samp{__word__} for the mode of a one-word integer, and @samp{pointer} 3149or @samp{__pointer__} for the mode used to represent pointers. 3150 3151@item packed 3152@cindex @code{packed} attribute 3153The @code{packed} attribute specifies that a variable or structure field 3154should have the smallest possible alignment---one byte for a variable, 3155and one bit for a field, unless you specify a larger value with the 3156@code{aligned} attribute. 3157 3158Here is a structure in which the field @code{x} is packed, so that it 3159immediately follows @code{a}: 3160 3161@smallexample 3162struct foo 3163@{ 3164 char a; 3165 int x[2] __attribute__ ((packed)); 3166@}; 3167@end smallexample 3168 3169@item section ("@var{section-name}") 3170@cindex @code{section} variable attribute 3171Normally, the compiler places the objects it generates in sections like 3172@code{data} and @code{bss}. Sometimes, however, you need additional sections, 3173or you need certain particular variables to appear in special sections, 3174for example to map to special hardware. The @code{section} 3175attribute specifies that a variable (or function) lives in a particular 3176section. For example, this small program uses several specific section names: 3177 3178@smallexample 3179struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; 3180struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; 3181char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; 3182int init_data __attribute__ ((section ("INITDATA"))) = 0; 3183 3184main() 3185@{ 3186 /* @r{Initialize stack pointer} */ 3187 init_sp (stack + sizeof (stack)); 3188 3189 /* @r{Initialize initialized data} */ 3190 memcpy (&init_data, &data, &edata - &data); 3191 3192 /* @r{Turn on the serial ports} */ 3193 init_duart (&a); 3194 init_duart (&b); 3195@} 3196@end smallexample 3197 3198@noindent 3199Use the @code{section} attribute with an @emph{initialized} definition 3200of a @emph{global} variable, as shown in the example. GCC issues 3201a warning and otherwise ignores the @code{section} attribute in 3202uninitialized variable declarations. 3203 3204You may only use the @code{section} attribute with a fully initialized 3205global definition because of the way linkers work. The linker requires 3206each object be defined once, with the exception that uninitialized 3207variables tentatively go in the @code{common} (or @code{bss}) section 3208and can be multiply ``defined''. You can force a variable to be 3209initialized with the @option{-fno-common} flag or the @code{nocommon} 3210attribute. 3211 3212Some file formats do not support arbitrary sections so the @code{section} 3213attribute is not available on all platforms. 3214If you need to map the entire contents of a module to a particular 3215section, consider using the facilities of the linker instead. 3216 3217@item shared 3218@cindex @code{shared} variable attribute 3219On Microsoft Windows, in addition to putting variable definitions in a named 3220section, the section can also be shared among all running copies of an 3221executable or DLL@. For example, this small program defines shared data 3222by putting it in a named section @code{shared} and marking the section 3223shareable: 3224 3225@smallexample 3226int foo __attribute__((section ("shared"), shared)) = 0; 3227 3228int 3229main() 3230@{ 3231 /* @r{Read and write foo. All running 3232 copies see the same value.} */ 3233 return 0; 3234@} 3235@end smallexample 3236 3237@noindent 3238You may only use the @code{shared} attribute along with @code{section} 3239attribute with a fully initialized global definition because of the way 3240linkers work. See @code{section} attribute for more information. 3241 3242The @code{shared} attribute is only available on Microsoft Windows@. 3243 3244@item tls_model ("@var{tls_model}") 3245@cindex @code{tls_model} attribute 3246The @code{tls_model} attribute sets thread-local storage model 3247(@pxref{Thread-Local}) of a particular @code{__thread} variable, 3248overriding @option{-ftls-model=} command line switch on a per-variable 3249basis. 3250The @var{tls_model} argument should be one of @code{global-dynamic}, 3251@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. 3252 3253Not all targets support this attribute. 3254 3255@item unused 3256This attribute, attached to a variable, means that the variable is meant 3257to be possibly unused. GCC will not produce a warning for this 3258variable. 3259 3260@item used 3261This attribute, attached to a variable, means that the variable must be 3262emitted even if it appears that the variable is not referenced. 3263 3264@item vector_size (@var{bytes}) 3265This attribute specifies the vector size for the variable, measured in 3266bytes. For example, the declaration: 3267 3268@smallexample 3269int foo __attribute__ ((vector_size (16))); 3270@end smallexample 3271 3272@noindent 3273causes the compiler to set the mode for @code{foo}, to be 16 bytes, 3274divided into @code{int} sized units. Assuming a 32-bit int (a vector of 32754 units of 4 bytes), the corresponding mode of @code{foo} will be V4SI@. 3276 3277This attribute is only applicable to integral and float scalars, 3278although arrays, pointers, and function return values are allowed in 3279conjunction with this construct. 3280 3281Aggregates with this attribute are invalid, even if they are of the same 3282size as a corresponding scalar. For example, the declaration: 3283 3284@smallexample 3285struct S @{ int a; @}; 3286struct S __attribute__ ((vector_size (16))) foo; 3287@end smallexample 3288 3289@noindent 3290is invalid even if the size of the structure is the same as the size of 3291the @code{int}. 3292 3293@item selectany 3294The @code{selectany} attribute causes an initialized global variable to 3295have link-once semantics. When multiple definitions of the variable are 3296encountered by the linker, the first is selected and the remainder are 3297discarded. Following usage by the Microsoft compiler, the linker is told 3298@emph{not} to warn about size or content differences of the multiple 3299definitions. 3300 3301Although the primary usage of this attribute is for POD types, the 3302attribute can also be applied to global C++ objects that are initialized 3303by a constructor. In this case, the static initialization and destruction 3304code for the object is emitted in each translation defining the object, 3305but the calls to the constructor and destructor are protected by a 3306link-once guard variable. 3307 3308The @code{selectany} attribute is only available on Microsoft Windows 3309targets. You can use @code{__declspec (selectany)} as a synonym for 3310@code{__attribute__ ((selectany))} for compatibility with other 3311compilers. 3312 3313@item weak 3314The @code{weak} attribute is described in @xref{Function Attributes}. 3315 3316@item dllimport 3317The @code{dllimport} attribute is described in @xref{Function Attributes}. 3318 3319@item dllexport 3320The @code{dllexport} attribute is described in @xref{Function Attributes}. 3321 3322@end table 3323 3324@subsection M32R/D Variable Attributes 3325 3326One attribute is currently defined for the M32R/D@. 3327 3328@table @code 3329@item model (@var{model-name}) 3330@cindex variable addressability on the M32R/D 3331Use this attribute on the M32R/D to set the addressability of an object. 3332The identifier @var{model-name} is one of @code{small}, @code{medium}, 3333or @code{large}, representing each of the code models. 3334 3335Small model objects live in the lower 16MB of memory (so that their 3336addresses can be loaded with the @code{ld24} instruction). 3337 3338Medium and large model objects may live anywhere in the 32-bit address space 3339(the compiler will generate @code{seth/add3} instructions to load their 3340addresses). 3341@end table 3342 3343@anchor{i386 Variable Attributes} 3344@subsection i386 Variable Attributes 3345 3346Two attributes are currently defined for i386 configurations: 3347@code{ms_struct} and @code{gcc_struct} 3348 3349@table @code 3350@item ms_struct 3351@itemx gcc_struct 3352@cindex @code{ms_struct} attribute 3353@cindex @code{gcc_struct} attribute 3354 3355If @code{packed} is used on a structure, or if bit-fields are used 3356it may be that the Microsoft ABI packs them differently 3357than GCC would normally pack them. Particularly when moving packed 3358data between functions compiled with GCC and the native Microsoft compiler 3359(either via function call or as data in a file), it may be necessary to access 3360either format. 3361 3362Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 3363compilers to match the native Microsoft compiler. 3364 3365The Microsoft structure layout algorithm is fairly simple with the exception 3366of the bitfield packing: 3367 3368The padding and alignment of members of structures and whether a bit field 3369can straddle a storage-unit boundary 3370 3371@enumerate 3372@item Structure members are stored sequentially in the order in which they are 3373declared: the first member has the lowest memory address and the last member 3374the highest. 3375 3376@item Every data object has an alignment-requirement. The alignment-requirement 3377for all data except structures, unions, and arrays is either the size of the 3378object or the current packing size (specified with either the aligned attribute 3379or the pack pragma), whichever is less. For structures, unions, and arrays, 3380the alignment-requirement is the largest alignment-requirement of its members. 3381Every object is allocated an offset so that: 3382 3383offset % alignment-requirement == 0 3384 3385@item Adjacent bit fields are packed into the same 1-, 2-, or 4-byte allocation 3386unit if the integral types are the same size and if the next bit field fits 3387into the current allocation unit without crossing the boundary imposed by the 3388common alignment requirements of the bit fields. 3389@end enumerate 3390 3391Handling of zero-length bitfields: 3392 3393MSVC interprets zero-length bitfields in the following ways: 3394 3395@enumerate 3396@item If a zero-length bitfield is inserted between two bitfields that would 3397normally be coalesced, the bitfields will not be coalesced. 3398 3399For example: 3400 3401@smallexample 3402struct 3403 @{ 3404 unsigned long bf_1 : 12; 3405 unsigned long : 0; 3406 unsigned long bf_2 : 12; 3407 @} t1; 3408@end smallexample 3409 3410The size of @code{t1} would be 8 bytes with the zero-length bitfield. If the 3411zero-length bitfield were removed, @code{t1}'s size would be 4 bytes. 3412 3413@item If a zero-length bitfield is inserted after a bitfield, @code{foo}, and the 3414alignment of the zero-length bitfield is greater than the member that follows it, 3415@code{bar}, @code{bar} will be aligned as the type of the zero-length bitfield. 3416 3417For example: 3418 3419@smallexample 3420struct 3421 @{ 3422 char foo : 4; 3423 short : 0; 3424 char bar; 3425 @} t2; 3426 3427struct 3428 @{ 3429 char foo : 4; 3430 short : 0; 3431 double bar; 3432 @} t3; 3433@end smallexample 3434 3435For @code{t2}, @code{bar} will be placed at offset 2, rather than offset 1. 3436Accordingly, the size of @code{t2} will be 4. For @code{t3}, the zero-length 3437bitfield will not affect the alignment of @code{bar} or, as a result, the size 3438of the structure. 3439 3440Taking this into account, it is important to note the following: 3441 3442@enumerate 3443@item If a zero-length bitfield follows a normal bitfield, the type of the 3444zero-length bitfield may affect the alignment of the structure as whole. For 3445example, @code{t2} has a size of 4 bytes, since the zero-length bitfield follows a 3446normal bitfield, and is of type short. 3447 3448@item Even if a zero-length bitfield is not followed by a normal bitfield, it may 3449still affect the alignment of the structure: 3450 3451@smallexample 3452struct 3453 @{ 3454 char foo : 6; 3455 long : 0; 3456 @} t4; 3457@end smallexample 3458 3459Here, @code{t4} will take up 4 bytes. 3460@end enumerate 3461 3462@item Zero-length bitfields following non-bitfield members are ignored: 3463 3464@smallexample 3465struct 3466 @{ 3467 char foo; 3468 long : 0; 3469 char bar; 3470 @} t5; 3471@end smallexample 3472 3473Here, @code{t5} will take up 2 bytes. 3474@end enumerate 3475@end table 3476 3477@subsection PowerPC Variable Attributes 3478 3479Three attributes currently are defined for PowerPC configurations: 3480@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 3481 3482For full documentation of the struct attributes please see the 3483documentation in the @xref{i386 Variable Attributes}, section. 3484 3485For documentation of @code{altivec} attribute please see the 3486documentation in the @xref{PowerPC Type Attributes}, section. 3487 3488@subsection Xstormy16 Variable Attributes 3489 3490One attribute is currently defined for xstormy16 configurations: 3491@code{below100} 3492 3493@table @code 3494@item below100 3495@cindex @code{below100} attribute 3496 3497If a variable has the @code{below100} attribute (@code{BELOW100} is 3498allowed also), GCC will place the variable in the first 0x100 bytes of 3499memory and use special opcodes to access it. Such variables will be 3500placed in either the @code{.bss_below100} section or the 3501@code{.data_below100} section. 3502 3503@end table 3504 3505@node Type Attributes 3506@section Specifying Attributes of Types 3507@cindex attribute of types 3508@cindex type attributes 3509 3510The keyword @code{__attribute__} allows you to specify special 3511attributes of @code{struct} and @code{union} types when you define 3512such types. This keyword is followed by an attribute specification 3513inside double parentheses. Seven attributes are currently defined for 3514types: @code{aligned}, @code{packed}, @code{transparent_union}, 3515@code{unused}, @code{deprecated}, @code{visibility}, and 3516@code{may_alias}. Other attributes are defined for functions 3517@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 3518(@pxref{Function Attributes}), variables (@pxref{Variable 3519Attributes}), and labels (@pxref{Label Attributes}). 3520 3521@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 3522You may also specify any one of these attributes with @samp{__} 3523preceding and following its keyword. This allows you to use these 3524attributes in header files without being concerned about a possible 3525macro of the same name. For example, you may use @code{__aligned__} 3526instead of @code{aligned}. 3527 3528You may specify type attributes either in a @code{typedef} declaration 3529or in an enum, struct or union type declaration or definition. 3530 3531For an enum, struct or union type, you may specify attributes either 3532between the enum, struct or union tag and the name of the type, or 3533just past the closing curly brace of the @emph{definition}. The 3534former syntax is preferred. 3535 3536@xref{Attribute Syntax}, for details of the exact syntax for using 3537attributes. 3538 3539@table @code 3540@cindex @code{aligned} attribute 3541@item aligned (@var{alignment}) 3542This attribute specifies a minimum alignment (in bytes) for variables 3543of the specified type. For example, the declarations: 3544 3545@smallexample 3546struct S @{ short f[3]; @} __attribute__ ((aligned (8))); 3547typedef int more_aligned_int __attribute__ ((aligned (8))); 3548@end smallexample 3549 3550@noindent 3551force the compiler to insure (as far as it can) that each variable whose 3552type is @code{struct S} or @code{more_aligned_int} will be allocated and 3553aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all 3554variables of type @code{struct S} aligned to 8-byte boundaries allows 3555the compiler to use the @code{ldd} and @code{std} (doubleword load and 3556store) instructions when copying one variable of type @code{struct S} to 3557another, thus improving run-time efficiency. 3558 3559Note that the alignment of any given @code{struct} or @code{union} type 3560is required by the ISO C standard to be at least a perfect multiple of 3561the lowest common multiple of the alignments of all of the members of 3562the @code{struct} or @code{union} in question. This means that you @emph{can} 3563effectively adjust the alignment of a @code{struct} or @code{union} 3564type by attaching an @code{aligned} attribute to any one of the members 3565of such a type, but the notation illustrated in the example above is a 3566more obvious, intuitive, and readable way to request the compiler to 3567adjust the alignment of an entire @code{struct} or @code{union} type. 3568 3569As in the preceding example, you can explicitly specify the alignment 3570(in bytes) that you wish the compiler to use for a given @code{struct} 3571or @code{union} type. Alternatively, you can leave out the alignment factor 3572and just ask the compiler to align a type to the maximum 3573useful alignment for the target machine you are compiling for. For 3574example, you could write: 3575 3576@smallexample 3577struct S @{ short f[3]; @} __attribute__ ((aligned)); 3578@end smallexample 3579 3580Whenever you leave out the alignment factor in an @code{aligned} 3581attribute specification, the compiler automatically sets the alignment 3582for the type to the largest alignment which is ever used for any data 3583type on the target machine you are compiling for. Doing this can often 3584make copy operations more efficient, because the compiler can use 3585whatever instructions copy the biggest chunks of memory when performing 3586copies to or from the variables which have types that you have aligned 3587this way. 3588 3589In the example above, if the size of each @code{short} is 2 bytes, then 3590the size of the entire @code{struct S} type is 6 bytes. The smallest 3591power of two which is greater than or equal to that is 8, so the 3592compiler sets the alignment for the entire @code{struct S} type to 8 3593bytes. 3594 3595Note that although you can ask the compiler to select a time-efficient 3596alignment for a given type and then declare only individual stand-alone 3597objects of that type, the compiler's ability to select a time-efficient 3598alignment is primarily useful only when you plan to create arrays of 3599variables having the relevant (efficiently aligned) type. If you 3600declare or use arrays of variables of an efficiently-aligned type, then 3601it is likely that your program will also be doing pointer arithmetic (or 3602subscripting, which amounts to the same thing) on pointers to the 3603relevant type, and the code that the compiler generates for these 3604pointer arithmetic operations will often be more efficient for 3605efficiently-aligned types than for other types. 3606 3607The @code{aligned} attribute can only increase the alignment; but you 3608can decrease it by specifying @code{packed} as well. See below. 3609 3610Note that the effectiveness of @code{aligned} attributes may be limited 3611by inherent limitations in your linker. On many systems, the linker is 3612only able to arrange for variables to be aligned up to a certain maximum 3613alignment. (For some linkers, the maximum supported alignment may 3614be very very small.) If your linker is only able to align variables 3615up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} 3616in an @code{__attribute__} will still only provide you with 8 byte 3617alignment. See your linker documentation for further information. 3618 3619@item packed 3620This attribute, attached to @code{struct} or @code{union} type 3621definition, specifies that each member (other than zero-width bitfields) 3622of the structure or union is placed to minimize the memory required. When 3623attached to an @code{enum} definition, it indicates that the smallest 3624integral type should be used. 3625 3626@opindex fshort-enums 3627Specifying this attribute for @code{struct} and @code{union} types is 3628equivalent to specifying the @code{packed} attribute on each of the 3629structure or union members. Specifying the @option{-fshort-enums} 3630flag on the line is equivalent to specifying the @code{packed} 3631attribute on all @code{enum} definitions. 3632 3633In the following example @code{struct my_packed_struct}'s members are 3634packed closely together, but the internal layout of its @code{s} member 3635is not packed---to do that, @code{struct my_unpacked_struct} would need to 3636be packed too. 3637 3638@smallexample 3639struct my_unpacked_struct 3640 @{ 3641 char c; 3642 int i; 3643 @}; 3644 3645struct __attribute__ ((__packed__)) my_packed_struct 3646 @{ 3647 char c; 3648 int i; 3649 struct my_unpacked_struct s; 3650 @}; 3651@end smallexample 3652 3653You may only specify this attribute on the definition of a @code{enum}, 3654@code{struct} or @code{union}, not on a @code{typedef} which does not 3655also define the enumerated type, structure or union. 3656 3657@item transparent_union 3658This attribute, attached to a @code{union} type definition, indicates 3659that any function parameter having that union type causes calls to that 3660function to be treated in a special way. 3661 3662First, the argument corresponding to a transparent union type can be of 3663any type in the union; no cast is required. Also, if the union contains 3664a pointer type, the corresponding argument can be a null pointer 3665constant or a void pointer expression; and if the union contains a void 3666pointer type, the corresponding argument can be any pointer expression. 3667If the union member type is a pointer, qualifiers like @code{const} on 3668the referenced type must be respected, just as with normal pointer 3669conversions. 3670 3671Second, the argument is passed to the function using the calling 3672conventions of the first member of the transparent union, not the calling 3673conventions of the union itself. All members of the union must have the 3674same machine representation; this is necessary for this argument passing 3675to work properly. 3676 3677Transparent unions are designed for library functions that have multiple 3678interfaces for compatibility reasons. For example, suppose the 3679@code{wait} function must accept either a value of type @code{int *} to 3680comply with Posix, or a value of type @code{union wait *} to comply with 3681the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, 3682@code{wait} would accept both kinds of arguments, but it would also 3683accept any other pointer type and this would make argument type checking 3684less useful. Instead, @code{<sys/wait.h>} might define the interface 3685as follows: 3686 3687@smallexample 3688typedef union 3689 @{ 3690 int *__ip; 3691 union wait *__up; 3692 @} wait_status_ptr_t __attribute__ ((__transparent_union__)); 3693 3694pid_t wait (wait_status_ptr_t); 3695@end smallexample 3696 3697This interface allows either @code{int *} or @code{union wait *} 3698arguments to be passed, using the @code{int *} calling convention. 3699The program can call @code{wait} with arguments of either type: 3700 3701@smallexample 3702int w1 () @{ int w; return wait (&w); @} 3703int w2 () @{ union wait w; return wait (&w); @} 3704@end smallexample 3705 3706With this interface, @code{wait}'s implementation might look like this: 3707 3708@smallexample 3709pid_t wait (wait_status_ptr_t p) 3710@{ 3711 return waitpid (-1, p.__ip, 0); 3712@} 3713@end smallexample 3714 3715@item unused 3716When attached to a type (including a @code{union} or a @code{struct}), 3717this attribute means that variables of that type are meant to appear 3718possibly unused. GCC will not produce a warning for any variables of 3719that type, even if the variable appears to do nothing. This is often 3720the case with lock or thread classes, which are usually defined and then 3721not referenced, but contain constructors and destructors that have 3722nontrivial bookkeeping functions. 3723 3724@item deprecated 3725The @code{deprecated} attribute results in a warning if the type 3726is used anywhere in the source file. This is useful when identifying 3727types that are expected to be removed in a future version of a program. 3728If possible, the warning also includes the location of the declaration 3729of the deprecated type, to enable users to easily find further 3730information about why the type is deprecated, or what they should do 3731instead. Note that the warnings only occur for uses and then only 3732if the type is being applied to an identifier that itself is not being 3733declared as deprecated. 3734 3735@smallexample 3736typedef int T1 __attribute__ ((deprecated)); 3737T1 x; 3738typedef T1 T2; 3739T2 y; 3740typedef T1 T3 __attribute__ ((deprecated)); 3741T3 z __attribute__ ((deprecated)); 3742@end smallexample 3743 3744results in a warning on line 2 and 3 but not lines 4, 5, or 6. No 3745warning is issued for line 4 because T2 is not explicitly 3746deprecated. Line 5 has no warning because T3 is explicitly 3747deprecated. Similarly for line 6. 3748 3749The @code{deprecated} attribute can also be used for functions and 3750variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) 3751 3752@item may_alias 3753Accesses to objects with types with this attribute are not subjected to 3754type-based alias analysis, but are instead assumed to be able to alias 3755any other type of objects, just like the @code{char} type. See 3756@option{-fstrict-aliasing} for more information on aliasing issues. 3757 3758Example of use: 3759 3760@smallexample 3761typedef short __attribute__((__may_alias__)) short_a; 3762 3763int 3764main (void) 3765@{ 3766 int a = 0x12345678; 3767 short_a *b = (short_a *) &a; 3768 3769 b[1] = 0; 3770 3771 if (a == 0x12345678) 3772 abort(); 3773 3774 exit(0); 3775@} 3776@end smallexample 3777 3778If you replaced @code{short_a} with @code{short} in the variable 3779declaration, the above program would abort when compiled with 3780@option{-fstrict-aliasing}, which is on by default at @option{-O2} or 3781above in recent GCC versions. 3782 3783@item visibility 3784In C++, attribute visibility (@pxref{Function Attributes}) can also be 3785applied to class, struct, union and enum types. Unlike other type 3786attributes, the attribute must appear between the initial keyword and 3787the name of the type; it cannot appear after the body of the type. 3788 3789Note that the type visibility is applied to vague linkage entities 3790associated with the class (vtable, typeinfo node, etc.). In 3791particular, if a class is thrown as an exception in one shared object 3792and caught in another, the class must have default visibility. 3793Otherwise the two shared objects will be unable to use the same 3794typeinfo node and exception handling will break. 3795 3796@c APPLE LOCAL begin weak types 5954418 3797@item weak 3798In C++, attribute weak can be applied to a class to ensure that all 3799non-hidden instances of the type are treated as the same type across 3800shared library boundaries on platforms (such as darwin and arm aapcs) 3801that can emit vtables and the type info meta data as non-comdat 3802symbols. This is useful when the class has a key method and the 3803translation unit that contains the key method is used in more than one 3804shared library or in a shared library and the application. Doing this 3805results in more expensive startup times. This attribute is inherited 3806by subclasses, so it is only necessary to mark a base type. The 3807typical use would be to mark any types used for throwing across shared 3808library boundaries or those used in dynamic_cast operations across a 3809shared library boundary. 3810@c APPLE LOCAL end weak types 5954418 3811 3812@subsection ARM Type Attributes 3813 3814On those ARM targets that support @code{dllimport} (such as Symbian 3815OS), you can use the @code{notshared} attribute to indicate that the 3816virtual table and other similar data for a class should not be 3817exported from a DLL@. For example: 3818 3819@smallexample 3820class __declspec(notshared) C @{ 3821public: 3822 __declspec(dllimport) C(); 3823 virtual void f(); 3824@} 3825 3826__declspec(dllexport) 3827C::C() @{@} 3828@end smallexample 3829 3830In this code, @code{C::C} is exported from the current DLL, but the 3831virtual table for @code{C} is not exported. (You can use 3832@code{__attribute__} instead of @code{__declspec} if you prefer, but 3833most Symbian OS code uses @code{__declspec}.) 3834 3835@anchor{i386 Type Attributes} 3836@subsection i386 Type Attributes 3837 3838Two attributes are currently defined for i386 configurations: 3839@code{ms_struct} and @code{gcc_struct} 3840 3841@item ms_struct 3842@itemx gcc_struct 3843@cindex @code{ms_struct} 3844@cindex @code{gcc_struct} 3845 3846If @code{packed} is used on a structure, or if bit-fields are used 3847it may be that the Microsoft ABI packs them differently 3848than GCC would normally pack them. Particularly when moving packed 3849data between functions compiled with GCC and the native Microsoft compiler 3850(either via function call or as data in a file), it may be necessary to access 3851either format. 3852 3853Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 3854compilers to match the native Microsoft compiler. 3855@end table 3856 3857To specify multiple attributes, separate them by commas within the 3858double parentheses: for example, @samp{__attribute__ ((aligned (16), 3859packed))}. 3860 3861@anchor{PowerPC Type Attributes} 3862@subsection PowerPC Type Attributes 3863 3864Three attributes currently are defined for PowerPC configurations: 3865@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 3866 3867For full documentation of the struct attributes please see the 3868documentation in the @xref{i386 Type Attributes}, section. 3869 3870The @code{altivec} attribute allows one to declare AltiVec vector data 3871types supported by the AltiVec Programming Interface Manual. The 3872attribute requires an argument to specify one of three vector types: 3873@code{vector__}, @code{pixel__} (always followed by unsigned short), 3874and @code{bool__} (always followed by unsigned). 3875 3876@smallexample 3877__attribute__((altivec(vector__))) 3878__attribute__((altivec(pixel__))) unsigned short 3879__attribute__((altivec(bool__))) unsigned 3880@end smallexample 3881 3882These attributes mainly are intended to support the @code{__vector}, 3883@code{__pixel}, and @code{__bool} AltiVec keywords. 3884 3885@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 3886@node Label Attributes 3887@section Specifying Attributes of Labels and Statements 3888@cindex attribute of labels 3889@cindex label attributes 3890@cindex attribute of statements 3891@cindex statement attributes 3892 3893The keyword @code{__attribute__} allows you to specify special 3894attributes of labels and statements. 3895 3896Some attributes are currently defined generically for variables. 3897Other attributes are defined for variables on particular target 3898systems. Other attributes are available for functions 3899(@pxref{Function Attributes}), types (@pxref{Type Attributes}) and 3900variables (@pxref{Variable Attributes}). 3901 3902You may also specify attributes with @samp{__} preceding and following 3903each keyword. This allows you to use them in header files without 3904being concerned about a possible macro of the same name. For example, 3905you may use @code{__aligned__} instead of @code{aligned}. 3906 3907@xref{Attribute Syntax}, for details of the exact syntax for using 3908attributes. 3909 3910@table @code 3911@cindex @code{aligned} attribute 3912@item aligned (@var{alignment}) 3913This attribute specifies a minimum alignment for the label, 3914measured in bytes. For example, the declaration: 3915 3916@smallexample 3917 some_label: __attribute__((aligned(16))) 3918@end smallexample 3919 3920@noindent 3921requests the compiler to align the label, inserting @code{nop}s as necessary, 3922to a 16-byte boundary. 3923 3924The alignment is only a request. The compiler will usually be able to 3925honour it but sometimes the label will be eliminated by the compiler, 3926in which case its alignment will be eliminated too. 3927 3928When applied to loops, the @code{aligned} attribute causes the loop to 3929be aligned. 3930 3931@item unused 3932When attached to a label this attribute means that the label might not 3933be used. GCC will not produce a warning for the label, even if the 3934label doesn't seem to be referenced. This feature is intended for 3935code generated by programs which contains labels that may be unused 3936but which is compiled with @option{-Wall}. It would not normally be 3937appropriate to use in it human-written code, though it could be useful 3938in cases where the code that jumps to the label is contained within an 3939@code{#ifdef} conditional. 3940 3941This attribute can only be applied to labels, not statements, because 3942there is no warning if a statement is removed. 3943@end table 3944 3945@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 3946@node Inline 3947@section An Inline Function is As Fast As a Macro 3948@cindex inline functions 3949@cindex integrating function code 3950@cindex open coding 3951@cindex macros, inline alternative 3952 3953By declaring a function inline, you can direct GCC to make 3954calls to that function faster. One way GCC can achieve this is to 3955integrate that function's code into the code for its callers. This 3956makes execution faster by eliminating the function-call overhead; in 3957addition, if any of the actual argument values are constant, their 3958known values may permit simplifications at compile time so that not 3959all of the inline function's code needs to be included. The effect on 3960code size is less predictable; object code may be larger or smaller 3961with function inlining, depending on the particular case. You can 3962also direct GCC to try to integrate all ``simple enough'' functions 3963into their callers with the option @option{-finline-functions}. 3964 3965GCC implements three different semantics of declaring a function 3966inline. One is available with @option{-std=gnu89}, another when 3967@option{-std=c99} or @option{-std=gnu99}, and the third is used when 3968compiling C++. 3969 3970To declare a function inline, use the @code{inline} keyword in its 3971declaration, like this: 3972 3973@smallexample 3974static inline int 3975inc (int *a) 3976@{ 3977 (*a)++; 3978@} 3979@end smallexample 3980 3981If you are writing a header file to be included in ISO C89 programs, write 3982@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. 3983 3984The three types of inlining behave similarly in two important cases: 3985when the @code{inline} keyword is used on a @code{static} function, 3986like the example above, and when a function is first declared without 3987using the @code{inline} keyword and then is defined with 3988@code{inline}, like this: 3989 3990@smallexample 3991extern int inc (int *a); 3992inline int 3993inc (int *a) 3994@{ 3995 (*a)++; 3996@} 3997@end smallexample 3998 3999In both of these common cases, the program behaves the same as if you 4000had not used the @code{inline} keyword, except for its speed. 4001 4002@cindex inline functions, omission of 4003@opindex fkeep-inline-functions 4004When a function is both inline and @code{static}, if all calls to the 4005function are integrated into the caller, and the function's address is 4006never used, then the function's own assembler code is never referenced. 4007In this case, GCC does not actually output assembler code for the 4008function, unless you specify the option @option{-fkeep-inline-functions}. 4009Some calls cannot be integrated for various reasons (in particular, 4010calls that precede the function's definition cannot be integrated, and 4011neither can recursive calls within the definition). If there is a 4012nonintegrated call, then the function is compiled to assembler code as 4013usual. The function must also be compiled as usual if the program 4014refers to its address, because that can't be inlined. 4015 4016@cindex automatic @code{inline} for C++ member fns 4017@cindex @code{inline} automatic for C++ member fns 4018@cindex member fns, automatically @code{inline} 4019@cindex C++ member fns, automatically @code{inline} 4020@opindex fno-default-inline 4021As required by ISO C++, GCC considers member functions defined within 4022the body of a class to be marked inline even if they are 4023not explicitly declared with the @code{inline} keyword. You can 4024override this with @option{-fno-default-inline}; @pxref{C++ Dialect 4025Options,,Options Controlling C++ Dialect}. 4026 4027GCC does not inline any functions when not optimizing unless you specify 4028the @samp{always_inline} attribute for the function, like this: 4029 4030@smallexample 4031/* @r{Prototype.} */ 4032inline void foo (const char) __attribute__((always_inline)); 4033@end smallexample 4034 4035The remainder of this section is specific to GNU C89 inlining. 4036 4037@cindex non-static inline function 4038When an inline function is not @code{static}, then the compiler must assume 4039that there may be calls from other source files; since a global symbol can 4040be defined only once in any program, the function must not be defined in 4041the other source files, so the calls therein cannot be integrated. 4042Therefore, a non-@code{static} inline function is always compiled on its 4043own in the usual fashion. 4044 4045If you specify both @code{inline} and @code{extern} in the function 4046definition, then the definition is used only for inlining. In no case 4047is the function compiled on its own, not even if you refer to its 4048address explicitly. Such an address becomes an external reference, as 4049if you had only declared the function, and had not defined it. 4050 4051This combination of @code{inline} and @code{extern} has almost the 4052effect of a macro. The way to use it is to put a function definition in 4053a header file with these keywords, and put another copy of the 4054definition (lacking @code{inline} and @code{extern}) in a library file. 4055The definition in the header file will cause most calls to the function 4056to be inlined. If any uses of the function remain, they will refer to 4057the single copy in the library. 4058 4059@node Extended Asm 4060@section Assembler Instructions with C Expression Operands 4061@cindex extended @code{asm} 4062@cindex @code{asm} expressions 4063@cindex assembler instructions 4064@cindex registers 4065 4066In an assembler instruction using @code{asm}, you can specify the 4067operands of the instruction using C expressions. This means you need not 4068guess which registers or memory locations will contain the data you want 4069to use. 4070 4071You must specify an assembler instruction template much like what 4072appears in a machine description, plus an operand constraint string for 4073each operand. 4074 4075For example, here is how to use the 68881's @code{fsinx} instruction: 4076 4077@smallexample 4078asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); 4079@end smallexample 4080 4081@noindent 4082Here @code{angle} is the C expression for the input operand while 4083@code{result} is that of the output operand. Each has @samp{"f"} as its 4084operand constraint, saying that a floating point register is required. 4085The @samp{=} in @samp{=f} indicates that the operand is an output; all 4086output operands' constraints must use @samp{=}. The constraints use the 4087same language used in the machine description (@pxref{Constraints}). 4088 4089Each operand is described by an operand-constraint string followed by 4090the C expression in parentheses. A colon separates the assembler 4091template from the first output operand and another separates the last 4092output operand from the first input, if any. Commas separate the 4093operands within each group. The total number of operands is currently 4094limited to 30; this limitation may be lifted in some future version of 4095GCC@. 4096 4097If there are no output operands but there are input operands, you must 4098place two consecutive colons surrounding the place where the output 4099operands would go. 4100 4101As of GCC version 3.1, it is also possible to specify input and output 4102operands using symbolic names which can be referenced within the 4103assembler code. These names are specified inside square brackets 4104preceding the constraint string, and can be referenced inside the 4105assembler code using @code{%[@var{name}]} instead of a percentage sign 4106followed by the operand number. Using named operands the above example 4107could look like: 4108 4109@smallexample 4110asm ("fsinx %[angle],%[output]" 4111 : [output] "=f" (result) 4112 : [angle] "f" (angle)); 4113@end smallexample 4114 4115@noindent 4116Note that the symbolic operand names have no relation whatsoever to 4117other C identifiers. You may use any name you like, even those of 4118existing C symbols, but you must ensure that no two operands within the same 4119assembler construct use the same symbolic name. 4120 4121Output operand expressions must be lvalues; the compiler can check this. 4122The input operands need not be lvalues. The compiler cannot check 4123whether the operands have data types that are reasonable for the 4124instruction being executed. It does not parse the assembler instruction 4125template and does not know what it means or even whether it is valid 4126assembler input. The extended @code{asm} feature is most often used for 4127machine instructions the compiler itself does not know exist. If 4128the output expression cannot be directly addressed (for example, it is a 4129bit-field), your constraint must allow a register. In that case, GCC 4130will use the register as the output of the @code{asm}, and then store 4131that register into the output. 4132 4133The ordinary output operands must be write-only; GCC will assume that 4134the values in these operands before the instruction are dead and need 4135not be generated. Extended asm supports input-output or read-write 4136operands. Use the constraint character @samp{+} to indicate such an 4137operand and list it with the output operands. You should only use 4138read-write operands when the constraints for the operand (or the 4139operand in which only some of the bits are to be changed) allow a 4140register. 4141 4142You may, as an alternative, logically split its function into two 4143separate operands, one input operand and one write-only output 4144operand. The connection between them is expressed by constraints 4145which say they need to be in the same location when the instruction 4146executes. You can use the same C expression for both operands, or 4147different expressions. For example, here we write the (fictitious) 4148@samp{combine} instruction with @code{bar} as its read-only source 4149operand and @code{foo} as its read-write destination: 4150 4151@smallexample 4152asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); 4153@end smallexample 4154 4155@noindent 4156The constraint @samp{"0"} for operand 1 says that it must occupy the 4157same location as operand 0. A number in constraint is allowed only in 4158an input operand and it must refer to an output operand. 4159 4160Only a number in the constraint can guarantee that one operand will be in 4161the same place as another. The mere fact that @code{foo} is the value 4162of both operands is not enough to guarantee that they will be in the 4163same place in the generated assembler code. The following would not 4164work reliably: 4165 4166@smallexample 4167asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); 4168@end smallexample 4169 4170Various optimizations or reloading could cause operands 0 and 1 to be in 4171different registers; GCC knows no reason not to do so. For example, the 4172compiler might find a copy of the value of @code{foo} in one register and 4173use it for operand 1, but generate the output operand 0 in a different 4174register (copying it afterward to @code{foo}'s own address). Of course, 4175since the register for operand 1 is not even mentioned in the assembler 4176code, the result will not work, but GCC can't tell that. 4177 4178As of GCC version 3.1, one may write @code{[@var{name}]} instead of 4179the operand number for a matching constraint. For example: 4180 4181@smallexample 4182asm ("cmoveq %1,%2,%[result]" 4183 : [result] "=r"(result) 4184 : "r" (test), "r"(new), "[result]"(old)); 4185@end smallexample 4186 4187Sometimes you need to make an @code{asm} operand be a specific register, 4188but there's no matching constraint letter for that register @emph{by 4189itself}. To force the operand into that register, use a local variable 4190for the operand and specify the register in the variable declaration. 4191@xref{Explicit Reg Vars}. Then for the @code{asm} operand, use any 4192register constraint letter that matches the register: 4193 4194@smallexample 4195register int *p1 asm ("r0") = @dots{}; 4196register int *p2 asm ("r1") = @dots{}; 4197register int *result asm ("r0"); 4198asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 4199@end smallexample 4200 4201@anchor{Example of asm with clobbered asm reg} 4202In the above example, beware that a register that is call-clobbered by 4203the target ABI will be overwritten by any function call in the 4204assignment, including library calls for arithmetic operators. 4205Assuming it is a call-clobbered register, this may happen to @code{r0} 4206above by the assignment to @code{p2}. If you have to use such a 4207register, use temporary variables for expressions between the register 4208assignment and use: 4209 4210@smallexample 4211int t1 = @dots{}; 4212register int *p1 asm ("r0") = @dots{}; 4213register int *p2 asm ("r1") = t1; 4214register int *result asm ("r0"); 4215asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 4216@end smallexample 4217 4218Some instructions clobber specific hard registers. To describe this, 4219write a third colon after the input operands, followed by the names of 4220the clobbered hard registers (given as strings). Here is a realistic 4221example for the VAX: 4222 4223@smallexample 4224asm volatile ("movc3 %0,%1,%2" 4225 : /* @r{no outputs} */ 4226 : "g" (from), "g" (to), "g" (count) 4227 : "r0", "r1", "r2", "r3", "r4", "r5"); 4228@end smallexample 4229 4230You may not write a clobber description in a way that overlaps with an 4231input or output operand. For example, you may not have an operand 4232describing a register class with one member if you mention that register 4233in the clobber list. Variables declared to live in specific registers 4234(@pxref{Explicit Reg Vars}), and used as asm input or output operands must 4235have no part mentioned in the clobber description. 4236There is no way for you to specify that an input 4237operand is modified without also specifying it as an output 4238operand. Note that if all the output operands you specify are for this 4239purpose (and hence unused), you will then also need to specify 4240@code{volatile} for the @code{asm} construct, as described below, to 4241prevent GCC from deleting the @code{asm} statement as unused. 4242 4243If you refer to a particular hardware register from the assembler code, 4244you will probably have to list the register after the third colon to 4245tell the compiler the register's value is modified. In some assemblers, 4246the register names begin with @samp{%}; to produce one @samp{%} in the 4247assembler code, you must write @samp{%%} in the input. 4248 4249If your assembler instruction can alter the condition code register, add 4250@samp{cc} to the list of clobbered registers. GCC on some machines 4251represents the condition codes as a specific hardware register; 4252@samp{cc} serves to name this register. On other machines, the 4253condition code is handled differently, and specifying @samp{cc} has no 4254effect. But it is valid no matter what the machine. 4255 4256If your assembler instructions access memory in an unpredictable 4257fashion, add @samp{memory} to the list of clobbered registers. This 4258will cause GCC to not keep memory values cached in registers across the 4259assembler instruction and not optimize stores or loads to that memory. 4260You will also want to add the @code{volatile} keyword if the memory 4261affected is not listed in the inputs or outputs of the @code{asm}, as 4262the @samp{memory} clobber does not count as a side-effect of the 4263@code{asm}. If you know how large the accessed memory is, you can add 4264it as input or output but if this is not known, you should add 4265@samp{memory}. As an example, if you access ten bytes of a string, you 4266can use a memory input like: 4267 4268@smallexample 4269@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}. 4270@end smallexample 4271 4272Note that in the following example the memory input is necessary, 4273otherwise GCC might optimize the store to @code{x} away: 4274@smallexample 4275int foo () 4276@{ 4277 int x = 42; 4278 int *y = &x; 4279 int result; 4280 asm ("magic stuff accessing an 'int' pointed to by '%1'" 4281 "=&d" (r) : "a" (y), "m" (*y)); 4282 return result; 4283@} 4284@end smallexample 4285 4286You can put multiple assembler instructions together in a single 4287@code{asm} template, separated by the characters normally used in assembly 4288code for the system. A combination that works in most places is a newline 4289to break the line, plus a tab character to move to the instruction field 4290(written as @samp{\n\t}). Sometimes semicolons can be used, if the 4291assembler allows semicolons as a line-breaking character. Note that some 4292assembler dialects use semicolons to start a comment. 4293The input operands are guaranteed not to use any of the clobbered 4294registers, and neither will the output operands' addresses, so you can 4295read and write the clobbered registers as many times as you like. Here 4296is an example of multiple instructions in a template; it assumes the 4297subroutine @code{_foo} accepts arguments in registers 9 and 10: 4298 4299@smallexample 4300asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo" 4301 : /* no outputs */ 4302 : "g" (from), "g" (to) 4303 : "r9", "r10"); 4304@end smallexample 4305 4306Unless an output operand has the @samp{&} constraint modifier, GCC 4307may allocate it in the same register as an unrelated input operand, on 4308the assumption the inputs are consumed before the outputs are produced. 4309This assumption may be false if the assembler code actually consists of 4310more than one instruction. In such a case, use @samp{&} for each output 4311operand that may not overlap an input. @xref{Modifiers}. 4312 4313If you want to test the condition code produced by an assembler 4314instruction, you must include a branch and a label in the @code{asm} 4315construct, as follows: 4316 4317@smallexample 4318asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:" 4319 : "g" (result) 4320 : "g" (input)); 4321@end smallexample 4322 4323@noindent 4324This assumes your assembler supports local labels, as the GNU assembler 4325and most Unix assemblers do. 4326 4327Speaking of labels, jumps from one @code{asm} to another are not 4328supported. The compiler's optimizers do not know about these jumps, and 4329therefore they cannot take account of them when deciding how to 4330optimize. 4331 4332@cindex macros containing @code{asm} 4333Usually the most convenient way to use these @code{asm} instructions is to 4334encapsulate them in macros that look like functions. For example, 4335 4336@smallexample 4337#define sin(x) \ 4338(@{ double __value, __arg = (x); \ 4339 asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ 4340 __value; @}) 4341@end smallexample 4342 4343@noindent 4344Here the variable @code{__arg} is used to make sure that the instruction 4345operates on a proper @code{double} value, and to accept only those 4346arguments @code{x} which can convert automatically to a @code{double}. 4347 4348Another way to make sure the instruction operates on the correct data 4349type is to use a cast in the @code{asm}. This is different from using a 4350variable @code{__arg} in that it converts more different types. For 4351example, if the desired type were @code{int}, casting the argument to 4352@code{int} would accept a pointer with no complaint, while assigning the 4353argument to an @code{int} variable named @code{__arg} would warn about 4354using a pointer unless the caller explicitly casts it. 4355 4356If an @code{asm} has output operands, GCC assumes for optimization 4357purposes the instruction has no side effects except to change the output 4358operands. This does not mean instructions with a side effect cannot be 4359used, but you must be careful, because the compiler may eliminate them 4360if the output operands aren't used, or move them out of loops, or 4361replace two with one if they constitute a common subexpression. Also, 4362if your instruction does have a side effect on a variable that otherwise 4363appears not to change, the old value of the variable may be reused later 4364if it happens to be found in a register. 4365 4366You can prevent an @code{asm} instruction from being deleted 4367by writing the keyword @code{volatile} after 4368the @code{asm}. For example: 4369 4370@smallexample 4371#define get_and_set_priority(new) \ 4372(@{ int __old; \ 4373 asm volatile ("get_and_set_priority %0, %1" \ 4374 : "=g" (__old) : "g" (new)); \ 4375 __old; @}) 4376@end smallexample 4377 4378@noindent 4379The @code{volatile} keyword indicates that the instruction has 4380important side-effects. GCC will not delete a volatile @code{asm} if 4381it is reachable. (The instruction can still be deleted if GCC can 4382prove that control-flow will never reach the location of the 4383instruction.) Note that even a volatile @code{asm} instruction 4384can be moved relative to other code, including across jump 4385instructions. For example, on many targets there is a system 4386register which can be set to control the rounding mode of 4387floating point operations. You might try 4388setting it with a volatile @code{asm}, like this PowerPC example: 4389 4390@smallexample 4391 asm volatile("mtfsf 255,%0" : : "f" (fpenv)); 4392 sum = x + y; 4393@end smallexample 4394 4395@noindent 4396This will not work reliably, as the compiler may move the addition back 4397before the volatile @code{asm}. To make it work you need to add an 4398artificial dependency to the @code{asm} referencing a variable in the code 4399you don't want moved, for example: 4400 4401@smallexample 4402 asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv)); 4403 sum = x + y; 4404@end smallexample 4405 4406Similarly, you can't expect a 4407sequence of volatile @code{asm} instructions to remain perfectly 4408consecutive. If you want consecutive output, use a single @code{asm}. 4409Also, GCC will perform some optimizations across a volatile @code{asm} 4410instruction; GCC does not ``forget everything'' when it encounters 4411a volatile @code{asm} instruction the way some other compilers do. 4412 4413An @code{asm} instruction without any output operands will be treated 4414identically to a volatile @code{asm} instruction. 4415 4416It is a natural idea to look for a way to give access to the condition 4417code left by the assembler instruction. However, when we attempted to 4418implement this, we found no way to make it work reliably. The problem 4419is that output operands might need reloading, which would result in 4420additional following ``store'' instructions. On most machines, these 4421instructions would alter the condition code before there was time to 4422test it. This problem doesn't arise for ordinary ``test'' and 4423``compare'' instructions because they don't have any output operands. 4424 4425For reasons similar to those described above, it is not possible to give 4426an assembler instruction access to the condition code left by previous 4427instructions. 4428 4429If you are writing a header file that should be includable in ISO C 4430programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate 4431Keywords}. 4432 4433@subsection Size of an @code{asm} 4434 4435Some targets require that GCC track the size of each instruction used in 4436order to generate correct code. Because the final length of an 4437@code{asm} is only known by the assembler, GCC must make an estimate as 4438to how big it will be. The estimate is formed by counting the number of 4439statements in the pattern of the @code{asm} and multiplying that by the 4440length of the longest instruction on that processor. Statements in the 4441@code{asm} are identified by newline characters and whatever statement 4442separator characters are supported by the assembler; on most processors 4443this is the `@code{;}' character. 4444 4445Normally, GCC's estimate is perfectly adequate to ensure that correct 4446code is generated, but it is possible to confuse the compiler if you use 4447pseudo instructions or assembler macros that expand into multiple real 4448instructions or if you use assembler directives that expand to more 4449space in the object file than would be needed for a single instruction. 4450If this happens then the assembler will produce a diagnostic saying that 4451a label is unreachable. 4452 4453@subsection i386 floating point asm operands 4454 4455There are several rules on the usage of stack-like regs in 4456asm_operands insns. These rules apply only to the operands that are 4457stack-like regs: 4458 4459@enumerate 4460@item 4461Given a set of input regs that die in an asm_operands, it is 4462necessary to know which are implicitly popped by the asm, and 4463which must be explicitly popped by gcc. 4464 4465An input reg that is implicitly popped by the asm must be 4466explicitly clobbered, unless it is constrained to match an 4467output operand. 4468 4469@item 4470For any input reg that is implicitly popped by an asm, it is 4471necessary to know how to adjust the stack to compensate for the pop. 4472If any non-popped input is closer to the top of the reg-stack than 4473the implicitly popped reg, it would not be possible to know what the 4474stack looked like---it's not clear how the rest of the stack ``slides 4475up''. 4476 4477All implicitly popped input regs must be closer to the top of 4478the reg-stack than any input that is not implicitly popped. 4479 4480It is possible that if an input dies in an insn, reload might 4481use the input reg for an output reload. Consider this example: 4482 4483@smallexample 4484asm ("foo" : "=t" (a) : "f" (b)); 4485@end smallexample 4486 4487This asm says that input B is not popped by the asm, and that 4488the asm pushes a result onto the reg-stack, i.e., the stack is one 4489deeper after the asm than it was before. But, it is possible that 4490reload will think that it can use the same reg for both the input and 4491the output, if input B dies in this insn. 4492 4493If any input operand uses the @code{f} constraint, all output reg 4494constraints must use the @code{&} earlyclobber. 4495 4496The asm above would be written as 4497 4498@smallexample 4499asm ("foo" : "=&t" (a) : "f" (b)); 4500@end smallexample 4501 4502@item 4503Some operands need to be in particular places on the stack. All 4504output operands fall in this category---there is no other way to 4505know which regs the outputs appear in unless the user indicates 4506this in the constraints. 4507 4508Output operands must specifically indicate which reg an output 4509appears in after an asm. @code{=f} is not allowed: the operand 4510constraints must select a class with a single reg. 4511 4512@item 4513Output operands may not be ``inserted'' between existing stack regs. 4514Since no 387 opcode uses a read/write operand, all output operands 4515are dead before the asm_operands, and are pushed by the asm_operands. 4516It makes no sense to push anywhere but the top of the reg-stack. 4517 4518Output operands must start at the top of the reg-stack: output 4519operands may not ``skip'' a reg. 4520 4521@item 4522Some asm statements may need extra stack space for internal 4523calculations. This can be guaranteed by clobbering stack registers 4524unrelated to the inputs and outputs. 4525 4526@end enumerate 4527 4528Here are a couple of reasonable asms to want to write. This asm 4529takes one input, which is internally popped, and produces two outputs. 4530 4531@smallexample 4532asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); 4533@end smallexample 4534 4535This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode, 4536and replaces them with one output. The user must code the @code{st(1)} 4537clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs. 4538 4539@smallexample 4540asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); 4541@end smallexample 4542 4543@include md.texi 4544 4545@node Asm Labels 4546@section Controlling Names Used in Assembler Code 4547@cindex assembler names for identifiers 4548@cindex names used in assembler code 4549@cindex identifiers, names in assembler code 4550 4551You can specify the name to be used in the assembler code for a C 4552function or variable by writing the @code{asm} (or @code{__asm__}) 4553keyword after the declarator as follows: 4554 4555@smallexample 4556int foo asm ("myfoo") = 2; 4557@end smallexample 4558 4559@noindent 4560This specifies that the name to be used for the variable @code{foo} in 4561the assembler code should be @samp{myfoo} rather than the usual 4562@samp{_foo}. 4563 4564On systems where an underscore is normally prepended to the name of a C 4565function or variable, this feature allows you to define names for the 4566linker that do not start with an underscore. 4567 4568It does not make sense to use this feature with a non-static local 4569variable since such variables do not have assembler names. If you are 4570trying to put the variable in a particular register, see @ref{Explicit 4571Reg Vars}. GCC presently accepts such code with a warning, but will 4572probably be changed to issue an error, rather than a warning, in the 4573future. 4574 4575You cannot use @code{asm} in this way in a function @emph{definition}; but 4576you can get the same effect by writing a declaration for the function 4577before its definition and putting @code{asm} there, like this: 4578 4579@smallexample 4580extern func () asm ("FUNC"); 4581 4582func (x, y) 4583 int x, y; 4584/* @r{@dots{}} */ 4585@end smallexample 4586 4587It is up to you to make sure that the assembler names you choose do not 4588conflict with any other assembler symbols. Also, you must not use a 4589register name; that would produce completely invalid assembler code. GCC 4590does not as yet have the ability to store static variables in registers. 4591Perhaps that will be added. 4592 4593@node Explicit Reg Vars 4594@section Variables in Specified Registers 4595@cindex explicit register variables 4596@cindex variables in specified registers 4597@cindex specified registers 4598@cindex registers, global allocation 4599 4600GNU C allows you to put a few global variables into specified hardware 4601registers. You can also specify the register in which an ordinary 4602register variable should be allocated. 4603 4604@itemize @bullet 4605@item 4606Global register variables reserve registers throughout the program. 4607This may be useful in programs such as programming language 4608interpreters which have a couple of global variables that are accessed 4609very often. 4610 4611@item 4612Local register variables in specific registers do not reserve the 4613registers, except at the point where they are used as input or output 4614operands in an @code{asm} statement and the @code{asm} statement itself is 4615not deleted. The compiler's data flow analysis is capable of determining 4616where the specified registers contain live values, and where they are 4617available for other uses. Stores into local register variables may be deleted 4618when they appear to be dead according to dataflow analysis. References 4619to local register variables may be deleted or moved or simplified. 4620 4621These local variables are sometimes convenient for use with the extended 4622@code{asm} feature (@pxref{Extended Asm}), if you want to write one 4623output of the assembler instruction directly into a particular register. 4624(This will work provided the register you specify fits the constraints 4625specified for that operand in the @code{asm}.) 4626@end itemize 4627 4628@menu 4629* Global Reg Vars:: 4630* Local Reg Vars:: 4631@end menu 4632 4633@node Global Reg Vars 4634@subsection Defining Global Register Variables 4635@cindex global register variables 4636@cindex registers, global variables in 4637 4638You can define a global register variable in GNU C like this: 4639 4640@smallexample 4641register int *foo asm ("a5"); 4642@end smallexample 4643 4644@noindent 4645Here @code{a5} is the name of the register which should be used. Choose a 4646register which is normally saved and restored by function calls on your 4647machine, so that library routines will not clobber it. 4648 4649Naturally the register name is cpu-dependent, so you would need to 4650conditionalize your program according to cpu type. The register 4651@code{a5} would be a good choice on a 68000 for a variable of pointer 4652type. On machines with register windows, be sure to choose a ``global'' 4653register that is not affected magically by the function call mechanism. 4654 4655In addition, operating systems on one type of cpu may differ in how they 4656name the registers; then you would need additional conditionals. For 4657example, some 68000 operating systems call this register @code{%a5}. 4658 4659Eventually there may be a way of asking the compiler to choose a register 4660automatically, but first we need to figure out how it should choose and 4661how to enable you to guide the choice. No solution is evident. 4662 4663Defining a global register variable in a certain register reserves that 4664register entirely for this use, at least within the current compilation. 4665The register will not be allocated for any other purpose in the functions 4666in the current compilation. The register will not be saved and restored by 4667these functions. Stores into this register are never deleted even if they 4668would appear to be dead, but references may be deleted or moved or 4669simplified. 4670 4671It is not safe to access the global register variables from signal 4672handlers, or from more than one thread of control, because the system 4673library routines may temporarily use the register for other things (unless 4674you recompile them specially for the task at hand). 4675 4676@cindex @code{qsort}, and global register variables 4677It is not safe for one function that uses a global register variable to 4678call another such function @code{foo} by way of a third function 4679@code{lose} that was compiled without knowledge of this variable (i.e.@: in a 4680different source file in which the variable wasn't declared). This is 4681because @code{lose} might save the register and put some other value there. 4682For example, you can't expect a global register variable to be available in 4683the comparison-function that you pass to @code{qsort}, since @code{qsort} 4684might have put something else in that register. (If you are prepared to 4685recompile @code{qsort} with the same global register variable, you can 4686solve this problem.) 4687 4688If you want to recompile @code{qsort} or other source files which do not 4689actually use your global register variable, so that they will not use that 4690register for any other purpose, then it suffices to specify the compiler 4691option @option{-ffixed-@var{reg}}. You need not actually add a global 4692register declaration to their source code. 4693 4694A function which can alter the value of a global register variable cannot 4695safely be called from a function compiled without this variable, because it 4696could clobber the value the caller expects to find there on return. 4697Therefore, the function which is the entry point into the part of the 4698program that uses the global register variable must explicitly save and 4699restore the value which belongs to its caller. 4700 4701@cindex register variable after @code{longjmp} 4702@cindex global register after @code{longjmp} 4703@cindex value after @code{longjmp} 4704@findex longjmp 4705@findex setjmp 4706On most machines, @code{longjmp} will restore to each global register 4707variable the value it had at the time of the @code{setjmp}. On some 4708machines, however, @code{longjmp} will not change the value of global 4709register variables. To be portable, the function that called @code{setjmp} 4710should make other arrangements to save the values of the global register 4711variables, and to restore them in a @code{longjmp}. This way, the same 4712thing will happen regardless of what @code{longjmp} does. 4713 4714All global register variable declarations must precede all function 4715definitions. If such a declaration could appear after function 4716definitions, the declaration would be too late to prevent the register from 4717being used for other purposes in the preceding functions. 4718 4719Global register variables may not have initial values, because an 4720executable file has no means to supply initial contents for a register. 4721 4722On the SPARC, there are reports that g3 @dots{} g7 are suitable 4723registers, but certain library functions, such as @code{getwd}, as well 4724as the subroutines for division and remainder, modify g3 and g4. g1 and 4725g2 are local temporaries. 4726 4727On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7. 4728Of course, it will not do to use more than a few of those. 4729 4730@node Local Reg Vars 4731@subsection Specifying Registers for Local Variables 4732@cindex local variables, specifying registers 4733@cindex specifying registers for local variables 4734@cindex registers for local variables 4735 4736You can define a local register variable with a specified register 4737like this: 4738 4739@smallexample 4740register int *foo asm ("a5"); 4741@end smallexample 4742 4743@noindent 4744Here @code{a5} is the name of the register which should be used. Note 4745that this is the same syntax used for defining global register 4746variables, but for a local variable it would appear within a function. 4747 4748Naturally the register name is cpu-dependent, but this is not a 4749problem, since specific registers are most often useful with explicit 4750assembler instructions (@pxref{Extended Asm}). Both of these things 4751generally require that you conditionalize your program according to 4752cpu type. 4753 4754In addition, operating systems on one type of cpu may differ in how they 4755name the registers; then you would need additional conditionals. For 4756example, some 68000 operating systems call this register @code{%a5}. 4757 4758Defining such a register variable does not reserve the register; it 4759remains available for other uses in places where flow control determines 4760the variable's value is not live. 4761 4762This option does not guarantee that GCC will generate code that has 4763this variable in the register you specify at all times. You may not 4764code an explicit reference to this register in the @emph{assembler 4765instruction template} part of an @code{asm} statement and assume it will 4766always refer to this variable. However, using the variable as an 4767@code{asm} @emph{operand} guarantees that the specified register is used 4768for the operand. 4769 4770Stores into local register variables may be deleted when they appear to be dead 4771according to dataflow analysis. References to local register variables may 4772be deleted or moved or simplified. 4773 4774As for global register variables, it's recommended that you choose a 4775register which is normally saved and restored by function calls on 4776your machine, so that library routines will not clobber it. A common 4777pitfall is to initialize multiple call-clobbered registers with 4778arbitrary expressions, where a function call or library call for an 4779arithmetic operator will overwrite a register value from a previous 4780assignment, for example @code{r0} below: 4781@smallexample 4782register int *p1 asm ("r0") = @dots{}; 4783register int *p2 asm ("r1") = @dots{}; 4784@end smallexample 4785In those cases, a solution is to use a temporary variable for 4786each arbitrary expression. @xref{Example of asm with clobbered asm reg}. 4787 4788@node Alternate Keywords 4789@section Alternate Keywords 4790@cindex alternate keywords 4791@cindex keywords, alternate 4792 4793@option{-ansi} and the various @option{-std} options disable certain 4794keywords. This causes trouble when you want to use GNU C extensions, or 4795a general-purpose header file that should be usable by all programs, 4796including ISO C programs. The keywords @code{asm}, @code{typeof} and 4797@code{inline} are not available in programs compiled with 4798@option{-ansi} or @option{-std} (although @code{inline} can be used in a 4799program compiled with @option{-std=c99}). The ISO C99 keyword 4800@code{restrict} is only available when @option{-std=gnu99} (which will 4801eventually be the default) or @option{-std=c99} (or the equivalent 4802@option{-std=iso9899:1999}) is used. 4803 4804The way to solve these problems is to put @samp{__} at the beginning and 4805end of each problematical keyword. For example, use @code{__asm__} 4806instead of @code{asm}, and @code{__inline__} instead of @code{inline}. 4807 4808Other C compilers won't accept these alternative keywords; if you want to 4809compile with another compiler, you can define the alternate keywords as 4810macros to replace them with the customary keywords. It looks like this: 4811 4812@smallexample 4813#ifndef __GNUC__ 4814#define __asm__ asm 4815#endif 4816@end smallexample 4817 4818@findex __extension__ 4819@opindex pedantic 4820@option{-pedantic} and other options cause warnings for many GNU C extensions. 4821You can 4822prevent such warnings within one expression by writing 4823@code{__extension__} before the expression. @code{__extension__} has no 4824effect aside from this. 4825 4826@node Incomplete Enums 4827@section Incomplete @code{enum} Types 4828 4829You can define an @code{enum} tag without specifying its possible values. 4830This results in an incomplete type, much like what you get if you write 4831@code{struct foo} without describing the elements. A later declaration 4832which does specify the possible values completes the type. 4833 4834You can't allocate variables or storage using the type while it is 4835incomplete. However, you can work with pointers to that type. 4836 4837This extension may not be very useful, but it makes the handling of 4838@code{enum} more consistent with the way @code{struct} and @code{union} 4839are handled. 4840 4841This extension is not supported by GNU C++. 4842 4843@node Function Names 4844@section Function Names as Strings 4845@cindex @code{__func__} identifier 4846@cindex @code{__FUNCTION__} identifier 4847@cindex @code{__PRETTY_FUNCTION__} identifier 4848 4849GCC provides three magic variables which hold the name of the current 4850function, as a string. The first of these is @code{__func__}, which 4851is part of the C99 standard: 4852 4853@display 4854The identifier @code{__func__} is implicitly declared by the translator 4855as if, immediately following the opening brace of each function 4856definition, the declaration 4857 4858@smallexample 4859static const char __func__[] = "function-name"; 4860@end smallexample 4861 4862appeared, where function-name is the name of the lexically-enclosing 4863function. This name is the unadorned name of the function. 4864@end display 4865 4866@code{__FUNCTION__} is another name for @code{__func__}. Older 4867versions of GCC recognize only this name. However, it is not 4868standardized. For maximum portability, we recommend you use 4869@code{__func__}, but provide a fallback definition with the 4870preprocessor: 4871 4872@smallexample 4873#if __STDC_VERSION__ < 199901L 4874# if __GNUC__ >= 2 4875# define __func__ __FUNCTION__ 4876# else 4877# define __func__ "<unknown>" 4878# endif 4879#endif 4880@end smallexample 4881 4882In C, @code{__PRETTY_FUNCTION__} is yet another name for 4883@code{__func__}. However, in C++, @code{__PRETTY_FUNCTION__} contains 4884the type signature of the function as well as its bare name. For 4885example, this program: 4886 4887@smallexample 4888extern "C" @{ 4889extern int printf (char *, ...); 4890@} 4891 4892class a @{ 4893 public: 4894 void sub (int i) 4895 @{ 4896 printf ("__FUNCTION__ = %s\n", __FUNCTION__); 4897 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); 4898 @} 4899@}; 4900 4901int 4902main (void) 4903@{ 4904 a ax; 4905 ax.sub (0); 4906 return 0; 4907@} 4908@end smallexample 4909 4910@noindent 4911gives this output: 4912 4913@smallexample 4914__FUNCTION__ = sub 4915__PRETTY_FUNCTION__ = void a::sub(int) 4916@end smallexample 4917 4918These identifiers are not preprocessor macros. In GCC 3.3 and 4919earlier, in C only, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} 4920were treated as string literals; they could be used to initialize 4921@code{char} arrays, and they could be concatenated with other string 4922literals. GCC 3.4 and later treat them as variables, like 4923@code{__func__}. In C++, @code{__FUNCTION__} and 4924@code{__PRETTY_FUNCTION__} have always been variables. 4925 4926@node Return Address 4927@section Getting the Return or Frame Address of a Function 4928 4929These functions may be used to get information about the callers of a 4930function. 4931 4932@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) 4933This function returns the return address of the current function, or of 4934one of its callers. The @var{level} argument is number of frames to 4935scan up the call stack. A value of @code{0} yields the return address 4936of the current function, a value of @code{1} yields the return address 4937of the caller of the current function, and so forth. When inlining 4938the expected behavior is that the function will return the address of 4939the function that will be returned to. To work around this behavior use 4940the @code{noinline} function attribute. 4941 4942The @var{level} argument must be a constant integer. 4943 4944On some machines it may be impossible to determine the return address of 4945any function other than the current one; in such cases, or when the top 4946of the stack has been reached, this function will return @code{0} or a 4947random value. In addition, @code{__builtin_frame_address} may be used 4948to determine if the top of the stack has been reached. 4949 4950This function should only be used with a nonzero argument for debugging 4951purposes. 4952@end deftypefn 4953 4954@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) 4955This function is similar to @code{__builtin_return_address}, but it 4956returns the address of the function frame rather than the return address 4957of the function. Calling @code{__builtin_frame_address} with a value of 4958@code{0} yields the frame address of the current function, a value of 4959@code{1} yields the frame address of the caller of the current function, 4960and so forth. 4961 4962The frame is the area on the stack which holds local variables and saved 4963registers. The frame address is normally the address of the first word 4964pushed on to the stack by the function. However, the exact definition 4965depends upon the processor and the calling convention. If the processor 4966has a dedicated frame pointer register, and the function has a frame, 4967then @code{__builtin_frame_address} will return the value of the frame 4968pointer register. 4969 4970On some machines it may be impossible to determine the frame address of 4971any function other than the current one; in such cases, or when the top 4972of the stack has been reached, this function will return @code{0} if 4973the first frame pointer is properly initialized by the startup code. 4974 4975This function should only be used with a nonzero argument for debugging 4976purposes. 4977@end deftypefn 4978 4979@node Vector Extensions 4980@section Using vector instructions through built-in functions 4981 4982On some targets, the instruction set contains SIMD vector instructions that 4983operate on multiple values contained in one large register at the same time. 4984For example, on the i386 the MMX, 3Dnow! and SSE extensions can be used 4985this way. 4986 4987The first step in using these extensions is to provide the necessary data 4988types. This should be done using an appropriate @code{typedef}: 4989 4990@smallexample 4991typedef int v4si __attribute__ ((vector_size (16))); 4992@end smallexample 4993 4994The @code{int} type specifies the base type, while the attribute specifies 4995the vector size for the variable, measured in bytes. For example, the 4996declaration above causes the compiler to set the mode for the @code{v4si} 4997type to be 16 bytes wide and divided into @code{int} sized units. For 4998a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the 4999corresponding mode of @code{foo} will be @acronym{V4SI}. 5000 5001The @code{vector_size} attribute is only applicable to integral and 5002float scalars, although arrays, pointers, and function return values 5003are allowed in conjunction with this construct. 5004 5005All the basic integer types can be used as base types, both as signed 5006and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, 5007@code{long long}. In addition, @code{float} and @code{double} can be 5008used to build floating-point vector types. 5009 5010Specifying a combination that is not valid for the current architecture 5011will cause GCC to synthesize the instructions using a narrower mode. 5012For example, if you specify a variable of type @code{V4SI} and your 5013architecture does not allow for this specific SIMD type, GCC will 5014produce code that uses 4 @code{SIs}. 5015 5016The types defined in this manner can be used with a subset of normal C 5017operations. Currently, GCC will allow using the following operators 5018on these types: @code{+, -, *, /, unary minus, ^, |, &, ~}@. 5019 5020The operations behave like C++ @code{valarrays}. Addition is defined as 5021the addition of the corresponding elements of the operands. For 5022example, in the code below, each of the 4 elements in @var{a} will be 5023added to the corresponding 4 elements in @var{b} and the resulting 5024vector will be stored in @var{c}. 5025 5026@smallexample 5027typedef int v4si __attribute__ ((vector_size (16))); 5028 5029v4si a, b, c; 5030 5031c = a + b; 5032@end smallexample 5033 5034Subtraction, multiplication, division, and the logical operations 5035operate in a similar manner. Likewise, the result of using the unary 5036minus or complement operators on a vector type is a vector whose 5037elements are the negative or complemented values of the corresponding 5038elements in the operand. 5039 5040You can declare variables and use them in function calls and returns, as 5041well as in assignments and some casts. You can specify a vector type as 5042a return type for a function. Vector types can also be used as function 5043arguments. It is possible to cast from one vector type to another, 5044provided they are of the same size (in fact, you can also cast vectors 5045to and from other datatypes of the same size). 5046 5047You cannot operate between vectors of different lengths or different 5048signedness without a cast. 5049 5050A port that supports hardware vector operations, usually provides a set 5051of built-in functions that can be used to operate on vectors. For 5052example, a function to add two vectors and multiply the result by a 5053third could look like this: 5054 5055@smallexample 5056v4si f (v4si a, v4si b, v4si c) 5057@{ 5058 v4si tmp = __builtin_addv4si (a, b); 5059 return __builtin_mulv4si (tmp, c); 5060@} 5061 5062@end smallexample 5063 5064@node Offsetof 5065@section Offsetof 5066@findex __builtin_offsetof 5067 5068GCC implements for both C and C++ a syntactic extension to implement 5069the @code{offsetof} macro. 5070 5071@smallexample 5072primary: 5073 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" 5074 5075offsetof_member_designator: 5076 @code{identifier} 5077 | offsetof_member_designator "." @code{identifier} 5078 | offsetof_member_designator "[" @code{expr} "]" 5079@end smallexample 5080 5081This extension is sufficient such that 5082 5083@smallexample 5084#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) 5085@end smallexample 5086 5087is a suitable definition of the @code{offsetof} macro. In C++, @var{type} 5088may be dependent. In either case, @var{member} may consist of a single 5089identifier, or a sequence of member accesses and array references. 5090 5091@node Atomic Builtins 5092@section Built-in functions for atomic memory access 5093 5094The following builtins are intended to be compatible with those described 5095in the @cite{Intel Itanium Processor-specific Application Binary Interface}, 5096section 7.4. As such, they depart from the normal GCC practice of using 5097the ``__builtin_'' prefix, and further that they are overloaded such that 5098they work on multiple types. 5099 5100The definition given in the Intel documentation allows only for the use of 5101the types @code{int}, @code{long}, @code{long long} as well as their unsigned 5102counterparts. GCC will allow any integral scalar or pointer type that is 51031, 2, 4 or 8 bytes in length. 5104 5105Not all operations are supported by all target processors. If a particular 5106operation cannot be implemented on the target processor, a warning will be 5107generated and a call an external function will be generated. The external 5108function will carry the same name as the builtin, with an additional suffix 5109@samp{_@var{n}} where @var{n} is the size of the data type. 5110 5111@c ??? Should we have a mechanism to suppress this warning? This is almost 5112@c useful for implementing the operation under the control of an external 5113@c mutex. 5114 5115In most cases, these builtins are considered a @dfn{full barrier}. That is, 5116no memory operand will be moved across the operation, either forward or 5117backward. Further, instructions will be issued as necessary to prevent the 5118processor from speculating loads across the operation and from queuing stores 5119after the operation. 5120 5121All of the routines are are described in the Intel documentation to take 5122``an optional list of variables protected by the memory barrier''. It's 5123not clear what is meant by that; it could mean that @emph{only} the 5124following variables are protected, or it could mean that these variables 5125should in addition be protected. At present GCC ignores this list and 5126protects all variables which are globally accessible. If in the future 5127we make some use of this list, an empty list will continue to mean all 5128globally accessible variables. 5129 5130@table @code 5131@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) 5132@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) 5133@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) 5134@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) 5135@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) 5136@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) 5137@findex __sync_fetch_and_add 5138@findex __sync_fetch_and_sub 5139@findex __sync_fetch_and_or 5140@findex __sync_fetch_and_and 5141@findex __sync_fetch_and_xor 5142@findex __sync_fetch_and_nand 5143These builtins perform the operation suggested by the name, and 5144returns the value that had previously been in memory. That is, 5145 5146@smallexample 5147@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} 5148@{ tmp = *ptr; *ptr = ~tmp & value; return tmp; @} // nand 5149@end smallexample 5150 5151@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) 5152@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) 5153@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) 5154@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) 5155@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) 5156@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) 5157@findex __sync_add_and_fetch 5158@findex __sync_sub_and_fetch 5159@findex __sync_or_and_fetch 5160@findex __sync_and_and_fetch 5161@findex __sync_xor_and_fetch 5162@findex __sync_nand_and_fetch 5163These builtins perform the operation suggested by the name, and 5164return the new value. That is, 5165 5166@smallexample 5167@{ *ptr @var{op}= value; return *ptr; @} 5168@{ *ptr = ~*ptr & value; return *ptr; @} // nand 5169@end smallexample 5170 5171@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...) 5172@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...) 5173@findex __sync_bool_compare_and_swap 5174@findex __sync_val_compare_and_swap 5175These builtins perform an atomic compare and swap. That is, if the current 5176value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into 5177@code{*@var{ptr}}. 5178 5179The ``bool'' version returns true if the comparison is successful and 5180@var{newval} was written. The ``val'' version returns the contents 5181of @code{*@var{ptr}} before the operation. 5182 5183@item __sync_synchronize (...) 5184@findex __sync_synchronize 5185This builtin issues a full memory barrier. 5186 5187@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) 5188@findex __sync_lock_test_and_set 5189This builtin, as described by Intel, is not a traditional test-and-set 5190operation, but rather an atomic exchange operation. It writes @var{value} 5191into @code{*@var{ptr}}, and returns the previous contents of 5192@code{*@var{ptr}}. 5193 5194Many targets have only minimal support for such locks, and do not support 5195a full exchange operation. In this case, a target may support reduced 5196functionality here by which the @emph{only} valid value to store is the 5197immediate constant 1. The exact value actually stored in @code{*@var{ptr}} 5198is implementation defined. 5199 5200This builtin is not a full barrier, but rather an @dfn{acquire barrier}. 5201This means that references after the builtin cannot move to (or be 5202speculated to) before the builtin, but previous memory stores may not 5203be globally visible yet, and previous memory loads may not yet be 5204satisfied. 5205 5206@item void __sync_lock_release (@var{type} *ptr, ...) 5207@findex __sync_lock_release 5208This builtin releases the lock acquired by @code{__sync_lock_test_and_set}. 5209Normally this means writing the constant 0 to @code{*@var{ptr}}. 5210 5211This builtin is not a full barrier, but rather a @dfn{release barrier}. 5212This means that all previous memory stores are globally visible, and all 5213previous memory loads have been satisfied, but following memory reads 5214are not prevented from being speculated to before the barrier. 5215@end table 5216 5217@node Object Size Checking 5218@section Object Size Checking Builtins 5219@findex __builtin_object_size 5220@findex __builtin___memcpy_chk 5221@findex __builtin___mempcpy_chk 5222@findex __builtin___memmove_chk 5223@findex __builtin___memset_chk 5224@findex __builtin___strcpy_chk 5225@findex __builtin___stpcpy_chk 5226@findex __builtin___strncpy_chk 5227@findex __builtin___strcat_chk 5228@findex __builtin___strncat_chk 5229@findex __builtin___sprintf_chk 5230@findex __builtin___snprintf_chk 5231@findex __builtin___vsprintf_chk 5232@findex __builtin___vsnprintf_chk 5233@findex __builtin___printf_chk 5234@findex __builtin___vprintf_chk 5235@findex __builtin___fprintf_chk 5236@findex __builtin___vfprintf_chk 5237 5238GCC implements a limited buffer overflow protection mechanism 5239that can prevent some buffer overflow attacks. 5240 5241@deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type}) 5242is a built-in construct that returns a constant number of bytes from 5243@var{ptr} to the end of the object @var{ptr} pointer points to 5244(if known at compile time). @code{__builtin_object_size} never evaluates 5245its arguments for side-effects. If there are any side-effects in them, it 5246returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 5247for @var{type} 2 or 3. If there are multiple objects @var{ptr} can 5248point to and all of them are known at compile time, the returned number 5249is the maximum of remaining byte counts in those objects if @var{type} & 2 is 52500 and minimum if nonzero. If it is not possible to determine which objects 5251@var{ptr} points to at compile time, @code{__builtin_object_size} should 5252return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 5253for @var{type} 2 or 3. 5254 5255@var{type} is an integer constant from 0 to 3. If the least significant 5256bit is clear, objects are whole variables, if it is set, a closest 5257surrounding subobject is considered the object a pointer points to. 5258The second bit determines if maximum or minimum of remaining bytes 5259is computed. 5260 5261@smallexample 5262struct V @{ char buf1[10]; int b; char buf2[10]; @} var; 5263char *p = &var.buf1[1], *q = &var.b; 5264 5265/* Here the object p points to is var. */ 5266assert (__builtin_object_size (p, 0) == sizeof (var) - 1); 5267/* The subobject p points to is var.buf1. */ 5268assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); 5269/* The object q points to is var. */ 5270assert (__builtin_object_size (q, 0) 5271 == (char *) (&var + 1) - (char *) &var.b); 5272/* The subobject q points to is var.b. */ 5273assert (__builtin_object_size (q, 1) == sizeof (var.b)); 5274@end smallexample 5275@end deftypefn 5276 5277There are built-in functions added for many common string operation 5278functions, e.g. for @code{memcpy} @code{__builtin___memcpy_chk} 5279built-in is provided. This built-in has an additional last argument, 5280which is the number of bytes remaining in object the @var{dest} 5281argument points to or @code{(size_t) -1} if the size is not known. 5282 5283The built-in functions are optimized into the normal string functions 5284like @code{memcpy} if the last argument is @code{(size_t) -1} or if 5285it is known at compile time that the destination object will not 5286be overflown. If the compiler can determine at compile time the 5287object will be always overflown, it issues a warning. 5288 5289The intended use can be e.g. 5290 5291@smallexample 5292#undef memcpy 5293#define bos0(dest) __builtin_object_size (dest, 0) 5294#define memcpy(dest, src, n) \ 5295 __builtin___memcpy_chk (dest, src, n, bos0 (dest)) 5296 5297char *volatile p; 5298char buf[10]; 5299/* It is unknown what object p points to, so this is optimized 5300 into plain memcpy - no checking is possible. */ 5301memcpy (p, "abcde", n); 5302/* Destination is known and length too. It is known at compile 5303 time there will be no overflow. */ 5304memcpy (&buf[5], "abcde", 5); 5305/* Destination is known, but the length is not known at compile time. 5306 This will result in __memcpy_chk call that can check for overflow 5307 at runtime. */ 5308memcpy (&buf[5], "abcde", n); 5309/* Destination is known and it is known at compile time there will 5310 be overflow. There will be a warning and __memcpy_chk call that 5311 will abort the program at runtime. */ 5312memcpy (&buf[6], "abcde", 5); 5313@end smallexample 5314 5315Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, 5316@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, 5317@code{strcat} and @code{strncat}. 5318 5319There are also checking built-in functions for formatted output functions. 5320@smallexample 5321int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); 5322int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, 5323 const char *fmt, ...); 5324int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, 5325 va_list ap); 5326int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, 5327 const char *fmt, va_list ap); 5328@end smallexample 5329 5330The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} 5331etc. functions and can contain implementation specific flags on what 5332additional security measures the checking function might take, such as 5333handling @code{%n} differently. 5334 5335The @var{os} argument is the object size @var{s} points to, like in the 5336other built-in functions. There is a small difference in the behavior 5337though, if @var{os} is @code{(size_t) -1}, the built-in functions are 5338optimized into the non-checking functions only if @var{flag} is 0, otherwise 5339the checking function is called with @var{os} argument set to 5340@code{(size_t) -1}. 5341 5342In addition to this, there are checking built-in functions 5343@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, 5344@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. 5345These have just one additional argument, @var{flag}, right before 5346format string @var{fmt}. If the compiler is able to optimize them to 5347@code{fputc} etc. functions, it will, otherwise the checking function 5348should be called and the @var{flag} argument passed to it. 5349 5350@node Other Builtins 5351@section Other built-in functions provided by GCC 5352@cindex built-in functions 5353@findex __builtin_isgreater 5354@findex __builtin_isgreaterequal 5355@findex __builtin_isless 5356@findex __builtin_islessequal 5357@findex __builtin_islessgreater 5358@findex __builtin_isunordered 5359@findex __builtin_powi 5360@findex __builtin_powif 5361@findex __builtin_powil 5362@findex _Exit 5363@findex _exit 5364@findex abort 5365@findex abs 5366@findex acos 5367@findex acosf 5368@findex acosh 5369@findex acoshf 5370@findex acoshl 5371@findex acosl 5372@findex alloca 5373@findex asin 5374@findex asinf 5375@findex asinh 5376@findex asinhf 5377@findex asinhl 5378@findex asinl 5379@findex atan 5380@findex atan2 5381@findex atan2f 5382@findex atan2l 5383@findex atanf 5384@findex atanh 5385@findex atanhf 5386@findex atanhl 5387@findex atanl 5388@findex bcmp 5389@findex bzero 5390@findex cabs 5391@findex cabsf 5392@findex cabsl 5393@findex cacos 5394@findex cacosf 5395@findex cacosh 5396@findex cacoshf 5397@findex cacoshl 5398@findex cacosl 5399@findex calloc 5400@findex carg 5401@findex cargf 5402@findex cargl 5403@findex casin 5404@findex casinf 5405@findex casinh 5406@findex casinhf 5407@findex casinhl 5408@findex casinl 5409@findex catan 5410@findex catanf 5411@findex catanh 5412@findex catanhf 5413@findex catanhl 5414@findex catanl 5415@findex cbrt 5416@findex cbrtf 5417@findex cbrtl 5418@findex ccos 5419@findex ccosf 5420@findex ccosh 5421@findex ccoshf 5422@findex ccoshl 5423@findex ccosl 5424@findex ceil 5425@findex ceilf 5426@findex ceill 5427@findex cexp 5428@findex cexpf 5429@findex cexpl 5430@findex cimag 5431@findex cimagf 5432@findex cimagl 5433@findex clog 5434@findex clogf 5435@findex clogl 5436@findex conj 5437@findex conjf 5438@findex conjl 5439@findex copysign 5440@findex copysignf 5441@findex copysignl 5442@findex cos 5443@findex cosf 5444@findex cosh 5445@findex coshf 5446@findex coshl 5447@findex cosl 5448@findex cpow 5449@findex cpowf 5450@findex cpowl 5451@findex cproj 5452@findex cprojf 5453@findex cprojl 5454@findex creal 5455@findex crealf 5456@findex creall 5457@findex csin 5458@findex csinf 5459@findex csinh 5460@findex csinhf 5461@findex csinhl 5462@findex csinl 5463@findex csqrt 5464@findex csqrtf 5465@findex csqrtl 5466@findex ctan 5467@findex ctanf 5468@findex ctanh 5469@findex ctanhf 5470@findex ctanhl 5471@findex ctanl 5472@findex dcgettext 5473@findex dgettext 5474@findex drem 5475@findex dremf 5476@findex dreml 5477@findex erf 5478@findex erfc 5479@findex erfcf 5480@findex erfcl 5481@findex erff 5482@findex erfl 5483@findex exit 5484@findex exp 5485@findex exp10 5486@findex exp10f 5487@findex exp10l 5488@findex exp2 5489@findex exp2f 5490@findex exp2l 5491@findex expf 5492@findex expl 5493@findex expm1 5494@findex expm1f 5495@findex expm1l 5496@findex fabs 5497@findex fabsf 5498@findex fabsl 5499@findex fdim 5500@findex fdimf 5501@findex fdiml 5502@findex ffs 5503@findex floor 5504@findex floorf 5505@findex floorl 5506@findex fma 5507@findex fmaf 5508@findex fmal 5509@findex fmax 5510@findex fmaxf 5511@findex fmaxl 5512@findex fmin 5513@findex fminf 5514@findex fminl 5515@findex fmod 5516@findex fmodf 5517@findex fmodl 5518@findex fprintf 5519@findex fprintf_unlocked 5520@findex fputs 5521@findex fputs_unlocked 5522@findex frexp 5523@findex frexpf 5524@findex frexpl 5525@findex fscanf 5526@findex gamma 5527@findex gammaf 5528@findex gammal 5529@findex gettext 5530@findex hypot 5531@findex hypotf 5532@findex hypotl 5533@findex ilogb 5534@findex ilogbf 5535@findex ilogbl 5536@findex imaxabs 5537@findex index 5538@findex isalnum 5539@findex isalpha 5540@findex isascii 5541@findex isblank 5542@findex iscntrl 5543@findex isdigit 5544@findex isgraph 5545@findex islower 5546@findex isprint 5547@findex ispunct 5548@findex isspace 5549@findex isupper 5550@findex iswalnum 5551@findex iswalpha 5552@findex iswblank 5553@findex iswcntrl 5554@findex iswdigit 5555@findex iswgraph 5556@findex iswlower 5557@findex iswprint 5558@findex iswpunct 5559@findex iswspace 5560@findex iswupper 5561@findex iswxdigit 5562@findex isxdigit 5563@findex j0 5564@findex j0f 5565@findex j0l 5566@findex j1 5567@findex j1f 5568@findex j1l 5569@findex jn 5570@findex jnf 5571@findex jnl 5572@findex labs 5573@findex ldexp 5574@findex ldexpf 5575@findex ldexpl 5576@findex lgamma 5577@findex lgammaf 5578@findex lgammal 5579@findex llabs 5580@findex llrint 5581@findex llrintf 5582@findex llrintl 5583@findex llround 5584@findex llroundf 5585@findex llroundl 5586@findex log 5587@findex log10 5588@findex log10f 5589@findex log10l 5590@findex log1p 5591@findex log1pf 5592@findex log1pl 5593@findex log2 5594@findex log2f 5595@findex log2l 5596@findex logb 5597@findex logbf 5598@findex logbl 5599@findex logf 5600@findex logl 5601@findex lrint 5602@findex lrintf 5603@findex lrintl 5604@findex lround 5605@findex lroundf 5606@findex lroundl 5607@findex malloc 5608@findex memcmp 5609@findex memcpy 5610@findex mempcpy 5611@findex memset 5612@findex modf 5613@findex modff 5614@findex modfl 5615@findex nearbyint 5616@findex nearbyintf 5617@findex nearbyintl 5618@findex nextafter 5619@findex nextafterf 5620@findex nextafterl 5621@findex nexttoward 5622@findex nexttowardf 5623@findex nexttowardl 5624@findex pow 5625@findex pow10 5626@findex pow10f 5627@findex pow10l 5628@findex powf 5629@findex powl 5630@findex printf 5631@findex printf_unlocked 5632@findex putchar 5633@findex puts 5634@findex remainder 5635@findex remainderf 5636@findex remainderl 5637@findex remquo 5638@findex remquof 5639@findex remquol 5640@findex rindex 5641@findex rint 5642@findex rintf 5643@findex rintl 5644@findex round 5645@findex roundf 5646@findex roundl 5647@findex scalb 5648@findex scalbf 5649@findex scalbl 5650@findex scalbln 5651@findex scalblnf 5652@findex scalblnf 5653@findex scalbn 5654@findex scalbnf 5655@findex scanfnl 5656@findex signbit 5657@findex signbitf 5658@findex signbitl 5659@findex significand 5660@findex significandf 5661@findex significandl 5662@findex sin 5663@findex sincos 5664@findex sincosf 5665@findex sincosl 5666@findex sinf 5667@findex sinh 5668@findex sinhf 5669@findex sinhl 5670@findex sinl 5671@findex snprintf 5672@findex sprintf 5673@findex sqrt 5674@findex sqrtf 5675@findex sqrtl 5676@findex sscanf 5677@findex stpcpy 5678@findex stpncpy 5679@findex strcasecmp 5680@findex strcat 5681@findex strchr 5682@findex strcmp 5683@findex strcpy 5684@findex strcspn 5685@findex strdup 5686@findex strfmon 5687@findex strftime 5688@findex strlen 5689@findex strncasecmp 5690@findex strncat 5691@findex strncmp 5692@findex strncpy 5693@findex strndup 5694@findex strpbrk 5695@findex strrchr 5696@findex strspn 5697@findex strstr 5698@findex tan 5699@findex tanf 5700@findex tanh 5701@findex tanhf 5702@findex tanhl 5703@findex tanl 5704@findex tgamma 5705@findex tgammaf 5706@findex tgammal 5707@findex toascii 5708@findex tolower 5709@findex toupper 5710@findex towlower 5711@findex towupper 5712@findex trunc 5713@findex truncf 5714@findex truncl 5715@findex vfprintf 5716@findex vfscanf 5717@findex vprintf 5718@findex vscanf 5719@findex vsnprintf 5720@findex vsprintf 5721@findex vsscanf 5722@findex y0 5723@findex y0f 5724@findex y0l 5725@findex y1 5726@findex y1f 5727@findex y1l 5728@findex yn 5729@findex ynf 5730@findex ynl 5731 5732GCC provides a large number of built-in functions other than the ones 5733mentioned above. Some of these are for internal use in the processing 5734of exceptions or variable-length argument lists and will not be 5735documented here because they may change from time to time; we do not 5736recommend general use of these functions. 5737 5738The remaining functions are provided for optimization purposes. 5739 5740@opindex fno-builtin 5741GCC includes built-in versions of many of the functions in the standard 5742C library. The versions prefixed with @code{__builtin_} will always be 5743treated as having the same meaning as the C library function even if you 5744specify the @option{-fno-builtin} option. (@pxref{C Dialect Options}) 5745Many of these functions are only optimized in certain cases; if they are 5746not optimized in a particular case, a call to the library function will 5747be emitted. 5748 5749@opindex ansi 5750@opindex std 5751Outside strict ISO C mode (@option{-ansi}, @option{-std=c89} or 5752@option{-std=c99}), the functions 5753@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, 5754@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, 5755@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, 5756@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, @code{fputs_unlocked}, 5757@code{gammaf}, @code{gammal}, @code{gamma}, @code{gettext}, 5758@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, 5759@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, 5760@code{mempcpy}, @code{pow10f}, @code{pow10l}, @code{pow10}, 5761@code{printf_unlocked}, @code{rindex}, @code{scalbf}, @code{scalbl}, 5762@code{scalb}, @code{signbit}, @code{signbitf}, @code{signbitl}, 5763@code{significandf}, @code{significandl}, @code{significand}, 5764@code{sincosf}, @code{sincosl}, @code{sincos}, @code{stpcpy}, 5765@code{stpncpy}, @code{strcasecmp}, @code{strdup}, @code{strfmon}, 5766@code{strncasecmp}, @code{strndup}, @code{toascii}, @code{y0f}, 5767@code{y0l}, @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, 5768@code{ynl} and @code{yn} 5769may be handled as built-in functions. 5770All these functions have corresponding versions 5771prefixed with @code{__builtin_}, which may be used even in strict C89 5772mode. 5773 5774The ISO C99 functions 5775@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, 5776@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, 5777@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, 5778@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, 5779@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, 5780@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, 5781@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, 5782@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, 5783@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, 5784@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, 5785@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, 5786@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, 5787@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, 5788@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, 5789@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, 5790@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, 5791@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, 5792@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, 5793@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, 5794@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, 5795@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, 5796@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, 5797@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, 5798@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, 5799@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, 5800@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, 5801@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, 5802@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, 5803@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, 5804@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, 5805@code{nextafterf}, @code{nextafterl}, @code{nextafter}, 5806@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, 5807@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, 5808@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, 5809@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, 5810@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, 5811@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, 5812@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, 5813@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} 5814are handled as built-in functions 5815except in strict ISO C90 mode (@option{-ansi} or @option{-std=c89}). 5816 5817There are also built-in versions of the ISO C99 functions 5818@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, 5819@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, 5820@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, 5821@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, 5822@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, 5823@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, 5824@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, 5825@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, 5826@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} 5827that are recognized in any mode since ISO C90 reserves these names for 5828the purpose to which ISO C99 puts them. All these functions have 5829corresponding versions prefixed with @code{__builtin_}. 5830 5831The ISO C94 functions 5832@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, 5833@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, 5834@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and 5835@code{towupper} 5836are handled as built-in functions 5837except in strict ISO C90 mode (@option{-ansi} or @option{-std=c89}). 5838 5839The ISO C90 functions 5840@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, 5841@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, 5842@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, 5843@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf}, 5844@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, 5845@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, 5846@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, 5847@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, 5848@code{malloc}, @code{memcmp}, @code{memcpy}, @code{memset}, @code{modf}, 5849@code{pow}, @code{printf}, @code{putchar}, @code{puts}, @code{scanf}, 5850@code{sinh}, @code{sin}, @code{snprintf}, @code{sprintf}, @code{sqrt}, 5851@code{sscanf}, @code{strcat}, @code{strchr}, @code{strcmp}, 5852@code{strcpy}, @code{strcspn}, @code{strlen}, @code{strncat}, 5853@code{strncmp}, @code{strncpy}, @code{strpbrk}, @code{strrchr}, 5854@code{strspn}, @code{strstr}, @code{tanh}, @code{tan}, @code{vfprintf}, 5855@code{vprintf} and @code{vsprintf} 5856are all recognized as built-in functions unless 5857@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} 5858is specified for an individual function). All of these functions have 5859corresponding versions prefixed with @code{__builtin_}. 5860 5861GCC provides built-in versions of the ISO C99 floating point comparison 5862macros that avoid raising exceptions for unordered operands. They have 5863the same names as the standard macros ( @code{isgreater}, 5864@code{isgreaterequal}, @code{isless}, @code{islessequal}, 5865@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} 5866prefixed. We intend for a library implementor to be able to simply 5867@code{#define} each standard macro to its built-in equivalent. 5868 5869@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) 5870 5871You can use the built-in function @code{__builtin_types_compatible_p} to 5872determine whether two types are the same. 5873 5874This built-in function returns 1 if the unqualified versions of the 5875types @var{type1} and @var{type2} (which are types, not expressions) are 5876compatible, 0 otherwise. The result of this built-in function can be 5877used in integer constant expressions. 5878 5879This built-in function ignores top level qualifiers (e.g., @code{const}, 5880@code{volatile}). For example, @code{int} is equivalent to @code{const 5881int}. 5882 5883The type @code{int[]} and @code{int[5]} are compatible. On the other 5884hand, @code{int} and @code{char *} are not compatible, even if the size 5885of their types, on the particular architecture are the same. Also, the 5886amount of pointer indirection is taken into account when determining 5887similarity. Consequently, @code{short *} is not similar to 5888@code{short **}. Furthermore, two types that are typedefed are 5889considered compatible if their underlying types are compatible. 5890 5891An @code{enum} type is not considered to be compatible with another 5892@code{enum} type even if both are compatible with the same integer 5893type; this is what the C standard specifies. 5894For example, @code{enum @{foo, bar@}} is not similar to 5895@code{enum @{hot, dog@}}. 5896 5897You would typically use this function in code whose execution varies 5898depending on the arguments' types. For example: 5899 5900@smallexample 5901#define foo(x) \ 5902 (@{ \ 5903 typeof (x) tmp = (x); \ 5904 if (__builtin_types_compatible_p (typeof (x), long double)) \ 5905 tmp = foo_long_double (tmp); \ 5906 else if (__builtin_types_compatible_p (typeof (x), double)) \ 5907 tmp = foo_double (tmp); \ 5908 else if (__builtin_types_compatible_p (typeof (x), float)) \ 5909 tmp = foo_float (tmp); \ 5910 else \ 5911 abort (); \ 5912 tmp; \ 5913 @}) 5914@end smallexample 5915 5916@emph{Note:} This construct is only available for C@. 5917 5918@end deftypefn 5919 5920@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) 5921 5922You can use the built-in function @code{__builtin_choose_expr} to 5923evaluate code depending on the value of a constant expression. This 5924built-in function returns @var{exp1} if @var{const_exp}, which is a 5925constant expression that must be able to be determined at compile time, 5926is nonzero. Otherwise it returns 0. 5927 5928This built-in function is analogous to the @samp{? :} operator in C, 5929except that the expression returned has its type unaltered by promotion 5930rules. Also, the built-in function does not evaluate the expression 5931that was not chosen. For example, if @var{const_exp} evaluates to true, 5932@var{exp2} is not evaluated even if it has side-effects. 5933 5934This built-in function can return an lvalue if the chosen argument is an 5935lvalue. 5936 5937If @var{exp1} is returned, the return type is the same as @var{exp1}'s 5938type. Similarly, if @var{exp2} is returned, its return type is the same 5939as @var{exp2}. 5940 5941Example: 5942 5943@smallexample 5944#define foo(x) \ 5945 __builtin_choose_expr ( \ 5946 __builtin_types_compatible_p (typeof (x), double), \ 5947 foo_double (x), \ 5948 __builtin_choose_expr ( \ 5949 __builtin_types_compatible_p (typeof (x), float), \ 5950 foo_float (x), \ 5951 /* @r{The void expression results in a compile-time error} \ 5952 @r{when assigning the result to something.} */ \ 5953 (void)0)) 5954@end smallexample 5955 5956@emph{Note:} This construct is only available for C@. Furthermore, the 5957unused expression (@var{exp1} or @var{exp2} depending on the value of 5958@var{const_exp}) may still generate syntax errors. This may change in 5959future revisions. 5960 5961@end deftypefn 5962 5963@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) 5964You can use the built-in function @code{__builtin_constant_p} to 5965determine if a value is known to be constant at compile-time and hence 5966that GCC can perform constant-folding on expressions involving that 5967value. The argument of the function is the value to test. The function 5968returns the integer 1 if the argument is known to be a compile-time 5969constant and 0 if it is not known to be a compile-time constant. A 5970return of 0 does not indicate that the value is @emph{not} a constant, 5971but merely that GCC cannot prove it is a constant with the specified 5972value of the @option{-O} option. 5973 5974You would typically use this function in an embedded application where 5975memory was a critical resource. If you have some complex calculation, 5976you may want it to be folded if it involves constants, but need to call 5977a function if it does not. For example: 5978 5979@smallexample 5980#define Scale_Value(X) \ 5981 (__builtin_constant_p (X) \ 5982 ? ((X) * SCALE + OFFSET) : Scale (X)) 5983@end smallexample 5984 5985You may use this built-in function in either a macro or an inline 5986function. However, if you use it in an inlined function and pass an 5987argument of the function as the argument to the built-in, GCC will 5988never return 1 when you call the inline function with a string constant 5989or compound literal (@pxref{Compound Literals}) and will not return 1 5990when you pass a constant numeric value to the inline function unless you 5991specify the @option{-O} option. 5992 5993You may also use @code{__builtin_constant_p} in initializers for static 5994data. For instance, you can write 5995 5996@smallexample 5997static const int table[] = @{ 5998 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, 5999 /* @r{@dots{}} */ 6000@}; 6001@end smallexample 6002 6003@noindent 6004This is an acceptable initializer even if @var{EXPRESSION} is not a 6005constant expression. GCC must be more conservative about evaluating the 6006built-in in this case, because it has no opportunity to perform 6007optimization. 6008 6009Previous versions of GCC did not accept this built-in in data 6010initializers. The earliest version where it is completely safe is 60113.0.1. 6012@end deftypefn 6013 6014@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) 6015@opindex fprofile-arcs 6016You may use @code{__builtin_expect} to provide the compiler with 6017branch prediction information. In general, you should prefer to 6018use actual profile feedback for this (@option{-fprofile-arcs}), as 6019programmers are notoriously bad at predicting how their programs 6020actually perform. However, there are applications in which this 6021data is hard to collect. 6022 6023The return value is the value of @var{exp}, which should be an 6024integral expression. The value of @var{c} must be a compile-time 6025constant. The semantics of the built-in are that it is expected 6026that @var{exp} == @var{c}. For example: 6027 6028@smallexample 6029if (__builtin_expect (x, 0)) 6030 foo (); 6031@end smallexample 6032 6033@noindent 6034would indicate that we do not expect to call @code{foo}, since 6035we expect @code{x} to be zero. Since you are limited to integral 6036expressions for @var{exp}, you should use constructions such as 6037 6038@smallexample 6039if (__builtin_expect (ptr != NULL, 1)) 6040 error (); 6041@end smallexample 6042 6043@noindent 6044when testing pointer or floating-point values. 6045@end deftypefn 6046 6047@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) 6048This function is used to minimize cache-miss latency by moving data into 6049a cache before it is accessed. 6050You can insert calls to @code{__builtin_prefetch} into code for which 6051you know addresses of data in memory that is likely to be accessed soon. 6052If the target supports them, data prefetch instructions will be generated. 6053If the prefetch is done early enough before the access then the data will 6054be in the cache by the time it is accessed. 6055 6056The value of @var{addr} is the address of the memory to prefetch. 6057There are two optional arguments, @var{rw} and @var{locality}. 6058The value of @var{rw} is a compile-time constant one or zero; one 6059means that the prefetch is preparing for a write to the memory address 6060and zero, the default, means that the prefetch is preparing for a read. 6061The value @var{locality} must be a compile-time constant integer between 6062zero and three. A value of zero means that the data has no temporal 6063locality, so it need not be left in the cache after the access. A value 6064of three means that the data has a high degree of temporal locality and 6065should be left in all levels of cache possible. Values of one and two 6066mean, respectively, a low or moderate degree of temporal locality. The 6067default is three. 6068 6069@smallexample 6070for (i = 0; i < n; i++) 6071 @{ 6072 a[i] = a[i] + b[i]; 6073 __builtin_prefetch (&a[i+j], 1, 1); 6074 __builtin_prefetch (&b[i+j], 0, 1); 6075 /* @r{@dots{}} */ 6076 @} 6077@end smallexample 6078 6079Data prefetch does not generate faults if @var{addr} is invalid, but 6080the address expression itself must be valid. For example, a prefetch 6081of @code{p->next} will not fault if @code{p->next} is not a valid 6082address, but evaluation will fault if @code{p} is not a valid address. 6083 6084If the target does not support data prefetch, the address expression 6085is evaluated if it includes side effects but no other code is generated 6086and GCC does not issue a warning. 6087@end deftypefn 6088 6089@deftypefn {Built-in Function} double __builtin_huge_val (void) 6090Returns a positive infinity, if supported by the floating-point format, 6091else @code{DBL_MAX}. This function is suitable for implementing the 6092ISO C macro @code{HUGE_VAL}. 6093@end deftypefn 6094 6095@deftypefn {Built-in Function} float __builtin_huge_valf (void) 6096Similar to @code{__builtin_huge_val}, except the return type is @code{float}. 6097@end deftypefn 6098 6099@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) 6100Similar to @code{__builtin_huge_val}, except the return 6101type is @code{long double}. 6102@end deftypefn 6103 6104@deftypefn {Built-in Function} double __builtin_inf (void) 6105Similar to @code{__builtin_huge_val}, except a warning is generated 6106if the target floating-point format does not support infinities. 6107@end deftypefn 6108 6109@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) 6110Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. 6111@end deftypefn 6112 6113@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) 6114Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. 6115@end deftypefn 6116 6117@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) 6118Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. 6119@end deftypefn 6120 6121@deftypefn {Built-in Function} float __builtin_inff (void) 6122Similar to @code{__builtin_inf}, except the return type is @code{float}. 6123This function is suitable for implementing the ISO C99 macro @code{INFINITY}. 6124@end deftypefn 6125 6126@deftypefn {Built-in Function} {long double} __builtin_infl (void) 6127Similar to @code{__builtin_inf}, except the return 6128type is @code{long double}. 6129@end deftypefn 6130 6131@deftypefn {Built-in Function} double __builtin_nan (const char *str) 6132This is an implementation of the ISO C99 function @code{nan}. 6133 6134Since ISO C99 defines this function in terms of @code{strtod}, which we 6135do not implement, a description of the parsing is in order. The string 6136is parsed as by @code{strtol}; that is, the base is recognized by 6137leading @samp{0} or @samp{0x} prefixes. The number parsed is placed 6138in the significand such that the least significant bit of the number 6139is at the least significant bit of the significand. The number is 6140truncated to fit the significand field provided. The significand is 6141forced to be a quiet NaN@. 6142 6143This function, if given a string literal all of which would have been 6144consumed by strtol, is evaluated early enough that it is considered a 6145compile-time constant. 6146@end deftypefn 6147 6148@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) 6149Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. 6150@end deftypefn 6151 6152@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) 6153Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. 6154@end deftypefn 6155 6156@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) 6157Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. 6158@end deftypefn 6159 6160@deftypefn {Built-in Function} float __builtin_nanf (const char *str) 6161Similar to @code{__builtin_nan}, except the return type is @code{float}. 6162@end deftypefn 6163 6164@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) 6165Similar to @code{__builtin_nan}, except the return type is @code{long double}. 6166@end deftypefn 6167 6168@deftypefn {Built-in Function} double __builtin_nans (const char *str) 6169Similar to @code{__builtin_nan}, except the significand is forced 6170to be a signaling NaN@. The @code{nans} function is proposed by 6171@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. 6172@end deftypefn 6173 6174@deftypefn {Built-in Function} float __builtin_nansf (const char *str) 6175Similar to @code{__builtin_nans}, except the return type is @code{float}. 6176@end deftypefn 6177 6178@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) 6179Similar to @code{__builtin_nans}, except the return type is @code{long double}. 6180@end deftypefn 6181 6182@deftypefn {Built-in Function} int __builtin_ffs (unsigned int x) 6183Returns one plus the index of the least significant 1-bit of @var{x}, or 6184if @var{x} is zero, returns zero. 6185@end deftypefn 6186 6187@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) 6188Returns the number of leading 0-bits in @var{x}, starting at the most 6189significant bit position. If @var{x} is 0, the result is undefined. 6190@end deftypefn 6191 6192@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) 6193Returns the number of trailing 0-bits in @var{x}, starting at the least 6194significant bit position. If @var{x} is 0, the result is undefined. 6195@end deftypefn 6196 6197@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) 6198Returns the number of 1-bits in @var{x}. 6199@end deftypefn 6200 6201@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) 6202Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} 6203modulo 2. 6204@end deftypefn 6205 6206@deftypefn {Built-in Function} int __builtin_ffsl (unsigned long) 6207Similar to @code{__builtin_ffs}, except the argument type is 6208@code{unsigned long}. 6209@end deftypefn 6210 6211@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) 6212Similar to @code{__builtin_clz}, except the argument type is 6213@code{unsigned long}. 6214@end deftypefn 6215 6216@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) 6217Similar to @code{__builtin_ctz}, except the argument type is 6218@code{unsigned long}. 6219@end deftypefn 6220 6221@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) 6222Similar to @code{__builtin_popcount}, except the argument type is 6223@code{unsigned long}. 6224@end deftypefn 6225 6226@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) 6227Similar to @code{__builtin_parity}, except the argument type is 6228@code{unsigned long}. 6229@end deftypefn 6230 6231@deftypefn {Built-in Function} int __builtin_ffsll (unsigned long long) 6232Similar to @code{__builtin_ffs}, except the argument type is 6233@code{unsigned long long}. 6234@end deftypefn 6235 6236@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) 6237Similar to @code{__builtin_clz}, except the argument type is 6238@code{unsigned long long}. 6239@end deftypefn 6240 6241@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) 6242Similar to @code{__builtin_ctz}, except the argument type is 6243@code{unsigned long long}. 6244@end deftypefn 6245 6246@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) 6247Similar to @code{__builtin_popcount}, except the argument type is 6248@code{unsigned long long}. 6249@end deftypefn 6250 6251@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) 6252Similar to @code{__builtin_parity}, except the argument type is 6253@code{unsigned long long}. 6254@end deftypefn 6255 6256@deftypefn {Built-in Function} double __builtin_powi (double, int) 6257Returns the first argument raised to the power of the second. Unlike the 6258@code{pow} function no guarantees about precision and rounding are made. 6259@end deftypefn 6260 6261@deftypefn {Built-in Function} float __builtin_powif (float, int) 6262Similar to @code{__builtin_powi}, except the argument and return types 6263are @code{float}. 6264@end deftypefn 6265 6266@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) 6267Similar to @code{__builtin_powi}, except the argument and return types 6268are @code{long double}. 6269@end deftypefn 6270 6271@deftypefn {Built-in Function} int32_t __builtin_bswap32 (int32_t x) 6272Returns @var{x} with the order of the bytes reversed; for example, 6273@code{0xaabbccdd} becomes @code{0xddccbbaa}. Byte here always means 6274exactly 8 bits. 6275@end deftypefn 6276 6277@deftypefn {Built-in Function} int64_t __builtin_bswap64 (int64_t x) 6278Similar to @code{__builtin_bswap32}, except the argument and return types 6279are 64-bit. 6280@end deftypefn 6281 6282@node Target Builtins 6283@section Built-in Functions Specific to Particular Target Machines 6284 6285On some target machines, GCC supports many built-in functions specific 6286to those machines. Generally these generate calls to specific machine 6287instructions, but allow the compiler to schedule those calls. 6288 6289@menu 6290* Alpha Built-in Functions:: 6291* ARM Built-in Functions:: 6292* Blackfin Built-in Functions:: 6293* FR-V Built-in Functions:: 6294* X86 Built-in Functions:: 6295* MIPS DSP Built-in Functions:: 6296* MIPS Paired-Single Support:: 6297* PowerPC AltiVec Built-in Functions:: 6298* SPARC VIS Built-in Functions:: 6299@end menu 6300 6301@node Alpha Built-in Functions 6302@subsection Alpha Built-in Functions 6303 6304These built-in functions are available for the Alpha family of 6305processors, depending on the command-line switches used. 6306 6307The following built-in functions are always available. They 6308all generate the machine instruction that is part of the name. 6309 6310@smallexample 6311long __builtin_alpha_implver (void) 6312long __builtin_alpha_rpcc (void) 6313long __builtin_alpha_amask (long) 6314long __builtin_alpha_cmpbge (long, long) 6315long __builtin_alpha_extbl (long, long) 6316long __builtin_alpha_extwl (long, long) 6317long __builtin_alpha_extll (long, long) 6318long __builtin_alpha_extql (long, long) 6319long __builtin_alpha_extwh (long, long) 6320long __builtin_alpha_extlh (long, long) 6321long __builtin_alpha_extqh (long, long) 6322long __builtin_alpha_insbl (long, long) 6323long __builtin_alpha_inswl (long, long) 6324long __builtin_alpha_insll (long, long) 6325long __builtin_alpha_insql (long, long) 6326long __builtin_alpha_inswh (long, long) 6327long __builtin_alpha_inslh (long, long) 6328long __builtin_alpha_insqh (long, long) 6329long __builtin_alpha_mskbl (long, long) 6330long __builtin_alpha_mskwl (long, long) 6331long __builtin_alpha_mskll (long, long) 6332long __builtin_alpha_mskql (long, long) 6333long __builtin_alpha_mskwh (long, long) 6334long __builtin_alpha_msklh (long, long) 6335long __builtin_alpha_mskqh (long, long) 6336long __builtin_alpha_umulh (long, long) 6337long __builtin_alpha_zap (long, long) 6338long __builtin_alpha_zapnot (long, long) 6339@end smallexample 6340 6341The following built-in functions are always with @option{-mmax} 6342or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or 6343later. They all generate the machine instruction that is part 6344of the name. 6345 6346@smallexample 6347long __builtin_alpha_pklb (long) 6348long __builtin_alpha_pkwb (long) 6349long __builtin_alpha_unpkbl (long) 6350long __builtin_alpha_unpkbw (long) 6351long __builtin_alpha_minub8 (long, long) 6352long __builtin_alpha_minsb8 (long, long) 6353long __builtin_alpha_minuw4 (long, long) 6354long __builtin_alpha_minsw4 (long, long) 6355long __builtin_alpha_maxub8 (long, long) 6356long __builtin_alpha_maxsb8 (long, long) 6357long __builtin_alpha_maxuw4 (long, long) 6358long __builtin_alpha_maxsw4 (long, long) 6359long __builtin_alpha_perr (long, long) 6360@end smallexample 6361 6362The following built-in functions are always with @option{-mcix} 6363or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or 6364later. They all generate the machine instruction that is part 6365of the name. 6366 6367@smallexample 6368long __builtin_alpha_cttz (long) 6369long __builtin_alpha_ctlz (long) 6370long __builtin_alpha_ctpop (long) 6371@end smallexample 6372 6373The following builtins are available on systems that use the OSF/1 6374PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} 6375PAL calls, but when invoked with @option{-mtls-kernel}, they invoke 6376@code{rdval} and @code{wrval}. 6377 6378@smallexample 6379void *__builtin_thread_pointer (void) 6380void __builtin_set_thread_pointer (void *) 6381@end smallexample 6382 6383@node ARM Built-in Functions 6384@subsection ARM Built-in Functions 6385 6386These built-in functions are available for the ARM family of 6387processors, when the @option{-mcpu=iwmmxt} switch is used: 6388 6389@smallexample 6390typedef int v2si __attribute__ ((vector_size (8))); 6391typedef short v4hi __attribute__ ((vector_size (8))); 6392typedef char v8qi __attribute__ ((vector_size (8))); 6393 6394int __builtin_arm_getwcx (int) 6395void __builtin_arm_setwcx (int, int) 6396int __builtin_arm_textrmsb (v8qi, int) 6397int __builtin_arm_textrmsh (v4hi, int) 6398int __builtin_arm_textrmsw (v2si, int) 6399int __builtin_arm_textrmub (v8qi, int) 6400int __builtin_arm_textrmuh (v4hi, int) 6401int __builtin_arm_textrmuw (v2si, int) 6402v8qi __builtin_arm_tinsrb (v8qi, int) 6403v4hi __builtin_arm_tinsrh (v4hi, int) 6404v2si __builtin_arm_tinsrw (v2si, int) 6405long long __builtin_arm_tmia (long long, int, int) 6406long long __builtin_arm_tmiabb (long long, int, int) 6407long long __builtin_arm_tmiabt (long long, int, int) 6408long long __builtin_arm_tmiaph (long long, int, int) 6409long long __builtin_arm_tmiatb (long long, int, int) 6410long long __builtin_arm_tmiatt (long long, int, int) 6411int __builtin_arm_tmovmskb (v8qi) 6412int __builtin_arm_tmovmskh (v4hi) 6413int __builtin_arm_tmovmskw (v2si) 6414long long __builtin_arm_waccb (v8qi) 6415long long __builtin_arm_wacch (v4hi) 6416long long __builtin_arm_waccw (v2si) 6417v8qi __builtin_arm_waddb (v8qi, v8qi) 6418v8qi __builtin_arm_waddbss (v8qi, v8qi) 6419v8qi __builtin_arm_waddbus (v8qi, v8qi) 6420v4hi __builtin_arm_waddh (v4hi, v4hi) 6421v4hi __builtin_arm_waddhss (v4hi, v4hi) 6422v4hi __builtin_arm_waddhus (v4hi, v4hi) 6423v2si __builtin_arm_waddw (v2si, v2si) 6424v2si __builtin_arm_waddwss (v2si, v2si) 6425v2si __builtin_arm_waddwus (v2si, v2si) 6426v8qi __builtin_arm_walign (v8qi, v8qi, int) 6427long long __builtin_arm_wand(long long, long long) 6428long long __builtin_arm_wandn (long long, long long) 6429v8qi __builtin_arm_wavg2b (v8qi, v8qi) 6430v8qi __builtin_arm_wavg2br (v8qi, v8qi) 6431v4hi __builtin_arm_wavg2h (v4hi, v4hi) 6432v4hi __builtin_arm_wavg2hr (v4hi, v4hi) 6433v8qi __builtin_arm_wcmpeqb (v8qi, v8qi) 6434v4hi __builtin_arm_wcmpeqh (v4hi, v4hi) 6435v2si __builtin_arm_wcmpeqw (v2si, v2si) 6436v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) 6437v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) 6438v2si __builtin_arm_wcmpgtsw (v2si, v2si) 6439v8qi __builtin_arm_wcmpgtub (v8qi, v8qi) 6440v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) 6441v2si __builtin_arm_wcmpgtuw (v2si, v2si) 6442long long __builtin_arm_wmacs (long long, v4hi, v4hi) 6443long long __builtin_arm_wmacsz (v4hi, v4hi) 6444long long __builtin_arm_wmacu (long long, v4hi, v4hi) 6445long long __builtin_arm_wmacuz (v4hi, v4hi) 6446v4hi __builtin_arm_wmadds (v4hi, v4hi) 6447v4hi __builtin_arm_wmaddu (v4hi, v4hi) 6448v8qi __builtin_arm_wmaxsb (v8qi, v8qi) 6449v4hi __builtin_arm_wmaxsh (v4hi, v4hi) 6450v2si __builtin_arm_wmaxsw (v2si, v2si) 6451v8qi __builtin_arm_wmaxub (v8qi, v8qi) 6452v4hi __builtin_arm_wmaxuh (v4hi, v4hi) 6453v2si __builtin_arm_wmaxuw (v2si, v2si) 6454v8qi __builtin_arm_wminsb (v8qi, v8qi) 6455v4hi __builtin_arm_wminsh (v4hi, v4hi) 6456v2si __builtin_arm_wminsw (v2si, v2si) 6457v8qi __builtin_arm_wminub (v8qi, v8qi) 6458v4hi __builtin_arm_wminuh (v4hi, v4hi) 6459v2si __builtin_arm_wminuw (v2si, v2si) 6460v4hi __builtin_arm_wmulsm (v4hi, v4hi) 6461v4hi __builtin_arm_wmulul (v4hi, v4hi) 6462v4hi __builtin_arm_wmulum (v4hi, v4hi) 6463long long __builtin_arm_wor (long long, long long) 6464v2si __builtin_arm_wpackdss (long long, long long) 6465v2si __builtin_arm_wpackdus (long long, long long) 6466v8qi __builtin_arm_wpackhss (v4hi, v4hi) 6467v8qi __builtin_arm_wpackhus (v4hi, v4hi) 6468v4hi __builtin_arm_wpackwss (v2si, v2si) 6469v4hi __builtin_arm_wpackwus (v2si, v2si) 6470long long __builtin_arm_wrord (long long, long long) 6471long long __builtin_arm_wrordi (long long, int) 6472v4hi __builtin_arm_wrorh (v4hi, long long) 6473v4hi __builtin_arm_wrorhi (v4hi, int) 6474v2si __builtin_arm_wrorw (v2si, long long) 6475v2si __builtin_arm_wrorwi (v2si, int) 6476v2si __builtin_arm_wsadb (v8qi, v8qi) 6477v2si __builtin_arm_wsadbz (v8qi, v8qi) 6478v2si __builtin_arm_wsadh (v4hi, v4hi) 6479v2si __builtin_arm_wsadhz (v4hi, v4hi) 6480v4hi __builtin_arm_wshufh (v4hi, int) 6481long long __builtin_arm_wslld (long long, long long) 6482long long __builtin_arm_wslldi (long long, int) 6483v4hi __builtin_arm_wsllh (v4hi, long long) 6484v4hi __builtin_arm_wsllhi (v4hi, int) 6485v2si __builtin_arm_wsllw (v2si, long long) 6486v2si __builtin_arm_wsllwi (v2si, int) 6487long long __builtin_arm_wsrad (long long, long long) 6488long long __builtin_arm_wsradi (long long, int) 6489v4hi __builtin_arm_wsrah (v4hi, long long) 6490v4hi __builtin_arm_wsrahi (v4hi, int) 6491v2si __builtin_arm_wsraw (v2si, long long) 6492v2si __builtin_arm_wsrawi (v2si, int) 6493long long __builtin_arm_wsrld (long long, long long) 6494long long __builtin_arm_wsrldi (long long, int) 6495v4hi __builtin_arm_wsrlh (v4hi, long long) 6496v4hi __builtin_arm_wsrlhi (v4hi, int) 6497v2si __builtin_arm_wsrlw (v2si, long long) 6498v2si __builtin_arm_wsrlwi (v2si, int) 6499v8qi __builtin_arm_wsubb (v8qi, v8qi) 6500v8qi __builtin_arm_wsubbss (v8qi, v8qi) 6501v8qi __builtin_arm_wsubbus (v8qi, v8qi) 6502v4hi __builtin_arm_wsubh (v4hi, v4hi) 6503v4hi __builtin_arm_wsubhss (v4hi, v4hi) 6504v4hi __builtin_arm_wsubhus (v4hi, v4hi) 6505v2si __builtin_arm_wsubw (v2si, v2si) 6506v2si __builtin_arm_wsubwss (v2si, v2si) 6507v2si __builtin_arm_wsubwus (v2si, v2si) 6508v4hi __builtin_arm_wunpckehsb (v8qi) 6509v2si __builtin_arm_wunpckehsh (v4hi) 6510long long __builtin_arm_wunpckehsw (v2si) 6511v4hi __builtin_arm_wunpckehub (v8qi) 6512v2si __builtin_arm_wunpckehuh (v4hi) 6513long long __builtin_arm_wunpckehuw (v2si) 6514v4hi __builtin_arm_wunpckelsb (v8qi) 6515v2si __builtin_arm_wunpckelsh (v4hi) 6516long long __builtin_arm_wunpckelsw (v2si) 6517v4hi __builtin_arm_wunpckelub (v8qi) 6518v2si __builtin_arm_wunpckeluh (v4hi) 6519long long __builtin_arm_wunpckeluw (v2si) 6520v8qi __builtin_arm_wunpckihb (v8qi, v8qi) 6521v4hi __builtin_arm_wunpckihh (v4hi, v4hi) 6522v2si __builtin_arm_wunpckihw (v2si, v2si) 6523v8qi __builtin_arm_wunpckilb (v8qi, v8qi) 6524v4hi __builtin_arm_wunpckilh (v4hi, v4hi) 6525v2si __builtin_arm_wunpckilw (v2si, v2si) 6526long long __builtin_arm_wxor (long long, long long) 6527long long __builtin_arm_wzero () 6528@end smallexample 6529 6530@node Blackfin Built-in Functions 6531@subsection Blackfin Built-in Functions 6532 6533Currently, there are two Blackfin-specific built-in functions. These are 6534used for generating @code{CSYNC} and @code{SSYNC} machine insns without 6535using inline assembly; by using these built-in functions the compiler can 6536automatically add workarounds for hardware errata involving these 6537instructions. These functions are named as follows: 6538 6539@smallexample 6540void __builtin_bfin_csync (void) 6541void __builtin_bfin_ssync (void) 6542@end smallexample 6543 6544@node FR-V Built-in Functions 6545@subsection FR-V Built-in Functions 6546 6547GCC provides many FR-V-specific built-in functions. In general, 6548these functions are intended to be compatible with those described 6549by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu 6550Semiconductor}. The two exceptions are @code{__MDUNPACKH} and 6551@code{__MBTOHE}, the gcc forms of which pass 128-bit values by 6552pointer rather than by value. 6553 6554Most of the functions are named after specific FR-V instructions. 6555Such functions are said to be ``directly mapped'' and are summarized 6556here in tabular form. 6557 6558@menu 6559* Argument Types:: 6560* Directly-mapped Integer Functions:: 6561* Directly-mapped Media Functions:: 6562* Raw read/write Functions:: 6563* Other Built-in Functions:: 6564@end menu 6565 6566@node Argument Types 6567@subsubsection Argument Types 6568 6569The arguments to the built-in functions can be divided into three groups: 6570register numbers, compile-time constants and run-time values. In order 6571to make this classification clear at a glance, the arguments and return 6572values are given the following pseudo types: 6573 6574@multitable @columnfractions .20 .30 .15 .35 6575@item Pseudo type @tab Real C type @tab Constant? @tab Description 6576@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword 6577@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word 6578@item @code{sw1} @tab @code{int} @tab No @tab a signed word 6579@item @code{uw2} @tab @code{unsigned long long} @tab No 6580@tab an unsigned doubleword 6581@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword 6582@item @code{const} @tab @code{int} @tab Yes @tab an integer constant 6583@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number 6584@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number 6585@end multitable 6586 6587These pseudo types are not defined by GCC, they are simply a notational 6588convenience used in this manual. 6589 6590Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} 6591and @code{sw2} are evaluated at run time. They correspond to 6592register operands in the underlying FR-V instructions. 6593 6594@code{const} arguments represent immediate operands in the underlying 6595FR-V instructions. They must be compile-time constants. 6596 6597@code{acc} arguments are evaluated at compile time and specify the number 6598of an accumulator register. For example, an @code{acc} argument of 2 6599will select the ACC2 register. 6600 6601@code{iacc} arguments are similar to @code{acc} arguments but specify the 6602number of an IACC register. See @pxref{Other Built-in Functions} 6603for more details. 6604 6605@node Directly-mapped Integer Functions 6606@subsubsection Directly-mapped Integer Functions 6607 6608The functions listed below map directly to FR-V I-type instructions. 6609 6610@multitable @columnfractions .45 .32 .23 6611@item Function prototype @tab Example usage @tab Assembly output 6612@item @code{sw1 __ADDSS (sw1, sw1)} 6613@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} 6614@tab @code{ADDSS @var{a},@var{b},@var{c}} 6615@item @code{sw1 __SCAN (sw1, sw1)} 6616@tab @code{@var{c} = __SCAN (@var{a}, @var{b})} 6617@tab @code{SCAN @var{a},@var{b},@var{c}} 6618@item @code{sw1 __SCUTSS (sw1)} 6619@tab @code{@var{b} = __SCUTSS (@var{a})} 6620@tab @code{SCUTSS @var{a},@var{b}} 6621@item @code{sw1 __SLASS (sw1, sw1)} 6622@tab @code{@var{c} = __SLASS (@var{a}, @var{b})} 6623@tab @code{SLASS @var{a},@var{b},@var{c}} 6624@item @code{void __SMASS (sw1, sw1)} 6625@tab @code{__SMASS (@var{a}, @var{b})} 6626@tab @code{SMASS @var{a},@var{b}} 6627@item @code{void __SMSSS (sw1, sw1)} 6628@tab @code{__SMSSS (@var{a}, @var{b})} 6629@tab @code{SMSSS @var{a},@var{b}} 6630@item @code{void __SMU (sw1, sw1)} 6631@tab @code{__SMU (@var{a}, @var{b})} 6632@tab @code{SMU @var{a},@var{b}} 6633@item @code{sw2 __SMUL (sw1, sw1)} 6634@tab @code{@var{c} = __SMUL (@var{a}, @var{b})} 6635@tab @code{SMUL @var{a},@var{b},@var{c}} 6636@item @code{sw1 __SUBSS (sw1, sw1)} 6637@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} 6638@tab @code{SUBSS @var{a},@var{b},@var{c}} 6639@item @code{uw2 __UMUL (uw1, uw1)} 6640@tab @code{@var{c} = __UMUL (@var{a}, @var{b})} 6641@tab @code{UMUL @var{a},@var{b},@var{c}} 6642@end multitable 6643 6644@node Directly-mapped Media Functions 6645@subsubsection Directly-mapped Media Functions 6646 6647The functions listed below map directly to FR-V M-type instructions. 6648 6649@multitable @columnfractions .45 .32 .23 6650@item Function prototype @tab Example usage @tab Assembly output 6651@item @code{uw1 __MABSHS (sw1)} 6652@tab @code{@var{b} = __MABSHS (@var{a})} 6653@tab @code{MABSHS @var{a},@var{b}} 6654@item @code{void __MADDACCS (acc, acc)} 6655@tab @code{__MADDACCS (@var{b}, @var{a})} 6656@tab @code{MADDACCS @var{a},@var{b}} 6657@item @code{sw1 __MADDHSS (sw1, sw1)} 6658@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} 6659@tab @code{MADDHSS @var{a},@var{b},@var{c}} 6660@item @code{uw1 __MADDHUS (uw1, uw1)} 6661@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} 6662@tab @code{MADDHUS @var{a},@var{b},@var{c}} 6663@item @code{uw1 __MAND (uw1, uw1)} 6664@tab @code{@var{c} = __MAND (@var{a}, @var{b})} 6665@tab @code{MAND @var{a},@var{b},@var{c}} 6666@item @code{void __MASACCS (acc, acc)} 6667@tab @code{__MASACCS (@var{b}, @var{a})} 6668@tab @code{MASACCS @var{a},@var{b}} 6669@item @code{uw1 __MAVEH (uw1, uw1)} 6670@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} 6671@tab @code{MAVEH @var{a},@var{b},@var{c}} 6672@item @code{uw2 __MBTOH (uw1)} 6673@tab @code{@var{b} = __MBTOH (@var{a})} 6674@tab @code{MBTOH @var{a},@var{b}} 6675@item @code{void __MBTOHE (uw1 *, uw1)} 6676@tab @code{__MBTOHE (&@var{b}, @var{a})} 6677@tab @code{MBTOHE @var{a},@var{b}} 6678@item @code{void __MCLRACC (acc)} 6679@tab @code{__MCLRACC (@var{a})} 6680@tab @code{MCLRACC @var{a}} 6681@item @code{void __MCLRACCA (void)} 6682@tab @code{__MCLRACCA ()} 6683@tab @code{MCLRACCA} 6684@item @code{uw1 __Mcop1 (uw1, uw1)} 6685@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} 6686@tab @code{Mcop1 @var{a},@var{b},@var{c}} 6687@item @code{uw1 __Mcop2 (uw1, uw1)} 6688@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} 6689@tab @code{Mcop2 @var{a},@var{b},@var{c}} 6690@item @code{uw1 __MCPLHI (uw2, const)} 6691@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} 6692@tab @code{MCPLHI @var{a},#@var{b},@var{c}} 6693@item @code{uw1 __MCPLI (uw2, const)} 6694@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} 6695@tab @code{MCPLI @var{a},#@var{b},@var{c}} 6696@item @code{void __MCPXIS (acc, sw1, sw1)} 6697@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} 6698@tab @code{MCPXIS @var{a},@var{b},@var{c}} 6699@item @code{void __MCPXIU (acc, uw1, uw1)} 6700@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} 6701@tab @code{MCPXIU @var{a},@var{b},@var{c}} 6702@item @code{void __MCPXRS (acc, sw1, sw1)} 6703@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} 6704@tab @code{MCPXRS @var{a},@var{b},@var{c}} 6705@item @code{void __MCPXRU (acc, uw1, uw1)} 6706@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} 6707@tab @code{MCPXRU @var{a},@var{b},@var{c}} 6708@item @code{uw1 __MCUT (acc, uw1)} 6709@tab @code{@var{c} = __MCUT (@var{a}, @var{b})} 6710@tab @code{MCUT @var{a},@var{b},@var{c}} 6711@item @code{uw1 __MCUTSS (acc, sw1)} 6712@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} 6713@tab @code{MCUTSS @var{a},@var{b},@var{c}} 6714@item @code{void __MDADDACCS (acc, acc)} 6715@tab @code{__MDADDACCS (@var{b}, @var{a})} 6716@tab @code{MDADDACCS @var{a},@var{b}} 6717@item @code{void __MDASACCS (acc, acc)} 6718@tab @code{__MDASACCS (@var{b}, @var{a})} 6719@tab @code{MDASACCS @var{a},@var{b}} 6720@item @code{uw2 __MDCUTSSI (acc, const)} 6721@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} 6722@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} 6723@item @code{uw2 __MDPACKH (uw2, uw2)} 6724@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} 6725@tab @code{MDPACKH @var{a},@var{b},@var{c}} 6726@item @code{uw2 __MDROTLI (uw2, const)} 6727@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} 6728@tab @code{MDROTLI @var{a},#@var{b},@var{c}} 6729@item @code{void __MDSUBACCS (acc, acc)} 6730@tab @code{__MDSUBACCS (@var{b}, @var{a})} 6731@tab @code{MDSUBACCS @var{a},@var{b}} 6732@item @code{void __MDUNPACKH (uw1 *, uw2)} 6733@tab @code{__MDUNPACKH (&@var{b}, @var{a})} 6734@tab @code{MDUNPACKH @var{a},@var{b}} 6735@item @code{uw2 __MEXPDHD (uw1, const)} 6736@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} 6737@tab @code{MEXPDHD @var{a},#@var{b},@var{c}} 6738@item @code{uw1 __MEXPDHW (uw1, const)} 6739@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} 6740@tab @code{MEXPDHW @var{a},#@var{b},@var{c}} 6741@item @code{uw1 __MHDSETH (uw1, const)} 6742@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} 6743@tab @code{MHDSETH @var{a},#@var{b},@var{c}} 6744@item @code{sw1 __MHDSETS (const)} 6745@tab @code{@var{b} = __MHDSETS (@var{a})} 6746@tab @code{MHDSETS #@var{a},@var{b}} 6747@item @code{uw1 __MHSETHIH (uw1, const)} 6748@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} 6749@tab @code{MHSETHIH #@var{a},@var{b}} 6750@item @code{sw1 __MHSETHIS (sw1, const)} 6751@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} 6752@tab @code{MHSETHIS #@var{a},@var{b}} 6753@item @code{uw1 __MHSETLOH (uw1, const)} 6754@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} 6755@tab @code{MHSETLOH #@var{a},@var{b}} 6756@item @code{sw1 __MHSETLOS (sw1, const)} 6757@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} 6758@tab @code{MHSETLOS #@var{a},@var{b}} 6759@item @code{uw1 __MHTOB (uw2)} 6760@tab @code{@var{b} = __MHTOB (@var{a})} 6761@tab @code{MHTOB @var{a},@var{b}} 6762@item @code{void __MMACHS (acc, sw1, sw1)} 6763@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} 6764@tab @code{MMACHS @var{a},@var{b},@var{c}} 6765@item @code{void __MMACHU (acc, uw1, uw1)} 6766@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} 6767@tab @code{MMACHU @var{a},@var{b},@var{c}} 6768@item @code{void __MMRDHS (acc, sw1, sw1)} 6769@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} 6770@tab @code{MMRDHS @var{a},@var{b},@var{c}} 6771@item @code{void __MMRDHU (acc, uw1, uw1)} 6772@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} 6773@tab @code{MMRDHU @var{a},@var{b},@var{c}} 6774@item @code{void __MMULHS (acc, sw1, sw1)} 6775@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} 6776@tab @code{MMULHS @var{a},@var{b},@var{c}} 6777@item @code{void __MMULHU (acc, uw1, uw1)} 6778@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} 6779@tab @code{MMULHU @var{a},@var{b},@var{c}} 6780@item @code{void __MMULXHS (acc, sw1, sw1)} 6781@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} 6782@tab @code{MMULXHS @var{a},@var{b},@var{c}} 6783@item @code{void __MMULXHU (acc, uw1, uw1)} 6784@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} 6785@tab @code{MMULXHU @var{a},@var{b},@var{c}} 6786@item @code{uw1 __MNOT (uw1)} 6787@tab @code{@var{b} = __MNOT (@var{a})} 6788@tab @code{MNOT @var{a},@var{b}} 6789@item @code{uw1 __MOR (uw1, uw1)} 6790@tab @code{@var{c} = __MOR (@var{a}, @var{b})} 6791@tab @code{MOR @var{a},@var{b},@var{c}} 6792@item @code{uw1 __MPACKH (uh, uh)} 6793@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} 6794@tab @code{MPACKH @var{a},@var{b},@var{c}} 6795@item @code{sw2 __MQADDHSS (sw2, sw2)} 6796@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} 6797@tab @code{MQADDHSS @var{a},@var{b},@var{c}} 6798@item @code{uw2 __MQADDHUS (uw2, uw2)} 6799@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} 6800@tab @code{MQADDHUS @var{a},@var{b},@var{c}} 6801@item @code{void __MQCPXIS (acc, sw2, sw2)} 6802@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} 6803@tab @code{MQCPXIS @var{a},@var{b},@var{c}} 6804@item @code{void __MQCPXIU (acc, uw2, uw2)} 6805@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} 6806@tab @code{MQCPXIU @var{a},@var{b},@var{c}} 6807@item @code{void __MQCPXRS (acc, sw2, sw2)} 6808@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} 6809@tab @code{MQCPXRS @var{a},@var{b},@var{c}} 6810@item @code{void __MQCPXRU (acc, uw2, uw2)} 6811@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} 6812@tab @code{MQCPXRU @var{a},@var{b},@var{c}} 6813@item @code{sw2 __MQLCLRHS (sw2, sw2)} 6814@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} 6815@tab @code{MQLCLRHS @var{a},@var{b},@var{c}} 6816@item @code{sw2 __MQLMTHS (sw2, sw2)} 6817@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} 6818@tab @code{MQLMTHS @var{a},@var{b},@var{c}} 6819@item @code{void __MQMACHS (acc, sw2, sw2)} 6820@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} 6821@tab @code{MQMACHS @var{a},@var{b},@var{c}} 6822@item @code{void __MQMACHU (acc, uw2, uw2)} 6823@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} 6824@tab @code{MQMACHU @var{a},@var{b},@var{c}} 6825@item @code{void __MQMACXHS (acc, sw2, sw2)} 6826@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} 6827@tab @code{MQMACXHS @var{a},@var{b},@var{c}} 6828@item @code{void __MQMULHS (acc, sw2, sw2)} 6829@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} 6830@tab @code{MQMULHS @var{a},@var{b},@var{c}} 6831@item @code{void __MQMULHU (acc, uw2, uw2)} 6832@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} 6833@tab @code{MQMULHU @var{a},@var{b},@var{c}} 6834@item @code{void __MQMULXHS (acc, sw2, sw2)} 6835@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} 6836@tab @code{MQMULXHS @var{a},@var{b},@var{c}} 6837@item @code{void __MQMULXHU (acc, uw2, uw2)} 6838@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} 6839@tab @code{MQMULXHU @var{a},@var{b},@var{c}} 6840@item @code{sw2 __MQSATHS (sw2, sw2)} 6841@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} 6842@tab @code{MQSATHS @var{a},@var{b},@var{c}} 6843@item @code{uw2 __MQSLLHI (uw2, int)} 6844@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} 6845@tab @code{MQSLLHI @var{a},@var{b},@var{c}} 6846@item @code{sw2 __MQSRAHI (sw2, int)} 6847@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} 6848@tab @code{MQSRAHI @var{a},@var{b},@var{c}} 6849@item @code{sw2 __MQSUBHSS (sw2, sw2)} 6850@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} 6851@tab @code{MQSUBHSS @var{a},@var{b},@var{c}} 6852@item @code{uw2 __MQSUBHUS (uw2, uw2)} 6853@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} 6854@tab @code{MQSUBHUS @var{a},@var{b},@var{c}} 6855@item @code{void __MQXMACHS (acc, sw2, sw2)} 6856@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} 6857@tab @code{MQXMACHS @var{a},@var{b},@var{c}} 6858@item @code{void __MQXMACXHS (acc, sw2, sw2)} 6859@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} 6860@tab @code{MQXMACXHS @var{a},@var{b},@var{c}} 6861@item @code{uw1 __MRDACC (acc)} 6862@tab @code{@var{b} = __MRDACC (@var{a})} 6863@tab @code{MRDACC @var{a},@var{b}} 6864@item @code{uw1 __MRDACCG (acc)} 6865@tab @code{@var{b} = __MRDACCG (@var{a})} 6866@tab @code{MRDACCG @var{a},@var{b}} 6867@item @code{uw1 __MROTLI (uw1, const)} 6868@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} 6869@tab @code{MROTLI @var{a},#@var{b},@var{c}} 6870@item @code{uw1 __MROTRI (uw1, const)} 6871@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} 6872@tab @code{MROTRI @var{a},#@var{b},@var{c}} 6873@item @code{sw1 __MSATHS (sw1, sw1)} 6874@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} 6875@tab @code{MSATHS @var{a},@var{b},@var{c}} 6876@item @code{uw1 __MSATHU (uw1, uw1)} 6877@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} 6878@tab @code{MSATHU @var{a},@var{b},@var{c}} 6879@item @code{uw1 __MSLLHI (uw1, const)} 6880@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} 6881@tab @code{MSLLHI @var{a},#@var{b},@var{c}} 6882@item @code{sw1 __MSRAHI (sw1, const)} 6883@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} 6884@tab @code{MSRAHI @var{a},#@var{b},@var{c}} 6885@item @code{uw1 __MSRLHI (uw1, const)} 6886@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} 6887@tab @code{MSRLHI @var{a},#@var{b},@var{c}} 6888@item @code{void __MSUBACCS (acc, acc)} 6889@tab @code{__MSUBACCS (@var{b}, @var{a})} 6890@tab @code{MSUBACCS @var{a},@var{b}} 6891@item @code{sw1 __MSUBHSS (sw1, sw1)} 6892@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} 6893@tab @code{MSUBHSS @var{a},@var{b},@var{c}} 6894@item @code{uw1 __MSUBHUS (uw1, uw1)} 6895@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} 6896@tab @code{MSUBHUS @var{a},@var{b},@var{c}} 6897@item @code{void __MTRAP (void)} 6898@tab @code{__MTRAP ()} 6899@tab @code{MTRAP} 6900@item @code{uw2 __MUNPACKH (uw1)} 6901@tab @code{@var{b} = __MUNPACKH (@var{a})} 6902@tab @code{MUNPACKH @var{a},@var{b}} 6903@item @code{uw1 __MWCUT (uw2, uw1)} 6904@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} 6905@tab @code{MWCUT @var{a},@var{b},@var{c}} 6906@item @code{void __MWTACC (acc, uw1)} 6907@tab @code{__MWTACC (@var{b}, @var{a})} 6908@tab @code{MWTACC @var{a},@var{b}} 6909@item @code{void __MWTACCG (acc, uw1)} 6910@tab @code{__MWTACCG (@var{b}, @var{a})} 6911@tab @code{MWTACCG @var{a},@var{b}} 6912@item @code{uw1 __MXOR (uw1, uw1)} 6913@tab @code{@var{c} = __MXOR (@var{a}, @var{b})} 6914@tab @code{MXOR @var{a},@var{b},@var{c}} 6915@end multitable 6916 6917@node Raw read/write Functions 6918@subsubsection Raw read/write Functions 6919 6920This sections describes built-in functions related to read and write 6921instructions to access memory. These functions generate 6922@code{membar} instructions to flush the I/O load and stores where 6923appropriate, as described in Fujitsu's manual described above. 6924 6925@table @code 6926 6927@item unsigned char __builtin_read8 (void *@var{data}) 6928@item unsigned short __builtin_read16 (void *@var{data}) 6929@item unsigned long __builtin_read32 (void *@var{data}) 6930@item unsigned long long __builtin_read64 (void *@var{data}) 6931 6932@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) 6933@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) 6934@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) 6935@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) 6936@end table 6937 6938@node Other Built-in Functions 6939@subsubsection Other Built-in Functions 6940 6941This section describes built-in functions that are not named after 6942a specific FR-V instruction. 6943 6944@table @code 6945@item sw2 __IACCreadll (iacc @var{reg}) 6946Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved 6947for future expansion and must be 0. 6948 6949@item sw1 __IACCreadl (iacc @var{reg}) 6950Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. 6951Other values of @var{reg} are rejected as invalid. 6952 6953@item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) 6954Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument 6955is reserved for future expansion and must be 0. 6956 6957@item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) 6958Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} 6959is 1. Other values of @var{reg} are rejected as invalid. 6960 6961@item void __data_prefetch0 (const void *@var{x}) 6962Use the @code{dcpl} instruction to load the contents of address @var{x} 6963into the data cache. 6964 6965@item void __data_prefetch (const void *@var{x}) 6966Use the @code{nldub} instruction to load the contents of address @var{x} 6967into the data cache. The instruction will be issued in slot I1@. 6968@end table 6969 6970@node X86 Built-in Functions 6971@subsection X86 Built-in Functions 6972 6973These built-in functions are available for the i386 and x86-64 family 6974of computers, depending on the command-line switches used. 6975 6976Note that, if you specify command-line switches such as @option{-msse}, 6977the compiler could use the extended instruction sets even if the built-ins 6978are not used explicitly in the program. For this reason, applications 6979which perform runtime CPU detection must compile separate files for each 6980supported architecture, using the appropriate flags. In particular, 6981the file containing the CPU detection code should be compiled without 6982these options. 6983 6984The following machine modes are available for use with MMX built-in functions 6985(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, 6986@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a 6987vector of eight 8-bit integers. Some of the built-in functions operate on 6988MMX registers as a whole 64-bit entity, these use @code{DI} as their mode. 6989 6990If 3Dnow extensions are enabled, @code{V2SF} is used as a mode for a vector 6991of two 32-bit floating point values. 6992 6993If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit 6994floating point values. Some instructions use a vector of four 32-bit 6995integers, these use @code{V4SI}. Finally, some instructions operate on an 6996entire vector register, interpreting it as a 128-bit integer, these use mode 6997@code{TI}. 6998 6999The following built-in functions are made available by @option{-mmmx}. 7000All of them generate the machine instruction that is part of the name. 7001 7002@smallexample 7003v8qi __builtin_ia32_paddb (v8qi, v8qi) 7004v4hi __builtin_ia32_paddw (v4hi, v4hi) 7005v2si __builtin_ia32_paddd (v2si, v2si) 7006v8qi __builtin_ia32_psubb (v8qi, v8qi) 7007v4hi __builtin_ia32_psubw (v4hi, v4hi) 7008v2si __builtin_ia32_psubd (v2si, v2si) 7009v8qi __builtin_ia32_paddsb (v8qi, v8qi) 7010v4hi __builtin_ia32_paddsw (v4hi, v4hi) 7011v8qi __builtin_ia32_psubsb (v8qi, v8qi) 7012v4hi __builtin_ia32_psubsw (v4hi, v4hi) 7013v8qi __builtin_ia32_paddusb (v8qi, v8qi) 7014v4hi __builtin_ia32_paddusw (v4hi, v4hi) 7015v8qi __builtin_ia32_psubusb (v8qi, v8qi) 7016v4hi __builtin_ia32_psubusw (v4hi, v4hi) 7017v4hi __builtin_ia32_pmullw (v4hi, v4hi) 7018v4hi __builtin_ia32_pmulhw (v4hi, v4hi) 7019di __builtin_ia32_pand (di, di) 7020di __builtin_ia32_pandn (di,di) 7021di __builtin_ia32_por (di, di) 7022di __builtin_ia32_pxor (di, di) 7023v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) 7024v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) 7025v2si __builtin_ia32_pcmpeqd (v2si, v2si) 7026v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) 7027v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) 7028v2si __builtin_ia32_pcmpgtd (v2si, v2si) 7029v8qi __builtin_ia32_punpckhbw (v8qi, v8qi) 7030v4hi __builtin_ia32_punpckhwd (v4hi, v4hi) 7031v2si __builtin_ia32_punpckhdq (v2si, v2si) 7032v8qi __builtin_ia32_punpcklbw (v8qi, v8qi) 7033v4hi __builtin_ia32_punpcklwd (v4hi, v4hi) 7034v2si __builtin_ia32_punpckldq (v2si, v2si) 7035v8qi __builtin_ia32_packsswb (v4hi, v4hi) 7036v4hi __builtin_ia32_packssdw (v2si, v2si) 7037v8qi __builtin_ia32_packuswb (v4hi, v4hi) 7038@end smallexample 7039 7040The following built-in functions are made available either with 7041@option{-msse}, or with a combination of @option{-m3dnow} and 7042@option{-march=athlon}. All of them generate the machine 7043instruction that is part of the name. 7044 7045@smallexample 7046v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) 7047v8qi __builtin_ia32_pavgb (v8qi, v8qi) 7048v4hi __builtin_ia32_pavgw (v4hi, v4hi) 7049v4hi __builtin_ia32_psadbw (v8qi, v8qi) 7050v8qi __builtin_ia32_pmaxub (v8qi, v8qi) 7051v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) 7052v8qi __builtin_ia32_pminub (v8qi, v8qi) 7053v4hi __builtin_ia32_pminsw (v4hi, v4hi) 7054int __builtin_ia32_pextrw (v4hi, int) 7055v4hi __builtin_ia32_pinsrw (v4hi, int, int) 7056int __builtin_ia32_pmovmskb (v8qi) 7057void __builtin_ia32_maskmovq (v8qi, v8qi, char *) 7058void __builtin_ia32_movntq (di *, di) 7059void __builtin_ia32_sfence (void) 7060@end smallexample 7061 7062The following built-in functions are available when @option{-msse} is used. 7063All of them generate the machine instruction that is part of the name. 7064 7065@smallexample 7066int __builtin_ia32_comieq (v4sf, v4sf) 7067int __builtin_ia32_comineq (v4sf, v4sf) 7068int __builtin_ia32_comilt (v4sf, v4sf) 7069int __builtin_ia32_comile (v4sf, v4sf) 7070int __builtin_ia32_comigt (v4sf, v4sf) 7071int __builtin_ia32_comige (v4sf, v4sf) 7072int __builtin_ia32_ucomieq (v4sf, v4sf) 7073int __builtin_ia32_ucomineq (v4sf, v4sf) 7074int __builtin_ia32_ucomilt (v4sf, v4sf) 7075int __builtin_ia32_ucomile (v4sf, v4sf) 7076int __builtin_ia32_ucomigt (v4sf, v4sf) 7077int __builtin_ia32_ucomige (v4sf, v4sf) 7078v4sf __builtin_ia32_addps (v4sf, v4sf) 7079v4sf __builtin_ia32_subps (v4sf, v4sf) 7080v4sf __builtin_ia32_mulps (v4sf, v4sf) 7081v4sf __builtin_ia32_divps (v4sf, v4sf) 7082v4sf __builtin_ia32_addss (v4sf, v4sf) 7083v4sf __builtin_ia32_subss (v4sf, v4sf) 7084v4sf __builtin_ia32_mulss (v4sf, v4sf) 7085v4sf __builtin_ia32_divss (v4sf, v4sf) 7086v4si __builtin_ia32_cmpeqps (v4sf, v4sf) 7087v4si __builtin_ia32_cmpltps (v4sf, v4sf) 7088v4si __builtin_ia32_cmpleps (v4sf, v4sf) 7089v4si __builtin_ia32_cmpgtps (v4sf, v4sf) 7090v4si __builtin_ia32_cmpgeps (v4sf, v4sf) 7091v4si __builtin_ia32_cmpunordps (v4sf, v4sf) 7092v4si __builtin_ia32_cmpneqps (v4sf, v4sf) 7093v4si __builtin_ia32_cmpnltps (v4sf, v4sf) 7094v4si __builtin_ia32_cmpnleps (v4sf, v4sf) 7095v4si __builtin_ia32_cmpngtps (v4sf, v4sf) 7096v4si __builtin_ia32_cmpngeps (v4sf, v4sf) 7097v4si __builtin_ia32_cmpordps (v4sf, v4sf) 7098v4si __builtin_ia32_cmpeqss (v4sf, v4sf) 7099v4si __builtin_ia32_cmpltss (v4sf, v4sf) 7100v4si __builtin_ia32_cmpless (v4sf, v4sf) 7101v4si __builtin_ia32_cmpunordss (v4sf, v4sf) 7102v4si __builtin_ia32_cmpneqss (v4sf, v4sf) 7103v4si __builtin_ia32_cmpnlts (v4sf, v4sf) 7104v4si __builtin_ia32_cmpnless (v4sf, v4sf) 7105v4si __builtin_ia32_cmpordss (v4sf, v4sf) 7106v4sf __builtin_ia32_maxps (v4sf, v4sf) 7107v4sf __builtin_ia32_maxss (v4sf, v4sf) 7108v4sf __builtin_ia32_minps (v4sf, v4sf) 7109v4sf __builtin_ia32_minss (v4sf, v4sf) 7110v4sf __builtin_ia32_andps (v4sf, v4sf) 7111v4sf __builtin_ia32_andnps (v4sf, v4sf) 7112v4sf __builtin_ia32_orps (v4sf, v4sf) 7113v4sf __builtin_ia32_xorps (v4sf, v4sf) 7114v4sf __builtin_ia32_movss (v4sf, v4sf) 7115v4sf __builtin_ia32_movhlps (v4sf, v4sf) 7116v4sf __builtin_ia32_movlhps (v4sf, v4sf) 7117v4sf __builtin_ia32_unpckhps (v4sf, v4sf) 7118v4sf __builtin_ia32_unpcklps (v4sf, v4sf) 7119v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) 7120v4sf __builtin_ia32_cvtsi2ss (v4sf, int) 7121v2si __builtin_ia32_cvtps2pi (v4sf) 7122int __builtin_ia32_cvtss2si (v4sf) 7123v2si __builtin_ia32_cvttps2pi (v4sf) 7124int __builtin_ia32_cvttss2si (v4sf) 7125v4sf __builtin_ia32_rcpps (v4sf) 7126v4sf __builtin_ia32_rsqrtps (v4sf) 7127v4sf __builtin_ia32_sqrtps (v4sf) 7128v4sf __builtin_ia32_rcpss (v4sf) 7129v4sf __builtin_ia32_rsqrtss (v4sf) 7130v4sf __builtin_ia32_sqrtss (v4sf) 7131v4sf __builtin_ia32_shufps (v4sf, v4sf, int) 7132void __builtin_ia32_movntps (float *, v4sf) 7133int __builtin_ia32_movmskps (v4sf) 7134@end smallexample 7135 7136The following built-in functions are available when @option{-msse} is used. 7137 7138@table @code 7139@item v4sf __builtin_ia32_loadaps (float *) 7140Generates the @code{movaps} machine instruction as a load from memory. 7141@item void __builtin_ia32_storeaps (float *, v4sf) 7142Generates the @code{movaps} machine instruction as a store to memory. 7143@item v4sf __builtin_ia32_loadups (float *) 7144Generates the @code{movups} machine instruction as a load from memory. 7145@item void __builtin_ia32_storeups (float *, v4sf) 7146Generates the @code{movups} machine instruction as a store to memory. 7147@item v4sf __builtin_ia32_loadsss (float *) 7148Generates the @code{movss} machine instruction as a load from memory. 7149@item void __builtin_ia32_storess (float *, v4sf) 7150Generates the @code{movss} machine instruction as a store to memory. 7151@item v4sf __builtin_ia32_loadhps (v4sf, v2si *) 7152Generates the @code{movhps} machine instruction as a load from memory. 7153@item v4sf __builtin_ia32_loadlps (v4sf, v2si *) 7154Generates the @code{movlps} machine instruction as a load from memory 7155@item void __builtin_ia32_storehps (v4sf, v2si *) 7156Generates the @code{movhps} machine instruction as a store to memory. 7157@item void __builtin_ia32_storelps (v4sf, v2si *) 7158Generates the @code{movlps} machine instruction as a store to memory. 7159@end table 7160 7161The following built-in functions are available when @option{-msse2} is used. 7162All of them generate the machine instruction that is part of the name. 7163 7164@smallexample 7165int __builtin_ia32_comisdeq (v2df, v2df) 7166int __builtin_ia32_comisdlt (v2df, v2df) 7167int __builtin_ia32_comisdle (v2df, v2df) 7168int __builtin_ia32_comisdgt (v2df, v2df) 7169int __builtin_ia32_comisdge (v2df, v2df) 7170int __builtin_ia32_comisdneq (v2df, v2df) 7171int __builtin_ia32_ucomisdeq (v2df, v2df) 7172int __builtin_ia32_ucomisdlt (v2df, v2df) 7173int __builtin_ia32_ucomisdle (v2df, v2df) 7174int __builtin_ia32_ucomisdgt (v2df, v2df) 7175int __builtin_ia32_ucomisdge (v2df, v2df) 7176int __builtin_ia32_ucomisdneq (v2df, v2df) 7177v2df __builtin_ia32_cmpeqpd (v2df, v2df) 7178v2df __builtin_ia32_cmpltpd (v2df, v2df) 7179v2df __builtin_ia32_cmplepd (v2df, v2df) 7180v2df __builtin_ia32_cmpgtpd (v2df, v2df) 7181v2df __builtin_ia32_cmpgepd (v2df, v2df) 7182v2df __builtin_ia32_cmpunordpd (v2df, v2df) 7183v2df __builtin_ia32_cmpneqpd (v2df, v2df) 7184v2df __builtin_ia32_cmpnltpd (v2df, v2df) 7185v2df __builtin_ia32_cmpnlepd (v2df, v2df) 7186v2df __builtin_ia32_cmpngtpd (v2df, v2df) 7187v2df __builtin_ia32_cmpngepd (v2df, v2df) 7188v2df __builtin_ia32_cmpordpd (v2df, v2df) 7189v2df __builtin_ia32_cmpeqsd (v2df, v2df) 7190v2df __builtin_ia32_cmpltsd (v2df, v2df) 7191v2df __builtin_ia32_cmplesd (v2df, v2df) 7192v2df __builtin_ia32_cmpunordsd (v2df, v2df) 7193v2df __builtin_ia32_cmpneqsd (v2df, v2df) 7194v2df __builtin_ia32_cmpnltsd (v2df, v2df) 7195v2df __builtin_ia32_cmpnlesd (v2df, v2df) 7196v2df __builtin_ia32_cmpordsd (v2df, v2df) 7197v2di __builtin_ia32_paddq (v2di, v2di) 7198v2di __builtin_ia32_psubq (v2di, v2di) 7199v2df __builtin_ia32_addpd (v2df, v2df) 7200v2df __builtin_ia32_subpd (v2df, v2df) 7201v2df __builtin_ia32_mulpd (v2df, v2df) 7202v2df __builtin_ia32_divpd (v2df, v2df) 7203v2df __builtin_ia32_addsd (v2df, v2df) 7204v2df __builtin_ia32_subsd (v2df, v2df) 7205v2df __builtin_ia32_mulsd (v2df, v2df) 7206v2df __builtin_ia32_divsd (v2df, v2df) 7207v2df __builtin_ia32_minpd (v2df, v2df) 7208v2df __builtin_ia32_maxpd (v2df, v2df) 7209v2df __builtin_ia32_minsd (v2df, v2df) 7210v2df __builtin_ia32_maxsd (v2df, v2df) 7211v2df __builtin_ia32_andpd (v2df, v2df) 7212v2df __builtin_ia32_andnpd (v2df, v2df) 7213v2df __builtin_ia32_orpd (v2df, v2df) 7214v2df __builtin_ia32_xorpd (v2df, v2df) 7215v2df __builtin_ia32_movsd (v2df, v2df) 7216v2df __builtin_ia32_unpckhpd (v2df, v2df) 7217v2df __builtin_ia32_unpcklpd (v2df, v2df) 7218v16qi __builtin_ia32_paddb128 (v16qi, v16qi) 7219v8hi __builtin_ia32_paddw128 (v8hi, v8hi) 7220v4si __builtin_ia32_paddd128 (v4si, v4si) 7221v2di __builtin_ia32_paddq128 (v2di, v2di) 7222v16qi __builtin_ia32_psubb128 (v16qi, v16qi) 7223v8hi __builtin_ia32_psubw128 (v8hi, v8hi) 7224v4si __builtin_ia32_psubd128 (v4si, v4si) 7225v2di __builtin_ia32_psubq128 (v2di, v2di) 7226v8hi __builtin_ia32_pmullw128 (v8hi, v8hi) 7227v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi) 7228v2di __builtin_ia32_pand128 (v2di, v2di) 7229v2di __builtin_ia32_pandn128 (v2di, v2di) 7230v2di __builtin_ia32_por128 (v2di, v2di) 7231v2di __builtin_ia32_pxor128 (v2di, v2di) 7232v16qi __builtin_ia32_pavgb128 (v16qi, v16qi) 7233v8hi __builtin_ia32_pavgw128 (v8hi, v8hi) 7234v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi) 7235v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi) 7236v4si __builtin_ia32_pcmpeqd128 (v4si, v4si) 7237v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi) 7238v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi) 7239v4si __builtin_ia32_pcmpgtd128 (v4si, v4si) 7240v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi) 7241v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi) 7242v16qi __builtin_ia32_pminub128 (v16qi, v16qi) 7243v8hi __builtin_ia32_pminsw128 (v8hi, v8hi) 7244v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi) 7245v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi) 7246v4si __builtin_ia32_punpckhdq128 (v4si, v4si) 7247v2di __builtin_ia32_punpckhqdq128 (v2di, v2di) 7248v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi) 7249v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi) 7250v4si __builtin_ia32_punpckldq128 (v4si, v4si) 7251v2di __builtin_ia32_punpcklqdq128 (v2di, v2di) 7252v16qi __builtin_ia32_packsswb128 (v16qi, v16qi) 7253v8hi __builtin_ia32_packssdw128 (v8hi, v8hi) 7254v16qi __builtin_ia32_packuswb128 (v16qi, v16qi) 7255v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi) 7256void __builtin_ia32_maskmovdqu (v16qi, v16qi) 7257v2df __builtin_ia32_loadupd (double *) 7258void __builtin_ia32_storeupd (double *, v2df) 7259v2df __builtin_ia32_loadhpd (v2df, double *) 7260v2df __builtin_ia32_loadlpd (v2df, double *) 7261int __builtin_ia32_movmskpd (v2df) 7262int __builtin_ia32_pmovmskb128 (v16qi) 7263void __builtin_ia32_movnti (int *, int) 7264void __builtin_ia32_movntpd (double *, v2df) 7265void __builtin_ia32_movntdq (v2df *, v2df) 7266v4si __builtin_ia32_pshufd (v4si, int) 7267v8hi __builtin_ia32_pshuflw (v8hi, int) 7268v8hi __builtin_ia32_pshufhw (v8hi, int) 7269v2di __builtin_ia32_psadbw128 (v16qi, v16qi) 7270v2df __builtin_ia32_sqrtpd (v2df) 7271v2df __builtin_ia32_sqrtsd (v2df) 7272v2df __builtin_ia32_shufpd (v2df, v2df, int) 7273v2df __builtin_ia32_cvtdq2pd (v4si) 7274v4sf __builtin_ia32_cvtdq2ps (v4si) 7275v4si __builtin_ia32_cvtpd2dq (v2df) 7276v2si __builtin_ia32_cvtpd2pi (v2df) 7277v4sf __builtin_ia32_cvtpd2ps (v2df) 7278v4si __builtin_ia32_cvttpd2dq (v2df) 7279v2si __builtin_ia32_cvttpd2pi (v2df) 7280v2df __builtin_ia32_cvtpi2pd (v2si) 7281int __builtin_ia32_cvtsd2si (v2df) 7282int __builtin_ia32_cvttsd2si (v2df) 7283long long __builtin_ia32_cvtsd2si64 (v2df) 7284long long __builtin_ia32_cvttsd2si64 (v2df) 7285v4si __builtin_ia32_cvtps2dq (v4sf) 7286v2df __builtin_ia32_cvtps2pd (v4sf) 7287v4si __builtin_ia32_cvttps2dq (v4sf) 7288v2df __builtin_ia32_cvtsi2sd (v2df, int) 7289v2df __builtin_ia32_cvtsi642sd (v2df, long long) 7290v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df) 7291v2df __builtin_ia32_cvtss2sd (v2df, v4sf) 7292void __builtin_ia32_clflush (const void *) 7293void __builtin_ia32_lfence (void) 7294void __builtin_ia32_mfence (void) 7295v16qi __builtin_ia32_loaddqu (const char *) 7296void __builtin_ia32_storedqu (char *, v16qi) 7297unsigned long long __builtin_ia32_pmuludq (v2si, v2si) 7298v2di __builtin_ia32_pmuludq128 (v4si, v4si) 7299v8hi __builtin_ia32_psllw128 (v8hi, v2di) 7300v4si __builtin_ia32_pslld128 (v4si, v2di) 7301v2di __builtin_ia32_psllq128 (v4si, v2di) 7302v8hi __builtin_ia32_psrlw128 (v8hi, v2di) 7303v4si __builtin_ia32_psrld128 (v4si, v2di) 7304v2di __builtin_ia32_psrlq128 (v2di, v2di) 7305v8hi __builtin_ia32_psraw128 (v8hi, v2di) 7306v4si __builtin_ia32_psrad128 (v4si, v2di) 7307v2di __builtin_ia32_pslldqi128 (v2di, int) 7308v8hi __builtin_ia32_psllwi128 (v8hi, int) 7309v4si __builtin_ia32_pslldi128 (v4si, int) 7310v2di __builtin_ia32_psllqi128 (v2di, int) 7311v2di __builtin_ia32_psrldqi128 (v2di, int) 7312v8hi __builtin_ia32_psrlwi128 (v8hi, int) 7313v4si __builtin_ia32_psrldi128 (v4si, int) 7314v2di __builtin_ia32_psrlqi128 (v2di, int) 7315v8hi __builtin_ia32_psrawi128 (v8hi, int) 7316v4si __builtin_ia32_psradi128 (v4si, int) 7317v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi) 7318@end smallexample 7319 7320The following built-in functions are available when @option{-msse3} is used. 7321All of them generate the machine instruction that is part of the name. 7322 7323@smallexample 7324v2df __builtin_ia32_addsubpd (v2df, v2df) 7325v4sf __builtin_ia32_addsubps (v4sf, v4sf) 7326v2df __builtin_ia32_haddpd (v2df, v2df) 7327v4sf __builtin_ia32_haddps (v4sf, v4sf) 7328v2df __builtin_ia32_hsubpd (v2df, v2df) 7329v4sf __builtin_ia32_hsubps (v4sf, v4sf) 7330v16qi __builtin_ia32_lddqu (char const *) 7331void __builtin_ia32_monitor (void *, unsigned int, unsigned int) 7332v2df __builtin_ia32_movddup (v2df) 7333v4sf __builtin_ia32_movshdup (v4sf) 7334v4sf __builtin_ia32_movsldup (v4sf) 7335void __builtin_ia32_mwait (unsigned int, unsigned int) 7336@end smallexample 7337 7338The following built-in functions are available when @option{-msse3} is used. 7339 7340@table @code 7341@item v2df __builtin_ia32_loadddup (double const *) 7342Generates the @code{movddup} machine instruction as a load from memory. 7343@end table 7344 7345The following built-in functions are available when @option{-mssse3} is used. 7346All of them generate the machine instruction that is part of the name 7347with MMX registers. 7348 7349@smallexample 7350v2si __builtin_ia32_phaddd (v2si, v2si) 7351v4hi __builtin_ia32_phaddw (v4hi, v4hi) 7352v4hi __builtin_ia32_phaddsw (v4hi, v4hi) 7353v2si __builtin_ia32_phsubd (v2si, v2si) 7354v4hi __builtin_ia32_phsubw (v4hi, v4hi) 7355v4hi __builtin_ia32_phsubsw (v4hi, v4hi) 7356v8qi __builtin_ia32_pmaddubsw (v8qi, v8qi) 7357v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi) 7358v8qi __builtin_ia32_pshufb (v8qi, v8qi) 7359v8qi __builtin_ia32_psignb (v8qi, v8qi) 7360v2si __builtin_ia32_psignd (v2si, v2si) 7361v4hi __builtin_ia32_psignw (v4hi, v4hi) 7362long long __builtin_ia32_palignr (long long, long long, int) 7363v8qi __builtin_ia32_pabsb (v8qi) 7364v2si __builtin_ia32_pabsd (v2si) 7365v4hi __builtin_ia32_pabsw (v4hi) 7366@end smallexample 7367 7368The following built-in functions are available when @option{-mssse3} is used. 7369All of them generate the machine instruction that is part of the name 7370with SSE registers. 7371 7372@smallexample 7373v4si __builtin_ia32_phaddd128 (v4si, v4si) 7374v8hi __builtin_ia32_phaddw128 (v8hi, v8hi) 7375v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi) 7376v4si __builtin_ia32_phsubd128 (v4si, v4si) 7377v8hi __builtin_ia32_phsubw128 (v8hi, v8hi) 7378v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi) 7379v16qi __builtin_ia32_pmaddubsw128 (v16qi, v16qi) 7380v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi) 7381v16qi __builtin_ia32_pshufb128 (v16qi, v16qi) 7382v16qi __builtin_ia32_psignb128 (v16qi, v16qi) 7383v4si __builtin_ia32_psignd128 (v4si, v4si) 7384v8hi __builtin_ia32_psignw128 (v8hi, v8hi) 7385v2di __builtin_ia32_palignr (v2di, v2di, int) 7386v16qi __builtin_ia32_pabsb128 (v16qi) 7387v4si __builtin_ia32_pabsd128 (v4si) 7388v8hi __builtin_ia32_pabsw128 (v8hi) 7389@end smallexample 7390 7391The following built-in functions are available when @option{-msse4a} is used. 7392 7393@smallexample 7394void _mm_stream_sd (double*,__m128d); 7395Generates the @code{movntsd} machine instruction. 7396void _mm_stream_ss (float*,__m128); 7397Generates the @code{movntss} machine instruction. 7398__m128i _mm_extract_si64 (__m128i, __m128i); 7399Generates the @code{extrq} machine instruction with only SSE register operands. 7400__m128i _mm_extracti_si64 (__m128i, int, int); 7401Generates the @code{extrq} machine instruction with SSE register and immediate operands. 7402__m128i _mm_insert_si64 (__m128i, __m128i); 7403Generates the @code{insertq} machine instruction with only SSE register operands. 7404__m128i _mm_inserti_si64 (__m128i, __m128i, int, int); 7405Generates the @code{insertq} machine instruction with SSE register and immediate operands. 7406@end smallexample 7407 7408The following built-in functions are available when @option{-m3dnow} is used. 7409All of them generate the machine instruction that is part of the name. 7410 7411@smallexample 7412void __builtin_ia32_femms (void) 7413v8qi __builtin_ia32_pavgusb (v8qi, v8qi) 7414v2si __builtin_ia32_pf2id (v2sf) 7415v2sf __builtin_ia32_pfacc (v2sf, v2sf) 7416v2sf __builtin_ia32_pfadd (v2sf, v2sf) 7417v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) 7418v2si __builtin_ia32_pfcmpge (v2sf, v2sf) 7419v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) 7420v2sf __builtin_ia32_pfmax (v2sf, v2sf) 7421v2sf __builtin_ia32_pfmin (v2sf, v2sf) 7422v2sf __builtin_ia32_pfmul (v2sf, v2sf) 7423v2sf __builtin_ia32_pfrcp (v2sf) 7424v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) 7425v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) 7426v2sf __builtin_ia32_pfrsqrt (v2sf) 7427v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf) 7428v2sf __builtin_ia32_pfsub (v2sf, v2sf) 7429v2sf __builtin_ia32_pfsubr (v2sf, v2sf) 7430v2sf __builtin_ia32_pi2fd (v2si) 7431v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) 7432@end smallexample 7433 7434The following built-in functions are available when both @option{-m3dnow} 7435and @option{-march=athlon} are used. All of them generate the machine 7436instruction that is part of the name. 7437 7438@smallexample 7439v2si __builtin_ia32_pf2iw (v2sf) 7440v2sf __builtin_ia32_pfnacc (v2sf, v2sf) 7441v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) 7442v2sf __builtin_ia32_pi2fw (v2si) 7443v2sf __builtin_ia32_pswapdsf (v2sf) 7444v2si __builtin_ia32_pswapdsi (v2si) 7445@end smallexample 7446 7447@node MIPS DSP Built-in Functions 7448@subsection MIPS DSP Built-in Functions 7449 7450The MIPS DSP Application-Specific Extension (ASE) includes new 7451instructions that are designed to improve the performance of DSP and 7452media applications. It provides instructions that operate on packed 74538-bit integer data, Q15 fractional data and Q31 fractional data. 7454 7455GCC supports MIPS DSP operations using both the generic 7456vector extensions (@pxref{Vector Extensions}) and a collection of 7457MIPS-specific built-in functions. Both kinds of support are 7458enabled by the @option{-mdsp} command-line option. 7459 7460At present, GCC only provides support for operations on 32-bit 7461vectors. The vector type associated with 8-bit integer data is 7462usually called @code{v4i8} and the vector type associated with Q15 is 7463usually called @code{v2q15}. They can be defined in C as follows: 7464 7465@smallexample 7466typedef char v4i8 __attribute__ ((vector_size(4))); 7467typedef short v2q15 __attribute__ ((vector_size(4))); 7468@end smallexample 7469 7470@code{v4i8} and @code{v2q15} values are initialized in the same way as 7471aggregates. For example: 7472 7473@smallexample 7474v4i8 a = @{1, 2, 3, 4@}; 7475v4i8 b; 7476b = (v4i8) @{5, 6, 7, 8@}; 7477 7478v2q15 c = @{0x0fcb, 0x3a75@}; 7479v2q15 d; 7480d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; 7481@end smallexample 7482 7483@emph{Note:} The CPU's endianness determines the order in which values 7484are packed. On little-endian targets, the first value is the least 7485significant and the last value is the most significant. The opposite 7486order applies to big-endian targets. For example, the code above will 7487set the lowest byte of @code{a} to @code{1} on little-endian targets 7488and @code{4} on big-endian targets. 7489 7490@emph{Note:} Q15 and Q31 values must be initialized with their integer 7491representation. As shown in this example, the integer representation 7492of a Q15 value can be obtained by multiplying the fractional value by 7493@code{0x1.0p15}. The equivalent for Q31 values is to multiply by 7494@code{0x1.0p31}. 7495 7496The table below lists the @code{v4i8} and @code{v2q15} operations for which 7497hardware support exists. @code{a} and @code{b} are @code{v4i8} values, 7498and @code{c} and @code{d} are @code{v2q15} values. 7499 7500@multitable @columnfractions .50 .50 7501@item C code @tab MIPS instruction 7502@item @code{a + b} @tab @code{addu.qb} 7503@item @code{c + d} @tab @code{addq.ph} 7504@item @code{a - b} @tab @code{subu.qb} 7505@item @code{c - d} @tab @code{subq.ph} 7506@end multitable 7507 7508It is easier to describe the DSP built-in functions if we first define 7509the following types: 7510 7511@smallexample 7512typedef int q31; 7513typedef int i32; 7514typedef long long a64; 7515@end smallexample 7516 7517@code{q31} and @code{i32} are actually the same as @code{int}, but we 7518use @code{q31} to indicate a Q31 fractional value and @code{i32} to 7519indicate a 32-bit integer value. Similarly, @code{a64} is the same as 7520@code{long long}, but we use @code{a64} to indicate values that will 7521be placed in one of the four DSP accumulators (@code{$ac0}, 7522@code{$ac1}, @code{$ac2} or @code{$ac3}). 7523 7524Also, some built-in functions prefer or require immediate numbers as 7525parameters, because the corresponding DSP instructions accept both immediate 7526numbers and register operands, or accept immediate numbers only. The 7527immediate parameters are listed as follows. 7528 7529@smallexample 7530imm0_7: 0 to 7. 7531imm0_15: 0 to 15. 7532imm0_31: 0 to 31. 7533imm0_63: 0 to 63. 7534imm0_255: 0 to 255. 7535imm_n32_31: -32 to 31. 7536imm_n512_511: -512 to 511. 7537@end smallexample 7538 7539The following built-in functions map directly to a particular MIPS DSP 7540instruction. Please refer to the architecture specification 7541for details on what each instruction does. 7542 7543@smallexample 7544v2q15 __builtin_mips_addq_ph (v2q15, v2q15) 7545v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) 7546q31 __builtin_mips_addq_s_w (q31, q31) 7547v4i8 __builtin_mips_addu_qb (v4i8, v4i8) 7548v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) 7549v2q15 __builtin_mips_subq_ph (v2q15, v2q15) 7550v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) 7551q31 __builtin_mips_subq_s_w (q31, q31) 7552v4i8 __builtin_mips_subu_qb (v4i8, v4i8) 7553v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) 7554i32 __builtin_mips_addsc (i32, i32) 7555i32 __builtin_mips_addwc (i32, i32) 7556i32 __builtin_mips_modsub (i32, i32) 7557i32 __builtin_mips_raddu_w_qb (v4i8) 7558v2q15 __builtin_mips_absq_s_ph (v2q15) 7559q31 __builtin_mips_absq_s_w (q31) 7560v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) 7561v2q15 __builtin_mips_precrq_ph_w (q31, q31) 7562v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) 7563v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) 7564q31 __builtin_mips_preceq_w_phl (v2q15) 7565q31 __builtin_mips_preceq_w_phr (v2q15) 7566v2q15 __builtin_mips_precequ_ph_qbl (v4i8) 7567v2q15 __builtin_mips_precequ_ph_qbr (v4i8) 7568v2q15 __builtin_mips_precequ_ph_qbla (v4i8) 7569v2q15 __builtin_mips_precequ_ph_qbra (v4i8) 7570v2q15 __builtin_mips_preceu_ph_qbl (v4i8) 7571v2q15 __builtin_mips_preceu_ph_qbr (v4i8) 7572v2q15 __builtin_mips_preceu_ph_qbla (v4i8) 7573v2q15 __builtin_mips_preceu_ph_qbra (v4i8) 7574v4i8 __builtin_mips_shll_qb (v4i8, imm0_7) 7575v4i8 __builtin_mips_shll_qb (v4i8, i32) 7576v2q15 __builtin_mips_shll_ph (v2q15, imm0_15) 7577v2q15 __builtin_mips_shll_ph (v2q15, i32) 7578v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) 7579v2q15 __builtin_mips_shll_s_ph (v2q15, i32) 7580q31 __builtin_mips_shll_s_w (q31, imm0_31) 7581q31 __builtin_mips_shll_s_w (q31, i32) 7582v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) 7583v4i8 __builtin_mips_shrl_qb (v4i8, i32) 7584v2q15 __builtin_mips_shra_ph (v2q15, imm0_15) 7585v2q15 __builtin_mips_shra_ph (v2q15, i32) 7586v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) 7587v2q15 __builtin_mips_shra_r_ph (v2q15, i32) 7588q31 __builtin_mips_shra_r_w (q31, imm0_31) 7589q31 __builtin_mips_shra_r_w (q31, i32) 7590v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) 7591v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) 7592v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) 7593q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) 7594q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) 7595a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) 7596a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) 7597a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) 7598a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) 7599a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) 7600a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) 7601a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) 7602a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) 7603a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) 7604a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) 7605a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) 7606a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) 7607a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) 7608i32 __builtin_mips_bitrev (i32) 7609i32 __builtin_mips_insv (i32, i32) 7610v4i8 __builtin_mips_repl_qb (imm0_255) 7611v4i8 __builtin_mips_repl_qb (i32) 7612v2q15 __builtin_mips_repl_ph (imm_n512_511) 7613v2q15 __builtin_mips_repl_ph (i32) 7614void __builtin_mips_cmpu_eq_qb (v4i8, v4i8) 7615void __builtin_mips_cmpu_lt_qb (v4i8, v4i8) 7616void __builtin_mips_cmpu_le_qb (v4i8, v4i8) 7617i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) 7618i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) 7619i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) 7620void __builtin_mips_cmp_eq_ph (v2q15, v2q15) 7621void __builtin_mips_cmp_lt_ph (v2q15, v2q15) 7622void __builtin_mips_cmp_le_ph (v2q15, v2q15) 7623v4i8 __builtin_mips_pick_qb (v4i8, v4i8) 7624v2q15 __builtin_mips_pick_ph (v2q15, v2q15) 7625v2q15 __builtin_mips_packrl_ph (v2q15, v2q15) 7626i32 __builtin_mips_extr_w (a64, imm0_31) 7627i32 __builtin_mips_extr_w (a64, i32) 7628i32 __builtin_mips_extr_r_w (a64, imm0_31) 7629i32 __builtin_mips_extr_s_h (a64, i32) 7630i32 __builtin_mips_extr_rs_w (a64, imm0_31) 7631i32 __builtin_mips_extr_rs_w (a64, i32) 7632i32 __builtin_mips_extr_s_h (a64, imm0_31) 7633i32 __builtin_mips_extr_r_w (a64, i32) 7634i32 __builtin_mips_extp (a64, imm0_31) 7635i32 __builtin_mips_extp (a64, i32) 7636i32 __builtin_mips_extpdp (a64, imm0_31) 7637i32 __builtin_mips_extpdp (a64, i32) 7638a64 __builtin_mips_shilo (a64, imm_n32_31) 7639a64 __builtin_mips_shilo (a64, i32) 7640a64 __builtin_mips_mthlip (a64, i32) 7641void __builtin_mips_wrdsp (i32, imm0_63) 7642i32 __builtin_mips_rddsp (imm0_63) 7643i32 __builtin_mips_lbux (void *, i32) 7644i32 __builtin_mips_lhx (void *, i32) 7645i32 __builtin_mips_lwx (void *, i32) 7646i32 __builtin_mips_bposge32 (void) 7647@end smallexample 7648 7649@node MIPS Paired-Single Support 7650@subsection MIPS Paired-Single Support 7651 7652The MIPS64 architecture includes a number of instructions that 7653operate on pairs of single-precision floating-point values. 7654Each pair is packed into a 64-bit floating-point register, 7655with one element being designated the ``upper half'' and 7656the other being designated the ``lower half''. 7657 7658GCC supports paired-single operations using both the generic 7659vector extensions (@pxref{Vector Extensions}) and a collection of 7660MIPS-specific built-in functions. Both kinds of support are 7661enabled by the @option{-mpaired-single} command-line option. 7662 7663The vector type associated with paired-single values is usually 7664called @code{v2sf}. It can be defined in C as follows: 7665 7666@smallexample 7667typedef float v2sf __attribute__ ((vector_size (8))); 7668@end smallexample 7669 7670@code{v2sf} values are initialized in the same way as aggregates. 7671For example: 7672 7673@smallexample 7674v2sf a = @{1.5, 9.1@}; 7675v2sf b; 7676float e, f; 7677b = (v2sf) @{e, f@}; 7678@end smallexample 7679 7680@emph{Note:} The CPU's endianness determines which value is stored in 7681the upper half of a register and which value is stored in the lower half. 7682On little-endian targets, the first value is the lower one and the second 7683value is the upper one. The opposite order applies to big-endian targets. 7684For example, the code above will set the lower half of @code{a} to 7685@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. 7686 7687@menu 7688* Paired-Single Arithmetic:: 7689* Paired-Single Built-in Functions:: 7690* MIPS-3D Built-in Functions:: 7691@end menu 7692 7693@node Paired-Single Arithmetic 7694@subsubsection Paired-Single Arithmetic 7695 7696The table below lists the @code{v2sf} operations for which hardware 7697support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} 7698values and @code{x} is an integral value. 7699 7700@multitable @columnfractions .50 .50 7701@item C code @tab MIPS instruction 7702@item @code{a + b} @tab @code{add.ps} 7703@item @code{a - b} @tab @code{sub.ps} 7704@item @code{-a} @tab @code{neg.ps} 7705@item @code{a * b} @tab @code{mul.ps} 7706@item @code{a * b + c} @tab @code{madd.ps} 7707@item @code{a * b - c} @tab @code{msub.ps} 7708@item @code{-(a * b + c)} @tab @code{nmadd.ps} 7709@item @code{-(a * b - c)} @tab @code{nmsub.ps} 7710@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} 7711@end multitable 7712 7713Note that the multiply-accumulate instructions can be disabled 7714using the command-line option @code{-mno-fused-madd}. 7715 7716@node Paired-Single Built-in Functions 7717@subsubsection Paired-Single Built-in Functions 7718 7719The following paired-single functions map directly to a particular 7720MIPS instruction. Please refer to the architecture specification 7721for details on what each instruction does. 7722 7723@table @code 7724@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) 7725Pair lower lower (@code{pll.ps}). 7726 7727@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) 7728Pair upper lower (@code{pul.ps}). 7729 7730@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) 7731Pair lower upper (@code{plu.ps}). 7732 7733@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) 7734Pair upper upper (@code{puu.ps}). 7735 7736@item v2sf __builtin_mips_cvt_ps_s (float, float) 7737Convert pair to paired single (@code{cvt.ps.s}). 7738 7739@item float __builtin_mips_cvt_s_pl (v2sf) 7740Convert pair lower to single (@code{cvt.s.pl}). 7741 7742@item float __builtin_mips_cvt_s_pu (v2sf) 7743Convert pair upper to single (@code{cvt.s.pu}). 7744 7745@item v2sf __builtin_mips_abs_ps (v2sf) 7746Absolute value (@code{abs.ps}). 7747 7748@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) 7749Align variable (@code{alnv.ps}). 7750 7751@emph{Note:} The value of the third parameter must be 0 or 4 7752modulo 8, otherwise the result will be unpredictable. Please read the 7753instruction description for details. 7754@end table 7755 7756The following multi-instruction functions are also available. 7757In each case, @var{cond} can be any of the 16 floating-point conditions: 7758@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 7759@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, 7760@code{lt}, @code{nge}, @code{le} or @code{ngt}. 7761 7762@table @code 7763@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7764@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7765Conditional move based on floating point comparison (@code{c.@var{cond}.ps}, 7766@code{movt.ps}/@code{movf.ps}). 7767 7768The @code{movt} functions return the value @var{x} computed by: 7769 7770@smallexample 7771c.@var{cond}.ps @var{cc},@var{a},@var{b} 7772mov.ps @var{x},@var{c} 7773movt.ps @var{x},@var{d},@var{cc} 7774@end smallexample 7775 7776The @code{movf} functions are similar but use @code{movf.ps} instead 7777of @code{movt.ps}. 7778 7779@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7780@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7781Comparison of two paired-single values (@code{c.@var{cond}.ps}, 7782@code{bc1t}/@code{bc1f}). 7783 7784These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 7785and return either the upper or lower half of the result. For example: 7786 7787@smallexample 7788v2sf a, b; 7789if (__builtin_mips_upper_c_eq_ps (a, b)) 7790 upper_halves_are_equal (); 7791else 7792 upper_halves_are_unequal (); 7793 7794if (__builtin_mips_lower_c_eq_ps (a, b)) 7795 lower_halves_are_equal (); 7796else 7797 lower_halves_are_unequal (); 7798@end smallexample 7799@end table 7800 7801@node MIPS-3D Built-in Functions 7802@subsubsection MIPS-3D Built-in Functions 7803 7804The MIPS-3D Application-Specific Extension (ASE) includes additional 7805paired-single instructions that are designed to improve the performance 7806of 3D graphics operations. Support for these instructions is controlled 7807by the @option{-mips3d} command-line option. 7808 7809The functions listed below map directly to a particular MIPS-3D 7810instruction. Please refer to the architecture specification for 7811more details on what each instruction does. 7812 7813@table @code 7814@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) 7815Reduction add (@code{addr.ps}). 7816 7817@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) 7818Reduction multiply (@code{mulr.ps}). 7819 7820@item v2sf __builtin_mips_cvt_pw_ps (v2sf) 7821Convert paired single to paired word (@code{cvt.pw.ps}). 7822 7823@item v2sf __builtin_mips_cvt_ps_pw (v2sf) 7824Convert paired word to paired single (@code{cvt.ps.pw}). 7825 7826@item float __builtin_mips_recip1_s (float) 7827@itemx double __builtin_mips_recip1_d (double) 7828@itemx v2sf __builtin_mips_recip1_ps (v2sf) 7829Reduced precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). 7830 7831@item float __builtin_mips_recip2_s (float, float) 7832@itemx double __builtin_mips_recip2_d (double, double) 7833@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) 7834Reduced precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). 7835 7836@item float __builtin_mips_rsqrt1_s (float) 7837@itemx double __builtin_mips_rsqrt1_d (double) 7838@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) 7839Reduced precision reciprocal square root (sequence step 1) 7840(@code{rsqrt1.@var{fmt}}). 7841 7842@item float __builtin_mips_rsqrt2_s (float, float) 7843@itemx double __builtin_mips_rsqrt2_d (double, double) 7844@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) 7845Reduced precision reciprocal square root (sequence step 2) 7846(@code{rsqrt2.@var{fmt}}). 7847@end table 7848 7849The following multi-instruction functions are also available. 7850In each case, @var{cond} can be any of the 16 floating-point conditions: 7851@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 7852@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 7853@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. 7854 7855@table @code 7856@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) 7857@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) 7858Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, 7859@code{bc1t}/@code{bc1f}). 7860 7861These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} 7862or @code{cabs.@var{cond}.d} and return the result as a boolean value. 7863For example: 7864 7865@smallexample 7866float a, b; 7867if (__builtin_mips_cabs_eq_s (a, b)) 7868 true (); 7869else 7870 false (); 7871@end smallexample 7872 7873@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7874@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7875Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, 7876@code{bc1t}/@code{bc1f}). 7877 7878These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} 7879and return either the upper or lower half of the result. For example: 7880 7881@smallexample 7882v2sf a, b; 7883if (__builtin_mips_upper_cabs_eq_ps (a, b)) 7884 upper_halves_are_equal (); 7885else 7886 upper_halves_are_unequal (); 7887 7888if (__builtin_mips_lower_cabs_eq_ps (a, b)) 7889 lower_halves_are_equal (); 7890else 7891 lower_halves_are_unequal (); 7892@end smallexample 7893 7894@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7895@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7896Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, 7897@code{movt.ps}/@code{movf.ps}). 7898 7899The @code{movt} functions return the value @var{x} computed by: 7900 7901@smallexample 7902cabs.@var{cond}.ps @var{cc},@var{a},@var{b} 7903mov.ps @var{x},@var{c} 7904movt.ps @var{x},@var{d},@var{cc} 7905@end smallexample 7906 7907The @code{movf} functions are similar but use @code{movf.ps} instead 7908of @code{movt.ps}. 7909 7910@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7911@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7912@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7913@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7914Comparison of two paired-single values 7915(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 7916@code{bc1any2t}/@code{bc1any2f}). 7917 7918These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 7919or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either 7920result is true and the @code{all} forms return true if both results are true. 7921For example: 7922 7923@smallexample 7924v2sf a, b; 7925if (__builtin_mips_any_c_eq_ps (a, b)) 7926 one_is_true (); 7927else 7928 both_are_false (); 7929 7930if (__builtin_mips_all_c_eq_ps (a, b)) 7931 both_are_true (); 7932else 7933 one_is_false (); 7934@end smallexample 7935 7936@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7937@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7938@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7939@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7940Comparison of four paired-single values 7941(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 7942@code{bc1any4t}/@code{bc1any4f}). 7943 7944These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} 7945to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. 7946The @code{any} forms return true if any of the four results are true 7947and the @code{all} forms return true if all four results are true. 7948For example: 7949 7950@smallexample 7951v2sf a, b, c, d; 7952if (__builtin_mips_any_c_eq_4s (a, b, c, d)) 7953 some_are_true (); 7954else 7955 all_are_false (); 7956 7957if (__builtin_mips_all_c_eq_4s (a, b, c, d)) 7958 all_are_true (); 7959else 7960 some_are_false (); 7961@end smallexample 7962@end table 7963 7964@node PowerPC AltiVec Built-in Functions 7965@subsection PowerPC AltiVec Built-in Functions 7966 7967GCC provides an interface for the PowerPC family of processors to access 7968the AltiVec operations described in Motorola's AltiVec Programming 7969Interface Manual. The interface is made available by including 7970@code{<altivec.h>} and using @option{-maltivec} and 7971@option{-mabi=altivec}. The interface supports the following vector 7972types. 7973 7974@smallexample 7975vector unsigned char 7976vector signed char 7977vector bool char 7978 7979vector unsigned short 7980vector signed short 7981vector bool short 7982vector pixel 7983 7984vector unsigned int 7985vector signed int 7986vector bool int 7987vector float 7988@end smallexample 7989 7990GCC's implementation of the high-level language interface available from 7991C and C++ code differs from Motorola's documentation in several ways. 7992 7993@itemize @bullet 7994 7995@item 7996A vector constant is a list of constant expressions within curly braces. 7997 7998@item 7999A vector initializer requires no cast if the vector constant is of the 8000same type as the variable it is initializing. 8001 8002@item 8003If @code{signed} or @code{unsigned} is omitted, the signedness of the 8004vector type is the default signedness of the base type. The default 8005varies depending on the operating system, so a portable program should 8006always specify the signedness. 8007 8008@item 8009Compiling with @option{-maltivec} adds keywords @code{__vector}, 8010@code{__pixel}, and @code{__bool}. Macros @option{vector}, 8011@code{pixel}, and @code{bool} are defined in @code{<altivec.h>} and can 8012be undefined. 8013 8014@item 8015GCC allows using a @code{typedef} name as the type specifier for a 8016vector type. 8017 8018@item 8019For C, overloaded functions are implemented with macros so the following 8020does not work: 8021 8022@smallexample 8023 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); 8024@end smallexample 8025 8026Since @code{vec_add} is a macro, the vector constant in the example 8027is treated as four separate arguments. Wrap the entire argument in 8028parentheses for this to work. 8029@end itemize 8030 8031@emph{Note:} Only the @code{<altivec.h>} interface is supported. 8032Internally, GCC uses built-in functions to achieve the functionality in 8033the aforementioned header file, but they are not supported and are 8034subject to change without notice. 8035 8036The following interfaces are supported for the generic and specific 8037AltiVec operations and the AltiVec predicates. In cases where there 8038is a direct mapping between generic and specific operations, only the 8039generic names are shown here, although the specific operations can also 8040be used. 8041 8042Arguments that are documented as @code{const int} require literal 8043integral values within the range required for that operation. 8044 8045@smallexample 8046vector signed char vec_abs (vector signed char); 8047vector signed short vec_abs (vector signed short); 8048vector signed int vec_abs (vector signed int); 8049vector float vec_abs (vector float); 8050 8051vector signed char vec_abss (vector signed char); 8052vector signed short vec_abss (vector signed short); 8053vector signed int vec_abss (vector signed int); 8054 8055vector signed char vec_add (vector bool char, vector signed char); 8056vector signed char vec_add (vector signed char, vector bool char); 8057vector signed char vec_add (vector signed char, vector signed char); 8058vector unsigned char vec_add (vector bool char, vector unsigned char); 8059vector unsigned char vec_add (vector unsigned char, vector bool char); 8060vector unsigned char vec_add (vector unsigned char, 8061 vector unsigned char); 8062vector signed short vec_add (vector bool short, vector signed short); 8063vector signed short vec_add (vector signed short, vector bool short); 8064vector signed short vec_add (vector signed short, vector signed short); 8065vector unsigned short vec_add (vector bool short, 8066 vector unsigned short); 8067vector unsigned short vec_add (vector unsigned short, 8068 vector bool short); 8069vector unsigned short vec_add (vector unsigned short, 8070 vector unsigned short); 8071vector signed int vec_add (vector bool int, vector signed int); 8072vector signed int vec_add (vector signed int, vector bool int); 8073vector signed int vec_add (vector signed int, vector signed int); 8074vector unsigned int vec_add (vector bool int, vector unsigned int); 8075vector unsigned int vec_add (vector unsigned int, vector bool int); 8076vector unsigned int vec_add (vector unsigned int, vector unsigned int); 8077vector float vec_add (vector float, vector float); 8078 8079vector float vec_vaddfp (vector float, vector float); 8080 8081vector signed int vec_vadduwm (vector bool int, vector signed int); 8082vector signed int vec_vadduwm (vector signed int, vector bool int); 8083vector signed int vec_vadduwm (vector signed int, vector signed int); 8084vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); 8085vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); 8086vector unsigned int vec_vadduwm (vector unsigned int, 8087 vector unsigned int); 8088 8089vector signed short vec_vadduhm (vector bool short, 8090 vector signed short); 8091vector signed short vec_vadduhm (vector signed short, 8092 vector bool short); 8093vector signed short vec_vadduhm (vector signed short, 8094 vector signed short); 8095vector unsigned short vec_vadduhm (vector bool short, 8096 vector unsigned short); 8097vector unsigned short vec_vadduhm (vector unsigned short, 8098 vector bool short); 8099vector unsigned short vec_vadduhm (vector unsigned short, 8100 vector unsigned short); 8101 8102vector signed char vec_vaddubm (vector bool char, vector signed char); 8103vector signed char vec_vaddubm (vector signed char, vector bool char); 8104vector signed char vec_vaddubm (vector signed char, vector signed char); 8105vector unsigned char vec_vaddubm (vector bool char, 8106 vector unsigned char); 8107vector unsigned char vec_vaddubm (vector unsigned char, 8108 vector bool char); 8109vector unsigned char vec_vaddubm (vector unsigned char, 8110 vector unsigned char); 8111 8112vector unsigned int vec_addc (vector unsigned int, vector unsigned int); 8113 8114vector unsigned char vec_adds (vector bool char, vector unsigned char); 8115vector unsigned char vec_adds (vector unsigned char, vector bool char); 8116vector unsigned char vec_adds (vector unsigned char, 8117 vector unsigned char); 8118vector signed char vec_adds (vector bool char, vector signed char); 8119vector signed char vec_adds (vector signed char, vector bool char); 8120vector signed char vec_adds (vector signed char, vector signed char); 8121vector unsigned short vec_adds (vector bool short, 8122 vector unsigned short); 8123vector unsigned short vec_adds (vector unsigned short, 8124 vector bool short); 8125vector unsigned short vec_adds (vector unsigned short, 8126 vector unsigned short); 8127vector signed short vec_adds (vector bool short, vector signed short); 8128vector signed short vec_adds (vector signed short, vector bool short); 8129vector signed short vec_adds (vector signed short, vector signed short); 8130vector unsigned int vec_adds (vector bool int, vector unsigned int); 8131vector unsigned int vec_adds (vector unsigned int, vector bool int); 8132vector unsigned int vec_adds (vector unsigned int, vector unsigned int); 8133vector signed int vec_adds (vector bool int, vector signed int); 8134vector signed int vec_adds (vector signed int, vector bool int); 8135vector signed int vec_adds (vector signed int, vector signed int); 8136 8137vector signed int vec_vaddsws (vector bool int, vector signed int); 8138vector signed int vec_vaddsws (vector signed int, vector bool int); 8139vector signed int vec_vaddsws (vector signed int, vector signed int); 8140 8141vector unsigned int vec_vadduws (vector bool int, vector unsigned int); 8142vector unsigned int vec_vadduws (vector unsigned int, vector bool int); 8143vector unsigned int vec_vadduws (vector unsigned int, 8144 vector unsigned int); 8145 8146vector signed short vec_vaddshs (vector bool short, 8147 vector signed short); 8148vector signed short vec_vaddshs (vector signed short, 8149 vector bool short); 8150vector signed short vec_vaddshs (vector signed short, 8151 vector signed short); 8152 8153vector unsigned short vec_vadduhs (vector bool short, 8154 vector unsigned short); 8155vector unsigned short vec_vadduhs (vector unsigned short, 8156 vector bool short); 8157vector unsigned short vec_vadduhs (vector unsigned short, 8158 vector unsigned short); 8159 8160vector signed char vec_vaddsbs (vector bool char, vector signed char); 8161vector signed char vec_vaddsbs (vector signed char, vector bool char); 8162vector signed char vec_vaddsbs (vector signed char, vector signed char); 8163 8164vector unsigned char vec_vaddubs (vector bool char, 8165 vector unsigned char); 8166vector unsigned char vec_vaddubs (vector unsigned char, 8167 vector bool char); 8168vector unsigned char vec_vaddubs (vector unsigned char, 8169 vector unsigned char); 8170 8171vector float vec_and (vector float, vector float); 8172vector float vec_and (vector float, vector bool int); 8173vector float vec_and (vector bool int, vector float); 8174vector bool int vec_and (vector bool int, vector bool int); 8175vector signed int vec_and (vector bool int, vector signed int); 8176vector signed int vec_and (vector signed int, vector bool int); 8177vector signed int vec_and (vector signed int, vector signed int); 8178vector unsigned int vec_and (vector bool int, vector unsigned int); 8179vector unsigned int vec_and (vector unsigned int, vector bool int); 8180vector unsigned int vec_and (vector unsigned int, vector unsigned int); 8181vector bool short vec_and (vector bool short, vector bool short); 8182vector signed short vec_and (vector bool short, vector signed short); 8183vector signed short vec_and (vector signed short, vector bool short); 8184vector signed short vec_and (vector signed short, vector signed short); 8185vector unsigned short vec_and (vector bool short, 8186 vector unsigned short); 8187vector unsigned short vec_and (vector unsigned short, 8188 vector bool short); 8189vector unsigned short vec_and (vector unsigned short, 8190 vector unsigned short); 8191vector signed char vec_and (vector bool char, vector signed char); 8192vector bool char vec_and (vector bool char, vector bool char); 8193vector signed char vec_and (vector signed char, vector bool char); 8194vector signed char vec_and (vector signed char, vector signed char); 8195vector unsigned char vec_and (vector bool char, vector unsigned char); 8196vector unsigned char vec_and (vector unsigned char, vector bool char); 8197vector unsigned char vec_and (vector unsigned char, 8198 vector unsigned char); 8199 8200vector float vec_andc (vector float, vector float); 8201vector float vec_andc (vector float, vector bool int); 8202vector float vec_andc (vector bool int, vector float); 8203vector bool int vec_andc (vector bool int, vector bool int); 8204vector signed int vec_andc (vector bool int, vector signed int); 8205vector signed int vec_andc (vector signed int, vector bool int); 8206vector signed int vec_andc (vector signed int, vector signed int); 8207vector unsigned int vec_andc (vector bool int, vector unsigned int); 8208vector unsigned int vec_andc (vector unsigned int, vector bool int); 8209vector unsigned int vec_andc (vector unsigned int, vector unsigned int); 8210vector bool short vec_andc (vector bool short, vector bool short); 8211vector signed short vec_andc (vector bool short, vector signed short); 8212vector signed short vec_andc (vector signed short, vector bool short); 8213vector signed short vec_andc (vector signed short, vector signed short); 8214vector unsigned short vec_andc (vector bool short, 8215 vector unsigned short); 8216vector unsigned short vec_andc (vector unsigned short, 8217 vector bool short); 8218vector unsigned short vec_andc (vector unsigned short, 8219 vector unsigned short); 8220vector signed char vec_andc (vector bool char, vector signed char); 8221vector bool char vec_andc (vector bool char, vector bool char); 8222vector signed char vec_andc (vector signed char, vector bool char); 8223vector signed char vec_andc (vector signed char, vector signed char); 8224vector unsigned char vec_andc (vector bool char, vector unsigned char); 8225vector unsigned char vec_andc (vector unsigned char, vector bool char); 8226vector unsigned char vec_andc (vector unsigned char, 8227 vector unsigned char); 8228 8229vector unsigned char vec_avg (vector unsigned char, 8230 vector unsigned char); 8231vector signed char vec_avg (vector signed char, vector signed char); 8232vector unsigned short vec_avg (vector unsigned short, 8233 vector unsigned short); 8234vector signed short vec_avg (vector signed short, vector signed short); 8235vector unsigned int vec_avg (vector unsigned int, vector unsigned int); 8236vector signed int vec_avg (vector signed int, vector signed int); 8237 8238vector signed int vec_vavgsw (vector signed int, vector signed int); 8239 8240vector unsigned int vec_vavguw (vector unsigned int, 8241 vector unsigned int); 8242 8243vector signed short vec_vavgsh (vector signed short, 8244 vector signed short); 8245 8246vector unsigned short vec_vavguh (vector unsigned short, 8247 vector unsigned short); 8248 8249vector signed char vec_vavgsb (vector signed char, vector signed char); 8250 8251vector unsigned char vec_vavgub (vector unsigned char, 8252 vector unsigned char); 8253 8254vector float vec_ceil (vector float); 8255 8256vector signed int vec_cmpb (vector float, vector float); 8257 8258vector bool char vec_cmpeq (vector signed char, vector signed char); 8259vector bool char vec_cmpeq (vector unsigned char, vector unsigned char); 8260vector bool short vec_cmpeq (vector signed short, vector signed short); 8261vector bool short vec_cmpeq (vector unsigned short, 8262 vector unsigned short); 8263vector bool int vec_cmpeq (vector signed int, vector signed int); 8264vector bool int vec_cmpeq (vector unsigned int, vector unsigned int); 8265vector bool int vec_cmpeq (vector float, vector float); 8266 8267vector bool int vec_vcmpeqfp (vector float, vector float); 8268 8269vector bool int vec_vcmpequw (vector signed int, vector signed int); 8270vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); 8271 8272vector bool short vec_vcmpequh (vector signed short, 8273 vector signed short); 8274vector bool short vec_vcmpequh (vector unsigned short, 8275 vector unsigned short); 8276 8277vector bool char vec_vcmpequb (vector signed char, vector signed char); 8278vector bool char vec_vcmpequb (vector unsigned char, 8279 vector unsigned char); 8280 8281vector bool int vec_cmpge (vector float, vector float); 8282 8283vector bool char vec_cmpgt (vector unsigned char, vector unsigned char); 8284vector bool char vec_cmpgt (vector signed char, vector signed char); 8285vector bool short vec_cmpgt (vector unsigned short, 8286 vector unsigned short); 8287vector bool short vec_cmpgt (vector signed short, vector signed short); 8288vector bool int vec_cmpgt (vector unsigned int, vector unsigned int); 8289vector bool int vec_cmpgt (vector signed int, vector signed int); 8290vector bool int vec_cmpgt (vector float, vector float); 8291 8292vector bool int vec_vcmpgtfp (vector float, vector float); 8293 8294vector bool int vec_vcmpgtsw (vector signed int, vector signed int); 8295 8296vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); 8297 8298vector bool short vec_vcmpgtsh (vector signed short, 8299 vector signed short); 8300 8301vector bool short vec_vcmpgtuh (vector unsigned short, 8302 vector unsigned short); 8303 8304vector bool char vec_vcmpgtsb (vector signed char, vector signed char); 8305 8306vector bool char vec_vcmpgtub (vector unsigned char, 8307 vector unsigned char); 8308 8309vector bool int vec_cmple (vector float, vector float); 8310 8311vector bool char vec_cmplt (vector unsigned char, vector unsigned char); 8312vector bool char vec_cmplt (vector signed char, vector signed char); 8313vector bool short vec_cmplt (vector unsigned short, 8314 vector unsigned short); 8315vector bool short vec_cmplt (vector signed short, vector signed short); 8316vector bool int vec_cmplt (vector unsigned int, vector unsigned int); 8317vector bool int vec_cmplt (vector signed int, vector signed int); 8318vector bool int vec_cmplt (vector float, vector float); 8319 8320vector float vec_ctf (vector unsigned int, const int); 8321vector float vec_ctf (vector signed int, const int); 8322 8323vector float vec_vcfsx (vector signed int, const int); 8324 8325vector float vec_vcfux (vector unsigned int, const int); 8326 8327vector signed int vec_cts (vector float, const int); 8328 8329vector unsigned int vec_ctu (vector float, const int); 8330 8331void vec_dss (const int); 8332 8333void vec_dssall (void); 8334 8335void vec_dst (const vector unsigned char *, int, const int); 8336void vec_dst (const vector signed char *, int, const int); 8337void vec_dst (const vector bool char *, int, const int); 8338void vec_dst (const vector unsigned short *, int, const int); 8339void vec_dst (const vector signed short *, int, const int); 8340void vec_dst (const vector bool short *, int, const int); 8341void vec_dst (const vector pixel *, int, const int); 8342void vec_dst (const vector unsigned int *, int, const int); 8343void vec_dst (const vector signed int *, int, const int); 8344void vec_dst (const vector bool int *, int, const int); 8345void vec_dst (const vector float *, int, const int); 8346void vec_dst (const unsigned char *, int, const int); 8347void vec_dst (const signed char *, int, const int); 8348void vec_dst (const unsigned short *, int, const int); 8349void vec_dst (const short *, int, const int); 8350void vec_dst (const unsigned int *, int, const int); 8351void vec_dst (const int *, int, const int); 8352void vec_dst (const unsigned long *, int, const int); 8353void vec_dst (const long *, int, const int); 8354void vec_dst (const float *, int, const int); 8355 8356void vec_dstst (const vector unsigned char *, int, const int); 8357void vec_dstst (const vector signed char *, int, const int); 8358void vec_dstst (const vector bool char *, int, const int); 8359void vec_dstst (const vector unsigned short *, int, const int); 8360void vec_dstst (const vector signed short *, int, const int); 8361void vec_dstst (const vector bool short *, int, const int); 8362void vec_dstst (const vector pixel *, int, const int); 8363void vec_dstst (const vector unsigned int *, int, const int); 8364void vec_dstst (const vector signed int *, int, const int); 8365void vec_dstst (const vector bool int *, int, const int); 8366void vec_dstst (const vector float *, int, const int); 8367void vec_dstst (const unsigned char *, int, const int); 8368void vec_dstst (const signed char *, int, const int); 8369void vec_dstst (const unsigned short *, int, const int); 8370void vec_dstst (const short *, int, const int); 8371void vec_dstst (const unsigned int *, int, const int); 8372void vec_dstst (const int *, int, const int); 8373void vec_dstst (const unsigned long *, int, const int); 8374void vec_dstst (const long *, int, const int); 8375void vec_dstst (const float *, int, const int); 8376 8377void vec_dststt (const vector unsigned char *, int, const int); 8378void vec_dststt (const vector signed char *, int, const int); 8379void vec_dststt (const vector bool char *, int, const int); 8380void vec_dststt (const vector unsigned short *, int, const int); 8381void vec_dststt (const vector signed short *, int, const int); 8382void vec_dststt (const vector bool short *, int, const int); 8383void vec_dststt (const vector pixel *, int, const int); 8384void vec_dststt (const vector unsigned int *, int, const int); 8385void vec_dststt (const vector signed int *, int, const int); 8386void vec_dststt (const vector bool int *, int, const int); 8387void vec_dststt (const vector float *, int, const int); 8388void vec_dststt (const unsigned char *, int, const int); 8389void vec_dststt (const signed char *, int, const int); 8390void vec_dststt (const unsigned short *, int, const int); 8391void vec_dststt (const short *, int, const int); 8392void vec_dststt (const unsigned int *, int, const int); 8393void vec_dststt (const int *, int, const int); 8394void vec_dststt (const unsigned long *, int, const int); 8395void vec_dststt (const long *, int, const int); 8396void vec_dststt (const float *, int, const int); 8397 8398void vec_dstt (const vector unsigned char *, int, const int); 8399void vec_dstt (const vector signed char *, int, const int); 8400void vec_dstt (const vector bool char *, int, const int); 8401void vec_dstt (const vector unsigned short *, int, const int); 8402void vec_dstt (const vector signed short *, int, const int); 8403void vec_dstt (const vector bool short *, int, const int); 8404void vec_dstt (const vector pixel *, int, const int); 8405void vec_dstt (const vector unsigned int *, int, const int); 8406void vec_dstt (const vector signed int *, int, const int); 8407void vec_dstt (const vector bool int *, int, const int); 8408void vec_dstt (const vector float *, int, const int); 8409void vec_dstt (const unsigned char *, int, const int); 8410void vec_dstt (const signed char *, int, const int); 8411void vec_dstt (const unsigned short *, int, const int); 8412void vec_dstt (const short *, int, const int); 8413void vec_dstt (const unsigned int *, int, const int); 8414void vec_dstt (const int *, int, const int); 8415void vec_dstt (const unsigned long *, int, const int); 8416void vec_dstt (const long *, int, const int); 8417void vec_dstt (const float *, int, const int); 8418 8419vector float vec_expte (vector float); 8420 8421vector float vec_floor (vector float); 8422 8423vector float vec_ld (int, const vector float *); 8424vector float vec_ld (int, const float *); 8425vector bool int vec_ld (int, const vector bool int *); 8426vector signed int vec_ld (int, const vector signed int *); 8427vector signed int vec_ld (int, const int *); 8428vector signed int vec_ld (int, const long *); 8429vector unsigned int vec_ld (int, const vector unsigned int *); 8430vector unsigned int vec_ld (int, const unsigned int *); 8431vector unsigned int vec_ld (int, const unsigned long *); 8432vector bool short vec_ld (int, const vector bool short *); 8433vector pixel vec_ld (int, const vector pixel *); 8434vector signed short vec_ld (int, const vector signed short *); 8435vector signed short vec_ld (int, const short *); 8436vector unsigned short vec_ld (int, const vector unsigned short *); 8437vector unsigned short vec_ld (int, const unsigned short *); 8438vector bool char vec_ld (int, const vector bool char *); 8439vector signed char vec_ld (int, const vector signed char *); 8440vector signed char vec_ld (int, const signed char *); 8441vector unsigned char vec_ld (int, const vector unsigned char *); 8442vector unsigned char vec_ld (int, const unsigned char *); 8443 8444vector signed char vec_lde (int, const signed char *); 8445vector unsigned char vec_lde (int, const unsigned char *); 8446vector signed short vec_lde (int, const short *); 8447vector unsigned short vec_lde (int, const unsigned short *); 8448vector float vec_lde (int, const float *); 8449vector signed int vec_lde (int, const int *); 8450vector unsigned int vec_lde (int, const unsigned int *); 8451vector signed int vec_lde (int, const long *); 8452vector unsigned int vec_lde (int, const unsigned long *); 8453 8454vector float vec_lvewx (int, float *); 8455vector signed int vec_lvewx (int, int *); 8456vector unsigned int vec_lvewx (int, unsigned int *); 8457vector signed int vec_lvewx (int, long *); 8458vector unsigned int vec_lvewx (int, unsigned long *); 8459 8460vector signed short vec_lvehx (int, short *); 8461vector unsigned short vec_lvehx (int, unsigned short *); 8462 8463vector signed char vec_lvebx (int, char *); 8464vector unsigned char vec_lvebx (int, unsigned char *); 8465 8466vector float vec_ldl (int, const vector float *); 8467vector float vec_ldl (int, const float *); 8468vector bool int vec_ldl (int, const vector bool int *); 8469vector signed int vec_ldl (int, const vector signed int *); 8470vector signed int vec_ldl (int, const int *); 8471vector signed int vec_ldl (int, const long *); 8472vector unsigned int vec_ldl (int, const vector unsigned int *); 8473vector unsigned int vec_ldl (int, const unsigned int *); 8474vector unsigned int vec_ldl (int, const unsigned long *); 8475vector bool short vec_ldl (int, const vector bool short *); 8476vector pixel vec_ldl (int, const vector pixel *); 8477vector signed short vec_ldl (int, const vector signed short *); 8478vector signed short vec_ldl (int, const short *); 8479vector unsigned short vec_ldl (int, const vector unsigned short *); 8480vector unsigned short vec_ldl (int, const unsigned short *); 8481vector bool char vec_ldl (int, const vector bool char *); 8482vector signed char vec_ldl (int, const vector signed char *); 8483vector signed char vec_ldl (int, const signed char *); 8484vector unsigned char vec_ldl (int, const vector unsigned char *); 8485vector unsigned char vec_ldl (int, const unsigned char *); 8486 8487vector float vec_loge (vector float); 8488 8489vector unsigned char vec_lvsl (int, const volatile unsigned char *); 8490vector unsigned char vec_lvsl (int, const volatile signed char *); 8491vector unsigned char vec_lvsl (int, const volatile unsigned short *); 8492vector unsigned char vec_lvsl (int, const volatile short *); 8493vector unsigned char vec_lvsl (int, const volatile unsigned int *); 8494vector unsigned char vec_lvsl (int, const volatile int *); 8495vector unsigned char vec_lvsl (int, const volatile unsigned long *); 8496vector unsigned char vec_lvsl (int, const volatile long *); 8497vector unsigned char vec_lvsl (int, const volatile float *); 8498 8499vector unsigned char vec_lvsr (int, const volatile unsigned char *); 8500vector unsigned char vec_lvsr (int, const volatile signed char *); 8501vector unsigned char vec_lvsr (int, const volatile unsigned short *); 8502vector unsigned char vec_lvsr (int, const volatile short *); 8503vector unsigned char vec_lvsr (int, const volatile unsigned int *); 8504vector unsigned char vec_lvsr (int, const volatile int *); 8505vector unsigned char vec_lvsr (int, const volatile unsigned long *); 8506vector unsigned char vec_lvsr (int, const volatile long *); 8507vector unsigned char vec_lvsr (int, const volatile float *); 8508 8509vector float vec_madd (vector float, vector float, vector float); 8510 8511vector signed short vec_madds (vector signed short, 8512 vector signed short, 8513 vector signed short); 8514 8515vector unsigned char vec_max (vector bool char, vector unsigned char); 8516vector unsigned char vec_max (vector unsigned char, vector bool char); 8517vector unsigned char vec_max (vector unsigned char, 8518 vector unsigned char); 8519vector signed char vec_max (vector bool char, vector signed char); 8520vector signed char vec_max (vector signed char, vector bool char); 8521vector signed char vec_max (vector signed char, vector signed char); 8522vector unsigned short vec_max (vector bool short, 8523 vector unsigned short); 8524vector unsigned short vec_max (vector unsigned short, 8525 vector bool short); 8526vector unsigned short vec_max (vector unsigned short, 8527 vector unsigned short); 8528vector signed short vec_max (vector bool short, vector signed short); 8529vector signed short vec_max (vector signed short, vector bool short); 8530vector signed short vec_max (vector signed short, vector signed short); 8531vector unsigned int vec_max (vector bool int, vector unsigned int); 8532vector unsigned int vec_max (vector unsigned int, vector bool int); 8533vector unsigned int vec_max (vector unsigned int, vector unsigned int); 8534vector signed int vec_max (vector bool int, vector signed int); 8535vector signed int vec_max (vector signed int, vector bool int); 8536vector signed int vec_max (vector signed int, vector signed int); 8537vector float vec_max (vector float, vector float); 8538 8539vector float vec_vmaxfp (vector float, vector float); 8540 8541vector signed int vec_vmaxsw (vector bool int, vector signed int); 8542vector signed int vec_vmaxsw (vector signed int, vector bool int); 8543vector signed int vec_vmaxsw (vector signed int, vector signed int); 8544 8545vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); 8546vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); 8547vector unsigned int vec_vmaxuw (vector unsigned int, 8548 vector unsigned int); 8549 8550vector signed short vec_vmaxsh (vector bool short, vector signed short); 8551vector signed short vec_vmaxsh (vector signed short, vector bool short); 8552vector signed short vec_vmaxsh (vector signed short, 8553 vector signed short); 8554 8555vector unsigned short vec_vmaxuh (vector bool short, 8556 vector unsigned short); 8557vector unsigned short vec_vmaxuh (vector unsigned short, 8558 vector bool short); 8559vector unsigned short vec_vmaxuh (vector unsigned short, 8560 vector unsigned short); 8561 8562vector signed char vec_vmaxsb (vector bool char, vector signed char); 8563vector signed char vec_vmaxsb (vector signed char, vector bool char); 8564vector signed char vec_vmaxsb (vector signed char, vector signed char); 8565 8566vector unsigned char vec_vmaxub (vector bool char, 8567 vector unsigned char); 8568vector unsigned char vec_vmaxub (vector unsigned char, 8569 vector bool char); 8570vector unsigned char vec_vmaxub (vector unsigned char, 8571 vector unsigned char); 8572 8573vector bool char vec_mergeh (vector bool char, vector bool char); 8574vector signed char vec_mergeh (vector signed char, vector signed char); 8575vector unsigned char vec_mergeh (vector unsigned char, 8576 vector unsigned char); 8577vector bool short vec_mergeh (vector bool short, vector bool short); 8578vector pixel vec_mergeh (vector pixel, vector pixel); 8579vector signed short vec_mergeh (vector signed short, 8580 vector signed short); 8581vector unsigned short vec_mergeh (vector unsigned short, 8582 vector unsigned short); 8583vector float vec_mergeh (vector float, vector float); 8584vector bool int vec_mergeh (vector bool int, vector bool int); 8585vector signed int vec_mergeh (vector signed int, vector signed int); 8586vector unsigned int vec_mergeh (vector unsigned int, 8587 vector unsigned int); 8588 8589vector float vec_vmrghw (vector float, vector float); 8590vector bool int vec_vmrghw (vector bool int, vector bool int); 8591vector signed int vec_vmrghw (vector signed int, vector signed int); 8592vector unsigned int vec_vmrghw (vector unsigned int, 8593 vector unsigned int); 8594 8595vector bool short vec_vmrghh (vector bool short, vector bool short); 8596vector signed short vec_vmrghh (vector signed short, 8597 vector signed short); 8598vector unsigned short vec_vmrghh (vector unsigned short, 8599 vector unsigned short); 8600vector pixel vec_vmrghh (vector pixel, vector pixel); 8601 8602vector bool char vec_vmrghb (vector bool char, vector bool char); 8603vector signed char vec_vmrghb (vector signed char, vector signed char); 8604vector unsigned char vec_vmrghb (vector unsigned char, 8605 vector unsigned char); 8606 8607vector bool char vec_mergel (vector bool char, vector bool char); 8608vector signed char vec_mergel (vector signed char, vector signed char); 8609vector unsigned char vec_mergel (vector unsigned char, 8610 vector unsigned char); 8611vector bool short vec_mergel (vector bool short, vector bool short); 8612vector pixel vec_mergel (vector pixel, vector pixel); 8613vector signed short vec_mergel (vector signed short, 8614 vector signed short); 8615vector unsigned short vec_mergel (vector unsigned short, 8616 vector unsigned short); 8617vector float vec_mergel (vector float, vector float); 8618vector bool int vec_mergel (vector bool int, vector bool int); 8619vector signed int vec_mergel (vector signed int, vector signed int); 8620vector unsigned int vec_mergel (vector unsigned int, 8621 vector unsigned int); 8622 8623vector float vec_vmrglw (vector float, vector float); 8624vector signed int vec_vmrglw (vector signed int, vector signed int); 8625vector unsigned int vec_vmrglw (vector unsigned int, 8626 vector unsigned int); 8627vector bool int vec_vmrglw (vector bool int, vector bool int); 8628 8629vector bool short vec_vmrglh (vector bool short, vector bool short); 8630vector signed short vec_vmrglh (vector signed short, 8631 vector signed short); 8632vector unsigned short vec_vmrglh (vector unsigned short, 8633 vector unsigned short); 8634vector pixel vec_vmrglh (vector pixel, vector pixel); 8635 8636vector bool char vec_vmrglb (vector bool char, vector bool char); 8637vector signed char vec_vmrglb (vector signed char, vector signed char); 8638vector unsigned char vec_vmrglb (vector unsigned char, 8639 vector unsigned char); 8640 8641vector unsigned short vec_mfvscr (void); 8642 8643vector unsigned char vec_min (vector bool char, vector unsigned char); 8644vector unsigned char vec_min (vector unsigned char, vector bool char); 8645vector unsigned char vec_min (vector unsigned char, 8646 vector unsigned char); 8647vector signed char vec_min (vector bool char, vector signed char); 8648vector signed char vec_min (vector signed char, vector bool char); 8649vector signed char vec_min (vector signed char, vector signed char); 8650vector unsigned short vec_min (vector bool short, 8651 vector unsigned short); 8652vector unsigned short vec_min (vector unsigned short, 8653 vector bool short); 8654vector unsigned short vec_min (vector unsigned short, 8655 vector unsigned short); 8656vector signed short vec_min (vector bool short, vector signed short); 8657vector signed short vec_min (vector signed short, vector bool short); 8658vector signed short vec_min (vector signed short, vector signed short); 8659vector unsigned int vec_min (vector bool int, vector unsigned int); 8660vector unsigned int vec_min (vector unsigned int, vector bool int); 8661vector unsigned int vec_min (vector unsigned int, vector unsigned int); 8662vector signed int vec_min (vector bool int, vector signed int); 8663vector signed int vec_min (vector signed int, vector bool int); 8664vector signed int vec_min (vector signed int, vector signed int); 8665vector float vec_min (vector float, vector float); 8666 8667vector float vec_vminfp (vector float, vector float); 8668 8669vector signed int vec_vminsw (vector bool int, vector signed int); 8670vector signed int vec_vminsw (vector signed int, vector bool int); 8671vector signed int vec_vminsw (vector signed int, vector signed int); 8672 8673vector unsigned int vec_vminuw (vector bool int, vector unsigned int); 8674vector unsigned int vec_vminuw (vector unsigned int, vector bool int); 8675vector unsigned int vec_vminuw (vector unsigned int, 8676 vector unsigned int); 8677 8678vector signed short vec_vminsh (vector bool short, vector signed short); 8679vector signed short vec_vminsh (vector signed short, vector bool short); 8680vector signed short vec_vminsh (vector signed short, 8681 vector signed short); 8682 8683vector unsigned short vec_vminuh (vector bool short, 8684 vector unsigned short); 8685vector unsigned short vec_vminuh (vector unsigned short, 8686 vector bool short); 8687vector unsigned short vec_vminuh (vector unsigned short, 8688 vector unsigned short); 8689 8690vector signed char vec_vminsb (vector bool char, vector signed char); 8691vector signed char vec_vminsb (vector signed char, vector bool char); 8692vector signed char vec_vminsb (vector signed char, vector signed char); 8693 8694vector unsigned char vec_vminub (vector bool char, 8695 vector unsigned char); 8696vector unsigned char vec_vminub (vector unsigned char, 8697 vector bool char); 8698vector unsigned char vec_vminub (vector unsigned char, 8699 vector unsigned char); 8700 8701vector signed short vec_mladd (vector signed short, 8702 vector signed short, 8703 vector signed short); 8704vector signed short vec_mladd (vector signed short, 8705 vector unsigned short, 8706 vector unsigned short); 8707vector signed short vec_mladd (vector unsigned short, 8708 vector signed short, 8709 vector signed short); 8710vector unsigned short vec_mladd (vector unsigned short, 8711 vector unsigned short, 8712 vector unsigned short); 8713 8714vector signed short vec_mradds (vector signed short, 8715 vector signed short, 8716 vector signed short); 8717 8718vector unsigned int vec_msum (vector unsigned char, 8719 vector unsigned char, 8720 vector unsigned int); 8721vector signed int vec_msum (vector signed char, 8722 vector unsigned char, 8723 vector signed int); 8724vector unsigned int vec_msum (vector unsigned short, 8725 vector unsigned short, 8726 vector unsigned int); 8727vector signed int vec_msum (vector signed short, 8728 vector signed short, 8729 vector signed int); 8730 8731vector signed int vec_vmsumshm (vector signed short, 8732 vector signed short, 8733 vector signed int); 8734 8735vector unsigned int vec_vmsumuhm (vector unsigned short, 8736 vector unsigned short, 8737 vector unsigned int); 8738 8739vector signed int vec_vmsummbm (vector signed char, 8740 vector unsigned char, 8741 vector signed int); 8742 8743vector unsigned int vec_vmsumubm (vector unsigned char, 8744 vector unsigned char, 8745 vector unsigned int); 8746 8747vector unsigned int vec_msums (vector unsigned short, 8748 vector unsigned short, 8749 vector unsigned int); 8750vector signed int vec_msums (vector signed short, 8751 vector signed short, 8752 vector signed int); 8753 8754vector signed int vec_vmsumshs (vector signed short, 8755 vector signed short, 8756 vector signed int); 8757 8758vector unsigned int vec_vmsumuhs (vector unsigned short, 8759 vector unsigned short, 8760 vector unsigned int); 8761 8762void vec_mtvscr (vector signed int); 8763void vec_mtvscr (vector unsigned int); 8764void vec_mtvscr (vector bool int); 8765void vec_mtvscr (vector signed short); 8766void vec_mtvscr (vector unsigned short); 8767void vec_mtvscr (vector bool short); 8768void vec_mtvscr (vector pixel); 8769void vec_mtvscr (vector signed char); 8770void vec_mtvscr (vector unsigned char); 8771void vec_mtvscr (vector bool char); 8772 8773vector unsigned short vec_mule (vector unsigned char, 8774 vector unsigned char); 8775vector signed short vec_mule (vector signed char, 8776 vector signed char); 8777vector unsigned int vec_mule (vector unsigned short, 8778 vector unsigned short); 8779vector signed int vec_mule (vector signed short, vector signed short); 8780 8781vector signed int vec_vmulesh (vector signed short, 8782 vector signed short); 8783 8784vector unsigned int vec_vmuleuh (vector unsigned short, 8785 vector unsigned short); 8786 8787vector signed short vec_vmulesb (vector signed char, 8788 vector signed char); 8789 8790vector unsigned short vec_vmuleub (vector unsigned char, 8791 vector unsigned char); 8792 8793vector unsigned short vec_mulo (vector unsigned char, 8794 vector unsigned char); 8795vector signed short vec_mulo (vector signed char, vector signed char); 8796vector unsigned int vec_mulo (vector unsigned short, 8797 vector unsigned short); 8798vector signed int vec_mulo (vector signed short, vector signed short); 8799 8800vector signed int vec_vmulosh (vector signed short, 8801 vector signed short); 8802 8803vector unsigned int vec_vmulouh (vector unsigned short, 8804 vector unsigned short); 8805 8806vector signed short vec_vmulosb (vector signed char, 8807 vector signed char); 8808 8809vector unsigned short vec_vmuloub (vector unsigned char, 8810 vector unsigned char); 8811 8812vector float vec_nmsub (vector float, vector float, vector float); 8813 8814vector float vec_nor (vector float, vector float); 8815vector signed int vec_nor (vector signed int, vector signed int); 8816vector unsigned int vec_nor (vector unsigned int, vector unsigned int); 8817vector bool int vec_nor (vector bool int, vector bool int); 8818vector signed short vec_nor (vector signed short, vector signed short); 8819vector unsigned short vec_nor (vector unsigned short, 8820 vector unsigned short); 8821vector bool short vec_nor (vector bool short, vector bool short); 8822vector signed char vec_nor (vector signed char, vector signed char); 8823vector unsigned char vec_nor (vector unsigned char, 8824 vector unsigned char); 8825vector bool char vec_nor (vector bool char, vector bool char); 8826 8827vector float vec_or (vector float, vector float); 8828vector float vec_or (vector float, vector bool int); 8829vector float vec_or (vector bool int, vector float); 8830vector bool int vec_or (vector bool int, vector bool int); 8831vector signed int vec_or (vector bool int, vector signed int); 8832vector signed int vec_or (vector signed int, vector bool int); 8833vector signed int vec_or (vector signed int, vector signed int); 8834vector unsigned int vec_or (vector bool int, vector unsigned int); 8835vector unsigned int vec_or (vector unsigned int, vector bool int); 8836vector unsigned int vec_or (vector unsigned int, vector unsigned int); 8837vector bool short vec_or (vector bool short, vector bool short); 8838vector signed short vec_or (vector bool short, vector signed short); 8839vector signed short vec_or (vector signed short, vector bool short); 8840vector signed short vec_or (vector signed short, vector signed short); 8841vector unsigned short vec_or (vector bool short, vector unsigned short); 8842vector unsigned short vec_or (vector unsigned short, vector bool short); 8843vector unsigned short vec_or (vector unsigned short, 8844 vector unsigned short); 8845vector signed char vec_or (vector bool char, vector signed char); 8846vector bool char vec_or (vector bool char, vector bool char); 8847vector signed char vec_or (vector signed char, vector bool char); 8848vector signed char vec_or (vector signed char, vector signed char); 8849vector unsigned char vec_or (vector bool char, vector unsigned char); 8850vector unsigned char vec_or (vector unsigned char, vector bool char); 8851vector unsigned char vec_or (vector unsigned char, 8852 vector unsigned char); 8853 8854vector signed char vec_pack (vector signed short, vector signed short); 8855vector unsigned char vec_pack (vector unsigned short, 8856 vector unsigned short); 8857vector bool char vec_pack (vector bool short, vector bool short); 8858vector signed short vec_pack (vector signed int, vector signed int); 8859vector unsigned short vec_pack (vector unsigned int, 8860 vector unsigned int); 8861vector bool short vec_pack (vector bool int, vector bool int); 8862 8863vector bool short vec_vpkuwum (vector bool int, vector bool int); 8864vector signed short vec_vpkuwum (vector signed int, vector signed int); 8865vector unsigned short vec_vpkuwum (vector unsigned int, 8866 vector unsigned int); 8867 8868vector bool char vec_vpkuhum (vector bool short, vector bool short); 8869vector signed char vec_vpkuhum (vector signed short, 8870 vector signed short); 8871vector unsigned char vec_vpkuhum (vector unsigned short, 8872 vector unsigned short); 8873 8874vector pixel vec_packpx (vector unsigned int, vector unsigned int); 8875 8876vector unsigned char vec_packs (vector unsigned short, 8877 vector unsigned short); 8878vector signed char vec_packs (vector signed short, vector signed short); 8879vector unsigned short vec_packs (vector unsigned int, 8880 vector unsigned int); 8881vector signed short vec_packs (vector signed int, vector signed int); 8882 8883vector signed short vec_vpkswss (vector signed int, vector signed int); 8884 8885vector unsigned short vec_vpkuwus (vector unsigned int, 8886 vector unsigned int); 8887 8888vector signed char vec_vpkshss (vector signed short, 8889 vector signed short); 8890 8891vector unsigned char vec_vpkuhus (vector unsigned short, 8892 vector unsigned short); 8893 8894vector unsigned char vec_packsu (vector unsigned short, 8895 vector unsigned short); 8896vector unsigned char vec_packsu (vector signed short, 8897 vector signed short); 8898vector unsigned short vec_packsu (vector unsigned int, 8899 vector unsigned int); 8900vector unsigned short vec_packsu (vector signed int, vector signed int); 8901 8902vector unsigned short vec_vpkswus (vector signed int, 8903 vector signed int); 8904 8905vector unsigned char vec_vpkshus (vector signed short, 8906 vector signed short); 8907 8908vector float vec_perm (vector float, 8909 vector float, 8910 vector unsigned char); 8911vector signed int vec_perm (vector signed int, 8912 vector signed int, 8913 vector unsigned char); 8914vector unsigned int vec_perm (vector unsigned int, 8915 vector unsigned int, 8916 vector unsigned char); 8917vector bool int vec_perm (vector bool int, 8918 vector bool int, 8919 vector unsigned char); 8920vector signed short vec_perm (vector signed short, 8921 vector signed short, 8922 vector unsigned char); 8923vector unsigned short vec_perm (vector unsigned short, 8924 vector unsigned short, 8925 vector unsigned char); 8926vector bool short vec_perm (vector bool short, 8927 vector bool short, 8928 vector unsigned char); 8929vector pixel vec_perm (vector pixel, 8930 vector pixel, 8931 vector unsigned char); 8932vector signed char vec_perm (vector signed char, 8933 vector signed char, 8934 vector unsigned char); 8935vector unsigned char vec_perm (vector unsigned char, 8936 vector unsigned char, 8937 vector unsigned char); 8938vector bool char vec_perm (vector bool char, 8939 vector bool char, 8940 vector unsigned char); 8941 8942vector float vec_re (vector float); 8943 8944vector signed char vec_rl (vector signed char, 8945 vector unsigned char); 8946vector unsigned char vec_rl (vector unsigned char, 8947 vector unsigned char); 8948vector signed short vec_rl (vector signed short, vector unsigned short); 8949vector unsigned short vec_rl (vector unsigned short, 8950 vector unsigned short); 8951vector signed int vec_rl (vector signed int, vector unsigned int); 8952vector unsigned int vec_rl (vector unsigned int, vector unsigned int); 8953 8954vector signed int vec_vrlw (vector signed int, vector unsigned int); 8955vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); 8956 8957vector signed short vec_vrlh (vector signed short, 8958 vector unsigned short); 8959vector unsigned short vec_vrlh (vector unsigned short, 8960 vector unsigned short); 8961 8962vector signed char vec_vrlb (vector signed char, vector unsigned char); 8963vector unsigned char vec_vrlb (vector unsigned char, 8964 vector unsigned char); 8965 8966vector float vec_round (vector float); 8967 8968vector float vec_rsqrte (vector float); 8969 8970vector float vec_sel (vector float, vector float, vector bool int); 8971vector float vec_sel (vector float, vector float, vector unsigned int); 8972vector signed int vec_sel (vector signed int, 8973 vector signed int, 8974 vector bool int); 8975vector signed int vec_sel (vector signed int, 8976 vector signed int, 8977 vector unsigned int); 8978vector unsigned int vec_sel (vector unsigned int, 8979 vector unsigned int, 8980 vector bool int); 8981vector unsigned int vec_sel (vector unsigned int, 8982 vector unsigned int, 8983 vector unsigned int); 8984vector bool int vec_sel (vector bool int, 8985 vector bool int, 8986 vector bool int); 8987vector bool int vec_sel (vector bool int, 8988 vector bool int, 8989 vector unsigned int); 8990vector signed short vec_sel (vector signed short, 8991 vector signed short, 8992 vector bool short); 8993vector signed short vec_sel (vector signed short, 8994 vector signed short, 8995 vector unsigned short); 8996vector unsigned short vec_sel (vector unsigned short, 8997 vector unsigned short, 8998 vector bool short); 8999vector unsigned short vec_sel (vector unsigned short, 9000 vector unsigned short, 9001 vector unsigned short); 9002vector bool short vec_sel (vector bool short, 9003 vector bool short, 9004 vector bool short); 9005vector bool short vec_sel (vector bool short, 9006 vector bool short, 9007 vector unsigned short); 9008vector signed char vec_sel (vector signed char, 9009 vector signed char, 9010 vector bool char); 9011vector signed char vec_sel (vector signed char, 9012 vector signed char, 9013 vector unsigned char); 9014vector unsigned char vec_sel (vector unsigned char, 9015 vector unsigned char, 9016 vector bool char); 9017vector unsigned char vec_sel (vector unsigned char, 9018 vector unsigned char, 9019 vector unsigned char); 9020vector bool char vec_sel (vector bool char, 9021 vector bool char, 9022 vector bool char); 9023vector bool char vec_sel (vector bool char, 9024 vector bool char, 9025 vector unsigned char); 9026 9027vector signed char vec_sl (vector signed char, 9028 vector unsigned char); 9029vector unsigned char vec_sl (vector unsigned char, 9030 vector unsigned char); 9031vector signed short vec_sl (vector signed short, vector unsigned short); 9032vector unsigned short vec_sl (vector unsigned short, 9033 vector unsigned short); 9034vector signed int vec_sl (vector signed int, vector unsigned int); 9035vector unsigned int vec_sl (vector unsigned int, vector unsigned int); 9036 9037vector signed int vec_vslw (vector signed int, vector unsigned int); 9038vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); 9039 9040vector signed short vec_vslh (vector signed short, 9041 vector unsigned short); 9042vector unsigned short vec_vslh (vector unsigned short, 9043 vector unsigned short); 9044 9045vector signed char vec_vslb (vector signed char, vector unsigned char); 9046vector unsigned char vec_vslb (vector unsigned char, 9047 vector unsigned char); 9048 9049vector float vec_sld (vector float, vector float, const int); 9050vector signed int vec_sld (vector signed int, 9051 vector signed int, 9052 const int); 9053vector unsigned int vec_sld (vector unsigned int, 9054 vector unsigned int, 9055 const int); 9056vector bool int vec_sld (vector bool int, 9057 vector bool int, 9058 const int); 9059vector signed short vec_sld (vector signed short, 9060 vector signed short, 9061 const int); 9062vector unsigned short vec_sld (vector unsigned short, 9063 vector unsigned short, 9064 const int); 9065vector bool short vec_sld (vector bool short, 9066 vector bool short, 9067 const int); 9068vector pixel vec_sld (vector pixel, 9069 vector pixel, 9070 const int); 9071vector signed char vec_sld (vector signed char, 9072 vector signed char, 9073 const int); 9074vector unsigned char vec_sld (vector unsigned char, 9075 vector unsigned char, 9076 const int); 9077vector bool char vec_sld (vector bool char, 9078 vector bool char, 9079 const int); 9080 9081vector signed int vec_sll (vector signed int, 9082 vector unsigned int); 9083vector signed int vec_sll (vector signed int, 9084 vector unsigned short); 9085vector signed int vec_sll (vector signed int, 9086 vector unsigned char); 9087vector unsigned int vec_sll (vector unsigned int, 9088 vector unsigned int); 9089vector unsigned int vec_sll (vector unsigned int, 9090 vector unsigned short); 9091vector unsigned int vec_sll (vector unsigned int, 9092 vector unsigned char); 9093vector bool int vec_sll (vector bool int, 9094 vector unsigned int); 9095vector bool int vec_sll (vector bool int, 9096 vector unsigned short); 9097vector bool int vec_sll (vector bool int, 9098 vector unsigned char); 9099vector signed short vec_sll (vector signed short, 9100 vector unsigned int); 9101vector signed short vec_sll (vector signed short, 9102 vector unsigned short); 9103vector signed short vec_sll (vector signed short, 9104 vector unsigned char); 9105vector unsigned short vec_sll (vector unsigned short, 9106 vector unsigned int); 9107vector unsigned short vec_sll (vector unsigned short, 9108 vector unsigned short); 9109vector unsigned short vec_sll (vector unsigned short, 9110 vector unsigned char); 9111vector bool short vec_sll (vector bool short, vector unsigned int); 9112vector bool short vec_sll (vector bool short, vector unsigned short); 9113vector bool short vec_sll (vector bool short, vector unsigned char); 9114vector pixel vec_sll (vector pixel, vector unsigned int); 9115vector pixel vec_sll (vector pixel, vector unsigned short); 9116vector pixel vec_sll (vector pixel, vector unsigned char); 9117vector signed char vec_sll (vector signed char, vector unsigned int); 9118vector signed char vec_sll (vector signed char, vector unsigned short); 9119vector signed char vec_sll (vector signed char, vector unsigned char); 9120vector unsigned char vec_sll (vector unsigned char, 9121 vector unsigned int); 9122vector unsigned char vec_sll (vector unsigned char, 9123 vector unsigned short); 9124vector unsigned char vec_sll (vector unsigned char, 9125 vector unsigned char); 9126vector bool char vec_sll (vector bool char, vector unsigned int); 9127vector bool char vec_sll (vector bool char, vector unsigned short); 9128vector bool char vec_sll (vector bool char, vector unsigned char); 9129 9130vector float vec_slo (vector float, vector signed char); 9131vector float vec_slo (vector float, vector unsigned char); 9132vector signed int vec_slo (vector signed int, vector signed char); 9133vector signed int vec_slo (vector signed int, vector unsigned char); 9134vector unsigned int vec_slo (vector unsigned int, vector signed char); 9135vector unsigned int vec_slo (vector unsigned int, vector unsigned char); 9136vector signed short vec_slo (vector signed short, vector signed char); 9137vector signed short vec_slo (vector signed short, vector unsigned char); 9138vector unsigned short vec_slo (vector unsigned short, 9139 vector signed char); 9140vector unsigned short vec_slo (vector unsigned short, 9141 vector unsigned char); 9142vector pixel vec_slo (vector pixel, vector signed char); 9143vector pixel vec_slo (vector pixel, vector unsigned char); 9144vector signed char vec_slo (vector signed char, vector signed char); 9145vector signed char vec_slo (vector signed char, vector unsigned char); 9146vector unsigned char vec_slo (vector unsigned char, vector signed char); 9147vector unsigned char vec_slo (vector unsigned char, 9148 vector unsigned char); 9149 9150vector signed char vec_splat (vector signed char, const int); 9151vector unsigned char vec_splat (vector unsigned char, const int); 9152vector bool char vec_splat (vector bool char, const int); 9153vector signed short vec_splat (vector signed short, const int); 9154vector unsigned short vec_splat (vector unsigned short, const int); 9155vector bool short vec_splat (vector bool short, const int); 9156vector pixel vec_splat (vector pixel, const int); 9157vector float vec_splat (vector float, const int); 9158vector signed int vec_splat (vector signed int, const int); 9159vector unsigned int vec_splat (vector unsigned int, const int); 9160vector bool int vec_splat (vector bool int, const int); 9161 9162vector float vec_vspltw (vector float, const int); 9163vector signed int vec_vspltw (vector signed int, const int); 9164vector unsigned int vec_vspltw (vector unsigned int, const int); 9165vector bool int vec_vspltw (vector bool int, const int); 9166 9167vector bool short vec_vsplth (vector bool short, const int); 9168vector signed short vec_vsplth (vector signed short, const int); 9169vector unsigned short vec_vsplth (vector unsigned short, const int); 9170vector pixel vec_vsplth (vector pixel, const int); 9171 9172vector signed char vec_vspltb (vector signed char, const int); 9173vector unsigned char vec_vspltb (vector unsigned char, const int); 9174vector bool char vec_vspltb (vector bool char, const int); 9175 9176vector signed char vec_splat_s8 (const int); 9177 9178vector signed short vec_splat_s16 (const int); 9179 9180vector signed int vec_splat_s32 (const int); 9181 9182vector unsigned char vec_splat_u8 (const int); 9183 9184vector unsigned short vec_splat_u16 (const int); 9185 9186vector unsigned int vec_splat_u32 (const int); 9187 9188vector signed char vec_sr (vector signed char, vector unsigned char); 9189vector unsigned char vec_sr (vector unsigned char, 9190 vector unsigned char); 9191vector signed short vec_sr (vector signed short, 9192 vector unsigned short); 9193vector unsigned short vec_sr (vector unsigned short, 9194 vector unsigned short); 9195vector signed int vec_sr (vector signed int, vector unsigned int); 9196vector unsigned int vec_sr (vector unsigned int, vector unsigned int); 9197 9198vector signed int vec_vsrw (vector signed int, vector unsigned int); 9199vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); 9200 9201vector signed short vec_vsrh (vector signed short, 9202 vector unsigned short); 9203vector unsigned short vec_vsrh (vector unsigned short, 9204 vector unsigned short); 9205 9206vector signed char vec_vsrb (vector signed char, vector unsigned char); 9207vector unsigned char vec_vsrb (vector unsigned char, 9208 vector unsigned char); 9209 9210vector signed char vec_sra (vector signed char, vector unsigned char); 9211vector unsigned char vec_sra (vector unsigned char, 9212 vector unsigned char); 9213vector signed short vec_sra (vector signed short, 9214 vector unsigned short); 9215vector unsigned short vec_sra (vector unsigned short, 9216 vector unsigned short); 9217vector signed int vec_sra (vector signed int, vector unsigned int); 9218vector unsigned int vec_sra (vector unsigned int, vector unsigned int); 9219 9220vector signed int vec_vsraw (vector signed int, vector unsigned int); 9221vector unsigned int vec_vsraw (vector unsigned int, 9222 vector unsigned int); 9223 9224vector signed short vec_vsrah (vector signed short, 9225 vector unsigned short); 9226vector unsigned short vec_vsrah (vector unsigned short, 9227 vector unsigned short); 9228 9229vector signed char vec_vsrab (vector signed char, vector unsigned char); 9230vector unsigned char vec_vsrab (vector unsigned char, 9231 vector unsigned char); 9232 9233vector signed int vec_srl (vector signed int, vector unsigned int); 9234vector signed int vec_srl (vector signed int, vector unsigned short); 9235vector signed int vec_srl (vector signed int, vector unsigned char); 9236vector unsigned int vec_srl (vector unsigned int, vector unsigned int); 9237vector unsigned int vec_srl (vector unsigned int, 9238 vector unsigned short); 9239vector unsigned int vec_srl (vector unsigned int, vector unsigned char); 9240vector bool int vec_srl (vector bool int, vector unsigned int); 9241vector bool int vec_srl (vector bool int, vector unsigned short); 9242vector bool int vec_srl (vector bool int, vector unsigned char); 9243vector signed short vec_srl (vector signed short, vector unsigned int); 9244vector signed short vec_srl (vector signed short, 9245 vector unsigned short); 9246vector signed short vec_srl (vector signed short, vector unsigned char); 9247vector unsigned short vec_srl (vector unsigned short, 9248 vector unsigned int); 9249vector unsigned short vec_srl (vector unsigned short, 9250 vector unsigned short); 9251vector unsigned short vec_srl (vector unsigned short, 9252 vector unsigned char); 9253vector bool short vec_srl (vector bool short, vector unsigned int); 9254vector bool short vec_srl (vector bool short, vector unsigned short); 9255vector bool short vec_srl (vector bool short, vector unsigned char); 9256vector pixel vec_srl (vector pixel, vector unsigned int); 9257vector pixel vec_srl (vector pixel, vector unsigned short); 9258vector pixel vec_srl (vector pixel, vector unsigned char); 9259vector signed char vec_srl (vector signed char, vector unsigned int); 9260vector signed char vec_srl (vector signed char, vector unsigned short); 9261vector signed char vec_srl (vector signed char, vector unsigned char); 9262vector unsigned char vec_srl (vector unsigned char, 9263 vector unsigned int); 9264vector unsigned char vec_srl (vector unsigned char, 9265 vector unsigned short); 9266vector unsigned char vec_srl (vector unsigned char, 9267 vector unsigned char); 9268vector bool char vec_srl (vector bool char, vector unsigned int); 9269vector bool char vec_srl (vector bool char, vector unsigned short); 9270vector bool char vec_srl (vector bool char, vector unsigned char); 9271 9272vector float vec_sro (vector float, vector signed char); 9273vector float vec_sro (vector float, vector unsigned char); 9274vector signed int vec_sro (vector signed int, vector signed char); 9275vector signed int vec_sro (vector signed int, vector unsigned char); 9276vector unsigned int vec_sro (vector unsigned int, vector signed char); 9277vector unsigned int vec_sro (vector unsigned int, vector unsigned char); 9278vector signed short vec_sro (vector signed short, vector signed char); 9279vector signed short vec_sro (vector signed short, vector unsigned char); 9280vector unsigned short vec_sro (vector unsigned short, 9281 vector signed char); 9282vector unsigned short vec_sro (vector unsigned short, 9283 vector unsigned char); 9284vector pixel vec_sro (vector pixel, vector signed char); 9285vector pixel vec_sro (vector pixel, vector unsigned char); 9286vector signed char vec_sro (vector signed char, vector signed char); 9287vector signed char vec_sro (vector signed char, vector unsigned char); 9288vector unsigned char vec_sro (vector unsigned char, vector signed char); 9289vector unsigned char vec_sro (vector unsigned char, 9290 vector unsigned char); 9291 9292void vec_st (vector float, int, vector float *); 9293void vec_st (vector float, int, float *); 9294void vec_st (vector signed int, int, vector signed int *); 9295void vec_st (vector signed int, int, int *); 9296void vec_st (vector unsigned int, int, vector unsigned int *); 9297void vec_st (vector unsigned int, int, unsigned int *); 9298void vec_st (vector bool int, int, vector bool int *); 9299void vec_st (vector bool int, int, unsigned int *); 9300void vec_st (vector bool int, int, int *); 9301void vec_st (vector signed short, int, vector signed short *); 9302void vec_st (vector signed short, int, short *); 9303void vec_st (vector unsigned short, int, vector unsigned short *); 9304void vec_st (vector unsigned short, int, unsigned short *); 9305void vec_st (vector bool short, int, vector bool short *); 9306void vec_st (vector bool short, int, unsigned short *); 9307void vec_st (vector pixel, int, vector pixel *); 9308void vec_st (vector pixel, int, unsigned short *); 9309void vec_st (vector pixel, int, short *); 9310void vec_st (vector bool short, int, short *); 9311void vec_st (vector signed char, int, vector signed char *); 9312void vec_st (vector signed char, int, signed char *); 9313void vec_st (vector unsigned char, int, vector unsigned char *); 9314void vec_st (vector unsigned char, int, unsigned char *); 9315void vec_st (vector bool char, int, vector bool char *); 9316void vec_st (vector bool char, int, unsigned char *); 9317void vec_st (vector bool char, int, signed char *); 9318 9319void vec_ste (vector signed char, int, signed char *); 9320void vec_ste (vector unsigned char, int, unsigned char *); 9321void vec_ste (vector bool char, int, signed char *); 9322void vec_ste (vector bool char, int, unsigned char *); 9323void vec_ste (vector signed short, int, short *); 9324void vec_ste (vector unsigned short, int, unsigned short *); 9325void vec_ste (vector bool short, int, short *); 9326void vec_ste (vector bool short, int, unsigned short *); 9327void vec_ste (vector pixel, int, short *); 9328void vec_ste (vector pixel, int, unsigned short *); 9329void vec_ste (vector float, int, float *); 9330void vec_ste (vector signed int, int, int *); 9331void vec_ste (vector unsigned int, int, unsigned int *); 9332void vec_ste (vector bool int, int, int *); 9333void vec_ste (vector bool int, int, unsigned int *); 9334 9335void vec_stvewx (vector float, int, float *); 9336void vec_stvewx (vector signed int, int, int *); 9337void vec_stvewx (vector unsigned int, int, unsigned int *); 9338void vec_stvewx (vector bool int, int, int *); 9339void vec_stvewx (vector bool int, int, unsigned int *); 9340 9341void vec_stvehx (vector signed short, int, short *); 9342void vec_stvehx (vector unsigned short, int, unsigned short *); 9343void vec_stvehx (vector bool short, int, short *); 9344void vec_stvehx (vector bool short, int, unsigned short *); 9345void vec_stvehx (vector pixel, int, short *); 9346void vec_stvehx (vector pixel, int, unsigned short *); 9347 9348void vec_stvebx (vector signed char, int, signed char *); 9349void vec_stvebx (vector unsigned char, int, unsigned char *); 9350void vec_stvebx (vector bool char, int, signed char *); 9351void vec_stvebx (vector bool char, int, unsigned char *); 9352 9353void vec_stl (vector float, int, vector float *); 9354void vec_stl (vector float, int, float *); 9355void vec_stl (vector signed int, int, vector signed int *); 9356void vec_stl (vector signed int, int, int *); 9357void vec_stl (vector unsigned int, int, vector unsigned int *); 9358void vec_stl (vector unsigned int, int, unsigned int *); 9359void vec_stl (vector bool int, int, vector bool int *); 9360void vec_stl (vector bool int, int, unsigned int *); 9361void vec_stl (vector bool int, int, int *); 9362void vec_stl (vector signed short, int, vector signed short *); 9363void vec_stl (vector signed short, int, short *); 9364void vec_stl (vector unsigned short, int, vector unsigned short *); 9365void vec_stl (vector unsigned short, int, unsigned short *); 9366void vec_stl (vector bool short, int, vector bool short *); 9367void vec_stl (vector bool short, int, unsigned short *); 9368void vec_stl (vector bool short, int, short *); 9369void vec_stl (vector pixel, int, vector pixel *); 9370void vec_stl (vector pixel, int, unsigned short *); 9371void vec_stl (vector pixel, int, short *); 9372void vec_stl (vector signed char, int, vector signed char *); 9373void vec_stl (vector signed char, int, signed char *); 9374void vec_stl (vector unsigned char, int, vector unsigned char *); 9375void vec_stl (vector unsigned char, int, unsigned char *); 9376void vec_stl (vector bool char, int, vector bool char *); 9377void vec_stl (vector bool char, int, unsigned char *); 9378void vec_stl (vector bool char, int, signed char *); 9379 9380vector signed char vec_sub (vector bool char, vector signed char); 9381vector signed char vec_sub (vector signed char, vector bool char); 9382vector signed char vec_sub (vector signed char, vector signed char); 9383vector unsigned char vec_sub (vector bool char, vector unsigned char); 9384vector unsigned char vec_sub (vector unsigned char, vector bool char); 9385vector unsigned char vec_sub (vector unsigned char, 9386 vector unsigned char); 9387vector signed short vec_sub (vector bool short, vector signed short); 9388vector signed short vec_sub (vector signed short, vector bool short); 9389vector signed short vec_sub (vector signed short, vector signed short); 9390vector unsigned short vec_sub (vector bool short, 9391 vector unsigned short); 9392vector unsigned short vec_sub (vector unsigned short, 9393 vector bool short); 9394vector unsigned short vec_sub (vector unsigned short, 9395 vector unsigned short); 9396vector signed int vec_sub (vector bool int, vector signed int); 9397vector signed int vec_sub (vector signed int, vector bool int); 9398vector signed int vec_sub (vector signed int, vector signed int); 9399vector unsigned int vec_sub (vector bool int, vector unsigned int); 9400vector unsigned int vec_sub (vector unsigned int, vector bool int); 9401vector unsigned int vec_sub (vector unsigned int, vector unsigned int); 9402vector float vec_sub (vector float, vector float); 9403 9404vector float vec_vsubfp (vector float, vector float); 9405 9406vector signed int vec_vsubuwm (vector bool int, vector signed int); 9407vector signed int vec_vsubuwm (vector signed int, vector bool int); 9408vector signed int vec_vsubuwm (vector signed int, vector signed int); 9409vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); 9410vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); 9411vector unsigned int vec_vsubuwm (vector unsigned int, 9412 vector unsigned int); 9413 9414vector signed short vec_vsubuhm (vector bool short, 9415 vector signed short); 9416vector signed short vec_vsubuhm (vector signed short, 9417 vector bool short); 9418vector signed short vec_vsubuhm (vector signed short, 9419 vector signed short); 9420vector unsigned short vec_vsubuhm (vector bool short, 9421 vector unsigned short); 9422vector unsigned short vec_vsubuhm (vector unsigned short, 9423 vector bool short); 9424vector unsigned short vec_vsubuhm (vector unsigned short, 9425 vector unsigned short); 9426 9427vector signed char vec_vsububm (vector bool char, vector signed char); 9428vector signed char vec_vsububm (vector signed char, vector bool char); 9429vector signed char vec_vsububm (vector signed char, vector signed char); 9430vector unsigned char vec_vsububm (vector bool char, 9431 vector unsigned char); 9432vector unsigned char vec_vsububm (vector unsigned char, 9433 vector bool char); 9434vector unsigned char vec_vsububm (vector unsigned char, 9435 vector unsigned char); 9436 9437vector unsigned int vec_subc (vector unsigned int, vector unsigned int); 9438 9439vector unsigned char vec_subs (vector bool char, vector unsigned char); 9440vector unsigned char vec_subs (vector unsigned char, vector bool char); 9441vector unsigned char vec_subs (vector unsigned char, 9442 vector unsigned char); 9443vector signed char vec_subs (vector bool char, vector signed char); 9444vector signed char vec_subs (vector signed char, vector bool char); 9445vector signed char vec_subs (vector signed char, vector signed char); 9446vector unsigned short vec_subs (vector bool short, 9447 vector unsigned short); 9448vector unsigned short vec_subs (vector unsigned short, 9449 vector bool short); 9450vector unsigned short vec_subs (vector unsigned short, 9451 vector unsigned short); 9452vector signed short vec_subs (vector bool short, vector signed short); 9453vector signed short vec_subs (vector signed short, vector bool short); 9454vector signed short vec_subs (vector signed short, vector signed short); 9455vector unsigned int vec_subs (vector bool int, vector unsigned int); 9456vector unsigned int vec_subs (vector unsigned int, vector bool int); 9457vector unsigned int vec_subs (vector unsigned int, vector unsigned int); 9458vector signed int vec_subs (vector bool int, vector signed int); 9459vector signed int vec_subs (vector signed int, vector bool int); 9460vector signed int vec_subs (vector signed int, vector signed int); 9461 9462vector signed int vec_vsubsws (vector bool int, vector signed int); 9463vector signed int vec_vsubsws (vector signed int, vector bool int); 9464vector signed int vec_vsubsws (vector signed int, vector signed int); 9465 9466vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); 9467vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); 9468vector unsigned int vec_vsubuws (vector unsigned int, 9469 vector unsigned int); 9470 9471vector signed short vec_vsubshs (vector bool short, 9472 vector signed short); 9473vector signed short vec_vsubshs (vector signed short, 9474 vector bool short); 9475vector signed short vec_vsubshs (vector signed short, 9476 vector signed short); 9477 9478vector unsigned short vec_vsubuhs (vector bool short, 9479 vector unsigned short); 9480vector unsigned short vec_vsubuhs (vector unsigned short, 9481 vector bool short); 9482vector unsigned short vec_vsubuhs (vector unsigned short, 9483 vector unsigned short); 9484 9485vector signed char vec_vsubsbs (vector bool char, vector signed char); 9486vector signed char vec_vsubsbs (vector signed char, vector bool char); 9487vector signed char vec_vsubsbs (vector signed char, vector signed char); 9488 9489vector unsigned char vec_vsububs (vector bool char, 9490 vector unsigned char); 9491vector unsigned char vec_vsububs (vector unsigned char, 9492 vector bool char); 9493vector unsigned char vec_vsububs (vector unsigned char, 9494 vector unsigned char); 9495 9496vector unsigned int vec_sum4s (vector unsigned char, 9497 vector unsigned int); 9498vector signed int vec_sum4s (vector signed char, vector signed int); 9499vector signed int vec_sum4s (vector signed short, vector signed int); 9500 9501vector signed int vec_vsum4shs (vector signed short, vector signed int); 9502 9503vector signed int vec_vsum4sbs (vector signed char, vector signed int); 9504 9505vector unsigned int vec_vsum4ubs (vector unsigned char, 9506 vector unsigned int); 9507 9508vector signed int vec_sum2s (vector signed int, vector signed int); 9509 9510vector signed int vec_sums (vector signed int, vector signed int); 9511 9512vector float vec_trunc (vector float); 9513 9514vector signed short vec_unpackh (vector signed char); 9515vector bool short vec_unpackh (vector bool char); 9516vector signed int vec_unpackh (vector signed short); 9517vector bool int vec_unpackh (vector bool short); 9518vector unsigned int vec_unpackh (vector pixel); 9519 9520vector bool int vec_vupkhsh (vector bool short); 9521vector signed int vec_vupkhsh (vector signed short); 9522 9523vector unsigned int vec_vupkhpx (vector pixel); 9524 9525vector bool short vec_vupkhsb (vector bool char); 9526vector signed short vec_vupkhsb (vector signed char); 9527 9528vector signed short vec_unpackl (vector signed char); 9529vector bool short vec_unpackl (vector bool char); 9530vector unsigned int vec_unpackl (vector pixel); 9531vector signed int vec_unpackl (vector signed short); 9532vector bool int vec_unpackl (vector bool short); 9533 9534vector unsigned int vec_vupklpx (vector pixel); 9535 9536vector bool int vec_vupklsh (vector bool short); 9537vector signed int vec_vupklsh (vector signed short); 9538 9539vector bool short vec_vupklsb (vector bool char); 9540vector signed short vec_vupklsb (vector signed char); 9541 9542vector float vec_xor (vector float, vector float); 9543vector float vec_xor (vector float, vector bool int); 9544vector float vec_xor (vector bool int, vector float); 9545vector bool int vec_xor (vector bool int, vector bool int); 9546vector signed int vec_xor (vector bool int, vector signed int); 9547vector signed int vec_xor (vector signed int, vector bool int); 9548vector signed int vec_xor (vector signed int, vector signed int); 9549vector unsigned int vec_xor (vector bool int, vector unsigned int); 9550vector unsigned int vec_xor (vector unsigned int, vector bool int); 9551vector unsigned int vec_xor (vector unsigned int, vector unsigned int); 9552vector bool short vec_xor (vector bool short, vector bool short); 9553vector signed short vec_xor (vector bool short, vector signed short); 9554vector signed short vec_xor (vector signed short, vector bool short); 9555vector signed short vec_xor (vector signed short, vector signed short); 9556vector unsigned short vec_xor (vector bool short, 9557 vector unsigned short); 9558vector unsigned short vec_xor (vector unsigned short, 9559 vector bool short); 9560vector unsigned short vec_xor (vector unsigned short, 9561 vector unsigned short); 9562vector signed char vec_xor (vector bool char, vector signed char); 9563vector bool char vec_xor (vector bool char, vector bool char); 9564vector signed char vec_xor (vector signed char, vector bool char); 9565vector signed char vec_xor (vector signed char, vector signed char); 9566vector unsigned char vec_xor (vector bool char, vector unsigned char); 9567vector unsigned char vec_xor (vector unsigned char, vector bool char); 9568vector unsigned char vec_xor (vector unsigned char, 9569 vector unsigned char); 9570 9571int vec_all_eq (vector signed char, vector bool char); 9572int vec_all_eq (vector signed char, vector signed char); 9573int vec_all_eq (vector unsigned char, vector bool char); 9574int vec_all_eq (vector unsigned char, vector unsigned char); 9575int vec_all_eq (vector bool char, vector bool char); 9576int vec_all_eq (vector bool char, vector unsigned char); 9577int vec_all_eq (vector bool char, vector signed char); 9578int vec_all_eq (vector signed short, vector bool short); 9579int vec_all_eq (vector signed short, vector signed short); 9580int vec_all_eq (vector unsigned short, vector bool short); 9581int vec_all_eq (vector unsigned short, vector unsigned short); 9582int vec_all_eq (vector bool short, vector bool short); 9583int vec_all_eq (vector bool short, vector unsigned short); 9584int vec_all_eq (vector bool short, vector signed short); 9585int vec_all_eq (vector pixel, vector pixel); 9586int vec_all_eq (vector signed int, vector bool int); 9587int vec_all_eq (vector signed int, vector signed int); 9588int vec_all_eq (vector unsigned int, vector bool int); 9589int vec_all_eq (vector unsigned int, vector unsigned int); 9590int vec_all_eq (vector bool int, vector bool int); 9591int vec_all_eq (vector bool int, vector unsigned int); 9592int vec_all_eq (vector bool int, vector signed int); 9593int vec_all_eq (vector float, vector float); 9594 9595int vec_all_ge (vector bool char, vector unsigned char); 9596int vec_all_ge (vector unsigned char, vector bool char); 9597int vec_all_ge (vector unsigned char, vector unsigned char); 9598int vec_all_ge (vector bool char, vector signed char); 9599int vec_all_ge (vector signed char, vector bool char); 9600int vec_all_ge (vector signed char, vector signed char); 9601int vec_all_ge (vector bool short, vector unsigned short); 9602int vec_all_ge (vector unsigned short, vector bool short); 9603int vec_all_ge (vector unsigned short, vector unsigned short); 9604int vec_all_ge (vector signed short, vector signed short); 9605int vec_all_ge (vector bool short, vector signed short); 9606int vec_all_ge (vector signed short, vector bool short); 9607int vec_all_ge (vector bool int, vector unsigned int); 9608int vec_all_ge (vector unsigned int, vector bool int); 9609int vec_all_ge (vector unsigned int, vector unsigned int); 9610int vec_all_ge (vector bool int, vector signed int); 9611int vec_all_ge (vector signed int, vector bool int); 9612int vec_all_ge (vector signed int, vector signed int); 9613int vec_all_ge (vector float, vector float); 9614 9615int vec_all_gt (vector bool char, vector unsigned char); 9616int vec_all_gt (vector unsigned char, vector bool char); 9617int vec_all_gt (vector unsigned char, vector unsigned char); 9618int vec_all_gt (vector bool char, vector signed char); 9619int vec_all_gt (vector signed char, vector bool char); 9620int vec_all_gt (vector signed char, vector signed char); 9621int vec_all_gt (vector bool short, vector unsigned short); 9622int vec_all_gt (vector unsigned short, vector bool short); 9623int vec_all_gt (vector unsigned short, vector unsigned short); 9624int vec_all_gt (vector bool short, vector signed short); 9625int vec_all_gt (vector signed short, vector bool short); 9626int vec_all_gt (vector signed short, vector signed short); 9627int vec_all_gt (vector bool int, vector unsigned int); 9628int vec_all_gt (vector unsigned int, vector bool int); 9629int vec_all_gt (vector unsigned int, vector unsigned int); 9630int vec_all_gt (vector bool int, vector signed int); 9631int vec_all_gt (vector signed int, vector bool int); 9632int vec_all_gt (vector signed int, vector signed int); 9633int vec_all_gt (vector float, vector float); 9634 9635int vec_all_in (vector float, vector float); 9636 9637int vec_all_le (vector bool char, vector unsigned char); 9638int vec_all_le (vector unsigned char, vector bool char); 9639int vec_all_le (vector unsigned char, vector unsigned char); 9640int vec_all_le (vector bool char, vector signed char); 9641int vec_all_le (vector signed char, vector bool char); 9642int vec_all_le (vector signed char, vector signed char); 9643int vec_all_le (vector bool short, vector unsigned short); 9644int vec_all_le (vector unsigned short, vector bool short); 9645int vec_all_le (vector unsigned short, vector unsigned short); 9646int vec_all_le (vector bool short, vector signed short); 9647int vec_all_le (vector signed short, vector bool short); 9648int vec_all_le (vector signed short, vector signed short); 9649int vec_all_le (vector bool int, vector unsigned int); 9650int vec_all_le (vector unsigned int, vector bool int); 9651int vec_all_le (vector unsigned int, vector unsigned int); 9652int vec_all_le (vector bool int, vector signed int); 9653int vec_all_le (vector signed int, vector bool int); 9654int vec_all_le (vector signed int, vector signed int); 9655int vec_all_le (vector float, vector float); 9656 9657int vec_all_lt (vector bool char, vector unsigned char); 9658int vec_all_lt (vector unsigned char, vector bool char); 9659int vec_all_lt (vector unsigned char, vector unsigned char); 9660int vec_all_lt (vector bool char, vector signed char); 9661int vec_all_lt (vector signed char, vector bool char); 9662int vec_all_lt (vector signed char, vector signed char); 9663int vec_all_lt (vector bool short, vector unsigned short); 9664int vec_all_lt (vector unsigned short, vector bool short); 9665int vec_all_lt (vector unsigned short, vector unsigned short); 9666int vec_all_lt (vector bool short, vector signed short); 9667int vec_all_lt (vector signed short, vector bool short); 9668int vec_all_lt (vector signed short, vector signed short); 9669int vec_all_lt (vector bool int, vector unsigned int); 9670int vec_all_lt (vector unsigned int, vector bool int); 9671int vec_all_lt (vector unsigned int, vector unsigned int); 9672int vec_all_lt (vector bool int, vector signed int); 9673int vec_all_lt (vector signed int, vector bool int); 9674int vec_all_lt (vector signed int, vector signed int); 9675int vec_all_lt (vector float, vector float); 9676 9677int vec_all_nan (vector float); 9678 9679int vec_all_ne (vector signed char, vector bool char); 9680int vec_all_ne (vector signed char, vector signed char); 9681int vec_all_ne (vector unsigned char, vector bool char); 9682int vec_all_ne (vector unsigned char, vector unsigned char); 9683int vec_all_ne (vector bool char, vector bool char); 9684int vec_all_ne (vector bool char, vector unsigned char); 9685int vec_all_ne (vector bool char, vector signed char); 9686int vec_all_ne (vector signed short, vector bool short); 9687int vec_all_ne (vector signed short, vector signed short); 9688int vec_all_ne (vector unsigned short, vector bool short); 9689int vec_all_ne (vector unsigned short, vector unsigned short); 9690int vec_all_ne (vector bool short, vector bool short); 9691int vec_all_ne (vector bool short, vector unsigned short); 9692int vec_all_ne (vector bool short, vector signed short); 9693int vec_all_ne (vector pixel, vector pixel); 9694int vec_all_ne (vector signed int, vector bool int); 9695int vec_all_ne (vector signed int, vector signed int); 9696int vec_all_ne (vector unsigned int, vector bool int); 9697int vec_all_ne (vector unsigned int, vector unsigned int); 9698int vec_all_ne (vector bool int, vector bool int); 9699int vec_all_ne (vector bool int, vector unsigned int); 9700int vec_all_ne (vector bool int, vector signed int); 9701int vec_all_ne (vector float, vector float); 9702 9703int vec_all_nge (vector float, vector float); 9704 9705int vec_all_ngt (vector float, vector float); 9706 9707int vec_all_nle (vector float, vector float); 9708 9709int vec_all_nlt (vector float, vector float); 9710 9711int vec_all_numeric (vector float); 9712 9713int vec_any_eq (vector signed char, vector bool char); 9714int vec_any_eq (vector signed char, vector signed char); 9715int vec_any_eq (vector unsigned char, vector bool char); 9716int vec_any_eq (vector unsigned char, vector unsigned char); 9717int vec_any_eq (vector bool char, vector bool char); 9718int vec_any_eq (vector bool char, vector unsigned char); 9719int vec_any_eq (vector bool char, vector signed char); 9720int vec_any_eq (vector signed short, vector bool short); 9721int vec_any_eq (vector signed short, vector signed short); 9722int vec_any_eq (vector unsigned short, vector bool short); 9723int vec_any_eq (vector unsigned short, vector unsigned short); 9724int vec_any_eq (vector bool short, vector bool short); 9725int vec_any_eq (vector bool short, vector unsigned short); 9726int vec_any_eq (vector bool short, vector signed short); 9727int vec_any_eq (vector pixel, vector pixel); 9728int vec_any_eq (vector signed int, vector bool int); 9729int vec_any_eq (vector signed int, vector signed int); 9730int vec_any_eq (vector unsigned int, vector bool int); 9731int vec_any_eq (vector unsigned int, vector unsigned int); 9732int vec_any_eq (vector bool int, vector bool int); 9733int vec_any_eq (vector bool int, vector unsigned int); 9734int vec_any_eq (vector bool int, vector signed int); 9735int vec_any_eq (vector float, vector float); 9736 9737int vec_any_ge (vector signed char, vector bool char); 9738int vec_any_ge (vector unsigned char, vector bool char); 9739int vec_any_ge (vector unsigned char, vector unsigned char); 9740int vec_any_ge (vector signed char, vector signed char); 9741int vec_any_ge (vector bool char, vector unsigned char); 9742int vec_any_ge (vector bool char, vector signed char); 9743int vec_any_ge (vector unsigned short, vector bool short); 9744int vec_any_ge (vector unsigned short, vector unsigned short); 9745int vec_any_ge (vector signed short, vector signed short); 9746int vec_any_ge (vector signed short, vector bool short); 9747int vec_any_ge (vector bool short, vector unsigned short); 9748int vec_any_ge (vector bool short, vector signed short); 9749int vec_any_ge (vector signed int, vector bool int); 9750int vec_any_ge (vector unsigned int, vector bool int); 9751int vec_any_ge (vector unsigned int, vector unsigned int); 9752int vec_any_ge (vector signed int, vector signed int); 9753int vec_any_ge (vector bool int, vector unsigned int); 9754int vec_any_ge (vector bool int, vector signed int); 9755int vec_any_ge (vector float, vector float); 9756 9757int vec_any_gt (vector bool char, vector unsigned char); 9758int vec_any_gt (vector unsigned char, vector bool char); 9759int vec_any_gt (vector unsigned char, vector unsigned char); 9760int vec_any_gt (vector bool char, vector signed char); 9761int vec_any_gt (vector signed char, vector bool char); 9762int vec_any_gt (vector signed char, vector signed char); 9763int vec_any_gt (vector bool short, vector unsigned short); 9764int vec_any_gt (vector unsigned short, vector bool short); 9765int vec_any_gt (vector unsigned short, vector unsigned short); 9766int vec_any_gt (vector bool short, vector signed short); 9767int vec_any_gt (vector signed short, vector bool short); 9768int vec_any_gt (vector signed short, vector signed short); 9769int vec_any_gt (vector bool int, vector unsigned int); 9770int vec_any_gt (vector unsigned int, vector bool int); 9771int vec_any_gt (vector unsigned int, vector unsigned int); 9772int vec_any_gt (vector bool int, vector signed int); 9773int vec_any_gt (vector signed int, vector bool int); 9774int vec_any_gt (vector signed int, vector signed int); 9775int vec_any_gt (vector float, vector float); 9776 9777int vec_any_le (vector bool char, vector unsigned char); 9778int vec_any_le (vector unsigned char, vector bool char); 9779int vec_any_le (vector unsigned char, vector unsigned char); 9780int vec_any_le (vector bool char, vector signed char); 9781int vec_any_le (vector signed char, vector bool char); 9782int vec_any_le (vector signed char, vector signed char); 9783int vec_any_le (vector bool short, vector unsigned short); 9784int vec_any_le (vector unsigned short, vector bool short); 9785int vec_any_le (vector unsigned short, vector unsigned short); 9786int vec_any_le (vector bool short, vector signed short); 9787int vec_any_le (vector signed short, vector bool short); 9788int vec_any_le (vector signed short, vector signed short); 9789int vec_any_le (vector bool int, vector unsigned int); 9790int vec_any_le (vector unsigned int, vector bool int); 9791int vec_any_le (vector unsigned int, vector unsigned int); 9792int vec_any_le (vector bool int, vector signed int); 9793int vec_any_le (vector signed int, vector bool int); 9794int vec_any_le (vector signed int, vector signed int); 9795int vec_any_le (vector float, vector float); 9796 9797int vec_any_lt (vector bool char, vector unsigned char); 9798int vec_any_lt (vector unsigned char, vector bool char); 9799int vec_any_lt (vector unsigned char, vector unsigned char); 9800int vec_any_lt (vector bool char, vector signed char); 9801int vec_any_lt (vector signed char, vector bool char); 9802int vec_any_lt (vector signed char, vector signed char); 9803int vec_any_lt (vector bool short, vector unsigned short); 9804int vec_any_lt (vector unsigned short, vector bool short); 9805int vec_any_lt (vector unsigned short, vector unsigned short); 9806int vec_any_lt (vector bool short, vector signed short); 9807int vec_any_lt (vector signed short, vector bool short); 9808int vec_any_lt (vector signed short, vector signed short); 9809int vec_any_lt (vector bool int, vector unsigned int); 9810int vec_any_lt (vector unsigned int, vector bool int); 9811int vec_any_lt (vector unsigned int, vector unsigned int); 9812int vec_any_lt (vector bool int, vector signed int); 9813int vec_any_lt (vector signed int, vector bool int); 9814int vec_any_lt (vector signed int, vector signed int); 9815int vec_any_lt (vector float, vector float); 9816 9817int vec_any_nan (vector float); 9818 9819int vec_any_ne (vector signed char, vector bool char); 9820int vec_any_ne (vector signed char, vector signed char); 9821int vec_any_ne (vector unsigned char, vector bool char); 9822int vec_any_ne (vector unsigned char, vector unsigned char); 9823int vec_any_ne (vector bool char, vector bool char); 9824int vec_any_ne (vector bool char, vector unsigned char); 9825int vec_any_ne (vector bool char, vector signed char); 9826int vec_any_ne (vector signed short, vector bool short); 9827int vec_any_ne (vector signed short, vector signed short); 9828int vec_any_ne (vector unsigned short, vector bool short); 9829int vec_any_ne (vector unsigned short, vector unsigned short); 9830int vec_any_ne (vector bool short, vector bool short); 9831int vec_any_ne (vector bool short, vector unsigned short); 9832int vec_any_ne (vector bool short, vector signed short); 9833int vec_any_ne (vector pixel, vector pixel); 9834int vec_any_ne (vector signed int, vector bool int); 9835int vec_any_ne (vector signed int, vector signed int); 9836int vec_any_ne (vector unsigned int, vector bool int); 9837int vec_any_ne (vector unsigned int, vector unsigned int); 9838int vec_any_ne (vector bool int, vector bool int); 9839int vec_any_ne (vector bool int, vector unsigned int); 9840int vec_any_ne (vector bool int, vector signed int); 9841int vec_any_ne (vector float, vector float); 9842 9843int vec_any_nge (vector float, vector float); 9844 9845int vec_any_ngt (vector float, vector float); 9846 9847int vec_any_nle (vector float, vector float); 9848 9849int vec_any_nlt (vector float, vector float); 9850 9851int vec_any_numeric (vector float); 9852 9853int vec_any_out (vector float, vector float); 9854@end smallexample 9855 9856@node SPARC VIS Built-in Functions 9857@subsection SPARC VIS Built-in Functions 9858 9859GCC supports SIMD operations on the SPARC using both the generic vector 9860extensions (@pxref{Vector Extensions}) as well as built-in functions for 9861the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} 9862switch, the VIS extension is exposed as the following built-in functions: 9863 9864@smallexample 9865typedef int v2si __attribute__ ((vector_size (8))); 9866typedef short v4hi __attribute__ ((vector_size (8))); 9867typedef short v2hi __attribute__ ((vector_size (4))); 9868typedef char v8qi __attribute__ ((vector_size (8))); 9869typedef char v4qi __attribute__ ((vector_size (4))); 9870 9871void * __builtin_vis_alignaddr (void *, long); 9872int64_t __builtin_vis_faligndatadi (int64_t, int64_t); 9873v2si __builtin_vis_faligndatav2si (v2si, v2si); 9874v4hi __builtin_vis_faligndatav4hi (v4si, v4si); 9875v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); 9876 9877v4hi __builtin_vis_fexpand (v4qi); 9878 9879v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); 9880v4hi __builtin_vis_fmul8x16au (v4qi, v4hi); 9881v4hi __builtin_vis_fmul8x16al (v4qi, v4hi); 9882v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); 9883v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); 9884v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); 9885v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); 9886 9887v4qi __builtin_vis_fpack16 (v4hi); 9888v8qi __builtin_vis_fpack32 (v2si, v2si); 9889v2hi __builtin_vis_fpackfix (v2si); 9890v8qi __builtin_vis_fpmerge (v4qi, v4qi); 9891 9892int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); 9893@end smallexample 9894 9895@node Target Format Checks 9896@section Format Checks Specific to Particular Target Machines 9897 9898For some target machines, GCC supports additional options to the 9899format attribute 9900(@pxref{Function Attributes,,Declaring Attributes of Functions}). 9901 9902@menu 9903* Solaris Format Checks:: 9904@end menu 9905 9906@node Solaris Format Checks 9907@subsection Solaris Format Checks 9908 9909Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format 9910check. @code{cmn_err} accepts a subset of the standard @code{printf} 9911conversions, and the two-argument @code{%b} conversion for displaying 9912bit-fields. See the Solaris man page for @code{cmn_err} for more information. 9913 9914@node Pragmas 9915@section Pragmas Accepted by GCC 9916@cindex pragmas 9917@cindex #pragma 9918 9919GCC supports several types of pragmas, primarily in order to compile 9920code originally written for other compilers. Note that in general 9921we do not recommend the use of pragmas; @xref{Function Attributes}, 9922for further explanation. 9923 9924@menu 9925* ARM Pragmas:: 9926* M32C Pragmas:: 9927* RS/6000 and PowerPC Pragmas:: 9928* Darwin Pragmas:: 9929* Solaris Pragmas:: 9930* Symbol-Renaming Pragmas:: 9931* Structure-Packing Pragmas:: 9932* Weak Pragmas:: 9933* Diagnostic Pragmas:: 9934* Visibility Pragmas:: 9935@end menu 9936 9937@node ARM Pragmas 9938@subsection ARM Pragmas 9939 9940The ARM target defines pragmas for controlling the default addition of 9941@code{long_call} and @code{short_call} attributes to functions. 9942@xref{Function Attributes}, for information about the effects of these 9943attributes. 9944 9945@table @code 9946@item long_calls 9947@cindex pragma, long_calls 9948Set all subsequent functions to have the @code{long_call} attribute. 9949 9950@item no_long_calls 9951@cindex pragma, no_long_calls 9952Set all subsequent functions to have the @code{short_call} attribute. 9953 9954@item long_calls_off 9955@cindex pragma, long_calls_off 9956Do not affect the @code{long_call} or @code{short_call} attributes of 9957subsequent functions. 9958@end table 9959 9960@node M32C Pragmas 9961@subsection M32C Pragmas 9962 9963@table @code 9964@item memregs @var{number} 9965@cindex pragma, memregs 9966Overrides the command line option @code{-memregs=} for the current 9967file. Use with care! This pragma must be before any function in the 9968file, and mixing different memregs values in different objects may 9969make them incompatible. This pragma is useful when a 9970performance-critical function uses a memreg for temporary values, 9971as it may allow you to reduce the number of memregs used. 9972 9973@end table 9974 9975@node RS/6000 and PowerPC Pragmas 9976@subsection RS/6000 and PowerPC Pragmas 9977 9978The RS/6000 and PowerPC targets define one pragma for controlling 9979whether or not the @code{longcall} attribute is added to function 9980declarations by default. This pragma overrides the @option{-mlongcall} 9981option, but not the @code{longcall} and @code{shortcall} attributes. 9982@xref{RS/6000 and PowerPC Options}, for more information about when long 9983calls are and are not necessary. 9984 9985@table @code 9986@item longcall (1) 9987@cindex pragma, longcall 9988Apply the @code{longcall} attribute to all subsequent function 9989declarations. 9990 9991@item longcall (0) 9992Do not apply the @code{longcall} attribute to subsequent function 9993declarations. 9994@end table 9995 9996@c Describe c4x pragmas here. 9997@c Describe h8300 pragmas here. 9998@c Describe sh pragmas here. 9999@c Describe v850 pragmas here. 10000 10001@node Darwin Pragmas 10002@subsection Darwin Pragmas 10003 10004The following pragmas are available for all architectures running the 10005Darwin operating system. These are useful for compatibility with other 10006Mac OS compilers. 10007 10008@table @code 10009@item mark @var{tokens}@dots{} 10010@cindex pragma, mark 10011This pragma is accepted, but has no effect. 10012 10013@item options align=@var{alignment} 10014@cindex pragma, options align 10015This pragma sets the alignment of fields in structures. The values of 10016@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or 10017@code{power}, to emulate PowerPC alignment. Uses of this pragma nest 10018properly; to restore the previous setting, use @code{reset} for the 10019@var{alignment}. 10020 10021@item segment @var{tokens}@dots{} 10022@cindex pragma, segment 10023This pragma is accepted, but has no effect. 10024 10025@item unused (@var{var} [, @var{var}]@dots{}) 10026@cindex pragma, unused 10027This pragma declares variables to be possibly unused. GCC will not 10028produce warnings for the listed variables. The effect is similar to 10029that of the @code{unused} attribute, except that this pragma may appear 10030anywhere within the variables' scopes. 10031@end table 10032 10033@node Solaris Pragmas 10034@subsection Solaris Pragmas 10035 10036The Solaris target supports @code{#pragma redefine_extname} 10037(@pxref{Symbol-Renaming Pragmas}). It also supports additional 10038@code{#pragma} directives for compatibility with the system compiler. 10039 10040@table @code 10041@item align @var{alignment} (@var{variable} [, @var{variable}]...) 10042@cindex pragma, align 10043 10044Increase the minimum alignment of each @var{variable} to @var{alignment}. 10045This is the same as GCC's @code{aligned} attribute @pxref{Variable 10046Attributes}). Macro expansion occurs on the arguments to this pragma 10047when compiling C. It does not currently occur when compiling C++, but 10048this is a bug which may be fixed in a future release. 10049 10050@item fini (@var{function} [, @var{function}]...) 10051@cindex pragma, fini 10052 10053This pragma causes each listed @var{function} to be called after 10054main, or during shared module unloading, by adding a call to the 10055@code{.fini} section. 10056 10057@item init (@var{function} [, @var{function}]...) 10058@cindex pragma, init 10059 10060This pragma causes each listed @var{function} to be called during 10061initialization (before @code{main}) or during shared module loading, by 10062adding a call to the @code{.init} section. 10063 10064@end table 10065 10066@node Symbol-Renaming Pragmas 10067@subsection Symbol-Renaming Pragmas 10068 10069For compatibility with the Solaris and Tru64 UNIX system headers, GCC 10070supports two @code{#pragma} directives which change the name used in 10071assembly for a given declaration. These pragmas are only available on 10072platforms whose system headers need them. To get this effect on all 10073platforms supported by GCC, use the asm labels extension (@pxref{Asm 10074Labels}). 10075 10076@table @code 10077@item redefine_extname @var{oldname} @var{newname} 10078@cindex pragma, redefine_extname 10079 10080This pragma gives the C function @var{oldname} the assembly symbol 10081@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} 10082will be defined if this pragma is available (currently only on 10083Solaris). 10084 10085@item extern_prefix @var{string} 10086@cindex pragma, extern_prefix 10087 10088This pragma causes all subsequent external function and variable 10089declarations to have @var{string} prepended to their assembly symbols. 10090This effect may be terminated with another @code{extern_prefix} pragma 10091whose argument is an empty string. The preprocessor macro 10092@code{__PRAGMA_EXTERN_PREFIX} will be defined if this pragma is 10093available (currently only on Tru64 UNIX)@. 10094@end table 10095 10096These pragmas and the asm labels extension interact in a complicated 10097manner. Here are some corner cases you may want to be aware of. 10098 10099@enumerate 10100@item Both pragmas silently apply only to declarations with external 10101linkage. Asm labels do not have this restriction. 10102 10103@item In C++, both pragmas silently apply only to declarations with 10104``C'' linkage. Again, asm labels do not have this restriction. 10105 10106@item If any of the three ways of changing the assembly name of a 10107declaration is applied to a declaration whose assembly name has 10108already been determined (either by a previous use of one of these 10109features, or because the compiler needed the assembly name in order to 10110generate code), and the new name is different, a warning issues and 10111the name does not change. 10112 10113@item The @var{oldname} used by @code{#pragma redefine_extname} is 10114always the C-language name. 10115 10116@item If @code{#pragma extern_prefix} is in effect, and a declaration 10117occurs with an asm label attached, the prefix is silently ignored for 10118that declaration. 10119 10120@item If @code{#pragma extern_prefix} and @code{#pragma redefine_extname} 10121apply to the same declaration, whichever triggered first wins, and a 10122warning issues if they contradict each other. (We would like to have 10123@code{#pragma redefine_extname} always win, for consistency with asm 10124labels, but if @code{#pragma extern_prefix} triggers first we have no 10125way of knowing that that happened.) 10126@end enumerate 10127 10128@node Structure-Packing Pragmas 10129@subsection Structure-Packing Pragmas 10130 10131For compatibility with Win32, GCC supports a set of @code{#pragma} 10132directives which change the maximum alignment of members of structures 10133(other than zero-width bitfields), unions, and classes subsequently 10134defined. The @var{n} value below always is required to be a small power 10135of two and specifies the new alignment in bytes. 10136 10137@enumerate 10138@item @code{#pragma pack(@var{n})} simply sets the new alignment. 10139@item @code{#pragma pack()} sets the alignment to the one that was in 10140effect when compilation started (see also command line option 10141@option{-fpack-struct[=<n>]} @pxref{Code Gen Options}). 10142@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment 10143setting on an internal stack and then optionally sets the new alignment. 10144@item @code{#pragma pack(pop)} restores the alignment setting to the one 10145saved at the top of the internal stack (and removes that stack entry). 10146Note that @code{#pragma pack([@var{n}])} does not influence this internal 10147stack; thus it is possible to have @code{#pragma pack(push)} followed by 10148multiple @code{#pragma pack(@var{n})} instances and finalized by a single 10149@code{#pragma pack(pop)}. 10150@end enumerate 10151 10152Some targets, e.g. i386 and powerpc, support the @code{ms_struct} 10153@code{#pragma} which lays out a structure as the documented 10154@code{__attribute__ ((ms_struct))}. 10155@enumerate 10156@item @code{#pragma ms_struct on} turns on the layout for structures 10157declared. 10158@item @code{#pragma ms_struct off} turns off the layout for structures 10159declared. 10160@item @code{#pragma ms_struct reset} goes back to the default layout. 10161@end enumerate 10162 10163@node Weak Pragmas 10164@subsection Weak Pragmas 10165 10166For compatibility with SVR4, GCC supports a set of @code{#pragma} 10167directives for declaring symbols to be weak, and defining weak 10168aliases. 10169 10170@table @code 10171@item #pragma weak @var{symbol} 10172@cindex pragma, weak 10173This pragma declares @var{symbol} to be weak, as if the declaration 10174had the attribute of the same name. The pragma may appear before 10175or after the declaration of @var{symbol}, but must appear before 10176either its first use or its definition. It is not an error for 10177@var{symbol} to never be defined at all. 10178 10179@item #pragma weak @var{symbol1} = @var{symbol2} 10180This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. 10181It is an error if @var{symbol2} is not defined in the current 10182translation unit. 10183@end table 10184 10185@node Diagnostic Pragmas 10186@subsection Diagnostic Pragmas 10187 10188GCC allows the user to selectively enable or disable certain types of 10189diagnostics, and change the kind of the diagnostic. For example, a 10190project's policy might require that all sources compile with 10191@option{-Werror} but certain files might have exceptions allowing 10192specific types of warnings. Or, a project might selectively enable 10193diagnostics and treat them as errors depending on which preprocessor 10194macros are defined. 10195 10196@table @code 10197@item #pragma GCC diagnostic @var{kind} @var{option} 10198@cindex pragma, diagnostic 10199 10200Modifies the disposition of a diagnostic. Note that not all 10201diagnostics are modifiable; at the moment only warnings (normally 10202controlled by @samp{-W...}) can be controlled, and not all of them. 10203Use @option{-fdiagnostics-show-option} to determine which diagnostics 10204are controllable and which option controls them. 10205 10206@var{kind} is @samp{error} to treat this diagnostic as an error, 10207@samp{warning} to treat it like a warning (even if @option{-Werror} is 10208in effect), or @samp{ignored} if the diagnostic is to be ignored. 10209@var{option} is a double quoted string which matches the command line 10210option. 10211 10212@example 10213#pragma GCC diagnostic warning "-Wformat" 10214#pragma GCC diagnostic error "-Wformat" 10215#pragma GCC diagnostic ignored "-Wformat" 10216@end example 10217 10218Note that these pragmas override any command line options. Also, 10219while it is syntactically valid to put these pragmas anywhere in your 10220sources, the only supported location for them is before any data or 10221functions are defined. Doing otherwise may result in unpredictable 10222results depending on how the optimizer manages your sources. If the 10223same option is listed multiple times, the last one specified is the 10224one that is in effect. This pragma is not intended to be a general 10225purpose replacement for command line options, but for implementing 10226strict control over project policies. 10227 10228@end table 10229 10230@node Visibility Pragmas 10231@subsection Visibility Pragmas 10232 10233@table @code 10234@item #pragma GCC visibility push(@var{visibility}) 10235@itemx #pragma GCC visibility pop 10236@cindex pragma, visibility 10237 10238This pragma allows the user to set the visibility for multiple 10239declarations without having to give each a visibility attribute 10240@xref{Function Attributes}, for more information about visibility and 10241the attribute syntax. 10242 10243In C++, @samp{#pragma GCC visibility} affects only namespace-scope 10244declarations. Class members and template specializations are not 10245affected; if you want to override the visibility for a particular 10246member or instantiation, you must use an attribute. 10247 10248@end table 10249 10250@node Unnamed Fields 10251@section Unnamed struct/union fields within structs/unions 10252@cindex struct 10253@cindex union 10254 10255For compatibility with other compilers, GCC allows you to define 10256a structure or union that contains, as fields, structures and unions 10257without names. For example: 10258 10259@smallexample 10260struct @{ 10261 int a; 10262 union @{ 10263 int b; 10264 float c; 10265 @}; 10266 int d; 10267@} foo; 10268@end smallexample 10269 10270In this example, the user would be able to access members of the unnamed 10271union with code like @samp{foo.b}. Note that only unnamed structs and 10272unions are allowed, you may not have, for example, an unnamed 10273@code{int}. 10274 10275You must never create such structures that cause ambiguous field definitions. 10276For example, this structure: 10277 10278@smallexample 10279struct @{ 10280 int a; 10281 struct @{ 10282 int a; 10283 @}; 10284@} foo; 10285@end smallexample 10286 10287It is ambiguous which @code{a} is being referred to with @samp{foo.a}. 10288Such constructs are not supported and must be avoided. In the future, 10289such constructs may be detected and treated as compilation errors. 10290 10291@opindex fms-extensions 10292Unless @option{-fms-extensions} is used, the unnamed field must be a 10293structure or union definition without a tag (for example, @samp{struct 10294@{ int a; @};}). If @option{-fms-extensions} is used, the field may 10295also be a definition with a tag such as @samp{struct foo @{ int a; 10296@};}, a reference to a previously defined structure or union such as 10297@samp{struct foo;}, or a reference to a @code{typedef} name for a 10298previously defined structure or union type. 10299 10300@node Thread-Local 10301@section Thread-Local Storage 10302@cindex Thread-Local Storage 10303@cindex @acronym{TLS} 10304@cindex __thread 10305 10306Thread-local storage (@acronym{TLS}) is a mechanism by which variables 10307are allocated such that there is one instance of the variable per extant 10308thread. The run-time model GCC uses to implement this originates 10309in the IA-64 processor-specific ABI, but has since been migrated 10310to other processors as well. It requires significant support from 10311the linker (@command{ld}), dynamic linker (@command{ld.so}), and 10312system libraries (@file{libc.so} and @file{libpthread.so}), so it 10313is not available everywhere. 10314 10315At the user level, the extension is visible with a new storage 10316class keyword: @code{__thread}. For example: 10317 10318@smallexample 10319__thread int i; 10320extern __thread struct state s; 10321static __thread char *p; 10322@end smallexample 10323 10324The @code{__thread} specifier may be used alone, with the @code{extern} 10325or @code{static} specifiers, but with no other storage class specifier. 10326When used with @code{extern} or @code{static}, @code{__thread} must appear 10327immediately after the other storage class specifier. 10328 10329The @code{__thread} specifier may be applied to any global, file-scoped 10330static, function-scoped static, or static data member of a class. It may 10331not be applied to block-scoped automatic or non-static data member. 10332 10333When the address-of operator is applied to a thread-local variable, it is 10334evaluated at run-time and returns the address of the current thread's 10335instance of that variable. An address so obtained may be used by any 10336thread. When a thread terminates, any pointers to thread-local variables 10337in that thread become invalid. 10338 10339No static initialization may refer to the address of a thread-local variable. 10340 10341In C++, if an initializer is present for a thread-local variable, it must 10342be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ 10343standard. 10344 10345See @uref{http://people.redhat.com/drepper/tls.pdf, 10346ELF Handling For Thread-Local Storage} for a detailed explanation of 10347the four thread-local storage addressing models, and how the run-time 10348is expected to function. 10349 10350@menu 10351* C99 Thread-Local Edits:: 10352* C++98 Thread-Local Edits:: 10353@end menu 10354 10355@node C99 Thread-Local Edits 10356@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage 10357 10358The following are a set of changes to ISO/IEC 9899:1999 (aka C99) 10359that document the exact semantics of the language extension. 10360 10361@itemize @bullet 10362@item 10363@cite{5.1.2 Execution environments} 10364 10365Add new text after paragraph 1 10366 10367@quotation 10368Within either execution environment, a @dfn{thread} is a flow of 10369control within a program. It is implementation defined whether 10370or not there may be more than one thread associated with a program. 10371It is implementation defined how threads beyond the first are 10372created, the name and type of the function called at thread 10373startup, and how threads may be terminated. However, objects 10374with thread storage duration shall be initialized before thread 10375startup. 10376@end quotation 10377 10378@item 10379@cite{6.2.4 Storage durations of objects} 10380 10381Add new text before paragraph 3 10382 10383@quotation 10384An object whose identifier is declared with the storage-class 10385specifier @w{@code{__thread}} has @dfn{thread storage duration}. 10386Its lifetime is the entire execution of the thread, and its 10387stored value is initialized only once, prior to thread startup. 10388@end quotation 10389 10390@item 10391@cite{6.4.1 Keywords} 10392 10393Add @code{__thread}. 10394 10395@item 10396@cite{6.7.1 Storage-class specifiers} 10397 10398Add @code{__thread} to the list of storage class specifiers in 10399paragraph 1. 10400 10401Change paragraph 2 to 10402 10403@quotation 10404With the exception of @code{__thread}, at most one storage-class 10405specifier may be given [@dots{}]. The @code{__thread} specifier may 10406be used alone, or immediately following @code{extern} or 10407@code{static}. 10408@end quotation 10409 10410Add new text after paragraph 6 10411 10412@quotation 10413The declaration of an identifier for a variable that has 10414block scope that specifies @code{__thread} shall also 10415specify either @code{extern} or @code{static}. 10416 10417The @code{__thread} specifier shall be used only with 10418variables. 10419@end quotation 10420@end itemize 10421 10422@node C++98 Thread-Local Edits 10423@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage 10424 10425The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) 10426that document the exact semantics of the language extension. 10427 10428@itemize @bullet 10429@item 10430@b{[intro.execution]} 10431 10432New text after paragraph 4 10433 10434@quotation 10435A @dfn{thread} is a flow of control within the abstract machine. 10436It is implementation defined whether or not there may be more than 10437one thread. 10438@end quotation 10439 10440New text after paragraph 7 10441 10442@quotation 10443It is unspecified whether additional action must be taken to 10444ensure when and whether side effects are visible to other threads. 10445@end quotation 10446 10447@item 10448@b{[lex.key]} 10449 10450Add @code{__thread}. 10451 10452@item 10453@b{[basic.start.main]} 10454 10455Add after paragraph 5 10456 10457@quotation 10458The thread that begins execution at the @code{main} function is called 10459the @dfn{main thread}. It is implementation defined how functions 10460beginning threads other than the main thread are designated or typed. 10461A function so designated, as well as the @code{main} function, is called 10462a @dfn{thread startup function}. It is implementation defined what 10463happens if a thread startup function returns. It is implementation 10464defined what happens to other threads when any thread calls @code{exit}. 10465@end quotation 10466 10467@item 10468@b{[basic.start.init]} 10469 10470Add after paragraph 4 10471 10472@quotation 10473The storage for an object of thread storage duration shall be 10474statically initialized before the first statement of the thread startup 10475function. An object of thread storage duration shall not require 10476dynamic initialization. 10477@end quotation 10478 10479@item 10480@b{[basic.start.term]} 10481 10482Add after paragraph 3 10483 10484@quotation 10485The type of an object with thread storage duration shall not have a 10486non-trivial destructor, nor shall it be an array type whose elements 10487(directly or indirectly) have non-trivial destructors. 10488@end quotation 10489 10490@item 10491@b{[basic.stc]} 10492 10493Add ``thread storage duration'' to the list in paragraph 1. 10494 10495Change paragraph 2 10496 10497@quotation 10498Thread, static, and automatic storage durations are associated with 10499objects introduced by declarations [@dots{}]. 10500@end quotation 10501 10502Add @code{__thread} to the list of specifiers in paragraph 3. 10503 10504@item 10505@b{[basic.stc.thread]} 10506 10507New section before @b{[basic.stc.static]} 10508 10509@quotation 10510The keyword @code{__thread} applied to a non-local object gives the 10511object thread storage duration. 10512 10513A local variable or class data member declared both @code{static} 10514and @code{__thread} gives the variable or member thread storage 10515duration. 10516@end quotation 10517 10518@item 10519@b{[basic.stc.static]} 10520 10521Change paragraph 1 10522 10523@quotation 10524All objects which have neither thread storage duration, dynamic 10525storage duration nor are local [@dots{}]. 10526@end quotation 10527 10528@item 10529@b{[dcl.stc]} 10530 10531Add @code{__thread} to the list in paragraph 1. 10532 10533Change paragraph 1 10534 10535@quotation 10536With the exception of @code{__thread}, at most one 10537@var{storage-class-specifier} shall appear in a given 10538@var{decl-specifier-seq}. The @code{__thread} specifier may 10539be used alone, or immediately following the @code{extern} or 10540@code{static} specifiers. [@dots{}] 10541@end quotation 10542 10543Add after paragraph 5 10544 10545@quotation 10546The @code{__thread} specifier can be applied only to the names of objects 10547and to anonymous unions. 10548@end quotation 10549 10550@item 10551@b{[class.mem]} 10552 10553Add after paragraph 6 10554 10555@quotation 10556Non-@code{static} members shall not be @code{__thread}. 10557@end quotation 10558@end itemize 10559 10560@c APPLE LOCAL begin blocks 7205047 5811887 10561@node Blocks 10562@section Blocks 10563@cindex Blocks 10564@cindex __block 10565 10566Blocks is a language feature that allows one to create anonymous 10567functions. The feature is also known as lambdas or closures in other 10568languages. The feature is controlled by @option{-fblocks}. 10569See @uref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html} for additional details. 10570@c APPLE LOCAL end blocks 7205047 5811887 10571 10572@node Binary constants 10573@section Binary constants using the @samp{0b} prefix 10574@cindex Binary constants using the @samp{0b} prefix 10575 10576Integer constants can be written as binary constants, consisting of a 10577sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or 10578@samp{0B}. This is particularly useful in environments that operate a 10579lot on the bit-level (like microcontrollers). 10580 10581The following statements are identical: 10582 10583@smallexample 10584i = 42; 10585i = 0x2a; 10586i = 052; 10587i = 0b101010; 10588@end smallexample 10589 10590The type of these constants follows the same rules as for octal or 10591hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} 10592can be applied. 10593 10594@node C++ Extensions 10595@chapter Extensions to the C++ Language 10596@cindex extensions, C++ language 10597@cindex C++ language extensions 10598 10599The GNU compiler provides these extensions to the C++ language (and you 10600can also use most of the C language extensions in your C++ programs). If you 10601want to write code that checks whether these features are available, you can 10602test for the GNU compiler the same way as for C programs: check for a 10603predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to 10604test specifically for GNU C++ (@pxref{Common Predefined Macros,, 10605Predefined Macros,cpp,The GNU C Preprocessor}). 10606 10607@menu 10608* Volatiles:: What constitutes an access to a volatile object. 10609* Restricted Pointers:: C99 restricted pointers and references. 10610* Vague Linkage:: Where G++ puts inlines, vtables and such. 10611* C++ Interface:: You can use a single C++ header file for both 10612 declarations and definitions. 10613* Template Instantiation:: Methods for ensuring that exactly one copy of 10614 each needed template instantiation is emitted. 10615* Bound member functions:: You can extract a function pointer to the 10616 method denoted by a @samp{->*} or @samp{.*} expression. 10617* C++ Attributes:: Variable, function, and type attributes for C++ only. 10618* Namespace Association:: Strong using-directives for namespace association. 10619* Java Exceptions:: Tweaking exception handling to work with Java. 10620* Deprecated Features:: Things will disappear from g++. 10621* Backwards Compatibility:: Compatibilities with earlier definitions of C++. 10622@end menu 10623 10624@node Volatiles 10625@section When is a Volatile Object Accessed? 10626@cindex accessing volatiles 10627@cindex volatile read 10628@cindex volatile write 10629@cindex volatile access 10630 10631Both the C and C++ standard have the concept of volatile objects. These 10632are normally accessed by pointers and used for accessing hardware. The 10633standards encourage compilers to refrain from optimizations concerning 10634accesses to volatile objects. The C standard leaves it implementation 10635defined as to what constitutes a volatile access. The C++ standard omits 10636to specify this, except to say that C++ should behave in a similar manner 10637to C with respect to volatiles, where possible. The minimum either 10638standard specifies is that at a sequence point all previous accesses to 10639volatile objects have stabilized and no subsequent accesses have 10640occurred. Thus an implementation is free to reorder and combine 10641volatile accesses which occur between sequence points, but cannot do so 10642for accesses across a sequence point. The use of volatiles does not 10643allow you to violate the restriction on updating objects multiple times 10644within a sequence point. 10645 10646@xref{Qualifiers implementation, , Volatile qualifier and the C compiler}. 10647 10648The behavior differs slightly between C and C++ in the non-obvious cases: 10649 10650@smallexample 10651volatile int *src = @var{somevalue}; 10652*src; 10653@end smallexample 10654 10655With C, such expressions are rvalues, and GCC interprets this either as a 10656read of the volatile object being pointed to or only as request to evaluate 10657the side-effects. The C++ standard specifies that such expressions do not 10658undergo lvalue to rvalue conversion, and that the type of the dereferenced 10659object may be incomplete. The C++ standard does not specify explicitly 10660that it is this lvalue to rvalue conversion which may be responsible for 10661causing an access. However, there is reason to believe that it is, 10662because otherwise certain simple expressions become undefined. However, 10663because it would surprise most programmers, G++ treats dereferencing a 10664pointer to volatile object of complete type when the value is unused as 10665GCC would do for an equivalent type in C. When the object has incomplete 10666type, G++ issues a warning; if you wish to force an error, you must 10667force a conversion to rvalue with, for instance, a static cast. 10668 10669When using a reference to volatile, G++ does not treat equivalent 10670expressions as accesses to volatiles, but instead issues a warning that 10671no volatile is accessed. The rationale for this is that otherwise it 10672becomes difficult to determine where volatile access occur, and not 10673possible to ignore the return value from functions returning volatile 10674references. Again, if you wish to force a read, cast the reference to 10675an rvalue. 10676 10677@node Restricted Pointers 10678@section Restricting Pointer Aliasing 10679@cindex restricted pointers 10680@cindex restricted references 10681@cindex restricted this pointer 10682 10683As with the C front end, G++ understands the C99 feature of restricted pointers, 10684specified with the @code{__restrict__}, or @code{__restrict} type 10685qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} 10686language flag, @code{restrict} is not a keyword in C++. 10687 10688In addition to allowing restricted pointers, you can specify restricted 10689references, which indicate that the reference is not aliased in the local 10690context. 10691 10692@smallexample 10693void fn (int *__restrict__ rptr, int &__restrict__ rref) 10694@{ 10695 /* @r{@dots{}} */ 10696@} 10697@end smallexample 10698 10699@noindent 10700In the body of @code{fn}, @var{rptr} points to an unaliased integer and 10701@var{rref} refers to a (different) unaliased integer. 10702 10703You may also specify whether a member function's @var{this} pointer is 10704unaliased by using @code{__restrict__} as a member function qualifier. 10705 10706@smallexample 10707void T::fn () __restrict__ 10708@{ 10709 /* @r{@dots{}} */ 10710@} 10711@end smallexample 10712 10713@noindent 10714Within the body of @code{T::fn}, @var{this} will have the effective 10715definition @code{T *__restrict__ const this}. Notice that the 10716interpretation of a @code{__restrict__} member function qualifier is 10717different to that of @code{const} or @code{volatile} qualifier, in that it 10718is applied to the pointer rather than the object. This is consistent with 10719other compilers which implement restricted pointers. 10720 10721As with all outermost parameter qualifiers, @code{__restrict__} is 10722ignored in function definition matching. This means you only need to 10723specify @code{__restrict__} in a function definition, rather than 10724in a function prototype as well. 10725 10726@node Vague Linkage 10727@section Vague Linkage 10728@cindex vague linkage 10729 10730There are several constructs in C++ which require space in the object 10731file but are not clearly tied to a single translation unit. We say that 10732these constructs have ``vague linkage''. Typically such constructs are 10733emitted wherever they are needed, though sometimes we can be more 10734clever. 10735 10736@table @asis 10737@item Inline Functions 10738Inline functions are typically defined in a header file which can be 10739included in many different compilations. Hopefully they can usually be 10740inlined, but sometimes an out-of-line copy is necessary, if the address 10741of the function is taken or if inlining fails. In general, we emit an 10742out-of-line copy in all translation units where one is needed. As an 10743exception, we only emit inline virtual functions with the vtable, since 10744it will always require a copy. 10745 10746Local static variables and string constants used in an inline function 10747are also considered to have vague linkage, since they must be shared 10748between all inlined and out-of-line instances of the function. 10749 10750@item VTables 10751@cindex vtable 10752C++ virtual functions are implemented in most compilers using a lookup 10753table, known as a vtable. The vtable contains pointers to the virtual 10754functions provided by a class, and each object of the class contains a 10755pointer to its vtable (or vtables, in some multiple-inheritance 10756situations). If the class declares any non-inline, non-pure virtual 10757functions, the first one is chosen as the ``key method'' for the class, 10758and the vtable is only emitted in the translation unit where the key 10759method is defined. 10760 10761@emph{Note:} If the chosen key method is later defined as inline, the 10762vtable will still be emitted in every translation unit which defines it. 10763Make sure that any inline virtuals are declared inline in the class 10764body, even if they are not defined there. 10765 10766@item type_info objects 10767@cindex type_info 10768@cindex RTTI 10769C++ requires information about types to be written out in order to 10770implement @samp{dynamic_cast}, @samp{typeid} and exception handling. 10771For polymorphic classes (classes with virtual functions), the type_info 10772object is written out along with the vtable so that @samp{dynamic_cast} 10773can determine the dynamic type of a class object at runtime. For all 10774other types, we write out the type_info object when it is used: when 10775applying @samp{typeid} to an expression, throwing an object, or 10776referring to a type in a catch clause or exception specification. 10777 10778@item Template Instantiations 10779Most everything in this section also applies to template instantiations, 10780but there are other options as well. 10781@xref{Template Instantiation,,Where's the Template?}. 10782 10783@end table 10784 10785When used with GNU ld version 2.8 or later on an ELF system such as 10786GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of 10787these constructs will be discarded at link time. This is known as 10788COMDAT support. 10789 10790On targets that don't support COMDAT, but do support weak symbols, GCC 10791will use them. This way one copy will override all the others, but 10792the unused copies will still take up space in the executable. 10793 10794For targets which do not support either COMDAT or weak symbols, 10795most entities with vague linkage will be emitted as local symbols to 10796avoid duplicate definition errors from the linker. This will not happen 10797for local statics in inlines, however, as having multiple copies will 10798almost certainly break things. 10799 10800@xref{C++ Interface,,Declarations and Definitions in One Header}, for 10801another way to control placement of these constructs. 10802 10803@node C++ Interface 10804@section #pragma interface and implementation 10805 10806@cindex interface and implementation headers, C++ 10807@cindex C++ interface and implementation headers 10808@cindex pragmas, interface and implementation 10809 10810@code{#pragma interface} and @code{#pragma implementation} provide the 10811user with a way of explicitly directing the compiler to emit entities 10812with vague linkage (and debugging information) in a particular 10813translation unit. 10814 10815@emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in 10816most cases, because of COMDAT support and the ``key method'' heuristic 10817mentioned in @ref{Vague Linkage}. Using them can actually cause your 10818program to grow due to unnecessary out-of-line copies of inline 10819functions. Currently (3.4) the only benefit of these 10820@code{#pragma}s is reduced duplication of debugging information, and 10821that should be addressed soon on DWARF 2 targets with the use of 10822COMDAT groups. 10823 10824@table @code 10825@item #pragma interface 10826@itemx #pragma interface "@var{subdir}/@var{objects}.h" 10827@kindex #pragma interface 10828Use this directive in @emph{header files} that define object classes, to save 10829space in most of the object files that use those classes. Normally, 10830local copies of certain information (backup copies of inline member 10831functions, debugging information, and the internal tables that implement 10832virtual functions) must be kept in each object file that includes class 10833definitions. You can use this pragma to avoid such duplication. When a 10834header file containing @samp{#pragma interface} is included in a 10835compilation, this auxiliary information will not be generated (unless 10836the main input source file itself uses @samp{#pragma implementation}). 10837Instead, the object files will contain references to be resolved at link 10838time. 10839 10840The second form of this directive is useful for the case where you have 10841multiple headers with the same name in different directories. If you 10842use this form, you must specify the same string to @samp{#pragma 10843implementation}. 10844 10845@item #pragma implementation 10846@itemx #pragma implementation "@var{objects}.h" 10847@kindex #pragma implementation 10848Use this pragma in a @emph{main input file}, when you want full output from 10849included header files to be generated (and made globally visible). The 10850included header file, in turn, should use @samp{#pragma interface}. 10851Backup copies of inline member functions, debugging information, and the 10852internal tables used to implement virtual functions are all generated in 10853implementation files. 10854 10855@cindex implied @code{#pragma implementation} 10856@cindex @code{#pragma implementation}, implied 10857@cindex naming convention, implementation headers 10858If you use @samp{#pragma implementation} with no argument, it applies to 10859an include file with the same basename@footnote{A file's @dfn{basename} 10860was the name stripped of all leading path information and of trailing 10861suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source 10862file. For example, in @file{allclass.cc}, giving just 10863@samp{#pragma implementation} 10864by itself is equivalent to @samp{#pragma implementation "allclass.h"}. 10865 10866In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as 10867an implementation file whenever you would include it from 10868@file{allclass.cc} even if you never specified @samp{#pragma 10869implementation}. This was deemed to be more trouble than it was worth, 10870however, and disabled. 10871 10872Use the string argument if you want a single implementation file to 10873include code from multiple header files. (You must also use 10874@samp{#include} to include the header file; @samp{#pragma 10875implementation} only specifies how to use the file---it doesn't actually 10876include it.) 10877 10878There is no way to split up the contents of a single header file into 10879multiple implementation files. 10880@end table 10881 10882@cindex inlining and C++ pragmas 10883@cindex C++ pragmas, effect on inlining 10884@cindex pragmas in C++, effect on inlining 10885@samp{#pragma implementation} and @samp{#pragma interface} also have an 10886effect on function inlining. 10887 10888If you define a class in a header file marked with @samp{#pragma 10889interface}, the effect on an inline function defined in that class is 10890similar to an explicit @code{extern} declaration---the compiler emits 10891no code at all to define an independent version of the function. Its 10892definition is used only for inlining with its callers. 10893 10894@opindex fno-implement-inlines 10895Conversely, when you include the same header file in a main source file 10896that declares it as @samp{#pragma implementation}, the compiler emits 10897code for the function itself; this defines a version of the function 10898that can be found via pointers (or by callers compiled without 10899inlining). If all calls to the function can be inlined, you can avoid 10900emitting the function by compiling with @option{-fno-implement-inlines}. 10901If any calls were not inlined, you will get linker errors. 10902 10903@node Template Instantiation 10904@section Where's the Template? 10905@cindex template instantiation 10906 10907C++ templates are the first language feature to require more 10908intelligence from the environment than one usually finds on a UNIX 10909system. Somehow the compiler and linker have to make sure that each 10910template instance occurs exactly once in the executable if it is needed, 10911and not at all otherwise. There are two basic approaches to this 10912problem, which are referred to as the Borland model and the Cfront model. 10913 10914@table @asis 10915@item Borland model 10916Borland C++ solved the template instantiation problem by adding the code 10917equivalent of common blocks to their linker; the compiler emits template 10918instances in each translation unit that uses them, and the linker 10919collapses them together. The advantage of this model is that the linker 10920only has to consider the object files themselves; there is no external 10921complexity to worry about. This disadvantage is that compilation time 10922is increased because the template code is being compiled repeatedly. 10923Code written for this model tends to include definitions of all 10924templates in the header file, since they must be seen to be 10925instantiated. 10926 10927@item Cfront model 10928The AT&T C++ translator, Cfront, solved the template instantiation 10929problem by creating the notion of a template repository, an 10930automatically maintained place where template instances are stored. A 10931more modern version of the repository works as follows: As individual 10932object files are built, the compiler places any template definitions and 10933instantiations encountered in the repository. At link time, the link 10934wrapper adds in the objects in the repository and compiles any needed 10935instances that were not previously emitted. The advantages of this 10936model are more optimal compilation speed and the ability to use the 10937system linker; to implement the Borland model a compiler vendor also 10938needs to replace the linker. The disadvantages are vastly increased 10939complexity, and thus potential for error; for some code this can be 10940just as transparent, but in practice it can been very difficult to build 10941multiple programs in one directory and one program in multiple 10942directories. Code written for this model tends to separate definitions 10943of non-inline member templates into a separate file, which should be 10944compiled separately. 10945@end table 10946 10947When used with GNU ld version 2.8 or later on an ELF system such as 10948GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the 10949Borland model. On other systems, G++ implements neither automatic 10950model. 10951 10952A future version of G++ will support a hybrid model whereby the compiler 10953will emit any instantiations for which the template definition is 10954included in the compile, and store template definitions and 10955instantiation context information into the object file for the rest. 10956The link wrapper will extract that information as necessary and invoke 10957the compiler to produce the remaining instantiations. The linker will 10958then combine duplicate instantiations. 10959 10960In the mean time, you have the following options for dealing with 10961template instantiations: 10962 10963@enumerate 10964@item 10965@opindex frepo 10966Compile your template-using code with @option{-frepo}. The compiler will 10967generate files with the extension @samp{.rpo} listing all of the 10968template instantiations used in the corresponding object files which 10969could be instantiated there; the link wrapper, @samp{collect2}, will 10970then update the @samp{.rpo} files to tell the compiler where to place 10971those instantiations and rebuild any affected object files. The 10972link-time overhead is negligible after the first pass, as the compiler 10973will continue to place the instantiations in the same files. 10974 10975This is your best option for application code written for the Borland 10976model, as it will just work. Code written for the Cfront model will 10977need to be modified so that the template definitions are available at 10978one or more points of instantiation; usually this is as simple as adding 10979@code{#include <tmethods.cc>} to the end of each template header. 10980 10981For library code, if you want the library to provide all of the template 10982instantiations it needs, just try to link all of its object files 10983together; the link will fail, but cause the instantiations to be 10984generated as a side effect. Be warned, however, that this may cause 10985conflicts if multiple libraries try to provide the same instantiations. 10986For greater control, use explicit instantiation as described in the next 10987option. 10988 10989@item 10990@opindex fno-implicit-templates 10991Compile your code with @option{-fno-implicit-templates} to disable the 10992implicit generation of template instances, and explicitly instantiate 10993all the ones you use. This approach requires more knowledge of exactly 10994which instances you need than do the others, but it's less 10995mysterious and allows greater control. You can scatter the explicit 10996instantiations throughout your program, perhaps putting them in the 10997translation units where the instances are used or the translation units 10998that define the templates themselves; you can put all of the explicit 10999instantiations you need into one big file; or you can create small files 11000like 11001 11002@smallexample 11003#include "Foo.h" 11004#include "Foo.cc" 11005 11006template class Foo<int>; 11007template ostream& operator << 11008 (ostream&, const Foo<int>&); 11009@end smallexample 11010 11011for each of the instances you need, and create a template instantiation 11012library from those. 11013 11014If you are using Cfront-model code, you can probably get away with not 11015using @option{-fno-implicit-templates} when compiling files that don't 11016@samp{#include} the member template definitions. 11017 11018If you use one big file to do the instantiations, you may want to 11019compile it without @option{-fno-implicit-templates} so you get all of the 11020instances required by your explicit instantiations (but not by any 11021other files) without having to specify them as well. 11022 11023G++ has extended the template instantiation syntax given in the ISO 11024standard to allow forward declaration of explicit instantiations 11025(with @code{extern}), instantiation of the compiler support data for a 11026template class (i.e.@: the vtable) without instantiating any of its 11027members (with @code{inline}), and instantiation of only the static data 11028members of a template class, without the support data or member 11029functions (with (@code{static}): 11030 11031@smallexample 11032extern template int max (int, int); 11033inline template class Foo<int>; 11034static template class Foo<int>; 11035@end smallexample 11036 11037@item 11038Do nothing. Pretend G++ does implement automatic instantiation 11039management. Code written for the Borland model will work fine, but 11040each translation unit will contain instances of each of the templates it 11041uses. In a large program, this can lead to an unacceptable amount of code 11042duplication. 11043@end enumerate 11044 11045@node Bound member functions 11046@section Extracting the function pointer from a bound pointer to member function 11047@cindex pmf 11048@cindex pointer to member function 11049@cindex bound pointer to member function 11050 11051In C++, pointer to member functions (PMFs) are implemented using a wide 11052pointer of sorts to handle all the possible call mechanisms; the PMF 11053needs to store information about how to adjust the @samp{this} pointer, 11054and if the function pointed to is virtual, where to find the vtable, and 11055where in the vtable to look for the member function. If you are using 11056PMFs in an inner loop, you should really reconsider that decision. If 11057that is not an option, you can extract the pointer to the function that 11058would be called for a given object/PMF pair and call it directly inside 11059the inner loop, to save a bit of time. 11060 11061Note that you will still be paying the penalty for the call through a 11062function pointer; on most modern architectures, such a call defeats the 11063branch prediction features of the CPU@. This is also true of normal 11064virtual function calls. 11065 11066The syntax for this extension is 11067 11068@smallexample 11069extern A a; 11070extern int (A::*fp)(); 11071typedef int (*fptr)(A *); 11072 11073fptr p = (fptr)(a.*fp); 11074@end smallexample 11075 11076For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), 11077no object is needed to obtain the address of the function. They can be 11078converted to function pointers directly: 11079 11080@smallexample 11081fptr p1 = (fptr)(&A::foo); 11082@end smallexample 11083 11084@opindex Wno-pmf-conversions 11085You must specify @option{-Wno-pmf-conversions} to use this extension. 11086 11087@node C++ Attributes 11088@section C++-Specific Variable, Function, and Type Attributes 11089 11090Some attributes only make sense for C++ programs. 11091 11092@table @code 11093@item init_priority (@var{priority}) 11094@cindex init_priority attribute 11095 11096 11097In Standard C++, objects defined at namespace scope are guaranteed to be 11098initialized in an order in strict accordance with that of their definitions 11099@emph{in a given translation unit}. No guarantee is made for initializations 11100across translation units. However, GNU C++ allows users to control the 11101order of initialization of objects defined at namespace scope with the 11102@code{init_priority} attribute by specifying a relative @var{priority}, 11103a constant integral expression currently bounded between 101 and 65535 11104inclusive. Lower numbers indicate a higher priority. 11105 11106In the following example, @code{A} would normally be created before 11107@code{B}, but the @code{init_priority} attribute has reversed that order: 11108 11109@smallexample 11110Some_Class A __attribute__ ((init_priority (2000))); 11111Some_Class B __attribute__ ((init_priority (543))); 11112@end smallexample 11113 11114@noindent 11115Note that the particular values of @var{priority} do not matter; only their 11116relative ordering. 11117 11118@item java_interface 11119@cindex java_interface attribute 11120 11121This type attribute informs C++ that the class is a Java interface. It may 11122only be applied to classes declared within an @code{extern "Java"} block. 11123Calls to methods declared in this interface will be dispatched using GCJ's 11124interface table mechanism, instead of regular virtual table dispatch. 11125 11126@end table 11127 11128See also @xref{Namespace Association}. 11129 11130@node Namespace Association 11131@section Namespace Association 11132 11133@strong{Caution:} The semantics of this extension are not fully 11134defined. Users should refrain from using this extension as its 11135semantics may change subtly over time. It is possible that this 11136extension will be removed in future versions of G++. 11137 11138A using-directive with @code{__attribute ((strong))} is stronger 11139than a normal using-directive in two ways: 11140 11141@itemize @bullet 11142@item 11143Templates from the used namespace can be specialized and explicitly 11144instantiated as though they were members of the using namespace. 11145 11146@item 11147The using namespace is considered an associated namespace of all 11148templates in the used namespace for purposes of argument-dependent 11149name lookup. 11150@end itemize 11151 11152The used namespace must be nested within the using namespace so that 11153normal unqualified lookup works properly. 11154 11155This is useful for composing a namespace transparently from 11156implementation namespaces. For example: 11157 11158@smallexample 11159namespace std @{ 11160 namespace debug @{ 11161 template <class T> struct A @{ @}; 11162 @} 11163 using namespace debug __attribute ((__strong__)); 11164 template <> struct A<int> @{ @}; // @r{ok to specialize} 11165 11166 template <class T> void f (A<T>); 11167@} 11168 11169int main() 11170@{ 11171 f (std::A<float>()); // @r{lookup finds} std::f 11172 f (std::A<int>()); 11173@} 11174@end smallexample 11175 11176@node Java Exceptions 11177@section Java Exceptions 11178 11179The Java language uses a slightly different exception handling model 11180from C++. Normally, GNU C++ will automatically detect when you are 11181writing C++ code that uses Java exceptions, and handle them 11182appropriately. However, if C++ code only needs to execute destructors 11183when Java exceptions are thrown through it, GCC will guess incorrectly. 11184Sample problematic code is: 11185 11186@smallexample 11187 struct S @{ ~S(); @}; 11188 extern void bar(); // @r{is written in Java, and may throw exceptions} 11189 void foo() 11190 @{ 11191 S s; 11192 bar(); 11193 @} 11194@end smallexample 11195 11196@noindent 11197The usual effect of an incorrect guess is a link failure, complaining of 11198a missing routine called @samp{__gxx_personality_v0}. 11199 11200You can inform the compiler that Java exceptions are to be used in a 11201translation unit, irrespective of what it might think, by writing 11202@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This 11203@samp{#pragma} must appear before any functions that throw or catch 11204exceptions, or run destructors when exceptions are thrown through them. 11205 11206You cannot mix Java and C++ exceptions in the same translation unit. It 11207is believed to be safe to throw a C++ exception from one file through 11208another file compiled for the Java exception model, or vice versa, but 11209there may be bugs in this area. 11210 11211@node Deprecated Features 11212@section Deprecated Features 11213 11214In the past, the GNU C++ compiler was extended to experiment with new 11215features, at a time when the C++ language was still evolving. Now that 11216the C++ standard is complete, some of those features are superseded by 11217superior alternatives. Using the old features might cause a warning in 11218some cases that the feature will be dropped in the future. In other 11219cases, the feature might be gone already. 11220 11221While the list below is not exhaustive, it documents some of the options 11222that are now deprecated: 11223 11224@table @code 11225@item -fexternal-templates 11226@itemx -falt-external-templates 11227These are two of the many ways for G++ to implement template 11228instantiation. @xref{Template Instantiation}. The C++ standard clearly 11229defines how template definitions have to be organized across 11230implementation units. G++ has an implicit instantiation mechanism that 11231should work just fine for standard-conforming code. 11232 11233@item -fstrict-prototype 11234@itemx -fno-strict-prototype 11235Previously it was possible to use an empty prototype parameter list to 11236indicate an unspecified number of parameters (like C), rather than no 11237parameters, as C++ demands. This feature has been removed, except where 11238it is required for backwards compatibility @xref{Backwards Compatibility}. 11239@end table 11240 11241G++ allows a virtual function returning @samp{void *} to be overridden 11242by one returning a different pointer type. This extension to the 11243covariant return type rules is now deprecated and will be removed from a 11244future version. 11245 11246The G++ minimum and maximum operators (@samp{<?} and @samp{>?}) and 11247their compound forms (@samp{<?=}) and @samp{>?=}) have been deprecated 11248and will be removed in a future version. Code using these operators 11249should be modified to use @code{std::min} and @code{std::max} instead. 11250 11251The named return value extension has been deprecated, and is now 11252removed from G++. 11253 11254The use of initializer lists with new expressions has been deprecated, 11255and is now removed from G++. 11256 11257Floating and complex non-type template parameters have been deprecated, 11258and are now removed from G++. 11259 11260The implicit typename extension has been deprecated and is now 11261removed from G++. 11262 11263The use of default arguments in function pointers, function typedefs 11264and other places where they are not permitted by the standard is 11265deprecated and will be removed from a future version of G++. 11266 11267G++ allows floating-point literals to appear in integral constant expressions, 11268e.g. @samp{ enum E @{ e = int(2.2 * 3.7) @} } 11269This extension is deprecated and will be removed from a future version. 11270 11271G++ allows static data members of const floating-point type to be declared 11272with an initializer in a class definition. The standard only allows 11273initializers for static members of const integral types and const 11274enumeration types so this extension has been deprecated and will be removed 11275from a future version. 11276 11277@node Backwards Compatibility 11278@section Backwards Compatibility 11279@cindex Backwards Compatibility 11280@cindex ARM [Annotated C++ Reference Manual] 11281 11282Now that there is a definitive ISO standard C++, G++ has a specification 11283to adhere to. The C++ language evolved over time, and features that 11284used to be acceptable in previous drafts of the standard, such as the ARM 11285[Annotated C++ Reference Manual], are no longer accepted. In order to allow 11286compilation of C++ written to such drafts, G++ contains some backwards 11287compatibilities. @emph{All such backwards compatibility features are 11288liable to disappear in future versions of G++.} They should be considered 11289deprecated @xref{Deprecated Features}. 11290 11291@table @code 11292@item For scope 11293If a variable is declared at for scope, it used to remain in scope until 11294the end of the scope which contained the for statement (rather than just 11295within the for scope). G++ retains this, but issues a warning, if such a 11296variable is accessed outside the for scope. 11297 11298@item Implicit C language 11299Old C system header files did not contain an @code{extern "C" @{@dots{}@}} 11300scope to set the language. On such systems, all header files are 11301implicitly scoped inside a C language scope. Also, an empty prototype 11302@code{()} will be treated as an unspecified number of arguments, rather 11303than no arguments, as C++ demands. 11304@end table 11305