gcc: Other Builtins
1
1 6.58 Other Built-in Functions Provided by GCC
1 =============================================
1
1 GCC provides a large number of built-in functions other than the ones
1 mentioned above. Some of these are for internal use in the processing
1 of exceptions or variable-length argument lists and are not documented
1 here because they may change from time to time; we do not recommend
1 general use of these functions.
1
1 The remaining functions are provided for optimization purposes.
1
1 With the exception of built-ins that have library equivalents such as
1 the standard C library functions discussed below, or that expand to
1 library calls, GCC built-in functions are always expanded inline and
1 thus do not have corresponding entry points and their address cannot be
1 obtained. Attempting to use them in an expression other than a function
1 call results in a compile-time error.
1
1 GCC includes built-in versions of many of the functions in the standard
1 C library. These functions come in two forms: one whose names start
1 with the '__builtin_' prefix, and the other without. Both forms have
1 the same type (including prototype), the same address (when their
1 address is taken), and the same meaning as the C library functions even
1 if you specify the '-fno-builtin' option ⇒C Dialect Options).
1 Many of these functions are only optimized in certain cases; if they are
1 not optimized in a particular case, a call to the library function is
1 emitted.
1
1 Outside strict ISO C mode ('-ansi', '-std=c90', '-std=c99' or
1 '-std=c11'), the functions '_exit', 'alloca', 'bcmp', 'bzero',
1 'dcgettext', 'dgettext', 'dremf', 'dreml', 'drem', 'exp10f', 'exp10l',
1 'exp10', 'ffsll', 'ffsl', 'ffs', 'fprintf_unlocked', 'fputs_unlocked',
1 'gammaf', 'gammal', 'gamma', 'gammaf_r', 'gammal_r', 'gamma_r',
1 'gettext', 'index', 'isascii', 'j0f', 'j0l', 'j0', 'j1f', 'j1l', 'j1',
1 'jnf', 'jnl', 'jn', 'lgammaf_r', 'lgammal_r', 'lgamma_r', 'mempcpy',
1 'pow10f', 'pow10l', 'pow10', 'printf_unlocked', 'rindex', 'scalbf',
1 'scalbl', 'scalb', 'signbit', 'signbitf', 'signbitl', 'signbitd32',
1 'signbitd64', 'signbitd128', 'significandf', 'significandl',
1 'significand', 'sincosf', 'sincosl', 'sincos', 'stpcpy', 'stpncpy',
1 'strcasecmp', 'strdup', 'strfmon', 'strncasecmp', 'strndup', 'toascii',
1 'y0f', 'y0l', 'y0', 'y1f', 'y1l', 'y1', 'ynf', 'ynl' and 'yn' may be
1 handled as built-in functions. All these functions have corresponding
1 versions prefixed with '__builtin_', which may be used even in strict
1 C90 mode.
1
1 The ISO C99 functions '_Exit', 'acoshf', 'acoshl', 'acosh', 'asinhf',
1 'asinhl', 'asinh', 'atanhf', 'atanhl', 'atanh', 'cabsf', 'cabsl',
1 'cabs', 'cacosf', 'cacoshf', 'cacoshl', 'cacosh', 'cacosl', 'cacos',
1 'cargf', 'cargl', 'carg', 'casinf', 'casinhf', 'casinhl', 'casinh',
1 'casinl', 'casin', 'catanf', 'catanhf', 'catanhl', 'catanh', 'catanl',
1 'catan', 'cbrtf', 'cbrtl', 'cbrt', 'ccosf', 'ccoshf', 'ccoshl', 'ccosh',
1 'ccosl', 'ccos', 'cexpf', 'cexpl', 'cexp', 'cimagf', 'cimagl', 'cimag',
1 'clogf', 'clogl', 'clog', 'conjf', 'conjl', 'conj', 'copysignf',
1 'copysignl', 'copysign', 'cpowf', 'cpowl', 'cpow', 'cprojf', 'cprojl',
1 'cproj', 'crealf', 'creall', 'creal', 'csinf', 'csinhf', 'csinhl',
1 'csinh', 'csinl', 'csin', 'csqrtf', 'csqrtl', 'csqrt', 'ctanf',
1 'ctanhf', 'ctanhl', 'ctanh', 'ctanl', 'ctan', 'erfcf', 'erfcl', 'erfc',
1 'erff', 'erfl', 'erf', 'exp2f', 'exp2l', 'exp2', 'expm1f', 'expm1l',
1 'expm1', 'fdimf', 'fdiml', 'fdim', 'fmaf', 'fmal', 'fmaxf', 'fmaxl',
1 'fmax', 'fma', 'fminf', 'fminl', 'fmin', 'hypotf', 'hypotl', 'hypot',
1 'ilogbf', 'ilogbl', 'ilogb', 'imaxabs', 'isblank', 'iswblank',
1 'lgammaf', 'lgammal', 'lgamma', 'llabs', 'llrintf', 'llrintl', 'llrint',
1 'llroundf', 'llroundl', 'llround', 'log1pf', 'log1pl', 'log1p', 'log2f',
1 'log2l', 'log2', 'logbf', 'logbl', 'logb', 'lrintf', 'lrintl', 'lrint',
1 'lroundf', 'lroundl', 'lround', 'nearbyintf', 'nearbyintl', 'nearbyint',
1 'nextafterf', 'nextafterl', 'nextafter', 'nexttowardf', 'nexttowardl',
1 'nexttoward', 'remainderf', 'remainderl', 'remainder', 'remquof',
1 'remquol', 'remquo', 'rintf', 'rintl', 'rint', 'roundf', 'roundl',
1 'round', 'scalblnf', 'scalblnl', 'scalbln', 'scalbnf', 'scalbnl',
1 'scalbn', 'snprintf', 'tgammaf', 'tgammal', 'tgamma', 'truncf',
1 'truncl', 'trunc', 'vfscanf', 'vscanf', 'vsnprintf' and 'vsscanf' are
1 handled as built-in functions except in strict ISO C90 mode ('-ansi' or
1 '-std=c90').
1
1 There are also built-in versions of the ISO C99 functions 'acosf',
1 'acosl', 'asinf', 'asinl', 'atan2f', 'atan2l', 'atanf', 'atanl',
1 'ceilf', 'ceill', 'cosf', 'coshf', 'coshl', 'cosl', 'expf', 'expl',
1 'fabsf', 'fabsl', 'floorf', 'floorl', 'fmodf', 'fmodl', 'frexpf',
1 'frexpl', 'ldexpf', 'ldexpl', 'log10f', 'log10l', 'logf', 'logl',
1 'modfl', 'modf', 'powf', 'powl', 'sinf', 'sinhf', 'sinhl', 'sinl',
1 'sqrtf', 'sqrtl', 'tanf', 'tanhf', 'tanhl' and 'tanl' that are
1 recognized in any mode since ISO C90 reserves these names for the
1 purpose to which ISO C99 puts them. All these functions have
1 corresponding versions prefixed with '__builtin_'.
1
1 There are also built-in functions '__builtin_fabsfN',
1 '__builtin_fabsfNx', '__builtin_copysignfN' and '__builtin_copysignfNx',
1 corresponding to the TS 18661-3 functions 'fabsfN', 'fabsfNx',
1 'copysignfN' and 'copysignfNx', for supported types '_FloatN' and
1 '_FloatNx'.
1
1 There are also GNU extension functions 'clog10', 'clog10f' and
1 'clog10l' which names are reserved by ISO C99 for future use. All these
1 functions have versions prefixed with '__builtin_'.
1
1 The ISO C94 functions 'iswalnum', 'iswalpha', 'iswcntrl', 'iswdigit',
1 'iswgraph', 'iswlower', 'iswprint', 'iswpunct', 'iswspace', 'iswupper',
1 'iswxdigit', 'towlower' and 'towupper' are handled as built-in functions
1 except in strict ISO C90 mode ('-ansi' or '-std=c90').
1
1 The ISO C90 functions 'abort', 'abs', 'acos', 'asin', 'atan2', 'atan',
1 'calloc', 'ceil', 'cosh', 'cos', 'exit', 'exp', 'fabs', 'floor', 'fmod',
1 'fprintf', 'fputs', 'frexp', 'fscanf', 'isalnum', 'isalpha', 'iscntrl',
1 'isdigit', 'isgraph', 'islower', 'isprint', 'ispunct', 'isspace',
1 'isupper', 'isxdigit', 'tolower', 'toupper', 'labs', 'ldexp', 'log10',
1 'log', 'malloc', 'memchr', 'memcmp', 'memcpy', 'memset', 'modf', 'pow',
1 'printf', 'putchar', 'puts', 'scanf', 'sinh', 'sin', 'snprintf',
1 'sprintf', 'sqrt', 'sscanf', 'strcat', 'strchr', 'strcmp', 'strcpy',
1 'strcspn', 'strlen', 'strncat', 'strncmp', 'strncpy', 'strpbrk',
1 'strrchr', 'strspn', 'strstr', 'tanh', 'tan', 'vfprintf', 'vprintf' and
1 'vsprintf' are all recognized as built-in functions unless
1 '-fno-builtin' is specified (or '-fno-builtin-FUNCTION' is specified for
1 an individual function). All of these functions have corresponding
1 versions prefixed with '__builtin_'.
1
1 GCC provides built-in versions of the ISO C99 floating-point comparison
1 macros that avoid raising exceptions for unordered operands. They have
1 the same names as the standard macros ( 'isgreater', 'isgreaterequal',
1 'isless', 'islessequal', 'islessgreater', and 'isunordered') , with
1 '__builtin_' prefixed. We intend for a library implementor to be able
1 to simply '#define' each standard macro to its built-in equivalent. In
1 the same fashion, GCC provides 'fpclassify', 'isfinite', 'isinf_sign',
1 'isnormal' and 'signbit' built-ins used with '__builtin_' prefixed. The
1 'isinf' and 'isnan' built-in functions appear both with and without the
1 '__builtin_' prefix.
1
1 -- Built-in Function: void *__builtin_alloca (size_t size)
1 The '__builtin_alloca' function must be called at block scope. The
1 function allocates an object SIZE bytes large on the stack of the
1 calling function. The object is aligned on the default stack
1 alignment boundary for the target determined by the
1 '__BIGGEST_ALIGNMENT__' macro. The '__builtin_alloca' function
1 returns a pointer to the first byte of the allocated object. The
1 lifetime of the allocated object ends just before the calling
1 function returns to its caller. This is so even when
1 '__builtin_alloca' is called within a nested block.
1
1 For example, the following function allocates eight objects of 'n'
1 bytes each on the stack, storing a pointer to each in consecutive
1 elements of the array 'a'. It then passes the array to function
1 'g' which can safely use the storage pointed to by each of the
1 array elements.
1
1 void f (unsigned n)
1 {
1 void *a [8];
1 for (int i = 0; i != 8; ++i)
1 a [i] = __builtin_alloca (n);
1
1 g (a, n); // safe
1 }
1
1 Since the '__builtin_alloca' function doesn't validate its argument
1 it is the responsibility of its caller to make sure the argument
1 doesn't cause it to exceed the stack size limit. The
1 '__builtin_alloca' function is provided to make it possible to
1 allocate on the stack arrays of bytes with an upper bound that may
1 be computed at run time. Since C99 Variable Length Arrays offer
1 similar functionality under a portable, more convenient, and safer
1 interface they are recommended instead, in both C99 and C++
11 programs where GCC provides them as an extension. ⇒Variable
Length, for details.
1
1 -- Built-in Function: void *__builtin_alloca_with_align (size_t size,
1 size_t alignment)
1 The '__builtin_alloca_with_align' function must be called at block
1 scope. The function allocates an object SIZE bytes large on the
1 stack of the calling function. The allocated object is aligned on
1 the boundary specified by the argument ALIGNMENT whose unit is
1 given in bits (not bytes). The SIZE argument must be positive and
1 not exceed the stack size limit. The ALIGNMENT argument must be a
1 constant integer expression that evaluates to a power of 2 greater
1 than or equal to 'CHAR_BIT' and less than some unspecified maximum.
1 Invocations with other values are rejected with an error indicating
1 the valid bounds. The function returns a pointer to the first byte
1 of the allocated object. The lifetime of the allocated object ends
1 at the end of the block in which the function was called. The
1 allocated storage is released no later than just before the calling
1 function returns to its caller, but may be released at the end of
1 the block in which the function was called.
1
1 For example, in the following function the call to 'g' is unsafe
1 because when 'overalign' is non-zero, the space allocated by
1 '__builtin_alloca_with_align' may have been released at the end of
1 the 'if' statement in which it was called.
1
1 void f (unsigned n, bool overalign)
1 {
1 void *p;
1 if (overalign)
1 p = __builtin_alloca_with_align (n, 64 /* bits */);
1 else
1 p = __builtin_alloc (n);
1
1 g (p, n); // unsafe
1 }
1
1 Since the '__builtin_alloca_with_align' function doesn't validate
1 its SIZE argument it is the responsibility of its caller to make
1 sure the argument doesn't cause it to exceed the stack size limit.
1 The '__builtin_alloca_with_align' function is provided to make it
1 possible to allocate on the stack overaligned arrays of bytes with
1 an upper bound that may be computed at run time. Since C99
1 Variable Length Arrays offer the same functionality under a
1 portable, more convenient, and safer interface they are recommended
1 instead, in both C99 and C++ programs where GCC provides them as an
1 extension. ⇒Variable Length, for details.
1
1 -- Built-in Function: void *__builtin_alloca_with_align_and_max (size_t
1 size, size_t alignment, size_t max_size)
1 Similar to '__builtin_alloca_with_align' but takes an extra
1 argument specifying an upper bound for SIZE in case its value
1 cannot be computed at compile time, for use by '-fstack-usage',
1 '-Wstack-usage' and '-Walloca-larger-than'. MAX_SIZE must be a
1 constant integer expression, it has no effect on code generation
1 and no attempt is made to check its compatibility with SIZE.
1
1 -- Built-in Function: int __builtin_types_compatible_p (TYPE1, TYPE2)
1
1 You can use the built-in function '__builtin_types_compatible_p' to
1 determine whether two types are the same.
1
1 This built-in function returns 1 if the unqualified versions of the
1 types TYPE1 and TYPE2 (which are types, not expressions) are
1 compatible, 0 otherwise. The result of this built-in function can
1 be used in integer constant expressions.
1
1 This built-in function ignores top level qualifiers (e.g., 'const',
1 'volatile'). For example, 'int' is equivalent to 'const int'.
1
1 The type 'int[]' and 'int[5]' are compatible. On the other hand,
1 'int' and 'char *' are not compatible, even if the size of their
1 types, on the particular architecture are the same. Also, the
1 amount of pointer indirection is taken into account when
1 determining similarity. Consequently, 'short *' is not similar to
1 'short **'. Furthermore, two types that are typedefed are
1 considered compatible if their underlying types are compatible.
1
1 An 'enum' type is not considered to be compatible with another
1 'enum' type even if both are compatible with the same integer type;
1 this is what the C standard specifies. For example, 'enum {foo,
1 bar}' is not similar to 'enum {hot, dog}'.
1
1 You typically use this function in code whose execution varies
1 depending on the arguments' types. For example:
1
1 #define foo(x) \
1 ({ \
1 typeof (x) tmp = (x); \
1 if (__builtin_types_compatible_p (typeof (x), long double)) \
1 tmp = foo_long_double (tmp); \
1 else if (__builtin_types_compatible_p (typeof (x), double)) \
1 tmp = foo_double (tmp); \
1 else if (__builtin_types_compatible_p (typeof (x), float)) \
1 tmp = foo_float (tmp); \
1 else \
1 abort (); \
1 tmp; \
1 })
1
1 _Note:_ This construct is only available for C.
1
1 -- Built-in Function: TYPE __builtin_call_with_static_chain (CALL_EXP,
1 POINTER_EXP)
1
1 The CALL_EXP expression must be a function call, and the
1 POINTER_EXP expression must be a pointer. The POINTER_EXP is
1 passed to the function call in the target's static chain location.
1 The result of builtin is the result of the function call.
1
1 _Note:_ This builtin is only available for C. This builtin can be
1 used to call Go closures from C.
1
1 -- Built-in Function: TYPE __builtin_choose_expr (CONST_EXP, EXP1,
1 EXP2)
1
1 You can use the built-in function '__builtin_choose_expr' to
1 evaluate code depending on the value of a constant expression.
1 This built-in function returns EXP1 if CONST_EXP, which is an
1 integer constant expression, is nonzero. Otherwise it returns
1 EXP2.
1
1 This built-in function is analogous to the '? :' operator in C,
1 except that the expression returned has its type unaltered by
1 promotion rules. Also, the built-in function does not evaluate the
1 expression that is not chosen. For example, if CONST_EXP evaluates
1 to true, EXP2 is not evaluated even if it has side effects.
1
1 This built-in function can return an lvalue if the chosen argument
1 is an lvalue.
1
1 If EXP1 is returned, the return type is the same as EXP1's type.
1 Similarly, if EXP2 is returned, its return type is the same as
1 EXP2.
1
1 Example:
1
1 #define foo(x) \
1 __builtin_choose_expr ( \
1 __builtin_types_compatible_p (typeof (x), double), \
1 foo_double (x), \
1 __builtin_choose_expr ( \
1 __builtin_types_compatible_p (typeof (x), float), \
1 foo_float (x), \
1 /* The void expression results in a compile-time error \
1 when assigning the result to something. */ \
1 (void)0))
1
1 _Note:_ This construct is only available for C. Furthermore, the
1 unused expression (EXP1 or EXP2 depending on the value of
1 CONST_EXP) may still generate syntax errors. This may change in
1 future revisions.
1
1 -- Built-in Function: TYPE __builtin_tgmath (FUNCTIONS, ARGUMENTS)
1
1 The built-in function '__builtin_tgmath', available only for C and
1 Objective-C, calls a function determined according to the rules of
1 '<tgmath.h>' macros. It is intended to be used in implementations
1 of that header, so that expansions of macros from that header only
1 expand each of their arguments once, to avoid problems when calls
1 to such macros are nested inside the arguments of other calls to
1 such macros; in addition, it results in better diagnostics for
1 invalid calls to '<tgmath.h>' macros than implementations using
1 other GNU C language features. For example, the 'pow' type-generic
1 macro might be defined as:
1
1 #define pow(a, b) __builtin_tgmath (powf, pow, powl, \
1 cpowf, cpow, cpowl, a, b)
1
1 The arguments to '__builtin_tgmath' are at least two pointers to
1 functions, followed by the arguments to the type-generic macro
1 (which will be passed as arguments to the selected function). All
1 the pointers to functions must be pointers to prototyped functions,
1 none of which may have variable arguments, and all of which must
1 have the same number of parameters; the number of parameters of the
1 first function determines how many arguments to '__builtin_tgmath'
1 are interpreted as function pointers, and how many as the arguments
1 to the called function.
1
1 The types of the specified functions must all be different, but
1 related to each other in the same way as a set of functions that
1 may be selected between by a macro in '<tgmath.h>'. This means
1 that the functions are parameterized by a floating-point type T,
1 different for each such function. The function return types may
1 all be the same type, or they may be T for each function, or they
1 may be the real type corresponding to T for each function (if some
1 of the types T are complex). Likewise, for each parameter
1 position, the type of the parameter in that position may always be
1 the same type, or may be T for each function (this case must apply
1 for at least one parameter position), or may be the real type
1 corresponding to T for each function.
1
1 The standard rules for '<tgmath.h>' macros are used to find a
1 common type U from the types of the arguments for parameters whose
1 types vary between the functions; complex integer types (a GNU
1 extension) are treated like '_Complex double' for this purpose (or
1 '_Complex _Float64' if all the function return types are the same
1 '_FloatN' or '_FloatNx' type). If the function return types vary,
1 or are all the same integer type, the function called is the one
1 for which T is U, and it is an error if there is no such function.
1 If the function return types are all the same floating-point type,
1 the type-generic macro is taken to be one of those from TS 18661
1 that rounds the result to a narrower type; if there is a function
1 for which T is U, it is called, and otherwise the first function,
1 if any, for which T has at least the range and precision of U is
1 called, and it is an error if there is no such function.
1
1 -- Built-in Function: TYPE __builtin_complex (REAL, IMAG)
1
1 The built-in function '__builtin_complex' is provided for use in
1 implementing the ISO C11 macros 'CMPLXF', 'CMPLX' and 'CMPLXL'.
1 REAL and IMAG must have the same type, a real binary floating-point
1 type, and the result has the corresponding complex type with real
1 and imaginary parts REAL and IMAG. Unlike 'REAL + I * IMAG', this
1 works even when infinities, NaNs and negative zeros are involved.
1
1 -- Built-in Function: int __builtin_constant_p (EXP)
1 You can use the built-in function '__builtin_constant_p' to
1 determine if a value is known to be constant at compile time and
1 hence that GCC can perform constant-folding on expressions
1 involving that value. The argument of the function is the value to
1 test. The function returns the integer 1 if the argument is known
1 to be a compile-time constant and 0 if it is not known to be a
1 compile-time constant. A return of 0 does not indicate that the
1 value is _not_ a constant, but merely that GCC cannot prove it is a
1 constant with the specified value of the '-O' option.
1
1 You typically use this function in an embedded application where
1 memory is a critical resource. If you have some complex
1 calculation, you may want it to be folded if it involves constants,
1 but need to call a function if it does not. For example:
1
1 #define Scale_Value(X) \
1 (__builtin_constant_p (X) \
1 ? ((X) * SCALE + OFFSET) : Scale (X))
1
1 You may use this built-in function in either a macro or an inline
1 function. However, if you use it in an inlined function and pass
1 an argument of the function as the argument to the built-in, GCC
1 never returns 1 when you call the inline function with a string
1 constant or compound literal (⇒Compound Literals) and does
1 not return 1 when you pass a constant numeric value to the inline
1 function unless you specify the '-O' option.
1
1 You may also use '__builtin_constant_p' in initializers for static
1 data. For instance, you can write
1
1 static const int table[] = {
1 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1,
1 /* ... */
1 };
1
1 This is an acceptable initializer even if EXPRESSION is not a
1 constant expression, including the case where
1 '__builtin_constant_p' returns 1 because EXPRESSION can be folded
1 to a constant but EXPRESSION contains operands that are not
1 otherwise permitted in a static initializer (for example, '0 && foo
1 ()'). GCC must be more conservative about evaluating the built-in
1 in this case, because it has no opportunity to perform
1 optimization.
1
1 -- Built-in Function: long __builtin_expect (long EXP, long C)
1 You may use '__builtin_expect' to provide the compiler with branch
1 prediction information. In general, you should prefer to use
1 actual profile feedback for this ('-fprofile-arcs'), as programmers
1 are notoriously bad at predicting how their programs actually
1 perform. However, there are applications in which this data is
1 hard to collect.
1
1 The return value is the value of EXP, which should be an integral
1 expression. The semantics of the built-in are that it is expected
1 that EXP == C. For example:
1
1 if (__builtin_expect (x, 0))
1 foo ();
1
1 indicates that we do not expect to call 'foo', since we expect 'x'
1 to be zero. Since you are limited to integral expressions for EXP,
1 you should use constructions such as
1
1 if (__builtin_expect (ptr != NULL, 1))
1 foo (*ptr);
1
1 when testing pointer or floating-point values.
1
1 -- Built-in Function: void __builtin_trap (void)
1 This function causes the program to exit abnormally. GCC
1 implements this function by using a target-dependent mechanism
1 (such as intentionally executing an illegal instruction) or by
1 calling 'abort'. The mechanism used may vary from release to
1 release so you should not rely on any particular implementation.
1
1 -- Built-in Function: void __builtin_unreachable (void)
1 If control flow reaches the point of the '__builtin_unreachable',
1 the program is undefined. It is useful in situations where the
1 compiler cannot deduce the unreachability of the code.
1
1 One such case is immediately following an 'asm' statement that
1 either never terminates, or one that transfers control elsewhere
1 and never returns. In this example, without the
1 '__builtin_unreachable', GCC issues a warning that control reaches
1 the end of a non-void function. It also generates code to return
1 after the 'asm'.
1
1 int f (int c, int v)
1 {
1 if (c)
1 {
1 return v;
1 }
1 else
1 {
1 asm("jmp error_handler");
1 __builtin_unreachable ();
1 }
1 }
1
1 Because the 'asm' statement unconditionally transfers control out
1 of the function, control never reaches the end of the function
1 body. The '__builtin_unreachable' is in fact unreachable and
1 communicates this fact to the compiler.
1
1 Another use for '__builtin_unreachable' is following a call a
1 function that never returns but that is not declared
1 '__attribute__((noreturn))', as in this example:
1
1 void function_that_never_returns (void);
1
1 int g (int c)
1 {
1 if (c)
1 {
1 return 1;
1 }
1 else
1 {
1 function_that_never_returns ();
1 __builtin_unreachable ();
1 }
1 }
1
1 -- Built-in Function: void * __builtin_assume_aligned (const void *EXP,
1 size_t ALIGN, ...)
1 This function returns its first argument, and allows the compiler
1 to assume that the returned pointer is at least ALIGN bytes
1 aligned. This built-in can have either two or three arguments, if
1 it has three, the third argument should have integer type, and if
1 it is nonzero means misalignment offset. For example:
1
1 void *x = __builtin_assume_aligned (arg, 16);
1
1 means that the compiler can assume 'x', set to 'arg', is at least
1 16-byte aligned, while:
1
1 void *x = __builtin_assume_aligned (arg, 32, 8);
1
1 means that the compiler can assume for 'x', set to 'arg', that
1 '(char *) x - 8' is 32-byte aligned.
1
1 -- Built-in Function: int __builtin_LINE ()
1 This function is the equivalent of the preprocessor '__LINE__'
1 macro and returns a constant integer expression that evaluates to
1 the line number of the invocation of the built-in. When used as a
1 C++ default argument for a function F, it returns the line number
1 of the call to F.
1
1 -- Built-in Function: const char * __builtin_FUNCTION ()
1 This function is the equivalent of the '__FUNCTION__' symbol and
1 returns an address constant pointing to the name of the function
1 from which the built-in was invoked, or the empty string if the
1 invocation is not at function scope. When used as a C++ default
1 argument for a function F, it returns the name of F's caller or the
1 empty string if the call was not made at function scope.
1
1 -- Built-in Function: const char * __builtin_FILE ()
1 This function is the equivalent of the preprocessor '__FILE__'
1 macro and returns an address constant pointing to the file name
1 containing the invocation of the built-in, or the empty string if
1 the invocation is not at function scope. When used as a C++
1 default argument for a function F, it returns the file name of the
1 call to F or the empty string if the call was not made at function
1 scope.
1
1 For example, in the following, each call to function 'foo' will
1 print a line similar to '"file.c:123: foo: message"' with the name
1 of the file and the line number of the 'printf' call, the name of
1 the function 'foo', followed by the word 'message'.
1
1 const char*
1 function (const char *func = __builtin_FUNCTION ())
1 {
1 return func;
1 }
1
1 void foo (void)
1 {
1 printf ("%s:%i: %s: message\n", file (), line (), function ());
1 }
1
1 -- Built-in Function: void __builtin___clear_cache (char *BEGIN, char
1 *END)
1 This function is used to flush the processor's instruction cache
1 for the region of memory between BEGIN inclusive and END exclusive.
1 Some targets require that the instruction cache be flushed, after
1 modifying memory containing code, in order to obtain deterministic
1 behavior.
1
1 If the target does not require instruction cache flushes,
1 '__builtin___clear_cache' has no effect. Otherwise either
1 instructions are emitted in-line to clear the instruction cache or
1 a call to the '__clear_cache' function in libgcc is made.
1
1 -- Built-in Function: void __builtin_prefetch (const void *ADDR, ...)
1 This function is used to minimize cache-miss latency by moving data
1 into a cache before it is accessed. You can insert calls to
1 '__builtin_prefetch' into code for which you know addresses of data
1 in memory that is likely to be accessed soon. If the target
1 supports them, data prefetch instructions are generated. If the
1 prefetch is done early enough before the access then the data will
1 be in the cache by the time it is accessed.
1
1 The value of ADDR is the address of the memory to prefetch. There
1 are two optional arguments, RW and LOCALITY. The value of RW is a
1 compile-time constant one or zero; one means that the prefetch is
1 preparing for a write to the memory address and zero, the default,
1 means that the prefetch is preparing for a read. The value
1 LOCALITY must be a compile-time constant integer between zero and
1 three. A value of zero means that the data has no temporal
1 locality, so it need not be left in the cache after the access. A
1 value of three means that the data has a high degree of temporal
1 locality and should be left in all levels of cache possible.
1 Values of one and two mean, respectively, a low or moderate degree
1 of temporal locality. The default is three.
1
1 for (i = 0; i < n; i++)
1 {
1 a[i] = a[i] + b[i];
1 __builtin_prefetch (&a[i+j], 1, 1);
1 __builtin_prefetch (&b[i+j], 0, 1);
1 /* ... */
1 }
1
1 Data prefetch does not generate faults if ADDR is invalid, but the
1 address expression itself must be valid. For example, a prefetch
1 of 'p->next' does not fault if 'p->next' is not a valid address,
1 but evaluation faults if 'p' is not a valid address.
1
1 If the target does not support data prefetch, the address
1 expression is evaluated if it includes side effects but no other
1 code is generated and GCC does not issue a warning.
1
1 -- Built-in Function: double __builtin_huge_val (void)
1 Returns a positive infinity, if supported by the floating-point
1 format, else 'DBL_MAX'. This function is suitable for implementing
1 the ISO C macro 'HUGE_VAL'.
1
1 -- Built-in Function: float __builtin_huge_valf (void)
1 Similar to '__builtin_huge_val', except the return type is 'float'.
1
1 -- Built-in Function: long double __builtin_huge_vall (void)
1 Similar to '__builtin_huge_val', except the return type is 'long
1 double'.
1
1 -- Built-in Function: _FloatN __builtin_huge_valfN (void)
1 Similar to '__builtin_huge_val', except the return type is
1 '_FloatN'.
1
1 -- Built-in Function: _FloatNx __builtin_huge_valfNx (void)
1 Similar to '__builtin_huge_val', except the return type is
1 '_FloatNx'.
1
1 -- Built-in Function: int __builtin_fpclassify (int, int, int, int,
1 int, ...)
1 This built-in implements the C99 fpclassify functionality. The
1 first five int arguments should be the target library's notion of
1 the possible FP classes and are used for return values. They must
1 be constant values and they must appear in this order: 'FP_NAN',
1 'FP_INFINITE', 'FP_NORMAL', 'FP_SUBNORMAL' and 'FP_ZERO'. The
1 ellipsis is for exactly one floating-point value to classify. GCC
1 treats the last argument as type-generic, which means it does not
1 do default promotion from float to double.
1
1 -- Built-in Function: double __builtin_inf (void)
1 Similar to '__builtin_huge_val', except a warning is generated if
1 the target floating-point format does not support infinities.
1
1 -- Built-in Function: _Decimal32 __builtin_infd32 (void)
1 Similar to '__builtin_inf', except the return type is '_Decimal32'.
1
1 -- Built-in Function: _Decimal64 __builtin_infd64 (void)
1 Similar to '__builtin_inf', except the return type is '_Decimal64'.
1
1 -- Built-in Function: _Decimal128 __builtin_infd128 (void)
1 Similar to '__builtin_inf', except the return type is
1 '_Decimal128'.
1
1 -- Built-in Function: float __builtin_inff (void)
1 Similar to '__builtin_inf', except the return type is 'float'.
1 This function is suitable for implementing the ISO C99 macro
1 'INFINITY'.
1
1 -- Built-in Function: long double __builtin_infl (void)
1 Similar to '__builtin_inf', except the return type is 'long
1 double'.
1
1 -- Built-in Function: _FloatN __builtin_inffN (void)
1 Similar to '__builtin_inf', except the return type is '_FloatN'.
1
1 -- Built-in Function: _FloatN __builtin_inffNx (void)
1 Similar to '__builtin_inf', except the return type is '_FloatNx'.
1
1 -- Built-in Function: int __builtin_isinf_sign (...)
1 Similar to 'isinf', except the return value is -1 for an argument
1 of '-Inf' and 1 for an argument of '+Inf'. Note while the
1 parameter list is an ellipsis, this function only accepts exactly
1 one floating-point argument. GCC treats this parameter as
1 type-generic, which means it does not do default promotion from
1 float to double.
1
1 -- Built-in Function: double __builtin_nan (const char *str)
1 This is an implementation of the ISO C99 function 'nan'.
1
1 Since ISO C99 defines this function in terms of 'strtod', which we
1 do not implement, a description of the parsing is in order. The
1 string is parsed as by 'strtol'; that is, the base is recognized by
1 leading '0' or '0x' prefixes. The number parsed is placed in the
1 significand such that the least significant bit of the number is at
1 the least significant bit of the significand. The number is
1 truncated to fit the significand field provided. The significand
1 is forced to be a quiet NaN.
1
1 This function, if given a string literal all of which would have
1 been consumed by 'strtol', is evaluated early enough that it is
1 considered a compile-time constant.
1
1 -- Built-in Function: _Decimal32 __builtin_nand32 (const char *str)
1 Similar to '__builtin_nan', except the return type is '_Decimal32'.
1
1 -- Built-in Function: _Decimal64 __builtin_nand64 (const char *str)
1 Similar to '__builtin_nan', except the return type is '_Decimal64'.
1
1 -- Built-in Function: _Decimal128 __builtin_nand128 (const char *str)
1 Similar to '__builtin_nan', except the return type is
1 '_Decimal128'.
1
1 -- Built-in Function: float __builtin_nanf (const char *str)
1 Similar to '__builtin_nan', except the return type is 'float'.
1
1 -- Built-in Function: long double __builtin_nanl (const char *str)
1 Similar to '__builtin_nan', except the return type is 'long
1 double'.
1
1 -- Built-in Function: _FloatN __builtin_nanfN (const char *str)
1 Similar to '__builtin_nan', except the return type is '_FloatN'.
1
1 -- Built-in Function: _FloatNx __builtin_nanfNx (const char *str)
1 Similar to '__builtin_nan', except the return type is '_FloatNx'.
1
1 -- Built-in Function: double __builtin_nans (const char *str)
1 Similar to '__builtin_nan', except the significand is forced to be
1 a signaling NaN. The 'nans' function is proposed by WG14 N965.
1
1 -- Built-in Function: float __builtin_nansf (const char *str)
1 Similar to '__builtin_nans', except the return type is 'float'.
1
1 -- Built-in Function: long double __builtin_nansl (const char *str)
1 Similar to '__builtin_nans', except the return type is 'long
1 double'.
1
1 -- Built-in Function: _FloatN __builtin_nansfN (const char *str)
1 Similar to '__builtin_nans', except the return type is '_FloatN'.
1
1 -- Built-in Function: _FloatNx __builtin_nansfNx (const char *str)
1 Similar to '__builtin_nans', except the return type is '_FloatNx'.
1
1 -- Built-in Function: int __builtin_ffs (int x)
1 Returns one plus the index of the least significant 1-bit of X, or
1 if X is zero, returns zero.
1
1 -- Built-in Function: int __builtin_clz (unsigned int x)
1 Returns the number of leading 0-bits in X, starting at the most
1 significant bit position. If X is 0, the result is undefined.
1
1 -- Built-in Function: int __builtin_ctz (unsigned int x)
1 Returns the number of trailing 0-bits in X, starting at the least
1 significant bit position. If X is 0, the result is undefined.
1
1 -- Built-in Function: int __builtin_clrsb (int x)
1 Returns the number of leading redundant sign bits in X, i.e. the
1 number of bits following the most significant bit that are
1 identical to it. There are no special cases for 0 or other values.
1
1 -- Built-in Function: int __builtin_popcount (unsigned int x)
1 Returns the number of 1-bits in X.
1
1 -- Built-in Function: int __builtin_parity (unsigned int x)
1 Returns the parity of X, i.e. the number of 1-bits in X modulo 2.
1
1 -- Built-in Function: int __builtin_ffsl (long)
1 Similar to '__builtin_ffs', except the argument type is 'long'.
1
1 -- Built-in Function: int __builtin_clzl (unsigned long)
1 Similar to '__builtin_clz', except the argument type is 'unsigned
1 long'.
1
1 -- Built-in Function: int __builtin_ctzl (unsigned long)
1 Similar to '__builtin_ctz', except the argument type is 'unsigned
1 long'.
1
1 -- Built-in Function: int __builtin_clrsbl (long)
1 Similar to '__builtin_clrsb', except the argument type is 'long'.
1
1 -- Built-in Function: int __builtin_popcountl (unsigned long)
1 Similar to '__builtin_popcount', except the argument type is
1 'unsigned long'.
1
1 -- Built-in Function: int __builtin_parityl (unsigned long)
1 Similar to '__builtin_parity', except the argument type is
1 'unsigned long'.
1
1 -- Built-in Function: int __builtin_ffsll (long long)
1 Similar to '__builtin_ffs', except the argument type is 'long
1 long'.
1
1 -- Built-in Function: int __builtin_clzll (unsigned long long)
1 Similar to '__builtin_clz', except the argument type is 'unsigned
1 long long'.
1
1 -- Built-in Function: int __builtin_ctzll (unsigned long long)
1 Similar to '__builtin_ctz', except the argument type is 'unsigned
1 long long'.
1
1 -- Built-in Function: int __builtin_clrsbll (long long)
1 Similar to '__builtin_clrsb', except the argument type is 'long
1 long'.
1
1 -- Built-in Function: int __builtin_popcountll (unsigned long long)
1 Similar to '__builtin_popcount', except the argument type is
1 'unsigned long long'.
1
1 -- Built-in Function: int __builtin_parityll (unsigned long long)
1 Similar to '__builtin_parity', except the argument type is
1 'unsigned long long'.
1
1 -- Built-in Function: double __builtin_powi (double, int)
1 Returns the first argument raised to the power of the second.
1 Unlike the 'pow' function no guarantees about precision and
1 rounding are made.
1
1 -- Built-in Function: float __builtin_powif (float, int)
1 Similar to '__builtin_powi', except the argument and return types
1 are 'float'.
1
1 -- Built-in Function: long double __builtin_powil (long double, int)
1 Similar to '__builtin_powi', except the argument and return types
1 are 'long double'.
1
1 -- Built-in Function: uint16_t __builtin_bswap16 (uint16_t x)
1 Returns X with the order of the bytes reversed; for example,
1 '0xaabb' becomes '0xbbaa'. Byte here always means exactly 8 bits.
1
1 -- Built-in Function: uint32_t __builtin_bswap32 (uint32_t x)
1 Similar to '__builtin_bswap16', except the argument and return
1 types are 32 bit.
1
1 -- Built-in Function: uint64_t __builtin_bswap64 (uint64_t x)
1 Similar to '__builtin_bswap32', except the argument and return
1 types are 64 bit.
1
1 -- Built-in Function: Pmode __builtin_extend_pointer (void * x)
1 On targets where the user visible pointer size is smaller than the
1 size of an actual hardware address this function returns the
1 extended user pointer. Targets where this is true included ILP32
1 mode on x86_64 or Aarch64. This function is mainly useful when
1 writing inline assembly code.
1