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.
* 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{<setjmp.h>} in user code
-instead of the builtins.
-
-The built-in versions of these functions use GCC's normal
-mechanisms to save and restore registers using the stack on function
-entry and exit. The jump buffer argument @var{buf} holds only the
-information needed to restore the stack frame, rather than the entire
-set of saved register values.
-
-An important caveat is that GCC arranges to save and restore only
-those registers known to the specific architecture variant being
-compiled for. This can make @code{__builtin_setjmp} and
-@code{__builtin_longjmp} more efficient than their library
-counterparts in some cases, but it can also cause incorrect and
-mysterious behavior when mixing with code that uses the full register
-set.
-
-You should declare the jump buffer argument @var{buf} to the
-built-in functions as:
-
-@smallexample
-#include <stdint.h>
-intptr_t @var{buf}[5];
-@end smallexample
-
-@defbuiltin{{int} __builtin_setjmp (intptr_t *@var{buf})}
-This function saves the current stack context in @var{buf}.
-@code{__builtin_setjmp} returns 0 when returning directly,
-and 1 when returning from @code{__builtin_longjmp} using the same
-@var{buf}.
-@enddefbuiltin
-
-@defbuiltin{{void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})}
-This function restores the stack context in @var{buf},
-saved by a previous call to @code{__builtin_setjmp}. After
-@code{__builtin_longjmp} is finished, the program resumes execution as
-if the matching @code{__builtin_setjmp} returns the value @var{val},
-which must be 1.
-
-Because @code{__builtin_longjmp} depends on the function return
-mechanism to restore the stack context, it cannot be called
-from the same function calling @code{__builtin_setjmp} to
-initialize @var{buf}. It can only be called from a function called
-(directly or indirectly) from the function calling @code{__builtin_setjmp}.
-@enddefbuiltin
-
-@node Constructing Calls
-@section Constructing Function Calls
-@cindex constructing calls
-@cindex forwarding calls
-
-Using the built-in functions described below, you can record
-the arguments a function received, and call another function
-with the same arguments, without knowing the number or types
-of the arguments.
-
-You can also record the return value of that function call,
-and later return that value, without knowing what data type
-the function tried to return (as long as your caller expects
-that data type).
-
-However, these built-in functions may interact badly with some
-sophisticated features or other extensions of the language. It
-is, therefore, not recommended to use them outside very simple
-functions acting as mere forwarders for their arguments.
-
-@defbuiltin{{void *} __builtin_apply_args ()}
-This built-in function returns a pointer to data
-describing how to perform a call with the same arguments as are passed
-to the current function.
-
-The function saves the arg pointer register, structure value address,
-and all registers that might be used to pass arguments to a function
-into a block of memory allocated on the stack. Then it returns the
-address of that block.
-@enddefbuiltin
-
-@defbuiltin{{void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})}
-This built-in function invokes @var{function}
-with a copy of the parameters described by @var{arguments}
-and @var{size}.
-
-The value of @var{arguments} should be the value returned by
-@code{__builtin_apply_args}. The argument @var{size} specifies the size
-of the stack argument data, in bytes.
-
-This function returns a pointer to data describing
-how to return whatever value is returned by @var{function}. The data
-is saved in a block of memory allocated on the stack.
-
-It is not always simple to compute the proper value for @var{size}. The
-value is used by @code{__builtin_apply} to compute the amount of data
-that should be pushed on the stack and copied from the incoming argument
-area.
-@enddefbuiltin
-
-@defbuiltin{{void} __builtin_return (void *@var{result})}
-This built-in function returns the value described by @var{result} from
-the containing function. You should specify, for @var{result}, a value
-returned by @code{__builtin_apply}.
-@enddefbuiltin
-
-@defbuiltin{{} __builtin_va_arg_pack ()}
-This built-in function represents all anonymous arguments of an inline
-function. It can be used only in inline functions that are always
-inlined, never compiled as a separate function, such as those using
-@code{__attribute__ ((__always_inline__))} or
-@code{__attribute__ ((__gnu_inline__))} extern inline functions.
-It must be only passed as last argument to some other function
-with variable arguments. This is useful for writing small wrapper
-inlines for variable argument functions, when using preprocessor
-macros is undesirable. For example:
-@smallexample
-extern int myprintf (FILE *f, const char *format, ...);
-extern inline __attribute__ ((__gnu_inline__)) int
-myprintf (FILE *f, const char *format, ...)
-@{
- int r = fprintf (f, "myprintf: ");
- if (r < 0)
- return r;
- int s = fprintf (f, format, __builtin_va_arg_pack ());
- if (s < 0)
- return s;
- return r + s;
-@}
-@end smallexample
-@enddefbuiltin
-
-@defbuiltin{int __builtin_va_arg_pack_len ()}
-This built-in function returns the number of anonymous arguments of
-an inline function. It can be used only in inline functions that
-are always inlined, never compiled as a separate function, such
-as those using @code{__attribute__ ((__always_inline__))} or
-@code{__attribute__ ((__gnu_inline__))} extern inline functions.
-For example following does link- or run-time checking of open
-arguments for optimized code:
-@smallexample
-#ifdef __OPTIMIZE__
-extern inline __attribute__((__gnu_inline__)) int
-myopen (const char *path, int oflag, ...)
-@{
- if (__builtin_va_arg_pack_len () > 1)
- warn_open_too_many_arguments ();
-
- if (__builtin_constant_p (oflag))
- @{
- if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
- @{
- warn_open_missing_mode ();
- return __open_2 (path, oflag);
- @}
- return open (path, oflag, __builtin_va_arg_pack ());
- @}
-
- if (__builtin_va_arg_pack_len () < 1)
- return __open_2 (path, oflag);
-
- return open (path, oflag, __builtin_va_arg_pack ());
-@}
-#endif
-@end smallexample
-@enddefbuiltin
-
-@node 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 <immintrin.h>
-
-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 <immintrin.h> // For _mm_pause
-
-int lockvar;
-
-/* Acquire lock with lock elision */
-while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE))
- _mm_pause(); /* Abort failed transaction */
-...
-/* Free lock with lock elision */
-__atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE);
-@end smallexample
-
-@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
@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{<setjmp.h>} in user code
+instead of the builtins.
+
+The built-in versions of these functions use GCC's normal
+mechanisms to save and restore registers using the stack on function
+entry and exit. The jump buffer argument @var{buf} holds only the
+information needed to restore the stack frame, rather than the entire
+set of saved register values.
+
+An important caveat is that GCC arranges to save and restore only
+those registers known to the specific architecture variant being
+compiled for. This can make @code{__builtin_setjmp} and
+@code{__builtin_longjmp} more efficient than their library
+counterparts in some cases, but it can also cause incorrect and
+mysterious behavior when mixing with code that uses the full register
+set.
+
+You should declare the jump buffer argument @var{buf} to the
+built-in functions as:
+
+@smallexample
+#include <stdint.h>
+intptr_t @var{buf}[5];
+@end smallexample
+
+@defbuiltin{{int} __builtin_setjmp (intptr_t *@var{buf})}
+This function saves the current stack context in @var{buf}.
+@code{__builtin_setjmp} returns 0 when returning directly,
+and 1 when returning from @code{__builtin_longjmp} using the same
+@var{buf}.
+@enddefbuiltin
+
+@defbuiltin{{void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val})}
+This function restores the stack context in @var{buf},
+saved by a previous call to @code{__builtin_setjmp}. After
+@code{__builtin_longjmp} is finished, the program resumes execution as
+if the matching @code{__builtin_setjmp} returns the value @var{val},
+which must be 1.
+
+Because @code{__builtin_longjmp} depends on the function return
+mechanism to restore the stack context, it cannot be called
+from the same function calling @code{__builtin_setjmp} to
+initialize @var{buf}. It can only be called from a function called
+(directly or indirectly) from the function calling @code{__builtin_setjmp}.
+@enddefbuiltin
+
+@node Constructing Calls
+@section Constructing Function Calls
+@cindex constructing calls
+@cindex forwarding calls
+
+Using the built-in functions described below, you can record
+the arguments a function received, and call another function
+with the same arguments, without knowing the number or types
+of the arguments.
+
+You can also record the return value of that function call,
+and later return that value, without knowing what data type
+the function tried to return (as long as your caller expects
+that data type).
+
+However, these built-in functions may interact badly with some
+sophisticated features or other extensions of the language. It
+is, therefore, not recommended to use them outside very simple
+functions acting as mere forwarders for their arguments.
+
+@defbuiltin{{void *} __builtin_apply_args ()}
+This built-in function returns a pointer to data
+describing how to perform a call with the same arguments as are passed
+to the current function.
+
+The function saves the arg pointer register, structure value address,
+and all registers that might be used to pass arguments to a function
+into a block of memory allocated on the stack. Then it returns the
+address of that block.
+@enddefbuiltin
+
+@defbuiltin{{void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size})}
+This built-in function invokes @var{function}
+with a copy of the parameters described by @var{arguments}
+and @var{size}.
+
+The value of @var{arguments} should be the value returned by
+@code{__builtin_apply_args}. The argument @var{size} specifies the size
+of the stack argument data, in bytes.
+
+This function returns a pointer to data describing
+how to return whatever value is returned by @var{function}. The data
+is saved in a block of memory allocated on the stack.
+
+It is not always simple to compute the proper value for @var{size}. The
+value is used by @code{__builtin_apply} to compute the amount of data
+that should be pushed on the stack and copied from the incoming argument
+area.
+@enddefbuiltin
+
+@defbuiltin{{void} __builtin_return (void *@var{result})}
+This built-in function returns the value described by @var{result} from
+the containing function. You should specify, for @var{result}, a value
+returned by @code{__builtin_apply}.
+@enddefbuiltin
+
+@defbuiltin{{} __builtin_va_arg_pack ()}
+This built-in function represents all anonymous arguments of an inline
+function. It can be used only in inline functions that are always
+inlined, never compiled as a separate function, such as those using
+@code{__attribute__ ((__always_inline__))} or
+@code{__attribute__ ((__gnu_inline__))} extern inline functions.
+It must be only passed as last argument to some other function
+with variable arguments. This is useful for writing small wrapper
+inlines for variable argument functions, when using preprocessor
+macros is undesirable. For example:
+@smallexample
+extern int myprintf (FILE *f, const char *format, ...);
+extern inline __attribute__ ((__gnu_inline__)) int
+myprintf (FILE *f, const char *format, ...)
+@{
+ int r = fprintf (f, "myprintf: ");
+ if (r < 0)
+ return r;
+ int s = fprintf (f, format, __builtin_va_arg_pack ());
+ if (s < 0)
+ return s;
+ return r + s;
+@}
+@end smallexample
+@enddefbuiltin
+
+@defbuiltin{int __builtin_va_arg_pack_len ()}
+This built-in function returns the number of anonymous arguments of
+an inline function. It can be used only in inline functions that
+are always inlined, never compiled as a separate function, such
+as those using @code{__attribute__ ((__always_inline__))} or
+@code{__attribute__ ((__gnu_inline__))} extern inline functions.
+For example following does link- or run-time checking of open
+arguments for optimized code:
+@smallexample
+#ifdef __OPTIMIZE__
+extern inline __attribute__((__gnu_inline__)) int
+myopen (const char *path, int oflag, ...)
+@{
+ if (__builtin_va_arg_pack_len () > 1)
+ warn_open_too_many_arguments ();
+
+ if (__builtin_constant_p (oflag))
+ @{
+ if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1)
+ @{
+ warn_open_missing_mode ();
+ return __open_2 (path, oflag);
+ @}
+ return open (path, oflag, __builtin_va_arg_pack ());
+ @}
+
+ if (__builtin_va_arg_pack_len () < 1)
+ return __open_2 (path, oflag);
+
+ return open (path, oflag, __builtin_va_arg_pack ());
+@}
+#endif
+@end smallexample
+@enddefbuiltin
+
+@defbuiltin{@var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})}
+
+The @var{call_exp} expression must be a function call, and the
+@var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
+is passed to the function call in the target's static chain location.
+The result of builtin is the result of the function call.
+
+@emph{Note:} This builtin is only available for C@.
+This builtin can be used to call Go closures from C.
+
+@enddefbuiltin
+
+@node Return Address
+@section Getting the Return or Frame Address of a Function
+
+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 <immintrin.h>
-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{<tgmath.h>} 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{<tgmath.h>} 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{<tgmath.h>}. 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{<tgmath.h>} 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 <immintrin.h> // 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{<tgmath.h>} 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{<tgmath.h>} 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{<tgmath.h>}. 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{<tgmath.h>} 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
projects / thirdparty / gcc.git / commitdiff
