5.43 Other built-in functions provided by GNU CC

GNU CC 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 will not be documented here because they may change from time to time; we do not recommend general use of these functions.

The remaining functions are provided for optimization purposes.

GNU CC includes built-in versions of many of the functions in the standard C library. The versions prefixed with __builtin_ will always be treated as having the same meaning as the C library function even if you specify the `-fno-builtin' (see section 3.4 Options Controlling C Dialect) option. Many of these functions are only optimized in certain cases; if not optimized in a particular case, a call to the library function will be emitted.

The functions abort, exit, _Exit and _exit are recognized and presumed not to return, but otherwise are not built in. _exit is not recognized in strict ISO C mode (`-ansi', `-std=c89' or `-std=c99'). _Exit is not recognized in strict C89 mode (`-ansi' or `-std=c89').

Outside strict ISO C mode, the functions alloca, bcmp, bzero, index, rindex and ffs may be handled as built-in functions. Corresponding versions __builtin_alloca, __builtin_bcmp, __builtin_bzero, __builtin_index, __builtin_rindex and __builtin_ffs are also recognized in strict ISO C mode.

The ISO C99 functions conj, conjf, conjl, creal, crealf, creall, cimag, cimagf, cimagl, llabs and imaxabs are handled as built-in functions except in strict ISO C89 mode. There are also built-in versions of the ISO C99 functions cosf, cosl, fabsf, fabsl, sinf, sinl, sqrtf, and sqrtl, that are recognized in any mode since ISO C89 reserves these names for the purpose to which ISO C99 puts them. All these functions have corresponding versions prefixed with __builtin_.

The following ISO C89 functions are recognized as built-in functions unless `-fno-builtin' is specified: abs, cos, fabs, fprintf, fputs, labs, memcmp, memcpy, memset, printf, sin, sqrt, strcat, strchr, strcmp, strcpy, strcspn, strlen, strncat, strncmp, strncpy, strpbrk, strrchr, strspn, and strstr. All of these functions have corresponding versions prefixed with __builtin_.

GNU CC provides built-in versions of the ISO C99 floating point comparison macros (that avoid raising exceptions for unordered operands): __builtin_isgreater, __builtin_isgreaterequal, __builtin_isless, __builtin_islessequal, __builtin_islessgreater, and __builtin_isunordered.

Built-in Function: int __builtin_constant_p (exp)

You can use the built-in function __builtin_constant_p to determine if a value is known to be constant at compile-time and hence that GNU CC can perform constant-folding on expressions involving that value. The argument of the function is the value to test. 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. A return of 0 does not indicate that the value is not a constant, but merely that GNU CC cannot prove it is a constant with the specified value of the `-O' option.

You would typically use this function in an embedded application where memory was 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:

#define Scale_Value(X) \ (__builtin_constant_p (X) \ ? ((X) * SCALE + OFFSET) : Scale (X))

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, GNU CC will never return 1 when you call the inline function with a string constant or compound literal (see section 5.21 Compound Literals) and will not return 1 when you pass a constant numeric value to the inline function unless you specify the `-O' option.

Built-in Function: long __builtin_expect (long exp, long c)

You may use __builtin_expect to provide the compiler with branch prediction information. In general, you should prefer to use actual profile feedback for this (`-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 exp, which should be an integral expression. The value of c must be a compile-time constant. The semantics of the built-in are that it is expected that exp == c. For example:

if (__builtin_expect (x, 0)) foo ();

would indicate that we do not expect to call foo, since we expect x to be zero. Since you are limited to integral expressions for exp, you should use constructions such as

if (__builtin_expect (ptr != NULL, 1)) error ();

when testing pointer or floating-point values.