diff options
Diffstat (limited to 'gcc/doc')
| -rw-r--r-- | gcc/doc/extend.texi | 3896 | ||||
| -rw-r--r-- | gcc/doc/gcc.texi | 1 | ||||
| -rw-r--r-- | gcc/doc/invoke.texi | 312 |
3 files changed, 2302 insertions, 1907 deletions
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index ed766e5..ae3357f 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -26,14 +26,7 @@ extensions, accepted by GCC in C90 mode and in C++. * Additional Numeric Types:: Additional sizes and formats, plus complex numbers. * Aggregate Types:: Extensions to arrays, structs, and unions. * Named Address Spaces::Named address spaces. -* Function Attributes:: Declaring that functions have no side effects, - or that they can never return. -* Variable Attributes:: Specifying attributes of variables. -* Type Attributes:: Specifying attributes of types. -* Label Attributes:: Specifying attributes on labels. -* Enumerator Attributes:: Specifying attributes on enumerators. -* Statement Attributes:: Specifying attributes on statements. -* Attribute Syntax:: Formal syntax for attributes. +* Attributes:: GCC supports both standard and legacy attribute syntax. * Pragmas:: Pragmas accepted by GCC. * Thread-Local:: Per-thread variables. * OpenMP:: Multiprocessing extensions. @@ -43,22 +36,6 @@ extensions, accepted by GCC in C90 mode and in C++. * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. * Syntax Extensions:: Other extensions to C syntax. * Semantic Extensions:: GNU C defines behavior for some non-standard constructs. -* Nonlocal Gotos:: Built-ins for nonlocal gotos. -* Constructing Calls:: Built-ins for dispatching a call to another function. -* Return Address:: Getting the return or frame address of a function. -* Stack Scrubbing:: Stack scrubbing internal interfaces. -* Vector Extensions:: Using vector instructions through built-in functions. -* __sync Builtins:: Legacy built-in functions for atomic memory access. -* __atomic Builtins:: Atomic built-in functions with memory model. -* Integer Overflow Builtins:: Built-in functions to perform arithmetics and - arithmetic overflow checking. -* x86 specific memory model extensions for transactional memory:: x86 memory models. -* Object Size Checking:: Built-in functions for limited buffer overflow - checking. -* New/Delete Builtins:: Built-in functions for C++ allocations and deallocations. -* Other Builtins:: Other built-in functions. -* Target Builtins:: Built-in functions specific to particular targets. -* Target Format Checks:: Format checks specific to particular targets. @end menu @node Additional Numeric Types @@ -1596,8 +1573,43 @@ The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are defined when these address spaces are supported. @end table +@node Attributes +@section Attributes Specific to GCC +@cindex attributes +@cindex declaring attributes +@cindex GNU attributes + +Attributes provide a mechanism to declare additional properties of +functions, variables, types, and statements. For example, attributes +can be used to control placement of objects in particular memory +sections, or to specify properties that can allow the compiler to +generate better code or diagnostics, such as declaring that a function +never returns. GCC supports a large number of such attributes, which +are documented in this section. + +GCC provides two different ways to specify attributes: the traditional +GNU syntax using @samp{__attribute__ ((...))} annotations, and the +newer standard C and C++ syntax using @samp{[[...]]} with the +@samp{gnu::} namespace prefix on attribute names. +The traditional syntax, described in detail in @ref{Attribute Syntax}, +is supported in all non-strict C and C++ language dialects. +The standard syntax is supported in C with @option{-std=c23} or later, +in C++ with @option{-std=c++11} or later, and as an extension in older +GNU C and C++ dialects. + +@menu +* Function Attributes:: Declaring that functions have no side effects, + or that they can never return. +* Variable Attributes:: Specifying attributes of variables. +* Type Attributes:: Specifying attributes of types. +* Label Attributes:: Specifying attributes on labels. +* Enumerator Attributes:: Specifying attributes on enumerators. +* Statement Attributes:: Specifying attributes on statements. +* Attribute Syntax:: Formal syntax for attributes. +@end menu + @node Function Attributes -@section Declaring Attributes of Functions +@subsection Declaring Attributes of Functions @cindex function attributes @cindex declaring attributes of functions @@ -1699,7 +1711,7 @@ GCC plugins may provide their own attributes. @end menu @node Common Function Attributes -@subsection Common Function Attributes +@subsubsection Common Function Attributes The following attributes are supported on most targets. @@ -1716,23 +1728,24 @@ write-only accesses to objects that are never read from. Such accesses may be diagnosed by warnings such as @option{-Wstringop-overflow}, @option{-Wuninitialized}, @option{-Wunused}, and others. -The @code{access} attribute specifies that a function to whose by-reference -arguments the attribute applies accesses the referenced object according to -@var{access-mode}. The @var{access-mode} argument is required and must be -one of four names: @code{read_only}, @code{read_write}, @code{write_only}, -or @code{none}. The remaining two are positional arguments. +The @code{access} attribute specifies that a pointer or reference argument +to the function is accessed according to @var{access-mode}, which must be +one of @code{read_only}, @code{read_write}, @code{write_only}, +or @code{none}. The semantics of these modes are described below. -The required @var{ref-index} positional argument denotes a function -argument of pointer (or in C++, reference) type that is subject to -the access. The same pointer argument can be referenced by at most one -distinct @code{access} attribute. +The argument the attribute applies to is identifed by @var{ref-index}, which +is an integer constant representing its position in the argument list. +Argument numbering starts from 1. You can specify multiple @code{access} +attributes to describe the access modes of different arguments, but multiple +@code{access} attributes applying to the same argument are not permitted. -The optional @var{size-index} positional argument denotes a function +The optional @var{size-index} denotes the position of a function argument of integer type that specifies the maximum size of the access. The size is the number of elements of the type referenced by @var{ref-index}, or the number of bytes when the pointer type is @code{void*}. When no @var{size-index} argument is specified, the pointer argument must be either -null or point to a space that is suitably aligned and large for at least one +null or point to a space that is suitably aligned and large enough +for at least one object of the referenced type (this implies that a past-the-end pointer is not a valid argument). The actual size of the access may be less but it must not be more. @@ -1744,7 +1757,7 @@ is zero, the referenced object must be initialized. The mode implies a stronger guarantee than the @code{const} qualifier which, when cast away from a pointer, does not prevent the pointed-to object from being modified. Examples of the use of the @code{read_only} access mode is the argument to -the @code{puts} function, or the second and third arguments to +the @code{puts} function, or the second argument to the @code{memcpy} function. @smallexample @@ -1784,12 +1797,13 @@ __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (char*, int, FILE*); @end smallexample -The access mode @code{none} specifies that the pointer to which it applies +The access mode @code{none} specifies that the pointer argument +to which it applies is not used to access the referenced object at all. Unless the pointer is -null the pointed-to object must exist and have at least the size as denoted +null, the pointed-to object must exist and have at least the size as denoted by the @var{size-index} argument. When the optional @var{size-index} -argument is omitted for an argument of @code{void*} type the actual pointer -agument is ignored. The referenced object need not be initialized. +argument is omitted for an argument of @code{void*} type, the actual pointer +argument is ignored. The referenced object need not be initialized. The mode is intended to be used as a means to help validate the expected object size, for example in functions that call @code{__builtin_object_size}. @xref{Object Size Checking}. @@ -1800,7 +1814,8 @@ an access @strong{will} happen. Also, the @code{access} attribute does not imply the attribute @code{nonnull} nor the attribute @code{nonnull_if_nonzero}; it may be appropriate to add both attributes at the declaration of a function that unconditionally manipulates a buffer via a pointer argument. See the -@code{nonnull} or @code{nonnull_if_nonzero} attributes for more information and +@code{nonnull} or @code{nonnull_if_nonzero} function attributes, +documented later in this section, for more information and caveats. @cindex @code{alias} function attribute @@ -2023,24 +2038,32 @@ called. Functions with these attributes are useful for initializing data that is used implicitly during the execution of the program. -On some targets the attributes also accept an integer argument to +On most targets the attributes also accept an integer argument to specify a priority to control the order in which constructor and -destructor functions are run. A constructor -with a smaller priority number runs before a constructor with a larger -priority number; the opposite relationship holds for destructors. Note -that priorities 0-100 are reserved. So, if you have a constructor that +destructor functions are run. The @var{priority} argument is a +constant integral expression bounded between 101 and 65535 inclusive; +priorities 0-100 are reserved for use by the compiler and its runtime +libraries. +A constructor with a smaller priority number runs before a constructor with +a larger priority number; the opposite relationship holds for destructors. +So, if you have a constructor that allocates a resource and a destructor that deallocates the same -resource, both functions typically have the same priority. The -priorities for constructor and destructor functions are the same as -those specified for namespace-scope C++ objects (@pxref{C++ Attributes}). -However, at present, the order in which constructors for C++ objects -with static storage duration and functions decorated with attribute -@code{constructor} are invoked is unspecified. In mixed declarations, -attribute @code{init_priority} can be used to impose a specific ordering. - -Using the argument forms of the @code{constructor} and @code{destructor} -attributes on targets where the feature is not supported is rejected with -an error. +resource, both functions typically have the same priority. + +The order in which constructors for C++ objects with static storage +duration are invoked relative to functions decorated with attribute +@code{constructor} is normally unspecified. You can use +attribute @code{init_priority} (@pxref{C++ Attributes}) on the +declarations of namespace-scope C++ objects to impose a specific +ordering; the @var{priority} for the @code{init_priority} attribute +has the same effect as the @var{priority} for the @code{constructor} +attribute. + +Using the argument form of the @code{constructor} and +@code{destructor} attributes on targets where the feature is not +supported is rejected with an error. Only a few targets (typically +those not using ELF object format, or the GNU linker) reject this +usage. @cindex @code{copy} function attribute @item copy @@ -2219,18 +2242,43 @@ for consistency with the @code{printf} style format string argument @code{my_format}. The parameter @var{archetype} determines how the format string is -interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}, +interpreted. +Valid archetypes include @code{printf}, @code{scanf}, @code{strftime}, @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or @code{strfmon}. (You can also use @code{__printf__}, -@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On -MinGW targets, @code{ms_printf}, @code{ms_scanf}, and -@code{ms_strftime} are also present. +@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) @var{archetype} values such as @code{printf} refer to the formats accepted by the system's C runtime library, while values prefixed with @samp{gnu_} always refer -to the formats accepted by the GNU C Library. On Microsoft Windows -targets, values prefixed with @samp{ms_} refer to the formats accepted by the +to the formats accepted by the GNU C Library. + +@anchor{Target Format Checks} +On MinGW and Microsoft Windows targets, @code{ms_printf}, +@code{ms_scanf}, and @code{ms_strftime} are also present. Values +prefixed with @samp{ms_} refer to the formats accepted by the @file{msvcrt.dll} library. + +@anchor{Solaris Format Checks} +Solaris targets also support the @code{cmn_err} (or @code{__cmn_err__}) +archetype. +@code{cmn_err} accepts a subset of the standard @code{printf} +conversions, and the two-argument @code{%b} conversion for displaying +bit-fields. See the Solaris man page for @code{cmn_err} for more information. + +@anchor{Darwin Format Checks} +Darwin targets also support the @code{CFString} (or +@code{__CFString__}) archetype in the @code{format} attribute. +Declarations with this archetype are parsed for correct syntax +and argument types. However, parsing of the format string itself and +validating arguments against it in calls to such functions is currently +not performed. + +For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is +recognized in the same context. Declarations including these format attributes +are parsed for correct syntax, however the result of checking of such format +strings is not yet defined, and is not carried out by this version of the +compiler. + The parameter @var{string-index} specifies which argument is the format string argument (starting from 1), while @var{first-to-check} is the number of the first @@ -2265,15 +2313,7 @@ standard modes, the X/Open function @code{strfmon} is also checked as are @code{printf_unlocked} and @code{fprintf_unlocked}. @xref{C Dialect Options,,Options Controlling C Dialect}. -For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is -recognized in the same context. Declarations including these format attributes -are parsed for correct syntax, however the result of checking of such format -strings is not yet defined, and is not carried out by this version of the -compiler. -The target may also provide additional types of format checks. -@xref{Target Format Checks,,Format Checks Specific to Particular -Target Machines}. @cindex @code{format_arg} function attribute @opindex Wformat-nonliteral @@ -2328,13 +2368,17 @@ requested by @option{-ansi} or an appropriate @option{-std} option, or is used. @xref{C Dialect Options,,Options Controlling C Dialect}. -For Objective-C dialects, the @code{format-arg} attribute may refer to an +For Objective-C dialects, the @code{format_arg} attribute may refer to an @code{NSString} reference for compatibility with the @code{format} attribute above. -The target may also allow additional types in @code{format-arg} attributes. -@xref{Target Format Checks,,Format Checks Specific to Particular -Target Machines}. +Similarly, on Darwin targets @code{CFStringRefs} (defined by the +@code{CoreFoundation} headers) may also be used as format arguments. +Note that the relevant headers are only likely to be available on +Darwin (OSX) installations. On such installations, the XCode and +system documentation provide descriptions of @code{CFString}, +@code{CFStringRefs} and associated functions. + @cindex @code{gnu_inline} function attribute @item gnu_inline @@ -3740,7 +3784,7 @@ The default for the attribute is controlled by @option{-fzero-call-used-regs}. @c This is the end of the target-independent attribute table @node AArch64 Function Attributes -@subsection AArch64 Function Attributes +@subsubsection AArch64 Function Attributes The following target-specific function attributes are available for the AArch64 target. For the most part, these options mirror the behavior of @@ -3887,7 +3931,7 @@ foo (int a) is valid and compiles function @code{foo} for ARMv8-A with @code{crc} and @code{crypto} extensions and tunes it for @code{cortex-a53}. -@subsubsection Inlining rules +@subsubheading Inlining rules Specifying target attributes on individual functions or performing link-time optimization across translation units compiled with different target options can affect function inlining rules: @@ -3913,7 +3957,7 @@ Note that CPU tuning options and attributes such as the @option{-mcpu=}, architectural feature rules specified above. @node AMD GCN Function Attributes -@subsection AMD GCN Function Attributes +@subsubsection AMD GCN Function Attributes These function attributes are supported by the AMD GCN back end: @@ -4003,7 +4047,7 @@ OpenACC/OpenMP). @end table @node ARC Function Attributes -@subsection ARC Function Attributes +@subsubsection ARC Function Attributes These function attributes are supported by the ARC back end: @@ -4081,7 +4125,7 @@ are not supported. @end table @node ARM Function Attributes -@subsection ARM Function Attributes +@subsubsection ARM Function Attributes These function attributes are supported for ARM targets: @@ -4233,7 +4277,7 @@ without modifying an existing @option{-march=} or @option{-mcpu} option. @end table @node AVR Function Attributes -@subsection AVR Function Attributes +@subsubsection AVR Function Attributes These function attributes are supported by the AVR back end: @@ -4405,7 +4449,7 @@ as needed. @end table @node Blackfin Function Attributes -@subsection Blackfin Function Attributes +@subsubsection Blackfin Function Attributes These function attributes are supported by the Blackfin back end: @@ -4483,7 +4527,7 @@ regardless of whether they are used or not. @end table @node BPF Function Attributes -@subsection BPF Function Attributes +@subsubsection BPF Function Attributes These function attributes are supported by the BPF back end: @@ -4512,7 +4556,7 @@ are not supported. @end table @node C-SKY Function Attributes -@subsection C-SKY Function Attributes +@subsubsection C-SKY Function Attributes These function attributes are supported by the C-SKY back end: @@ -4544,7 +4588,7 @@ depended upon to work reliably and are not supported. @node Epiphany Function Attributes -@subsection Epiphany Function Attributes +@subsubsection Epiphany Function Attributes These function attributes are supported by the Epiphany back end: @@ -4617,7 +4661,7 @@ command-line switch and @code{#pragma long_calls} settings. @node H8/300 Function Attributes -@subsection H8/300 Function Attributes +@subsubsection H8/300 Function Attributes These function attributes are available for H8/300 targets: @@ -4647,7 +4691,7 @@ regardless of whether they are used or not. @end table @node IA-64 Function Attributes -@subsection IA-64 Function Attributes +@subsubsection IA-64 Function Attributes These function attributes are supported on IA-64 targets: @@ -4676,7 +4720,7 @@ Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}. @end table @node LoongArch Function Attributes -@subsection LoongArch Function Attributes +@subsubsection LoongArch Function Attributes These function attributes are supported by the LoongArch end: @@ -4750,7 +4794,7 @@ $ gcc test.c -o test.s -O2 -mlasx -mno-lasx @end table @node M32C Function Attributes -@subsection M32C Function Attributes +@subsubsection M32C Function Attributes These function attributes are supported by the M32C back end: @@ -4813,7 +4857,7 @@ when this attribute is present. @end table @node M32R/D Function Attributes -@subsection M32R/D Function Attributes +@subsubsection M32R/D Function Attributes These function attributes are supported by the M32R/D back end: @@ -4849,7 +4893,7 @@ generates the much slower @code{seth/add3/jl} instruction sequence). @end table @node m68k Function Attributes -@subsection m68k Function Attributes +@subsubsection m68k Function Attributes These function attributes are supported by the m68k back end: @@ -4873,7 +4917,7 @@ instruction. This attribute is available only on fido. @end table @node MCORE Function Attributes -@subsection MCORE Function Attributes +@subsubsection MCORE Function Attributes These function attributes are supported by the MCORE back end: @@ -4891,7 +4935,7 @@ depended upon to work reliably and are not supported. @end table @node MicroBlaze Function Attributes -@subsection MicroBlaze Function Attributes +@subsubsection MicroBlaze Function Attributes These function attributes are supported on MicroBlaze targets: @@ -4930,7 +4974,7 @@ using @code{rtid} instead of @code{rtsd}. @end table @node Microsoft Windows Function Attributes -@subsection Microsoft Windows Function Attributes +@subsubsection Microsoft Windows Function Attributes The following attributes are available on Microsoft Windows and Symbian OS targets. @@ -5028,7 +5072,7 @@ for functions by setting the @option{-mnop-fun-dllimport} flag. @end table @node MIPS Function Attributes -@subsection MIPS Function Attributes +@subsubsection MIPS Function Attributes These function attributes are supported by the MIPS back end: @@ -5178,7 +5222,7 @@ If there is no argument supplied, the default of @code{"yes"} applies. @end table @node MSP430 Function Attributes -@subsection MSP430 Function Attributes +@subsubsection MSP430 Function Attributes These function attributes are supported by the MSP430 back end: @@ -5269,7 +5313,7 @@ easier to pack regions. @end table @node NDS32 Function Attributes -@subsection NDS32 Function Attributes +@subsubsection NDS32 Function Attributes These function attributes are supported by the NDS32 back end: @@ -5338,7 +5382,7 @@ Provide a user-defined function to handle warm reset exception. @end table @node Nvidia PTX Function Attributes -@subsection Nvidia PTX Function Attributes +@subsubsection Nvidia PTX Function Attributes These function attributes are supported by the Nvidia PTX back end: @@ -5354,7 +5398,7 @@ Kernel functions must have @code{void} return type. @end table @node PowerPC Function Attributes -@subsection PowerPC Function Attributes +@subsubsection PowerPC Function Attributes These function attributes are supported by the PowerPC back end: @@ -5551,7 +5595,7 @@ callee has a subset of the target options of the caller. @end table @node RISC-V Function Attributes -@subsection RISC-V Function Attributes +@subsubsection RISC-V Function Attributes These function attributes are supported by the RISC-V back end: @@ -5654,7 +5698,7 @@ is valid and compiles function @code{foo} with @code{zba} and @code{zbb} extensions and tunes it for @code{rocket}. @node RL78 Function Attributes -@subsection RL78 Function Attributes +@subsubsection RL78 Function Attributes These function attributes are supported by the RL78 back end: @@ -5685,7 +5729,7 @@ depended upon to work reliably and are not supported. @end table @node RX Function Attributes -@subsection RX Function Attributes +@subsubsection RX Function Attributes These function attributes are supported by the RX back end: @@ -5746,7 +5790,7 @@ function (i.e.@: it retains the normal C function calling ABI). See the @end table @node S/390 Function Attributes -@subsection S/390 Function Attributes +@subsubsection S/390 Function Attributes These function attributes are supported on the S/390: @@ -5811,7 +5855,7 @@ does not undefine the @code{__VEC__} macro. @end table @node SH Function Attributes -@subsection SH Function Attributes +@subsubsection SH Function Attributes These function attributes are supported on the SH family of processors: @@ -5893,13 +5937,13 @@ but it does not save and restore all registers. @end table @node Symbian OS Function Attributes -@subsection Symbian OS Function Attributes +@subsubsection Symbian OS Function Attributes @xref{Microsoft Windows Function Attributes}, for discussion of the @code{dllexport} and @code{dllimport} attributes. @node V850 Function Attributes -@subsection V850 Function Attributes +@subsubsection V850 Function Attributes The V850 back end supports these function attributes: @@ -5915,7 +5959,7 @@ when either attribute is present. @end table @node Visium Function Attributes -@subsection Visium Function Attributes +@subsubsection Visium Function Attributes These function attributes are supported by the Visium back end: @@ -5929,7 +5973,7 @@ when this attribute is present. @end table @node x86 Function Attributes -@subsection x86 Function Attributes +@subsubsection x86 Function Attributes These function attributes are supported by the x86 back end: @@ -6879,7 +6923,7 @@ counterpart to option @option{-mno-direct-extern-access}. @end table -@subsubsection Inlining rules +@subsubheading Inlining rules On the x86, the inliner does not inline a function that has different target options than the caller, unless the callee has a subset of the target options of the caller. For example @@ -6894,7 +6938,7 @@ a function with default @option{-march=x86-64} and of ISA features and marked with always_inline. @node Xstormy16 Function Attributes -@subsection Xstormy16 Function Attributes +@subsubsection Xstormy16 Function Attributes These function attributes are supported by the Xstormy16 back end: @@ -6908,7 +6952,7 @@ when this attribute is present. @end table @node Variable Attributes -@section Specifying Attributes of Variables +@subsection Specifying Attributes of Variables @cindex attribute of variables @cindex variable attributes @@ -6950,7 +6994,7 @@ which syntax you use. @xref{Attribute Syntax}, for details. @end menu @node Common Variable Attributes -@subsection Common Variable Attributes +@subsubsection Common Variable Attributes The following attributes are supported on most targets. @@ -7600,7 +7644,7 @@ The @code{weak} attribute is described in @end table @node ARC Variable Attributes -@subsection ARC Variable Attributes +@subsubsection ARC Variable Attributes @table @code @cindex @code{aux} variable attribute, ARC @@ -7612,7 +7656,7 @@ given via attribute argument. @end table @node AVR Variable Attributes -@subsection AVR Variable Attributes +@subsubsection AVR Variable Attributes @table @code @cindex @code{progmem} variable attribute, AVR @@ -7777,7 +7821,7 @@ See also the @option{-mabsdata} @ref{AVR Options,command-line option}. @end table @node Blackfin Variable Attributes -@subsection Blackfin Variable Attributes +@subsubsection Blackfin Variable Attributes Three attributes are currently defined for the Blackfin. @@ -7802,7 +7846,7 @@ named @code{.l2.data}. @end table @node H8/300 Variable Attributes -@subsection H8/300 Variable Attributes +@subsubsection H8/300 Variable Attributes These variable attributes are available for H8/300 targets: @@ -7831,7 +7875,7 @@ slightly under 32KB of data. @end table @node IA-64 Variable Attributes -@subsection IA-64 Variable Attributes +@subsubsection IA-64 Variable Attributes The IA-64 back end supports the following variable attribute: @@ -7850,7 +7894,7 @@ defined by shared libraries. @end table @node LoongArch Variable Attributes -@subsection LoongArch Variable Attributes +@subsubsection LoongArch Variable Attributes One attribute is currently defined for the LoongArch. @@ -7866,7 +7910,7 @@ specially. Currently the only supported values of @var{name} are @end table @node M32R/D Variable Attributes -@subsection M32R/D Variable Attributes +@subsubsection M32R/D Variable Attributes One attribute is currently defined for the M32R/D@. @@ -7887,7 +7931,7 @@ addresses). @end table @node Microsoft Windows Variable Attributes -@subsection Microsoft Windows Variable Attributes +@subsubsection Microsoft Windows Variable Attributes You can use these attributes on Microsoft Windows targets. @ref{x86 Variable Attributes} for additional Windows compatibility @@ -7952,7 +7996,7 @@ The @code{shared} attribute is only available on Microsoft Windows@. @end table @node MSP430 Variable Attributes -@subsection MSP430 Variable Attributes +@subsubsection MSP430 Variable Attributes @table @code @cindex @code{upper} variable attribute, MSP430 @@ -7982,7 +8026,7 @@ will be used, and the @code{.lower} prefix will not be added. @end table @node Nvidia PTX Variable Attributes -@subsection Nvidia PTX Variable Attributes +@subsubsection Nvidia PTX Variable Attributes These variable attributes are supported by the Nvidia PTX back end: @@ -7996,7 +8040,7 @@ The runtime does not initialize variables in this memory space. @end table @node PowerPC Variable Attributes -@subsection PowerPC Variable Attributes +@subsubsection PowerPC Variable Attributes Three attributes currently are defined for PowerPC configurations: @code{altivec}, @code{ms_struct} and @code{gcc_struct}. @@ -8011,7 +8055,7 @@ For documentation of @code{altivec} attribute please see the documentation in @ref{PowerPC Type Attributes}. @node RL78 Variable Attributes -@subsection RL78 Variable Attributes +@subsubsection RL78 Variable Attributes @cindex @code{saddr} variable attribute, RL78 The RL78 back end supports the @code{saddr} variable attribute. This @@ -8019,7 +8063,7 @@ specifies placement of the corresponding variable in the SADDR area, which can be accessed more efficiently than the default memory region. @node V850 Variable Attributes -@subsection V850 Variable Attributes +@subsubsection V850 Variable Attributes These variable attributes are supported by the V850 back end: @@ -8042,7 +8086,7 @@ of memory. @end table @node x86 Variable Attributes -@subsection x86 Variable Attributes +@subsubsection x86 Variable Attributes Two attributes are currently defined for x86 configurations: @code{ms_struct} and @code{gcc_struct}. @@ -8070,7 +8114,7 @@ attributes on types. @end table @node Xstormy16 Variable Attributes -@subsection Xstormy16 Variable Attributes +@subsubsection Xstormy16 Variable Attributes One attribute is currently defined for xstormy16 configurations: @code{below100}. @@ -8088,7 +8132,7 @@ placed in either the @code{.bss_below100} section or the @end table @node Type Attributes -@section Specifying Attributes of Types +@subsection Specifying Attributes of Types @cindex attribute of types @cindex type attributes @@ -8130,7 +8174,7 @@ the closing brace. You can also include type attributes in a @end menu @node Common Type Attributes -@subsection Common Type Attributes +@subsubsection Common Type Attributes The following type attributes are supported on most targets. @@ -8999,7 +9043,7 @@ double parentheses: for example, @samp{__attribute__ ((aligned (16), packed))}. @node ARC Type Attributes -@subsection ARC Type Attributes +@subsubsection ARC Type Attributes @cindex @code{uncached} type attribute, ARC Declaring objects with @code{uncached} allows you to exclude @@ -9009,7 +9053,7 @@ without involving the additional semantic implications of loads and stores of data declared @code{uncached}. @node ARM Type Attributes -@subsection ARM Type Attributes +@subsubsection ARM Type Attributes @cindex @code{notshared} type attribute, ARM On those ARM targets that support @code{dllimport} (such as Symbian @@ -9035,7 +9079,7 @@ virtual table for @code{C} is not exported. (You can use most Symbian OS code uses @code{__declspec}.) @node BPF Type Attributes -@subsection BPF Type Attributes +@subsubsection BPF Type Attributes @cindex @code{preserve_access_index} type attribute, BPF BPF Compile Once - Run Everywhere (CO-RE) support. When attached to a @@ -9046,7 +9090,7 @@ wrapping every such access with @code{__builtin_preserve_access_index}. @node PowerPC Type Attributes -@subsection PowerPC Type Attributes +@subsubsection PowerPC Type Attributes Three attributes currently are defined for PowerPC configurations: @code{altivec}, @code{ms_struct} and @code{gcc_struct}. @@ -9073,7 +9117,7 @@ These attributes mainly are intended to support the @code{__vector}, @code{__pixel}, and @code{__bool} AltiVec keywords. @node x86 Type Attributes -@subsection x86 Type Attributes +@subsubsection x86 Type Attributes Two attributes are currently defined for x86 configurations: @code{ms_struct} and @code{gcc_struct}. @@ -9102,7 +9146,7 @@ attributes on variables. @end table @node Label Attributes -@section Label Attributes +@subsection Label Attributes @cindex Label Attributes GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for @@ -9158,7 +9202,7 @@ with computed goto or @code{asm goto}. @end table @node Enumerator Attributes -@section Enumerator Attributes +@subsection Enumerator Attributes @cindex Enumerator Attributes GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for @@ -9203,7 +9247,7 @@ same manner as the @code{deprecated} attribute. @end table @node Statement Attributes -@section Statement Attributes +@subsection Statement Attributes @cindex Statement Attributes GCC allows attributes to be set on statements. @xref{Attribute Syntax}, @@ -9270,7 +9314,7 @@ The @code{gnu::musttail} or @code{clang::musttail} standard attribute or @code{musttail} GNU attribute can be applied to a @code{return} statement with a return-value expression that is a function call. It asserts that the call must be a tail call that does not allocate extra stack space, so it is -safe to use tail recursion to implement long running loops. +safe to use tail recursion to implement long-running loops. @smallexample [[gnu::musttail]] return foo(); @@ -9280,16 +9324,82 @@ safe to use tail recursion to implement long running loops. __attribute__((musttail)) return bar(); @end smallexample -If the compiler cannot generate a @code{musttail} tail call it will report -an error. On some targets tail calls may never be supported. -Tail calls cannot reference locals in memory, which may affect -builds without optimization when passing small structures, or passing -or returning large structures. Enabling @option{-O1} or @option{-O2} can -improve the success of tail calls. +If the compiler cannot generate a @code{musttail} tail call it reports +an error. On some targets, tail calls may not be supported at all. +The @code{musttail} attribute asserts that the lifetime of automatic +variables, function parameters and temporaries (unless they have non-trivial +destruction) can end before the actual call instruction, and that any access +to those from inside of the called function results is considered undefined +behavior. Enabling @option{-O1} or @option{-O2} can improve the success of +tail calls. + +@smallexample +int foo (int *); +void bar (int *); +struct S @{ S (); ~S (); int s; @}; + +int +baz (int *x) +@{ + if (*x == 1) + @{ + int a = 42; + /* The call is a tail call (would not be without the + attribute). Dereferencing the pointer in the callee is + undefined behavior, and there is a warning emitted + for this by default (@option{-Wmusttail-local-addr}). */ + [[gnu::musttail]] return foo (&a); + @} + else if (*x == 2) + @{ + int a = 42; + bar (&a); + /* The call is a tail call (would not be without the + attribute). If bar stores the pointer anywhere, dereferencing + it in foo is undefined behavior. There is a warning + emitted for this with @option{-Wextra}, which implies + @option{-Wmaybe-musttail-local-addr}. */ + [[gnu::musttail]] return foo (nullptr); + @} + else + @{ + S s; + /* The s variable requires non-trivial destruction which ought + to be performed after the foo call returns, so this is + rejected. */ + [[gnu::musttail]] return foo (&s.s); + @} +@} +@end smallexample + +To avoid the @option{-Wmaybe-musttail-local-addr} warning in the +above @code{*x == 2} case and similar code, consider defining the +maybe-escaped variables in a separate scope that ends before the +return statement, if that is possible, to make it clear that the +variable is not live during the call. So: + +@smallexample + else if (*x == 2) + @{ + @{ + int a = 42; + bar (&a); + @} + /* The call is a tail call (would not be without the + attribute). If bar stores the pointer anywhere, dereferencing + it in foo is undefined behavior even without tail call + optimization, and there is no warning. */ + [[gnu::musttail]] return foo (nullptr); + @} +@end smallexample + +It is not possible to avoid the warning in this way if the maybe-escaped +variable is a function argument, because those are in scope +for the whole function. @end table @node Attribute Syntax -@section Attribute Syntax +@subsection Attribute Syntax @cindex attribute syntax @cindex C standard attributes @cindex C++ standard attributes @@ -9865,50 +9975,79 @@ always the C-language name. @node Structure-Layout Pragmas @subsection Structure-Layout Pragmas -For compatibility with Microsoft Windows compilers, GCC supports a -set of @code{#pragma} directives that change the maximum alignment of +@cindex pragma, pack +@cindex pack pragma +For compatibility with Microsoft Windows compilers, GCC supports a set +of @code{#pragma pack} directives that change the maximum alignment of members of structures (other than zero-width bit-fields), unions, and -classes subsequently defined. The @var{n} value below always is required -to be a small power of two and specifies the new alignment in bytes. +classes subsequently defined. The @var{n} value below specifies the +new alignment in bytes and may have the value 1, 2, 4, 8, and 16. A +value of 0 is also permitted and indicates the default alignment (as if +no @code{#pragma pack} were in effect) should be used. -@enumerate -@item @code{#pragma pack(@var{n})} simply sets the new alignment. -@item @code{#pragma pack()} sets the alignment to the one that was in +@table @code +@item #pragma pack(@var{n}) +Sets the new alignment according to @var{n}. + +@item #pragma pack() +Sets the alignment to the one that was in effect when compilation started (see also command-line option -@option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). -@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment +@option{-fpack-struct[=@var{n}]}. @xref{Code Gen Options}). + +@item #pragma pack(push[,@var{n}]) +Pushes the current alignment setting on an internal stack and then optionally sets the new alignment. -@item @code{#pragma pack(pop)} restores the alignment setting to the one + +@item #pragma pack(pop) +Restores the alignment setting to the one saved at the top of the internal stack (and removes that stack entry). Note that @code{#pragma pack([@var{n}])} does not influence this internal stack; thus it is possible to have @code{#pragma pack(push)} followed by -multiple @code{#pragma pack(@var{n})} instances and finalized by a single -@code{#pragma pack(pop)}. -@end enumerate +multiple @code{#pragma pack(@var{n})} instances, with the original state +restored by a single @code{#pragma pack(pop)}. + +@end table + +You can also use the @code{packed} type attribute (@pxref{Common Type +Attributes}) to pack a structure. However, the @code{packed} +attribute interferes with @code{#pragma pack}, and attempting to use +them together may cause spurious warnings or unexpected behavior. +@c FIXME: This is PR 60972. +@cindex pragma, ms_struct +@cindex ms_struct pragma +@cindex Microsoft struct layout Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct} -directive which lays out structures and unions subsequently defined as the -documented @code{__attribute__ ((ms_struct))}. +directive, which causes subsequent structure and union declarations to +be laid out in the same way as +@code{__attribute__ ((ms_struct))}; @pxref{x86 Variable Attributes}. -@enumerate -@item @code{#pragma ms_struct on} turns on the Microsoft layout. -@item @code{#pragma ms_struct off} turns off the Microsoft layout. -@item @code{#pragma ms_struct reset} goes back to the default layout. -@end enumerate +@table @code +@item #pragma ms_struct on +Turns on the Microsoft layout. +@item #pragma ms_struct off +Turns off the Microsoft layout. +@item #pragma ms_struct reset +Goes back to the default layout. +@end table +@cindex pragma, scalar_storage_order Most targets also support the @code{#pragma scalar_storage_order} directive -which lays out structures and unions subsequently defined as the documented -@code{__attribute__ ((scalar_storage_order))}. +which lays out subsequent structure and union declarations in +in the same way as the documented +@code{__attribute__ ((scalar_storage_order))}; @pxref{Common Type Attributes}. -@enumerate -@item @code{#pragma scalar_storage_order big-endian} sets the storage order -of the scalar fields to big-endian. -@item @code{#pragma scalar_storage_order little-endian} sets the storage order -of the scalar fields to little-endian. -@item @code{#pragma scalar_storage_order default} goes back to the endianness +@table @code +@item #pragma scalar_storage_order big-endian +@itemx #pragma scalar_storage_order little-endian +Set the storage order of scalar fields to big- or little-endian, +respectively. + +@item #pragma scalar_storage_order default +Goes back to the endianness that was in effect when compilation started (see also command-line option @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}). -@end enumerate +@end table @node Weak Pragmas @subsection Weak Pragmas @@ -12910,7 +13049,8 @@ C and/or C++ standards, while others remain specific to GNU C. * Typeof:: @code{typeof}: referring to the type of an expression. * Offsetof:: Special syntax for @code{offsetof}. * Alignment:: Determining the alignment of a function, type or variable. -* Incomplete Enums:: @code{enum foo;}, with details to follow. +* Enum Extensions:: Forward declarations and specifying the underlying type. +* Boolean Type:: Support for the @code{_Bool} keyword. * Variadic Macros:: Macros with a variable number of arguments. * Conditionals:: Omitting the middle operand of a @samp{?:} expression. * Case Ranges:: `case 1 ... 9' and such. @@ -13610,22 +13750,77 @@ If the operand of the @code{__alignof__} expression is a function, the expression evaluates to the alignment of the function which may be specified by attribute @code{aligned} (@pxref{Common Function Attributes}). -@node Incomplete Enums -@subsection Incomplete @code{enum} Types +@node Enum Extensions +@subsection Extensions to @code{enum} Type Declarations +@anchor{Incomplete Enums} +@cindex @code{enum} extensions +@cindex base type of an @code{enum} +@cindex underlying type of an @code{enum} +@cindex forward declaration of an @code{enum} +@cindex opaque @code{enum} types +@cindex incomplete @code{enum} types + +The C23 and C++11 standards added new syntax to specify the underlying +type of an @code{enum} type. For example, + +@smallexample +enum pet : unsigned char @{ CAT, DOG, ROCK @}; +@end smallexample + +In GCC, this feature is supported as an extension in all older +dialects of C and C++ as well. For C++ dialects before C++11, use +@option{-Wno-c++11-extensions} to silence the associated warnings. + +You can also forward-declare an @code{enum} type, without specifying +its possible values. The enumerators are supplied in a later +redeclaration of the type, which must match the underlying type of the +first declaration. + +@smallexample +enum pet : unsigned char; +static enum pet my_pet; +... +enum pet : unsigned char @{ CAT, DOG, ROCK @}; +@end smallexample + +Forward declaration of @code{enum} types with an explicit underlying +type is also a feature of C++11 that is supported as an extension by +GCC for all C dialects. However, it's not available in C++ dialects +prior to C++11. -You can define an @code{enum} tag without specifying its possible values. -This results in an incomplete type, much like what you get if you write -@code{struct foo} without describing the elements. A later declaration -that does specify the possible values completes the type. +The C++ standard refers to a forward declaration of an @code{enum} +with an explicit underlying type as an @dfn{opaque type}. It is not +considered an incomplete type, since its size is known. That means +you can declare variables or allocate storage using the type before +the redeclaration, not just use pointers of that type. +GCC has also traditionally supported forward declarations of +@code{enum} types that don't include an explicit underlying type +specification. This results in an incomplete type, much like what you +get if you write @code{struct foo} without describing the elements. You cannot allocate variables or storage using the type while it is incomplete. However, you can work with pointers to that type. -This extension may not be very useful, but it makes the handling of -@code{enum} more consistent with the way @code{struct} and @code{union} -are handled. +Forward-declaring an incomplete enum type without an explicit +underlying type is supported as an extension in all GNU C dialects, +but is not supported at all in GNU C++. -This extension is not supported by GNU C++. +@node Boolean Type +@subsection Support for the @code{_Bool} Type +@cindex boolean type +@cindex @code{_Bool} keyword + +The C99 standard added @code{_Bool} as a C language keyword naming the +boolean type. As an extension, GNU C also recognizes @code{_Bool} in +C90 mode as well as with @option{-std=c99} and later. + +C23 added @code{bool} as the preferred name of the boolean type, but +@code{_Bool} also remains a standard keyword in the language and is +supported as such by GCC with @option{-std=c23}. + +GNU C++ does not support @code{_Bool} as a keyword, but including +@code{<stdbool.h>} defines it as a macro in terms of standard C++'s +@code{bool} type. @node Variadic Macros @subsection Macros with a Variable Number of Arguments. @@ -14169,6 +14364,1502 @@ extension explicit. Additionally, using @code{const} and @code{volatile} in this way is specific to GNU C and does not work in GNU C++. +@node Built-in Functions +@chapter Built-in Functions Provided by GCC +@cindex Built-in Functions + +GCC provides a very large number of implicitly-declared built-in +functions that are typically inlined by the compiler. Some of these +builtins directly correspond to standard library routines. Some are +for internal use in the processing of exceptions or variable-length +argument lists and are not documented here because they may change +from time to time; we do not recommend general use of these functions. + +The remaining functions are provided either for optimization purposes, or +to expose low-level functionality needed to implement +features provided by library functions or similar ``glue'' between GCC +and other programming languages or libraries. Others are +target-specific, providing direct access to instructions that have no +direct C equivalents without the need to write assembly language. There +are also builtins to support various kinds of runtime error checking. + +Most builtins have names prefixed with @samp{__builtin_}, although not +all of them use this convention. Except as otherwise documented, all +built-in functions are available from any of the C family languages +supported by GCC. + +With the exception of built-ins that have library equivalents such as +the standard C library functions discussed below in @ref{Library Builtins}, +or that expand to +library calls, GCC built-in functions are always expanded inline and +thus do not have corresponding entry points and their address cannot +be obtained. Attempting to use them in an expression other than +a function call results in a compile-time error. + +@menu +* Library Builtins:: Built-in equivalents for C library functions. +* Numeric Builtins:: Additional builtins for numeric and bit operations. +* Stack Allocation:: Built-in alloca variants. +* Nonlocal Gotos:: Built-ins for nonlocal gotos. +* Constructing Calls:: Built-ins for dispatching a call to another function. +* Return Address:: Getting the return or frame address of a function. +* Stack Scrubbing:: Stack scrubbing internal interfaces. +* Vector Extensions:: Using vector instructions through built-in functions. +* Atomic Memory Access:: __atomic and __sync builtins. +* Object Size Checking:: Built-in functions for limited buffer overflow + checking. +* New/Delete Builtins:: Built-in functions for C++ allocations and deallocations. +* Other Builtins:: Other built-in functions. +* Target Builtins:: Built-in functions specific to particular targets. +@end menu + +@node Library Builtins +@section Builtins for C Library Functions +@cindex built-in library functions +@cindex library function builtins +@cindex C library function builtins + +@findex __builtin_iseqsig +@findex __builtin_isfinite +@findex __builtin_isnormal +@findex __builtin_isgreater +@findex __builtin_isgreaterequal +@findex __builtin_isunordered +@findex __builtin_speculation_safe_value +@findex _Exit +@findex _exit +@findex abort +@findex abs +@findex acos +@findex acosf +@findex acosh +@findex acoshf +@findex acoshl +@findex acosl +@findex alloca +@findex asin +@findex asinf +@findex asinh +@findex asinhf +@findex asinhl +@findex asinl +@findex atan +@findex atan2 +@findex atan2f +@findex atan2l +@findex atanf +@findex atanh +@findex atanhf +@findex atanhl +@findex atanl +@findex bcmp +@findex bzero +@findex cabs +@findex cabsf +@findex cabsl +@findex cacos +@findex cacosf +@findex cacosh +@findex cacoshf +@findex cacoshl +@findex cacosl +@findex calloc +@findex carg +@findex cargf +@findex cargl +@findex casin +@findex casinf +@findex casinh +@findex casinhf +@findex casinhl +@findex casinl +@findex catan +@findex catanf +@findex catanh +@findex catanhf +@findex catanhl +@findex catanl +@findex cbrt +@findex cbrtf +@findex cbrtl +@findex ccos +@findex ccosf +@findex ccosh +@findex ccoshf +@findex ccoshl +@findex ccosl +@findex ceil +@findex ceilf +@findex ceill +@findex cexp +@findex cexpf +@findex cexpl +@findex cimag +@findex cimagf +@findex cimagl +@findex clog +@findex clogf +@findex clogl +@findex clog10 +@findex clog10f +@findex clog10l +@findex conj +@findex conjf +@findex conjl +@findex copysign +@findex copysignf +@findex copysignl +@findex cos +@findex cosf +@findex cosh +@findex coshf +@findex coshl +@findex cosl +@findex cpow +@findex cpowf +@findex cpowl +@findex cproj +@findex cprojf +@findex cprojl +@findex creal +@findex crealf +@findex creall +@findex csin +@findex csinf +@findex csinh +@findex csinhf +@findex csinhl +@findex csinl +@findex csqrt +@findex csqrtf +@findex csqrtl +@findex ctan +@findex ctanf +@findex ctanh +@findex ctanhf +@findex ctanhl +@findex ctanl +@findex dcgettext +@findex dgettext +@findex drem +@findex dremf +@findex dreml +@findex erf +@findex erfc +@findex erfcf +@findex erfcl +@findex erff +@findex erfl +@findex exit +@findex exp +@findex exp10 +@findex exp10f +@findex exp10l +@findex exp2 +@findex exp2f +@findex exp2l +@findex expf +@findex expl +@findex expm1 +@findex expm1f +@findex expm1l +@findex fabs +@findex fabsf +@findex fabsl +@findex fdim +@findex fdimf +@findex fdiml +@findex ffs +@findex floor +@findex floorf +@findex floorl +@findex fma +@findex fmaf +@findex fmal +@findex fmax +@findex fmaxf +@findex fmaxl +@findex fmin +@findex fminf +@findex fminl +@findex fmod +@findex fmodf +@findex fmodl +@findex fprintf +@findex fprintf_unlocked +@findex fputs +@findex fputs_unlocked +@findex free +@findex frexp +@findex frexpf +@findex frexpl +@findex fscanf +@findex gamma +@findex gammaf +@findex gammal +@findex gamma_r +@findex gammaf_r +@findex gammal_r +@findex gettext +@findex hypot +@findex hypotf +@findex hypotl +@findex ilogb +@findex ilogbf +@findex ilogbl +@findex imaxabs +@findex index +@findex isalnum +@findex isalpha +@findex isascii +@findex isblank +@findex iscntrl +@findex isdigit +@findex isgraph +@findex islower +@findex isprint +@findex ispunct +@findex isspace +@findex isupper +@findex iswalnum +@findex iswalpha +@findex iswblank +@findex iswcntrl +@findex iswdigit +@findex iswgraph +@findex iswlower +@findex iswprint +@findex iswpunct +@findex iswspace +@findex iswupper +@findex iswxdigit +@findex isxdigit +@findex j0 +@findex j0f +@findex j0l +@findex j1 +@findex j1f +@findex j1l +@findex jn +@findex jnf +@findex jnl +@findex labs +@findex ldexp +@findex ldexpf +@findex ldexpl +@findex lgamma +@findex lgammaf +@findex lgammal +@findex lgamma_r +@findex lgammaf_r +@findex lgammal_r +@findex llabs +@findex llrint +@findex llrintf +@findex llrintl +@findex llround +@findex llroundf +@findex llroundl +@findex log +@findex log10 +@findex log10f +@findex log10l +@findex log1p +@findex log1pf +@findex log1pl +@findex log2 +@findex log2f +@findex log2l +@findex logb +@findex logbf +@findex logbl +@findex logf +@findex logl +@findex lrint +@findex lrintf +@findex lrintl +@findex lround +@findex lroundf +@findex lroundl +@findex malloc +@findex memchr +@findex memcmp +@findex memcpy +@findex mempcpy +@findex memset +@findex modf +@findex modff +@findex modfl +@findex nearbyint +@findex nearbyintf +@findex nearbyintl +@findex nextafter +@findex nextafterf +@findex nextafterl +@findex nexttoward +@findex nexttowardf +@findex nexttowardl +@findex pow +@findex pow10 +@findex pow10f +@findex pow10l +@findex powf +@findex powl +@findex printf +@findex printf_unlocked +@findex putchar +@findex puts +@findex realloc +@findex remainder +@findex remainderf +@findex remainderl +@findex remquo +@findex remquof +@findex remquol +@findex rindex +@findex rint +@findex rintf +@findex rintl +@findex round +@findex roundf +@findex roundl +@findex scalb +@findex scalbf +@findex scalbl +@findex scalbln +@findex scalblnf +@findex scalblnf +@findex scalbn +@findex scalbnf +@findex scanfnl +@findex signbit +@findex signbitf +@findex signbitl +@findex signbitd32 +@findex signbitd64 +@findex signbitd128 +@findex significand +@findex significandf +@findex significandl +@findex sin +@findex sincos +@findex sincosf +@findex sincosl +@findex sinf +@findex sinh +@findex sinhf +@findex sinhl +@findex sinl +@findex snprintf +@findex sprintf +@findex sqrt +@findex sqrtf +@findex sqrtl +@findex sscanf +@findex stpcpy +@findex stpncpy +@findex strcasecmp +@findex strcat +@findex strchr +@findex strcmp +@findex strcpy +@findex strcspn +@findex strdup +@findex strfmon +@findex strftime +@findex strlen +@findex strncasecmp +@findex strncat +@findex strncmp +@findex strncpy +@findex strndup +@findex strnlen +@findex strpbrk +@findex strrchr +@findex strspn +@findex strstr +@findex tan +@findex tanf +@findex tanh +@findex tanhf +@findex tanhl +@findex tanl +@findex tgamma +@findex tgammaf +@findex tgammal +@findex toascii +@findex tolower +@findex toupper +@findex towlower +@findex towupper +@findex trunc +@findex truncf +@findex truncl +@findex vfprintf +@findex vfscanf +@findex vprintf +@findex vscanf +@findex vsnprintf +@findex vsprintf +@findex vsscanf +@findex y0 +@findex y0f +@findex y0l +@findex y1 +@findex y1f +@findex y1l +@findex yn +@findex ynf +@findex ynl + +@opindex fno-builtin +GCC includes built-in versions of many of the functions in the standard +C library. These functions come in two forms: one whose names start with +the @code{__builtin_} prefix, and the other without. Both forms have the +same type (including prototype), the same address (when their address is +taken), and the same meaning as the C library functions even if you specify +the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these +functions are only optimized in certain cases; if they are not optimized in +a particular case, a call to the library function is emitted. + +@opindex ansi +@opindex std +Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, +@option{-std=c99} or @option{-std=c11}), the functions +@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, +@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, +@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, +@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, +@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, +@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, +@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, +@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, +@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, +@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, +@code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl}, +@code{scalbf}, @code{scalbl}, @code{scalb}, +@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, +@code{signbitd64}, @code{signbitd128}, @code{significandf}, +@code{significandl}, @code{significand}, @code{sincosf}, +@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, +@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, +@code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l}, +@code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and +@code{yn} +may be handled as built-in functions. +All these functions have corresponding versions +prefixed with @code{__builtin_}, which may be used even in strict C90 +mode. + +The ISO C99 functions +@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, +@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, +@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, +@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, +@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, +@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, +@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, +@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, +@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, +@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, +@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, +@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, +@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, +@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, +@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, +@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, +@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, +@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, +@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, +@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, +@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, +@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, +@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, +@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, +@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, +@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, +@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, +@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, +@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, +@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, +@code{nextafterf}, @code{nextafterl}, @code{nextafter}, +@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, +@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, +@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, +@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, +@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, +@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, +@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, +@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} +are handled as built-in functions +except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). + +There are also built-in versions of the ISO C99 functions +@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, +@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, +@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, +@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, +@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, +@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, +@code{modfl}, @code{modff}, @code{powf}, @code{powl}, @code{sinf}, +@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, +@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} +that are recognized in any mode since ISO C90 reserves these names for +the purpose to which ISO C99 puts them. All these functions have +corresponding versions prefixed with @code{__builtin_}. + +There are also built-in functions @code{__builtin_fabsf@var{n}}, +@code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and +@code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3 +functions @code{fabsf@var{n}}, @code{fabsf@var{n}x}, +@code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported +types @code{_Float@var{n}} and @code{_Float@var{n}x}. + +There are also GNU extension functions @code{clog10}, @code{clog10f} and +@code{clog10l} which names are reserved by ISO C99 for future use. +All these functions have versions prefixed with @code{__builtin_}. + +The ISO C94 functions +@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, +@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, +@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and +@code{towupper} +are handled as built-in functions +except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). + +The ISO C90 functions +@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, +@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, +@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, +@code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf}, +@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, +@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, +@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, +@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, +@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, +@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, +@code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin}, +@code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, +@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, +@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, +@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, +@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} +are all recognized as built-in functions unless +@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} +is specified for an individual function). All of these functions have +corresponding versions prefixed with @code{__builtin_}. + +GCC provides built-in versions of the ISO C99 floating-point comparison +macros that avoid raising exceptions for unordered operands. They have +the same names as the standard macros ( @code{isgreater}, +@code{isgreaterequal}, @code{isless}, @code{islessequal}, +@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} +prefixed. We intend for a library implementor to be able to simply +@code{#define} each standard macro to its built-in equivalent. +In the same fashion, GCC provides @code{fpclassify}, @code{iseqsig}, +@code{isfinite}, @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins +used with @code{__builtin_} prefixed. The @code{isinf} and @code{isnan} +built-in functions appear both with and without the @code{__builtin_} prefix. +With @code{-ffinite-math-only} option the @code{isinf} and @code{isnan} +built-in functions will always return 0. + +GCC provides built-in versions of the ISO C99 floating-point rounding and +exceptions handling functions @code{fegetround}, @code{feclearexcept} and +@code{feraiseexcept}. They may not be available for all targets, and because +they need close interaction with libc internal values, they may not be available +for all target libcs, but in all cases they will gracefully fallback to libc +calls. These built-in functions appear both with and without the +@code{__builtin_} prefix. + +@node Numeric Builtins +@section Additional Builtins for Numeric Operations +@cindex built-in numeric functions +@cindex numeric builtins + +GCC provides a large set of built-in functions for operating on GCC's +extended set of floating-point and integer types (@pxref{Additional +Numeric Types}). The floating-point builtins include functions for +building and testing infinities and NaNs. On integer types, there are +additional bit manipulation functions, byte-swapping, and CRC +functions. + +Many of these builtins are type-generic and can operate on any +floating-point or integer operand. + +@menu +* Floating-Point Format Builtins:: Huge values, infinities, and NaNs. +* Bit Operation Builtins:: Counting bits and similar functions. +* Byte-Swapping Builtins:: Reversing byte order. +* CRC Builtins:: Compute cyclic redundancy checks. +* Integer Overflow Builtins:: Built-in functions to perform arithmetics + and arithmetic overflow checking. +@end menu + +@node Floating-Point Format Builtins +@subsection Floating-Point Format Builtins +@cindex floating-point format builtins +@cindex NaN builtins +@cindex infinity builtins +@cindex huge value builtins + +@defbuiltin{double __builtin_huge_val (void)} +Returns a positive infinity, if supported by the floating-point format, +else @code{DBL_MAX}. This function is suitable for implementing the +ISO C macro @code{HUGE_VAL}. +@enddefbuiltin + +@defbuiltin{float __builtin_huge_valf (void)} +Similar to @code{__builtin_huge_val}, except the return type is @code{float}. +@enddefbuiltin + +@defbuiltin{{long double} __builtin_huge_vall (void)} +Similar to @code{__builtin_huge_val}, except the return +type is @code{long double}. +@enddefbuiltin + +@defbuiltin{_Float@var{n} __builtin_huge_valf@var{n} (void)} +Similar to @code{__builtin_huge_val}, except the return type is +@code{_Float@var{n}}. +@enddefbuiltin + +@defbuiltin{_Float@var{n}x __builtin_huge_valf@var{n}x (void)} +Similar to @code{__builtin_huge_val}, except the return type is +@code{_Float@var{n}x}. +@enddefbuiltin + +@defbuiltin{int __builtin_fpclassify (int, int, int, int, int, ...)} +This built-in implements the C99 fpclassify functionality. The first +five int arguments should be the target library's notion of the +possible FP classes and are used for return values. They must be +constant values and they must appear in this order: @code{FP_NAN}, +@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and +@code{FP_ZERO}. The ellipsis is for exactly one floating-point value +to classify. GCC treats the last argument as type-generic, which +means it does not do default promotion from float to double. +@enddefbuiltin + +@defbuiltin{double __builtin_inf (void)} +Similar to @code{__builtin_huge_val}, except a warning is generated +if the target floating-point format does not support infinities. +@enddefbuiltin + +@defbuiltin{_Decimal32 __builtin_infd32 (void)} +Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. +@enddefbuiltin + +@defbuiltin{_Decimal64 __builtin_infd64 (void)} +Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. +@enddefbuiltin + +@defbuiltin{_Decimal128 __builtin_infd128 (void)} +Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. +@enddefbuiltin + +@defbuiltin{float __builtin_inff (void)} +Similar to @code{__builtin_inf}, except the return type is @code{float}. +This function is suitable for implementing the ISO C99 macro @code{INFINITY}. +@enddefbuiltin + +@defbuiltin{{long double} __builtin_infl (void)} +Similar to @code{__builtin_inf}, except the return +type is @code{long double}. +@enddefbuiltin + +@defbuiltin{_Float@var{n} __builtin_inff@var{n} (void)} +Similar to @code{__builtin_inf}, except the return +type is @code{_Float@var{n}}. +@enddefbuiltin + +@defbuiltin{_Float@var{n} __builtin_inff@var{n}x (void)} +Similar to @code{__builtin_inf}, except the return +type is @code{_Float@var{n}x}. +@enddefbuiltin + +@defbuiltin{int __builtin_isinf_sign (...)} +Similar to @code{isinf}, except the return value is -1 for +an argument of @code{-Inf} and 1 for an argument of @code{+Inf}. +Note while the parameter list is an +ellipsis, this function only accepts exactly one floating-point +argument. GCC treats this parameter as type-generic, which means it +does not do default promotion from float to double. +@enddefbuiltin + +@defbuiltin{double __builtin_nan (const char *@var{str})} +This is an implementation of the ISO C99 function @code{nan}. + +Since ISO C99 defines this function in terms of @code{strtod}, which we +do not implement, a description of the parsing is in order. The string +is parsed as by @code{strtol}; that is, the base is recognized by +leading @samp{0} or @samp{0x} prefixes. The number parsed is placed +in the significand such that the least significant bit of the number +is at the least significant bit of the significand. The number is +truncated to fit the significand field provided. The significand is +forced to be a quiet NaN@. + +This function, if given a string literal all of which would have been +consumed by @code{strtol}, is evaluated early enough that it is considered a +compile-time constant. +@enddefbuiltin + +@defbuiltin{_Decimal32 __builtin_nand32 (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. +@enddefbuiltin + +@defbuiltin{_Decimal64 __builtin_nand64 (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. +@enddefbuiltin + +@defbuiltin{_Decimal128 __builtin_nand128 (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. +@enddefbuiltin + +@defbuiltin{float __builtin_nanf (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is @code{float}. +@enddefbuiltin + +@defbuiltin{{long double} __builtin_nanl (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is @code{long double}. +@enddefbuiltin + +@defbuiltin{_Float@var{n} __builtin_nanf@var{n} (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is +@code{_Float@var{n}}. +@enddefbuiltin + +@defbuiltin{_Float@var{n}x __builtin_nanf@var{n}x (const char *@var{str})} +Similar to @code{__builtin_nan}, except the return type is +@code{_Float@var{n}x}. +@enddefbuiltin + +@defbuiltin{double __builtin_nans (const char *@var{str})} +Similar to @code{__builtin_nan}, except the significand is forced +to be a signaling NaN@. The @code{nans} function is proposed by +@uref{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. +@enddefbuiltin + +@defbuiltin{_Decimal32 __builtin_nansd32 (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}. +@enddefbuiltin + +@defbuiltin{_Decimal64 __builtin_nansd64 (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}. +@enddefbuiltin + +@defbuiltin{_Decimal128 __builtin_nansd128 (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}. +@enddefbuiltin + +@defbuiltin{float __builtin_nansf (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is @code{float}. +@enddefbuiltin + +@defbuiltin{{long double} __builtin_nansl (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is @code{long double}. +@enddefbuiltin + +@defbuiltin{_Float@var{n} __builtin_nansf@var{n} (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is +@code{_Float@var{n}}. +@enddefbuiltin + +@defbuiltin{_Float@var{n}x __builtin_nansf@var{n}x (const char *@var{str})} +Similar to @code{__builtin_nans}, except the return type is +@code{_Float@var{n}x}. +@enddefbuiltin + +@defbuiltin{int __builtin_issignaling (...)} +Return non-zero if the argument is a signaling NaN and zero otherwise. +Note while the parameter list is an +ellipsis, this function only accepts exactly one floating-point +argument. GCC treats this parameter as type-generic, which means it +does not do default promotion from float to double. +This built-in function can work even without the non-default +@code{-fsignaling-nans} option, although if a signaling NaN is computed, +stored or passed as argument to some function other than this built-in +in the current translation unit, it is safer to use @code{-fsignaling-nans}. +With @code{-ffinite-math-only} option this built-in function will always +return 0. +@enddefbuiltin + +@defbuiltin{double __builtin_powi (double, int)} +@defbuiltinx{float __builtin_powif (float, int)} +@defbuiltinx{{long double} __builtin_powil (long double, int)} +Returns the first argument raised to the power of the second. Unlike the +@code{pow} function no guarantees about precision and rounding are made. +@enddefbuiltin + +@node Bit Operation Builtins +@subsection Bit Operation Builtins +@cindex bit operation builtins + +@defbuiltin{int __builtin_ffs (int @var{x})} +Returns one plus the index of the least significant 1-bit of @var{x}, or +if @var{x} is zero, returns zero. +@enddefbuiltin + +@defbuiltin{int __builtin_clz (unsigned int @var{x})} +Returns the number of leading 0-bits in @var{x}, starting at the most +significant bit position. If @var{x} is 0, the result is undefined. +@enddefbuiltin + +@defbuiltin{int __builtin_ctz (unsigned int @var{x})} +Returns the number of trailing 0-bits in @var{x}, starting at the least +significant bit position. If @var{x} is 0, the result is undefined. +@enddefbuiltin + +@defbuiltin{int __builtin_clrsb (int @var{x})} +Returns the number of leading redundant sign bits in @var{x}, i.e.@: the +number of bits following the most significant bit that are identical +to it. There are no special cases for 0 or other values. +@enddefbuiltin + +@defbuiltin{int __builtin_popcount (unsigned int @var{x})} +Returns the number of 1-bits in @var{x}. +@enddefbuiltin + +@defbuiltin{int __builtin_parity (unsigned int @var{x})} +Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} +modulo 2. +@enddefbuiltin + +@defbuiltin{int __builtin_ffsl (long)} +Similar to @code{__builtin_ffs}, except the argument type is +@code{long}. +@enddefbuiltin + +@defbuiltin{int __builtin_clzl (unsigned long)} +Similar to @code{__builtin_clz}, except the argument type is +@code{unsigned long}. +@enddefbuiltin + +@defbuiltin{int __builtin_ctzl (unsigned long)} +Similar to @code{__builtin_ctz}, except the argument type is +@code{unsigned long}. +@enddefbuiltin + +@defbuiltin{int __builtin_clrsbl (long)} +Similar to @code{__builtin_clrsb}, except the argument type is +@code{long}. +@enddefbuiltin + +@defbuiltin{int __builtin_popcountl (unsigned long)} +Similar to @code{__builtin_popcount}, except the argument type is +@code{unsigned long}. +@enddefbuiltin + +@defbuiltin{int __builtin_parityl (unsigned long)} +Similar to @code{__builtin_parity}, except the argument type is +@code{unsigned long}. +@enddefbuiltin + +@defbuiltin{int __builtin_ffsll (long long)} +Similar to @code{__builtin_ffs}, except the argument type is +@code{long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_clzll (unsigned long long)} +Similar to @code{__builtin_clz}, except the argument type is +@code{unsigned long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_ctzll (unsigned long long)} +Similar to @code{__builtin_ctz}, except the argument type is +@code{unsigned long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_clrsbll (long long)} +Similar to @code{__builtin_clrsb}, except the argument type is +@code{long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_popcountll (unsigned long long)} +Similar to @code{__builtin_popcount}, except the argument type is +@code{unsigned long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_parityll (unsigned long long)} +Similar to @code{__builtin_parity}, except the argument type is +@code{unsigned long long}. +@enddefbuiltin + +@defbuiltin{int __builtin_ffsg (...)} +Similar to @code{__builtin_ffs}, except the argument is type-generic +signed integer (standard, extended or bit-precise). No integral argument +promotions are performed on the argument. +@enddefbuiltin + +@defbuiltin{int __builtin_clzg (...)} +Similar to @code{__builtin_clz}, except the argument is type-generic +unsigned integer (standard, extended or bit-precise) and there is +optional second argument with int type. No integral argument promotions +are performed on the first argument. If two arguments are specified, +and first argument is 0, the result is the second argument. If only +one argument is specified and it is 0, the result is undefined. +@enddefbuiltin + +@defbuiltin{int __builtin_ctzg (...)} +Similar to @code{__builtin_ctz}, except the argument is type-generic +unsigned integer (standard, extended or bit-precise) and there is +optional second argument with int type. No integral argument promotions +are performed on the first argument. If two arguments are specified, +and first argument is 0, the result is the second argument. If only +one argument is specified and it is 0, the result is undefined. +@enddefbuiltin + +@defbuiltin{int __builtin_clrsbg (...)} +Similar to @code{__builtin_clrsb}, except the argument is type-generic +signed integer (standard, extended or bit-precise). No integral argument +promotions are performed on the argument. +@enddefbuiltin + +@defbuiltin{int __builtin_popcountg (...)} +Similar to @code{__builtin_popcount}, except the argument is type-generic +unsigned integer (standard, extended or bit-precise). No integral argument +promotions are performed on the argument. +@enddefbuiltin + +@defbuiltin{int __builtin_parityg (...)} +Similar to @code{__builtin_parity}, except the argument is type-generic +unsigned integer (standard, extended or bit-precise). No integral argument +promotions are performed on the argument. +@enddefbuiltin + +@defbuiltin{@var{type} __builtin_stdc_bit_ceil (@var{type} @var{arg})} +The @code{__builtin_stdc_bit_ceil} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{@var{arg} <= 1 ? (@var{type}) 1 +: (@var{type}) 2 << (@var{prec} - 1 - __builtin_clzg ((@var{type}) (@var{arg} - 1)))} +where @var{prec} is bit width of @var{type}, except that side-effects +in @var{arg} are evaluated just once. +@enddefbuiltin + +@defbuiltin{@var{type} __builtin_stdc_bit_floor (@var{type} @var{arg})} +The @code{__builtin_stdc_bit_floor} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{@var{arg} == 0 ? (@var{type}) 0 +: (@var{type}) 1 << (@var{prec} - 1 - __builtin_clzg (@var{arg}))} +where @var{prec} is bit width of @var{type}, except that side-effects +in @var{arg} are evaluated just once. +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_bit_width (@var{type} @var{arg})} +The @code{__builtin_stdc_bit_width} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) (@var{prec} - __builtin_clzg (@var{arg}, @var{prec}))} +where @var{prec} is bit width of @var{type}. +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_count_ones (@var{type} @var{arg})} +The @code{__builtin_stdc_count_ones} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_popcountg (@var{arg})} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_count_zeros (@var{type} @var{arg})} +The @code{__builtin_stdc_count_zeros} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_popcountg ((@var{type}) ~@var{arg})} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_first_leading_one (@var{type} @var{arg})} +The @code{__builtin_stdc_first_leading_one} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{__builtin_clzg (@var{arg}, -1) + 1U} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_first_leading_zero (@var{type} @var{arg})} +The @code{__builtin_stdc_first_leading_zero} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{__builtin_clzg ((@var{type}) ~@var{arg}, -1) + 1U} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_first_trailing_one (@var{type} @var{arg})} +The @code{__builtin_stdc_first_trailing_one} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{__builtin_ctzg (@var{arg}, -1) + 1U} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_first_trailing_zero (@var{type} @var{arg})} +The @code{__builtin_stdc_first_trailing_zero} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{__builtin_ctzg ((@var{type}) ~@var{arg}, -1) + 1U} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_has_single_bit (@var{type} @var{arg})} +The @code{__builtin_stdc_has_single_bit} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(_Bool) (__builtin_popcountg (@var{arg}) == 1)} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_leading_ones (@var{type} @var{arg})} +The @code{__builtin_stdc_leading_ones} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_clzg ((@var{type}) ~@var{arg}, @var{prec})} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_leading_zeros (@var{type} @var{arg})} +The @code{__builtin_stdc_leading_zeros} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_clzg (@var{arg}, @var{prec})} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_trailing_ones (@var{type} @var{arg})} +The @code{__builtin_stdc_trailing_ones} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_ctzg ((@var{type}) ~@var{arg}, @var{prec})} +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_stdc_trailing_zeros (@var{type} @var{arg})} +The @code{__builtin_stdc_trailing_zeros} function is available only +in C. It is type-generic, the argument can be any unsigned integer +(standard, extended or bit-precise). No integral argument promotions are +performed on the argument. It is equivalent to +@code{(unsigned int) __builtin_ctzg (@var{arg}, @var{prec})} +@enddefbuiltin + +@defbuiltin{@var{type1} __builtin_stdc_rotate_left (@var{type1} @var{arg1}, @var{type2} @var{arg2})} +The @code{__builtin_stdc_rotate_left} function is available only +in C. It is type-generic, the first argument can be any unsigned integer +(standard, extended or bit-precise) and second argument any signed or +unsigned integer or @code{char}. No integral argument promotions are +performed on the arguments. It is equivalent to +@code{(@var{type1}) ((@var{arg1} << (@var{arg2} % @var{prec})) +| (@var{arg1} >> ((-(unsigned @var{type2}) @var{arg2}) % @var{prec})))} +where @var{prec} is bit width of @var{type1}, except that side-effects +in @var{arg1} and @var{arg2} are evaluated just once. The behavior is +undefined if @var{arg2} is negative. +@enddefbuiltin + +@defbuiltin{@var{type1} __builtin_stdc_rotate_right (@var{type1} @var{arg1}, @var{type2} @var{arg2})} +The @code{__builtin_stdc_rotate_right} function is available only +in C. It is type-generic, the first argument can be any unsigned integer +(standard, extended or bit-precise) and second argument any signed or +unsigned integer or @code{char}. No integral argument promotions are +performed on the arguments. It is equivalent to +@code{(@var{type1}) ((@var{arg1} >> (@var{arg2} % @var{prec})) +| (@var{arg1} << ((-(unsigned @var{type2}) @var{arg2}) % @var{prec})))} +where @var{prec} is bit width of @var{type1}, except that side-effects +in @var{arg1} and @var{arg2} are evaluated just once. The behavior is +undefined if @var{arg2} is negative. +@enddefbuiltin + +@node Byte-Swapping Builtins +@subsection Byte-Swapping Builtins +@cindex byte-swapping builtins + +@defbuiltin{uint16_t __builtin_bswap16 (uint16_t @var{x})} +Returns @var{x} with the order of the bytes reversed; for example, +@code{0xabcd} becomes @code{0xcdab}. Byte here always means +exactly 8 bits. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_bswap32 (uint32_t @var{x})} +Similar to @code{__builtin_bswap16}, except the argument and return types +are 32-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_bswap64 (uint64_t @var{x})} +Similar to @code{__builtin_bswap32}, except the argument and return types +are 64-bit. +@enddefbuiltin + +@defbuiltin{uint128_t __builtin_bswap128 (uint128_t @var{x})} +Similar to @code{__builtin_bswap64}, except the argument and return types +are 128-bit. Only supported on targets when 128-bit types are supported. +@enddefbuiltin + +@node CRC Builtins +@subsection CRC Builtins +@cindex CRC builtins + +@defbuiltin{uint8_t __builtin_rev_crc8_data8 (uint8_t @var{crc}, uint8_t @var{data}, uint8_t @var{poly})} +Returns the calculated 8-bit bit-reversed CRC using the initial CRC (8-bit), +data (8-bit) and the polynomial (8-bit). +@var{crc} is the initial CRC, @var{data} is the data and +@var{poly} is the polynomial without leading 1. +Table-based or clmul-based CRC may be used for the +calculation, depending on the target architecture. +@enddefbuiltin + +@defbuiltin{uint16_t __builtin_rev_crc16_data16 (uint16_t @var{crc}, uint16_t @var{data}, uint16_t @var{poly})} +Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types +are 16-bit. +@enddefbuiltin + +@defbuiltin{uint16_t __builtin_rev_crc16_data8 (uint16_t @var{crc}, uint8_t @var{data}, uint16_t @var{poly})} +Similar to @code{__builtin_rev_crc16_data16}, except the @var{data} argument +type is 8-bit. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_rev_crc32_data32 (uint32_t @var{crc}, uint32_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types +are 32-bit and for the CRC calculation may be also used crc* machine instruction +depending on the target and the polynomial. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_rev_crc32_data8 (uint32_t @var{crc}, uint8_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_rev_crc32_data32}, except the @var{data} argument +type is 8-bit. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_rev_crc32_data16 (uint32_t @var{crc}, uint16_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_rev_crc32_data32}, except the @var{data} argument +type is 16-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_rev_crc64_data64 (uint64_t @var{crc}, uint64_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types +are 64-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_rev_crc64_data8 (uint64_t @var{crc}, uint8_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type +is 8-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_rev_crc64_data16 (uint64_t @var{crc}, uint16_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type +is 16-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_rev_crc64_data32 (uint64_t @var{crc}, uint32_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type +is 32-bit. +@enddefbuiltin + +@defbuiltin{uint8_t __builtin_crc8_data8 (uint8_t @var{crc}, uint8_t @var{data}, uint8_t @var{poly})} +Returns the calculated 8-bit bit-forward CRC using the initial CRC (8-bit), +data (8-bit) and the polynomial (8-bit). +@var{crc} is the initial CRC, @var{data} is the data and +@var{poly} is the polynomial without leading 1. +Table-based or clmul-based CRC may be used for the +calculation, depending on the target architecture. +@enddefbuiltin + +@defbuiltin{uint16_t __builtin_crc16_data16 (uint16_t @var{crc}, uint16_t @var{data}, uint16_t @var{poly})} +Similar to @code{__builtin_crc8_data8}, except the argument and return types +are 16-bit. +@enddefbuiltin + +@defbuiltin{uint16_t __builtin_crc16_data8 (uint16_t @var{crc}, uint8_t @var{data}, uint16_t @var{poly})} +Similar to @code{__builtin_crc16_data16}, except the @var{data} argument type +is 8-bit. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_crc32_data32 (uint32_t @var{crc}, uint32_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_crc8_data8}, except the argument and return types +are 32-bit. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_crc32_data8 (uint32_t @var{crc}, uint8_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_crc32_data32}, except the @var{data} argument type +is 8-bit. +@enddefbuiltin + +@defbuiltin{uint32_t __builtin_crc32_data16 (uint32_t @var{crc}, uint16_t @var{data}, uint32_t @var{poly})} +Similar to @code{__builtin_crc32_data32}, except the @var{data} argument type +is 16-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_crc64_data64 (uint64_t @var{crc}, uint64_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_crc8_data8}, except the argument and return types +are 64-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_crc64_data8 (uint64_t @var{crc}, uint8_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type +is 8-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_crc64_data16 (uint64_t @var{crc}, uint16_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type +is 16-bit. +@enddefbuiltin + +@defbuiltin{uint64_t __builtin_crc64_data32 (uint64_t @var{crc}, uint32_t @var{data}, uint64_t @var{poly})} +Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type +is 32-bit. +@enddefbuiltin + +@node Integer Overflow Builtins +@subsection Built-in Functions to Perform Arithmetic with Overflow Checking +@cindex overflow checking builtins +@cindex integer arithmetic overflow checking builtins +@cindex builtins for arithmetic overflow checking + +The following built-in functions allow performing simple arithmetic operations +together with checking whether the operations overflowed. + +@defbuiltin{bool __builtin_add_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} +@defbuiltinx{bool __builtin_sadd_overflow (int @var{a}, int @var{b}, int *@var{res})} +@defbuiltinx{bool __builtin_saddl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} +@defbuiltinx{bool __builtin_saddll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} +@defbuiltinx{bool __builtin_uadd_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} +@defbuiltinx{bool __builtin_uaddl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} +@defbuiltinx{bool __builtin_uaddll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} + +These built-in functions promote the first two operands into infinite precision signed +type and perform addition on those promoted operands. The result is then +cast to the type the third pointer argument points to and stored there. +If the stored result is equal to the infinite precision result, the built-in +functions return @code{false}, otherwise they return @code{true}. As the addition is +performed in infinite signed precision, these built-in functions have fully defined +behavior for all argument values. + +The first built-in function allows arbitrary integral types for operands and +the result type must be pointer to some integral type other than enumerated or +boolean type, the rest of the built-in functions have explicit integer types. + +The compiler will attempt to use hardware instructions to implement +these built-in functions where possible, like conditional jump on overflow +after addition, conditional jump on carry etc. + +@enddefbuiltin + +@defbuiltin{bool __builtin_sub_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} +@defbuiltinx{bool __builtin_ssub_overflow (int @var{a}, int @var{b}, int *@var{res})} +@defbuiltinx{bool __builtin_ssubl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} +@defbuiltinx{bool __builtin_ssubll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} +@defbuiltinx{bool __builtin_usub_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} +@defbuiltinx{bool __builtin_usubl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} +@defbuiltinx{bool __builtin_usubll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} + +These built-in functions are similar to the add overflow checking built-in +functions above, except they perform subtraction, subtract the second argument +from the first one, instead of addition. + +@enddefbuiltin + +@defbuiltin{bool __builtin_mul_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} +@defbuiltinx{bool __builtin_smul_overflow (int @var{a}, int @var{b}, int *@var{res})} +@defbuiltinx{bool __builtin_smull_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} +@defbuiltinx{bool __builtin_smulll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} +@defbuiltinx{bool __builtin_umul_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} +@defbuiltinx{bool __builtin_umull_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} +@defbuiltinx{bool __builtin_umulll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} + +These built-in functions are similar to the add overflow checking built-in +functions above, except they perform multiplication, instead of addition. + +@enddefbuiltin + +The following built-in functions allow checking if simple arithmetic operation +would overflow. + +@defbuiltin{bool __builtin_add_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} +@defbuiltinx{bool __builtin_sub_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} +@defbuiltinx{bool __builtin_mul_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} + +These built-in functions are similar to @code{__builtin_add_overflow}, +@code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that +they don't store the result of the arithmetic operation anywhere and the +last argument is not a pointer, but some expression with integral type other +than enumerated or boolean type. + +The built-in functions promote the first two operands into infinite precision signed type +and perform addition on those promoted operands. The result is then +cast to the type of the third argument. If the cast result is equal to the infinite +precision result, the built-in functions return @code{false}, otherwise they return @code{true}. +The value of the third argument is ignored, just the side effects in the third argument +are evaluated, and no integral argument promotions are performed on the last argument. +If the third argument is a bit-field, the type used for the result cast has the +precision and signedness of the given bit-field, rather than precision and signedness +of the underlying type. + +For example, the following macro can be used to portably check, at +compile-time, whether or not adding two constant integers will overflow, +and perform the addition only when it is known to be safe and not to trigger +a @option{-Woverflow} warning. + +@smallexample +#define INT_ADD_OVERFLOW_P(a, b) \ + __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0) + +enum @{ + A = INT_MAX, B = 3, + C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B, + D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0) +@}; +@end smallexample + +The compiler will attempt to use hardware instructions to implement +these built-in functions where possible, like conditional jump on overflow +after addition, conditional jump on carry etc. + +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_addc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})} +@defbuiltinx{{unsigned long int} __builtin_addcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})} +@defbuiltinx{{unsigned long long int} __builtin_addcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})} + +These built-in functions are equivalent to: +@smallexample + (@{ __typeof__ (@var{a}) s; \ + __typeof__ (@var{a}) c1 = __builtin_add_overflow (@var{a}, @var{b}, &s); \ + __typeof__ (@var{a}) c2 = __builtin_add_overflow (s, @var{carry_in}, &s); \ + *(@var{carry_out}) = c1 | c2; \ + s; @}) +@end smallexample + +i.e.@: they add 3 unsigned values, set what the last argument +points to to 1 if any of the two additions overflowed (otherwise 0) +and return the sum of those 3 unsigned values. Note, while all +the first 3 arguments can have arbitrary values, better code will be +emitted if one of them (preferably the third one) has only values +0 or 1 (i.e.@: carry-in). + +@enddefbuiltin + +@defbuiltin{{unsigned int} __builtin_subc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})} +@defbuiltinx{{unsigned long int} __builtin_subcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})} +@defbuiltinx{{unsigned long long int} __builtin_subcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})} + +These built-in functions are equivalent to: +@smallexample + (@{ __typeof__ (@var{a}) s; \ + __typeof__ (@var{a}) c1 = __builtin_sub_overflow (@var{a}, @var{b}, &s); \ + __typeof__ (@var{a}) c2 = __builtin_sub_overflow (s, @var{carry_in}, &s); \ + *(@var{carry_out}) = c1 | c2; \ + s; @}) +@end smallexample + +i.e.@: they subtract 2 unsigned values from the first unsigned value, +set what the last argument points to to 1 if any of the two subtractions +overflowed (otherwise 0) and return the result of the subtractions. +Note, while all the first 3 arguments can have arbitrary values, better code +will be emitted if one of them (preferrably the third one) has only values +0 or 1 (i.e.@: carry-in). + +@enddefbuiltin + +@node Stack Allocation +@section Builtins for Stack Allocation +@cindex stack allocation builtins +@cindex builtins for stack allocation + +@defbuiltin{{void *} __builtin_alloca (size_t @var{size})} +The @code{__builtin_alloca} function must be called at block scope. +The function allocates an object @var{size} bytes large on the stack +of the calling function. The object is aligned on the default stack +alignment boundary for the target determined by the +@code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca} +function returns a pointer to the first byte of the allocated object. +The lifetime of the allocated object ends just before the calling +function returns to its caller. This is so even when +@code{__builtin_alloca} is called within a nested block. + +For example, the following function allocates eight objects of @code{n} +bytes each on the stack, storing a pointer to each in consecutive elements +of the array @code{a}. It then passes the array to function @code{g} +which can safely use the storage pointed to by each of the array elements. + +@smallexample +void f (unsigned n) +@{ + void *a [8]; + for (int i = 0; i != 8; ++i) + a [i] = __builtin_alloca (n); + + g (a, n); // @r{safe} +@} +@end smallexample + +Since the @code{__builtin_alloca} function doesn't validate its argument +it is the responsibility of its caller to make sure the argument doesn't +cause it to exceed the stack size limit. +The @code{__builtin_alloca} function is provided to make it possible to +allocate on the stack arrays of bytes with an upper bound that may be +computed at run time. Since C99 Variable Length Arrays offer +similar functionality under a portable, more convenient, and safer +interface they are recommended instead, in both C99 and C++ programs +where GCC provides them as an extension. +@xref{Variable Length}, for details. + +@enddefbuiltin + +@defbuiltin{{void *} __builtin_alloca_with_align (size_t @var{size}, size_t @var{alignment})} +The @code{__builtin_alloca_with_align} function must be called at block +scope. The function allocates an object @var{size} bytes large on +the stack of the calling function. The allocated object is aligned on +the boundary specified by the argument @var{alignment} whose unit is given +in bits (not bytes). The @var{size} argument must be positive and not +exceed the stack size limit. The @var{alignment} argument must be a constant +integer expression that evaluates to a power of 2 greater than or equal to +@code{CHAR_BIT} and less than some unspecified maximum. Invocations +with other values are rejected with an error indicating the valid bounds. +The function returns a pointer to the first byte of the allocated object. +The lifetime of the allocated object ends at the end of the block in which +the function was called. The allocated storage is released no later than +just before the calling function returns to its caller, but may be released +at the end of the block in which the function was called. + +For example, in the following function the call to @code{g} is unsafe +because when @code{overalign} is non-zero, the space allocated by +@code{__builtin_alloca_with_align} may have been released at the end +of the @code{if} statement in which it was called. + +@smallexample +void f (unsigned n, bool overalign) +@{ + void *p; + if (overalign) + p = __builtin_alloca_with_align (n, 64 /* bits */); + else + p = __builtin_alloc (n); + + g (p, n); // @r{unsafe} +@} +@end smallexample + +Since the @code{__builtin_alloca_with_align} function doesn't validate its +@var{size} argument it is the responsibility of its caller to make sure +the argument doesn't cause it to exceed the stack size limit. +The @code{__builtin_alloca_with_align} function is provided to make +it possible to allocate on the stack overaligned arrays of bytes with +an upper bound that may be computed at run time. Since C99 +Variable Length Arrays offer the same functionality under +a portable, more convenient, and safer interface they are recommended +instead, in both C99 and C++ programs where GCC provides them as +an extension. @xref{Variable Length}, for details. + +@enddefbuiltin + +@defbuiltin{{void *} __builtin_alloca_with_align_and_max (size_t @var{size}, size_t @var{alignment}, size_t @var{max_size})} +Similar to @code{__builtin_alloca_with_align} but takes an extra argument +specifying an upper bound for @var{size} in case its value cannot be computed +at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage} +and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer +expression, it has no effect on code generation and no attempt is made to +check its compatibility with @var{size}. + +@enddefbuiltin + @node Nonlocal Gotos @section Nonlocal Gotos @cindex nonlocal gotos @@ -14341,6 +16032,18 @@ myopen (const char *path, int oflag, ...) @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 @@ -14783,149 +16486,27 @@ x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@}); @c but GCC does not accept it for unions of vector types (PR 88955). @end smallexample -@node __sync Builtins -@section Legacy @code{__sync} Built-in Functions for Atomic Memory Access +@node Atomic Memory Access +@section Builtins for Atomic Memory Access +@cindex atomic memory access builtins +@cindex builtins 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. +GCC supports two sets of builtins for atomic memory access primitives. The +@code{__atomic} builtins provide the underlying support for the C++11 +atomic operations library, and are the currently-recommended interface when +the C++11 library functions cannot be used directly. +The @code{__sync} builtins implement the specification from the Intel IA64 +pSABI and are supported primarily for use in legacy code. -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 +@menu +* __atomic Builtins:: Atomic built-in functions with memory model. +* __sync Builtins:: Legacy built-in functions for atomic memory access. +@end menu @node __atomic Builtins -@section Built-in Functions for Memory Model Aware Atomic Operations +@subsection Built-in Functions for Memory Model Aware Atomic Operations +@cindex C++11 memory model +@cindex __atomic builtins The following built-in functions approximately match the requirements for the C++11 memory model. They are all @@ -15029,6 +16610,39 @@ reserved for the memory order. The remainder of the signed int is reserved for target use and should be 0. Use of the predefined atomic values ensures proper usage. +@anchor{x86 specific memory model extensions for transactional memory} +@cindex x86 transactional memory extensions +@cindex transactional memory extensions for x86 +The x86 architecture supports additional memory ordering modifiers +to mark critical sections for hardware lock elision. +These modifiers can be bitwise or'ed with a standard memory order to +atomic intrinsics. + +@table @code +@item __ATOMIC_HLE_ACQUIRE +Start lock elision on a lock variable. +Memory order must be @code{__ATOMIC_ACQUIRE} or stronger. +@item __ATOMIC_HLE_RELEASE +End lock elision on a lock variable. +Memory order must be @code{__ATOMIC_RELEASE} or stronger. +@end table + +When a lock acquire fails, it is required for good performance to abort +the transaction quickly. This can be done with a @code{_mm_pause}. + +@smallexample +#include <immintrin.h> // For _mm_pause + +int lockvar; + +/* Acquire lock with lock elision */ +while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) + _mm_pause(); /* Abort failed transaction */ +... +/* Free lock with lock elision */ +__atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); +@end smallexample + @defbuiltin{@var{type} __atomic_load_n (@var{type} *@var{ptr}, int @var{memorder})} This built-in function implements an atomic load operation. It returns the contents of @code{*@var{ptr}}. @@ -15226,186 +16840,150 @@ alignment. A value of 0 indicates typical alignment should be used. The compiler may also ignore this parameter. @enddefbuiltin -@node Integer Overflow Builtins -@section Built-in Functions to Perform Arithmetic with Overflow Checking - -The following built-in functions allow performing simple arithmetic operations -together with checking whether the operations overflowed. - -@defbuiltin{bool __builtin_add_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} -@defbuiltinx{bool __builtin_sadd_overflow (int @var{a}, int @var{b}, int *@var{res})} -@defbuiltinx{bool __builtin_saddl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} -@defbuiltinx{bool __builtin_saddll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} -@defbuiltinx{bool __builtin_uadd_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} -@defbuiltinx{bool __builtin_uaddl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} -@defbuiltinx{bool __builtin_uaddll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} - -These built-in functions promote the first two operands into infinite precision signed -type and perform addition on those promoted operands. The result is then -cast to the type the third pointer argument points to and stored there. -If the stored result is equal to the infinite precision result, the built-in -functions return @code{false}, otherwise they return @code{true}. As the addition is -performed in infinite signed precision, these built-in functions have fully defined -behavior for all argument values. - -The first built-in function allows arbitrary integral types for operands and -the result type must be pointer to some integral type other than enumerated or -boolean type, the rest of the built-in functions have explicit integer types. - -The compiler will attempt to use hardware instructions to implement -these built-in functions where possible, like conditional jump on overflow -after addition, conditional jump on carry etc. - -@enddefbuiltin - -@defbuiltin{bool __builtin_sub_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} -@defbuiltinx{bool __builtin_ssub_overflow (int @var{a}, int @var{b}, int *@var{res})} -@defbuiltinx{bool __builtin_ssubl_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} -@defbuiltinx{bool __builtin_ssubll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} -@defbuiltinx{bool __builtin_usub_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} -@defbuiltinx{bool __builtin_usubl_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} -@defbuiltinx{bool __builtin_usubll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} -These built-in functions are similar to the add overflow checking built-in -functions above, except they perform subtraction, subtract the second argument -from the first one, instead of addition. - -@enddefbuiltin - -@defbuiltin{bool __builtin_mul_overflow (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} *@var{res})} -@defbuiltinx{bool __builtin_smul_overflow (int @var{a}, int @var{b}, int *@var{res})} -@defbuiltinx{bool __builtin_smull_overflow (long int @var{a}, long int @var{b}, long int *@var{res})} -@defbuiltinx{bool __builtin_smulll_overflow (long long int @var{a}, long long int @var{b}, long long int *@var{res})} -@defbuiltinx{bool __builtin_umul_overflow (unsigned int @var{a}, unsigned int @var{b}, unsigned int *@var{res})} -@defbuiltinx{bool __builtin_umull_overflow (unsigned long int @var{a}, unsigned long int @var{b}, unsigned long int *@var{res})} -@defbuiltinx{bool __builtin_umulll_overflow (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int *@var{res})} +@node __sync Builtins +@subsection Legacy @code{__sync} Built-in Functions for Atomic Memory Access +@cindex legacy builtins for atomic memory access +@cindex IA64 atomic memory access builtins +@cindex __sync builtins -These built-in functions are similar to the add overflow checking built-in -functions above, except they perform multiplication, instead of addition. +The following built-in functions +are intended to be compatible with those described +in the @cite{Intel Itanium Processor-specific Application Binary Interface}, +section 7.4. As such, they depart from normal GCC practice by not using +the @samp{__builtin_} prefix and also by being overloaded so that they +work on multiple types. -@enddefbuiltin +The definition given in the Intel documentation allows only for the use of +the types @code{int}, @code{long}, @code{long long} or their unsigned +counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in +size other than the C type @code{_Bool} or the C++ type @code{bool}. +Operations on pointer arguments are performed as if the operands were +of the @code{uintptr_t} type. That is, they are not scaled by the size +of the type to which the pointer points. -The following built-in functions allow checking if simple arithmetic operation -would overflow. +These functions are implemented in terms of the @samp{__atomic} +builtins (@pxref{__atomic Builtins}). They should not be used for new +code which should use the @samp{__atomic} builtins instead. -@defbuiltin{bool __builtin_add_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} -@defbuiltinx{bool __builtin_sub_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} -@defbuiltinx{bool __builtin_mul_overflow_p (@var{type1} @var{a}, @var{type2} @var{b}, @var{type3} @var{c})} +Not all operations are supported by all target processors. If a particular +operation cannot be implemented on the target processor, a call to an +external function is generated. The external function carries the same name +as the built-in version, with an additional suffix +@samp{_@var{n}} where @var{n} is the size of the data type. -These built-in functions are similar to @code{__builtin_add_overflow}, -@code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that -they don't store the result of the arithmetic operation anywhere and the -last argument is not a pointer, but some expression with integral type other -than enumerated or boolean type. +In most cases, these built-in functions are considered a @dfn{full barrier}. +That is, +no memory operand is moved across the operation, either forward or +backward. Further, instructions are issued as necessary to prevent the +processor from speculating loads across the operation and from queuing stores +after the operation. -The built-in functions promote the first two operands into infinite precision signed type -and perform addition on those promoted operands. The result is then -cast to the type of the third argument. If the cast result is equal to the infinite -precision result, the built-in functions return @code{false}, otherwise they return @code{true}. -The value of the third argument is ignored, just the side effects in the third argument -are evaluated, and no integral argument promotions are performed on the last argument. -If the third argument is a bit-field, the type used for the result cast has the -precision and signedness of the given bit-field, rather than precision and signedness -of the underlying type. +All of the routines are described in the Intel documentation to take +``an optional list of variables protected by the memory barrier''. It's +not clear what is meant by that; it could mean that @emph{only} the +listed variables are protected, or it could mean a list of additional +variables to be protected. The list is ignored by GCC which treats it as +empty. GCC interprets an empty list as meaning that all globally +accessible variables should be protected. -For example, the following macro can be used to portably check, at -compile-time, whether or not adding two constant integers will overflow, -and perform the addition only when it is known to be safe and not to trigger -a @option{-Woverflow} warning. +@defbuiltin{@var{type} __sync_fetch_and_add (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_fetch_and_sub (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_fetch_and_or (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_fetch_and_and (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_fetch_and_xor (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_fetch_and_nand (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +These built-in functions perform the operation suggested by the name, and +returns the value that had previously been in memory. That is, operations +on integer operands have the following semantics. Operations on pointer +arguments are performed as if the operands were of the @code{uintptr_t} +type. That is, they are not scaled by the size of the type to which +the pointer points. @smallexample -#define INT_ADD_OVERFLOW_P(a, b) \ - __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0) - -enum @{ - A = INT_MAX, B = 3, - C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B, - D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0) -@}; +@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} +@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand @end smallexample -The compiler will attempt to use hardware instructions to implement -these built-in functions where possible, like conditional jump on overflow -after addition, conditional jump on carry etc. - +The object pointed to by the first argument must be of integer or pointer +type. It must not be a boolean type. + +@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} +as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. @enddefbuiltin -@defbuiltin{{unsigned int} __builtin_addc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})} -@defbuiltinx{{unsigned long int} __builtin_addcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})} -@defbuiltinx{{unsigned long long int} __builtin_addcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})} +@defbuiltin{@var{type} __sync_add_and_fetch (@var{type} *@var{ptr}, @ + @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_sub_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_or_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_and_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_xor_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +@defbuiltinx{@var{type} __sync_nand_and_fetch (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +These built-in functions perform the operation suggested by the name, and +return the new value. That is, operations on integer operands have +the following semantics. Operations on pointer operands are performed as +if the operand's type were @code{uintptr_t}. -These built-in functions are equivalent to: @smallexample - (@{ __typeof__ (@var{a}) s; \ - __typeof__ (@var{a}) c1 = __builtin_add_overflow (@var{a}, @var{b}, &s); \ - __typeof__ (@var{a}) c2 = __builtin_add_overflow (s, @var{carry_in}, &s); \ - *(@var{carry_out}) = c1 | c2; \ - s; @}) +@{ *ptr @var{op}= value; return *ptr; @} +@{ *ptr = ~(*ptr & value); return *ptr; @} // nand @end smallexample -i.e.@: they add 3 unsigned values, set what the last argument -points to to 1 if any of the two additions overflowed (otherwise 0) -and return the sum of those 3 unsigned values. Note, while all -the first 3 arguments can have arbitrary values, better code will be -emitted if one of them (preferably the third one) has only values -0 or 1 (i.e.@: carry-in). +The same constraints on arguments apply as for the corresponding +@code{__sync_op_and_fetch} built-in functions. +@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} +as @code{*ptr = ~(*ptr & value)} instead of +@code{*ptr = ~*ptr & value}. @enddefbuiltin -@defbuiltin{{unsigned int} __builtin_subc (unsigned int @var{a}, unsigned int @var{b}, unsigned int @var{carry_in}, unsigned int *@var{carry_out})} -@defbuiltinx{{unsigned long int} __builtin_subcl (unsigned long int @var{a}, unsigned long int @var{b}, unsigned int @var{carry_in}, unsigned long int *@var{carry_out})} -@defbuiltinx{{unsigned long long int} __builtin_subcll (unsigned long long int @var{a}, unsigned long long int @var{b}, unsigned long long int @var{carry_in}, unsigned long long int *@var{carry_out})} - -These built-in functions are equivalent to: -@smallexample - (@{ __typeof__ (@var{a}) s; \ - __typeof__ (@var{a}) c1 = __builtin_sub_overflow (@var{a}, @var{b}, &s); \ - __typeof__ (@var{a}) c2 = __builtin_sub_overflow (s, @var{carry_in}, &s); \ - *(@var{carry_out}) = c1 | c2; \ - s; @}) -@end smallexample - -i.e.@: they subtract 2 unsigned values from the first unsigned value, -set what the last argument points to to 1 if any of the two subtractions -overflowed (otherwise 0) and return the result of the subtractions. -Note, while all the first 3 arguments can have arbitrary values, better code -will be emitted if one of them (preferrably the third one) has only values -0 or 1 (i.e.@: carry-in). +@defbuiltin{bool __sync_bool_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)} +@defbuiltinx{@var{type} __sync_val_compare_and_swap (@var{type} *@var{ptr}, @var{type} @var{oldval}, @var{type} @var{newval}, ...)} +These built-in functions perform an atomic compare and swap. +That is, if the current +value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into +@code{*@var{ptr}}. +The ``bool'' version returns @code{true} if the comparison is successful and +@var{newval} is written. The ``val'' version returns the contents +of @code{*@var{ptr}} before the operation. @enddefbuiltin -@node x86 specific memory model extensions for transactional memory -@section x86-Specific Memory Model Extensions for Transactional Memory - -The x86 architecture supports additional memory ordering flags -to mark critical sections for hardware lock elision. -These must be specified in addition to an existing memory order to -atomic intrinsics. +@defbuiltin{void __sync_synchronize (...)} +This built-in function issues a full memory barrier. +@enddefbuiltin -@table @code -@item __ATOMIC_HLE_ACQUIRE -Start lock elision on a lock variable. -Memory order must be @code{__ATOMIC_ACQUIRE} or stronger. -@item __ATOMIC_HLE_RELEASE -End lock elision on a lock variable. -Memory order must be @code{__ATOMIC_RELEASE} or stronger. -@end table +@defbuiltin{@var{type} __sync_lock_test_and_set (@var{type} *@var{ptr}, @var{type} @var{value}, ...)} +This built-in function, as described by Intel, is not a traditional test-and-set +operation, but rather an atomic exchange operation. It writes @var{value} +into @code{*@var{ptr}}, and returns the previous contents of +@code{*@var{ptr}}. -When a lock acquire fails, it is required for good performance to abort -the transaction quickly. This can be done with a @code{_mm_pause}. +Many targets have only minimal support for such locks, and do not support +a full exchange operation. In this case, a target may support reduced +functionality here by which the @emph{only} valid value to store is the +immediate constant 1. The exact value actually stored in @code{*@var{ptr}} +is implementation defined. -@smallexample -#include <immintrin.h> // For _mm_pause +This built-in function is not a full barrier, +but rather an @dfn{acquire barrier}. +This means that references after the operation cannot move to (or be +speculated to) before the operation, but previous memory stores may not +be globally visible yet, and previous memory loads may not yet be +satisfied. +@enddefbuiltin -int lockvar; +@defbuiltin{void __sync_lock_release (@var{type} *@var{ptr}, ...)} +This built-in function releases the lock acquired by +@code{__sync_lock_test_and_set}. +Normally this means writing the constant 0 to @code{*@var{ptr}}. -/* Acquire lock with lock elision */ -while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) - _mm_pause(); /* Abort failed transaction */ -... -/* Free lock with lock elision */ -__atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); -@end smallexample +This built-in function is not a full barrier, +but rather a @dfn{release barrier}. +This means that all previous memory stores are globally visible, and all +previous memory loads have been satisfied, but following memory reads +are not prevented from being speculated to before the barrier. +@enddefbuiltin @node Object Size Checking @section Object Size Checking @@ -15432,7 +17010,7 @@ on various optimization passes enabled with @option{-O2}. However, to a limited extent, they can be used without optimization as well. @defbuiltin{size_t __builtin_object_size (const void * @var{ptr}, int @var{type})} -is a built-in construct that returns a constant number of bytes from +This built-in construct returns a constant number of bytes from @var{ptr} to the end of the object @var{ptr} pointer points to (if known at compile time). To determine the sizes of dynamically allocated objects the function relies on the allocation functions called to obtain @@ -15471,6 +17049,7 @@ assert (__builtin_object_size (q, 1) == sizeof (var.b)); @enddefbuiltin @defbuiltin{{size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})} +This builtin is similar to @code{__builtin_object_size} in that it returns a number of bytes from @var{ptr} to the end of the object @var{ptr} pointer points to, except that the size returned may not be a constant. This results in successful @@ -15568,18 +17147,20 @@ is called and the @var{flag} argument passed to it. @node New/Delete Builtins @section Built-in functions for C++ allocations and deallocations -@findex __builtin_operator_new -@findex __builtin_operator_delete -Calling these C++ built-in functions is similar to calling -@code{::operator new} or @code{::operator delete} with the same arguments, -except that it is an error if the selected @code{::operator new} or -@code{::operator delete} overload is not a replaceable global operator -and for optimization purposes calls to pairs of these functions can be -omitted if access to the allocation is optimized out, or could be replaced -with implementation provided buffer on the stack, or multiple allocation -calls can be merged into a single allocation. In C++ such optimizations -are normally allowed just for calls to such replaceable global operators -from @code{new} and @code{delete} expressions. +@cindex builtins for C++ @code{new} and @code{delete} operators +@cindex @code{new} and @code{delete} builtins + +GNU C++ provides builtins that are equivalent to calling +@code{::operator new} or @code{::operator delete} with the same arguments. +It is an error if the selected @code{::operator new} or +@code{::operator delete} overload is not a replaceable global operator. +For optimization purposes, calls to pairs of these +builtins can be omitted if access to the allocation is optimized out, +or could be replaced with an implementation-provided buffer on the stack, +or multiple allocation calls can be merged into a single allocation. +In C++ such optimizations are normally allowed just for calls to such +replaceable global operators from @code{new} and @code{delete} +expressions. @smallexample void foo () @{ @@ -15593,672 +17174,26 @@ void foo () @{ @} @end smallexample -@node Other Builtins -@section Other Built-in Functions Provided by GCC -@cindex built-in functions -@findex __builtin_iseqsig -@findex __builtin_isfinite -@findex __builtin_isnormal -@findex __builtin_isgreater -@findex __builtin_isgreaterequal -@findex __builtin_isunordered -@findex __builtin_speculation_safe_value -@findex _Exit -@findex _exit -@findex abort -@findex abs -@findex acos -@findex acosf -@findex acosh -@findex acoshf -@findex acoshl -@findex acosl -@findex alloca -@findex asin -@findex asinf -@findex asinh -@findex asinhf -@findex asinhl -@findex asinl -@findex atan -@findex atan2 -@findex atan2f -@findex atan2l -@findex atanf -@findex atanh -@findex atanhf -@findex atanhl -@findex atanl -@findex bcmp -@findex bzero -@findex cabs -@findex cabsf -@findex cabsl -@findex cacos -@findex cacosf -@findex cacosh -@findex cacoshf -@findex cacoshl -@findex cacosl -@findex calloc -@findex carg -@findex cargf -@findex cargl -@findex casin -@findex casinf -@findex casinh -@findex casinhf -@findex casinhl -@findex casinl -@findex catan -@findex catanf -@findex catanh -@findex catanhf -@findex catanhl -@findex catanl -@findex cbrt -@findex cbrtf -@findex cbrtl -@findex ccos -@findex ccosf -@findex ccosh -@findex ccoshf -@findex ccoshl -@findex ccosl -@findex ceil -@findex ceilf -@findex ceill -@findex cexp -@findex cexpf -@findex cexpl -@findex cimag -@findex cimagf -@findex cimagl -@findex clog -@findex clogf -@findex clogl -@findex clog10 -@findex clog10f -@findex clog10l -@findex conj -@findex conjf -@findex conjl -@findex copysign -@findex copysignf -@findex copysignl -@findex cos -@findex cosf -@findex cosh -@findex coshf -@findex coshl -@findex cosl -@findex cpow -@findex cpowf -@findex cpowl -@findex cproj -@findex cprojf -@findex cprojl -@findex creal -@findex crealf -@findex creall -@findex csin -@findex csinf -@findex csinh -@findex csinhf -@findex csinhl -@findex csinl -@findex csqrt -@findex csqrtf -@findex csqrtl -@findex ctan -@findex ctanf -@findex ctanh -@findex ctanhf -@findex ctanhl -@findex ctanl -@findex dcgettext -@findex dgettext -@findex drem -@findex dremf -@findex dreml -@findex erf -@findex erfc -@findex erfcf -@findex erfcl -@findex erff -@findex erfl -@findex exit -@findex exp -@findex exp10 -@findex exp10f -@findex exp10l -@findex exp2 -@findex exp2f -@findex exp2l -@findex expf -@findex expl -@findex expm1 -@findex expm1f -@findex expm1l -@findex fabs -@findex fabsf -@findex fabsl -@findex fdim -@findex fdimf -@findex fdiml -@findex ffs -@findex floor -@findex floorf -@findex floorl -@findex fma -@findex fmaf -@findex fmal -@findex fmax -@findex fmaxf -@findex fmaxl -@findex fmin -@findex fminf -@findex fminl -@findex fmod -@findex fmodf -@findex fmodl -@findex fprintf -@findex fprintf_unlocked -@findex fputs -@findex fputs_unlocked -@findex free -@findex frexp -@findex frexpf -@findex frexpl -@findex fscanf -@findex gamma -@findex gammaf -@findex gammal -@findex gamma_r -@findex gammaf_r -@findex gammal_r -@findex gettext -@findex hypot -@findex hypotf -@findex hypotl -@findex ilogb -@findex ilogbf -@findex ilogbl -@findex imaxabs -@findex index -@findex isalnum -@findex isalpha -@findex isascii -@findex isblank -@findex iscntrl -@findex isdigit -@findex isgraph -@findex islower -@findex isprint -@findex ispunct -@findex isspace -@findex isupper -@findex iswalnum -@findex iswalpha -@findex iswblank -@findex iswcntrl -@findex iswdigit -@findex iswgraph -@findex iswlower -@findex iswprint -@findex iswpunct -@findex iswspace -@findex iswupper -@findex iswxdigit -@findex isxdigit -@findex j0 -@findex j0f -@findex j0l -@findex j1 -@findex j1f -@findex j1l -@findex jn -@findex jnf -@findex jnl -@findex labs -@findex ldexp -@findex ldexpf -@findex ldexpl -@findex lgamma -@findex lgammaf -@findex lgammal -@findex lgamma_r -@findex lgammaf_r -@findex lgammal_r -@findex llabs -@findex llrint -@findex llrintf -@findex llrintl -@findex llround -@findex llroundf -@findex llroundl -@findex log -@findex log10 -@findex log10f -@findex log10l -@findex log1p -@findex log1pf -@findex log1pl -@findex log2 -@findex log2f -@findex log2l -@findex logb -@findex logbf -@findex logbl -@findex logf -@findex logl -@findex lrint -@findex lrintf -@findex lrintl -@findex lround -@findex lroundf -@findex lroundl -@findex malloc -@findex memchr -@findex memcmp -@findex memcpy -@findex mempcpy -@findex memset -@findex modf -@findex modff -@findex modfl -@findex nearbyint -@findex nearbyintf -@findex nearbyintl -@findex nextafter -@findex nextafterf -@findex nextafterl -@findex nexttoward -@findex nexttowardf -@findex nexttowardl -@findex pow -@findex pow10 -@findex pow10f -@findex pow10l -@findex powf -@findex powl -@findex printf -@findex printf_unlocked -@findex putchar -@findex puts -@findex realloc -@findex remainder -@findex remainderf -@findex remainderl -@findex remquo -@findex remquof -@findex remquol -@findex rindex -@findex rint -@findex rintf -@findex rintl -@findex round -@findex roundf -@findex roundl -@findex scalb -@findex scalbf -@findex scalbl -@findex scalbln -@findex scalblnf -@findex scalblnf -@findex scalbn -@findex scalbnf -@findex scanfnl -@findex signbit -@findex signbitf -@findex signbitl -@findex signbitd32 -@findex signbitd64 -@findex signbitd128 -@findex significand -@findex significandf -@findex significandl -@findex sin -@findex sincos -@findex sincosf -@findex sincosl -@findex sinf -@findex sinh -@findex sinhf -@findex sinhl -@findex sinl -@findex snprintf -@findex sprintf -@findex sqrt -@findex sqrtf -@findex sqrtl -@findex sscanf -@findex stpcpy -@findex stpncpy -@findex strcasecmp -@findex strcat -@findex strchr -@findex strcmp -@findex strcpy -@findex strcspn -@findex strdup -@findex strfmon -@findex strftime -@findex strlen -@findex strncasecmp -@findex strncat -@findex strncmp -@findex strncpy -@findex strndup -@findex strnlen -@findex strpbrk -@findex strrchr -@findex strspn -@findex strstr -@findex tan -@findex tanf -@findex tanh -@findex tanhf -@findex tanhl -@findex tanl -@findex tgamma -@findex tgammaf -@findex tgammal -@findex toascii -@findex tolower -@findex toupper -@findex towlower -@findex towupper -@findex trunc -@findex truncf -@findex truncl -@findex vfprintf -@findex vfscanf -@findex vprintf -@findex vscanf -@findex vsnprintf -@findex vsprintf -@findex vsscanf -@findex y0 -@findex y0f -@findex y0l -@findex y1 -@findex y1f -@findex y1l -@findex yn -@findex ynf -@findex ynl - -GCC provides a large number of built-in functions other than the ones -mentioned above. Some of these are for internal use in the processing -of exceptions or variable-length argument lists and are not -documented here because they may change from time to time; we do not -recommend general use of these functions. - -The remaining functions are provided for optimization purposes. - -With the exception of built-ins that have library equivalents such as -the standard C library functions discussed below, or that expand to -library calls, GCC built-in functions are always expanded inline and -thus do not have corresponding entry points and their address cannot -be obtained. Attempting to use them in an expression other than -a function call results in a compile-time error. - -@opindex fno-builtin -GCC includes built-in versions of many of the functions in the standard -C library. These functions come in two forms: one whose names start with -the @code{__builtin_} prefix, and the other without. Both forms have the -same type (including prototype), the same address (when their address is -taken), and the same meaning as the C library functions even if you specify -the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these -functions are only optimized in certain cases; if they are not optimized in -a particular case, a call to the library function is emitted. - -@opindex ansi -@opindex std -Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, -@option{-std=c99} or @option{-std=c11}), the functions -@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, -@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, -@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, -@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, -@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, -@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, -@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, -@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, -@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, -@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, -@code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl}, -@code{scalbf}, @code{scalbl}, @code{scalb}, -@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, -@code{signbitd64}, @code{signbitd128}, @code{significandf}, -@code{significandl}, @code{significand}, @code{sincosf}, -@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, -@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, -@code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l}, -@code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and -@code{yn} -may be handled as built-in functions. -All these functions have corresponding versions -prefixed with @code{__builtin_}, which may be used even in strict C90 -mode. - -The ISO C99 functions -@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, -@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, -@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, -@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, -@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, -@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, -@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, -@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, -@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, -@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, -@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, -@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, -@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, -@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, -@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, -@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, -@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, -@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, -@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, -@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, -@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, -@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, -@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, -@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, -@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, -@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, -@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, -@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, -@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, -@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, -@code{nextafterf}, @code{nextafterl}, @code{nextafter}, -@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, -@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, -@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, -@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, -@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, -@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, -@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, -@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} -are handled as built-in functions -except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). - -There are also built-in versions of the ISO C99 functions -@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, -@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, -@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, -@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, -@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, -@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, -@code{modfl}, @code{modff}, @code{powf}, @code{powl}, @code{sinf}, -@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, -@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} -that are recognized in any mode since ISO C90 reserves these names for -the purpose to which ISO C99 puts them. All these functions have -corresponding versions prefixed with @code{__builtin_}. - -There are also built-in functions @code{__builtin_fabsf@var{n}}, -@code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and -@code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3 -functions @code{fabsf@var{n}}, @code{fabsf@var{n}x}, -@code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported -types @code{_Float@var{n}} and @code{_Float@var{n}x}. - -There are also GNU extension functions @code{clog10}, @code{clog10f} and -@code{clog10l} which names are reserved by ISO C99 for future use. -All these functions have versions prefixed with @code{__builtin_}. - -The ISO C94 functions -@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, -@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, -@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and -@code{towupper} -are handled as built-in functions -except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). - -The ISO C90 functions -@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, -@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, -@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, -@code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf}, -@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, -@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, -@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, -@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, -@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, -@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, -@code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin}, -@code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, -@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, -@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, -@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, -@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} -are all recognized as built-in functions unless -@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} -is specified for an individual function). All of these functions have -corresponding versions prefixed with @code{__builtin_}. - -GCC provides built-in versions of the ISO C99 floating-point comparison -macros that avoid raising exceptions for unordered operands. They have -the same names as the standard macros ( @code{isgreater}, -@code{isgreaterequal}, @code{isless}, @code{islessequal}, -@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} -prefixed. We intend for a library implementor to be able to simply -@code{#define} each standard macro to its built-in equivalent. -In the same fashion, GCC provides @code{fpclassify}, @code{iseqsig}, -@code{isfinite}, @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins -used with @code{__builtin_} prefixed. The @code{isinf} and @code{isnan} -built-in functions appear both with and without the @code{__builtin_} prefix. -With @code{-ffinite-math-only} option the @code{isinf} and @code{isnan} -built-in functions will always return 0. - -GCC provides built-in versions of the ISO C99 floating-point rounding and -exceptions handling functions @code{fegetround}, @code{feclearexcept} and -@code{feraiseexcept}. They may not be available for all targets, and because -they need close interaction with libc internal values, they may not be available -for all target libcs, but in all cases they will gracefully fallback to libc -calls. These built-in functions appear both with and without the -@code{__builtin_} prefix. - -@defbuiltin{{void *} __builtin_alloca (size_t @var{size})} -The @code{__builtin_alloca} function must be called at block scope. -The function allocates an object @var{size} bytes large on the stack -of the calling function. The object is aligned on the default stack -alignment boundary for the target determined by the -@code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca} -function returns a pointer to the first byte of the allocated object. -The lifetime of the allocated object ends just before the calling -function returns to its caller. This is so even when -@code{__builtin_alloca} is called within a nested block. - -For example, the following function allocates eight objects of @code{n} -bytes each on the stack, storing a pointer to each in consecutive elements -of the array @code{a}. It then passes the array to function @code{g} -which can safely use the storage pointed to by each of the array elements. - -@smallexample -void f (unsigned n) -@{ - void *a [8]; - for (int i = 0; i != 8; ++i) - a [i] = __builtin_alloca (n); - - g (a, n); // @r{safe} -@} -@end smallexample - -Since the @code{__builtin_alloca} function doesn't validate its argument -it is the responsibility of its caller to make sure the argument doesn't -cause it to exceed the stack size limit. -The @code{__builtin_alloca} function is provided to make it possible to -allocate on the stack arrays of bytes with an upper bound that may be -computed at run time. Since C99 Variable Length Arrays offer -similar functionality under a portable, more convenient, and safer -interface they are recommended instead, in both C99 and C++ programs -where GCC provides them as an extension. -@xref{Variable Length}, for details. +These built-ins are only available in C++. +@defbuiltin{{void *} __builtin_operator_new (std::size_t @var{size}, ...)} +This is the built-in form of @code{operator new}. It accepts the same +argument forms as a ``usual allocation function'', as described in the +C++ standard. @enddefbuiltin -@defbuiltin{{void *} __builtin_alloca_with_align (size_t @var{size}, size_t @var{alignment})} -The @code{__builtin_alloca_with_align} function must be called at block -scope. The function allocates an object @var{size} bytes large on -the stack of the calling function. The allocated object is aligned on -the boundary specified by the argument @var{alignment} whose unit is given -in bits (not bytes). The @var{size} argument must be positive and not -exceed the stack size limit. The @var{alignment} argument must be a constant -integer expression that evaluates to a power of 2 greater than or equal to -@code{CHAR_BIT} and less than some unspecified maximum. Invocations -with other values are rejected with an error indicating the valid bounds. -The function returns a pointer to the first byte of the allocated object. -The lifetime of the allocated object ends at the end of the block in which -the function was called. The allocated storage is released no later than -just before the calling function returns to its caller, but may be released -at the end of the block in which the function was called. - -For example, in the following function the call to @code{g} is unsafe -because when @code{overalign} is non-zero, the space allocated by -@code{__builtin_alloca_with_align} may have been released at the end -of the @code{if} statement in which it was called. - -@smallexample -void f (unsigned n, bool overalign) -@{ - void *p; - if (overalign) - p = __builtin_alloca_with_align (n, 64 /* bits */); - else - p = __builtin_alloc (n); - - g (p, n); // @r{unsafe} -@} -@end smallexample +@defbuiltin{void __builtin_operator_delete (void * @var{ptr}, ...)} +This is the built-in form of @code{operator delete}. It accepts the same +argument forms as a ``usual deallocation function'', as described in the +C++ standard. +@enddefbuiltin -Since the @code{__builtin_alloca_with_align} function doesn't validate its -@var{size} argument it is the responsibility of its caller to make sure -the argument doesn't cause it to exceed the stack size limit. -The @code{__builtin_alloca_with_align} function is provided to make -it possible to allocate on the stack overaligned arrays of bytes with -an upper bound that may be computed at run time. Since C99 -Variable Length Arrays offer the same functionality under -a portable, more convenient, and safer interface they are recommended -instead, in both C99 and C++ programs where GCC provides them as -an extension. @xref{Variable Length}, for details. -@enddefbuiltin +@node Other Builtins +@section Other Built-in Functions Provided by GCC -@defbuiltin{{void *} __builtin_alloca_with_align_and_max (size_t @var{size}, size_t @var{alignment}, size_t @var{max_size})} -Similar to @code{__builtin_alloca_with_align} but takes an extra argument -specifying an upper bound for @var{size} in case its value cannot be computed -at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage} -and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer -expression, it has no effect on code generation and no attempt is made to -check its compatibility with @var{size}. +This section documents miscellaneous built-in functions available in GCC. -@enddefbuiltin @defbuiltin{bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute})} The @code{__builtin_has_attribute} function evaluates to an integer constant @@ -16444,18 +17379,6 @@ depending on the arguments' types. For example: @enddefbuiltin -@defbuiltin{@var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})} - -The @var{call_exp} expression must be a function call, and the -@var{pointer_exp} expression must be a pointer. The @var{pointer_exp} -is passed to the function call in the target's static chain location. -The result of builtin is the result of the function call. - -@emph{Note:} This builtin is only available for C@. -This builtin can be used to call Go closures from C. - -@enddefbuiltin - @defbuiltin{@var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})} You can use the built-in function @code{__builtin_choose_expr} to @@ -16988,17 +17911,6 @@ is evaluated if it includes side effects but no other code is generated and GCC does not issue a warning. @enddefbuiltin -@defbuiltin{{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type})} -Returns a constant size estimate of an object pointed to by @var{ptr}. -@xref{Object Size Checking}, for a detailed description of the function. -@enddefbuiltin - -@defbuiltin{{size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type})} -Similar to @code{__builtin_object_size} except that the return value -need not be a constant. @xref{Object Size Checking}, for a detailed -description of the function. -@enddefbuiltin - @defbuiltin{int __builtin_classify_type (@var{arg})} @defbuiltinx{int __builtin_classify_type (@var{type})} The @code{__builtin_classify_type} returns a small integer with a category @@ -17023,490 +17935,6 @@ to pointer. The last two comparisons will be true as they classify pointers in the second case and arrays in the last case. @enddefbuiltin -@defbuiltin{double __builtin_huge_val (void)} -Returns a positive infinity, if supported by the floating-point format, -else @code{DBL_MAX}. This function is suitable for implementing the -ISO C macro @code{HUGE_VAL}. -@enddefbuiltin - -@defbuiltin{float __builtin_huge_valf (void)} -Similar to @code{__builtin_huge_val}, except the return type is @code{float}. -@enddefbuiltin - -@defbuiltin{{long double} __builtin_huge_vall (void)} -Similar to @code{__builtin_huge_val}, except the return -type is @code{long double}. -@enddefbuiltin - -@defbuiltin{_Float@var{n} __builtin_huge_valf@var{n} (void)} -Similar to @code{__builtin_huge_val}, except the return type is -@code{_Float@var{n}}. -@enddefbuiltin - -@defbuiltin{_Float@var{n}x __builtin_huge_valf@var{n}x (void)} -Similar to @code{__builtin_huge_val}, except the return type is -@code{_Float@var{n}x}. -@enddefbuiltin - -@defbuiltin{int __builtin_fpclassify (int, int, int, int, int, ...)} -This built-in implements the C99 fpclassify functionality. The first -five int arguments should be the target library's notion of the -possible FP classes and are used for return values. They must be -constant values and they must appear in this order: @code{FP_NAN}, -@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and -@code{FP_ZERO}. The ellipsis is for exactly one floating-point value -to classify. GCC treats the last argument as type-generic, which -means it does not do default promotion from float to double. -@enddefbuiltin - -@defbuiltin{double __builtin_inf (void)} -Similar to @code{__builtin_huge_val}, except a warning is generated -if the target floating-point format does not support infinities. -@enddefbuiltin - -@defbuiltin{_Decimal32 __builtin_infd32 (void)} -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. -@enddefbuiltin - -@defbuiltin{_Decimal64 __builtin_infd64 (void)} -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. -@enddefbuiltin - -@defbuiltin{_Decimal128 __builtin_infd128 (void)} -Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. -@enddefbuiltin - -@defbuiltin{float __builtin_inff (void)} -Similar to @code{__builtin_inf}, except the return type is @code{float}. -This function is suitable for implementing the ISO C99 macro @code{INFINITY}. -@enddefbuiltin - -@defbuiltin{{long double} __builtin_infl (void)} -Similar to @code{__builtin_inf}, except the return -type is @code{long double}. -@enddefbuiltin - -@defbuiltin{_Float@var{n} __builtin_inff@var{n} (void)} -Similar to @code{__builtin_inf}, except the return -type is @code{_Float@var{n}}. -@enddefbuiltin - -@defbuiltin{_Float@var{n} __builtin_inff@var{n}x (void)} -Similar to @code{__builtin_inf}, except the return -type is @code{_Float@var{n}x}. -@enddefbuiltin - -@defbuiltin{int __builtin_isinf_sign (...)} -Similar to @code{isinf}, except the return value is -1 for -an argument of @code{-Inf} and 1 for an argument of @code{+Inf}. -Note while the parameter list is an -ellipsis, this function only accepts exactly one floating-point -argument. GCC treats this parameter as type-generic, which means it -does not do default promotion from float to double. -@enddefbuiltin - -@defbuiltin{double __builtin_nan (const char *@var{str})} -This is an implementation of the ISO C99 function @code{nan}. - -Since ISO C99 defines this function in terms of @code{strtod}, which we -do not implement, a description of the parsing is in order. The string -is parsed as by @code{strtol}; that is, the base is recognized by -leading @samp{0} or @samp{0x} prefixes. The number parsed is placed -in the significand such that the least significant bit of the number -is at the least significant bit of the significand. The number is -truncated to fit the significand field provided. The significand is -forced to be a quiet NaN@. - -This function, if given a string literal all of which would have been -consumed by @code{strtol}, is evaluated early enough that it is considered a -compile-time constant. -@enddefbuiltin - -@defbuiltin{_Decimal32 __builtin_nand32 (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. -@enddefbuiltin - -@defbuiltin{_Decimal64 __builtin_nand64 (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. -@enddefbuiltin - -@defbuiltin{_Decimal128 __builtin_nand128 (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. -@enddefbuiltin - -@defbuiltin{float __builtin_nanf (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{float}. -@enddefbuiltin - -@defbuiltin{{long double} __builtin_nanl (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is @code{long double}. -@enddefbuiltin - -@defbuiltin{_Float@var{n} __builtin_nanf@var{n} (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is -@code{_Float@var{n}}. -@enddefbuiltin - -@defbuiltin{_Float@var{n}x __builtin_nanf@var{n}x (const char *@var{str})} -Similar to @code{__builtin_nan}, except the return type is -@code{_Float@var{n}x}. -@enddefbuiltin - -@defbuiltin{double __builtin_nans (const char *@var{str})} -Similar to @code{__builtin_nan}, except the significand is forced -to be a signaling NaN@. The @code{nans} function is proposed by -@uref{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. -@enddefbuiltin - -@defbuiltin{_Decimal32 __builtin_nansd32 (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}. -@enddefbuiltin - -@defbuiltin{_Decimal64 __builtin_nansd64 (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}. -@enddefbuiltin - -@defbuiltin{_Decimal128 __builtin_nansd128 (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}. -@enddefbuiltin - -@defbuiltin{float __builtin_nansf (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{float}. -@enddefbuiltin - -@defbuiltin{{long double} __builtin_nansl (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is @code{long double}. -@enddefbuiltin - -@defbuiltin{_Float@var{n} __builtin_nansf@var{n} (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is -@code{_Float@var{n}}. -@enddefbuiltin - -@defbuiltin{_Float@var{n}x __builtin_nansf@var{n}x (const char *@var{str})} -Similar to @code{__builtin_nans}, except the return type is -@code{_Float@var{n}x}. -@enddefbuiltin - -@defbuiltin{int __builtin_issignaling (...)} -Return non-zero if the argument is a signaling NaN and zero otherwise. -Note while the parameter list is an -ellipsis, this function only accepts exactly one floating-point -argument. GCC treats this parameter as type-generic, which means it -does not do default promotion from float to double. -This built-in function can work even without the non-default -@code{-fsignaling-nans} option, although if a signaling NaN is computed, -stored or passed as argument to some function other than this built-in -in the current translation unit, it is safer to use @code{-fsignaling-nans}. -With @code{-ffinite-math-only} option this built-in function will always -return 0. -@enddefbuiltin - -@defbuiltin{int __builtin_ffs (int @var{x})} -Returns one plus the index of the least significant 1-bit of @var{x}, or -if @var{x} is zero, returns zero. -@enddefbuiltin - -@defbuiltin{int __builtin_clz (unsigned int @var{x})} -Returns the number of leading 0-bits in @var{x}, starting at the most -significant bit position. If @var{x} is 0, the result is undefined. -@enddefbuiltin - -@defbuiltin{int __builtin_ctz (unsigned int @var{x})} -Returns the number of trailing 0-bits in @var{x}, starting at the least -significant bit position. If @var{x} is 0, the result is undefined. -@enddefbuiltin - -@defbuiltin{int __builtin_clrsb (int @var{x})} -Returns the number of leading redundant sign bits in @var{x}, i.e.@: the -number of bits following the most significant bit that are identical -to it. There are no special cases for 0 or other values. -@enddefbuiltin - -@defbuiltin{int __builtin_popcount (unsigned int @var{x})} -Returns the number of 1-bits in @var{x}. -@enddefbuiltin - -@defbuiltin{int __builtin_parity (unsigned int @var{x})} -Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} -modulo 2. -@enddefbuiltin - -@defbuiltin{int __builtin_ffsl (long)} -Similar to @code{__builtin_ffs}, except the argument type is -@code{long}. -@enddefbuiltin - -@defbuiltin{int __builtin_clzl (unsigned long)} -Similar to @code{__builtin_clz}, except the argument type is -@code{unsigned long}. -@enddefbuiltin - -@defbuiltin{int __builtin_ctzl (unsigned long)} -Similar to @code{__builtin_ctz}, except the argument type is -@code{unsigned long}. -@enddefbuiltin - -@defbuiltin{int __builtin_clrsbl (long)} -Similar to @code{__builtin_clrsb}, except the argument type is -@code{long}. -@enddefbuiltin - -@defbuiltin{int __builtin_popcountl (unsigned long)} -Similar to @code{__builtin_popcount}, except the argument type is -@code{unsigned long}. -@enddefbuiltin - -@defbuiltin{int __builtin_parityl (unsigned long)} -Similar to @code{__builtin_parity}, except the argument type is -@code{unsigned long}. -@enddefbuiltin - -@defbuiltin{int __builtin_ffsll (long long)} -Similar to @code{__builtin_ffs}, except the argument type is -@code{long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_clzll (unsigned long long)} -Similar to @code{__builtin_clz}, except the argument type is -@code{unsigned long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_ctzll (unsigned long long)} -Similar to @code{__builtin_ctz}, except the argument type is -@code{unsigned long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_clrsbll (long long)} -Similar to @code{__builtin_clrsb}, except the argument type is -@code{long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_popcountll (unsigned long long)} -Similar to @code{__builtin_popcount}, except the argument type is -@code{unsigned long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_parityll (unsigned long long)} -Similar to @code{__builtin_parity}, except the argument type is -@code{unsigned long long}. -@enddefbuiltin - -@defbuiltin{int __builtin_ffsg (...)} -Similar to @code{__builtin_ffs}, except the argument is type-generic -signed integer (standard, extended or bit-precise). No integral argument -promotions are performed on the argument. -@enddefbuiltin - -@defbuiltin{int __builtin_clzg (...)} -Similar to @code{__builtin_clz}, except the argument is type-generic -unsigned integer (standard, extended or bit-precise) and there is -optional second argument with int type. No integral argument promotions -are performed on the first argument. If two arguments are specified, -and first argument is 0, the result is the second argument. If only -one argument is specified and it is 0, the result is undefined. -@enddefbuiltin - -@defbuiltin{int __builtin_ctzg (...)} -Similar to @code{__builtin_ctz}, except the argument is type-generic -unsigned integer (standard, extended or bit-precise) and there is -optional second argument with int type. No integral argument promotions -are performed on the first argument. If two arguments are specified, -and first argument is 0, the result is the second argument. If only -one argument is specified and it is 0, the result is undefined. -@enddefbuiltin - -@defbuiltin{int __builtin_clrsbg (...)} -Similar to @code{__builtin_clrsb}, except the argument is type-generic -signed integer (standard, extended or bit-precise). No integral argument -promotions are performed on the argument. -@enddefbuiltin - -@defbuiltin{int __builtin_popcountg (...)} -Similar to @code{__builtin_popcount}, except the argument is type-generic -unsigned integer (standard, extended or bit-precise). No integral argument -promotions are performed on the argument. -@enddefbuiltin - -@defbuiltin{int __builtin_parityg (...)} -Similar to @code{__builtin_parity}, except the argument is type-generic -unsigned integer (standard, extended or bit-precise). No integral argument -promotions are performed on the argument. -@enddefbuiltin - -@defbuiltin{@var{type} __builtin_stdc_bit_ceil (@var{type} @var{arg})} -The @code{__builtin_stdc_bit_ceil} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{@var{arg} <= 1 ? (@var{type}) 1 -: (@var{type}) 2 << (@var{prec} - 1 - __builtin_clzg ((@var{type}) (@var{arg} - 1)))} -where @var{prec} is bit width of @var{type}, except that side-effects -in @var{arg} are evaluated just once. -@enddefbuiltin - -@defbuiltin{@var{type} __builtin_stdc_bit_floor (@var{type} @var{arg})} -The @code{__builtin_stdc_bit_floor} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{@var{arg} == 0 ? (@var{type}) 0 -: (@var{type}) 1 << (@var{prec} - 1 - __builtin_clzg (@var{arg}))} -where @var{prec} is bit width of @var{type}, except that side-effects -in @var{arg} are evaluated just once. -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_bit_width (@var{type} @var{arg})} -The @code{__builtin_stdc_bit_width} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) (@var{prec} - __builtin_clzg (@var{arg}, @var{prec}))} -where @var{prec} is bit width of @var{type}. -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_count_ones (@var{type} @var{arg})} -The @code{__builtin_stdc_count_ones} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_popcountg (@var{arg})} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_count_zeros (@var{type} @var{arg})} -The @code{__builtin_stdc_count_zeros} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_popcountg ((@var{type}) ~@var{arg})} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_first_leading_one (@var{type} @var{arg})} -The @code{__builtin_stdc_first_leading_one} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{__builtin_clzg (@var{arg}, -1) + 1U} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_first_leading_zero (@var{type} @var{arg})} -The @code{__builtin_stdc_first_leading_zero} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{__builtin_clzg ((@var{type}) ~@var{arg}, -1) + 1U} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_first_trailing_one (@var{type} @var{arg})} -The @code{__builtin_stdc_first_trailing_one} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{__builtin_ctzg (@var{arg}, -1) + 1U} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_first_trailing_zero (@var{type} @var{arg})} -The @code{__builtin_stdc_first_trailing_zero} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{__builtin_ctzg ((@var{type}) ~@var{arg}, -1) + 1U} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_has_single_bit (@var{type} @var{arg})} -The @code{__builtin_stdc_has_single_bit} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(_Bool) (__builtin_popcountg (@var{arg}) == 1)} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_leading_ones (@var{type} @var{arg})} -The @code{__builtin_stdc_leading_ones} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_clzg ((@var{type}) ~@var{arg}, @var{prec})} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_leading_zeros (@var{type} @var{arg})} -The @code{__builtin_stdc_leading_zeros} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_clzg (@var{arg}, @var{prec})} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_trailing_ones (@var{type} @var{arg})} -The @code{__builtin_stdc_trailing_ones} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_ctzg ((@var{type}) ~@var{arg}, @var{prec})} -@enddefbuiltin - -@defbuiltin{{unsigned int} __builtin_stdc_trailing_zeros (@var{type} @var{arg})} -The @code{__builtin_stdc_trailing_zeros} function is available only -in C. It is type-generic, the argument can be any unsigned integer -(standard, extended or bit-precise). No integral argument promotions are -performed on the argument. It is equivalent to -@code{(unsigned int) __builtin_ctzg (@var{arg}, @var{prec})} -@enddefbuiltin - -@defbuiltin{@var{type1} __builtin_stdc_rotate_left (@var{type1} @var{arg1}, @var{type2} @var{arg2})} -The @code{__builtin_stdc_rotate_left} function is available only -in C. It is type-generic, the first argument can be any unsigned integer -(standard, extended or bit-precise) and second argument any signed or -unsigned integer or @code{char}. No integral argument promotions are -performed on the arguments. It is equivalent to -@code{(@var{type1}) ((@var{arg1} << (@var{arg2} % @var{prec})) -| (@var{arg1} >> ((-(unsigned @var{type2}) @var{arg2}) % @var{prec})))} -where @var{prec} is bit width of @var{type1}, except that side-effects -in @var{arg1} and @var{arg2} are evaluated just once. The behavior is -undefined if @var{arg2} is negative. -@enddefbuiltin - -@defbuiltin{@var{type1} __builtin_stdc_rotate_right (@var{type1} @var{arg1}, @var{type2} @var{arg2})} -The @code{__builtin_stdc_rotate_right} function is available only -in C. It is type-generic, the first argument can be any unsigned integer -(standard, extended or bit-precise) and second argument any signed or -unsigned integer or @code{char}. No integral argument promotions are -performed on the arguments. It is equivalent to -@code{(@var{type1}) ((@var{arg1} >> (@var{arg2} % @var{prec})) -| (@var{arg1} << ((-(unsigned @var{type2}) @var{arg2}) % @var{prec})))} -where @var{prec} is bit width of @var{type1}, except that side-effects -in @var{arg1} and @var{arg2} are evaluated just once. The behavior is -undefined if @var{arg2} is negative. -@enddefbuiltin - -@defbuiltin{double __builtin_powi (double, int)} -@defbuiltinx{float __builtin_powif (float, int)} -@defbuiltinx{{long double} __builtin_powil (long double, int)} -Returns the first argument raised to the power of the second. Unlike the -@code{pow} function no guarantees about precision and rounding are made. -@enddefbuiltin - -@defbuiltin{uint16_t __builtin_bswap16 (uint16_t @var{x})} -Returns @var{x} with the order of the bytes reversed; for example, -@code{0xabcd} becomes @code{0xcdab}. Byte here always means -exactly 8 bits. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_bswap32 (uint32_t @var{x})} -Similar to @code{__builtin_bswap16}, except the argument and return types -are 32-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_bswap64 (uint64_t @var{x})} -Similar to @code{__builtin_bswap32}, except the argument and return types -are 64-bit. -@enddefbuiltin - -@defbuiltin{uint128_t __builtin_bswap128 (uint128_t @var{x})} -Similar to @code{__builtin_bswap64}, except the argument and return types -are 128-bit. Only supported on targets when 128-bit types are supported. -@enddefbuiltin - @defbuiltin{Pmode __builtin_extend_pointer (void * @var{x})} On targets where the user visible pointer size is smaller than the size @@ -17526,114 +17954,6 @@ Returns the openacc gang, worker or vector size depending on whether @var{x} is 0, 1 or 2. @enddefbuiltin -@defbuiltin{uint8_t __builtin_rev_crc8_data8 (uint8_t @var{crc}, uint8_t @var{data}, uint8_t @var{poly})} -Returns the calculated 8-bit bit-reversed CRC using the initial CRC (8-bit), -data (8-bit) and the polynomial (8-bit). -@var{crc} is the initial CRC, @var{data} is the data and -@var{poly} is the polynomial without leading 1. -Table-based or clmul-based CRC may be used for the -calculation, depending on the target architecture. -@enddefbuiltin - -@defbuiltin{uint16_t __builtin_rev_crc16_data16 (uint16_t @var{crc}, uint16_t @var{data}, uint16_t @var{poly})} -Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types -are 16-bit. -@enddefbuiltin - -@defbuiltin{uint16_t __builtin_rev_crc16_data8 (uint16_t @var{crc}, uint8_t @var{data}, uint16_t @var{poly})} -Similar to @code{__builtin_rev_crc16_data16}, except the @var{data} argument -type is 8-bit. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_rev_crc32_data32 (uint32_t @var{crc}, uint32_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types -are 32-bit and for the CRC calculation may be also used crc* machine instruction -depending on the target and the polynomial. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_rev_crc32_data8 (uint32_t @var{crc}, uint8_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_rev_crc32_data32}, except the @var{data} argument -type is 8-bit. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_rev_crc32_data16 (uint32_t @var{crc}, uint16_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_rev_crc32_data32}, except the @var{data} argument -type is 16-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_rev_crc64_data64 (uint64_t @var{crc}, uint64_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_rev_crc8_data8}, except the argument and return types -are 64-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_rev_crc64_data8 (uint64_t @var{crc}, uint8_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type -is 8-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_rev_crc64_data16 (uint64_t @var{crc}, uint16_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type -is 16-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_rev_crc64_data32 (uint64_t @var{crc}, uint32_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_rev_crc64_data64}, except the @var{data} argument type -is 32-bit. -@enddefbuiltin - -@defbuiltin{uint8_t __builtin_crc8_data8 (uint8_t @var{crc}, uint8_t @var{data}, uint8_t @var{poly})} -Returns the calculated 8-bit bit-forward CRC using the initial CRC (8-bit), -data (8-bit) and the polynomial (8-bit). -@var{crc} is the initial CRC, @var{data} is the data and -@var{poly} is the polynomial without leading 1. -Table-based or clmul-based CRC may be used for the -calculation, depending on the target architecture. -@enddefbuiltin - -@defbuiltin{uint16_t __builtin_crc16_data16 (uint16_t @var{crc}, uint16_t @var{data}, uint16_t @var{poly})} -Similar to @code{__builtin_crc8_data8}, except the argument and return types -are 16-bit. -@enddefbuiltin - -@defbuiltin{uint16_t __builtin_crc16_data8 (uint16_t @var{crc}, uint8_t @var{data}, uint16_t @var{poly})} -Similar to @code{__builtin_crc16_data16}, except the @var{data} argument type -is 8-bit. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_crc32_data32 (uint32_t @var{crc}, uint32_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_crc8_data8}, except the argument and return types -are 32-bit. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_crc32_data8 (uint32_t @var{crc}, uint8_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_crc32_data32}, except the @var{data} argument type -is 8-bit. -@enddefbuiltin - -@defbuiltin{uint32_t __builtin_crc32_data16 (uint32_t @var{crc}, uint16_t @var{data}, uint32_t @var{poly})} -Similar to @code{__builtin_crc32_data32}, except the @var{data} argument type -is 16-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_crc64_data64 (uint64_t @var{crc}, uint64_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_crc8_data8}, except the argument and return types -are 64-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_crc64_data8 (uint64_t @var{crc}, uint8_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type -is 8-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_crc64_data16 (uint64_t @var{crc}, uint16_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type -is 16-bit. -@enddefbuiltin - -@defbuiltin{uint64_t __builtin_crc64_data32 (uint64_t @var{crc}, uint32_t @var{data}, uint64_t @var{poly})} -Similar to @code{__builtin_crc64_data64}, except the @var{data} argument type -is 32-bit. -@enddefbuiltin @node Target Builtins @section Built-in Functions Specific to Particular Target Machines @@ -29555,43 +29875,6 @@ The shadow stack unwind code looks like: This code runs unconditionally on all 64-bit processors. For 32-bit processors the code runs on those that support multi-byte NOP instructions. -@node Target Format Checks -@section Format Checks Specific to Particular Target Machines - -For some target machines, GCC supports additional options to the -format attribute -(@pxref{Function Attributes,,Declaring Attributes of Functions}). - -@menu -* Solaris Format Checks:: -* Darwin Format Checks:: -@end menu - -@node Solaris Format Checks -@subsection Solaris Format Checks - -Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format -check. @code{cmn_err} accepts a subset of the standard @code{printf} -conversions, and the two-argument @code{%b} conversion for displaying -bit-fields. See the Solaris man page for @code{cmn_err} for more information. - -@node Darwin Format Checks -@subsection Darwin Format Checks - -In addition to the full set of format archetypes (attribute format style -arguments such as @code{printf}, @code{scanf}, @code{strftime}, and -@code{strfmon}), Darwin targets also support the @code{CFString} (or -@code{__CFString__}) archetype in the @code{format} attribute. -Declarations with this archetype are parsed for correct syntax -and argument types. However, parsing of the format string itself and -validating arguments against it in calls to such functions is currently -not performed. - -Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may -also be used as format arguments. Note that the relevant headers are only likely to be -available on Darwin (OSX) installations. On such installations, the XCode and system -documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and -associated functions. @node C++ Extensions @chapter Extensions to the C++ Language @@ -30120,11 +30403,11 @@ variable or function or moving it into a tagged inline namespace. In Standard C++, objects defined at namespace scope are guaranteed to be initialized in an order in strict accordance with that of their definitions @emph{in a given translation unit}. No guarantee is made for initializations -across translation units. However, GNU C++ allows users to control the +across translation units. However, GNU C++ allows you to control the order of initialization of objects defined at namespace scope with the @code{init_priority} attribute by specifying a relative @var{priority}, -a constant integral expression currently bounded between 101 and 65535 -inclusive. Lower numbers indicate a higher priority. +with the same meaning as for the @code{constructor} attribute +(@pxref{Common Function Attributes}). In the following example, @code{A} would normally be created before @code{B}, but the @code{init_priority} attribute reverses that order: @@ -30138,6 +30421,11 @@ Some_Class B __attribute__ ((init_priority (543))); Note that the particular values of @var{priority} do not matter; only their relative ordering. +As with the @var{priority} argument to the @code{constructor} and +@code{destructor} attributes, a few targets do not support the +@code{init_priority} attribute. In that case the attribute is rejected +with an error rather than ignored. + @cindex @code{no_dangling} type attribute @cindex @code{no_dangling} function attribute @item no_dangling diff --git a/gcc/doc/gcc.texi b/gcc/doc/gcc.texi index ba26bf8..3b7b289 100644 --- a/gcc/doc/gcc.texi +++ b/gcc/doc/gcc.texi @@ -144,6 +144,7 @@ Introduction, gccint, GNU Compiler Collection (GCC) Internals}. * C Implementation:: How GCC implements the ISO C specification. * C++ Implementation:: How GCC implements the ISO C++ specification. * C Extensions:: GNU extensions to the C language family. +* Built-in Functions:: Library functions built in to GCC. * C++ Extensions:: GNU extensions to the C++ language. * Objective-C:: GNU Objective-C runtime features. * Compatibility:: Binary Compatibility diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 2397e5d..4be80a7 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -211,8 +211,7 @@ in the following sections. @item C++ Language Options @xref{C++ Dialect Options,,Options Controlling C++ Dialect}. @gccoptlist{-fabi-version=@var{n} -fno-access-control --faligned-new=@var{n} -fargs-in-order=@var{n} --fno-assume-sane-operators-new-delete +-faligned-new=@var{n} -fno-assume-sane-operators-new-delete -fchar8_t -fcheck-new -fconcepts -fconstexpr-depth=@var{n} -fconstexpr-cache-depth=@var{n} -fconstexpr-loop-limit=@var{n} -fconstexpr-ops-limit=@var{n} @@ -235,6 +234,7 @@ in the following sections. -fno-optional-diags -fno-pretty-templates -frange-for-ext-temps -fno-rtti -fsized-deallocation +-fstrong-eval-order@r{[}=@var{kind}@r{]} -ftemplate-backtrace-limit=@var{n} -ftemplate-depth=@var{n} -fno-threadsafe-statics -fuse-cxa-atexit @@ -274,7 +274,7 @@ in the following sections. -Wsuggest-final-types -Wsuggest-override -Wno-template-body -Wno-template-id-cdtor -Wtemplate-names-tu-local -Wno-terminate -Wno-vexing-parse -Wvirtual-inheritance --Wno-virtual-move-assign -Wvolatile -Wzero-as-null-pointer-constant} +-Wno-virtual-move-assign -Wvolatile} @item Objective-C and Objective-C++ Language Options @xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling @@ -394,7 +394,8 @@ Objective-C and Objective-C++ Dialects}. -Wmemset-elt-size -Wmemset-transposed-args -Wmisleading-indentation -Wmissing-attributes -Wmissing-braces -Wmissing-field-initializers -Wmissing-format-attribute --Wmissing-include-dirs -Wmissing-noreturn -Wno-missing-profile +-Wmissing-include-dirs -Wmissing-noreturn -Wmusttail-local-addr +-Wmaybe-musttail-local-addr -Wno-missing-profile -Wno-multichar -Wmultistatement-macros -Wnonnull -Wnonnull-compare -Wnormalized=@r{[}none@r{|}id@r{|}nfc@r{|}nfkc@r{]} -Wnull-dereference -Wno-odr @@ -405,7 +406,9 @@ Objective-C and Objective-C++ Dialects}. -Wparentheses -Wno-pedantic-ms-format -Wpointer-arith -Wno-pointer-compare -Wno-pointer-to-int-cast -Wno-pragmas -Wno-pragma-once-outside-header -Wno-prio-ctor-dtor --Wredundant-decls -Wrestrict -Wno-return-local-addr -Wreturn-type +-Wno-psabi +-Wredundant-decls -Wrestrict +-Wno-return-local-addr -Wreturn-type -Wno-scalar-storage-order -Wsequence-point -Wshadow -Wshadow=global -Wshadow=local -Wshadow=compatible-local -Wno-shadow-ivar @@ -442,6 +445,7 @@ Objective-C and Objective-C++ Dialects}. -Wvla -Wvla-larger-than=@var{byte-size} -Wno-vla-larger-than -Wvolatile-register-var -Wwrite-strings -Wno-xor-used-as-pow +-Wzero-as-null-pointer-constant -Wzero-length-bounds} @item Static Analyzer Options @@ -638,8 +642,8 @@ Objective-C and Objective-C++ Dialects}. -fsplit-wide-types -fsplit-wide-types-early -fssa-backprop -fssa-phiopt -fstdarg-opt -fstore-merging -fstrict-aliasing -fipa-strict-aliasing -fthread-jumps -ftracer -ftree-bit-ccp --ftree-builtin-call-dce -ftree-ccp -ftree-ch --ftree-coalesce-vars -ftree-copy-prop -ftree-dce -ftree-dominator-opts +-ftree-builtin-call-dce -ftree-ccp -ftree-ch -ftree-coalesce-vars +-ftree-copy-prop -ftree-cselim -ftree-dce -ftree-dominator-opts -ftree-dse -ftree-forwprop -ftree-fre -fcode-hoisting -ftree-loop-if-convert -ftree-loop-im -ftree-phiprop -ftree-loop-distribution -ftree-loop-distribute-patterns @@ -671,7 +675,7 @@ Objective-C and Objective-C++ Dialects}. -fsanitize=@var{style} -fsanitize-recover -fsanitize-recover=@var{style} -fsanitize-trap -fsanitize-trap=@var{style} -fasan-shadow-offset=@var{number} -fsanitize-sections=@var{s1},@var{s2},... --fsanitize-undefined-trap-on-error -fbounds-check +-fsanitize-undefined-trap-on-error -fbounds-check -fcf-protection -fcf-protection=@r{[}full@r{|}branch@r{|}return@r{|}none@r{|}check@r{]} -fharden-compares -fharden-conditional-branches -fhardened -fharden-control-flow-redundancy -fhardcfr-skip-leaf @@ -991,6 +995,7 @@ Objective-C and Objective-C++ Dialects}. -mtrap-precision=@var{mode} -mbuild-constants -mcpu=@var{cpu-type} -mtune=@var{cpu-type} -mbwx -mmax -mfix -mcix +-msafe-bwa -msafe-partial -mfloat-vax -mfloat-ieee -mexplicit-relocs -msmall-data -mlarge-data -msmall-text -mlarge-text @@ -2613,8 +2618,8 @@ ISO C23. @item -fno-builtin @itemx -fno-builtin-@var{function} Don't recognize built-in functions that do not begin with -@samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in -functions provided by GCC}, for details of the functions affected, +@samp{__builtin_} as prefix. @xref{Library Builtins}, +for details of the functions affected, including those which are not built-in functions when @option{-ansi} or @option{-std} options for strict ISO C conformance are used because they do not have an ISO standard meaning. @@ -3576,12 +3581,19 @@ type. @opindex fstrong-eval-order @item -fstrong-eval-order +@itemx -fstrong-eval-order=@var{kind} Evaluate member access, array subscripting, and shift expressions in left-to-right order, and evaluate assignment in right-to-left order, -as adopted for C++17. Enabled by default with @option{-std=c++17}. +as adopted for C++17. @option{-fstrong-eval-order} is equivalent to +@option{-fstrong-eval-order=all}, +and is enabled by default with @option{-std=c++17} or later. + @option{-fstrong-eval-order=some} enables just the ordering of member -access and shift expressions, and is the default without -@option{-std=c++17}. +access and shift expressions, and is the default for C++ dialects prior to +C++17. + +@option{-fstrong-eval-order=none} is equivalent to +@option{-fno-strong-eval-order}. @opindex ftemplate-backtrace-limit @item -ftemplate-backtrace-limit=@var{n} @@ -4689,11 +4701,6 @@ non-class type, @code{volatile}-qualified function return type, Enabled by default with @option{-std=c++20}. Before @option{-std=c++20}, enabled with explicit @option{-Wdeprecated}. -@opindex Wzero-as-null-pointer-constant -@opindex Wno-zero-as-null-pointer-constant -@item -Wzero-as-null-pointer-constant -Warn when a literal @samp{0} is used as null pointer constant. - @opindex Waligned-new @opindex Wno-aligned-new @item -Waligned-new @@ -6147,12 +6154,12 @@ Inhibit all warning messages. @opindex Werror @opindex Wno-error @item -Werror -Make all warnings into errors. +Turn all warnings into errors. @opindex Werror= @opindex Wno-error= @item -Werror= -Make the specified warning into an error. The specifier for a warning +Turn the specified warning into an error. The specifier for a warning is appended; for example @option{-Werror=switch} turns the warnings controlled by @option{-Wswitch} into errors. This switch takes a negative form, to be used to negate @option{-Werror} for specific @@ -6180,10 +6187,11 @@ messages. @end table You can request many specific warnings with options beginning with -@samp{-W}, for example @option{-Wimplicit} to request warnings on -implicit declarations. Each of these specific warning options also -has a negative form beginning @samp{-Wno-} to turn off warnings; for -example, @option{-Wno-implicit}. This manual lists only one of the +@samp{-W}, for example @option{-Wunused-variable} to request warnings on +declarations of variables that are never used. +Each of these specific warning options also +has a negative form beginning with @samp{-Wno-} to turn off warnings; for +example, @option{-Wno-unused-variable}. This manual lists only one of the two forms, whichever is not the default. For further language-specific options also refer to @ref{C++ Dialect Options} and @ref{Objective-C and Objective-C++ Dialect Options}. @@ -6192,15 +6200,15 @@ Additional warnings can be produced by enabling the static analyzer; Some options, such as @option{-Wall} and @option{-Wextra}, turn on other options, such as @option{-Wunused}, which may turn on further options, -such as @option{-Wunused-value}. The combined effect of positive and +such as @option{-Wunused-variable}. The combined effect of positive and negative forms is that more specific options have priority over less -specific ones, independently of their position in the command-line. For +specific ones, independently of their position in the command line. For options of the same specificity, the last one takes effect. Options enabled or disabled via pragmas (@pxref{Diagnostic Pragmas}) take effect -as if they appeared at the end of the command-line. +as if they appeared at the end of the command line. When an unrecognized warning option is requested (e.g., -@option{-Wunknown-warning}), GCC emits a diagnostic stating +@option{-Wunknown-warning}), GCC gives an error stating that the option is not recognized. However, if the @option{-Wno-} form is used, the behavior is slightly different: no diagnostic is produced for @option{-Wno-unknown-warning} unless other diagnostics @@ -6209,11 +6217,11 @@ with old compilers, but if something goes wrong, the compiler warns that an unrecognized option is present. The effectiveness of some warnings depends on optimizations also being -enabled. For example @option{-Wsuggest-final-types} is more effective -with link-time optimization and some instances of other warnings may +enabled. For example, @option{-Wsuggest-final-types} is more effective +with link-time optimization. Some other warnings may not be issued at all unless optimization is enabled. While optimization -in general improves the efficacy of control and data flow sensitive -warnings, in some cases it may also cause false positives. +in general improves the efficacy of warnings about control and data-flow +problems, in some cases it may also cause false positives. @table @gcctabopt @opindex pedantic @@ -6499,7 +6507,8 @@ of a derived class. Warn about code affected by ABI changes. This includes code that may not be compatible with the vendor-neutral C++ ABI as well as the psABI -for the particular target. +for the particular target. The latter warnings are also controlled +separately by @option{-Wpsabi}, which is implied by @option{-Wabi}. Since G++ now defaults to updating the ABI with each major release, normally @option{-Wabi} warns only about C++ ABI compatibility @@ -6602,27 +6611,21 @@ This was fixed in @option{-fabi-version=10}, the default for GCC 6.1. @end itemize -This option also enables warnings about psABI-related changes. -The known psABI changes at this point include: +@opindex Wpsabi +@opindex Wno-psabi +@item -Wpsabi @r{(C, Objective-C, C++ and Objective-C++ only)} -@itemize @bullet +@option{-Wpsabi} enables warnings about processor-specific ABI +changes, such as changes in alignment requirements or how function +arguments are passed. On several targets, including AArch64, ARM, +x86, MIPS, RS6000/PowerPC, and S/390, these details have changed +between different versions of GCC and/or different versions of the C +or C++ language standards in ways that affect binary compatibility of +compiled code. With @option{-Wpsabi}, GCC can detect potentially +incompatible usages and warn you about them. -@item -For SysV/x86-64, unions with @code{long double} members are -passed in memory as specified in psABI. Prior to GCC 4.4, this was not -the case. For example: - -@smallexample -union U @{ - long double ld; - int i; -@}; -@end smallexample - -@noindent -@code{union U} is now always passed in memory. - -@end itemize +@option{-Wpsabi} is enabled by default, and is also implied by +@option{-Wabi}. @opindex Wchanges-meaning @opindex Wno-changes-meaning @@ -6975,6 +6978,55 @@ is only active when @option{-fdelete-null-pointer-checks} is active, which is enabled by optimizations in most targets. The precision of the warnings depends on the optimization options used. +@opindex Wno-musttail-local-addr +@opindex -Wmusttail-local-addr +@item -Wno-musttail-local-addr +Do not warn about passing a pointer (or in C++, a reference) to a +local variable or label to argument of a @code{musttail} call. Those +variables go out of scope before the tail call instruction. + +@opindex Wmaybe-musttail-local-addr +@opindex -Wno-maybe-musttail-local-addr +@item -Wmaybe-musttail-local-addr +Warn when address of a local variable can escape to a @code{musttail} +call, unless it goes out of scope already before the @code{musttail} +call. + +@smallexample +int foo (int *); + +int +bar (int *x) +@{ + if (x[0] == 1) + @{ + int a = 42; + foo (&a); + /* Without the @code{musttail} attribute this call would not + be tail called, because address of the @code{a} variable escapes + and the second foo call could dereference it. With the attribute + the local variables are assumed to go out of scope immediately + before the tail call instruction and the compiler warns about + this. */ + [[gnu::musttail]] return foo (nullptr); + @} + else + @{ + @{ + int a = 42; + foo (&a); + @} + /* The @code{a} variable isn't already in scope, so even when it + escaped, even without @code{musttail} attribute it would be + undefined behavior to dereference it and the compiler could + turn this into a tail call. No warning is diagnosed here. */ + [[gnu::musttail]] return foo (nullptr); + @} +@} +@end smallexample + +This warning is enabled by @option{-Wextra}. + @opindex Wnrvo @opindex Wno-nrvo @item -Wnrvo @r{(C++ and Objective-C++ only)} @@ -8919,6 +8971,11 @@ error alone, with @option{-Wno-error=int-conversion}. This warning is upgraded to an error by @option{-pedantic-errors}. +@opindex Wzero-as-null-pointer-constant +@opindex Wno-zero-as-null-pointer-constant +@item -Wzero-as-null-pointer-constant +Warn when a literal @samp{0} is used as null pointer constant. + @opindex Wzero-length-bounds @opindex Wzero-length-bounds @item -Wzero-length-bounds @@ -10060,8 +10117,9 @@ a warning.) @opindex Wno-aggressive-loop-optimizations @opindex Waggressive-loop-optimizations @item -Wno-aggressive-loop-optimizations -Warn if in a loop with constant number of iterations the compiler detects -undefined behavior in some statement during one or more of the iterations. +Do not warn if the compiler detects undefined behavior in a loop with +a constant number of iterations. @option{-Waggressive-loop-optimizations} +is enabled by default. @opindex Wno-attributes @opindex Wattributes @@ -14021,6 +14079,12 @@ in this pass can be limited using @option{max-tail-merge-comparisons} parameter and @option{max-tail-merge-iterations} parameter. +@opindex ftree-cselim +@item -ftree-cselim +Perform conditional store elimination on trees. This flag is enabled by +default at @option{-O1} and higher on targets that have conditional +move instructions. + @opindex ftree-dce @item -ftree-dce Perform dead code elimination (DCE) on trees. This flag is enabled by @@ -15267,32 +15331,24 @@ arithmetic. These options trade off between speed and correctness. All must be specifically enabled. @table @gcctabopt -@opindex ffloat-store -@item -ffloat-store -Do not store floating-point variables in registers, and inhibit other -options that might change whether a floating-point value is taken from a -register or memory. - -@cindex floating-point precision -This option prevents undesirable excess precision on machines such as -the 68000 where the floating registers (of the 68881) keep more -precision than a @code{double} is supposed to have. Similarly for the -x86 architecture. For most programs, the excess precision does only -good, but a few programs rely on the precise definition of IEEE floating -point. Use @option{-ffloat-store} for such programs, after modifying -them to store all pertinent intermediate computations into variables. - @opindex fexcess-precision @item -fexcess-precision=@var{style} -This option allows further control over excess precision on machines +This option allows control over excess precision on machines where floating-point operations occur in a format with more precision or -range than the IEEE standard and interchange floating-point types. By -default, @option{-fexcess-precision=fast} is in effect; this means that +range than the IEEE standard and interchange floating-point types. +An example of such a target is x87 floating point on x86 processors, +which uses an 80-bit representation internally instead of the 64-bit +IEEE format. For most programs, the excess precision is harmless, +but some programs may rely on the +requirements of the C or C++ language standards for handling IEEE values. + +By default, @option{-fexcess-precision=fast} is in effect; this means that operations may be carried out in a wider precision than the types specified in the source if that would result in faster code, and it is unpredictable when rounding to the types specified in the source code takes place. When compiling C or C++, if @option{-fexcess-precision=standard} is specified -then excess precision follows the rules specified in ISO C99 or C++; in particular, +then excess precision follows the rules specified in ISO C99 or C++; +in particular, both casts and assignments cause values to be rounded to their semantic types (whereas @option{-ffloat-store} only affects assignments). This option is enabled by default for C or C++ if a strict @@ -15310,6 +15366,18 @@ or @option{-mfpmath=sse+387} is specified; in the former case, IEEE semantics apply without excess precision, and in the latter, rounding is unpredictable. +@opindex ffloat-store +@item -ffloat-store +Do not store floating-point variables in registers, and inhibit other +options that might change whether a floating-point value is taken from a +register or memory. This option has generally been subsumed by +@option{-fexcess-precision=standard}, which is more general. If you do use +@option{-ffloat-store}, you may need to modify your program to explicitly +store intermediate computations in temporary variables since +@option{-ffloat-store} handles rounding to IEEE format +only on assignments and not casts as @option{-fexcess-precision=standard} +does. + @opindex ffast-math @item -ffast-math Sets the options @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @@ -15444,9 +15512,8 @@ default state for @code{FENV_ACCESS}. @opindex frounding-math @item -frounding-math Disable transformations and optimizations that assume default floating-point -rounding behavior. This is round-to-zero for all floating point -to integer conversions, and round-to-nearest for all other arithmetic -truncations. This option should be specified for programs that change +rounding behavior (round-to-nearest). +This option should be specified for programs that change the FP rounding mode dynamically, or that may be executed with a non-default rounding mode. This option disables constant folding of floating-point expressions at compile time (which may be affected by @@ -16466,6 +16533,15 @@ in combiner for a pseudo register as last known value of that register. @item max-combine-insns The maximum number of instructions the RTL combiner tries to combine. +@item max-combine-search-insns +The maximum number of instructions that the RTL combiner searches in order +to find the next use of a given register definition. If this limit is reached +without finding such a use, the combiner will stop trying to optimize the +definition. + +Currently this limit only applies after certain successful combination +attempts, but it could be extended to other cases in future. + @item integer-share-limit Small integer constants can use a shared data structure, reducing the compiler's memory usage and increasing its speed. This sets the maximum @@ -18321,7 +18397,8 @@ operand constant, @code{__sanitizer_cov_trace_cmpf} or @opindex fcf-protection @item -fcf-protection=@r{[}full@r{|}branch@r{|}return@r{|}none@r{|}check@r{]} -Enable code instrumentation of control-flow transfers to increase +@itemx -fcf-protection +Enable code instrumentation to increase program security by checking that target addresses of control-flow transfer instructions (such as indirect function call, function return, indirect jump) are valid. This prevents diverting the flow of control @@ -18329,22 +18406,30 @@ to an unexpected target. This is intended to protect against such threats as Return-oriented Programming (ROP), and similarly call/jmp-oriented programming (COP/JOP). +The @option{-fcf-protection=} keywords are interpreted as follows. + The value @code{branch} tells the compiler to implement checking of validity of control-flow transfer at the point of indirect branch -instructions, i.e.@: call/jmp instructions. The value @code{return} -implements checking of validity at the point of returning from a -function. The value @code{full} is an alias for specifying both -@code{branch} and @code{return}. The value @code{none} turns off -instrumentation. +instructions, i.e.@: call/jmp instructions. + +The value @code{return} implements checking of validity at the point of +returning from a function. -To override @option{-fcf-protection}, @option{-fcf-protection=none} -needs to be added and then with @option{-fcf-protection=xxx}. +The value @code{full} is an alias for specifying both +@code{branch} and @code{return}. The value @code{check} is used for the final link with link-time optimization (LTO). An error is issued if LTO object files are compiled with different @option{-fcf-protection} values. The value @code{check} is ignored at the compile time. +The value @code{none} turns off instrumentation. + +@option{-fcf-protection} is an alias for @option{-fcf-protection=full}. +To override a previous @option{-fcf-protection} option on the command +line, add @option{-fcf-protection=none} and then +@option{-fcf-protection=@var{kind}}. + The macro @code{__CET__} is defined when @option{-fcf-protection} is used. The first bit of @code{__CET__} is set to 1 for the value @code{branch} and the second bit of @code{__CET__} is set to 1 for @@ -21800,11 +21885,13 @@ performance of the code. Permissible values for this option are: @samp{cortex-x2}, @samp{cortex-x3}, @samp{cortex-x4}, @samp{cortex-a510}, @samp{cortex-a520}, @samp{cortex-a520ae}, @samp{cortex-a710}, @samp{cortex-a715}, @samp{cortex-a720}, @samp{cortex-a720ae}, @samp{ampere1}, @samp{ampere1a}, -@samp{ampere1b}, @samp{cobalt-100} and @samp{native}. +@samp{ampere1b}, @samp{cobalt-100}, @samp{apple-m1}, @samp{apple-m2}, +@samp{apple-m3} and @samp{native}. The values @samp{cortex-a57.cortex-a53}, @samp{cortex-a72.cortex-a53}, @samp{cortex-a73.cortex-a35}, @samp{cortex-a73.cortex-a53}, -@samp{cortex-a75.cortex-a55}, @samp{cortex-a76.cortex-a55} specify that GCC +@samp{cortex-a75.cortex-a55}, @samp{cortex-a76.cortex-a55}, +@samp{apple-m1}, @samp{apple-m2}, @samp{apple-m3} specify that GCC should tune for a big.LITTLE system. The value @samp{neoverse-512tvb} specifies that GCC should tune @@ -22094,7 +22181,8 @@ Enable the Pointer Authentication Extension. @item cssc Enable the Common Short Sequence Compression instructions. @item sme -Enable the Scalable Matrix Extension. +Enable the Scalable Matrix Extension. This is only supported when SVE2 is also +enabled. @item sme-i16i64 Enable the FEAT_SME_I16I64 extension to SME. This also enables SME instructions. @@ -26302,6 +26390,24 @@ CIX, FIX and MAX instruction sets. The default is to use the instruction sets supported by the CPU type specified via @option{-mcpu=} option or that of the CPU on which GCC was built if none is specified. +@opindex msafe-bwa +@opindex mno-safe-bwa +@item -msafe-bwa +@itemx -mno-safe-bwa +Indicate whether in the absence of the optional BWX instruction set +GCC should generate multi-thread and async-signal safe code for byte +and aligned word memory accesses. + +@opindex msafe-partial +@opindex mno-safe-partial +@item -msafe-partial +@itemx -mno-safe-partial +Indicate whether GCC should generate multi-thread and async-signal +safe code for partial memory accesses, including piecemeal accesses +to unaligned data as well as block accesses to leading and trailing +parts of aggregate types or other objects in memory that do not +respectively start and end on an aligned 64-bit data boundary. + @opindex mfloat-vax @opindex mfloat-ieee @item -mfloat-vax @@ -28000,8 +28106,8 @@ Use (do not use) @code{amcas[_db].@{b/h/w/d@}} instructions. When build with @opindex mno-ld-seq-sa @item -mld-seq-sa @itemx -mno-ld-seq-sa -Whether a load-load barrier (@code{dbar 0x700}) is needed. When build with -@option{-march=la664}, it is enabled by default. The default is +Whether a same-address load-load barrier (@code{dbar 0x700}) is needed. When +build with @option{-march=la664}, it is enabled by default. The default is @option{-mno-ld-seq-sa}, the load-load barrier is needed. @opindex mtls-dialect @@ -28009,6 +28115,14 @@ Whether a load-load barrier (@code{dbar 0x700}) is needed. When build with This option controls which tls dialect may be used for general dynamic and local dynamic TLS models. +@table @samp +@item trad +Use traditional TLS. This is the default. + +@item desc +Use TLS descriptors. +@end table + @opindex mannotate-tablejump @opindex mno-annotate-tablejump @item -mannotate-tablejump @@ -28020,14 +28134,6 @@ tools, for example @file{objtool} of the Linux kernel building system, need the annotation to analysis the control flow. The default is @option{-mno-annotate-tablejump}. -@table @samp -@item trad -Use traditional TLS. This is the default. - -@item desc -Use TLS descriptors. -@end table - @item --param loongarch-vect-unroll-limit=@var{n} The vectorizer will use available tuning information to determine whether it would be beneficial to unroll the main vectorized loop and by how much. This @@ -32372,18 +32478,18 @@ and for AIX: @samp{vec-extabi}, @samp{vec-default}@. Change the current ABI to use IBM extended-precision long double. This is not likely to work if your system defaults to using IEEE extended-precision long double. If you change the long double type -from IEEE extended-precision, the compiler will issue a warning unless -you use the @option{-Wno-psabi} option. Requires @option{-mlong-double-128} -to be enabled. +from IEEE extended-precision, the compiler issues a warning unless +you use the @option{-Wno-psabi} option (@pxref{Warning Options}). +Requires @option{-mlong-double-128} to be enabled. @opindex mabi=ieeelongdouble @item -mabi=ieeelongdouble Change the current ABI to use IEEE extended-precision long double. This is not likely to work if your system defaults to using IBM extended-precision long double. If you change the long double type -from IBM extended-precision, the compiler will issue a warning unless -you use the @option{-Wno-psabi} option. Requires @option{-mlong-double-128} -to be enabled. +from IBM extended-precision, the compiler issues a warning unless +you use the @option{-Wno-psabi} option (@pxref{Warning Options}). +Requires @option{-mlong-double-128} to be enabled. @opindex mabi=elfv1 @item -mabi=elfv1 |