1169689Skan@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2169689Skan@c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. 3169689Skan 490075Sobrien@c This is part of the GCC manual. 590075Sobrien@c For copying conditions, see the file gcc.texi. 690075Sobrien 790075Sobrien@node C Extensions 890075Sobrien@chapter Extensions to the C Language Family 990075Sobrien@cindex extensions, C language 1090075Sobrien@cindex C language extensions 1190075Sobrien 1290075Sobrien@opindex pedantic 1390075SobrienGNU C provides several language features not found in ISO standard C@. 1490075Sobrien(The @option{-pedantic} option directs GCC to print a warning message if 1590075Sobrienany of these features is used.) To test for the availability of these 1690075Sobrienfeatures in conditional compilation, check for a predefined macro 1790075Sobrien@code{__GNUC__}, which is always defined under GCC@. 1890075Sobrien 19220755SdimThese extensions are available in C. Most of them are also available 20220755Sdimin C++. @xref{C++ Extensions,,Extensions to the C++ Language}, for 21220755Sdimextensions that apply @emph{only} to C++. 2290075Sobrien 2390075SobrienSome features that are in ISO C99 but not C89 or C++ are also, as 2490075Sobrienextensions, accepted by GCC in C89 mode and in C++. 2590075Sobrien 2690075Sobrien@menu 2790075Sobrien* Statement Exprs:: Putting statements and declarations inside expressions. 28132718Skan* Local Labels:: Labels local to a block. 2990075Sobrien* Labels as Values:: Getting pointers to labels, and computed gotos. 3090075Sobrien* Nested Functions:: As in Algol and Pascal, lexical scoping of functions. 3190075Sobrien* Constructing Calls:: Dispatching a call to another function. 3290075Sobrien* Typeof:: @code{typeof}: referring to the type of an expression. 3390075Sobrien* Conditionals:: Omitting the middle operand of a @samp{?:} expression. 3490075Sobrien* Long Long:: Double-word integers---@code{long long int}. 3590075Sobrien* Complex:: Data types for complex numbers. 36169689Skan* Decimal Float:: Decimal Floating Types. 3790075Sobrien* Hex Floats:: Hexadecimal floating-point constants. 3890075Sobrien* Zero Length:: Zero-length arrays. 3990075Sobrien* Variable Length:: Arrays whose length is computed at run time. 40117395Skan* Empty Structures:: Structures with no members. 4190075Sobrien* Variadic Macros:: Macros with a variable number of arguments. 4290075Sobrien* Escaped Newlines:: Slightly looser rules for escaped newlines. 4390075Sobrien* Subscripting:: Any array can be subscripted, even if not an lvalue. 4490075Sobrien* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. 4590075Sobrien* Initializers:: Non-constant initializers. 4690075Sobrien* Compound Literals:: Compound literals give structures, unions 4790075Sobrien or arrays as values. 4890075Sobrien* Designated Inits:: Labeling elements of initializers. 4990075Sobrien* Cast to Union:: Casting to union type from any member of the union. 5090075Sobrien* Case Ranges:: `case 1 ... 9' and such. 5190075Sobrien* Mixed Declarations:: Mixing declarations and code. 5290075Sobrien* Function Attributes:: Declaring that functions have no side effects, 5390075Sobrien or that they can never return. 5490075Sobrien* Attribute Syntax:: Formal syntax for attributes. 5590075Sobrien* Function Prototypes:: Prototype declarations and old-style definitions. 5690075Sobrien* C++ Comments:: C++ comments are recognized. 5790075Sobrien* Dollar Signs:: Dollar sign is allowed in identifiers. 5890075Sobrien* Character Escapes:: @samp{\e} stands for the character @key{ESC}. 5990075Sobrien* Variable Attributes:: Specifying attributes of variables. 6090075Sobrien* Type Attributes:: Specifying attributes of types. 61260918Spfg@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 62260918Spfg* Label Attributes:: Specifying attributes of labels and statements. 63260918Spfg@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 6490075Sobrien* Alignment:: Inquiring about the alignment of a type or variable. 6590075Sobrien* Inline:: Defining inline functions (as fast as macros). 6690075Sobrien* Extended Asm:: Assembler instructions with C expressions as operands. 6790075Sobrien (With them you can define ``built-in'' functions.) 6890075Sobrien* Constraints:: Constraints for asm operands 6990075Sobrien* Asm Labels:: Specifying the assembler name to use for a C symbol. 7090075Sobrien* Explicit Reg Vars:: Defining variables residing in specified registers. 7190075Sobrien* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. 7290075Sobrien* Incomplete Enums:: @code{enum foo;}, with details to follow. 7390075Sobrien* Function Names:: Printable strings which are the name of the current 7490075Sobrien function. 7590075Sobrien* Return Address:: Getting the return or frame address of a function. 7690075Sobrien* Vector Extensions:: Using vector instructions through built-in functions. 77169689Skan* Offsetof:: Special syntax for implementing @code{offsetof}. 78169689Skan* Atomic Builtins:: Built-in functions for atomic memory access. 79169689Skan* Object Size Checking:: Built-in functions for limited buffer overflow 80169689Skan checking. 8190075Sobrien* Other Builtins:: Other built-in functions. 8290075Sobrien* Target Builtins:: Built-in functions specific to particular targets. 83169689Skan* Target Format Checks:: Format checks specific to particular targets. 8490075Sobrien* Pragmas:: Pragmas accepted by GCC. 8590075Sobrien* Unnamed Fields:: Unnamed struct/union fields within structs/unions. 86117395Skan* Thread-Local:: Per-thread variables. 87255107Spfg* Binary constants:: Binary constants using the @samp{0b} prefix. 88261188Spfg@c APPLE LOCAL blocks 7205047 5811887 89261188Spfg* Blocks:: Anonymous functions (closures). 9090075Sobrien@end menu 9190075Sobrien 9290075Sobrien@node Statement Exprs 9390075Sobrien@section Statements and Declarations in Expressions 9490075Sobrien@cindex statements inside expressions 9590075Sobrien@cindex declarations inside expressions 9690075Sobrien@cindex expressions containing statements 9790075Sobrien@cindex macros, statements in expressions 9890075Sobrien 9990075Sobrien@c the above section title wrapped and causes an underfull hbox.. i 10090075Sobrien@c changed it from "within" to "in". --mew 4feb93 10190075SobrienA compound statement enclosed in parentheses may appear as an expression 10290075Sobrienin GNU C@. This allows you to use loops, switches, and local variables 10390075Sobrienwithin an expression. 10490075Sobrien 10590075SobrienRecall that a compound statement is a sequence of statements surrounded 10690075Sobrienby braces; in this construct, parentheses go around the braces. For 10790075Sobrienexample: 10890075Sobrien 109132718Skan@smallexample 11090075Sobrien(@{ int y = foo (); int z; 11190075Sobrien if (y > 0) z = y; 11290075Sobrien else z = - y; 11390075Sobrien z; @}) 114132718Skan@end smallexample 11590075Sobrien 11690075Sobrien@noindent 11790075Sobrienis a valid (though slightly more complex than necessary) expression 11890075Sobrienfor the absolute value of @code{foo ()}. 11990075Sobrien 12090075SobrienThe last thing in the compound statement should be an expression 12190075Sobrienfollowed by a semicolon; the value of this subexpression serves as the 12290075Sobrienvalue of the entire construct. (If you use some other kind of statement 12390075Sobrienlast within the braces, the construct has type @code{void}, and thus 12490075Sobrieneffectively no value.) 12590075Sobrien 12690075SobrienThis feature is especially useful in making macro definitions ``safe'' (so 12790075Sobrienthat they evaluate each operand exactly once). For example, the 12890075Sobrien``maximum'' function is commonly defined as a macro in standard C as 12990075Sobrienfollows: 13090075Sobrien 131132718Skan@smallexample 13290075Sobrien#define max(a,b) ((a) > (b) ? (a) : (b)) 133132718Skan@end smallexample 13490075Sobrien 13590075Sobrien@noindent 13690075Sobrien@cindex side effects, macro argument 13790075SobrienBut this definition computes either @var{a} or @var{b} twice, with bad 13890075Sobrienresults if the operand has side effects. In GNU C, if you know the 139132718Skantype of the operands (here taken as @code{int}), you can define 14090075Sobrienthe macro safely as follows: 14190075Sobrien 142132718Skan@smallexample 14390075Sobrien#define maxint(a,b) \ 14490075Sobrien (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) 145132718Skan@end smallexample 14690075Sobrien 14790075SobrienEmbedded statements are not allowed in constant expressions, such as 14890075Sobrienthe value of an enumeration constant, the width of a bit-field, or 14990075Sobrienthe initial value of a static variable. 15090075Sobrien 15190075SobrienIf you don't know the type of the operand, you can still do this, but you 152104752Skanmust use @code{typeof} (@pxref{Typeof}). 15390075Sobrien 154132718SkanIn G++, the result value of a statement expression undergoes array and 155132718Skanfunction pointer decay, and is returned by value to the enclosing 156169689Skanexpression. For instance, if @code{A} is a class, then 15790075Sobrien 158132718Skan@smallexample 159132718Skan A a; 16090075Sobrien 161132718Skan (@{a;@}).Foo () 162132718Skan@end smallexample 16390075Sobrien 16490075Sobrien@noindent 165132718Skanwill construct a temporary @code{A} object to hold the result of the 166132718Skanstatement expression, and that will be used to invoke @code{Foo}. 167132718SkanTherefore the @code{this} pointer observed by @code{Foo} will not be the 168132718Skanaddress of @code{a}. 16990075Sobrien 170132718SkanAny temporaries created within a statement within a statement expression 171132718Skanwill be destroyed at the statement's end. This makes statement 172132718Skanexpressions inside macros slightly different from function calls. In 173132718Skanthe latter case temporaries introduced during argument evaluation will 174132718Skanbe destroyed at the end of the statement that includes the function 175132718Skancall. In the statement expression case they will be destroyed during 176132718Skanthe statement expression. For instance, 17790075Sobrien 178132718Skan@smallexample 179132718Skan#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) 180132718Skantemplate<typename T> T function(T a) @{ T b = a; return b + 3; @} 181132718Skan 182132718Skanvoid foo () 183132718Skan@{ 184132718Skan macro (X ()); 185132718Skan function (X ()); 186132718Skan@} 187132718Skan@end smallexample 188132718Skan 18990075Sobrien@noindent 190132718Skanwill have different places where temporaries are destroyed. For the 191132718Skan@code{macro} case, the temporary @code{X} will be destroyed just after 192132718Skanthe initialization of @code{b}. In the @code{function} case that 193132718Skantemporary will be destroyed when the function returns. 19490075Sobrien 19590075SobrienThese considerations mean that it is probably a bad idea to use 19690075Sobrienstatement-expressions of this form in header files that are designed to 19790075Sobrienwork with C++. (Note that some versions of the GNU C Library contained 19890075Sobrienheader files using statement-expression that lead to precisely this 19990075Sobrienbug.) 20090075Sobrien 201169689SkanJumping into a statement expression with @code{goto} or using a 202169689Skan@code{switch} statement outside the statement expression with a 203169689Skan@code{case} or @code{default} label inside the statement expression is 204169689Skannot permitted. Jumping into a statement expression with a computed 205169689Skan@code{goto} (@pxref{Labels as Values}) yields undefined behavior. 206169689SkanJumping out of a statement expression is permitted, but if the 207169689Skanstatement expression is part of a larger expression then it is 208169689Skanunspecified which other subexpressions of that expression have been 209169689Skanevaluated except where the language definition requires certain 210169689Skansubexpressions to be evaluated before or after the statement 211169689Skanexpression. In any case, as with a function call the evaluation of a 212169689Skanstatement expression is not interleaved with the evaluation of other 213169689Skanparts of the containing expression. For example, 214169689Skan 215169689Skan@smallexample 216169689Skan foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); 217169689Skan@end smallexample 218169689Skan 219169689Skan@noindent 220169689Skanwill call @code{foo} and @code{bar1} and will not call @code{baz} but 221169689Skanmay or may not call @code{bar2}. If @code{bar2} is called, it will be 222169689Skancalled after @code{foo} and before @code{bar1} 223169689Skan 22490075Sobrien@node Local Labels 22590075Sobrien@section Locally Declared Labels 22690075Sobrien@cindex local labels 22790075Sobrien@cindex macros, local labels 22890075Sobrien 229132718SkanGCC allows you to declare @dfn{local labels} in any nested block 230169689Skanscope. A local label is just like an ordinary label, but you can 231132718Skanonly reference it (with a @code{goto} statement, or by taking its 232132718Skanaddress) within the block in which it was declared. 23390075Sobrien 23490075SobrienA local label declaration looks like this: 23590075Sobrien 236132718Skan@smallexample 23790075Sobrien__label__ @var{label}; 238132718Skan@end smallexample 23990075Sobrien 24090075Sobrien@noindent 24190075Sobrienor 24290075Sobrien 243132718Skan@smallexample 244117395Skan__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; 245132718Skan@end smallexample 24690075Sobrien 247132718SkanLocal label declarations must come at the beginning of the block, 248132718Skanbefore any ordinary declarations or statements. 24990075Sobrien 25090075SobrienThe label declaration defines the label @emph{name}, but does not define 25190075Sobrienthe label itself. You must do this in the usual way, with 25290075Sobrien@code{@var{label}:}, within the statements of the statement expression. 25390075Sobrien 254132718SkanThe local label feature is useful for complex macros. If a macro 255132718Skancontains nested loops, a @code{goto} can be useful for breaking out of 256132718Skanthem. However, an ordinary label whose scope is the whole function 257132718Skancannot be used: if the macro can be expanded several times in one 258132718Skanfunction, the label will be multiply defined in that function. A 259132718Skanlocal label avoids this problem. For example: 26090075Sobrien 261132718Skan@smallexample 262132718Skan#define SEARCH(value, array, target) \ 263132718Skando @{ \ 264132718Skan __label__ found; \ 265132718Skan typeof (target) _SEARCH_target = (target); \ 266132718Skan typeof (*(array)) *_SEARCH_array = (array); \ 267132718Skan int i, j; \ 268132718Skan int value; \ 269132718Skan for (i = 0; i < max; i++) \ 270132718Skan for (j = 0; j < max; j++) \ 271132718Skan if (_SEARCH_array[i][j] == _SEARCH_target) \ 272132718Skan @{ (value) = i; goto found; @} \ 273132718Skan (value) = -1; \ 274132718Skan found:; \ 275132718Skan@} while (0) 276132718Skan@end smallexample 277132718Skan 278132718SkanThis could also be written using a statement-expression: 279132718Skan 280132718Skan@smallexample 28190075Sobrien#define SEARCH(array, target) \ 28290075Sobrien(@{ \ 28390075Sobrien __label__ found; \ 28490075Sobrien typeof (target) _SEARCH_target = (target); \ 28590075Sobrien typeof (*(array)) *_SEARCH_array = (array); \ 28690075Sobrien int i, j; \ 28790075Sobrien int value; \ 28890075Sobrien for (i = 0; i < max; i++) \ 28990075Sobrien for (j = 0; j < max; j++) \ 29090075Sobrien if (_SEARCH_array[i][j] == _SEARCH_target) \ 29190075Sobrien @{ value = i; goto found; @} \ 29290075Sobrien value = -1; \ 29390075Sobrien found: \ 29490075Sobrien value; \ 29590075Sobrien@}) 296132718Skan@end smallexample 29790075Sobrien 298132718SkanLocal label declarations also make the labels they declare visible to 299132718Skannested functions, if there are any. @xref{Nested Functions}, for details. 300132718Skan 30190075Sobrien@node Labels as Values 30290075Sobrien@section Labels as Values 30390075Sobrien@cindex labels as values 30490075Sobrien@cindex computed gotos 30590075Sobrien@cindex goto with computed label 30690075Sobrien@cindex address of a label 30790075Sobrien 30890075SobrienYou can get the address of a label defined in the current function 30990075Sobrien(or a containing function) with the unary operator @samp{&&}. The 31090075Sobrienvalue has type @code{void *}. This value is a constant and can be used 31190075Sobrienwherever a constant of that type is valid. For example: 31290075Sobrien 313132718Skan@smallexample 31490075Sobrienvoid *ptr; 315117395Skan/* @r{@dots{}} */ 31690075Sobrienptr = &&foo; 317132718Skan@end smallexample 31890075Sobrien 31990075SobrienTo use these values, you need to be able to jump to one. This is done 32090075Sobrienwith the computed goto statement@footnote{The analogous feature in 32190075SobrienFortran is called an assigned goto, but that name seems inappropriate in 32290075SobrienC, where one can do more than simply store label addresses in label 32390075Sobrienvariables.}, @code{goto *@var{exp};}. For example, 32490075Sobrien 325132718Skan@smallexample 32690075Sobriengoto *ptr; 327132718Skan@end smallexample 32890075Sobrien 32990075Sobrien@noindent 33090075SobrienAny expression of type @code{void *} is allowed. 33190075Sobrien 33290075SobrienOne way of using these constants is in initializing a static array that 33390075Sobrienwill serve as a jump table: 33490075Sobrien 335132718Skan@smallexample 33690075Sobrienstatic void *array[] = @{ &&foo, &&bar, &&hack @}; 337132718Skan@end smallexample 33890075Sobrien 33990075SobrienThen you can select a label with indexing, like this: 34090075Sobrien 341132718Skan@smallexample 34290075Sobriengoto *array[i]; 343132718Skan@end smallexample 34490075Sobrien 34590075Sobrien@noindent 34690075SobrienNote that this does not check whether the subscript is in bounds---array 34790075Sobrienindexing in C never does that. 34890075Sobrien 34990075SobrienSuch an array of label values serves a purpose much like that of the 35090075Sobrien@code{switch} statement. The @code{switch} statement is cleaner, so 35190075Sobrienuse that rather than an array unless the problem does not fit a 35290075Sobrien@code{switch} statement very well. 35390075Sobrien 35490075SobrienAnother use of label values is in an interpreter for threaded code. 35590075SobrienThe labels within the interpreter function can be stored in the 35690075Sobrienthreaded code for super-fast dispatching. 35790075Sobrien 35890075SobrienYou may not use this mechanism to jump to code in a different function. 35990075SobrienIf you do that, totally unpredictable things will happen. The best way to 36090075Sobrienavoid this is to store the label address only in automatic variables and 36190075Sobriennever pass it as an argument. 36290075Sobrien 36390075SobrienAn alternate way to write the above example is 36490075Sobrien 365132718Skan@smallexample 36690075Sobrienstatic const int array[] = @{ &&foo - &&foo, &&bar - &&foo, 36790075Sobrien &&hack - &&foo @}; 36890075Sobriengoto *(&&foo + array[i]); 369132718Skan@end smallexample 37090075Sobrien 37190075Sobrien@noindent 37290075SobrienThis is more friendly to code living in shared libraries, as it reduces 37390075Sobrienthe number of dynamic relocations that are needed, and by consequence, 37490075Sobrienallows the data to be read-only. 37590075Sobrien 37690075Sobrien@node Nested Functions 37790075Sobrien@section Nested Functions 37890075Sobrien@cindex nested functions 37990075Sobrien@cindex downward funargs 38090075Sobrien@cindex thunks 38190075Sobrien 38290075SobrienA @dfn{nested function} is a function defined inside another function. 383261188Spfg@c APPLE LOCAL begin nested functions 4357979 384261188SpfgNested functions are not supported for GNU C++ and are disable by 385261188Spfgdefault on FreeBSD. The @option{-fnested-functions} and 386261188Spfg@option{-fno-nested-functions} options can be used to enable and 387261188Spfgdisable nested function suppport. The nested function's name is local 388261188Spfgto the block where it is defined. For example, here we define a 389261188Spfgnested function named @code{square}, and call it twice: 390261188Spfg@c APPLE LOCAL end nested functions 4357979 39190075Sobrien 392132718Skan@smallexample 39390075Sobrien@group 39490075Sobrienfoo (double a, double b) 39590075Sobrien@{ 39690075Sobrien double square (double z) @{ return z * z; @} 39790075Sobrien 39890075Sobrien return square (a) + square (b); 39990075Sobrien@} 40090075Sobrien@end group 401132718Skan@end smallexample 40290075Sobrien 40390075SobrienThe nested function can access all the variables of the containing 40490075Sobrienfunction that are visible at the point of its definition. This is 40590075Sobriencalled @dfn{lexical scoping}. For example, here we show a nested 40690075Sobrienfunction which uses an inherited variable named @code{offset}: 40790075Sobrien 408132718Skan@smallexample 40990075Sobrien@group 41090075Sobrienbar (int *array, int offset, int size) 41190075Sobrien@{ 41290075Sobrien int access (int *array, int index) 41390075Sobrien @{ return array[index + offset]; @} 41490075Sobrien int i; 415117395Skan /* @r{@dots{}} */ 41690075Sobrien for (i = 0; i < size; i++) 417117395Skan /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 41890075Sobrien@} 41990075Sobrien@end group 420132718Skan@end smallexample 42190075Sobrien 42290075SobrienNested function definitions are permitted within functions in the places 423169689Skanwhere variable definitions are allowed; that is, in any block, mixed 424169689Skanwith the other declarations and statements in the block. 42590075Sobrien 42690075SobrienIt is possible to call the nested function from outside the scope of its 42790075Sobrienname by storing its address or passing the address to another function: 42890075Sobrien 429132718Skan@smallexample 43090075Sobrienhack (int *array, int size) 43190075Sobrien@{ 43290075Sobrien void store (int index, int value) 43390075Sobrien @{ array[index] = value; @} 43490075Sobrien 43590075Sobrien intermediate (store, size); 43690075Sobrien@} 437132718Skan@end smallexample 43890075Sobrien 43990075SobrienHere, the function @code{intermediate} receives the address of 44090075Sobrien@code{store} as an argument. If @code{intermediate} calls @code{store}, 44190075Sobrienthe arguments given to @code{store} are used to store into @code{array}. 44290075SobrienBut this technique works only so long as the containing function 44390075Sobrien(@code{hack}, in this example) does not exit. 44490075Sobrien 44590075SobrienIf you try to call the nested function through its address after the 44690075Sobriencontaining function has exited, all hell will break loose. If you try 44790075Sobriento call it after a containing scope level has exited, and if it refers 44890075Sobriento some of the variables that are no longer in scope, you may be lucky, 44990075Sobrienbut it's not wise to take the risk. If, however, the nested function 45090075Sobriendoes not refer to anything that has gone out of scope, you should be 45190075Sobriensafe. 45290075Sobrien 45390075SobrienGCC implements taking the address of a nested function using a technique 45490075Sobriencalled @dfn{trampolines}. A paper describing them is available as 45590075Sobrien 45690075Sobrien@noindent 457103445Skan@uref{http://people.debian.org/~aaronl/Usenix88-lexic.pdf}. 45890075Sobrien 45990075SobrienA nested function can jump to a label inherited from a containing 46090075Sobrienfunction, provided the label was explicitly declared in the containing 46190075Sobrienfunction (@pxref{Local Labels}). Such a jump returns instantly to the 46290075Sobriencontaining function, exiting the nested function which did the 46390075Sobrien@code{goto} and any intermediate functions as well. Here is an example: 46490075Sobrien 465132718Skan@smallexample 46690075Sobrien@group 46790075Sobrienbar (int *array, int offset, int size) 46890075Sobrien@{ 46990075Sobrien __label__ failure; 47090075Sobrien int access (int *array, int index) 47190075Sobrien @{ 47290075Sobrien if (index > size) 47390075Sobrien goto failure; 47490075Sobrien return array[index + offset]; 47590075Sobrien @} 47690075Sobrien int i; 477117395Skan /* @r{@dots{}} */ 47890075Sobrien for (i = 0; i < size; i++) 479117395Skan /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 480117395Skan /* @r{@dots{}} */ 48190075Sobrien return 0; 48290075Sobrien 48390075Sobrien /* @r{Control comes here from @code{access} 48490075Sobrien if it detects an error.} */ 48590075Sobrien failure: 48690075Sobrien return -1; 48790075Sobrien@} 48890075Sobrien@end group 489132718Skan@end smallexample 49090075Sobrien 491169689SkanA nested function always has no linkage. Declaring one with 492169689Skan@code{extern} or @code{static} is erroneous. If you need to declare the nested function 49390075Sobrienbefore its definition, use @code{auto} (which is otherwise meaningless 49490075Sobrienfor function declarations). 49590075Sobrien 496132718Skan@smallexample 49790075Sobrienbar (int *array, int offset, int size) 49890075Sobrien@{ 49990075Sobrien __label__ failure; 50090075Sobrien auto int access (int *, int); 501117395Skan /* @r{@dots{}} */ 50290075Sobrien int access (int *array, int index) 50390075Sobrien @{ 50490075Sobrien if (index > size) 50590075Sobrien goto failure; 50690075Sobrien return array[index + offset]; 50790075Sobrien @} 508117395Skan /* @r{@dots{}} */ 50990075Sobrien@} 510132718Skan@end smallexample 51190075Sobrien 51290075Sobrien@node Constructing Calls 51390075Sobrien@section Constructing Function Calls 51490075Sobrien@cindex constructing calls 51590075Sobrien@cindex forwarding calls 51690075Sobrien 51790075SobrienUsing the built-in functions described below, you can record 51890075Sobrienthe arguments a function received, and call another function 51990075Sobrienwith the same arguments, without knowing the number or types 52090075Sobrienof the arguments. 52190075Sobrien 52290075SobrienYou can also record the return value of that function call, 52390075Sobrienand later return that value, without knowing what data type 52490075Sobrienthe function tried to return (as long as your caller expects 52590075Sobrienthat data type). 52690075Sobrien 527132718SkanHowever, these built-in functions may interact badly with some 528132718Skansophisticated features or other extensions of the language. It 529132718Skanis, therefore, not recommended to use them outside very simple 530132718Skanfunctions acting as mere forwarders for their arguments. 531132718Skan 53290075Sobrien@deftypefn {Built-in Function} {void *} __builtin_apply_args () 53390075SobrienThis built-in function returns a pointer to data 53490075Sobriendescribing how to perform a call with the same arguments as were passed 53590075Sobriento the current function. 53690075Sobrien 53790075SobrienThe function saves the arg pointer register, structure value address, 53890075Sobrienand all registers that might be used to pass arguments to a function 53990075Sobrieninto a block of memory allocated on the stack. Then it returns the 54090075Sobrienaddress of that block. 54190075Sobrien@end deftypefn 54290075Sobrien 54390075Sobrien@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) 54490075SobrienThis built-in function invokes @var{function} 54590075Sobrienwith a copy of the parameters described by @var{arguments} 54690075Sobrienand @var{size}. 54790075Sobrien 54890075SobrienThe value of @var{arguments} should be the value returned by 54990075Sobrien@code{__builtin_apply_args}. The argument @var{size} specifies the size 55090075Sobrienof the stack argument data, in bytes. 55190075Sobrien 55290075SobrienThis function returns a pointer to data describing 55390075Sobrienhow to return whatever value was returned by @var{function}. The data 55490075Sobrienis saved in a block of memory allocated on the stack. 55590075Sobrien 55690075SobrienIt is not always simple to compute the proper value for @var{size}. The 55790075Sobrienvalue is used by @code{__builtin_apply} to compute the amount of data 55890075Sobrienthat should be pushed on the stack and copied from the incoming argument 55990075Sobrienarea. 56090075Sobrien@end deftypefn 56190075Sobrien 56290075Sobrien@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) 56390075SobrienThis built-in function returns the value described by @var{result} from 56490075Sobrienthe containing function. You should specify, for @var{result}, a value 56590075Sobrienreturned by @code{__builtin_apply}. 56690075Sobrien@end deftypefn 56790075Sobrien 56890075Sobrien@node Typeof 56990075Sobrien@section Referring to a Type with @code{typeof} 57090075Sobrien@findex typeof 57190075Sobrien@findex sizeof 57290075Sobrien@cindex macros, types of arguments 57390075Sobrien 57490075SobrienAnother way to refer to the type of an expression is with @code{typeof}. 57590075SobrienThe syntax of using of this keyword looks like @code{sizeof}, but the 57690075Sobrienconstruct acts semantically like a type name defined with @code{typedef}. 57790075Sobrien 57890075SobrienThere are two ways of writing the argument to @code{typeof}: with an 57990075Sobrienexpression or with a type. Here is an example with an expression: 58090075Sobrien 581132718Skan@smallexample 58290075Sobrientypeof (x[0](1)) 583132718Skan@end smallexample 58490075Sobrien 58590075Sobrien@noindent 58690075SobrienThis assumes that @code{x} is an array of pointers to functions; 58790075Sobrienthe type described is that of the values of the functions. 58890075Sobrien 58990075SobrienHere is an example with a typename as the argument: 59090075Sobrien 591132718Skan@smallexample 59290075Sobrientypeof (int *) 593132718Skan@end smallexample 59490075Sobrien 59590075Sobrien@noindent 59690075SobrienHere the type described is that of pointers to @code{int}. 59790075Sobrien 59890075SobrienIf you are writing a header file that must work when included in ISO C 59990075Sobrienprograms, write @code{__typeof__} instead of @code{typeof}. 60090075Sobrien@xref{Alternate Keywords}. 60190075Sobrien 60290075SobrienA @code{typeof}-construct can be used anywhere a typedef name could be 60390075Sobrienused. For example, you can use it in a declaration, in a cast, or inside 60490075Sobrienof @code{sizeof} or @code{typeof}. 60590075Sobrien 606104752Skan@code{typeof} is often useful in conjunction with the 607104752Skanstatements-within-expressions feature. Here is how the two together can 608104752Skanbe used to define a safe ``maximum'' macro that operates on any 609104752Skanarithmetic type and evaluates each of its arguments exactly once: 610104752Skan 611132718Skan@smallexample 612104752Skan#define max(a,b) \ 613104752Skan (@{ typeof (a) _a = (a); \ 614104752Skan typeof (b) _b = (b); \ 615104752Skan _a > _b ? _a : _b; @}) 616132718Skan@end smallexample 617104752Skan 618117395Skan@cindex underscores in variables in macros 619117395Skan@cindex @samp{_} in variables in macros 620117395Skan@cindex local variables in macros 621117395Skan@cindex variables, local, in macros 622117395Skan@cindex macros, local variables in 623117395Skan 624117395SkanThe reason for using names that start with underscores for the local 625117395Skanvariables is to avoid conflicts with variable names that occur within the 626117395Skanexpressions that are substituted for @code{a} and @code{b}. Eventually we 627117395Skanhope to design a new form of declaration syntax that allows you to declare 628117395Skanvariables whose scopes start only after their initializers; this will be a 629117395Skanmore reliable way to prevent such conflicts. 630117395Skan 631104752Skan@noindent 632104752SkanSome more examples of the use of @code{typeof}: 633104752Skan 63490075Sobrien@itemize @bullet 63590075Sobrien@item 63690075SobrienThis declares @code{y} with the type of what @code{x} points to. 63790075Sobrien 638132718Skan@smallexample 63990075Sobrientypeof (*x) y; 640132718Skan@end smallexample 64190075Sobrien 64290075Sobrien@item 64390075SobrienThis declares @code{y} as an array of such values. 64490075Sobrien 645132718Skan@smallexample 64690075Sobrientypeof (*x) y[4]; 647132718Skan@end smallexample 64890075Sobrien 64990075Sobrien@item 65090075SobrienThis declares @code{y} as an array of pointers to characters: 65190075Sobrien 652132718Skan@smallexample 65390075Sobrientypeof (typeof (char *)[4]) y; 654132718Skan@end smallexample 65590075Sobrien 65690075Sobrien@noindent 65790075SobrienIt is equivalent to the following traditional C declaration: 65890075Sobrien 659132718Skan@smallexample 66090075Sobrienchar *y[4]; 661132718Skan@end smallexample 66290075Sobrien 66390075SobrienTo see the meaning of the declaration using @code{typeof}, and why it 664132718Skanmight be a useful way to write, rewrite it with these macros: 66590075Sobrien 666132718Skan@smallexample 66790075Sobrien#define pointer(T) typeof(T *) 66890075Sobrien#define array(T, N) typeof(T [N]) 669132718Skan@end smallexample 67090075Sobrien 67190075Sobrien@noindent 67290075SobrienNow the declaration can be rewritten this way: 67390075Sobrien 674132718Skan@smallexample 67590075Sobrienarray (pointer (char), 4) y; 676132718Skan@end smallexample 67790075Sobrien 67890075Sobrien@noindent 67990075SobrienThus, @code{array (pointer (char), 4)} is the type of arrays of 4 68090075Sobrienpointers to @code{char}. 68190075Sobrien@end itemize 68290075Sobrien 683104752Skan@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported 684104752Skana more limited extension which permitted one to write 685104752Skan 686132718Skan@smallexample 687104752Skantypedef @var{T} = @var{expr}; 688132718Skan@end smallexample 689104752Skan 690104752Skan@noindent 691104752Skanwith the effect of declaring @var{T} to have the type of the expression 692104752Skan@var{expr}. This extension does not work with GCC 3 (versions between 693104752Skan3.0 and 3.2 will crash; 3.2.1 and later give an error). Code which 694104752Skanrelies on it should be rewritten to use @code{typeof}: 695104752Skan 696132718Skan@smallexample 697104752Skantypedef typeof(@var{expr}) @var{T}; 698132718Skan@end smallexample 699104752Skan 700104752Skan@noindent 701104752SkanThis will work with all versions of GCC@. 702104752Skan 70390075Sobrien@node Conditionals 70490075Sobrien@section Conditionals with Omitted Operands 70590075Sobrien@cindex conditional expressions, extensions 70690075Sobrien@cindex omitted middle-operands 70790075Sobrien@cindex middle-operands, omitted 70890075Sobrien@cindex extensions, @code{?:} 70990075Sobrien@cindex @code{?:} extensions 71090075Sobrien 71190075SobrienThe middle operand in a conditional expression may be omitted. Then 71290075Sobrienif the first operand is nonzero, its value is the value of the conditional 71390075Sobrienexpression. 71490075Sobrien 71590075SobrienTherefore, the expression 71690075Sobrien 717132718Skan@smallexample 71890075Sobrienx ? : y 719132718Skan@end smallexample 72090075Sobrien 72190075Sobrien@noindent 72290075Sobrienhas the value of @code{x} if that is nonzero; otherwise, the value of 72390075Sobrien@code{y}. 72490075Sobrien 72590075SobrienThis example is perfectly equivalent to 72690075Sobrien 727132718Skan@smallexample 72890075Sobrienx ? x : y 729132718Skan@end smallexample 73090075Sobrien 73190075Sobrien@cindex side effect in ?: 73290075Sobrien@cindex ?: side effect 73390075Sobrien@noindent 73490075SobrienIn this simple case, the ability to omit the middle operand is not 73590075Sobrienespecially useful. When it becomes useful is when the first operand does, 73690075Sobrienor may (if it is a macro argument), contain a side effect. Then repeating 73790075Sobrienthe operand in the middle would perform the side effect twice. Omitting 73890075Sobrienthe middle operand uses the value already computed without the undesirable 73990075Sobrieneffects of recomputing it. 74090075Sobrien 74190075Sobrien@node Long Long 74290075Sobrien@section Double-Word Integers 74390075Sobrien@cindex @code{long long} data types 74490075Sobrien@cindex double-word arithmetic 74590075Sobrien@cindex multiprecision arithmetic 74690075Sobrien@cindex @code{LL} integer suffix 74790075Sobrien@cindex @code{ULL} integer suffix 74890075Sobrien 74990075SobrienISO C99 supports data types for integers that are at least 64 bits wide, 75090075Sobrienand as an extension GCC supports them in C89 mode and in C++. 75190075SobrienSimply write @code{long long int} for a signed integer, or 75290075Sobrien@code{unsigned long long int} for an unsigned integer. To make an 75390075Sobrieninteger constant of type @code{long long int}, add the suffix @samp{LL} 75490075Sobriento the integer. To make an integer constant of type @code{unsigned long 75590075Sobrienlong int}, add the suffix @samp{ULL} to the integer. 75690075Sobrien 75790075SobrienYou can use these types in arithmetic like any other integer types. 75890075SobrienAddition, subtraction, and bitwise boolean operations on these types 75990075Sobrienare open-coded on all types of machines. Multiplication is open-coded 76090075Sobrienif the machine supports fullword-to-doubleword a widening multiply 76190075Sobrieninstruction. Division and shifts are open-coded only on machines that 76290075Sobrienprovide special support. The operations that are not open-coded use 76390075Sobrienspecial library routines that come with GCC@. 76490075Sobrien 76590075SobrienThere may be pitfalls when you use @code{long long} types for function 76690075Sobrienarguments, unless you declare function prototypes. If a function 76790075Sobrienexpects type @code{int} for its argument, and you pass a value of type 76890075Sobrien@code{long long int}, confusion will result because the caller and the 76990075Sobriensubroutine will disagree about the number of bytes for the argument. 77090075SobrienLikewise, if the function expects @code{long long int} and you pass 77190075Sobrien@code{int}. The best way to avoid such problems is to use prototypes. 77290075Sobrien 77390075Sobrien@node Complex 77490075Sobrien@section Complex Numbers 77590075Sobrien@cindex complex numbers 77690075Sobrien@cindex @code{_Complex} keyword 77790075Sobrien@cindex @code{__complex__} keyword 77890075Sobrien 77990075SobrienISO C99 supports complex floating data types, and as an extension GCC 78090075Sobriensupports them in C89 mode and in C++, and supports complex integer data 78190075Sobrientypes which are not part of ISO C99. You can declare complex types 78290075Sobrienusing the keyword @code{_Complex}. As an extension, the older GNU 78390075Sobrienkeyword @code{__complex__} is also supported. 78490075Sobrien 78590075SobrienFor example, @samp{_Complex double x;} declares @code{x} as a 78690075Sobrienvariable whose real part and imaginary part are both of type 78790075Sobrien@code{double}. @samp{_Complex short int y;} declares @code{y} to 78890075Sobrienhave real and imaginary parts of type @code{short int}; this is not 78990075Sobrienlikely to be useful, but it shows that the set of complex types is 79090075Sobriencomplete. 79190075Sobrien 79290075SobrienTo write a constant with a complex data type, use the suffix @samp{i} or 79390075Sobrien@samp{j} (either one; they are equivalent). For example, @code{2.5fi} 79490075Sobrienhas type @code{_Complex float} and @code{3i} has type 79590075Sobrien@code{_Complex int}. Such a constant always has a pure imaginary 79690075Sobrienvalue, but you can form any complex value you like by adding one to a 79790075Sobrienreal constant. This is a GNU extension; if you have an ISO C99 79890075Sobrienconforming C library (such as GNU libc), and want to construct complex 79990075Sobrienconstants of floating type, you should include @code{<complex.h>} and 80090075Sobrienuse the macros @code{I} or @code{_Complex_I} instead. 80190075Sobrien 80290075Sobrien@cindex @code{__real__} keyword 80390075Sobrien@cindex @code{__imag__} keyword 80490075SobrienTo extract the real part of a complex-valued expression @var{exp}, write 80590075Sobrien@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to 80690075Sobrienextract the imaginary part. This is a GNU extension; for values of 80790075Sobrienfloating type, you should use the ISO C99 functions @code{crealf}, 80890075Sobrien@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and 80990075Sobrien@code{cimagl}, declared in @code{<complex.h>} and also provided as 81090075Sobrienbuilt-in functions by GCC@. 81190075Sobrien 81290075Sobrien@cindex complex conjugation 81390075SobrienThe operator @samp{~} performs complex conjugation when used on a value 81490075Sobrienwith a complex type. This is a GNU extension; for values of 81590075Sobrienfloating type, you should use the ISO C99 functions @code{conjf}, 81690075Sobrien@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also 81790075Sobrienprovided as built-in functions by GCC@. 81890075Sobrien 81990075SobrienGCC can allocate complex automatic variables in a noncontiguous 82090075Sobrienfashion; it's even possible for the real part to be in a register while 821117395Skanthe imaginary part is on the stack (or vice-versa). Only the DWARF2 822117395Skandebug info format can represent this, so use of DWARF2 is recommended. 823117395SkanIf you are using the stabs debug info format, GCC describes a noncontiguous 824117395Skancomplex variable as if it were two separate variables of noncomplex type. 82590075SobrienIf the variable's actual name is @code{foo}, the two fictitious 82690075Sobrienvariables are named @code{foo$real} and @code{foo$imag}. You can 82790075Sobrienexamine and set these two fictitious variables with your debugger. 82890075Sobrien 829169689Skan@node Decimal Float 830169689Skan@section Decimal Floating Types 831169689Skan@cindex decimal floating types 832169689Skan@cindex @code{_Decimal32} data type 833169689Skan@cindex @code{_Decimal64} data type 834169689Skan@cindex @code{_Decimal128} data type 835169689Skan@cindex @code{df} integer suffix 836169689Skan@cindex @code{dd} integer suffix 837169689Skan@cindex @code{dl} integer suffix 838169689Skan@cindex @code{DF} integer suffix 839169689Skan@cindex @code{DD} integer suffix 840169689Skan@cindex @code{DL} integer suffix 841169689Skan 842169689SkanAs an extension, the GNU C compiler supports decimal floating types as 843169689Skandefined in the N1176 draft of ISO/IEC WDTR24732. Support for decimal 844169689Skanfloating types in GCC will evolve as the draft technical report changes. 845169689SkanCalling conventions for any target might also change. Not all targets 846169689Skansupport decimal floating types. 847169689Skan 848169689SkanThe decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and 849169689Skan@code{_Decimal128}. They use a radix of ten, unlike the floating types 850169689Skan@code{float}, @code{double}, and @code{long double} whose radix is not 851169689Skanspecified by the C standard but is usually two. 852169689Skan 853169689SkanSupport for decimal floating types includes the arithmetic operators 854169689Skanadd, subtract, multiply, divide; unary arithmetic operators; 855169689Skanrelational operators; equality operators; and conversions to and from 856169689Skaninteger and other floating types. Use a suffix @samp{df} or 857169689Skan@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} 858169689Skanor @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for 859169689Skan@code{_Decimal128}. 860169689Skan 861169689SkanGCC support of decimal float as specified by the draft technical report 862169689Skanis incomplete: 863169689Skan 864169689Skan@itemize @bullet 865169689Skan@item 866169689SkanTranslation time data type (TTDT) is not supported. 867169689Skan 868169689Skan@item 869169689SkanCharacteristics of decimal floating types are defined in header file 870169689Skan@file{decfloat.h} rather than @file{float.h}. 871169689Skan 872169689Skan@item 873169689SkanWhen the value of a decimal floating type cannot be represented in the 874169689Skaninteger type to which it is being converted, the result is undefined 875169689Skanrather than the result value specified by the draft technical report. 876169689Skan@end itemize 877169689Skan 878169689SkanTypes @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} 879169689Skanare supported by the DWARF2 debug information format. 880169689Skan 88190075Sobrien@node Hex Floats 88290075Sobrien@section Hex Floats 88390075Sobrien@cindex hex floats 88490075Sobrien 88590075SobrienISO C99 supports floating-point numbers written not only in the usual 88690075Sobriendecimal notation, such as @code{1.55e1}, but also numbers such as 88790075Sobrien@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC 88890075Sobriensupports this in C89 mode (except in some cases when strictly 88990075Sobrienconforming) and in C++. In that format the 89090075Sobrien@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are 89190075Sobrienmandatory. The exponent is a decimal number that indicates the power of 89290075Sobrien2 by which the significant part will be multiplied. Thus @samp{0x1.f} is 89390075Sobrien@tex 89490075Sobrien$1 {15\over16}$, 89590075Sobrien@end tex 89690075Sobrien@ifnottex 89790075Sobrien1 15/16, 89890075Sobrien@end ifnottex 89990075Sobrien@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} 90090075Sobrienis the same as @code{1.55e1}. 90190075Sobrien 90290075SobrienUnlike for floating-point numbers in the decimal notation the exponent 90390075Sobrienis always required in the hexadecimal notation. Otherwise the compiler 90490075Sobrienwould not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This 90590075Sobriencould mean @code{1.0f} or @code{1.9375} since @samp{f} is also the 90690075Sobrienextension for floating-point constants of type @code{float}. 90790075Sobrien 90890075Sobrien@node Zero Length 90990075Sobrien@section Arrays of Length Zero 91090075Sobrien@cindex arrays of length zero 91190075Sobrien@cindex zero-length arrays 91290075Sobrien@cindex length-zero arrays 91390075Sobrien@cindex flexible array members 91490075Sobrien 91590075SobrienZero-length arrays are allowed in GNU C@. They are very useful as the 91690075Sobrienlast element of a structure which is really a header for a variable-length 91790075Sobrienobject: 91890075Sobrien 919132718Skan@smallexample 92090075Sobrienstruct line @{ 92190075Sobrien int length; 92290075Sobrien char contents[0]; 92390075Sobrien@}; 92490075Sobrien 92590075Sobrienstruct line *thisline = (struct line *) 92690075Sobrien malloc (sizeof (struct line) + this_length); 92790075Sobrienthisline->length = this_length; 928132718Skan@end smallexample 92990075Sobrien 930117395SkanIn ISO C90, you would have to give @code{contents} a length of 1, which 93190075Sobrienmeans either you waste space or complicate the argument to @code{malloc}. 93290075Sobrien 93390075SobrienIn ISO C99, you would use a @dfn{flexible array member}, which is 93490075Sobrienslightly different in syntax and semantics: 93590075Sobrien 93690075Sobrien@itemize @bullet 93790075Sobrien@item 93890075SobrienFlexible array members are written as @code{contents[]} without 93990075Sobrienthe @code{0}. 94090075Sobrien 94190075Sobrien@item 94290075SobrienFlexible array members have incomplete type, and so the @code{sizeof} 94390075Sobrienoperator may not be applied. As a quirk of the original implementation 94490075Sobrienof zero-length arrays, @code{sizeof} evaluates to zero. 94590075Sobrien 94690075Sobrien@item 94790075SobrienFlexible array members may only appear as the last member of a 94890075Sobrien@code{struct} that is otherwise non-empty. 949117395Skan 950117395Skan@item 951117395SkanA structure containing a flexible array member, or a union containing 952117395Skansuch a structure (possibly recursively), may not be a member of a 953117395Skanstructure or an element of an array. (However, these uses are 954117395Skanpermitted by GCC as extensions.) 95590075Sobrien@end itemize 95690075Sobrien 95790075SobrienGCC versions before 3.0 allowed zero-length arrays to be statically 95890075Sobrieninitialized, as if they were flexible arrays. In addition to those 95990075Sobriencases that were useful, it also allowed initializations in situations 96090075Sobrienthat would corrupt later data. Non-empty initialization of zero-length 96190075Sobrienarrays is now treated like any case where there are more initializer 96290075Sobrienelements than the array holds, in that a suitable warning about "excess 96390075Sobrienelements in array" is given, and the excess elements (all of them, in 96490075Sobrienthis case) are ignored. 96590075Sobrien 96690075SobrienInstead GCC allows static initialization of flexible array members. 96790075SobrienThis is equivalent to defining a new structure containing the original 96890075Sobrienstructure followed by an array of sufficient size to contain the data. 96990075SobrienI.e.@: in the following, @code{f1} is constructed as if it were declared 97090075Sobrienlike @code{f2}. 97190075Sobrien 972132718Skan@smallexample 97390075Sobrienstruct f1 @{ 97490075Sobrien int x; int y[]; 97590075Sobrien@} f1 = @{ 1, @{ 2, 3, 4 @} @}; 97690075Sobrien 97790075Sobrienstruct f2 @{ 97890075Sobrien struct f1 f1; int data[3]; 97990075Sobrien@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; 980132718Skan@end smallexample 98190075Sobrien 98290075Sobrien@noindent 98390075SobrienThe convenience of this extension is that @code{f1} has the desired 98490075Sobrientype, eliminating the need to consistently refer to @code{f2.f1}. 98590075Sobrien 98690075SobrienThis has symmetry with normal static arrays, in that an array of 98790075Sobrienunknown size is also written with @code{[]}. 98890075Sobrien 98990075SobrienOf course, this extension only makes sense if the extra data comes at 99090075Sobrienthe end of a top-level object, as otherwise we would be overwriting 99190075Sobriendata at subsequent offsets. To avoid undue complication and confusion 99290075Sobrienwith initialization of deeply nested arrays, we simply disallow any 99390075Sobriennon-empty initialization except when the structure is the top-level 99490075Sobrienobject. For example: 99590075Sobrien 996132718Skan@smallexample 99790075Sobrienstruct foo @{ int x; int y[]; @}; 99890075Sobrienstruct bar @{ struct foo z; @}; 99990075Sobrien 100090075Sobrienstruct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} 100190075Sobrienstruct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 100290075Sobrienstruct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} 100390075Sobrienstruct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1004132718Skan@end smallexample 100590075Sobrien 1006117395Skan@node Empty Structures 1007117395Skan@section Structures With No Members 1008117395Skan@cindex empty structures 1009117395Skan@cindex zero-size structures 1010117395Skan 1011117395SkanGCC permits a C structure to have no members: 1012117395Skan 1013132718Skan@smallexample 1014117395Skanstruct empty @{ 1015117395Skan@}; 1016132718Skan@end smallexample 1017117395Skan 1018117395SkanThe structure will have size zero. In C++, empty structures are part 1019119256Skanof the language. G++ treats empty structures as if they had a single 1020119256Skanmember of type @code{char}. 1021117395Skan 102290075Sobrien@node Variable Length 102390075Sobrien@section Arrays of Variable Length 102490075Sobrien@cindex variable-length arrays 102590075Sobrien@cindex arrays of variable length 102690075Sobrien@cindex VLAs 102790075Sobrien 102890075SobrienVariable-length automatic arrays are allowed in ISO C99, and as an 102990075Sobrienextension GCC accepts them in C89 mode and in C++. (However, GCC's 103090075Sobrienimplementation of variable-length arrays does not yet conform in detail 103190075Sobriento the ISO C99 standard.) These arrays are 103290075Sobriendeclared like any other automatic arrays, but with a length that is not 103390075Sobriena constant expression. The storage is allocated at the point of 103490075Sobriendeclaration and deallocated when the brace-level is exited. For 103590075Sobrienexample: 103690075Sobrien 1037132718Skan@smallexample 103890075SobrienFILE * 103990075Sobrienconcat_fopen (char *s1, char *s2, char *mode) 104090075Sobrien@{ 104190075Sobrien char str[strlen (s1) + strlen (s2) + 1]; 104290075Sobrien strcpy (str, s1); 104390075Sobrien strcat (str, s2); 104490075Sobrien return fopen (str, mode); 104590075Sobrien@} 1046132718Skan@end smallexample 104790075Sobrien 104890075Sobrien@cindex scope of a variable length array 104990075Sobrien@cindex variable-length array scope 105090075Sobrien@cindex deallocating variable length arrays 105190075SobrienJumping or breaking out of the scope of the array name deallocates the 105290075Sobrienstorage. Jumping into the scope is not allowed; you get an error 105390075Sobrienmessage for it. 105490075Sobrien 105590075Sobrien@cindex @code{alloca} vs variable-length arrays 105690075SobrienYou can use the function @code{alloca} to get an effect much like 105790075Sobrienvariable-length arrays. The function @code{alloca} is available in 105890075Sobrienmany other C implementations (but not in all). On the other hand, 105990075Sobrienvariable-length arrays are more elegant. 106090075Sobrien 106190075SobrienThere are other differences between these two methods. Space allocated 106290075Sobrienwith @code{alloca} exists until the containing @emph{function} returns. 106390075SobrienThe space for a variable-length array is deallocated as soon as the array 106490075Sobrienname's scope ends. (If you use both variable-length arrays and 106590075Sobrien@code{alloca} in the same function, deallocation of a variable-length array 106690075Sobrienwill also deallocate anything more recently allocated with @code{alloca}.) 106790075Sobrien 106890075SobrienYou can also use variable-length arrays as arguments to functions: 106990075Sobrien 1070132718Skan@smallexample 107190075Sobrienstruct entry 107290075Sobrientester (int len, char data[len][len]) 107390075Sobrien@{ 1074117395Skan /* @r{@dots{}} */ 107590075Sobrien@} 1076132718Skan@end smallexample 107790075Sobrien 107890075SobrienThe length of an array is computed once when the storage is allocated 107990075Sobrienand is remembered for the scope of the array in case you access it with 108090075Sobrien@code{sizeof}. 108190075Sobrien 108290075SobrienIf you want to pass the array first and the length afterward, you can 108390075Sobrienuse a forward declaration in the parameter list---another GNU extension. 108490075Sobrien 1085132718Skan@smallexample 108690075Sobrienstruct entry 108790075Sobrientester (int len; char data[len][len], int len) 108890075Sobrien@{ 1089117395Skan /* @r{@dots{}} */ 109090075Sobrien@} 1091132718Skan@end smallexample 109290075Sobrien 109390075Sobrien@cindex parameter forward declaration 109490075SobrienThe @samp{int len} before the semicolon is a @dfn{parameter forward 109590075Sobriendeclaration}, and it serves the purpose of making the name @code{len} 109690075Sobrienknown when the declaration of @code{data} is parsed. 109790075Sobrien 109890075SobrienYou can write any number of such parameter forward declarations in the 109990075Sobrienparameter list. They can be separated by commas or semicolons, but the 110090075Sobrienlast one must end with a semicolon, which is followed by the ``real'' 110190075Sobrienparameter declarations. Each forward declaration must match a ``real'' 110290075Sobriendeclaration in parameter name and data type. ISO C99 does not support 110390075Sobrienparameter forward declarations. 110490075Sobrien 110590075Sobrien@node Variadic Macros 110690075Sobrien@section Macros with a Variable Number of Arguments. 110790075Sobrien@cindex variable number of arguments 110890075Sobrien@cindex macro with variable arguments 110990075Sobrien@cindex rest argument (in macro) 111090075Sobrien@cindex variadic macros 111190075Sobrien 111290075SobrienIn the ISO C standard of 1999, a macro can be declared to accept a 111390075Sobrienvariable number of arguments much as a function can. The syntax for 111490075Sobriendefining the macro is similar to that of a function. Here is an 111590075Sobrienexample: 111690075Sobrien 1117103445Skan@smallexample 111890075Sobrien#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) 1119103445Skan@end smallexample 112090075Sobrien 112190075SobrienHere @samp{@dots{}} is a @dfn{variable argument}. In the invocation of 112290075Sobriensuch a macro, it represents the zero or more tokens until the closing 112390075Sobrienparenthesis that ends the invocation, including any commas. This set of 112490075Sobrientokens replaces the identifier @code{__VA_ARGS__} in the macro body 112590075Sobrienwherever it appears. See the CPP manual for more information. 112690075Sobrien 112790075SobrienGCC has long supported variadic macros, and used a different syntax that 112890075Sobrienallowed you to give a name to the variable arguments just like any other 112990075Sobrienargument. Here is an example: 113090075Sobrien 1131132718Skan@smallexample 113290075Sobrien#define debug(format, args...) fprintf (stderr, format, args) 1133132718Skan@end smallexample 113490075Sobrien 113590075SobrienThis is in all ways equivalent to the ISO C example above, but arguably 113690075Sobrienmore readable and descriptive. 113790075Sobrien 113890075SobrienGNU CPP has two further variadic macro extensions, and permits them to 113990075Sobrienbe used with either of the above forms of macro definition. 114090075Sobrien 114190075SobrienIn standard C, you are not allowed to leave the variable argument out 114290075Sobrienentirely; but you are allowed to pass an empty argument. For example, 114390075Sobrienthis invocation is invalid in ISO C, because there is no comma after 114490075Sobrienthe string: 114590075Sobrien 1146132718Skan@smallexample 114790075Sobriendebug ("A message") 1148132718Skan@end smallexample 114990075Sobrien 115090075SobrienGNU CPP permits you to completely omit the variable arguments in this 115190075Sobrienway. In the above examples, the compiler would complain, though since 115290075Sobrienthe expansion of the macro still has the extra comma after the format 115390075Sobrienstring. 115490075Sobrien 115590075SobrienTo help solve this problem, CPP behaves specially for variable arguments 115690075Sobrienused with the token paste operator, @samp{##}. If instead you write 115790075Sobrien 1158103445Skan@smallexample 115990075Sobrien#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) 1160103445Skan@end smallexample 116190075Sobrien 116290075Sobrienand if the variable arguments are omitted or empty, the @samp{##} 116390075Sobrienoperator causes the preprocessor to remove the comma before it. If you 116490075Sobriendo provide some variable arguments in your macro invocation, GNU CPP 116590075Sobriendoes not complain about the paste operation and instead places the 116690075Sobrienvariable arguments after the comma. Just like any other pasted macro 116790075Sobrienargument, these arguments are not macro expanded. 116890075Sobrien 116990075Sobrien@node Escaped Newlines 117090075Sobrien@section Slightly Looser Rules for Escaped Newlines 117190075Sobrien@cindex escaped newlines 117290075Sobrien@cindex newlines (escaped) 117390075Sobrien 1174117395SkanRecently, the preprocessor has relaxed its treatment of escaped 1175117395Skannewlines. Previously, the newline had to immediately follow a 1176119256Skanbackslash. The current implementation allows whitespace in the form 1177119256Skanof spaces, horizontal and vertical tabs, and form feeds between the 117890075Sobrienbackslash and the subsequent newline. The preprocessor issues a 117990075Sobrienwarning, but treats it as a valid escaped newline and combines the two 118090075Sobrienlines to form a single logical line. This works within comments and 1181117395Skantokens, as well as between tokens. Comments are @emph{not} treated as 1182117395Skanwhitespace for the purposes of this relaxation, since they have not 1183117395Skanyet been replaced with spaces. 118490075Sobrien 118590075Sobrien@node Subscripting 118690075Sobrien@section Non-Lvalue Arrays May Have Subscripts 118790075Sobrien@cindex subscripting 118890075Sobrien@cindex arrays, non-lvalue 118990075Sobrien 119090075Sobrien@cindex subscripting and function values 119190075SobrienIn ISO C99, arrays that are not lvalues still decay to pointers, and 119290075Sobrienmay be subscripted, although they may not be modified or used after 119390075Sobrienthe next sequence point and the unary @samp{&} operator may not be 119490075Sobrienapplied to them. As an extension, GCC allows such arrays to be 119590075Sobriensubscripted in C89 mode, though otherwise they do not decay to 119690075Sobrienpointers outside C99 mode. For example, 119790075Sobrienthis is valid in GNU C though not valid in C89: 119890075Sobrien 1199132718Skan@smallexample 120090075Sobrien@group 120190075Sobrienstruct foo @{int a[4];@}; 120290075Sobrien 120390075Sobrienstruct foo f(); 120490075Sobrien 120590075Sobrienbar (int index) 120690075Sobrien@{ 120790075Sobrien return f().a[index]; 120890075Sobrien@} 120990075Sobrien@end group 1210132718Skan@end smallexample 121190075Sobrien 121290075Sobrien@node Pointer Arith 121390075Sobrien@section Arithmetic on @code{void}- and Function-Pointers 121490075Sobrien@cindex void pointers, arithmetic 121590075Sobrien@cindex void, size of pointer to 121690075Sobrien@cindex function pointers, arithmetic 121790075Sobrien@cindex function, size of pointer to 121890075Sobrien 121990075SobrienIn GNU C, addition and subtraction operations are supported on pointers to 122090075Sobrien@code{void} and on pointers to functions. This is done by treating the 122190075Sobriensize of a @code{void} or of a function as 1. 122290075Sobrien 122390075SobrienA consequence of this is that @code{sizeof} is also allowed on @code{void} 122490075Sobrienand on function types, and returns 1. 122590075Sobrien 122690075Sobrien@opindex Wpointer-arith 122790075SobrienThe option @option{-Wpointer-arith} requests a warning if these extensions 122890075Sobrienare used. 122990075Sobrien 123090075Sobrien@node Initializers 123190075Sobrien@section Non-Constant Initializers 123290075Sobrien@cindex initializers, non-constant 123390075Sobrien@cindex non-constant initializers 123490075Sobrien 123590075SobrienAs in standard C++ and ISO C99, the elements of an aggregate initializer for an 123690075Sobrienautomatic variable are not required to be constant expressions in GNU C@. 123790075SobrienHere is an example of an initializer with run-time varying elements: 123890075Sobrien 1239132718Skan@smallexample 124090075Sobrienfoo (float f, float g) 124190075Sobrien@{ 124290075Sobrien float beat_freqs[2] = @{ f-g, f+g @}; 1243117395Skan /* @r{@dots{}} */ 124490075Sobrien@} 1245132718Skan@end smallexample 124690075Sobrien 124790075Sobrien@node Compound Literals 124890075Sobrien@section Compound Literals 124990075Sobrien@cindex constructor expressions 125090075Sobrien@cindex initializations in expressions 125190075Sobrien@cindex structures, constructor expression 125290075Sobrien@cindex expressions, constructor 125390075Sobrien@cindex compound literals 125490075Sobrien@c The GNU C name for what C99 calls compound literals was "constructor expressions". 125590075Sobrien 125690075SobrienISO C99 supports compound literals. A compound literal looks like 125790075Sobriena cast containing an initializer. Its value is an object of the 125890075Sobrientype specified in the cast, containing the elements specified in 125990075Sobrienthe initializer; it is an lvalue. As an extension, GCC supports 126090075Sobriencompound literals in C89 mode and in C++. 126190075Sobrien 126290075SobrienUsually, the specified type is a structure. Assume that 126390075Sobrien@code{struct foo} and @code{structure} are declared as shown: 126490075Sobrien 1265132718Skan@smallexample 126690075Sobrienstruct foo @{int a; char b[2];@} structure; 1267132718Skan@end smallexample 126890075Sobrien 126990075Sobrien@noindent 127090075SobrienHere is an example of constructing a @code{struct foo} with a compound literal: 127190075Sobrien 1272132718Skan@smallexample 127390075Sobrienstructure = ((struct foo) @{x + y, 'a', 0@}); 1274132718Skan@end smallexample 127590075Sobrien 127690075Sobrien@noindent 127790075SobrienThis is equivalent to writing the following: 127890075Sobrien 1279132718Skan@smallexample 128090075Sobrien@{ 128190075Sobrien struct foo temp = @{x + y, 'a', 0@}; 128290075Sobrien structure = temp; 128390075Sobrien@} 1284132718Skan@end smallexample 128590075Sobrien 128690075SobrienYou can also construct an array. If all the elements of the compound literal 128790075Sobrienare (made up of) simple constant expressions, suitable for use in 128890075Sobrieninitializers of objects of static storage duration, then the compound 128990075Sobrienliteral can be coerced to a pointer to its first element and used in 129090075Sobriensuch an initializer, as shown here: 129190075Sobrien 1292132718Skan@smallexample 129390075Sobrienchar **foo = (char *[]) @{ "x", "y", "z" @}; 1294132718Skan@end smallexample 129590075Sobrien 129690075SobrienCompound literals for scalar types and union types are is 129790075Sobrienalso allowed, but then the compound literal is equivalent 129890075Sobriento a cast. 129990075Sobrien 130090075SobrienAs a GNU extension, GCC allows initialization of objects with static storage 130190075Sobrienduration by compound literals (which is not possible in ISO C99, because 130290075Sobrienthe initializer is not a constant). 130390075SobrienIt is handled as if the object was initialized only with the bracket 1304169689Skanenclosed list if the types of the compound literal and the object match. 130590075SobrienThe initializer list of the compound literal must be constant. 130690075SobrienIf the object being initialized has array type of unknown size, the size is 130790075Sobriendetermined by compound literal size. 130890075Sobrien 1309132718Skan@smallexample 131090075Sobrienstatic struct foo x = (struct foo) @{1, 'a', 'b'@}; 131190075Sobrienstatic int y[] = (int []) @{1, 2, 3@}; 131290075Sobrienstatic int z[] = (int [3]) @{1@}; 1313132718Skan@end smallexample 131490075Sobrien 131590075Sobrien@noindent 131690075SobrienThe above lines are equivalent to the following: 1317132718Skan@smallexample 131890075Sobrienstatic struct foo x = @{1, 'a', 'b'@}; 131990075Sobrienstatic int y[] = @{1, 2, 3@}; 132090075Sobrienstatic int z[] = @{1, 0, 0@}; 1321132718Skan@end smallexample 132290075Sobrien 132390075Sobrien@node Designated Inits 132490075Sobrien@section Designated Initializers 132590075Sobrien@cindex initializers with labeled elements 132690075Sobrien@cindex labeled elements in initializers 132790075Sobrien@cindex case labels in initializers 132890075Sobrien@cindex designated initializers 132990075Sobrien 133090075SobrienStandard C89 requires the elements of an initializer to appear in a fixed 133190075Sobrienorder, the same as the order of the elements in the array or structure 133290075Sobrienbeing initialized. 133390075Sobrien 133490075SobrienIn ISO C99 you can give the elements in any order, specifying the array 133590075Sobrienindices or structure field names they apply to, and GNU C allows this as 133690075Sobrienan extension in C89 mode as well. This extension is not 133790075Sobrienimplemented in GNU C++. 133890075Sobrien 133990075SobrienTo specify an array index, write 134090075Sobrien@samp{[@var{index}] =} before the element value. For example, 134190075Sobrien 1342132718Skan@smallexample 134390075Sobrienint a[6] = @{ [4] = 29, [2] = 15 @}; 1344132718Skan@end smallexample 134590075Sobrien 134690075Sobrien@noindent 134790075Sobrienis equivalent to 134890075Sobrien 1349132718Skan@smallexample 135090075Sobrienint a[6] = @{ 0, 0, 15, 0, 29, 0 @}; 1351132718Skan@end smallexample 135290075Sobrien 135390075Sobrien@noindent 135490075SobrienThe index values must be constant expressions, even if the array being 135590075Sobrieninitialized is automatic. 135690075Sobrien 135790075SobrienAn alternative syntax for this which has been obsolete since GCC 2.5 but 135890075SobrienGCC still accepts is to write @samp{[@var{index}]} before the element 135990075Sobrienvalue, with no @samp{=}. 136090075Sobrien 136190075SobrienTo initialize a range of elements to the same value, write 136290075Sobrien@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU 136390075Sobrienextension. For example, 136490075Sobrien 1365132718Skan@smallexample 136690075Sobrienint widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; 1367132718Skan@end smallexample 136890075Sobrien 136990075Sobrien@noindent 137090075SobrienIf the value in it has side-effects, the side-effects will happen only once, 137190075Sobriennot for each initialized field by the range initializer. 137290075Sobrien 137390075Sobrien@noindent 137490075SobrienNote that the length of the array is the highest value specified 137590075Sobrienplus one. 137690075Sobrien 137790075SobrienIn a structure initializer, specify the name of a field to initialize 137890075Sobrienwith @samp{.@var{fieldname} =} before the element value. For example, 137990075Sobriengiven the following structure, 138090075Sobrien 1381132718Skan@smallexample 138290075Sobrienstruct point @{ int x, y; @}; 1383132718Skan@end smallexample 138490075Sobrien 138590075Sobrien@noindent 138690075Sobrienthe following initialization 138790075Sobrien 1388132718Skan@smallexample 138990075Sobrienstruct point p = @{ .y = yvalue, .x = xvalue @}; 1390132718Skan@end smallexample 139190075Sobrien 139290075Sobrien@noindent 139390075Sobrienis equivalent to 139490075Sobrien 1395132718Skan@smallexample 139690075Sobrienstruct point p = @{ xvalue, yvalue @}; 1397132718Skan@end smallexample 139890075Sobrien 139990075SobrienAnother syntax which has the same meaning, obsolete since GCC 2.5, is 140090075Sobrien@samp{@var{fieldname}:}, as shown here: 140190075Sobrien 1402132718Skan@smallexample 140390075Sobrienstruct point p = @{ y: yvalue, x: xvalue @}; 1404132718Skan@end smallexample 140590075Sobrien 140690075Sobrien@cindex designators 140790075SobrienThe @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a 140890075Sobrien@dfn{designator}. You can also use a designator (or the obsolete colon 140990075Sobriensyntax) when initializing a union, to specify which element of the union 141090075Sobrienshould be used. For example, 141190075Sobrien 1412132718Skan@smallexample 141390075Sobrienunion foo @{ int i; double d; @}; 141490075Sobrien 141590075Sobrienunion foo f = @{ .d = 4 @}; 1416132718Skan@end smallexample 141790075Sobrien 141890075Sobrien@noindent 141990075Sobrienwill convert 4 to a @code{double} to store it in the union using 142090075Sobrienthe second element. By contrast, casting 4 to type @code{union foo} 142190075Sobrienwould store it into the union as the integer @code{i}, since it is 142290075Sobrienan integer. (@xref{Cast to Union}.) 142390075Sobrien 142490075SobrienYou can combine this technique of naming elements with ordinary C 142590075Sobrieninitialization of successive elements. Each initializer element that 142690075Sobriendoes not have a designator applies to the next consecutive element of the 142790075Sobrienarray or structure. For example, 142890075Sobrien 1429132718Skan@smallexample 143090075Sobrienint a[6] = @{ [1] = v1, v2, [4] = v4 @}; 1431132718Skan@end smallexample 143290075Sobrien 143390075Sobrien@noindent 143490075Sobrienis equivalent to 143590075Sobrien 1436132718Skan@smallexample 143790075Sobrienint a[6] = @{ 0, v1, v2, 0, v4, 0 @}; 1438132718Skan@end smallexample 143990075Sobrien 144090075SobrienLabeling the elements of an array initializer is especially useful 144190075Sobrienwhen the indices are characters or belong to an @code{enum} type. 144290075SobrienFor example: 144390075Sobrien 1444132718Skan@smallexample 144590075Sobrienint whitespace[256] 144690075Sobrien = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, 144790075Sobrien ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; 1448132718Skan@end smallexample 144990075Sobrien 145090075Sobrien@cindex designator lists 145190075SobrienYou can also write a series of @samp{.@var{fieldname}} and 145290075Sobrien@samp{[@var{index}]} designators before an @samp{=} to specify a 145390075Sobriennested subobject to initialize; the list is taken relative to the 145490075Sobriensubobject corresponding to the closest surrounding brace pair. For 145590075Sobrienexample, with the @samp{struct point} declaration above: 145690075Sobrien 1457103445Skan@smallexample 145890075Sobrienstruct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; 1459103445Skan@end smallexample 146090075Sobrien 146190075Sobrien@noindent 146290075SobrienIf the same field is initialized multiple times, it will have value from 146390075Sobrienthe last initialization. If any such overridden initialization has 146490075Sobrienside-effect, it is unspecified whether the side-effect happens or not. 1465132718SkanCurrently, GCC will discard them and issue a warning. 146690075Sobrien 146790075Sobrien@node Case Ranges 146890075Sobrien@section Case Ranges 146990075Sobrien@cindex case ranges 147090075Sobrien@cindex ranges in case statements 147190075Sobrien 147290075SobrienYou can specify a range of consecutive values in a single @code{case} label, 147390075Sobrienlike this: 147490075Sobrien 1475132718Skan@smallexample 147690075Sobriencase @var{low} ... @var{high}: 1477132718Skan@end smallexample 147890075Sobrien 147990075Sobrien@noindent 148090075SobrienThis has the same effect as the proper number of individual @code{case} 148190075Sobrienlabels, one for each integer value from @var{low} to @var{high}, inclusive. 148290075Sobrien 148390075SobrienThis feature is especially useful for ranges of ASCII character codes: 148490075Sobrien 1485132718Skan@smallexample 148690075Sobriencase 'A' ... 'Z': 1487132718Skan@end smallexample 148890075Sobrien 148990075Sobrien@strong{Be careful:} Write spaces around the @code{...}, for otherwise 149090075Sobrienit may be parsed wrong when you use it with integer values. For example, 149190075Sobrienwrite this: 149290075Sobrien 1493132718Skan@smallexample 149490075Sobriencase 1 ... 5: 1495132718Skan@end smallexample 149690075Sobrien 149790075Sobrien@noindent 149890075Sobrienrather than this: 149990075Sobrien 1500132718Skan@smallexample 150190075Sobriencase 1...5: 1502132718Skan@end smallexample 150390075Sobrien 150490075Sobrien@node Cast to Union 150590075Sobrien@section Cast to a Union Type 150690075Sobrien@cindex cast to a union 150790075Sobrien@cindex union, casting to a 150890075Sobrien 150990075SobrienA cast to union type is similar to other casts, except that the type 151090075Sobrienspecified is a union type. You can specify the type either with 151190075Sobrien@code{union @var{tag}} or with a typedef name. A cast to union is actually 151290075Sobriena constructor though, not a cast, and hence does not yield an lvalue like 151390075Sobriennormal casts. (@xref{Compound Literals}.) 151490075Sobrien 151590075SobrienThe types that may be cast to the union type are those of the members 151690075Sobrienof the union. Thus, given the following union and variables: 151790075Sobrien 1518132718Skan@smallexample 151990075Sobrienunion foo @{ int i; double d; @}; 152090075Sobrienint x; 152190075Sobriendouble y; 1522132718Skan@end smallexample 152390075Sobrien 152490075Sobrien@noindent 152590075Sobrienboth @code{x} and @code{y} can be cast to type @code{union foo}. 152690075Sobrien 152790075SobrienUsing the cast as the right-hand side of an assignment to a variable of 152890075Sobrienunion type is equivalent to storing in a member of the union: 152990075Sobrien 1530132718Skan@smallexample 153190075Sobrienunion foo u; 1532117395Skan/* @r{@dots{}} */ 153390075Sobrienu = (union foo) x @equiv{} u.i = x 153490075Sobrienu = (union foo) y @equiv{} u.d = y 1535132718Skan@end smallexample 153690075Sobrien 153790075SobrienYou can also use the union cast as a function argument: 153890075Sobrien 1539132718Skan@smallexample 154090075Sobrienvoid hack (union foo); 1541117395Skan/* @r{@dots{}} */ 154290075Sobrienhack ((union foo) x); 1543132718Skan@end smallexample 154490075Sobrien 154590075Sobrien@node Mixed Declarations 154690075Sobrien@section Mixed Declarations and Code 154790075Sobrien@cindex mixed declarations and code 154890075Sobrien@cindex declarations, mixed with code 154990075Sobrien@cindex code, mixed with declarations 155090075Sobrien 155190075SobrienISO C99 and ISO C++ allow declarations and code to be freely mixed 155290075Sobrienwithin compound statements. As an extension, GCC also allows this in 155390075SobrienC89 mode. For example, you could do: 155490075Sobrien 1555132718Skan@smallexample 155690075Sobrienint i; 1557117395Skan/* @r{@dots{}} */ 155890075Sobrieni++; 155990075Sobrienint j = i + 2; 1560132718Skan@end smallexample 156190075Sobrien 156290075SobrienEach identifier is visible from where it is declared until the end of 156390075Sobrienthe enclosing block. 156490075Sobrien 156590075Sobrien@node Function Attributes 156690075Sobrien@section Declaring Attributes of Functions 156790075Sobrien@cindex function attributes 156890075Sobrien@cindex declaring attributes of functions 156990075Sobrien@cindex functions that never return 1570169689Skan@cindex functions that return more than once 157190075Sobrien@cindex functions that have no side effects 157290075Sobrien@cindex functions in arbitrary sections 157390075Sobrien@cindex functions that behave like malloc 157490075Sobrien@cindex @code{volatile} applied to function 157590075Sobrien@cindex @code{const} applied to function 157690075Sobrien@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments 1577117395Skan@cindex functions with non-null pointer arguments 157890075Sobrien@cindex functions that are passed arguments in registers on the 386 157990075Sobrien@cindex functions that pop the argument stack on the 386 158090075Sobrien@cindex functions that do not pop the argument stack on the 386 158190075Sobrien 158290075SobrienIn GNU C, you declare certain things about functions called in your program 158390075Sobrienwhich help the compiler optimize function calls and check your code more 158490075Sobriencarefully. 158590075Sobrien 158690075SobrienThe keyword @code{__attribute__} allows you to specify special 158790075Sobrienattributes when making a declaration. This keyword is followed by an 158890075Sobrienattribute specification inside double parentheses. The following 158990075Sobrienattributes are currently defined for functions on all targets: 1590259694Spfg@code{aligned}, 1591169689Skan@code{noreturn}, @code{returns_twice}, @code{noinline}, @code{always_inline}, 1592169689Skan@code{flatten}, @code{pure}, @code{const}, @code{nothrow}, @code{sentinel}, 159390075Sobrien@code{format}, @code{format_arg}, @code{no_instrument_function}, 159490075Sobrien@code{section}, @code{constructor}, @code{destructor}, @code{used}, 1595117395Skan@code{unused}, @code{deprecated}, @code{weak}, @code{malloc}, 1596169689Skan@code{alias}, @code{warn_unused_result}, @code{nonnull}, 1597169689Skan@code{gnu_inline} and @code{externally_visible}. Several other 1598132718Skanattributes are defined for functions on particular target systems. Other 1599132718Skanattributes, including @code{section} are supported for variables declarations 1600260918Spfg@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 1601260918Spfg(@pxref{Variable Attributes}), for types (@pxref{Type Attributes}), 1602260918Spfgand labels (@pxref{Label Attributes}). 160390075Sobrien 1604260918Spfg@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 160590075SobrienYou may also specify attributes with @samp{__} preceding and following 160690075Sobrieneach keyword. This allows you to use them in header files without 160790075Sobrienbeing concerned about a possible macro of the same name. For example, 160890075Sobrienyou may use @code{__noreturn__} instead of @code{noreturn}. 160990075Sobrien 161090075Sobrien@xref{Attribute Syntax}, for details of the exact syntax for using 161190075Sobrienattributes. 161290075Sobrien 161390075Sobrien@table @code 1614169689Skan@c Keep this table alphabetized by attribute name. Treat _ as space. 161590075Sobrien 1616169689Skan@item alias ("@var{target}") 1617169689Skan@cindex @code{alias} attribute 1618169689SkanThe @code{alias} attribute causes the declaration to be emitted as an 1619169689Skanalias for another symbol, which must be specified. For instance, 162090075Sobrien 162190075Sobrien@smallexample 1622169689Skanvoid __f () @{ /* @r{Do something.} */; @} 1623169689Skanvoid f () __attribute__ ((weak, alias ("__f"))); 162490075Sobrien@end smallexample 162590075Sobrien 1626169689Skandefines @samp{f} to be a weak alias for @samp{__f}. In C++, the 1627169689Skanmangled name for the target must be used. It is an error if @samp{__f} 1628169689Skanis not defined in the same translation unit. 1629146895Skan 1630169689SkanNot all target machines support this attribute. 163190075Sobrien 1632259694Spfg@item aligned (@var{alignment}) 1633259694Spfg@cindex @code{aligned} attribute 1634259694SpfgThis attribute specifies a minimum alignment for the function, 1635259694Spfgmeasured in bytes. 1636259694Spfg 1637259694SpfgYou cannot use this attribute to decrease the alignment of a function, 1638259694Spfgonly to increase it. However, when you explicitly specify a function 1639259694Spfgalignment this will override the effect of the 1640259694Spfg@option{-falign-functions} (@pxref{Optimize Options}) option for this 1641259694Spfgfunction. 1642259694Spfg 1643259694SpfgNote that the effectiveness of @code{aligned} attributes may be 1644259694Spfglimited by inherent limitations in your linker. On many systems, the 1645259694Spfglinker is only able to arrange for functions to be aligned up to a 1646259694Spfgcertain maximum alignment. (For some linkers, the maximum supported 1647259694Spfgalignment may be very very small.) See your linker documentation for 1648259694Spfgfurther information. 1649259694Spfg 1650259694SpfgThe @code{aligned} attribute can also be used for variables and fields 1651259694Spfg(@pxref{Variable Attributes}.) 1652259694Spfg 1653169689Skan@item always_inline 165496263Sobrien@cindex @code{always_inline} function attribute 165596263SobrienGenerally, functions are not inlined unless optimization is specified. 165696263SobrienFor functions declared inline, this attribute inlines the function even 165796263Sobrienif no optimization level was specified. 165896263Sobrien 1659169689Skan@item gnu_inline 1660169689Skan@cindex @code{gnu_inline} function attribute 1661169689SkanThis attribute should be used with a function which is also declared 1662169689Skanwith the @code{inline} keyword. It directs GCC to treat the function 1663169689Skanas if it were defined in gnu89 mode even when compiling in C99 or 1664169689Skangnu99 mode. 166590075Sobrien 1666169689SkanIf the function is declared @code{extern}, then this definition of the 1667169689Skanfunction is used only for inlining. In no case is the function 1668169689Skancompiled as a standalone function, not even if you take its address 1669169689Skanexplicitly. Such an address becomes an external reference, as if you 1670169689Skanhad only declared the function, and had not defined it. This has 1671169689Skanalmost the effect of a macro. The way to use this is to put a 1672169689Skanfunction definition in a header file with this attribute, and put 1673169689Skananother copy of the function, without @code{extern}, in a library 1674169689Skanfile. The definition in the header file will cause most calls to the 1675169689Skanfunction to be inlined. If any uses of the function remain, they will 1676169689Skanrefer to the single copy in the library. Note that the two 1677169689Skandefinitions of the functions need not be precisely the same, although 1678169689Skanif they do not have the same effect your program may behave oddly. 167990075Sobrien 1680169689SkanIf the function is neither @code{extern} nor @code{static}, then the 1681169689Skanfunction is compiled as a standalone function, as well as being 1682169689Skaninlined where possible. 168390075Sobrien 1684169689SkanThis is how GCC traditionally handled functions declared 1685169689Skan@code{inline}. Since ISO C99 specifies a different semantics for 1686169689Skan@code{inline}, this function attribute is provided as a transition 1687169689Skanmeasure and as a useful feature in its own right. This attribute is 1688169689Skanavailable in GCC 4.1.3 and later. It is available if either of the 1689169689Skanpreprocessor macros @code{__GNUC_GNU_INLINE__} or 1690169689Skan@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline 1691169689SkanFunction is As Fast As a Macro}. 169290075Sobrien 1693169689SkanNote that since the first version of GCC to support C99 inline semantics 1694169689Skanis 4.3, earlier versions of GCC which accept this attribute effectively 1695169689Skanassume that it is always present, whether or not it is given explicitly. 1696169689SkanIn versions prior to 4.3, the only effect of explicitly including it is 1697169689Skanto disable warnings about using inline functions in C99 mode. 1698169689Skan 1699169689Skan@cindex @code{flatten} function attribute 1700169689Skan@item flatten 1701169689SkanGenerally, inlining into a function is limited. For a function marked with 1702169689Skanthis attribute, every call inside this function will be inlined, if possible. 1703169689SkanWhether the function itself is considered for inlining depends on its size and 1704169689Skanthe current inlining parameters. The @code{flatten} attribute only works 1705169689Skanreliably in unit-at-a-time mode. 1706169689Skan 1707169689Skan@item cdecl 1708169689Skan@cindex functions that do pop the argument stack on the 386 1709169689Skan@opindex mrtd 1710169689SkanOn the Intel 386, the @code{cdecl} attribute causes the compiler to 1711169689Skanassume that the calling function will pop off the stack space used to 1712169689Skanpass arguments. This is 1713169689Skanuseful to override the effects of the @option{-mrtd} switch. 1714169689Skan 1715169689Skan@item const 171690075Sobrien@cindex @code{const} function attribute 171790075SobrienMany functions do not examine any values except their arguments, and 171890075Sobrienhave no effects except the return value. Basically this is just slightly 1719169689Skanmore strict class than the @code{pure} attribute below, since function is not 172090075Sobrienallowed to read global memory. 172190075Sobrien 172290075Sobrien@cindex pointer arguments 172390075SobrienNote that a function that has pointer arguments and examines the data 172490075Sobrienpointed to must @emph{not} be declared @code{const}. Likewise, a 172590075Sobrienfunction that calls a non-@code{const} function usually must not be 172690075Sobrien@code{const}. It does not make sense for a @code{const} function to 172790075Sobrienreturn @code{void}. 172890075Sobrien 172990075SobrienThe attribute @code{const} is not implemented in GCC versions earlier 173090075Sobrienthan 2.5. An alternative way to declare that a function has no side 173190075Sobrieneffects, which works in the current version and in some older versions, 173290075Sobrienis as follows: 173390075Sobrien 173490075Sobrien@smallexample 173590075Sobrientypedef int intfn (); 173690075Sobrien 173790075Sobrienextern const intfn square; 173890075Sobrien@end smallexample 173990075Sobrien 174090075SobrienThis approach does not work in GNU C++ from 2.6.0 on, since the language 174190075Sobrienspecifies that the @samp{const} must be attached to the return value. 174290075Sobrien 1743169689Skan@item constructor 1744169689Skan@itemx destructor 1745169689Skan@cindex @code{constructor} function attribute 1746169689Skan@cindex @code{destructor} function attribute 1747169689SkanThe @code{constructor} attribute causes the function to be called 1748169689Skanautomatically before execution enters @code{main ()}. Similarly, the 1749169689Skan@code{destructor} attribute causes the function to be called 1750169689Skanautomatically after @code{main ()} has completed or @code{exit ()} has 1751169689Skanbeen called. Functions with these attributes are useful for 1752169689Skaninitializing data that will be used implicitly during the execution of 1753169689Skanthe program. 175490075Sobrien 1755169689Skan@item deprecated 1756169689Skan@cindex @code{deprecated} attribute. 1757169689SkanThe @code{deprecated} attribute results in a warning if the function 1758169689Skanis used anywhere in the source file. This is useful when identifying 1759169689Skanfunctions that are expected to be removed in a future version of a 1760169689Skanprogram. The warning also includes the location of the declaration 1761169689Skanof the deprecated function, to enable users to easily find further 1762169689Skaninformation about why the function is deprecated, or what they should 1763169689Skando instead. Note that the warnings only occurs for uses: 1764169689Skan 1765169689Skan@smallexample 1766169689Skanint old_fn () __attribute__ ((deprecated)); 1767169689Skanint old_fn (); 1768169689Skanint (*fn_ptr)() = old_fn; 1769169689Skan@end smallexample 1770169689Skan 1771169689Skanresults in a warning on line 3 but not line 2. 1772169689Skan 1773169689SkanThe @code{deprecated} attribute can also be used for variables and 1774169689Skantypes (@pxref{Variable Attributes}, @pxref{Type Attributes}.) 1775169689Skan 1776169689Skan@item dllexport 1777169689Skan@cindex @code{__declspec(dllexport)} 1778169689SkanOn Microsoft Windows targets and Symbian OS targets the 1779169689Skan@code{dllexport} attribute causes the compiler to provide a global 1780169689Skanpointer to a pointer in a DLL, so that it can be referenced with the 1781169689Skan@code{dllimport} attribute. On Microsoft Windows targets, the pointer 1782169689Skanname is formed by combining @code{_imp__} and the function or variable 1783169689Skanname. 1784169689Skan 1785169689SkanYou can use @code{__declspec(dllexport)} as a synonym for 1786169689Skan@code{__attribute__ ((dllexport))} for compatibility with other 1787169689Skancompilers. 1788169689Skan 1789169689SkanOn systems that support the @code{visibility} attribute, this 1790169689Skanattribute also implies ``default'' visibility, unless a 1791169689Skan@code{visibility} attribute is explicitly specified. You should avoid 1792169689Skanthe use of @code{dllexport} with ``hidden'' or ``internal'' 1793169689Skanvisibility; in the future GCC may issue an error for those cases. 1794169689Skan 1795169689SkanCurrently, the @code{dllexport} attribute is ignored for inlined 1796169689Skanfunctions, unless the @option{-fkeep-inline-functions} flag has been 1797169689Skanused. The attribute is also ignored for undefined symbols. 1798169689Skan 1799169689SkanWhen applied to C++ classes, the attribute marks defined non-inlined 1800169689Skanmember functions and static data members as exports. Static consts 1801169689Skaninitialized in-class are not marked unless they are also defined 1802169689Skanout-of-class. 1803169689Skan 1804169689SkanFor Microsoft Windows targets there are alternative methods for 1805169689Skanincluding the symbol in the DLL's export table such as using a 1806169689Skan@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using 1807169689Skanthe @option{--export-all} linker flag. 1808169689Skan 1809169689Skan@item dllimport 1810169689Skan@cindex @code{__declspec(dllimport)} 1811169689SkanOn Microsoft Windows and Symbian OS targets, the @code{dllimport} 1812169689Skanattribute causes the compiler to reference a function or variable via 1813169689Skana global pointer to a pointer that is set up by the DLL exporting the 1814169689Skansymbol. The attribute implies @code{extern} storage. On Microsoft 1815169689SkanWindows targets, the pointer name is formed by combining @code{_imp__} 1816169689Skanand the function or variable name. 1817169689Skan 1818169689SkanYou can use @code{__declspec(dllimport)} as a synonym for 1819169689Skan@code{__attribute__ ((dllimport))} for compatibility with other 1820169689Skancompilers. 1821169689Skan 1822169689SkanCurrently, the attribute is ignored for inlined functions. If the 1823169689Skanattribute is applied to a symbol @emph{definition}, an error is reported. 1824169689SkanIf a symbol previously declared @code{dllimport} is later defined, the 1825169689Skanattribute is ignored in subsequent references, and a warning is emitted. 1826169689SkanThe attribute is also overridden by a subsequent declaration as 1827169689Skan@code{dllexport}. 1828169689Skan 1829169689SkanWhen applied to C++ classes, the attribute marks non-inlined 1830169689Skanmember functions and static data members as imports. However, the 1831169689Skanattribute is ignored for virtual methods to allow creation of vtables 1832169689Skanusing thunks. 1833169689Skan 1834169689SkanOn the SH Symbian OS target the @code{dllimport} attribute also has 1835169689Skananother affect---it can cause the vtable and run-time type information 1836169689Skanfor a class to be exported. This happens when the class has a 1837169689Skandllimport'ed constructor or a non-inline, non-pure virtual function 1838169689Skanand, for either of those two conditions, the class also has a inline 1839169689Skanconstructor or destructor and has a key function that is defined in 1840169689Skanthe current translation unit. 1841169689Skan 1842169689SkanFor Microsoft Windows based targets the use of the @code{dllimport} 1843169689Skanattribute on functions is not necessary, but provides a small 1844169689Skanperformance benefit by eliminating a thunk in the DLL@. The use of the 1845169689Skan@code{dllimport} attribute on imported variables was required on older 1846169689Skanversions of the GNU linker, but can now be avoided by passing the 1847169689Skan@option{--enable-auto-import} switch to the GNU linker. As with 1848169689Skanfunctions, using the attribute for a variable eliminates a thunk in 1849169689Skanthe DLL@. 1850169689Skan 1851169689SkanOne drawback to using this attribute is that a pointer to a function 1852169689Skanor variable marked as @code{dllimport} cannot be used as a constant 1853169689Skanaddress. On Microsoft Windows targets, the attribute can be disabled 1854169689Skanfor functions by setting the @option{-mnop-fun-dllimport} flag. 1855169689Skan 1856169689Skan@item eightbit_data 1857169689Skan@cindex eight bit data on the H8/300, H8/300H, and H8S 1858169689SkanUse this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 1859169689Skanvariable should be placed into the eight bit data section. 1860169689SkanThe compiler will generate more efficient code for certain operations 1861169689Skanon data in the eight bit data area. Note the eight bit data area is limited to 1862169689Skan256 bytes of data. 1863169689Skan 1864169689SkanYou must use GAS and GLD from GNU binutils version 2.7 or later for 1865169689Skanthis attribute to work correctly. 1866169689Skan 1867169689Skan@item exception_handler 1868169689Skan@cindex exception handler functions on the Blackfin processor 1869169689SkanUse this attribute on the Blackfin to indicate that the specified function 1870169689Skanis an exception handler. The compiler will generate function entry and 1871169689Skanexit sequences suitable for use in an exception handler when this 1872169689Skanattribute is present. 1873169689Skan 1874169689Skan@item far 1875169689Skan@cindex functions which handle memory bank switching 1876169689SkanOn 68HC11 and 68HC12 the @code{far} attribute causes the compiler to 1877169689Skanuse a calling convention that takes care of switching memory banks when 1878169689Skanentering and leaving a function. This calling convention is also the 1879169689Skandefault when using the @option{-mlong-calls} option. 1880169689Skan 1881169689SkanOn 68HC12 the compiler will use the @code{call} and @code{rtc} instructions 1882169689Skanto call and return from a function. 1883169689Skan 1884169689SkanOn 68HC11 the compiler will generate a sequence of instructions 1885169689Skanto invoke a board-specific routine to switch the memory bank and call the 1886169689Skanreal function. The board-specific routine simulates a @code{call}. 1887169689SkanAt the end of a function, it will jump to a board-specific routine 1888169689Skaninstead of using @code{rts}. The board-specific return routine simulates 1889169689Skanthe @code{rtc}. 1890169689Skan 1891169689Skan@item fastcall 1892169689Skan@cindex functions that pop the argument stack on the 386 1893169689SkanOn the Intel 386, the @code{fastcall} attribute causes the compiler to 1894169689Skanpass the first argument (if of integral type) in the register ECX and 1895169689Skanthe second argument (if of integral type) in the register EDX@. Subsequent 1896169689Skanand other typed arguments are passed on the stack. The called function will 1897169689Skanpop the arguments off the stack. If the number of arguments is variable all 1898169689Skanarguments are pushed on the stack. 1899169689Skan 190090075Sobrien@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) 190190075Sobrien@cindex @code{format} function attribute 190290075Sobrien@opindex Wformat 190390075SobrienThe @code{format} attribute specifies that a function takes @code{printf}, 190490075Sobrien@code{scanf}, @code{strftime} or @code{strfmon} style arguments which 190590075Sobrienshould be type-checked against a format string. For example, the 190690075Sobriendeclaration: 190790075Sobrien 190890075Sobrien@smallexample 190990075Sobrienextern int 191090075Sobrienmy_printf (void *my_object, const char *my_format, ...) 191190075Sobrien __attribute__ ((format (printf, 2, 3))); 191290075Sobrien@end smallexample 191390075Sobrien 191490075Sobrien@noindent 191590075Sobriencauses the compiler to check the arguments in calls to @code{my_printf} 191690075Sobrienfor consistency with the @code{printf} style format string argument 191790075Sobrien@code{my_format}. 191890075Sobrien 191990075SobrienThe parameter @var{archetype} determines how the format string is 192090075Sobrieninterpreted, and should be @code{printf}, @code{scanf}, @code{strftime} 192190075Sobrienor @code{strfmon}. (You can also use @code{__printf__}, 192290075Sobrien@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) The 192390075Sobrienparameter @var{string-index} specifies which argument is the format 192490075Sobrienstring argument (starting from 1), while @var{first-to-check} is the 192590075Sobriennumber of the first argument to check against the format string. For 192690075Sobrienfunctions where the arguments are not available to be checked (such as 192790075Sobrien@code{vprintf}), specify the third parameter as zero. In this case the 192890075Sobriencompiler only checks the format string for consistency. For 192990075Sobrien@code{strftime} formats, the third parameter is required to be zero. 1930119256SkanSince non-static C++ methods have an implicit @code{this} argument, the 1931119256Skanarguments of such methods should be counted from two, not one, when 1932119256Skangiving values for @var{string-index} and @var{first-to-check}. 193390075Sobrien 193490075SobrienIn the example above, the format string (@code{my_format}) is the second 193590075Sobrienargument of the function @code{my_print}, and the arguments to check 193690075Sobrienstart with the third argument, so the correct parameters for the format 193790075Sobrienattribute are 2 and 3. 193890075Sobrien 193990075Sobrien@opindex ffreestanding 1940169689Skan@opindex fno-builtin 194190075SobrienThe @code{format} attribute allows you to identify your own functions 194290075Sobrienwhich take format strings as arguments, so that GCC can check the 194390075Sobriencalls to these functions for errors. The compiler always (unless 1944169689Skan@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats 194590075Sobrienfor the standard library functions @code{printf}, @code{fprintf}, 194690075Sobrien@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, 194790075Sobrien@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such 194890075Sobrienwarnings are requested (using @option{-Wformat}), so there is no need to 194990075Sobrienmodify the header file @file{stdio.h}. In C99 mode, the functions 195090075Sobrien@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and 195190075Sobrien@code{vsscanf} are also checked. Except in strictly conforming C 195290075Sobrienstandard modes, the X/Open function @code{strfmon} is also checked as 195390075Sobrienare @code{printf_unlocked} and @code{fprintf_unlocked}. 195490075Sobrien@xref{C Dialect Options,,Options Controlling C Dialect}. 195590075Sobrien 1956169689SkanThe target may provide additional types of format checks. 1957169689Skan@xref{Target Format Checks,,Format Checks Specific to Particular 1958169689SkanTarget Machines}. 1959169689Skan 196090075Sobrien@item format_arg (@var{string-index}) 196190075Sobrien@cindex @code{format_arg} function attribute 196290075Sobrien@opindex Wformat-nonliteral 196390075SobrienThe @code{format_arg} attribute specifies that a function takes a format 196490075Sobrienstring for a @code{printf}, @code{scanf}, @code{strftime} or 196590075Sobrien@code{strfmon} style function and modifies it (for example, to translate 196690075Sobrienit into another language), so the result can be passed to a 196790075Sobrien@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style 196890075Sobrienfunction (with the remaining arguments to the format function the same 196990075Sobrienas they would have been for the unmodified string). For example, the 197090075Sobriendeclaration: 197190075Sobrien 197290075Sobrien@smallexample 197390075Sobrienextern char * 197490075Sobrienmy_dgettext (char *my_domain, const char *my_format) 197590075Sobrien __attribute__ ((format_arg (2))); 197690075Sobrien@end smallexample 197790075Sobrien 197890075Sobrien@noindent 197990075Sobriencauses the compiler to check the arguments in calls to a @code{printf}, 198090075Sobrien@code{scanf}, @code{strftime} or @code{strfmon} type function, whose 198190075Sobrienformat string argument is a call to the @code{my_dgettext} function, for 198290075Sobrienconsistency with the format string argument @code{my_format}. If the 198390075Sobrien@code{format_arg} attribute had not been specified, all the compiler 198490075Sobriencould tell in such calls to format functions would be that the format 198590075Sobrienstring argument is not constant; this would generate a warning when 198690075Sobrien@option{-Wformat-nonliteral} is used, but the calls could not be checked 198790075Sobrienwithout the attribute. 198890075Sobrien 198990075SobrienThe parameter @var{string-index} specifies which argument is the format 1990119256Skanstring argument (starting from one). Since non-static C++ methods have 1991119256Skanan implicit @code{this} argument, the arguments of such methods should 1992119256Skanbe counted from two. 199390075Sobrien 199490075SobrienThe @code{format-arg} attribute allows you to identify your own 199590075Sobrienfunctions which modify format strings, so that GCC can check the 199690075Sobriencalls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} 199790075Sobrientype function whose operands are a call to one of your own function. 199890075SobrienThe compiler always treats @code{gettext}, @code{dgettext}, and 199990075Sobrien@code{dcgettext} in this manner except when strict ISO C support is 200090075Sobrienrequested by @option{-ansi} or an appropriate @option{-std} option, or 2001169689Skan@option{-ffreestanding} or @option{-fno-builtin} 2002169689Skanis used. @xref{C Dialect Options,,Options 200390075SobrienControlling C Dialect}. 200490075Sobrien 2005169689Skan@item function_vector 2006169689Skan@cindex calling functions through the function vector on the H8/300 processors 2007169689SkanUse this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 2008169689Skanfunction should be called through the function vector. Calling a 2009169689Skanfunction through the function vector will reduce code size, however; 2010169689Skanthe function vector has a limited size (maximum 128 entries on the H8/300 2011169689Skanand 64 entries on the H8/300H and H8S) and shares space with the interrupt vector. 2012169689Skan 2013169689SkanYou must use GAS and GLD from GNU binutils version 2.7 or later for 2014169689Skanthis attribute to work correctly. 2015169689Skan 2016169689Skan@item interrupt 2017169689Skan@cindex interrupt handler functions 2018169689SkanUse this attribute on the ARM, AVR, C4x, CRX, M32C, M32R/D, MS1, and Xstormy16 2019169689Skanports to indicate that the specified function is an interrupt handler. 2020169689SkanThe compiler will generate function entry and exit sequences suitable 2021169689Skanfor use in an interrupt handler when this attribute is present. 2022169689Skan 2023169689SkanNote, interrupt handlers for the Blackfin, m68k, H8/300, H8/300H, H8S, and 2024169689SkanSH processors can be specified via the @code{interrupt_handler} attribute. 2025169689Skan 2026169689SkanNote, on the AVR, interrupts will be enabled inside the function. 2027169689Skan 2028169689SkanNote, for the ARM, you can specify the kind of interrupt to be handled by 2029169689Skanadding an optional parameter to the interrupt attribute like this: 2030169689Skan 2031169689Skan@smallexample 2032169689Skanvoid f () __attribute__ ((interrupt ("IRQ"))); 2033169689Skan@end smallexample 2034169689Skan 2035169689SkanPermissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@. 2036169689Skan 2037169689Skan@item interrupt_handler 2038169689Skan@cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors 2039169689SkanUse this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to 2040169689Skanindicate that the specified function is an interrupt handler. The compiler 2041169689Skanwill generate function entry and exit sequences suitable for use in an 2042169689Skaninterrupt handler when this attribute is present. 2043169689Skan 2044169689Skan@item kspisusp 2045169689Skan@cindex User stack pointer in interrupts on the Blackfin 2046169689SkanWhen used together with @code{interrupt_handler}, @code{exception_handler} 2047169689Skanor @code{nmi_handler}, code will be generated to load the stack pointer 2048169689Skanfrom the USP register in the function prologue. 2049169689Skan 2050169689Skan@item long_call/short_call 2051169689Skan@cindex indirect calls on ARM 2052169689SkanThis attribute specifies how a particular function is called on 2053169689SkanARM@. Both attributes override the @option{-mlong-calls} (@pxref{ARM Options}) 2054169689Skancommand line switch and @code{#pragma long_calls} settings. The 2055169689Skan@code{long_call} attribute indicates that the function might be far 2056169689Skanaway from the call site and require a different (more expensive) 2057169689Skancalling sequence. The @code{short_call} attribute always places 2058169689Skanthe offset to the function from the call site into the @samp{BL} 2059169689Skaninstruction directly. 2060169689Skan 2061169689Skan@item longcall/shortcall 2062169689Skan@cindex functions called via pointer on the RS/6000 and PowerPC 2063169689SkanOn the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute 2064169689Skanindicates that the function might be far away from the call site and 2065169689Skanrequire a different (more expensive) calling sequence. The 2066169689Skan@code{shortcall} attribute indicates that the function is always close 2067169689Skanenough for the shorter calling sequence to be used. These attributes 2068169689Skanoverride both the @option{-mlongcall} switch and, on the RS/6000 and 2069169689SkanPowerPC, the @code{#pragma longcall} setting. 2070169689Skan 2071169689Skan@xref{RS/6000 and PowerPC Options}, for more information on whether long 2072169689Skancalls are necessary. 2073169689Skan 2074169689Skan@item long_call 2075169689Skan@cindex indirect calls on MIPS 2076169689SkanThis attribute specifies how a particular function is called on MIPS@. 2077169689SkanThe attribute overrides the @option{-mlong-calls} (@pxref{MIPS Options}) 2078169689Skancommand line switch. This attribute causes the compiler to always call 2079169689Skanthe function by first loading its address into a register, and then using 2080169689Skanthe contents of that register. 2081169689Skan 2082169689Skan@item malloc 2083169689Skan@cindex @code{malloc} attribute 2084169689SkanThe @code{malloc} attribute is used to tell the compiler that a function 2085169689Skanmay be treated as if any non-@code{NULL} pointer it returns cannot 2086169689Skanalias any other pointer valid when the function returns. 2087169689SkanThis will often improve optimization. 2088169689SkanStandard functions with this property include @code{malloc} and 2089169689Skan@code{calloc}. @code{realloc}-like functions have this property as 2090169689Skanlong as the old pointer is never referred to (including comparing it 2091169689Skanto the new pointer) after the function returns a non-@code{NULL} 2092169689Skanvalue. 2093169689Skan 2094169689Skan@item model (@var{model-name}) 2095169689Skan@cindex function addressability on the M32R/D 2096169689Skan@cindex variable addressability on the IA-64 2097169689Skan 2098169689SkanOn the M32R/D, use this attribute to set the addressability of an 2099169689Skanobject, and of the code generated for a function. The identifier 2100169689Skan@var{model-name} is one of @code{small}, @code{medium}, or 2101169689Skan@code{large}, representing each of the code models. 2102169689Skan 2103169689SkanSmall model objects live in the lower 16MB of memory (so that their 2104169689Skanaddresses can be loaded with the @code{ld24} instruction), and are 2105169689Skancallable with the @code{bl} instruction. 2106169689Skan 2107169689SkanMedium model objects may live anywhere in the 32-bit address space (the 2108169689Skancompiler will generate @code{seth/add3} instructions to load their addresses), 2109169689Skanand are callable with the @code{bl} instruction. 2110169689Skan 2111169689SkanLarge model objects may live anywhere in the 32-bit address space (the 2112169689Skancompiler will generate @code{seth/add3} instructions to load their addresses), 2113169689Skanand may not be reachable with the @code{bl} instruction (the compiler will 2114169689Skangenerate the much slower @code{seth/add3/jl} instruction sequence). 2115169689Skan 2116169689SkanOn IA-64, use this attribute to set the addressability of an object. 2117169689SkanAt present, the only supported identifier for @var{model-name} is 2118169689Skan@code{small}, indicating addressability via ``small'' (22-bit) 2119169689Skanaddresses (so that their addresses can be loaded with the @code{addl} 2120169689Skaninstruction). Caveat: such addressing is by definition not position 2121169689Skanindependent and hence this attribute must not be used for objects 2122169689Skandefined by shared libraries. 2123169689Skan 2124169689Skan@item naked 2125169689Skan@cindex function without a prologue/epilogue code 2126169689SkanUse this attribute on the ARM, AVR, C4x and IP2K ports to indicate that the 2127169689Skanspecified function does not need prologue/epilogue sequences generated by 2128169689Skanthe compiler. It is up to the programmer to provide these sequences. 2129169689Skan 2130169689Skan@item near 2131169689Skan@cindex functions which do not handle memory bank switching on 68HC11/68HC12 2132169689SkanOn 68HC11 and 68HC12 the @code{near} attribute causes the compiler to 2133169689Skanuse the normal calling convention based on @code{jsr} and @code{rts}. 2134169689SkanThis attribute can be used to cancel the effect of the @option{-mlong-calls} 2135169689Skanoption. 2136169689Skan 2137169689Skan@item nesting 2138169689Skan@cindex Allow nesting in an interrupt handler on the Blackfin processor. 2139169689SkanUse this attribute together with @code{interrupt_handler}, 2140169689Skan@code{exception_handler} or @code{nmi_handler} to indicate that the function 2141169689Skanentry code should enable nested interrupts or exceptions. 2142169689Skan 2143169689Skan@item nmi_handler 2144169689Skan@cindex NMI handler functions on the Blackfin processor 2145169689SkanUse this attribute on the Blackfin to indicate that the specified function 2146169689Skanis an NMI handler. The compiler will generate function entry and 2147169689Skanexit sequences suitable for use in an NMI handler when this 2148169689Skanattribute is present. 2149169689Skan 2150169689Skan@item no_instrument_function 2151169689Skan@cindex @code{no_instrument_function} function attribute 2152169689Skan@opindex finstrument-functions 2153169689SkanIf @option{-finstrument-functions} is given, profiling function calls will 2154169689Skanbe generated at entry and exit of most user-compiled functions. 2155169689SkanFunctions with this attribute will not be so instrumented. 2156169689Skan 2157169689Skan@item noinline 2158169689Skan@cindex @code{noinline} function attribute 2159169689SkanThis function attribute prevents a function from being considered for 2160169689Skaninlining. 2161169689Skan 2162117395Skan@item nonnull (@var{arg-index}, @dots{}) 2163117395Skan@cindex @code{nonnull} function attribute 2164117395SkanThe @code{nonnull} attribute specifies that some function parameters should 2165117395Skanbe non-null pointers. For instance, the declaration: 2166117395Skan 2167117395Skan@smallexample 2168117395Skanextern void * 2169117395Skanmy_memcpy (void *dest, const void *src, size_t len) 2170117395Skan __attribute__((nonnull (1, 2))); 2171117395Skan@end smallexample 2172117395Skan 2173117395Skan@noindent 2174117395Skancauses the compiler to check that, in calls to @code{my_memcpy}, 2175117395Skanarguments @var{dest} and @var{src} are non-null. If the compiler 2176117395Skandetermines that a null pointer is passed in an argument slot marked 2177117395Skanas non-null, and the @option{-Wnonnull} option is enabled, a warning 2178117395Skanis issued. The compiler may also choose to make optimizations based 2179117395Skanon the knowledge that certain function arguments will not be null. 2180117395Skan 2181117395SkanIf no argument index list is given to the @code{nonnull} attribute, 2182117395Skanall pointer arguments are marked as non-null. To illustrate, the 2183117395Skanfollowing declaration is equivalent to the previous example: 2184117395Skan 2185117395Skan@smallexample 2186117395Skanextern void * 2187117395Skanmy_memcpy (void *dest, const void *src, size_t len) 2188117395Skan __attribute__((nonnull)); 2189117395Skan@end smallexample 2190117395Skan 2191169689Skan@item noreturn 2192169689Skan@cindex @code{noreturn} function attribute 2193169689SkanA few standard library functions, such as @code{abort} and @code{exit}, 2194169689Skancannot return. GCC knows this automatically. Some programs define 2195169689Skantheir own functions that never return. You can declare them 2196169689Skan@code{noreturn} to tell the compiler this fact. For example, 219790075Sobrien 219890075Sobrien@smallexample 2199169689Skan@group 2200169689Skanvoid fatal () __attribute__ ((noreturn)); 220190075Sobrien 2202169689Skanvoid 2203169689Skanfatal (/* @r{@dots{}} */) 2204132718Skan@{ 2205169689Skan /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ 2206169689Skan exit (1); 2207132718Skan@} 2208169689Skan@end group 2209132718Skan@end smallexample 2210132718Skan 2211169689SkanThe @code{noreturn} keyword tells the compiler to assume that 2212169689Skan@code{fatal} cannot return. It can then optimize without regard to what 2213169689Skanwould happen if @code{fatal} ever did return. This makes slightly 2214169689Skanbetter code. More importantly, it helps avoid spurious warnings of 2215169689Skanuninitialized variables. 2216132718Skan 2217169689SkanThe @code{noreturn} keyword does not affect the exceptional path when that 2218169689Skanapplies: a @code{noreturn}-marked function may still return to the caller 2219169689Skanby throwing an exception or calling @code{longjmp}. 222090075Sobrien 2221169689SkanDo not assume that registers saved by the calling function are 2222169689Skanrestored before calling the @code{noreturn} function. 222390075Sobrien 2224169689SkanIt does not make sense for a @code{noreturn} function to have a return 2225169689Skantype other than @code{void}. 222690075Sobrien 2227169689SkanThe attribute @code{noreturn} is not implemented in GCC versions 2228169689Skanearlier than 2.5. An alternative way to declare that a function does 2229169689Skannot return, which works in the current version and in some older 2230169689Skanversions, is as follows: 2231169689Skan 223290075Sobrien@smallexample 2233169689Skantypedef void voidfn (); 2234169689Skan 2235169689Skanvolatile voidfn fatal; 223690075Sobrien@end smallexample 223790075Sobrien 2238169689SkanThis approach does not work in GNU C++. 223990075Sobrien 2240169689Skan@item nothrow 2241169689Skan@cindex @code{nothrow} function attribute 2242169689SkanThe @code{nothrow} attribute is used to inform the compiler that a 2243169689Skanfunction cannot throw an exception. For example, most functions in 2244169689Skanthe standard C library can be guaranteed not to throw an exception 2245169689Skanwith the notable exceptions of @code{qsort} and @code{bsearch} that 2246169689Skantake function pointer arguments. The @code{nothrow} attribute is not 2247169689Skanimplemented in GCC versions earlier than 3.3. 224890075Sobrien 2249169689Skan@item pure 2250169689Skan@cindex @code{pure} function attribute 2251169689SkanMany functions have no effects except the return value and their 2252169689Skanreturn value depends only on the parameters and/or global variables. 2253169689SkanSuch a function can be subject 2254169689Skanto common subexpression elimination and loop optimization just as an 2255169689Skanarithmetic operator would be. These functions should be declared 2256169689Skanwith the attribute @code{pure}. For example, 2257117395Skan 2258117395Skan@smallexample 2259169689Skanint square (int) __attribute__ ((pure)); 2260117395Skan@end smallexample 2261117395Skan 2262169689Skan@noindent 2263169689Skansays that the hypothetical function @code{square} is safe to call 2264169689Skanfewer times than the program says. 2265117395Skan 2266169689SkanSome of common examples of pure functions are @code{strlen} or @code{memcmp}. 2267169689SkanInteresting non-pure functions are functions with infinite loops or those 2268169689Skandepending on volatile memory or other system resource, that may change between 2269169689Skantwo consecutive calls (such as @code{feof} in a multithreading environment). 2270117395Skan 2271169689SkanThe attribute @code{pure} is not implemented in GCC versions earlier 2272169689Skanthan 2.96. 2273117395Skan 227490075Sobrien@item regparm (@var{number}) 2275117395Skan@cindex @code{regparm} attribute 227690075Sobrien@cindex functions that are passed arguments in registers on the 386 227790075SobrienOn the Intel 386, the @code{regparm} attribute causes the compiler to 2278169689Skanpass arguments number one to @var{number} if they are of integral type 2279169689Skanin registers EAX, EDX, and ECX instead of on the stack. Functions that 2280169689Skantake a variable number of arguments will continue to be passed all of their 228190075Sobrienarguments on the stack. 228290075Sobrien 2283117395SkanBeware that on some ELF systems this attribute is unsuitable for 2284117395Skanglobal functions in shared libraries with lazy binding (which is the 2285117395Skandefault). Lazy binding will send the first call via resolving code in 2286117395Skanthe loader, which might assume EAX, EDX and ECX can be clobbered, as 2287117395Skanper the standard calling conventions. Solaris 8 is affected by this. 2288117395SkanGNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be 2289117395Skansafe since the loaders there save all registers. (Lazy binding can be 2290117395Skandisabled with the linker or the loader if desired, to avoid the 2291117395Skanproblem.) 2292117395Skan 2293169689Skan@item sseregparm 2294169689Skan@cindex @code{sseregparm} attribute 2295169689SkanOn the Intel 386 with SSE support, the @code{sseregparm} attribute 2296169689Skancauses the compiler to pass up to 3 floating point arguments in 2297169689SkanSSE registers instead of on the stack. Functions that take a 2298169689Skanvariable number of arguments will continue to pass all of their 2299169689Skanfloating point arguments on the stack. 230090075Sobrien 2301169689Skan@item force_align_arg_pointer 2302169689Skan@cindex @code{force_align_arg_pointer} attribute 2303169689SkanOn the Intel x86, the @code{force_align_arg_pointer} attribute may be 2304169689Skanapplied to individual function definitions, generating an alternate 2305169689Skanprologue and epilogue that realigns the runtime stack. This supports 2306169689Skanmixing legacy codes that run with a 4-byte aligned stack with modern 2307169689Skancodes that keep a 16-byte stack for SSE compatibility. The alternate 2308169689Skanprologue and epilogue are slower and bigger than the regular ones, and 2309169689Skanthe alternate prologue requires a scratch register; this lowers the 2310169689Skannumber of registers available if used in conjunction with the 2311169689Skan@code{regparm} attribute. The @code{force_align_arg_pointer} 2312169689Skanattribute is incompatible with nested functions; this is considered a 2313169689Skanhard error. 231490075Sobrien 2315169689Skan@item returns_twice 2316169689Skan@cindex @code{returns_twice} attribute 2317169689SkanThe @code{returns_twice} attribute tells the compiler that a function may 2318169689Skanreturn more than one time. The compiler will ensure that all registers 2319169689Skanare dead before calling such a function and will emit a warning about 2320169689Skanthe variables that may be clobbered after the second return from the 2321169689Skanfunction. Examples of such functions are @code{setjmp} and @code{vfork}. 2322169689SkanThe @code{longjmp}-like counterpart of such function, if any, might need 2323169689Skanto be marked with the @code{noreturn} attribute. 232490075Sobrien 2325169689Skan@item saveall 2326169689Skan@cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S 2327169689SkanUse this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that 2328169689Skanall registers except the stack pointer should be saved in the prologue 2329169689Skanregardless of whether they are used or not. 233090075Sobrien 2331169689Skan@item section ("@var{section-name}") 2332169689Skan@cindex @code{section} function attribute 2333169689SkanNormally, the compiler places the code it generates in the @code{text} section. 2334169689SkanSometimes, however, you need additional sections, or you need certain 2335169689Skanparticular functions to appear in special sections. The @code{section} 2336169689Skanattribute specifies that a function lives in a particular section. 2337169689SkanFor example, the declaration: 2338117395Skan 2339169689Skan@smallexample 2340169689Skanextern void foobar (void) __attribute__ ((section ("bar"))); 2341169689Skan@end smallexample 234290075Sobrien 2343169689Skan@noindent 2344169689Skanputs the function @code{foobar} in the @code{bar} section. 234590075Sobrien 2346169689SkanSome file formats do not support arbitrary sections so the @code{section} 2347169689Skanattribute is not available on all platforms. 2348169689SkanIf you need to map the entire contents of a module to a particular 2349169689Skansection, consider using the facilities of the linker instead. 235090075Sobrien 2351169689Skan@item sentinel 2352169689Skan@cindex @code{sentinel} function attribute 2353169689SkanThis function attribute ensures that a parameter in a function call is 2354169689Skanan explicit @code{NULL}. The attribute is only valid on variadic 2355169689Skanfunctions. By default, the sentinel is located at position zero, the 2356169689Skanlast parameter of the function call. If an optional integer position 2357169689Skanargument P is supplied to the attribute, the sentinel must be located at 2358169689Skanposition P counting backwards from the end of the argument list. 235990075Sobrien 2360169689Skan@smallexample 2361169689Skan__attribute__ ((sentinel)) 2362169689Skanis equivalent to 2363169689Skan__attribute__ ((sentinel(0))) 2364169689Skan@end smallexample 236590075Sobrien 2366169689SkanThe attribute is automatically set with a position of 0 for the built-in 2367169689Skanfunctions @code{execl} and @code{execlp}. The built-in function 2368169689Skan@code{execle} has the attribute set with a position of 1. 236990075Sobrien 2370169689SkanA valid @code{NULL} in this context is defined as zero with any pointer 2371169689Skantype. If your system defines the @code{NULL} macro with an integer type 2372169689Skanthen you need to add an explicit cast. GCC replaces @code{stddef.h} 2373169689Skanwith a copy that redefines NULL appropriately. 237490075Sobrien 2375169689SkanThe warnings for missing or incorrect sentinels are enabled with 2376169689Skan@option{-Wformat}. 237790075Sobrien 2378169689Skan@item short_call 2379169689SkanSee long_call/short_call. 238090075Sobrien 2381169689Skan@item shortcall 2382169689SkanSee longcall/shortcall. 238390075Sobrien 2384169689Skan@item signal 2385169689Skan@cindex signal handler functions on the AVR processors 2386169689SkanUse this attribute on the AVR to indicate that the specified 2387169689Skanfunction is a signal handler. The compiler will generate function 2388169689Skanentry and exit sequences suitable for use in a signal handler when this 2389169689Skanattribute is present. Interrupts will be disabled inside the function. 2390169689Skan 239190075Sobrien@item sp_switch 239290075SobrienUse this attribute on the SH to indicate an @code{interrupt_handler} 239390075Sobrienfunction should switch to an alternate stack. It expects a string 239490075Sobrienargument that names a global variable holding the address of the 239590075Sobrienalternate stack. 239690075Sobrien 239790075Sobrien@smallexample 239890075Sobrienvoid *alt_stack; 239990075Sobrienvoid f () __attribute__ ((interrupt_handler, 240090075Sobrien sp_switch ("alt_stack"))); 240190075Sobrien@end smallexample 240290075Sobrien 2403169689Skan@item stdcall 2404169689Skan@cindex functions that pop the argument stack on the 386 2405169689SkanOn the Intel 386, the @code{stdcall} attribute causes the compiler to 2406169689Skanassume that the called function will pop off the stack space used to 2407169689Skanpass arguments, unless it takes a variable number of arguments. 240890075Sobrien 240990075Sobrien@item tiny_data 2410132718Skan@cindex tiny data section on the H8/300H and H8S 2411132718SkanUse this attribute on the H8/300H and H8S to indicate that the specified 241290075Sobrienvariable should be placed into the tiny data section. 241390075SobrienThe compiler will generate more efficient code for loads and stores 241490075Sobrienon data in the tiny data section. Note the tiny data area is limited to 241590075Sobrienslightly under 32kbytes of data. 241690075Sobrien 2417169689Skan@item trap_exit 2418169689SkanUse this attribute on the SH for an @code{interrupt_handler} to return using 2419169689Skan@code{trapa} instead of @code{rte}. This attribute expects an integer 2420169689Skanargument specifying the trap number to be used. 2421132718Skan 2422169689Skan@item unused 2423169689Skan@cindex @code{unused} attribute. 2424169689SkanThis attribute, attached to a function, means that the function is meant 2425169689Skanto be possibly unused. GCC will not produce a warning for this 2426169689Skanfunction. 242790075Sobrien 2428169689Skan@item used 2429169689Skan@cindex @code{used} attribute. 2430169689SkanThis attribute, attached to a function, means that code must be emitted 2431169689Skanfor the function even if it appears that the function is not referenced. 2432169689SkanThis is useful, for example, when the function is referenced only in 2433169689Skaninline assembly. 243490075Sobrien 2435169689Skan@item visibility ("@var{visibility_type}") 2436169689Skan@cindex @code{visibility} attribute 2437169689SkanThis attribute affects the linkage of the declaration to which it is attached. 2438169689SkanThere are four supported @var{visibility_type} values: default, 2439169689Skanhidden, protected or internal visibility. 244090075Sobrien 2441169689Skan@smallexample 2442169689Skanvoid __attribute__ ((visibility ("protected"))) 2443169689Skanf () @{ /* @r{Do something.} */; @} 2444169689Skanint i __attribute__ ((visibility ("hidden"))); 2445169689Skan@end smallexample 2446132718Skan 2447169689SkanThe possible values of @var{visibility_type} correspond to the 2448169689Skanvisibility settings in the ELF gABI. 244990075Sobrien 2450169689Skan@table @dfn 2451169689Skan@c keep this list of visibilities in alphabetical order. 245290075Sobrien 2453169689Skan@item default 2454169689SkanDefault visibility is the normal case for the object file format. 2455169689SkanThis value is available for the visibility attribute to override other 2456169689Skanoptions that may change the assumed visibility of entities. 245790075Sobrien 2458169689SkanOn ELF, default visibility means that the declaration is visible to other 2459169689Skanmodules and, in shared libraries, means that the declared entity may be 2460169689Skanoverridden. 2461132718Skan 2462169689SkanOn Darwin, default visibility means that the declaration is visible to 2463169689Skanother modules. 2464117395Skan 2465169689SkanDefault visibility corresponds to ``external linkage'' in the language. 2466117395Skan 2467169689Skan@item hidden 2468169689SkanHidden visibility indicates that the entity declared will have a new 2469169689Skanform of linkage, which we'll call ``hidden linkage''. Two 2470169689Skandeclarations of an object with hidden linkage refer to the same object 2471169689Skanif they are in the same shared object. 2472117395Skan 2473169689Skan@item internal 2474169689SkanInternal visibility is like hidden visibility, but with additional 2475169689Skanprocessor specific semantics. Unless otherwise specified by the 2476169689SkanpsABI, GCC defines internal visibility to mean that a function is 2477169689Skan@emph{never} called from another module. Compare this with hidden 2478169689Skanfunctions which, while they cannot be referenced directly by other 2479169689Skanmodules, can be referenced indirectly via function pointers. By 2480169689Skanindicating that a function cannot be called from outside the module, 2481169689SkanGCC may for instance omit the load of a PIC register since it is known 2482169689Skanthat the calling function loaded the correct value. 2483117395Skan 2484169689Skan@item protected 2485169689SkanProtected visibility is like default visibility except that it 2486169689Skanindicates that references within the defining module will bind to the 2487169689Skandefinition in that module. That is, the declared entity cannot be 2488169689Skanoverridden by another module. 2489119256Skan 2490169689Skan@end table 2491119256Skan 2492169689SkanAll visibilities are supported on many, but not all, ELF targets 2493169689Skan(supported when the assembler supports the @samp{.visibility} 2494169689Skanpseudo-op). Default visibility is supported everywhere. Hidden 2495169689Skanvisibility is supported on Darwin targets. 2496119256Skan 2497169689SkanThe visibility attribute should be applied only to declarations which 2498169689Skanwould otherwise have external linkage. The attribute should be applied 2499169689Skanconsistently, so that the same entity should not be declared with 2500169689Skandifferent settings of the attribute. 2501119256Skan 2502169689SkanIn C++, the visibility attribute applies to types as well as functions 2503169689Skanand objects, because in C++ types have linkage. A class must not have 2504169689Skangreater visibility than its non-static data member types and bases, 2505169689Skanand class members default to the visibility of their class. Also, a 2506169689Skandeclaration without explicit visibility is limited to the visibility 2507169689Skanof its type. 2508119256Skan 2509169689SkanIn C++, you can mark member functions and static member variables of a 2510169689Skanclass with the visibility attribute. This is useful if if you know a 2511169689Skanparticular method or static member variable should only be used from 2512169689Skanone shared object; then you can mark it hidden while the rest of the 2513169689Skanclass has default visibility. Care must be taken to avoid breaking 2514169689Skanthe One Definition Rule; for example, it is usually not useful to mark 2515169689Skanan inline method as hidden without marking the whole class as hidden. 2516119256Skan 2517169689SkanA C++ namespace declaration can also have the visibility attribute. 2518169689SkanThis attribute applies only to the particular namespace body, not to 2519169689Skanother definitions of the same namespace; it is equivalent to using 2520169689Skan@samp{#pragma GCC visibility} before and after the namespace 2521169689Skandefinition (@pxref{Visibility Pragmas}). 2522119256Skan 2523169689SkanIn C++, if a template argument has limited visibility, this 2524169689Skanrestriction is implicitly propagated to the template instantiation. 2525169689SkanOtherwise, template instantiations and specializations default to the 2526169689Skanvisibility of their template. 2527119256Skan 2528169689SkanIf both the template and enclosing class have explicit visibility, the 2529169689Skanvisibility from the template is used. 2530119256Skan 2531169689Skan@item warn_unused_result 2532169689Skan@cindex @code{warn_unused_result} attribute 2533169689SkanThe @code{warn_unused_result} attribute causes a warning to be emitted 2534169689Skanif a caller of the function with this attribute does not use its 2535169689Skanreturn value. This is useful for functions where not checking 2536169689Skanthe result is either a security problem or always a bug, such as 2537169689Skan@code{realloc}. 2538119256Skan 2539169689Skan@smallexample 2540169689Skanint fn () __attribute__ ((warn_unused_result)); 2541169689Skanint foo () 2542169689Skan@{ 2543169689Skan if (fn () < 0) return -1; 2544169689Skan fn (); 2545169689Skan return 0; 2546169689Skan@} 2547169689Skan@end smallexample 2548119256Skan 2549169689Skanresults in warning on line 5. 2550169689Skan 2551169689Skan@item weak 2552169689Skan@cindex @code{weak} attribute 2553169689SkanThe @code{weak} attribute causes the declaration to be emitted as a weak 2554169689Skansymbol rather than a global. This is primarily useful in defining 2555169689Skanlibrary functions which can be overridden in user code, though it can 2556169689Skanalso be used with non-function declarations. Weak symbols are supported 2557169689Skanfor ELF targets, and also for a.out targets when using the GNU assembler 2558169689Skanand linker. 2559169689Skan 2560169689Skan@item weakref 2561169689Skan@itemx weakref ("@var{target}") 2562169689Skan@cindex @code{weakref} attribute 2563169689SkanThe @code{weakref} attribute marks a declaration as a weak reference. 2564169689SkanWithout arguments, it should be accompanied by an @code{alias} attribute 2565169689Skannaming the target symbol. Optionally, the @var{target} may be given as 2566169689Skanan argument to @code{weakref} itself. In either case, @code{weakref} 2567169689Skanimplicitly marks the declaration as @code{weak}. Without a 2568169689Skan@var{target}, given as an argument to @code{weakref} or to @code{alias}, 2569169689Skan@code{weakref} is equivalent to @code{weak}. 2570169689Skan 2571169689Skan@smallexample 2572169689Skanstatic int x() __attribute__ ((weakref ("y"))); 2573169689Skan/* is equivalent to... */ 2574169689Skanstatic int x() __attribute__ ((weak, weakref, alias ("y"))); 2575169689Skan/* and to... */ 2576169689Skanstatic int x() __attribute__ ((weakref)); 2577169689Skanstatic int x() __attribute__ ((alias ("y"))); 2578169689Skan@end smallexample 2579169689Skan 2580169689SkanA weak reference is an alias that does not by itself require a 2581169689Skandefinition to be given for the target symbol. If the target symbol is 2582169689Skanonly referenced through weak references, then the becomes a @code{weak} 2583169689Skanundefined symbol. If it is directly referenced, however, then such 2584169689Skanstrong references prevail, and a definition will be required for the 2585169689Skansymbol, not necessarily in the same translation unit. 2586169689Skan 2587169689SkanThe effect is equivalent to moving all references to the alias to a 2588169689Skanseparate translation unit, renaming the alias to the aliased symbol, 2589169689Skandeclaring it as weak, compiling the two separate translation units and 2590169689Skanperforming a reloadable link on them. 2591169689Skan 2592169689SkanAt present, a declaration to which @code{weakref} is attached can 2593169689Skanonly be @code{static}. 2594169689Skan 2595169689Skan@item externally_visible 2596169689Skan@cindex @code{externally_visible} attribute. 2597169689SkanThis attribute, attached to a global variable or function nullify 2598169689Skaneffect of @option{-fwhole-program} command line option, so the object 2599169689Skanremain visible outside the current compilation unit 2600169689Skan 260190075Sobrien@end table 260290075Sobrien 260390075SobrienYou can specify multiple attributes in a declaration by separating them 260490075Sobrienby commas within the double parentheses or by immediately following an 260590075Sobrienattribute declaration with another attribute declaration. 260690075Sobrien 260790075Sobrien@cindex @code{#pragma}, reason for not using 260890075Sobrien@cindex pragma, reason for not using 260990075SobrienSome people object to the @code{__attribute__} feature, suggesting that 261090075SobrienISO C's @code{#pragma} should be used instead. At the time 261190075Sobrien@code{__attribute__} was designed, there were two reasons for not doing 261290075Sobrienthis. 261390075Sobrien 261490075Sobrien@enumerate 261590075Sobrien@item 261690075SobrienIt is impossible to generate @code{#pragma} commands from a macro. 261790075Sobrien 261890075Sobrien@item 261990075SobrienThere is no telling what the same @code{#pragma} might mean in another 262090075Sobriencompiler. 262190075Sobrien@end enumerate 262290075Sobrien 262390075SobrienThese two reasons applied to almost any application that might have been 262490075Sobrienproposed for @code{#pragma}. It was basically a mistake to use 262590075Sobrien@code{#pragma} for @emph{anything}. 262690075Sobrien 262790075SobrienThe ISO C99 standard includes @code{_Pragma}, which now allows pragmas 262890075Sobriento be generated from macros. In addition, a @code{#pragma GCC} 262990075Sobriennamespace is now in use for GCC-specific pragmas. However, it has been 263090075Sobrienfound convenient to use @code{__attribute__} to achieve a natural 263190075Sobrienattachment of attributes to their corresponding declarations, whereas 263290075Sobrien@code{#pragma GCC} is of use for constructs that do not naturally form 263390075Sobrienpart of the grammar. @xref{Other Directives,,Miscellaneous 2634122180SkanPreprocessing Directives, cpp, The GNU C Preprocessor}. 263590075Sobrien 263690075Sobrien@node Attribute Syntax 263790075Sobrien@section Attribute Syntax 263890075Sobrien@cindex attribute syntax 263990075Sobrien 264090075SobrienThis section describes the syntax with which @code{__attribute__} may be 264190075Sobrienused, and the constructs to which attribute specifiers bind, for the C 2642220755Sdimlanguage. Some details may vary for C++. Because of infelicities in 2643220755Sdimthe grammar for attributes, some forms described here may not be 2644220755Sdimsuccessfully parsed in all cases. 264590075Sobrien 264690075SobrienThere are some problems with the semantics of attributes in C++. For 264790075Sobrienexample, there are no manglings for attributes, although they may affect 264890075Sobriencode generation, so problems may arise when attributed types are used in 264990075Sobrienconjunction with templates or overloading. Similarly, @code{typeid} 265090075Sobriendoes not distinguish between types with different attributes. Support 265190075Sobrienfor attributes in C++ may be restricted in future to attributes on 265290075Sobriendeclarations only, but not on nested declarators. 265390075Sobrien 265490075Sobrien@xref{Function Attributes}, for details of the semantics of attributes 265590075Sobrienapplying to functions. @xref{Variable Attributes}, for details of the 2656260918Spfg@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 2657260918Spfgsemantics of attributes applying to variables. @xref{Type 2658260918SpfgAttributes}, for details of the semantics of attributes applying to 2659260918Spfgstructure, union and enumerated types. @xref{Label Attributes}, for 2660260918Spfgdetails of the semantics of attributes applying to labels and 2661260918Spfgstatements. 266290075Sobrien 2663260918Spfg@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 266490075SobrienAn @dfn{attribute specifier} is of the form 266590075Sobrien@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} 266690075Sobrienis a possibly empty comma-separated sequence of @dfn{attributes}, where 266790075Sobrieneach attribute is one of the following: 266890075Sobrien 266990075Sobrien@itemize @bullet 267090075Sobrien@item 267190075SobrienEmpty. Empty attributes are ignored. 267290075Sobrien 267390075Sobrien@item 267490075SobrienA word (which may be an identifier such as @code{unused}, or a reserved 267590075Sobrienword such as @code{const}). 267690075Sobrien 267790075Sobrien@item 267890075SobrienA word, followed by, in parentheses, parameters for the attribute. 267990075SobrienThese parameters take one of the following forms: 268090075Sobrien 268190075Sobrien@itemize @bullet 268290075Sobrien@item 268390075SobrienAn identifier. For example, @code{mode} attributes use this form. 268490075Sobrien 268590075Sobrien@item 268690075SobrienAn identifier followed by a comma and a non-empty comma-separated list 268790075Sobrienof expressions. For example, @code{format} attributes use this form. 268890075Sobrien 268990075Sobrien@item 269090075SobrienA possibly empty comma-separated list of expressions. For example, 269190075Sobrien@code{format_arg} attributes use this form with the list being a single 269290075Sobrieninteger constant expression, and @code{alias} attributes use this form 269390075Sobrienwith the list being a single string constant. 269490075Sobrien@end itemize 269590075Sobrien@end itemize 269690075Sobrien 269790075SobrienAn @dfn{attribute specifier list} is a sequence of one or more attribute 269890075Sobrienspecifiers, not separated by any other tokens. 269990075Sobrien 2700260918Spfg@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 2701260918SpfgIn GNU C, an attribute specifier list may appear after the colon 2702260918Spfgfollowing a label, other than a @code{case} or @code{default} label. 2703260918SpfgGNU C++ does not permit such placement of attribute lists, as it is 2704260918Spfgpermissible for a declaration, which could begin with an attribute 2705260918Spfglist, to be labelled in C++. Declarations cannot be labelled in C90 2706260918Spfgor C99, so the ambiguity does not arise there. 270790075Sobrien 2708260918SpfgIn GNU C an attribute specifier list may also appear after the keyword 2709260918Spfg@code{while} in a while loop, after @code{do} and after @code{for}. 2710260918Spfg 2711260918Spfg@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 271290075SobrienAn attribute specifier list may appear as part of a @code{struct}, 271390075Sobrien@code{union} or @code{enum} specifier. It may go either immediately 271490075Sobrienafter the @code{struct}, @code{union} or @code{enum} keyword, or after 2715169689Skanthe closing brace. The former syntax is preferred. 271690075SobrienWhere attribute specifiers follow the closing brace, they are considered 271790075Sobriento relate to the structure, union or enumerated type defined, not to any 271890075Sobrienenclosing declaration the type specifier appears in, and the type 271990075Sobriendefined is not complete until after the attribute specifiers. 272090075Sobrien@c Otherwise, there would be the following problems: a shift/reduce 272190075Sobrien@c conflict between attributes binding the struct/union/enum and 272290075Sobrien@c binding to the list of specifiers/qualifiers; and "aligned" 272390075Sobrien@c attributes could use sizeof for the structure, but the size could be 272490075Sobrien@c changed later by "packed" attributes. 272590075Sobrien 272690075SobrienOtherwise, an attribute specifier appears as part of a declaration, 272790075Sobriencounting declarations of unnamed parameters and type names, and relates 272890075Sobriento that declaration (which may be nested in another declaration, for 272990075Sobrienexample in the case of a parameter declaration), or to a particular declarator 273090075Sobrienwithin a declaration. Where an 273190075Sobrienattribute specifier is applied to a parameter declared as a function or 273290075Sobrienan array, it should apply to the function or array rather than the 273390075Sobrienpointer to which the parameter is implicitly converted, but this is not 273490075Sobrienyet correctly implemented. 273590075Sobrien 273690075SobrienAny list of specifiers and qualifiers at the start of a declaration may 273790075Sobriencontain attribute specifiers, whether or not such a list may in that 273890075Sobriencontext contain storage class specifiers. (Some attributes, however, 273990075Sobrienare essentially in the nature of storage class specifiers, and only make 274090075Sobriensense where storage class specifiers may be used; for example, 274190075Sobrien@code{section}.) There is one necessary limitation to this syntax: the 274290075Sobrienfirst old-style parameter declaration in a function definition cannot 274390075Sobrienbegin with an attribute specifier, because such an attribute applies to 274490075Sobrienthe function instead by syntax described below (which, however, is not 274590075Sobrienyet implemented in this case). In some other cases, attribute 274690075Sobrienspecifiers are permitted by this grammar but not yet supported by the 274790075Sobriencompiler. All attribute specifiers in this place relate to the 274890075Sobriendeclaration as a whole. In the obsolescent usage where a type of 274990075Sobrien@code{int} is implied by the absence of type specifiers, such a list of 275090075Sobrienspecifiers and qualifiers may be an attribute specifier list with no 275190075Sobrienother specifiers or qualifiers. 275290075Sobrien 2753169689SkanAt present, the first parameter in a function prototype must have some 2754169689Skantype specifier which is not an attribute specifier; this resolves an 2755169689Skanambiguity in the interpretation of @code{void f(int 2756169689Skan(__attribute__((foo)) x))}, but is subject to change. At present, if 2757169689Skanthe parentheses of a function declarator contain only attributes then 2758169689Skanthose attributes are ignored, rather than yielding an error or warning 2759169689Skanor implying a single parameter of type int, but this is subject to 2760169689Skanchange. 2761169689Skan 276290075SobrienAn attribute specifier list may appear immediately before a declarator 276390075Sobrien(other than the first) in a comma-separated list of declarators in a 276490075Sobriendeclaration of more than one identifier using a single list of 276590075Sobrienspecifiers and qualifiers. Such attribute specifiers apply 276690075Sobrienonly to the identifier before whose declarator they appear. For 276790075Sobrienexample, in 276890075Sobrien 276990075Sobrien@smallexample 277090075Sobrien__attribute__((noreturn)) void d0 (void), 277190075Sobrien __attribute__((format(printf, 1, 2))) d1 (const char *, ...), 277290075Sobrien d2 (void) 277390075Sobrien@end smallexample 277490075Sobrien 277590075Sobrien@noindent 277690075Sobrienthe @code{noreturn} attribute applies to all the functions 277790075Sobriendeclared; the @code{format} attribute only applies to @code{d1}. 277890075Sobrien 277990075SobrienAn attribute specifier list may appear immediately before the comma, 278090075Sobrien@code{=} or semicolon terminating the declaration of an identifier other 278190075Sobrienthan a function definition. At present, such attribute specifiers apply 278290075Sobriento the declared object or function, but in future they may attach to the 278390075Sobrienoutermost adjacent declarator. In simple cases there is no difference, 278496263Sobrienbut, for example, in 278590075Sobrien 278690075Sobrien@smallexample 278790075Sobrienvoid (****f)(void) __attribute__((noreturn)); 278890075Sobrien@end smallexample 278990075Sobrien 279090075Sobrien@noindent 279190075Sobrienat present the @code{noreturn} attribute applies to @code{f}, which 279290075Sobriencauses a warning since @code{f} is not a function, but in future it may 279390075Sobrienapply to the function @code{****f}. The precise semantics of what 279490075Sobrienattributes in such cases will apply to are not yet specified. Where an 279590075Sobrienassembler name for an object or function is specified (@pxref{Asm 279690075SobrienLabels}), at present the attribute must follow the @code{asm} 279790075Sobrienspecification; in future, attributes before the @code{asm} specification 279890075Sobrienmay apply to the adjacent declarator, and those after it to the declared 279990075Sobrienobject or function. 280090075Sobrien 280190075SobrienAn attribute specifier list may, in future, be permitted to appear after 280290075Sobrienthe declarator in a function definition (before any old-style parameter 280390075Sobriendeclarations or the function body). 280490075Sobrien 280590075SobrienAttribute specifiers may be mixed with type qualifiers appearing inside 280690075Sobrienthe @code{[]} of a parameter array declarator, in the C99 construct by 280790075Sobrienwhich such qualifiers are applied to the pointer to which the array is 280890075Sobrienimplicitly converted. Such attribute specifiers apply to the pointer, 280990075Sobriennot to the array, but at present this is not implemented and they are 281090075Sobrienignored. 281190075Sobrien 281290075SobrienAn attribute specifier list may appear at the start of a nested 281390075Sobriendeclarator. At present, there are some limitations in this usage: the 281490075Sobrienattributes correctly apply to the declarator, but for most individual 281590075Sobrienattributes the semantics this implies are not implemented. 281690075SobrienWhen attribute specifiers follow the @code{*} of a pointer 281790075Sobriendeclarator, they may be mixed with any type qualifiers present. 281890075SobrienThe following describes the formal semantics of this syntax. It will make the 281990075Sobrienmost sense if you are familiar with the formal specification of 282090075Sobriendeclarators in the ISO C standard. 282190075Sobrien 282290075SobrienConsider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T 282390075SobrienD1}, where @code{T} contains declaration specifiers that specify a type 282490075Sobrien@var{Type} (such as @code{int}) and @code{D1} is a declarator that 282590075Sobriencontains an identifier @var{ident}. The type specified for @var{ident} 282690075Sobrienfor derived declarators whose type does not include an attribute 282790075Sobrienspecifier is as in the ISO C standard. 282890075Sobrien 282990075SobrienIf @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, 283090075Sobrienand the declaration @code{T D} specifies the type 283190075Sobrien``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 283290075Sobrien@code{T D1} specifies the type ``@var{derived-declarator-type-list} 283390075Sobrien@var{attribute-specifier-list} @var{Type}'' for @var{ident}. 283490075Sobrien 283590075SobrienIf @code{D1} has the form @code{* 283690075Sobrien@var{type-qualifier-and-attribute-specifier-list} D}, and the 283790075Sobriendeclaration @code{T D} specifies the type 283890075Sobrien``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 283990075Sobrien@code{T D1} specifies the type ``@var{derived-declarator-type-list} 284090075Sobrien@var{type-qualifier-and-attribute-specifier-list} @var{Type}'' for 284190075Sobrien@var{ident}. 284290075Sobrien 284396263SobrienFor example, 284490075Sobrien 284590075Sobrien@smallexample 284690075Sobrienvoid (__attribute__((noreturn)) ****f) (void); 284790075Sobrien@end smallexample 284890075Sobrien 284990075Sobrien@noindent 285090075Sobrienspecifies the type ``pointer to pointer to pointer to pointer to 285190075Sobriennon-returning function returning @code{void}''. As another example, 285290075Sobrien 285390075Sobrien@smallexample 285490075Sobrienchar *__attribute__((aligned(8))) *f; 285590075Sobrien@end smallexample 285690075Sobrien 285790075Sobrien@noindent 285890075Sobrienspecifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. 285990075SobrienNote again that this does not work with most attributes; for example, 286090075Sobrienthe usage of @samp{aligned} and @samp{noreturn} attributes given above 286190075Sobrienis not yet supported. 286290075Sobrien 286390075SobrienFor compatibility with existing code written for compiler versions that 286490075Sobriendid not implement attributes on nested declarators, some laxity is 286590075Sobrienallowed in the placing of attributes. If an attribute that only applies 286690075Sobriento types is applied to a declaration, it will be treated as applying to 286790075Sobrienthe type of that declaration. If an attribute that only applies to 286890075Sobriendeclarations is applied to the type of a declaration, it will be treated 286990075Sobrienas applying to that declaration; and, for compatibility with code 287090075Sobrienplacing the attributes immediately before the identifier declared, such 287190075Sobrienan attribute applied to a function return type will be treated as 287290075Sobrienapplying to the function type, and such an attribute applied to an array 287390075Sobrienelement type will be treated as applying to the array type. If an 287490075Sobrienattribute that only applies to function types is applied to a 287590075Sobrienpointer-to-function type, it will be treated as applying to the pointer 287690075Sobrientarget type; if such an attribute is applied to a function return type 287790075Sobrienthat is not a pointer-to-function type, it will be treated as applying 287890075Sobriento the function type. 287990075Sobrien 288090075Sobrien@node Function Prototypes 288190075Sobrien@section Prototypes and Old-Style Function Definitions 288290075Sobrien@cindex function prototype declarations 288390075Sobrien@cindex old-style function definitions 288490075Sobrien@cindex promotion of formal parameters 288590075Sobrien 288690075SobrienGNU C extends ISO C to allow a function prototype to override a later 288790075Sobrienold-style non-prototype definition. Consider the following example: 288890075Sobrien 2889132718Skan@smallexample 289090075Sobrien/* @r{Use prototypes unless the compiler is old-fashioned.} */ 289190075Sobrien#ifdef __STDC__ 289290075Sobrien#define P(x) x 289390075Sobrien#else 289490075Sobrien#define P(x) () 289590075Sobrien#endif 289690075Sobrien 289790075Sobrien/* @r{Prototype function declaration.} */ 289890075Sobrienint isroot P((uid_t)); 289990075Sobrien 290090075Sobrien/* @r{Old-style function definition.} */ 290190075Sobrienint 2902169689Skanisroot (x) /* @r{??? lossage here ???} */ 290390075Sobrien uid_t x; 290490075Sobrien@{ 290590075Sobrien return x == 0; 290690075Sobrien@} 2907132718Skan@end smallexample 290890075Sobrien 290990075SobrienSuppose the type @code{uid_t} happens to be @code{short}. ISO C does 291090075Sobriennot allow this example, because subword arguments in old-style 291190075Sobriennon-prototype definitions are promoted. Therefore in this example the 291290075Sobrienfunction definition's argument is really an @code{int}, which does not 291390075Sobrienmatch the prototype argument type of @code{short}. 291490075Sobrien 291590075SobrienThis restriction of ISO C makes it hard to write code that is portable 291690075Sobriento traditional C compilers, because the programmer does not know 291790075Sobrienwhether the @code{uid_t} type is @code{short}, @code{int}, or 291890075Sobrien@code{long}. Therefore, in cases like these GNU C allows a prototype 291990075Sobriento override a later old-style definition. More precisely, in GNU C, a 292090075Sobrienfunction prototype argument type overrides the argument type specified 292190075Sobrienby a later old-style definition if the former type is the same as the 292290075Sobrienlatter type before promotion. Thus in GNU C the above example is 292390075Sobrienequivalent to the following: 292490075Sobrien 2925132718Skan@smallexample 292690075Sobrienint isroot (uid_t); 292790075Sobrien 292890075Sobrienint 292990075Sobrienisroot (uid_t x) 293090075Sobrien@{ 293190075Sobrien return x == 0; 293290075Sobrien@} 2933132718Skan@end smallexample 293490075Sobrien 293590075Sobrien@noindent 293690075SobrienGNU C++ does not support old-style function definitions, so this 293790075Sobrienextension is irrelevant. 293890075Sobrien 293990075Sobrien@node C++ Comments 294090075Sobrien@section C++ Style Comments 294190075Sobrien@cindex // 294290075Sobrien@cindex C++ comments 294390075Sobrien@cindex comments, C++ style 294490075Sobrien 294590075SobrienIn GNU C, you may use C++ style comments, which start with @samp{//} and 294690075Sobriencontinue until the end of the line. Many other C implementations allow 2947117395Skansuch comments, and they are included in the 1999 C standard. However, 2948117395SkanC++ style comments are not recognized if you specify an @option{-std} 2949117395Skanoption specifying a version of ISO C before C99, or @option{-ansi} 2950117395Skan(equivalent to @option{-std=c89}). 295190075Sobrien 295290075Sobrien@node Dollar Signs 295390075Sobrien@section Dollar Signs in Identifier Names 295490075Sobrien@cindex $ 295590075Sobrien@cindex dollar signs in identifier names 295690075Sobrien@cindex identifier names, dollar signs in 295790075Sobrien 295890075SobrienIn GNU C, you may normally use dollar signs in identifier names. 295990075SobrienThis is because many traditional C implementations allow such identifiers. 296090075SobrienHowever, dollar signs in identifiers are not supported on a few target 296190075Sobrienmachines, typically because the target assembler does not allow them. 296290075Sobrien 296390075Sobrien@node Character Escapes 296490075Sobrien@section The Character @key{ESC} in Constants 296590075Sobrien 296690075SobrienYou can use the sequence @samp{\e} in a string or character constant to 296790075Sobrienstand for the ASCII character @key{ESC}. 296890075Sobrien 296990075Sobrien@node Alignment 297090075Sobrien@section Inquiring on Alignment of Types or Variables 297190075Sobrien@cindex alignment 297290075Sobrien@cindex type alignment 297390075Sobrien@cindex variable alignment 297490075Sobrien 297590075SobrienThe keyword @code{__alignof__} allows you to inquire about how an object 297690075Sobrienis aligned, or the minimum alignment usually required by a type. Its 297790075Sobriensyntax is just like @code{sizeof}. 297890075Sobrien 297990075SobrienFor example, if the target machine requires a @code{double} value to be 298090075Sobrienaligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. 298190075SobrienThis is true on many RISC machines. On more traditional machine 298290075Sobriendesigns, @code{__alignof__ (double)} is 4 or even 2. 298390075Sobrien 298490075SobrienSome machines never actually require alignment; they allow reference to any 2985119256Skandata type even at an odd address. For these machines, @code{__alignof__} 298690075Sobrienreports the @emph{recommended} alignment of a type. 298790075Sobrien 298890075SobrienIf the operand of @code{__alignof__} is an lvalue rather than a type, 298990075Sobrienits value is the required alignment for its type, taking into account 299090075Sobrienany minimum alignment specified with GCC's @code{__attribute__} 299190075Sobrienextension (@pxref{Variable Attributes}). For example, after this 299290075Sobriendeclaration: 299390075Sobrien 2994132718Skan@smallexample 299590075Sobrienstruct foo @{ int x; char y; @} foo1; 2996132718Skan@end smallexample 299790075Sobrien 299890075Sobrien@noindent 299990075Sobrienthe value of @code{__alignof__ (foo1.y)} is 1, even though its actual 300090075Sobrienalignment is probably 2 or 4, the same as @code{__alignof__ (int)}. 300190075Sobrien 300290075SobrienIt is an error to ask for the alignment of an incomplete type. 300390075Sobrien 300490075Sobrien@node Variable Attributes 300590075Sobrien@section Specifying Attributes of Variables 300690075Sobrien@cindex attribute of variables 300790075Sobrien@cindex variable attributes 300890075Sobrien 300990075SobrienThe keyword @code{__attribute__} allows you to specify special 301090075Sobrienattributes of variables or structure fields. This keyword is followed 3011119256Skanby an attribute specification inside double parentheses. Some 3012119256Skanattributes are currently defined generically for variables. 3013119256SkanOther attributes are defined for variables on particular target 3014119256Skansystems. Other attributes are available for functions 3015260918Spfg@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 3016260918Spfg(@pxref{Function Attributes}), types (@pxref{Type Attributes}) and 3017260918Spfglabels (@pxref{Label Attributes}). Other front ends might define 3018260918Spfgmore attributes (@pxref{C++ Extensions,,Extensions to the C++ Language}). 301990075Sobrien 3020260918Spfg@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 302190075SobrienYou may also specify attributes with @samp{__} preceding and following 302290075Sobrieneach keyword. This allows you to use them in header files without 302390075Sobrienbeing concerned about a possible macro of the same name. For example, 302490075Sobrienyou may use @code{__aligned__} instead of @code{aligned}. 302590075Sobrien 302690075Sobrien@xref{Attribute Syntax}, for details of the exact syntax for using 302790075Sobrienattributes. 302890075Sobrien 302990075Sobrien@table @code 303090075Sobrien@cindex @code{aligned} attribute 303190075Sobrien@item aligned (@var{alignment}) 303290075SobrienThis attribute specifies a minimum alignment for the variable or 303390075Sobrienstructure field, measured in bytes. For example, the declaration: 303490075Sobrien 303590075Sobrien@smallexample 303690075Sobrienint x __attribute__ ((aligned (16))) = 0; 303790075Sobrien@end smallexample 303890075Sobrien 303990075Sobrien@noindent 304090075Sobriencauses the compiler to allocate the global variable @code{x} on a 304190075Sobrien16-byte boundary. On a 68040, this could be used in conjunction with 304290075Sobrienan @code{asm} expression to access the @code{move16} instruction which 304390075Sobrienrequires 16-byte aligned operands. 304490075Sobrien 304590075SobrienYou can also specify the alignment of structure fields. For example, to 304690075Sobriencreate a double-word aligned @code{int} pair, you could write: 304790075Sobrien 304890075Sobrien@smallexample 304990075Sobrienstruct foo @{ int x[2] __attribute__ ((aligned (8))); @}; 305090075Sobrien@end smallexample 305190075Sobrien 305290075Sobrien@noindent 305390075SobrienThis is an alternative to creating a union with a @code{double} member 305490075Sobrienthat forces the union to be double-word aligned. 305590075Sobrien 305690075SobrienAs in the preceding examples, you can explicitly specify the alignment 305790075Sobrien(in bytes) that you wish the compiler to use for a given variable or 305890075Sobrienstructure field. Alternatively, you can leave out the alignment factor 305990075Sobrienand just ask the compiler to align a variable or field to the maximum 306090075Sobrienuseful alignment for the target machine you are compiling for. For 306190075Sobrienexample, you could write: 306290075Sobrien 306390075Sobrien@smallexample 306490075Sobrienshort array[3] __attribute__ ((aligned)); 306590075Sobrien@end smallexample 306690075Sobrien 306790075SobrienWhenever you leave out the alignment factor in an @code{aligned} attribute 306890075Sobrienspecification, the compiler automatically sets the alignment for the declared 306990075Sobrienvariable or field to the largest alignment which is ever used for any data 307090075Sobrientype on the target machine you are compiling for. Doing this can often make 307190075Sobriencopy operations more efficient, because the compiler can use whatever 307290075Sobrieninstructions copy the biggest chunks of memory when performing copies to 307390075Sobrienor from the variables or fields that you have aligned this way. 307490075Sobrien 307590075SobrienThe @code{aligned} attribute can only increase the alignment; but you 307690075Sobriencan decrease it by specifying @code{packed} as well. See below. 307790075Sobrien 307890075SobrienNote that the effectiveness of @code{aligned} attributes may be limited 307990075Sobrienby inherent limitations in your linker. On many systems, the linker is 308090075Sobrienonly able to arrange for variables to be aligned up to a certain maximum 308190075Sobrienalignment. (For some linkers, the maximum supported alignment may 308290075Sobrienbe very very small.) If your linker is only able to align variables 308390075Sobrienup to a maximum of 8 byte alignment, then specifying @code{aligned(16)} 308490075Sobrienin an @code{__attribute__} will still only provide you with 8 byte 308590075Sobrienalignment. See your linker documentation for further information. 308690075Sobrien 3087259694SpfgThe @code{aligned} attribute can also be used for functions 3088259694Spfg(@pxref{Function Attributes}.) 3089259694Spfg 3090117395Skan@item cleanup (@var{cleanup_function}) 3091117395Skan@cindex @code{cleanup} attribute 3092117395SkanThe @code{cleanup} attribute runs a function when the variable goes 3093117395Skanout of scope. This attribute can only be applied to auto function 3094117395Skanscope variables; it may not be applied to parameters or variables 3095117395Skanwith static storage duration. The function must take one parameter, 3096117395Skana pointer to a type compatible with the variable. The return value 3097117395Skanof the function (if any) is ignored. 3098117395Skan 3099117395SkanIf @option{-fexceptions} is enabled, then @var{cleanup_function} 3100117395Skanwill be run during the stack unwinding that happens during the 3101117395Skanprocessing of the exception. Note that the @code{cleanup} attribute 3102117395Skandoes not allow the exception to be caught, only to perform an action. 3103117395SkanIt is undefined what happens if @var{cleanup_function} does not 3104117395Skanreturn normally. 3105117395Skan 3106119256Skan@item common 3107119256Skan@itemx nocommon 3108119256Skan@cindex @code{common} attribute 3109119256Skan@cindex @code{nocommon} attribute 3110119256Skan@opindex fcommon 3111119256Skan@opindex fno-common 3112119256SkanThe @code{common} attribute requests GCC to place a variable in 3113119256Skan``common'' storage. The @code{nocommon} attribute requests the 3114169689Skanopposite---to allocate space for it directly. 3115119256Skan 3116132718SkanThese attributes override the default chosen by the 3117119256Skan@option{-fno-common} and @option{-fcommon} flags respectively. 3118119256Skan 3119119256Skan@item deprecated 3120119256Skan@cindex @code{deprecated} attribute 3121119256SkanThe @code{deprecated} attribute results in a warning if the variable 3122119256Skanis used anywhere in the source file. This is useful when identifying 3123119256Skanvariables that are expected to be removed in a future version of a 3124119256Skanprogram. The warning also includes the location of the declaration 3125119256Skanof the deprecated variable, to enable users to easily find further 3126119256Skaninformation about why the variable is deprecated, or what they should 3127119256Skando instead. Note that the warning only occurs for uses: 3128119256Skan 3129119256Skan@smallexample 3130119256Skanextern int old_var __attribute__ ((deprecated)); 3131119256Skanextern int old_var; 3132119256Skanint new_fn () @{ return old_var; @} 3133119256Skan@end smallexample 3134119256Skan 3135119256Skanresults in a warning on line 3 but not line 2. 3136119256Skan 3137119256SkanThe @code{deprecated} attribute can also be used for functions and 3138119256Skantypes (@pxref{Function Attributes}, @pxref{Type Attributes}.) 3139119256Skan 314090075Sobrien@item mode (@var{mode}) 314190075Sobrien@cindex @code{mode} attribute 314290075SobrienThis attribute specifies the data type for the declaration---whichever 314390075Sobrientype corresponds to the mode @var{mode}. This in effect lets you 314490075Sobrienrequest an integer or floating point type according to its width. 314590075Sobrien 314690075SobrienYou may also specify a mode of @samp{byte} or @samp{__byte__} to 314790075Sobrienindicate the mode corresponding to a one-byte integer, @samp{word} or 314890075Sobrien@samp{__word__} for the mode of a one-word integer, and @samp{pointer} 314990075Sobrienor @samp{__pointer__} for the mode used to represent pointers. 315090075Sobrien 315190075Sobrien@item packed 315290075Sobrien@cindex @code{packed} attribute 315390075SobrienThe @code{packed} attribute specifies that a variable or structure field 315490075Sobrienshould have the smallest possible alignment---one byte for a variable, 315590075Sobrienand one bit for a field, unless you specify a larger value with the 315690075Sobrien@code{aligned} attribute. 315790075Sobrien 315890075SobrienHere is a structure in which the field @code{x} is packed, so that it 315990075Sobrienimmediately follows @code{a}: 316090075Sobrien 3161132718Skan@smallexample 316290075Sobrienstruct foo 316390075Sobrien@{ 316490075Sobrien char a; 316590075Sobrien int x[2] __attribute__ ((packed)); 316690075Sobrien@}; 3167132718Skan@end smallexample 316890075Sobrien 316990075Sobrien@item section ("@var{section-name}") 317090075Sobrien@cindex @code{section} variable attribute 317190075SobrienNormally, the compiler places the objects it generates in sections like 317290075Sobrien@code{data} and @code{bss}. Sometimes, however, you need additional sections, 317390075Sobrienor you need certain particular variables to appear in special sections, 317490075Sobrienfor example to map to special hardware. The @code{section} 317590075Sobrienattribute specifies that a variable (or function) lives in a particular 317690075Sobriensection. For example, this small program uses several specific section names: 317790075Sobrien 317890075Sobrien@smallexample 317990075Sobrienstruct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; 318090075Sobrienstruct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; 318190075Sobrienchar stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; 318290075Sobrienint init_data __attribute__ ((section ("INITDATA"))) = 0; 318390075Sobrien 318490075Sobrienmain() 318590075Sobrien@{ 3186169689Skan /* @r{Initialize stack pointer} */ 318790075Sobrien init_sp (stack + sizeof (stack)); 318890075Sobrien 3189169689Skan /* @r{Initialize initialized data} */ 319090075Sobrien memcpy (&init_data, &data, &edata - &data); 319190075Sobrien 3192169689Skan /* @r{Turn on the serial ports} */ 319390075Sobrien init_duart (&a); 319490075Sobrien init_duart (&b); 319590075Sobrien@} 319690075Sobrien@end smallexample 319790075Sobrien 319890075Sobrien@noindent 319990075SobrienUse the @code{section} attribute with an @emph{initialized} definition 320090075Sobrienof a @emph{global} variable, as shown in the example. GCC issues 320190075Sobriena warning and otherwise ignores the @code{section} attribute in 320290075Sobrienuninitialized variable declarations. 320390075Sobrien 320490075SobrienYou may only use the @code{section} attribute with a fully initialized 320590075Sobrienglobal definition because of the way linkers work. The linker requires 320690075Sobrieneach object be defined once, with the exception that uninitialized 320790075Sobrienvariables tentatively go in the @code{common} (or @code{bss}) section 320890075Sobrienand can be multiply ``defined''. You can force a variable to be 320990075Sobrieninitialized with the @option{-fno-common} flag or the @code{nocommon} 321090075Sobrienattribute. 321190075Sobrien 321290075SobrienSome file formats do not support arbitrary sections so the @code{section} 321390075Sobrienattribute is not available on all platforms. 321490075SobrienIf you need to map the entire contents of a module to a particular 321590075Sobriensection, consider using the facilities of the linker instead. 321690075Sobrien 321790075Sobrien@item shared 321890075Sobrien@cindex @code{shared} variable attribute 3219132718SkanOn Microsoft Windows, in addition to putting variable definitions in a named 322090075Sobriensection, the section can also be shared among all running copies of an 322190075Sobrienexecutable or DLL@. For example, this small program defines shared data 322290075Sobrienby putting it in a named section @code{shared} and marking the section 322390075Sobrienshareable: 322490075Sobrien 322590075Sobrien@smallexample 322690075Sobrienint foo __attribute__((section ("shared"), shared)) = 0; 322790075Sobrien 322890075Sobrienint 322990075Sobrienmain() 323090075Sobrien@{ 3231169689Skan /* @r{Read and write foo. All running 3232169689Skan copies see the same value.} */ 323390075Sobrien return 0; 323490075Sobrien@} 323590075Sobrien@end smallexample 323690075Sobrien 323790075Sobrien@noindent 323890075SobrienYou may only use the @code{shared} attribute along with @code{section} 323990075Sobrienattribute with a fully initialized global definition because of the way 324090075Sobrienlinkers work. See @code{section} attribute for more information. 324190075Sobrien 3242132718SkanThe @code{shared} attribute is only available on Microsoft Windows@. 324390075Sobrien 3244119256Skan@item tls_model ("@var{tls_model}") 3245119256Skan@cindex @code{tls_model} attribute 3246119256SkanThe @code{tls_model} attribute sets thread-local storage model 3247119256Skan(@pxref{Thread-Local}) of a particular @code{__thread} variable, 3248169689Skanoverriding @option{-ftls-model=} command line switch on a per-variable 3249119256Skanbasis. 3250119256SkanThe @var{tls_model} argument should be one of @code{global-dynamic}, 3251119256Skan@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. 3252119256Skan 3253119256SkanNot all targets support this attribute. 3254119256Skan 325590075Sobrien@item unused 325690075SobrienThis attribute, attached to a variable, means that the variable is meant 325790075Sobriento be possibly unused. GCC will not produce a warning for this 325890075Sobrienvariable. 325990075Sobrien 3260169689Skan@item used 3261169689SkanThis attribute, attached to a variable, means that the variable must be 3262169689Skanemitted even if it appears that the variable is not referenced. 3263169689Skan 326490075Sobrien@item vector_size (@var{bytes}) 326590075SobrienThis attribute specifies the vector size for the variable, measured in 326690075Sobrienbytes. For example, the declaration: 326790075Sobrien 326890075Sobrien@smallexample 326990075Sobrienint foo __attribute__ ((vector_size (16))); 327090075Sobrien@end smallexample 327190075Sobrien 327290075Sobrien@noindent 327390075Sobriencauses the compiler to set the mode for @code{foo}, to be 16 bytes, 327490075Sobriendivided into @code{int} sized units. Assuming a 32-bit int (a vector of 327590075Sobrien4 units of 4 bytes), the corresponding mode of @code{foo} will be V4SI@. 327690075Sobrien 327790075SobrienThis attribute is only applicable to integral and float scalars, 327890075Sobrienalthough arrays, pointers, and function return values are allowed in 327990075Sobrienconjunction with this construct. 328090075Sobrien 328190075SobrienAggregates with this attribute are invalid, even if they are of the same 328290075Sobriensize as a corresponding scalar. For example, the declaration: 328390075Sobrien 328490075Sobrien@smallexample 328590075Sobrienstruct S @{ int a; @}; 328690075Sobrienstruct S __attribute__ ((vector_size (16))) foo; 328790075Sobrien@end smallexample 328890075Sobrien 328990075Sobrien@noindent 329090075Sobrienis invalid even if the size of the structure is the same as the size of 329190075Sobrienthe @code{int}. 329290075Sobrien 3293169689Skan@item selectany 3294169689SkanThe @code{selectany} attribute causes an initialized global variable to 3295169689Skanhave link-once semantics. When multiple definitions of the variable are 3296169689Skanencountered by the linker, the first is selected and the remainder are 3297169689Skandiscarded. Following usage by the Microsoft compiler, the linker is told 3298169689Skan@emph{not} to warn about size or content differences of the multiple 3299169689Skandefinitions. 3300169689Skan 3301169689SkanAlthough the primary usage of this attribute is for POD types, the 3302169689Skanattribute can also be applied to global C++ objects that are initialized 3303169689Skanby a constructor. In this case, the static initialization and destruction 3304169689Skancode for the object is emitted in each translation defining the object, 3305169689Skanbut the calls to the constructor and destructor are protected by a 3306169689Skanlink-once guard variable. 3307169689Skan 3308169689SkanThe @code{selectany} attribute is only available on Microsoft Windows 3309169689Skantargets. You can use @code{__declspec (selectany)} as a synonym for 3310169689Skan@code{__attribute__ ((selectany))} for compatibility with other 3311169689Skancompilers. 3312169689Skan 331390075Sobrien@item weak 331490075SobrienThe @code{weak} attribute is described in @xref{Function Attributes}. 331590075Sobrien 3316132718Skan@item dllimport 3317132718SkanThe @code{dllimport} attribute is described in @xref{Function Attributes}. 3318132718Skan 3319169689Skan@item dllexport 3320132718SkanThe @code{dllexport} attribute is described in @xref{Function Attributes}. 3321132718Skan 3322132718Skan@end table 3323132718Skan 3324132718Skan@subsection M32R/D Variable Attributes 3325132718Skan 3326169689SkanOne attribute is currently defined for the M32R/D@. 3327132718Skan 3328132718Skan@table @code 332990075Sobrien@item model (@var{model-name}) 333090075Sobrien@cindex variable addressability on the M32R/D 333190075SobrienUse this attribute on the M32R/D to set the addressability of an object. 333290075SobrienThe identifier @var{model-name} is one of @code{small}, @code{medium}, 333390075Sobrienor @code{large}, representing each of the code models. 333490075Sobrien 333590075SobrienSmall model objects live in the lower 16MB of memory (so that their 333690075Sobrienaddresses can be loaded with the @code{ld24} instruction). 333790075Sobrien 333890075SobrienMedium and large model objects may live anywhere in the 32-bit address space 333990075Sobrien(the compiler will generate @code{seth/add3} instructions to load their 334090075Sobrienaddresses). 3341132718Skan@end table 334290075Sobrien 3343169689Skan@anchor{i386 Variable Attributes} 3344132718Skan@subsection i386 Variable Attributes 3345119256Skan 3346132718SkanTwo attributes are currently defined for i386 configurations: 3347132718Skan@code{ms_struct} and @code{gcc_struct} 3348119256Skan 3349132718Skan@table @code 3350132718Skan@item ms_struct 3351132718Skan@itemx gcc_struct 3352132718Skan@cindex @code{ms_struct} attribute 3353132718Skan@cindex @code{gcc_struct} attribute 3354132718Skan 3355132718SkanIf @code{packed} is used on a structure, or if bit-fields are used 3356132718Skanit may be that the Microsoft ABI packs them differently 3357132718Skanthan GCC would normally pack them. Particularly when moving packed 3358132718Skandata between functions compiled with GCC and the native Microsoft compiler 3359132718Skan(either via function call or as data in a file), it may be necessary to access 3360132718Skaneither format. 3361132718Skan 3362132718SkanCurrently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 3363132718Skancompilers to match the native Microsoft compiler. 3364169689Skan 3365169689SkanThe Microsoft structure layout algorithm is fairly simple with the exception 3366169689Skanof the bitfield packing: 3367169689Skan 3368169689SkanThe padding and alignment of members of structures and whether a bit field 3369169689Skancan straddle a storage-unit boundary 3370169689Skan 3371169689Skan@enumerate 3372169689Skan@item Structure members are stored sequentially in the order in which they are 3373169689Skandeclared: the first member has the lowest memory address and the last member 3374169689Skanthe highest. 3375169689Skan 3376169689Skan@item Every data object has an alignment-requirement. The alignment-requirement 3377169689Skanfor all data except structures, unions, and arrays is either the size of the 3378169689Skanobject or the current packing size (specified with either the aligned attribute 3379169689Skanor the pack pragma), whichever is less. For structures, unions, and arrays, 3380169689Skanthe alignment-requirement is the largest alignment-requirement of its members. 3381169689SkanEvery object is allocated an offset so that: 3382169689Skan 3383169689Skanoffset % alignment-requirement == 0 3384169689Skan 3385169689Skan@item Adjacent bit fields are packed into the same 1-, 2-, or 4-byte allocation 3386169689Skanunit if the integral types are the same size and if the next bit field fits 3387169689Skaninto the current allocation unit without crossing the boundary imposed by the 3388169689Skancommon alignment requirements of the bit fields. 3389169689Skan@end enumerate 3390169689Skan 3391169689SkanHandling of zero-length bitfields: 3392169689Skan 3393169689SkanMSVC interprets zero-length bitfields in the following ways: 3394169689Skan 3395169689Skan@enumerate 3396169689Skan@item If a zero-length bitfield is inserted between two bitfields that would 3397169689Skannormally be coalesced, the bitfields will not be coalesced. 3398169689Skan 3399169689SkanFor example: 3400169689Skan 3401169689Skan@smallexample 3402169689Skanstruct 3403169689Skan @{ 3404169689Skan unsigned long bf_1 : 12; 3405169689Skan unsigned long : 0; 3406169689Skan unsigned long bf_2 : 12; 3407169689Skan @} t1; 3408169689Skan@end smallexample 3409169689Skan 3410169689SkanThe size of @code{t1} would be 8 bytes with the zero-length bitfield. If the 3411169689Skanzero-length bitfield were removed, @code{t1}'s size would be 4 bytes. 3412169689Skan 3413169689Skan@item If a zero-length bitfield is inserted after a bitfield, @code{foo}, and the 3414169689Skanalignment of the zero-length bitfield is greater than the member that follows it, 3415169689Skan@code{bar}, @code{bar} will be aligned as the type of the zero-length bitfield. 3416169689Skan 3417169689SkanFor example: 3418169689Skan 3419169689Skan@smallexample 3420169689Skanstruct 3421169689Skan @{ 3422169689Skan char foo : 4; 3423169689Skan short : 0; 3424169689Skan char bar; 3425169689Skan @} t2; 3426169689Skan 3427169689Skanstruct 3428169689Skan @{ 3429169689Skan char foo : 4; 3430169689Skan short : 0; 3431169689Skan double bar; 3432169689Skan @} t3; 3433169689Skan@end smallexample 3434169689Skan 3435169689SkanFor @code{t2}, @code{bar} will be placed at offset 2, rather than offset 1. 3436169689SkanAccordingly, the size of @code{t2} will be 4. For @code{t3}, the zero-length 3437169689Skanbitfield will not affect the alignment of @code{bar} or, as a result, the size 3438169689Skanof the structure. 3439169689Skan 3440169689SkanTaking this into account, it is important to note the following: 3441169689Skan 3442169689Skan@enumerate 3443169689Skan@item If a zero-length bitfield follows a normal bitfield, the type of the 3444169689Skanzero-length bitfield may affect the alignment of the structure as whole. For 3445169689Skanexample, @code{t2} has a size of 4 bytes, since the zero-length bitfield follows a 3446169689Skannormal bitfield, and is of type short. 3447169689Skan 3448169689Skan@item Even if a zero-length bitfield is not followed by a normal bitfield, it may 3449169689Skanstill affect the alignment of the structure: 3450169689Skan 3451169689Skan@smallexample 3452169689Skanstruct 3453169689Skan @{ 3454169689Skan char foo : 6; 3455169689Skan long : 0; 3456169689Skan @} t4; 3457169689Skan@end smallexample 3458169689Skan 3459169689SkanHere, @code{t4} will take up 4 bytes. 3460169689Skan@end enumerate 3461169689Skan 3462169689Skan@item Zero-length bitfields following non-bitfield members are ignored: 3463169689Skan 3464169689Skan@smallexample 3465169689Skanstruct 3466169689Skan @{ 3467169689Skan char foo; 3468169689Skan long : 0; 3469169689Skan char bar; 3470169689Skan @} t5; 3471169689Skan@end smallexample 3472169689Skan 3473169689SkanHere, @code{t5} will take up 2 bytes. 3474169689Skan@end enumerate 347590075Sobrien@end table 347690075Sobrien 3477169689Skan@subsection PowerPC Variable Attributes 3478169689Skan 3479169689SkanThree attributes currently are defined for PowerPC configurations: 3480169689Skan@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 3481169689Skan 3482169689SkanFor full documentation of the struct attributes please see the 3483169689Skandocumentation in the @xref{i386 Variable Attributes}, section. 3484169689Skan 3485169689SkanFor documentation of @code{altivec} attribute please see the 3486169689Skandocumentation in the @xref{PowerPC Type Attributes}, section. 3487169689Skan 3488169689Skan@subsection Xstormy16 Variable Attributes 3489169689Skan 3490169689SkanOne attribute is currently defined for xstormy16 configurations: 3491169689Skan@code{below100} 3492169689Skan 3493169689Skan@table @code 3494169689Skan@item below100 3495169689Skan@cindex @code{below100} attribute 3496169689Skan 3497169689SkanIf a variable has the @code{below100} attribute (@code{BELOW100} is 3498169689Skanallowed also), GCC will place the variable in the first 0x100 bytes of 3499169689Skanmemory and use special opcodes to access it. Such variables will be 3500169689Skanplaced in either the @code{.bss_below100} section or the 3501169689Skan@code{.data_below100} section. 3502169689Skan 3503169689Skan@end table 3504169689Skan 350590075Sobrien@node Type Attributes 350690075Sobrien@section Specifying Attributes of Types 350790075Sobrien@cindex attribute of types 350890075Sobrien@cindex type attributes 350990075Sobrien 351090075SobrienThe keyword @code{__attribute__} allows you to specify special 3511169689Skanattributes of @code{struct} and @code{union} types when you define 3512169689Skansuch types. This keyword is followed by an attribute specification 3513169689Skaninside double parentheses. Seven attributes are currently defined for 3514169689Skantypes: @code{aligned}, @code{packed}, @code{transparent_union}, 3515169689Skan@code{unused}, @code{deprecated}, @code{visibility}, and 3516169689Skan@code{may_alias}. Other attributes are defined for functions 3517260918Spfg@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 3518260918Spfg(@pxref{Function Attributes}), variables (@pxref{Variable 3519260918SpfgAttributes}), and labels (@pxref{Label Attributes}). 352090075Sobrien 3521260918Spfg@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 352290075SobrienYou may also specify any one of these attributes with @samp{__} 352390075Sobrienpreceding and following its keyword. This allows you to use these 352490075Sobrienattributes in header files without being concerned about a possible 352590075Sobrienmacro of the same name. For example, you may use @code{__aligned__} 352690075Sobrieninstead of @code{aligned}. 352790075Sobrien 3528169689SkanYou may specify type attributes either in a @code{typedef} declaration 3529169689Skanor in an enum, struct or union type declaration or definition. 353090075Sobrien 3531169689SkanFor an enum, struct or union type, you may specify attributes either 3532169689Skanbetween the enum, struct or union tag and the name of the type, or 3533169689Skanjust past the closing curly brace of the @emph{definition}. The 3534169689Skanformer syntax is preferred. 353590075Sobrien 353690075Sobrien@xref{Attribute Syntax}, for details of the exact syntax for using 353790075Sobrienattributes. 353890075Sobrien 353990075Sobrien@table @code 354090075Sobrien@cindex @code{aligned} attribute 354190075Sobrien@item aligned (@var{alignment}) 354290075SobrienThis attribute specifies a minimum alignment (in bytes) for variables 354390075Sobrienof the specified type. For example, the declarations: 354490075Sobrien 354590075Sobrien@smallexample 354690075Sobrienstruct S @{ short f[3]; @} __attribute__ ((aligned (8))); 354790075Sobrientypedef int more_aligned_int __attribute__ ((aligned (8))); 354890075Sobrien@end smallexample 354990075Sobrien 355090075Sobrien@noindent 355190075Sobrienforce the compiler to insure (as far as it can) that each variable whose 355290075Sobrientype is @code{struct S} or @code{more_aligned_int} will be allocated and 3553117395Skanaligned @emph{at least} on a 8-byte boundary. On a SPARC, having all 355490075Sobrienvariables of type @code{struct S} aligned to 8-byte boundaries allows 355590075Sobrienthe compiler to use the @code{ldd} and @code{std} (doubleword load and 355690075Sobrienstore) instructions when copying one variable of type @code{struct S} to 355790075Sobrienanother, thus improving run-time efficiency. 355890075Sobrien 355990075SobrienNote that the alignment of any given @code{struct} or @code{union} type 356090075Sobrienis required by the ISO C standard to be at least a perfect multiple of 356190075Sobrienthe lowest common multiple of the alignments of all of the members of 356290075Sobrienthe @code{struct} or @code{union} in question. This means that you @emph{can} 356390075Sobrieneffectively adjust the alignment of a @code{struct} or @code{union} 356490075Sobrientype by attaching an @code{aligned} attribute to any one of the members 356590075Sobrienof such a type, but the notation illustrated in the example above is a 356690075Sobrienmore obvious, intuitive, and readable way to request the compiler to 356790075Sobrienadjust the alignment of an entire @code{struct} or @code{union} type. 356890075Sobrien 356990075SobrienAs in the preceding example, you can explicitly specify the alignment 357090075Sobrien(in bytes) that you wish the compiler to use for a given @code{struct} 357190075Sobrienor @code{union} type. Alternatively, you can leave out the alignment factor 357290075Sobrienand just ask the compiler to align a type to the maximum 357390075Sobrienuseful alignment for the target machine you are compiling for. For 357490075Sobrienexample, you could write: 357590075Sobrien 357690075Sobrien@smallexample 357790075Sobrienstruct S @{ short f[3]; @} __attribute__ ((aligned)); 357890075Sobrien@end smallexample 357990075Sobrien 358090075SobrienWhenever you leave out the alignment factor in an @code{aligned} 358190075Sobrienattribute specification, the compiler automatically sets the alignment 358290075Sobrienfor the type to the largest alignment which is ever used for any data 358390075Sobrientype on the target machine you are compiling for. Doing this can often 358490075Sobrienmake copy operations more efficient, because the compiler can use 358590075Sobrienwhatever instructions copy the biggest chunks of memory when performing 358690075Sobriencopies to or from the variables which have types that you have aligned 358790075Sobrienthis way. 358890075Sobrien 358990075SobrienIn the example above, if the size of each @code{short} is 2 bytes, then 359090075Sobrienthe size of the entire @code{struct S} type is 6 bytes. The smallest 359190075Sobrienpower of two which is greater than or equal to that is 8, so the 359290075Sobriencompiler sets the alignment for the entire @code{struct S} type to 8 359390075Sobrienbytes. 359490075Sobrien 359590075SobrienNote that although you can ask the compiler to select a time-efficient 359690075Sobrienalignment for a given type and then declare only individual stand-alone 359790075Sobrienobjects of that type, the compiler's ability to select a time-efficient 359890075Sobrienalignment is primarily useful only when you plan to create arrays of 359990075Sobrienvariables having the relevant (efficiently aligned) type. If you 360090075Sobriendeclare or use arrays of variables of an efficiently-aligned type, then 360190075Sobrienit is likely that your program will also be doing pointer arithmetic (or 360290075Sobriensubscripting, which amounts to the same thing) on pointers to the 360390075Sobrienrelevant type, and the code that the compiler generates for these 360490075Sobrienpointer arithmetic operations will often be more efficient for 360590075Sobrienefficiently-aligned types than for other types. 360690075Sobrien 360790075SobrienThe @code{aligned} attribute can only increase the alignment; but you 360890075Sobriencan decrease it by specifying @code{packed} as well. See below. 360990075Sobrien 361090075SobrienNote that the effectiveness of @code{aligned} attributes may be limited 361190075Sobrienby inherent limitations in your linker. On many systems, the linker is 361290075Sobrienonly able to arrange for variables to be aligned up to a certain maximum 361390075Sobrienalignment. (For some linkers, the maximum supported alignment may 361490075Sobrienbe very very small.) If your linker is only able to align variables 361590075Sobrienup to a maximum of 8 byte alignment, then specifying @code{aligned(16)} 361690075Sobrienin an @code{__attribute__} will still only provide you with 8 byte 361790075Sobrienalignment. See your linker documentation for further information. 361890075Sobrien 361990075Sobrien@item packed 3620132718SkanThis attribute, attached to @code{struct} or @code{union} type 3621169689Skandefinition, specifies that each member (other than zero-width bitfields) 3622169689Skanof the structure or union is placed to minimize the memory required. When 3623169689Skanattached to an @code{enum} definition, it indicates that the smallest 3624169689Skanintegral type should be used. 362590075Sobrien 362690075Sobrien@opindex fshort-enums 362790075SobrienSpecifying this attribute for @code{struct} and @code{union} types is 362890075Sobrienequivalent to specifying the @code{packed} attribute on each of the 362990075Sobrienstructure or union members. Specifying the @option{-fshort-enums} 363090075Sobrienflag on the line is equivalent to specifying the @code{packed} 363190075Sobrienattribute on all @code{enum} definitions. 363290075Sobrien 3633132718SkanIn the following example @code{struct my_packed_struct}'s members are 3634132718Skanpacked closely together, but the internal layout of its @code{s} member 3635169689Skanis not packed---to do that, @code{struct my_unpacked_struct} would need to 3636132718Skanbe packed too. 363790075Sobrien 3638132718Skan@smallexample 3639132718Skanstruct my_unpacked_struct 3640132718Skan @{ 3641132718Skan char c; 3642132718Skan int i; 3643132718Skan @}; 3644132718Skan 3645169689Skanstruct __attribute__ ((__packed__)) my_packed_struct 3646132718Skan @{ 3647132718Skan char c; 3648132718Skan int i; 3649132718Skan struct my_unpacked_struct s; 3650132718Skan @}; 3651132718Skan@end smallexample 3652132718Skan 3653132718SkanYou may only specify this attribute on the definition of a @code{enum}, 3654132718Skan@code{struct} or @code{union}, not on a @code{typedef} which does not 3655132718Skanalso define the enumerated type, structure or union. 3656132718Skan 365790075Sobrien@item transparent_union 365890075SobrienThis attribute, attached to a @code{union} type definition, indicates 365990075Sobrienthat any function parameter having that union type causes calls to that 366090075Sobrienfunction to be treated in a special way. 366190075Sobrien 366290075SobrienFirst, the argument corresponding to a transparent union type can be of 366390075Sobrienany type in the union; no cast is required. Also, if the union contains 366490075Sobriena pointer type, the corresponding argument can be a null pointer 366590075Sobrienconstant or a void pointer expression; and if the union contains a void 366690075Sobrienpointer type, the corresponding argument can be any pointer expression. 366790075SobrienIf the union member type is a pointer, qualifiers like @code{const} on 366890075Sobrienthe referenced type must be respected, just as with normal pointer 366990075Sobrienconversions. 367090075Sobrien 367190075SobrienSecond, the argument is passed to the function using the calling 3672119256Skanconventions of the first member of the transparent union, not the calling 367390075Sobrienconventions of the union itself. All members of the union must have the 367490075Sobriensame machine representation; this is necessary for this argument passing 367590075Sobriento work properly. 367690075Sobrien 367790075SobrienTransparent unions are designed for library functions that have multiple 367890075Sobrieninterfaces for compatibility reasons. For example, suppose the 367990075Sobrien@code{wait} function must accept either a value of type @code{int *} to 368090075Sobriencomply with Posix, or a value of type @code{union wait *} to comply with 368190075Sobrienthe 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, 368290075Sobrien@code{wait} would accept both kinds of arguments, but it would also 368390075Sobrienaccept any other pointer type and this would make argument type checking 368490075Sobrienless useful. Instead, @code{<sys/wait.h>} might define the interface 368590075Sobrienas follows: 368690075Sobrien 368790075Sobrien@smallexample 368890075Sobrientypedef union 368990075Sobrien @{ 369090075Sobrien int *__ip; 369190075Sobrien union wait *__up; 369290075Sobrien @} wait_status_ptr_t __attribute__ ((__transparent_union__)); 369390075Sobrien 369490075Sobrienpid_t wait (wait_status_ptr_t); 369590075Sobrien@end smallexample 369690075Sobrien 369790075SobrienThis interface allows either @code{int *} or @code{union wait *} 369890075Sobrienarguments to be passed, using the @code{int *} calling convention. 369990075SobrienThe program can call @code{wait} with arguments of either type: 370090075Sobrien 3701132718Skan@smallexample 370290075Sobrienint w1 () @{ int w; return wait (&w); @} 370390075Sobrienint w2 () @{ union wait w; return wait (&w); @} 3704132718Skan@end smallexample 370590075Sobrien 370690075SobrienWith this interface, @code{wait}'s implementation might look like this: 370790075Sobrien 3708132718Skan@smallexample 370990075Sobrienpid_t wait (wait_status_ptr_t p) 371090075Sobrien@{ 371190075Sobrien return waitpid (-1, p.__ip, 0); 371290075Sobrien@} 3713132718Skan@end smallexample 371490075Sobrien 371590075Sobrien@item unused 371690075SobrienWhen attached to a type (including a @code{union} or a @code{struct}), 371790075Sobrienthis attribute means that variables of that type are meant to appear 371890075Sobrienpossibly unused. GCC will not produce a warning for any variables of 371990075Sobrienthat type, even if the variable appears to do nothing. This is often 372090075Sobrienthe case with lock or thread classes, which are usually defined and then 372190075Sobriennot referenced, but contain constructors and destructors that have 372290075Sobriennontrivial bookkeeping functions. 372390075Sobrien 372490075Sobrien@item deprecated 372590075SobrienThe @code{deprecated} attribute results in a warning if the type 372690075Sobrienis used anywhere in the source file. This is useful when identifying 372790075Sobrientypes that are expected to be removed in a future version of a program. 372890075SobrienIf possible, the warning also includes the location of the declaration 372990075Sobrienof the deprecated type, to enable users to easily find further 373090075Sobrieninformation about why the type is deprecated, or what they should do 373190075Sobrieninstead. Note that the warnings only occur for uses and then only 373290075Sobrienif the type is being applied to an identifier that itself is not being 373390075Sobriendeclared as deprecated. 373490075Sobrien 373590075Sobrien@smallexample 373690075Sobrientypedef int T1 __attribute__ ((deprecated)); 373790075SobrienT1 x; 373890075Sobrientypedef T1 T2; 373990075SobrienT2 y; 374090075Sobrientypedef T1 T3 __attribute__ ((deprecated)); 374190075SobrienT3 z __attribute__ ((deprecated)); 374290075Sobrien@end smallexample 374390075Sobrien 374490075Sobrienresults in a warning on line 2 and 3 but not lines 4, 5, or 6. No 374590075Sobrienwarning is issued for line 4 because T2 is not explicitly 374690075Sobriendeprecated. Line 5 has no warning because T3 is explicitly 374790075Sobriendeprecated. Similarly for line 6. 374890075Sobrien 374990075SobrienThe @code{deprecated} attribute can also be used for functions and 375090075Sobrienvariables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) 375190075Sobrien 3752117395Skan@item may_alias 3753117395SkanAccesses to objects with types with this attribute are not subjected to 3754117395Skantype-based alias analysis, but are instead assumed to be able to alias 3755117395Skanany other type of objects, just like the @code{char} type. See 3756117395Skan@option{-fstrict-aliasing} for more information on aliasing issues. 3757117395Skan 3758117395SkanExample of use: 3759117395Skan 3760117395Skan@smallexample 3761117395Skantypedef short __attribute__((__may_alias__)) short_a; 3762117395Skan 3763117395Skanint 3764117395Skanmain (void) 3765117395Skan@{ 3766117395Skan int a = 0x12345678; 3767117395Skan short_a *b = (short_a *) &a; 3768117395Skan 3769117395Skan b[1] = 0; 3770117395Skan 3771117395Skan if (a == 0x12345678) 3772117395Skan abort(); 3773117395Skan 3774117395Skan exit(0); 3775117395Skan@} 3776117395Skan@end smallexample 3777117395Skan 3778117395SkanIf you replaced @code{short_a} with @code{short} in the variable 3779117395Skandeclaration, the above program would abort when compiled with 3780117395Skan@option{-fstrict-aliasing}, which is on by default at @option{-O2} or 3781117395Skanabove in recent GCC versions. 3782132718Skan 3783169689Skan@item visibility 3784169689SkanIn C++, attribute visibility (@pxref{Function Attributes}) can also be 3785169689Skanapplied to class, struct, union and enum types. Unlike other type 3786169689Skanattributes, the attribute must appear between the initial keyword and 3787169689Skanthe name of the type; it cannot appear after the body of the type. 3788169689Skan 3789169689SkanNote that the type visibility is applied to vague linkage entities 3790169689Skanassociated with the class (vtable, typeinfo node, etc.). In 3791169689Skanparticular, if a class is thrown as an exception in one shared object 3792169689Skanand caught in another, the class must have default visibility. 3793169689SkanOtherwise the two shared objects will be unable to use the same 3794169689Skantypeinfo node and exception handling will break. 3795169689Skan 3796261188Spfg@c APPLE LOCAL begin weak types 5954418 3797261188Spfg@item weak 3798261188SpfgIn C++, attribute weak can be applied to a class to ensure that all 3799261188Spfgnon-hidden instances of the type are treated as the same type across 3800261188Spfgshared library boundaries on platforms (such as darwin and arm aapcs) 3801261188Spfgthat can emit vtables and the type info meta data as non-comdat 3802261188Spfgsymbols. This is useful when the class has a key method and the 3803261188Spfgtranslation unit that contains the key method is used in more than one 3804261188Spfgshared library or in a shared library and the application. Doing this 3805261188Spfgresults in more expensive startup times. This attribute is inherited 3806261188Spfgby subclasses, so it is only necessary to mark a base type. The 3807261188Spfgtypical use would be to mark any types used for throwing across shared 3808261188Spfglibrary boundaries or those used in dynamic_cast operations across a 3809261188Spfgshared library boundary. 3810261188Spfg@c APPLE LOCAL end weak types 5954418 3811261188Spfg 3812169689Skan@subsection ARM Type Attributes 3813169689Skan 3814169689SkanOn those ARM targets that support @code{dllimport} (such as Symbian 3815169689SkanOS), you can use the @code{notshared} attribute to indicate that the 3816169689Skanvirtual table and other similar data for a class should not be 3817169689Skanexported from a DLL@. For example: 3818169689Skan 3819169689Skan@smallexample 3820169689Skanclass __declspec(notshared) C @{ 3821169689Skanpublic: 3822169689Skan __declspec(dllimport) C(); 3823169689Skan virtual void f(); 3824169689Skan@} 3825169689Skan 3826169689Skan__declspec(dllexport) 3827169689SkanC::C() @{@} 3828169689Skan@end smallexample 3829169689Skan 3830169689SkanIn this code, @code{C::C} is exported from the current DLL, but the 3831169689Skanvirtual table for @code{C} is not exported. (You can use 3832169689Skan@code{__attribute__} instead of @code{__declspec} if you prefer, but 3833169689Skanmost Symbian OS code uses @code{__declspec}.) 3834169689Skan 3835169689Skan@anchor{i386 Type Attributes} 3836132718Skan@subsection i386 Type Attributes 3837132718Skan 3838132718SkanTwo attributes are currently defined for i386 configurations: 3839132718Skan@code{ms_struct} and @code{gcc_struct} 3840132718Skan 3841132718Skan@item ms_struct 3842132718Skan@itemx gcc_struct 3843132718Skan@cindex @code{ms_struct} 3844132718Skan@cindex @code{gcc_struct} 3845132718Skan 3846132718SkanIf @code{packed} is used on a structure, or if bit-fields are used 3847132718Skanit may be that the Microsoft ABI packs them differently 3848132718Skanthan GCC would normally pack them. Particularly when moving packed 3849132718Skandata between functions compiled with GCC and the native Microsoft compiler 3850132718Skan(either via function call or as data in a file), it may be necessary to access 3851132718Skaneither format. 3852132718Skan 3853132718SkanCurrently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 3854132718Skancompilers to match the native Microsoft compiler. 385590075Sobrien@end table 385690075Sobrien 385790075SobrienTo specify multiple attributes, separate them by commas within the 385890075Sobriendouble parentheses: for example, @samp{__attribute__ ((aligned (16), 385990075Sobrienpacked))}. 386090075Sobrien 3861169689Skan@anchor{PowerPC Type Attributes} 3862169689Skan@subsection PowerPC Type Attributes 3863169689Skan 3864169689SkanThree attributes currently are defined for PowerPC configurations: 3865169689Skan@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 3866169689Skan 3867169689SkanFor full documentation of the struct attributes please see the 3868169689Skandocumentation in the @xref{i386 Type Attributes}, section. 3869169689Skan 3870169689SkanThe @code{altivec} attribute allows one to declare AltiVec vector data 3871169689Skantypes supported by the AltiVec Programming Interface Manual. The 3872169689Skanattribute requires an argument to specify one of three vector types: 3873169689Skan@code{vector__}, @code{pixel__} (always followed by unsigned short), 3874169689Skanand @code{bool__} (always followed by unsigned). 3875169689Skan 3876169689Skan@smallexample 3877169689Skan__attribute__((altivec(vector__))) 3878169689Skan__attribute__((altivec(pixel__))) unsigned short 3879169689Skan__attribute__((altivec(bool__))) unsigned 3880169689Skan@end smallexample 3881169689Skan 3882169689SkanThese attributes mainly are intended to support the @code{__vector}, 3883169689Skan@code{__pixel}, and @code{__bool} AltiVec keywords. 3884169689Skan 3885260918Spfg@c APPLE LOCAL begin for-fsf-4_4 3274130 5295549 3886260918Spfg@node Label Attributes 3887260918Spfg@section Specifying Attributes of Labels and Statements 3888260918Spfg@cindex attribute of labels 3889260918Spfg@cindex label attributes 3890260918Spfg@cindex attribute of statements 3891260918Spfg@cindex statement attributes 3892260918Spfg 3893260918SpfgThe keyword @code{__attribute__} allows you to specify special 3894260918Spfgattributes of labels and statements. 3895260918Spfg 3896260918SpfgSome attributes are currently defined generically for variables. 3897260918SpfgOther attributes are defined for variables on particular target 3898260918Spfgsystems. Other attributes are available for functions 3899260918Spfg(@pxref{Function Attributes}), types (@pxref{Type Attributes}) and 3900260918Spfgvariables (@pxref{Variable Attributes}). 3901260918Spfg 3902260918SpfgYou may also specify attributes with @samp{__} preceding and following 3903260918Spfgeach keyword. This allows you to use them in header files without 3904260918Spfgbeing concerned about a possible macro of the same name. For example, 3905260918Spfgyou may use @code{__aligned__} instead of @code{aligned}. 3906260918Spfg 3907260918Spfg@xref{Attribute Syntax}, for details of the exact syntax for using 3908260918Spfgattributes. 3909260918Spfg 3910260918Spfg@table @code 3911260918Spfg@cindex @code{aligned} attribute 3912260918Spfg@item aligned (@var{alignment}) 3913260918SpfgThis attribute specifies a minimum alignment for the label, 3914260918Spfgmeasured in bytes. For example, the declaration: 3915260918Spfg 3916260918Spfg@smallexample 3917260918Spfg some_label: __attribute__((aligned(16))) 3918260918Spfg@end smallexample 3919260918Spfg 3920260918Spfg@noindent 3921260918Spfgrequests the compiler to align the label, inserting @code{nop}s as necessary, 3922260918Spfgto a 16-byte boundary. 3923260918Spfg 3924260918SpfgThe alignment is only a request. The compiler will usually be able to 3925260918Spfghonour it but sometimes the label will be eliminated by the compiler, 3926260918Spfgin which case its alignment will be eliminated too. 3927260918Spfg 3928260918SpfgWhen applied to loops, the @code{aligned} attribute causes the loop to 3929260918Spfgbe aligned. 3930260918Spfg 3931260918Spfg@item unused 3932260918SpfgWhen attached to a label this attribute means that the label might not 3933260918Spfgbe used. GCC will not produce a warning for the label, even if the 3934260918Spfglabel doesn't seem to be referenced. This feature is intended for 3935260918Spfgcode generated by programs which contains labels that may be unused 3936260918Spfgbut which is compiled with @option{-Wall}. It would not normally be 3937260918Spfgappropriate to use in it human-written code, though it could be useful 3938260918Spfgin cases where the code that jumps to the label is contained within an 3939260918Spfg@code{#ifdef} conditional. 3940260918Spfg 3941260918SpfgThis attribute can only be applied to labels, not statements, because 3942260918Spfgthere is no warning if a statement is removed. 3943260918Spfg@end table 3944260918Spfg 3945260918Spfg@c APPLE LOCAL end for-fsf-4_4 3274130 5295549 394690075Sobrien@node Inline 394790075Sobrien@section An Inline Function is As Fast As a Macro 394890075Sobrien@cindex inline functions 394990075Sobrien@cindex integrating function code 395090075Sobrien@cindex open coding 395190075Sobrien@cindex macros, inline alternative 395290075Sobrien 3953189824SdasBy declaring a function inline, you can direct GCC to make 3954189824Sdascalls to that function faster. One way GCC can achieve this is to 395590075Sobrienintegrate that function's code into the code for its callers. This 395690075Sobrienmakes execution faster by eliminating the function-call overhead; in 3957189824Sdasaddition, if any of the actual argument values are constant, their 3958189824Sdasknown values may permit simplifications at compile time so that not 3959189824Sdasall of the inline function's code needs to be included. The effect on 3960189824Sdascode size is less predictable; object code may be larger or smaller 3961189824Sdaswith function inlining, depending on the particular case. You can 3962189824Sdasalso direct GCC to try to integrate all ``simple enough'' functions 3963189824Sdasinto their callers with the option @option{-finline-functions}. 396490075Sobrien 3965189824SdasGCC implements three different semantics of declaring a function 3966189824Sdasinline. One is available with @option{-std=gnu89}, another when 3967189824Sdas@option{-std=c99} or @option{-std=gnu99}, and the third is used when 3968189824Sdascompiling C++. 396990075Sobrien 397090075SobrienTo declare a function inline, use the @code{inline} keyword in its 397190075Sobriendeclaration, like this: 397290075Sobrien 3973132718Skan@smallexample 3974189824Sdasstatic inline int 397590075Sobrieninc (int *a) 397690075Sobrien@{ 397790075Sobrien (*a)++; 397890075Sobrien@} 3979132718Skan@end smallexample 398090075Sobrien 3981189824SdasIf you are writing a header file to be included in ISO C89 programs, write 3982189824Sdas@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. 398390075Sobrien 3984189824SdasThe three types of inlining behave similarly in two important cases: 3985189824Sdaswhen the @code{inline} keyword is used on a @code{static} function, 3986189824Sdaslike the example above, and when a function is first declared without 3987189824Sdasusing the @code{inline} keyword and then is defined with 3988189824Sdas@code{inline}, like this: 398990075Sobrien 3990189824Sdas@smallexample 3991189824Sdasextern int inc (int *a); 3992189824Sdasinline int 3993189824Sdasinc (int *a) 3994189824Sdas@{ 3995189824Sdas (*a)++; 3996189824Sdas@} 3997189824Sdas@end smallexample 399890075Sobrien 3999189824SdasIn both of these common cases, the program behaves the same as if you 4000189824Sdashad not used the @code{inline} keyword, except for its speed. 400190075Sobrien 400290075Sobrien@cindex inline functions, omission of 400390075Sobrien@opindex fkeep-inline-functions 400490075SobrienWhen a function is both inline and @code{static}, if all calls to the 400590075Sobrienfunction are integrated into the caller, and the function's address is 400690075Sobriennever used, then the function's own assembler code is never referenced. 400790075SobrienIn this case, GCC does not actually output assembler code for the 400890075Sobrienfunction, unless you specify the option @option{-fkeep-inline-functions}. 400990075SobrienSome calls cannot be integrated for various reasons (in particular, 401090075Sobriencalls that precede the function's definition cannot be integrated, and 401190075Sobrienneither can recursive calls within the definition). If there is a 401290075Sobriennonintegrated call, then the function is compiled to assembler code as 401390075Sobrienusual. The function must also be compiled as usual if the program 401490075Sobrienrefers to its address, because that can't be inlined. 401590075Sobrien 4016189824Sdas@cindex automatic @code{inline} for C++ member fns 4017189824Sdas@cindex @code{inline} automatic for C++ member fns 4018189824Sdas@cindex member fns, automatically @code{inline} 4019189824Sdas@cindex C++ member fns, automatically @code{inline} 4020189824Sdas@opindex fno-default-inline 4021189824SdasAs required by ISO C++, GCC considers member functions defined within 4022189824Sdasthe body of a class to be marked inline even if they are 4023189824Sdasnot explicitly declared with the @code{inline} keyword. You can 4024189824Sdasoverride this with @option{-fno-default-inline}; @pxref{C++ Dialect 4025189824SdasOptions,,Options Controlling C++ Dialect}. 4026189824Sdas 4027189824SdasGCC does not inline any functions when not optimizing unless you specify 4028189824Sdasthe @samp{always_inline} attribute for the function, like this: 4029189824Sdas 4030189824Sdas@smallexample 4031189824Sdas/* @r{Prototype.} */ 4032189824Sdasinline void foo (const char) __attribute__((always_inline)); 4033189824Sdas@end smallexample 4034189824Sdas 4035189824SdasThe remainder of this section is specific to GNU C89 inlining. 4036189824Sdas 403790075Sobrien@cindex non-static inline function 403890075SobrienWhen an inline function is not @code{static}, then the compiler must assume 403990075Sobrienthat there may be calls from other source files; since a global symbol can 404090075Sobrienbe defined only once in any program, the function must not be defined in 404190075Sobrienthe other source files, so the calls therein cannot be integrated. 404290075SobrienTherefore, a non-@code{static} inline function is always compiled on its 404390075Sobrienown in the usual fashion. 404490075Sobrien 404590075SobrienIf you specify both @code{inline} and @code{extern} in the function 404690075Sobriendefinition, then the definition is used only for inlining. In no case 404790075Sobrienis the function compiled on its own, not even if you refer to its 404890075Sobrienaddress explicitly. Such an address becomes an external reference, as 404990075Sobrienif you had only declared the function, and had not defined it. 405090075Sobrien 405190075SobrienThis combination of @code{inline} and @code{extern} has almost the 405290075Sobrieneffect of a macro. The way to use it is to put a function definition in 405390075Sobriena header file with these keywords, and put another copy of the 405490075Sobriendefinition (lacking @code{inline} and @code{extern}) in a library file. 405590075SobrienThe definition in the header file will cause most calls to the function 405690075Sobriento be inlined. If any uses of the function remain, they will refer to 405790075Sobrienthe single copy in the library. 405890075Sobrien 405990075Sobrien@node Extended Asm 406090075Sobrien@section Assembler Instructions with C Expression Operands 406190075Sobrien@cindex extended @code{asm} 406290075Sobrien@cindex @code{asm} expressions 406390075Sobrien@cindex assembler instructions 406490075Sobrien@cindex registers 406590075Sobrien 406690075SobrienIn an assembler instruction using @code{asm}, you can specify the 406790075Sobrienoperands of the instruction using C expressions. This means you need not 406890075Sobrienguess which registers or memory locations will contain the data you want 406990075Sobriento use. 407090075Sobrien 407190075SobrienYou must specify an assembler instruction template much like what 407290075Sobrienappears in a machine description, plus an operand constraint string for 407390075Sobrieneach operand. 407490075Sobrien 407590075SobrienFor example, here is how to use the 68881's @code{fsinx} instruction: 407690075Sobrien 4077132718Skan@smallexample 407890075Sobrienasm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); 4079132718Skan@end smallexample 408090075Sobrien 408190075Sobrien@noindent 408290075SobrienHere @code{angle} is the C expression for the input operand while 408390075Sobrien@code{result} is that of the output operand. Each has @samp{"f"} as its 408490075Sobrienoperand constraint, saying that a floating point register is required. 408590075SobrienThe @samp{=} in @samp{=f} indicates that the operand is an output; all 408690075Sobrienoutput operands' constraints must use @samp{=}. The constraints use the 408790075Sobriensame language used in the machine description (@pxref{Constraints}). 408890075Sobrien 408990075SobrienEach operand is described by an operand-constraint string followed by 409090075Sobrienthe C expression in parentheses. A colon separates the assembler 409190075Sobrientemplate from the first output operand and another separates the last 409290075Sobrienoutput operand from the first input, if any. Commas separate the 409390075Sobrienoperands within each group. The total number of operands is currently 409490075Sobrienlimited to 30; this limitation may be lifted in some future version of 4095169689SkanGCC@. 409690075Sobrien 409790075SobrienIf there are no output operands but there are input operands, you must 409890075Sobrienplace two consecutive colons surrounding the place where the output 409990075Sobrienoperands would go. 410090075Sobrien 410190075SobrienAs of GCC version 3.1, it is also possible to specify input and output 410290075Sobrienoperands using symbolic names which can be referenced within the 410390075Sobrienassembler code. These names are specified inside square brackets 410490075Sobrienpreceding the constraint string, and can be referenced inside the 410590075Sobrienassembler code using @code{%[@var{name}]} instead of a percentage sign 410690075Sobrienfollowed by the operand number. Using named operands the above example 410790075Sobriencould look like: 410890075Sobrien 4109132718Skan@smallexample 411090075Sobrienasm ("fsinx %[angle],%[output]" 411190075Sobrien : [output] "=f" (result) 411290075Sobrien : [angle] "f" (angle)); 4113132718Skan@end smallexample 411490075Sobrien 411590075Sobrien@noindent 411690075SobrienNote that the symbolic operand names have no relation whatsoever to 411790075Sobrienother C identifiers. You may use any name you like, even those of 4118119256Skanexisting C symbols, but you must ensure that no two operands within the same 411990075Sobrienassembler construct use the same symbolic name. 412090075Sobrien 412190075SobrienOutput operand expressions must be lvalues; the compiler can check this. 412290075SobrienThe input operands need not be lvalues. The compiler cannot check 412390075Sobrienwhether the operands have data types that are reasonable for the 412490075Sobrieninstruction being executed. It does not parse the assembler instruction 412590075Sobrientemplate and does not know what it means or even whether it is valid 412690075Sobrienassembler input. The extended @code{asm} feature is most often used for 412790075Sobrienmachine instructions the compiler itself does not know exist. If 412890075Sobrienthe output expression cannot be directly addressed (for example, it is a 412990075Sobrienbit-field), your constraint must allow a register. In that case, GCC 413090075Sobrienwill use the register as the output of the @code{asm}, and then store 413190075Sobrienthat register into the output. 413290075Sobrien 413390075SobrienThe ordinary output operands must be write-only; GCC will assume that 413490075Sobrienthe values in these operands before the instruction are dead and need 413590075Sobriennot be generated. Extended asm supports input-output or read-write 413690075Sobrienoperands. Use the constraint character @samp{+} to indicate such an 4137132718Skanoperand and list it with the output operands. You should only use 4138132718Skanread-write operands when the constraints for the operand (or the 4139132718Skanoperand in which only some of the bits are to be changed) allow a 4140132718Skanregister. 414190075Sobrien 4142132718SkanYou may, as an alternative, logically split its function into two 4143132718Skanseparate operands, one input operand and one write-only output 4144132718Skanoperand. The connection between them is expressed by constraints 4145132718Skanwhich say they need to be in the same location when the instruction 4146132718Skanexecutes. You can use the same C expression for both operands, or 4147132718Skandifferent expressions. For example, here we write the (fictitious) 4148132718Skan@samp{combine} instruction with @code{bar} as its read-only source 4149132718Skanoperand and @code{foo} as its read-write destination: 415090075Sobrien 4151132718Skan@smallexample 415290075Sobrienasm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); 4153132718Skan@end smallexample 415490075Sobrien 415590075Sobrien@noindent 415690075SobrienThe constraint @samp{"0"} for operand 1 says that it must occupy the 415790075Sobriensame location as operand 0. A number in constraint is allowed only in 415890075Sobrienan input operand and it must refer to an output operand. 415990075Sobrien 416090075SobrienOnly a number in the constraint can guarantee that one operand will be in 416190075Sobrienthe same place as another. The mere fact that @code{foo} is the value 416290075Sobrienof both operands is not enough to guarantee that they will be in the 416390075Sobriensame place in the generated assembler code. The following would not 416490075Sobrienwork reliably: 416590075Sobrien 4166132718Skan@smallexample 416790075Sobrienasm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); 4168132718Skan@end smallexample 416990075Sobrien 417090075SobrienVarious optimizations or reloading could cause operands 0 and 1 to be in 417190075Sobriendifferent registers; GCC knows no reason not to do so. For example, the 417290075Sobriencompiler might find a copy of the value of @code{foo} in one register and 417390075Sobrienuse it for operand 1, but generate the output operand 0 in a different 417490075Sobrienregister (copying it afterward to @code{foo}'s own address). Of course, 417590075Sobriensince the register for operand 1 is not even mentioned in the assembler 417690075Sobriencode, the result will not work, but GCC can't tell that. 417790075Sobrien 417890075SobrienAs of GCC version 3.1, one may write @code{[@var{name}]} instead of 417990075Sobrienthe operand number for a matching constraint. For example: 418090075Sobrien 4181132718Skan@smallexample 418290075Sobrienasm ("cmoveq %1,%2,%[result]" 418390075Sobrien : [result] "=r"(result) 418490075Sobrien : "r" (test), "r"(new), "[result]"(old)); 4185132718Skan@end smallexample 418690075Sobrien 4187169689SkanSometimes you need to make an @code{asm} operand be a specific register, 4188169689Skanbut there's no matching constraint letter for that register @emph{by 4189169689Skanitself}. To force the operand into that register, use a local variable 4190169689Skanfor the operand and specify the register in the variable declaration. 4191169689Skan@xref{Explicit Reg Vars}. Then for the @code{asm} operand, use any 4192169689Skanregister constraint letter that matches the register: 4193169689Skan 4194169689Skan@smallexample 4195169689Skanregister int *p1 asm ("r0") = @dots{}; 4196169689Skanregister int *p2 asm ("r1") = @dots{}; 4197169689Skanregister int *result asm ("r0"); 4198169689Skanasm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 4199169689Skan@end smallexample 4200169689Skan 4201169689Skan@anchor{Example of asm with clobbered asm reg} 4202169689SkanIn the above example, beware that a register that is call-clobbered by 4203169689Skanthe target ABI will be overwritten by any function call in the 4204169689Skanassignment, including library calls for arithmetic operators. 4205169689SkanAssuming it is a call-clobbered register, this may happen to @code{r0} 4206169689Skanabove by the assignment to @code{p2}. If you have to use such a 4207169689Skanregister, use temporary variables for expressions between the register 4208169689Skanassignment and use: 4209169689Skan 4210169689Skan@smallexample 4211169689Skanint t1 = @dots{}; 4212169689Skanregister int *p1 asm ("r0") = @dots{}; 4213169689Skanregister int *p2 asm ("r1") = t1; 4214169689Skanregister int *result asm ("r0"); 4215169689Skanasm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 4216169689Skan@end smallexample 4217169689Skan 421890075SobrienSome instructions clobber specific hard registers. To describe this, 421990075Sobrienwrite a third colon after the input operands, followed by the names of 422090075Sobrienthe clobbered hard registers (given as strings). Here is a realistic 422190075Sobrienexample for the VAX: 422290075Sobrien 4223132718Skan@smallexample 422490075Sobrienasm volatile ("movc3 %0,%1,%2" 4225169689Skan : /* @r{no outputs} */ 422690075Sobrien : "g" (from), "g" (to), "g" (count) 422790075Sobrien : "r0", "r1", "r2", "r3", "r4", "r5"); 4228132718Skan@end smallexample 422990075Sobrien 423090075SobrienYou may not write a clobber description in a way that overlaps with an 423190075Sobrieninput or output operand. For example, you may not have an operand 423290075Sobriendescribing a register class with one member if you mention that register 4233117395Skanin the clobber list. Variables declared to live in specific registers 4234117395Skan(@pxref{Explicit Reg Vars}), and used as asm input or output operands must 4235117395Skanhave no part mentioned in the clobber description. 4236117395SkanThere is no way for you to specify that an input 423790075Sobrienoperand is modified without also specifying it as an output 423890075Sobrienoperand. Note that if all the output operands you specify are for this 423990075Sobrienpurpose (and hence unused), you will then also need to specify 424090075Sobrien@code{volatile} for the @code{asm} construct, as described below, to 424190075Sobrienprevent GCC from deleting the @code{asm} statement as unused. 424290075Sobrien 424390075SobrienIf you refer to a particular hardware register from the assembler code, 424490075Sobrienyou will probably have to list the register after the third colon to 424590075Sobrientell the compiler the register's value is modified. In some assemblers, 424690075Sobrienthe register names begin with @samp{%}; to produce one @samp{%} in the 424790075Sobrienassembler code, you must write @samp{%%} in the input. 424890075Sobrien 424990075SobrienIf your assembler instruction can alter the condition code register, add 425090075Sobrien@samp{cc} to the list of clobbered registers. GCC on some machines 425190075Sobrienrepresents the condition codes as a specific hardware register; 425290075Sobrien@samp{cc} serves to name this register. On other machines, the 425390075Sobriencondition code is handled differently, and specifying @samp{cc} has no 425490075Sobrieneffect. But it is valid no matter what the machine. 425590075Sobrien 4256132718SkanIf your assembler instructions access memory in an unpredictable 425790075Sobrienfashion, add @samp{memory} to the list of clobbered registers. This 4258132718Skanwill cause GCC to not keep memory values cached in registers across the 4259132718Skanassembler instruction and not optimize stores or loads to that memory. 4260132718SkanYou will also want to add the @code{volatile} keyword if the memory 4261132718Skanaffected is not listed in the inputs or outputs of the @code{asm}, as 4262132718Skanthe @samp{memory} clobber does not count as a side-effect of the 4263132718Skan@code{asm}. If you know how large the accessed memory is, you can add 4264132718Skanit as input or output but if this is not known, you should add 4265132718Skan@samp{memory}. As an example, if you access ten bytes of a string, you 4266132718Skancan use a memory input like: 426790075Sobrien 4268169689Skan@smallexample 4269132718Skan@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}. 4270169689Skan@end smallexample 4271132718Skan 4272132718SkanNote that in the following example the memory input is necessary, 4273132718Skanotherwise GCC might optimize the store to @code{x} away: 4274169689Skan@smallexample 4275132718Skanint foo () 4276132718Skan@{ 4277132718Skan int x = 42; 4278132718Skan int *y = &x; 4279132718Skan int result; 4280132718Skan asm ("magic stuff accessing an 'int' pointed to by '%1'" 4281132718Skan "=&d" (r) : "a" (y), "m" (*y)); 4282169689Skan return result; 4283132718Skan@} 4284169689Skan@end smallexample 4285132718Skan 428690075SobrienYou can put multiple assembler instructions together in a single 428790075Sobrien@code{asm} template, separated by the characters normally used in assembly 428890075Sobriencode for the system. A combination that works in most places is a newline 428990075Sobriento break the line, plus a tab character to move to the instruction field 429090075Sobrien(written as @samp{\n\t}). Sometimes semicolons can be used, if the 429190075Sobrienassembler allows semicolons as a line-breaking character. Note that some 429290075Sobrienassembler dialects use semicolons to start a comment. 429390075SobrienThe input operands are guaranteed not to use any of the clobbered 429490075Sobrienregisters, and neither will the output operands' addresses, so you can 429590075Sobrienread and write the clobbered registers as many times as you like. Here 429690075Sobrienis an example of multiple instructions in a template; it assumes the 429790075Sobriensubroutine @code{_foo} accepts arguments in registers 9 and 10: 429890075Sobrien 4299132718Skan@smallexample 430090075Sobrienasm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo" 430190075Sobrien : /* no outputs */ 430290075Sobrien : "g" (from), "g" (to) 430390075Sobrien : "r9", "r10"); 4304132718Skan@end smallexample 430590075Sobrien 430690075SobrienUnless an output operand has the @samp{&} constraint modifier, GCC 430790075Sobrienmay allocate it in the same register as an unrelated input operand, on 430890075Sobrienthe assumption the inputs are consumed before the outputs are produced. 430990075SobrienThis assumption may be false if the assembler code actually consists of 431090075Sobrienmore than one instruction. In such a case, use @samp{&} for each output 431190075Sobrienoperand that may not overlap an input. @xref{Modifiers}. 431290075Sobrien 431390075SobrienIf you want to test the condition code produced by an assembler 431490075Sobrieninstruction, you must include a branch and a label in the @code{asm} 431590075Sobrienconstruct, as follows: 431690075Sobrien 4317132718Skan@smallexample 431890075Sobrienasm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:" 431990075Sobrien : "g" (result) 432090075Sobrien : "g" (input)); 4321132718Skan@end smallexample 432290075Sobrien 432390075Sobrien@noindent 432490075SobrienThis assumes your assembler supports local labels, as the GNU assembler 432590075Sobrienand most Unix assemblers do. 432690075Sobrien 432790075SobrienSpeaking of labels, jumps from one @code{asm} to another are not 432890075Sobriensupported. The compiler's optimizers do not know about these jumps, and 432990075Sobrientherefore they cannot take account of them when deciding how to 433090075Sobrienoptimize. 433190075Sobrien 433290075Sobrien@cindex macros containing @code{asm} 433390075SobrienUsually the most convenient way to use these @code{asm} instructions is to 433490075Sobrienencapsulate them in macros that look like functions. For example, 433590075Sobrien 4336132718Skan@smallexample 433790075Sobrien#define sin(x) \ 433890075Sobrien(@{ double __value, __arg = (x); \ 433990075Sobrien asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ 434090075Sobrien __value; @}) 4341132718Skan@end smallexample 434290075Sobrien 434390075Sobrien@noindent 434490075SobrienHere the variable @code{__arg} is used to make sure that the instruction 434590075Sobrienoperates on a proper @code{double} value, and to accept only those 434690075Sobrienarguments @code{x} which can convert automatically to a @code{double}. 434790075Sobrien 434890075SobrienAnother way to make sure the instruction operates on the correct data 434990075Sobrientype is to use a cast in the @code{asm}. This is different from using a 435090075Sobrienvariable @code{__arg} in that it converts more different types. For 435190075Sobrienexample, if the desired type were @code{int}, casting the argument to 435290075Sobrien@code{int} would accept a pointer with no complaint, while assigning the 435390075Sobrienargument to an @code{int} variable named @code{__arg} would warn about 435490075Sobrienusing a pointer unless the caller explicitly casts it. 435590075Sobrien 435690075SobrienIf an @code{asm} has output operands, GCC assumes for optimization 435790075Sobrienpurposes the instruction has no side effects except to change the output 435890075Sobrienoperands. This does not mean instructions with a side effect cannot be 435990075Sobrienused, but you must be careful, because the compiler may eliminate them 436090075Sobrienif the output operands aren't used, or move them out of loops, or 436190075Sobrienreplace two with one if they constitute a common subexpression. Also, 436290075Sobrienif your instruction does have a side effect on a variable that otherwise 436390075Sobrienappears not to change, the old value of the variable may be reused later 436490075Sobrienif it happens to be found in a register. 436590075Sobrien 4366169689SkanYou can prevent an @code{asm} instruction from being deleted 4367169689Skanby writing the keyword @code{volatile} after 436890075Sobrienthe @code{asm}. For example: 436990075Sobrien 4370132718Skan@smallexample 437190075Sobrien#define get_and_set_priority(new) \ 437290075Sobrien(@{ int __old; \ 437390075Sobrien asm volatile ("get_and_set_priority %0, %1" \ 437490075Sobrien : "=g" (__old) : "g" (new)); \ 437590075Sobrien __old; @}) 4376132718Skan@end smallexample 437790075Sobrien 437890075Sobrien@noindent 437990075SobrienThe @code{volatile} keyword indicates that the instruction has 438090075Sobrienimportant side-effects. GCC will not delete a volatile @code{asm} if 438190075Sobrienit is reachable. (The instruction can still be deleted if GCC can 438290075Sobrienprove that control-flow will never reach the location of the 4383169689Skaninstruction.) Note that even a volatile @code{asm} instruction 4384169689Skancan be moved relative to other code, including across jump 4385169689Skaninstructions. For example, on many targets there is a system 4386169689Skanregister which can be set to control the rounding mode of 4387169689Skanfloating point operations. You might try 4388169689Skansetting it with a volatile @code{asm}, like this PowerPC example: 438990075Sobrien 4390132718Skan@smallexample 4391169689Skan asm volatile("mtfsf 255,%0" : : "f" (fpenv)); 4392169689Skan sum = x + y; 4393132718Skan@end smallexample 439490075Sobrien 439590075Sobrien@noindent 4396169689SkanThis will not work reliably, as the compiler may move the addition back 4397169689Skanbefore the volatile @code{asm}. To make it work you need to add an 4398169689Skanartificial dependency to the @code{asm} referencing a variable in the code 4399169689Skanyou don't want moved, for example: 440090075Sobrien 4401169689Skan@smallexample 4402169689Skan asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv)); 4403169689Skan sum = x + y; 4404169689Skan@end smallexample 440590075Sobrien 4406169689SkanSimilarly, you can't expect a 4407169689Skansequence of volatile @code{asm} instructions to remain perfectly 4408169689Skanconsecutive. If you want consecutive output, use a single @code{asm}. 4409169689SkanAlso, GCC will perform some optimizations across a volatile @code{asm} 4410169689Skaninstruction; GCC does not ``forget everything'' when it encounters 4411169689Skana volatile @code{asm} instruction the way some other compilers do. 441290075Sobrien 4413169689SkanAn @code{asm} instruction without any output operands will be treated 4414169689Skanidentically to a volatile @code{asm} instruction. 4415169689Skan 441690075SobrienIt is a natural idea to look for a way to give access to the condition 441790075Sobriencode left by the assembler instruction. However, when we attempted to 441890075Sobrienimplement this, we found no way to make it work reliably. The problem 441990075Sobrienis that output operands might need reloading, which would result in 442090075Sobrienadditional following ``store'' instructions. On most machines, these 442190075Sobrieninstructions would alter the condition code before there was time to 442290075Sobrientest it. This problem doesn't arise for ordinary ``test'' and 442390075Sobrien``compare'' instructions because they don't have any output operands. 442490075Sobrien 442590075SobrienFor reasons similar to those described above, it is not possible to give 442690075Sobrienan assembler instruction access to the condition code left by previous 442790075Sobrieninstructions. 442890075Sobrien 442990075SobrienIf you are writing a header file that should be includable in ISO C 443090075Sobrienprograms, write @code{__asm__} instead of @code{asm}. @xref{Alternate 443190075SobrienKeywords}. 443290075Sobrien 4433132718Skan@subsection Size of an @code{asm} 4434132718Skan 4435132718SkanSome targets require that GCC track the size of each instruction used in 4436132718Skanorder to generate correct code. Because the final length of an 4437132718Skan@code{asm} is only known by the assembler, GCC must make an estimate as 4438132718Skanto how big it will be. The estimate is formed by counting the number of 4439132718Skanstatements in the pattern of the @code{asm} and multiplying that by the 4440132718Skanlength of the longest instruction on that processor. Statements in the 4441132718Skan@code{asm} are identified by newline characters and whatever statement 4442132718Skanseparator characters are supported by the assembler; on most processors 4443132718Skanthis is the `@code{;}' character. 4444132718Skan 4445132718SkanNormally, GCC's estimate is perfectly adequate to ensure that correct 4446132718Skancode is generated, but it is possible to confuse the compiler if you use 4447132718Skanpseudo instructions or assembler macros that expand into multiple real 4448132718Skaninstructions or if you use assembler directives that expand to more 4449132718Skanspace in the object file than would be needed for a single instruction. 4450132718SkanIf this happens then the assembler will produce a diagnostic saying that 4451132718Skana label is unreachable. 4452132718Skan 445390075Sobrien@subsection i386 floating point asm operands 445490075Sobrien 445590075SobrienThere are several rules on the usage of stack-like regs in 445690075Sobrienasm_operands insns. These rules apply only to the operands that are 445790075Sobrienstack-like regs: 445890075Sobrien 445990075Sobrien@enumerate 446090075Sobrien@item 446190075SobrienGiven a set of input regs that die in an asm_operands, it is 446290075Sobriennecessary to know which are implicitly popped by the asm, and 446390075Sobrienwhich must be explicitly popped by gcc. 446490075Sobrien 446590075SobrienAn input reg that is implicitly popped by the asm must be 446690075Sobrienexplicitly clobbered, unless it is constrained to match an 446790075Sobrienoutput operand. 446890075Sobrien 446990075Sobrien@item 447090075SobrienFor any input reg that is implicitly popped by an asm, it is 447190075Sobriennecessary to know how to adjust the stack to compensate for the pop. 447290075SobrienIf any non-popped input is closer to the top of the reg-stack than 447390075Sobrienthe implicitly popped reg, it would not be possible to know what the 447490075Sobrienstack looked like---it's not clear how the rest of the stack ``slides 447590075Sobrienup''. 447690075Sobrien 447790075SobrienAll implicitly popped input regs must be closer to the top of 447890075Sobrienthe reg-stack than any input that is not implicitly popped. 447990075Sobrien 448090075SobrienIt is possible that if an input dies in an insn, reload might 448190075Sobrienuse the input reg for an output reload. Consider this example: 448290075Sobrien 4483132718Skan@smallexample 448490075Sobrienasm ("foo" : "=t" (a) : "f" (b)); 4485132718Skan@end smallexample 448690075Sobrien 448790075SobrienThis asm says that input B is not popped by the asm, and that 448890075Sobrienthe asm pushes a result onto the reg-stack, i.e., the stack is one 448990075Sobriendeeper after the asm than it was before. But, it is possible that 449090075Sobrienreload will think that it can use the same reg for both the input and 449190075Sobrienthe output, if input B dies in this insn. 449290075Sobrien 449390075SobrienIf any input operand uses the @code{f} constraint, all output reg 449490075Sobrienconstraints must use the @code{&} earlyclobber. 449590075Sobrien 449690075SobrienThe asm above would be written as 449790075Sobrien 4498132718Skan@smallexample 449990075Sobrienasm ("foo" : "=&t" (a) : "f" (b)); 4500132718Skan@end smallexample 450190075Sobrien 450290075Sobrien@item 450390075SobrienSome operands need to be in particular places on the stack. All 450490075Sobrienoutput operands fall in this category---there is no other way to 450590075Sobrienknow which regs the outputs appear in unless the user indicates 450690075Sobrienthis in the constraints. 450790075Sobrien 450890075SobrienOutput operands must specifically indicate which reg an output 450990075Sobrienappears in after an asm. @code{=f} is not allowed: the operand 451090075Sobrienconstraints must select a class with a single reg. 451190075Sobrien 451290075Sobrien@item 451390075SobrienOutput operands may not be ``inserted'' between existing stack regs. 451490075SobrienSince no 387 opcode uses a read/write operand, all output operands 451590075Sobrienare dead before the asm_operands, and are pushed by the asm_operands. 451690075SobrienIt makes no sense to push anywhere but the top of the reg-stack. 451790075Sobrien 451890075SobrienOutput operands must start at the top of the reg-stack: output 451990075Sobrienoperands may not ``skip'' a reg. 452090075Sobrien 452190075Sobrien@item 452290075SobrienSome asm statements may need extra stack space for internal 452390075Sobriencalculations. This can be guaranteed by clobbering stack registers 452490075Sobrienunrelated to the inputs and outputs. 452590075Sobrien 452690075Sobrien@end enumerate 452790075Sobrien 452890075SobrienHere are a couple of reasonable asms to want to write. This asm 452990075Sobrientakes one input, which is internally popped, and produces two outputs. 453090075Sobrien 4531132718Skan@smallexample 453290075Sobrienasm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); 4533132718Skan@end smallexample 453490075Sobrien 453590075SobrienThis asm takes two inputs, which are popped by the @code{fyl2xp1} opcode, 453690075Sobrienand replaces them with one output. The user must code the @code{st(1)} 453790075Sobrienclobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs. 453890075Sobrien 4539132718Skan@smallexample 454090075Sobrienasm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); 4541132718Skan@end smallexample 454290075Sobrien 454390075Sobrien@include md.texi 454490075Sobrien 454590075Sobrien@node Asm Labels 454690075Sobrien@section Controlling Names Used in Assembler Code 454790075Sobrien@cindex assembler names for identifiers 454890075Sobrien@cindex names used in assembler code 454990075Sobrien@cindex identifiers, names in assembler code 455090075Sobrien 455190075SobrienYou can specify the name to be used in the assembler code for a C 455290075Sobrienfunction or variable by writing the @code{asm} (or @code{__asm__}) 455390075Sobrienkeyword after the declarator as follows: 455490075Sobrien 4555132718Skan@smallexample 455690075Sobrienint foo asm ("myfoo") = 2; 4557132718Skan@end smallexample 455890075Sobrien 455990075Sobrien@noindent 456090075SobrienThis specifies that the name to be used for the variable @code{foo} in 456190075Sobrienthe assembler code should be @samp{myfoo} rather than the usual 456290075Sobrien@samp{_foo}. 456390075Sobrien 456490075SobrienOn systems where an underscore is normally prepended to the name of a C 456590075Sobrienfunction or variable, this feature allows you to define names for the 456690075Sobrienlinker that do not start with an underscore. 456790075Sobrien 456890075SobrienIt does not make sense to use this feature with a non-static local 456990075Sobrienvariable since such variables do not have assembler names. If you are 457090075Sobrientrying to put the variable in a particular register, see @ref{Explicit 457190075SobrienReg Vars}. GCC presently accepts such code with a warning, but will 457290075Sobrienprobably be changed to issue an error, rather than a warning, in the 457390075Sobrienfuture. 457490075Sobrien 457590075SobrienYou cannot use @code{asm} in this way in a function @emph{definition}; but 457690075Sobrienyou can get the same effect by writing a declaration for the function 457790075Sobrienbefore its definition and putting @code{asm} there, like this: 457890075Sobrien 4579132718Skan@smallexample 458090075Sobrienextern func () asm ("FUNC"); 458190075Sobrien 458290075Sobrienfunc (x, y) 458390075Sobrien int x, y; 4584117395Skan/* @r{@dots{}} */ 4585132718Skan@end smallexample 458690075Sobrien 458790075SobrienIt is up to you to make sure that the assembler names you choose do not 458890075Sobrienconflict with any other assembler symbols. Also, you must not use a 458990075Sobrienregister name; that would produce completely invalid assembler code. GCC 459090075Sobriendoes not as yet have the ability to store static variables in registers. 459190075SobrienPerhaps that will be added. 459290075Sobrien 459390075Sobrien@node Explicit Reg Vars 459490075Sobrien@section Variables in Specified Registers 459590075Sobrien@cindex explicit register variables 459690075Sobrien@cindex variables in specified registers 459790075Sobrien@cindex specified registers 459890075Sobrien@cindex registers, global allocation 459990075Sobrien 460090075SobrienGNU C allows you to put a few global variables into specified hardware 460190075Sobrienregisters. You can also specify the register in which an ordinary 460290075Sobrienregister variable should be allocated. 460390075Sobrien 460490075Sobrien@itemize @bullet 460590075Sobrien@item 460690075SobrienGlobal register variables reserve registers throughout the program. 460790075SobrienThis may be useful in programs such as programming language 460890075Sobrieninterpreters which have a couple of global variables that are accessed 460990075Sobrienvery often. 461090075Sobrien 461190075Sobrien@item 461290075SobrienLocal register variables in specific registers do not reserve the 4613169689Skanregisters, except at the point where they are used as input or output 4614169689Skanoperands in an @code{asm} statement and the @code{asm} statement itself is 4615169689Skannot deleted. The compiler's data flow analysis is capable of determining 461690075Sobrienwhere the specified registers contain live values, and where they are 461790075Sobrienavailable for other uses. Stores into local register variables may be deleted 461890075Sobrienwhen they appear to be dead according to dataflow analysis. References 461990075Sobriento local register variables may be deleted or moved or simplified. 462090075Sobrien 462190075SobrienThese local variables are sometimes convenient for use with the extended 462290075Sobrien@code{asm} feature (@pxref{Extended Asm}), if you want to write one 462390075Sobrienoutput of the assembler instruction directly into a particular register. 462490075Sobrien(This will work provided the register you specify fits the constraints 462590075Sobrienspecified for that operand in the @code{asm}.) 462690075Sobrien@end itemize 462790075Sobrien 462890075Sobrien@menu 462990075Sobrien* Global Reg Vars:: 463090075Sobrien* Local Reg Vars:: 463190075Sobrien@end menu 463290075Sobrien 463390075Sobrien@node Global Reg Vars 463490075Sobrien@subsection Defining Global Register Variables 463590075Sobrien@cindex global register variables 463690075Sobrien@cindex registers, global variables in 463790075Sobrien 463890075SobrienYou can define a global register variable in GNU C like this: 463990075Sobrien 4640132718Skan@smallexample 464190075Sobrienregister int *foo asm ("a5"); 4642132718Skan@end smallexample 464390075Sobrien 464490075Sobrien@noindent 464590075SobrienHere @code{a5} is the name of the register which should be used. Choose a 464690075Sobrienregister which is normally saved and restored by function calls on your 464790075Sobrienmachine, so that library routines will not clobber it. 464890075Sobrien 464990075SobrienNaturally the register name is cpu-dependent, so you would need to 465090075Sobrienconditionalize your program according to cpu type. The register 465190075Sobrien@code{a5} would be a good choice on a 68000 for a variable of pointer 465290075Sobrientype. On machines with register windows, be sure to choose a ``global'' 465390075Sobrienregister that is not affected magically by the function call mechanism. 465490075Sobrien 465590075SobrienIn addition, operating systems on one type of cpu may differ in how they 465690075Sobrienname the registers; then you would need additional conditionals. For 465790075Sobrienexample, some 68000 operating systems call this register @code{%a5}. 465890075Sobrien 465990075SobrienEventually there may be a way of asking the compiler to choose a register 466090075Sobrienautomatically, but first we need to figure out how it should choose and 466190075Sobrienhow to enable you to guide the choice. No solution is evident. 466290075Sobrien 466390075SobrienDefining a global register variable in a certain register reserves that 466490075Sobrienregister entirely for this use, at least within the current compilation. 466590075SobrienThe register will not be allocated for any other purpose in the functions 466690075Sobrienin the current compilation. The register will not be saved and restored by 466790075Sobrienthese functions. Stores into this register are never deleted even if they 466890075Sobrienwould appear to be dead, but references may be deleted or moved or 466990075Sobriensimplified. 467090075Sobrien 467190075SobrienIt is not safe to access the global register variables from signal 467290075Sobrienhandlers, or from more than one thread of control, because the system 467390075Sobrienlibrary routines may temporarily use the register for other things (unless 467490075Sobrienyou recompile them specially for the task at hand). 467590075Sobrien 467690075Sobrien@cindex @code{qsort}, and global register variables 467790075SobrienIt is not safe for one function that uses a global register variable to 467890075Sobriencall another such function @code{foo} by way of a third function 467990075Sobrien@code{lose} that was compiled without knowledge of this variable (i.e.@: in a 468090075Sobriendifferent source file in which the variable wasn't declared). This is 468190075Sobrienbecause @code{lose} might save the register and put some other value there. 468290075SobrienFor example, you can't expect a global register variable to be available in 468390075Sobrienthe comparison-function that you pass to @code{qsort}, since @code{qsort} 468490075Sobrienmight have put something else in that register. (If you are prepared to 468590075Sobrienrecompile @code{qsort} with the same global register variable, you can 468690075Sobriensolve this problem.) 468790075Sobrien 468890075SobrienIf you want to recompile @code{qsort} or other source files which do not 468990075Sobrienactually use your global register variable, so that they will not use that 469090075Sobrienregister for any other purpose, then it suffices to specify the compiler 469190075Sobrienoption @option{-ffixed-@var{reg}}. You need not actually add a global 469290075Sobrienregister declaration to their source code. 469390075Sobrien 469490075SobrienA function which can alter the value of a global register variable cannot 469590075Sobriensafely be called from a function compiled without this variable, because it 469690075Sobriencould clobber the value the caller expects to find there on return. 469790075SobrienTherefore, the function which is the entry point into the part of the 469890075Sobrienprogram that uses the global register variable must explicitly save and 469990075Sobrienrestore the value which belongs to its caller. 470090075Sobrien 470190075Sobrien@cindex register variable after @code{longjmp} 470290075Sobrien@cindex global register after @code{longjmp} 470390075Sobrien@cindex value after @code{longjmp} 470490075Sobrien@findex longjmp 470590075Sobrien@findex setjmp 470690075SobrienOn most machines, @code{longjmp} will restore to each global register 470790075Sobrienvariable the value it had at the time of the @code{setjmp}. On some 470890075Sobrienmachines, however, @code{longjmp} will not change the value of global 470990075Sobrienregister variables. To be portable, the function that called @code{setjmp} 471090075Sobrienshould make other arrangements to save the values of the global register 471190075Sobrienvariables, and to restore them in a @code{longjmp}. This way, the same 471290075Sobrienthing will happen regardless of what @code{longjmp} does. 471390075Sobrien 471490075SobrienAll global register variable declarations must precede all function 471590075Sobriendefinitions. If such a declaration could appear after function 471690075Sobriendefinitions, the declaration would be too late to prevent the register from 471790075Sobrienbeing used for other purposes in the preceding functions. 471890075Sobrien 471990075SobrienGlobal register variables may not have initial values, because an 472090075Sobrienexecutable file has no means to supply initial contents for a register. 472190075Sobrien 4722117395SkanOn the SPARC, there are reports that g3 @dots{} g7 are suitable 472390075Sobrienregisters, but certain library functions, such as @code{getwd}, as well 472490075Sobrienas the subroutines for division and remainder, modify g3 and g4. g1 and 472590075Sobrieng2 are local temporaries. 472690075Sobrien 472790075SobrienOn the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7. 472890075SobrienOf course, it will not do to use more than a few of those. 472990075Sobrien 473090075Sobrien@node Local Reg Vars 473190075Sobrien@subsection Specifying Registers for Local Variables 473290075Sobrien@cindex local variables, specifying registers 473390075Sobrien@cindex specifying registers for local variables 473490075Sobrien@cindex registers for local variables 473590075Sobrien 473690075SobrienYou can define a local register variable with a specified register 473790075Sobrienlike this: 473890075Sobrien 4739132718Skan@smallexample 474090075Sobrienregister int *foo asm ("a5"); 4741132718Skan@end smallexample 474290075Sobrien 474390075Sobrien@noindent 474490075SobrienHere @code{a5} is the name of the register which should be used. Note 474590075Sobrienthat this is the same syntax used for defining global register 474690075Sobrienvariables, but for a local variable it would appear within a function. 474790075Sobrien 474890075SobrienNaturally the register name is cpu-dependent, but this is not a 474990075Sobrienproblem, since specific registers are most often useful with explicit 475090075Sobrienassembler instructions (@pxref{Extended Asm}). Both of these things 475190075Sobriengenerally require that you conditionalize your program according to 475290075Sobriencpu type. 475390075Sobrien 475490075SobrienIn addition, operating systems on one type of cpu may differ in how they 475590075Sobrienname the registers; then you would need additional conditionals. For 475690075Sobrienexample, some 68000 operating systems call this register @code{%a5}. 475790075Sobrien 475890075SobrienDefining such a register variable does not reserve the register; it 475990075Sobrienremains available for other uses in places where flow control determines 4760169689Skanthe variable's value is not live. 476190075Sobrien 476290075SobrienThis option does not guarantee that GCC will generate code that has 476390075Sobrienthis variable in the register you specify at all times. You may not 4764169689Skancode an explicit reference to this register in the @emph{assembler 4765169689Skaninstruction template} part of an @code{asm} statement and assume it will 4766169689Skanalways refer to this variable. However, using the variable as an 4767169689Skan@code{asm} @emph{operand} guarantees that the specified register is used 4768169689Skanfor the operand. 476990075Sobrien 477090075SobrienStores into local register variables may be deleted when they appear to be dead 477190075Sobrienaccording to dataflow analysis. References to local register variables may 477290075Sobrienbe deleted or moved or simplified. 477390075Sobrien 4774169689SkanAs for global register variables, it's recommended that you choose a 4775169689Skanregister which is normally saved and restored by function calls on 4776169689Skanyour machine, so that library routines will not clobber it. A common 4777169689Skanpitfall is to initialize multiple call-clobbered registers with 4778169689Skanarbitrary expressions, where a function call or library call for an 4779169689Skanarithmetic operator will overwrite a register value from a previous 4780169689Skanassignment, for example @code{r0} below: 4781169689Skan@smallexample 4782169689Skanregister int *p1 asm ("r0") = @dots{}; 4783169689Skanregister int *p2 asm ("r1") = @dots{}; 4784169689Skan@end smallexample 4785169689SkanIn those cases, a solution is to use a temporary variable for 4786169689Skaneach arbitrary expression. @xref{Example of asm with clobbered asm reg}. 4787169689Skan 478890075Sobrien@node Alternate Keywords 478990075Sobrien@section Alternate Keywords 479090075Sobrien@cindex alternate keywords 479190075Sobrien@cindex keywords, alternate 479290075Sobrien 479390075Sobrien@option{-ansi} and the various @option{-std} options disable certain 4794117395Skankeywords. This causes trouble when you want to use GNU C extensions, or 4795117395Skana general-purpose header file that should be usable by all programs, 4796117395Skanincluding ISO C programs. The keywords @code{asm}, @code{typeof} and 4797117395Skan@code{inline} are not available in programs compiled with 4798117395Skan@option{-ansi} or @option{-std} (although @code{inline} can be used in a 4799117395Skanprogram compiled with @option{-std=c99}). The ISO C99 keyword 480090075Sobrien@code{restrict} is only available when @option{-std=gnu99} (which will 480190075Sobrieneventually be the default) or @option{-std=c99} (or the equivalent 480290075Sobrien@option{-std=iso9899:1999}) is used. 480390075Sobrien 480490075SobrienThe way to solve these problems is to put @samp{__} at the beginning and 480590075Sobrienend of each problematical keyword. For example, use @code{__asm__} 4806117395Skaninstead of @code{asm}, and @code{__inline__} instead of @code{inline}. 480790075Sobrien 480890075SobrienOther C compilers won't accept these alternative keywords; if you want to 480990075Sobriencompile with another compiler, you can define the alternate keywords as 481090075Sobrienmacros to replace them with the customary keywords. It looks like this: 481190075Sobrien 4812132718Skan@smallexample 481390075Sobrien#ifndef __GNUC__ 481490075Sobrien#define __asm__ asm 481590075Sobrien#endif 4816132718Skan@end smallexample 481790075Sobrien 481890075Sobrien@findex __extension__ 481990075Sobrien@opindex pedantic 482090075Sobrien@option{-pedantic} and other options cause warnings for many GNU C extensions. 482190075SobrienYou can 482290075Sobrienprevent such warnings within one expression by writing 482390075Sobrien@code{__extension__} before the expression. @code{__extension__} has no 482490075Sobrieneffect aside from this. 482590075Sobrien 482690075Sobrien@node Incomplete Enums 482790075Sobrien@section Incomplete @code{enum} Types 482890075Sobrien 482990075SobrienYou can define an @code{enum} tag without specifying its possible values. 483090075SobrienThis results in an incomplete type, much like what you get if you write 483190075Sobrien@code{struct foo} without describing the elements. A later declaration 483290075Sobrienwhich does specify the possible values completes the type. 483390075Sobrien 483490075SobrienYou can't allocate variables or storage using the type while it is 483590075Sobrienincomplete. However, you can work with pointers to that type. 483690075Sobrien 483790075SobrienThis extension may not be very useful, but it makes the handling of 483890075Sobrien@code{enum} more consistent with the way @code{struct} and @code{union} 483990075Sobrienare handled. 484090075Sobrien 484190075SobrienThis extension is not supported by GNU C++. 484290075Sobrien 484390075Sobrien@node Function Names 484490075Sobrien@section Function Names as Strings 4845132718Skan@cindex @code{__func__} identifier 484690075Sobrien@cindex @code{__FUNCTION__} identifier 484790075Sobrien@cindex @code{__PRETTY_FUNCTION__} identifier 484890075Sobrien 4849132718SkanGCC provides three magic variables which hold the name of the current 4850132718Skanfunction, as a string. The first of these is @code{__func__}, which 4851132718Skanis part of the C99 standard: 485290075Sobrien 4853132718Skan@display 4854132718SkanThe identifier @code{__func__} is implicitly declared by the translator 4855132718Skanas if, immediately following the opening brace of each function 4856132718Skandefinition, the declaration 485790075Sobrien 485890075Sobrien@smallexample 4859132718Skanstatic const char __func__[] = "function-name"; 4860132718Skan@end smallexample 4861132718Skan 4862132718Skanappeared, where function-name is the name of the lexically-enclosing 4863132718Skanfunction. This name is the unadorned name of the function. 4864132718Skan@end display 4865132718Skan 4866132718Skan@code{__FUNCTION__} is another name for @code{__func__}. Older 4867132718Skanversions of GCC recognize only this name. However, it is not 4868132718Skanstandardized. For maximum portability, we recommend you use 4869132718Skan@code{__func__}, but provide a fallback definition with the 4870132718Skanpreprocessor: 4871132718Skan 4872132718Skan@smallexample 4873132718Skan#if __STDC_VERSION__ < 199901L 4874132718Skan# if __GNUC__ >= 2 4875132718Skan# define __func__ __FUNCTION__ 4876132718Skan# else 4877132718Skan# define __func__ "<unknown>" 4878132718Skan# endif 4879132718Skan#endif 4880132718Skan@end smallexample 4881132718Skan 4882132718SkanIn C, @code{__PRETTY_FUNCTION__} is yet another name for 4883132718Skan@code{__func__}. However, in C++, @code{__PRETTY_FUNCTION__} contains 4884132718Skanthe type signature of the function as well as its bare name. For 4885132718Skanexample, this program: 4886132718Skan 4887132718Skan@smallexample 488890075Sobrienextern "C" @{ 488990075Sobrienextern int printf (char *, ...); 489090075Sobrien@} 489190075Sobrien 489290075Sobrienclass a @{ 489390075Sobrien public: 4894132718Skan void sub (int i) 489590075Sobrien @{ 489690075Sobrien printf ("__FUNCTION__ = %s\n", __FUNCTION__); 489790075Sobrien printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); 489890075Sobrien @} 489990075Sobrien@}; 490090075Sobrien 490190075Sobrienint 490290075Sobrienmain (void) 490390075Sobrien@{ 490490075Sobrien a ax; 490590075Sobrien ax.sub (0); 490690075Sobrien return 0; 490790075Sobrien@} 490890075Sobrien@end smallexample 490990075Sobrien 491090075Sobrien@noindent 491190075Sobriengives this output: 491290075Sobrien 491390075Sobrien@smallexample 491490075Sobrien__FUNCTION__ = sub 4915132718Skan__PRETTY_FUNCTION__ = void a::sub(int) 491690075Sobrien@end smallexample 491790075Sobrien 4918132718SkanThese identifiers are not preprocessor macros. In GCC 3.3 and 4919132718Skanearlier, in C only, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} 4920132718Skanwere treated as string literals; they could be used to initialize 4921132718Skan@code{char} arrays, and they could be concatenated with other string 4922132718Skanliterals. GCC 3.4 and later treat them as variables, like 4923132718Skan@code{__func__}. In C++, @code{__FUNCTION__} and 4924132718Skan@code{__PRETTY_FUNCTION__} have always been variables. 492590075Sobrien 492690075Sobrien@node Return Address 492790075Sobrien@section Getting the Return or Frame Address of a Function 492890075Sobrien 492990075SobrienThese functions may be used to get information about the callers of a 493090075Sobrienfunction. 493190075Sobrien 493290075Sobrien@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) 493390075SobrienThis function returns the return address of the current function, or of 493490075Sobrienone of its callers. The @var{level} argument is number of frames to 493590075Sobrienscan up the call stack. A value of @code{0} yields the return address 493690075Sobrienof the current function, a value of @code{1} yields the return address 4937169689Skanof the caller of the current function, and so forth. When inlining 4938117395Skanthe expected behavior is that the function will return the address of 4939117395Skanthe function that will be returned to. To work around this behavior use 4940117395Skanthe @code{noinline} function attribute. 494190075Sobrien 494290075SobrienThe @var{level} argument must be a constant integer. 494390075Sobrien 494490075SobrienOn some machines it may be impossible to determine the return address of 494590075Sobrienany function other than the current one; in such cases, or when the top 494690075Sobrienof the stack has been reached, this function will return @code{0} or a 4947169689Skanrandom value. In addition, @code{__builtin_frame_address} may be used 494890075Sobriento determine if the top of the stack has been reached. 494990075Sobrien 495090075SobrienThis function should only be used with a nonzero argument for debugging 495190075Sobrienpurposes. 495290075Sobrien@end deftypefn 495390075Sobrien 495490075Sobrien@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) 495590075SobrienThis function is similar to @code{__builtin_return_address}, but it 495690075Sobrienreturns the address of the function frame rather than the return address 495790075Sobrienof the function. Calling @code{__builtin_frame_address} with a value of 495890075Sobrien@code{0} yields the frame address of the current function, a value of 495990075Sobrien@code{1} yields the frame address of the caller of the current function, 496090075Sobrienand so forth. 496190075Sobrien 496290075SobrienThe frame is the area on the stack which holds local variables and saved 496390075Sobrienregisters. The frame address is normally the address of the first word 496490075Sobrienpushed on to the stack by the function. However, the exact definition 496590075Sobriendepends upon the processor and the calling convention. If the processor 496690075Sobrienhas a dedicated frame pointer register, and the function has a frame, 496790075Sobrienthen @code{__builtin_frame_address} will return the value of the frame 496890075Sobrienpointer register. 496990075Sobrien 497090075SobrienOn some machines it may be impossible to determine the frame address of 497190075Sobrienany function other than the current one; in such cases, or when the top 497290075Sobrienof the stack has been reached, this function will return @code{0} if 497390075Sobrienthe first frame pointer is properly initialized by the startup code. 497490075Sobrien 497590075SobrienThis function should only be used with a nonzero argument for debugging 497690075Sobrienpurposes. 497790075Sobrien@end deftypefn 497890075Sobrien 497990075Sobrien@node Vector Extensions 498090075Sobrien@section Using vector instructions through built-in functions 498190075Sobrien 498290075SobrienOn some targets, the instruction set contains SIMD vector instructions that 498390075Sobrienoperate on multiple values contained in one large register at the same time. 498490075SobrienFor example, on the i386 the MMX, 3Dnow! and SSE extensions can be used 498590075Sobrienthis way. 498690075Sobrien 498790075SobrienThe first step in using these extensions is to provide the necessary data 498890075Sobrientypes. This should be done using an appropriate @code{typedef}: 498990075Sobrien 4990132718Skan@smallexample 4991169689Skantypedef int v4si __attribute__ ((vector_size (16))); 4992132718Skan@end smallexample 499390075Sobrien 4994169689SkanThe @code{int} type specifies the base type, while the attribute specifies 4995169689Skanthe vector size for the variable, measured in bytes. For example, the 4996169689Skandeclaration above causes the compiler to set the mode for the @code{v4si} 4997169689Skantype to be 16 bytes wide and divided into @code{int} sized units. For 4998169689Skana 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the 4999169689Skancorresponding mode of @code{foo} will be @acronym{V4SI}. 500090075Sobrien 5001169689SkanThe @code{vector_size} attribute is only applicable to integral and 5002169689Skanfloat scalars, although arrays, pointers, and function return values 5003169689Skanare allowed in conjunction with this construct. 500490075Sobrien 5005169689SkanAll the basic integer types can be used as base types, both as signed 5006169689Skanand as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, 5007169689Skan@code{long long}. In addition, @code{float} and @code{double} can be 5008169689Skanused to build floating-point vector types. 5009169689Skan 5010117395SkanSpecifying a combination that is not valid for the current architecture 5011132718Skanwill cause GCC to synthesize the instructions using a narrower mode. 5012117395SkanFor example, if you specify a variable of type @code{V4SI} and your 5013132718Skanarchitecture does not allow for this specific SIMD type, GCC will 5014117395Skanproduce code that uses 4 @code{SIs}. 501590075Sobrien 5016117395SkanThe types defined in this manner can be used with a subset of normal C 5017132718Skanoperations. Currently, GCC will allow using the following operators 5018132718Skanon these types: @code{+, -, *, /, unary minus, ^, |, &, ~}@. 501990075Sobrien 5020117395SkanThe operations behave like C++ @code{valarrays}. Addition is defined as 5021117395Skanthe addition of the corresponding elements of the operands. For 5022117395Skanexample, in the code below, each of the 4 elements in @var{a} will be 5023117395Skanadded to the corresponding 4 elements in @var{b} and the resulting 5024117395Skanvector will be stored in @var{c}. 502590075Sobrien 5026132718Skan@smallexample 5027169689Skantypedef int v4si __attribute__ ((vector_size (16))); 502890075Sobrien 5029117395Skanv4si a, b, c; 503090075Sobrien 5031117395Skanc = a + b; 5032132718Skan@end smallexample 5033117395Skan 5034132718SkanSubtraction, multiplication, division, and the logical operations 5035132718Skanoperate in a similar manner. Likewise, the result of using the unary 5036132718Skanminus or complement operators on a vector type is a vector whose 5037132718Skanelements are the negative or complemented values of the corresponding 5038117395Skanelements in the operand. 5039117395Skan 5040117395SkanYou can declare variables and use them in function calls and returns, as 5041117395Skanwell as in assignments and some casts. You can specify a vector type as 5042117395Skana return type for a function. Vector types can also be used as function 5043117395Skanarguments. It is possible to cast from one vector type to another, 5044117395Skanprovided they are of the same size (in fact, you can also cast vectors 5045117395Skanto and from other datatypes of the same size). 5046117395Skan 5047117395SkanYou cannot operate between vectors of different lengths or different 5048117395Skansignedness without a cast. 5049117395Skan 5050117395SkanA port that supports hardware vector operations, usually provides a set 5051117395Skanof built-in functions that can be used to operate on vectors. For 5052117395Skanexample, a function to add two vectors and multiply the result by a 5053117395Skanthird could look like this: 5054117395Skan 5055132718Skan@smallexample 505690075Sobrienv4si f (v4si a, v4si b, v4si c) 505790075Sobrien@{ 505890075Sobrien v4si tmp = __builtin_addv4si (a, b); 505990075Sobrien return __builtin_mulv4si (tmp, c); 506090075Sobrien@} 506190075Sobrien 5062132718Skan@end smallexample 506390075Sobrien 5064169689Skan@node Offsetof 5065169689Skan@section Offsetof 5066169689Skan@findex __builtin_offsetof 5067169689Skan 5068169689SkanGCC implements for both C and C++ a syntactic extension to implement 5069169689Skanthe @code{offsetof} macro. 5070169689Skan 5071169689Skan@smallexample 5072169689Skanprimary: 5073169689Skan "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" 5074169689Skan 5075169689Skanoffsetof_member_designator: 5076169689Skan @code{identifier} 5077169689Skan | offsetof_member_designator "." @code{identifier} 5078169689Skan | offsetof_member_designator "[" @code{expr} "]" 5079169689Skan@end smallexample 5080169689Skan 5081169689SkanThis extension is sufficient such that 5082169689Skan 5083169689Skan@smallexample 5084169689Skan#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) 5085169689Skan@end smallexample 5086169689Skan 5087169689Skanis a suitable definition of the @code{offsetof} macro. In C++, @var{type} 5088169689Skanmay be dependent. In either case, @var{member} may consist of a single 5089169689Skanidentifier, or a sequence of member accesses and array references. 5090169689Skan 5091169689Skan@node Atomic Builtins 5092169689Skan@section Built-in functions for atomic memory access 5093169689Skan 5094169689SkanThe following builtins are intended to be compatible with those described 5095169689Skanin the @cite{Intel Itanium Processor-specific Application Binary Interface}, 5096169689Skansection 7.4. As such, they depart from the normal GCC practice of using 5097169689Skanthe ``__builtin_'' prefix, and further that they are overloaded such that 5098169689Skanthey work on multiple types. 5099169689Skan 5100169689SkanThe definition given in the Intel documentation allows only for the use of 5101169689Skanthe types @code{int}, @code{long}, @code{long long} as well as their unsigned 5102169689Skancounterparts. GCC will allow any integral scalar or pointer type that is 5103169689Skan1, 2, 4 or 8 bytes in length. 5104169689Skan 5105169689SkanNot all operations are supported by all target processors. If a particular 5106169689Skanoperation cannot be implemented on the target processor, a warning will be 5107169689Skangenerated and a call an external function will be generated. The external 5108169689Skanfunction will carry the same name as the builtin, with an additional suffix 5109169689Skan@samp{_@var{n}} where @var{n} is the size of the data type. 5110169689Skan 5111169689Skan@c ??? Should we have a mechanism to suppress this warning? This is almost 5112169689Skan@c useful for implementing the operation under the control of an external 5113169689Skan@c mutex. 5114169689Skan 5115169689SkanIn most cases, these builtins are considered a @dfn{full barrier}. That is, 5116169689Skanno memory operand will be moved across the operation, either forward or 5117169689Skanbackward. Further, instructions will be issued as necessary to prevent the 5118169689Skanprocessor from speculating loads across the operation and from queuing stores 5119169689Skanafter the operation. 5120169689Skan 5121169689SkanAll of the routines are are described in the Intel documentation to take 5122169689Skan``an optional list of variables protected by the memory barrier''. It's 5123169689Skannot clear what is meant by that; it could mean that @emph{only} the 5124169689Skanfollowing variables are protected, or it could mean that these variables 5125169689Skanshould in addition be protected. At present GCC ignores this list and 5126169689Skanprotects all variables which are globally accessible. If in the future 5127169689Skanwe make some use of this list, an empty list will continue to mean all 5128169689Skanglobally accessible variables. 5129169689Skan 5130169689Skan@table @code 5131169689Skan@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) 5132169689Skan@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) 5133169689Skan@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) 5134169689Skan@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) 5135169689Skan@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) 5136169689Skan@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) 5137169689Skan@findex __sync_fetch_and_add 5138169689Skan@findex __sync_fetch_and_sub 5139169689Skan@findex __sync_fetch_and_or 5140169689Skan@findex __sync_fetch_and_and 5141169689Skan@findex __sync_fetch_and_xor 5142169689Skan@findex __sync_fetch_and_nand 5143169689SkanThese builtins perform the operation suggested by the name, and 5144169689Skanreturns the value that had previously been in memory. That is, 5145169689Skan 5146169689Skan@smallexample 5147169689Skan@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} 5148169689Skan@{ tmp = *ptr; *ptr = ~tmp & value; return tmp; @} // nand 5149169689Skan@end smallexample 5150169689Skan 5151169689Skan@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) 5152169689Skan@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) 5153169689Skan@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) 5154169689Skan@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) 5155169689Skan@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) 5156169689Skan@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) 5157169689Skan@findex __sync_add_and_fetch 5158169689Skan@findex __sync_sub_and_fetch 5159169689Skan@findex __sync_or_and_fetch 5160169689Skan@findex __sync_and_and_fetch 5161169689Skan@findex __sync_xor_and_fetch 5162169689Skan@findex __sync_nand_and_fetch 5163169689SkanThese builtins perform the operation suggested by the name, and 5164169689Skanreturn the new value. That is, 5165169689Skan 5166169689Skan@smallexample 5167169689Skan@{ *ptr @var{op}= value; return *ptr; @} 5168169689Skan@{ *ptr = ~*ptr & value; return *ptr; @} // nand 5169169689Skan@end smallexample 5170169689Skan 5171169689Skan@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...) 5172169689Skan@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...) 5173169689Skan@findex __sync_bool_compare_and_swap 5174169689Skan@findex __sync_val_compare_and_swap 5175169689SkanThese builtins perform an atomic compare and swap. That is, if the current 5176169689Skanvalue of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into 5177169689Skan@code{*@var{ptr}}. 5178169689Skan 5179169689SkanThe ``bool'' version returns true if the comparison is successful and 5180169689Skan@var{newval} was written. The ``val'' version returns the contents 5181169689Skanof @code{*@var{ptr}} before the operation. 5182169689Skan 5183169689Skan@item __sync_synchronize (...) 5184169689Skan@findex __sync_synchronize 5185169689SkanThis builtin issues a full memory barrier. 5186169689Skan 5187169689Skan@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) 5188169689Skan@findex __sync_lock_test_and_set 5189169689SkanThis builtin, as described by Intel, is not a traditional test-and-set 5190169689Skanoperation, but rather an atomic exchange operation. It writes @var{value} 5191169689Skaninto @code{*@var{ptr}}, and returns the previous contents of 5192169689Skan@code{*@var{ptr}}. 5193169689Skan 5194169689SkanMany targets have only minimal support for such locks, and do not support 5195169689Skana full exchange operation. In this case, a target may support reduced 5196169689Skanfunctionality here by which the @emph{only} valid value to store is the 5197169689Skanimmediate constant 1. The exact value actually stored in @code{*@var{ptr}} 5198169689Skanis implementation defined. 5199169689Skan 5200169689SkanThis builtin is not a full barrier, but rather an @dfn{acquire barrier}. 5201169689SkanThis means that references after the builtin cannot move to (or be 5202169689Skanspeculated to) before the builtin, but previous memory stores may not 5203169689Skanbe globally visible yet, and previous memory loads may not yet be 5204169689Skansatisfied. 5205169689Skan 5206169689Skan@item void __sync_lock_release (@var{type} *ptr, ...) 5207169689Skan@findex __sync_lock_release 5208169689SkanThis builtin releases the lock acquired by @code{__sync_lock_test_and_set}. 5209169689SkanNormally this means writing the constant 0 to @code{*@var{ptr}}. 5210169689Skan 5211169689SkanThis builtin is not a full barrier, but rather a @dfn{release barrier}. 5212169689SkanThis means that all previous memory stores are globally visible, and all 5213169689Skanprevious memory loads have been satisfied, but following memory reads 5214169689Skanare not prevented from being speculated to before the barrier. 5215169689Skan@end table 5216169689Skan 5217169689Skan@node Object Size Checking 5218169689Skan@section Object Size Checking Builtins 5219169689Skan@findex __builtin_object_size 5220169689Skan@findex __builtin___memcpy_chk 5221169689Skan@findex __builtin___mempcpy_chk 5222169689Skan@findex __builtin___memmove_chk 5223169689Skan@findex __builtin___memset_chk 5224169689Skan@findex __builtin___strcpy_chk 5225169689Skan@findex __builtin___stpcpy_chk 5226169689Skan@findex __builtin___strncpy_chk 5227169689Skan@findex __builtin___strcat_chk 5228169689Skan@findex __builtin___strncat_chk 5229169689Skan@findex __builtin___sprintf_chk 5230169689Skan@findex __builtin___snprintf_chk 5231169689Skan@findex __builtin___vsprintf_chk 5232169689Skan@findex __builtin___vsnprintf_chk 5233169689Skan@findex __builtin___printf_chk 5234169689Skan@findex __builtin___vprintf_chk 5235169689Skan@findex __builtin___fprintf_chk 5236169689Skan@findex __builtin___vfprintf_chk 5237169689Skan 5238169689SkanGCC implements a limited buffer overflow protection mechanism 5239169689Skanthat can prevent some buffer overflow attacks. 5240169689Skan 5241169689Skan@deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type}) 5242169689Skanis a built-in construct that returns a constant number of bytes from 5243169689Skan@var{ptr} to the end of the object @var{ptr} pointer points to 5244169689Skan(if known at compile time). @code{__builtin_object_size} never evaluates 5245169689Skanits arguments for side-effects. If there are any side-effects in them, it 5246169689Skanreturns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 5247169689Skanfor @var{type} 2 or 3. If there are multiple objects @var{ptr} can 5248169689Skanpoint to and all of them are known at compile time, the returned number 5249169689Skanis the maximum of remaining byte counts in those objects if @var{type} & 2 is 5250169689Skan0 and minimum if nonzero. If it is not possible to determine which objects 5251169689Skan@var{ptr} points to at compile time, @code{__builtin_object_size} should 5252169689Skanreturn @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 5253169689Skanfor @var{type} 2 or 3. 5254169689Skan 5255169689Skan@var{type} is an integer constant from 0 to 3. If the least significant 5256169689Skanbit is clear, objects are whole variables, if it is set, a closest 5257169689Skansurrounding subobject is considered the object a pointer points to. 5258169689SkanThe second bit determines if maximum or minimum of remaining bytes 5259169689Skanis computed. 5260169689Skan 5261169689Skan@smallexample 5262169689Skanstruct V @{ char buf1[10]; int b; char buf2[10]; @} var; 5263169689Skanchar *p = &var.buf1[1], *q = &var.b; 5264169689Skan 5265169689Skan/* Here the object p points to is var. */ 5266169689Skanassert (__builtin_object_size (p, 0) == sizeof (var) - 1); 5267169689Skan/* The subobject p points to is var.buf1. */ 5268169689Skanassert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); 5269169689Skan/* The object q points to is var. */ 5270169689Skanassert (__builtin_object_size (q, 0) 5271169689Skan == (char *) (&var + 1) - (char *) &var.b); 5272169689Skan/* The subobject q points to is var.b. */ 5273169689Skanassert (__builtin_object_size (q, 1) == sizeof (var.b)); 5274169689Skan@end smallexample 5275169689Skan@end deftypefn 5276169689Skan 5277169689SkanThere are built-in functions added for many common string operation 5278169689Skanfunctions, e.g. for @code{memcpy} @code{__builtin___memcpy_chk} 5279169689Skanbuilt-in is provided. This built-in has an additional last argument, 5280169689Skanwhich is the number of bytes remaining in object the @var{dest} 5281169689Skanargument points to or @code{(size_t) -1} if the size is not known. 5282169689Skan 5283169689SkanThe built-in functions are optimized into the normal string functions 5284169689Skanlike @code{memcpy} if the last argument is @code{(size_t) -1} or if 5285169689Skanit is known at compile time that the destination object will not 5286169689Skanbe overflown. If the compiler can determine at compile time the 5287169689Skanobject will be always overflown, it issues a warning. 5288169689Skan 5289169689SkanThe intended use can be e.g. 5290169689Skan 5291169689Skan@smallexample 5292169689Skan#undef memcpy 5293169689Skan#define bos0(dest) __builtin_object_size (dest, 0) 5294169689Skan#define memcpy(dest, src, n) \ 5295169689Skan __builtin___memcpy_chk (dest, src, n, bos0 (dest)) 5296169689Skan 5297169689Skanchar *volatile p; 5298169689Skanchar buf[10]; 5299169689Skan/* It is unknown what object p points to, so this is optimized 5300169689Skan into plain memcpy - no checking is possible. */ 5301169689Skanmemcpy (p, "abcde", n); 5302169689Skan/* Destination is known and length too. It is known at compile 5303169689Skan time there will be no overflow. */ 5304169689Skanmemcpy (&buf[5], "abcde", 5); 5305169689Skan/* Destination is known, but the length is not known at compile time. 5306169689Skan This will result in __memcpy_chk call that can check for overflow 5307169689Skan at runtime. */ 5308169689Skanmemcpy (&buf[5], "abcde", n); 5309169689Skan/* Destination is known and it is known at compile time there will 5310169689Skan be overflow. There will be a warning and __memcpy_chk call that 5311169689Skan will abort the program at runtime. */ 5312169689Skanmemcpy (&buf[6], "abcde", 5); 5313169689Skan@end smallexample 5314169689Skan 5315169689SkanSuch built-in functions are provided for @code{memcpy}, @code{mempcpy}, 5316169689Skan@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, 5317169689Skan@code{strcat} and @code{strncat}. 5318169689Skan 5319169689SkanThere are also checking built-in functions for formatted output functions. 5320169689Skan@smallexample 5321169689Skanint __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); 5322169689Skanint __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, 5323169689Skan const char *fmt, ...); 5324169689Skanint __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, 5325169689Skan va_list ap); 5326169689Skanint __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, 5327169689Skan const char *fmt, va_list ap); 5328169689Skan@end smallexample 5329169689Skan 5330169689SkanThe added @var{flag} argument is passed unchanged to @code{__sprintf_chk} 5331169689Skanetc. functions and can contain implementation specific flags on what 5332169689Skanadditional security measures the checking function might take, such as 5333169689Skanhandling @code{%n} differently. 5334169689Skan 5335169689SkanThe @var{os} argument is the object size @var{s} points to, like in the 5336169689Skanother built-in functions. There is a small difference in the behavior 5337169689Skanthough, if @var{os} is @code{(size_t) -1}, the built-in functions are 5338169689Skanoptimized into the non-checking functions only if @var{flag} is 0, otherwise 5339169689Skanthe checking function is called with @var{os} argument set to 5340169689Skan@code{(size_t) -1}. 5341169689Skan 5342169689SkanIn addition to this, there are checking built-in functions 5343169689Skan@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, 5344169689Skan@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. 5345169689SkanThese have just one additional argument, @var{flag}, right before 5346169689Skanformat string @var{fmt}. If the compiler is able to optimize them to 5347169689Skan@code{fputc} etc. functions, it will, otherwise the checking function 5348169689Skanshould be called and the @var{flag} argument passed to it. 5349169689Skan 535090075Sobrien@node Other Builtins 535190075Sobrien@section Other built-in functions provided by GCC 535290075Sobrien@cindex built-in functions 535390075Sobrien@findex __builtin_isgreater 535490075Sobrien@findex __builtin_isgreaterequal 535590075Sobrien@findex __builtin_isless 535690075Sobrien@findex __builtin_islessequal 535790075Sobrien@findex __builtin_islessgreater 535890075Sobrien@findex __builtin_isunordered 5359169689Skan@findex __builtin_powi 5360169689Skan@findex __builtin_powif 5361169689Skan@findex __builtin_powil 5362132718Skan@findex _Exit 5363132718Skan@findex _exit 536490075Sobrien@findex abort 536590075Sobrien@findex abs 5366132718Skan@findex acos 5367132718Skan@findex acosf 5368132718Skan@findex acosh 5369132718Skan@findex acoshf 5370132718Skan@findex acoshl 5371132718Skan@findex acosl 537290075Sobrien@findex alloca 5373132718Skan@findex asin 5374132718Skan@findex asinf 5375132718Skan@findex asinh 5376132718Skan@findex asinhf 5377132718Skan@findex asinhl 5378132718Skan@findex asinl 5379132718Skan@findex atan 5380132718Skan@findex atan2 5381132718Skan@findex atan2f 5382132718Skan@findex atan2l 5383132718Skan@findex atanf 5384132718Skan@findex atanh 5385132718Skan@findex atanhf 5386132718Skan@findex atanhl 5387132718Skan@findex atanl 538890075Sobrien@findex bcmp 538990075Sobrien@findex bzero 5390132718Skan@findex cabs 5391132718Skan@findex cabsf 5392132718Skan@findex cabsl 5393132718Skan@findex cacos 5394132718Skan@findex cacosf 5395132718Skan@findex cacosh 5396132718Skan@findex cacoshf 5397132718Skan@findex cacoshl 5398132718Skan@findex cacosl 5399132718Skan@findex calloc 5400132718Skan@findex carg 5401132718Skan@findex cargf 5402132718Skan@findex cargl 5403132718Skan@findex casin 5404132718Skan@findex casinf 5405132718Skan@findex casinh 5406132718Skan@findex casinhf 5407132718Skan@findex casinhl 5408132718Skan@findex casinl 5409132718Skan@findex catan 5410132718Skan@findex catanf 5411132718Skan@findex catanh 5412132718Skan@findex catanhf 5413132718Skan@findex catanhl 5414132718Skan@findex catanl 5415132718Skan@findex cbrt 5416132718Skan@findex cbrtf 5417132718Skan@findex cbrtl 5418132718Skan@findex ccos 5419132718Skan@findex ccosf 5420132718Skan@findex ccosh 5421132718Skan@findex ccoshf 5422132718Skan@findex ccoshl 5423132718Skan@findex ccosl 5424132718Skan@findex ceil 5425132718Skan@findex ceilf 5426132718Skan@findex ceill 5427132718Skan@findex cexp 5428132718Skan@findex cexpf 5429132718Skan@findex cexpl 543090075Sobrien@findex cimag 543190075Sobrien@findex cimagf 543290075Sobrien@findex cimagl 5433169689Skan@findex clog 5434169689Skan@findex clogf 5435169689Skan@findex clogl 543690075Sobrien@findex conj 543790075Sobrien@findex conjf 543890075Sobrien@findex conjl 5439132718Skan@findex copysign 5440132718Skan@findex copysignf 5441132718Skan@findex copysignl 544290075Sobrien@findex cos 544390075Sobrien@findex cosf 5444132718Skan@findex cosh 5445132718Skan@findex coshf 5446132718Skan@findex coshl 544790075Sobrien@findex cosl 5448132718Skan@findex cpow 5449132718Skan@findex cpowf 5450132718Skan@findex cpowl 5451132718Skan@findex cproj 5452132718Skan@findex cprojf 5453132718Skan@findex cprojl 545490075Sobrien@findex creal 545590075Sobrien@findex crealf 545690075Sobrien@findex creall 5457132718Skan@findex csin 5458132718Skan@findex csinf 5459132718Skan@findex csinh 5460132718Skan@findex csinhf 5461132718Skan@findex csinhl 5462132718Skan@findex csinl 5463132718Skan@findex csqrt 5464132718Skan@findex csqrtf 5465132718Skan@findex csqrtl 5466132718Skan@findex ctan 5467132718Skan@findex ctanf 5468132718Skan@findex ctanh 5469132718Skan@findex ctanhf 5470132718Skan@findex ctanhl 5471132718Skan@findex ctanl 5472132718Skan@findex dcgettext 5473132718Skan@findex dgettext 5474132718Skan@findex drem 5475132718Skan@findex dremf 5476132718Skan@findex dreml 5477132718Skan@findex erf 5478132718Skan@findex erfc 5479132718Skan@findex erfcf 5480132718Skan@findex erfcl 5481132718Skan@findex erff 5482132718Skan@findex erfl 548390075Sobrien@findex exit 5484117395Skan@findex exp 5485132718Skan@findex exp10 5486132718Skan@findex exp10f 5487132718Skan@findex exp10l 5488132718Skan@findex exp2 5489132718Skan@findex exp2f 5490132718Skan@findex exp2l 5491117395Skan@findex expf 5492117395Skan@findex expl 5493132718Skan@findex expm1 5494132718Skan@findex expm1f 5495132718Skan@findex expm1l 549690075Sobrien@findex fabs 549790075Sobrien@findex fabsf 549890075Sobrien@findex fabsl 5499132718Skan@findex fdim 5500132718Skan@findex fdimf 5501132718Skan@findex fdiml 550290075Sobrien@findex ffs 5503132718Skan@findex floor 5504132718Skan@findex floorf 5505132718Skan@findex floorl 5506132718Skan@findex fma 5507132718Skan@findex fmaf 5508132718Skan@findex fmal 5509132718Skan@findex fmax 5510132718Skan@findex fmaxf 5511132718Skan@findex fmaxl 5512132718Skan@findex fmin 5513132718Skan@findex fminf 5514132718Skan@findex fminl 5515132718Skan@findex fmod 5516132718Skan@findex fmodf 5517132718Skan@findex fmodl 551890075Sobrien@findex fprintf 551990075Sobrien@findex fprintf_unlocked 552090075Sobrien@findex fputs 552190075Sobrien@findex fputs_unlocked 5522132718Skan@findex frexp 5523132718Skan@findex frexpf 5524132718Skan@findex frexpl 5525132718Skan@findex fscanf 5526132718Skan@findex gamma 5527132718Skan@findex gammaf 5528132718Skan@findex gammal 5529132718Skan@findex gettext 5530132718Skan@findex hypot 5531132718Skan@findex hypotf 5532132718Skan@findex hypotl 5533132718Skan@findex ilogb 5534132718Skan@findex ilogbf 5535132718Skan@findex ilogbl 553690075Sobrien@findex imaxabs 553790075Sobrien@findex index 5538169689Skan@findex isalnum 5539169689Skan@findex isalpha 5540169689Skan@findex isascii 5541169689Skan@findex isblank 5542169689Skan@findex iscntrl 5543169689Skan@findex isdigit 5544169689Skan@findex isgraph 5545169689Skan@findex islower 5546169689Skan@findex isprint 5547169689Skan@findex ispunct 5548169689Skan@findex isspace 5549169689Skan@findex isupper 5550169689Skan@findex iswalnum 5551169689Skan@findex iswalpha 5552169689Skan@findex iswblank 5553169689Skan@findex iswcntrl 5554169689Skan@findex iswdigit 5555169689Skan@findex iswgraph 5556169689Skan@findex iswlower 5557169689Skan@findex iswprint 5558169689Skan@findex iswpunct 5559169689Skan@findex iswspace 5560169689Skan@findex iswupper 5561169689Skan@findex iswxdigit 5562169689Skan@findex isxdigit 5563132718Skan@findex j0 5564132718Skan@findex j0f 5565132718Skan@findex j0l 5566132718Skan@findex j1 5567132718Skan@findex j1f 5568132718Skan@findex j1l 5569132718Skan@findex jn 5570132718Skan@findex jnf 5571132718Skan@findex jnl 557290075Sobrien@findex labs 5573132718Skan@findex ldexp 5574132718Skan@findex ldexpf 5575132718Skan@findex ldexpl 5576132718Skan@findex lgamma 5577132718Skan@findex lgammaf 5578132718Skan@findex lgammal 557990075Sobrien@findex llabs 5580132718Skan@findex llrint 5581132718Skan@findex llrintf 5582132718Skan@findex llrintl 5583132718Skan@findex llround 5584132718Skan@findex llroundf 5585132718Skan@findex llroundl 5586117395Skan@findex log 5587132718Skan@findex log10 5588132718Skan@findex log10f 5589132718Skan@findex log10l 5590132718Skan@findex log1p 5591132718Skan@findex log1pf 5592132718Skan@findex log1pl 5593132718Skan@findex log2 5594132718Skan@findex log2f 5595132718Skan@findex log2l 5596132718Skan@findex logb 5597132718Skan@findex logbf 5598132718Skan@findex logbl 5599117395Skan@findex logf 5600117395Skan@findex logl 5601132718Skan@findex lrint 5602132718Skan@findex lrintf 5603132718Skan@findex lrintl 5604132718Skan@findex lround 5605132718Skan@findex lroundf 5606132718Skan@findex lroundl 5607132718Skan@findex malloc 560890075Sobrien@findex memcmp 560990075Sobrien@findex memcpy 5610132718Skan@findex mempcpy 561190075Sobrien@findex memset 5612132718Skan@findex modf 5613132718Skan@findex modff 5614132718Skan@findex modfl 5615132718Skan@findex nearbyint 5616132718Skan@findex nearbyintf 5617132718Skan@findex nearbyintl 5618132718Skan@findex nextafter 5619132718Skan@findex nextafterf 5620132718Skan@findex nextafterl 5621132718Skan@findex nexttoward 5622132718Skan@findex nexttowardf 5623132718Skan@findex nexttowardl 5624132718Skan@findex pow 5625132718Skan@findex pow10 5626132718Skan@findex pow10f 5627132718Skan@findex pow10l 5628132718Skan@findex powf 5629132718Skan@findex powl 563090075Sobrien@findex printf 563190075Sobrien@findex printf_unlocked 5632117395Skan@findex putchar 5633117395Skan@findex puts 5634132718Skan@findex remainder 5635132718Skan@findex remainderf 5636132718Skan@findex remainderl 5637132718Skan@findex remquo 5638132718Skan@findex remquof 5639132718Skan@findex remquol 564090075Sobrien@findex rindex 5641132718Skan@findex rint 5642132718Skan@findex rintf 5643132718Skan@findex rintl 5644132718Skan@findex round 5645132718Skan@findex roundf 5646132718Skan@findex roundl 5647132718Skan@findex scalb 5648132718Skan@findex scalbf 5649132718Skan@findex scalbl 5650132718Skan@findex scalbln 5651132718Skan@findex scalblnf 5652132718Skan@findex scalblnf 5653132718Skan@findex scalbn 5654132718Skan@findex scalbnf 5655132718Skan@findex scanfnl 5656169689Skan@findex signbit 5657169689Skan@findex signbitf 5658169689Skan@findex signbitl 5659132718Skan@findex significand 5660132718Skan@findex significandf 5661132718Skan@findex significandl 566290075Sobrien@findex sin 5663132718Skan@findex sincos 5664132718Skan@findex sincosf 5665132718Skan@findex sincosl 566690075Sobrien@findex sinf 5667132718Skan@findex sinh 5668132718Skan@findex sinhf 5669132718Skan@findex sinhl 567090075Sobrien@findex sinl 5671117395Skan@findex snprintf 5672117395Skan@findex sprintf 567390075Sobrien@findex sqrt 567490075Sobrien@findex sqrtf 567590075Sobrien@findex sqrtl 5676117395Skan@findex sscanf 5677132718Skan@findex stpcpy 5678169689Skan@findex stpncpy 5679169689Skan@findex strcasecmp 568090075Sobrien@findex strcat 568190075Sobrien@findex strchr 568290075Sobrien@findex strcmp 568390075Sobrien@findex strcpy 568490075Sobrien@findex strcspn 5685132718Skan@findex strdup 5686132718Skan@findex strfmon 5687132718Skan@findex strftime 568890075Sobrien@findex strlen 5689169689Skan@findex strncasecmp 569090075Sobrien@findex strncat 569190075Sobrien@findex strncmp 569290075Sobrien@findex strncpy 5693169689Skan@findex strndup 569490075Sobrien@findex strpbrk 569590075Sobrien@findex strrchr 569690075Sobrien@findex strspn 569790075Sobrien@findex strstr 5698132718Skan@findex tan 5699132718Skan@findex tanf 5700132718Skan@findex tanh 5701132718Skan@findex tanhf 5702132718Skan@findex tanhl 5703132718Skan@findex tanl 5704132718Skan@findex tgamma 5705132718Skan@findex tgammaf 5706132718Skan@findex tgammal 5707169689Skan@findex toascii 5708169689Skan@findex tolower 5709169689Skan@findex toupper 5710169689Skan@findex towlower 5711169689Skan@findex towupper 5712132718Skan@findex trunc 5713132718Skan@findex truncf 5714132718Skan@findex truncl 5715132718Skan@findex vfprintf 5716132718Skan@findex vfscanf 5717117395Skan@findex vprintf 5718117395Skan@findex vscanf 5719117395Skan@findex vsnprintf 5720117395Skan@findex vsprintf 5721117395Skan@findex vsscanf 5722132718Skan@findex y0 5723132718Skan@findex y0f 5724132718Skan@findex y0l 5725132718Skan@findex y1 5726132718Skan@findex y1f 5727132718Skan@findex y1l 5728132718Skan@findex yn 5729132718Skan@findex ynf 5730132718Skan@findex ynl 573190075Sobrien 573290075SobrienGCC provides a large number of built-in functions other than the ones 573390075Sobrienmentioned above. Some of these are for internal use in the processing 573490075Sobrienof exceptions or variable-length argument lists and will not be 573590075Sobriendocumented here because they may change from time to time; we do not 573690075Sobrienrecommend general use of these functions. 573790075Sobrien 573890075SobrienThe remaining functions are provided for optimization purposes. 573990075Sobrien 574090075Sobrien@opindex fno-builtin 574190075SobrienGCC includes built-in versions of many of the functions in the standard 574290075SobrienC library. The versions prefixed with @code{__builtin_} will always be 574390075Sobrientreated as having the same meaning as the C library function even if you 5744169689Skanspecify the @option{-fno-builtin} option. (@pxref{C Dialect Options}) 574590075SobrienMany of these functions are only optimized in certain cases; if they are 574690075Sobriennot optimized in a particular case, a call to the library function will 574790075Sobrienbe emitted. 574890075Sobrien 574990075Sobrien@opindex ansi 575090075Sobrien@opindex std 5751132718SkanOutside strict ISO C mode (@option{-ansi}, @option{-std=c89} or 5752132718Skan@option{-std=c99}), the functions 5753132718Skan@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, 5754132718Skan@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, 5755132718Skan@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, 5756132718Skan@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, @code{fputs_unlocked}, 5757132718Skan@code{gammaf}, @code{gammal}, @code{gamma}, @code{gettext}, 5758169689Skan@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, 5759169689Skan@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, 5760169689Skan@code{mempcpy}, @code{pow10f}, @code{pow10l}, @code{pow10}, 5761169689Skan@code{printf_unlocked}, @code{rindex}, @code{scalbf}, @code{scalbl}, 5762169689Skan@code{scalb}, @code{signbit}, @code{signbitf}, @code{signbitl}, 5763132718Skan@code{significandf}, @code{significandl}, @code{significand}, 5764132718Skan@code{sincosf}, @code{sincosl}, @code{sincos}, @code{stpcpy}, 5765169689Skan@code{stpncpy}, @code{strcasecmp}, @code{strdup}, @code{strfmon}, 5766169689Skan@code{strncasecmp}, @code{strndup}, @code{toascii}, @code{y0f}, 5767169689Skan@code{y0l}, @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, 5768169689Skan@code{ynl} and @code{yn} 5769132718Skanmay be handled as built-in functions. 5770132718SkanAll these functions have corresponding versions 577190075Sobrienprefixed with @code{__builtin_}, which may be used even in strict C89 577290075Sobrienmode. 577390075Sobrien 5774132718SkanThe ISO C99 functions 5775132718Skan@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, 5776132718Skan@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, 5777132718Skan@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, 5778132718Skan@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, 5779132718Skan@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, 5780132718Skan@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, 5781132718Skan@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, 5782132718Skan@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, 5783132718Skan@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, 5784132718Skan@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, 5785169689Skan@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, 5786169689Skan@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, 5787169689Skan@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, 5788169689Skan@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, 5789169689Skan@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, 5790169689Skan@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, 5791169689Skan@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, 5792169689Skan@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, 5793169689Skan@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, 5794169689Skan@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, 5795169689Skan@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, 5796169689Skan@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, 5797169689Skan@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, 5798169689Skan@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, 5799169689Skan@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, 5800169689Skan@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, 5801169689Skan@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, 5802169689Skan@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, 5803169689Skan@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, 5804169689Skan@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, 5805169689Skan@code{nextafterf}, @code{nextafterl}, @code{nextafter}, 5806169689Skan@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, 5807169689Skan@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, 5808169689Skan@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, 5809169689Skan@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, 5810169689Skan@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, 5811169689Skan@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, 5812169689Skan@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, 5813169689Skan@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} 5814132718Skanare handled as built-in functions 5815132718Skanexcept in strict ISO C90 mode (@option{-ansi} or @option{-std=c89}). 581690075Sobrien 5817132718SkanThere are also built-in versions of the ISO C99 functions 5818132718Skan@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, 5819132718Skan@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, 5820132718Skan@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, 5821132718Skan@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, 5822132718Skan@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, 5823132718Skan@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, 5824132718Skan@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, 5825132718Skan@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, 5826132718Skan@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} 5827132718Skanthat are recognized in any mode since ISO C90 reserves these names for 5828132718Skanthe purpose to which ISO C99 puts them. All these functions have 5829132718Skancorresponding versions prefixed with @code{__builtin_}. 583090075Sobrien 5831169689SkanThe ISO C94 functions 5832169689Skan@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, 5833169689Skan@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, 5834169689Skan@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and 5835169689Skan@code{towupper} 5836169689Skanare handled as built-in functions 5837169689Skanexcept in strict ISO C90 mode (@option{-ansi} or @option{-std=c89}). 5838169689Skan 5839132718SkanThe ISO C90 functions 5840132718Skan@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, 5841132718Skan@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, 5842132718Skan@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, 5843169689Skan@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf}, 5844169689Skan@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, 5845169689Skan@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, 5846169689Skan@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, 5847169689Skan@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, 5848169689Skan@code{malloc}, @code{memcmp}, @code{memcpy}, @code{memset}, @code{modf}, 5849169689Skan@code{pow}, @code{printf}, @code{putchar}, @code{puts}, @code{scanf}, 5850169689Skan@code{sinh}, @code{sin}, @code{snprintf}, @code{sprintf}, @code{sqrt}, 5851169689Skan@code{sscanf}, @code{strcat}, @code{strchr}, @code{strcmp}, 5852169689Skan@code{strcpy}, @code{strcspn}, @code{strlen}, @code{strncat}, 5853169689Skan@code{strncmp}, @code{strncpy}, @code{strpbrk}, @code{strrchr}, 5854169689Skan@code{strspn}, @code{strstr}, @code{tanh}, @code{tan}, @code{vfprintf}, 5855169689Skan@code{vprintf} and @code{vsprintf} 5856132718Skanare all recognized as built-in functions unless 5857132718Skan@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} 5858132718Skanis specified for an individual function). All of these functions have 5859132718Skancorresponding versions prefixed with @code{__builtin_}. 5860132718Skan 586190075SobrienGCC provides built-in versions of the ISO C99 floating point comparison 586290075Sobrienmacros that avoid raising exceptions for unordered operands. They have 586390075Sobrienthe same names as the standard macros ( @code{isgreater}, 586490075Sobrien@code{isgreaterequal}, @code{isless}, @code{islessequal}, 586590075Sobrien@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} 586690075Sobrienprefixed. We intend for a library implementor to be able to simply 586790075Sobrien@code{#define} each standard macro to its built-in equivalent. 586890075Sobrien 586990075Sobrien@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) 587090075Sobrien 587190075SobrienYou can use the built-in function @code{__builtin_types_compatible_p} to 587290075Sobriendetermine whether two types are the same. 587390075Sobrien 587490075SobrienThis built-in function returns 1 if the unqualified versions of the 587590075Sobrientypes @var{type1} and @var{type2} (which are types, not expressions) are 587690075Sobriencompatible, 0 otherwise. The result of this built-in function can be 587790075Sobrienused in integer constant expressions. 587890075Sobrien 587990075SobrienThis built-in function ignores top level qualifiers (e.g., @code{const}, 588090075Sobrien@code{volatile}). For example, @code{int} is equivalent to @code{const 588190075Sobrienint}. 588290075Sobrien 588390075SobrienThe type @code{int[]} and @code{int[5]} are compatible. On the other 588490075Sobrienhand, @code{int} and @code{char *} are not compatible, even if the size 588590075Sobrienof their types, on the particular architecture are the same. Also, the 588690075Sobrienamount of pointer indirection is taken into account when determining 588790075Sobriensimilarity. Consequently, @code{short *} is not similar to 588890075Sobrien@code{short **}. Furthermore, two types that are typedefed are 588990075Sobrienconsidered compatible if their underlying types are compatible. 589090075Sobrien 5891132718SkanAn @code{enum} type is not considered to be compatible with another 5892132718Skan@code{enum} type even if both are compatible with the same integer 5893132718Skantype; this is what the C standard specifies. 5894132718SkanFor example, @code{enum @{foo, bar@}} is not similar to 589590075Sobrien@code{enum @{hot, dog@}}. 589690075Sobrien 589790075SobrienYou would typically use this function in code whose execution varies 589890075Sobriendepending on the arguments' types. For example: 589990075Sobrien 590090075Sobrien@smallexample 590196263Sobrien#define foo(x) \ 590296263Sobrien (@{ \ 5903169689Skan typeof (x) tmp = (x); \ 590496263Sobrien if (__builtin_types_compatible_p (typeof (x), long double)) \ 590596263Sobrien tmp = foo_long_double (tmp); \ 590696263Sobrien else if (__builtin_types_compatible_p (typeof (x), double)) \ 590796263Sobrien tmp = foo_double (tmp); \ 590896263Sobrien else if (__builtin_types_compatible_p (typeof (x), float)) \ 590996263Sobrien tmp = foo_float (tmp); \ 591096263Sobrien else \ 591196263Sobrien abort (); \ 591296263Sobrien tmp; \ 591390075Sobrien @}) 591490075Sobrien@end smallexample 591590075Sobrien 5916169689Skan@emph{Note:} This construct is only available for C@. 591790075Sobrien 591890075Sobrien@end deftypefn 591990075Sobrien 592090075Sobrien@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) 592190075Sobrien 592290075SobrienYou can use the built-in function @code{__builtin_choose_expr} to 592390075Sobrienevaluate code depending on the value of a constant expression. This 592490075Sobrienbuilt-in function returns @var{exp1} if @var{const_exp}, which is a 592590075Sobrienconstant expression that must be able to be determined at compile time, 592690075Sobrienis nonzero. Otherwise it returns 0. 592790075Sobrien 592890075SobrienThis built-in function is analogous to the @samp{? :} operator in C, 592990075Sobrienexcept that the expression returned has its type unaltered by promotion 593090075Sobrienrules. Also, the built-in function does not evaluate the expression 593190075Sobrienthat was not chosen. For example, if @var{const_exp} evaluates to true, 593290075Sobrien@var{exp2} is not evaluated even if it has side-effects. 593390075Sobrien 593490075SobrienThis built-in function can return an lvalue if the chosen argument is an 593590075Sobrienlvalue. 593690075Sobrien 593790075SobrienIf @var{exp1} is returned, the return type is the same as @var{exp1}'s 593890075Sobrientype. Similarly, if @var{exp2} is returned, its return type is the same 593990075Sobrienas @var{exp2}. 594090075Sobrien 594190075SobrienExample: 594290075Sobrien 594390075Sobrien@smallexample 5944117395Skan#define foo(x) \ 5945117395Skan __builtin_choose_expr ( \ 5946117395Skan __builtin_types_compatible_p (typeof (x), double), \ 5947117395Skan foo_double (x), \ 5948117395Skan __builtin_choose_expr ( \ 5949117395Skan __builtin_types_compatible_p (typeof (x), float), \ 5950117395Skan foo_float (x), \ 5951117395Skan /* @r{The void expression results in a compile-time error} \ 5952117395Skan @r{when assigning the result to something.} */ \ 595390075Sobrien (void)0)) 595490075Sobrien@end smallexample 595590075Sobrien 5956169689Skan@emph{Note:} This construct is only available for C@. Furthermore, the 595790075Sobrienunused expression (@var{exp1} or @var{exp2} depending on the value of 595890075Sobrien@var{const_exp}) may still generate syntax errors. This may change in 595990075Sobrienfuture revisions. 596090075Sobrien 596190075Sobrien@end deftypefn 596290075Sobrien 596390075Sobrien@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) 596490075SobrienYou can use the built-in function @code{__builtin_constant_p} to 596590075Sobriendetermine if a value is known to be constant at compile-time and hence 596690075Sobrienthat GCC can perform constant-folding on expressions involving that 596790075Sobrienvalue. The argument of the function is the value to test. The function 596890075Sobrienreturns the integer 1 if the argument is known to be a compile-time 596990075Sobrienconstant and 0 if it is not known to be a compile-time constant. A 597090075Sobrienreturn of 0 does not indicate that the value is @emph{not} a constant, 597190075Sobrienbut merely that GCC cannot prove it is a constant with the specified 597290075Sobrienvalue of the @option{-O} option. 597390075Sobrien 597490075SobrienYou would typically use this function in an embedded application where 597590075Sobrienmemory was a critical resource. If you have some complex calculation, 597690075Sobrienyou may want it to be folded if it involves constants, but need to call 597790075Sobriena function if it does not. For example: 597890075Sobrien 597990075Sobrien@smallexample 598090075Sobrien#define Scale_Value(X) \ 598190075Sobrien (__builtin_constant_p (X) \ 598290075Sobrien ? ((X) * SCALE + OFFSET) : Scale (X)) 598390075Sobrien@end smallexample 598490075Sobrien 598590075SobrienYou may use this built-in function in either a macro or an inline 598690075Sobrienfunction. However, if you use it in an inlined function and pass an 598790075Sobrienargument of the function as the argument to the built-in, GCC will 598890075Sobriennever return 1 when you call the inline function with a string constant 598990075Sobrienor compound literal (@pxref{Compound Literals}) and will not return 1 599090075Sobrienwhen you pass a constant numeric value to the inline function unless you 599190075Sobrienspecify the @option{-O} option. 599290075Sobrien 599390075SobrienYou may also use @code{__builtin_constant_p} in initializers for static 599490075Sobriendata. For instance, you can write 599590075Sobrien 599690075Sobrien@smallexample 599790075Sobrienstatic const int table[] = @{ 599890075Sobrien __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, 5999117395Skan /* @r{@dots{}} */ 600090075Sobrien@}; 600190075Sobrien@end smallexample 600290075Sobrien 600390075Sobrien@noindent 600490075SobrienThis is an acceptable initializer even if @var{EXPRESSION} is not a 600590075Sobrienconstant expression. GCC must be more conservative about evaluating the 600690075Sobrienbuilt-in in this case, because it has no opportunity to perform 600790075Sobrienoptimization. 600890075Sobrien 600990075SobrienPrevious versions of GCC did not accept this built-in in data 601090075Sobrieninitializers. The earliest version where it is completely safe is 601190075Sobrien3.0.1. 601290075Sobrien@end deftypefn 601390075Sobrien 601490075Sobrien@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) 601590075Sobrien@opindex fprofile-arcs 601690075SobrienYou may use @code{__builtin_expect} to provide the compiler with 601790075Sobrienbranch prediction information. In general, you should prefer to 601890075Sobrienuse actual profile feedback for this (@option{-fprofile-arcs}), as 601990075Sobrienprogrammers are notoriously bad at predicting how their programs 602090075Sobrienactually perform. However, there are applications in which this 602190075Sobriendata is hard to collect. 602290075Sobrien 602390075SobrienThe return value is the value of @var{exp}, which should be an 602490075Sobrienintegral expression. The value of @var{c} must be a compile-time 602590075Sobrienconstant. The semantics of the built-in are that it is expected 602690075Sobrienthat @var{exp} == @var{c}. For example: 602790075Sobrien 602890075Sobrien@smallexample 602990075Sobrienif (__builtin_expect (x, 0)) 603090075Sobrien foo (); 603190075Sobrien@end smallexample 603290075Sobrien 603390075Sobrien@noindent 603490075Sobrienwould indicate that we do not expect to call @code{foo}, since 603590075Sobrienwe expect @code{x} to be zero. Since you are limited to integral 603690075Sobrienexpressions for @var{exp}, you should use constructions such as 603790075Sobrien 603890075Sobrien@smallexample 603990075Sobrienif (__builtin_expect (ptr != NULL, 1)) 604090075Sobrien error (); 604190075Sobrien@end smallexample 604290075Sobrien 604390075Sobrien@noindent 604490075Sobrienwhen testing pointer or floating-point values. 604590075Sobrien@end deftypefn 604690075Sobrien 604790075Sobrien@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) 604890075SobrienThis function is used to minimize cache-miss latency by moving data into 604990075Sobriena cache before it is accessed. 605090075SobrienYou can insert calls to @code{__builtin_prefetch} into code for which 605190075Sobrienyou know addresses of data in memory that is likely to be accessed soon. 605290075SobrienIf the target supports them, data prefetch instructions will be generated. 605390075SobrienIf the prefetch is done early enough before the access then the data will 605490075Sobrienbe in the cache by the time it is accessed. 605590075Sobrien 605690075SobrienThe value of @var{addr} is the address of the memory to prefetch. 605790075SobrienThere are two optional arguments, @var{rw} and @var{locality}. 605890075SobrienThe value of @var{rw} is a compile-time constant one or zero; one 605990075Sobrienmeans that the prefetch is preparing for a write to the memory address 606090075Sobrienand zero, the default, means that the prefetch is preparing for a read. 606190075SobrienThe value @var{locality} must be a compile-time constant integer between 606290075Sobrienzero and three. A value of zero means that the data has no temporal 606390075Sobrienlocality, so it need not be left in the cache after the access. A value 606490075Sobrienof three means that the data has a high degree of temporal locality and 606590075Sobrienshould be left in all levels of cache possible. Values of one and two 606690075Sobrienmean, respectively, a low or moderate degree of temporal locality. The 606790075Sobriendefault is three. 606890075Sobrien 606990075Sobrien@smallexample 607090075Sobrienfor (i = 0; i < n; i++) 607190075Sobrien @{ 607290075Sobrien a[i] = a[i] + b[i]; 607390075Sobrien __builtin_prefetch (&a[i+j], 1, 1); 607490075Sobrien __builtin_prefetch (&b[i+j], 0, 1); 6075117395Skan /* @r{@dots{}} */ 607690075Sobrien @} 607790075Sobrien@end smallexample 607890075Sobrien 607996263SobrienData prefetch does not generate faults if @var{addr} is invalid, but 608090075Sobrienthe address expression itself must be valid. For example, a prefetch 608190075Sobrienof @code{p->next} will not fault if @code{p->next} is not a valid 608290075Sobrienaddress, but evaluation will fault if @code{p} is not a valid address. 608390075Sobrien 608490075SobrienIf the target does not support data prefetch, the address expression 608590075Sobrienis evaluated if it includes side effects but no other code is generated 608690075Sobrienand GCC does not issue a warning. 608790075Sobrien@end deftypefn 608890075Sobrien 6089117395Skan@deftypefn {Built-in Function} double __builtin_huge_val (void) 6090117395SkanReturns a positive infinity, if supported by the floating-point format, 6091117395Skanelse @code{DBL_MAX}. This function is suitable for implementing the 6092117395SkanISO C macro @code{HUGE_VAL}. 6093117395Skan@end deftypefn 6094117395Skan 6095117395Skan@deftypefn {Built-in Function} float __builtin_huge_valf (void) 6096117395SkanSimilar to @code{__builtin_huge_val}, except the return type is @code{float}. 6097117395Skan@end deftypefn 6098117395Skan 6099117395Skan@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) 6100117395SkanSimilar to @code{__builtin_huge_val}, except the return 6101117395Skantype is @code{long double}. 6102117395Skan@end deftypefn 6103117395Skan 6104117395Skan@deftypefn {Built-in Function} double __builtin_inf (void) 6105117395SkanSimilar to @code{__builtin_huge_val}, except a warning is generated 6106117395Skanif the target floating-point format does not support infinities. 6107117395Skan@end deftypefn 6108117395Skan 6109169689Skan@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) 6110169689SkanSimilar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. 6111169689Skan@end deftypefn 6112169689Skan 6113169689Skan@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) 6114169689SkanSimilar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. 6115169689Skan@end deftypefn 6116169689Skan 6117169689Skan@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) 6118169689SkanSimilar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. 6119169689Skan@end deftypefn 6120169689Skan 6121117395Skan@deftypefn {Built-in Function} float __builtin_inff (void) 6122117395SkanSimilar to @code{__builtin_inf}, except the return type is @code{float}. 6123169689SkanThis function is suitable for implementing the ISO C99 macro @code{INFINITY}. 6124117395Skan@end deftypefn 6125117395Skan 6126117395Skan@deftypefn {Built-in Function} {long double} __builtin_infl (void) 6127117395SkanSimilar to @code{__builtin_inf}, except the return 6128117395Skantype is @code{long double}. 6129117395Skan@end deftypefn 6130117395Skan 6131117395Skan@deftypefn {Built-in Function} double __builtin_nan (const char *str) 6132117395SkanThis is an implementation of the ISO C99 function @code{nan}. 6133117395Skan 6134117395SkanSince ISO C99 defines this function in terms of @code{strtod}, which we 6135117395Skando not implement, a description of the parsing is in order. The string 6136117395Skanis parsed as by @code{strtol}; that is, the base is recognized by 6137117395Skanleading @samp{0} or @samp{0x} prefixes. The number parsed is placed 6138117395Skanin the significand such that the least significant bit of the number 6139132718Skanis at the least significant bit of the significand. The number is 6140117395Skantruncated to fit the significand field provided. The significand is 6141169689Skanforced to be a quiet NaN@. 6142117395Skan 6143169689SkanThis function, if given a string literal all of which would have been 6144169689Skanconsumed by strtol, is evaluated early enough that it is considered a 6145169689Skancompile-time constant. 6146117395Skan@end deftypefn 6147117395Skan 6148169689Skan@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) 6149169689SkanSimilar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. 6150169689Skan@end deftypefn 6151169689Skan 6152169689Skan@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) 6153169689SkanSimilar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. 6154169689Skan@end deftypefn 6155169689Skan 6156169689Skan@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) 6157169689SkanSimilar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. 6158169689Skan@end deftypefn 6159169689Skan 6160117395Skan@deftypefn {Built-in Function} float __builtin_nanf (const char *str) 6161117395SkanSimilar to @code{__builtin_nan}, except the return type is @code{float}. 6162117395Skan@end deftypefn 6163117395Skan 6164117395Skan@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) 6165117395SkanSimilar to @code{__builtin_nan}, except the return type is @code{long double}. 6166117395Skan@end deftypefn 6167117395Skan 6168117395Skan@deftypefn {Built-in Function} double __builtin_nans (const char *str) 6169132718SkanSimilar to @code{__builtin_nan}, except the significand is forced 6170169689Skanto be a signaling NaN@. The @code{nans} function is proposed by 6171132718Skan@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. 6172117395Skan@end deftypefn 6173117395Skan 6174117395Skan@deftypefn {Built-in Function} float __builtin_nansf (const char *str) 6175117395SkanSimilar to @code{__builtin_nans}, except the return type is @code{float}. 6176117395Skan@end deftypefn 6177117395Skan 6178117395Skan@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) 6179117395SkanSimilar to @code{__builtin_nans}, except the return type is @code{long double}. 6180117395Skan@end deftypefn 6181117395Skan 6182132718Skan@deftypefn {Built-in Function} int __builtin_ffs (unsigned int x) 6183132718SkanReturns one plus the index of the least significant 1-bit of @var{x}, or 6184132718Skanif @var{x} is zero, returns zero. 6185132718Skan@end deftypefn 6186132718Skan 6187132718Skan@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) 6188132718SkanReturns the number of leading 0-bits in @var{x}, starting at the most 6189132718Skansignificant bit position. If @var{x} is 0, the result is undefined. 6190132718Skan@end deftypefn 6191132718Skan 6192132718Skan@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) 6193132718SkanReturns the number of trailing 0-bits in @var{x}, starting at the least 6194132718Skansignificant bit position. If @var{x} is 0, the result is undefined. 6195132718Skan@end deftypefn 6196132718Skan 6197132718Skan@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) 6198132718SkanReturns the number of 1-bits in @var{x}. 6199132718Skan@end deftypefn 6200132718Skan 6201132718Skan@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) 6202169689SkanReturns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} 6203132718Skanmodulo 2. 6204132718Skan@end deftypefn 6205132718Skan 6206132718Skan@deftypefn {Built-in Function} int __builtin_ffsl (unsigned long) 6207132718SkanSimilar to @code{__builtin_ffs}, except the argument type is 6208132718Skan@code{unsigned long}. 6209132718Skan@end deftypefn 6210132718Skan 6211132718Skan@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) 6212132718SkanSimilar to @code{__builtin_clz}, except the argument type is 6213132718Skan@code{unsigned long}. 6214132718Skan@end deftypefn 6215132718Skan 6216132718Skan@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) 6217132718SkanSimilar to @code{__builtin_ctz}, except the argument type is 6218132718Skan@code{unsigned long}. 6219132718Skan@end deftypefn 6220132718Skan 6221132718Skan@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) 6222132718SkanSimilar to @code{__builtin_popcount}, except the argument type is 6223132718Skan@code{unsigned long}. 6224132718Skan@end deftypefn 6225132718Skan 6226132718Skan@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) 6227132718SkanSimilar to @code{__builtin_parity}, except the argument type is 6228132718Skan@code{unsigned long}. 6229132718Skan@end deftypefn 6230132718Skan 6231132718Skan@deftypefn {Built-in Function} int __builtin_ffsll (unsigned long long) 6232132718SkanSimilar to @code{__builtin_ffs}, except the argument type is 6233132718Skan@code{unsigned long long}. 6234132718Skan@end deftypefn 6235132718Skan 6236132718Skan@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) 6237132718SkanSimilar to @code{__builtin_clz}, except the argument type is 6238132718Skan@code{unsigned long long}. 6239132718Skan@end deftypefn 6240132718Skan 6241132718Skan@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) 6242132718SkanSimilar to @code{__builtin_ctz}, except the argument type is 6243132718Skan@code{unsigned long long}. 6244132718Skan@end deftypefn 6245132718Skan 6246132718Skan@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) 6247132718SkanSimilar to @code{__builtin_popcount}, except the argument type is 6248132718Skan@code{unsigned long long}. 6249132718Skan@end deftypefn 6250132718Skan 6251132718Skan@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) 6252132718SkanSimilar to @code{__builtin_parity}, except the argument type is 6253132718Skan@code{unsigned long long}. 6254132718Skan@end deftypefn 6255132718Skan 6256169689Skan@deftypefn {Built-in Function} double __builtin_powi (double, int) 6257169689SkanReturns the first argument raised to the power of the second. Unlike the 6258169689Skan@code{pow} function no guarantees about precision and rounding are made. 6259169689Skan@end deftypefn 6260132718Skan 6261169689Skan@deftypefn {Built-in Function} float __builtin_powif (float, int) 6262169689SkanSimilar to @code{__builtin_powi}, except the argument and return types 6263169689Skanare @code{float}. 6264169689Skan@end deftypefn 6265169689Skan 6266169689Skan@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) 6267169689SkanSimilar to @code{__builtin_powi}, except the argument and return types 6268169689Skanare @code{long double}. 6269169689Skan@end deftypefn 6270169689Skan 6271259563Spfg@deftypefn {Built-in Function} int32_t __builtin_bswap32 (int32_t x) 6272259563SpfgReturns @var{x} with the order of the bytes reversed; for example, 6273259563Spfg@code{0xaabbccdd} becomes @code{0xddccbbaa}. Byte here always means 6274259563Spfgexactly 8 bits. 6275259563Spfg@end deftypefn 6276169689Skan 6277259563Spfg@deftypefn {Built-in Function} int64_t __builtin_bswap64 (int64_t x) 6278259563SpfgSimilar to @code{__builtin_bswap32}, except the argument and return types 6279259563Spfgare 64-bit. 6280259563Spfg@end deftypefn 6281259563Spfg 628290075Sobrien@node Target Builtins 628390075Sobrien@section Built-in Functions Specific to Particular Target Machines 628490075Sobrien 628590075SobrienOn some target machines, GCC supports many built-in functions specific 628690075Sobriento those machines. Generally these generate calls to specific machine 628790075Sobrieninstructions, but allow the compiler to schedule those calls. 628890075Sobrien 628990075Sobrien@menu 6290117395Skan* Alpha Built-in Functions:: 6291132718Skan* ARM Built-in Functions:: 6292169689Skan* Blackfin Built-in Functions:: 6293169689Skan* FR-V Built-in Functions:: 629490075Sobrien* X86 Built-in Functions:: 6295169689Skan* MIPS DSP Built-in Functions:: 6296169689Skan* MIPS Paired-Single Support:: 629790075Sobrien* PowerPC AltiVec Built-in Functions:: 6298169689Skan* SPARC VIS Built-in Functions:: 629990075Sobrien@end menu 630090075Sobrien 6301117395Skan@node Alpha Built-in Functions 6302117395Skan@subsection Alpha Built-in Functions 6303117395Skan 6304117395SkanThese built-in functions are available for the Alpha family of 6305117395Skanprocessors, depending on the command-line switches used. 6306117395Skan 6307117395SkanThe following built-in functions are always available. They 6308117395Skanall generate the machine instruction that is part of the name. 6309117395Skan 6310132718Skan@smallexample 6311117395Skanlong __builtin_alpha_implver (void) 6312117395Skanlong __builtin_alpha_rpcc (void) 6313117395Skanlong __builtin_alpha_amask (long) 6314117395Skanlong __builtin_alpha_cmpbge (long, long) 6315117395Skanlong __builtin_alpha_extbl (long, long) 6316117395Skanlong __builtin_alpha_extwl (long, long) 6317117395Skanlong __builtin_alpha_extll (long, long) 6318117395Skanlong __builtin_alpha_extql (long, long) 6319117395Skanlong __builtin_alpha_extwh (long, long) 6320117395Skanlong __builtin_alpha_extlh (long, long) 6321117395Skanlong __builtin_alpha_extqh (long, long) 6322117395Skanlong __builtin_alpha_insbl (long, long) 6323117395Skanlong __builtin_alpha_inswl (long, long) 6324117395Skanlong __builtin_alpha_insll (long, long) 6325117395Skanlong __builtin_alpha_insql (long, long) 6326117395Skanlong __builtin_alpha_inswh (long, long) 6327117395Skanlong __builtin_alpha_inslh (long, long) 6328117395Skanlong __builtin_alpha_insqh (long, long) 6329117395Skanlong __builtin_alpha_mskbl (long, long) 6330117395Skanlong __builtin_alpha_mskwl (long, long) 6331117395Skanlong __builtin_alpha_mskll (long, long) 6332117395Skanlong __builtin_alpha_mskql (long, long) 6333117395Skanlong __builtin_alpha_mskwh (long, long) 6334117395Skanlong __builtin_alpha_msklh (long, long) 6335117395Skanlong __builtin_alpha_mskqh (long, long) 6336117395Skanlong __builtin_alpha_umulh (long, long) 6337117395Skanlong __builtin_alpha_zap (long, long) 6338117395Skanlong __builtin_alpha_zapnot (long, long) 6339132718Skan@end smallexample 6340117395Skan 6341117395SkanThe following built-in functions are always with @option{-mmax} 6342117395Skanor @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or 6343117395Skanlater. They all generate the machine instruction that is part 6344117395Skanof the name. 6345117395Skan 6346132718Skan@smallexample 6347117395Skanlong __builtin_alpha_pklb (long) 6348117395Skanlong __builtin_alpha_pkwb (long) 6349117395Skanlong __builtin_alpha_unpkbl (long) 6350117395Skanlong __builtin_alpha_unpkbw (long) 6351117395Skanlong __builtin_alpha_minub8 (long, long) 6352117395Skanlong __builtin_alpha_minsb8 (long, long) 6353117395Skanlong __builtin_alpha_minuw4 (long, long) 6354117395Skanlong __builtin_alpha_minsw4 (long, long) 6355117395Skanlong __builtin_alpha_maxub8 (long, long) 6356117395Skanlong __builtin_alpha_maxsb8 (long, long) 6357117395Skanlong __builtin_alpha_maxuw4 (long, long) 6358117395Skanlong __builtin_alpha_maxsw4 (long, long) 6359117395Skanlong __builtin_alpha_perr (long, long) 6360132718Skan@end smallexample 6361117395Skan 6362117395SkanThe following built-in functions are always with @option{-mcix} 6363117395Skanor @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or 6364117395Skanlater. They all generate the machine instruction that is part 6365117395Skanof the name. 6366117395Skan 6367132718Skan@smallexample 6368117395Skanlong __builtin_alpha_cttz (long) 6369117395Skanlong __builtin_alpha_ctlz (long) 6370117395Skanlong __builtin_alpha_ctpop (long) 6371132718Skan@end smallexample 6372117395Skan 6373117395SkanThe following builtins are available on systems that use the OSF/1 6374117395SkanPALcode. Normally they invoke the @code{rduniq} and @code{wruniq} 6375117395SkanPAL calls, but when invoked with @option{-mtls-kernel}, they invoke 6376117395Skan@code{rdval} and @code{wrval}. 6377117395Skan 6378132718Skan@smallexample 6379117395Skanvoid *__builtin_thread_pointer (void) 6380117395Skanvoid __builtin_set_thread_pointer (void *) 6381132718Skan@end smallexample 6382117395Skan 6383132718Skan@node ARM Built-in Functions 6384132718Skan@subsection ARM Built-in Functions 6385132718Skan 6386132718SkanThese built-in functions are available for the ARM family of 6387132718Skanprocessors, when the @option{-mcpu=iwmmxt} switch is used: 6388132718Skan 6389132718Skan@smallexample 6390132718Skantypedef int v2si __attribute__ ((vector_size (8))); 6391132718Skantypedef short v4hi __attribute__ ((vector_size (8))); 6392132718Skantypedef char v8qi __attribute__ ((vector_size (8))); 6393132718Skan 6394132718Skanint __builtin_arm_getwcx (int) 6395132718Skanvoid __builtin_arm_setwcx (int, int) 6396132718Skanint __builtin_arm_textrmsb (v8qi, int) 6397132718Skanint __builtin_arm_textrmsh (v4hi, int) 6398132718Skanint __builtin_arm_textrmsw (v2si, int) 6399132718Skanint __builtin_arm_textrmub (v8qi, int) 6400132718Skanint __builtin_arm_textrmuh (v4hi, int) 6401132718Skanint __builtin_arm_textrmuw (v2si, int) 6402132718Skanv8qi __builtin_arm_tinsrb (v8qi, int) 6403132718Skanv4hi __builtin_arm_tinsrh (v4hi, int) 6404132718Skanv2si __builtin_arm_tinsrw (v2si, int) 6405132718Skanlong long __builtin_arm_tmia (long long, int, int) 6406132718Skanlong long __builtin_arm_tmiabb (long long, int, int) 6407132718Skanlong long __builtin_arm_tmiabt (long long, int, int) 6408132718Skanlong long __builtin_arm_tmiaph (long long, int, int) 6409132718Skanlong long __builtin_arm_tmiatb (long long, int, int) 6410132718Skanlong long __builtin_arm_tmiatt (long long, int, int) 6411132718Skanint __builtin_arm_tmovmskb (v8qi) 6412132718Skanint __builtin_arm_tmovmskh (v4hi) 6413132718Skanint __builtin_arm_tmovmskw (v2si) 6414132718Skanlong long __builtin_arm_waccb (v8qi) 6415132718Skanlong long __builtin_arm_wacch (v4hi) 6416132718Skanlong long __builtin_arm_waccw (v2si) 6417132718Skanv8qi __builtin_arm_waddb (v8qi, v8qi) 6418132718Skanv8qi __builtin_arm_waddbss (v8qi, v8qi) 6419132718Skanv8qi __builtin_arm_waddbus (v8qi, v8qi) 6420132718Skanv4hi __builtin_arm_waddh (v4hi, v4hi) 6421132718Skanv4hi __builtin_arm_waddhss (v4hi, v4hi) 6422132718Skanv4hi __builtin_arm_waddhus (v4hi, v4hi) 6423132718Skanv2si __builtin_arm_waddw (v2si, v2si) 6424132718Skanv2si __builtin_arm_waddwss (v2si, v2si) 6425132718Skanv2si __builtin_arm_waddwus (v2si, v2si) 6426132718Skanv8qi __builtin_arm_walign (v8qi, v8qi, int) 6427132718Skanlong long __builtin_arm_wand(long long, long long) 6428132718Skanlong long __builtin_arm_wandn (long long, long long) 6429132718Skanv8qi __builtin_arm_wavg2b (v8qi, v8qi) 6430132718Skanv8qi __builtin_arm_wavg2br (v8qi, v8qi) 6431132718Skanv4hi __builtin_arm_wavg2h (v4hi, v4hi) 6432132718Skanv4hi __builtin_arm_wavg2hr (v4hi, v4hi) 6433132718Skanv8qi __builtin_arm_wcmpeqb (v8qi, v8qi) 6434132718Skanv4hi __builtin_arm_wcmpeqh (v4hi, v4hi) 6435132718Skanv2si __builtin_arm_wcmpeqw (v2si, v2si) 6436132718Skanv8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) 6437132718Skanv4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) 6438132718Skanv2si __builtin_arm_wcmpgtsw (v2si, v2si) 6439132718Skanv8qi __builtin_arm_wcmpgtub (v8qi, v8qi) 6440132718Skanv4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) 6441132718Skanv2si __builtin_arm_wcmpgtuw (v2si, v2si) 6442132718Skanlong long __builtin_arm_wmacs (long long, v4hi, v4hi) 6443132718Skanlong long __builtin_arm_wmacsz (v4hi, v4hi) 6444132718Skanlong long __builtin_arm_wmacu (long long, v4hi, v4hi) 6445132718Skanlong long __builtin_arm_wmacuz (v4hi, v4hi) 6446132718Skanv4hi __builtin_arm_wmadds (v4hi, v4hi) 6447132718Skanv4hi __builtin_arm_wmaddu (v4hi, v4hi) 6448132718Skanv8qi __builtin_arm_wmaxsb (v8qi, v8qi) 6449132718Skanv4hi __builtin_arm_wmaxsh (v4hi, v4hi) 6450132718Skanv2si __builtin_arm_wmaxsw (v2si, v2si) 6451132718Skanv8qi __builtin_arm_wmaxub (v8qi, v8qi) 6452132718Skanv4hi __builtin_arm_wmaxuh (v4hi, v4hi) 6453132718Skanv2si __builtin_arm_wmaxuw (v2si, v2si) 6454132718Skanv8qi __builtin_arm_wminsb (v8qi, v8qi) 6455132718Skanv4hi __builtin_arm_wminsh (v4hi, v4hi) 6456132718Skanv2si __builtin_arm_wminsw (v2si, v2si) 6457132718Skanv8qi __builtin_arm_wminub (v8qi, v8qi) 6458132718Skanv4hi __builtin_arm_wminuh (v4hi, v4hi) 6459132718Skanv2si __builtin_arm_wminuw (v2si, v2si) 6460132718Skanv4hi __builtin_arm_wmulsm (v4hi, v4hi) 6461132718Skanv4hi __builtin_arm_wmulul (v4hi, v4hi) 6462132718Skanv4hi __builtin_arm_wmulum (v4hi, v4hi) 6463132718Skanlong long __builtin_arm_wor (long long, long long) 6464132718Skanv2si __builtin_arm_wpackdss (long long, long long) 6465132718Skanv2si __builtin_arm_wpackdus (long long, long long) 6466132718Skanv8qi __builtin_arm_wpackhss (v4hi, v4hi) 6467132718Skanv8qi __builtin_arm_wpackhus (v4hi, v4hi) 6468132718Skanv4hi __builtin_arm_wpackwss (v2si, v2si) 6469132718Skanv4hi __builtin_arm_wpackwus (v2si, v2si) 6470132718Skanlong long __builtin_arm_wrord (long long, long long) 6471132718Skanlong long __builtin_arm_wrordi (long long, int) 6472132718Skanv4hi __builtin_arm_wrorh (v4hi, long long) 6473132718Skanv4hi __builtin_arm_wrorhi (v4hi, int) 6474132718Skanv2si __builtin_arm_wrorw (v2si, long long) 6475132718Skanv2si __builtin_arm_wrorwi (v2si, int) 6476132718Skanv2si __builtin_arm_wsadb (v8qi, v8qi) 6477132718Skanv2si __builtin_arm_wsadbz (v8qi, v8qi) 6478132718Skanv2si __builtin_arm_wsadh (v4hi, v4hi) 6479132718Skanv2si __builtin_arm_wsadhz (v4hi, v4hi) 6480132718Skanv4hi __builtin_arm_wshufh (v4hi, int) 6481132718Skanlong long __builtin_arm_wslld (long long, long long) 6482132718Skanlong long __builtin_arm_wslldi (long long, int) 6483132718Skanv4hi __builtin_arm_wsllh (v4hi, long long) 6484132718Skanv4hi __builtin_arm_wsllhi (v4hi, int) 6485132718Skanv2si __builtin_arm_wsllw (v2si, long long) 6486132718Skanv2si __builtin_arm_wsllwi (v2si, int) 6487132718Skanlong long __builtin_arm_wsrad (long long, long long) 6488132718Skanlong long __builtin_arm_wsradi (long long, int) 6489132718Skanv4hi __builtin_arm_wsrah (v4hi, long long) 6490132718Skanv4hi __builtin_arm_wsrahi (v4hi, int) 6491132718Skanv2si __builtin_arm_wsraw (v2si, long long) 6492132718Skanv2si __builtin_arm_wsrawi (v2si, int) 6493132718Skanlong long __builtin_arm_wsrld (long long, long long) 6494132718Skanlong long __builtin_arm_wsrldi (long long, int) 6495132718Skanv4hi __builtin_arm_wsrlh (v4hi, long long) 6496132718Skanv4hi __builtin_arm_wsrlhi (v4hi, int) 6497132718Skanv2si __builtin_arm_wsrlw (v2si, long long) 6498132718Skanv2si __builtin_arm_wsrlwi (v2si, int) 6499132718Skanv8qi __builtin_arm_wsubb (v8qi, v8qi) 6500132718Skanv8qi __builtin_arm_wsubbss (v8qi, v8qi) 6501132718Skanv8qi __builtin_arm_wsubbus (v8qi, v8qi) 6502132718Skanv4hi __builtin_arm_wsubh (v4hi, v4hi) 6503132718Skanv4hi __builtin_arm_wsubhss (v4hi, v4hi) 6504132718Skanv4hi __builtin_arm_wsubhus (v4hi, v4hi) 6505132718Skanv2si __builtin_arm_wsubw (v2si, v2si) 6506132718Skanv2si __builtin_arm_wsubwss (v2si, v2si) 6507132718Skanv2si __builtin_arm_wsubwus (v2si, v2si) 6508132718Skanv4hi __builtin_arm_wunpckehsb (v8qi) 6509132718Skanv2si __builtin_arm_wunpckehsh (v4hi) 6510132718Skanlong long __builtin_arm_wunpckehsw (v2si) 6511132718Skanv4hi __builtin_arm_wunpckehub (v8qi) 6512132718Skanv2si __builtin_arm_wunpckehuh (v4hi) 6513132718Skanlong long __builtin_arm_wunpckehuw (v2si) 6514132718Skanv4hi __builtin_arm_wunpckelsb (v8qi) 6515132718Skanv2si __builtin_arm_wunpckelsh (v4hi) 6516132718Skanlong long __builtin_arm_wunpckelsw (v2si) 6517132718Skanv4hi __builtin_arm_wunpckelub (v8qi) 6518132718Skanv2si __builtin_arm_wunpckeluh (v4hi) 6519132718Skanlong long __builtin_arm_wunpckeluw (v2si) 6520132718Skanv8qi __builtin_arm_wunpckihb (v8qi, v8qi) 6521132718Skanv4hi __builtin_arm_wunpckihh (v4hi, v4hi) 6522132718Skanv2si __builtin_arm_wunpckihw (v2si, v2si) 6523132718Skanv8qi __builtin_arm_wunpckilb (v8qi, v8qi) 6524132718Skanv4hi __builtin_arm_wunpckilh (v4hi, v4hi) 6525132718Skanv2si __builtin_arm_wunpckilw (v2si, v2si) 6526132718Skanlong long __builtin_arm_wxor (long long, long long) 6527132718Skanlong long __builtin_arm_wzero () 6528132718Skan@end smallexample 6529132718Skan 6530169689Skan@node Blackfin Built-in Functions 6531169689Skan@subsection Blackfin Built-in Functions 6532169689Skan 6533169689SkanCurrently, there are two Blackfin-specific built-in functions. These are 6534169689Skanused for generating @code{CSYNC} and @code{SSYNC} machine insns without 6535169689Skanusing inline assembly; by using these built-in functions the compiler can 6536169689Skanautomatically add workarounds for hardware errata involving these 6537169689Skaninstructions. These functions are named as follows: 6538169689Skan 6539169689Skan@smallexample 6540169689Skanvoid __builtin_bfin_csync (void) 6541169689Skanvoid __builtin_bfin_ssync (void) 6542169689Skan@end smallexample 6543169689Skan 6544169689Skan@node FR-V Built-in Functions 6545169689Skan@subsection FR-V Built-in Functions 6546169689Skan 6547169689SkanGCC provides many FR-V-specific built-in functions. In general, 6548169689Skanthese functions are intended to be compatible with those described 6549169689Skanby @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu 6550169689SkanSemiconductor}. The two exceptions are @code{__MDUNPACKH} and 6551169689Skan@code{__MBTOHE}, the gcc forms of which pass 128-bit values by 6552169689Skanpointer rather than by value. 6553169689Skan 6554169689SkanMost of the functions are named after specific FR-V instructions. 6555169689SkanSuch functions are said to be ``directly mapped'' and are summarized 6556169689Skanhere in tabular form. 6557169689Skan 6558169689Skan@menu 6559169689Skan* Argument Types:: 6560169689Skan* Directly-mapped Integer Functions:: 6561169689Skan* Directly-mapped Media Functions:: 6562169689Skan* Raw read/write Functions:: 6563169689Skan* Other Built-in Functions:: 6564169689Skan@end menu 6565169689Skan 6566169689Skan@node Argument Types 6567169689Skan@subsubsection Argument Types 6568169689Skan 6569169689SkanThe arguments to the built-in functions can be divided into three groups: 6570169689Skanregister numbers, compile-time constants and run-time values. In order 6571169689Skanto make this classification clear at a glance, the arguments and return 6572169689Skanvalues are given the following pseudo types: 6573169689Skan 6574169689Skan@multitable @columnfractions .20 .30 .15 .35 6575169689Skan@item Pseudo type @tab Real C type @tab Constant? @tab Description 6576169689Skan@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword 6577169689Skan@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word 6578169689Skan@item @code{sw1} @tab @code{int} @tab No @tab a signed word 6579169689Skan@item @code{uw2} @tab @code{unsigned long long} @tab No 6580169689Skan@tab an unsigned doubleword 6581169689Skan@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword 6582169689Skan@item @code{const} @tab @code{int} @tab Yes @tab an integer constant 6583169689Skan@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number 6584169689Skan@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number 6585169689Skan@end multitable 6586169689Skan 6587169689SkanThese pseudo types are not defined by GCC, they are simply a notational 6588169689Skanconvenience used in this manual. 6589169689Skan 6590169689SkanArguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} 6591169689Skanand @code{sw2} are evaluated at run time. They correspond to 6592169689Skanregister operands in the underlying FR-V instructions. 6593169689Skan 6594169689Skan@code{const} arguments represent immediate operands in the underlying 6595169689SkanFR-V instructions. They must be compile-time constants. 6596169689Skan 6597169689Skan@code{acc} arguments are evaluated at compile time and specify the number 6598169689Skanof an accumulator register. For example, an @code{acc} argument of 2 6599169689Skanwill select the ACC2 register. 6600169689Skan 6601169689Skan@code{iacc} arguments are similar to @code{acc} arguments but specify the 6602169689Skannumber of an IACC register. See @pxref{Other Built-in Functions} 6603169689Skanfor more details. 6604169689Skan 6605169689Skan@node Directly-mapped Integer Functions 6606169689Skan@subsubsection Directly-mapped Integer Functions 6607169689Skan 6608169689SkanThe functions listed below map directly to FR-V I-type instructions. 6609169689Skan 6610169689Skan@multitable @columnfractions .45 .32 .23 6611169689Skan@item Function prototype @tab Example usage @tab Assembly output 6612169689Skan@item @code{sw1 __ADDSS (sw1, sw1)} 6613169689Skan@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} 6614169689Skan@tab @code{ADDSS @var{a},@var{b},@var{c}} 6615169689Skan@item @code{sw1 __SCAN (sw1, sw1)} 6616169689Skan@tab @code{@var{c} = __SCAN (@var{a}, @var{b})} 6617169689Skan@tab @code{SCAN @var{a},@var{b},@var{c}} 6618169689Skan@item @code{sw1 __SCUTSS (sw1)} 6619169689Skan@tab @code{@var{b} = __SCUTSS (@var{a})} 6620169689Skan@tab @code{SCUTSS @var{a},@var{b}} 6621169689Skan@item @code{sw1 __SLASS (sw1, sw1)} 6622169689Skan@tab @code{@var{c} = __SLASS (@var{a}, @var{b})} 6623169689Skan@tab @code{SLASS @var{a},@var{b},@var{c}} 6624169689Skan@item @code{void __SMASS (sw1, sw1)} 6625169689Skan@tab @code{__SMASS (@var{a}, @var{b})} 6626169689Skan@tab @code{SMASS @var{a},@var{b}} 6627169689Skan@item @code{void __SMSSS (sw1, sw1)} 6628169689Skan@tab @code{__SMSSS (@var{a}, @var{b})} 6629169689Skan@tab @code{SMSSS @var{a},@var{b}} 6630169689Skan@item @code{void __SMU (sw1, sw1)} 6631169689Skan@tab @code{__SMU (@var{a}, @var{b})} 6632169689Skan@tab @code{SMU @var{a},@var{b}} 6633169689Skan@item @code{sw2 __SMUL (sw1, sw1)} 6634169689Skan@tab @code{@var{c} = __SMUL (@var{a}, @var{b})} 6635169689Skan@tab @code{SMUL @var{a},@var{b},@var{c}} 6636169689Skan@item @code{sw1 __SUBSS (sw1, sw1)} 6637169689Skan@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} 6638169689Skan@tab @code{SUBSS @var{a},@var{b},@var{c}} 6639169689Skan@item @code{uw2 __UMUL (uw1, uw1)} 6640169689Skan@tab @code{@var{c} = __UMUL (@var{a}, @var{b})} 6641169689Skan@tab @code{UMUL @var{a},@var{b},@var{c}} 6642169689Skan@end multitable 6643169689Skan 6644169689Skan@node Directly-mapped Media Functions 6645169689Skan@subsubsection Directly-mapped Media Functions 6646169689Skan 6647169689SkanThe functions listed below map directly to FR-V M-type instructions. 6648169689Skan 6649169689Skan@multitable @columnfractions .45 .32 .23 6650169689Skan@item Function prototype @tab Example usage @tab Assembly output 6651169689Skan@item @code{uw1 __MABSHS (sw1)} 6652169689Skan@tab @code{@var{b} = __MABSHS (@var{a})} 6653169689Skan@tab @code{MABSHS @var{a},@var{b}} 6654169689Skan@item @code{void __MADDACCS (acc, acc)} 6655169689Skan@tab @code{__MADDACCS (@var{b}, @var{a})} 6656169689Skan@tab @code{MADDACCS @var{a},@var{b}} 6657169689Skan@item @code{sw1 __MADDHSS (sw1, sw1)} 6658169689Skan@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} 6659169689Skan@tab @code{MADDHSS @var{a},@var{b},@var{c}} 6660169689Skan@item @code{uw1 __MADDHUS (uw1, uw1)} 6661169689Skan@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} 6662169689Skan@tab @code{MADDHUS @var{a},@var{b},@var{c}} 6663169689Skan@item @code{uw1 __MAND (uw1, uw1)} 6664169689Skan@tab @code{@var{c} = __MAND (@var{a}, @var{b})} 6665169689Skan@tab @code{MAND @var{a},@var{b},@var{c}} 6666169689Skan@item @code{void __MASACCS (acc, acc)} 6667169689Skan@tab @code{__MASACCS (@var{b}, @var{a})} 6668169689Skan@tab @code{MASACCS @var{a},@var{b}} 6669169689Skan@item @code{uw1 __MAVEH (uw1, uw1)} 6670169689Skan@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} 6671169689Skan@tab @code{MAVEH @var{a},@var{b},@var{c}} 6672169689Skan@item @code{uw2 __MBTOH (uw1)} 6673169689Skan@tab @code{@var{b} = __MBTOH (@var{a})} 6674169689Skan@tab @code{MBTOH @var{a},@var{b}} 6675169689Skan@item @code{void __MBTOHE (uw1 *, uw1)} 6676169689Skan@tab @code{__MBTOHE (&@var{b}, @var{a})} 6677169689Skan@tab @code{MBTOHE @var{a},@var{b}} 6678169689Skan@item @code{void __MCLRACC (acc)} 6679169689Skan@tab @code{__MCLRACC (@var{a})} 6680169689Skan@tab @code{MCLRACC @var{a}} 6681169689Skan@item @code{void __MCLRACCA (void)} 6682169689Skan@tab @code{__MCLRACCA ()} 6683169689Skan@tab @code{MCLRACCA} 6684169689Skan@item @code{uw1 __Mcop1 (uw1, uw1)} 6685169689Skan@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} 6686169689Skan@tab @code{Mcop1 @var{a},@var{b},@var{c}} 6687169689Skan@item @code{uw1 __Mcop2 (uw1, uw1)} 6688169689Skan@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} 6689169689Skan@tab @code{Mcop2 @var{a},@var{b},@var{c}} 6690169689Skan@item @code{uw1 __MCPLHI (uw2, const)} 6691169689Skan@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} 6692169689Skan@tab @code{MCPLHI @var{a},#@var{b},@var{c}} 6693169689Skan@item @code{uw1 __MCPLI (uw2, const)} 6694169689Skan@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} 6695169689Skan@tab @code{MCPLI @var{a},#@var{b},@var{c}} 6696169689Skan@item @code{void __MCPXIS (acc, sw1, sw1)} 6697169689Skan@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} 6698169689Skan@tab @code{MCPXIS @var{a},@var{b},@var{c}} 6699169689Skan@item @code{void __MCPXIU (acc, uw1, uw1)} 6700169689Skan@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} 6701169689Skan@tab @code{MCPXIU @var{a},@var{b},@var{c}} 6702169689Skan@item @code{void __MCPXRS (acc, sw1, sw1)} 6703169689Skan@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} 6704169689Skan@tab @code{MCPXRS @var{a},@var{b},@var{c}} 6705169689Skan@item @code{void __MCPXRU (acc, uw1, uw1)} 6706169689Skan@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} 6707169689Skan@tab @code{MCPXRU @var{a},@var{b},@var{c}} 6708169689Skan@item @code{uw1 __MCUT (acc, uw1)} 6709169689Skan@tab @code{@var{c} = __MCUT (@var{a}, @var{b})} 6710169689Skan@tab @code{MCUT @var{a},@var{b},@var{c}} 6711169689Skan@item @code{uw1 __MCUTSS (acc, sw1)} 6712169689Skan@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} 6713169689Skan@tab @code{MCUTSS @var{a},@var{b},@var{c}} 6714169689Skan@item @code{void __MDADDACCS (acc, acc)} 6715169689Skan@tab @code{__MDADDACCS (@var{b}, @var{a})} 6716169689Skan@tab @code{MDADDACCS @var{a},@var{b}} 6717169689Skan@item @code{void __MDASACCS (acc, acc)} 6718169689Skan@tab @code{__MDASACCS (@var{b}, @var{a})} 6719169689Skan@tab @code{MDASACCS @var{a},@var{b}} 6720169689Skan@item @code{uw2 __MDCUTSSI (acc, const)} 6721169689Skan@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} 6722169689Skan@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} 6723169689Skan@item @code{uw2 __MDPACKH (uw2, uw2)} 6724169689Skan@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} 6725169689Skan@tab @code{MDPACKH @var{a},@var{b},@var{c}} 6726169689Skan@item @code{uw2 __MDROTLI (uw2, const)} 6727169689Skan@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} 6728169689Skan@tab @code{MDROTLI @var{a},#@var{b},@var{c}} 6729169689Skan@item @code{void __MDSUBACCS (acc, acc)} 6730169689Skan@tab @code{__MDSUBACCS (@var{b}, @var{a})} 6731169689Skan@tab @code{MDSUBACCS @var{a},@var{b}} 6732169689Skan@item @code{void __MDUNPACKH (uw1 *, uw2)} 6733169689Skan@tab @code{__MDUNPACKH (&@var{b}, @var{a})} 6734169689Skan@tab @code{MDUNPACKH @var{a},@var{b}} 6735169689Skan@item @code{uw2 __MEXPDHD (uw1, const)} 6736169689Skan@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} 6737169689Skan@tab @code{MEXPDHD @var{a},#@var{b},@var{c}} 6738169689Skan@item @code{uw1 __MEXPDHW (uw1, const)} 6739169689Skan@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} 6740169689Skan@tab @code{MEXPDHW @var{a},#@var{b},@var{c}} 6741169689Skan@item @code{uw1 __MHDSETH (uw1, const)} 6742169689Skan@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} 6743169689Skan@tab @code{MHDSETH @var{a},#@var{b},@var{c}} 6744169689Skan@item @code{sw1 __MHDSETS (const)} 6745169689Skan@tab @code{@var{b} = __MHDSETS (@var{a})} 6746169689Skan@tab @code{MHDSETS #@var{a},@var{b}} 6747169689Skan@item @code{uw1 __MHSETHIH (uw1, const)} 6748169689Skan@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} 6749169689Skan@tab @code{MHSETHIH #@var{a},@var{b}} 6750169689Skan@item @code{sw1 __MHSETHIS (sw1, const)} 6751169689Skan@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} 6752169689Skan@tab @code{MHSETHIS #@var{a},@var{b}} 6753169689Skan@item @code{uw1 __MHSETLOH (uw1, const)} 6754169689Skan@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} 6755169689Skan@tab @code{MHSETLOH #@var{a},@var{b}} 6756169689Skan@item @code{sw1 __MHSETLOS (sw1, const)} 6757169689Skan@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} 6758169689Skan@tab @code{MHSETLOS #@var{a},@var{b}} 6759169689Skan@item @code{uw1 __MHTOB (uw2)} 6760169689Skan@tab @code{@var{b} = __MHTOB (@var{a})} 6761169689Skan@tab @code{MHTOB @var{a},@var{b}} 6762169689Skan@item @code{void __MMACHS (acc, sw1, sw1)} 6763169689Skan@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} 6764169689Skan@tab @code{MMACHS @var{a},@var{b},@var{c}} 6765169689Skan@item @code{void __MMACHU (acc, uw1, uw1)} 6766169689Skan@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} 6767169689Skan@tab @code{MMACHU @var{a},@var{b},@var{c}} 6768169689Skan@item @code{void __MMRDHS (acc, sw1, sw1)} 6769169689Skan@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} 6770169689Skan@tab @code{MMRDHS @var{a},@var{b},@var{c}} 6771169689Skan@item @code{void __MMRDHU (acc, uw1, uw1)} 6772169689Skan@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} 6773169689Skan@tab @code{MMRDHU @var{a},@var{b},@var{c}} 6774169689Skan@item @code{void __MMULHS (acc, sw1, sw1)} 6775169689Skan@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} 6776169689Skan@tab @code{MMULHS @var{a},@var{b},@var{c}} 6777169689Skan@item @code{void __MMULHU (acc, uw1, uw1)} 6778169689Skan@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} 6779169689Skan@tab @code{MMULHU @var{a},@var{b},@var{c}} 6780169689Skan@item @code{void __MMULXHS (acc, sw1, sw1)} 6781169689Skan@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} 6782169689Skan@tab @code{MMULXHS @var{a},@var{b},@var{c}} 6783169689Skan@item @code{void __MMULXHU (acc, uw1, uw1)} 6784169689Skan@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} 6785169689Skan@tab @code{MMULXHU @var{a},@var{b},@var{c}} 6786169689Skan@item @code{uw1 __MNOT (uw1)} 6787169689Skan@tab @code{@var{b} = __MNOT (@var{a})} 6788169689Skan@tab @code{MNOT @var{a},@var{b}} 6789169689Skan@item @code{uw1 __MOR (uw1, uw1)} 6790169689Skan@tab @code{@var{c} = __MOR (@var{a}, @var{b})} 6791169689Skan@tab @code{MOR @var{a},@var{b},@var{c}} 6792169689Skan@item @code{uw1 __MPACKH (uh, uh)} 6793169689Skan@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} 6794169689Skan@tab @code{MPACKH @var{a},@var{b},@var{c}} 6795169689Skan@item @code{sw2 __MQADDHSS (sw2, sw2)} 6796169689Skan@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} 6797169689Skan@tab @code{MQADDHSS @var{a},@var{b},@var{c}} 6798169689Skan@item @code{uw2 __MQADDHUS (uw2, uw2)} 6799169689Skan@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} 6800169689Skan@tab @code{MQADDHUS @var{a},@var{b},@var{c}} 6801169689Skan@item @code{void __MQCPXIS (acc, sw2, sw2)} 6802169689Skan@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} 6803169689Skan@tab @code{MQCPXIS @var{a},@var{b},@var{c}} 6804169689Skan@item @code{void __MQCPXIU (acc, uw2, uw2)} 6805169689Skan@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} 6806169689Skan@tab @code{MQCPXIU @var{a},@var{b},@var{c}} 6807169689Skan@item @code{void __MQCPXRS (acc, sw2, sw2)} 6808169689Skan@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} 6809169689Skan@tab @code{MQCPXRS @var{a},@var{b},@var{c}} 6810169689Skan@item @code{void __MQCPXRU (acc, uw2, uw2)} 6811169689Skan@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} 6812169689Skan@tab @code{MQCPXRU @var{a},@var{b},@var{c}} 6813169689Skan@item @code{sw2 __MQLCLRHS (sw2, sw2)} 6814169689Skan@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} 6815169689Skan@tab @code{MQLCLRHS @var{a},@var{b},@var{c}} 6816169689Skan@item @code{sw2 __MQLMTHS (sw2, sw2)} 6817169689Skan@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} 6818169689Skan@tab @code{MQLMTHS @var{a},@var{b},@var{c}} 6819169689Skan@item @code{void __MQMACHS (acc, sw2, sw2)} 6820169689Skan@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} 6821169689Skan@tab @code{MQMACHS @var{a},@var{b},@var{c}} 6822169689Skan@item @code{void __MQMACHU (acc, uw2, uw2)} 6823169689Skan@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} 6824169689Skan@tab @code{MQMACHU @var{a},@var{b},@var{c}} 6825169689Skan@item @code{void __MQMACXHS (acc, sw2, sw2)} 6826169689Skan@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} 6827169689Skan@tab @code{MQMACXHS @var{a},@var{b},@var{c}} 6828169689Skan@item @code{void __MQMULHS (acc, sw2, sw2)} 6829169689Skan@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} 6830169689Skan@tab @code{MQMULHS @var{a},@var{b},@var{c}} 6831169689Skan@item @code{void __MQMULHU (acc, uw2, uw2)} 6832169689Skan@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} 6833169689Skan@tab @code{MQMULHU @var{a},@var{b},@var{c}} 6834169689Skan@item @code{void __MQMULXHS (acc, sw2, sw2)} 6835169689Skan@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} 6836169689Skan@tab @code{MQMULXHS @var{a},@var{b},@var{c}} 6837169689Skan@item @code{void __MQMULXHU (acc, uw2, uw2)} 6838169689Skan@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} 6839169689Skan@tab @code{MQMULXHU @var{a},@var{b},@var{c}} 6840169689Skan@item @code{sw2 __MQSATHS (sw2, sw2)} 6841169689Skan@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} 6842169689Skan@tab @code{MQSATHS @var{a},@var{b},@var{c}} 6843169689Skan@item @code{uw2 __MQSLLHI (uw2, int)} 6844169689Skan@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} 6845169689Skan@tab @code{MQSLLHI @var{a},@var{b},@var{c}} 6846169689Skan@item @code{sw2 __MQSRAHI (sw2, int)} 6847169689Skan@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} 6848169689Skan@tab @code{MQSRAHI @var{a},@var{b},@var{c}} 6849169689Skan@item @code{sw2 __MQSUBHSS (sw2, sw2)} 6850169689Skan@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} 6851169689Skan@tab @code{MQSUBHSS @var{a},@var{b},@var{c}} 6852169689Skan@item @code{uw2 __MQSUBHUS (uw2, uw2)} 6853169689Skan@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} 6854169689Skan@tab @code{MQSUBHUS @var{a},@var{b},@var{c}} 6855169689Skan@item @code{void __MQXMACHS (acc, sw2, sw2)} 6856169689Skan@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} 6857169689Skan@tab @code{MQXMACHS @var{a},@var{b},@var{c}} 6858169689Skan@item @code{void __MQXMACXHS (acc, sw2, sw2)} 6859169689Skan@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} 6860169689Skan@tab @code{MQXMACXHS @var{a},@var{b},@var{c}} 6861169689Skan@item @code{uw1 __MRDACC (acc)} 6862169689Skan@tab @code{@var{b} = __MRDACC (@var{a})} 6863169689Skan@tab @code{MRDACC @var{a},@var{b}} 6864169689Skan@item @code{uw1 __MRDACCG (acc)} 6865169689Skan@tab @code{@var{b} = __MRDACCG (@var{a})} 6866169689Skan@tab @code{MRDACCG @var{a},@var{b}} 6867169689Skan@item @code{uw1 __MROTLI (uw1, const)} 6868169689Skan@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} 6869169689Skan@tab @code{MROTLI @var{a},#@var{b},@var{c}} 6870169689Skan@item @code{uw1 __MROTRI (uw1, const)} 6871169689Skan@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} 6872169689Skan@tab @code{MROTRI @var{a},#@var{b},@var{c}} 6873169689Skan@item @code{sw1 __MSATHS (sw1, sw1)} 6874169689Skan@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} 6875169689Skan@tab @code{MSATHS @var{a},@var{b},@var{c}} 6876169689Skan@item @code{uw1 __MSATHU (uw1, uw1)} 6877169689Skan@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} 6878169689Skan@tab @code{MSATHU @var{a},@var{b},@var{c}} 6879169689Skan@item @code{uw1 __MSLLHI (uw1, const)} 6880169689Skan@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} 6881169689Skan@tab @code{MSLLHI @var{a},#@var{b},@var{c}} 6882169689Skan@item @code{sw1 __MSRAHI (sw1, const)} 6883169689Skan@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} 6884169689Skan@tab @code{MSRAHI @var{a},#@var{b},@var{c}} 6885169689Skan@item @code{uw1 __MSRLHI (uw1, const)} 6886169689Skan@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} 6887169689Skan@tab @code{MSRLHI @var{a},#@var{b},@var{c}} 6888169689Skan@item @code{void __MSUBACCS (acc, acc)} 6889169689Skan@tab @code{__MSUBACCS (@var{b}, @var{a})} 6890169689Skan@tab @code{MSUBACCS @var{a},@var{b}} 6891169689Skan@item @code{sw1 __MSUBHSS (sw1, sw1)} 6892169689Skan@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} 6893169689Skan@tab @code{MSUBHSS @var{a},@var{b},@var{c}} 6894169689Skan@item @code{uw1 __MSUBHUS (uw1, uw1)} 6895169689Skan@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} 6896169689Skan@tab @code{MSUBHUS @var{a},@var{b},@var{c}} 6897169689Skan@item @code{void __MTRAP (void)} 6898169689Skan@tab @code{__MTRAP ()} 6899169689Skan@tab @code{MTRAP} 6900169689Skan@item @code{uw2 __MUNPACKH (uw1)} 6901169689Skan@tab @code{@var{b} = __MUNPACKH (@var{a})} 6902169689Skan@tab @code{MUNPACKH @var{a},@var{b}} 6903169689Skan@item @code{uw1 __MWCUT (uw2, uw1)} 6904169689Skan@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} 6905169689Skan@tab @code{MWCUT @var{a},@var{b},@var{c}} 6906169689Skan@item @code{void __MWTACC (acc, uw1)} 6907169689Skan@tab @code{__MWTACC (@var{b}, @var{a})} 6908169689Skan@tab @code{MWTACC @var{a},@var{b}} 6909169689Skan@item @code{void __MWTACCG (acc, uw1)} 6910169689Skan@tab @code{__MWTACCG (@var{b}, @var{a})} 6911169689Skan@tab @code{MWTACCG @var{a},@var{b}} 6912169689Skan@item @code{uw1 __MXOR (uw1, uw1)} 6913169689Skan@tab @code{@var{c} = __MXOR (@var{a}, @var{b})} 6914169689Skan@tab @code{MXOR @var{a},@var{b},@var{c}} 6915169689Skan@end multitable 6916169689Skan 6917169689Skan@node Raw read/write Functions 6918169689Skan@subsubsection Raw read/write Functions 6919169689Skan 6920169689SkanThis sections describes built-in functions related to read and write 6921169689Skaninstructions to access memory. These functions generate 6922169689Skan@code{membar} instructions to flush the I/O load and stores where 6923169689Skanappropriate, as described in Fujitsu's manual described above. 6924169689Skan 6925169689Skan@table @code 6926169689Skan 6927169689Skan@item unsigned char __builtin_read8 (void *@var{data}) 6928169689Skan@item unsigned short __builtin_read16 (void *@var{data}) 6929169689Skan@item unsigned long __builtin_read32 (void *@var{data}) 6930169689Skan@item unsigned long long __builtin_read64 (void *@var{data}) 6931169689Skan 6932169689Skan@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) 6933169689Skan@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) 6934169689Skan@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) 6935169689Skan@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) 6936169689Skan@end table 6937169689Skan 6938169689Skan@node Other Built-in Functions 6939169689Skan@subsubsection Other Built-in Functions 6940169689Skan 6941169689SkanThis section describes built-in functions that are not named after 6942169689Skana specific FR-V instruction. 6943169689Skan 6944169689Skan@table @code 6945169689Skan@item sw2 __IACCreadll (iacc @var{reg}) 6946169689SkanReturn the full 64-bit value of IACC0@. The @var{reg} argument is reserved 6947169689Skanfor future expansion and must be 0. 6948169689Skan 6949169689Skan@item sw1 __IACCreadl (iacc @var{reg}) 6950169689SkanReturn the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. 6951169689SkanOther values of @var{reg} are rejected as invalid. 6952169689Skan 6953169689Skan@item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) 6954169689SkanSet the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument 6955169689Skanis reserved for future expansion and must be 0. 6956169689Skan 6957169689Skan@item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) 6958169689SkanSet IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} 6959169689Skanis 1. Other values of @var{reg} are rejected as invalid. 6960169689Skan 6961169689Skan@item void __data_prefetch0 (const void *@var{x}) 6962169689SkanUse the @code{dcpl} instruction to load the contents of address @var{x} 6963169689Skaninto the data cache. 6964169689Skan 6965169689Skan@item void __data_prefetch (const void *@var{x}) 6966169689SkanUse the @code{nldub} instruction to load the contents of address @var{x} 6967169689Skaninto the data cache. The instruction will be issued in slot I1@. 6968169689Skan@end table 6969169689Skan 697090075Sobrien@node X86 Built-in Functions 697190075Sobrien@subsection X86 Built-in Functions 697290075Sobrien 697390075SobrienThese built-in functions are available for the i386 and x86-64 family 697490075Sobrienof computers, depending on the command-line switches used. 697590075Sobrien 6976169689SkanNote that, if you specify command-line switches such as @option{-msse}, 6977169689Skanthe compiler could use the extended instruction sets even if the built-ins 6978169689Skanare not used explicitly in the program. For this reason, applications 6979169689Skanwhich perform runtime CPU detection must compile separate files for each 6980169689Skansupported architecture, using the appropriate flags. In particular, 6981169689Skanthe file containing the CPU detection code should be compiled without 6982169689Skanthese options. 6983169689Skan 698490075SobrienThe following machine modes are available for use with MMX built-in functions 698590075Sobrien(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, 698690075Sobrien@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a 698790075Sobrienvector of eight 8-bit integers. Some of the built-in functions operate on 698890075SobrienMMX registers as a whole 64-bit entity, these use @code{DI} as their mode. 698990075Sobrien 699090075SobrienIf 3Dnow extensions are enabled, @code{V2SF} is used as a mode for a vector 699190075Sobrienof two 32-bit floating point values. 699290075Sobrien 699390075SobrienIf SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit 699490075Sobrienfloating point values. Some instructions use a vector of four 32-bit 699590075Sobrienintegers, these use @code{V4SI}. Finally, some instructions operate on an 699690075Sobrienentire vector register, interpreting it as a 128-bit integer, these use mode 699790075Sobrien@code{TI}. 699890075Sobrien 699990075SobrienThe following built-in functions are made available by @option{-mmmx}. 700090075SobrienAll of them generate the machine instruction that is part of the name. 700190075Sobrien 7002132718Skan@smallexample 700390075Sobrienv8qi __builtin_ia32_paddb (v8qi, v8qi) 700490075Sobrienv4hi __builtin_ia32_paddw (v4hi, v4hi) 700590075Sobrienv2si __builtin_ia32_paddd (v2si, v2si) 700690075Sobrienv8qi __builtin_ia32_psubb (v8qi, v8qi) 700790075Sobrienv4hi __builtin_ia32_psubw (v4hi, v4hi) 700890075Sobrienv2si __builtin_ia32_psubd (v2si, v2si) 700990075Sobrienv8qi __builtin_ia32_paddsb (v8qi, v8qi) 701090075Sobrienv4hi __builtin_ia32_paddsw (v4hi, v4hi) 701190075Sobrienv8qi __builtin_ia32_psubsb (v8qi, v8qi) 701290075Sobrienv4hi __builtin_ia32_psubsw (v4hi, v4hi) 701390075Sobrienv8qi __builtin_ia32_paddusb (v8qi, v8qi) 701490075Sobrienv4hi __builtin_ia32_paddusw (v4hi, v4hi) 701590075Sobrienv8qi __builtin_ia32_psubusb (v8qi, v8qi) 701690075Sobrienv4hi __builtin_ia32_psubusw (v4hi, v4hi) 701790075Sobrienv4hi __builtin_ia32_pmullw (v4hi, v4hi) 701890075Sobrienv4hi __builtin_ia32_pmulhw (v4hi, v4hi) 701990075Sobriendi __builtin_ia32_pand (di, di) 702090075Sobriendi __builtin_ia32_pandn (di,di) 702190075Sobriendi __builtin_ia32_por (di, di) 702290075Sobriendi __builtin_ia32_pxor (di, di) 702390075Sobrienv8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) 702490075Sobrienv4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) 702590075Sobrienv2si __builtin_ia32_pcmpeqd (v2si, v2si) 702690075Sobrienv8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) 702790075Sobrienv4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) 702890075Sobrienv2si __builtin_ia32_pcmpgtd (v2si, v2si) 702990075Sobrienv8qi __builtin_ia32_punpckhbw (v8qi, v8qi) 703090075Sobrienv4hi __builtin_ia32_punpckhwd (v4hi, v4hi) 703190075Sobrienv2si __builtin_ia32_punpckhdq (v2si, v2si) 703290075Sobrienv8qi __builtin_ia32_punpcklbw (v8qi, v8qi) 703390075Sobrienv4hi __builtin_ia32_punpcklwd (v4hi, v4hi) 703490075Sobrienv2si __builtin_ia32_punpckldq (v2si, v2si) 703590075Sobrienv8qi __builtin_ia32_packsswb (v4hi, v4hi) 703690075Sobrienv4hi __builtin_ia32_packssdw (v2si, v2si) 703790075Sobrienv8qi __builtin_ia32_packuswb (v4hi, v4hi) 7038132718Skan@end smallexample 703990075Sobrien 704090075SobrienThe following built-in functions are made available either with 704190075Sobrien@option{-msse}, or with a combination of @option{-m3dnow} and 704290075Sobrien@option{-march=athlon}. All of them generate the machine 704390075Sobrieninstruction that is part of the name. 704490075Sobrien 7045132718Skan@smallexample 704690075Sobrienv4hi __builtin_ia32_pmulhuw (v4hi, v4hi) 704790075Sobrienv8qi __builtin_ia32_pavgb (v8qi, v8qi) 704890075Sobrienv4hi __builtin_ia32_pavgw (v4hi, v4hi) 704990075Sobrienv4hi __builtin_ia32_psadbw (v8qi, v8qi) 705090075Sobrienv8qi __builtin_ia32_pmaxub (v8qi, v8qi) 705190075Sobrienv4hi __builtin_ia32_pmaxsw (v4hi, v4hi) 705290075Sobrienv8qi __builtin_ia32_pminub (v8qi, v8qi) 705390075Sobrienv4hi __builtin_ia32_pminsw (v4hi, v4hi) 705490075Sobrienint __builtin_ia32_pextrw (v4hi, int) 705590075Sobrienv4hi __builtin_ia32_pinsrw (v4hi, int, int) 705690075Sobrienint __builtin_ia32_pmovmskb (v8qi) 705790075Sobrienvoid __builtin_ia32_maskmovq (v8qi, v8qi, char *) 705890075Sobrienvoid __builtin_ia32_movntq (di *, di) 705990075Sobrienvoid __builtin_ia32_sfence (void) 7060132718Skan@end smallexample 706190075Sobrien 706290075SobrienThe following built-in functions are available when @option{-msse} is used. 706390075SobrienAll of them generate the machine instruction that is part of the name. 706490075Sobrien 7065132718Skan@smallexample 706690075Sobrienint __builtin_ia32_comieq (v4sf, v4sf) 706790075Sobrienint __builtin_ia32_comineq (v4sf, v4sf) 706890075Sobrienint __builtin_ia32_comilt (v4sf, v4sf) 706990075Sobrienint __builtin_ia32_comile (v4sf, v4sf) 707090075Sobrienint __builtin_ia32_comigt (v4sf, v4sf) 707190075Sobrienint __builtin_ia32_comige (v4sf, v4sf) 707290075Sobrienint __builtin_ia32_ucomieq (v4sf, v4sf) 707390075Sobrienint __builtin_ia32_ucomineq (v4sf, v4sf) 707490075Sobrienint __builtin_ia32_ucomilt (v4sf, v4sf) 707590075Sobrienint __builtin_ia32_ucomile (v4sf, v4sf) 707690075Sobrienint __builtin_ia32_ucomigt (v4sf, v4sf) 707790075Sobrienint __builtin_ia32_ucomige (v4sf, v4sf) 707890075Sobrienv4sf __builtin_ia32_addps (v4sf, v4sf) 707990075Sobrienv4sf __builtin_ia32_subps (v4sf, v4sf) 708090075Sobrienv4sf __builtin_ia32_mulps (v4sf, v4sf) 708190075Sobrienv4sf __builtin_ia32_divps (v4sf, v4sf) 708290075Sobrienv4sf __builtin_ia32_addss (v4sf, v4sf) 708390075Sobrienv4sf __builtin_ia32_subss (v4sf, v4sf) 708490075Sobrienv4sf __builtin_ia32_mulss (v4sf, v4sf) 708590075Sobrienv4sf __builtin_ia32_divss (v4sf, v4sf) 708690075Sobrienv4si __builtin_ia32_cmpeqps (v4sf, v4sf) 708790075Sobrienv4si __builtin_ia32_cmpltps (v4sf, v4sf) 708890075Sobrienv4si __builtin_ia32_cmpleps (v4sf, v4sf) 708990075Sobrienv4si __builtin_ia32_cmpgtps (v4sf, v4sf) 709090075Sobrienv4si __builtin_ia32_cmpgeps (v4sf, v4sf) 709190075Sobrienv4si __builtin_ia32_cmpunordps (v4sf, v4sf) 709290075Sobrienv4si __builtin_ia32_cmpneqps (v4sf, v4sf) 709390075Sobrienv4si __builtin_ia32_cmpnltps (v4sf, v4sf) 709490075Sobrienv4si __builtin_ia32_cmpnleps (v4sf, v4sf) 709590075Sobrienv4si __builtin_ia32_cmpngtps (v4sf, v4sf) 709690075Sobrienv4si __builtin_ia32_cmpngeps (v4sf, v4sf) 709790075Sobrienv4si __builtin_ia32_cmpordps (v4sf, v4sf) 709890075Sobrienv4si __builtin_ia32_cmpeqss (v4sf, v4sf) 709990075Sobrienv4si __builtin_ia32_cmpltss (v4sf, v4sf) 710090075Sobrienv4si __builtin_ia32_cmpless (v4sf, v4sf) 710190075Sobrienv4si __builtin_ia32_cmpunordss (v4sf, v4sf) 710290075Sobrienv4si __builtin_ia32_cmpneqss (v4sf, v4sf) 710390075Sobrienv4si __builtin_ia32_cmpnlts (v4sf, v4sf) 710490075Sobrienv4si __builtin_ia32_cmpnless (v4sf, v4sf) 710590075Sobrienv4si __builtin_ia32_cmpordss (v4sf, v4sf) 710690075Sobrienv4sf __builtin_ia32_maxps (v4sf, v4sf) 710790075Sobrienv4sf __builtin_ia32_maxss (v4sf, v4sf) 710890075Sobrienv4sf __builtin_ia32_minps (v4sf, v4sf) 710990075Sobrienv4sf __builtin_ia32_minss (v4sf, v4sf) 711090075Sobrienv4sf __builtin_ia32_andps (v4sf, v4sf) 711190075Sobrienv4sf __builtin_ia32_andnps (v4sf, v4sf) 711290075Sobrienv4sf __builtin_ia32_orps (v4sf, v4sf) 711390075Sobrienv4sf __builtin_ia32_xorps (v4sf, v4sf) 711490075Sobrienv4sf __builtin_ia32_movss (v4sf, v4sf) 711590075Sobrienv4sf __builtin_ia32_movhlps (v4sf, v4sf) 711690075Sobrienv4sf __builtin_ia32_movlhps (v4sf, v4sf) 711790075Sobrienv4sf __builtin_ia32_unpckhps (v4sf, v4sf) 711890075Sobrienv4sf __builtin_ia32_unpcklps (v4sf, v4sf) 711990075Sobrienv4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) 712090075Sobrienv4sf __builtin_ia32_cvtsi2ss (v4sf, int) 712190075Sobrienv2si __builtin_ia32_cvtps2pi (v4sf) 712290075Sobrienint __builtin_ia32_cvtss2si (v4sf) 712390075Sobrienv2si __builtin_ia32_cvttps2pi (v4sf) 712490075Sobrienint __builtin_ia32_cvttss2si (v4sf) 712590075Sobrienv4sf __builtin_ia32_rcpps (v4sf) 712690075Sobrienv4sf __builtin_ia32_rsqrtps (v4sf) 712790075Sobrienv4sf __builtin_ia32_sqrtps (v4sf) 712890075Sobrienv4sf __builtin_ia32_rcpss (v4sf) 712990075Sobrienv4sf __builtin_ia32_rsqrtss (v4sf) 713090075Sobrienv4sf __builtin_ia32_sqrtss (v4sf) 713190075Sobrienv4sf __builtin_ia32_shufps (v4sf, v4sf, int) 713290075Sobrienvoid __builtin_ia32_movntps (float *, v4sf) 713390075Sobrienint __builtin_ia32_movmskps (v4sf) 7134132718Skan@end smallexample 713590075Sobrien 713690075SobrienThe following built-in functions are available when @option{-msse} is used. 713790075Sobrien 713890075Sobrien@table @code 713990075Sobrien@item v4sf __builtin_ia32_loadaps (float *) 714090075SobrienGenerates the @code{movaps} machine instruction as a load from memory. 714190075Sobrien@item void __builtin_ia32_storeaps (float *, v4sf) 714290075SobrienGenerates the @code{movaps} machine instruction as a store to memory. 714390075Sobrien@item v4sf __builtin_ia32_loadups (float *) 714490075SobrienGenerates the @code{movups} machine instruction as a load from memory. 714590075Sobrien@item void __builtin_ia32_storeups (float *, v4sf) 714690075SobrienGenerates the @code{movups} machine instruction as a store to memory. 714790075Sobrien@item v4sf __builtin_ia32_loadsss (float *) 714890075SobrienGenerates the @code{movss} machine instruction as a load from memory. 714990075Sobrien@item void __builtin_ia32_storess (float *, v4sf) 715090075SobrienGenerates the @code{movss} machine instruction as a store to memory. 715190075Sobrien@item v4sf __builtin_ia32_loadhps (v4sf, v2si *) 715290075SobrienGenerates the @code{movhps} machine instruction as a load from memory. 715390075Sobrien@item v4sf __builtin_ia32_loadlps (v4sf, v2si *) 715490075SobrienGenerates the @code{movlps} machine instruction as a load from memory 715590075Sobrien@item void __builtin_ia32_storehps (v4sf, v2si *) 715690075SobrienGenerates the @code{movhps} machine instruction as a store to memory. 715790075Sobrien@item void __builtin_ia32_storelps (v4sf, v2si *) 715890075SobrienGenerates the @code{movlps} machine instruction as a store to memory. 715990075Sobrien@end table 716090075Sobrien 7161169689SkanThe following built-in functions are available when @option{-msse2} is used. 7162169689SkanAll of them generate the machine instruction that is part of the name. 7163169689Skan 7164169689Skan@smallexample 7165169689Skanint __builtin_ia32_comisdeq (v2df, v2df) 7166169689Skanint __builtin_ia32_comisdlt (v2df, v2df) 7167169689Skanint __builtin_ia32_comisdle (v2df, v2df) 7168169689Skanint __builtin_ia32_comisdgt (v2df, v2df) 7169169689Skanint __builtin_ia32_comisdge (v2df, v2df) 7170169689Skanint __builtin_ia32_comisdneq (v2df, v2df) 7171169689Skanint __builtin_ia32_ucomisdeq (v2df, v2df) 7172169689Skanint __builtin_ia32_ucomisdlt (v2df, v2df) 7173169689Skanint __builtin_ia32_ucomisdle (v2df, v2df) 7174169689Skanint __builtin_ia32_ucomisdgt (v2df, v2df) 7175169689Skanint __builtin_ia32_ucomisdge (v2df, v2df) 7176169689Skanint __builtin_ia32_ucomisdneq (v2df, v2df) 7177169689Skanv2df __builtin_ia32_cmpeqpd (v2df, v2df) 7178169689Skanv2df __builtin_ia32_cmpltpd (v2df, v2df) 7179169689Skanv2df __builtin_ia32_cmplepd (v2df, v2df) 7180169689Skanv2df __builtin_ia32_cmpgtpd (v2df, v2df) 7181169689Skanv2df __builtin_ia32_cmpgepd (v2df, v2df) 7182169689Skanv2df __builtin_ia32_cmpunordpd (v2df, v2df) 7183169689Skanv2df __builtin_ia32_cmpneqpd (v2df, v2df) 7184169689Skanv2df __builtin_ia32_cmpnltpd (v2df, v2df) 7185169689Skanv2df __builtin_ia32_cmpnlepd (v2df, v2df) 7186169689Skanv2df __builtin_ia32_cmpngtpd (v2df, v2df) 7187169689Skanv2df __builtin_ia32_cmpngepd (v2df, v2df) 7188169689Skanv2df __builtin_ia32_cmpordpd (v2df, v2df) 7189169689Skanv2df __builtin_ia32_cmpeqsd (v2df, v2df) 7190169689Skanv2df __builtin_ia32_cmpltsd (v2df, v2df) 7191169689Skanv2df __builtin_ia32_cmplesd (v2df, v2df) 7192169689Skanv2df __builtin_ia32_cmpunordsd (v2df, v2df) 7193169689Skanv2df __builtin_ia32_cmpneqsd (v2df, v2df) 7194169689Skanv2df __builtin_ia32_cmpnltsd (v2df, v2df) 7195169689Skanv2df __builtin_ia32_cmpnlesd (v2df, v2df) 7196169689Skanv2df __builtin_ia32_cmpordsd (v2df, v2df) 7197169689Skanv2di __builtin_ia32_paddq (v2di, v2di) 7198169689Skanv2di __builtin_ia32_psubq (v2di, v2di) 7199169689Skanv2df __builtin_ia32_addpd (v2df, v2df) 7200169689Skanv2df __builtin_ia32_subpd (v2df, v2df) 7201169689Skanv2df __builtin_ia32_mulpd (v2df, v2df) 7202169689Skanv2df __builtin_ia32_divpd (v2df, v2df) 7203169689Skanv2df __builtin_ia32_addsd (v2df, v2df) 7204169689Skanv2df __builtin_ia32_subsd (v2df, v2df) 7205169689Skanv2df __builtin_ia32_mulsd (v2df, v2df) 7206169689Skanv2df __builtin_ia32_divsd (v2df, v2df) 7207169689Skanv2df __builtin_ia32_minpd (v2df, v2df) 7208169689Skanv2df __builtin_ia32_maxpd (v2df, v2df) 7209169689Skanv2df __builtin_ia32_minsd (v2df, v2df) 7210169689Skanv2df __builtin_ia32_maxsd (v2df, v2df) 7211169689Skanv2df __builtin_ia32_andpd (v2df, v2df) 7212169689Skanv2df __builtin_ia32_andnpd (v2df, v2df) 7213169689Skanv2df __builtin_ia32_orpd (v2df, v2df) 7214169689Skanv2df __builtin_ia32_xorpd (v2df, v2df) 7215169689Skanv2df __builtin_ia32_movsd (v2df, v2df) 7216169689Skanv2df __builtin_ia32_unpckhpd (v2df, v2df) 7217169689Skanv2df __builtin_ia32_unpcklpd (v2df, v2df) 7218169689Skanv16qi __builtin_ia32_paddb128 (v16qi, v16qi) 7219169689Skanv8hi __builtin_ia32_paddw128 (v8hi, v8hi) 7220169689Skanv4si __builtin_ia32_paddd128 (v4si, v4si) 7221169689Skanv2di __builtin_ia32_paddq128 (v2di, v2di) 7222169689Skanv16qi __builtin_ia32_psubb128 (v16qi, v16qi) 7223169689Skanv8hi __builtin_ia32_psubw128 (v8hi, v8hi) 7224169689Skanv4si __builtin_ia32_psubd128 (v4si, v4si) 7225169689Skanv2di __builtin_ia32_psubq128 (v2di, v2di) 7226169689Skanv8hi __builtin_ia32_pmullw128 (v8hi, v8hi) 7227169689Skanv8hi __builtin_ia32_pmulhw128 (v8hi, v8hi) 7228169689Skanv2di __builtin_ia32_pand128 (v2di, v2di) 7229169689Skanv2di __builtin_ia32_pandn128 (v2di, v2di) 7230169689Skanv2di __builtin_ia32_por128 (v2di, v2di) 7231169689Skanv2di __builtin_ia32_pxor128 (v2di, v2di) 7232169689Skanv16qi __builtin_ia32_pavgb128 (v16qi, v16qi) 7233169689Skanv8hi __builtin_ia32_pavgw128 (v8hi, v8hi) 7234169689Skanv16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi) 7235169689Skanv8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi) 7236169689Skanv4si __builtin_ia32_pcmpeqd128 (v4si, v4si) 7237169689Skanv16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi) 7238169689Skanv8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi) 7239169689Skanv4si __builtin_ia32_pcmpgtd128 (v4si, v4si) 7240169689Skanv16qi __builtin_ia32_pmaxub128 (v16qi, v16qi) 7241169689Skanv8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi) 7242169689Skanv16qi __builtin_ia32_pminub128 (v16qi, v16qi) 7243169689Skanv8hi __builtin_ia32_pminsw128 (v8hi, v8hi) 7244169689Skanv16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi) 7245169689Skanv8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi) 7246169689Skanv4si __builtin_ia32_punpckhdq128 (v4si, v4si) 7247169689Skanv2di __builtin_ia32_punpckhqdq128 (v2di, v2di) 7248169689Skanv16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi) 7249169689Skanv8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi) 7250169689Skanv4si __builtin_ia32_punpckldq128 (v4si, v4si) 7251169689Skanv2di __builtin_ia32_punpcklqdq128 (v2di, v2di) 7252169689Skanv16qi __builtin_ia32_packsswb128 (v16qi, v16qi) 7253169689Skanv8hi __builtin_ia32_packssdw128 (v8hi, v8hi) 7254169689Skanv16qi __builtin_ia32_packuswb128 (v16qi, v16qi) 7255169689Skanv8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi) 7256169689Skanvoid __builtin_ia32_maskmovdqu (v16qi, v16qi) 7257169689Skanv2df __builtin_ia32_loadupd (double *) 7258169689Skanvoid __builtin_ia32_storeupd (double *, v2df) 7259169689Skanv2df __builtin_ia32_loadhpd (v2df, double *) 7260169689Skanv2df __builtin_ia32_loadlpd (v2df, double *) 7261169689Skanint __builtin_ia32_movmskpd (v2df) 7262169689Skanint __builtin_ia32_pmovmskb128 (v16qi) 7263169689Skanvoid __builtin_ia32_movnti (int *, int) 7264169689Skanvoid __builtin_ia32_movntpd (double *, v2df) 7265169689Skanvoid __builtin_ia32_movntdq (v2df *, v2df) 7266169689Skanv4si __builtin_ia32_pshufd (v4si, int) 7267169689Skanv8hi __builtin_ia32_pshuflw (v8hi, int) 7268169689Skanv8hi __builtin_ia32_pshufhw (v8hi, int) 7269169689Skanv2di __builtin_ia32_psadbw128 (v16qi, v16qi) 7270169689Skanv2df __builtin_ia32_sqrtpd (v2df) 7271169689Skanv2df __builtin_ia32_sqrtsd (v2df) 7272169689Skanv2df __builtin_ia32_shufpd (v2df, v2df, int) 7273169689Skanv2df __builtin_ia32_cvtdq2pd (v4si) 7274169689Skanv4sf __builtin_ia32_cvtdq2ps (v4si) 7275169689Skanv4si __builtin_ia32_cvtpd2dq (v2df) 7276169689Skanv2si __builtin_ia32_cvtpd2pi (v2df) 7277169689Skanv4sf __builtin_ia32_cvtpd2ps (v2df) 7278169689Skanv4si __builtin_ia32_cvttpd2dq (v2df) 7279169689Skanv2si __builtin_ia32_cvttpd2pi (v2df) 7280169689Skanv2df __builtin_ia32_cvtpi2pd (v2si) 7281169689Skanint __builtin_ia32_cvtsd2si (v2df) 7282169689Skanint __builtin_ia32_cvttsd2si (v2df) 7283169689Skanlong long __builtin_ia32_cvtsd2si64 (v2df) 7284169689Skanlong long __builtin_ia32_cvttsd2si64 (v2df) 7285169689Skanv4si __builtin_ia32_cvtps2dq (v4sf) 7286169689Skanv2df __builtin_ia32_cvtps2pd (v4sf) 7287169689Skanv4si __builtin_ia32_cvttps2dq (v4sf) 7288169689Skanv2df __builtin_ia32_cvtsi2sd (v2df, int) 7289169689Skanv2df __builtin_ia32_cvtsi642sd (v2df, long long) 7290169689Skanv4sf __builtin_ia32_cvtsd2ss (v4sf, v2df) 7291169689Skanv2df __builtin_ia32_cvtss2sd (v2df, v4sf) 7292169689Skanvoid __builtin_ia32_clflush (const void *) 7293169689Skanvoid __builtin_ia32_lfence (void) 7294169689Skanvoid __builtin_ia32_mfence (void) 7295169689Skanv16qi __builtin_ia32_loaddqu (const char *) 7296169689Skanvoid __builtin_ia32_storedqu (char *, v16qi) 7297169689Skanunsigned long long __builtin_ia32_pmuludq (v2si, v2si) 7298169689Skanv2di __builtin_ia32_pmuludq128 (v4si, v4si) 7299169689Skanv8hi __builtin_ia32_psllw128 (v8hi, v2di) 7300169689Skanv4si __builtin_ia32_pslld128 (v4si, v2di) 7301169689Skanv2di __builtin_ia32_psllq128 (v4si, v2di) 7302169689Skanv8hi __builtin_ia32_psrlw128 (v8hi, v2di) 7303169689Skanv4si __builtin_ia32_psrld128 (v4si, v2di) 7304169689Skanv2di __builtin_ia32_psrlq128 (v2di, v2di) 7305169689Skanv8hi __builtin_ia32_psraw128 (v8hi, v2di) 7306169689Skanv4si __builtin_ia32_psrad128 (v4si, v2di) 7307169689Skanv2di __builtin_ia32_pslldqi128 (v2di, int) 7308169689Skanv8hi __builtin_ia32_psllwi128 (v8hi, int) 7309169689Skanv4si __builtin_ia32_pslldi128 (v4si, int) 7310169689Skanv2di __builtin_ia32_psllqi128 (v2di, int) 7311169689Skanv2di __builtin_ia32_psrldqi128 (v2di, int) 7312169689Skanv8hi __builtin_ia32_psrlwi128 (v8hi, int) 7313169689Skanv4si __builtin_ia32_psrldi128 (v4si, int) 7314169689Skanv2di __builtin_ia32_psrlqi128 (v2di, int) 7315169689Skanv8hi __builtin_ia32_psrawi128 (v8hi, int) 7316169689Skanv4si __builtin_ia32_psradi128 (v4si, int) 7317169689Skanv4si __builtin_ia32_pmaddwd128 (v8hi, v8hi) 7318169689Skan@end smallexample 7319169689Skan 7320132718SkanThe following built-in functions are available when @option{-msse3} is used. 7321122180SkanAll of them generate the machine instruction that is part of the name. 7322122180Skan 7323132718Skan@smallexample 7324122180Skanv2df __builtin_ia32_addsubpd (v2df, v2df) 7325169689Skanv4sf __builtin_ia32_addsubps (v4sf, v4sf) 7326122180Skanv2df __builtin_ia32_haddpd (v2df, v2df) 7327169689Skanv4sf __builtin_ia32_haddps (v4sf, v4sf) 7328122180Skanv2df __builtin_ia32_hsubpd (v2df, v2df) 7329169689Skanv4sf __builtin_ia32_hsubps (v4sf, v4sf) 7330122180Skanv16qi __builtin_ia32_lddqu (char const *) 7331122180Skanvoid __builtin_ia32_monitor (void *, unsigned int, unsigned int) 7332122180Skanv2df __builtin_ia32_movddup (v2df) 7333122180Skanv4sf __builtin_ia32_movshdup (v4sf) 7334122180Skanv4sf __builtin_ia32_movsldup (v4sf) 7335122180Skanvoid __builtin_ia32_mwait (unsigned int, unsigned int) 7336132718Skan@end smallexample 7337122180Skan 7338132718SkanThe following built-in functions are available when @option{-msse3} is used. 7339122180Skan 7340122180Skan@table @code 7341122180Skan@item v2df __builtin_ia32_loadddup (double const *) 7342122180SkanGenerates the @code{movddup} machine instruction as a load from memory. 7343122180Skan@end table 7344122180Skan 7345219639SmmThe following built-in functions are available when @option{-mssse3} is used. 7346219639SmmAll of them generate the machine instruction that is part of the name 7347219639Smmwith MMX registers. 7348219639Smm 7349219639Smm@smallexample 7350219639Smmv2si __builtin_ia32_phaddd (v2si, v2si) 7351219639Smmv4hi __builtin_ia32_phaddw (v4hi, v4hi) 7352219639Smmv4hi __builtin_ia32_phaddsw (v4hi, v4hi) 7353219639Smmv2si __builtin_ia32_phsubd (v2si, v2si) 7354219639Smmv4hi __builtin_ia32_phsubw (v4hi, v4hi) 7355219639Smmv4hi __builtin_ia32_phsubsw (v4hi, v4hi) 7356219639Smmv8qi __builtin_ia32_pmaddubsw (v8qi, v8qi) 7357219639Smmv4hi __builtin_ia32_pmulhrsw (v4hi, v4hi) 7358219639Smmv8qi __builtin_ia32_pshufb (v8qi, v8qi) 7359219639Smmv8qi __builtin_ia32_psignb (v8qi, v8qi) 7360219639Smmv2si __builtin_ia32_psignd (v2si, v2si) 7361219639Smmv4hi __builtin_ia32_psignw (v4hi, v4hi) 7362219639Smmlong long __builtin_ia32_palignr (long long, long long, int) 7363219639Smmv8qi __builtin_ia32_pabsb (v8qi) 7364219639Smmv2si __builtin_ia32_pabsd (v2si) 7365219639Smmv4hi __builtin_ia32_pabsw (v4hi) 7366219639Smm@end smallexample 7367219639Smm 7368219639SmmThe following built-in functions are available when @option{-mssse3} is used. 7369219639SmmAll of them generate the machine instruction that is part of the name 7370219639Smmwith SSE registers. 7371219639Smm 7372219639Smm@smallexample 7373219639Smmv4si __builtin_ia32_phaddd128 (v4si, v4si) 7374219639Smmv8hi __builtin_ia32_phaddw128 (v8hi, v8hi) 7375219639Smmv8hi __builtin_ia32_phaddsw128 (v8hi, v8hi) 7376219639Smmv4si __builtin_ia32_phsubd128 (v4si, v4si) 7377219639Smmv8hi __builtin_ia32_phsubw128 (v8hi, v8hi) 7378219639Smmv8hi __builtin_ia32_phsubsw128 (v8hi, v8hi) 7379219639Smmv16qi __builtin_ia32_pmaddubsw128 (v16qi, v16qi) 7380219639Smmv8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi) 7381219639Smmv16qi __builtin_ia32_pshufb128 (v16qi, v16qi) 7382219639Smmv16qi __builtin_ia32_psignb128 (v16qi, v16qi) 7383219639Smmv4si __builtin_ia32_psignd128 (v4si, v4si) 7384219639Smmv8hi __builtin_ia32_psignw128 (v8hi, v8hi) 7385219639Smmv2di __builtin_ia32_palignr (v2di, v2di, int) 7386219639Smmv16qi __builtin_ia32_pabsb128 (v16qi) 7387219639Smmv4si __builtin_ia32_pabsd128 (v4si) 7388219639Smmv8hi __builtin_ia32_pabsw128 (v8hi) 7389219639Smm@end smallexample 7390219639Smm 7391251212SpfgThe following built-in functions are available when @option{-msse4a} is used. 7392251212Spfg 7393251212Spfg@smallexample 7394251212Spfgvoid _mm_stream_sd (double*,__m128d); 7395251212SpfgGenerates the @code{movntsd} machine instruction. 7396251212Spfgvoid _mm_stream_ss (float*,__m128); 7397251212SpfgGenerates the @code{movntss} machine instruction. 7398251212Spfg__m128i _mm_extract_si64 (__m128i, __m128i); 7399251212SpfgGenerates the @code{extrq} machine instruction with only SSE register operands. 7400251212Spfg__m128i _mm_extracti_si64 (__m128i, int, int); 7401251212SpfgGenerates the @code{extrq} machine instruction with SSE register and immediate operands. 7402251212Spfg__m128i _mm_insert_si64 (__m128i, __m128i); 7403251212SpfgGenerates the @code{insertq} machine instruction with only SSE register operands. 7404251212Spfg__m128i _mm_inserti_si64 (__m128i, __m128i, int, int); 7405251212SpfgGenerates the @code{insertq} machine instruction with SSE register and immediate operands. 7406251212Spfg@end smallexample 7407251212Spfg 740890075SobrienThe following built-in functions are available when @option{-m3dnow} is used. 740990075SobrienAll of them generate the machine instruction that is part of the name. 741090075Sobrien 7411132718Skan@smallexample 741290075Sobrienvoid __builtin_ia32_femms (void) 741390075Sobrienv8qi __builtin_ia32_pavgusb (v8qi, v8qi) 741490075Sobrienv2si __builtin_ia32_pf2id (v2sf) 741590075Sobrienv2sf __builtin_ia32_pfacc (v2sf, v2sf) 741690075Sobrienv2sf __builtin_ia32_pfadd (v2sf, v2sf) 741790075Sobrienv2si __builtin_ia32_pfcmpeq (v2sf, v2sf) 741890075Sobrienv2si __builtin_ia32_pfcmpge (v2sf, v2sf) 741990075Sobrienv2si __builtin_ia32_pfcmpgt (v2sf, v2sf) 742090075Sobrienv2sf __builtin_ia32_pfmax (v2sf, v2sf) 742190075Sobrienv2sf __builtin_ia32_pfmin (v2sf, v2sf) 742290075Sobrienv2sf __builtin_ia32_pfmul (v2sf, v2sf) 742390075Sobrienv2sf __builtin_ia32_pfrcp (v2sf) 742490075Sobrienv2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) 742590075Sobrienv2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) 742690075Sobrienv2sf __builtin_ia32_pfrsqrt (v2sf) 742790075Sobrienv2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf) 742890075Sobrienv2sf __builtin_ia32_pfsub (v2sf, v2sf) 742990075Sobrienv2sf __builtin_ia32_pfsubr (v2sf, v2sf) 743090075Sobrienv2sf __builtin_ia32_pi2fd (v2si) 743190075Sobrienv4hi __builtin_ia32_pmulhrw (v4hi, v4hi) 7432132718Skan@end smallexample 743390075Sobrien 743490075SobrienThe following built-in functions are available when both @option{-m3dnow} 743590075Sobrienand @option{-march=athlon} are used. All of them generate the machine 743690075Sobrieninstruction that is part of the name. 743790075Sobrien 7438132718Skan@smallexample 743990075Sobrienv2si __builtin_ia32_pf2iw (v2sf) 744090075Sobrienv2sf __builtin_ia32_pfnacc (v2sf, v2sf) 744190075Sobrienv2sf __builtin_ia32_pfpnacc (v2sf, v2sf) 744290075Sobrienv2sf __builtin_ia32_pi2fw (v2si) 744390075Sobrienv2sf __builtin_ia32_pswapdsf (v2sf) 744490075Sobrienv2si __builtin_ia32_pswapdsi (v2si) 7445132718Skan@end smallexample 744690075Sobrien 7447169689Skan@node MIPS DSP Built-in Functions 7448169689Skan@subsection MIPS DSP Built-in Functions 7449169689Skan 7450169689SkanThe MIPS DSP Application-Specific Extension (ASE) includes new 7451169689Skaninstructions that are designed to improve the performance of DSP and 7452169689Skanmedia applications. It provides instructions that operate on packed 7453169689Skan8-bit integer data, Q15 fractional data and Q31 fractional data. 7454169689Skan 7455169689SkanGCC supports MIPS DSP operations using both the generic 7456169689Skanvector extensions (@pxref{Vector Extensions}) and a collection of 7457169689SkanMIPS-specific built-in functions. Both kinds of support are 7458169689Skanenabled by the @option{-mdsp} command-line option. 7459169689Skan 7460169689SkanAt present, GCC only provides support for operations on 32-bit 7461169689Skanvectors. The vector type associated with 8-bit integer data is 7462169689Skanusually called @code{v4i8} and the vector type associated with Q15 is 7463169689Skanusually called @code{v2q15}. They can be defined in C as follows: 7464169689Skan 7465169689Skan@smallexample 7466169689Skantypedef char v4i8 __attribute__ ((vector_size(4))); 7467169689Skantypedef short v2q15 __attribute__ ((vector_size(4))); 7468169689Skan@end smallexample 7469169689Skan 7470169689Skan@code{v4i8} and @code{v2q15} values are initialized in the same way as 7471169689Skanaggregates. For example: 7472169689Skan 7473169689Skan@smallexample 7474169689Skanv4i8 a = @{1, 2, 3, 4@}; 7475169689Skanv4i8 b; 7476169689Skanb = (v4i8) @{5, 6, 7, 8@}; 7477169689Skan 7478169689Skanv2q15 c = @{0x0fcb, 0x3a75@}; 7479169689Skanv2q15 d; 7480169689Skand = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; 7481169689Skan@end smallexample 7482169689Skan 7483169689Skan@emph{Note:} The CPU's endianness determines the order in which values 7484169689Skanare packed. On little-endian targets, the first value is the least 7485169689Skansignificant and the last value is the most significant. The opposite 7486169689Skanorder applies to big-endian targets. For example, the code above will 7487169689Skanset the lowest byte of @code{a} to @code{1} on little-endian targets 7488169689Skanand @code{4} on big-endian targets. 7489169689Skan 7490169689Skan@emph{Note:} Q15 and Q31 values must be initialized with their integer 7491169689Skanrepresentation. As shown in this example, the integer representation 7492169689Skanof a Q15 value can be obtained by multiplying the fractional value by 7493169689Skan@code{0x1.0p15}. The equivalent for Q31 values is to multiply by 7494169689Skan@code{0x1.0p31}. 7495169689Skan 7496169689SkanThe table below lists the @code{v4i8} and @code{v2q15} operations for which 7497169689Skanhardware support exists. @code{a} and @code{b} are @code{v4i8} values, 7498169689Skanand @code{c} and @code{d} are @code{v2q15} values. 7499169689Skan 7500169689Skan@multitable @columnfractions .50 .50 7501169689Skan@item C code @tab MIPS instruction 7502169689Skan@item @code{a + b} @tab @code{addu.qb} 7503169689Skan@item @code{c + d} @tab @code{addq.ph} 7504169689Skan@item @code{a - b} @tab @code{subu.qb} 7505169689Skan@item @code{c - d} @tab @code{subq.ph} 7506169689Skan@end multitable 7507169689Skan 7508169689SkanIt is easier to describe the DSP built-in functions if we first define 7509169689Skanthe following types: 7510169689Skan 7511169689Skan@smallexample 7512169689Skantypedef int q31; 7513169689Skantypedef int i32; 7514169689Skantypedef long long a64; 7515169689Skan@end smallexample 7516169689Skan 7517169689Skan@code{q31} and @code{i32} are actually the same as @code{int}, but we 7518169689Skanuse @code{q31} to indicate a Q31 fractional value and @code{i32} to 7519169689Skanindicate a 32-bit integer value. Similarly, @code{a64} is the same as 7520169689Skan@code{long long}, but we use @code{a64} to indicate values that will 7521169689Skanbe placed in one of the four DSP accumulators (@code{$ac0}, 7522169689Skan@code{$ac1}, @code{$ac2} or @code{$ac3}). 7523169689Skan 7524169689SkanAlso, some built-in functions prefer or require immediate numbers as 7525169689Skanparameters, because the corresponding DSP instructions accept both immediate 7526169689Skannumbers and register operands, or accept immediate numbers only. The 7527169689Skanimmediate parameters are listed as follows. 7528169689Skan 7529169689Skan@smallexample 7530169689Skanimm0_7: 0 to 7. 7531169689Skanimm0_15: 0 to 15. 7532169689Skanimm0_31: 0 to 31. 7533169689Skanimm0_63: 0 to 63. 7534169689Skanimm0_255: 0 to 255. 7535169689Skanimm_n32_31: -32 to 31. 7536169689Skanimm_n512_511: -512 to 511. 7537169689Skan@end smallexample 7538169689Skan 7539169689SkanThe following built-in functions map directly to a particular MIPS DSP 7540169689Skaninstruction. Please refer to the architecture specification 7541169689Skanfor details on what each instruction does. 7542169689Skan 7543169689Skan@smallexample 7544169689Skanv2q15 __builtin_mips_addq_ph (v2q15, v2q15) 7545169689Skanv2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) 7546169689Skanq31 __builtin_mips_addq_s_w (q31, q31) 7547169689Skanv4i8 __builtin_mips_addu_qb (v4i8, v4i8) 7548169689Skanv4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) 7549169689Skanv2q15 __builtin_mips_subq_ph (v2q15, v2q15) 7550169689Skanv2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) 7551169689Skanq31 __builtin_mips_subq_s_w (q31, q31) 7552169689Skanv4i8 __builtin_mips_subu_qb (v4i8, v4i8) 7553169689Skanv4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) 7554169689Skani32 __builtin_mips_addsc (i32, i32) 7555169689Skani32 __builtin_mips_addwc (i32, i32) 7556169689Skani32 __builtin_mips_modsub (i32, i32) 7557169689Skani32 __builtin_mips_raddu_w_qb (v4i8) 7558169689Skanv2q15 __builtin_mips_absq_s_ph (v2q15) 7559169689Skanq31 __builtin_mips_absq_s_w (q31) 7560169689Skanv4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) 7561169689Skanv2q15 __builtin_mips_precrq_ph_w (q31, q31) 7562169689Skanv2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) 7563169689Skanv4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) 7564169689Skanq31 __builtin_mips_preceq_w_phl (v2q15) 7565169689Skanq31 __builtin_mips_preceq_w_phr (v2q15) 7566169689Skanv2q15 __builtin_mips_precequ_ph_qbl (v4i8) 7567169689Skanv2q15 __builtin_mips_precequ_ph_qbr (v4i8) 7568169689Skanv2q15 __builtin_mips_precequ_ph_qbla (v4i8) 7569169689Skanv2q15 __builtin_mips_precequ_ph_qbra (v4i8) 7570169689Skanv2q15 __builtin_mips_preceu_ph_qbl (v4i8) 7571169689Skanv2q15 __builtin_mips_preceu_ph_qbr (v4i8) 7572169689Skanv2q15 __builtin_mips_preceu_ph_qbla (v4i8) 7573169689Skanv2q15 __builtin_mips_preceu_ph_qbra (v4i8) 7574169689Skanv4i8 __builtin_mips_shll_qb (v4i8, imm0_7) 7575169689Skanv4i8 __builtin_mips_shll_qb (v4i8, i32) 7576169689Skanv2q15 __builtin_mips_shll_ph (v2q15, imm0_15) 7577169689Skanv2q15 __builtin_mips_shll_ph (v2q15, i32) 7578169689Skanv2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) 7579169689Skanv2q15 __builtin_mips_shll_s_ph (v2q15, i32) 7580169689Skanq31 __builtin_mips_shll_s_w (q31, imm0_31) 7581169689Skanq31 __builtin_mips_shll_s_w (q31, i32) 7582169689Skanv4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) 7583169689Skanv4i8 __builtin_mips_shrl_qb (v4i8, i32) 7584169689Skanv2q15 __builtin_mips_shra_ph (v2q15, imm0_15) 7585169689Skanv2q15 __builtin_mips_shra_ph (v2q15, i32) 7586169689Skanv2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) 7587169689Skanv2q15 __builtin_mips_shra_r_ph (v2q15, i32) 7588169689Skanq31 __builtin_mips_shra_r_w (q31, imm0_31) 7589169689Skanq31 __builtin_mips_shra_r_w (q31, i32) 7590169689Skanv2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) 7591169689Skanv2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) 7592169689Skanv2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) 7593169689Skanq31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) 7594169689Skanq31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) 7595169689Skana64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) 7596169689Skana64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) 7597169689Skana64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) 7598169689Skana64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) 7599169689Skana64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) 7600169689Skana64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) 7601169689Skana64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) 7602169689Skana64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) 7603169689Skana64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) 7604169689Skana64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) 7605169689Skana64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) 7606169689Skana64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) 7607169689Skana64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) 7608169689Skani32 __builtin_mips_bitrev (i32) 7609169689Skani32 __builtin_mips_insv (i32, i32) 7610169689Skanv4i8 __builtin_mips_repl_qb (imm0_255) 7611169689Skanv4i8 __builtin_mips_repl_qb (i32) 7612169689Skanv2q15 __builtin_mips_repl_ph (imm_n512_511) 7613169689Skanv2q15 __builtin_mips_repl_ph (i32) 7614169689Skanvoid __builtin_mips_cmpu_eq_qb (v4i8, v4i8) 7615169689Skanvoid __builtin_mips_cmpu_lt_qb (v4i8, v4i8) 7616169689Skanvoid __builtin_mips_cmpu_le_qb (v4i8, v4i8) 7617169689Skani32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) 7618169689Skani32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) 7619169689Skani32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) 7620169689Skanvoid __builtin_mips_cmp_eq_ph (v2q15, v2q15) 7621169689Skanvoid __builtin_mips_cmp_lt_ph (v2q15, v2q15) 7622169689Skanvoid __builtin_mips_cmp_le_ph (v2q15, v2q15) 7623169689Skanv4i8 __builtin_mips_pick_qb (v4i8, v4i8) 7624169689Skanv2q15 __builtin_mips_pick_ph (v2q15, v2q15) 7625169689Skanv2q15 __builtin_mips_packrl_ph (v2q15, v2q15) 7626169689Skani32 __builtin_mips_extr_w (a64, imm0_31) 7627169689Skani32 __builtin_mips_extr_w (a64, i32) 7628169689Skani32 __builtin_mips_extr_r_w (a64, imm0_31) 7629169689Skani32 __builtin_mips_extr_s_h (a64, i32) 7630169689Skani32 __builtin_mips_extr_rs_w (a64, imm0_31) 7631169689Skani32 __builtin_mips_extr_rs_w (a64, i32) 7632169689Skani32 __builtin_mips_extr_s_h (a64, imm0_31) 7633169689Skani32 __builtin_mips_extr_r_w (a64, i32) 7634169689Skani32 __builtin_mips_extp (a64, imm0_31) 7635169689Skani32 __builtin_mips_extp (a64, i32) 7636169689Skani32 __builtin_mips_extpdp (a64, imm0_31) 7637169689Skani32 __builtin_mips_extpdp (a64, i32) 7638169689Skana64 __builtin_mips_shilo (a64, imm_n32_31) 7639169689Skana64 __builtin_mips_shilo (a64, i32) 7640169689Skana64 __builtin_mips_mthlip (a64, i32) 7641169689Skanvoid __builtin_mips_wrdsp (i32, imm0_63) 7642169689Skani32 __builtin_mips_rddsp (imm0_63) 7643169689Skani32 __builtin_mips_lbux (void *, i32) 7644169689Skani32 __builtin_mips_lhx (void *, i32) 7645169689Skani32 __builtin_mips_lwx (void *, i32) 7646169689Skani32 __builtin_mips_bposge32 (void) 7647169689Skan@end smallexample 7648169689Skan 7649169689Skan@node MIPS Paired-Single Support 7650169689Skan@subsection MIPS Paired-Single Support 7651169689Skan 7652169689SkanThe MIPS64 architecture includes a number of instructions that 7653169689Skanoperate on pairs of single-precision floating-point values. 7654169689SkanEach pair is packed into a 64-bit floating-point register, 7655169689Skanwith one element being designated the ``upper half'' and 7656169689Skanthe other being designated the ``lower half''. 7657169689Skan 7658169689SkanGCC supports paired-single operations using both the generic 7659169689Skanvector extensions (@pxref{Vector Extensions}) and a collection of 7660169689SkanMIPS-specific built-in functions. Both kinds of support are 7661169689Skanenabled by the @option{-mpaired-single} command-line option. 7662169689Skan 7663169689SkanThe vector type associated with paired-single values is usually 7664169689Skancalled @code{v2sf}. It can be defined in C as follows: 7665169689Skan 7666169689Skan@smallexample 7667169689Skantypedef float v2sf __attribute__ ((vector_size (8))); 7668169689Skan@end smallexample 7669169689Skan 7670169689Skan@code{v2sf} values are initialized in the same way as aggregates. 7671169689SkanFor example: 7672169689Skan 7673169689Skan@smallexample 7674169689Skanv2sf a = @{1.5, 9.1@}; 7675169689Skanv2sf b; 7676169689Skanfloat e, f; 7677169689Skanb = (v2sf) @{e, f@}; 7678169689Skan@end smallexample 7679169689Skan 7680169689Skan@emph{Note:} The CPU's endianness determines which value is stored in 7681169689Skanthe upper half of a register and which value is stored in the lower half. 7682169689SkanOn little-endian targets, the first value is the lower one and the second 7683169689Skanvalue is the upper one. The opposite order applies to big-endian targets. 7684169689SkanFor example, the code above will set the lower half of @code{a} to 7685169689Skan@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. 7686169689Skan 7687169689Skan@menu 7688169689Skan* Paired-Single Arithmetic:: 7689169689Skan* Paired-Single Built-in Functions:: 7690169689Skan* MIPS-3D Built-in Functions:: 7691169689Skan@end menu 7692169689Skan 7693169689Skan@node Paired-Single Arithmetic 7694169689Skan@subsubsection Paired-Single Arithmetic 7695169689Skan 7696169689SkanThe table below lists the @code{v2sf} operations for which hardware 7697169689Skansupport exists. @code{a}, @code{b} and @code{c} are @code{v2sf} 7698169689Skanvalues and @code{x} is an integral value. 7699169689Skan 7700169689Skan@multitable @columnfractions .50 .50 7701169689Skan@item C code @tab MIPS instruction 7702169689Skan@item @code{a + b} @tab @code{add.ps} 7703169689Skan@item @code{a - b} @tab @code{sub.ps} 7704169689Skan@item @code{-a} @tab @code{neg.ps} 7705169689Skan@item @code{a * b} @tab @code{mul.ps} 7706169689Skan@item @code{a * b + c} @tab @code{madd.ps} 7707169689Skan@item @code{a * b - c} @tab @code{msub.ps} 7708169689Skan@item @code{-(a * b + c)} @tab @code{nmadd.ps} 7709169689Skan@item @code{-(a * b - c)} @tab @code{nmsub.ps} 7710169689Skan@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} 7711169689Skan@end multitable 7712169689Skan 7713169689SkanNote that the multiply-accumulate instructions can be disabled 7714169689Skanusing the command-line option @code{-mno-fused-madd}. 7715169689Skan 7716169689Skan@node Paired-Single Built-in Functions 7717169689Skan@subsubsection Paired-Single Built-in Functions 7718169689Skan 7719169689SkanThe following paired-single functions map directly to a particular 7720169689SkanMIPS instruction. Please refer to the architecture specification 7721169689Skanfor details on what each instruction does. 7722169689Skan 7723169689Skan@table @code 7724169689Skan@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) 7725169689SkanPair lower lower (@code{pll.ps}). 7726169689Skan 7727169689Skan@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) 7728169689SkanPair upper lower (@code{pul.ps}). 7729169689Skan 7730169689Skan@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) 7731169689SkanPair lower upper (@code{plu.ps}). 7732169689Skan 7733169689Skan@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) 7734169689SkanPair upper upper (@code{puu.ps}). 7735169689Skan 7736169689Skan@item v2sf __builtin_mips_cvt_ps_s (float, float) 7737169689SkanConvert pair to paired single (@code{cvt.ps.s}). 7738169689Skan 7739169689Skan@item float __builtin_mips_cvt_s_pl (v2sf) 7740169689SkanConvert pair lower to single (@code{cvt.s.pl}). 7741169689Skan 7742169689Skan@item float __builtin_mips_cvt_s_pu (v2sf) 7743169689SkanConvert pair upper to single (@code{cvt.s.pu}). 7744169689Skan 7745169689Skan@item v2sf __builtin_mips_abs_ps (v2sf) 7746169689SkanAbsolute value (@code{abs.ps}). 7747169689Skan 7748169689Skan@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) 7749169689SkanAlign variable (@code{alnv.ps}). 7750169689Skan 7751169689Skan@emph{Note:} The value of the third parameter must be 0 or 4 7752169689Skanmodulo 8, otherwise the result will be unpredictable. Please read the 7753169689Skaninstruction description for details. 7754169689Skan@end table 7755169689Skan 7756169689SkanThe following multi-instruction functions are also available. 7757169689SkanIn each case, @var{cond} can be any of the 16 floating-point conditions: 7758169689Skan@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 7759169689Skan@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, 7760169689Skan@code{lt}, @code{nge}, @code{le} or @code{ngt}. 7761169689Skan 7762169689Skan@table @code 7763169689Skan@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7764169689Skan@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7765169689SkanConditional move based on floating point comparison (@code{c.@var{cond}.ps}, 7766169689Skan@code{movt.ps}/@code{movf.ps}). 7767169689Skan 7768169689SkanThe @code{movt} functions return the value @var{x} computed by: 7769169689Skan 7770169689Skan@smallexample 7771169689Skanc.@var{cond}.ps @var{cc},@var{a},@var{b} 7772169689Skanmov.ps @var{x},@var{c} 7773169689Skanmovt.ps @var{x},@var{d},@var{cc} 7774169689Skan@end smallexample 7775169689Skan 7776169689SkanThe @code{movf} functions are similar but use @code{movf.ps} instead 7777169689Skanof @code{movt.ps}. 7778169689Skan 7779169689Skan@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7780169689Skan@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7781169689SkanComparison of two paired-single values (@code{c.@var{cond}.ps}, 7782169689Skan@code{bc1t}/@code{bc1f}). 7783169689Skan 7784169689SkanThese functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 7785169689Skanand return either the upper or lower half of the result. For example: 7786169689Skan 7787169689Skan@smallexample 7788169689Skanv2sf a, b; 7789169689Skanif (__builtin_mips_upper_c_eq_ps (a, b)) 7790169689Skan upper_halves_are_equal (); 7791169689Skanelse 7792169689Skan upper_halves_are_unequal (); 7793169689Skan 7794169689Skanif (__builtin_mips_lower_c_eq_ps (a, b)) 7795169689Skan lower_halves_are_equal (); 7796169689Skanelse 7797169689Skan lower_halves_are_unequal (); 7798169689Skan@end smallexample 7799169689Skan@end table 7800169689Skan 7801169689Skan@node MIPS-3D Built-in Functions 7802169689Skan@subsubsection MIPS-3D Built-in Functions 7803169689Skan 7804169689SkanThe MIPS-3D Application-Specific Extension (ASE) includes additional 7805169689Skanpaired-single instructions that are designed to improve the performance 7806169689Skanof 3D graphics operations. Support for these instructions is controlled 7807169689Skanby the @option{-mips3d} command-line option. 7808169689Skan 7809169689SkanThe functions listed below map directly to a particular MIPS-3D 7810169689Skaninstruction. Please refer to the architecture specification for 7811169689Skanmore details on what each instruction does. 7812169689Skan 7813169689Skan@table @code 7814169689Skan@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) 7815169689SkanReduction add (@code{addr.ps}). 7816169689Skan 7817169689Skan@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) 7818169689SkanReduction multiply (@code{mulr.ps}). 7819169689Skan 7820169689Skan@item v2sf __builtin_mips_cvt_pw_ps (v2sf) 7821169689SkanConvert paired single to paired word (@code{cvt.pw.ps}). 7822169689Skan 7823169689Skan@item v2sf __builtin_mips_cvt_ps_pw (v2sf) 7824169689SkanConvert paired word to paired single (@code{cvt.ps.pw}). 7825169689Skan 7826169689Skan@item float __builtin_mips_recip1_s (float) 7827169689Skan@itemx double __builtin_mips_recip1_d (double) 7828169689Skan@itemx v2sf __builtin_mips_recip1_ps (v2sf) 7829169689SkanReduced precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). 7830169689Skan 7831169689Skan@item float __builtin_mips_recip2_s (float, float) 7832169689Skan@itemx double __builtin_mips_recip2_d (double, double) 7833169689Skan@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) 7834169689SkanReduced precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). 7835169689Skan 7836169689Skan@item float __builtin_mips_rsqrt1_s (float) 7837169689Skan@itemx double __builtin_mips_rsqrt1_d (double) 7838169689Skan@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) 7839169689SkanReduced precision reciprocal square root (sequence step 1) 7840169689Skan(@code{rsqrt1.@var{fmt}}). 7841169689Skan 7842169689Skan@item float __builtin_mips_rsqrt2_s (float, float) 7843169689Skan@itemx double __builtin_mips_rsqrt2_d (double, double) 7844169689Skan@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) 7845169689SkanReduced precision reciprocal square root (sequence step 2) 7846169689Skan(@code{rsqrt2.@var{fmt}}). 7847169689Skan@end table 7848169689Skan 7849169689SkanThe following multi-instruction functions are also available. 7850169689SkanIn each case, @var{cond} can be any of the 16 floating-point conditions: 7851169689Skan@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 7852169689Skan@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 7853169689Skan@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. 7854169689Skan 7855169689Skan@table @code 7856169689Skan@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) 7857169689Skan@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) 7858169689SkanAbsolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, 7859169689Skan@code{bc1t}/@code{bc1f}). 7860169689Skan 7861169689SkanThese functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} 7862169689Skanor @code{cabs.@var{cond}.d} and return the result as a boolean value. 7863169689SkanFor example: 7864169689Skan 7865169689Skan@smallexample 7866169689Skanfloat a, b; 7867169689Skanif (__builtin_mips_cabs_eq_s (a, b)) 7868169689Skan true (); 7869169689Skanelse 7870169689Skan false (); 7871169689Skan@end smallexample 7872169689Skan 7873169689Skan@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7874169689Skan@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7875169689SkanAbsolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, 7876169689Skan@code{bc1t}/@code{bc1f}). 7877169689Skan 7878169689SkanThese functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} 7879169689Skanand return either the upper or lower half of the result. For example: 7880169689Skan 7881169689Skan@smallexample 7882169689Skanv2sf a, b; 7883169689Skanif (__builtin_mips_upper_cabs_eq_ps (a, b)) 7884169689Skan upper_halves_are_equal (); 7885169689Skanelse 7886169689Skan upper_halves_are_unequal (); 7887169689Skan 7888169689Skanif (__builtin_mips_lower_cabs_eq_ps (a, b)) 7889169689Skan lower_halves_are_equal (); 7890169689Skanelse 7891169689Skan lower_halves_are_unequal (); 7892169689Skan@end smallexample 7893169689Skan 7894169689Skan@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7895169689Skan@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7896169689SkanConditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, 7897169689Skan@code{movt.ps}/@code{movf.ps}). 7898169689Skan 7899169689SkanThe @code{movt} functions return the value @var{x} computed by: 7900169689Skan 7901169689Skan@smallexample 7902169689Skancabs.@var{cond}.ps @var{cc},@var{a},@var{b} 7903169689Skanmov.ps @var{x},@var{c} 7904169689Skanmovt.ps @var{x},@var{d},@var{cc} 7905169689Skan@end smallexample 7906169689Skan 7907169689SkanThe @code{movf} functions are similar but use @code{movf.ps} instead 7908169689Skanof @code{movt.ps}. 7909169689Skan 7910169689Skan@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7911169689Skan@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7912169689Skan@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7913169689Skan@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 7914169689SkanComparison of two paired-single values 7915169689Skan(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 7916169689Skan@code{bc1any2t}/@code{bc1any2f}). 7917169689Skan 7918169689SkanThese functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 7919169689Skanor @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either 7920169689Skanresult is true and the @code{all} forms return true if both results are true. 7921169689SkanFor example: 7922169689Skan 7923169689Skan@smallexample 7924169689Skanv2sf a, b; 7925169689Skanif (__builtin_mips_any_c_eq_ps (a, b)) 7926169689Skan one_is_true (); 7927169689Skanelse 7928169689Skan both_are_false (); 7929169689Skan 7930169689Skanif (__builtin_mips_all_c_eq_ps (a, b)) 7931169689Skan both_are_true (); 7932169689Skanelse 7933169689Skan one_is_false (); 7934169689Skan@end smallexample 7935169689Skan 7936169689Skan@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7937169689Skan@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7938169689Skan@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7939169689Skan@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 7940169689SkanComparison of four paired-single values 7941169689Skan(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 7942169689Skan@code{bc1any4t}/@code{bc1any4f}). 7943169689Skan 7944169689SkanThese functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} 7945169689Skanto compare @var{a} with @var{b} and to compare @var{c} with @var{d}. 7946169689SkanThe @code{any} forms return true if any of the four results are true 7947169689Skanand the @code{all} forms return true if all four results are true. 7948169689SkanFor example: 7949169689Skan 7950169689Skan@smallexample 7951169689Skanv2sf a, b, c, d; 7952169689Skanif (__builtin_mips_any_c_eq_4s (a, b, c, d)) 7953169689Skan some_are_true (); 7954169689Skanelse 7955169689Skan all_are_false (); 7956169689Skan 7957169689Skanif (__builtin_mips_all_c_eq_4s (a, b, c, d)) 7958169689Skan all_are_true (); 7959169689Skanelse 7960169689Skan some_are_false (); 7961169689Skan@end smallexample 7962169689Skan@end table 7963169689Skan 796490075Sobrien@node PowerPC AltiVec Built-in Functions 796590075Sobrien@subsection PowerPC AltiVec Built-in Functions 796690075Sobrien 7967146895SkanGCC provides an interface for the PowerPC family of processors to access 7968146895Skanthe AltiVec operations described in Motorola's AltiVec Programming 7969146895SkanInterface Manual. The interface is made available by including 7970146895Skan@code{<altivec.h>} and using @option{-maltivec} and 7971146895Skan@option{-mabi=altivec}. The interface supports the following vector 7972146895Skantypes. 797390075Sobrien 7974146895Skan@smallexample 7975146895Skanvector unsigned char 7976146895Skanvector signed char 7977146895Skanvector bool char 797890075Sobrien 7979146895Skanvector unsigned short 7980146895Skanvector signed short 7981146895Skanvector bool short 7982146895Skanvector pixel 798390075Sobrien 7984146895Skanvector unsigned int 7985146895Skanvector signed int 7986146895Skanvector bool int 7987146895Skanvector float 7988146895Skan@end smallexample 7989117395Skan 7990146895SkanGCC's implementation of the high-level language interface available from 7991146895SkanC and C++ code differs from Motorola's documentation in several ways. 7992146895Skan 7993146895Skan@itemize @bullet 7994146895Skan 7995146895Skan@item 7996146895SkanA vector constant is a list of constant expressions within curly braces. 7997146895Skan 7998146895Skan@item 7999146895SkanA vector initializer requires no cast if the vector constant is of the 8000146895Skansame type as the variable it is initializing. 8001146895Skan 8002146895Skan@item 8003169689SkanIf @code{signed} or @code{unsigned} is omitted, the signedness of the 8004169689Skanvector type is the default signedness of the base type. The default 8005169689Skanvaries depending on the operating system, so a portable program should 8006169689Skanalways specify the signedness. 8007169689Skan 8008146895Skan@item 8009146895SkanCompiling with @option{-maltivec} adds keywords @code{__vector}, 8010146895Skan@code{__pixel}, and @code{__bool}. Macros @option{vector}, 8011146895Skan@code{pixel}, and @code{bool} are defined in @code{<altivec.h>} and can 8012146895Skanbe undefined. 8013169689Skan 8014146895Skan@item 8015146895SkanGCC allows using a @code{typedef} name as the type specifier for a 8016146895Skanvector type. 8017146895Skan 8018146895Skan@item 8019146895SkanFor C, overloaded functions are implemented with macros so the following 8020146895Skandoes not work: 8021146895Skan 8022117395Skan@smallexample 8023117395Skan vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); 8024117395Skan@end smallexample 8025117395Skan 8026146895SkanSince @code{vec_add} is a macro, the vector constant in the example 8027146895Skanis treated as four separate arguments. Wrap the entire argument in 8028146895Skanparentheses for this to work. 8029146895Skan@end itemize 8030117395Skan 803196263Sobrien@emph{Note:} Only the @code{<altivec.h>} interface is supported. 803296263SobrienInternally, GCC uses built-in functions to achieve the functionality in 803396263Sobrienthe aforementioned header file, but they are not supported and are 803496263Sobriensubject to change without notice. 803596263Sobrien 8036146895SkanThe following interfaces are supported for the generic and specific 8037146895SkanAltiVec operations and the AltiVec predicates. In cases where there 8038146895Skanis a direct mapping between generic and specific operations, only the 8039146895Skangeneric names are shown here, although the specific operations can also 8040146895Skanbe used. 8041146895Skan 8042146895SkanArguments that are documented as @code{const int} require literal 8043146895Skanintegral values within the range required for that operation. 8044146895Skan 804590075Sobrien@smallexample 8046146895Skanvector signed char vec_abs (vector signed char); 8047146895Skanvector signed short vec_abs (vector signed short); 8048146895Skanvector signed int vec_abs (vector signed int); 8049146895Skanvector float vec_abs (vector float); 805090075Sobrien 8051146895Skanvector signed char vec_abss (vector signed char); 8052146895Skanvector signed short vec_abss (vector signed short); 8053146895Skanvector signed int vec_abss (vector signed int); 805490075Sobrien 8055146895Skanvector signed char vec_add (vector bool char, vector signed char); 8056146895Skanvector signed char vec_add (vector signed char, vector bool char); 805790075Sobrienvector signed char vec_add (vector signed char, vector signed char); 8058146895Skanvector unsigned char vec_add (vector bool char, vector unsigned char); 8059146895Skanvector unsigned char vec_add (vector unsigned char, vector bool char); 806096263Sobrienvector unsigned char vec_add (vector unsigned char, 806196263Sobrien vector unsigned char); 8062146895Skanvector signed short vec_add (vector bool short, vector signed short); 8063146895Skanvector signed short vec_add (vector signed short, vector bool short); 806490075Sobrienvector signed short vec_add (vector signed short, vector signed short); 8065146895Skanvector unsigned short vec_add (vector bool short, 806696263Sobrien vector unsigned short); 806796263Sobrienvector unsigned short vec_add (vector unsigned short, 8068146895Skan vector bool short); 806996263Sobrienvector unsigned short vec_add (vector unsigned short, 807096263Sobrien vector unsigned short); 8071146895Skanvector signed int vec_add (vector bool int, vector signed int); 8072146895Skanvector signed int vec_add (vector signed int, vector bool int); 807390075Sobrienvector signed int vec_add (vector signed int, vector signed int); 8074146895Skanvector unsigned int vec_add (vector bool int, vector unsigned int); 8075146895Skanvector unsigned int vec_add (vector unsigned int, vector bool int); 807690075Sobrienvector unsigned int vec_add (vector unsigned int, vector unsigned int); 807790075Sobrienvector float vec_add (vector float, vector float); 807890075Sobrien 8079146895Skanvector float vec_vaddfp (vector float, vector float); 8080146895Skan 8081146895Skanvector signed int vec_vadduwm (vector bool int, vector signed int); 8082146895Skanvector signed int vec_vadduwm (vector signed int, vector bool int); 8083146895Skanvector signed int vec_vadduwm (vector signed int, vector signed int); 8084146895Skanvector unsigned int vec_vadduwm (vector bool int, vector unsigned int); 8085146895Skanvector unsigned int vec_vadduwm (vector unsigned int, vector bool int); 8086146895Skanvector unsigned int vec_vadduwm (vector unsigned int, 8087146895Skan vector unsigned int); 8088146895Skan 8089146895Skanvector signed short vec_vadduhm (vector bool short, 8090146895Skan vector signed short); 8091146895Skanvector signed short vec_vadduhm (vector signed short, 8092146895Skan vector bool short); 8093146895Skanvector signed short vec_vadduhm (vector signed short, 8094146895Skan vector signed short); 8095146895Skanvector unsigned short vec_vadduhm (vector bool short, 8096146895Skan vector unsigned short); 8097146895Skanvector unsigned short vec_vadduhm (vector unsigned short, 8098146895Skan vector bool short); 8099146895Skanvector unsigned short vec_vadduhm (vector unsigned short, 8100146895Skan vector unsigned short); 8101146895Skan 8102146895Skanvector signed char vec_vaddubm (vector bool char, vector signed char); 8103146895Skanvector signed char vec_vaddubm (vector signed char, vector bool char); 8104146895Skanvector signed char vec_vaddubm (vector signed char, vector signed char); 8105146895Skanvector unsigned char vec_vaddubm (vector bool char, 8106146895Skan vector unsigned char); 8107146895Skanvector unsigned char vec_vaddubm (vector unsigned char, 8108146895Skan vector bool char); 8109146895Skanvector unsigned char vec_vaddubm (vector unsigned char, 8110146895Skan vector unsigned char); 8111146895Skan 811290075Sobrienvector unsigned int vec_addc (vector unsigned int, vector unsigned int); 811390075Sobrien 8114146895Skanvector unsigned char vec_adds (vector bool char, vector unsigned char); 8115146895Skanvector unsigned char vec_adds (vector unsigned char, vector bool char); 811696263Sobrienvector unsigned char vec_adds (vector unsigned char, 811796263Sobrien vector unsigned char); 8118146895Skanvector signed char vec_adds (vector bool char, vector signed char); 8119146895Skanvector signed char vec_adds (vector signed char, vector bool char); 812090075Sobrienvector signed char vec_adds (vector signed char, vector signed char); 8121146895Skanvector unsigned short vec_adds (vector bool short, 812296263Sobrien vector unsigned short); 812396263Sobrienvector unsigned short vec_adds (vector unsigned short, 8124146895Skan vector bool short); 812596263Sobrienvector unsigned short vec_adds (vector unsigned short, 812696263Sobrien vector unsigned short); 8127146895Skanvector signed short vec_adds (vector bool short, vector signed short); 8128146895Skanvector signed short vec_adds (vector signed short, vector bool short); 812990075Sobrienvector signed short vec_adds (vector signed short, vector signed short); 8130146895Skanvector unsigned int vec_adds (vector bool int, vector unsigned int); 8131146895Skanvector unsigned int vec_adds (vector unsigned int, vector bool int); 813290075Sobrienvector unsigned int vec_adds (vector unsigned int, vector unsigned int); 8133146895Skanvector signed int vec_adds (vector bool int, vector signed int); 8134146895Skanvector signed int vec_adds (vector signed int, vector bool int); 813590075Sobrienvector signed int vec_adds (vector signed int, vector signed int); 813690075Sobrien 8137146895Skanvector signed int vec_vaddsws (vector bool int, vector signed int); 8138146895Skanvector signed int vec_vaddsws (vector signed int, vector bool int); 8139146895Skanvector signed int vec_vaddsws (vector signed int, vector signed int); 8140146895Skan 8141146895Skanvector unsigned int vec_vadduws (vector bool int, vector unsigned int); 8142146895Skanvector unsigned int vec_vadduws (vector unsigned int, vector bool int); 8143146895Skanvector unsigned int vec_vadduws (vector unsigned int, 8144146895Skan vector unsigned int); 8145146895Skan 8146146895Skanvector signed short vec_vaddshs (vector bool short, 8147146895Skan vector signed short); 8148146895Skanvector signed short vec_vaddshs (vector signed short, 8149146895Skan vector bool short); 8150146895Skanvector signed short vec_vaddshs (vector signed short, 8151146895Skan vector signed short); 8152146895Skan 8153146895Skanvector unsigned short vec_vadduhs (vector bool short, 8154146895Skan vector unsigned short); 8155146895Skanvector unsigned short vec_vadduhs (vector unsigned short, 8156146895Skan vector bool short); 8157146895Skanvector unsigned short vec_vadduhs (vector unsigned short, 8158146895Skan vector unsigned short); 8159146895Skan 8160146895Skanvector signed char vec_vaddsbs (vector bool char, vector signed char); 8161146895Skanvector signed char vec_vaddsbs (vector signed char, vector bool char); 8162146895Skanvector signed char vec_vaddsbs (vector signed char, vector signed char); 8163146895Skan 8164146895Skanvector unsigned char vec_vaddubs (vector bool char, 8165146895Skan vector unsigned char); 8166146895Skanvector unsigned char vec_vaddubs (vector unsigned char, 8167146895Skan vector bool char); 8168146895Skanvector unsigned char vec_vaddubs (vector unsigned char, 8169146895Skan vector unsigned char); 8170146895Skan 817190075Sobrienvector float vec_and (vector float, vector float); 8172146895Skanvector float vec_and (vector float, vector bool int); 8173146895Skanvector float vec_and (vector bool int, vector float); 8174146895Skanvector bool int vec_and (vector bool int, vector bool int); 8175146895Skanvector signed int vec_and (vector bool int, vector signed int); 8176146895Skanvector signed int vec_and (vector signed int, vector bool int); 817790075Sobrienvector signed int vec_and (vector signed int, vector signed int); 8178146895Skanvector unsigned int vec_and (vector bool int, vector unsigned int); 8179146895Skanvector unsigned int vec_and (vector unsigned int, vector bool int); 818090075Sobrienvector unsigned int vec_and (vector unsigned int, vector unsigned int); 8181146895Skanvector bool short vec_and (vector bool short, vector bool short); 8182146895Skanvector signed short vec_and (vector bool short, vector signed short); 8183146895Skanvector signed short vec_and (vector signed short, vector bool short); 818490075Sobrienvector signed short vec_and (vector signed short, vector signed short); 8185146895Skanvector unsigned short vec_and (vector bool short, 818696263Sobrien vector unsigned short); 818796263Sobrienvector unsigned short vec_and (vector unsigned short, 8188146895Skan vector bool short); 818996263Sobrienvector unsigned short vec_and (vector unsigned short, 819096263Sobrien vector unsigned short); 8191146895Skanvector signed char vec_and (vector bool char, vector signed char); 8192146895Skanvector bool char vec_and (vector bool char, vector bool char); 8193146895Skanvector signed char vec_and (vector signed char, vector bool char); 819490075Sobrienvector signed char vec_and (vector signed char, vector signed char); 8195146895Skanvector unsigned char vec_and (vector bool char, vector unsigned char); 8196146895Skanvector unsigned char vec_and (vector unsigned char, vector bool char); 819796263Sobrienvector unsigned char vec_and (vector unsigned char, 819896263Sobrien vector unsigned char); 819990075Sobrien 820090075Sobrienvector float vec_andc (vector float, vector float); 8201146895Skanvector float vec_andc (vector float, vector bool int); 8202146895Skanvector float vec_andc (vector bool int, vector float); 8203146895Skanvector bool int vec_andc (vector bool int, vector bool int); 8204146895Skanvector signed int vec_andc (vector bool int, vector signed int); 8205146895Skanvector signed int vec_andc (vector signed int, vector bool int); 820690075Sobrienvector signed int vec_andc (vector signed int, vector signed int); 8207146895Skanvector unsigned int vec_andc (vector bool int, vector unsigned int); 8208146895Skanvector unsigned int vec_andc (vector unsigned int, vector bool int); 820990075Sobrienvector unsigned int vec_andc (vector unsigned int, vector unsigned int); 8210146895Skanvector bool short vec_andc (vector bool short, vector bool short); 8211146895Skanvector signed short vec_andc (vector bool short, vector signed short); 8212146895Skanvector signed short vec_andc (vector signed short, vector bool short); 821390075Sobrienvector signed short vec_andc (vector signed short, vector signed short); 8214146895Skanvector unsigned short vec_andc (vector bool short, 821596263Sobrien vector unsigned short); 821696263Sobrienvector unsigned short vec_andc (vector unsigned short, 8217146895Skan vector bool short); 821896263Sobrienvector unsigned short vec_andc (vector unsigned short, 821996263Sobrien vector unsigned short); 8220146895Skanvector signed char vec_andc (vector bool char, vector signed char); 8221146895Skanvector bool char vec_andc (vector bool char, vector bool char); 8222146895Skanvector signed char vec_andc (vector signed char, vector bool char); 822390075Sobrienvector signed char vec_andc (vector signed char, vector signed char); 8224146895Skanvector unsigned char vec_andc (vector bool char, vector unsigned char); 8225146895Skanvector unsigned char vec_andc (vector unsigned char, vector bool char); 822696263Sobrienvector unsigned char vec_andc (vector unsigned char, 822796263Sobrien vector unsigned char); 822890075Sobrien 822996263Sobrienvector unsigned char vec_avg (vector unsigned char, 823096263Sobrien vector unsigned char); 823190075Sobrienvector signed char vec_avg (vector signed char, vector signed char); 823296263Sobrienvector unsigned short vec_avg (vector unsigned short, 823396263Sobrien vector unsigned short); 823490075Sobrienvector signed short vec_avg (vector signed short, vector signed short); 823590075Sobrienvector unsigned int vec_avg (vector unsigned int, vector unsigned int); 823690075Sobrienvector signed int vec_avg (vector signed int, vector signed int); 823790075Sobrien 8238146895Skanvector signed int vec_vavgsw (vector signed int, vector signed int); 8239146895Skan 8240146895Skanvector unsigned int vec_vavguw (vector unsigned int, 8241146895Skan vector unsigned int); 8242146895Skan 8243146895Skanvector signed short vec_vavgsh (vector signed short, 8244146895Skan vector signed short); 8245146895Skan 8246146895Skanvector unsigned short vec_vavguh (vector unsigned short, 8247146895Skan vector unsigned short); 8248146895Skan 8249146895Skanvector signed char vec_vavgsb (vector signed char, vector signed char); 8250146895Skan 8251146895Skanvector unsigned char vec_vavgub (vector unsigned char, 8252146895Skan vector unsigned char); 8253146895Skan 825490075Sobrienvector float vec_ceil (vector float); 825590075Sobrien 825690075Sobrienvector signed int vec_cmpb (vector float, vector float); 825790075Sobrien 8258146895Skanvector bool char vec_cmpeq (vector signed char, vector signed char); 8259146895Skanvector bool char vec_cmpeq (vector unsigned char, vector unsigned char); 8260146895Skanvector bool short vec_cmpeq (vector signed short, vector signed short); 8261146895Skanvector bool short vec_cmpeq (vector unsigned short, 8262146895Skan vector unsigned short); 8263146895Skanvector bool int vec_cmpeq (vector signed int, vector signed int); 8264146895Skanvector bool int vec_cmpeq (vector unsigned int, vector unsigned int); 8265146895Skanvector bool int vec_cmpeq (vector float, vector float); 826690075Sobrien 8267146895Skanvector bool int vec_vcmpeqfp (vector float, vector float); 826890075Sobrien 8269146895Skanvector bool int vec_vcmpequw (vector signed int, vector signed int); 8270146895Skanvector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); 827190075Sobrien 8272146895Skanvector bool short vec_vcmpequh (vector signed short, 8273146895Skan vector signed short); 8274146895Skanvector bool short vec_vcmpequh (vector unsigned short, 8275146895Skan vector unsigned short); 827690075Sobrien 8277146895Skanvector bool char vec_vcmpequb (vector signed char, vector signed char); 8278146895Skanvector bool char vec_vcmpequb (vector unsigned char, 8279146895Skan vector unsigned char); 828090075Sobrien 8281146895Skanvector bool int vec_cmpge (vector float, vector float); 828290075Sobrien 8283146895Skanvector bool char vec_cmpgt (vector unsigned char, vector unsigned char); 8284146895Skanvector bool char vec_cmpgt (vector signed char, vector signed char); 8285146895Skanvector bool short vec_cmpgt (vector unsigned short, 8286146895Skan vector unsigned short); 8287146895Skanvector bool short vec_cmpgt (vector signed short, vector signed short); 8288146895Skanvector bool int vec_cmpgt (vector unsigned int, vector unsigned int); 8289146895Skanvector bool int vec_cmpgt (vector signed int, vector signed int); 8290146895Skanvector bool int vec_cmpgt (vector float, vector float); 829190075Sobrien 8292146895Skanvector bool int vec_vcmpgtfp (vector float, vector float); 829390075Sobrien 8294146895Skanvector bool int vec_vcmpgtsw (vector signed int, vector signed int); 829590075Sobrien 8296146895Skanvector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); 8297146895Skan 8298146895Skanvector bool short vec_vcmpgtsh (vector signed short, 8299146895Skan vector signed short); 8300146895Skan 8301146895Skanvector bool short vec_vcmpgtuh (vector unsigned short, 8302146895Skan vector unsigned short); 8303146895Skan 8304146895Skanvector bool char vec_vcmpgtsb (vector signed char, vector signed char); 8305146895Skan 8306146895Skanvector bool char vec_vcmpgtub (vector unsigned char, 8307146895Skan vector unsigned char); 8308146895Skan 8309146895Skanvector bool int vec_cmple (vector float, vector float); 8310146895Skan 8311146895Skanvector bool char vec_cmplt (vector unsigned char, vector unsigned char); 8312146895Skanvector bool char vec_cmplt (vector signed char, vector signed char); 8313146895Skanvector bool short vec_cmplt (vector unsigned short, 8314146895Skan vector unsigned short); 8315146895Skanvector bool short vec_cmplt (vector signed short, vector signed short); 8316146895Skanvector bool int vec_cmplt (vector unsigned int, vector unsigned int); 8317146895Skanvector bool int vec_cmplt (vector signed int, vector signed int); 8318146895Skanvector bool int vec_cmplt (vector float, vector float); 8319146895Skan 8320146895Skanvector float vec_ctf (vector unsigned int, const int); 8321146895Skanvector float vec_ctf (vector signed int, const int); 8322146895Skan 8323146895Skanvector float vec_vcfsx (vector signed int, const int); 8324146895Skan 8325146895Skanvector float vec_vcfux (vector unsigned int, const int); 8326146895Skan 8327146895Skanvector signed int vec_cts (vector float, const int); 8328146895Skan 8329146895Skanvector unsigned int vec_ctu (vector float, const int); 8330146895Skan 8331146895Skanvoid vec_dss (const int); 8332146895Skan 833390075Sobrienvoid vec_dssall (void); 833490075Sobrien 8335146895Skanvoid vec_dst (const vector unsigned char *, int, const int); 8336146895Skanvoid vec_dst (const vector signed char *, int, const int); 8337146895Skanvoid vec_dst (const vector bool char *, int, const int); 8338146895Skanvoid vec_dst (const vector unsigned short *, int, const int); 8339146895Skanvoid vec_dst (const vector signed short *, int, const int); 8340146895Skanvoid vec_dst (const vector bool short *, int, const int); 8341146895Skanvoid vec_dst (const vector pixel *, int, const int); 8342146895Skanvoid vec_dst (const vector unsigned int *, int, const int); 8343146895Skanvoid vec_dst (const vector signed int *, int, const int); 8344146895Skanvoid vec_dst (const vector bool int *, int, const int); 8345146895Skanvoid vec_dst (const vector float *, int, const int); 8346146895Skanvoid vec_dst (const unsigned char *, int, const int); 8347146895Skanvoid vec_dst (const signed char *, int, const int); 8348146895Skanvoid vec_dst (const unsigned short *, int, const int); 8349146895Skanvoid vec_dst (const short *, int, const int); 8350146895Skanvoid vec_dst (const unsigned int *, int, const int); 8351146895Skanvoid vec_dst (const int *, int, const int); 8352146895Skanvoid vec_dst (const unsigned long *, int, const int); 8353146895Skanvoid vec_dst (const long *, int, const int); 8354146895Skanvoid vec_dst (const float *, int, const int); 835590075Sobrien 8356146895Skanvoid vec_dstst (const vector unsigned char *, int, const int); 8357146895Skanvoid vec_dstst (const vector signed char *, int, const int); 8358146895Skanvoid vec_dstst (const vector bool char *, int, const int); 8359146895Skanvoid vec_dstst (const vector unsigned short *, int, const int); 8360146895Skanvoid vec_dstst (const vector signed short *, int, const int); 8361146895Skanvoid vec_dstst (const vector bool short *, int, const int); 8362146895Skanvoid vec_dstst (const vector pixel *, int, const int); 8363146895Skanvoid vec_dstst (const vector unsigned int *, int, const int); 8364146895Skanvoid vec_dstst (const vector signed int *, int, const int); 8365146895Skanvoid vec_dstst (const vector bool int *, int, const int); 8366146895Skanvoid vec_dstst (const vector float *, int, const int); 8367146895Skanvoid vec_dstst (const unsigned char *, int, const int); 8368146895Skanvoid vec_dstst (const signed char *, int, const int); 8369146895Skanvoid vec_dstst (const unsigned short *, int, const int); 8370146895Skanvoid vec_dstst (const short *, int, const int); 8371146895Skanvoid vec_dstst (const unsigned int *, int, const int); 8372146895Skanvoid vec_dstst (const int *, int, const int); 8373146895Skanvoid vec_dstst (const unsigned long *, int, const int); 8374146895Skanvoid vec_dstst (const long *, int, const int); 8375146895Skanvoid vec_dstst (const float *, int, const int); 837690075Sobrien 8377146895Skanvoid vec_dststt (const vector unsigned char *, int, const int); 8378146895Skanvoid vec_dststt (const vector signed char *, int, const int); 8379146895Skanvoid vec_dststt (const vector bool char *, int, const int); 8380146895Skanvoid vec_dststt (const vector unsigned short *, int, const int); 8381146895Skanvoid vec_dststt (const vector signed short *, int, const int); 8382146895Skanvoid vec_dststt (const vector bool short *, int, const int); 8383146895Skanvoid vec_dststt (const vector pixel *, int, const int); 8384146895Skanvoid vec_dststt (const vector unsigned int *, int, const int); 8385146895Skanvoid vec_dststt (const vector signed int *, int, const int); 8386146895Skanvoid vec_dststt (const vector bool int *, int, const int); 8387146895Skanvoid vec_dststt (const vector float *, int, const int); 8388146895Skanvoid vec_dststt (const unsigned char *, int, const int); 8389146895Skanvoid vec_dststt (const signed char *, int, const int); 8390146895Skanvoid vec_dststt (const unsigned short *, int, const int); 8391146895Skanvoid vec_dststt (const short *, int, const int); 8392146895Skanvoid vec_dststt (const unsigned int *, int, const int); 8393146895Skanvoid vec_dststt (const int *, int, const int); 8394146895Skanvoid vec_dststt (const unsigned long *, int, const int); 8395146895Skanvoid vec_dststt (const long *, int, const int); 8396146895Skanvoid vec_dststt (const float *, int, const int); 839790075Sobrien 8398146895Skanvoid vec_dstt (const vector unsigned char *, int, const int); 8399146895Skanvoid vec_dstt (const vector signed char *, int, const int); 8400146895Skanvoid vec_dstt (const vector bool char *, int, const int); 8401146895Skanvoid vec_dstt (const vector unsigned short *, int, const int); 8402146895Skanvoid vec_dstt (const vector signed short *, int, const int); 8403146895Skanvoid vec_dstt (const vector bool short *, int, const int); 8404146895Skanvoid vec_dstt (const vector pixel *, int, const int); 8405146895Skanvoid vec_dstt (const vector unsigned int *, int, const int); 8406146895Skanvoid vec_dstt (const vector signed int *, int, const int); 8407146895Skanvoid vec_dstt (const vector bool int *, int, const int); 8408146895Skanvoid vec_dstt (const vector float *, int, const int); 8409146895Skanvoid vec_dstt (const unsigned char *, int, const int); 8410146895Skanvoid vec_dstt (const signed char *, int, const int); 8411146895Skanvoid vec_dstt (const unsigned short *, int, const int); 8412146895Skanvoid vec_dstt (const short *, int, const int); 8413146895Skanvoid vec_dstt (const unsigned int *, int, const int); 8414146895Skanvoid vec_dstt (const int *, int, const int); 8415146895Skanvoid vec_dstt (const unsigned long *, int, const int); 8416146895Skanvoid vec_dstt (const long *, int, const int); 8417146895Skanvoid vec_dstt (const float *, int, const int); 841890075Sobrien 8419146895Skanvector float vec_expte (vector float); 842090075Sobrien 8421146895Skanvector float vec_floor (vector float); 842290075Sobrien 8423146895Skanvector float vec_ld (int, const vector float *); 8424146895Skanvector float vec_ld (int, const float *); 8425146895Skanvector bool int vec_ld (int, const vector bool int *); 8426146895Skanvector signed int vec_ld (int, const vector signed int *); 8427146895Skanvector signed int vec_ld (int, const int *); 8428146895Skanvector signed int vec_ld (int, const long *); 8429146895Skanvector unsigned int vec_ld (int, const vector unsigned int *); 8430146895Skanvector unsigned int vec_ld (int, const unsigned int *); 8431146895Skanvector unsigned int vec_ld (int, const unsigned long *); 8432146895Skanvector bool short vec_ld (int, const vector bool short *); 8433146895Skanvector pixel vec_ld (int, const vector pixel *); 8434146895Skanvector signed short vec_ld (int, const vector signed short *); 8435146895Skanvector signed short vec_ld (int, const short *); 8436146895Skanvector unsigned short vec_ld (int, const vector unsigned short *); 8437146895Skanvector unsigned short vec_ld (int, const unsigned short *); 8438146895Skanvector bool char vec_ld (int, const vector bool char *); 8439146895Skanvector signed char vec_ld (int, const vector signed char *); 8440146895Skanvector signed char vec_ld (int, const signed char *); 8441146895Skanvector unsigned char vec_ld (int, const vector unsigned char *); 8442146895Skanvector unsigned char vec_ld (int, const unsigned char *); 844390075Sobrien 8444146895Skanvector signed char vec_lde (int, const signed char *); 8445146895Skanvector unsigned char vec_lde (int, const unsigned char *); 8446146895Skanvector signed short vec_lde (int, const short *); 8447146895Skanvector unsigned short vec_lde (int, const unsigned short *); 8448146895Skanvector float vec_lde (int, const float *); 8449146895Skanvector signed int vec_lde (int, const int *); 8450146895Skanvector unsigned int vec_lde (int, const unsigned int *); 8451146895Skanvector signed int vec_lde (int, const long *); 8452146895Skanvector unsigned int vec_lde (int, const unsigned long *); 845390075Sobrien 8454146895Skanvector float vec_lvewx (int, float *); 8455146895Skanvector signed int vec_lvewx (int, int *); 8456146895Skanvector unsigned int vec_lvewx (int, unsigned int *); 8457146895Skanvector signed int vec_lvewx (int, long *); 8458146895Skanvector unsigned int vec_lvewx (int, unsigned long *); 845990075Sobrien 8460146895Skanvector signed short vec_lvehx (int, short *); 8461146895Skanvector unsigned short vec_lvehx (int, unsigned short *); 8462146895Skan 8463146895Skanvector signed char vec_lvebx (int, char *); 8464146895Skanvector unsigned char vec_lvebx (int, unsigned char *); 8465146895Skan 8466146895Skanvector float vec_ldl (int, const vector float *); 8467146895Skanvector float vec_ldl (int, const float *); 8468146895Skanvector bool int vec_ldl (int, const vector bool int *); 8469146895Skanvector signed int vec_ldl (int, const vector signed int *); 8470146895Skanvector signed int vec_ldl (int, const int *); 8471146895Skanvector signed int vec_ldl (int, const long *); 8472146895Skanvector unsigned int vec_ldl (int, const vector unsigned int *); 8473146895Skanvector unsigned int vec_ldl (int, const unsigned int *); 8474146895Skanvector unsigned int vec_ldl (int, const unsigned long *); 8475146895Skanvector bool short vec_ldl (int, const vector bool short *); 8476146895Skanvector pixel vec_ldl (int, const vector pixel *); 8477146895Skanvector signed short vec_ldl (int, const vector signed short *); 8478146895Skanvector signed short vec_ldl (int, const short *); 8479146895Skanvector unsigned short vec_ldl (int, const vector unsigned short *); 8480146895Skanvector unsigned short vec_ldl (int, const unsigned short *); 8481146895Skanvector bool char vec_ldl (int, const vector bool char *); 8482146895Skanvector signed char vec_ldl (int, const vector signed char *); 8483146895Skanvector signed char vec_ldl (int, const signed char *); 8484146895Skanvector unsigned char vec_ldl (int, const vector unsigned char *); 8485146895Skanvector unsigned char vec_ldl (int, const unsigned char *); 8486146895Skan 848790075Sobrienvector float vec_loge (vector float); 848890075Sobrien 8489146895Skanvector unsigned char vec_lvsl (int, const volatile unsigned char *); 8490146895Skanvector unsigned char vec_lvsl (int, const volatile signed char *); 8491146895Skanvector unsigned char vec_lvsl (int, const volatile unsigned short *); 8492146895Skanvector unsigned char vec_lvsl (int, const volatile short *); 8493146895Skanvector unsigned char vec_lvsl (int, const volatile unsigned int *); 8494146895Skanvector unsigned char vec_lvsl (int, const volatile int *); 8495146895Skanvector unsigned char vec_lvsl (int, const volatile unsigned long *); 8496146895Skanvector unsigned char vec_lvsl (int, const volatile long *); 8497146895Skanvector unsigned char vec_lvsl (int, const volatile float *); 849890075Sobrien 8499146895Skanvector unsigned char vec_lvsr (int, const volatile unsigned char *); 8500146895Skanvector unsigned char vec_lvsr (int, const volatile signed char *); 8501146895Skanvector unsigned char vec_lvsr (int, const volatile unsigned short *); 8502146895Skanvector unsigned char vec_lvsr (int, const volatile short *); 8503146895Skanvector unsigned char vec_lvsr (int, const volatile unsigned int *); 8504146895Skanvector unsigned char vec_lvsr (int, const volatile int *); 8505146895Skanvector unsigned char vec_lvsr (int, const volatile unsigned long *); 8506146895Skanvector unsigned char vec_lvsr (int, const volatile long *); 8507146895Skanvector unsigned char vec_lvsr (int, const volatile float *); 850890075Sobrien 850990075Sobrienvector float vec_madd (vector float, vector float, vector float); 851090075Sobrien 8511146895Skanvector signed short vec_madds (vector signed short, 8512146895Skan vector signed short, 851396263Sobrien vector signed short); 851490075Sobrien 8515146895Skanvector unsigned char vec_max (vector bool char, vector unsigned char); 8516146895Skanvector unsigned char vec_max (vector unsigned char, vector bool char); 851796263Sobrienvector unsigned char vec_max (vector unsigned char, 851896263Sobrien vector unsigned char); 8519146895Skanvector signed char vec_max (vector bool char, vector signed char); 8520146895Skanvector signed char vec_max (vector signed char, vector bool char); 852190075Sobrienvector signed char vec_max (vector signed char, vector signed char); 8522146895Skanvector unsigned short vec_max (vector bool short, 852396263Sobrien vector unsigned short); 852496263Sobrienvector unsigned short vec_max (vector unsigned short, 8525146895Skan vector bool short); 852696263Sobrienvector unsigned short vec_max (vector unsigned short, 852796263Sobrien vector unsigned short); 8528146895Skanvector signed short vec_max (vector bool short, vector signed short); 8529146895Skanvector signed short vec_max (vector signed short, vector bool short); 853090075Sobrienvector signed short vec_max (vector signed short, vector signed short); 8531146895Skanvector unsigned int vec_max (vector bool int, vector unsigned int); 8532146895Skanvector unsigned int vec_max (vector unsigned int, vector bool int); 853390075Sobrienvector unsigned int vec_max (vector unsigned int, vector unsigned int); 8534146895Skanvector signed int vec_max (vector bool int, vector signed int); 8535146895Skanvector signed int vec_max (vector signed int, vector bool int); 853690075Sobrienvector signed int vec_max (vector signed int, vector signed int); 853790075Sobrienvector float vec_max (vector float, vector float); 853890075Sobrien 8539146895Skanvector float vec_vmaxfp (vector float, vector float); 8540146895Skan 8541146895Skanvector signed int vec_vmaxsw (vector bool int, vector signed int); 8542146895Skanvector signed int vec_vmaxsw (vector signed int, vector bool int); 8543146895Skanvector signed int vec_vmaxsw (vector signed int, vector signed int); 8544146895Skan 8545146895Skanvector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); 8546146895Skanvector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); 8547146895Skanvector unsigned int vec_vmaxuw (vector unsigned int, 8548146895Skan vector unsigned int); 8549146895Skan 8550146895Skanvector signed short vec_vmaxsh (vector bool short, vector signed short); 8551146895Skanvector signed short vec_vmaxsh (vector signed short, vector bool short); 8552146895Skanvector signed short vec_vmaxsh (vector signed short, 8553146895Skan vector signed short); 8554146895Skan 8555146895Skanvector unsigned short vec_vmaxuh (vector bool short, 8556146895Skan vector unsigned short); 8557146895Skanvector unsigned short vec_vmaxuh (vector unsigned short, 8558146895Skan vector bool short); 8559146895Skanvector unsigned short vec_vmaxuh (vector unsigned short, 8560146895Skan vector unsigned short); 8561146895Skan 8562146895Skanvector signed char vec_vmaxsb (vector bool char, vector signed char); 8563146895Skanvector signed char vec_vmaxsb (vector signed char, vector bool char); 8564146895Skanvector signed char vec_vmaxsb (vector signed char, vector signed char); 8565146895Skan 8566146895Skanvector unsigned char vec_vmaxub (vector bool char, 8567146895Skan vector unsigned char); 8568146895Skanvector unsigned char vec_vmaxub (vector unsigned char, 8569146895Skan vector bool char); 8570146895Skanvector unsigned char vec_vmaxub (vector unsigned char, 8571146895Skan vector unsigned char); 8572146895Skan 8573146895Skanvector bool char vec_mergeh (vector bool char, vector bool char); 857490075Sobrienvector signed char vec_mergeh (vector signed char, vector signed char); 857596263Sobrienvector unsigned char vec_mergeh (vector unsigned char, 857696263Sobrien vector unsigned char); 8577146895Skanvector bool short vec_mergeh (vector bool short, vector bool short); 8578146895Skanvector pixel vec_mergeh (vector pixel, vector pixel); 857996263Sobrienvector signed short vec_mergeh (vector signed short, 858096263Sobrien vector signed short); 858196263Sobrienvector unsigned short vec_mergeh (vector unsigned short, 858296263Sobrien vector unsigned short); 858390075Sobrienvector float vec_mergeh (vector float, vector float); 8584146895Skanvector bool int vec_mergeh (vector bool int, vector bool int); 858590075Sobrienvector signed int vec_mergeh (vector signed int, vector signed int); 858696263Sobrienvector unsigned int vec_mergeh (vector unsigned int, 858796263Sobrien vector unsigned int); 858890075Sobrien 8589146895Skanvector float vec_vmrghw (vector float, vector float); 8590146895Skanvector bool int vec_vmrghw (vector bool int, vector bool int); 8591146895Skanvector signed int vec_vmrghw (vector signed int, vector signed int); 8592146895Skanvector unsigned int vec_vmrghw (vector unsigned int, 8593146895Skan vector unsigned int); 8594146895Skan 8595146895Skanvector bool short vec_vmrghh (vector bool short, vector bool short); 8596146895Skanvector signed short vec_vmrghh (vector signed short, 8597146895Skan vector signed short); 8598146895Skanvector unsigned short vec_vmrghh (vector unsigned short, 8599146895Skan vector unsigned short); 8600146895Skanvector pixel vec_vmrghh (vector pixel, vector pixel); 8601146895Skan 8602146895Skanvector bool char vec_vmrghb (vector bool char, vector bool char); 8603146895Skanvector signed char vec_vmrghb (vector signed char, vector signed char); 8604146895Skanvector unsigned char vec_vmrghb (vector unsigned char, 8605146895Skan vector unsigned char); 8606146895Skan 8607146895Skanvector bool char vec_mergel (vector bool char, vector bool char); 860890075Sobrienvector signed char vec_mergel (vector signed char, vector signed char); 860996263Sobrienvector unsigned char vec_mergel (vector unsigned char, 861096263Sobrien vector unsigned char); 8611146895Skanvector bool short vec_mergel (vector bool short, vector bool short); 8612146895Skanvector pixel vec_mergel (vector pixel, vector pixel); 861396263Sobrienvector signed short vec_mergel (vector signed short, 861496263Sobrien vector signed short); 861596263Sobrienvector unsigned short vec_mergel (vector unsigned short, 861696263Sobrien vector unsigned short); 861790075Sobrienvector float vec_mergel (vector float, vector float); 8618146895Skanvector bool int vec_mergel (vector bool int, vector bool int); 861990075Sobrienvector signed int vec_mergel (vector signed int, vector signed int); 862096263Sobrienvector unsigned int vec_mergel (vector unsigned int, 862196263Sobrien vector unsigned int); 862290075Sobrien 8623146895Skanvector float vec_vmrglw (vector float, vector float); 8624146895Skanvector signed int vec_vmrglw (vector signed int, vector signed int); 8625146895Skanvector unsigned int vec_vmrglw (vector unsigned int, 8626146895Skan vector unsigned int); 8627146895Skanvector bool int vec_vmrglw (vector bool int, vector bool int); 862890075Sobrien 8629146895Skanvector bool short vec_vmrglh (vector bool short, vector bool short); 8630146895Skanvector signed short vec_vmrglh (vector signed short, 8631146895Skan vector signed short); 8632146895Skanvector unsigned short vec_vmrglh (vector unsigned short, 8633146895Skan vector unsigned short); 8634146895Skanvector pixel vec_vmrglh (vector pixel, vector pixel); 863590075Sobrien 8636146895Skanvector bool char vec_vmrglb (vector bool char, vector bool char); 8637146895Skanvector signed char vec_vmrglb (vector signed char, vector signed char); 8638146895Skanvector unsigned char vec_vmrglb (vector unsigned char, 8639146895Skan vector unsigned char); 864090075Sobrien 8641146895Skanvector unsigned short vec_mfvscr (void); 8642146895Skan 8643146895Skanvector unsigned char vec_min (vector bool char, vector unsigned char); 8644146895Skanvector unsigned char vec_min (vector unsigned char, vector bool char); 864596263Sobrienvector unsigned char vec_min (vector unsigned char, 864696263Sobrien vector unsigned char); 8647146895Skanvector signed char vec_min (vector bool char, vector signed char); 8648146895Skanvector signed char vec_min (vector signed char, vector bool char); 864990075Sobrienvector signed char vec_min (vector signed char, vector signed char); 8650146895Skanvector unsigned short vec_min (vector bool short, 865196263Sobrien vector unsigned short); 865296263Sobrienvector unsigned short vec_min (vector unsigned short, 8653146895Skan vector bool short); 865496263Sobrienvector unsigned short vec_min (vector unsigned short, 865596263Sobrien vector unsigned short); 8656146895Skanvector signed short vec_min (vector bool short, vector signed short); 8657146895Skanvector signed short vec_min (vector signed short, vector bool short); 865890075Sobrienvector signed short vec_min (vector signed short, vector signed short); 8659146895Skanvector unsigned int vec_min (vector bool int, vector unsigned int); 8660146895Skanvector unsigned int vec_min (vector unsigned int, vector bool int); 866190075Sobrienvector unsigned int vec_min (vector unsigned int, vector unsigned int); 8662146895Skanvector signed int vec_min (vector bool int, vector signed int); 8663146895Skanvector signed int vec_min (vector signed int, vector bool int); 866490075Sobrienvector signed int vec_min (vector signed int, vector signed int); 866590075Sobrienvector float vec_min (vector float, vector float); 866690075Sobrien 8667146895Skanvector float vec_vminfp (vector float, vector float); 8668146895Skan 8669146895Skanvector signed int vec_vminsw (vector bool int, vector signed int); 8670146895Skanvector signed int vec_vminsw (vector signed int, vector bool int); 8671146895Skanvector signed int vec_vminsw (vector signed int, vector signed int); 8672146895Skan 8673146895Skanvector unsigned int vec_vminuw (vector bool int, vector unsigned int); 8674146895Skanvector unsigned int vec_vminuw (vector unsigned int, vector bool int); 8675146895Skanvector unsigned int vec_vminuw (vector unsigned int, 8676146895Skan vector unsigned int); 8677146895Skan 8678146895Skanvector signed short vec_vminsh (vector bool short, vector signed short); 8679146895Skanvector signed short vec_vminsh (vector signed short, vector bool short); 8680146895Skanvector signed short vec_vminsh (vector signed short, 8681146895Skan vector signed short); 8682146895Skan 8683146895Skanvector unsigned short vec_vminuh (vector bool short, 8684146895Skan vector unsigned short); 8685146895Skanvector unsigned short vec_vminuh (vector unsigned short, 8686146895Skan vector bool short); 8687146895Skanvector unsigned short vec_vminuh (vector unsigned short, 8688146895Skan vector unsigned short); 8689146895Skan 8690146895Skanvector signed char vec_vminsb (vector bool char, vector signed char); 8691146895Skanvector signed char vec_vminsb (vector signed char, vector bool char); 8692146895Skanvector signed char vec_vminsb (vector signed char, vector signed char); 8693146895Skan 8694146895Skanvector unsigned char vec_vminub (vector bool char, 8695146895Skan vector unsigned char); 8696146895Skanvector unsigned char vec_vminub (vector unsigned char, 8697146895Skan vector bool char); 8698146895Skanvector unsigned char vec_vminub (vector unsigned char, 8699146895Skan vector unsigned char); 8700146895Skan 8701146895Skanvector signed short vec_mladd (vector signed short, 8702146895Skan vector signed short, 870396263Sobrien vector signed short); 870496263Sobrienvector signed short vec_mladd (vector signed short, 870596263Sobrien vector unsigned short, 870696263Sobrien vector unsigned short); 870796263Sobrienvector signed short vec_mladd (vector unsigned short, 870896263Sobrien vector signed short, 870996263Sobrien vector signed short); 871096263Sobrienvector unsigned short vec_mladd (vector unsigned short, 871196263Sobrien vector unsigned short, 871296263Sobrien vector unsigned short); 871390075Sobrien 871496263Sobrienvector signed short vec_mradds (vector signed short, 871596263Sobrien vector signed short, 871696263Sobrien vector signed short); 871790075Sobrien 871896263Sobrienvector unsigned int vec_msum (vector unsigned char, 871996263Sobrien vector unsigned char, 872096263Sobrien vector unsigned int); 8721146895Skanvector signed int vec_msum (vector signed char, 8722146895Skan vector unsigned char, 872396263Sobrien vector signed int); 872496263Sobrienvector unsigned int vec_msum (vector unsigned short, 872596263Sobrien vector unsigned short, 872696263Sobrien vector unsigned int); 8727146895Skanvector signed int vec_msum (vector signed short, 8728146895Skan vector signed short, 872996263Sobrien vector signed int); 873090075Sobrien 8731146895Skanvector signed int vec_vmsumshm (vector signed short, 8732146895Skan vector signed short, 8733146895Skan vector signed int); 8734146895Skan 8735146895Skanvector unsigned int vec_vmsumuhm (vector unsigned short, 8736146895Skan vector unsigned short, 8737146895Skan vector unsigned int); 8738146895Skan 8739146895Skanvector signed int vec_vmsummbm (vector signed char, 8740146895Skan vector unsigned char, 8741146895Skan vector signed int); 8742146895Skan 8743146895Skanvector unsigned int vec_vmsumubm (vector unsigned char, 8744146895Skan vector unsigned char, 8745146895Skan vector unsigned int); 8746146895Skan 874796263Sobrienvector unsigned int vec_msums (vector unsigned short, 874896263Sobrien vector unsigned short, 874996263Sobrien vector unsigned int); 8750146895Skanvector signed int vec_msums (vector signed short, 8751146895Skan vector signed short, 875296263Sobrien vector signed int); 875390075Sobrien 8754146895Skanvector signed int vec_vmsumshs (vector signed short, 8755146895Skan vector signed short, 8756146895Skan vector signed int); 8757146895Skan 8758146895Skanvector unsigned int vec_vmsumuhs (vector unsigned short, 8759146895Skan vector unsigned short, 8760146895Skan vector unsigned int); 8761146895Skan 876290075Sobrienvoid vec_mtvscr (vector signed int); 876390075Sobrienvoid vec_mtvscr (vector unsigned int); 8764146895Skanvoid vec_mtvscr (vector bool int); 876590075Sobrienvoid vec_mtvscr (vector signed short); 876690075Sobrienvoid vec_mtvscr (vector unsigned short); 8767146895Skanvoid vec_mtvscr (vector bool short); 8768146895Skanvoid vec_mtvscr (vector pixel); 876990075Sobrienvoid vec_mtvscr (vector signed char); 877090075Sobrienvoid vec_mtvscr (vector unsigned char); 8771146895Skanvoid vec_mtvscr (vector bool char); 877290075Sobrien 877396263Sobrienvector unsigned short vec_mule (vector unsigned char, 877496263Sobrien vector unsigned char); 8775146895Skanvector signed short vec_mule (vector signed char, 8776146895Skan vector signed char); 877796263Sobrienvector unsigned int vec_mule (vector unsigned short, 877896263Sobrien vector unsigned short); 877990075Sobrienvector signed int vec_mule (vector signed short, vector signed short); 878090075Sobrien 8781146895Skanvector signed int vec_vmulesh (vector signed short, 8782146895Skan vector signed short); 8783146895Skan 8784146895Skanvector unsigned int vec_vmuleuh (vector unsigned short, 8785146895Skan vector unsigned short); 8786146895Skan 8787146895Skanvector signed short vec_vmulesb (vector signed char, 8788146895Skan vector signed char); 8789146895Skan 8790146895Skanvector unsigned short vec_vmuleub (vector unsigned char, 8791146895Skan vector unsigned char); 8792146895Skan 879396263Sobrienvector unsigned short vec_mulo (vector unsigned char, 879496263Sobrien vector unsigned char); 879590075Sobrienvector signed short vec_mulo (vector signed char, vector signed char); 879696263Sobrienvector unsigned int vec_mulo (vector unsigned short, 879796263Sobrien vector unsigned short); 879890075Sobrienvector signed int vec_mulo (vector signed short, vector signed short); 879990075Sobrien 8800146895Skanvector signed int vec_vmulosh (vector signed short, 8801146895Skan vector signed short); 8802146895Skan 8803146895Skanvector unsigned int vec_vmulouh (vector unsigned short, 8804146895Skan vector unsigned short); 8805146895Skan 8806146895Skanvector signed short vec_vmulosb (vector signed char, 8807146895Skan vector signed char); 8808146895Skan 8809146895Skanvector unsigned short vec_vmuloub (vector unsigned char, 8810146895Skan vector unsigned char); 8811146895Skan 881290075Sobrienvector float vec_nmsub (vector float, vector float, vector float); 881390075Sobrien 881490075Sobrienvector float vec_nor (vector float, vector float); 881590075Sobrienvector signed int vec_nor (vector signed int, vector signed int); 881690075Sobrienvector unsigned int vec_nor (vector unsigned int, vector unsigned int); 8817146895Skanvector bool int vec_nor (vector bool int, vector bool int); 881890075Sobrienvector signed short vec_nor (vector signed short, vector signed short); 881996263Sobrienvector unsigned short vec_nor (vector unsigned short, 882096263Sobrien vector unsigned short); 8821146895Skanvector bool short vec_nor (vector bool short, vector bool short); 882290075Sobrienvector signed char vec_nor (vector signed char, vector signed char); 882396263Sobrienvector unsigned char vec_nor (vector unsigned char, 882496263Sobrien vector unsigned char); 8825146895Skanvector bool char vec_nor (vector bool char, vector bool char); 882690075Sobrien 882790075Sobrienvector float vec_or (vector float, vector float); 8828146895Skanvector float vec_or (vector float, vector bool int); 8829146895Skanvector float vec_or (vector bool int, vector float); 8830146895Skanvector bool int vec_or (vector bool int, vector bool int); 8831146895Skanvector signed int vec_or (vector bool int, vector signed int); 8832146895Skanvector signed int vec_or (vector signed int, vector bool int); 883390075Sobrienvector signed int vec_or (vector signed int, vector signed int); 8834146895Skanvector unsigned int vec_or (vector bool int, vector unsigned int); 8835146895Skanvector unsigned int vec_or (vector unsigned int, vector bool int); 883690075Sobrienvector unsigned int vec_or (vector unsigned int, vector unsigned int); 8837146895Skanvector bool short vec_or (vector bool short, vector bool short); 8838146895Skanvector signed short vec_or (vector bool short, vector signed short); 8839146895Skanvector signed short vec_or (vector signed short, vector bool short); 884090075Sobrienvector signed short vec_or (vector signed short, vector signed short); 8841146895Skanvector unsigned short vec_or (vector bool short, vector unsigned short); 8842146895Skanvector unsigned short vec_or (vector unsigned short, vector bool short); 884396263Sobrienvector unsigned short vec_or (vector unsigned short, 884496263Sobrien vector unsigned short); 8845146895Skanvector signed char vec_or (vector bool char, vector signed char); 8846146895Skanvector bool char vec_or (vector bool char, vector bool char); 8847146895Skanvector signed char vec_or (vector signed char, vector bool char); 884890075Sobrienvector signed char vec_or (vector signed char, vector signed char); 8849146895Skanvector unsigned char vec_or (vector bool char, vector unsigned char); 8850146895Skanvector unsigned char vec_or (vector unsigned char, vector bool char); 885196263Sobrienvector unsigned char vec_or (vector unsigned char, 885296263Sobrien vector unsigned char); 885390075Sobrien 885490075Sobrienvector signed char vec_pack (vector signed short, vector signed short); 885596263Sobrienvector unsigned char vec_pack (vector unsigned short, 885696263Sobrien vector unsigned short); 8857146895Skanvector bool char vec_pack (vector bool short, vector bool short); 885890075Sobrienvector signed short vec_pack (vector signed int, vector signed int); 885996263Sobrienvector unsigned short vec_pack (vector unsigned int, 886096263Sobrien vector unsigned int); 8861146895Skanvector bool short vec_pack (vector bool int, vector bool int); 886290075Sobrien 8863146895Skanvector bool short vec_vpkuwum (vector bool int, vector bool int); 8864146895Skanvector signed short vec_vpkuwum (vector signed int, vector signed int); 8865146895Skanvector unsigned short vec_vpkuwum (vector unsigned int, 8866146895Skan vector unsigned int); 886790075Sobrien 8868146895Skanvector bool char vec_vpkuhum (vector bool short, vector bool short); 8869146895Skanvector signed char vec_vpkuhum (vector signed short, 8870146895Skan vector signed short); 8871146895Skanvector unsigned char vec_vpkuhum (vector unsigned short, 8872146895Skan vector unsigned short); 8873146895Skan 8874146895Skanvector pixel vec_packpx (vector unsigned int, vector unsigned int); 8875146895Skan 887696263Sobrienvector unsigned char vec_packs (vector unsigned short, 887796263Sobrien vector unsigned short); 887890075Sobrienvector signed char vec_packs (vector signed short, vector signed short); 887996263Sobrienvector unsigned short vec_packs (vector unsigned int, 888096263Sobrien vector unsigned int); 888190075Sobrienvector signed short vec_packs (vector signed int, vector signed int); 888290075Sobrien 8883146895Skanvector signed short vec_vpkswss (vector signed int, vector signed int); 8884146895Skan 8885146895Skanvector unsigned short vec_vpkuwus (vector unsigned int, 8886146895Skan vector unsigned int); 8887146895Skan 8888146895Skanvector signed char vec_vpkshss (vector signed short, 8889146895Skan vector signed short); 8890146895Skan 8891146895Skanvector unsigned char vec_vpkuhus (vector unsigned short, 8892146895Skan vector unsigned short); 8893146895Skan 889496263Sobrienvector unsigned char vec_packsu (vector unsigned short, 889596263Sobrien vector unsigned short); 889696263Sobrienvector unsigned char vec_packsu (vector signed short, 889796263Sobrien vector signed short); 889896263Sobrienvector unsigned short vec_packsu (vector unsigned int, 889996263Sobrien vector unsigned int); 890090075Sobrienvector unsigned short vec_packsu (vector signed int, vector signed int); 890190075Sobrien 8902146895Skanvector unsigned short vec_vpkswus (vector signed int, 8903146895Skan vector signed int); 8904146895Skan 8905146895Skanvector unsigned char vec_vpkshus (vector signed short, 8906146895Skan vector signed short); 8907146895Skan 8908146895Skanvector float vec_perm (vector float, 8909146895Skan vector float, 891096263Sobrien vector unsigned char); 8911146895Skanvector signed int vec_perm (vector signed int, 8912146895Skan vector signed int, 891396263Sobrien vector unsigned char); 8914146895Skanvector unsigned int vec_perm (vector unsigned int, 8915146895Skan vector unsigned int, 891696263Sobrien vector unsigned char); 8917146895Skanvector bool int vec_perm (vector bool int, 8918146895Skan vector bool int, 8919146895Skan vector unsigned char); 8920146895Skanvector signed short vec_perm (vector signed short, 8921146895Skan vector signed short, 892296263Sobrien vector unsigned char); 892396263Sobrienvector unsigned short vec_perm (vector unsigned short, 892496263Sobrien vector unsigned short, 892596263Sobrien vector unsigned char); 8926146895Skanvector bool short vec_perm (vector bool short, 8927146895Skan vector bool short, 8928146895Skan vector unsigned char); 8929146895Skanvector pixel vec_perm (vector pixel, 8930146895Skan vector pixel, 8931146895Skan vector unsigned char); 8932146895Skanvector signed char vec_perm (vector signed char, 8933146895Skan vector signed char, 893496263Sobrien vector unsigned char); 893596263Sobrienvector unsigned char vec_perm (vector unsigned char, 893696263Sobrien vector unsigned char, 893796263Sobrien vector unsigned char); 8938146895Skanvector bool char vec_perm (vector bool char, 8939146895Skan vector bool char, 8940146895Skan vector unsigned char); 894190075Sobrien 894290075Sobrienvector float vec_re (vector float); 894390075Sobrien 8944146895Skanvector signed char vec_rl (vector signed char, 8945146895Skan vector unsigned char); 894696263Sobrienvector unsigned char vec_rl (vector unsigned char, 894796263Sobrien vector unsigned char); 894890075Sobrienvector signed short vec_rl (vector signed short, vector unsigned short); 894996263Sobrienvector unsigned short vec_rl (vector unsigned short, 895096263Sobrien vector unsigned short); 895190075Sobrienvector signed int vec_rl (vector signed int, vector unsigned int); 895290075Sobrienvector unsigned int vec_rl (vector unsigned int, vector unsigned int); 895390075Sobrien 8954146895Skanvector signed int vec_vrlw (vector signed int, vector unsigned int); 8955146895Skanvector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); 8956146895Skan 8957146895Skanvector signed short vec_vrlh (vector signed short, 8958146895Skan vector unsigned short); 8959146895Skanvector unsigned short vec_vrlh (vector unsigned short, 8960146895Skan vector unsigned short); 8961146895Skan 8962146895Skanvector signed char vec_vrlb (vector signed char, vector unsigned char); 8963146895Skanvector unsigned char vec_vrlb (vector unsigned char, 8964146895Skan vector unsigned char); 8965146895Skan 896690075Sobrienvector float vec_round (vector float); 896790075Sobrien 896890075Sobrienvector float vec_rsqrte (vector float); 896990075Sobrien 8970146895Skanvector float vec_sel (vector float, vector float, vector bool int); 897190075Sobrienvector float vec_sel (vector float, vector float, vector unsigned int); 8972146895Skanvector signed int vec_sel (vector signed int, 8973146895Skan vector signed int, 8974146895Skan vector bool int); 8975146895Skanvector signed int vec_sel (vector signed int, 8976146895Skan vector signed int, 897796263Sobrien vector unsigned int); 8978146895Skanvector unsigned int vec_sel (vector unsigned int, 8979146895Skan vector unsigned int, 8980146895Skan vector bool int); 8981146895Skanvector unsigned int vec_sel (vector unsigned int, 8982146895Skan vector unsigned int, 898396263Sobrien vector unsigned int); 8984146895Skanvector bool int vec_sel (vector bool int, 8985146895Skan vector bool int, 8986146895Skan vector bool int); 8987146895Skanvector bool int vec_sel (vector bool int, 8988146895Skan vector bool int, 8989146895Skan vector unsigned int); 8990146895Skanvector signed short vec_sel (vector signed short, 8991146895Skan vector signed short, 8992146895Skan vector bool short); 8993146895Skanvector signed short vec_sel (vector signed short, 8994146895Skan vector signed short, 899596263Sobrien vector unsigned short); 899696263Sobrienvector unsigned short vec_sel (vector unsigned short, 899796263Sobrien vector unsigned short, 8998146895Skan vector bool short); 899996263Sobrienvector unsigned short vec_sel (vector unsigned short, 900096263Sobrien vector unsigned short, 900196263Sobrien vector unsigned short); 9002146895Skanvector bool short vec_sel (vector bool short, 9003146895Skan vector bool short, 9004146895Skan vector bool short); 9005146895Skanvector bool short vec_sel (vector bool short, 9006146895Skan vector bool short, 9007146895Skan vector unsigned short); 9008146895Skanvector signed char vec_sel (vector signed char, 9009146895Skan vector signed char, 9010146895Skan vector bool char); 9011146895Skanvector signed char vec_sel (vector signed char, 9012146895Skan vector signed char, 901396263Sobrien vector unsigned char); 901496263Sobrienvector unsigned char vec_sel (vector unsigned char, 901596263Sobrien vector unsigned char, 9016146895Skan vector bool char); 901796263Sobrienvector unsigned char vec_sel (vector unsigned char, 901896263Sobrien vector unsigned char, 901996263Sobrien vector unsigned char); 9020146895Skanvector bool char vec_sel (vector bool char, 9021146895Skan vector bool char, 9022146895Skan vector bool char); 9023146895Skanvector bool char vec_sel (vector bool char, 9024146895Skan vector bool char, 9025146895Skan vector unsigned char); 902690075Sobrien 9027146895Skanvector signed char vec_sl (vector signed char, 9028146895Skan vector unsigned char); 902996263Sobrienvector unsigned char vec_sl (vector unsigned char, 903096263Sobrien vector unsigned char); 903190075Sobrienvector signed short vec_sl (vector signed short, vector unsigned short); 903296263Sobrienvector unsigned short vec_sl (vector unsigned short, 903396263Sobrien vector unsigned short); 903490075Sobrienvector signed int vec_sl (vector signed int, vector unsigned int); 903590075Sobrienvector unsigned int vec_sl (vector unsigned int, vector unsigned int); 903690075Sobrien 9037146895Skanvector signed int vec_vslw (vector signed int, vector unsigned int); 9038146895Skanvector unsigned int vec_vslw (vector unsigned int, vector unsigned int); 9039146895Skan 9040146895Skanvector signed short vec_vslh (vector signed short, 9041146895Skan vector unsigned short); 9042146895Skanvector unsigned short vec_vslh (vector unsigned short, 9043146895Skan vector unsigned short); 9044146895Skan 9045146895Skanvector signed char vec_vslb (vector signed char, vector unsigned char); 9046146895Skanvector unsigned char vec_vslb (vector unsigned char, 9047146895Skan vector unsigned char); 9048146895Skan 9049146895Skanvector float vec_sld (vector float, vector float, const int); 9050146895Skanvector signed int vec_sld (vector signed int, 9051146895Skan vector signed int, 9052146895Skan const int); 9053146895Skanvector unsigned int vec_sld (vector unsigned int, 9054146895Skan vector unsigned int, 9055146895Skan const int); 9056146895Skanvector bool int vec_sld (vector bool int, 9057146895Skan vector bool int, 9058146895Skan const int); 9059146895Skanvector signed short vec_sld (vector signed short, 9060146895Skan vector signed short, 9061146895Skan const int); 906296263Sobrienvector unsigned short vec_sld (vector unsigned short, 9063146895Skan vector unsigned short, 9064146895Skan const int); 9065146895Skanvector bool short vec_sld (vector bool short, 9066146895Skan vector bool short, 9067146895Skan const int); 9068146895Skanvector pixel vec_sld (vector pixel, 9069146895Skan vector pixel, 9070146895Skan const int); 9071146895Skanvector signed char vec_sld (vector signed char, 9072146895Skan vector signed char, 9073146895Skan const int); 907496263Sobrienvector unsigned char vec_sld (vector unsigned char, 907596263Sobrien vector unsigned char, 9076146895Skan const int); 9077146895Skanvector bool char vec_sld (vector bool char, 9078146895Skan vector bool char, 9079146895Skan const int); 908090075Sobrien 9081146895Skanvector signed int vec_sll (vector signed int, 9082146895Skan vector unsigned int); 9083146895Skanvector signed int vec_sll (vector signed int, 9084146895Skan vector unsigned short); 9085146895Skanvector signed int vec_sll (vector signed int, 9086146895Skan vector unsigned char); 908796263Sobrienvector unsigned int vec_sll (vector unsigned int, 9088146895Skan vector unsigned int); 9089146895Skanvector unsigned int vec_sll (vector unsigned int, 909096263Sobrien vector unsigned short); 9091146895Skanvector unsigned int vec_sll (vector unsigned int, 9092146895Skan vector unsigned char); 9093146895Skanvector bool int vec_sll (vector bool int, 9094146895Skan vector unsigned int); 9095146895Skanvector bool int vec_sll (vector bool int, 9096146895Skan vector unsigned short); 9097146895Skanvector bool int vec_sll (vector bool int, 9098146895Skan vector unsigned char); 909996263Sobrienvector signed short vec_sll (vector signed short, 9100146895Skan vector unsigned int); 9101146895Skanvector signed short vec_sll (vector signed short, 910296263Sobrien vector unsigned short); 9103146895Skanvector signed short vec_sll (vector signed short, 9104146895Skan vector unsigned char); 910596263Sobrienvector unsigned short vec_sll (vector unsigned short, 910696263Sobrien vector unsigned int); 910796263Sobrienvector unsigned short vec_sll (vector unsigned short, 910896263Sobrien vector unsigned short); 910996263Sobrienvector unsigned short vec_sll (vector unsigned short, 911096263Sobrien vector unsigned char); 9111146895Skanvector bool short vec_sll (vector bool short, vector unsigned int); 9112146895Skanvector bool short vec_sll (vector bool short, vector unsigned short); 9113146895Skanvector bool short vec_sll (vector bool short, vector unsigned char); 9114146895Skanvector pixel vec_sll (vector pixel, vector unsigned int); 9115146895Skanvector pixel vec_sll (vector pixel, vector unsigned short); 9116146895Skanvector pixel vec_sll (vector pixel, vector unsigned char); 911790075Sobrienvector signed char vec_sll (vector signed char, vector unsigned int); 911890075Sobrienvector signed char vec_sll (vector signed char, vector unsigned short); 911990075Sobrienvector signed char vec_sll (vector signed char, vector unsigned char); 912096263Sobrienvector unsigned char vec_sll (vector unsigned char, 912196263Sobrien vector unsigned int); 912296263Sobrienvector unsigned char vec_sll (vector unsigned char, 912396263Sobrien vector unsigned short); 912496263Sobrienvector unsigned char vec_sll (vector unsigned char, 912596263Sobrien vector unsigned char); 9126146895Skanvector bool char vec_sll (vector bool char, vector unsigned int); 9127146895Skanvector bool char vec_sll (vector bool char, vector unsigned short); 9128146895Skanvector bool char vec_sll (vector bool char, vector unsigned char); 912990075Sobrien 913090075Sobrienvector float vec_slo (vector float, vector signed char); 913190075Sobrienvector float vec_slo (vector float, vector unsigned char); 913290075Sobrienvector signed int vec_slo (vector signed int, vector signed char); 913390075Sobrienvector signed int vec_slo (vector signed int, vector unsigned char); 913490075Sobrienvector unsigned int vec_slo (vector unsigned int, vector signed char); 913590075Sobrienvector unsigned int vec_slo (vector unsigned int, vector unsigned char); 913690075Sobrienvector signed short vec_slo (vector signed short, vector signed char); 913790075Sobrienvector signed short vec_slo (vector signed short, vector unsigned char); 913896263Sobrienvector unsigned short vec_slo (vector unsigned short, 913996263Sobrien vector signed char); 914096263Sobrienvector unsigned short vec_slo (vector unsigned short, 914196263Sobrien vector unsigned char); 9142146895Skanvector pixel vec_slo (vector pixel, vector signed char); 9143146895Skanvector pixel vec_slo (vector pixel, vector unsigned char); 914490075Sobrienvector signed char vec_slo (vector signed char, vector signed char); 914590075Sobrienvector signed char vec_slo (vector signed char, vector unsigned char); 914690075Sobrienvector unsigned char vec_slo (vector unsigned char, vector signed char); 914796263Sobrienvector unsigned char vec_slo (vector unsigned char, 914896263Sobrien vector unsigned char); 914990075Sobrien 9150146895Skanvector signed char vec_splat (vector signed char, const int); 9151146895Skanvector unsigned char vec_splat (vector unsigned char, const int); 9152146895Skanvector bool char vec_splat (vector bool char, const int); 9153146895Skanvector signed short vec_splat (vector signed short, const int); 9154146895Skanvector unsigned short vec_splat (vector unsigned short, const int); 9155146895Skanvector bool short vec_splat (vector bool short, const int); 9156146895Skanvector pixel vec_splat (vector pixel, const int); 9157146895Skanvector float vec_splat (vector float, const int); 9158146895Skanvector signed int vec_splat (vector signed int, const int); 9159146895Skanvector unsigned int vec_splat (vector unsigned int, const int); 9160146895Skanvector bool int vec_splat (vector bool int, const int); 916190075Sobrien 9162146895Skanvector float vec_vspltw (vector float, const int); 9163146895Skanvector signed int vec_vspltw (vector signed int, const int); 9164146895Skanvector unsigned int vec_vspltw (vector unsigned int, const int); 9165146895Skanvector bool int vec_vspltw (vector bool int, const int); 916690075Sobrien 9167146895Skanvector bool short vec_vsplth (vector bool short, const int); 9168146895Skanvector signed short vec_vsplth (vector signed short, const int); 9169146895Skanvector unsigned short vec_vsplth (vector unsigned short, const int); 9170146895Skanvector pixel vec_vsplth (vector pixel, const int); 917190075Sobrien 9172146895Skanvector signed char vec_vspltb (vector signed char, const int); 9173146895Skanvector unsigned char vec_vspltb (vector unsigned char, const int); 9174146895Skanvector bool char vec_vspltb (vector bool char, const int); 917590075Sobrien 9176146895Skanvector signed char vec_splat_s8 (const int); 917790075Sobrien 9178146895Skanvector signed short vec_splat_s16 (const int); 917990075Sobrien 9180146895Skanvector signed int vec_splat_s32 (const int); 918190075Sobrien 9182146895Skanvector unsigned char vec_splat_u8 (const int); 9183146895Skan 9184146895Skanvector unsigned short vec_splat_u16 (const int); 9185146895Skan 9186146895Skanvector unsigned int vec_splat_u32 (const int); 9187146895Skan 918890075Sobrienvector signed char vec_sr (vector signed char, vector unsigned char); 918996263Sobrienvector unsigned char vec_sr (vector unsigned char, 919096263Sobrien vector unsigned char); 9191146895Skanvector signed short vec_sr (vector signed short, 9192146895Skan vector unsigned short); 919396263Sobrienvector unsigned short vec_sr (vector unsigned short, 919496263Sobrien vector unsigned short); 919590075Sobrienvector signed int vec_sr (vector signed int, vector unsigned int); 919690075Sobrienvector unsigned int vec_sr (vector unsigned int, vector unsigned int); 919790075Sobrien 9198146895Skanvector signed int vec_vsrw (vector signed int, vector unsigned int); 9199146895Skanvector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); 9200146895Skan 9201146895Skanvector signed short vec_vsrh (vector signed short, 9202146895Skan vector unsigned short); 9203146895Skanvector unsigned short vec_vsrh (vector unsigned short, 9204146895Skan vector unsigned short); 9205146895Skan 9206146895Skanvector signed char vec_vsrb (vector signed char, vector unsigned char); 9207146895Skanvector unsigned char vec_vsrb (vector unsigned char, 9208146895Skan vector unsigned char); 9209146895Skan 921090075Sobrienvector signed char vec_sra (vector signed char, vector unsigned char); 921196263Sobrienvector unsigned char vec_sra (vector unsigned char, 921296263Sobrien vector unsigned char); 921396263Sobrienvector signed short vec_sra (vector signed short, 921496263Sobrien vector unsigned short); 921596263Sobrienvector unsigned short vec_sra (vector unsigned short, 921696263Sobrien vector unsigned short); 921790075Sobrienvector signed int vec_sra (vector signed int, vector unsigned int); 921890075Sobrienvector unsigned int vec_sra (vector unsigned int, vector unsigned int); 921990075Sobrien 9220146895Skanvector signed int vec_vsraw (vector signed int, vector unsigned int); 9221146895Skanvector unsigned int vec_vsraw (vector unsigned int, 9222146895Skan vector unsigned int); 9223146895Skan 9224146895Skanvector signed short vec_vsrah (vector signed short, 9225146895Skan vector unsigned short); 9226146895Skanvector unsigned short vec_vsrah (vector unsigned short, 9227146895Skan vector unsigned short); 9228146895Skan 9229146895Skanvector signed char vec_vsrab (vector signed char, vector unsigned char); 9230146895Skanvector unsigned char vec_vsrab (vector unsigned char, 9231146895Skan vector unsigned char); 9232146895Skan 923390075Sobrienvector signed int vec_srl (vector signed int, vector unsigned int); 923490075Sobrienvector signed int vec_srl (vector signed int, vector unsigned short); 923590075Sobrienvector signed int vec_srl (vector signed int, vector unsigned char); 923690075Sobrienvector unsigned int vec_srl (vector unsigned int, vector unsigned int); 923796263Sobrienvector unsigned int vec_srl (vector unsigned int, 923896263Sobrien vector unsigned short); 923990075Sobrienvector unsigned int vec_srl (vector unsigned int, vector unsigned char); 9240146895Skanvector bool int vec_srl (vector bool int, vector unsigned int); 9241146895Skanvector bool int vec_srl (vector bool int, vector unsigned short); 9242146895Skanvector bool int vec_srl (vector bool int, vector unsigned char); 924390075Sobrienvector signed short vec_srl (vector signed short, vector unsigned int); 924496263Sobrienvector signed short vec_srl (vector signed short, 924596263Sobrien vector unsigned short); 924690075Sobrienvector signed short vec_srl (vector signed short, vector unsigned char); 924796263Sobrienvector unsigned short vec_srl (vector unsigned short, 924896263Sobrien vector unsigned int); 924996263Sobrienvector unsigned short vec_srl (vector unsigned short, 925096263Sobrien vector unsigned short); 925196263Sobrienvector unsigned short vec_srl (vector unsigned short, 925296263Sobrien vector unsigned char); 9253146895Skanvector bool short vec_srl (vector bool short, vector unsigned int); 9254146895Skanvector bool short vec_srl (vector bool short, vector unsigned short); 9255146895Skanvector bool short vec_srl (vector bool short, vector unsigned char); 9256146895Skanvector pixel vec_srl (vector pixel, vector unsigned int); 9257146895Skanvector pixel vec_srl (vector pixel, vector unsigned short); 9258146895Skanvector pixel vec_srl (vector pixel, vector unsigned char); 925990075Sobrienvector signed char vec_srl (vector signed char, vector unsigned int); 926090075Sobrienvector signed char vec_srl (vector signed char, vector unsigned short); 926190075Sobrienvector signed char vec_srl (vector signed char, vector unsigned char); 926296263Sobrienvector unsigned char vec_srl (vector unsigned char, 926396263Sobrien vector unsigned int); 926496263Sobrienvector unsigned char vec_srl (vector unsigned char, 926596263Sobrien vector unsigned short); 926696263Sobrienvector unsigned char vec_srl (vector unsigned char, 926796263Sobrien vector unsigned char); 9268146895Skanvector bool char vec_srl (vector bool char, vector unsigned int); 9269146895Skanvector bool char vec_srl (vector bool char, vector unsigned short); 9270146895Skanvector bool char vec_srl (vector bool char, vector unsigned char); 927190075Sobrien 927290075Sobrienvector float vec_sro (vector float, vector signed char); 927390075Sobrienvector float vec_sro (vector float, vector unsigned char); 927490075Sobrienvector signed int vec_sro (vector signed int, vector signed char); 927590075Sobrienvector signed int vec_sro (vector signed int, vector unsigned char); 927690075Sobrienvector unsigned int vec_sro (vector unsigned int, vector signed char); 927790075Sobrienvector unsigned int vec_sro (vector unsigned int, vector unsigned char); 927890075Sobrienvector signed short vec_sro (vector signed short, vector signed char); 927990075Sobrienvector signed short vec_sro (vector signed short, vector unsigned char); 928096263Sobrienvector unsigned short vec_sro (vector unsigned short, 928196263Sobrien vector signed char); 928296263Sobrienvector unsigned short vec_sro (vector unsigned short, 928396263Sobrien vector unsigned char); 9284146895Skanvector pixel vec_sro (vector pixel, vector signed char); 9285146895Skanvector pixel vec_sro (vector pixel, vector unsigned char); 928690075Sobrienvector signed char vec_sro (vector signed char, vector signed char); 928790075Sobrienvector signed char vec_sro (vector signed char, vector unsigned char); 928890075Sobrienvector unsigned char vec_sro (vector unsigned char, vector signed char); 928996263Sobrienvector unsigned char vec_sro (vector unsigned char, 929096263Sobrien vector unsigned char); 929190075Sobrien 9292146895Skanvoid vec_st (vector float, int, vector float *); 929390075Sobrienvoid vec_st (vector float, int, float *); 9294146895Skanvoid vec_st (vector signed int, int, vector signed int *); 929590075Sobrienvoid vec_st (vector signed int, int, int *); 9296146895Skanvoid vec_st (vector unsigned int, int, vector unsigned int *); 929790075Sobrienvoid vec_st (vector unsigned int, int, unsigned int *); 9298146895Skanvoid vec_st (vector bool int, int, vector bool int *); 9299146895Skanvoid vec_st (vector bool int, int, unsigned int *); 9300146895Skanvoid vec_st (vector bool int, int, int *); 9301146895Skanvoid vec_st (vector signed short, int, vector signed short *); 930290075Sobrienvoid vec_st (vector signed short, int, short *); 9303146895Skanvoid vec_st (vector unsigned short, int, vector unsigned short *); 930490075Sobrienvoid vec_st (vector unsigned short, int, unsigned short *); 9305146895Skanvoid vec_st (vector bool short, int, vector bool short *); 9306146895Skanvoid vec_st (vector bool short, int, unsigned short *); 9307146895Skanvoid vec_st (vector pixel, int, vector pixel *); 9308146895Skanvoid vec_st (vector pixel, int, unsigned short *); 9309146895Skanvoid vec_st (vector pixel, int, short *); 9310146895Skanvoid vec_st (vector bool short, int, short *); 9311146895Skanvoid vec_st (vector signed char, int, vector signed char *); 931290075Sobrienvoid vec_st (vector signed char, int, signed char *); 9313146895Skanvoid vec_st (vector unsigned char, int, vector unsigned char *); 931490075Sobrienvoid vec_st (vector unsigned char, int, unsigned char *); 9315146895Skanvoid vec_st (vector bool char, int, vector bool char *); 9316146895Skanvoid vec_st (vector bool char, int, unsigned char *); 9317146895Skanvoid vec_st (vector bool char, int, signed char *); 931890075Sobrien 931990075Sobrienvoid vec_ste (vector signed char, int, signed char *); 932090075Sobrienvoid vec_ste (vector unsigned char, int, unsigned char *); 9321146895Skanvoid vec_ste (vector bool char, int, signed char *); 9322146895Skanvoid vec_ste (vector bool char, int, unsigned char *); 932390075Sobrienvoid vec_ste (vector signed short, int, short *); 9324146895Skanvoid vec_ste (vector unsigned short, int, unsigned short *); 9325146895Skanvoid vec_ste (vector bool short, int, short *); 9326146895Skanvoid vec_ste (vector bool short, int, unsigned short *); 9327146895Skanvoid vec_ste (vector pixel, int, short *); 9328146895Skanvoid vec_ste (vector pixel, int, unsigned short *); 9329146895Skanvoid vec_ste (vector float, int, float *); 933090075Sobrienvoid vec_ste (vector signed int, int, int *); 933190075Sobrienvoid vec_ste (vector unsigned int, int, unsigned int *); 9332146895Skanvoid vec_ste (vector bool int, int, int *); 9333146895Skanvoid vec_ste (vector bool int, int, unsigned int *); 933490075Sobrien 9335146895Skanvoid vec_stvewx (vector float, int, float *); 9336146895Skanvoid vec_stvewx (vector signed int, int, int *); 9337146895Skanvoid vec_stvewx (vector unsigned int, int, unsigned int *); 9338146895Skanvoid vec_stvewx (vector bool int, int, int *); 9339146895Skanvoid vec_stvewx (vector bool int, int, unsigned int *); 9340146895Skan 9341146895Skanvoid vec_stvehx (vector signed short, int, short *); 9342146895Skanvoid vec_stvehx (vector unsigned short, int, unsigned short *); 9343146895Skanvoid vec_stvehx (vector bool short, int, short *); 9344146895Skanvoid vec_stvehx (vector bool short, int, unsigned short *); 9345146895Skanvoid vec_stvehx (vector pixel, int, short *); 9346146895Skanvoid vec_stvehx (vector pixel, int, unsigned short *); 9347146895Skan 9348146895Skanvoid vec_stvebx (vector signed char, int, signed char *); 9349146895Skanvoid vec_stvebx (vector unsigned char, int, unsigned char *); 9350146895Skanvoid vec_stvebx (vector bool char, int, signed char *); 9351146895Skanvoid vec_stvebx (vector bool char, int, unsigned char *); 9352146895Skan 935390075Sobrienvoid vec_stl (vector float, int, vector float *); 935490075Sobrienvoid vec_stl (vector float, int, float *); 935590075Sobrienvoid vec_stl (vector signed int, int, vector signed int *); 935690075Sobrienvoid vec_stl (vector signed int, int, int *); 935790075Sobrienvoid vec_stl (vector unsigned int, int, vector unsigned int *); 935890075Sobrienvoid vec_stl (vector unsigned int, int, unsigned int *); 9359146895Skanvoid vec_stl (vector bool int, int, vector bool int *); 9360146895Skanvoid vec_stl (vector bool int, int, unsigned int *); 9361146895Skanvoid vec_stl (vector bool int, int, int *); 9362146895Skanvoid vec_stl (vector signed short, int, vector signed short *); 936390075Sobrienvoid vec_stl (vector signed short, int, short *); 9364146895Skanvoid vec_stl (vector unsigned short, int, vector unsigned short *); 936590075Sobrienvoid vec_stl (vector unsigned short, int, unsigned short *); 9366146895Skanvoid vec_stl (vector bool short, int, vector bool short *); 9367146895Skanvoid vec_stl (vector bool short, int, unsigned short *); 9368146895Skanvoid vec_stl (vector bool short, int, short *); 9369146895Skanvoid vec_stl (vector pixel, int, vector pixel *); 9370146895Skanvoid vec_stl (vector pixel, int, unsigned short *); 9371146895Skanvoid vec_stl (vector pixel, int, short *); 9372146895Skanvoid vec_stl (vector signed char, int, vector signed char *); 937390075Sobrienvoid vec_stl (vector signed char, int, signed char *); 9374146895Skanvoid vec_stl (vector unsigned char, int, vector unsigned char *); 937590075Sobrienvoid vec_stl (vector unsigned char, int, unsigned char *); 9376146895Skanvoid vec_stl (vector bool char, int, vector bool char *); 9377146895Skanvoid vec_stl (vector bool char, int, unsigned char *); 9378146895Skanvoid vec_stl (vector bool char, int, signed char *); 937990075Sobrien 9380146895Skanvector signed char vec_sub (vector bool char, vector signed char); 9381146895Skanvector signed char vec_sub (vector signed char, vector bool char); 938290075Sobrienvector signed char vec_sub (vector signed char, vector signed char); 9383146895Skanvector unsigned char vec_sub (vector bool char, vector unsigned char); 9384146895Skanvector unsigned char vec_sub (vector unsigned char, vector bool char); 938596263Sobrienvector unsigned char vec_sub (vector unsigned char, 938696263Sobrien vector unsigned char); 9387146895Skanvector signed short vec_sub (vector bool short, vector signed short); 9388146895Skanvector signed short vec_sub (vector signed short, vector bool short); 938990075Sobrienvector signed short vec_sub (vector signed short, vector signed short); 9390146895Skanvector unsigned short vec_sub (vector bool short, 939196263Sobrien vector unsigned short); 939296263Sobrienvector unsigned short vec_sub (vector unsigned short, 9393146895Skan vector bool short); 939496263Sobrienvector unsigned short vec_sub (vector unsigned short, 939596263Sobrien vector unsigned short); 9396146895Skanvector signed int vec_sub (vector bool int, vector signed int); 9397146895Skanvector signed int vec_sub (vector signed int, vector bool int); 939890075Sobrienvector signed int vec_sub (vector signed int, vector signed int); 9399146895Skanvector unsigned int vec_sub (vector bool int, vector unsigned int); 9400146895Skanvector unsigned int vec_sub (vector unsigned int, vector bool int); 940190075Sobrienvector unsigned int vec_sub (vector unsigned int, vector unsigned int); 940290075Sobrienvector float vec_sub (vector float, vector float); 940390075Sobrien 9404146895Skanvector float vec_vsubfp (vector float, vector float); 9405146895Skan 9406146895Skanvector signed int vec_vsubuwm (vector bool int, vector signed int); 9407146895Skanvector signed int vec_vsubuwm (vector signed int, vector bool int); 9408146895Skanvector signed int vec_vsubuwm (vector signed int, vector signed int); 9409146895Skanvector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); 9410146895Skanvector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); 9411146895Skanvector unsigned int vec_vsubuwm (vector unsigned int, 9412146895Skan vector unsigned int); 9413146895Skan 9414146895Skanvector signed short vec_vsubuhm (vector bool short, 9415146895Skan vector signed short); 9416146895Skanvector signed short vec_vsubuhm (vector signed short, 9417146895Skan vector bool short); 9418146895Skanvector signed short vec_vsubuhm (vector signed short, 9419146895Skan vector signed short); 9420146895Skanvector unsigned short vec_vsubuhm (vector bool short, 9421146895Skan vector unsigned short); 9422146895Skanvector unsigned short vec_vsubuhm (vector unsigned short, 9423146895Skan vector bool short); 9424146895Skanvector unsigned short vec_vsubuhm (vector unsigned short, 9425146895Skan vector unsigned short); 9426146895Skan 9427146895Skanvector signed char vec_vsububm (vector bool char, vector signed char); 9428146895Skanvector signed char vec_vsububm (vector signed char, vector bool char); 9429146895Skanvector signed char vec_vsububm (vector signed char, vector signed char); 9430146895Skanvector unsigned char vec_vsububm (vector bool char, 9431146895Skan vector unsigned char); 9432146895Skanvector unsigned char vec_vsububm (vector unsigned char, 9433146895Skan vector bool char); 9434146895Skanvector unsigned char vec_vsububm (vector unsigned char, 9435146895Skan vector unsigned char); 9436146895Skan 943790075Sobrienvector unsigned int vec_subc (vector unsigned int, vector unsigned int); 943890075Sobrien 9439146895Skanvector unsigned char vec_subs (vector bool char, vector unsigned char); 9440146895Skanvector unsigned char vec_subs (vector unsigned char, vector bool char); 944196263Sobrienvector unsigned char vec_subs (vector unsigned char, 944296263Sobrien vector unsigned char); 9443146895Skanvector signed char vec_subs (vector bool char, vector signed char); 9444146895Skanvector signed char vec_subs (vector signed char, vector bool char); 944590075Sobrienvector signed char vec_subs (vector signed char, vector signed char); 9446146895Skanvector unsigned short vec_subs (vector bool short, 944796263Sobrien vector unsigned short); 944896263Sobrienvector unsigned short vec_subs (vector unsigned short, 9449146895Skan vector bool short); 945096263Sobrienvector unsigned short vec_subs (vector unsigned short, 945196263Sobrien vector unsigned short); 9452146895Skanvector signed short vec_subs (vector bool short, vector signed short); 9453146895Skanvector signed short vec_subs (vector signed short, vector bool short); 945490075Sobrienvector signed short vec_subs (vector signed short, vector signed short); 9455146895Skanvector unsigned int vec_subs (vector bool int, vector unsigned int); 9456146895Skanvector unsigned int vec_subs (vector unsigned int, vector bool int); 945790075Sobrienvector unsigned int vec_subs (vector unsigned int, vector unsigned int); 9458146895Skanvector signed int vec_subs (vector bool int, vector signed int); 9459146895Skanvector signed int vec_subs (vector signed int, vector bool int); 946090075Sobrienvector signed int vec_subs (vector signed int, vector signed int); 946190075Sobrien 9462146895Skanvector signed int vec_vsubsws (vector bool int, vector signed int); 9463146895Skanvector signed int vec_vsubsws (vector signed int, vector bool int); 9464146895Skanvector signed int vec_vsubsws (vector signed int, vector signed int); 9465146895Skan 9466146895Skanvector unsigned int vec_vsubuws (vector bool int, vector unsigned int); 9467146895Skanvector unsigned int vec_vsubuws (vector unsigned int, vector bool int); 9468146895Skanvector unsigned int vec_vsubuws (vector unsigned int, 9469146895Skan vector unsigned int); 9470146895Skan 9471146895Skanvector signed short vec_vsubshs (vector bool short, 9472146895Skan vector signed short); 9473146895Skanvector signed short vec_vsubshs (vector signed short, 9474146895Skan vector bool short); 9475146895Skanvector signed short vec_vsubshs (vector signed short, 9476146895Skan vector signed short); 9477146895Skan 9478146895Skanvector unsigned short vec_vsubuhs (vector bool short, 9479146895Skan vector unsigned short); 9480146895Skanvector unsigned short vec_vsubuhs (vector unsigned short, 9481146895Skan vector bool short); 9482146895Skanvector unsigned short vec_vsubuhs (vector unsigned short, 9483146895Skan vector unsigned short); 9484146895Skan 9485146895Skanvector signed char vec_vsubsbs (vector bool char, vector signed char); 9486146895Skanvector signed char vec_vsubsbs (vector signed char, vector bool char); 9487146895Skanvector signed char vec_vsubsbs (vector signed char, vector signed char); 9488146895Skan 9489146895Skanvector unsigned char vec_vsububs (vector bool char, 9490146895Skan vector unsigned char); 9491146895Skanvector unsigned char vec_vsububs (vector unsigned char, 9492146895Skan vector bool char); 9493146895Skanvector unsigned char vec_vsububs (vector unsigned char, 9494146895Skan vector unsigned char); 9495146895Skan 949696263Sobrienvector unsigned int vec_sum4s (vector unsigned char, 949796263Sobrien vector unsigned int); 949890075Sobrienvector signed int vec_sum4s (vector signed char, vector signed int); 949990075Sobrienvector signed int vec_sum4s (vector signed short, vector signed int); 950090075Sobrien 9501146895Skanvector signed int vec_vsum4shs (vector signed short, vector signed int); 9502146895Skan 9503146895Skanvector signed int vec_vsum4sbs (vector signed char, vector signed int); 9504146895Skan 9505146895Skanvector unsigned int vec_vsum4ubs (vector unsigned char, 9506146895Skan vector unsigned int); 9507146895Skan 950890075Sobrienvector signed int vec_sum2s (vector signed int, vector signed int); 950990075Sobrien 951090075Sobrienvector signed int vec_sums (vector signed int, vector signed int); 951190075Sobrien 951290075Sobrienvector float vec_trunc (vector float); 951390075Sobrien 951490075Sobrienvector signed short vec_unpackh (vector signed char); 9515146895Skanvector bool short vec_unpackh (vector bool char); 951690075Sobrienvector signed int vec_unpackh (vector signed short); 9517146895Skanvector bool int vec_unpackh (vector bool short); 9518146895Skanvector unsigned int vec_unpackh (vector pixel); 951990075Sobrien 9520146895Skanvector bool int vec_vupkhsh (vector bool short); 9521146895Skanvector signed int vec_vupkhsh (vector signed short); 9522146895Skan 9523146895Skanvector unsigned int vec_vupkhpx (vector pixel); 9524146895Skan 9525146895Skanvector bool short vec_vupkhsb (vector bool char); 9526146895Skanvector signed short vec_vupkhsb (vector signed char); 9527146895Skan 952890075Sobrienvector signed short vec_unpackl (vector signed char); 9529146895Skanvector bool short vec_unpackl (vector bool char); 9530146895Skanvector unsigned int vec_unpackl (vector pixel); 953190075Sobrienvector signed int vec_unpackl (vector signed short); 9532146895Skanvector bool int vec_unpackl (vector bool short); 953390075Sobrien 9534146895Skanvector unsigned int vec_vupklpx (vector pixel); 9535146895Skan 9536146895Skanvector bool int vec_vupklsh (vector bool short); 9537146895Skanvector signed int vec_vupklsh (vector signed short); 9538146895Skan 9539146895Skanvector bool short vec_vupklsb (vector bool char); 9540146895Skanvector signed short vec_vupklsb (vector signed char); 9541146895Skan 954290075Sobrienvector float vec_xor (vector float, vector float); 9543146895Skanvector float vec_xor (vector float, vector bool int); 9544146895Skanvector float vec_xor (vector bool int, vector float); 9545146895Skanvector bool int vec_xor (vector bool int, vector bool int); 9546146895Skanvector signed int vec_xor (vector bool int, vector signed int); 9547146895Skanvector signed int vec_xor (vector signed int, vector bool int); 954890075Sobrienvector signed int vec_xor (vector signed int, vector signed int); 9549146895Skanvector unsigned int vec_xor (vector bool int, vector unsigned int); 9550146895Skanvector unsigned int vec_xor (vector unsigned int, vector bool int); 955190075Sobrienvector unsigned int vec_xor (vector unsigned int, vector unsigned int); 9552146895Skanvector bool short vec_xor (vector bool short, vector bool short); 9553146895Skanvector signed short vec_xor (vector bool short, vector signed short); 9554146895Skanvector signed short vec_xor (vector signed short, vector bool short); 955590075Sobrienvector signed short vec_xor (vector signed short, vector signed short); 9556146895Skanvector unsigned short vec_xor (vector bool short, 955796263Sobrien vector unsigned short); 955896263Sobrienvector unsigned short vec_xor (vector unsigned short, 9559146895Skan vector bool short); 956096263Sobrienvector unsigned short vec_xor (vector unsigned short, 956196263Sobrien vector unsigned short); 9562146895Skanvector signed char vec_xor (vector bool char, vector signed char); 9563146895Skanvector bool char vec_xor (vector bool char, vector bool char); 9564146895Skanvector signed char vec_xor (vector signed char, vector bool char); 956590075Sobrienvector signed char vec_xor (vector signed char, vector signed char); 9566146895Skanvector unsigned char vec_xor (vector bool char, vector unsigned char); 9567146895Skanvector unsigned char vec_xor (vector unsigned char, vector bool char); 956896263Sobrienvector unsigned char vec_xor (vector unsigned char, 956996263Sobrien vector unsigned char); 957090075Sobrien 9571146895Skanint vec_all_eq (vector signed char, vector bool char); 9572146895Skanint vec_all_eq (vector signed char, vector signed char); 9573146895Skanint vec_all_eq (vector unsigned char, vector bool char); 9574146895Skanint vec_all_eq (vector unsigned char, vector unsigned char); 9575146895Skanint vec_all_eq (vector bool char, vector bool char); 9576146895Skanint vec_all_eq (vector bool char, vector unsigned char); 9577146895Skanint vec_all_eq (vector bool char, vector signed char); 9578146895Skanint vec_all_eq (vector signed short, vector bool short); 9579146895Skanint vec_all_eq (vector signed short, vector signed short); 9580146895Skanint vec_all_eq (vector unsigned short, vector bool short); 9581146895Skanint vec_all_eq (vector unsigned short, vector unsigned short); 9582146895Skanint vec_all_eq (vector bool short, vector bool short); 9583146895Skanint vec_all_eq (vector bool short, vector unsigned short); 9584146895Skanint vec_all_eq (vector bool short, vector signed short); 9585146895Skanint vec_all_eq (vector pixel, vector pixel); 9586146895Skanint vec_all_eq (vector signed int, vector bool int); 9587146895Skanint vec_all_eq (vector signed int, vector signed int); 9588146895Skanint vec_all_eq (vector unsigned int, vector bool int); 9589146895Skanint vec_all_eq (vector unsigned int, vector unsigned int); 9590146895Skanint vec_all_eq (vector bool int, vector bool int); 9591146895Skanint vec_all_eq (vector bool int, vector unsigned int); 9592146895Skanint vec_all_eq (vector bool int, vector signed int); 9593146895Skanint vec_all_eq (vector float, vector float); 959490075Sobrien 9595146895Skanint vec_all_ge (vector bool char, vector unsigned char); 9596146895Skanint vec_all_ge (vector unsigned char, vector bool char); 9597146895Skanint vec_all_ge (vector unsigned char, vector unsigned char); 9598146895Skanint vec_all_ge (vector bool char, vector signed char); 9599146895Skanint vec_all_ge (vector signed char, vector bool char); 9600146895Skanint vec_all_ge (vector signed char, vector signed char); 9601146895Skanint vec_all_ge (vector bool short, vector unsigned short); 9602146895Skanint vec_all_ge (vector unsigned short, vector bool short); 9603146895Skanint vec_all_ge (vector unsigned short, vector unsigned short); 9604146895Skanint vec_all_ge (vector signed short, vector signed short); 9605146895Skanint vec_all_ge (vector bool short, vector signed short); 9606146895Skanint vec_all_ge (vector signed short, vector bool short); 9607146895Skanint vec_all_ge (vector bool int, vector unsigned int); 9608146895Skanint vec_all_ge (vector unsigned int, vector bool int); 9609146895Skanint vec_all_ge (vector unsigned int, vector unsigned int); 9610146895Skanint vec_all_ge (vector bool int, vector signed int); 9611146895Skanint vec_all_ge (vector signed int, vector bool int); 9612146895Skanint vec_all_ge (vector signed int, vector signed int); 9613146895Skanint vec_all_ge (vector float, vector float); 961490075Sobrien 9615146895Skanint vec_all_gt (vector bool char, vector unsigned char); 9616146895Skanint vec_all_gt (vector unsigned char, vector bool char); 9617146895Skanint vec_all_gt (vector unsigned char, vector unsigned char); 9618146895Skanint vec_all_gt (vector bool char, vector signed char); 9619146895Skanint vec_all_gt (vector signed char, vector bool char); 9620146895Skanint vec_all_gt (vector signed char, vector signed char); 9621146895Skanint vec_all_gt (vector bool short, vector unsigned short); 9622146895Skanint vec_all_gt (vector unsigned short, vector bool short); 9623146895Skanint vec_all_gt (vector unsigned short, vector unsigned short); 9624146895Skanint vec_all_gt (vector bool short, vector signed short); 9625146895Skanint vec_all_gt (vector signed short, vector bool short); 9626146895Skanint vec_all_gt (vector signed short, vector signed short); 9627146895Skanint vec_all_gt (vector bool int, vector unsigned int); 9628146895Skanint vec_all_gt (vector unsigned int, vector bool int); 9629146895Skanint vec_all_gt (vector unsigned int, vector unsigned int); 9630146895Skanint vec_all_gt (vector bool int, vector signed int); 9631146895Skanint vec_all_gt (vector signed int, vector bool int); 9632146895Skanint vec_all_gt (vector signed int, vector signed int); 9633146895Skanint vec_all_gt (vector float, vector float); 963490075Sobrien 9635146895Skanint vec_all_in (vector float, vector float); 963690075Sobrien 9637146895Skanint vec_all_le (vector bool char, vector unsigned char); 9638146895Skanint vec_all_le (vector unsigned char, vector bool char); 9639146895Skanint vec_all_le (vector unsigned char, vector unsigned char); 9640146895Skanint vec_all_le (vector bool char, vector signed char); 9641146895Skanint vec_all_le (vector signed char, vector bool char); 9642146895Skanint vec_all_le (vector signed char, vector signed char); 9643146895Skanint vec_all_le (vector bool short, vector unsigned short); 9644146895Skanint vec_all_le (vector unsigned short, vector bool short); 9645146895Skanint vec_all_le (vector unsigned short, vector unsigned short); 9646146895Skanint vec_all_le (vector bool short, vector signed short); 9647146895Skanint vec_all_le (vector signed short, vector bool short); 9648146895Skanint vec_all_le (vector signed short, vector signed short); 9649146895Skanint vec_all_le (vector bool int, vector unsigned int); 9650146895Skanint vec_all_le (vector unsigned int, vector bool int); 9651146895Skanint vec_all_le (vector unsigned int, vector unsigned int); 9652146895Skanint vec_all_le (vector bool int, vector signed int); 9653146895Skanint vec_all_le (vector signed int, vector bool int); 9654146895Skanint vec_all_le (vector signed int, vector signed int); 9655146895Skanint vec_all_le (vector float, vector float); 965690075Sobrien 9657146895Skanint vec_all_lt (vector bool char, vector unsigned char); 9658146895Skanint vec_all_lt (vector unsigned char, vector bool char); 9659146895Skanint vec_all_lt (vector unsigned char, vector unsigned char); 9660146895Skanint vec_all_lt (vector bool char, vector signed char); 9661146895Skanint vec_all_lt (vector signed char, vector bool char); 9662146895Skanint vec_all_lt (vector signed char, vector signed char); 9663146895Skanint vec_all_lt (vector bool short, vector unsigned short); 9664146895Skanint vec_all_lt (vector unsigned short, vector bool short); 9665146895Skanint vec_all_lt (vector unsigned short, vector unsigned short); 9666146895Skanint vec_all_lt (vector bool short, vector signed short); 9667146895Skanint vec_all_lt (vector signed short, vector bool short); 9668146895Skanint vec_all_lt (vector signed short, vector signed short); 9669146895Skanint vec_all_lt (vector bool int, vector unsigned int); 9670146895Skanint vec_all_lt (vector unsigned int, vector bool int); 9671146895Skanint vec_all_lt (vector unsigned int, vector unsigned int); 9672146895Skanint vec_all_lt (vector bool int, vector signed int); 9673146895Skanint vec_all_lt (vector signed int, vector bool int); 9674146895Skanint vec_all_lt (vector signed int, vector signed int); 9675146895Skanint vec_all_lt (vector float, vector float); 967690075Sobrien 9677146895Skanint vec_all_nan (vector float); 967890075Sobrien 9679146895Skanint vec_all_ne (vector signed char, vector bool char); 9680146895Skanint vec_all_ne (vector signed char, vector signed char); 9681146895Skanint vec_all_ne (vector unsigned char, vector bool char); 9682146895Skanint vec_all_ne (vector unsigned char, vector unsigned char); 9683146895Skanint vec_all_ne (vector bool char, vector bool char); 9684146895Skanint vec_all_ne (vector bool char, vector unsigned char); 9685146895Skanint vec_all_ne (vector bool char, vector signed char); 9686146895Skanint vec_all_ne (vector signed short, vector bool short); 9687146895Skanint vec_all_ne (vector signed short, vector signed short); 9688146895Skanint vec_all_ne (vector unsigned short, vector bool short); 9689146895Skanint vec_all_ne (vector unsigned short, vector unsigned short); 9690146895Skanint vec_all_ne (vector bool short, vector bool short); 9691146895Skanint vec_all_ne (vector bool short, vector unsigned short); 9692146895Skanint vec_all_ne (vector bool short, vector signed short); 9693146895Skanint vec_all_ne (vector pixel, vector pixel); 9694146895Skanint vec_all_ne (vector signed int, vector bool int); 9695146895Skanint vec_all_ne (vector signed int, vector signed int); 9696146895Skanint vec_all_ne (vector unsigned int, vector bool int); 9697146895Skanint vec_all_ne (vector unsigned int, vector unsigned int); 9698146895Skanint vec_all_ne (vector bool int, vector bool int); 9699146895Skanint vec_all_ne (vector bool int, vector unsigned int); 9700146895Skanint vec_all_ne (vector bool int, vector signed int); 9701146895Skanint vec_all_ne (vector float, vector float); 970290075Sobrien 9703146895Skanint vec_all_nge (vector float, vector float); 970490075Sobrien 9705146895Skanint vec_all_ngt (vector float, vector float); 970690075Sobrien 9707146895Skanint vec_all_nle (vector float, vector float); 970890075Sobrien 9709146895Skanint vec_all_nlt (vector float, vector float); 971090075Sobrien 9711146895Skanint vec_all_numeric (vector float); 971290075Sobrien 9713146895Skanint vec_any_eq (vector signed char, vector bool char); 9714146895Skanint vec_any_eq (vector signed char, vector signed char); 9715146895Skanint vec_any_eq (vector unsigned char, vector bool char); 9716146895Skanint vec_any_eq (vector unsigned char, vector unsigned char); 9717146895Skanint vec_any_eq (vector bool char, vector bool char); 9718146895Skanint vec_any_eq (vector bool char, vector unsigned char); 9719146895Skanint vec_any_eq (vector bool char, vector signed char); 9720146895Skanint vec_any_eq (vector signed short, vector bool short); 9721146895Skanint vec_any_eq (vector signed short, vector signed short); 9722146895Skanint vec_any_eq (vector unsigned short, vector bool short); 9723146895Skanint vec_any_eq (vector unsigned short, vector unsigned short); 9724146895Skanint vec_any_eq (vector bool short, vector bool short); 9725146895Skanint vec_any_eq (vector bool short, vector unsigned short); 9726146895Skanint vec_any_eq (vector bool short, vector signed short); 9727146895Skanint vec_any_eq (vector pixel, vector pixel); 9728146895Skanint vec_any_eq (vector signed int, vector bool int); 9729146895Skanint vec_any_eq (vector signed int, vector signed int); 9730146895Skanint vec_any_eq (vector unsigned int, vector bool int); 9731146895Skanint vec_any_eq (vector unsigned int, vector unsigned int); 9732146895Skanint vec_any_eq (vector bool int, vector bool int); 9733146895Skanint vec_any_eq (vector bool int, vector unsigned int); 9734146895Skanint vec_any_eq (vector bool int, vector signed int); 9735146895Skanint vec_any_eq (vector float, vector float); 973690075Sobrien 9737146895Skanint vec_any_ge (vector signed char, vector bool char); 9738146895Skanint vec_any_ge (vector unsigned char, vector bool char); 9739146895Skanint vec_any_ge (vector unsigned char, vector unsigned char); 9740146895Skanint vec_any_ge (vector signed char, vector signed char); 9741146895Skanint vec_any_ge (vector bool char, vector unsigned char); 9742146895Skanint vec_any_ge (vector bool char, vector signed char); 9743146895Skanint vec_any_ge (vector unsigned short, vector bool short); 9744146895Skanint vec_any_ge (vector unsigned short, vector unsigned short); 9745146895Skanint vec_any_ge (vector signed short, vector signed short); 9746146895Skanint vec_any_ge (vector signed short, vector bool short); 9747146895Skanint vec_any_ge (vector bool short, vector unsigned short); 9748146895Skanint vec_any_ge (vector bool short, vector signed short); 9749146895Skanint vec_any_ge (vector signed int, vector bool int); 9750146895Skanint vec_any_ge (vector unsigned int, vector bool int); 9751146895Skanint vec_any_ge (vector unsigned int, vector unsigned int); 9752146895Skanint vec_any_ge (vector signed int, vector signed int); 9753146895Skanint vec_any_ge (vector bool int, vector unsigned int); 9754146895Skanint vec_any_ge (vector bool int, vector signed int); 9755146895Skanint vec_any_ge (vector float, vector float); 975690075Sobrien 9757146895Skanint vec_any_gt (vector bool char, vector unsigned char); 9758146895Skanint vec_any_gt (vector unsigned char, vector bool char); 9759146895Skanint vec_any_gt (vector unsigned char, vector unsigned char); 9760146895Skanint vec_any_gt (vector bool char, vector signed char); 9761146895Skanint vec_any_gt (vector signed char, vector bool char); 9762146895Skanint vec_any_gt (vector signed char, vector signed char); 9763146895Skanint vec_any_gt (vector bool short, vector unsigned short); 9764146895Skanint vec_any_gt (vector unsigned short, vector bool short); 9765146895Skanint vec_any_gt (vector unsigned short, vector unsigned short); 9766146895Skanint vec_any_gt (vector bool short, vector signed short); 9767146895Skanint vec_any_gt (vector signed short, vector bool short); 9768146895Skanint vec_any_gt (vector signed short, vector signed short); 9769146895Skanint vec_any_gt (vector bool int, vector unsigned int); 9770146895Skanint vec_any_gt (vector unsigned int, vector bool int); 9771146895Skanint vec_any_gt (vector unsigned int, vector unsigned int); 9772146895Skanint vec_any_gt (vector bool int, vector signed int); 9773146895Skanint vec_any_gt (vector signed int, vector bool int); 9774146895Skanint vec_any_gt (vector signed int, vector signed int); 9775146895Skanint vec_any_gt (vector float, vector float); 977690075Sobrien 9777146895Skanint vec_any_le (vector bool char, vector unsigned char); 9778146895Skanint vec_any_le (vector unsigned char, vector bool char); 9779146895Skanint vec_any_le (vector unsigned char, vector unsigned char); 9780146895Skanint vec_any_le (vector bool char, vector signed char); 9781146895Skanint vec_any_le (vector signed char, vector bool char); 9782146895Skanint vec_any_le (vector signed char, vector signed char); 9783146895Skanint vec_any_le (vector bool short, vector unsigned short); 9784146895Skanint vec_any_le (vector unsigned short, vector bool short); 9785146895Skanint vec_any_le (vector unsigned short, vector unsigned short); 9786146895Skanint vec_any_le (vector bool short, vector signed short); 9787146895Skanint vec_any_le (vector signed short, vector bool short); 9788146895Skanint vec_any_le (vector signed short, vector signed short); 9789146895Skanint vec_any_le (vector bool int, vector unsigned int); 9790146895Skanint vec_any_le (vector unsigned int, vector bool int); 9791146895Skanint vec_any_le (vector unsigned int, vector unsigned int); 9792146895Skanint vec_any_le (vector bool int, vector signed int); 9793146895Skanint vec_any_le (vector signed int, vector bool int); 9794146895Skanint vec_any_le (vector signed int, vector signed int); 9795146895Skanint vec_any_le (vector float, vector float); 979690075Sobrien 9797146895Skanint vec_any_lt (vector bool char, vector unsigned char); 9798146895Skanint vec_any_lt (vector unsigned char, vector bool char); 9799146895Skanint vec_any_lt (vector unsigned char, vector unsigned char); 9800146895Skanint vec_any_lt (vector bool char, vector signed char); 9801146895Skanint vec_any_lt (vector signed char, vector bool char); 9802146895Skanint vec_any_lt (vector signed char, vector signed char); 9803146895Skanint vec_any_lt (vector bool short, vector unsigned short); 9804146895Skanint vec_any_lt (vector unsigned short, vector bool short); 9805146895Skanint vec_any_lt (vector unsigned short, vector unsigned short); 9806146895Skanint vec_any_lt (vector bool short, vector signed short); 9807146895Skanint vec_any_lt (vector signed short, vector bool short); 9808146895Skanint vec_any_lt (vector signed short, vector signed short); 9809146895Skanint vec_any_lt (vector bool int, vector unsigned int); 9810146895Skanint vec_any_lt (vector unsigned int, vector bool int); 9811146895Skanint vec_any_lt (vector unsigned int, vector unsigned int); 9812146895Skanint vec_any_lt (vector bool int, vector signed int); 9813146895Skanint vec_any_lt (vector signed int, vector bool int); 9814146895Skanint vec_any_lt (vector signed int, vector signed int); 9815146895Skanint vec_any_lt (vector float, vector float); 981690075Sobrien 9817146895Skanint vec_any_nan (vector float); 981890075Sobrien 9819146895Skanint vec_any_ne (vector signed char, vector bool char); 9820146895Skanint vec_any_ne (vector signed char, vector signed char); 9821146895Skanint vec_any_ne (vector unsigned char, vector bool char); 9822146895Skanint vec_any_ne (vector unsigned char, vector unsigned char); 9823146895Skanint vec_any_ne (vector bool char, vector bool char); 9824146895Skanint vec_any_ne (vector bool char, vector unsigned char); 9825146895Skanint vec_any_ne (vector bool char, vector signed char); 9826146895Skanint vec_any_ne (vector signed short, vector bool short); 9827146895Skanint vec_any_ne (vector signed short, vector signed short); 9828146895Skanint vec_any_ne (vector unsigned short, vector bool short); 9829146895Skanint vec_any_ne (vector unsigned short, vector unsigned short); 9830146895Skanint vec_any_ne (vector bool short, vector bool short); 9831146895Skanint vec_any_ne (vector bool short, vector unsigned short); 9832146895Skanint vec_any_ne (vector bool short, vector signed short); 9833146895Skanint vec_any_ne (vector pixel, vector pixel); 9834146895Skanint vec_any_ne (vector signed int, vector bool int); 9835146895Skanint vec_any_ne (vector signed int, vector signed int); 9836146895Skanint vec_any_ne (vector unsigned int, vector bool int); 9837146895Skanint vec_any_ne (vector unsigned int, vector unsigned int); 9838146895Skanint vec_any_ne (vector bool int, vector bool int); 9839146895Skanint vec_any_ne (vector bool int, vector unsigned int); 9840146895Skanint vec_any_ne (vector bool int, vector signed int); 9841146895Skanint vec_any_ne (vector float, vector float); 984290075Sobrien 9843146895Skanint vec_any_nge (vector float, vector float); 984490075Sobrien 9845146895Skanint vec_any_ngt (vector float, vector float); 984690075Sobrien 9847146895Skanint vec_any_nle (vector float, vector float); 984890075Sobrien 9849146895Skanint vec_any_nlt (vector float, vector float); 985090075Sobrien 9851146895Skanint vec_any_numeric (vector float); 985290075Sobrien 9853146895Skanint vec_any_out (vector float, vector float); 985490075Sobrien@end smallexample 985590075Sobrien 9856169689Skan@node SPARC VIS Built-in Functions 9857169689Skan@subsection SPARC VIS Built-in Functions 9858169689Skan 9859169689SkanGCC supports SIMD operations on the SPARC using both the generic vector 9860169689Skanextensions (@pxref{Vector Extensions}) as well as built-in functions for 9861169689Skanthe SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} 9862169689Skanswitch, the VIS extension is exposed as the following built-in functions: 9863169689Skan 9864169689Skan@smallexample 9865169689Skantypedef int v2si __attribute__ ((vector_size (8))); 9866169689Skantypedef short v4hi __attribute__ ((vector_size (8))); 9867169689Skantypedef short v2hi __attribute__ ((vector_size (4))); 9868169689Skantypedef char v8qi __attribute__ ((vector_size (8))); 9869169689Skantypedef char v4qi __attribute__ ((vector_size (4))); 9870169689Skan 9871169689Skanvoid * __builtin_vis_alignaddr (void *, long); 9872169689Skanint64_t __builtin_vis_faligndatadi (int64_t, int64_t); 9873169689Skanv2si __builtin_vis_faligndatav2si (v2si, v2si); 9874169689Skanv4hi __builtin_vis_faligndatav4hi (v4si, v4si); 9875169689Skanv8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); 9876169689Skan 9877169689Skanv4hi __builtin_vis_fexpand (v4qi); 9878169689Skan 9879169689Skanv4hi __builtin_vis_fmul8x16 (v4qi, v4hi); 9880169689Skanv4hi __builtin_vis_fmul8x16au (v4qi, v4hi); 9881169689Skanv4hi __builtin_vis_fmul8x16al (v4qi, v4hi); 9882169689Skanv4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); 9883169689Skanv4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); 9884169689Skanv2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); 9885169689Skanv2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); 9886169689Skan 9887169689Skanv4qi __builtin_vis_fpack16 (v4hi); 9888169689Skanv8qi __builtin_vis_fpack32 (v2si, v2si); 9889169689Skanv2hi __builtin_vis_fpackfix (v2si); 9890169689Skanv8qi __builtin_vis_fpmerge (v4qi, v4qi); 9891169689Skan 9892169689Skanint64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); 9893169689Skan@end smallexample 9894169689Skan 9895169689Skan@node Target Format Checks 9896169689Skan@section Format Checks Specific to Particular Target Machines 9897169689Skan 9898169689SkanFor some target machines, GCC supports additional options to the 9899169689Skanformat attribute 9900169689Skan(@pxref{Function Attributes,,Declaring Attributes of Functions}). 9901169689Skan 9902169689Skan@menu 9903169689Skan* Solaris Format Checks:: 9904169689Skan@end menu 9905169689Skan 9906169689Skan@node Solaris Format Checks 9907169689Skan@subsection Solaris Format Checks 9908169689Skan 9909169689SkanSolaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format 9910169689Skancheck. @code{cmn_err} accepts a subset of the standard @code{printf} 9911169689Skanconversions, and the two-argument @code{%b} conversion for displaying 9912169689Skanbit-fields. See the Solaris man page for @code{cmn_err} for more information. 9913169689Skan 991490075Sobrien@node Pragmas 991590075Sobrien@section Pragmas Accepted by GCC 991690075Sobrien@cindex pragmas 991790075Sobrien@cindex #pragma 991890075Sobrien 991990075SobrienGCC supports several types of pragmas, primarily in order to compile 992090075Sobriencode originally written for other compilers. Note that in general 992190075Sobrienwe do not recommend the use of pragmas; @xref{Function Attributes}, 992290075Sobrienfor further explanation. 992390075Sobrien 992490075Sobrien@menu 992590075Sobrien* ARM Pragmas:: 9926169689Skan* M32C Pragmas:: 9927117395Skan* RS/6000 and PowerPC Pragmas:: 992890075Sobrien* Darwin Pragmas:: 992996263Sobrien* Solaris Pragmas:: 9930169689Skan* Symbol-Renaming Pragmas:: 9931169689Skan* Structure-Packing Pragmas:: 9932169689Skan* Weak Pragmas:: 9933169689Skan* Diagnostic Pragmas:: 9934169689Skan* Visibility Pragmas:: 993590075Sobrien@end menu 993690075Sobrien 993790075Sobrien@node ARM Pragmas 993890075Sobrien@subsection ARM Pragmas 993990075Sobrien 994090075SobrienThe ARM target defines pragmas for controlling the default addition of 994190075Sobrien@code{long_call} and @code{short_call} attributes to functions. 994290075Sobrien@xref{Function Attributes}, for information about the effects of these 994390075Sobrienattributes. 994490075Sobrien 994590075Sobrien@table @code 994690075Sobrien@item long_calls 994790075Sobrien@cindex pragma, long_calls 994890075SobrienSet all subsequent functions to have the @code{long_call} attribute. 994990075Sobrien 995090075Sobrien@item no_long_calls 995190075Sobrien@cindex pragma, no_long_calls 995290075SobrienSet all subsequent functions to have the @code{short_call} attribute. 995390075Sobrien 995490075Sobrien@item long_calls_off 995590075Sobrien@cindex pragma, long_calls_off 995690075SobrienDo not affect the @code{long_call} or @code{short_call} attributes of 995790075Sobriensubsequent functions. 995890075Sobrien@end table 995990075Sobrien 9960169689Skan@node M32C Pragmas 9961169689Skan@subsection M32C Pragmas 9962169689Skan 9963169689Skan@table @code 9964169689Skan@item memregs @var{number} 9965169689Skan@cindex pragma, memregs 9966169689SkanOverrides the command line option @code{-memregs=} for the current 9967169689Skanfile. Use with care! This pragma must be before any function in the 9968169689Skanfile, and mixing different memregs values in different objects may 9969169689Skanmake them incompatible. This pragma is useful when a 9970169689Skanperformance-critical function uses a memreg for temporary values, 9971169689Skanas it may allow you to reduce the number of memregs used. 9972169689Skan 9973169689Skan@end table 9974169689Skan 9975117395Skan@node RS/6000 and PowerPC Pragmas 9976117395Skan@subsection RS/6000 and PowerPC Pragmas 9977117395Skan 9978117395SkanThe RS/6000 and PowerPC targets define one pragma for controlling 9979117395Skanwhether or not the @code{longcall} attribute is added to function 9980117395Skandeclarations by default. This pragma overrides the @option{-mlongcall} 9981117395Skanoption, but not the @code{longcall} and @code{shortcall} attributes. 9982117395Skan@xref{RS/6000 and PowerPC Options}, for more information about when long 9983117395Skancalls are and are not necessary. 9984117395Skan 9985117395Skan@table @code 9986117395Skan@item longcall (1) 9987117395Skan@cindex pragma, longcall 9988117395SkanApply the @code{longcall} attribute to all subsequent function 9989117395Skandeclarations. 9990117395Skan 9991117395Skan@item longcall (0) 9992117395SkanDo not apply the @code{longcall} attribute to subsequent function 9993117395Skandeclarations. 9994117395Skan@end table 9995117395Skan 999690075Sobrien@c Describe c4x pragmas here. 999790075Sobrien@c Describe h8300 pragmas here. 999890075Sobrien@c Describe sh pragmas here. 999990075Sobrien@c Describe v850 pragmas here. 1000090075Sobrien 1000190075Sobrien@node Darwin Pragmas 1000290075Sobrien@subsection Darwin Pragmas 1000390075Sobrien 1000490075SobrienThe following pragmas are available for all architectures running the 1000590075SobrienDarwin operating system. These are useful for compatibility with other 10006117395SkanMac OS compilers. 1000790075Sobrien 1000890075Sobrien@table @code 1000990075Sobrien@item mark @var{tokens}@dots{} 1001090075Sobrien@cindex pragma, mark 1001190075SobrienThis pragma is accepted, but has no effect. 1001290075Sobrien 1001390075Sobrien@item options align=@var{alignment} 1001490075Sobrien@cindex pragma, options align 1001590075SobrienThis pragma sets the alignment of fields in structures. The values of 1001690075Sobrien@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or 1001790075Sobrien@code{power}, to emulate PowerPC alignment. Uses of this pragma nest 1001890075Sobrienproperly; to restore the previous setting, use @code{reset} for the 1001990075Sobrien@var{alignment}. 1002090075Sobrien 1002190075Sobrien@item segment @var{tokens}@dots{} 1002290075Sobrien@cindex pragma, segment 1002390075SobrienThis pragma is accepted, but has no effect. 1002490075Sobrien 1002590075Sobrien@item unused (@var{var} [, @var{var}]@dots{}) 1002690075Sobrien@cindex pragma, unused 1002790075SobrienThis pragma declares variables to be possibly unused. GCC will not 1002890075Sobrienproduce warnings for the listed variables. The effect is similar to 1002990075Sobrienthat of the @code{unused} attribute, except that this pragma may appear 1003090075Sobrienanywhere within the variables' scopes. 1003190075Sobrien@end table 1003290075Sobrien 1003396263Sobrien@node Solaris Pragmas 1003496263Sobrien@subsection Solaris Pragmas 1003596263Sobrien 10036169689SkanThe Solaris target supports @code{#pragma redefine_extname} 10037169689Skan(@pxref{Symbol-Renaming Pragmas}). It also supports additional 10038169689Skan@code{#pragma} directives for compatibility with the system compiler. 1003996263Sobrien 1004096263Sobrien@table @code 10041169689Skan@item align @var{alignment} (@var{variable} [, @var{variable}]...) 10042169689Skan@cindex pragma, align 1004396263Sobrien 10044169689SkanIncrease the minimum alignment of each @var{variable} to @var{alignment}. 10045169689SkanThis is the same as GCC's @code{aligned} attribute @pxref{Variable 10046169689SkanAttributes}). Macro expansion occurs on the arguments to this pragma 10047220755Sdimwhen compiling C. It does not currently occur when compiling C++, but 10048220755Sdimthis is a bug which may be fixed in a future release. 10049169689Skan 10050169689Skan@item fini (@var{function} [, @var{function}]...) 10051169689Skan@cindex pragma, fini 10052169689Skan 10053169689SkanThis pragma causes each listed @var{function} to be called after 10054169689Skanmain, or during shared module unloading, by adding a call to the 10055169689Skan@code{.fini} section. 10056169689Skan 10057169689Skan@item init (@var{function} [, @var{function}]...) 10058169689Skan@cindex pragma, init 10059169689Skan 10060169689SkanThis pragma causes each listed @var{function} to be called during 10061169689Skaninitialization (before @code{main}) or during shared module loading, by 10062169689Skanadding a call to the @code{.init} section. 10063169689Skan 1006496263Sobrien@end table 1006596263Sobrien 10066169689Skan@node Symbol-Renaming Pragmas 10067169689Skan@subsection Symbol-Renaming Pragmas 1006896263Sobrien 10069169689SkanFor compatibility with the Solaris and Tru64 UNIX system headers, GCC 10070169689Skansupports two @code{#pragma} directives which change the name used in 10071169689Skanassembly for a given declaration. These pragmas are only available on 10072169689Skanplatforms whose system headers need them. To get this effect on all 10073169689Skanplatforms supported by GCC, use the asm labels extension (@pxref{Asm 10074169689SkanLabels}). 1007596263Sobrien 1007696263Sobrien@table @code 10077169689Skan@item redefine_extname @var{oldname} @var{newname} 10078169689Skan@cindex pragma, redefine_extname 10079169689Skan 10080169689SkanThis pragma gives the C function @var{oldname} the assembly symbol 10081169689Skan@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} 10082169689Skanwill be defined if this pragma is available (currently only on 10083169689SkanSolaris). 10084169689Skan 1008596263Sobrien@item extern_prefix @var{string} 1008696263Sobrien@cindex pragma, extern_prefix 1008796263Sobrien 10088169689SkanThis pragma causes all subsequent external function and variable 10089169689Skandeclarations to have @var{string} prepended to their assembly symbols. 10090169689SkanThis effect may be terminated with another @code{extern_prefix} pragma 10091169689Skanwhose argument is an empty string. The preprocessor macro 10092169689Skan@code{__PRAGMA_EXTERN_PREFIX} will be defined if this pragma is 10093169689Skanavailable (currently only on Tru64 UNIX)@. 10094169689Skan@end table 1009596263Sobrien 10096169689SkanThese pragmas and the asm labels extension interact in a complicated 10097169689Skanmanner. Here are some corner cases you may want to be aware of. 10098169689Skan 10099169689Skan@enumerate 10100169689Skan@item Both pragmas silently apply only to declarations with external 10101169689Skanlinkage. Asm labels do not have this restriction. 10102169689Skan 10103169689Skan@item In C++, both pragmas silently apply only to declarations with 10104169689Skan``C'' linkage. Again, asm labels do not have this restriction. 10105169689Skan 10106169689Skan@item If any of the three ways of changing the assembly name of a 10107169689Skandeclaration is applied to a declaration whose assembly name has 10108169689Skanalready been determined (either by a previous use of one of these 10109169689Skanfeatures, or because the compiler needed the assembly name in order to 10110169689Skangenerate code), and the new name is different, a warning issues and 10111169689Skanthe name does not change. 10112169689Skan 10113169689Skan@item The @var{oldname} used by @code{#pragma redefine_extname} is 10114169689Skanalways the C-language name. 10115169689Skan 10116169689Skan@item If @code{#pragma extern_prefix} is in effect, and a declaration 10117169689Skanoccurs with an asm label attached, the prefix is silently ignored for 10118169689Skanthat declaration. 10119169689Skan 10120169689Skan@item If @code{#pragma extern_prefix} and @code{#pragma redefine_extname} 10121169689Skanapply to the same declaration, whichever triggered first wins, and a 10122169689Skanwarning issues if they contradict each other. (We would like to have 10123169689Skan@code{#pragma redefine_extname} always win, for consistency with asm 10124169689Skanlabels, but if @code{#pragma extern_prefix} triggers first we have no 10125169689Skanway of knowing that that happened.) 10126169689Skan@end enumerate 10127169689Skan 10128169689Skan@node Structure-Packing Pragmas 10129169689Skan@subsection Structure-Packing Pragmas 10130169689Skan 10131169689SkanFor compatibility with Win32, GCC supports a set of @code{#pragma} 10132169689Skandirectives which change the maximum alignment of members of structures 10133169689Skan(other than zero-width bitfields), unions, and classes subsequently 10134169689Skandefined. The @var{n} value below always is required to be a small power 10135169689Skanof two and specifies the new alignment in bytes. 10136169689Skan 10137169689Skan@enumerate 10138169689Skan@item @code{#pragma pack(@var{n})} simply sets the new alignment. 10139169689Skan@item @code{#pragma pack()} sets the alignment to the one that was in 10140169689Skaneffect when compilation started (see also command line option 10141169689Skan@option{-fpack-struct[=<n>]} @pxref{Code Gen Options}). 10142169689Skan@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment 10143169689Skansetting on an internal stack and then optionally sets the new alignment. 10144169689Skan@item @code{#pragma pack(pop)} restores the alignment setting to the one 10145169689Skansaved at the top of the internal stack (and removes that stack entry). 10146169689SkanNote that @code{#pragma pack([@var{n}])} does not influence this internal 10147169689Skanstack; thus it is possible to have @code{#pragma pack(push)} followed by 10148169689Skanmultiple @code{#pragma pack(@var{n})} instances and finalized by a single 10149169689Skan@code{#pragma pack(pop)}. 10150169689Skan@end enumerate 10151169689Skan 10152169689SkanSome targets, e.g. i386 and powerpc, support the @code{ms_struct} 10153169689Skan@code{#pragma} which lays out a structure as the documented 10154169689Skan@code{__attribute__ ((ms_struct))}. 10155169689Skan@enumerate 10156169689Skan@item @code{#pragma ms_struct on} turns on the layout for structures 10157169689Skandeclared. 10158169689Skan@item @code{#pragma ms_struct off} turns off the layout for structures 10159169689Skandeclared. 10160169689Skan@item @code{#pragma ms_struct reset} goes back to the default layout. 10161169689Skan@end enumerate 10162169689Skan 10163169689Skan@node Weak Pragmas 10164169689Skan@subsection Weak Pragmas 10165169689Skan 10166169689SkanFor compatibility with SVR4, GCC supports a set of @code{#pragma} 10167169689Skandirectives for declaring symbols to be weak, and defining weak 10168169689Skanaliases. 10169169689Skan 10170169689Skan@table @code 10171169689Skan@item #pragma weak @var{symbol} 10172169689Skan@cindex pragma, weak 10173169689SkanThis pragma declares @var{symbol} to be weak, as if the declaration 10174169689Skanhad the attribute of the same name. The pragma may appear before 10175169689Skanor after the declaration of @var{symbol}, but must appear before 10176169689Skaneither its first use or its definition. It is not an error for 10177169689Skan@var{symbol} to never be defined at all. 10178169689Skan 10179169689Skan@item #pragma weak @var{symbol1} = @var{symbol2} 10180169689SkanThis pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. 10181169689SkanIt is an error if @var{symbol2} is not defined in the current 10182169689Skantranslation unit. 1018396263Sobrien@end table 1018496263Sobrien 10185169689Skan@node Diagnostic Pragmas 10186169689Skan@subsection Diagnostic Pragmas 10187169689Skan 10188169689SkanGCC allows the user to selectively enable or disable certain types of 10189169689Skandiagnostics, and change the kind of the diagnostic. For example, a 10190169689Skanproject's policy might require that all sources compile with 10191169689Skan@option{-Werror} but certain files might have exceptions allowing 10192169689Skanspecific types of warnings. Or, a project might selectively enable 10193169689Skandiagnostics and treat them as errors depending on which preprocessor 10194169689Skanmacros are defined. 10195169689Skan 10196169689Skan@table @code 10197169689Skan@item #pragma GCC diagnostic @var{kind} @var{option} 10198169689Skan@cindex pragma, diagnostic 10199169689Skan 10200169689SkanModifies the disposition of a diagnostic. Note that not all 10201169689Skandiagnostics are modifiable; at the moment only warnings (normally 10202169689Skancontrolled by @samp{-W...}) can be controlled, and not all of them. 10203169689SkanUse @option{-fdiagnostics-show-option} to determine which diagnostics 10204169689Skanare controllable and which option controls them. 10205169689Skan 10206169689Skan@var{kind} is @samp{error} to treat this diagnostic as an error, 10207169689Skan@samp{warning} to treat it like a warning (even if @option{-Werror} is 10208169689Skanin effect), or @samp{ignored} if the diagnostic is to be ignored. 10209169689Skan@var{option} is a double quoted string which matches the command line 10210169689Skanoption. 10211169689Skan 10212169689Skan@example 10213169689Skan#pragma GCC diagnostic warning "-Wformat" 10214169689Skan#pragma GCC diagnostic error "-Wformat" 10215169689Skan#pragma GCC diagnostic ignored "-Wformat" 10216169689Skan@end example 10217169689Skan 10218169689SkanNote that these pragmas override any command line options. Also, 10219169689Skanwhile it is syntactically valid to put these pragmas anywhere in your 10220169689Skansources, the only supported location for them is before any data or 10221169689Skanfunctions are defined. Doing otherwise may result in unpredictable 10222169689Skanresults depending on how the optimizer manages your sources. If the 10223169689Skansame option is listed multiple times, the last one specified is the 10224169689Skanone that is in effect. This pragma is not intended to be a general 10225169689Skanpurpose replacement for command line options, but for implementing 10226169689Skanstrict control over project policies. 10227169689Skan 10228169689Skan@end table 10229169689Skan 10230169689Skan@node Visibility Pragmas 10231169689Skan@subsection Visibility Pragmas 10232169689Skan 10233169689Skan@table @code 10234169689Skan@item #pragma GCC visibility push(@var{visibility}) 10235169689Skan@itemx #pragma GCC visibility pop 10236169689Skan@cindex pragma, visibility 10237169689Skan 10238169689SkanThis pragma allows the user to set the visibility for multiple 10239169689Skandeclarations without having to give each a visibility attribute 10240169689Skan@xref{Function Attributes}, for more information about visibility and 10241169689Skanthe attribute syntax. 10242169689Skan 10243169689SkanIn C++, @samp{#pragma GCC visibility} affects only namespace-scope 10244169689Skandeclarations. Class members and template specializations are not 10245169689Skanaffected; if you want to override the visibility for a particular 10246169689Skanmember or instantiation, you must use an attribute. 10247169689Skan 10248169689Skan@end table 10249169689Skan 1025090075Sobrien@node Unnamed Fields 10251169689Skan@section Unnamed struct/union fields within structs/unions 1025290075Sobrien@cindex struct 1025390075Sobrien@cindex union 1025490075Sobrien 1025590075SobrienFor compatibility with other compilers, GCC allows you to define 1025690075Sobriena structure or union that contains, as fields, structures and unions 1025790075Sobrienwithout names. For example: 1025890075Sobrien 10259132718Skan@smallexample 1026090075Sobrienstruct @{ 1026190075Sobrien int a; 1026290075Sobrien union @{ 1026390075Sobrien int b; 1026490075Sobrien float c; 1026590075Sobrien @}; 1026690075Sobrien int d; 1026790075Sobrien@} foo; 10268132718Skan@end smallexample 1026990075Sobrien 1027090075SobrienIn this example, the user would be able to access members of the unnamed 1027190075Sobrienunion with code like @samp{foo.b}. Note that only unnamed structs and 1027290075Sobrienunions are allowed, you may not have, for example, an unnamed 1027390075Sobrien@code{int}. 1027490075Sobrien 1027590075SobrienYou must never create such structures that cause ambiguous field definitions. 1027690075SobrienFor example, this structure: 1027790075Sobrien 10278132718Skan@smallexample 1027990075Sobrienstruct @{ 1028090075Sobrien int a; 1028190075Sobrien struct @{ 1028290075Sobrien int a; 1028390075Sobrien @}; 1028490075Sobrien@} foo; 10285132718Skan@end smallexample 1028690075Sobrien 1028790075SobrienIt is ambiguous which @code{a} is being referred to with @samp{foo.a}. 1028890075SobrienSuch constructs are not supported and must be avoided. In the future, 1028990075Sobriensuch constructs may be detected and treated as compilation errors. 1029090075Sobrien 10291169689Skan@opindex fms-extensions 10292169689SkanUnless @option{-fms-extensions} is used, the unnamed field must be a 10293169689Skanstructure or union definition without a tag (for example, @samp{struct 10294169689Skan@{ int a; @};}). If @option{-fms-extensions} is used, the field may 10295169689Skanalso be a definition with a tag such as @samp{struct foo @{ int a; 10296169689Skan@};}, a reference to a previously defined structure or union such as 10297169689Skan@samp{struct foo;}, or a reference to a @code{typedef} name for a 10298169689Skanpreviously defined structure or union type. 10299169689Skan 10300117395Skan@node Thread-Local 10301117395Skan@section Thread-Local Storage 10302117395Skan@cindex Thread-Local Storage 10303117395Skan@cindex @acronym{TLS} 10304117395Skan@cindex __thread 10305117395Skan 10306117395SkanThread-local storage (@acronym{TLS}) is a mechanism by which variables 10307117395Skanare allocated such that there is one instance of the variable per extant 10308117395Skanthread. The run-time model GCC uses to implement this originates 10309117395Skanin the IA-64 processor-specific ABI, but has since been migrated 10310117395Skanto other processors as well. It requires significant support from 10311117395Skanthe linker (@command{ld}), dynamic linker (@command{ld.so}), and 10312117395Skansystem libraries (@file{libc.so} and @file{libpthread.so}), so it 10313117395Skanis not available everywhere. 10314117395Skan 10315117395SkanAt the user level, the extension is visible with a new storage 10316117395Skanclass keyword: @code{__thread}. For example: 10317117395Skan 10318132718Skan@smallexample 10319117395Skan__thread int i; 10320117395Skanextern __thread struct state s; 10321117395Skanstatic __thread char *p; 10322132718Skan@end smallexample 10323117395Skan 10324117395SkanThe @code{__thread} specifier may be used alone, with the @code{extern} 10325117395Skanor @code{static} specifiers, but with no other storage class specifier. 10326117395SkanWhen used with @code{extern} or @code{static}, @code{__thread} must appear 10327117395Skanimmediately after the other storage class specifier. 10328117395Skan 10329117395SkanThe @code{__thread} specifier may be applied to any global, file-scoped 10330117395Skanstatic, function-scoped static, or static data member of a class. It may 10331117395Skannot be applied to block-scoped automatic or non-static data member. 10332117395Skan 10333117395SkanWhen the address-of operator is applied to a thread-local variable, it is 10334117395Skanevaluated at run-time and returns the address of the current thread's 10335117395Skaninstance of that variable. An address so obtained may be used by any 10336117395Skanthread. When a thread terminates, any pointers to thread-local variables 10337117395Skanin that thread become invalid. 10338117395Skan 10339117395SkanNo static initialization may refer to the address of a thread-local variable. 10340117395Skan 10341117395SkanIn C++, if an initializer is present for a thread-local variable, it must 10342117395Skanbe a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ 10343117395Skanstandard. 10344117395Skan 10345117395SkanSee @uref{http://people.redhat.com/drepper/tls.pdf, 10346117395SkanELF Handling For Thread-Local Storage} for a detailed explanation of 10347117395Skanthe four thread-local storage addressing models, and how the run-time 10348117395Skanis expected to function. 10349117395Skan 10350117395Skan@menu 10351117395Skan* C99 Thread-Local Edits:: 10352117395Skan* C++98 Thread-Local Edits:: 10353117395Skan@end menu 10354117395Skan 10355117395Skan@node C99 Thread-Local Edits 10356117395Skan@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage 10357117395Skan 10358117395SkanThe following are a set of changes to ISO/IEC 9899:1999 (aka C99) 10359117395Skanthat document the exact semantics of the language extension. 10360117395Skan 10361117395Skan@itemize @bullet 10362117395Skan@item 10363117395Skan@cite{5.1.2 Execution environments} 10364117395Skan 10365117395SkanAdd new text after paragraph 1 10366117395Skan 10367117395Skan@quotation 10368117395SkanWithin either execution environment, a @dfn{thread} is a flow of 10369117395Skancontrol within a program. It is implementation defined whether 10370117395Skanor not there may be more than one thread associated with a program. 10371117395SkanIt is implementation defined how threads beyond the first are 10372117395Skancreated, the name and type of the function called at thread 10373117395Skanstartup, and how threads may be terminated. However, objects 10374117395Skanwith thread storage duration shall be initialized before thread 10375117395Skanstartup. 10376117395Skan@end quotation 10377117395Skan 10378117395Skan@item 10379117395Skan@cite{6.2.4 Storage durations of objects} 10380117395Skan 10381117395SkanAdd new text before paragraph 3 10382117395Skan 10383117395Skan@quotation 10384117395SkanAn object whose identifier is declared with the storage-class 10385117395Skanspecifier @w{@code{__thread}} has @dfn{thread storage duration}. 10386117395SkanIts lifetime is the entire execution of the thread, and its 10387117395Skanstored value is initialized only once, prior to thread startup. 10388117395Skan@end quotation 10389117395Skan 10390117395Skan@item 10391117395Skan@cite{6.4.1 Keywords} 10392117395Skan 10393117395SkanAdd @code{__thread}. 10394117395Skan 10395117395Skan@item 10396117395Skan@cite{6.7.1 Storage-class specifiers} 10397117395Skan 10398117395SkanAdd @code{__thread} to the list of storage class specifiers in 10399117395Skanparagraph 1. 10400117395Skan 10401117395SkanChange paragraph 2 to 10402117395Skan 10403117395Skan@quotation 10404117395SkanWith the exception of @code{__thread}, at most one storage-class 10405117395Skanspecifier may be given [@dots{}]. The @code{__thread} specifier may 10406117395Skanbe used alone, or immediately following @code{extern} or 10407117395Skan@code{static}. 10408117395Skan@end quotation 10409117395Skan 10410117395SkanAdd new text after paragraph 6 10411117395Skan 10412117395Skan@quotation 10413117395SkanThe declaration of an identifier for a variable that has 10414117395Skanblock scope that specifies @code{__thread} shall also 10415117395Skanspecify either @code{extern} or @code{static}. 10416117395Skan 10417117395SkanThe @code{__thread} specifier shall be used only with 10418117395Skanvariables. 10419117395Skan@end quotation 10420117395Skan@end itemize 10421117395Skan 10422117395Skan@node C++98 Thread-Local Edits 10423117395Skan@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage 10424117395Skan 10425117395SkanThe following are a set of changes to ISO/IEC 14882:1998 (aka C++98) 10426117395Skanthat document the exact semantics of the language extension. 10427117395Skan 10428117395Skan@itemize @bullet 10429119256Skan@item 10430117395Skan@b{[intro.execution]} 10431117395Skan 10432117395SkanNew text after paragraph 4 10433117395Skan 10434117395Skan@quotation 10435117395SkanA @dfn{thread} is a flow of control within the abstract machine. 10436117395SkanIt is implementation defined whether or not there may be more than 10437117395Skanone thread. 10438117395Skan@end quotation 10439117395Skan 10440117395SkanNew text after paragraph 7 10441117395Skan 10442117395Skan@quotation 10443117395SkanIt is unspecified whether additional action must be taken to 10444117395Skanensure when and whether side effects are visible to other threads. 10445117395Skan@end quotation 10446117395Skan 10447117395Skan@item 10448117395Skan@b{[lex.key]} 10449117395Skan 10450117395SkanAdd @code{__thread}. 10451117395Skan 10452117395Skan@item 10453117395Skan@b{[basic.start.main]} 10454117395Skan 10455117395SkanAdd after paragraph 5 10456117395Skan 10457117395Skan@quotation 10458117395SkanThe thread that begins execution at the @code{main} function is called 10459117395Skanthe @dfn{main thread}. It is implementation defined how functions 10460117395Skanbeginning threads other than the main thread are designated or typed. 10461117395SkanA function so designated, as well as the @code{main} function, is called 10462117395Skana @dfn{thread startup function}. It is implementation defined what 10463117395Skanhappens if a thread startup function returns. It is implementation 10464117395Skandefined what happens to other threads when any thread calls @code{exit}. 10465117395Skan@end quotation 10466117395Skan 10467117395Skan@item 10468117395Skan@b{[basic.start.init]} 10469117395Skan 10470117395SkanAdd after paragraph 4 10471117395Skan 10472117395Skan@quotation 10473117395SkanThe storage for an object of thread storage duration shall be 10474117395Skanstatically initialized before the first statement of the thread startup 10475117395Skanfunction. An object of thread storage duration shall not require 10476117395Skandynamic initialization. 10477117395Skan@end quotation 10478117395Skan 10479117395Skan@item 10480117395Skan@b{[basic.start.term]} 10481117395Skan 10482117395SkanAdd after paragraph 3 10483117395Skan 10484117395Skan@quotation 10485117395SkanThe type of an object with thread storage duration shall not have a 10486117395Skannon-trivial destructor, nor shall it be an array type whose elements 10487117395Skan(directly or indirectly) have non-trivial destructors. 10488117395Skan@end quotation 10489117395Skan 10490117395Skan@item 10491117395Skan@b{[basic.stc]} 10492117395Skan 10493117395SkanAdd ``thread storage duration'' to the list in paragraph 1. 10494117395Skan 10495117395SkanChange paragraph 2 10496117395Skan 10497117395Skan@quotation 10498117395SkanThread, static, and automatic storage durations are associated with 10499117395Skanobjects introduced by declarations [@dots{}]. 10500117395Skan@end quotation 10501117395Skan 10502117395SkanAdd @code{__thread} to the list of specifiers in paragraph 3. 10503117395Skan 10504117395Skan@item 10505117395Skan@b{[basic.stc.thread]} 10506117395Skan 10507117395SkanNew section before @b{[basic.stc.static]} 10508117395Skan 10509117395Skan@quotation 10510117395SkanThe keyword @code{__thread} applied to a non-local object gives the 10511117395Skanobject thread storage duration. 10512117395Skan 10513117395SkanA local variable or class data member declared both @code{static} 10514117395Skanand @code{__thread} gives the variable or member thread storage 10515117395Skanduration. 10516117395Skan@end quotation 10517117395Skan 10518117395Skan@item 10519117395Skan@b{[basic.stc.static]} 10520117395Skan 10521117395SkanChange paragraph 1 10522117395Skan 10523117395Skan@quotation 10524117395SkanAll objects which have neither thread storage duration, dynamic 10525117395Skanstorage duration nor are local [@dots{}]. 10526117395Skan@end quotation 10527117395Skan 10528117395Skan@item 10529117395Skan@b{[dcl.stc]} 10530117395Skan 10531117395SkanAdd @code{__thread} to the list in paragraph 1. 10532117395Skan 10533117395SkanChange paragraph 1 10534117395Skan 10535117395Skan@quotation 10536117395SkanWith the exception of @code{__thread}, at most one 10537117395Skan@var{storage-class-specifier} shall appear in a given 10538117395Skan@var{decl-specifier-seq}. The @code{__thread} specifier may 10539117395Skanbe used alone, or immediately following the @code{extern} or 10540117395Skan@code{static} specifiers. [@dots{}] 10541117395Skan@end quotation 10542117395Skan 10543117395SkanAdd after paragraph 5 10544117395Skan 10545117395Skan@quotation 10546117395SkanThe @code{__thread} specifier can be applied only to the names of objects 10547117395Skanand to anonymous unions. 10548117395Skan@end quotation 10549117395Skan 10550117395Skan@item 10551117395Skan@b{[class.mem]} 10552117395Skan 10553117395SkanAdd after paragraph 6 10554117395Skan 10555117395Skan@quotation 10556117395SkanNon-@code{static} members shall not be @code{__thread}. 10557117395Skan@end quotation 10558117395Skan@end itemize 10559117395Skan 10560261188Spfg@c APPLE LOCAL begin blocks 7205047 5811887 10561261188Spfg@node Blocks 10562261188Spfg@section Blocks 10563261188Spfg@cindex Blocks 10564261188Spfg@cindex __block 10565261188Spfg 10566261188SpfgBlocks is a language feature that allows one to create anonymous 10567261188Spfgfunctions. The feature is also known as lambdas or closures in other 10568261188Spfglanguages. The feature is controlled by @option{-fblocks}. 10569261188SpfgSee @uref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html} for additional details. 10570261188Spfg@c APPLE LOCAL end blocks 7205047 5811887 10571261188Spfg 10572255107Spfg@node Binary constants 10573255107Spfg@section Binary constants using the @samp{0b} prefix 10574255107Spfg@cindex Binary constants using the @samp{0b} prefix 10575255107Spfg 10576255107SpfgInteger constants can be written as binary constants, consisting of a 10577255107Spfgsequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or 10578255107Spfg@samp{0B}. This is particularly useful in environments that operate a 10579255107Spfglot on the bit-level (like microcontrollers). 10580255107Spfg 10581255107SpfgThe following statements are identical: 10582255107Spfg 10583255107Spfg@smallexample 10584255107Spfgi = 42; 10585255107Spfgi = 0x2a; 10586255107Spfgi = 052; 10587255107Spfgi = 0b101010; 10588255107Spfg@end smallexample 10589255107Spfg 10590255107SpfgThe type of these constants follows the same rules as for octal or 10591255107Spfghexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} 10592255107Spfgcan be applied. 10593255107Spfg 1059490075Sobrien@node C++ Extensions 1059590075Sobrien@chapter Extensions to the C++ Language 1059690075Sobrien@cindex extensions, C++ language 1059790075Sobrien@cindex C++ language extensions 1059890075Sobrien 1059990075SobrienThe GNU compiler provides these extensions to the C++ language (and you 1060090075Sobriencan also use most of the C language extensions in your C++ programs). If you 1060190075Sobrienwant to write code that checks whether these features are available, you can 1060290075Sobrientest for the GNU compiler the same way as for C programs: check for a 1060390075Sobrienpredefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to 10604122180Skantest specifically for GNU C++ (@pxref{Common Predefined Macros,, 10605122180SkanPredefined Macros,cpp,The GNU C Preprocessor}). 1060690075Sobrien 1060790075Sobrien@menu 1060890075Sobrien* Volatiles:: What constitutes an access to a volatile object. 1060990075Sobrien* Restricted Pointers:: C99 restricted pointers and references. 1061090075Sobrien* Vague Linkage:: Where G++ puts inlines, vtables and such. 1061190075Sobrien* C++ Interface:: You can use a single C++ header file for both 1061290075Sobrien declarations and definitions. 1061390075Sobrien* Template Instantiation:: Methods for ensuring that exactly one copy of 1061490075Sobrien each needed template instantiation is emitted. 1061590075Sobrien* Bound member functions:: You can extract a function pointer to the 1061690075Sobrien method denoted by a @samp{->*} or @samp{.*} expression. 1061790075Sobrien* C++ Attributes:: Variable, function, and type attributes for C++ only. 10618169689Skan* Namespace Association:: Strong using-directives for namespace association. 1061990075Sobrien* Java Exceptions:: Tweaking exception handling to work with Java. 10620132718Skan* Deprecated Features:: Things will disappear from g++. 1062190075Sobrien* Backwards Compatibility:: Compatibilities with earlier definitions of C++. 1062290075Sobrien@end menu 1062390075Sobrien 1062490075Sobrien@node Volatiles 1062590075Sobrien@section When is a Volatile Object Accessed? 1062690075Sobrien@cindex accessing volatiles 1062790075Sobrien@cindex volatile read 1062890075Sobrien@cindex volatile write 1062990075Sobrien@cindex volatile access 1063090075Sobrien 1063190075SobrienBoth the C and C++ standard have the concept of volatile objects. These 1063290075Sobrienare normally accessed by pointers and used for accessing hardware. The 10633169689Skanstandards encourage compilers to refrain from optimizations concerning 10634169689Skanaccesses to volatile objects. The C standard leaves it implementation 10635169689Skandefined as to what constitutes a volatile access. The C++ standard omits 10636169689Skanto specify this, except to say that C++ should behave in a similar manner 1063790075Sobriento C with respect to volatiles, where possible. The minimum either 1063890075Sobrienstandard specifies is that at a sequence point all previous accesses to 1063990075Sobrienvolatile objects have stabilized and no subsequent accesses have 1064090075Sobrienoccurred. Thus an implementation is free to reorder and combine 1064190075Sobrienvolatile accesses which occur between sequence points, but cannot do so 1064290075Sobrienfor accesses across a sequence point. The use of volatiles does not 1064390075Sobrienallow you to violate the restriction on updating objects multiple times 1064490075Sobrienwithin a sequence point. 1064590075Sobrien 10646169689Skan@xref{Qualifiers implementation, , Volatile qualifier and the C compiler}. 1064790075Sobrien 10648169689SkanThe behavior differs slightly between C and C++ in the non-obvious cases: 1064990075Sobrien 10650132718Skan@smallexample 1065190075Sobrienvolatile int *src = @var{somevalue}; 1065290075Sobrien*src; 10653132718Skan@end smallexample 1065490075Sobrien 10655169689SkanWith C, such expressions are rvalues, and GCC interprets this either as a 10656169689Skanread of the volatile object being pointed to or only as request to evaluate 10657169689Skanthe side-effects. The C++ standard specifies that such expressions do not 10658169689Skanundergo lvalue to rvalue conversion, and that the type of the dereferenced 1065990075Sobrienobject may be incomplete. The C++ standard does not specify explicitly 10660169689Skanthat it is this lvalue to rvalue conversion which may be responsible for 1066190075Sobriencausing an access. However, there is reason to believe that it is, 1066290075Sobrienbecause otherwise certain simple expressions become undefined. However, 1066390075Sobrienbecause it would surprise most programmers, G++ treats dereferencing a 10664169689Skanpointer to volatile object of complete type when the value is unused as 10665169689SkanGCC would do for an equivalent type in C. When the object has incomplete 10666169689Skantype, G++ issues a warning; if you wish to force an error, you must 10667169689Skanforce a conversion to rvalue with, for instance, a static cast. 1066890075Sobrien 1066990075SobrienWhen using a reference to volatile, G++ does not treat equivalent 1067090075Sobrienexpressions as accesses to volatiles, but instead issues a warning that 1067190075Sobrienno volatile is accessed. The rationale for this is that otherwise it 1067290075Sobrienbecomes difficult to determine where volatile access occur, and not 1067390075Sobrienpossible to ignore the return value from functions returning volatile 1067490075Sobrienreferences. Again, if you wish to force a read, cast the reference to 1067590075Sobrienan rvalue. 1067690075Sobrien 1067790075Sobrien@node Restricted Pointers 1067890075Sobrien@section Restricting Pointer Aliasing 1067990075Sobrien@cindex restricted pointers 1068090075Sobrien@cindex restricted references 1068190075Sobrien@cindex restricted this pointer 1068290075Sobrien 10683132718SkanAs with the C front end, G++ understands the C99 feature of restricted pointers, 1068490075Sobrienspecified with the @code{__restrict__}, or @code{__restrict} type 1068590075Sobrienqualifier. Because you cannot compile C++ by specifying the @option{-std=c99} 1068690075Sobrienlanguage flag, @code{restrict} is not a keyword in C++. 1068790075Sobrien 1068890075SobrienIn addition to allowing restricted pointers, you can specify restricted 1068990075Sobrienreferences, which indicate that the reference is not aliased in the local 1069090075Sobriencontext. 1069190075Sobrien 10692132718Skan@smallexample 1069390075Sobrienvoid fn (int *__restrict__ rptr, int &__restrict__ rref) 1069490075Sobrien@{ 10695117395Skan /* @r{@dots{}} */ 1069690075Sobrien@} 10697132718Skan@end smallexample 1069890075Sobrien 1069990075Sobrien@noindent 1070090075SobrienIn the body of @code{fn}, @var{rptr} points to an unaliased integer and 1070190075Sobrien@var{rref} refers to a (different) unaliased integer. 1070290075Sobrien 1070390075SobrienYou may also specify whether a member function's @var{this} pointer is 1070490075Sobrienunaliased by using @code{__restrict__} as a member function qualifier. 1070590075Sobrien 10706132718Skan@smallexample 1070790075Sobrienvoid T::fn () __restrict__ 1070890075Sobrien@{ 10709117395Skan /* @r{@dots{}} */ 1071090075Sobrien@} 10711132718Skan@end smallexample 1071290075Sobrien 1071390075Sobrien@noindent 1071490075SobrienWithin the body of @code{T::fn}, @var{this} will have the effective 1071590075Sobriendefinition @code{T *__restrict__ const this}. Notice that the 1071690075Sobrieninterpretation of a @code{__restrict__} member function qualifier is 1071790075Sobriendifferent to that of @code{const} or @code{volatile} qualifier, in that it 1071890075Sobrienis applied to the pointer rather than the object. This is consistent with 1071990075Sobrienother compilers which implement restricted pointers. 1072090075Sobrien 1072190075SobrienAs with all outermost parameter qualifiers, @code{__restrict__} is 1072290075Sobrienignored in function definition matching. This means you only need to 1072390075Sobrienspecify @code{__restrict__} in a function definition, rather than 1072490075Sobrienin a function prototype as well. 1072590075Sobrien 1072690075Sobrien@node Vague Linkage 1072790075Sobrien@section Vague Linkage 1072890075Sobrien@cindex vague linkage 1072990075Sobrien 1073090075SobrienThere are several constructs in C++ which require space in the object 1073190075Sobrienfile but are not clearly tied to a single translation unit. We say that 1073290075Sobrienthese constructs have ``vague linkage''. Typically such constructs are 1073390075Sobrienemitted wherever they are needed, though sometimes we can be more 1073490075Sobrienclever. 1073590075Sobrien 1073690075Sobrien@table @asis 1073790075Sobrien@item Inline Functions 1073890075SobrienInline functions are typically defined in a header file which can be 1073990075Sobrienincluded in many different compilations. Hopefully they can usually be 1074090075Sobrieninlined, but sometimes an out-of-line copy is necessary, if the address 1074190075Sobrienof the function is taken or if inlining fails. In general, we emit an 1074290075Sobrienout-of-line copy in all translation units where one is needed. As an 1074390075Sobrienexception, we only emit inline virtual functions with the vtable, since 1074490075Sobrienit will always require a copy. 1074590075Sobrien 1074690075SobrienLocal static variables and string constants used in an inline function 1074790075Sobrienare also considered to have vague linkage, since they must be shared 1074890075Sobrienbetween all inlined and out-of-line instances of the function. 1074990075Sobrien 1075090075Sobrien@item VTables 1075190075Sobrien@cindex vtable 1075290075SobrienC++ virtual functions are implemented in most compilers using a lookup 1075390075Sobrientable, known as a vtable. The vtable contains pointers to the virtual 1075490075Sobrienfunctions provided by a class, and each object of the class contains a 1075590075Sobrienpointer to its vtable (or vtables, in some multiple-inheritance 1075690075Sobriensituations). If the class declares any non-inline, non-pure virtual 1075790075Sobrienfunctions, the first one is chosen as the ``key method'' for the class, 1075890075Sobrienand the vtable is only emitted in the translation unit where the key 1075990075Sobrienmethod is defined. 1076090075Sobrien 1076190075Sobrien@emph{Note:} If the chosen key method is later defined as inline, the 1076290075Sobrienvtable will still be emitted in every translation unit which defines it. 1076390075SobrienMake sure that any inline virtuals are declared inline in the class 1076490075Sobrienbody, even if they are not defined there. 1076590075Sobrien 1076690075Sobrien@item type_info objects 1076790075Sobrien@cindex type_info 1076890075Sobrien@cindex RTTI 1076990075SobrienC++ requires information about types to be written out in order to 1077090075Sobrienimplement @samp{dynamic_cast}, @samp{typeid} and exception handling. 1077190075SobrienFor polymorphic classes (classes with virtual functions), the type_info 1077290075Sobrienobject is written out along with the vtable so that @samp{dynamic_cast} 1077390075Sobriencan determine the dynamic type of a class object at runtime. For all 1077490075Sobrienother types, we write out the type_info object when it is used: when 1077590075Sobrienapplying @samp{typeid} to an expression, throwing an object, or 1077690075Sobrienreferring to a type in a catch clause or exception specification. 1077790075Sobrien 1077890075Sobrien@item Template Instantiations 1077990075SobrienMost everything in this section also applies to template instantiations, 1078090075Sobrienbut there are other options as well. 1078190075Sobrien@xref{Template Instantiation,,Where's the Template?}. 1078290075Sobrien 1078390075Sobrien@end table 1078490075Sobrien 1078590075SobrienWhen used with GNU ld version 2.8 or later on an ELF system such as 10786132718SkanGNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of 1078790075Sobrienthese constructs will be discarded at link time. This is known as 1078890075SobrienCOMDAT support. 1078990075Sobrien 1079090075SobrienOn targets that don't support COMDAT, but do support weak symbols, GCC 1079190075Sobrienwill use them. This way one copy will override all the others, but 1079290075Sobrienthe unused copies will still take up space in the executable. 1079390075Sobrien 1079490075SobrienFor targets which do not support either COMDAT or weak symbols, 1079590075Sobrienmost entities with vague linkage will be emitted as local symbols to 1079690075Sobrienavoid duplicate definition errors from the linker. This will not happen 1079790075Sobrienfor local statics in inlines, however, as having multiple copies will 1079890075Sobrienalmost certainly break things. 1079990075Sobrien 1080090075Sobrien@xref{C++ Interface,,Declarations and Definitions in One Header}, for 1080190075Sobrienanother way to control placement of these constructs. 1080290075Sobrien 1080390075Sobrien@node C++ Interface 10804132718Skan@section #pragma interface and implementation 1080590075Sobrien 1080690075Sobrien@cindex interface and implementation headers, C++ 1080790075Sobrien@cindex C++ interface and implementation headers 1080890075Sobrien@cindex pragmas, interface and implementation 1080990075Sobrien 10810132718Skan@code{#pragma interface} and @code{#pragma implementation} provide the 10811132718Skanuser with a way of explicitly directing the compiler to emit entities 10812132718Skanwith vague linkage (and debugging information) in a particular 10813132718Skantranslation unit. 1081490075Sobrien 10815132718Skan@emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in 10816132718Skanmost cases, because of COMDAT support and the ``key method'' heuristic 10817132718Skanmentioned in @ref{Vague Linkage}. Using them can actually cause your 10818169689Skanprogram to grow due to unnecessary out-of-line copies of inline 10819169689Skanfunctions. Currently (3.4) the only benefit of these 10820169689Skan@code{#pragma}s is reduced duplication of debugging information, and 10821169689Skanthat should be addressed soon on DWARF 2 targets with the use of 10822169689SkanCOMDAT groups. 1082390075Sobrien 1082490075Sobrien@table @code 1082590075Sobrien@item #pragma interface 1082690075Sobrien@itemx #pragma interface "@var{subdir}/@var{objects}.h" 1082790075Sobrien@kindex #pragma interface 1082890075SobrienUse this directive in @emph{header files} that define object classes, to save 1082990075Sobrienspace in most of the object files that use those classes. Normally, 1083090075Sobrienlocal copies of certain information (backup copies of inline member 1083190075Sobrienfunctions, debugging information, and the internal tables that implement 1083290075Sobrienvirtual functions) must be kept in each object file that includes class 1083390075Sobriendefinitions. You can use this pragma to avoid such duplication. When a 1083490075Sobrienheader file containing @samp{#pragma interface} is included in a 1083590075Sobriencompilation, this auxiliary information will not be generated (unless 1083690075Sobrienthe main input source file itself uses @samp{#pragma implementation}). 1083790075SobrienInstead, the object files will contain references to be resolved at link 1083890075Sobrientime. 1083990075Sobrien 1084090075SobrienThe second form of this directive is useful for the case where you have 1084190075Sobrienmultiple headers with the same name in different directories. If you 1084290075Sobrienuse this form, you must specify the same string to @samp{#pragma 1084390075Sobrienimplementation}. 1084490075Sobrien 1084590075Sobrien@item #pragma implementation 1084690075Sobrien@itemx #pragma implementation "@var{objects}.h" 1084790075Sobrien@kindex #pragma implementation 1084890075SobrienUse this pragma in a @emph{main input file}, when you want full output from 1084990075Sobrienincluded header files to be generated (and made globally visible). The 1085090075Sobrienincluded header file, in turn, should use @samp{#pragma interface}. 1085190075SobrienBackup copies of inline member functions, debugging information, and the 1085290075Sobrieninternal tables used to implement virtual functions are all generated in 1085390075Sobrienimplementation files. 1085490075Sobrien 1085590075Sobrien@cindex implied @code{#pragma implementation} 1085690075Sobrien@cindex @code{#pragma implementation}, implied 1085790075Sobrien@cindex naming convention, implementation headers 1085890075SobrienIf you use @samp{#pragma implementation} with no argument, it applies to 1085990075Sobrienan include file with the same basename@footnote{A file's @dfn{basename} 1086090075Sobrienwas the name stripped of all leading path information and of trailing 1086190075Sobriensuffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source 1086290075Sobrienfile. For example, in @file{allclass.cc}, giving just 1086390075Sobrien@samp{#pragma implementation} 1086490075Sobrienby itself is equivalent to @samp{#pragma implementation "allclass.h"}. 1086590075Sobrien 1086690075SobrienIn versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as 1086790075Sobrienan implementation file whenever you would include it from 1086890075Sobrien@file{allclass.cc} even if you never specified @samp{#pragma 1086990075Sobrienimplementation}. This was deemed to be more trouble than it was worth, 1087090075Sobrienhowever, and disabled. 1087190075Sobrien 1087290075SobrienUse the string argument if you want a single implementation file to 1087390075Sobrieninclude code from multiple header files. (You must also use 1087490075Sobrien@samp{#include} to include the header file; @samp{#pragma 1087590075Sobrienimplementation} only specifies how to use the file---it doesn't actually 1087690075Sobrieninclude it.) 1087790075Sobrien 1087890075SobrienThere is no way to split up the contents of a single header file into 1087990075Sobrienmultiple implementation files. 1088090075Sobrien@end table 1088190075Sobrien 1088290075Sobrien@cindex inlining and C++ pragmas 1088390075Sobrien@cindex C++ pragmas, effect on inlining 1088490075Sobrien@cindex pragmas in C++, effect on inlining 1088590075Sobrien@samp{#pragma implementation} and @samp{#pragma interface} also have an 1088690075Sobrieneffect on function inlining. 1088790075Sobrien 1088890075SobrienIf you define a class in a header file marked with @samp{#pragma 10889132718Skaninterface}, the effect on an inline function defined in that class is 10890132718Skansimilar to an explicit @code{extern} declaration---the compiler emits 10891132718Skanno code at all to define an independent version of the function. Its 10892132718Skandefinition is used only for inlining with its callers. 1089390075Sobrien 1089490075Sobrien@opindex fno-implement-inlines 1089590075SobrienConversely, when you include the same header file in a main source file 1089690075Sobrienthat declares it as @samp{#pragma implementation}, the compiler emits 1089790075Sobriencode for the function itself; this defines a version of the function 1089890075Sobrienthat can be found via pointers (or by callers compiled without 1089990075Sobrieninlining). If all calls to the function can be inlined, you can avoid 1090090075Sobrienemitting the function by compiling with @option{-fno-implement-inlines}. 1090190075SobrienIf any calls were not inlined, you will get linker errors. 1090290075Sobrien 1090390075Sobrien@node Template Instantiation 1090490075Sobrien@section Where's the Template? 1090590075Sobrien@cindex template instantiation 1090690075Sobrien 1090790075SobrienC++ templates are the first language feature to require more 1090890075Sobrienintelligence from the environment than one usually finds on a UNIX 1090990075Sobriensystem. Somehow the compiler and linker have to make sure that each 1091090075Sobrientemplate instance occurs exactly once in the executable if it is needed, 1091190075Sobrienand not at all otherwise. There are two basic approaches to this 10912132718Skanproblem, which are referred to as the Borland model and the Cfront model. 1091390075Sobrien 1091490075Sobrien@table @asis 1091590075Sobrien@item Borland model 1091690075SobrienBorland C++ solved the template instantiation problem by adding the code 1091790075Sobrienequivalent of common blocks to their linker; the compiler emits template 1091890075Sobrieninstances in each translation unit that uses them, and the linker 1091990075Sobriencollapses them together. The advantage of this model is that the linker 1092090075Sobrienonly has to consider the object files themselves; there is no external 1092190075Sobriencomplexity to worry about. This disadvantage is that compilation time 1092290075Sobrienis increased because the template code is being compiled repeatedly. 1092390075SobrienCode written for this model tends to include definitions of all 1092490075Sobrientemplates in the header file, since they must be seen to be 1092590075Sobrieninstantiated. 1092690075Sobrien 1092790075Sobrien@item Cfront model 1092890075SobrienThe AT&T C++ translator, Cfront, solved the template instantiation 1092990075Sobrienproblem by creating the notion of a template repository, an 1093090075Sobrienautomatically maintained place where template instances are stored. A 1093190075Sobrienmore modern version of the repository works as follows: As individual 1093290075Sobrienobject files are built, the compiler places any template definitions and 1093390075Sobrieninstantiations encountered in the repository. At link time, the link 1093490075Sobrienwrapper adds in the objects in the repository and compiles any needed 1093590075Sobrieninstances that were not previously emitted. The advantages of this 1093690075Sobrienmodel are more optimal compilation speed and the ability to use the 1093790075Sobriensystem linker; to implement the Borland model a compiler vendor also 1093890075Sobrienneeds to replace the linker. The disadvantages are vastly increased 1093990075Sobriencomplexity, and thus potential for error; for some code this can be 1094090075Sobrienjust as transparent, but in practice it can been very difficult to build 1094190075Sobrienmultiple programs in one directory and one program in multiple 1094290075Sobriendirectories. Code written for this model tends to separate definitions 1094390075Sobrienof non-inline member templates into a separate file, which should be 1094490075Sobriencompiled separately. 1094590075Sobrien@end table 1094690075Sobrien 1094790075SobrienWhen used with GNU ld version 2.8 or later on an ELF system such as 10948132718SkanGNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the 10949132718SkanBorland model. On other systems, G++ implements neither automatic 1095090075Sobrienmodel. 1095190075Sobrien 10952132718SkanA future version of G++ will support a hybrid model whereby the compiler 1095390075Sobrienwill emit any instantiations for which the template definition is 1095490075Sobrienincluded in the compile, and store template definitions and 1095590075Sobrieninstantiation context information into the object file for the rest. 1095690075SobrienThe link wrapper will extract that information as necessary and invoke 1095790075Sobrienthe compiler to produce the remaining instantiations. The linker will 1095890075Sobrienthen combine duplicate instantiations. 1095990075Sobrien 1096090075SobrienIn the mean time, you have the following options for dealing with 1096190075Sobrientemplate instantiations: 1096290075Sobrien 1096390075Sobrien@enumerate 1096490075Sobrien@item 1096590075Sobrien@opindex frepo 1096690075SobrienCompile your template-using code with @option{-frepo}. The compiler will 1096790075Sobriengenerate files with the extension @samp{.rpo} listing all of the 1096890075Sobrientemplate instantiations used in the corresponding object files which 1096990075Sobriencould be instantiated there; the link wrapper, @samp{collect2}, will 1097090075Sobrienthen update the @samp{.rpo} files to tell the compiler where to place 1097190075Sobrienthose instantiations and rebuild any affected object files. The 1097290075Sobrienlink-time overhead is negligible after the first pass, as the compiler 1097390075Sobrienwill continue to place the instantiations in the same files. 1097490075Sobrien 1097590075SobrienThis is your best option for application code written for the Borland 1097690075Sobrienmodel, as it will just work. Code written for the Cfront model will 1097790075Sobrienneed to be modified so that the template definitions are available at 1097890075Sobrienone or more points of instantiation; usually this is as simple as adding 1097990075Sobrien@code{#include <tmethods.cc>} to the end of each template header. 1098090075Sobrien 1098190075SobrienFor library code, if you want the library to provide all of the template 1098290075Sobrieninstantiations it needs, just try to link all of its object files 1098390075Sobrientogether; the link will fail, but cause the instantiations to be 1098490075Sobriengenerated as a side effect. Be warned, however, that this may cause 1098590075Sobrienconflicts if multiple libraries try to provide the same instantiations. 1098690075SobrienFor greater control, use explicit instantiation as described in the next 1098790075Sobrienoption. 1098890075Sobrien 1098990075Sobrien@item 1099090075Sobrien@opindex fno-implicit-templates 1099190075SobrienCompile your code with @option{-fno-implicit-templates} to disable the 1099290075Sobrienimplicit generation of template instances, and explicitly instantiate 1099390075Sobrienall the ones you use. This approach requires more knowledge of exactly 1099490075Sobrienwhich instances you need than do the others, but it's less 1099590075Sobrienmysterious and allows greater control. You can scatter the explicit 1099690075Sobrieninstantiations throughout your program, perhaps putting them in the 1099790075Sobrientranslation units where the instances are used or the translation units 1099890075Sobrienthat define the templates themselves; you can put all of the explicit 1099990075Sobrieninstantiations you need into one big file; or you can create small files 1100090075Sobrienlike 1100190075Sobrien 11002132718Skan@smallexample 1100390075Sobrien#include "Foo.h" 1100490075Sobrien#include "Foo.cc" 1100590075Sobrien 1100690075Sobrientemplate class Foo<int>; 1100790075Sobrientemplate ostream& operator << 1100890075Sobrien (ostream&, const Foo<int>&); 11009132718Skan@end smallexample 1101090075Sobrien 1101190075Sobrienfor each of the instances you need, and create a template instantiation 1101290075Sobrienlibrary from those. 1101390075Sobrien 1101490075SobrienIf you are using Cfront-model code, you can probably get away with not 1101590075Sobrienusing @option{-fno-implicit-templates} when compiling files that don't 1101690075Sobrien@samp{#include} the member template definitions. 1101790075Sobrien 1101890075SobrienIf you use one big file to do the instantiations, you may want to 1101990075Sobriencompile it without @option{-fno-implicit-templates} so you get all of the 1102090075Sobrieninstances required by your explicit instantiations (but not by any 1102190075Sobrienother files) without having to specify them as well. 1102290075Sobrien 11023132718SkanG++ has extended the template instantiation syntax given in the ISO 11024117395Skanstandard to allow forward declaration of explicit instantiations 1102590075Sobrien(with @code{extern}), instantiation of the compiler support data for a 1102690075Sobrientemplate class (i.e.@: the vtable) without instantiating any of its 1102790075Sobrienmembers (with @code{inline}), and instantiation of only the static data 1102890075Sobrienmembers of a template class, without the support data or member 1102990075Sobrienfunctions (with (@code{static}): 1103090075Sobrien 11031132718Skan@smallexample 1103290075Sobrienextern template int max (int, int); 1103390075Sobrieninline template class Foo<int>; 1103490075Sobrienstatic template class Foo<int>; 11035132718Skan@end smallexample 1103690075Sobrien 1103790075Sobrien@item 11038132718SkanDo nothing. Pretend G++ does implement automatic instantiation 1103990075Sobrienmanagement. Code written for the Borland model will work fine, but 1104090075Sobrieneach translation unit will contain instances of each of the templates it 1104190075Sobrienuses. In a large program, this can lead to an unacceptable amount of code 1104290075Sobrienduplication. 1104390075Sobrien@end enumerate 1104490075Sobrien 1104590075Sobrien@node Bound member functions 1104690075Sobrien@section Extracting the function pointer from a bound pointer to member function 1104790075Sobrien@cindex pmf 1104890075Sobrien@cindex pointer to member function 1104990075Sobrien@cindex bound pointer to member function 1105090075Sobrien 1105190075SobrienIn C++, pointer to member functions (PMFs) are implemented using a wide 1105290075Sobrienpointer of sorts to handle all the possible call mechanisms; the PMF 1105390075Sobrienneeds to store information about how to adjust the @samp{this} pointer, 1105490075Sobrienand if the function pointed to is virtual, where to find the vtable, and 1105590075Sobrienwhere in the vtable to look for the member function. If you are using 1105690075SobrienPMFs in an inner loop, you should really reconsider that decision. If 1105790075Sobrienthat is not an option, you can extract the pointer to the function that 1105890075Sobrienwould be called for a given object/PMF pair and call it directly inside 1105990075Sobrienthe inner loop, to save a bit of time. 1106090075Sobrien 1106190075SobrienNote that you will still be paying the penalty for the call through a 1106290075Sobrienfunction pointer; on most modern architectures, such a call defeats the 1106390075Sobrienbranch prediction features of the CPU@. This is also true of normal 1106490075Sobrienvirtual function calls. 1106590075Sobrien 1106690075SobrienThe syntax for this extension is 1106790075Sobrien 11068132718Skan@smallexample 1106990075Sobrienextern A a; 1107090075Sobrienextern int (A::*fp)(); 1107190075Sobrientypedef int (*fptr)(A *); 1107290075Sobrien 1107390075Sobrienfptr p = (fptr)(a.*fp); 11074132718Skan@end smallexample 1107590075Sobrien 1107690075SobrienFor PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), 1107790075Sobrienno object is needed to obtain the address of the function. They can be 1107890075Sobrienconverted to function pointers directly: 1107990075Sobrien 11080132718Skan@smallexample 1108190075Sobrienfptr p1 = (fptr)(&A::foo); 11082132718Skan@end smallexample 1108390075Sobrien 1108490075Sobrien@opindex Wno-pmf-conversions 1108590075SobrienYou must specify @option{-Wno-pmf-conversions} to use this extension. 1108690075Sobrien 1108790075Sobrien@node C++ Attributes 1108890075Sobrien@section C++-Specific Variable, Function, and Type Attributes 1108990075Sobrien 1109090075SobrienSome attributes only make sense for C++ programs. 1109190075Sobrien 1109290075Sobrien@table @code 1109390075Sobrien@item init_priority (@var{priority}) 1109490075Sobrien@cindex init_priority attribute 1109590075Sobrien 1109690075Sobrien 1109790075SobrienIn Standard C++, objects defined at namespace scope are guaranteed to be 1109890075Sobrieninitialized in an order in strict accordance with that of their definitions 1109990075Sobrien@emph{in a given translation unit}. No guarantee is made for initializations 1110090075Sobrienacross translation units. However, GNU C++ allows users to control the 1110190075Sobrienorder of initialization of objects defined at namespace scope with the 1110290075Sobrien@code{init_priority} attribute by specifying a relative @var{priority}, 1110390075Sobriena constant integral expression currently bounded between 101 and 65535 1110490075Sobrieninclusive. Lower numbers indicate a higher priority. 1110590075Sobrien 1110690075SobrienIn the following example, @code{A} would normally be created before 1110790075Sobrien@code{B}, but the @code{init_priority} attribute has reversed that order: 1110890075Sobrien 11109103445Skan@smallexample 1111090075SobrienSome_Class A __attribute__ ((init_priority (2000))); 1111190075SobrienSome_Class B __attribute__ ((init_priority (543))); 11112103445Skan@end smallexample 1111390075Sobrien 1111490075Sobrien@noindent 1111590075SobrienNote that the particular values of @var{priority} do not matter; only their 1111690075Sobrienrelative ordering. 1111790075Sobrien 1111890075Sobrien@item java_interface 1111990075Sobrien@cindex java_interface attribute 1112090075Sobrien 1112190075SobrienThis type attribute informs C++ that the class is a Java interface. It may 1112290075Sobrienonly be applied to classes declared within an @code{extern "Java"} block. 1112390075SobrienCalls to methods declared in this interface will be dispatched using GCJ's 1112490075Sobrieninterface table mechanism, instead of regular virtual table dispatch. 1112590075Sobrien 1112690075Sobrien@end table 1112790075Sobrien 11128169689SkanSee also @xref{Namespace Association}. 11129132718Skan 11130169689Skan@node Namespace Association 11131169689Skan@section Namespace Association 11132132718Skan 11133132718Skan@strong{Caution:} The semantics of this extension are not fully 11134132718Skandefined. Users should refrain from using this extension as its 11135132718Skansemantics may change subtly over time. It is possible that this 11136169689Skanextension will be removed in future versions of G++. 11137132718Skan 11138132718SkanA using-directive with @code{__attribute ((strong))} is stronger 11139132718Skanthan a normal using-directive in two ways: 11140132718Skan 11141132718Skan@itemize @bullet 11142132718Skan@item 11143169689SkanTemplates from the used namespace can be specialized and explicitly 11144169689Skaninstantiated as though they were members of the using namespace. 11145132718Skan 11146132718Skan@item 11147132718SkanThe using namespace is considered an associated namespace of all 11148132718Skantemplates in the used namespace for purposes of argument-dependent 11149132718Skanname lookup. 11150132718Skan@end itemize 11151132718Skan 11152169689SkanThe used namespace must be nested within the using namespace so that 11153169689Skannormal unqualified lookup works properly. 11154169689Skan 11155132718SkanThis is useful for composing a namespace transparently from 11156132718Skanimplementation namespaces. For example: 11157132718Skan 11158132718Skan@smallexample 11159132718Skannamespace std @{ 11160132718Skan namespace debug @{ 11161132718Skan template <class T> struct A @{ @}; 11162132718Skan @} 11163132718Skan using namespace debug __attribute ((__strong__)); 11164169689Skan template <> struct A<int> @{ @}; // @r{ok to specialize} 11165132718Skan 11166132718Skan template <class T> void f (A<T>); 11167132718Skan@} 11168132718Skan 11169132718Skanint main() 11170132718Skan@{ 11171169689Skan f (std::A<float>()); // @r{lookup finds} std::f 11172132718Skan f (std::A<int>()); 11173132718Skan@} 11174132718Skan@end smallexample 11175132718Skan 1117690075Sobrien@node Java Exceptions 1117790075Sobrien@section Java Exceptions 1117890075Sobrien 1117990075SobrienThe Java language uses a slightly different exception handling model 1118090075Sobrienfrom C++. Normally, GNU C++ will automatically detect when you are 1118190075Sobrienwriting C++ code that uses Java exceptions, and handle them 1118290075Sobrienappropriately. However, if C++ code only needs to execute destructors 1118390075Sobrienwhen Java exceptions are thrown through it, GCC will guess incorrectly. 1118490075SobrienSample problematic code is: 1118590075Sobrien 11186103445Skan@smallexample 1118790075Sobrien struct S @{ ~S(); @}; 11188169689Skan extern void bar(); // @r{is written in Java, and may throw exceptions} 1118990075Sobrien void foo() 1119090075Sobrien @{ 1119190075Sobrien S s; 1119290075Sobrien bar(); 1119390075Sobrien @} 11194103445Skan@end smallexample 1119590075Sobrien 1119690075Sobrien@noindent 1119790075SobrienThe usual effect of an incorrect guess is a link failure, complaining of 1119890075Sobriena missing routine called @samp{__gxx_personality_v0}. 1119990075Sobrien 1120090075SobrienYou can inform the compiler that Java exceptions are to be used in a 1120190075Sobrientranslation unit, irrespective of what it might think, by writing 1120290075Sobrien@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This 1120390075Sobrien@samp{#pragma} must appear before any functions that throw or catch 1120490075Sobrienexceptions, or run destructors when exceptions are thrown through them. 1120590075Sobrien 1120690075SobrienYou cannot mix Java and C++ exceptions in the same translation unit. It 1120790075Sobrienis believed to be safe to throw a C++ exception from one file through 1120890075Sobrienanother file compiled for the Java exception model, or vice versa, but 1120990075Sobrienthere may be bugs in this area. 1121090075Sobrien 1121190075Sobrien@node Deprecated Features 1121290075Sobrien@section Deprecated Features 1121390075Sobrien 1121490075SobrienIn the past, the GNU C++ compiler was extended to experiment with new 1121590075Sobrienfeatures, at a time when the C++ language was still evolving. Now that 1121690075Sobrienthe C++ standard is complete, some of those features are superseded by 1121790075Sobriensuperior alternatives. Using the old features might cause a warning in 1121890075Sobriensome cases that the feature will be dropped in the future. In other 1121990075Sobriencases, the feature might be gone already. 1122090075Sobrien 1122190075SobrienWhile the list below is not exhaustive, it documents some of the options 1122290075Sobrienthat are now deprecated: 1122390075Sobrien 1122490075Sobrien@table @code 1122590075Sobrien@item -fexternal-templates 1122690075Sobrien@itemx -falt-external-templates 11227132718SkanThese are two of the many ways for G++ to implement template 1122890075Sobrieninstantiation. @xref{Template Instantiation}. The C++ standard clearly 1122990075Sobriendefines how template definitions have to be organized across 11230132718Skanimplementation units. G++ has an implicit instantiation mechanism that 1123190075Sobrienshould work just fine for standard-conforming code. 1123290075Sobrien 1123390075Sobrien@item -fstrict-prototype 1123490075Sobrien@itemx -fno-strict-prototype 1123590075SobrienPreviously it was possible to use an empty prototype parameter list to 1123690075Sobrienindicate an unspecified number of parameters (like C), rather than no 1123790075Sobrienparameters, as C++ demands. This feature has been removed, except where 1123890075Sobrienit is required for backwards compatibility @xref{Backwards Compatibility}. 1123990075Sobrien@end table 1124090075Sobrien 11241169689SkanG++ allows a virtual function returning @samp{void *} to be overridden 11242169689Skanby one returning a different pointer type. This extension to the 11243169689Skancovariant return type rules is now deprecated and will be removed from a 11244169689Skanfuture version. 11245169689Skan 11246169689SkanThe G++ minimum and maximum operators (@samp{<?} and @samp{>?}) and 11247169689Skantheir compound forms (@samp{<?=}) and @samp{>?=}) have been deprecated 11248169689Skanand will be removed in a future version. Code using these operators 11249169689Skanshould be modified to use @code{std::min} and @code{std::max} instead. 11250169689Skan 1125190075SobrienThe named return value extension has been deprecated, and is now 11252132718Skanremoved from G++. 1125390075Sobrien 1125490075SobrienThe use of initializer lists with new expressions has been deprecated, 11255132718Skanand is now removed from G++. 1125690075Sobrien 1125790075SobrienFloating and complex non-type template parameters have been deprecated, 11258132718Skanand are now removed from G++. 1125990075Sobrien 11260132718SkanThe implicit typename extension has been deprecated and is now 11261132718Skanremoved from G++. 1126290075Sobrien 11263169689SkanThe use of default arguments in function pointers, function typedefs 11264132718Skanand other places where they are not permitted by the standard is 11265132718Skandeprecated and will be removed from a future version of G++. 11266132718Skan 11267169689SkanG++ allows floating-point literals to appear in integral constant expressions, 11268169689Skane.g. @samp{ enum E @{ e = int(2.2 * 3.7) @} } 11269169689SkanThis extension is deprecated and will be removed from a future version. 11270169689Skan 11271169689SkanG++ allows static data members of const floating-point type to be declared 11272169689Skanwith an initializer in a class definition. The standard only allows 11273169689Skaninitializers for static members of const integral types and const 11274169689Skanenumeration types so this extension has been deprecated and will be removed 11275169689Skanfrom a future version. 11276169689Skan 1127790075Sobrien@node Backwards Compatibility 1127890075Sobrien@section Backwards Compatibility 1127990075Sobrien@cindex Backwards Compatibility 1128090075Sobrien@cindex ARM [Annotated C++ Reference Manual] 1128190075Sobrien 1128290075SobrienNow that there is a definitive ISO standard C++, G++ has a specification 1128390075Sobriento adhere to. The C++ language evolved over time, and features that 1128490075Sobrienused to be acceptable in previous drafts of the standard, such as the ARM 1128590075Sobrien[Annotated C++ Reference Manual], are no longer accepted. In order to allow 1128690075Sobriencompilation of C++ written to such drafts, G++ contains some backwards 1128790075Sobriencompatibilities. @emph{All such backwards compatibility features are 1128890075Sobrienliable to disappear in future versions of G++.} They should be considered 1128990075Sobriendeprecated @xref{Deprecated Features}. 1129090075Sobrien 1129190075Sobrien@table @code 1129290075Sobrien@item For scope 1129390075SobrienIf a variable is declared at for scope, it used to remain in scope until 1129490075Sobrienthe end of the scope which contained the for statement (rather than just 1129590075Sobrienwithin the for scope). G++ retains this, but issues a warning, if such a 1129690075Sobrienvariable is accessed outside the for scope. 1129790075Sobrien 1129890075Sobrien@item Implicit C language 1129990075SobrienOld C system header files did not contain an @code{extern "C" @{@dots{}@}} 1130090075Sobrienscope to set the language. On such systems, all header files are 1130190075Sobrienimplicitly scoped inside a C language scope. Also, an empty prototype 1130290075Sobrien@code{()} will be treated as an unspecified number of arguments, rather 1130390075Sobrienthan no arguments, as C++ demands. 1130490075Sobrien@end table 11305