From: Sandra Loosemore Date: Wed, 26 Mar 2025 04:16:24 +0000 (+0000) Subject: Doc: Break up and rearrange the "other builtins" section [PR42270] X-Git-Tag: basepoints/gcc-16~510 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=35e0f112a487b38d4d3e8eec101a9e0b33a1016b;p=thirdparty%2Fgcc.git Doc: Break up and rearrange the "other builtins" section [PR42270] This is part of an incremental effort to make the chapter on GCC extensions better organized by grouping/rearranging sections by topic. The "Other Builtins" section had become a catch-all for all sorts of things with very little organization or attempt to differentiate between important information (e.g., GCC treats a gazillion library functions as builtins by default) from obscure builtins provided primarily as internal interfaces. I've split it up into various pieces and attempted to move the more important or useful-to-users documentation earlier in the chapter. What's left of the section is still a jumbled mess... but at least it's a smaller jumbled mess. gcc/ChangeLog PR other/42270 * doc/extend.texi (Built-in Functions): Incorporate some text formerly in "Other Builtins" into the introduction. Adjust menu for new sections. (Library Builtins): New section, split from "Other Builtins". (Numeric Builtins): Likewise. (Stack Allocation): Likewise. (Constructing Calls): Move __builtin_call_with_static_chain here. (Object Size Checking): Minor copy-editing. (Other Builtins): Move text to new sections listed above. Delete duplicate docs for object-size checking builtins. * doc/invoke.texi (C dialect options): Update @xref for -fno-builtin. --- diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 386b6b0f5b1..68f9398590f 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -14208,19 +14208,36 @@ GNU C++. 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, while -others provide the underlying functionality needed to implement +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_}. Except as -otherwise documented, all built-in functions are available from any -of the C family languages supported by GCC. +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. @@ -14238,1433 +14255,12 @@ of the C family languages supported by GCC. * Target Builtins:: Built-in functions specific to particular targets. @end menu -@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{} 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 -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 Return Address -@section Getting the Return or Frame Address of a Function - -These functions may be used to get information about the callers of a -function. - -@defbuiltin{{void *} __builtin_return_address (unsigned int @var{level})} -This function returns the return address of the current function, or of -one of its callers. The @var{level} argument is number of frames to -scan up the call stack. A value of @code{0} yields the return address -of the current function, a value of @code{1} yields the return address -of the caller of the current function, and so forth. When inlining -the expected behavior is that the function returns the address of -the function that is returned to. To work around this behavior use -the @code{noinline} function attribute. - -The @var{level} argument must be a constant integer. - -On some machines it may be impossible to determine the return address of -any function other than the current one; in such cases, or when the top -of the stack has been reached, this function returns an unspecified -value. In addition, @code{__builtin_frame_address} may be used -to determine if the top of the stack has been reached. - -Additional post-processing of the returned value may be needed, see -@code{__builtin_extract_return_addr}. - -The stored representation of the return address in memory may be different -from the address returned by @code{__builtin_return_address}. For example, -on AArch64 the stored address may be mangled with return address signing -whereas the address returned by @code{__builtin_return_address} is not. - -Calling this function with a nonzero argument can have unpredictable -effects, including crashing the calling program. As a result, calls -that are considered unsafe are diagnosed when the @option{-Wframe-address} -option is in effect. Such calls should only be made in debugging -situations. - -On targets where code addresses are representable as @code{void *}, -@smallexample -void *addr = __builtin_extract_return_addr (__builtin_return_address (0)); -@end smallexample -gives the code address where the current function would return. For example, -such an address may be used with @code{dladdr} or other interfaces that work -with code addresses. -@enddefbuiltin - -@defbuiltin{{void *} __builtin_extract_return_addr (void *@var{addr})} -The address as returned by @code{__builtin_return_address} may have to be fed -through this function to get the actual encoded address. For example, on the -31-bit S/390 platform the highest bit has to be masked out, or on SPARC -platforms an offset has to be added for the true next instruction to be -executed. - -If no fixup is needed, this function simply passes through @var{addr}. -@enddefbuiltin - -@defbuiltin{{void *} __builtin_frob_return_addr (void *@var{addr})} -This function does the reverse of @code{__builtin_extract_return_addr}. -@enddefbuiltin - -@defbuiltin{{void *} __builtin_frame_address (unsigned int @var{level})} -This function is similar to @code{__builtin_return_address}, but it -returns the address of the function frame rather than the return address -of the function. Calling @code{__builtin_frame_address} with a value of -@code{0} yields the frame address of the current function, a value of -@code{1} yields the frame address of the caller of the current function, -and so forth. - -The frame is the area on the stack that holds local variables and saved -registers. The frame address is normally the address of the first word -pushed on to the stack by the function. However, the exact definition -depends upon the processor and the calling convention. If the processor -has a dedicated frame pointer register, and the function has a frame, -then @code{__builtin_frame_address} returns the value of the frame -pointer register. +@node Library Builtins +@section Builtins for C Library Functions +@cindex built-in library functions +@cindex library function builtins +@cindex C library function builtins -On some machines it may be impossible to determine the frame address of -any function other than the current one; in such cases, or when the top -of the stack has been reached, this function returns @code{0} if -the first frame pointer is properly initialized by the startup code. - -Calling this function with a nonzero argument can have unpredictable -effects, including crashing the calling program. As a result, calls -that are considered unsafe are diagnosed when the @option{-Wframe-address} -option is in effect. Such calls should only be made in debugging -situations. -@enddefbuiltin - -@deftypefn {Built-in Function} {void *} __builtin_stack_address () -This function returns the stack pointer register, offset by -@code{STACK_ADDRESS_OFFSET} if that's defined. - -Conceptually, the returned address returned by this built-in function is -the boundary between the stack area allocated for use by its caller, and -the area that could be modified by a function call, that the caller -could safely zero-out before or after (but not during) the call -sequence. - -Arguments for a callee may be preallocated as part of the caller's stack -frame, or allocated on a per-call basis, depending on the target, so -they may be on either side of this boundary. - -Even if the stack pointer is biased, the result is not. The register -save area on SPARC is regarded as modifiable by calls, rather than as -allocated for use by the caller function, since it is never in use while -the caller function itself is running. - -Red zones that only leaf functions could use are also regarded as -modifiable by calls, rather than as allocated for use by the caller. -This is only theoretical, since leaf functions do not issue calls, but a -constant offset makes this built-in function more predictable. -@end deftypefn - -@node Stack Scrubbing -@section Stack scrubbing internal interfaces - -Stack scrubbing involves cooperation between a @code{strub} context, -i.e., a function whose stack frame is to be zeroed-out, and its callers. -The caller initializes a stack watermark, the @code{strub} context -updates the watermark according to its stack use, and the caller zeroes -it out once it regains control, whether by the callee's returning or by -an exception. - -Each of these steps is performed by a different builtin function call. -Calls to these builtins are introduced automatically, in response to -@code{strub} attributes and command-line options; they are not expected -to be explicitly called by source code. - -The functions that implement the builtins are available in libgcc but, -depending on optimization levels, they are expanded internally, adjusted -to account for inlining, and sometimes combined/deferred (e.g. passing -the caller-supplied watermark on to callees, refraining from erasing -stack areas that the caller will) to enable tail calls and to optimize -for code size. - -@deftypefn {Built-in Function} {void} __builtin___strub_enter (void **@var{wmptr}) -This function initializes a stack @var{watermark} variable with the -current top of the stack. A call to this builtin function is introduced -before entering a @code{strub} context. It remains as a function call -if optimization is not enabled. -@end deftypefn - -@deftypefn {Built-in Function} {void} __builtin___strub_update (void **@var{wmptr}) -This function updates a stack @var{watermark} variable with the current -top of the stack, if it tops the previous watermark. A call to this -builtin function is inserted within @code{strub} contexts, whenever -additional stack space may have been used. It remains as a function -call at optimization levels lower than 2. -@end deftypefn - -@deftypefn {Built-in Function} {void} __builtin___strub_leave (void **@var{wmptr}) -This function overwrites the memory area between the current top of the -stack, and the @var{watermark}ed address. A call to this builtin -function is inserted after leaving a @code{strub} context. It remains -as a function call at optimization levels lower than 3, and it is guarded by -a condition at level 2. -@end deftypefn - -@node Vector Extensions -@section Using Vector Instructions through Built-in Functions - -On some targets, the instruction set contains SIMD vector instructions which -operate on multiple values contained in one large register at the same time. -For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used -this way. - -The first step in using these extensions is to provide the necessary data -types. This should be done using an appropriate @code{typedef}: - -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); -@end smallexample - -@noindent -The @code{int} type specifies the @dfn{base type} (which can be a -@code{typedef}), while the attribute specifies the vector size for the -variable, measured in bytes. For example, the declaration above causes -the compiler to set the mode for the @code{v4si} type to be 16 bytes wide -and divided into @code{int} sized units. For a 32-bit @code{int} this -means a vector of 4 units of 4 bytes, and the corresponding mode of -@code{foo} is @acronym{V4SI}. - -The @code{vector_size} attribute is only applicable to integral and -floating scalars, although arrays, pointers, and function return values -are allowed in conjunction with this construct. Only sizes that are -positive power-of-two multiples of the base type size are currently allowed. - -All the basic integer types can be used as base types, both as signed -and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, -@code{long long}. In addition, @code{float} and @code{double} can be -used to build floating-point vector types. - -Specifying a combination that is not valid for the current architecture -causes GCC to synthesize the instructions using a narrower mode. -For example, if you specify a variable of type @code{V4SI} and your -architecture does not allow for this specific SIMD type, GCC -produces code that uses 4 @code{SIs}. - -The types defined in this manner can be used with a subset of normal C -operations. Currently, GCC allows using the following operators -on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. - -The operations behave like C++ @code{valarrays}. Addition is defined as -the addition of the corresponding elements of the operands. For -example, in the code below, each of the 4 elements in @var{a} is -added to the corresponding 4 elements in @var{b} and the resulting -vector is stored in @var{c}. - -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); - -v4si a, b, c; - -c = a + b; -@end smallexample - -Subtraction, multiplication, division, and the logical operations -operate in a similar manner. Likewise, the result of using the unary -minus or complement operators on a vector type is a vector whose -elements are the negative or complemented values of the corresponding -elements in the operand. - -It is possible to use shifting operators @code{<<}, @code{>>} on -integer-type vectors. The operation is defined as following: @code{@{a0, -a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, -@dots{}, an >> bn@}}@. Unlike OpenCL, values of @code{b} are not -implicitly taken modulo bit width of the base type @code{B}, and the behavior -is undefined if any @code{bi} is greater than or equal to @code{B}. - -In contrast to scalar operations in C and C++, operands of integer vector -operations do not undergo integer promotions. - -Operands of binary vector operations must have the same number of -elements. - -For convenience, it is allowed to use a binary vector operation -where one operand is a scalar. In that case the compiler transforms -the scalar operand into a vector where each element is the scalar from -the operation. The transformation happens only if the scalar could be -safely converted to the vector-element type. -Consider the following code. - -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); - -v4si a, b, c; -long l; - -a = b + 1; /* a = b + @{1,1,1,1@}; */ -a = 2 * b; /* a = @{2,2,2,2@} * b; */ - -a = l + a; /* Error, cannot convert long to int. */ -@end smallexample - -Vectors can be subscripted as if the vector were an array with -the same number of elements and base type. Out of bound accesses -invoke undefined behavior at run time. Warnings for out of bound -accesses for vector subscription can be enabled with -@option{-Warray-bounds}. - -Vector comparison is supported with standard comparison -operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be -vector expressions of integer-type or real-type. Comparison between -integer-type vectors and real-type vectors are not supported. The -result of the comparison is a vector of the same width and number of -elements as the comparison operands with a signed integral element -type. - -Vectors are compared element-wise producing 0 when comparison is false -and -1 (constant of the appropriate type where all bits are set) -otherwise. Consider the following example. - -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); - -v4si a = @{1,2,3,4@}; -v4si b = @{3,2,1,4@}; -v4si c; - -c = a > b; /* The result would be @{0, 0,-1, 0@} */ -c = a == b; /* The result would be @{0,-1, 0,-1@} */ -@end smallexample - -In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where -@code{b} and @code{c} are vectors of the same type and @code{a} is an -integer vector with the same number of elements of the same size as @code{b} -and @code{c}, computes all three arguments and creates a vector -@code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in -OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}. -As in the case of binary operations, this syntax is also accepted when -one of @code{b} or @code{c} is a scalar that is then transformed into a -vector. If both @code{b} and @code{c} are scalars and the type of -@code{true?b:c} has the same size as the element type of @code{a}, then -@code{b} and @code{c} are converted to a vector type whose elements have -this type and with the same number of elements as @code{a}. - -In C++, the logic operators @code{!, &&, ||} are available for vectors. -@code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to -@code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}. -For mixed operations between a scalar @code{s} and a vector @code{v}, -@code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is -short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}. - -@findex __builtin_shuffle -Vector shuffling is available using functions -@code{__builtin_shuffle (vec, mask)} and -@code{__builtin_shuffle (vec0, vec1, mask)}. -Both functions construct a permutation of elements from one or two -vectors and return a vector of the same type as the input vector(s). -The @var{mask} is an integral vector with the same width (@var{W}) -and element count (@var{N}) as the output vector. - -The elements of the input vectors are numbered in memory ordering of -@var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The -elements of @var{mask} are considered modulo @var{N} in the single-operand -case and modulo @math{2*@var{N}} in the two-operand case. - -Consider the following example, - -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); - -v4si a = @{1,2,3,4@}; -v4si b = @{5,6,7,8@}; -v4si mask1 = @{0,1,1,3@}; -v4si mask2 = @{0,4,2,5@}; -v4si res; - -res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */ -res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */ -@end smallexample - -Note that @code{__builtin_shuffle} is intentionally semantically -compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions. - -You can declare variables and use them in function calls and returns, as -well as in assignments and some casts. You can specify a vector type as -a return type for a function. Vector types can also be used as function -arguments. It is possible to cast from one vector type to another, -provided they are of the same size (in fact, you can also cast vectors -to and from other data types of the same size). - -You cannot operate between vectors of different lengths or different -signedness without a cast. - -@findex __builtin_shufflevector -Vector shuffling is available using the -@code{__builtin_shufflevector (vec1, vec2, index...)} -function. @var{vec1} and @var{vec2} must be expressions with -vector type with a compatible element type. The result of -@code{__builtin_shufflevector} is a vector with the same element type -as @var{vec1} and @var{vec2} but that has an element count equal to -the number of indices specified. - -The @var{index} arguments are a list of integers that specify the -elements indices of the first two vectors that should be extracted and -returned in a new vector. These element indices are numbered sequentially -starting with the first vector, continuing into the second vector. -An index of -1 can be used to indicate that the corresponding element in -the returned vector is a don't care and can be freely chosen to optimized -the generated code sequence performing the shuffle operation. - -Consider the following example, -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); -typedef int v8si __attribute__ ((vector_size (32))); - -v8si a = @{1,-2,3,-4,5,-6,7,-8@}; -v4si b = __builtin_shufflevector (a, a, 0, 2, 4, 6); /* b is @{1,3,5,7@} */ -v4si c = @{-2,-4,-6,-8@}; -v8si d = __builtin_shufflevector (c, b, 4, 0, 5, 1, 6, 2, 7, 3); /* d is a */ -@end smallexample - -@findex __builtin_convertvector -Vector conversion is available using the -@code{__builtin_convertvector (vec, vectype)} -function. @var{vec} must be an expression with integral or floating -vector type and @var{vectype} an integral or floating vector type with the -same number of elements. The result has @var{vectype} type and value of -a C cast of every element of @var{vec} to the element type of @var{vectype}. - -Consider the following example, -@smallexample -typedef int v4si __attribute__ ((vector_size (16))); -typedef float v4sf __attribute__ ((vector_size (16))); -typedef double v4df __attribute__ ((vector_size (32))); -typedef unsigned long long v4di __attribute__ ((vector_size (32))); - -v4si a = @{1,-2,3,-4@}; -v4sf b = @{1.5f,-2.5f,3.f,7.f@}; -v4di c = @{1ULL,5ULL,0ULL,10ULL@}; -v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */ -/* Equivalent of: - v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */ -v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */ -v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */ -v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */ -v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */ -@end smallexample - -@cindex vector types, using with x86 intrinsics -Sometimes it is desirable to write code using a mix of generic vector -operations (for clarity) and machine-specific vector intrinsics (to -access vector instructions that are not exposed via generic built-ins). -On x86, intrinsic functions for integer vectors typically use the same -vector type @code{__m128i} irrespective of how they interpret the vector, -making it necessary to cast their arguments and return values from/to -other vector types. In C, you can make use of a @code{union} type: -@c In C++ such type punning via a union is not allowed by the language -@smallexample -#include - -typedef unsigned char u8x16 __attribute__ ((vector_size (16))); -typedef unsigned int u32x4 __attribute__ ((vector_size (16))); - -typedef union @{ - __m128i mm; - u8x16 u8; - u32x4 u32; -@} v128; -@end smallexample - -@noindent -for variables that can be used with both built-in operators and x86 -intrinsics: - -@smallexample -v128 x, y = @{ 0 @}; -memcpy (&x, ptr, sizeof x); -y.u8 += 0x80; -x.mm = _mm_adds_epu8 (x.mm, y.mm); -x.u32 &= 0xffffff; - -/* Instead of a variable, a compound literal may be used to pass the - return value of an intrinsic call to a function expecting the union: */ -v128 foo (v128); -x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@}); -@c This could be done implicitly with __attribute__((transparent_union)), -@c but GCC does not accept it for unions of vector types (PR 88955). -@end smallexample - -@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. - -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 - -@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 - -@node __atomic Builtins -@section Built-in Functions for Memory Model Aware Atomic Operations - -The following built-in functions approximately match the requirements -for the C++11 memory model. They are all -identified by being prefixed with @samp{__atomic} and most are -overloaded so that they work with multiple types. - -These functions are intended to replace the legacy @samp{__sync} -builtins. The main difference is that the memory order that is requested -is a parameter to the functions. New code should always use the -@samp{__atomic} builtins rather than the @samp{__sync} builtins. - -Note that the @samp{__atomic} builtins assume that programs will -conform to the C++11 memory model. In particular, they assume -that programs are free of data races. See the C++11 standard for -detailed requirements. - -The @samp{__atomic} builtins can be used with any integral scalar or -pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral -types are also allowed if @samp{__int128} (@pxref{__int128}) is -supported by the architecture. - -The four non-arithmetic functions (load, store, exchange, and -compare_exchange) all have a generic version as well. This generic -version works on any data type. It uses the lock-free built-in function -if the specific data type size makes that possible; otherwise, an -external call is left to be resolved at run time. This external call is -the same format with the addition of a @samp{size_t} parameter inserted -as the first parameter indicating the size of the object being pointed to. -All objects must be the same size. - -There are 6 different memory orders that can be specified. These map -to the C++11 memory orders with the same names, see the C++11 standard -or the @uref{https://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki -on atomic synchronization} for detailed definitions. Individual -targets may also support additional memory orders for use on specific -architectures. Refer to the target documentation for details of -these. - -An atomic operation can both constrain code motion and -be mapped to hardware instructions for synchronization between threads -(e.g., a fence). To which extent this happens is controlled by the -memory orders, which are listed here in approximately ascending order of -strength. The description of each memory order is only meant to roughly -illustrate the effects and is not a specification; see the C++11 -memory model for precise semantics. - -@table @code -@item __ATOMIC_RELAXED -Implies no inter-thread ordering constraints. -@item __ATOMIC_CONSUME -This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE} -memory order because of a deficiency in C++11's semantics for -@code{memory_order_consume}. -@item __ATOMIC_ACQUIRE -Creates an inter-thread happens-before constraint from the release (or -stronger) semantic store to this acquire load. Can prevent hoisting -of code to before the operation. -@item __ATOMIC_RELEASE -Creates an inter-thread happens-before constraint to acquire (or stronger) -semantic loads that read from this release store. Can prevent sinking -of code to after the operation. -@item __ATOMIC_ACQ_REL -Combines the effects of both @code{__ATOMIC_ACQUIRE} and -@code{__ATOMIC_RELEASE}. -@item __ATOMIC_SEQ_CST -Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations. -@end table - -Note that in the C++11 memory model, @emph{fences} (e.g., -@samp{__atomic_thread_fence}) take effect in combination with other -atomic operations on specific memory locations (e.g., atomic loads); -operations on specific memory locations do not necessarily affect other -operations in the same way. - -Target architectures are encouraged to provide their own patterns for -each of the atomic built-in functions. If no target is provided, the original -non-memory model set of @samp{__sync} atomic built-in functions are -used, along with any required synchronization fences surrounding it in -order to achieve the proper behavior. Execution in this case is subject -to the same restrictions as those built-in functions. - -If there is no pattern or mechanism to provide a lock-free instruction -sequence, a call is made to an external routine with the same parameters -to be resolved at run time. - -When implementing patterns for these built-in functions, the memory order -parameter can be ignored as long as the pattern implements the most -restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory -orders execute correctly with this memory order but they may not execute as -efficiently as they could with a more appropriate implementation of the -relaxed requirements. - -Note that the C++11 standard allows for the memory order parameter to be -determined at run time rather than at compile time. These built-in -functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather -than invoke a runtime library call or inline a switch statement. This is -standard compliant, safe, and the simplest approach for now. - -The memory order parameter is a signed int, but only the lower 16 bits are -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. - -@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}}. - -The valid memory order variants are -@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, -and @code{__ATOMIC_CONSUME}. - -@enddefbuiltin - -@defbuiltin{void __atomic_load (@var{type} *@var{ptr}, @var{type} *@var{ret}, int @var{memorder})} -This is the generic version of an atomic load. It returns the -contents of @code{*@var{ptr}} in @code{*@var{ret}}. - -@enddefbuiltin - -@defbuiltin{void __atomic_store_n (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -This built-in function implements an atomic store operation. It writes -@code{@var{val}} into @code{*@var{ptr}}. - -The valid memory order variants are -@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}. - -@enddefbuiltin - -@defbuiltin{void __atomic_store (@var{type} *@var{ptr}, @var{type} *@var{val}, int @var{memorder})} -This is the generic version of an atomic store. It stores the value -of @code{*@var{val}} into @code{*@var{ptr}}. - -@enddefbuiltin - -@defbuiltin{@var{type} __atomic_exchange_n (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -This built-in function implements an atomic exchange operation. It writes -@var{val} into @code{*@var{ptr}}, and returns the previous contents of -@code{*@var{ptr}}. - -All memory order variants are valid. - -@enddefbuiltin - -@defbuiltin{void __atomic_exchange (@var{type} *@var{ptr}, @var{type} *@var{val}, @var{type} *@var{ret}, int @var{memorder})} -This is the generic version of an atomic exchange. It stores the -contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value -of @code{*@var{ptr}} is copied into @code{*@var{ret}}. - -@enddefbuiltin - -@defbuiltin{bool __atomic_compare_exchange_n (@var{type} *@var{ptr}, @var{type} *@var{expected}, @var{type} @var{desired}, bool @var{weak}, int @var{success_memorder}, int @var{failure_memorder})} -This built-in function implements an atomic compare and exchange operation. -This compares the contents of @code{*@var{ptr}} with the contents of -@code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write} -operation that writes @var{desired} into @code{*@var{ptr}}. If they are not -equal, the operation is a @emph{read} and the current contents of -@code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true} -for weak compare_exchange, which may fail spuriously, and @code{false} for -the strong variation, which never fails spuriously. Many targets -only offer the strong variation and ignore the parameter. When in doubt, use -the strong variation. - -If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned -and memory is affected according to the -memory order specified by @var{success_memorder}. There are no -restrictions on what memory order can be used here. - -Otherwise, @code{false} is returned and memory is affected according -to @var{failure_memorder}. This memory order cannot be -@code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a -stronger order than that specified by @var{success_memorder}. - -@enddefbuiltin - -@defbuiltin{bool __atomic_compare_exchange (@var{type} *@var{ptr}, @var{type} *@var{expected}, @var{type} *@var{desired}, bool @var{weak}, int @var{success_memorder}, int @var{failure_memorder})} -This built-in function implements the generic version of -@code{__atomic_compare_exchange}. The function is virtually identical to -@code{__atomic_compare_exchange_n}, except the desired value is also a -pointer. - -@enddefbuiltin - -@defbuiltin{@var{type} __atomic_add_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -@defbuiltinx{@var{type} __atomic_sub_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -@defbuiltinx{@var{type} __atomic_and_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -@defbuiltinx{@var{type} __atomic_xor_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -@defbuiltinx{@var{type} __atomic_or_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -@defbuiltinx{@var{type} __atomic_nand_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -These built-in functions perform the operation suggested by the name, and -return the result of the operation. 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 -@{ *ptr @var{op}= val; return *ptr; @} -@{ *ptr = ~(*ptr & val); return *ptr; @} // 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. All memory orders are valid. - -@enddefbuiltin - -@defbuiltin{@var{type} __atomic_fetch_add (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -@defbuiltinx{@var{type} __atomic_fetch_sub (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -@defbuiltinx{@var{type} __atomic_fetch_and (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -@defbuiltinx{@var{type} __atomic_fetch_xor (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -@defbuiltinx{@var{type} __atomic_fetch_or (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -@defbuiltinx{@var{type} __atomic_fetch_nand (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} -These built-in functions perform the operation suggested by the name, and -return the value that had previously been in @code{*@var{ptr}}. 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}= val; return tmp; @} -@{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand -@end smallexample - -The same constraints on arguments apply as for the corresponding -@code{__atomic_op_fetch} built-in functions. All memory orders are valid. - -@enddefbuiltin - -@defbuiltin{bool __atomic_test_and_set (void *@var{ptr}, int @var{memorder})} - -This built-in function performs an atomic test-and-set operation on -the byte at @code{*@var{ptr}}. The byte is set to some implementation -defined nonzero ``set'' value and the return value is @code{true} if and only -if the previous contents were ``set''. -It should be only used for operands of type @code{bool} or @code{char}. For -other types only part of the value may be set. - -All memory orders are valid. - -@enddefbuiltin - -@defbuiltin{void __atomic_clear (bool *@var{ptr}, int @var{memorder})} - -This built-in function performs an atomic clear operation on -@code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0. -It should be only used for operands of type @code{bool} or @code{char} and -in conjunction with @code{__atomic_test_and_set}. -For other types it may only clear partially. If the type is not @code{bool} -prefer using @code{__atomic_store}. - -The valid memory order variants are -@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and -@code{__ATOMIC_RELEASE}. - -@enddefbuiltin - -@defbuiltin{void __atomic_thread_fence (int @var{memorder})} - -This built-in function acts as a synchronization fence between threads -based on the specified memory order. - -All memory orders are valid. - -@enddefbuiltin - -@defbuiltin{void __atomic_signal_fence (int @var{memorder})} - -This built-in function acts as a synchronization fence between a thread -and signal handlers based in the same thread. - -All memory orders are valid. - -@enddefbuiltin - -@defbuiltin{bool __atomic_always_lock_free (size_t @var{size}, void *@var{ptr})} - -This built-in function returns @code{true} if objects of @var{size} bytes always -generate lock-free atomic instructions for the target architecture. -@var{size} must resolve to a compile-time constant and the result also -resolves to a compile-time constant. - -@var{ptr} is an optional pointer to the object that may be used to determine -alignment. A value of 0 indicates typical alignment should be used. The -compiler may also ignore this parameter. - -@smallexample -if (__atomic_always_lock_free (sizeof (long long), 0)) -@end smallexample - -@enddefbuiltin - -@defbuiltin{bool __atomic_is_lock_free (size_t @var{size}, void *@var{ptr})} - -This built-in function returns @code{true} if objects of @var{size} bytes always -generate lock-free atomic instructions for the target architecture. If -the built-in function is not known to be lock-free, a call is made to a -runtime routine named @code{__atomic_is_lock_free}. - -@var{ptr} is an optional pointer to the object that may be used to determine -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})} - -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 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. - -@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 // 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 - -@node Object Size Checking -@section Object Size Checking - -@subsection Object Size Checking Built-in Functions -@findex __builtin___memcpy_chk -@findex __builtin___mempcpy_chk -@findex __builtin___memmove_chk -@findex __builtin___memset_chk -@findex __builtin___strcpy_chk -@findex __builtin___stpcpy_chk -@findex __builtin___strncpy_chk -@findex __builtin___strcat_chk -@findex __builtin___strncat_chk - -GCC implements a limited buffer overflow protection mechanism that can -prevent some buffer overflow attacks by determining the sizes of objects -into which data is about to be written and preventing the writes when -the size isn't sufficient. The built-in functions described below yield -the best results when used together and when optimization is enabled. -For example, to detect object sizes across function boundaries or to -follow pointer assignments through non-trivial control flow they rely -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 -@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 -the storage to be declared with the @code{alloc_size} attribute (@pxref{Common -Function Attributes}). @code{__builtin_object_size} never evaluates -its arguments for side effects. If there are any side effects in them, it -returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} -for @var{type} 2 or 3. If there are multiple objects @var{ptr} can -point to and all of them are known at compile time, the returned number -is the maximum of remaining byte counts in those objects if @var{type} & 2 is -0 and minimum if nonzero. If it is not possible to determine which objects -@var{ptr} points to at compile time, @code{__builtin_object_size} should -return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} -for @var{type} 2 or 3. - -@var{type} is an integer constant from 0 to 3. If the least significant -bit is clear, objects are whole variables, if it is set, a closest -surrounding subobject is considered the object a pointer points to. -The second bit determines if maximum or minimum of remaining bytes -is computed. - -@smallexample -struct V @{ char buf1[10]; int b; char buf2[10]; @} var; -char *p = &var.buf1[1], *q = &var.b; - -/* Here the object p points to is var. */ -assert (__builtin_object_size (p, 0) == sizeof (var) - 1); -/* The subobject p points to is var.buf1. */ -assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); -/* The object q points to is var. */ -assert (__builtin_object_size (q, 0) - == (char *) (&var + 1) - (char *) &var.b); -/* The subobject q points to is var.b. */ -assert (__builtin_object_size (q, 1) == sizeof (var.b)); -@end smallexample -@enddefbuiltin - -@defbuiltin{{size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})} -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 -evaluation of object size estimates in a wider range of use cases and can be -more precise than @code{__builtin_object_size}, but it incurs a performance -penalty since it may add a runtime overhead on size computation. Semantics of -@var{type} as well as return values in case it is not possible to determine -which objects @var{ptr} points to at compile time are the same as in the case -of @code{__builtin_object_size}. -@enddefbuiltin - -@subsection Object Size Checking and Source Fortification - -Hardening of function calls using the @code{_FORTIFY_SOURCE} macro is -one of the key uses of the object size checking built-in functions. To -make implementation of these features more convenient and improve -optimization and diagnostics, there are built-in functions added for -many common string operation functions, e.g., for @code{memcpy} -@code{__builtin___memcpy_chk} built-in is provided. This built-in has -an additional last argument, which is the number of bytes remaining in -the object the @var{dest} argument points to or @code{(size_t) -1} if -the size is not known. - -The built-in functions are optimized into the normal string functions -like @code{memcpy} if the last argument is @code{(size_t) -1} or if -it is known at compile time that the destination object will not -be overflowed. If the compiler can determine at compile time that the -object will always be overflowed, it issues a warning. - -The intended use can be e.g.@: - -@smallexample -#undef memcpy -#define bos0(dest) __builtin_object_size (dest, 0) -#define memcpy(dest, src, n) \ - __builtin___memcpy_chk (dest, src, n, bos0 (dest)) - -char *volatile p; -char buf[10]; -/* It is unknown what object p points to, so this is optimized - into plain memcpy - no checking is possible. */ -memcpy (p, "abcde", n); -/* Destination is known and length too. It is known at compile - time there will be no overflow. */ -memcpy (&buf[5], "abcde", 5); -/* Destination is known, but the length is not known at compile time. - This will result in __memcpy_chk call that can check for overflow - at run time. */ -memcpy (&buf[5], "abcde", n); -/* Destination is known and it is known at compile time there will - be overflow. There will be a warning and __memcpy_chk call that - will abort the program at run time. */ -memcpy (&buf[6], "abcde", 5); -@end smallexample - -Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, -@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, -@code{strcat} and @code{strncat}. - -@subsubsection Formatted Output Function Checking -@defbuiltin{int __builtin___sprintf_chk @ - (char *@var{s}, int @var{flag}, size_t @var{os}, @ - const char *@var{fmt}, ...)} -@defbuiltinx{int __builtin___snprintf_chk @ - (char *@var{s}, size_t @var{maxlen}, int @var{flag}, @ - size_t @var{os}, const char *@var{fmt}, ...)} -@defbuiltinx{int __builtin___vsprintf_chk @ - (char *@var{s}, int @var{flag}, size_t @var{os}, @ - const char *@var{fmt}, va_list @var{ap})} -@defbuiltinx{int __builtin___vsnprintf_chk @ - (char *@var{s}, size_t @var{maxlen}, int @var{flag}, @ - size_t @var{os}, const char *@var{fmt}, @ - va_list @var{ap})} - -The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} -etc.@: functions and can contain implementation specific flags on what -additional security measures the checking function might take, such as -handling @code{%n} differently. - -The @var{os} argument is the object size @var{s} points to, like in the -other built-in functions. There is a small difference in the behavior -though, if @var{os} is @code{(size_t) -1}, the built-in functions are -optimized into the non-checking functions only if @var{flag} is 0, otherwise -the checking function is called with @var{os} argument set to -@code{(size_t) -1}. - -In addition to this, there are checking built-in functions -@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, -@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. -These have just one additional argument, @var{flag}, right before -format string @var{fmt}. If the compiler is able to optimize them to -@code{fputc} etc.@: functions, it does, otherwise the checking function -is called and the @var{flag} argument passed to it. -@enddefbuiltin - -@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. - -@smallexample -void foo () @{ - int *a = new int; - delete a; // This pair of allocation/deallocation operators can be omitted - // or replaced with int _temp; int *a = &_temp; etc.@: - void *b = ::operator new (32); - ::operator delete (b); // This one cannnot. - void *c = __builtin_operator_new (32); - __builtin_operator_delete (c); // This one can. -@} -@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 @@ -16058,1651 +14654,3103 @@ void foo () @{ @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. +@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. +@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 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{} 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 +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 + +These functions may be used to get information about the callers of a +function. + +@defbuiltin{{void *} __builtin_return_address (unsigned int @var{level})} +This function returns the return address of the current function, or of +one of its callers. The @var{level} argument is number of frames to +scan up the call stack. A value of @code{0} yields the return address +of the current function, a value of @code{1} yields the return address +of the caller of the current function, and so forth. When inlining +the expected behavior is that the function returns the address of +the function that is returned to. To work around this behavior use +the @code{noinline} function attribute. + +The @var{level} argument must be a constant integer. + +On some machines it may be impossible to determine the return address of +any function other than the current one; in such cases, or when the top +of the stack has been reached, this function returns an unspecified +value. In addition, @code{__builtin_frame_address} may be used +to determine if the top of the stack has been reached. + +Additional post-processing of the returned value may be needed, see +@code{__builtin_extract_return_addr}. + +The stored representation of the return address in memory may be different +from the address returned by @code{__builtin_return_address}. For example, +on AArch64 the stored address may be mangled with return address signing +whereas the address returned by @code{__builtin_return_address} is not. + +Calling this function with a nonzero argument can have unpredictable +effects, including crashing the calling program. As a result, calls +that are considered unsafe are diagnosed when the @option{-Wframe-address} +option is in effect. Such calls should only be made in debugging +situations. + +On targets where code addresses are representable as @code{void *}, +@smallexample +void *addr = __builtin_extract_return_addr (__builtin_return_address (0)); +@end smallexample +gives the code address where the current function would return. For example, +such an address may be used with @code{dladdr} or other interfaces that work +with code addresses. +@enddefbuiltin + +@defbuiltin{{void *} __builtin_extract_return_addr (void *@var{addr})} +The address as returned by @code{__builtin_return_address} may have to be fed +through this function to get the actual encoded address. For example, on the +31-bit S/390 platform the highest bit has to be masked out, or on SPARC +platforms an offset has to be added for the true next instruction to be +executed. + +If no fixup is needed, this function simply passes through @var{addr}. +@enddefbuiltin + +@defbuiltin{{void *} __builtin_frob_return_addr (void *@var{addr})} +This function does the reverse of @code{__builtin_extract_return_addr}. +@enddefbuiltin + +@defbuiltin{{void *} __builtin_frame_address (unsigned int @var{level})} +This function is similar to @code{__builtin_return_address}, but it +returns the address of the function frame rather than the return address +of the function. Calling @code{__builtin_frame_address} with a value of +@code{0} yields the frame address of the current function, a value of +@code{1} yields the frame address of the caller of the current function, +and so forth. + +The frame is the area on the stack that holds local variables and saved +registers. The frame address is normally the address of the first word +pushed on to the stack by the function. However, the exact definition +depends upon the processor and the calling convention. If the processor +has a dedicated frame pointer register, and the function has a frame, +then @code{__builtin_frame_address} returns the value of the frame +pointer register. + +On some machines it may be impossible to determine the frame address of +any function other than the current one; in such cases, or when the top +of the stack has been reached, this function returns @code{0} if +the first frame pointer is properly initialized by the startup code. + +Calling this function with a nonzero argument can have unpredictable +effects, including crashing the calling program. As a result, calls +that are considered unsafe are diagnosed when the @option{-Wframe-address} +option is in effect. Such calls should only be made in debugging +situations. +@enddefbuiltin + +@deftypefn {Built-in Function} {void *} __builtin_stack_address () +This function returns the stack pointer register, offset by +@code{STACK_ADDRESS_OFFSET} if that's defined. + +Conceptually, the returned address returned by this built-in function is +the boundary between the stack area allocated for use by its caller, and +the area that could be modified by a function call, that the caller +could safely zero-out before or after (but not during) the call +sequence. + +Arguments for a callee may be preallocated as part of the caller's stack +frame, or allocated on a per-call basis, depending on the target, so +they may be on either side of this boundary. + +Even if the stack pointer is biased, the result is not. The register +save area on SPARC is regarded as modifiable by calls, rather than as +allocated for use by the caller function, since it is never in use while +the caller function itself is running. + +Red zones that only leaf functions could use are also regarded as +modifiable by calls, rather than as allocated for use by the caller. +This is only theoretical, since leaf functions do not issue calls, but a +constant offset makes this built-in function more predictable. +@end deftypefn + +@node Stack Scrubbing +@section Stack scrubbing internal interfaces + +Stack scrubbing involves cooperation between a @code{strub} context, +i.e., a function whose stack frame is to be zeroed-out, and its callers. +The caller initializes a stack watermark, the @code{strub} context +updates the watermark according to its stack use, and the caller zeroes +it out once it regains control, whether by the callee's returning or by +an exception. + +Each of these steps is performed by a different builtin function call. +Calls to these builtins are introduced automatically, in response to +@code{strub} attributes and command-line options; they are not expected +to be explicitly called by source code. + +The functions that implement the builtins are available in libgcc but, +depending on optimization levels, they are expanded internally, adjusted +to account for inlining, and sometimes combined/deferred (e.g. passing +the caller-supplied watermark on to callees, refraining from erasing +stack areas that the caller will) to enable tail calls and to optimize +for code size. + +@deftypefn {Built-in Function} {void} __builtin___strub_enter (void **@var{wmptr}) +This function initializes a stack @var{watermark} variable with the +current top of the stack. A call to this builtin function is introduced +before entering a @code{strub} context. It remains as a function call +if optimization is not enabled. +@end deftypefn + +@deftypefn {Built-in Function} {void} __builtin___strub_update (void **@var{wmptr}) +This function updates a stack @var{watermark} variable with the current +top of the stack, if it tops the previous watermark. A call to this +builtin function is inserted within @code{strub} contexts, whenever +additional stack space may have been used. It remains as a function +call at optimization levels lower than 2. +@end deftypefn + +@deftypefn {Built-in Function} {void} __builtin___strub_leave (void **@var{wmptr}) +This function overwrites the memory area between the current top of the +stack, and the @var{watermark}ed address. A call to this builtin +function is inserted after leaving a @code{strub} context. It remains +as a function call at optimization levels lower than 3, and it is guarded by +a condition at level 2. +@end deftypefn + +@node Vector Extensions +@section Using Vector Instructions through Built-in Functions + +On some targets, the instruction set contains SIMD vector instructions which +operate on multiple values contained in one large register at the same time. +For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used +this way. + +The first step in using these extensions is to provide the necessary data +types. This should be done using an appropriate @code{typedef}: + +@smallexample +typedef int v4si __attribute__ ((vector_size (16))); +@end smallexample + +@noindent +The @code{int} type specifies the @dfn{base type} (which can be a +@code{typedef}), while the attribute specifies the vector size for the +variable, measured in bytes. For example, the declaration above causes +the compiler to set the mode for the @code{v4si} type to be 16 bytes wide +and divided into @code{int} sized units. For a 32-bit @code{int} this +means a vector of 4 units of 4 bytes, and the corresponding mode of +@code{foo} is @acronym{V4SI}. + +The @code{vector_size} attribute is only applicable to integral and +floating scalars, although arrays, pointers, and function return values +are allowed in conjunction with this construct. Only sizes that are +positive power-of-two multiples of the base type size are currently allowed. + +All the basic integer types can be used as base types, both as signed +and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, +@code{long long}. In addition, @code{float} and @code{double} can be +used to build floating-point vector types. + +Specifying a combination that is not valid for the current architecture +causes GCC to synthesize the instructions using a narrower mode. +For example, if you specify a variable of type @code{V4SI} and your +architecture does not allow for this specific SIMD type, GCC +produces code that uses 4 @code{SIs}. + +The types defined in this manner can be used with a subset of normal C +operations. Currently, GCC allows using the following operators +on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. + +The operations behave like C++ @code{valarrays}. Addition is defined as +the addition of the corresponding elements of the operands. For +example, in the code below, each of the 4 elements in @var{a} is +added to the corresponding 4 elements in @var{b} and the resulting +vector is stored in @var{c}. + +@smallexample +typedef int v4si __attribute__ ((vector_size (16))); + +v4si a, b, c; -The remaining functions are provided for optimization purposes. +c = a + b; +@end smallexample -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. +Subtraction, multiplication, division, and the logical operations +operate in a similar manner. Likewise, the result of using the unary +minus or complement operators on a vector type is a vector whose +elements are the negative or complemented values of the corresponding +elements in the operand. -@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. +It is possible to use shifting operators @code{<<}, @code{>>} on +integer-type vectors. The operation is defined as following: @code{@{a0, +a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, +@dots{}, an >> bn@}}@. Unlike OpenCL, values of @code{b} are not +implicitly taken modulo bit width of the base type @code{B}, and the behavior +is undefined if any @code{bi} is greater than or equal to @code{B}. -@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. +In contrast to scalar operations in C and C++, operands of integer vector +operations do not undergo integer promotions. -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}). +Operands of binary vector operations must have the same number of +elements. + +For convenience, it is allowed to use a binary vector operation +where one operand is a scalar. In that case the compiler transforms +the scalar operand into a vector where each element is the scalar from +the operation. The transformation happens only if the scalar could be +safely converted to the vector-element type. +Consider the following code. + +@smallexample +typedef int v4si __attribute__ ((vector_size (16))); + +v4si a, b, c; +long l; + +a = b + 1; /* a = b + @{1,1,1,1@}; */ +a = 2 * b; /* a = @{2,2,2,2@} * b; */ + +a = l + a; /* Error, cannot convert long to int. */ +@end smallexample + +Vectors can be subscripted as if the vector were an array with +the same number of elements and base type. Out of bound accesses +invoke undefined behavior at run time. Warnings for out of bound +accesses for vector subscription can be enabled with +@option{-Warray-bounds}. + +Vector comparison is supported with standard comparison +operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be +vector expressions of integer-type or real-type. Comparison between +integer-type vectors and real-type vectors are not supported. The +result of the comparison is a vector of the same width and number of +elements as the comparison operands with a signed integral element +type. + +Vectors are compared element-wise producing 0 when comparison is false +and -1 (constant of the appropriate type where all bits are set) +otherwise. Consider the following example. + +@smallexample +typedef int v4si __attribute__ ((vector_size (16))); + +v4si a = @{1,2,3,4@}; +v4si b = @{3,2,1,4@}; +v4si c; + +c = a > b; /* The result would be @{0, 0,-1, 0@} */ +c = a == b; /* The result would be @{0,-1, 0,-1@} */ +@end smallexample + +In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where +@code{b} and @code{c} are vectors of the same type and @code{a} is an +integer vector with the same number of elements of the same size as @code{b} +and @code{c}, computes all three arguments and creates a vector +@code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in +OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}. +As in the case of binary operations, this syntax is also accepted when +one of @code{b} or @code{c} is a scalar that is then transformed into a +vector. If both @code{b} and @code{c} are scalars and the type of +@code{true?b:c} has the same size as the element type of @code{a}, then +@code{b} and @code{c} are converted to a vector type whose elements have +this type and with the same number of elements as @code{a}. + +In C++, the logic operators @code{!, &&, ||} are available for vectors. +@code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to +@code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}. +For mixed operations between a scalar @code{s} and a vector @code{v}, +@code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is +short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}. + +@findex __builtin_shuffle +Vector shuffling is available using functions +@code{__builtin_shuffle (vec, mask)} and +@code{__builtin_shuffle (vec0, vec1, mask)}. +Both functions construct a permutation of elements from one or two +vectors and return a vector of the same type as the input vector(s). +The @var{mask} is an integral vector with the same width (@var{W}) +and element count (@var{N}) as the output vector. + +The elements of the input vectors are numbered in memory ordering of +@var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The +elements of @var{mask} are considered modulo @var{N} in the single-operand +case and modulo @math{2*@var{N}} in the two-operand case. + +Consider the following example, + +@smallexample +typedef int v4si __attribute__ ((vector_size (16))); + +v4si a = @{1,2,3,4@}; +v4si b = @{5,6,7,8@}; +v4si mask1 = @{0,1,1,3@}; +v4si mask2 = @{0,4,2,5@}; +v4si res; + +res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */ +res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */ +@end smallexample + +Note that @code{__builtin_shuffle} is intentionally semantically +compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions. + +You can declare variables and use them in function calls and returns, as +well as in assignments and some casts. You can specify a vector type as +a return type for a function. Vector types can also be used as function +arguments. It is possible to cast from one vector type to another, +provided they are of the same size (in fact, you can also cast vectors +to and from other data types of the same size). + +You cannot operate between vectors of different lengths or different +signedness without a cast. + +@findex __builtin_shufflevector +Vector shuffling is available using the +@code{__builtin_shufflevector (vec1, vec2, index...)} +function. @var{vec1} and @var{vec2} must be expressions with +vector type with a compatible element type. The result of +@code{__builtin_shufflevector} is a vector with the same element type +as @var{vec1} and @var{vec2} but that has an element count equal to +the number of indices specified. + +The @var{index} arguments are a list of integers that specify the +elements indices of the first two vectors that should be extracted and +returned in a new vector. These element indices are numbered sequentially +starting with the first vector, continuing into the second vector. +An index of -1 can be used to indicate that the corresponding element in +the returned vector is a don't care and can be freely chosen to optimized +the generated code sequence performing the shuffle operation. + +Consider the following example, +@smallexample +typedef int v4si __attribute__ ((vector_size (16))); +typedef int v8si __attribute__ ((vector_size (32))); + +v8si a = @{1,-2,3,-4,5,-6,7,-8@}; +v4si b = __builtin_shufflevector (a, a, 0, 2, 4, 6); /* b is @{1,3,5,7@} */ +v4si c = @{-2,-4,-6,-8@}; +v8si d = __builtin_shufflevector (c, b, 4, 0, 5, 1, 6, 2, 7, 3); /* d is a */ +@end smallexample + +@findex __builtin_convertvector +Vector conversion is available using the +@code{__builtin_convertvector (vec, vectype)} +function. @var{vec} must be an expression with integral or floating +vector type and @var{vectype} an integral or floating vector type with the +same number of elements. The result has @var{vectype} type and value of +a C cast of every element of @var{vec} to the element type of @var{vectype}. + +Consider the following example, +@smallexample +typedef int v4si __attribute__ ((vector_size (16))); +typedef float v4sf __attribute__ ((vector_size (16))); +typedef double v4df __attribute__ ((vector_size (32))); +typedef unsigned long long v4di __attribute__ ((vector_size (32))); -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_}. +v4si a = @{1,-2,3,-4@}; +v4sf b = @{1.5f,-2.5f,3.f,7.f@}; +v4di c = @{1ULL,5ULL,0ULL,10ULL@}; +v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */ +/* Equivalent of: + v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */ +v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */ +v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */ +v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */ +v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */ +@end smallexample -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}. +@cindex vector types, using with x86 intrinsics +Sometimes it is desirable to write code using a mix of generic vector +operations (for clarity) and machine-specific vector intrinsics (to +access vector instructions that are not exposed via generic built-ins). +On x86, intrinsic functions for integer vectors typically use the same +vector type @code{__m128i} irrespective of how they interpret the vector, +making it necessary to cast their arguments and return values from/to +other vector types. In C, you can make use of a @code{union} type: +@c In C++ such type punning via a union is not allowed by the language +@smallexample +#include -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_}. +typedef unsigned char u8x16 __attribute__ ((vector_size (16))); +typedef unsigned int u32x4 __attribute__ ((vector_size (16))); -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}). +typedef union @{ + __m128i mm; + u8x16 u8; + u32x4 u32; +@} v128; +@end smallexample -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_}. +@noindent +for variables that can be used with both built-in operators and x86 +intrinsics: -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. +@smallexample +v128 x, y = @{ 0 @}; +memcpy (&x, ptr, sizeof x); +y.u8 += 0x80; +x.mm = _mm_adds_epu8 (x.mm, y.mm); +x.u32 &= 0xffffff; -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. +/* Instead of a variable, a compound literal may be used to pass the + return value of an intrinsic call to a function expecting the union: */ +v128 foo (v128); +x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@}); +@c This could be done implicitly with __attribute__((transparent_union)), +@c but GCC does not accept it for unions of vector types (PR 88955). +@end smallexample -@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. +@node __sync Builtins +@section Legacy @code{__sync} Built-in Functions for Atomic Memory Access -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. +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. -@smallexample -void f (unsigned n) -@{ - void *a [8]; - for (int i = 0; i != 8; ++i) - a [i] = __builtin_alloca (n); +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. - g (a, n); // @r{safe} -@} +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 -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. +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{{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. +@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}. -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 +@{ *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}}. -@smallexample -void f (unsigned n, bool overalign) -@{ - void *p; - if (overalign) - p = __builtin_alloca_with_align (n, 64 /* bits */); - else - p = __builtin_alloc (n); +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 - g (p, n); // @r{unsafe} -@} -@end smallexample +@defbuiltin{void __sync_synchronize (...)} +This built-in function issues a full memory barrier. +@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. +@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. +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 -@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}. +@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 -@defbuiltin{bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})} -The @code{__builtin_has_attribute} function evaluates to an integer constant -expression equal to @code{true} if the symbol or type referenced by -the @var{type-or-expression} argument has been declared with -the @var{attribute} referenced by the second argument. For -an @var{type-or-expression} argument that does not reference a symbol, -since attributes do not apply to expressions the built-in consider -the type of the argument. Neither argument is evaluated. -The @var{type-or-expression} argument is subject to the same -restrictions as the argument to @code{typeof} (@pxref{Typeof}). The -@var{attribute} argument is an attribute name optionally followed by -a comma-separated list of arguments enclosed in parentheses. Both forms -of attribute names---with and without double leading and trailing -underscores---are recognized. @xref{Attribute Syntax}, for details. -When no attribute arguments are specified for an attribute that expects -one or more arguments the function returns @code{true} if -@var{type-or-expression} has been declared with the attribute regardless -of the attribute argument values. Arguments provided for an attribute -that expects some are validated and matched up to the provided number. -The function returns @code{true} if all provided arguments match. For -example, the first call to the function below evaluates to @code{true} -because @code{x} is declared with the @code{aligned} attribute but -the second call evaluates to @code{false} because @code{x} is declared -@code{aligned (8)} and not @code{aligned (4)}. +@node __atomic Builtins +@section Built-in Functions for Memory Model Aware Atomic Operations -@smallexample -__attribute__ ((aligned (8))) int x; -_Static_assert (__builtin_has_attribute (x, aligned), "aligned"); -_Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)"); -@end smallexample +The following built-in functions approximately match the requirements +for the C++11 memory model. They are all +identified by being prefixed with @samp{__atomic} and most are +overloaded so that they work with multiple types. -Due to a limitation the @code{__builtin_has_attribute} function returns -@code{false} for the @code{mode} attribute even if the type or variable -referenced by the @var{type-or-expression} argument was declared with one. -The function is also not supported with labels, and in C with enumerators. +These functions are intended to replace the legacy @samp{__sync} +builtins. The main difference is that the memory order that is requested +is a parameter to the functions. New code should always use the +@samp{__atomic} builtins rather than the @samp{__sync} builtins. -Note that unlike the @code{__has_attribute} preprocessor operator which -is suitable for use in @code{#if} preprocessing directives -@code{__builtin_has_attribute} is an intrinsic function that is not -recognized in such contexts. +Note that the @samp{__atomic} builtins assume that programs will +conform to the C++11 memory model. In particular, they assume +that programs are free of data races. See the C++11 standard for +detailed requirements. -@enddefbuiltin +The @samp{__atomic} builtins can be used with any integral scalar or +pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral +types are also allowed if @samp{__int128} (@pxref{__int128}) is +supported by the architecture. -@defbuiltin{@var{type} __builtin_speculation_safe_value (@var{type} @var{val}, @var{type} @var{failval})} +The four non-arithmetic functions (load, store, exchange, and +compare_exchange) all have a generic version as well. This generic +version works on any data type. It uses the lock-free built-in function +if the specific data type size makes that possible; otherwise, an +external call is left to be resolved at run time. This external call is +the same format with the addition of a @samp{size_t} parameter inserted +as the first parameter indicating the size of the object being pointed to. +All objects must be the same size. -This built-in function can be used to help mitigate against unsafe -speculative execution. @var{type} may be any integral type or any -pointer type. +There are 6 different memory orders that can be specified. These map +to the C++11 memory orders with the same names, see the C++11 standard +or the @uref{https://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki +on atomic synchronization} for detailed definitions. Individual +targets may also support additional memory orders for use on specific +architectures. Refer to the target documentation for details of +these. -@enumerate -@item -If the CPU is not speculatively executing the code, then @var{val} -is returned. -@item -If the CPU is executing speculatively then either: -@itemize -@item -The function may cause execution to pause until it is known that the -code is no-longer being executed speculatively (in which case -@var{val} can be returned, as above); or -@item -The function may use target-dependent speculation tracking state to cause -@var{failval} to be returned when it is known that speculative -execution has incorrectly predicted a conditional branch operation. -@end itemize -@end enumerate +An atomic operation can both constrain code motion and +be mapped to hardware instructions for synchronization between threads +(e.g., a fence). To which extent this happens is controlled by the +memory orders, which are listed here in approximately ascending order of +strength. The description of each memory order is only meant to roughly +illustrate the effects and is not a specification; see the C++11 +memory model for precise semantics. -The second argument, @var{failval}, is optional and defaults to zero -if omitted. +@table @code +@item __ATOMIC_RELAXED +Implies no inter-thread ordering constraints. +@item __ATOMIC_CONSUME +This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE} +memory order because of a deficiency in C++11's semantics for +@code{memory_order_consume}. +@item __ATOMIC_ACQUIRE +Creates an inter-thread happens-before constraint from the release (or +stronger) semantic store to this acquire load. Can prevent hoisting +of code to before the operation. +@item __ATOMIC_RELEASE +Creates an inter-thread happens-before constraint to acquire (or stronger) +semantic loads that read from this release store. Can prevent sinking +of code to after the operation. +@item __ATOMIC_ACQ_REL +Combines the effects of both @code{__ATOMIC_ACQUIRE} and +@code{__ATOMIC_RELEASE}. +@item __ATOMIC_SEQ_CST +Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations. +@end table -GCC defines the preprocessor macro -@code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been -updated to support this builtin. +Note that in the C++11 memory model, @emph{fences} (e.g., +@samp{__atomic_thread_fence}) take effect in combination with other +atomic operations on specific memory locations (e.g., atomic loads); +operations on specific memory locations do not necessarily affect other +operations in the same way. -The built-in function can be used where a variable appears to be used in a -safe way, but the CPU, due to speculative execution may temporarily ignore -the bounds checks. Consider, for example, the following function: +Target architectures are encouraged to provide their own patterns for +each of the atomic built-in functions. If no target is provided, the original +non-memory model set of @samp{__sync} atomic built-in functions are +used, along with any required synchronization fences surrounding it in +order to achieve the proper behavior. Execution in this case is subject +to the same restrictions as those built-in functions. -@smallexample -int array[500]; -int f (unsigned untrusted_index) -@{ - if (untrusted_index < 500) - return array[untrusted_index]; - return 0; -@} -@end smallexample +If there is no pattern or mechanism to provide a lock-free instruction +sequence, a call is made to an external routine with the same parameters +to be resolved at run time. -If the function is called repeatedly with @code{untrusted_index} less -than the limit of 500, then a branch predictor will learn that the -block of code that returns a value stored in @code{array} will be -executed. If the function is subsequently called with an -out-of-range value it will still try to execute that block of code -first until the CPU determines that the prediction was incorrect -(the CPU will unwind any incorrect operations at that point). -However, depending on how the result of the function is used, it might be -possible to leave traces in the cache that can reveal what was stored -at the out-of-bounds location. The built-in function can be used to -provide some protection against leaking data in this way by changing -the code to: +When implementing patterns for these built-in functions, the memory order +parameter can be ignored as long as the pattern implements the most +restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory +orders execute correctly with this memory order but they may not execute as +efficiently as they could with a more appropriate implementation of the +relaxed requirements. -@smallexample -int array[500]; -int f (unsigned untrusted_index) -@{ - if (untrusted_index < 500) - return array[__builtin_speculation_safe_value (untrusted_index)]; - return 0; -@} -@end smallexample +Note that the C++11 standard allows for the memory order parameter to be +determined at run time rather than at compile time. These built-in +functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather +than invoke a runtime library call or inline a switch statement. This is +standard compliant, safe, and the simplest approach for now. -The built-in function will either cause execution to stall until the -conditional branch has been fully resolved, or it may permit -speculative execution to continue, but using 0 instead of -@code{untrusted_value} if that exceeds the limit. +The memory order parameter is a signed int, but only the lower 16 bits are +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. + +@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}}. -If accessing any memory location is potentially unsafe when speculative -execution is incorrect, then the code can be rewritten as +The valid memory order variants are +@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, +and @code{__ATOMIC_CONSUME}. -@smallexample -int array[500]; -int f (unsigned untrusted_index) -@{ - if (untrusted_index < 500) - return *__builtin_speculation_safe_value (&array[untrusted_index], NULL); - return 0; -@} -@end smallexample +@enddefbuiltin -which will cause a @code{NULL} pointer to be used for the unsafe case. +@defbuiltin{void __atomic_load (@var{type} *@var{ptr}, @var{type} *@var{ret}, int @var{memorder})} +This is the generic version of an atomic load. It returns the +contents of @code{*@var{ptr}} in @code{*@var{ret}}. @enddefbuiltin -@defbuiltin{int __builtin_types_compatible_p (@var{type1}, @var{type2})} +@defbuiltin{void __atomic_store_n (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +This built-in function implements an atomic store operation. It writes +@code{@var{val}} into @code{*@var{ptr}}. -You can use the built-in function @code{__builtin_types_compatible_p} to -determine whether two types are the same. +The valid memory order variants are +@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}. -This built-in function returns 1 if the unqualified versions of the -types @var{type1} and @var{type2} (which are types, not expressions) are -compatible, 0 otherwise. The result of this built-in function can be -used in integer constant expressions. +@enddefbuiltin -This built-in function ignores top level qualifiers (e.g., @code{const}, -@code{volatile}). For example, @code{int} is equivalent to @code{const -int}. +@defbuiltin{void __atomic_store (@var{type} *@var{ptr}, @var{type} *@var{val}, int @var{memorder})} +This is the generic version of an atomic store. It stores the value +of @code{*@var{val}} into @code{*@var{ptr}}. -The type @code{int[]} and @code{int[5]} are compatible. On the other -hand, @code{int} and @code{char *} are not compatible, even if the size -of their types, on the particular architecture are the same. Also, the -amount of pointer indirection is taken into account when determining -similarity. Consequently, @code{short *} is not similar to -@code{short **}. Furthermore, two types that are typedefed are -considered compatible if their underlying types are compatible. +@enddefbuiltin -An @code{enum} type is not considered to be compatible with another -@code{enum} type even if both are compatible with the same integer -type; this is what the C standard specifies. -For example, @code{enum @{foo, bar@}} is not similar to -@code{enum @{hot, dog@}}. +@defbuiltin{@var{type} __atomic_exchange_n (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +This built-in function implements an atomic exchange operation. It writes +@var{val} into @code{*@var{ptr}}, and returns the previous contents of +@code{*@var{ptr}}. -You typically use this function in code whose execution varies -depending on the arguments' types. For example: +All memory order variants are valid. -@smallexample -#define foo(x) \ - (@{ \ - typeof (x) tmp = (x); \ - if (__builtin_types_compatible_p (typeof (x), long double)) \ - tmp = foo_long_double (tmp); \ - else if (__builtin_types_compatible_p (typeof (x), double)) \ - tmp = foo_double (tmp); \ - else if (__builtin_types_compatible_p (typeof (x), float)) \ - tmp = foo_float (tmp); \ - else \ - abort (); \ - tmp; \ - @}) -@end smallexample +@enddefbuiltin -@emph{Note:} This construct is only available for C@. +@defbuiltin{void __atomic_exchange (@var{type} *@var{ptr}, @var{type} *@var{val}, @var{type} *@var{ret}, int @var{memorder})} +This is the generic version of an atomic exchange. It stores the +contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value +of @code{*@var{ptr}} is copied into @code{*@var{ret}}. @enddefbuiltin -@defbuiltin{@var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})} +@defbuiltin{bool __atomic_compare_exchange_n (@var{type} *@var{ptr}, @var{type} *@var{expected}, @var{type} @var{desired}, bool @var{weak}, int @var{success_memorder}, int @var{failure_memorder})} +This built-in function implements an atomic compare and exchange operation. +This compares the contents of @code{*@var{ptr}} with the contents of +@code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write} +operation that writes @var{desired} into @code{*@var{ptr}}. If they are not +equal, the operation is a @emph{read} and the current contents of +@code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true} +for weak compare_exchange, which may fail spuriously, and @code{false} for +the strong variation, which never fails spuriously. Many targets +only offer the strong variation and ignore the parameter. When in doubt, use +the strong variation. -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. +If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned +and memory is affected according to the +memory order specified by @var{success_memorder}. There are no +restrictions on what memory order can be used here. -@emph{Note:} This builtin is only available for C@. -This builtin can be used to call Go closures from C. +Otherwise, @code{false} is returned and memory is affected according +to @var{failure_memorder}. This memory order cannot be +@code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a +stronger order than that specified by @var{success_memorder}. @enddefbuiltin -@defbuiltin{@var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})} +@defbuiltin{bool __atomic_compare_exchange (@var{type} *@var{ptr}, @var{type} *@var{expected}, @var{type} *@var{desired}, bool @var{weak}, int @var{success_memorder}, int @var{failure_memorder})} +This built-in function implements the generic version of +@code{__atomic_compare_exchange}. The function is virtually identical to +@code{__atomic_compare_exchange_n}, except the desired value is also a +pointer. -You can use the built-in function @code{__builtin_choose_expr} to -evaluate code depending on the value of a constant expression. This -built-in function returns @var{exp1} if @var{const_exp}, which is an -integer constant expression, is nonzero. Otherwise it returns @var{exp2}. +@enddefbuiltin -Like the @samp{? :} operator, this built-in function does not evaluate the -expression that is not chosen. For example, if @var{const_exp} evaluates to -@code{true}, @var{exp2} is not evaluated even if it has side effects. On the -other hand, @code{__builtin_choose_expr} differs from @samp{? :} in that the -first operand must be a compile-time constant, and the other operands are not -subject to the @samp{? :} type constraints and promotions. +@defbuiltin{@var{type} __atomic_add_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +@defbuiltinx{@var{type} __atomic_sub_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +@defbuiltinx{@var{type} __atomic_and_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +@defbuiltinx{@var{type} __atomic_xor_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +@defbuiltinx{@var{type} __atomic_or_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +@defbuiltinx{@var{type} __atomic_nand_fetch (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +These built-in functions perform the operation suggested by the name, and +return the result of the operation. 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. -This built-in function can return an lvalue if the chosen argument is an -lvalue. +@smallexample +@{ *ptr @var{op}= val; return *ptr; @} +@{ *ptr = ~(*ptr & val); return *ptr; @} // nand +@end smallexample -If @var{exp1} is returned, the return type is the same as @var{exp1}'s -type. Similarly, if @var{exp2} is returned, its return type is the same -as @var{exp2}. +The object pointed to by the first argument must be of integer or pointer +type. It must not be a boolean type. All memory orders are valid. -Example: +@enddefbuiltin + +@defbuiltin{@var{type} __atomic_fetch_add (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +@defbuiltinx{@var{type} __atomic_fetch_sub (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +@defbuiltinx{@var{type} __atomic_fetch_and (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +@defbuiltinx{@var{type} __atomic_fetch_xor (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +@defbuiltinx{@var{type} __atomic_fetch_or (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +@defbuiltinx{@var{type} __atomic_fetch_nand (@var{type} *@var{ptr}, @var{type} @var{val}, int @var{memorder})} +These built-in functions perform the operation suggested by the name, and +return the value that had previously been in @code{*@var{ptr}}. 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 foo(x) \ - __builtin_choose_expr ( \ - __builtin_types_compatible_p (typeof (x), double), \ - foo_double (x), \ - __builtin_choose_expr ( \ - __builtin_types_compatible_p (typeof (x), float), \ - foo_float (x), \ - /* @r{The void expression results in a compile-time error} \ - @r{when assigning the result to something.} */ \ - (void)0)) +@{ tmp = *ptr; *ptr @var{op}= val; return tmp; @} +@{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand @end smallexample -@emph{Note:} This construct is only available for C@. Furthermore, the -unused expression (@var{exp1} or @var{exp2} depending on the value of -@var{const_exp}) may still generate syntax errors. This may change in -future revisions. +The same constraints on arguments apply as for the corresponding +@code{__atomic_op_fetch} built-in functions. All memory orders are valid. @enddefbuiltin -@defbuiltin{@var{type} __builtin_tgmath (@var{functions}, @var{arguments})} +@defbuiltin{bool __atomic_test_and_set (void *@var{ptr}, int @var{memorder})} -The built-in function @code{__builtin_tgmath}, available only for C -and Objective-C, calls a function determined according to the rules of -@code{} macros. It is intended to be used in -implementations of that header, so that expansions of macros from that -header only expand each of their arguments once, to avoid problems -when calls to such macros are nested inside the arguments of other -calls to such macros; in addition, it results in better diagnostics -for invalid calls to @code{} macros than implementations -using other GNU C language features. For example, the @code{pow} -type-generic macro might be defined as: +This built-in function performs an atomic test-and-set operation on +the byte at @code{*@var{ptr}}. The byte is set to some implementation +defined nonzero ``set'' value and the return value is @code{true} if and only +if the previous contents were ``set''. +It should be only used for operands of type @code{bool} or @code{char}. For +other types only part of the value may be set. -@smallexample -#define pow(a, b) __builtin_tgmath (powf, pow, powl, \ - cpowf, cpow, cpowl, a, b) -@end smallexample +All memory orders are valid. -The arguments to @code{__builtin_tgmath} are at least two pointers to -functions, followed by the arguments to the type-generic macro (which -will be passed as arguments to the selected function). All the -pointers to functions must be pointers to prototyped functions, none -of which may have variable arguments, and all of which must have the -same number of parameters; the number of parameters of the first -function determines how many arguments to @code{__builtin_tgmath} are -interpreted as function pointers, and how many as the arguments to the -called function. +@enddefbuiltin -The types of the specified functions must all be different, but -related to each other in the same way as a set of functions that may -be selected between by a macro in @code{}. This means that -the functions are parameterized by a floating-point type @var{t}, -different for each such function. The function return types may all -be the same type, or they may be @var{t} for each function, or they -may be the real type corresponding to @var{t} for each function (if -some of the types @var{t} are complex). Likewise, for each parameter -position, the type of the parameter in that position may always be the -same type, or may be @var{t} for each function (this case must apply -for at least one parameter position), or may be the real type -corresponding to @var{t} for each function. +@defbuiltin{void __atomic_clear (bool *@var{ptr}, int @var{memorder})} -The standard rules for @code{} macros are used to find a -common type @var{u} from the types of the arguments for parameters -whose types vary between the functions; complex integer types (a GNU -extension) are treated like the complex type corresponding to the real -floating type that would be chosen for the corresponding real integer type. -If the function return types vary, or are all the same integer type, -the function called is the one for which @var{t} is @var{u}, and it is -an error if there is no such function. If the function return types -are all the same floating-point type, the type-generic macro is taken -to be one of those from TS 18661 that rounds the result to a narrower -type; if there is a function for which @var{t} is @var{u}, it is -called, and otherwise the first function, if any, for which @var{t} -has at least the range and precision of @var{u} is called, and it is -an error if there is no such function. +This built-in function performs an atomic clear operation on +@code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0. +It should be only used for operands of type @code{bool} or @code{char} and +in conjunction with @code{__atomic_test_and_set}. +For other types it may only clear partially. If the type is not @code{bool} +prefer using @code{__atomic_store}. + +The valid memory order variants are +@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and +@code{__ATOMIC_RELEASE}. + +@enddefbuiltin + +@defbuiltin{void __atomic_thread_fence (int @var{memorder})} + +This built-in function acts as a synchronization fence between threads +based on the specified memory order. + +All memory orders are valid. @enddefbuiltin -@defbuiltin{int __builtin_constant_p (@var{exp})} -You can use the built-in function @code{__builtin_constant_p} to -determine if the expression @var{exp} is known to be constant at -compile time and hence that GCC can perform constant-folding on expressions -involving that value. The argument of the function is the expression to test. -The expression is not evaluated, side-effects are discarded. The function -returns the integer 1 if the argument is known to be a compile-time -constant and 0 if it is not known to be a compile-time constant. -Any expression that has side-effects makes the function return 0. -A return of 0 does not indicate that the expression is @emph{not} a constant, -but merely that GCC cannot prove it is a constant within the constraints -of the active set of optimization options. +@defbuiltin{void __atomic_signal_fence (int @var{memorder})} -You typically use this function in an embedded application where -memory is a critical resource. If you have some complex calculation, -you may want it to be folded if it involves constants, but need to call -a function if it does not. For example: +This built-in function acts as a synchronization fence between a thread +and signal handlers based in the same thread. -@smallexample -#define Scale_Value(X) \ - (__builtin_constant_p (X) \ - ? ((X) * SCALE + OFFSET) : Scale (X)) -@end smallexample +All memory orders are valid. -You may use this built-in function in either a macro or an inline -function. However, if you use it in an inlined function and pass an -argument of the function as the argument to the built-in, GCC -never returns 1 when you call the inline function with a string constant -or compound literal (@pxref{Compound Literals}) and does not return 1 -when you pass a constant numeric value to the inline function unless you -specify the @option{-O} option. +@enddefbuiltin -You may also use @code{__builtin_constant_p} in initializers for static -data. For instance, you can write +@defbuiltin{bool __atomic_always_lock_free (size_t @var{size}, void *@var{ptr})} + +This built-in function returns @code{true} if objects of @var{size} bytes always +generate lock-free atomic instructions for the target architecture. +@var{size} must resolve to a compile-time constant and the result also +resolves to a compile-time constant. + +@var{ptr} is an optional pointer to the object that may be used to determine +alignment. A value of 0 indicates typical alignment should be used. The +compiler may also ignore this parameter. @smallexample -static const int table[] = @{ - __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, - /* @r{@dots{}} */ -@}; +if (__atomic_always_lock_free (sizeof (long long), 0)) @end smallexample -@noindent -This is an acceptable initializer even if @var{EXPRESSION} is not a -constant expression, including the case where -@code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be -folded to a constant but @var{EXPRESSION} contains operands that are -not otherwise permitted in a static initializer (for example, -@code{0 && foo ()}). GCC must be more conservative about evaluating the -built-in in this case, because it has no opportunity to perform -optimization. @enddefbuiltin -@defbuiltin{bool __builtin_is_constant_evaluated (void)} -The @code{__builtin_is_constant_evaluated} function is available only -in C++. The built-in is intended to be used by implementations of -the @code{std::is_constant_evaluated} C++ function. Programs should make -use of the latter function rather than invoking the built-in directly. +@defbuiltin{bool __atomic_is_lock_free (size_t @var{size}, void *@var{ptr})} -The main use case of the built-in is to determine whether a @code{constexpr} -function is being called in a @code{constexpr} context. A call to -the function evaluates to a core constant expression with the value -@code{true} if and only if it occurs within the evaluation of an expression -or conversion that is manifestly constant-evaluated as defined in the C++ -standard. Manifestly constant-evaluated contexts include constant-expressions, -the conditions of @code{constexpr if} statements, constraint-expressions, and -initializers of variables usable in constant expressions. For more details -refer to the latest revision of the C++ standard. +This built-in function returns @code{true} if objects of @var{size} bytes always +generate lock-free atomic instructions for the target architecture. If +the built-in function is not known to be lock-free, a call is made to a +runtime routine named @code{__atomic_is_lock_free}. + +@var{ptr} is an optional pointer to the object that may be used to determine +alignment. A value of 0 indicates typical alignment should be used. The +compiler may also ignore this parameter. @enddefbuiltin -@defbuiltin{@var{type} __builtin_counted_by_ref (@var{ptr})} -The built-in function @code{__builtin_counted_by_ref} checks whether the array -object pointed by the pointer @var{ptr} has another object associated with it -that represents the number of elements in the array object through the -@code{counted_by} attribute (i.e. the counted-by object). If so, returns a -pointer to the corresponding counted-by object. -If such counted-by object does not exist, returns a null pointer. +@node Integer Overflow Builtins +@section Built-in Functions to Perform Arithmetic with Overflow Checking -This built-in function is only available in C for now. +The following built-in functions allow performing simple arithmetic operations +together with checking whether the operations overflowed. -The argument @var{ptr} must be a pointer to an array. -The @var{type} of the returned value is a pointer type pointing to the -corresponding type of the counted-by object or a void pointer type in case -of a null pointer being returned. +@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})} -For example: +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. -@smallexample -struct foo1 @{ - int counter; - struct bar1 array[] __attribute__((counted_by (counter))); -@} *p; +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. -struct foo2 @{ - int other; - struct bar2 array[]; -@} *q; -@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. -@noindent -the following call to the built-in +@enddefbuiltin -@smallexample -__builtin_counted_by_ref (p->array) -@end smallexample +@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})} -@noindent -returns: +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 -&p->counter with type @code{int *}. +#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 -@noindent -However, the following call to the built-in +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 -__builtin_counted_by_ref (q->array) + (@{ __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 -@noindent -returns a null pointer to @code{void}. +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{void __builtin_clear_padding (@var{ptr})} -The built-in function @code{__builtin_clear_padding} function clears -padding bits inside of the object representation of object pointed by -@var{ptr}, which has to be a pointer. The value representation of the -object is not affected. The type of the object is assumed to be the type -the pointer points to. Inside of a union, the only cleared bits are -bits that are padding bits for all the union members. +@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})} -This built-in-function is useful if the padding bits of an object might -have indeterminate values and the object representation needs to be -bitwise compared to some other object, for example for atomic operations. +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). -For C++, @var{ptr} argument type should be pointer to trivially-copyable -type, unless the argument is address of a variable or parameter, because -otherwise it isn't known if the type isn't just a base class whose padding -bits are reused or laid out differently in a derived class. @enddefbuiltin -@defbuiltin{@var{type} __builtin_bit_cast (@var{type}, @var{arg})} -The @code{__builtin_bit_cast} function is available only -in C++. The built-in is intended to be used by implementations of -the @code{std::bit_cast} C++ template function. Programs should make -use of the latter function rather than invoking the built-in directly. +@node x86 specific memory model extensions for transactional memory +@section x86-Specific Memory Model Extensions for Transactional Memory -This built-in function allows reinterpreting the bits of the @var{arg} -argument as if it had type @var{type}. @var{type} and the type of the -@var{arg} argument need to be trivially copyable types with the same size. -When manifestly constant-evaluated, it performs extra diagnostics required -for @code{std::bit_cast} and returns a constant expression if @var{arg} -is a constant expression. For more details -refer to the latest revision of the C++ standard. -@enddefbuiltin +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{long __builtin_expect (long @var{exp}, long @var{c})} -@opindex fprofile-arcs -You may use @code{__builtin_expect} to provide the compiler with -branch prediction information. In general, you should prefer to -use actual profile feedback for this (@option{-fprofile-arcs}), as -programmers are notoriously bad at predicting how their programs -actually perform. However, there are applications in which this -data is hard to collect. +@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 -The return value is the value of @var{exp}, which should be an integral -expression. The semantics of the built-in are that it is expected that -@var{exp} == @var{c}. For example: +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 -if (__builtin_expect (x, 0)) - foo (); -@end smallexample +#include // For _mm_pause -@noindent -indicates that we do not expect to call @code{foo}, since -we expect @code{x} to be zero. Since you are limited to integral -expressions for @var{exp}, you should use constructions such as +int lockvar; -@smallexample -if (__builtin_expect (ptr != NULL, 1)) - foo (*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 -@noindent -when testing pointer or floating-point values. +@node Object Size Checking +@section Object Size Checking -For the purposes of branch prediction optimizations, the probability that -a @code{__builtin_expect} expression is @code{true} is controlled by GCC's -@code{builtin-expect-probability} parameter, which defaults to 90%. +@subsection Object Size Checking Built-in Functions +@findex __builtin___memcpy_chk +@findex __builtin___mempcpy_chk +@findex __builtin___memmove_chk +@findex __builtin___memset_chk +@findex __builtin___strcpy_chk +@findex __builtin___stpcpy_chk +@findex __builtin___strncpy_chk +@findex __builtin___strcat_chk +@findex __builtin___strncat_chk -You can also use @code{__builtin_expect_with_probability} to explicitly -assign a probability value to individual expressions. If the built-in -is used in a loop construct, the provided probability will influence -the expected number of iterations made by loop optimizations. -@enddefbuiltin +GCC implements a limited buffer overflow protection mechanism that can +prevent some buffer overflow attacks by determining the sizes of objects +into which data is about to be written and preventing the writes when +the size isn't sufficient. The built-in functions described below yield +the best results when used together and when optimization is enabled. +For example, to detect object sizes across function boundaries or to +follow pointer assignments through non-trivial control flow they rely +on various optimization passes enabled with @option{-O2}. However, to +a limited extent, they can be used without optimization as well. -@defbuiltin{long __builtin_expect_with_probability} -(long @var{exp}, long @var{c}, double @var{probability}) +@defbuiltin{size_t __builtin_object_size (const void * @var{ptr}, int @var{type})} +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 +the storage to be declared with the @code{alloc_size} attribute (@pxref{Common +Function Attributes}). @code{__builtin_object_size} never evaluates +its arguments for side effects. If there are any side effects in them, it +returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} +for @var{type} 2 or 3. If there are multiple objects @var{ptr} can +point to and all of them are known at compile time, the returned number +is the maximum of remaining byte counts in those objects if @var{type} & 2 is +0 and minimum if nonzero. If it is not possible to determine which objects +@var{ptr} points to at compile time, @code{__builtin_object_size} should +return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} +for @var{type} 2 or 3. -This function has the same semantics as @code{__builtin_expect}, -but the caller provides the expected probability that @var{exp} == @var{c}. -The last argument, @var{probability}, is a floating-point value in the -range 0.0 to 1.0, inclusive. The @var{probability} argument must be a -constant floating-point expression. +@var{type} is an integer constant from 0 to 3. If the least significant +bit is clear, objects are whole variables, if it is set, a closest +surrounding subobject is considered the object a pointer points to. +The second bit determines if maximum or minimum of remaining bytes +is computed. + +@smallexample +struct V @{ char buf1[10]; int b; char buf2[10]; @} var; +char *p = &var.buf1[1], *q = &var.b; + +/* Here the object p points to is var. */ +assert (__builtin_object_size (p, 0) == sizeof (var) - 1); +/* The subobject p points to is var.buf1. */ +assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); +/* The object q points to is var. */ +assert (__builtin_object_size (q, 0) + == (char *) (&var + 1) - (char *) &var.b); +/* The subobject q points to is var.b. */ +assert (__builtin_object_size (q, 1) == sizeof (var.b)); +@end smallexample @enddefbuiltin -@defbuiltin{void __builtin_trap (void)} -This function causes the program to exit abnormally. GCC implements -this function by using a target-dependent mechanism (such as -intentionally executing an illegal instruction) or by calling -@code{abort}. The mechanism used may vary from release to release so -you should not rely on any particular implementation. +@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 +evaluation of object size estimates in a wider range of use cases and can be +more precise than @code{__builtin_object_size}, but it incurs a performance +penalty since it may add a runtime overhead on size computation. Semantics of +@var{type} as well as return values in case it is not possible to determine +which objects @var{ptr} points to at compile time are the same as in the case +of @code{__builtin_object_size}. @enddefbuiltin -@defbuiltin{void __builtin_unreachable (void)} -If control flow reaches the point of the @code{__builtin_unreachable}, -the program is undefined. It is useful in situations where the -compiler cannot deduce the unreachability of the code. +@subsection Object Size Checking and Source Fortification -One such case is immediately following an @code{asm} statement that -either never terminates, or one that transfers control elsewhere -and never returns. In this example, without the -@code{__builtin_unreachable}, GCC issues a warning that control -reaches the end of a non-void function. It also generates code -to return after the @code{asm}. +Hardening of function calls using the @code{_FORTIFY_SOURCE} macro is +one of the key uses of the object size checking built-in functions. To +make implementation of these features more convenient and improve +optimization and diagnostics, there are built-in functions added for +many common string operation functions, e.g., for @code{memcpy} +@code{__builtin___memcpy_chk} built-in is provided. This built-in has +an additional last argument, which is the number of bytes remaining in +the object the @var{dest} argument points to or @code{(size_t) -1} if +the size is not known. + +The built-in functions are optimized into the normal string functions +like @code{memcpy} if the last argument is @code{(size_t) -1} or if +it is known at compile time that the destination object will not +be overflowed. If the compiler can determine at compile time that the +object will always be overflowed, it issues a warning. + +The intended use can be e.g.@: @smallexample -int f (int c, int v) -@{ - if (c) - @{ - return v; - @} - else - @{ - asm("jmp error_handler"); - __builtin_unreachable (); - @} -@} +#undef memcpy +#define bos0(dest) __builtin_object_size (dest, 0) +#define memcpy(dest, src, n) \ + __builtin___memcpy_chk (dest, src, n, bos0 (dest)) + +char *volatile p; +char buf[10]; +/* It is unknown what object p points to, so this is optimized + into plain memcpy - no checking is possible. */ +memcpy (p, "abcde", n); +/* Destination is known and length too. It is known at compile + time there will be no overflow. */ +memcpy (&buf[5], "abcde", 5); +/* Destination is known, but the length is not known at compile time. + This will result in __memcpy_chk call that can check for overflow + at run time. */ +memcpy (&buf[5], "abcde", n); +/* Destination is known and it is known at compile time there will + be overflow. There will be a warning and __memcpy_chk call that + will abort the program at run time. */ +memcpy (&buf[6], "abcde", 5); @end smallexample -@noindent -Because the @code{asm} statement unconditionally transfers control out -of the function, control never reaches the end of the function -body. The @code{__builtin_unreachable} is in fact unreachable and -communicates this fact to the compiler. +Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, +@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, +@code{strcat} and @code{strncat}. -Another use for @code{__builtin_unreachable} is following a call a -function that never returns but that is not declared -@code{__attribute__((noreturn))}, as in this example: +@subsubsection Formatted Output Function Checking +@defbuiltin{int __builtin___sprintf_chk @ + (char *@var{s}, int @var{flag}, size_t @var{os}, @ + const char *@var{fmt}, ...)} +@defbuiltinx{int __builtin___snprintf_chk @ + (char *@var{s}, size_t @var{maxlen}, int @var{flag}, @ + size_t @var{os}, const char *@var{fmt}, ...)} +@defbuiltinx{int __builtin___vsprintf_chk @ + (char *@var{s}, int @var{flag}, size_t @var{os}, @ + const char *@var{fmt}, va_list @var{ap})} +@defbuiltinx{int __builtin___vsnprintf_chk @ + (char *@var{s}, size_t @var{maxlen}, int @var{flag}, @ + size_t @var{os}, const char *@var{fmt}, @ + va_list @var{ap})} -@smallexample -void function_that_never_returns (void); +The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} +etc.@: functions and can contain implementation specific flags on what +additional security measures the checking function might take, such as +handling @code{%n} differently. -int g (int c) -@{ - if (c) - @{ - return 1; - @} - else - @{ - function_that_never_returns (); - __builtin_unreachable (); - @} -@} -@end smallexample +The @var{os} argument is the object size @var{s} points to, like in the +other built-in functions. There is a small difference in the behavior +though, if @var{os} is @code{(size_t) -1}, the built-in functions are +optimized into the non-checking functions only if @var{flag} is 0, otherwise +the checking function is called with @var{os} argument set to +@code{(size_t) -1}. +In addition to this, there are checking built-in functions +@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, +@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. +These have just one additional argument, @var{flag}, right before +format string @var{fmt}. If the compiler is able to optimize them to +@code{fputc} etc.@: functions, it does, otherwise the checking function +is called and the @var{flag} argument passed to it. @enddefbuiltin -@defbuiltin{@var{type} __builtin_assoc_barrier (@var{type} @var{expr})} -This built-in inhibits re-association of the floating-point expression -@var{expr} with expressions consuming the return value of the built-in. The -expression @var{expr} itself can be reordered, and the whole expression -@var{expr} can be reordered with operands after the barrier. The barrier is -relevant when @code{-fassociative-math} is active. +@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. @smallexample -float x0 = a + b - b; -float x1 = __builtin_assoc_barrier(a + b) - b; +void foo () @{ + int *a = new int; + delete a; // This pair of allocation/deallocation operators can be omitted + // or replaced with int _temp; int *a = &_temp; etc.@: + void *b = ::operator new (32); + ::operator delete (b); // This one cannnot. + void *c = __builtin_operator_new (32); + __builtin_operator_delete (c); // This one can. +@} @end smallexample -@noindent -means that, with @code{-fassociative-math}, @code{x0} can be optimized to -@code{x0 = a} but @code{x1} cannot. - -It is also relevant when @code{-ffp-contract=fast} is active; -it will prevent contraction between expressions. - -@smallexample -float x0 = a * b + c; -float x1 = __builtin_assoc_barrier (a * b) + c; -@end smallexample +@node Other Builtins +@section Other Built-in Functions Provided by GCC -@noindent -means that, with @code{-ffp-contract=fast}, @code{x0} may be optimized to -use a fused multiply-add instruction but @code{x1} cannot. +This section documents miscellaneous built-in functions available in GCC. -@enddefbuiltin -@defbuiltin{{void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)} -This function returns its first argument, and allows the compiler -to assume that the returned pointer is at least @var{align} bytes -aligned. This built-in can have either two or three arguments, -if it has three, the third argument should have integer type, and -if it is nonzero means misalignment offset. For example: +@defbuiltin{bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})} +The @code{__builtin_has_attribute} function evaluates to an integer constant +expression equal to @code{true} if the symbol or type referenced by +the @var{type-or-expression} argument has been declared with +the @var{attribute} referenced by the second argument. For +an @var{type-or-expression} argument that does not reference a symbol, +since attributes do not apply to expressions the built-in consider +the type of the argument. Neither argument is evaluated. +The @var{type-or-expression} argument is subject to the same +restrictions as the argument to @code{typeof} (@pxref{Typeof}). The +@var{attribute} argument is an attribute name optionally followed by +a comma-separated list of arguments enclosed in parentheses. Both forms +of attribute names---with and without double leading and trailing +underscores---are recognized. @xref{Attribute Syntax}, for details. +When no attribute arguments are specified for an attribute that expects +one or more arguments the function returns @code{true} if +@var{type-or-expression} has been declared with the attribute regardless +of the attribute argument values. Arguments provided for an attribute +that expects some are validated and matched up to the provided number. +The function returns @code{true} if all provided arguments match. For +example, the first call to the function below evaluates to @code{true} +because @code{x} is declared with the @code{aligned} attribute but +the second call evaluates to @code{false} because @code{x} is declared +@code{aligned (8)} and not @code{aligned (4)}. @smallexample -void *x = __builtin_assume_aligned (arg, 16); +__attribute__ ((aligned (8))) int x; +_Static_assert (__builtin_has_attribute (x, aligned), "aligned"); +_Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)"); @end smallexample -@noindent -means that the compiler can assume @code{x}, set to @code{arg}, is at least -16-byte aligned, while: +Due to a limitation the @code{__builtin_has_attribute} function returns +@code{false} for the @code{mode} attribute even if the type or variable +referenced by the @var{type-or-expression} argument was declared with one. +The function is also not supported with labels, and in C with enumerators. -@smallexample -void *x = __builtin_assume_aligned (arg, 32, 8); -@end smallexample +Note that unlike the @code{__has_attribute} preprocessor operator which +is suitable for use in @code{#if} preprocessing directives +@code{__builtin_has_attribute} is an intrinsic function that is not +recognized in such contexts. -@noindent -means that the compiler can assume for @code{x}, set to @code{arg}, that -@code{(char *) x - 8} is 32-byte aligned. @enddefbuiltin -@defbuiltin{int __builtin_LINE ()} -This function is the equivalent of the preprocessor @code{__LINE__} -macro and returns a constant integer expression that evaluates to -the line number of the invocation of the built-in. When used as a C++ -default argument for a function @var{F}, it returns the line number -of the call to @var{F}. -@enddefbuiltin +@defbuiltin{@var{type} __builtin_speculation_safe_value (@var{type} @var{val}, @var{type} @var{failval})} -@defbuiltin{{const char *} __builtin_FUNCTION ()} -This function is the equivalent of the @code{__FUNCTION__} symbol -and returns an address constant pointing to the name of the function -from which the built-in was invoked, or the empty string if -the invocation is not at function scope. When used as a C++ default -argument for a function @var{F}, it returns the name of @var{F}'s -caller or the empty string if the call was not made at function -scope. -@enddefbuiltin +This built-in function can be used to help mitigate against unsafe +speculative execution. @var{type} may be any integral type or any +pointer type. -@defbuiltin{{const char *} __builtin_FILE ()} -This function is the equivalent of the preprocessor @code{__FILE__} -macro and returns an address constant pointing to the file name -containing the invocation of the built-in, or the empty string if -the invocation is not at function scope. When used as a C++ default -argument for a function @var{F}, it returns the file name of the call -to @var{F} or the empty string if the call was not made at function -scope. +@enumerate +@item +If the CPU is not speculatively executing the code, then @var{val} +is returned. +@item +If the CPU is executing speculatively then either: +@itemize +@item +The function may cause execution to pause until it is known that the +code is no-longer being executed speculatively (in which case +@var{val} can be returned, as above); or +@item +The function may use target-dependent speculation tracking state to cause +@var{failval} to be returned when it is known that speculative +execution has incorrectly predicted a conditional branch operation. +@end itemize +@end enumerate -For example, in the following, each call to function @code{foo} will -print a line similar to @code{"file.c:123: foo: message"} with the name -of the file and the line number of the @code{printf} call, the name of -the function @code{foo}, followed by the word @code{message}. +The second argument, @var{failval}, is optional and defaults to zero +if omitted. -@smallexample -const char* -function (const char *func = __builtin_FUNCTION ()) -@{ - return func; -@} +GCC defines the preprocessor macro +@code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been +updated to support this builtin. -void foo (void) +The built-in function can be used where a variable appears to be used in a +safe way, but the CPU, due to speculative execution may temporarily ignore +the bounds checks. Consider, for example, the following function: + +@smallexample +int array[500]; +int f (unsigned untrusted_index) @{ - printf ("%s:%i: %s: message\n", file (), line (), function ()); + if (untrusted_index < 500) + return array[untrusted_index]; + return 0; @} @end smallexample -@enddefbuiltin - -@defbuiltin{void __builtin___clear_cache (void *@var{begin}, void *@var{end})} -This function is used to flush the processor's instruction cache for -the region of memory between @var{begin} inclusive and @var{end} -exclusive. Some targets require that the instruction cache be -flushed, after modifying memory containing code, in order to obtain -deterministic behavior. - -If the target does not require instruction cache flushes, -@code{__builtin___clear_cache} has no effect. Otherwise either -instructions are emitted in-line to clear the instruction cache or a -call to the @code{__clear_cache} function in libgcc is made. -@enddefbuiltin - -@defbuiltin{void __builtin_prefetch (const void *@var{addr}, ...)} -This function is used to minimize cache-miss latency by moving data into -a cache before it is accessed. -You can insert calls to @code{__builtin_prefetch} into code for which -you know addresses of data in memory that is likely to be accessed soon. -If the target supports them, data prefetch instructions are generated. -If the prefetch is done early enough before the access then the data will -be in the cache by the time it is accessed. - -The value of @var{addr} is the address of the memory to prefetch. -There are two optional arguments, @var{rw} and @var{locality}. -The value of @var{rw} is a compile-time constant zero, one or two; one -means that the prefetch is preparing for a write to the memory address, -two means that the prefetch is preparing for a shared read (expected to be -read by at least one other processor before it is written if written at -all) and zero, the default, means that the prefetch is preparing for a read. -The value @var{locality} must be a compile-time constant integer between -zero and three. A value of zero means that the data has no temporal -locality, so it need not be left in the cache after the access. A value -of three means that the data has a high degree of temporal locality and -should be left in all levels of cache possible. Values of one and two -mean, respectively, a low or moderate degree of temporal locality. The -default is three. +If the function is called repeatedly with @code{untrusted_index} less +than the limit of 500, then a branch predictor will learn that the +block of code that returns a value stored in @code{array} will be +executed. If the function is subsequently called with an +out-of-range value it will still try to execute that block of code +first until the CPU determines that the prediction was incorrect +(the CPU will unwind any incorrect operations at that point). +However, depending on how the result of the function is used, it might be +possible to leave traces in the cache that can reveal what was stored +at the out-of-bounds location. The built-in function can be used to +provide some protection against leaking data in this way by changing +the code to: @smallexample -for (i = 0; i < n; i++) - @{ - a[i] = a[i] + b[i]; - __builtin_prefetch (&a[i+j], 1, 1); - __builtin_prefetch (&b[i+j], 0, 1); - /* @r{@dots{}} */ - @} -@end smallexample - -Data prefetch does not generate faults if @var{addr} is invalid, but -the address expression itself must be valid. For example, a prefetch -of @code{p->next} does not fault if @code{p->next} is not a valid -address, but evaluation faults if @code{p} is not a valid address. - -If the target does not support data prefetch, the address expression -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 +int array[500]; +int f (unsigned untrusted_index) +@{ + if (untrusted_index < 500) + return array[__builtin_speculation_safe_value (untrusted_index)]; + return 0; +@} +@end smallexample -@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 +The built-in function will either cause execution to stall until the +conditional branch has been fully resolved, or it may permit +speculative execution to continue, but using 0 instead of +@code{untrusted_value} if that exceeds the limit. -@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 -of @var{arg} argument's type, like void type, integer type, enumeral type, -boolean type, pointer type, reference type, offset type, real type, complex -type, function type, method type, record type, union type, array type, -string type, bit-precise integer type, vector type, etc. When the argument -is an expression, for backwards compatibility reason the argument is promoted -like arguments passed to @code{...} in varargs function, so some classes are -never returned in certain languages. Alternatively, the argument of the -built-in function can be a typename, such as the @code{typeof} specifier. +If accessing any memory location is potentially unsafe when speculative +execution is incorrect, then the code can be rewritten as @smallexample -int a[2]; -__builtin_classify_type (a) == __builtin_classify_type (int[5]); -__builtin_classify_type (a) == __builtin_classify_type (void*); -__builtin_classify_type (typeof (a)) == __builtin_classify_type (int[5]); +int array[500]; +int f (unsigned untrusted_index) +@{ + if (untrusted_index < 500) + return *__builtin_speculation_safe_value (&array[untrusted_index], NULL); + return 0; +@} @end smallexample -The first comparison will never be true, as @var{a} is implicitly converted -to pointer. The last two comparisons will be true as they classify -pointers in the second case and arrays in the last case. -@enddefbuiltin +which will cause a @code{NULL} pointer to be used for the unsafe case. -@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{int __builtin_types_compatible_p (@var{type1}, @var{type2})} -@defbuiltin{{long double} __builtin_huge_vall (void)} -Similar to @code{__builtin_huge_val}, except the return -type is @code{long double}. -@enddefbuiltin +You can use the built-in function @code{__builtin_types_compatible_p} to +determine whether two types are the same. -@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 +This built-in function returns 1 if the unqualified versions of the +types @var{type1} and @var{type2} (which are types, not expressions) are +compatible, 0 otherwise. The result of this built-in function can be +used in integer constant expressions. -@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 +This built-in function ignores top level qualifiers (e.g., @code{const}, +@code{volatile}). For example, @code{int} is equivalent to @code{const +int}. -@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 +The type @code{int[]} and @code{int[5]} are compatible. On the other +hand, @code{int} and @code{char *} are not compatible, even if the size +of their types, on the particular architecture are the same. Also, the +amount of pointer indirection is taken into account when determining +similarity. Consequently, @code{short *} is not similar to +@code{short **}. Furthermore, two types that are typedefed are +considered compatible if their underlying types are compatible. -@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 +An @code{enum} type is not considered to be compatible with another +@code{enum} type even if both are compatible with the same integer +type; this is what the C standard specifies. +For example, @code{enum @{foo, bar@}} is not similar to +@code{enum @{hot, dog@}}. -@defbuiltin{_Decimal32 __builtin_infd32 (void)} -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. -@enddefbuiltin +You typically use this function in code whose execution varies +depending on the arguments' types. For example: -@defbuiltin{_Decimal64 __builtin_infd64 (void)} -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. -@enddefbuiltin +@smallexample +#define foo(x) \ + (@{ \ + typeof (x) tmp = (x); \ + if (__builtin_types_compatible_p (typeof (x), long double)) \ + tmp = foo_long_double (tmp); \ + else if (__builtin_types_compatible_p (typeof (x), double)) \ + tmp = foo_double (tmp); \ + else if (__builtin_types_compatible_p (typeof (x), float)) \ + tmp = foo_float (tmp); \ + else \ + abort (); \ + tmp; \ + @}) +@end smallexample -@defbuiltin{_Decimal128 __builtin_infd128 (void)} -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. -@enddefbuiltin +@emph{Note:} This construct is only available for C@. -@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{@var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})} -@defbuiltin{_Float@var{n} __builtin_inff@var{n} (void)} -Similar to @code{__builtin_inf}, except the return -type is @code{_Float@var{n}}. -@enddefbuiltin +You can use the built-in function @code{__builtin_choose_expr} to +evaluate code depending on the value of a constant expression. This +built-in function returns @var{exp1} if @var{const_exp}, which is an +integer constant expression, is nonzero. Otherwise it returns @var{exp2}. -@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 +Like the @samp{? :} operator, this built-in function does not evaluate the +expression that is not chosen. For example, if @var{const_exp} evaluates to +@code{true}, @var{exp2} is not evaluated even if it has side effects. On the +other hand, @code{__builtin_choose_expr} differs from @samp{? :} in that the +first operand must be a compile-time constant, and the other operands are not +subject to the @samp{? :} type constraints and promotions. -@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 +This built-in function can return an lvalue if the chosen argument is an +lvalue. -@defbuiltin{double __builtin_nan (const char *@var{str})} -This is an implementation of the ISO C99 function @code{nan}. +If @var{exp1} is returned, the return type is the same as @var{exp1}'s +type. Similarly, if @var{exp2} is returned, its return type is the same +as @var{exp2}. -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@. +Example: -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 +@smallexample +#define foo(x) \ + __builtin_choose_expr ( \ + __builtin_types_compatible_p (typeof (x), double), \ + foo_double (x), \ + __builtin_choose_expr ( \ + __builtin_types_compatible_p (typeof (x), float), \ + foo_float (x), \ + /* @r{The void expression results in a compile-time error} \ + @r{when assigning the result to something.} */ \ + (void)0)) +@end smallexample -@defbuiltin{_Decimal32 __builtin_nand32 (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. -@enddefbuiltin +@emph{Note:} This construct is only available for C@. Furthermore, the +unused expression (@var{exp1} or @var{exp2} depending on the value of +@var{const_exp}) may still generate syntax errors. This may change in +future revisions. -@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{@var{type} __builtin_tgmath (@var{functions}, @var{arguments})} -@defbuiltin{float __builtin_nanf (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{float}. -@enddefbuiltin +The built-in function @code{__builtin_tgmath}, available only for C +and Objective-C, calls a function determined according to the rules of +@code{} macros. It is intended to be used in +implementations of that header, so that expansions of macros from that +header only expand each of their arguments once, to avoid problems +when calls to such macros are nested inside the arguments of other +calls to such macros; in addition, it results in better diagnostics +for invalid calls to @code{} macros than implementations +using other GNU C language features. For example, the @code{pow} +type-generic macro might be defined as: -@defbuiltin{{long double} __builtin_nanl (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{long double}. -@enddefbuiltin +@smallexample +#define pow(a, b) __builtin_tgmath (powf, pow, powl, \ + cpowf, cpow, cpowl, a, b) +@end smallexample + +The arguments to @code{__builtin_tgmath} are at least two pointers to +functions, followed by the arguments to the type-generic macro (which +will be passed as arguments to the selected function). All the +pointers to functions must be pointers to prototyped functions, none +of which may have variable arguments, and all of which must have the +same number of parameters; the number of parameters of the first +function determines how many arguments to @code{__builtin_tgmath} are +interpreted as function pointers, and how many as the arguments to the +called function. + +The types of the specified functions must all be different, but +related to each other in the same way as a set of functions that may +be selected between by a macro in @code{}. This means that +the functions are parameterized by a floating-point type @var{t}, +different for each such function. The function return types may all +be the same type, or they may be @var{t} for each function, or they +may be the real type corresponding to @var{t} for each function (if +some of the types @var{t} are complex). Likewise, for each parameter +position, the type of the parameter in that position may always be the +same type, or may be @var{t} for each function (this case must apply +for at least one parameter position), or may be the real type +corresponding to @var{t} for each function. + +The standard rules for @code{} macros are used to find a +common type @var{u} from the types of the arguments for parameters +whose types vary between the functions; complex integer types (a GNU +extension) are treated like the complex type corresponding to the real +floating type that would be chosen for the corresponding real integer type. +If the function return types vary, or are all the same integer type, +the function called is the one for which @var{t} is @var{u}, and it is +an error if there is no such function. If the function return types +are all the same floating-point type, the type-generic macro is taken +to be one of those from TS 18661 that rounds the result to a narrower +type; if there is a function for which @var{t} is @var{u}, it is +called, and otherwise the first function, if any, for which @var{t} +has at least the range and precision of @var{u} is called, and it is +an error if there is no such function. -@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{int __builtin_constant_p (@var{exp})} +You can use the built-in function @code{__builtin_constant_p} to +determine if the expression @var{exp} is known to be constant at +compile time and hence that GCC can perform constant-folding on expressions +involving that value. The argument of the function is the expression to test. +The expression is not evaluated, side-effects are discarded. The function +returns the integer 1 if the argument is known to be a compile-time +constant and 0 if it is not known to be a compile-time constant. +Any expression that has side-effects makes the function return 0. +A return of 0 does not indicate that the expression is @emph{not} a constant, +but merely that GCC cannot prove it is a constant within the constraints +of the active set of optimization options. -@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 +You typically use this function in an embedded application where +memory is a critical resource. If you have some complex calculation, +you may want it to be folded if it involves constants, but need to call +a function if it does not. For example: -@defbuiltin{_Decimal32 __builtin_nansd32 (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}. -@enddefbuiltin +@smallexample +#define Scale_Value(X) \ + (__builtin_constant_p (X) \ + ? ((X) * SCALE + OFFSET) : Scale (X)) +@end smallexample -@defbuiltin{_Decimal64 __builtin_nansd64 (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}. -@enddefbuiltin +You may use this built-in function in either a macro or an inline +function. However, if you use it in an inlined function and pass an +argument of the function as the argument to the built-in, GCC +never returns 1 when you call the inline function with a string constant +or compound literal (@pxref{Compound Literals}) and does not return 1 +when you pass a constant numeric value to the inline function unless you +specify the @option{-O} option. -@defbuiltin{_Decimal128 __builtin_nansd128 (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}. -@enddefbuiltin +You may also use @code{__builtin_constant_p} in initializers for static +data. For instance, you can write -@defbuiltin{float __builtin_nansf (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{float}. -@enddefbuiltin +@smallexample +static const int table[] = @{ + __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, + /* @r{@dots{}} */ +@}; +@end smallexample -@defbuiltin{{long double} __builtin_nansl (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{long double}. +@noindent +This is an acceptable initializer even if @var{EXPRESSION} is not a +constant expression, including the case where +@code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be +folded to a constant but @var{EXPRESSION} contains operands that are +not otherwise permitted in a static initializer (for example, +@code{0 && foo ()}). GCC must be more conservative about evaluating the +built-in in this case, because it has no opportunity to perform +optimization. @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{bool __builtin_is_constant_evaluated (void)} +The @code{__builtin_is_constant_evaluated} function is available only +in C++. The built-in is intended to be used by implementations of +the @code{std::is_constant_evaluated} C++ function. Programs should make +use of the latter function rather than invoking the built-in directly. -@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}. +The main use case of the built-in is to determine whether a @code{constexpr} +function is being called in a @code{constexpr} context. A call to +the function evaluates to a core constant expression with the value +@code{true} if and only if it occurs within the evaluation of an expression +or conversion that is manifestly constant-evaluated as defined in the C++ +standard. Manifestly constant-evaluated contexts include constant-expressions, +the conditions of @code{constexpr if} statements, constraint-expressions, and +initializers of variables usable in constant expressions. For more details +refer to the latest revision of the C++ standard. @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{@var{type} __builtin_counted_by_ref (@var{ptr})} +The built-in function @code{__builtin_counted_by_ref} checks whether the array +object pointed by the pointer @var{ptr} has another object associated with it +that represents the number of elements in the array object through the +@code{counted_by} attribute (i.e. the counted-by object). If so, returns a +pointer to the corresponding counted-by object. +If such counted-by object does not exist, returns a null pointer. -@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 +This built-in function is only available in C for now. -@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 +The argument @var{ptr} must be a pointer to an array. +The @var{type} of the returned value is a pointer type pointing to the +corresponding type of the counted-by object or a void pointer type in case +of a null pointer being returned. -@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 +For example: -@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 +@smallexample +struct foo1 @{ + int counter; + struct bar1 array[] __attribute__((counted_by (counter))); +@} *p; -@defbuiltin{int __builtin_popcount (unsigned int @var{x})} -Returns the number of 1-bits in @var{x}. -@enddefbuiltin +struct foo2 @{ + int other; + struct bar2 array[]; +@} *q; +@end smallexample -@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 +@noindent +the following call to the built-in -@defbuiltin{int __builtin_ffsl (long)} -Similar to @code{__builtin_ffs}, except the argument type is -@code{long}. -@enddefbuiltin +@smallexample +__builtin_counted_by_ref (p->array) +@end smallexample -@defbuiltin{int __builtin_clzl (unsigned long)} -Similar to @code{__builtin_clz}, except the argument type is -@code{unsigned long}. -@enddefbuiltin +@noindent +returns: -@defbuiltin{int __builtin_ctzl (unsigned long)} -Similar to @code{__builtin_ctz}, except the argument type is -@code{unsigned long}. -@enddefbuiltin +@smallexample +&p->counter with type @code{int *}. +@end smallexample -@defbuiltin{int __builtin_clrsbl (long)} -Similar to @code{__builtin_clrsb}, except the argument type is -@code{long}. -@enddefbuiltin +@noindent +However, the following call to the built-in -@defbuiltin{int __builtin_popcountl (unsigned long)} -Similar to @code{__builtin_popcount}, except the argument type is -@code{unsigned long}. -@enddefbuiltin +@smallexample +__builtin_counted_by_ref (q->array) +@end smallexample -@defbuiltin{int __builtin_parityl (unsigned long)} -Similar to @code{__builtin_parity}, except the argument type is -@code{unsigned long}. -@enddefbuiltin +@noindent +returns a null pointer to @code{void}. -@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{void __builtin_clear_padding (@var{ptr})} +The built-in function @code{__builtin_clear_padding} function clears +padding bits inside of the object representation of object pointed by +@var{ptr}, which has to be a pointer. The value representation of the +object is not affected. The type of the object is assumed to be the type +the pointer points to. Inside of a union, the only cleared bits are +bits that are padding bits for all the union members. -@defbuiltin{int __builtin_ctzll (unsigned long long)} -Similar to @code{__builtin_ctz}, except the argument type is -@code{unsigned long long}. -@enddefbuiltin +This built-in-function is useful if the padding bits of an object might +have indeterminate values and the object representation needs to be +bitwise compared to some other object, for example for atomic operations. -@defbuiltin{int __builtin_clrsbll (long long)} -Similar to @code{__builtin_clrsb}, except the argument type is -@code{long long}. +For C++, @var{ptr} argument type should be pointer to trivially-copyable +type, unless the argument is address of a variable or parameter, because +otherwise it isn't known if the type isn't just a base class whose padding +bits are reused or laid out differently in a derived class. @enddefbuiltin -@defbuiltin{int __builtin_popcountll (unsigned long long)} -Similar to @code{__builtin_popcount}, except the argument type is -@code{unsigned long long}. -@enddefbuiltin +@defbuiltin{@var{type} __builtin_bit_cast (@var{type}, @var{arg})} +The @code{__builtin_bit_cast} function is available only +in C++. The built-in is intended to be used by implementations of +the @code{std::bit_cast} C++ template function. Programs should make +use of the latter function rather than invoking the built-in directly. -@defbuiltin{int __builtin_parityll (unsigned long long)} -Similar to @code{__builtin_parity}, except the argument type is -@code{unsigned long long}. +This built-in function allows reinterpreting the bits of the @var{arg} +argument as if it had type @var{type}. @var{type} and the type of the +@var{arg} argument need to be trivially copyable types with the same size. +When manifestly constant-evaluated, it performs extra diagnostics required +for @code{std::bit_cast} and returns a constant expression if @var{arg} +is a constant expression. For more details +refer to the latest revision of the C++ standard. @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{long __builtin_expect (long @var{exp}, long @var{c})} +@opindex fprofile-arcs +You may use @code{__builtin_expect} to provide the compiler with +branch prediction information. In general, you should prefer to +use actual profile feedback for this (@option{-fprofile-arcs}), as +programmers are notoriously bad at predicting how their programs +actually perform. However, there are applications in which this +data is hard to collect. + +The return value is the value of @var{exp}, which should be an integral +expression. The semantics of the built-in are that it is expected that +@var{exp} == @var{c}. For example: -@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 +@smallexample +if (__builtin_expect (x, 0)) + foo (); +@end smallexample -@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 +@noindent +indicates that we do not expect to call @code{foo}, since +we expect @code{x} to be zero. Since you are limited to integral +expressions for @var{exp}, you should use constructions such as -@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 +@smallexample +if (__builtin_expect (ptr != NULL, 1)) + foo (*ptr); +@end smallexample -@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 +@noindent +when testing pointer or floating-point values. -@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 +For the purposes of branch prediction optimizations, the probability that +a @code{__builtin_expect} expression is @code{true} is controlled by GCC's +@code{builtin-expect-probability} parameter, which defaults to 90%. -@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. +You can also use @code{__builtin_expect_with_probability} to explicitly +assign a probability value to individual expressions. If the built-in +is used in a loop construct, the provided probability will influence +the expected number of iterations made by loop optimizations. @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{long __builtin_expect_with_probability} +(long @var{exp}, long @var{c}, double @var{probability}) -@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}. +This function has the same semantics as @code{__builtin_expect}, +but the caller provides the expected probability that @var{exp} == @var{c}. +The last argument, @var{probability}, is a floating-point value in the +range 0.0 to 1.0, inclusive. The @var{probability} argument must be a +constant floating-point expression. @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})} +@defbuiltin{void __builtin_trap (void)} +This function causes the program to exit abnormally. GCC implements +this function by using a target-dependent mechanism (such as +intentionally executing an illegal instruction) or by calling +@code{abort}. The mechanism used may vary from release to release so +you should not rely on any particular implementation. @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{void __builtin_unreachable (void)} +If control flow reaches the point of the @code{__builtin_unreachable}, +the program is undefined. It is useful in situations where the +compiler cannot deduce the unreachability of the code. -@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 +One such case is immediately following an @code{asm} statement that +either never terminates, or one that transfers control elsewhere +and never returns. In this example, without the +@code{__builtin_unreachable}, GCC issues a warning that control +reaches the end of a non-void function. It also generates code +to return after the @code{asm}. -@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 +@smallexample +int f (int c, int v) +@{ + if (c) + @{ + return v; + @} + else + @{ + asm("jmp error_handler"); + __builtin_unreachable (); + @} +@} +@end smallexample -@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 +@noindent +Because the @code{asm} statement unconditionally transfers control out +of the function, control never reaches the end of the function +body. The @code{__builtin_unreachable} is in fact unreachable and +communicates this fact to the compiler. -@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 +Another use for @code{__builtin_unreachable} is following a call a +function that never returns but that is not declared +@code{__attribute__((noreturn))}, as in this example: -@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 +@smallexample +void function_that_never_returns (void); -@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 +int g (int c) +@{ + if (c) + @{ + return 1; + @} + else + @{ + function_that_never_returns (); + __builtin_unreachable (); + @} +@} +@end smallexample -@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{@var{type} __builtin_assoc_barrier (@var{type} @var{expr})} +This built-in inhibits re-association of the floating-point expression +@var{expr} with expressions consuming the return value of the built-in. The +expression @var{expr} itself can be reordered, and the whole expression +@var{expr} can be reordered with operands after the barrier. The barrier is +relevant when @code{-fassociative-math} is active. -@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 +@smallexample +float x0 = a + b - b; +float x1 = __builtin_assoc_barrier(a + b) - b; +@end smallexample -@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 +@noindent +means that, with @code{-fassociative-math}, @code{x0} can be optimized to +@code{x0 = a} but @code{x1} cannot. -@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 +It is also relevant when @code{-ffp-contract=fast} is active; +it will prevent contraction between expressions. + +@smallexample +float x0 = a * b + c; +float x1 = __builtin_assoc_barrier (a * b) + c; +@end smallexample -@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 +@noindent +means that, with @code{-ffp-contract=fast}, @code{x0} may be optimized to +use a fused multiply-add instruction but @code{x1} cannot. -@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{{void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...)} +This function returns its first argument, and allows the compiler +to assume that the returned pointer is at least @var{align} bytes +aligned. This built-in can have either two or three arguments, +if it has three, the third argument should have integer type, and +if it is nonzero means misalignment offset. For example: -@defbuiltin{uint64_t __builtin_bswap64 (uint64_t @var{x})} -Similar to @code{__builtin_bswap32}, except the argument and return types -are 64-bit. -@enddefbuiltin +@smallexample +void *x = __builtin_assume_aligned (arg, 16); +@end smallexample -@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 +@noindent +means that the compiler can assume @code{x}, set to @code{arg}, is at least +16-byte aligned, while: +@smallexample +void *x = __builtin_assume_aligned (arg, 32, 8); +@end smallexample -@defbuiltin{Pmode __builtin_extend_pointer (void * @var{x})} -On targets where the user visible pointer size is smaller than the size -of an actual hardware address this function returns the extended user -pointer. Targets where this is true included ILP32 mode on x86_64 or -Aarch64. This function is mainly useful when writing inline assembly -code. +@noindent +means that the compiler can assume for @code{x}, set to @code{arg}, that +@code{(char *) x - 8} is 32-byte aligned. @enddefbuiltin -@defbuiltin{int __builtin_goacc_parlevel_id (int @var{x})} -Returns the openacc gang, worker or vector id depending on whether @var{x} is -0, 1 or 2. +@defbuiltin{int __builtin_LINE ()} +This function is the equivalent of the preprocessor @code{__LINE__} +macro and returns a constant integer expression that evaluates to +the line number of the invocation of the built-in. When used as a C++ +default argument for a function @var{F}, it returns the line number +of the call to @var{F}. @enddefbuiltin -@defbuiltin{int __builtin_goacc_parlevel_size (int @var{x})} -Returns the openacc gang, worker or vector size depending on whether @var{x} is -0, 1 or 2. +@defbuiltin{{const char *} __builtin_FUNCTION ()} +This function is the equivalent of the @code{__FUNCTION__} symbol +and returns an address constant pointing to the name of the function +from which the built-in was invoked, or the empty string if +the invocation is not at function scope. When used as a C++ default +argument for a function @var{F}, it returns the name of @var{F}'s +caller or the empty string if the call was not made at function +scope. @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{{const char *} __builtin_FILE ()} +This function is the equivalent of the preprocessor @code{__FILE__} +macro and returns an address constant pointing to the file name +containing the invocation of the built-in, or the empty string if +the invocation is not at function scope. When used as a C++ default +argument for a function @var{F}, it returns the file name of the call +to @var{F} or the empty string if the call was not made at function +scope. -@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 +For example, in the following, each call to function @code{foo} will +print a line similar to @code{"file.c:123: foo: message"} with the name +of the file and the line number of the @code{printf} call, the name of +the function @code{foo}, followed by the word @code{message}. -@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 +@smallexample +const char* +function (const char *func = __builtin_FUNCTION ()) +@{ + return func; +@} -@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 +void foo (void) +@{ + printf ("%s:%i: %s: message\n", file (), line (), function ()); +@} +@end smallexample -@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{void __builtin___clear_cache (void *@var{begin}, void *@var{end})} +This function is used to flush the processor's instruction cache for +the region of memory between @var{begin} inclusive and @var{end} +exclusive. Some targets require that the instruction cache be +flushed, after modifying memory containing code, in order to obtain +deterministic behavior. -@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. +If the target does not require instruction cache flushes, +@code{__builtin___clear_cache} has no effect. Otherwise either +instructions are emitted in-line to clear the instruction cache or a +call to the @code{__clear_cache} function in libgcc is made. @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{void __builtin_prefetch (const void *@var{addr}, ...)} +This function is used to minimize cache-miss latency by moving data into +a cache before it is accessed. +You can insert calls to @code{__builtin_prefetch} into code for which +you know addresses of data in memory that is likely to be accessed soon. +If the target supports them, data prefetch instructions are generated. +If the prefetch is done early enough before the access then the data will +be in the cache by the time it is accessed. -@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 +The value of @var{addr} is the address of the memory to prefetch. +There are two optional arguments, @var{rw} and @var{locality}. +The value of @var{rw} is a compile-time constant zero, one or two; one +means that the prefetch is preparing for a write to the memory address, +two means that the prefetch is preparing for a shared read (expected to be +read by at least one other processor before it is written if written at +all) and zero, the default, means that the prefetch is preparing for a read. +The value @var{locality} must be a compile-time constant integer between +zero and three. A value of zero means that the data has no temporal +locality, so it need not be left in the cache after the access. A value +of three means that the data has a high degree of temporal locality and +should be left in all levels of cache possible. Values of one and two +mean, respectively, a low or moderate degree of temporal locality. The +default is three. -@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 +@smallexample +for (i = 0; i < n; i++) + @{ + a[i] = a[i] + b[i]; + __builtin_prefetch (&a[i+j], 1, 1); + __builtin_prefetch (&b[i+j], 0, 1); + /* @r{@dots{}} */ + @} +@end smallexample -@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 +Data prefetch does not generate faults if @var{addr} is invalid, but +the address expression itself must be valid. For example, a prefetch +of @code{p->next} does not fault if @code{p->next} is not a valid +address, but evaluation faults if @code{p} is not a valid address. -@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. +If the target does not support data prefetch, the address expression +is evaluated if it includes side effects but no other code is generated +and GCC does not issue a warning. @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{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 +of @var{arg} argument's type, like void type, integer type, enumeral type, +boolean type, pointer type, reference type, offset type, real type, complex +type, function type, method type, record type, union type, array type, +string type, bit-precise integer type, vector type, etc. When the argument +is an expression, for backwards compatibility reason the argument is promoted +like arguments passed to @code{...} in varargs function, so some classes are +never returned in certain languages. Alternatively, the argument of the +built-in function can be a typename, such as the @code{typeof} specifier. -@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 +@smallexample +int a[2]; +__builtin_classify_type (a) == __builtin_classify_type (int[5]); +__builtin_classify_type (a) == __builtin_classify_type (void*); +__builtin_classify_type (typeof (a)) == __builtin_classify_type (int[5]); +@end smallexample -@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. +The first comparison will never be true, as @var{a} is implicitly converted +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{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. +@defbuiltin{Pmode __builtin_extend_pointer (void * @var{x})} +On targets where the user visible pointer size is smaller than the size +of an actual hardware address this function returns the extended user +pointer. Targets where this is true included ILP32 mode on x86_64 or +Aarch64. This function is mainly useful when writing inline assembly +code. @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. +@defbuiltin{int __builtin_goacc_parlevel_id (int @var{x})} +Returns the openacc gang, worker or vector id depending on whether @var{x} is +0, 1 or 2. @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. +@defbuiltin{int __builtin_goacc_parlevel_size (int @var{x})} +Returns the openacc gang, worker or vector size depending on whether @var{x} is +0, 1 or 2. @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 diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index a2b48f728c2..d4767dcd614 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -2614,8 +2614,8 @@ ISO C23. @item -fno-builtin @itemx -fno-builtin-@var{function} Don't recognize built-in functions that do not begin with -@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in -functions provided by GCC}, for details of the functions affected, +@samp{__builtin_} as prefix. @xref{Library Builtins}, +for details of the functions affected, including those which are not built-in functions when @option{-ansi} or @option{-std} options for strict ISO C conformance are used because they do not have an ISO standard meaning.