diff options
Diffstat (limited to 'gcc/doc/extend.texi')
| -rw-r--r-- | gcc/doc/extend.texi | 9146 |
1 files changed, 4719 insertions, 4427 deletions
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index b919df9..109c7d2 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -23,913 +23,41 @@ Some features that are in ISO C99 but not C90 or C++ are also, as extensions, accepted by GCC in C90 mode and in C++. @menu -* Statement Exprs:: Putting statements and declarations inside expressions. -* Local Labels:: Labels local to a block. -* Labels as Values:: Getting pointers to labels, and computed gotos. -* Nested Functions:: Nested function in GNU C. -* Nonlocal Gotos:: Nonlocal gotos. -* Constructing Calls:: Dispatching a call to another function. -* Typeof:: @code{typeof}: referring to the type of an expression. -* Conditionals:: Omitting the middle operand of a @samp{?:} expression. -* __int128:: 128-bit integers---@code{__int128}. -* Long Long:: Double-word integers---@code{long long int}. -* Complex:: Data types for complex numbers. -* Floating Types:: Additional Floating Types. -* Half-Precision:: Half-Precision Floating Point. -* Decimal Float:: Decimal Floating Types. -* Hex Floats:: Hexadecimal floating-point constants. -* Fixed-Point:: Fixed-Point Types. +* Additional Numeric Types:: Additional sizes and formats, plus complex numbers. +* Aggregate Types:: Extensions to arrays, structs, and unions. * Named Address Spaces::Named address spaces. -* Zero Length:: Zero-length arrays. -* Empty Structures:: Structures with no members. -* Flexible Array Members in Unions:: Unions with Flexible Array Members. -* Flexible Array Members alone in Structures:: Structures with only Flexible Array Members. -* Variable Length:: Arrays whose length is computed at run time. -* Variadic Macros:: Macros with a variable number of arguments. -* Escaped Newlines:: Slightly looser rules for escaped newlines. -* Subscripting:: Any array can be subscripted, even if not an lvalue. -* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. -* Variadic Pointer Args:: Pointer arguments to variadic functions. -* Pointers to Arrays:: Pointers to arrays with qualifiers work as expected. -* Initializers:: Non-constant initializers. -* Compound Literals:: Compound literals give structures, unions - or arrays as values. -* Designated Inits:: Labeling elements of initializers. -* Case Ranges:: `case 1 ... 9' and such. -* Cast to Union:: Casting to union type from any member of the union. -* Mixed Labels and Declarations:: Mixing declarations, labels and code. -* Function Attributes:: Declaring that functions have no side effects, - or that they can never return. -* Variable Attributes:: Specifying attributes of variables. -* Type Attributes:: Specifying attributes of types. -* Label Attributes:: Specifying attributes on labels. -* Enumerator Attributes:: Specifying attributes on enumerators. -* Statement Attributes:: Specifying attributes on statements. -* Attribute Syntax:: Formal syntax for attributes. -* Function Prototypes:: Prototype declarations and old-style definitions. -* C++ Comments:: C++ comments are recognized. -* Dollar Signs:: Dollar sign is allowed in identifiers. -* Character Escapes:: @samp{\e} stands for the character @key{ESC}. -* Alignment:: Determining the alignment of a function, type or variable. -* Inline:: Defining inline functions (as fast as macros). -* Const and Volatile Functions :: GCC interprets these specially in C. -* Volatiles:: What constitutes an access to a volatile object. -* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. -* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. -* Incomplete Enums:: @code{enum foo;}, with details to follow. -* Function Names:: Printable strings which are the name of the current - function. -* Return Address:: Getting the return or frame address of a function. -* Stack Scrubbing:: Stack scrubbing internal interfaces. -* Vector Extensions:: Using vector instructions through built-in functions. -* Offsetof:: Special syntax for implementing @code{offsetof}. -* __sync Builtins:: Legacy built-in functions for atomic memory access. -* __atomic Builtins:: Atomic built-in functions with memory model. -* Integer Overflow Builtins:: Built-in functions to perform arithmetics and - arithmetic overflow checking. -* x86 specific memory model extensions for transactional memory:: x86 memory models. -* Object Size Checking:: Built-in functions for limited buffer overflow - checking. -* New/Delete Builtins:: Built-in functions for C++ allocations and deallocations. -* Other Builtins:: Other built-in functions. -* Target Builtins:: Built-in functions specific to particular targets. -* Target Format Checks:: Format checks specific to particular targets. +* Attributes:: GCC supports both standard and legacy attribute syntax. * Pragmas:: Pragmas accepted by GCC. -* Unnamed Fields:: Unnamed struct/union fields within structs/unions. * Thread-Local:: Per-thread variables. -* Binary constants:: Binary constants using the @samp{0b} prefix. * OpenMP:: Multiprocessing extensions. * OpenACC:: Extensions for offloading code to accelerator devices. +* Inline:: Defining inline functions (as fast as macros). +* Volatiles:: What constitutes an access to a volatile object. +* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. +* Syntax Extensions:: Other extensions to C syntax. +* Semantic Extensions:: GNU C defines behavior for some non-standard constructs. @end menu -@node Statement Exprs -@section Statements and Declarations in Expressions -@cindex statements inside expressions -@cindex declarations inside expressions -@cindex expressions containing statements -@cindex macros, statements in expressions - -@c the above section title wrapped and causes an underfull hbox.. i -@c changed it from "within" to "in". --mew 4feb93 -A compound statement enclosed in parentheses may appear as an expression -in GNU C@. This allows you to use loops, switches, and local variables -within an expression. - -Recall that a compound statement is a sequence of statements surrounded -by braces; in this construct, parentheses go around the braces. For -example: - -@smallexample -(@{ int y = foo (); int z; - if (y > 0) z = y; - else z = - y; - z; @}) -@end smallexample - -@noindent -is a valid (though slightly more complex than necessary) expression -for the absolute value of @code{foo ()}. - -The last thing in the compound statement should be an expression -followed by a semicolon; the value of this subexpression serves as the -value of the entire construct. (If you use some other kind of statement -last within the braces, the construct has type @code{void}, and thus -effectively no value.) - -This feature is especially useful in making macro definitions ``safe'' (so -that they evaluate each operand exactly once). For example, the -``maximum'' function is commonly defined as a macro in standard C as -follows: - -@smallexample -#define max(a,b) ((a) > (b) ? (a) : (b)) -@end smallexample - -@noindent -@cindex side effects, macro argument -But this definition computes either @var{a} or @var{b} twice, with bad -results if the operand has side effects. In GNU C, if you know the -type of the operands (here taken as @code{int}), you can avoid this -problem by defining the macro as follows: - -@smallexample -#define maxint(a,b) \ - (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) -@end smallexample - -Note that introducing variable declarations (as we do in @code{maxint}) can -cause variable shadowing, so while this example using the @code{max} macro -produces correct results: -@smallexample -int _a = 1, _b = 2, c; -c = max (_a, _b); -@end smallexample -@noindent -this example using maxint will not: -@smallexample -int _a = 1, _b = 2, c; -c = maxint (_a, _b); -@end smallexample - -This problem may for instance occur when we use this pattern recursively, like -so: - -@smallexample -#define maxint3(a, b, c) \ - (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @}) -@end smallexample - -Embedded statements are not allowed in constant expressions, such as -the value of an enumeration constant, the width of a bit-field, or -the initial value of a static variable. - -If you don't know the type of the operand, you can still do this, but you -must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}). - -In G++, the result value of a statement expression undergoes array and -function pointer decay, and is returned by value to the enclosing -expression. For instance, if @code{A} is a class, then - -@smallexample - A a; - - (@{a;@}).Foo () -@end smallexample - -@noindent -constructs a temporary @code{A} object to hold the result of the -statement expression, and that is used to invoke @code{Foo}. -Therefore the @code{this} pointer observed by @code{Foo} is not the -address of @code{a}. - -In a statement expression, any temporaries created within a statement -are destroyed at that statement's end. This makes statement -expressions inside macros slightly different from function calls. In -the latter case temporaries introduced during argument evaluation are -destroyed at the end of the statement that includes the function -call. In the statement expression case they are destroyed during -the statement expression. For instance, - -@smallexample -#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) -template<typename T> T function(T a) @{ T b = a; return b + 3; @} - -void foo () -@{ - macro (X ()); - function (X ()); -@} -@end smallexample - -@noindent -has different places where temporaries are destroyed. For the -@code{macro} case, the temporary @code{X} is destroyed just after -the initialization of @code{b}. In the @code{function} case that -temporary is destroyed when the function returns. - -These considerations mean that it is probably a bad idea to use -statement expressions of this form in header files that are designed to -work with C++. (Note that some versions of the GNU C Library contained -header files using statement expressions that lead to precisely this -bug.) - -Jumping into a statement expression with @code{goto} or using a -@code{switch} statement outside the statement expression with a -@code{case} or @code{default} label inside the statement expression is -not permitted. Jumping into a statement expression with a computed -@code{goto} (@pxref{Labels as Values}) has undefined behavior. -Jumping out of a statement expression is permitted, but if the -statement expression is part of a larger expression then it is -unspecified which other subexpressions of that expression have been -evaluated except where the language definition requires certain -subexpressions to be evaluated before or after the statement -expression. A @code{break} or @code{continue} statement inside of -a statement expression used in @code{while}, @code{do} or @code{for} -loop or @code{switch} statement condition -or @code{for} statement init or increment expressions jumps to an -outer loop or @code{switch} statement if any (otherwise it is an error), -rather than to the loop or @code{switch} statement in whose condition -or init or increment expression it appears. -In any case, as with a function call, the evaluation of a -statement expression is not interleaved with the evaluation of other -parts of the containing expression. For example, - -@smallexample - foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); -@end smallexample - -@noindent -calls @code{foo} and @code{bar1} and does not call @code{baz} but -may or may not call @code{bar2}. If @code{bar2} is called, it is -called after @code{foo} and before @code{bar1}. - -@node Local Labels -@section Locally Declared Labels -@cindex local labels -@cindex macros, local labels - -GCC allows you to declare @dfn{local labels} in any nested block -scope. A local label is just like an ordinary label, but you can -only reference it (with a @code{goto} statement, or by taking its -address) within the block in which it is declared. - -A local label declaration looks like this: - -@smallexample -__label__ @var{label}; -@end smallexample - -@noindent -or - -@smallexample -__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; -@end smallexample - -Local label declarations must come at the beginning of the block, -before any ordinary declarations or statements. - -The label declaration defines the label @emph{name}, but does not define -the label itself. You must do this in the usual way, with -@code{@var{label}:}, within the statements of the statement expression. - -The local label feature is useful for complex macros. If a macro -contains nested loops, a @code{goto} can be useful for breaking out of -them. However, an ordinary label whose scope is the whole function -cannot be used: if the macro can be expanded several times in one -function, the label is multiply defined in that function. A -local label avoids this problem. For example: - -@smallexample -#define SEARCH(value, array, target) \ -do @{ \ - __label__ found; \ - typeof (target) _SEARCH_target = (target); \ - typeof (*(array)) *_SEARCH_array = (array); \ - int i, j; \ - int value; \ - for (i = 0; i < max; i++) \ - for (j = 0; j < max; j++) \ - if (_SEARCH_array[i][j] == _SEARCH_target) \ - @{ (value) = i; goto found; @} \ - (value) = -1; \ - found:; \ -@} while (0) -@end smallexample - -This could also be written using a statement expression: - -@smallexample -#define SEARCH(array, target) \ -(@{ \ - __label__ found; \ - typeof (target) _SEARCH_target = (target); \ - typeof (*(array)) *_SEARCH_array = (array); \ - int i, j; \ - int value; \ - for (i = 0; i < max; i++) \ - for (j = 0; j < max; j++) \ - if (_SEARCH_array[i][j] == _SEARCH_target) \ - @{ value = i; goto found; @} \ - value = -1; \ - found: \ - value; \ -@}) -@end smallexample +@node Additional Numeric Types +@section Additional Numeric Types -Local label declarations also make the labels they declare visible to -nested functions, if there are any. @xref{Nested Functions}, for details. +GCC supports additional numeric types, including larger integer types, +integer and floating-point complex types, +additional floating-point sizes and formats, decimal floating types, +and fixed-point types. -@node Labels as Values -@section Labels as Values -@cindex labels as values -@cindex computed gotos -@cindex goto with computed label -@cindex address of a label - -You can get the address of a label defined in the current function -(or a containing function) with the unary operator @samp{&&}. The -value has type @code{void *}. This value is a constant and can be used -wherever a constant of that type is valid. For example: - -@smallexample -void *ptr; -/* @r{@dots{}} */ -ptr = &&foo; -@end smallexample - -To use these values, you need to be able to jump to one. This is done -with the computed goto statement@footnote{The analogous feature in -Fortran is called an assigned goto, but that name seems inappropriate in -C, where one can do more than simply store label addresses in label -variables.}, @code{goto *@var{exp};}. For example, - -@smallexample -goto *ptr; -@end smallexample - -@noindent -Any expression of type @code{void *} is allowed. - -One way of using these constants is in initializing a static array that -serves as a jump table: - -@smallexample -static void *array[] = @{ &&foo, &&bar, &&hack @}; -@end smallexample - -@noindent -Then you can select a label with indexing, like this: - -@smallexample -goto *array[i]; -@end smallexample - -@noindent -Note that this does not check whether the subscript is in bounds---array -indexing in C never does that. - -Such an array of label values serves a purpose much like that of the -@code{switch} statement. The @code{switch} statement is cleaner, so -use that rather than an array unless the problem does not fit a -@code{switch} statement very well. - -Another use of label values is in an interpreter for threaded code. -The labels within the interpreter function can be stored in the -threaded code for super-fast dispatching. - -You may not use this mechanism to jump to code in a different function. -If you do that, totally unpredictable things happen. The best way to -avoid this is to store the label address only in automatic variables and -never pass it as an argument. - -An alternate way to write the above example is - -@smallexample -static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, - &&hack - &&foo @}; -goto *(&&foo + array[i]); -@end smallexample - -@noindent -This is more friendly to code living in shared libraries, as it reduces -the number of dynamic relocations that are needed, and by consequence, -allows the data to be read-only. -This alternative with label differences is not supported for the AVR target, -please use the first approach for AVR programs. - -The @code{&&foo} expressions for the same label might have different -values if the containing function is inlined or cloned. If a program -relies on them being always the same, -@code{__attribute__((__noinline__,__noclone__))} should be used to -prevent inlining and cloning. If @code{&&foo} is used in a static -variable initializer, inlining and cloning is forbidden. - -Unlike a normal goto, in GNU C++ a computed goto will not call -destructors for objects that go out of scope. - -@node Nested Functions -@section Nested Functions -@cindex nested functions -@cindex downward funargs -@cindex thunks - -A @dfn{nested function} is a function defined inside another function. -Nested functions are supported as an extension in GNU C, but are not -supported by GNU C++. - -The nested function's name is local to the block where it is defined. -For example, here we define a nested function named @code{square}, and -call it twice: - -@smallexample -@group -foo (double a, double b) -@{ - double square (double z) @{ return z * z; @} - - return square (a) + square (b); -@} -@end group -@end smallexample - -The nested function can access all the variables of the containing -function that are visible at the point of its definition. This is -called @dfn{lexical scoping}. For example, here we show a nested -function which uses an inherited variable named @code{offset}: - -@smallexample -@group -bar (int *array, int offset, int size) -@{ - int access (int *array, int index) - @{ return array[index + offset]; @} - int i; - /* @r{@dots{}} */ - for (i = 0; i < size; i++) - /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ -@} -@end group -@end smallexample - -Nested function definitions are permitted within functions in the places -where variable definitions are allowed; that is, in any block, mixed -with the other declarations and statements in the block. - -It is possible to call the nested function from outside the scope of its -name by storing its address or passing the address to another function: - -@smallexample -hack (int *array, int size) -@{ - void store (int index, int value) - @{ array[index] = value; @} - - intermediate (store, size); -@} -@end smallexample - -Here, the function @code{intermediate} receives the address of -@code{store} as an argument. If @code{intermediate} calls @code{store}, -the arguments given to @code{store} are used to store into @code{array}. -But this technique works only so long as the containing function -(@code{hack}, in this example) does not exit. - -If you try to call the nested function through its address after the -containing function exits, all hell breaks loose. If you try -to call it after a containing scope level exits, and if it refers -to some of the variables that are no longer in scope, you may be lucky, -but it's not wise to take the risk. If, however, the nested function -does not refer to anything that has gone out of scope, you should be -safe. - -GCC implements taking the address of a nested function using a technique -called @dfn{trampolines}. This technique was described in -@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX -C++ Conference Proceedings, October 17-21, 1988). - -A nested function can jump to a label inherited from a containing -function, provided the label is explicitly declared in the containing -function (@pxref{Local Labels}). Such a jump returns instantly to the -containing function, exiting the nested function that did the -@code{goto} and any intermediate functions as well. Here is an example: - -@smallexample -@group -bar (int *array, int offset, int size) -@{ - __label__ failure; - int access (int *array, int index) - @{ - if (index > size) - goto failure; - return array[index + offset]; - @} - int i; - /* @r{@dots{}} */ - for (i = 0; i < size; i++) - /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ - /* @r{@dots{}} */ - return 0; - - /* @r{Control comes here from @code{access} - if it detects an error.} */ - failure: - return -1; -@} -@end group -@end smallexample - -A nested function always has no linkage. Declaring one with -@code{extern} or @code{static} is erroneous. If you need to declare the nested function -before its definition, use @code{auto} (which is otherwise meaningless -for function declarations). - -@smallexample -bar (int *array, int offset, int size) -@{ - __label__ failure; - auto int access (int *, int); - /* @r{@dots{}} */ - int access (int *array, int index) - @{ - if (index > size) - goto failure; - return array[index + offset]; - @} - /* @r{@dots{}} */ -@} -@end smallexample - -@node Nonlocal Gotos -@section Nonlocal Gotos -@cindex nonlocal gotos - -GCC provides the built-in functions @code{__builtin_setjmp} and -@code{__builtin_longjmp} which are similar to, but not interchangeable -with, the C library functions @code{setjmp} and @code{longjmp}. -The built-in versions are used internally by GCC's libraries -to implement exception handling on some targets. You should use the -standard C library functions declared in @code{<setjmp.h>} in user code -instead of the builtins. - -The built-in versions of these functions use GCC's normal -mechanisms to save and restore registers using the stack on function -entry and exit. The jump buffer argument @var{buf} holds only the -information needed to restore the stack frame, rather than the entire -set of saved register values. - -An important caveat is that GCC arranges to save and restore only -those registers known to the specific architecture variant being -compiled for. This can make @code{__builtin_setjmp} and -@code{__builtin_longjmp} more efficient than their library -counterparts in some cases, but it can also cause incorrect and -mysterious behavior when mixing with code that uses the full register -set. - -You should declare the jump buffer argument @var{buf} to the -built-in functions as: - -@smallexample -#include <stdint.h> -intptr_t @var{buf}[5]; -@end smallexample - -@defbuiltin{{int} __builtin_setjmp (intptr_t *@var{buf})} -This function saves the current stack context in @var{buf}. -@code{__builtin_setjmp} returns 0 when returning directly, -and 1 when returning from @code{__builtin_longjmp} using the same -@var{buf}. -@enddefbuiltin - -@defbuiltin{{void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})} -This function restores the stack context in @var{buf}, -saved by a previous call to @code{__builtin_setjmp}. After -@code{__builtin_longjmp} is finished, the program resumes execution as -if the matching @code{__builtin_setjmp} returns the value @var{val}, -which must be 1. - -Because @code{__builtin_longjmp} depends on the function return -mechanism to restore the stack context, it cannot be called -from the same function calling @code{__builtin_setjmp} to -initialize @var{buf}. It can only be called from a function called -(directly or indirectly) from the function calling @code{__builtin_setjmp}. -@enddefbuiltin - -@node Constructing Calls -@section Constructing Function Calls -@cindex constructing calls -@cindex forwarding calls - -Using the built-in functions described below, you can record -the arguments a function received, and call another function -with the same arguments, without knowing the number or types -of the arguments. - -You can also record the return value of that function call, -and later return that value, without knowing what data type -the function tried to return (as long as your caller expects -that data type). - -However, these built-in functions may interact badly with some -sophisticated features or other extensions of the language. It -is, therefore, not recommended to use them outside very simple -functions acting as mere forwarders for their arguments. - -@defbuiltin{{void *} __builtin_apply_args ()} -This built-in function returns a pointer to data -describing how to perform a call with the same arguments as are passed -to the current function. - -The function saves the arg pointer register, structure value address, -and all registers that might be used to pass arguments to a function -into a block of memory allocated on the stack. Then it returns the -address of that block. -@enddefbuiltin - -@defbuiltin{{void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})} -This built-in function invokes @var{function} -with a copy of the parameters described by @var{arguments} -and @var{size}. - -The value of @var{arguments} should be the value returned by -@code{__builtin_apply_args}. The argument @var{size} specifies the size -of the stack argument data, in bytes. - -This function returns a pointer to data describing -how to return whatever value is returned by @var{function}. The data -is saved in a block of memory allocated on the stack. - -It is not always simple to compute the proper value for @var{size}. The -value is used by @code{__builtin_apply} to compute the amount of data -that should be pushed on the stack and copied from the incoming argument -area. -@enddefbuiltin - -@defbuiltin{{void} __builtin_return (void *@var{result})} -This built-in function returns the value described by @var{result} from -the containing function. You should specify, for @var{result}, a value -returned by @code{__builtin_apply}. -@enddefbuiltin - -@defbuiltin{{} __builtin_va_arg_pack ()} -This built-in function represents all anonymous arguments of an inline -function. It can be used only in inline functions that are always -inlined, never compiled as a separate function, such as those using -@code{__attribute__ ((__always_inline__))} or -@code{__attribute__ ((__gnu_inline__))} extern inline functions. -It must be only passed as last argument to some other function -with variable arguments. This is useful for writing small wrapper -inlines for variable argument functions, when using preprocessor -macros is undesirable. For example: -@smallexample -extern int myprintf (FILE *f, const char *format, ...); -extern inline __attribute__ ((__gnu_inline__)) int -myprintf (FILE *f, const char *format, ...) -@{ - int r = fprintf (f, "myprintf: "); - if (r < 0) - return r; - int s = fprintf (f, format, __builtin_va_arg_pack ()); - if (s < 0) - return s; - return r + s; -@} -@end smallexample -@enddefbuiltin - -@defbuiltin{int __builtin_va_arg_pack_len ()} -This built-in function returns the number of anonymous arguments of -an inline function. It can be used only in inline functions that -are always inlined, never compiled as a separate function, such -as those using @code{__attribute__ ((__always_inline__))} or -@code{__attribute__ ((__gnu_inline__))} extern inline functions. -For example following does link- or run-time checking of open -arguments for optimized code: -@smallexample -#ifdef __OPTIMIZE__ -extern inline __attribute__((__gnu_inline__)) int -myopen (const char *path, int oflag, ...) -@{ - if (__builtin_va_arg_pack_len () > 1) - warn_open_too_many_arguments (); - - if (__builtin_constant_p (oflag)) - @{ - if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1) - @{ - warn_open_missing_mode (); - return __open_2 (path, oflag); - @} - return open (path, oflag, __builtin_va_arg_pack ()); - @} - - if (__builtin_va_arg_pack_len () < 1) - return __open_2 (path, oflag); - - return open (path, oflag, __builtin_va_arg_pack ()); -@} -#endif -@end smallexample -@enddefbuiltin - -@node Typeof -@section Referring to a Type with @code{typeof} -@findex typeof -@findex sizeof -@cindex macros, types of arguments - -Another way to refer to the type of an expression is with @code{typeof}. -The syntax of using of this keyword looks like @code{sizeof}, but the -construct acts semantically like a type name defined with @code{typedef}. - -There are two ways of writing the argument to @code{typeof}: with an -expression or with a type. Here is an example with an expression: - -@smallexample -typeof (x[0](1)) -@end smallexample - -@noindent -This assumes that @code{x} is an array of pointers to functions; -the type described is that of the values of the functions. - -Here is an example with a typename as the argument: - -@smallexample -typeof (int *) -@end smallexample - -@noindent -Here the type described is that of pointers to @code{int}. - -If you are writing a header file that must work when included in ISO C -programs, write @code{__typeof__} instead of @code{typeof}. -@xref{Alternate Keywords}. - -A @code{typeof} construct can be used anywhere a typedef name can be -used. For example, you can use it in a declaration, in a cast, or inside -of @code{sizeof} or @code{typeof}. - -The operand of @code{typeof} is evaluated for its side effects if and -only if it is an expression of variably modified type or the name of -such a type. - -@code{typeof} is often useful in conjunction with -statement expressions (@pxref{Statement Exprs}). -Here is how the two together can -be used to define a safe ``maximum'' macro which operates on any -arithmetic type and evaluates each of its arguments exactly once: - -@smallexample -#define max(a,b) \ - (@{ typeof (a) _a = (a); \ - typeof (b) _b = (b); \ - _a > _b ? _a : _b; @}) -@end smallexample - -@cindex underscores in variables in macros -@cindex @samp{_} in variables in macros -@cindex local variables in macros -@cindex variables, local, in macros -@cindex macros, local variables in - -The reason for using names that start with underscores for the local -variables is to avoid conflicts with variable names that occur within the -expressions that are substituted for @code{a} and @code{b}. Eventually we -hope to design a new form of declaration syntax that allows you to declare -variables whose scopes start only after their initializers; this will be a -more reliable way to prevent such conflicts. - -@noindent -Some more examples of the use of @code{typeof}: - -@itemize @bullet -@item -This declares @code{y} with the type of what @code{x} points to. - -@smallexample -typeof (*x) y; -@end smallexample - -@item -This declares @code{y} as an array of such values. - -@smallexample -typeof (*x) y[4]; -@end smallexample - -@item -This declares @code{y} as an array of pointers to characters: - -@smallexample -typeof (typeof (char *)[4]) y; -@end smallexample - -@noindent -It is equivalent to the following traditional C declaration: - -@smallexample -char *y[4]; -@end smallexample - -To see the meaning of the declaration using @code{typeof}, and why it -might be a useful way to write, rewrite it with these macros: - -@smallexample -#define pointer(T) typeof(T *) -#define array(T, N) typeof(T [N]) -@end smallexample - -@noindent -Now the declaration can be rewritten this way: - -@smallexample -array (pointer (char), 4) y; -@end smallexample - -@noindent -Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 -pointers to @code{char}. -@end itemize - -The ISO C23 operator @code{typeof_unqual} is available in ISO C23 mode -and its result is the non-atomic unqualified version of what @code{typeof} -operator returns. Alternate spelling @code{__typeof_unqual__} is -available in all C modes and provides non-atomic unqualified version of -what @code{__typeof__} operator returns. -@xref{Alternate Keywords}. - -@cindex @code{__auto_type} in GNU C -In GNU C, but not GNU C++, you may also declare the type of a variable -as @code{__auto_type}. In that case, the declaration must declare -only one variable, whose declarator must just be an identifier, the -declaration must be initialized, and the type of the variable is -determined by the initializer; the name of the variable is not in -scope until after the initializer. (In C++, you should use C++11 -@code{auto} for this purpose.) Using @code{__auto_type}, the -``maximum'' macro above could be written as: - -@smallexample -#define max(a,b) \ - (@{ __auto_type _a = (a); \ - __auto_type _b = (b); \ - _a > _b ? _a : _b; @}) -@end smallexample - -Using @code{__auto_type} instead of @code{typeof} has two advantages: - -@itemize @bullet -@item Each argument to the macro appears only once in the expansion of -the macro. This prevents the size of the macro expansion growing -exponentially when calls to such macros are nested inside arguments of -such macros. - -@item If the argument to the macro has variably modified type, it is -evaluated only once when using @code{__auto_type}, but twice if -@code{typeof} is used. -@end itemize - -@node Conditionals -@section Conditionals with Omitted Operands -@cindex conditional expressions, extensions -@cindex omitted middle-operands -@cindex middle-operands, omitted -@cindex extensions, @code{?:} -@cindex @code{?:} extensions - -The middle operand in a conditional expression may be omitted. Then -if the first operand is nonzero, its value is the value of the conditional -expression. - -Therefore, the expression - -@smallexample -x ? : y -@end smallexample - -@noindent -has the value of @code{x} if that is nonzero; otherwise, the value of -@code{y}. - -This example is perfectly equivalent to - -@smallexample -x ? x : y -@end smallexample - -@cindex side effect in @code{?:} -@cindex @code{?:} side effect -@noindent -In this simple case, the ability to omit the middle operand is not -especially useful. When it becomes useful is when the first operand does, -or may (if it is a macro argument), contain a side effect. Then repeating -the operand in the middle would perform the side effect twice. Omitting -the middle operand uses the value already computed without the undesirable -effects of recomputing it. +@menu +* __int128:: 128-bit integers---@code{__int128}. +* Long Long:: Double-word integers---@code{long long int}. +* Complex:: Data types for complex numbers. +* Floating Types:: Additional Floating Types. +* Half-Precision:: Half-Precision Floating Point. +* Decimal Float:: Decimal Floating Types. +* Fixed-Point:: Fixed-Point Types. +@end menu @node __int128 -@section 128-bit Integers +@subsection 128-bit Integers @cindex @code{__int128} data types As an extension the integer scalar type @code{__int128} is supported for @@ -940,7 +68,7 @@ support in GCC for expressing an integer constant of type @code{__int128} for targets with @code{long long} integer less than 128 bits wide. @node Long Long -@section Double-Word Integers +@subsection Double-Word Integers @cindex @code{long long} data types @cindex double-word arithmetic @cindex multiprecision arithmetic @@ -972,7 +100,7 @@ Likewise, if the function expects @code{long long int} and you pass @code{int}. The best way to avoid such problems is to use prototypes. @node Complex -@section Complex Numbers +@subsection Complex Numbers @cindex complex numbers @cindex @code{_Complex} keyword @cindex @code{__complex__} keyword @@ -1083,7 +211,7 @@ infinities, NaNs and negative zeros are involved. @enddefbuiltin @node Floating Types -@section Additional Floating Types +@subsection Additional Floating Types @cindex additional floating types @cindex @code{_Float@var{n}} data types @cindex @code{_Float@var{n}x} data types @@ -1169,7 +297,7 @@ typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128; @end smallexample @node Half-Precision -@section Half-Precision Floating Point +@subsection Half-Precision Floating Point @cindex half-precision floating point @cindex @code{__fp16} data type @cindex @code{__Float16} data type @@ -1240,7 +368,7 @@ It is useful for code that does not have @code{_Float16} and runs on the x87 FPU. @node Decimal Float -@section Decimal Floating Types +@subsection Decimal Floating Types @cindex decimal floating types @cindex @code{_Decimal32} data type @cindex @code{_Decimal64} data type @@ -1292,35 +420,8 @@ the technical report. Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} are supported by the DWARF debug information format. -@node Hex Floats -@section Hex Floats -@cindex hex floats - -ISO C99 and ISO C++17 support floating-point numbers written not only in -the usual decimal notation, such as @code{1.55e1}, but also numbers such as -@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC -supports this in C90 mode (except in some cases when strictly -conforming) and in C++98, C++11 and C++14 modes. In that format the -@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are -mandatory. The exponent is a decimal number that indicates the power of -2 by which the significant part is multiplied. Thus @samp{0x1.f} is -@tex -$1 {15\over16}$, -@end tex -@ifnottex -1 15/16, -@end ifnottex -@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} -is the same as @code{1.55e1}. - -Unlike for floating-point numbers in the decimal notation the exponent -is always required in the hexadecimal notation. Otherwise the compiler -would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This -could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the -extension for floating-point constants of type @code{float}. - @node Fixed-Point -@section Fixed-Point Types +@subsection Fixed-Point Types @cindex fixed-point types @cindex @code{_Fract} data type @cindex @code{_Accum} data type @@ -1466,257 +567,121 @@ Pragmas to control overflow and rounding behaviors are not implemented. Fixed-point types are supported by the DWARF debug information format. -@node Named Address Spaces -@section Named Address Spaces -@cindex Named Address Spaces - -As an extension, GNU C supports named address spaces as -defined in the N1275 draft of ISO/IEC DTR 18037. Support for named -address spaces in GCC will evolve as the draft technical report -changes. Calling conventions for any target might also change. At -present, only the AVR, M32C, PRU, RL78, and x86 targets support -address spaces other than the generic address space. - -Address space identifiers may be used exactly like any other C type -qualifier (e.g., @code{const} or @code{volatile}). See the N1275 -document for more details. - -@anchor{AVR Named Address Spaces} -@subsection AVR Named Address Spaces - -On the AVR target, there are several address spaces that can be used -in order to put read-only data into the flash memory and access that -data by means of the special instructions @code{LPM} or @code{ELPM} -needed to read from flash. - -Devices belonging to @code{avrtiny} and @code{avrxmega3} can access -flash memory by means of @code{LD*} instructions because the flash -memory is mapped into the RAM address space. There is @emph{no need} -for language extensions like @code{__flash} or attribute -@ref{AVR Variable Attributes,,@code{progmem}}. -The default linker description files for these devices cater for that -feature and @code{.rodata} stays in flash: The compiler just generates -@code{LD*} instructions, and the linker script adds core specific -offsets to all @code{.rodata} symbols: @code{0x4000} in the case of -@code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}. -See @ref{AVR Options} for a list of respective devices. - -For devices not in @code{avrtiny} or @code{avrxmega3}, -any data including read-only data is located in RAM (the generic -address space) because flash memory is not visible in the RAM address -space. In order to locate read-only data in flash memory @emph{and} -to generate the right instructions to access this data without -using (inline) assembler code, special address spaces are needed. - -@table @code -@cindex @code{__flash} AVR Named Address Spaces -@item __flash -The @code{__flash} qualifier locates data in the -@code{.progmem.data} section. Data is read using the @code{LPM} -instruction. Pointers to this address space are 16 bits wide. - -@cindex @code{__flash1} AVR Named Address Spaces -@cindex @code{__flash2} AVR Named Address Spaces -@cindex @code{__flash3} AVR Named Address Spaces -@cindex @code{__flash4} AVR Named Address Spaces -@cindex @code{__flash5} AVR Named Address Spaces -@item __flash1 -@itemx __flash2 -@itemx __flash3 -@itemx __flash4 -@itemx __flash5 -These are 16-bit address spaces locating data in section -@code{.progmem@var{N}.data} where @var{N} refers to -address space @code{__flash@var{N}}. -The compiler sets the @code{RAMPZ} segment register appropriately -before reading data by means of the @code{ELPM} instruction. - -@cindex @code{__flashx} AVR Named Address Spaces -@item __flashx +@node Aggregate Types +@section Array, Union, and Struct Extensions -This is a 24-bit flash address space locating data in section -@code{.progmemx.data}. -The compiler sets the @code{RAMPZ} segment register appropriately -before reading data by means of the @code{ELPM} instruction. +GCC supports several extensions relating to array, union, and struct types, +including extensions for aggregate initializers for objects of these types. -@cindex @code{__memx} AVR Named Address Spaces -@item __memx -This is a 24-bit address space that linearizes flash and RAM: -If the high bit of the address is set, data is read from -RAM using the lower two bytes as RAM address. -If the high bit of the address is clear, data is read from flash -with @code{RAMPZ} set according to the high byte of the address. -@xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}. +@menu +* Variable Length:: Arrays whose length is computed at run time. +* Zero Length:: Zero-length arrays. +* Empty Structures:: Structures with no members. +* Flexible Array Members in Unions:: Unions with Flexible Array Members. +* Flexible Array Members alone in Structures:: Structures with only Flexible Array Members. +* Unnamed Fields:: Unnamed struct/union fields within structs/unions. +* Cast to Union:: Casting to union type from any member of the union. +* Subscripting:: Any array can be subscripted, even if not an lvalue. +* Initializers:: Non-constant initializers. +* Compound Literals:: Compound literals give structures, unions + or arrays as values. +* Designated Inits:: Labeling elements of initializers. +@end menu -Objects in this address space are located in @code{.progmemx.data}. -@end table +@node Variable Length +@subsection Arrays of Variable Length +@cindex variable-length arrays +@cindex arrays of variable length +@cindex VLAs -@b{Example} +Variable-length automatic arrays are allowed in ISO C99, and as an +extension GCC accepts them in C90 mode and in C++. These arrays are +declared like any other automatic arrays, but with a length that is not +a constant expression. The storage is allocated at the point of +declaration and deallocated when the block scope containing the declaration +exits. For +example: @smallexample -char my_read (const __flash char ** p) -@{ - /* p is a pointer to RAM that points to a pointer to flash. - The first indirection of p reads that flash pointer - from RAM and the second indirection reads a char from this - flash address. */ - - return **p; -@} - -/* Locate array[] in flash memory */ -const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; - -int i = 1; - -int main (void) +FILE * +concat_fopen (char *s1, char *s2, char *mode) @{ - /* Return 17 by reading from flash memory */ - return array[array[i]]; + char str[strlen (s1) + strlen (s2) + 1]; + strcpy (str, s1); + strcat (str, s2); + return fopen (str, mode); @} @end smallexample -@noindent -For each named address space supported by avr-gcc there is an equally -named but uppercase built-in macro defined. -The purpose is to facilitate testing if respective address space -support is available or not: - -@smallexample -#ifdef __FLASH -const __flash int var = 1; - -int read_var (void) -@{ - return var; -@} -#else -#include <avr/pgmspace.h> /* From AVR-LibC */ +@cindex scope of a variable length array +@cindex variable-length array scope +@cindex deallocating variable length arrays +Jumping or breaking out of the scope of the array name deallocates the +storage. Jumping into the scope is not allowed; you get an error +message for it. -const int var PROGMEM = 1; +@cindex variable-length array in a structure +As an extension, GCC accepts variable-length arrays as a member of +a structure or a union. For example: -int read_var (void) +@smallexample +void +foo (int n) @{ - return (int) pgm_read_word (&var); + struct S @{ int x[n]; @}; @} -#endif /* __FLASH */ @end smallexample -@noindent -Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}} -locates data in flash but -accesses to these data read from generic address space, i.e.@: -from RAM, -so that you need special accessors like @code{pgm_read_byte} -from @w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/,AVR-LibC}} -together with attribute @code{progmem}. - -@noindent -@b{Limitations and Caveats} - -@itemize -@item -Reading across the 64@tie{}KiB section boundary of -the @code{__flash} or @code{__flash@var{N}} address spaces -is not supported. The only address spaces that -support reading across the 64@tie{}KiB flash segment boundaries are -@code{__memx} and @code{__flashx}. +@cindex @code{alloca} vs variable-length arrays +You can use the function @code{alloca} to get an effect much like +variable-length arrays. The function @code{alloca} is available in +many other C implementations (but not in all). On the other hand, +variable-length arrays are more elegant. -@item -If you use one of the @code{__flash@var{N}} address spaces -you must arrange your linker script to locate the -@code{.progmem@var{N}.data} sections according to your needs. -For an example, see the -@w{@uref{https://gcc.gnu.org/wiki/avr-gcc#Address_Spaces,avr-gcc wiki}} +There are other differences between these two methods. Space allocated +with @code{alloca} exists until the containing @emph{function} returns. +The space for a variable-length array is deallocated as soon as the array +name's scope ends, unless you also use @code{alloca} in this scope. -@item -Any data or pointers to the non-generic address spaces must -be qualified as @code{const}, i.e.@: as read-only data. -This still applies if the data in one of these address -spaces like software version number or calibration lookup table are intended to -be changed after load time by, say, a boot loader. In this case -the right qualification is @code{const} @code{volatile} so that the compiler -must not optimize away known values or insert them -as immediates into operands of instructions. +You can also use variable-length arrays as arguments to functions: -@item -The following code initializes a variable @code{pfoo} -located in static storage with a 24-bit address: @smallexample -extern const __memx char foo; -const __memx void *pfoo = &foo; +struct entry +tester (int len, char data[len][len]) +@{ + /* @r{@dots{}} */ +@} @end smallexample -@item -On the reduced Tiny devices like ATtiny40, no address spaces are supported. -Just use vanilla C / C++ code without overhead as outlined above. -Attribute @code{progmem} is supported but works differently, -see @ref{AVR Variable Attributes}. - -@end itemize - -@subsection M32C Named Address Spaces -@cindex @code{__far} M32C Named Address Spaces - -On the M32C target, with the R8C and M16C CPU variants, variables -qualified with @code{__far} are accessed using 32-bit addresses in -order to access memory beyond the first 64@tie{}Ki bytes. If -@code{__far} is used with the M32CM or M32C CPU variants, it has no -effect. - -@subsection PRU Named Address Spaces -@cindex @code{__regio_symbol} PRU Named Address Spaces +The length of an array is computed once when the storage is allocated +and is remembered for the scope of the array in case you access it with +@code{sizeof}. -On the PRU target, variables qualified with @code{__regio_symbol} are -aliases used to access the special I/O CPU registers. They must be -declared as @code{extern} because such variables will not be allocated in -any data memory. They must also be marked as @code{volatile}, and can -only be 32-bit integer types. The only names those variables can have -are @code{__R30} and @code{__R31}, representing respectively the -@code{R30} and @code{R31} special I/O CPU registers. Hence the following -example is the only valid usage of @code{__regio_symbol}: +If you want to pass the array first and the length afterward, you can +use a forward declaration in the parameter list---another GNU extension. @smallexample -extern volatile __regio_symbol uint32_t __R30; -extern volatile __regio_symbol uint32_t __R31; +struct entry +tester (int len; char data[len][len], int len) +@{ + /* @r{@dots{}} */ +@} @end smallexample -@subsection RL78 Named Address Spaces -@cindex @code{__far} RL78 Named Address Spaces - -On the RL78 target, variables qualified with @code{__far} are accessed -with 32-bit pointers (20-bit addresses) rather than the default 16-bit -addresses. Non-far variables are assumed to appear in the topmost -64@tie{}KiB of the address space. - -@subsection x86 Named Address Spaces -@cindex x86 named address spaces - -On the x86 target, variables may be declared as being relative -to the @code{%fs} or @code{%gs} segments. - -@table @code -@cindex @code{__seg_fs} x86 named address space -@cindex @code{__seg_gs} x86 named address space -@item __seg_fs -@itemx __seg_gs -The object is accessed with the respective segment override prefix. - -The respective segment base must be set via some method specific to -the operating system. Rather than require an expensive system call -to retrieve the segment base, these address spaces are not considered -to be subspaces of the generic (flat) address space. This means that -explicit casts are required to convert pointers between these address -spaces and the generic address space. In practice the application -should cast to @code{uintptr_t} and apply the segment base offset -that it installed previously. +@cindex parameter forward declaration +The @samp{int len} before the semicolon is a @dfn{parameter forward +declaration}, and it serves the purpose of making the name @code{len} +known when the declaration of @code{data} is parsed. -The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are -defined when these address spaces are supported. -@end table +You can write any number of such parameter forward declarations in the +parameter list. They can be separated by commas or semicolons, but the +last one must end with a semicolon, which is followed by the ``real'' +parameter declarations. Each forward declaration must match a ``real'' +declaration in parameter name and data type. ISO C99 does not support +parameter forward declarations. @node Zero Length -@section Arrays of Length Zero +@subsection Arrays of Length Zero @cindex arrays of length zero @cindex zero-length arrays @cindex length-zero arrays @@ -1875,7 +840,7 @@ struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} @end smallexample @node Empty Structures -@section Structures with No Members +@subsection Structures with No Members @cindex empty structures @cindex zero-size structures @@ -1891,7 +856,7 @@ of the language. G++ treats empty structures as if they had a single member of type @code{char}. @node Flexible Array Members in Unions -@section Unions with Flexible Array Members +@subsection Unions with Flexible Array Members @cindex unions with flexible array members @cindex unions with FAMs @@ -1908,7 +873,7 @@ If every member of a union is a flexible array member, the size of such a union is zero. @node Flexible Array Members alone in Structures -@section Structures with only Flexible Array Members +@subsection Structures with only Flexible Array Members @cindex structures with only flexible array members @cindex structures with only FAMs @@ -1922,184 +887,150 @@ struct only_fam @{ The size of such a structure is zero. -@node Variable Length -@section Arrays of Variable Length -@cindex variable-length arrays -@cindex arrays of variable length -@cindex VLAs +@node Unnamed Fields +@subsection Unnamed Structure and Union Fields +@cindex @code{struct} +@cindex @code{union} -Variable-length automatic arrays are allowed in ISO C99, and as an -extension GCC accepts them in C90 mode and in C++. These arrays are -declared like any other automatic arrays, but with a length that is not -a constant expression. The storage is allocated at the point of -declaration and deallocated when the block scope containing the declaration -exits. For -example: +As permitted by ISO C11 and for compatibility with other compilers, +GCC allows you to define +a structure or union that contains, as fields, structures and unions +without names. For example: @smallexample -FILE * -concat_fopen (char *s1, char *s2, char *mode) -@{ - char str[strlen (s1) + strlen (s2) + 1]; - strcpy (str, s1); - strcat (str, s2); - return fopen (str, mode); -@} +struct @{ + int a; + union @{ + int b; + float c; + @}; + int d; +@} foo; @end smallexample -@cindex scope of a variable length array -@cindex variable-length array scope -@cindex deallocating variable length arrays -Jumping or breaking out of the scope of the array name deallocates the -storage. Jumping into the scope is not allowed; you get an error -message for it. +@noindent +In this example, you are able to access members of the unnamed +union with code like @samp{foo.b}. Note that only unnamed structs and +unions are allowed, you may not have, for example, an unnamed +@code{int}. -@cindex variable-length array in a structure -As an extension, GCC accepts variable-length arrays as a member of -a structure or a union. For example: +You must never create such structures that cause ambiguous field definitions. +For example, in this structure: @smallexample -void -foo (int n) -@{ - struct S @{ int x[n]; @}; -@} +struct @{ + int a; + struct @{ + int a; + @}; +@} foo; @end smallexample -@cindex @code{alloca} vs variable-length arrays -You can use the function @code{alloca} to get an effect much like -variable-length arrays. The function @code{alloca} is available in -many other C implementations (but not in all). On the other hand, -variable-length arrays are more elegant. +@noindent +it is ambiguous which @code{a} is being referred to with @samp{foo.a}. +The compiler gives errors for such constructs. -There are other differences between these two methods. Space allocated -with @code{alloca} exists until the containing @emph{function} returns. -The space for a variable-length array is deallocated as soon as the array -name's scope ends, unless you also use @code{alloca} in this scope. +@opindex fms-extensions +Unless @option{-fms-extensions} is used, the unnamed field must be a +structure or union definition without a tag (for example, @samp{struct +@{ int a; @};}). If @option{-fms-extensions} is used, the field may +also be a definition with a tag such as @samp{struct foo @{ int a; +@};}, a reference to a previously defined structure or union such as +@samp{struct foo;}, or a reference to a @code{typedef} name for a +previously defined structure or union type. -You can also use variable-length arrays as arguments to functions: +@opindex fplan9-extensions +The option @option{-fplan9-extensions} enables +@option{-fms-extensions} as well as two other extensions. First, a +pointer to a structure is automatically converted to a pointer to an +anonymous field for assignments and function calls. For example: @smallexample -struct entry -tester (int len, char data[len][len]) -@{ - /* @r{@dots{}} */ -@} +struct s1 @{ int a; @}; +struct s2 @{ struct s1; @}; +extern void f1 (struct s1 *); +void f2 (struct s2 *p) @{ f1 (p); @} @end smallexample -The length of an array is computed once when the storage is allocated -and is remembered for the scope of the array in case you access it with -@code{sizeof}. +@noindent +In the call to @code{f1} inside @code{f2}, the pointer @code{p} is +converted into a pointer to the anonymous field. -If you want to pass the array first and the length afterward, you can -use a forward declaration in the parameter list---another GNU extension. +Second, when the type of an anonymous field is a @code{typedef} for a +@code{struct} or @code{union}, code may refer to the field using the +name of the @code{typedef}. @smallexample -struct entry -tester (int len; char data[len][len], int len) -@{ - /* @r{@dots{}} */ -@} +typedef struct @{ int a; @} s1; +struct s2 @{ s1; @}; +s1 f1 (struct s2 *p) @{ return p->s1; @} @end smallexample -@cindex parameter forward declaration -The @samp{int len} before the semicolon is a @dfn{parameter forward -declaration}, and it serves the purpose of making the name @code{len} -known when the declaration of @code{data} is parsed. +These usages are only permitted when they are not ambiguous. -You can write any number of such parameter forward declarations in the -parameter list. They can be separated by commas or semicolons, but the -last one must end with a semicolon, which is followed by the ``real'' -parameter declarations. Each forward declaration must match a ``real'' -declaration in parameter name and data type. ISO C99 does not support -parameter forward declarations. +@node Cast to Union +@subsection Cast to a Union Type +@cindex cast to a union +@cindex union, casting to a -@node Variadic Macros -@section Macros with a Variable Number of Arguments. -@cindex variable number of arguments -@cindex macro with variable arguments -@cindex rest argument (in macro) -@cindex variadic macros +A cast to a union type is a C extension not available in C++. It looks +just like ordinary casts with the constraint that the type specified is +a union type. You can specify the type either with the @code{union} +keyword or with a @code{typedef} name that refers to a union. The result +of a cast to a union is a temporary rvalue of the union type with a member +whose type matches that of the operand initialized to the value of +the operand. The effect of a cast to a union is similar to a compound +literal except that it yields an rvalue like standard casts do. +@xref{Compound Literals}. -In the ISO C standard of 1999, a macro can be declared to accept a -variable number of arguments much as a function can. The syntax for -defining the macro is similar to that of a function. Here is an -example: +Expressions that may be cast to the union type are those whose type matches +at least one of the members of the union. Thus, given the following union +and variables: @smallexample -#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) +union foo @{ int i; double d; @}; +int x; +double y; +union foo z; @end smallexample @noindent -Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of -such a macro, it represents the zero or more tokens until the closing -parenthesis that ends the invocation, including any commas. This set of -tokens replaces the identifier @code{__VA_ARGS__} in the macro body -wherever it appears. See the CPP manual for more information. - -GCC has long supported variadic macros, and used a different syntax that -allowed you to give a name to the variable arguments just like any other -argument. Here is an example: - +both @code{x} and @code{y} can be cast to type @code{union foo} and +the following assignments @smallexample -#define debug(format, args...) fprintf (stderr, format, args) + z = (union foo) x; + z = (union foo) y; @end smallexample - -@noindent -This is in all ways equivalent to the ISO C example above, but arguably -more readable and descriptive. - -GNU CPP has two further variadic macro extensions, and permits them to -be used with either of the above forms of macro definition. - -In standard C, you are not allowed to leave the variable argument out -entirely; but you are allowed to pass an empty argument. For example, -this invocation is invalid in ISO C, because there is no comma after -the string: - +are shorthand equivalents of these @smallexample -debug ("A message") + z = (union foo) @{ .i = x @}; + z = (union foo) @{ .d = y @}; @end smallexample -GNU CPP permits you to completely omit the variable arguments in this -way. In the above examples, the compiler would complain, though since -the expansion of the macro still has the extra comma after the format -string. +However, @code{(union foo) FLT_MAX;} is not a valid cast because the union +has no member of type @code{float}. -To help solve this problem, CPP behaves specially for variable arguments -used with the token paste operator, @samp{##}. If instead you write +Using the cast as the right-hand side of an assignment to a variable of +union type is equivalent to storing in a member of the union with +the same type @smallexample -#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) +union foo u; +/* @r{@dots{}} */ +u = (union foo) x @equiv{} u.i = x +u = (union foo) y @equiv{} u.d = y @end smallexample -@noindent -and if the variable arguments are omitted or empty, the @samp{##} -operator causes the preprocessor to remove the comma before it. If you -do provide some variable arguments in your macro invocation, GNU CPP -does not complain about the paste operation and instead places the -variable arguments after the comma. Just like any other pasted macro -argument, these arguments are not macro expanded. - -@node Escaped Newlines -@section Slightly Looser Rules for Escaped Newlines -@cindex escaped newlines -@cindex newlines (escaped) +You can also use the union cast as a function argument: -The preprocessor treatment of escaped newlines is more relaxed -than that specified by the C90 standard, which requires the newline -to immediately follow a backslash. -GCC's implementation allows whitespace in the form -of spaces, horizontal and vertical tabs, and form feeds between the -backslash and the subsequent newline. The preprocessor issues a -warning, but treats it as a valid escaped newline and combines the two -lines to form a single logical line. This works within comments and -tokens, as well as between tokens. Comments are @emph{not} treated as -whitespace for the purposes of this relaxation, since they have not -yet been replaced with spaces. +@smallexample +void hack (union foo); +/* @r{@dots{}} */ +hack ((union foo) x); +@end smallexample @node Subscripting -@section Non-Lvalue Arrays May Have Subscripts +@subsection Non-Lvalue Arrays May Have Subscripts @cindex subscripting @cindex arrays, non-lvalue @@ -2125,63 +1056,8 @@ bar (int index) @end group @end smallexample -@node Pointer Arith -@section Arithmetic on @code{void}- and Function-Pointers -@cindex void pointers, arithmetic -@cindex void, size of pointer to -@cindex function pointers, arithmetic -@cindex function, size of pointer to - -In GNU C, addition and subtraction operations are supported on pointers to -@code{void} and on pointers to functions. This is done by treating the -size of a @code{void} or of a function as 1. - -A consequence of this is that @code{sizeof} is also allowed on @code{void} -and on function types, and returns 1. - -@opindex Wpointer-arith -The option @option{-Wpointer-arith} requests a warning if these extensions -are used. - -@node Variadic Pointer Args -@section Pointer Arguments in Variadic Functions -@cindex pointer arguments in variadic functions -@cindex variadic functions, pointer arguments - -Standard C requires that pointer types used with @code{va_arg} in -functions with variable argument lists either must be compatible with -that of the actual argument, or that one type must be a pointer to -@code{void} and the other a pointer to a character type. GNU C -implements the POSIX XSI extension that additionally permits the use -of @code{va_arg} with a pointer type to receive arguments of any other -pointer type. - -In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used -to consume an argument of any pointer type. - -@node Pointers to Arrays -@section Pointers to Arrays with Qualifiers Work as Expected -@cindex pointers to arrays -@cindex const qualifier - -In GNU C, pointers to arrays with qualifiers work similar to pointers -to other qualified types. For example, a value of type @code{int (*)[5]} -can be used to initialize a variable of type @code{const int (*)[5]}. -These types are incompatible in ISO C because the @code{const} qualifier -is formally attached to the element type of the array and not the -array itself. - -@smallexample -extern void -transpose (int N, int M, double out[M][N], const double in[N][M]); -double x[3][2]; -double y[2][3]; -@r{@dots{}} -transpose(3, 2, y, x); -@end smallexample - @node Initializers -@section Non-Constant Initializers +@subsection Non-Constant Initializers @cindex initializers, non-constant @cindex non-constant initializers @@ -2198,7 +1074,7 @@ foo (float f, float g) @end smallexample @node Compound Literals -@section Compound Literals +@subsection Compound Literals @cindex constructor expressions @cindex initializations in expressions @cindex structures, constructor expression @@ -2300,7 +1176,7 @@ duration. But it is probably safest just to avoid the use of array compound literals in C++ code. @node Designated Inits -@section Designated Initializers +@subsection Designated Initializers @cindex initializers with labeled elements @cindex labeled elements in initializers @cindex case labels in initializers @@ -2442,134 +1318,298 @@ struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; If the same field is initialized multiple times, or overlapping fields of a union are initialized, the value from the last -initialization is used. When a field of a union is itself a structure, +initialization is used. When a field of a union is itself a structure, the entire structure from the last field initialized is used. If any previous initializer has side effect, it is unspecified whether the side effect happens or not. Currently, GCC discards the side-effecting initializer expressions and issues a warning. -@node Case Ranges -@section Case Ranges -@cindex case ranges -@cindex ranges in case statements +@node Named Address Spaces +@section Named Address Spaces +@cindex Named Address Spaces -You can specify a range of consecutive values in a single @code{case} label, -like this: +As an extension, GNU C supports named address spaces as +defined in the N1275 draft of ISO/IEC DTR 18037. Support for named +address spaces in GCC will evolve as the draft technical report +changes. Calling conventions for any target might also change. At +present, only the AVR, M32C, PRU, RL78, and x86 targets support +address spaces other than the generic address space. -@smallexample -case @var{low} ... @var{high}: -@end smallexample +Address space identifiers may be used exactly like any other C type +qualifier (e.g., @code{const} or @code{volatile}). See the N1275 +document for more details. -@noindent -This has the same effect as the proper number of individual @code{case} -labels, one for each integer value from @var{low} to @var{high}, inclusive. +@anchor{AVR Named Address Spaces} +@subsection AVR Named Address Spaces -This feature is especially useful for ranges of ASCII character codes: +On the AVR target, there are several address spaces that can be used +in order to put read-only data into the flash memory and access that +data by means of the special instructions @code{LPM} or @code{ELPM} +needed to read from flash. -@smallexample -case 'A' ... 'Z': -@end smallexample +Devices belonging to @code{avrtiny} and @code{avrxmega3} can access +flash memory by means of @code{LD*} instructions because the flash +memory is mapped into the RAM address space. There is @emph{no need} +for language extensions like @code{__flash} or attribute +@ref{AVR Variable Attributes,,@code{progmem}}. +The default linker description files for these devices cater for that +feature and @code{.rodata} stays in flash: The compiler just generates +@code{LD*} instructions, and the linker script adds core specific +offsets to all @code{.rodata} symbols: @code{0x4000} in the case of +@code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}. +See @ref{AVR Options} for a list of respective devices. -@strong{Be careful:} Write spaces around the @code{...}, for otherwise -it may be parsed wrong when you use it with integer values. For example, -write this: +For devices not in @code{avrtiny} or @code{avrxmega3}, +any data including read-only data is located in RAM (the generic +address space) because flash memory is not visible in the RAM address +space. In order to locate read-only data in flash memory @emph{and} +to generate the right instructions to access this data without +using (inline) assembler code, special address spaces are needed. -@smallexample -case 1 ... 5: -@end smallexample +@table @code +@cindex @code{__flash} AVR Named Address Spaces +@item __flash +The @code{__flash} qualifier locates data in the +@code{.progmem.data} section. Data is read using the @code{LPM} +instruction. Pointers to this address space are 16 bits wide. -@noindent -rather than this: +@cindex @code{__flash1} AVR Named Address Spaces +@cindex @code{__flash2} AVR Named Address Spaces +@cindex @code{__flash3} AVR Named Address Spaces +@cindex @code{__flash4} AVR Named Address Spaces +@cindex @code{__flash5} AVR Named Address Spaces +@item __flash1 +@itemx __flash2 +@itemx __flash3 +@itemx __flash4 +@itemx __flash5 +These are 16-bit address spaces locating data in section +@code{.progmem@var{N}.data} where @var{N} refers to +address space @code{__flash@var{N}}. +The compiler sets the @code{RAMPZ} segment register appropriately +before reading data by means of the @code{ELPM} instruction. -@smallexample -case 1...5: -@end smallexample +@cindex @code{__flashx} AVR Named Address Spaces +@item __flashx -@node Cast to Union -@section Cast to a Union Type -@cindex cast to a union -@cindex union, casting to a +This is a 24-bit flash address space locating data in section +@code{.progmemx.data}. +The compiler sets the @code{RAMPZ} segment register appropriately +before reading data by means of the @code{ELPM} instruction. -A cast to a union type is a C extension not available in C++. It looks -just like ordinary casts with the constraint that the type specified is -a union type. You can specify the type either with the @code{union} -keyword or with a @code{typedef} name that refers to a union. The result -of a cast to a union is a temporary rvalue of the union type with a member -whose type matches that of the operand initialized to the value of -the operand. The effect of a cast to a union is similar to a compound -literal except that it yields an rvalue like standard casts do. -@xref{Compound Literals}. +@cindex @code{__memx} AVR Named Address Spaces +@item __memx +This is a 24-bit address space that linearizes flash and RAM: +If the high bit of the address is set, data is read from +RAM using the lower two bytes as RAM address. +If the high bit of the address is clear, data is read from flash +with @code{RAMPZ} set according to the high byte of the address. +@xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}. -Expressions that may be cast to the union type are those whose type matches -at least one of the members of the union. Thus, given the following union -and variables: +Objects in this address space are located in @code{.progmemx.data}. +@end table + +@b{Example} @smallexample -union foo @{ int i; double d; @}; -int x; -double y; -union foo z; +char my_read (const __flash char ** p) +@{ + /* p is a pointer to RAM that points to a pointer to flash. + The first indirection of p reads that flash pointer + from RAM and the second indirection reads a char from this + flash address. */ + + return **p; +@} + +/* Locate array[] in flash memory */ +const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; + +int i = 1; + +int main (void) +@{ + /* Return 17 by reading from flash memory */ + return array[array[i]]; +@} @end smallexample @noindent -both @code{x} and @code{y} can be cast to type @code{union foo} and -the following assignments -@smallexample - z = (union foo) x; - z = (union foo) y; -@end smallexample -are shorthand equivalents of these +For each named address space supported by avr-gcc there is an equally +named but uppercase built-in macro defined. +The purpose is to facilitate testing if respective address space +support is available or not: + @smallexample - z = (union foo) @{ .i = x @}; - z = (union foo) @{ .d = y @}; -@end smallexample +#ifdef __FLASH +const __flash int var = 1; -However, @code{(union foo) FLT_MAX;} is not a valid cast because the union -has no member of type @code{float}. +int read_var (void) +@{ + return var; +@} +#else +#include <avr/pgmspace.h> /* From AVR-LibC */ -Using the cast as the right-hand side of an assignment to a variable of -union type is equivalent to storing in a member of the union with -the same type +const int var PROGMEM = 1; -@smallexample -union foo u; -/* @r{@dots{}} */ -u = (union foo) x @equiv{} u.i = x -u = (union foo) y @equiv{} u.d = y +int read_var (void) +@{ + return (int) pgm_read_word (&var); +@} +#endif /* __FLASH */ @end smallexample -You can also use the union cast as a function argument: +@noindent +Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}} +locates data in flash but +accesses to these data read from generic address space, i.e.@: +from RAM, +so that you need special accessors like @code{pgm_read_byte} +from @w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/,AVR-LibC}} +together with attribute @code{progmem}. + +@noindent +@b{Limitations and Caveats} + +@itemize +@item +Reading across the 64@tie{}KiB section boundary of +the @code{__flash} or @code{__flash@var{N}} address spaces +is not supported. The only address spaces that +support reading across the 64@tie{}KiB flash segment boundaries are +@code{__memx} and @code{__flashx}. + +@item +If you use one of the @code{__flash@var{N}} address spaces +you must arrange your linker script to locate the +@code{.progmem@var{N}.data} sections according to your needs. +For an example, see the +@w{@uref{https://gcc.gnu.org/wiki/avr-gcc#Address_Spaces,avr-gcc wiki}} +@item +Any data or pointers to the non-generic address spaces must +be qualified as @code{const}, i.e.@: as read-only data. +This still applies if the data in one of these address +spaces like software version number or calibration lookup table are intended to +be changed after load time by, say, a boot loader. In this case +the right qualification is @code{const} @code{volatile} so that the compiler +must not optimize away known values or insert them +as immediates into operands of instructions. + +@item +The following code initializes a variable @code{pfoo} +located in static storage with a 24-bit address: @smallexample -void hack (union foo); -/* @r{@dots{}} */ -hack ((union foo) x); +extern const __memx char foo; +const __memx void *pfoo = &foo; @end smallexample -@node Mixed Labels and Declarations -@section Mixed Declarations, Labels and Code -@cindex mixed declarations and code -@cindex declarations, mixed with code -@cindex code, mixed with declarations +@item +On the reduced Tiny devices like ATtiny40, no address spaces are supported. +Just use vanilla C / C++ code without overhead as outlined above. +Attribute @code{progmem} is supported but works differently, +see @ref{AVR Variable Attributes}. -ISO C99 and ISO C++ allow declarations and code to be freely mixed -within compound statements. ISO C23 allows labels to be -placed before declarations and at the end of a compound statement. -As an extension, GNU C also allows all this in C90 mode. For example, -you could do: +@end itemize + +@subsection M32C Named Address Spaces +@cindex @code{__far} M32C Named Address Spaces + +On the M32C target, with the R8C and M16C CPU variants, variables +qualified with @code{__far} are accessed using 32-bit addresses in +order to access memory beyond the first 64@tie{}Ki bytes. If +@code{__far} is used with the M32CM or M32C CPU variants, it has no +effect. + +@subsection PRU Named Address Spaces +@cindex @code{__regio_symbol} PRU Named Address Spaces + +On the PRU target, variables qualified with @code{__regio_symbol} are +aliases used to access the special I/O CPU registers. They must be +declared as @code{extern} because such variables will not be allocated in +any data memory. They must also be marked as @code{volatile}, and can +only be 32-bit integer types. The only names those variables can have +are @code{__R30} and @code{__R31}, representing respectively the +@code{R30} and @code{R31} special I/O CPU registers. Hence the following +example is the only valid usage of @code{__regio_symbol}: @smallexample -int i; -/* @r{@dots{}} */ -i++; -int j = i + 2; +extern volatile __regio_symbol uint32_t __R30; +extern volatile __regio_symbol uint32_t __R31; @end smallexample -Each identifier is visible from where it is declared until the end of -the enclosing block. +@subsection RL78 Named Address Spaces +@cindex @code{__far} RL78 Named Address Spaces + +On the RL78 target, variables qualified with @code{__far} are accessed +with 32-bit pointers (20-bit addresses) rather than the default 16-bit +addresses. Non-far variables are assumed to appear in the topmost +64@tie{}KiB of the address space. + +@subsection x86 Named Address Spaces +@cindex x86 named address spaces + +On the x86 target, variables may be declared as being relative +to the @code{%fs} or @code{%gs} segments. + +@table @code +@cindex @code{__seg_fs} x86 named address space +@cindex @code{__seg_gs} x86 named address space +@item __seg_fs +@itemx __seg_gs +The object is accessed with the respective segment override prefix. + +The respective segment base must be set via some method specific to +the operating system. Rather than require an expensive system call +to retrieve the segment base, these address spaces are not considered +to be subspaces of the generic (flat) address space. This means that +explicit casts are required to convert pointers between these address +spaces and the generic address space. In practice the application +should cast to @code{uintptr_t} and apply the segment base offset +that it installed previously. + +The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are +defined when these address spaces are supported. +@end table + +@node Attributes +@section Attributes Specific to GCC +@cindex attributes +@cindex declaring attributes +@cindex GNU attributes + +Attributes provide a mechanism to declare additional properties of +functions, variables, types, and statements. For example, attributes +can be used to control placement of objects in particular memory +sections, or to specify properties that can allow the compiler to +generate better code or diagnostics, such as declaring that a function +never returns. GCC supports a large number of such attributes, which +are documented in this section. + +GCC provides two different ways to specify attributes: the traditional +GNU syntax using @samp{__attribute__ ((...))} annotations, and the +newer standard C and C++ syntax using @samp{[[...]]} with the +@samp{gnu::} namespace prefix on attribute names. +The traditional syntax, described in detail in @ref{Attribute Syntax}, +is supported in all non-strict C and C++ language dialects. +The standard syntax is supported in C with @option{-std=c23} or later, +in C++ with @option{-std=c++11} or later, and as an extension in older +GNU C and C++ dialects. + +@menu +* Function Attributes:: Declaring that functions have no side effects, + or that they can never return. +* Variable Attributes:: Specifying attributes of variables. +* Type Attributes:: Specifying attributes of types. +* Label Attributes:: Specifying attributes on labels. +* Enumerator Attributes:: Specifying attributes on enumerators. +* Statement Attributes:: Specifying attributes on statements. +* Attribute Syntax:: Formal syntax for attributes. +@end menu @node Function Attributes -@section Declaring Attributes of Functions +@subsection Declaring Attributes of Functions @cindex function attributes @cindex declaring attributes of functions @@ -2671,7 +1711,7 @@ GCC plugins may provide their own attributes. @end menu @node Common Function Attributes -@subsection Common Function Attributes +@subsubsection Common Function Attributes The following attributes are supported on most targets. @@ -2995,24 +2035,32 @@ called. Functions with these attributes are useful for initializing data that is used implicitly during the execution of the program. -On some targets the attributes also accept an integer argument to +On most targets the attributes also accept an integer argument to specify a priority to control the order in which constructor and -destructor functions are run. A constructor -with a smaller priority number runs before a constructor with a larger -priority number; the opposite relationship holds for destructors. Note -that priorities 0-100 are reserved. So, if you have a constructor that +destructor functions are run. The @var{priority} argument is a +constant integral expression bounded between 101 and 65535 inclusive; +priorities 0-100 are reserved for use by the compiler and its runtime +libraries. +A constructor with a smaller priority number runs before a constructor with +a larger priority number; the opposite relationship holds for destructors. +So, if you have a constructor that allocates a resource and a destructor that deallocates the same -resource, both functions typically have the same priority. The -priorities for constructor and destructor functions are the same as -those specified for namespace-scope C++ objects (@pxref{C++ Attributes}). -However, at present, the order in which constructors for C++ objects -with static storage duration and functions decorated with attribute -@code{constructor} are invoked is unspecified. In mixed declarations, -attribute @code{init_priority} can be used to impose a specific ordering. - -Using the argument forms of the @code{constructor} and @code{destructor} -attributes on targets where the feature is not supported is rejected with -an error. +resource, both functions typically have the same priority. + +The order in which constructors for C++ objects with static storage +duration are invoked relative to functions decorated with attribute +@code{constructor} is normally unspecified. You can use +attribute @code{init_priority} (@pxref{C++ Attributes}) on the +declarations of namespace-scope C++ objects to impose a specific +ordering; the @var{priority} for the @code{init_priority} attribute +has the same effect as the @var{priority} for the @code{constructor} +attribute. + +Using the argument form of the @code{constructor} and +@code{destructor} attributes on targets where the feature is not +supported is rejected with an error. Only a few targets (typically +those not using ELF object format, or the GNU linker) reject this +usage. @cindex @code{copy} function attribute @item copy @@ -3191,18 +2239,43 @@ for consistency with the @code{printf} style format string argument @code{my_format}. The parameter @var{archetype} determines how the format string is -interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}, +interpreted. +Valid archetypes include @code{printf}, @code{scanf}, @code{strftime}, @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or @code{strfmon}. (You can also use @code{__printf__}, -@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On -MinGW targets, @code{ms_printf}, @code{ms_scanf}, and -@code{ms_strftime} are also present. +@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) @var{archetype} values such as @code{printf} refer to the formats accepted by the system's C runtime library, while values prefixed with @samp{gnu_} always refer -to the formats accepted by the GNU C Library. On Microsoft Windows -targets, values prefixed with @samp{ms_} refer to the formats accepted by the +to the formats accepted by the GNU C Library. + +@anchor{Target Format Checks} +On MinGW and Microsoft Windows targets, @code{ms_printf}, +@code{ms_scanf}, and @code{ms_strftime} are also present. Values +prefixed with @samp{ms_} refer to the formats accepted by the @file{msvcrt.dll} library. + +@anchor{Solaris Format Checks} +Solaris targets also support the @code{cmn_err} (or @code{__cmn_err__}) +archetype. +@code{cmn_err} accepts a subset of the standard @code{printf} +conversions, and the two-argument @code{%b} conversion for displaying +bit-fields. See the Solaris man page for @code{cmn_err} for more information. + +@anchor{Darwin Format Checks} +Darwin targets also support the @code{CFString} (or +@code{__CFString__}) archetype in the @code{format} attribute. +Declarations with this archetype are parsed for correct syntax +and argument types. However, parsing of the format string itself and +validating arguments against it in calls to such functions is currently +not performed. + +For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is +recognized in the same context. Declarations including these format attributes +are parsed for correct syntax, however the result of checking of such format +strings is not yet defined, and is not carried out by this version of the +compiler. + The parameter @var{string-index} specifies which argument is the format string argument (starting from 1), while @var{first-to-check} is the number of the first @@ -3237,15 +2310,7 @@ standard modes, the X/Open function @code{strfmon} is also checked as are @code{printf_unlocked} and @code{fprintf_unlocked}. @xref{C Dialect Options,,Options Controlling C Dialect}. -For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is -recognized in the same context. Declarations including these format attributes -are parsed for correct syntax, however the result of checking of such format -strings is not yet defined, and is not carried out by this version of the -compiler. -The target may also provide additional types of format checks. -@xref{Target Format Checks,,Format Checks Specific to Particular -Target Machines}. @cindex @code{format_arg} function attribute @opindex Wformat-nonliteral @@ -3300,13 +2365,17 @@ requested by @option{-ansi} or an appropriate @option{-std} option, or is used. @xref{C Dialect Options,,Options Controlling C Dialect}. -For Objective-C dialects, the @code{format-arg} attribute may refer to an +For Objective-C dialects, the @code{format_arg} attribute may refer to an @code{NSString} reference for compatibility with the @code{format} attribute above. -The target may also allow additional types in @code{format-arg} attributes. -@xref{Target Format Checks,,Format Checks Specific to Particular -Target Machines}. +Similarly, on Darwin targets @code{CFStringRefs} (defined by the +@code{CoreFoundation} headers) may also be used as format arguments. +Note that the relevant headers are only likely to be available on +Darwin (OSX) installations. On such installations, the XCode and +system documentation provide descriptions of @code{CFString}, +@code{CFStringRefs} and associated functions. + @cindex @code{gnu_inline} function attribute @item gnu_inline @@ -4712,7 +3781,7 @@ The default for the attribute is controlled by @option{-fzero-call-used-regs}. @c This is the end of the target-independent attribute table @node AArch64 Function Attributes -@subsection AArch64 Function Attributes +@subsubsection AArch64 Function Attributes The following target-specific function attributes are available for the AArch64 target. For the most part, these options mirror the behavior of @@ -4859,7 +3928,7 @@ foo (int a) is valid and compiles function @code{foo} for ARMv8-A with @code{crc} and @code{crypto} extensions and tunes it for @code{cortex-a53}. -@subsubsection Inlining rules +@subsubheading Inlining rules Specifying target attributes on individual functions or performing link-time optimization across translation units compiled with different target options can affect function inlining rules: @@ -4885,7 +3954,7 @@ Note that CPU tuning options and attributes such as the @option{-mcpu=}, architectural feature rules specified above. @node AMD GCN Function Attributes -@subsection AMD GCN Function Attributes +@subsubsection AMD GCN Function Attributes These function attributes are supported by the AMD GCN back end: @@ -4975,7 +4044,7 @@ OpenACC/OpenMP). @end table @node ARC Function Attributes -@subsection ARC Function Attributes +@subsubsection ARC Function Attributes These function attributes are supported by the ARC back end: @@ -5053,7 +4122,7 @@ are not supported. @end table @node ARM Function Attributes -@subsection ARM Function Attributes +@subsubsection ARM Function Attributes These function attributes are supported for ARM targets: @@ -5205,7 +4274,7 @@ without modifying an existing @option{-march=} or @option{-mcpu} option. @end table @node AVR Function Attributes -@subsection AVR Function Attributes +@subsubsection AVR Function Attributes These function attributes are supported by the AVR back end: @@ -5377,7 +4446,7 @@ as needed. @end table @node Blackfin Function Attributes -@subsection Blackfin Function Attributes +@subsubsection Blackfin Function Attributes These function attributes are supported by the Blackfin back end: @@ -5455,7 +4524,7 @@ regardless of whether they are used or not. @end table @node BPF Function Attributes -@subsection BPF Function Attributes +@subsubsection BPF Function Attributes These function attributes are supported by the BPF back end: @@ -5484,7 +4553,7 @@ are not supported. @end table @node C-SKY Function Attributes -@subsection C-SKY Function Attributes +@subsubsection C-SKY Function Attributes These function attributes are supported by the C-SKY back end: @@ -5516,7 +4585,7 @@ depended upon to work reliably and are not supported. @node Epiphany Function Attributes -@subsection Epiphany Function Attributes +@subsubsection Epiphany Function Attributes These function attributes are supported by the Epiphany back end: @@ -5589,7 +4658,7 @@ command-line switch and @code{#pragma long_calls} settings. @node H8/300 Function Attributes -@subsection H8/300 Function Attributes +@subsubsection H8/300 Function Attributes These function attributes are available for H8/300 targets: @@ -5619,7 +4688,7 @@ regardless of whether they are used or not. @end table @node IA-64 Function Attributes -@subsection IA-64 Function Attributes +@subsubsection IA-64 Function Attributes These function attributes are supported on IA-64 targets: @@ -5648,7 +4717,7 @@ Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}. @end table @node LoongArch Function Attributes -@subsection LoongArch Function Attributes +@subsubsection LoongArch Function Attributes These function attributes are supported by the LoongArch end: @@ -5722,7 +4791,7 @@ $ gcc test.c -o test.s -O2 -mlasx -mno-lasx @end table @node M32C Function Attributes -@subsection M32C Function Attributes +@subsubsection M32C Function Attributes These function attributes are supported by the M32C back end: @@ -5785,7 +4854,7 @@ when this attribute is present. @end table @node M32R/D Function Attributes -@subsection M32R/D Function Attributes +@subsubsection M32R/D Function Attributes These function attributes are supported by the M32R/D back end: @@ -5821,7 +4890,7 @@ generates the much slower @code{seth/add3/jl} instruction sequence). @end table @node m68k Function Attributes -@subsection m68k Function Attributes +@subsubsection m68k Function Attributes These function attributes are supported by the m68k back end: @@ -5845,7 +4914,7 @@ instruction. This attribute is available only on fido. @end table @node MCORE Function Attributes -@subsection MCORE Function Attributes +@subsubsection MCORE Function Attributes These function attributes are supported by the MCORE back end: @@ -5863,7 +4932,7 @@ depended upon to work reliably and are not supported. @end table @node MicroBlaze Function Attributes -@subsection MicroBlaze Function Attributes +@subsubsection MicroBlaze Function Attributes These function attributes are supported on MicroBlaze targets: @@ -5902,7 +4971,7 @@ using @code{rtid} instead of @code{rtsd}. @end table @node Microsoft Windows Function Attributes -@subsection Microsoft Windows Function Attributes +@subsubsection Microsoft Windows Function Attributes The following attributes are available on Microsoft Windows and Symbian OS targets. @@ -6000,7 +5069,7 @@ for functions by setting the @option{-mnop-fun-dllimport} flag. @end table @node MIPS Function Attributes -@subsection MIPS Function Attributes +@subsubsection MIPS Function Attributes These function attributes are supported by the MIPS back end: @@ -6150,7 +5219,7 @@ If there is no argument supplied, the default of @code{"yes"} applies. @end table @node MSP430 Function Attributes -@subsection MSP430 Function Attributes +@subsubsection MSP430 Function Attributes These function attributes are supported by the MSP430 back end: @@ -6241,7 +5310,7 @@ easier to pack regions. @end table @node NDS32 Function Attributes -@subsection NDS32 Function Attributes +@subsubsection NDS32 Function Attributes These function attributes are supported by the NDS32 back end: @@ -6310,7 +5379,7 @@ Provide a user-defined function to handle warm reset exception. @end table @node Nvidia PTX Function Attributes -@subsection Nvidia PTX Function Attributes +@subsubsection Nvidia PTX Function Attributes These function attributes are supported by the Nvidia PTX back end: @@ -6326,7 +5395,7 @@ Kernel functions must have @code{void} return type. @end table @node PowerPC Function Attributes -@subsection PowerPC Function Attributes +@subsubsection PowerPC Function Attributes These function attributes are supported by the PowerPC back end: @@ -6523,7 +5592,7 @@ callee has a subset of the target options of the caller. @end table @node RISC-V Function Attributes -@subsection RISC-V Function Attributes +@subsubsection RISC-V Function Attributes These function attributes are supported by the RISC-V back end: @@ -6626,7 +5695,7 @@ is valid and compiles function @code{foo} with @code{zba} and @code{zbb} extensions and tunes it for @code{rocket}. @node RL78 Function Attributes -@subsection RL78 Function Attributes +@subsubsection RL78 Function Attributes These function attributes are supported by the RL78 back end: @@ -6657,7 +5726,7 @@ depended upon to work reliably and are not supported. @end table @node RX Function Attributes -@subsection RX Function Attributes +@subsubsection RX Function Attributes These function attributes are supported by the RX back end: @@ -6718,7 +5787,7 @@ function (i.e.@: it retains the normal C function calling ABI). See the @end table @node S/390 Function Attributes -@subsection S/390 Function Attributes +@subsubsection S/390 Function Attributes These function attributes are supported on the S/390: @@ -6783,7 +5852,7 @@ does not undefine the @code{__VEC__} macro. @end table @node SH Function Attributes -@subsection SH Function Attributes +@subsubsection SH Function Attributes These function attributes are supported on the SH family of processors: @@ -6865,13 +5934,13 @@ but it does not save and restore all registers. @end table @node Symbian OS Function Attributes -@subsection Symbian OS Function Attributes +@subsubsection Symbian OS Function Attributes @xref{Microsoft Windows Function Attributes}, for discussion of the @code{dllexport} and @code{dllimport} attributes. @node V850 Function Attributes -@subsection V850 Function Attributes +@subsubsection V850 Function Attributes The V850 back end supports these function attributes: @@ -6887,7 +5956,7 @@ when either attribute is present. @end table @node Visium Function Attributes -@subsection Visium Function Attributes +@subsubsection Visium Function Attributes These function attributes are supported by the Visium back end: @@ -6901,7 +5970,7 @@ when this attribute is present. @end table @node x86 Function Attributes -@subsection x86 Function Attributes +@subsubsection x86 Function Attributes These function attributes are supported by the x86 back end: @@ -7611,6 +6680,12 @@ EGPR, PUSH2POP2, NDD and PPX. Enable the generation of the AVX10.1 instructions with 256 bit support. Disable the generation of the AVX10.1 instructions. +@cindex @code{target("avx10.1")} function attribute, x86 +@item avx10.1 +@itemx no-avx10.1 +Enable the generation of the AVX10.1 instructions with 512 bit support. +Disable the generation of the AVX10.1 instructions. + @cindex @code{target("avx10.1-512")} function attribute, x86 @item avx10.1-512 @itemx no-avx10.1-512 @@ -7620,16 +6695,7 @@ Disable the generation of the AVX10.1 instructions. @cindex @code{target("avx10.2")} function attribute, x86 @item avx10.2 @itemx no-avx10.2 -Enable the generation of the AVX10.2 instructions with 512 bit support. -Disable the generation of the AVX10.2 instructions. - -@cindex @code{target("avx10.2-256")} function attribute, x86 -@item avx10.2-256 -Enable the generation of the AVX10.2 instructions with 256 bit support. - -@cindex @code{target("avx10.2-512")} function attribute, x86 -@item avx10.2-512 -Enable the generation of the AVX10.2 instructions with 512 bit support. +Enable/Disable the generation of the AVX10.2 instructions. @cindex @code{target("amx-avx512")} function attribute, x86 @item amx-avx512 @@ -7854,7 +6920,7 @@ counterpart to option @option{-mno-direct-extern-access}. @end table -@subsubsection Inlining rules +@subsubheading Inlining rules On the x86, the inliner does not inline a function that has different target options than the caller, unless the callee has a subset of the target options of the caller. For example @@ -7869,7 +6935,7 @@ a function with default @option{-march=x86-64} and of ISA features and marked with always_inline. @node Xstormy16 Function Attributes -@subsection Xstormy16 Function Attributes +@subsubsection Xstormy16 Function Attributes These function attributes are supported by the Xstormy16 back end: @@ -7883,7 +6949,7 @@ when this attribute is present. @end table @node Variable Attributes -@section Specifying Attributes of Variables +@subsection Specifying Attributes of Variables @cindex attribute of variables @cindex variable attributes @@ -7925,7 +6991,7 @@ which syntax you use. @xref{Attribute Syntax}, for details. @end menu @node Common Variable Attributes -@subsection Common Variable Attributes +@subsubsection Common Variable Attributes The following attributes are supported on most targets. @@ -8575,7 +7641,7 @@ The @code{weak} attribute is described in @end table @node ARC Variable Attributes -@subsection ARC Variable Attributes +@subsubsection ARC Variable Attributes @table @code @cindex @code{aux} variable attribute, ARC @@ -8587,7 +7653,7 @@ given via attribute argument. @end table @node AVR Variable Attributes -@subsection AVR Variable Attributes +@subsubsection AVR Variable Attributes @table @code @cindex @code{progmem} variable attribute, AVR @@ -8752,7 +7818,7 @@ See also the @option{-mabsdata} @ref{AVR Options,command-line option}. @end table @node Blackfin Variable Attributes -@subsection Blackfin Variable Attributes +@subsubsection Blackfin Variable Attributes Three attributes are currently defined for the Blackfin. @@ -8777,7 +7843,7 @@ named @code{.l2.data}. @end table @node H8/300 Variable Attributes -@subsection H8/300 Variable Attributes +@subsubsection H8/300 Variable Attributes These variable attributes are available for H8/300 targets: @@ -8806,7 +7872,7 @@ slightly under 32KB of data. @end table @node IA-64 Variable Attributes -@subsection IA-64 Variable Attributes +@subsubsection IA-64 Variable Attributes The IA-64 back end supports the following variable attribute: @@ -8825,7 +7891,7 @@ defined by shared libraries. @end table @node LoongArch Variable Attributes -@subsection LoongArch Variable Attributes +@subsubsection LoongArch Variable Attributes One attribute is currently defined for the LoongArch. @@ -8841,7 +7907,7 @@ specially. Currently the only supported values of @var{name} are @end table @node M32R/D Variable Attributes -@subsection M32R/D Variable Attributes +@subsubsection M32R/D Variable Attributes One attribute is currently defined for the M32R/D@. @@ -8862,7 +7928,7 @@ addresses). @end table @node Microsoft Windows Variable Attributes -@subsection Microsoft Windows Variable Attributes +@subsubsection Microsoft Windows Variable Attributes You can use these attributes on Microsoft Windows targets. @ref{x86 Variable Attributes} for additional Windows compatibility @@ -8927,7 +7993,7 @@ The @code{shared} attribute is only available on Microsoft Windows@. @end table @node MSP430 Variable Attributes -@subsection MSP430 Variable Attributes +@subsubsection MSP430 Variable Attributes @table @code @cindex @code{upper} variable attribute, MSP430 @@ -8957,7 +8023,7 @@ will be used, and the @code{.lower} prefix will not be added. @end table @node Nvidia PTX Variable Attributes -@subsection Nvidia PTX Variable Attributes +@subsubsection Nvidia PTX Variable Attributes These variable attributes are supported by the Nvidia PTX back end: @@ -8971,7 +8037,7 @@ The runtime does not initialize variables in this memory space. @end table @node PowerPC Variable Attributes -@subsection PowerPC Variable Attributes +@subsubsection PowerPC Variable Attributes Three attributes currently are defined for PowerPC configurations: @code{altivec}, @code{ms_struct} and @code{gcc_struct}. @@ -8986,7 +8052,7 @@ For documentation of @code{altivec} attribute please see the documentation in @ref{PowerPC Type Attributes}. @node RL78 Variable Attributes -@subsection RL78 Variable Attributes +@subsubsection RL78 Variable Attributes @cindex @code{saddr} variable attribute, RL78 The RL78 back end supports the @code{saddr} variable attribute. This @@ -8994,7 +8060,7 @@ specifies placement of the corresponding variable in the SADDR area, which can be accessed more efficiently than the default memory region. @node V850 Variable Attributes -@subsection V850 Variable Attributes +@subsubsection V850 Variable Attributes These variable attributes are supported by the V850 back end: @@ -9017,7 +8083,7 @@ of memory. @end table @node x86 Variable Attributes -@subsection x86 Variable Attributes +@subsubsection x86 Variable Attributes Two attributes are currently defined for x86 configurations: @code{ms_struct} and @code{gcc_struct}. @@ -9045,7 +8111,7 @@ attributes on types. @end table @node Xstormy16 Variable Attributes -@subsection Xstormy16 Variable Attributes +@subsubsection Xstormy16 Variable Attributes One attribute is currently defined for xstormy16 configurations: @code{below100}. @@ -9063,7 +8129,7 @@ placed in either the @code{.bss_below100} section or the @end table @node Type Attributes -@section Specifying Attributes of Types +@subsection Specifying Attributes of Types @cindex attribute of types @cindex type attributes @@ -9105,7 +8171,7 @@ the closing brace. You can also include type attributes in a @end menu @node Common Type Attributes -@subsection Common Type Attributes +@subsubsection Common Type Attributes The following type attributes are supported on most targets. @@ -9974,7 +9040,7 @@ double parentheses: for example, @samp{__attribute__ ((aligned (16), packed))}. @node ARC Type Attributes -@subsection ARC Type Attributes +@subsubsection ARC Type Attributes @cindex @code{uncached} type attribute, ARC Declaring objects with @code{uncached} allows you to exclude @@ -9984,7 +9050,7 @@ without involving the additional semantic implications of loads and stores of data declared @code{uncached}. @node ARM Type Attributes -@subsection ARM Type Attributes +@subsubsection ARM Type Attributes @cindex @code{notshared} type attribute, ARM On those ARM targets that support @code{dllimport} (such as Symbian @@ -10010,7 +9076,7 @@ virtual table for @code{C} is not exported. (You can use most Symbian OS code uses @code{__declspec}.) @node BPF Type Attributes -@subsection BPF Type Attributes +@subsubsection BPF Type Attributes @cindex @code{preserve_access_index} type attribute, BPF BPF Compile Once - Run Everywhere (CO-RE) support. When attached to a @@ -10021,7 +9087,7 @@ wrapping every such access with @code{__builtin_preserve_access_index}. @node PowerPC Type Attributes -@subsection PowerPC Type Attributes +@subsubsection PowerPC Type Attributes Three attributes currently are defined for PowerPC configurations: @code{altivec}, @code{ms_struct} and @code{gcc_struct}. @@ -10048,7 +9114,7 @@ These attributes mainly are intended to support the @code{__vector}, @code{__pixel}, and @code{__bool} AltiVec keywords. @node x86 Type Attributes -@subsection x86 Type Attributes +@subsubsection x86 Type Attributes Two attributes are currently defined for x86 configurations: @code{ms_struct} and @code{gcc_struct}. @@ -10077,7 +9143,7 @@ attributes on variables. @end table @node Label Attributes -@section Label Attributes +@subsection Label Attributes @cindex Label Attributes GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for @@ -10133,7 +9199,7 @@ with computed goto or @code{asm goto}. @end table @node Enumerator Attributes -@section Enumerator Attributes +@subsection Enumerator Attributes @cindex Enumerator Attributes GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for @@ -10178,7 +9244,7 @@ same manner as the @code{deprecated} attribute. @end table @node Statement Attributes -@section Statement Attributes +@subsection Statement Attributes @cindex Statement Attributes GCC allows attributes to be set on statements. @xref{Attribute Syntax}, @@ -10257,14 +9323,80 @@ __attribute__((musttail)) return bar(); If the compiler cannot generate a @code{musttail} tail call it will report an error. On some targets tail calls may never be supported. -Tail calls cannot reference locals in memory, which may affect -builds without optimization when passing small structures, or passing -or returning large structures. Enabling @option{-O1} or @option{-O2} can -improve the success of tail calls. +The user asserts for @code{musttail} tail calls that lifetime of automatic +variables, function parameters and temporaries (unless they have non-trivial +destruction) can end before the actual call instruction and that any access +to those from inside of the called function results is considered undefined +behavior. Enabling @option{-O1} or @option{-O2} can improve the success of +tail calls. + +@smallexample +int foo (int *); +void bar (int *); +struct S @{ S (); ~S (); int s; @}; + +int +baz (int *x) +@{ + if (*x == 1) + @{ + int a = 42; + /* The call will be tail called (would not be without the + attribute), dereferencing the pointer in the callee is + undefined behavior and there will be a warning emitted + for this by default (@option{-Wmusttail-local-addr}). */ + [[gnu::musttail]] return foo (&a); + @} + else if (*x == 2) + @{ + int a = 42; + bar (&a); + /* The call will be tail called (would not be without the + attribute), if bar stores the pointer anywhere, dereferencing + it in foo will be undefined behavior and there will be a warning + emitted for this with @option{-Wextra}, which implies + @option{-Wmaybe-musttail-local-addr}. */ + [[gnu::musttail]] return foo (nullptr); + @} + else + @{ + S s; + /* The s variable requires non-trivial destruction which ought + to be performed after the foo call returns, so this will + be rejected. */ + [[gnu::musttail]] return foo (&s.s); + @} +@} +@end smallexample + +To avoid the @option{-Wmaybe-musttail-local-addr} warning in the +above @code{*x == 2} case and similar code, consider defining the +maybe escaped variables in a separate scope which will end before the +return statement if possible to make it clear that the variable is not +live during the call. So + +@smallexample + else if (*x == 2) + @{ + @{ + int a = 42; + bar (&a); + @} + /* The call will be tail called (would not be without the + attribute), if bar stores the pointer anywhere, dereferencing + it in foo will be undefined behavior and there will be a warning + emitted for this with @option{-Wextra}, which implies + @option{-Wmaybe-musttail-local-addr}. */ + [[gnu::musttail]] return foo (nullptr); + @} +@end smallexample + +in this case. That is not possible if it is function argument which +is address taken because those are in scope for the whole function. @end table @node Attribute Syntax -@section Attribute Syntax +@subsection Attribute Syntax @cindex attribute syntax @cindex C standard attributes @cindex C++ standard attributes @@ -10551,134 +9683,989 @@ target type; if such an attribute is applied to a function return type that is not a pointer-to-function type, it is treated as applying to the function type. -@node Function Prototypes -@section Prototypes and Old-Style Function Definitions -@cindex function prototype declarations -@cindex old-style function definitions -@cindex promotion of formal parameters +@node Pragmas +@section Pragmas Accepted by GCC +@cindex pragmas +@cindex @code{#pragma} -GNU C extends ISO C to allow a function prototype to override a later -old-style non-prototype definition. Consider the following example: +GCC supports several types of pragmas, primarily in order to compile +code originally written for other compilers. Note that in general +we do not recommend the use of pragmas; @xref{Function Attributes}, +for further explanation. + +The GNU C preprocessor recognizes several pragmas in addition to the +compiler pragmas documented here. Refer to the CPP manual for more +information. + +GCC additionally recognizes OpenMP pragmas when the @option{-fopenmp} +option is specified, and OpenACC pragmas when the @option{-fopenacc} +option is specified. @xref{OpenMP}, and @ref{OpenACC}. + +@menu +* AArch64 Pragmas:: +* ARM Pragmas:: +* LoongArch Pragmas:: +* M32C Pragmas:: +* PRU Pragmas:: +* RS/6000 and PowerPC Pragmas:: +* S/390 Pragmas:: +* Darwin Pragmas:: +* Solaris Pragmas:: +* Symbol-Renaming Pragmas:: +* Structure-Layout Pragmas:: +* Weak Pragmas:: +* Diagnostic Pragmas:: +* Visibility Pragmas:: +* Push/Pop Macro Pragmas:: +* Function Specific Option Pragmas:: +* Loop-Specific Pragmas:: +@end menu +@node AArch64 Pragmas +@subsection AArch64 Pragmas + +The pragmas defined by the AArch64 target correspond to the AArch64 +target function attributes. They can be specified as below: @smallexample -/* @r{Use prototypes unless the compiler is old-fashioned.} */ -#ifdef __STDC__ -#define P(x) x -#else -#define P(x) () -#endif +#pragma GCC target("string") +@end smallexample -/* @r{Prototype function declaration.} */ -int isroot P((uid_t)); +where @code{@var{string}} can be any string accepted as an AArch64 target +attribute. @xref{AArch64 Function Attributes}, for more details +on the permissible values of @code{string}. -/* @r{Old-style function definition.} */ -int -isroot (x) /* @r{??? lossage here ???} */ - uid_t x; +@node ARM Pragmas +@subsection ARM Pragmas + +The ARM target defines pragmas for controlling the default addition of +@code{long_call} and @code{short_call} attributes to functions. +@xref{Function Attributes}, for information about the effects of these +attributes. + +@table @code +@cindex pragma, long_calls +@item long_calls +Set all subsequent functions to have the @code{long_call} attribute. + +@cindex pragma, no_long_calls +@item no_long_calls +Set all subsequent functions to have the @code{short_call} attribute. + +@cindex pragma, long_calls_off +@item long_calls_off +Do not affect the @code{long_call} or @code{short_call} attributes of +subsequent functions. +@end table + +@node LoongArch Pragmas +@subsection LoongArch Pragmas + +The list of attributes supported by Pragma is the same as that of target +function attributes. @xref{LoongArch Function Attributes}. + +Example: + +@smallexample +#pragma GCC target("strict-align") +@end smallexample + +@node M32C Pragmas +@subsection M32C Pragmas + +@table @code +@cindex pragma, memregs +@item GCC memregs @var{number} +Overrides the command-line option @code{-memregs=} for the current +file. Use with care! This pragma must be before any function in the +file, and mixing different memregs values in different objects may +make them incompatible. This pragma is useful when a +performance-critical function uses a memreg for temporary values, +as it may allow you to reduce the number of memregs used. + +@cindex pragma, address +@item ADDRESS @var{name} @var{address} +For any declared symbols matching @var{name}, this does three things +to that symbol: it forces the symbol to be located at the given +address (a number), it forces the symbol to be volatile, and it +changes the symbol's scope to be static. This pragma exists for +compatibility with other compilers, but note that the common +@code{1234H} numeric syntax is not supported (use @code{0x1234} +instead). Example: + +@smallexample +#pragma ADDRESS port3 0x103 +char port3; +@end smallexample + +@end table + +@node PRU Pragmas +@subsection PRU Pragmas + +@table @code + +@cindex pragma, ctable_entry +@item ctable_entry @var{index} @var{constant_address} +Specifies that the PRU CTABLE entry given by @var{index} has the value +@var{constant_address}. This enables GCC to emit LBCO/SBCO instructions +when the load/store address is known and can be addressed with some CTABLE +entry. For example: + +@smallexample +/* will compile to "sbco Rx, 2, 0x10, 4" */ +#pragma ctable_entry 2 0x4802a000 +*(unsigned int *)0x4802a010 = val; +@end smallexample + +@end table + +@node RS/6000 and PowerPC Pragmas +@subsection RS/6000 and PowerPC Pragmas + +The RS/6000 and PowerPC targets define one pragma for controlling +whether or not the @code{longcall} attribute is added to function +declarations by default. This pragma overrides the @option{-mlongcall} +option, but not the @code{longcall} and @code{shortcall} attributes. +@xref{RS/6000 and PowerPC Options}, for more information about when long +calls are and are not necessary. + +@table @code +@cindex pragma, longcall +@item longcall (1) +Apply the @code{longcall} attribute to all subsequent function +declarations. + +@item longcall (0) +Do not apply the @code{longcall} attribute to subsequent function +declarations. +@end table + +@c Describe h8300 pragmas here. +@c Describe sh pragmas here. +@c Describe v850 pragmas here. + +@node S/390 Pragmas +@subsection S/390 Pragmas + +The pragmas defined by the S/390 target correspond to the S/390 +target function attributes and some the additional options: + +@table @samp +@item zvector +@itemx no-zvector +@end table + +Note that options of the pragma, unlike options of the target +attribute, do change the value of preprocessor macros like +@code{__VEC__}. They can be specified as below: + +@smallexample +#pragma GCC target("string[,string]...") +#pragma GCC target("string"[,"string"]...) +@end smallexample + +@node Darwin Pragmas +@subsection Darwin Pragmas + +The following pragmas are available for all architectures running the +Darwin operating system. These are useful for compatibility with other +macOS compilers. + +@table @code +@cindex pragma, mark +@item mark @var{tokens}@dots{} +This pragma is accepted, but has no effect. + +@cindex pragma, options align +@item options align=@var{alignment} +This pragma sets the alignment of fields in structures. The values of +@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or +@code{power}, to emulate PowerPC alignment. Uses of this pragma nest +properly; to restore the previous setting, use @code{reset} for the +@var{alignment}. + +@cindex pragma, segment +@item segment @var{tokens}@dots{} +This pragma is accepted, but has no effect. + +@cindex pragma, unused +@item unused (@var{var} [, @var{var}]@dots{}) +This pragma declares variables to be possibly unused. GCC does not +produce warnings for the listed variables. The effect is similar to +that of the @code{unused} attribute, except that this pragma may appear +anywhere within the variables' scopes. +@end table + +@node Solaris Pragmas +@subsection Solaris Pragmas + +The Solaris target supports @code{#pragma redefine_extname} +(@pxref{Symbol-Renaming Pragmas}). It also supports additional +@code{#pragma} directives for compatibility with the system compiler. + +@table @code +@cindex pragma, align +@item align @var{alignment} (@var{variable} [, @var{variable}]...) + +Increase the minimum alignment of each @var{variable} to @var{alignment}. +This is the same as GCC's @code{aligned} attribute @pxref{Variable +Attributes}). Macro expansion occurs on the arguments to this pragma +when compiling C and Objective-C@. It does not currently occur when +compiling C++, but this is a bug which may be fixed in a future +release. + +@cindex pragma, fini +@item fini (@var{function} [, @var{function}]...) + +This pragma causes each listed @var{function} to be called after +main, or during shared module unloading, by adding a call to the +@code{.fini} section. + +@cindex pragma, init +@item init (@var{function} [, @var{function}]...) + +This pragma causes each listed @var{function} to be called during +initialization (before @code{main}) or during shared module loading, by +adding a call to the @code{.init} section. + +@end table + +@node Symbol-Renaming Pragmas +@subsection Symbol-Renaming Pragmas + +GCC supports a @code{#pragma} directive that changes the name used in +assembly for a given declaration. While this pragma is supported on all +platforms, it is intended primarily to provide compatibility with the +Solaris system headers. This effect can also be achieved using the asm +labels extension (@pxref{Asm Labels}). + +@table @code +@cindex pragma, redefine_extname +@item redefine_extname @var{oldname} @var{newname} + +This pragma gives the C function @var{oldname} the assembly symbol +@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} +is defined if this pragma is available (currently on all platforms). +@end table + +This pragma and the @code{asm} labels extension interact in a complicated +manner. Here are some corner cases you may want to be aware of: + +@enumerate +@item This pragma silently applies only to declarations with external +linkage. The @code{asm} label feature does not have this restriction. + +@item In C++, this pragma silently applies only to declarations with +``C'' linkage. Again, @code{asm} labels do not have this restriction. + +@item If either of the ways of changing the assembly name of a +declaration are applied to a declaration whose assembly name has +already been determined (either by a previous use of one of these +features, or because the compiler needed the assembly name in order to +generate code), and the new name is different, a warning issues and +the name does not change. + +@item The @var{oldname} used by @code{#pragma redefine_extname} is +always the C-language name. +@end enumerate + +@node Structure-Layout Pragmas +@subsection Structure-Layout Pragmas + +For compatibility with Microsoft Windows compilers, GCC supports a +set of @code{#pragma} directives that change the maximum alignment of +members of structures (other than zero-width bit-fields), unions, and +classes subsequently defined. The @var{n} value below always is required +to be a small power of two and specifies the new alignment in bytes. + +@enumerate +@item @code{#pragma pack(@var{n})} simply sets the new alignment. +@item @code{#pragma pack()} sets the alignment to the one that was in +effect when compilation started (see also command-line option +@option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). +@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment +setting on an internal stack and then optionally sets the new alignment. +@item @code{#pragma pack(pop)} restores the alignment setting to the one +saved at the top of the internal stack (and removes that stack entry). +Note that @code{#pragma pack([@var{n}])} does not influence this internal +stack; thus it is possible to have @code{#pragma pack(push)} followed by +multiple @code{#pragma pack(@var{n})} instances and finalized by a single +@code{#pragma pack(pop)}. +@end enumerate + +Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct} +directive which lays out structures and unions subsequently defined as the +documented @code{__attribute__ ((ms_struct))}. + +@enumerate +@item @code{#pragma ms_struct on} turns on the Microsoft layout. +@item @code{#pragma ms_struct off} turns off the Microsoft layout. +@item @code{#pragma ms_struct reset} goes back to the default layout. +@end enumerate + +Most targets also support the @code{#pragma scalar_storage_order} directive +which lays out structures and unions subsequently defined as the documented +@code{__attribute__ ((scalar_storage_order))}. + +@enumerate +@item @code{#pragma scalar_storage_order big-endian} sets the storage order +of the scalar fields to big-endian. +@item @code{#pragma scalar_storage_order little-endian} sets the storage order +of the scalar fields to little-endian. +@item @code{#pragma scalar_storage_order default} goes back to the endianness +that was in effect when compilation started (see also command-line option +@option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}). +@end enumerate + +@node Weak Pragmas +@subsection Weak Pragmas + +For compatibility with SVR4, GCC supports a set of @code{#pragma} +directives for declaring symbols to be weak, and defining weak +aliases. + +@table @code +@cindex pragma, weak +@item #pragma weak @var{symbol} +This pragma declares @var{symbol} to be weak, as if the declaration +had the attribute of the same name. The pragma may appear before +or after the declaration of @var{symbol}. It is not an error for +@var{symbol} to never be defined at all. + +@item #pragma weak @var{symbol1} = @var{symbol2} +This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. +It is an error if @var{symbol2} is not defined in the current +translation unit. +@end table + +@node Diagnostic Pragmas +@subsection Diagnostic Pragmas + +GCC allows the user to selectively enable or disable certain types of +diagnostics, and change the kind of the diagnostic. For example, a +project's policy might require that all sources compile with +@option{-Werror} but certain files might have exceptions allowing +specific types of warnings. Or, a project might selectively enable +diagnostics and treat them as errors depending on which preprocessor +macros are defined. + +@table @code +@cindex pragma, diagnostic +@item #pragma GCC diagnostic @var{kind} @var{option} + +Modifies the disposition of a diagnostic. Note that not all +diagnostics are modifiable; at the moment only warnings (normally +controlled by @samp{-W@dots{}}) can be controlled, and not all of them. +Use @option{-fdiagnostics-show-option} to determine which diagnostics +are controllable and which option controls them. + +@var{kind} is @samp{error} to treat this diagnostic as an error, +@samp{warning} to treat it like a warning (even if @option{-Werror} is +in effect), or @samp{ignored} if the diagnostic is to be ignored. +@var{option} is a double quoted string that matches the command-line +option. + +@smallexample +#pragma GCC diagnostic warning "-Wformat" +#pragma GCC diagnostic error "-Wformat" +#pragma GCC diagnostic ignored "-Wformat" +@end smallexample + +Note that these pragmas override any command-line options. GCC keeps +track of the location of each pragma, and issues diagnostics according +to the state as of that point in the source file. Thus, pragmas occurring +after a line do not affect diagnostics caused by that line. + +@item #pragma GCC diagnostic push +@itemx #pragma GCC diagnostic pop + +Causes GCC to remember the state of the diagnostics as of each +@code{push}, and restore to that point at each @code{pop}. If a +@code{pop} has no matching @code{push}, the command-line options are +restored. + +@smallexample +#pragma GCC diagnostic error "-Wuninitialized" + foo(a); /* error is given for this one */ +#pragma GCC diagnostic push +#pragma GCC diagnostic ignored "-Wuninitialized" + foo(b); /* no diagnostic for this one */ +#pragma GCC diagnostic pop + foo(c); /* error is given for this one */ +#pragma GCC diagnostic pop + foo(d); /* depends on command-line options */ +@end smallexample + +@item #pragma GCC diagnostic ignored_attributes + +Similarly to @option{-Wno-attributes=}, this pragma allows users to suppress +warnings about unknown scoped attributes (in C++11 and C23). For example, +@code{#pragma GCC diagnostic ignored_attributes "vendor::attr"} disables +warning about the following declaration: + +@smallexample +[[vendor::attr]] void f(); +@end smallexample + +whereas @code{#pragma GCC diagnostic ignored_attributes "vendor::"} prevents +warning about both of these declarations: + +@smallexample +[[vendor::safe]] void f(); +[[vendor::unsafe]] void f2(); +@end smallexample + +@end table + +GCC also offers a simple mechanism for printing messages during +compilation. + +@table @code +@cindex pragma, diagnostic +@item #pragma message @var{string} + +Prints @var{string} as a compiler message on compilation. The message +is informational only, and is neither a compilation warning nor an +error. Newlines can be included in the string by using the @samp{\n} +escape sequence. + +@smallexample +#pragma message "Compiling " __FILE__ "..." +@end smallexample + +@var{string} may be parenthesized, and is printed with location +information. For example, + +@smallexample +#define DO_PRAGMA(x) _Pragma (#x) +#define TODO(x) DO_PRAGMA(message ("TODO - " #x)) + +TODO(Remember to fix this) +@end smallexample + +@noindent +prints @samp{/tmp/file.c:4: note: #pragma message: +TODO - Remember to fix this}. + +@cindex pragma, diagnostic +@item #pragma GCC error @var{message} +Generates an error message. This pragma @emph{is} considered to +indicate an error in the compilation, and it will be treated as such. + +Newlines can be included in the string by using the @samp{\n} +escape sequence. They will be displayed as newlines even if the +@option{-fmessage-length} option is set to zero. + +The error is only generated if the pragma is present in the code after +pre-processing has been completed. It does not matter however if the +code containing the pragma is unreachable: + +@smallexample +#if 0 +#pragma GCC error "this error is not seen" +#endif +void foo (void) @{ - return x == 0; + return; +#pragma GCC error "this error is seen" @} @end smallexample -Suppose the type @code{uid_t} happens to be @code{short}. ISO C does -not allow this example, because subword arguments in old-style -non-prototype definitions are promoted. Therefore in this example the -function definition's argument is really an @code{int}, which does not -match the prototype argument type of @code{short}. +@cindex pragma, diagnostic +@item #pragma GCC warning @var{message} +This is just like @samp{pragma GCC error} except that a warning +message is issued instead of an error message. Unless +@option{-Werror} is in effect, in which case this pragma will generate +an error as well. -This restriction of ISO C makes it hard to write code that is portable -to traditional C compilers, because the programmer does not know -whether the @code{uid_t} type is @code{short}, @code{int}, or -@code{long}. Therefore, in cases like these GNU C allows a prototype -to override a later old-style definition. More precisely, in GNU C, a -function prototype argument type overrides the argument type specified -by a later old-style definition if the former type is the same as the -latter type before promotion. Thus in GNU C the above example is -equivalent to the following: +@end table + +@node Visibility Pragmas +@subsection Visibility Pragmas + +@table @code +@cindex pragma, visibility +@item #pragma GCC visibility push(@var{visibility}) +@itemx #pragma GCC visibility pop + +This pragma allows the user to set the visibility for multiple +declarations without having to give each a visibility attribute +(@pxref{Function Attributes}). + +In C++, @samp{#pragma GCC visibility} affects only namespace-scope +declarations. Class members and template specializations are not +affected; if you want to override the visibility for a particular +member or instantiation, you must use an attribute. + +@end table + + +@node Push/Pop Macro Pragmas +@subsection Push/Pop Macro Pragmas + +For compatibility with Microsoft Windows compilers, GCC supports +@samp{#pragma push_macro(@var{"macro_name"})} +and @samp{#pragma pop_macro(@var{"macro_name"})}. + +@table @code +@cindex pragma, push_macro +@item #pragma push_macro(@var{"macro_name"}) +This pragma saves the value of the macro named as @var{macro_name} to +the top of the stack for this macro. + +@cindex pragma, pop_macro +@item #pragma pop_macro(@var{"macro_name"}) +This pragma sets the value of the macro named as @var{macro_name} to +the value on top of the stack for this macro. If the stack for +@var{macro_name} is empty, the value of the macro remains unchanged. +@end table + +For example: @smallexample -int isroot (uid_t); +#define X 1 +#pragma push_macro("X") +#undef X +#define X -1 +#pragma pop_macro("X") +int x [X]; +@end smallexample -int -isroot (uid_t x) +@noindent +In this example, the definition of X as 1 is saved by @code{#pragma +push_macro} and restored by @code{#pragma pop_macro}. + +@node Function Specific Option Pragmas +@subsection Function Specific Option Pragmas + +@table @code +@cindex pragma GCC target +@item #pragma GCC target (@var{string}, @dots{}) + +This pragma allows you to set target-specific options for functions +defined later in the source file. One or more strings can be +specified. Each function that is defined after this point is treated +as if it had been declared with one @code{target(}@var{string}@code{)} +attribute for each @var{string} argument. The parentheses around +the strings in the pragma are optional. @xref{Function Attributes}, +for more information about the @code{target} attribute and the attribute +syntax. + +The @code{#pragma GCC target} pragma is presently implemented for +x86, ARM, AArch64, PowerPC, and S/390 targets only. + +@cindex pragma GCC optimize +@item #pragma GCC optimize (@var{string}, @dots{}) + +This pragma allows you to set global optimization options for functions +defined later in the source file. One or more strings can be +specified. Each function that is defined after this point is treated +as if it had been declared with one @code{optimize(}@var{string}@code{)} +attribute for each @var{string} argument. The parentheses around +the strings in the pragma are optional. @xref{Function Attributes}, +for more information about the @code{optimize} attribute and the attribute +syntax. + +@cindex pragma GCC push_options +@cindex pragma GCC pop_options +@item #pragma GCC push_options +@itemx #pragma GCC pop_options + +These pragmas maintain a stack of the current target and optimization +options. It is intended for include files where you temporarily want +to switch to using a different @samp{#pragma GCC target} or +@samp{#pragma GCC optimize} and then to pop back to the previous +options. + +@cindex pragma GCC reset_options +@item #pragma GCC reset_options + +This pragma clears the current @code{#pragma GCC target} and +@code{#pragma GCC optimize} to use the default switches as specified +on the command line. + +@end table + +@node Loop-Specific Pragmas +@subsection Loop-Specific Pragmas + +@table @code +@cindex pragma GCC ivdep +@item #pragma GCC ivdep + +With this pragma, the programmer asserts that there are no loop-carried +dependencies which would prevent consecutive iterations of +the following loop from executing concurrently with SIMD +(single instruction multiple data) instructions. + +For example, the compiler can only unconditionally vectorize the following +loop with the pragma: + +@smallexample +void foo (int n, int *a, int *b, int *c) @{ - return x == 0; + int i, j; +#pragma GCC ivdep + for (i = 0; i < n; ++i) + a[i] = b[i] + c[i]; @} @end smallexample @noindent -GNU C++ does not support old-style function definitions, so this -extension is irrelevant. +In this example, using the @code{restrict} qualifier had the same +effect. In the following example, that would not be possible. Assume +@math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows +that it can unconditionally vectorize the following loop: -@node C++ Comments -@section C++ Style Comments -@cindex @code{//} -@cindex C++ comments -@cindex comments, C++ style +@smallexample +void ignore_vec_dep (int *a, int k, int c, int m) +@{ +#pragma GCC ivdep + for (int i = 0; i < m; i++) + a[i] = a[i + k] * c; +@} +@end smallexample -In GNU C, you may use C++ style comments, which start with @samp{//} and -continue until the end of the line. Many other C implementations allow -such comments, and they are included in the 1999 C standard. However, -C++ style comments are not recognized if you specify an @option{-std} -option specifying a version of ISO C before C99, or @option{-ansi} -(equivalent to @option{-std=c90}). +@cindex pragma GCC novector +@item #pragma GCC novector -@node Dollar Signs -@section Dollar Signs in Identifier Names -@cindex $ -@cindex dollar signs in identifier names -@cindex identifier names, dollar signs in +With this pragma, the programmer asserts that the following loop should be +prevented from executing concurrently with SIMD (single instruction multiple +data) instructions. -In GNU C, you may normally use dollar signs in identifier names. -This is because many traditional C implementations allow such identifiers. -However, dollar signs in identifiers are not supported on a few target -machines, typically because the target assembler does not allow them. +For example, the compiler cannot vectorize the following loop with the pragma: -@node Character Escapes -@section The Character @key{ESC} in Constants +@smallexample +void foo (int n, int *a, int *b, int *c) +@{ + int i, j; +#pragma GCC novector + for (i = 0; i < n; ++i) + a[i] = b[i] + c[i]; +@} +@end smallexample -You can use the sequence @samp{\e} in a string or character constant to -stand for the ASCII character @key{ESC}. +@cindex pragma GCC unroll @var{n} +@item #pragma GCC unroll @var{n} -@node Alignment -@section Determining the Alignment of Functions, Types or Variables -@cindex alignment -@cindex type alignment -@cindex variable alignment +You can use this pragma to control how many times a loop should be unrolled. +It must be placed immediately before a @code{for}, @code{while} or @code{do} +loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows. +@var{n} is an integer constant expression specifying the unrolling factor. +The values of @math{0} and @math{1} block any unrolling of the loop. -The keyword @code{__alignof__} determines the alignment requirement of -a function, object, or a type, or the minimum alignment usually required -by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}. +@end table -For example, if the target machine requires a @code{double} value to be -aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. -This is true on many RISC machines. On more traditional machine -designs, @code{__alignof__ (double)} is 4 or even 2. +@node Thread-Local +@section Thread-Local Storage +@cindex Thread-Local Storage +@cindex @acronym{TLS} +@cindex @code{__thread} -Some machines never actually require alignment; they allow references to any -data type even at an odd address. For these machines, @code{__alignof__} -reports the smallest alignment that GCC gives the data type, usually as -mandated by the target ABI. +Thread-local storage (@acronym{TLS}) is a mechanism by which variables +are allocated such that there is one instance of the variable per extant +thread. The runtime model GCC uses to implement this originates +in the IA-64 processor-specific ABI, but has since been migrated +to other processors as well. It requires significant support from +the linker (@command{ld}), dynamic linker (@command{ld.so}), and +system libraries (@file{libc.so} and @file{libpthread.so}), so it +is not available everywhere. -If the operand of @code{__alignof__} is an lvalue rather than a type, -its value is the required alignment for its type, taking into account -any minimum alignment specified by attribute @code{aligned} -(@pxref{Common Variable Attributes}). For example, after this -declaration: +At the user level, the extension is visible with a new storage +class keyword: @code{__thread}. For example: @smallexample -struct foo @{ int x; char y; @} foo1; +__thread int i; +extern __thread struct state s; +static __thread char *p; @end smallexample -@noindent -the value of @code{__alignof__ (foo1.y)} is 1, even though its actual -alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. -It is an error to ask for the alignment of an incomplete type other -than @code{void}. +The @code{__thread} specifier may be used alone, with the @code{extern} +or @code{static} specifiers, but with no other storage class specifier. +When used with @code{extern} or @code{static}, @code{__thread} must appear +immediately after the other storage class specifier. -If the operand of the @code{__alignof__} expression is a function, -the expression evaluates to the alignment of the function which may -be specified by attribute @code{aligned} (@pxref{Common Function Attributes}). +The @code{__thread} specifier may be applied to any global, file-scoped +static, function-scoped static, or static data member of a class. It may +not be applied to block-scoped automatic or non-static data member. + +When the address-of operator is applied to a thread-local variable, it is +evaluated at run time and returns the address of the current thread's +instance of that variable. An address so obtained may be used by any +thread. When a thread terminates, any pointers to thread-local variables +in that thread become invalid. + +No static initialization may refer to the address of a thread-local variable. + +In C++, if an initializer is present for a thread-local variable, it must +be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ +standard. + +See @uref{https://www.akkadia.org/drepper/tls.pdf, +ELF Handling For Thread-Local Storage} for a detailed explanation of +the four thread-local storage addressing models, and how the runtime +is expected to function. + +@menu +* C99 Thread-Local Edits:: +* C++98 Thread-Local Edits:: +@end menu + +@node C99 Thread-Local Edits +@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage + +The following are a set of changes to ISO/IEC 9899:1999 (aka C99) +that document the exact semantics of the language extension. + +@itemize @bullet +@item +@cite{5.1.2 Execution environments} + +Add new text after paragraph 1 + +@quotation +Within either execution environment, a @dfn{thread} is a flow of +control within a program. It is implementation defined whether +or not there may be more than one thread associated with a program. +It is implementation defined how threads beyond the first are +created, the name and type of the function called at thread +startup, and how threads may be terminated. However, objects +with thread storage duration shall be initialized before thread +startup. +@end quotation + +@item +@cite{6.2.4 Storage durations of objects} + +Add new text before paragraph 3 + +@quotation +An object whose identifier is declared with the storage-class +specifier @w{@code{__thread}} has @dfn{thread storage duration}. +Its lifetime is the entire execution of the thread, and its +stored value is initialized only once, prior to thread startup. +@end quotation + +@item +@cite{6.4.1 Keywords} + +Add @code{__thread}. + +@item +@cite{6.7.1 Storage-class specifiers} + +Add @code{__thread} to the list of storage class specifiers in +paragraph 1. + +Change paragraph 2 to + +@quotation +With the exception of @code{__thread}, at most one storage-class +specifier may be given [@dots{}]. The @code{__thread} specifier may +be used alone, or immediately following @code{extern} or +@code{static}. +@end quotation + +Add new text after paragraph 6 + +@quotation +The declaration of an identifier for a variable that has +block scope that specifies @code{__thread} shall also +specify either @code{extern} or @code{static}. + +The @code{__thread} specifier shall be used only with +variables. +@end quotation +@end itemize + +@node C++98 Thread-Local Edits +@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage + +The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) +that document the exact semantics of the language extension. + +@itemize @bullet +@item +@b{[intro.execution]} + +New text after paragraph 4 + +@quotation +A @dfn{thread} is a flow of control within the abstract machine. +It is implementation defined whether or not there may be more than +one thread. +@end quotation + +New text after paragraph 7 + +@quotation +It is unspecified whether additional action must be taken to +ensure when and whether side effects are visible to other threads. +@end quotation + +@item +@b{[lex.key]} + +Add @code{__thread}. + +@item +@b{[basic.start.main]} + +Add after paragraph 5 + +@quotation +The thread that begins execution at the @code{main} function is called +the @dfn{main thread}. It is implementation defined how functions +beginning threads other than the main thread are designated or typed. +A function so designated, as well as the @code{main} function, is called +a @dfn{thread startup function}. It is implementation defined what +happens if a thread startup function returns. It is implementation +defined what happens to other threads when any thread calls @code{exit}. +@end quotation + +@item +@b{[basic.start.init]} + +Add after paragraph 4 + +@quotation +The storage for an object of thread storage duration shall be +statically initialized before the first statement of the thread startup +function. An object of thread storage duration shall not require +dynamic initialization. +@end quotation + +@item +@b{[basic.start.term]} + +Add after paragraph 3 + +@quotation +The type of an object with thread storage duration shall not have a +non-trivial destructor, nor shall it be an array type whose elements +(directly or indirectly) have non-trivial destructors. +@end quotation + +@item +@b{[basic.stc]} + +Add ``thread storage duration'' to the list in paragraph 1. + +Change paragraph 2 + +@quotation +Thread, static, and automatic storage durations are associated with +objects introduced by declarations [@dots{}]. +@end quotation + +Add @code{__thread} to the list of specifiers in paragraph 3. + +@item +@b{[basic.stc.thread]} + +New section before @b{[basic.stc.static]} + +@quotation +The keyword @code{__thread} applied to a non-local object gives the +object thread storage duration. + +A local variable or class data member declared both @code{static} +and @code{__thread} gives the variable or member thread storage +duration. +@end quotation + +@item +@b{[basic.stc.static]} + +Change paragraph 1 + +@quotation +All objects that have neither thread storage duration, dynamic +storage duration nor are local [@dots{}]. +@end quotation + +@item +@b{[dcl.stc]} + +Add @code{__thread} to the list in paragraph 1. + +Change paragraph 1 + +@quotation +With the exception of @code{__thread}, at most one +@var{storage-class-specifier} shall appear in a given +@var{decl-specifier-seq}. The @code{__thread} specifier may +be used alone, or immediately following the @code{extern} or +@code{static} specifiers. [@dots{}] +@end quotation + +Add after paragraph 5 + +@quotation +The @code{__thread} specifier can be applied only to the names of objects +and to anonymous unions. +@end quotation + +@item +@b{[class.mem]} + +Add after paragraph 6 + +@quotation +Non-@code{static} members shall not be @code{__thread}. +@end quotation +@end itemize + +@node OpenMP +@section OpenMP +@cindex OpenMP extension support + +OpenMP (Open Multi-Processing) is an application programming +interface (API) that supports multi-platform shared memory +multiprocessing programming in C/C++ and Fortran on many +architectures, including Unix and Microsoft Windows platforms. +It consists of a set of compiler directives, library routines, +and environment variables that influence run-time behavior. + +GCC implements all of the @uref{https://www.openmp.org/specifications/, +OpenMP Application Program Interface v4.5}, and many features from later +versions of the OpenMP specification. +@xref{OpenMP Implementation Status,,,libgomp, +GNU Offloading and Multi Processing Runtime Library}, +for more details about currently supported OpenMP features. + +To enable the processing of OpenMP directives @samp{#pragma omp}, +@samp{[[omp::directive(...)]]}, @samp{[[omp::decl(...)]]}, +and @samp{[[omp::sequence(...)]]} in C and C++, +GCC needs to be invoked with the @option{-fopenmp} option. +This option also arranges for automatic linking of the OpenMP +runtime library. +@xref{,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. + +@xref{OpenMP and OpenACC Options}, for additional options useful with +@option{-fopenmp}. + +@node OpenACC +@section OpenACC +@cindex OpenACC extension support + +OpenACC is an application programming interface (API) that supports +offloading of code to accelerator devices. It consists of a set of +compiler directives, library routines, and environment variables that +influence run-time behavior. + +GCC strives to be compatible with the +@uref{https://www.openacc.org/, OpenACC Application Programming +Interface v2.6}. + +To enable the processing of OpenACC directives @samp{#pragma acc} +in C and C++, GCC needs to be invoked with the @option{-fopenacc} option. +This option also arranges for automatic linking of the OpenACC runtime +library. +@xref{,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. + +@xref{OpenMP and OpenACC Options}, for additional options useful with +@option{-fopenacc}. @node Inline @section An Inline Function is As Fast As a Macro @@ -10804,40 +10791,6 @@ The definition in the header file causes most calls to the function to be inlined. If any uses of the function remain, they refer to the single copy in the library. -@node Const and Volatile Functions -@section Const and Volatile Functions -@cindex @code{const} applied to function -@cindex @code{volatile} applied to function - -The C standard explicitly leaves the behavior of the @code{const} and -@code{volatile} type qualifiers applied to functions undefined; these -constructs can only arise through the use of @code{typedef}. As an extension, -GCC defines this use of the @code{const} qualifier to have the same meaning -as the GCC @code{const} function attribute, and the @code{volatile} qualifier -to be equivalent to the @code{noreturn} attribute. -@xref{Common Function Attributes}, for more information. - -As examples of this usage, - -@smallexample - -/* @r{Equivalent to:} - void fatal () __attribute__ ((noreturn)); */ -typedef void voidfn (); -volatile voidfn fatal; - -/* @r{Equivalent to:} - extern int square (int) __attribute__ ((const)); */ -typedef int intfn (int); -extern const intfn square; -@end smallexample - -In general, using function attributes instead is preferred, since the -attributes make both the intent of the code and its reliance on a GNU -extension explicit. Additionally, using @code{const} and -@code{volatile} in this way is specific to GNU C and does not work in -GNU C++. - @node Volatiles @section When is a Volatile Object Accessed? @cindex accessing volatiles @@ -13047,8 +13000,1052 @@ This size is also used for inlining decisions. If you use @code{asm inline} instead of just @code{asm}, then for inlining purposes the size of the asm is taken as the minimum size, ignoring how many instructions GCC thinks it is. +@node Syntax Extensions +@section Other Extensions to C Syntax + +GNU C has traditionally supported numerous extensions to standard C +syntax. Some of these features were originally intended for +compatibility with other compilers or to ease traditional C +compatibility, some have been adopted into subsequent versions of the +C and/or C++ standards, while others remain specific to GNU C. + +@menu +* Statement Exprs:: Putting statements and declarations inside expressions. +* Local Labels:: Labels local to a block. +* Labels as Values:: Getting pointers to labels, and computed gotos. +* Nested Functions:: Nested functions in GNU C. +* Typeof:: @code{typeof}: referring to the type of an expression. +* Offsetof:: Special syntax for @code{offsetof}. +* Alignment:: Determining the alignment of a function, type or variable. +* Enum Extensions:: Forward declarations and specifying the underlying type. +* Boolean Type:: Support for the @code{_Bool} keyword. +* Variadic Macros:: Macros with a variable number of arguments. +* Conditionals:: Omitting the middle operand of a @samp{?:} expression. +* Case Ranges:: `case 1 ... 9' and such. +* Mixed Labels and Declarations:: Mixing declarations, labels and code. +* C++ Comments:: C++ comments are recognized. +* Escaped Newlines:: Slightly looser rules for escaped newlines. +* Hex Floats:: Hexadecimal floating-point constants. +* Binary constants:: Binary constants using the @samp{0b} prefix. +* Dollar Signs:: Dollar sign is allowed in identifiers. +* Character Escapes:: @samp{\e} stands for the character @key{ESC}. +* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. +* Function Names:: Printable strings which are the name of the current + function. +@end menu + +@node Statement Exprs +@subsection Statements and Declarations in Expressions +@cindex statements inside expressions +@cindex declarations inside expressions +@cindex expressions containing statements +@cindex macros, statements in expressions + +@c the above section title wrapped and causes an underfull hbox.. i +@c changed it from "within" to "in". --mew 4feb93 +A compound statement enclosed in parentheses may appear as an expression +in GNU C@. This allows you to use loops, switches, and local variables +within an expression. + +Recall that a compound statement is a sequence of statements surrounded +by braces; in this construct, parentheses go around the braces. For +example: + +@smallexample +(@{ int y = foo (); int z; + if (y > 0) z = y; + else z = - y; + z; @}) +@end smallexample + +@noindent +is a valid (though slightly more complex than necessary) expression +for the absolute value of @code{foo ()}. + +The last thing in the compound statement should be an expression +followed by a semicolon; the value of this subexpression serves as the +value of the entire construct. (If you use some other kind of statement +last within the braces, the construct has type @code{void}, and thus +effectively no value.) + +This feature is especially useful in making macro definitions ``safe'' (so +that they evaluate each operand exactly once). For example, the +``maximum'' function is commonly defined as a macro in standard C as +follows: + +@smallexample +#define max(a,b) ((a) > (b) ? (a) : (b)) +@end smallexample + +@noindent +@cindex side effects, macro argument +But this definition computes either @var{a} or @var{b} twice, with bad +results if the operand has side effects. In GNU C, if you know the +type of the operands (here taken as @code{int}), you can avoid this +problem by defining the macro as follows: + +@smallexample +#define maxint(a,b) \ + (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) +@end smallexample + +Note that introducing variable declarations (as we do in @code{maxint}) can +cause variable shadowing, so while this example using the @code{max} macro +produces correct results: +@smallexample +int _a = 1, _b = 2, c; +c = max (_a, _b); +@end smallexample +@noindent +this example using maxint will not: +@smallexample +int _a = 1, _b = 2, c; +c = maxint (_a, _b); +@end smallexample + +This problem may for instance occur when we use this pattern recursively, like +so: + +@smallexample +#define maxint3(a, b, c) \ + (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @}) +@end smallexample + +Embedded statements are not allowed in constant expressions, such as +the value of an enumeration constant, the width of a bit-field, or +the initial value of a static variable. + +If you don't know the type of the operand, you can still do this, but you +must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}). + +In G++, the result value of a statement expression undergoes array and +function pointer decay, and is returned by value to the enclosing +expression. For instance, if @code{A} is a class, then + +@smallexample + A a; + + (@{a;@}).Foo () +@end smallexample + +@noindent +constructs a temporary @code{A} object to hold the result of the +statement expression, and that is used to invoke @code{Foo}. +Therefore the @code{this} pointer observed by @code{Foo} is not the +address of @code{a}. + +In a statement expression, any temporaries created within a statement +are destroyed at that statement's end. This makes statement +expressions inside macros slightly different from function calls. In +the latter case temporaries introduced during argument evaluation are +destroyed at the end of the statement that includes the function +call. In the statement expression case they are destroyed during +the statement expression. For instance, + +@smallexample +#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) +template<typename T> T function(T a) @{ T b = a; return b + 3; @} + +void foo () +@{ + macro (X ()); + function (X ()); +@} +@end smallexample + +@noindent +has different places where temporaries are destroyed. For the +@code{macro} case, the temporary @code{X} is destroyed just after +the initialization of @code{b}. In the @code{function} case that +temporary is destroyed when the function returns. + +These considerations mean that it is probably a bad idea to use +statement expressions of this form in header files that are designed to +work with C++. (Note that some versions of the GNU C Library contained +header files using statement expressions that lead to precisely this +bug.) + +Jumping into a statement expression with @code{goto} or using a +@code{switch} statement outside the statement expression with a +@code{case} or @code{default} label inside the statement expression is +not permitted. Jumping into a statement expression with a computed +@code{goto} (@pxref{Labels as Values}) has undefined behavior. +Jumping out of a statement expression is permitted, but if the +statement expression is part of a larger expression then it is +unspecified which other subexpressions of that expression have been +evaluated except where the language definition requires certain +subexpressions to be evaluated before or after the statement +expression. A @code{break} or @code{continue} statement inside of +a statement expression used in @code{while}, @code{do} or @code{for} +loop or @code{switch} statement condition +or @code{for} statement init or increment expressions jumps to an +outer loop or @code{switch} statement if any (otherwise it is an error), +rather than to the loop or @code{switch} statement in whose condition +or init or increment expression it appears. +In any case, as with a function call, the evaluation of a +statement expression is not interleaved with the evaluation of other +parts of the containing expression. For example, + +@smallexample + foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); +@end smallexample + +@noindent +calls @code{foo} and @code{bar1} and does not call @code{baz} but +may or may not call @code{bar2}. If @code{bar2} is called, it is +called after @code{foo} and before @code{bar1}. + +@node Local Labels +@subsection Locally Declared Labels +@cindex local labels +@cindex macros, local labels + +GCC allows you to declare @dfn{local labels} in any nested block +scope. A local label is just like an ordinary label, but you can +only reference it (with a @code{goto} statement, or by taking its +address) within the block in which it is declared. + +A local label declaration looks like this: + +@smallexample +__label__ @var{label}; +@end smallexample + +@noindent +or + +@smallexample +__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; +@end smallexample + +Local label declarations must come at the beginning of the block, +before any ordinary declarations or statements. + +The label declaration defines the label @emph{name}, but does not define +the label itself. You must do this in the usual way, with +@code{@var{label}:}, within the statements of the statement expression. + +The local label feature is useful for complex macros. If a macro +contains nested loops, a @code{goto} can be useful for breaking out of +them. However, an ordinary label whose scope is the whole function +cannot be used: if the macro can be expanded several times in one +function, the label is multiply defined in that function. A +local label avoids this problem. For example: + +@smallexample +#define SEARCH(value, array, target) \ +do @{ \ + __label__ found; \ + typeof (target) _SEARCH_target = (target); \ + typeof (*(array)) *_SEARCH_array = (array); \ + int i, j; \ + int value; \ + for (i = 0; i < max; i++) \ + for (j = 0; j < max; j++) \ + if (_SEARCH_array[i][j] == _SEARCH_target) \ + @{ (value) = i; goto found; @} \ + (value) = -1; \ + found:; \ +@} while (0) +@end smallexample + +This could also be written using a statement expression: + +@smallexample +#define SEARCH(array, target) \ +(@{ \ + __label__ found; \ + typeof (target) _SEARCH_target = (target); \ + typeof (*(array)) *_SEARCH_array = (array); \ + int i, j; \ + int value; \ + for (i = 0; i < max; i++) \ + for (j = 0; j < max; j++) \ + if (_SEARCH_array[i][j] == _SEARCH_target) \ + @{ value = i; goto found; @} \ + value = -1; \ + found: \ + value; \ +@}) +@end smallexample + +Local label declarations also make the labels they declare visible to +nested functions, if there are any. @xref{Nested Functions}, for details. + +@node Labels as Values +@subsection Labels as Values +@cindex labels as values +@cindex computed gotos +@cindex goto with computed label +@cindex address of a label + +You can get the address of a label defined in the current function +(or a containing function) with the unary operator @samp{&&}. The +value has type @code{void *}. This value is a constant and can be used +wherever a constant of that type is valid. For example: + +@smallexample +void *ptr; +/* @r{@dots{}} */ +ptr = &&foo; +@end smallexample + +To use these values, you need to be able to jump to one. This is done +with the computed goto statement@footnote{The analogous feature in +Fortran is called an assigned goto, but that name seems inappropriate in +C, where one can do more than simply store label addresses in label +variables.}, @code{goto *@var{exp};}. For example, + +@smallexample +goto *ptr; +@end smallexample + +@noindent +Any expression of type @code{void *} is allowed. + +One way of using these constants is in initializing a static array that +serves as a jump table: + +@smallexample +static void *array[] = @{ &&foo, &&bar, &&hack @}; +@end smallexample + +@noindent +Then you can select a label with indexing, like this: + +@smallexample +goto *array[i]; +@end smallexample + +@noindent +Note that this does not check whether the subscript is in bounds---array +indexing in C never does that. + +Such an array of label values serves a purpose much like that of the +@code{switch} statement. The @code{switch} statement is cleaner, so +use that rather than an array unless the problem does not fit a +@code{switch} statement very well. + +Another use of label values is in an interpreter for threaded code. +The labels within the interpreter function can be stored in the +threaded code for super-fast dispatching. + +You may not use this mechanism to jump to code in a different function. +If you do that, totally unpredictable things happen. The best way to +avoid this is to store the label address only in automatic variables and +never pass it as an argument. + +An alternate way to write the above example is + +@smallexample +static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, + &&hack - &&foo @}; +goto *(&&foo + array[i]); +@end smallexample + +@noindent +This is more friendly to code living in shared libraries, as it reduces +the number of dynamic relocations that are needed, and by consequence, +allows the data to be read-only. +This alternative with label differences is not supported for the AVR target, +please use the first approach for AVR programs. + +The @code{&&foo} expressions for the same label might have different +values if the containing function is inlined or cloned. If a program +relies on them being always the same, +@code{__attribute__((__noinline__,__noclone__))} should be used to +prevent inlining and cloning. If @code{&&foo} is used in a static +variable initializer, inlining and cloning is forbidden. + +Unlike a normal goto, in GNU C++ a computed goto will not call +destructors for objects that go out of scope. + +@node Nested Functions +@subsection Nested Functions +@cindex nested functions +@cindex downward funargs +@cindex thunks + +A @dfn{nested function} is a function defined inside another function. +Nested functions are supported as an extension in GNU C, but are not +supported by GNU C++. + +The nested function's name is local to the block where it is defined. +For example, here we define a nested function named @code{square}, and +call it twice: + +@smallexample +@group +foo (double a, double b) +@{ + double square (double z) @{ return z * z; @} + + return square (a) + square (b); +@} +@end group +@end smallexample + +The nested function can access all the variables of the containing +function that are visible at the point of its definition. This is +called @dfn{lexical scoping}. For example, here we show a nested +function which uses an inherited variable named @code{offset}: + +@smallexample +@group +bar (int *array, int offset, int size) +@{ + int access (int *array, int index) + @{ return array[index + offset]; @} + int i; + /* @r{@dots{}} */ + for (i = 0; i < size; i++) + /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ +@} +@end group +@end smallexample + +Nested function definitions are permitted within functions in the places +where variable definitions are allowed; that is, in any block, mixed +with the other declarations and statements in the block. + +It is possible to call the nested function from outside the scope of its +name by storing its address or passing the address to another function: + +@smallexample +hack (int *array, int size) +@{ + void store (int index, int value) + @{ array[index] = value; @} + + intermediate (store, size); +@} +@end smallexample + +Here, the function @code{intermediate} receives the address of +@code{store} as an argument. If @code{intermediate} calls @code{store}, +the arguments given to @code{store} are used to store into @code{array}. +But this technique works only so long as the containing function +(@code{hack}, in this example) does not exit. + +If you try to call the nested function through its address after the +containing function exits, all hell breaks loose. If you try +to call it after a containing scope level exits, and if it refers +to some of the variables that are no longer in scope, you may be lucky, +but it's not wise to take the risk. If, however, the nested function +does not refer to anything that has gone out of scope, you should be +safe. + +GCC implements taking the address of a nested function using a technique +called @dfn{trampolines}. This technique was described in +@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX +C++ Conference Proceedings, October 17-21, 1988). + +A nested function can jump to a label inherited from a containing +function, provided the label is explicitly declared in the containing +function (@pxref{Local Labels}). Such a jump returns instantly to the +containing function, exiting the nested function that did the +@code{goto} and any intermediate functions as well. Here is an example: + +@smallexample +@group +bar (int *array, int offset, int size) +@{ + __label__ failure; + int access (int *array, int index) + @{ + if (index > size) + goto failure; + return array[index + offset]; + @} + int i; + /* @r{@dots{}} */ + for (i = 0; i < size; i++) + /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ + /* @r{@dots{}} */ + return 0; + + /* @r{Control comes here from @code{access} + if it detects an error.} */ + failure: + return -1; +@} +@end group +@end smallexample + +A nested function always has no linkage. Declaring one with +@code{extern} or @code{static} is erroneous. If you need to declare the nested function +before its definition, use @code{auto} (which is otherwise meaningless +for function declarations). + +@smallexample +bar (int *array, int offset, int size) +@{ + __label__ failure; + auto int access (int *, int); + /* @r{@dots{}} */ + int access (int *array, int index) + @{ + if (index > size) + goto failure; + return array[index + offset]; + @} + /* @r{@dots{}} */ +@} +@end smallexample + +@node Typeof +@subsection Referring to a Type with @code{typeof} +@findex typeof +@findex sizeof +@cindex macros, types of arguments + +Another way to refer to the type of an expression is with @code{typeof}. +The syntax of using of this keyword looks like @code{sizeof}, but the +construct acts semantically like a type name defined with @code{typedef}. + +There are two ways of writing the argument to @code{typeof}: with an +expression or with a type. Here is an example with an expression: + +@smallexample +typeof (x[0](1)) +@end smallexample + +@noindent +This assumes that @code{x} is an array of pointers to functions; +the type described is that of the values of the functions. + +Here is an example with a typename as the argument: + +@smallexample +typeof (int *) +@end smallexample + +@noindent +Here the type described is that of pointers to @code{int}. + +If you are writing a header file that must work when included in ISO C +programs, write @code{__typeof__} instead of @code{typeof}. +@xref{Alternate Keywords}. + +A @code{typeof} construct can be used anywhere a typedef name can be +used. For example, you can use it in a declaration, in a cast, or inside +of @code{sizeof} or @code{typeof}. + +The operand of @code{typeof} is evaluated for its side effects if and +only if it is an expression of variably modified type or the name of +such a type. + +@code{typeof} is often useful in conjunction with +statement expressions (@pxref{Statement Exprs}). +Here is how the two together can +be used to define a safe ``maximum'' macro which operates on any +arithmetic type and evaluates each of its arguments exactly once: + +@smallexample +#define max(a,b) \ + (@{ typeof (a) _a = (a); \ + typeof (b) _b = (b); \ + _a > _b ? _a : _b; @}) +@end smallexample + +@cindex underscores in variables in macros +@cindex @samp{_} in variables in macros +@cindex local variables in macros +@cindex variables, local, in macros +@cindex macros, local variables in + +The reason for using names that start with underscores for the local +variables is to avoid conflicts with variable names that occur within the +expressions that are substituted for @code{a} and @code{b}. Eventually we +hope to design a new form of declaration syntax that allows you to declare +variables whose scopes start only after their initializers; this will be a +more reliable way to prevent such conflicts. + +@noindent +Some more examples of the use of @code{typeof}: + +@itemize @bullet +@item +This declares @code{y} with the type of what @code{x} points to. + +@smallexample +typeof (*x) y; +@end smallexample + +@item +This declares @code{y} as an array of such values. + +@smallexample +typeof (*x) y[4]; +@end smallexample + +@item +This declares @code{y} as an array of pointers to characters: + +@smallexample +typeof (typeof (char *)[4]) y; +@end smallexample + +@noindent +It is equivalent to the following traditional C declaration: + +@smallexample +char *y[4]; +@end smallexample + +To see the meaning of the declaration using @code{typeof}, and why it +might be a useful way to write, rewrite it with these macros: + +@smallexample +#define pointer(T) typeof(T *) +#define array(T, N) typeof(T [N]) +@end smallexample + +@noindent +Now the declaration can be rewritten this way: + +@smallexample +array (pointer (char), 4) y; +@end smallexample + +@noindent +Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 +pointers to @code{char}. +@end itemize + +The ISO C23 operator @code{typeof_unqual} is available in ISO C23 mode +and its result is the non-atomic unqualified version of what @code{typeof} +operator returns. Alternate spelling @code{__typeof_unqual__} is +available in all C modes and provides non-atomic unqualified version of +what @code{__typeof__} operator returns. +@xref{Alternate Keywords}. + +@cindex @code{__auto_type} in GNU C +In GNU C, but not GNU C++, you may also declare the type of a variable +as @code{__auto_type}. In that case, the declaration must declare +only one variable, whose declarator must just be an identifier, the +declaration must be initialized, and the type of the variable is +determined by the initializer; the name of the variable is not in +scope until after the initializer. (In C++, you should use C++11 +@code{auto} for this purpose.) Using @code{__auto_type}, the +``maximum'' macro above could be written as: + +@smallexample +#define max(a,b) \ + (@{ __auto_type _a = (a); \ + __auto_type _b = (b); \ + _a > _b ? _a : _b; @}) +@end smallexample + +Using @code{__auto_type} instead of @code{typeof} has two advantages: + +@itemize @bullet +@item Each argument to the macro appears only once in the expansion of +the macro. This prevents the size of the macro expansion growing +exponentially when calls to such macros are nested inside arguments of +such macros. + +@item If the argument to the macro has variably modified type, it is +evaluated only once when using @code{__auto_type}, but twice if +@code{typeof} is used. +@end itemize + +@node Offsetof +@subsection Support for @code{offsetof} +@findex __builtin_offsetof + +GCC implements for both C and C++ a syntactic extension to implement +the @code{offsetof} macro. + +@smallexample +primary: + "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" + +offsetof_member_designator: + @code{identifier} + | offsetof_member_designator "." @code{identifier} + | offsetof_member_designator "[" @code{expr} "]" +@end smallexample + +This extension is sufficient such that + +@smallexample +#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) +@end smallexample + +@noindent +is a suitable definition of the @code{offsetof} macro. In C++, @var{type} +may be dependent. In either case, @var{member} may consist of a single +identifier, or a sequence of member accesses and array references. + +@node Alignment +@subsection Determining the Alignment of Functions, Types or Variables +@cindex alignment +@cindex type alignment +@cindex variable alignment + +The keyword @code{__alignof__} determines the alignment requirement of +a function, object, or a type, or the minimum alignment usually required +by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}. + +For example, if the target machine requires a @code{double} value to be +aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. +This is true on many RISC machines. On more traditional machine +designs, @code{__alignof__ (double)} is 4 or even 2. + +Some machines never actually require alignment; they allow references to any +data type even at an odd address. For these machines, @code{__alignof__} +reports the smallest alignment that GCC gives the data type, usually as +mandated by the target ABI. + +If the operand of @code{__alignof__} is an lvalue rather than a type, +its value is the required alignment for its type, taking into account +any minimum alignment specified by attribute @code{aligned} +(@pxref{Common Variable Attributes}). For example, after this +declaration: + +@smallexample +struct foo @{ int x; char y; @} foo1; +@end smallexample + +@noindent +the value of @code{__alignof__ (foo1.y)} is 1, even though its actual +alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. +It is an error to ask for the alignment of an incomplete type other +than @code{void}. + +If the operand of the @code{__alignof__} expression is a function, +the expression evaluates to the alignment of the function which may +be specified by attribute @code{aligned} (@pxref{Common Function Attributes}). + +@node Enum Extensions +@subsection Extensions to @code{enum} Type Declarations +@anchor{Incomplete Enums} +@cindex @code{enum} extensions +@cindex base type of an @code{enum} +@cindex underlying type of an @code{enum} +@cindex forward declaration of an @code{enum} +@cindex opaque @code{enum} types +@cindex incomplete @code{enum} types + +The C23 and C++11 standards added new syntax to specify the underlying +type of an @code{enum} type. For example, + +@smallexample +enum pet : unsigned char @{ CAT, DOG, ROCK @}; +@end smallexample + +In GCC, this feature is supported as an extension in all older +dialects of C and C++ as well. For C++ dialects before C++11, use +@option{-Wno-c++11-extensions} to silence the associated warnings. + +You can also forward-declare an @code{enum} type, without specifying +its possible values. The enumerators are supplied in a later +redeclaration of the type, which must match the underlying type of the +first declaration. + +@smallexample +enum pet : unsigned char; +static enum pet my_pet; +... +enum pet : unsigned char @{ CAT, DOG, ROCK @}; +@end smallexample + +Forward declaration of @code{enum} types with an explicit underlying +type is also a feature of C++11 that is supported as an extension by +GCC for all C dialects. However, it's not available in C++ dialects +prior to C++11. + +The C++ standard refers to a forward declaration of an @code{enum} +with an explicit underlying type as an @dfn{opaque type}. It is not +considered an incomplete type, since its size is known. That means +you can declare variables or allocate storage using the type before +the redeclaration, not just use pointers of that type. + +GCC has also traditionally supported forward declarations of +@code{enum} types that don't include an explicit underlying type +specification. This results in an incomplete type, much like what you +get if you write @code{struct foo} without describing the elements. +You cannot allocate variables or storage using the type while it is +incomplete. However, you can work with pointers to that type. + +Forward-declaring an incomplete enum type without an explicit +underlying type is supported as an extension in all GNU C dialects, +but is not supported at all in GNU C++. + +@node Boolean Type +@subsection Support for the @code{_Bool} Type +@cindex boolean type +@cindex @code{_Bool} keyword + +The C99 standard added @code{_Bool} as a C language keyword naming the +boolean type. As an extension, GNU C also recognizes @code{_Bool} in +C90 mode as well as with @option{-std=c99} and later. + +GNU C++ does not support the @code{_Bool} keyword. + +@node Variadic Macros +@subsection Macros with a Variable Number of Arguments. +@cindex variable number of arguments +@cindex macro with variable arguments +@cindex rest argument (in macro) +@cindex variadic macros + +In the ISO C standard of 1999, a macro can be declared to accept a +variable number of arguments much as a function can. The syntax for +defining the macro is similar to that of a function. Here is an +example: + +@smallexample +#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) +@end smallexample + +@noindent +Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of +such a macro, it represents the zero or more tokens until the closing +parenthesis that ends the invocation, including any commas. This set of +tokens replaces the identifier @code{__VA_ARGS__} in the macro body +wherever it appears. See the CPP manual for more information. + +GCC has long supported variadic macros, and used a different syntax that +allowed you to give a name to the variable arguments just like any other +argument. Here is an example: + +@smallexample +#define debug(format, args...) fprintf (stderr, format, args) +@end smallexample + +@noindent +This is in all ways equivalent to the ISO C example above, but arguably +more readable and descriptive. + +GNU CPP has two further variadic macro extensions, and permits them to +be used with either of the above forms of macro definition. + +In standard C, you are not allowed to leave the variable argument out +entirely; but you are allowed to pass an empty argument. For example, +this invocation is invalid in ISO C, because there is no comma after +the string: + +@smallexample +debug ("A message") +@end smallexample + +GNU CPP permits you to completely omit the variable arguments in this +way. In the above examples, the compiler would complain, though since +the expansion of the macro still has the extra comma after the format +string. + +To help solve this problem, CPP behaves specially for variable arguments +used with the token paste operator, @samp{##}. If instead you write + +@smallexample +#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) +@end smallexample + +@noindent +and if the variable arguments are omitted or empty, the @samp{##} +operator causes the preprocessor to remove the comma before it. If you +do provide some variable arguments in your macro invocation, GNU CPP +does not complain about the paste operation and instead places the +variable arguments after the comma. Just like any other pasted macro +argument, these arguments are not macro expanded. + +@node Conditionals +@subsection Conditionals with Omitted Operands +@cindex conditional expressions, extensions +@cindex omitted middle-operands +@cindex middle-operands, omitted +@cindex extensions, @code{?:} +@cindex @code{?:} extensions + +The middle operand in a conditional expression may be omitted. Then +if the first operand is nonzero, its value is the value of the conditional +expression. + +Therefore, the expression + +@smallexample +x ? : y +@end smallexample + +@noindent +has the value of @code{x} if that is nonzero; otherwise, the value of +@code{y}. + +This example is perfectly equivalent to + +@smallexample +x ? x : y +@end smallexample + +@cindex side effect in @code{?:} +@cindex @code{?:} side effect +@noindent +In this simple case, the ability to omit the middle operand is not +especially useful. When it becomes useful is when the first operand does, +or may (if it is a macro argument), contain a side effect. Then repeating +the operand in the middle would perform the side effect twice. Omitting +the middle operand uses the value already computed without the undesirable +effects of recomputing it. + +@node Case Ranges +@subsection Case Ranges +@cindex case ranges +@cindex ranges in case statements + +You can specify a range of consecutive values in a single @code{case} label, +like this: + +@smallexample +case @var{low} ... @var{high}: +@end smallexample + +@noindent +This has the same effect as the proper number of individual @code{case} +labels, one for each integer value from @var{low} to @var{high}, inclusive. + +This feature is especially useful for ranges of ASCII character codes: + +@smallexample +case 'A' ... 'Z': +@end smallexample + +@strong{Be careful:} Write spaces around the @code{...}, for otherwise +it may be parsed wrong when you use it with integer values. For example, +write this: + +@smallexample +case 1 ... 5: +@end smallexample + +@noindent +rather than this: + +@smallexample +case 1...5: +@end smallexample + +@node Mixed Labels and Declarations +@subsection Mixed Declarations, Labels and Code +@cindex mixed declarations and code +@cindex declarations, mixed with code +@cindex code, mixed with declarations + +ISO C99 and ISO C++ allow declarations and code to be freely mixed +within compound statements. ISO C23 allows labels to be +placed before declarations and at the end of a compound statement. +As an extension, GNU C also allows all this in C90 mode. For example, +you could do: + +@smallexample +int i; +/* @r{@dots{}} */ +i++; +int j = i + 2; +@end smallexample + +Each identifier is visible from where it is declared until the end of +the enclosing block. + +@node C++ Comments +@subsection C++ Style Comments +@cindex @code{//} +@cindex C++ comments +@cindex comments, C++ style + +In GNU C, you may use C++ style comments, which start with @samp{//} and +continue until the end of the line. Many other C implementations allow +such comments, and they are included in the 1999 C standard. However, +C++ style comments are not recognized if you specify an @option{-std} +option specifying a version of ISO C before C99, or @option{-ansi} +(equivalent to @option{-std=c90}). + +@node Escaped Newlines +@subsection Slightly Looser Rules for Escaped Newlines +@cindex escaped newlines +@cindex newlines (escaped) + +The preprocessor treatment of escaped newlines is more relaxed +than that specified by the C90 standard, which requires the newline +to immediately follow a backslash. +GCC's implementation allows whitespace in the form +of spaces, horizontal and vertical tabs, and form feeds between the +backslash and the subsequent newline. The preprocessor issues a +warning, but treats it as a valid escaped newline and combines the two +lines to form a single logical line. This works within comments and +tokens, as well as between tokens. Comments are @emph{not} treated as +whitespace for the purposes of this relaxation, since they have not +yet been replaced with spaces. + +@node Hex Floats +@subsection Hex Floats +@cindex hex floats + +ISO C99 and ISO C++17 support floating-point numbers written not only in +the usual decimal notation, such as @code{1.55e1}, but also numbers such as +@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC +supports this in C90 mode (except in some cases when strictly +conforming) and in C++98, C++11 and C++14 modes. In that format the +@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are +mandatory. The exponent is a decimal number that indicates the power of +2 by which the significant part is multiplied. Thus @samp{0x1.f} is +@tex +$1 {15\over16}$, +@end tex +@ifnottex +1 15/16, +@end ifnottex +@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} +is the same as @code{1.55e1}. + +Unlike for floating-point numbers in the decimal notation the exponent +is always required in the hexadecimal notation. Otherwise the compiler +would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This +could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the +extension for floating-point constants of type @code{float}. + +@node Binary constants +@subsection Binary Constants using the @samp{0b} Prefix +@cindex Binary constants using the @samp{0b} prefix + +Integer constants can be written as binary constants, consisting of a +sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or +@samp{0B}. This is particularly useful in environments that operate a +lot on the bit level (like microcontrollers). + +The following statements are identical: + +@smallexample +i = 42; +i = 0x2a; +i = 052; +i = 0b101010; +@end smallexample + +The type of these constants follows the same rules as for octal or +hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} +can be applied. + +@node Dollar Signs +@subsection Dollar Signs in Identifier Names +@cindex $ +@cindex dollar signs in identifier names +@cindex identifier names, dollar signs in + +In GNU C, you may normally use dollar signs in identifier names. +This is because many traditional C implementations allow such identifiers. +However, dollar signs in identifiers are not supported on a few target +machines, typically because the target assembler does not allow them. + +@node Character Escapes +@subsection The Character @key{ESC} in Constants + +You can use the sequence @samp{\e} in a string or character constant to +stand for the ASCII character @key{ESC}. + @node Alternate Keywords -@section Alternate Keywords +@subsection Alternate Keywords @cindex alternate keywords @cindex keywords, alternate @@ -13099,25 +14096,8 @@ that predate C23@. @code{__extension__} has no effect aside from this. -@node Incomplete Enums -@section Incomplete @code{enum} Types - -You can define an @code{enum} tag without specifying its possible values. -This results in an incomplete type, much like what you get if you write -@code{struct foo} without describing the elements. A later declaration -that does specify the possible values completes the type. - -You cannot allocate variables or storage using the type while it is -incomplete. However, you can work with pointers to that type. - -This extension may not be very useful, but it makes the handling of -@code{enum} more consistent with the way @code{struct} and @code{union} -are handled. - -This extension is not supported by GNU C++. - @node Function Names -@section Function Names as Strings +@subsection Function Names as Strings @cindex @code{__func__} identifier @cindex @code{__FUNCTION__} identifier @cindex @code{__PRETTY_FUNCTION__} identifier @@ -13184,6 +14164,1848 @@ These identifiers are variables, not preprocessor macros, and may not be used to initialize @code{char} arrays or be concatenated with string literals. +@node Semantic Extensions +@section Extensions to C Semantics + +GNU C defines useful behavior for some constructs that are not allowed or +well-defined in standard C. + +@menu +* Function Prototypes:: Prototype declarations and old-style definitions. +* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. +* Variadic Pointer Args:: Pointer arguments to variadic functions. +* Pointers to Arrays:: Pointers to arrays with qualifiers work as expected. +* Const and Volatile Functions:: GCC interprets these specially in C. +@end menu + +@node Function Prototypes +@subsection Prototypes and Old-Style Function Definitions +@cindex function prototype declarations +@cindex old-style function definitions +@cindex promotion of formal parameters + +GNU C extends ISO C to allow a function prototype to override a later +old-style non-prototype definition. Consider the following example: + +@smallexample +/* @r{Use prototypes unless the compiler is old-fashioned.} */ +#ifdef __STDC__ +#define P(x) x +#else +#define P(x) () +#endif + +/* @r{Prototype function declaration.} */ +int isroot P((uid_t)); + +/* @r{Old-style function definition.} */ +int +isroot (x) /* @r{??? lossage here ???} */ + uid_t x; +@{ + return x == 0; +@} +@end smallexample + +Suppose the type @code{uid_t} happens to be @code{short}. ISO C does +not allow this example, because subword arguments in old-style +non-prototype definitions are promoted. Therefore in this example the +function definition's argument is really an @code{int}, which does not +match the prototype argument type of @code{short}. + +This restriction of ISO C makes it hard to write code that is portable +to traditional C compilers, because the programmer does not know +whether the @code{uid_t} type is @code{short}, @code{int}, or +@code{long}. Therefore, in cases like these GNU C allows a prototype +to override a later old-style definition. More precisely, in GNU C, a +function prototype argument type overrides the argument type specified +by a later old-style definition if the former type is the same as the +latter type before promotion. Thus in GNU C the above example is +equivalent to the following: + +@smallexample +int isroot (uid_t); + +int +isroot (uid_t x) +@{ + return x == 0; +@} +@end smallexample + +@noindent +GNU C++ does not support old-style function definitions, so this +extension is irrelevant. + +@node Pointer Arith +@subsection Arithmetic on @code{void}- and Function-Pointers +@cindex void pointers, arithmetic +@cindex void, size of pointer to +@cindex function pointers, arithmetic +@cindex function, size of pointer to + +In GNU C, addition and subtraction operations are supported on pointers to +@code{void} and on pointers to functions. This is done by treating the +size of a @code{void} or of a function as 1. + +A consequence of this is that @code{sizeof} is also allowed on @code{void} +and on function types, and returns 1. + +@opindex Wpointer-arith +The option @option{-Wpointer-arith} requests a warning if these extensions +are used. + +@node Variadic Pointer Args +@subsection Pointer Arguments in Variadic Functions +@cindex pointer arguments in variadic functions +@cindex variadic functions, pointer arguments + +Standard C requires that pointer types used with @code{va_arg} in +functions with variable argument lists either must be compatible with +that of the actual argument, or that one type must be a pointer to +@code{void} and the other a pointer to a character type. GNU C +implements the POSIX XSI extension that additionally permits the use +of @code{va_arg} with a pointer type to receive arguments of any other +pointer type. + +In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used +to consume an argument of any pointer type. + +@node Pointers to Arrays +@subsection Pointers to Arrays with Qualifiers Work as Expected +@cindex pointers to arrays +@cindex const qualifier + +In GNU C, pointers to arrays with qualifiers work similar to pointers +to other qualified types. For example, a value of type @code{int (*)[5]} +can be used to initialize a variable of type @code{const int (*)[5]}. +These types are incompatible in ISO C because the @code{const} qualifier +is formally attached to the element type of the array and not the +array itself. + +@smallexample +extern void +transpose (int N, int M, double out[M][N], const double in[N][M]); +double x[3][2]; +double y[2][3]; +@r{@dots{}} +transpose(3, 2, y, x); +@end smallexample + +@node Const and Volatile Functions +@subsection Const and Volatile Functions +@cindex @code{const} applied to function +@cindex @code{volatile} applied to function + +The C standard explicitly leaves the behavior of the @code{const} and +@code{volatile} type qualifiers applied to functions undefined; these +constructs can only arise through the use of @code{typedef}. As an extension, +GCC defines this use of the @code{const} qualifier to have the same meaning +as the GCC @code{const} function attribute, and the @code{volatile} qualifier +to be equivalent to the @code{noreturn} attribute. +@xref{Common Function Attributes}, for more information. + +As examples of this usage, + +@smallexample + +/* @r{Equivalent to:} + void fatal () __attribute__ ((noreturn)); */ +typedef void voidfn (); +volatile voidfn fatal; + +/* @r{Equivalent to:} + extern int square (int) __attribute__ ((const)); */ +typedef int intfn (int); +extern const intfn square; +@end smallexample + +In general, using function attributes instead is preferred, since the +attributes make both the intent of the code and its reliance on a GNU +extension explicit. Additionally, using @code{const} and +@code{volatile} in this way is specific to GNU C and does not work in +GNU C++. + +@node Built-in Functions +@chapter Built-in Functions Provided by GCC +@cindex Built-in Functions + +GCC provides a very large number of implicitly-declared built-in +functions that are typically inlined by the compiler. Some of these +builtins directly correspond to standard library routines. Some are +for internal use in the processing of exceptions or variable-length +argument lists and are not documented here because they may change +from time to time; we do not recommend general use of these functions. + +The remaining functions are provided either for optimization purposes, or +to expose low-level functionality needed to implement +features provided by library functions or similar ``glue'' between GCC +and other programming languages or libraries. Others are +target-specific, providing direct access to instructions that have no +direct C equivalents without the need to write assembly language. There +are also builtins to support various kinds of runtime error checking. + +Most builtins have names prefixed with @samp{__builtin_}, although not +all of them use this convention. Except as otherwise documented, all +built-in functions are available from any of the C family languages +supported by GCC. + +With the exception of built-ins that have library equivalents such as +the standard C library functions discussed below in @ref{Library Builtins}, +or that expand to +library calls, GCC built-in functions are always expanded inline and +thus do not have corresponding entry points and their address cannot +be obtained. Attempting to use them in an expression other than +a function call results in a compile-time error. + +@menu +* Library Builtins:: Built-in equivalents for C library functions. +* Numeric Builtins:: Additional builtins for numeric and bit operations. +* Stack Allocation:: Built-in alloca variants. +* Nonlocal Gotos:: Built-ins for nonlocal gotos. +* Constructing Calls:: Built-ins for dispatching a call to another function. +* Return Address:: Getting the return or frame address of a function. +* Stack Scrubbing:: Stack scrubbing internal interfaces. +* Vector Extensions:: Using vector instructions through built-in functions. +* Atomic Memory Access:: __atomic and __sync builtins. +* Object Size Checking:: Built-in functions for limited buffer overflow + checking. +* New/Delete Builtins:: Built-in functions for C++ allocations and deallocations. +* Other Builtins:: Other built-in functions. +* Target Builtins:: Built-in functions specific to particular targets. +@end menu + +@node Library Builtins +@section Builtins for C Library Functions +@cindex built-in library functions +@cindex library function builtins +@cindex C library function builtins + +@findex __builtin_iseqsig +@findex __builtin_isfinite +@findex __builtin_isnormal +@findex __builtin_isgreater +@findex __builtin_isgreaterequal +@findex __builtin_isunordered +@findex __builtin_speculation_safe_value +@findex _Exit +@findex _exit +@findex abort +@findex abs +@findex acos +@findex acosf +@findex acosh +@findex acoshf +@findex acoshl +@findex acosl +@findex alloca +@findex asin +@findex asinf +@findex asinh +@findex asinhf +@findex asinhl +@findex asinl +@findex atan +@findex atan2 +@findex atan2f +@findex atan2l +@findex atanf +@findex atanh +@findex atanhf +@findex atanhl +@findex atanl +@findex bcmp +@findex bzero +@findex cabs +@findex cabsf +@findex cabsl +@findex cacos +@findex cacosf +@findex cacosh +@findex cacoshf +@findex cacoshl +@findex cacosl +@findex calloc +@findex carg +@findex cargf +@findex cargl +@findex casin +@findex casinf +@findex casinh +@findex casinhf +@findex casinhl +@findex casinl +@findex catan +@findex catanf +@findex catanh +@findex catanhf +@findex catanhl +@findex catanl +@findex cbrt +@findex cbrtf +@findex cbrtl +@findex ccos +@findex ccosf +@findex ccosh +@findex ccoshf +@findex ccoshl +@findex ccosl +@findex ceil +@findex ceilf +@findex ceill +@findex cexp +@findex cexpf +@findex cexpl +@findex cimag +@findex cimagf +@findex cimagl +@findex clog +@findex clogf +@findex clogl +@findex clog10 +@findex clog10f +@findex clog10l +@findex conj +@findex conjf +@findex conjl +@findex copysign +@findex copysignf +@findex copysignl +@findex cos +@findex cosf +@findex cosh +@findex coshf +@findex coshl +@findex cosl +@findex cpow +@findex cpowf +@findex cpowl +@findex cproj +@findex cprojf +@findex cprojl +@findex creal +@findex crealf +@findex creall +@findex csin +@findex csinf +@findex csinh +@findex csinhf +@findex csinhl +@findex csinl +@findex csqrt +@findex csqrtf +@findex csqrtl +@findex ctan +@findex ctanf +@findex ctanh +@findex ctanhf +@findex ctanhl +@findex ctanl +@findex dcgettext +@findex dgettext +@findex drem +@findex dremf +@findex dreml +@findex erf +@findex erfc +@findex erfcf +@findex erfcl +@findex erff +@findex erfl +@findex exit +@findex exp +@findex exp10 +@findex exp10f +@findex exp10l +@findex exp2 +@findex exp2f +@findex exp2l +@findex expf +@findex expl +@findex expm1 +@findex expm1f +@findex expm1l +@findex fabs +@findex fabsf +@findex fabsl +@findex fdim +@findex fdimf +@findex fdiml +@findex ffs +@findex floor +@findex floorf +@findex floorl +@findex fma +@findex fmaf +@findex fmal +@findex fmax +@findex fmaxf +@findex fmaxl +@findex fmin +@findex fminf +@findex fminl +@findex fmod +@findex fmodf +@findex fmodl +@findex fprintf +@findex fprintf_unlocked +@findex fputs +@findex fputs_unlocked +@findex free +@findex frexp +@findex frexpf +@findex frexpl +@findex fscanf +@findex gamma +@findex gammaf +@findex gammal +@findex gamma_r +@findex gammaf_r +@findex gammal_r +@findex gettext +@findex hypot +@findex hypotf +@findex hypotl +@findex ilogb +@findex ilogbf +@findex ilogbl +@findex imaxabs +@findex index +@findex isalnum +@findex isalpha +@findex isascii +@findex isblank +@findex iscntrl +@findex isdigit +@findex isgraph +@findex islower +@findex isprint +@findex ispunct +@findex isspace +@findex isupper +@findex iswalnum +@findex iswalpha +@findex iswblank +@findex iswcntrl +@findex iswdigit +@findex iswgraph +@findex iswlower +@findex iswprint +@findex iswpunct +@findex iswspace +@findex iswupper +@findex iswxdigit +@findex isxdigit +@findex j0 +@findex j0f +@findex j0l +@findex j1 +@findex j1f +@findex j1l +@findex jn +@findex jnf +@findex jnl +@findex labs +@findex ldexp +@findex ldexpf +@findex ldexpl +@findex lgamma +@findex lgammaf +@findex lgammal +@findex lgamma_r +@findex lgammaf_r +@findex lgammal_r +@findex llabs +@findex llrint +@findex llrintf +@findex llrintl +@findex llround +@findex llroundf +@findex llroundl +@findex log +@findex log10 +@findex log10f +@findex log10l +@findex log1p +@findex log1pf +@findex log1pl +@findex log2 +@findex log2f +@findex log2l +@findex logb +@findex logbf +@findex logbl +@findex logf +@findex logl +@findex lrint +@findex lrintf +@findex lrintl +@findex lround +@findex lroundf +@findex lroundl +@findex malloc +@findex memchr +@findex memcmp +@findex memcpy +@findex mempcpy +@findex memset +@findex modf +@findex modff +@findex modfl +@findex nearbyint +@findex nearbyintf +@findex nearbyintl +@findex nextafter +@findex nextafterf +@findex nextafterl +@findex nexttoward +@findex nexttowardf +@findex nexttowardl +@findex pow +@findex pow10 +@findex pow10f +@findex pow10l +@findex powf +@findex powl +@findex printf +@findex printf_unlocked +@findex putchar +@findex puts +@findex realloc +@findex remainder +@findex remainderf +@findex remainderl +@findex remquo +@findex remquof +@findex remquol +@findex rindex +@findex rint +@findex rintf +@findex rintl +@findex round +@findex roundf +@findex roundl +@findex scalb +@findex scalbf +@findex scalbl +@findex scalbln +@findex scalblnf +@findex scalblnf +@findex scalbn +@findex scalbnf +@findex scanfnl +@findex signbit +@findex signbitf +@findex signbitl +@findex signbitd32 +@findex signbitd64 +@findex signbitd128 +@findex significand +@findex significandf +@findex significandl +@findex sin +@findex sincos +@findex sincosf +@findex sincosl +@findex sinf +@findex sinh +@findex sinhf +@findex sinhl +@findex sinl +@findex snprintf +@findex sprintf +@findex sqrt +@findex sqrtf +@findex sqrtl +@findex sscanf +@findex stpcpy +@findex stpncpy +@findex strcasecmp +@findex strcat +@findex strchr +@findex strcmp +@findex strcpy +@findex strcspn +@findex strdup +@findex strfmon +@findex strftime +@findex strlen +@findex strncasecmp +@findex strncat +@findex strncmp +@findex strncpy +@findex strndup +@findex strnlen +@findex strpbrk +@findex strrchr +@findex strspn +@findex strstr +@findex tan +@findex tanf +@findex tanh +@findex tanhf +@findex tanhl +@findex tanl +@findex tgamma +@findex tgammaf +@findex tgammal +@findex toascii +@findex tolower +@findex toupper +@findex towlower +@findex towupper +@findex trunc +@findex truncf +@findex truncl +@findex vfprintf +@findex vfscanf +@findex vprintf +@findex vscanf +@findex vsnprintf +@findex vsprintf +@findex vsscanf +@findex y0 +@findex y0f +@findex y0l +@findex y1 +@findex y1f +@findex y1l +@findex yn +@findex ynf +@findex ynl + +@opindex fno-builtin +GCC includes built-in versions of many of the functions in the standard +C library. These functions come in two forms: one whose names start with +the @code{__builtin_} prefix, and the other without. Both forms have the +same type (including prototype), the same address (when their address is +taken), and the same meaning as the C library functions even if you specify +the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these +functions are only optimized in certain cases; if they are not optimized in +a particular case, a call to the library function is emitted. + +@opindex ansi +@opindex std +Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, +@option{-std=c99} or @option{-std=c11}), the functions +@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, +@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, +@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, +@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, +@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, +@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, +@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, +@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, +@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, +@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, +@code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl}, +@code{scalbf}, @code{scalbl}, @code{scalb}, +@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, +@code{signbitd64}, @code{signbitd128}, @code{significandf}, +@code{significandl}, @code{significand}, @code{sincosf}, +@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, +@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, +@code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l}, +@code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and +@code{yn} +may be handled as built-in functions. +All these functions have corresponding versions +prefixed with @code{__builtin_}, which may be used even in strict C90 +mode. + +The ISO C99 functions +@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, +@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, +@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, +@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, +@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, +@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, +@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, +@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, +@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, +@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, +@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, +@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, +@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, +@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, +@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, +@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, +@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, +@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, +@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, +@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, +@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, +@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, +@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, +@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, +@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, +@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, +@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, +@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, +@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, +@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, +@code{nextafterf}, @code{nextafterl}, @code{nextafter}, +@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, +@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, +@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, +@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, +@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, +@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, +@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, +@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} +are handled as built-in functions +except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). + +There are also built-in versions of the ISO C99 functions +@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, +@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, +@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, +@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, +@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, +@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, +@code{modfl}, @code{modff}, @code{powf}, @code{powl}, @code{sinf}, +@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, +@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} +that are recognized in any mode since ISO C90 reserves these names for +the purpose to which ISO C99 puts them. All these functions have +corresponding versions prefixed with @code{__builtin_}. + +There are also built-in functions @code{__builtin_fabsf@var{n}}, +@code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and +@code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3 +functions @code{fabsf@var{n}}, @code{fabsf@var{n}x}, +@code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported +types @code{_Float@var{n}} and @code{_Float@var{n}x}. + +There are also GNU extension functions @code{clog10}, @code{clog10f} and +@code{clog10l} which names are reserved by ISO C99 for future use. +All these functions have versions prefixed with @code{__builtin_}. + +The ISO C94 functions +@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, +@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, +@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and +@code{towupper} +are handled as built-in functions +except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). + +The ISO C90 functions +@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, +@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, +@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, +@code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf}, +@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, +@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, +@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, +@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, +@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, +@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, +@code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin}, +@code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, +@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, +@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, +@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, +@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} +are all recognized as built-in functions unless +@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} +is specified for an individual function). All of these functions have +corresponding versions prefixed with @code{__builtin_}. + +GCC provides built-in versions of the ISO C99 floating-point comparison +macros that avoid raising exceptions for unordered operands. They have +the same names as the standard macros ( @code{isgreater}, +@code{isgreaterequal}, @code{isless}, @code{islessequal}, +@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} +prefixed. We intend for a library implementor to be able to simply +@code{#define} each standard macro to its built-in equivalent. +In the same fashion, GCC provides @code{fpclassify}, @code{iseqsig}, +@code{isfinite}, @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins +used with @code{__builtin_} prefixed. The @code{isinf} and @code{isnan} +built-in functions appear both with and without the @code{__builtin_} prefix. +With @code{-ffinite-math-only} option the @code{isinf} and @code{isnan} +built-in functions will always return 0. + +GCC provides built-in versions of the ISO C99 floating-point rounding and +exceptions handling functions @code{fegetround}, @code{feclearexcept} and +@code{feraiseexcept}. They may not be available for all targets, and because +they need close interaction with libc internal values, they may not be available +for all target libcs, but in all cases they will gracefully fallback to libc +calls. These built-in functions appear both with and without the +@code{__builtin_} prefix. + +@node Numeric Builtins +@section Additional Builtins for Numeric Operations +@cindex built-in numeric functions +@cindex numeric builtins + +GCC provides a large set of built-in functions for operating on GCC's +extended set of floating-point and integer types (@pxref{Additional +Numeric Types}). The floating-point builtins include functions for +building and testing infinities and NaNs. On integer types, there are +additional bit manipulation functions, byte-swapping, and CRC +functions. + +Many of these builtins are type-generic and can operate on any +floating-point or integer operand. + +@menu +* Floating-Point Format Builtins:: Huge values, infinities, and NaNs. +* Bit Operation Builtins:: Counting bits and similar functions. +* Byte-Swapping Builtins:: Reversing byte order. +* CRC Builtins:: Compute cyclic redundancy checks. +* Integer Overflow Builtins:: Built-in functions to perform arithmetics + and arithmetic overflow checking. +@end menu + +@node Floating-Point Format Builtins +@subsection Floating-Point Format Builtins +@cindex floating-point format builtins +@cindex NaN builtins +@cindex infinity builtins +@cindex huge value builtins + +@defbuiltin{double __builtin_huge_val (void)} +Returns a positive infinity, if supported by the floating-point format, +else @code{DBL_MAX}. This function is suitable for implementing the +ISO C macro @code{HUGE_VAL}. +@enddefbuiltin + +@defbuiltin{float __builtin_huge_valf (void)} +Similar to @code{__builtin_huge_val}, except the return type is @code{float}. +@enddefbuiltin + +@defbuiltin{{long double} __builtin_huge_vall (void)} +Similar to @code{__builtin_huge_val}, except the return +type is @code{long double}. +@enddefbuiltin + +@defbuiltin{_Float@var{n} __builtin_huge_valf@var{n} (void)} +Similar to @code{__builtin_huge_val}, except the return type is +@code{_Float@var{n}}. +@enddefbuiltin + +@defbuiltin{_Float@var{n}x __builtin_huge_valf@var{n}x (void)} +Similar to @code{__builtin_huge_val}, except the return type is +@code{_Float@var{n}x}. +@enddefbuiltin + +@defbuiltin{int __builtin_fpclassify (int, int, int, int, int, ...)} +This built-in implements the C99 fpclassify functionality. The first +five int arguments should be the target library's notion of the +possible FP classes and are used for return values. They must be +constant values and they must appear in this order: @code{FP_NAN}, +@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and +@code{FP_ZERO}. The ellipsis is for exactly one floating-point value +to classify. GCC treats the last argument as type-generic, which +means it does not do default promotion from float to double. +@enddefbuiltin + +@defbuiltin{double __builtin_inf (void)} +Similar to @code{__builtin_huge_val}, except a warning is generated +if the target floating-point format does not support infinities. +@enddefbuiltin + +@defbuiltin{_Decimal32 __builtin_infd32 (void)} +Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. +@enddefbuiltin + +@defbuiltin{_Decimal64 __builtin_infd64 (void)} +Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. +@enddefbuiltin + +@defbuiltin{_Decimal128 __builtin_infd128 (void)} +Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. +@enddefbuiltin + +@defbuiltin{float __builtin_inff (void)} +Similar to @code{__builtin_inf}, except the return type is @code{float}. +This function is suitable for implementing the ISO C99 macro @code{INFINITY}. +@enddefbuiltin + +@defbuiltin{{long double} __builtin_infl (void)} +Similar to @code{__builtin_inf}, except the return +type is @code{long double}. +@enddefbuiltin + +@defbuiltin{_Float@var{n} __builtin_inff@var{n} (void)} +Similar to @code{__builtin_inf}, except the return +type is @code{_Float@var{n}}. +@enddefbuiltin + +@defbuiltin{_Float@var{n} __builtin_inff@var{n}x (void)} +Similar to @code{__builtin_inf}, except the return +type is @code{_Float@var{n}x}. +@enddefbuiltin + +@defbuiltin{int __builtin_isinf_sign (...)} +Similar to @code{isinf}, except the return value is -1 for +an argument of @code{-Inf} and 1 for an argument of @code{+Inf}. +Note while the parameter list is an +ellipsis, this function only accepts exactly one floating-point +argument. GCC treats this parameter as type-generic, which means it +does not do default promotion from float to double. +@enddefbuiltin + +@defbuiltin{double __builtin_nan (const char *@var{str})} +This is an implementation of the ISO C99 function @code{nan}. + +Since ISO C99 defines this function in terms of @code{strtod}, which we +do not implement, a description of the parsing is in order. The string +is parsed as by @code{strtol}; that is, the base is recognized by +leading @samp{0} or @samp{0x} prefixes. The number parsed is placed +in the significand such that the least significant bit of the number +is at the least significant bit of the significand. The number is +truncated to fit the significand field provided. The significand is +forced to be a quiet NaN@. + +This function, if given a string literal all of which would have been +consumed by @code{strtol}, is evaluated early enough that it is considered a +compile-time constant. +@enddefbuiltin + +@defbuiltin{_Decimal32 __builtin_nand32 (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. +@enddefbuiltin + +@defbuiltin{_Decimal64 __builtin_nand64 (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. +@enddefbuiltin + +@defbuiltin{_Decimal128 __builtin_nand128 (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. +@enddefbuiltin + +@defbuiltin{float __builtin_nanf (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is @code{float}. +@enddefbuiltin + +@defbuiltin{{long double} __builtin_nanl (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is @code{long double}. +@enddefbuiltin + +@defbuiltin{_Float@var{n} __builtin_nanf@var{n} (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is +@code{_Float@var{n}}. +@enddefbuiltin + +@defbuiltin{_Float@var{n}x __builtin_nanf@var{n}x (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is +@code{_Float@var{n}x}. +@enddefbuiltin + +@defbuiltin{double __builtin_nans (const char *@var{str})} +Similar to @code{__builtin_nan}, except the significand is forced +to be a signaling NaN@. The @code{nans} function is proposed by +@uref{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. +@enddefbuiltin + +@defbuiltin{_Decimal32 __builtin_nansd32 (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}. +@enddefbuiltin + +@defbuiltin{_Decimal64 __builtin_nansd64 (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}. +@enddefbuiltin + +@defbuiltin{_Decimal128 __builtin_nansd128 (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}. +@enddefbuiltin + +@defbuiltin{float __builtin_nansf (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is @code{float}. +@enddefbuiltin + +@defbuiltin{{long double} __builtin_nansl (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is @code{long double}. +@enddefbuiltin + +@defbuiltin{_Float@var{n} __builtin_nansf@var{n} (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is +@code{_Float@var{n}}. +@enddefbuiltin + +@defbuiltin{_Float@var{n}x __builtin_nansf@var{n}x (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is +@code{_Float@var{n}x}. +@enddefbuiltin + +@defbuiltin{int __builtin_issignaling (...)} +Return non-zero if the argument is a signaling NaN and zero otherwise. +Note while the parameter list is an +ellipsis, this function only accepts exactly one floating-point +argument. GCC treats this parameter as type-generic, which means it +does not do default promotion from float to double. +This built-in function can work even without the non-default +@code{-fsignaling-nans} option, although if a signaling NaN is computed, +stored or passed as argument to some function other than this built-in +in the current translation unit, it is safer to use @code{-fsignaling-nans}. +With @code{-ffinite-math-only} option this built-in function will always +return 0. +@enddefbuiltin + +@defbuiltin{double __builtin_powi (double, int)} +@defbuiltinx{float __builtin_powif (float, int)} +@defbuiltinx{{long double} __builtin_powil (long double, int)} +Returns the first argument raised to the power of the second. Unlike the +@code{pow} function no guarantees about precision and rounding are made. +@enddefbuiltin + +@node Bit Operation Builtins +@subsection Bit Operation Builtins +@cindex bit operation builtins + +@defbuiltin{int __builtin_ffs (int @var{x})} +Returns one plus the index of the least significant 1-bit of @var{x}, or +if @var{x} is zero, returns zero. +@enddefbuiltin + +@defbuiltin{int __builtin_clz (unsigned int @var{x})} +Returns the number of leading 0-bits in @var{x}, starting at the most +significant bit position. If @var{x} is 0, the result is undefined. +@enddefbuiltin + +@defbuiltin{int __builtin_ctz (unsigned int @var{x})} +Returns the number of trailing 0-bits in @var{x}, starting at the least +significant bit position. If @var{x} is 0, the result is undefined. +@enddefbuiltin + +@defbuiltin{int __builtin_clrsb (int @var{x})} +Returns the number of leading redundant sign bits in @var{x}, i.e.@: the +number of bits following the most significant bit that are identical +to it. There are no special cases for 0 or other values. +@enddefbuiltin + +@defbuiltin{int __builtin_popcount (unsigned int @var{x})} +Returns the number of 1-bits in @var{x}. +@enddefbuiltin + +@defbuiltin{int __builtin_parity (unsigned int @var{x})} +Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} +modulo 2. +@enddefbuiltin + +@defbuiltin{int __builtin_ffsl (long)} +Similar to @code{__builtin_ffs}, except the argument type is +@code{long}. +@enddefbuiltin + +@defbuiltin{int __builtin_clzl (unsigned long)} +Similar to @code{__builtin_clz}, except the argument type is +@code{unsigned long}. +@enddefbuiltin + +@defbuiltin{int __builtin_ctzl (unsigned long)} +Similar to @code{__builtin_ctz}, except the argument type is +@code{unsigned long}. +@enddefbuiltin + +@defbuiltin{int __builtin_clrsbl (long)} +Similar to @code{__builtin_clrsb}, except the argument type is +@code{long}. +@enddefbuiltin + +@defbuiltin{int __builtin_popcountl (unsigned long)} +Similar to @code{__builtin_popcount}, except the argument type is +@code{unsigned long}. +@enddefbuiltin + +@defbuiltin{int __builtin_parityl (unsigned long)} +Similar to @code{__builtin_parity}, except the argument type is +@code{unsigned long}. +@enddefbuiltin + +@defbuiltin{int __builtin_ffsll (long long)} +Similar to @code{__builtin_ffs}, except the argument type is +@code{long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_clzll (unsigned long long)} +Similar to @code{__builtin_clz}, except the argument type is +@code{unsigned long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_ctzll (unsigned long long)} +Similar to @code{__builtin_ctz}, except the argument type is +@code{unsigned long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_clrsbll (long long)} +Similar to @code{__builtin_clrsb}, except the argument type is +@code{long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_popcountll (unsigned long long)} +Similar to @code{__builtin_popcount}, except the argument type is +@code{unsigned long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_parityll (unsigned long long)} +Similar to @code{__builtin_parity}, except the argument type is +@code{unsigned long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_ffsg (...)} +Similar to @code{__builtin_ffs}, except the argument is type-generic +signed integer (standard, extended or bit-precise). No integral argument +promotions are performed on the argument. +@enddefbuiltin + +@defbuiltin{int __builtin_clzg (...)} +Similar to @code{__builtin_clz}, except the argument is type-generic +unsigned integer (standard, extended or bit-precise) and there is +optional second argument with int type. No integral argument promotions +are performed on the first argument. If two arguments are specified, +and first argument is 0, the result is the second argument. If only +one argument is specified and it is 0, the result is undefined. +@enddefbuiltin + +@defbuiltin{int __builtin_ctzg (...)} +Similar to @code{__builtin_ctz}, except the argument is type-generic +unsigned integer (standard, extended or bit-precise) and there is +optional second argument with int type. No integral argument promotions +are performed on the first argument. If two arguments are specified, +and first argument is 0, the result is the second argument. If only +one argument is specified and it is 0, the result is undefined. +@enddefbuiltin + +@defbuiltin{int __builtin_clrsbg (...)} +Similar to @code{__builtin_clrsb}, except the argument is type-generic +signed integer (standard, extended or bit-precise). No integral argument +promotions are performed on the argument. +@enddefbuiltin + +@defbuiltin{int __builtin_popcountg (...)} +Similar to @code{__builtin_popcount}, except the argument is type-generic +unsigned integer (standard, extended or bit-precise). No integral argument +promotions are performed on the argument. +@enddefbuiltin + +@defbuiltin{int __builtin_parityg (...)} +Similar to @code{__builtin_parity}, except the argument is type-generic +unsigned integer (standard, extended or bit-precise). No integral argument +promotions are performed on the argument. +@enddefbuiltin + +@defbuiltin{@var{type} __builtin_stdc_bit_ceil (@var{type} @var{arg})} +The @code{__builtin_stdc_bit_ceil} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{@var{arg} <= 1 ? (@var{type}) 1 +: (@var{type}) 2 << (@var{prec} - 1 - __builtin_clzg ((@var{type}) (@var{arg} - 1)))} +where @var{prec} is bit width of @var{type}, except that side-effects +in @var{arg} are evaluated just once. +@enddefbuiltin + +@defbuiltin{@var{type} __builtin_stdc_bit_floor (@var{type} @var{arg})} +The @code{__builtin_stdc_bit_floor} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{@var{arg} == 0 ? (@var{type}) 0 +: (@var{type}) 1 << (@var{prec} - 1 - __builtin_clzg (@var{arg}))} +where @var{prec} is bit width of @var{type}, except that side-effects +in @var{arg} are evaluated just once. +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_bit_width (@var{type} @var{arg})} +The @code{__builtin_stdc_bit_width} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) (@var{prec} - __builtin_clzg (@var{arg}, @var{prec}))} +where @var{prec} is bit width of @var{type}. +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_count_ones (@var{type} @var{arg})} +The @code{__builtin_stdc_count_ones} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_popcountg (@var{arg})} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_count_zeros (@var{type} @var{arg})} +The @code{__builtin_stdc_count_zeros} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_popcountg ((@var{type}) ~@var{arg})} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_first_leading_one (@var{type} @var{arg})} +The @code{__builtin_stdc_first_leading_one} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{__builtin_clzg (@var{arg}, -1) + 1U} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_first_leading_zero (@var{type} @var{arg})} +The @code{__builtin_stdc_first_leading_zero} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{__builtin_clzg ((@var{type}) ~@var{arg}, -1) + 1U} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_first_trailing_one (@var{type} @var{arg})} +The @code{__builtin_stdc_first_trailing_one} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{__builtin_ctzg (@var{arg}, -1) + 1U} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_first_trailing_zero (@var{type} @var{arg})} +The @code{__builtin_stdc_first_trailing_zero} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{__builtin_ctzg ((@var{type}) ~@var{arg}, -1) + 1U} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_has_single_bit (@var{type} @var{arg})} +The @code{__builtin_stdc_has_single_bit} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(_Bool) (__builtin_popcountg (@var{arg}) == 1)} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_leading_ones (@var{type} @var{arg})} +The @code{__builtin_stdc_leading_ones} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_clzg ((@var{type}) ~@var{arg}, @var{prec})} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_leading_zeros (@var{type} @var{arg})} +The @code{__builtin_stdc_leading_zeros} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_clzg (@var{arg}, @var{prec})} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_trailing_ones (@var{type} @var{arg})} +The @code{__builtin_stdc_trailing_ones} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_ctzg ((@var{type}) ~@var{arg}, @var{prec})} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_trailing_zeros (@var{type} @var{arg})} +The @code{__builtin_stdc_trailing_zeros} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_ctzg (@var{arg}, @var{prec})} +@enddefbuiltin + +@defbuiltin{@var{type1} __builtin_stdc_rotate_left (@var{type1} @var{arg1}, @var{type2} @var{arg2})} +The @code{__builtin_stdc_rotate_left} function is available only +in C. It is type-generic, the first argument can be any unsigned integer +(standard, extended or bit-precise) and second argument any signed or +unsigned integer or @code{char}. No integral argument promotions are +performed on the arguments. It is equivalent to +@code{(@var{type1}) ((@var{arg1} << (@var{arg2} % @var{prec})) +| (@var{arg1} >> ((-(unsigned @var{type2}) @var{arg2}) % @var{prec})))} +where @var{prec} is bit width of @var{type1}, except that side-effects +in @var{arg1} and @var{arg2} are evaluated just once. The behavior is +undefined if @var{arg2} is negative. +@enddefbuiltin + +@defbuiltin{@var{type1} __builtin_stdc_rotate_right (@var{type1} @var{arg1}, @var{type2} @var{arg2})} +The @code{__builtin_stdc_rotate_right} function is available only +in C. It is type-generic, the first argument can be any unsigned integer +(standard, extended or bit-precise) and second argument any signed or +unsigned integer or @code{char}. No integral argument promotions are +performed on the arguments. It is equivalent to +@code{(@var{type1}) ((@var{arg1} >> (@var{arg2} % @var{prec})) +| (@var{arg1} << ((-(unsigned @var{type2}) @var{arg2}) % @var{prec})))} +where @var{prec} is bit width of @var{type1}, except that side-effects +in @var{arg1} and @var{arg2} are evaluated just once. The behavior is +undefined if @var{arg2} is negative. +@enddefbuiltin + +@node Byte-Swapping Builtins +@subsection Byte-Swapping Builtins +@cindex byte-swapping builtins + +@defbuiltin{uint16_t __builtin_bswap16 (uint16_t @var{x})} +Returns @var{x} with the order of the bytes reversed; for example, +@code{0xabcd} becomes @code{0xcdab}. Byte here always means +exactly 8 bits. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_bswap32 (uint32_t @var{x})} +Similar to @code{__builtin_bswap16}, except the argument and return types +are 32-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_bswap64 (uint64_t @var{x})} +Similar to @code{__builtin_bswap32}, except the argument and return types +are 64-bit. +@enddefbuiltin + +@defbuiltin{uint128_t __builtin_bswap128 (uint128_t @var{x})} +Similar to @code{__builtin_bswap64}, except the argument and return types +are 128-bit. Only supported on targets when 128-bit types are supported. +@enddefbuiltin + +@node CRC Builtins +@subsection CRC Builtins +@cindex CRC builtins + +@defbuiltin{uint8_t __builtin_rev_crc8_data8 (uint8_t @var{crc}, uint8_t @var{data}, uint8_t @var{poly})} +Returns the calculated 8-bit bit-reversed CRC using the initial CRC (8-bit), +data (8-bit) and the polynomial (8-bit). +@var{crc} is the initial CRC, @var{data} is the data and +@var{poly} is the polynomial without leading 1. +Table-based or clmul-based CRC may be used for the +calculation, depending on the target architecture. +@enddefbuiltin + +@defbuiltin{uint16_t __builtin_rev_crc16_data16 (uint16_t @var{crc}, uint16_t @var{data}, uint16_t @var{poly})} +Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types +are 16-bit. +@enddefbuiltin + +@defbuiltin{uint16_t __builtin_rev_crc16_data8 (uint16_t @var{crc}, uint8_t @var{data}, uint16_t @var{poly})} +Similar to @code{__builtin_rev_crc16_data16}, except the @var{data} argument +type is 8-bit. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_rev_crc32_data32 (uint32_t @var{crc}, uint32_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types +are 32-bit and for the CRC calculation may be also used crc* machine instruction +depending on the target and the polynomial. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_rev_crc32_data8 (uint32_t @var{crc}, uint8_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_rev_crc32_data32}, except the @var{data} argument +type is 8-bit. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_rev_crc32_data16 (uint32_t @var{crc}, uint16_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_rev_crc32_data32}, except the @var{data} argument +type is 16-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_rev_crc64_data64 (uint64_t @var{crc}, uint64_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types +are 64-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_rev_crc64_data8 (uint64_t @var{crc}, uint8_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type +is 8-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_rev_crc64_data16 (uint64_t @var{crc}, uint16_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type +is 16-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_rev_crc64_data32 (uint64_t @var{crc}, uint32_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type +is 32-bit. +@enddefbuiltin + +@defbuiltin{uint8_t __builtin_crc8_data8 (uint8_t @var{crc}, uint8_t @var{data}, uint8_t @var{poly})} +Returns the calculated 8-bit bit-forward CRC using the initial CRC (8-bit), +data (8-bit) and the polynomial (8-bit). +@var{crc} is the initial CRC, @var{data} is the data and +@var{poly} is the polynomial without leading 1. +Table-based or clmul-based CRC may be used for the +calculation, depending on the target architecture. +@enddefbuiltin + +@defbuiltin{uint16_t __builtin_crc16_data16 (uint16_t @var{crc}, uint16_t @var{data}, uint16_t @var{poly})} +Similar to @code{__builtin_crc8_data8}, except the argument and return types +are 16-bit. +@enddefbuiltin + +@defbuiltin{uint16_t __builtin_crc16_data8 (uint16_t @var{crc}, uint8_t @var{data}, uint16_t @var{poly})} +Similar to @code{__builtin_crc16_data16}, except the @var{data} argument type +is 8-bit. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_crc32_data32 (uint32_t @var{crc}, uint32_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_crc8_data8}, except the argument and return types +are 32-bit. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_crc32_data8 (uint32_t @var{crc}, uint8_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_crc32_data32}, except the @var{data} argument type +is 8-bit. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_crc32_data16 (uint32_t @var{crc}, uint16_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_crc32_data32}, except the @var{data} argument type +is 16-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_crc64_data64 (uint64_t @var{crc}, uint64_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_crc8_data8}, except the argument and return types +are 64-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_crc64_data8 (uint64_t @var{crc}, uint8_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type +is 8-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_crc64_data16 (uint64_t @var{crc}, uint16_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type +is 16-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_crc64_data32 (uint64_t @var{crc}, uint32_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type +is 32-bit. +@enddefbuiltin + +@node Integer Overflow Builtins +@subsection Built-in Functions to Perform Arithmetic with Overflow Checking +@cindex overflow checking builtins +@cindex integer arithmetic overflow checking builtins +@cindex builtins for arithmetic overflow checking + +The following built-in functions allow performing simple arithmetic operations +together with checking whether the operations overflowed. + +@defbuiltin{bool __builtin_add_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} +@defbuiltinx{bool __builtin_sadd_overflow (int @var{a}, int @var{b}, int *@var{res})} +@defbuiltinx{bool __builtin_saddl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} +@defbuiltinx{bool __builtin_saddll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} +@defbuiltinx{bool __builtin_uadd_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} +@defbuiltinx{bool __builtin_uaddl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} +@defbuiltinx{bool __builtin_uaddll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} + +These built-in functions promote the first two operands into infinite precision signed +type and perform addition on those promoted operands. The result is then +cast to the type the third pointer argument points to and stored there. +If the stored result is equal to the infinite precision result, the built-in +functions return @code{false}, otherwise they return @code{true}. As the addition is +performed in infinite signed precision, these built-in functions have fully defined +behavior for all argument values. + +The first built-in function allows arbitrary integral types for operands and +the result type must be pointer to some integral type other than enumerated or +boolean type, the rest of the built-in functions have explicit integer types. + +The compiler will attempt to use hardware instructions to implement +these built-in functions where possible, like conditional jump on overflow +after addition, conditional jump on carry etc. + +@enddefbuiltin + +@defbuiltin{bool __builtin_sub_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} +@defbuiltinx{bool __builtin_ssub_overflow (int @var{a}, int @var{b}, int *@var{res})} +@defbuiltinx{bool __builtin_ssubl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} +@defbuiltinx{bool __builtin_ssubll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} +@defbuiltinx{bool __builtin_usub_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} +@defbuiltinx{bool __builtin_usubl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} +@defbuiltinx{bool __builtin_usubll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} + +These built-in functions are similar to the add overflow checking built-in +functions above, except they perform subtraction, subtract the second argument +from the first one, instead of addition. + +@enddefbuiltin + +@defbuiltin{bool __builtin_mul_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} +@defbuiltinx{bool __builtin_smul_overflow (int @var{a}, int @var{b}, int *@var{res})} +@defbuiltinx{bool __builtin_smull_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} +@defbuiltinx{bool __builtin_smulll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} +@defbuiltinx{bool __builtin_umul_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} +@defbuiltinx{bool __builtin_umull_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} +@defbuiltinx{bool __builtin_umulll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} + +These built-in functions are similar to the add overflow checking built-in +functions above, except they perform multiplication, instead of addition. + +@enddefbuiltin + +The following built-in functions allow checking if simple arithmetic operation +would overflow. + +@defbuiltin{bool __builtin_add_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} +@defbuiltinx{bool __builtin_sub_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} +@defbuiltinx{bool __builtin_mul_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} + +These built-in functions are similar to @code{__builtin_add_overflow}, +@code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that +they don't store the result of the arithmetic operation anywhere and the +last argument is not a pointer, but some expression with integral type other +than enumerated or boolean type. + +The built-in functions promote the first two operands into infinite precision signed type +and perform addition on those promoted operands. The result is then +cast to the type of the third argument. If the cast result is equal to the infinite +precision result, the built-in functions return @code{false}, otherwise they return @code{true}. +The value of the third argument is ignored, just the side effects in the third argument +are evaluated, and no integral argument promotions are performed on the last argument. +If the third argument is a bit-field, the type used for the result cast has the +precision and signedness of the given bit-field, rather than precision and signedness +of the underlying type. + +For example, the following macro can be used to portably check, at +compile-time, whether or not adding two constant integers will overflow, +and perform the addition only when it is known to be safe and not to trigger +a @option{-Woverflow} warning. + +@smallexample +#define INT_ADD_OVERFLOW_P(a, b) \ + __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0) + +enum @{ + A = INT_MAX, B = 3, + C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B, + D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0) +@}; +@end smallexample + +The compiler will attempt to use hardware instructions to implement +these built-in functions where possible, like conditional jump on overflow +after addition, conditional jump on carry etc. + +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_addc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})} +@defbuiltinx{{unsigned long int} __builtin_addcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})} +@defbuiltinx{{unsigned long long int} __builtin_addcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})} + +These built-in functions are equivalent to: +@smallexample + (@{ __typeof__ (@var{a}) s; \ + __typeof__ (@var{a}) c1 = __builtin_add_overflow (@var{a}, @var{b}, &s); \ + __typeof__ (@var{a}) c2 = __builtin_add_overflow (s, @var{carry_in}, &s); \ + *(@var{carry_out}) = c1 | c2; \ + s; @}) +@end smallexample + +i.e.@: they add 3 unsigned values, set what the last argument +points to to 1 if any of the two additions overflowed (otherwise 0) +and return the sum of those 3 unsigned values. Note, while all +the first 3 arguments can have arbitrary values, better code will be +emitted if one of them (preferably the third one) has only values +0 or 1 (i.e.@: carry-in). + +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_subc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})} +@defbuiltinx{{unsigned long int} __builtin_subcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})} +@defbuiltinx{{unsigned long long int} __builtin_subcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})} + +These built-in functions are equivalent to: +@smallexample + (@{ __typeof__ (@var{a}) s; \ + __typeof__ (@var{a}) c1 = __builtin_sub_overflow (@var{a}, @var{b}, &s); \ + __typeof__ (@var{a}) c2 = __builtin_sub_overflow (s, @var{carry_in}, &s); \ + *(@var{carry_out}) = c1 | c2; \ + s; @}) +@end smallexample + +i.e.@: they subtract 2 unsigned values from the first unsigned value, +set what the last argument points to to 1 if any of the two subtractions +overflowed (otherwise 0) and return the result of the subtractions. +Note, while all the first 3 arguments can have arbitrary values, better code +will be emitted if one of them (preferrably the third one) has only values +0 or 1 (i.e.@: carry-in). + +@enddefbuiltin + +@node Stack Allocation +@section Builtins for Stack Allocation +@cindex stack allocation builtins +@cindex builtins for stack allocation + +@defbuiltin{{void *} __builtin_alloca (size_t @var{size})} +The @code{__builtin_alloca} function must be called at block scope. +The function allocates an object @var{size} bytes large on the stack +of the calling function. The object is aligned on the default stack +alignment boundary for the target determined by the +@code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca} +function returns a pointer to the first byte of the allocated object. +The lifetime of the allocated object ends just before the calling +function returns to its caller. This is so even when +@code{__builtin_alloca} is called within a nested block. + +For example, the following function allocates eight objects of @code{n} +bytes each on the stack, storing a pointer to each in consecutive elements +of the array @code{a}. It then passes the array to function @code{g} +which can safely use the storage pointed to by each of the array elements. + +@smallexample +void f (unsigned n) +@{ + void *a [8]; + for (int i = 0; i != 8; ++i) + a [i] = __builtin_alloca (n); + + g (a, n); // @r{safe} +@} +@end smallexample + +Since the @code{__builtin_alloca} function doesn't validate its argument +it is the responsibility of its caller to make sure the argument doesn't +cause it to exceed the stack size limit. +The @code{__builtin_alloca} function is provided to make it possible to +allocate on the stack arrays of bytes with an upper bound that may be +computed at run time. Since C99 Variable Length Arrays offer +similar functionality under a portable, more convenient, and safer +interface they are recommended instead, in both C99 and C++ programs +where GCC provides them as an extension. +@xref{Variable Length}, for details. + +@enddefbuiltin + +@defbuiltin{{void *} __builtin_alloca_with_align (size_t @var{size}, size_t @var{alignment})} +The @code{__builtin_alloca_with_align} function must be called at block +scope. The function allocates an object @var{size} bytes large on +the stack of the calling function. The allocated object is aligned on +the boundary specified by the argument @var{alignment} whose unit is given +in bits (not bytes). The @var{size} argument must be positive and not +exceed the stack size limit. The @var{alignment} argument must be a constant +integer expression that evaluates to a power of 2 greater than or equal to +@code{CHAR_BIT} and less than some unspecified maximum. Invocations +with other values are rejected with an error indicating the valid bounds. +The function returns a pointer to the first byte of the allocated object. +The lifetime of the allocated object ends at the end of the block in which +the function was called. The allocated storage is released no later than +just before the calling function returns to its caller, but may be released +at the end of the block in which the function was called. + +For example, in the following function the call to @code{g} is unsafe +because when @code{overalign} is non-zero, the space allocated by +@code{__builtin_alloca_with_align} may have been released at the end +of the @code{if} statement in which it was called. + +@smallexample +void f (unsigned n, bool overalign) +@{ + void *p; + if (overalign) + p = __builtin_alloca_with_align (n, 64 /* bits */); + else + p = __builtin_alloc (n); + + g (p, n); // @r{unsafe} +@} +@end smallexample + +Since the @code{__builtin_alloca_with_align} function doesn't validate its +@var{size} argument it is the responsibility of its caller to make sure +the argument doesn't cause it to exceed the stack size limit. +The @code{__builtin_alloca_with_align} function is provided to make +it possible to allocate on the stack overaligned arrays of bytes with +an upper bound that may be computed at run time. Since C99 +Variable Length Arrays offer the same functionality under +a portable, more convenient, and safer interface they are recommended +instead, in both C99 and C++ programs where GCC provides them as +an extension. @xref{Variable Length}, for details. + +@enddefbuiltin + +@defbuiltin{{void *} __builtin_alloca_with_align_and_max (size_t @var{size}, size_t @var{alignment}, size_t @var{max_size})} +Similar to @code{__builtin_alloca_with_align} but takes an extra argument +specifying an upper bound for @var{size} in case its value cannot be computed +at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage} +and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer +expression, it has no effect on code generation and no attempt is made to +check its compatibility with @var{size}. + +@enddefbuiltin + +@node Nonlocal Gotos +@section Nonlocal Gotos +@cindex nonlocal gotos + +GCC provides the built-in functions @code{__builtin_setjmp} and +@code{__builtin_longjmp} which are similar to, but not interchangeable +with, the C library functions @code{setjmp} and @code{longjmp}. +The built-in versions are used internally by GCC's libraries +to implement exception handling on some targets. You should use the +standard C library functions declared in @code{<setjmp.h>} in user code +instead of the builtins. + +The built-in versions of these functions use GCC's normal +mechanisms to save and restore registers using the stack on function +entry and exit. The jump buffer argument @var{buf} holds only the +information needed to restore the stack frame, rather than the entire +set of saved register values. + +An important caveat is that GCC arranges to save and restore only +those registers known to the specific architecture variant being +compiled for. This can make @code{__builtin_setjmp} and +@code{__builtin_longjmp} more efficient than their library +counterparts in some cases, but it can also cause incorrect and +mysterious behavior when mixing with code that uses the full register +set. + +You should declare the jump buffer argument @var{buf} to the +built-in functions as: + +@smallexample +#include <stdint.h> +intptr_t @var{buf}[5]; +@end smallexample + +@defbuiltin{{int} __builtin_setjmp (intptr_t *@var{buf})} +This function saves the current stack context in @var{buf}. +@code{__builtin_setjmp} returns 0 when returning directly, +and 1 when returning from @code{__builtin_longjmp} using the same +@var{buf}. +@enddefbuiltin + +@defbuiltin{{void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})} +This function restores the stack context in @var{buf}, +saved by a previous call to @code{__builtin_setjmp}. After +@code{__builtin_longjmp} is finished, the program resumes execution as +if the matching @code{__builtin_setjmp} returns the value @var{val}, +which must be 1. + +Because @code{__builtin_longjmp} depends on the function return +mechanism to restore the stack context, it cannot be called +from the same function calling @code{__builtin_setjmp} to +initialize @var{buf}. It can only be called from a function called +(directly or indirectly) from the function calling @code{__builtin_setjmp}. +@enddefbuiltin + +@node Constructing Calls +@section Constructing Function Calls +@cindex constructing calls +@cindex forwarding calls + +Using the built-in functions described below, you can record +the arguments a function received, and call another function +with the same arguments, without knowing the number or types +of the arguments. + +You can also record the return value of that function call, +and later return that value, without knowing what data type +the function tried to return (as long as your caller expects +that data type). + +However, these built-in functions may interact badly with some +sophisticated features or other extensions of the language. It +is, therefore, not recommended to use them outside very simple +functions acting as mere forwarders for their arguments. + +@defbuiltin{{void *} __builtin_apply_args ()} +This built-in function returns a pointer to data +describing how to perform a call with the same arguments as are passed +to the current function. + +The function saves the arg pointer register, structure value address, +and all registers that might be used to pass arguments to a function +into a block of memory allocated on the stack. Then it returns the +address of that block. +@enddefbuiltin + +@defbuiltin{{void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})} +This built-in function invokes @var{function} +with a copy of the parameters described by @var{arguments} +and @var{size}. + +The value of @var{arguments} should be the value returned by +@code{__builtin_apply_args}. The argument @var{size} specifies the size +of the stack argument data, in bytes. + +This function returns a pointer to data describing +how to return whatever value is returned by @var{function}. The data +is saved in a block of memory allocated on the stack. + +It is not always simple to compute the proper value for @var{size}. The +value is used by @code{__builtin_apply} to compute the amount of data +that should be pushed on the stack and copied from the incoming argument +area. +@enddefbuiltin + +@defbuiltin{{void} __builtin_return (void *@var{result})} +This built-in function returns the value described by @var{result} from +the containing function. You should specify, for @var{result}, a value +returned by @code{__builtin_apply}. +@enddefbuiltin + +@defbuiltin{{} __builtin_va_arg_pack ()} +This built-in function represents all anonymous arguments of an inline +function. It can be used only in inline functions that are always +inlined, never compiled as a separate function, such as those using +@code{__attribute__ ((__always_inline__))} or +@code{__attribute__ ((__gnu_inline__))} extern inline functions. +It must be only passed as last argument to some other function +with variable arguments. This is useful for writing small wrapper +inlines for variable argument functions, when using preprocessor +macros is undesirable. For example: +@smallexample +extern int myprintf (FILE *f, const char *format, ...); +extern inline __attribute__ ((__gnu_inline__)) int +myprintf (FILE *f, const char *format, ...) +@{ + int r = fprintf (f, "myprintf: "); + if (r < 0) + return r; + int s = fprintf (f, format, __builtin_va_arg_pack ()); + if (s < 0) + return s; + return r + s; +@} +@end smallexample +@enddefbuiltin + +@defbuiltin{int __builtin_va_arg_pack_len ()} +This built-in function returns the number of anonymous arguments of +an inline function. It can be used only in inline functions that +are always inlined, never compiled as a separate function, such +as those using @code{__attribute__ ((__always_inline__))} or +@code{__attribute__ ((__gnu_inline__))} extern inline functions. +For example following does link- or run-time checking of open +arguments for optimized code: +@smallexample +#ifdef __OPTIMIZE__ +extern inline __attribute__((__gnu_inline__)) int +myopen (const char *path, int oflag, ...) +@{ + if (__builtin_va_arg_pack_len () > 1) + warn_open_too_many_arguments (); + + if (__builtin_constant_p (oflag)) + @{ + if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1) + @{ + warn_open_missing_mode (); + return __open_2 (path, oflag); + @} + return open (path, oflag, __builtin_va_arg_pack ()); + @} + + if (__builtin_va_arg_pack_len () < 1) + return __open_2 (path, oflag); + + return open (path, oflag, __builtin_va_arg_pack ()); +@} +#endif +@end smallexample +@enddefbuiltin + +@defbuiltin{@var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})} + +The @var{call_exp} expression must be a function call, and the +@var{pointer_exp} expression must be a pointer. The @var{pointer_exp} +is passed to the function call in the target's static chain location. +The result of builtin is the result of the function call. + +@emph{Note:} This builtin is only available for C@. +This builtin can be used to call Go closures from C. + +@enddefbuiltin + @node Return Address @section Getting the Return or Frame Address of a Function @@ -13626,177 +16448,27 @@ x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@}); @c but GCC does not accept it for unions of vector types (PR 88955). @end smallexample -@node Offsetof -@section Support for @code{offsetof} -@findex __builtin_offsetof - -GCC implements for both C and C++ a syntactic extension to implement -the @code{offsetof} macro. - -@smallexample -primary: - "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" - -offsetof_member_designator: - @code{identifier} - | offsetof_member_designator "." @code{identifier} - | offsetof_member_designator "[" @code{expr} "]" -@end smallexample - -This extension is sufficient such that - -@smallexample -#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) -@end smallexample - -@noindent -is a suitable definition of the @code{offsetof} macro. In C++, @var{type} -may be dependent. In either case, @var{member} may consist of a single -identifier, or a sequence of member accesses and array references. - -@node __sync Builtins -@section Legacy @code{__sync} Built-in Functions for Atomic Memory Access - -The following built-in functions -are intended to be compatible with those described -in the @cite{Intel Itanium Processor-specific Application Binary Interface}, -section 7.4. As such, they depart from normal GCC practice by not using -the @samp{__builtin_} prefix and also by being overloaded so that they -work on multiple types. - -The definition given in the Intel documentation allows only for the use of -the types @code{int}, @code{long}, @code{long long} or their unsigned -counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in -size other than the C type @code{_Bool} or the C++ type @code{bool}. -Operations on pointer arguments are performed as if the operands were -of the @code{uintptr_t} type. That is, they are not scaled by the size -of the type to which the pointer points. - -These functions are implemented in terms of the @samp{__atomic} -builtins (@pxref{__atomic Builtins}). They should not be used for new -code which should use the @samp{__atomic} builtins instead. - -Not all operations are supported by all target processors. If a particular -operation cannot be implemented on the target processor, a call to an -external function is generated. The external function carries the same name -as the built-in version, with an additional suffix -@samp{_@var{n}} where @var{n} is the size of the data type. - -In most cases, these built-in functions are considered a @dfn{full barrier}. -That is, -no memory operand is moved across the operation, either forward or -backward. Further, instructions are issued as necessary to prevent the -processor from speculating loads across the operation and from queuing stores -after the operation. - -All of the routines are described in the Intel documentation to take -``an optional list of variables protected by the memory barrier''. It's -not clear what is meant by that; it could mean that @emph{only} the -listed variables are protected, or it could mean a list of additional -variables to be protected. The list is ignored by GCC which treats it as -empty. GCC interprets an empty list as meaning that all globally -accessible variables should be protected. - -@defbuiltin{@var{type} __sync_fetch_and_add (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_fetch_and_sub (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_fetch_and_or (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_fetch_and_and (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_fetch_and_xor (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_fetch_and_nand (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -These built-in functions perform the operation suggested by the name, and -returns the value that had previously been in memory. That is, operations -on integer operands have the following semantics. Operations on pointer -arguments are performed as if the operands were of the @code{uintptr_t} -type. That is, they are not scaled by the size of the type to which -the pointer points. - -@smallexample -@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} -@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand -@end smallexample - -The object pointed to by the first argument must be of integer or pointer -type. It must not be a boolean type. - -@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} -as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. -@enddefbuiltin - -@defbuiltin{@var{type} __sync_add_and_fetch (@var{type} *@var{ptr}, @ - @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_sub_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_or_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_and_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_xor_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -@defbuiltinx{@var{type} __sync_nand_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -These built-in functions perform the operation suggested by the name, and -return the new value. That is, operations on integer operands have -the following semantics. Operations on pointer operands are performed as -if the operand's type were @code{uintptr_t}. - -@smallexample -@{ *ptr @var{op}= value; return *ptr; @} -@{ *ptr = ~(*ptr & value); return *ptr; @} // nand -@end smallexample - -The same constraints on arguments apply as for the corresponding -@code{__sync_op_and_fetch} built-in functions. - -@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} -as @code{*ptr = ~(*ptr & value)} instead of -@code{*ptr = ~*ptr & value}. -@enddefbuiltin - -@defbuiltin{bool __sync_bool_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)} -@defbuiltinx{@var{type} __sync_val_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)} -These built-in functions perform an atomic compare and swap. -That is, if the current -value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into -@code{*@var{ptr}}. - -The ``bool'' version returns @code{true} if the comparison is successful and -@var{newval} is written. The ``val'' version returns the contents -of @code{*@var{ptr}} before the operation. -@enddefbuiltin - -@defbuiltin{void __sync_synchronize (...)} -This built-in function issues a full memory barrier. -@enddefbuiltin - -@defbuiltin{@var{type} __sync_lock_test_and_set (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} -This built-in function, as described by Intel, is not a traditional test-and-set -operation, but rather an atomic exchange operation. It writes @var{value} -into @code{*@var{ptr}}, and returns the previous contents of -@code{*@var{ptr}}. - -Many targets have only minimal support for such locks, and do not support -a full exchange operation. In this case, a target may support reduced -functionality here by which the @emph{only} valid value to store is the -immediate constant 1. The exact value actually stored in @code{*@var{ptr}} -is implementation defined. +@node Atomic Memory Access +@section Builtins for Atomic Memory Access +@cindex atomic memory access builtins +@cindex builtins for atomic memory access -This built-in function is not a full barrier, -but rather an @dfn{acquire barrier}. -This means that references after the operation cannot move to (or be -speculated to) before the operation, but previous memory stores may not -be globally visible yet, and previous memory loads may not yet be -satisfied. -@enddefbuiltin +GCC supports two sets of builtins for atomic memory access primitives. The +@code{__atomic} builtins provide the underlying support for the C++11 +atomic operations library, and are the currently-recommended interface when +the C++11 library functions cannot be used directly. +The @code{__sync} builtins implement the specification from the Intel IA64 +pSABI and are supported primarily for use in legacy code. -@defbuiltin{void __sync_lock_release (@var{type} *@var{ptr}, ...)} -This built-in function releases the lock acquired by -@code{__sync_lock_test_and_set}. -Normally this means writing the constant 0 to @code{*@var{ptr}}. - -This built-in function is not a full barrier, -but rather a @dfn{release barrier}. -This means that all previous memory stores are globally visible, and all -previous memory loads have been satisfied, but following memory reads -are not prevented from being speculated to before the barrier. -@enddefbuiltin +@menu +* __atomic Builtins:: Atomic built-in functions with memory model. +* __sync Builtins:: Legacy built-in functions for atomic memory access. +@end menu @node __atomic Builtins -@section Built-in Functions for Memory Model Aware Atomic Operations +@subsection Built-in Functions for Memory Model Aware Atomic Operations +@cindex C++11 memory model +@cindex __atomic builtins The following built-in functions approximately match the requirements for the C++11 memory model. They are all @@ -13900,6 +16572,39 @@ reserved for the memory order. The remainder of the signed int is reserved for target use and should be 0. Use of the predefined atomic values ensures proper usage. +@anchor{x86 specific memory model extensions for transactional memory} +@cindex x86 transactional memory extensions +@cindex transactional memory extensions for x86 +The x86 architecture supports additional memory ordering modifiers +to mark critical sections for hardware lock elision. +These modifiers can be bitwise or'ed with a standard memory order to +atomic intrinsics. + +@table @code +@item __ATOMIC_HLE_ACQUIRE +Start lock elision on a lock variable. +Memory order must be @code{__ATOMIC_ACQUIRE} or stronger. +@item __ATOMIC_HLE_RELEASE +End lock elision on a lock variable. +Memory order must be @code{__ATOMIC_RELEASE} or stronger. +@end table + +When a lock acquire fails, it is required for good performance to abort +the transaction quickly. This can be done with a @code{_mm_pause}. + +@smallexample +#include <immintrin.h> // For _mm_pause + +int lockvar; + +/* Acquire lock with lock elision */ +while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) + _mm_pause(); /* Abort failed transaction */ +... +/* Free lock with lock elision */ +__atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); +@end smallexample + @defbuiltin{@var{type} __atomic_load_n (@var{type} *@var{ptr}, int @var{memorder})} This built-in function implements an atomic load operation. It returns the contents of @code{*@var{ptr}}. @@ -14097,186 +16802,150 @@ alignment. A value of 0 indicates typical alignment should be used. The compiler may also ignore this parameter. @enddefbuiltin -@node Integer Overflow Builtins -@section Built-in Functions to Perform Arithmetic with Overflow Checking - -The following built-in functions allow performing simple arithmetic operations -together with checking whether the operations overflowed. -@defbuiltin{bool __builtin_add_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} -@defbuiltinx{bool __builtin_sadd_overflow (int @var{a}, int @var{b}, int *@var{res})} -@defbuiltinx{bool __builtin_saddl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} -@defbuiltinx{bool __builtin_saddll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} -@defbuiltinx{bool __builtin_uadd_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} -@defbuiltinx{bool __builtin_uaddl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} -@defbuiltinx{bool __builtin_uaddll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} - -These built-in functions promote the first two operands into infinite precision signed -type and perform addition on those promoted operands. The result is then -cast to the type the third pointer argument points to and stored there. -If the stored result is equal to the infinite precision result, the built-in -functions return @code{false}, otherwise they return @code{true}. As the addition is -performed in infinite signed precision, these built-in functions have fully defined -behavior for all argument values. - -The first built-in function allows arbitrary integral types for operands and -the result type must be pointer to some integral type other than enumerated or -boolean type, the rest of the built-in functions have explicit integer types. - -The compiler will attempt to use hardware instructions to implement -these built-in functions where possible, like conditional jump on overflow -after addition, conditional jump on carry etc. - -@enddefbuiltin - -@defbuiltin{bool __builtin_sub_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} -@defbuiltinx{bool __builtin_ssub_overflow (int @var{a}, int @var{b}, int *@var{res})} -@defbuiltinx{bool __builtin_ssubl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} -@defbuiltinx{bool __builtin_ssubll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} -@defbuiltinx{bool __builtin_usub_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} -@defbuiltinx{bool __builtin_usubl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} -@defbuiltinx{bool __builtin_usubll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} - -These built-in functions are similar to the add overflow checking built-in -functions above, except they perform subtraction, subtract the second argument -from the first one, instead of addition. - -@enddefbuiltin - -@defbuiltin{bool __builtin_mul_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} -@defbuiltinx{bool __builtin_smul_overflow (int @var{a}, int @var{b}, int *@var{res})} -@defbuiltinx{bool __builtin_smull_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} -@defbuiltinx{bool __builtin_smulll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} -@defbuiltinx{bool __builtin_umul_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} -@defbuiltinx{bool __builtin_umull_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} -@defbuiltinx{bool __builtin_umulll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} +@node __sync Builtins +@subsection Legacy @code{__sync} Built-in Functions for Atomic Memory Access +@cindex legacy builtins for atomic memory access +@cindex IA64 atomic memory access builtins +@cindex __sync builtins -These built-in functions are similar to the add overflow checking built-in -functions above, except they perform multiplication, instead of addition. +The following built-in functions +are intended to be compatible with those described +in the @cite{Intel Itanium Processor-specific Application Binary Interface}, +section 7.4. As such, they depart from normal GCC practice by not using +the @samp{__builtin_} prefix and also by being overloaded so that they +work on multiple types. -@enddefbuiltin +The definition given in the Intel documentation allows only for the use of +the types @code{int}, @code{long}, @code{long long} or their unsigned +counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in +size other than the C type @code{_Bool} or the C++ type @code{bool}. +Operations on pointer arguments are performed as if the operands were +of the @code{uintptr_t} type. That is, they are not scaled by the size +of the type to which the pointer points. -The following built-in functions allow checking if simple arithmetic operation -would overflow. +These functions are implemented in terms of the @samp{__atomic} +builtins (@pxref{__atomic Builtins}). They should not be used for new +code which should use the @samp{__atomic} builtins instead. -@defbuiltin{bool __builtin_add_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} -@defbuiltinx{bool __builtin_sub_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} -@defbuiltinx{bool __builtin_mul_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} +Not all operations are supported by all target processors. If a particular +operation cannot be implemented on the target processor, a call to an +external function is generated. The external function carries the same name +as the built-in version, with an additional suffix +@samp{_@var{n}} where @var{n} is the size of the data type. -These built-in functions are similar to @code{__builtin_add_overflow}, -@code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that -they don't store the result of the arithmetic operation anywhere and the -last argument is not a pointer, but some expression with integral type other -than enumerated or boolean type. +In most cases, these built-in functions are considered a @dfn{full barrier}. +That is, +no memory operand is moved across the operation, either forward or +backward. Further, instructions are issued as necessary to prevent the +processor from speculating loads across the operation and from queuing stores +after the operation. -The built-in functions promote the first two operands into infinite precision signed type -and perform addition on those promoted operands. The result is then -cast to the type of the third argument. If the cast result is equal to the infinite -precision result, the built-in functions return @code{false}, otherwise they return @code{true}. -The value of the third argument is ignored, just the side effects in the third argument -are evaluated, and no integral argument promotions are performed on the last argument. -If the third argument is a bit-field, the type used for the result cast has the -precision and signedness of the given bit-field, rather than precision and signedness -of the underlying type. +All of the routines are described in the Intel documentation to take +``an optional list of variables protected by the memory barrier''. It's +not clear what is meant by that; it could mean that @emph{only} the +listed variables are protected, or it could mean a list of additional +variables to be protected. The list is ignored by GCC which treats it as +empty. GCC interprets an empty list as meaning that all globally +accessible variables should be protected. -For example, the following macro can be used to portably check, at -compile-time, whether or not adding two constant integers will overflow, -and perform the addition only when it is known to be safe and not to trigger -a @option{-Woverflow} warning. +@defbuiltin{@var{type} __sync_fetch_and_add (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_fetch_and_sub (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_fetch_and_or (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_fetch_and_and (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_fetch_and_xor (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_fetch_and_nand (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +These built-in functions perform the operation suggested by the name, and +returns the value that had previously been in memory. That is, operations +on integer operands have the following semantics. Operations on pointer +arguments are performed as if the operands were of the @code{uintptr_t} +type. That is, they are not scaled by the size of the type to which +the pointer points. @smallexample -#define INT_ADD_OVERFLOW_P(a, b) \ - __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0) - -enum @{ - A = INT_MAX, B = 3, - C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B, - D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0) -@}; +@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} +@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand @end smallexample -The compiler will attempt to use hardware instructions to implement -these built-in functions where possible, like conditional jump on overflow -after addition, conditional jump on carry etc. - +The object pointed to by the first argument must be of integer or pointer +type. It must not be a boolean type. + +@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} +as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. @enddefbuiltin -@defbuiltin{{unsigned int} __builtin_addc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})} -@defbuiltinx{{unsigned long int} __builtin_addcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})} -@defbuiltinx{{unsigned long long int} __builtin_addcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})} +@defbuiltin{@var{type} __sync_add_and_fetch (@var{type} *@var{ptr}, @ + @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_sub_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_or_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_and_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_xor_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_nand_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +These built-in functions perform the operation suggested by the name, and +return the new value. That is, operations on integer operands have +the following semantics. Operations on pointer operands are performed as +if the operand's type were @code{uintptr_t}. -These built-in functions are equivalent to: @smallexample - (@{ __typeof__ (@var{a}) s; \ - __typeof__ (@var{a}) c1 = __builtin_add_overflow (@var{a}, @var{b}, &s); \ - __typeof__ (@var{a}) c2 = __builtin_add_overflow (s, @var{carry_in}, &s); \ - *(@var{carry_out}) = c1 | c2; \ - s; @}) +@{ *ptr @var{op}= value; return *ptr; @} +@{ *ptr = ~(*ptr & value); return *ptr; @} // nand @end smallexample -i.e.@: they add 3 unsigned values, set what the last argument -points to to 1 if any of the two additions overflowed (otherwise 0) -and return the sum of those 3 unsigned values. Note, while all -the first 3 arguments can have arbitrary values, better code will be -emitted if one of them (preferably the third one) has only values -0 or 1 (i.e.@: carry-in). +The same constraints on arguments apply as for the corresponding +@code{__sync_op_and_fetch} built-in functions. +@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} +as @code{*ptr = ~(*ptr & value)} instead of +@code{*ptr = ~*ptr & value}. @enddefbuiltin -@defbuiltin{{unsigned int} __builtin_subc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})} -@defbuiltinx{{unsigned long int} __builtin_subcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})} -@defbuiltinx{{unsigned long long int} __builtin_subcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})} - -These built-in functions are equivalent to: -@smallexample - (@{ __typeof__ (@var{a}) s; \ - __typeof__ (@var{a}) c1 = __builtin_sub_overflow (@var{a}, @var{b}, &s); \ - __typeof__ (@var{a}) c2 = __builtin_sub_overflow (s, @var{carry_in}, &s); \ - *(@var{carry_out}) = c1 | c2; \ - s; @}) -@end smallexample - -i.e.@: they subtract 2 unsigned values from the first unsigned value, -set what the last argument points to to 1 if any of the two subtractions -overflowed (otherwise 0) and return the result of the subtractions. -Note, while all the first 3 arguments can have arbitrary values, better code -will be emitted if one of them (preferrably the third one) has only values -0 or 1 (i.e.@: carry-in). +@defbuiltin{bool __sync_bool_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)} +@defbuiltinx{@var{type} __sync_val_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)} +These built-in functions perform an atomic compare and swap. +That is, if the current +value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into +@code{*@var{ptr}}. +The ``bool'' version returns @code{true} if the comparison is successful and +@var{newval} is written. The ``val'' version returns the contents +of @code{*@var{ptr}} before the operation. @enddefbuiltin -@node x86 specific memory model extensions for transactional memory -@section x86-Specific Memory Model Extensions for Transactional Memory - -The x86 architecture supports additional memory ordering flags -to mark critical sections for hardware lock elision. -These must be specified in addition to an existing memory order to -atomic intrinsics. +@defbuiltin{void __sync_synchronize (...)} +This built-in function issues a full memory barrier. +@enddefbuiltin -@table @code -@item __ATOMIC_HLE_ACQUIRE -Start lock elision on a lock variable. -Memory order must be @code{__ATOMIC_ACQUIRE} or stronger. -@item __ATOMIC_HLE_RELEASE -End lock elision on a lock variable. -Memory order must be @code{__ATOMIC_RELEASE} or stronger. -@end table +@defbuiltin{@var{type} __sync_lock_test_and_set (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +This built-in function, as described by Intel, is not a traditional test-and-set +operation, but rather an atomic exchange operation. It writes @var{value} +into @code{*@var{ptr}}, and returns the previous contents of +@code{*@var{ptr}}. -When a lock acquire fails, it is required for good performance to abort -the transaction quickly. This can be done with a @code{_mm_pause}. +Many targets have only minimal support for such locks, and do not support +a full exchange operation. In this case, a target may support reduced +functionality here by which the @emph{only} valid value to store is the +immediate constant 1. The exact value actually stored in @code{*@var{ptr}} +is implementation defined. -@smallexample -#include <immintrin.h> // For _mm_pause +This built-in function is not a full barrier, +but rather an @dfn{acquire barrier}. +This means that references after the operation cannot move to (or be +speculated to) before the operation, but previous memory stores may not +be globally visible yet, and previous memory loads may not yet be +satisfied. +@enddefbuiltin -int lockvar; +@defbuiltin{void __sync_lock_release (@var{type} *@var{ptr}, ...)} +This built-in function releases the lock acquired by +@code{__sync_lock_test_and_set}. +Normally this means writing the constant 0 to @code{*@var{ptr}}. -/* Acquire lock with lock elision */ -while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) - _mm_pause(); /* Abort failed transaction */ -... -/* Free lock with lock elision */ -__atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); -@end smallexample +This built-in function is not a full barrier, +but rather a @dfn{release barrier}. +This means that all previous memory stores are globally visible, and all +previous memory loads have been satisfied, but following memory reads +are not prevented from being speculated to before the barrier. +@enddefbuiltin @node Object Size Checking @section Object Size Checking @@ -14303,7 +16972,7 @@ on various optimization passes enabled with @option{-O2}. However, to a limited extent, they can be used without optimization as well. @defbuiltin{size_t __builtin_object_size (const void * @var{ptr}, int @var{type})} -is a built-in construct that returns a constant number of bytes from +This built-in construct returns a constant number of bytes from @var{ptr} to the end of the object @var{ptr} pointer points to (if known at compile time). To determine the sizes of dynamically allocated objects the function relies on the allocation functions called to obtain @@ -14342,6 +17011,7 @@ assert (__builtin_object_size (q, 1) == sizeof (var.b)); @enddefbuiltin @defbuiltin{{size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})} +This builtin is similar to @code{__builtin_object_size} in that it returns a number of bytes from @var{ptr} to the end of the object @var{ptr} pointer points to, except that the size returned may not be a constant. This results in successful @@ -14439,18 +17109,20 @@ is called and the @var{flag} argument passed to it. @node New/Delete Builtins @section Built-in functions for C++ allocations and deallocations -@findex __builtin_operator_new -@findex __builtin_operator_delete -Calling these C++ built-in functions is similar to calling -@code{::operator new} or @code{::operator delete} with the same arguments, -except that it is an error if the selected @code{::operator new} or -@code{::operator delete} overload is not a replaceable global operator -and for optimization purposes calls to pairs of these functions can be -omitted if access to the allocation is optimized out, or could be replaced -with implementation provided buffer on the stack, or multiple allocation -calls can be merged into a single allocation. In C++ such optimizations -are normally allowed just for calls to such replaceable global operators -from @code{new} and @code{delete} expressions. +@cindex builtins for C++ @code{new} and @code{delete} operators +@cindex @code{new} and @code{delete} builtins + +GNU C++ provides builtins that are equivalent to calling +@code{::operator new} or @code{::operator delete} with the same arguments. +It is an error if the selected @code{::operator new} or +@code{::operator delete} overload is not a replaceable global operator. +For optimization purposes, calls to pairs of these +builtins can be omitted if access to the allocation is optimized out, +or could be replaced with an implementation-provided buffer on the stack, +or multiple allocation calls can be merged into a single allocation. +In C++ such optimizations are normally allowed just for calls to such +replaceable global operators from @code{new} and @code{delete} +expressions. @smallexample void foo () @{ @@ -14464,672 +17136,26 @@ void foo () @{ @} @end smallexample -@node Other Builtins -@section Other Built-in Functions Provided by GCC -@cindex built-in functions -@findex __builtin_iseqsig -@findex __builtin_isfinite -@findex __builtin_isnormal -@findex __builtin_isgreater -@findex __builtin_isgreaterequal -@findex __builtin_isunordered -@findex __builtin_speculation_safe_value -@findex _Exit -@findex _exit -@findex abort -@findex abs -@findex acos -@findex acosf -@findex acosh -@findex acoshf -@findex acoshl -@findex acosl -@findex alloca -@findex asin -@findex asinf -@findex asinh -@findex asinhf -@findex asinhl -@findex asinl -@findex atan -@findex atan2 -@findex atan2f -@findex atan2l -@findex atanf -@findex atanh -@findex atanhf -@findex atanhl -@findex atanl -@findex bcmp -@findex bzero -@findex cabs -@findex cabsf -@findex cabsl -@findex cacos -@findex cacosf -@findex cacosh -@findex cacoshf -@findex cacoshl -@findex cacosl -@findex calloc -@findex carg -@findex cargf -@findex cargl -@findex casin -@findex casinf -@findex casinh -@findex casinhf -@findex casinhl -@findex casinl -@findex catan -@findex catanf -@findex catanh -@findex catanhf -@findex catanhl -@findex catanl -@findex cbrt -@findex cbrtf -@findex cbrtl -@findex ccos -@findex ccosf -@findex ccosh -@findex ccoshf -@findex ccoshl -@findex ccosl -@findex ceil -@findex ceilf -@findex ceill -@findex cexp -@findex cexpf -@findex cexpl -@findex cimag -@findex cimagf -@findex cimagl -@findex clog -@findex clogf -@findex clogl -@findex clog10 -@findex clog10f -@findex clog10l -@findex conj -@findex conjf -@findex conjl -@findex copysign -@findex copysignf -@findex copysignl -@findex cos -@findex cosf -@findex cosh -@findex coshf -@findex coshl -@findex cosl -@findex cpow -@findex cpowf -@findex cpowl -@findex cproj -@findex cprojf -@findex cprojl -@findex creal -@findex crealf -@findex creall -@findex csin -@findex csinf -@findex csinh -@findex csinhf -@findex csinhl -@findex csinl -@findex csqrt -@findex csqrtf -@findex csqrtl -@findex ctan -@findex ctanf -@findex ctanh -@findex ctanhf -@findex ctanhl -@findex ctanl -@findex dcgettext -@findex dgettext -@findex drem -@findex dremf -@findex dreml -@findex erf -@findex erfc -@findex erfcf -@findex erfcl -@findex erff -@findex erfl -@findex exit -@findex exp -@findex exp10 -@findex exp10f -@findex exp10l -@findex exp2 -@findex exp2f -@findex exp2l -@findex expf -@findex expl -@findex expm1 -@findex expm1f -@findex expm1l -@findex fabs -@findex fabsf -@findex fabsl -@findex fdim -@findex fdimf -@findex fdiml -@findex ffs -@findex floor -@findex floorf -@findex floorl -@findex fma -@findex fmaf -@findex fmal -@findex fmax -@findex fmaxf -@findex fmaxl -@findex fmin -@findex fminf -@findex fminl -@findex fmod -@findex fmodf -@findex fmodl -@findex fprintf -@findex fprintf_unlocked -@findex fputs -@findex fputs_unlocked -@findex free -@findex frexp -@findex frexpf -@findex frexpl -@findex fscanf -@findex gamma -@findex gammaf -@findex gammal -@findex gamma_r -@findex gammaf_r -@findex gammal_r -@findex gettext -@findex hypot -@findex hypotf -@findex hypotl -@findex ilogb -@findex ilogbf -@findex ilogbl -@findex imaxabs -@findex index -@findex isalnum -@findex isalpha -@findex isascii -@findex isblank -@findex iscntrl -@findex isdigit -@findex isgraph -@findex islower -@findex isprint -@findex ispunct -@findex isspace -@findex isupper -@findex iswalnum -@findex iswalpha -@findex iswblank -@findex iswcntrl -@findex iswdigit -@findex iswgraph -@findex iswlower -@findex iswprint -@findex iswpunct -@findex iswspace -@findex iswupper -@findex iswxdigit -@findex isxdigit -@findex j0 -@findex j0f -@findex j0l -@findex j1 -@findex j1f -@findex j1l -@findex jn -@findex jnf -@findex jnl -@findex labs -@findex ldexp -@findex ldexpf -@findex ldexpl -@findex lgamma -@findex lgammaf -@findex lgammal -@findex lgamma_r -@findex lgammaf_r -@findex lgammal_r -@findex llabs -@findex llrint -@findex llrintf -@findex llrintl -@findex llround -@findex llroundf -@findex llroundl -@findex log -@findex log10 -@findex log10f -@findex log10l -@findex log1p -@findex log1pf -@findex log1pl -@findex log2 -@findex log2f -@findex log2l -@findex logb -@findex logbf -@findex logbl -@findex logf -@findex logl -@findex lrint -@findex lrintf -@findex lrintl -@findex lround -@findex lroundf -@findex lroundl -@findex malloc -@findex memchr -@findex memcmp -@findex memcpy -@findex mempcpy -@findex memset -@findex modf -@findex modff -@findex modfl -@findex nearbyint -@findex nearbyintf -@findex nearbyintl -@findex nextafter -@findex nextafterf -@findex nextafterl -@findex nexttoward -@findex nexttowardf -@findex nexttowardl -@findex pow -@findex pow10 -@findex pow10f -@findex pow10l -@findex powf -@findex powl -@findex printf -@findex printf_unlocked -@findex putchar -@findex puts -@findex realloc -@findex remainder -@findex remainderf -@findex remainderl -@findex remquo -@findex remquof -@findex remquol -@findex rindex -@findex rint -@findex rintf -@findex rintl -@findex round -@findex roundf -@findex roundl -@findex scalb -@findex scalbf -@findex scalbl -@findex scalbln -@findex scalblnf -@findex scalblnf -@findex scalbn -@findex scalbnf -@findex scanfnl -@findex signbit -@findex signbitf -@findex signbitl -@findex signbitd32 -@findex signbitd64 -@findex signbitd128 -@findex significand -@findex significandf -@findex significandl -@findex sin -@findex sincos -@findex sincosf -@findex sincosl -@findex sinf -@findex sinh -@findex sinhf -@findex sinhl -@findex sinl -@findex snprintf -@findex sprintf -@findex sqrt -@findex sqrtf -@findex sqrtl -@findex sscanf -@findex stpcpy -@findex stpncpy -@findex strcasecmp -@findex strcat -@findex strchr -@findex strcmp -@findex strcpy -@findex strcspn -@findex strdup -@findex strfmon -@findex strftime -@findex strlen -@findex strncasecmp -@findex strncat -@findex strncmp -@findex strncpy -@findex strndup -@findex strnlen -@findex strpbrk -@findex strrchr -@findex strspn -@findex strstr -@findex tan -@findex tanf -@findex tanh -@findex tanhf -@findex tanhl -@findex tanl -@findex tgamma -@findex tgammaf -@findex tgammal -@findex toascii -@findex tolower -@findex toupper -@findex towlower -@findex towupper -@findex trunc -@findex truncf -@findex truncl -@findex vfprintf -@findex vfscanf -@findex vprintf -@findex vscanf -@findex vsnprintf -@findex vsprintf -@findex vsscanf -@findex y0 -@findex y0f -@findex y0l -@findex y1 -@findex y1f -@findex y1l -@findex yn -@findex ynf -@findex ynl - -GCC provides a large number of built-in functions other than the ones -mentioned above. Some of these are for internal use in the processing -of exceptions or variable-length argument lists and are not -documented here because they may change from time to time; we do not -recommend general use of these functions. - -The remaining functions are provided for optimization purposes. - -With the exception of built-ins that have library equivalents such as -the standard C library functions discussed below, or that expand to -library calls, GCC built-in functions are always expanded inline and -thus do not have corresponding entry points and their address cannot -be obtained. Attempting to use them in an expression other than -a function call results in a compile-time error. - -@opindex fno-builtin -GCC includes built-in versions of many of the functions in the standard -C library. These functions come in two forms: one whose names start with -the @code{__builtin_} prefix, and the other without. Both forms have the -same type (including prototype), the same address (when their address is -taken), and the same meaning as the C library functions even if you specify -the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these -functions are only optimized in certain cases; if they are not optimized in -a particular case, a call to the library function is emitted. - -@opindex ansi -@opindex std -Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, -@option{-std=c99} or @option{-std=c11}), the functions -@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, -@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, -@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, -@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, -@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, -@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, -@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, -@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, -@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, -@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, -@code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl}, -@code{scalbf}, @code{scalbl}, @code{scalb}, -@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, -@code{signbitd64}, @code{signbitd128}, @code{significandf}, -@code{significandl}, @code{significand}, @code{sincosf}, -@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, -@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, -@code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l}, -@code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and -@code{yn} -may be handled as built-in functions. -All these functions have corresponding versions -prefixed with @code{__builtin_}, which may be used even in strict C90 -mode. - -The ISO C99 functions -@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, -@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, -@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, -@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, -@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, -@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, -@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, -@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, -@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, -@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, -@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, -@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, -@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, -@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, -@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, -@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, -@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, -@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, -@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, -@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, -@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, -@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, -@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, -@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, -@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, -@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, -@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, -@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, -@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, -@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, -@code{nextafterf}, @code{nextafterl}, @code{nextafter}, -@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, -@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, -@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, -@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, -@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, -@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, -@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, -@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} -are handled as built-in functions -except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). - -There are also built-in versions of the ISO C99 functions -@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, -@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, -@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, -@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, -@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, -@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, -@code{modfl}, @code{modff}, @code{powf}, @code{powl}, @code{sinf}, -@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, -@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} -that are recognized in any mode since ISO C90 reserves these names for -the purpose to which ISO C99 puts them. All these functions have -corresponding versions prefixed with @code{__builtin_}. - -There are also built-in functions @code{__builtin_fabsf@var{n}}, -@code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and -@code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3 -functions @code{fabsf@var{n}}, @code{fabsf@var{n}x}, -@code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported -types @code{_Float@var{n}} and @code{_Float@var{n}x}. - -There are also GNU extension functions @code{clog10}, @code{clog10f} and -@code{clog10l} which names are reserved by ISO C99 for future use. -All these functions have versions prefixed with @code{__builtin_}. - -The ISO C94 functions -@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, -@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, -@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and -@code{towupper} -are handled as built-in functions -except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). - -The ISO C90 functions -@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, -@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, -@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, -@code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf}, -@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, -@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, -@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, -@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, -@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, -@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, -@code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin}, -@code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, -@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, -@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, -@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, -@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} -are all recognized as built-in functions unless -@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} -is specified for an individual function). All of these functions have -corresponding versions prefixed with @code{__builtin_}. - -GCC provides built-in versions of the ISO C99 floating-point comparison -macros that avoid raising exceptions for unordered operands. They have -the same names as the standard macros ( @code{isgreater}, -@code{isgreaterequal}, @code{isless}, @code{islessequal}, -@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} -prefixed. We intend for a library implementor to be able to simply -@code{#define} each standard macro to its built-in equivalent. -In the same fashion, GCC provides @code{fpclassify}, @code{iseqsig}, -@code{isfinite}, @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins -used with @code{__builtin_} prefixed. The @code{isinf} and @code{isnan} -built-in functions appear both with and without the @code{__builtin_} prefix. -With @code{-ffinite-math-only} option the @code{isinf} and @code{isnan} -built-in functions will always return 0. - -GCC provides built-in versions of the ISO C99 floating-point rounding and -exceptions handling functions @code{fegetround}, @code{feclearexcept} and -@code{feraiseexcept}. They may not be available for all targets, and because -they need close interaction with libc internal values, they may not be available -for all target libcs, but in all cases they will gracefully fallback to libc -calls. These built-in functions appear both with and without the -@code{__builtin_} prefix. - -@defbuiltin{{void *} __builtin_alloca (size_t @var{size})} -The @code{__builtin_alloca} function must be called at block scope. -The function allocates an object @var{size} bytes large on the stack -of the calling function. The object is aligned on the default stack -alignment boundary for the target determined by the -@code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca} -function returns a pointer to the first byte of the allocated object. -The lifetime of the allocated object ends just before the calling -function returns to its caller. This is so even when -@code{__builtin_alloca} is called within a nested block. - -For example, the following function allocates eight objects of @code{n} -bytes each on the stack, storing a pointer to each in consecutive elements -of the array @code{a}. It then passes the array to function @code{g} -which can safely use the storage pointed to by each of the array elements. - -@smallexample -void f (unsigned n) -@{ - void *a [8]; - for (int i = 0; i != 8; ++i) - a [i] = __builtin_alloca (n); - - g (a, n); // @r{safe} -@} -@end smallexample - -Since the @code{__builtin_alloca} function doesn't validate its argument -it is the responsibility of its caller to make sure the argument doesn't -cause it to exceed the stack size limit. -The @code{__builtin_alloca} function is provided to make it possible to -allocate on the stack arrays of bytes with an upper bound that may be -computed at run time. Since C99 Variable Length Arrays offer -similar functionality under a portable, more convenient, and safer -interface they are recommended instead, in both C99 and C++ programs -where GCC provides them as an extension. -@xref{Variable Length}, for details. +These built-ins are only available in C++. +@defbuiltin{{void *} __builtin_operator_new (std::size_t @var{size}, ...)} +This is the built-in form of @code{operator new}. It accepts the same +argument forms as a ``usual allocation function'', as described in the +C++ standard. @enddefbuiltin -@defbuiltin{{void *} __builtin_alloca_with_align (size_t @var{size}, size_t @var{alignment})} -The @code{__builtin_alloca_with_align} function must be called at block -scope. The function allocates an object @var{size} bytes large on -the stack of the calling function. The allocated object is aligned on -the boundary specified by the argument @var{alignment} whose unit is given -in bits (not bytes). The @var{size} argument must be positive and not -exceed the stack size limit. The @var{alignment} argument must be a constant -integer expression that evaluates to a power of 2 greater than or equal to -@code{CHAR_BIT} and less than some unspecified maximum. Invocations -with other values are rejected with an error indicating the valid bounds. -The function returns a pointer to the first byte of the allocated object. -The lifetime of the allocated object ends at the end of the block in which -the function was called. The allocated storage is released no later than -just before the calling function returns to its caller, but may be released -at the end of the block in which the function was called. - -For example, in the following function the call to @code{g} is unsafe -because when @code{overalign} is non-zero, the space allocated by -@code{__builtin_alloca_with_align} may have been released at the end -of the @code{if} statement in which it was called. - -@smallexample -void f (unsigned n, bool overalign) -@{ - void *p; - if (overalign) - p = __builtin_alloca_with_align (n, 64 /* bits */); - else - p = __builtin_alloc (n); - - g (p, n); // @r{unsafe} -@} -@end smallexample +@defbuiltin{void __builtin_operator_delete (void * @var{ptr}, ...)} +This is the built-in form of @code{operator delete}. It accepts the same +argument forms as a ``usual deallocation function'', as described in the +C++ standard. +@enddefbuiltin -Since the @code{__builtin_alloca_with_align} function doesn't validate its -@var{size} argument it is the responsibility of its caller to make sure -the argument doesn't cause it to exceed the stack size limit. -The @code{__builtin_alloca_with_align} function is provided to make -it possible to allocate on the stack overaligned arrays of bytes with -an upper bound that may be computed at run time. Since C99 -Variable Length Arrays offer the same functionality under -a portable, more convenient, and safer interface they are recommended -instead, in both C99 and C++ programs where GCC provides them as -an extension. @xref{Variable Length}, for details. -@enddefbuiltin +@node Other Builtins +@section Other Built-in Functions Provided by GCC -@defbuiltin{{void *} __builtin_alloca_with_align_and_max (size_t @var{size}, size_t @var{alignment}, size_t @var{max_size})} -Similar to @code{__builtin_alloca_with_align} but takes an extra argument -specifying an upper bound for @var{size} in case its value cannot be computed -at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage} -and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer -expression, it has no effect on code generation and no attempt is made to -check its compatibility with @var{size}. +This section documents miscellaneous built-in functions available in GCC. -@enddefbuiltin @defbuiltin{bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})} The @code{__builtin_has_attribute} function evaluates to an integer constant @@ -15315,18 +17341,6 @@ depending on the arguments' types. For example: @enddefbuiltin -@defbuiltin{@var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})} - -The @var{call_exp} expression must be a function call, and the -@var{pointer_exp} expression must be a pointer. The @var{pointer_exp} -is passed to the function call in the target's static chain location. -The result of builtin is the result of the function call. - -@emph{Note:} This builtin is only available for C@. -This builtin can be used to call Go closures from C. - -@enddefbuiltin - @defbuiltin{@var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})} You can use the built-in function @code{__builtin_choose_expr} to @@ -15859,17 +17873,6 @@ is evaluated if it includes side effects but no other code is generated and GCC does not issue a warning. @enddefbuiltin -@defbuiltin{{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})} -Returns a constant size estimate of an object pointed to by @var{ptr}. -@xref{Object Size Checking}, for a detailed description of the function. -@enddefbuiltin - -@defbuiltin{{size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})} -Similar to @code{__builtin_object_size} except that the return value -need not be a constant. @xref{Object Size Checking}, for a detailed -description of the function. -@enddefbuiltin - @defbuiltin{int __builtin_classify_type (@var{arg})} @defbuiltinx{int __builtin_classify_type (@var{type})} The @code{__builtin_classify_type} returns a small integer with a category @@ -15894,490 +17897,6 @@ to pointer. The last two comparisons will be true as they classify pointers in the second case and arrays in the last case. @enddefbuiltin -@defbuiltin{double __builtin_huge_val (void)} -Returns a positive infinity, if supported by the floating-point format, -else @code{DBL_MAX}. This function is suitable for implementing the -ISO C macro @code{HUGE_VAL}. -@enddefbuiltin - -@defbuiltin{float __builtin_huge_valf (void)} -Similar to @code{__builtin_huge_val}, except the return type is @code{float}. -@enddefbuiltin - -@defbuiltin{{long double} __builtin_huge_vall (void)} -Similar to @code{__builtin_huge_val}, except the return -type is @code{long double}. -@enddefbuiltin - -@defbuiltin{_Float@var{n} __builtin_huge_valf@var{n} (void)} -Similar to @code{__builtin_huge_val}, except the return type is -@code{_Float@var{n}}. -@enddefbuiltin - -@defbuiltin{_Float@var{n}x __builtin_huge_valf@var{n}x (void)} -Similar to @code{__builtin_huge_val}, except the return type is -@code{_Float@var{n}x}. -@enddefbuiltin - -@defbuiltin{int __builtin_fpclassify (int, int, int, int, int, ...)} -This built-in implements the C99 fpclassify functionality. The first -five int arguments should be the target library's notion of the -possible FP classes and are used for return values. They must be -constant values and they must appear in this order: @code{FP_NAN}, -@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and -@code{FP_ZERO}. The ellipsis is for exactly one floating-point value -to classify. GCC treats the last argument as type-generic, which -means it does not do default promotion from float to double. -@enddefbuiltin - -@defbuiltin{double __builtin_inf (void)} -Similar to @code{__builtin_huge_val}, except a warning is generated -if the target floating-point format does not support infinities. -@enddefbuiltin - -@defbuiltin{_Decimal32 __builtin_infd32 (void)} -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. -@enddefbuiltin - -@defbuiltin{_Decimal64 __builtin_infd64 (void)} -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. -@enddefbuiltin - -@defbuiltin{_Decimal128 __builtin_infd128 (void)} -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. -@enddefbuiltin - -@defbuiltin{float __builtin_inff (void)} -Similar to @code{__builtin_inf}, except the return type is @code{float}. -This function is suitable for implementing the ISO C99 macro @code{INFINITY}. -@enddefbuiltin - -@defbuiltin{{long double} __builtin_infl (void)} -Similar to @code{__builtin_inf}, except the return -type is @code{long double}. -@enddefbuiltin - -@defbuiltin{_Float@var{n} __builtin_inff@var{n} (void)} -Similar to @code{__builtin_inf}, except the return -type is @code{_Float@var{n}}. -@enddefbuiltin - -@defbuiltin{_Float@var{n} __builtin_inff@var{n}x (void)} -Similar to @code{__builtin_inf}, except the return -type is @code{_Float@var{n}x}. -@enddefbuiltin - -@defbuiltin{int __builtin_isinf_sign (...)} -Similar to @code{isinf}, except the return value is -1 for -an argument of @code{-Inf} and 1 for an argument of @code{+Inf}. -Note while the parameter list is an -ellipsis, this function only accepts exactly one floating-point -argument. GCC treats this parameter as type-generic, which means it -does not do default promotion from float to double. -@enddefbuiltin - -@defbuiltin{double __builtin_nan (const char *@var{str})} -This is an implementation of the ISO C99 function @code{nan}. - -Since ISO C99 defines this function in terms of @code{strtod}, which we -do not implement, a description of the parsing is in order. The string -is parsed as by @code{strtol}; that is, the base is recognized by -leading @samp{0} or @samp{0x} prefixes. The number parsed is placed -in the significand such that the least significant bit of the number -is at the least significant bit of the significand. The number is -truncated to fit the significand field provided. The significand is -forced to be a quiet NaN@. - -This function, if given a string literal all of which would have been -consumed by @code{strtol}, is evaluated early enough that it is considered a -compile-time constant. -@enddefbuiltin - -@defbuiltin{_Decimal32 __builtin_nand32 (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. -@enddefbuiltin - -@defbuiltin{_Decimal64 __builtin_nand64 (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. -@enddefbuiltin - -@defbuiltin{_Decimal128 __builtin_nand128 (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. -@enddefbuiltin - -@defbuiltin{float __builtin_nanf (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{float}. -@enddefbuiltin - -@defbuiltin{{long double} __builtin_nanl (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{long double}. -@enddefbuiltin - -@defbuiltin{_Float@var{n} __builtin_nanf@var{n} (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is -@code{_Float@var{n}}. -@enddefbuiltin - -@defbuiltin{_Float@var{n}x __builtin_nanf@var{n}x (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is -@code{_Float@var{n}x}. -@enddefbuiltin - -@defbuiltin{double __builtin_nans (const char *@var{str})} -Similar to @code{__builtin_nan}, except the significand is forced -to be a signaling NaN@. The @code{nans} function is proposed by -@uref{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. -@enddefbuiltin - -@defbuiltin{_Decimal32 __builtin_nansd32 (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}. -@enddefbuiltin - -@defbuiltin{_Decimal64 __builtin_nansd64 (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}. -@enddefbuiltin - -@defbuiltin{_Decimal128 __builtin_nansd128 (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}. -@enddefbuiltin - -@defbuiltin{float __builtin_nansf (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{float}. -@enddefbuiltin - -@defbuiltin{{long double} __builtin_nansl (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{long double}. -@enddefbuiltin - -@defbuiltin{_Float@var{n} __builtin_nansf@var{n} (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is -@code{_Float@var{n}}. -@enddefbuiltin - -@defbuiltin{_Float@var{n}x __builtin_nansf@var{n}x (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is -@code{_Float@var{n}x}. -@enddefbuiltin - -@defbuiltin{int __builtin_issignaling (...)} -Return non-zero if the argument is a signaling NaN and zero otherwise. -Note while the parameter list is an -ellipsis, this function only accepts exactly one floating-point -argument. GCC treats this parameter as type-generic, which means it -does not do default promotion from float to double. -This built-in function can work even without the non-default -@code{-fsignaling-nans} option, although if a signaling NaN is computed, -stored or passed as argument to some function other than this built-in -in the current translation unit, it is safer to use @code{-fsignaling-nans}. -With @code{-ffinite-math-only} option this built-in function will always -return 0. -@enddefbuiltin - -@defbuiltin{int __builtin_ffs (int @var{x})} -Returns one plus the index of the least significant 1-bit of @var{x}, or -if @var{x} is zero, returns zero. -@enddefbuiltin - -@defbuiltin{int __builtin_clz (unsigned int @var{x})} -Returns the number of leading 0-bits in @var{x}, starting at the most -significant bit position. If @var{x} is 0, the result is undefined. -@enddefbuiltin - -@defbuiltin{int __builtin_ctz (unsigned int @var{x})} -Returns the number of trailing 0-bits in @var{x}, starting at the least -significant bit position. If @var{x} is 0, the result is undefined. -@enddefbuiltin - -@defbuiltin{int __builtin_clrsb (int @var{x})} -Returns the number of leading redundant sign bits in @var{x}, i.e.@: the -number of bits following the most significant bit that are identical -to it. There are no special cases for 0 or other values. -@enddefbuiltin - -@defbuiltin{int __builtin_popcount (unsigned int @var{x})} -Returns the number of 1-bits in @var{x}. -@enddefbuiltin - -@defbuiltin{int __builtin_parity (unsigned int @var{x})} -Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} -modulo 2. -@enddefbuiltin - -@defbuiltin{int __builtin_ffsl (long)} -Similar to @code{__builtin_ffs}, except the argument type is -@code{long}. -@enddefbuiltin - -@defbuiltin{int __builtin_clzl (unsigned long)} -Similar to @code{__builtin_clz}, except the argument type is -@code{unsigned long}. -@enddefbuiltin - -@defbuiltin{int __builtin_ctzl (unsigned long)} -Similar to @code{__builtin_ctz}, except the argument type is -@code{unsigned long}. -@enddefbuiltin - -@defbuiltin{int __builtin_clrsbl (long)} -Similar to @code{__builtin_clrsb}, except the argument type is -@code{long}. -@enddefbuiltin - -@defbuiltin{int __builtin_popcountl (unsigned long)} -Similar to @code{__builtin_popcount}, except the argument type is -@code{unsigned long}. -@enddefbuiltin - -@defbuiltin{int __builtin_parityl (unsigned long)} -Similar to @code{__builtin_parity}, except the argument type is -@code{unsigned long}. -@enddefbuiltin - -@defbuiltin{int __builtin_ffsll (long long)} -Similar to @code{__builtin_ffs}, except the argument type is -@code{long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_clzll (unsigned long long)} -Similar to @code{__builtin_clz}, except the argument type is -@code{unsigned long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_ctzll (unsigned long long)} -Similar to @code{__builtin_ctz}, except the argument type is -@code{unsigned long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_clrsbll (long long)} -Similar to @code{__builtin_clrsb}, except the argument type is -@code{long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_popcountll (unsigned long long)} -Similar to @code{__builtin_popcount}, except the argument type is -@code{unsigned long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_parityll (unsigned long long)} -Similar to @code{__builtin_parity}, except the argument type is -@code{unsigned long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_ffsg (...)} -Similar to @code{__builtin_ffs}, except the argument is type-generic -signed integer (standard, extended or bit-precise). No integral argument -promotions are performed on the argument. -@enddefbuiltin - -@defbuiltin{int __builtin_clzg (...)} -Similar to @code{__builtin_clz}, except the argument is type-generic -unsigned integer (standard, extended or bit-precise) and there is -optional second argument with int type. No integral argument promotions -are performed on the first argument. If two arguments are specified, -and first argument is 0, the result is the second argument. If only -one argument is specified and it is 0, the result is undefined. -@enddefbuiltin - -@defbuiltin{int __builtin_ctzg (...)} -Similar to @code{__builtin_ctz}, except the argument is type-generic -unsigned integer (standard, extended or bit-precise) and there is -optional second argument with int type. No integral argument promotions -are performed on the first argument. If two arguments are specified, -and first argument is 0, the result is the second argument. If only -one argument is specified and it is 0, the result is undefined. -@enddefbuiltin - -@defbuiltin{int __builtin_clrsbg (...)} -Similar to @code{__builtin_clrsb}, except the argument is type-generic -signed integer (standard, extended or bit-precise). No integral argument -promotions are performed on the argument. -@enddefbuiltin - -@defbuiltin{int __builtin_popcountg (...)} -Similar to @code{__builtin_popcount}, except the argument is type-generic -unsigned integer (standard, extended or bit-precise). No integral argument -promotions are performed on the argument. -@enddefbuiltin - -@defbuiltin{int __builtin_parityg (...)} -Similar to @code{__builtin_parity}, except the argument is type-generic -unsigned integer (standard, extended or bit-precise). No integral argument -promotions are performed on the argument. -@enddefbuiltin - -@defbuiltin{@var{type} __builtin_stdc_bit_ceil (@var{type} @var{arg})} -The @code{__builtin_stdc_bit_ceil} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{@var{arg} <= 1 ? (@var{type}) 1 -: (@var{type}) 2 << (@var{prec} - 1 - __builtin_clzg ((@var{type}) (@var{arg} - 1)))} -where @var{prec} is bit width of @var{type}, except that side-effects -in @var{arg} are evaluated just once. -@enddefbuiltin - -@defbuiltin{@var{type} __builtin_stdc_bit_floor (@var{type} @var{arg})} -The @code{__builtin_stdc_bit_floor} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{@var{arg} == 0 ? (@var{type}) 0 -: (@var{type}) 1 << (@var{prec} - 1 - __builtin_clzg (@var{arg}))} -where @var{prec} is bit width of @var{type}, except that side-effects -in @var{arg} are evaluated just once. -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_bit_width (@var{type} @var{arg})} -The @code{__builtin_stdc_bit_width} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) (@var{prec} - __builtin_clzg (@var{arg}, @var{prec}))} -where @var{prec} is bit width of @var{type}. -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_count_ones (@var{type} @var{arg})} -The @code{__builtin_stdc_count_ones} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_popcountg (@var{arg})} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_count_zeros (@var{type} @var{arg})} -The @code{__builtin_stdc_count_zeros} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_popcountg ((@var{type}) ~@var{arg})} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_first_leading_one (@var{type} @var{arg})} -The @code{__builtin_stdc_first_leading_one} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{__builtin_clzg (@var{arg}, -1) + 1U} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_first_leading_zero (@var{type} @var{arg})} -The @code{__builtin_stdc_first_leading_zero} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{__builtin_clzg ((@var{type}) ~@var{arg}, -1) + 1U} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_first_trailing_one (@var{type} @var{arg})} -The @code{__builtin_stdc_first_trailing_one} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{__builtin_ctzg (@var{arg}, -1) + 1U} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_first_trailing_zero (@var{type} @var{arg})} -The @code{__builtin_stdc_first_trailing_zero} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{__builtin_ctzg ((@var{type}) ~@var{arg}, -1) + 1U} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_has_single_bit (@var{type} @var{arg})} -The @code{__builtin_stdc_has_single_bit} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(_Bool) (__builtin_popcountg (@var{arg}) == 1)} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_leading_ones (@var{type} @var{arg})} -The @code{__builtin_stdc_leading_ones} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_clzg ((@var{type}) ~@var{arg}, @var{prec})} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_leading_zeros (@var{type} @var{arg})} -The @code{__builtin_stdc_leading_zeros} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_clzg (@var{arg}, @var{prec})} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_trailing_ones (@var{type} @var{arg})} -The @code{__builtin_stdc_trailing_ones} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_ctzg ((@var{type}) ~@var{arg}, @var{prec})} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_trailing_zeros (@var{type} @var{arg})} -The @code{__builtin_stdc_trailing_zeros} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_ctzg (@var{arg}, @var{prec})} -@enddefbuiltin - -@defbuiltin{@var{type1} __builtin_stdc_rotate_left (@var{type1} @var{arg1}, @var{type2} @var{arg2})} -The @code{__builtin_stdc_rotate_left} function is available only -in C. It is type-generic, the first argument can be any unsigned integer -(standard, extended or bit-precise) and second argument any signed or -unsigned integer or @code{char}. No integral argument promotions are -performed on the arguments. It is equivalent to -@code{(@var{type1}) ((@var{arg1} << (@var{arg2} % @var{prec})) -| (@var{arg1} >> ((-(unsigned @var{type2}) @var{arg2}) % @var{prec})))} -where @var{prec} is bit width of @var{type1}, except that side-effects -in @var{arg1} and @var{arg2} are evaluated just once. The behavior is -undefined if @var{arg2} is negative. -@enddefbuiltin - -@defbuiltin{@var{type1} __builtin_stdc_rotate_right (@var{type1} @var{arg1}, @var{type2} @var{arg2})} -The @code{__builtin_stdc_rotate_right} function is available only -in C. It is type-generic, the first argument can be any unsigned integer -(standard, extended or bit-precise) and second argument any signed or -unsigned integer or @code{char}. No integral argument promotions are -performed on the arguments. It is equivalent to -@code{(@var{type1}) ((@var{arg1} >> (@var{arg2} % @var{prec})) -| (@var{arg1} << ((-(unsigned @var{type2}) @var{arg2}) % @var{prec})))} -where @var{prec} is bit width of @var{type1}, except that side-effects -in @var{arg1} and @var{arg2} are evaluated just once. The behavior is -undefined if @var{arg2} is negative. -@enddefbuiltin - -@defbuiltin{double __builtin_powi (double, int)} -@defbuiltinx{float __builtin_powif (float, int)} -@defbuiltinx{{long double} __builtin_powil (long double, int)} -Returns the first argument raised to the power of the second. Unlike the -@code{pow} function no guarantees about precision and rounding are made. -@enddefbuiltin - -@defbuiltin{uint16_t __builtin_bswap16 (uint16_t @var{x})} -Returns @var{x} with the order of the bytes reversed; for example, -@code{0xabcd} becomes @code{0xcdab}. Byte here always means -exactly 8 bits. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_bswap32 (uint32_t @var{x})} -Similar to @code{__builtin_bswap16}, except the argument and return types -are 32-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_bswap64 (uint64_t @var{x})} -Similar to @code{__builtin_bswap32}, except the argument and return types -are 64-bit. -@enddefbuiltin - -@defbuiltin{uint128_t __builtin_bswap128 (uint128_t @var{x})} -Similar to @code{__builtin_bswap64}, except the argument and return types -are 128-bit. Only supported on targets when 128-bit types are supported. -@enddefbuiltin - @defbuiltin{Pmode __builtin_extend_pointer (void * @var{x})} On targets where the user visible pointer size is smaller than the size @@ -16397,114 +17916,6 @@ Returns the openacc gang, worker or vector size depending on whether @var{x} is 0, 1 or 2. @enddefbuiltin -@defbuiltin{uint8_t __builtin_rev_crc8_data8 (uint8_t @var{crc}, uint8_t @var{data}, uint8_t @var{poly})} -Returns the calculated 8-bit bit-reversed CRC using the initial CRC (8-bit), -data (8-bit) and the polynomial (8-bit). -@var{crc} is the initial CRC, @var{data} is the data and -@var{poly} is the polynomial without leading 1. -Table-based or clmul-based CRC may be used for the -calculation, depending on the target architecture. -@enddefbuiltin - -@defbuiltin{uint16_t __builtin_rev_crc16_data16 (uint16_t @var{crc}, uint16_t @var{data}, uint16_t @var{poly})} -Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types -are 16-bit. -@enddefbuiltin - -@defbuiltin{uint16_t __builtin_rev_crc16_data8 (uint16_t @var{crc}, uint8_t @var{data}, uint16_t @var{poly})} -Similar to @code{__builtin_rev_crc16_data16}, except the @var{data} argument -type is 8-bit. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_rev_crc32_data32 (uint32_t @var{crc}, uint32_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types -are 32-bit and for the CRC calculation may be also used crc* machine instruction -depending on the target and the polynomial. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_rev_crc32_data8 (uint32_t @var{crc}, uint8_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_rev_crc32_data32}, except the @var{data} argument -type is 8-bit. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_rev_crc32_data16 (uint32_t @var{crc}, uint16_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_rev_crc32_data32}, except the @var{data} argument -type is 16-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_rev_crc64_data64 (uint64_t @var{crc}, uint64_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types -are 64-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_rev_crc64_data8 (uint64_t @var{crc}, uint8_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type -is 8-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_rev_crc64_data16 (uint64_t @var{crc}, uint16_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type -is 16-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_rev_crc64_data32 (uint64_t @var{crc}, uint32_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type -is 32-bit. -@enddefbuiltin - -@defbuiltin{uint8_t __builtin_crc8_data8 (uint8_t @var{crc}, uint8_t @var{data}, uint8_t @var{poly})} -Returns the calculated 8-bit bit-forward CRC using the initial CRC (8-bit), -data (8-bit) and the polynomial (8-bit). -@var{crc} is the initial CRC, @var{data} is the data and -@var{poly} is the polynomial without leading 1. -Table-based or clmul-based CRC may be used for the -calculation, depending on the target architecture. -@enddefbuiltin - -@defbuiltin{uint16_t __builtin_crc16_data16 (uint16_t @var{crc}, uint16_t @var{data}, uint16_t @var{poly})} -Similar to @code{__builtin_crc8_data8}, except the argument and return types -are 16-bit. -@enddefbuiltin - -@defbuiltin{uint16_t __builtin_crc16_data8 (uint16_t @var{crc}, uint8_t @var{data}, uint16_t @var{poly})} -Similar to @code{__builtin_crc16_data16}, except the @var{data} argument type -is 8-bit. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_crc32_data32 (uint32_t @var{crc}, uint32_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_crc8_data8}, except the argument and return types -are 32-bit. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_crc32_data8 (uint32_t @var{crc}, uint8_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_crc32_data32}, except the @var{data} argument type -is 8-bit. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_crc32_data16 (uint32_t @var{crc}, uint16_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_crc32_data32}, except the @var{data} argument type -is 16-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_crc64_data64 (uint64_t @var{crc}, uint64_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_crc8_data8}, except the argument and return types -are 64-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_crc64_data8 (uint64_t @var{crc}, uint8_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type -is 8-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_crc64_data16 (uint64_t @var{crc}, uint16_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type -is 16-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_crc64_data32 (uint64_t @var{crc}, uint32_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type -is 32-bit. -@enddefbuiltin @node Target Builtins @section Built-in Functions Specific to Particular Target Machines @@ -28426,1130 +29837,6 @@ The shadow stack unwind code looks like: This code runs unconditionally on all 64-bit processors. For 32-bit processors the code runs on those that support multi-byte NOP instructions. -@node Target Format Checks -@section Format Checks Specific to Particular Target Machines - -For some target machines, GCC supports additional options to the -format attribute -(@pxref{Function Attributes,,Declaring Attributes of Functions}). - -@menu -* Solaris Format Checks:: -* Darwin Format Checks:: -@end menu - -@node Solaris Format Checks -@subsection Solaris Format Checks - -Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format -check. @code{cmn_err} accepts a subset of the standard @code{printf} -conversions, and the two-argument @code{%b} conversion for displaying -bit-fields. See the Solaris man page for @code{cmn_err} for more information. - -@node Darwin Format Checks -@subsection Darwin Format Checks - -In addition to the full set of format archetypes (attribute format style -arguments such as @code{printf}, @code{scanf}, @code{strftime}, and -@code{strfmon}), Darwin targets also support the @code{CFString} (or -@code{__CFString__}) archetype in the @code{format} attribute. -Declarations with this archetype are parsed for correct syntax -and argument types. However, parsing of the format string itself and -validating arguments against it in calls to such functions is currently -not performed. - -Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may -also be used as format arguments. Note that the relevant headers are only likely to be -available on Darwin (OSX) installations. On such installations, the XCode and system -documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and -associated functions. - -@node Pragmas -@section Pragmas Accepted by GCC -@cindex pragmas -@cindex @code{#pragma} - -GCC supports several types of pragmas, primarily in order to compile -code originally written for other compilers. Note that in general -we do not recommend the use of pragmas; @xref{Function Attributes}, -for further explanation. - -The GNU C preprocessor recognizes several pragmas in addition to the -compiler pragmas documented here. Refer to the CPP manual for more -information. - -GCC additionally recognizes OpenMP pragmas when the @option{-fopenmp} -option is specified, and OpenACC pragmas when the @option{-fopenacc} -option is specified. @xref{OpenMP}, and @ref{OpenACC}. - -@menu -* AArch64 Pragmas:: -* ARM Pragmas:: -* LoongArch Pragmas:: -* M32C Pragmas:: -* PRU Pragmas:: -* RS/6000 and PowerPC Pragmas:: -* S/390 Pragmas:: -* Darwin Pragmas:: -* Solaris Pragmas:: -* Symbol-Renaming Pragmas:: -* Structure-Layout Pragmas:: -* Weak Pragmas:: -* Diagnostic Pragmas:: -* Visibility Pragmas:: -* Push/Pop Macro Pragmas:: -* Function Specific Option Pragmas:: -* Loop-Specific Pragmas:: -@end menu - -@node AArch64 Pragmas -@subsection AArch64 Pragmas - -The pragmas defined by the AArch64 target correspond to the AArch64 -target function attributes. They can be specified as below: -@smallexample -#pragma GCC target("string") -@end smallexample - -where @code{@var{string}} can be any string accepted as an AArch64 target -attribute. @xref{AArch64 Function Attributes}, for more details -on the permissible values of @code{string}. - -@node ARM Pragmas -@subsection ARM Pragmas - -The ARM target defines pragmas for controlling the default addition of -@code{long_call} and @code{short_call} attributes to functions. -@xref{Function Attributes}, for information about the effects of these -attributes. - -@table @code -@cindex pragma, long_calls -@item long_calls -Set all subsequent functions to have the @code{long_call} attribute. - -@cindex pragma, no_long_calls -@item no_long_calls -Set all subsequent functions to have the @code{short_call} attribute. - -@cindex pragma, long_calls_off -@item long_calls_off -Do not affect the @code{long_call} or @code{short_call} attributes of -subsequent functions. -@end table - -@node LoongArch Pragmas -@subsection LoongArch Pragmas - -The list of attributes supported by Pragma is the same as that of target -function attributes. @xref{LoongArch Function Attributes}. - -Example: - -@smallexample -#pragma GCC target("strict-align") -@end smallexample - -@node M32C Pragmas -@subsection M32C Pragmas - -@table @code -@cindex pragma, memregs -@item GCC memregs @var{number} -Overrides the command-line option @code{-memregs=} for the current -file. Use with care! This pragma must be before any function in the -file, and mixing different memregs values in different objects may -make them incompatible. This pragma is useful when a -performance-critical function uses a memreg for temporary values, -as it may allow you to reduce the number of memregs used. - -@cindex pragma, address -@item ADDRESS @var{name} @var{address} -For any declared symbols matching @var{name}, this does three things -to that symbol: it forces the symbol to be located at the given -address (a number), it forces the symbol to be volatile, and it -changes the symbol's scope to be static. This pragma exists for -compatibility with other compilers, but note that the common -@code{1234H} numeric syntax is not supported (use @code{0x1234} -instead). Example: - -@smallexample -#pragma ADDRESS port3 0x103 -char port3; -@end smallexample - -@end table - -@node PRU Pragmas -@subsection PRU Pragmas - -@table @code - -@cindex pragma, ctable_entry -@item ctable_entry @var{index} @var{constant_address} -Specifies that the PRU CTABLE entry given by @var{index} has the value -@var{constant_address}. This enables GCC to emit LBCO/SBCO instructions -when the load/store address is known and can be addressed with some CTABLE -entry. For example: - -@smallexample -/* will compile to "sbco Rx, 2, 0x10, 4" */ -#pragma ctable_entry 2 0x4802a000 -*(unsigned int *)0x4802a010 = val; -@end smallexample - -@end table - -@node RS/6000 and PowerPC Pragmas -@subsection RS/6000 and PowerPC Pragmas - -The RS/6000 and PowerPC targets define one pragma for controlling -whether or not the @code{longcall} attribute is added to function -declarations by default. This pragma overrides the @option{-mlongcall} -option, but not the @code{longcall} and @code{shortcall} attributes. -@xref{RS/6000 and PowerPC Options}, for more information about when long -calls are and are not necessary. - -@table @code -@cindex pragma, longcall -@item longcall (1) -Apply the @code{longcall} attribute to all subsequent function -declarations. - -@item longcall (0) -Do not apply the @code{longcall} attribute to subsequent function -declarations. -@end table - -@c Describe h8300 pragmas here. -@c Describe sh pragmas here. -@c Describe v850 pragmas here. - -@node S/390 Pragmas -@subsection S/390 Pragmas - -The pragmas defined by the S/390 target correspond to the S/390 -target function attributes and some the additional options: - -@table @samp -@item zvector -@itemx no-zvector -@end table - -Note that options of the pragma, unlike options of the target -attribute, do change the value of preprocessor macros like -@code{__VEC__}. They can be specified as below: - -@smallexample -#pragma GCC target("string[,string]...") -#pragma GCC target("string"[,"string"]...) -@end smallexample - -@node Darwin Pragmas -@subsection Darwin Pragmas - -The following pragmas are available for all architectures running the -Darwin operating system. These are useful for compatibility with other -macOS compilers. - -@table @code -@cindex pragma, mark -@item mark @var{tokens}@dots{} -This pragma is accepted, but has no effect. - -@cindex pragma, options align -@item options align=@var{alignment} -This pragma sets the alignment of fields in structures. The values of -@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or -@code{power}, to emulate PowerPC alignment. Uses of this pragma nest -properly; to restore the previous setting, use @code{reset} for the -@var{alignment}. - -@cindex pragma, segment -@item segment @var{tokens}@dots{} -This pragma is accepted, but has no effect. - -@cindex pragma, unused -@item unused (@var{var} [, @var{var}]@dots{}) -This pragma declares variables to be possibly unused. GCC does not -produce warnings for the listed variables. The effect is similar to -that of the @code{unused} attribute, except that this pragma may appear -anywhere within the variables' scopes. -@end table - -@node Solaris Pragmas -@subsection Solaris Pragmas - -The Solaris target supports @code{#pragma redefine_extname} -(@pxref{Symbol-Renaming Pragmas}). It also supports additional -@code{#pragma} directives for compatibility with the system compiler. - -@table @code -@cindex pragma, align -@item align @var{alignment} (@var{variable} [, @var{variable}]...) - -Increase the minimum alignment of each @var{variable} to @var{alignment}. -This is the same as GCC's @code{aligned} attribute @pxref{Variable -Attributes}). Macro expansion occurs on the arguments to this pragma -when compiling C and Objective-C@. It does not currently occur when -compiling C++, but this is a bug which may be fixed in a future -release. - -@cindex pragma, fini -@item fini (@var{function} [, @var{function}]...) - -This pragma causes each listed @var{function} to be called after -main, or during shared module unloading, by adding a call to the -@code{.fini} section. - -@cindex pragma, init -@item init (@var{function} [, @var{function}]...) - -This pragma causes each listed @var{function} to be called during -initialization (before @code{main}) or during shared module loading, by -adding a call to the @code{.init} section. - -@end table - -@node Symbol-Renaming Pragmas -@subsection Symbol-Renaming Pragmas - -GCC supports a @code{#pragma} directive that changes the name used in -assembly for a given declaration. While this pragma is supported on all -platforms, it is intended primarily to provide compatibility with the -Solaris system headers. This effect can also be achieved using the asm -labels extension (@pxref{Asm Labels}). - -@table @code -@cindex pragma, redefine_extname -@item redefine_extname @var{oldname} @var{newname} - -This pragma gives the C function @var{oldname} the assembly symbol -@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} -is defined if this pragma is available (currently on all platforms). -@end table - -This pragma and the @code{asm} labels extension interact in a complicated -manner. Here are some corner cases you may want to be aware of: - -@enumerate -@item This pragma silently applies only to declarations with external -linkage. The @code{asm} label feature does not have this restriction. - -@item In C++, this pragma silently applies only to declarations with -``C'' linkage. Again, @code{asm} labels do not have this restriction. - -@item If either of the ways of changing the assembly name of a -declaration are applied to a declaration whose assembly name has -already been determined (either by a previous use of one of these -features, or because the compiler needed the assembly name in order to -generate code), and the new name is different, a warning issues and -the name does not change. - -@item The @var{oldname} used by @code{#pragma redefine_extname} is -always the C-language name. -@end enumerate - -@node Structure-Layout Pragmas -@subsection Structure-Layout Pragmas - -For compatibility with Microsoft Windows compilers, GCC supports a -set of @code{#pragma} directives that change the maximum alignment of -members of structures (other than zero-width bit-fields), unions, and -classes subsequently defined. The @var{n} value below always is required -to be a small power of two and specifies the new alignment in bytes. - -@enumerate -@item @code{#pragma pack(@var{n})} simply sets the new alignment. -@item @code{#pragma pack()} sets the alignment to the one that was in -effect when compilation started (see also command-line option -@option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). -@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment -setting on an internal stack and then optionally sets the new alignment. -@item @code{#pragma pack(pop)} restores the alignment setting to the one -saved at the top of the internal stack (and removes that stack entry). -Note that @code{#pragma pack([@var{n}])} does not influence this internal -stack; thus it is possible to have @code{#pragma pack(push)} followed by -multiple @code{#pragma pack(@var{n})} instances and finalized by a single -@code{#pragma pack(pop)}. -@end enumerate - -Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct} -directive which lays out structures and unions subsequently defined as the -documented @code{__attribute__ ((ms_struct))}. - -@enumerate -@item @code{#pragma ms_struct on} turns on the Microsoft layout. -@item @code{#pragma ms_struct off} turns off the Microsoft layout. -@item @code{#pragma ms_struct reset} goes back to the default layout. -@end enumerate - -Most targets also support the @code{#pragma scalar_storage_order} directive -which lays out structures and unions subsequently defined as the documented -@code{__attribute__ ((scalar_storage_order))}. - -@enumerate -@item @code{#pragma scalar_storage_order big-endian} sets the storage order -of the scalar fields to big-endian. -@item @code{#pragma scalar_storage_order little-endian} sets the storage order -of the scalar fields to little-endian. -@item @code{#pragma scalar_storage_order default} goes back to the endianness -that was in effect when compilation started (see also command-line option -@option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}). -@end enumerate - -@node Weak Pragmas -@subsection Weak Pragmas - -For compatibility with SVR4, GCC supports a set of @code{#pragma} -directives for declaring symbols to be weak, and defining weak -aliases. - -@table @code -@cindex pragma, weak -@item #pragma weak @var{symbol} -This pragma declares @var{symbol} to be weak, as if the declaration -had the attribute of the same name. The pragma may appear before -or after the declaration of @var{symbol}. It is not an error for -@var{symbol} to never be defined at all. - -@item #pragma weak @var{symbol1} = @var{symbol2} -This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. -It is an error if @var{symbol2} is not defined in the current -translation unit. -@end table - -@node Diagnostic Pragmas -@subsection Diagnostic Pragmas - -GCC allows the user to selectively enable or disable certain types of -diagnostics, and change the kind of the diagnostic. For example, a -project's policy might require that all sources compile with -@option{-Werror} but certain files might have exceptions allowing -specific types of warnings. Or, a project might selectively enable -diagnostics and treat them as errors depending on which preprocessor -macros are defined. - -@table @code -@cindex pragma, diagnostic -@item #pragma GCC diagnostic @var{kind} @var{option} - -Modifies the disposition of a diagnostic. Note that not all -diagnostics are modifiable; at the moment only warnings (normally -controlled by @samp{-W@dots{}}) can be controlled, and not all of them. -Use @option{-fdiagnostics-show-option} to determine which diagnostics -are controllable and which option controls them. - -@var{kind} is @samp{error} to treat this diagnostic as an error, -@samp{warning} to treat it like a warning (even if @option{-Werror} is -in effect), or @samp{ignored} if the diagnostic is to be ignored. -@var{option} is a double quoted string that matches the command-line -option. - -@smallexample -#pragma GCC diagnostic warning "-Wformat" -#pragma GCC diagnostic error "-Wformat" -#pragma GCC diagnostic ignored "-Wformat" -@end smallexample - -Note that these pragmas override any command-line options. GCC keeps -track of the location of each pragma, and issues diagnostics according -to the state as of that point in the source file. Thus, pragmas occurring -after a line do not affect diagnostics caused by that line. - -@item #pragma GCC diagnostic push -@itemx #pragma GCC diagnostic pop - -Causes GCC to remember the state of the diagnostics as of each -@code{push}, and restore to that point at each @code{pop}. If a -@code{pop} has no matching @code{push}, the command-line options are -restored. - -@smallexample -#pragma GCC diagnostic error "-Wuninitialized" - foo(a); /* error is given for this one */ -#pragma GCC diagnostic push -#pragma GCC diagnostic ignored "-Wuninitialized" - foo(b); /* no diagnostic for this one */ -#pragma GCC diagnostic pop - foo(c); /* error is given for this one */ -#pragma GCC diagnostic pop - foo(d); /* depends on command-line options */ -@end smallexample - -@item #pragma GCC diagnostic ignored_attributes - -Similarly to @option{-Wno-attributes=}, this pragma allows users to suppress -warnings about unknown scoped attributes (in C++11 and C23). For example, -@code{#pragma GCC diagnostic ignored_attributes "vendor::attr"} disables -warning about the following declaration: - -@smallexample -[[vendor::attr]] void f(); -@end smallexample - -whereas @code{#pragma GCC diagnostic ignored_attributes "vendor::"} prevents -warning about both of these declarations: - -@smallexample -[[vendor::safe]] void f(); -[[vendor::unsafe]] void f2(); -@end smallexample - -@end table - -GCC also offers a simple mechanism for printing messages during -compilation. - -@table @code -@cindex pragma, diagnostic -@item #pragma message @var{string} - -Prints @var{string} as a compiler message on compilation. The message -is informational only, and is neither a compilation warning nor an -error. Newlines can be included in the string by using the @samp{\n} -escape sequence. - -@smallexample -#pragma message "Compiling " __FILE__ "..." -@end smallexample - -@var{string} may be parenthesized, and is printed with location -information. For example, - -@smallexample -#define DO_PRAGMA(x) _Pragma (#x) -#define TODO(x) DO_PRAGMA(message ("TODO - " #x)) - -TODO(Remember to fix this) -@end smallexample - -@noindent -prints @samp{/tmp/file.c:4: note: #pragma message: -TODO - Remember to fix this}. - -@cindex pragma, diagnostic -@item #pragma GCC error @var{message} -Generates an error message. This pragma @emph{is} considered to -indicate an error in the compilation, and it will be treated as such. - -Newlines can be included in the string by using the @samp{\n} -escape sequence. They will be displayed as newlines even if the -@option{-fmessage-length} option is set to zero. - -The error is only generated if the pragma is present in the code after -pre-processing has been completed. It does not matter however if the -code containing the pragma is unreachable: - -@smallexample -#if 0 -#pragma GCC error "this error is not seen" -#endif -void foo (void) -@{ - return; -#pragma GCC error "this error is seen" -@} -@end smallexample - -@cindex pragma, diagnostic -@item #pragma GCC warning @var{message} -This is just like @samp{pragma GCC error} except that a warning -message is issued instead of an error message. Unless -@option{-Werror} is in effect, in which case this pragma will generate -an error as well. - -@end table - -@node Visibility Pragmas -@subsection Visibility Pragmas - -@table @code -@cindex pragma, visibility -@item #pragma GCC visibility push(@var{visibility}) -@itemx #pragma GCC visibility pop - -This pragma allows the user to set the visibility for multiple -declarations without having to give each a visibility attribute -(@pxref{Function Attributes}). - -In C++, @samp{#pragma GCC visibility} affects only namespace-scope -declarations. Class members and template specializations are not -affected; if you want to override the visibility for a particular -member or instantiation, you must use an attribute. - -@end table - - -@node Push/Pop Macro Pragmas -@subsection Push/Pop Macro Pragmas - -For compatibility with Microsoft Windows compilers, GCC supports -@samp{#pragma push_macro(@var{"macro_name"})} -and @samp{#pragma pop_macro(@var{"macro_name"})}. - -@table @code -@cindex pragma, push_macro -@item #pragma push_macro(@var{"macro_name"}) -This pragma saves the value of the macro named as @var{macro_name} to -the top of the stack for this macro. - -@cindex pragma, pop_macro -@item #pragma pop_macro(@var{"macro_name"}) -This pragma sets the value of the macro named as @var{macro_name} to -the value on top of the stack for this macro. If the stack for -@var{macro_name} is empty, the value of the macro remains unchanged. -@end table - -For example: - -@smallexample -#define X 1 -#pragma push_macro("X") -#undef X -#define X -1 -#pragma pop_macro("X") -int x [X]; -@end smallexample - -@noindent -In this example, the definition of X as 1 is saved by @code{#pragma -push_macro} and restored by @code{#pragma pop_macro}. - -@node Function Specific Option Pragmas -@subsection Function Specific Option Pragmas - -@table @code -@cindex pragma GCC target -@item #pragma GCC target (@var{string}, @dots{}) - -This pragma allows you to set target-specific options for functions -defined later in the source file. One or more strings can be -specified. Each function that is defined after this point is treated -as if it had been declared with one @code{target(}@var{string}@code{)} -attribute for each @var{string} argument. The parentheses around -the strings in the pragma are optional. @xref{Function Attributes}, -for more information about the @code{target} attribute and the attribute -syntax. - -The @code{#pragma GCC target} pragma is presently implemented for -x86, ARM, AArch64, PowerPC, and S/390 targets only. - -@cindex pragma GCC optimize -@item #pragma GCC optimize (@var{string}, @dots{}) - -This pragma allows you to set global optimization options for functions -defined later in the source file. One or more strings can be -specified. Each function that is defined after this point is treated -as if it had been declared with one @code{optimize(}@var{string}@code{)} -attribute for each @var{string} argument. The parentheses around -the strings in the pragma are optional. @xref{Function Attributes}, -for more information about the @code{optimize} attribute and the attribute -syntax. - -@cindex pragma GCC push_options -@cindex pragma GCC pop_options -@item #pragma GCC push_options -@itemx #pragma GCC pop_options - -These pragmas maintain a stack of the current target and optimization -options. It is intended for include files where you temporarily want -to switch to using a different @samp{#pragma GCC target} or -@samp{#pragma GCC optimize} and then to pop back to the previous -options. - -@cindex pragma GCC reset_options -@item #pragma GCC reset_options - -This pragma clears the current @code{#pragma GCC target} and -@code{#pragma GCC optimize} to use the default switches as specified -on the command line. - -@end table - -@node Loop-Specific Pragmas -@subsection Loop-Specific Pragmas - -@table @code -@cindex pragma GCC ivdep -@item #pragma GCC ivdep - -With this pragma, the programmer asserts that there are no loop-carried -dependencies which would prevent consecutive iterations of -the following loop from executing concurrently with SIMD -(single instruction multiple data) instructions. - -For example, the compiler can only unconditionally vectorize the following -loop with the pragma: - -@smallexample -void foo (int n, int *a, int *b, int *c) -@{ - int i, j; -#pragma GCC ivdep - for (i = 0; i < n; ++i) - a[i] = b[i] + c[i]; -@} -@end smallexample - -@noindent -In this example, using the @code{restrict} qualifier had the same -effect. In the following example, that would not be possible. Assume -@math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows -that it can unconditionally vectorize the following loop: - -@smallexample -void ignore_vec_dep (int *a, int k, int c, int m) -@{ -#pragma GCC ivdep - for (int i = 0; i < m; i++) - a[i] = a[i + k] * c; -@} -@end smallexample - -@cindex pragma GCC novector -@item #pragma GCC novector - -With this pragma, the programmer asserts that the following loop should be -prevented from executing concurrently with SIMD (single instruction multiple -data) instructions. - -For example, the compiler cannot vectorize the following loop with the pragma: - -@smallexample -void foo (int n, int *a, int *b, int *c) -@{ - int i, j; -#pragma GCC novector - for (i = 0; i < n; ++i) - a[i] = b[i] + c[i]; -@} -@end smallexample - -@cindex pragma GCC unroll @var{n} -@item #pragma GCC unroll @var{n} - -You can use this pragma to control how many times a loop should be unrolled. -It must be placed immediately before a @code{for}, @code{while} or @code{do} -loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows. -@var{n} is an integer constant expression specifying the unrolling factor. -The values of @math{0} and @math{1} block any unrolling of the loop. - -@end table - -@node Unnamed Fields -@section Unnamed Structure and Union Fields -@cindex @code{struct} -@cindex @code{union} - -As permitted by ISO C11 and for compatibility with other compilers, -GCC allows you to define -a structure or union that contains, as fields, structures and unions -without names. For example: - -@smallexample -struct @{ - int a; - union @{ - int b; - float c; - @}; - int d; -@} foo; -@end smallexample - -@noindent -In this example, you are able to access members of the unnamed -union with code like @samp{foo.b}. Note that only unnamed structs and -unions are allowed, you may not have, for example, an unnamed -@code{int}. - -You must never create such structures that cause ambiguous field definitions. -For example, in this structure: - -@smallexample -struct @{ - int a; - struct @{ - int a; - @}; -@} foo; -@end smallexample - -@noindent -it is ambiguous which @code{a} is being referred to with @samp{foo.a}. -The compiler gives errors for such constructs. - -@opindex fms-extensions -Unless @option{-fms-extensions} is used, the unnamed field must be a -structure or union definition without a tag (for example, @samp{struct -@{ int a; @};}). If @option{-fms-extensions} is used, the field may -also be a definition with a tag such as @samp{struct foo @{ int a; -@};}, a reference to a previously defined structure or union such as -@samp{struct foo;}, or a reference to a @code{typedef} name for a -previously defined structure or union type. - -@opindex fplan9-extensions -The option @option{-fplan9-extensions} enables -@option{-fms-extensions} as well as two other extensions. First, a -pointer to a structure is automatically converted to a pointer to an -anonymous field for assignments and function calls. For example: - -@smallexample -struct s1 @{ int a; @}; -struct s2 @{ struct s1; @}; -extern void f1 (struct s1 *); -void f2 (struct s2 *p) @{ f1 (p); @} -@end smallexample - -@noindent -In the call to @code{f1} inside @code{f2}, the pointer @code{p} is -converted into a pointer to the anonymous field. - -Second, when the type of an anonymous field is a @code{typedef} for a -@code{struct} or @code{union}, code may refer to the field using the -name of the @code{typedef}. - -@smallexample -typedef struct @{ int a; @} s1; -struct s2 @{ s1; @}; -s1 f1 (struct s2 *p) @{ return p->s1; @} -@end smallexample - -These usages are only permitted when they are not ambiguous. - -@node Thread-Local -@section Thread-Local Storage -@cindex Thread-Local Storage -@cindex @acronym{TLS} -@cindex @code{__thread} - -Thread-local storage (@acronym{TLS}) is a mechanism by which variables -are allocated such that there is one instance of the variable per extant -thread. The runtime model GCC uses to implement this originates -in the IA-64 processor-specific ABI, but has since been migrated -to other processors as well. It requires significant support from -the linker (@command{ld}), dynamic linker (@command{ld.so}), and -system libraries (@file{libc.so} and @file{libpthread.so}), so it -is not available everywhere. - -At the user level, the extension is visible with a new storage -class keyword: @code{__thread}. For example: - -@smallexample -__thread int i; -extern __thread struct state s; -static __thread char *p; -@end smallexample - -The @code{__thread} specifier may be used alone, with the @code{extern} -or @code{static} specifiers, but with no other storage class specifier. -When used with @code{extern} or @code{static}, @code{__thread} must appear -immediately after the other storage class specifier. - -The @code{__thread} specifier may be applied to any global, file-scoped -static, function-scoped static, or static data member of a class. It may -not be applied to block-scoped automatic or non-static data member. - -When the address-of operator is applied to a thread-local variable, it is -evaluated at run time and returns the address of the current thread's -instance of that variable. An address so obtained may be used by any -thread. When a thread terminates, any pointers to thread-local variables -in that thread become invalid. - -No static initialization may refer to the address of a thread-local variable. - -In C++, if an initializer is present for a thread-local variable, it must -be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ -standard. - -See @uref{https://www.akkadia.org/drepper/tls.pdf, -ELF Handling For Thread-Local Storage} for a detailed explanation of -the four thread-local storage addressing models, and how the runtime -is expected to function. - -@menu -* C99 Thread-Local Edits:: -* C++98 Thread-Local Edits:: -@end menu - -@node C99 Thread-Local Edits -@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage - -The following are a set of changes to ISO/IEC 9899:1999 (aka C99) -that document the exact semantics of the language extension. - -@itemize @bullet -@item -@cite{5.1.2 Execution environments} - -Add new text after paragraph 1 - -@quotation -Within either execution environment, a @dfn{thread} is a flow of -control within a program. It is implementation defined whether -or not there may be more than one thread associated with a program. -It is implementation defined how threads beyond the first are -created, the name and type of the function called at thread -startup, and how threads may be terminated. However, objects -with thread storage duration shall be initialized before thread -startup. -@end quotation - -@item -@cite{6.2.4 Storage durations of objects} - -Add new text before paragraph 3 - -@quotation -An object whose identifier is declared with the storage-class -specifier @w{@code{__thread}} has @dfn{thread storage duration}. -Its lifetime is the entire execution of the thread, and its -stored value is initialized only once, prior to thread startup. -@end quotation - -@item -@cite{6.4.1 Keywords} - -Add @code{__thread}. - -@item -@cite{6.7.1 Storage-class specifiers} - -Add @code{__thread} to the list of storage class specifiers in -paragraph 1. - -Change paragraph 2 to - -@quotation -With the exception of @code{__thread}, at most one storage-class -specifier may be given [@dots{}]. The @code{__thread} specifier may -be used alone, or immediately following @code{extern} or -@code{static}. -@end quotation - -Add new text after paragraph 6 - -@quotation -The declaration of an identifier for a variable that has -block scope that specifies @code{__thread} shall also -specify either @code{extern} or @code{static}. - -The @code{__thread} specifier shall be used only with -variables. -@end quotation -@end itemize - -@node C++98 Thread-Local Edits -@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage - -The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) -that document the exact semantics of the language extension. - -@itemize @bullet -@item -@b{[intro.execution]} - -New text after paragraph 4 - -@quotation -A @dfn{thread} is a flow of control within the abstract machine. -It is implementation defined whether or not there may be more than -one thread. -@end quotation - -New text after paragraph 7 - -@quotation -It is unspecified whether additional action must be taken to -ensure when and whether side effects are visible to other threads. -@end quotation - -@item -@b{[lex.key]} - -Add @code{__thread}. - -@item -@b{[basic.start.main]} - -Add after paragraph 5 - -@quotation -The thread that begins execution at the @code{main} function is called -the @dfn{main thread}. It is implementation defined how functions -beginning threads other than the main thread are designated or typed. -A function so designated, as well as the @code{main} function, is called -a @dfn{thread startup function}. It is implementation defined what -happens if a thread startup function returns. It is implementation -defined what happens to other threads when any thread calls @code{exit}. -@end quotation - -@item -@b{[basic.start.init]} - -Add after paragraph 4 - -@quotation -The storage for an object of thread storage duration shall be -statically initialized before the first statement of the thread startup -function. An object of thread storage duration shall not require -dynamic initialization. -@end quotation - -@item -@b{[basic.start.term]} - -Add after paragraph 3 - -@quotation -The type of an object with thread storage duration shall not have a -non-trivial destructor, nor shall it be an array type whose elements -(directly or indirectly) have non-trivial destructors. -@end quotation - -@item -@b{[basic.stc]} - -Add ``thread storage duration'' to the list in paragraph 1. - -Change paragraph 2 - -@quotation -Thread, static, and automatic storage durations are associated with -objects introduced by declarations [@dots{}]. -@end quotation - -Add @code{__thread} to the list of specifiers in paragraph 3. - -@item -@b{[basic.stc.thread]} - -New section before @b{[basic.stc.static]} - -@quotation -The keyword @code{__thread} applied to a non-local object gives the -object thread storage duration. - -A local variable or class data member declared both @code{static} -and @code{__thread} gives the variable or member thread storage -duration. -@end quotation - -@item -@b{[basic.stc.static]} - -Change paragraph 1 - -@quotation -All objects that have neither thread storage duration, dynamic -storage duration nor are local [@dots{}]. -@end quotation - -@item -@b{[dcl.stc]} - -Add @code{__thread} to the list in paragraph 1. - -Change paragraph 1 - -@quotation -With the exception of @code{__thread}, at most one -@var{storage-class-specifier} shall appear in a given -@var{decl-specifier-seq}. The @code{__thread} specifier may -be used alone, or immediately following the @code{extern} or -@code{static} specifiers. [@dots{}] -@end quotation - -Add after paragraph 5 - -@quotation -The @code{__thread} specifier can be applied only to the names of objects -and to anonymous unions. -@end quotation - -@item -@b{[class.mem]} - -Add after paragraph 6 - -@quotation -Non-@code{static} members shall not be @code{__thread}. -@end quotation -@end itemize - -@node Binary constants -@section Binary Constants using the @samp{0b} Prefix -@cindex Binary constants using the @samp{0b} prefix - -Integer constants can be written as binary constants, consisting of a -sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or -@samp{0B}. This is particularly useful in environments that operate a -lot on the bit level (like microcontrollers). - -The following statements are identical: - -@smallexample -i = 42; -i = 0x2a; -i = 052; -i = 0b101010; -@end smallexample - -The type of these constants follows the same rules as for octal or -hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} -can be applied. - -@node OpenMP -@section OpenMP -@cindex OpenMP extension support - -OpenMP (Open Multi-Processing) is an application programming -interface (API) that supports multi-platform shared memory -multiprocessing programming in C/C++ and Fortran on many -architectures, including Unix and Microsoft Windows platforms. -It consists of a set of compiler directives, library routines, -and environment variables that influence run-time behavior. - -GCC implements all of the @uref{https://www.openmp.org/specifications/, -OpenMP Application Program Interface v4.5}, and many features from later -versions of the OpenMP specification. -@xref{OpenMP Implementation Status,,,libgomp, -GNU Offloading and Multi Processing Runtime Library}, -for more details about currently supported OpenMP features. - -To enable the processing of OpenMP directives @samp{#pragma omp}, -@samp{[[omp::directive(...)]]}, @samp{[[omp::decl(...)]]}, -and @samp{[[omp::sequence(...)]]} in C and C++, -GCC needs to be invoked with the @option{-fopenmp} option. -This option also arranges for automatic linking of the OpenMP -runtime library. -@xref{,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. - -@xref{OpenMP and OpenACC Options}, for additional options useful with -@option{-fopenmp}. - -@node OpenACC -@section OpenACC -@cindex OpenACC extension support - -OpenACC is an application programming interface (API) that supports -offloading of code to accelerator devices. It consists of a set of -compiler directives, library routines, and environment variables that -influence run-time behavior. - -GCC strives to be compatible with the -@uref{https://www.openacc.org/, OpenACC Application Programming -Interface v2.6}. - -To enable the processing of OpenACC directives @samp{#pragma acc} -in C and C++, GCC needs to be invoked with the @option{-fopenacc} option. -This option also arranges for automatic linking of the OpenACC runtime -library. -@xref{,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. - -@xref{OpenMP and OpenACC Options}, for additional options useful with -@option{-fopenacc}. @node C++ Extensions @chapter Extensions to the C++ Language @@ -30078,11 +30365,11 @@ variable or function or moving it into a tagged inline namespace. In Standard C++, objects defined at namespace scope are guaranteed to be initialized in an order in strict accordance with that of their definitions @emph{in a given translation unit}. No guarantee is made for initializations -across translation units. However, GNU C++ allows users to control the +across translation units. However, GNU C++ allows you to control the order of initialization of objects defined at namespace scope with the @code{init_priority} attribute by specifying a relative @var{priority}, -a constant integral expression currently bounded between 101 and 65535 -inclusive. Lower numbers indicate a higher priority. +with the same meaning as for the @code{constructor} attribute +(@pxref{Common Function Attributes}). In the following example, @code{A} would normally be created before @code{B}, but the @code{init_priority} attribute reverses that order: @@ -30096,6 +30383,11 @@ Some_Class B __attribute__ ((init_priority (543))); Note that the particular values of @var{priority} do not matter; only their relative ordering. +As with the @var{priority} argument to the @code{constructor} and +@code{destructor} attributes, a few targets do not support the +@code{init_priority} attribute. In that case the attribute is rejected +with an error rather than ignored. + @cindex @code{no_dangling} type attribute @cindex @code{no_dangling} function attribute @item no_dangling |